diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 615643c523216d1957f6f5c4546ecb16b865b586..8836e041c37f5d380008cb82c8c8eae066f3be27 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 81c0028513673057284fd4d65ea76cc73ba58498..b106fd5b476edfc002319e0afe1331f4c2deacc1 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 11f933e96210cad27847bffc8dd7937fe1406e2f..4133fdbd62c971e9e639dcac159ce8fbd017db39 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 0c9fa2c3169f7e5d0a17c63f131639e9cc71c118..5d7032f5ad8e5b44dbf1228d794ddc05fdeb6469 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' },