Skip to content

Commit 5d1c819

Browse files
gitstergitster
committed
Merge branch 'fr/vimdiff-layout' into next
Reimplement "vimdiff[123]" mergetool drivers with a more generic layout mechanism. * fr/vimdiff-layout: mergetools: add description to all diff/merge tools vimdiff: add tool documentation vimdiff: integrate layout tests in the unit tests framework ('t' folder) vimdiff: new implementation with layout support
2 parents 251b149 + 980145f commit 5d1c819

27 files changed

+978
-32
lines changed

‎Documentation/Makefile‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -302,12 +302,12 @@ $(mergetools_txt): mergetools-list.made
302302

303303
mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
304304
$(QUIET_GEN) \
305-
$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \
305+
$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=diff && \
306306
. ../git-mergetool--lib.sh && \
307-
show_tool_names can_diff "* " || :' >mergetools-diff.txt && \
308-
$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \
307+
show_tool_names can_diff' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-diff.txt && \
308+
$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=merge && \
309309
. ../git-mergetool--lib.sh && \
310-
show_tool_names can_merge "* " || :' >mergetools-merge.txt && \
310+
show_tool_names can_merge' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-merge.txt && \
311311
date >$@
312312

313313
TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))

‎Documentation/config/mergetool.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,15 @@ mergetool.meld.useAutoMerge::
4545
value of `false` avoids using `--auto-merge` altogether, and is the
4646
default value.
4747

48+
mergetool.vimdiff.layout::
49+
The vimdiff backend uses this variable to control how its split
50+
windows look like. Applies even if you are using Neovim (`nvim`) or
51+
gVim (`gvim`) as the merge tool. See BACKEND SPECIFIC HINTS section
52+
ifndef::git-mergetool[]
53+
in linkgit:git-mergetool[1].
54+
endif::[]
55+
for details.
56+
4857
mergetool.hideResolved::
4958
During a merge Git will automatically resolve as many conflicts as
5059
possible and write the 'MERGED' file containing conflict markers around

‎Documentation/git-mergetool.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@ success of the resolution after the custom tool has exited.
101101

102102
CONFIGURATION
103103
-------------
104+
:git-mergetool: 1
104105
include::config/mergetool.txt[]
105106

106107
TEMPORARY FILES
@@ -113,6 +114,13 @@ Setting the `mergetool.keepBackup` configuration variable to `false`
113114
causes `git mergetool` to automatically remove the backup as files
114115
are successfully merged.
115116

117+
BACKEND SPECIFIC HINTS
118+
----------------------
119+
120+
vimdiff
121+
~~~~~~~
122+
include::mergetools/vimdiff.txt[]
123+
116124
GIT
117125
---
118126
Part of the linkgit:git[1] suite

