5.3 Git distribué - Maintenance d’un projet

Si vous avez reçu le patch de quelqu’un qui l’a généré avec la commande git diff ou diff Unix, vous pouvez l’appliquer avec la commande git apply. Si le patch a été sauvé comme fichier /tmp/patch-ruby-client.patch, vous pouvez l’appliquer comme ceci :

Les fichiers dans votre copie de travail sont modifiés. C’est quasiment identique à la commande patch -p1 qui applique directement les patchs mais en plus paranoïaque et moins tolérant sur les concordances approximatives. Les ajouts, effacements et renommages de fichiers sont aussi gérés s’ils sont décrits dans le format git diff, ce que patch ne supporte pas. Enfin, git apply fonctionne en mode « applique tout ou refuse tout » dans lequel toutes les modifications proposées sont appliquées si elles le peuvent, sinon rien n’est modifié, là où patch peut n’appliquer que partiellement les patchs, laissant le répertoire de travail dans un état intermédiaire. git apply est par-dessus tout plus paranoïaque que patch. Il ne créera pas une validation à votre place : après l’avoir lancé, vous devrez indexer et valider les modifications manuellement.

Vous pouvez aussi utiliser git apply pour voir si un patch s’applique proprement avant de réellement l’appliquer — vous pouvez lancer git apply --check avec le patch :

S’il n’y pas de message, le patch devrait s’appliquer proprement. Cette commande se termine avec un statut non-nul si la vérification échoue et vous pouvez donc l’utiliser dans des scripts.

Si le contributeur est un utilisateur de Git qui a été assez gentil d’utiliser la commande format-patch pour générer ses patchs, votre travail sera facilité car le patch contient alors déjà l’information d’auteur et le message de validation. Si possible, encouragez vos contributeurs à utiliser format-patch au lieu de patch pour générer les patchs qu’ils vous adressent. Vous ne devriez avoir à n’utiliser git apply que pour les vrais patchs.

Pour appliquer un patch généré par format-patch, vous utilisez git am. Techniquement, git am s’attend à lire un fichier au format mbox, qui est un format texte simple permettant de stocker un ou plusieurs courriels dans un unique fichier texte. Il ressemble à ceci :

C’est le début de ce que la commande format-patch affiche, comme vous avez vu dans la section précédente. C’est aussi un format courriel mbox parfaitement valide. Si quelqu’un vous a envoyé par courriel un patch correctement formaté en utilisant git send-mail et que vous le téléchargez en format mbox, vous pouvez pointer git am sur ce fichier mbox et il commencera à appliquer tous les patchs contenus. Si vous utilisez un client courriel qui sait sauver plusieurs messages au format mbox, vous pouvez sauver la totalité de la série de patchs dans un fichier et utiliser git am pour les appliquer tous en une fois.

Néanmoins, si quelqu’un a déposé un fichier de patch généré via format-patch sur un système de suivi de faits techniques ou quelque chose de similaire, vous pouvez toujours sauvegarder le fichier localement et le passer à git am pour l’appliquer :

Vous remarquez qu’il s’est appliqué proprement et a créé une nouvelle validation pour vous. L’information d’auteur est extraite des en-têtes From et Date tandis que le message de validation est repris du champ Subject et du corps (avant le patch) du message. Par exemple, si le patch est appliqué depuis le fichier mbox ci-dessus, la validation générée ressemblerait à ceci :

L’information Commit indique la personne qui a appliqué le patch et la date d’application. L’information Author indique la personne qui a créé le patch et la date de création.

Il reste la possibilité que le patch ne s’applique pas proprement. Peut-être votre branche principale a-t’elle déjà trop divergé de la branche sur laquelle le patch a été construit, ou peut-être que le patch dépend d’un autre patch qui n’a pas encore été appliqué. Dans ce cas, le processus de git am échouera et vous demandera ce que vous souhaitez faire :

Cette commande introduit des marqueurs de conflit dans tous les fichiers qui ont généré un problème, de la même manière qu’un conflit de fusion ou de rebasage. Vous pouvez résoudre les problèmes de manière identique — éditez le fichier pour résoudre les conflits, indexez le nouveau fichier, puis lancez git am --resolved ou git am --continue pour continuer avec le patch suivant :

