1*diff.txt* For Vim version 8.1. Last change: 2019 Jun 02 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 *diff* *vimdiff* *gvimdiff* *diff-mode* 8This file describes the |+diff| feature: Showing differences between two to 9eight versions of the same file. 10 11The basics are explained in section |08.7| of the user manual. 12 131. Starting diff mode |start-vimdiff| 142. Viewing diffs |view-diffs| 153. Jumping to diffs |jumpto-diffs| 164. Copying diffs |copy-diffs| 175. Diff options |diff-options| 18 19============================================================================== 201. Starting diff mode *start-vimdiff* 21 22The easiest way to start editing in diff mode is with the "vimdiff" command. 23This starts Vim as usual, and additionally sets up for viewing the differences 24between the arguments. > 25 26 vimdiff file1 file2 [file3 [file4]] 27 28This is equivalent to: > 29 30 vim -d file1 file2 [file3 [file4]] 31 32You may also use "gvimdiff" or "vim -d -g". The GUI is started then. 33You may also use "viewdiff" or "gviewdiff". Vim starts in readonly mode then. 34"r" may be prepended for restricted mode (see |-Z|). 35 36The second and following arguments may also be a directory name. Vim will 37then append the file name of the first argument to the directory name to find 38the file. 39 40By default an internal diff library will be used. When 'diffopt' or 41'diffexpr' has been set an external "diff" command will be used. This only 42works when such a diff program is available. 43 44Diffs are local to the current tab page |tab-page|. You can't see diffs with 45a window in another tab page. This does make it possible to have several 46diffs at the same time, each in their own tab page. 47 48What happens is that Vim opens a window for each of the files. This is like 49using the |-O| argument. This uses vertical splits. If you prefer horizontal 50splits add the |-o| argument: > 51 52 vimdiff -o file1 file2 [file3 [file4]] 53 54If you always prefer horizontal splits include "horizontal" in 'diffopt'. 55 56In each of the edited files these options are set: 57 58 'diff' on 59 'scrollbind' on 60 'cursorbind' on 61 'scrollopt' includes "hor" 62 'wrap' off 63 'foldmethod' "diff" 64 'foldcolumn' value from 'diffopt', default is 2 65 66These options are set local to the window. When editing another file they are 67reset to the global value. 68The options can still be overruled from a modeline when re-editing the file. 69However, 'foldmethod' and 'wrap' won't be set from a modeline when 'diff' is 70set. 71 72The differences shown are actually the differences in the buffer. Thus if you 73make changes after loading a file, these will be included in the displayed 74diffs. You might have to do ":diffupdate" now and then, not all changes are 75immediately taken into account. 76 77In your .vimrc file you could do something special when Vim was started in 78diff mode. You could use a construct like this: > 79 80 if &diff 81 setup for diff mode 82 else 83 setup for non-diff mode 84 endif 85 86While already in Vim you can start diff mode in three ways. 87 88 *E98* 89:diffs[plit] {filename} *:diffs* *:diffsplit* 90 Open a new window on the file {filename}. The options are set 91 as for "vimdiff" for the current and the newly opened window. 92 Also see 'diffexpr'. 93 94 *:difft* *:diffthis* 95:difft[his] Make the current window part of the diff windows. This sets 96 the options like for "vimdiff". 97 98:diffp[atch] {patchfile} *E816* *:diffp* *:diffpatch* 99 Use the current buffer, patch it with the diff found in 100 {patchfile} and open a buffer on the result. The options are 101 set as for "vimdiff". 102 {patchfile} can be in any format that the "patch" program 103 understands or 'patchexpr' can handle. 104 Note that {patchfile} should only contain a diff for one file, 105 the current file. If {patchfile} contains diffs for other 106 files as well, the results are unpredictable. Vim changes 107 directory to /tmp to avoid files in the current directory 108 accidentally being patched. But it may still result in 109 various ".rej" files to be created. And when absolute path 110 names are present these files may get patched anyway. 111 112To make these commands use a vertical split, prepend |:vertical|. Examples: > 113 114 :vert diffsplit main.c~ 115 :vert diffpatch /tmp/diff 116 117If you always prefer a vertical split include "vertical" in 'diffopt'. 118 119 *E96* 120There can be up to eight buffers with 'diff' set. 121 122Since the option values are remembered with the buffer, you can edit another 123file for a moment and come back to the same file and be in diff mode again. 124 125 *:diffo* *:diffoff* 126:diffo[ff] Switch off diff mode for the current window. Resets related 127 options also when 'diff' was not set. 128 129:diffo[ff]! Switch off diff mode for the current window and in all windows 130 in the current tab page where 'diff' is set. Resetting 131 related options only happens in a window that has 'diff' set, 132 if the current window does not have 'diff' set then no options 133 in it are changed. 134 Hidden buffers are also removed from the list of diff'ed 135 buffers. 136 137The `:diffoff` command resets the relevant options to the values they had when 138using `:diffsplit`, `:diffpatch` , `:diffthis`. or starting Vim in diff mode. 139When using `:diffoff` twice the last saved values are restored. 140Otherwise they are set to their default value: 141 142 'diff' off 143 'scrollbind' off 144 'cursorbind' off 145 'scrollopt' without "hor" 146 'wrap' on 147 'foldmethod' "manual" 148 'foldcolumn' 0 149 150============================================================================== 1512. Viewing diffs *view-diffs* 152 153The effect is that the diff windows show the same text, with the differences 154highlighted. When scrolling the text, the 'scrollbind' option will make the 155text in other windows to be scrolled as well. With vertical splits the text 156should be aligned properly. 157 158The alignment of text will go wrong when: 159- 'wrap' is on, some lines will be wrapped and occupy two or more screen 160 lines 161- folds are open in one window but not another 162- 'scrollbind' is off 163- changes have been made to the text 164- "filler" is not present in 'diffopt', deleted/inserted lines makes the 165 alignment go wrong 166 167All the buffers edited in a window where the 'diff' option is set will join in 168the diff. This is also possible for hidden buffers. They must have been 169edited in a window first for this to be possible. To get rid of the hidden 170buffers use `:diffoff!`. 171 172 *:DiffOrig* *diff-original-file* 173Since 'diff' is a window-local option, it's possible to view the same buffer 174in diff mode in one window and "normal" in another window. It is also 175possible to view the changes you have made to a buffer since the file was 176loaded. Since Vim doesn't allow having two buffers for the same file, you 177need another buffer. This command is useful: > 178 command DiffOrig vert new | set bt=nofile | r ++edit # | 0d_ 179 \ | diffthis | wincmd p | diffthis 180(this is in |defaults.vim|). Use ":DiffOrig" to see the differences between 181the current buffer and the file it was loaded from. 182 183A buffer that is unloaded cannot be used for the diff. But it does work for 184hidden buffers. You can use ":hide" to close a window without unloading the 185buffer. If you don't want a buffer to remain used for the diff do ":set 186nodiff" before hiding it. 187 188 *:dif* *:diff* *:diffupdate* 189:dif[fupdate][!] Update the diff highlighting and folds. 190 191Vim attempts to keep the differences updated when you make changes to the 192text. This mostly takes care of inserted and deleted lines. Changes within a 193line and more complicated changes do not cause the differences to be updated. 194To force the differences to be updated use: > 195 196 :diffupdate 197 198If the ! is included Vim will check if the file was changed externally and 199needs to be reloaded. It will prompt for each changed file, like `:checktime` 200was used. 201 202Vim will show filler lines for lines that are missing in one window but are 203present in another. These lines were inserted in another file or deleted in 204this file. Removing "filler" from the 'diffopt' option will make Vim not 205display these filler lines. 206 207 208Folds are used to hide the text that wasn't changed. See |folding| for all 209the commands that can be used with folds. 210 211The context of lines above a difference that are not included in the fold can 212be set with the 'diffopt' option. For example, to set the context to three 213lines: > 214 215 :set diffopt=filler,context:3 216 217 218The diffs are highlighted with these groups: 219 220|hl-DiffAdd| DiffAdd Added (inserted) lines. These lines exist in 221 this buffer but not in another. 222|hl-DiffChange| DiffChange Changed lines. 223|hl-DiffText| DiffText Changed text inside a Changed line. Vim 224 finds the first character that is different, 225 and the last character that is different 226 (searching from the end of the line). The 227 text in between is highlighted. This means 228 that parts in the middle that are still the 229 same are highlighted anyway. The 'diffopt' 230 flags "iwhite" and "icase" are used here. 231|hl-DiffDelete| DiffDelete Deleted lines. Also called filler lines, 232 because they don't really exist in this 233 buffer. 234 235============================================================================== 2363. Jumping to diffs *jumpto-diffs* 237 238Two commands can be used to jump to diffs: 239 *[c* 240 [c Jump backwards to the previous start of a change. 241 When a count is used, do it that many times. 242 *]c* 243 ]c Jump forwards to the next start of a change. 244 When a count is used, do it that many times. 245 246It is an error if there is no change for the cursor to move to. 247 248============================================================================== 2494. Diff copying *copy-diffs* *E99* *E100* *E101* *E102* *E103* 250 *merge* 251There are two commands to copy text from one buffer to another. The result is 252that the buffers will be equal within the specified range. 253 254 *:diffg* *:diffget* 255:[range]diffg[et] [bufspec] 256 Modify the current buffer to undo difference with another 257 buffer. If [bufspec] is given, that buffer is used. If 258 [bufspec] refers to the current buffer then nothing happens. 259 Otherwise this only works if there is one other buffer in diff 260 mode. 261 See below for [range]. 262 263 *:diffpu* *:diffput* *E793* 264:[range]diffpu[t] [bufspec] 265 Modify another buffer to undo difference with the current 266 buffer. Just like ":diffget" but the other buffer is modified 267 instead of the current one. 268 When [bufspec] is omitted and there is more than one other 269 buffer in diff mode where 'modifiable' is set this fails. 270 See below for [range]. 271 272 *do* 273[count]do Same as ":diffget" without range. The "o" stands for "obtain" 274 ("dg" can't be used, it could be the start of "dgg"!). Note: 275 this doesn't work in Visual mode. 276 If you give a [count], it is used as the [bufspec] argument 277 for ":diffget". 278 279 *dp* 280[count]dp Same as ":diffput" without range. Note: this doesn't work in 281 Visual mode. 282 If you give a [count], it is used as the [bufspec] argument 283 for ":diffput". 284 285 286When no [range] is given, the diff at the cursor position or just above it is 287affected. When [range] is used, Vim tries to only put or get the specified 288lines. When there are deleted lines, this may not always be possible. 289 290There can be deleted lines below the last line of the buffer. When the cursor 291is on the last line in the buffer and there is no diff above this line, the 292":diffget" and "do" commands will obtain lines from the other buffer. 293 294To be able to get those lines from another buffer in a [range] it's allowed to 295use the last line number plus one. This command gets all diffs from the other 296buffer: > 297 298 :1,$+1diffget 299 300Note that deleted lines are displayed, but not counted as text lines. You 301can't move the cursor into them. To fill the deleted lines with the lines 302from another buffer use ":diffget" on the line below them. 303 *E787* 304When the buffer that is about to be modified is read-only and the autocommand 305that is triggered by |FileChangedRO| changes buffers the command will fail. 306The autocommand must not change buffers. 307 308The [bufspec] argument above can be a buffer number, a pattern for a buffer 309name or a part of a buffer name. Examples: 310 311 :diffget Use the other buffer which is in diff mode 312 :diffget 3 Use buffer 3 313 :diffget v2 Use the buffer which matches "v2" and is in 314 diff mode (e.g., "file.c.v2") 315 316============================================================================== 3175. Diff options *diff-options* 318 319Also see |'diffopt'| and the "diff" item of |'fillchars'|. 320 321 *diff-slow* *diff_translations* 322For very long lines, the diff syntax highlighting might be slow, especially 323since it tries to match all different kind of localisations. To disable 324localisations and speed up the syntax highlighting, set the global variable 325g:diff_translations to zero: > 326 327 let g:diff_translations = 0 328< 329After setting this variable, reload the syntax script: > 330 331 set syntax=diff 332< 333 334 335FINDING THE DIFFERENCES *diff-diffexpr* 336 337The 'diffexpr' option can be set to use something else than the standard 338"diff" program to compare two files and find the differences. 339 340When 'diffexpr' is empty, Vim uses this command to find the differences 341between file1 and file2: > 342 343 diff file1 file2 > outfile 344 345The ">" is replaced with the value of 'shellredir'. 346 347The output of "diff" must be a normal "ed" style diff or a unified diff. Do 348NOT use a context diff. This example explains the format that Vim expects for 349the "ed" style diff: > 350 351 1a2 352 > bbb 353 4d4 354 < 111 355 7c7 356 < GGG 357 --- 358 > ggg 359 360The "1a2" item appends the line "bbb". 361The "4d4" item deletes the line "111". 362The "7c7" item replaces the line "GGG" with "ggg". 363 364When 'diffexpr' is not empty, Vim evaluates it to obtain a diff file in the 365format mentioned. These variables are set to the file names used: 366 367 v:fname_in original file 368 v:fname_new new version of the same file 369 v:fname_out resulting diff file 370 371Additionally, 'diffexpr' should take care of "icase" and "iwhite" in the 372'diffopt' option. 'diffexpr' cannot change the value of 'lines' and 373'columns'. 374 375Example (this does almost the same as 'diffexpr' being empty): > 376 377 set diffexpr=MyDiff() 378 function MyDiff() 379 let opt = "" 380 if &diffopt =~ "icase" 381 let opt = opt . "-i " 382 endif 383 if &diffopt =~ "iwhite" 384 let opt = opt . "-b " 385 endif 386 silent execute "!diff -a --binary " . opt . v:fname_in . " " . v:fname_new . 387 \ " > " . v:fname_out 388 redraw! 389 endfunction 390 391The "-a" argument is used to force comparing the files as text, comparing as 392binaries isn't useful. The "--binary" argument makes the files read in binary 393mode, so that a CTRL-Z doesn't end the text on DOS. 394 395The `redraw!` command may not be needed, depending on whether executing a 396shell command shows something on the display or not. 397 398 *E810* *E97* 399Vim will do a test if the diff output looks alright. If it doesn't, you will 400get an error message. Possible causes: 401- The "diff" program cannot be executed. 402- The "diff" program doesn't produce normal "ed" style diffs (see above). 403- The 'shell' and associated options are not set correctly. Try if filtering 404 works with a command like ":!sort". 405- You are using 'diffexpr' and it doesn't work. 406If it's not clear what the problem is set the 'verbose' option to one or more 407to see more messages. 408 409The self-installing Vim for MS-Windows includes a diff program. If you don't 410have it you might want to download a diff.exe. For example from 411http://gnuwin32.sourceforge.net/packages/diffutils.htm. 412 413 414USING PATCHES *diff-patchexpr* 415 416The 'patchexpr' option can be set to use something else than the standard 417"patch" program. 418 419When 'patchexpr' is empty, Vim will call the "patch" program like this: > 420 421 patch -o outfile origfile < patchfile 422 423This should work fine with most versions of the "patch" program. Note that a 424CR in the middle of a line may cause problems, it is seen as a line break. 425 426If the default doesn't work for you, set the 'patchexpr' to an expression that 427will have the same effect. These variables are set to the file names used: 428 429 v:fname_in original file 430 v:fname_diff patch file 431 v:fname_out resulting patched file 432 433Example (this does the same as 'patchexpr' being empty): > 434 435 set patchexpr=MyPatch() 436 function MyPatch() 437 :call system("patch -o " . v:fname_out . " " . v:fname_in . 438 \ " < " . v:fname_diff) 439 endfunction 440 441Make sure that using the "patch" program doesn't have unwanted side effects. 442For example, watch out for additionally generated files, which should be 443deleted. It should just patch the file and nothing else. 444 Vim will change directory to "/tmp" or another temp directory before 445evaluating 'patchexpr'. This hopefully avoids that files in the current 446directory are accidentally patched. Vim will also delete files starting with 447v:fname_in and ending in ".rej" and ".orig". 448 449 vim:tw=78:ts=8:noet:ft=help:norl: 450