romain@931: \chapter{Un rapide tour de Mercurial}
bos@95: \label{chap:tour-basic}
bos@84: 
romain@931: \section{Installer Mercurial sur votre système}
bos@84: \label{sec:tour:install}
bos@84: 
huguesfrachon@942: Des paquetages binaires de Mercurial sont disponibles pour la plupart
huguesfrachon@942: des systèmes d'exploitation, ce qui rend facile l'utilisation immédiate
huguesfrachon@942: de Mercurial sur votre ordinateur.
bos@85: 
bos@84: \subsection{Linux}
bos@84: 
romain@931: Parce que chaque distribution de Linux a ses propres outils de gestion
huguesfrachon@942: de paquets, politiques et rythmes de développements, il est difficile de
Wilk@956: donner un ensemble d'instructions uniques pour installer les binaires de
romain@931: Mercurial. La version de Mercurial avec laquelle vous vous retrouverez
huguesfrachon@942: dépendra grandement de l'activité de la personne en charge du paquetage
romain@931: pour la distribution.
romain@931: 
huguesfrachon@942: Pour rester simple, je me concentrerai sur l'installation de Mercurial
Wilk@956: en ligne de commande, sous les distributions les plus courantes. La 
romain@931: plupart des distributions fournissent des gestionnaires graphiques de
romain@931: paquetage qui vous permettront d'installer Mercurial en quelques clicks.
romain@931: Le paquetage devrait se nommer \textit{mercurial}.
bos@84: 
bos@85: \begin{itemize}
bos@85: \item[Debian]
bos@85:   \begin{codesample4}
bos@85:     apt-get install mercurial
bos@85:   \end{codesample4}
bos@84: 
bos@85: \item[Fedora Core]
bos@85:   \begin{codesample4}
bos@85:     yum install mercurial
bos@85:   \end{codesample4}
bos@84: 
bos@85: \item[Gentoo]
bos@85:   \begin{codesample4}
bos@85:     emerge mercurial
bos@85:   \end{codesample4}
bos@84: 
bos@85: \item[OpenSUSE]
bos@85:   \begin{codesample4}
bos@85:     yum install mercurial
bos@85:   \end{codesample4}
bos@84: 
belaran@943: \item[Ubuntu] Le paquetage de Mercurial d'Ubuntu est construit sur celui de Debian. 
Wilk@956:               Pour l'installer, exécutez simplement les commandes suivantes:
bos@262:   \begin{codesample4}
bos@262:     apt-get install mercurial
bos@262:   \end{codesample4}
romain@931:   Les paquetages Ubuntu pour Mercurial ont tendance à être un peu en retard
belaran@943:   par rapport au paquetage Debian (au moment de l'écriture de ce livre, il
Wilk@956:   faut compter à peu près un retard de 7 mois), ce qui signifie que parfois 
belaran@943:   sur Ubuntu, vous risquez de rencontrer des problèmes qui ont été corrigés 
belaran@943:   depuis longtemps dans les paquetages Debian.
bos@85: \end{itemize}
bos@84: 
arne@264: \subsection{Solaris}
arne@264: 
romain@931: SunFreeWare, à \url{http://www.saufreeware.com}, est une bonne source 
huguesfrachon@942: pour trouver un vaste nombre de paquets précompilés pour 32 ou 64 bits
romain@931: Intel et les architecture Sparc, dont les versions courantes de Mercurial.
arne@264: 
bos@84: \subsection{Mac OS X}
bos@84: 
Wilk@956: Lee Cantey publie un installateur de Mercurial pour Mac OS~X sur le site 
romain@931: \url{http://mercurial.berkwood.com}.  Ce paquetage fonctionne sur les 
Wilk@956: architectures Intel-~et PowerPC. Avant de vous en servir, vous devez
Wilk@956: installer une version Universelle MacPython~\cite{web:macpython}. C'est
romain@931: assez facile à faire : suivez simplement les instructions sur le site
romain@931: de Lee.
romain@931: 
romain@931: Il est aussi possible d'installer Mercurial en utilisant Fink ou MacPorts,
huguesfrachon@942: deux outils de gestion de paquetage libres pour Mac OS X. Si vous avez 
Wilk@956: Fink, utilisez \command{sudo fink install mercurial-py25}. Si vous avez 
Wilk@956: MacPorts, \command{sudo port install mercurial}.
simon@313: 
bos@84: \subsection{Windows}
bos@84: 
Wilk@956: Lee Cantey publie aussi un installateur de Mercurial pour Windows sur le site
romain@931: \url{http://mercurial.berkwood.com}. Ce paquetage n'a aucune dépendance 
romain@931: externe, il fonctionne ``tout court''.
bos@84: 
bos@84: \begin{note}
Wilk@956:   La version de Windows de Mercurial ne convertie pas automatiquement
Wilk@956:   les retours chariot Windows et Unix. Si vous désirez partager votre
romain@931:   travail avec des utilisateurs Unix, vous devez faire un peu de configuration
Wilk@956:   supplémentaire. XXX En dire plus.
bos@84: \end{note}
bos@84: 
romain@931: \section{Commencer à utiliser Mercurial}
romain@931: 
romain@931: Pour commencer, nous utiliserons la commande \hgcmd{version} pour vérifier
romain@931: si Mercurial est installé proprement. Les informations affichées sur la 
Wilk@956: version ne sont pas réellement importantes en soit, c'est surtout de savoir
romain@931: si elles s'affichent qui nous intéresse.
bos@87: \interaction{tour.version}
bos@87: 
romain@931: \subsection{L'aide intégrée}
romain@931: 
romain@931: Mercurial fournit un système d'aide intégré, ce qui est inestimable quand
romain@931: vous vous retrouvez coincé à essayer de vous rappeler comment lancer telle
romain@931: ou telle commande. 
Wilk@956: Si c'est le cas, exécutez simplement \hgcmd{help}; il vous aidera à imprimer
huguesfrachon@942: une brève liste de commandes, avec une description de ce qu'elles font. Si vous
Wilk@956: demandez de l'aide sur une commande spécifique (voir ci-dessous), il affichera
huguesfrachon@942: des informations plus détaillées.
bos@87: \interaction{tour.help}
huguesfrachon@942: Pour un niveau d'informations encore plus détaillées (ce dont vous aurez rarement
huguesfrachon@942: besoin), exécuter \hgcmdargs{help}{\hggopt{-v}}.  L'option \hggopt{-v} est 
romain@931: l'abréviation de \hggopt{--verbose}, et indique à Mercurial d'afficher plus 
huguesfrachon@942: d'informations que d'habitude.
romain@931: 
Wilk@956: \section{Travailler avec un dépôt}
Wilk@956: 
Wilk@956: Avec Mercurial, tout se déroule au sein du \emph{dépôt}\footnote{NdT: Dépôt est
huguesfrachon@942: la traduction que j'ai retenue pour tout l'ouvrage du terme anglais \textit{repository}}.
huguesfrachon@942: Le dépôt d'un projet contient tous les fichiers qui ``appartiennent'' au projet.
belaran@938: 
Wilk@956: Il n'y a rien de particulièrement magique au sujet de ce dépôt, c'est
Wilk@956: simplement une arborescence sur votre système de fichiers que Mercurial
huguesfrachon@950: traite de manière spéciale. Vous pouvez renommer ou effacer ce répertoire
Wilk@956: à n'importe quel moment, en utilisant la ligne de commande ou votre
belaran@938: explorateur de fichiers.
belaran@938: 
Wilk@956: \subsection{Faire une copie locale de votre dépôt}
belaran@938: 
huguesfrachon@950: \emph{Copier} un dépôt est juste un peu spécial. Bien que vous 
belaran@938: puissiez utiliser une commande habituelle de copie pour copier
belaran@938: votre dépôt, il vaut mieux utiliser une commande fournie par
belaran@938: Mercurial. Cette commande est appelée \hgcmd{clone}, car elle
Wilk@956: crée une copie identique à un dépôt existant.
bos@87: \interaction{tour.clone}
belaran@938: Si votre opération de clonage réussit, vous devriez maintenant
belaran@938: avoir un répertoire local appelé \dirname{hello}. Ce répertoire
belaran@938: contiendra quelques fichiers.
bos@87: \interaction{tour.ls}
belaran@938: Ces fichiers ont le même contenu et historique dans votre dépôt
belaran@938: qu'ils ont dans le dépôt que vous avez cloné.
belaran@938: 
belaran@938: Chaque dépôt Mercurial est complet, autonome et indépendant. Il
Wilk@956: contient sa propre copie privée des fichiers du projet et de leur
Wilk@956: historique. Le clone d'un dépôt se souvient de la localisation du
belaran@938: dépôt à partir duquel il a été clôné, mais il ne communique pas avec
belaran@938: ce dernier, ou un autre, à moins que vous ne lui demandiez.
belaran@938: 
huguesfrachon@950: Ce que tout ceci signifie pour le moment est que nous sommes libres
huguesfrachon@950: d'expérimenter avec ce dépôt, confiants dans le fait qu'il s'agit d'un
huguesfrachon@950: ``bac à sable'' qui n'affectera personne d'autre.
belaran@938: 
belaran@938: \subsection{Quel est le contenu d'un dépôt ?}
belaran@938: 
belaran@938: Prêtons plus attention un instant au contenu d'un dépôt. Nous voyons 
huguesfrachon@950: qu'il contient un répertoire nommé \dirname{.hg}. C'est ici que Mercurial
belaran@938: conserve toutes ses métadonnées.
bos@88: \interaction{tour.ls-a}
bos@88: 
belaran@938: Le contenu du répertoire \dirname{.hg} et ses sous répertoires sont les
huguesfrachon@950: seuls propres à Mercurial. Tous les autres fichiers et répertoires dans 
Wilk@956: le dépôt sont à vous, et vous pouvez en faire ce que vous voulez.
belaran@938: 
belaran@938: Pour introduire un peu de terminologie, le répertoire \dirname{.hg} est
huguesfrachon@950: un ``vrai'' dépôt, et tous les fichiers et les répertoires qui coexistent
Wilk@956: avec lui, sont désignés sous le nom \emph{espace de travail}\footnote{NdT: 
belaran@938: \textit{working directory}}. Une manière facile de se rappeler cette 
belaran@938: distinction est de retenir que le \emph{dépôt} contient l'\emph{historique}
belaran@938: de votre projet, alors que l'\emph{espace de travail} contient une \emph{copie
Wilk@956: ponctuelle}\footnote{NdT: Ce terme est une traduction du terme anglais 
belaran@938: \textit{snapshot}. Il est traduit ici pour faciliter la lecture, mais ne sera
belaran@938: plus traduit par la suite.} de votre projet à un certain point de son
belaran@938: historique.
belaran@938: 
belaran@938: \section{Une ballade dans l'historique}
belaran@938: 
belaran@938: Une des premières choses que vous aurez envie de faire avec un nouveau
belaran@938: dépôt, sera de comprendre son historique. La commande \hgcmd{log} vous
belaran@938: donne une vue de l'historique.
bos@88: \interaction{tour.log}
belaran@938: Par défaut, cette commande affiche à l'écran un bref paragraphe pour chaque
belaran@938: révision enregistrée pour ce projet. Dans la terminologie de Mercurial, nous
belaran@938: appelons chacun de ces évènements enregistrés un \emph{changeset}, parce 
Wilk@956: qu'il contient un ensemble de modifications sur plusieurs fichiers.
belaran@938: 
belaran@938: La commande \hgcmd{log} affiche ainsi ces informations:
bos@88: \begin{itemize}
Wilk@956: \item[\texttt{changeset}] Ce champ contient un nombre, séparé par deux points
Wilk@956:   (:), d'une chaine hexadécimale. Il s'agit en fait d'\emph{identifiants}
Wilk@956:   d'un \textit{changeset}. Il y a deux identifiants car le numéro de
belaran@938:   la révision est plus court et plus à facile à saisir qu'une séquence
belaran@938:   hexadécimale.
Wilk@956: \item[\texttt{user}] L'identité de la personne qui a créée ce  %%% laisser le terme anglais car il sera affiché
belaran@938:   \textit{changeset}. C'est un champ libre de forme, mais la plupart du
belaran@938:   temps il contient le nom et l'email de la personne.
belaran@938: \item[\texttt{date}] La date et l'heure à laquelle le \textit{changeset}
Wilk@956:   a été créé, ainsi que le \textit{fuseau horaire} dans laquelle il a été créé. %%%TODO: Translate 'timezone' properly : FUSEAU
Wilk@956:   (La date et l'heure sont locales à ce \textit{fuseau}, elles indiquent
Wilk@956:   donc quelle date et heure il était pour la personne qui a créé ce %%%TODO: je suppose (quelle "heure")  OUI
belaran@938:   \textit{changeset}.)
Wilk@956: \item[\texttt{résumé}] La première du message que le créateur a associé à
belaran@938:   son \textit{changeset} pour le décrire.
bos@88: \end{itemize}
belaran@938: 
belaran@938: Par défaut, la commande \hgcmd{log} n'affiche qu'un résumé, il manque 
belaran@938: beaucoup de détails.
belaran@938: 
Wilk@956: La figure~\ref{fig:tour-basic:history} fournit une représentation graphique
belaran@938: de l'historique du dépôt \dirname{hello}, pour rendre plus facile de voir
belaran@938: dans quelle direction l'historique se ``déroule''\footnote{NdT: \textit{flowing in}.}.
Wilk@956: Nous reviendrons régulièrement sur cette représentation dans ce chapitre et
belaran@938: ceux qui suivent.
bos@97: 
bos@96: \begin{figure}[ht]
bos@96:   \centering
bos@96:   \grafix{tour-history}
belaran@938:   \caption{Représentation graphique du dépôt \dirname{hello} }
bos@99:   \label{fig:tour-basic:history}
bos@96: \end{figure}
bos@96: 
huguesfrachon@950: \subsection{Changesets, révisions, et discuter avec les autres}%%%TODO: je propose : "discussion" (3 noms communs)
Wilk@956: %%% je propose "colaboration"
huguesfrachon@950: 
huguesfrachon@950: Comme l'anglais est réputé pour être un langage maladroit, et que l'informatique
Wilk@956: est la source de bien des erreurs de terminologies (pourquoi utiliser un
belaran@939: seul terme quand quatre feront l'affaire ?), la gestion de version a une
huguesfrachon@950: variété de mots et de phrases qui veulent dire la même chose. Si vous 
Wilk@956: discutez d'historique de Mercurial avec d'autres personnes, 
huguesfrachon@950: %%%TODO: ça ne veut rien dire: il faut supprimer une des personnes : soit "quelqu'un", 
huguesfrachon@950: % soit "à d'autres personnes"
Wilk@956: vous constaterez que souvent le mot ``\textit{changeset}'' est contracté simplement
huguesfrachon@950: en ``change'' ou (à l'écrit) ``cset'', et même parfois un 
belaran@939: \textit{changeset} simplement ``révision'', abrégé en ``rev''.
belaran@939: 
belaran@939: Bien que le \emph{mot} que vous utilisez pour désigner le concept de
belaran@939: \textit{changeset} importe peu, l'\emph{identifiant} que vous utilisez
Wilk@956: pour désigner un \emph{changeset} \textit{spécifique} a une grande
Wilk@956: importance. Rappelez vous que le champ \textit{changeset} affiché par la 
belaran@939: commande \hgcmd{log} identifie un \textit{changeset} à la fois avec
belaran@939: un numéro de révision et une séquence hexadécimale.
belaran@939: 
bos@97: \begin{itemize}
belaran@939: \item Le numéro de révision est \emph{seulement valable dans ce dépôt},
belaran@939: \item alors que la séquence hexadécimale est un \emph{identifiant 
huguesfrachon@950: 	permanent, et invariant } qui pourra toujours être associé au 
huguesfrachon@950: 	\textit{changeset} exact de \emph{chaque} copie de votre dépôt.
bos@97: \end{itemize}
belaran@939: 
belaran@939: La distinction est importante. Si vous envoyez un email à quelqu'un en
belaran@939: parlant de la ``révision 33'', il est très probable que sa révision~33
belaran@939: \emph{ne sera pas la même} que la votre. La raison de ceci est que le
belaran@939: numéro de révision dépend de l'ordre dans lequel les modifications sont
huguesfrachon@950: arrivées dans le dépôt, et il n'y a aucune garantie que les mêmes changements
belaran@939: soient arrivés dans le même ordre dans différents dépôts. Trois modifications
belaran@939: $a,b,c$ peuvent aisément apparaitre dans un dépôt comme $0,1,2$, et dans
belaran@939: un autre comme $1,0,2$.
belaran@939: 
Wilk@956: Mercurial utilise les numéros de révision uniquement comme des raccourcis
Wilk@956: pratiques. Si vous devez discuter d'un \textit{changeset} avec quelqu'un, 
Wilk@956: ou identifer un \textit{changeset} pour une quelquonque %%%TODO: our : "pour" ou "ou"
belaran@939: raison (par exemple, un rapport de \textit{bug}), utilisez la séquence
belaran@939: hexadécimale.
belaran@939: 
belaran@939: \subsection{Afficher une révision spécifique}
belaran@939: 
belaran@939: Pour réduire la sortie de \hgcmd{log} à une seule révision, utilisez
huguesfrachon@950: l'option \hgopt{log}{-r} (ou \hgopt{log}{--rev}). Vous pouvez utiliser
huguesfrachon@950: le numéro de révision ou la séquence hexadécimale comme identifiant, et 
Wilk@956: demander autant de révisions que vous le souhaitez. 
belaran@939: \interaction{tour.log-r}
belaran@939: 
belaran@939: Si vous voulez voir l'historique de plusieurs révisions sans avoir à 
belaran@939: les énumérer, vous pouvez utiliser la \emph{\textit{range notation}}
Wilk@956: \footnote{NdT: Il n'est pas aisé de traduire ce terme, donc je le  %%%TODO : intervalle de numérotation ?
belaran@939: laisse en anglais} qui vous permet d'exprimer l'idée ``je veux toutes
belaran@939: les révisions entre $a$ et $b$, inclus''.
bos@88: \interaction{tour.log.range}
huguesfrachon@950: Mercurial respecte aussi l'ordre dans lequel vous spécifiez les 
belaran@939: révisions, ainsi \hgcmdargs{log}{-r 2:4} affichera $2,3,4$ alors que 
belaran@939: \hgcmdargs{log}{-r 4:2} affichera $4,3,2$.
belaran@939: 
belaran@939: \subsection{Informations détaillées}
bos@91: 
belaran@948: 
Wilk@956: Le résumé affiché par \hgcmd{log} est suffisant si vous savez déjà ce %%%TODO: je pense que le premier "si" est de trop : exact
Wilk@956: que vous cherchez. En revanche, vous aurez probablement besoin de voir une description
Wilk@956: complète du changement, ou une liste des fichiers modifiés si vous 
Wilk@956: cherchez à déterminer qu'un \textit{changeset} est bien celui que vous%%%TODO: les propositions sont mal construites : après un "si...." il faut une proposition sans "si... donc ici : "si ... recherchez", ben quoi ?
belaran@940: recherchez. L'option \hgopt{-v} de la commande \hgcmd{log} (ou 
Wilk@956: \hgopt{--verbose}) vous donne ces informations supplémentaires.
bos@91: \interaction{tour.log-v}
bos@91: 
belaran@949: Si vous voulez voir à la fois la description et le contenu d'une 
belaran@949: modification, ajouter l'option \hgopt{log}{-p} (ou \hgopt{log}{--patch}).
belaran@949: Ceci affiche le contenu d'une modification comme un \emph{diff unifié}
belaran@949: \footnote{NdT: \textit{unified diff}} (si vous n'avez jamais vu de diff 
huguesfrachon@950: unifié avant, consultez la section~\ref{sec:mq:patch} pour un rapide 
belaran@949: survol).
belaran@948: 
bos@91: \interaction{tour.log-vp}
bos@91: 
belaran@940: \section{Tout sur les options de commandes}
belaran@940: 
belaran@946: 
belaran@940: Avant d'aller plus loin sur le fonctionnement des commandes de Mercurial,
huguesfrachon@950: étudions un moment comment elles fonctionnent de manière générale. Vous
belaran@940: trouverez ça probablement utile pour la suite de notre parcours.
belaran@940: 
Wilk@956: Mercurial utilise une approche directe et cohérente pour interpréter %%%TODO: une manière d'approche ?
belaran@940: les options que vous passez aux commandes. Il suit une convention commune
belaran@940: à la plupart des systèmes Unix et Linux modernes.
belaran@940: 
bos@91: \begin{itemize}
belaran@947: \item Chaque option a un nom complet. Par exemple, comme nous l'avons déjà
Wilk@956:       vu, la commande \hgcmd{log} accepte l'option \hgopt{log}{--rev}.%%%TODO: commande ou command e\hgcmd...?
huguesfrachon@950: \item La plupart des options disposent de noms abrégés. Aussi, au lieu d'utiliser
belaran@947:   \hgopt{log}{--rev}, vous pouvez utiliser \hgopt{log}{-r}. (Les options qui
Wilk@956:   n'ont pas de noms abrégés sont généralement rarement utilisées, pour cette raison).
huguesfrachon@950: \item Les noms complets commencent par deux tirets (i.e.~\hgopt{log}{--rev}),
belaran@947:   alors que les options courtes commencent avec un seul (i.e.~\hgopt{log}{-r}).
huguesfrachon@950: \item Les noms des options sont cohérents entre les commandes. Par exemple, 
Wilk@956:   chaque commande qui accepte un \textit{changeset~ID} ou un numéro de révision
belaran@947:   accepte aussi \hgopt{log}{-r} et \hgopt{log}{--rev} comme arguments.
belaran@947:   %TODO: Small mistake here, shouldn't have log here... shouldn't it ?
bos@91: \end{itemize}
belaran@947: 
huguesfrachon@950: Dans les exemples de ce livre, j'utilise les noms abrégés plutôt que les noms
huguesfrachon@950: complets. Ceci est une préférence personnelle, pas une recommandation.
huguesfrachon@950: 
Wilk@956: La plupart des commandes qui affichent une quelconque sortie à l'écran,
Wilk@956: afficheront davantage avec l'option \hggopt{-v} (ou \hggopt{--verbose}), et
huguesfrachon@950: moins avec l'option \hggopt{-q} (ou \hggopt{--quiet}).
belaran@947: 
belaran@947: \section{Faire et vérifier des modifications}
belaran@947: 
huguesfrachon@950: Maintenant que nous avons une bonne idée des commandes pour consulter 
huguesfrachon@950: l'historique de Mercurial, regardons comment faire des modifications et 
huguesfrachon@950: les examiner.
huguesfrachon@950: 
belaran@947: 
belaran@947: La première chose que nous allons faire c'est isoler notre expérience dans
belaran@947: un dépôt à part. Nous allons utiliser la commande \hgcmd{clone}, mais nous
belaran@947: n'avons pas besoin de faire une copie de dépôt distant. Comme nous avons 
Wilk@956: déjà une copie locale, nous pouvons juste faire un clone de celle-ci à la 
belaran@947: place. C'est beaucoup plus rapide que de faire une copie à travers le 
Wilk@956: réseau, et un dépôt cloné localement prend également moins d'espace disque.
belaran@947: 
bos@91: \interaction{tour.reclone}
belaran@947: 
belaran@947: On notera au passage qu'il est souvent considéré comme une bonne pratique
belaran@947: de conserver une copie ``immaculée'' du dépôt distant, à partir de laquelle
belaran@947: vous pourrez faire des copies locales temporaires pour créer des ``bacs à 
belaran@947: sable'' pour chaque tâche sur laquelle vous souhaitez travailler. Ceci vous
huguesfrachon@950: permet de travailler sur plusieurs choses en parallèle, chacune isolée les 
huguesfrachon@950: unes des autres en attendant que ces tâches soient finies et que vous soyez
huguesfrachon@950: prêt à les réintégrer. Parce que les copies locales sont peu coûteuses, il
belaran@947: est très rapide de créer ou détruire des dépôts dès que vous en avez besoin.
belaran@947: 
belaran@947: %% Note: la dernière phrase n'est pas une traduction littérale, mais je
belaran@947: %% pense qu'elle exprime plus clairement en français ce que veut dire son 
Wilk@956: %% équivalent anglais. : OUI
belaran@947: 
belaran@947: Dans notre dépôt \dirname{my-hello}, nous avons un fichier \filename{hello.c}
belaran@947: qui contient le classique programme ``hello, world''. Nous allons utiliser 
Wilk@956: l'ancienne et vénérable commande \command{sed} pour l'éditer afin qu'il 
belaran@947: affiche une seconde ligne à l'écran. (J'utilise \command{sed} seulement parce
Wilk@956: qu'il est ainsi facile d'écrire des exemples sous forme de script. Comme 
belaran@947: vous n'avez pas ces contraintes, vous n'utiliserez probablement pas \command{sed}
belaran@947: mais plutôt votre éditeur de texte favori). 
belaran@947: 
bos@91: \interaction{tour.sed}
bos@91: 
belaran@947: La commande \hgcmd{status} de Mercurial nous dira de quels fichiers Mercurial
belaran@947: s'occupe au sein de ce dépôt.
bos@91: \interaction{tour.status}
belaran@947: La commande \hgcmd{status} n'affiche rien sur la sortie pour quelques fichiers
belaran@947: mais une ligne commence par ``\texttt{M}'' for \filename{hello.c}. À moins que
belaran@947: vous ne lui indiquiez de le faire, \hgcmd{status} n'affichera aucune sortie 
belaran@947: pour les fichiers qui n'ont pas été modifiés.
belaran@947: 
belaran@947: Le caractère ``\texttt{M}'' indique que Mercurial a remarqué que nous avions
belaran@947: modifié le fichier \filename{hello.c}. Nous n'avons pas besoin d'\emph{informer}
belaran@947: Mercurial que nous allons modifier un fichier avant de le faire, ou que nous 
belaran@947: venons de le modifier, il est capable de s'en rendre compte tout seul.
belaran@947: 
belaran@947: C'est pratique de savoir que nous avons modifié \filename{hello.c}, mais il
belaran@947: serait encore plus pratique de savoir ce que nous avons modifié exactement. Pour
belaran@947: cela, nous avons la commande  \hgcmd{diff}.
belaran@947: 
bos@91: \interaction{tour.diff}
bos@91: 
belaran@947: \section{Enregister les modifications dans un nouveau \textit{changeset}}
belaran@947: 
belaran@947: Nous pouvons modifier des fichiers, compiler et tester nos modifications,
Wilk@956: et utiliser les commandes \hgcmd{status} et \hgcmd{diff} pour voir les
huguesfrachon@950: modifications effectuées, jusqu'au moment où nous serons assez satisfaits
huguesfrachon@950: pour décider d'enregistrer notre travail dans un \textit{changeset}.
belaran@947: 
belaran@947: La commande \hgcmd{commit} vous laisse créer un nouveau \textit{changeset},
belaran@947: nous désignerons généralement cette opération par ``faire un commit'' ou
huguesfrachon@950: ``commiter''\footnote{NdT: De mon expérience, la plupart des francophones 
belaran@947: utilisent  régulièrement, à l'oral, cette expression, mais bien évidement
Wilk@956: il ne s'agit pas d'un terme de terminologie correcte, ni même français.}
belaran@947: 
belaran@947: \subsection{Définir le nom d'utilisateur}
belaran@947: 
huguesfrachon@950: Quand vous exécutez la commande \hgcmd{commit} pour la première fois, elle
huguesfrachon@950: n'est pas garantie de réussir. Mercurial enregistre votre nom et votre 
belaran@947: adresse avec chaque modification que vous effectuez, de manière à ce que
belaran@947: vous soyez capable (ou d'autres le soient) de savoir qui a fait quelle
belaran@947: modification. Mercurial essaye automatiquement de découvrir un nom 
huguesfrachon@950: d'utilisateur qui ait un minimum de sens pour effectuer l'opération
belaran@947: de \textit{commit} avec. Il va essayer chacune des méthodes suivantes,
belaran@947: dans l'ordre:
bos@174: \begin{enumerate}
belaran@947: \item Si vous spécifiez l'option \hgopt{commit}{-u} avec la commande 
belaran@947:   \hgcmd{commit}, suivi d'un nom d'utilisateur, ceci aura toujours la 
belaran@947:   priorité sur les autres méthodes ci dessous.
Wilk@956: \item Si vous avez défini une variable d'environnement \envar{HGUSER}, 
belaran@947:   c'est cette valeur qui est alors utilisée.
huguesfrachon@950: \item Si vous créez un fichier nommé \sfilename{.hgrc} dans votre 
belaran@947:    répertoire \textit{home}, avec une entrée \rcitem{ui}{username}, 
belaran@947:    c'est la valeur associée qui sera utilisée. Pour voir à quoi 
belaran@947:    ressemble le contenu de ce fichier regardez la 
Wilk@956:    section~\ref{sec:tour-basic:username} ci-dessous.
Wilk@956: \item Si vous avez défini une variable d'environnement \envar{EMAIL}
belaran@947:   celle ci sera utilisée ensuite.
belaran@947: \item Enfin, Mercurial interrogera votre système pour trouver votre
belaran@947:   nom d'utilisateur local ainsi que le nom de la machine hôte, et il 
belaran@951:   fabriquera un nom d'utilisateur à partir de ces données. Comme il arrive
belaran@947:   souvent que ce genre de noms soit totalement inutile, il vous 
belaran@947:   préviendra en affichant un message d'avertissement.
bos@174: \end{enumerate}
belaran@947: 
huguesfrachon@950: Si tous ces mécanismes échouent, Mercurial n'exécutera pas la commande,
belaran@947: affichant un message d'erreur. Dans ce cas, il ne vous laissera pas 
belaran@947: effectuer de \textit{commit} tant que vous n'aurez pas défini un nom
belaran@947: d'utilisateur.
belaran@947: 
belaran@947: Vous devriez penser à utiliser la variable d'environement \envar{HGUSER} 
belaran@947: et l'option \hgopt{commit}{-u} comme moyen pour \emph{changer le nom
Wilk@956: d'utilisateur} par défaut. Pour une utilisation normale, la manière la plus
Wilk@956: simple et robuste d'opérer est de créer un fichier \sfilename{.hgrc},
Wilk@956: voir ci-dessous pour les détails à ce sujet.
bos@102: 
huguesfrachon@950: \subsubsection{Créer un fichier de configuration pour Mercurial}
bos@174: \label{sec:tour-basic:username}
bos@102: 
Wilk@956: Pour définir un nom d'utilisateur, utilisez votre éditeur de texte favori
huguesfrachon@950: pour créer un fichier \sfilename{.hgrc} dans votre répertoire \textit{home}.
huguesfrachon@950: Mercurial va utiliser ce fichier pour retrouver votre configuration personnelle.
huguesfrachon@950: Le contenu initial devrait ressembler à ceci:
bos@102: \begin{codesample2}
bos@102:   # This is a Mercurial configuration file.
bos@102:   [ui]
bos@102:   username = Firstname Lastname <email.address@domain.net>
bos@102: \end{codesample2}
huguesfrachon@950: La ligne avec \texttt{[ui]} commence une \emph{section} du fichier de
huguesfrachon@950: configuration, ainsi la ligne ``\texttt{username = ...}'' signifie ``
huguesfrachon@950: définir la valeur de l'élément \texttt{username} dans la section 
huguesfrachon@950: \texttt{ui}''. Une section continue jusqu'à ce qu'une nouvelle 
huguesfrachon@950: commence, ou que la fin du fichier soit atteinte. Mercurial ignore
huguesfrachon@955: les lignes vides et traite tout texte situé à la suite d'un  
belaran@951: ``\texttt{\#}'' jusqu'à la fin de la ligne comme un commentaire.
belaran@951: 
belaran@951: \subsubsection{Choisir un nom d'utilisateur}
belaran@951: 
belaran@951: Vous pouvez utiliser n'importe quelle valeur pour votre \texttt{username},
belaran@951: car cette information est destinée à d'autres personnes et non à être
belaran@951: interprétée par Mercurial. La convention que la plupart des personnes
belaran@958: <<<<<<< local
belaran@951: suivent est d'utiliser leurs noms suivies de leurs adresses emails,
Wilk@956: comme montrée ci-dessus:
bos@102: 
bos@102: \begin{note}
belaran@951:   Le mécanisme interne du serveur \textit{web} intégré à Mercurial,
belaran@951:   masque les adresses emails, pour rendre plus difficile leurs
belaran@951:   récupérations par les outils utilisés par les \textit{spammmers}.
huguesfrachon@955:   Ceci réduit la probabilité que de recevoir encore plus de 
belaran@951:   \textit{spam} si vous vous publiez un dépôt sur internet.
bos@102: \end{note}
bos@102: 
belaran@951: \subsection{Rédiger un message de \textit{commit}}
belaran@951: 
Wilk@956: Lorsqu'on effectue une opération de \textit{commit}, Mercurial 
belaran@951: lance automatiquement un éditeur de texte pour permettre de saisir
belaran@951: un message qui décrira les modifications effectuées dans ce 
huguesfrachon@955: \textit{changeset}. Ce message est nommé le \emph{message de 
belaran@951: \textit{commit}}. Ce sera un enregistrement pour tout lecteur 
belaran@951: expliquant le pourquoi et le comment de vos modifications, et il sera
belaran@951: affiché par la commande \hgcmd{log}.
bos@91: \interaction{tour.commit}
bos@91: 
huguesfrachon@955: L'éditeur que la commande \hgcmd{commit} déclenche ne contiendra
belaran@951: qu'une ligne vide suivi d'un certain nombre de lignes commençant
belaran@951: par ``\texttt{HG:}''.
bos@91: \begin{codesample2}
bos@91:   \emph{empty line}
bos@91:   HG: changed hello.c
bos@91: \end{codesample2}
huguesfrachon@955: Mercurial ignore les lignes qui commencent avec ``\texttt{HG:}'', il 
belaran@951: ne les utilise que pour nous indiquer quels fichiers modifiés il se 
belaran@951: prépare à \textit{commiter}. Modifier ou effacer ces lignes n'a 
belaran@951: aucune conséquence sur l'opération de \textit{commit}.
belaran@951: 
Wilk@956: \subsection{Rédiger un message \textit{approprié}}
belaran@951: 
belaran@951: Comme \hgcmd{log} n'affiche que la première ligne du message de
belaran@951: \textit{commit} par défaut, il est souvent considéré comme une bonne
Wilk@956: pratique de rédiger des messages de \textit{commit} qui tiennent
belaran@951: sur une seule ligne. Voilà un exemple concret de message de 
belaran@951: \textit{commit} qui \emph{ne suit pas} cette directive, et qui a donc
belaran@951: un résumé peu lisible.
belaran@960: 
bos@91: \begin{codesample2}
bos@91:   changeset:   73:584af0e231be
bos@91:   user:        Censored Person <censored.person@example.org>
bos@91:   date:        Tue Sep 26 21:37:07 2006 -0700
bos@91:   summary:     include buildmeister/commondefs.   Add an exports and install
bos@91: \end{codesample2}
bos@91: 
huguesfrachon@955: A ce sujet, il faut noter qu'il n'existe pas de règle absolue dans ce 
belaran@951: domaine. Mercurial lui-même n'interprète pas les contenus des messages
belaran@951: de \textit{commit}, ainsi votre projet est libre de concevoir différentes
Wilk@956: politiques de mise en page des messages.
belaran@951: 
belaran@951: Ma préférence personnelle va au message court, mais informatif, qui offre
huguesfrachon@955: des précisions supplémentaires par rapport à ce que pourrait m'apprendre une commande
belaran@951: \hgcmdargs{log}{--patch}.
belaran@951: 
belaran@951: \subsection{Annuler un \textit{commit}}
belaran@951: 
belaran@951: Si, en rédigeant le message, vous décidez que finalement vous ne 
huguesfrachon@955: voulez pas effectuer ce \textit{commit}, il suffit de quitter simplement
belaran@951: l'éditeur sans sauver. Ceci n'aura aucune conséquence sur le dépôt ou
belaran@951: les fichiers de l'espace de travail.
belaran@951: 
Wilk@956: Si vous exécuter la commande \hgcmd{commit} sans aucun argument, elle
belaran@951: enregistre toutes les modifications que vous avez faites, comme le montre
huguesfrachon@955: les commandes \hgcmd{status} et \hgcmd{diff}.
belaran@951: 
belaran@951: \subsection{Admirer votre travail}
belaran@951: 
belaran@951: Une fois que votre \textit{commit} est terminé, vous pouvez utiliser
belaran@951: la commande \hgcmd{tip} pour afficher le \textit{changeset} que nous
belaran@951: venons de créer. Cette commande produit une sortie à l'écran qui est
huguesfrachon@955: identique à celle du \hgcmd{log}, mais qui n'affiche que la dernière
belaran@951: révision du dépôt.
bos@91: \interaction{tour.tip}
Wilk@956: On fait couramment référence à la dernière révision du dépôt comme
belaran@951: étant la révision \textit{tip}, ou plus simplement le \textit{tip}.
belaran@951: 
belaran@951: \section{Partager ses modifications}
belaran@951: 
belaran@951: Nous avons mentionné plus haut que les dépôts de Mercurial 
belaran@951: sont autosuffisants. Ce qui signifie que le \textit{changeset} 
belaran@951: que vous venez de créer existe seulement dans votre répertoire 
Wilk@956: \dirname{my-hello}. Étudions comment propager cette modification
belaran@951: dans d'autres dépôts.
belaran@951: 
belaran@951: \subsection{Récupérer les modifications d'autres dépôts}
bos@91: \label{sec:tour:pull}
bos@91: 
Wilk@956: Pour commencer, construisons un clone de notre dépôt \dirname{hello} 
belaran@951: qui ne contiendra pas le changement que nous venons d'effectuer. Nous
Wilk@956: l'appellerons notre dépôt temporaire \dirname{hello-pull}.
belaran@960: 
bos@91: \interaction{tour.clone-pull}
bos@91: 
belaran@951: Nous allons utiliser la commande \hgcmd{pull} pour apporter les 
belaran@951: modifications depuis \dirname{my-hello} dans \dirname{hello-pull}.
belaran@951: Néanmoins, récupérer aveuglement des modifications depuis un dépôt
Wilk@956: a quelque chose d'un peu effrayant. Mercurial propose donc une 
belaran@951: commande \hgcmd{incoming} qui permet de savoir quelles modifications
belaran@951: la commande \hgcmd{pull} \emph{pourrait} entraîner dans notre dépôt,
huguesfrachon@955: et ceci sans effectuer réellement de modification dessus.
bos@91: \interaction{tour.incoming}
huguesfrachon@955: (Bien évidement, quelqu'un pourrait ajouter des modifications
belaran@951: supplémentaires sur le dépôt que nous étudions avec \hgcmd{incoming},
belaran@951: avant que nous ayons effectué notre \hgcmd{pull}, avec comme 
belaran@951: triste conséquence que nous aurons récupéré des modifications que 
belaran@951: nous n'attendions pas.)
belaran@951: 
huguesfrachon@955: Apporter les modifications rapatriées dans un dépôt se résume donc
belaran@951: à exécuter la commande \hgcmd{pull}, et préciser depuis quel dépôt 
belaran@951: effectuer le \hgcmd{pull}.
bos@91: \interaction{tour.pull}
belaran@951: 
belaran@951: Comme vous le voyez avec une sortie avant et après de la commande
belaran@951: \hgcmd{tip}, nous avons réussi à récupérer aisément les modifications
huguesfrachon@955: dans notre dépôt. Il reste néanmoins quelque chose à faire avant de
belaran@951: placer ces modifications dans l'espace de travail.
belaran@951: 
belaran@951: \subsection{Mise à jour de l'espace de travail}
belaran@951: 
huguesfrachon@955: Nous avons jusqu'à maintenant grossièrement définie la relation 
belaran@951: entre un dépôt et un espace de travail. La commande \hgcmd{pull} que
huguesfrachon@955: nous avons exécutée dans la section~\ref{sec:tour:pull} a apporté
belaran@951: des modifications, que nous avons vérifiées, dans notre dépôt, mais
huguesfrachon@955: il n'y a aucune trace de ces modifications dans notre espace de travail.
belaran@951: En effet, \hgcmd{pull} ne touche pas (par défaut) à l'espace de 
belaran@951: travail. C'est la commande \hgcmd{update} qui s'en charge.
bos@91: \interaction{tour.update}
bos@91: 
huguesfrachon@955: Il peut sembler un peu étrange que la commande \hgcmd{pull} ne mette
belaran@951: pas à jour l'espace de travail automatiquement. Il y a en fait une
Wilk@956: très bonne raison à cela : vous pouvez utilisez la commande 
belaran@960: 
belaran@951: \hgcmd{update} pour mettre à jour votre espace de travail à l'état
belaran@951: dans lequel il était à \emph{n'importe quelle révision} de l'historique
belaran@951: du dépôt. Si vous aviez un espace de travail contenant une ancienne
belaran@951: révision---pour chercher l'origine d'un \textit{bug}, par exemple---et
belaran@951: que vous effectuiez un \hgcmd{pull} qui mettrait à jour automatiquement
belaran@951: votre espace de travail, vous ne seriez probablement pas très satisfait.
belaran@951: 
Wilk@956: Néanmoins, comme les opérations de \textit{pull} sont très souvent
belaran@951: suivies d'un \textit{update}, Mercurial vous permet de combiner les
huguesfrachon@955: deux aisément en passant l'option \hgopt{pull}{-u} à la commande
belaran@951: \hgcmd{pull}
bos@91: \begin{codesample2}
bos@91:   hg pull -u
bos@91: \end{codesample2}
belaran@951: 
belaran@951: Si vous étudiez de nouveau la sortie de la commande \hgcmd{pull} dans
huguesfrachon@955: la section~\ref{sec:tour:pull} quand nous l'avons exécutée sans l'option
huguesfrachon@955: \hgopt{pull}{-u}, vous pouvez constater qu'elle a affiché un rappel assez
huguesfrachon@955: utile : vous devez encore effectuer une opération pour mettre à jour
belaran@951: votre espace de travail:
belaran@960: 
bos@92: \begin{codesample2}
bos@92:   (run 'hg update' to get a working copy)
bos@92: \end{codesample2}
bos@91: 
Wilk@956: Pour découvrir sur quelle révision de l'espace de travail on est, utilisez
belaran@951: la commande \hgcmd{parents}. 
bos@91: \interaction{tour.parents}
belaran@951: Si vous regardez de nouveau le dessin~\ref{fig:tour-basic:history}, vous
belaran@958: <<<<<<< local
Wilk@956: verrez les flèches reliant entre eux les \textit{changeset}. Le nœud 
Wilk@956: d'où la flèche \emph{part} est dans chaque cas un parent, 
Wilk@956: et le nœud où la flèche \emph{arrive} est un enfant. 
belaran@960: 
belaran@951: L'espace de travail a un parent de la même manière, c'est ce \textit{changeset} 
belaran@951: que l'espace de travail contient à ce moment.
huguesfrachon@955: %%%TODO : difficile à comprendre : l'espace de travail a un parent, de la même manière, c'est ce changeset que l'espace...
belaran@951: 
belaran@951: Pour mettre à jour l'espace de travail d'une révision particulière, 
Wilk@956: indiquez un numéro de révision ou un \textit{changeset~ID} à la commande 
belaran@951: \hgcmd{update}.
bos@91: \interaction{tour.older}
belaran@951: Si vous ne précisez pas de manière explicite de numéro de révision
belaran@951: la commande \hgcmd{update} mettra à jour votre espace de travail avec
belaran@960: le contenu de la révsion \textit{tip}, comme montré dans l'exemple 
belaran@951: ci dessus lors du second appel à \hgcmd{update}.
belaran@951: 
belaran@951: \subsection{Transférer les modifications à un autre dépôt}
belaran@951: 
belaran@951: Mercurial vous laisse transférer les modifications à un autre
belaran@951: dépôt, depuis votre dépôt actuel. Comme dans l'exemple du 
Wilk@956: \hgcmd{pull} ci-dessus, nous allons créer un dépôt temporaire
belaran@951: vers lequel transférer\footnote{NdT: Les francophones disent souvent 
belaran@951: ``pousser'' tout simplement} nos modifications.
bos@92: \interaction{tour.clone-push}
belaran@951: La commande \hgcmd{outgoing} nous indique quels changements nous
huguesfrachon@955: allons transférer vers l'autre serveur ?
bos@92: \interaction{tour.outgoing}
belaran@951: Et la commande \hgcmd{push} effectue réellement le transfert.
bos@92: \interaction{tour.push}
belaran@951: Comme avec \hgcmd{pull}, la commande \hgcmd{push} ne met pas à jour
belaran@951: le répertoire de travail du dépôt dans lequel il transfère les 
belaran@951: modifications. (À l'inverse de \hgcmd{pull}, \hgcmd{push} ne fournit
belaran@951: pas d'option \texttt{-u} pour forcer la mise à jour de l'espace
belaran@951: de travail cible).
belaran@951: 
belaran@951: Qu'est ce qui se passe lorsque vous essayez de récupérer ou de transférer
belaran@951: vos modifications et que le dépôt cible a déjà reçu ces modifications ? 
belaran@951: Rien de bien excitant.
bos@92: \interaction{tour.push.nothing}
bos@92: 
belaran@951: \subsection{Partager ses modifications à travers le réseau}
belaran@951: 
huguesfrachon@955: Les commandes que nous avons étudiées dans les sections précédentes
huguesfrachon@955: ne sont pas limitées aux dépôt locaux. Chacune fonctionne de la même
belaran@951: manière à travers une connexion réseau, il suffit de lui passer une 
Wilk@956: URL à la place d'un chemin de fichier local.
belaran@951: 
bos@93: \interaction{tour.outgoing.net}
belaran@951: Dans cet exemple, nous allons voir quels changements nous pourrions
belaran@951: transférer vers le dépôt distant, mais le dépôt est, de manière tout
belaran@951: à fait compréhensible, pas configuré pour accepter des modifications
belaran@951: d'utilisateurs anonymes.
bos@93: \interaction{tour.push.net}
bos@93: 
bos@84: %%% Local Variables: 
bos@84: %%% mode: latex
bos@84: %%% TeX-master: "00book"
bos@84: %%% End: