Introduction à Mercurial

Date de publication : 13/04/2009

Par BLUGEON Damien
 

Cet article vous propose une introduction au gestionnaire de code source Mercurial.

               Version PDF (Miroir)   Version hors-ligne (Miroir)

I. Introduction
II. Installation
III. Utilisation
III-A. Création d'un dépôt
III-B. Récupération d'un dépôt existant
III-C. Mise à jour d'un dépôt depuis le dépôt d'origine
III-D. Livrer des modifications
III-E. Annuler des modifications
III-F. Afficher l'historique d'un dépôt
III-G. Tagger un changeset
III-H. Publier vos modifications
III-G-1. La commande hg push
III-G-2. La commande hg export
IV. Quelques Outils
IV-A. La commande hg view
IV-A-1. Installation sous Windows
IV-A-2. Installation sous Linux Ubuntu 8.04
IV-A-3. Installation sous Mac OS
IV-B. Intégration dans Netbeans
IV-C. Intégration dans Eclipse
IV-D. Tortoise HG
V. Conclusion
VI. Remerciements


I. Introduction

Mercurial est un gestionnaire de versions distribué, ce qui n'est pas le cas de Subversion et de CVS. Dans les chapitres suivants, nous ferons des comparaisons entre les deux afin de distinguer les différences entre les deux types de gestionnaire. C'est un logiciel libre sous licence GPLV2 développé par la en société Selenic. Il est développé en python avec quelques extensions en C. Il a, ces derniers mois, été choisi afin de remplacer soit subversion soit CVS.
Voici quelques exemples de migrations :

Ce tutoriel se concentrera sur la présentation de l'outil, de ses commandes les plus utilisées et de son intégration dans votre environnement informatique.


II. Installation

Tout d'abord, il vous faut récupérer le programme d'installation correspondant à votre système d'exploitation. Vous le trouverez à la page suivante : en http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages (source).
Note : il existe aussi une version "easy_install".

écran d'installation de mercurial sous Mac OS X
Ecran d'installation de mercurial sous Mac OS X

Voilà vous pouvez utiliser mercurial.


III. Utilisation


III-A. Création d'un dépôt

Si vous êtes seul, vous devez initier votre dépôt mercurial. Pour cela, placez vous dans le répertoire contenant les sources à versionner désiré et tapez la commande suivante : 

hg init
Cette commande aura pour effet de rajouter un dossier (.hg). C'est ce répertoire qui contient tout l'historique de votre dépôt.

warning Ne supprimez pas le répertoire .hg, car vous perdriez tous l'historique de votre dépôt local.

III-B. Récupération d'un dépôt existant

Imaginons maintenant que vous souhaitiez récupérer le contenu d'un dépôt existant, comme par exemple celui-ci : http://www.selenic.com/repo/hello. Ce dépôt est un dépôt mis à disposition par la société selenic afin de tester les capacités de mercurial. (en tutoriel officiel)
Il vous suffit de faire : 

hg clone http://www.selenic.com/repo/hello [NomQueVousVoulez]
Le paramètre [NomQueVousVoulez] est optionnel. Il vous permet de choisir le nom de votre copie locale, si vous ne le précisez pas, le nom utilisé sera celui du dépôt d'origine.
Sur l'exemple, ce sera "hello". Tout comme lors de la création d'un dépôt, vous retrouverez le dossier .hg. Contrairement à Subversion, ce dossier contient tout l'historique des modifications, il n'y a pas d'autres dossiers servant d'historique. C'est grâce à cet historique que l'on peut faire un "commit" de ses modifications sans avoir le serveur en face. Enfin, il est possible de cloner un dépôt local, il suffit d'exécuter la commande suivante : 

hg clone depot-existant chemin/vers/nouveauDepot
clone d'un dépôt mercurial
clone d'un dépôt mercurial
Contenu d'un dépôt

III-C. Mise à jour d'un dépôt depuis le dépôt d'origine

Avec subversion, pour mettre à jour sa copie locale, on exécute la commande : 

svn checkout
depuis le répertoire de la copie locale. Avec mercurial, on effectue la commande suivante depuis le dépôt local : 

