Worktrees
To complement branches, Antora can be configured to use the worktree linked to any branch it discovers in a local repository.
This behavior is controlled using the worktrees
key.
The worktrees
key accepts a boolean value or a list of exact worktree names, name patterns, or a symbolic name.
Worktrees are only relevant for branches, not tags.
worktrees key
The worktrees
key is optional.
It can be specified directly on the content
key (which changes the default value for all content sources) or on an individual content source (which overrides the inherited default value).
The worktrees
key accepts a boolean value or list.
Each value in the list can be an exact worktree name (e.g., v2.3
, main
, etc.), a positive or negative name pattern (e.g., v2.*
, v@({1..9})*({0..9}).({0..9}).x+
, etc.), or a symbolic name (e.g., .
).
The list of name patterns can be any combination of these value types, with one caveat.
There are a few things to note about worktrees.
Typically, a worktree has the same name as the branch from which it was created, but not always.
The main worktree does not have a formal name and is therefore represented in Antora by the symbolic name .
(to symbolize the current directory of the content source).
The main worktree is not necessarily linked to the main branch, but rather to the current branch of the local repository. |
If the worktrees
key is not specified, Antora automatically uses the primary (i.e., main) worktree of a local repository (represented as .
) as long as the current branch of that repository is among the branches matched by the branches
key.
If such a match is made, Antora takes the files from the worktree instead of the files from the git tree for that branch.
Default worktrees filter
When the worktrees
key isn’t set on the content
key or a content source, the key inherits the default worktrees filter, .
.
That means Antora will use files from the main worktree if it’s amoung one of the branches selected by the branches
filter.
+You can override this inherited value per content source by setting the worktrees
key directly on the content
parent key.
Use all worktrees
By default, Antora does not look for linked worktrees.
You can use the worktrees
key to customize this behavior.
For example, to enable the use of all worktrees, simply set the worktrees
key to the boolean value true
.
content:
sources:
- url: /path/to/repo-a/main
branches: [v1.0, v2.0, main]
worktrees: true
In order for Antora to discover linked worktrees, the url
key must point to the location of the main worktree (where the .git folder is located).
If the url
points directly to a linked worktree, Antora will not recognize that content source as a valid git repository.
(Support for using a linked worktree as a content source is a feature introduced in Antora 3.2).
Linked worktree as content source
It’s possible to enhance Antora to support using a linked worktree as a content source with the help of an Antora extension.
The following extension detects when the url
key of a content source points to a linked worktree, then reconfigures the content source to point to the main worktree instead.
'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 dotgit = ospath.join(absdir, '.git')
const dotgitIsFile = await fsp.stat(dotgit).then((stat) => stat.isFile(), () => false)
if (!dotgitIsFile) continue
const worktreeGitdir = await fsp.readFile(dotgit, 'utf8').then((contents) => contents.substr(8).trimRight())
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)
)
}
})
}
Save this file next to your playbook file and load it using --extension ./linked-worktree-as-content-source.js
when invoking Antora.
Once #535 is resolved, this patch will no longer be necessary.
Don’t use any worktrees
If you want Antora to bypass all worktrees, set the value of the worktrees
key to the keyword false
.
content:
sources:
- url: /path/to/repo-a/main
branches: [v1.0, v2.0, main]
worktrees: false
Specify worktrees by keyword
The worktrees
key accepts the following keyword values:
- true
-
Use all worktrees (the main worktree and all linked worktrees).
- false (or ~)
-
Do not use any worktrees (not the main worktree or any linked worktrees).
- .
-
Use only the main worktree. (default)
- *
-
Use only the linked worktrees.
The boolean values true and false can only be used as a singular value, not as an entry in the list.
|
Specify worktrees by glob pattern
If you want more fine-grained control over which worktrees Antora uses, you can specify a list of glob patterns.
You refer to worktrees by their name, which is often the branch name to which they are linked (but not always).
Thus, the glob pattern works the same as described on the Branches page.
If you want to refer to the main worktree, you do so using the .
keyword.
Let’s configure Antora to use the main worktree as well as the linked worktree for the v2.0 branch. The files for the v1.0 branch will be read from the git tree, even if there is a linked worktree associated with that branch.
content:
sources:
- url: /path/to/repo-a/main
branches: [v1.0, v2.0, main]
worktrees: [., v2.0]
Configure multiple worktrees
To learn how to configure multiple worktrees, refer to this guide on the Author Mode page.