git-rebase - Reaplique os commits em cima do topo de outra base

Se o <ramo> for especificado, o git rebase executará um git switch <ramo> automático antes de fazer qualquer outra coisa. Caso contrário, ele permanecerá no ramo atual.

Se o <upstream> não for especificado, será utilizado o "upstream" configurado nas opções branch.<nome>.remote e branch.<nome>.merge (para mais detalhes consulte git-config[1]) e a opção --fork-point será assumida. Se você não estiver em nenhuma ramificação no momento ou se a ramificação atual não tiver um "upstream" configurado, o rebase será abortado.

Todas as alterações feitas por commits no ramo atual, mas que não estão no <upstream>, são salvos numa área temporária. Esse é o mesmo conjunto de commits que seria exibido pelo comando git log <upstream>..HEAD; ou pelo comando git log 'fork_point'..HEAD, se a opção --fork-point estiver ativa (consulte abaixo a descrição sobre a opção --fork-point); ou pelo git log HEAD, caso a opção --root seja usada.

O ramo atual é redefinido para <upstream> ou <newbase> caso a opção --onto tenha sido usada. Isso tem exatamente o mesmo efeito que git reset --hard <upstream> (ou <newbase>). O ORIG_HEAD é definido para apontar para o cume do ramo antes da reinicialização.

Os commits que foram salvos anteriormente na área temporária são reaplicadas no ramo atual, uma por uma e em ordem. Observe que quaisquer commits no HEAD que introduzam as mesmas alterações textuais que um commit no HEAD..<upstream> são omitidas (ou seja, um patch já aceito na inicial com uma mensagem de commit ou carimbo de data e hora diferente, serão ignorados).

É possível que uma falha na mesclagem impeça que este processo seja totalmente automático. Você terá que resolver qualquer falha na mesclagem e executar o comando git rebase --continue. Outra opção é ignorar o commit que causou a falha na mesclagem com comando git rebase --skip. Para verificar o <ramo> original e remover os arquivos de trabalho .git/rebase-apply, use o comando git rebase --abort.

Suponha que o seguinte histórico exista e que o ramo atual seja "topic":

A partir deste ponto, o resultado de um dos seguintes comandos:

seria:

OBSERVAÇÃO: A última maneira é apenas uma abreviação do comando git checkout topic seguido de git rebase master. Quando o "rebase" for encerrado, o topic continuará sendo o ramo com o check-out.

