Einführung

Eine symbolische Ref ist eine Referenz, deren Wert ein anderer Ref-Name statt eines Objekt-Hashes ist. Das kanonische Beispiel ist HEAD, das üblicherweise ref: refs/heads/main enthält. Symbolische Refs erlauben Git, "den aktuellen Branch" als Daten statt als Zustand zu verfolgen.

Lesen und Schreiben

git symbolic-ref HEAD
# refs/heads/main

git symbolic-ref refs/remotes/origin/HEAD
# refs/remotes/origin/main

git symbolic-ref HEAD refs/heads/feature/login   # ohne Checkout ändern
git symbolic-ref --short HEAD                      # Kurzform: main
git symbolic-ref --delete refs/remotes/origin/HEAD

HEAD als symbolische Ref

Wenn Sie committen, löst Git HEAD auf, um den aktuellen Branch zu finden, und aktualisiert die Spitze jenes Branches. Wenn HEAD detached ist, hört es auf, symbolisch zu sein, und enthält einen rohen SHA.

cat .git/HEAD
# ref: refs/heads/main         (symbolisch)
# vs. nach Detach:
# a1b2c3d4...                  (roh)

Remote HEAD

Jeder Remote kann ein symbolisches HEAD haben, das seinen Standard-Branch angibt. Setzen oder erneuern:

git remote set-head origin --auto       # Server abfragen
git remote set-head origin main         # explizit setzen
git remote set-head origin --delete

Das ist es, was git log origin zu origin/main auflöst.

Wofür sie nützlich sind

• "Aktueller Branch" kann sich ändern, ohne die Historie umzuschreiben.
• Tools können fragen "was ist der Standard?", ohne Namen hardzucodieren.
• Hooks können generisch auf den aktuell ausgecheckten Branch zielen.

Worktrees und Per-Worktree-HEAD

Jeder verlinkte Worktree (git worktree add) hat sein eigenes HEAD, gespeichert unter .git/worktrees/<name>/HEAD. Jedes kann auf einen anderen Branch zeigen:

git worktree add ../wt-feature feature/login
cat ../wt-feature/.git
# gitdir: /path/to/main/.git/worktrees/wt-feature
cat .git/worktrees/wt-feature/HEAD
# ref: refs/heads/feature/login

Erkennung

git symbolic-ref -q HEAD && echo "on a branch" || echo "detached"

Den Standard umbenennen

Um master sicher in main umzubenennen:

git branch -m master main
git symbolic-ref HEAD refs/heads/main
git push -u origin main
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

Symbolische Auflösung inspizieren

git rev-parse löst einen Namen über symbolische Refs ganz bis zu einem SHA auf, während git symbolic-ref nur einer Ebene folgt. Das Paar ist nützlich für Skripte:

git symbolic-ref HEAD                       # refs/heads/main
git symbolic-ref --short HEAD               # main
git rev-parse HEAD                          # SHA
git rev-parse --symbolic-full-name HEAD     # refs/heads/main
git rev-parse --symbolic-full-name @{u}     # refs/remotes/origin/main

Verwenden Sie --symbolic-full-name, wenn Sie den kanonischen Ref-Namen wollen, egal welche Kurzform der Nutzer eintippte.

Häufige Fehler

.git/HEAD manuell editieren und das abschließende Newline vergessen, sodass Git es nicht mehr parsen kann. Verwenden Sie git symbolic-ref. refs/remotes/origin/HEAD als maßgeblich behandeln, obwohl es tatsächlich gecached ist; aktualisieren mit git remote set-head origin --auto. Eine symbolische Ref, die auf einen fehlenden Branch zeigt, mit einem echten Fehler verwechseln; git symbolic-ref -q beendet sich mit Nicht-Null, was Skripte handhaben können. Schließlich: Die zugrunde liegende Ref löschen, ohne die symbolische zu aktualisieren, und einen Dangling-Symref hinterlassen; Tools können das melden, aber es ist harmlos und leicht mit einem weiteren symbolic-ref zu beheben.