Commit Graph

10 Commits

Author SHA1 Message Date
Fernando Ramos 7b5cf8be18 vimdiff: add tool documentation
Running 'git {merge,diff}tool --tool-help' now also prints usage
information about the vimdiff tool (and its variants) instead of just
its name.

Two new functions ('diff_cmd_help()' and 'merge_cmd_help()') have been
added to the set of functions that each merge tool (ie. scripts found
inside "mergetools/") can overwrite to provided tool specific

Right now, only 'mergetools/vimdiff' implements these functions, but
other tools are encouraged to do so in the future, specially if they
take configuration options not explained anywhere else (as it is the
case with the 'vimdiff' tool and the new 'layout' option)

Note that the function 'show_tool_names', used in the implementation of
'git mergetool --tool-help', is also used in Documentation/Makefile to
generate the list of allowed values for the configuration variables
'{diff,merge}.{gui,}tool'. Adjust the rule so its output is an Asciidoc
"description list" instead of a plain list, with the tool name as the
item and the newly added tool description as the description.

In addition, a section has been added to
"Documentation/git-mergetool.txt" to explain the new "layout"
configuration option with examples.

Helped-by: Philippe Blain <>
Signed-off-by: Fernando Ramos <>
Signed-off-by: Junio C Hamano <>
2022-04-03 15:09:52 -07:00
Fernando Ramos 0041797449 vimdiff: new implementation with layout support
When running 'git mergetool -t vimdiff', a new configuration option
('mergetool.vimdiff.layout') can now be used to select how the user
wants the different windows, tabs and buffers to be displayed.

If the option is not provided, the layout will be the same one that was
being used before this commit (ie. two rows with LOCAL, BASE and COMMIT
in the top one and MERGED in the bottom one).

The 'vimdiff' variants ('vimdiff{1,2,3}') still work but, because they
represented nothing else than different layouts, are now internally
implemented as a subcase of 'vimdiff' with the corresponding
pre-configured 'layout'.

Again, if you don't set "mergetool.vimdiff.layout" everything will work
the same as before *but* the arguments used to call {n,g,}vim will be
others (even if you don't/shouldn't notice it):

  - git mergetool -t vimdiff

    > Before this commit:
      {n,g,}vim -f -d -c '4wincmd w | wincmd J' $LOCAL $BASE $REMOTE $MERGED

    > After this commit:
      {n,g,}vim -f -c "echo | split | vertical split | 1b | wincmd l | vertical split | 2b | wincmd l | 3b | wincmd j | 4b | tabdo windo diffthis" -c "tabfirst" $LOCAL $BASE $REMOTE $MERGED

  - git mergetool -t vimdiff1

    > Before this commit:
      {n,g,}vim -f -d -c 'echon "..."' $LOCAL $REMOTE

    > After this commit:
      {n,g,}vim -f -c "echo | vertical split | 1b | wincmd l | 3b | tabdo windo diffthis" -c "tabfirst" $LOCAL $BASE $REMOTE $MERGED

  - git mergetool -t vimdiff2

    > Before this commit:
      {n,g,}vim -f -d -c 'wincmd l' $LOCAL $MERGED $REMOTE

    > After this commit:
      {n,g,}vim -f -c "echo | vertical split | 1b | wincmd l | vertical split | 4b | wincmd l | 3b | tabdo windo diffthis" -c "tabfirst" $LOCAL $BASE $REMOTE $MERGED

  - git mergetool -t vimdiff3

    > Before this commit:
      {n,g,}vim -f -d -c 'hid | hid | hid' $LOCAL $REMOTE $BASE $MERGED

    > After this commit:
      {n,g,}vim -f -c "echo | 4b | bufdo diffthis" -c "tabfirst" $LOCAL $BASE $REMOTE $MERGED

Despite being different, I have manually verified that they generate the same
layout as before.

Signed-off-by: Fernando Ramos <>
Signed-off-by: Junio C Hamano <>
2022-03-30 13:15:42 -07:00
Seth House 30bb8088af mergetools/vimdiff: add vimdiff1 merge tool variant
This adds yet another vimdiff/gvimdiff variant and presents conflicts as
a two-way diff between 'LOCAL' and 'REMOTE'. 'MERGED' is not opened
which deviates from the norm so usage text is echoed as a Vim message on
startup that instructs the user with how to proceed and how to abort.

Vimdiff is well-suited to two-way diffs so this is an option for a more
simple, more streamlined conflict resolution. For example: it is
difficult to communicate differences across more than two files using
only syntax highlighting; default vimdiff commands to get and put
changes between buffers do not need the user to manually specify
a source or destination buffer when only using two buffers.

