From e3931b618f6b2d95a5ff3041ab2fd2dc8a0513e6 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Mon, 22 Jul 2024 13:25:09 -0600 Subject: [PATCH] resolves #8 allow checkout of worktree to be bypassed by setting worktree.false on the collector config --- CHANGELOG.adoc | 1 + .../ROOT/pages/configuration-keys.adoc | 39 +++++++++++++++ docs/modules/ROOT/pages/index.adoc | 1 + packages/collector-extension/lib/index.js | 15 ++++-- .../test/collector-extension-test.js | 47 +++++++++++++++++++ 5 files changed, 99 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index df0d7bb..c29f09c 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 454f0d2..2191c56 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 eb063af..c84cd09 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 bd6ab00..a813225 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 0596e10..82ac333 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(() => -- GitLab