git-update-index - Registriert Datei-Inhalte im Arbeitsverzeichnis im Index

Modifiziert den Index. Jede erwähnte Datei wird im Index aktualisiert und jeder Zustand "unmerged" oder "needs updating" wird gelöscht.

Siehe auch git-add[1] für eine benutzerfreundlichere Methode, einige der häufigsten Operationen auf dem Index durchzuführen.

Die Art und Weise, wie git update-index Dateien behandelt, über die es informiert wird, kann mit den verschiedenen Optionen modifiziert werden

--refresh berechnet kein neues sha1-File und aktualisiert den Index nicht auf den neuesten Stand für Modus-/Inhaltsänderungen. Was es jedoch tut, ist, die stat-Informationen einer Datei mit dem Index zu "neu abzugleichen", damit Sie den Index für eine Datei auffrischen können, die nicht geändert wurde, bei der aber der stat-Eintrag veraltet ist.

Zum Beispiel würden Sie dies nach einem git read-tree tun wollen, um die stat-Indexdetails mit den richtigen Dateien zu verknüpfen.

--cacheinfo wird verwendet, um eine Datei zu registrieren, die sich nicht im aktuellen Arbeitsverzeichnis befindet. Dies ist nützlich für Minimum-Checkout-Merges.

Um vorzutäuschen, dass Sie eine Datei unter dem Pfad mit Modus und sha1 haben, sagen Sie

--info-only wird verwendet, um Dateien zu registrieren, ohne sie in die Objekt-Datenbank zu legen. Dies ist nützlich für reine Status-Repositories.

Beide Befehle, --cacheinfo und --info-only, verhalten sich ähnlich: Der Index wird aktualisiert, aber die Objekt-Datenbank nicht. --cacheinfo ist nützlich, wenn das Objekt in der Datenbank ist, die Datei aber lokal nicht verfügbar ist. --info-only ist nützlich, wenn die Datei verfügbar ist, Sie aber die Objekt-Datenbank nicht aktualisieren möchten.

--index-info ist ein leistungsfähigerer Mechanismus, der es Ihnen ermöglicht, mehrere Eintragsdefinitionen von der Standardeingabe zu verarbeiten und ist speziell für Skripte konzipiert. Er kann Eingaben in drei Formaten annehmen:

Um einen Eintrag höherer Stufe in den Index einzufügen, sollte der Pfad zunächst durch Übergabe eines Eintrags mit mode=0 für den Pfad entfernt und dann die notwendigen Eingabezeilen im dritten Format übergeben werden.

Beispiel: Beginnen Sie mit diesem Index

Sie können die folgende Eingabe an --index-info übergeben

Die erste Zeile der Eingabe übergibt 0 als Modus, um den Pfad zu entfernen; der SHA-1 spielt keine Rolle, solange er korrekt formatiert ist. Dann übergeben die zweite und dritte Zeile die Einträge für Stage 1 und Stage 2 für diesen Pfad. Danach hätten wir folgendes Ergebnis:

Viele Operationen in Git hängen von einer effizienten lstat(2) Implementierung Ihres Dateisystems ab, sodass die st_mtime-Informationen für Arbeitsverzeichnisdateien kostengünstig geprüft werden können, um festzustellen, ob sich der Dateiinhalt von der im Index gespeicherten Version geändert hat. Leider haben einige Dateisysteme ineffiziente lstat(2)-Aufrufe. Wenn Ihr Dateisystem eines davon ist, können Sie das "assume unchanged"-Bit für Pfade setzen, die Sie nicht geändert haben, damit Git diese Prüfung nicht durchführt. Beachten Sie, dass das Setzen dieses Bits für einen Pfad nicht bedeutet, dass Git den Dateiinhalt auf Änderungen prüft – es bewirkt, dass Git jegliche Prüfung weglässt und davon ausgeht, dass er sich **nicht** geändert hat. Wenn Sie Änderungen an Arbeitsverzeichnisdateien vornehmen, müssen Sie Git dies explizit mitteilen, indem Sie das "assume unchanged"-Bit fallen lassen, entweder bevor oder nachdem Sie sie ändern.

Um das "assume unchanged"-Bit zu setzen, verwenden Sie die Option --assume-unchanged. Zum Löschen verwenden Sie --no-assume-unchanged. Um zu sehen, welche Dateien das "assume unchanged"-Bit gesetzt haben, verwenden Sie git ls-files -v (siehe git-ls-files[1]).