Si vous souhaitez que Git essaie de résoudre les conflits avec plus d’intelligence, vous pouvez passer l’option -3 qui demande à Git de tenter une fusion à trois sources. Cette option n’est pas active par défaut parce qu’elle ne fonctionne pas si le commit sur lequel le patch indique être basé n’existe pas dans votre dépôt. Si par contre, le patch est basé sur un commit public, l’option -3 est généralement beaucoup plus fine pour appliquer des patchs conflictuels :

Dans ce cas, je cherchais à appliquer un patch qui avait déjà été intégré. Sans l’option -3, cela aurait ressemblé à un conflit.

Si vous appliquez des patchs à partir d’un fichier mbox, vous pouvez aussi lancer la commande am en mode interactif qui s’arrête à chaque patch trouvé et vous demande si vous souhaitez l’appliquer :

C’est agréable si vous avez un certain nombre de patchs sauvegardés parce que vous pouvez voir les patchs pour vous rafraîchir la mémoire et ne pas les appliquer s’ils ont déjà été intégrés.

Quand tous les patchs pour votre sujet ont été appliqués et validés dans votre branche, vous pouvez choisir si et comment vous souhaitez les intégrer dans une branche au long cours.

Un mode simple fusionne votre travail dans la branche master. Dans ce scénario, vous avez une branche master qui contient le code stable. Quand vous avez des modifications prêtes dans une branche thématique, vous la fusionnez dans votre branche master puis effacez la branche thématique, et ainsi de suite. Si vous avez un dépôt contenant deux branches nommées ruby_client et php_client qui ressemble à Historique avec quelques branches thématiques. et que vous fusionnez ruby_client en premier, suivi de php_client, alors votre historique ressemblera à la fin à Après fusion des branches thématiques..

C’est probablement le mode le plus simple mais cela peut s’avérer problématique si vous avez à gérer des dépôts ou des projets plus gros pour lesquels vous devez être circonspect sur ce que vous acceptez.

Si vous avez plus de développeurs ou un projet plus important, vous souhaiterez probablement utiliser un cycle de fusion à deux étapes. Dans ce scénario, vous avez deux branches au long cours, master et develop, dans lequel vous déterminez que master est mis à jour seulement lors d’une version vraiment stable et tout le nouveau code est intégré dans la branche develop. Vous poussez régulièrement ces deux branches sur le dépôt public. Chaque fois que vous avez une nouvelle branche thématique à fusionner (Avant la fusion d’une branche thématique.), vous la fusionnez dans develop (Après la fusion d’une branche thématique.). Puis, lorsque vous étiquetez une version majeure, vous mettez master à niveau avec l’état stable de develop en avance rapide (Après une publication d’une branche thématique.).

Ainsi, lorsque l’on clone le dépôt de votre projet, on peut soit extraire la branche master pour construire la dernière version stable et mettre à jour facilement ou on peut extraire la branche develop qui représente le nec plus ultra du développement.

Vous pouvez aussi continuer ce concept avec une branche d’intégration où tout le travail est fusionné. Alors, quand la base de code sur cette branche est stable et que les tests passent, vous la fusionnez dans la branche develop. Quand cela s’est avéré stable pendant un certain temps, vous mettez à jour la branche master en avance rapide.

Le projet Git dispose de quatre branches au long cours : master, next, pu (proposed updates : propositions) pour les nouveaux travaux et maint pour les backports de maintenance. Quand une nouvelle contribution est proposée, elle est collectée dans des branches thématiques dans le dépôt du mainteneur d’une manière similaire à ce que j’ai décrit (Série complexe de branches thématiques contribuées en parallèle.). À ce point, les fonctionnalités sont évaluées pour déterminer si elles sont stables et prêtes à être consommées ou si elles nécessitent un peaufinage. Si elles sont stables, elles sont fusionnées dans next et cette branche est poussée sur le serveur public pour que tout le monde puisse essayer les fonctionnalités intégrées ensemble.

