From 6880aa6fd1e0a11a49634fa0aa0c320be6ef6005 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Wed, 24 Jul 2024 01:32:40 -0600 Subject: [PATCH] resolves #23 always create worktree if create_worktrees option on extension or worktree.create option on collector config is always --- CHANGELOG.adoc | 1 + .../ROOT/pages/configuration-keys.adoc | 26 +++++++- packages/collector-extension/lib/index.js | 10 +-- .../test/collector-extension-test.js | 66 +++++++++++++++++++ 4 files changed, 96 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 615643c..8836e04 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -27,6 +27,7 @@ For a detailed view of what's changed, refer to the {url-repo}/commits[commit hi * 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.checkout` on the collector config (#8) * allow keep worktree behavior to be configured per origin by setting `worktree.keep` on the collector config (#22) +* always create worktree if `create_worktrees` option on extension or `worktree.create` option on collector config is `always` (#23) == 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 81c0028..b106fd5 100644 --- a/docs/modules/ROOT/pages/configuration-keys.adoc +++ b/docs/modules/ROOT/pages/configuration-keys.adoc @@ -58,7 +58,7 @@ If the `collector` key is an array, the `worktree` key must be specified in the The `worktree` key accepts map. Acceptable keys are `checkout` and `keep`. -By default, Collector will checkout the git reference into a temporary worktree if the content source does not already have a worktree. +By default, Collector will check out the git reference into a temporary worktree if the content source root (i.e., origi) 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 @@ -79,7 +79,7 @@ ext: ---- 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 command cannot be a file in the git repository (unless the command does its own git 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. The decision to keep the worktree can be configured per origin by setting `worktree.keep` on the collector configuration. @@ -102,6 +102,28 @@ ext: This `worktree.keep` setting overrides the global setting on the extension. +By default, Collector will reuse the worktee for a content source root (i.e., origin) if it has one. +If it does not, Collector will check out the git reference into a temporary worktree. +You can force Collector to always create a temporary worktree by setting the `create_worktrees` key on the extension or the `worktree.create` key on the collector configuration to `always`. + +.antora.yml +[,yaml] +---- +name: colorado +title: Colorado +version: '5.6.0' +ext: + collector: + worktree: + create: always + run: + - command: generate-files + scan: + dir: generated +---- + +Note that when this behavior is enabled, the command will not be able to see any uncommitted files in the local worktree. + [#clean-key] == clean key diff --git a/packages/collector-extension/lib/index.js b/packages/collector-extension/lib/index.js index 11f933e..4133fdb 100644 --- a/packages/collector-extension/lib/index.js +++ b/packages/collector-extension/lib/index.js @@ -21,7 +21,7 @@ const PACKAGE_NAME = require('../package.json').name const CONTEXT_VARIABLE_REF_RX = /\$\{\{ *([a-z0-9_.]+)(?: as (json|yaml))? *\}\}/gi -module.exports.register = function ({ config: { keepWorktrees = false } }) { +module.exports.register = function ({ config: { createWorktrees = 'auto', keepWorktrees = false } }) { this.once('contentAggregated', async ({ playbook, contentAggregate }) => { let logger const playbookEnv = playbook.env @@ -37,11 +37,11 @@ module.exports.register = function ({ config: { keepWorktrees = false } }) { let collectorConfig = descriptor?.ext?.collector || [] if (!(Array.isArray(collectorConfig) ? collectorConfig.length : (collectorConfig = [collectorConfig]))) continue let worktreeDir = worktree - const createWorktree = !worktree - let checkoutWorktree + const worktreeConfig = collectorConfig[0].worktree || {} + const createWorktree = + !worktree || ('create' in worktreeConfig ? worktreeConfig.create : createWorktrees) === 'always' + const checkoutWorktree = worktreeConfig.checkout !== false if (createWorktree) { - const worktreeConfig = collectorConfig[0].worktree || {} - checkoutWorktree = worktreeConfig.checkout !== false const keepWorktree = 'keep' in worktreeConfig ? worktreeConfig.keep : keepWorktrees worktreeDir = ospath.join(cacheDir, generateWorktreeFolderName(origin, keepWorktree)) if (managedWorktrees.has(worktreeDir)) { diff --git a/packages/collector-extension/test/collector-extension-test.js b/packages/collector-extension/test/collector-extension-test.js index 0c9fa2c..5d7032f 100644 --- a/packages/collector-extension/test/collector-extension-test.js +++ b/packages/collector-extension/test/collector-extension-test.js @@ -376,6 +376,72 @@ describe('collector extension', () => { }) }) + it('should not run in local worktree if createWorktrees is set to always on extension', async () => { + const collectorConfig = { + globalConfig: { createWorktrees: 'always' }, + run: { command: 'node .gen-start-page.js' }, + scan: { dir: 'build' }, + } + await runScenario({ + repoName: 'test-at-root', + collectorConfig, + local: true, + before: (contentAggregate) => { + expect(contentAggregate).to.have.lengthOf(1) + expect(contentAggregate[0].files).to.be.empty() + }, + after: (contentAggregate) => { + expect(contentAggregate[0].files).to.have.lengthOf(1) + const expectedScanned = 'build/modules/ROOT/pages/index.adoc' + const localAbspath = ospath.join(contentAggregate[0].origins[0].worktree, expectedScanned) + expect(contentAggregate[0].files[0]).to.have.property('stat') + expect(contentAggregate[0].files[0].src).to.include({ + path: 'modules/ROOT/pages/index.adoc', + basename: 'index.adoc', + stem: 'index', + extname: '.adoc', + abspath: expectedScanned, + scanned: expectedScanned, + origin: contentAggregate[0].origins[0], + }) + expect(contentAggregate[0].files[0].src.abspath).to.not.equal(localAbspath) + }, + }) + }) + + it('should not run in local worktree if worktree.create is set to always on collector config', async () => { + const collectorConfig = { + worktree: { create: 'always' }, + run: { command: 'node .gen-start-page.js' }, + scan: { dir: 'build' }, + } + await runScenario({ + repoName: 'test-at-root', + collectorConfig, + local: true, + before: (contentAggregate) => { + expect(contentAggregate).to.have.lengthOf(1) + expect(contentAggregate[0].files).to.be.empty() + }, + after: (contentAggregate) => { + expect(contentAggregate[0].files).to.have.lengthOf(1) + const expectedScanned = 'build/modules/ROOT/pages/index.adoc' + const localAbspath = ospath.join(contentAggregate[0].origins[0].worktree, expectedScanned) + expect(contentAggregate[0].files[0]).to.have.property('stat') + expect(contentAggregate[0].files[0].src).to.include({ + path: 'modules/ROOT/pages/index.adoc', + basename: 'index.adoc', + stem: 'index', + extname: '.adoc', + abspath: expectedScanned, + scanned: expectedScanned, + origin: contentAggregate[0].origins[0], + }) + expect(contentAggregate[0].files[0].src.abspath).to.not.equal(localAbspath) + }, + }) + }) + it('should update component metadata from antora.yml file, if found', async () => { const collectorConfig = { run: { command: '$NODE .gen-component-desc.js' }, -- GitLab