Feature/git cache

README.md

@@ -160,6 +160,12 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     # running from unless specified. Example URLs are https://github.com or
     # https://my-ghes-server.example.com
     github-server-url: ''
+
+    # Path to a local directory used as a reference cache for Git clones. Over time,
+    # this directory will contain bare clones of the checked-out repositories (and
+    # their submodules). Using this significantly reduces network bandwidth and speeds
+    # up clones.
+    reference-cache: ''
 ```
 <!-- end usage -->
 

__test__/git-auth-helper.test.ts

@@ -1047,8 +1047,10 @@ async function setup(testName: string): Promise<void> {
     lfsFetch: jest.fn(),
     lfsInstall: jest.fn(),
     log1: jest.fn(),
+    referenceAdd: jest.fn(),
     remoteAdd: jest.fn(),
     removeEnvironmentVariable: jest.fn((name: string) => delete git.env[name]),
+    execGit: jest.fn(),
     revParse: jest.fn(),
     setEnvironmentVariable: jest.fn((name: string, value: string) => {
       git.env[name] = value
@@ -1157,6 +1159,7 @@ async function setup(testName: string): Promise<void> {
     sparseCheckout: [],
     sparseCheckoutConeMode: true,
     fetchDepth: 1,
+    fetchDepthExplicit: false,
     fetchTags: false,
     showProgress: true,
     lfs: false,
@@ -1173,7 +1176,8 @@ async function setup(testName: string): Promise<void> {
     sshUser: '',
     workflowOrganizationId: 123456,
     setSafeDirectory: true,
-    githubServerUrl: githubServerUrl
+    githubServerUrl: githubServerUrl,
+    referenceCache: ''
   }
 }
 

__test__/git-cache-helper.test.ts

@@ -0,0 +1,109 @@
+import * as path from 'path'
+import * as fs from 'fs'
+import * as io from '@actions/io'
+import { GitCacheHelper } from '../src/git-cache-helper'
+import { IGitCommandManager } from '../src/git-command-manager'
+
+describe('GitCacheHelper', () => {
+  let cacheHelper: GitCacheHelper
+  let mockGit: jest.Mocked<IGitCommandManager>
+
+  const cacheDir = path.join(__dirname, 'test-cache')
+
+  beforeEach(async () => {
+    cacheHelper = new GitCacheHelper(cacheDir)
+    mockGit = {
+      execGit: jest.fn().mockImplementation(async (args) => {
+        // If git clone is called, simulate creating the destination dir
+        if (args && args.includes('clone')) {
+          const dest = args.find((a: string) => a.includes('.tmp.'));
+          if (dest) {
+            await io.mkdirP(dest);
+          } else {
+            console.log('No .tmp. found in args:', args);
+          }
+        }
+        return { exitCode: 0, stdout: '', stderr: '' };
+      }),
+      gitEnv: {}
+    } as any
+
+    await io.mkdirP(cacheDir)
+  })
+
+  afterEach(async () => {
+    await io.rmRF(cacheDir)
+  })
+
+  it('generates a consistent, short, and safe cache directory name', () => {
+    const url1 = 'https://github.com/mwyraz/forgejo-actions-checkout.git'
+    const name1 = (cacheHelper as any).generateCacheDirName(url1)
+
+    // Check structure: safe string + hash
+    expect(name1).toMatch(/^https___github_com_mwyraz_forgejo_actions_checkout_git_[0-9a-f]{8}\.git$/)
+
+    // Same URL should produce the same directory name
+    const url1_duplicate = 'https://github.com/mwyraz/forgejo-actions-checkout.git'
+    expect((cacheHelper as any).generateCacheDirName(url1_duplicate)).toBe(name1)
+
+    // Different URL should produce a different directory name
+    const url2 = 'https://github.com/mwyraz/forgejo-actions-checkout-other.git'
+    expect((cacheHelper as any).generateCacheDirName(url2)).not.toBe(name1)
+
+    // SSH URL
+    const url3 = 'git@github.com:auth/repo.git'
+    const name3 = (cacheHelper as any).generateCacheDirName(url3)
+    expect(name3).toMatch(/^git_github_com_auth_repo_git_[0-9a-f]{8}\.git$/)
+
+    // Unclean URLs
+    const url4 = 'https://github.com/foo/bar.git?v=1'
+    const name4 = (cacheHelper as any).generateCacheDirName(url4)
+    expect(name4).toMatch(/^https___github_com_foo_bar_git_v_1_[0-9a-f]{8}\.git$/)
+  })
+
+  it('sets up a cache directory if it does not exist', async () => {
+    const repositoryUrl = 'https://github.com/mwyraz/test-repo.git'
+    const resultPath = await cacheHelper.setupCache(mockGit, repositoryUrl)
+
+    const expectedName = (cacheHelper as any).generateCacheDirName(repositoryUrl)
+    expect(resultPath).toBe(path.join(cacheDir, expectedName))
+
+    // It should have executed git clone --bare
+    expect(mockGit.execGit).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        '-C',
+        cacheDir,
+        'clone',
+        '--bare',
+        repositoryUrl,
+        expect.stringContaining(`${expectedName}.tmp`) // should use tmp dir
+      ])
+    )
+  })
+
+  it('fetches updates if the cache directory already exists', async () => {
+    const repositoryUrl = 'https://github.com/mwyraz/existing-repo.git'
+    const expectedName = (cacheHelper as any).generateCacheDirName(repositoryUrl)
+    const fixedPath = path.join(cacheDir, expectedName)
+
+    // Fake existing directory
+    await io.mkdirP(path.join(fixedPath, 'objects'))
+
+    const resultPath = await cacheHelper.setupCache(mockGit, repositoryUrl)
+    expect(resultPath).toBe(fixedPath)
+
+    // It should have executed git fetch
+    expect(mockGit.execGit).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        '-C',
+        fixedPath,
+        'fetch',
+        '--force',
+        '--prune',
+        '--tags',
+        'origin',
+        '+refs/heads/*:refs/heads/*'
+      ])
+    )
+  })
+})

__test__/git-directory-helper.test.ts

@@ -478,8 +478,10 @@ async function setup(testName: string): Promise<void> {
     lfsFetch: jest.fn(),
     lfsInstall: jest.fn(),
     log1: jest.fn(),
+    referenceAdd: jest.fn(),
     remoteAdd: jest.fn(),
     removeEnvironmentVariable: jest.fn(),
+    execGit: jest.fn(),
     revParse: jest.fn(),
     setEnvironmentVariable: jest.fn(),
     shaExists: jest.fn(),

__test__/git-source-provider.test.ts

@@ -0,0 +1,88 @@
+import * as core from '@actions/core'
+import {adjustFetchDepthForCache} from '../src/git-source-provider'
+
+// Mock @actions/core
+jest.mock('@actions/core')
+
+describe('adjustFetchDepthForCache', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('does nothing when referenceCache is not set', () => {
+    const settings = {
+      referenceCache: '',
+      fetchDepth: 1,
+      fetchDepthExplicit: false
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(1)
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(core.info).not.toHaveBeenCalled()
+  })
+
+  it('overrides fetchDepth to 0 when referenceCache is set and fetchDepth is default', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 1,
+      fetchDepthExplicit: false
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(0)
+    expect(core.info).toHaveBeenCalledWith(
+      expect.stringContaining('Overriding fetch-depth from 1 to 0')
+    )
+    expect(core.warning).not.toHaveBeenCalled()
+  })
+
+  it('warns but keeps fetchDepth when referenceCache is set and fetchDepth is explicit', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 1,
+      fetchDepthExplicit: true
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(1)
+    expect(core.warning).toHaveBeenCalledWith(
+      expect.stringContaining("'fetch-depth: 1' is set with reference-cache enabled")
+    )
+    expect(core.info).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when referenceCache is set and fetchDepth is already 0 (explicit)', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 0,
+      fetchDepthExplicit: true
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(0)
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(core.info).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when referenceCache is set and fetchDepth is already 0 (default)', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 0,
+      fetchDepthExplicit: false
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(0)
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(core.info).not.toHaveBeenCalled()
+  })
+
+  it('warns with correct depth value when explicit fetchDepth is > 1', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 42,
+      fetchDepthExplicit: true
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(42)
+    expect(core.warning).toHaveBeenCalledWith(
+      expect.stringContaining("'fetch-depth: 42' is set with reference-cache enabled")
+    )
+  })
+})

__test__/input-helper.test.ts

@@ -91,6 +91,7 @@ describe('input-helper tests', () => {
     expect(settings.repositoryOwner).toBe('some-owner')
     expect(settings.repositoryPath).toBe(gitHubWorkspace)
     expect(settings.setSafeDirectory).toBe(true)
+    expect(settings.referenceCache || '').toBe('')
   })
 
   it('qualifies ref', async () => {

action.yml

@@ -98,6 +98,12 @@ inputs:
   github-server-url:
     description: The base URL for the GitHub instance that you are trying to clone from, will use environment defaults to fetch from the same instance that the workflow is running from unless specified. Example URLs are https://github.com or https://my-ghes-server.example.com
     required: false
+  reference-cache:
+    description: >
+      Path to a local directory used as a reference cache for Git clones. Over time,
+      this directory will contain bare clones of the checked-out repositories (and their submodules).
+      Using this significantly reduces network bandwidth and speeds up clones.
+    required: false
 outputs:
   ref:
     description: 'The branch, tag or SHA that was checked out'

adrs/2303-reference-cache.md

@@ -0,0 +1,37 @@
+# Reference Cache für schnelle Checkouts
+
+## Zusammenfassung
+Einführung eines lokal verwalteten Git-Referenz-Caches für Haupt-Repositories und Submodule, um Netzwerk-Traffic und Checkout-Zeiten auf persistenten Runnern (z.B. Self-Hosted) massiv zu reduzieren.
+
+## Implementierungsplan
+
+1. **Inputs:**
+   - In `action.yml` einen neuen Input `reference-cache` (Pfad zum Cache-Verzeichnis) hinzufügen. Default ist leer.
+   - In `src/git-source-settings.ts` und `src/input-helper.ts` den Input auslesen und bereitstellen (`settings.referenceCache`).
+
+2. **Cache Manager (`src/git-cache-helper.ts`):**
+   - Eine neue Klasse/Helper-Logik, die das Erstellen (`git clone --bare`) und Aktualisieren (`git fetch --force`) von Bare Cache-Repos übernimmt.
+   - **Namenskonvention Cache-Verzeichnis:** Damit Admin-Lesbarkeit und Kollisionsfreiheit gewährleistet sind, wird das Cache-Verzeichnis aus der Repository-URL gebildet:
+     - Alle Sonderzeichen in der URL durch `_` ersetzen.
+     - Ein kurzer Hash (z. B. erste 8 Zeichen des SHA256) der echten URL zur Eindeutigkeit anhängen.
+     - Beispiel: `<reference-cache>/https___github_com_actions_checkout_8f9b1c2a.git`
+
+3. **Haupt-Repo Checkout (`src/git-source-provider.ts`):**
+   - Vor dem Setup des Checkouts prüfen, ob `reference-cache` gesetzt ist.
+   - Wenn ja: den Cache-Ordner für die Haupt-URL aktualisieren/anlegen.
+   - Nach dem initialen `git.init()` den Pfad in `.git/objects/info/alternates` schreiben, der auf das `objects`-Verzeichnis des Cache-Ordners zeigt.
+
+4. **Submodule Checkouts (Iterativ statt monolithisch):**
+   - Der aktuelle Befehl `git submodule update --recursive` funktioniert nicht out-of-the-box mit `reference`, wenn jedes Submodul seinen individuellen Referenz-Cache benötigt.
+   - Wenn `reference-cache` aktiv ist und Submodule initialisiert werden sollen:
+     - Lese `.gitmodules` aus (alle Sub-URLs ermitteln).
+     - Für jedes Submodul den Cache (genauso wie in Step 2) anlegen oder aktualisieren.
+     - Submodul einzeln auschecken per `git submodule update --init --reference <cache-pfad/.git> <pfad>`.
+     - Bei der Einstellung `recursive`: In jedes Submodul-Verzeichnis wechseln und den Vorgang für `.gitmodules` rekursiv auf Skript-Ebene durchführen (anstatt Git's `--recursive` Flag einfach weiterzugeben).
+
+## Akzeptanzkriterien
+1. **Neue Option konfigurierbar**: Der Input `reference-cache` kann übergeben werden, der Code reagiert darauf.
+2. **Ordnerstruktur korrekt**: Der Cache-Ordner für das Hauptrepo und Submodule erhält Namen nach der "URL_Sonderzeichen_Ersetzt+SHA_Cut"-Logik.
+3. **Bandbreite gespart / Alternates genutzt**: Beim Hauptcheckout wird eine `.git/objects/info/alternates`-Datei mit Pfad zum lokalen Cache erzeugt. Danach ausgeführte `git fetch`-Befehle sind signifikant schneller bzw. laden deutlich weniger Bytes herunter.
+4. **Submodule erhalten Caches**: Auch tiefe (rekursive) Submodule profitieren für deren jeweilige Remote-URL vom Cache, da pro Submodul ein passender `--reference` Punkt dynamisch berechnet und übergeben wird.
+5. **Kein --dissociate**: Aus Performance-Gründen bleibt der Arbeitsordner an den Cache gebunden (`git repack` ist zeitaufwändig). Fällt der Cache weg, muss der Workspace erst einmal neu erzeugt werden (was bei Action Runnern die Norm ist, falls es nicht ohnehin "single-use" Runner sind).