Tracker: stacked generated diff layout #152

New issue

Closed

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

barrettruth commented

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

Owner

Original issue: barrettruth/diffs.nvim#358
Original author: barrettruth
Original date: 2026-05-19T22:13:58Z

Root tracker for a Pierre-like stacked generated diff layout.

Original note:

see pierre-like diffs stacked mode (i.e. not two columns)

Goal

Add ++layout=stacked as a generated single-column diff layout that keeps unified diff text flow but uses one side-aware line-number rail instead of the current dual old/new rail.

This is not a new diff algorithm and not a new buffer topology. It should reuse existing generated diffs:// buffers, hunk metadata, actions, source navigation, lists, highlighting, and reload machinery.

Accepted product decisions

Use ++layout=stacked as the user-facing mode name.
Support both :Gdiff ++layout=stacked and :Greview ++layout=stacked.
Do not add public config in the first pass.
Keep ++layout=unified as the default and preserve current dual old/new rails.
Keep ++layout=split as the existing paired endpoint/native-diff behavior.
Avoid Pierre-specific implementation details in vimdoc; document the behavior directly.

Line-number semantics

The stacked rail displays one file line number per rendered diff row:

- deleted lines show old-side line numbers.
+ added lines show new-side line numbers.
context lines show new-side line numbers.
file headers, hunk headers, and metadata rows do not display file line numbers.

Example replacement display:

  10 │  alpha
  10 │ -beta
  11 │ +beta changed
  12 │  gamma

The repeated 10 is intentional: the context line is numbered on the new side, while the deletion is numbered on the old side.

Internal direction

Treat unified and stacked as generated-buffer layouts.
Map generated layouts to rail styles:
- unified -> dual
- stacked -> single
Add or centralize layout constants/helpers for unified, stacked, and split.
Store generated rail style in buffer metadata, for example b:diffs_rail_style, so reloads preserve stacked buffers.
Keep raw hunk/action metadata parsed from raw unified diff lines, not rail-prefixed display lines.

Child issues

Non-goals for this tracker

No public default-layout or rail-style config unless a later issue explicitly scopes it.
No rewrite of generated hunk/action metadata.
No changes to the split paired-window endpoint model beyond preserving existing behavior.
No attempt to port Pierre's web renderer architecture; use Neovim-native buffers/extmarks/highlights.

Final acceptance criteria

:Gdiff ++layout=stacked opens a generated single-column diffs:// buffer with single side-aware rails.
:Greview ++layout=stacked opens the full generated review map with single side-aware rails.
:edit / BufReadCmd reload preserves stacked rail style.
Hunk navigation, source opening, dp/do, and visual hunk actions still operate on raw generated diff metadata.
Parser, highlighting, and merge/conflict helpers handle both dual and single rails correctly.
Vimdoc describes stacked layout, exact line-number semantics, and relevant highlight behavior.
Existing unified and split behavior remains unchanged.

Planning reference

Detailed implementation conference notes were used to create the scoped child issues above; those child issues are the source of truth for implementation slices.

> Original issue: barrettruth/diffs.nvim#358 > Original author: `barrettruth` > Original date: 2026-05-19T22:13:58Z Root tracker for a Pierre-like stacked generated diff layout. Original note: > see pierre-like diffs stacked mode (i.e. not two columns) ## Goal Add `++layout=stacked` as a generated single-column diff layout that keeps unified diff text flow but uses **one side-aware line-number rail** instead of the current dual old/new rail. This is not a new diff algorithm and not a new buffer topology. It should reuse existing generated `diffs://` buffers, hunk metadata, actions, source navigation, lists, highlighting, and reload machinery. ## Accepted product decisions - Use `++layout=stacked` as the user-facing mode name. - Support both `:Gdiff ++layout=stacked` and `:Greview ++layout=stacked`. - Do not add public config in the first pass. - Keep `++layout=unified` as the default and preserve current dual old/new rails. - Keep `++layout=split` as the existing paired endpoint/native-diff behavior. - Avoid Pierre-specific implementation details in vimdoc; document the behavior directly. ## Line-number semantics The stacked rail displays one file line number per rendered diff row: - `-` deleted lines show old-side line numbers. - `+` added lines show new-side line numbers. - context lines show new-side line numbers. - file headers, hunk headers, and metadata rows do not display file line numbers. Example replacement display: ```diff 10 │ alpha 10 │ -beta 11 │ +beta changed 12 │ gamma ``` The repeated `10` is intentional: the context line is numbered on the new side, while the deletion is numbered on the old side. ## Internal direction - Treat `unified` and `stacked` as generated-buffer layouts. - Map generated layouts to rail styles: - `unified` -> `dual` - `stacked` -> `single` - Add or centralize layout constants/helpers for `unified`, `stacked`, and `split`. - Store generated rail style in buffer metadata, for example `b:diffs_rail_style`, so reloads preserve stacked buffers. - Keep raw hunk/action metadata parsed from raw unified diff lines, not rail-prefixed display lines. ## Child issues - [x] #361 - [x] #362 - [x] #363 - [x] #364 - [x] #365 - [x] #366 - [x] #367 ## Non-goals for this tracker - No public default-layout or rail-style config unless a later issue explicitly scopes it. - No rewrite of generated hunk/action metadata. - No changes to the split paired-window endpoint model beyond preserving existing behavior. - No attempt to port Pierre's web renderer architecture; use Neovim-native buffers/extmarks/highlights. ## Final acceptance criteria - `:Gdiff ++layout=stacked` opens a generated single-column `diffs://` buffer with single side-aware rails. - `:Greview ++layout=stacked` opens the full generated review map with single side-aware rails. - `:edit` / `BufReadCmd` reload preserves stacked rail style. - Hunk navigation, source opening, `dp`/`do`, and visual hunk actions still operate on raw generated diff metadata. - Parser, highlighting, and merge/conflict helpers handle both dual and single rails correctly. - Vimdoc describes stacked layout, exact line-number semantics, and relevant highlight behavior. - Existing `unified` and `split` behavior remains unchanged. ## Planning reference Detailed implementation conference notes were used to create the scoped child issues above; those child issues are the source of truth for implementation slices.

barrettruth

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