| Description | |
| ^^^^^^^^^^^ | |
| When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4 | |
| windows layout distributed in the following way: | |
| .... | |
| ------------------------------------------ | |
| | | | | | |
| | LOCAL | BASE | REMOTE | | |
| | | | | | |
| ------------------------------------------ | |
| | | | |
| | MERGED | | |
| | | | |
| ------------------------------------------ | |
| .... | |
| `LOCAL`, `BASE` and `REMOTE` are read-only buffers showing the contents of the | |
| conflicting file in specific commits ("commit you are merging into", "common | |
| ancestor commit" and "commit you are merging from" respectively) | |
| `MERGED` is a writable buffer where you have to resolve the conflicts (using the | |
| other read-only buffers as a reference). Once you are done, save and exit Vim as | |
| usual (`:wq`) or, if you want to abort, exit using `:cq`. | |
| Layout configuration | |
| ^^^^^^^^^^^^^^^^^^^^ | |
| You can change the windows layout used by Vim by setting configuration variable | |
| `mergetool.vimdiff.layout` which accepts a string where the following separators | |
| have special meaning: | |
| - `+` is used to "open a new tab" | |
| - `,` is used to "open a new vertical split" | |
| - `/` is used to "open a new horizontal split" | |
| - `@` is used to indicate the file containing the final version after | |
| solving the conflicts. If not present, `MERGED` will be used by default. | |
| The precedence of the operators is as follows (you can use parentheses to change | |
| it): | |
| `@` > `+` > `/` > `,` | |
| Let's see some examples to understand how it works: | |
| * `layout = "(LOCAL,BASE,REMOTE)/MERGED"` | |
| + | |
| -- | |
| This is exactly the same as the default layout we have already seen. | |
| Note that `/` has precedence over `,` and thus the parenthesis are not | |
| needed in this case. The next layout definition is equivalent: | |
| layout = "LOCAL,BASE,REMOTE / MERGED" | |
| -- | |
| * `layout = "LOCAL,MERGED,REMOTE"` | |
| + | |
| -- | |
| If, for some reason, we are not interested in the `BASE` buffer. | |
| .... | |
| ------------------------------------------ | |
| | | | | | |
| | | | | | |
| | LOCAL | MERGED | REMOTE | | |
| | | | | | |
| | | | | | |
| ------------------------------------------ | |
| .... | |
| -- | |
| * `layout = "MERGED"` | |
| + | |
| -- | |
| Only the `MERGED` buffer will be shown. Note, however, that all the other | |
| ones are still loaded in vim, and you can access them with the "buffers" | |
| command. | |
| .... | |
| ------------------------------------------ | |
| | | | |
| | | | |
| | MERGED | | |
| | | | |
| | | | |
| ------------------------------------------ | |
| .... | |
| -- | |
| * `layout = "@LOCAL,REMOTE"` | |
| + | |
| -- | |
| When `MERGED` is not present in the layout, you must "mark" one of the | |
| buffers with an arobase (`@`). That will become the buffer you need to edit and | |
| save after resolving the conflicts. | |
| .... | |
| ------------------------------------------ | |
| | | | | |
| | | | | |
| | | | | |
| | LOCAL | REMOTE | | |
| | | | | |
| | | | | |
| | | | | |
| ------------------------------------------ | |
| .... | |
| -- | |
| * `layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE"` | |
| + | |
| -- | |
| Three tabs will open: the first one is a copy of the default layout, while | |
| the other two only show the differences between (`BASE` and `LOCAL`) and | |
| (`BASE` and `REMOTE`) respectively. | |
| .... | |
| ------------------------------------------ | |
| | <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"` | |
| + | |
| -- | |
| Same as the previous example, but adds a fourth tab with the same | |
| information as the first tab, with a different layout. | |
| .... | |
| --------------------------------------------- | |
| | TAB #1 | TAB #2 | TAB #3 | <TAB #4> | | |
| --------------------------------------------- | |
| | LOCAL | | | |
| |---------------------| | | |
| | BASE | MERGED | | |
| |---------------------| | | |
| | REMOTE | | | |
| --------------------------------------------- | |
| .... | |
| Note how in the third tab definition we need to use parentheses to make `,` | |
| have precedence over `/`. | |
| -- | |
| Variants | |
| ^^^^^^^^ | |
| Instead of `--tool=vimdiff`, you can also use one of these other variants: | |
| * `--tool=gvimdiff`, to open gVim instead of Vim. | |
| * `--tool=nvimdiff`, to open Neovim instead of Vim. | |
| When using these variants, in order to specify a custom layout you will have to | |
| set configuration variables `mergetool.gvimdiff.layout` and | |
| `mergetool.nvimdiff.layout` instead of `mergetool.vimdiff.layout` (though the | |
| latter will be used as fallback if the variant-specific one is not set). | |
| In addition, for backwards compatibility with previous Git versions, you can | |
| also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex: | |
| `vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout. | |
| In other words, using `--tool=[g|n]vimdiff<x>` is the same as using | |
| `--tool=[g|n]vimdiff` and setting configuration variable | |
| `mergetool.[g|n]vimdiff.layout` to... | |
| * `<x>=1`: `"@LOCAL, REMOTE"` | |
| * `<x>=2`: `"LOCAL, MERGED, REMOTE"` | |
| * `<x>=3`: `"MERGED"` | |
| Example: using `--tool=gvimdiff2` will open `gvim` with three columns (`LOCAL`, | |
| `MERGED` and `REMOTE`). |