hgbook
annotate en/tour-basic.tex @ 214:154e4ba293e7
Delete the hgbook.css file generated by htlatex.
This lets us substitute our own.
This lets us substitute our own.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed May 09 17:03:56 2007 -0700 (2007-05-09) |
parents | d3f8aec5beff |
children | 6a847f7902a7 |
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 |
steve@158 | 88 Mercurial provides a built-in help system. This is 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. |
steve@158 | 108 You can rename or 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 |
steve@158 | 176 created, and the timezone in which it was created. (The 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@99 | 185 Figure~\ref{fig:tour-basic:history} provides a graphical representation of |
bos@97 | 186 the history of the \dirname{hello} repository, to make it a little |
bos@97 | 187 easier to see which direction history is ``flowing'' in. We'll be |
bos@97 | 188 returning to this figure several times in this chapter and the chapter |
bos@97 | 189 that follows. |
bos@97 | 190 |
bos@96 | 191 \begin{figure}[ht] |
bos@96 | 192 \centering |
bos@96 | 193 \grafix{tour-history} |
bos@96 | 194 \caption{Graphical history of the \dirname{hello} repository} |
bos@99 | 195 \label{fig:tour-basic:history} |
bos@96 | 196 \end{figure} |
bos@96 | 197 |
bos@97 | 198 \subsection{Changesets, revisions, and talking to other |
bos@97 | 199 people} |
bos@97 | 200 |
bos@97 | 201 As English is a notoriously sloppy language, and computer science has |
bos@99 | 202 a hallowed history of terminological confusion (why use one term when |
bos@99 | 203 four will do?), revision control has a variety of words and phrases |
bos@99 | 204 that mean the same thing. If you are talking about Mercurial history |
bos@99 | 205 with other people, you will find that the word ``changeset'' is often |
bos@99 | 206 compressed to ``change'' or (when written) ``cset'', and sometimes a |
bos@99 | 207 changeset is referred to as a ``revision'' or a ``rev''. |
bos@88 | 208 |
bos@88 | 209 While it doesn't matter what \emph{word} you use to refer to the |
bos@88 | 210 concept of ``a~changeset'', the \emph{identifier} that you use to |
bos@88 | 211 refer to ``a~\emph{specific} changeset'' is of great importance. |
bos@88 | 212 Recall that the \texttt{changeset} field in the output from |
bos@88 | 213 \hgcmd{log} identifies a changeset using both a number and a |
bos@97 | 214 hexadecimal string. |
bos@97 | 215 \begin{itemize} |
bos@97 | 216 \item The revision number is \emph{only valid in that repository}, |
bos@97 | 217 \item while the hex string is the \emph{permanent, unchanging |
bos@97 | 218 identifier} that will always identify that exact changeset in |
bos@97 | 219 \emph{every} copy of the repository. |
bos@97 | 220 \end{itemize} |
bos@88 | 221 This distinction is important. If you send someone an email talking |
bos@88 | 222 about ``revision~33'', there's a high likelihood that their |
bos@88 | 223 revision~33 will \emph{not be the same} as yours. The reason for this |
bos@88 | 224 is that a revision number depends on the order in which changes |
bos@88 | 225 arrived in a repository, and there is no guarantee that the same |
bos@88 | 226 changes will happen in the same order in different repositories. |
bos@88 | 227 Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, |
bos@88 | 228 while in another as $1,0,2$. |
bos@88 | 229 |
bos@88 | 230 Mercurial uses revision numbers purely as a convenient shorthand. If |
bos@88 | 231 you need to discuss a changeset with someone, or make a record of a |
bos@88 | 232 changeset for some other reason (for example, in a bug report), use |
bos@88 | 233 the hexadecimal identifier. |
bos@88 | 234 |
bos@88 | 235 \subsection{Viewing specific revisions} |
bos@88 | 236 |
bos@88 | 237 To narrow the output of \hgcmd{log} down to a single revision, use the |
bos@91 | 238 \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a |
bos@91 | 239 revision number or a long-form changeset identifier, and you can |
bos@91 | 240 provide as many revisions as you want. \interaction{tour.log-r} |
bos@88 | 241 |
bos@88 | 242 If you want to see the history of several revisions without having to |
bos@88 | 243 list each one, you can use \emph{range notation}; this lets you |
bos@88 | 244 express the idea ``I want all revisions between $a$ and $b$, |
bos@88 | 245 inclusive''. |
bos@88 | 246 \interaction{tour.log.range} |
bos@88 | 247 Mercurial also honours the order in which you specify revisions, so |
bos@88 | 248 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} |
bos@88 | 249 prints $4,3,2$. |
bos@88 | 250 |
bos@91 | 251 \subsection{More detailed information} |
bos@91 | 252 |
bos@91 | 253 While the summary information printed by \hgcmd{log} is useful if you |
bos@91 | 254 already know what you're looking for, you may need to see a complete |
bos@91 | 255 description of the change, or a list of the files changed, if you're |
bos@91 | 256 trying to decide whether a changeset is the one you're looking for. |
bos@91 | 257 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) |
bos@91 | 258 option gives you this extra detail. |
bos@91 | 259 \interaction{tour.log-v} |
bos@91 | 260 |
bos@91 | 261 If you want to see both the description and content of a change, add |
bos@91 | 262 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays |
bos@91 | 263 the content of a change as a \emph{unified diff} (if you've never seen |
bos@91 | 264 a unified diff before, see section~\ref{sec:mq:patch} for an overview). |
bos@91 | 265 \interaction{tour.log-vp} |
bos@91 | 266 |
bos@91 | 267 \section{All about command options} |
bos@91 | 268 |
bos@91 | 269 Let's take a brief break from exploring Mercurial commands to discuss |
bos@91 | 270 a pattern in the way that they work; you may find this useful to keep |
steve@158 | 271 in mind as we continue our tour. |
bos@91 | 272 |
bos@91 | 273 Mercurial has a consistent and straightforward approach to dealing |
bos@91 | 274 with the options that you can pass to commands. It follows the |
bos@91 | 275 conventions for options that are common to modern Linux and Unix |
bos@91 | 276 systems. |
bos@91 | 277 \begin{itemize} |
bos@91 | 278 \item Every option has a long name. For example, as we've already |
bos@91 | 279 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. |
bos@91 | 280 \item Most options have short names, too. Instead of |
bos@91 | 281 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that |
bos@91 | 282 some options don't have short names is that the options in question |
bos@91 | 283 are rarely used.) |
bos@91 | 284 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), |
bos@91 | 285 while short options start with one (e.g.~\hgopt{log}{-r}). |
bos@91 | 286 \item Option naming and usage is consistent across commands. For |
bos@91 | 287 example, every command that lets you specify a changeset~ID or |
bos@91 | 288 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} |
bos@91 | 289 arguments. |
bos@91 | 290 \end{itemize} |
bos@91 | 291 In the examples throughout this book, I use short options instead of |
bos@91 | 292 long. This just reflects my own preference, so don't read anything |
bos@91 | 293 significant into it. |
bos@91 | 294 |
bos@91 | 295 Most commands that print output of some kind will print more output |
bos@91 | 296 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less |
bos@91 | 297 when passed \hggopt{-q} (or \hggopt{--quiet}). |
bos@91 | 298 |
bos@91 | 299 \section{Making and reviewing changes} |
bos@91 | 300 |
bos@91 | 301 Now that we have a grasp of viewing history in Mercurial, let's take a |
bos@91 | 302 look at making some changes and examining them. |
bos@91 | 303 |
bos@91 | 304 The first thing we'll do is isolate our experiment in a repository of |
bos@91 | 305 its own. We use the \hgcmd{clone} command, but we don't need to |
bos@91 | 306 clone a copy of the remote repository. Since we already have a copy |
bos@91 | 307 of it locally, we can just clone that instead. This is much faster |
bos@91 | 308 than cloning over the network, and cloning a local repository uses |
bos@91 | 309 less disk space in most cases, too. |
bos@91 | 310 \interaction{tour.reclone} |
bos@91 | 311 As an aside, it's often good practice to keep a ``pristine'' copy of a |
bos@91 | 312 remote repository around, which you can then make temporary clones of |
bos@91 | 313 to create sandboxes for each task you want to work on. This lets you |
bos@91 | 314 work on multiple tasks in parallel, each isolated from the others |
bos@91 | 315 until it's complete and you're ready to integrate it back. Because |
bos@91 | 316 local clones are so cheap, there's almost no overhead to cloning and |
bos@91 | 317 destroying repositories whenever you want. |
bos@91 | 318 |
bos@91 | 319 In our \dirname{my-hello} repository, we have a file |
bos@91 | 320 \filename{hello.c} that contains the classic ``hello, world'' program. |
bos@91 | 321 Let's use the ancient and venerable \command{sed} command to edit this |
bos@91 | 322 file so that it prints a second line of output. (I'm only using |
bos@91 | 323 \command{sed} to do this because it's easy to write a scripted example |
bos@91 | 324 this way. Since you're not under the same constraint, you probably |
bos@91 | 325 won't want to use \command{sed}; simply use your preferred text editor to |
bos@91 | 326 do the same thing.) |
bos@91 | 327 \interaction{tour.sed} |
bos@91 | 328 |
bos@91 | 329 Mercurial's \hgcmd{status} command will tell us what Mercurial knows |
bos@91 | 330 about the files in the repository. |
bos@91 | 331 \interaction{tour.status} |
bos@91 | 332 The \hgcmd{status} command prints no output for some files, but a line |
bos@91 | 333 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell |
bos@91 | 334 it to, \hgcmd{status} will not print any output for files that have |
bos@91 | 335 not been modified. |
bos@91 | 336 |
bos@91 | 337 The ``\texttt{M}'' indicates that Mercurial has noticed that we |
bos@97 | 338 modified \filename{hello.c}. We didn't need to \emph{inform} |
bos@97 | 339 Mercurial that we were going to modify the file before we started, or |
bos@97 | 340 that we had modified the file after we were done; it was able to |
bos@97 | 341 figure this out itself. |
bos@91 | 342 |
bos@91 | 343 It's a little bit helpful to know that we've modified |
bos@91 | 344 \filename{hello.c}, but we might prefer to know exactly \emph{what} |
bos@91 | 345 changes we've made to it. To do this, we use the \hgcmd{diff} |
bos@91 | 346 command. |
bos@91 | 347 \interaction{tour.diff} |
bos@91 | 348 |
bos@91 | 349 \section{Recording changes in a new changeset} |
bos@91 | 350 |
bos@91 | 351 We can modify files, build and test our changes, and use |
bos@91 | 352 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're |
bos@91 | 353 satisfied with what we've done and arrive at a natural stopping point |
bos@91 | 354 where we want to record our work in a new changeset. |
bos@91 | 355 |
bos@91 | 356 The \hgcmd{commit} command lets us create a new changeset; we'll |
bos@91 | 357 usually refer to this as ``making a commit'' or ``committing''. |
bos@91 | 358 |
bos@102 | 359 \subsection{Setting up a username} |
bos@102 | 360 |
bos@174 | 361 When you try to run \hgcmd{commit} for the first time, it is not |
bos@174 | 362 guaranteed to succeed. Mercurial records your name and address with |
bos@174 | 363 each change that you commit, so that you and others will later be able |
bos@174 | 364 to tell who made each change. Mercurial tries to automatically figure |
bos@174 | 365 out a sensible username to commit the change with. It will attempt |
bos@174 | 366 each of the following methods, in order: |
bos@174 | 367 \begin{enumerate} |
bos@174 | 368 \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit} |
bos@174 | 369 command on the command line, followed by a username, this is always |
bos@174 | 370 given the highest precedence. |
bos@174 | 371 \item If you have set the \envar{HGUSER} environment variable, this is |
bos@174 | 372 checked next. |
bos@174 | 373 \item If you create a file in your home directory called |
bos@174 | 374 \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be |
bos@174 | 375 used next. To see what the contents of this file should look like, |
bos@174 | 376 refer to section~\ref{sec:tour-basic:username} below. |
bos@174 | 377 \item If you have set the \envar{EMAIL} environment variable, this |
bos@174 | 378 will be used next. |
bos@174 | 379 \item Mercurial will query your system to find out your local user |
bos@174 | 380 name and host name, and construct a username from these components. |
bos@174 | 381 Since this often results in a username that is not very useful, it |
bos@174 | 382 will print a warning if it has to do this. |
bos@174 | 383 \end{enumerate} |
bos@174 | 384 If all of these mechanisms fail, Mercurial will fail, printing an |
bos@174 | 385 error message. In this case, it will not let you commit until you set |
bos@174 | 386 up a username. |
bos@174 | 387 |
bos@174 | 388 You should think of the \envar{HGUSER} environment variable and the |
bos@174 | 389 \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to |
bos@174 | 390 \emph{override} Mercurial's default selection of username. For normal |
bos@174 | 391 use, the simplest and most robust way to set a username for yourself |
bos@174 | 392 is by creating a \sfilename{.hgrc} file; see below for details. |
bos@102 | 393 |
bos@102 | 394 \subsubsection{Creating a Mercurial configuration file} |
bos@174 | 395 \label{sec:tour-basic:username} |
bos@102 | 396 |
bos@102 | 397 To set a user name, use your favourite editor to create a file called |
bos@102 | 398 \sfilename{.hgrc} in your home directory. Mercurial will use this |
bos@102 | 399 file to look up your personalised configuration settings. The initial |
bos@102 | 400 contents of your \sfilename{.hgrc} should look like this. |
bos@102 | 401 \begin{codesample2} |
bos@102 | 402 # This is a Mercurial configuration file. |
bos@102 | 403 [ui] |
bos@102 | 404 username = Firstname Lastname <email.address@domain.net> |
bos@102 | 405 \end{codesample2} |
bos@102 | 406 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file, |
bos@102 | 407 so you can read the ``\texttt{username = ...}'' line as meaning ``set |
bos@102 | 408 the value of the \texttt{username} item in the \texttt{ui} section''. |
bos@102 | 409 A section continues until a new section begins, or the end of the |
bos@102 | 410 file. Mercurial ignores empty lines and treats any text from |
bos@102 | 411 ``\texttt{\#}'' to the end of a line as a comment. |
bos@102 | 412 |
bos@102 | 413 \subsubsection{Choosing a user name} |
bos@102 | 414 |
bos@102 | 415 You can use any text you like as the value of the \texttt{username} |
bos@102 | 416 config item, since this information is for reading by other people, |
bos@102 | 417 but for interpreting by Mercurial. The convention that most people |
bos@102 | 418 follow is to use their name and email address, as in the example |
bos@102 | 419 above. |
bos@102 | 420 |
bos@102 | 421 \begin{note} |
bos@102 | 422 Mercurial's built-in web server obfuscates email addresses, to make |
bos@102 | 423 it more difficult for the email harvesting tools that spammers use. |
bos@102 | 424 This reduces the likelihood that you'll start receiving more junk |
bos@102 | 425 email if you publish a Mercurial repository on the web. |
bos@102 | 426 \end{note} |
bos@102 | 427 |
bos@91 | 428 \subsection{Writing a commit message} |
bos@91 | 429 |
bos@91 | 430 When we commit a change, Mercurial drops us into a text editor, to |
bos@91 | 431 enter a message that will describe the modifications we've made in |
bos@91 | 432 this changeset. This is called the \emph{commit message}. It will be |
bos@91 | 433 a record for readers of what we did and why, and it will be printed by |
bos@91 | 434 \hgcmd{log} after we've finished committing. |
bos@91 | 435 \interaction{tour.commit} |
bos@91 | 436 |
bos@91 | 437 The editor that the \hgcmd{commit} command drops us into will contain |
bos@91 | 438 an empty line, followed by a number of lines starting with |
bos@91 | 439 ``\texttt{HG:}''. |
bos@91 | 440 \begin{codesample2} |
bos@91 | 441 \emph{empty line} |
bos@91 | 442 HG: changed hello.c |
bos@91 | 443 \end{codesample2} |
bos@91 | 444 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses |
bos@91 | 445 them only to tell us which files it's recording changes to. Modifying |
bos@91 | 446 or deleting these lines has no effect. |
bos@91 | 447 |
bos@91 | 448 \subsection{Writing a good commit message} |
bos@91 | 449 |
bos@91 | 450 Since \hgcmd{log} only prints the first line of a commit message by |
bos@91 | 451 default, it's best to write a commit message whose first line stands |
bos@91 | 452 alone. Here's a real example of a commit message that \emph{doesn't} |
bos@91 | 453 follow this guideline, and hence has a summary that is not readable. |
bos@91 | 454 \begin{codesample2} |
bos@91 | 455 changeset: 73:584af0e231be |
bos@91 | 456 user: Censored Person <censored.person@example.org> |
bos@91 | 457 date: Tue Sep 26 21:37:07 2006 -0700 |
bos@91 | 458 summary: include buildmeister/commondefs. Add an exports and install |
bos@91 | 459 \end{codesample2} |
bos@91 | 460 |
bos@91 | 461 As far as the remainder of the contents of the commit message are |
bos@91 | 462 concerned, there are no hard-and-fast rules. Mercurial itself doesn't |
bos@91 | 463 interpret or care about the contents of the commit message, though |
bos@91 | 464 your project may have policies that dictate a certain kind of |
bos@91 | 465 formatting. |
bos@91 | 466 |
bos@91 | 467 My personal preference is for short, but informative, commit messages |
bos@91 | 468 that tell me something that I can't figure out with a quick glance at |
bos@91 | 469 the output of \hgcmdargs{log}{--patch}. |
bos@91 | 470 |
bos@91 | 471 \subsection{Aborting a commit} |
bos@91 | 472 |
bos@91 | 473 If you decide that you don't want to commit while in the middle of |
bos@91 | 474 editing a commit message, simply exit from your editor without saving |
bos@91 | 475 the file that it's editing. This will cause nothing to happen to |
bos@91 | 476 either the repository or the working directory. |
bos@91 | 477 |
bos@91 | 478 If we run the \hgcmd{commit} command without any arguments, it records |
bos@91 | 479 all of the changes we've made, as reported by \hgcmd{status} and |
bos@91 | 480 \hgcmd{diff}. |
bos@91 | 481 |
bos@102 | 482 \subsection{Admiring our new handiwork} |
bos@91 | 483 |
bos@91 | 484 Once we've finished the commit, we can use the \hgcmd{tip} command to |
bos@91 | 485 display the changeset we just created. This command produces output |
bos@91 | 486 that is identical to \hgcmd{log}, but it only displays the newest |
bos@91 | 487 revision in the repository. |
bos@91 | 488 \interaction{tour.tip} |
bos@91 | 489 We refer to the newest revision in the repository as the tip revision, |
bos@91 | 490 or simply the tip. |
bos@91 | 491 |
bos@91 | 492 \section{Sharing changes} |
bos@91 | 493 |
bos@91 | 494 We mentioned earlier that repositories in Mercurial are |
bos@91 | 495 self-contained. This means that the changeset we just created exists |
bos@91 | 496 only in our \dirname{my-hello} repository. Let's look at a few ways |
bos@91 | 497 that we can propagate this change into other repositories. |
bos@91 | 498 |
bos@91 | 499 \subsection{Pulling changes from another repository} |
bos@91 | 500 \label{sec:tour:pull} |
bos@91 | 501 |
bos@91 | 502 To get started, let's clone our original \dirname{hello} repository, |
bos@91 | 503 which does not contain the change we just committed. We'll call our |
bos@91 | 504 temporary repository \dirname{hello-pull}. |
bos@91 | 505 \interaction{tour.clone-pull} |
bos@91 | 506 |
bos@91 | 507 We'll use the \hgcmd{pull} command to bring changes from |
bos@91 | 508 \dirname{my-hello} into \dirname{hello-pull}. However, blindly |
bos@91 | 509 pulling unknown changes into a repository is a somewhat scary |
bos@91 | 510 prospect. Mercurial provides the \hgcmd{incoming} command to tell us |
bos@91 | 511 what changes the \hgcmd{pull} command \emph{would} pull into the |
bos@91 | 512 repository, without actually pulling the changes in. |
bos@91 | 513 \interaction{tour.incoming} |
bos@91 | 514 (Of course, someone could cause more changesets to appear in the |
bos@91 | 515 repository that we ran \hgcmd{incoming} in, before we get a chance to |
bos@91 | 516 \hgcmd{pull} the changes, so that we could end up pulling changes that we |
bos@91 | 517 didn't expect.) |
bos@91 | 518 |
bos@91 | 519 Bringing changes into a repository is a simple matter of running the |
bos@91 | 520 \hgcmd{pull} command, and telling it which repository to pull from. |
bos@91 | 521 \interaction{tour.pull} |
bos@91 | 522 As you can see from the before-and-after output of \hgcmd{tip}, we |
bos@91 | 523 have successfully pulled changes into our repository. There remains |
bos@92 | 524 one step before we can see these changes in the working directory. |
bos@92 | 525 |
bos@92 | 526 \subsection{Updating the working directory} |
bos@92 | 527 |
bos@92 | 528 We have so far glossed over the relationship between a repository and |
bos@91 | 529 its working directory. The \hgcmd{pull} command that we ran in |
bos@91 | 530 section~\ref{sec:tour:pull} brought changes into the repository, but |
bos@91 | 531 if we check, there's no sign of those changes in the working |
bos@91 | 532 directory. This is because \hgcmd{pull} does not (by default) touch |
bos@91 | 533 the working directory. Instead, we use the \hgcmd{update} command to |
bos@91 | 534 do this. |
bos@91 | 535 \interaction{tour.update} |
bos@91 | 536 |
bos@91 | 537 It might seem a bit strange that \hgcmd{pull} doesn't update the |
bos@91 | 538 working directory automatically. There's actually a good reason for |
bos@91 | 539 this: you can use \hgcmd{update} to update the working directory to |
bos@91 | 540 the state it was in at \emph{any revision} in the history of the |
bos@91 | 541 repository. If you had the working directory updated to an old |
bos@91 | 542 revision---to hunt down the origin of a bug, say---and ran a |
bos@91 | 543 \hgcmd{pull} which automatically updated the working directory to a |
bos@91 | 544 new revision, you might not be terribly happy. |
bos@91 | 545 |
bos@91 | 546 However, since pull-then-update is such a common thing to do, |
bos@91 | 547 Mercurial lets you combine the two by passing the \hgopt{pull}{-u} |
bos@91 | 548 option to \hgcmd{pull}. |
bos@91 | 549 \begin{codesample2} |
bos@91 | 550 hg pull -u |
bos@91 | 551 \end{codesample2} |
bos@92 | 552 If you look back at the output of \hgcmd{pull} in |
bos@92 | 553 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, |
bos@92 | 554 you can see that it printed a helpful reminder that we'd have to take |
bos@92 | 555 an explicit step to update the working directory: |
bos@92 | 556 \begin{codesample2} |
bos@92 | 557 (run 'hg update' to get a working copy) |
bos@92 | 558 \end{codesample2} |
bos@91 | 559 |
bos@91 | 560 To find out what revision the working directory is at, use the |
bos@91 | 561 \hgcmd{parents} command. |
bos@91 | 562 \interaction{tour.parents} |
bos@101 | 563 If you look back at figure~\ref{fig:tour-basic:history}, you'll see |
bos@101 | 564 arrows connecting each changeset. The node that the arrow leads |
bos@101 | 565 \emph{from} in each case is a parent, and the node that the arrow |
bos@101 | 566 leads \emph{to} is its child. The working directory has a parent in |
bos@101 | 567 just the same way; this is the changeset that the working directory |
bos@101 | 568 currently contains. |
bos@101 | 569 |
bos@91 | 570 To update the working directory to a particular revision, give a |
bos@91 | 571 revision number or changeset~ID to the \hgcmd{update} command. |
bos@91 | 572 \interaction{tour.older} |
bos@91 | 573 If you omit an explicit revision, \hgcmd{update} will update to the |
bos@94 | 574 tip revision, as shown by the second call to \hgcmd{update} in the |
bos@94 | 575 example above. |
bos@91 | 576 |
bos@92 | 577 \subsection{Pushing changes to another repository} |
bos@92 | 578 |
bos@92 | 579 Mercurial lets us push changes to another repository, from the |
bos@92 | 580 repository we're currently visiting. As with the example of |
bos@92 | 581 \hgcmd{pull} above, we'll create a temporary repository to push our |
bos@92 | 582 changes into. |
bos@92 | 583 \interaction{tour.clone-push} |
bos@92 | 584 The \hgcmd{outgoing} command tells us what changes would be pushed |
bos@92 | 585 into another repository. |
bos@92 | 586 \interaction{tour.outgoing} |
bos@92 | 587 And the \hgcmd{push} command does the actual push. |
bos@92 | 588 \interaction{tour.push} |
bos@92 | 589 As with \hgcmd{pull}, the \hgcmd{push} command does not update the |
bos@92 | 590 working directory in the repository that it's pushing changes into. |
bos@92 | 591 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} |
bos@92 | 592 option that updates the other repository's working directory.) |
bos@92 | 593 |
bos@92 | 594 What happens if we try to pull or push changes and the receiving |
bos@92 | 595 repository already has those changes? Nothing too exciting. |
bos@92 | 596 \interaction{tour.push.nothing} |
bos@92 | 597 |
bos@93 | 598 \subsection{Sharing changes over a network} |
bos@93 | 599 |
bos@93 | 600 The commands we have covered in the previous few sections are not |
bos@93 | 601 limited to working with local repositories. Each works in exactly the |
bos@93 | 602 same fashion over a network connection; simply pass in a URL instead |
bos@93 | 603 of a local path. |
bos@93 | 604 \interaction{tour.outgoing.net} |
bos@93 | 605 In this example, we can see what changes we could push to the remote |
bos@93 | 606 repository, but the repository is understandably not set up to let |
bos@93 | 607 anonymous users push to it. |
bos@93 | 608 \interaction{tour.push.net} |
bos@93 | 609 |
bos@84 | 610 %%% Local Variables: |
bos@84 | 611 %%% mode: latex |
bos@84 | 612 %%% TeX-master: "00book" |
bos@84 | 613 %%% End: |