diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index df0d7bb4cda3d6cbf4be37dc403697b848a39e0d..c29f09c1228d055568557c8d908b4ddab060d676 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -10,6 +10,7 @@ For a detailed view of what's changed, refer to the {url-repo}/commits[commit hi * allow target bucket to be specified using `into` key on scan operation (#3) * allow different target bucket to be specified in scanned antora.yml when `create` key is true (#3) +* allow checkout of worktree to be bypassed by setting `worktree.false` on the collector config (#8) == 1.0.0-alpha.6 (2024-07-17) diff --git a/docs/modules/ROOT/pages/configuration-keys.adoc b/docs/modules/ROOT/pages/configuration-keys.adoc index 454f0d2ec30d5135fc9fcc4844fbcedfabe47c5e..2191c5672aab3a0e4341729a87a2dc7a7641bf69 100644 --- a/docs/modules/ROOT/pages/configuration-keys.adoc +++ b/docs/modules/ROOT/pages/configuration-keys.adoc @@ -49,6 +49,39 @@ TIP: If there's only a single entry, the array can be replaced by a map (i.e., d If the `collector` key isn't set in a component version descriptor, or its value is falsy, the extension won't run on that git reference. +[#worktree-key] +== worktree key + +The `worktree` key must be nested under the `collector` key. +If the `collector` key is an array, the `worktree` key must be specified in the first entry of the array. + +The `worktree` key accepts map. +Currently, the only key recognized in that map is `checkout`. + +By default, Collector will checkout the git reference into a temporary worktree if the content source does not already have a worktree. +To turn off the default behavior and run collector in an empty directory, set the value of this key to `false`. + +.antora.yml +[,yaml] +---- +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, the command to run must be available on the system. +The command cannot be a file in the git repository (unless the command does its own checkout). +The purpose of this option is to avoid the overhead of checking out the worktree when the Collector run does not need any of those files. + [#clean-key] == clean key @@ -243,6 +276,12 @@ The table below lists the keys that can be defined in a component version descri |=== |Collector Keys |Description |Default |Values +|`worktree.checkout` +|Specifies whether the git reference should be checked out into the prepared worktree (i.e., the equivalent of `git checkout`) when the content source does not have a worktree. +Set to false to turn off the default behavior and run collector in an empty directory. +|true +|Boolean + |`clean.dir` |Defines the location of a directory to clean before processing the rest of the collector entry (i.e., before run and scan). The value of the `dir` key is a string path for a single directory. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index eb063afcb9d1598f43ee5d962487e5e26879c32b..c84cd0922f6d69529f3f7d243747408554a09fa5 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -22,6 +22,7 @@ The second action (`run`) enables you to designate one or more external commands The commands are run in the context of a temporary worktree for the git reference of the content root. The third action (`scan`) enables you to specify one or more directories to scan and import matched files into the content aggregate bucket (files grouped by component name and version) associated with the content root. Those files, in turn, get added to the content catalog. +The extension also provides an optional key named `worktree` to controls whether the worktree is checked out when the content source doesn't have one. == Collected files diff --git a/packages/collector-extension/lib/index.js b/packages/collector-extension/lib/index.js index bd6ab004dffcd9b84ef1ffbeb60487db1b9668d0..a813225e17dfca9d4041d1c4c8a6616935d3110a 100644 --- a/packages/collector-extension/lib/index.js +++ b/packages/collector-extension/lib/index.js @@ -34,13 +34,16 @@ module.exports.register = function ({ config: { keepWorktrees = false } }) { let collectorConfig = descriptor?.ext?.collector || [] if (!(Array.isArray(collectorConfig) ? collectorConfig.length : (collectorConfig = [collectorConfig]))) continue let worktreeDir = worktree + let checkout if (!worktree) { worktreeDir = ospath.join(cacheDir, generateWorktreeFolderName(origin, keepWorktrees)) + checkout = collectorConfig[0].worktree?.checkout !== false if (managedWorktrees.has(worktreeDir)) { managedWorktrees.get(worktreeDir).add(origin) + if (!checkout) await fsp.rm(worktreeDir, { force: true, recursive: true }) } else { managedWorktrees.set(worktreeDir, new Set([origin])) - if (keepWorktrees !== true) await fsp.rm(worktreeDir, { force: true, recursive: true }) + if (!checkout || keepWorktrees !== true) await fsp.rm(worktreeDir, { force: true, recursive: true }) } origin.collectorWorktree = worktreeDir } @@ -71,9 +74,13 @@ module.exports.register = function ({ config: { keepWorktrees = false } }) { } }) if (!worktree) { - const cache = gitCache[gitdir] || (gitCache[gitdir] = {}) - const ref = `refs/${reftype === 'branch' ? 'head' : reftype}s/${refname}` - await prepareWorktree({ fs, cache, dir: worktreeDir, gitdir, ref, remote, bare: worktree === undefined }) + if (checkout) { + const cache = gitCache[gitdir] || (gitCache[gitdir] = {}) + const ref = `refs/${reftype === 'branch' ? 'head' : reftype}s/${refname}` + await prepareWorktree({ fs, cache, dir: worktreeDir, gitdir, ref, remote, bare: worktree === undefined }) + } else { + await fsp.mkdir(worktreeDir, { recursive: true }) + } } for (const { clean: cleans, run: runs, scan: scans } of collectors) { for (const clean of cleans) { diff --git a/packages/collector-extension/test/collector-extension-test.js b/packages/collector-extension/test/collector-extension-test.js index 0596e109fd2c1d65d4295b7bb7cc61fa6c933c80..82ac333970cb2936065bb531390792ce0cc48fba 100644 --- a/packages/collector-extension/test/collector-extension-test.js +++ b/packages/collector-extension/test/collector-extension-test.js @@ -1344,6 +1344,53 @@ describe('collector extension', () => { }) }) + it('should not checkout reference if worktree.checkout is false', async () => { + const command = + "node -e 'fs.writeFileSync(process.argv[1], String(fs.existsSync(process.argv[2])))' home.adoc .git" + const collectorConfig = { + worktree: { checkout: false }, + run: { command }, + scan: { dir: '.', into: 'modules/ROOT/pages' }, + } + await runScenario({ + repoName: 'test-at-root', + collectorConfig, + after: (contentAggregate) => { + expect(contentAggregate).to.have.lengthOf(1) + const bucket = contentAggregate[0] + expect(bucket.files).to.have.lengthOf(1) + expect(bucket.files[0].path).to.equal('modules/ROOT/pages/home.adoc') + expect(bucket.files[0].contents.toString()).to.equal('false') + }, + }) + }) + + it('should only look for checkout config in first entry in config array', async () => { + const command = + "node -e 'fs.writeFileSync(process.argv[1], String(fs.existsSync(process.argv[2])))' home.adoc .git" + const collectorConfig = [ + { + worktree: { checkout: false }, + }, + { + worktree: { checkout: true }, // ignored + run: { command }, + scan: { dir: '.', into: 'modules/ROOT/pages' }, + }, + ] + await runScenario({ + repoName: 'test-at-root', + collectorConfig, + after: (contentAggregate) => { + expect(contentAggregate).to.have.lengthOf(1) + const bucket = contentAggregate[0] + expect(bucket.files).to.have.lengthOf(1) + expect(bucket.files[0].path).to.equal('modules/ROOT/pages/home.adoc') + expect(bucket.files[0].contents.toString()).to.equal('false') + }, + }) + }) + it('should send output from command to stdout by default', async () => { const collectorConfig = { run: { command: 'node .gen-output.js' } } const stdout = await captureStdout(() =>