94 lines
2.9 KiB
Markdown
94 lines
2.9 KiB
Markdown
---
|
|
name: Working with Jujutsu Version Control
|
|
description: Understand and work with Jujutsu (jj) version control system. Use when the user mentions commits, changes, version control, or working with jj repositories. Helps with stack-based commit workflows, change curation, and jj best practices.
|
|
allowed-tools: Bash(jj status:*), Bash(jj log:*), Bash(jj show:*), Bash(jj diff:*)
|
|
---
|
|
|
|
# Working with Jujutsu Version Control
|
|
|
|
## Core Concepts
|
|
|
|
**Jujutsu (jj)** - Git-compatible VCS with:
|
|
|
|
- **Change-based**: Unique IDs persist through rewrites
|
|
- **Auto-snapshotting**: Working copy snapshotted before each operation
|
|
- **Stack-based**: Build commits in a stack
|
|
- **Undoable**: All ops in `jj op log`, use `jj op restore` to time travel
|
|
|
|
**vs Git:** No staging area, edit any commit (`jj edit`), conflicts stored in commits
|
|
|
|
## Working Copy (`@`)
|
|
|
|
Current commit is always `@`:
|
|
|
|
- `jj log -r @` - Current commit
|
|
- `jj log -r @-` - Parent commit
|
|
- `jj log -r 'ancestors(@, 5)'` - Recent stack
|
|
|
|
**State:**
|
|
|
|
- Empty, no description → Ready for changes
|
|
- Has changes, no description → Needs description
|
|
- Has description + changes → Can stack with `jj new`
|
|
- Has description, no changes → Ready for new work
|
|
|
|
## Stack-Based Workflow
|
|
|
|
1. Make changes in `@` (new files tracked automatically via `/jj:commit`)
|
|
2. Describe: `jj describe -m "message"` or `/jj:commit`
|
|
3. Stack: `jj new`
|
|
4. Repeat
|
|
|
|
**Why stack:** Individual review, easy reordering, incremental shipping, clean history
|
|
|
|
## Plan-Driven Workflow
|
|
|
|
1. **Start**: Create "plan:" commit describing intent
|
|
2. **Work**: Implement the plan
|
|
3. **End**: Replace "plan:" with actual work using `/jj:commit`
|
|
|
|
**TodoWrite:** One commit per major todo, `jj new` between todos
|
|
|
|
## Automatic Snapshotting
|
|
|
|
Every `jj` command auto-snapshots. Use `jj op log`, `jj undo`, or `jj op restore <id>` for time travel.
|
|
|
|
## When to Suggest Commands
|
|
|
|
**Viewing state:** `jj status`, `jj log`, `jj show`, `jj diff`
|
|
|
|
**Creating commits:**
|
|
|
|
- Use `/jj:commit` (not `jj describe` directly)
|
|
- Suggest when user has substantial changes or plan needs updating
|
|
|
|
**Organizing commits:**
|
|
|
|
- `/jj:split <pattern>` when mixing concerns (tests+code)
|
|
- `/jj:squash` for multiple WIP commits
|
|
- Don't suggest for simple, focused changes
|
|
|
|
**Undoing:** `jj undo`, `jj op restore`, `jj abandon`
|
|
|
|
## Slash Commands
|
|
|
|
- `/jj:commit [message]` - Stack commit with message generation
|
|
- `/jj:split <pattern>` - Split by pattern (test, docs, config)
|
|
- `/jj:squash [revision]` - Merge commits
|
|
- `/jj:cleanup` - Remove empty workspaces
|
|
|
|
## Git Translation
|
|
|
|
Repository blocks git write commands via hook. Prefer jj equivalents:
|
|
|
|
- `git status` → `jj status`
|
|
- `git commit` → `/jj:commit`
|
|
- `git log` → `jj log`
|
|
- `git checkout` → `jj new`
|
|
|
|
## Best Practices
|
|
|
|
**Do:** Stack commits, describe clearly (what/why), use plan-driven workflow, leverage `jj op log`, split mixed concerns
|
|
|
|
**Don't:** Mix git/jj, leave work undescribed, create monolithic commits, forget everything is undoable
|