‎Documentation/mergetools/vimdiff.txt‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
Description
2+
^^^^^^^^^^^
3+
4+
When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4
5+
windows layout distributed in the following way:
6+
....
7+
------------------------------------------
8+
| | | |
9+
| LOCAL | BASE | REMOTE |
10+
| | | |
11+
------------------------------------------
12+
| |
13+
| MERGED |
14+
| |
15+
------------------------------------------
16+
....
17+
`LOCAL`, `BASE` and `REMOTE` are read-only buffers showing the contents of the
18+
conflicting file in specific commits ("commit you are merging into", "common
19+
ancestor commit" and "commit you are merging from" respectively)
20+
21+
`MERGED` is a writable buffer where you have to resolve the conflicts (using the
22+
other read-only buffers as a reference). Once you are done, save and exit Vim as
23+
usual (`:wq`) or, if you want to abort, exit using `:cq`.
24+
25+
Layout configuration
26+
^^^^^^^^^^^^^^^^^^^^
27+
28+
You can change the windows layout used by Vim by setting configuration variable
29+
`mergetool.vimdiff.layout` which accepts a string where the following separators
30+
have special meaning:
31+
32+
- `+` is used to "open a new tab"
33+
- `,` is used to "open a new vertical split"
34+
- `/` is used to "open a new horizontal split"
35+
- `@` is used to indicate which is the file containing the final version after
36+
solving the conflicts. If not present, `MERGED` will be used by default.
37+
38+
The precedence of the operators is this one (you can use parentheses to change
39+
it):
40+
41+
`@` > `+` > `/` > `,`
42+
43+
Let's see some examples to understand how it works:
44+
45+
* `layout = "(LOCAL,BASE,REMOTE)/MERGED"`
46+
+
47+
--
48+
This is exactly the same as the default layout we have already seen.
49+
50+
Note that `/` has precedence over `,` and thus the parenthesis are not
51+
needed in this case. The next layout definition is equivalent:
52+
53+
layout = "LOCAL,BASE,REMOTE / MERGED"
54+
--
55+
* `layout = "LOCAL,MERGED,REMOTE"`
56+
+
57+
--
58+
If, for some reason, we are not interested in the `BASE` buffer.
59+
....
60+
------------------------------------------
61+
| | | |
62+
| | | |
63+
| LOCAL | MERGED | REMOTE |
64+
| | | |
65+
| | | |
66+
------------------------------------------
67+
....
68+
--
69+
* `layout = "MERGED"`
70+
+
71+
--
72+
Only the `MERGED` buffer will be shown. Note, however, that all the other
73+
ones are still loaded in vim, and you can access them with the "buffers"
74+
command.
75+
....
76+
------------------------------------------
77+
| |
78+
| |
79+
| MERGED |
80+
| |
81+
| |
82+
------------------------------------------
83+
....
84+
--
85+
* `layout = "@LOCAL,REMOTE"`
86+
+
87+
--
88+
When `MERGED` is not present in the layout, you must "mark" one of the
89+
buffers with an asterisk. That will become the buffer you need to edit and
90+
save after resolving the conflicts.
91+
....
92+
------------------------------------------
93+
| | |
94+
| | |
95+
| | |
96+
| LOCAL | REMOTE |
97+
| | |
98+
| | |
99+
| | |
100+
------------------------------------------
101+
....
102+
--
103+
* `layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE"`
104+
+
105+
--
106+
Three tabs will open: the first one is a copy of the default layout, while
107+
the other two only show the differences between (`BASE` and `LOCAL`) and
108+
(`BASE` and `REMOTE`) respectively.
109+
....
110+
------------------------------------------
111+
| <TAB #1> | TAB #2 | TAB #3 | |
112+
------------------------------------------
113+
| | | |
114+
| LOCAL | BASE | REMOTE |
115+
| | | |
116+
------------------------------------------
117+
| |
118+
| MERGED |
119+
| |
120+
------------------------------------------
121+
....
122+
....
123+
------------------------------------------
124+
| TAB #1 | <TAB #2> | TAB #3 | |
125+
------------------------------------------
126+
| | |
127+
| | |
128+
| | |
129+
| BASE | LOCAL |
130+
| | |
131+
| | |
132+
| | |
133+
------------------------------------------
134+
....
135+
....
136+
------------------------------------------
137+
| TAB #1 | TAB #2 | <TAB #3> | |
138+
------------------------------------------
139+
| | |
140+
| | |
141+
| | |
142+
| BASE | REMOTE |
143+
| | |
144+
| | |
145+
| | |
146+
------------------------------------------
147+
....
148+
--
149+
* `layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE + (LOCAL/BASE/REMOTE),MERGED"`
150+
+
151+
--
152+
Same as the previous example, but adds a fourth tab with the same
153+
information as the first tab, with a different layout.
154+
....
155+
---------------------------------------------
156+
| TAB #1 | TAB #2 | TAB #3 | <TAB #4> |
157+
---------------------------------------------
158+
| LOCAL | |
159+
|---------------------| |
160+
| BASE | MERGED |
161+
|---------------------| |
162+
| REMOTE | |
163+
---------------------------------------------
164+
....
165+
Note how in the third tab definition we need to use parenthesis to make `,`
166+
have precedence over `/`.
167+
--
168+
169+
Variants
170+
^^^^^^^^
171+
172+
Instead of `--tool=vimdiff`, you can also use one of these other variants:
173+
174+
* `--tool=gvimdiff`, to open gVim instead of Vim.
175+
176+
* `--tool=nvimdiff`, to open Neovim instead of Vim.
177+
178+
When using these variants, in order to specify a custom layout you will have to
179+
set configuration variables `mergetool.gvimdiff.layout` and
180+
`mergetool.nvimdiff.layout` instead of `mergetool.vimdiff.layout`
181+
182+
In addition, for backwards compatibility with previous Git versions, you can
183+
also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex:
184+
`vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout.
185+
In other words, using `--tool=[g,n,]vimdiffx` is the same as using
186+
`--tool=[g,n,]vimdiff` and setting configuration variable
187+
`mergetool.[g,n,]vimdiff.layout` to...
188+
189+
* `x=1`: `"@LOCAL, REMOTE"`
190+
* `x=2`: `"LOCAL, MERGED, REMOTE"`
191+
* `x=3`: `"MERGED"`
192+
193+
Example: using `--tool=gvimdiff2` will open `gvim` with three columns (LOCAL,
194+
MERGED and REMOTE).

‎git-mergetool--lib.sh‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ $(list_tool_variants)"
6363
preamble=
6464
fi
6565
shown_any=yes
66-
printf "%s%s\n" "$per_line_prefix" "$toolname"
66+
printf "%s%-15s %s\n" "$per_line_prefix" "$toolname" $(diff_mode && diff_cmd_help "$toolname" || merge_cmd_help "$toolname")
6767
fi
6868
done
6969

@@ -162,10 +162,18 @@ setup_tool () {
162162
return 1
163163
}
164164

165+
diff_cmd_help () {
166+
return 0
167+
}
168+
165169
merge_cmd () {
166170
return 1
167171
}
168172

173+
merge_cmd_help () {
174+
return 0
175+
}
176+
169177
hide_resolved_enabled () {
170178
return 0
171179
}

‎mergetools/araxis‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ diff_cmd () {
22
"$merge_tool_path" -wait -2 "$LOCAL" "$REMOTE" >/dev/null 2>&1
33
}
44

5+
diff_cmd_help () {
6+
echo "Use Araxis Merge (requires a graphical session)"
7+
}
8+
59
merge_cmd () {
610
if $base_present
711
then
@@ -13,6 +17,10 @@ merge_cmd () {
1317
fi
1418
}
1519

20+
merge_cmd_help () {
21+
echo "Use Araxis Merge (requires a graphical session)"
22+
}
23+
1624
translate_merge_tool_path() {
1725
echo compare
1826
}

‎mergetools/bc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ diff_cmd () {
22
"$merge_tool_path" "$LOCAL" "$REMOTE"
33
}
44

5+
diff_cmd_help () {
6+
echo "Use Beyond Compare (requires a graphical session)"
7+
}
8+
59
merge_cmd () {
610
if $base_present
711
then
@@ -13,6 +17,10 @@ merge_cmd () {
1317
fi
1418
}
1519

20+
merge_cmd_help () {
21+
echo "Use Beyond Compare (requires a graphical session)"
22+
}
23+
1624
translate_merge_tool_path() {
1725
if type bcomp >/dev/null 2>/dev/null
1826
then

‎mergetools/codecompare‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ diff_cmd () {
22
"$merge_tool_path" "$LOCAL" "$REMOTE"
33
}
44

5+
diff_cmd_help () {
6+
echo "Use Code Compare (requires a graphical session)"
7+
}
8+
59
merge_cmd () {
610
if $base_present
711
then
@@ -13,6 +17,10 @@ merge_cmd () {
1317
fi
1418
}
1519

20+
merge_cmd_help () {
21+
echo "Use Code Compare (requires a graphical session)"
22+
}
23+
1624
translate_merge_tool_path() {
1725
if merge_mode
1826
then

‎mergetools/deltawalker‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ diff_cmd () {
22
"$merge_tool_path" "$LOCAL" "$REMOTE" >/dev/null 2>&1
33
}
44

5+
diff_cmd_help () {
6+
echo "Use DeltaWalker (requires a graphical session)"
7+
}
8+
59
merge_cmd () {
610
# Adding $(pwd)/ in front of $MERGED should not be necessary.
711
# However without it, DeltaWalker (at least v1.9.8 on Windows)
@@ -16,6 +20,10 @@ merge_cmd () {
1620
fi >/dev/null 2>&1
1721
}
1822

23+
merge_cmd_help () {
24+
echo "Use DeltaWalker (requires a graphical session)"
25+
}
26+
1927
translate_merge_tool_path () {
2028
echo DeltaWalker
2129
}

‎mergetools/diffmerge‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ diff_cmd () {
22
"$merge_tool_path" "$LOCAL" "$REMOTE" >/dev/null 2>&1
33
}
44

5+
diff_cmd_help () {
6+
echo "Use DiffMerge (requires a graphical session)"
7+
}
8+
59
merge_cmd () {
610
if $base_present
711
then
@@ -13,6 +17,10 @@ merge_cmd () {
1317
fi
1418
}
1519

20+
merge_cmd_help () {
21+
echo "Use DiffMerge (requires a graphical session)"
22+
}
23+
1624
exit_code_trustable () {
1725
true
1826
}

0 commit comments

Comments
 (0)