jj-summary

name: jj-summary description: Jujutsu workflow summary with essential paradigm shifts and decision guide. Reference for quick jj orientation.

Jujutsu workflow summary

Quick reference and decision guide for jj version control. Full documentation: ~/.claude/skills/jj-workflow/SKILL.md

When to read full documentation

Read specific sections of jj-workflow.md when:

• First time with jj: Read "Core philosophy" and "Foundation" sections
• Starting parallel experiments: Read "Parallel experimentation with bookmarks"
• Multiple parallel work streams: Read jj-version-control/tiered-ceremony.md for the three-tier model and jj-version-control/SKILL.md for development-join mechanics
• User explicitly requests workspace isolation: Read jj-version-control/tiered-ceremony.md "Workspaces are not a tier" and jj-workflow/SKILL.md "Graduating to workspaces"
• Managing multiple experiments: Read "Experiment lifecycle management"
• Cleaning up history: Read "History refinement"
• Integration strategies: Read "Advanced patterns"
• Git interop questions: Read "Git colocated mode"
• Command lookup: Read "Reference" section

For quick questions about commands or concepts, this summary may suffice.

Essential paradigm shifts (git → jj)

Core differences:

• Working copy is always a commit (@) that's automatically snapshotted
• Bookmarks don't move when you commit (only when commits are rewritten)
• No "current branch" - always in detached HEAD equivalent state
• Change IDs provide stable identity (commit IDs change, change IDs persist)
• Operation log is real history (commits are snapshots, operations are timeline)
• No staging area (working copy state is commit state)
• Conflicts are committed (resolved when convenient, never blocking)

Mental model shift:

• Git: "I'm working on branch X" → jj: "I'm building commit chain from X"
• Git: "Branch moves when I commit" → jj: "@ is rewritten when I change files"
• Git: "Switch branch to work elsewhere" → jj: "Create new @ anywhere"
• Git: "Branches are history" → jj: "Operation log is history"

Non-interactive execution for AI agents

Commands that launch editors by default (WILL HANG without proper flags):

Mandatory verification protocol:

1. Not certain a command is non-interactive? → Run jj [subcommand] --help FIRST
2. Check help output for -m, --message <MESSAGE> flag
3. If command accepts -m, ALWAYS use it to avoid editor launch

For untrusted call sites or in-flight hang recovery, see jj-workflow "Escape hatches for interactive operations" — covers the JJ_EDITOR=true belt-and-suspenders pattern and the SIGTERM + jj op restore recovery procedure.

Git parity requirement:

• jj working copy @ exists only in .jj/ until frozen
• From git's perspective, @ appears as uncommitted working directory changes
• Pattern: jj describe -m "msg" → jj new → commit now visible in git
• Without jj new, described commits remain invisible to git operations

Critical jj concepts

Working copy commit (@):

• Ephemeral commit constantly rewritten as you work
• Auto-snapshotted before each jj command
• Use jj describe -m "message" to add description when cohesive (ALWAYS use -m)
• Use jj new to freeze @ and create new empty @ on top
• Git export: @ is jj-only until frozen; execute jj new after jj describe for git visibility

Bookmarks:

• Named pointers that stay put when you create commits
• Only move when commits are rewritten (rebase, squash, abandon)
• Update explicitly: jj bookmark set <name> -r <commit>
• Multiple workspaces can work near same bookmark (no exclusive ownership)

Change IDs vs Commit IDs:

• Commit ID: changes with every rewrite (like git SHA)
• Change ID: stable across rewrites (tracks logical change)
• Use change IDs to track "same change" through rebase/amend

Operation log:

• Every jj operation recorded atomically
• jj undo reverses any operation
• jj op restore <id> returns to exact prior state
• Safety net replaces backup branches

Revsets:

• Query language for selecting commits (like SQL for commits)
• Examples: main..@, mine() & ~bookmarks(), description(glob:"WIP*")
• Operate on multiple commits: jj squash -r 'empty() & main..@'

Quick command reference

# Atomic commit cycle (one file per change, matching git-preferences conventions)
# Edit ONE file, then immediately:
jj describe -m "message"       # Describe current @ (ALWAYS use -m!)
jj new                         # Freeze @, start new empty @
# Repeat for next file. Without `jj new`, the next edit accumulates into the same change.
# If multiple files were edited before freezing, split after the fact:
jj split <path> -m "msg"       # Extract one file into its own change

