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