在内容源中重新命名匹配
Antora 的核心是收集存储在各个 git 存储库的引用中的内容。该剧本提供了几个键来指示 Antora 要考虑哪些引用名称（即 refnames），包括分支、标签和工作树，以及要扫描这些引用中的哪些起始路径。配置此过滤器的一种方法是单独列出每个引用名称。然而，由于内容通常移动得非常快，因此这种方法可能会很繁琐且静态。这就是为什么 Antora 提供了一种使用模式匹配批量包含和排除引用名称的工具。模式匹配方法的优点是简化配置并在新的引用名称可用时自动发现它们。
本页描述了可用于匹配内容源中的引用名称的值类型和语法。
Value 类型
本页涵盖的键接受两种值：
-
字符串（即字符序列）
-
字符串数组
字符串值将被逗号分隔，最好后跟空格（如果存在）。例如，字符串 v1.0.x、v2.0.x 将成为两个字符串 v1.0.x 和 v2.0.x 的数组。
通常最好将字符串值括在单引号中，以避免值中的字符与 YAML（或您选择的配置语言）中的特殊语法之间发生冲突。
|
如果您使用模式匹配引用名称，我们强烈建议您使用数组语法。单个或逗号分隔的字符串语法仅用于精确匹配。否则，您可能会出现意想不到的行为。 |
精确匹配
匹配引用名称的最简单方法是将它们指定为精确名称。例如，您可以匹配名为 main 的单个分支，如下所示：
branches: main如果您还想为旧版本行添加分支名称，可以用逗号分隔它们：
branches: v1.0.x, v2.0.x, main您还可以将值表示为数组以使其明确：
branches: [v1.0.x, v2.0.x, main]当我们说“完全匹配”时，我们指的是与引用的短名称的匹配。例如，您不匹配 remotes/origin/v1.0.x 或 heads/v1.0.x，而是匹配 v1.0.x。原因是 Antora 会同时查找远程和本地引用，更喜欢本地引用，并且仅针对每个唯一的短名称选择一个引用。
虽然看起来精确匹配是一个字面值，但实际上它是一个模式。并且模式始终从引用名称的开头到结尾匹配。但是，大多数引用名称不包含任何在模式匹配语法中有意义的字符（甚至不包含 .）。因此它的作用就像一个文字值，寻找完全匹配的引用名称。但是，如果您发现它与您期望它匹配的引用名称不匹配，请记住它是一种模式这一事实。
通配符(基本通配符)
必须在剧本中维护准确的引用名称列表可能是乏味且嘈杂的。这就是 Antora 允许您使用模式匹配批量匹配引用名称的原因。
最基本的模式匹配工具是通配符（*）。这种模式的使用通常被称为 globbing，因为您使用它来捕获一组项目。
您可以使用单独的通配符来通配所有存在的引用名称：
branches: '*'但你很少愿意这样做。相反，假设我们想要匹配所有以 v 开头的引用名称。我们可以通过在字母后面放置一个星号来做到这一点。
branches: v** 表示“任意数量的字符”。在这种情况下，它匹配重命名开头的 v 后面的任意数量的字符。
您还可以在字符串的两个部分之间使用通配符来匹配两个部分之间的任意数量的字符。 让我们用它来更精确地匹配版本号。
branches: v*.*.x此模式将匹配 v1.0.x、v2.0.x，甚至 v20.10.x。但是，如果引用名称本身只有数字，它只会匹配数字。这意味着它也可以匹配 very.last.x。虽然稍后当我们进入更高级的模式时我们将能够解决这个问题，但它确实给我们带来了过度匹配的问题和排除的需要。
排除
到目前为止，我们已经讨论了我们想要匹配的引用名称或包含内容。当您开始使用模式时，您可能会遇到匹配太多项目的问题。您可以使用一项或多项排除来删除之前匹配的项目。排除条目始终以 ! 开头。
假设您想要匹配所有类似版本的引用名称，但您想要在开始使用 Antora 之前排除该版本。
branches: [v*.*.x, '!v1.0.x']请注意，我们已按照建议将值切换为数组语法。还需要将排除条目括在单引号中，这样就不会混淆 YAML 解析器。如有疑问，请将字符串值括在单引号中。这样做永远不会有坏处。
让我们扔掉我们无意中匹配的非版本引用名称：
branches: [v*.*.x, '!v1.0.x', '!very.last.x']您还可以在排除模式中使用通配符来批量匹配已匹配的内容并删除这些匹配项。
branches: [v*.*.x, '!v1.*.x', '!very.last.x']通配符是一个有用的工具，但它匹配的字符非常宽松。您可能会发现您需要变得更加精确。这就是大括号的用武之地。
大括号
大括号也称为大括号表达式，是用大括号 ({}) 括起来的模式。Antora 支持三种大括号表达式：
-
以逗号分隔的备用字符序列列表
-
字母或数字范围
-
带步长的数值范围
可选
以逗号分隔的替代字符列表，例如 {this,that} 应读作 "this or that"。这对于匹配版本中的特定数字非常有用。假设我们只想匹配数量非常有限的主要版本引用名称。我们可以使用交替大括号表达式来识别它们：
branches: v{5,6}.*.x此表达式将匹配 v5.0.x、v5.1.x 和 v6.0.x。
您可以使用替换表达式来匹配缺少字符或使用空条目的段。让我们考虑将 v 前缀设置为可选。
branches: '{,v}{5,6}.*.x'您还可以在交替条目中使用通配符。例如，我们可能希望以这种方式匹配预发布：
branches: '{,v}{5,6}.*.x{,-*}'让我们考虑另一种情况，即为给定的主要版本引用名称匹配特定的次要版本：
branches: v5.{7,8}.x也可以匹配不以 v （或其他前导字符）开头的引用名称。
branches: 5.{7,8}.x正如您可以想象的那样，如果您指定一堆数字，它们可能会开始形成一个范围。您可以使用范围语法来合并交替。
范围
如果您要匹配的字符是某个范围的成员，则可以仅使用开始值和结束值来指定它们，并用两个句点 (..) 分隔它们。范围是另一种交替，其中考虑每个项目。
让我们重新审视我们的版本模式，以便它只考虑具有数字的匹配。
branches: v{1..9}.{0..9}.x现在我们将不再匹配 very.last.x。但是，它也不再匹配 v20.10.x。我们可以通过扩大范围来解决这个问题，范围不限于个位数。
branches: v{1..99}.{0..99}.x然而，还有更有效的编写方法，我们将在扩展通配部分中介绍这些方法。
回到我们的另一个例子，假设 5.9.x 刚刚发布，我们想将其添加到 Antora 时代的版本号模式中。我们可以从基本交替切换到范围。
branches: 5.{7..9}.x或者，我们可以使用排除以相反的方式表达此匹配。
branches: ['5.*.x', '!5.{0..6}.x']默认情况下，范围会考虑每个项目。您可以使用步骤跳过项目。
扩展的 globing 和重复
到目前为止，我们一直在匹配单次出现的段，无论它们是字符序列、交替还是范围。我们可以通过指定这些片段必须出现的次数（如果有的话）来进一步改进我们的模式。扩展的 glob 允许您将模式或模式列表括在一对圆括号内，然后为其分配重复运算符。
Antora 中的模式匹配支持以下运算符：
-
* - 零次或多次
-
+ - 一次或多次（即至少一次）
-
? - 零次或一次（即可选）
-
@ - 恰好一次（如果未指定运算符则隐含）
-
！- 不存在
以下扩展 glob 是 {0..9} 的更正式的编写方式：
@({0..9})这是一个扩展的 glob，可以匹配任何数字序列。
*({0..9})这种重复的使用比以下范围更有效，您应该避免使用：
{0..100}|
虽然您可以在模式列表后面添加 *，但我们不建议这样做。重复操作应始终放在模式列表之前。 |
我们可以使用扩展的通配符使我们的版本匹配器精确匹配从 v1.0.0 开始的所有次要版本引用名称：
branches: v@({1..9})*({0..9}).+({0..9}).x我们说主版本不能以 0 开头。然后，它后面可以跟任意数量的数字（例如 1、10 等）。次要版本可以有一位或多位数字（例如 0、99、101 等）。
我们可以在包含时使用否定运算符来排除，而不是使用单独的排除条目：
branches: 5.!({0..5}).x可以嵌套大括号表达式以指定两个匹配分支。以下是我们如何排除那些早期的小版本，同时仍然匹配任何后续版本。
branches: '5.{{6..9},{1..9}+({0..9})}.x'我们想提醒您不要让您的模式过于复杂。虽然可以设计一个可以完成您需要做的所有匹配的模式，但它变得越来越难以阅读和维护。这就是为什么我们鼓励您根据需要使用尽可能多的包含和排除模式，以轻松匹配您网站的引用名称。
让我们用一个完整的示例来结束，该示例将非常特定的版本号范围与删除的所有里程碑版本相匹配。
tags:
- '{5,6}.+({0..9}).+({0..9}){,-*}'
- '!5.{0..5}.*'
- '!*-M+({0..9})'