Inspiré par Git pour les débutants: Le guide pratique définitif .

Il s'agit d'une compilation d'informations sur l'utilisation de Mercurial pour les débutants à des fins pratiques .

Débutant - un programmeur qui a touché le contrôle des sources sans très bien le comprendre.

Pratique - couvrant les situations que la majorité des utilisateurs rencontrent souvent - création d'un référentiel, branchement, fusion, extraction / transfert depuis / vers un référentiel distant, etc.

Remarques :

• Expliquez comment faire quelque chose plutôt que comment quelque chose est mis en œuvre.
• Traitez une question par réponse.
• Répondez de façon claire et aussi concise que possible.
• Modifier / étendre une réponse existante plutôt que de créer une nouvelle réponse sur le même sujet.
• Veuillez fournir un lien vers le wiki Mercurial ou le livre HG pour les personnes qui souhaitent en savoir plus.

Des questions:

Installation / configuration

• Comment installer Mercurial?
• Comment configurer Mercurial?
• Comment créez-vous un nouveau projet / référentiel?
• Comment le configurez-vous pour ignorer les fichiers?

Travailler avec le code

• Comment obtenez-vous le dernier code?
• Comment extrayez-vous le code?
• Comment commettez-vous des changements?
• Comment voyez-vous ce qui n'est pas engagé ou l'état de votre base de code actuelle?
• Comment supprimer des fichiers du référentiel?
• Comment détruisez-vous les commits indésirables?
• Comment comparez-vous deux révisions d'un fichier, ou votre fichier actuel et une révision précédente?
• Comment voyez-vous l'historique des révisions d'un fichier ou d'un référentiel?
• Comment gérez-vous les fichiers binaires (visio docs, par exemple, ou les environnements de compilation)?
• Comment fusionner des fichiers modifiés en "même temps"?
• Comment annuler un ensemble de modifications?
• Comment revenir à une version précédente du code?
• Comment extraire un correctif d'un ensemble de modifications spécifique?
• Comment enregistrez-vous que vous avez renommé ou supprimé un fichier sans utiliser la commande Mercurial?

Marquage, branchement, versions, lignes de base

• Comment «marquer» «tag» ou «publier» un ensemble particulier de révisions pour un ensemble particulier de fichiers afin de pouvoir toujours le récupérer plus tard?
• Comment tirez-vous une «version» particulière?
• Comment branchez-vous?
• Comment fusionnez-vous les succursales?
• Comment fusionner des parties d'une branche dans une autre branche?

Autre

• Bon plugin GUI / IDE pour Mercurial? Avantages désavantages?
• Y a-t-il d'autres tâches courantes qu'un débutant devrait connaître?
• Comment puis-je interfacer avec Subversion?

Autres références Mercurial

• Mercurial: Le guide définitif
• Mercurial Wiki
• Rencontrez Mercurial | Screencast Peepcode
• Maîtriser Mercurial | TekPub Screencast
• Hg Init - Tutoriel Mercurial de base

Comment le configurez-vous pour ignorer les fichiers?

Ignorer est configuré dans un fichier texte normal appelé .hgignore à la racine de votre référentiel. Ajoutez-le comme un fichier normal avec:

hg add .hgignore

Il existe deux options de syntaxe disponibles pour la correspondance de fichiers, glob et regexp. glob est une extension de nom de fichier de type Unix et regexp est une expression régulière. Vous activez chacun en ajoutant syntax: globou syntax: regexpsur une ligne par lui-même. Toutes les lignes qui suivent utiliseront cette syntaxe jusqu'au prochain marqueur de syntaxe. Vous pouvez avoir autant de marqueurs de syntaxe que vous le souhaitez. La syntaxe par défaut est regexp, donc si vous utilisez uniquement regexp, vous n'avez pas besoin de marqueur de syntaxe.

Vous pouvez ajouter des commentaires avec #

Exemple:

# python temporary files
syntax: glob
*.pyc

