Migrating to Mercurial

# HG changeset patch # User Romain PELISSE # Date 1250522604 -7200 # Node ID 030ccd6c5474939abef19dfb1078459e381472a4 # Parent 108c5ecc8232687fca0bb7958527dfff67064a94 Finishing translation for appA-svn diff -r 108c5ecc8232 -r 030ccd6c5474 fr/appA-svn.xml --- a/fr/appA-svn.xml Sun Aug 16 18:08:05 2009 +0200 +++ b/fr/appA-svn.xml Mon Aug 17 17:23:24 2009 +0200 @@ -1,25 +1,27 @@ - + -Migrating to Mercurial - - A common way to test the waters with a new revision control - tool is to experiment with switching an existing project, rather - than starting a new project from scratch. - - In this appendix, we discuss how to import a project's history - into Mercurial, and what to look out for if you are used to a - different revision control system. +Migrer vers Mercurial + + Une manière courante de s'essayer à un nouveau + gestionnaire de révisions est d'expérimenter consiste à migrer un + projet existant, plutôt que le faire avec un nouveau projet. + + + Dans cette annexe, nous discuterons comment importer + l'historique d'un projet dans Mercurial, et à quoi faire attention + si vous êtes habitué à un autre outils de gestion de révisions. + - Importing history from another system - - Mercurial ships with an extension named - convert, which can import project history - from most popular revision control systems. At the time this - book was written, it could import history from the following - systems: + Importer l'historique depuis un autre système + + Mercurial est livré avec une extension nommée + convert, qui permet d'importer son historique + depuis les gestionnaire de révisions les plus courants. Lors de + l'écriture de ce livre, il pouvait importer l'historique depuis: + Subversion @@ -47,117 +49,123 @@ - (To see why Mercurial itself is supported as a source, see - .) - - You can enable the extension in the usual way, by editing - your ~/.hgrc file. + (Pour savoir pourquoi Mercurial lui même est supporté + comme source, voir, see .) + + Vous pouvez activer l'extension de la manière + habituelle, en éditant votre fichier ~/.hgrc file. [extensions] convert = - This will make a hg convert command - available. The command is easy to use. For instance, this - command will import the Subversion history for the Nose unit - testing framework into Mercurial. + Ceci rendra la commande hg convert + disponible. La commande est facile à utiliser. Par exemple, la + commande suivante va importer l'historique Subversion du framework de test Nose Unit dans Mercurial. + $ hg convert http://python-nose.googlecode.com/svn/trunk - The convert extension operates - incrementally. In other words, after you have run hg - convert once, running it again will import any new - revisions committed after the first run began. Incremental - conversion will only work if you run hg - convert in the same Mercurial repository that you - originally used, because the convert - extension saves some private metadata in a - non-revision-controlled file named - .hg/shamap inside the target - repository. - - When you want to start making changes using Mercurial, it's - best to clone the tree in which you are doing your conversions, - and leave the original tree for future incremental conversions. - This is the safest way to let you pull and merge future commits - from the source revision control system into your newly active - Mercurial project. + L'extension convert opère de + manière incrémentale. En d'autres mots, après que vous ayez exécuter + la commande hg convert une première fois, l'exécuter + de nouveau importera les nouvelles révisions, ajoutées depuis votre + précédente exécution. La conversion incrémentale ne réussiera que si + vous exécutez hg convert dans le même dépôt que vous + aviez utilisé à l'origine car l'extension convert + sauvegarde un certains nombres de méta-données privées dans le fichier, + non versioné, .hg/shamap, au sein du dépôt cible. + + + Quand vous voulez faire des modifications en utilisant + Mercurial, le mieux est de faire un clone de l'ensemble de l'arborescence + que vous souhaitez convertir, et laisser l'arborescence d'origine pour + des conversions futures. C'est la manière la plus sûr pour vous laisser + récupérer et fusionner les modifications futures depuis la gestionnaire de + révisions source dans votre dépôt Mercurial. - Converting multiple branches - - The hg convert command given above - converts only the history of the trunk - branch of the Subversion repository. If we instead use the - URL http://python-nose.googlecode.com/svn, - Mercurial will automatically detect the - trunk, tags and - branches layout that Subversion projects - usually use, and it will import each as a separate Mercurial - branch. - - By default, each Subversion branch imported into Mercurial - is given a branch name. After the conversion completes, you - can get a list of the active branch names in the Mercurial - repository using hg branches -a. If you - would prefer to import the Subversion branches without names, - pass the option to - hg convert. - - Once you have converted your tree, if you want to follow - the usual Mercurial practice of working in a tree that - contains a single branch, you can clone that single branch - using hg clone -r mybranchname. + Convertir plusieurs branches + + La commande hg convert cité + ci dessus converti seulement l'historique de la branche + principal (trunk) du dépôt Subversion. Si vous utilisons + à la place l'URL http://python-nose.googlecode.com/svn, + Mercurial va automatiquement détecter les répertoires + branche principale (trunk), les étiquettes + (tags), et les branches que les dépôt + Subversion utilisent généralement, et il va les importer chacun dans + une branche Mercurial distincte. + + Par défaut, chaque branche Subversion importée + dans Mercurial se voit attribué un nom de branche. Une fois la + conversion achevée, vous pouvez lister les noms des branches + actives dans le dépôt Mercurial en utilisant la commande + hg branches -a. Si vous préférez importer les + branches Subversion sans noms, ajoutez l'option à la commande + hg convert. + + Une fois que vous avez converti votre arborescence, + si vous voulez suivre la pratique habituel avec Mercurial dans une + arborescence qui ne contient qu'une seule branche, vous pouvez cloner + une seule branche en utilisant + hg clone -r nomdemabranche. - Mapping user names - - Some revision control tools save only short usernames with - commits, and these can be difficult to interpret. The norm - with Mercurial is to save a committer's name and email - address, which is much more useful for talking to them after - the fact. - - If you are converting a tree from a revision control - system that uses short names, you can map those names to - longer equivalents by passing a - option to hg convert. This option accepts - a file name that should contain entries of the following - form. + Associer les noms d'utilisateurs + + Certains système de gestion de révisions + ne sauvegarde, avec les modifications transférées, que les noms + d'utilisateurs raccourcis et ceci peuvent être difficile à + intépréter. La norme avec Mercurial est de sauvegarder le + nom du committer et son adresse + mail, ce qui est beaucoup plus utile pour discuter avec lui + par la suite. + + Si vous convertissez une arborescence depuis + un gestionnaire de révisions qui utilisent seulement les noms + raccourcies, vous pouvez associer ces noms à des équivalents + plus détaillés en passant l'option + à la commande hg convert. Cette option + attend un fichier qui contient des entrées de la forme suivante: + arist = Aristotle <aristotle@phil.example.gr> soc = Socrates <socrates@phil.example.gr> - Whenever convert encounters a commit - with the username arist in the source - repository, it will use the name Aristotle - <aristotle@phil.example.gr> in the converted - Mercurial revision. If no match is found for a name, it is - used verbatim. + Quand convert trouve une + modification associé au nom arist dans le + dépôt de source, il va utiliser le nom Aristotle + <aristotle@phil.example.gr> dans les révisions + Mercurial. Si aucune correspondance n'est trouvé, il utilise + le nom tel quel. - Tidying up the tree - - Not all projects have pristine history. There may be a - directory that should never have been checked in, a file that - is too big, or a whole hierarchy that needs to be - refactored. - - The convert extension supports the idea - of a file map that can reorganize the files and - directories in a project as it imports the project's history. - This is useful not only when importing history from other - revision control systems, but also to prune or refactor a - Mercurial tree. - - To specify a file map, use the - option and supply a file name. A file map contains lines of the - following forms. - - # This is a comment. -# Empty lines are ignored. + Nettoyer l'arboresence + + Tout les projets n'ont pas un historique parfait. + Il peut y avoir des répertoire qui n'auraient jamais dû être ajoutés, + un fichier qui est trop volumineux, ou même une sous partie de la + hiérarchie qui devraient être réorganisée. + + L'extension convert permet + d'utiliser un fichier d'association qui peut + réorganiser les fichiers et les répertoires dans un projet alors + qu'il importe son historique. Ceci est utile non seulement quand vous + importez l'historique d'un autre gestionnaire de révisions, mais + aussi pour nettoyer ou refactorer l'arboresence d'un projet + Mercurial. + + Pour indiquer le fichier d'association, on utilise + l'option en lui fournissant un nom de + fichier. Le fichier d'association contient des lignes de la forme + suivante: + + # Ceci est un commentaire. +# Les lignes vides sont ignorées. include path/to/file @@ -166,203 +174,207 @@ rename from/some/path to/some/other/place - The include directive causes a file, or - all files under a directory, to be included in the destination - repository. This also excludes all other files and dirs not - explicitely included. The exclude - directive causes files or directories to be omitted, and - others not explicitly mentioned to be included. - - To move a file or directory from one location to another, - use the rename directive. If you need to - move a file or directory from a subdirectory into the root of - the repository, use . as the second - argument to the rename directive. + La directive include inclus un + fichier, ou l'ensemble des fichiers d'un répertoire, dans le dépôt + de destination. La directive exclude omet les + fichiers ou répertoires du dépôt. Ceci inclut aussi les autres + fichiers et répertoires qui ne sont pas explicitement inclus. + La directive exclude entraine l'omission + des fichiers ou répertoires, et autres fichiers qui ne sont + explicitement inclus. + + Pour déplacer un fichier ou un répertoire d'un + emplacement à un autre, il faut utiliser la directive + rename. Si vous avez besoin de déplacer un + fichier ou un répertoire depuis un sous répertoire dans la raçine + du dépôt, utilisez . comme second argument de + la directive rename. - Improving Subversion conversion performance - - You will often need several attempts before you hit the - perfect combination of user map, file map, and other - conversion parameters. Converting a Subversion repository - over an access protocol like ssh or - http can proceed thousands of times more - slowly than Mercurial is capable of actually operating, due to - network delays. This can make tuning that perfect conversion - recipe very painful. - - The Améliorer les performances la conversion Subversion + + Vous aurez souvent besoin de plusieurs essais + avant d'arriver à la parfaite combinaison de fichier d'association, + d'association de noms d'utilisateurs et d'autres paramètres. Hors, + convertir un dépôt Mercurial via un protocol comme ssh + or http peut être des milliers de fois plus long + que ce dont le système d'exploitation est en fait capable de faire, + à cause des latence réseau. Ceci peut rendre la conception de cette + combinaison parfaite très douloureuse. + + La commande svnsync - command can greatly speed up the conversion of a Subversion - repository. It is a read-only mirroring program for - Subversion repositories. The idea is that you create a local - mirror of your Subversion tree, then convert the mirror into a - Mercurial repository. - - Suppose we want to convert the Subversion repository for - the popular Memcached project into a Mercurial tree. First, - we create a local Subversion repository. + peut grandement améliorer la vitesse de conversion d'un dépôt + Subversion. Il s'agit d'un programme de miroir de dépôt Subversion + en lecture seule. L'idée est de créer un miroir local d'une + arboresence Subversion, puis de convertir ce miroir en dépôt + Mercurial. + + Supposez que nous voulions convertir le dépôt + Subversion du populaire projet Memcached en une arboresence Mercurial. + Premièrement, nous créons un dépôt Subversion local. $ svnadmin create memcached-mirror - Next, we set up a Subversion hook that - svnsync needs. + Puis, nous allons mettre en place le 'hook' Subversion + dont svnsync a besoin. $ echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change $ chmod +x memcached-mirror/hooks/pre-revprop-change - We then initialize svnsync in this - repository. + Nous initialisons svnsync dans ce + dépôt. $ svnsync --init file://`pwd`/memcached-mirror \ http://code.sixapart.com/svn/memcached - Our next step is to begin the svnsync - mirroring process. + La prochaine étape est de commencer le processus de + miroir de svnsync. $ svnsync sync file://`pwd`/memcached-mirror - Finally, we import the history of our local Subversion - mirror into Mercurial. + Enfin, nous importons l'historique de notre dépôt + local Subversion dans Mercurial. $ hg convert memcached-mirror - We can use this process incrementally if the Subversion - repository is still in use. We run svnsync - to pull new changes into our mirror, then hg - convert to import them into our Mercurial - tree. - - There are two advantages to doing a two-stage import with - svnsync. The first is that it uses more - efficient Subversion network syncing code than hg - convert, so it transfers less data over the - network. The second is that the import from a local - Subversion tree is so fast that you can tweak your conversion - setup repeatedly without having to sit through a painfully - slow network-based conversion process each time. + Nous pouvons utiliser ce processus de manière + incrémentale, si le dépôt Subversion est toujours en activité. + Il suffit d'exécuter de nouveau svnsync pour + récupérer les modifications dans notre miroir, puis hg convert + les importe dans notre arboresence Mercurial. + + Il y a deux avantages à utiliser un import à deux + étages comme avec svnsync. Le premier + est qu'il utilise plus efficassement la synchronisation à travers + le réseau de Subversion que la commande hg convert, + et donc il transfère moins de données à travers ce dernier. La deuxième + est que l'import depuis un dépôt subversion local est si rapide que + vous pouvez améliorer votre conversion de ce dernier, en le répétant + succesivement, sans souffrir de la qualité de la connection + réseau. Migrating from Subversion - Subversion is currently the most popular open source - revision control system. Although there are many differences - between Mercurial and Subversion, making the transition from - Subversion to Mercurial is not particularly difficult. The two - have similar command sets and generally uniform - interfaces. + Subversion est aujourd'hui le plus utilisé des + système de gestion de révision Open Source. Bien qu'il y est des + différences entre Mercurial et Subversion, faire la transition de + l'un à l'autre n'est pas très difficile. Les deux disposent en effet + de jeux de commandes similaires et d'interfaces uniformes. - Philosophical differences - - The fundamental difference between Subversion and - Mercurial is of course that Subversion is centralized, while - Mercurial is distributed. Since Mercurial stores all of a - project's history on your local drive, it only needs to - perform a network access when you want to explicitly - communicate with another repository. In contrast, Subversion - stores very little information locally, and the client must - thus contact its server for many common operations. - - Subversion more or less gets away without a well-defined - notion of a branch: which portion of a server's namespace - qualifies as a branch is a matter of convention, with the - software providing no enforcement. Mercurial treats a - repository as the unit of branch management. - + Différences philosophiques + + La différence fondamentale entre Subversion et + Mercurial est bien évidement que Subversion est centralisé, alors + que Mercurial est distribué. Puisque que Mercurial enregistre tout + l'historique d'un projet sur votre disque dur local, il n'a besoin + d'effectuer des accès au réseau que lorsque vous lui demandez + explicitement de discuter avec un autre dépôt, distant. Par contraste, + Subversion ne conserve que peu d'information localement, et le client + doit donc régulièrement discuter avec le serveur central pour la + plupart des opérations communes. + + Subversion s'en tire plus ou moins bien sans de notion + de branche réellement bien définie : quel part de l'espace de nommage + du serveur est une branche est une simple question de convention, le + logiciel ne fournissant aucune sécurité à ce sujet. Mercurial considère + un dépôt comme une branche. + - Scope of commands - - Since Subversion doesn't know what parts of its - namespace are really branches, it treats most commands as - requests to operate at and below whatever directory you are - currently visiting. For instance, if you run svn - log, you'll get the history of whatever part of - the tree you're looking at, not the tree as a whole. - - Mercurial's commands behave differently, by defaulting - to operating over an entire repository. Run hg - log and it will tell you the history of the - entire tree, no matter what part of the working directory - you're visiting at the time. If you want the history of - just a particular file or directory, simply supply it by - name, e.g. hg log src. - - From my own experience, this difference in default - behaviors is probably the most likely to trip you up if you - have to switch back and forth frequently between the two - tools. + Portée des commandes + + Puisque que Subversion ne sait pas réellement + quelle partie de son espace de nommage est en fait une branche, il + traite la plupart des commandes comme des requêtes à exécuter sur le + répertoire où vous vous situez, et ses sous répertoires. Par exemple, + si vous exécuter svn log, vous verrez l'historique + de la partie de l'arboresence où vous vous situez, et non la + hiérarchie entière. + + Les commandes de Mercurial ont un comportement + différents, appliquant toutes commandes à l'ensemble de l'arboresence + du dépôt. Exécutez la commande hg log et elle vous + donnera l'historique de l'ensemble de l'arboresence, quelque soit le + répertoire de cette dernière où vous vous situez à ce moment là. Si + vous souhaitez l'historique d'une répertoire ou seulement d'un + fichier, ajouter simplement le nom de celui-ci à la commande + hg log src. + + De ma propre expérience, cette différence dans leur + comportement par défaut est probablement ce qui risque de vous + surprendre si vous basculez régulièrement d'un outil à l'autre. - Multi-user operation and safety - - With Subversion, it is normal (though slightly frowned - upon) for multiple people to collaborate in a single branch. - If Alice and Bob are working together, and Alice commits - some changes to their shared branch, Bob must update his - client's view of the branch before he can commit. Since at - this time he has no permanent record of the changes he has - made, he can corrupt or lose his modifications during and - after his update. - - Mercurial encourages a commit-then-merge model instead. - Bob commits his changes locally before pulling changes from, - or pushing them to, the server that he shares with Alice. - If Alice pushed her changes before Bob tries to push his, he - will not be able to push his changes until he pulls hers, - merges with them, and commits the result of the merge. If - he makes a mistake during the merge, he still has the option - of reverting to the commit that recorded his changes. - - It is worth emphasizing that these are the common ways - of working with these tools. Subversion supports a safer - work-in-your-own-branch model, but it is cumbersome enough - in practice to not be widely used. Mercurial can support - the less safe mode of allowing changes to be pulled in and - merged on top of uncommitted edits, but this is considered - highly unusual. + Opération multi utilisateur et sécurité + + Avec Subversion, il est normal (bien que légèrement + désapprouvée) que différentes personnes collaborent sur une seule + branche. Si Alice et Bob travaillent ensemble, et Alice ajoute ses + modications à leur branche partagée, Bob doit alors mettre à jour + la vue de la banche de son client avant d'ajouter lui même ses + modifications. Puisqu'il n'a, à ce moment, aucun enregistrement + permanent des modifications qu'il a fait, il peut corrompre ou perdre + des modifications pendant et après sa mise à jour. + + Mercurial encourage, à l'inverse, un modèle + "commit-puis-merge". Bob ajoute ses modifications de manière locale + avant de récupérer les modifications d'Alice, ou d'envoyer les siennes + au serveur qu'ils partagent. Si Alice envoye ses modifications avant + que Alice n'envoye les siennes, il ne pourra envoyer ses + modifications avant d'avoir récupérer les siennes. Si il fait une + erreur lors de la fusion, il peut toujours à sa version d'origine, + telle qu'elle a été enregistré. + + Il est important de souligner qu'il s'agit de la + manière habituelle de travailler avec ses outils. Subversion propose + une manière plus sûr de travailler-dans-votre-propre-branche, mais il + est assez complexe pour que, en pratique, il ne soit jamais utiliser. + Mercurial propose un mode, un peu moyen sûr, mais permettant de + récupérer des modifications par dessus des modifications non + commitées, mais c'est considéré comme assez inhabituel. - Published vs local changes - - A Subversion svn commit command - immediately publishes changes to a server, where they can be - seen by everyone who has read access. - - With Mercurial, commits are always local, and must be - published via a hg push command - afterwards. - - Each approach has its advantages and disadvantages. The - Subversion model means that changes are published, and hence - reviewable and usable, immediately. On the other hand, this - means that a user must have commit access to a repository in - order to use the software in a normal way, and commit access - is not lightly given out by most open source - projects. - - The Mercurial approach allows anyone who can clone a - repository to commit changes without the need for someone - else's permission, and they can then publish their changes - and continue to participate however they see fit. The - distinction between committing and pushing does open up the - possibility of someone committing changes to their laptop - and walking away for a few days having forgotten to push - them, which in rare cases might leave collaborators - temporarily stuck. + Publication vs changement locaux + + Une commande Subversion svn + commit publie immédiatement les modifications sur le + serveur, où ils peuvent être vu par n'importe qui doté du privilège + de lecture. + + Avec Mercurial, les modifications sont toujours + enregistrées localement, et doivent être par la suite transférer par + la commande hg push. + + Chaque approche à ses avantages et ses désavantages. + Le modèle Subversion implique que les modifications sont publiées, et + donc disponible immédiatement. D'un autre coté, il implique aussi + qu'un utilisateur doit avoir le droit d'écriture dans le dépôt pour + permettre l'utiliser normalement, et ce privilège n'est pas concédé + facilement par les projets Open Source. + + L'approche de Mercurial permet à quiquonque de faire + un clone du dépôt et d'y ajouter ses modifications sans jamais avoir + besoin de la permission de quiquonque, et l'on peut même publier ses + modifications et continuer à participer comme on le désir. La + distinction entre les commits et le transfert de ces derniers ouvre + la possibilité néanmoins que quelqu'un oublie pendant une longue + période de transférer ses modifications, ce qui dans certains cas + rares, peut piéger ses collaborateurs. - Quick reference + Références des commandes - Subversion commands and Mercurial equivalents + Commandes Subversion et leurs équivalents Mercurial @@ -395,24 +407,24 @@ svn cleanup n/a - No cleanup needed + Aucun nettoyage nécessaire. svn commit hg commit; hg push - hg push publishes after - commit + hg push publie les modifications + après leur enregistrement. svn copy hg clone - To create a new branch + Pour créer une nouvelle branche svn copy hg copy - To copy files or directories + Pour copier des fichiers ou des répertoires svn delete (svn @@ -444,13 +456,13 @@ svn info hg parents - Shows what revision is checked out + Affiche quelle révision est extraite svn info hg showconfig paths.parent - Shows what URL is checked out + Affiche de quelle URL est extrait ce dépôt svn list @@ -470,7 +482,7 @@ svn mkdir n/a - Mercurial does not track directories + Mercurial ne versionne pas les répertoires svn move (svn @@ -505,29 +517,31 @@ - Useful tips for newcomers - - Under some revision control systems, printing a diff for a - single committed revision can be painful. For instance, with - Subversion, to see what changed in revision 104654, you must - type svn diff -r104653:104654. Mercurial - eliminates the need to type the revision ID twice in this common - case. For a plain diff, hg export 104654. For - a log message followed by a diff, hg log -r104654 - -p. - - When you run hg status without any - arguments, it prints the status of the entire tree, with paths - relative to the root of the repository. This makes it tricky to - copy a file name from the output of hg status - into the command line. If you supply a file or directory name - to hg status, it will print paths relative to - your current location instead. So to get tree-wide status from - hg status, with paths that are relative to - your current directory and not the root of the repository, feed - the output of hg root into hg - status. You can easily do this as follows on a - Unix-like system: + Conseils utiles pour les débutants + + Avec la plupart des gestionnaire de révisions, afficher + un diff associé à une révision peut être assez douloureux. Par exemple, + avec Subversion, pour voir ce qui a été modifiée dans la révision 104654, + vous devez saisir svn diff -r104653:104654. Mercurial + élimine le besoin de saisir l'identifiant d'une révision deux fois dans + ce cas classique. Pour un simple diff, hg + export + 104654 suffit. Pour l'entrée du journal suivi du diff, + hg log -r104654. + + Quand vous exécutez la commande hg status + sans aucun arguments, elle affiche l'état de l'ensemble de l'arboresence, + avec des chemins relatifs partant de la raçine du dépôt. Ceci rend + difficile de copier un nom de fichier depuis la sortie de la commande + hg status dans une autre ligne de commande. Si vous + fournissez un fichier ou un répertoire à la commande hg + status, elle va afficher les chemins relatif depuis votre + répertoire courant à la place. Ainsi, pour avoir un état sur l'ensemble + de l'arboresence à l'aide de hg status, avec des + chemins relatifs à votre répertoire courant, et non le raçine du dépôt, + ajoutez la sortie de hg root à la commande + hg status. Vous pouvez le faire aisément sur un + système Unix ainsi : $ hg status `hg root`