Documentation/mergetools/vimdiff.txt

   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 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 as follows (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 parentheses 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).