Der Befehl betrachtet die Konfigurationsvariable core.ignorestat. Wenn diese wahr ist, werden Pfade, die mit git update-index paths... aktualisiert wurden, und Pfade, die mit anderen Git-Befehlen aktualisiert wurden, die sowohl den Index als auch das Arbeitsverzeichnis aktualisieren (z.B. git apply --index, git checkout-index -u und git read-tree -u), automatisch als "assume unchanged" markiert. Beachten Sie, dass das "assume unchanged"-Bit **nicht** gesetzt wird, wenn git update-index --refresh feststellt, dass die Arbeitsverzeichnisdatei mit dem Index übereinstimmt (verwenden Sie git update-index --really-refresh, wenn Sie sie als "assume unchanged" markieren möchten).

Manchmal verwechseln Benutzer das "assume-unchanged"-Bit mit dem "skip-worktree"-Bit. Siehe den letzten Absatz im Abschnitt "Skip-worktree bit" unten für eine Erklärung der Unterschiede.

Um nur die bereits ausgecheckten Dateien zu aktualisieren und aufzufrischen

Das Skip-Worktree-Bit kann in einem (langen) Satz definiert werden: Sagt Git, dass die Datei nach Möglichkeit nicht in das Arbeitsverzeichnis geschrieben werden soll und die Datei als unverändert behandelt werden soll, wenn sie nicht im Arbeitsverzeichnis vorhanden ist.

Beachten Sie, dass nicht alle Git-Befehle auf dieses Bit achten und einige es nur teilweise unterstützen.

Die Flags von update-index und die Fähigkeiten von read-tree im Zusammenhang mit dem skip-worktree-Bit entstanden vor der Einführung des Befehls git-sparse-checkout[1], der eine viel einfachere Möglichkeit bietet, die skip-worktree-Bits zu konfigurieren und zu handhaben. Wenn Sie Ihr Arbeitsverzeichnis auf eine Teilmenge der Dateien im Repository reduzieren möchten, empfehlen wir dringend die Verwendung von git-sparse-checkout[1] anstelle der Low-Level-Primitive update-index und read-tree.

Der Hauptzweck des skip-worktree-Bits ist die Ermöglichung von Sparse-Checkouts, d.h. Arbeitsverzeichnissen mit nur einer Teilmenge von vorhandenen Pfaden. Wenn das skip-worktree-Bit gesetzt ist, vermeiden Git-Befehle (wie z.B. switch, pull, merge) das Schreiben dieser Dateien. Diese Befehle schreiben diese Dateien jedoch manchmal trotzdem in wichtigen Fällen, wie z.B. bei Konflikten während eines Merges oder Rebases. Git-Befehle werden auch vermeiden, das Fehlen solcher Dateien als absichtliche Löschung zu behandeln; zum Beispiel wird git add -u keine Löschung für diese Dateien staged und git commit -a wird diese ebenfalls nicht löschen.

Obwohl dieses Bit dem "assume-unchanged"-Bit ähnelt, ist sein Ziel anders. Das "assume-unchanged"-Bit dient dazu, die Datei im Arbeitsverzeichnis zu belassen, aber Git anzuweisen, sie nicht auf Änderungen zu prüfen und davon auszugehen, dass die Datei nicht geändert wurde (obwohl, wenn es feststellen kann, ohne die Datei zu statten, dass sie geändert wurde, es die Änderungen aufzeichnen darf). skip-worktree weist Git an, das Fehlen der Datei zu ignorieren, sie bei Befehlen, die normalerweise einen Großteil des Arbeitsverzeichnisses aktualisieren (z.B. checkout, switch, pull usw.), nach Möglichkeit nicht zu aktualisieren und ihr Fehlen nicht in Commits aufzuzeichnen. Beachten Sie, dass in Sparse-Checkouts (eingerichtet durch git sparse-checkout oder durch Konfiguration von core.sparseCheckout auf true), wenn eine Datei im Index als skip-worktree markiert ist, aber im Arbeitsverzeichnis gefunden wird, Git das skip-worktree-Bit für diese Datei löscht.

Dieser Modus ist für Repositories mit sehr großen Indizes konzipiert und zielt darauf ab, die Zeit zu reduzieren, die zum wiederholten Schreiben dieser Indizes benötigt wird.

