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