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

名称

git-mergetool - 运行合并冲突解决工具以解决合并冲突

概要

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

描述

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

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

选项

-t <工具>
--tool=<工具>

使用由 <工具> 指定的合并解决程序。有效值包括 emerge、gvimdiff、kdiff3、meld、vimdiff 和 tortoisemerge。运行 git mergetool --tool-help 可获取有效的 <工具> 设置列表。

如果未指定合并解决程序，git mergetool 将使用配置变量 merge.tool。如果未设置配置变量 merge.tool，git mergetool 将选择一个合适的默认值。

你可以通过设置配置变量 mergetool.<工具>.path 明确提供该工具的完整路径。例如，你可以通过设置 mergetool.kdiff3.path 来配置 kdiff3 的绝对路径。否则，git mergetool 会假定该工具在 $PATH 中可用。

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

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

如果自定义合并工具通过其退出代码正确指示了合并解决的成功，则可以将配置变量 mergetool.<工具>.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<顺序文件>

按照 <顺序文件> 中指定的顺序处理文件，该文件每行包含一个 shell 通配符模式。这会覆盖 diff.orderFile 配置变量（参见 git-config[1]）。要取消 diff.orderFile，请使用 -O/dev/null。

配置

本节中以下所有内容均从 git-config[1] 文档中选择性地包含。内容与彼处相同：

mergetool.<工具>.path

覆盖给定工具的路径。如果你的工具不在 $PATH 中，这很有用。

mergetool.<工具>.cmd

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

mergetool.<工具>.hideResolved

允许用户覆盖特定工具的全局 mergetool.hideResolved 值。有关完整说明，请参见 mergetool.hideResolved。

mergetool.<工具>.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，并仅在可用时使用 --auto-merge。值为 false 则完全避免使用 --auto-merge，这是默认值。

mergetool.<变体>.layout

配置 vimdiff 的 <变体> 的拆分窗口布局，变体可以是 vimdiff、nvimdiff、gvimdiff 中的任意一个。当使用 --tool=<变体>（或如果 merge.tool 配置为 <变体> 时不使用 --tool）启动 git mergetool 时，Git 将参考 mergetool.<变体>.layout 来确定工具的布局。如果变体特定的配置不可用，将使用 vimdiff 的配置作为回退。如果该配置也不可用，将使用包含 4 个窗口的默认布局。要配置布局，请参阅“后端特定提示”部分。

mergetool.hideResolved

在合并过程中，Git 会自动解决尽可能多的冲突，并写入包含冲突标记的 $MERGED 文件，围绕 Git 无法解决的任何冲突；$LOCAL 和 $REMOTE 通常是 Git 解决冲突前文件的版本。此标志会导致 $LOCAL 和 $REMOTE 被覆盖，以便仅向合并工具呈现未解决的冲突。可以通过 mergetool.<工具>.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）之间的差异。

    ------------------------------------------
| <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] 套件的一部分