git branch

O que o git branch faz

O comando git branch cria, lista, renomeia e deleta branches. Essa é toda a sua função — ele não muda a sua árvore de trabalho para um branch e não mescla trabalhos. Essas tarefas pertencem ao git checkout / git switch e ao git merge. Pense no git branch como a ferramenta que gerencia os rótulos, enquanto os outros comandos permitem mover-se entre eles e reuni-los.

Esta página aborda o que é um branch de fato, como criá-los e listá-los, como renomeá-los e deletá-los (localmente e em um repositório remoto), e as armadilhas comuns que costumam pegar as pessoas de surpresa.

O que é um branch de verdade

Um branch no Git não é uma cópia dos seus arquivos — é um ponteiro leve e móvel para um único commit. Cada commit também aponta de volta para seu(s) pai(s), portanto, seguir um ponteiro de branch de volta pelos seus pais reconstrói o histórico completo daquela linha de trabalho.

Como um branch é apenas um arquivo de 41 bytes contendo um hash de commit, criá-lo é instantâneo e custa quase nada:

cat .git/refs/heads/main
# 9f1c2a7e8d... (the commit your branch currently points at)

Um ponteiro especial chamado HEAD rastreia em qual branch você está atualmente. Quando você faz um commit, o ponteiro do branch atual avança para o novo commit e o HEAD o segue. É por isso que o uso de branches é tão barato no Git em comparação com sistemas de controle de versão mais antigos que duplicavam arquivos fisicamente.

Por que usar branches

Os branches oferecem uma linha de desenvolvimento isolada. Você pode construir um recurso ou corrigir um bug em seu próprio branch sem tocar no branch main estável, e depois mesclá-lo de volta quando estiver pronto. Razões comuns:

• Desenvolver dois recursos em paralelo sem que suas alterações colidam.
• Manter o main sempre pronto para lançamento enquanto o código experimental vive em outro lugar.
• Limpar o histórico antes de mesclar, para que o branch compartilhado permaneça organizado.
• Abrir um pull request — a maioria das plataformas cria PRs com base em branches.

Opções comuns

Criando branches

Branches são apenas ponteiros para commits. Quando você cria um, o Git adiciona um novo ponteiro no seu commit atual — ele não altera o histórico.

Crie um branch no seu commit atual:

git branch test_branch

Um novo ponteiro para o commit atual é criado; mais nada se move:

Criar um branch não muda você para ele — o HEAD ainda aponta para o branch antigo. Para começar a trabalhar no novo branch, mude para ele e então use git add e git commit para registrar o trabalho:

git switch test_branch     # modern; or: git checkout test_branch

Na maioria das vezes, você quer criar e mudar em uma única etapa:

git switch -c test_branch     # create + switch (modern)
git checkout -b test_branch   # create + switch (older syntax, identical effect)

Você também pode criar um branch a partir de um ponto específico em vez do HEAD — uma tag, outro branch ou um hash de commit:

git branch hotfix v1.0        # branch starting at the v1.0 tag
git branch experiment 9f1c2a7 # branch starting at an old commit

Listando e inspecionando branches

Executar git branch sem argumentos mostra seus branches locais e marca o atual:

git branch
#   feature-login
# * main
#   test_branch

Adicione -v para ver para onde cada branch aponta:

git branch -v
#   feature-login 1a2b3c4 Add login form
# * main          9f1c2a7 Update README
#   test_branch   9f1c2a7 Update README

Para saber quais branches são seguros para limpar, liste os que já foram mesclados no seu branch atual. Qualquer um listado aqui pode ser removido com -d:

git branch --merged
#   feature-login
# * main

Renomeando branches

Use -m (mover) para renomear. Para renomear o branch em que você está, basta fornecer o novo nome:

git branch -m better-name

Para renomear um branch diferente, forneça o nome antigo e o novo:

git branch -m old-name new-name

Se um branch com o nome de destino já existir, -m recusa sobrescrevê-lo; use -M para forçar a renomeação. Note que renomear um branch que existe em um repositório remoto não o renomeia lá — você precisa fazer push do novo nome e deletar o antigo.

Deletando branches

Após um branch ser mesclado no main, delete o ponteiro local para manter sua lista de branches organizada:

git branch -d test_branch
# Deleted branch test_branch (was 9f1c2a7).

A flag -d é uma verificação de segurança: ela recusa deletar um branch cujos commits não foram ainda mesclados no branch atual, para que você não perca trabalho:

git branch -d test_branch
# error: The branch 'test_branch' is not fully merged.
# If you are sure you want to delete it, run 'git branch -D test_branch'.

Se você tem certeza de que quer o branch (e seus commits não mesclados) removido, use o -D maiúsculo para forçar:

git branch -D test_branch

Deletando um branch remoto

Os comandos acima removem apenas a sua cópia local. O branch ainda pode existir no repositório remoto (por exemplo, em origin). Para deletá-lo lá:

git push origin --delete test_branch

A sintaxe mais antiga com dois-pontos faz a mesma coisa — ela faz push de "nada" no branch remoto, o que o deleta:

git push origin :test_branch

Para criar um branch em um repositório remoto, faça push de um branch local; o primeiro push o cria no remoto e (com -u) configura o rastreamento. Consulte git push e git remote para mais detalhes:

git push -u origin test_branch
# pushes test_branch to origin and tracks it

Um exemplo completo

Aqui está o ciclo típico de criar → trabalhar → mesclar → limpar, do início ao fim:

git switch -c feature-x        # create and switch to the branch
# ... edit files ...
git add .
git commit -m "Add feature X"

git switch main                # back to main
git merge feature-x            # bring the work in
git branch -d feature-x        # delete the now-merged local branch
git push origin --delete feature-x   # and remove it from the remote

Prática