工作树

为了补充分支,Antora 可以使用链接到它在本地存储库中发现的每个分支的工作树。此行为使用 worktrees 键进行控制。worktrees 键接受一个关键字或一个精确分支名称或全局模式列表。

工作树只与分支相关,与标签(tag)无关。

链接工作树

本地 git 存储库可以配置为拥有多个工作树(称为链接工作树)。main 工作树以正常方式工作,包含一个 .git 文件夹。链接的工作树(位于其它地方)每个都有一个 .git 文件而不是 .git 文件夹 .git 文件包含实际的 .git 文件夹( gitdir )所在位置的路径。

下面是链接工作树中 .git 文件内容的示例:

gitdir: /home/usr/projects/project-name/master/.git/worktrees/v2.2.x

Antora 所需要做的就是从这个文件中检索 gitdir 路径,并将其传递给 isomorphic 的 git 。其余部分将按原样工作。

worktrees键

worktrees 键是可选的。如果没有指定,如果存储库的当前分支在 branches 键匹配的分支中,那么 Antora 将自动使用本地存储库的 main (即,primary )工作树。如果匹配成功,Antora 将从工作树中获取文件,而不是从 git 树中获取该分支的文件。

默认情况下,Antora 只使用 main 工作树(不要与 main 分支混淆),不使用链接工作树。要自定义此行为,您可以设置 worktrees 键。

NOTE

主工作树不一定链接到主分支,而是链接到本地存储库的当前分支。

在内容源的条目上指定 worktrees 键。该键接受关键字或分支名称模式列表。每个分支名称模式可以是一个精确的分支名称,也可以是一个正的或负的全局模式。

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

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

为了让 Antora 发现链接的工作树,url 键必须指向 main 工作树的位置( .git 文件夹所在的位置)。如果 url 直接指向一个链接的工作树,那么 Antora 将不会把它识别为一个有效的 git 存储库。

链接的工作树作为内容源

在扩展的帮助下,可以让 Antora 支持使用链接的工作树作为内容源。下面的 Antora 扩展将检测内容源的 url 键何时指向链接的工作树,然后将内容源重新配置为指向 main 工作树。

'use strict'

/* Copyright (c) 2022 OpenDevise, Inc.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License Version 2.0. If a copy of this license was not distributed
 * with this file, you can obtain one at http://mozilla.org/MPL/2.0/.
 */
const { promises: fsp } = require('fs')
const ospath = require('path')

/**
 * Rewrites local content sources to support the use of linked worktrees.
 *
 * @author 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))
      }
    }
  })
}

在调用 Antora 时,请在剧本文件旁边保存此文件,然后使用 --extension ./linked-worktree-as-content-source.js 加载。解决 #535 后,将不再需要此补丁。

通过关键字来设置worktree

worktrees 键接受以下关键字值:

true

使用所有的工作树( main 工作树和所有链接的工作树)。

false(or ~)

不要使用任何工作树(不是 main 工作树,也不是任何链接的工作树)。

.

只使用主工作树。(默认)

*

只使用链接的工作树。

如果您想让 Antora 绕过所有的工作树,请将 worktrees 键的值设置为关键字 false

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

通过glob模式来设置worktree

如果您希望对 Antora 使用的工作树进行更细粒度的控制,您可以指定一个全局模式列表。您可以通过链接到的分支名称来引用工作树。因此,glob 模式的工作方式与 Branches 页面上描述的相同。如果要引用当前分支,可以使用 . 关键字。如果存在,该条目必须首先出现在列表中。

让我们将 Antora 配置为使用 main 工作树以及 v2.0 分支的链接工作树。v1.0 分支的文件将从 git 树中读取,即使有一个与该分支相关联的链接工作树。

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

配置多个worktrees

要了解如何配置多个工作树,请参阅作者模式页面上的本 指南