HOWTO · Git

Buscar Branch Remoto no Git

Este tutorial demonstra como buscar um branch remoto no Git usando diferentes comandos.

Nesta página

Buscar um branch remoto atualiza as referências de acompanhamento remoto no repositório local; não mescla alterações ao branch atual nem modifica os arquivos da árvore de trabalho. Use git fetch quando quiser inspecionar outro branch antes de decidir se vai trabalhar nele ou integrar suas alterações.

Nos comandos abaixo, substitua origin pelo nome do remoto e topic pelo nome do branch. origin/topic é uma referência de acompanhamento remoto: ela registra o último estado buscado desse branch. Ela não é, por si só, um branch local no qual você possa fazer commits.

Como git fetch atualiza referências de acompanhamento remoto

Um remoto é uma conexão nomeada com outro repositório. Ao clonar, normalmente são configurados origin e um refspec de busca que mapeia os branches desse remoto para referências como refs/remotes/origin/main. Quando uma busca é concluída, Git atualiza as referências abrangidas pela solicitação e registra o commit buscado em FETCH_HEAD. O branch em uso e a árvore de trabalho permanecem como estavam.

Buscar é útil antes de revisar o trabalho de alguém da equipe, comparar commits ou decidir se vai fazer merge ou rebase. É seguro buscar mesmo quando há alterações locais: a busca não sobrescreve esses arquivos da árvore de trabalho.

Buscar um branch remoto específico

Para buscar um branch nomeado de um remoto, execute git fetch origin topic. Isso solicita a Git que busque topic em origin. Para ver os branches de acompanhamento remoto disponíveis localmente, execute git branch -r.

Procure origin/topic na lista. Ela mostra as referências já buscadas para este repositório; não necessariamente lista em tempo real todos os branches que existem no servidor. Para inspecionar os commits do branch buscado, compare-o com o branch atual usando git log --oneline HEAD..origin/topic. Os commits exibidos podem ser alcançados a partir de origin/topic, mas não de HEAD.

Se o nome do branch não aparecer, confira a grafia e o remoto com git remote -v e tente buscá-lo novamente. O refspec de busca de um remoto controla quais referências de acompanhamento remoto são atualizadas. A busca ainda pode registrar o commit solicitado em FETCH_HEAD, mesmo que um refspec personalizado não crie a referência origin/topic esperada.

Criar um branch local que acompanhe o remoto

Quando estiver pronto para trabalhar no branch buscado, crie um branch local que acompanhe a referência de acompanhamento remoto. Se o branch local e o remoto devem ter o nome topic, use git switch --track origin/topic. Git cria e muda para um branch local topic, configurado para acompanhar origin/topic. Se quiser usar outro nome local, especifique-o com git switch --track -c my-topic origin/topic.

Essa relação de acompanhamento permite que comandos como git status informem se o branch local está à frente ou atrás de seu upstream. Ela também define um upstream padrão para comandos posteriores de git pull e git push. O nome do branch local precisa estar disponível; se ele já existir, mude para esse branch em vez de tentar criá-lo novamente.

Execute este exemplo autossuficiente para criar um remoto local e buscar o branch topic:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

set -eu
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
git init -q "$work/source"
git -C "$work/source" config user.name Example
git -C "$work/source" config user.email example@example.com
git -C "$work/source" checkout -q -b topic
printf 'hello
' > "$work/source/README.md"
git -C "$work/source" add README.md
git -C "$work/source" commit -q -m initial
git init -q --bare "$work/remote.git"
git -C "$work/source" remote add origin "$work/remote.git"
git -C "$work/source" push -q -u origin topic
git init -q "$work/consumer"
git -C "$work/consumer" remote add origin "$work/remote.git"
git -C "$work/consumer" fetch -q origin topic
git -C "$work/consumer" branch -r
  origin/topic

Buscar todos os remotos ou branches

Sem um argumento de branch, git fetch busca de acordo com o refspec configurado para o remoto selecionado, normalmente origin. Esse refspec costuma abranger todos os branches desse remoto, mas a configuração pode restringir ou alterar o conjunto. Para buscar de todos os remotos configurados, use git fetch --all.

--all significa todos os remotos; não substitui o refspec de cada remoto para buscar todos os branches possíveis. Se também precisar de tags que não possam ser alcançadas pelos branches buscados, considere usar git fetch --all --tags. Inspecione as referências atualizadas com git branch -r. Nenhum dos comandos muda para outro branch nem grava versões dos arquivos buscados na árvore de trabalho.

Escolher entre git fetch e git pull

Use git fetch quando quiser atualizar referências de acompanhamento remoto e inspecionar os commits recebidos antes de integrá-los. Use git pull quando a intenção for buscar e integrar alterações ao branch atual. Em geral, pull usa o upstream configurado para o branch atual, e a integração segue o comportamento de pull configurado, normalmente merge ou rebase.

Por exemplo, git pull origin topic busca de origin e integra topic ao branch em uso. O comando não muda para um branch local chamado topic. A integração pode gerar conflitos quando as alterações se sobrepõem ao trabalho local; se quiser revisar primeiro, busque e inspecione origin/topic e depois escolha explicitamente entre merge e rebase.