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] 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