Jujutsu (jj) is a Git-compatible VCS that eliminates common Git pain points. It's designed for safety, simplicity, and powerful history manipulation.
1. Working Copy Is Always a Commit
Unlike Git, your working copy state is always a commit in jj. Every file change is automatically tracked in the current commit—no staging area, no git add. When you run most jj commands, changes are auto-committed.
# In Git: edit → add → commit
# In jj: edit → done (auto-committed)
2. Change IDs vs Commit IDs
Every commit has two identifiers:
- Change ID: Stable across rewrites (use this daily)
- Commit ID: Changes when commit is rewritten (like Git's SHA)
Use change IDs in your workflow—they survive rebases and amends.
3. Operations Are Always Reversible
The operation log records every action. Made a mistake? jj undo reverses it. Need to see what happened? jj op log shows everything.
4. Conflicts Are First-Class
Conflicts don't block operations. They're recorded in commits and can be resolved later. No more "rebase in progress" states.
5. Automatic Rebasing
When you edit a commit, all descendants automatically rebase on top of the modified version. Bookmarks and working copy update automatically.
Essential Commands:
| Task |
Command |
| Status |
jj st |
| Diff |
jj diff |
| Log |
jj log |
| Describe commit |
jj describe -m "message" |
| Create new commit |
jj new |
| Squash into parent |
jj squash |
| Edit any commit |
jj edit <change-id> |
| Undo last operation |
jj undo |
Working with Git repos:
# Clone
jj git clone <url>
# Init in existing Git repo (colocated)
jj git init --colocate
# Fetch and push
jj git fetch
jj git push
- Get started (clone, init, basic setup)
- Make changes (daily development workflow)
- Work with history (edit, split, squash, rebase)
- Resolve conflicts
- Collaborate (GitHub, push, pull, PRs)
- Recover from mistakes (undo, operation log)
- Understand a concept or command
Wait for response before proceeding.
After reading the workflow, follow it exactly.
After every operation, verify state:
# 1. Check current state
jj st
# 2. View recent history
jj log -r 'ancestors(@, 5)'
# 3. If issues, check operation log
jj op log
Report to user:
- Current commit and its description
- Any conflicts present
- Any pending changes
Core Knowledge in references/:
| File |
Contents |
| core-concepts.md |
Working copy, change IDs, automatic rebasing |
| git-command-mapping.md |
Git → jj command translation table |
| revsets.md |
Selecting commits with the revset language |
| bookmarks.md |
Named pointers (like Git branches) |
| common-patterns.md |
Typical workflows and patterns |
| troubleshooting.md |
Common issues and solutions |
Workflows in workflows/:
| File |
Purpose |
| getting-started.md |
Initialize repos, clone, basic setup |
| make-changes.md |
Daily development workflow |
| work-with-history.md |
Edit, split, squash, rebase commits |
| resolve-conflicts.md |
Handle and resolve conflicts |
| collaborate-github.md |
Push, pull, PRs, remote workflows |
| recover-mistakes.md |
Undo operations, restore state |
A successful jj operation:
- Completes without unexpected conflicts
- Maintains clean history (descriptive commit messages)
- Keeps working copy in expected state
- Can be undone if needed via
jj undo
1---2name: jujutsu-vcs3description: Guide AI agents to use Jujutsu (jj) for version control. Covers core concepts, daily workflows, Git compatibility, conflict resolution, and collaboration with GitHub. Use this skill when working with jj repositories or when the user wants to use Jujutsu instead of Git.4---56<essential_principles>78**Jujutsu (jj) is a Git-compatible VCS that eliminates common Git pain points.** It's designed for safety, simplicity, and powerful history manipulation.910**1. Working Copy Is Always a Commit**1112Unlike Git, your working copy state is always a commit in jj. Every file change is automatically tracked in the current commit—no staging area, no `git add`. When you run most jj commands, changes are auto-committed.1314```bash15# In Git: edit → add → commit16# In jj: edit → done (auto-committed)17```1819**2. Change IDs vs Commit IDs**2021Every commit has two identifiers:22- **Change ID**: Stable across rewrites (use this daily)23- **Commit ID**: Changes when commit is rewritten (like Git's SHA)2425Use change IDs in your workflow—they survive rebases and amends.2627**3. Operations Are Always Reversible**2829The operation log records every action. Made a mistake? `jj undo` reverses it. Need to see what happened? `jj op log` shows everything.3031**4. Conflicts Are First-Class**3233Conflicts don't block operations. They're recorded in commits and can be resolved later. No more "rebase in progress" states.3435**5. Automatic Rebasing**3637When you edit a commit, all descendants automatically rebase on top of the modified version. Bookmarks and working copy update automatically.3839</essential_principles>4041<quick_reference>4243**Essential Commands:**44| Task | Command |45|------|---------|46| Status | `jj st` |47| Diff | `jj diff` |48| Log | `jj log` |49| Describe commit | `jj describe -m "message"` |50| Create new commit | `jj new` |51| Squash into parent | `jj squash` |52| Edit any commit | `jj edit <change-id>` |53| Undo last operation | `jj undo` |5455**Working with Git repos:**56```bash57# Clone58jj git clone <url>5960# Init in existing Git repo (colocated)61jj git init --colocate6263# Fetch and push64jj git fetch65jj git push66```6768</quick_reference>6970<intake>71**What would you like to do with Jujutsu?**72731. Get started (clone, init, basic setup)742. Make changes (daily development workflow)753. Work with history (edit, split, squash, rebase)764. Resolve conflicts775. Collaborate (GitHub, push, pull, PRs)786. Recover from mistakes (undo, operation log)797. Understand a concept or command8081**Wait for response before proceeding.**82</intake>8384<routing>85| Response | Workflow |86|----------|----------|87| 1, "start", "clone", "init", "setup" | `workflows/getting-started.md` |88| 2, "change", "edit", "commit", "develop", "daily" | `workflows/make-changes.md` |89| 3, "history", "rebase", "split", "squash", "amend" | `workflows/work-with-history.md` |90| 4, "conflict", "merge", "resolve" | `workflows/resolve-conflicts.md` |91| 5, "github", "push", "pull", "pr", "collaborate", "remote" | `workflows/collaborate-github.md` |92| 6, "undo", "mistake", "recover", "oops", "operation" | `workflows/recover-mistakes.md` |93| 7, "concept", "understand", "what is", "how does" | Route to relevant reference file |9495**After reading the workflow, follow it exactly.**96</routing>9798<verification_loop>99100After every operation, verify state:101102```bash103# 1. Check current state104jj st105106# 2. View recent history107jj log -r 'ancestors(@, 5)'108109# 3. If issues, check operation log110jj op log111```112113Report to user:114- Current commit and its description115- Any conflicts present116- Any pending changes117118</verification_loop>119120<reference_index>121122**Core Knowledge** in `references/`:123124| File | Contents |125|------|----------|126| core-concepts.md | Working copy, change IDs, automatic rebasing |127| git-command-mapping.md | Git → jj command translation table |128| revsets.md | Selecting commits with the revset language |129| bookmarks.md | Named pointers (like Git branches) |130| common-patterns.md | Typical workflows and patterns |131| troubleshooting.md | Common issues and solutions |132133</reference_index>134135<workflows_index>136137**Workflows** in `workflows/`:138139| File | Purpose |140|------|---------|141| getting-started.md | Initialize repos, clone, basic setup |142| make-changes.md | Daily development workflow |143| work-with-history.md | Edit, split, squash, rebase commits |144| resolve-conflicts.md | Handle and resolve conflicts |145| collaborate-github.md | Push, pull, PRs, remote workflows |146| recover-mistakes.md | Undo operations, restore state |147148</workflows_index>149150<success_criteria>151152A successful jj operation:153- Completes without unexpected conflicts154- Maintains clean history (descriptive commit messages)155- Keeps working copy in expected state156- Can be undone if needed via `jj undo`157158</success_criteria>
cercova-studios