diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index 70f7455..f0205d5 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -6,27 +6,22 @@ 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|. +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. Features: ~ -- Treesitter syntax highlighting in diff hunks -- Character-level intra-line diff highlighting +- 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.) - 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 ...`) +- Inline merge conflict marker detection, highlighting, and resolution ============================================================================== 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| - Fugitive .......................................... |diffs-fugitive| - Neogit .............................................. |diffs-neogit| - Gitsigns .......................................... |diffs-gitsigns| - Telescope ........................................ |diffs-telescope| + 7. Fugitive Status Keymaps ................................ |diffs-fugitive| 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| + 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| ============================================================================== 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` — -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. +NOTE: Load your colorscheme before `diffs.nvim`. For example, with lazy.nvim, +set `priority = 1000` and `lazy = false` on your colorscheme plugin. ============================================================================== 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 -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. +When inside a vim-fugitive |: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* diff --git a/lua/diffs/init.lua b/lua/diffs/init.lua index 882d0c4..a9551a5 100644 --- a/lua/diffs/init.lua +++ b/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() diff --git a/plugin/diffs.lua b/plugin/diffs.lua index 9f59dc1..bce599d 100644 --- a/plugin/diffs.lua +++ b/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)