1
- *diff.txt* For Vim version 9.1. Last change: 2025 Jun 20
1
+ *diff.txt* For Vim version 9.1. Last change: 2025 Jul 26
2
2
3
3
4
4
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -14,7 +14,8 @@ The basics are explained in section |08.7| of the user manual.
14
14
2. Viewing diffs | view-diffs |
15
15
3. Jumping to diffs | jumpto-diffs |
16
16
4. Copying diffs | copy-diffs |
17
- 5. Diff options | diff-options |
17
+ 5. Diff anchors | diff-anchors |
18
+ 6. Diff options | diff-options |
18
19
19
20
==============================================================================
20
21
1. Starting diff mode *start-vimdiff*
@@ -336,7 +337,129 @@ name or a part of a buffer name. Examples:
336
337
diff mode (e.g., "file.c.v2")
337
338
338
339
==============================================================================
339
- 5. Diff options *diff-options*
340
+ 5. Diff anchors *diff-anchors*
341
+
342
+ Diff anchors allow you to control where the diff algorithm aligns and
343
+ synchronize text across files. Each anchor matches each other in each file,
344
+ allowing you to control the output of a diff.
345
+
346
+ This is useful when a change involves complicated edits. For example, if a
347
+ function was moved to another location and further edited. By default, the
348
+ algorithm aims to create the smallest diff, which results in that entire
349
+ function being considered to be deleted and added on the other side, making it
350
+ hard to see what the actual edit on it was. You can use diff anchors to pin
351
+ that function so the diff algorithm will align based on it.
352
+
353
+ To use it, set anchors using 'diffanchors' which is a comma-separated list of
354
+ {address} in each file, and then add "anchor" to 'diffopt' . Internaly, Vim
355
+ splits each file up into sections split by the anchors. It performs the diff
356
+ on each pair of sections separately before merging the results back.
357
+
358
+ Setting 'diffanchors' will update the diff immediately. If an anchor is tied
359
+ to a mark, and you change what the mark is pointed to, you need to manually
360
+ call | :diffupdate | afterwards to get the updated diff results.
361
+
362
+ Example:
363
+
364
+ Let's say we have the following files, side-by-side. We are interested in the
365
+ change that happened to the function `foo ()` , which was both edited and moved.
366
+
367
+ File A: >
368
+ int foo() {
369
+ int n = 1;
370
+ return n;
371
+ }
372
+
373
+ int g = 1;
374
+
375
+ int bar(int a) {
376
+ a *= 2;
377
+ a += 3;
378
+ return a;
379
+ }
380
+ < File B: >
381
+ int bar(int a) {
382
+ a *= 2;
383
+ a += 3;
384
+ return a;
385
+ }
386
+
387
+ int foo() {
388
+ int n = 999;
389
+ return n;
390
+ }
391
+
392
+ int g = 1;
393
+ <
394
+ A normal diff will usually align the diff result as such: >
395
+
396
+ int foo() { |----------------
397
+ int n = 1; |----------------
398
+ return n; |----------------
399
+ } |----------------
400
+ |----------------
401
+ int g = 1; |----------------
402
+ |----------------
403
+ int bar(int a) {|int bar(int a) {
404
+ a *= 2; | a *= 2;
405
+ a += 3; | a += 3;
406
+ return a; | return a;
407
+ } |}
408
+ ----------------|
409
+ ----------------|int foo() {
410
+ ----------------| int n = 999;
411
+ ----------------| return n;
412
+ ----------------|}
413
+ ----------------|
414
+ ----------------|int g = 1;
415
+ <
416
+ What we want is to instead ask the diff to align on `foo ()` : >
417
+
418
+ ----------------|int bar(int a) {
419
+ ----------------| a *= 2;
420
+ ----------------| a += 3;
421
+ ----------------| return a;
422
+ ----------------|}
423
+ ----------------|
424
+ int foo() { |int foo() {
425
+ int n = 1; | int n = 999;
426
+ return n; | return n;
427
+ } |}
428
+ |
429
+ int g = 1; |int g = 1;
430
+ |----------------
431
+ int bar(int a) {|----------------
432
+ a *= 2; |----------------
433
+ a += 3; |----------------
434
+ return a; |----------------
435
+ } |----------------
436
+ <
437
+
438
+ Below are some ways of setting diff anchors to get the above result. In each
439
+ example, 'diffopt' needs to have `anchor` set for this to take effect.
440
+
441
+ Marks: Set the | 'a | mark on the `int foo()` lines in each file first before
442
+ setting the anchors: >
443
+ set diffanchors='a
444
+
445
+ Pattern: Specify the anchor using a | pattern | (see | :/ | ). Here, we make sure
446
+ to always start search from line 1 for consistency: >
447
+ set diffanchors=1/int\ foo(/
448
+ <
449
+ Selection: Use visual mode to select the entire `foo ()` function body in each
450
+ file. Here, we use two anchors. This does a better job of making sure only
451
+ the function bodies are anchored against each other but not the lines after
452
+ it. Note the `'>+ 1 ` below. The "+1" is necessary as we want the split to
453
+ happen below the last line of the function, not above: >
454
+ set diffanchors='<,'>+1
455
+ <
456
+ Manually set two anchors using line numbers via buffer-local options: >
457
+ setlocal diffanchors=1,5
458
+ wincmd w
459
+ setlocal diffanchors=7,11
460
+ <
461
+ ==============================================================================
462
+ 6. Diff options *diff-options*
340
463
341
464
Also see | 'diffopt' | and the "diff" item of | 'fillchars' | .
342
465
0 commit comments