工作树

为了补充分支，Antora可以使用与其在本地存储库中发现的每个分支相关联的工作树。这种行为是使用worktrees键来控制的。 worktrees键接受关键字或一系列确切的分支名称或glob模式。

工作树仅与分支相关，而与标签无关。

worktrees键

worktrees键是可选的。如果未指定，Antora将自动使用本地存储库的主（即主要）工作树，如果该存储库的当前分支与branches键匹配的分支之一。如果进行了这样的匹配，Antora将使用工作树中的文件，而不是该分支的git树中的文件。

默认情况下，Antora仅使用主工作树（不要与主分支混淆），而不使用链接的工作树。要自定义此行为，您可以设置worktrees键。

主工作树不一定与主分支相关联，而是与本地存储库的当前分支相关联。

worktrees键在内容源的条目上指定。该键接受关键字或一系列分支名称模式。每个分支名称模式可以是确切的分支名称或正或负的glob模式。

要启用所有工作树的使用，只需将worktrees键设置为关键字值true。

示例1. antora-playbook.yml

content:
  sources:
  - url: /path/to/repo-a/main
    branches: [v1.0, v2.0, main]
    worktrees: true

为了让Antora发现链接的工作树，url键必须指向主工作树的位置（.git文件夹所在的位置）。如果url直接指向链接的工作树，Antora将无法将其识别为有效的git存储库。

链接的工作树作为内容源

通过扩展，可以使Antora支持使用链接的工作树作为内容源。以下Antora扩展将检测url键指向链接的工作树时，然后重新配置内容源以指向主工作树。

'use strict'

/* 版权所有 (c) 2022 OpenDevise, Inc.
 *
 * 本源代码表单受Mozilla Public
 * 许可证第2.0版的条款约束。如果未分发此许可证的副本
 * 与此文件一起，您可以在http://mozilla.org/MPL/2.0/处获取一个。
 */
const { promises: fsp } = require('fs')
const ospath = require('path')

/**
 * 重写本地内容源以支持使用链接的工作树。
 *
 * @作者 Dan Allen <dan@opendevise.com>
 */
module.exports.register = function () {
  this.once('playbookBuilt', async ({ playbook }) => {
    const expandPath = this.require('@antora/expand-path-helper')
    for (const contentSource of playbook.content.sources) {
      const { url, branches } = contentSource
      if (url.charAt() !== '.') continue
      const absdir = expandPath(url, { dot: playbook.dir })
      const gitfile = ospath.join(absdir, '.git')
      if (await fsp.stat(gitfile).then((stat) => !stat.isDirectory(), () => false)) {
        const worktreeGitdir = await fsp.readFile(gitfile, 'utf8')
          .then((contents) => contents.trimRight().substr(8))
        const worktreeBranch = await fsp.readFile(ospath.join(worktreeGitdir, 'HEAD'), 'utf8')
          .then((contents) => contents.trimRight().replace(/^ref: (?:refs\/heads\/)?/, ''))
        const reldir = ospath.relative(
          playbook.dir,
          await fsp.readFile(ospath.join(worktreeGitdir, 'commondir'), 'utf8')
            .then((contents) => {
              const gitdir = ospath.join(worktreeGitdir, contents.trimRight())
              return ospath.basename(gitdir) === '.git' ? ospath.dirname(gitdir) : gitdir
            })
        )
        contentSource.url = reldir ? `.${ospath.sep}${reldir}` : '.'
        if (!branches) continue
        contentSource.branches = (branches.constructor === Array ? branches : [branches])
          .map((pattern) => pattern.replaceAll('HEAD', worktreeBranch))
      }
    }
  })
}

将此文件保存在playbook文件旁边，并在调用Antora时使用--extension ./linked-worktree-as-content-source.js进行加载。一旦问题#535得到解决，这个补丁将不再必要。

通过关键字指定工作树

worktrees键接受以下关键字值：

true: 使用所有工作树（主工作树和所有链接的工作树）。
false（或~）: 不使用任何工作树（不是主工作树，也不是任何链接的工作树）。
.: 仅使用主工作树。（默认）
*: 仅使用链接的工作树。

如果要让Antora绕过所有工作树，请将worktrees键的值设置为关键字false。

示例2. antora-playbook.yml

content:
  sources:
  - url: /path/to/repo-a/main
    branches: [v1.0, v2.0, main]
    worktrees: false

通过glob模式指定工作树

如果要更精细地控制Antora使用哪些工作树，可以指定一系列glob模式。您通过分支名称引用工作树，因此，glob模式的工作方式与分支页面上描述的相同。如果要引用当前分支，可以使用.关键字。如果存在，该条目必须首先出现在列表中。

让我们配置Antora使用主工作树以及v2.0分支的链接工作树。即使与该分支关联的工作树存在，也将从git树中读取v1.0分支的文件。

示例3. antora-playbook.yml

content:
  sources:
  - url: /path/to/repo-a/main
    branches: [v1.0, v2.0, main]
    worktrees: [., v2.0]

配置多个工作树

要了解如何配置多个工作树，请参考作者模式页面上的此指南。