Reference: Revsets

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

Recipes

See https://github.com/arxanas/git-branchless/discussions/496 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.
• 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.)

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