Layer 8Ehrlicher Tech-Support
SoftwareSchweregrad: Lästig

git sparse-checkout: Ordner verschwinden nach set

Nach git sparse-checkout set fehlen plötzlich andere Ordner, git status schweigt. set ersetzt die Auswahl, add ergänzt sie; alles wie dokumentiert.

Aufwand:
ca. 10 Min.
Voraussetzung:
Ein Terminal mit git 2.55 oder neuer, Ein Repository mit mehreren Unterprojekten (Monorepo), Die Ausgabe von git sparse-checkout list
Gilt für:
Git 2.55.0 (Dokumentation von git-sparse-checkout und git-clone auf git-scm.com, Stand 17.10.2026); das Kommando ist laut Dokumentation als experimentell gekennzeichnet

Das Symptom

In einem Monorepo hat jemand den Sparse-Checkout entdeckt: git sparse-checkout set src/app, und der Arbeitsbaum ist angenehm klein. Eine Woche später braucht er zusätzlich src/lib, tippt git sparse-checkout set src/lib, und src/app ist weg. git status meldet nichts. Kein Fehler, keine Warnung, keine als gelöscht markierten Dateien. Der Editor zeigt offene Dateien, die es auf der Platte nicht mehr gibt, und der Build scheitert an fehlenden Importen.

Der erste Verdacht fällt auf ein kaputtes Repository, der zweite auf einen Kollegen, der etwas gelöscht hat. Beides falsch.

Die „Layer 8“-Wahrheit

set und add sind keine Synonyme. Die Dokumentation von git sparse-checkout beschreibt set als Befehl, der die Konfiguration aktiviert und dann die Sparse-Checkout-Datei aus den Argumenten füllt, „and update the working directory to match.“ Die Argumente sind die neue Auswahl, vollständig. Für das Ergänzen gibt es add, das die Datei um weitere Verzeichnisse erweitert. Wer set mit einem einzelnen Ordner aufruft, hat genau diesen einen Ordner bestellt, und Git liefert genau das.

Dass git status schweigt, ist ebenfalls dokumentiert. Ein Sparse-Checkout verändert den Arbeitsbaum „from having all tracked files present to only having a subset of those files“, und die übrigen Befehle wissen das: Beim Zweigwechsel werden Pfade außerhalb der Auswahl nicht angefasst, und „git commit -a will not record paths outside the sparse-checkout directories/patterns as deleted.“ Die Dateien sind nicht gelöscht, sie sind nur nicht ausgecheckt. Die Objekte liegen weiter im Repository, und disable bringt den vollständigen Arbeitsbaum zurück.

Der Kegelmodus erklärt eine zweite Verwunderung: Warum liegen Dateien im Wurzelverzeichnis und in den Elternordnern, die niemand angefordert hat? Weil der Kegel so definiert ist. Für ein angegebenes Verzeichnis sind alle Pfade darunter enthalten, dazu alle Dateien unmittelbar in den führenden Verzeichnissen bis hinauf zur Wurzel. „Also, in cone mode, even if no directories are specified, then the files in the toplevel directory will be included.“ Das ist kein Leck in der Auswahl, sondern die Garantie, dass Build-Skripte und Konfiguration an der Wurzel immer da sind.

Zwei Warnungen aus derselben Seite gehören dazu. Erstens trägt das Kommando die Kennzeichnung als experimentell, in Großbuchstaben; sein Verhalten und das anderer Befehle in Sparse-Checkouts kann sich ändern. Zweitens ist der Mustermodus abgekündigt: „For all these reasons, non-cone mode is deprecated. Please switch to using cone mode.“ Anleitungen, die Muster im Stil von .gitignore in die Sparse-Checkout-Datei schreiben, beschreiben einen Zustand, von dem die Dokumentation heute abrät.

