docs: clarify generated :Gdiff versus Fugitive :Gdiffsplit #125

New issue

Closed

opened 2026-09-21 18:12:23 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-09-21 18:12:23 +00:00

Owner

Original issue: barrettruth/diffs.nvim#276
Original author: barrettruth
Original date: 2026-05-09T19:21:42Z

Parent tracker: #270

Problem

The docs need to explain generated :Gdiff on its own terms.

The current stack was motivated by Fugitive interaction limitations, but the product is not a native :Gdiffsplit clone:

Fugitive :Gdiffsplit opens real &diff windows and uses native Vim diff operations.
diffs.nvim :Gdiff opens one generated unified diffs:// buffer with hunk metadata and plugin-owned actions.
Some Fugitive behavior is a useful reference, especially endpoint selection, but not all Fugitive window or object behavior should be copied.

Without explicit docs, future work will keep confusing "Fugitive-compatible generated :Gdiff" with "exact :Gdiffsplit parity".

Required documentation context

Document these facts clearly:

Plain direct :Gdiff from a worktree file shows index -> worktree.
Plain direct :Gdiff does not show staged-only changes; use status-row staged action or an explicit index/tree endpoint when supported.
Fugitive status-row du/dU chooses the edge from the row:
- staged: HEAD -> index
- unstaged: index -> worktree
- untracked: empty index -> worktree
- unmerged: generated ours :2: vs theirs :3:
:Gdiff does not support :Gdiffsplit!, native 3-way diff windows, writable Fugitive object buffers, or &diff window lifecycle.
There is no --staged flag copied from Fugitive because Fugitive does not have that command surface.
Generated hunk actions are capability-scoped:
- dp stages supported index -> worktree hunks/ranges.
- do unstages supported tree -> index hunks/ranges.
- read-only comparisons do not expose mutation maps.
Unsupported or limited surfaces:
- rename/copy;
- binary;
- mode-only;
- submodule;
- direct merge stages.
Paired-window behavior belongs to #252/#253.

Files likely involved

doc/diffs.nvim.txt
README.md
doc/tags if tags are regenerated in this repo's workflow

Behavior / readiness

At minimum:

If docs tags are generated by an existing command, run that command too. Do not hand-edit generated tags if the project has a generation path.

Acceptance criteria

Users can understand why :Gdiff is not :Gdiffsplit.
Direct command behavior and Fugitive status-row behavior are separately documented.
Edge-case docs match the implementation after the refinement issues land.
Docs point paired-window expectations to #252/#253 instead of over-promising generated-buffer parity.

> Original issue: barrettruth/diffs.nvim#276 > Original author: `barrettruth` > Original date: 2026-05-09T19:21:42Z Parent tracker: #270 ## Problem The docs need to explain generated `:Gdiff` on its own terms. The current stack was motivated by Fugitive interaction limitations, but the product is not a native `:Gdiffsplit` clone: - Fugitive `:Gdiffsplit` opens real `&diff` windows and uses native Vim diff operations. - `diffs.nvim :Gdiff` opens one generated unified `diffs://` buffer with hunk metadata and plugin-owned actions. - Some Fugitive behavior is a useful reference, especially endpoint selection, but not all Fugitive window or object behavior should be copied. Without explicit docs, future work will keep confusing "Fugitive-compatible generated `:Gdiff`" with "exact `:Gdiffsplit` parity". ## Required documentation context Document these facts clearly: - Plain direct `:Gdiff` from a worktree file shows `index -> worktree`. - Plain direct `:Gdiff` does not show staged-only changes; use status-row staged action or an explicit index/tree endpoint when supported. - Fugitive status-row `du`/`dU` chooses the edge from the row: - staged: `HEAD -> index` - unstaged: `index -> worktree` - untracked: empty index -> worktree - unmerged: generated ours `:2:` vs theirs `:3:` - `:Gdiff` does not support `:Gdiffsplit!`, native 3-way diff windows, writable Fugitive object buffers, or `&diff` window lifecycle. - There is no `--staged` flag copied from Fugitive because Fugitive does not have that command surface. - Generated hunk actions are capability-scoped: - `dp` stages supported `index -> worktree` hunks/ranges. - `do` unstages supported `tree -> index` hunks/ranges. - read-only comparisons do not expose mutation maps. - Unsupported or limited surfaces: - rename/copy; - binary; - mode-only; - submodule; - direct merge stages. - Paired-window behavior belongs to #252/#253. ## Files likely involved - `doc/diffs.nvim.txt` - `README.md` - `doc/tags` if tags are regenerated in this repo's workflow ## Behavior / readiness At minimum: ```sh ``` If docs tags are generated by an existing command, run that command too. Do not hand-edit generated tags if the project has a generation path. ## Acceptance criteria - Users can understand why `:Gdiff` is not `:Gdiffsplit`. - Direct command behavior and Fugitive status-row behavior are separately documented. - Edge-case docs match the implementation after the refinement issues land. - Docs point paired-window expectations to #252/#253 instead of over-promising generated-buffer parity.

barrettruth

2026-09-21 18:12:23 +00:00