From 951622dbc6a14647e1282cc3083505681a09ac23 Mon Sep 17 00:00:00 2001
From: Barrett Ruth
Date: Sun, 8 Nov 2026 16:18:01 -0600
Subject: [PATCH] docs: show vim.pack setup and complete component defaults
---
README.md | 38 +++++++++++++----
doc/diffs-collection.txt | 90 +++++++++++++++++++++++++++++-----------
2 files changed, 95 insertions(+), 33 deletions(-)
diff --git a/README.md b/README.md
index cb0b3f8..caa49b1 100644
--- a/README.md
+++ b/README.md
@@ -11,39 +11,61 @@ File comparisons, repository review, and conflict resolution for
## Installation
-Install both plugins with your package manager of choice.
+With `vim.pack` (Neovim 0.12+):
-**Load diffs.nvim before diffs-collection.nvim.**
+**Load diffs.nvim before diffs-collection.nvim.** Set configuration before
+`vim.pack.add()`. This example opens repository reviews in split layout:
+
+```lua
+vim.g.diffs_review = { layout = 'split' }
+
+vim.pack.add({
+ 'https://github.com/barrettruth/diffs.nvim',
+ 'https://github.com/barrettruth/diffs-collection.nvim',
+}, { load = true })
+```
+
+`load = true` loads the plugins immediately, in the listed order.
## Configuration
### diffs-diff
-Compare files, buffers, and Git objects with `:Diff`.
+Compare files, buffers, and Git objects with `:Diff`. Defaults:
```lua
vim.g.diffs_diff = {
- default_layout = 'unified',
- difftastic = false,
+ default_layout = 'unified', -- 'unified', 'stacked', or 'split'
+ difftastic = false, -- true or { args = {} } to enable Difftastic
}
```
+Difftastic requires the `difft` executable. Its optional `args` list defaults to
+`{}`. Set `vim.g.diffs_diff = false` to disable `:Diff`.
+
### diffs-review
-Review repository changes with `:Review`.
+Review repository changes with `:Review`. Defaults:
```lua
-vim.g.diffs_review = { layout = 'unified' }
+vim.g.diffs_review = {
+ layout = 'unified', -- 'unified', 'stacked', or 'split'
+}
```
+Set `vim.g.diffs_review = false` to disable `:Review`.
+
### diffs-conflict
-Highlight and resolve conflict markers in the working buffer.
+Highlight and resolve conflict markers in the working buffer. Default:
```lua
vim.g.diffs_conflict = {}
```
+The empty table enables conflict handling. There are no additional options.
+Set `vim.g.diffs_conflict = false` to disable automatic detection and mappings.
+
## Documentation
```vim
diff --git a/doc/diffs-collection.txt b/doc/diffs-collection.txt
index 910b1eb..c8323f3 100644
--- a/doc/diffs-collection.txt
+++ b/doc/diffs-collection.txt
@@ -1,21 +1,77 @@
*diffs-collection.txt* File comparisons, repository review, and conflicts
*diffs-collection*
+diffs-collection.nvim provides :Diff file comparisons, :Review repository
+reviews, and conflict resolution. It requires diffs.nvim for syntax and
+intra-line highlighting.
+
INSTALLATION *diffs-collection-installation*
-Install both plugins. Load diffs.nvim before diffs-collection.nvim.
-Core highlighting uses vim.g.diffs.
+Requires Neovim 0.12+ and Git. Install these repositories:
+
+ https://github.com/barrettruth/diffs.nvim
+ https://github.com/barrettruth/diffs-collection.nvim
+
+Load diffs.nvim before diffs-collection.nvim. Set configuration before loading
+the plugins. Add this example to init.lua to use split repository reviews: >lua
+ vim.g.diffs_review = { layout = 'split' }
+
+ vim.pack.add({
+ 'https://github.com/barrettruth/diffs.nvim',
+ 'https://github.com/barrettruth/diffs-collection.nvim',
+ }, { load = true })
+<
+The load = true option loads the plugins immediately, in the listed order.
+See |vim.pack.add()| for package management. No setup() call is required.
+
+CONFIGURATION *diffs-collection-config*
+ *diffs-collection-components*
+
+Each component is enabled by default. The tables below contain all default
+settings. Define them before |vim.pack.add()|. Configure syntax and intra-line
+highlighting separately through |g:diffs| in diffs.nvim.
+
+File comparisons *g:diffs_diff*
+
+Default configuration: >lua
+ vim.g.diffs_diff = {
+ default_layout = 'unified', -- 'unified', 'stacked', or 'split'
+ difftastic = false, -- true or { args = {} } to enable Difftastic
+ }
+<
+ default_layout
+ Layout for :Diff. Default: 'unified'. See |diffs-collection-commands|
+ for layout descriptions.
+
+ difftastic
+ Structural highlighting with the external difft executable.
+ false disables it. true enables it with no extra arguments.
+ A table enables it and accepts an args list, which defaults to {}.
+ For example: >lua
+ vim.g.diffs_diff = { difftastic = { args = {} } }
+<
+Set vim.g.diffs_diff = false to disable :Diff and its plugin mappings.
+
+Repository review *g:diffs_review*
+
+Default configuration: >lua
+ vim.g.diffs_review = {
+ layout = 'unified', -- 'unified', 'stacked', or 'split'
+ }
+<
+ layout
+ Layout for :Review. Default: 'unified'.
+
+Set vim.g.diffs_review = false to disable :Review and its plugin mappings.
-COMPONENTS *diffs-collection-components*
+Conflict resolution *g:diffs_conflict*
-Components are enabled by default. Define configuration before plugin loading: >lua
- vim.g.diffs_diff = { default_layout = 'unified', difftastic = false }
- vim.g.diffs_review = { layout = 'unified' }
+Default configuration: >lua
vim.g.diffs_conflict = {}
<
-Set a component to false to disable it. An empty table selects its defaults.
-Disabling diffs_diff removes :Diff. Disabling diffs_review removes :Review.
-Disabling diffs_conflict prevents automatic conflict detection and mappings.
+The empty table enables conflict handling. There are no additional options.
+Set vim.g.diffs_conflict = false to disable automatic detection and mappings.
+Configure keys with |vim.keymap.set()| and |diffs-collection-mappings|.
COMMANDS *diffs-collection-commands*
@@ -38,22 +94,6 @@ the old and new content in separate panes.
unstaged, and optional untracked changes. A..B compares endpoints directly.
A...B compares B with the merge base. A B is a direct comparison.
-CONFIGURATION *diffs-collection-config*
-
-vim.g.diffs_diff.default_layout
- Default :Diff layout: 'unified', 'stacked', or 'split'. Default: 'unified'.
-
-vim.g.diffs_diff.difftastic
- false, true, or { args = { ... } }. Default: false. Requires an installed
- difft executable. Structural differences use difftastic's intra-line spans.
-
-vim.g.diffs_review.layout
- Default :Review layout: 'unified', 'stacked', or 'split'. Default: 'unified'.
-
-vim.g.diffs_conflict
- {} enables conflict detection. false disables it. Configure conflict
- mappings with vim.keymap.set() and the mappings below.
-
GENERATED VIEWS *diffs-collection-views*
CTRL-L refreshes the current generated view from its comparison sources. :edit