git branch

Branches e merges

Listar, criar ou excluir branches

O comando 'git branch' permite criar, listar, renomear e excluir branches. Ele não troca de branch - para isso use 'git switch' ou 'git checkout'. No Git, as branches são ponteiros leves para commits, o que torna criar e trocar de branch extremamente rápido. Sem argumentos, o git branch lista as branches existentes e destaca a atual. Com um nome de branch, ele cria uma branch nova apontando para o HEAD atual. Branches são essenciais para o desenvolvimento em paralelo: várias funcionalidades ou correções podem avançar ao mesmo tempo sem atrapalhar umas às outras.

Sinopse

git branch [--list] [-a | -r] [-v [--abbrev=<n> | --no-abbrev]] [--merged | --no-merged] [<pattern>...]
git branch <branch-name> [<start-point>]
git branch (-d | -D) [-r] <branch-name>...
git branch (-m | -M) [<old-branch>] <new-branch>
git branch (-c | -C) [<old-branch>] <new-branch>
git branch [--set-upstream-to=<upstream> | -u <upstream>] [<branch-name>]
[ ] opcional| ou<arg> valor a substituir... repetível--flag opção

Opções

Clique em uma opção para expandir

Iniciante (7)

Listar as branches que correspondem a um ou mais padrões curinga do shell. Sem padrão, lista todas as branches locais. A opção --list é obrigatória para filtrar - senão o Git entende o padrão como o nome de uma branch nova a criar.

RecomendadoNecessário para filtrar por padrão; sem ele, um padrão cria uma branch

Exemplo

git branch --list "feature-*"

Listar tanto as branches de rastreamento remoto quanto as locais. Mostra todas as branches que existem localmente e todas as branches remotas que o seu repositório conhece.

RecomendadoVer juntas as branches locais e de rastreamento remoto depois de um fetch

Exemplo

git branch -a

Listar só as branches de rastreamento remoto. São referências locais (refs/remotes/...) que representam o estado das branches nos repositórios remotos no momento do último fetch.

Quando necessárioLista só as branches de rastreamento remoto; rode git fetch antes

Exemplo

git branch -r

Excluir uma branch. A branch precisa estar totalmente mesclada no upstream dela, ou no HEAD se nenhum upstream foi definido. É uma exclusão segura que protege você contra perder trabalho.

RecomendadoFaxina segura: recusa se a branch tiver trabalho não mesclado

Exemplo

git branch -d feature-complete

Mover/renomear uma branch junto com a configuração e o reflog dela. Se você está na branch, pode omitir o nome antigo.

RecomendadoRenomeia uma branch e mantém o reflog dela; falha com segurança se o nome já existir

Exemplo

git branch -m old-name new-name

Mostrar o hash e o assunto de cada branch, e quanto ela está à frente ou atrás do upstream. Use -vv para mostrar também o nome da branch upstream (e o caminho de um worktree vinculado).

RecomendadoO -vv mostra de relance o upstream e as contagens à frente/atrás

Exemplo

git branch -v

Mostrar o nome da branch atual. Em HEAD desanexado, nada é mostrado. Saída limpa, perfeita para scripts e automação.

Quando necessárioImprime só o nome da branch; útil em scripts e prompts

Exemplo

git branch --show-current

Intermediário (10)

Forçar a exclusão de uma branch mesmo com mudanças não mescladas. Atalho para --delete --force. Use com cuidado, pois commits podem ficar inalcançáveis.

Não recomendadoExclui trabalho não mesclado — só quando você tiver certeza de que os commits podem ser descartados

Exemplo

git branch -D abandoned-feature

Forçar a renomeação de uma branch, sobrescrevendo o destino se já existir. Atalho para --move --force. A branch sobrescrita se perde.

Não recomendadoSobrescreve sem aviso uma branch existente; use -m, a menos que queira substituí-la de propósito

Exemplo

git branch -M main master

