9.2 Git et les autres systèmes - Migration vers Git

Si vous avez lu la section précédente concernant l’utilisation de git svn, vous pouvez utiliser facilement ces instructions pour git svn clone un dépôt ; ensuite, vous pouvez arrêter d’utiliser le serveur Subversion, pousser vers un nouveau serveur Git, et commencer à l’utiliser. Si vous voulez l’historique, vous pouvez obtenir cela aussi rapidement que vous pouvez tirer les données hors du serveur Subversion (ce qui peut prendre un bout de temps).

Cependant, l’import n’est pas parfait ; et comme ça prendra tant de temps, autant le faire correctement. Le premier problème est l’information d’auteur. Dans Subversion, chaque personne qui crée un commit a un utilisateur sur le système qui est enregistré dans l’information de commit. Les exemples dans la section précédente montrent schacon à quelques endroits, comme la sortie de blame et git svn log. Si vous voulez faire correspondre cela à une meilleure donnée d’auteur Git, vous avez besoin d’une transposition des utilisateurs Subversion vers les auteurs Git. Créez un fichier appelé users.txt qui a cette correspondance dans un format tel que celui-ci :

Pour obtenir une liste des noms d’auteur que SVN utilise, vous pouvez lancer ceci :

Cela génère la sortie log dans le format XML, puis garde seulement les lignes avec l’information d’auteur, rejette les doublons, enlève les étiquettes XML. (Bien sûr, cela ne marche que sur une machine ayant grep, sort et perl installés.) Ensuite, redirigez cette sortie dans votre fichier users.txt afin que vous puissiez ajouter l’information d’utilisateur Git équivalente près de chaque entrée.

Vous pouvez fournir ce fichier à git svn pour l’aider à faire correspondre la donnée d’auteur plus précisément. Vous pouvez aussi demander à git svn de ne pas inclure les metadonnées que Subversion importe normalement, en passant --no-metadata à la commande clone ou init.

Ceci fait ressembler votre commande import à ceci :

Maintenant vous devriez avoir un import Subversion plus joli dans votre dossier my_project. Au lieu de commits qui ressemblent à ceci

ils ressemblent à ceci :

Non seulement le champ Auteur a l’air beaucoup mieux, mais le git-svn-id n’est plus là non plus.

Vous devriez aussi faire un peu de ménage post-import. D’abord, vous devriez nettoyer les références bizarres que git svn a installées. Premièrement vous déplacerez les étiquettes afin qu’elles soient de véritables étiquettes plutôt que d’étranges branches distantes, et ensuite vous déplacerez le reste des branches afin qu’elles soient locales.

Pour déplacer les étiquettes pour qu’elles soient des étiquettes Git propres, lancez

Ceci prend les références qui étaient des branches distantes qui commençaient par remotes/origin/tags et en fait de vraies étiquettes (légères).

Ensuite, déplacez le reste des références sous refs/remotes pour qu’elles soient des branches locales :

Il peut arriver que vous voyiez quelques autres branches qui sont suffixées par @xxx (où xxx est un nombre), alors que dans Subversion vous ne voyez qu’une seule branche. C’est en fait une fonctionnalité Subversion appelée « peg-revisions », qui est quelque chose pour laquelle Git n’a tout simplement pas d’équivalent syntaxique. Donc, git svn ajoute simplement le numéro de version svn au nom de la branche de la même façon que vous l’auriez écrit dans svn pour adresser la « peg-revision » de cette branche. Si vous ne vous souciez plus des « peg-revisions », supprimez-les simplement en utilisant git branch -d.

Maintenant toutes les vieilles branches sont de vraies branches Git et toutes les vieilles étiquettes sont de vraies étiquettes Git.

Il y a une dernière chose à nettoyer. Malheureusement, git svn crée une branche supplémentaire appelée trunk, qui correspond à la branche par défaut de Subversion, mais la ref trunk pointe au même endroit que master. Comme master est plus idiomatiquement Git, voici comment supprimer la branche supplémentaire :

La dernière chose à faire est d’ajouter votre nouveau serveur Git en tant que serveur distant et pousser vers lui. Voici un exemple d’ajout de votre serveur en tant que serveur distant :

Puisque vous voulez que vos branches et étiquettes montent, vous pouvez maintenant lancer :

Toutes vos branches et étiquettes devraient être sur votre nouveau serveur Git dans un import joli et propre.

Puisque Mercurial et Git ont des modèles assez similaires pour représenter les versions, et puisque Git est un peu plus flexible, convertir un dépôt depuis Mercurial vers Git est assez simple, en utilisant un outil appelé "hg-fast-export", duquel vous aurez besoin d’une copie :

La première étape dans la conversion est d’obtenir un clone complet du dépôt Mercurial que vous voulez convertir :

L’étape suivante est de créer un fichier d’association d’auteur. Mercurial est un peu plus indulgent que Git pour ce qu’il mettra dans le champ auteur pour les modifications, donc c’est le bon moment pour faire le ménage. La génération de ceci tient en une ligne de commande dans un shell bash :

