Jj

Jujutsu (jj) Workflow Skill

Execute version-control tasks with jj first. Keep commands non-interactive unless the user explicitly asks for an interactive workflow.

Detect Repository Mode

1. Run jj root to confirm Jujutsu context.
2. Treat the repository as Jujutsu-managed when .jj/ exists.
3. In colocated repos (.jj/ + .git/), use jj for mutations and keep git usage read-only unless the user explicitly requests otherwise.

Use Agent-Safe Command Patterns

1. Pass a message flag instead of opening an editor:

• jj describe -m "message"
• jj commit -m "message"
• jj squash -m "message"

1. Avoid commands that require interactive UI flows when running non-interactively.
2. After history mutations (squash, rebase, abandon, restore), run jj status to verify state.

Run the Core Daily Flow

1. Inspect current state:

jj status
jj log -n 10
jj show
jj diff

1. Start and describe work:

jj new
jj describe -m "Implement feature X"

1. Continue editing files. Jujutsu tracks working-copy changes automatically.

1. Navigate the change graph without revision IDs:

jj next -e       # edit child change directly
jj prev -e       # edit parent change directly
jj edit  # jump to a specific change for editing

Without -e, jj next/jj prev create a new working-copy commit on top of the target revision.

Handle History Edits

Use these commands for most agent workflows:

jj absorb
jj squash
jj split ... -m "split: "    # non-interactive split by file paths
jj rebase -r  -d 
jj simplify-parents                         # remove redundant merge parents after rebase
jj duplicate  --destination  # copy a change onto an explicit target (cherry-pick style)
jj abandon 
jj restore 

In agent contexts, always pass both filesets and -m to jj split.

Use jj evolog to inspect how a change has evolved over time (useful for debugging history mutations).

Load [cheat-sheet.md](./references/cheat-sheet.md) when the user describes a Git command and needs a Jujutsu equivalent.

Push and Sync with Remotes

1. Sync from remote:

jj git fetch
jj rebase -d main@origin

1. Push a single change quickly:

jj git push --change @-

1. Use bookmarks for explicit branch-like collaboration:

jj bookmark create feat/my-change -r @-
jj git push -b feat/my-change

Load [colocated-git.md](./references/colocated-git.md) for teams that use GitHub/GitLab while you work locally in Jujutsu.

Resolve Conflicts

1. Inspect conflict state:

jj status
jj resolve --list          # list all conflicted files

1. In non-interactive agent contexts, edit conflicted files directly and remove conflict markers. In interactive contexts, use the configured merge tool:

jj resolve           # opens external merge tool (interactive only)

1. Re-run jj status until no unresolved conflicts remain.

Recover Safely

Use operation-level undo when something goes wrong:

jj undo
jj op log
jj op restore 

Prefer these commands instead of attempting destructive resets.

Use Workspaces for Parallel Work

Workspaces let you check out multiple changes simultaneously in separate directories (like git worktree):

jj workspace add ../my-feature     # create a new workspace
jj workspace list                  # list all workspaces
jj workspace forget          # remove a workspace

Each workspace has its own working-copy commit but shares the full change graph and operation log.

Inspect Files

jj diff                            # diff of working copy against parent
jj diff -r               # diff of a specific revision
jj file annotate             # blame/annotate a file (added in 0.24)
jj file list                       # list tracked files

Auto-Format Code

If a formatting tool is configured, apply it across revisions:

jj fix

Handle Version Differences

1. Run jj --version.
2. If a command flag behaves differently, run jj help .
3. Prefer command forms documented in [sources.md](./references/sources.md) when uncertain.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RealAdarsh
• Source: RealAdarsh/jj-skill
• License: MIT

Install and usage instructions live in the source repository linked above.