Copiar uma branch junto com a configuração e o reflog dela. Cria uma branch nova no mesmo commit da original. A branch original é mantida (ao contrário de --move).

Quando necessárioDuplica uma branch com a configuração dela; raramente útil no dia a dia

Exemplo

git branch -c feature feature-backup

Listar as branches cuja ponta é alcançável a partir do commit indicado (HEAD, se nenhum for indicado). Essas branches já foram totalmente incorporadas e podem ser excluídas com segurança com -d.

RecomendadoMostra branches totalmente mescladas, que podem ser excluídas com segurança

Exemplo

git branch --merged main

Listar só as branches cuja ponta NÃO é alcançável a partir do commit indicado (HEAD, se nenhum for indicado). Essas branches têm trabalho ainda não integrado e pedem atenção antes de serem excluídas.

Quando necessárioMostra branches com trabalho ainda não integrado

Exemplo

git branch --no-merged

Configurar a relação de rastreamento entre uma branch local e uma branch remota. Assim, git pull/push funcionam sem indicar o remoto e o nome da branch.

RecomendadoVincula uma branch ao remoto para pull e push simples funcionarem

Exemplo

git branch -u origin/main

Remover as informações de rastreamento do upstream de uma branch. Depois disso, git pull e git push vão exigir o remoto e a branch explicitamente.

Quando necessárioRemove o vínculo de rastreamento, por ex. depois que a branch remota sumiu

Exemplo

git branch --unset-upstream

Criar uma branch local nova que rastreia uma branch remota. A branch nova terá o upstream configurado automaticamente para git pull/push.

Quando necessárioDefine o upstream na criação; já é o padrão a partir de uma branch remota

Exemplo

git branch --track feature origin/feature

Listar só as branches cujo commit da ponta descende do commit indicado (o contém). Útil para saber quais branches têm uma correção ou funcionalidade específica. Usa o HEAD se nenhum commit for indicado.

Quando necessárioDescobre quais branches já incluem uma correção ou um commit

Exemplo

git branch --contains a1b2c3d

Ordenar as branches pela chave indicada. Use o prefixo - para ordem decrescente. Chaves comuns: committerdate, authordate, refname.

Quando necessário--sort=-committerdate mostra primeiro as branches com atividade recente

Exemplo

git branch --sort=-committerdate

Escolhendo a opção certa

Ver branches

Jeitos diferentes de listar e inspecionar branches

ComandoMostra locaisMostra remotasInformação extraCaso de uso
git branchSimNoBranch atual marcada com *Olhada rápida nas branches locais
git branch -rNoSimRefs de rastreamento remotoVer o que há no servidor
git branch -aSimSimTodas as refsVisão completa de todas as branches
git branch -vSimNoÚltimo commit de cada branchVer a atividade das branches de relance
git branch -vvSimNoUpstream + à frente/atrásConferir a sincronização com o remoto
git branch --show-currentSó a atualNoSó o nomeScripts, prompts do shell

Excluir branches

Exclusão segura ou forçada - saiba a diferença

ComandoExige mergePode perder trabalhoQuando usar
-d (--delete)SimNoDepois do merge do PR, limpeza de rotina
-D (--delete --force)NoSimAbandonar trabalho experimental

Renomear e copiar branches

Opções para reorganizar os nomes das suas branches

ComandoSobrescreve a existenteMantém a originalUso típico
-m (--move)Não (falha)NoRenomear: feature → feature-v2
-M (--move --force)SimNoSubstituir um nome de branch existente
-c (--copy)Não (falha)SimDuplicar uma branch para experimentar
-C (--copy --force)SimSimCopiar, sobrescrevendo se existir

Filtrar branches pelo status de merge

Achar branches prontas para excluir ou ainda em andamento