In diesem Modus ist der Index in zwei Dateien aufgeteilt: $GIT_DIR/index und $GIT_DIR/sharedindex.<SHA-1>. Änderungen werden in $GIT_DIR/index, dem Split-Index, gesammelt, während die gemeinsame Indexdatei alle Indexeinträge enthält und unverändert bleibt.

Alle Änderungen im Split-Index werden zurück in die gemeinsame Indexdatei geschrieben, wenn die Anzahl der Einträge im Split-Index ein Niveau erreicht, das durch die Konfigurationsvariable splitIndex.maxPercentChange festgelegt ist (siehe git-config[1]).

Jedes Mal, wenn eine neue gemeinsame Indexdatei erstellt wird, werden die alten gemeinsamen Indexdateien gelöscht, wenn ihre Änderungszeit älter ist als die, die durch die Konfigurationsvariable splitIndex.sharedIndexExpire angegeben ist (siehe git-config[1]).

Um eine gemeinsame Indexdatei, die noch verwendet wird, nicht zu löschen, wird ihre Änderungszeit bei jeder Erstellung oder jedem Lesen eines neuen Split-Indexes, der auf der gemeinsamen Indexdatei basiert, auf die aktuelle Zeit aktualisiert.

Dieser Cache soll die Geschwindigkeit von Befehlen erhöhen, die sich mit der Ermittlung von nicht nachverfolgten Dateien befassen, wie z.B. git status.

Diese Funktion funktioniert, indem sie die mtime der Verzeichnisse des Arbeitsverzeichnisses speichert und dann das Lesen von Verzeichnissen und stat-Aufrufe gegen Dateien in diesen Verzeichnissen auslässt, deren mtime sich nicht geändert hat. Damit dies funktioniert, müssen das zugrunde liegende Betriebssystem und das Dateisystem das Feld st_mtime von Verzeichnissen ändern, wenn Dateien in dem Verzeichnis hinzugefügt, geändert oder gelöscht werden.

Sie können testen, ob das Dateisystem dies unterstützt, mit der Option --test-untracked-cache. Die Option --untracked-cache führte in älteren Git-Versionen implizit diesen Test durch, aber das ist nicht mehr der Fall.

Wenn Sie diese Funktion aktivieren (oder deaktivieren) möchten, ist es einfacher, die Konfigurationsvariable core.untrackedCache (siehe git-config[1]) zu verwenden, als die Option --untracked-cache für git update-index in jedem Repository, insbesondere wenn Sie dies in allen von Ihnen verwendeten Repositories tun möchten, da Sie die Konfigurationsvariable einmalig in Ihrer $HOME/.gitconfig auf true (oder false) setzen können und dies alle von Ihnen bearbeiteten Repositories betrifft.

Wenn die Konfigurationsvariable core.untrackedCache geändert wird, wird der Untracked-Cache zum Index hinzugefügt oder daraus entfernt, wenn das nächste Mal ein Befehl den Index liest; während bei Verwendung von --[no-|force-]untracked-cache der Untracked-Cache sofort zum Index hinzugefügt oder daraus entfernt wird.

Vor 2.17 hatte der Untracked-Cache einen Fehler, bei dem das Ersetzen eines Verzeichnisses durch einen Symlink zu einem anderen Verzeichnis dazu führen konnte, dass von Git nachverfolgte Dateien fälschlicherweise als nicht nachverfolgt angezeigt wurden. Siehe den Commit "status: add a failing test showing a core.untrackedCache bug" in git.git. Eine Abhilfe dafür ist (und dies funktioniert möglicherweise auch für andere unentdeckte Fehler in der Zukunft)

Dieser Fehler hat auch Nicht-Symlink-Fälle des Ersetzens eines Verzeichnisses durch eine Datei in Bezug auf die internen Strukturen des Untracked-Cache betroffen, aber es wurde kein Fall gemeldet, bei dem dies zu falschen "git status"-Ausgaben geführt hätte.

Es gibt auch Fälle, in denen bestehende Indizes, die von Git-Versionen vor 2.17 geschrieben wurden, auf Verzeichnisse verweisen, die nicht mehr existieren, was potenziell zu vielen Warnungen "could not open directory" bei "git status" führen kann. Dies sind neue Warnungen für bestehende Probleme, die zuvor stillschweigend verworfen wurden.

