
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
huguesfrachon@942: donner un ensemble d'instructions fixes 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
romain@931: en ligne de commande, sous les plus courantes des distributions. 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. 
belaran@943:               Pour l'installer, exécute 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
belaran@943:   faut compter un 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: 
romain@931: Lee Cantey publie un installeur de Mercurial pour Mac OS~X sur le site 
romain@931: \url{http://mercurial.berkwood.com}.  Ce paquetage fonctionne sur les 
huguesfrachon@942: architectures Intel-~et PowerPCC. Avant de vous en servir, vous devez
romain@931: installer une version Universel 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 
romain@931: Fink, utiliser \command{sudo fink install mercurial-py25}. Si vous avez 
romain@931: acPorts, \command{sudo port install mercurial}.
simon@313: 
bos@84: \subsection{Windows}
bos@84: 
romain@931: Lee Cantey publie aussi un installeur 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}
romain@931:   Le version de Windows de Mercurial ne convertie pas automatiquement
romain@931:   les retour chariot Windows et Unix. Si vous désirez partager votre
romain@931:   travail avec des utilisateurs Unix, vous devez faire un peu de configuration
romain@931:   supllé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 
romain@931: version ne sont pas réellement importante 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. 
romain@931: Si c'est le cas, exécuter 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
romain@931: 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: 
romain@931: \section{Travailler avec un dépot}
romain@931: 
romain@931: Avec Mercurial, tout se déroule au sein du \emph{dépot}\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: 
belaran@938: Il n'y a rien de particulièrement magique au sujet de ce dépot, c'est
belaran@938: simplement une arboresence sur votre système de fichiers que Mercurial
belaran@938: traite de manière spéciale. Si vous pouvez renommer ou effacer ce répertoire
belaran@938: à n'importe quel moment, en utilisant la ligne de commande ou votre
belaran@938: explorateur de fichiers.
belaran@938: 
belaran@938: \subsection{Faire une copie locale de votre dépot}
belaran@938: 
belaran@938: \emph{Copier} un dépôt est just 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
belaran@938: crée une copie identique d'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
belaran@938: contient sa propre copie privé des fichiers du projet et de leurs
belaran@938: historiques. 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: 
belaran@938: Ce que tout ceci signifie pour le moment est que nous sommes libre
belaran@938: d'expérimenter avec ce dépôt, confiant dans le fait qu'il s'agit d'un
belaran@938: ``bac à sable'' qui n'affectera personne d'autres.
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 
belaran@938: qu'il contient un répertoire nommée \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
belaran@938: seules propre à Mercurial. Tout les autres fichiers et répertoire dans 
belaran@938: le répertoire sont à vous, et vous pouvez faire ce que vous en voulez.
belaran@938: 
belaran@938: Pour introduire un peu de terminologie, le répertoire \dirname{.hg} est
belaran@938: un ``vrai'' dépôt, et tout les fichiers et les répertoires qui coexistent
belaran@938: avec lui, sont désigné sous le nom de \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
belaran@938: précise}\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 
belaran@938: qu'il contient un ensemble de mofications sur plusieurs fichiers.
belaran@938: 
belaran@938: La commande \hgcmd{log} affiche ainsi ces informations:
bos@88: \begin{itemize}
belaran@938: \item[\texttt{changeset}] Ce champ contient un nombre, séparé par une 
belaran@938:   virgule, d'une chaine hexadécimal. Il s'agit en effet d'\emph{identifiants}
belaran@938:   pour 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.
belaran@938: \item[\texttt{utilisateur}] L'identité de la personne qui a crée ce 
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}
belaran@938:   a été crée, ainsi que le \textit{timezone} dans laquelle il a été crée. %%%TODO: Translate 'timezone' properly
belaran@938:   (La date et l'heure sont locals à cette \textit{timezone}, ils indiquent
belaran@938:   donc quelle date et quelle il était pour la personne qui a crée ce 
belaran@938:   \textit{changeset}.)
belaran@938: \item[\texttt{résumé}] La première du message que le créateur a associée à
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: 
belaran@938: 
belaran@938: La figure~\ref{fig:tour-basic:history} fournit un 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}.}.
belaran@938: Nous reviendrons régulièrement à 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: 
belaran@938: \subsection{Changesets, révisions, et discuter avec les autres}
bos@97: 
belaran@939: Comme l'anglais est réputé pour un langage maladroit, et que l'informatique
belaran@939: est la source de bien des erreurs terminologique (pourquoi utiliser un
belaran@939: seul terme quand quatre feront l'affaire ?), la gestion de version a une
belaran@939: variété de mot et de phrases qui veulent dire la même chose. Si vous 
belaran@939: parlez à quelqu'un de l'historique de Mercurial à d'autres personnes, 
belaran@939: vous constaterez que souvent le mot ``\textit{changeset}'' est compressé 
belaran@939: en juste ``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
belaran@939: pour désigner un \emph{spécifique} \textit{spécifique} a une grande
belaran@939: importance. Rappelez vous que le \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 
belaran@939: 	permanent, et immutable } qui pourra toujours être associé à %%%TODO: Immutable ? Is this french ?
belaran@939: 	\textit{changeset} exacte 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
belaran@939: arrivés 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: 
belaran@939: Mercurial utilise les numéro de révision uniquement comme des raccourcis
belaran@939: pratique. Si vous devez disctuer d'un \textit{changeset} avec quelqu'un, 
belaran@939: our faire un enregistrement d'un \textit{changeset} pour une quelquonque
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
belaran@939: l'option \hgopt{log}{-r} (ou \hgopt{log}{--rev}). Vous pouvez utiser
belaran@939: le numéro de révision ou la séquence hexadécimal comme identifiant, et 
belaran@939: vous demandez 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}}
belaran@939: \footnote{NdT: Il n'est pas aisé de traduire ce terme, donc je le 
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}
belaran@939: Mercurial respecte aussi l'ordre dans lequel vous spécifier 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@946: Si le résumé affiché par \hgcmd{log} est utile si vous savez déjà ce                                                                   
belaran@946: que vous cherchez. Vous aurez probablement besoin de voir un description                                                               
belaran@946: complète du changement, ou une liste des fichiers modifiés. Si vous                                                                    
belaran@946: cherchez à déterminer si ce \textit{changeset} est bien celui que vous                                                                 
belaran@946: recherchez. L'option \hgopt{-v} de la commande \hgcmd{log} (ou                                                                         
belaran@946: \hgopt{--verbose}) vous donne des informations supplémentaires.
belaran@946: 
belaran@946: Si vous voulez voir à la fois la description et le contenu d'une                                                                       
belaran@946: modification, ajouter l'option \hgopt{log}{-p} (ou \hgopt{log}{--patch}).                                                              
belaran@946: Ceci affiche le contenu d'une modification comme un \emph{diff unifié}                                                                 
belaran@946: \footnote{NdT: \textit{unified diff}} (si vous n'avez jamais vu de diff                                                                
belaran@946: unifié avant, consulter la section~\ref{sec:mq:patch} pour rapide                                                                      
belaran@946: survol).
belaran@946: 
belaran@946: 
belaran@946: \section{Tout sur les options de commandes}
belaran@946: 
belaran@946: Avant d'aller plus loin sur le fonctionnement des commandes de Mercurial,
belaran@946: étudions un moment comment elles fonctionnent de manière générale, vous
belaran@946: trouverez ça probablement utile pour la suite de notre parcours.
belaran@946: 
belaran@946: Mercurial a une manière approche directe et cohérente pour interpréter
belaran@946: les options que vous passez aux commandes. Il suit une convention commune
belaran@946: à la plupart des systèmes Unix et Linux modernes.
belaran@946: 
bos@91: \begin{itemize}
bos@91: \item Every option has a long name.  For example, as we've already
bos@91:   seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
bos@91: \item Most options have short names, too.  Instead of
bos@91:   \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
bos@91:   some options don't have short names is that the options in question
bos@91:   are rarely used.)
bos@91: \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
bos@91:   while short options start with one (e.g.~\hgopt{log}{-r}).
bos@91: \item Option naming and usage is consistent across commands.  For
bos@91:   example, every command that lets you specify a changeset~ID or
bos@91:   revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
bos@91:   arguments.
bos@91: \end{itemize}
bos@91: In the examples throughout this book, I use short options instead of
bos@91: long.  This just reflects my own preference, so don't read anything
bos@91: significant into it.
bos@91: 
bos@91: Most commands that print output of some kind will print more output
bos@91: when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
bos@91: when passed \hggopt{-q} (or \hggopt{--quiet}).
bos@91: 
bos@91: \section{Making and reviewing changes}
bos@91: 
bos@91: Now that we have a grasp of viewing history in Mercurial, let's take a
bos@91: look at making some changes and examining them.
bos@91: 
bos@91: The first thing we'll do is isolate our experiment in a repository of
bos@91: its own.  We use the \hgcmd{clone} command, but we don't need to
bos@91: clone a copy of the remote repository.  Since we already have a copy
bos@91: of it locally, we can just clone that instead.  This is much faster
bos@91: than cloning over the network, and cloning a local repository uses
bos@91: less disk space in most cases, too.
bos@91: \interaction{tour.reclone}
bos@91: As an aside, it's often good practice to keep a ``pristine'' copy of a
bos@91: remote repository around, which you can then make temporary clones of
bos@91: to create sandboxes for each task you want to work on.  This lets you
bos@91: work on multiple tasks in parallel, each isolated from the others
bos@91: until it's complete and you're ready to integrate it back.  Because
bos@91: local clones are so cheap, there's almost no overhead to cloning and
bos@91: destroying repositories whenever you want.
bos@91: 
bos@91: In our \dirname{my-hello} repository, we have a file
bos@91: \filename{hello.c} that contains the classic ``hello, world'' program.
bos@91: Let's use the ancient and venerable \command{sed} command to edit this
bos@91: file so that it prints a second line of output.  (I'm only using
bos@91: \command{sed} to do this because it's easy to write a scripted example
bos@91: this way.  Since you're not under the same constraint, you probably
bos@91: won't want to use \command{sed}; simply use your preferred text editor to
bos@91: do the same thing.)
bos@91: \interaction{tour.sed}
bos@91: 
bos@91: Mercurial's \hgcmd{status} command will tell us what Mercurial knows
bos@91: about the files in the repository.
bos@91: \interaction{tour.status}
bos@91: The \hgcmd{status} command prints no output for some files, but a line
bos@91: starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
bos@91: it to, \hgcmd{status} will not print any output for files that have
bos@91: not been modified.  
bos@91: 
bos@91: The ``\texttt{M}'' indicates that Mercurial has noticed that we
bos@97: modified \filename{hello.c}.  We didn't need to \emph{inform}
bos@97: Mercurial that we were going to modify the file before we started, or
bos@97: that we had modified the file after we were done; it was able to
bos@97: figure this out itself.
bos@91: 
bos@91: It's a little bit helpful to know that we've modified
bos@91: \filename{hello.c}, but we might prefer to know exactly \emph{what}
bos@91: changes we've made to it.  To do this, we use the \hgcmd{diff}
bos@91: command.
bos@91: \interaction{tour.diff}
bos@91: 
bos@91: \section{Recording changes in a new changeset}
bos@91: 
bos@91: We can modify files, build and test our changes, and use
bos@91: \hgcmd{status} and \hgcmd{diff} to review our changes, until we're
bos@91: satisfied with what we've done and arrive at a natural stopping point
bos@91: where we want to record our work in a new changeset.
bos@91: 
bos@91: The \hgcmd{commit} command lets us create a new changeset; we'll
bos@91: usually refer to this as ``making a commit'' or ``committing''.  
bos@91: 
bos@102: \subsection{Setting up a username}
bos@102: 
bos@174: When you try to run \hgcmd{commit} for the first time, it is not
bos@174: guaranteed to succeed.  Mercurial records your name and address with
bos@174: each change that you commit, so that you and others will later be able
bos@174: to tell who made each change.  Mercurial tries to automatically figure
bos@174: out a sensible username to commit the change with.  It will attempt
bos@174: each of the following methods, in order:
bos@174: \begin{enumerate}
bos@174: \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
bos@174:   command on the command line, followed by a username, this is always
bos@174:   given the highest precedence.
bos@174: \item If you have set the \envar{HGUSER} environment variable, this is
bos@174:   checked next.
bos@174: \item If you create a file in your home directory called
bos@174:   \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
bos@174:   used next.  To see what the contents of this file should look like,
bos@174:   refer to section~\ref{sec:tour-basic:username} below.
bos@174: \item If you have set the \envar{EMAIL} environment variable, this
bos@174:   will be used next.
bos@174: \item Mercurial will query your system to find out your local user
bos@174:   name and host name, and construct a username from these components.
bos@174:   Since this often results in a username that is not very useful, it
bos@174:   will print a warning if it has to do this.
bos@174: \end{enumerate}
bos@174: If all of these mechanisms fail, Mercurial will fail, printing an
bos@174: error message.  In this case, it will not let you commit until you set
bos@174: up a username.
bos@174: 
bos@174: You should think of the \envar{HGUSER} environment variable and the
bos@174: \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
bos@174: \emph{override} Mercurial's default selection of username.  For normal
bos@174: use, the simplest and most robust way to set a username for yourself
bos@174: is by creating a \sfilename{.hgrc} file; see below for details.
bos@102: 
bos@102: \subsubsection{Creating a Mercurial configuration file}
bos@174: \label{sec:tour-basic:username}
bos@102: 
bos@102: To set a user name, use your favourite editor to create a file called
bos@102: \sfilename{.hgrc} in your home directory.  Mercurial will use this
bos@102: file to look up your personalised configuration settings.  The initial
bos@102: contents of your \sfilename{.hgrc} should look like this.
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}
bos@102: The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
bos@102: so you can read the ``\texttt{username = ...}'' line as meaning ``set
bos@102: the value of the \texttt{username} item in the \texttt{ui} section''.
bos@102: A section continues until a new section begins, or the end of the
bos@102: file.  Mercurial ignores empty lines and treats any text from
bos@102: ``\texttt{\#}'' to the end of a line as a comment.
bos@102: 
bos@102: \subsubsection{Choosing a user name}
bos@102: 
bos@102: You can use any text you like as the value of the \texttt{username}
bos@102: config item, since this information is for reading by other people,
bos@102: but for interpreting by Mercurial.  The convention that most people
bos@102: follow is to use their name and email address, as in the example
bos@102: above.
bos@102: 
bos@102: \begin{note}
bos@102:   Mercurial's built-in web server obfuscates email addresses, to make
bos@102:   it more difficult for the email harvesting tools that spammers use.
bos@102:   This reduces the likelihood that you'll start receiving more junk
bos@102:   email if you publish a Mercurial repository on the web.
bos@102: \end{note}
bos@102: 
bos@91: \subsection{Writing a commit message}
bos@91: 
bos@91: When we commit a change, Mercurial drops us into a text editor, to
bos@91: enter a message that will describe the modifications we've made in
bos@91: this changeset.  This is called the \emph{commit message}.  It will be
bos@91: a record for readers of what we did and why, and it will be printed by
bos@91: \hgcmd{log} after we've finished committing.
bos@91: \interaction{tour.commit}
bos@91: 
bos@91: The editor that the \hgcmd{commit} command drops us into will contain
bos@91: an empty line, followed by a number of lines starting with
bos@91: ``\texttt{HG:}''.
bos@91: \begin{codesample2}
bos@91:   \emph{empty line}
bos@91:   HG: changed hello.c
bos@91: \end{codesample2}
bos@91: Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
bos@91: them only to tell us which files it's recording changes to.  Modifying
bos@91: or deleting these lines has no effect.
bos@91: 
bos@91: \subsection{Writing a good commit message}
bos@91: 
bos@91: Since \hgcmd{log} only prints the first line of a commit message by
bos@91: default, it's best to write a commit message whose first line stands
bos@91: alone.  Here's a real example of a commit message that \emph{doesn't}
bos@91: follow this guideline, and hence has a summary that is not readable.
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: 
bos@91: As far as the remainder of the contents of the commit message are
bos@91: concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
bos@91: interpret or care about the contents of the commit message, though
bos@91: your project may have policies that dictate a certain kind of
bos@91: formatting.
bos@91: 
bos@91: My personal preference is for short, but informative, commit messages
bos@91: that tell me something that I can't figure out with a quick glance at
bos@91: the output of \hgcmdargs{log}{--patch}.
bos@91: 
bos@91: \subsection{Aborting a commit}
bos@91: 
bos@91: If you decide that you don't want to commit while in the middle of
bos@91: editing a commit message, simply exit from your editor without saving
bos@91: the file that it's editing.  This will cause nothing to happen to
bos@91: either the repository or the working directory.
bos@91: 
bos@91: If we run the \hgcmd{commit} command without any arguments, it records
bos@91: all of the changes we've made, as reported by \hgcmd{status} and
bos@91: \hgcmd{diff}.
bos@91: 
bos@102: \subsection{Admiring our new handiwork}
bos@91: 
bos@91: Once we've finished the commit, we can use the \hgcmd{tip} command to
bos@91: display the changeset we just created.  This command produces output
bos@91: that is identical to \hgcmd{log}, but it only displays the newest
bos@91: revision in the repository.
bos@91: \interaction{tour.tip}
bos@91: We refer to the newest revision in the repository as the tip revision,
bos@91: or simply the tip.
bos@91: 
bos@91: \section{Sharing changes}
bos@91: 
bos@91: We mentioned earlier that repositories in Mercurial are
bos@91: self-contained.  This means that the changeset we just created exists
bos@91: only in our \dirname{my-hello} repository.  Let's look at a few ways
bos@91: that we can propagate this change into other repositories.
bos@91: 
bos@91: \subsection{Pulling changes from another repository}
bos@91: \label{sec:tour:pull}
bos@91: 
bos@91: To get started, let's clone our original \dirname{hello} repository,
bos@91: which does not contain the change we just committed.  We'll call our
bos@91: temporary repository \dirname{hello-pull}.
bos@91: \interaction{tour.clone-pull}
bos@91: 
bos@91: We'll use the \hgcmd{pull} command to bring changes from
bos@91: \dirname{my-hello} into \dirname{hello-pull}.  However, blindly
bos@91: pulling unknown changes into a repository is a somewhat scary
bos@91: prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
bos@91: what changes the \hgcmd{pull} command \emph{would} pull into the
bos@91: repository, without actually pulling the changes in.
bos@91: \interaction{tour.incoming}
bos@91: (Of course, someone could cause more changesets to appear in the
bos@91: repository that we ran \hgcmd{incoming} in, before we get a chance to
bos@91: \hgcmd{pull} the changes, so that we could end up pulling changes that we
bos@91: didn't expect.)
bos@91: 
bos@91: Bringing changes into a repository is a simple matter of running the
bos@91: \hgcmd{pull} command, and telling it which repository to pull from.
bos@91: \interaction{tour.pull}
bos@91: As you can see from the before-and-after output of \hgcmd{tip}, we
bos@91: have successfully pulled changes into our repository.  There remains
bos@92: one step before we can see these changes in the working directory.
bos@92: 
bos@92: \subsection{Updating the working directory}
bos@92: 
bos@92: We have so far glossed over the relationship between a repository and
bos@91: its working directory.  The \hgcmd{pull} command that we ran in
bos@91: section~\ref{sec:tour:pull} brought changes into the repository, but
bos@91: if we check, there's no sign of those changes in the working
bos@91: directory.  This is because \hgcmd{pull} does not (by default) touch
bos@91: the working directory.  Instead, we use the \hgcmd{update} command to
bos@91: do this.
bos@91: \interaction{tour.update}
bos@91: 
bos@91: It might seem a bit strange that \hgcmd{pull} doesn't update the
bos@91: working directory automatically.  There's actually a good reason for
bos@91: this: you can use \hgcmd{update} to update the working directory to
bos@91: the state it was in at \emph{any revision} in the history of the
bos@91: repository.  If you had the working directory updated to an old
bos@91: revision---to hunt down the origin of a bug, say---and ran a
bos@91: \hgcmd{pull} which automatically updated the working directory to a
bos@91: new revision, you might not be terribly happy.
bos@91: 
bos@91: However, since pull-then-update is such a common thing to do,
bos@91: Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
bos@91: option to \hgcmd{pull}.
bos@91: \begin{codesample2}
bos@91:   hg pull -u
bos@91: \end{codesample2}
bos@92: If you look back at the output of \hgcmd{pull} in
bos@92: section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
bos@92: you can see that it printed a helpful reminder that we'd have to take
bos@92: an explicit step to update the working directory:
bos@92: \begin{codesample2}
bos@92:   (run 'hg update' to get a working copy)
bos@92: \end{codesample2}
bos@91: 
bos@91: To find out what revision the working directory is at, use the
bos@91: \hgcmd{parents} command.
bos@91: \interaction{tour.parents}
bos@101: If you look back at figure~\ref{fig:tour-basic:history}, you'll see
bos@101: arrows connecting each changeset.  The node that the arrow leads
bos@101: \emph{from} in each case is a parent, and the node that the arrow
bos@101: leads \emph{to} is its child.  The working directory has a parent in
bos@101: just the same way; this is the changeset that the working directory
bos@101: currently contains.
bos@101: 
bos@91: To update the working directory to a particular revision, give a
bos@91: revision number or changeset~ID to the \hgcmd{update} command.
bos@91: \interaction{tour.older}
bos@91: If you omit an explicit revision, \hgcmd{update} will update to the
bos@94: tip revision, as shown by the second call to \hgcmd{update} in the
bos@94: example above.
bos@91: 
bos@92: \subsection{Pushing changes to another repository}
bos@92: 
bos@92: Mercurial lets us push changes to another repository, from the
bos@92: repository we're currently visiting.  As with the example of
bos@92: \hgcmd{pull} above, we'll create a temporary repository to push our
bos@92: changes into.
bos@92: \interaction{tour.clone-push}
bos@92: The \hgcmd{outgoing} command tells us what changes would be pushed
bos@92: into another repository.
bos@92: \interaction{tour.outgoing}
bos@92: And the \hgcmd{push} command does the actual push.
bos@92: \interaction{tour.push}
bos@92: As with \hgcmd{pull}, the \hgcmd{push} command does not update the
bos@92: working directory in the repository that it's pushing changes into.
bos@92: (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
bos@92: option that updates the other repository's working directory.)
bos@92: 
bos@92: What happens if we try to pull or push changes and the receiving
bos@92: repository already has those changes?  Nothing too exciting.
bos@92: \interaction{tour.push.nothing}
bos@92: 
bos@93: \subsection{Sharing changes over a network}
bos@93: 
bos@93: The commands we have covered in the previous few sections are not
bos@93: limited to working with local repositories.  Each works in exactly the
bos@93: same fashion over a network connection; simply pass in a URL instead
bos@93: of a local path.
bos@93: \interaction{tour.outgoing.net}
bos@93: In this example, we can see what changes we could push to the remote
bos@93: repository, but the repository is understandably not set up to let
bos@93: anonymous users push to it.
bos@93: \interaction{tour.push.net}
bos@93: 
bos@84: %%% Local Variables: 
bos@84: %%% mode: latex
bos@84: %%% TeX-master: "00book"
bos@84: %%% End: 