ComandoMostraPropósitoPasso seguinte comum
--mergedBranches mescladas no HEADAchar candidatas à limpezagit branch -d <branch>
--merged mainBranches mescladas na mainEncontrar branches que podem ser excluídas com segurançaExcluir em massa as branches mescladas
--no-mergedBranches NÃO mescladasAchar trabalho em andamentoRevisar antes de uma release
--contains <commit>Branches que contêm um commitDescobrir para onde foi uma correçãoConferir o deploy de um hotfix

Rastreamento do upstream

Configurar a relação entre branches locais e remotas

ComandoAçãoEfeitoQuando usar
-u origin/mainDefinir o upstreamgit push/pull funcionam sem argumentosDepois de criar uma branch local
--track origin/featureCriar + definir o upstreamBranch local nova rastreando uma remotaComeçar a trabalhar em uma branch remota
--unset-upstreamRemover o upstreamDesconectar do remotoParar de rastrear uma branch remota excluída

Exemplos de fluxos de trabalho

1
git branch feature-login

Criar uma branch nova para a funcionalidade

2
git switch feature-login

Trocar para a branch nova

3
(make changes and commits)

Trabalhar na funcionalidade com vários commits

4
git switch main && git merge feature-login

Mesclar a funcionalidade pronta de volta na main

5
git branch -d feature-login

Excluir a branch da funcionalidade depois do merge

1
git branch --merged

Listar as branches já mescladas

2
git branch -d branch-name

Excluir com segurança as branches mescladas, uma a uma

3
git fetch --prune

Remover referências de rastreamento remoto obsoletas

4
git branch -r

Conferir que as branches remotas estão limpas

1
git fetch origin

Buscar as informações mais recentes das branches remotas

2
git branch -r

Listar as branches remotas disponíveis

3
git branch --track feature origin/feature

Criar uma branch local rastreando a remota

4
git switch feature

Trocar para a nova branch de rastreamento

1
git branch -m old-name new-name

Renomear a branch local

2
git push origin -u new-name

Enviar o nome novo da branch para o remoto

3
git push origin --delete old-name

Excluir o nome antigo da branch do remoto

1
git log --oneline -1

Pegar o hash do commit que você procura

2
git branch --contains <commit-hash>

Achar branches locais com este commit

3
git branch -r --contains <commit-hash>

Achar branches remotas com este commit

Solução de problemas

Não é possível excluir a branch - não totalmente mesclada

Causa: A branch tem commits não mesclados no upstream dela (ou no HEAD, se não tiver upstream)

Mescle a branch primeiro, ou use -D para forçar a exclusão se tiver certeza de que quer descartar o trabalho

git branch -D branch-name

Não é possível excluir a branch atual

Causa: Você está tentando excluir a branch em que está

Troque antes para outra branch e depois exclua a branch desejada

git switch main && git branch -d old-branch

Esse nome de branch já existe

Causa: Você está tentando criar uma branch com um nome que já existe

Escolha outro nome, exclua antes a branch existente ou use -f para movê-la para um novo ponto de partida

git branch -f existing-name <start-point>

Nenhum upstream configurado para o push

Causa: A branch local não tem relação de rastreamento com uma branch remota

Configure a relação de rastreamento com o upstream

git push -u origin branch-name

A branch remota não aparece em git branch -r

Causa: O repositório local não tem as informações mais recentes das branches remotas

Faça fetch do remoto para atualizar as suas branches de rastreamento remoto

git fetch origin

HEAD desanexado (detached) depois do checkout

Causa: Você fez checkout de um commit diretamente em vez de uma branch

Crie uma branch nova no commit atual ou volte para uma branch existente

git switch -c new-branch-name

A branch rastreia o remoto errado

Causa: O upstream está configurado para rastrear uma branch remota incorreta

Redefina o rastreamento do upstream para a branch remota correta

git branch -u origin/correct-branch

Não aparecem todas as branches

Causa: Por padrão, só as branches locais são mostradas

Use a opção -a para mostrar tanto as branches locais quanto as de rastreamento remoto

git branch -a

Dicas e armadilhas

