git pull

Compartilhar e atualizar

Buscar de outro repositório ou de uma branch local e integrar

O comando 'git pull' busca o conteúdo de um repositório remoto e o integra imediatamente na sua branch local. É basicamente 'git fetch' seguido de 'git merge' (ou de 'git rebase' com a opção --rebase). É o jeito mais comum de sincronizar o seu repositório local com as mudanças dos outros. Quando você roda git pull, o Git primeiro baixa todos os commits novos do remoto e depois os integra na branch atual. Se a sua branch só está atrás, ele faz fast-forward; se os dois lados têm commits novos, o Git moderno para e pede que você escolha entre merge e rebase (--no-rebase / --rebase, ou a configuração pull.rebase). Se houver mudanças em conflito, o Git para e pede que você resolva os conflitos antes de concluir o merge.

Sinopse

git pull [--rebase | --no-rebase] [--ff-only | --ff | --no-ff] [--commit | --no-commit] [--autostash | --no-autostash] [-q | --quiet] [-v | --verbose] [--depth=<depth>] [--prune] [--tags | --no-tags] [--recurse-submodules[=yes|on-demand|no]] [<repository> [<refspec>...]]
[ ] opcional| ou<arg> valor a substituir... repetível--flag opção

Opções

Clique em uma opção para expandir

Iniciante (7)

O nome do remoto padrão. Quando você clona um repositório, o Git chama o remoto de 'origin' automaticamente. Você pode fazer pull do origin indicando-o explicitamente ou contar com a configuração de rastreamento padrão.

Quando necessárioIndica explicitamente o remoto e a branch; o git pull simples usa o upstream

Exemplo

git pull origin main

Depois do fetch, fazer rebase da branch atual sobre a branch upstream. Isso cria um histórico linear reaplicando os seus commits locais em cima dos commits baixados, sem commits de merge.

RecomendadoReaplica por cima os seus commits não enviados, mantendo o histórico linear

Exemplo

git pull --rebase origin main

Atalho para --rebase=false. Anula qualquer configuração que faça rebase por padrão e força um merge em vez de rebase ao integrar as mudanças baixadas. Cria um commit de merge se os históricos divergiram.

Quando necessárioMescla explicitamente quando as branches divergiram ou a configuração usa rebase por padrão

Exemplo

git pull --no-rebase origin main

Só atualizar se a branch local puder avançar por fast-forward (sem commits locais à frente do remoto). Falha se os históricos divergiram, evitando merges acidentais e fazendo você decidir como integrar.

RecomendadoNunca cria merges inesperados; para para você escolher quando as branches divergem

Exemplo

git pull --ff-only origin main

Modo detalhado. Mostra informações detalhadas do fetch e do merge, incluindo quais refs estão sendo atualizadas e estatísticas de transferência de objetos.

Quando necessárioPara depurar o que o fetch e o merge estão fazendo

Exemplo

git pull -v origin main

Silenciar a saída durante o fetch e o merge. Só os erros aparecem. Útil em scripts que devem rodar em silêncio.

Quando necessárioPara scripts; esconde o progresso e a saída do merge

Exemplo

git pull -q origin main

Guardar automaticamente as modificações locais antes do pull e reaplicá-las ao final (funciona com pulls por merge e por rebase; se a reaplicação der conflito, as suas mudanças ficam seguras no stash). Perfeito quando você tem mudanças sem commit, mas precisa sincronizar com o remoto.

Quando necessárioPrático com trabalho sem commit; um conflito ao reaplicar o deixa no stash

Exemplo

git pull --rebase --autostash origin main

Intermediário (6)

Fazer o merge, mas parar antes de criar o commit de merge. Permite inspecionar e, se quiser, modificar o resultado antes do commit.

Quando necessárioPara antes do commit de merge para você conferir o resultado

Exemplo

git pull --no-commit origin main

Antes do fetch, remover as refs de rastreamento remoto que não existem mais no remoto. Ajuda a manter o repositório local livre de branches obsoletas. Só poda quando os refspecs configurados do remoto são usados - 'git pull --prune origin main' não poda nada.

Quando necessárioLimpa refs de rastreamento remoto desatualizadas; não faz nada com um refspec explícito

Exemplo

git pull --prune

Buscar todas as tags do remoto, além do que normalmente seria buscado. Útil para sincronizar tags de release.

Quando necessárioTambém busca tags fora do histórico puxado; raramente necessário

Exemplo

git pull --tags origin main

Desativar o acompanhamento automático de tags: por padrão, as tags que apontam para os commits baixados também são buscadas. Anula a configuração remote.<name>.tagOpt. Útil quando você só quer atualizar branches.

Quando necessárioPula o acompanhamento automático de tags para atualizar só branches

Exemplo

git pull --no-tags origin main

Limitar a busca ao número de commits indicado a partir da ponta do histórico de cada branch remota. Cria ou aprofunda um clone raso. Útil em repositórios grandes.

Quando necessárioMantém raso um clone raso (CI); comandos baseados em histórico enxergam menos

Exemplo

git pull --depth=1 origin main

Buscar de todos os remotos. Em vez de um único remoto, busca de todos os configurados antes do merge.

Quando necessárioBusca de todos os remotos, mas mescla só o upstream atual

Exemplo

git pull --all

Avançado (4)

Controlar se os submódulos são buscados e atualizados recursivamente. Valores: 'yes' (sempre), 'on-demand' (quando o superprojeto atualiza a ref do submódulo), 'no' (nunca).

Quando necessárioSó em repositórios com submódulos, para mantê-los sincronizados

Exemplo

git pull --recurse-submodules=on-demand origin main

Converter um repositório raso em completo, buscando todo o histórico que falta. Só é válido ao fazer pull em um clone raso.

Quando necessárioTransforma um clone raso em completo quando você precisa de todo o histórico

Exemplo

git pull --unshallow origin main

Usar a estratégia de merge indicada. Estratégias comuns: ort (a padrão), resolve, octopus, ours, subtree. recursive ainda é aceito, mas desde o Git 2.50 é só um sinônimo de ort.

Quando necessárioRaramente necessário; a estratégia ort padrão serve para quase todo pull

Exemplo

git pull -s ort origin main

Permitir mesclar históricos sem ancestral comum. Necessário para juntar dois repositórios criados de forma independente.

Não recomendadoSó para unir repositórios separados de propósito; senão, esconde um erro

Exemplo

git pull --allow-unrelated-histories origin main

Escolhendo a opção certa

Estratégia de pull: merge ou rebase

A escolha fundamental que afeta o seu histórico de commits

ComandoCria commit de mergeEstilo de históricoIdeal para
git pullDepende da configuração (falha se divergiu e não há configuração)Definido por pull.rebase / pull.ffFast-forward quando só está atrás
git pull --rebaseNoLinearBranches de funcionalidade, histórico limpo
git pull --no-rebaseSim (se divergiu)Preserva as branchesAnular a configuração de rebase e forçar merge
git pull --ff-onlyNoLinear (falha se divergiu)Garantir que não haja merges acidentais

Opções de segurança e controle

Opções para evitar erros e manter o controle

ComandoEvitaComportamentoQuando usar
--ff-onlyMerges inesperadosFalha se não puder fazer fast-forwardCI/CD, branches protegidas
--no-commitCommit automáticoMescla, mas para antes do commitRevisar o merge antes do commit
--autostashErros de diretório de trabalho com mudançasStash → pull → popSincronização rápida com trabalho sem commit
--dry-runQuaisquer mudançasMostra o que o fetch baixaria; sem mergePré-visualizar refs que chegam

O que é baixado

Controlar quais refs e quanto histórico são baixados

ComandoBusca tagsBaixa o histórico completoCaso de uso
git pullAuto (tags seguidas)SimFluxo normal
--tagsTodas as tagsSimSincronizar versões lançadas
--no-tagsNoSimEconomizar banda, sincronizar só a branch
--depth=NAuto (tags seguidas)Só os N últimos commitsRepositórios grandes, builds de CI
--unshallowAuto (tags seguidas)Converte raso em completoPrecisa do histórico completo depois de um clone raso

Gerenciamento de remotos e branches

Opções para lidar com vários remotos e refs obsoletas

ComandoAlcanceLimpaCenário
git pull origin mainUm só remoto/branchNoPull padrão do origin
--allTodos os remotosNoSincronizar a partir de origin + upstream
--pruneUm só remotoBranches excluídasRemover refs de rastreamento obsoletas

Cenários avançados

Opções para situações complexas ou incomuns

ComandoResolveNível de riscoCenário típico
--allow-unrelated-historiesSem ancestral comumMédioMesclar dois repositórios separados
-s <strategy>Necessidades especiais de merge (não evita conflitos)BaixoForçar um algoritmo de merge específico
--recurse-submodulesSubmódulos desatualizadosBaixoProjetos com submódulos do git

