Übersicht

git update-ref [-d] [--create-reflog] <ref> <newvalue> [<oldvalue>]

Beschreibung

Der git update-ref-Befehl schreibt einen neuen SHA atomar in eine Ref. Mit einem optionalen erwarteten Altwert bietet er Compare-and-Swap-Semantik für Sicherheit. Das ist es, was Porcelain-Befehle wie git commit und git branch unter der Haube verwenden, und was Skripte, die Refs direkt manipulieren, statt Dateien in .git/refs/ zu bearbeiten, verwenden sollten.

Im täglichen Einsatz integriert sich git update-ref eng mit Shell-Aliasen, Editor-Plugins und Continuous Integration. Power-User fügen oft Aliase hinzu, die Flags kombinieren, die sie immer übergeben, oder wickeln den Befehl in Skripte, die Teamkonventionen durchsetzen. Die Ausgabeformatierung kann über Git-Config angepasst werden — Pretty-Formate, Farbschemata und Pager-Verhalten sind alle einstellbar. Wenn etwas schiefgeht, ist der erste Diagnoseschritt üblicherweise, den Befehl erneut mit GIT_TRACE=1 in der Umgebung auszuführen, was die zugrunde liegenden Plumbing-Aufrufe offenlegt. Für ungewöhnliche Situationen öffnet die --help-Ausgabe (git update-ref --help) die vollständige Manpage mit Details zu jeder Option, einschließlich solcher, die in alltäglichen Workflows selten verwendet werden, aber für Debugging oder Skripting im großen Maßstab essentiell sind.

Zu verstehen, wie git update-ref mit dem Rest von Gits Datenmodell interagiert — der Objektdatenbank, dem Index, Refs und dem Working Tree — zahlt sich aus. Jeder Befehl operiert auf einer Teilmenge dieser Stücke, und zu wissen, welche er berührt, hilft Ergebnisse vorherzusagen und sich von Fehlern zu erholen. Das Lesen der offiziellen Git-Dokumentation neben praktischer Übung in einem Wegwerf-Repository ist der schnellste Weg, die Nuancen zu verinnerlichen. Die meisten Produktionsprobleme mit Git rühren von einer von drei Ursachen: überraschendem Standardverhalten, partiellen Netzwerkoperationen oder dem Umschreiben bereits geteilter Historie. Ein funktionierendes mentales Modell der Nebenwirkungen von git update-ref hilft, alle drei zu vermeiden.

Häufige Optionen

Option	Beschreibung
-d <ref> [<oldvalue>]	Löscht eine Ref (optional Compare-and-Swap).
--no-deref	Folgt nicht symbolischen Refs.
--create-reflog	Erstellt ein Reflog, falls fehlend.
-m <reason>	Reflog-Grund für dieses Update.
--stdin	Liest Updates von stdin (atomarer Batch).

Beispiele

git update-ref refs/heads/feature abc123
    # feature-Branch auf Commit abc123 bewegen

    git update-ref -d refs/heads/old-experiment
    # Eine Branch-Ref direkt löschen

    git update-ref refs/notes/ci HEAD def456
    # Eine eigene Notes-Ref atomar bewegen

    # Atomares Multi-Ref-Update via stdin:
    printf 'update refs/heads/main %s\nupdate refs/heads/dev %s\n' "$NEW1" "$NEW2" | \
      git update-ref --stdin

Häufige Fehler

Sicherheit zu umgehen, indem Sie .git/refs/-Dateien direkt bearbeiten, kann Packed Refs korrumpieren oder Reflog-Einträge überspringen. Verwenden Sie immer update-ref. Das Vergessen, <oldvalue> zu liefern, vereitelt den Compare-and-Swap-Schutz — liefern Sie ihn, wann immer möglich.

Verwandte Befehle

git symbolic-ref, git pack-refs, git for-each-ref, git branch