Boas práticas

  • ✓Use nomes de branch descritivos que indiquem o propósito: feature/user-auth, bugfix/login-error, hotfix/security-patch
  • ✓Exclua branches depois do merge para manter o repositório limpo - use 'git branch --merged' para achar as que podem ser excluídas com segurança
  • ✓Sempre crie branches de funcionalidade a partir de uma main atualizada para diminuir conflitos de merge
  • ✓Use 'git branch -vv' para ver as relações de rastreamento e quanto está à frente/atrás
  • ✓Configure o rastreamento ao criar branches com 'git push -u origin branch-name' para facilitar push/pull
  • ✓Evite trabalhar direto na main/master - sempre crie uma branch para as mudanças
  • ✓Use 'git branch --no-merged' para achar branches com trabalho ainda em andamento
  • ✓Sincronize as branches remotas com frequência com 'git fetch --prune' para remover referências obsoletas
  • ✓Considere usar 'git switch' em vez de 'git checkout' para deixar a intenção mais clara ao trocar de branch
  • ✓Use '--sort=-committerdate' para ver primeiro as branches com atividade mais recente
  • ✓Antes de excluir uma branch com -D, confirme com 'git log branch-name' que você não precisa mais dela
  • ✓Mantenha os nomes de branch em minúsculas e com hifens, por consistência e compatibilidade

Erros comuns

  • ✗Esperar que 'git branch <name>' troque para a branch nova. Ele só cria a branch - use 'git switch <name>' ou 'git checkout -b <name>' para criar e trocar.
  • ✗Tentar excluir a branch atual. Você precisa trocar para outra branch antes de excluir aquela em que está.
  • ✗Usar -d em branches não mescladas e perder trabalho. O -d protege você - se quiser mesmo excluir trabalho não mesclado, use -D.
  • ✗Esquecer de enviar branches novas para o remoto. Branches locais não são compartilhadas até você rodar 'git push -u origin <branch>'.
  • ✗Não limpar branches antigas. Use com frequência 'git branch --merged' para achar e excluir branches já mescladas.

Perguntas frequentes

A:

'git branch <name>' só cria uma branch nova, sem trocar para ela. 'git checkout -b <name>' cria uma branch nova E troca para ela em um só comando. O equivalente moderno é 'git switch -c <name>'.

A:

Use 'git branch -m old-name new-name' para renomear uma branch. Se você está na branch que quer renomear, basta 'git branch -m new-name'. Para branches remotas, você precisa enviar o nome novo e excluir o antigo.

A:

-d é uma exclusão segura que só funciona se a branch estiver totalmente mesclada no upstream dela (ou no HEAD, se não houver upstream). -D é uma exclusão forçada que remove a branch seja qual for o status de merge. Só use -D quando tiver certeza de que quer descartar commits não mesclados.

A:

Use 'git push origin --delete branch-name' ou a sintaxe mais curta 'git push origin :branch-name'. Isso remove a branch do repositório remoto.

A:

Branches de rastreamento remoto (como origin/main) são referências locais que acompanham o estado das branches nos repositórios remotos. Elas são atualizadas no fetch ou no pull e mostram para onde as branches remotas apontam.

A:

Use 'git branch --show-current' para ver só o nome, ou 'git branch' para ver todas as branches com a atual marcada com *. O 'git status' também mostra a branch atual.

A:

O Git não permite excluir a branch em que você está. Troque antes para outra branch com 'git switch other-branch' e depois exclua a branch desejada.

A:

Use 'git branch branch-name commit-hash' para criar uma branch a partir de qualquer commit. O ponto de partida pode ser um hash de commit, uma tag ou outro nome de branch.

A:

A branch upstream (ou de rastreamento) é a branch remota para a qual a sua branch local envia e da qual puxa por padrão. Defina-a com 'git branch -u origin/branch-name' ou 'git push -u origin branch-name'.

A:

Use 'git branch --sort=-committerdate' para listar primeiro as branches com os commits mais recentes. Adicione -v para ver também o hash e a mensagem do commit.