hgbook

annotate fr/tour-basic.tex @ 933:4934b0c2947e

review french intro.tex
author Wilk
date Mon Feb 09 14:41:04 2009 +0100 (2009-02-09)
parents 547d3aa25ef0
children 651aa8fd9882
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
romain@931 7 Des paquetages binaires de Mercurial sont disponible pour tous les plupart
romain@931 8 des systèmes d'exploitation, ce qui rend facile de commencer de suite
romain@931 9 à utiliser 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
romain@931 14 de paquets, politique et rythme de développements, il est difficile de
romain@931 15 donner un ensemble instructions fixes pour installer les binaires de
romain@931 16 Mercurial. La version de Mercurial avec laquelle vous vous retrouverez
romain@931 17 dépendera grandement selon l'activité de la personne en charge du paquetage
romain@931 18 pour la distribution.
romain@931 19
romain@931 20 Pour rester simple, je me concentrerais 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
romain@931 47 \item[Ubuntu] Le paquetage de Mercurial d'Ubuntu est construit sur celui de Debian. Pour
romain@931 48 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
romain@931 53 par rapport au paquetage Debian (au moment de l'écriture de ce livre, un
romain@931 54 peu près 7 mois), ce qui signifie que parfois sur Ubuntu, vous risquez
romain@931 55 de rencontrer des problèmes qui ont été corrigés depuis longtemps dans
romain@931 56 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
romain@931 62 pour trouver un vaste nombre de paquet précompiler 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
romain@931 69 architecture 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,
romain@931 75 deux outils de gestion de paquetage libre 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
romain@931 106 une brève liste de commandes, avec une description de ce qu'elle fait. Si vous
romain@931 107 demandez de l'aide sur une commande spécifique (voir ci dessous), il affichera
romain@931 108 des informations plus détaillés.
bos@87 109 \interaction{tour.help}
romain@931 110 Pour un niveau d'informations encore plus détaillé (ce dont vous aurez rarement
romain@931 111 besoins), 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
romain@931 113 d'information 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
romain@931 118 la traduction que j'ai retenu pour tout l'ouvrage du terme anglais \textit{repository}}.
romain@931 119 Le dépôt d'une projet contient tout les fichiers qui ``appartiennent'' au projet.
bos@87 120 In Mercurial, everything happens inside a \emph{repository}. The
bos@87 121 repository for a project contains all of the files that ``belong to''
bos@87 122 that project, along with a historical record of the project's files.
bos@87 123
bos@87 124 There's nothing particularly magical about a repository; it is simply
bos@87 125 a directory tree in your filesystem that Mercurial treats as special.
steve@158 126 You can rename or delete a repository any time you like, using either the
bos@87 127 command line or your file browser.
bos@87 128
bos@88 129 \subsection{Making a local copy of a repository}
bos@87 130
bos@87 131 \emph{Copying} a repository is just a little bit special. While you
bos@87 132 could use a normal file copying command to make a copy of a
bos@87 133 repository, it's best to use a built-in command that Mercurial
bos@87 134 provides. This command is called \hgcmd{clone}, because it creates an
bos@87 135 identical copy of an existing repository.
bos@87 136 \interaction{tour.clone}
bos@87 137 If our clone succeeded, we should now have a local directory called
bos@87 138 \dirname{hello}. This directory will contain some files.
bos@87 139 \interaction{tour.ls}
bos@87 140 These files have the same contents and history in our repository as
bos@87 141 they do in the repository we cloned.
bos@87 142
bos@87 143 Every Mercurial repository is complete, self-contained, and
bos@87 144 independent. It contains its own private copy of a project's files
bos@87 145 and history. A cloned repository remembers the location of the
bos@87 146 repository it was cloned from, but it does not communicate with that
bos@87 147 repository, or any other, unless you tell it to.
bos@87 148
bos@87 149 What this means for now is that we're free to experiment with our
bos@87 150 repository, safe in the knowledge that it's a private ``sandbox'' that
bos@87 151 won't affect anyone else.
bos@85 152
bos@88 153 \subsection{What's in a repository?}
bos@88 154
bos@88 155 When we take a more detailed look inside a repository, we can see that
bos@88 156 it contains a directory named \dirname{.hg}. This is where Mercurial
bos@88 157 keeps all of its metadata for the repository.
bos@88 158 \interaction{tour.ls-a}
bos@88 159
bos@88 160 The contents of the \dirname{.hg} directory and its subdirectories are
bos@88 161 private to Mercurial. Every other file and directory in the
bos@88 162 repository is yours to do with as you please.
bos@88 163
bos@88 164 To introduce a little terminology, the \dirname{.hg} directory is the
bos@88 165 ``real'' repository, and all of the files and directories that coexist
bos@91 166 with it are said to live in the \emph{working directory}. An easy way
bos@91 167 to remember the distinction is that the \emph{repository} contains the
bos@88 168 \emph{history} of your project, while the \emph{working directory}
bos@88 169 contains a \emph{snapshot} of your project at a particular point in
bos@88 170 history.
bos@88 171
bos@88 172 \section{A tour through history}
bos@88 173
bos@88 174 One of the first things we might want to do with a new, unfamiliar
bos@88 175 repository is understand its history. The \hgcmd{log} command gives
bos@88 176 us a view of history.
bos@88 177 \interaction{tour.log}
bos@88 178 By default, this command prints a brief paragraph of output for each
bos@88 179 change to the project that was recorded. In Mercurial terminology, we
bos@88 180 call each of these recorded events a \emph{changeset}, because it can
bos@88 181 contain a record of changes to several files.
bos@88 182
bos@88 183 The fields in a record of output from \hgcmd{log} are as follows.
bos@88 184 \begin{itemize}
bos@88 185 \item[\texttt{changeset}] This field has the format of a number,
bos@88 186 followed by a colon, followed by a hexadecimal string. These are
bos@88 187 \emph{identifiers} for the changeset. There are two identifiers
bos@88 188 because the number is shorter and easier to type than the hex
bos@88 189 string.
bos@88 190 \item[\texttt{user}] The identity of the person who created the
bos@88 191 changeset. This is a free-form field, but it most often contains a
bos@88 192 person's name and email address.
bos@88 193 \item[\texttt{date}] The date and time on which the changeset was
steve@158 194 created, and the timezone in which it was created. (The date and
bos@88 195 time are local to that timezone; they display what time and date it
bos@88 196 was for the person who created the changeset.)
bos@88 197 \item[\texttt{summary}] The first line of the text message that the
bos@88 198 creator of the changeset entered to describe the changeset.
bos@88 199 \end{itemize}
bos@88 200 The default output printed by \hgcmd{log} is purely a summary; it is
bos@88 201 missing a lot of detail.
bos@88 202
bos@99 203 Figure~\ref{fig:tour-basic:history} provides a graphical representation of
bos@97 204 the history of the \dirname{hello} repository, to make it a little
bos@97 205 easier to see which direction history is ``flowing'' in. We'll be
bos@97 206 returning to this figure several times in this chapter and the chapter
bos@97 207 that follows.
bos@97 208
bos@96 209 \begin{figure}[ht]
bos@96 210 \centering
bos@96 211 \grafix{tour-history}
bos@96 212 \caption{Graphical history of the \dirname{hello} repository}
bos@99 213 \label{fig:tour-basic:history}
bos@96 214 \end{figure}
bos@96 215
bos@97 216 \subsection{Changesets, revisions, and talking to other
bos@97 217 people}
bos@97 218
bos@97 219 As English is a notoriously sloppy language, and computer science has
bos@99 220 a hallowed history of terminological confusion (why use one term when
bos@99 221 four will do?), revision control has a variety of words and phrases
bos@99 222 that mean the same thing. If you are talking about Mercurial history
bos@99 223 with other people, you will find that the word ``changeset'' is often
bos@99 224 compressed to ``change'' or (when written) ``cset'', and sometimes a
bos@99 225 changeset is referred to as a ``revision'' or a ``rev''.
bos@88 226
bos@88 227 While it doesn't matter what \emph{word} you use to refer to the
bos@88 228 concept of ``a~changeset'', the \emph{identifier} that you use to
bos@88 229 refer to ``a~\emph{specific} changeset'' is of great importance.
bos@88 230 Recall that the \texttt{changeset} field in the output from
bos@88 231 \hgcmd{log} identifies a changeset using both a number and a
bos@97 232 hexadecimal string.
bos@97 233 \begin{itemize}
bos@97 234 \item The revision number is \emph{only valid in that repository},
bos@97 235 \item while the hex string is the \emph{permanent, unchanging
bos@97 236 identifier} that will always identify that exact changeset in
bos@97 237 \emph{every} copy of the repository.
bos@97 238 \end{itemize}
bos@88 239 This distinction is important. If you send someone an email talking
bos@88 240 about ``revision~33'', there's a high likelihood that their
bos@88 241 revision~33 will \emph{not be the same} as yours. The reason for this
bos@88 242 is that a revision number depends on the order in which changes
bos@88 243 arrived in a repository, and there is no guarantee that the same
bos@88 244 changes will happen in the same order in different repositories.
bos@88 245 Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
bos@88 246 while in another as $1,0,2$.
bos@88 247
bos@88 248 Mercurial uses revision numbers purely as a convenient shorthand. If
bos@88 249 you need to discuss a changeset with someone, or make a record of a
bos@88 250 changeset for some other reason (for example, in a bug report), use
bos@88 251 the hexadecimal identifier.
bos@88 252
bos@88 253 \subsection{Viewing specific revisions}
bos@88 254
bos@88 255 To narrow the output of \hgcmd{log} down to a single revision, use the
bos@91 256 \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a
bos@91 257 revision number or a long-form changeset identifier, and you can
bos@91 258 provide as many revisions as you want. \interaction{tour.log-r}
bos@88 259
bos@88 260 If you want to see the history of several revisions without having to
bos@88 261 list each one, you can use \emph{range notation}; this lets you
bos@88 262 express the idea ``I want all revisions between $a$ and $b$,
bos@88 263 inclusive''.
bos@88 264 \interaction{tour.log.range}
bos@88 265 Mercurial also honours the order in which you specify revisions, so
bos@88 266 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
bos@88 267 prints $4,3,2$.
bos@88 268
bos@91 269 \subsection{More detailed information}
bos@91 270
bos@91 271 While the summary information printed by \hgcmd{log} is useful if you
bos@91 272 already know what you're looking for, you may need to see a complete
bos@91 273 description of the change, or a list of the files changed, if you're
bos@91 274 trying to decide whether a changeset is the one you're looking for.
bos@91 275 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
bos@91 276 option gives you this extra detail.
bos@91 277 \interaction{tour.log-v}
bos@91 278
bos@91 279 If you want to see both the description and content of a change, add
bos@91 280 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays
bos@91 281 the content of a change as a \emph{unified diff} (if you've never seen
bos@91 282 a unified diff before, see section~\ref{sec:mq:patch} for an overview).
bos@91 283 \interaction{tour.log-vp}
bos@91 284
bos@91 285 \section{All about command options}
bos@91 286
bos@91 287 Let's take a brief break from exploring Mercurial commands to discuss
bos@91 288 a pattern in the way that they work; you may find this useful to keep
steve@158 289 in mind as we continue our tour.
bos@91 290
bos@91 291 Mercurial has a consistent and straightforward approach to dealing
bos@91 292 with the options that you can pass to commands. It follows the
bos@91 293 conventions for options that are common to modern Linux and Unix
bos@91 294 systems.
bos@91 295 \begin{itemize}
bos@91 296 \item Every option has a long name. For example, as we've already
bos@91 297 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
bos@91 298 \item Most options have short names, too. Instead of
bos@91 299 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that
bos@91 300 some options don't have short names is that the options in question
bos@91 301 are rarely used.)
bos@91 302 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
bos@91 303 while short options start with one (e.g.~\hgopt{log}{-r}).
bos@91 304 \item Option naming and usage is consistent across commands. For
bos@91 305 example, every command that lets you specify a changeset~ID or
bos@91 306 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
bos@91 307 arguments.
bos@91 308 \end{itemize}
bos@91 309 In the examples throughout this book, I use short options instead of
bos@91 310 long. This just reflects my own preference, so don't read anything
bos@91 311 significant into it.
bos@91 312
bos@91 313 Most commands that print output of some kind will print more output
bos@91 314 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
bos@91 315 when passed \hggopt{-q} (or \hggopt{--quiet}).
bos@91 316
bos@91 317 \section{Making and reviewing changes}
bos@91 318
bos@91 319 Now that we have a grasp of viewing history in Mercurial, let's take a
bos@91 320 look at making some changes and examining them.
bos@91 321
bos@91 322 The first thing we'll do is isolate our experiment in a repository of
bos@91 323 its own. We use the \hgcmd{clone} command, but we don't need to
bos@91 324 clone a copy of the remote repository. Since we already have a copy
bos@91 325 of it locally, we can just clone that instead. This is much faster
bos@91 326 than cloning over the network, and cloning a local repository uses
bos@91 327 less disk space in most cases, too.
bos@91 328 \interaction{tour.reclone}
bos@91 329 As an aside, it's often good practice to keep a ``pristine'' copy of a
bos@91 330 remote repository around, which you can then make temporary clones of
bos@91 331 to create sandboxes for each task you want to work on. This lets you
bos@91 332 work on multiple tasks in parallel, each isolated from the others
bos@91 333 until it's complete and you're ready to integrate it back. Because
bos@91 334 local clones are so cheap, there's almost no overhead to cloning and
bos@91 335 destroying repositories whenever you want.
bos@91 336
bos@91 337 In our \dirname{my-hello} repository, we have a file
bos@91 338 \filename{hello.c} that contains the classic ``hello, world'' program.
bos@91 339 Let's use the ancient and venerable \command{sed} command to edit this
bos@91 340 file so that it prints a second line of output. (I'm only using
bos@91 341 \command{sed} to do this because it's easy to write a scripted example
bos@91 342 this way. Since you're not under the same constraint, you probably
bos@91 343 won't want to use \command{sed}; simply use your preferred text editor to
bos@91 344 do the same thing.)
bos@91 345 \interaction{tour.sed}
bos@91 346
bos@91 347 Mercurial's \hgcmd{status} command will tell us what Mercurial knows
bos@91 348 about the files in the repository.
bos@91 349 \interaction{tour.status}
bos@91 350 The \hgcmd{status} command prints no output for some files, but a line
bos@91 351 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell
bos@91 352 it to, \hgcmd{status} will not print any output for files that have
bos@91 353 not been modified.
bos@91 354
bos@91 355 The ``\texttt{M}'' indicates that Mercurial has noticed that we
bos@97 356 modified \filename{hello.c}. We didn't need to \emph{inform}
bos@97 357 Mercurial that we were going to modify the file before we started, or
bos@97 358 that we had modified the file after we were done; it was able to
bos@97 359 figure this out itself.
bos@91 360
bos@91 361 It's a little bit helpful to know that we've modified
bos@91 362 \filename{hello.c}, but we might prefer to know exactly \emph{what}
bos@91 363 changes we've made to it. To do this, we use the \hgcmd{diff}
bos@91 364 command.
bos@91 365 \interaction{tour.diff}
bos@91 366
bos@91 367 \section{Recording changes in a new changeset}
bos@91 368
bos@91 369 We can modify files, build and test our changes, and use
bos@91 370 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're
bos@91 371 satisfied with what we've done and arrive at a natural stopping point
bos@91 372 where we want to record our work in a new changeset.
bos@91 373
bos@91 374 The \hgcmd{commit} command lets us create a new changeset; we'll
bos@91 375 usually refer to this as ``making a commit'' or ``committing''.
bos@91 376
bos@102 377 \subsection{Setting up a username}
bos@102 378
bos@174 379 When you try to run \hgcmd{commit} for the first time, it is not
bos@174 380 guaranteed to succeed. Mercurial records your name and address with
bos@174 381 each change that you commit, so that you and others will later be able
bos@174 382 to tell who made each change. Mercurial tries to automatically figure
bos@174 383 out a sensible username to commit the change with. It will attempt
bos@174 384 each of the following methods, in order:
bos@174 385 \begin{enumerate}
bos@174 386 \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
bos@174 387 command on the command line, followed by a username, this is always
bos@174 388 given the highest precedence.
bos@174 389 \item If you have set the \envar{HGUSER} environment variable, this is
bos@174 390 checked next.
bos@174 391 \item If you create a file in your home directory called
bos@174 392 \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
bos@174 393 used next. To see what the contents of this file should look like,
bos@174 394 refer to section~\ref{sec:tour-basic:username} below.
bos@174 395 \item If you have set the \envar{EMAIL} environment variable, this
bos@174 396 will be used next.
bos@174 397 \item Mercurial will query your system to find out your local user
bos@174 398 name and host name, and construct a username from these components.
bos@174 399 Since this often results in a username that is not very useful, it
bos@174 400 will print a warning if it has to do this.
bos@174 401 \end{enumerate}
bos@174 402 If all of these mechanisms fail, Mercurial will fail, printing an
bos@174 403 error message. In this case, it will not let you commit until you set
bos@174 404 up a username.
bos@174 405
bos@174 406 You should think of the \envar{HGUSER} environment variable and the
bos@174 407 \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
bos@174 408 \emph{override} Mercurial's default selection of username. For normal
bos@174 409 use, the simplest and most robust way to set a username for yourself
bos@174 410 is by creating a \sfilename{.hgrc} file; see below for details.
bos@102 411
bos@102 412 \subsubsection{Creating a Mercurial configuration file}
bos@174 413 \label{sec:tour-basic:username}
bos@102 414
bos@102 415 To set a user name, use your favourite editor to create a file called
bos@102 416 \sfilename{.hgrc} in your home directory. Mercurial will use this
bos@102 417 file to look up your personalised configuration settings. The initial
bos@102 418 contents of your \sfilename{.hgrc} should look like this.
bos@102 419 \begin{codesample2}
bos@102 420 # This is a Mercurial configuration file.
bos@102 421 [ui]
bos@102 422 username = Firstname Lastname <email.address@domain.net>
bos@102 423 \end{codesample2}
bos@102 424 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
bos@102 425 so you can read the ``\texttt{username = ...}'' line as meaning ``set
bos@102 426 the value of the \texttt{username} item in the \texttt{ui} section''.
bos@102 427 A section continues until a new section begins, or the end of the
bos@102 428 file. Mercurial ignores empty lines and treats any text from
bos@102 429 ``\texttt{\#}'' to the end of a line as a comment.
bos@102 430
bos@102 431 \subsubsection{Choosing a user name}
bos@102 432
bos@102 433 You can use any text you like as the value of the \texttt{username}
bos@102 434 config item, since this information is for reading by other people,
bos@102 435 but for interpreting by Mercurial. The convention that most people
bos@102 436 follow is to use their name and email address, as in the example
bos@102 437 above.
bos@102 438
bos@102 439 \begin{note}
bos@102 440 Mercurial's built-in web server obfuscates email addresses, to make
bos@102 441 it more difficult for the email harvesting tools that spammers use.
bos@102 442 This reduces the likelihood that you'll start receiving more junk
bos@102 443 email if you publish a Mercurial repository on the web.
bos@102 444 \end{note}
bos@102 445
bos@91 446 \subsection{Writing a commit message}
bos@91 447
bos@91 448 When we commit a change, Mercurial drops us into a text editor, to
bos@91 449 enter a message that will describe the modifications we've made in
bos@91 450 this changeset. This is called the \emph{commit message}. It will be
bos@91 451 a record for readers of what we did and why, and it will be printed by
bos@91 452 \hgcmd{log} after we've finished committing.
bos@91 453 \interaction{tour.commit}
bos@91 454
bos@91 455 The editor that the \hgcmd{commit} command drops us into will contain
bos@91 456 an empty line, followed by a number of lines starting with
bos@91 457 ``\texttt{HG:}''.
bos@91 458 \begin{codesample2}
bos@91 459 \emph{empty line}
bos@91 460 HG: changed hello.c
bos@91 461 \end{codesample2}
bos@91 462 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
bos@91 463 them only to tell us which files it's recording changes to. Modifying
bos@91 464 or deleting these lines has no effect.
bos@91 465
bos@91 466 \subsection{Writing a good commit message}
bos@91 467
bos@91 468 Since \hgcmd{log} only prints the first line of a commit message by
bos@91 469 default, it's best to write a commit message whose first line stands
bos@91 470 alone. Here's a real example of a commit message that \emph{doesn't}
bos@91 471 follow this guideline, and hence has a summary that is not readable.
bos@91 472 \begin{codesample2}
bos@91 473 changeset: 73:584af0e231be
bos@91 474 user: Censored Person <censored.person@example.org>
bos@91 475 date: Tue Sep 26 21:37:07 2006 -0700
bos@91 476 summary: include buildmeister/commondefs. Add an exports and install
bos@91 477 \end{codesample2}
bos@91 478
bos@91 479 As far as the remainder of the contents of the commit message are
bos@91 480 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
bos@91 481 interpret or care about the contents of the commit message, though
bos@91 482 your project may have policies that dictate a certain kind of
bos@91 483 formatting.
bos@91 484
bos@91 485 My personal preference is for short, but informative, commit messages
bos@91 486 that tell me something that I can't figure out with a quick glance at
bos@91 487 the output of \hgcmdargs{log}{--patch}.
bos@91 488
bos@91 489 \subsection{Aborting a commit}
bos@91 490
bos@91 491 If you decide that you don't want to commit while in the middle of
bos@91 492 editing a commit message, simply exit from your editor without saving
bos@91 493 the file that it's editing. This will cause nothing to happen to
bos@91 494 either the repository or the working directory.
bos@91 495
bos@91 496 If we run the \hgcmd{commit} command without any arguments, it records
bos@91 497 all of the changes we've made, as reported by \hgcmd{status} and
bos@91 498 \hgcmd{diff}.
bos@91 499
bos@102 500 \subsection{Admiring our new handiwork}
bos@91 501
bos@91 502 Once we've finished the commit, we can use the \hgcmd{tip} command to
bos@91 503 display the changeset we just created. This command produces output
bos@91 504 that is identical to \hgcmd{log}, but it only displays the newest
bos@91 505 revision in the repository.
bos@91 506 \interaction{tour.tip}
bos@91 507 We refer to the newest revision in the repository as the tip revision,
bos@91 508 or simply the tip.
bos@91 509
bos@91 510 \section{Sharing changes}
bos@91 511
bos@91 512 We mentioned earlier that repositories in Mercurial are
bos@91 513 self-contained. This means that the changeset we just created exists
bos@91 514 only in our \dirname{my-hello} repository. Let's look at a few ways
bos@91 515 that we can propagate this change into other repositories.
bos@91 516
bos@91 517 \subsection{Pulling changes from another repository}
bos@91 518 \label{sec:tour:pull}
bos@91 519
bos@91 520 To get started, let's clone our original \dirname{hello} repository,
bos@91 521 which does not contain the change we just committed. We'll call our
bos@91 522 temporary repository \dirname{hello-pull}.
bos@91 523 \interaction{tour.clone-pull}
bos@91 524
bos@91 525 We'll use the \hgcmd{pull} command to bring changes from
bos@91 526 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
bos@91 527 pulling unknown changes into a repository is a somewhat scary
bos@91 528 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
bos@91 529 what changes the \hgcmd{pull} command \emph{would} pull into the
bos@91 530 repository, without actually pulling the changes in.
bos@91 531 \interaction{tour.incoming}
bos@91 532 (Of course, someone could cause more changesets to appear in the
bos@91 533 repository that we ran \hgcmd{incoming} in, before we get a chance to
bos@91 534 \hgcmd{pull} the changes, so that we could end up pulling changes that we
bos@91 535 didn't expect.)
bos@91 536
bos@91 537 Bringing changes into a repository is a simple matter of running the
bos@91 538 \hgcmd{pull} command, and telling it which repository to pull from.
bos@91 539 \interaction{tour.pull}
bos@91 540 As you can see from the before-and-after output of \hgcmd{tip}, we
bos@91 541 have successfully pulled changes into our repository. There remains
bos@92 542 one step before we can see these changes in the working directory.
bos@92 543
bos@92 544 \subsection{Updating the working directory}
bos@92 545
bos@92 546 We have so far glossed over the relationship between a repository and
bos@91 547 its working directory. The \hgcmd{pull} command that we ran in
bos@91 548 section~\ref{sec:tour:pull} brought changes into the repository, but
bos@91 549 if we check, there's no sign of those changes in the working
bos@91 550 directory. This is because \hgcmd{pull} does not (by default) touch
bos@91 551 the working directory. Instead, we use the \hgcmd{update} command to
bos@91 552 do this.
bos@91 553 \interaction{tour.update}
bos@91 554
bos@91 555 It might seem a bit strange that \hgcmd{pull} doesn't update the
bos@91 556 working directory automatically. There's actually a good reason for
bos@91 557 this: you can use \hgcmd{update} to update the working directory to
bos@91 558 the state it was in at \emph{any revision} in the history of the
bos@91 559 repository. If you had the working directory updated to an old
bos@91 560 revision---to hunt down the origin of a bug, say---and ran a
bos@91 561 \hgcmd{pull} which automatically updated the working directory to a
bos@91 562 new revision, you might not be terribly happy.
bos@91 563
bos@91 564 However, since pull-then-update is such a common thing to do,
bos@91 565 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
bos@91 566 option to \hgcmd{pull}.
bos@91 567 \begin{codesample2}
bos@91 568 hg pull -u
bos@91 569 \end{codesample2}
bos@92 570 If you look back at the output of \hgcmd{pull} in
bos@92 571 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
bos@92 572 you can see that it printed a helpful reminder that we'd have to take
bos@92 573 an explicit step to update the working directory:
bos@92 574 \begin{codesample2}
bos@92 575 (run 'hg update' to get a working copy)
bos@92 576 \end{codesample2}
bos@91 577
bos@91 578 To find out what revision the working directory is at, use the
bos@91 579 \hgcmd{parents} command.
bos@91 580 \interaction{tour.parents}
bos@101 581 If you look back at figure~\ref{fig:tour-basic:history}, you'll see
bos@101 582 arrows connecting each changeset. The node that the arrow leads
bos@101 583 \emph{from} in each case is a parent, and the node that the arrow
bos@101 584 leads \emph{to} is its child. The working directory has a parent in
bos@101 585 just the same way; this is the changeset that the working directory
bos@101 586 currently contains.
bos@101 587
bos@91 588 To update the working directory to a particular revision, give a
bos@91 589 revision number or changeset~ID to the \hgcmd{update} command.
bos@91 590 \interaction{tour.older}
bos@91 591 If you omit an explicit revision, \hgcmd{update} will update to the
bos@94 592 tip revision, as shown by the second call to \hgcmd{update} in the
bos@94 593 example above.
bos@91 594
bos@92 595 \subsection{Pushing changes to another repository}
bos@92 596
bos@92 597 Mercurial lets us push changes to another repository, from the
bos@92 598 repository we're currently visiting. As with the example of
bos@92 599 \hgcmd{pull} above, we'll create a temporary repository to push our
bos@92 600 changes into.
bos@92 601 \interaction{tour.clone-push}
bos@92 602 The \hgcmd{outgoing} command tells us what changes would be pushed
bos@92 603 into another repository.
bos@92 604 \interaction{tour.outgoing}
bos@92 605 And the \hgcmd{push} command does the actual push.
bos@92 606 \interaction{tour.push}
bos@92 607 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
bos@92 608 working directory in the repository that it's pushing changes into.
bos@92 609 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
bos@92 610 option that updates the other repository's working directory.)
bos@92 611
bos@92 612 What happens if we try to pull or push changes and the receiving
bos@92 613 repository already has those changes? Nothing too exciting.
bos@92 614 \interaction{tour.push.nothing}
bos@92 615
bos@93 616 \subsection{Sharing changes over a network}
bos@93 617
bos@93 618 The commands we have covered in the previous few sections are not
bos@93 619 limited to working with local repositories. Each works in exactly the
bos@93 620 same fashion over a network connection; simply pass in a URL instead
bos@93 621 of a local path.
bos@93 622 \interaction{tour.outgoing.net}
bos@93 623 In this example, we can see what changes we could push to the remote
bos@93 624 repository, but the repository is understandably not set up to let
bos@93 625 anonymous users push to it.
bos@93 626 \interaction{tour.push.net}
bos@93 627
bos@84 628 %%% Local Variables:
bos@84 629 %%% mode: latex
bos@84 630 %%% TeX-master: "00book"
bos@84 631 %%% End: