**REQUIRED** - Always activate FIRST on any git/VCS operations (commit, status, branch, push, etc.), especially when HEAD is detached. If `.jj/` exists -> this is a Jujutsu (jj) repo - raw git commands can corrupt data. Essential git safety instructions inside. DO NOT IGNORE.
78%
Does it follow best practices?
Impact
94%
1.59x2 of 3 eval scenarios. Add 1 more for a full score.
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./jujutsu/SKILL.mdThis skill helps you work with Jujutsu, a Git-compatible VCS with mutable commits and automatic rebasing.
Tested with jj v0.46.0 - Commands may differ in other versions.
When running as an agent:
--no-pager to prevent commands from opening an interactive pager (like less), which will hang the agent:# Always use --no-pager on commands that produce output
jj --no-pager log # NOT: jj log
jj --no-pager diff # NOT: jj diff
jj --no-pager show <id> # NOT: jj show <id>-m flags to provide messages inline rather than relying on editor prompts:# Always use -m to avoid editor prompts
jj desc -m "message" # NOT: jj desc
jj squash -m "message" # NOT: jj squash (which opens editor)Editor-based commands will fail in non-interactive environments.
jj st after mutations (squash, abandon, rebase, restore) to confirm the operation succeeded.In jj, your working directory is always a commit (referenced as @). Changes are automatically snapshotted when you run any jj command. There is no staging area.
There is no need to run jj commit.
CRITICAL: Unlike git, jj commits can be freely modified after creation. You can update descriptions, squash changes, rebase, and absorb — all without creating new commits. See "Essential Workflow" below for the recommended working pattern.
tqpwlqmp) that persists when a commit is rewritten — prefer these when referencing commits3ccf7581) that changes when commit content changesjj uses a revset language to select commits in commands. Common revsets:
@ — the working copy commit@- — the parent of the working copy::@ — all ancestors of @@:: — all descendants of @trunk()..@ — commits between trunk and @ (your branch)bookmarks() — all commits with bookmarksUse revsets with -r flags: jj log -r 'trunk()..@'
Always create your commit message before writing code:
Validate that you're on a blank revision with jj st. If you are not, you should type:
jj new# First, describe what you intend to do
jj desc -m "Add user authentication to login endpoint"
# Then make your changes - they automatically become part of this commit
# ... edit files ...
# Check status
jj stEach commit should represent ONE logical change. Use this format for commit messages:
Examples:
- "Add validation to user input forms"
- "Fix null pointer in payment processor"
- "Remove deprecated API endpoints"
- "Update dependencies to latest versions"# View recent commits
jj --no-pager log
# View with patches
jj --no-pager log -p
# View specific commit
jj --no-pager show <change-id>
# View diff of working copy (use --git for familiar +/- format)
jj --no-pager diff --gitIMPORTANT: jj diff output format: The default jj diff output uses a side-by-side line number format (e.g. 26 26:) that looks very different from git's +/- prefix format. This is normal and correct — it is NOT corrupted or showing stale content. However, to avoid confusion, always use jj diff --git to get standard unified diff format with +/- lines.
# Create a new empty commit on top of current
jj new
# Create new commit with message
jj new -m "Commit message"
# Edit an existing commit (working copy becomes that commit)
jj edit <change-id>
# Edit the previous commit
jj prev -e
# Edit the next commit
jj next -eMove changes from current commit into its parent:
# Squash all changes into parent
jj squashNote: jj squash -i opens an interactive UI and will hang in agent environments. Avoid it.
Pass the paths that should move into a new first commit, plus -m for its message:
# src/search.txt moves into a new commit described "Add search";
# everything else stays in the original commit, which keeps its description
jj split -m "Add search" src/search.txtWithout paths, jj split opens an interactive diff editor, and without -m it opens an editor for the description. Neither works in an agent environment.
Automatically distribute changes to the commits that last modified those lines:
# Absorb working copy changes into appropriate ancestor commits
jj absorbRemove a commit entirely (descendants are rebased to its parent):
jj abandon <change-id>Undo a commit's changes with a new commit, keeping the original in history. jj backout no longer exists; use jj revert:
# Insert a commit that reverts <change-id> directly below the working copy
jj revert -r <change-id> -B @Reverse the last jj operation:
jj undoThis reverts the repository to its state before the previous command. Useful for recovering from mistakes like accidental abandon, squash, or rebase.
Run jj undo again to step further back, and jj redo to step forward. jj undo takes no operation ID. To return to a specific operation, find it in the operation log and restore it:
jj --no-pager op log
jj op restore <operation-id>Move commits to a different parent:
# Rebase current branch onto a destination
jj rebase -o <destination>
# Rebase a specific revision (without descendants) onto a destination
jj rebase -r <change-id> -o <destination>
# Rebase a revision and all its descendants
jj rebase -s <change-id> -o <destination>
# Rebase onto trunk (common: update your branch to latest main)
jj rebase -o main-o is short for --onto. The older -d/--destination still works but is deprecated.
Discard changes to specific files or restore files from another revision:
# Discard all uncommitted changes in working copy (restore from parent)
jj restore
# Discard changes to specific files
jj restore path/to/file.txt
# Restore files from a specific revision
jj restore --from <change-id> path/to/file.txtQuote paths that contain fileset syntax. jj reads file arguments as fileset expressions. A path with parentheses fails to parse, and a leading ~ means "everything except": jj restore ~scratch.txt discards the changes to every file other than scratch.txt. Wrap such paths as file:"...", in single quotes for the shell:
jj restore 'file:"docs/notes (draft).md"' 'file:"~scratch.txt"'Bookmarks are jj's equivalent to git branches:
# Create a bookmark at current commit
jj bookmark create my-feature -r@
# Move bookmark to a different commit
jj bookmark move my-feature --to <change-id>
# List bookmarks
jj --no-pager bookmark list
# Delete a bookmark
jj bookmark delete my-featureA workspace is a working copy plus its associated repo. One repo can have multiple workspaces — each with its own working directory and working-copy commit (@) — all sharing the same commits, operations, and bookmarks. This is jj's equivalent of git worktree.
Useful for running a long build or test in one workspace while editing in another. Workspaces are a rarely-needed feature; consult the official docs for anything beyond the basics below.
# Create a new workspace (defaults: name = basename of path, parent = current @'s parent)
jj workspace add ../my-tests
jj workspace add --name tests -r <change-id> ../my-tests # explicit name and base
# Inspect
jj --no-pager workspace list
jj workspace root [--name <ws>]
# Remove (does NOT delete files on disk — rm the directory separately)
jj workspace forget [<ws>]
# Rename current workspace
jj workspace rename <new-name>In jj log, each workspace's @ appears as <workspace-name>@.
jj workspace add gives the new workspace its own fresh empty commit; workspaces don't start out sharing @, and on-disk files are never live-mirrored between them.@ (e.g. via jj squash, rebase, abandon), jj refuses commands here until you run jj workspace update-stale. Same recovery path if a command was interrupted mid-update.@ is sharp-edged. jj edit <id> lets two workspaces point at the same change without warning. When one mutates it, the other goes stale; if the stale one had un-snapshotted edits, update-stale preserves them as a divergent commit (same change ID, shown as xyz?? in jj log) that you must resolve. Avoid sharing @ unless both workspaces are read-only.--no-pager to jj workspace list.jj edit a change another workspace already has as its @ — main cause of accidental divergence.rm -rf a workspace directory without also running jj workspace forget <name>.# Clone a git repository
jj git clone <url>
# Initialize jj in an existing git repo
jj git init --colocate# Fetch all branches from the default remote
jj git fetch
# Fetch from a specific remote
jj git fetch --remote <remote-name>
# Fetch specific branches
jj git fetch -b <branch-name>After fetching, rebase your work onto the updated trunk: jj rebase -o main
This section only applies to colocated repos (where both .jj/ and .git/ exist). In non-colocated repos, do not use git commands — they will corrupt jj state.
In a colocated repository, you can use both jj and git commands with care:
Switching to git mode (e.g., for merge workflows):
# First, ensure your jj working copy is clean
jj st
# Then checkout a branch with git
git checkout <branch-name>Switching back to jj mode:
# Use jj edit to resume working with jj
jj edit <change-id>Important notes:
When the user asks you to push changes:
# Push a specific bookmark to the remote
jj git push -b <bookmark-name>
# Example: push the main bookmark
jj git push -b mainBefore pushing, ensure:
IMPORTANT: Unlike git branches, jj bookmarks do not automatically move when you create new commits. You must manually update them before pushing:
# Preferred (jj 0.39+): advance the closest bookmark(s) behind @ up to @
jj bookmark advance
# Or move a specific bookmark explicitly
jj bookmark move my-feature --to @
# Then push it
jj git push -b my-featureIf @ is an empty working-copy commit, as it is after jj commit or jj new, your work ends at @-. Advance to that instead:
jj bookmark advance --to @-A bare jj bookmark advance would put the bookmark on the empty commit, which jj refuses to push because it has no description. advance only moves bookmarks forward, so to recover, jj undo it.
If no bookmark exists for your changes, create one first:
# Create a bookmark at the current commit
jj bookmark create my-feature
# Then push it
jj git push -b my-featurejj allows committing conflicts — you can resolve them later:
# View conflicts
jj stAgent conflict resolution: Do not use jj resolve (interactive). Instead, edit the conflicted files directly to remove conflict markers, then run jj st to verify resolution.
IMPORTANT: Because commits are mutable, always refine them before considering work done:
jj --no-pager show @ or jj --no-pager diff --gitjj split -m "message" <paths> to move them into their own commitjj squash or jj absorb| Action | Command |
|---|---|
| Describe commit | jj desc -m "message" |
| View status | jj st |
| View log | jj --no-pager log |
| View diff | jj --no-pager diff --git |
| New commit | jj new -m "message" (use jj st first; skip if @ is empty) |
| Edit commit | jj edit <id> |
| Squash to parent | jj squash |
| Split by path | jj split -m "message" <paths> |
| Auto-distribute | jj absorb |
| Rebase | jj rebase -o <destination> |
| Abandon commit | jj abandon <id> |
| Revert commit | jj revert -r <id> -B @ |
| Undo last operation | jj undo |
| Return to an operation | jj op restore <operation-id> |
| Restore files | jj restore [paths] |
| Create bookmark | jj bookmark create <name> |
| Fetch remote | jj git fetch |
| Advance bookmark before pushing | jj bookmark advance (--to @- if @ is empty) |
| Push bookmark | jj git push -b <name> |
| Add workspace | jj workspace add <path> |
| List workspaces | jj --no-pager workspace list |
| Forget workspace | jj workspace forget [name] |
| Fix stale working copy | jj workspace update-stale |
danverbraganza/jujutsu-skill
jujutsu/SKILL.md
85a8376
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.