Versions and Diffs

Versions and diffs

Every capture is a version of one plan. A revision does not replace what came before it — it is appended, and both stay readable.

planx capture --parent v3 says which version this one revises. Capturing text identical to the current latest is a no-op that hands back the existing version rather than creating a duplicate.

Moving between them

In the picker, → on a plan opens its versions and ← shuts them again.

In a review, ← and → step to the previous and next version of the plan. Both keys are absent on a plan that has only one.

planx <plan-id>           # the latest version
planx <plan-id> v2        # an exact version

The diff

Opening a version that has a predecessor shows the diff first. You opened v4 because v4 is new, and what is new about it is the diff. Press d for the plan on its own, and d again to come back.

Changes are highlighted at the word. A rewritten approach cannot slip past as a wall of re-flowed text, and a paragraph whose words did not change does not light up because its line breaks moved.

Unchanged runs collapse. space on a collapsed run opens it when you want the surrounding context back.

The comparison is against the newest earlier version that can still be read, not against n - 1. History has holes: a version whose text was trimmed is listed but has no file, and subtracting one would land on something that cannot be opened.

Printing a diff without the review

planx diff <plan-id>                        # against the previous version
planx diff <plan-id> v1 v3 --print
planx diff <plan-id> v1 v3 --print --plain
planx diff <plan-id> --stat

Flag	Meaning
--print	Non-interactive: write the diff to stdout and exit
--plain	Raw unified diff, no rich rendering
--rich	Rich rendering — the default
--stat	Just the summary line

Piping the output implies --print, so planx diff <id> \| less does what it looks like.

Printing a version

planx show <plan-id> v3 --plain
planx show <plan-id> latest --rich

--plain is the raw markdown source; --rich is syntax-highlighted.

The version is required, here as on revise and execute. A plan reference with no version means whatever was captured most recently, which is not what a command written against a reviewed version meant. Say latest when latest is genuinely what you want.

Listing plans

planx list
planx list --here
planx list --json

Newest first. --here limits it to plans captured in the current directory — the same grouping the picker shows.

Deleting

ctrl+d in the picker deletes the plan or version under the cursor, after a confirmation that names its target in full. There is no trash behind it.

The latest version of a plan never offers a delete: it is the plan. Deleting the plan row removes the whole thing.