git-mergetool

运行合并冲突解决工具来解决合并冲突。

概要

git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...]

描述

使用 git mergetool 运行多个合并实用程序之一来解决合并冲突。通常在 git merge 之后运行。

如果给定了一个或多个 <file> 参数，将运行合并工具程序来解决每个文件中的差异（跳过没有冲突的文件）。指定目录将包含该路径中的所有未解决文件。如果未指定 <file> 名称，git mergetool 将对每个有合并冲突的文件运行合并工具程序。

选项

-t <tool>, --tool=<tool>

使用 <tool> 指定的合并解决程序。有效值包括 emerge、gvimdiff、kdiff3、meld、vimdiff 和 tortoisemerge。运行 git mergetool --tool-help 可查看有效的 <tool> 设置列表。 如果未指定合并解决程序，git mergetool 将使用配置变量 merge.tool。如果配置变量 merge.tool 未设置，git mergetool 将选择一个合适的默认值。 您可以通过设置配置变量 mergetool.<tool>.path 来显式提供工具的完整路径。例如，您可以通过设置 mergetool.kdiff3.path 来配置 kdiff3 的绝对路径。否则，git mergetool 假定工具在 $PATH 中可用。 除了运行已知的合并工具程序外，git mergetool 可以通过在配置变量 mergetool.<tool>.cmd 中指定要调用的命令行来自定义运行替代程序。 当使用此工具调用 git mergetool 时（通过 -t 或 --tool 选项或 merge.tool 配置变量），配置的命令行将被调用，并设置 BASE 为包含合并公共基础的临时文件名（如果可用）；LOCAL 为包含当前分支上文件内容的临时文件名；REMOTE 为包含要合并的文件内容的临时文件名；MERGED 为合并工具应将合并解决结果写入的文件名。 如果自定义合并工具通过其退出代码正确指示合并解决成功，则配置变量 mergetool.<tool>.trustExitCode 可以设置为 true。否则，git mergetool 将在自定义工具退出后提示用户指示解决是否成功。

--tool-help

：打印可与 --tool 一起使用的合并工具列表。

-y, --no-prompt, --tool

在每次调用合并解决程序之前不提示。如果通过 --tool 选项或 merge.tool 配置变量显式指定合并解决程序，则这是默认行为。

--prompt

：在每次调用合并解决程序之前提示，给用户跳过该路径的机会。

-g, --gui

当使用 -g 或 --gui 选项调用 git-mergetool 时，默认合并工具将从配置的 merge.guitool 变量读取，而不是从 merge.tool 读取。如果 merge.guitool 未设置，将回退到 merge.tool 下配置的工具。这可以使用配置变量 mergetool.guiDefault 自动选择。

--no-gui

：覆盖之前的 -g 或 --gui 设置或 mergetool.guiDefault 配置，从配置的 merge.tool 变量读取默认合并工具。

-O<orderfile>

：按 <orderfile> 中指定的顺序处理文件，该文件每行有一个 shell glob 模式。这会覆盖 diff.orderFile 配置变量（参见 git-config(1)）。要取消 diff.orderFile，使用 -O/dev/null。

配置

以下内容选自 git-config(1) 文档：

mergetool.<tool>.path

：覆盖给定工具的路径。当您的工具不在 $PATH 中时很有用。

mergetool.<tool>.cmd

：指定调用指定合并工具的命令。指定的命令在 shell 中求值，以下变量可用：BASE 是包含要合并文件的公共基础的临时文件名（如果可用）；LOCAL 是包含当前分支上文件内容的临时文件名；REMOTE 是包含要合并分支上文件内容的临时文件名；MERGED 包含合并工具应将成功合并结果写入的文件名。

mergetool.<tool>.hideResolved

：允许用户为特定工具覆盖全局 mergetool.hideResolved 值。

mergetool.<tool>.trustExitCode

：对于自定义合并命令，指定合并命令的退出代码是否可用于确定合并是否成功。如果未设置为 true，则检查合并目标文件的时间戳，如果文件已更新则假定合并成功；否则提示用户指示合并是否成功。

mergetool.meld.hasOutput

：旧版本的 meld 不支持 --output 选项。Git 将尝试通过检查 meld --help 的输出来检测 meld 是否支持 --output。配置 mergetool.meld.hasOutput 将使 Git 跳过这些检查并使用配置的值。将 mergetool.meld.hasOutput 设置为 true 告诉 Git 无条件使用 --output 选项，false 则避免使用 --output。

mergetool.meld.useAutoMerge

：当给出 --auto-merge 时，meld 将自动合并非冲突部分，高亮冲突部分，并等待用户决定。将 mergetool.meld.useAutoMerge 设置为 true 告诉 Git 无条件对 meld 使用 --auto-merge 选项。将此值设置为 auto 使 git 检测是否支持 --auto-merge 并仅在可用时使用。值为 false 则完全避免使用 --auto-merge，这是默认值。

mergetool.<variant>.layout

：配置 vimdiff 的 <variant> 的分割窗口布局，可以是 vimdiff、nvimdiff、gvimdiff 中的任何一个。当使用 --tool=<variant> 启动 git mergetool 时（或在未指定 --tool 且 merge.tool 配置为 <variant> 时），Git 将查阅 mergetool.<variant>.layout 来确定工具的布局。如果特定变体的配置不可用，则使用 vimdiff 的配置作为回退。如果也不可用，则使用具有 4 个窗口的默认布局。

mergetool.hideResolved

