hgbook

annotate en/tour-basic.tex @ 96:7d7ddc3a57af

Split tour into two chapters.
author Bryan O'Sullivan <bos@serpentine.com>
date Fri Oct 13 15:34:54 2006 -0700 (2006-10-13)
parents 47ea206351d5
children 659fa1a2c628
rev   line source
bos@95 1 \chapter{A tour of Mercurial: the basics}
bos@95 2 \label{chap:tour-basic}
bos@84 3
bos@84 4 \section{Installing Mercurial on your system}
bos@84 5 \label{sec:tour:install}
bos@84 6
bos@85 7 Prebuilt binary packages of Mercurial are available for every popular
bos@85 8 operating system. These make it easy to start using Mercurial on your
bos@85 9 computer immediately.
bos@85 10
bos@84 11 \subsection{Linux}
bos@84 12
bos@84 13 Because each Linux distribution has its own packaging tools, policies,
bos@84 14 and rate of development, it's difficult to give a comprehensive set of
bos@85 15 instructions on how to install Mercurial binaries. The version of
bos@85 16 Mercurial that you will end up with can vary depending on how active
bos@85 17 the person is who maintains the package for your distribution.
bos@84 18
bos@84 19 To keep things simple, I will focus on installing Mercurial from the
bos@84 20 command line under the most popular Linux distributions. Most of
bos@84 21 these distributions provide graphical package managers that will let
bos@84 22 you install Mercurial with a single click; the package name to look
bos@84 23 for is \texttt{mercurial}.
bos@84 24
bos@85 25 \begin{itemize}
bos@85 26 \item[Debian]
bos@85 27 \begin{codesample4}
bos@85 28 apt-get install mercurial
bos@85 29 \end{codesample4}
bos@84 30
bos@85 31 \item[Fedora Core]
bos@85 32 \begin{codesample4}
bos@85 33 yum install mercurial
bos@85 34 \end{codesample4}
bos@84 35
bos@85 36 \item[Gentoo]
bos@85 37 \begin{codesample4}
bos@85 38 emerge mercurial
bos@85 39 \end{codesample4}
bos@84 40
bos@85 41 \item[OpenSUSE]
bos@85 42 \begin{codesample4}
bos@85 43 yum install mercurial
bos@85 44 \end{codesample4}
bos@84 45
bos@85 46 \item[Ubuntu] Ubuntu's Mercurial package is particularly old, and you
bos@85 47 should not use it. If you know how, you can rebuild and install the
bos@85 48 Debian package. It's probably easier to build Mercurial from source
bos@85 49 and simply run that; see section~\ref{sec:srcinstall:unixlike} for
bos@85 50 details.
bos@85 51 \end{itemize}
bos@84 52
bos@84 53 \subsection{Mac OS X}
bos@84 54
bos@84 55 Lee Cantey publishes an installer of Mercurial for Mac OS~X at
bos@84 56 \url{http://mercurial.berkwood.com}. This package works on both
bos@85 57 Intel-~and Power-based Macs. Before you can use it, you must install
bos@85 58 a compatible version of Universal MacPython~\cite{web:macpython}. This
bos@85 59 is easy to do; simply follow the instructions on Lee's site.
bos@84 60
bos@84 61 \subsection{Solaris}
bos@84 62
bos@84 63 XXX.
bos@84 64
bos@84 65 \subsection{Windows}
bos@84 66
bos@84 67 Lee Cantey publishes an installer of Mercurial for Windows at
bos@84 68 \url{http://mercurial.berkwood.com}. This package has no external
bos@84 69 dependencies; it ``just works''.
bos@84 70
bos@84 71 \begin{note}
bos@84 72 The Windows version of Mercurial does not automatically convert line
bos@84 73 endings between Windows and Unix styles. If you want to share work
bos@84 74 with Unix users, you must do a little additional configuration
bos@84 75 work. XXX Flesh this out.
bos@84 76 \end{note}
bos@84 77
bos@87 78 \section{Getting started}
bos@87 79
bos@87 80 To begin, we'll use the \hgcmd{version} command to find out whether
bos@87 81 Mercurial is actually installed properly. The actual version
bos@87 82 information that it prints isn't so important; it's whether it prints
bos@87 83 anything at all that we care about.
bos@87 84 \interaction{tour.version}
bos@87 85
bos@87 86 \subsection{Built-in help}
bos@87 87
bos@87 88 Mercurial provides a built-in help system. This invaluable for those
bos@87 89 times when you find yourself stuck trying to remember how to run a
bos@87 90 command. If you are completely stuck, simply run \hgcmd{help}; it
bos@87 91 will print a brief list of commands, along with a description of what
bos@87 92 each does. If you ask for help on a specific command (as below), it
bos@87 93 prints more detailed information.
bos@87 94 \interaction{tour.help}
bos@87 95 For a more impressive level of detail (which you won't usually need)
bos@87 96 run \hgcmdargs{help}{\hggopt{-v}}. The \hggopt{-v} option is short
bos@87 97 for \hggopt{--verbose}, and tells Mercurial to print more information
bos@87 98 than it usually would.
bos@87 99
bos@87 100 \section{Working with a repository}
bos@87 101
bos@87 102 In Mercurial, everything happens inside a \emph{repository}. The
bos@87 103 repository for a project contains all of the files that ``belong to''
bos@87 104 that project, along with a historical record of the project's files.
bos@87 105
bos@87 106 There's nothing particularly magical about a repository; it is simply
bos@87 107 a directory tree in your filesystem that Mercurial treats as special.
bos@87 108 You can rename delete a repository any time you like, using either the
bos@87 109 command line or your file browser.
bos@87 110
bos@88 111 \subsection{Making a local copy of a repository}
bos@87 112
bos@87 113 \emph{Copying} a repository is just a little bit special. While you
bos@87 114 could use a normal file copying command to make a copy of a
bos@87 115 repository, it's best to use a built-in command that Mercurial
bos@87 116 provides. This command is called \hgcmd{clone}, because it creates an
bos@87 117 identical copy of an existing repository.
bos@87 118 \interaction{tour.clone}
bos@87 119 If our clone succeeded, we should now have a local directory called
bos@87 120 \dirname{hello}. This directory will contain some files.
bos@87 121 \interaction{tour.ls}
bos@87 122 These files have the same contents and history in our repository as
bos@87 123 they do in the repository we cloned.
bos@87 124
bos@87 125 Every Mercurial repository is complete, self-contained, and
bos@87 126 independent. It contains its own private copy of a project's files
bos@87 127 and history. A cloned repository remembers the location of the
bos@87 128 repository it was cloned from, but it does not communicate with that
bos@87 129 repository, or any other, unless you tell it to.
bos@87 130
bos@87 131 What this means for now is that we're free to experiment with our
bos@87 132 repository, safe in the knowledge that it's a private ``sandbox'' that
bos@87 133 won't affect anyone else.
bos@85 134
bos@88 135 \subsection{What's in a repository?}
bos@88 136
bos@88 137 When we take a more detailed look inside a repository, we can see that
bos@88 138 it contains a directory named \dirname{.hg}. This is where Mercurial
bos@88 139 keeps all of its metadata for the repository.
bos@88 140 \interaction{tour.ls-a}
bos@88 141
bos@88 142 The contents of the \dirname{.hg} directory and its subdirectories are
bos@88 143 private to Mercurial. Every other file and directory in the
bos@88 144 repository is yours to do with as you please.
bos@88 145
bos@88 146 To introduce a little terminology, the \dirname{.hg} directory is the
bos@88 147 ``real'' repository, and all of the files and directories that coexist
bos@91 148 with it are said to live in the \emph{working directory}. An easy way
bos@91 149 to remember the distinction is that the \emph{repository} contains the
bos@88 150 \emph{history} of your project, while the \emph{working directory}
bos@88 151 contains a \emph{snapshot} of your project at a particular point in
bos@88 152 history.
bos@88 153
bos@88 154 \section{A tour through history}
bos@88 155
bos@88 156 One of the first things we might want to do with a new, unfamiliar
bos@88 157 repository is understand its history. The \hgcmd{log} command gives
bos@88 158 us a view of history.
bos@88 159 \interaction{tour.log}
bos@88 160 By default, this command prints a brief paragraph of output for each
bos@88 161 change to the project that was recorded. In Mercurial terminology, we
bos@88 162 call each of these recorded events a \emph{changeset}, because it can
bos@88 163 contain a record of changes to several files.
bos@88 164
bos@88 165 The fields in a record of output from \hgcmd{log} are as follows.
bos@88 166 \begin{itemize}
bos@88 167 \item[\texttt{changeset}] This field has the format of a number,
bos@88 168 followed by a colon, followed by a hexadecimal string. These are
bos@88 169 \emph{identifiers} for the changeset. There are two identifiers
bos@88 170 because the number is shorter and easier to type than the hex
bos@88 171 string.
bos@88 172 \item[\texttt{user}] The identity of the person who created the
bos@88 173 changeset. This is a free-form field, but it most often contains a
bos@88 174 person's name and email address.
bos@88 175 \item[\texttt{date}] The date and time on which the changeset was
bos@88 176 created, and the timezone in which it was created. (Thef date and
bos@88 177 time are local to that timezone; they display what time and date it
bos@88 178 was for the person who created the changeset.)
bos@88 179 \item[\texttt{summary}] The first line of the text message that the
bos@88 180 creator of the changeset entered to describe the changeset.
bos@88 181 \end{itemize}
bos@88 182 The default output printed by \hgcmd{log} is purely a summary; it is
bos@88 183 missing a lot of detail.
bos@88 184
bos@96 185 \begin{figure}[ht]
bos@96 186 \centering
bos@96 187 \grafix{tour-history}
bos@96 188 \caption{Graphical history of the \dirname{hello} repository}
bos@96 189 \label{fig:tour:history}
bos@96 190 \end{figure}
bos@96 191
bos@88 192 \subsection{Changesets, revisions, and identification}
bos@88 193
bos@88 194 English being a notoriously sloppy language, we have a variety of
bos@88 195 terms that have the same meaning. If you are talking about Mercurial
bos@88 196 history with other people, you will find that the word ``changeset''
bos@88 197 is often compressed to ``change'' or ``cset'', and sometimes a
bos@88 198 changeset is referred to as a ``revision'' or a ``rev''.
bos@88 199
bos@88 200 While it doesn't matter what \emph{word} you use to refer to the
bos@88 201 concept of ``a~changeset'', the \emph{identifier} that you use to
bos@88 202 refer to ``a~\emph{specific} changeset'' is of great importance.
bos@88 203 Recall that the \texttt{changeset} field in the output from
bos@88 204 \hgcmd{log} identifies a changeset using both a number and a
bos@88 205 hexadecimal string. The number is \emph{only valid in that
bos@88 206 repository}, while the hex string is the \emph{permanent, unchanging
bos@88 207 identifier} that will always identify that changeset in every copy
bos@88 208 of the repository.
bos@88 209
bos@88 210 This distinction is important. If you send someone an email talking
bos@88 211 about ``revision~33'', there's a high likelihood that their
bos@88 212 revision~33 will \emph{not be the same} as yours. The reason for this
bos@88 213 is that a revision number depends on the order in which changes
bos@88 214 arrived in a repository, and there is no guarantee that the same
bos@88 215 changes will happen in the same order in different repositories.
bos@88 216 Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
bos@88 217 while in another as $1,0,2$.
bos@88 218
bos@88 219 Mercurial uses revision numbers purely as a convenient shorthand. If
bos@88 220 you need to discuss a changeset with someone, or make a record of a
bos@88 221 changeset for some other reason (for example, in a bug report), use
bos@88 222 the hexadecimal identifier.
bos@88 223
bos@88 224 \subsection{Viewing specific revisions}
bos@88 225
bos@88 226 To narrow the output of \hgcmd{log} down to a single revision, use the
bos@91 227 \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a
bos@91 228 revision number or a long-form changeset identifier, and you can
bos@91 229 provide as many revisions as you want. \interaction{tour.log-r}
bos@88 230
bos@88 231 If you want to see the history of several revisions without having to
bos@88 232 list each one, you can use \emph{range notation}; this lets you
bos@88 233 express the idea ``I want all revisions between $a$ and $b$,
bos@88 234 inclusive''.
bos@88 235 \interaction{tour.log.range}
bos@88 236 Mercurial also honours the order in which you specify revisions, so
bos@88 237 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
bos@88 238 prints $4,3,2$.
bos@88 239
bos@91 240 \subsection{More detailed information}
bos@91 241
bos@91 242 While the summary information printed by \hgcmd{log} is useful if you
bos@91 243 already know what you're looking for, you may need to see a complete
bos@91 244 description of the change, or a list of the files changed, if you're
bos@91 245 trying to decide whether a changeset is the one you're looking for.
bos@91 246 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
bos@91 247 option gives you this extra detail.
bos@91 248 \interaction{tour.log-v}
bos@91 249
bos@91 250 If you want to see both the description and content of a change, add
bos@91 251 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays
bos@91 252 the content of a change as a \emph{unified diff} (if you've never seen
bos@91 253 a unified diff before, see section~\ref{sec:mq:patch} for an overview).
bos@91 254 \interaction{tour.log-vp}
bos@91 255
bos@91 256 \section{All about command options}
bos@91 257
bos@91 258 Let's take a brief break from exploring Mercurial commands to discuss
bos@91 259 a pattern in the way that they work; you may find this useful to keep
bos@91 260 in mind as we continiue our tour.
bos@91 261
bos@91 262 Mercurial has a consistent and straightforward approach to dealing
bos@91 263 with the options that you can pass to commands. It follows the
bos@91 264 conventions for options that are common to modern Linux and Unix
bos@91 265 systems.
bos@91 266 \begin{itemize}
bos@91 267 \item Every option has a long name. For example, as we've already
bos@91 268 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
bos@91 269 \item Most options have short names, too. Instead of
bos@91 270 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that
bos@91 271 some options don't have short names is that the options in question
bos@91 272 are rarely used.)
bos@91 273 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
bos@91 274 while short options start with one (e.g.~\hgopt{log}{-r}).
bos@91 275 \item Option naming and usage is consistent across commands. For
bos@91 276 example, every command that lets you specify a changeset~ID or
bos@91 277 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
bos@91 278 arguments.
bos@91 279 \end{itemize}
bos@91 280 In the examples throughout this book, I use short options instead of
bos@91 281 long. This just reflects my own preference, so don't read anything
bos@91 282 significant into it.
bos@91 283
bos@91 284 Most commands that print output of some kind will print more output
bos@91 285 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
bos@91 286 when passed \hggopt{-q} (or \hggopt{--quiet}).
bos@91 287
bos@91 288 \section{Making and reviewing changes}
bos@91 289
bos@91 290 Now that we have a grasp of viewing history in Mercurial, let's take a
bos@91 291 look at making some changes and examining them.
bos@91 292
bos@91 293 The first thing we'll do is isolate our experiment in a repository of
bos@91 294 its own. We use the \hgcmd{clone} command, but we don't need to
bos@91 295 clone a copy of the remote repository. Since we already have a copy
bos@91 296 of it locally, we can just clone that instead. This is much faster
bos@91 297 than cloning over the network, and cloning a local repository uses
bos@91 298 less disk space in most cases, too.
bos@91 299 \interaction{tour.reclone}
bos@91 300 As an aside, it's often good practice to keep a ``pristine'' copy of a
bos@91 301 remote repository around, which you can then make temporary clones of
bos@91 302 to create sandboxes for each task you want to work on. This lets you
bos@91 303 work on multiple tasks in parallel, each isolated from the others
bos@91 304 until it's complete and you're ready to integrate it back. Because
bos@91 305 local clones are so cheap, there's almost no overhead to cloning and
bos@91 306 destroying repositories whenever you want.
bos@91 307
bos@91 308 In our \dirname{my-hello} repository, we have a file
bos@91 309 \filename{hello.c} that contains the classic ``hello, world'' program.
bos@91 310 Let's use the ancient and venerable \command{sed} command to edit this
bos@91 311 file so that it prints a second line of output. (I'm only using
bos@91 312 \command{sed} to do this because it's easy to write a scripted example
bos@91 313 this way. Since you're not under the same constraint, you probably
bos@91 314 won't want to use \command{sed}; simply use your preferred text editor to
bos@91 315 do the same thing.)
bos@91 316 \interaction{tour.sed}
bos@91 317
bos@91 318 Mercurial's \hgcmd{status} command will tell us what Mercurial knows
bos@91 319 about the files in the repository.
bos@91 320 \interaction{tour.status}
bos@91 321 The \hgcmd{status} command prints no output for some files, but a line
bos@91 322 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell
bos@91 323 it to, \hgcmd{status} will not print any output for files that have
bos@91 324 not been modified.
bos@91 325
bos@91 326 The ``\texttt{M}'' indicates that Mercurial has noticed that we
bos@91 327 modified \filename{hello.c}. Notice that we didn't need to
bos@91 328 \emph{inform} Mercurial that we were going to modify the file before
bos@91 329 we started, or that we had modified the file after we were done; it
bos@91 330 was able to figure this out itself.
bos@91 331
bos@91 332 It's a little bit helpful to know that we've modified
bos@91 333 \filename{hello.c}, but we might prefer to know exactly \emph{what}
bos@91 334 changes we've made to it. To do this, we use the \hgcmd{diff}
bos@91 335 command.
bos@91 336 \interaction{tour.diff}
bos@91 337
bos@91 338 \section{Recording changes in a new changeset}
bos@91 339
bos@91 340 We can modify files, build and test our changes, and use
bos@91 341 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're
bos@91 342 satisfied with what we've done and arrive at a natural stopping point
bos@91 343 where we want to record our work in a new changeset.
bos@91 344
bos@91 345 The \hgcmd{commit} command lets us create a new changeset; we'll
bos@91 346 usually refer to this as ``making a commit'' or ``committing''.
bos@91 347
bos@91 348 \subsection{Writing a commit message}
bos@91 349
bos@91 350 When we commit a change, Mercurial drops us into a text editor, to
bos@91 351 enter a message that will describe the modifications we've made in
bos@91 352 this changeset. This is called the \emph{commit message}. It will be
bos@91 353 a record for readers of what we did and why, and it will be printed by
bos@91 354 \hgcmd{log} after we've finished committing.
bos@91 355 \interaction{tour.commit}
bos@91 356
bos@91 357 The editor that the \hgcmd{commit} command drops us into will contain
bos@91 358 an empty line, followed by a number of lines starting with
bos@91 359 ``\texttt{HG:}''.
bos@91 360 \begin{codesample2}
bos@91 361 \emph{empty line}
bos@91 362 HG: changed hello.c
bos@91 363 \end{codesample2}
bos@91 364 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
bos@91 365 them only to tell us which files it's recording changes to. Modifying
bos@91 366 or deleting these lines has no effect.
bos@91 367
bos@91 368 \subsection{Writing a good commit message}
bos@91 369
bos@91 370 Since \hgcmd{log} only prints the first line of a commit message by
bos@91 371 default, it's best to write a commit message whose first line stands
bos@91 372 alone. Here's a real example of a commit message that \emph{doesn't}
bos@91 373 follow this guideline, and hence has a summary that is not readable.
bos@91 374 \begin{codesample2}
bos@91 375 changeset: 73:584af0e231be
bos@91 376 user: Censored Person <censored.person@example.org>
bos@91 377 date: Tue Sep 26 21:37:07 2006 -0700
bos@91 378 summary: include buildmeister/commondefs. Add an exports and install
bos@91 379 \end{codesample2}
bos@91 380
bos@91 381 As far as the remainder of the contents of the commit message are
bos@91 382 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
bos@91 383 interpret or care about the contents of the commit message, though
bos@91 384 your project may have policies that dictate a certain kind of
bos@91 385 formatting.
bos@91 386
bos@91 387 My personal preference is for short, but informative, commit messages
bos@91 388 that tell me something that I can't figure out with a quick glance at
bos@91 389 the output of \hgcmdargs{log}{--patch}.
bos@91 390
bos@91 391 \subsection{Aborting a commit}
bos@91 392
bos@91 393 If you decide that you don't want to commit while in the middle of
bos@91 394 editing a commit message, simply exit from your editor without saving
bos@91 395 the file that it's editing. This will cause nothing to happen to
bos@91 396 either the repository or the working directory.
bos@91 397
bos@91 398 If we run the \hgcmd{commit} command without any arguments, it records
bos@91 399 all of the changes we've made, as reported by \hgcmd{status} and
bos@91 400 \hgcmd{diff}.
bos@91 401
bos@91 402 \subsection{Admiring our new handywork}
bos@91 403
bos@91 404 Once we've finished the commit, we can use the \hgcmd{tip} command to
bos@91 405 display the changeset we just created. This command produces output
bos@91 406 that is identical to \hgcmd{log}, but it only displays the newest
bos@91 407 revision in the repository.
bos@91 408 \interaction{tour.tip}
bos@91 409 We refer to the newest revision in the repository as the tip revision,
bos@91 410 or simply the tip.
bos@91 411
bos@91 412 \section{Sharing changes}
bos@91 413
bos@91 414 We mentioned earlier that repositories in Mercurial are
bos@91 415 self-contained. This means that the changeset we just created exists
bos@91 416 only in our \dirname{my-hello} repository. Let's look at a few ways
bos@91 417 that we can propagate this change into other repositories.
bos@91 418
bos@91 419 \subsection{Pulling changes from another repository}
bos@91 420 \label{sec:tour:pull}
bos@91 421
bos@91 422 To get started, let's clone our original \dirname{hello} repository,
bos@91 423 which does not contain the change we just committed. We'll call our
bos@91 424 temporary repository \dirname{hello-pull}.
bos@91 425 \interaction{tour.clone-pull}
bos@91 426
bos@91 427 We'll use the \hgcmd{pull} command to bring changes from
bos@91 428 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
bos@91 429 pulling unknown changes into a repository is a somewhat scary
bos@91 430 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
bos@91 431 what changes the \hgcmd{pull} command \emph{would} pull into the
bos@91 432 repository, without actually pulling the changes in.
bos@91 433 \interaction{tour.incoming}
bos@91 434 (Of course, someone could cause more changesets to appear in the
bos@91 435 repository that we ran \hgcmd{incoming} in, before we get a chance to
bos@91 436 \hgcmd{pull} the changes, so that we could end up pulling changes that we
bos@91 437 didn't expect.)
bos@91 438
bos@91 439 Bringing changes into a repository is a simple matter of running the
bos@91 440 \hgcmd{pull} command, and telling it which repository to pull from.
bos@91 441 \interaction{tour.pull}
bos@91 442 As you can see from the before-and-after output of \hgcmd{tip}, we
bos@91 443 have successfully pulled changes into our repository. There remains
bos@92 444 one step before we can see these changes in the working directory.
bos@92 445
bos@92 446 \subsection{Updating the working directory}
bos@92 447
bos@92 448 We have so far glossed over the relationship between a repository and
bos@91 449 its working directory. The \hgcmd{pull} command that we ran in
bos@91 450 section~\ref{sec:tour:pull} brought changes into the repository, but
bos@91 451 if we check, there's no sign of those changes in the working
bos@91 452 directory. This is because \hgcmd{pull} does not (by default) touch
bos@91 453 the working directory. Instead, we use the \hgcmd{update} command to
bos@91 454 do this.
bos@91 455 \interaction{tour.update}
bos@91 456
bos@91 457 It might seem a bit strange that \hgcmd{pull} doesn't update the
bos@91 458 working directory automatically. There's actually a good reason for
bos@91 459 this: you can use \hgcmd{update} to update the working directory to
bos@91 460 the state it was in at \emph{any revision} in the history of the
bos@91 461 repository. If you had the working directory updated to an old
bos@91 462 revision---to hunt down the origin of a bug, say---and ran a
bos@91 463 \hgcmd{pull} which automatically updated the working directory to a
bos@91 464 new revision, you might not be terribly happy.
bos@91 465
bos@91 466 However, since pull-then-update is such a common thing to do,
bos@91 467 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
bos@91 468 option to \hgcmd{pull}.
bos@91 469 \begin{codesample2}
bos@91 470 hg pull -u
bos@91 471 \end{codesample2}
bos@92 472 If you look back at the output of \hgcmd{pull} in
bos@92 473 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
bos@92 474 you can see that it printed a helpful reminder that we'd have to take
bos@92 475 an explicit step to update the working directory:
bos@92 476 \begin{codesample2}
bos@92 477 (run 'hg update' to get a working copy)
bos@92 478 \end{codesample2}
bos@91 479
bos@91 480 To find out what revision the working directory is at, use the
bos@91 481 \hgcmd{parents} command.
bos@91 482 \interaction{tour.parents}
bos@91 483 To update the working directory to a particular revision, give a
bos@91 484 revision number or changeset~ID to the \hgcmd{update} command.
bos@91 485 \interaction{tour.older}
bos@91 486 If you omit an explicit revision, \hgcmd{update} will update to the
bos@94 487 tip revision, as shown by the second call to \hgcmd{update} in the
bos@94 488 example above.
bos@91 489
bos@92 490 \subsection{Pushing changes to another repository}
bos@92 491
bos@92 492 Mercurial lets us push changes to another repository, from the
bos@92 493 repository we're currently visiting. As with the example of
bos@92 494 \hgcmd{pull} above, we'll create a temporary repository to push our
bos@92 495 changes into.
bos@92 496 \interaction{tour.clone-push}
bos@92 497 The \hgcmd{outgoing} command tells us what changes would be pushed
bos@92 498 into another repository.
bos@92 499 \interaction{tour.outgoing}
bos@92 500 And the \hgcmd{push} command does the actual push.
bos@92 501 \interaction{tour.push}
bos@92 502 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
bos@92 503 working directory in the repository that it's pushing changes into.
bos@92 504 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
bos@92 505 option that updates the other repository's working directory.)
bos@92 506
bos@92 507 What happens if we try to pull or push changes and the receiving
bos@92 508 repository already has those changes? Nothing too exciting.
bos@92 509 \interaction{tour.push.nothing}
bos@92 510
bos@93 511 \subsection{Sharing changes over a network}
bos@93 512
bos@93 513 The commands we have covered in the previous few sections are not
bos@93 514 limited to working with local repositories. Each works in exactly the
bos@93 515 same fashion over a network connection; simply pass in a URL instead
bos@93 516 of a local path.
bos@93 517 \interaction{tour.outgoing.net}
bos@93 518 In this example, we can see what changes we could push to the remote
bos@93 519 repository, but the repository is understandably not set up to let
bos@93 520 anonymous users push to it.
bos@93 521 \interaction{tour.push.net}
bos@93 522
bos@84 523 %%% Local Variables:
bos@84 524 %%% mode: latex
bos@84 525 %%% TeX-master: "00book"
bos@84 526 %%% End: