forked from mirrors/jj
5b769c5c9e
Since fileset/revset/template expressions are specified as command-line arguments, it's sometimes convenient to use single quotes instead of double quotes. Various scripting languages parse single-quoted strings in various ways, but I choose the TOML rule because it's simple and practically useful. TOML is our config language, so copying the TOML syntax would be less surprising than borrowing it from another language. https://github.com/toml-lang/toml/issues/188
309 lines
11 KiB
Markdown
309 lines
11 KiB
Markdown
# Revsets
|
|
|
|
Jujutsu supports a functional language for selecting a set of revisions.
|
|
Expressions in this language are called "revsets" (the idea comes from
|
|
[Mercurial](https://www.mercurial-scm.org/repo/hg/help/revsets)). The language
|
|
consists of symbols, operators, and functions.
|
|
|
|
Most `jj` commands accept a revset (or multiple). Many commands, such as
|
|
`jj diff -r <revset>` expect the revset to resolve to a single commit; it is
|
|
an error to pass a revset that resolves to more than one commit (or zero
|
|
commits) to such commands.
|
|
|
|
The words "revisions" and "commits" are used interchangeably in this document.
|
|
|
|
Most revsets search only the [visible commits](glossary.md#visible-commits).
|
|
Other commits are only included if you explicitly mention them (e.g. by commit
|
|
ID or a Git ref pointing to them).
|
|
|
|
## Symbols
|
|
|
|
The `@` expression refers to the working copy commit in the current workspace.
|
|
Use `<workspace name>@` to refer to the working-copy commit in another
|
|
workspace. Use `<name>@<remote>` to refer to a remote-tracking branch.
|
|
|
|
A full commit ID refers to a single commit. A unique prefix of the full commit
|
|
ID can also be used. It is an error to use a non-unique prefix.
|
|
|
|
A full change ID refers to all visible commits with that change ID (there is
|
|
typically only one visible commit with a given change ID). A unique prefix of
|
|
the full change ID can also be used. It is an error to use a non-unique prefix.
|
|
|
|
Use [single or double quotes][string-literals] to prevent a symbol from being
|
|
interpreted as an expression. For example, `"x-"` is the symbol `x-`, not the
|
|
parents of symbol `x`. Taking shell quoting into account, you may need to use
|
|
something like `jj log -r '"x-"'`.
|
|
|
|
[string-literals]: templates.md#string-literals
|
|
|
|
### Priority
|
|
|
|
Jujutsu attempts to resolve a symbol in the following order:
|
|
|
|
1. Tag name
|
|
2. Branch name
|
|
3. Git ref
|
|
4. Commit ID or change ID
|
|
|
|
## Operators
|
|
|
|
The following operators are supported. `x` and `y` below can be any revset, not
|
|
only symbols.
|
|
|
|
* `x & y`: Revisions that are in both `x` and `y`.
|
|
* `x | y`: Revisions that are in either `x` or `y` (or both).
|
|
* `x ~ y`: Revisions that are in `x` but not in `y`.
|
|
* `~x`: Revisions that are not in `x`.
|
|
* `x-`: Parents of `x`.
|
|
* `x+`: Children of `x`.
|
|
* `::x`: Ancestors of `x`, including the commits in `x` itself.
|
|
* `x::`: Descendants of `x`, including the commits in `x` itself.
|
|
* `x::y`: Descendants of `x` that are also ancestors of `y`. Equivalent
|
|
to `x:: & ::y`. This is what `git log` calls `--ancestry-path x..y`.
|
|
* `::`: All visible commits in the repo. Equivalent to `all()`.
|
|
* `x..y`: Ancestors of `y` that are not also ancestors of `x`. Equivalent to
|
|
`::y ~ ::x`. This is what `git log` calls `x..y` (i.e. the same as we call it).
|
|
* `..x`: Ancestors of `x`, including the commits in `x` itself, but excluding
|
|
the root commit. Equivalent to `::x ~ root()`.
|
|
* `x..`: Revisions that are not ancestors of `x`.
|
|
* `..`: All visible commits in the repo, but excluding the root commit.
|
|
Equivalent to `~root()`.
|
|
|
|
You can use parentheses to control evaluation order, such as `(x & y) | z` or
|
|
`x & (y | z)`.
|
|
|
|
## Functions
|
|
|
|
You can also specify revisions by using functions. Some functions take other
|
|
revsets (expressions) as arguments.
|
|
|
|
* `parents(x)`: Same as `x-`.
|
|
|
|
* `children(x)`: Same as `x+`.
|
|
|
|
* `ancestors(x[, depth])`: `ancestors(x)` is the same as `::x`.
|
|
`ancestors(x, depth)` returns the ancestors of `x` limited to the given
|
|
`depth`.
|
|
|
|
* `descendants(x)`: Same as `x::`.
|
|
|
|
* `connected(x)`: Same as `x::x`. Useful when `x` includes several commits.
|
|
|
|
* `all()`: All visible commits in the repo.
|
|
|
|
* `none()`: No commits. This function is rarely useful; it is provided for
|
|
completeness.
|
|
|
|
* `branches([pattern])`: All local branch targets. If `pattern` is specified,
|
|
this selects the branches whose name match the given [string
|
|
pattern](#string-patterns). For example, `branches(push)` would match the
|
|
branches `push-123` and `repushed` but not the branch `main`. If a branch is
|
|
in a conflicted state, all its possible targets are included.
|
|
|
|
* `remote_branches([branch_pattern[, [remote=]remote_pattern]])`: All remote
|
|
branch targets across all remotes. If just the `branch_pattern` is
|
|
specified, the branches whose names match the given [string
|
|
pattern](#string-patterns) across all remotes are selected. If both
|
|
`branch_pattern` and `remote_pattern` are specified, the selection is
|
|
further restricted to just the remotes whose names match `remote_pattern`.
|
|
|
|
For example, `remote_branches(push, ri)` would match the branches
|
|
`push-123@origin` and `repushed@private` but not `push-123@upstream` or
|
|
`main@origin` or `main@upstream`. If a branch is in a conflicted state, all
|
|
its possible targets are included.
|
|
|
|
While Git-tracking branches can be selected by `<name>@git`, these branches
|
|
aren't included in `remote_branches()`.
|
|
|
|
* `tags()`: All tag targets. If a tag is in a conflicted state, all its
|
|
possible targets are included.
|
|
|
|
* `git_refs()`: All Git ref targets as of the last import. If a Git ref
|
|
is in a conflicted state, all its possible targets are included.
|
|
|
|
* `git_head()`: The Git `HEAD` target as of the last import. Equivalent to
|
|
`present(HEAD@git)`.
|
|
|
|
* `visible_heads()`: All visible heads (same as `heads(all())`).
|
|
|
|
* `root()`: The virtual commit that is the oldest ancestor of all other commits.
|
|
|
|
* `heads(x)`: Commits in `x` that are not ancestors of other commits in `x`.
|
|
Note that this is different from
|
|
[Mercurial's](https://repo.mercurial-scm.org/hg/help/revsets) `heads(x)`
|
|
function, which is equivalent to `x ~ x-`.
|
|
|
|
* `roots(x)`: Commits in `x` that are not descendants of other commits in `x`.
|
|
Note that this is different from
|
|
[Mercurial's](https://repo.mercurial-scm.org/hg/help/revsets) `roots(x)`
|
|
function, which is equivalent to `x ~ x+`.
|
|
|
|
* `latest(x[, count])`: Latest `count` commits in `x`, based on committer
|
|
timestamp. The default `count` is 1.
|
|
|
|
* `merges()`: Merge commits.
|
|
|
|
* `description(pattern)`: Commits that have a description matching the given
|
|
[string pattern](#string-patterns).
|
|
|
|
* `author(pattern)`: Commits with the author's name or email matching the given
|
|
[string pattern](#string-patterns).
|
|
|
|
* `mine()`: Commits where the author's email matches the email of the current
|
|
user.
|
|
|
|
* `committer(pattern)`: Commits with the committer's name or email matching the
|
|
given [string pattern](#string-patterns).
|
|
|
|
* `empty()`: Commits modifying no files. This also includes `merges()` without
|
|
user modifications and `root()`.
|
|
|
|
* `file(pattern[, pattern]...)`: Commits modifying paths matching one of the
|
|
given [file patterns](filesets.md#file-patterns).
|
|
|
|
Paths are relative to the directory `jj` was invoked from. A directory name
|
|
will match all files in that directory and its subdirectories.
|
|
|
|
For example, `file(foo)` will match files `foo`, `foo/bar`, `foo/bar/baz`.
|
|
It will *not* match `foobar` or `bar/foo`.
|
|
|
|
* `conflict()`: Commits with conflicts.
|
|
|
|
* `present(x)`: Same as `x`, but evaluated to `none()` if any of the commits
|
|
in `x` doesn't exist (e.g. is an unknown branch name.)
|
|
|
|
* `working_copies()`: The working copy commits across all the workspaces.
|
|
|
|
## String patterns
|
|
|
|
Functions that perform string matching support the following pattern syntax:
|
|
|
|
* `"string"`, or `string` (the quotes are optional), or `substring:"string"`:
|
|
Matches strings that contain `string`.
|
|
* `exact:"string"`: Matches strings exactly equal to `string`.
|
|
* `glob:"pattern"`: Matches strings with Unix-style shell [wildcard
|
|
`pattern`](https://docs.rs/glob/latest/glob/struct.Pattern.html).
|
|
|
|
## Aliases
|
|
|
|
New symbols and functions can be defined in the config file, by using any
|
|
combination of the predefined symbols/functions and other aliases.
|
|
|
|
For example:
|
|
|
|
```toml
|
|
[revset-aliases]
|
|
'HEAD' = '@-'
|
|
'user(x)' = 'author(x) | committer(x)'
|
|
```
|
|
|
|
### Built-in Aliases
|
|
|
|
The following aliases are built-in and used for certain operations. These functions
|
|
are defined as aliases in order to allow you to overwrite them as needed.
|
|
See [revsets.toml](https://github.com/martinvonz/jj/blob/main/cli/src/config/revsets.toml)
|
|
for a comprehensive list.
|
|
|
|
* `trunk()`: Resolves to the head commit for the trunk branch of the remote
|
|
named `origin` or `upstream`. The branches `main`, `master`, and `trunk` are
|
|
tried. If more than one potential trunk commit exists, the newest one is
|
|
chosen. If none of the branches exist, the revset evaluates to `root()`.
|
|
|
|
You can [override](./config.md) this as appropriate. If you do, make sure it
|
|
always resolves to exactly one commit. For example:
|
|
|
|
```toml
|
|
[revset-aliases]
|
|
'trunk()' = 'your-branch@your-remote'
|
|
```
|
|
|
|
* `immutable_heads()`: Resolves to `trunk() | tags()` by default. See
|
|
[here](config.md#set-of-immutable-commits) for details.
|
|
|
|
|
|
## The `all:` modifier
|
|
|
|
Certain commands (such as `jj rebase`) can take multiple revset arguments, and
|
|
each of these may resolve to one-or-many revisions. By default, `jj` will not
|
|
allow revsets that resolve to more than one revision — a so-called "large
|
|
revset" — and will ask you to confirm that you want to proceed by
|
|
prefixing it with the `all:` modifier.
|
|
|
|
If you set the `ui.always-allow-large-revsets` option to `true`, `jj` will
|
|
behave as though the `all:` modifier was used every time it would matter.
|
|
|
|
An `all:` modifier before a revset expression does not otherwise change its
|
|
meaning. Strictly speaking, it is not part of the revset language. The notation
|
|
is similar to the modifiers like `glob:` allowed before [string
|
|
patterms](#string-patterns).
|
|
|
|
For example, `jj rebase -r w -d xyz+` will rebase `w` on top of the child of
|
|
`xyz` as long as `xyz` has exactly one child.
|
|
|
|
If `xyz` has more than one child, the `all:` modifier is *not* specified, and
|
|
`ui.always-allow-large-revsets` is `false` (the default), `jj rebase -r w -d
|
|
xyz+` will return an error.
|
|
|
|
If `ui.always-allow-large-revsets` was `true`, the above command would act as if
|
|
`all:` was set (see the next paragraph).
|
|
|
|
With the `all:` modifier, `jj rebase -r w -d all:xyz+` will make `w` into a merge
|
|
commit if `xyz` has more than one child. The `all:` modifier confirms that the
|
|
user expected `xyz` to have more than one child.
|
|
|
|
A more useful example: if `w` is a merge commit, `jj rebase -s w -d all:w- -d
|
|
xyz` will add `xyz` to the list of `w`'s parents.
|
|
|
|
## Examples
|
|
|
|
Show the parent(s) of the working-copy commit (like `git log -1 HEAD`):
|
|
|
|
```
|
|
jj log -r @-
|
|
```
|
|
|
|
Show all ancestors of the working copy (like plain `git log`)
|
|
|
|
```
|
|
jj log -r ::@
|
|
```
|
|
|
|
Show commits not on any remote branch:
|
|
|
|
```
|
|
jj log -r 'remote_branches()..'
|
|
```
|
|
|
|
Show commits not on `origin` (if you have other remotes like `fork`):
|
|
|
|
```
|
|
jj log -r 'remote_branches(remote=origin)..'
|
|
```
|
|
|
|
Show the initial commits in the repo (the ones Git calls "root commits"):
|
|
|
|
```
|
|
jj log -r root()+
|
|
```
|
|
|
|
Show some important commits (like `git --simplify-by-decoration`):
|
|
|
|
```
|
|
jj log -r 'tags() | branches()'
|
|
```
|
|
|
|
Show local commits leading up to the working copy, as well as descendants of
|
|
those commits:
|
|
|
|
|
|
```
|
|
jj log -r '(remote_branches()..@)::'
|
|
```
|
|
|
|
Show commits authored by "martinvonz" and containing the word "reset" in the
|
|
description:
|
|
|
|
```
|
|
jj log -r 'author(martinvonz) & description(reset)'
|
|
```
|