：在合并期间，Git 将自动解决尽可能多的冲突并写入 $MERGED 文件，在其无法解决的冲突周围包含冲突标记；$LOCAL 和 $REMOTE 通常是 Git 冲突解决之前的文件版本。此标志导致 $LOCAL 和 $REMOTE 被覆盖，以便仅将未解决的冲突呈现给合并工具。可以通过 mergetool.<tool>.hideResolved 配置变量按工具配置。默认为 false。

mergetool.keepBackup

：执行合并后，带有冲突标记的原始文件可以保存为 .orig 扩展名的文件。如果此变量设置为 false，则不保留此文件。默认为 true（即保留备份文件）。

mergetool.keepTemporaries

：调用自定义合并工具时，Git 使用一组临时文件传递给工具。如果工具返回错误且此变量设置为 true，则这些临时文件将被保留；否则在工具退出后将被移除。默认为 false。

mergetool.writeToTemp

：Git 默认在工作树中写入冲突文件的临时 BASE、LOCAL 和 REMOTE 版本。当设置为 true 时，Git 将尝试使用临时目录存放这些文件。默认为 false。

mergetool.prompt

：在每次调用合并解决程序之前提示。

mergetool.guiDefault

：设置为 true 以默认使用 merge.guitool（等同于指定 --gui 参数），或设置为 auto 根据 DISPLAY 环境变量值的存在选择 merge.guitool 或 merge.tool。默认为 false，此时必须显式提供 --gui 参数才能使用 merge.guitool。

临时文件

git mergetool 在解决合并时创建 *.orig 备份文件。一旦文件已合并且其 git mergetool 会话完成，可以安全删除这些文件。

将 mergetool.keepBackup 配置变量设置为 false 会使 git mergetool 在文件成功合并时自动移除备份文件。

后端特定提示

vimdiff

描述

当在 git mergetool 中指定 --tool=vimdiff 时，Git 将以如下方式打开具有 4 个窗口布局的 Vim：

|             |           |              |
|   LOCAL     |   BASE    |   REMOTE     |
|             |           |              |
|                                        |
|                MERGED                  |
|                                        |

LOCAL、BASE 和 REMOTE 是只读缓冲区，显示特定提交中冲突文件的内容（分别是"您要合并到的提交"、"公共祖先提交"和"您要合并的提交"）。

MERGED 是一个可写缓冲区，您需要在其中解决冲突（使用其他只读缓冲区作为参考）。完成后，像往常一样保存并退出 Vim（:wq），或者如果要中止，使用 :cq 退出。

布局配置

您可以通过设置配置变量 mergetool.vimdiff.layout 来更改 Vim 使用的窗口布局，该变量接受一个字符串，其中以下分隔符具有特殊含义：

• + 用于"打开新标签页"
• , 用于"打开新的垂直分割"
• / 用于"打开新的水平分割"
• @ 用于指示包含解决冲突后最终版本的文件。如果不存在，将默认使用 MERGED。

运算符的优先级如下（可以使用括号来更改）：

`@` > `+` > `/` > `,`

让我们看一些示例来理解它的工作方式：

• layout = "(LOCAL,BASE,REMOTE)/MERGED" 这与我们已经看到的默认布局完全相同。 注意 / 的优先级高于 ,，因此在这种情况下不需要括号。下一个布局定义是等效的：

  layout = "LOCAL,BASE,REMOTE / MERGED"

• layout = "LOCAL,MERGED,REMOTE" 如果出于某种原因，我们对 BASE 缓冲区不感兴趣。

|             |           |              |
|             |           |              |
|   LOCAL     |   MERGED  |   REMOTE     |
|             |           |              |
|             |           |              |

• layout = "MERGED" 只显示 MERGED 缓冲区。但是请注意，所有其他缓冲区仍然加载在 vim 中，您可以使用 "buffers" 命令访问它们。

|                                        |
|                                        |
|                 MERGED                 |
|                                        |
|                                        |

• layout = "@LOCAL,REMOTE" 当 MERGED 不在布局中时，您必须用 @ 符号 "标记" 一个缓冲区。这将成为解决冲突后需要编辑和保存的缓冲区。

|                   |                    |
|                   |                    |
|                   |                    |
|     LOCAL         |    REMOTE          |
|                   |                    |
|                   |                    |
|                   |                    |

• layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE" 将打开三个标签页：第一个是默认布局的副本，而其他两个分别只显示（BASE 和 LOCAL）以及（BASE 和 REMOTE）之间的差异。

变体

除了 --tool=vimdiff，您还可以使用以下其他变体之一：

• --tool=gvimdiff，打开 gVim 而不是 Vim。
• --tool=nvimdiff，打开 Neovim 而不是 Vim。

使用这些变体时，要指定自定义布局，您需要设置配置变量 mergetool.gvimdiff.layout 和 mergetool.nvimdiff.layout，而不是 mergetool.vimdiff.layout（尽管后者将用作回退）。

此外，为了与以前的 Git 版本向后兼容，您还可以在 vimdiff 或任何变体后附加 1、2 或 3（例如：vimdiff3、nvimdiff1 等）以使用预定义布局。

换句话说，使用 --tool=[g|n]vimdiff<x> 等同于使用 --tool=[g|n]vimdiff 并将配置变量 mergetool.[g|n]vimdiff.layout 设置为...

• <x>=1: "@LOCAL, REMOTE"
• <x>=2: "LOCAL, MERGED, REMOTE"
• <x>=3: "MERGED"

示例：使用 --tool=gvimdiff2 将打开具有三列（LOCAL、MERGED 和 REMOTE）的 gvim。

Git

git(1) 套件的一部分