1# jj recipes for a shared stack
2
3Rewrites (squash, rebase, restore, abandon, `op restore`, `workspace
4update-stale`) are run only by the agent `NOW.md` names as the rewriter. Other
5agents run `jj new`, `jj describe` and `jj commit` in their own workspace.
6Always pass `-m '…'` or `--use-destination-message`; a bare `squash` or
7`describe` opens an editor and hangs. Checked against jj 0.42.
8
9## Stack rules
10
11- Fold every fix into its owning patch. No "fix after review" commits.
12- Fold into the lowest patch where the change compiles. A fold below a patch it
13 depends on cascades conflicts through every commit in between.
14- Fold only when no end-to-end run is active; a fold changes the tree under it.
15- Until the release ships, park fixes on top as `WIP: fold into <change>: …`,
16 so the tested tree doesn't move.
17
18## An agent's workspace
19
20```
21jj workspace add <workspaces dir>/<project>-ws-<name> -r <change>
22```
23
24Before `jj workspace forget`, confirm its commits are reachable from the stack
25(`jj log -r '<its change>'`) or deliberately abandoned. Then delete the
26directory.
27
28## Folding a fix into its owner
29
30```
31jj log -r '<owner>::' # other agents' "fold into <owner>" WIPs get rebased into conflicts
32jj squash --from <fix> --into <owner> --use-destination-message
33jj st # conflicts: stop and undo (below)
34```
35
36When unsure, park it and fold during the next rebase:
37
38```
39jj describe -r <fix> -m 'WIP: fold into <owner>: <what>'
40jj rebase -r <fix> -A <tip>
41```
42
43## Undoing your own mistake
44
45```
46jj op log # only your operations since the bad one?
47jj op restore <op before> # then restore
48```
49
50If another agent's operation came after, use `jj op revert <op>` for just
51yours, or repair by hand. `jj op undo` doesn't exist here.
52
53## Keeping a frozen tree
54
55A fold below a frozen snapshot (a hotfix base, a tested tree) rebases it and
56can move its tree. Restore it right after the fold:
57
58```
59jj restore --from <old commit of the snapshot> --into <snapshot change>
60```
61
62## Scratch workspace at a frozen snapshot
63
64Create it before folding. `jj workspace add -r <obsolete commit>` unhides that
65commit's old ancestors and turns the stack divergent; use a live change with
66the same tree instead. Afterwards, `jj workspace forget` it, abandon its
67commit, and delete the directory.
68
69## After an interruption
70
71```
72jj workspace update-stale
73jj log -r 'description(substring:"<subject>")' # two copies of one commit?
74jj diff --git -r <each> # keep the one with the edits
75jj abandon <the other>
76```