From cb852d115b0417ad0e256e6db6685428791b32ee Mon Sep 17 00:00:00 2001 From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com> Date: Fri, 6 Mar 2026 11:22:13 -0500 Subject: [PATCH 1/4] docs: document picker integration via `extra_filetypes` (#164) ## Problem `extra_filetypes = { 'diff' }` enables highlighting in telescope, snacks, and fzf-lua git preview buffers, but this was not documented beyond a brief mention of `.diff` files. ## Solution Add a README FAQ entry and expand the vimdoc `extra_filetypes` field description to mention specific pickers and which previewer styles are supported. --- doc/diffs.nvim.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index f0205d5..e1541e2 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -184,6 +184,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. From 8122f23541216eb31d2cce2980c7056961eb66eb Mon Sep 17 00:00:00 2001 From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com> Date: Fri, 6 Mar 2026 11:26:35 -0500 Subject: [PATCH 2/4] docs: restructure vimdoc with integrations parent section (#165) ## Problem Integration docs (fugitive, neogit, gitsigns) were scattered as top-level sections with no grouping, making it hard to find all supported plugin integrations in one place. ## Solution Add `|diffs-integrations|` parent section that groups all integration subsections under a single TOC entry. Fugitive, neogit, and gitsigns are now subsections (using `---` separators) under the new `INTEGRATIONS` heading. The intro paragraph documents the two attachment patterns: automatic (config toggles like `fugitive = true`) and opt-in (`extra_filetypes`). Conflict resolution and merge diff resolution remain as standalone top-level sections. TOC renumbered accordingly. --- doc/diffs.nvim.txt | 130 +++++++++++++++++++++++++-------------------- 1 file changed, 72 insertions(+), 58 deletions(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index e1541e2..43e949a 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -32,17 +32,18 @@ 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| 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* @@ -453,10 +454,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* @@ -505,6 +540,31 @@ 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. + ============================================================================== CONFLICT RESOLUTION *diffs-conflict* @@ -648,52 +708,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* From d06144450cf6dbee6fac2cd2b41f5cdef211a067 Mon Sep 17 00:00:00 2001 From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com> Date: Fri, 6 Mar 2026 11:31:40 -0500 Subject: [PATCH 3/4] docs: revamp vimdoc structure and content (#167) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Problem The vimdoc had several issues: integration sections (fugitive, neogit, gitsigns) were scattered as top-level entries with no grouping, the intro implied diffs.nvim works automatically with fugitive/neogit out of the box, the neogit section described a highlight override workaround that was already removed, and `extra_filetypes` didn't mention picker support. ## Solution - Rewrite intro to document default behavior: `gitcommit` highlighting, conflict detection, `&diff` winhighlight — everything else is opt-in - Remove vim-fugitive as a dependency in setup - Add `|diffs-integrations|` parent section grouping fugitive, neogit, and gitsigns - Add fugitive intro paragraph mentioning `:Gdiff` - Trim neogit section (remove stale highlight override docs) - Trim gitsigns section (remove implementation details) - Add `committia` config field docs - Expand `extra_filetypes` docs to mention telescope, snacks, and fzf-lua --- doc/diffs.nvim.txt | 58 ++++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 23 deletions(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index 43e949a..85b8cb5 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -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* @@ -49,27 +54,23 @@ CONTENTS *diffs-contents* 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* @@ -82,6 +83,7 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads: fugitive = false, neogit = false, gitsigns = false, + committia = false, extra_filetypes = {}, highlights = { background = true, @@ -175,6 +177,16 @@ 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 } +< + {extra_filetypes} (table, default: {}) Additional filetypes to attach to, beyond the built-in `git`, `gitcommit`, and any enabled From dc6fd7a3876dd28a2f213619a7edcd88c0627b3b Mon Sep 17 00:00:00 2001 From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com> Date: Fri, 6 Mar 2026 13:04:21 -0500 Subject: [PATCH 4/4] feat: add committia.vim integration (#166) ## Problem committia.vim's diff pane (`ft=git`, buffer name `__committia_diff__`) is rejected by the `ft=git` guard in the `FileType` callback, preventing diffs.nvim from highlighting it. ## Solution Add a `committia` config toggle following the same pattern as `neogit`/`gitsigns`. When enabled, the `ft=git` guard also allows committia's `__committia_diff__` buffer through. Closes #161 --- lua/diffs/init.lua | 17 +++++++++++++++++ plugin/diffs.lua | 5 ++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/lua/diffs/init.lua b/lua/diffs/init.lua index 06b6ad9..a9551a5 100644 --- a/lua/diffs/init.lua +++ b/lua/diffs/init.lua @@ -40,6 +40,8 @@ ---@class diffs.GitsignsConfig +---@class diffs.CommittiaConfig + ---@class diffs.ConflictKeymaps ---@field ours string|false ---@field theirs string|false @@ -65,6 +67,7 @@ ---@field fugitive diffs.FugitiveConfig|false ---@field neogit diffs.NeogitConfig|false ---@field gitsigns diffs.GitsignsConfig|false +---@field committia diffs.CommittiaConfig|false ---@field conflict diffs.ConflictConfig ---@class diffs @@ -145,6 +148,7 @@ local default_config = { fugitive = false, neogit = false, gitsigns = false, + committia = false, conflict = { enabled = true, disable_diagnostics = true, @@ -599,6 +603,10 @@ local function init() opts.gitsigns = {} end + if opts.committia == true then + opts.committia = {} + end + vim.validate('debug', opts.debug, function(v) return v == nil or type(v) == 'boolean' or type(v) == 'string' end, 'boolean or string (file path)') @@ -612,6 +620,9 @@ local function init() vim.validate('gitsigns', opts.gitsigns, function(v) return v == nil or v == false or type(v) == 'table' end, 'table or false') + vim.validate('committia', opts.committia, function(v) + return v == nil or v == false or type(v) == 'table' + end, 'table or false') vim.validate('extra_filetypes', opts.extra_filetypes, 'table', true) vim.validate('highlights', opts.highlights, 'table', true) @@ -995,6 +1006,12 @@ function M.get_fugitive_config() return config.fugitive end +---@return diffs.CommittiaConfig|false +function M.get_committia_config() + init() + return config.committia +end + ---@return diffs.ConflictConfig function M.get_conflict_config() init() diff --git a/plugin/diffs.lua b/plugin/diffs.lua index 43c5564..bce599d 100644 --- a/plugin/diffs.lua +++ b/plugin/diffs.lua @@ -23,7 +23,10 @@ vim.api.nvim_create_autocmd('FileType', { callback = function(args) local diffs = require('diffs') if args.match == 'git' then - if not diffs.get_fugitive_config() or not diffs.is_fugitive_buffer(args.buf) then + local is_fugitive = diffs.get_fugitive_config() and diffs.is_fugitive_buffer(args.buf) + local is_committia = diffs.get_committia_config() + and vim.api.nvim_buf_get_name(args.buf):match('__committia_diff__$') + if not is_fugitive and not is_committia then return end end