doc/diffs.nvim.txt

@@ -6,27 +6,22 @@ License: MIT
 ==============================================================================
 INTRODUCTION                                                       *diffs.nvim*
 
-diffs.nvim adds language-aware syntax highlighting to unified diff content
+diffs.nvim adds syntax highlighting to diff views. It overlays language-aware
-in Neovim buffers. It replaces flat `diffAdded`/`diffRemoved` coloring with
+highlights on top of default diff highlighting in vim-fugitive, Neogit, and
-treesitter syntax, blended line backgrounds, and character-level intra-line
+Neovim's built-in diff mode.
-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
+- Syntax highlighting in |:Git| summary diffs and commit detail views
-- Character-level intra-line diff highlighting
+- 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.)
 - 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
+- Inline merge conflict marker detection, highlighting, and resolution
-- Email quoting/patch syntax support (`> diff ...`)
 
 ==============================================================================
 CONTENTS                                                      *diffs-contents*
@@ -37,41 +32,43 @@ CONTENTS                                                      *diffs-contents*
   4. Configuration ............................................ |diffs-config|
   5. Commands ............................................... |diffs-commands|
   6. Mappings ............................................... |diffs-mappings|
-  7. Integrations ..................................... |diffs-integrations|
+  7. Fugitive Status Keymaps ................................ |diffs-fugitive|
-       Fugitive .......................................... |diffs-fugitive|
-       Neogit .............................................. |diffs-neogit|
-       Gitsigns .......................................... |diffs-gitsigns|
-       Telescope ........................................ |diffs-telescope|
   8. Conflict Resolution .................................... |diffs-conflict|
   9. Merge Diff Resolution ..................................... |diffs-merge|
- 10. API ......................................................... |diffs-api|
+ 10. Neogit ................................................... |diffs-neogit|
- 11. Implementation ................................... |diffs-implementation|
+ 11. Gitsigns ................................................ |diffs-gitsigns|
- 12. Known Limitations ................................... |diffs-limitations|
+ 12. API ......................................................... |diffs-api|
- 13. Highlight Groups ..................................... |diffs-highlights|
+ 13. Implementation ................................... |diffs-implementation|
- 14. Health Check ............................................. |diffs-health|
+ 14. Known Limitations ................................... |diffs-limitations|
- 15. Acknowledgements ............................... |diffs-acknowledgements|
+ 15. Highlight Groups ..................................... |diffs-highlights|
+ 16. Health Check ............................................. |diffs-health|
+ 17. 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' }
+    {
+      'barrettruth/diffs.nvim',
+      dependencies = { 'tpope/vim-fugitive' },
+    }
 <
+The plugin works automatically with no configuration required. For
+customization, see |diffs-config|.
 
-Do not lazy load with `event`, `lazy`, `ft`, `config`, or `keys` —
+NOTE: Load your colorscheme before `diffs.nvim`. For example, with lazy.nvim,
-diffs.nvim lazy-loads itself.
+set `priority = 1000` and `lazy = false` on your colorscheme plugin.
-
-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*
@@ -84,8 +81,6 @@ 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,
@@ -179,26 +174,6 @@ 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
@@ -209,12 +184,6 @@ 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.
@@ -478,44 +447,10 @@ Diff buffer mappings: ~
                     or the fugitive status keymaps.
 
 ==============================================================================
-INTEGRATIONS                                           *diffs-integrations*
+FUGITIVE STATUS KEYMAPS                                   *diffs-fugitive*
 
-diffs.nvim integrates with several plugins. There are two attachment
+When inside a vim-fugitive |:Git| status buffer, diffs.nvim provides keymaps
-patterns:
+to open unified diffs for files or entire sections.
-
-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*
@@ -564,53 +499,6 @@ 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*
 
@@ -754,6 +642,52 @@ 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*
 

lua/diffs/init.lua

@@ -42,8 +42,6 @@
 
 ---@class diffs.CommittiaConfig
 
----@class diffs.TelescopeConfig
-
 ---@class diffs.ConflictKeymaps
 ---@field ours string|false
 ---@field theirs string|false
@@ -70,7 +68,6 @@
 ---@field neogit diffs.NeogitConfig|false
 ---@field gitsigns diffs.GitsignsConfig|false
 ---@field committia diffs.CommittiaConfig|false
----@field telescope diffs.TelescopeConfig|false
 ---@field conflict diffs.ConflictConfig
 
 ---@class diffs
@@ -152,7 +149,6 @@ local default_config = {
   neogit = false,
   gitsigns = false,
   committia = false,
-  telescope = false,
   conflict = {
     enabled = true,
     disable_diagnostics = true,
@@ -611,10 +607,6 @@ local function init()
     opts.committia = {}
   end
 
-  if opts.telescope == true then
-    opts.telescope = {}
-  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)')
@@ -631,9 +623,6 @@ local function init()
   vim.validate('committia', opts.committia, function(v)
     return v == nil or v == false or type(v) == 'table'
   end, 'table or false')
-  vim.validate('telescope', opts.telescope, 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)
 
@@ -1023,12 +1012,6 @@ function M.get_committia_config()
   return config.committia
 end
 
----@return diffs.TelescopeConfig|false
-function M.get_telescope_config()
-  init()
-  return config.telescope
-end
-
 ---@return diffs.ConflictConfig
 function M.get_conflict_config()
   init()

plugin/diffs.lua

@@ -18,16 +18,6 @@ if gs_cfg == true or type(gs_cfg) == 'table' then
   end
 end
 
-local tel_cfg = (vim.g.diffs or {}).telescope
-if tel_cfg == true or type(tel_cfg) == 'table' then
-  vim.api.nvim_create_autocmd('User', {
-    pattern = 'TelescopePreviewerLoaded',
-    callback = function()
-      require('diffs').attach(vim.api.nvim_get_current_buf())
-    end,
-  })
-end
-
 vim.api.nvim_create_autocmd('FileType', {
   pattern = require('diffs').compute_filetypes(vim.g.diffs or {}),
   callback = function(args)