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