Initial commit

skills/working-with-jj/references/command-syntax.md

@@ -0,0 +1,211 @@
+# 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*")'` |