Ramos da lista Git: Um guia prático

Se você já trabalhou em mais de um recurso ao mesmo tempo, essa situação pode parecer familiar: você executa um comando Git e agora não tem mais certeza de onde está o seu trabalho da semana passada.

Esse problema fica mais comum conforme os projetos crescem. No começo, um repositório pode ter só um branch main. Com o tempo, porém, as equipes criam ramificações para novos recursos, correções de bugs, experimentos, lançamentos e hotfixes de emergência. 

É aqui que listar ramificações no Git se torna essencial. Ajuda a responder a perguntas práticas:

• Em que ramo estou trabalhando agora?
• Que outras ramificações existem na minha máquina?
• Quais branches existem no repositório remoto?

Neste guia, vamos ver o básico sobre listar branches no Git, como fazer isso e como resolver problemas comuns.

Se você nunca usou o Git, recomendo fazer nosso curso Introdução ao Git pra ganhar confiança antes de mergulhar em tópicos mais detalhados sobre gerenciamento de branches.

Entendendo os branches do Git

Antes de começarmos a listá-los, vamos explicar o que são branches do Git. 

Um equívoco comum é achar que os branches do Git são pastas separadas ou cópias completas de uma base de código, mas, na verdade, um branch do Git é só um ponteiro leve para um commit específico.

Você pode pensar nisso como uma linha do tempo paralela, onde você pode criar recursos ou fazer testes isoladamente, sem afetar seu código principal estável. Essa arquitetura torna a criação e a fusão de ramificações incrivelmente rápidas e eficientes.

Fonte: Git

O Git acompanha sua posição atual nessas linhas do tempo usando uma referência especial chamada HEAD, que sempre aponta para o branch em que você está trabalhando no momento. Como os ramos são só ponteiros, a troca de contextos é instantânea e não precisa mexer em arquivos pesados.

Pra saber mais, dá uma olhada no nosso tutorial sobre branches do Git ou consulta nossa folha de dicas do Git.

Como listar branches locais no Git

Com essa base conceitual estabelecida, vamos ver como listar os branches locais no seu repositório.

Uma filial local é uma filial que existe no seu computador. Ele fica na pasta .git do seu repositório e é tipo um ponteiro móvel para uma série de commits. Você pode mudar para um branch local, fazer alterações e criar novos commits nele.

É bom pensar nas filiais locais assim:

• Eles fazem parte da sua cópia do repositório.
• Eles avançam quando você faz novas alterações.
• Eles não são atualizados automaticamente quando outras pessoas enviam código.

Usando o git branch

O comando mais comum e básico pra listar os branches locais é bem simples:

git branch

Quando você usa esse comando sem opções extras, o Git mostra todos os branches locais.

Coisas importantes para lembrar sobre git branch:

• Só mostra as ramificações locais, não as remotas.
• Não se conecta à internet.
• Não altera arquivos, commits ou histórico de ramificações.

Por ser seguro e rápido, muitos desenvolvedores costumam executar o comando ` git branch ` antes de começar um novo trabalho ou mudar de contexto.

Entendendo o resultado

Aqui está um exemplo do que git branch pode mostrar:

 bugfix/login-timeout
  feature/payment-refactor
* main

Mesmo que essa saída pareça simples, tem alguns detalhes importantes escondidos nela.

Primeiro, o asterisco (*) mostra o branch que está sendo usado no momento. Este é o ramo ao qual seu diretório de trabalho está vinculado no momento. Qualquer novo commit que você criar vai para esse branch.

Segundo, o Git geralmente destaca o branch atual em verde. Isso é só uma ajuda visual do terminal e não muda o jeito que o Git funciona.

Terceiro, repara no que não aparece:

• Sem datas de compromisso
• Sem nomes de autores
• Sem informações remotas

Isso é de propósito. O Git mantém a saída padrão curta, então é fácil de ler e juntar com outros comandos.

Dica para iniciantes: Se o seu terminal parecer “travado” depois de executar um comando Git, tente pressionar q. O Git costuma usar um pager para mostrar resultados longos, e essa é uma maneira normal de sair dele.

Pegando só o ramo atual

Às vezes, não precisa listar todos os ramos. Talvez você só queira saber em qual ramo você está agora. O Git tem um comando específico pra isso:

git branch --show-current

A saída é só o nome do branch:

main

Situações comuns em que isso é útil incluem:

• Verificando seu branch antes de enviar o código
• Registrando o nome do branch nos scripts
• Usando o nome da ramificação em automação ou pipelines de CI

Se o Git estiver em um estado HEAD destacado, esse comando não vai mostrar nada. Embora isso possa parecer estranho à primeira vista, na verdade é útil ao escrever scripts que precisam detectar se uma ramificação foi verificada.

Erro comum: Alguns usuários acham que o Git está “com defeito” quando nenhum nome de branch aparece. Na maioria dos casos, isso só quer dizer que você não está em um branch agora, mas em um commit específico.

Como listar ramos remotos e todos os ramos no Git

Listar branches remotos ou até mesmo todos os branches no Git funciona de forma muito parecida com listar os locais.

Listando branches remotos no Git

Repositórios remotos, como os do GitHub ou GitLab, têm seus próprios branches. Para visualizá-los, adicione o sinalizador -r:

git branch -r

  origin/HEAD -> origin/main
  origin/bugfix/login-timeout
  origin/feature/payment-refactor
  origin/main

Esse exemplo de resultado pode ser meio confuso no começo, então vamos dar uma olhada nele.

O que você está vendo aqui são ramificações de rastreamento remoto. São referências locais que o Git usa pra lembrar o último estado conhecido do repositório remoto.

Pontos importantes a entender:

• Esses ramos são guardados localmente.
• Eles só são atualizados quando você faz o fetch.
• Eles não se movem automaticamente.

Dica para iniciantes: Pense nos branches de rastreamento remoto como o caderno do Git. O Git grava como o remoto estava da última vez que você verificou, mas não atualiza esse caderno a menos que você faça explicitamente o fetch.

Listando todos os branches no Git

Para ver os branches locais e os branches de rastreamento remoto juntos, use o sinalizador ` -a `:

git branch -a

* main
  feature/payment-refactor
  remotes/origin/bugfix/login-timeout
  remotes/origin/main

Essa visão combinada ajuda você a entender como suas filiais locais se relacionam com as filiais remotas.

Padrões de nomenclatura a serem observados:

• As filiais locais aparecem como nomes simples, como main

• Os branches de rastreamento remoto aparecem em remotes/origin/

Essa visualização é super útil quando você tá decidindo se vai criar um novo branch local que acompanha um branch remoto que já existe.

Sempre buscar primeiro

Se um colega de equipe enviar um novo branch e você não conseguir vê-lo, o motivo mais comum é que seu cache local está desatualizado. 

A solução é buscar:

git fetch

O que o site git fetch faz:

• Baixa as informações mais recentes do branch do remoto
• Atualiza seus branches de rastreamento remoto
• Deixa seus arquivos de trabalho como estão

Esse comando é seguro para ser executado a qualquer momento. Não junta código nem substitui o seu trabalho. Muitas equipes tratam o comando ` git fetch ` como uma etapa de rotina antes de inspecionar os branches.

Erro comum: Os iniciantes muitas vezes confundem git fetch com git pull. O comando fetch só pega as atualizações das informações do branch, enquanto o pull também junta as mudanças no seu branch atual.

Como ver mais detalhes na sua lista de branches do Git

Às vezes, só o nome da filial não é suficiente. Se você quiser ver mais detalhes, tem alguns indicadores úteis que podem te ajudar.

Vendo os últimos commits

Pra ver o que cada ramo realmente tem, usa:

git branch -v

A saída pode ficar assim:

* main   a1b2c3d Fix typo in README
  feature/payment-refactor e4f5g6h Refactor payment service

Como você pode ver, o sinalizador -v adiciona um contexto importante:

• O hash curto do commit mostra para onde o branch está apontando agora.
• A mensagem de commit dá uma dica sobre o objetivo do branch.

Essa é uma das maneiras mais fáceis de entender para que serve um branch sem precisar fazer check-out.

Dica para iniciantes: Se você não tem certeza se um branch pode ser excluído com segurança, verificar a última mensagem de commit é uma boa primeira pista.

Verificando as conexões upstream

Os ramos locais geralmente acompanham um ramo remoto correspondente. Para ver essa relação, execute:

git branch -vv

* main   a1b2c3d [origin/main] Fix typo in README
  feature/payment-refactor e4f5g6h [origin/feature/payment-refactor] Refactor payment service

Essa saída informa:

• Qual ramo remoto está conectado ao seu ramo local?

• De onde o git pull vai buscar as informações

• Onde o git push vai insistir para

Se um branch não tiver upstream, não vai aparecer nada entre colchetes. Isso geralmente explica os erros de push ou pull.

Erro comum: Tentar executar git pull em um branch sem upstream geralmente não vai funcionar. Nesse caso, você precisa definir primeiro um branch upstream ou enviar o branch pela primeira vez.

Organizando os ramos por data ou versão

