jj

Jujutsu is a Git-compatible VCS with mutable commits, automatic change tracking, and an operation log that makes every action undoable.

Target version: jj 0.36+

Topics

| I need to... | Deep dive | |--------------|-----------| | Understand how jj relates to Git, or use raw git in a jj repo | git-compatibility.md | | Write revset, fileset, or template expressions | revsets.md | | Push, pull, manage bookmarks, or work with GitHub | bookmarks.md | | Split, rebase, squash, or resolve conflicts | conflicts.md | | Run parallel agents with isolated working copies | parallel-agents.md | | Configure jj, set up aliases, or customize diffs | config-reference.md |

Mental Model

The working copy is a commit. No staging area. Every file change is auto-snapshotted into @ when you run any jj command. Instead of "stage → commit," just code and describe.

Change IDs are stable. Commit IDs are not. Every commit has two identifiers:

• Change ID — Stable across rewrites. Letters k–z (e.g., tqpwlqmp). Prefer these.
• Commit ID — Content hash, changes on any rewrite. Hex digits. This is the Git commit ID in colocated repos.

History is mutable. Commits can be freely rewritten. Descendants auto-rebase. Old versions stay in the operation log.

Bookmarks are not branches. Bookmarks don't advance when new commits are created. They follow rewrites but must be explicitly set before pushing. → Deep dive: bookmarks.md

Conflicts don't block. jj allows committing conflicted files. Resolve at your convenience by editing conflict markers directly, then verify with jj st. → Deep dive: conflicts.md

Agent Rules

Non-negotiable when operating as an automated agent:

1. Always use -m for messages. Never invoke a command that opens an editor. Commands that need -m: jj new, jj describe, jj commit, jj squash.
2. Never use interactive commands. jj split (without file paths), jj squash -i, jj resolve — all hang. Use file-path args or jj restore workflows.
3. Verify after mutations. Run jj st after squash, abandon, rebase, restore, or any destructive op.
4. Use change IDs, not commit IDs. Change IDs survive rewrites.
5. Quote revsets. Always single-quote: jj log -r 'mine() & ::@'.

Agent-Specific Configuration

# agent-jj-config.toml
[user]
name = "Agent"
email = "agent@example.com"

[ui]
editor = "TRIED_TO_RUN_AN_INTERACTIVE_EDITOR"
diff-formatter = ":git"
paginate = "never"

Launch with: JJ_CONFIG=/path/to/agent-jj-config.toml <agent-harness> → Deep dive: config-reference.md

Core Workflow

The daily loop: describe → code → new → repeat.

jj describe -m "feat: add user validation"
# make changes — auto-tracked, no `add` needed
jj st && jj diff
jj new -m "feat: add error handling"

Curating History

jj squash -m "feat: final clean message"   # fold working copy into parent
jj absorb                                   # auto-distribute hunks to right ancestor
jj abandon @                               # drop a failed experiment

→ Deep dive: command-gotchas.md

Non-Linear Work

When new work doesn't depend on the current chain, branch off trunk:

# Create sibling from trunk (doesn't move @)
jj new trunk() --no-edit -m "fix: correct timezone handling"
jj edit <bugfix-change-id>
# ... fix the bug ...

# Return to original work
jj log -r 'heads(trunk()..)'
jj edit <feature-change-id>

Agent rule: Before creating a new commit, decide if it depends on the current chain. If not, branch off trunk and flag the divergence to the user.

Pushing Changes

jj bookmark set feat -r @
jj git push -b feat

Bookmarks must be set before pushing — they don't auto-advance. → Deep dive: bookmarks.md

Essential Commands

| Task | Command | |------|---------| | Check status | jj st | | View diff / log | jj diff / jj log | | Describe current commit | jj describe -m "message" | | Start new work | jj new -m "task description" | | Edit an older commit | jj edit <change-id> | | Squash into parent | jj squash | | Auto-distribute changes | jj absorb | | Abandon a commit | jj abandon <change-id> | | Undo last operation | jj undo | | View operation history | jj op log | | Restore to earlier state | jj op restore <op-id> | | Create/move bookmark | jj bookmark create <n> -r @ / jj bookmark set <n> -r @ | | Push / fetch | jj git push -b <bookmark> / jj git fetch |

For Git translations: references/git-to-jj.md

Recovery

jj undo                      # undo last op; repeatable
jj op log                    # full operation history
jj op restore <op-id>        # jump to any past state
jj evolog -r <change-id>     # see how a change evolved

Detecting a jj Repo

.jj/ directory = jj repo. Both .jj/ and .git/ = colocated repo. Always use jj commands. Git's "detached HEAD" is normal in colocated repos — use jj log for real state.

Common Mistakes

| Mistake | Fix | |---------|-----| | Omitting -m on commands | Always pass -m — editor hangs agents | | Using jj split without file paths | Provide paths or use the jj restore workflow | | Forgetting to set bookmark before push | jj bookmark set <name> -r @ first | | Using commit IDs instead of change IDs | Change IDs (letters k–z) survive rewrites | | Unquoted revset expressions | Always single-quote: 'mine() & ::@' | | Confusing :: vs .. operators | :: = ancestry path, .. = range (see revsets.md) | | Creating workspaces as subdirectories | Must be sibling dirs, not children |

Reference Index

Git Interop:

• references/git-to-jj.md — Git-to-jj command mapping
• references/git-experts.md — Why jj improves on Git
• references/git-compatibility.md — Git interop and colocated repos

Commands:

• references/command-gotchas.md — Flag semantics, quoting, deprecated flags

Revsets & Templates:

• references/revsets.md — Complete revset language spec
• references/filesets.md — Complete fileset language spec
• references/templates.md — Complete template language spec

Sharing:

• references/bookmarks.md — Complete bookmarks reference
• references/github.md — GitHub/GitLab workflow details

History:

• references/conflicts.md — Conflict handling and marker formats
• references/divergence.md — Divergent changes guide

Config:

• references/config-reference.md — Full configuration reference

Workspaces:

• references/parallel-agents.md — Parallel agent setup guide