Jj

Jujutsu (jj) Version Control Guide

CRITICAL: This is NOT git

This repository uses jujutsu (jj) as its version control system, NOT git.

• NEVER use git commands (git add, git commit, git push, git branch, etc.)
• Using git commands directly can corrupt the repository state
• jj manages the underlying git repository internally — all operations go through jj

Git to jj Mapping

If you know git, use this table to find the jj equivalent:

| Git command | jj equivalent | Notes | | --- | --- | --- | | git status | jj status | Show changed files | | git diff | jj diff | Show working copy changes | | git log | jj log | Show commit history | | git show | jj show | Show a specific commit | | git add + git commit | jj describe -m "msg" | No staging needed; changes are auto-tracked | | git branch | jj bookmark create | Bookmarks replace branches | | git checkout -b | jj new + jj bookmark create | Create new change, then bookmark it | | git push | jj git push -b | Must specify bookmark | | git pull | jj git fetch + jj rebase -o main@origin | Fetch then rebase | | git stash | Not needed | Every change is already a commit | | git rebase -i | jj rebase -o | Non-interactive by default | | git reset | jj restore / jj abandon | Restore files or abandon changes |

Commands to Avoid

| Command | Status | Reason | Use instead | | --- | --- | --- | --- | | git * | PROHIBITED | jj is the VCS; git commands can corrupt state | Corresponding jj command | | jj commit | PROHIBITED | Splits working copy in confusing ways | jj new + jj describe | | jj squash -r | RESTRICTED | Risk of merging into unintended commit | Only bare jj squash (squash into parent) is allowed |

jj squash without -r is safe — it squashes the current change into its parent, which is a common and useful operation.

Reading Repository State

jj status          # Changed files in working copy
jj diff            # Diff of working copy changes
jj diff -r    # Diff of a specific revision
jj log             # Commit history (default revset)
jj log -r 'all()'  # Full history
jj show            # Show current commit details
jj show       # Show specific commit details

Core Workflow

1. Create a New Change

jj new              # Create a new empty change on top of current
jj new -m "msg"     # Create with initial description

2. Edit Files

Make your changes. jj automatically tracks all file modifications — no git add needed.

3. Describe the Change

jj describe -m "What you did and why"

Push Operations

Push to a Feature Bookmark (Branch)

# If bookmark does not exist yet:
jj bookmark create  -r @
jj git push -b 

# If bookmark already exists (e.g., pushing additional changes):
jj bookmark set  -r @
jj git push -b 

Push to main

jj new                               # Create next working space first
jj bookmark set main -r @-           # Point main to the completed change
jj git push -b main

Why @-? After jj new, the completed work is in the parent (@-), and the current change (@) is the new empty working space.

Troubleshooting

Push blocked by empty commits

If jj git push fails because a commit has no description, find and remove the empty commit:

jj log                               # Find the empty change-id
jj abandon                # Remove it (children are auto-rebased)

Nix flake does not recognize new files

Nix flakes only see files tracked by the VCS. To make jj track a new file:

jj describe -m "description"         # Commit current state
jj new                               # New files are now in a parent commit, visible to git

More commands and details

See [references/command-reference.md](references/command-reference.md) for:

• Full command quick-reference table
• Workspace and bookmark management
• Conflict resolution procedures
• Undo and recovery operations
• Advanced operations (rebase, split, squash)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: megumish
• Source: megumish/jj-skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.