简体中文 ▾ 主题 ▾ 最新版本 ▾ git-mergetool 最后更新于 2.52.0

名称

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 中可用。

除了运行已知的合并工具程序之一，还可以通过在配置变量 mergetool.<tool>.cmd 中指定要调用的命令行来定制 git mergetool 以运行替代程序。

当使用此工具调用 git mergetool 时（通过 -t 或 --tool 选项或 merge.tool 配置变量），调用的命令行将带有以下设置：BASE 设置为包含合并共同基准（如果可用）的临时文件名；LOCAL 设置为包含当前分支上文件内容的临时文件名；REMOTE 设置为包含要合并的文件内容的临时文件名；MERGED 设置为合并工具应向其写入合并解决结果的文件名。

如果自定义合并工具通过其退出代码正确指示合并解决的成功，则可以将配置变量 mergetool.<tool>.trustExitCode 设置为 true。否则，在自定义工具退出后，git mergetool 将提示用户指示解决是否成功。

--tool-help

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

-y
--no-prompt

在每次调用合并解决程序之前不进行提示。如果使用 --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 通配符模式。这会覆盖 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.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>（或者在配置了 merge.tool 为 <variant> 时不带 --tool）启动 git mergetool 时，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 将打开 Vim，其 4 窗口布局分布如下：

------------------------------------------
|             |           |              |
|   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) 之间的差异。

    ------------------------------------------
| <TAB #1> |  TAB #2  |  TAB #3  |       |
------------------------------------------
|             |           |              |
|   LOCAL     |   BASE    |   REMOTE     |
|             |           |              |
------------------------------------------
|                                        |
|                MERGED                  |
|                                        |
------------------------------------------
    ------------------------------------------
|  TAB #1  | <TAB #2> |  TAB #3  |       |
------------------------------------------
|                   |                    |
|                   |                    |
|                   |                    |
|     BASE          |    LOCAL           |
|                   |                    |
|                   |                    |
|                   |                    |
------------------------------------------
    ------------------------------------------
|  TAB #1  |  TAB #2  | <TAB #3> |       |
------------------------------------------
|                   |                    |
|                   |                    |
|                   |                    |
|     BASE          |    REMOTE          |
|                   |                    |
|                   |                    |
|                   |                    |
------------------------------------------

  • layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE + (LOCAL/BASE/REMOTE),MERGED"

    与前面的示例相同，但添加了第四个标签页，其中包含与第一个标签页相同的信息，但布局不同。

    ---------------------------------------------
|  TAB #1  |  TAB #2  |  TAB #3  | <TAB #4> |
---------------------------------------------
|       LOCAL         |                     |
|---------------------|                     |
|       BASE          |        MERGED       |
|---------------------|                     |
|       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] 套件的一部分