Erro do Git 'is not a valid branch name': Regras, Correções e Convenções

Quando o Git reporta `fatal: 'some-name' is not a valid branch name`, significa que a string que você passou como nome de branch viola a especificação de refname do Git: o conjunto de regras que governa o que constitui um nome de referência válido em um repositório Git. O Git usa as mesmas regras para nomes de branches, tags e nomes de rastreamento remoto, porque todos são armazenados como referências no diretório `.git/refs/`.

A validação acontece antes de qualquer objeto ser escrito. O Git passa o nome proposto por `check_refname_format()` internamente e aborta com o erro se o nome falhar. Isso significa que você vê o erro imediatamente ao executar `git checkout -b`, `git branch` ou `git switch -c` - não há estado parcial para limpar.

Onde o erro aparece

• `git checkout -b branch-name` - criar uma nova branch e alternar para ela
• `git branch branch-name` - criar uma nova branch sem alternar
• `git switch -c branch-name` - o equivalente moderno de checkout -b
• `git push origin branch-name` - fazer push para um remoto com um nome local inválido
• Scripts de CI/CD - quando um nome de branch é construído programaticamente a partir de um ID de ticket ou mensagem de commit

A especificação de refname do Git (definida na página man de `git-check-ref-format`) descreve um conjunto preciso de caracteres e padrões proibidos. Aprender as regras uma vez previne todos os futuros erros de nomenclatura - não há casos ambíguos depois que você conhece a lista completa.

Caracteres e sequências explicitamente proibidos

