docs: revamp vimdoc structure and content (#167)

## 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
This commit is contained in:
Barrett Ruth 2026-03-06 11:31:40 -05:00 committed by GitHub
parent 8122f23541
commit d06144450c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -6,22 +6,27 @@ License: MIT
============================================================================== ==============================================================================
INTRODUCTION *diffs.nvim* INTRODUCTION *diffs.nvim*
diffs.nvim adds syntax highlighting to diff views. It overlays language-aware diffs.nvim adds language-aware syntax highlighting to unified diff content
highlights on top of default diff highlighting in vim-fugitive, Neogit, and in Neovim buffers. It replaces flat `diffAdded`/`diffRemoved` coloring with
Neovim's built-in diff mode. 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: ~ Features: ~
- Syntax highlighting in |:Git| summary diffs and commit detail views - Treesitter syntax highlighting in diff hunks
- Diff header highlighting (`diff --git`, `index`, `---`, `+++`) - Character-level intra-line diff highlighting
- 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 - Vim syntax fallback for languages without a treesitter parser
- Blended diff background colors that preserve syntax visibility - Blended diff background colors that preserve syntax visibility
- Optional diff prefix (`+`/`-`/` `) concealment - Optional diff prefix (`+`/`-`/` `) concealment
- Gutter (line number) highlighting - 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* CONTENTS *diffs-contents*
@ -49,27 +54,23 @@ CONTENTS *diffs-contents*
REQUIREMENTS *diffs-requirements* REQUIREMENTS *diffs-requirements*
- Neovim 0.9.0+ - 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 - 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* SETUP *diffs-setup*
Install with lazy.nvim: >lua 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|.
NOTE: Load your colorscheme before `diffs.nvim`. For example, with lazy.nvim, Do not lazy load with `event`, `lazy`, `ft`, `config`, or `keys` —
set `priority = 1000` and `lazy = false` on your colorscheme plugin. 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* CONFIGURATION *diffs-config*
@ -82,6 +83,7 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads:
fugitive = false, fugitive = false,
neogit = false, neogit = false,
gitsigns = false, gitsigns = false,
committia = false,
extra_filetypes = {}, extra_filetypes = {},
highlights = { highlights = {
background = true, background = true,
@ -175,6 +177,16 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads:
vim.g.diffs = { gitsigns = true } 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: {}) {extra_filetypes} (table, default: {})
Additional filetypes to attach to, beyond the Additional filetypes to attach to, beyond the
built-in `git`, `gitcommit`, and any enabled built-in `git`, `gitcommit`, and any enabled