annotate en/tour.tex @ 92:72d207927dc4

Tour: push.
author Bryan O'Sullivan <bos@serpentine.com>
date Thu, 12 Oct 2006 16:15:16 -0700
parents 7524d52d9577
children 97638d862ef3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
84
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
1 \chapter{A lightning tour of Mercurial}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
2 \label{chap:tour}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
3
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
4 \section{Installing Mercurial on your system}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
5 \label{sec:tour:install}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
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
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
11 \subsection{Linux}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
12
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
13 Because each Linux distribution has its own packaging tools, policies,
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
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
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
18
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
19 To keep things simple, I will focus on installing Mercurial from the
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
20 command line under the most popular Linux distributions. Most of
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
21 these distributions provide graphical package managers that will let
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
22 you install Mercurial with a single click; the package name to look
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
23 for is \texttt{mercurial}.
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
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
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
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
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
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
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
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
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
45
85
b7c69a68b0cc A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents: 84
diff changeset
46 \item[Ubuntu] Ubuntu's Mercurial package is particularly old, and you
b7c69a68b0cc A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents: 84
diff changeset
47 should not use it. If you know how, you can rebuild and install the
b7c69a68b0cc A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents: 84
diff changeset
48 Debian package. It's probably easier to build Mercurial from source
b7c69a68b0cc A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents: 84
diff changeset
49 and simply run that; see section~\ref{sec:srcinstall:unixlike} for
b7c69a68b0cc A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents: 84
diff changeset
50 details.
b7c69a68b0cc A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents: 84
diff changeset
51 \end{itemize}
84
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
52
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
53 \subsection{Mac OS X}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
54
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
55 Lee Cantey publishes an installer of Mercurial for Mac OS~X at
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
56 \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
57 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
58 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
59 is easy to do; simply follow the instructions on Lee's site.
84
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
60
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
61 \subsection{Solaris}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
62
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
63 XXX.
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
64
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
65 \subsection{Windows}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
66
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
67 Lee Cantey publishes an installer of Mercurial for Windows at
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
68 \url{http://mercurial.berkwood.com}. This package has no external
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
69 dependencies; it ``just works''.
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
70
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
71 \begin{note}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
72 The Windows version of Mercurial does not automatically convert line
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
73 endings between Windows and Unix styles. If you want to share work
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
74 with Unix users, you must do a little additional configuration
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
75 work. XXX Flesh this out.
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
76 \end{note}
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
77
87
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
78 \section{Getting started}
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
79
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
80 To begin, we'll use the \hgcmd{version} command to find out whether
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
81 Mercurial is actually installed properly. The actual version
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
82 information that it prints isn't so important; it's whether it prints
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
83 anything at all that we care about.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
84 \interaction{tour.version}
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
85
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
86 \subsection{Built-in help}
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
87
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
88 Mercurial provides a built-in help system. This invaluable for those
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
89 times when you find yourself stuck trying to remember how to run a
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
90 command. If you are completely stuck, simply run \hgcmd{help}; it
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
91 will print a brief list of commands, along with a description of what
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
92 each does. If you ask for help on a specific command (as below), it
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
93 prints more detailed information.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
94 \interaction{tour.help}
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
95 For a more impressive level of detail (which you won't usually need)
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
96 run \hgcmdargs{help}{\hggopt{-v}}. The \hggopt{-v} option is short
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
97 for \hggopt{--verbose}, and tells Mercurial to print more information
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
98 than it usually would.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
99
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
100 \section{Working with a repository}
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
101
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
102 In Mercurial, everything happens inside a \emph{repository}. The
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
103 repository for a project contains all of the files that ``belong to''
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
104 that project, along with a historical record of the project's files.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
105
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
106 There's nothing particularly magical about a repository; it is simply
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
107 a directory tree in your filesystem that Mercurial treats as special.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
108 You can rename delete a repository any time you like, using either the
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
109 command line or your file browser.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
110
88
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
111 \subsection{Making a local copy of a repository}
87
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
112
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
113 \emph{Copying} a repository is just a little bit special. While you
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
114 could use a normal file copying command to make a copy of a
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
115 repository, it's best to use a built-in command that Mercurial
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
116 provides. This command is called \hgcmd{clone}, because it creates an
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
117 identical copy of an existing repository.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
118 \interaction{tour.clone}
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
119 If our clone succeeded, we should now have a local directory called
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
120 \dirname{hello}. This directory will contain some files.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
121 \interaction{tour.ls}
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
122 These files have the same contents and history in our repository as
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
123 they do in the repository we cloned.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
124
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
125 Every Mercurial repository is complete, self-contained, and
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
126 independent. It contains its own private copy of a project's files
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
127 and history. A cloned repository remembers the location of the
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
128 repository it was cloned from, but it does not communicate with that
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
129 repository, or any other, unless you tell it to.
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
130
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
131 What this means for now is that we're free to experiment with our
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
132 repository, safe in the knowledge that it's a private ``sandbox'' that
0995016342f8 More bumf.
Bryan O'Sullivan <bos@serpentine.com>
parents: 85
diff changeset
133 won't affect anyone else.
85
b7c69a68b0cc A little progress on "lightning tour".
Bryan O'Sullivan <bos@serpentine.com>
parents: 84
diff changeset
134
88
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
135 \subsection{What's in a repository?}
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
136
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
137 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
138 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
139 keeps all of its metadata for the repository.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
140 \interaction{tour.ls-a}
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
141
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
142 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
143 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
144 repository is yours to do with as you please.
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 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
147 ``real'' repository, and all of the files and directories that coexist
91
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
148 with it are said to live in the \emph{working directory}. An easy way
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
149 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
150 \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
151 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
152 history.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
153
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
154 \section{A tour through history}
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
155
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
156 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
157 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
158 us a view of history.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
159 \interaction{tour.log}
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
160 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
161 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
162 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
163 contain a record of changes to several files.
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 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
166 \begin{itemize}
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
167 \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
168 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
169 \emph{identifiers} for the changeset. There are two identifiers
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
170 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
171 string.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
172 \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
173 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
174 person's name and email address.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
175 \item[\texttt{date}] The date and time on which the changeset was
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
176 created, and the timezone in which it was created. (Thef date and
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
177 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
178 was for the person who created the changeset.)
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
179 \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
180 creator of the changeset entered to describe the changeset.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
181 \end{itemize}
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
182 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
183 missing a lot of detail.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
184
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
185 \subsection{Changesets, revisions, and identification}
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
186
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
187 English being a notoriously sloppy language, we have a variety of
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
188 terms that have the same meaning. If you are talking about Mercurial
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
189 history with other people, you will find that the word ``changeset''
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
190 is often compressed to ``change'' or ``cset'', and sometimes a
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
191 changeset is referred to as a ``revision'' or a ``rev''.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
192
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
193 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
194 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
195 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
196 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
197 \hgcmd{log} identifies a changeset using both a number and a
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
198 hexadecimal string. The number is \emph{only valid in that
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
199 repository}, while the hex string is the \emph{permanent, unchanging
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
200 identifier} that will always identify that changeset in every copy
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
201 of the repository.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
202
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
203 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
204 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
205 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
206 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
207 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
208 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
209 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
210 while in another as $1,0,2$.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
211
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
212 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
213 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
214 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
215 the hexadecimal identifier.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
216
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
217 \subsection{Viewing specific revisions}
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
218
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
219 To narrow the output of \hgcmd{log} down to a single revision, use the
91
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
220 \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
221 revision number or a long-form changeset identifier, and you can
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
222 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
223
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
224 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
225 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
226 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
227 inclusive''.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
228 \interaction{tour.log.range}
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
229 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
230 \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
231 prints $4,3,2$.
d351032c189c Progress with log coverage.
Bryan O'Sullivan <bos@serpentine.com>
parents: 87
diff changeset
232
91
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
233 \subsection{More detailed information}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
234
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
235 While the summary information printed by \hgcmd{log} is useful if you
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
236 already know what you're looking for, you may need to see a complete
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
237 description of the change, or a list of the files changed, if you're
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
238 trying to decide whether a changeset is the one you're looking for.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
239 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
240 option gives you this extra detail.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
241 \interaction{tour.log-v}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
242
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
243 If you want to see both the description and content of a change, add
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
244 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
245 the content of a change as a \emph{unified diff} (if you've never seen
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
246 a unified diff before, see section~\ref{sec:mq:patch} for an overview).
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
247 \interaction{tour.log-vp}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
248
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
249 \section{All about command options}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
250
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
251 Let's take a brief break from exploring Mercurial commands to discuss
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
252 a pattern in the way that they work; you may find this useful to keep
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
253 in mind as we continiue our tour.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
254
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
255 Mercurial has a consistent and straightforward approach to dealing
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
256 with the options that you can pass to commands. It follows the
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
257 conventions for options that are common to modern Linux and Unix
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
258 systems.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
259 \begin{itemize}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
260 \item Every option has a long name. For example, as we've already
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
261 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
262 \item Most options have short names, too. Instead of
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
263 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
264 some options don't have short names is that the options in question
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
265 are rarely used.)
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
266 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
267 while short options start with one (e.g.~\hgopt{log}{-r}).
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
268 \item Option naming and usage is consistent across commands. For
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
269 example, every command that lets you specify a changeset~ID or
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
270 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
271 arguments.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
272 \end{itemize}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
273 In the examples throughout this book, I use short options instead of
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
274 long. This just reflects my own preference, so don't read anything
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
275 significant into it.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
276
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
277 Most commands that print output of some kind will print more output
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
278 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
279 when passed \hggopt{-q} (or \hggopt{--quiet}).
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
280
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
281 \section{Making and reviewing changes}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
282
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
283 Now that we have a grasp of viewing history in Mercurial, let's take a
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
284 look at making some changes and examining them.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
285
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
286 The first thing we'll do is isolate our experiment in a repository of
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
287 its own. We use the \hgcmd{clone} command, but we don't need to
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
288 clone a copy of the remote repository. Since we already have a copy
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
289 of it locally, we can just clone that instead. This is much faster
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
290 than cloning over the network, and cloning a local repository uses
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
291 less disk space in most cases, too.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
292 \interaction{tour.reclone}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
293 As an aside, it's often good practice to keep a ``pristine'' copy of a
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
294 remote repository around, which you can then make temporary clones of
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
295 to create sandboxes for each task you want to work on. This lets you
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
296 work on multiple tasks in parallel, each isolated from the others
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
297 until it's complete and you're ready to integrate it back. Because
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
298 local clones are so cheap, there's almost no overhead to cloning and
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
299 destroying repositories whenever you want.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
300
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
301 In our \dirname{my-hello} repository, we have a file
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
302 \filename{hello.c} that contains the classic ``hello, world'' program.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
303 Let's use the ancient and venerable \command{sed} command to edit this
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
304 file so that it prints a second line of output. (I'm only using
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
305 \command{sed} to do this because it's easy to write a scripted example
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
306 this way. Since you're not under the same constraint, you probably
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
307 won't want to use \command{sed}; simply use your preferred text editor to
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
308 do the same thing.)
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
309 \interaction{tour.sed}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
310
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
311 Mercurial's \hgcmd{status} command will tell us what Mercurial knows
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
312 about the files in the repository.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
313 \interaction{tour.status}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
314 The \hgcmd{status} command prints no output for some files, but a line
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
315 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
316 it to, \hgcmd{status} will not print any output for files that have
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
317 not been modified.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
318
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
319 The ``\texttt{M}'' indicates that Mercurial has noticed that we
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
320 modified \filename{hello.c}. Notice that we didn't need to
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
321 \emph{inform} Mercurial that we were going to modify the file before
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
322 we started, or that we had modified the file after we were done; it
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
323 was able to figure this out itself.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
324
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
325 It's a little bit helpful to know that we've modified
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
326 \filename{hello.c}, but we might prefer to know exactly \emph{what}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
327 changes we've made to it. To do this, we use the \hgcmd{diff}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
328 command.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
329 \interaction{tour.diff}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
330
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
331 \section{Recording changes in a new changeset}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
332
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
333 We can modify files, build and test our changes, and use
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
334 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
335 satisfied with what we've done and arrive at a natural stopping point
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
336 where we want to record our work in a new changeset.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
337
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
338 The \hgcmd{commit} command lets us create a new changeset; we'll
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
339 usually refer to this as ``making a commit'' or ``committing''.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
340
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
341 \subsection{Writing a commit message}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
342
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
343 When we commit a change, Mercurial drops us into a text editor, to
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
344 enter a message that will describe the modifications we've made in
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
345 this changeset. This is called the \emph{commit message}. It will be
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
346 a record for readers of what we did and why, and it will be printed by
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
347 \hgcmd{log} after we've finished committing.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
348 \interaction{tour.commit}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
349
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
350 The editor that the \hgcmd{commit} command drops us into will contain
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
351 an empty line, followed by a number of lines starting with
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
352 ``\texttt{HG:}''.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
353 \begin{codesample2}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
354 \emph{empty line}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
355 HG: changed hello.c
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
356 \end{codesample2}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
357 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
358 them only to tell us which files it's recording changes to. Modifying
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
359 or deleting these lines has no effect.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
360
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
361 \subsection{Writing a good commit message}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
362
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
363 Since \hgcmd{log} only prints the first line of a commit message by
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
364 default, it's best to write a commit message whose first line stands
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
365 alone. Here's a real example of a commit message that \emph{doesn't}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
366 follow this guideline, and hence has a summary that is not readable.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
367 \begin{codesample2}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
368 changeset: 73:584af0e231be
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
369 user: Censored Person <censored.person@example.org>
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
370 date: Tue Sep 26 21:37:07 2006 -0700
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
371 summary: include buildmeister/commondefs. Add an exports and install
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
372 \end{codesample2}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
373
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
374 As far as the remainder of the contents of the commit message are
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
375 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
376 interpret or care about the contents of the commit message, though
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
377 your project may have policies that dictate a certain kind of
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
378 formatting.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
379
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
380 My personal preference is for short, but informative, commit messages
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
381 that tell me something that I can't figure out with a quick glance at
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
382 the output of \hgcmdargs{log}{--patch}.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
383
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
384 \subsection{Aborting a commit}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
385
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
386 If you decide that you don't want to commit while in the middle of
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
387 editing a commit message, simply exit from your editor without saving
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
388 the file that it's editing. This will cause nothing to happen to
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
389 either the repository or the working directory.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
390
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
391 If we run the \hgcmd{commit} command without any arguments, it records
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
392 all of the changes we've made, as reported by \hgcmd{status} and
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
393 \hgcmd{diff}.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
394
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
395 \subsection{Admiring our new handywork}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
396
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
397 Once we've finished the commit, we can use the \hgcmd{tip} command to
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
398 display the changeset we just created. This command produces output
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
399 that is identical to \hgcmd{log}, but it only displays the newest
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
400 revision in the repository.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
401 \interaction{tour.tip}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
402 We refer to the newest revision in the repository as the tip revision,
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
403 or simply the tip.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
404
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
405 \section{Sharing changes}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
406
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
407 We mentioned earlier that repositories in Mercurial are
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
408 self-contained. This means that the changeset we just created exists
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
409 only in our \dirname{my-hello} repository. Let's look at a few ways
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
410 that we can propagate this change into other repositories.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
411
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
412 \subsection{Pulling changes from another repository}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
413 \label{sec:tour:pull}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
414
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
415 To get started, let's clone our original \dirname{hello} repository,
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
416 which does not contain the change we just committed. We'll call our
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
417 temporary repository \dirname{hello-pull}.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
418 \interaction{tour.clone-pull}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
419
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
420 We'll use the \hgcmd{pull} command to bring changes from
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
421 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
422 pulling unknown changes into a repository is a somewhat scary
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
423 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
424 what changes the \hgcmd{pull} command \emph{would} pull into the
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
425 repository, without actually pulling the changes in.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
426 \interaction{tour.incoming}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
427 (Of course, someone could cause more changesets to appear in the
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
428 repository that we ran \hgcmd{incoming} in, before we get a chance to
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
429 \hgcmd{pull} the changes, so that we could end up pulling changes that we
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
430 didn't expect.)
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
431
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
432 Bringing changes into a repository is a simple matter of running the
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
433 \hgcmd{pull} command, and telling it which repository to pull from.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
434 \interaction{tour.pull}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
435 As you can see from the before-and-after output of \hgcmd{tip}, we
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
436 have successfully pulled changes into our repository. There remains
92
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
437 one step before we can see these changes in the working directory.
91
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
438
92
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
439 \subsection{Updating the working directory}
91
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
440
92
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
441 We have so far glossed over the relationship between a repository and
91
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
442 its working directory. The \hgcmd{pull} command that we ran in
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
443 section~\ref{sec:tour:pull} brought changes into the repository, but
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
444 if we check, there's no sign of those changes in the working
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
445 directory. This is because \hgcmd{pull} does not (by default) touch
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
446 the working directory. Instead, we use the \hgcmd{update} command to
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
447 do this.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
448 \interaction{tour.update}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
449
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
450 It might seem a bit strange that \hgcmd{pull} doesn't update the
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
451 working directory automatically. There's actually a good reason for
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
452 this: you can use \hgcmd{update} to update the working directory to
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
453 the state it was in at \emph{any revision} in the history of the
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
454 repository. If you had the working directory updated to an old
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
455 revision---to hunt down the origin of a bug, say---and ran a
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
456 \hgcmd{pull} which automatically updated the working directory to a
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
457 new revision, you might not be terribly happy.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
458
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
459 However, since pull-then-update is such a common thing to do,
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
460 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
461 option to \hgcmd{pull}.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
462 \begin{codesample2}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
463 hg pull -u
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
464 \end{codesample2}
92
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
465 If you look back at the output of \hgcmd{pull} in
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
466 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
467 you can see that it printed a helpful reminder that we'd have to take
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
468 an explicit step to update the working directory:
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
469 \begin{codesample2}
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
470 (run 'hg update' to get a working copy)
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
471 \end{codesample2}
91
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
472
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
473 To find out what revision the working directory is at, use the
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
474 \hgcmd{parents} command.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
475 \interaction{tour.parents}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
476 To update the working directory to a particular revision, give a
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
477 revision number or changeset~ID to the \hgcmd{update} command.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
478 \interaction{tour.older}
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
479 If you omit an explicit revision, \hgcmd{update} will update to the
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
480 tip revision.
7524d52d9577 More tour progress.
Bryan O'Sullivan <bos@serpentine.com>
parents: 88
diff changeset
481
92
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
482 \subsection{Pushing changes to another repository}
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
483
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
484 Mercurial lets us push changes to another repository, from the
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
485 repository we're currently visiting. As with the example of
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
486 \hgcmd{pull} above, we'll create a temporary repository to push our
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
487 changes into.
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
488 \interaction{tour.clone-push}
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
489 The \hgcmd{outgoing} command tells us what changes would be pushed
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
490 into another repository.
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
491 \interaction{tour.outgoing}
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
492 And the \hgcmd{push} command does the actual push.
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
493 \interaction{tour.push}
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
494 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
495 working directory in the repository that it's pushing changes into.
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
496 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
497 option that updates the other repository's working directory.)
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
498
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
499 What happens if we try to pull or push changes and the receiving
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
500 repository already has those changes? Nothing too exciting.
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
501 \interaction{tour.push.nothing}
72d207927dc4 Tour: push.
Bryan O'Sullivan <bos@serpentine.com>
parents: 91
diff changeset
502
84
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
503 %%% Local Variables:
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
504 %%% mode: latex
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
505 %%% TeX-master: "00book"
43b9793b4e38 Begin tour chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
506 %%% End: