| 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:
|
