Mercurial: The Definitive Guide

Compiled from 6e286efa81b3 (2011-03-17)

Bryan O'Sullivan


Table of Contents

Préface
1. Un conte technique
2. Merci de votre soutien à Mercurial
3. Remerciements
4. Conventions utilisées dans ce livre
5. Utiliser les exemples de code
6. Safari® Books Online
7. Comment nous contacter
1. Comment en est-on arrivé là ?
1.1. À propos de la gestion de révisions. Pourquoi Mercurial ?
1.1.1. Pourquoi utiliser un gestionnaire de révisions ?
1.1.2. Les multiples noms de la gestion de source
1.2. À propos des exemples dans ce livre
1.3. Tendances de la gestion de révisions
1.4. Quelques avantages des gestionnaires de révisions distribués
1.4.1. Avantages pour les projets Open Source
1.4.2. Avantages pour les projets commerciaux
1.5. Pourquoi choisir Mercurial?
1.6. Mercurial comparé aux autres outils
1.6.1. Subversion
1.6.2. Git
1.6.3. CVS
1.6.4. Outils propriétaires
1.6.5. Choisir un outil de gestion de révisions
1.7. Migrer depuis un outil vers Mercurial
1.8. Une courte histoire de la gestion de révisions
2. Une rapide présentation de Mercurial : les bases
2.1. Installer Mercurial sur votre système
2.1.1. Windows
2.1.2. Mac OS X
2.1.3. Linux
2.1.4. Solaris
2.2. Commencer à utiliser Mercurial
2.2.1. L'aide intégrée
2.3. Travailler avec un dépôt
2.3.1. Faire une copie locale de votre dépôt
2.3.2. Quel est le contenu d'un dépôt ?
2.4. Une promenade dans l'historique
2.4.1. Changesets, révisions, et collaboration
2.4.2. Afficher une révision spécifique
2.4.3. Informations détaillées
2.5. Tout sur les options de commandes
2.6. Faire et vérifier des modifications
2.7. Enregistrer vos modifications dans une nouvelle révision
2.7.1. Définir le nom d'utilisateur
2.7.2. Rédiger un message de commit
2.7.3. Rédiger un message approprié
2.7.4. Annuler un commit
2.7.5. Admirer votre travail
2.8. Partager ses modifications
2.8.1. Récupérer les modifications d'autres dépôts
2.8.2. Mise à jour de l'espace de travail
2.8.3. Transférer les modifications vers un autre dépôt
2.8.4. Emplacements par défaut
2.8.5. Partager ses modifications à travers le réseau
2.9. Commencer un nouveau projet
3. Un tour rapide de Mercurial : fusionner les travaux
3.1. Fusionner différents travaux
3.1.1. Les révisions heads
3.1.2. Effectuer la fusion
3.1.3. Effectuer l'ajout (commit) du résultat de la fusion
3.2. Fusionner les modifications en conflit
3.2.1. Utiliser un outil graphique de fusion
3.2.2. Un exemple concret
3.3. Simplification de la séquence pull-merge-commit
3.4. Renommer, copier, et fusionner (merge)
4. Derrière le décor
4.1. Conservation de l'historique sous Mercurial
4.1.1. Suivi de l'historique pour un seul fichier
4.1.2. Gestion des fichiers suivis
4.1.3. Enregistrer les informations des changesets
4.1.4. Relations entre les révisions
4.2. Stockage sûr et efficace
4.2.1. Stockage efficace
4.2.2. Opérations sûres
4.2.3. Récupération rapide
4.2.4. Identification et intégrité forte
4.3. Historique des révisions, branches et fusions (merge)
4.4. Le répertoire de travail
4.4.1. Que se passe-t-il lorsque vous committez
4.4.2. Création d'une nouvelle head
4.4.3. Fusionner (merge) les changements
4.4.4. Fusions et renommages
4.5. D'autres fonctionnalités intéressantes
4.5.1. Compression astucieuse
4.5.2. Ordre de lecture/écriture et atomicité
4.5.3. Accès concurrent
4.5.4. Empêcher les recherches
4.5.5. Autres contenus du dirstate
5. Utilisation quotidienne de Mercurial
5.1. Informer Mercurial des fichiers à suivre
5.1.1. Nommage des fichiers explicite versus implicite
5.1.2. Mercurial suit les fichiers, pas les répertoires
5.2. Comment arrêter de suivre un fichier
5.2.1. Supprimer un fichier n'affecte pas son historique
5.2.2. Fichiers manquants
5.2.3. Aparté : Pourquoi dire explicitement à Mercurial de supprimer un fichier ?
5.2.4. Raccourci utile—ajouter et supprimer des fichiers en une seule étape.
5.3. Copier des fichiers
5.3.1. Les résultats d'une copie durant une fusion (merge)
5.3.2. Pourquoi les changements devraient-ils suivre les copies ?
5.3.3. Comment faire des changements qui ne suivent pas une copie
5.3.4. Comportement de la commande hg copy
5.4. Renommer les fichiers
5.4.1. Renommer les fichiers et fusionner (merge) les changements
5.4.2. Renommages divergeants et fusion (merge)
5.4.3. Renommages et fusion convergeants
5.4.4. Autres cas épineux relatifs aux noms
5.5. Récupération d'erreurs
5.6. Traiter avec les fusions (merge) malicieuses
5.6.1. États de résolution des fichiers
5.6.2. Résoudre une fusion de fichier
5.7. Des diffs plus utiles
5.8. Quels fichiers suivre et lesquels éviter
5.9. Sauvegardes et miroirs
6. Collaborer avec d'autres personnes
6.1. Interface web de Mercurial
6.2. Modèles de collaboration
6.2.1. Facteurs à garder en tête
6.2.2. Anarchie informelle
6.2.3. Un simple dépôt central
6.2.4. Un dépôt central hébergé
6.2.5. Travailler avec plusieurs branches
6.2.6. Feature branches
6.2.7. Le train des releases
6.2.8. Le modèle du noyau Linux
6.2.9. Collaboration pull seulement versus pull partagé
6.2.10. Lorsque la collaboration rencontre la gestion de branches
6.3. Le côté technique du partage
6.4. Partage informel avec hg serve
6.4.1. Quelques choses à garder à l'esprit
6.5. Utiliser le protocole Secure Shell (ssh)
6.5.1. Comment lire et écrire des URLs ssh
6.5.2. Trouver un client ssh pour votre système
6.5.3. Créer une paire de clef
6.5.4. Utiliser un agent d'authentification
6.5.5. Configurer correctement le serveur
6.5.6. Utilisation de la compression avec ssh
6.6. Service sur HTTP grâce à CGI
6.6.1. Liste de contrôle de la configuration du serveur web
6.6.2. Configuration élémentaire de CGI
6.6.3. Partager plusieurs dépôts avec un seul script CGI
6.6.4. Télécharger des archives de sources
6.6.5. Options de configuration web
6.7. Configuration "system-wide"
6.7.1. Rendre Mercurial moins méfiant
7. File names and pattern matching
7.1. Simple file naming
7.2. Running commands without any file names
7.3. Telling you what's going on
7.4. Using patterns to identify files
7.4.1. Shell-style glob patterns
7.4.2. Regular expression matching with re patterns
7.5. Filtering files
7.6. Permanently ignoring unwanted files and directories
7.7. Case sensitivity
7.7.1. Safe, portable repository storage
7.7.2. Detecting case conflicts
7.7.3. Fixing a case conflict
8. Managing releases and branchy development
8.1. Giving a persistent name to a revision
8.1.1. Handling tag conflicts during a merge
8.1.2. Tags and cloning
8.1.3. When permanent tags are too much
8.2. The flow of changes—big picture vs. little
8.3. Managing big-picture branches in repositories
8.4. Don't repeat yourself: merging across branches
8.5. Naming branches within one repository
8.6. Dealing with multiple named branches in a repository
8.7. Branch names and merging
8.8. Branch naming is generally useful
9. Finding and fixing mistakes
9.1. Erasing local history
9.1.1. The accidental commit
9.1.2. Rolling back a transaction
9.1.3. The erroneous pull
9.1.4. Rolling back is useless once you've pushed
9.1.5. You can only roll back once
9.2. Reverting the mistaken change
9.2.1. File management errors
9.3. Dealing with committed changes
9.3.1. Backing out a changeset
9.3.2. Backing out the tip changeset
9.3.3. Backing out a non-tip change
9.3.4. Gaining more control of the backout process
9.3.5. Why hg backout works as it does
9.4. Changes that should never have been
9.4.1. Backing out a merge
9.4.2. Protect yourself from escaped changes
9.4.3. What to do about sensitive changes that escape
9.5. Finding the source of a bug
9.5.1. Using the hg bisect command
9.5.2. Cleaning up after your search
9.6. Tips for finding bugs effectively
9.6.1. Give consistent input
9.6.2. Automate as much as possible
9.6.3. Check your results
9.6.4. Beware interference between bugs
9.6.5. Bracket your search lazily
10. Handling repository events with hooks
10.1. An overview of hooks in Mercurial
10.2. Hooks and security
10.2.1. Hooks are run with your privileges
10.2.2. Hooks do not propagate
10.2.3. Hooks can be overridden
10.2.4. Ensuring that critical hooks are run
10.3. A short tutorial on using hooks
10.3.1. Performing multiple actions per event
10.3.2. Controlling whether an activity can proceed
10.4. Writing your own hooks
10.4.1. Choosing how your hook should run
10.4.2. Hook parameters
10.4.3. Hook return values and activity control
10.4.4. Writing an external hook
10.4.5. Telling Mercurial to use an in-process hook
10.4.6. Writing an in-process hook
10.5. Some hook examples
10.5.1. Writing meaningful commit messages
10.5.2. Checking for trailing whitespace
10.6. Bundled hooks
10.6.1. acl—access control for parts of a repository
10.6.2. bugzilla—integration with Bugzilla
10.6.3. notify—send email notifications
10.7. Information for writers of hooks
10.7.1. In-process hook execution
10.7.2. External hook execution
10.7.3. Finding out where changesets come from
10.8. Hook reference
10.8.1. changegroup—after remote changesets added
10.8.2. commit—after a new changeset is created
10.8.3. incoming—after one remote changeset is added
10.8.4. outgoing—after changesets are propagated
10.8.5. prechangegroup—before starting to add remote changesets
10.8.6. precommit—before starting to commit a changeset
10.8.7. preoutgoing—before starting to propagate changesets
10.8.8. pretag—before tagging a changeset
10.8.9. pretxnchangegroup—before completing addition of remote changesets
10.8.10. pretxncommit—before completing commit of new changeset
10.8.11. preupdate—before updating or merging working directory
10.8.12. tag—after tagging a changeset
10.8.13. update—after updating or merging working directory
11. Customizing the output of Mercurial
11.1. Using precanned output styles
11.1.1. Setting a default style
11.2. Commands that support styles and templates
11.3. The basics of templating
11.4. Common template keywords
11.5. Escape sequences
11.6. Filtering keywords to change their results
11.6.1. Combining filters
11.7. From templates to styles
11.7.1. The simplest of style files
11.7.2. Style file syntax
11.8. Style files by example
11.8.1. Identifying mistakes in style files
11.8.2. Uniquely identifying a repository
11.8.3. Listing files on multiple lines
11.8.4. Mimicking Subversion's output
12. Managing change with Mercurial Queues
12.1. The patch management problem
12.2. The prehistory of Mercurial Queues
12.2.1. A patchwork quilt
12.2.2. From patchwork quilt to Mercurial Queues
12.3. The huge advantage of MQ
12.4. Understanding patches
12.5. Getting started with Mercurial Queues
12.5.1. Creating a new patch
12.5.2. Refreshing a patch
12.5.3. Stacking and tracking patches
12.5.4. Manipulating the patch stack
12.5.5. Pushing and popping many patches
12.5.6. Safety checks, and overriding them
12.5.7. Working on several patches at once
12.6. More about patches
12.6.1. The strip count
12.6.2. Strategies for applying a patch
12.6.3. Some quirks of patch representation
12.6.4. Beware the fuzz
12.6.5. Handling rejection
12.7. More on patch management
12.7.1. Deleting unwanted patches
12.7.2. Converting to and from permanent revisions
12.8. Getting the best performance out of MQ
12.9. Updating your patches when the underlying code changes
12.10. Identifying patches
12.11. Useful things to know about
12.12. Managing patches in a repository
12.12.1. MQ support for patch repositories
12.12.2. A few things to watch out for
12.13. Third party tools for working with patches
12.14. Good ways to work with patches
12.15. MQ cookbook
12.15.1. Manage trivial patches
12.15.2. Combining entire patches
12.15.3. Merging part of one patch into another
12.16. Differences between quilt and MQ
13. Advanced uses of Mercurial Queues
13.1. The problem of many targets
13.1.1. Tempting approaches that don't work well
13.2. Conditionally applying patches with guards
13.3. Controlling the guards on a patch
13.4. Selecting the guards to use
13.5. MQ's rules for applying patches
13.6. Trimming the work environment
13.7. Dividing up the series file
13.8. Maintaining the patch series
13.8.1. The art of writing backport patches
13.9. Useful tips for developing with MQ
13.9.1. Organising patches in directories
13.9.2. Viewing the history of a patch
14. Adding functionality with extensions
14.1. Improve performance with the inotify extension
14.2. Flexible diff support with the extdiff extension
14.2.1. Defining command aliases
14.3. Cherrypicking changes with the transplant extension
14.4. Send changes via email with the patchbomb extension
14.4.1. Changing the behavior of patchbombs
A. Migrer vers Mercurial
A.1. Importer l'historique depuis un autre système
A.1.1. Convertir plusieurs branches
A.1.2. Associer les noms d'utilisateurs
A.1.3. Nettoyer l'arboresence
A.1.4. Améliorer les performances de la conversion Subversion
A.2. Migrer depuis Subversion
A.2.1. Différences philosophiques
A.2.2. Références des commandes
A.3. Conseils utiles pour les débutants
B. Mercurial Queues reference
B.1. MQ command reference
B.1.1. qapplied—print applied patches
B.1.2. qcommit—commit changes in the queue repository
B.1.3. qdelete—delete a patch from the series file
B.1.4. qdiff—print a diff of the topmost applied patch
B.1.5. qfold—move applied patches into repository history
B.1.6. qfold—merge (fold) several patches into one
B.1.7. qheader—display the header/description of a patch
B.1.8. qimport—import a third-party patch into the queue
B.1.9. qinit—prepare a repository to work with MQ
B.1.10. qnew—create a new patch
B.1.11. qnext—print the name of the next patch
B.1.12. qpop—pop patches off the stack
B.1.13. qprev—print the name of the previous patch
B.1.14. qpush—push patches onto the stack
B.1.15. qrefresh—update the topmost applied patch
B.1.16. qrename—rename a patch
B.1.17. qseries—print the entire patch series
B.1.18. qtop—print the name of the current patch
B.1.19. qunapplied—print patches not yet applied
B.1.20. hg strip—remove a revision and descendants
B.2. MQ file reference
B.2.1. The series file
B.2.2. The status file
C. Installer Mercurial à partir des sources
C.1. Pour un système Unix ou similaire
C.2. Pour Windows
D. Open Publication License
D.1. Requirements on both unmodified and modified versions
D.2. Copyright
D.3. Scope of license
D.4. Requirements on modified works
D.5. Good-practice recommendations
D.6. License options

