Initial commit

skills/git-jj/references/jj_revset.md

@@ -0,0 +1,87 @@
+# JJ Revset Language Reference
+
+Source: https://docs.jj-vcs.dev/latest/revsets/
+
+Revsets select sets of revisions for inspection, history manipulation, and automation.
+
+## Atoms
+
+| Atom | Meaning |
+|------|---------|
+| `@` | Working-copy commit |
+| `<commit-id>` | Specific commit (short/full hex) |
+| `<change-id>` | Latest visible commit for change |
+| `<bookmark>` | Bookmark target |
+| `<bookmark>@<remote>` | Remote bookmark snapshot |
+| `root()` | Virtual root |
+| `trunk()` | Main branch |
+
+## Operators
+
+| Syntax | Meaning |
+|--------|---------|
+| `X::` | Ancestors of X (inclusive) |
+| `::X` | Descendants of X (inclusive) |
+| `A..B` | Reachable from B but not A |
+| `A \| B` | Union |
+| `A & B` | Intersection |
+| `A - B` | Difference |
+
+## Functions
+
+| Function | Purpose |
+|----------|---------|
+| `all()` | All commits (visible + hidden) |
+| `visible()` | Non-abandoned commits |
+| `ancestors(X)` / `descendants(X)` | Ancestry traversal |
+| `parents(X)` / `children(X)` | Direct relatives |
+| `heads(X)` | Commits with no descendants in X |
+| `author("name")` | By author substring |
+| `description("regex")` | By description regex |
+| `file("path")` | Commits affecting path |
+| `present(X)` | Filter to visible form |
+
+## Common Patterns
+
+```bash
+# Work since branching from main
+main..@
+
+# Commits affecting file
+descendants(main) & file("src/lib.rs")
+
+# Ahead of remote (push candidates)
+feature - feature@origin
+
+# Behind remote (need to pull)
+feature@origin - feature
+
+# Find WIP commits
+description("WIP") & ::@
+
+# Filter by author
+author("alice") & main..@
+
+# Divergent heads (conflicts)
+heads(<change-id>)
+
+# Hidden/abandoned commits
+all() - visible()
+```
+
+## File Filtering
+
+```bash
+file("src/")                              # Commits under src/
+file("src/") - file("src/test/")          # Exclude test dir
+descendants(main) & file("*.rs")          # Rust files since main
+```
+
+## Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| `A..B` direction confusion | B's ancestors minus A's ancestors |
+| Using `all()` unnecessarily | Use `visible()` for normal queries |
+| Hidden commits not showing | Use `all()` or `present()` |
+| Shell expansion | Quote paths and regex |