Exemplos de fluxos de trabalho

1
git status

Verificar mudanças sem commit que podem conflitar

2
git stash

Guardar com stash o trabalho sem commit se precisar (ou usar --autostash)

3
git pull --rebase origin main

Fazer pull com rebase para manter o histórico limpo

4
git stash pop

Restaurar o trabalho guardado, se tiver guardado antes

1
git checkout feature-branch

Trocar para a sua branch de funcionalidade

2
git pull --no-rebase origin main

Mesclar a main mais recente na sua branch de funcionalidade (explicitamente, já que as branches divergiram)

3
git push origin feature-branch

Enviar a branch de funcionalidade atualizada

1
git fetch origin

Baixar as mudanças remotas sem mexer no diretório de trabalho

2
git log HEAD..origin/main

Ver quais commits você vai puxar

3
git diff HEAD...origin/main

Revisar as mudanças feitas no remoto

4
git pull origin main

Fazer o pull quando estiver satisfeito com as mudanças

1
git pull --no-rebase origin main

Tentar um pull com merge - pode gerar conflitos

2
git status

Ver quais arquivos têm conflitos (marcados como 'both modified')

3
(edit conflicted files)

Abrir os arquivos e resolver os marcadores de conflito (<<<<<<<, =======, >>>>>>>)

4
git add <resolved-files>

Preparar os arquivos resolvidos

5
git commit

Concluir o merge com um commit

1
git pull --rebase --autostash origin main

Guardar as mudanças automaticamente, fazer pull e reaplicá-las

Solução de problemas

Your local changes would be overwritten by merge

Causa: Você tem mudanças sem commit em arquivos que o pull modificaria

Faça commit das mudanças antes (git add . && git commit), guarde-as com stash (git stash) ou use git pull --rebase --autostash

git stash && git pull && git stash pop

Refusing to merge unrelated histories

Causa: Os repositórios remoto e local não têm ancestral comum (por ex., ao fazer pull em um repositório recém-iniciado)

Permitir o merge de históricos sem relação, algo comum ao adicionar um remoto a um repositório local existente

git pull --allow-unrelated-histories origin main

Conflito de merge em arquivo(s)

Causa: Você e o remoto mudaram as mesmas linhas de um arquivo

Abra os arquivos em conflito, procure os marcadores (<<<<<<<, =======, >>>>>>>), edite para resolver, depois git add e git commit. Ou cancele com git merge --abort

git add <resolved-file> && git commit

Not possible to fast-forward, aborting

Causa: Você usou --ff-only (ou pull.ff=only está configurado), mas a sua branch local divergiu do remoto

Use rebase em vez disso (git pull --rebase) ou permita um commit de merge (git pull --no-rebase)

git pull --rebase origin main

Cannot pull with rebase: You have unstaged changes

Causa: Um pull com rebase precisa de uma árvore de trabalho limpa, e você tem modificações sem commit

Faça commit ou stash das mudanças, ou use autostash para cuidar delas automaticamente

git pull --rebase --autostash

No tracking information for the current branch

Causa: A sua branch não está configurada para rastrear uma branch remota

Defina a branch upstream explicitamente, ou indique o remoto e a branch no comando pull

git branch --set-upstream-to=origin/main main

'origin' does not appear to be a git repository

Causa: Nenhum remoto chamado 'origin' está configurado

Confira os remotos com git remote -v e adicione o origin ou use o nome de remoto certo

git remote add origin <url>

You have divergent branches and need to specify how to reconcile them

Causa: Os dois lados têm commits novos e nem pull.rebase nem pull.ff estão configurados, então o Git moderno se recusa a adivinhar (versões 2.27+ mais antigas só avisavam)

Indique merge (--no-rebase) ou rebase (--rebase), ou configure um padrão com git config pull.rebase

git config --global pull.rebase true

Dicas e armadilhas

Boas práticas

  • ✓Sempre confira o git status antes do pull para evitar conflitos com mudanças sem commit
  • ✓Use git pull --rebase para manter um histórico limpo e linear em branches de funcionalidade
  • ✓Configure pull.rebase=true globalmente se preferir rebase por padrão: git config --global pull.rebase true
  • ✓Use git fetch primeiro quando quiser revisar as mudanças antes de integrá-las
  • ✓Use --ff-only quando quiser garantir que nenhum commit de merge seja criado sem querer
  • ✓Configure o rastreamento com git push -u no primeiro push para simplificar os próximos pulls
  • ✓Use --autostash quando tiver mudanças sem commit, mas precisar fazer pull rápido
  • ✓Faça pull da main/master com frequência para evitar merges grandes e complexos depois
  • ✓Resolva os conflitos na hora - nunca deixe o repositório em estado de conflito
  • ✓Use git pull --prune para limpar branches de rastreamento remoto obsoletas
  • ✓Considere usar git fetch + git merge para ter mais controle sobre a integração
  • ✓Sempre confira se está na branch certa antes do pull para não misturar mudanças