Pra achar os branches que estiveram ativos recentemente, dá pra ordenar por data de commit:

git branch --sort=-committerdate

Isso coloca os ramos atualizados mais recentemente no topo e os ramos mais antigos na parte inferior.

Para repositórios com branches versionados, a classificação semântica é mais útil:

git branch --sort=v:refname

Isso respeita os números das versões e evita a confusão da ordem alfabética.

Como filtrar a lista de branches no Git

Se você está procurando um ramo específico, a filtragem pode ser muito útil. Vou te mostrar como fazer isso usando alguns sinalizadores importantes.

Pesquisando por padrão de nome

Principalmente em repositórios grandes, filtrar por nome pode te ajudar a economizar um tempão na hora de achar o branch certo. Você pode filtrar por nome usando o sinalizador --list junto com o termo de pesquisa:

git branch --list 'feature/*'

Observe como o * é usado como um curinga: O resultado aqui mostra só os ramos que combinam com o padrão, ou seja, aqueles que começam com feature. As equipes costumam usar prefixos como feature/, bugfix/ ou hotfix/ para manter tudo organizado. Pense nelas como pastas para suas ramificações.

Encontrando ramificações mescladas e não mescladas

Dois filtros bem importantes são:

git branch --merged
git branch --no-merged

Esses comandos comparam outros branches com o seu branch atual.

• --merged mostra os ramos cujo trabalho já está incluído

• --no-merged mostra os branches que ainda têm commits únicos

Lembrete de segurança: Sempre dá uma conferida se você tá no ramo base certo (geralmente main ou develop) antes de usar --merged. Os resultados dependem do seu ramo atual.

Descobrindo qual branch tem um commit

Se você sabe o hash de um commit e quer descobrir onde ele tá, use esse comando:

git branch --contains <commit-hash>

Isso é útil quando você está rastreando bugs ou verificando se uma correção foi incorporada.

Por exemplo, quando um colega de trabalho te diz isso: Encontrei um bug neste hash de commit; quais branches são afetados por ele? Você pode usar esse comando para localizar com precisão o local exato do bug.

Combinando filtros para fluxos de trabalho avançados

Os filtros que mostrei podem ser combinados para refinar ainda mais os resultados. Vamos ver um exemplo:

git branch --list 'feature/*' --no-merged

Esse comando mostra rapidinho todos os branches feature/ que ainda não foram mesclados e ajuda a equipe a se manter organizada.

Resolução de problemas comuns

Se você tiver problemas, não se preocupe; os mais comuns são bem fáceis de resolver.

Ramos remotos ausentes

Se você não consegue ver um branch que outra pessoa enviou, o motivo mais provável é que você simplesmente esqueceu de fazer o fetch. Para resolver o problema:

1. Correr git fetch

2. Depois, liste os ramos de novo.

Se o problema era a falta de busca, essa solução rápida atualiza sua visualização local na hora.

O estado HEAD destacado

Às vezes, a saída do comando ` git branch ` fica assim:

* (HEAD detached at a1b2c3d)

Isso quer dizer que você não está em um branch. Você está vendo um commit específico diretamente.

Estar em um estado HEAD destacado não é perigoso por si só, mas quaisquer novos commits que você fizer podem ser difíceis de encontrar mais tarde, a menos que você crie um branch.

Para voltar ao trabalho normal, use checkout para criar uma nova ramificação:

git checkout <branch-name>

Você também pode criar uma nova ramificação a partir da sua posição atual usando o sinalizador “ -b ”:

git checkout -b <new-branch-name>

As ramificações ainda aparecem depois de serem apagadas.

Se os branches remotos ainda aparecerem depois de serem excluídos no servidor, você pode limpar a referência local deles usando o seguinte comando:

git remote prune origin

Isso limpa referências obsoletas e mantém seu repositório organizado.

Dica profissional: Como alternativa, você também pode usar git fetch --prune toda vez que fizer um fetch, assim o repositório é atualizado e limpo em uma única etapa.

Conclusão

Listar ramificações no Git é uma habilidade essencial que ajuda você a entender seu repositório. Os comandos e sinalizadores abordados neste tutorial vão te ajudar a evitar erros e trabalhar com confiança com outras pessoas. 

Quando você começa um novo projeto, geralmente vale a pena pensar sobre que tipo de estrutura de ramificação você vai precisar. Pra dar uma olhada em algumas dicas, dá uma olhada nesse guia sobre estratégia de ramificação do Git.

Pronto pra ir além do básico? O programa “Fundamentos do Git” da traz os conceitos e a experiência prática que você precisa pra passar de iniciante a profissional.