1*diff.txt* For Vim version 7.3. Last change: 2010 Jul 31 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, 9three or four 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 [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:diffsplit {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:diffthis Make the current window part of the diff windows. This sets 96 the options like for "vimdiff". 97 98:diffpatch {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 four 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:diffoff Switch off diff mode for the current window. 127 128:diffoff! Switch off diff mode for the current window and in all windows 129 in the current tab page where 'diff' is set. 130 131The ":diffoff" command resets the relevant options to their default value. 132This may be different from what the values were before diff mode was started, 133the old values are not remembered. 134 135 'diff' off 136 'scrollbind' off 137 'cursorbind' off 138 'scrollopt' without "hor" 139 'wrap' on 140 'foldmethod' "manual" 141 'foldcolumn' 0 142 143============================================================================== 1442. Viewing diffs *view-diffs* 145 146The effect is that the diff windows show the same text, with the differences 147highlighted. When scrolling the text, the 'scrollbind' option will make the 148text in other windows to be scrolled as well. With vertical splits the text 149should be aligned properly. 150 151The alignment of text will go wrong when: 152- 'wrap' is on, some lines will be wrapped and occupy two or more screen 153 lines 154- folds are open in one window but not another 155- 'scrollbind' is off 156- changes have been made to the text 157- "filler" is not present in 'diffopt', deleted/inserted lines makes the 158 alignment go wrong 159 160All the buffers edited in a window where the 'diff' option is set will join in 161the diff. This is also possible for hidden buffers. They must have been 162edited in a window first for this to be possible. 163 164 *:DiffOrig* *diff-original-file* 165Since 'diff' is a window-local option, it's possible to view the same buffer 166in diff mode in one window and "normal" in another window. It is also 167possible to view the changes you have made to a buffer since the file was 168loaded. Since Vim doesn't allow having two buffers for the same file, you 169need another buffer. This command is useful: > 170 command DiffOrig vert new | set bt=nofile | r # | 0d_ | diffthis 171 \ | wincmd p | diffthis 172(this is in |vimrc_example.vim|). Use ":DiffOrig" to see the differences 173between the current buffer and the file it was loaded from. 174 175A buffer that is unloaded cannot be used for the diff. But it does work for 176hidden buffers. You can use ":hide" to close a window without unloading the 177buffer. If you don't want a buffer to remain used for the diff do ":set 178nodiff" before hiding it. 179 180 *:diffu* *:diffupdate* 181:diffu[pdate] Update the diff highlighting and folds. 182 183Vim attempts to keep the differences updated when you make changes to the 184text. This mostly takes care of inserted and deleted lines. Changes within a 185line and more complicated changes do not cause the differences to be updated. 186To force the differences to be updated use: > 187 188 :diffupdate 189 190 191Vim will show filler lines for lines that are missing in one window but are 192present in another. These lines were inserted in another file or deleted in 193this file. Removing "filler" from the 'diffopt' option will make Vim not 194display these filler lines. 195 196 197Folds are used to hide the text that wasn't changed. See |folding| for all 198the commands that can be used with folds. 199 200The context of lines above a difference that are not included in the fold can 201be set with the 'diffopt' option. For example, to set the context to three 202lines: > 203 204 :set diffopt=filler,context:3 205 206 207The diffs are highlighted with these groups: 208 209|hl-DiffAdd| DiffAdd Added (inserted) lines. These lines exist in 210 this buffer but not in another. 211|hl-DiffChange| DiffChange Changed lines. 212|hl-DiffText| DiffText Changed text inside a Changed line. Vim 213 finds the first character that is different, 214 and the last character that is different 215 (searching from the end of the line). The 216 text in between is highlighted. This means 217 that parts in the middle that are still the 218 same are highlighted anyway. Only "iwhite" of 219 'diffopt' is used here. 220|hl-DiffDelete| DiffDelete Deleted lines. Also called filler lines, 221 because they don't really exist in this 222 buffer. 223 224============================================================================== 2253. Jumping to diffs *jumpto-diffs* 226 227Two commands can be used to jump to diffs: 228 *[c* 229 [c Jump backwards to the previous start of a change. 230 When a count is used, do it that many times. 231 *]c* 232 ]c Jump forwards to the next start of a change. 233 When a count is used, do it that many times. 234 235It is an error if there is no change for the cursor to move to. 236 237============================================================================== 2384. Diff copying *copy-diffs* *E99* *E100* *E101* *E102* *E103* 239 *merge* 240There are two commands to copy text from one buffer to another. The result is 241that the buffers will be equal within the specified range. 242 243 *:diffg* *:diffget* 244:[range]diffg[et] [bufspec] 245 Modify the current buffer to undo difference with another 246 buffer. If [bufspec] is given, that buffer is used. If 247 [bufspec] refers to the current buffer then nothing happens. 248 Otherwise this only works if there is one other buffer in diff 249 mode. 250 See below for [range]. 251 252 *:diffpu* *:diffput* *E793* 253:[range]diffpu[t] [bufspec] 254 Modify another buffer to undo difference with the current 255 buffer. Just like ":diffget" but the other buffer is modified 256 instead of the current one. 257 When [bufspec] is omitted and there is more than one other 258 buffer in diff mode where 'modifiable' is set this fails. 259 See below for [range]. 260 261 *do* 262do Same as ":diffget" without argument or range. The "o" stands 263 for "obtain" ("dg" can't be used, it could be the start of 264 "dgg"!). 265 266 *dp* 267dp Same as ":diffput" without argument or range. 268 269When no [range] is given, the diff at the cursor position or just above it is 270affected. When [range] is used, Vim tries to only put or get the specified 271lines. When there are deleted lines, this may not always be possible. 272 273There can be deleted lines below the last line of the buffer. When the cursor 274is on the last line in the buffer and there is no diff above this line, the 275":diffget" and "do" commands will obtain lines from the other buffer. 276 277To be able to get those lines from another buffer in a [range] it's allowed to 278use the last line number plus one. This command gets all diffs from the other 279buffer: > 280 281 :1,$+1diffget 282 283Note that deleted lines are displayed, but not counted as text lines. You 284can't move the cursor into them. To fill the deleted lines with the lines 285from another buffer use ":diffget" on the line below them. 286 *E787* 287When the buffer that is about to be modified is read-only and the autocommand 288that is triggered by |FileChangedRO| changes buffers the command will fail. 289The autocommand must not change buffers. 290 291The [bufspec] argument above can be a buffer number, a pattern for a buffer 292name or a part of a buffer name. Examples: 293 294 :diffget Use the other buffer which is in diff mode 295 :diffget 3 Use buffer 3 296 :diffget v2 Use the buffer which matches "v2" and is in 297 diff mode (e.g., "file.c.v2") 298 299============================================================================== 3005. Diff options *diff-options* 301 302Also see |'diffopt'| and the "diff" item of |'fillchars'|. 303 304 305FINDING THE DIFFERENCES *diff-diffexpr* 306 307The 'diffexpr' option can be set to use something else than the standard 308"diff" program to compare two files and find the differences. 309 310When 'diffexpr' is empty, Vim uses this command to find the differences 311between file1 and file2: > 312 313 diff file1 file2 > outfile 314 315The ">" is replaced with the value of 'shellredir'. 316 317The output of "diff" must be a normal "ed" style diff. Do NOT use a context 318diff. This example explains the format that Vim expects: > 319 320 1a2 321 > bbb 322 4d4 323 < 111 324 7c7 325 < GGG 326 --- 327 > ggg 328 329The "1a2" item appends the line "bbb". 330The "4d4" item deletes the line "111". 331The '7c7" item replaces the line "GGG" with "ggg". 332 333When 'diffexpr' is not empty, Vim evaluates it to obtain a diff file in the 334format mentioned. These variables are set to the file names used: 335 336 v:fname_in original file 337 v:fname_new new version of the same file 338 v:fname_out resulting diff file 339 340Additionally, 'diffexpr' should take care of "icase" and "iwhite" in the 341'diffopt' option. 'diffexpr' cannot change the value of 'lines' and 342'columns'. 343 344Example (this does almost the same as 'diffexpr' being empty): > 345 346 set diffexpr=MyDiff() 347 function MyDiff() 348 let opt = "" 349 if &diffopt =~ "icase" 350 let opt = opt . "-i " 351 endif 352 if &diffopt =~ "iwhite" 353 let opt = opt . "-b " 354 endif 355 silent execute "!diff -a --binary " . opt . v:fname_in . " " . v:fname_new . 356 \ " > " . v:fname_out 357 endfunction 358 359The "-a" argument is used to force comparing the files as text, comparing as 360binaries isn't useful. The "--binary" argument makes the files read in binary 361mode, so that a CTRL-Z doesn't end the text on DOS. 362 363 *E810* *E97* 364Vim will do a test if the diff output looks alright. If it doesn't, you will 365get an error message. Possible causes: 366- The "diff" program cannot be executed. 367- The "diff" program doesn't produce normal "ed" style diffs (see above). 368- The 'shell' and associated options are not set correctly. Try if filtering 369 works with a command like ":!sort". 370- You are using 'diffexpr' and it doesn't work. 371If it's not clear what the problem is set the 'verbose' option to one or more 372to see more messages. 373 374The self-installing Vim includes a diff program. If you don't have it you 375might want to download a diff.exe. For example from 376http://jlb.twu.net/code/unixkit.php. 377 378 379USING PATCHES *diff-patchexpr* 380 381The 'patchexpr' option can be set to use something else than the standard 382"patch" program. 383 384When 'patchexpr' is empty, Vim will call the "patch" program like this: > 385 386 patch -o outfile origfile < patchfile 387 388This should work fine with most versions of the "patch" program. Note that a 389CR in the middle of a line may cause problems, it is seen as a line break. 390 391If the default doesn't work for you, set the 'patchexpr' to an expression that 392will have the same effect. These variables are set to the file names used: 393 394 v:fname_in original file 395 v:fname_diff patch file 396 v:fname_out resulting patched file 397 398Example (this does the same as 'patchexpr' being empty): > 399 400 set patchexpr=MyPatch() 401 function MyPatch() 402 :call system("patch -o " . v:fname_out . " " . v:fname_in . 403 \ " < " . v:fname_diff) 404 endfunction 405 406Make sure that using the "patch" program doesn't have unwanted side effects. 407For example, watch out for additionally generated files, which should be 408deleted. It should just patch the file and nothing else. 409 Vim will change directory to "/tmp" or another temp directory before 410evaluating 'patchexpr'. This hopefully avoids that files in the current 411directory are accidentally patched. Vim will also delete files starting with 412v:fname_in and ending in ".rej" and ".orig". 413 414 vim:tw=78:ts=8:ft=help:norl: 415