分支

branches 键接受一个精确的分支名称列表和匹配分支名称的模式。当分支键没有全局指定或在内容源上指定时，Antora 将应用默认的分支过滤器。

branches键

branches 键是可选的。它可以直接在 content 键上指定（这会改变所有内容源的默认值），也可以在内容源上指定（这会覆盖默认值）。branches 键接受一个分支名称模式列表，以从指定的 URL 使用。每个值可以是精确的分支名称（例如 v2.3 、main 等），也可以是模式（例如 v2.*、v@(1..9)*({0..9}).+({0..9}).x 等）。分支列表也可以是这些值类型的组合。

Example 1. 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 将多个值封装在一组方括号（[]）中。使用逗号（,）分隔每个值。如果一个值以符号（例如 *）开头，根据 YAML 规则，使用单引号（'）括起来。
2 单个值不需要用方括号括起来，但是，如果它以数字（例如 2.0 ）开头，则要使用单引号（'）括起来。如果该值以符号（例如 *）开头，根据 YAML 规则，要使用单引号（'）括起来。
3 可以将确切的分支名称和分支名称模式分配给 branches 键。

这些值模式不区分大小写。这意味着字符无论在什么情况下都是匹配的。这些值可以在逗号分隔的列表中指定，也可以作为单独行上的单个项指定。作为使用 YAML 的一般经验法则，最好将值用单引号括起来。

Example 2. 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 在各自的行中输入每个值，并使用前导连字符和空格。
2 数字开头的值应用单引号(')括起来。
3 否定的值，即以感叹号符号(!)开头的值，应该用单引号(')括起来。

默认分支过滤器

当 content 键或内容源中未设置 branches 键时，Antora 将继承默认分支过滤器，[HEAD,v{0..9}*]。这意味着 Antora 将使用当前分支（对于本地）或默认分支（对于远程）（例如 main ）以及以字母 v 后紧跟数字开头的任何分支文件（例如 v2.0.x ） 。您可以通过设置 branches 键覆盖每个内容源的继承值。

Example 3. 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 此内容源将使用指定的确切分支名称。
2 该内容源将使用默认的分支过滤器。
3 该内容源将使用 edge 分支名称以及以 v 开头的分支名称，这些分支名称与 refname 模式匹配。

修改默认分支过滤器

如果要修改默认的分支过滤器，请直接在 content 键上为分支键指定一个值。

Example 4. 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 在 content 键下指定 branches ，以更改默认分支过滤器。
2 该内容源将使用自定义的默认分支过滤器，即 branches: v*。
3 该内容源将使用指定的分支过滤器，而不是默认的。
4 该内容源还将使用自定义的默认分支过滤器。

新的默认分支过滤器将应用于所有没有明确定义分支键的 url 条目。

通过名称指定分支

分支可以通过它们的确切名称来指定。

content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [main, sneaky-chinchilla, 1.0, 1.5]

通过模式指定分支

Antora 提供了一种使用模式匹配来批量包含和排除分支名称的功能。例如，可以使用通配符( * )指定分支。

Example 5. Example 5. Select branches using a wildcard
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.*, v3.*, v4.*]

有关使用通配符(*)的深入了解，请参阅 通配符 。Antora 还支持使用排除、大括号、交替、范围和重复模式匹配分支名称。参见 内容源中的重命名匹配。

通过模式排除分支

可以通过在值前加上 ! 来取消选择与前一个模式匹配的分支。这就是排除所有以 v 开头以 -beta 结束的分支的方法：

Example 6. Example 6. Excluding branches using a wildcard
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v*, '!v*-beta']

如果否定模式首先出现在列表中，含义略有变化。此位置的否定模式意味着在其前面存在 * 条目（例如 '*'，'!main'）。

Example 7. 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']

我们不建议使用这种反向选择，因为它可能会拉入你可能不想要的分支。最好明确想要匹配的分支，然后使用排除来减少该列表。

使用当前，本地分支

在使用本地存储库时，您可能会发现自己经常在分支之间切换。为了使您不必记住更新剧本文件以指向当前分支，您可以使用保留值 HEAD 。

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

值 HEAD 相当于使用当前分支的名称。