Ce document est un mémento des commandes et de leurs enchainements lors de l’utilisation d’un dépôt local et d’un dépôt central hébergé sur Bitbucket. Le principe de travail est basé sur un fonctionnement avec 2 branches : default et stable.

La branche « default » est la branche de développement qui est toujours la plus à jour (HEAD dans le monde svn).

La branche « stable » est la branche contenant uniquement des versions stables. Le contenu de la branche « stable » correspond à la dernière release officielle. On utilise cette branche pour la correction de bugs urgents (hotfix).

Les actions Mercurial sont réalisées au moyen de la commande « hg ». Certaines actions concernent le dépôt local (interactions entre les sources et le dépôt local),  d’autres concernent le dépôt central (interactions entre le dépôt local et le dépôt central). Les commandes locales seront indiquées en bleu et les autres en rouge.

Pour l’exemple, le projet s’appelle « HelloWorld ». Le but est de commencer avec les 2 dépôt (local et central) synchronisés.

Cas 1 : le projet est totalement nouveau, il n’y a ni dépôt local, ni dépôt central

Créer un dépôts « HelloWord » central sur Bitbucket

On obtient l’url d’accès au dépot : ssh://hg@bitbucket.org/bejean/helloworld

Créer un dépôt local

$ mkdir /Projects/HelloWord
$ cd /Projects/HelloWord
$ hg init

Cas 2 : le projet existe dans un dépôt central

Créer un dépôt local et récupérer les sources du dépot central.

$ mkdir /Projects/HelloWord
$ cd /Projects/HelloWord
$ hg init

$ hg clone ssh://hg@bitbucket.org/bejean/helloworld

(cette commande met à jour à la fois le dépôt local et les sources, elle devrait être bleue et rouge)

Cas 3 : le projet existe dans un dépôt local

Créer un dépôt central.
On obtient l’url d’accès au dépôt : ssh://hg@bitbucket.org/bejean/helloworld

Se placer dans le dépôt local et envoyer les sources dans le dépôt central.

$ cd /Projects/HelloWord
$ hg push ssh://hg@bitbucket.org/bejean/helloworld

Pour la suite de cet article, nous supposons que l’on est dans le cas 1. On a alors nos dépôts créés mais vides.

Configuration

Afin de ne pas devoir spécifier l’url du dépôt central pour toutes les commandes qui interagissent entre le dépôt local et le dépôt central (en rouge), nous allons commencer par configurer notre dépôt local.

On édite le fichier « hgrc » du dépôt.

$ cd /Projects/HelloWord
$ vi .hg/hgrc

et on ajoute la section suivante :

[paths]
default = ssh://hg@bitbucket.org/bejean/helloworld

Début de développement

Commençons à travailler dans notre environnent local. On créer un fichier en local

$ cd /Projects/HelloWord
$ touch readme.txt

hg status indique que le fichier est inconnu dans le dépôt local

$ hg status
? readme.txt

On ajoute le fichier dans le dépôt local

$ hg add readme.txt

hg status indique que le fichier est connu dans le dépôt local mais pas à jour

$ hg status
A readme.txt

On met a jour le fichier dans le dépôt local

$ hg commit -m "Premiere version du fichier" readme.txt

hg status n’indique plus de fichier inconnus ou non à jour.

hg branches indique maintenant qu’il existe une branche « default »

$ hg branches
default                        0:621365c7850a

Le dépôt central n’est toujours pas au courant du contenu du dépôt local. On envoi nos modifications dans le dépôt central.

$ hg push
pushing to ssh://hg@bitbucket.org/bejean/helloworld
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 1 changes to 1 files
remote: bb/acl: bejean is allowed. accepted payload.

La copie d’écran si dessous montre que le dépot central est à jour avec une branche « default »

Publication d’une première version stable (v1.0) : branches et tags

On considère que cette version des sources du projet est la première version stable. Il faut donc maintenant :

1/ tagger la version

$ hg tag v1.0

2/ créer une branche « stable » qui soit le reflet de la branche « default »

$ hg branch stable
$ hg commit -m "branch stable"

Afficher les tags, les branches et la branche active.

$ hg tags
tip                                2:88b63958bb97
v1.0                               0:621365c7850a

$ hg branches
stable                         2:88b63958bb97
default                        1:6d1c947c8a95 (inactive)

$ hg branch
stable

On met à jour le dépôt central avec la nouvelle branche.

$ hg push --new-branch

Voici un schéma qui récapitule les différentes actions et les différents flux.

Attention, à cette étape, la branche active est « stable ». Il faut revenir à la branche « default », pour coder de nouvelles fonctionnalités.

$ hg update default
$ hg branch
default

Le développement continu …

On modifie le fichier readme.txt et la commande hg status nous le confirme.

$ hg status
M readme.txt

on commit les modifications dans le dépôt local

$ hg commit -m "Ajout d'une fonction"

On peut vérifier les modifications locales transférables dans le dépôt central.

$ hg outgoing
comparaison avec ssh://hg@bitbucket.org/bejean/helloworld
searching for changes
changeset:   3:2b9ef639a08b
tag:         tip
parent:      1:6d1c947c8a95
user:        Dominique Bejean <dominique.bejean@eolya.fr>
date:        Sat Nov 19 20:16:49 2011 +0100
summary:     Ajout d'une fonction

Si ces modifications sont terminées, on peut les mettre à disposition des autres développeurs dans le dépôt central

$ hg push

De même on peut vérifier les modifications faites dans le dépôt central (par d’autres développeurs) et pouvant être récurées. Dans notre cas, il n’y en a pas.

$ hg incoming
comparaison avec ssh://hg@bitbucket.org/bejean/helloworld
searching for changes
aucun changement trouvé

Régulièrement, on récupère dans notre dépôt local les modifications faites par les autres développeurs et disponibles dans le dépôt central.

$ hg pull
$ hg update

Publication d’un nouvelle version (v2.0)

La publication d’une nouvelle version implique de :

1/ tagger la branche active (default)

$ hg tag v2.0

2/ mettre à jour la stable (merger default dans stable)

$ hg update stable
$ hg merge default

(gérer les conflits. il ne devrait pas y en avoir si les hotfixs fait dans stable ont systématiquement été mergés dans default)

$ hg commit -m "merge from default"

3/ revenir dans la branche de développement

$ hg update default

Le diagramme suivant illustre les séquences de commandes durant le cycle de production d’une nouvelle version :

 

Correction d’un bug dans la version stable

1/ se placer dans la version stable

$ hg update stable

2/ corriger le bug

$ vi readme.txt

3/ commiter la correction

$ hg commit -m "v2.0 fixe"

4/ revenir à la branche default

$ hg update default

5/ merger la correction de la branche stable et résoudre les potentiels conflits

$ hg merge stable
$ vi readme.txt
$ hg resolve -m readme.txt
$ hg commit -m "merge resolve"
$ rm readme.txt.orig

 

Comme référence, on trouve les 2 diagrammes suivants sur le site ivy.fr (licence Creative Commons Attribution 3.0 Unported).

Un autre diagramme (trouvé sur le site secretGeek) qui indique un workflow basic. Le point 6 (qui n’est pas systématique) doit être suivi d’un « hg up ».