Migrer vers Mercurial

belaran@970: bos@559: bos@686: bos@687: belaran@970: Migrer vers Mercurial belaran@970: belaran@970: Une manière courante de s'essayer à un nouveau JeanMarieClement@974: gestionnaire de révisions est d'expérimenter en migrant un belaran@970: projet existant, plutôt que le faire avec un nouveau projet. belaran@970: belaran@970: belaran@970: Dans cette annexe, nous discuterons comment importer belaran@970: l'historique d'un projet dans Mercurial, et à quoi faire attention youshe@984: si vous êtes habitués à un autre outil de gestion de révisions. belaran@970: bos@686: bos@686: belaran@970: Importer l'historique depuis un autre système belaran@970: belaran@970: Mercurial est livré avec une extension nommée JeanMarieClement@974: convert, qui permet d'importer un historique JeanMarieClement@974: depuis les gestionnaire de révisions les plus courants. Au moment de belaran@970: l'écriture de ce livre, il pouvait importer l'historique depuis: belaran@970: bos@686: bos@686: bos@691: Subversion bos@691: bos@691: bos@691: CVS bos@691: bos@691: bos@691: git bos@691: bos@691: bos@691: Darcs bos@691: bos@691: bos@691: Bazaar bos@691: bos@691: bos@691: Monotone bos@691: bos@691: bos@691: GNU Arch bos@691: bos@691: bos@691: Mercurial bos@686: bos@686: bos@686: belaran@970: (Pour savoir pourquoi Mercurial lui même est supporté JeanMarieClement@974: comme source, voir .) belaran@970: belaran@970: Vous pouvez activer l'extension de la manière JeanMarieClement@974: habituelle, en éditant votre fichier ~/.hgrc bos@686: bos@686: [extensions] bos@686: convert = bos@686: belaran@970: Ceci rendra la commande hg convert belaran@970: disponible. La commande est facile à utiliser. Par exemple, la belaran@970: commande suivante va importer l'historique Subversion du framework de test Nose Unit dans Mercurial. belaran@970: bos@686: bos@686: $ hg convert http://python-nose.googlecode.com/svn/trunk bos@686: belaran@970: L'extension convert opère de JeanMarieClement@974: manière incrémentale. En d'autres mots, après une première exécution de JeanMarieClement@974: la commande hg convert, les exécutions ultérieures JeanMarieClement@974: importeront les révisions ultérieures à l'exécution précédente. youshe@984: La conversion incrémentale ne réussira que si belaran@970: vous exécutez hg convert dans le même dépôt que vous JeanMarieClement@974: aviez utilisé à l'origine, ceci parce que l'extension convert JeanMarieClement@974: sauvegarde un certain nombre de méta-données privées dans le fichier JeanMarieClement@974: .hg/shamap (non versioné) au sein du dépôt cible. belaran@970: belaran@970: JeanMarieClement@974: Lorsque vous voulez faire des modifications en utilisant belaran@970: Mercurial, le mieux est de faire un clone de l'ensemble de l'arborescence JeanMarieClement@974: que vous souhaitez convertir, et de laisser l'arborescence d'origine pour JeanMarieClement@974: de futures conversions incrémentales. C'est la manière la plus sûre pour vous laisser JeanMarieClement@974: récupérer et fusionner les modifications futures depuis l'outil de gestion JeanMarieClement@974: de révisions dans votre nouveau dépôt Mercurial. bos@693: bos@693: belaran@970: Convertir plusieurs branches belaran@970: JeanMarieClement@974: La commande hg convert citée JeanMarieClement@974: ci-dessus convertit seulement l'historique de la branche JeanMarieClement@974: principale (trunk) du dépôt Subversion. Si nous utilisons belaran@970: à la place l'URL http://python-nose.googlecode.com/svn, JeanMarieClement@974: Mercurial va automatiquement détecter la belaran@970: branche principale (trunk), les étiquettes youshe@984: (tags), et les branches que les dépôts JeanMarieClement@974: Subversion utilisent généralement, et les importera chacun dans belaran@970: une branche Mercurial distincte. belaran@970: belaran@970: Par défaut, chaque branche Subversion importée JeanMarieClement@974: dans Mercurial se voit attribuer un nom de branche. Une fois la JeanMarieClement@974: conversion achevée, vous pouvez obtenir la liste des noms des branches belaran@970: actives dans le dépôt Mercurial en utilisant la commande belaran@970: hg branches -a. Si vous préférez importer les belaran@970: branches Subversion sans noms, ajoutez l'option à la commande belaran@970: hg convert. belaran@970: JeanMarieClement@974: Une fois votre arborescence convertie, JeanMarieClement@974: si vous souhaitez travailler selon la pratique habituelle sous Mercurial JeanMarieClement@974: avec une arborescence qui ne contient qu'une seule branche, vous pouvez cloner JeanMarieClement@974: cette seule branche en utilisant belaran@970: hg clone -r nomdemabranche. bos@693: bos@693: bos@686: belaran@970: Associer les noms d'utilisateurs belaran@970: JeanMarieClement@974: Certains outils de gestion de révisions JeanMarieClement@974: ne sauvegardent, avec les modifications, que les noms JeanMarieClement@974: d'utilisateurs raccourcis. Ceux-ci peuvent être difficiles à JeanMarieClement@974: interpréter. La norme avec Mercurial est de sauvegarder le JeanMarieClement@974: nom du committeur et son adresse belaran@970: mail, ce qui est beaucoup plus utile pour discuter avec lui belaran@970: par la suite. belaran@970: belaran@970: Si vous convertissez une arborescence depuis JeanMarieClement@974: un gestionnaire de révisions qui utilise seulement les noms JeanMarieClement@974: raccourcis, vous pouvez associer ces noms à des équivalents belaran@970: plus détaillés en passant l'option belaran@970: à la commande hg convert. Cette option JeanMarieClement@974: attend un fichier qui contient des entrées sous la forme suivante: belaran@970: bos@686: bos@686: arist = Aristotle <aristotle@phil.example.gr> bos@686: soc = Socrates <socrates@phil.example.gr> bos@686: belaran@970: Quand convert trouve une JeanMarieClement@974: modification associée au nom arist dans le belaran@970: dépôt de source, il va utiliser le nom Aristotle belaran@970: <aristotle@phil.example.gr> dans les révisions belaran@970: Mercurial. Si aucune correspondance n'est trouvé, il utilise belaran@970: le nom tel quel. bos@686: bos@686: bos@686: belaran@970: Nettoyer l'arboresence belaran@970: JeanMarieClement@974: Tous les projets n'ont pas un historique parfait. JeanMarieClement@974: Il peut y avoir des répertoires qui n'auraient jamais dû être ajoutés, JeanMarieClement@974: un fichier qui est trop volumineux, ou même une partie de la JeanMarieClement@974: hiérarchie qui devrait être réorganisée. belaran@970: belaran@970: L'extension convert permet belaran@970: d'utiliser un fichier d'association qui peut JeanMarieClement@974: réorganiser les fichiers et les répertoires dans un projet lors de JeanMarieClement@974: l'importation de son historique. Ceci est utile non seulement quand vous belaran@970: importez l'historique d'un autre gestionnaire de révisions, mais JeanMarieClement@974: aussi pour nettoyer ou réorganiser l'arborescence d'un projet belaran@970: Mercurial. belaran@970: belaran@970: Pour indiquer le fichier d'association, on utilise JeanMarieClement@974: l'option en lui fournissant un nom de belaran@970: fichier. Le fichier d'association contient des lignes de la forme youshe@984: suivante : belaran@970: belaran@970: # Ceci est un commentaire. belaran@970: # Les lignes vides sont ignorées. bos@686: bos@686: include path/to/file bos@686: bos@686: exclude path/to/file bos@686: bos@686: rename from/some/path to/some/other/place bos@686: JeanMarieClement@974: JeanMarieClement@974: La directive include inclut un belaran@970: fichier, ou l'ensemble des fichiers d'un répertoire, dans le dépôt belaran@970: de destination. La directive exclude omet les belaran@970: fichiers ou répertoires du dépôt. Ceci inclut aussi les autres belaran@970: fichiers et répertoires qui ne sont pas explicitement inclus. belaran@970: La directive exclude entraine l'omission JeanMarieClement@974: des fichiers ou répertoires, et autres fichiers qui ne sont pas belaran@970: explicitement inclus. belaran@970: belaran@970: Pour déplacer un fichier ou un répertoire d'un JeanMarieClement@974: emplacement à un autre, utilisez la directive belaran@970: rename. Si vous avez besoin de déplacer un JeanMarieClement@974: fichier ou un répertoire depuis un sous répertoire dans la racine belaran@970: du dépôt, utilisez . comme second argument de belaran@970: la directive rename. bos@686: bos@693: bos@693: JeanMarieClement@974: Améliorer les performances de la conversion Subversion belaran@970: belaran@970: Vous aurez souvent besoin de plusieurs essais JeanMarieClement@974: avant d'arriver à la parfaite combinaison de fichier d'association de fichiers, youshe@984: de fichier d'association de noms d'utilisateurs et des autres paramètres. Or, youshe@984: convertir un dépôt Mercurial via un protocole comme ssh JeanMarieClement@974: ou http peut être des milliers de fois plus long belaran@970: que ce dont le système d'exploitation est en fait capable de faire, belaran@970: à cause des latence réseau. Ceci peut rendre la conception de cette belaran@970: combinaison parfaite très douloureuse. belaran@970: belaran@970: La commande svnsync belaran@970: peut grandement améliorer la vitesse de conversion d'un dépôt belaran@970: Subversion. Il s'agit d'un programme de miroir de dépôt Subversion belaran@970: en lecture seule. L'idée est de créer un miroir local d'une JeanMarieClement@974: arborescence Subversion, puis de convertir ce miroir en dépôt belaran@970: Mercurial. belaran@970: belaran@970: Supposez que nous voulions convertir le dépôt youshe@984: Subversion du populaire projet Memcached en une arborescence Mercurial. JeanMarieClement@974: Tout d'abord, nous créons un dépôt Subversion local. bos@693: bos@693: $ svnadmin create memcached-mirror bos@693: JeanMarieClement@974: Puis, nous allons mettre en place un hook Subversion belaran@970: dont svnsync a besoin. bos@693: bos@693: $ echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change bos@693: $ chmod +x memcached-mirror/hooks/pre-revprop-change bos@693: JeanMarieClement@974: Nous initialisons ensuite svnsync dans ce belaran@970: dépôt. bos@693: bos@693: $ svnsync --init file://`pwd`/memcached-mirror \ bos@693: http://code.sixapart.com/svn/memcached bos@693: belaran@970: La prochaine étape est de commencer le processus de JeanMarieClement@974: mirroring de svnsync. bos@693: bos@693: $ svnsync sync file://`pwd`/memcached-mirror bos@693: belaran@970: Enfin, nous importons l'historique de notre dépôt belaran@970: local Subversion dans Mercurial. bos@693: bos@693: $ hg convert memcached-mirror bos@693: belaran@970: Nous pouvons utiliser ce processus de manière belaran@970: incrémentale, si le dépôt Subversion est toujours en activité. belaran@970: Il suffit d'exécuter de nouveau svnsync pour JeanMarieClement@974: récupérer les récentes modifications dans notre miroir, puis hg JeanMarieClement@974: convert youshe@984: les importe dans notre arborescence Mercurial. belaran@970: belaran@970: Il y a deux avantages à utiliser un import à deux JeanMarieClement@974: étages comme avec svnsync. Le premier JeanMarieClement@974: est qu'il utilise du code de synchronisation réseau de Subversion JeanMarieClement@974: plus efficace que la commande hg convert, JeanMarieClement@974: et donc transfère moins de données par le réseau. Le deuxième JeanMarieClement@974: est que l'import depuis un dépôt Subversion local est si rapide que JeanMarieClement@974: vous pouvez peaufiner et réitérer les paramètres de conversion de youshe@984: ce dernier sans souffrir de la qualité de la connexion réseau. bos@693: bos@686: bos@686: bos@686: JeanMarieClement@974: Migrer depuis Subversion JeanMarieClement@974: JeanMarieClement@974: Subversion est le système de gestion de versions JeanMarieClement@974: open source le plus populaire aujourd'hui. Bien qu'il y ait des belaran@970: différences entre Mercurial et Subversion, faire la transition de belaran@970: l'un à l'autre n'est pas très difficile. Les deux disposent en effet JeanMarieClement@974: de jeux de commandes similaires et d'interfaces similaires. bos@686: bos@686: belaran@970: Différences philosophiques belaran@970: belaran@970: La différence fondamentale entre Subversion et belaran@970: Mercurial est bien évidement que Subversion est centralisé, alors belaran@970: que Mercurial est distribué. Puisque que Mercurial enregistre tout belaran@970: l'historique d'un projet sur votre disque dur local, il n'a besoin JeanMarieClement@974: d'effectuer des accès au réseau que lorsque vous voulez JeanMarieClement@974: explicitement communiquer avec un autre dépôt. Subversion, par contre, youshe@984: ne conserve que peu d'informations localement, et le client JeanMarieClement@974: doit donc communiquer avec le serveur central pour la belaran@970: plupart des opérations communes. belaran@970: JeanMarieClement@974: Subversion s'en tire plus ou moins bien sans notion JeanMarieClement@974: de branche réellement bien définie : quelle portion de l'espace de nommage belaran@970: du serveur est une branche est une simple question de convention, le JeanMarieClement@974: logiciel n'imposant rien à ce sujet. Mercurial considère JeanMarieClement@974: un dépôt comme un élément de la gestion des branches. belaran@970: bos@686: belaran@970: Portée des commandes belaran@970: belaran@970: Puisque que Subversion ne sait pas réellement belaran@970: quelle partie de son espace de nommage est en fait une branche, il belaran@970: traite la plupart des commandes comme des requêtes à exécuter sur le belaran@970: répertoire où vous vous situez, et ses sous répertoires. Par exemple, JeanMarieClement@978: si vous exécutez svn log, vous verrez l'historique youshe@984: de la partie de l'arborescence où vous vous situez, et non de la belaran@970: hiérarchie entière. belaran@970: belaran@970: Les commandes de Mercurial ont un comportement youshe@984: différent : toutes les commandes s'appliquent à l'ensemble de l'arborescence belaran@970: du dépôt. Exécutez la commande hg log et elle vous youshe@984: donnera l'historique de l'ensemble de l'arborescence, quel que soit le JeanMarieClement@978: sous-répertoire où vous vous situez. Si JeanMarieClement@978: vous souhaitez obtenir l'historique d'un répertoire ou seulement d'un JeanMarieClement@978: fichier, ajouter simplement le nom de celui-ci à la commande, par JeanMarieClement@978: exemple hg log src. belaran@970: belaran@970: De ma propre expérience, cette différence dans leur youshe@984: comportement par défaut est probablement ce qui risque de vous youshe@984: surprendre le plus si vous passez régulièrement d'un outil à l'autre. bos@686: bos@686: bos@686: belaran@970: Opération multi utilisateur et sécurité belaran@970: belaran@970: Avec Subversion, il est normal (bien que légèrement JeanMarieClement@978: désapprouvé) que différentes personnes collaborent sur une seule belaran@970: branche. Si Alice et Bob travaillent ensemble, et Alice ajoute ses youshe@984: modifications à leur branche partagée, Bob doit alors mettre à jour JeanMarieClement@978: sa vue de la branche avant de pouvoir appliquer un commit. JeanMarieClement@978: Puisqu'il n'a, à ce moment, pas effectué de commit JeanMarieClement@978: des modifications qu'il a faites, il se peut qu'il ne corrompe JeanMarieClement@978: ou ne perde JeanMarieClement@978: ses modifications pendant ou après la mise à jour. belaran@970: belaran@970: Mercurial encourage, à l'inverse, un modèle JeanMarieClement@978: "commit-puis-merge". Avant de récupérer des modifications depuis le JeanMarieClement@978: serveur, ou avant d'y envoyer les siennes, Bob enregistre ses JeanMarieClement@978: modifications de manière locale en appliquant un commit. C'est à dire JeanMarieClement@978: que si Alice avait envoyé ses modifications sur le serveur avant JeanMarieClement@978: que Bob n'envoie les siennes, ce dernier ne pourra le faire JeanMarieClement@978: qu'après avoir récupéré et fusionné celles d'Alice avec les siennes. JeanMarieClement@978: Si Bob fait alors une JeanMarieClement@978: erreur lors de la fusion, il pourra toujours restaurer sa version, pour JeanMarieClement@978: laquelle il avait appliqué le commit. belaran@970: belaran@970: Il est important de souligner qu'il s'agit de la JeanMarieClement@978: manière habituelle de travailler avec ces outils. Subversion propose JeanMarieClement@978: une manière plus sûre de "travailler-dans-votre-propre-branche", mais elle JeanMarieClement@978: est assez complexe pour que, en pratique, elle ne soit que rarement utilisé. JeanMarieClement@978: Mercurial propose de son côté un mode un peu moins sûr, permettant de belaran@970: récupérer des modifications par dessus des modifications non youshe@984: committées, qui reste toutefois très peu répandu. bos@686: bos@686: bos@686: belaran@970: Publication vs changement locaux belaran@970: belaran@970: Une commande Subversion svn belaran@970: commit publie immédiatement les modifications sur le JeanMarieClement@978: serveur, où elles peuvent être vu par n'importe qui doté d'un privilège belaran@970: de lecture. belaran@970: JeanMarieClement@978: Avec Mercurial, les modifications sont toujours d'abord JeanMarieClement@978: enregistrées localement, et doivent être par la suite transférés par belaran@970: la commande hg push. belaran@970: youshe@984: Chaque approche a ses avantages et ses inconvénients. JeanMarieClement@978: Le modèle Subversion implique que les modifications soient publiées, et JeanMarieClement@978: donc disponibles immédiatement. D'un autre coté, cela implique aussi JeanMarieClement@978: que, pour pouvoir utiliser le logiciel normalement, un utilisateur doit JeanMarieClement@978: avoir les droits d'écriture dans le dépôt, et ce privilège n'est pas concédé JeanMarieClement@978: facilement par la plupart des projets Open Source. belaran@970: youshe@984: L'approche de Mercurial permet à quiconque de faire belaran@970: un clone du dépôt et d'y ajouter ses modifications sans jamais avoir youshe@984: besoin de la permission de quiconque, et l'on peut même publier ses JeanMarieClement@978: modifications et continuer à participer comme on le désire. Toutefois, la JeanMarieClement@978: distinction entre les commits et le transfert de ces derniers présente JeanMarieClement@978: le risque que quelqu'un applique ses modifications par un commit local JeanMarieClement@978: sur son portable et parte se promener pendant quelques jours en ayant JeanMarieClement@978: oublié de les transférer, ce qui peut, dans certains rares cas, JeanMarieClement@978: bloquer temporairement ses collaborateurs. bos@686: bos@686: bos@686: bos@686: belaran@970: Références des commandes bos@686: bos@686: belaran@970: Commandes Subversion et leurs équivalents Mercurial bos@686: bos@686: bos@686: bos@686: Subversion bos@686: Mercurial bos@686: Notes bos@686: bos@686: bos@686: bos@686: bos@686: svn add bos@686: hg add bos@686: bos@686: bos@686: bos@686: svn blame bos@686: hg annotate bos@686: bos@686: bos@686: bos@686: svn cat bos@686: hg cat bos@686: bos@686: bos@686: bos@686: svn checkout bos@686: hg clone bos@686: bos@686: bos@686: bos@686: svn cleanup bos@686: n/a belaran@970: Aucun nettoyage nécessaire. bos@686: bos@686: bos@686: svn commit bos@686: hg commit; hg bos@686: push belaran@970: hg push publie les modifications JeanMarieClement@978: après un commit. bos@686: bos@686: bos@686: svn copy bos@686: hg clone belaran@970: Pour créer une nouvelle branche bos@686: bos@686: bos@686: svn copy bos@686: hg copy belaran@970: Pour copier des fichiers ou des répertoires bos@686: bos@686: bos@686: svn delete (svn bos@686: remove) bos@686: hg remove bos@686: bos@686: bos@686: bos@686: svn diff bos@686: hg diff bos@686: bos@686: bos@686: bos@686: svn export bos@686: hg archive bos@686: bos@686: bos@686: bos@686: svn help bos@686: hg help bos@686: bos@686: bos@686: bos@686: svn import bos@686: hg addremove; hg bos@686: commit bos@686: bos@686: bos@686: bos@686: svn info bos@686: hg parents JeanMarieClement@978: Affiche la version sur la base de laquelle on travaille bos@686: bos@686: bos@686: svn info bos@686: hg showconfig JeanMarieClement@978: paths.default belaran@970: Affiche de quelle URL est extrait ce dépôt bos@686: bos@686: bos@686: svn list bos@686: hg manifest bos@686: bos@686: bos@686: bos@686: svn log bos@686: hg log bos@686: bos@686: bos@686: bos@686: svn merge bos@686: hg merge bos@686: bos@686: bos@686: bos@686: svn mkdir bos@686: n/a belaran@970: Mercurial ne versionne pas les répertoires bos@686: bos@686: bos@686: svn move (svn bos@686: rename) bos@686: hg rename bos@686: bos@686: bos@686: bos@686: svn resolved bos@686: hg resolve -m bos@686: bos@686: bos@686: bos@686: svn revert bos@686: hg revert bos@686: bos@686: bos@686: bos@686: svn status bos@686: hg status bos@686: bos@686: bos@686: bos@686: svn update bos@686: hg pull -u bos@686: bos@686: bos@686: bos@686: bos@686:

