Menu
Jujutsu workflow summary with essential paradigm shifts and decision guide. Reference for quick jj orientation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | jj-summary |
| description | Jujutsu workflow summary with essential paradigm shifts and decision guide. Reference for quick jj orientation. |
Quick reference and decision guide for jj version control. Full documentation: ~/.claude/skills/jj-workflow/SKILL.md
Read specific sections of jj-workflow.md when:
jj-version-control/tiered-ceremony.md for the three-tier model and jj-version-control/SKILL.md for development-join mechanicsjj-version-control/tiered-ceremony.md "Workspaces are not a tier" and jj-workflow/SKILL.md "Graduating to workspaces"For quick questions about commands or concepts, this summary may suffice.
Core differences:
@) that's automatically snapshottedMental model shift:
Commands that launch editors by default (WILL HANG without proper flags):
| Command | Default behavior | Non-interactive pattern |
|---|---|---|
jj describe | Opens editor | jj describe -m "message" |
jj describe -r <c> | Opens editor | jj describe -r <c> -m "message" |
jj split <paths> | Opens editor twice (extracted + remainder) | jj describe -m "<remainder>" first, then jj split <paths> -m "<extracted>" — see jj-workflow "Common gotchas" for the multi-boundary rule |
jj split (no paths) | Opens diff editor (TUI) | Cannot be non-interactive |
jj squash --into <dest> | Opens description merge editor | jj squash --into <dest> -u (keep dest description) or -m "msg" |
jj squash --from @ --insert-after <tip> / --insert-before <revset> (create mode) | Opens editor for the new commit's description when neither -m nor -u is supplied | always pass -m "msg" (and --keep-emptied so @ returns to empty [wip]) |
Mandatory verification protocol:
jj [subcommand] --help FIRST-m, --message <MESSAGE> flag-m, ALWAYS use it to avoid editor launchFor 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:
@ exists only in .jj/ until frozen@ appears as uncommitted working directory changesjj describe -m "msg" → jj new → commit now visible in gitjj new, described commits remain invisible to git operationsWorking copy commit (@):
jj describe -m "message" to add description when cohesive (ALWAYS use -m)jj new to freeze @ and create new empty @ on topjj new after jj describe for git visibilityBookmarks:
jj bookmark set <name> -r <commit>Change IDs vs Commit IDs:
Operation log:
jj undo reverses any operationjj op restore <id> returns to exact prior stateRevsets:
main..@, mine() & ~bookmarks(), description(glob:"WIP*")jj squash -r 'empty() & main..@'# 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: Core philosophy (lines 1-16 of jj-workflow.md)
Section: Automatic snapshotting preferences (lines 18-34)
Section: Foundation - Atomic commit workflow (lines 36-110)
@ rewriting, bookmark management, undo/restore patternsSection: Parallel experimentation with bookmarks (lines 112-176)
Section: Graduating to workspaces (lines 178-243)
Section: Experiment lifecycle management (lines 245-372)
Section: History refinement (lines 374-557)
Section: Advanced patterns (lines 559-643)
Section: Git colocated mode (lines 645-713)
Section: Reference (lines 715-1045)
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
# 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()'
-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 firstjj [subcommand] --help to check for interactive flags (look for -m, --message)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 gitjj 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.jj op log and jj op restore insteadjj bookmark set, don't assume movement[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.Which tier of ceremony does this work warrant? (See jj-version-control/tiered-ceremony.md for the full policy.)
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.
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.
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.
<base> below all chains → splice-below-join (see ~/.claude/skills/jj-version-control/SKILL.md §"Splice-below-join")<base> advanced during diamond work → diamond integration on remote advance (see ~/.claude/skills/jj-version-control/SKILL.md §"Diamond integration on remote advance")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?
jj-version-control/tiered-ceremony.md tier 3~/.claude/skills/jj-version-control/SKILL.md for mechanics and tiered-ceremony.md for the policy.Should I use jj or git for this operation?
~/.claude/skills/jj-workflow/SKILL.md~/.claude/skills/jj-version-control/SKILL.md~/.claude/skills/preferences-git-version-control/SKILL.mdIndex curated reference corpora into a searchable knowledge graph via the cognee engine, then query it to ground technical writing, review, and analysis. Use when ingesting reference documents into named datasets or retrieving grounding context for tasks like drafting or reviewing a manuscript. A reference-knowledge index, explicitly not agent session memory.
Nix development conventions for flakes, derivations, modules, and code style. Use when authoring flake.nix files, writing derivations or builders, designing NixOS/nix-darwin/home-manager modules, or following nix formatting and naming conventions. For check architecture and CI integration, see preferences-nix-checks-architecture and preferences-nix-ci-cd-integration.
Approximately-verifiable, refinement-driven development for type-driven domain-driven design. Use when modeling a domain as a dependently-typed Lean 4 specification, refining/lowering it to a Rust implementation, lifting the implementation back via Charon and Aeneas to check spec<->implementation correspondence (translation validation) — mechanically when tractable, otherwise via differential testing or LLM comparison — or when generating and diffing type-system diagrams of the model and implementation to track their evolution. Mechanical on-the-nose proof is the precise ideal, not a requirement; its absence is not a failure of the method.
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
Algebraic data type patterns including sum types, product types, and pattern matching across languages. Load when designing type hierarchies or working with discriminated unions.
Algebraic laws including functor/monad laws and property-based testing strategies. Load when verifying algebraic properties or writing property tests.