How jj abandon works

In short: jj resolves the revisions (default @), keeps only the visible ones, and refuses if any is immutable. One transform_descendants_with_options walk records each target as abandoned onto its (possibly rewritten) parents. It rebases every other descendant, or with --restore-descendants, reparents it so its content stays the same. Bookmarks are then updated, which by default means deleting the abandoned commits' bookmarks. If @ was abandoned, a new empty @ is created on its parents. One operation, abandon commit <id>, records it all. The commits still exist in the store, and jj undo brings them back.

The command is cmd_abandon. Its help text compares it with jj restore --changes-in, which removes the same changes but keeps the change rather than giving you a new one (source). The same "abandoned commit" machinery runs whenever another command empties a commit: squash sources, rebase --skip-emptied, and the empty working-copy commit edit and new leave behind.

1. Command-line surface

AbandonArgs

2. Configuration

jj abandon reads no settings of its own. revset-aliases."immutable_heads()" decides what check_rewritable_expr refuses, so the root commit and anything immutable can't be abandoned. user.name/user.email become the committer of rebased descendants. For the "push deleted bookmarks" hint, the default remote that jj ignores when looking for tracked bookmarks is git on Git-backed repositories (has_tracked_remote_bookmarks).

3. End-to-end flow

4. Core architecture touchpoints

5. Transaction and operation

• Transaction: one, only if at least one visible commit is to be abandoned (source).
• Operation description (source): abandon commit <id> or abandon commit <id> and <n> more. The ID is formatted with Display, which writes the full hex (core/src/object_id.rs). It is the first target in evaluation order, which puts children first.
• Commits created or rewritten: none are created, except a replacement @ when @ is abandoned. Every descendant of a target is rewritten.
• Working copy: snapshotted first, so abandoning @ abandons your latest edits too. The new @'s tree, the merge of its parents, is then checked out.
• jj undo restores the previous view, which brings back the abandoned commits, their bookmarks and the old descendants. Nothing was deleted from the store.

6. Algorithm and invariants

Choosing the targets

The revsets are unioned, then intersected with ::visible_heads() (source). A revset can name hidden commits, for example by full commit ID. Those are counted and reported as skipped rather than abandoned again (source). The immutability check runs only on the visible part.

One walk over the descendants

Everything happens in one call to transform_descendants_with_options rooted at the targets (source). It visits the targets and all their descendants, parents first. Each visit gets a CommitRewriter whose new parents already reflect earlier visits. So when a target's parent was itself abandoned, the new parents are that parent's parents, and chains of abandoned commits collapse correctly.

• Target: rewriter.abandon() records Abandoned(new parents) without writing anything. Later commits that had it as a parent get those parents instead.
• Other descendant, default: rebase() merges new base + (tree − old base). The abandoned changes therefore vanish from every descendant, and a descendant that built on them may now conflict.
• Other descendant, --restore-descendants: reparent() keeps the tree as it was. Its diff against the new parent now includes the abandoned changes, as if they'd been squashed into it.

Bookmarks and the working copy

At the end of the walk, update_rewritten_references runs with RewriteRefsOptions { delete_abandoned_bookmarks: !retain_bookmarks } (source). update_local_bookmarks sets a bookmark on an abandoned commit to absent. With --retain-bookmarks, it builds a new target from the new parents with the old commit interleaved as the "removed" side. When the abandoned commit was a merge, that means the bookmark becomes conflicted across both parents, shown as e?? in the upstream test below. The command then diffs the old and new bookmark tables to list what was deleted (source). update_wc_commits gives a workspace whose @ was abandoned a new empty commit on the new parents, with their merged tree.

Invariants: nothing is deleted from storage, so the operation is fully undoable. Every descendant survives, rebased or reparented, and none is abandoned implicitly. The root commit and immutable commits can't be abandoned. Abandoned changes don't vanish under --restore-descendants; they move into the children.

7. Errors and edge cases

8. Worked example

From upstream's test_basics. b is on a, d is on c, and e (@) merges a and d. Each commit has a bookmark of its own name and adds a file of that name. Run jj abandon 'descendants(d)':

Upstream's snapshot of the output:

Abandoned 2 commits:
  znkkpsqq 03e0d4bf e | e
  vruxwmqv 636920e4 d | d
Deleted bookmarks: d, e
Working copy  (@) now at: xtnwkqum 1c70f4d2 (empty) (no description set)
Parent commit (@-)      : rlvkpnrz 7d980be7 a | a
Parent commit (@-)      : royxmykx c12952d9 c | c
Added 0 files, modified 0 files, removed 2 files

e is listed first because it comes first in evaluation order, so the operation is abandon commit 03e0d4bf… and 1 more. d was abandoned onto c. When the walk reached e, its new parents were already a and c, so the replacement @ merges those two. The same test shows the bookmark variants. jj abandon --retain-bookmarks d moves bookmark d onto c. Abandoning the merge e with --retain-bookmarks leaves bookmark e conflicted between a and d, shown as a e?? and d e??.