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