-
-
Notifications
You must be signed in to change notification settings - Fork 88
Reference: Revsets
See Revset recipes for some ideas and examples on how to use revsets.
The latest grammar is in grammar.lalrpop.
Names are resolved using the same logic as git rev-parse
. Additionally, .
is a synonym for HEAD
.
The following functions are defined:
-
all()
: all visible commits. -
none()
: the empty set of commits. -
union(x, y)
: all commits that are in eitherx
ory
. -
intersection(x, y)
: all commits that are in bothx
andy
. -
difference(x, y)
: all commits that are inx
but not iny
. -
only(x, y)
: all commits which are ancestors ofx
, but not ancestors ofy
. -
range(x, y)
: all commits which are both descendants ofx
and ancestors ofy
. -
ancestors(x)
: all commits which are ancestors of commits inx
.- A commit is an "ancestor" of
x
if it isx
or it is a parent of an ancestor ofx
. Note that this definition includesx
itself in the set of ancestors ofx
.
- A commit is an "ancestor" of
-
ancestors.nth(x, n)
: then
th generation ancestor ofx
, following only the first parents. Equivalent to~n
. -
descendants(x)
: all commits which are descendants of commits inx
.- A commit is a "descendant" of
x
if it isx
or it is a child of a descendant ofx
. Note that this definition includesx
itself in the set of descendants ofx
.
- A commit is a "descendant" of
-
parents(x)
: all commits which are an immediate parent of a commit inx
. -
parents.nth(x, n)
: then
th parent ofx
. Equivalent to^n
-
children(x)
: all commits which are an immediate child of a commit inx
. -
roots(x)
: all commits inx
which have no immediate ancestors also inx
. -
heads(x)
: all commits inx
which have no immediate descendants also inx
. -
merges()
: all merge commits. (Available since v0.9.0) -
main()
: the main branch commit. (Available since v0.6.0.) -
public()
: all public commits, which is to say, all commits on the main branch. This is the same asancestors(main())
. (Available since v0.6.0.) -
draft()
: all draft commits. -
stack([x])
: all draft commits in the commit stack containingx
. Without arguments, refers to the current commit stack (i.e. the one containingHEAD
). -
branches([text-pattern])
: all commits with branches pointing to them. If a pattern is provided, the result is restricted to commits whose branches match that pattern. (Available since v0.9.0.) -
message(text-pattern)
: all commits whose messages match the specified pattern. -
paths.changed(text-pattern)
: all commits with a changed file path matching the specified pattern. -
author.name(text-pattern)
: all commits whose author name matches the specified pattern. -
author.email(text-pattern)
: all commits whose author email matches the specified pattern. -
author.date(date-pattern)
: all commits whose author date matches the specified pattern. -
committer.name(text-pattern)
: all commits whose committer name matches the specified pattern. -
committer.email(text-pattern)
: all commits whose committer email matches the specified pattern. -
committer.date(date-pattern)
: all commits whose committer date matches the specified pattern. -
exactly(x, n)
: all commits inx
, but only ifx
contains exactlyn
commits. (Available since v0.5.0.) -
current(x)
: the current version of all commits inx
. (Available since v0.6.0.)- Commits in
x
that have been rewritten (for example, by being moved, reworded, amended, restacked, etc) will be resolved to their current version. Commits inx
that have not been rewritten will be included as is.
- Commits in
-
tests.passed([test-command-pattern])
: all commits whose most recent test run for the specified test command passed. If no test command is specified, refers to the most-recently-run test command. (Available since v0.7.0.) -
tests.failed([test-command-pattern])
: all commits whose most recent test run for the specified test command failed. If no test command is specified, refers to the most-recently-run test command. (Available since v0.7.0.) -
tests.fixable([test-command-pattern])
: all commits whose most recent test run for the specified test command wrote output to the working copy, which could be used withgit test fix
to apply the changes. If no test command is specified, refers to the most-recently-run test command. (Available since v0.7.0.)
The following unary operations are defined:
-
:x
: same asancestors(x)
.-
::x
is also accepted to be familiar for Mercurial users.
-
-
x:
: same asdescendants(x)
.-
x::
is also accepted to be familiar for Mercurial users.
-
The following binary operations are defined:
-
+
,|
,or
: same asunion
. -
&
,and
: same asintersection
. -
-
: same asdifference
.- Note that
foo-bar
is parsed as a branch name. To force the binary operation parsing, writefoo - bar
instead.
- Note that
-
%
: same asonly
. -
:
: same asrange
.-
::
is also accepted to be familiar for Mercurial users.
-
-
..
: same asonly
.
Text patterns:
-
foo
,substr:foo
,substring:foo
: matches if the text containsfoo
anywhere. -
exact:foo
: matches if the entire text content is exactlyfoo
. -
glob:foo/*
: matches if the text content matches the glob patternfoo/*
anywhere. -
regex:foo.*
: matches if the text content matches the glob patternfoo.*
anywhere.
Dates can be either absolute (2022-01-01
) or relative (1 month ago
). Date patterns:
-
before:date
: matches if the date is beforedate
. -
after:date
: matches if the date is afterdate
.
Test command patterns: these are the same as text patterns and match against the full test command as run by git test
. In particular, test command aliases are not stored in historical test run data, so test command matching is always performed against the fully-expanded test command.
Aliases may be defined via git config to provide easy access to oft used revset constructs. Parameters are supported, too: $1
will be replaced with the first parameter, $2
with the second, etc.
They can be defined from the command line:
$ git config --global \
branchless.revsets.alias.d \
"draft()"`
Or directly in the git config file:
[branchless "revsets.alias"]
grandChildren = children(children($1))
sole = exactly($1, 1)
onlyChild = sole(children($1))
onlyParent = sole(parents($1))
siblings = children(onlyParent($1)) - $1
Then, they can be used anywhere that git branchless
accepts revsets
:
$ git query 'd()'
...
$ git reword 'sole(siblings(abc123))'
...
- Search the Wiki 🔎
- User guide
- Welcome
- Installation
- Tutorial
- Command overview
- General:
- Navigation:
- Committing:
- Rebasing:
- Verification:
- Collaboration:
- Workflows
- Advanced topics
- Reference
- Developer guide
- Onboarding offer
- Development
- Reference