Und ein Detail für den Alltag: Nach einem Merge oder Rebase können laut Dokumentation Pfade außerhalb der Auswahl im Arbeitsbaum auftauchen, weil Git sie zum Anzeigen von Konflikten braucht. Auch das ist kein Zurücksetzen der Auswahl; reapply wendet die Regeln neu an. Wer das Werkzeug mit den vier Unterbefehlen list, add, set und disable bedient, hat keinen Grund mehr, nach verschwundenen Dateien zu suchen. Sie liegen genau dort, wo Git sie laut list ablegen soll.

Die echte, verifizierte Lösung

1000 % faktenbasiert. Jeder Befehl ist real, jeder Pfad existiert. Schritt für Schritt:

  1. 1.

    Aktuelle Auswahl anzeigen

    git sparse-checkout list beschreibt laut Dokumentation die Verzeichnisse oder Muster der Sparse-Checkout-Datei. Das ist die Wahrheit darüber, was im Arbeitsbaum liegen soll; ein fehlender Ordner, der hier nicht aufgeführt ist, fehlt nicht aus Versehen. Die Konfiguration ist seit dem Unterbefehl set je Arbeitsbaum (worktree) gespeichert, Änderungen in einem Worktree berühren andere also nicht.

    git sparse-checkout list
  2. 2.

    Ordner ergänzen statt ersetzen

    add nimmt zusätzliche Verzeichnisse in die Auswahl auf und lässt die vorhandenen stehen. set dagegen setzt die Auswahl auf genau die angegebenen Argumente und passt den Arbeitsbaum an; alles, was nicht genannt ist, verschwindet aus dem Arbeitsbaum. Wer die gesamte Auswahl neu festlegen will, nennt bei set alle gewünschten Verzeichnisse auf einmal.

    git sparse-checkout add src/lib
git sparse-checkout set src/app src/lib
  3. 3.

    Alles zurückholen

    disable schaltet laut Dokumentation core.sparseCheckout ab und stellt den Arbeitsbaum mit allen Dateien wieder her. Das ist der richtige Befehl, wenn der Sparse-Checkout nur zum Ausprobieren diente oder jemand den Überblick verloren hat. Bei einem großen Monorepo kann das dauern und Platz kosten; das ist der Preis, den der Sparse-Checkout vorher gespart hat.

    git sparse-checkout disable
  4. 4.

    Nach Merge oder Rebase aufräumen

    Befehle wie merge oder rebase können laut Dokumentation Pfade außerhalb der Auswahl materialisieren, etwa um einen Konflikt zu zeigen, und einzelne Dateien lassen sich wegen ungesicherter Änderungen nicht wieder ausblenden. reapply wendet die Regeln erneut auf den Arbeitsbaum an. Erscheinen nach einem Merge also wieder fremde Ordner, ist das kein Zurücksetzen der Auswahl, sondern Material, das reapply wieder einsammelt.

    git sparse-checkout reapply
  5. 5.

    Von Anfang an sparsam klonen

    git clone --sparse legt laut Dokumentation einen Sparse-Checkout an, bei dem zunächst nur die Dateien des Wurzelverzeichnisses vorhanden sind; der Arbeitsbaum wird danach mit git sparse-checkout nach Bedarf erweitert. In Verbindung mit --filter=blob:none werden außerdem Dateiinhalte erst bei Bedarf vom Server geholt, was bei großen Repositorys den ersten Klon erheblich verkürzt. Wichtig bleibt auch hier: Verzeichnisse mit add ergänzen.

    git clone --sparse --filter=blob:none <adresse> monorepo
cd monorepo
git sparse-checkout add src/app

Häufige Fragen (FAQ)

?Ich habe einen zweiten Ordner mit set hinzugefügt, jetzt ist der erste weg. Warum?

