@antora/content-aggregator 3.2.0-alpha.8 → 3.2.0-rc.1

package/lib/aggregate-content.js

@@ -87,35 +87,41 @@ 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)
-    const gitPlugins = loadGitPlugins(gitConfig, playbook.network || {}, startDir)
-    const concurrency = {
-      fetch: Math.max(gitConfig.fetchConcurrency || Infinity, 1),
-      read: Math.max(gitConfig.readConcurrency || Infinity, 1),
-    }
-    const sourcesByUrl = sources.reduce((accum, source) => {
-      return accum.set(source.url, [...(accum.get(source.url) || []), Object.assign({}, sourceDefaults, source)])
-    }, new Map())
-    const progress = quiet ? undefined : createProgress(sourcesByUrl.keys(), process.stdout)
-    const refPatternCache = Object.assign(new Map(), { braces: new Map() })
-    const fetchConfig = { always: fetch, depth: Math.max(0, gitConfig.fetchDepth ?? 1) }
-    const loadOpts = { cacheDir, fetch: fetchConfig, gitPlugins, progress, startDir, refPatternCache }
-    return collectFiles(sourcesByUrl, loadOpts, concurrency).then(buildAggregate, (err) => {
-      progress?.terminate()
-      throw err
+  const READABLE_STREAM_DISABLED = process.env.READABLE_STREAM === 'disable'
+  if (!READABLE_STREAM_DISABLED) process.env.READABLE_STREAM = 'disable' // force use of Node.js stream APIs
+  return ensureCacheDir(requestedCacheDir, startDir)
+    .then((cacheDir) => {
+      const gitConfig = Object.assign({ ensureGitSuffix: true }, playbook.git)
+      const gitPlugins = loadGitPlugins(gitConfig, playbook.network || {}, startDir)
+      const concurrency = {
+        fetch: Math.max(gitConfig.fetchConcurrency || Infinity, 1),
+        read: Math.max(gitConfig.readConcurrency || Infinity, 1),
+      }
+      const sourcesByUrl = sources.reduce((accum, source) => {
+        return accum.set(source.url, [...(accum.get(source.url) || []), Object.assign({}, sourceDefaults, source)])
+      }, new Map())
+      const progress = quiet ? undefined : createProgress(sourcesByUrl.keys(), process.stdout)
+      const refPatternCache = Object.assign(new Map(), { braces: new Map() })
+      const fetchConfig = { always: fetch, depth: Math.max(0, gitConfig.fetchDepth ?? 1) }
+      const loadOpts = { cacheDir, fetch: fetchConfig, gitPlugins, progress, startDir, refPatternCache }
+      return collectFiles(sourcesByUrl, loadOpts, concurrency).then(buildAggregate, (err) => {
+        progress?.terminate()
+        throw err
+      })
     })
-  })
+    .finally(() => READABLE_STREAM_DISABLED || delete process.env.READABLE_STREAM)
 }
 
 async function collectFiles (sourcesByUrl, loadOpts, concurrency, fetchedUrls = []) {
   const loadTasks = [...sourcesByUrl.entries()].map(([url, sources]) => {
     const loadOptsForUrl = Object.assign({}, loadOpts)
-    if (loadOpts.fetch.always && fetchedUrls.length && fetchedUrls.includes(url)) loadOptsForUrl.fetch.always = false
+    if (loadOpts.fetch.always && fetchedUrls.length && ~fetchedUrls.indexOf(url)) loadOptsForUrl.fetch.always = false
     if (tagsSpecified(sources)) loadOptsForUrl.fetch.tags = true
+    const commits = commitsRequested(sources)
+    if (commits) loadOptsForUrl.fetch.commits = commits
     return loadRepository.bind(null, url, loadOptsForUrl, { url, sources })
   })
   return gracefulPromiseAllWithLimit(loadTasks, concurrency.fetch).then(([results, rejections]) => {
@@ -132,7 +138,7 @@ async function collectFiles (sourcesByUrl, loadOpts, concurrency, fetchedUrls =
     }
     return Promise.all(
       results.map(({ repo, authStatus, sources }) =>
-        selectStartPathsForRepository(repo, authStatus, sources).then((startPaths) =>
+        selectStartPathsForRepository(repo, sources).then((startPaths) =>
           collectFilesFromStartPaths.bind(null, startPaths, repo, authStatus)
         )
       )
@@ -140,9 +146,10 @@ async function collectFiles (sourcesByUrl, loadOpts, concurrency, fetchedUrls =
   })
 }
 
-function buildAggregate (componentVersionBuckets) {
-  const entries = Object.assign(new Map(), { accum: [] })
-  for (const batchesForOrigin of componentVersionBuckets) {
+function buildAggregate (componentVersionBatches) {
+  const contentAggregate = []
+  const entries = new Map()
+  for (const batchesForOrigin of componentVersionBatches) {
     for (const batch of batchesForOrigin) {
       let key, entry
       if ((entry = entries.get((key = batch.version + '@' + batch.name)))) {
@@ -151,11 +158,12 @@ function buildAggregate (componentVersionBuckets) {
         ;(batch.origins = entry.origins).push(origins[0])
         Object.assign(entry, batch)
       } else {
-        entries.set(key, batch).accum.push(batch)
+        entries.set(key, batch)
+        contentAggregate.push(batch)
       }
     }
   }
-  return entries.accum
+  return contentAggregate
 }
 
 async function loadRepository (url, opts, result = {}) {
@@ -177,6 +185,7 @@ async function loadRepository (url, opts, result = {}) {
         const fetchOpts = buildFetchOptions(repo, progress, displayUrl, credentials, gitPlugins, fetch, 'fetch')
         await git
           .fetch(fetchOpts)
+          .then(() => ensureOids(fetchOpts))
           .then(() => {
             authStatus = identifyAuthStatus(credentialManager, credentials, url)
             return git.setConfig(Object.assign({ path: 'remote.origin.private', value: authStatus }, repo))
@@ -192,12 +201,13 @@ async function loadRepository (url, opts, result = {}) {
         authStatus = await git.getConfig(Object.assign({ path: 'remote.origin.private' }, repo))
       }
     } catch (gitErr) {
-      await fsp['rm' in fsp ? 'rm' : 'rmdir'](dir, { recursive: true, force: true })
+      await fsp.rm(dir, { recursive: true, force: true })
       if (gitErr.rethrow) throw transformGitCloneError(gitErr, displayUrl)
       const fetchOpts = buildFetchOptions(repo, progress, displayUrl, credentials, gitPlugins, fetch, 'clone')
       await git
         .clone(fetchOpts)
         .then(() => git.resolveRef(Object.assign({ ref: 'HEAD', depth: 1 }, repo)))
+        .then(() => ensureOids(fetchOpts))
         .then(() => {
           authStatus = identifyAuthStatus(credentialManager, credentials, url)
           return git.setConfig(Object.assign({ path: 'remote.origin.private', value: authStatus }, repo))
@@ -216,6 +226,7 @@ async function loadRepository (url, opts, result = {}) {
     if (dotgitStat.isDirectory()) {
       repo = { cache, dir, fs, gitdir: dotgit }
     } else if (dotgitStat.isFile()) {
+      // NOTE isomorphic-git will discover the gitdir, but we must do it eagerly to process worktree patterns correctly
       repo = await resolveRepositoryFromWorktree({ cache, dir, fs, gitdir: dotgit })
     } else {
       repo = { cache, dir, fs, gitdir: dir, noCheckout: true }
@@ -245,33 +256,46 @@ function extractCredentials (url) {
     const credentials = username ? { username, password: password || '' } : {}
     return { displayUrl, url, credentials }
   }
-  if (url.startsWith('git@')) return { displayUrl: url, url: 'https://' + url.substr(4).replace(':', '/') }
+  if (url.startsWith('git@')) return { displayUrl: url, url: 'https://' + url.substring(4).replace(':', '/') }
   return { displayUrl: url, url }
 }
 
-async function selectStartPathsForRepository (repo, authStatus, sources) {
+async function selectStartPathsForRepository (repo, sources) {
   const startPaths = []
   const originUrls = {}
   for (const source of sources) {
     const { version, editUrl } = source
-    // NOTE if repository is managed (has a url property), we can assume the remote name is origin
-    // TODO if the repo has no remotes, then remoteName should be undefined
-    const remoteName = repo.url ? 'origin' : source.remote || 'origin'
-    const originUrl = repo.url || (originUrls[remoteName] ||= await resolveRemoteUrl(repo, remoteName))
+    let remoteName, originUrl
+    if (repo.url) {
+      remoteName = 'origin' // NOTE if repository is managed (has url property), we can assume remote name is origin
+      originUrl = repo.url
+    } else {
+      remoteName = source.remote || 'origin'
+      originUrl =
+        remoteName in originUrls
+          ? originUrls[remoteName]
+          : (originUrls[remoteName] = await resolveRemoteUrl(repo, remoteName))
+      if (!originUrl) {
+        remoteName = undefined
+        if ((originUrl = posixify ? 'file:///' + posixify(repo.dir) : 'file://' + repo.dir).indexOf(' ')) {
+          originUrl = originUrl.replace(SPACE_RX, '%20')
+        }
+      }
+    }
     const refs = await selectReferences(source, repo, remoteName)
     if (refs.length) {
       for (const ref of refs) {
-        for (const startPath of await selectStartPaths(source, repo, remoteName, ref)) {
+        for (const startPath of await selectStartPaths(source, repo, ref)) {
           startPaths.push({ startPath, ref, originUrl, editUrl, version })
         }
       }
     } else {
-      const { url, branches, tags } = source
+      const { url, branches, tags, commits } = source
       const startPathInfo =
         'startPaths' in source
           ? { 'start paths': source.startPaths || undefined }
           : { 'start path': source.startPath || undefined }
-      const sourceInfo = yaml.dump({ url, branches, tags, ...startPathInfo }, { flowLevel: 1 }).trimRight()
+      const sourceInfo = yaml.dump({ url, branches, tags, commits, ...startPathInfo }, { flowLevel: 1 }).trimRight()
       logger.info(`No matching references found for content source entry (${sourceInfo.replace(NEWLINE_RX, ' | ')})`)
     }
   }
@@ -280,11 +304,12 @@ async function selectStartPathsForRepository (repo, authStatus, 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, commits, worktrees: worktreePatterns } = source
   const managed = 'url' in repo
   const isBare = managed || repo.noCheckout
   const patternCache = repo.cache[REF_PATTERN_CACHE_KEY]
   const noWorktree = managed ? undefined : false
+  const isLinkedWorktree = repo.worktree?.name
   const refs = new Map()
   if (
     tagPatterns &&
@@ -295,11 +320,20 @@ async function selectReferences (source, repo, remote) {
     const tags = await git.listTags(repo)
     if (tags.length) {
       for (const shortname of filterRefs(tags, tagPatterns, patternCache)) {
-        // NOTE tags are stored using symbol keys to distinguish them from branches
-        refs.set(Symbol(shortname), { shortname, fullname: 'tags/' + shortname, type: 'tag', head: noWorktree })
+        // NOTE tags are stored using Buffer keys to distinguish them from commits and branches
+        refs.set(Buffer.from(shortname), { shortname, fullname: 'tags/' + shortname, type: 'tag', head: noWorktree })
       }
     }
   }
+  if (
+    commits &&
+    (commits = Array.isArray(commits) ? commits.map((commit) => String(commit)) : commits.split(CSV_RX)).length
+  ) {
+    for (const oid of commits) {
+      // NOTE commits are stored using Symbol keys to distinguish them from tags and branches
+      refs.set(Symbol(oid), { oid, shortname: oid, fullname: 'commits/' + oid, type: 'commit' })
+    }
+  }
   if (
     !branchPatterns ||
     !(branchPatterns = Array.isArray(branchPatterns)
@@ -308,38 +342,54 @@ async function selectReferences (source, repo, remote) {
   ) {
     return [...refs.values()]
   }
-  const worktreeName = repo.worktreeName // possibly switch to worktree property ({ name, dir}) in future
-  if (worktreeName) branchPatterns = branchPatterns.map((it) => (it === 'HEAD' ? 'HEAD@' + worktreeName : it))
-  if (worktreePatterns) {
+  let useWorktree = false
+  if (!managed && (useWorktree = {})) {
     if (worktreePatterns === '.') {
-      worktreePatterns = ['.']
+      isLinkedWorktree ? (useWorktree.linked = isLinkedWorktree) : isBare || (useWorktree.main = true)
+      worktreePatterns = []
+    } else if (!worktreePatterns) {
+      worktreePatterns = []
     } else if (worktreePatterns === true) {
-      worktreePatterns = ['.', '*']
+      if (!isBare) useWorktree.main = true
+      // NOTE if we don't start at a linked worktree, linked worktree cannot be current worktree
+      if (isLinkedWorktree) useWorktree.linked = isLinkedWorktree
+      worktreePatterns = ['*']
+    } else if (worktreePatterns === '/.') {
+      if (!isBare) useWorktree.main = true
+      worktreePatterns = []
     } else {
-      worktreePatterns = Array.isArray(worktreePatterns)
-        ? worktreePatterns.map((pattern) => String(pattern))
-        : splitRefPatterns(String(worktreePatterns))
-      if (worktreeName) worktreePatterns = worktreePatterns.map((it) => (it === '@' ? worktreeName : it))
+      worktreePatterns = (
+        Array.isArray(worktreePatterns)
+          ? worktreePatterns.map((pattern) => String(pattern))
+          : splitRefPatterns(String(worktreePatterns))
+      ).reduce((accum, it) => {
+        if (it === '/.') return (isBare || (useWorktree.main = true)) && accum
+        if (it === '.') {
+          isLinkedWorktree ? (useWorktree.linked = isLinkedWorktree) : isBare || (useWorktree.main = true)
+        } else {
+          accum.push(it)
+        }
+        return accum
+      }, [])
     }
-  } else {
-    worktreePatterns = worktreePatterns === undefined ? [worktreeName || '.'] : []
+    if (!(useWorktree.main || useWorktree.linked)) useWorktree = false
   }
   let currentBranch
-  if (branchPatterns.length === 1 && (branchPatterns[0] === 'HEAD' || branchPatterns[0] === '.')) {
-    if ((currentBranch = await getCurrentBranchName(repo, remote).then((branch) => branch ?? false))) {
-      branchPatterns = [currentBranch]
-    } else if (isBare) {
-      return [...refs.values()]
-    } else {
-      // NOTE current branch is undefined when HEAD is detached
-      const head = worktreePatterns[0] === '.' ? repo.dir : noWorktree
-      refs.set('HEAD', { shortname: 'HEAD', fullname: 'HEAD', type: 'branch', detached: true, head })
-      return [...refs.values()]
-    }
-  } else {
+  if (!isLinkedWorktree) {
     let headBranchIdx
-    // NOTE we can assume at least two entries if HEAD or . are present
-    if (~(headBranchIdx = branchPatterns.indexOf('HEAD')) || ~(headBranchIdx = branchPatterns.indexOf('.'))) {
+    if (branchPatterns.length === 1 && (branchPatterns[0] === 'HEAD' || branchPatterns[0] === '.')) {
+      if ((currentBranch = await getCurrentBranchName(repo, remote).then((branch) => branch ?? false))) {
+        branchPatterns = [currentBranch]
+      } else if (isBare) {
+        return [...refs.values()]
+      } else {
+        // NOTE current branch is undefined when HEAD is detached
+        const head = useWorktree.main ? repo.dir : noWorktree
+        refs.set('HEAD', { shortname: 'HEAD', fullname: 'HEAD', type: 'branch', detached: true, head })
+        return [...refs.values()]
+      }
+    } else if (~(headBranchIdx = branchPatterns.indexOf('HEAD')) || ~(headBranchIdx = branchPatterns.indexOf('.'))) {
+      // NOTE we can assume at least two entries if HEAD or . are present
       if ((currentBranch = await getCurrentBranchName(repo, remote).then((branch) => branch ?? false))) {
         if (~branchPatterns.indexOf(currentBranch)) {
           branchPatterns.splice(headBranchIdx, 1)
@@ -349,11 +399,7 @@ async function selectReferences (source, repo, remote) {
       } else if (isBare) {
         branchPatterns.splice(headBranchIdx, 1)
       } else {
-        let head = noWorktree
-        if (worktreePatterns[0] === '.') {
-          worktreePatterns = worktreePatterns.slice(1)
-          head = repo.dir
-        }
+        const head = useWorktree.main ? repo.dir : noWorktree
         // NOTE current branch is undefined when HEAD is detached
         refs.set('HEAD', { shortname: 'HEAD', fullname: 'HEAD', type: 'branch', detached: true, head })
         branchPatterns.splice(headBranchIdx, 1)
@@ -361,45 +407,54 @@ async function selectReferences (source, repo, remote) {
     }
   }
   // NOTE isomorphic-git includes HEAD in list of remote branches (see https://isomorphic-git.org/docs/listBranches)
-  const remoteBranches = (await git.listBranches(Object.assign({ remote }, repo))).filter((it) => it !== 'HEAD')
+  const remoteBranches = remote
+    ? (await git.listBranches(Object.assign({ remote }, repo))).filter((it) => it !== 'HEAD')
+    : []
   if (remoteBranches.length) {
     for (const shortname of filterRefs(remoteBranches, branchPatterns, patternCache)) {
       const fullname = 'remotes/' + remote + '/' + shortname
       refs.set(shortname, { shortname, fullname, type: 'branch', remote, head: noWorktree })
     }
   }
-  // NOTE only consider local branches if repo has a worktree or there are no remote tracking branches
-  if (!isBare) {
+  if (!managed) {
     const localBranches = await git.listBranches(repo).then((branches) => {
-      if (branches.length) return branches
-      if (currentBranch == null) return getCurrentBranchName(repo).then((branch) => (branch ? [branch] : []))
-      return currentBranch ? [currentBranch] : []
+      if (branches.length || isBare) return branches
+      if (currentBranch != null) return [currentBranch]
+      return getCurrentBranchName(repo).then((branch) => (branch ? [branch] : []))
     })
-    if (localBranches.length) {
-      const worktrees = await findWorktrees(repo, worktreePatterns)
-      let onMatch
-      if ((worktreePatterns.join('') || '.') !== '.') {
-        const symbolicNames = new Map()
-        worktrees.forEach(({ name, symbolicName = 'HEAD@' + name }, shortname) => {
-          localBranches.push(symbolicName)
-          symbolicNames.set(symbolicName, shortname)
-        })
-        onMatch = (candidate, { pattern }) => {
-          const shortname = symbolicNames.get(candidate)
-          return shortname ? (pattern.startsWith('HEAD@') ? shortname : undefined) : candidate
+    let onMatch, worktrees
+    if (
+      (useWorktree || worktreePatterns.length) &&
+      (worktrees = await findWorktrees(repo, worktreePatterns, useWorktree)).size
+    ) {
+      const headNames = new Map()
+      worktrees.forEach(({ name, symbolicNames }, shortname) => {
+        if (name) {
+          const headName = 'HEAD@' + name
+          localBranches.push(headName)
+          headNames.set(headName, shortname)
         }
-      }
-      for (const shortname of filterRefs(localBranches, branchPatterns, patternCache, onMatch)) {
-        const head = (worktrees.get(shortname) || { head: noWorktree }).head
-        refs.set(shortname, { shortname, fullname: 'heads/' + shortname, type: 'branch', head })
+        if (symbolicNames) {
+          for (const symbolicName of symbolicNames) {
+            const symbolicHeadName = symbolicName === 'HEAD' ? symbolicName : 'HEAD@' + symbolicName
+            localBranches.push(symbolicHeadName)
+            headNames.set(symbolicHeadName, shortname)
+          }
+        }
+      })
+      onMatch = (candidate, { pattern }) => {
+        const shortname = headNames.get(candidate)
+        if (!shortname) return candidate
+        if (pattern === 'HEAD' || pattern.startsWith('HEAD@')) return shortname
       }
     }
-  } else if (!managed || !remoteBranches.length) {
-    const localBranches = await git.listBranches(repo)
     if (localBranches.length) {
-      for (const shortname of filterRefs(localBranches, branchPatterns, patternCache)) {
-        if (refs.has(shortname)) continue // NOTE prefer remote branches in bare repository
-        refs.set(shortname, { shortname, fullname: 'heads/' + shortname, type: 'branch', head: noWorktree })
+      const preferRemote = isBare && remoteBranches.length > 0
+      for (const shortname of filterRefs(localBranches, branchPatterns, patternCache, onMatch)) {
+        if (preferRemote && refs.has(shortname)) continue
+        worktrees ??= await findWorktrees(repo, worktreePatterns, useWorktree)
+        const head = (worktrees.get(shortname) || { head: false }).head
+        refs.set(shortname, { shortname, fullname: 'heads/' + shortname, type: 'branch', head })
       }
     }
   }
@@ -419,14 +474,16 @@ function getCurrentBranchName (repo, remote) {
   ).then((ref) => (ref.startsWith('refs/') ? ref.replace(SHORTEN_REF_RX, '') : undefined))
 }
 
-async function selectStartPaths (source, repo, remoteName, ref) {
+async function selectStartPaths (source, repo, ref) {
   const url = repo.url
   const displayUrl = url || repo.dir
   const worktreePath = ref.head
   if (!worktreePath) {
-    ref.oid = await git.resolveRef(
-      Object.assign(ref.detached ? { ref: 'HEAD', depth: 1 } : { ref: 'refs/' + ref.fullname }, repo)
-    )
+    ref.oid = ref.oid
+      ? await git.expandOid(Object.assign({ oid: ref.oid }, repo)).catch(() => ref.oid)
+      : await git.resolveRef(
+          Object.assign(ref.detached ? { ref: 'HEAD', depth: 1 } : { ref: 'refs/' + ref.fullname }, repo)
+        )
   }
   if ('startPaths' in source) {
     let startPaths
@@ -461,7 +518,9 @@ function collectFilesFromStartPath (startPath, repo, authStatus, ref, originUrl,
   return (worktreePath ? readFilesFromWorktree(origin) : readFilesFromGitTree(repo, ref.oid, startPath))
     .then((files) => {
       const batch = deepClone((origin.descriptor = loadComponentDescriptor(files, ref, version)))
-      if ('nav' in batch && Array.isArray(batch.nav)) batch.nav.origin = origin
+      if ('nav' in batch && Array.isArray(batch.nav)) {
+        Object.defineProperty(batch.nav, 'origin', { configurable: true, value: origin, writable: true })
+      }
       batch.files = files.map((file) => assignFileProperties(file, origin))
       batch.origins = [origin]
       return batch
@@ -648,10 +707,10 @@ function readGitSymlink (repo, root, parent, { oid, path: name }, following) {
     let target
     let targetParent = root
     if (dirname) {
-      if (!(target = path.join('/', dirname, symlink).substr(1)) || target === dirname) {
+      if (!(target = path.join('/', dirname, symlink).substring(1)) || target === dirname) {
         target = '.'
       } else if (target.startsWith(dirname + '/')) {
-        target = target.substr(dirname.length + 1) // join doesn't remove trailing separator
+        target = target.substring(dirname.length + 1) // join doesn't remove trailing separator
         targetParent = parent
       }
     } else {
@@ -734,19 +793,19 @@ function loadComponentDescriptor (files, ref, version) {
   if (!version) {
     if (version === undefined) throw new Error(`${COMPONENT_DESC_FILENAME} is missing a version`)
     if (version === false) throw new Error(`${COMPONENT_DESC_FILENAME} has an invalid version`)
-    version = '' + (typeof version === 'number' ? version : '')
+    version = typeof version === 'number' ? '' + version : ''
   } else if (version === true) {
     version = ref.shortname.replace(PATH_SEPARATOR_RX, '-')
   } else if (version.constructor === Object) {
     const refname = ref.shortname
     let matched
     if (refname in version) {
-      matched = version[refname]
+      matched = '' + (version[refname] ?? '')
     } else if (
       !Object.entries(version).some(([pattern, replacement]) => {
-        const result = refname.replace(makeMatcherRx(pattern, VERSION_MATCHER_OPTS), '\0' + replacement)
-        if (result === refname) return false
-        matched = result.substr(1)
+        const result = refname.replace(makeMatcherRx(pattern, VERSION_MATCHER_OPTS), '\0' + (replacement ?? ''))
+        if (result === refname) return false // no match
+        matched = result.substring(1)
         return true
       })
     ) {
@@ -793,6 +852,7 @@ function buildFetchOptions (repo, progress, displayUrl, credentialsFromUrl, gitP
   } else if (!fetch.tags) {
     opts.noTags = true
   }
+  if (fetch.commits) opts.oids = fetch.commits
   return opts
 }
 
@@ -827,14 +887,17 @@ function createProgressListener (progress, progressLabel, operation) {
   // NOTE leave room for indeterminate progress at end of bar; this isn't strictly needed for a bare clone
   progressBar.scaleFactor = Math.max(0, (ticks - 1) / ticks)
   progressBar.tick(0)
-  return Object.assign(onGitProgress.bind(progressBar), { finish: onGitComplete.bind(progressBar) })
+  return Object.assign(onGitProgress.bind(progressBar), {
+    finish: onGitComplete.bind(progressBar),
+    reset: () => progressBar.update(0),
+  })
 }
 
 function formatProgressBar (label, maxLabelWidth, operation) {
   const paddingSize = maxLabelWidth - label.length
   let padding = ''
   if (paddingSize < 0) {
-    label = '...' + label.substr(-paddingSize + 3)
+    label = '...' + label.substring(-paddingSize + 3)
   } else if (paddingSize) {
     padding = ' '.repeat(paddingSize)
   }
@@ -914,21 +977,18 @@ function generateCloneFolderName (url) {
  *
  * @param {Repository} repo - The repository on which to operate.
  * @param {String} remoteName - The name of the remote to resolve.
- * @returns {String} The URL of the specified remote, if defined, or the file URI to the local repository.
+ * @returns {String} The URL of the specified remote, if defined
  */
 function resolveRemoteUrl (repo, remoteName) {
   return git.getConfig(Object.assign({ path: 'remote.' + remoteName + '.url' }, repo)).then((url) => {
-    if (url) {
-      if (url.startsWith('https://') || url.startsWith('http://')) {
-        return ~url.indexOf('@') ? url.replace(URL_AUTH_CLEANER_RX, '$1') : url
-      }
-      if (url.startsWith('git@')) return 'https://' + url.substr(4).replace(':', '/')
-      if (url.startsWith('ssh://')) {
-        return 'https://' + url.substr(url.indexOf('@') + 1 || 6).replace(URL_PORT_CLEANER_RX, '$1')
-      }
+    if (!url) return
+    if (url.startsWith('https://') || url.startsWith('http://')) {
+      return ~url.indexOf('@') ? url.replace(URL_AUTH_CLEANER_RX, '$1') : url
+    }
+    if (url.startsWith('git@')) return 'https://' + url.substring(4).replace(':', '/')
+    if (url.startsWith('ssh://')) {
+      return 'https://' + url.substring(url.indexOf('@') + 1 || 6).replace(URL_PORT_CLEANER_RX, '$1')
     }
-    url = posixify ? 'file:///' + posixify(repo.dir) : 'file://' + repo.dir
-    return ~url.indexOf(' ') ? url.replace(SPACE_RX, '%20') : url
   })
 }
 
@@ -946,6 +1006,16 @@ function tagsSpecified (sources) {
   return sources.some(({ tags }) => tags && (Array.isArray(tags) ? tags.length : true))
 }
 
+function commitsRequested (sources) {
+  if (!sources.some(({ commits }) => commits && (Array.isArray(commits) ? commits.length : true))) return
+  const result = new Set()
+  for (const { commits } of sources) {
+    if (!commits) continue
+    for (const commit of Array.isArray(commits) ? commits : commits.split(CSV_RX)) result.add(String(commit))
+  }
+  return [...result]
+}
+
 function loadGitPlugins (gitConfig, networkConfig, startDir) {
   const plugins = new Map((git.cores || git.default.cores || new Map()).get(GIT_CORE))
   for (const [name, request] of Object.entries(gitConfig.plugins || {})) {
@@ -1023,7 +1093,7 @@ function transformGitCloneError (err, displayUrl, authRequested) {
 }
 
 function splitRefPatterns (str) {
-  return ~str.indexOf('{') ? str.split(VENTILATED_CSV_RX) : str.split(CSV_RX)
+  return str.split(~str.indexOf('{') ? VENTILATED_CSV_RX : CSV_RX)
 }
 
 function camelCaseKeys (o, stopPaths = [], p = '') {
@@ -1049,47 +1119,57 @@ function coerceToString (value) {
 function resolveRepositoryFromWorktree (repo) {
   return fsp
     .readFile(repo.gitdir, 'utf8')
-    .then((contents) => contents.substr(8).trimEnd())
+    .then((contents) => contents.substring(8).trimEnd())
     .then((worktreeGitdir) =>
       fsp.readFile(ospath.join(worktreeGitdir, 'commondir'), 'utf8').then(
         (contents) => {
           const gitdir = ospath.join(worktreeGitdir, contents.trimEnd())
           const dir = ospath.basename(gitdir) === '.git' ? ospath.dirname(gitdir) : gitdir
-          return Object.assign(repo, { dir, gitdir, worktreeName: ospath.basename(worktreeGitdir) })
+          const name = ospath.basename(worktreeGitdir)
+          return Object.assign(repo, { dir, gitdir, worktree: { gitdir: worktreeGitdir, name } })
         },
         () => repo
       )
     )
 }
 
-function findWorktrees (repo, patterns) {
-  if (!patterns.length) return new Map()
-  const mainWorktree =
-    patterns[0] === '.' && (patterns = patterns.slice(1))
-      ? getCurrentBranchName(repo).then((branch) => branch && [branch, { head: repo.dir, name: '.' }])
-      : Promise.resolve()
-  const worktreesDir = patterns.length ? ospath.join(repo.dir, '.git', 'worktrees') : undefined
+function findWorktrees (repo, patterns, useWorktree) {
+  const useLinkedWorktree = !!useWorktree.linked
+  const mainWorktree = useWorktree.main
+    ? getCurrentBranchName(repo).then((branch) => {
+        if (!branch) return
+        return [branch, { head: repo.dir, name: undefined, symbolicNames: useLinkedWorktree ? ['/.'] : ['/.', '.'] }]
+      })
+    : Promise.resolve()
+  if (!(useLinkedWorktree || patterns.length)) return mainWorktree.then((entry) => new Map(entry && [entry]))
+  const worktreesDir = ospath.join(repo.dir, repo.dir === repo.gitdir ? '' : '.git', 'worktrees')
   const patternCache = repo.cache[REF_PATTERN_CACHE_KEY]
-  return (
-    worktreesDir
-      ? fsp
-          .readdir(worktreesDir)
-          .then((worktreeNames) => filterRefs(worktreeNames, patterns, patternCache), invariably.emptyArray)
-          .then((worktreeNames) =>
-            Promise.all(
-              worktreeNames.map((worktreeName) => {
-                const gitdir = ospath.resolve(worktreesDir, worktreeName)
-                // NOTE branch name defaults to worktree name if HEAD is detached
-                return getCurrentBranchName(Object.assign({}, repo, { gitdir })).then((branch = worktreeName) =>
-                  fsp
-                    .readFile(ospath.join(gitdir, 'gitdir'), 'utf8')
-                    .then((contents) => [branch, { head: ospath.dirname(contents.trimEnd()), name: worktreeName }])
-                )
-              })
-            )
+  const scanWorktrees = patterns.length
+    ? fsp
+        .readdir(worktreesDir)
+        .then((worktreeNames) => filterRefs(worktreeNames, patterns, patternCache), invariably.emptyArray)
+        .then((worktreeNames) => {
+          if (useLinkedWorktree && !~worktreeNames.indexOf(useWorktree.linked)) worktreeNames.push(useWorktree.linked)
+          return worktreeNames
+        })
+    : Promise.resolve(useLinkedWorktree ? [useWorktree.linked] : [])
+  return scanWorktrees
+    .then((worktreeNames) =>
+      Promise.all(
+        worktreeNames.map((name) => {
+          const symbolicNames = useLinkedWorktree && name === useWorktree.linked ? ['.', 'HEAD'] : undefined
+          const gitdir = ospath.resolve(worktreesDir, name)
+          // NOTE branch name defaults to worktree name if HEAD is detached
+          return getCurrentBranchName(Object.assign({}, repo, { gitdir })).then((branch = name) =>
+            fsp
+              .readFile(ospath.join(gitdir, 'gitdir'), 'utf8')
+              .then((contents) => [branch, { head: ospath.dirname(contents.trimEnd()), name, symbolicNames }])
           )
-      : Promise.resolve()
-  ).then((entries = []) => mainWorktree.then((entry) => new Map(entry ? entries.push(entry) && entries : entries)))
+        })
+      )
+    )
+    .then((entries) => new Map(entries))
+    .then((worktrees) => mainWorktree.then((result) => (result ? worktrees.set(result[0], result[1]) : worktrees)))
 }
 
 async function gracefulPromiseAllWithLimit (tasks, limit = Infinity) {
@@ -1125,4 +1205,27 @@ async function promiseAllWithLimit (tasks, limit = Infinity) {
   return Promise.all(started)
 }
 
+async function ensureOids (opts) {
+  if (!opts.oids) return
+  let prevShallowCommits = await getShallowCommits(opts)
+  if (prevShallowCommits == null) return
+  let oids = opts.oids.slice()
+  const deepenOpts = Object.assign({}, opts, { relative: true })
+  const format = 'deflated'
+  while (oids.length) {
+    deepenOpts.onProgress?.reset()
+    await git.fetch(deepenOpts)
+    const shallowCommits = await getShallowCommits(opts)
+    if (shallowCommits == null || shallowCommits === prevShallowCommits) break
+    prevShallowCommits = shallowCommits
+    oids = await Promise.all(
+      oids.map((oid) => git.readObject(Object.assign({ oid, format }, opts)).then(invariably.void, () => oid))
+    ).then((results) => results.filter((it) => it))
+  }
+}
+
+function getShallowCommits ({ gitdir }) {
+  return fsp.readFile(ospath.join(gitdir, 'shallow'), 'utf8').catch(invariably.void)
+}
+
 module.exports = aggregateContent

package/lib/compute-origin.js

@@ -42,7 +42,7 @@ function computeOrigin (url, authStatus, gitdir, ref, startPath, worktreePath =
   } else if (editUrl) {
     const vars = {
       path: () => (startPath ? path.join(startPath, '%s') : '%s'),
-      ref: () => 'refs/' + (reftype === 'branch' ? 'heads' : reftype) + '/' + refname,
+      ref: () => 'refs/' + (reftype === 'branch' ? 'head' : reftype) + 's/' + refname,
       refhash: () => refhash,
       reftype: () => reftype,
       refname: () => refname,

package/lib/filter-refs.js

@@ -6,7 +6,7 @@ function compileRx (pattern, opts) {
   if (pattern === '*' || pattern === '**') return MATCH_ALL_RX
   const rx =
     pattern.charAt() === '!' // we handle negate ourselves
-      ? Object.defineProperty(makeMatcherRx((pattern = pattern.substr(1)), opts), 'negated', { value: true })
+      ? Object.defineProperty(makeMatcherRx((pattern = pattern.substring(1)), opts), 'negated', { value: true })
       : makeMatcherRx(pattern, opts)
   return Object.defineProperty(rx, 'pattern', { value: pattern })
 }
@@ -39,6 +39,7 @@ function createMatcher (patterns, cache = Object.assign(new Map(), { braces: new
 }
 
 function filterRefs (candidates, patterns, cache, onMatch) {
+  if (!(patterns = patterns.filter(compact)).length) return []
   const match = createMatcher(patterns, cache)
   return candidates.reduce((accum, candidate) => {
     if ((candidate = match(candidate, onMatch))) accum.push(candidate)
@@ -46,4 +47,8 @@ function filterRefs (candidates, patterns, cache, onMatch) {
   }, [])
 }
 
+function compact (str) {
+  return str !== ''
+}
+
 module.exports = filterRefs

package/lib/resolve-path-globs.js

@@ -14,7 +14,7 @@ function resolvePathGlobs (base, patterns, listDirents, retrievePath, tree = { p
     if (pattern.charAt() === '!') {
       return paths.then((resolvedPaths) => {
         if (resolvedPaths.length) {
-          const rx = makeMatcherRx(pattern.substr(1), MATCHER_OPTS)
+          const rx = makeMatcherRx(pattern.substring(1), MATCHER_OPTS)
           return resolvedPaths.filter((it) => !rx.test(it))
         }
         return resolvedPaths

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/content-aggregator",
-  "version": "3.2.0-alpha.8",
+  "version": "3.2.0-rc.1",
   "description": "Fetches and aggregates content from distributed sources for use in an Antora documentation pipeline.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -33,14 +33,14 @@
   },
   "dependencies": {
     "@antora/expand-path-helper": "~3.0",
-    "@antora/logger": "3.2.0-alpha.8",
+    "@antora/logger": "3.2.0-rc.1",
     "@antora/user-require-helper": "~3.0",
     "braces": "~3.0",
     "cache-directory": "~2.0",
     "fast-glob": "~3.3",
     "hpagent": "~1.2",
-    "isomorphic-git": "~1.25",
-    "js-yaml": "~4.1",
+    "isomorphic-git": "~1.38",
+    "js-yaml": "~4.2",
     "multi-progress": "~4.0",
     "picomatch": "~4.0",
     "progress": "~2.0",
@@ -49,7 +49,7 @@
     "vinyl": "~3.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "files": [
     "lib/"
@@ -65,7 +65,7 @@
     "web publishing"
   ],
   "scripts": {
-    "test": "_mocha",
+    "test": "node --test",
     "prepublishOnly": "npx -y downdoc@latest --prepublish",
     "postpublish": "npx -y downdoc@latest --postpublish"
   }