# Bookmarks
jj bookmark create <name>      # Create at @
jj bookmark set <name> -r <c>  # Move bookmark

# Move changes
jj squash                      # Move @ into parent
jj squash -r <commit>          # Squash commit into parent
jj split <paths> -m "message"  # Split @ by paths (REQUIRES -m!)
jj absorb                      # Auto-distribute @ to ancestors

# Rewrite history
jj rebase -r <c> -d <dest>     # Move commit to new parent
jj abandon <commit>            # Remove commit, rebase descendants
jj describe -r <c> -m "msg"    # Reword commit (ALWAYS use -m!)

# Workspaces
jj workspace add <path> -r <c> # Create workspace
jj workspace update-stale      # Update stale workspace

# Note: the `jj describe @` + `jj new` cycle above is for SINGLE-CHAIN (tier 1) work, where `@` becomes content.
# In a development join (tier 3), `@` is the shared empty [wip] directly atop the join — do NOT `jj describe @`
# into content and do NOT `jj rebase -r @` positionally; route DOWN via `jj squash --from @ ... --keep-emptied`,
# `jj absorb`, or `jj split` (keeping the wip), which leave `@` in place and empty.
# Multi-parent development join (composite working copy)
jj new bm-a bm-b bm-c         # Join multiple chains into one working tree
jj describe -m "join: bm-a + bm-b + bm-c"  # Describe the development join
jj new                         # Create wip commit on top of the join
# Work in wip, then route changes to the appropriate chain:
jj squash --into <chain> -u -- <path>     # Manual routing (keeps dest description)
jj absorb                      # Auto-route changes by blame
# Route-and-extend: create a NEW commit on a chain (not amend existing); @/[wip] never drifts below the join
jj new -A <bookmark> --no-edit -m "feat: msg"   # Insert empty commit after bookmark; --no-edit keeps @ on [wip]
jj squash --from @ --into <id> --keep-emptied -- <path>  # Route file content into it; --keep-emptied preserves @ in place (NOT -u alone: -u only sets the dest description)
jj bookmark set <bookmark> -r <id>        # Advance bookmark to new tip (use the printed Created-new-commit id, not @-)
# `@` stays an empty [wip] on the join. `jj describe -m ""` (empty message ONLY) may clear a stale wip description; never `jj describe @ -m "<content>"`.
# Route-and-extend multi-commit-range form: relocate an N-commit linear segment into a chain
jj rebase --revisions '<range-start>::<range-end>' --insert-after <chain-tip>
jj bookmark set <chain-bookmark> -r <range-end>
# See ~/.claude/skills/jj-version-control/SKILL.md §"Extending a chain with a new commit (route-and-extend pattern)" → Multi-commit-range form
# Add/remove chains dynamically:
jj rebase -r @ -d 'all:(@- | new-bm)'    # Add chain to the development join
jj rebase -r @ -d 'all:(@- ~ old-bm)'    # Remove chain from the development join

# Splice-below-join: insert a <base>-bound commit between <base> and chain roots
# By-construction: author a new splice commit in position
jj new --insert-before 'children(fork_point(parents(<join>))) & ::<join>' -m "msg"
# To route content currently in @/[wip] below the join, use the @-PRESERVING form (never moves @):
jj squash --from @ --insert-before 'children(fork_point(parents(<join>))) & ::<join>' \
  -m "fix(scope): description" --keep-emptied -- <paths>
# By-relocation: ONLY for a SEPARATE, already-sealed NON-wip commit that already exists above the join.
# `<separate-sealed-non-wip-commit>` MUST NOT be `@`/[wip]; NEVER `jj describe @` then relocate it — that destroys the shared [wip].
# Precondition (by-relocation only): relocation set's files must be disjoint from any chain's files
# (skill/aggregator files frequently collide; on collision use route-and-extend or new-chain instead)
jj rebase --revisions <separate-sealed-non-wip-commit> --insert-before 'children(fork_point(parents(<join>))) & ::<join>'
# See ~/.claude/skills/jj-version-control/SKILL.md §"Splice-below-join"

# Diamond integration on remote advance: rebase diamond onto fast-forwarded remote
jj git fetch
jj rebase --source 'roots(<base>@origin..@)' --destination '<base>@origin'
jj bookmark set <base> -r '<base>@origin'
# See ~/.claude/skills/jj-version-control/SKILL.md §"Diamond integration on remote advance"

# Diamond-health diagnostic (surfaces all five diamond invariants in one view)
jj log -r 'present(@) | ancestors(immutable_heads().., 2) | trunk()'

