Kesalahan Git 'is not a valid branch name': Aturan, Perbaikan & Konvensi

Saat Git melaporkan `fatal: 'some-name' is not a valid branch name`, itu berarti string yang Anda kirim sebagai nama branch melanggar spesifikasi refname Git: rangkaian aturan yang mengatur apa yang menjadi nama referensi valid dalam repositori Git. Git memakai aturan yang sama untuk nama branch, nama tag, dan nama pelacakan remote, karena semuanya disimpan sebagai referensi di direktori `.git/refs/`.

Validasi terjadi sebelum objek apa pun ditulis. Git menjalankan nama yang Anda usulkan melalui `check_refname_format()` secara internal dan berhenti dengan kesalahan jika nama itu gagal. Artinya, kesalahan terlihat langsung saat menjalankan `git checkout -b`, `git branch`, atau `git switch -c` - tidak ada keadaan parsial yang perlu dibersihkan.

Di mana kesalahan muncul

• `git checkout -b branch-name` - membuat branch baru dan berpindah ke sana
• `git branch branch-name` - membuat branch baru tanpa berpindah
• `git switch -c branch-name` - padanan modern dari checkout -b
• `git push origin branch-name` - mendorong ke remote dengan nama lokal yang tidak valid
• Skrip CI/CD - ketika nama branch dibangun secara programatik dari ID tiket atau pesan commit

Spesifikasi refname Git (didefinisikan di halaman man `git-check-ref-format`) menjelaskan rangkaian karakter dan pola yang dilarang secara presisi. Mempelajari aturan sekali mencegah semua kesalahan penamaan berikutnya - tidak ada kasus ambigu begitu daftar lengkapnya diketahui.

Karakter dan urutan yang dilarang secara eksplisit

