feat: implement reference-cache for faster checkouts

- Add `reference-cache` input to action.yml
- Introduce `GitCacheHelper` for bare clone cache management
- Prevent race conditions with `proper-lockfile` and atomic directory renames
- Support iterative submodule caching and robust relative URL resolution
- Append to `info/alternates` preserving existing alternate references
- Add fallback to standard clone on submodule cache failure
- Add unit tests for `GitCacheHelper`

Signed-off-by: Michael Wyraz <mw@brick4u.de>

src/git-auth-helper.ts

@@ -21,6 +21,7 @@ export interface IGitAuthHelper {
   configureSubmoduleAuth(): Promise<void>
   configureTempGlobalConfig(): Promise<string>
   removeAuth(): Promise<void>
+  removeGlobalAuth(): Promise<void>
   removeGlobalConfig(): Promise<void>
 }
 
@@ -235,6 +236,12 @@ class GitAuthHelper {
     await this.removeToken()
   }
 
+  async removeGlobalAuth(): Promise<void> {
+    core.debug('Removing global auth entries')
+    await this.git.tryConfigUnset('include.path', true)
+    await this.git.tryConfigUnset(this.insteadOfKey, true)
+  }
+
   async removeGlobalConfig(): Promise<void> {
     if (this.temporaryHomePath?.length > 0) {
       core.debug(`Unsetting HOME override`)

src/git-cache-helper.ts

@@ -0,0 +1,98 @@
+import * as core from '@actions/core'
+import * as path from 'path'
+import * as fs from 'fs'
+import * as crypto from 'crypto'
+import * as lockfile from 'proper-lockfile'
+import {IGitCommandManager} from './git-command-manager'
+
+export class GitCacheHelper {
+  constructor(private referenceCache: string) {}
+
+  /**
+   * Prepares the reference cache for a given repository URL.
+   * If the cache does not exist, it performs a bare clone.
+   * If it exists, it performs a fetch to update it.
+   * Returns the absolute path to the bare cache repository.
+   */
+  async setupCache(git: IGitCommandManager, repositoryUrl: string): Promise<string> {
+    const cacheDirName = this.generateCacheDirName(repositoryUrl)
+    const cachePath = path.join(this.referenceCache, cacheDirName)
+    
+    // Ensure the base cache directory exists before we try to lock inside it
+    if (!fs.existsSync(this.referenceCache)) {
+      await fs.promises.mkdir(this.referenceCache, { recursive: true })
+    }
+
+    // We use a dedicated lock dir specifically for this repository's cache
+    // since we cannot place a lock *inside* a repository that might not exist yet
+    const lockfilePath = `${cachePath}.lock`
+    
+    // Ensure the file we are locking exists
+    if (!fs.existsSync(lockfilePath)) {
+      await fs.promises.writeFile(lockfilePath, '')
+    }
+
+    core.debug(`Acquiring lock for ${repositoryUrl} at ${lockfilePath}`)
+    
+    let releaseLock: () => Promise<void>
+    try {
+      // proper-lockfile creates a ".lock" directory next to the target file.
+      // We configure it to wait up to 10 minutes (600,000 ms) for another process to finish.
+      // E.g. cloning a very large monorepo might take minutes.
+      releaseLock = await lockfile.lock(lockfilePath, {
+        retries: {
+          retries: 60,         // try 60 times
+          factor: 1,           // linear backoff
+          minTimeout: 10000,   // wait 10 seconds between tries
+          maxTimeout: 10000,   // (total max wait time: 600s = 10m)
+          randomize: true
+        }
+      })
+      core.debug(`Lock acquired.`)
+    } catch (err) {
+      throw new Error(`Failed to acquire lock for repository cache ${repositoryUrl}: ${err}`)
+    }
+
+    try {
+      if (fs.existsSync(path.join(cachePath, 'objects'))) {
+        core.info(`Reference cache for ${repositoryUrl} exists. Updating...`)
+        const args = ['-C', cachePath, 'fetch', '--force', '--prune', '--tags', 'origin', '+refs/heads/*:refs/heads/*']
+        await git.execGit(args)
+      } else {
+        core.info(`Reference cache for ${repositoryUrl} does not exist. Cloning --bare...`)
+        
+        // Use a temporary clone pattern to prevent corrupted repos if process is killed mid-clone
+        const tmpPath = `${cachePath}.tmp.${crypto.randomUUID()}`
+        try {
+          const args = ['-C', this.referenceCache, 'clone', '--bare', repositoryUrl, tmpPath]
+          await git.execGit(args)
+          
+          if (fs.existsSync(cachePath)) {
+             // In rare cases where it somehow exists but objects/ didn't, clean it up
+             await fs.promises.rm(cachePath, { recursive: true, force: true })
+          }
+          await fs.promises.rename(tmpPath, cachePath)
+        } catch (cloneErr) {
+          // Cleanup partial clone if an error occurred
+          await fs.promises.rm(tmpPath, { recursive: true, force: true }).catch(() => {})
+          throw cloneErr
+        }
+      }
+    } finally {
+      await releaseLock()
+    }
+
+    return cachePath
+  }
+
+  /**
+   * Generates a directory name for the cache based on the URL.
+   * Replaces non-alphanumeric characters with underscores
+   * and appends a short SHA256 hash of the original URL.
+   */
+  generateCacheDirName(url: string): string {
+    const cleanUrl = url.replace(/[^a-zA-Z0-9]/g, '_')
+    const hash = crypto.createHash('sha256').update(url).digest('hex').substring(0, 8)
+    return `${cleanUrl}_${hash}.git`
+  }
+}

src/git-command-manager.ts

@@ -15,6 +15,11 @@ import {GitVersion} from './git-version'
 export const MinimumGitVersion = new GitVersion('2.18')
 export const MinimumGitSparseCheckoutVersion = new GitVersion('2.28')
 
+export class GitOutput {
+  stdout = ''
+  exitCode = 0
+}
+
 export interface IGitCommandManager {
   branchDelete(remote: boolean, branch: string): Promise<void>
   branchExists(remote: boolean, pattern: string): Promise<boolean>
@@ -48,6 +53,7 @@ export interface IGitCommandManager {
   lfsFetch(ref: string): Promise<void>
   lfsInstall(): Promise<void>
   log1(format?: string): Promise<string>
+  referenceAdd(referenceObjects: string): Promise<void>
   remoteAdd(remoteName: string, remoteUrl: string): Promise<void>
   removeEnvironmentVariable(name: string): void
   revParse(ref: string): Promise<string>
@@ -80,6 +86,12 @@ export interface IGitCommandManager {
   ): Promise<string[]>
   tryReset(): Promise<boolean>
   version(): Promise<GitVersion>
+  execGit(
+    args: string[],
+    allowAllExitCodes?: boolean,
+    silent?: boolean,
+    customListeners?: any
+  ): Promise<GitOutput>
 }
 
 export async function createCommandManager(
@@ -401,6 +413,32 @@ class GitCommandManager {
     await this.execGit(['remote', 'add', remoteName, remoteUrl])
   }
 
+  async referenceAdd(referenceObjects: string): Promise<void> {
+    const alternatesPath = path.join(
+      this.workingDirectory,
+      '.git',
+      'objects',
+      'info',
+      'alternates'
+    )
+    core.info(`Configuring git alternate to reference objects at ${referenceObjects}`)
+    const infoDir = path.dirname(alternatesPath)
+    if (!fs.existsSync(infoDir)) {
+      await fs.promises.mkdir(infoDir, { recursive: true })
+    }
+    
+    let existing = ''
+    if (fs.existsSync(alternatesPath)) {
+      existing = (await fs.promises.readFile(alternatesPath, 'utf8')).trim()
+    }
+    
+    const lines = existing ? existing.split('\n') : []
+    if (!lines.includes(referenceObjects)) {
+      lines.push(referenceObjects)
+      await fs.promises.writeFile(alternatesPath, lines.join('\n') + '\n')
+    }
+  }
+
   removeEnvironmentVariable(name: string): void {
     delete this.gitEnv[name]
   }
@@ -609,7 +647,7 @@ class GitCommandManager {
     return result
   }
 
-  private async execGit(
+  async execGit(
     args: string[],
     allowAllExitCodes = false,
     silent = false,
@@ -746,7 +784,3 @@ class GitCommandManager {
   }
 }
 
-class GitOutput {
-  stdout = ''
-  exitCode = 0
-}

src/git-source-provider.ts

@@ -14,6 +14,156 @@ import {
   IGitCommandManager
 } from './git-command-manager'
 import {IGitSourceSettings} from './git-source-settings'
+import {GitCacheHelper} from './git-cache-helper'
+import * as fs from 'fs'
+
+interface SubmoduleInfo {
+  name: string
+  path: string
+  url: string
+}
+
+async function iterativeSubmoduleUpdate(
+  git: IGitCommandManager,
+  cacheHelper: GitCacheHelper,
+  repositoryPath: string,
+  fetchDepth: number,
+  nestedSubmodules: boolean
+): Promise<void> {
+  const gitmodulesPath = path.join(repositoryPath, '.gitmodules')
+  if (!fs.existsSync(gitmodulesPath)) {
+    return
+  }
+
+  const submodules = new Map<string, SubmoduleInfo>()
+
+  // Get all submodule config keys
+  try {
+    const output = await git.execGit([
+      '-C', repositoryPath,
+      'config', '--file', gitmodulesPath, '--get-regexp', 'submodule\\..*'
+    ], true, true)
+
+    const lines = output.stdout.split('\n').filter(l => l.trim().length > 0)
+    for (const line of lines) {
+      const match = line.match(/^submodule\.(.+?)\.(path|url)\s+(.*)$/)
+      if (match) {
+        const [, name, key, value] = match
+        if (!submodules.has(name)) {
+          submodules.set(name, { name, path: '', url: '' })
+        }
+        const info = submodules.get(name)!
+        if (key === 'path') info.path = value
+        if (key === 'url') info.url = value
+      }
+    }
+  } catch (err) {
+    core.warning(`Failed to read .gitmodules: ${err}`)
+    return
+  }
+
+  for (const info of submodules.values()) {
+    if (!info.path || !info.url) continue
+
+    core.info(`Processing submodule ${info.name} at ${info.path}`)
+    
+    // Resolve relative URLs or valid URLs
+    let subUrl = info.url
+    if (subUrl.startsWith('../') || subUrl.startsWith('./')) {
+      // In checkout action, relative URLs are handled automatically by git.
+      // But for our bare cache clone, we need an absolute URL.
+      let originUrl = ''
+      try {
+        const originOut = await git.execGit(['-C', repositoryPath, 'remote', 'get-url', 'origin'], true, true)
+        if (originOut.exitCode === 0) {
+          originUrl = originOut.stdout.trim()
+        }
+        
+        if (originUrl) {
+          try {
+            if (originUrl.match(/^https?:\/\//)) {
+              // Using Node's URL class to resolve relative paths for HTTP(s)
+              const parsedOrigin = new URL(originUrl.replace(/\.git$/, ''))
+              const resolvedUrl = new URL(subUrl, parsedOrigin.href + '/')
+              subUrl = resolvedUrl.href
+            } else {
+              // Fallback for SSH URLs which new URL() cannot parse (e.g. git@github.com:org/repo)
+              let originParts = originUrl.replace(/\.git$/, '').split('/')
+              originParts.pop() // remove current repo
+              
+              // Handle multiple ../
+              let subTarget = subUrl
+              while (subTarget.startsWith('../')) {
+                if (originParts.length === 0) break // Can't go higher
+                originParts.pop()
+                subTarget = subTarget.substring(3)
+              }
+              if (subTarget.startsWith('./')) {
+                subTarget = subTarget.substring(2)
+              }
+              
+              if (originParts.length > 0) {
+                subUrl = originParts.join('/') + '/' + subTarget
+              }
+            }
+          } catch {
+            // Fallback does not work
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    if (!subUrl || subUrl.startsWith('../') || subUrl.startsWith('./')) {
+      core.warning(`Could not resolve absolute URL for submodule ${info.name}. Falling back to standard clone.`)
+      await invokeStandardSubmoduleUpdate(git, repositoryPath, fetchDepth, info.path)
+      continue
+    }
+
+    try {
+      // Prepare cache
+      const cachePath = await cacheHelper.setupCache(git, subUrl)
+      
+      // Submodule update for this specific one
+      const args = ['-C', repositoryPath, '-c', 'protocol.version=2', 'submodule', 'update', '--init', '--force']
+      if (fetchDepth > 0) {
+        args.push(`--depth=${fetchDepth}`)
+      }
+      args.push('--reference', cachePath)
+      args.push(info.path)
+
+      const output = await git.execGit(args, true)
+      if (output.exitCode !== 0) {
+        throw new Error(`Submodule update failed with exit code ${output.exitCode}`)
+      }
+    } catch (err) {
+      core.warning(`Reference cache failed for submodule ${info.name} (${err}). Falling back to standard clone...`)
+      await invokeStandardSubmoduleUpdate(git, repositoryPath, fetchDepth, info.path)
+    }
+    
+    // Recursive update inside the submodule
+    if (nestedSubmodules) {
+      const subRepoPath = path.join(repositoryPath, info.path)
+      await iterativeSubmoduleUpdate(
+        git,
+        cacheHelper,
+        subRepoPath,
+        fetchDepth,
+        nestedSubmodules
+      )
+    }
+  }
+}
+
+async function invokeStandardSubmoduleUpdate(git: IGitCommandManager, repositoryPath: string, fetchDepth: number, submodulePath: string) {
+  const args = ['-C', repositoryPath, '-c', 'protocol.version=2', 'submodule', 'update', '--init', '--force']
+  if (fetchDepth > 0) {
+    args.push(`--depth=${fetchDepth}`)
+  }
+  args.push(submodulePath)
+  await git.execGit(args)
+}
 
 export async function getSource(settings: IGitSourceSettings): Promise<void> {
   // Repository URL
@@ -105,6 +255,19 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
     // Save state for POST action
     stateHelper.setRepositoryPath(settings.repositoryPath)
 
+    // If we didn't initialize it above, do it now
+    if (!authHelper) {
+      authHelper = gitAuthHelper.createAuthHelper(git, settings)
+    }
+
+    // Check if we need global auth setup early for reference cache
+    // Global auth does not require a local .git directory
+    if (settings.referenceCache) {
+      core.startGroup('Setting up global auth for reference cache')
+      await authHelper.configureGlobalAuth()
+      core.endGroup()
+    }
+
     // Initialize the repository
     if (
       !fsHelper.directoryExistsSync(path.join(settings.repositoryPath, '.git'))
@@ -113,8 +276,35 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
       await git.init()
       await git.remoteAdd('origin', repositoryUrl)
       core.endGroup()
+
+      // Setup reference cache if requested
+      if (settings.referenceCache) {
+        core.startGroup('Setting up reference repository cache')
+        const cacheHelper = new GitCacheHelper(settings.referenceCache)
+        const cachePath = await cacheHelper.setupCache(git, repositoryUrl)
+        const cacheObjects = path.join(cachePath, 'objects')
+        if (fsHelper.directoryExistsSync(cacheObjects, false)) {
+          await git.referenceAdd(cacheObjects)
+        } else {
+          core.warning(`Reference repository cache objects directory ${cacheObjects} does not exist`)
+        }
+        core.endGroup()
+      }
     }
 
+    // Remove global auth if it was set for reference cache,
+    // to avoid duplicate AUTHORIZATION headers during fetch
+    if (settings.referenceCache) {
+      core.startGroup('Removing global auth after reference cache setup')
+      await authHelper.removeGlobalAuth()
+      core.endGroup()
+    }
+
+    // Configure auth (must happen after git init so .git exists)
+    core.startGroup('Setting up auth')
+    await authHelper.configureAuth()
+    core.endGroup()
+
     // Disable automatic garbage collection
     core.startGroup('Disabling automatic garbage collection')
     if (!(await git.tryDisableAutomaticGarbageCollection())) {
@@ -124,15 +314,6 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
     }
     core.endGroup()
 
-    // If we didn't initialize it above, do it now
-    if (!authHelper) {
-      authHelper = gitAuthHelper.createAuthHelper(git, settings)
-    }
-    // Configure auth
-    core.startGroup('Setting up auth')
-    await authHelper.configureAuth()
-    core.endGroup()
-
     // Determine the default branch
     if (!settings.ref && !settings.commit) {
       core.startGroup('Determining the default branch')
@@ -264,7 +445,21 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
       // Checkout submodules
       core.startGroup('Fetching submodules')
       await git.submoduleSync(settings.nestedSubmodules)
-      await git.submoduleUpdate(settings.fetchDepth, settings.nestedSubmodules)
+      
+      if (settings.referenceCache) {
+        core.info('Iterative submodule update using reference cache')
+        const cacheHelper = new GitCacheHelper(settings.referenceCache)
+        await iterativeSubmoduleUpdate(
+          git,
+          cacheHelper,
+          settings.repositoryPath,
+          settings.fetchDepth,
+          settings.nestedSubmodules
+        )
+      } else {
+        await git.submoduleUpdate(settings.fetchDepth, settings.nestedSubmodules)
+      }
+      
       await git.submoduleForeach(
         'git config --local gc.auto 0',
         settings.nestedSubmodules

src/git-source-settings.ts

@@ -59,6 +59,11 @@ export interface IGitSourceSettings {
    */
   showProgress: boolean
 
+  /**
+   * The path to a local directory used as a reference cache for Git clones
+   */
+  referenceCache: string
+
   /**
    * Indicates whether to fetch LFS objects
    */

src/input-helper.ts

@@ -161,5 +161,9 @@ export async function getInputs(): Promise<IGitSourceSettings> {
   result.githubServerUrl = core.getInput('github-server-url')
   core.debug(`GitHub Host URL = ${result.githubServerUrl}`)
 
+  // Reference Cache
+  result.referenceCache = core.getInput('reference-cache')
+  core.debug(`Reference Cache = ${result.referenceCache}`)
+
   return result
 }