Cela prendra quelques secondes, en fonction de la longueur de l’historique de votre projet, et ensuite le fichier /tmp/authors ressemblera à quelque chose comme ceci :

Dans cet exemple, la même personne (Bob) a créé des modifications sous différents noms, dont l’un est correct, et dont un autre est complètement invalide pour un commit Git. Hg-fast-import nous laisse régler cela en transformant chaque ligne en règle : "<source>"="<cible>", qui transforme une `<source> en <cible>. Dans les chaînes <source> et <cible>, toutes les séquences d’échappement supportées par la fonction python string_escape sont prises en charge. Si le fichier de transformation d’auteurs ne contient pas de correspondance avec <source>, cet auteur sera envoyé à Git sans modification. Dans cet exemple, nous voulons que notre fichier ressemble à cela :

Le même type de fichier de correspondance peut être utilisé pour renommer les branches et les étiquettes lorsque le nom Mercurial n’est pas permis dans Git.

L’étape suivante consiste à créer notre nouveau dépôt Git, et à lancer le script d’export :

L’option -r indique à hg-fast-export où trouver le dépôt Mercurial que l’on veut convertir, et l’option -A lui indique où trouver le fichier de correspondance d’auteur. Le script analyse les modifications Mercurial et les convertit en un script pour la fonctionnalité "fast-import" de Git (que nous détaillerons un peu plus tard). Cela prend un peu de temps (bien que ce soit beaucoup plus rapide que si c’était à travers le réseau), et la sortie est assez verbeuse :

C’est à peu près tout ce qu’il y a. Toutes les étiquettes Mercurial ont été converties en étiquettes Git, et les branches et marques-page Mercurial ont été convertis en branches Git. Maintenant vous êtes prêt à pousser le dépôt vers son nouveau serveur d’hébergement :

Le système suivant dont vous allez voir l’importation est Perforce. Ainsi que nous l’avons dit plus haut, il y a deux façons de permettre de faire parler Git et Perforce l’un avec l’autre : git-p4 et Perforce Git Fusion.

Si votre système n’est pas un de ceux ci-dessus, vous devriez chercher un importateur en ligne – des importateurs de qualité sont disponibles pour plein d’autres systèmes, incluant CVS, Clear Case, Visual Source Safe, même un dossier d’archives. Si aucun de ces outils ne fonctionne pour vous, vous avez un outil plus obscur, ou alors vous avez besoin d’un procédé d’importation personnalisé, vous devriez utiliser git fast-import. Cette commande lit des instructions simples depuis l’entrée standard pour écrire des données Git spécifiques. Il est bien plus facile de créer des objets Git de cette façon que de lancer des commandes Git brutes ou que d’essayer d’écrire les objets bruts (voir Les tripes de Git pour plus d’informations). De cette façon, vous pouvez écrire un script d’importation qui lit l’information nécessaire hors du système duquel vous importez et qui affiche les instructions directement dans la sortie standard. Vous pouvez alors lancer ce programme et envoyer sa sortie à travers un tube dans git fast-import.

Pour démontrer rapidement, vous écrirez un importateur simple. Supposez que vous travaillez dans current, vous sauvegardez votre projet en copiant occasionnellement le dossier dans un dossier de sauvegarde estampillé de la date back_YYYY_MM_DD, et vous voulez importer cela dans Git. Votre structure de dossier ressemble à ceci :

Pour importer un dossier Git, vous devez passer en revue comment Git stocke ses données. Comme vous vous le rappelez, Git est fondamentalement une liste liée d’objets commit qui pointent sur un instantané de contenu. Tout ce que vous avez à faire est de dire à fast-import ce que sont les instantanés de contenu, quelles données de commit pointent sur eux, et l’ordre dans lequel ils vont. Votre stratégie sera d’explorer les instantanés un à un et créer les commits avec les contenus dans chaque dossier, en liant chaque commit avec le précédent.

Comme nous l’avons fait dans Exemple de politique gérée par Git, nous écrirons ceci en Ruby, parce que c’est ce avec quoi nous travaillons généralement et ça a tendance à être facile à lire. Vous pouvez écrire cet exemple assez facilement avec n’importe quel langage de programmation auquel vous êtes familier – il faut seulement afficher l’information appropriée dans stdout. Et, si vous travaillez sous Windows, cela signifie que vous devrez prendre un soin particulier à ne pas introduire de retour chariot (carriage return, CR) à la fin de vos lignes – git fast-import est très exigeant ; il accepte seulement la fin de ligne (Line Feed, LF) et pas le retour chariot fin de ligne (CRLF) que Windows utilise.

Pour commencer, vous vous placerez dans le dossier cible et identifierez chaque sous-dossier, chacun étant un instantané que vous voulez importer en tant que commit. Vous vous placerez dans chaque sous-dossier et afficherez les commandes nécessaires pour l’exporter. Votre boucle basique principale ressemble à ceci :

Vous lancez print_export à l’intérieur de chaque dossier, qui prend le manifeste et la marque de l’instantané précédent et retourne la marque et l’empreinte de celui-ci ; de cette façon, vous pouvez les lier proprement. `Marque'' est le terme de `fast-import pour un identifiant que vous donnez à un commit ; au fur et à mesure que vous créez des commits, vous donnez à chacun une marque que vous pouvez utiliser pour le lier aux autres commits. Donc, la première chose à faire dans votre méthode print_export est de générer une marque à partir du nom du dossier :

Vous ferez ceci en créant un tableau de dossiers et en utilisant la valeur d’index comme marque, car une marque doit être un nombre entier. Votre méthode ressemble à ceci :

Maintenant que vous avez une représentation par un entier de votre commit, vous avez besoin d’une date pour les métadonnées du commit. Puisque la date est exprimée dans le nom du dossier, vous l’analyserez. La ligne suivante dans votre fichier print_export est

où convert_dir_to_date est définie comme

Cela retourne une valeur entière pour la date de chaque dossier. Le dernier bout de méta-information dont vous avez besoin pour chaque commit est la donnée de l’auteur, que vous codez en dur dans une variable globale :

Maintenant vous êtes prêt à commencer à publier l’information de commit pour votre importateur. L’information initiale déclare que vous êtes en train de définir un objet commit et sur quelle branche il est, suivi de la marque que vous avez générée, l’information d’auteur et le message de commit, et ensuite le précédent commit, s’il y en a un. Le code ressemble à ceci :

Vous codez en dur le fuseau horaire (-0700) parce que c’est facile de faire ainsi. Si vous importez depuis un autre système, vous devez spécifier le fuseau horaire comme décalage. Le message de commit doit être exprimé dans un format spécial :

Le format est constitué du mot data, de la taille de la donnée à lire, d’une nouvelle ligne et finalement de la donnée. Comme vous avez besoin d’utiliser le même format pour spécifier le contenu du fichier plus tard, vous créez une méthode assistante, export_data :

Tout ce qui reste à faire est de spécifier le contenu du fichier pour chaque instantané. C’est facile, car vous les avez dans un dossier – vous pouvez imprimer la commande deleteall suivie par le contenu de chaque fichier du dossier. Git enregistrera ensuite chaque instantané de manière appropriée :

Note : Comme beaucoup de systèmes conçoivent leurs révisions comme des changements d’un commit à l’autre, fast-import peut aussi prendre des commandes avec chaque commit pour spécifier quels fichiers ont été ajoutés, supprimés ou modifiés et ce qu’est le nouveau contenu. Vous pourriez calculer les différences entre instantanés et fournir seulement cette donnée, mais faire ainsi est plus complexe – vous pouvez aussi bien donner à Git toutes les données et le laisser faire. Si cela convient mieux pour vos données, référez-vous à la page de manuel fast-import pour les détails sur la manière de fournir les données de cette façon.

Le format pour lister le contenu d’un nouveau fichier ou pour spécifier un fichier modifié avec le nouveau contenu est le suivant :

Ici, 644 est le mode (si vous avez des fichiers exécutables, vous devez le détecter et spécifier 755 à la place), et inline dit que vous listerez le contenu immédiatement après cette ligne. Votre méthode inline_data ressemble à ceci :

Vous réutilisez la méthode export_data que vous avez définie plus tôt, parce que c’est de la même façon que vous avez spécifié vos données du message de commit.

La dernière chose que vous avez besoin de faire est de retourner la marque courante pour qu’elle soit passée à la prochaine itération :

Et voilà. Voici le script dans son intégralité :

Si vous lancez ce script, vous obtiendrez un contenu qui ressemble à peu près à ceci :

Pour lancer l’importateur, envoyez à travers un tube cette sortie à git fast-import pendant que vous êtes dans le dossier Git dans lequel vous voulez importer. Vous pouvez créer un nouveau dossier et ensuite exécuter git init à l’intérieur de celui-ci comme point de départ, et ensuite exécuter votre script :

Comme vous pouvez le voir, lorsque c’est terminé avec succès, il vous donne un lot de statistiques sur ce qu’il a fait. Dans ce cas-ci, vous avez importé un total de 13 objets pour 4 commits dans une branche. Maintenant, vous pouvez lancer git log pour voir votre nouvel historique :

Vous y voilà — un dépôt Git beau et propre. Il est important de noter que rien n’est extrait – vous n’avez d’abord aucun fichier dans votre répertoire de travail. Pour les obtenir, vous devez réinitialiser votre branche là où master est maintenant :

Vous pouvez faire beaucoup plus avec l’outil fast-import – manipuler différents modes, les données binaires, les branches multiples et la fusion, les étiquettes, les indicateurs de progression, et plus encore. Nombre d’exemples de scénarios plus complexes sont disponibles dans le dossier contrib/fast-import du code source Git.