---
name: jujutsu
description: How to use `jj`, the Jujutsu version control system
---

# Jujutsu (jj) Version Control Skill

This skill enables working with Jujutsu, a Git-compatible version control system
with a fundamentally different model. Jujutsu treats the working copy as a
commit, has no staging area, and uses change IDs for stable references across
rewrites.

## Core Concepts

### Working Copy as a Commit

Unlike Git, the working copy IS a commit. Changes are automatically snapshotted
when running `jj` commands - no explicit `add` or staging required.

### Change IDs vs Commit IDs

Every commit has two identifiers:

- **Change ID**: Stable across rewrites (e.g., `kkmpptxz`)
- **Commit ID**: Hash-based, changes on rewrite (e.g., `abc123def`)

Use change IDs for references that survive rebases.

### Revsets

Revsets are expressions to select commits:

| Expression    | Description                         |
| ------------- | ----------------------------------- |
| `@`           | Working copy commit                 |
| `@-`          | Parent of working copy              |
| `root()`      | Repository root                     |
| `bookmarks()` | All bookmarked commits              |
| `foo..bar`    | Commits from foo to bar (exclusive) |
| `foo::bar`    | Commits from foo to bar (inclusive) |
| `A \| B`      | Union                               |
| `A & B`       | Intersection                        |
| `~A`          | Complement                          |

### Bookmarks (not Branches)

Bookmarks are named pointers that map to Git branches. They move automatically
when commits are rewritten.

## Quick Reference

| Git Command                 | Jujutsu Equivalent        | Notes                            |
| --------------------------- | ------------------------- | -------------------------------- |
| `git init`                  | `jj git init`             | Use `--colocate` for Git interop |
| `git clone URL`             | `jj git clone URL`        | Git repos only                   |
| `git status`                | `jj st`                   | Shows working copy diff          |
| `git diff`                  | `jj diff`                 | Diff of working copy             |
| `git diff --staged`         | N/A                       | No staging area                  |
| `git add && git commit`     | `jj commit`               | Auto-includes all changes        |
| `git commit --amend`        | `jj squash`               | Squash into parent               |
| `git log --oneline --graph` | `jj log`                  | Visual commit graph              |
| `git show COMMIT`           | `jj show REV`             | Show revision details            |
| `git checkout -b NAME`      | `jj new`                  | Start new change                 |
| `git switch BRANCH`         | `jj edit BOOKMARK`        | Edit existing change             |
| `git reset --hard`          | `jj abandon`              | Discard working copy             |
| `git stash`                 | `jj new`                  | Just start new change            |
| `git rebase B A`            | `jj rebase -b A -d B`     | Rebase A onto B                  |
| `git cherry-pick`           | `jj duplicate`            | Copy commits                     |
| `git merge`                 | `jj new A B`              | Creates merge commit             |
| `git fetch`                 | `jj git fetch`            | Fetch from remote                |
| `git push`                  | `jj git push`             | Push bookmarks                   |
| `git branch NAME`           | `jj bookmark create NAME` | Create bookmark                  |
| `git reflog`                | `jj evolog`               | Show previous states of a change |
| N/A                         | `jj op log`               | Show previous operations         |

## Common Workflows

### Starting Work

```bash
# Clone a repo
jj git clone https://github.com/owner/repo

# Or init in existing directory
jj git init --colocate

# Create new change from main
jj new main

# Work on files (no add needed)
# Edit files...

# Describe the change
jj describe -m "feat: add new feature"

# Finish and start next change
jj new
```

### Viewing State

```bash
# Show log with graph
jj log

# Show working copy diff
jj diff

# Show specific revision
jj show @-

# Status of working copy
jj st

# Show file at revision
jj file show path/to/file -r REV
```

### Modifying History

```bash
# Squash working copy into parent
jj squash

# Squash specific change into parent
jj squash -r CHANGE

# Interactive squash (select hunks)
jj squash -i

# Split a commit
jj split

# Edit a commit message
jj describe -r REV -m "new message"

# Edit an older commit
jj edit CHANGE
# Make changes...
jj new # Return to tip
```

### Rebasing

```bash
# Rebase current change onto main
jj rebase -d main

# Rebase branch onto main
jj rebase -b BRANCH -d main

# Rebase revision and descendants
jj rebase -r REV -d DEST

# Rebase source and descendants
jj rebase -s SOURCE -d DEST
```

### Bookmarks and Remotes

```bash
# Create bookmark at current change
jj bookmark create NAME

# Create bookmark at specific revision
jj bookmark create NAME -r REV

# Move bookmark
jj bookmark move NAME -r REV

# List bookmarks
jj bookmark list

# Track remote bookmark
jj bookmark track NAME@origin

# Push bookmark to remote
jj git push --bookmark NAME

# Push all bookmarks
jj git push --all

# Fetch from remote
jj git fetch
```

### Working with GitHub

```bash
# Create PR branch
jj new main
# Work...
jj describe -m "feat: my feature"
jj bookmark create my-feature
jj git push --bookmark my-feature

# Update PR after review
jj edit my-feature
# Make changes...
jj git push --bookmark my-feature

# After merge, clean up
jj git fetch
jj bookmark delete my-feature
```

### Conflict Resolution

Conflicts in Jujutsu don't block rebases - they're recorded in commits.

```bash
# Check for conflicts
jj log # Conflicted commits shown with marker

# Resolve conflicts
jj new CONFLICTED_CHANGE
# Edit conflict markers in files
jj squash # Squash resolution into conflicted change

# Or use resolve command
jj resolve
```

### Undo Operations

```bash
# View operation log
jj op log

# Undo last operation
jj undo

# Restore to specific operation
jj op restore OP_ID
```

## Key Differences from Git

1. **No staging area**: All file changes automatically included
2. **Working copy is a commit**: Always have a "draft" commit
3. **Conflicts don't block**: Rebases complete, conflicts recorded
4. **Change IDs**: Stable references across history rewrites
5. **Operation log**: Full undo capability for any operation
6. **Automatic snapshot**: No risk of losing uncommitted work

## Colocated vs Non-colocated

**Colocated** (`jj git init --colocate`):

- `.git` and `.jj` in same directory
- Can use Git tools alongside jj
- Git sees jj commits

**Non-colocated** (`jj git init`):

- Only `.jj` directory
- Pure jj workflow
- Use `jj git export` to sync to Git

## Additional Resources

### Reference Files

For detailed command reference and advanced workflows:

- **`references/git-command-table.md`** - Complete Git to Jujutsu command
  mapping
- **`references/revsets.md`** - Revset syntax and examples

### External Documentation

- Official docs: https://docs.jj-vcs.dev/latest/
- Tutorial: https://docs.jj-vcs.dev/latest/tutorial/
- GitHub workflow: https://docs.jj-vcs.dev/latest/github/