git-rebase - Réapplique des commits sur le sommet de l’autre base

Si l ' on spécifie <branche> ` , `git rebase effectuera un git switch <branche> automatique avant de faire autre chose. Sinon, il reste sur la branche actuelle.

Si <amont> n’est pas spécifié, on utilisera l’amont configuré dans les options branch.<nom>. remote et branch.<nom>.merge (voir git-config[1] pour plus de détails) et on suppose l’option --fork-point. Si vous n’êtes actuellement sur aucune branche ou si la branche actuelle n’a pas d’amont configuré, le rebasage échouera.

Tous les changements apportés par des commits dans la branche actuelle, mais qui ne sont pas dans <amont> sont enregistrés dans une zone temporaire. Il s’agit de la même série de commits qui serait affichée par git log <amont>.HEAD ; ou par git log 'fork_point'.HEAD, si --fork-point est actif (voir la description de --fork-point ci-dessous) ; ou par git log HEAD si l’option --root est spécifiée.

La branche actuelle est réinitialisée à <amont> ou <nouvellebase> si l’option --onto a été fournie. Cela a le même effet que git reset --hard <amont> (ou <nouvellebase>). ORIG_HEAD est fixé pour pointer au sommet de la branche avant la réinitialisation.

Les commits qui ont été précédemment sauvés dans la zone temporaire sont ensuite réappliqués à la branche actuelle, un par un, dans l’ordre. Notez que tout commit dans HEAD qui introduit les mêmes changements textuels que ceux d’un commit dans HEAD..<amont> sont omis (c.-à-d. une rustine déjà acceptée en amont avec un autre message de validation ou un autre horodatage sera ignorée).

Il est possible qu’un échec de fusion empêche ce processus d’être complètement automatique. Vous devrez résoudre un tel échec de fusion et exécuter git rebase --continue. Une autre option est de contourner le commit qui a causé l’échec de fusion avec git rebase --skip. Pour extraire la <branche>`originale et supprimer les fichiers de travail de `.git/rebase-apply, utilisez la commande git rebase --abort à la place.

Supposons que l’historique suivant existe et que la branche actuelle est "topic" :

À partir de là, le résultat de l’une des commandes suivantes :

serait :

NOTE: Cette dernière forme n’est qu’un raccourcis de`git checkout sujet` suivi par git rebase master . Lorsque rebase se termine, sujet restera à la branche extraite.

