266 lines
7.0 KiB
Markdown
266 lines
7.0 KiB
Markdown
# 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'
|
|
```
|