Weil set die Auswahl nicht ergänzt, sondern neu schreibt. Die Dokumentation beschreibt den Unterbefehl so: Er aktiviert die nötigen Konfigurationswerte, „populate the sparse-checkout file from the list of arguments following the set subcommand, and update the working directory to match.“ Die Liste der Argumente ist die neue vollständige Auswahl. Zum Ergänzen gibt es add: „Update the sparse-checkout file to include additional directories (in cone mode) or patterns (in non-cone mode).“ Wer also src/app hat und src/lib dazu will, schreibt add src/lib, nicht set src/lib; sonst bleibt nur src/lib übrig.

?Sind die verschwundenen Dateien gelöscht?

Nein, sie sind nur nicht im Arbeitsbaum. Ein Sparse-Checkout ändert laut Dokumentation den Arbeitsbaum „from having all tracked files present to only having a subset of those files“; die Objekte bleiben im Repository. Die Dokumentation sagt auch, warum git status nichts meldet: In einem Sparse-Checkout verhalten sich andere Befehle anders, zum Beispiel wird „git commit -a will not record paths outside the sparse-checkout directories/patterns as deleted.“ Mit git sparse-checkout disable kommen alle Dateien zurück: Der Befehl schaltet core.sparseCheckout ab und stellt den Arbeitsbaum mit allen Dateien wieder her.

?Warum liegen trotz Auswahl eines Unterordners Dateien im Wurzelverzeichnis und in den Elternordnern?

Das ist der Kegelmodus (cone mode), die Voreinstellung. Die Dokumentation erklärt am Beispiel Documentation/technical/, dass der Checkout dann enthält: alle Dateien im Wurzelverzeichnis, alle Dateien direkt unter Documentation/ und alle Dateien in beliebiger Tiefe unter Documentation/technical/. Und weiter: „Also, in cone mode, even if no directories are specified, then the files in the toplevel directory will be included.“ Das ist gewollt, damit Build-Dateien, README und Konfiguration im Wurzelverzeichnis immer vorhanden sind.

?Soll ich lieber Muster mit --no-cone verwenden, wie es ältere Anleitungen zeigen?

Nein. Die Dokumentation rät ausdrücklich ab: Der Mustermodus hat eine Reihe von Nachteilen, funktioniert nicht mit Optionen wie --sparse-index, und im Abschnitt zu den Problemen des Nicht-Kegel-Modus heißt es: „For all these reasons, non-cone mode is deprecated. Please switch to using cone mode.“ Ältere Anleitungen stammen aus der Zeit, als der Kegelmodus noch mit --cone eingeschaltet werden musste; die Dokumentation vermerkt, dass das früher nicht die Voreinstellung war. Heute reicht eine Liste von Verzeichnissen.

Belege

Diese Seite ist gegen die folgenden Primärquellen geprüft – Hersteller, Standard oder Gesetzestext. Wer es nicht glaubt, muss es nicht: Da steht, wo es nachzulesen ist.

  1. [1]
    git-sparse-checkout Documentation, Abschnitte DESCRIPTION, COMMANDS (list, set, add, reapply, disable) und INTERNALS — CONE MODE HANDLING, INTERNALS — NON-CONE PROBLEMS (Git 2.55.0, git-scm.com, abgerufen 17.10.2026)

    git-scm.com · abgerufen am

  2. [2]
    git-clone Documentation, Optionen --sparse und --filter=<filter-spec> (Git 2.54.0, git-scm.com, abgerufen 17.10.2026)

    git-scm.com · abgerufen am

Zuletzt geprüft am . Dokumentation altert – ein Datum daneben ist der einzige ehrliche Umgang damit.

Auch zu finden unter

Verwandte Fehler

SWLästigNot possible to fast-forward, aborting.

git pull: Not possible to fast-forward, aborting

git pull bricht ab, sobald eigener und entfernter Zweig auseinandergelaufen sind. Laut Git 2.55 ist --ff-only die Voreinstellung, nicht der Merge.

SWLästigdetached HEAD

Git: detached HEAD state

Git meldet „detached HEAD“? Du stehst nicht auf einem Branch, sondern direkt auf einem Commit — Änderungen hier gehen ohne Gegenmaßnahme leicht verloren.