hgbook
changeset 95:47ea206351d5
Split tour into two sections.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Fri Oct 13 14:00:06 2006 -0700 (2006-10-13) |
parents | 0b97b0bdc830 |
children | 7d7ddc3a57af |
files | en/00book.tex en/Makefile en/tour-basic.tex en/tour-merge.tex en/tour.tex |
line diff
1.1 --- a/en/00book.tex Fri Oct 13 13:55:06 2006 -0700 1.2 +++ b/en/00book.tex Fri Oct 13 14:00:06 2006 -0700 1.3 @@ -38,7 +38,8 @@ 1.4 \include{preface} 1.5 \include{intro} 1.6 %\include{concepts} 1.7 -\include{tour} 1.8 +\include{tour-basic} 1.9 +\include{tour-merge} 1.10 \include{daily} 1.11 \include{hook} 1.12 \include{template}
2.1 --- a/en/Makefile Fri Oct 13 13:55:06 2006 -0700 2.2 +++ b/en/Makefile Fri Oct 13 14:00:06 2006 -0700 2.3 @@ -15,7 +15,8 @@ 2.4 preface.tex \ 2.5 srcinstall.tex \ 2.6 template.tex \ 2.7 - tour.tex 2.8 + tour-basic.tex \ 2.9 + tour-merge.tex 2.10 2.11 image-sources := \ 2.12 mq-stack.svg
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 3.2 +++ b/en/tour-basic.tex Fri Oct 13 14:00:06 2006 -0700 3.3 @@ -0,0 +1,519 @@ 3.4 +\chapter{A tour of Mercurial: the basics} 3.5 +\label{chap:tour-basic} 3.6 + 3.7 +\section{Installing Mercurial on your system} 3.8 +\label{sec:tour:install} 3.9 + 3.10 +Prebuilt binary packages of Mercurial are available for every popular 3.11 +operating system. These make it easy to start using Mercurial on your 3.12 +computer immediately. 3.13 + 3.14 +\subsection{Linux} 3.15 + 3.16 +Because each Linux distribution has its own packaging tools, policies, 3.17 +and rate of development, it's difficult to give a comprehensive set of 3.18 +instructions on how to install Mercurial binaries. The version of 3.19 +Mercurial that you will end up with can vary depending on how active 3.20 +the person is who maintains the package for your distribution. 3.21 + 3.22 +To keep things simple, I will focus on installing Mercurial from the 3.23 +command line under the most popular Linux distributions. Most of 3.24 +these distributions provide graphical package managers that will let 3.25 +you install Mercurial with a single click; the package name to look 3.26 +for is \texttt{mercurial}. 3.27 + 3.28 +\begin{itemize} 3.29 +\item[Debian] 3.30 + \begin{codesample4} 3.31 + apt-get install mercurial 3.32 + \end{codesample4} 3.33 + 3.34 +\item[Fedora Core] 3.35 + \begin{codesample4} 3.36 + yum install mercurial 3.37 + \end{codesample4} 3.38 + 3.39 +\item[Gentoo] 3.40 + \begin{codesample4} 3.41 + emerge mercurial 3.42 + \end{codesample4} 3.43 + 3.44 +\item[OpenSUSE] 3.45 + \begin{codesample4} 3.46 + yum install mercurial 3.47 + \end{codesample4} 3.48 + 3.49 +\item[Ubuntu] Ubuntu's Mercurial package is particularly old, and you 3.50 + should not use it. If you know how, you can rebuild and install the 3.51 + Debian package. It's probably easier to build Mercurial from source 3.52 + and simply run that; see section~\ref{sec:srcinstall:unixlike} for 3.53 + details. 3.54 +\end{itemize} 3.55 + 3.56 +\subsection{Mac OS X} 3.57 + 3.58 +Lee Cantey publishes an installer of Mercurial for Mac OS~X at 3.59 +\url{http://mercurial.berkwood.com}. This package works on both 3.60 +Intel-~and Power-based Macs. Before you can use it, you must install 3.61 +a compatible version of Universal MacPython~\cite{web:macpython}. This 3.62 +is easy to do; simply follow the instructions on Lee's site. 3.63 + 3.64 +\subsection{Solaris} 3.65 + 3.66 +XXX. 3.67 + 3.68 +\subsection{Windows} 3.69 + 3.70 +Lee Cantey publishes an installer of Mercurial for Windows at 3.71 +\url{http://mercurial.berkwood.com}. This package has no external 3.72 +dependencies; it ``just works''. 3.73 + 3.74 +\begin{note} 3.75 + The Windows version of Mercurial does not automatically convert line 3.76 + endings between Windows and Unix styles. If you want to share work 3.77 + with Unix users, you must do a little additional configuration 3.78 + work. XXX Flesh this out. 3.79 +\end{note} 3.80 + 3.81 +\section{Getting started} 3.82 + 3.83 +To begin, we'll use the \hgcmd{version} command to find out whether 3.84 +Mercurial is actually installed properly. The actual version 3.85 +information that it prints isn't so important; it's whether it prints 3.86 +anything at all that we care about. 3.87 +\interaction{tour.version} 3.88 + 3.89 +\subsection{Built-in help} 3.90 + 3.91 +Mercurial provides a built-in help system. This invaluable for those 3.92 +times when you find yourself stuck trying to remember how to run a 3.93 +command. If you are completely stuck, simply run \hgcmd{help}; it 3.94 +will print a brief list of commands, along with a description of what 3.95 +each does. If you ask for help on a specific command (as below), it 3.96 +prints more detailed information. 3.97 +\interaction{tour.help} 3.98 +For a more impressive level of detail (which you won't usually need) 3.99 +run \hgcmdargs{help}{\hggopt{-v}}. The \hggopt{-v} option is short 3.100 +for \hggopt{--verbose}, and tells Mercurial to print more information 3.101 +than it usually would. 3.102 + 3.103 +\section{Working with a repository} 3.104 + 3.105 +In Mercurial, everything happens inside a \emph{repository}. The 3.106 +repository for a project contains all of the files that ``belong to'' 3.107 +that project, along with a historical record of the project's files. 3.108 + 3.109 +There's nothing particularly magical about a repository; it is simply 3.110 +a directory tree in your filesystem that Mercurial treats as special. 3.111 +You can rename delete a repository any time you like, using either the 3.112 +command line or your file browser. 3.113 + 3.114 +\subsection{Making a local copy of a repository} 3.115 + 3.116 +\emph{Copying} a repository is just a little bit special. While you 3.117 +could use a normal file copying command to make a copy of a 3.118 +repository, it's best to use a built-in command that Mercurial 3.119 +provides. This command is called \hgcmd{clone}, because it creates an 3.120 +identical copy of an existing repository. 3.121 +\interaction{tour.clone} 3.122 +If our clone succeeded, we should now have a local directory called 3.123 +\dirname{hello}. This directory will contain some files. 3.124 +\interaction{tour.ls} 3.125 +These files have the same contents and history in our repository as 3.126 +they do in the repository we cloned. 3.127 + 3.128 +Every Mercurial repository is complete, self-contained, and 3.129 +independent. It contains its own private copy of a project's files 3.130 +and history. A cloned repository remembers the location of the 3.131 +repository it was cloned from, but it does not communicate with that 3.132 +repository, or any other, unless you tell it to. 3.133 + 3.134 +What this means for now is that we're free to experiment with our 3.135 +repository, safe in the knowledge that it's a private ``sandbox'' that 3.136 +won't affect anyone else. 3.137 + 3.138 +\subsection{What's in a repository?} 3.139 + 3.140 +When we take a more detailed look inside a repository, we can see that 3.141 +it contains a directory named \dirname{.hg}. This is where Mercurial 3.142 +keeps all of its metadata for the repository. 3.143 +\interaction{tour.ls-a} 3.144 + 3.145 +The contents of the \dirname{.hg} directory and its subdirectories are 3.146 +private to Mercurial. Every other file and directory in the 3.147 +repository is yours to do with as you please. 3.148 + 3.149 +To introduce a little terminology, the \dirname{.hg} directory is the 3.150 +``real'' repository, and all of the files and directories that coexist 3.151 +with it are said to live in the \emph{working directory}. An easy way 3.152 +to remember the distinction is that the \emph{repository} contains the 3.153 +\emph{history} of your project, while the \emph{working directory} 3.154 +contains a \emph{snapshot} of your project at a particular point in 3.155 +history. 3.156 + 3.157 +\section{A tour through history} 3.158 + 3.159 +One of the first things we might want to do with a new, unfamiliar 3.160 +repository is understand its history. The \hgcmd{log} command gives 3.161 +us a view of history. 3.162 +\interaction{tour.log} 3.163 +By default, this command prints a brief paragraph of output for each 3.164 +change to the project that was recorded. In Mercurial terminology, we 3.165 +call each of these recorded events a \emph{changeset}, because it can 3.166 +contain a record of changes to several files. 3.167 + 3.168 +The fields in a record of output from \hgcmd{log} are as follows. 3.169 +\begin{itemize} 3.170 +\item[\texttt{changeset}] This field has the format of a number, 3.171 + followed by a colon, followed by a hexadecimal string. These are 3.172 + \emph{identifiers} for the changeset. There are two identifiers 3.173 + because the number is shorter and easier to type than the hex 3.174 + string. 3.175 +\item[\texttt{user}] The identity of the person who created the 3.176 + changeset. This is a free-form field, but it most often contains a 3.177 + person's name and email address. 3.178 +\item[\texttt{date}] The date and time on which the changeset was 3.179 + created, and the timezone in which it was created. (Thef date and 3.180 + time are local to that timezone; they display what time and date it 3.181 + was for the person who created the changeset.) 3.182 +\item[\texttt{summary}] The first line of the text message that the 3.183 + creator of the changeset entered to describe the changeset. 3.184 +\end{itemize} 3.185 +The default output printed by \hgcmd{log} is purely a summary; it is 3.186 +missing a lot of detail. 3.187 + 3.188 +\subsection{Changesets, revisions, and identification} 3.189 + 3.190 +English being a notoriously sloppy language, we have a variety of 3.191 +terms that have the same meaning. If you are talking about Mercurial 3.192 +history with other people, you will find that the word ``changeset'' 3.193 +is often compressed to ``change'' or ``cset'', and sometimes a 3.194 +changeset is referred to as a ``revision'' or a ``rev''. 3.195 + 3.196 +While it doesn't matter what \emph{word} you use to refer to the 3.197 +concept of ``a~changeset'', the \emph{identifier} that you use to 3.198 +refer to ``a~\emph{specific} changeset'' is of great importance. 3.199 +Recall that the \texttt{changeset} field in the output from 3.200 +\hgcmd{log} identifies a changeset using both a number and a 3.201 +hexadecimal string. The number is \emph{only valid in that 3.202 + repository}, while the hex string is the \emph{permanent, unchanging 3.203 + identifier} that will always identify that changeset in every copy 3.204 +of the repository. 3.205 + 3.206 +This distinction is important. If you send someone an email talking 3.207 +about ``revision~33'', there's a high likelihood that their 3.208 +revision~33 will \emph{not be the same} as yours. The reason for this 3.209 +is that a revision number depends on the order in which changes 3.210 +arrived in a repository, and there is no guarantee that the same 3.211 +changes will happen in the same order in different repositories. 3.212 +Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, 3.213 +while in another as $1,0,2$. 3.214 + 3.215 +Mercurial uses revision numbers purely as a convenient shorthand. If 3.216 +you need to discuss a changeset with someone, or make a record of a 3.217 +changeset for some other reason (for example, in a bug report), use 3.218 +the hexadecimal identifier. 3.219 + 3.220 +\subsection{Viewing specific revisions} 3.221 + 3.222 +To narrow the output of \hgcmd{log} down to a single revision, use the 3.223 +\hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a 3.224 +revision number or a long-form changeset identifier, and you can 3.225 +provide as many revisions as you want. \interaction{tour.log-r} 3.226 + 3.227 +If you want to see the history of several revisions without having to 3.228 +list each one, you can use \emph{range notation}; this lets you 3.229 +express the idea ``I want all revisions between $a$ and $b$, 3.230 +inclusive''. 3.231 +\interaction{tour.log.range} 3.232 +Mercurial also honours the order in which you specify revisions, so 3.233 +\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} 3.234 +prints $4,3,2$. 3.235 + 3.236 +\subsection{More detailed information} 3.237 + 3.238 +While the summary information printed by \hgcmd{log} is useful if you 3.239 +already know what you're looking for, you may need to see a complete 3.240 +description of the change, or a list of the files changed, if you're 3.241 +trying to decide whether a changeset is the one you're looking for. 3.242 +The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) 3.243 +option gives you this extra detail. 3.244 +\interaction{tour.log-v} 3.245 + 3.246 +If you want to see both the description and content of a change, add 3.247 +the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays 3.248 +the content of a change as a \emph{unified diff} (if you've never seen 3.249 +a unified diff before, see section~\ref{sec:mq:patch} for an overview). 3.250 +\interaction{tour.log-vp} 3.251 + 3.252 +\section{All about command options} 3.253 + 3.254 +Let's take a brief break from exploring Mercurial commands to discuss 3.255 +a pattern in the way that they work; you may find this useful to keep 3.256 +in mind as we continiue our tour. 3.257 + 3.258 +Mercurial has a consistent and straightforward approach to dealing 3.259 +with the options that you can pass to commands. It follows the 3.260 +conventions for options that are common to modern Linux and Unix 3.261 +systems. 3.262 +\begin{itemize} 3.263 +\item Every option has a long name. For example, as we've already 3.264 + seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. 3.265 +\item Most options have short names, too. Instead of 3.266 + \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that 3.267 + some options don't have short names is that the options in question 3.268 + are rarely used.) 3.269 +\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), 3.270 + while short options start with one (e.g.~\hgopt{log}{-r}). 3.271 +\item Option naming and usage is consistent across commands. For 3.272 + example, every command that lets you specify a changeset~ID or 3.273 + revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} 3.274 + arguments. 3.275 +\end{itemize} 3.276 +In the examples throughout this book, I use short options instead of 3.277 +long. This just reflects my own preference, so don't read anything 3.278 +significant into it. 3.279 + 3.280 +Most commands that print output of some kind will print more output 3.281 +when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less 3.282 +when passed \hggopt{-q} (or \hggopt{--quiet}). 3.283 + 3.284 +\section{Making and reviewing changes} 3.285 + 3.286 +Now that we have a grasp of viewing history in Mercurial, let's take a 3.287 +look at making some changes and examining them. 3.288 + 3.289 +The first thing we'll do is isolate our experiment in a repository of 3.290 +its own. We use the \hgcmd{clone} command, but we don't need to 3.291 +clone a copy of the remote repository. Since we already have a copy 3.292 +of it locally, we can just clone that instead. This is much faster 3.293 +than cloning over the network, and cloning a local repository uses 3.294 +less disk space in most cases, too. 3.295 +\interaction{tour.reclone} 3.296 +As an aside, it's often good practice to keep a ``pristine'' copy of a 3.297 +remote repository around, which you can then make temporary clones of 3.298 +to create sandboxes for each task you want to work on. This lets you 3.299 +work on multiple tasks in parallel, each isolated from the others 3.300 +until it's complete and you're ready to integrate it back. Because 3.301 +local clones are so cheap, there's almost no overhead to cloning and 3.302 +destroying repositories whenever you want. 3.303 + 3.304 +In our \dirname{my-hello} repository, we have a file 3.305 +\filename{hello.c} that contains the classic ``hello, world'' program. 3.306 +Let's use the ancient and venerable \command{sed} command to edit this 3.307 +file so that it prints a second line of output. (I'm only using 3.308 +\command{sed} to do this because it's easy to write a scripted example 3.309 +this way. Since you're not under the same constraint, you probably 3.310 +won't want to use \command{sed}; simply use your preferred text editor to 3.311 +do the same thing.) 3.312 +\interaction{tour.sed} 3.313 + 3.314 +Mercurial's \hgcmd{status} command will tell us what Mercurial knows 3.315 +about the files in the repository. 3.316 +\interaction{tour.status} 3.317 +The \hgcmd{status} command prints no output for some files, but a line 3.318 +starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell 3.319 +it to, \hgcmd{status} will not print any output for files that have 3.320 +not been modified. 3.321 + 3.322 +The ``\texttt{M}'' indicates that Mercurial has noticed that we 3.323 +modified \filename{hello.c}. Notice that we didn't need to 3.324 +\emph{inform} Mercurial that we were going to modify the file before 3.325 +we started, or that we had modified the file after we were done; it 3.326 +was able to figure this out itself. 3.327 + 3.328 +It's a little bit helpful to know that we've modified 3.329 +\filename{hello.c}, but we might prefer to know exactly \emph{what} 3.330 +changes we've made to it. To do this, we use the \hgcmd{diff} 3.331 +command. 3.332 +\interaction{tour.diff} 3.333 + 3.334 +\section{Recording changes in a new changeset} 3.335 + 3.336 +We can modify files, build and test our changes, and use 3.337 +\hgcmd{status} and \hgcmd{diff} to review our changes, until we're 3.338 +satisfied with what we've done and arrive at a natural stopping point 3.339 +where we want to record our work in a new changeset. 3.340 + 3.341 +The \hgcmd{commit} command lets us create a new changeset; we'll 3.342 +usually refer to this as ``making a commit'' or ``committing''. 3.343 + 3.344 +\subsection{Writing a commit message} 3.345 + 3.346 +When we commit a change, Mercurial drops us into a text editor, to 3.347 +enter a message that will describe the modifications we've made in 3.348 +this changeset. This is called the \emph{commit message}. It will be 3.349 +a record for readers of what we did and why, and it will be printed by 3.350 +\hgcmd{log} after we've finished committing. 3.351 +\interaction{tour.commit} 3.352 + 3.353 +The editor that the \hgcmd{commit} command drops us into will contain 3.354 +an empty line, followed by a number of lines starting with 3.355 +``\texttt{HG:}''. 3.356 +\begin{codesample2} 3.357 + \emph{empty line} 3.358 + HG: changed hello.c 3.359 +\end{codesample2} 3.360 +Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses 3.361 +them only to tell us which files it's recording changes to. Modifying 3.362 +or deleting these lines has no effect. 3.363 + 3.364 +\subsection{Writing a good commit message} 3.365 + 3.366 +Since \hgcmd{log} only prints the first line of a commit message by 3.367 +default, it's best to write a commit message whose first line stands 3.368 +alone. Here's a real example of a commit message that \emph{doesn't} 3.369 +follow this guideline, and hence has a summary that is not readable. 3.370 +\begin{codesample2} 3.371 + changeset: 73:584af0e231be 3.372 + user: Censored Person <censored.person@example.org> 3.373 + date: Tue Sep 26 21:37:07 2006 -0700 3.374 + summary: include buildmeister/commondefs. Add an exports and install 3.375 +\end{codesample2} 3.376 + 3.377 +As far as the remainder of the contents of the commit message are 3.378 +concerned, there are no hard-and-fast rules. Mercurial itself doesn't 3.379 +interpret or care about the contents of the commit message, though 3.380 +your project may have policies that dictate a certain kind of 3.381 +formatting. 3.382 + 3.383 +My personal preference is for short, but informative, commit messages 3.384 +that tell me something that I can't figure out with a quick glance at 3.385 +the output of \hgcmdargs{log}{--patch}. 3.386 + 3.387 +\subsection{Aborting a commit} 3.388 + 3.389 +If you decide that you don't want to commit while in the middle of 3.390 +editing a commit message, simply exit from your editor without saving 3.391 +the file that it's editing. This will cause nothing to happen to 3.392 +either the repository or the working directory. 3.393 + 3.394 +If we run the \hgcmd{commit} command without any arguments, it records 3.395 +all of the changes we've made, as reported by \hgcmd{status} and 3.396 +\hgcmd{diff}. 3.397 + 3.398 +\subsection{Admiring our new handywork} 3.399 + 3.400 +Once we've finished the commit, we can use the \hgcmd{tip} command to 3.401 +display the changeset we just created. This command produces output 3.402 +that is identical to \hgcmd{log}, but it only displays the newest 3.403 +revision in the repository. 3.404 +\interaction{tour.tip} 3.405 +We refer to the newest revision in the repository as the tip revision, 3.406 +or simply the tip. 3.407 + 3.408 +\section{Sharing changes} 3.409 + 3.410 +We mentioned earlier that repositories in Mercurial are 3.411 +self-contained. This means that the changeset we just created exists 3.412 +only in our \dirname{my-hello} repository. Let's look at a few ways 3.413 +that we can propagate this change into other repositories. 3.414 + 3.415 +\subsection{Pulling changes from another repository} 3.416 +\label{sec:tour:pull} 3.417 + 3.418 +To get started, let's clone our original \dirname{hello} repository, 3.419 +which does not contain the change we just committed. We'll call our 3.420 +temporary repository \dirname{hello-pull}. 3.421 +\interaction{tour.clone-pull} 3.422 + 3.423 +We'll use the \hgcmd{pull} command to bring changes from 3.424 +\dirname{my-hello} into \dirname{hello-pull}. However, blindly 3.425 +pulling unknown changes into a repository is a somewhat scary 3.426 +prospect. Mercurial provides the \hgcmd{incoming} command to tell us 3.427 +what changes the \hgcmd{pull} command \emph{would} pull into the 3.428 +repository, without actually pulling the changes in. 3.429 +\interaction{tour.incoming} 3.430 +(Of course, someone could cause more changesets to appear in the 3.431 +repository that we ran \hgcmd{incoming} in, before we get a chance to 3.432 +\hgcmd{pull} the changes, so that we could end up pulling changes that we 3.433 +didn't expect.) 3.434 + 3.435 +Bringing changes into a repository is a simple matter of running the 3.436 +\hgcmd{pull} command, and telling it which repository to pull from. 3.437 +\interaction{tour.pull} 3.438 +As you can see from the before-and-after output of \hgcmd{tip}, we 3.439 +have successfully pulled changes into our repository. There remains 3.440 +one step before we can see these changes in the working directory. 3.441 + 3.442 +\subsection{Updating the working directory} 3.443 + 3.444 +We have so far glossed over the relationship between a repository and 3.445 +its working directory. The \hgcmd{pull} command that we ran in 3.446 +section~\ref{sec:tour:pull} brought changes into the repository, but 3.447 +if we check, there's no sign of those changes in the working 3.448 +directory. This is because \hgcmd{pull} does not (by default) touch 3.449 +the working directory. Instead, we use the \hgcmd{update} command to 3.450 +do this. 3.451 +\interaction{tour.update} 3.452 + 3.453 +It might seem a bit strange that \hgcmd{pull} doesn't update the 3.454 +working directory automatically. There's actually a good reason for 3.455 +this: you can use \hgcmd{update} to update the working directory to 3.456 +the state it was in at \emph{any revision} in the history of the 3.457 +repository. If you had the working directory updated to an old 3.458 +revision---to hunt down the origin of a bug, say---and ran a 3.459 +\hgcmd{pull} which automatically updated the working directory to a 3.460 +new revision, you might not be terribly happy. 3.461 + 3.462 +However, since pull-then-update is such a common thing to do, 3.463 +Mercurial lets you combine the two by passing the \hgopt{pull}{-u} 3.464 +option to \hgcmd{pull}. 3.465 +\begin{codesample2} 3.466 + hg pull -u 3.467 +\end{codesample2} 3.468 +If you look back at the output of \hgcmd{pull} in 3.469 +section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, 3.470 +you can see that it printed a helpful reminder that we'd have to take 3.471 +an explicit step to update the working directory: 3.472 +\begin{codesample2} 3.473 + (run 'hg update' to get a working copy) 3.474 +\end{codesample2} 3.475 + 3.476 +To find out what revision the working directory is at, use the 3.477 +\hgcmd{parents} command. 3.478 +\interaction{tour.parents} 3.479 +To update the working directory to a particular revision, give a 3.480 +revision number or changeset~ID to the \hgcmd{update} command. 3.481 +\interaction{tour.older} 3.482 +If you omit an explicit revision, \hgcmd{update} will update to the 3.483 +tip revision, as shown by the second call to \hgcmd{update} in the 3.484 +example above. 3.485 + 3.486 +\subsection{Pushing changes to another repository} 3.487 + 3.488 +Mercurial lets us push changes to another repository, from the 3.489 +repository we're currently visiting. As with the example of 3.490 +\hgcmd{pull} above, we'll create a temporary repository to push our 3.491 +changes into. 3.492 +\interaction{tour.clone-push} 3.493 +The \hgcmd{outgoing} command tells us what changes would be pushed 3.494 +into another repository. 3.495 +\interaction{tour.outgoing} 3.496 +And the \hgcmd{push} command does the actual push. 3.497 +\interaction{tour.push} 3.498 +As with \hgcmd{pull}, the \hgcmd{push} command does not update the 3.499 +working directory in the repository that it's pushing changes into. 3.500 +(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} 3.501 +option that updates the other repository's working directory.) 3.502 + 3.503 +What happens if we try to pull or push changes and the receiving 3.504 +repository already has those changes? Nothing too exciting. 3.505 +\interaction{tour.push.nothing} 3.506 + 3.507 +\subsection{Sharing changes over a network} 3.508 + 3.509 +The commands we have covered in the previous few sections are not 3.510 +limited to working with local repositories. Each works in exactly the 3.511 +same fashion over a network connection; simply pass in a URL instead 3.512 +of a local path. 3.513 +\interaction{tour.outgoing.net} 3.514 +In this example, we can see what changes we could push to the remote 3.515 +repository, but the repository is understandably not set up to let 3.516 +anonymous users push to it. 3.517 +\interaction{tour.push.net} 3.518 + 3.519 +%%% Local Variables: 3.520 +%%% mode: latex 3.521 +%%% TeX-master: "00book" 3.522 +%%% End:
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 4.2 +++ b/en/tour-merge.tex Fri Oct 13 14:00:06 2006 -0700 4.3 @@ -0,0 +1,64 @@ 4.4 +\chapter{A tour of Mercurial: merging work} 4.5 +\label{chap:tour-merge} 4.6 + 4.7 +We've now covered cloning a repository, making changes in a 4.8 +repository, and pulling or pushing changes from one repository into 4.9 +another. Our next step is \emph{merging} changes from separate 4.10 +repositories. 4.11 + 4.12 +\section{Merging streams of work} 4.13 + 4.14 +Merging is a fundamental part of working with a distributed revision 4.15 +control tool. 4.16 +\begin{itemize} 4.17 +\item Alice and Bob each have a personal copy of a repository for a 4.18 + project they're collaborating on. Alice fixes a bug in her 4.19 + repository; Bob adds a new feature in his. They want the shared 4.20 + repository to contain both the bug fix and the new feature. 4.21 +\item I frequently work on several different tasks for a single 4.22 + project at once, each safely isolated in its own repository. 4.23 + Working this way means that I often need to merge one piece of my 4.24 + own work with another. 4.25 +\end{itemize} 4.26 + 4.27 +Because merging is such a common thing to need to do, Mercurial makes 4.28 +it easy. Let's walk through the process. We'll begin by cloning yet 4.29 +another repository (see how often they spring up?) and making a change 4.30 +in it. 4.31 +\interaction{tour.merge.clone} 4.32 +We should now have two copies of \filename{hello.c} with different 4.33 +contents. 4.34 +\interaction{tour.merge.cat} 4.35 + 4.36 +We already know that pulling changes from our \dirname{my-hello} 4.37 +repository will have no effect on the working directory. 4.38 +\interaction{tour.merge.pull} 4.39 +However, the \hgcmd{pull} command says something about ``heads''. 4.40 + 4.41 +A head is a change that has no descendants. The tip revision is thus 4.42 +a head, but a repository can contain more than one head. We can view 4.43 +them using the \hgcmd{heads} command. 4.44 +\interaction{tour.merge.heads} 4.45 +What happens if we try to use the normal \hgcmd{update} command to 4.46 +update to the new tip? 4.47 +\interaction{tour.merge.update} 4.48 +Mercurial is telling us that the \hgcmd{update} command won't do a 4.49 +merge. Instead, we use the \hgcmd{merge} command to merge the two 4.50 +heads. 4.51 +\interaction{tour.merge.merge} 4.52 +This updates the working directory so that it contains changes from 4.53 +both heads, which is reflected in both the output of \hgcmd{parents} 4.54 +and the contents of \filename{hello.c}. 4.55 +\interaction{tour.merge.parents} 4.56 +Whenever we've done a merge, \hgcmd{parents} will display two parents 4.57 +until we \hgcmd{commit} the results of the merge. 4.58 +\interaction{tour.merge.commit} 4.59 +We now have a new tip revision; notice that it has \emph{both} of 4.60 +our former heads as its parents. These are the same revisions that 4.61 +were previously displayed by \hgcmd{parents}. 4.62 +\interaction{tour.merge.tip} 4.63 + 4.64 +%%% Local Variables: 4.65 +%%% mode: latex 4.66 +%%% TeX-master: "00book" 4.67 +%%% End:
5.1 --- a/en/tour.tex Fri Oct 13 13:55:06 2006 -0700 5.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 5.3 @@ -1,576 +0,0 @@ 5.4 -\chapter{A lightning tour of Mercurial} 5.5 -\label{chap:tour} 5.6 - 5.7 -\section{Installing Mercurial on your system} 5.8 -\label{sec:tour:install} 5.9 - 5.10 -Prebuilt binary packages of Mercurial are available for every popular 5.11 -operating system. These make it easy to start using Mercurial on your 5.12 -computer immediately. 5.13 - 5.14 -\subsection{Linux} 5.15 - 5.16 -Because each Linux distribution has its own packaging tools, policies, 5.17 -and rate of development, it's difficult to give a comprehensive set of 5.18 -instructions on how to install Mercurial binaries. The version of 5.19 -Mercurial that you will end up with can vary depending on how active 5.20 -the person is who maintains the package for your distribution. 5.21 - 5.22 -To keep things simple, I will focus on installing Mercurial from the 5.23 -command line under the most popular Linux distributions. Most of 5.24 -these distributions provide graphical package managers that will let 5.25 -you install Mercurial with a single click; the package name to look 5.26 -for is \texttt{mercurial}. 5.27 - 5.28 -\begin{itemize} 5.29 -\item[Debian] 5.30 - \begin{codesample4} 5.31 - apt-get install mercurial 5.32 - \end{codesample4} 5.33 - 5.34 -\item[Fedora Core] 5.35 - \begin{codesample4} 5.36 - yum install mercurial 5.37 - \end{codesample4} 5.38 - 5.39 -\item[Gentoo] 5.40 - \begin{codesample4} 5.41 - emerge mercurial 5.42 - \end{codesample4} 5.43 - 5.44 -\item[OpenSUSE] 5.45 - \begin{codesample4} 5.46 - yum install mercurial 5.47 - \end{codesample4} 5.48 - 5.49 -\item[Ubuntu] Ubuntu's Mercurial package is particularly old, and you 5.50 - should not use it. If you know how, you can rebuild and install the 5.51 - Debian package. It's probably easier to build Mercurial from source 5.52 - and simply run that; see section~\ref{sec:srcinstall:unixlike} for 5.53 - details. 5.54 -\end{itemize} 5.55 - 5.56 -\subsection{Mac OS X} 5.57 - 5.58 -Lee Cantey publishes an installer of Mercurial for Mac OS~X at 5.59 -\url{http://mercurial.berkwood.com}. This package works on both 5.60 -Intel-~and Power-based Macs. Before you can use it, you must install 5.61 -a compatible version of Universal MacPython~\cite{web:macpython}. This 5.62 -is easy to do; simply follow the instructions on Lee's site. 5.63 - 5.64 -\subsection{Solaris} 5.65 - 5.66 -XXX. 5.67 - 5.68 -\subsection{Windows} 5.69 - 5.70 -Lee Cantey publishes an installer of Mercurial for Windows at 5.71 -\url{http://mercurial.berkwood.com}. This package has no external 5.72 -dependencies; it ``just works''. 5.73 - 5.74 -\begin{note} 5.75 - The Windows version of Mercurial does not automatically convert line 5.76 - endings between Windows and Unix styles. If you want to share work 5.77 - with Unix users, you must do a little additional configuration 5.78 - work. XXX Flesh this out. 5.79 -\end{note} 5.80 - 5.81 -\section{Getting started} 5.82 - 5.83 -To begin, we'll use the \hgcmd{version} command to find out whether 5.84 -Mercurial is actually installed properly. The actual version 5.85 -information that it prints isn't so important; it's whether it prints 5.86 -anything at all that we care about. 5.87 -\interaction{tour.version} 5.88 - 5.89 -\subsection{Built-in help} 5.90 - 5.91 -Mercurial provides a built-in help system. This invaluable for those 5.92 -times when you find yourself stuck trying to remember how to run a 5.93 -command. If you are completely stuck, simply run \hgcmd{help}; it 5.94 -will print a brief list of commands, along with a description of what 5.95 -each does. If you ask for help on a specific command (as below), it 5.96 -prints more detailed information. 5.97 -\interaction{tour.help} 5.98 -For a more impressive level of detail (which you won't usually need) 5.99 -run \hgcmdargs{help}{\hggopt{-v}}. The \hggopt{-v} option is short 5.100 -for \hggopt{--verbose}, and tells Mercurial to print more information 5.101 -than it usually would. 5.102 - 5.103 -\section{Working with a repository} 5.104 - 5.105 -In Mercurial, everything happens inside a \emph{repository}. The 5.106 -repository for a project contains all of the files that ``belong to'' 5.107 -that project, along with a historical record of the project's files. 5.108 - 5.109 -There's nothing particularly magical about a repository; it is simply 5.110 -a directory tree in your filesystem that Mercurial treats as special. 5.111 -You can rename delete a repository any time you like, using either the 5.112 -command line or your file browser. 5.113 - 5.114 -\subsection{Making a local copy of a repository} 5.115 - 5.116 -\emph{Copying} a repository is just a little bit special. While you 5.117 -could use a normal file copying command to make a copy of a 5.118 -repository, it's best to use a built-in command that Mercurial 5.119 -provides. This command is called \hgcmd{clone}, because it creates an 5.120 -identical copy of an existing repository. 5.121 -\interaction{tour.clone} 5.122 -If our clone succeeded, we should now have a local directory called 5.123 -\dirname{hello}. This directory will contain some files. 5.124 -\interaction{tour.ls} 5.125 -These files have the same contents and history in our repository as 5.126 -they do in the repository we cloned. 5.127 - 5.128 -Every Mercurial repository is complete, self-contained, and 5.129 -independent. It contains its own private copy of a project's files 5.130 -and history. A cloned repository remembers the location of the 5.131 -repository it was cloned from, but it does not communicate with that 5.132 -repository, or any other, unless you tell it to. 5.133 - 5.134 -What this means for now is that we're free to experiment with our 5.135 -repository, safe in the knowledge that it's a private ``sandbox'' that 5.136 -won't affect anyone else. 5.137 - 5.138 -\subsection{What's in a repository?} 5.139 - 5.140 -When we take a more detailed look inside a repository, we can see that 5.141 -it contains a directory named \dirname{.hg}. This is where Mercurial 5.142 -keeps all of its metadata for the repository. 5.143 -\interaction{tour.ls-a} 5.144 - 5.145 -The contents of the \dirname{.hg} directory and its subdirectories are 5.146 -private to Mercurial. Every other file and directory in the 5.147 -repository is yours to do with as you please. 5.148 - 5.149 -To introduce a little terminology, the \dirname{.hg} directory is the 5.150 -``real'' repository, and all of the files and directories that coexist 5.151 -with it are said to live in the \emph{working directory}. An easy way 5.152 -to remember the distinction is that the \emph{repository} contains the 5.153 -\emph{history} of your project, while the \emph{working directory} 5.154 -contains a \emph{snapshot} of your project at a particular point in 5.155 -history. 5.156 - 5.157 -\section{A tour through history} 5.158 - 5.159 -One of the first things we might want to do with a new, unfamiliar 5.160 -repository is understand its history. The \hgcmd{log} command gives 5.161 -us a view of history. 5.162 -\interaction{tour.log} 5.163 -By default, this command prints a brief paragraph of output for each 5.164 -change to the project that was recorded. In Mercurial terminology, we 5.165 -call each of these recorded events a \emph{changeset}, because it can 5.166 -contain a record of changes to several files. 5.167 - 5.168 -The fields in a record of output from \hgcmd{log} are as follows. 5.169 -\begin{itemize} 5.170 -\item[\texttt{changeset}] This field has the format of a number, 5.171 - followed by a colon, followed by a hexadecimal string. These are 5.172 - \emph{identifiers} for the changeset. There are two identifiers 5.173 - because the number is shorter and easier to type than the hex 5.174 - string. 5.175 -\item[\texttt{user}] The identity of the person who created the 5.176 - changeset. This is a free-form field, but it most often contains a 5.177 - person's name and email address. 5.178 -\item[\texttt{date}] The date and time on which the changeset was 5.179 - created, and the timezone in which it was created. (Thef date and 5.180 - time are local to that timezone; they display what time and date it 5.181 - was for the person who created the changeset.) 5.182 -\item[\texttt{summary}] The first line of the text message that the 5.183 - creator of the changeset entered to describe the changeset. 5.184 -\end{itemize} 5.185 -The default output printed by \hgcmd{log} is purely a summary; it is 5.186 -missing a lot of detail. 5.187 - 5.188 -\subsection{Changesets, revisions, and identification} 5.189 - 5.190 -English being a notoriously sloppy language, we have a variety of 5.191 -terms that have the same meaning. If you are talking about Mercurial 5.192 -history with other people, you will find that the word ``changeset'' 5.193 -is often compressed to ``change'' or ``cset'', and sometimes a 5.194 -changeset is referred to as a ``revision'' or a ``rev''. 5.195 - 5.196 -While it doesn't matter what \emph{word} you use to refer to the 5.197 -concept of ``a~changeset'', the \emph{identifier} that you use to 5.198 -refer to ``a~\emph{specific} changeset'' is of great importance. 5.199 -Recall that the \texttt{changeset} field in the output from 5.200 -\hgcmd{log} identifies a changeset using both a number and a 5.201 -hexadecimal string. The number is \emph{only valid in that 5.202 - repository}, while the hex string is the \emph{permanent, unchanging 5.203 - identifier} that will always identify that changeset in every copy 5.204 -of the repository. 5.205 - 5.206 -This distinction is important. If you send someone an email talking 5.207 -about ``revision~33'', there's a high likelihood that their 5.208 -revision~33 will \emph{not be the same} as yours. The reason for this 5.209 -is that a revision number depends on the order in which changes 5.210 -arrived in a repository, and there is no guarantee that the same 5.211 -changes will happen in the same order in different repositories. 5.212 -Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, 5.213 -while in another as $1,0,2$. 5.214 - 5.215 -Mercurial uses revision numbers purely as a convenient shorthand. If 5.216 -you need to discuss a changeset with someone, or make a record of a 5.217 -changeset for some other reason (for example, in a bug report), use 5.218 -the hexadecimal identifier. 5.219 - 5.220 -\subsection{Viewing specific revisions} 5.221 - 5.222 -To narrow the output of \hgcmd{log} down to a single revision, use the 5.223 -\hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a 5.224 -revision number or a long-form changeset identifier, and you can 5.225 -provide as many revisions as you want. \interaction{tour.log-r} 5.226 - 5.227 -If you want to see the history of several revisions without having to 5.228 -list each one, you can use \emph{range notation}; this lets you 5.229 -express the idea ``I want all revisions between $a$ and $b$, 5.230 -inclusive''. 5.231 -\interaction{tour.log.range} 5.232 -Mercurial also honours the order in which you specify revisions, so 5.233 -\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} 5.234 -prints $4,3,2$. 5.235 - 5.236 -\subsection{More detailed information} 5.237 - 5.238 -While the summary information printed by \hgcmd{log} is useful if you 5.239 -already know what you're looking for, you may need to see a complete 5.240 -description of the change, or a list of the files changed, if you're 5.241 -trying to decide whether a changeset is the one you're looking for. 5.242 -The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) 5.243 -option gives you this extra detail. 5.244 -\interaction{tour.log-v} 5.245 - 5.246 -If you want to see both the description and content of a change, add 5.247 -the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays 5.248 -the content of a change as a \emph{unified diff} (if you've never seen 5.249 -a unified diff before, see section~\ref{sec:mq:patch} for an overview). 5.250 -\interaction{tour.log-vp} 5.251 - 5.252 -\section{All about command options} 5.253 - 5.254 -Let's take a brief break from exploring Mercurial commands to discuss 5.255 -a pattern in the way that they work; you may find this useful to keep 5.256 -in mind as we continiue our tour. 5.257 - 5.258 -Mercurial has a consistent and straightforward approach to dealing 5.259 -with the options that you can pass to commands. It follows the 5.260 -conventions for options that are common to modern Linux and Unix 5.261 -systems. 5.262 -\begin{itemize} 5.263 -\item Every option has a long name. For example, as we've already 5.264 - seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. 5.265 -\item Most options have short names, too. Instead of 5.266 - \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that 5.267 - some options don't have short names is that the options in question 5.268 - are rarely used.) 5.269 -\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), 5.270 - while short options start with one (e.g.~\hgopt{log}{-r}). 5.271 -\item Option naming and usage is consistent across commands. For 5.272 - example, every command that lets you specify a changeset~ID or 5.273 - revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} 5.274 - arguments. 5.275 -\end{itemize} 5.276 -In the examples throughout this book, I use short options instead of 5.277 -long. This just reflects my own preference, so don't read anything 5.278 -significant into it. 5.279 - 5.280 -Most commands that print output of some kind will print more output 5.281 -when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less 5.282 -when passed \hggopt{-q} (or \hggopt{--quiet}). 5.283 - 5.284 -\section{Making and reviewing changes} 5.285 - 5.286 -Now that we have a grasp of viewing history in Mercurial, let's take a 5.287 -look at making some changes and examining them. 5.288 - 5.289 -The first thing we'll do is isolate our experiment in a repository of 5.290 -its own. We use the \hgcmd{clone} command, but we don't need to 5.291 -clone a copy of the remote repository. Since we already have a copy 5.292 -of it locally, we can just clone that instead. This is much faster 5.293 -than cloning over the network, and cloning a local repository uses 5.294 -less disk space in most cases, too. 5.295 -\interaction{tour.reclone} 5.296 -As an aside, it's often good practice to keep a ``pristine'' copy of a 5.297 -remote repository around, which you can then make temporary clones of 5.298 -to create sandboxes for each task you want to work on. This lets you 5.299 -work on multiple tasks in parallel, each isolated from the others 5.300 -until it's complete and you're ready to integrate it back. Because 5.301 -local clones are so cheap, there's almost no overhead to cloning and 5.302 -destroying repositories whenever you want. 5.303 - 5.304 -In our \dirname{my-hello} repository, we have a file 5.305 -\filename{hello.c} that contains the classic ``hello, world'' program. 5.306 -Let's use the ancient and venerable \command{sed} command to edit this 5.307 -file so that it prints a second line of output. (I'm only using 5.308 -\command{sed} to do this because it's easy to write a scripted example 5.309 -this way. Since you're not under the same constraint, you probably 5.310 -won't want to use \command{sed}; simply use your preferred text editor to 5.311 -do the same thing.) 5.312 -\interaction{tour.sed} 5.313 - 5.314 -Mercurial's \hgcmd{status} command will tell us what Mercurial knows 5.315 -about the files in the repository. 5.316 -\interaction{tour.status} 5.317 -The \hgcmd{status} command prints no output for some files, but a line 5.318 -starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell 5.319 -it to, \hgcmd{status} will not print any output for files that have 5.320 -not been modified. 5.321 - 5.322 -The ``\texttt{M}'' indicates that Mercurial has noticed that we 5.323 -modified \filename{hello.c}. Notice that we didn't need to 5.324 -\emph{inform} Mercurial that we were going to modify the file before 5.325 -we started, or that we had modified the file after we were done; it 5.326 -was able to figure this out itself. 5.327 - 5.328 -It's a little bit helpful to know that we've modified 5.329 -\filename{hello.c}, but we might prefer to know exactly \emph{what} 5.330 -changes we've made to it. To do this, we use the \hgcmd{diff} 5.331 -command. 5.332 -\interaction{tour.diff} 5.333 - 5.334 -\section{Recording changes in a new changeset} 5.335 - 5.336 -We can modify files, build and test our changes, and use 5.337 -\hgcmd{status} and \hgcmd{diff} to review our changes, until we're 5.338 -satisfied with what we've done and arrive at a natural stopping point 5.339 -where we want to record our work in a new changeset. 5.340 - 5.341 -The \hgcmd{commit} command lets us create a new changeset; we'll 5.342 -usually refer to this as ``making a commit'' or ``committing''. 5.343 - 5.344 -\subsection{Writing a commit message} 5.345 - 5.346 -When we commit a change, Mercurial drops us into a text editor, to 5.347 -enter a message that will describe the modifications we've made in 5.348 -this changeset. This is called the \emph{commit message}. It will be 5.349 -a record for readers of what we did and why, and it will be printed by 5.350 -\hgcmd{log} after we've finished committing. 5.351 -\interaction{tour.commit} 5.352 - 5.353 -The editor that the \hgcmd{commit} command drops us into will contain 5.354 -an empty line, followed by a number of lines starting with 5.355 -``\texttt{HG:}''. 5.356 -\begin{codesample2} 5.357 - \emph{empty line} 5.358 - HG: changed hello.c 5.359 -\end{codesample2} 5.360 -Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses 5.361 -them only to tell us which files it's recording changes to. Modifying 5.362 -or deleting these lines has no effect. 5.363 - 5.364 -\subsection{Writing a good commit message} 5.365 - 5.366 -Since \hgcmd{log} only prints the first line of a commit message by 5.367 -default, it's best to write a commit message whose first line stands 5.368 -alone. Here's a real example of a commit message that \emph{doesn't} 5.369 -follow this guideline, and hence has a summary that is not readable. 5.370 -\begin{codesample2} 5.371 - changeset: 73:584af0e231be 5.372 - user: Censored Person <censored.person@example.org> 5.373 - date: Tue Sep 26 21:37:07 2006 -0700 5.374 - summary: include buildmeister/commondefs. Add an exports and install 5.375 -\end{codesample2} 5.376 - 5.377 -As far as the remainder of the contents of the commit message are 5.378 -concerned, there are no hard-and-fast rules. Mercurial itself doesn't 5.379 -interpret or care about the contents of the commit message, though 5.380 -your project may have policies that dictate a certain kind of 5.381 -formatting. 5.382 - 5.383 -My personal preference is for short, but informative, commit messages 5.384 -that tell me something that I can't figure out with a quick glance at 5.385 -the output of \hgcmdargs{log}{--patch}. 5.386 - 5.387 -\subsection{Aborting a commit} 5.388 - 5.389 -If you decide that you don't want to commit while in the middle of 5.390 -editing a commit message, simply exit from your editor without saving 5.391 -the file that it's editing. This will cause nothing to happen to 5.392 -either the repository or the working directory. 5.393 - 5.394 -If we run the \hgcmd{commit} command without any arguments, it records 5.395 -all of the changes we've made, as reported by \hgcmd{status} and 5.396 -\hgcmd{diff}. 5.397 - 5.398 -\subsection{Admiring our new handywork} 5.399 - 5.400 -Once we've finished the commit, we can use the \hgcmd{tip} command to 5.401 -display the changeset we just created. This command produces output 5.402 -that is identical to \hgcmd{log}, but it only displays the newest 5.403 -revision in the repository. 5.404 -\interaction{tour.tip} 5.405 -We refer to the newest revision in the repository as the tip revision, 5.406 -or simply the tip. 5.407 - 5.408 -\section{Sharing changes} 5.409 - 5.410 -We mentioned earlier that repositories in Mercurial are 5.411 -self-contained. This means that the changeset we just created exists 5.412 -only in our \dirname{my-hello} repository. Let's look at a few ways 5.413 -that we can propagate this change into other repositories. 5.414 - 5.415 -\subsection{Pulling changes from another repository} 5.416 -\label{sec:tour:pull} 5.417 - 5.418 -To get started, let's clone our original \dirname{hello} repository, 5.419 -which does not contain the change we just committed. We'll call our 5.420 -temporary repository \dirname{hello-pull}. 5.421 -\interaction{tour.clone-pull} 5.422 - 5.423 -We'll use the \hgcmd{pull} command to bring changes from 5.424 -\dirname{my-hello} into \dirname{hello-pull}. However, blindly 5.425 -pulling unknown changes into a repository is a somewhat scary 5.426 -prospect. Mercurial provides the \hgcmd{incoming} command to tell us 5.427 -what changes the \hgcmd{pull} command \emph{would} pull into the 5.428 -repository, without actually pulling the changes in. 5.429 -\interaction{tour.incoming} 5.430 -(Of course, someone could cause more changesets to appear in the 5.431 -repository that we ran \hgcmd{incoming} in, before we get a chance to 5.432 -\hgcmd{pull} the changes, so that we could end up pulling changes that we 5.433 -didn't expect.) 5.434 - 5.435 -Bringing changes into a repository is a simple matter of running the 5.436 -\hgcmd{pull} command, and telling it which repository to pull from. 5.437 -\interaction{tour.pull} 5.438 -As you can see from the before-and-after output of \hgcmd{tip}, we 5.439 -have successfully pulled changes into our repository. There remains 5.440 -one step before we can see these changes in the working directory. 5.441 - 5.442 -\subsection{Updating the working directory} 5.443 - 5.444 -We have so far glossed over the relationship between a repository and 5.445 -its working directory. The \hgcmd{pull} command that we ran in 5.446 -section~\ref{sec:tour:pull} brought changes into the repository, but 5.447 -if we check, there's no sign of those changes in the working 5.448 -directory. This is because \hgcmd{pull} does not (by default) touch 5.449 -the working directory. Instead, we use the \hgcmd{update} command to 5.450 -do this. 5.451 -\interaction{tour.update} 5.452 - 5.453 -It might seem a bit strange that \hgcmd{pull} doesn't update the 5.454 -working directory automatically. There's actually a good reason for 5.455 -this: you can use \hgcmd{update} to update the working directory to 5.456 -the state it was in at \emph{any revision} in the history of the 5.457 -repository. If you had the working directory updated to an old 5.458 -revision---to hunt down the origin of a bug, say---and ran a 5.459 -\hgcmd{pull} which automatically updated the working directory to a 5.460 -new revision, you might not be terribly happy. 5.461 - 5.462 -However, since pull-then-update is such a common thing to do, 5.463 -Mercurial lets you combine the two by passing the \hgopt{pull}{-u} 5.464 -option to \hgcmd{pull}. 5.465 -\begin{codesample2} 5.466 - hg pull -u 5.467 -\end{codesample2} 5.468 -If you look back at the output of \hgcmd{pull} in 5.469 -section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, 5.470 -you can see that it printed a helpful reminder that we'd have to take 5.471 -an explicit step to update the working directory: 5.472 -\begin{codesample2} 5.473 - (run 'hg update' to get a working copy) 5.474 -\end{codesample2} 5.475 - 5.476 -To find out what revision the working directory is at, use the 5.477 -\hgcmd{parents} command. 5.478 -\interaction{tour.parents} 5.479 -To update the working directory to a particular revision, give a 5.480 -revision number or changeset~ID to the \hgcmd{update} command. 5.481 -\interaction{tour.older} 5.482 -If you omit an explicit revision, \hgcmd{update} will update to the 5.483 -tip revision, as shown by the second call to \hgcmd{update} in the 5.484 -example above. 5.485 - 5.486 -\subsection{Pushing changes to another repository} 5.487 - 5.488 -Mercurial lets us push changes to another repository, from the 5.489 -repository we're currently visiting. As with the example of 5.490 -\hgcmd{pull} above, we'll create a temporary repository to push our 5.491 -changes into. 5.492 -\interaction{tour.clone-push} 5.493 -The \hgcmd{outgoing} command tells us what changes would be pushed 5.494 -into another repository. 5.495 -\interaction{tour.outgoing} 5.496 -And the \hgcmd{push} command does the actual push. 5.497 -\interaction{tour.push} 5.498 -As with \hgcmd{pull}, the \hgcmd{push} command does not update the 5.499 -working directory in the repository that it's pushing changes into. 5.500 -(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} 5.501 -option that updates the other repository's working directory.) 5.502 - 5.503 -What happens if we try to pull or push changes and the receiving 5.504 -repository already has those changes? Nothing too exciting. 5.505 -\interaction{tour.push.nothing} 5.506 - 5.507 -\subsection{Sharing changes over a network} 5.508 - 5.509 -The commands we have covered in the previous few sections are not 5.510 -limited to working with local repositories. Each works in exactly the 5.511 -same fashion over a network connection; simply pass in a URL instead 5.512 -of a local path. 5.513 -\interaction{tour.outgoing.net} 5.514 -In this example, we can see what changes we could push to the remote 5.515 -repository, but the repository is understandably not set up to let 5.516 -anonymous users push to it. 5.517 -\interaction{tour.push.net} 5.518 - 5.519 -\section{Merging streams of work} 5.520 - 5.521 -We've now covered cloning a repository, making changes in a 5.522 -repository, and pulling or pushing changes from one repository into 5.523 -another. Our next step is \emph{merging} changes from separate 5.524 -repositories. 5.525 - 5.526 -Merging is a fundamental part of working with a distributed revision 5.527 -control tool. 5.528 -\begin{itemize} 5.529 -\item Alice and Bob each have a personal copy of a repository for a 5.530 - project they're collaborating on. Alice fixes a bug in her 5.531 - repository; Bob adds a new feature in his. They want the shared 5.532 - repository to contain both the bug fix and the new feature. 5.533 -\item I frequently work on several different tasks for a single 5.534 - project at once, each safely isolated in its own repository. 5.535 - Working this way means that I often need to merge one piece of my 5.536 - own work with another. 5.537 -\end{itemize} 5.538 - 5.539 -Because merging is such a common thing to need to do, Mercurial makes 5.540 -it easy. Let's walk through the process. We'll begin by cloning yet 5.541 -another repository (see how often they spring up?) and making a change 5.542 -in it. 5.543 -\interaction{tour.merge.clone} 5.544 -We should now have two copies of \filename{hello.c} with different 5.545 -contents. 5.546 -\interaction{tour.merge.cat} 5.547 - 5.548 -We already know that pulling changes from our \dirname{my-hello} 5.549 -repository will have no effect on the working directory. 5.550 -\interaction{tour.merge.pull} 5.551 -However, the \hgcmd{pull} command says something about ``heads''. 5.552 - 5.553 -A head is a change that has no descendants. The tip revision is thus 5.554 -a head, but a repository can contain more than one head. We can view 5.555 -them using the \hgcmd{heads} command. 5.556 -\interaction{tour.merge.heads} 5.557 -What happens if we try to use the normal \hgcmd{update} command to 5.558 -update to the new tip? 5.559 -\interaction{tour.merge.update} 5.560 -Mercurial is telling us that the \hgcmd{update} command won't do a 5.561 -merge. Instead, we use the \hgcmd{merge} command to merge the two 5.562 -heads. 5.563 -\interaction{tour.merge.merge} 5.564 -This updates the working directory so that it contains changes from 5.565 -both heads, which is reflected in both the output of \hgcmd{parents} 5.566 -and the contents of \filename{hello.c}. 5.567 -\interaction{tour.merge.parents} 5.568 -Whenever we've done a merge, \hgcmd{parents} will display two parents 5.569 -until we \hgcmd{commit} the results of the merge. 5.570 -\interaction{tour.merge.commit} 5.571 -We now have a new tip revision; notice that it has \emph{both} of 5.572 -our former heads as its parents. These are the same revisions that 5.573 -were previously displayed by \hgcmd{parents}. 5.574 -\interaction{tour.merge.tip} 5.575 - 5.576 -%%% Local Variables: 5.577 -%%% mode: latex 5.578 -%%% TeX-master: "00book" 5.579 -%%% End: