113 lines
4.5 KiB
Markdown
113 lines
4.5 KiB
Markdown
---
|
|
name: working-with-jj
|
|
description: Expert guidance for using JJ (Jujutsu) version control system. Use when working with JJ, whatever the subject. Operations, revsets, templates, TODO commit workflows, debugging change evolution, etc. Covers JJ commands, template system, evolog, operations log, and specific JJ workflows.
|
|
---
|
|
|
|
# JJ (Jujutsu) Version Control Helper
|
|
|
|
## Core Principles
|
|
|
|
- **Change IDs** (immutable) vs **Commit IDs** (content-based hashes that change
|
|
on edit)
|
|
- **Operations log** - every operation can be undone with `jj op restore`
|
|
- **No staging area** - working copy auto-snapshots
|
|
- **Conflicts don't block** - resolve later
|
|
- **Commits are lightweight** - edit freely
|
|
|
|
## Essential Commands
|
|
|
|
```bash
|
|
jj log -r <revset> # View history
|
|
jj evolog -r <rev> --git # Change evolution (with diffs)
|
|
jj new <base> # Create revision and edit it
|
|
jj new --no-edit <base> # Create without switching (for TODOs)
|
|
jj edit <rev> # Switch to editing revision
|
|
jj desc -r <rev> -m "text" # Set description
|
|
|
|
jj diff # Changes in @
|
|
jj diff -r <rev> # Changes in revision
|
|
jj restore <path> # Discard changes to file
|
|
jj restore --from <rev> <path> # Restore from another revision
|
|
|
|
jj split -r <rev> # Split into multiple commits
|
|
jj squash # Squash @ into parent
|
|
jj squash --into <dest> # Squash @ into specific revision
|
|
jj absorb # Auto-squash into right ancestors
|
|
|
|
jj rebase -s <src> -d <dest> # Rebase with descendants
|
|
jj rebase -r <rev> -d <dest> # Rebase single revision only
|
|
```
|
|
|
|
## Quick Revset Reference
|
|
|
|
```bash
|
|
@, @-, @-- # Working copy, parent, grandparent
|
|
::@ # Ancestors
|
|
mine() # Your changes
|
|
conflict() # Has conflicts
|
|
description(substring:"text") # Match description
|
|
A | B, A & B, A ~ B # Union, intersection, difference
|
|
```
|
|
|
|
See `references/revsets.md` for comprehensive revset patterns.
|
|
|
|
## Common Pitfalls
|
|
|
|
### 1. Use `-r` not `--revisions`
|
|
|
|
```bash
|
|
jj log -r xyz # ✅
|
|
jj log --revisions xyz # ❌
|
|
```
|
|
|
|
### 2. Use `--no-edit` for parallel branches
|
|
|
|
```bash
|
|
jj new parent -m "A"; jj new parent -m "B" # ❌ B is child of A!
|
|
jj new --no-edit parent -m "A"; jj new --no-edit parent -m "B" # ✅ Both children of parent
|
|
```
|
|
|
|
### 3. Quote revsets in shell
|
|
|
|
```bash
|
|
jj log -r 'description(substring:"[todo]")' # ✅
|
|
```
|
|
|
|
## Scripts
|
|
|
|
Helper scripts in `scripts/`. Add to PATH or invoke directly.
|
|
|
|
| Script | Purpose |
|
|
| ----------------------------------------- | -------------------------------------- |
|
|
| `jj-show-desc [REV]` | Get description only |
|
|
| `jj-show-detailed [REV]` | Detailed info with git diff |
|
|
| `jj-todo-create <PARENT> <TITLE> [DESC]` | Create TODO (stays on @) |
|
|
| `jj-todo-done [NEXT_REV]` | Complete current TODO, start next |
|
|
| `jj-flag-update <REV> <TO_FLAG>` | Update status flag (auto-detects current) |
|
|
| `jj-find-flagged [FLAG]` | Find flagged revisions |
|
|
| `jj-parallel-todos <PARENT> <T1> <T2>...` | Create parallel TODOs |
|
|
| `jj-desc-transform <REV> <CMD...>` | Pipe description through command |
|
|
| `jj-batch-desc <SED_FILE> <REV...>` | Batch transform descriptions |
|
|
| `jj-checkpoint [NAME]` | Record op ID before risky operations |
|
|
|
|
These scripts are notably useful if you are working using a _"TODO Commit
|
|
Workflow"_: see `references/todo-workflow.md` for structured TODO planning,
|
|
parallel task DAGs, and AI-assisted workflows.
|
|
|
|
## Recovery
|
|
|
|
```bash
|
|
jj op log # Find operation before problem
|
|
jj op restore <op-id> # Restore to that state
|
|
```
|
|
|
|
## References
|
|
|
|
- `references/todo-workflow.md` - Structured TODO planning, parallel DAGs, AI
|
|
workflows
|
|
- `references/revsets.md` - Full revset syntax and patterns
|
|
- `references/templates.md` - Template language and custom output
|
|
- `references/git-remotes.md` - Bookmarks, push/fetch, remote workflows
|
|
- `references/command-syntax.md` - Command flag details
|
|
- `references/batch-operations.md` - Complex batch transformations
|