Initial commit

2025-11-29 18:17:51 +08:00
commit 70011f3c64
8 changed files with 1940 additions and 0 deletions
--- a/references/revsets.md
+++ b/references/revsets.md
@@ -0,0 +1,265 @@
+# Revsets Reference
+
+Revsets are a functional language for selecting commits in jj. This reference covers all operators, functions, and patterns.
+
+## Table of Contents
+
+- [Basic Symbols](#basic-symbols)
+- [Operators](#operators)
+- [Functions](#functions)
+- [String Patterns](#string-patterns)
+- [Common Patterns](#common-patterns)
+
+## Basic Symbols
+
+| Symbol | Description |
+|--------|-------------|
+| `@` | Working copy commit |
+| `root()` | Repository root (empty commit) |
+| `<change_id>` | Commit by change ID (e.g., `kntqzsqt`) |
+| `<commit_id>` | Commit by commit hash (prefix ok) |
+| `<bookmark>` | Commit at bookmark (e.g., `main`) |
+| `<bookmark>@<remote>` | Remote bookmark (e.g., `main@origin`) |
+| `<tag>` | Commit at tag |
+
+## Operators
+
+### Parent/Child Navigation
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `x-` | Parents of x | `@-` (parent of working copy) |
+| `x+` | Children of x | `main+` (children of main) |
+| `x--` | Grandparents | `@--` |
+| `x++` | Grandchildren | `main++` |
+
+### Ancestry/Descendant
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `::x` | Ancestors of x (inclusive) | `::@` |
+| `x::` | Descendants of x (inclusive) | `main::` |
+| `x::y` | DAG path from x to y | `main::@` |
+| `:x` | Ancestors of x (exclusive) | `:@` (excludes @) |
+| `x:` | Descendants of x (exclusive) | `main:` (excludes main) |
+
+### Range
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `x..y` | Ancestors of y minus ancestors of x | `main..@` |
+| `x..` | Descendants of x minus x | `main..` |
+| `..y` | Ancestors of y minus root | `..@` |
+
+### Set Operations
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `x \| y` | Union (x or y) | `main \| develop` |
+| `x & y` | Intersection (x and y) | `mine() & ::@` |
+| `x ~ y` | Difference (x minus y) | `::@ ~ ::main` |
+| `~x` | Complement (not x) | `~empty()` |
+
+### Grouping
+
+Use parentheses for grouping: `(x | y) & z`
+
+## Functions
+
+### Commit Selection
+
+| Function | Description |
+|----------|-------------|
+| `all()` | All commits |
+| `none()` | Empty set |
+| `visible_heads()` | Visible branch heads |
+| `heads(x)` | Commits in x with no descendants in x |
+| `roots(x)` | Commits in x with no ancestors in x |
+| `latest(x, n)` | Latest n commits from x by committer date |
+
+### Bookmarks and Tags
+
+| Function | Description |
+|----------|-------------|
+| `bookmarks()` | All local bookmark targets |
+| `bookmarks(pattern)` | Bookmarks matching pattern |
+| `remote_bookmarks()` | All remote bookmark targets |
+| `remote_bookmarks(pattern)` | Remote bookmarks matching pattern |
+| `tracked_remote_bookmarks()` | Tracked remote bookmarks |
+| `untracked_remote_bookmarks()` | Untracked remote bookmarks |
+| `tags()` | All tag targets |
+| `tags(pattern)` | Tags matching pattern |
+| `trunk()` | Main branch (main, master, trunk) |
+
+### Author/Committer
+
+| Function | Description |
+|----------|-------------|
+| `author(pattern)` | Commits by matching author name/email |
+| `author_date(pattern)` | Commits by author date |
+| `committer(pattern)` | Commits by committer |
+| `committer_date(pattern)` | Commits by committer date |
+| `mine()` | Commits by configured user |
+
+### Content
+
+| Function | Description |
+|----------|-------------|
+| `description(pattern)` | Match commit description |
+| `description(exact:"text")` | Exact description match |
+| `empty()` | Empty commits (no file changes) |
+| `file(pattern)` | Commits modifying matching files |
+| `diff_contains(pattern)` | Commits with matching diff content |
+
+### Conflicts and Status
+
+| Function | Description |
+|----------|-------------|
+| `conflicts()` | Commits containing conflicts |
+| `signed()` | Cryptographically signed commits |
+| `working_copies()` | All working copy commits |
+
+### Mutability
+
+| Function | Description |
+|----------|-------------|
+| `mutable()` | Commits that can be rewritten |
+| `immutable()` | Protected commits (trunk, tags) |
+| `immutable_heads()` | Heads of immutable commits |
+
+### Ancestry
+
+| Function | Description |
+|----------|-------------|
+| `ancestors(x)` | Same as `::x` |
+| `ancestors(x, depth)` | Ancestors up to depth |
+| `descendants(x)` | Same as `x::` |
+| `descendants(x, depth)` | Descendants up to depth |
+| `connected(x)` | x plus ancestors and descendants within x |
+| `reachable(x, domain)` | Commits reachable from x within domain |
+
+### Structure
+
+| Function | Description |
+|----------|-------------|
+| `parents(x)` | Parents of commits in x |
+| `children(x)` | Children of commits in x |
+| `present(x)` | x if it exists, else empty |
+| `coalesce(x, y)` | x if non-empty, else y |
+
+## String Patterns
+
+Used in functions like `bookmarks()`, `description()`, `author()`:
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `substring:text` | Contains text (default) | `description("fix")` |
+| `exact:text` | Exact match | `description(exact:"")` |
+| `glob:pattern` | Glob pattern | `bookmarks(glob:"feature-*")` |
+| `regex:pattern` | Regular expression | `author(regex:"^J.*")` |
+
+## Common Patterns
+
+### Working with Current Work
+
+```bash
+# My work in progress
+jj log -r 'trunk()..@'
+
+# My recent changes
+jj log -r 'mine() & ancestors(@, 20)'
+
+# Empty commits I made (WIP markers)
+jj log -r 'mine() & empty()'
+
+# Commits with empty descriptions
+jj log -r 'description(exact:"")'
+```
+
+### Branch Operations
+
+```bash
+# Commits on feature branch not on main
+jj log -r 'main..feature'
+
+# All commits on any feature branch
+jj log -r 'bookmarks(glob:"feature-*")::'
+
+# Diverged commits
+jj log -r 'heads(trunk()..)'
+```
+
+### Finding Commits
+
+```bash
+# Commits touching specific file
+jj log -r 'file("src/main.rs")'
+
+# Commits containing "TODO" in diff
+jj log -r 'diff_contains("TODO")'
+
+# Commits by specific author
+jj log -r 'author("alice@")'
+
+# Commits from last week
+jj log -r 'committer_date(after:"1 week ago")'
+```
+
+### Conflicts
+
+```bash
+# All conflicted commits
+jj log -r 'conflicts()'
+
+# Conflicted commits in my branch
+jj log -r 'conflicts() & trunk()..@'
+```
+
+### Rebasing Patterns
+
+```bash
+# Rebase entire branch onto trunk
+jj rebase -s 'roots(trunk()..@)' -d trunk()
+
+# Rebase all mutable descendants
+jj rebase -s 'roots(mutable())' -d <dest>
+
+# Find commits to squash (empty changes)
+jj log -r 'empty() & trunk()..@'
+```
+
+### Working Copies (Multiple Workspaces)
+
+```bash
+# All working copy commits
+jj log -r 'working_copies()'
+
+# Current workspace's working copy
+jj log -r '@'
+```
+
+## Date Patterns
+
+For `author_date()` and `committer_date()`:
+
+| Pattern | Example |
+|---------|---------|
+| `after:date` | `author_date(after:"2024-01-01")` |
+| `before:date` | `committer_date(before:"yesterday")` |
+| Relative | `"1 week ago"`, `"2 days ago"` |
+| Absolute | `"2024-06-15"`, `"2024-06-15T10:30:00"` |
+
+## Combining Expressions
+
+Complex queries combine operators and functions:
+
+```bash
+# My non-empty commits on feature branch, excluding conflicts
+jj log -r '(mine() & feature::@) ~ (empty() | conflicts())'
+
+# Latest 5 commits touching src/ by any author
+jj log -r 'latest(file("src/**"), 5)'
+
+# All commits between two tags
+jj log -r 'v1.0::v2.0'
+```