Branches
The branches key accepts a list of exact branch names and patterns for matching branch names.
When the branches key isn’t specified globally or on a content source, Antora will apply the default branches filter.
branches key
The 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).
The branches key accepts a list of branch name patterns to use from the specified url.
Each value can be an exact branch name (e.g., v2.3, main, etc.) or a pattern (e.g., v2.*, v@({1..9})*({0..9}).({0..9}).x+, etc.).
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 ([]).
Separate each value with a comma (,).
If a value begins with a symbol (e.g., *), enclose it in single quotation marks (') per YAML rules. |
| 2 | A single value doesn’t need to be enclosed in square brackets, but, if it begins with a number (e.g., 2.0), enclose it in single quotation marks (').
If the value begins with a symbol (e.g., *), enclose it in single quotation marks (') per YAML rules. |
| 3 | Exact branch names and branch name patterns can be assigned to a branches key. |
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 (!), should be enclosed single quotation marks ('). |
Default branches filter
When the branches key isn’t set on the content key or a content source, Antora will inherit the default branches filter, [HEAD, v{0..9}*].
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., v2.0.x).
You can override this inherited value per content source by setting the branches key.
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 edge branch name as well as the branch names that begin with v that are matched by the refname pattern. |
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 key.
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)| 1 | Specify branches under the content key to change the default branches filter. |
| 2 | This content source will use the custom default branches filter, i.e., branches: v*. |
| 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 -beta:
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., '*', '!main').
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, HEAD.
content:
sources:
- url: ./workspace/project-a
branches: HEADThe value HEAD is equivalent to using the name of the current branch.