hg pull [dépôt à utiliser]
Là encore, il y a une différence avec subversion. Cette commande sans paramètre va chercher les dernières modifications du dépôt qui a servi à la création du dépôt local.
Si l'on reprend l'exemple avec le clone du dépôt de selenic, la commande ira télécharger les modifications sur le site de selenic. Il est possible de mettre à jour un dépôt, depuis un autre dépôt que celui ayant servi à la création du clone. Il suffit de préciser son emplacement.
Précision importante : la commande hg pull mettra à jour uniquement le dossier .hg. Si vous souhaitez mettre à jour les fichiers de la copie de travail, il faut utiliser la commande suivante : 

hg update
Enfin, si vous avez fait des modifications dans votre dépôt local, il est nécessaire de lancer la commande : 

hg merge
Cette commande va fusionner les dernières modifications distantes avec les vôtres. En cas de conflit, mercurial ouvrira l'outil dédié à la fusion des fichiers.
Puis vous devrez livrer les modifications dans votre dépôt local avec la commande : 

hg commit
info la commande hg update dispose de deux options :
l'option -m : indique que l'on veut fusionner les modifications locales lors de la mise à jour du dépôt.
l'option -C : met à jour votre dépôt local en supprimant vos modifications. Attention, aucune sauvegarde des fichiers modifiés n'est effectuée.

III-D. Livrer des modifications

Ici, nous allons nous retrouver en terrain connu. Pour ajouter des fichiers dans le dépôt, il suffit de faire un : 

hg add [fichier/dossiers]
Si on ne précise pas de nom de fichiers/répertoire, tous les fichiers inconnus du dépôt seront ajoutés.

Copie d'écran de la commande hg add
Pour supprimer des fichiers, il faut utiliser la commande hg remove. 

hg remove fichiers/dossier
Copie d'écran de la commande hg remove
Une fois les fichiers rajoutés/modifiés/supprimés, il faut utiliser la commande hg commit. 

hg commit [-u username] [-m "un message"] -v
Copie d'écran de la commande hg commit
Cette commande crée un "changeset" dans votre dépôt. Dans mercurial, on n'utilise pas le terme de révision, mais de changeset (tout comme dans Git ou dans bazaar). Un changeset est unique parmi tous les dépôts d'un projet.
Cependant, il existe un numéro de révision plus classique, mais qui dépend du dépôt. Le numéro de révision est indiqué devant le changeset.

L'option -v permet d'afficher le nouveau changeset.

idea Si vous souhaitez communiquer avec d'autres developpeurs, utilisez le changeset ou un tag.
Note : ici, je n'ai pas configuré avec un nom d'utilisateur mercurial, d'où l'avertissement.
Note 2: le message est optionnel si vous avez configuré un éditeur de texte. Ce dernier sera lancé automatiquement. Si vous n'en avez pas configuré, l'éditeur de texte par défaut sera lancé ( Notepad pour windows, vi pour les unix).

Comme indiqué plus haut, la command hg commit livre les modifications dans le dépôt local. Alors qu'avec Subversion, il n'est pas possible de faire "svn commit" sans dépôt central. Avec ce mode, il est simple d'enregistrer ces modifications lorsque l'on ne dispose pas de connexion réseau.
Une fois la connexion réseau rétablie, il suffit de faire une mise à jour de son dépôt local (hg pull), puis de fusionner son travail avec les autres modifications (hg update -m + hg commit).


III-E. Annuler des modifications

Mercurial propose des commandes particulières afin de rattraper des erreurs provenant d'un "hg commit" ou d'un "hg remove" malencontreux.

Pour annuler des modifications non livrées par un hg commit ou pour restaurer des fichiers à une révision antérieure, il faut utiliser la commande 

hg revert [--all] [-r revision] [-n][ Fichiers]
image illustrant l'effet d'un hg revert
L'option --all annule tous les changements survenus dans le dépôt.
L'option -r permet de revenir à une révision particulière. Si vous ne la précisez pas cette option, seules les modifications non livrées seront annulées.
L'option -n permet de voir ce que ferait la commande.
Enfin il est possible de préciser les répertoires ou les fichiers qui seront la cible de la commande.
Les fichiers modifiés par la commande sont sauvegardés avec le suffixe .orig avant application de la restauration.

Si vous vous êtes trompé et que vous ayez déjà exécuté la commande "hg commit". Vous pouvez utiliser la commande hg rollback.
Cette commande annule la dernière transaction. Les opérations créant une transaction sont "commit", "import", "push", "pull".
Si vous venez d'utiliser la commande "hg commit", l'utilisation de cette commande supprimera cette transaction. Il n'est pas possible d'annuler l'effet de cette commande.


III-F. Afficher l'historique d'un dépôt

Tout comme la commande svn log, la commande hg log vous permet d'afficher l'historique d'un dépôt ou d'un fichier. 

hg log [-r rev/changeset] [-f] [-u nomUser] [...] [File]
copie d'écran de hg log
Voici une petite explication de ces options :

  • l'option -r : vous permet d'afficher le détail d'une révision ou d'un changeset. Il existe des révisions spéciales comme la révision "tip" (la révision la plus récente). vous pouvez spécifier le nom d'un tag.
  • l'option -f : vous permet de suivre dans l'historique les opérations de copie et de renommage.
  • l'option -u : vous permet de lister les livraisons effectuées par l'utilisateur spécifié.
Je ne vous aie présenté que quelques options de cette commande, il en existe beaucoup d'autres.
Il existe une extension (glog) qui vous permet d'avoir un historique avec un graphe en ASCII.

copie d'écran de hg glog

III-G. Tagger un changeset

En général avec Subversion, lorsque vous souhaitez créer une étiquette (ou un tag), vous créez une copie de votre branche de développement vers l'arborescence tags.
En fait les tags dans svn sont plus une convention. Dans mercurial, les tags sont définis par un changeset particulier et un nom. Pour créer un tag il suffit de taper la commande suivante : 

hg tag [-l ][-u userName] [--remove] [-m "un message particulier"] [-r "une révision"] nomDuTag
copie d'écran hg tag
Comme vous pouvez le voir, il est possible de spécifier un message pour la livraison. Si vous ne le spécifiez pas, il aura cette forme : "Added tag NomDuTag for changeset b1e4171a0973".
Si vous avez besoin de supprimer un tag, l'option --remove vous sera utile, un "commit" sera là aussi effectué.
l'option "-l" est particulière, elle permet de créer un tag local. C'est-à-dire que ce dernier ne sera pas cloné comme le reste de l'historique du dépôt.

Vous savez comment créer un tag, mais pour en faire l'inventaire que faut-il faire ? La commande hg tags répond à cette demande. 

hg tags [-v]
copie d'écran hg tags
L'option "-v" permet d'afficher une troisième colonne où apparaît la mention "local" pour les tags locaux.
Tous les tags sont référencés dans le fichier .hgtags. Il est possible de rajouter des tags en modifiant manuellement le fichier .hgtags et en livrant ces modifications dans le dépôt.

warning Deux remarques à propos des tags locaux, ces derniers se distinguent des autres en deux occasions :
-Dans le fichier .hgtags, ils sont référencés deux fois : une fois avec la révision de création et une autre avec une révision 000000.
-La création d'un tag local n'entraîne pas un commit.

III-H. Publier vos modifications

Après avoir récupéré la version en cours de développement, effectué des modifications, livré ces modifications, il faut publier ces modifications.


III-G-1. La commande hg push

Voici la commande qui permet de faire remonter les modifications de votre dépôt vers un autre. 

hg push
va par défaut, faire remonter les modifications de votre dépôt dans le dépôt parent. 

hg push http://unEmplcamentOuReseau
permet d'indiquer le dépôt de destination. Mercurial, par défaut, vous avertira si vous tentez de pousser des modifications vers un dépôt qui n'a aucun lien avec le vôtre : 

hg push ../growl
pushing to ../growl/
searching for changes
abort: repository is unrelated
Ce contrôle est aussi fait pour la commande hg pull.


III-G-2. La commande hg export


hg export
Cette commande est semblable à la commande 

svn export
Elle permet de fabriquer un fichier .diff ou .patch pour une diffusion par mail, par attachement dans un gestionnaire d'anomalie,... Voici un exemple d'utilisation : 

