Feature/git cache

[b4u-mw]

Full implementation of a reference cache. Works for main git and submodules (recursive). Cache is automatically created/updated.
Fixes #2303

[Copilot]

Pull request overview

This PR implements a reference cache feature for the actions/checkout GitHub Action, addressing issue #2303. The reference cache allows storing bare clones of repositories locally, so subsequent checkouts can use Git alternates to avoid re-downloading objects over the network. This is particularly valuable for self-hosted runners and custom runner images with persistent storage.

Changes:

• Adds a new reference-cache input parameter that accepts a path to a local directory for storing bare cache repositories, with associated settings, input parsing, and documentation.
• Introduces GitCacheHelper class (src/git-cache-helper.ts) that manages bare cache repositories with file-based locking (via proper-lockfile), atomic clone-to-rename patterns, and automatic cache creation/update.
• Modifies the checkout flow in git-source-provider.ts to set up Git alternates for the main repository and iteratively process submodule updates with per-submodule reference caches, including automatic fetch-depth adjustment when reference cache is active.

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
action.yml	Adds new reference-cache input parameter
src/git-source-settings.ts	Adds referenceCache and fetchDepthExplicit fields to settings interface
src/input-helper.ts	Reads reference-cache input and tracks explicit fetch-depth
src/git-cache-helper.ts	New file: cache management with locking, bare clone/fetch, and URL-based dir naming
src/git-source-provider.ts	Integrates reference cache into clone and submodule flows; adds adjustFetchDepthForCache
src/git-command-manager.ts	Makes execGit/GitOutput public; adds referenceAdd for Git alternates
src/git-auth-helper.ts	Adds removeGlobalAuth method for cache auth lifecycle
package.json / package-lock.json	Adds proper-lockfile dependency and types
adrs/2303-reference-cache.md	ADR documenting the design and acceptance criteria
README.md	Documents the new reference-cache input
__test__/git-source-provider.test.ts	Tests for adjustFetchDepthForCache
__test__/git-cache-helper.test.ts	Tests for cache dir naming and setup behavior
__test__/git-directory-helper.test.ts	Updates mock to include new interface methods
__test__/git-auth-helper.test.ts	Updates mock and settings for new fields
__test__/input-helper.test.ts	Asserts referenceCache defaults to empty
dist/index.js	Bundled output including new code and proper-lockfile

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Golubhatt]

something missing check

[BastirEiii]

algo más directo y con codigos de respeto celestial dame el último más directo de los chekaut Obtener Outlook para Android<https://aka.ms/AAb9ysg>

________________________________ From: b4u-mw ***@***.***> Sent: Tuesday, March 10, 2026 3:37:37 AM To: actions/checkout ***@***.***> Cc: Subscribed ***@***.***> Subject: Re: [actions/checkout] Feature/git cache (PR #2384) @b4u-mw commented on this pull request.

________________________________ In adrs/2303-reference-cache.md<#2384 (comment)>:

+# 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). Valid point. That was still my initial blueprint for the implementation. Replaced by a reworked version. — Reply to this email directly, view it on GitHub<#2384 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BEPQODX2G7ZEAHZUYZZB7GT4P6Z3DAVCNFSM6AAAAACWIL2ZVOVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTSMRQGEYTEMBVGM>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[b4u-mw]

algo más directo y con codigos de respeto celestial dame el último más directo de los chekaut

Sorry, that version of the ADR was not meant to be checked in. I already have added the final, translated version

[b4u-mw]

something missing check

@Golubhatt I'm sorry but I do not understand your comments. I can run all tests locally without issues. Could you please be more precise what is missing or failing?

[tvishwanatharkin]

Is this PR moving ahead? This is a very good feature IMHO which can reduce the load on Github.

[quic-seaswara]

Looking forward for getting this merged

[b4u-mw]

I wonder if there's anything to do from my side. Seems that it's approved. There are a few open comments where I cannot read anything to do from (marking those as resolved).
So please merge if there's nothing missing.