Branches

The branches key accepts a list of exact branch names and glob patterns. 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) or a glob pattern (e.g., v2.*). The list of branches can also have a combination of these value types.

Example 1. antora-playbook.yml
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: master (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 (,).
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 (').
3 Exact branch names and glob patterns can be assigned to a branches key.

These value patterns are case insensitive (i.e., the characters are matched regardless of case). The values can be specified in a comma-separated list or as single items on individual lines.

Example 2. branches values listed on individual lines
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 use the default branches filter. By default, Antora will select all of the branches from the repository that begin with the letter v as well as the branch named master.

Example 3. antora-playbook.yml
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 glob patterns.

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.

Example 4. Change the default branches filter
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: [master, sneaky-chinchilla, 1.0, 1.5]

Specify branches by glob pattern

Branches can be specified by glob patterns such as as v3.4.*.

Example 5. Glob branch patterns
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.*, v3.*, v4.*]

Negate glob patterns

If a pattern starts with a ! character, then it is negated (i.e., the matches are excluded). This is how you can deselect branches that were matched by a previous glob.

Here’s how you’d exclude all branches that end in -beta.

Example 6. Exclude branches ending in -beta
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v*, !v*-beta]

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: HEAD

The value HEAD is equivalent to using the name of the current branch.