]>
Commit | Line | Data |
---|---|---|
7b5cf8be FR |
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" | |
cf6cac20 | 35 | - `@` is used to indicate the file containing the final version after |
7b5cf8be FR |
36 | solving the conflicts. If not present, `MERGED` will be used by default. |
37 | ||
cf6cac20 | 38 | The precedence of the operators is as follows (you can use parentheses to change |
7b5cf8be FR |
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 | .... | |
6cc668c0 | 165 | Note how in the third tab definition we need to use parentheses to make `,` |
7b5cf8be FR |
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). |