Reorganizing a stack with jj

Mechanics for stack-reorganize in a Jujutsu checkout. Read SKILL.md first for the contract, the envision phase and the diagnosis, which hold whichever tool you use.

Preconditions

Before you start, ensure a clean starting state with no uncommited changes and no conflicts in the original commit series: run jj st and jj log -r 'main..@'. Also note the current op-id (jj op log -n1) so you can jj op restore if anything goes sideways. Remember how to get the overall diff of the original commit series, e.g. jj diff --git --from oty --to yuxp --at-op aab4.

Execution

Once you know where you want to go, it’s just a matter of creating the right commits with the right commit message and the right content. For small commits it can make sense to just rewrite them from scratch. For larger commits you’ll want tool assistance.

You can choose to either mutate the original changes, or you can duplicate changes so that the original changes are still around to quickly compare against. If you mutate the original changes, you can use --at-op=<operation-id> with any jj command to simulate a previous state of the repository.

When you’re done with everything, make sure the current jj change is an empty change on top of the last commit (jj new). In general, prefer jj new; make changes; jj squash over jj edit so that you can use jj diff while you’re working to see just the changes you made - if you instead used jj edit vwx; make changes; jj diff, it will give you the combined diff of vwx + your local changes, which is often not what you want.

At the end, run jj fix. This will run ./mach lint –fix on every commit in parallel and make sure lint passes after every commit.

jj fix runs only the tools configured under fix.tools; where jj config list fix prints nothing, lint each rewritten commit by hand: jj new <commit>, ./mach lint <paths>, repeat.

jj describe -r <change> -m <commit-message> sets the commit message for a change. jj commit -m <msg> is a shortcut for jj describe -m <msg> && jj new jj rebase -r <single-change> -d <new-parent> moves a single change. jj rebase -s <subtree-root> -d <new-parent> moves a subtree. jj rebase -r <single-change> --before <new-child> or jj squash --from <change> --insert-before <new-child> can be used to reorder. jj new <conflicted-change>; <address conflicts>; jj squash can be used to resolve conflicts. jj squash --from <one-or-more-changes> --into <dest-change> [FILESET] can be used to combine changes. Pass -u (use destination’s description) or -m "..." to skip the description editor when both source and destination have descriptions. jj squash --from X --insert-before <target> FILESET extracts FILESET from X into a new commit before <target>. This is the swiss army knife for splitting and relocating:

--insert-before X → FILESET goes into a new parent of X (split, FILESET first).
--insert-before <child-of-X> → FILESET goes into a new child of X (split, FILESET second).
--insert-before <some-distant-commit> → FILESET is relocated elsewhere in the stack (the “land-early nugget” case). Prefer this over jj split, which is a less general subset. jj absorb -f <change> is the fastest way to fold a refactor commit back into its ancestors: each modified line goes to the closest mutable ancestor that last touched it. Anything attributable only to immutable code (e.g. main) stays behind in <change> as a residue, which can then be squashed manually. Try this first when “fold C4 into C2 and C3”-style work is needed. jj restore --from <rev> [paths] pulls file content from another revision into the working copy without launching an editor. jj file show -r <rev> <path> prints the file’s content at <rev> to stdout — useful for snapshotting “final state” into a temp file before you rewrite history, so you can later restore or diff against it without checking out the revision.

For guidance on splitting an individual commit, check the stack-split-commit skill and its references/jj.md.

jj abandon <change> drops a commit and rebases its descendants automatically, recording any conflicts in them rather than halting. That makes drop-at-source cheap here; drop-superseded.md says when it is the right call, and “Drops” below gives the commands by its step.

jj op log plus jj op restore <op-id> lets you undo cleanly after mutating commits; jj --at-operation <op> peeks at (or even mutates) prior states without disturbing current work.

Measuring the churn

Churn measurement is git’s: git.md, “Measuring the churn”, runs scripts/git-churn.sh over a <base>..<tip> of commit ids. In a colocated checkout, jj log --no-graph -T commit_id -r <change> prints the commit id for a change id.

Drops

The commands for drop-superseded.md, by its step.

Bound the blast radius. jj has no string search over history, so a colocated checkout runs the shape reference’s two git log searches; the path form alone is jj log -r '<change>::<tip>' <added-path>.
Drop it. Note the operation to return to (jj op log -n1) and the tip’s commit id (jj log --no-graph -T commit_id -r <tip>), then jj abandon <change>. The descendants are rebased at once and their conflicts recorded, so the cascade is worked through afterwards. A rewrite carries every bookmark on the range with it: list them first (jj bookmark list -r '<change>::'), and one that must stay put is moved back afterwards with jj bookmark move <name> --to <commit> --allow-backwards, or the range is worked on as a jj duplicate.
Resolve the cascade. jj log -r 'conflicts()' lists the conflicted descendants; resolve them bottom-up with jj new <conflicted>, edit the conflict markers, jj squash. A faithful cascade leaves the reverser an empty change, which jj keeps: confirm jj diff -r <reverser> prints nothing, then jj abandon it; a bookmark pointing at it is deleted by the abandon, so move it to the parent first. On a whole-file move-then-unmove the reverser can instead come up conflicted on the file it deletes, which the drop already removed: deleting the file resolves it, and jj diff is then empty. A hunk written by hand takes its text from the original tip byte for byte, jj file show -r <tip-commit-id> <path>, at the path where the text lives at the tip.
Finish coupled changes at their source. jj new <that-commit>, edit, jj squash.
Validate. jj diff --from <tip-commit-id> --to <new-tip> must be empty for a net-zero drop, and jj log -r '<base>..<new-tip>' two changes shorter than the input once the empty reverser is abandoned; jj op restore <op-id> returns to the input where either fails.

Fold-resplit

The commands for fold-resplit.md. Keep the original tip’s commit id before rewriting; it is the end-state. An input commit’s version of a file is jj file show -r <commit> <path>; the end-state’s whole tree is jj restore --from <tip-commit-id> in a new change on top of the last leaf; a leaf equal to an input commit is that commit rebased into place (jj rebase -r <change> -d <parent>), and a leaf that keeps an input commit’s message copies its description (jj describe -m "$(jj log --no-graph -r <original> -T description)").

Avoiding interactive tools

Avoid running jj diffedit, jj split (without paths), and jj squash -i - these all open a diff editor and aren’t usable from a non-interactive shell.