---
name: jj-vcs
description: Using jj (Jujutsu) for version control. Make sure to use this skill whenever the user mentions jj, jujutsu, version control, commits, branches/bookmarks, rebasing, history rewriting, cloning/pushing/pulling, or any VCS workflow — even when they don't explicitly say "jj." This skill covers daily editing, history restructuring, collaboration with remotes, and recovery from mistakes. When the user's repository uses jj (look for a .jj/ directory), ALWAYS use jj commands instead of git commands.
allowed-tools: Bash(jj:*)
license: MIT
metadata:
  author: OpticLM
  version: "0.41.0.2"
---

## Core mental model

jj is a Git-compatible version control system built around *changes* (revisions) that evolve over time. Each change has a **change ID** (stable — follows the change across rebases) and a **commit hash** (changes whenever the commit content changes). Refer to changes by their change ID (short prefix form) when you want to track a logical change, or by commit hash when pinning exact content.

Key differences from Git:
- **No staging area.** The working copy (`@`) is itself a commit. `jj status` compares `@` to its parent. Changes to tracked files are automatically part of `@`.
- **Change IDs**, not branch names, are the primary way history is organized. A commit's change ID survives rebase, squash, and split.
- **Operation log.** Every jj command creates an operation. `jj undo` simply undoes the last operation. `jj op log` shows the full history of commands run. Nothing is lost unless you explicitly garbage-collect.
- **Bookmarks, not branches.** Bookmarks are labels on revisions. To move a bookmark to point at a different revision, use `jj bookmark move`. Git branches are just bookmarks that jj syncs to the remote.
- **Revsets.** jj's revision selection language. Used everywhere commands accept revisions. Learn the common patterns (see core-concepts.md).

---

## Finding the right command

### Daily work loop

The core cycle is: **start a change → make edits → describe → (optionally) start the next change.**

| Intent | Command |
|---|---|
| See what's changed in `@` | `jj status` (aliases: `st`) |
| See file-level diff | `jj diff` (use `--git` for git-style output, `-s` for summary) |
| Start a new change on top of `@` | `jj new [REVISION]` (defaults to `@`) |
| Describe/set the commit message | `jj describe -m "msg"` or `jj describe` (opens editor) |
| Describe + start next change | `jj commit -m "msg"` (equivalent to `describe -m && new`) |
| View revision graph | `jj log` (use `-r` with a revset to filter, `-p` for patch) |
| Browse file in older revision | `jj file show -r REV PATH` |

`jj new` is the primary way to create changes. It creates an empty child of the given revision and makes it the new `@`. Unlike `git checkout -b`, it does not need a branch name.

When the user says "commit my changes" they almost always mean `jj describe -m "message"` to record a message on the current change, or `jj commit -m "message"` to record and start a new empty change on top.

### History restructuring

jj makes rewriting history safe because nothing is truly lost (the operation log preserves everything).