Si la branche amont contient déjà un changement que vous avez fait (par exemple, parce que vous avez envoyé une rustine qui a été appliquée en amont), alors ce commit sera ignoré et des avertissements seront émis (si le backend merge est utilisé). Par exemple, l’exécution de git rebase master sur l’historique suivant (dans lequel A' et A introduisent le même ensemble de modifications, mais ont des informations de validateur différentes) :

donnera :

Voici comment vous transplanteriez une branche de sujet basée sur une branche sur une autre, pour prétendre que vous avez fourché la branche de sujet de cette dernière branche, en utilisant rebase --onto.

D’abord supposons que votre sujet est basé sur la branche next. Par exemple, une fonctionnalité développée en sujet dépend de certaines fonctionnalités qui se trouvent dans next.

Nous voulons rendre sujet embranchée depuis la branche master. ; par exemple, parce que la fonctionnalité sur laquelle sujet dépend a été fusionnée dans la branche master plus stable. Nous voulons que notre arbre ressemble à ça :

Nous pouvons l’obtenir en utilisant la commande suivante :

Un autre exemple de l’option --onto est de rebaser une partie d’une branche. Si nous avons la situation suivante :

puis la commande

aurait pour résultat :

Ceci est utile lorsque le sujet B ne dépend pas du sujetA.

Une plage de commits pourrait également être supprimée avec rebase. Si nous avons la situation suivante :

puis la commande

entraînerait le retrait des commits F et G :

Ceci est utile si F et G ont été corrompues d’une certaine manière, ou ne devraient pas faire partie de sujetA. Notez que l’argument pour --onto et le paramètre <amont> peuvent être n’importe quel commit-esque valide.

En cas de conflit, git rebase s’arrêtera au premier commit problématique et laissera les marqueurs de conflit dans l’arbre. Vous pouvez utiliser git diff pour localiser les marqueurs (<<<<<<) et faire des modification pour résoudre le conflit. Pour chaque fichier que vous éditez, vous devez dire à Git que le conflit a été résolu, généralement cela serait fait avec

Après avoir résolu le conflit manuellement et mis à jour l’index avec la résolution souhaitée, vous pouvez poursuivre le processus de rebasage avec

Alternativement, vous pouvez défaire le git rebase avec

Les options de cette section ne peuvent être utilisées avec aucune autre option, y compris pas les unes avec les autres :

Les options suivantes :

sont incompatibles avec les options suivantes :

En outre, les paires d’options suivantes sont incompatibles :

git rebase a deux backends primaires : apply et merge. (Le backend apply était connu comme le backend am, mais le nom a conduit à la confusion car il ressemble à un verbe au lieu d’un nom. De plus, le backend merge était connu comme le backend interactif, mais il est maintenant utilisé aussi pour les cas non interactifs. Les deux ont été renommés en fonction de la fonctionnalité de bas niveau qui sous-tend chacun.) Il y a quelques différences subtiles dans la façon dont ces deux backends se comportent :

Le mécanisme de fusion (commandes git merge et git pull) permet de choisir les stratégies de fusion du backend avec l’option -s. Certaines stratégies peuvent également prendre leurs propres options, qui peuvent être passées en donnant des arguments -X<option> à git merge et/ou git pull.

Avec les stratégies qui utilisent la fusion à trois points (y compris la fusion par défaut, ort), si une modification est effectuée sur les deux branches, mais qu’elle est ensuite inversée sur l’une des branches, ce changement sera présent dans le résultat de la fusion ; certaines personnes trouvent ce comportement déroutant. Cela se produit parce que seules les têtes et la base de la fusion sont prises en compte lors d’une fusion, et non le commit individuel. L’algorithme de fusion considère donc le changement inversé comme n’étant pas un changement du tout, et substitue la version modifiée à la place.

Vous devriez comprendre les implications de l’utilisation de git rebase sur un dépôt partagé. Voir la section « RATTRAPER UN REBASAGE AMONT » ci-dessous.

Lorsque le rebasage est exécuté, il exécutera d’abord un crochet pre-rebase si il existe. Vous pouvez utiliser ce crochet pour faire des vérifications de santé et rejeter le rebasage si il n’est pas approprié. Veuillez voir le modèle de script crochet`pre-rebase` pour un exemple.

Une fois terminé, <branche> sera la branche actuelle.

Rebaser interactivement signifie que vous avez une possibilité de modifier les commits qui sont rebasés. Vous pouvez réordonner les commits, et vous pouvez les supprimer (en éliminant des rustines mauvaises ou autrement indésirables).

Le mode interactif est destiné à ce type de flux de travail :

où le point 2. se compose de plusieurs cas

a) utilisation régulière

b) correction indépendante

Parfois, la chose corrigée en b.2. ne peut pas être ajoutée au commit pas totalement parfait qu’elle corrige, parce que ce commit est enterré profondément dans une série de rustines. C’est exactement ce à quoi le rebasage interactif sert : utilisez-le après beaucoup de "a"s et "b"s, en réorganisant et en éditant des commits, et en combinant plusieurs commits en un.

Commencez avec le dernier commit que vous voulez retenir tel quel :

Un éditeur sera démarré avec tous les commits dans votre branche actuelle (en ignorant les commits de fusion), qui viennent après le commit donné. Vous pouvez réorganiser à votre goût les commits dans cette liste, et vous pouvez les supprimer. La liste ressemble plus ou moins à ceci :

Les titres sont purement pour votre usage ; git rebase ne les regardera pas mais s’appuiera sur les noms de commit («deadbee» et «fa1afe1» dans cet exemple), donc ne supprimez pas ou ne modifiez pas les noms.

En remplaçant la commande "pick" par la commande "edit", vous pouvez dire à git rebase de s’arrêter après l’application de ce commit, afin que vous puissiez modifier les fichiers et/ou le message de validation, modifier le commit, et continuer de rebaser.

Pour interrompre le rebasage (comme une commande "edit" le ferait, mais sans picorer de commit d’abord), utilisez la commande "break".

Si vous voulez simplement modifier le message de validation pour un commit, remplacez la commande "pick" par la commande "reword".

Pour abandonner un commit, remplacer la commande "pick" par "drop", ou supprimez simplement la ligne correspondante.

