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.

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

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

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

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: [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 (*).

Example 5. Select branches using a wildcard
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:

Example 6. Excluding branches using a wildcard
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').

Example 7. Include all branches that aren’t excluded by name
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 worktree and 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 name HEAD for this purpose.

content:
  sources:
  - url: ./workspace/project-a
    branches: HEAD

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

Use the current branch of a worktree

If you’re working with multiple branches of content, and you find yourself switching between those branches often in the main worktree, you may consider using linked worktrees. A linked worktree is an additional worktree for a git repository that exists alongside other worktrees, including the main worktree.

In the past, we’ve said that the branches value HEAD refers to the main worktree. However, this isn’t the whole picture. In actuality, HEAD refers to the worktree at the location specified by the content source url key, not necessary the main worktree. If you’re using linked worktrees (alongside the main worktree) to manage multiple branches, the HEAD keyword alone is not enough to differentiate between available worktrees. Clearly, when using multiple worktrees, we need a way to be able to specify which HEAD we’re talking about.

Antora introduces a special branch syntax you can use to select different worktrees using the branches filter. To refer to a specific worktree, you use the syntax HEAD@<name>, where <name> is the name (or symbolic name) of the worktree. The available worktrees to select are controlled by the worktrees key.

For examaple, to use the files in the linked worktree named v1.0.x, you use HEAD@v1.0.x. You can also use a glob pattern to refer to multiple linked worktrees (e.g., HEAD@*).

Let’s look at the configuration in the playbook to use the worktree named 1.0.x.

content:
  sources:
  - url: workspace/my-content-source
    branches: HEAD@v1.0.x
    worktrees: v1.0.x

First, we make the v1.0.x worktree available using the worktrees key, then we select that worktree using the branches key.

In addition to worktree names, there are two symbolic worktree names you can use, . and /..

.

Refers to the worktree at the directory specified by the url key. That means that HEAD is effectively an alias of HEAD@, so using HEAD is sufficient.

Let’s look at an example where the content source URL is a linked worktree.

content:
  sources:
  - url: workspace/my-content-source-1.0.x
    branches: HEAD

We don’t have to specify the worktrees key in this case since Antora automatically selects the current worktree (e.g., .).

/.

Refers to the worktree at the root of the repository (i.e., the main worktree). This syntax is only needed when you’re using, and starting from, a linked worktree. Using HEAD@/. tells Antora to use the files in the main worktree, even when the content source points to a linked worktree of that repository.

Let’s look at that previous example, but select the main worktree instead.

content:
  sources:
  - url: workspace/my-content-source-1.0.x
    branches: HEAD@/.
    worktrees: true

Notice that, this time, we need to set worktrees: true to make all available worktrees, including the main worktree, selectable by the branches pattern. (Setting worktrees: /. would have worked as well). We expect that the version of the content used will be version specified on the main branch, not the v1.0.x branch.