ok/jj
1
0
Fork 0
forked from mirrors/jj
jj/docs/revsets.md

234 lines
8.8 KiB
Markdown
Raw Normal View History

# 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.
The commits listed by `jj log` without arguments are called "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 double quotes 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-"'`.
### 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`, `x:`, and `x:y`: Deprecated versions of `::x`, `x::`, and `x::y` We
plan to delete them in jj 0.15+.
* `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,
branches whose name contains the given string are selected. 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,
branches whose name contains the given string across all remotes are
selected. If both `branch_pattern` and `remote_pattern` are specified, the
selection is further restricted to just the remotes whose name contains
`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.
* `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-`.
2022-04-13 20:55:47 +00:00
* `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 with the given string in their
description.
* `author(pattern)`: Commits with the given string in the author's name or
email.
2023-08-14 00:35:11 +00:00
* `mine()`: Commits where the author's email matches the email of the current
user.
* `committer(pattern)`: Commits with the given string in the committer's
name or email.
* `empty()`: Commits modifying no files. This also includes `merges()` without
user modifications and `root()`.
* `file(pattern..)`: Commits modifying the paths specified by the `pattern..`.
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`, but not file
`foobar`.
* `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.)
## String patterns
Functions that perform string matching support the following pattern syntax.
* `"string"`, `substring:"string"`: Matches strings that contain `string`.
* `exact:"string"`: Matches strings exactly equal to `string`.
## 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]
'mine' = 'author(martinvonz)'
'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'
```
## Examples
Show the parent(s) of the working-copy commit (like `git log -1 HEAD`):
```
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 all ancestors of the working copy (almost like plain `git log`)
```
jj log -r ::@
```
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:
revsets: allow `::` as synonym for `:` The `--allow-large-revsets` flag we have on `jj rebase` and `jj new` allows the user to do e.g. `jj rebase --allow-large-revsets -b main.. -d main` to rebase all commits that are not in main onto main. The reason we don't allow these revsets to resolve to multiple commits by default is that we think users might specify multiple commits by mistake. That's probably not much of a problem with `jj rebase -b` (maybe we should always allow that to resolve to multiple commits), but the user might want to know if `jj rebase -d @-` resolves to multiple commits. One problem with having a flag to allow multiple commits is that it needs to be added to every command where we want to allow multiple commits but default to one. Also, it should probably apply to each revset argument those commands take. For example, even if the user meant `-b main..` to resolve to multiple commits, they might not have meant `-d main` to resolve to multiple commits (which it will in case of a conflicted branch), so we might want separate `--allow-large-revsets-in-destination` and `--allow-large-revsets-in-source`, which gets quite cumbersome. It seems better to have some syntax in the individual revsets for saying that multiple commits are allowed. One proposal I had was to use a `multiple()` revset function which would have no effect in general but would be used as a marker if used at the top level (e.g. `jj rebase -d 'multiple(@-)'`). After some discussion on the PR adding that function (#1911), it seems that the consensus is to instead use a prefix like `many:` or `all:`. That avoids the problem with having a function that has no effect unless it's used at the top level (`jj rebase -d 'multiple(x)|y'` would have no effect). Since we already have the `:` operator for DAG ranges, we need to change it to make room for `many:`/`all:` syntax. This commit starts that by allowing both `:` and `::`. I have tried to update the documentation in this commit to either mention both forms, or just the new and preferred `::` form. However, it's useless to search for `:` in Rust code, so I'm sure I've missed many instances. We'll have to address those as we notice them. I'll let most tests use `:` until we deprecate it or delete it.
2023-07-27 23:27:44 +00:00
```
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)'
```