Se o ramo "upstream" já tiver uma alteração que você fez (porque você enviou uma correção que foi aplicado no "upstream" por exemplo), este commit será ignorado e serão emitidos avisos (se o backend merge for usado). Por exemplo, executar o comando git rebase master no seguinte histórico (onde A' e A introduzem o mesmo conjunto de alterações, mas têm informações diferentes de quem fez o commit):

vai resultar em:

Aqui está como você transplantaria um ramo do tópico com base num ramo para outro, para fingir que você bifurcou o ramo do tópico deste último ramo, utilizando rebase --onto.

Primeiro, vamos supor que seu tópico tenha como base o ramo next. Por exemplo, um recurso desenvolvido no tópico depende de alguma funcionalidade encontrada em next.

Queremos criar um tópico bifurcado no ramo master; porque a funcionalidade da qual o tópico depende foi mesclado na ramificação master mais estável. Queremos que a nossa árvore fique assim:

Podemos conseguir isso utilizando o seguinte comando:

Outro exemplo da opção --onto é fazer o rebase de uma parte de um ramo. Se tivermos a seguinte situação:

então o comando

resultaria em:

É útil quando o topicB não depender do topicA.

Uma série de commits também pode ser removida com o rebase. Se tivermos a seguinte situação:

então o comando

resultaria na remoção dos commits F e G:

Isso é útil se F e G tiverem alguma falha ou não devam fazer parte do "topicA". Observe que o argumento para a opção --onto e o parâmetro <upstream> podem ser qualquer tipo válido de commit.

Em caso de conflito, o comando git rebase encerrará no primeiro commit problemático e deixará marcadores de conflito na árvore. Você pode usar o comando git diff para localizar os marcadores (<<<<<<) e fazer as edições para resolver o conflito. Para cada arquivo editado, você precisa informar ao Git que o conflito foi resolvido; normalmente, isso seria feito com

Depois de resolver o conflito manualmente e atualizar o índice com a resolução desejada, você pode continuar o processo de reconstrução com o comando

Como alternativa, você pode desfazer o git rebase com

As opções nesta seção, não podem ser usadas com nenhuma outra opção, inclusive entre si:

As seguintes opções:

são incompatíveis com as seguintes opções:

Além disso, os seguintes pares de opções são incompatíveis:

O git rebase tem dois backends principais: apply e merge. (O backend apply costumava ser conhecido como backend am, mas o nome gerou confusão, pois parece um verbo em vez de um substantivo. Além disso, o backend merge costumava ser conhecido como backend interativo, mas agora também é usado para casos não interativos. Ambos foram renomeados com base na funcionalidade de baixo nível que sustentava cada um deles). Há algumas diferenças sutis na maneira de como estes dois backends se comportam:

O mecanismo de mesclagem (os comandos git merge e git pull) permite que as estratégias de mesclagem do backend sejam escolhidas com a opção -s. Algumas estratégias também podem ter as suas próprias opções, que podem ser passadas usando argumentos -X<opção> ao comando git merge e/ou git pull.

Com as estratégias que usam a mesclagem de 3 vias (incluindo a predefinição, ort), se uma alteração for feita em ambos os ramos, mas posteriormente revertida num dos ramos, essa alteração estará presente no resultado da mesclagem; algumas pessoas acham este comportamento confuso. Isto ocorre porque somente os cabeçalhos e a base de mesclagem são considerados ao realizar uma mesclagem, e não os commits individuais. Portanto, o algoritmo de mesclagem considera a alteração revertida como se não houvesse nenhuma alteração e, em vez disso, substitui a versão alterada.

Você deve entender as implicações de usar o comando git rebase num repositório que você compartilha. Consulte também SE RECUPERANDO DA RECONSTRUÇÃO DA FUNDAÇÃO INICIAL (UPSTREM REBASE) abaixo.

Quando o rebase for executado, ele primeiro executará um gancho pre-rebase, caso exista um. Você pode usar esse gancho para fazer verificações de sanidade e rejeitar o rebase caso não seja apropriado. Consulte o script modelo do gancho do pre-rebase para ver um exemplo.

Após a conclusão, o <ramo> será o ramo atual.

O rebase interativo significa que você tem a chance de editar os commits onde o rebase foi feito. Você pode reordenar os commits e removê-los (eliminando correções ruins ou indesejados).

O modo interativo é destinado para este tipo de fluxo de trabalho:

onde o ponto 2. consiste em várias instâncias do

a) uso regular

b) correção independente

Às vezes, o problema é corrigido na versão b.2. Não pode ser emendado no commit parcialmente perfeito que ele corrige, porque este commit está profundamente entranhado numa série de correções. É exatamente para isso que serve o rebase interativo: use-o após muitos "a" e "b", ao reorganizar e editar os commits e acumulando vários commits num só.

Inicie-o com o último commit que você quer manter como está:

Um editor será acionado com todos os commits em seu ramo atual (ignorando a mesclagem dos commits), que vêm após o commit informado. Você pode reordenar os commits nesta lista como quiser e também é possível removê-los. A lista é mais ou menos assim:

As descrições on-line são puramente para o seu prazer; o comando git rebase não examinará eles, porém os nomes dos commits ("deadbee" e "fa1afe1" neste exemplo), portanto, não exclua ou edite os nomes.

Ao substituir o comando "pick" pelo comando "edit", é possível dizer ao comando git rebase para parar após aplicar este commit, para que seja possível editar os arquivos e/ou a mensagem do commit, alterar o commit e continuar com a reconstrução.

Para interromper um "rebase" (exatamente como um comando "edit" faria, mas sem fazer uma escolha seletiva de nenhum commit primeiro), use o comando "break".

Caso apenas queira editar a mensagem do commit para um commit, substitua o comando pick pelo comando reword.

Para eliminar um commit, substitua o comando "pick" por "drop" ou apenas exclua a linha coincidente.

Se você quiser juntar dois ou mais commits num só, substitua o comando pick para o segundo commit e os subsequentes com squash ou fixup. Se os commits tiverem autores diferentes, o commit agrupado será atribuído ao autor do primeiro commit. A mensagem sugerida do commit para o commit agrupado é a concatenação da mensagem do primeiro commit com aquelas identificadas pelos comandos squash, omitindo as mensagens dos commits identificados pelos comandos fixup, a menos que fixup -c seja usado. Nesse caso, a mensagem sugerida do commit é apenas a mensagem do commit fixup -c, e um editor é aberto para que você possa editar a mensagem. O conteúdo (correção) do commit fixup -c ainda é incorporado ao commit agrupado. Se houver mais de um commit fixup -c, será usada a mensagem do último commit. Você também pode usar fixup -C para obter o mesmo comportamento de fixup -c, mas sem abrir um editor.

O comando git rebase será interrompido quando o "pick" for substituído por "edit" ou quando um comando falhar devido aos erros da mesclagem. Quando você terminar de editar e/ou resolver os conflitos, será possível continuar utilizando git rebase --continue.

Como por exemplo, caso você queira reordenar os últimos 5 commits de maneira onde o que era HEAD~4 se torne o novo HEAD. Para conseguir isso, você chamaria o comando git rebase assim:

E mova o primeiro patch para o ramo da lista.

Convém recriar a mesclagem dos commits, por exemplo, caso tenha um histórico como este:

Suponha que queira reconstruir o lado do ramo ao lado começando em "A" para "Q". Verifique se o HEAD atual é "B" e chame

A reordenação e a edição dos commits geralmente criam etapas intermediárias não testadas. Talvez você queira verificar se a edição do histórico não quebrou nada executando um teste ou, pelo menos, recompilando em pontos intermediários do histórico usando o comando exec (o atalho é x). Você pode fazer isso criando uma lista de tarefas como esta:

A reconstrução interativa será interrompida quando um comando falhar (ou seja, encerra com uma condição diferente de 0) oferecendo uma oportunidade para a correção do problema. Você pode continuar com o comando git rebase --continue.

O comando exec inicia o comando num shell (a ´predefinição, geralmente é /bin/sh), para que você possa usar os recursos do shell (como cd, >, ; …​). O comando é executado a partir da raiz da árvore de trabalho.

Esse comando permite que você verifique se os commits intermediários são compiláveis. A lista de tarefas fica assim:

No modo interativo, você pode marcar commits com a ação edit (editar). No entanto, isso não significa necessariamente que o comando git rebase espera que o resultado desta edição seja exatamente um commit. De fato, você pode desfazer o commit ou adicionar outros commits. Isso pode ser usado para dividir um commit em dois:

Caso não tenha certeza absoluta que as revisões intermediárias são consistentes (elas compilam, passam no conjunto de testes, etc.), você deve usar o git stash para armazenar o commit das alterações que ainda não foram feitas após cada commit, teste e corrija o commit caso correções sejam necessárias.

Fazer o rebase (ou qualquer outra forma de reescrita) de uma ramificação onde outras pessoas trabalharam é uma má ideia: qualquer pessoa que esteja a posteriori dela é forçada a corrigir seu histórico manualmente. Esta seção explica como fazer a correção do ponto de vista de quem fez depois. A verdadeira correção, no entanto, seria evitar o rebase da ponta em primeiro lugar.

Para ilustrar, imagine que você esteja numa situação onde alguém desenvolve um subsystem no ramo e você está trabalhando num topic que depende deste subsystem. Você pode acabar com um histórico como este:

Caso a reconstrução da fundação do subsystem seja realizada contra o master, o seguinte acontece:

Caso agora continue o desenvolvimento normalmente e eventualmente mescle o topic para subsystem, os commits do subsystem permanecerão duplicados para sempre:

Estas duplicatas são geralmente desaprovadas, pois desorganizam o histórico, tornando-o mais difícil de acompanhar. Para limpar as coisas, você precisa transplantar os commits em topic para o novo topo subsystem, ou seja, rebase topic. Isso se torna um efeito cascata: qualquer pessoa que esteja após topic é forçada a refazer a base também, e assim por diante!

Existem dois tipos de correções, discutidos nas seguintes subseções:

O comando de reconstrução interativa foi originalmente projetado para lidar com séries de patches individuais. Como tal, faz sentido excluir a mesclagem dos commits da lista de tarefas, pois o desenvolvedor pode ter mesclado o master atual enquanto trabalhava no ramo, apenas para redefinir todos os commits para master eventualmente (ignorando a mesclagem dos commits).

No entanto, existem razões legítimas pelas quais um desenvolvedor pode querer recriar as mesclagens dos commits: para manter a estrutura do ramo (ou a "topologia do commit") ao trabalhar em diversos ramos inter-relacionadas.

No exemplo a seguir, o desenvolvedor trabalha em um tópico no ramo que refatora a maneira como os botões são definidos, em outro tópico do ramo que utilize esta refatoração para implementar um botão "Relatar um bug". A saída do git log --graph --format=%s -5 pode ficar assim:

O desenvolvedor pode querer redefinir estes commits para um novo master enquanto mantém a topologia da ramificação. Quando se espera que o primeiro tópico do ramo que seja integrado ao` master` muito antes do segundo por exemplo. Para resolver os conflitos da mesclagem com as alterações para a classe DownloadButton que a transformou em master por exemplo.

Esse rebase pode ser realizado com a opção --rebase-merges. Ele gerará uma lista de tarefas semelhante a esta:

Ao contrário de uma reconstrução interativa regular, existem os comandos label, reset e merge além dos comandos pick.

O comando label associa um rótulo ao HEAD atual quando este comando for executado. Estes rótulos são criados como refs locais da árvore de trabalho (refs/rewritten/<label>) que serão excluídos quando a reconstrução terminar. Dessa forma, as operações da reconstrução em várias árvores de trabalho vinculadas ao mesmo repositório não interferem entre si. Caso o comando label falhe, este é imediatamente reagendado, com uma mensagem útil sobre como proceder.

O comando reset redefine o HEAD, o índice e a árvore de trabalho para a revisão específica. É semelhante a um comando exec git reset --hard <label>, porém se recusa a sobrescrever os arquivos que não sejam monitorados. Se o comando reset falhar, ele será imediatamente reagendado, com uma mensagem útil sobre como editar a lista de tarefas (normalmente acontece quando um comando reset foi inserido manualmente na lista de tarefas e contém um erro de digitação).

O comando merge mesclará revisões usadas no que seja HEAD naquele momento. Com -C <original-commit>, a mensagem do commit de um determinada mesclagem será usada. Quando o -C é alterado para minúsculo -c, a mensagem será aberta num editor após uma mesclagem bem-sucedida, para que o usuário possa editá-la.

Se um comando merge falhar por qualquer motivo que não seja conflitos de mesclagem (ou seja, quando a operação de mesclagem nem sequer foi iniciada), ele será reagendado imediatamente.

É predefinido que o comando merge use a estratégia de mesclagem ort para mesclagens regulares e octopus para mesclagens "octopus". É possível especificar uma estratégia predefinida para todas as mesclagens usando o a opção --strategy ao invocar o rebase, ou substituir mesclagens específicas na lista interativa de comandos usando um comando exec para invocar o comando git merge explicitamente com a opção --strategy. Observe que, ao invocar explicitamente o comando git merge dessa maneira, você pode usar o fato de que as etiquetas são referências locais da árvore de trabalho (a referência refs/rewritten/onto corresponderia a etiqueta onto, por exemplo) para se referir às ramificações que deseja mesclar.

Observação: o primeiro comando (label onto) rotula a revisão onde os commits são refeitos; O nome onto é apenas uma convenção, como um aceno para a opção --onto.

Também é possível introduzir commits para mesclagem completamente novos, adicionando um comando no formato merge <merge-head>. Este formulário gera uma mensagem de commit provisória e sempre abre um editor para permitir que o usuário a edite. Pode ser útil quando por exemplo, um ramo de um tópico acaba resolvendo mais de um problema e quer ser dividido em dois ou mais ramos de tópico. Considere esta lista de tarefas:

O único commit nesta lista que não está relacionado ao CMake pode muito bem ter sido motivado ao trabalhar na correção de todos os erros introduzidos durante a mudança para o CMake, porém ele lida com um interesse diferente. Para dividir esse ramo em dois tópicos, a lista de tarefas pode ser editada desta maneira:

Parte do conjunto git[1]