Configure the Worktree

A Collector instance is invoked in a worktree directory. The default behavior of Collector is to use the worktree for the origin if it has one or check out the git reference into a temporary worktree if it does not.

You can configure how the worktree directory is prepared using the worktree configuration key for the Collector instance. For example, you can force Collector to create a fresh worktree even if the origin already has one using the create key. Conversely, you can instruct Collector to skip the checkout and use an empty worktree instead using the checkout key. This page explains how to use the worktree key and the keys it accepts.

worktree key

The worktree behavior is configured using the worktree configuration key for the Collector instance. The worktree key must be nested under the collector key in antora.yml. If the value of the collector key is an array (instead of a map), the worktree key must be defined in the first entry in the array (i.e., the first step).

The value of the worktree key can be a map or a boolean. If the value is a boolean, the value is assumed to be the value of the checkout key of a map.

Acceptable keys for the map value are listed in the table below.

Key Default Type Description

Key	Default	Type	Description
`checkout`	true	Boolean or always	Whether to checkout the git reference when no worktree is available.
`create`	auto	String enum (auto or always)	Under what condition to create the worktree.
`keep`	false	Boolean or until:<eventName>	Whether to keep the generated worktree and for how long.

checkout

true

Boolean or always

Whether to checkout the git reference when no worktree is available.

create

auto

String enum (auto or always)

Under what condition to create the worktree.

keep

false

Boolean or until:<eventName>

Whether to keep the generated worktree and for how long.

checkout key

The checkout key specifies whether the git reference should be checked out (i.e., git checkout) into a temporary worktree when the origin (i.e., content source root) does not have a worktree (e.g., the origin is a remote or bare repository). This key only applies when the origin has a worktree if the create key is set to always. The combination of checkout: true and create: always can be abbreviated as checkout: always.

If the origin does not have a worktree, Collector will check out the git reference into a temporary worktree by default. This directory will be set up as a linked worktree (thus linking it to the source repository).

If the worktree is configured to be kept using the keep key, the temporary worktree will be unique by git reference (i.e., refname). Otherwise, the Collector extension will recycle the same temporary directory for every git reference for a single git repository. The latter behavior is an optimization to reduce the time it takes to perform the checkout into the worktree.

To turn off the default behavior and invoke the Collector instance in an empty temporary directory, set the value of the checkout key to false. The purpose of this option is to allow the user to bypass the overhead of checking out the worktree when the Collector instance does not need any files in the repository.

antora.yml

name: colorado
title: Colorado
version: '5.6.0'
ext:
  collector:
    worktree:
      checkout: false
    run:
    - command: wget https://example.org/archive.zip
    - command: unzip archive.zip
    scan:
      dir: archive

When the worktree checkout behavior is turned off (i.e., false), the Collector instance is invoked in an empty directory. In this case, the commands to run must be available on the system. The command cannot be taken from a file in the git repository since the files contained in the git reference are not in the worktree.

create key

If the origin (i.e., content source root) has a worktree, Collector will reuse that worktree by default. You can force Collector to always create a temporary worktree by assigning the value always to the create key on the Collector instance. If set, this key overrides the global setting on the extension.

antora.yml

name: colorado
title: Colorado
version: '5.6.0'
ext:
  collector:
    worktree:
      create: always
    run:
    - command: generate-files
    scan:
      dir: generated

The default create behavior can be set on the extension itself using the create_worktrees key.

Keep in mind that when the create behavior is forced (i.e., always), the command will not be able to see any uncommitted files in the local worktree (since it will be run instead a fresh worktree instead).

keep key

By default, Collector will remove the temporary worktree once the instance of Collector is finished running. You can customize this behavior using the keep key. If set, this key overrides the global setting on the extension.

antora.yml

name: colorado
title: Colorado
version: '5.6.0'
ext:
  collector:
    worktree:
      keep: until:exit
    run:
    - command: generate-files
    scan:
      dir: generated

The key handles the acceptable values as follows:

true - keep the temporary worktree indefinitely
until:<eventName> - keep the temporary worktree until the specified Antora event (e.g., exit, contextClosed, etc.)
false - remove the temporary worktree as soon as the Collector instance completes

The default keep behavior can be set on the extension itself using the keep_worktrees key.

If the temporary worktree is kept, the location is stored on the collectorWorktree property on the origin object to make it available to other extensions.