jujutsu
Use when planning or running version-control operations: jj for every write and history edit, git for reads only. Covers non-interactive use, side-effect-free reads (templates, filesets, past operatio
SKILL.mdhome-manager/ai-tools/agent-skills/skills/jujutsu/SKILL.md
GitHubJujutsu (jj)
A .jj/ directory at the root of the checkout you work in means jj is in use: run all version-control
operations through jj and keep GitHub operations on gh. Git is read-only; CLAUDE.md gives the rule, including
what to do when .jj/ is missing. A .worktrees/ directory under a bare repository without its own .jj/ is
not a jj workspace: jj root succeeds there but names the bare root, whose jj sees none of the directory's
files, and jj status shows no changes.
Two layouts carry .jj/:
- A non-bare clone is colocated:
.jj/and.git/share one Git object store, jj exports its changes to Git refs, and Git's HEAD is left detached. Write through jj; read-only git subcommands also work. - A bare
<repo>.git/holds jj's store at its root in an empty-sparsedefaultworkspace that tracks no files. Work happens in jj workspaces under.worktrees/, which have no.gitof their own. A gate that enumerates files through git (git ls-files, treefmt's default walker) there checks nothing and exits 0. Confirm its input count, or run it with a filesystem walk (treefmt --walk filesystem).
Local jj writes on a non-default change (commit, describe, split, squash, absorb, rebase of your own changes,
bookmark create, fetch, workspace add) need no separate authorization when the task calls for them. Push, and
any write to the default branch, need the user's confirmation; so does moving or discarding a shared working
copy (CLAUDE.md hard_rules).
Before the first commit in a repository, run jj config get user.email there and confirm the value. Jujutsu
does not read Git's conditional includeIf identity configuration.
The working copy is a commit
jj has no staging area. Repository commands normally snapshot files on disk into the working-copy revision @,
so jj status records edits as well as reporting them. In a checkout shared with other sessions, that snapshot
absorbs their edits into @ too: before describing, squashing, or pushing @, read jj diff --git and
confirm every hunk is yours. Pass --ignore-working-copy to read-only commands to avoid snapshotting shared
edits, but their view may be stale. To read on-disk state, run jj status or jj diff --git without the flag:
before committing, to separate your changes from existing ones, or at completion to confirm the changed files,
not as a routine first step.
Confirm a remote ref before relying on a fetched one: compare jj log --ignore-working-copy -r '<b>@<remote>' --no-graph -T 'commit_id' with gh api repos/<owner>/<repo>/git/ref/heads/<branch> --jq .object.sha (tags:
git/ref/tags/<tag>). A remote-tracking ref left by a fetch without explicit --remote and --branch is not
freshness evidence.
A change has a stable change ID (letters k-z) and a commit ID that changes on every rewrite. Refer to changes by change ID across rewrites.
Command map
Run only the jj column.
| Git habit | jj |
|---|---|
git status |
jj status |
git log --oneline --graph |
jj log |
git diff / git diff --cached |
jj diff --git (no staging, one diff) |
git show <rev> |
jj show --git <rev> |
git add + git commit -m |
jj commit -m "<msg>" (describes @, starts a new empty @) |
git commit --amend -m |
jj describe -m "<msg>" |
git commit --amend --no-edit (fold in edits) |
jj squash (moves @ into its parent) |
git add -p + commit (some files) |
jj split -m "<msg>" <paths> |
git commit --fixup + autosquash |
jj absorb [<paths>] |
git checkout -b <b> |
jj bookmark create <b> -r @ |
git branch -f <b> <rev> |
jj bookmark set <b> -r <rev> (-B to move it backwards or sideways) |
git fetch |
jj git fetch --remote <r> --branch <b> (always name both) |
git push origin <b> |
jj git push -b <b> (see Pushing) |
git rebase <onto> |
jj rebase -b @ -o <onto> (-o is --onto) |
git cherry-pick <sha> |
jj duplicate <rev> -o <dest> |
git revert <sha> |
jj revert -r <rev> -o @ |
git checkout -- <path> |
jj restore <path> |
git blame <file> |
jj file annotate <file> |
git reflog |
jj op log |
Non-interactive use
- Always pass
-mtojj commit,jj describe, andjj split; without it they open an editor. Forjj squash, pass-mor-u(keep the destination's message) when both sides carry descriptions. jj splitwith paths selects those files without a diff editor; without paths it opens one. Never runjj splitwithout paths,jj diffedit,jj resolvewithout--list, or any-i/--interactiveform. The guardrail hook does not catch these; an editor waiting for input hangs the call.- Add
--no-pagerto output-producing commands, and--gitto diff commands whose output will be parsed: the default diff formatter here is difftastic. - For machine-readable output, pass
--no-ext-difftogit diffso configured external diff drivers cannot alter its output. - For scripted reads,
jj log --no-graph -r <revset> -T '<template>'gives stable output.
Reading without side effects
These read the repository without moving @ or rewriting a commit. Each still snapshots the files on disk
into @ first unless you add --ignore-working-copy:
-T 'json(self) ++ "\n"'prints one JSON object per commit (change and commit IDs, parents, description, author, committer). For a narrower line, combine the keywordschange_id.shortest(),commit_id.short(),description.first_line(),bookmarks,empty,conflict,divergent, andimmutable.- Path arguments are filesets:
jj diff --git -r <rev> 'glob:"**/*.nix" & ~glob:"flake.nix"'limits a diff to the matching files. A bare path matches that file or directory relative to the current directory. jj file show -r <rev> <path>prints a file as it was in a revision, andjj file list -r <rev>lists the tracked files there. Neither touches the files on disk.jj --at-op <op> log -r <revset>shows the repository as it was after an earlier operation, without restoring it. Take<op>fromjj op log.
Editing history precisely
Each command below rewrites mutable commits and rebases their descendants automatically; none touches
immutable() commits (by default trunk(), tags, and untracked remote bookmarks) without --ignore-immutable,
which needs its own explicit request.
- Move part of a change:
jj squash --from <src> --into <dest> <paths>moves only those paths. Without paths it moves everything and abandons an emptied, undescribed source;-kkeeps it. - Distribute fixups:
jj absorbsends each hunk of@to the closest mutable ancestor that last modified those lines, and leaves a hunk in place when the destination is ambiguous. Review where every hunk went withjj op show -pbefore building on the result; move a misplaced one withjj squash --from <wrong> --into <right> <path>, since the guardrail hook blocksjj undo. - Rebase by scope:
-r <rev>moves one commit and reparents its children onto its parent;-s <rev>moves it with its descendants;-b <rev>moves the whole branch relative to the destination.-A/-Binsert instead of stacking on top. Choosing-rwhen-swas meant strands the descendants on the old base. - Reorder independent commits:
jj parallelize <a>::<b>makes a linear run into siblings. - Edit a commit other than
@: most rewrites take-r.jj describe -r <rev> -m "<msg>"rewords it,jj split -r <rev> -m "<msg>" <paths>splits it (--parallelmakes the two halves siblings), andjj squash -r <rev>folds it into its parent. - Insert without moving
@:jj new --no-edit -A <rev> -m "<msg>"creates an empty commit after<rev>and rebases<rev>'s children onto it;-Binserts before.jj new --no-edit <a> <b> -m "<msg>"creates a merge of the two.--no-editis what the guardrail hook allows: without it,jj newonto another revision moves@and is blocked. - Copy content between revisions:
jj restore --from <src> --into <dest> <paths>gives those paths in<dest>the content they have in<src>. Paths are required, as in everyjj restorethe hook allows. - Clean up merges:
jj simplify-parents -r <rev>drops a parent that is also an ancestor through another parent, without changing any content.
Recovering an earlier version
The guardrail hook blocks jj undo and jj op restore, so recover by reading the old state and rewriting
forward:
jj evolog -r <change> -p --gitlists each earlier commit of the change with its patch.jj op logandjj --at-op <op> loglocate the state before a bad operation. A rewritten commit stays addressable by its old commit ID, as a hidden commit.jj interdiff --from <old-commit-id> --to <change> --gitshows how the two versions' changes differ.jj restore --from <old-commit-id> --into <change> <paths>brings back the old content of those paths, orjj duplicate <old-commit-id> -o <dest>recreates the whole old version as a new change.
Conflicts are commits, not stops
A rebase or squash that conflicts still exits 0: jj records the conflict inside the commit and carries on,
and every descendant inherits it. An exit status is therefore no evidence a rewrite succeeded. After any
rewrite, compare the old and new tips with jj interdiff --from <old-tip> --to <new-tip> --git, then run
jj log --no-graph -r 'conflicts()' before pushing. The conflict query must print nothing. In a clean @,
jj resolve --list exits 2 with "No conflicts found", so its nonzero exit is the passing result there.
When @ is the conflicted commit, edit the conflict markers in the files directly and the next snapshot
records the resolution. When the conflict sits in an ancestor, jj suggests jj new <conflicted>, which the
guardrail hook blocks. If one side is right for a whole file, resolve it in place with
jj resolve -r <conflicted> --tool :ours <path> (:theirs for the other side); a permission rule makes any
--tool form prompt the user. For a manual resolution, keep @ on its current descendant, edit the conflict
markers in its file, then run jj squash --into <conflicted> <paths> from the repository root. The squash
moves the resolution into the ancestor and leaves a new empty @ child. Run
jj log --no-graph -r 'conflicts()' to confirm that no conflicts remain. Otherwise report the conflicted
change IDs and ask the user to resolve them or to approve a separate workspace for it.
Revsets that answer checks
Confirm what trunk() resolves to (jj log -r 'trunk()') before using it as a range bound. A clone may carry
a per-repository alias (jj config list 'revset-aliases."trunk()"' shows it); otherwise the built-in tries
main, master, and trunk on origin and then upstream, and with none of them it resolves to the root
commit, so trunk()..@ silently spans the whole history.
| Question | Revset |
|---|---|
| My unpushed stack | trunk()..@ |
| Anything conflicted | conflicts() |
| One change rewritten by two sessions | divergent() |
| Leftover empty commits | empty() & mutable() & ~merges() & ~working_copies() |
| Commits touching a path | files("<path>") |
| Find by message | description(substring:"<text>") |
| Tips of mutable work | heads(mutable()) |
| Commits whose diff mentions a string | diff_lines("*<text>*", "<path>") |
| Another workspace's working copy | <workspace-name>@ (the trailing @ is part of the syntax) |
| A state as of an earlier operation | at_operation(<op>, <revset>) |
Wrap a revset that must name one commit in exactly(<revset>, 1): it errors instead of silently acting on
several commits or none.
divergent() turns nonempty when concurrent sessions rewrite the same change: two commits then share one
change ID. Do not abandon either side to tidy it; report both commit IDs and let the user choose.
The operation log
Every jj command records an operation, including those another session ran in the same repository.
jj op log lists them, jj op show -p <op> shows what one changed as a diff, and jj op diff --from <a> --to <b> compares two points. Read these to establish what took effect after an interrupted or surprising command.
Restoring or reverting an operation is blocked by the guardrail hook; name the operation ID and ask.
Shared working copy
The guardrail hook blocks commands that rewrite the files under other sessions: jj edit, jj next,
jj prev, jj new onto another revision, jj abandon, jj restore without paths, jj undo, jj redo,
jj op restore/revert, and jj sparse set/reset/edit. It also blocks every git write, and
ALLOW_DESTRUCTIVE_GIT=1 does not lift that verdict: the prefix applies to the jj verdicts only. The equivalents are to start work with plain jj new, discard one file with
jj restore <path>, and undo a revision with jj revert. Spell the built-in subcommand in full and
literally: one produced by $(...) or a variable is blocked, and so is any name that is not a built-in,
including the default aliases b, ci, desc, and st, because a config file can repoint an alias at any
command. Workspace isolation follows execution-workflow's jj procedure, not git worktree. A repository with .jj/ at its
root isolates with a jj workspace:
jj -R <repo> workspace add --no-colocate --sparse-patterns full --name <dir> -r <rev> <repo>/.worktrees/<dir>,
after mkdir -p <repo>/.worktrees. Without --sparse-patterns full the workspace copies the bare root's empty
sparse set and checks out no files.
When another workspace rewrites the commit this workspace's @ sits on, jj reports this working copy as stale.
jj workspace update-stale rewrites this workspace's files to match its new @.
jj bisect run makes each candidate revision the working copy in turn, so the guardrail hook blocks it like
jj edit. In a workspace created for the bisect and used by no other session, run
ALLOW_DESTRUCTIVE_GIT=1 jj bisect run --range '<good>..<bad>' -- <command>. The override prefix is an ask
rule in Claude Code, so its permission prompt is the user's confirmation.
Pushing
jj runs no Git hooks, so the pre-commit checks (gitleaks, conflict markers, editorconfig, author identity) never
ran on commits made with jj, and jj git push skips the pre-push hook too. One check still holds: the jj config
sets git.private-commits = "~mine()", so jj git push refuses any commit the remote lacks whose author is not
you. The author check only holds while the user config is the real one, so the hook blocks jj commands that
pass --config user.*, --config git.private-commits, --config-file, or --allow-private, or set
JJ_USER, JJ_EMAIL, or JJ_CONFIG. The secret scan before jj git push is on you:
jj git push --dry-run -b <bookmark>to list what would move.- Confirm
jj log --no-graph -r 'conflicts() & (trunk()..<commit>)'is empty: jj pushes a conflicted commit without complaint. - Scan exactly that range with the configured rules (
gitleaks gitis a gitleaks subcommand, not git):gitleaks git --config ~/.config/gitleaks/config.toml --log-opts="<remote>/<bookmark>..<commit>", or for a new bookmark--log-opts="<commit> --not --remotes". A finding stops the push. jj log --ignore-working-copy --no-pager -r '<range>' -T 'author.email() ++ "\n"'to confirm the author identity.- When the user has confirmed the push and all checks pass, push with the override prefix the guardrail hook names for this step:
ALLOW_DESTRUCTIVE_GIT=1 jj git push -b <bookmark>. The hook blocks every unprefixedjj git pushso the scan above cannot be skipped; the prefix is for that scanned push only.
A rejection naming a private commit means a commit by someone else is about to be pushed; stop and ask rather than overriding it.
A bookmark does not follow new commits. Move it first (jj bookmark set <b> -r @-), or push a change directly
with jj git push -c <change>, which creates a bookmark named after it. For a stack of pull requests, give each
commit its own bookmark and push them together with repeated -b; after rewriting a lower commit, every
bookmark above it moves with its rebased descendant and needs pushing again.
Bookmarks and stacks
jj bookmark list --all-remotesshows each bookmark with its remote counterparts;--conflictedlists the ones that point at several commits after concurrent moves or a fetch. Settle a conflicted bookmark by choosing one target withjj bookmark set <b> -r <rev>.- A remote bookmark fetched but not tracked stays immutable and gets no local bookmark.
jj bookmark track <b>@<remote>creates the local one and keeps it updated on later fetches. - After trunk moves, restack the whole stack in one rewrite:
jj git fetch --remote <r> --branch <default>, thenjj rebase -s 'roots(trunk()..@)' -o 'trunk()'. Check for conflicts as above before pushing.