Skill v1.0.1

version: "1.0.1" name: jujutsu description: Prefer Jujutsu (jj) over git for version control. Use squash workflow pattern where commits are described first, then changes are made in a scratch child commit and squashed into the parent. license: MIT compatibility: opencode metadata: category: vcs tools: jj

When to use me

Use this skill for all version control operations. Prefer jj commands over git unless:

• Jujutsu is not installed (command -v jj fails)
• Performing git-specific operations not yet supported (e.g., submodules)
• Working with CI systems that require raw git

Mental model

Jujutsu differs fundamentally from git:

• Working copy is always a commit: No staging area. @ represents your current working-copy commit.
• Change IDs vs Commit IDs: Change IDs (e.g., kxryzmor) are stable across rebases. Prefer them for references.
• Bookmarks ≠ Branches: Bookmarks don't auto-advance on commit. You must explicitly move them.
• Anonymous commits are normal: No branch/bookmark needed to start working.
• History rewriting is first-class: squash, split, rebase are core workflows.

Preferred workflow: squash pattern

Separate intent (commit message) from implementation (working changes).

# 1. Create the described commit
jj new main -m "feat: implement user authentication"
 
# 2. Create a scratch child to work in
jj new
 
# 3. Make changes in the scratch commit
 
# 4. When satisfied, squash into the parent
jj squash
 
# 5. Repeat steps 2-4 for additional changes

Multi-commit features

# First commit
jj new main -m "refactor: extract auth module"
jj new
# ... work ...
jj squash
 
# Second commit as child of first
jj new -m "feat: add JWT validation"
jj new
# ... work ...
jj squash

Command reference

Git interop

Bookmark management

# Create/move bookmark to current commit
jj bookmark set feature-name
 
# Push to remote
jj git push -b feature-name
 
# After more work, must re-set bookmark before pushing again
jj bookmark set feature-name
jj git push -b feature-name

Git command translations

Repository setup

Always use colocated repos for compatibility with git-expecting tools:

# New repo
jj git init --colocate
 
# Existing git repo
cd existing-repo
jj git init --colocate

Common workflows

Starting a feature

jj git fetch
jj new main -m "feat: add widget support"
jj new
# ... work ...
jj squash
jj bookmark set add-widget-support
jj git push -b add-widget-support

Updating with upstream

jj git fetch
jj rebase -d main

Code review fixes

jj edit <change_id>     # go to commit needing fixes
jj new                  # scratch commit
# ... make fixes ...
jj squash
jj bookmark set feature-name
jj git push -b feature-name

Gotchas

1. Bookmarks don't auto-advance: After jj git push, run jj bookmark set <name> again before next push.

1. Colocated sync: Run jj git export if external tools aren't seeing changes, jj git import after raw git commands.

1. Revset shortcuts: @ is current, @- is parent, @-- is grandparent.

1. Undo anything: jj undo reverts last operation. jj op log shows history.

1. Empty commits are fine: Unlike git, empty commits are normal placeholders.

1. Conflicts are commits: Conflicts appear in the commit itself. Edit files to resolve, commit auto-updates.