Introduction à Mercurial

BLUGEON Damien

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

- Titre : Introduction à Mercurial

- Auteur : BLUGEON Damien

- Parution : 13 avril 2009

- Mise à jour : 2 juin 2020

- Licence : 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'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- 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-H-1. La commande hg push

- III-H-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 gestionnaires. C'est un logiciel libre sous licence GPLV2 développé par la 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 :

- netbeans (dépôt hg) ;

- openJDK (dépôt hg) ;

- openSolaris (récupération du dépôt openSolaris) ;

- glassfih (prévu après une migration vers svn.) ;

- mozilla (dépôt mercurial).

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 : 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

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.

Ne supprimez pas le répertoire .hg, car vous perdriez tout 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, 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. (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

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

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.

Pour supprimer des fichiers, il faut utiliser la commande hg remove.

hg remove fichiers/dossier

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

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.

Si vous souhaitez communiquer avec d'autres développeurs, 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]

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 avez 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]

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 n'ai 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.

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

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]

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.

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-H-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-H-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'anomalies… 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.

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 : 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.

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.
Éditez 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.

Le plugin Netbeans est bien intégré, il gère la récupération des projets et les fonctionnalités mercurial de base.
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 « Mercurial Queues »sur le wiki) il est possible de lancer le serveur standalone de mercurial

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 œuvre sont différents, ce projet utilise python comme langage. De plus il est possible de 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 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 page en répertorie quelques-uns.

VI - Remerciements

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