| Intent | Command |
|---|---|
| Move a change to a different parent | `jj rebase -r REV -o NEW_PARENT` |
| Move a whole branch of changes | `jj rebase -b REV -o NEW_PARENT` |
| Absorb changes from `@` into parent | `jj squash` (moves `@`'s diff into its parent) |
| Squash specific changes into sibling | `jj squash -f FROM_REV -t INTO_REV` |
| Split a revision in two | `jj split [-r REV]` (interactive by default) |
| Drop a change entirely | `jj abandon [-r REV]` (defaults to `@` if empty) |
| Rename/edit a change's description | `jj describe -r REV -m "new message"` |
| Edit a change's metadata (author, etc.) | `jj metaedit -r REV` |
| Pull edits from child into parent | `jj absorb` (auto-detects where changes belong) |
| Reorder siblings into a chain | `jj parallelize -r REVS...` |
| Interactive graph rearrangement | `jj arrange` |
| Touch up a change's content diff | `jj diffedit -r REV` |

**Common squash patterns:**
- `jj squash` — squash `@` into its parent (the most common: you made a small fix that belongs in the previous commit)
- `jj squash -f FEATURE_REV -t MAIN` — move changes from a feature revision into main

**Common rebase patterns:**
- `jj rebase -r REV -o DEST` — rebase a single revision onto DEST
- `jj rebase -b REV -o DEST` — rebase REV and all its descendants onto DEST
- `jj rebase -r REV --insert-after ANCHOR` — reorder REV to come after ANCHOR (useful for reordering commits in a stack)
- `jj rebase -r REV --insert-before ANCHOR`

When rebasing after a squash/split/abandon, jj automatically rebases descendants. You rarely need to manually restack.

### Collaboration

jj interoperates with Git remotes. The workflow is: fetch → rebase → push.

| Intent | Command |
|---|---|
| Clone a remote repo | `jj git clone <URL>` |
| Fetch from remote | `jj git fetch [--remote NAME]` |
| Push to remote | `jj git push [--remote NAME]` |
| List bookmarks and their targets | `jj bookmark list` (aliases: `b l`) |
| Track a remote bookmark as local | `jj bookmark track NAME --remote origin` |
| Move a bookmark to point at a revision | `jj bookmark move --to REV BOOKMARK` (aliases: `b m -t REV BOOKMARK`) |
| Create a new bookmark | `jj bookmark create NAME` |
| List remotes | `jj git remote list` |
| Add a remote | `jj git remote add NAME URL` |

**Push workflow:**
1. Ensure the bookmark you want to push points at your revision: `jj bookmark move --to=@ BOOKMARK`
2. Push: `jj git push`
3. If the remote has new commits: `jj git fetch` then `jj rebase -b BOOKMARK -o BOOKMARK@origin`

**Important:** Before pushing, always check the change has a description. `jj git push` will fail or warn you if a change lacks a description. Use `jj describe -m "msg"` first.

### Recovery

| Intent | Command |
|---|---|
| Undo the last operation | `jj undo` |
| Redo an undo | `jj redo` |
| See operation history | `jj op log` |
| Restore repo to a past state | `jj op restore OPERATION_ID` |
| Restore files in `@` (undo edits in wd) | `jj restore` (restores all files from parent) |
| Restore specific paths from another revision | `jj restore --from SOURCE_REV PATH...` |
| Undo the changes introduced by a commit | `jj restore --changes-in REV` (creates a reverse of REV on top of @, effectively undoing its changes) |
| Resolve conflicts | `jj resolve PATH...` (opens external merge tool) |
| Inspect old repo state without restoring | `jj --at-op OPERATION_ID status` |

`jj undo` is the first thing to reach for when something goes wrong. If you need to undo farther back, `jj op log` + `jj op restore` can take you to any previous state.

---

## Git-to-jj translation

When a user asks for a git command, translate to the equivalent jj command:

| Git | jj |
|---|---|
| `git add FILE` | Edit FILE (no staging needed — tracked files auto-included) |
| `git commit -m "msg"` | `jj describe -m "msg"` (or `jj commit -m "msg"` to also start a new change) |
| `git commit --amend` | `jj squash` (move `@`'s changes into its parent) |
| `git checkout BRANCH` | `jj new BOOKMARK` |
| `git checkout -b BRANCH` | `jj new` then `jj bookmark create NAME` |
| `git branch -d BRANCH` | `jj bookmark delete NAME` |
| `git rebase main` | `jj rebase -b @ -o MAIN` |
| `git reset HEAD~1` | `jj restore` then `jj abandon @` |
| `git revert COMMIT` | `jj restore --changes-in COMMIT` |
| `git log --oneline` | `jj log --no-graph` |
| `git stash` | Not needed — just `jj new` to start fresh on top, or `jj bookmark create` to save the current state |

---

## Choosing the right ancestor (`-o`) vs insert-after (`-A`) vs insert-before (`-B`)

- `-o` / `--onto`: makes the source revision(s) children of the target. Most common.
- `-A` / `--insert-after`: inserts the source revision(s) *after* the target, making them siblings of the target's current children. Use when reordering within a stack.
- `-B` / `--insert-before`: inserts the source revision(s) *before* the target, making them parents of the target. Use when you want to add a step before an existing commit.

These options appear on `rebase`, `new`, `split`, `squash`, and `restore`.

---

## Reference files

Read these for deeper guidance on specific workflows:

- **references/core-concepts.md** — Revsets, change IDs, working copy mechanics, configuration
- **references/daily-work.md** — Commands and patterns for the daily edit/describe/log loop
- **references/history-rewriting.md** — Detailed squash, rebase, split, abandon, and absorb patterns
- **references/collaboration.md** — Pushing, pulling, bookmark management, Gerrit
- **references/recovery.md** — Undo, operation log, conflict resolution, and restore
- **references/commands.md** — Quick reference for every jj command with key flags