Like other merge tools that directly compare 'LOCAL' with 'REMOTE', this
tool will benefit when paired with the new `mergetool.hideResolved`

Signed-off-by: Seth House <>
Tested-by: David Aguilar <>
Signed-off-by: Junio C Hamano <>
2021-02-23 11:37:13 -08:00
pudinha 11868978c7 mergetools: add support for nvimdiff (neovim) family
Signed-off-by: pudinha <>
Signed-off-by: Junio C Hamano <>
2020-07-29 14:44:49 -07:00
pudinha 83bbf9b92e mergetool--lib: improve support for vimdiff-style tool variants
The merge tools vimdiff2, vimdiff3, gvimdiff2, gvimdiff3 and bc3 are all
variants of the main tools vimdiff and bc. They are implemented in the
main and a one-liner script that just sources it exist for each.

Allow variants ending in [0-9] to be correctly wired without the need
for such one-liners, so instead of 5 scripts, only 1 (gvimdiff) is

Signed-off-by: pudinha <>
Signed-off-by: Junio C Hamano <>
2020-07-29 14:44:46 -07:00
David Aguilar 2967284456 mergetools/vimdiff: trust Vim's exit code
Allow vimdiff users to signal that they do not want to use the
result of a merge by exiting with ":cquit", which tells Vim to
exit with an error code.

This is better than the current behavior because it allows users
to directly flag that the merge is bad, using a standard Vim
feature, rather than relying on a timestamp heuristic that is
unforgiving to users that save in-progress merge files.

The original behavior can be restored by configuring
mergetool.vimdiff.trustExitCode to false.

Reported-by: Dun Peal <>
Signed-off-by: David Aguilar <>
Signed-off-by: Junio C Hamano <>
2016-11-29 10:57:41 -08:00
David Aguilar 7c10605d2c mergetool: honor mergetool.$tool.trustExitCode for built-in tools
Built-in merge tools contain a hard-coded assumption about
whether or not a tool's exit code can be trusted to determine
the success or failure of a merge.  Tools whose exit codes are
not trusted contain calls to check_unchanged() in their
merge_cmd() functions.

A problem with this is that the trustExitCode configuration is
not honored for built-in tools.

Teach built-in tools to honor the trustExitCode configuration.
Extend run_merge_cmd() so that it is responsible for calling
check_unchanged() when a tool's exit code cannot be trusted.
Remove check_unchanged() calls from scriptlets since they are no
longer responsible for calling it.

When no configuration is present, exit_code_trustable() is
checked to see whether the exit code should be trusted.
The default implementation returns false.

Tools whose exit codes can be trusted override
exit_code_trustable() to true.

Reported-by: Dun Peal <>
Signed-off-by: David Aguilar <>
Signed-off-by: Junio C Hamano <>
2016-11-29 10:54:03 -08:00
Dickson Wong 2300328cb2 mergetool: reorder vim/gvim buffers in three-way diffs
When invoking default (g)vimdiff three-way merge, the merged file is
loaded as the first buffer but moved to the bottom as the fourth window.
This causes a disconnect between vim commands that operate on window
positions (e.g. CTRL-W_w) and those that operate on buffer index (e.g.

This change reorders the buffers to have the same index as windows while
keeping the cursor default to the merged result as the bottom window.

Signed-off-by: Dickson Wong <>
Tested-by: Michael J Gruber <>
Acked-by: David Aguilar <>
Signed-off-by: Junio C Hamano <>
2016-02-12 10:14:09 -08:00
Felipe Contreras 7c147b77d3 mergetools: add vimdiff3 mode
It's similar to the default, except that the other windows are hidden.
This ensures that removed/added colors are still visible on the main
merge window, but the other windows not visible.

Specially useful with merge.conflictstyle=diff3.

Signed-off-by: Felipe Contreras <>
Acked-by: David Aguilar <>
Signed-off-by: Junio C Hamano <>
2014-04-22 12:49:07 -07:00
David Aguilar 073678b8e6 mergetools: simplify how we handle "vim" and "defaults"
Remove the exceptions for "vim" and "defaults" in the mergetool library
so that every filename in mergetools/ matches 1:1 with the name of a
valid built-in tool.

Define the trivial fallback definition of shell functions in-line in
git-mergetool-lib script, instead of dot-sourcing them from another
file.  The result is much easier to follow.

[jc: squashed in an update from John Keeping as well]

Signed-off-by: David Aguilar <>
Signed-off-by: Junio C Hamano <>
2013-01-28 19:00:38 -08:00