hg export révision > monpatch.diff
Le contenu du fichier sera le suivant : 

# HG changeset patch
# User Matt Mackall <mpm@selenic.com>
# Node ID b8daa9444f08a98a0d91d922dbeba05ab3247169
# Parent 82e55d328c8ca4ee16520036c0aaace03a5beb65
Voici l'expression de la grande joie de l'existence de Mercurial


diff -r 82e55d328c8c -r b8daa9444f08 hello.c
--- a/hello.c Fri Aug 26 08:21:28 2005
+++ b/hello.c Sun Aug 28 09:10:28 2005
@@ -12,5 +12,6 @@
int main(int argc, char **argv)
{
printf("hello, world!\n");
+ printf("Certain que vous êtes heureux d'utiliser Mercurial!\n");
return 0;
}
Pour importer le patch dans le dépôt de destination, il faudra faire : 

hg import monpatch.diff
Il est possible d'importer plusieurs patchs. Pour chaque patch, un "commit" sera effectué dans le dépôt.


IV. Quelques Outils

Dans cette section nous allons présenter quelques outils qui facilitent l'utilisation de mercurial.


IV-A. La commande hg view

Cette commande est une extension de mercurial qui permet d'afficher l'historique d'un dépôt.
C'est un portage de la commande gitk qui provient du gestionnaire de source git et qui a été renommé en hgk.
Elle utilise le couple tcl/tk pour fonctionner.

interface d'hg view
Cet outil vous permet de :
  • Visualiser tous les changesets
  • Effectuer des recherches dans les changesets
  • Visualiser tous les changesets (fichiers modifiés, commentaires, parents, enfants,..)

IV-A-1. Installation sous Windows

Pour installer cette commande sous Windows, vous devez d'abord vous procurer active tcl à cette adresse : en http://www.activestate.com/store/activetcl/download/
Clonez ce dépôt et mettez-le à jour selon votre version (par exemple "1.1"). 

hg clone http://selenic.com/hg hg-upstream
hg up -r votreVersion
Copier le fichier hgk qui se trouve dans le répertoire contrib dans un répertoire de votre choix.
Renommez le fichier en "hgk.tcl".
Editer le fichier mercurial.ini pour ajouter les lignes suivantes :


[extensions]
hgext.hgk=

[hgk]
path="C:\le repertoire\hgk.tcl"
Les guillemets dans le chemin "path" sont nécessaires uniquement si vous utilisez un chemin avec des espaces.

idea Vous pouvez aussi éditer le fichier %votreRépertoireUtilisateur%\mercurial.ini si vous ne souhaitez pas rendre cette commande disponible à tous les utilisateurs de votre ordinateur.

IV-A-2. Installation sous Linux Ubuntu 8.04

Je pars du principe que vous avez installé mercurial depuis synaptic/apt-get. En passant par ce biais, vous avez automatiquement le script nécessaire à la commande. Il ne vous reste plus qu'à faire : 

sudo apt-get install tk8.4
Une fois ceci, fait il ne vous reste plus qu'à modifier le fichier $HOME/.hgrc afin de rajouter les lignes suivantes : 

[hgk] path=/usr/share/mercurial/hgk
Une fois ceci fait, la commande hg view sera disponible. Mais quelques explications s'imposent :
Contrairement aux autres OS, Ubuntu apporte directement mercurial avec la commande hgk. Cette distribution configure d'amblé une série d'extension dont celle qui nous intéresse.
Cependant, notre commande ne fonctionne pas directement. Car lorsque vous indiquez une nouvelle extension à mercurial, sans préciser de chemin, ce dernier va chercher les extensions dans une série de répertoires. Et il se trouve que dans le cas présent le script hgk est hors de portée. C'est le but de la directive "path".

Il se peut que vous ayez un avertissement à propos d'un module bisect absent lorsque vous tentez d'utiliser la commande hg view. Une des conséquences est que la commande n'est pas opérationnelle. Pour y remédier, vous devez éditer le fichier /etc/mercurial/hgrc.d/hgext.rc, puis commenter la ligne "hgext.hbisect=".


