barrett/diffs.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 13

merge: resolve conflicts with main

Browse source 
Problem: `feat/telescope` diverged from `main` after the vimdoc
rewrite and committia docs landed upstream.

Solution: merge `origin/main`, resolve conflicts in `init.lua`
(keep telescope config additions), and add telescope.nvim section
to the vimdoc with upstream bug reference.
This commit is contained in:
Barrett Ruth 2026-03-06 13:42:34 -05:00
commit 804421ed17
Signed by: barrett
GPG key ID: A6C96C9349D2FC81
1 changed files with 147 additions and 81 deletions
Download patch file Download diff file Expand all files Collapse all files

228
doc/diffs.nvim.txt
View file

@ -6,22 +6,27 @@ License: MIT
==============================================================================
INTRODUCTION *diffs.nvim*
diffs.nvim adds syntax highlighting to diff views. It overlays language-aware
highlights on top of default diff highlighting in vim-fugitive, Neogit, and
Neovim's built-in diff mode.
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: ~
- Syntax highlighting in |:Git| summary diffs and commit detail views
- Diff header highlighting (`diff --git`, `index`, `---`, `+++`)
- Syntax highlighting in |:Gdiffsplit| / |:Gvdiffsplit| side-by-side diffs
- |:Gdiff| command for unified diff against any git revision
- gitsigns.nvim blame popup highlighting (see |diffs-gitsigns|)
- Background-only diff colors for any `&diff` buffer (vimdiff, diffthis, etc.)
- 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
- Inline merge conflict marker detection, highlighting, and resolution
- |:Gdiff| unified diff against any revision
- Email quoting/patch syntax support (`> diff ...`)
==============================================================================
CONTENTS *diffs-contents*
@ -32,43 +37,41 @@ CONTENTS *diffs-contents*
4. Configuration ............................................ |diffs-config|
5. Commands ............................................... |diffs-commands|
6. Mappings ............................................... |diffs-mappings|
7. Fugitive Status Keymaps ................................ |diffs-fugitive|
7. Integrations ..................................... |diffs-integrations|
Fugitive .......................................... |diffs-fugitive|
Neogit .............................................. |diffs-neogit|
Gitsigns .......................................... |diffs-gitsigns|
Telescope ........................................ |diffs-telescope|
8. Conflict Resolution .................................... |diffs-conflict|
9. Merge Diff Resolution ..................................... |diffs-merge|
10. Neogit ................................................... |diffs-neogit|
11. Gitsigns ................................................ |diffs-gitsigns|
12. API ......................................................... |diffs-api|
13. Implementation ................................... |diffs-implementation|
14. Known Limitations ................................... |diffs-limitations|
15. Highlight Groups ..................................... |diffs-highlights|
16. Health Check ............................................. |diffs-health|
17. Acknowledgements ............................... |diffs-acknowledgements|
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+
- vim-fugitive (https://github.com/tpope/vim-fugitive) (optional, for unified
diff syntax highlighting in |:Git| and commit views)
- Treesitter parsers for languages you want highlighted
Note: The diff mode feature (background-only colors for |:diffthis|, vimdiff,
etc.) works without vim-fugitive.
==============================================================================
SETUP *diffs-setup*
Install with lazy.nvim: >lua
{
'barrettruth/diffs.nvim',
dependencies = { 'tpope/vim-fugitive' },
}
{ 'barrettruth/diffs.nvim' }
<
The plugin works automatically with no configuration required. For
customization, see |diffs-config|.
NOTE: Load your colorscheme before `diffs.nvim`. For example, with lazy.nvim,
set `priority = 1000` and `lazy = false` on your colorscheme plugin.
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*
@ -81,6 +84,8 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads:
fugitive = false,
neogit = false,
gitsigns = false,
committia = false,
telescope = false,
extra_filetypes = {},
highlights = {
background = true,
@ -174,6 +179,26 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads:
vim.g.diffs = { gitsigns = true }
<
{committia} (boolean|table, default: false)
Enable committia.vim integration. Pass `true`
or `{}` to enable, `false` to disable. When
active, committia's diff pane (`ft=git`,
buffer name `__committia_diff__`) receives
treesitter syntax, line backgrounds, and
intra-line diffs. >lua
vim.g.diffs = { committia = true }
<
{telescope} (boolean|table, default: false)
Enable telescope.nvim preview highlighting.
Pass `true` or `{}` to enable, `false` to
disable. When active, telescope preview
buffers showing diffs receive treesitter
syntax, line backgrounds, and intra-line
diffs. See |diffs-telescope|. >lua
vim.g.diffs = { telescope = true }
<
{extra_filetypes} (table, default: {})
Additional filetypes to attach to, beyond the
built-in `git`, `gitcommit`, and any enabled
@ -184,6 +209,12 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads:
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.
@ -447,10 +478,44 @@ Diff buffer mappings: ~
or the fugitive status keymaps.
==============================================================================
FUGITIVE STATUS KEYMAPS *diffs-fugitive*
INTEGRATIONS *diffs-integrations*
When inside a vim-fugitive |:Git| status buffer, diffs.nvim provides keymaps
to open unified diffs for files or entire sections.
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 = {
fugitive = true,
neogit = 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 = { 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*
@ -499,6 +564,53 @@ Configuration: ~
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 = { 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.
------------------------------------------------------------------------------
GITSIGNS *diffs-gitsigns*
Enable gitsigns.nvim (https://github.com/lewis6991/gitsigns.nvim) blame
popup highlighting: >lua
vim.g.diffs = { 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 = { 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*
@ -642,52 +754,6 @@ 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.
==============================================================================
NEOGIT *diffs-neogit*
diffs.nvim works with Neogit (https://github.com/NeogitOrg/neogit) out of
the box. Enable Neogit support in your config: >lua
vim.g.diffs = { neogit = true }
<
When a diff is expanded in a Neogit buffer (e.g., via TAB on a file in the
status view), diffs.nvim applies treesitter syntax highlighting and
intra-line diffs to the hunk lines, just as it does for fugitive.
Neogit highlight overrides: ~
On first attach to a Neogit buffer, diffs.nvim overrides Neogit's diff
highlight groups (`NeogitDiffAdd*`, `NeogitDiffDelete*`,
`NeogitDiffContext*`, `NeogitHunkHeader*`, `NeogitDiffHeader*`, etc.) by
setting them to empty (`{}`). This gives diffs.nvim sole control of diff
line visuals. The overrides are reapplied on `ColorScheme` since Neogit
re-defines its groups then. When `neogit = false`, no highlight overrides
are applied.
==============================================================================
GITSIGNS *diffs-gitsigns*
diffs.nvim can enhance gitsigns.nvim blame popups with syntax highlighting.
Enable gitsigns support in your config: >lua
vim.g.diffs = { gitsigns = true }
<
When `:Gitsigns blame_line full=true` opens a popup, diffs.nvim intercepts
the popup and replaces gitsigns' flat `GitSignsAddPreview`/
`GitSignsDeletePreview` highlights with:
- Treesitter syntax highlighting on the code content
- `DiffsAdd`/`DiffsDelete` line backgrounds
- Character-level intra-line diffs (`DiffsAddText`/`DiffsDeleteText`)
- `@diff.plus`/`@diff.minus` coloring on `+`/`-` prefix characters
The integration patches `gitsigns.popup.create` and `gitsigns.popup.update`
so highlights persist across gitsigns' two-phase render (initial popup, then
update with GitHub/PR data). If gitsigns loads after diffs.nvim, a
`User GitAttach` autocmd retries the setup automatically.
Highlights are applied in a separate `diffs-gitsigns` namespace and do not
interfere with the main decoration provider used for diff buffers.
==============================================================================
API *diffs-api*