From 58d392916e951ef512ba985d478c193f2c8cb788 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Thu, 2 Oct 2025 20:16:42 -0600 Subject: [PATCH] resolves #746 allow default worktrees value to be configured --- CHANGELOG.adoc | 1 + .../modules/playbook/pages/configure-content-sources.adoc | 8 +++++++- docs/modules/playbook/pages/content-worktrees.adoc | 4 ++-- packages/content-aggregator/lib/aggregate-content.js | 6 +++--- .../content-aggregator/test/aggregate-content-test.js | 2 ++ packages/playbook-builder/lib/config/schema.js | 5 +++++ packages/playbook-builder/lib/solitary-convict.js | 8 ++++++++ packages/playbook-builder/test/build-playbook-test.js | 2 ++ .../test/fixtures/content-source-merge-spec-sample.yml | 1 + .../test/fixtures/default-schema-spec-sample.yml | 1 + 10 files changed, 32 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 56aebd931..8a7d26110 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -11,6 +11,7 @@ This project utilizes semantic versioning. * *content-aggregator*: Use symbolic name `.` to refer to current worktree and `/.` to refer to main worktree on `worktrees` key (#1187) * *content-aggregator*: Allow symbolic name `.` to be placed anywhere in list of patterns on `worktrees` key (#1188) +* *content-aggregator*: Allow default worktrees value to be configured using `worktrees` key on `content` key in playbook (#746) * *content-classifier*: Allow page alias to resolve to an attachment (#1185) * *asciidoc-loader*: Store document ID, if set, on asciidoc metadata object on page (#1186) diff --git a/docs/modules/playbook/pages/configure-content-sources.adoc b/docs/modules/playbook/pages/configure-content-sources.adoc index 858c6a9e9..60be7a98d 100644 --- a/docs/modules/playbook/pages/configure-content-sources.adoc +++ b/docs/modules/playbook/pages/configure-content-sources.adoc @@ -16,6 +16,7 @@ content: # <.> branches: [v2.0, v2.5, v3.0] # <.> tags: [release/*, '!release/*-patch'] # <.> edit_url: '{web_url}/blob/{refname}/{path}' # <.> + worktrees: true # <.> sources: # <.> - url: https://git-service.com/org/repo-z.git # <.> start_path: path-to/content-source-root # <.> @@ -24,6 +25,7 @@ content: # <.> <.> Required `content` key <.> Optional `branches` key <.> Optional `tags` key +<.> Optional `worktrees` key <.> Optional `edit_url` key <.> Required `sources` key <.> Required `url` key @@ -33,7 +35,7 @@ content: # <.> The `content` and `sources` keys are required. The `sources` key must contain at least one entry with the `url` key defined. All other keys are optional. -The xref:content-branches.adoc#default[branches] and xref:content-edit-url.adoc#default[edit_url] keys have built-in values Antora automatically applies at runtime if they're not explicitly set in the playbook. +The xref:content-branches.adoc#default[branches], xref:content-worktrees.adoc#default[worktrees], and xref:content-edit-url.adoc#default[edit_url] keys have built-in values Antora automatically applies at runtime if they're not explicitly set in the playbook. Keys-value pairs that are specified directly under `content` are applied to all of the `url` key entries under `sources`, unless the key is also specified on a specific `url`. @@ -111,6 +113,10 @@ Accommodates the following placeholder segments: `+{web_url}+`, `+{refname}+`, ` |xref:content-tags.adoc[tags] |Accepts a list of exact tag names and name patterns to use from the repository specified in the content source. |No + +|xref:content-worktrees.adoc[worktrees] +|Accepts a boolean value or list of exact worktree names, name patterns, or symbolic names to control which corresponding worktrees Antora should use for any branches it selects. +|No |=== [#content-source-reference] diff --git a/docs/modules/playbook/pages/content-worktrees.adoc b/docs/modules/playbook/pages/content-worktrees.adoc index 3212046ad..9147e366c 100644 --- a/docs/modules/playbook/pages/content-worktrees.adoc +++ b/docs/modules/playbook/pages/content-worktrees.adoc @@ -10,7 +10,7 @@ Worktrees are only relevant for branches, not tags. == worktrees key The `worktrees` key is optional. -The key can only be specified on a content source (which overrides the built-in value). +The key can be specified directly on the `content` key (which changes the default value for all content sources) or on an individual content source (which overrides the inherited default value). The `worktrees` key accepts a boolean value or list. Each value in the list can be an exact worktree name (e.g., `v2.3`, `main`, etc.), a positive or negative name pattern (e.g., `+v2.*+`, `+v@({1..9})*({0..9}).+({0..9}).x+`, etc.), or a symbolic name (e.g., `.`). The list of name patterns can be any combination of these value types, with one caveat. @@ -36,7 +36,7 @@ When the `worktrees` key isn't set on a content source, Antora use the [.term]*d That means Antora will use the main worktree of the (local) repository (represented as `.`) if the current branch of that worktree is selected by the `branches` filter. If such a match is made, Antora uses the files from that worktree instead of the files from the git tree for that branch. -You cannot currently customize the default value. +You can override the default filter by setting the `worktrees` key directly on the `content` parent key. == Use all worktrees diff --git a/packages/content-aggregator/lib/aggregate-content.js b/packages/content-aggregator/lib/aggregate-content.js index 5973346e4..767e7b61a 100644 --- a/packages/content-aggregator/lib/aggregate-content.js +++ b/packages/content-aggregator/lib/aggregate-content.js @@ -87,8 +87,8 @@ const URL_PORT_CLEANER_RX = /^([^/]+):[0-9]+(?=\/)/ */ function aggregateContent (playbook) { const startDir = playbook.dir || '.' - const { branches, editUrl, tags, sources } = playbook.content - const sourceDefaults = { branches, editUrl, tags } + const { branches, editUrl, tags, sources, worktrees } = playbook.content + const sourceDefaults = { branches, editUrl, tags, worktrees } const { cacheDir: requestedCacheDir, fetch, quiet } = playbook.runtime return ensureCacheDir(requestedCacheDir, startDir).then((cacheDir) => { const gitConfig = Object.assign({ ensureGitSuffix: true }, playbook.git) @@ -293,7 +293,7 @@ async function selectStartPathsForRepository (repo, sources) { // QUESTION should we resolve HEAD to a ref eagerly to avoid having to do a match on it? async function selectReferences (source, repo, remote) { - let { branches: branchPatterns, tags: tagPatterns, worktrees: worktreePatterns = '.' } = source + let { branches: branchPatterns, tags: tagPatterns, worktrees: worktreePatterns } = source const managed = 'url' in repo const isBare = managed || repo.noCheckout const patternCache = repo.cache[REF_PATTERN_CACHE_KEY] diff --git a/packages/content-aggregator/test/aggregate-content-test.js b/packages/content-aggregator/test/aggregate-content-test.js index 0c4925728..72420ee51 100644 --- a/packages/content-aggregator/test/aggregate-content-test.js +++ b/packages/content-aggregator/test/aggregate-content-test.js @@ -164,6 +164,8 @@ describe('aggregateContent()', () => { content: { sources: [], branches: ['HEAD', 'v{0..9}*'], + worktrees: '.', + editUrl: true, }, } clean() diff --git a/packages/playbook-builder/lib/config/schema.js b/packages/playbook-builder/lib/config/schema.js index ba07a3e63..a76999279 100644 --- a/packages/playbook-builder/lib/config/schema.js +++ b/packages/playbook-builder/lib/config/schema.js @@ -86,6 +86,11 @@ module.exports = { format: 'array-or-string', default: undefined, }, + worktrees: { + doc: 'The default worktrees pattern to use when no specific pattern is provided.', + format: 'boolean-or-array-or-string', + default: '.', + }, }, ui: { bundle: { diff --git a/packages/playbook-builder/lib/solitary-convict.js b/packages/playbook-builder/lib/solitary-convict.js index 96bd7ef71..7f733e830 100644 --- a/packages/playbook-builder/lib/solitary-convict.js +++ b/packages/playbook-builder/lib/solitary-convict.js @@ -44,6 +44,14 @@ function registerFormats (convict) { } }, }) + convict.addFormat({ + name: 'boolean-or-array-or-string', + validate: (val) => { + if (!(val == null || typeof val === 'boolean' || val.constructor === String || Array.isArray(val))) { + throw new Error('must be a boolean, array, string, or null') + } + }, + }) convict.addFormat({ name: 'map', validate: (val) => { diff --git a/packages/playbook-builder/test/build-playbook-test.js b/packages/playbook-builder/test/build-playbook-test.js index 1b667aea3..afc98d7c3 100644 --- a/packages/playbook-builder/test/build-playbook-test.js +++ b/packages/playbook-builder/test/build-playbook-test.js @@ -767,6 +767,7 @@ describe('buildPlaybook()', () => { expect(playbook.site.startPage).to.equal('1.0@server::intro') expect(playbook.site.keys.googleAnalytics).to.equal('XX-123456') expect(playbook.site.keys.jiraCollectorId).to.equal('xyz123') + expect(playbook.content.worktrees).to.be.true() expect(playbook.content.branches).to.eql('HEAD, v*') expect(playbook.content.editUrl).to.equal('{web_url}/blob/{refname}/{path}') expect(playbook.content.sources).to.have.lengthOf(1) @@ -812,6 +813,7 @@ describe('buildPlaybook()', () => { const playbook = buildPlaybook(['--playbook', contentSourceMergeSpec], {}) expect(playbook).to.have.nested.property('content.sources') const sources = playbook.content.sources + expect(playbook.content.worktrees).to.eql(['.', '*']) expect(sources).to.have.lengthOf(3) expect(sources[0]).to.have.property('url', 'https://git.example.org/project-a-docs.git') expect(sources[1]).to.have.property('url', 'https://git.example.org/project-b-docs.git') diff --git a/packages/playbook-builder/test/fixtures/content-source-merge-spec-sample.yml b/packages/playbook-builder/test/fixtures/content-source-merge-spec-sample.yml index 4aa382b4b..592f659d9 100644 --- a/packages/playbook-builder/test/fixtures/content-source-merge-spec-sample.yml +++ b/packages/playbook-builder/test/fixtures/content-source-merge-spec-sample.yml @@ -1,4 +1,5 @@ content: + worktrees: ['.', '*'] sources: - &base_source url: https://git.example.org/project-a-docs.git diff --git a/packages/playbook-builder/test/fixtures/default-schema-spec-sample.yml b/packages/playbook-builder/test/fixtures/default-schema-spec-sample.yml index a38e72f63..4cfe48c48 100644 --- a/packages/playbook-builder/test/fixtures/default-schema-spec-sample.yml +++ b/packages/playbook-builder/test/fixtures/default-schema-spec-sample.yml @@ -30,6 +30,7 @@ site: jira_collector_id: 'xyz123' content: branches: HEAD, v* + worktrees: true edit_url: '{web_url}/blob/{refname}/{path}' sources: - url: https://gitlab.com/antora/demo/demo-component-a.git -- GitLab