212 lines
4.8 KiB
Markdown
212 lines
4.8 KiB
Markdown
# JJ Command Syntax Reference
|
|
|
|
## The `-r` Flag Confusion
|
|
|
|
JJ commands are **inconsistent** with flag naming, which can be confusing:
|
|
|
|
### Commands Using `-r` (Most Common)
|
|
|
|
```bash
|
|
jj log -r <revset> # ✅ Short form only
|
|
jj desc -r <revset> # ✅ Short form only
|
|
jj show -r <revset> # ✅ Short form only
|
|
jj rebase -r <revset> # ✅ Short form only
|
|
jj edit -r <revset> # ✅ Short form only (no --revision)
|
|
```
|
|
|
|
**Rule:** For most commands, use `-r` and **never** `--revisions` or `--revision`.
|
|
|
|
### Why This Matters
|
|
|
|
```bash
|
|
# ❌ Common mistake: trying long form
|
|
jj desc --revisions xyz
|
|
# Error: unexpected argument '--revisions' found
|
|
|
|
jj log --revision xyz
|
|
# Error: unexpected argument '--revision' found
|
|
|
|
# ✅ Always use short form
|
|
jj desc -r xyz
|
|
jj log -r xyz
|
|
```
|
|
|
|
## Command Patterns
|
|
|
|
### Reading Revision Info
|
|
|
|
```bash
|
|
# Get description only (for processing)
|
|
jj log -r <rev> -n1 --no-graph -T description
|
|
|
|
# Get detailed info (human-readable)
|
|
jj log -r <rev> -n1 --no-graph -T builtin_log_detailed
|
|
|
|
# Get compact one-liner
|
|
jj log -r <rev> -T 'change_id.shortest(4) ++ " " ++ description.first_line()'
|
|
```
|
|
|
|
**Key flags:**
|
|
- `-n1`: Limit to 1 revision
|
|
- `--no-graph`: No ASCII art graph
|
|
- `-T <template>`: Output template
|
|
- `-r <revset>`: Which revision(s)
|
|
|
|
### Modifying Revisions
|
|
|
|
```bash
|
|
# Change description from string
|
|
jj desc -r <rev> -m "New description"
|
|
|
|
# Change description from stdin (for scripts)
|
|
echo "New description" | jj desc -r <rev> --stdin
|
|
|
|
# Change description from file
|
|
jj desc -r <rev> --stdin < /path/to/description.txt
|
|
|
|
# Pipeline pattern
|
|
jj log -r <rev> -n1 --no-graph -T description | \
|
|
sed 's/old/new/' | \
|
|
jj desc -r <rev> --stdin
|
|
```
|
|
|
|
**Key insight:** `--stdin` is essential for scripted modifications.
|
|
|
|
### Creating Revisions
|
|
|
|
```bash
|
|
# Create and edit immediately (moves @)
|
|
jj new <parent> -m "Description"
|
|
|
|
# Create without editing (@ stays put) - IMPORTANT for parallel branches
|
|
jj new --no-edit <parent> -m "Description"
|
|
|
|
# Create with multiple parents (merge)
|
|
jj new --no-edit <parent1> <parent2> -m "Merge point"
|
|
```
|
|
|
|
**Critical distinction:**
|
|
- Without `--no-edit`: Your working copy (@) moves to the new revision
|
|
- With `--no-edit`: New revision created, but @ stays where it was
|
|
|
|
## Revset Syntax
|
|
|
|
### Basic Revsets
|
|
|
|
```bash
|
|
@ # Working copy
|
|
<change-id> # Specific revision (e.g., abc, unxn)
|
|
<commit-id> # By commit hash
|
|
```
|
|
|
|
### Operators
|
|
|
|
```bash
|
|
<rev>::<rev> # Range (from..to, inclusive)
|
|
<rev>.. # All descendants
|
|
..<rev> # All ancestors
|
|
|
|
# Examples
|
|
zyxu::@ # All revisions from zyxu to current
|
|
roww:: # roww and all its descendants
|
|
::@ # All ancestors of @
|
|
```
|
|
|
|
### Functions
|
|
|
|
```bash
|
|
description(glob:"pattern") # Match description
|
|
description(exact:"text") # Exact match
|
|
mine() # Your commits
|
|
```
|
|
|
|
### Combining
|
|
|
|
```bash
|
|
# Union (OR)
|
|
rev1 | rev2
|
|
|
|
# Intersection (AND)
|
|
rev1 & rev2
|
|
|
|
# Example: Your changes in current branch
|
|
mine() & ::@
|
|
```
|
|
|
|
## Shell Quoting
|
|
|
|
Revsets often need quoting because they contain special characters:
|
|
|
|
```bash
|
|
# ❌ Shell interprets glob
|
|
jj log -r description(glob:"[todo]*")
|
|
|
|
# ✅ Single quotes (safest)
|
|
jj log -r 'description(glob:"[todo]*")'
|
|
|
|
# ✅ Double quotes with escaping
|
|
jj log -r "description(glob:\"[todo]*\")"
|
|
```
|
|
|
|
**Rule:** When in doubt, use single quotes around revsets.
|
|
|
|
## Common Patterns
|
|
|
|
### Update Multiple Revisions
|
|
|
|
```bash
|
|
# Pattern: Extract → Transform → Apply
|
|
for rev in a b c; do
|
|
jj log -r "$rev" -n1 --no-graph -T description > /tmp/desc.txt
|
|
# ... transform /tmp/desc.txt ...
|
|
jj desc -r "$rev" --stdin < /tmp/desc.txt
|
|
done
|
|
```
|
|
|
|
### Find and Update
|
|
|
|
```bash
|
|
# Find all [todo] revisions
|
|
jj log -r 'description(glob:"[todo]*")'
|
|
|
|
# Update specific one
|
|
jj log -r xyz -n1 --no-graph -T description | \
|
|
sed 's/\[todo\]/[wip]/' | \
|
|
jj desc -r xyz --stdin
|
|
```
|
|
|
|
### Create Parallel Branches
|
|
|
|
```bash
|
|
# All branch from same parent
|
|
parent=xyz
|
|
jj new --no-edit "$parent" -m "[todo] Branch A"
|
|
jj new --no-edit "$parent" -m "[todo] Branch B"
|
|
jj new --no-edit "$parent" -m "[todo] Branch C"
|
|
```
|
|
|
|
## Debugging
|
|
|
|
```bash
|
|
# Did my command work?
|
|
jj log -r <rev> -T 'change_id ++ " " ++ description.first_line()'
|
|
|
|
# View full description
|
|
jj log -r <rev> -n1 --no-graph -T description
|
|
|
|
# Check revision graph
|
|
jj log -r '<parent>::' -T builtin_log_compact
|
|
```
|
|
|
|
## Quick Reference Card
|
|
|
|
| Task | Command |
|
|
|------|---------|
|
|
| View description | `jj log -r <rev> -n1 --no-graph -T description` |
|
|
| Set description | `jj desc -r <rev> -m "text"` |
|
|
| Set from stdin | `jj desc -r <rev> --stdin` |
|
|
| Create (edit) | `jj new <parent> -m "text"` |
|
|
| Create (no edit) | `jj new --no-edit <parent> -m "text"` |
|
|
| Range query | `jj log -r '<from>::<to>'` |
|
|
| Find pattern | `jj log -r 'description(glob:"pat*")'` |
|