工作树
为了补充分支,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
。
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
。
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
树中读取,即使有一个与该分支相关联的链接工作树。
content:
sources:
- url: /path/to/repo-a/main
branches: [v1.0, v2.0, main]
worktrees: [., v2.0]
配置多个worktrees
要了解如何配置多个工作树,请参阅作者模式页面上的本 指南 。