Reference: Revsets

• Recipes
• Grammar
• Built-in functions
• Operators
• Patterns
• Aliases

Recipes

See Revset recipes for some ideas and examples on how to use revsets.

Grammar

The latest grammar is in grammar.lalrpop.

Names are resolved using the same logic as git rev-parse. Additionally, . is a synonym for HEAD.

Built-in functions

The following functions are defined:

• all(): all visible commits.
• none(): the empty set of commits.
• union(x, y): all commits that are in either x or y.
• intersection(x, y): all commits that are in both x and y.
• difference(x, y): all commits that are in x but not in y.
• only(x, y): all commits which are ancestors of x, but not ancestors of y.
• range(x, y): all commits which are both descendants of x and ancestors of y.
• ancestors(x): all commits which are ancestors of commits in x.
  • A commit is an "ancestor" of x if it x or it is a parent of an ancestor of x. Note that this definition includes x itself in the set of ancestors of x.
• ancestors.nth(x, n): the nth generation ancestor of x, following only the first parents. Equivalent to ~n.
• descendants(x): all commits which are descendants of commits in x.
  • A commit is a "descendant" of x if it x or it is a child of a descendant of x. Note that this definition includes x itself in the set of descendants of x.
• parents(x): all commits which are an immediate parent of a commit in x.
• parents.nth(x, n): the nth parent of x. Equivalent to ^n
• children(x): all commits which are an immediate child of a commit in x.
• roots(x): all commits in x which have no immediate ancestors also in x.
• heads(x): all commits in x which have no immediate descendants also in x.
• main(): the main branch commit. (New in master.)
• public(): all public commits, which is to say, all commits on the main branch. This is the same as ancestors(main()). (New in master.)
• draft(): all draft commits.
• stack(x): all draft commits in the commit stack containing x. Without arguments, refers to the current commit stack (ie the one containing HEAD).
• 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 email 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 email matches the specified pattern.
• exactly(x, n): all commits in x, but only if x contains exactly n commits. (New in v0.5.0.)
• current(x): the current version of all commits in x. (New in master.)
  • Commits in x that have been rewritten (for example, by being moved, reworded, amended, restacked, etc) will be resolved to their current version. Commits in x that have not been rewritten will be included as is.

Operators

The following unary operations are defined:

• :x: same as ancestors(x).
  • ::x is also accepted to be familiar for Mercurial users.
• x:: same as descendants(x).
  • x:: is also accepted to be familiar for Mercurial users.

The following binary operations are defined:

• +, |, or: same as union.
• &, and: same as intersection.
• -: same as difference.
  • Note that foo-bar is parsed as a branch name. To force the binary operation parsing, write foo - bar instead.
• %: same as only.
• :: same as range.
  • :: is also accepted to be familiar for Mercurial users.
• ..: same as only.

Patterns

Text patterns:

• foo, substr:foo, substring:foo: matches if the text contains foo anywhere.
• exact:foo: matches if the entire text content is exactly foo.
• glob:foo/*: matches if the text content matches the glob pattern foo/* anywhere.
• regex:foo.*: matches if the text content matches the glob pattern foo.* anywhere.

Dates can be either absolute (2022-01-01) or relative (1 month ago). Date patterns:

• before:date: matches if the date is before date.
• after:date: matches if the date is after date.

Aliases

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))'
...