IV-A-3. Installation sous Mac OS

Tcl/tk est déjà présent sur le système, il n'est pas nécessaire de l'installer. Cependant, le script hgk n'est pas présent dans la distribution de mercurial pour Mac OS X. Il faut donc la récupérer depuis les sources. Je vais décrire la méthode permettant de le faire depuis le dépôt.

Pour commencer ouvrez le terminal, puis placez-vous dans votre répertoire utilisateur. Et tapez 

hg clone http://selenic.com/hg hg-upstream
hg up -r votreVersion
mkdir bin
cp hg-upstream/contrib/hgk ./bin/
Voilà vous avez copié le script hgk correspondant à votre version dans le répertoire ~/bin.
Editez maintenant le fichier .hgrc de votre répertoire utilisateur qui se trouve dans votre répertoire utilisateur et ajoutez-y les lignes suivantes. 


[extensions]
hgext.hgk=
[hgk]
path=/Users/votreUser/bin/hgk
Voilà la commande "hg view" est maintenant disponible. Comme les autres commandes, il faut se placer dans le répertoire d'un dépôt pour qu'elle fonctionne.


IV-B. Intégration dans Netbeans

Depuis la version 6.0, Netbeans intègre un plugin pour gérer les dépôts mercurial au sein des projets de l'EDI. Ce dernier est présent dans toutes les distributions officielles.

copie d'écran du plugin netbeans.

Le plugin Netbeans est bien intégré, il gère la récupération des projets et les fonctionnalités mercurial de bases.
Si vous clonez un dépôt mercurial qui contient un projet que votre installation de Netbeans peut gérer, il vous sera proposé d'ouvrir le(s) projet(s).


IV-C. Intégration dans Eclipse

Il existe un plugin pour eclipse v 3.3+ afin de gérer les dépôts mercurial depuis eclipse. Il propose des fonctionnalités similaires. Avec des petits plus : il est possible d'afficher un graphe de l'historique du dépôt. Il est possible de gérer une "Mercurial Queues" (voir l'extension en "Mercurial Queues" sur le wiki) il est possible de lancer le serveur standalone de mercurial

copie d'écran du plugin eclipse

IV-D. Tortoise HG

Tortoise HG est un clone du projet TortoiseSvn. Son but est le même, vous permettre de gérer vos dépôts mercurial depuis l'explorateur de fichier.
Mais les moyens de mise en oeuvre sont différents, ce projet utilise python comme langage. De plus il est possible de en l'intégrer à Nautilus, l'explorateur de fichier de Gnome.


Ici on peut voir les fichiers marqués dans l'explorateur Windows comme étant livrés dans le dépôt. Et en premier plan la fenêtre de tortoise hg permettant de récupérer les modifications d'un dépôt distant.


V. Conclusion

Nous voici arrivés à la fin de cet article, le wiki de la société selenic est une excellente source d'informations. Il y a aussi un hg red book (calqué sur le modèle du svn red book) disponible en ici, mais ce dernier n'est pas un livre officiel. Si vous recherchez les détails d'une commande il existe l'aide en ligne : hg [-v] help laCommande.
Enfin si vous recherchez des dépôts disponibles sur internet, cette en page en répertorie quelques-uns.


VI. Remerciements

Je souhaite remercier Ricky81 pour m'avoir guidé ainsi que hed62 et RideKick pour leurs relectures. en Télécharger Mercurial
en Le HG Red Book
en les hébergeurs de dépôts Mercurial
en Le wiki de selenic sur Mercurial
fr Le wiki de selenic en français
en Installation d'hg view sous Mac OS X



               Version PDF (Miroir)   Version hors-ligne (Miroir)

Valid XHTML 1.1!Valid CSS!

Copyright © 2009 Damien BLUGEON. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à 3 ans de prison et jusqu'à 300 000 E de dommages et intérêts. Cette page est déposée à la SACD.

Vos questions techniques : forum d'entraide Conception - Publiez vos articles, tutoriels et cours
et rejoignez-nous dans l'équipe de rédaction du club d'entraide des développeurs francophones
Nous contacter - Hébergement - Participez - Copyright © 2000-2010 www.developpez.com - Legal informations.