# Recovery
jj undo                        # Undo last operation
jj op log                      # View operation history
jj op restore <id>             # Restore to operation

# Git interop (colocated mode)
jj git init --colocate         # Initialize in existing git repo
jj git fetch                   # Fetch from remote
jj git push --bookmark <name>  # Push bookmark

Section index with triggers

Section: Core philosophy (lines 1-16 of jj-workflow.md)

• Read when: First time using jj, need paradigm explanation
• Covers: Fundamental differences from git, mental model shifts
• Key concepts: Auto-snapshotting, operation log, no special modes

Section: Automatic snapshotting preferences (lines 18-34)

• Read when: Configuring commit behavior, understanding preferences
• Covers: When to commit automatically, escape hatches
• Key concepts: Trust operation log, no staging area

Section: Foundation - Atomic commit workflow (lines 36-110)

• Read when: Learning basic jj workflow, single-workspace development
• Covers: Working copy commit behavior, bookmarks, operation log, conflicts
• Key concepts: @ rewriting, bookmark management, undo/restore patterns

Section: Parallel experimentation with bookmarks (lines 112-176)

• Read when: Starting multiple experiments, comparing approaches
• Covers: Bookmark-based experiments, revset queries, checkpointing
• Key concepts: Single workspace with multiple bookmarks, exp-N naming

Section: Graduating to workspaces (lines 178-243)

• Read when: Need simultaneous file access, parallel builds/tests
• Covers: When to create workspaces, workspace lifecycle, stale handling
• Key concepts: workspace@, stale detection, cross-workspace operations

Section: Experiment lifecycle management (lines 245-372)

• Read when: Managing arbitrary N experiments, scaling patterns
• Covers: Naming conventions, revset aliases, registry, state transitions
• Key concepts: exp-N-description, docs/experiments.md, cleanup workflow

Section: History refinement (lines 374-557)

• Read when: Cleaning up commit history for review/PR
• Covers: Incremental cleanup, reorder/squash/split/reword/abandon
• Key concepts: No backup branches needed, jj undo at any step

Section: Advanced patterns (lines 559-643)

• Read when: Integrating experiments, handling dependencies
• Covers: Integration strategies (rebase/squash), sequential linearization, sub-experiments
• Key concepts: Stacking experiments, feature flags, session patterns

Section: Git colocated mode (lines 645-713)

• Read when: Working with existing git repos, git interop questions
• Covers: Initialization, remote sync, reverting to git-only
• Key concepts: .git and .jj coexist, automatic import/export

Section: Reference (lines 715-1045)

• Read when: Looking up revset syntax, command patterns
• Covers: Essential revset patterns, common commands, session summaries
• Key concepts: Comprehensive command reference, revset operators

Common workflow patterns (compressed)

Single-workspace experimentation:

jj bookmark create exp-1 -r main
jj new exp-1
# Work on changes (auto-snapshotted)
jj describe -m "[exp-1] feat: implement feature"  # ALWAYS use -m
jj new                         # Freeze for git, start new @ on top
jj bookmark set exp-1 -r @-    # Checkpoint (point to frozen commit)
jj git push --bookmark exp-1   # Share

Create workspace for serious work:

jj workspace add ../repo-exp-1 -r exp-1
cd ../repo-exp-1
# Work with persistent files

Clean up history incrementally:

jj log -r 'main..@'                    # Review
jj squash -r 'description(glob:"WIP*")' # Remove WIP
jj abandon 'empty()'                    # Remove empty
jj rebase -r <commit> -d <parent>      # Reorder
jj describe -r <commit> -m "proper"    # Reword
jj undo                                # Undo any mistake

Integrate experiment to main (linear history only, no merge commits):

# Option 1: Rebase single chain (preserve commits)
jj rebase -s 'main..exp-1' -d main
jj bookmark set main -r exp-1

# Option 2: Squash single chain (single commit)
jj new main
jj squash --from 'main..exp-1' --into @
jj bookmark set main -r @

# Option 3: Sequential linearization of multiple chains from a development join
# Rebase each chain onto main one at a time, advancing main after each.
# Order chains by dependency (independent chains first, dependents after).
jj rebase -s 'roots(main..feature-a)' -d main
jj bookmark set main -r feature-a
jj rebase -s 'roots(main..feature-b)' -d main
jj bookmark set main -r feature-b
# Repeat for each chain. Never create merge commits for integration to main.

