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