branches key accepts a list of exact branch names and patterns for matching branch names.
branches key isn’t specified globally or on a content source, Antora will apply the default branches filter.
branches key is optional.
It can be specified directly on the
content key (which changes the default value for all content sources) or on a content source (which overrides the default value).
branches key accepts a list of branch name patterns to use from the specified
Each value can be an exact branch name (e.g.,
main, etc.) or a pattern (e.g.,
The list of branches can also be a combination of these value types.
content: sources: - url: https://git-service.com/org/repo-z.git branches: [rawhide, 90.0, 93.0, dev] (1) - url: https://git-service.com/org/repo-y.git branches: main (2) - url: https://git-service.com/org/repo-x.git branches: [edge, v*, '!v1.*'] (3)
|1||Enclose multiple values in a set of square brackets (
|2||A single value doesn’t need to be enclosed in square brackets, but, if it begins with a number (e.g.,
|3||Exact branch names and branch name patterns can be assigned to a
These value patterns are case insensitive. That means the characters are matched regardless of their case. The values can be specified in a comma-separated list or as single items on individual lines. As a general rule of thumb when using YAML, it’s always best to enclose values in single quotation marks.
content: sources: - url: https://git-service.com/org/repo-x.git branches: - edge (1) - '2.0' (2) - v* - '!v1.*' (3)
|1||Enter each value on its own line with a leading hyphen and blank space.|
|2||Value that start with number should be enclosed in single quotation marks (
|3||Negated values, i.e., values that start with the bang symbol (
Default branches filter
branches key isn’t set on the
content key or a content source, Antora will inherit the default branches filter,
That means Antora will use files from the current (for local) or default (for remote) branch (e.g.,
main) as well as any branch that begins with the letter
v followed immediately by a number (e.g.,
You can override this inherited value per content source by setting the
content: sources: - url: https://git-service.com/org/repo-z.git branches: [rawhide, 90.0, 93.0, dev] (1) - url: https://git-service.com/org/repo-y.git (2) - url: https://git-service.com/org/repo-x.git branches: [edge, v*, '!v1.*'] (3)
|1||This content source will use the exact branch names specified.|
|2||This content source will use the default branches filter.|
|3||This content source will use the
Modify the default branches filter
If you want to modify the default branches filter, assign a value to the
branches key directly on the
content: branches: v* (1) sources: - url: https://git-service.com/org/repo-z.git (2) - url: https://git-service.com/org/repo-x.git branches: [edge, v*, '!v1.*'] (3) - url: https://git-service.com/org/repo-y.git (4)
|2||This content source will use the custom default branches filter, i.e.,
|3||This content source will use the specified branches filter instead of the default one.|
|4||This content source will also use the custom default branches filter.|
The new default branches filter will be applied to all of the
url entries that don’t have a
branches key explicitly defined on them.
Specify branches by name
Branches can be specified by their exact name.
content: sources: - url: https://gitlab.com/antora/demo/demo-component-b.git branches: [main, sneaky-chinchilla, 1.0, 1.5]
Specify branches by pattern
Antora provides a facility to include and exclude branch names in bulk using pattern matching.
For example, branches can be specified using the wildcard operator (
content: sources: - url: https://gitlab.com/antora/demo/demo-component-b.git branches: [v2.*, v3.*, v4.*]
For an in depth look at using wildcards (
*), see Wildcards.
Antora also supports matching branch names using exclusions, braces, alternation, ranges, and repetition patterns.
See Refname Matching in Content Sources.
Exclude branches by pattern
You can unselect branches that were matched by a previous pattern by prefixing the value with
Here’s how you’d exclude all branches that begin with
v and end with
content: sources: - url: https://gitlab.com/antora/demo/demo-component-b.git branches: [v*, '!v*-beta']
If the negated pattern appears first in the list, the meaning slightly changes.
A negated pattern in this position implies that there’s a
* entry before it (e.g.,
content: sources: - url: https://gitlab.com/antora/demo/demo-component-b.git branches: ['!main']
We recommend against using this inverted selection since it can pull in branches you probably don’t want. It’s best to be specific about the branches you want to match, then use exclusions to reduce that list.
Use the current, local branch
When working with a local repository, you may find yourself switching between branches often.
To save you from having to remember to update the playbook file to point to the current branch, you can use the reserved value,
content: sources: - url: ./workspace/project-a branches: HEAD
HEAD is equivalent to using the name of the current branch.