Jujutsu (jj) is a Git-compatible version control system that eliminates common Git pain points while maintaining full compatibility with Git repositories.

Core Concepts

Change IDs vs Commit IDs

JJ uses change IDs to track logical changes, separate from commit IDs:

1
2
3
4
5

# Change ID: stable identifier for a logical change
# Commit ID: Git SHA, changes on every amendment
jj log
@  qpvuntsm [email protected] 2025-01-19 12:34:56 d4f2a1b2
│  (empty) WIP: refactor parser

• Change ID: qpvuntsm - stable across amendments
• Commit ID: d4f2a1b2 - changes with every modification

This allows amending commits without losing track of the logical change.

No Staging Area

JJ eliminates Git’s staging area. Every edit is automatically part of the working commit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Edit files
vim src/main.rs

# Check status - changes are already tracked
jj st
Working copy changes:
M src/main.rs

# Describe the change
jj describe -m "Add error handling"

No git add required. Changes are immediately visible in jj log.

Conflicts as First-Class Objects

JJ treats conflicts as committable states, not errors:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Create a merge with conflicts
jj merge feature-branch
Added 0 files, modified 2 files, removed 0 files
There are unresolved conflicts at these paths:
src/config.rs    2-sided conflict

# Commit includes conflict markers
jj st
Working copy changes:
C src/config.rs

Conflicts can be committed, rebased, and resolved later. The conflict state is preserved across operations.

Automatic Working Copy Commits

JJ automatically commits working changes to track history:

1
2
3
4

# Working copy is always a commit
jj log
@  sqpkvzwt [email protected] 2025-01-19 12:45:11 HEAD@git
│  (no description set)

The @ symbol represents the current working copy commit.

Why JJ Over Git

Simplified Mental Model

Git workflow:

1. Edit files
2. Stage changes (git add)
3. Commit staged changes
4. Amend requires --amend flag
5. Force push with --force-with-lease

JJ workflow:

1. Edit files
2. Describe changes (jj describe)
3. Create new change (jj new)

Safe Rewriting

JJ makes rewriting history safe:

1
2
3
4
5
6
7
8

# Amend any commit without checkout
jj describe -r <revision> -m "Updated message"

# Split a commit
jj split -r <revision>

# Move changes between commits
jj squash -r <source> -d <dest>

No detached HEAD states. No lost work.

Branchless Workflow

JJ doesn’t require named branches for development:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Create stack of changes
jj new -m "Add feature A"
# ... work ...
jj new -m "Add feature B"  # Based on A
# ... work ...
jj new -m "Add tests"      # Based on B

# View stack
jj log
@  wzklmpqy [email protected] 2025-01-19 13:01:22
│  Add tests
○  nsqwlrty [email protected] 2025-01-19 13:00:15
│  Add feature B
○  mlpkrtws [email protected] 2025-01-19 12:58:43
│  Add feature A

Named branches (bookmarks) are optional, used only when needed for remotes.

Git Compatibility

JJ is a Git frontend. All operations work on Git repositories:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Clone existing Git repo
jj git clone https://github.com/user/repo.git

# Or initialize in existing Git repo
cd existing-git-repo
jj git init --colocate

# Push to Git remotes
jj git push

# Fetch from Git remotes
jj git fetch

Git and JJ can be used interchangeably on the same repository.

Key Operations

When to Use JJ

Good fit:

• Teams comfortable with advanced Git workflows
• Projects requiring frequent history rewriting
• Developers frustrated with Git’s staging area
• Stacked PR workflows (Gerrit-style)

Consider staying with Git:

• Teams with basic Git workflows (commit/push only)
• Heavy reliance on Git-specific tools
• Team unfamiliar with advanced VCS concepts

Resources

• Official documentation: https://martinvonz.github.io/jj/
• GitHub repository: https://github.com/martinvonz/jj
• Comparison with other VCS: https://github.com/martinvonz/jj/blob/main/docs/comparison.md