| rev |
line source |
|
bos@84
|
1 \chapter{A lightning tour of Mercurial}
|
|
bos@84
|
2 \label{chap:tour}
|
|
bos@84
|
3
|
|
bos@84
|
4 \section{Installing Mercurial on your system}
|
|
bos@84
|
5 \label{sec:tour:install}
|
|
bos@84
|
6
|
|
bos@85
|
7 Prebuilt binary packages of Mercurial are available for every popular
|
|
bos@85
|
8 operating system. These make it easy to start using Mercurial on your
|
|
bos@85
|
9 computer immediately.
|
|
bos@85
|
10
|
|
bos@84
|
11 \subsection{Linux}
|
|
bos@84
|
12
|
|
bos@84
|
13 Because each Linux distribution has its own packaging tools, policies,
|
|
bos@84
|
14 and rate of development, it's difficult to give a comprehensive set of
|
|
bos@85
|
15 instructions on how to install Mercurial binaries. The version of
|
|
bos@85
|
16 Mercurial that you will end up with can vary depending on how active
|
|
bos@85
|
17 the person is who maintains the package for your distribution.
|
|
bos@84
|
18
|
|
bos@84
|
19 To keep things simple, I will focus on installing Mercurial from the
|
|
bos@84
|
20 command line under the most popular Linux distributions. Most of
|
|
bos@84
|
21 these distributions provide graphical package managers that will let
|
|
bos@84
|
22 you install Mercurial with a single click; the package name to look
|
|
bos@84
|
23 for is \texttt{mercurial}.
|
|
bos@84
|
24
|
|
bos@85
|
25 \begin{itemize}
|
|
bos@85
|
26 \item[Debian]
|
|
bos@85
|
27 \begin{codesample4}
|
|
bos@85
|
28 apt-get install mercurial
|
|
bos@85
|
29 \end{codesample4}
|
|
bos@84
|
30
|
|
bos@85
|
31 \item[Fedora Core]
|
|
bos@85
|
32 \begin{codesample4}
|
|
bos@85
|
33 yum install mercurial
|
|
bos@85
|
34 \end{codesample4}
|
|
bos@84
|
35
|
|
bos@85
|
36 \item[Gentoo]
|
|
bos@85
|
37 \begin{codesample4}
|
|
bos@85
|
38 emerge mercurial
|
|
bos@85
|
39 \end{codesample4}
|
|
bos@84
|
40
|
|
bos@85
|
41 \item[OpenSUSE]
|
|
bos@85
|
42 \begin{codesample4}
|
|
bos@85
|
43 yum install mercurial
|
|
bos@85
|
44 \end{codesample4}
|
|
bos@84
|
45
|
|
bos@85
|
46 \item[Ubuntu] Ubuntu's Mercurial package is particularly old, and you
|
|
bos@85
|
47 should not use it. If you know how, you can rebuild and install the
|
|
bos@85
|
48 Debian package. It's probably easier to build Mercurial from source
|
|
bos@85
|
49 and simply run that; see section~\ref{sec:srcinstall:unixlike} for
|
|
bos@85
|
50 details.
|
|
bos@85
|
51 \end{itemize}
|
|
bos@84
|
52
|
|
bos@84
|
53 \subsection{Mac OS X}
|
|
bos@84
|
54
|
|
bos@84
|
55 Lee Cantey publishes an installer of Mercurial for Mac OS~X at
|
|
bos@84
|
56 \url{http://mercurial.berkwood.com}. This package works on both
|
|
bos@85
|
57 Intel-~and Power-based Macs. Before you can use it, you must install
|
|
bos@85
|
58 a compatible version of Universal MacPython~\cite{web:macpython}. This
|
|
bos@85
|
59 is easy to do; simply follow the instructions on Lee's site.
|
|
bos@84
|
60
|
|
bos@84
|
61 \subsection{Solaris}
|
|
bos@84
|
62
|
|
bos@84
|
63 XXX.
|
|
bos@84
|
64
|
|
bos@84
|
65 \subsection{Windows}
|
|
bos@84
|
66
|
|
bos@84
|
67 Lee Cantey publishes an installer of Mercurial for Windows at
|
|
bos@84
|
68 \url{http://mercurial.berkwood.com}. This package has no external
|
|
bos@84
|
69 dependencies; it ``just works''.
|
|
bos@84
|
70
|
|
bos@84
|
71 \begin{note}
|
|
bos@84
|
72 The Windows version of Mercurial does not automatically convert line
|
|
bos@84
|
73 endings between Windows and Unix styles. If you want to share work
|
|
bos@84
|
74 with Unix users, you must do a little additional configuration
|
|
bos@84
|
75 work. XXX Flesh this out.
|
|
bos@84
|
76 \end{note}
|
|
bos@84
|
77
|
|
bos@87
|
78 \section{Getting started}
|
|
bos@87
|
79
|
|
bos@87
|
80 To begin, we'll use the \hgcmd{version} command to find out whether
|
|
bos@87
|
81 Mercurial is actually installed properly. The actual version
|
|
bos@87
|
82 information that it prints isn't so important; it's whether it prints
|
|
bos@87
|
83 anything at all that we care about.
|
|
bos@87
|
84 \interaction{tour.version}
|
|
bos@87
|
85
|
|
bos@87
|
86 \subsection{Built-in help}
|
|
bos@87
|
87
|
|
bos@87
|
88 Mercurial provides a built-in help system. This invaluable for those
|
|
bos@87
|
89 times when you find yourself stuck trying to remember how to run a
|
|
bos@87
|
90 command. If you are completely stuck, simply run \hgcmd{help}; it
|
|
bos@87
|
91 will print a brief list of commands, along with a description of what
|
|
bos@87
|
92 each does. If you ask for help on a specific command (as below), it
|
|
bos@87
|
93 prints more detailed information.
|
|
bos@87
|
94 \interaction{tour.help}
|
|
bos@87
|
95 For a more impressive level of detail (which you won't usually need)
|
|
bos@87
|
96 run \hgcmdargs{help}{\hggopt{-v}}. The \hggopt{-v} option is short
|
|
bos@87
|
97 for \hggopt{--verbose}, and tells Mercurial to print more information
|
|
bos@87
|
98 than it usually would.
|
|
bos@87
|
99
|
|
bos@87
|
100 \section{Working with a repository}
|
|
bos@87
|
101
|
|
bos@87
|
102 In Mercurial, everything happens inside a \emph{repository}. The
|
|
bos@87
|
103 repository for a project contains all of the files that ``belong to''
|
|
bos@87
|
104 that project, along with a historical record of the project's files.
|
|
bos@87
|
105
|
|
bos@87
|
106 There's nothing particularly magical about a repository; it is simply
|
|
bos@87
|
107 a directory tree in your filesystem that Mercurial treats as special.
|
|
bos@87
|
108 You can rename delete a repository any time you like, using either the
|
|
bos@87
|
109 command line or your file browser.
|
|
bos@87
|
110
|
|
bos@88
|
111 \subsection{Making a local copy of a repository}
|
|
bos@87
|
112
|
|
bos@87
|
113 \emph{Copying} a repository is just a little bit special. While you
|
|
bos@87
|
114 could use a normal file copying command to make a copy of a
|
|
bos@87
|
115 repository, it's best to use a built-in command that Mercurial
|
|
bos@87
|
116 provides. This command is called \hgcmd{clone}, because it creates an
|
|
bos@87
|
117 identical copy of an existing repository.
|
|
bos@87
|
118 \interaction{tour.clone}
|
|
bos@87
|
119 If our clone succeeded, we should now have a local directory called
|
|
bos@87
|
120 \dirname{hello}. This directory will contain some files.
|
|
bos@87
|
121 \interaction{tour.ls}
|
|
bos@87
|
122 These files have the same contents and history in our repository as
|
|
bos@87
|
123 they do in the repository we cloned.
|
|
bos@87
|
124
|
|
bos@87
|
125 Every Mercurial repository is complete, self-contained, and
|
|
bos@87
|
126 independent. It contains its own private copy of a project's files
|
|
bos@87
|
127 and history. A cloned repository remembers the location of the
|
|
bos@87
|
128 repository it was cloned from, but it does not communicate with that
|
|
bos@87
|
129 repository, or any other, unless you tell it to.
|
|
bos@87
|
130
|
|
bos@87
|
131 What this means for now is that we're free to experiment with our
|
|
bos@87
|
132 repository, safe in the knowledge that it's a private ``sandbox'' that
|
|
bos@87
|
133 won't affect anyone else.
|
|
bos@85
|
134
|
|
bos@88
|
135 \subsection{What's in a repository?}
|
|
bos@88
|
136
|
|
bos@88
|
137 When we take a more detailed look inside a repository, we can see that
|
|
bos@88
|
138 it contains a directory named \dirname{.hg}. This is where Mercurial
|
|
bos@88
|
139 keeps all of its metadata for the repository.
|
|
bos@88
|
140 \interaction{tour.ls-a}
|
|
bos@88
|
141
|
|
bos@88
|
142 The contents of the \dirname{.hg} directory and its subdirectories are
|
|
bos@88
|
143 private to Mercurial. Every other file and directory in the
|
|
bos@88
|
144 repository is yours to do with as you please.
|
|
bos@88
|
145
|
|
bos@88
|
146 To introduce a little terminology, the \dirname{.hg} directory is the
|
|
bos@88
|
147 ``real'' repository, and all of the files and directories that coexist
|
|
bos@88
|
148 with it are said to live in the ``working directory''. An easy way to
|
|
bos@88
|
149 remember the distinction is that the \emph{repository} contains the
|
|
bos@88
|
150 \emph{history} of your project, while the \emph{working directory}
|
|
bos@88
|
151 contains a \emph{snapshot} of your project at a particular point in
|
|
bos@88
|
152 history.
|
|
bos@88
|
153
|
|
bos@88
|
154 \section{A tour through history}
|
|
bos@88
|
155
|
|
bos@88
|
156 One of the first things we might want to do with a new, unfamiliar
|
|
bos@88
|
157 repository is understand its history. The \hgcmd{log} command gives
|
|
bos@88
|
158 us a view of history.
|
|
bos@88
|
159 \interaction{tour.log}
|
|
bos@88
|
160 By default, this command prints a brief paragraph of output for each
|
|
bos@88
|
161 change to the project that was recorded. In Mercurial terminology, we
|
|
bos@88
|
162 call each of these recorded events a \emph{changeset}, because it can
|
|
bos@88
|
163 contain a record of changes to several files.
|
|
bos@88
|
164
|
|
bos@88
|
165 The fields in a record of output from \hgcmd{log} are as follows.
|
|
bos@88
|
166 \begin{itemize}
|
|
bos@88
|
167 \item[\texttt{changeset}] This field has the format of a number,
|
|
bos@88
|
168 followed by a colon, followed by a hexadecimal string. These are
|
|
bos@88
|
169 \emph{identifiers} for the changeset. There are two identifiers
|
|
bos@88
|
170 because the number is shorter and easier to type than the hex
|
|
bos@88
|
171 string.
|
|
bos@88
|
172 \item[\texttt{user}] The identity of the person who created the
|
|
bos@88
|
173 changeset. This is a free-form field, but it most often contains a
|
|
bos@88
|
174 person's name and email address.
|
|
bos@88
|
175 \item[\texttt{date}] The date and time on which the changeset was
|
|
bos@88
|
176 created, and the timezone in which it was created. (Thef date and
|
|
bos@88
|
177 time are local to that timezone; they display what time and date it
|
|
bos@88
|
178 was for the person who created the changeset.)
|
|
bos@88
|
179 \item[\texttt{summary}] The first line of the text message that the
|
|
bos@88
|
180 creator of the changeset entered to describe the changeset.
|
|
bos@88
|
181 \end{itemize}
|
|
bos@88
|
182 The default output printed by \hgcmd{log} is purely a summary; it is
|
|
bos@88
|
183 missing a lot of detail.
|
|
bos@88
|
184
|
|
bos@88
|
185 \subsection{Changesets, revisions, and identification}
|
|
bos@88
|
186
|
|
bos@88
|
187 English being a notoriously sloppy language, we have a variety of
|
|
bos@88
|
188 terms that have the same meaning. If you are talking about Mercurial
|
|
bos@88
|
189 history with other people, you will find that the word ``changeset''
|
|
bos@88
|
190 is often compressed to ``change'' or ``cset'', and sometimes a
|
|
bos@88
|
191 changeset is referred to as a ``revision'' or a ``rev''.
|
|
bos@88
|
192
|
|
bos@88
|
193 While it doesn't matter what \emph{word} you use to refer to the
|
|
bos@88
|
194 concept of ``a~changeset'', the \emph{identifier} that you use to
|
|
bos@88
|
195 refer to ``a~\emph{specific} changeset'' is of great importance.
|
|
bos@88
|
196 Recall that the \texttt{changeset} field in the output from
|
|
bos@88
|
197 \hgcmd{log} identifies a changeset using both a number and a
|
|
bos@88
|
198 hexadecimal string. The number is \emph{only valid in that
|
|
bos@88
|
199 repository}, while the hex string is the \emph{permanent, unchanging
|
|
bos@88
|
200 identifier} that will always identify that changeset in every copy
|
|
bos@88
|
201 of the repository.
|
|
bos@88
|
202
|
|
bos@88
|
203 This distinction is important. If you send someone an email talking
|
|
bos@88
|
204 about ``revision~33'', there's a high likelihood that their
|
|
bos@88
|
205 revision~33 will \emph{not be the same} as yours. The reason for this
|
|
bos@88
|
206 is that a revision number depends on the order in which changes
|
|
bos@88
|
207 arrived in a repository, and there is no guarantee that the same
|
|
bos@88
|
208 changes will happen in the same order in different repositories.
|
|
bos@88
|
209 Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
|
|
bos@88
|
210 while in another as $1,0,2$.
|
|
bos@88
|
211
|
|
bos@88
|
212 Mercurial uses revision numbers purely as a convenient shorthand. If
|
|
bos@88
|
213 you need to discuss a changeset with someone, or make a record of a
|
|
bos@88
|
214 changeset for some other reason (for example, in a bug report), use
|
|
bos@88
|
215 the hexadecimal identifier.
|
|
bos@88
|
216
|
|
bos@88
|
217 \subsection{Viewing specific revisions}
|
|
bos@88
|
218
|
|
bos@88
|
219 To narrow the output of \hgcmd{log} down to a single revision, use the
|
|
bos@88
|
220 \hgopt{log}{-r} option. You can use either a revision number or a
|
|
bos@88
|
221 long-form changeset identifier, and you can provide as many revisions
|
|
bos@88
|
222 as you want.
|
|
bos@88
|
223 \interaction{tour.log-r}
|
|
bos@88
|
224
|
|
bos@88
|
225 If you want to see the history of several revisions without having to
|
|
bos@88
|
226 list each one, you can use \emph{range notation}; this lets you
|
|
bos@88
|
227 express the idea ``I want all revisions between $a$ and $b$,
|
|
bos@88
|
228 inclusive''.
|
|
bos@88
|
229 \interaction{tour.log.range}
|
|
bos@88
|
230 Mercurial also honours the order in which you specify revisions, so
|
|
bos@88
|
231 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
|
|
bos@88
|
232 prints $4,3,2$.
|
|
bos@88
|
233
|
|
bos@84
|
234 %%% Local Variables:
|
|
bos@84
|
235 %%% mode: latex
|
|
bos@84
|
236 %%% TeX-master: "00book"
|
|
bos@84
|
237 %%% End:
|