Development join (simultaneous multi-bookmark editing):

In a development join, @ is the shared empty [wip] directly atop the join and the SHARED editing surface for all concurrent editors; do NOT jj describe @ into content and do NOT jj rebase -r @, route DOWN via jj squash --from @ ... --keep-emptied, jj absorb, or jj split (keeping the wip). The describe+new cycle taught earlier is for SINGLE-CHAIN (tier 1) work only.

# Join multiple chains into one working tree
jj new feature-a feature-b feature-c
jj describe -m "join: feature-a + feature-b + feature-c"
jj new                            # Create wip commit on top of the join
# Work in wip, then route changes to the appropriate chain:
jj squash --into feature-a -u -- <path>  # Manual routing (keeps dest description)
jj absorb                         # Auto-route by blame
# IMPORTANT: `jj squash --into` AMENDS the existing chain tip.
# To CREATE a new commit extending the chain (route-and-extend), `@`/[wip] stays the empty wip throughout —
# never `jj describe @` into content, never `jj rebase -r @`:
# jj new -A <bookmark> --no-edit -m "msg"          # insert new empty commit after tip; --no-edit keeps @ on [wip]
# jj squash --from @ --into <new-id> --keep-emptied -- <path>  # route content; --keep-emptied preserves empty [wip]
# jj bookmark set <bookmark> -r <new-id>           # advance bookmark to new tip
# No description-recovery step is needed; [wip] is ephemeral.
# See jj-version-control/SKILL.md §"Extending a chain with a new commit (route-and-extend pattern)".
# Add/remove chains dynamically:
jj rebase -r @ -d 'all:(@- | new-bookmark)'   # Add chain
jj rebase -r @ -d 'all:(@- ~ old-bookmark)'   # Remove chain

Diamond workflow (epic-scoped, four phases):

The diamond connects a beads epic graph to jj chain topology via diverge, develop, converge, serialize. Canonical recipe: ~/.claude/skills/jj-version-control/diamond-workflow.md.

# Pre-edit recon: which chain (if any) already touched this file?
PAGER=cat jj log -r 'fork_point(@--)..@- & files("<path>")' \
    --no-graph -T 'change_id.short() ++ " " ++ bookmarks ++ " " ++ description.first_line() ++ "\n"'

# Develop phase: N-way development join + wip (tactical example)
jj new chain-a chain-b chain-c
jj describe -m "join N=3: chain-a, chain-b, chain-c"
jj new                                                   # wip on top
jj squash --from @ --into <chain> -m "feat: desc"        # route changes

Revset examples for experiments

# All experiments
jj log -r 'main..'

# Specific experiment
jj log -r 'main..exp-1@'

# Compare experiments (unique to exp-1)
jj log -r '(main..exp-1@) ~ (main..exp-2@)'

# Shared between experiments
jj log -r '(main..exp-1@) & (main..exp-2@)'

# All working-copy commits
jj log -r 'working_copies()'

# Your unbookmarked work
jj log -r 'mine() & ~bookmarks()'

Critical reminders

• Non-interactive execution: ALWAYS use -m "message" with jj describe, jj describe -r, and jj split <paths> to avoid editor hangups; use -u or -m with jj squash --into to prevent the description merge editor; the development-join append-route jj squash --from @ --insert-after/--insert-before is create-a-new-commit mode and opens an editor without -m/-u, so always pass -m and --keep-emptied so @ stays an empty [wip]; verify unfamiliar commands with jj [subcommand] --help first
• Command verification protocol: Before executing any jj command you're uncertain about, run jj [subcommand] --help to check for interactive flags (look for -m, --message)
• Git parity requirement: Execute jj new immediately after jj describe -m "msg" to freeze commits for git export; without jj new, described commits exist only in jj and appear as uncommitted changes in git
• Always colocated mode: We operate with both .git and .jj (can revert to git anytime)
• Operation log is safety net: Delete bookmarks freely, everything in operation log
• Start with bookmarks: Only create workspaces when need simultaneous file access
• Describe atomically: Each jj describe + jj new cycle should represent one logical change to one file — this is a standing directive matching the git-preferences atomic commit convention. Use jj split to fix up if you forgot.
• Trust auto-snapshot: Changes saved before every command, recoverable via operation log
• Change IDs track identity: Commit IDs change on rewrite, change IDs don't
• No backup branches: Use jj op log and jj op restore instead
• Bookmarks stay put: Explicitly move with jj bookmark set, don't assume movement
• @ is ephemeral: Working copy commit constantly rewritten, bookmark @ parent not @
• @ stays empty [wip] in a development join: when a multi-parent join exists, @ is the empty [wip] directly atop [merge] and the SHARED editing surface for all concurrent editors. Never jj describe @ into a content commit and never jj rebase -r @ / jj rebase --revisions @ — both drift @ off [wip], vanish the shared coordination point, break the join's one-child invariant (vi), and (in this repo) drag the pushed wip deploy bookmark. Route DOWN into the owning chain via jj squash --from @ … --keep-emptied, jj absorb, or jj split (keeping the wip). Canon: ~/.claude/skills/jj-version-control/SKILL.md §development join / invariants (iii-b)/(vi), and diamond-workflow.md.
• Conflicts are first-class: Committed and resolved when convenient, never blocking
• Detached HEAD is normal: In a jj-colocated repo, detached HEAD is the expected state. Do not attempt to reattach HEAD or "fix" this.

