Branches :: Antora Docs

分支键

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

示例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时，通常最好将值括在单引号中。

示例2. 分支值列在单独行上

content:
  sources:
  - url: https://git-service.com/org/repo-x.git
    branches:
    - edge (1)
    - '2.0' (2)
    - v*
    - '!v1.*' (3)

1	在每行的开头加一个连字符和空格。
2	以数字开头的值应该用单引号括起来（`'`）。
3	否定值，即以感叹号符号（`!`）开头的值，应该用单引号括起来（`'`）。

默认分支过滤器

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

示例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	此内容源将使用指定的分支过滤器而不是默认值。

修改默认分支过滤器

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

示例4. 更改默认分支过滤器

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	此内容源还将使用自定义默认分支过滤器。

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

按名称指定分支

可以按照其精确名称指定分支。

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

按模式指定分支

Antora提供了一种使用模式匹配来批量包含和排除分支名称的方法。例如，可以使用通配符运算符（*）指定分支。

示例5. 使用通配符选择分支

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

有关使用通配符（*）的详细信息，请参阅通配符。Antora还支持使用排除、大括号、交替、范围和重复模式来匹配分支名称。请参阅内容源中的Refname匹配。

按模式排除分支

您可以通过在值前加上!前缀来取消先前模式匹配的分支。以下是如何排除所有以v开头并以-beta结尾的分支：

示例6. 使用通配符排除分支

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

如果否定模式出现在列表中的第一个位置，则含义略有不同。在此位置的否定模式意味着在其前有一个*条目（例如，'*', '!main'）。

示例7. 包含所有未被名称排除的分支

content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: ['!main']

我们建议不要使用这种倒置选择，因为它可能会引入您可能不想要的分支。最好具体说明您想匹配的分支，然后使用排除来减少该列表。

使用当前本地分支

在使用本地存储库时，您可能经常需要在不同分支之间切换。为了避免您需要记住更新playbook文件以指向当前分支，您可以使用保留值HEAD。

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

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