Si vous voulez replier deux ou plusieurs commits en un, remplacer la commande "pick" pour le second commit et les commits subséquents par "squash" ou "fixup". Si les commits avaient différents auteurs, le commit replié sera attribué à l’auteur du premier commit. Le message de commit proposé pour le commit replié est la concaténation du message du premier commit avec ceux identifiés par les commandes "squash", en omettant les messages de commits identifiés par les commandes "fixup", à moins que "fixup -c" ne soit utilisé. Dans ce cas, le message de validation proposé n’est que le message du commit appliqué par "fixup -c", et un éditeur est ouvert vous permettant de modifier le message. Le contenu (rustine) du commit "fixup -c" sont toujours incorporé dans le commit replié. S’il y a plus d’un commit "fixup -c", le message du dernier est utilisé. Vous pouvez également utiliser "fixup -C" pour obtenir le même comportement que "fixup -c" sauf sans ouvrir un éditeur.

git rebase s’arrêtera lorsque "pick" a été remplacé par "edit" ou quand une commande échoue en raison d’erreurs de fusion. Lorsque vous avez terminé l’édition et/ou la résolution des conflits, vous pouvez continuer avec git rebase --continue.

Par exemple, si vous voulez réorganiser les 5 derniers commits, de sorte que ce qui était HEAD~4 devient le nouveau HEAD. Pour ce faire, vous appelez git rebase comme ceci :

Et déplacer la première rustine jusqu’à la fin de la liste.

Vous pourriez vouloir recréer des commits de fusion, par exemple si vous avez une histoire comme celle-ci :

Supposons que vous voulez rebaser la branche latérale à partir de "A" à "Q". Assurez-vous que la `HEAD`actuelle est "B", et appelez

La réorganisation et l’édition des commits créent généralement des étapes intermédiaires non testées. Vous pouvez vérifier que votre édition d’historique n’a rien cassé en exécutant un test, ou au moins en recompilant à des points intermédiaires de l’historique en utilisant la commande "exec" (raccourci "x"). Vous pouvez le faire en créant une liste de todo comme celle-ci :

Le rebasage interactif s’arrêtera quand une commande échouera (c.-à-d. des sorties avec statut non-0) pour vous donner l’occasion de résoudre le problème. Vous pouvez continuer avec git rebase --continue.

La commande "exec" lance la commande dans un shell (la commande par défaut, habituellement /bin/sh), de sorte que vous pouvez utiliser des fonctions de shell (comme "cd", ">", ";" …​). La commande est exécutée de la racine de l’arbre de travail.

Cette commande vous permet de vérifier que les commits intermédiaires sont compilables. La liste de todo devient ainsi :

En mode interactif, vous pouvez marquer des commits avec l’action "edit". Cependant, cela ne signifie pas nécessairement que git rebase s’attende à ce que le résultat de cette modification soit exactement un commit. En effet, vous pouvez défaire le commit, ou vous pouvez ajouter d’autres commits. Ceci peut être utilisé pour diviser un commit en deux :

Si vous n’êtes pas absolument sûr que les révisions intermédiaires sont cohérentes (qu’elles compilent, passent la suite de test, etc.) vous devriez utiliser git stash pour remiser les modifications pas encore validées après chaque commit, puis tester, et modifier le commit si des corrections sont nécessaires.

Rebaser (ou réécrire sous toute autre forme) une branche sur laquelle d’autres ont basé le travail est une mauvaise idée : quiconque en aval est obligé de réparer manuellement son historique. Cette section explique comment corriger cet état du point de vue de l’aval. La vraie solution, cependant, serait d’éviter de rebaser en amont en premier lieu.

Pour illustrer, supposez que vous êtes dans une situation où quelqu’un développe une branche sous-systeme, et que vous travaillez sur un sujet qui dépend de ce sous-systeme. Vous pourriez finir avec un historique comme suit :

Si sous-systeme est rebasé sur master, il se produit ce qui suit :

Si vous continuez maintenant le développement comme d’habitude, et finalement fusionnez sujet à sous-systeme, les commits de sous-systeme resteront dupliquées pour toujours :

De telles doublons sont généralement mal vus parce qu’ils encombrent l’historique, ce qui le rend plus difficile à suivre. Pour nettoyer, vous devez transplanter les commits sur sujet au nouveau sommet de sous-systeme, c’est-à-dire rebaser sujet. Cela s’applique en cascade : toute personne en aval de sujet est obligée de rebaser aussi, et ainsi de suite !

Il existe deux types de corrections, discutées dans les sections suivantes :

La commande de rebasage interactive a été à l’origine conçue pour gérer des séries de rustines individuelles. En tant que tel, il est logique d’exclure les commits de fusion de la liste de todo, car le développeur a peut-être fusionné le master alors qu’il travaillait sur la branche, en attendant de rebaser tous les commits sur master à un moment (en sautant les commits de fusion).

