HG en 7 commandes

Vous avez un projet en cours de développement et vous aimeriez le partager avec d'autres développeurs. Cela implique de le mettre sous contrôle d’un système de contrôle de révision come CVS, SVN ou Mercurial.

Voici comment passer votre projet sous contrôle de Mercurial en utilisant TortoiseHg, la version Windows de Mercurial. (hg étant le nom du programme utilisé en ligne de commande)

Disons que votre projet à passer sous Mercurial est dans workspace/Demo.

1) init

Allez dans le repertoire workspace.
Bouton droit sur « demo » : TortoiseHg > Create Repository Here

Cliquer « Close »
Un message confirme la création.
En fait hg a créé le répertoire Demo/.hg

2) add

Maintenant il faut ajouter les fichiers à ce repository local. En fait il s’agit de dire à Mercurial quels sont les fichiers qu’il doit prendre en charge.

Aller dans votre répertoire workspace\Demo
Sélectionnez les répertoires et fichiers à passer sous contrôle de Mercurial.
Bouton droit sur la selection de fichiers : TortoiseHg > Add Files…

Une fenêtre listant tous les fichiers à ajouter s’ouvre.
En cliquant sur un nom de fichier on peut voir son contenu.
Confirmez en cliquant sur le bouton « Add »

3) commit

Il faut maintenant dire à Mercurial de faire une copie de ces fichiers dans le repository local (en fait le répertoire .hg)
Bouton droit n’importe où dans le repertoire workspace/Demo : TortoiseHg > Commit…

Une fenêtre s’ouvre avec la liste de tous les fichiers de ce répertoire.
La couleur et la lettre qui préfixe chaque fichier indique l’état du fichier :

  A=Ajouté mais pas encore pris en compte, 

  ?=non géré par mercurial

  ect...

Tapez un commentaire dans le champ en haut à droite.
Cliquez sur le bouton « Commit »

La fenêtre est mise à jour. Les fichiers ajoutés n’y figurent  plus.
La fermer en cliquant sur le bouton « Close »

4) clone

Votre repository local est maintenant en place. Il faut mettre en place le repository central, celui qui vous permettra de partager vos fichiers avec les autres développeurs du monde extérieur.

Bouton droit n’importe où dans le directory workspace\Demo : TortoiseHg > Clone…
Donner l’url de votre repository dans le champ destination. (Voir comment configurer ssh + hg)

Et voila !

Votre repository Mercurial est maintenant opérationnel des deux cotés (local et central).
Vous n’aurez plus à utiliser les commandes init et clone.

Pour mémoire voici comment sont organisés les 2 niveaux de repository (Local/Central) de Mercurial

Ceci signifie qu'il n'est pas necessaire d'etre connecté au réseau pour travailler avec le repository local.

Pour valider votre travail en local : commit
Pour envoyer vos fichiers sur le serveur : push
Pour récupérer des fichiers depuis le server : pull
Pour mettre à jour vos fichiers de travail : update

Ne pas oublier de faire un add chaque fois que l’on crée un nouveau fichier.

HG + SSH

Dans le cas où on utilise Mercurial dans un mode client/serveur il faut choisir un protocole de communication entre les clients et le serveur. Cette page récapitule les options possibles.

Si on ne veut pas installer des applications supplémentaires (Rhodecode, hgweb, hg-ssh ect…) la seule solution efficace est ssh. Mais c’est aussi la solution la moins documentée !

Le principe de fonctionnement de hg + ssh est le suivant :
Le hg coté client va utiliser ssh pour exécuter les commandes hg coté serveur et communiquer avec.

Le problème c’est que des commande comme celle-ci on n’a pas envie de les taper ni de rentrer le mot de passe à chaque fois.

“C:\Program Files\TortoiseHg\TortoisePlink.exe” -ssh -2 -i “C:\Documents and Settings\All Users\Documents\ssh\hg\id_rsa.ppk" hg@mon.domaine.com “hg -R /home/hg/repo1 serve –stdio”

