| rev |
line source |
|
romain@931
|
1 \chapter{Un rapide tour de Mercurial}
|
|
bos@95
|
2 \label{chap:tour-basic}
|
|
bos@84
|
3
|
|
romain@931
|
4 \section{Installer Mercurial sur votre système}
|
|
bos@84
|
5 \label{sec:tour:install}
|
|
bos@84
|
6
|
|
huguesfrachon@942
|
7 Des paquetages binaires de Mercurial sont disponibles pour la plupart
|
|
huguesfrachon@942
|
8 des systèmes d'exploitation, ce qui rend facile l'utilisation immédiate
|
|
huguesfrachon@942
|
9 de Mercurial sur votre ordinateur.
|
|
bos@85
|
10
|
|
bos@84
|
11 \subsection{Linux}
|
|
bos@84
|
12
|
|
romain@931
|
13 Parce que chaque distribution de Linux a ses propres outils de gestion
|
|
huguesfrachon@942
|
14 de paquets, politiques et rythmes de développements, il est difficile de
|
|
huguesfrachon@942
|
15 donner un ensemble d'instructions fixes pour installer les binaires de
|
|
romain@931
|
16 Mercurial. La version de Mercurial avec laquelle vous vous retrouverez
|
|
huguesfrachon@942
|
17 dépendra grandement de l'activité de la personne en charge du paquetage
|
|
romain@931
|
18 pour la distribution.
|
|
romain@931
|
19
|
|
huguesfrachon@942
|
20 Pour rester simple, je me concentrerai sur l'installation de Mercurial
|
|
romain@931
|
21 en ligne de commande, sous les plus courantes des distributions. La
|
|
romain@931
|
22 plupart des distributions fournissent des gestionnaires graphiques de
|
|
romain@931
|
23 paquetage qui vous permettront d'installer Mercurial en quelques clicks.
|
|
romain@931
|
24 Le paquetage devrait se nommer \textit{mercurial}.
|
|
bos@84
|
25
|
|
bos@85
|
26 \begin{itemize}
|
|
bos@85
|
27 \item[Debian]
|
|
bos@85
|
28 \begin{codesample4}
|
|
bos@85
|
29 apt-get install mercurial
|
|
bos@85
|
30 \end{codesample4}
|
|
bos@84
|
31
|
|
bos@85
|
32 \item[Fedora Core]
|
|
bos@85
|
33 \begin{codesample4}
|
|
bos@85
|
34 yum install mercurial
|
|
bos@85
|
35 \end{codesample4}
|
|
bos@84
|
36
|
|
bos@85
|
37 \item[Gentoo]
|
|
bos@85
|
38 \begin{codesample4}
|
|
bos@85
|
39 emerge mercurial
|
|
bos@85
|
40 \end{codesample4}
|
|
bos@84
|
41
|
|
bos@85
|
42 \item[OpenSUSE]
|
|
bos@85
|
43 \begin{codesample4}
|
|
bos@85
|
44 yum install mercurial
|
|
bos@85
|
45 \end{codesample4}
|
|
bos@84
|
46
|
|
belaran@943
|
47 \item[Ubuntu] Le paquetage de Mercurial d'Ubuntu est construit sur celui de Debian.
|
|
belaran@943
|
48 Pour l'installer, exécute simplement les commandes suivantes:
|
|
bos@262
|
49 \begin{codesample4}
|
|
bos@262
|
50 apt-get install mercurial
|
|
bos@262
|
51 \end{codesample4}
|
|
romain@931
|
52 Les paquetages Ubuntu pour Mercurial ont tendance à être un peu en retard
|
|
belaran@943
|
53 par rapport au paquetage Debian (au moment de l'écriture de ce livre, il
|
|
belaran@943
|
54 faut compter un peu près un retard de 7 mois), ce qui signifie que parfois
|
|
belaran@943
|
55 sur Ubuntu, vous risquez de rencontrer des problèmes qui ont été corrigés
|
|
belaran@943
|
56 depuis longtemps dans les paquetages Debian.
|
|
bos@85
|
57 \end{itemize}
|
|
bos@84
|
58
|
|
arne@264
|
59 \subsection{Solaris}
|
|
arne@264
|
60
|
|
romain@931
|
61 SunFreeWare, à \url{http://www.saufreeware.com}, est une bonne source
|
|
huguesfrachon@942
|
62 pour trouver un vaste nombre de paquets précompilés pour 32 ou 64 bits
|
|
romain@931
|
63 Intel et les architecture Sparc, dont les versions courantes de Mercurial.
|
|
arne@264
|
64
|
|
bos@84
|
65 \subsection{Mac OS X}
|
|
bos@84
|
66
|
|
romain@931
|
67 Lee Cantey publie un installeur de Mercurial pour Mac OS~X sur le site
|
|
romain@931
|
68 \url{http://mercurial.berkwood.com}. Ce paquetage fonctionne sur les
|
|
huguesfrachon@942
|
69 architectures Intel-~et PowerPCC. Avant de vous en servir, vous devez
|
|
romain@931
|
70 installer une version Universel MacPython~\cite{web:macpython}. C'est
|
|
romain@931
|
71 assez facile à faire : suivez simplement les instructions sur le site
|
|
romain@931
|
72 de Lee.
|
|
romain@931
|
73
|
|
romain@931
|
74 Il est aussi possible d'installer Mercurial en utilisant Fink ou MacPorts,
|
|
huguesfrachon@942
|
75 deux outils de gestion de paquetage libres pour Mac OS X. Si vous avez
|
|
romain@931
|
76 Fink, utiliser \command{sudo fink install mercurial-py25}. Si vous avez
|
|
romain@931
|
77 acPorts, \command{sudo port install mercurial}.
|
|
simon@313
|
78
|
|
bos@84
|
79 \subsection{Windows}
|
|
bos@84
|
80
|
|
romain@931
|
81 Lee Cantey publie aussi un installeur de Mercurial pour Windows sur le site
|
|
romain@931
|
82 \url{http://mercurial.berkwood.com}. Ce paquetage n'a aucune dépendance
|
|
romain@931
|
83 externe, il fonctionne ``tout court''.
|
|
bos@84
|
84
|
|
bos@84
|
85 \begin{note}
|
|
romain@931
|
86 Le version de Windows de Mercurial ne convertie pas automatiquement
|
|
romain@931
|
87 les retour chariot Windows et Unix. Si vous désirez partager votre
|
|
romain@931
|
88 travail avec des utilisateurs Unix, vous devez faire un peu de configuration
|
|
romain@931
|
89 supllémentaire. XXX En dire plus.
|
|
bos@84
|
90 \end{note}
|
|
bos@84
|
91
|
|
romain@931
|
92 \section{Commencer à utiliser Mercurial}
|
|
romain@931
|
93
|
|
romain@931
|
94 Pour commencer, nous utiliserons la commande \hgcmd{version} pour vérifier
|
|
romain@931
|
95 si Mercurial est installé proprement. Les informations affichées sur la
|
|
romain@931
|
96 version ne sont pas réellement importante en soit, c'est surtout de savoir
|
|
romain@931
|
97 si elles s'affichent qui nous intéresse.
|
|
bos@87
|
98 \interaction{tour.version}
|
|
bos@87
|
99
|
|
romain@931
|
100 \subsection{L'aide intégrée}
|
|
romain@931
|
101
|
|
romain@931
|
102 Mercurial fournit un système d'aide intégré, ce qui est inestimable quand
|
|
romain@931
|
103 vous vous retrouvez coincé à essayer de vous rappeler comment lancer telle
|
|
romain@931
|
104 ou telle commande.
|
|
romain@931
|
105 Si c'est le cas, exécuter simplement \hgcmd{help}; il vous aidera à imprimer
|
|
huguesfrachon@942
|
106 une brève liste de commandes, avec une description de ce qu'elles font. Si vous
|
|
romain@931
|
107 demandez de l'aide sur une commande spécifique (voir ci dessous), il affichera
|
|
huguesfrachon@942
|
108 des informations plus détaillées.
|
|
bos@87
|
109 \interaction{tour.help}
|
|
huguesfrachon@942
|
110 Pour un niveau d'informations encore plus détaillées (ce dont vous aurez rarement
|
|
huguesfrachon@942
|
111 besoin), exécuter \hgcmdargs{help}{\hggopt{-v}}. L'option \hggopt{-v} est
|
|
romain@931
|
112 l'abréviation de \hggopt{--verbose}, et indique à Mercurial d'afficher plus
|
|
huguesfrachon@942
|
113 d'informations que d'habitude.
|
|
romain@931
|
114
|
|
romain@931
|
115 \section{Travailler avec un dépot}
|
|
romain@931
|
116
|
|
romain@931
|
117 Avec Mercurial, tout se déroule au sein du \emph{dépot}\footnote{NdT: Dépôt est
|
|
huguesfrachon@942
|
118 la traduction que j'ai retenue pour tout l'ouvrage du terme anglais \textit{repository}}.
|
|
huguesfrachon@942
|
119 Le dépôt d'un projet contient tous les fichiers qui ``appartiennent'' au projet.
|
|
belaran@938
|
120
|
|
belaran@938
|
121 Il n'y a rien de particulièrement magique au sujet de ce dépot, c'est
|
|
belaran@938
|
122 simplement une arboresence sur votre système de fichiers que Mercurial
|
|
belaran@938
|
123 traite de manière spéciale. Si vous pouvez renommer ou effacer ce répertoire
|
|
belaran@938
|
124 à n'importe quel moment, en utilisant la ligne de commande ou votre
|
|
belaran@938
|
125 explorateur de fichiers.
|
|
belaran@938
|
126
|
|
belaran@938
|
127 \subsection{Faire une copie locale de votre dépot}
|
|
belaran@938
|
128
|
|
belaran@938
|
129 \emph{Copier} un dépôt est just un peu spécial. Bien que vous
|
|
belaran@938
|
130 puissiez utiliser une commande habituelle de copie pour copier
|
|
belaran@938
|
131 votre dépôt, il vaut mieux utiliser une commande fournie par
|
|
belaran@938
|
132 Mercurial. Cette commande est appelée \hgcmd{clone}, car elle
|
|
belaran@938
|
133 crée une copie identique d'un dépôt existant.
|
|
bos@87
|
134 \interaction{tour.clone}
|
|
belaran@938
|
135 Si votre opération de clonage réussit, vous devriez maintenant
|
|
belaran@938
|
136 avoir un répertoire local appelé \dirname{hello}. Ce répertoire
|
|
belaran@938
|
137 contiendra quelques fichiers.
|
|
bos@87
|
138 \interaction{tour.ls}
|
|
belaran@938
|
139 Ces fichiers ont le même contenu et historique dans votre dépôt
|
|
belaran@938
|
140 qu'ils ont dans le dépôt que vous avez cloné.
|
|
belaran@938
|
141
|
|
belaran@938
|
142 Chaque dépôt Mercurial est complet, autonome et indépendant. Il
|
|
belaran@938
|
143 contient sa propre copie privé des fichiers du projet et de leurs
|
|
belaran@938
|
144 historiques. Le clone d'un dépôt se souvient de la localisation du
|
|
belaran@938
|
145 dépôt à partir duquel il a été clôné, mais il ne communique pas avec
|
|
belaran@938
|
146 ce dernier, ou un autre, à moins que vous ne lui demandiez.
|
|
belaran@938
|
147
|
|
belaran@938
|
148 Ce que tout ceci signifie pour le moment est que nous sommes libre
|
|
belaran@938
|
149 d'expérimenter avec ce dépôt, confiant dans le fait qu'il s'agit d'un
|
|
belaran@938
|
150 ``bac à sable'' qui n'affectera personne d'autres.
|
|
belaran@938
|
151
|
|
belaran@938
|
152 \subsection{Quel est le contenu d'un dépôt ?}
|
|
belaran@938
|
153
|
|
belaran@938
|
154 Prêtons plus attention un instant au contenu d'un dépôt. Nous voyons
|
|
belaran@938
|
155 qu'il contient un répertoire nommée \dirname{.hg}. C'est ici que Mercurial
|
|
belaran@938
|
156 conserve toutes ses métadonnées.
|
|
bos@88
|
157 \interaction{tour.ls-a}
|
|
bos@88
|
158
|
|
belaran@938
|
159 Le contenu du répertoire \dirname{.hg} et ses sous répertoires sont les
|
|
belaran@938
|
160 seules propre à Mercurial. Tout les autres fichiers et répertoire dans
|
|
belaran@938
|
161 le répertoire sont à vous, et vous pouvez faire ce que vous en voulez.
|
|
belaran@938
|
162
|
|
belaran@938
|
163 Pour introduire un peu de terminologie, le répertoire \dirname{.hg} est
|
|
belaran@938
|
164 un ``vrai'' dépôt, et tout les fichiers et les répertoires qui coexistent
|
|
belaran@938
|
165 avec lui, sont désigné sous le nom de \emph{espace de travail}\footnote{NdT:
|
|
belaran@938
|
166 \textit{working directory}}. Une manière facile de se rappeler cette
|
|
belaran@938
|
167 distinction est de retenir que le \emph{dépôt} contient l'\emph{historique}
|
|
belaran@938
|
168 de votre projet, alors que l'\emph{espace de travail} contient une \emph{copie
|
|
belaran@938
|
169 précise}\footnote{NdT: Ce terme est une traduction du terme anglais
|
|
belaran@938
|
170 \textit{snapshot}. Il est traduit ici pour faciliter la lecture, mais ne sera
|
|
belaran@938
|
171 plus traduit par la suite.} de votre projet à un certain point de son
|
|
belaran@938
|
172 historique.
|
|
belaran@938
|
173
|
|
belaran@938
|
174 \section{Une ballade dans l'historique}
|
|
belaran@938
|
175
|
|
belaran@938
|
176 Une des premières choses que vous aurez envie de faire avec un nouveau
|
|
belaran@938
|
177 dépôt, sera de comprendre son historique. La commande \hgcmd{log} vous
|
|
belaran@938
|
178 donne une vue de l'historique.
|
|
bos@88
|
179 \interaction{tour.log}
|
|
belaran@938
|
180 Par défaut, cette commande affiche à l'écran un bref paragraphe pour chaque
|
|
belaran@938
|
181 révision enregistrée pour ce projet. Dans la terminologie de Mercurial, nous
|
|
belaran@938
|
182 appelons chacun de ces évènements enregistrés un \emph{changeset}, parce
|
|
belaran@938
|
183 qu'il contient un ensemble de mofications sur plusieurs fichiers.
|
|
belaran@938
|
184
|
|
belaran@938
|
185 La commande \hgcmd{log} affiche ainsi ces informations:
|
|
bos@88
|
186 \begin{itemize}
|
|
belaran@938
|
187 \item[\texttt{changeset}] Ce champ contient un nombre, séparé par une
|
|
belaran@938
|
188 virgule, d'une chaine hexadécimal. Il s'agit en effet d'\emph{identifiants}
|
|
belaran@938
|
189 pour un \textit{changeset}. Il y a deux identifiants car le numéro de
|
|
belaran@938
|
190 la révision est plus court et plus à facile à saisir qu'une séquence
|
|
belaran@938
|
191 hexadécimale.
|
|
belaran@938
|
192 \item[\texttt{utilisateur}] L'identité de la personne qui a crée ce
|
|
belaran@938
|
193 \textit{changeset}. C'est un champ libre de forme, mais la plupart du
|
|
belaran@938
|
194 temps il contient le nom et l'email de la personne.
|
|
belaran@938
|
195 \item[\texttt{date}] La date et l'heure à laquelle le \textit{changeset}
|
|
belaran@938
|
196 a été crée, ainsi que le \textit{timezone} dans laquelle il a été crée. %%%TODO: Translate 'timezone' properly
|
|
belaran@938
|
197 (La date et l'heure sont locals à cette \textit{timezone}, ils indiquent
|
|
belaran@938
|
198 donc quelle date et quelle il était pour la personne qui a crée ce
|
|
belaran@938
|
199 \textit{changeset}.)
|
|
belaran@938
|
200 \item[\texttt{résumé}] La première du message que le créateur a associée à
|
|
belaran@938
|
201 son \textit{changeset} pour le décrire.
|
|
bos@88
|
202 \end{itemize}
|
|
belaran@938
|
203
|
|
belaran@938
|
204 Par défaut, la commande \hgcmd{log} n'affiche qu'un résumé, il manque
|
|
belaran@938
|
205 beaucoup de détails.
|
|
belaran@938
|
206
|
|
belaran@938
|
207
|
|
belaran@938
|
208 La figure~\ref{fig:tour-basic:history} fournit un représentation graphique
|
|
belaran@938
|
209 de l'historique du dépôt \dirname{hello}, pour rendre plus facile de voir
|
|
belaran@938
|
210 dans quelle direction l'historique se ``déroule''\footnote{NdT: \textit{flowing in}.}.
|
|
belaran@938
|
211 Nous reviendrons régulièrement à cette représentation dans ce chapitre et
|
|
belaran@938
|
212 ceux qui suivent.
|
|
bos@97
|
213
|
|
bos@96
|
214 \begin{figure}[ht]
|
|
bos@96
|
215 \centering
|
|
bos@96
|
216 \grafix{tour-history}
|
|
belaran@938
|
217 \caption{Représentation graphique du dépôt \dirname{hello} }
|
|
bos@99
|
218 \label{fig:tour-basic:history}
|
|
bos@96
|
219 \end{figure}
|
|
bos@96
|
220
|
|
belaran@938
|
221 \subsection{Changesets, révisions, et discuter avec les autres}
|
|
bos@97
|
222
|
|
belaran@939
|
223 Comme l'anglais est réputé pour un langage maladroit, et que l'informatique
|
|
belaran@939
|
224 est la source de bien des erreurs terminologique (pourquoi utiliser un
|
|
belaran@939
|
225 seul terme quand quatre feront l'affaire ?), la gestion de version a une
|
|
belaran@939
|
226 variété de mot et de phrases qui veulent dire la même chose. Si vous
|
|
belaran@939
|
227 parlez à quelqu'un de l'historique de Mercurial à d'autres personnes,
|
|
belaran@939
|
228 vous constaterez que souvent le mot ``\textit{changeset}'' est compressé
|
|
belaran@939
|
229 en juste ``change'' ou (à l'écrit) ``cset'', et même parfois un
|
|
belaran@939
|
230 \textit{changeset} simplement ``révision'', abrégé en ``rev''.
|
|
belaran@939
|
231
|
|
belaran@939
|
232 Bien que le \emph{mot} que vous utilisez pour désigner le concept de
|
|
belaran@939
|
233 \textit{changeset} importe peu, l'\emph{identifiant} que vous utilisez
|
|
belaran@939
|
234 pour désigner un \emph{spécifique} \textit{spécifique} a une grande
|
|
belaran@939
|
235 importance. Rappelez vous que le \textit{changeset} affiché par la
|
|
belaran@939
|
236 commande \hgcmd{log} identifie un \textit{changeset} à la fois avec
|
|
belaran@939
|
237 un numéro de révision et une séquence hexadécimale.
|
|
belaran@939
|
238
|
|
bos@97
|
239 \begin{itemize}
|
|
belaran@939
|
240 \item Le numéro de révision est \emph{seulement valable dans ce dépôt},
|
|
belaran@939
|
241 \item alors que la séquence hexadécimale est un \emph{identifiant
|
|
belaran@939
|
242 permanent, et immutable } qui pourra toujours être associé à %%%TODO: Immutable ? Is this french ?
|
|
belaran@939
|
243 \textit{changeset} exacte de \emph{chaque} copie de votre dépôt.
|
|
bos@97
|
244 \end{itemize}
|
|
belaran@939
|
245
|
|
belaran@939
|
246 La distinction est importante. Si vous envoyez un email à quelqu'un en
|
|
belaran@939
|
247 parlant de la ``révision 33'', il est très probable que sa révision~33
|
|
belaran@939
|
248 \emph{ne sera pas la même} que la votre. La raison de ceci est que le
|
|
belaran@939
|
249 numéro de révision dépend de l'ordre dans lequel les modifications sont
|
|
belaran@939
|
250 arrivés dans le dépôt, et il n'y a aucune garantie que les mêmes changements
|
|
belaran@939
|
251 soient arrivés dans le même ordre dans différents dépôts. Trois modifications
|
|
belaran@939
|
252 $a,b,c$ peuvent aisément apparaitre dans un dépôt comme $0,1,2$, et dans
|
|
belaran@939
|
253 un autre comme $1,0,2$.
|
|
belaran@939
|
254
|
|
belaran@939
|
255 Mercurial utilise les numéro de révision uniquement comme des raccourcis
|
|
belaran@939
|
256 pratique. Si vous devez disctuer d'un \textit{changeset} avec quelqu'un,
|
|
belaran@939
|
257 our faire un enregistrement d'un \textit{changeset} pour une quelquonque
|
|
belaran@939
|
258 raison (par exemple, un rapport de \textit{bug}), utilisez la séquence
|
|
belaran@939
|
259 hexadécimale.
|
|
belaran@939
|
260
|
|
belaran@939
|
261 \subsection{Afficher une révision spécifique}
|
|
belaran@939
|
262
|
|
belaran@939
|
263 Pour réduire la sortie de \hgcmd{log} à une seule révision, utilisez
|
|
belaran@939
|
264 l'option \hgopt{log}{-r} (ou \hgopt{log}{--rev}). Vous pouvez utiser
|
|
belaran@939
|
265 le numéro de révision ou la séquence hexadécimal comme identifiant, et
|
|
belaran@939
|
266 vous demandez autant de révisions que vous le souhaitez.
|
|
belaran@939
|
267 \interaction{tour.log-r}
|
|
belaran@939
|
268
|
|
belaran@939
|
269 Si vous voulez voir l'historique de plusieurs révisions sans avoir à
|
|
belaran@939
|
270 les énumérer, vous pouvez utiliser la \emph{\textit{range notation}}
|
|
belaran@939
|
271 \footnote{NdT: Il n'est pas aisé de traduire ce terme, donc je le
|
|
belaran@939
|
272 laisse en anglais} qui vous permet d'exprimer l'idée ``je veux toutes
|
|
belaran@939
|
273 les révisions entre $a$ et $b$, inclus''.
|
|
bos@88
|
274 \interaction{tour.log.range}
|
|
belaran@939
|
275 Mercurial respecte aussi l'ordre dans lequel vous spécifier les
|
|
belaran@939
|
276 révisions, ainsi \hgcmdargs{log}{-r 2:4} affichera $2,3,4$ alors que
|
|
belaran@939
|
277 \hgcmdargs{log}{-r 4:2} affichera $4,3,2$.
|
|
belaran@939
|
278
|
|
belaran@939
|
279 \subsection{Informations détaillées}
|
|
bos@91
|
280
|
|
belaran@946
|
281 Si le résumé affiché par \hgcmd{log} est utile si vous savez déjà ce
|
|
belaran@946
|
282 que vous cherchez. Vous aurez probablement besoin de voir un description
|
|
belaran@946
|
283 complète du changement, ou une liste des fichiers modifiés. Si vous
|
|
belaran@946
|
284 cherchez à déterminer si ce \textit{changeset} est bien celui que vous
|
|
belaran@946
|
285 recherchez. L'option \hgopt{-v} de la commande \hgcmd{log} (ou
|
|
belaran@946
|
286 \hgopt{--verbose}) vous donne des informations supplémentaires.
|
|
belaran@946
|
287
|
|
belaran@946
|
288 Si vous voulez voir à la fois la description et le contenu d'une
|
|
belaran@946
|
289 modification, ajouter l'option \hgopt{log}{-p} (ou \hgopt{log}{--patch}).
|
|
belaran@946
|
290 Ceci affiche le contenu d'une modification comme un \emph{diff unifié}
|
|
belaran@946
|
291 \footnote{NdT: \textit{unified diff}} (si vous n'avez jamais vu de diff
|
|
belaran@946
|
292 unifié avant, consulter la section~\ref{sec:mq:patch} pour rapide
|
|
belaran@946
|
293 survol).
|
|
belaran@946
|
294
|
|
belaran@946
|
295
|
|
belaran@946
|
296 \section{Tout sur les options de commandes}
|
|
belaran@946
|
297
|
|
belaran@946
|
298 Avant d'aller plus loin sur le fonctionnement des commandes de Mercurial,
|
|
belaran@946
|
299 étudions un moment comment elles fonctionnent de manière générale, vous
|
|
belaran@946
|
300 trouverez ça probablement utile pour la suite de notre parcours.
|
|
belaran@946
|
301
|
|
belaran@946
|
302 Mercurial a une manière approche directe et cohérente pour interpréter
|
|
belaran@946
|
303 les options que vous passez aux commandes. Il suit une convention commune
|
|
belaran@946
|
304 à la plupart des systèmes Unix et Linux modernes.
|
|
belaran@946
|
305
|
|
bos@91
|
306 \begin{itemize}
|
|
bos@91
|
307 \item Every option has a long name. For example, as we've already
|
|
bos@91
|
308 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
|
|
bos@91
|
309 \item Most options have short names, too. Instead of
|
|
bos@91
|
310 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that
|
|
bos@91
|
311 some options don't have short names is that the options in question
|
|
bos@91
|
312 are rarely used.)
|
|
bos@91
|
313 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
|
|
bos@91
|
314 while short options start with one (e.g.~\hgopt{log}{-r}).
|
|
bos@91
|
315 \item Option naming and usage is consistent across commands. For
|
|
bos@91
|
316 example, every command that lets you specify a changeset~ID or
|
|
bos@91
|
317 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
|
|
bos@91
|
318 arguments.
|
|
bos@91
|
319 \end{itemize}
|
|
bos@91
|
320 In the examples throughout this book, I use short options instead of
|
|
bos@91
|
321 long. This just reflects my own preference, so don't read anything
|
|
bos@91
|
322 significant into it.
|
|
bos@91
|
323
|
|
bos@91
|
324 Most commands that print output of some kind will print more output
|
|
bos@91
|
325 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
|
|
bos@91
|
326 when passed \hggopt{-q} (or \hggopt{--quiet}).
|
|
bos@91
|
327
|
|
bos@91
|
328 \section{Making and reviewing changes}
|
|
bos@91
|
329
|
|
bos@91
|
330 Now that we have a grasp of viewing history in Mercurial, let's take a
|
|
bos@91
|
331 look at making some changes and examining them.
|
|
bos@91
|
332
|
|
bos@91
|
333 The first thing we'll do is isolate our experiment in a repository of
|
|
bos@91
|
334 its own. We use the \hgcmd{clone} command, but we don't need to
|
|
bos@91
|
335 clone a copy of the remote repository. Since we already have a copy
|
|
bos@91
|
336 of it locally, we can just clone that instead. This is much faster
|
|
bos@91
|
337 than cloning over the network, and cloning a local repository uses
|
|
bos@91
|
338 less disk space in most cases, too.
|
|
bos@91
|
339 \interaction{tour.reclone}
|
|
bos@91
|
340 As an aside, it's often good practice to keep a ``pristine'' copy of a
|
|
bos@91
|
341 remote repository around, which you can then make temporary clones of
|
|
bos@91
|
342 to create sandboxes for each task you want to work on. This lets you
|
|
bos@91
|
343 work on multiple tasks in parallel, each isolated from the others
|
|
bos@91
|
344 until it's complete and you're ready to integrate it back. Because
|
|
bos@91
|
345 local clones are so cheap, there's almost no overhead to cloning and
|
|
bos@91
|
346 destroying repositories whenever you want.
|
|
bos@91
|
347
|
|
bos@91
|
348 In our \dirname{my-hello} repository, we have a file
|
|
bos@91
|
349 \filename{hello.c} that contains the classic ``hello, world'' program.
|
|
bos@91
|
350 Let's use the ancient and venerable \command{sed} command to edit this
|
|
bos@91
|
351 file so that it prints a second line of output. (I'm only using
|
|
bos@91
|
352 \command{sed} to do this because it's easy to write a scripted example
|
|
bos@91
|
353 this way. Since you're not under the same constraint, you probably
|
|
bos@91
|
354 won't want to use \command{sed}; simply use your preferred text editor to
|
|
bos@91
|
355 do the same thing.)
|
|
bos@91
|
356 \interaction{tour.sed}
|
|
bos@91
|
357
|
|
bos@91
|
358 Mercurial's \hgcmd{status} command will tell us what Mercurial knows
|
|
bos@91
|
359 about the files in the repository.
|
|
bos@91
|
360 \interaction{tour.status}
|
|
bos@91
|
361 The \hgcmd{status} command prints no output for some files, but a line
|
|
bos@91
|
362 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell
|
|
bos@91
|
363 it to, \hgcmd{status} will not print any output for files that have
|
|
bos@91
|
364 not been modified.
|
|
bos@91
|
365
|
|
bos@91
|
366 The ``\texttt{M}'' indicates that Mercurial has noticed that we
|
|
bos@97
|
367 modified \filename{hello.c}. We didn't need to \emph{inform}
|
|
bos@97
|
368 Mercurial that we were going to modify the file before we started, or
|
|
bos@97
|
369 that we had modified the file after we were done; it was able to
|
|
bos@97
|
370 figure this out itself.
|
|
bos@91
|
371
|
|
bos@91
|
372 It's a little bit helpful to know that we've modified
|
|
bos@91
|
373 \filename{hello.c}, but we might prefer to know exactly \emph{what}
|
|
bos@91
|
374 changes we've made to it. To do this, we use the \hgcmd{diff}
|
|
bos@91
|
375 command.
|
|
bos@91
|
376 \interaction{tour.diff}
|
|
bos@91
|
377
|
|
bos@91
|
378 \section{Recording changes in a new changeset}
|
|
bos@91
|
379
|
|
bos@91
|
380 We can modify files, build and test our changes, and use
|
|
bos@91
|
381 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're
|
|
bos@91
|
382 satisfied with what we've done and arrive at a natural stopping point
|
|
bos@91
|
383 where we want to record our work in a new changeset.
|
|
bos@91
|
384
|
|
bos@91
|
385 The \hgcmd{commit} command lets us create a new changeset; we'll
|
|
bos@91
|
386 usually refer to this as ``making a commit'' or ``committing''.
|
|
bos@91
|
387
|
|
bos@102
|
388 \subsection{Setting up a username}
|
|
bos@102
|
389
|
|
bos@174
|
390 When you try to run \hgcmd{commit} for the first time, it is not
|
|
bos@174
|
391 guaranteed to succeed. Mercurial records your name and address with
|
|
bos@174
|
392 each change that you commit, so that you and others will later be able
|
|
bos@174
|
393 to tell who made each change. Mercurial tries to automatically figure
|
|
bos@174
|
394 out a sensible username to commit the change with. It will attempt
|
|
bos@174
|
395 each of the following methods, in order:
|
|
bos@174
|
396 \begin{enumerate}
|
|
bos@174
|
397 \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
|
|
bos@174
|
398 command on the command line, followed by a username, this is always
|
|
bos@174
|
399 given the highest precedence.
|
|
bos@174
|
400 \item If you have set the \envar{HGUSER} environment variable, this is
|
|
bos@174
|
401 checked next.
|
|
bos@174
|
402 \item If you create a file in your home directory called
|
|
bos@174
|
403 \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
|
|
bos@174
|
404 used next. To see what the contents of this file should look like,
|
|
bos@174
|
405 refer to section~\ref{sec:tour-basic:username} below.
|
|
bos@174
|
406 \item If you have set the \envar{EMAIL} environment variable, this
|
|
bos@174
|
407 will be used next.
|
|
bos@174
|
408 \item Mercurial will query your system to find out your local user
|
|
bos@174
|
409 name and host name, and construct a username from these components.
|
|
bos@174
|
410 Since this often results in a username that is not very useful, it
|
|
bos@174
|
411 will print a warning if it has to do this.
|
|
bos@174
|
412 \end{enumerate}
|
|
bos@174
|
413 If all of these mechanisms fail, Mercurial will fail, printing an
|
|
bos@174
|
414 error message. In this case, it will not let you commit until you set
|
|
bos@174
|
415 up a username.
|
|
bos@174
|
416
|
|
bos@174
|
417 You should think of the \envar{HGUSER} environment variable and the
|
|
bos@174
|
418 \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
|
|
bos@174
|
419 \emph{override} Mercurial's default selection of username. For normal
|
|
bos@174
|
420 use, the simplest and most robust way to set a username for yourself
|
|
bos@174
|
421 is by creating a \sfilename{.hgrc} file; see below for details.
|
|
bos@102
|
422
|
|
bos@102
|
423 \subsubsection{Creating a Mercurial configuration file}
|
|
bos@174
|
424 \label{sec:tour-basic:username}
|
|
bos@102
|
425
|
|
bos@102
|
426 To set a user name, use your favourite editor to create a file called
|
|
bos@102
|
427 \sfilename{.hgrc} in your home directory. Mercurial will use this
|
|
bos@102
|
428 file to look up your personalised configuration settings. The initial
|
|
bos@102
|
429 contents of your \sfilename{.hgrc} should look like this.
|
|
bos@102
|
430 \begin{codesample2}
|
|
bos@102
|
431 # This is a Mercurial configuration file.
|
|
bos@102
|
432 [ui]
|
|
bos@102
|
433 username = Firstname Lastname <email.address@domain.net>
|
|
bos@102
|
434 \end{codesample2}
|
|
bos@102
|
435 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
|
|
bos@102
|
436 so you can read the ``\texttt{username = ...}'' line as meaning ``set
|
|
bos@102
|
437 the value of the \texttt{username} item in the \texttt{ui} section''.
|
|
bos@102
|
438 A section continues until a new section begins, or the end of the
|
|
bos@102
|
439 file. Mercurial ignores empty lines and treats any text from
|
|
bos@102
|
440 ``\texttt{\#}'' to the end of a line as a comment.
|
|
bos@102
|
441
|
|
bos@102
|
442 \subsubsection{Choosing a user name}
|
|
bos@102
|
443
|
|
bos@102
|
444 You can use any text you like as the value of the \texttt{username}
|
|
bos@102
|
445 config item, since this information is for reading by other people,
|
|
bos@102
|
446 but for interpreting by Mercurial. The convention that most people
|
|
bos@102
|
447 follow is to use their name and email address, as in the example
|
|
bos@102
|
448 above.
|
|
bos@102
|
449
|
|
bos@102
|
450 \begin{note}
|
|
bos@102
|
451 Mercurial's built-in web server obfuscates email addresses, to make
|
|
bos@102
|
452 it more difficult for the email harvesting tools that spammers use.
|
|
bos@102
|
453 This reduces the likelihood that you'll start receiving more junk
|
|
bos@102
|
454 email if you publish a Mercurial repository on the web.
|
|
bos@102
|
455 \end{note}
|
|
bos@102
|
456
|
|
bos@91
|
457 \subsection{Writing a commit message}
|
|
bos@91
|
458
|
|
bos@91
|
459 When we commit a change, Mercurial drops us into a text editor, to
|
|
bos@91
|
460 enter a message that will describe the modifications we've made in
|
|
bos@91
|
461 this changeset. This is called the \emph{commit message}. It will be
|
|
bos@91
|
462 a record for readers of what we did and why, and it will be printed by
|
|
bos@91
|
463 \hgcmd{log} after we've finished committing.
|
|
bos@91
|
464 \interaction{tour.commit}
|
|
bos@91
|
465
|
|
bos@91
|
466 The editor that the \hgcmd{commit} command drops us into will contain
|
|
bos@91
|
467 an empty line, followed by a number of lines starting with
|
|
bos@91
|
468 ``\texttt{HG:}''.
|
|
bos@91
|
469 \begin{codesample2}
|
|
bos@91
|
470 \emph{empty line}
|
|
bos@91
|
471 HG: changed hello.c
|
|
bos@91
|
472 \end{codesample2}
|
|
bos@91
|
473 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
|
|
bos@91
|
474 them only to tell us which files it's recording changes to. Modifying
|
|
bos@91
|
475 or deleting these lines has no effect.
|
|
bos@91
|
476
|
|
bos@91
|
477 \subsection{Writing a good commit message}
|
|
bos@91
|
478
|
|
bos@91
|
479 Since \hgcmd{log} only prints the first line of a commit message by
|
|
bos@91
|
480 default, it's best to write a commit message whose first line stands
|
|
bos@91
|
481 alone. Here's a real example of a commit message that \emph{doesn't}
|
|
bos@91
|
482 follow this guideline, and hence has a summary that is not readable.
|
|
bos@91
|
483 \begin{codesample2}
|
|
bos@91
|
484 changeset: 73:584af0e231be
|
|
bos@91
|
485 user: Censored Person <censored.person@example.org>
|
|
bos@91
|
486 date: Tue Sep 26 21:37:07 2006 -0700
|
|
bos@91
|
487 summary: include buildmeister/commondefs. Add an exports and install
|
|
bos@91
|
488 \end{codesample2}
|
|
bos@91
|
489
|
|
bos@91
|
490 As far as the remainder of the contents of the commit message are
|
|
bos@91
|
491 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
|
|
bos@91
|
492 interpret or care about the contents of the commit message, though
|
|
bos@91
|
493 your project may have policies that dictate a certain kind of
|
|
bos@91
|
494 formatting.
|
|
bos@91
|
495
|
|
bos@91
|
496 My personal preference is for short, but informative, commit messages
|
|
bos@91
|
497 that tell me something that I can't figure out with a quick glance at
|
|
bos@91
|
498 the output of \hgcmdargs{log}{--patch}.
|
|
bos@91
|
499
|
|
bos@91
|
500 \subsection{Aborting a commit}
|
|
bos@91
|
501
|
|
bos@91
|
502 If you decide that you don't want to commit while in the middle of
|
|
bos@91
|
503 editing a commit message, simply exit from your editor without saving
|
|
bos@91
|
504 the file that it's editing. This will cause nothing to happen to
|
|
bos@91
|
505 either the repository or the working directory.
|
|
bos@91
|
506
|
|
bos@91
|
507 If we run the \hgcmd{commit} command without any arguments, it records
|
|
bos@91
|
508 all of the changes we've made, as reported by \hgcmd{status} and
|
|
bos@91
|
509 \hgcmd{diff}.
|
|
bos@91
|
510
|
|
bos@102
|
511 \subsection{Admiring our new handiwork}
|
|
bos@91
|
512
|
|
bos@91
|
513 Once we've finished the commit, we can use the \hgcmd{tip} command to
|
|
bos@91
|
514 display the changeset we just created. This command produces output
|
|
bos@91
|
515 that is identical to \hgcmd{log}, but it only displays the newest
|
|
bos@91
|
516 revision in the repository.
|
|
bos@91
|
517 \interaction{tour.tip}
|
|
bos@91
|
518 We refer to the newest revision in the repository as the tip revision,
|
|
bos@91
|
519 or simply the tip.
|
|
bos@91
|
520
|
|
bos@91
|
521 \section{Sharing changes}
|
|
bos@91
|
522
|
|
bos@91
|
523 We mentioned earlier that repositories in Mercurial are
|
|
bos@91
|
524 self-contained. This means that the changeset we just created exists
|
|
bos@91
|
525 only in our \dirname{my-hello} repository. Let's look at a few ways
|
|
bos@91
|
526 that we can propagate this change into other repositories.
|
|
bos@91
|
527
|
|
bos@91
|
528 \subsection{Pulling changes from another repository}
|
|
bos@91
|
529 \label{sec:tour:pull}
|
|
bos@91
|
530
|
|
bos@91
|
531 To get started, let's clone our original \dirname{hello} repository,
|
|
bos@91
|
532 which does not contain the change we just committed. We'll call our
|
|
bos@91
|
533 temporary repository \dirname{hello-pull}.
|
|
bos@91
|
534 \interaction{tour.clone-pull}
|
|
bos@91
|
535
|
|
bos@91
|
536 We'll use the \hgcmd{pull} command to bring changes from
|
|
bos@91
|
537 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
|
|
bos@91
|
538 pulling unknown changes into a repository is a somewhat scary
|
|
bos@91
|
539 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
|
|
bos@91
|
540 what changes the \hgcmd{pull} command \emph{would} pull into the
|
|
bos@91
|
541 repository, without actually pulling the changes in.
|
|
bos@91
|
542 \interaction{tour.incoming}
|
|
bos@91
|
543 (Of course, someone could cause more changesets to appear in the
|
|
bos@91
|
544 repository that we ran \hgcmd{incoming} in, before we get a chance to
|
|
bos@91
|
545 \hgcmd{pull} the changes, so that we could end up pulling changes that we
|
|
bos@91
|
546 didn't expect.)
|
|
bos@91
|
547
|
|
bos@91
|
548 Bringing changes into a repository is a simple matter of running the
|
|
bos@91
|
549 \hgcmd{pull} command, and telling it which repository to pull from.
|
|
bos@91
|
550 \interaction{tour.pull}
|
|
bos@91
|
551 As you can see from the before-and-after output of \hgcmd{tip}, we
|
|
bos@91
|
552 have successfully pulled changes into our repository. There remains
|
|
bos@92
|
553 one step before we can see these changes in the working directory.
|
|
bos@92
|
554
|
|
bos@92
|
555 \subsection{Updating the working directory}
|
|
bos@92
|
556
|
|
bos@92
|
557 We have so far glossed over the relationship between a repository and
|
|
bos@91
|
558 its working directory. The \hgcmd{pull} command that we ran in
|
|
bos@91
|
559 section~\ref{sec:tour:pull} brought changes into the repository, but
|
|
bos@91
|
560 if we check, there's no sign of those changes in the working
|
|
bos@91
|
561 directory. This is because \hgcmd{pull} does not (by default) touch
|
|
bos@91
|
562 the working directory. Instead, we use the \hgcmd{update} command to
|
|
bos@91
|
563 do this.
|
|
bos@91
|
564 \interaction{tour.update}
|
|
bos@91
|
565
|
|
bos@91
|
566 It might seem a bit strange that \hgcmd{pull} doesn't update the
|
|
bos@91
|
567 working directory automatically. There's actually a good reason for
|
|
bos@91
|
568 this: you can use \hgcmd{update} to update the working directory to
|
|
bos@91
|
569 the state it was in at \emph{any revision} in the history of the
|
|
bos@91
|
570 repository. If you had the working directory updated to an old
|
|
bos@91
|
571 revision---to hunt down the origin of a bug, say---and ran a
|
|
bos@91
|
572 \hgcmd{pull} which automatically updated the working directory to a
|
|
bos@91
|
573 new revision, you might not be terribly happy.
|
|
bos@91
|
574
|
|
bos@91
|
575 However, since pull-then-update is such a common thing to do,
|
|
bos@91
|
576 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
|
|
bos@91
|
577 option to \hgcmd{pull}.
|
|
bos@91
|
578 \begin{codesample2}
|
|
bos@91
|
579 hg pull -u
|
|
bos@91
|
580 \end{codesample2}
|
|
bos@92
|
581 If you look back at the output of \hgcmd{pull} in
|
|
bos@92
|
582 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
|
|
bos@92
|
583 you can see that it printed a helpful reminder that we'd have to take
|
|
bos@92
|
584 an explicit step to update the working directory:
|
|
bos@92
|
585 \begin{codesample2}
|
|
bos@92
|
586 (run 'hg update' to get a working copy)
|
|
bos@92
|
587 \end{codesample2}
|
|
bos@91
|
588
|
|
bos@91
|
589 To find out what revision the working directory is at, use the
|
|
bos@91
|
590 \hgcmd{parents} command.
|
|
bos@91
|
591 \interaction{tour.parents}
|
|
bos@101
|
592 If you look back at figure~\ref{fig:tour-basic:history}, you'll see
|
|
bos@101
|
593 arrows connecting each changeset. The node that the arrow leads
|
|
bos@101
|
594 \emph{from} in each case is a parent, and the node that the arrow
|
|
bos@101
|
595 leads \emph{to} is its child. The working directory has a parent in
|
|
bos@101
|
596 just the same way; this is the changeset that the working directory
|
|
bos@101
|
597 currently contains.
|
|
bos@101
|
598
|
|
bos@91
|
599 To update the working directory to a particular revision, give a
|
|
bos@91
|
600 revision number or changeset~ID to the \hgcmd{update} command.
|
|
bos@91
|
601 \interaction{tour.older}
|
|
bos@91
|
602 If you omit an explicit revision, \hgcmd{update} will update to the
|
|
bos@94
|
603 tip revision, as shown by the second call to \hgcmd{update} in the
|
|
bos@94
|
604 example above.
|
|
bos@91
|
605
|
|
bos@92
|
606 \subsection{Pushing changes to another repository}
|
|
bos@92
|
607
|
|
bos@92
|
608 Mercurial lets us push changes to another repository, from the
|
|
bos@92
|
609 repository we're currently visiting. As with the example of
|
|
bos@92
|
610 \hgcmd{pull} above, we'll create a temporary repository to push our
|
|
bos@92
|
611 changes into.
|
|
bos@92
|
612 \interaction{tour.clone-push}
|
|
bos@92
|
613 The \hgcmd{outgoing} command tells us what changes would be pushed
|
|
bos@92
|
614 into another repository.
|
|
bos@92
|
615 \interaction{tour.outgoing}
|
|
bos@92
|
616 And the \hgcmd{push} command does the actual push.
|
|
bos@92
|
617 \interaction{tour.push}
|
|
bos@92
|
618 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
|
|
bos@92
|
619 working directory in the repository that it's pushing changes into.
|
|
bos@92
|
620 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
|
|
bos@92
|
621 option that updates the other repository's working directory.)
|
|
bos@92
|
622
|
|
bos@92
|
623 What happens if we try to pull or push changes and the receiving
|
|
bos@92
|
624 repository already has those changes? Nothing too exciting.
|
|
bos@92
|
625 \interaction{tour.push.nothing}
|
|
bos@92
|
626
|
|
bos@93
|
627 \subsection{Sharing changes over a network}
|
|
bos@93
|
628
|
|
bos@93
|
629 The commands we have covered in the previous few sections are not
|
|
bos@93
|
630 limited to working with local repositories. Each works in exactly the
|
|
bos@93
|
631 same fashion over a network connection; simply pass in a URL instead
|
|
bos@93
|
632 of a local path.
|
|
bos@93
|
633 \interaction{tour.outgoing.net}
|
|
bos@93
|
634 In this example, we can see what changes we could push to the remote
|
|
bos@93
|
635 repository, but the repository is understandably not set up to let
|
|
bos@93
|
636 anonymous users push to it.
|
|
bos@93
|
637 \interaction{tour.push.net}
|
|
bos@93
|
638
|
|
bos@84
|
639 %%% Local Variables:
|
|
bos@84
|
640 %%% mode: latex
|
|
bos@84
|
641 %%% TeX-master: "00book"
|
|
bos@84
|
642 %%% End:
|