Si les fonctionnalités nécessitent encore du travail, elles sont fusionnées plutôt dans pu. Quand elles sont considérées comme totalement stables, elles sont re-fusionnées dans master et sont alors reconstruites à partir des fonctionnalités qui résidaient dans next mais n’ont pu intégrer master. Cela signifie que master évolue quasiment toujours en mode avance rapide, tandis que next est rebasé assez souvent et pu est rebasé encore plus souvent :

Quand une branche thématique a finalement été fusionnée dans master, elle est effacée du dépôt. Le projet Git a aussi une branche maint qui est créée à partir de la dernière version pour fournir des patchs correctifs en cas de besoin de version de maintenance. Ainsi, quand vous clonez le dépôt de Git, vous avez quatre branches disponibles pour évaluer le projet à différentes étapes de développement, selon le niveau de développement que vous souhaitez utiliser ou pour lequel vous souhaitez contribuer. Le mainteneur a une gestion structurée qui lui permet d’évaluer et sélectionner les nouvelles contributions.

D’autres mainteneurs préfèrent rebaser ou sélectionner les contributions sur le sommet de la branche master, plutôt que les fusionner, de manière à conserver un historique à peu près linéaire. Lorsque plusieurs modifications sont présentes dans une branche thématique et que vous souhaitez les intégrer, vous vous placez sur cette branche et vous lancez la commande rebase pour reconstruire les modifications à partir du sommet courant de la branche master (ou develop, ou autre). Si cela fonctionne correctement, vous pouvez faire une avance rapide sur votre branche master et vous obtenez finalement un historique de projet linéaire.

L’autre moyen de déplacer des modifications introduites dans une branche vers une autre consiste à les sélectionner ou les picorer (cherry-pick). Un picorage dans Git ressemble à un rebasage appliqué à un commit unique. Cela consiste à prendre le patch qui a été introduit lors d’une validation et à essayer de l’appliquer sur la branche sur laquelle on se trouve. C’est très utile si on a un certain nombre de commits sur une branche thématique et que l’on veut n’en intégrer qu’un seul, ou si on n’a qu’un commit sur une branche thématique et qu’on préfère le sélectionner plutôt que de lancer rebase. Par exemple, supposons que vous ayez un projet ressemblant à ceci :

Si vous souhaitez tirer le commit e43a6 dans votre branche master, vous pouvez lancer :

La même modification que celle introduite en e43a6 est tirée mais vous obtenez une nouvelle valeur de SHA-1 car les dates d’application sont différentes. À présent, votre historique ressemble à ceci :

Maintenant, vous pouvez effacer votre branche thématique et abandonner les commits que vous n’avez pas tirés dans master.

Si vous fusionnez et rebasez beaucoup ou si vous maintenez une branche au long cours, la fonctionnalité appelée « rerere » peut s’avérer utile.

Rerere signifie « ré utiliser les ré solutions en re gistrées » (“ reuse recorded resolution ”) ‑ c’est un moyen de raccourcir les résolutions manuelles de conflit. Quand rerere est actif, Git va conserver un jeu de couples d’images pré et post fusion des fichiers ayant présenté des conflits, puis s’il s’aperçoit qu’un conflit ressemble à une de ces résolutions, il va utiliser la même stratégie sans rien vous demander.

Cette fonctionnalité se traite en deux phases : une étape de configuration et une commande. L’étape de configuration est rerere.enabled qui active la fonction et qu’il est facile de placer en config globale :

Ensuite, quand vous fusionnez en résolvant des conflits, la résolution sera enregistrée dans le cache pour un usage futur.

Si besoin, vous pouvez interagir avec le cache rerere au moyen de la commande git rerere. Quand elle est invoquée telle quelle, Git vérifie sa base de données de résolutions et essaie de trouver une correspondance avec les conflits en cours et les résout (bien que ce soit automatique si rerere.enabled est à true). Il existe aussi des sous-commandes permettant de voir ce qui sera enregistré, d’effacer du cache une résolution spécifique ou d’effacer entièrement le cache. rerere est traité plus en détail dans Rerere.