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