How jj undo works

In short: jj takes the current operation. If it is itself an undo, jj takes the operation that undo restored, read back from its description. It refuses if the operation came from another workspace, is the root, or is a merge, and warns about undoing a push or a workspace removal. It then picks the operation to restore: the target's parent, or, if that parent is an undo, what that undo restored. A transaction copies that operation's view (commits, bookmarks, tags, working-copy pointers and remote-tracking refs) over the current one. It is recorded as undo: restore to operation <id>. That description is how the next jj undo finds its place.

The command is cmd_undo. The operations page compares undo with redo, op restore and op revert, and explains what a view is. This page follows undo line by line. Restoring an operation never touches commits, which are immutable and stay in the store. Only the view, meaning which commits are visible and where refs point, changes.

1. Command-line surface

UndoArgs and its help text

There is no argument naming an operation. To restore or revert a particular one, the help text points to jj op restore and jj op revert. The global --at-operation flag changes which operation the repository is loaded at, and therefore which one is "current".

2. Configuration

jj undo reads no settings of its own. templates.op_summary formats the Undid operation: and Restored to operation: lines (source). The working-copy settings on the working-copy page govern the snapshot at the start and the checkout at the end. jj undo always restores both the repo portion and the remote-tracking portion of the view; the choice that op restore --what offers isn't exposed (DEFAULT_REVERT_WHAT).

3. End-to-end flow

4. Core architecture touchpoints

5. Transaction and operation

• Transaction: one, started after every check passes (source).
• Operation description: undo: restore to operation <id>, where <id> is the full hex ID of the restored operation (UNDO_OP_DESC_PREFIX, source). This exact text is functional: the next jj undo strips the prefix and parses the ID. jj op revert uses a different description, so an undo after op revert undoes the revert rather than continuing a stack (upstream test).
• Commits created or rewritten: none. Only the view changes.
• Working copy: the workspace is loaded with the usual snapshot. If you have unrecorded edits, that snapshot is committed as its own operation and becomes the current one (source), so it is what jj undo undoes. After the undo operation is written, the restored @ is checked out.
• jj undo again continues further back. jj redo undoes the undo, by restoring the operation the undo replaced.

6. Algorithm and invariants

The undo stack, encoded in descriptions

There is no separate undo stack. It is reconstructed from operation descriptions, using two substitutions (source comment):

1. Choosing what to undo. If the current operation is an undo, the thing to undo next is the operation it restored, not the undo itself (source). So repeated jj undo keeps stepping back instead of toggling between two states.
2. Choosing what to restore. Normally that's the target's parent. If the parent is itself an undo, jj restores what that undo restored instead (source). The source comment explains that otherwise, repeated jj new; jj undo would build an ever-longer linked list of undos that a later undo would have to walk.

Together these make the stack "jump over" older undo stacks it runs into, as the worked example below shows.

What restoring means

view_with_desired_portions_restored builds a new View field by field. With Repo selected, head_ids, local_bookmarks, local_tags and wc_commit_ids come from the restored view. With RemoteTracking selected, so does remote_views. The Git ref mirrors git_refs and git_heads always come from the current view (RevertWhatToRestore). MutableRepo::set_view installs it un-normalized (source), and the transaction commits it as usual.

Guards

• Other workspaces. An operation records the workspace it ran in. Undoing another workspace's operation would usually surprise you, so it needs --allow-cross-workspace. Operations with no recorded workspace pass the check (source).
• Pushes. Undoing a push … operation (is_push_operation) restores remote-tracking bookmarks to their pre-push positions, while the remote keeps the pushed ones. That's why it warns that the bookmarks will often end up conflicted.
• Workspace removal. The workspace's entry in the view comes back, but its directory on disk doesn't.
• Shape. The root operation has nothing to restore. A merge operation, created when concurrent operations are reconciled, has no single "before", so jj points you to op restore.

Invariants: undo is append-only, because it always adds an operation and never deletes one. Undo can itself be undone (jj redo, or jj op restore to the undo's parent). No commit is ever destroyed. Repeated undos step back monotonically through the non-undo history, without building chains.

7. Errors and edge cases

Upstream's tests cover the root case, including the missing-workspace warning on the first undo (source), the merge case, created with --at-op (source), and the push warning (source).

8. Worked example

undo moves through operations, not commits, so this example draws the operation log. It is upstream's test_jump_over_old_undo_stack. Each of operations A–D writes its own letter to a file named state and snapshots. The test then runs undo, undo, writes and snapshots E and F, and runs undo three more times. After each command it checks the file.

The test asserts the file reads C, then B, then E, B and A. The fourth undo is the interesting one. Its target is E, the operation undo 3 restored, and E's parent is undo 2. Rather than restore undo 2, it restores what undo 2 restored, B. The old stack (undo 1, undo 2, C, D) is jumped over, so the fifth undo goes straight from B to A.