Quick decision tree

Which tier of ceremony does this work warrant? (See jj-version-control/tiered-ceremony.md for the full policy.)

1. Single-chain work with low verification severity (atomic local changes safe to land on the trunk, covered adequately by just check-fast)? → Tier 1: anonymous chain on @. No bookmark beyond trunk, no PR; advance and push via jj bookmark move main --to @- then jj git push --bookmark main.

2. Need PR/CI validation via buildbot flake checks (multi-platform fleet matrix, large change benefiting from unified PR review, or fleet-wide gate before trunk)? → Tier 2: single named bookmark created retroactively on the chain. jj bookmark create <name> -r <change-id> then jj git push --bookmark <name> --allow-new; follow ~/.claude/skills/nix-flake-pr-cycle/SKILL.md.

3. Multiple independent work streams in flight (multiple beads issues within an epic, parallel agent dispatch, parallel experiments to compose)? → Tier 3: diamond workflow via development join over the chains' bookmarks. jj new <existing-bookmark> <new-bookmark> -m "join N=2: <alphabetical bookmarks, comma-separated>"; route edits via jj squash --from @ --into <tip> -u plus jj bookmark move <name> --to <tip>, and rewrite the [merge] description in full whenever the parent set changes so it always reflects the current join N=<cardinality>: <alphabetical bookmarks> state.

   • Mid-diamond commit belongs on <base> below all chains → splice-below-join (see ~/.claude/skills/jj-version-control/SKILL.md §"Splice-below-join")
   • Remote <base> advanced during diamond work → diamond integration on remote advance (see ~/.claude/skills/jj-version-control/SKILL.md §"Diamond integration on remote advance")

4. Did the user explicitly request workspace isolation (utterance naming worktree, workspace, isolate, separate working copy, or path forms like .worktrees/X)? → jj workspace add <path> -r <change> mechanics; otherwise stay at tier 3 and parallelize via the development join in a single working copy. In jj mode, EnterWorktree, ExitWorktree, and Task dispatches with isolation: "worktree" are hook-blocked by gate-worktree-surfaces; parallel work uses the diamond development join, not worktrees. The explicit-workspace path is jj workspace add and applies only when the user names workspace isolation specifically.

Should I read jj-workflow.md?

1. Never used jj? → Read "Core philosophy" and "Foundation"
2. Need parallel experiments? → Read "Parallel experimentation" and jj-version-control/tiered-ceremony.md tier 3
3. User explicitly requested workspace isolation? → Read "Graduating to workspaces"
4. Working on 2+ independent chains? → Tier 3 development join over per-chain bookmarks; see ~/.claude/skills/jj-version-control/SKILL.md for mechanics and tiered-ceremony.md for the policy.
5. Cleaning history? → Read "History refinement"
6. Integrating work? → Read "Advanced patterns"
7. Just need command? → Check "Quick command reference" above or "Reference" section

Should I use jj or git for this operation?

• History editing (rebase, squash, reorder)? → jj (more powerful, safer)
• Basic operations (commit, view log)? → jj (automatic snapshotting)
• Git-specific tools (e.g., GitHub CLI)? → git (works fine in colocated mode)
• Uncertain? → jj (can always undo with operation log)

For full documentation

• Full jj workflow reference: ~/.claude/skills/jj-workflow/SKILL.md
• Development join workflow, beads integration: ~/.claude/skills/jj-version-control/SKILL.md
• VCS mode detection, beads conventions: ~/.claude/skills/preferences-git-version-control/SKILL.md