adam/vim
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

patch 9.1.1557: not possible to anchor specific lines in difff mode

Browse Source 
Problem:  not possible to anchor specific lines in difff mode
Solution: Add support for the anchoring lines in diff mode using the
          'diffanchor' option (Yee Cheng Chin).

Adds support for anchoring specific lines to each other while viewing a
diff. While lines are anchored, they are guaranteed to be aligned to
each other in a diff view, allowing the user to control and inform the
diff algorithm what the desired alignment is. Internally, this is done
by splitting up the buffer at each anchor and run the diff algorithm on
each split section separately, and then merge the results back for a
logically consistent diff result.

To do this, add a new "diffanchors" option that takes a list of
`{address}`, and a new "diffopt" option value "anchor". Each address
specified will be an anchor, and the user can choose to use any type of
address, including marks, line numbers, or pattern search. Anchors are
sorted by line number in each file, and it's possible to have multiple
anchors on the same line (this is useful when doing multi-buffer diff).
Update documentation to provide examples.

This is similar to Git diff's `--anchored` flag. Other diff tools like
Meld/Araxis Merge also have similar features (called "synchronization
points" or "synchronization links"). We are not using Git/Xdiff's
`--anchored` implementation here because it has a very limited API
(it requires usage of the Patience algorithm, and can only anchor
unique lines that are the same across both files).

Because the user could anchor anywhere, diff anchors could result in
adjacent diff blocks (one block is directly touching another without a
gap), if there is a change right above the anchor point. We don't want
to merge these diff blocks because we want to line up the change at the
anchor. Adjacent diff blocks were first allowed when linematch was
added, but the existing code had a lot of branched paths where
line-matched diff blocks were handled differently. As a part of this
change, refactor them to have a more unified code path that is
generalized enough to handle adjacent diff blocks correctly and without
needing to carve in exceptions all over the place.

closes: #17615

Signed-off-by: Yee Cheng Chin <ychin.git@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
This commit is contained in:
Yee Cheng Chin
2025-07-16 20:36:54 +02:00
committed by Christian Brabandt
parent 393d398247
commit 0d9160e11c
54 changed files with 1889 additions and 579 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
runtime/doc/diff.txt
View File

@ -1,4 +1,4 @@
*diff.txt* For Vim version 9.1. Last change: 2025 Jun 20
*diff.txt* For Vim version 9.1. Last change: 2025 Jul 26
VIM REFERENCE MANUAL by Bram Moolenaar
@ -14,7 +14,8 @@ The basics are explained in section |08.7| of the user manual.
2. Viewing diffs |view-diffs|
3. Jumping to diffs |jumpto-diffs|
4. Copying diffs |copy-diffs|
5. Diff options |diff-options|
5. Diff anchors |diff-anchors|
6. Diff options |diff-options|
==============================================================================
1. Starting diff mode *start-vimdiff*
@ -336,7 +337,129 @@ name or a part of a buffer name. Examples:
diff mode (e.g., "file.c.v2")
==============================================================================
5. Diff options *diff-options*
5. Diff anchors *diff-anchors*
Diff anchors allow you to control where the diff algorithm aligns and
synchronize text across files. Each anchor matches each other in each file,
allowing you to control the output of a diff.
This is useful when a change involves complicated edits. For example, if a
function was moved to another location and further edited. By default, the
algorithm aims to create the smallest diff, which results in that entire
function being considered to be deleted and added on the other side, making it
hard to see what the actual edit on it was. You can use diff anchors to pin
that function so the diff algorithm will align based on it.
To use it, set anchors using 'diffanchors' which is a comma-separated list of
{address} in each file, and then add "anchor" to 'diffopt'. Internaly, Vim
splits each file up into sections split by the anchors. It performs the diff
on each pair of sections separately before merging the results back.
Setting 'diffanchors' will update the diff immediately. If an anchor is tied
to a mark, and you change what the mark is pointed to, you need to manually
call |:diffupdate| afterwards to get the updated diff results.
Example:
Let's say we have the following files, side-by-side. We are interested in the
change that happened to the function `foo()`, which was both edited and moved.
File A: >
int foo() {
int n = 1;
return n;
}
int g = 1;
int bar(int a) {
a *= 2;
a += 3;
return a;
}
<File B: >
int bar(int a) {
a *= 2;
a += 3;
return a;
}
int foo() {
int n = 999;
return n;
}
int g = 1;
<
A normal diff will usually align the diff result as such: >
int foo() { |----------------
int n = 1; |----------------
return n; |----------------
} |----------------
|----------------
int g = 1; |----------------
|----------------
int bar(int a) {|int bar(int a) {
a *= 2; | a *= 2;
a += 3; | a += 3;
return a; | return a;
} |}
----------------|
----------------|int foo() {
----------------| int n = 999;
----------------| return n;
----------------|}
----------------|
----------------|int g = 1;
<
What we want is to instead ask the diff to align on `foo()`: >
----------------|int bar(int a) {
----------------| a *= 2;
----------------| a += 3;
----------------| return a;
----------------|}
----------------|
int foo() { |int foo() {
int n = 1; | int n = 999;
return n; | return n;
} |}
|
int g = 1; |int g = 1;
|----------------
int bar(int a) {|----------------
a *= 2; |----------------
a += 3; |----------------
return a; |----------------
} |----------------
<
Below are some ways of setting diff anchors to get the above result. In each
example, 'diffopt' needs to have `anchor` set for this to take effect.
Marks: Set the |'a| mark on the `int foo()` lines in each file first before
setting the anchors: >
set diffanchors='a
Pattern: Specify the anchor using a |pattern| (see |:/|). Here, we make sure
to always start search from line 1 for consistency: >
set diffanchors=1/int\ foo(/
<
Selection: Use visual mode to select the entire `foo()` function body in each
file. Here, we use two anchors. This does a better job of making sure only
the function bodies are anchored against each other but not the lines after
it. Note the `'>+1` below. The "+1" is necessary as we want the split to
happen below the last line of the function, not above: >
set diffanchors='<,'>+1
<
Manually set two anchors using line numbers via buffer-local options: >
setlocal diffanchors=1,5
wincmd w
setlocal diffanchors=7,11
<
==============================================================================
6. Diff options *diff-options*
Also see |'diffopt'| and the "diff" item of |'fillchars'|.

29
runtime/doc/options.txt
View File

@ -1,4 +1,4 @@
*options.txt* For Vim version 9.1. Last change: 2025 Jul 13
*options.txt* For Vim version 9.1. Last change: 2025 Jul 16
VIM REFERENCE MANUAL by Bram Moolenaar
@ -2986,6 +2986,28 @@ A jump table for the options with a short description can be found at |Q_op|.
Join the current window in the group of windows that shows differences
between files. See |vimdiff|.
*'dia'* *'diffanchors'* *E1549*
'diffanchors' 'dia' string (default "")
global or local to buffer |global-local|
List of {address} in each buffer, separated by commas, that are
considered anchors when used for diffing. It's valid to specify "$+1"
for 1 past the last line. "%" cannot be used for this option. There
can be at most 20 anchors set for each buffer.
Each anchor line splits the buffer (the split happens above the
anchor), with each part being diff'ed separately before the final
result is joined. When more than one {address} are provided, the
anchors will be sorted interally by line number. If using buffer
local options, each buffer should have the same number of anchors
(extra anchors will be ignored). This option is only used when
'diffopt' has "anchor" set. See |diff-anchors| for more details and
examples.
*E1550*
If some of the {address} do not resolve to a line in each buffer (e.g.
a pattern search that does not match anything), none of the anchors
will be used.
*'dex'* *'diffexpr'*
'diffexpr' 'dex' string (default "")
global
@ -3014,6 +3036,10 @@ A jump table for the options with a short description can be found at |Q_op|.
patience patience diff algorithm
histogram histogram diff algorithm
anchor Anchor specific lines in each buffer to be
aligned with each other if 'diffanchors' is
set. See |diff-anchors|.
closeoff When a window is closed where 'diff' is set
and there is only one window remaining in the
same tab page with 'diff' set, execute
@ -3116,6 +3142,7 @@ A jump table for the options with a short description can be found at |Q_op|.
"linematch:60", as this will enable alignment
for a 2 buffer diff hunk of 30 lines each,
or a 3 buffer diff hunk of 20 lines each.
Implicitly sets "filler" when this is set.
vertical Start diff mode with vertical splits (unless
explicitly specified otherwise).

3
runtime/doc/quickref.txt
View File

@ -1,4 +1,4 @@
*quickref.txt* For Vim version 9.1. Last change: 2025 Jun 28
*quickref.txt* For Vim version 9.1. Last change: 2025 Jul 16
VIM REFERENCE MANUAL by Bram Moolenaar
@ -682,6 +682,7 @@ Short explanation of each option: *option-list*
'delcombine' 'deco' delete combining characters on their own
'dictionary' 'dict' list of file names used for keyword completion
'diff' use diff mode for the current window
'diffanchors' 'dia' list of {address} to force anchoring of a diff
'diffexpr' 'dex' expression used to obtain a diff file
'diffopt' 'dip' options for using diff mode
'digraph' 'dg' enable the entering of digraphs in Insert mode

5
runtime/doc/tags
View File

@ -216,9 +216,11 @@ $quote eval.txt /*$quote*
'delcombine' options.txt /*'delcombine'*
'dex' options.txt /*'dex'*
'dg' options.txt /*'dg'*
'dia' options.txt /*'dia'*
'dict' options.txt /*'dict'*
'dictionary' options.txt /*'dictionary'*
'diff' options.txt /*'diff'*
'diffanchors' options.txt /*'diffanchors'*
'diffexpr' options.txt /*'diffexpr'*
'diffopt' options.txt /*'diffopt'*
'digraph' options.txt /*'digraph'*
@ -4667,7 +4669,9 @@ E1540 eval.txt /*E1540*
E1541 vi_diff.txt /*E1541*
E1547 various.txt /*E1547*
E1548 wayland.txt /*E1548*
E1549 options.txt /*E1549*
E155 sign.txt /*E155*
E1550 options.txt /*E1550*
E156 sign.txt /*E156*
E157 sign.txt /*E157*
E158 sign.txt /*E158*
@ -6935,6 +6939,7 @@ dict-modification eval.txt /*dict-modification*
did_filetype() builtin.txt /*did_filetype()*
diff diff.txt /*diff*
diff() builtin.txt /*diff()*
diff-anchors diff.txt /*diff-anchors*
diff-diffexpr diff.txt /*diff-diffexpr*
diff-func-examples diff.txt /*diff-func-examples*
diff-mode diff.txt /*diff-mode*

9
runtime/doc/version9.txt
View File

@ -1,4 +1,4 @@
*version9.txt* For Vim version 9.1. Last change: 2025 Jul 15
*version9.txt* For Vim version 9.1. Last change: 2025 Jul 16
VIM REFERENCE MANUAL by Bram Moolenaar
@ -41570,6 +41570,12 @@ the "inline" sub option value for the 'diffopt' setting, with "inline:simple"
being added to the default "diffopt" value (but this does not change how diff
mode works).
The 'diffanchors' option specifies a comma-separated list of addresses in
a buffer that act as anchor points for splitting and independently diffing
buffer sections, improving diff alignment. It is only used when 'diffopt'
includes "anchor" and all specified addresses must resolve in every buffer, or
else the anchors are ignored.
Completion~
----------
- New Insert-mode completion: |i_CTRL-X_CTRL-R| to complete words from
@ -41799,6 +41805,7 @@ Options: ~
|ins-completion| modes
'completeitemalign' Order of |complete-items| in Insert mode completion
popup
'diffanchors' list of {address} to force syncing of diffs
'eventignorewin' autocommand events that are ignored in a window
'findfunc' Vim function to obtain the results for a |:find|
command