• Espaço (ASCII 0x20) - o erro mais comum; use `-` ou `_` no lugar.
• Til `~` - usado na notação de reflog (`branch~2` significa dois commits antes da ponta).
• Acento circunflexo `^` - usado na notação de revisão (`branch^` significa o commit pai).
• Dois-pontos `:` - usados na notação de refspec de fetch (`refs/heads/main:refs/heads/main`).
• Interrogação `?` - caractere curinga glob em padrões de refs.
• Asterisco `*` - caractere curinga glob em padrões de refs.
• Colchete de abertura `[` - abertura de conjunto de caracteres glob.
• Barra invertida `\\` - separador de caminho no Windows; proibida para evitar problemas multiplataforma.
• Ponto duplo `..` - usado na notação de intervalo (`main..feature`).
• Sequência @{ - notação abreviada de reflog (`branch@{1}` é uma entrada de reflog).

Regras posicionais e estruturais

• Não pode começar com ponto (`.`) - convenção de arquivos ocultos; `.hidden` não é um início válido.
• Não pode terminar com ponto (`.`) - ambíguo com a extensão `.lock` e a notação de extensões de arquivo.
• Não pode terminar com `.lock` - o Git usa o sufixo `.lock` para arquivos de bloqueio; qualquer componente de caminho terminando em `.lock` é proibido.
• Não pode começar com hífen (`-`) - conflita com a análise de opções de linha de comando.
• Não pode conter pontos consecutivos (`..`) - conflito com a notação de intervalo (veja acima).
• Não pode ser o caractere único `@` - abreviação de `HEAD`.
• Não pode conter caracteres de controle - caracteres ASCII abaixo de 0x20 e DEL (0x7F) são proibidos.
• Não pode ser vazio - uma string vazia não é um nome válido.

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

A maioria das ocorrências desse erro vem de um pequeno número de padrões repetitivos. Cada um tem uma causa específica e uma correção específica de uma linha.

Espaços de títulos de ticket copiados e colados

O gatilho mais comum é copiar um título de ticket ou história diretamente para o nome da branch. "Add user login form" se torna `git checkout -b Add user login form`, que o Git vê como três argumentos separados e rejeita o nome de branch `Add`. Correção: substitua cada espaço por um hífen. Muitas equipes automatizam isso com um alias ou script `branch-from-ticket` que transforma o título antes de passá-lo ao Git. O Gerador de Slugs converte qualquer texto em um slug limpo separado por hifens adequado para nomes de branches.

Caracteres especiais na interpolação de variáveis de CI/CD

Pipelines de CI frequentemente constroem nomes de branches a partir de variáveis de ambiente - títulos de PR, mensagens de commit ou IDs de tickets do Jira. Se qualquer um desses valores contiver um caractere especial (dois-pontos em um ID do Jira como `PROJECT:123`, ou uma barra em uma tag semver como `v1.0.0/rc.1`), o nome de branch interpolado falhará. Correção: sanitize a entrada antes de usá-la como nome de branch. Substitua caracteres não alfanuméricos por hifens e remova hifens e pontos no início e no fim.

Ponto final ou sufixo .lock

Um nome de branch que termina com ponto (`feature.`) ou termina com `.lock` (`release.lock`) falha porque o Git reserva esses padrões para arquivos de bloqueio. Esse erro normalmente aparece quando um desenvolvedor digita um nome terminando com ponto por acidente, ou quando um script acrescenta `.lock` como parte de um nome gerado. Correção: remova o ponto final, ou substitua `.lock` por um sufixo válido como `-locked` ou `-pending`.

Em casos raros - particularmente com versões antigas do Git ou branches criadas via ferramentas de terceiros - você pode acabar com um nome de branch inválido já commitado no seu repositório. O Git moderno previne isso no momento da criação, mas se você herdar um repositório com um nome de branch problemático, veja como corrigir.

As regras de refname do próprio Git são a base. As plataformas de hospedagem remota aplicam restrições adicionais por cima - um nome que passa na validação local do Git ainda pode falhar no push para GitHub ou GitLab. Entender as regras específicas de cada plataforma evita a frustração de um nome que funciona localmente mas falha remotamente.

Restrições adicionais do GitHub

O GitHub rejeita nomes de branches que terminam com `.lock` em qualquer componente de caminho (não apenas o segmento final), nomes que contêm pontos consecutivos em qualquer posição e nomes que contêm um byte nulo. O GitHub também impõe um tamanho máximo de nome de branch de 255 bytes. A interface web do GitHub, adicionalmente, remove espaços em branco no início e no fim de nomes criados pela interface.

Restrições adicionais do GitLab

O GitLab acrescenta restrições para padrões de branches protegidas - nomes contendo curingas `*` são reservados para regras de branches protegidas e não podem ser usados como nomes literais de branch. O GitLab também reserva nomes de branch que correspondam ao seu namespacing interno como `protected` e `refs`. Nomes de branch com mais de 255 caracteres são rejeitados. A validação de nomes no pipeline do GitLab CI é separada da validação de refname do Git - erros de interpolação de variáveis de CI aparecem como falhas de pipeline em vez de erros do Git.

Considerações sobre o sistema de arquivos do Windows

No Windows, o diretório `.git/refs/heads/` armazena cada branch como um arquivo. Isso significa que todas as restrições de nomes de arquivo do Windows se aplicam: nomes não podem conter `<`, `>`, `"`, `|`, `?` ou `*`; nomes não podem terminar com espaço ou ponto; e os nomes são insensíveis a maiúsculas e minúsculas no NTFS. A questão da insensibilidade a maiúsculas é particularmente importante em equipes mistas - `Feature/Login` e `feature/login` são a mesma branch no Windows, mas branches diferentes no Linux e no macOS.

Válido é o piso, não o teto. Um nome de branch pode ser válido segundo as regras do Git e ainda ser pouco claro, inconsistente ou inutilizável no fluxo de trabalho da sua equipe. Convenções estabelecidas acrescentam previsibilidade sobre a validade técnica - cada membro da equipe consegue ler um nome de branch e entender imediatamente seu propósito, escopo e ciclo de vida.

Convenção Gitflow

O Gitflow usa cinco tipos de branch: `main` (produção), `develop` (integração), `feature/descrição`, `release/versão` e `hotfix/descrição`. Os nomes de branch usam a categoria como prefixo seguido de uma barra e uma descrição separada por hifens. As branches de release incluem o número de versão (`release/1.4.0`). Essa convenção é bem suportada pela maioria dos clientes GUI do Git e ferramentas de CI, que reconhecem os prefixos como categorias de branch.

GitHub Flow e convenções baseadas em trunk

O GitHub Flow usa uma estrutura mais simples: `main` mais branches de feature de vida curta com nomes descritivos (`add-oauth-login`, `fix-pagination-bug`). O desenvolvimento baseado em trunk usa, de forma semelhante, `main` mais branches muito efêmeras que são mescladas em horas. Ambas as abordagens preferem nomes curtos, em minúsculas e separados por hifens sem prefixos de categoria - a suposição é que os nomes de branch são temporários e o título e a descrição do PR carregam o contexto.

Convenções com referência de ticket

Muitas equipes prefixam nomes de branches com uma referência de ticket: `JIRA-1234-fix-login-bug` ou `feat/GH-456-add-dark-mode`. O ID do ticket fornece rastreabilidade entre a branch e o item de trabalho de origem. Ao construir esses nomes programaticamente, sempre sanitize a parte da descrição do ticket - títulos de ticket frequentemente contêm dois-pontos, barras e outros caracteres que quebram as regras de nomenclatura do Git.

Nomes de branches, como mensagens de commit, são documentação. Uma convenção de nomenclatura consistente transforma sua lista de branches em um changelog legível do trabalho em andamento.

Corrigir erros individuais é reativo. A melhor abordagem é impedir que nomes inválidos sejam criados em primeiro lugar - por meio de ferramentas de validação, integrações de editor e verificações de CI que capturam problemas antes de atrapalhar a equipe.

Hooks de pre-push do Git

Um script `.git/hooks/pre-push` roda antes de qualquer `git push` e pode validar o nome da branch atual contra a convenção da sua equipe. Se o nome falhar, o hook sai com código diferente de zero e aborta o push com uma mensagem explicativa. Use o framework `pre-commit` para distribuir hooks de forma consistente pela equipe - arquivos `.git/hooks/` individuais não são commitados no repositório, mas um `.pre-commit-config.yaml` é.

Validação de nomes no pipeline de CI

Adicione uma etapa de validação de nome de branch no início do seu pipeline de CI. Para o GitHub Actions, use uma etapa de job inicial que verifica o nome da branch contra um padrão regex e faz o workflow falhar se não corresponder. Isso captura nomes tecnicamente válidos segundo o Git, mas que violam a convenção da equipe - nomes sem prefixo de tipo, muito longos ou sem referência de ticket. O Validador de Convenção de Nomes de Branch aplica essa mesma lógica localmente no seu navegador, útil para verificar um nome antes de criar a branch.

• Valide localmente antes de criar: use o Validador de Convenção de Nomes de Branch para verificar nomes contra as regras do Git e as convenções da equipe.
• Use um script de criação de branch: uma pequena função de shell que recebe um ID de ticket e uma descrição e produz um nome de branch corretamente formatado elimina totalmente os erros manuais de nomenclatura.
• Adicione um hook de pre-push: valida o nome da branch a cada push - a última linha de defesa antes que um nome inválido chegue ao remoto.
• Faça lint no CI: uma etapa do GitHub Actions ou GitLab CI que valida o nome da branch em cada PR impede que violações de convenção sejam mescladas.
• Documente a convenção no CONTRIBUTING.md: membros da equipe que conhecem as regras cometem menos erros do que quem adivinha a partir de exemplos.