Pour automatiser il faut :

• Utiliser un client graphique. Il s’occupera de construire la commande et de l’exécuter.  Le meilleur des clients graphiques est TortoiseHg
• Utiliser ssh avec une paire de clefs publique/privée pour éviter de taper le mot de passe à chaque commande.

1) Installation de Mercurial

On partira du principe que le serveur est sous Unix et le client sous Windows.

* L’installation de TortoiseHg sur le poste Windows n’est pas un problème. Il inclut tout : Mercurial, l'interface graphique et même le client ssh : TortoisePlink.exe (mais on peut en utiliser un autre).
* L'installation de Mercurial sur le serveur Unix est basique. Il suffit d'installer le package correspondant à son Unix ou à sa distribution Linux. (Il faut avoir python 2.6+ deja installé).


2) La paire de clefs publique/privée

Il faut ensuite créer la paire de clefs, déposer la clef publique sur le serveur Unix et expliquer à TortoisePlink ou trouver la clef privée. Attention la clef privée doit être au format ppk. Ce format de clef est propre à PuTTY, et TortoisePlink est basé sur le Plink de PuTTY.

Pour générer cette paire de clefs il faut utiliser puttygen, qui ne fait pas partie de TortoiseHg mais de de PuTTY.  Voir cette page sur comment générer cette paire de clefs avec puttygen.

Important : Pour simplifier ne pas attribuer de passphrase à la clef privée.

Par la suite on supposera que les noms de fichiers pour la paire de clefs sont:
   Publique : hg_rsa.pub
   Privée : hg_rsa.ppk

Déposer la clef publique sur le serveur Unix dans le répertoire de l’utilisateur dédié à hg. En principe on crée un utilisateur nommé ‘hg’ et les repository sont stockés dans son home directory.  Donc on dépose la clef publique hg_rsa.pub dans le répertoire /home/hg/.ssh  du serveur.

Ensuite il faut ajouter cette clef publique à la fin du fichier /home/hg/.ssh/authorized_keys
   cat hg_rsa.pub >> authorized_keys
On peut ensuite supprimer le fichier hg_rsa.pub coté serveur
   rm hg_rsa.pub



3) Mercurial.ini
Il faut maintenant expliquer à Hg comment utiliser ces clefs.
Dans le fichier %USERPROFILE%\Mercurial.ini ajouter dans la section [ui] la ligne

ssh = "C:\Program Files\TortoiseHg\TortoisePlink.exe" -ssh -2 -i "C:\Documents and Settings\Path\To\hg_rsa.ppk"

4) Init + Clone
Coté serveur, en utilisant le user dédié à hg, créer un repository vide:

cd /home/hg
hg init PremierTest

Coté client créer le repertoire PremierTest
Click bouton droit sur ce répertoire puis dans le menu contextuel sélectionner TortoiseHg > Clone ..

Remplacer le contenu du champ « Source » par   
   ssh://hg@mon.serveur.com//home/hg/PremierTest
ou  
   ssh://hg@mon.serveur.com/PremierTest
(en supposant que votre utilisateur soit hg)

ATTENTION : 
  Ne pas oublier le nom du user coté Unix (ici hg)
  Respecter la case du path coté Unix.  
  C'est bien un double / ou un simple / entre le nom du serveur et le path

Quand le path commence par un double / cela signifie qu'il est absolu.
Quand il commence par un simple / cela signifie qu'il est relatif au home directory du user (ici 'hg')

Un path relatif est moins dépendant des variations de l'organisation sur le disque du serveur et est donc préférable car plus stable.

Puis cliquer sur le bouton "Clone".

A partir de là il ne sera plus nécessaire de faire référence à ssh ou au nom du serveur. TortoiseHg a tout enregistré et générera les commandes ssh adéquates.

5) Apprendre !

Voici un très bon tutoriel (plein d'humour) sur Mercurial. Il ne présente que l'utilisation de la ligne de commande (hg). Mais la conversion en clicks sur l'interface graphique de TortoiseHg est facile.