bos@686: bos@686: bos@686: bos@686: belaran@970: Conseils utiles pour les débutants belaran@970: JeanMarieClement@978: Avec la plupart des gestionnaire de versions, afficher belaran@970: un diff associé à une révision peut être assez douloureux. Par exemple, belaran@970: avec Subversion, pour voir ce qui a été modifiée dans la révision 104654, belaran@970: vous devez saisir svn diff -r104653:104654. Mercurial belaran@970: élimine le besoin de saisir l'identifiant d'une révision deux fois dans belaran@970: ce cas classique. Pour un simple diff, hg JeanMarieClement@978: export 104654 suffit. Pour obtenir une entrée du journal suivie d'un diff, JeanMarieClement@978: hg log -r104654 -p. belaran@970: belaran@970: Quand vous exécutez la commande hg status youshe@984: sans aucun arguments, elle affiche l'état de l'ensemble de l'arborescence, youshe@984: avec des chemins relatifs partant de la racine du dépôt. Ceci rend belaran@970: difficile de copier un nom de fichier depuis la sortie de la commande belaran@970: hg status dans une autre ligne de commande. Si vous belaran@970: fournissez un fichier ou un répertoire à la commande hg belaran@970: status, elle va afficher les chemins relatif depuis votre belaran@970: répertoire courant à la place. Ainsi, pour avoir un état sur l'ensemble youshe@984: de l'arborescence à l'aide de hg status, avec des youshe@984: chemins relatifs à votre répertoire courant, et non la racine du dépôt, belaran@970: ajoutez la sortie de hg root à la commande belaran@970: hg status. Vous pouvez le faire aisément sur un belaran@970: système Unix ainsi : bos@686: bos@686: $ hg status `hg root` bos@686: bos@559: bos@559: bos@559: