jj-workflow
Guides Claude on using Jujutsu (jj) version control system. Use when working with jj repositories, making commits, syncing changes, or managing version control workflows.
📖 中文导读:Guides Claude on using Jujutsu (jj) version control system. Use when working with jj repositories, making commits, syncing changes, or managing version control workflows. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: jj-workflow description: Guides Claude on using Jujutsu (jj) version control system. Use when working with jj repositories, making commits, syncing changes, or managing version control workflows.
Jujutsu (jj) Workflow
Jujutsu is a modern version control system that provides a simpler mental model than Git while remaining Git-compatible. This skill covers the core concepts and workflow commands.
Core Concepts
Changes vs Commits
- Change: A mutable revision identified by a change ID (e.g.,
kkmpptxz). Changes can be modified. - Commit: An immutable snapshot identified by a commit ID (SHA). Once created, commits are permanent.
- The working copy (
@) is always a change that can be modified freely.
Working Copy
- The working copy is denoted by
@and represents your current state. @-refers to the parent of the working copy.- Unlike Git, there's no staging area—all changes are automatically tracked.
Permission Requirements
CRITICAL: Jujutsu commands require GPG signing and SSH/GitHub authentication. Always request elevated permissions when running jj or gh commands:
required_permissions: ["all"]
Never run jj commands in the default sandbox—they will fail due to authentication requirements.
Essential Commands
Viewing State
jj status # Show working copy status
jj log # View commit history
jj diff # Show uncommitted changes
jj show @ # Show current change details
Creating and Describing Changes
jj new # Create a new empty change on top of @
jj describe -m "feat: message" # Set commit message for current change
jj new -m "feat: message" # Create new change with message
Syncing with Remote
jj tug # Fetch updates and rebase current change onto latest remote
jj git fetch # Fetch from remote without rebasing
jj git push # Push current changes to remote
Modifying History
jj squash # Squash current change into parent
jj squash --into @- # Explicitly squash into parent
jj split <file> -m "msg" # Split specific files into their own commit
jj edit <change-id> # Edit an existing change
Working with Branches
jj branch create <name> # Create a branch pointing to @
jj branch set <name> # Move branch to current change
jj branch list # List all branches
Commit Message Format
Use Conventional Commits format:
feat:— New featurefix:— Bug fixrefactor:— Code change that neither fixes a bug nor adds a featureperf:— Performance improvementdocs:— Documentation changeschore:— Maintenance taskstest:— Adding or updating tests
Examples:
jj describe -m "feat: add user authentication"
jj describe -m "fix: resolve null pointer in parser"
jj describe -m "refactor: extract validation logic"
Common Patterns
Starting New Work
jj tug # Sync with remote
jj new -m "feat: new feature" # Start new change
# ... make changes ...
jj new # Finalize and start next
Amending Current Change
Simply make changes—they're automatically included in @. Use jj describe to update the message if needed.
Rebasing onto Latest
jj tug # Fetches and rebases in one command
Viewing What Will Be Pushed
jj log -r 'remote_branches()..@' # Changes not yet on remote
Key Differences from Git
- No staging area: All changes are tracked automatically
- Mutable working copy: The current change can always be modified
- Change IDs: Stable identifiers that persist through rebases
- Anonymous branches: You can work without named branches
- Automatic conflict handling: Conflicts are recorded and can be resolved later