#editor autosaves
*~

# temporary data
syntax: regexp
temp

Ignorer s'applique uniquement aux fichiers non gérés (c'est-à-dire les fichiers qui ne sont pas déjà archivés). Pour ignorer les fichiers sous contrôle de version, vous pouvez utiliser les commutateurs -I et -X.

Comment voyez-vous ce qui n'est pas engagé ou l'état de votre base de code actuelle?

Pour voir une liste des fichiers qui ont été modifiés:

$ hg status

Cela imprimera chaque fichier qui a été modifié avec son état, qui peut inclure:

• M- Modifié. Le fichier a été modifié et les modifications n'ont pas été validées.
• A- Ajoutée. Le fichier n'a pas été suivi auparavant, mais si vous validez, Mercurial commencera à le suivre.
• R- Supprimé. Le fichier a été suivi auparavant, mais si vous validez, Mercurial cessera de le suivre dans ce cas et dans les futurs validations.
• ?- Inconnue. Le fichier n'est actuellement pas suivi par Mercurial. La validation n'aura aucun effet à moins que vous ne l'utilisiez hg addpour l'ajouter.
• !- Disparu. Le fichier a été suivi mais Mercurial ne le trouve pas dans la copie de travail.

Pour voir les modifications réellement apportées aux fichiers:

$ hg diff

Comment créez-vous un nouveau projet / référentiel?

$ hg init my-repository

Comment puis-je interfacer avec Subversion?

Il existe trois façons:

L' extension convert convertira un dépôt Subversion existant en un dépôt Mercurial. Il vient avec Mercurial. Cela fonctionne à peu près comme ceci:

hg convert <Subversion URL or directory> <path to new Mercurial repository>

Par exemple, cela récupérera le tronc du référentiel memcached SixApart.

hg convert http://code.sixapart.com/svn/memcached/trunk

