Git-Fehler 'is not a valid branch name': Regeln, Behebungen & Konventionen

Wenn Git `fatal: 'some-name' is not a valid branch name` meldet, bedeutet das, dass die als Branchnamen übergebene Zeichenfolge die Refname-Spezifikation von Git verletzt - die Regeln, die festlegen, was ein gültiger Referenzname in einem Git-Repository ist. Git verwendet dieselben Regeln für Branchnamen, Tag-Namen und Remote-Tracking-Namen, da alle als Referenzen im Verzeichnis `.git/refs/` gespeichert werden.

Die Validierung findet statt, bevor ein Objekt geschrieben wird. Git führt den vorgeschlagenen Namen intern durch `check_refname_format()` und bricht mit dem Fehler ab, wenn der Name scheitert. Das bedeutet, Sie sehen den Fehler sofort beim Ausführen von `git checkout -b`, `git branch` oder `git switch -c` - es gibt keinen Teilzustand zu bereinigen.

Wo der Fehler auftritt

• `git checkout -b branch-name` - einen neuen Branch erstellen und dorthin wechseln
• `git branch branch-name` - einen neuen Branch erstellen, ohne zu wechseln
• `git switch -c branch-name` - das moderne Äquivalent zu checkout -b
• `git push origin branch-name` - Push auf ein Remote mit ungültigem lokalem Namen
• CI/CD-Skripte - wenn ein Branchnamen programmiertechnisch aus einer Ticket-ID oder Commit-Nachricht konstruiert wird

Die Refname-Spezifikation von Git (definiert in der Manpage von `git-check-ref-format`) beschreibt einen präzisen Satz verbotener Zeichen und Muster. Die Regeln einmal gelernt, verhindern alle künftigen Namensfehler - es gibt keine mehrdeutigen Fälle, wenn man die vollständige Liste kennt.

Explizit verbotene Zeichen und Sequenzen

