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