• Spasi (ASCII 0x20) - kesalahan paling umum; gunakan `-` atau `_` sebagai gantinya.
• Tilde `~` - dipakai dalam notasi reflog (`branch~2` berarti dua commit sebelum ujung).
• Sirkumfleks `^` - dipakai dalam notasi revisi (`branch^` berarti commit induk).
• Titik dua `:` - dipakai dalam notasi refspec fetch (`refs/heads/main:refs/heads/main`).
• Tanda tanya `?` - karakter wildcard glob dalam pola ref.
• Asterisk `*` - karakter wildcard glob dalam pola ref.
• Kurung siku pembuka `[` - pembuka set karakter glob.
• Backslash `\\` - pemisah jalur di Windows; dilarang untuk menghindari masalah lintas platform.
• Titik ganda `..` - dipakai dalam notasi rentang (`main..feature`).
• Urutan @{ - notasi singkat reflog (`branch@{1}` adalah entri reflog).

Aturan posisional dan struktural

• Tidak boleh diawali titik (`.`) - konvensi file tersembunyi; `.hidden` bukan awalan yang valid.
• Tidak boleh diakhiri titik (`.`) - ambigu dengan ekstensi `.lock` dan notasi ekstensi file.
• Tidak boleh diakhiri `.lock` - Git memakai akhiran `.lock` untuk file kunci; komponen jalur mana pun yang berakhiran `.lock` dilarang.
• Tidak boleh diawali tanda hubung (`-`) - bentrok dengan penguraian opsi baris perintah.
• Tidak boleh memuat titik berurutan (`..`) - bentrok dengan notasi rentang (lihat di atas).
• Tidak boleh berupa karakter tunggal `@` - singkatan dari `HEAD`.
• Tidak boleh memuat karakter kontrol - karakter ASCII di bawah 0x20 dan DEL (0x7F) dilarang.
• Tidak boleh kosong - string kosong bukan nama yang valid.

# ✓ 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

Sebagian besar kejadian kesalahan ini berasal dari sejumlah kecil pola yang berulang. Masing-masing punya penyebab spesifik dan perbaikan spesifik satu baris.

Spasi dari judul tiket yang di-copy-paste

Pemicu paling umum adalah menyalin judul tiket atau story langsung ke nama branch. "Add user login form" menjadi `git checkout -b Add user login form`, yang Git pandang sebagai tiga argumen terpisah dan menolak nama branch `Add`. Perbaikan: ganti setiap spasi dengan tanda hubung. Banyak tim mengotomatiskannya dengan alias atau skrip `branch-from-ticket` yang mentransformasi judul sebelum diteruskan ke Git. Pembuat Slug mengonversi teks apa pun menjadi slug bersih terpisah tanda hubung yang cocok untuk nama branch.

Karakter khusus dalam interpolasi variabel CI/CD

Pipeline CI sering membangun nama branch dari variabel lingkungan - judul PR, pesan commit, atau ID tiket Jira. Jika ada nilai yang memuat karakter khusus (titik dua dalam ID Jira seperti `PROJECT:123`, atau garis miring dalam tag semver seperti `v1.0.0/rc.1`), nama branch hasil interpolasi akan gagal. Perbaikan: bersihkan masukan sebelum dipakai sebagai nama branch. Ganti karakter non-alfanumerik dengan tanda hubung dan buang tanda hubung serta titik di awal dan akhir.

Titik di akhir atau akhiran .lock

Nama branch yang berakhir dengan titik (`feature.`) atau berakhir dengan `.lock` (`release.lock`) gagal karena Git mencadangkan pola-pola itu untuk file kunci. Kesalahan ini biasanya muncul saat seorang pengembang tak sengaja mengetik nama yang berakhir titik, atau saat skrip menambahkan `.lock` sebagai bagian dari nama hasil generasi. Perbaikan: hapus titik di akhir, atau ganti `.lock` dengan akhiran valid seperti `-locked` atau `-pending`.

Dalam kasus yang jarang - terutama dengan versi Git lama atau branch yang dibuat lewat alat pihak ketiga - Anda bisa mewarisi nama branch tidak valid yang sudah ter-commit di repositori. Git modern mencegah hal ini saat pembuatan, tetapi jika Anda mewarisi repositori dengan nama branch bermasalah, begini perbaikannya.

Aturan refname Git sendiri adalah garis dasar. Platform hosting remote menerapkan pembatasan tambahan di atasnya - nama yang lolos validasi lokal Git tetap bisa gagal saat didorong ke GitHub atau GitLab. Memahami aturan spesifik platform mencegah frustrasi nama yang berfungsi lokal tetapi gagal di remote.

Pembatasan tambahan GitHub

GitHub menolak nama branch yang berakhiran `.lock` pada komponen jalur mana pun (bukan hanya segmen terakhir), nama yang memuat titik berurutan pada posisi mana pun, dan nama yang memuat byte nol. GitHub juga menegakkan panjang nama branch maksimum 255 byte. Antarmuka web GitHub juga memangkas spasi di awal dan akhir nama yang dibuat melalui UI.

Pembatasan tambahan GitLab

GitLab menambahkan pembatasan untuk pola branch terproteksi - nama yang memuat wildcard `*` dicadangkan untuk aturan branch terproteksi dan tidak boleh dipakai sebagai nama branch literal. GitLab juga mencadangkan nama branch yang cocok dengan namespacing internalnya seperti `protected` dan `refs`. Nama branch lebih panjang dari 255 karakter ditolak. Validasi nama di pipeline GitLab CI terpisah dari validasi refname Git - kesalahan interpolasi variabel CI muncul sebagai kegagalan pipeline, bukan kesalahan Git.

Pertimbangan sistem berkas Windows

Di Windows, direktori `.git/refs/heads/` menyimpan setiap branch sebagai file. Artinya, semua pembatasan nama file Windows berlaku: nama tidak boleh memuat `<`, `>`, `"`, `|`, `?`, atau `*`; nama tidak boleh berakhir spasi atau titik; dan nama tidak peka huruf besar-kecil pada NTFS. Isu ketidakpekaan huruf ini penting sekali dalam tim campuran - `Feature/Login` dan `feature/login` adalah branch yang sama di Windows tetapi branch berbeda di Linux dan macOS.

Valid adalah batas bawah, bukan batas atas. Nama branch bisa valid menurut aturan Git tetapi tetap tidak jelas, tidak konsisten, atau tak terpakai dalam alur kerja tim Anda. Konvensi yang mapan menambah prediktabilitas di atas validitas teknis - setiap anggota tim bisa membaca nama branch dan langsung memahami tujuan, cakupan, dan siklus hidupnya.

Konvensi Gitflow

Gitflow memakai lima jenis branch: `main` (produksi), `develop` (integrasi), `feature/deskripsi`, `release/versi`, dan `hotfix/deskripsi`. Nama branch memakai kategori sebagai prefiks diikuti garis miring dan deskripsi terpisah tanda hubung. Branch release memuat nomor versi (`release/1.4.0`). Konvensi ini didukung baik oleh kebanyakan klien GUI Git dan alat CI, yang mengenali prefiks sebagai kategori branch.

GitHub Flow dan konvensi berbasis trunk

GitHub Flow memakai struktur lebih sederhana: `main` ditambah branch fitur berumur pendek dengan nama deskriptif (`add-oauth-login`, `fix-pagination-bug`). Pengembangan berbasis trunk juga memakai `main` ditambah branch sangat pendek usianya yang di-merge dalam hitungan jam. Kedua pendekatan menyukai nama pendek, huruf kecil, terpisah tanda hubung tanpa prefiks kategori - asumsinya nama branch bersifat sementara dan judul serta deskripsi PR yang membawa konteks.

Konvensi dengan referensi tiket

Banyak tim memberi prefiks referensi tiket pada nama branch: `JIRA-1234-fix-login-bug` atau `feat/GH-456-add-dark-mode`. ID tiket menyediakan ketertelusuran antara branch dan item kerja asal. Saat membangun nama-nama ini secara programatik, selalu bersihkan bagian deskripsi tiket - judul tiket sering memuat titik dua, garis miring, dan karakter lain yang merusak aturan penamaan Git.

Nama branch, seperti pesan commit, adalah dokumentasi. Konvensi penamaan yang konsisten mengubah daftar branch Anda menjadi changelog yang mudah dibaca atas pekerjaan yang sedang berjalan.

Memperbaiki kesalahan satu per satu itu reaktif. Pendekatan yang lebih baik adalah mencegah nama tidak valid tercipta sejak awal - melalui alat validasi, integrasi editor, dan pemeriksaan CI yang menangkap masalah sebelum mengganggu tim.

Hook Git pre-push

Skrip `.git/hooks/pre-push` berjalan sebelum setiap `git push` dan dapat memvalidasi nama branch saat ini terhadap konvensi tim Anda. Jika nama gagal, hook keluar dengan kode non-nol dan menghentikan push dengan pesan penjelas. Gunakan framework `pre-commit` untuk mendistribusikan hook secara konsisten ke seluruh tim - file `.git/hooks/` individual tidak di-commit ke repositori, tetapi `.pre-commit-config.yaml` di-commit.

Validasi nama di pipeline CI

Tambahkan langkah validasi nama branch di awal pipeline CI Anda. Untuk GitHub Actions, gunakan langkah job awal yang memeriksa nama branch terhadap pola regex dan menggagalkan workflow jika tidak cocok. Ini menangkap nama yang secara teknis valid menurut Git tetapi melanggar konvensi tim - nama tanpa prefiks jenis, terlalu panjang, atau tanpa referensi tiket. Validator Konvensi Nama Branch menerapkan logika yang sama secara lokal di browser Anda, berguna untuk memeriksa nama sebelum membuat branch.

• Validasi lokal sebelum membuat: gunakan Validator Konvensi Nama Branch untuk memeriksa nama terhadap aturan Git sekaligus konvensi tim.
• Gunakan skrip pembuatan branch: fungsi shell kecil yang menerima ID tiket dan deskripsi lalu menghasilkan nama branch terformat benar menghilangkan sepenuhnya kesalahan penamaan manual.
• Tambahkan hook pre-push: memvalidasi nama branch pada setiap push - lini pertahanan terakhir sebelum nama tidak valid mencapai remote.
• Lint di CI: langkah GitHub Actions atau GitLab CI yang memvalidasi nama branch pada setiap PR mencegah pelanggaran konvensi ter-merge.
• Dokumentasikan konvensi di CONTRIBUTING.md: anggota tim yang tahu aturannya membuat lebih sedikit kesalahan daripada yang menebak dari contoh.