Einführung

Tags sind benannte Referenzen auf bestimmte Commits. Anders als Branches sind Tags nicht dafür gedacht, sich zu bewegen. Sie eignen sich perfekt zum Markieren von Releases (v1.0.0) und anderen historischen Punkten.

Zwei Arten von Tags

• Lightweight: nur eine Ref, die auf einen Commit zeigt. Keine Metadaten.
• Annotated: ein vollständiges Git-Objekt mit Tagger, Datum, Nachricht und optionaler GPG-Signatur. Verwenden Sie diese für Releases.

Tags erstellen

git tag v1.0.0                          # Lightweight
git tag -a v1.0.0 -m "First stable release"   # Annotated
git tag -s v1.0.0 -m "Signed release"         # GPG-signiert

Standardmäßig hängen Tags an HEAD. Um einen bestimmten Commit zu taggen:

git tag -a v0.9.0 a1b2c3d -m "Beta"

Auflisten und inspizieren

git tag
git tag -l "v1.*"
git show v1.0.0
git tag -l --format='%(refname:short) %(taggerdate:short) %(subject)'

Tags pushen

Tags werden standardmäßig nicht gepusht:

git push origin v1.0.0
git push origin --tags                # alle Tags
git push --follow-tags                # nur Tags, die von gepushten Commits aus erreichbar sind

--follow-tags ist die empfohlene Voreinstellung für Release-Pipelines.

Tags löschen

git tag -d v1.0.0                     # lokal
git push origin --delete v1.0.0       # Remote

Einen Tag auschecken

git switch --detach v1.0.0
# oder einen Hotfix-Branch auf einem Tag basieren
git switch -c hotfix/1.0.1 v1.0.0

Signaturen verifizieren

git tag -v v1.0.0

Erfordert den öffentlichen Schlüssel des Taggers in Ihrem GPG-Keyring.

Builds mit git describe beschreiben

Sobald Ihr Repository annotated Tags hat, erzeugt git describe stabile Build-Identifikatoren, die den letzten Tag, den Abstand und den abgekürzten SHA kombinieren:

git describe
# v1.2.3-7-gabc1234
git describe --always --dirty
# v1.2.3-7-gabc1234-dirty

Das --dirty-Suffix erscheint, wenn der Working Tree uncommitted Änderungen hat; --always fällt auf einen reinen SHA zurück, wenn kein Tag erreichbar ist. CI-Pipelines betten diesen String oft in Binaries ein, um die Fehlersuche bei Berichten aus dem Feld trivial zu machen.

Tagging-Richtlinien

Für langfristig unterstützte Projekte sollten Sie entscheiden und dokumentieren:

• Namensschema: v1.2.3, release-2025-04, 1.2.3 (ohne Präfix)?
• Annotated oder signiert?
• Wer darf Tags pushen? Viele Hosts erlauben es Ihnen, Tag-Namen mit Mustern zu schützen.
• Was ist die Wahrheitsquelle: nur Tags-auf-main, oder Release-Branches mit eigenen Tags?

git for-each-ref --sort=-creatordate --format='%(refname:short) %(creatordate:short)' refs/tags | head

Wählen Sie ein Schema und bleiben Sie dabei; Tag-Historie ist schwerer zu migrieren als Commit-Historie.

Häufige Fehler

Lightweight-Tags für Releases verwenden. Ihnen fehlen Datum, Autor und Nachricht, was Audit-Trails schmerzhaft macht. Verwenden Sie für Releases immer -a oder -s. Einen Tag nach Veröffentlichung verschieben; nachgelagerte Nutzer übernehmen die Änderung nicht sauber. Erstellen Sie stattdessen einen neuen Tag (z. B. v1.0.1). Vergessen, Tags zu pushen, und sich wundern, warum die Release-Seite leer ist; denken Sie an git push --tags oder --follow-tags. Schließlich: Tags mit Zeichen benennen, die mit Refs kollidieren (ein Tag und ein Branch namens release erzeugen Mehrdeutigkeit); verwenden Sie eine klare Konvention wie v<semver> für Releases.