barrett/diffs.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 13
diffs.nvim/doc/diffs.nvim.txt
Barrett Ruth 5da3929480
feat(neojj): add neojj (jujutsu) integration 
Problem: diffs.nvim has no support for neojj, the neogit-like TUI for
jujutsu VCS. Users switching to jj get no syntax highlighting in neojj
status/diff buffers.

Solution: Mirror the existing neogit integration pattern for neojj.
Register `NeojjStatus`, `NeojjCommitView`, `NeojjDiffView` filetypes,
set `vim.b.neojj_disable_hunk_highlight` on attach, listen for
`User NeojjDiffLoaded` events, and detect jj repo root via
`neojj.lib.jj.repo.worktree_root`. Add parser patterns for neojj's
`added`, `updated`, `changed`, and `unmerged` filename labels.
2026-03-11 14:01:28 -04:00

1061 lines
48 KiB
Text
Raw Permalink Blame History

*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. Derived by blending `diffAdded`
foreground with `Normal` background at 60% alpha.
Only sets `bg`, so treesitter foreground colors show
through.
*DiffsDeleteText*
DiffsDeleteText Character-level background for changed characters
within `-` lines. Derived by blending `diffRemoved`
foreground with `Normal` background at 60% alpha.
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
action line shown when `show_actions` is true.
Diff mode window highlights: ~
These are used for |winhighlight| remapping in `&diff` windows.
*DiffsDiffAdd*
DiffsDiffAdd Background-only. Derived from `DiffAdd` bg.
Treesitter provides foreground syntax highlighting.
*DiffsDiffDelete*
DiffsDiffDelete Foreground and background from `DiffDelete`.
Used for filler lines (`/////`) which have no real
code content to highlight.
*DiffsDiffChange*
DiffsDiffChange Background-only. Derived from `DiffChange` bg.
Treesitter provides foreground syntax highlighting.
*DiffsDiffText*
DiffsDiffText Background-only. Derived from `DiffText` bg.
Treesitter provides foreground syntax highlighting.
To customize these in your colorscheme: >lua
vim.api.nvim_set_hl(0, 'DiffsAdd', { bg = '#2e4a3a' })
vim.api.nvim_set_hl(0, 'DiffsDiffDelete', { link = 'DiffDelete' })
<
Or via `highlights.overrides` in config: >lua
vim.g.diffs = {
highlights = {
overrides = {
DiffsAdd = { bg = '#2e4a3a' },
DiffsDiffDelete = { link = 'DiffDelete' },
},
},
}
<
==============================================================================
HEALTH CHECK *diffs-health*
Run |:checkhealth| diffs to verify your setup.
Checks performed:
- Neovim version >= 0.9.0
- vim-fugitive is installed (optional)
- libvscode_diff shared library is available (optional)
==============================================================================
ACKNOWLEDGEMENTS *diffs-acknowledgements*
- vim-fugitive (https://github.com/tpope/vim-fugitive)
- codediff.nvim (https://github.com/esmuellert/codediff.nvim)
- diffview.nvim (https://github.com/sindrets/diffview.nvim)
- @phanen (https://github.com/phanen) - diff header highlighting,
treesitter injection support, blame_hl.nvim (gitsigns blame popup
highlighting inspiration)
- @tris203 (https://github.com/tris203) - support for transparent backgrounds
==============================================================================
vim:tw=78:ts=8:ft=help:norl:
Reference in a new issue View git blame Copy permalink