feat: docs update (vim-fugitive is optional)

README.md

@@ -11,7 +11,7 @@ highlighting.
 
 - Treesitter syntax highlighting in `:Git` diffs and commit views
 - `:Gdiffsplit` / `:Gvdiffsplit` syntax through diff backgrounds
-- Background-only diff colors for any `&diff` buffer
+- Background-only diff colors for any `&diff` buffer (`:diffthis`, `vimdiff`)
 - Vim syntax fallback for languages without a treesitter parser
 - Hunk header context highlighting (`@@ ... @@ function foo()`)
 - Configurable debouncing, max lines, and diff prefix concealment
@@ -19,7 +19,8 @@ highlighting.
 ## Requirements
 
 - Neovim 0.9.0+
-- [vim-fugitive](https://github.com/tpope/vim-fugitive)
+- [vim-fugitive](https://github.com/tpope/vim-fugitive) (optional, for unified
+  diff syntax highlighting)
 
 ## Installation
 
@@ -39,6 +40,26 @@ Using [lazy.nvim](https://github.com/folke/lazy.nvim):
 :help diffs.nvim
 ```
 
+## Highlight Groups
+
+diffs.nvim defines the following highlight groups. All use `default = true`, so
+colorschemes can override them.
+
+| Group             | Purpose                                            |
+| ----------------- | -------------------------------------------------- |
+| `DiffsAdd`        | Background for `+` lines in fugitive unified diffs |
+| `DiffsDelete`     | Background for `-` lines in fugitive unified diffs |
+| `DiffsAddNr`      | Line number highlight for `+` lines                |
+| `DiffsDeleteNr`   | Line number highlight for `-` lines                |
+| `DiffsDiffAdd`    | Background-only `DiffAdd` for `&diff` windows      |
+| `DiffsDiffDelete` | Background-only `DiffDelete` for `&diff` windows   |
+| `DiffsDiffChange` | Background-only `DiffChange` for `&diff` windows   |
+| `DiffsDiffText`   | Background-only `DiffText` for `&diff` windows     |
+
+By default, these are computed from your colorscheme's `DiffAdd`, `DiffDelete`,
+`DiffChange`, `DiffText`, and `Normal` groups. To customize, define them in your
+colorscheme before diffs.nvim loads, or link them to existing groups.
+
 ## Known Limitations
 
 - Syntax "flashing": diffs.nvim hooks into the `FileType fugitive` event

doc/diffs.nvim.txt

@@ -23,9 +23,13 @@ Features: ~
 REQUIREMENTS                                              *diffs-requirements*
 
 - Neovim 0.9.0+
-- vim-fugitive (https://github.com/tpope/vim-fugitive) for unified diff views
+- 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*
 
@@ -187,6 +191,50 @@ To minimize the flash, use a low debounce value: >lua
     })
 <
 
+==============================================================================
+HIGHLIGHT GROUPS                                          *diffs-highlights*
+
+diffs.nvim defines custom highlight groups. All are set with `default = true`,
+so colorschemes can override them by defining them first.
+
+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
+                        `diffAdded`, background from `DiffsAdd`.
+
+                                                             *DiffsDeleteNr*
+    DiffsDeleteNr       Line number for `-` lines. Foreground from
+                        `diffRemoved`, background from `DiffsDelete`.
+
+Diff mode window highlights: ~
+These are background-only variants used for |winhighlight| remapping in
+`&diff` windows, allowing treesitter syntax to show through.
+
+                                                             *DiffsDiffAdd*
+    DiffsDiffAdd        Background-only version of `DiffAdd`.
+
+                                                          *DiffsDiffDelete*
+    DiffsDiffDelete     Background-only version of `DiffDelete`.
+
+                                                          *DiffsDiffChange*
+    DiffsDiffChange     Background-only version of `DiffChange`.
+
+                                                            *DiffsDiffText*
+    DiffsDiffText       Background-only version of `DiffText`.
+
+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' })
+<
+
 ==============================================================================
 HEALTH CHECK                                                 *diffs-health*
 
@@ -194,7 +242,7 @@ Run |:checkhealth| diffs to verify your setup.
 
 Checks performed:
 - Neovim version >= 0.9.0
-- vim-fugitive is installed
+- vim-fugitive is installed (optional)
 
 ==============================================================================
  vim:tw=78:ts=8:ft=help:norl:

lua/diffs/init.lua

@@ -220,18 +220,18 @@ local function compute_highlight_groups()
   local blended_add = blend_color(add_bg, bg, 0.4)
   local blended_del = blend_color(del_bg, bg, 0.4)
 
-  vim.api.nvim_set_hl(0, 'DiffsAdd', { bg = blended_add })
-  vim.api.nvim_set_hl(0, 'DiffsDelete', { bg = blended_del })
-  vim.api.nvim_set_hl(0, 'DiffsAddNr', { fg = add_fg, bg = blended_add })
-  vim.api.nvim_set_hl(0, 'DiffsDeleteNr', { fg = del_fg, bg = blended_del })
+  vim.api.nvim_set_hl(0, 'DiffsAdd', { default = true, bg = blended_add })
+  vim.api.nvim_set_hl(0, 'DiffsDelete', { default = true, bg = blended_del })
+  vim.api.nvim_set_hl(0, 'DiffsAddNr', { default = true, fg = add_fg, bg = blended_add })
+  vim.api.nvim_set_hl(0, 'DiffsDeleteNr', { default = true, fg = del_fg, bg = blended_del })
 
   local diff_change = resolve_hl('DiffChange')
   local diff_text = resolve_hl('DiffText')
 
-  vim.api.nvim_set_hl(0, 'DiffsDiffAdd', { bg = diff_add.bg })
-  vim.api.nvim_set_hl(0, 'DiffsDiffDelete', { bg = diff_delete.bg })
-  vim.api.nvim_set_hl(0, 'DiffsDiffChange', { bg = diff_change.bg })
-  vim.api.nvim_set_hl(0, 'DiffsDiffText', { bg = diff_text.bg })
+  vim.api.nvim_set_hl(0, 'DiffsDiffAdd', { default = true, bg = diff_add.bg })
+  vim.api.nvim_set_hl(0, 'DiffsDiffDelete', { default = true, bg = diff_delete.bg })
+  vim.api.nvim_set_hl(0, 'DiffsDiffChange', { default = true, bg = diff_change.bg })
+  vim.api.nvim_set_hl(0, 'DiffsDiffText', { default = true, bg = diff_text.bg })
 end
 
 local DIFF_WINHIGHLIGHT = table.concat({