Sua branch de funcionalidade está atrás da main e você precisa do trabalho novo. Git merge vs rebase é a escolha entre duas formas de obtê-lo, e ambas estão corretas. Elas diferem em como o histórico fica depois.

Criamos um repositório minúsculo, executamos os dois comandos e colamos a saída real abaixo, para você comparar o resultado em vez de imaginá-lo. Novo no Git? Comece pelo nosso tutorial de Git para iniciantes (em inglês).

O que git merge e git rebase fazem

git merge pega as pontas de duas branches e as combina. Se ambas têm commits novos, o Git cria um commit de merge com dois pais. Nada do que já existe é alterado.

git rebase pega os commits exclusivos da sua branch, deixa-os de lado, move sua branch para a ponta da outra e depois os reaplica um a um. Os commits reaplicados são commits novos com hashes novos, mesmo que as mudanças sejam as mesmas.

Git merge na prática

Nosso ponto de partida: commit A na main, dois commits (F1, F2) na feature e mais um commit (M1) adicionado depois à main. Agora fazemos merge da main na feature.

git switch feature
git merge main
git log --oneline --graph

*   f507aab Merge main into feature
|\
| * 8842fb5 M1
* | 082cc6a F2
* | 5a71e3c F1
|/
* 8766865 A

O gráfico mostra a história real: duas linhas de trabalho que foram unidas. Os commits originais F1 e F2 mantêm seus hashes. O custo é um commit de merge extra e, em um projeto movimentado, o gráfico vira uma teia.

Git rebase na prática

Mesmo ponto de partida, mas desta vez fazemos rebase da feature sobre a main.

git switch feature
git rebase main
git log --oneline --graph

* 1ff474b F2
* bf9149e F1
* 8842fb5 M1
* 8766865 A

O histórico é uma linha reta, como se você tivesse começado depois do M1. Olhe os hashes: F1 era 5a71e3c e agora é bf9149e, e F2 passou de 082cc6a para 1ff474b. O Git os reescreveu, e é por isso que o rebase exige cuidado.

Merge vs rebase lado a lado

A regra de ouro do rebase

Não faça rebase de commits que existem fora do seu próprio repositório. Depois de um rebase, sua branch não corresponde mais à cópia do servidor, então o push exige força. Se um colega construiu trabalho sobre os commits antigos, o histórico dele agora diverge do seu, e resolver isso é doloroso.

Fazer rebase da sua branch privada de funcionalidade é aceitável. Fazer da main ou de qualquer branch usada por outros, não.

Um fluxo de trabalho seguro para equipes

Esta rotina mantém o histórico limpo sem surpreender ninguém. É também o que a maioria das equipes usa antes do pipeline de CI, como o do nosso guia de GitHub Actions CI/CD (em inglês).

git switch feature
git fetch origin
git rebase origin/main        # or: git pull --rebase
# fix conflicts, then: git add <file> && git rebase --continue
git push --force-with-lease   # only on your own branch

--force-with-lease se recusa a sobrescrever a branch do servidor se alguém tiver feito push desde o seu último fetch, o que um --force simples destruiria em silêncio. Quando o pull request for aprovado, faça merge dele na main.

Como desfazer um rebase ruim

Um rebase parece destrutivo, mas os commits antigos ficam por um tempo no reflog do Git, então você pode voltar atrás.

git reflog                    # find the commit before the rebase
git reset --hard HEAD@{5}     # example position, check reflog first

Crie uma branch de backup com git branch backup antes de qualquer rebase arriscado e a recuperação vira um único comando. Rodando um banco de dados ou ferramentas em contêineres? Veja nosso tutorial de Docker para iniciantes (em inglês).

Considerações finais

Merge preserva a verdade, rebase a mantém organizada. Use rebase para atualizar sua própria branch, merge para entregá-la e nunca reescreva um histórico do qual outras pessoas dependem.

Perguntas frequentes

Continue aprendendo (artigos em inglês)