List of Figures

2.1. Historique graphique du dépôt hello
3.1. Historique divergeant des dépôts my-hello et my-new-hello.
3.2. Contenu du dépôt après une récupération (pull) depuis le dépôt my-hello vers le dépôt my-new-hello
3.3. Répertoire de travail et dépôt pendant une fusion, et le commit qui suit
3.4. Modifications en conflit dans un document
3.5. Utiliser kdiff3 pour fusionner les différentes version d'un fichier.
4.1. Relations entre les fichiers dans le répertoire de travail et leurs filelogs dans le dépôt
4.2. Metadata relationships
4.3. Snapshot d'un revlog, avec des deltas incrémentaux
4.4. Le concept de la structure d'un revlog
4.5. Le répertoire de travail peut avoir deux parents
4.6. Le répertoire de travail gagne de nouveaux parents après un commit
4.7. Le répertoire de travail, updaté pour un changeset plus ancien
4.8. Après un commit fait pendant la synchronisation avec un ancien changeset
4.9. Fusionner (merge) deux heads
6.1. Feature branches
9.1. Backing out a change using the hg backout command
9.2. Automated backout of a non-tip change using the hg backout command
9.3. Backing out a change using the hg backout command
9.4. Manually merging a backout change
9.5. A bad merge
9.6. Backing out the merge, favoring one parent
9.7. Backing out the merge, favoring the other parent
9.8. Merging the backouts
9.9. Merging the backouts
12.1. Applied and unapplied patches in the MQ patch stack

List of Tables

A.1. Commandes Subversion et leurs équivalents Mercurial