Cependant, il y a des raisons légitimes pour lesquelles un développeur peut vouloir recréer des commits de fusion : garder la structure de la branche (ou « topologie des commit ») lorsqu’il travaille sur plusieurs branches interconnectées.

Dans l’exemple suivant, le développeur travaille sur une branche de sujet qui refactorise la façon dont les boutons sont définis, ainsi que sur une autre branche de sujet qui utilise cette refactorisation pour mettre en œuvre un bouton « Signaler un bug ». La sortie de ‘git log --graph --format=% -5’ peut ressembler à ça :

Le développeur pourrait vouloir rebaser ces commits sur un nouveau master tout en gardant la topologie de la branche, par exemple lorsque la première branche de sujet devrait être intégrée dans master beaucoup plus tôt que la seconde, par exemple, pour résoudre les conflits de fusion avec des modifications à la classe DownloadButton qui ont déjà été intégrées sur ‘master’.

Ce rebasage peut être effectué en utilisant l’option --rebase-merges. Il générera une liste de todo qui ressemble à ceci :

Contrairement à une base interactive régulière, il y a des commandes label, reset et merge en plus des commandes pick.

La commande label associe une étiquette à la HEAD actuelle lorsque cette commande est exécutée. Ces étiquettes sont créées sous forme de refs local à l’arbre-de-travail (refs/rewritten/<étiquette>) qui seront supprimées lorsque le rebasage sera terminé. De cette façon, les opérations de rebasage dans plusieurs arbre-de-travail liés au même dépôt n’interfèrent pas les uns avec les autres. Si la commande label échoue, elle est reprogrammée immédiatement, avec un message indiquant comment procéder.

La commande reset réinitialise la HEAD, l’index et l’abre de travail à la révision spécifiée. Il est semblable à un exec git reset --hard <étiquette>, mais refuse d’écraser des fichiers non suivis. Si la commande reset échoue, elle est reprogrammée immédiatement, avec un message indiquant comment modifier la liste de todo (cela arrive généralement quand une commande reset a été insérée dans la liste de todo manuellement et contient une typo).

La commande merge fusionnera la ou les révisions spécifiées dans ce qui est HEAD à ce moment-là. Avec -C <commit-original>, le message de validation de la fusion spécifiée sera utilisé. Lorsque le -C est changé en minuscule -c, le message sera ouvert dans un éditeur après une fusion réussie afin que l’utilisateur puisse modifier le message.

Si une commande merge échoue pour toute raison autre que des conflits de fusion (c.-à-d. lorsque l’opération de fusion n’a même pas commencé), elle est reprogrammée immédiatement.

Par défaut, la commande merge utilisera la stratégie de fusion ort pour les fusions normales, et octopus pour les fusions de plusieurs branches. On peut spécifier une stratégie par défaut pour toutes les fusions en utilisant l’argument --strategy lorsqu’on invoque rebase, ou peut remplacer des fusions spécifiques dans la liste interactive des commandes en utilisant une commande exec pour appeler git merge explicitement avec un argument --strategy. Notez que lorsque vous appelez git merge explicitement comme cela, vous pouvez utiliser le fait que les étiquettes sont des réfs sont locales à l’arbre-de-travail (la réf refs/rewritten/onto correspondrait à l`étiquette onto, par exemple) afin de se référer aux branches que vous voulez fusionner.

Note : la première commande (label onto) étiquette la révision sur laquelle les commits sont rebasés ; Le nom onto est juste une convention, comme un référence à l’option --onto.

Il est également possible d’introduire des commits de fusion complètement nouveaux à partir de zéro en ajoutant une commande de la forme merge <tête-de-fusion>. Cette forme générera un message de validation provisoire et ouvrira toujours un éditeur pour laisser l’utilisateur l’éditer. Cela peut être utile, par exemple lorsqu’une branche de sujet traite plus d’un seul problème et doit être divisée en deux branches de thème ou plus. Considérez cette liste de todo :

Le seul commit de cette liste qui n’est pas lié à CMake peut très bien avoir été motivé par le travail sur la correction de tous ces bugs introduits en passant à CMake, mais il répond à une préoccupation différente. Pour diviser cette branche en deux branches thématiques, la liste de todo pourrait être modifiée comme ceci :

Fait partie de la suite git[1]

Cette page de manuel a été traduite par Jean-Noël Avila <jn.avila AT free DOT fr> et les membres du projet git-manpages-l10n. Veuillez signaler toute erreur de traduction par un rapport de bogue sur le site https://github.com/jnavila/git-manpages-l10n .