Erros comuns

  • ✗Fazer pull com mudanças sem commit: isso pode causar conflitos ou falhar de vez. Sempre faça commit ou stash antes, ou use --autostash para cuidar disso automaticamente.
  • ✗Não entender pull e fetch: 'git pull' mescla automaticamente, o que pode surpreender. Use 'git fetch' antes se quiser revisar as mudanças antes de integrá-las.
  • ✗Usar merge quando o rebase seria mais limpo: em branches de funcionalidade, 'git pull --rebase' cria um histórico linear mais limpo, sem commits de merge desnecessários.
  • ✗Ignorar conflitos de merge: depois de um pull com conflitos, você precisa resolvê-los e fazer commit. Nunca deixe o repositório em estado de conflito.
  • ✗Fazer pull na branch errada: sempre confira a branch atual com 'git status' antes do pull. Puxar para a main quando queria puxar para uma branch de funcionalidade pode causar problemas.

Perguntas frequentes

A:

O git fetch só baixa os commits novos do remoto, sem modificar o seu diretório de trabalho nem as suas branches locais. O git pull faz o fetch E mescla (ou faz rebase) automaticamente essas mudanças na sua branch atual. Use fetch quando quiser revisar as mudanças antes de integrá-las.

A:

Use --rebase quando quiser um histórico limpo e linear (principalmente em branches de funcionalidade). Isso reaplica os seus commits locais em cima dos commits baixados em vez de criar um commit de merge. Use o pull comum (merge) quando quiser preservar exatamente o histórico de quando as mudanças foram feitas.

A:

O fast-forward acontece quando a sua branch local não tem commits novos que o remoto não tenha. O Git só avança o ponteiro da branch até o remoto - nenhum commit de merge é necessário. Se você tem commits locais, o Git precisa criar um commit de merge ou fazer rebase - e, a menos que você passe --rebase/--no-rebase ou configure pull.rebase, o Git moderno para com “Need to specify how to reconcile divergent branches”.

A:

Use git pull --rebase para reaplicar os seus commits locais em cima dos commits remotos, criando um histórico linear. Ou use git pull --ff-only, que só funciona se um fast-forward for possível (falha se você tiver commits locais à frente).

A:

Depende. Com um pull por merge, o Git permite se os commits que chegam não mexem nos arquivos que você modificou; senão ele recusa com “Your local changes ... would be overwritten by merge”. Com --rebase, qualquer mudança sem commit bloqueia o pull. Boa prática: faça commit antes, ou use git pull --rebase --autostash para guardar e restaurar as suas mudanças automaticamente.

A:

O Git pausa o merge e marca os arquivos em conflito. Abra cada um, procure os marcadores de conflito (<<<<<<<, =======, >>>>>>>), edite para resolver, depois git add no arquivo e git commit para concluir o merge. Use git merge --abort para cancelar (ou, no git pull --rebase, git rebase --continue / git rebase --abort).

A:

Logo depois do pull, rode git reset --hard ORIG_HEAD - o Git guarda a ponta anterior em ORIG_HEAD em merges, fast-forwards e rebases. Não use HEAD~1: um fast-forward pode ter trazido vários commits. O --hard também descarta mudanças sem commit. Se o ORIG_HEAD já mudou, encontre a ponta antiga com git reflog.

A:

Normalmente significa que você está puxando da branch ou do remoto errado. Confira: git branch -vv para ver as informações de rastreamento, git remote -v para verificar os remotos, e git fetch --all seguido de git log origin/main para ver os commits remotos.

A:

git pull origin main indica explicitamente o remoto e a branch de onde puxar. git pull (sem argumentos) usa a branch de rastreamento configurada para a sua branch atual. Se o rastreamento não estiver configurado, aparece um erro pedindo que você os indique.

A:

Globalmente: git config --global pull.rebase true (para rebase) ou git config --global pull.rebase false (para merge). Também dá para definir por repositório sem --global, ou por branch com git config branch.<name>.rebase true.