L'extension peut apporter progressivement de nouvelles révisions d'un référentiel Subversion dans le référentiel Mercurial (un peu comme tirer). Cependant, il ne prend pas en charge la prise de révisions Mercurial et leur renvoi à Subversion (sans push). [XXX: Corrigez cela si c'est faux] .

L' extension hgsubversion . C'est à bien des égards la solution la plus sophistiquée car elle utilise l'API Subversion pour communiquer avec le référentiel Subversion. Il vise à devenir le pont hg-svn. Il permet un déclenchement complet des révisions (clone complet, pull et push). Cependant, à ce jour [XXX: Modifiez ceci si / quand il devient incorrect] il est toujours en développement et il n'y a pas encore de versions officielles. En conséquence, il ne fonctionne qu'avec le Mercurial le plus récent (1.3 au moment de la rédaction).

• Il mappe les balises et les branches (précédant toutes les balises avec tags/pour les distinguer des branches nommées de manière équivalente).
• Il maintient une branche spéciale closed-branchespour fermer les branches qui sont supprimées dans Subversion.
• Cela nécessite que le référentiel Subversion soit disposé selon la convention tronc / branches / balises.
• Le jeu de commandes est généralement hg svn <subcommand>bien qu'il vise à être intégré au point que vous n'avez pas besoin de la partie «svn» (c'est-à-dire qu'il veut traiter un clone Subversion autant que possible comme tout autre référentiel Mercurial).

Cela fonctionne comme ceci:

cloner:

hg svnclone <Subversion URL> 

OU (uniquement pour les svn://URL)

hg clone <svn:// URL>

tirer:

hg svn pull

pousser:

hg svn push

entrant:

hg svn incoming

sortant:

hg svn outgoing

Extraire un référentiel entier:

hg svnclone http://code.sixapart.com/svn/memcached

L' utilitaire hgsvn ( arborescence bitbucket ). Jusqu'à récemment, cela ne vous permettait que de cloner et d'extraire un référentiel Subversion, mais à partir de maintenant hgsvn 0.1.7il prend en charge push. [Je ne sais pas comment bien il fait pousser. Quiconque ayant plus d'expérience devrait le mettre à jour.] Il présente les caractéristiques notables suivantes:

• Il génère une balise Mercurial pour chaque balise SVN.
• Il place une balise locale sur chaque ensemble de modifications pour marquer sa révision SVN.
• Il place chaque révision Mercurial sur une branche nommée nommée d'après sa branche SVN. Par exemple branches/some-featureserait comme hg branch some-feature. Il met le coffre trunk(c'est-à-dire que rien ne se trouve sur la branche par défaut de Mercurial, sauf si l'utilisateur y passe explicitement.)
• Il essaiera d'identifier les branches et les balises et de les créer, mais s'il ne le peut pas, il les saute simplement. Ceci est pratique lorsque le référentiel Subversion ne suit pas la disposition de tronc / branches / balises conventionnelle.

Cela fonctionne comme ceci:

cloner:

hgimportsvn <Subversion URL>

tirer:

hgpullsvn

pousser:

hgpushsvn

entrant:

hgpullsvn -n

sortant:

hgpushsvn -n

Extraire un référentiel entier:

hgimportsvn http://code.sixapart.com/svn/memcached

Vérifier juste le coffre:

hgimportsvn http://code.sixapart.com/svn/memcached/trunk

Comment comparez-vous deux révisions d'un fichier, ou votre fichier actuel et une révision précédente?

Les deux utilisent hg diff. Quand hg diffest utilisé tous les changements dans la copie de travail et le conseil (le dernier commit) est affiché.

Pour "Comment comparez-vous deux révisions d'un fichier?"

$ hg diff -r{rev1} -r{rev2} {file.code}

La commande ci-dessus montrera différent entre rev1 et rev2 de "file.code".

Pour "Comment comparez-vous votre fichier actuel et une révision précédente?"

$ hg diff {file.code}

La commande ci-dessus affichera une différence entre la version actuelle de "file.code" et la dernière révision (la dernière validée).

:RÉ

Comment «marquer» «tag» ou «publier» un ensemble particulier de révisions pour un ensemble particulier de fichiers afin de pouvoir toujours le récupérer plus tard?

$ hg tag my-tag

Vous pouvez également cloner votre référentiel pour créer un référentiel de balises spécial .

$ hg clone working-repository my-tag-repository

Comment branchez-vous?

$ hg branch my-branch

ou

$ hg clone original-repository my-branch

Bien qu'il soit à noter que la branche crée un répertoire "virtuel" (c'est-à-dire que les fichiers restent les mêmes, mais hg les traite comme s'ils étaient différents à l'intérieur du système), tandis que le clone crée une copie complète et réelle. À strictement parler, le clone ne se ramifie pas.

Bon plugin GUI / IDE pour Mercurial?

GUI

• TortoiseHg pour à peu près n'importe quel système d'exploitation. Comprend l'intégration de l'Explorateur Windows. Il fonctionne également sous Linux et quelques autres OS: y compris Max OS X. Il a une interface quelque peu maladroite et est un peu gênant à utiliser au début, mais il est très complet et puissant.
• Murky fonctionne sur Mac OS X 10.5 ou version ultérieure. Murky est bon pour explorer le référentiel et les commandes de base, mais vous devrez également savoir comment utiliser la ligne de commande.
• MacHg est un joli Mac OS X Gui qui a un peu plus de fonctionnalités et de raffinement que Murky, mais vous aurez également besoin de la ligne de commande.
• SourceTree est un client Mac à l'origine, avec une version Windows disponible récemment. Interface assez agréable (au moins sur OS X), prend en charge la majorité des fonctionnalités Hg, y compris les étagères.

Plugins

• VisualHG pour Visual Studio
• HgSccPackage pour Visual Studio 2008/2010
• MercurialEclipse pour Eclipse
• Prise en charge de Mercurial pour NetBeans
• Support Mercurial pour Sublime Text