• Leerzeichen (ASCII 0x20) - der häufigste Fehler; verwenden Sie stattdessen `-` oder `_`.
• Tilde `~` - verwendet in der Reflog-Notation (`branch~2` bedeutet zwei Commits vor der Spitze).
• Caret `^` - verwendet in der Revisionsnotation (`branch^` bedeutet der Eltern-Commit).
• Doppelpunkt `:` - verwendet in der Fetch-Refspec-Notation (`refs/heads/main:refs/heads/main`).
• Fragezeichen `?` - Glob-Platzhalterzeichen in Ref-Mustern.
• Sternchen `*` - Glob-Platzhalterzeichen in Ref-Mustern.
• Eckige Klammer auf `[` - öffnet eine Glob-Zeichenauswahl.
• Backslash `\\` - Pfadtrenner unter Windows; verboten, um plattformübergreifende Probleme zu vermeiden.
• Doppelter Punkt `..` - verwendet in der Bereichsnotation (`main..feature`).
• @{ Sequenz - Reflog-Kurzschrift (`branch@{1}` ist ein Reflog-Eintrag).

Positionale und strukturelle Regeln

• Darf nicht mit einem Punkt beginnen (`.`) - Konvention versteckter Dateien; `.hidden` ist kein gültiger Anfang.
• Darf nicht mit einem Punkt enden (`.`) - mehrdeutig mit der Endung `.lock` und der Dateierweiterungsnotation.
• Darf nicht mit `.lock` enden - Git nutzt das Suffix `.lock` für Sperrdateien; jeder Pfadkomponente, die auf `.lock` endet, ist verboten.
• Darf nicht mit einem Bindestrich beginnen (`-`) - kollidiert mit dem Parsen von Kommandozeilenoptionen.
• Darf keine aufeinanderfolgenden Punkte enthalten (`..`) - Konflikt mit der Bereichsnotation (siehe oben).
• Darf nicht das einzelne Zeichen `@` sein - Kurzschrift für `HEAD`.
• Darf keine Steuerzeichen enthalten - ASCII-Zeichen unter 0x20 und DEL (0x7F) sind verboten.
• Darf nicht leer sein - eine leere Zeichenfolge ist kein gültiger Name.

# ✓ Valid branch names
git checkout -b feature/add-login
git checkout -b fix/null-pointer-123
git checkout -b release/v2.1.0
git checkout -b chore_update-deps
git checkout -b users/alice/experiment

# ✗ Invalid - contains a space
git checkout -b "my feature"
# fatal: 'my feature' is not a valid branch name

# ✗ Invalid - double dot
git checkout -b feature..login
# fatal: 'feature..login' is not a valid branch name

# ✗ Invalid - ends with .lock
git checkout -b release.lock
# fatal: 'release.lock' is not a valid branch name

# ✗ Invalid - starts with hyphen
git checkout -b -hotfix
# fatal: '-hotfix' is not a valid branch name

Die meisten Vorkommen dieses Fehlers stammen aus einer kleinen Zahl sich wiederholender Muster. Jedes hat eine spezifische Ursache und eine spezifische Einzeiler-Behebung.

Leerzeichen aus kopierten Tickertiteln

Der häufigste Auslöser ist das direkte Kopieren eines Ticket- oder Story-Titels in den Branchnamen. „Add user login form" wird zu `git checkout -b Add user login form`, was Git als drei separate Argumente sieht und den Branchnamen `Add` ablehnt. Behebung: ersetzen Sie jedes Leerzeichen durch einen Bindestrich. Viele Teams automatisieren das mit einem `branch-from-ticket`-Alias oder -Skript, das den Titel transformiert, bevor er an Git übergeben wird. Der Slug-Generator wandelt beliebigen Text in einen sauberen, bindestrichgetrennten Slug um, der für Branchnamen geeignet ist.

Sonderzeichen in der Variableninterpolation von CI/CD

CI-Pipelines konstruieren Branchnamen oft aus Umgebungsvariablen - PR-Titel, Commit-Nachrichten oder Jira-Ticket-IDs. Enthält einer dieser Werte ein Sonderzeichen (ein Doppelpunkt in einer Jira-ID wie `PROJECT:123` oder ein Schrägstrich in einem Semver-Tag wie `v1.0.0/rc.1`), scheitert der interpolierte Branchname. Behebung: bereinigen Sie die Eingabe, bevor Sie sie als Branchnamen verwenden. Ersetzen Sie nicht-alphanumerische Zeichen durch Bindestriche und entfernen Sie führende und nachgestellte Bindestriche und Punkte.

Punkt am Ende oder .lock-Suffix

Ein Branchname, der mit einem Punkt endet (`feature.`) oder mit `.lock` endet (`release.lock`), scheitert, weil Git diese Muster für Sperrdateien reserviert. Dieser Fehler tritt typischerweise auf, wenn ein Entwickler versehentlich einen Namen mit Punkt am Ende eingibt, oder wenn ein Skript `.lock` an einen generierten Namen anhängt. Behebung: entfernen Sie den Punkt am Ende oder ersetzen Sie `.lock` durch ein gültiges Suffix wie `-locked` oder `-pending`.

In seltenen Fällen - insbesondere mit älteren Git-Versionen oder über Drittanbieter-Tools erstellten Branches - kann ein ungültiger Branchname bereits in Ihrem Repository gelandet sein. Modernes Git verhindert das bei der Erstellung, aber wenn Sie ein Repository mit problematischem Branchnamen erben, ist das die Behebung.

Die Refname-Regeln von Git selbst sind die Basis. Remote-Hosting-Plattformen legen zusätzliche Beschränkungen darüber - ein Name, der die lokale Git-Validierung besteht, kann beim Push zu GitHub oder GitLab trotzdem scheitern. Das Verständnis der plattformspezifischen Regeln verhindert die Frustration eines Namens, der lokal funktioniert, aber remote fehlschlägt.

Zusätzliche GitHub-Beschränkungen

GitHub lehnt Branchnamen ab, die auf `.lock` in irgendeiner Pfadkomponente enden (nicht nur das letzte Segment), Namen mit aufeinanderfolgenden Punkten an irgendeiner Position und Namen mit Nullbyte. GitHub setzt zudem eine maximale Branchnamenlänge von 255 Byte durch. Die GitHub-Weboberfläche entfernt außerdem führende und nachgestellte Leerzeichen von über die Oberfläche erstellten Branchnamen.

Zusätzliche GitLab-Beschränkungen

GitLab ergänzt Beschränkungen für geschützte Branch-Muster - Namen mit `*`-Platzhaltern sind für geschützte Branch-Regeln reserviert und können nicht als literale Branchnamen verwendet werden. GitLab reserviert auch Branchnamen, die seinem internen Namespacing entsprechen, etwa `protected` und `refs`. Branchnamen länger als 255 Zeichen werden abgelehnt. Die Namensvalidierung der GitLab-CI-Pipeline ist getrennt von der Git-Refname-Validierung - CI-Variablen-Interpolationsfehler erscheinen als Pipeline-Fehler, nicht als Git-Fehler.

Überlegungen zum Windows-Dateisystem

Unter Windows speichert das Verzeichnis `.git/refs/heads/` jeden Branch als Datei. Das bedeutet, alle Windows-Dateinamensbeschränkungen gelten: Namen dürfen keine `<`, `>`, `"`, `|`, `?` oder `*` enthalten; Namen dürfen nicht mit Leerzeichen oder Punkt enden; und Namen sind auf NTFS groß-/kleinschreibungsunempfindlich. Die Case-Insensitivität ist in gemischten Teams besonders wichtig - `Feature/Login` und `feature/login` sind unter Windows derselbe Branch, aber unter Linux und macOS unterschiedliche Branches.

Gültig ist das Minimum, nicht das Maximum. Ein Branchname kann gemäß den Git-Regeln gültig sein und dennoch unklar, inkonsistent oder im Workflow Ihres Teams unbrauchbar sein. Etablierte Konventionen fügen über der technischen Gültigkeit Vorhersehbarkeit hinzu - jedes Teammitglied kann einen Branchnamen lesen und sofort Zweck, Umfang und Lebenszyklus verstehen.

Gitflow-Konvention

Gitflow verwendet fünf Branch-Typen: `main` (Produktion), `develop` (Integration), `feature/beschreibung`, `release/version` und `hotfix/beschreibung`. Branchnamen nutzen die Kategorie als Präfix, gefolgt von einem Schrägstrich und einer bindestrichgetrennten Beschreibung. Release-Branches enthalten die Versionsnummer (`release/1.4.0`). Diese Konvention wird von den meisten Git-GUI-Clients und CI-Tools gut unterstützt, die die Präfixe als Branch-Kategorien erkennen.

GitHub-Flow und trunk-basierte Konventionen

GitHub Flow nutzt eine einfachere Struktur: `main` plus kurzlebige Feature-Branches mit beschreibenden Namen (`add-oauth-login`, `fix-pagination-bug`). Trunk-basierte Entwicklung nutzt ebenso `main` plus sehr kurzlebige Branches, die innerhalb von Stunden gemerged werden. Beide Ansätze bevorzugen kurze, kleingeschriebene, bindestrichgetrennte Namen ohne Kategoriepräfixe - die Annahme ist, dass Branchnamen temporär sind und der PR-Titel und die Beschreibung den Kontext tragen.

Ticket-Referenz-Konventionen

Viele Teams stellen Branchnamen eine Ticket-Referenz voran: `JIRA-1234-fix-login-bug` oder `feat/GH-456-add-dark-mode`. Die Ticket-ID schafft Rückverfolgbarkeit zwischen dem Branch und dem ursprünglichen Arbeitselement. Beim programmierten Aufbau dieser Namen bereinigen Sie stets den Ticket-Beschreibungsteil - Tickertitel enthalten häufig Doppelpunkte, Schrägstriche und andere Zeichen, die die Git-Namensregeln brechen.

Branchnamen sind, wie Commit-Nachrichten, Dokumentation. Eine konsistente Namenskonvention macht Ihre Branchliste zu einem lesbaren Changelog laufender Arbeiten.

Einzelne Fehler zu beheben ist reaktiv. Der bessere Ansatz ist, zu verhindern, dass ungültige Namen überhaupt entstehen - durch Validierungswerkzeuge, Editor-Integrationen und CI-Prüfungen, die Probleme abfangen, bevor sie das Team stören.

Pre-Push-Git-Hooks

Ein `.git/hooks/pre-push`-Skript läuft vor jedem `git push` und kann den aktuellen Branchnamen gegen die Konvention Ihres Teams validieren. Scheitert der Name, terminiert der Hook mit einem Code ungleich null und bricht den Push mit einer erklärenden Nachricht ab. Nutzen Sie das `pre-commit`-Framework, um Hooks teamweit konsistent zu verteilen - einzelne `.git/hooks/`-Dateien werden nicht ins Repository committet, eine `.pre-commit-config.yaml` jedoch.

Namensvalidierung in der CI-Pipeline

Fügen Sie eine Validierungsstufe für Branchnamen am Anfang Ihrer CI-Pipeline hinzu. Für GitHub Actions nutzen Sie einen frühen Job-Schritt, der den Branchnamen gegen ein Regex-Muster prüft und den Workflow scheitern lässt, wenn er nicht passt. Das fängt Namen ab, die gemäß Git technisch gültig sind, aber die Team-Konvention verletzen - Branchnamen ohne Typ-Präfix, zu lange Namen oder Namen ohne Ticket-Referenz. Der Branchnamen-Konventionsvalidator wendet dieselbe Logik lokal in Ihrem Browser an, nützlich, um einen Namen zu prüfen, bevor Sie den Branch erstellen.

• Lokal validieren vor dem Erstellen: nutzen Sie den Branchnamen-Konventionsvalidator, um Namen gegen Git-Regeln und Team-Konventionen zu prüfen.
• Ein Branch-Erstellungsskript nutzen: eine kleine Shell-Funktion, die eine Ticket-ID und Beschreibung nimmt und einen korrekt formatierten Branchnamen erzeugt, eliminiert manuelle Namensfehler vollständig.
• Pre-Push-Hook ergänzen: validiert den Branchnamen bei jedem Push - die letzte Verteidigungslinie, bevor ein ungültiger Name das Remote erreicht.
• In CI linten: ein GitHub-Actions- oder GitLab-CI-Schritt, der den Branchnamen bei jedem PR validiert, verhindert, dass Konventionsverstöße gemerged werden.
• Konvention in CONTRIBUTING.md dokumentieren: Teammitglieder, die die Regeln kennen, machen weniger Fehler als solche, die aus Beispielen raten.