Skip to content

Commit 9294720

Browse files
authored
Merge pull request #2173 from h-east/update-diff
Update diff.{txt,jax}
2 parents 396b0aa + 18ce879 commit 9294720

File tree

2 files changed

+253
-6
lines changed

2 files changed

+253
-6
lines changed

doc/diff.jax

Lines changed: 127 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
*diff.txt* For Vim バージョン 9.1. Last change: 2025 Jun 20
1+
*diff.txt* For Vim バージョン 9.1. Last change: 2025 Jul 26
22

33

44
VIMリファレンスマニュアル by Bram Moolenaar
@@ -14,7 +14,8 @@
1414
2. 差分を眺める |view-diffs|
1515
3. 差分へ移動する |jumpto-diffs|
1616
4. 差分を写す |copy-diffs|
17-
5. 差分モードのオプション |diff-options|
17+
5. 差分アンカー |diff-anchors|
18+
6. 差分モードのオプション |diff-options|
1819

1920
==============================================================================
2021
1. 差分モードを開始する *start-vimdiff*
@@ -343,7 +344,130 @@ Vimは片方のウィンドウには存在しないがもう一方には存在
343344
用する (例, "file.c.v2")
344345

345346
==============================================================================
346-
5. 差分モードオプション *diff-options*
347+
5. 差分アンカー *diff-anchors*
348+
349+
差分アンカーを使用すると、差分アルゴリズムがファイル間でテキストを揃えて同期さ
350+
せる位置を制御できる。各アンカーは各ファイル内で互いにマッチするため、差分の出
351+
力を制御できる。
352+
353+
これは、変更に複雑な編集が含まれる場合に便利である。例えば、関数が別の場所に移
354+
動され、さらに編集された場合などである。デフォルトでは、アルゴリズムは最小の差
355+
分を作成することを目指す。その結果、その関数全体が削除され、反対側に追加された
356+
とみなされ、実際の編集内容を把握することが困難になる。差分アンカーを使用してそ
357+
の関数をピン留めすることで、差分アルゴリズムはそれに基づいて調整を行う。
358+
359+
使用するには、各ファイル内の {address} をコンマ区切りでリスト化した
360+
'diffanchors' を使ってアンカーを設定し、'diffopt' に "anchor" を追加する。Vim
361+
は内部的に各ファイルをアンカーによって分割されたセクションに分割する。そして、
362+
各セクションのペアごとに個別に diff を実行し、結果をマージする。
363+
364+
'diffanchors' を設定すると、差分が即座に更新される。アンカーがマークに結び付け
365+
られており、マークの参照先を変更した場合は、更新された差分結果を取得するため
366+
に、後で手動で |:diffupdate| を呼び出す必要がある。
367+
368+
例:
369+
370+
以下のファイルが並んでいるとする。ここで注目したいのは、編集と移動の両方が行わ
371+
れた関数 `foo()` の変更点である。
372+
373+
ファイル A: >
374+
int foo() {
375+
int n = 1;
376+
return n;
377+
}
378+
379+
int g = 1;
380+
381+
int bar(int a) {
382+
a *= 2;
383+
a += 3;
384+
return a;
385+
}
386+
ファイル B: >
387+
int bar(int a) {
388+
a *= 2;
389+
a += 3;
390+
return a;
391+
}
392+
393+
int foo() {
394+
int n = 999;
395+
return n;
396+
}
397+
398+
int g = 1;
399+
<
400+
通常の差分では、通常、以下のように差分結果が整列される: >
401+
402+
int foo() { |----------------
403+
int n = 1; |----------------
404+
return n; |----------------
405+
} |----------------
406+
|----------------
407+
int g = 1; |----------------
408+
|----------------
409+
int bar(int a) {|int bar(int a) {
410+
a *= 2; | a *= 2;
411+
a += 3; | a += 3;
412+
return a; | return a;
413+
} |}
414+
----------------|
415+
----------------|int foo() {
416+
----------------| int n = 999;
417+
----------------| return n;
418+
----------------|}
419+
----------------|
420+
----------------|int g = 1;
421+
<
422+
我々が望むのは、代わりに差分を `foo()` で揃えることである: >
423+
424+
----------------|int bar(int a) {
425+
----------------| a *= 2;
426+
----------------| a += 3;
427+
----------------| return a;
428+
----------------|}
429+
----------------|
430+
int foo() { |int foo() {
431+
int n = 1; | int n = 999;
432+
return n; | return n;
433+
} |}
434+
|
435+
int g = 1; |int g = 1;
436+
|----------------
437+
int bar(int a) {|----------------
438+
a *= 2; |----------------
439+
a += 3; |----------------
440+
return a; |----------------
441+
} |----------------
442+
<
443+
444+
以下に、上記の結果を得るための差分アンカーの設定方法をいくつか示す。各例におい
445+
て、この設定を有効にするには、'diffopt'`anchor` が設定されている必要があ
446+
る。
447+
448+
マーク: アンカーを設定する前に、各ファイルの `int foo()` 行に |'a| マークを設
449+
定する: >
450+
set diffanchors='a
451+
452+
パターン: |pattern| (|:/| を参照) を使用してアンカーを指定する。ここでは、一
453+
貫性を保つために、常に 1 行目から検索を開始するようにしている: >
454+
set diffanchors=1/int\ foo(/
455+
<
456+
選択: ビジュアルモードを使用して、各ファイルの `foo()` 関数本体全体を選択する。
457+
ここでは 2 つのアンカーを使用している。これにより、関数本体のみが互いにアンカー
458+
され、それ以降の行はアンカーされないようになる。Note 下の `'>+1` に注目。
459+
"+1" が必要なのは、関数の最終行の上ではなく下で分割が行われるようにするためで
460+
ある: >
461+
set diffanchors='<,'>+1
462+
<
463+
バッファローカルなオプションを介して行番号を使用し 2 つのアンカーを手動で設定
464+
する: >
465+
setlocal diffanchors=1,5
466+
wincmd w
467+
setlocal diffanchors=7,11
468+
<
469+
==============================================================================
470+
6. 差分モードオプション *diff-options*
347471

348472
|'diffopt'||'fillchars'| の "diff" 項目も参照。
349473

en/diff.txt

Lines changed: 126 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
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
22

33

44
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -14,7 +14,8 @@ The basics are explained in section |08.7| of the user manual.
1414
2. Viewing diffs |view-diffs|
1515
3. Jumping to diffs |jumpto-diffs|
1616
4. Copying diffs |copy-diffs|
17-
5. Diff options |diff-options|
17+
5. Diff anchors |diff-anchors|
18+
6. Diff options |diff-options|
1819

1920
==============================================================================
2021
1. Starting diff mode *start-vimdiff*
@@ -336,7 +337,129 @@ name or a part of a buffer name. Examples:
336337
diff mode (e.g., "file.c.v2")
337338

338339
==============================================================================
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*
340463

341464
Also see |'diffopt'| and the "diff" item of |'fillchars'|.
342465

0 commit comments

Comments
 (0)