Wie bei dem oben beschriebenen Fehler ist die Lösung, einmalig einen "git status"-Lauf mit core.untrackedCache=false durchzuführen, um die verbleibenden fehlerhaften Daten zu bereinigen.

Diese Funktion soll die Geschwindigkeit von Git-Operationen für Repositories mit großen Arbeitsverzeichnissen verbessern.

Sie ermöglicht Git die Zusammenarbeit mit einem Dateisystem-Monitor (siehe git-fsmonitor--daemon[1] und den Abschnitt "fsmonitor-watchman" in githooks[5]), der es ihm mitteilen kann, welche Dateien geändert wurden. Dies ermöglicht Git, das lstat()-en jeder Datei zur Suche nach geänderten Dateien zu vermeiden.

In Verbindung mit dem Untracked-Cache kann die Leistung weiter verbessert werden, indem die Kosten für das Scannen des gesamten Arbeitsverzeichnisses nach neuen Dateien vermieden werden.

Wenn Sie diese Funktion aktivieren (oder deaktivieren) möchten, ist es einfacher, die Konfigurationsvariable core.fsmonitor (siehe git-config[1]) zu verwenden, als die Option --fsmonitor für git update-index in jedem Repository, insbesondere wenn Sie dies in allen von Ihnen verwendeten Repositories tun möchten, da Sie die Konfigurationsvariable einmalig in Ihrer $HOME/.gitconfig setzen können und dies alle von Ihnen bearbeiteten Repositories betrifft.

Wenn die Konfigurationsvariable core.fsmonitor geändert wird, wird der Dateisystem-Monitor zum Index hinzugefügt oder daraus entfernt, wenn das nächste Mal ein Befehl den Index liest. Wenn --[no-]fsmonitor verwendet werden, wird der Dateisystem-Monitor sofort zum Index hinzugefügt oder daraus entfernt.

Der Befehl berücksichtigt die Konfigurationsvariable core.filemode. Wenn Ihr Repository auf einem Dateisystem liegt, dessen ausführbare Bits unzuverlässig sind, sollte dies auf false gesetzt werden (siehe git-config[1]). Dies bewirkt, dass der Befehl Unterschiede in den im Index gespeicherten Dateimodien und den Dateimodien auf dem Dateisystem ignoriert, wenn sie sich nur auf das ausführbare Bit unterscheiden. Auf einem solchen unglücklichen Dateisystem müssen Sie möglicherweise git update-index --chmod= verwenden.

Ebenso, wenn die Konfigurationsvariable core.symlinks auf false gesetzt ist (siehe git-config[1]), werden symbolische Links als normale Dateien ausgecheckt, und dieser Befehl ändert den aufgezeichneten Dateimodus nicht von einem symbolischen Link zu einer regulären Datei.

Der Befehl berücksichtigt die Konfigurationsvariable core.ignorestat. Siehe den Abschnitt "Using "assume unchanged" bit" oben.

Der Befehl berücksichtigt auch die Konfigurationsvariable core.trustctime. Dies kann nützlich sein, wenn die Inode-Änderungszeit regelmäßig von etwas außerhalb von Git modifiziert wird (Dateisystem-Crawler und Backup-Systeme verwenden ctime, um verarbeitete Dateien zu markieren) (siehe git-config[1]).

Die Untracked-Cache-Erweiterung kann durch die Konfigurationsvariable core.untrackedCache aktiviert werden (siehe git-config[1]).

Benutzer versuchen oft, die Bits "assume-unchanged" und "skip-worktree" zu verwenden, um Git mitzuteilen, dass Änderungen an Dateien ignoriert werden sollen, die nachverfolgt werden. Dies funktioniert nicht wie erwartet, da Git beim Ausführen bestimmter Operationen immer noch Arbeitsverzeichnisdateien mit dem Index vergleichen kann. Im Allgemeinen bietet Git keine Möglichkeit, Änderungen an nachverfolgten Dateien zu ignorieren, daher werden alternative Lösungen empfohlen.

Wenn beispielsweise die zu ändernde Datei eine Art Konfigurationsdatei ist, kann das Repository eine Beispielkonfigurationsdatei enthalten, die dann in den ignorierten Namen kopiert und geändert werden kann. Das Repository kann sogar ein Skript enthalten, um die Beispieldatei als Vorlage zu behandeln, sie automatisch zu modifizieren und zu kopieren.

git-config[1], git-add[1], git-ls-files[1]

Teil der git[1] Suite