Jujutsu (jj) Version Control
Jujutsu (jj) is a Git-compatible distributed version control system with a fundamentally better mental model. It treats the working copy as a commit, distinguishes changes from revisions, and provides first-class conflict handling.
Core Mental Model
Key Paradigm Shifts from Git
| Git Concept | jj Concept | Implication |
|---|---|---|
| Staging area/index | None - working copy IS a commit | No jj add needed; use jj split for selective commits |
| Detached HEAD | Anonymous branches (default) | Work freely; create bookmarks only when sharing |
| Branches auto-advance | Bookmarks are static pointers | Must jj bookmark set before jj git push |
| Conflicts block work | Conflicts are first-class objects | Commit through conflicts, resolve later |
| Commit hashes only | Change IDs + commit hashes | Stable identifiers even as commits evolve |
The @ Symbol
@ always refers to the current working copy commit. Most commands operate on @ by default.
Essential Commands
Daily Workflow
bash
# View status and log jj status # Current state (alias: jj st) jj log # Commit graph with smart defaults jj diff # Changes in current working copy jj diff -r <revset> # Changes in specific revision # Working with changes jj describe -m "message" # Set/update commit message (any revision with -r) jj new # Create new empty change (signals "done with this") jj commit -m "message" # Shorthand: describe + new jj edit <id> # Move working copy to different change
History Manipulation
bash
# Squash and move changes jj squash # Move current changes into parent jj squash -i # Interactive: select what to squash jj move --from <id1> --to <id2> # Move changes between any commits # Split commits jj split # Break current commit into multiple (interactive) jj split -r <id> # Split specific commit # Rebase (always succeeds - conflicts become objects) jj rebase -s <source> -d <dest> # Rebase commit and descendants jj rebase -b @ -d main # Rebase current branch onto main # Insert commits anywhere jj new -A <id> # Insert after (--insert-after) jj new -B <id> # Insert before (--insert-before) # Remove commits jj abandon # Discard commit, rebase children onto parent
Git Interoperability
bash
# Setup (in existing Git repo) jj git init --colocate # Creates .jj alongside .git; both work # Remote operations jj git fetch # Fetch from remotes jj git push # Push tracked bookmarks jj git push --allow-new # Push newly created bookmarks # IMPORTANT: No jj git pull - explicitly fetch then rebase jj git fetch && jj rebase -b @ -d main
Bookmark Management (Required for Pushing)
bash
jj bookmark create <name> # Create bookmark at @ (or -r <id>) jj bookmark set <name> # Move existing bookmark to @ jj bookmark list # Show all bookmarks jj bookmark track <name>@<remote> # Start tracking remote bookmark jj bookmark delete <name> # Delete locally and on push
Critical: Bookmarks don't auto-advance. Before pushing:
bash
jj bookmark set feature-x # Move bookmark to current @ jj git push # Push the bookmark
Undo and Recovery
bash
jj op log # All operations (more comprehensive than git reflog) jj undo # Undo last operation jj op restore --operation <id> # Restore to any previous state jj evolog # Evolution of current change over time
Revset Quick Reference
Revsets are a functional language for selecting commits.
Basic Operators
| Operator | Meaning | Example |
|---|---|---|
@ | Working copy | jj log -r @ |
@- | Parent of @ | jj diff -r @- |
@-- | Grandparent | jj log -r @-- |
::x | Ancestors of x | jj log -r '::@' |
x:: | Descendants of x | jj log -r 'main::' |
x..y | Range (y not reachable from x) | jj log -r 'main..@' |
| | Union | jj log -r 'a | b' |
& | Intersection | jj log -r 'mine() & main..' |
~ | Difference | jj log -r 'all() ~ trunk()' |
Key Functions
| Function | Returns |
|---|---|
trunk() | Main branch (auto-detects main/master) |
bookmarks() | All bookmarked commits |
remote_bookmarks() | Remote bookmarks |
mine() | Commits by current user |
heads(revset) | Commits with no children |
roots(revset) | Commits with no parents in set |
ancestors(revset) | All ancestors |
descendants(revset) | All descendants |
Practical Revset Examples
bash
# Work not yet pushed jj log -r 'bookmarks() & ~remote_bookmarks()' # My commits since branching from main jj log -r 'mine() & main..@' # Rebase all local branches onto updated main jj rebase -s 'all:roots(trunk..@)' -d trunk # Commits with conflicts jj log -r 'conflict()' # Empty commits (cleanup candidates) jj log -r 'empty() & mine()'
Common Workflows
Starting New Feature
bash
jj new -r main -m "feat: add feature X" # Branch from main with message # ... make changes ... jj new # Done with this, start next
Iterative Development (Squash Workflow)
bash
# Work in @, make small changes jj describe -m "WIP" # ... edit code ... jj squash # Move changes to parent # Repeat until done jj describe -m "feat: final message"
Rebasing onto Updated Main
bash
jj git fetch jj rebase -b @ -d main # Rebase current branch onto main # If conflicts, resolve with jj resolve or edit directly jj bookmark set feature-x jj git push
Creating Pull Requests
bash
# Ensure bookmark exists and is current jj bookmark create pr-feature -r @ # Or: jj bookmark set pr-feature jj git push --allow-new # --allow-new for new bookmarks # Create PR via gh or web interface
Working with Conflicts
bash
# Conflicts are committed, not blocking jj rebase -s @ -d main # May create conflicts jj log # Shows conflict markers in graph # Continue working if needed jj resolve # Interactive resolution when ready # Or edit conflict markers directly and jj describe
Configuration Tips
Essential Config (~/.jjconfig.toml)
toml
[user] name = "Your Name" email = "your@email.com" [ui] default-command = "log" diff-editor = ":builtin" # Built-in TUI for split/squash -i [revset-aliases] 'wip' = 'mine() & mutable() & ~empty()' 'stack' = 'trunk()..@'
Useful Aliases
toml
[aliases] # Move nearest ancestor bookmark to current commit tug = ['bookmark', 'move', '--from', 'heads(::@- & bookmarks())', '--to', '@']
Common Pitfalls
Bookmark not advancing: Unlike Git branches, jj bookmarks don't auto-advance.
bash
# Wrong assumption: bookmark follows after jj new jj new jj git push # ERROR: bookmark still at old commit # Correct: explicitly set before push jj bookmark set <name> jj git push
Force push is normal: jj rewrites history freely. Expect force pushes.
No jj git pull: Intentional design. Always:
bash
jj git fetch jj rebase -b @ -d main
Progressive Context
- •For advanced revsets and patterns: see
references/revsets.md - •For stacked PR workflows: see
references/stacked-prs.md - •For common workflow examples: see
examples/workflows.md