Branching Convencional

Crie branches Git que sigam a especificação Branching Convencional — uma convenção simples e consistente para nomear branches Git.

Formato do Nome da Branch

<type>/<description>

Tipos de Branch

Branches Trunk

main, master e develop são branches trunk — elas não usam um prefixo. Nunca crie novas branches com os mesmos nomes das branches trunk; crie a partir delas em vez disso.

Regras de Nomenclatura

• Apenas minúsculas — sem letras maiúsculas em lugar nenhum
• Alfanuméricos, hifens e pontos — a-z, 0-9, -, .
• Pontos permitidos apenas em descrições de versão release/ (ex: release/v1.2.0)
• Sem underscores, espaços ou caracteres especiais
• Sem hifens consecutivos (--), pontos (..) ou adjacência de hífen-ponto (-. ou .-)
• Sem hifens ou pontos no início ou fim da descrição

Exemplos Válidos

main
master
develop
feature/add-login-page
feat/add-login-page
bugfix/fix-header-bug
fix/header-bug
hotfix/security-patch
release/v1.2.0
chore/update-dependencies
feature/issue-123-new-login

Exemplos Inválidos

Diretrizes de Descrição

• Use kebab-case com 2-5 palavras
• Seja descritivo, mas conciso (~50 caracteres no total)
• Bom: add-oauth-login, fix-header-overflow, update-ci-config
• Ruim: fix-bug, new-feature

Fluxo de Trabalho

Siga estes passos:

Passo 1 — Determinar o Tipo da Branch

Pergunte ao usuário (se não estiver claro):

• Tipo da branch — use feature como padrão quando incerto
• Breve descrição — para que serve a branch

Se o usuário mencionar um número de ticket ou issue, inclua-o na descrição (ex: feature/issue-123-add-oauth).

Passo 2 — Validar o Nome

Verifique o nome montado com as Regras de Nomenclatura acima. Se alguma regra falhar, corrija:

• Converta tudo para minúsculas
• Substitua underscores e espaços por hifens
• Colapse hifens consecutivos
• Remova hifens no início/fim

Passo 3 — Detectar a Branch Base

Diferentes repositórios usam diferentes branches trunk. Detecte qual este repositório usa:

# Prefer the remote's default branch
git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'

Se isso não retornar nada, verifique qual branch trunk existe localmente (ordem de prioridade: develop, main, master):

for b in develop main master; do
  git show-ref --verify --quiet "refs/heads/$b" && echo "$b" && break
done

Passo 4 — Criar e Fazer Checkout

git checkout <base>
git pull origin <base>
git checkout -b <type>/<description>

Passo 5 — Confirmar

Informe ao usuário:

• O nome da branch que foi criada
• Que ele agora está na nova branch
• Lembre-o: git push -u origin <branch-name> quando estiver pronto

Relação com Commits Convencionais

Branching Convencional complementa Commits Convencionais:

Alinhe o tipo da branch com os tipos de commit sempre que possível (ex: branches feature/* com commits feat:).