Comment commettez-vous des changements?

Appelez cette commande à partir du référentiel mercurial local * actuel

hg commit [OPTION]... [FILE]...

alias: ci

• Un dépôt mercurial local a .hg dans le répertoire courant

Où l'option peut être:

 -A --addremove     mark new/missing files as added/removed before committing
    --close-branch  mark a branch as closed, hiding it from the branch list
 -I --include       include names matching the given patterns
 -X --exclude       exclude names matching the given patterns
 -m --message       use <text> as commit message
 -l --logfile       read commit message from <file>
 -d --date          record datecode as commit date
 -u --user          record user as committer

Un exemple de commande serait:

hg commit -m "added readme" README

REMARQUES :

• Si une liste de fichiers est omise, toutes les modifications signalées par "hg status" seront validées.
• Si vous validez le résultat d'une fusion, ne fournissez aucun nom de fichier ni filtre -I / -X.
• Si aucun message de validation n'est spécifié, l'éditeur configuré est démarré pour vous demander un message.

Comment configurer Mercurial?

Mercurial stocke ses informations de configuration ~/.hgrcsur les systèmes * nix et %UserProfile%\mercurial.inisur les systèmes Windows. ( %UserProfile%est généralement "C:\Documents and Settings\[username]\"sur les systèmes Windows 2000 ou Windows XP, et généralement C:\Users\[username]\sur les systèmes Windows Vista et Windows 7.)

Comme point de départ, vous devez définir votre nom d'utilisateur Mercurial en plaçant ce qui suit dans votre .hgrcou mercurial.ini:

# This is a Mercurial configuration file.
[ui]
username = Firstname Lastname <email.address@example.net>

Les utilisateurs de TortoiseHg sur les systèmes Windows peuvent également exécuter hgtk userconfig

Voir également « Création d'un fichier de configuration Mercurial » dans le chapitre 2 de « Mercurial: The Definitive Guide ».

Comment fusionnez-vous les succursales?

$ cd repository-where-i-want-to merge
$ hg pull branch-i-want-to-merge
$ hg merge # if necessary

Comment installer Mercurial?

Veuillez bien éditer si vous avez installé à partir des sources sur Linux, ou utilisé les installateurs Windows.

Mac OS X 10.4 (Tiger), 10.5 (Leopard)

Utilisez easy_install de Python (avec Setuptools ):

sudo easy_install mercurial

Cela trouve la dernière version (1.3.1 au moment de la rédaction) et installe à:

/Library/Frameworks/Python.framework/Versions/2.6/bin/

Avec Python 2.6, cela contourne également le package d'installation de Mercurial OS X (à la version 1.2.1 du 26 juillet 2009) se plaignant d'avoir besoin de Python 2.5. D'après la documentation , il apparaît que Fink et Macports installent la version 1.2.

Linux

La plupart des packages Linux explicites semblent être en retard sur la version actuelle, alors utilisez easy_install (comme ci-dessus) ou téléchargez l' archive tar Mercurial , extrayez l'archive, accédez au répertoire mercurial et exécutez:

$ make
$ sudo make install    # do a system-wide install
$ hg debuginstall      # sanity check
$ hg                   # see help

(de Introducing Mercurial, un système de contrôle de version distribué )

les fenêtres

Il existe un package binaire de la dernière version de Mercurial . TortoiseHg est une extension shell Windows pour et installe Mercurial. Cygwin peut également installer Mercurial.

Alternativement (instructions trop longues donc liées ici), vous pouvez créer une version Python optimisée ou pure de Mercurial à partir des sources.

Comment obtenez-vous le dernier code?

Mercurial se souvient d'où un référentiel a été cloné (en .hg / hgrc) afin que vous puissiez simplement exécuter:

hg pull

pour extraire le dernier code du référentiel d'origine. (Cela ne met pas à jour le répertoire de travail)

hg update

pour mettre à jour le répertoire de travail.

hg pull -u

pour effectuer à la fois un pull et une mise à jour.

Comment extrayez-vous le code?

hg clone [OPTION]... SOURCE [DEST]

Où l'option peut être:

 -U --noupdate      the clone will only contain a repository (no working copy)
 -r --rev           a changeset you would like to have after cloning
    --pull          use pull protocol to copy metadata
    --uncompressed  use uncompressed transfer (fast over LAN)
 -e --ssh           specify ssh command to use
    --remotecmd     specify hg command to run on the remote side

Où source est la source des fichiers d'origine situés dans le référentiel, où il peut s'agir d'une URL distante ou d'un répertoire de système de fichiers. Par exemple:

• http://bitbucket.org/scrum8/django-wmd-editor/
• / home / nom d'utilisateur / dépôt / django-wmd-editor /
• ssh: //myusername@scrum8.com/~/repository/django-wmd-editor/

Et la destination est l'endroit où le code source sera situé dans votre système de fichiers local.

Comment commettez-vous des changements?

$ hg commit -m "Commit message"

Comment voyez-vous quelles modifications seront envoyées au référentiel en amont lorsque vous poussez?

Utilisez hg outgoingpour obtenir la liste des changements qui seront définis sur le référentiel par défaut:

$ hg outgoing

Pour obtenir les changements de code réels, utilisez -p( --patch). Cela affichera chaque ensemble de modifications dans son intégralité:

$ hg outgoing -p

Comment supprimer un fichier du référentiel?

Pour supprimer un fichier du référentiel et le supprimer lors du prochain commit:

$ hg remove {file(s)}

Pour supprimer un fichier du référentiel, mais ne pas le supprimer

$ hg remove -Af {file(s)}

ou de Mercurial 1.3

$ hg forget {file(s)}

Comment revenir à une version précédente du code?

De cette question

$ hg update [-r REV]

@van: Si plus tard vous vous engagez, vous créerez effectivement une nouvelle branche. Ensuite, vous pouvez continuer à travailler uniquement sur cette branche ou éventuellement fusionner la branche existante en elle.

Comment annuler un ensemble de modifications?

Quelques options disponibles

Easy Way (sauvegarde d'un seul jeu de modifications)

$ hg backout -m 'back out second change' tip
reverting myfile
changeset 2:01adc4672142 backs out changeset 1:7e341ee3be7a
$ cat myfile
first change

Hard Way (diff manuellement et appliquer)

Étape 1 : Créez un fichier de correctif pour annuler ce qui a changé entre la révision 107 et 108:

hg diff -r107 -r108 --reverse  > revert-change.patch

(alternativement, hg diff -r108 -r107 sans --reverse fera la même chose)

Étape 2 : appliquez le fichier de patch:

patch -p1 < revert-change.patch

Certaines différences peuvent ne pas s'appliquer, par exemple:

Hunk #3 FAILED at 517.
1 out of 3 hunks FAILED -- saving rejects to file 'foo/bar.c.rej'

Le fichier .rej contiendra le contenu du diff qui n'a pas pu s'appliquer, vous devrez y jeter un œil.

Comment voyez-vous l'historique des révisions d'un fichier ou d'un référentiel?

Pour afficher l'historique des révisions de l'ensemble du référentiel ou des fichiers

$ hg log {file(s)}

ou

$ hg history {file(s)}

Et pour voir la liste dans l'ordre inverse

$ hg log -r:

Comment fusionner des parties d'une branche dans une autre branche?

Activez l'extension 'transplant' dans votre .hg / hgrc

[extensions]
transplant=

Chargez la branche cible puis transplantez la révision cible.
ex: cerise sur le gâteau révision 81 de la branche 'foo' dans la branche courante

$ hg transplant -b foo 81

Comment extraire un correctif d'un ensemble de modifications spécifique?

$ hg export -o patchfile changeset

Vous pouvez ensuite l'importer dans une autre branche avec:

$ hg import patchfile