jujutsu
指南,介绍如何使用Jujutsu (jj)版本控制系统作为Git的替代方案。在使用包含.jj目录的仓库时使用此技能,该目录表示仓库使用Jujutsu VCS。提供jj操作的命令映射、工作流程和最佳实践,包括提交、分支、变基和git互操作性。
name: jujutsu description: Guide for using Jujutsu (jj) version control system as an alternative to Git. Use this skill when working in repositories with a .jj directory, which indicates the repository uses Jujutsu VCS. Provides command mappings, workflows, and best practices for jj operations including commits, branching, rebasing, and git interoperability.
Jujutsu Version Control
Overview
Enable seamless use of Jujutsu (jj), a modern version control system that is fully compatible with Git. Jujutsu provides a more intuitive interface with automatic change tracking, safe history rewriting, and powerful undo capabilities.
When to Use This Skill
Use jujutsu commands automatically when:
- The working directory contains a
.jj/directory (indicates a jujutsu repository)
Otherwise, continue using git commands as normal.
Detection pattern:
if [ -d .jj ]; then
# Use jj commands from this skill
else
# Use standard git commands
fi
Core Concepts
Working-Copy-as-a-Commit Model
- Every file change is automatically part of the working copy commit
- No staging area - changes are immediately tracked
- Use
jj describeto add/update commit messages (notjj commit) - Use
jj newto create a new change on top of current
Change-Centric History
- Each "change" has a unique ID that persists across rewrites
- Revisions can be modified in place without losing history
- Conflicts are tracked explicitly as first-class citizens
Safe Operations with Undo
- Every operation is logged in the operation log (
jj op log) - Any operation can be undone with
jj op undo - Even "destructive" operations never lose data permanently
Daily Workflow
Starting Work
Check repository type and status:
# Check if jujutsu repo
if [ -d .jj ]; then
jj status
else
git status
fi
Making Changes
There are two workflows depending on whether you have existing changes:
Workflow 1: Commit existing changes (when jj status shows changes)
# 1. Edit files (automatically tracked - no `add` needed)
# 2. Review changes
jj diff # See all changes
jj status # Check status
# 3. Commit the changes
jj commit -m "Implement feature X" # Describe and create new change on top
Workflow 2: Start new change first (when jj status shows no changes)
jj new # Start new empty change
# ... edit files ...
jj describe -m "Implement feature" # Add description as you work
jj new # When done, create next change
When user says "commit":
- If
jj statusshows changes: usejj commit -m "message" - If current change is already described: use
jj newto start next change
Note: jj commit = jj describe + jj new in one command.
Viewing History
jj log # View change history
jj log -p # View history with diffs
jj log <file> # View history for specific file
jj show <revision> # Show specific revision
Git Interoperability
Working with Git Remotes
Jujutsu works seamlessly with git remotes using jj git commands:
# Fetch from remote
jj git fetch
# Push to remote (must move bookmark first!)
jj bookmark set <bookmark-name> -r <revision> # Move bookmark to commit you want to push
jj git push # Push all bookmarks
# Push specific bookmark (branch)
jj git push --bookmark <name>
# Push with force (use carefully)
jj git push --force
IMPORTANT: Before pushing, you must move the bookmark to the commit you want as the head:
jj bookmark set master -r @- # Move master to parent of working copy
jj git push # Now push
Colocated Repositories
When a repository has both .git/ and .jj/ directories:
- Both git and jj commands work on the same repository
- Changes made with git appear in jj log and vice versa
- Git branches appear as jj bookmarks
- Use
jj git init --colocateto set this up initially
Syncing with Upstream
# Fetch latest changes
jj git fetch
# Rebase current work on remote main
jj rebase -d main@origin
# If conflicts occur, resolve and continue
jj resolve
jj rebase --continue
Branching and Bookmarks
Jujutsu uses "bookmarks" (similar to git branches):
# List bookmarks
jj bookmark list
# Create bookmark at current revision
jj bookmark create <name>
# Move bookmark to current revision
jj bookmark set <name>
# Track remote bookmark
jj bookmark track <name>@origin
# Delete bookmark
jj bookmark delete <name>
Common pattern for feature work:
jj new # Start new change
jj describe -m "Add feature" # Describe work
jj bookmark create my-feature # Create bookmark
jj git push # Push to remote
History Modification
Editing Past Changes
# Edit a specific revision
jj edit <change-id>
# ... make changes ...
jj describe -m "Updated message"
jj new # Return to tip
Squashing Changes
# Squash current change into parent
jj squash
# Squash specific changes
jj squash -r <source> -d <destination>
Rebasing
# Rebase current change onto destination
jj rebase -d <destination>
# Rebase specific change
jj rebase -r <revision> -d <destination>
# Continue after conflict resolution
jj rebase --continue
Splitting Changes
# Split current change into multiple
jj split
# Interactive prompt will guide through the split
Moving Changes Between Revisions
# Move specific changes between revisions
jj move --from <source> --to <destination>
Safe Undo and Recovery
Operation History
View all operations performed:
jj op log # Show operation history
Undoing Operations
# Undo the last operation
jj op undo
# Undo specific operation
jj op undo <operation-id>
# Restore to specific state
jj op restore <operation-id>
When to use undo:
- Accidentally abandoned a change
- Rebased to wrong destination
- Made any mistake that needs reversal
- Want to explore alternative approaches
Revision Selection (Revsets)
Use these patterns to reference revisions:
@ # Current working copy
@- # Parent of working copy
@-- # Grandparent
<change-id> # Specific change (first 12+ chars)
<bookmark> # Named bookmark
main@origin # Remote bookmark
description(text) # Changes matching description text
author(name) # Changes by specific author
mine() # Changes authored by current user
Examples:
jj diff -r @- # Diff of parent change
jj show main@origin # Show remote main
jj log -r 'author(alice)' # Log of Alice's changes
jj rebase -d main@origin # Rebase onto remote main
Conflict Resolution
Jujutsu tracks conflicts explicitly in history:
# When conflicts occur during rebase/merge
jj status # Shows conflicted files
# Resolve conflicts in your editor
# Edit conflicted files to resolve
# Mark as resolved and continue
jj resolve
jj rebase --continue
# Or undo the operation entirely
jj op undo
Common Command Patterns
Feature Development
# Option 1: Commit existing work
# ... edit files ...
jj commit -m "Start feature X"
# ... work more ...
jj commit -m "Add tests for X"
# Option 2: Start new changes first
jj new
jj describe -m "Start feature X"
# ... work on feature ...
jj new
jj describe -m "Add tests for X"
# ... add tests ...
# Create bookmark and push
jj bookmark create feature-x
jj git push
Code Review Workflow
# Push changes for review
jj bookmark create my-feature
jj git push
# Address review feedback (edit in place)
jj edit <change-id>
# ... make changes ...
jj describe -m "Address review feedback"
jj git push --force
# Squash review fixups if desired
jj squash
Syncing Work
# Sync with remote regularly
jj git fetch
jj rebase -d main@origin
# Push your work
jj git push
Exploring History
# View detailed history
jj log -p
# Search for specific changes
jj log -r 'description(bug fix)'
# Show what changed in a file
jj log <file>
Reference Material
For detailed command mappings between git and jujutsu, including all supported operations and syntax, refer to references/command_reference.md.
The reference includes:
- Complete git → jj command mappings
- Revset syntax and examples
- Colocated repository workflows
- Advanced patterns and use cases
Load the reference when:
- Unsure of the jj equivalent for a git command
- Need to understand revset syntax
- Working with complex history modifications
- Debugging workflow issues
Best Practices
- Use descriptive commit messages: Run
jj describefrequently to document work - Create new changes regularly: Use
jj newto logically separate work - Leverage safe undo: Don't fear mistakes -
jj op undois always available - Sync frequently: Regular
jj git fetchkeeps work up-to-date - Use bookmarks for features: Create bookmarks for feature branches
- Review before pushing: Use
jj logandjj diffto review beforejj git push
Error Handling
If jj Command Not Found
Jujutsu should be available via the shell.tools.development.enable configuration. If not available:
# Verify installation
command -v jj || echo "jujutsu not installed"
Inform the user to enable development tools in their Nix configuration.
When .jj Directory Missing
If user wants to use jujutsu in an existing git repository:
# Initialize colocated repository (keeps .git)
jj git init --colocate
This creates .jj/ alongside existing .git/, enabling jj commands while maintaining git compatibility.