jujutsu

Files (15)

• SKILL.md
• openai.yaml · agents/
• COLOCATED.md · references/
• COMMIT_MSG.md · references/
• CONFLICTS.md · references/
• GOTCHAS.md · references/
• NEW_CHANGE.md · references/
• NONLINEAR.md · references/
• PUSH.md · references/
• QUERY_LANGUAGES.md · references/
• RECOVERY.md · references/
• REFINE_COMMIT.md · references/
• REMOTES.md · references/
• TEMPLATES.md · references/
• WORKSPACES.md · references/

SKILL.md (first lines)

# Jujutsu (jj) Version Control System

This skill helps you work with Jujutsu, a Git-compatible VCS with mutable commits and automatic rebasing.

**Tested with jj v0.41.0** - Commands may differ in other versions.

For token-sensitive inspection commands, prefer the compact commands in `references/TEMPLATES.md` over jj's default output.

The compact commands in `references/TEMPLATES.md` intentionally use `jj --no-pager ...`.

For revsets, filesets, and template syntax, see `references/QUERY_LANGUAGES.md`.

For sibling or unrelated work that should start from `trunk()`, see `references/NONLINEAR.md`.

For common surprises and easy mistakes, see `references/GOTCHAS.md`.

<!--
Attribution and inspiration sources:

- Forked from danverbraganza/jujutsu-skill (https://skills.sh/danverbraganza/jujutsu-skill/jujutsu).
  The original scaffolding, references/ structure, and core mental-model wording are from there.

- Enforcement language in "Critical: never use git for mutations" was tightened using the
  read-only-git allowlist pattern from knoopx/pi@jujutsu
  (https://skills.sh/knoopx/pi/jujutsu).

- "Parallel Workspaces" framing as a tool for multi-agent isolation draws on
  onevcat/skills@onevcat-jj (https://skills.sh/onevcat/skills/onevcat-jj),
  which is explicitly subtitled "Version Control for Agent Workflows".

- The .workspaces/ project-local directory convention, the .gitignore safety check,
  and the directory-selection priority documented in references/WORKSPACES.md
  come from edmundmiller/dotfiles using-jj-workspaces
  (https://lobehub.com/skills/edmundmiller-dotfiles-using-jj-workspaces).

- The "op log records every mutation; nothing is ever truly lost" framing in the
  Recovery section is adapted from trevors/dot-claude@jj-workflow
  (https://skills.sh/trevors/dot-claude/jj-workflow).

- Query-language guidance, nonlinear-work patterns, and workspace handoff /
  monitoring ideas were adapted from joshuadavidthomas/agent-skills `jj`
  (https://github.com/joshuadavidthomas/agent-skills/tree/main/jj) and its
  `workspaces.md`
  (https://raw.githubusercontent.com/joshuadavidthomas/agent-skills/main/jj/workspaces.md),
  while intentionally preserving this skill's local describe-first workflow and
  `.workspaces/` / `workspaces/` directory priority.
-->


## Detecting a jj repo

Check whether a directory is part of a jj repo:

```bash
jj root
```

If it returns a path, the repo is jj-managed. If it returns `Error: There is no jj repo in <directory>`, it isn't. The presence of a `.jj/` folder is another giveaway. If the repo is not a jj one, do not further use this skill.

<!-- Enforcement wording (allowed/forbidden split with read-only git allowlist) adapted from knoopx/pi@jujutsu. -->
## Critical: never use git for mutations in a jj repo

In a jj repo (including co-located repos that also have `.git/`):

- **Forbidden** (corrupts jj state): `git commit`, `git add`, `git stash`, `git reset`, `git checkout <branch>`, `git switch`, `git rebase`, `git merge`, `git cherry-pick`, `git push`, `git pull`.
- **Allowed** (read-only): `git log`, `git show`, `git diff`, `git blame`, `git grep`, `git status`. Prefer the `jj` equivalents (`jj log`, `jj show`, `jj diff`, etc.) but read-only git commands won't break anything.
- **Use jj instead**: `jj git push`, `jj git fetch`, `jj edit <change>` (not `git checkout`), `jj rebase`, `jj new <a> <b>` (for merges).

See `references/COLOCATED.md` for the full co-located repo workflow.

## Important: Automated/Agent Environment

When running as an agent or running on behalf of the user:

1. **Always use `-m` flags** to provide commit messages inline rather than relying on editor prompts:

```bash
# Always use -m to avoid editor prompts
jj desc -m "message"               # NOT: jj desc
jj squash --into @- -m "message"   # NOT: jj squash (which opens editor or prompts for hunks)
```

Editor-based commands will fail in non-interactive environments.

2. **Verify operations with `jj st`** after mutations (`squash`, `abandon`, `rebase`, `restore`) to confirm the operation succeeded.

## Important Principles

1. Each commit should represent one logical change. See [commit messages](references/COMMIT_MSG.md) for details on good commit messages. Before starting work on a new change, make sure the working copy is clean (no changes)

```bash
jj st
```

## Core Concepts

### The Working Copy is a Commit

In jj, your working directory is always a commit (referenced as `@`). Changes are automatically snapshotted when you run any jj command. There is no staging area.

There is no need to run `jj commit`.

### Commits Are Mutable

**CRITICAL**: Unlike git, jj commits can be freely modified. This enables a high-quality commit workflow:

1. Before starting work, run `jj st`. If `@` already has changes, run `jj new` first. If `@` is empty, use it as-is.
2. Describe your intended changes with `jj desc -m "Message"`
3. Make your changes.
4. Do NOT run `jj new` when finished — leave that to the next task's step 1.

You may refine the commit using `jj squash` or `jj absorb` as needed

### Change IDs vs Commit IDs

- **Change ID**: A stable identifier (like `tqpwlqmp`) that persists when a commit is rewritten
- **Commit ID**: A content hash (like `3ccf7581`) that changes when commit content changes

Prefer using Change IDs when referencing commits in commands.

From johnstegeman/ai-skills, Apache-2.0.

More from johnstegeman/ai-skills