-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy pathdiffs.nvim.txt
More file actions
1060 lines (874 loc) · 47.9 KB
/
diffs.nvim.txt
File metadata and controls
1060 lines (874 loc) · 47.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*diffs.nvim.txt* Syntax highlighting for diffs in Neovim
Author: Barrett Ruth <br.barrettruth@gmail.com>
License: MIT
==============================================================================
INTRODUCTION *diffs.nvim*
diffs.nvim adds language-aware syntax highlighting to unified diff content
in Neovim buffers. It replaces flat `diffAdded`/`diffRemoved` coloring with
treesitter syntax, blended line backgrounds, and character-level intra-line
diffs.
With no configuration, diffs.nvim provides:
- `gitcommit` diff highlighting (e.g., `git commit --verbose`)
- Inline merge conflict detection, highlighting, and resolution
- Background-only diff colors for `&diff` buffers (vimdiff, diffthis)
All other integrations are opt-in. See |diffs-integrations|.
Features: ~
- Treesitter syntax highlighting in diff hunks
- Character-level intra-line diff highlighting
- Vim syntax fallback for languages without a treesitter parser
- Blended diff background colors that preserve syntax visibility
- Optional diff prefix (`+`/`-`/` `) concealment
- Gutter (line number) highlighting
- |:Gdiff| unified diff against any revision
- Email quoting/patch syntax support (`> diff ...`)
==============================================================================
CONTENTS *diffs-contents*
1. Introduction ............................................... |diffs.nvim|
2. Requirements ....................................... |diffs-requirements|
3. Setup ..................................................... |diffs-setup|
4. Configuration ............................................ |diffs-config|
5. Commands ............................................... |diffs-commands|
6. Mappings ............................................... |diffs-mappings|
7. Integrations ..................................... |diffs-integrations|
Fugitive .......................................... |diffs-fugitive|
Neogit .............................................. |diffs-neogit|
Neojj ............................................... |diffs-neojj|
Gitsigns .......................................... |diffs-gitsigns|
Telescope ........................................ |diffs-telescope|
8. Conflict Resolution .................................... |diffs-conflict|
9. Merge Diff Resolution ..................................... |diffs-merge|
10. API ......................................................... |diffs-api|
11. Implementation ................................... |diffs-implementation|
12. Known Limitations ................................... |diffs-limitations|
13. Highlight Groups ..................................... |diffs-highlights|
14. Health Check ............................................. |diffs-health|
15. Acknowledgements ............................... |diffs-acknowledgements|
==============================================================================
REQUIREMENTS *diffs-requirements*
- Neovim 0.9.0+
- Treesitter parsers for languages you want highlighted
==============================================================================
SETUP *diffs-setup*
Install with lazy.nvim: >lua
{ 'barrettruth/diffs.nvim' }
<
Do not lazy load with `event`, `lazy`, `ft`, `config`, or `keys` —
diffs.nvim lazy-loads itself.
NOTE: Load your colorscheme before diffs.nvim. With lazy.nvim, set
`priority = 1000` and `lazy = false` on your colorscheme plugin.
See |diffs-config| for customization, |diffs-integrations| for plugin
support.
==============================================================================
CONFIGURATION *diffs-config*
Configuration is done via `vim.g.diffs`. Set this before the plugin loads:
>lua
vim.g.diffs = {
debug = false,
hide_prefix = false,
integrations = {
fugitive = false,
neogit = false,
neojj = false,
gitsigns = false,
committia = false,
telescope = false,
},
extra_filetypes = {},
highlights = {
background = true,
gutter = true,
blend_alpha = 0.6,
warn_max_lines = true,
context = {
enabled = true,
lines = 25,
},
treesitter = {
enabled = true,
max_lines = 500,
},
vim = {
enabled = true,
max_lines = 200,
},
intra = {
enabled = true,
algorithm = 'default',
max_lines = 500,
},
priorities = {
clear = 198,
syntax = 199,
line_bg = 200,
char_bg = 201,
},
overrides = {},
},
conflict = {
enabled = true,
disable_diagnostics = true,
show_virtual_text = true,
show_actions = false,
keymaps = {
ours = 'doo',
theirs = 'dot',
both = 'dob',
none = 'don',
next = ']c',
prev = '[c',
},
},
}
<
*diffs.Config*
Fields: ~
{debug} (boolean, default: false)
Enable debug logging to |:messages| with
`[diffs]` prefix.
{hide_prefix} (boolean, default: false)
Hide diff prefixes (`+`/`-`/` `) using virtual
text overlay. Makes code appear without the
leading diff character. When `highlights.background`
is also enabled, the overlay inherits the line's
background color.
{integrations} (table, default: all false)
Integration toggles. Each key accepts `true`,
`false`, or a table with sub-options. Passing
`true` or a table enables the integration;
`false` disables it. See |diffs-integrations|.
*diffs.IntegrationsConfig*
Fields: ~
{fugitive} (boolean|table, default: false)
Enable vim-fugitive integration. Pass `true`
for defaults, or a table with sub-options
(see |diffs.FugitiveConfig|). When active,
the `fugitive` filetype is registered and
status buffer keymaps are set. >lua
vim.g.diffs = {
integrations = { fugitive = true },
}
vim.g.diffs = {
integrations = {
fugitive = { horizontal = 'dd' },
},
}
<
{neogit} (boolean|table, default: false)
Enable Neogit integration. When active,
`NeogitStatus`, `NeogitCommitView`, and
`NeogitDiffView` filetypes are registered.
See |diffs-neogit|. >lua
integrations = { neogit = true }
<
{neojj} (boolean|table, default: false)
Enable neojj integration. When active,
`NeojjStatus`, `NeojjCommitView`, and
`NeojjDiffView` filetypes are registered.
See |diffs-neojj|. >lua
integrations = { neojj = true }
<
{gitsigns} (boolean|table, default: false)
Enable gitsigns.nvim blame popup highlighting.
See |diffs-gitsigns|. >lua
integrations = { gitsigns = true }
<
{committia} (boolean|table, default: false)
Enable committia.vim integration. When active,
committia's diff pane receives treesitter
syntax and intra-line diffs. >lua
integrations = { committia = true }
<
{telescope} (boolean|table, default: false)
Enable telescope.nvim preview highlighting.
See |diffs-telescope|. >lua
integrations = { telescope = true }
<
Legacy top-level keys (`vim.g.diffs.fugitive`,
etc.) still work but emit a deprecation
warning. If both `integrations` and top-level
keys are present, `integrations` wins and
the stale keys are ignored with a warning.
{extra_filetypes} (table, default: {})
Additional filetypes to attach to, beyond the
built-in `git`, `gitcommit`, and any enabled
integration filetypes. Use this to enable
highlighting in plain `.diff` / `.patch`
files: >lua
vim.g.diffs = {
extra_filetypes = { 'diff' },
}
<
Adding `'diff'` also enables highlighting in
picker preview buffers that set `filetype=diff`:
telescope.nvim (git_commits, git_bcommits,
git_status), snacks.nvim (syntax style only),
and fzf-lua (builtin previewer only). Terminal-
based previewers are not supported.
{highlights} (table, default: see below)
Controls which highlight features are enabled.
See |diffs.Highlights| for fields.
{conflict} (table, default: see below)
Inline merge conflict resolution options.
See |diffs.ConflictConfig| for fields.
*diffs.Highlights*
Highlights table fields: ~
{background} (boolean, default: true)
Apply background highlighting to `+`/`-` lines
using `DiffsAdd`/`DiffsDelete` groups (derived
from `DiffAdd`/`DiffDelete` backgrounds).
{gutter} (boolean, default: true)
Highlight line numbers with matching colors.
Only visible if line numbers are enabled.
{blend_alpha} (number, default: 0.6)
Alpha value for diff line background intensity.
Controls how strongly diff lines (adds/deletes)
stand out from the editor background. Intra-line
highlights use alpha + 0.3 (capped at 1.0) for
extra contrast. Must be between 0 and 1
(inclusive). Higher values produce more vivid
backgrounds.
{warn_max_lines} (boolean, default: true)
Show a |vim.notify()| warning when syntax
highlighting is skipped because a hunk exceeds
{max_lines}. See |diffs-max-lines|.
{context} (table, default: see below)
Syntax parsing context options.
See |diffs.ContextConfig| for fields.
{treesitter} (table, default: see below)
Treesitter highlighting options.
See |diffs.TreesitterConfig| for fields.
{vim} (table, default: see below)
Vim syntax fallback highlighting options.
See |diffs.VimConfig| for fields.
{intra} (table, default: see below)
Character-level (intra-line) diff highlighting.
See |diffs.IntraConfig| for fields.
{priorities} (table, default: see below)
Extmark priority values.
See |diffs.PrioritiesConfig| for fields.
{overrides} (table, default: {})
Map of highlight group names to highlight
definitions (see |nvim_set_hl()|). Applied
after all computed groups without `default`,
so overrides always win over both computed
defaults and colorscheme definitions.
*diffs.ContextConfig*
Context config fields: ~
{enabled} (boolean, default: true)
Read surrounding code from the working tree
file and feed it into the treesitter string
parser. Uses the hunk's `@@ +start,count @@`
line numbers to read lines before and after
the hunk from disk. Improves syntax accuracy
when the hunk is inside an incomplete construct
(e.g., a table literal or function body whose
opening is not visible in the hunk's own
context lines).
{lines} (integer, default: 25)
Max context lines to read in each direction.
Files are read once per parse and cached across
hunks in the same file.
*diffs.PrioritiesConfig*
Priorities config fields: ~
{clear} (integer, default: 198)
Priority for `DiffsClear` extmarks that reset
underlying diff foreground colors. Must be
below {syntax}.
{syntax} (integer, default: 199)
Priority for treesitter and vim syntax extmarks.
Must be below {line_bg} so that colorscheme
backgrounds on syntax groups do not obscure
line-level diff backgrounds.
{line_bg} (integer, default: 200)
Priority for `DiffsAdd`/`DiffsDelete` line
background extmarks. Must be below {char_bg}.
{char_bg} (integer, default: 201)
Priority for `DiffsAddText`/`DiffsDeleteText`
character-level background extmarks. Highest
priority so changed characters stand out.
*diffs.TreesitterConfig*
Treesitter config fields: ~
{enabled} (boolean, default: true)
Apply treesitter syntax highlighting to code.
{max_lines} (integer, default: 500)
Skip treesitter highlighting for hunks with more
highlighted lines (`+`/`-`) than this threshold.
Context lines are not counted. Prevents lag on
massive diffs.
*diffs.VimConfig*
Vim config fields: ~
{enabled} (boolean, default: true)
Use vim syntax highlighting as fallback when no
treesitter parser is available for a language.
Creates a scratch buffer, sets the filetype, and
queries |synID()| per character to extract
highlight groups. Deferred via |vim.schedule()|
so it never blocks the first paint. Slower than
treesitter but covers languages without a TS
parser installed (e.g., COBOL, Fortran).
{max_lines} (integer, default: 200)
Skip vim syntax highlighting for hunks with more
highlighted lines (`+`/`-`) than this threshold.
Context lines are not counted. Lower than the
treesitter default due to the per-character cost
of |synID()|.
*diffs.IntraConfig*
Intra config fields: ~
{enabled} (boolean, default: true)
Enable character-level diff highlighting within
changed lines. When a line changes from `local x = 1`
to `local x = 2`, only the `1`/`2` characters get
an intense background overlay while the rest of the
line keeps the softer line-level background.
{algorithm} (string, default: 'default')
Diff algorithm for character-level analysis.
`'default'`: use |vim.diff()| with settings
inherited from |'diffopt'| (`algorithm` and
`linematch`). `'vscode'`: use libvscodediff FFI
(falls back to default if not available).
{max_lines} (integer, default: 500)
Skip character-level highlighting for hunks with
more highlighted lines (`+`/`-`) than this
threshold. Context lines are not counted.
Note: Header context (e.g., `@@ -10,3 +10,4 @@ func()`) is always
highlighted with treesitter when a parser is available.
Language detection uses Neovim's built-in |vim.filetype.match()| and
|vim.treesitter.language.get_lang()|. To customize filetype detection
or register treesitter parsers for custom filetypes, use
|vim.filetype.add()| and |vim.treesitter.language.register()|.
==============================================================================
MAX LINES *diffs-max-lines*
When a hunk contains more highlighted lines (`+`/`-`) than the configured
threshold, diffs.nvim skips syntax highlighting for that hunk to avoid lag.
Context lines (lines with a space prefix) are not counted toward the limit.
A warning is shown when this happens: >
[diffs.nvim]: Syntax highlighting skipped for 1 hunk(s) — too large.
<
To increase the threshold: >lua
vim.g.diffs = {
highlights = {
treesitter = { max_lines = 1000 }, -- default: 500
vim = { max_lines = 500 }, -- default: 200
},
}
<
To suppress the warning without changing the threshold: >lua
vim.g.diffs = {
highlights = { warn_max_lines = false },
}
<
The `intra.max_lines` threshold (default: 500) is separate and controls
character-level diff highlighting within changed lines. It does not affect
the syntax highlighting warning.
==============================================================================
COMMANDS *diffs-commands*
:Gdiff [revision] *:Gdiff*
Open a unified diff of the current file against a git revision. Displays
in a horizontal split below the current window.
The diff buffer shows `+`/`-` lines with full syntax highlighting for the
code language, plus diff header highlighting for `diff --git`, `---`,
`+++`, and `@@` lines.
If a `diffs://` window already exists in the current tabpage, the new
diff replaces its buffer instead of creating another split.
Parameters: ~
{revision} (string, optional) Git revision to diff against.
Defaults to HEAD.
Examples: >vim
:Gdiff " diff against HEAD
:Gdiff main " diff against main branch
:Gdiff HEAD~3 " diff against 3 commits ago
:Gdiff abc123 " diff against specific commit
<
:Gvdiff [revision] *:Gvdiff*
Like |:Gdiff| but opens in a vertical split.
:Ghdiff [revision] *:Ghdiff*
Like |:Gdiff| but explicitly opens in a horizontal split.
==============================================================================
MAPPINGS *diffs-mappings*
*<Plug>(diffs-gdiff)*
<Plug>(diffs-gdiff) Show unified diff against HEAD in a horizontal
split. Equivalent to |:Gdiff| with no arguments.
*<Plug>(diffs-gvdiff)*
<Plug>(diffs-gvdiff) Show unified diff against HEAD in a vertical
split. Equivalent to |:Gvdiff| with no arguments.
Example configuration: >lua
vim.keymap.set('n', '<leader>gd', '<Plug>(diffs-gdiff)')
vim.keymap.set('n', '<leader>gD', '<Plug>(diffs-gvdiff)')
<
*<Plug>(diffs-conflict-ours)*
<Plug>(diffs-conflict-ours)
Accept current (ours) change. Replaces the
conflict block with ours content.
*<Plug>(diffs-conflict-theirs)*
<Plug>(diffs-conflict-theirs)
Accept incoming (theirs) change. Replaces the
conflict block with theirs content.
*<Plug>(diffs-conflict-both)*
<Plug>(diffs-conflict-both)
Accept both changes (ours then theirs).
*<Plug>(diffs-conflict-none)*
<Plug>(diffs-conflict-none)
Reject both changes (delete entire block).
*<Plug>(diffs-conflict-next)*
<Plug>(diffs-conflict-next)
Jump to next conflict marker. Wraps around.
*<Plug>(diffs-conflict-prev)*
<Plug>(diffs-conflict-prev)
Jump to previous conflict marker. Wraps around.
Example configuration: >lua
vim.keymap.set('n', 'co', '<Plug>(diffs-conflict-ours)')
vim.keymap.set('n', 'ct', '<Plug>(diffs-conflict-theirs)')
vim.keymap.set('n', 'cb', '<Plug>(diffs-conflict-both)')
vim.keymap.set('n', 'cn', '<Plug>(diffs-conflict-none)')
vim.keymap.set('n', ']c', '<Plug>(diffs-conflict-next)')
vim.keymap.set('n', '[c', '<Plug>(diffs-conflict-prev)')
<
*<Plug>(diffs-merge-ours)*
<Plug>(diffs-merge-ours)
Accept ours in a merge diff view. Resolves the
conflict in the working file with ours content.
*<Plug>(diffs-merge-theirs)*
<Plug>(diffs-merge-theirs)
Accept theirs in a merge diff view.
*<Plug>(diffs-merge-both)*
<Plug>(diffs-merge-both)
Accept both (ours then theirs) in a merge diff view.
*<Plug>(diffs-merge-none)*
<Plug>(diffs-merge-none)
Reject both in a merge diff view.
*<Plug>(diffs-merge-next)*
<Plug>(diffs-merge-next)
Jump to next unresolved conflict hunk in merge diff.
*<Plug>(diffs-merge-prev)*
<Plug>(diffs-merge-prev)
Jump to previous unresolved conflict hunk in merge
diff.
Diff buffer mappings: ~
*diffs-q*
q Close the diff window. Available in all `diffs://`
buffers created by |:Gdiff|, |:Gvdiff|, |:Ghdiff|,
or the fugitive status keymaps.
==============================================================================
INTEGRATIONS *diffs-integrations*
diffs.nvim integrates with several plugins. There are two attachment
patterns:
Automatic: ~
Enable via config toggles. The plugin registers `FileType` autocmds for
each integration's filetypes and attaches automatically.
>lua
vim.g.diffs = {
integrations = {
fugitive = true,
neogit = true,
neojj = true,
gitsigns = true,
},
}
<
Opt-in: ~
For filetypes not covered by a built-in integration, use `extra_filetypes`
to attach to any buffer whose content looks like a diff.
>lua
vim.g.diffs = { extra_filetypes = { 'diff' } }
<
------------------------------------------------------------------------------
FUGITIVE *diffs-fugitive*
Enable vim-fugitive (https://github.com/tpope/vim-fugitive) support: >lua
vim.g.diffs = { integrations = { fugitive = true } }
<
|:Git| status and commit views receive treesitter syntax, line backgrounds,
and intra-line diffs. |:Gdiff| opens a unified diff against any revision
(see |diffs-commands|).
Fugitive status keymaps: ~
When inside a |:Git| status buffer, diffs.nvim provides keymaps to open
unified diffs for files or entire sections.
Keymaps: ~
*diffs-du* *diffs-dU*
du Open unified diff in a horizontal split.
dU Open unified diff in a vertical split.
These keymaps work on:
- File lines (e.g., `M src/foo.lua`) - opens diff for that file
- Section headers (e.g., `Staged (3)`) - opens diff for all files in section
- Hunk/context lines below a file - opens diff for the parent file
Behavior by file status: ~
Status Section Base Current Result ~
M Unstaged index working tree unstaged changes
M Staged HEAD index staged changes
A Staged (empty) index file as all-added
D Staged HEAD (empty) file as all-removed
R Staged HEAD:oldname index:newname content diff
U Unstaged :2: (ours) :3: (theirs) merge diff
? Untracked (empty) working tree file as all-added
On section headers, the keymap runs `git diff` (or `git diff --cached` for
staged) and displays all changes in that section as a single unified diff.
Untracked section headers show a warning since there is no meaningful diff.
Configuration: ~
*diffs.FugitiveConfig*
>lua
vim.g.diffs = {
integrations = {
fugitive = {
horizontal = 'du', -- keymap for horizontal split, false to disable
vertical = 'dU', -- keymap for vertical split, false to disable
},
},
}
<
Passing a table enables fugitive integration. Use `fugitive = false`
to disable. There is no `enabled` field; table presence is sufficient.
Fields: ~
{horizontal} (string|false, default: 'du')
Keymap for unified diff in horizontal split.
Set to `false` to disable.
{vertical} (string|false, default: 'dU')
Keymap for unified diff in vertical split.
Set to `false` to disable.
------------------------------------------------------------------------------
NEOGIT *diffs-neogit*
Enable Neogit (https://github.com/NeogitOrg/neogit) support: >lua
vim.g.diffs = { integrations = { neogit = true } }
<
Expanding a diff in a Neogit buffer (e.g., TAB on a file in the status
view) applies treesitter syntax highlighting and intra-line diffs to the
hunk lines.
------------------------------------------------------------------------------
NEOJJ *diffs-neojj*
Enable neojj (https://github.com/NicholasZolton/neojj) support: >lua
vim.g.diffs = { integrations = { neojj = true } }
<
Expanding a diff in a neojj buffer (e.g., TAB on a file in the status
view) applies treesitter syntax highlighting and intra-line diffs to the
hunk lines.
------------------------------------------------------------------------------
GITSIGNS *diffs-gitsigns*
Enable gitsigns.nvim (https://github.com/lewis6991/gitsigns.nvim) blame
popup highlighting: >lua
vim.g.diffs = { integrations = { gitsigns = true } }
<
`:Gitsigns blame_line full=true` popups receive treesitter syntax, line
backgrounds, and intra-line diffs.
Highlights are applied in a separate `diffs-gitsigns` namespace and do not
interfere with the main decoration provider used for diff buffers.
------------------------------------------------------------------------------
TELESCOPE *diffs-telescope*
Enable telescope.nvim (https://github.com/nvim-telescope/telescope.nvim)
preview highlighting: >lua
vim.g.diffs = { integrations = { telescope = true } }
<
Telescope does not set `filetype=diff` on preview buffers — it calls
`vim.treesitter.start(bufnr, "diff")` directly, so diffs.nvim's `FileType`
autocmd never fires. This integration listens for the
`User TelescopePreviewerLoaded` event and attaches to the preview buffer.
Pickers that show diff content (e.g. `git_bcommits`, `git_status`) will
receive treesitter syntax, line backgrounds, and intra-line diffs in the
preview pane.
Known issue: Telescope's previewer may render the first line of the preview
buffer with a black background regardless of colorscheme. This is a
Telescope artifact unrelated to diffs.nvim. Tracked upstream:
https://github.com/nvim-telescope/telescope.nvim/issues/3626
==============================================================================
CONFLICT RESOLUTION *diffs-conflict*
diffs.nvim detects inline merge conflict markers (`<<<<<<<`/`=======`/
`>>>>>>>`) in working files and provides highlighting and resolution keymaps.
Both standard and diff3 (`|||||||`) formats are supported.
Conflict regions are detected automatically on `BufReadPost` and re-scanned
on `TextChanged`. When all conflicts in a buffer are resolved, highlighting
is removed and diagnostics are re-enabled.
Configuration: ~
*diffs.ConflictConfig*
>lua
vim.g.diffs = {
conflict = {
enabled = true,
disable_diagnostics = true,
show_virtual_text = true,
show_actions = false,
priority = 200,
keymaps = {
ours = 'doo',
theirs = 'dot',
both = 'dob',
none = 'don',
next = ']c',
prev = '[c',
},
},
}
<
Fields: ~
{enabled} (boolean, default: true)
Enable conflict marker detection and
resolution. Set to `false` to disable
entirely.
{disable_diagnostics} (boolean, default: true)
Suppress LSP diagnostics on buffers with
conflict markers. Markers produce syntax
errors that clutter the diagnostic list.
Diagnostics are re-enabled when all conflicts
are resolved. Set `false` to leave
diagnostics alone.
{show_virtual_text} (boolean, default: true)
Show `(current)` and `(incoming)` labels at
the end of `<<<<<<<` and `>>>>>>>` marker
lines. Also controls hunk hints in merge
diff views.
{format_virtual_text} (function|nil, default: nil)
Custom formatter for virtual text labels.
Receives `(side, keymap)` where `side` is
`"ours"` or `"theirs"` and `keymap` is the
configured keymap string or `false`. Return
a string (label text without parens) or
`nil` to hide the label. Example: >lua
format_virtual_text = function(side, keymap)
if keymap then
return side .. ' [' .. keymap .. ']'
end
return side
end
<
{show_actions} (boolean, default: false)
Show a codelens-style action line above each
`<<<<<<<` marker listing available resolution
keymaps. Renders as virtual lines using the
`DiffsConflictActions` highlight group.
Only keymaps that are not `false` appear.
{priority} (integer, default: 200)
Extmark priority for conflict region
backgrounds and markers. Adjust if other
plugins use the same priority range.
{keymaps} (table, default: see above)
Buffer-local keymaps for conflict resolution
and navigation. Each value accepts a string
(custom key) or `false` (disabled).
*diffs.ConflictKeymaps*
Keymap fields: ~
{ours} (string|false, default: 'doo')
Accept current (ours) change.
{theirs} (string|false, default: 'dot')
Accept incoming (theirs) change.
{both} (string|false, default: 'dob')
Accept both changes (ours then theirs).
{none} (string|false, default: 'don')
Reject both changes (delete entire block).
{next} (string|false, default: ']c')
Jump to next conflict marker. Wraps around.
{prev} (string|false, default: '[c')
Jump to previous conflict marker. Wraps
around.
User events: ~
*DiffsConflictResolved*
DiffsConflictResolved Fired when the last conflict in a buffer is
resolved. Useful for triggering custom actions
(e.g., auto-staging the file). >lua
vim.api.nvim_create_autocmd('User', {
pattern = 'DiffsConflictResolved',
callback = function()
print('all conflicts resolved!')
end,
})
<
==============================================================================
MERGE DIFF RESOLUTION *diffs-merge*
When pressing `du`/`dU` on an unmerged (`U`) file in the fugitive status
buffer, diffs.nvim opens a unified diff of ours (`git show :2:path`) vs
theirs (`git show :3:path`) with full treesitter and intra-line highlighting.
The same conflict resolution keymaps (`doo`/`dot`/`dob`/`don`/`]c`/`[c`)
are available on the diff buffer. They resolve conflicts in the working
file by matching diff hunks to conflict markers:
- `doo` replaces the conflict region with ours content
- `dot` replaces the conflict region with theirs content
- `dob` replaces with both (ours then theirs)
- `don` removes the conflict region entirely
- `]c`/`[c` navigate between unresolved conflict hunks
Resolved hunks are marked with `(resolved)` virtual text. Hunks that
correspond to auto-merged content (no conflict markers) show an
informational notification and are left unchanged.
The working file buffer is modified in place; save it when ready.
Phase 1 inline conflict highlights (see |diffs-conflict|) are refreshed
automatically after each resolution.
==============================================================================
API *diffs-api*
attach({bufnr}) *diffs.attach()*
Manually attach highlighting to a buffer. Called automatically for
fugitive buffers via the `FileType fugitive` autocmd.
Parameters: ~
{bufnr} (integer, optional) Buffer number. Defaults to current buffer.
refresh({bufnr}) *diffs.refresh()*
Manually refresh highlighting for a buffer. Useful after external changes
or for debugging.
Parameters: ~
{bufnr} (integer, optional) Buffer number. Defaults to current buffer.
==============================================================================
IMPLEMENTATION *diffs-implementation*
Summary / commit detail views: ~
1. `FileType` autocmd for computed filetypes (see |diffs-config|) triggers
|diffs.attach()|. For `git` buffers, only `fugitive://` URIs are attached.
2. The buffer is parsed to detect file headers (`M path/to/file`,
`diff --git a/... b/...`) and hunk headers (`@@ -10,3 +10,4 @@`)
3. For each hunk:
- Language is detected from the filename using |vim.filetype.match()|
- Diff prefixes (`+`/`-`/` `) are stripped from code lines
- Code is parsed with |vim.treesitter.get_string_parser()|
- If no treesitter parser and `vim.enabled`: vim syntax fallback via
scratch buffer and |synID()|
- `DiffsClear` extmarks at priority 198 clear underlying diff foreground
- Syntax highlights are applied as extmarks at priority 199
- Background extmarks (`DiffsAdd`/`DiffsDelete`) at priority 200
- Character-level diff extmarks (`DiffsAddText`/`DiffsDeleteText`) at
priority 201 overlay changed characters with an intense background
- Conceal extmarks hide diff prefixes when `hide_prefix` is enabled
- All priorities are configurable via |diffs.PrioritiesConfig|
4. A decoration provider re-highlights visible hunks on each redraw
Diff mode views: ~
1. `OptionSet diff` detects when any window enters diff mode
2. All `&diff` windows in the tabpage receive a window-local 'winhighlight'
override that remaps `DiffAdd`/`DiffDelete`/`DiffChange`/`DiffText` to
background-only variants, allowing existing treesitter highlighting to
show through the diff colors
==============================================================================
KNOWN LIMITATIONS *diffs-limitations*
Incomplete Syntax Context ~
*diffs-syntax-context*
Treesitter parses each diff hunk in isolation. When `highlights.context` is
enabled (the default), surrounding code is read from the working tree file
and fed into the parser to improve accuracy at hunk boundaries. This helps
when a hunk is inside a table, function body, or loop whose opening is
beyond the hunk's own context lines. Requires `repo_root` and
`file_new_start` to be available on the hunk (true for standard unified
diffs). In rare cases, hunks that start or end mid-expression may still
produce imperfect highlights due to treesitter error recovery.
Syntax Highlighting Flash ~
*diffs-flash*
When opening a fugitive buffer, there is an unavoidable visual "flash" where
the buffer briefly shows fugitive's default diff highlighting before
diffs.nvim applies treesitter highlights.
This occurs because diffs.nvim hooks into the `FileType fugitive` event,
which fires after vim-fugitive has already painted the buffer. The
decoration provider applies highlights on the next redraw cycle.
Conflicting Diff Plugins ~
*diffs-plugin-conflicts*
diffs.nvim may not interact well with other plugins that modify diff
highlighting or the sign column in diff views. Known plugins that may
conflict:
- diffview.nvim (sindrets/diffview.nvim)
Provides its own diff highlighting and conflict resolution UI.
When using diffview.nvim for viewing diffs, you may want to disable
diffs.nvim's diff mode attachment or use one plugin exclusively.
- mini.diff (echasnovski/mini.diff)
Visualizes buffer differences with its own highlighting system.
May override or conflict with diffs.nvim's background highlighting.
- gitsigns.nvim (lewis6991/gitsigns.nvim)
Generally compatible for sign column decorations, but both plugins
modifying line highlights may produce unexpected results.
- git-conflict.nvim (akinsho/git-conflict.nvim)
Provides conflict marker highlighting and resolution keymaps.
diffs.nvim now has built-in conflict resolution (see
|diffs-conflict|). Disable one or the other to avoid overlap.
If you experience visual conflicts, try disabling the conflicting plugin's
diff-related features.
==============================================================================
HIGHLIGHT GROUPS *diffs-highlights*
diffs.nvim defines custom highlight groups. All groups use `default = true`,
so colorschemes can override them by defining the group before the plugin
loads.
All derived groups are computed by alpha-blending a source color into the
`Normal` background. Line-level groups blend at 40% alpha for a subtle tint;
character-level groups blend at 60% for more contrast. Line-number groups
combine both: background from the line-level blend, foreground from the
character-level blend.
Fugitive unified diff highlights: ~
*DiffsAdd*
DiffsAdd Background for `+` lines. Derived by blending
`DiffAdd` background with `Normal` at 40% alpha.
*DiffsDelete*
DiffsDelete Background for `-` lines. Derived by blending
`DiffDelete` background with `Normal` at 40% alpha.
*DiffsAddNr*
DiffsAddNr Line number for `+` lines. Foreground from
`DiffsAddText`, background from `DiffsAdd`.
*DiffsDeleteNr*
DiffsDeleteNr Line number for `-` lines. Foreground from
`DiffsDeleteText`, background from `DiffsDelete`.
*DiffsAddText*
DiffsAddText Character-level background for changed characters
within `+` lines. Uses the raw `DiffAdd` background
color. Only sets `bg`, so treesitter foreground
colors show through.
*DiffsDeleteText*
DiffsDeleteText Character-level background for changed characters
within `-` lines. Uses the raw `DiffDelete`
background color.
Conflict highlights: ~
*DiffsConflictOurs*
DiffsConflictOurs Background for "ours" (current) content lines.
Derived by blending `DiffAdd` background with
`Normal` at 40% alpha (green tint).
*DiffsConflictTheirs*
DiffsConflictTheirs Background for "theirs" (incoming) content lines.
Derived by blending `DiffChange` background with
`Normal` at 40% alpha.
*DiffsConflictBase*
DiffsConflictBase Background for base (ancestor) content lines in
diff3 conflicts. Derived by blending `DiffText`
background with `Normal` at 30% alpha (muted).
*DiffsConflictMarker*
DiffsConflictMarker Dimmed foreground with bold for `<<<<<<<`,
`=======`, `>>>>>>>`, and `|||||||` marker lines.
*DiffsConflictOursNr*
DiffsConflictOursNr Line number for "ours" content lines. Foreground
from higher-alpha blend, background from line-level
blend.
*DiffsConflictTheirsNr*
DiffsConflictTheirsNr Line number for "theirs" content lines.
*DiffsConflictBaseNr*
DiffsConflictBaseNr Line number for base content lines (diff3).
*DiffsConflictActions*
DiffsConflictActions Dimmed foreground (no bold) for the codelens-style