92 lines
2.6 KiB
Markdown
92 lines
2.6 KiB
Markdown
# Query Languages
|
|
|
|
Use jj's query languages when you need to select revisions, paths, or render compact output without falling back to the default verbose UI.
|
|
|
|
**Tested with jj 0.41.0**
|
|
|
|
## Revsets
|
|
|
|
Use revsets to select commits and workspaces.
|
|
|
|
Common selectors:
|
|
|
|
- `@`: current working-copy change
|
|
- `@-`: parent of the current working-copy change
|
|
- `trunk()`: configured mainline; use this instead of guessing `main` vs `master`
|
|
- `::@`: all ancestors of `@`
|
|
- `trunk()..@`: work reachable from `@` that is not on `trunk()`
|
|
- `working_copies()`: all workspace working-copy commits
|
|
- `<workspace>@`: another workspace's working-copy commit
|
|
- `<change-id>`: a stable change ID such as `wqzktpqm`
|
|
|
|
Agent patterns:
|
|
|
|
```bash
|
|
# Current work relative to trunk
|
|
jj --no-pager log -r 'trunk()..@'
|
|
|
|
# All active workspace tips
|
|
jj --no-pager log -r 'working_copies()'
|
|
|
|
# One specific workspace tip
|
|
jj --no-pager log -r '<workspace>@'
|
|
```
|
|
|
|
Quote revsets that contain punctuation or function calls.
|
|
|
|
## Filesets
|
|
|
|
Use filesets when a command should operate on only part of the tree.
|
|
|
|
Common patterns:
|
|
|
|
- `path` or `"path"`: cwd-relative path prefix
|
|
- `file:"path"`: exact cwd-relative file path
|
|
- `glob:"pattern"`: cwd-relative glob
|
|
- `root:"path"`: workspace-relative path prefix
|
|
- `~x`: everything except `x`
|
|
- `x & y`: intersection
|
|
- `x | y`: union
|
|
- `x ~ y`: subtract `y` from `x`
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
# Only markdown files in the current directory
|
|
jj diff 'glob:"*.md"'
|
|
|
|
# Everything in src except snapshots
|
|
jj diff 'src ~ glob:"src/**/*.snap"'
|
|
|
|
# Exact file path
|
|
jj diff 'file:"README.md"'
|
|
```
|
|
|
|
## Templates
|
|
|
|
Use templates when default output is too large or too decorative for agent work.
|
|
|
|
Common building blocks:
|
|
|
|
- `++`: concatenate output pieces
|
|
- `if(cond, a, b)`: conditional formatting
|
|
- `description.first_line()`: one-line summary
|
|
- `change_id.shortest(8)`: stable short ID
|
|
- `bookmarks`: bookmark names for a commit
|
|
- `current_working_copy`, `empty`, `conflict`: useful booleans in `jj log`
|
|
|
|
Example:
|
|
|
|
```bash
|
|
jj --no-pager log --no-graph -n 5 -T 'change_id.shortest(8) ++ " " ++ if(description, description.first_line(), "(no description)") ++ "\n"'
|
|
```
|
|
|
|
Start from `references/TEMPLATES.md` instead of inventing new templates unless you need something substantially different.
|
|
|
|
## Rules
|
|
|
|
- Prefer `trunk()` over hardcoding `main` or `master`.
|
|
- Quote revsets and filesets in shell commands when punctuation could be interpreted by the shell.
|
|
- Prefer compact `jj --no-pager` inspection commands before widening the query.
|
|
- If a query fails to parse, check `jj <command> --help`, `jj help -k revsets`, `jj help -k filesets`, or `jj help -k templates`.
|