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 feature
• fix: — Bug fix
• refactor: — Code change that neither fixes a bug nor adds a feature
• perf: — Performance improvement
• docs: — Documentation changes
• chore: — Maintenance tasks
• test: — 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

1. No staging area: All changes are tracked automatically
2. Mutable working copy: The current change can always be modified
3. Change IDs: Stable identifiers that persist through rebases
4. Anonymous branches: You can work without named branches
5. Automatic conflict handling: Conflicts are recorded and can be resolved later