hgbook
diff en/ch01-tour-basic.xml @ 609:c44d5854620b
Fix up chapter 1.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Tue Mar 31 22:38:30 2009 -0700 (2009-03-31) |
| parents | 0b45854f0b7b |
| children | 3b33dd6aba87 |
line diff
1.1 --- a/en/ch01-tour-basic.xml Thu Mar 26 22:00:53 2009 -0700 1.2 +++ b/en/ch01-tour-basic.xml Tue Mar 31 22:38:30 2009 -0700 1.3 @@ -12,6 +12,26 @@ 1.4 using Mercurial on your computer immediately.</para> 1.5 1.6 <sect2> 1.7 + <title>Windows</title> 1.8 + 1.9 + <para id="x_c">The best version of Mercurial for Windows is 1.10 + TortoiseHg, which can be found at <ulink 1.11 + url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 1.12 + This package has no external dependencies; it <quote>just 1.13 + works</quote>. It provides both command line and graphical 1.14 + user interfaces.</para> 1.15 + 1.16 + </sect2> 1.17 + 1.18 + <sect2> 1.19 + <title>Mac OS X</title> 1.20 + 1.21 + <para id="x_a">Lee Cantey publishes an installer of Mercurial 1.22 + for Mac OS X at <ulink 1.23 + url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para> 1.24 + </sect2> 1.25 + 1.26 + <sect2> 1.27 <title>Linux</title> 1.28 1.29 <para id="x_2">Because each Linux distribution has its own packaging 1.30 @@ -29,18 +49,12 @@ 1.31 <literal>mercurial</literal>.</para> 1.32 1.33 <itemizedlist> 1.34 - <listitem><para id="x_4">Debian:</para> 1.35 + <listitem><para id="x_4">Ubuntu and Debian:</para> 1.36 <programlisting>apt-get install mercurial</programlisting></listitem> 1.37 - <listitem><para id="x_5">Fedora Core:</para> 1.38 + <listitem><para id="x_5">Fedora and OpenSUSE:</para> 1.39 <programlisting>yum install mercurial</programlisting></listitem> 1.40 <listitem><para id="x_6">Gentoo:</para> 1.41 <programlisting>emerge mercurial</programlisting></listitem> 1.42 - <listitem><para id="x_7">OpenSUSE:</para> 1.43 - <programlisting>yum install mercurial</programlisting></listitem> 1.44 - <listitem><para id="x_8">Ubuntu: Ubuntu's Mercurial package is based on 1.45 - Debian's. To install it, run the following 1.46 - command.</para> 1.47 - <programlisting>apt-get install mercurial</programlisting></listitem> 1.48 </itemizedlist> 1.49 1.50 </sect2> 1.51 @@ -49,49 +63,12 @@ 1.52 1.53 <para id="x_9">SunFreeWare, at <ulink 1.54 url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 1.55 - is a good source for a large number of pre-built Solaris 1.56 - packages for 32 and 64 bit Intel and Sparc architectures, 1.57 - including current versions of Mercurial.</para> 1.58 - 1.59 - </sect2> 1.60 - <sect2> 1.61 - <title>Mac OS X</title> 1.62 - 1.63 - <para id="x_a">Lee Cantey publishes an installer of Mercurial for Mac OS 1.64 - X at <ulink 1.65 - url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 1.66 - This package works on both Intel- and Power-based Macs. Before 1.67 - you can use it, you must install a compatible version of 1.68 - Universal MacPython <citation>web:macpython</citation>. This 1.69 - is easy to do; simply follow the instructions on Lee's 1.70 - site.</para> 1.71 - 1.72 - <para id="x_b">It's also possible to install Mercurial using Fink or 1.73 - MacPorts, two popular free package managers for Mac OS X. If 1.74 - you have Fink, use <command>sudo apt-get install 1.75 - mercurial-py25</command>. If MacPorts, <command>sudo port 1.76 - install mercurial</command>.</para> 1.77 - 1.78 - </sect2> 1.79 - <sect2> 1.80 - <title>Windows</title> 1.81 - 1.82 - <para id="x_c">Lee Cantey publishes an installer of Mercurial for Windows 1.83 - at <ulink 1.84 - url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 1.85 - This package has no external dependencies; it <quote>just 1.86 - works</quote>.</para> 1.87 - 1.88 - <note> 1.89 - <para id="x_d"> The Windows version of Mercurial does not 1.90 - automatically convert line endings between Windows and Unix 1.91 - styles. If you want to share work with Unix users, you must 1.92 - do a little additional configuration work. XXX Flesh this 1.93 - out.</para> 1.94 - </note> 1.95 - 1.96 - </sect2> 1.97 + provides prebuilt packages of Mercurial.</para> 1.98 + 1.99 + </sect2> 1.100 + 1.101 </sect1> 1.102 + 1.103 <sect1> 1.104 <title>Getting started</title> 1.105 1.106 @@ -150,10 +127,16 @@ 1.107 command to make a copy of a repository, it's best to use a 1.108 built-in command that Mercurial provides. This command is 1.109 called <command role="hg-cmd">hg clone</command>, because it 1.110 - creates an identical copy of an existing repository.</para> 1.111 + makes an identical copy of an existing repository.</para> 1.112 1.113 &interaction.tour.clone; 1.114 1.115 + <para>One advantage of using <command role="hg-cmd">hg 1.116 + clone</command> is that, as we can see above, it lets us clone 1.117 + repositories over the network. Another is that it remembers 1.118 + where we cloned from, which we'll find useful soon when we 1.119 + want to fetch new changes from another repository.</para> 1.120 + 1.121 <para id="x_14">If our clone succeeded, we should now have a local 1.122 directory called <filename class="directory">hello</filename>. 1.123 This directory will contain some files.</para> 1.124 @@ -163,12 +146,12 @@ 1.125 <para id="x_15">These files have the same contents and history in our 1.126 repository as they do in the repository we cloned.</para> 1.127 1.128 - <para id="x_16">Every Mercurial repository is complete, self-contained, 1.129 - and independent. It contains its own private copy of a 1.130 - project's files and history. A cloned repository remembers 1.131 - the location of the repository it was cloned from, but it does 1.132 - not communicate with that repository, or any other, unless you 1.133 - tell it to.</para> 1.134 + <para id="x_16">Every Mercurial repository is complete, 1.135 + self-contained, and independent. It contains its own private 1.136 + copy of a project's files and history. As we just mentioned, 1.137 + a cloned repository remembers the location of the repository 1.138 + it was cloned from, but Mercurial will not communicate with 1.139 + that repository, or any other, unless you tell it to.</para> 1.140 1.141 <para id="x_17">What this means for now is that we're free to experiment 1.142 with our repository, safe in the knowledge that it's a private 1.143 @@ -211,7 +194,7 @@ 1.144 <para id="x_1b">One of the first things we might want to do with a new, 1.145 unfamiliar repository is understand its history. The <command 1.146 role="hg-cmd">hg log</command> command gives us a view of 1.147 - history.</para> 1.148 + the history of changes in the repository.</para> 1.149 1.150 &interaction.tour.log; 1.151 1.152 @@ -223,13 +206,20 @@ 1.153 1.154 <para id="x_1d">The fields in a record of output from <command 1.155 role="hg-cmd">hg log</command> are as follows.</para> 1.156 + 1.157 <itemizedlist> 1.158 - <listitem><para id="x_1e"><literal>changeset</literal>: This field has the 1.159 - format of a number, followed by a colon, followed by a 1.160 - hexadecimal string. These are 1.161 - <emphasis>identifiers</emphasis> for the changeset. There 1.162 - are two identifiers because the number is shorter and easier 1.163 - to type than the hex string.</para></listitem> 1.164 + <listitem><para id="x_1e"><literal>changeset</literal>: This 1.165 + field has the format of a number, followed by a colon, 1.166 + followed by a hexadecimal (or <emphasis>hex</emphasis>) 1.167 + string. These are <emphasis>identifiers</emphasis> for the 1.168 + changeset. The hex string is a unique identifier: the same 1.169 + hex string will always refer to the same changeset. The 1.170 + number is shorter and easier to type than the hex string, 1.171 + but it isn't unique: the same number in two different clones 1.172 + of a repository may identify different changesets. Why 1.173 + provide the number at all, then? For local 1.174 + convenience.</para> 1.175 + </listitem> 1.176 <listitem><para id="x_1f"><literal>user</literal>: The identity of the 1.177 person who created the changeset. This is a free-form 1.178 field, but it most often contains a person's name and email 1.179 @@ -241,10 +231,19 @@ 1.180 person who created the changeset.)</para></listitem> 1.181 <listitem><para id="x_21"><literal>summary</literal>: The first line of 1.182 the text message that the creator of the changeset entered 1.183 - to describe the changeset.</para></listitem></itemizedlist> 1.184 - <para id="x_22">The default output printed by <command role="hg-cmd">hg 1.185 - log</command> is purely a summary; it is missing a lot of 1.186 - detail.</para> 1.187 + to describe the changeset.</para></listitem> 1.188 + <listitem> 1.189 + <para>Some changesets, such as the first in the list above, 1.190 + have a <literal>tag</literal> field. A tag is another way 1.191 + to identify a changeset, by giving it an easy-to-remember 1.192 + name. (The tag named <literal>tip</literal> is special: it 1.193 + always refers to the newest change in a repository.)</para> 1.194 + </listitem> 1.195 + </itemizedlist> 1.196 + 1.197 + <para id="x_22">The default output printed by <command 1.198 + role="hg-cmd">hg log</command> is purely a summary; it is 1.199 + missing a lot of detail.</para> 1.200 1.201 <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides 1.202 a graphical representation of the history of the <filename 1.203 @@ -286,22 +285,26 @@ 1.204 log</command> identifies a changeset using both a number and 1.205 a hexadecimal string.</para> 1.206 <itemizedlist> 1.207 - <listitem><para id="x_27">The revision number is <emphasis>only valid in 1.208 - that repository</emphasis>,</para></listitem> 1.209 - <listitem><para id="x_28">while the hex string is the 1.210 + <listitem><para id="x_27">The revision number is a handy 1.211 + notation that is <emphasis>only valid in that 1.212 + repository</emphasis>.</para></listitem> 1.213 + <listitem><para id="x_28">The hexadecimal string is the 1.214 <emphasis>permanent, unchanging identifier</emphasis> that 1.215 will always identify that exact changeset in 1.216 <emphasis>every</emphasis> copy of the 1.217 repository.</para></listitem></itemizedlist> 1.218 - <para id="x_29">This distinction is important. If you send someone an 1.219 - email talking about <quote>revision 33</quote>, there's a high 1.220 - likelihood that their revision 33 will <emphasis>not be the 1.221 - same</emphasis> as yours. The reason for this is that a 1.222 - revision number depends on the order in which changes arrived 1.223 - in a repository, and there is no guarantee that the same 1.224 - changes will happen in the same order in different 1.225 - repositories. Three changes $a,b,c$ can easily appear in one 1.226 - repository as $0,1,2$, while in another as $1,0,2$.</para> 1.227 + 1.228 + <para id="x_29">This distinction is important. If you send 1.229 + someone an email talking about <quote>revision 33</quote>, 1.230 + there's a high likelihood that their revision 33 will 1.231 + <emphasis>not be the same</emphasis> as yours. The reason for 1.232 + this is that a revision number depends on the order in which 1.233 + changes arrived in a repository, and there is no guarantee 1.234 + that the same changes will happen in the same order in 1.235 + different repositories. Three changes <literal>a,b,c</literal> 1.236 + can easily appear in one repository as 1.237 + <literal>0,1,2</literal>, while in another as 1.238 + <literal>0,2,1</literal>.</para> 1.239 1.240 <para id="x_2a">Mercurial uses revision numbers purely as a convenient 1.241 shorthand. If you need to discuss a changeset with someone, 1.242 @@ -317,7 +320,7 @@ 1.243 log</command> down to a single revision, use the <option 1.244 role="hg-opt-log">-r</option> (or <option 1.245 role="hg-opt-log">--rev</option>) option. You can use 1.246 - either a revision number or a long-form changeset identifier, 1.247 + either a revision number or a hexadecimal identifier, 1.248 and you can provide as many revisions as you want.</para> 1.249 1.250 &interaction.tour.log-r; 1.251 @@ -361,8 +364,12 @@ 1.252 1.253 &interaction.tour.log-vp; 1.254 1.255 + <para>The <option role="hg-opt-log">-p</option> option is 1.256 + tremendously useful, so it's well worth remembering.</para> 1.257 + 1.258 </sect2> 1.259 </sect1> 1.260 + 1.261 <sect1> 1.262 <title>All about command options</title> 1.263 1.264 @@ -374,26 +381,42 @@ 1.265 dealing with the options that you can pass to commands. It 1.266 follows the conventions for options that are common to modern 1.267 Linux and Unix systems.</para> 1.268 + 1.269 <itemizedlist> 1.270 - <listitem><para id="x_32">Every option has a long name. For example, as 1.271 + <listitem> 1.272 + <para id="x_32">Every option has a long name. For example, as 1.273 we've already seen, the <command role="hg-cmd">hg 1.274 log</command> command accepts a <option 1.275 - role="hg-opt-log">--rev</option> option.</para></listitem> 1.276 - <listitem><para id="x_33">Most options have short names, too. Instead of 1.277 - <option role="hg-opt-log">--rev</option>, we can use <option 1.278 - role="hg-opt-log">-r</option>. (The reason that some 1.279 - options don't have short names is that the options in 1.280 - question are rarely used.)</para></listitem> 1.281 - <listitem><para id="x_34">Long options start with two dashes (e.g. <option 1.282 - role="hg-opt-log">--rev</option>), while short options 1.283 - start with one (e.g. <option 1.284 - role="hg-opt-log">-r</option>).</para></listitem> 1.285 - <listitem><para id="x_35">Option naming and usage is consistent across 1.286 + role="hg-opt-log">--rev</option> option.</para> 1.287 + </listitem> 1.288 + <listitem> 1.289 + <para id="x_33">Most options have short names, too. Instead 1.290 + of <option role="hg-opt-log">--rev</option>, we can use 1.291 + <option role="hg-opt-log">-r</option>. (The reason that 1.292 + some options don't have short names is that the options in 1.293 + question are rarely used.)</para> 1.294 + </listitem> 1.295 + <listitem> 1.296 + <para id="x_34">Long options start with two dashes (e.g. 1.297 + <option role="hg-opt-log">--rev</option>), while short 1.298 + options start with one (e.g. <option 1.299 + role="hg-opt-log">-r</option>).</para> 1.300 + </listitem> 1.301 + <listitem> 1.302 + <para id="x_35">Option naming and usage is consistent across 1.303 commands. For example, every command that lets you specify 1.304 a changeset ID or revision number accepts both <option 1.305 role="hg-opt-log">-r</option> and <option 1.306 - role="hg-opt-log">--rev</option> 1.307 - arguments.</para></listitem></itemizedlist> 1.308 + role="hg-opt-log">--rev</option> arguments.</para> 1.309 + </listitem> 1.310 + <listitem> 1.311 + <para>If you are using short options, you can save typing by 1.312 + running them together. For example, the command <command 1.313 + role="hg-cmd">hg log -v -p -r 2</command> can be written 1.314 + as <command role="hg-cmd">hg log -vpr2</command>.</para> 1.315 + </listitem> 1.316 + </itemizedlist> 1.317 + 1.318 <para id="x_36">In the examples throughout this book, I use short options 1.319 instead of long. This just reflects my own preference, so don't 1.320 read anything significant into it.</para> 1.321 @@ -404,6 +427,18 @@ 1.322 less when passed <option role="hg-opt-global">-q</option> (or 1.323 <option role="hg-opt-global">--quiet</option>).</para> 1.324 1.325 + <note> 1.326 + <title>Option naming consistency</title> 1.327 + 1.328 + <para>Almost always, Mercurial commands use consistent option 1.329 + names to refer to the same concepts. For instance, if a 1.330 + command deals with changesets, you'll always identify them 1.331 + with <option role="hg-opt-log">--rev</option> or <option 1.332 + role="hg-opt-log">-r</option>. This consistent use of 1.333 + option names makes it easier to remember what options a 1.334 + particular command takes.</para> 1.335 + </note> 1.336 + 1.337 </sect1> 1.338 <sect1> 1.339 <title>Making and reviewing changes</title> 1.340 @@ -418,7 +453,14 @@ 1.341 the remote repository. Since we already have a copy of it 1.342 locally, we can just clone that instead. This is much faster 1.343 than cloning over the network, and cloning a local repository 1.344 - uses less disk space in most cases, too.</para> 1.345 + uses less disk space in most cases, too<footnote> 1.346 + <para>The saving of space arises when source and destination 1.347 + repositories are on the same filesystem, in which case 1.348 + Mercurial will use hardlinks to do copy-on-write sharing of 1.349 + its internal metadata. If that explanation meant nothing to 1.350 + you, don't worry: everything happens transparently and 1.351 + automatically, and you don't need to understand it.</para> 1.352 + </footnote>.</para> 1.353 1.354 &interaction.tour.reclone; 1.355 1.356 @@ -433,16 +475,14 @@ 1.357 1.358 <para id="x_3b">In our <filename class="directory">my-hello</filename> 1.359 repository, we have a file <filename>hello.c</filename> that 1.360 - contains the classic <quote>hello, world</quote> program. Let's 1.361 - use the ancient and venerable <command>sed</command> command to 1.362 - edit this file so that it prints a second line of output. (I'm 1.363 - only using <command>sed</command> to do this because it's easy 1.364 - to write a scripted example this way. Since you're not under 1.365 - the same constraint, you probably won't want to use 1.366 - <command>sed</command>; simply use your preferred text editor to 1.367 - do the same thing.)</para> 1.368 - 1.369 - &interaction.tour.sed; 1.370 + contains the classic <quote>hello, world</quote> program.</para> 1.371 + 1.372 + &interaction.tour.cat1; 1.373 + 1.374 + <para>Let's edit this file so that it prints a second line of 1.375 + output.</para> 1.376 + 1.377 + &interaction.tour.cat2; 1.378 1.379 <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command> 1.380 command will tell us what Mercurial knows about the files in the 1.381 @@ -465,7 +505,7 @@ 1.382 file after we were done; it was able to figure this out 1.383 itself.</para> 1.384 1.385 - <para id="x_3f">It's a little bit helpful to know that we've modified 1.386 + <para id="x_3f">It's somewhat helpful to know that we've modified 1.387 <filename>hello.c</filename>, but we might prefer to know 1.388 exactly <emphasis>what</emphasis> changes we've made to it. To 1.389 do this, we use the <command role="hg-cmd">hg diff</command> 1.390 @@ -473,6 +513,13 @@ 1.391 1.392 &interaction.tour.diff; 1.393 1.394 + <tip> 1.395 + <title>Understanding patches</title> 1.396 + 1.397 + <para>Remember to take a look at <xref 1.398 + linkend="sec:mq:patch"/> if you don't know how to read 1.399 + output above.</para> 1.400 + </tip> 1.401 </sect1> 1.402 <sect1> 1.403 <title>Recording changes in a new changeset</title> 1.404 @@ -549,10 +596,13 @@ 1.405 configuration settings. The initial contents of your 1.406 <filename role="special">.hgrc</filename> should look like 1.407 this.</para> 1.408 + 1.409 + <remark>Figure out what the appropriate directory is on 1.410 + Windows.</remark> 1.411 + 1.412 <programlisting># This is a Mercurial configuration file. 1.413 [ui] 1.414 -username = Firstname Lastname 1.415 -<email.address@domain.net></programlisting> 1.416 +username = Firstname Lastname <email.address@domain.net></programlisting> 1.417 1.418 <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a 1.419 <emphasis>section</emphasis> of the config file, so you can 1.420 @@ -571,8 +621,8 @@ 1.421 1.422 <para id="x_4c">You can use any text you like as the value of 1.423 the <literal>username</literal> config item, since this 1.424 - information is for reading by other people, but for 1.425 - interpreting by Mercurial. The convention that most 1.426 + information is for reading by other people, but will not be 1.427 + interpreted by Mercurial. The convention that most 1.428 people follow is to use their name and email address, as 1.429 in the example above.</para> 1.430 <note> 1.431 @@ -600,10 +650,17 @@ 1.432 1.433 <para id="x_4f">The editor that the <command role="hg-cmd">hg 1.434 commit</command> command drops us into will contain an 1.435 - empty line, followed by a number of lines starting with 1.436 + empty line or two, followed by a number of lines starting with 1.437 <quote><literal>HG:</literal></quote>.</para> 1.438 1.439 - <programlisting>XXX fix this XXX</programlisting> 1.440 + <programlisting> 1.441 +This is where I type my commit comment. 1.442 + 1.443 +HG: Enter commit message. Lines beginning with 'HG:' are removed. 1.444 +HG: -- 1.445 +HG: user: Bryan O'Sullivan <bos@serpentine.com> 1.446 +HG: branch 'default' 1.447 +HG: changed hello.c</programlisting> 1.448 1.449 <para id="x_50">Mercurial ignores the lines that start with 1.450 <quote><literal>HG:</literal></quote>; it uses them only to 1.451 @@ -665,9 +722,18 @@ 1.452 1.453 &interaction.tour.tip; 1.454 1.455 - <para id="x_57">We refer to 1.456 - the newest revision in the repository as the tip revision, 1.457 - or simply the tip.</para> 1.458 + <para id="x_57">We refer to the newest revision in the 1.459 + repository as the <emphasis>tip revision</emphasis>, or simply 1.460 + the <emphasis>tip</emphasis>.</para> 1.461 + 1.462 + <para>By the way, the <command role="hg-cmd">hg tip</command> 1.463 + command accepts many of the same options as <command 1.464 + role="hg-cmd">hg log</command>, so <option 1.465 + role="hg-opt-global">-v</option> above indicates <quote>be 1.466 + verbose</quote>, <option role="hg-opt-tip">-p</option> 1.467 + specifies <quote>print a patch</quote>. The use of <option 1.468 + role="hg-opt-tip">-p</option> to print patches is another 1.469 + example of the consistent naming we mentioned earlier.</para> 1.470 </sect2> 1.471 </sect1> 1.472 1.473 @@ -704,12 +770,13 @@ 1.474 1.475 &interaction.tour.incoming; 1.476 1.477 - <para id="x_5b">(Of course, someone could 1.478 - cause more changesets to appear in the repository that we 1.479 - ran <command role="hg-cmd">hg incoming</command> in, before 1.480 - we get a chance to <command role="hg-cmd">hg pull</command> 1.481 - the changes, so that we could end up pulling changes that we 1.482 - didn't expect.)</para> 1.483 + <para id="x_5b">Suppose you're pulling changes from a repository 1.484 + on the network somewhere. While you are looking at the <command 1.485 + role="hg-cmd">hg incoming</command> output, and before you 1.486 + pull those changes, someone might have committed something in 1.487 + the remote repository. This means that it's possible to pull 1.488 + more changes than you saw when using <command 1.489 + role="hg-cmd">hg incoming</command>.</para> 1.490 1.491 <para id="x_5c">Bringing changes into a repository is a simple 1.492 matter of running the <command role="hg-cmd">hg 1.493 @@ -746,8 +813,8 @@ 1.494 can use <command role="hg-cmd">hg update</command> to update 1.495 the working directory to the state it was in at <emphasis>any 1.496 revision</emphasis> in the history of the repository. If 1.497 - you had the working directory updated to an old revision---to 1.498 - hunt down the origin of a bug, say---and ran a <command 1.499 + you had the working directory updated to an old revision&emdash;to 1.500 + hunt down the origin of a bug, say&emdash;and ran a <command 1.501 role="hg-cmd">hg pull</command> which automatically updated 1.502 the working directory to a new revision, you might not be 1.503 terribly happy.</para> 1.504 @@ -817,14 +884,17 @@ 1.505 1.506 &interaction.tour.push; 1.507 1.508 - <para id="x_69">As with 1.509 - <command role="hg-cmd">hg pull</command>, the <command 1.510 - role="hg-cmd">hg push</command> command does not update 1.511 - the working directory in the repository that it's pushing 1.512 - changes into. (Unlike <command role="hg-cmd">hg 1.513 - pull</command>, <command role="hg-cmd">hg push</command> 1.514 - does not provide a <literal>-u</literal> option that updates 1.515 - the other repository's working directory.)</para> 1.516 + <para id="x_69">As with <command role="hg-cmd">hg 1.517 + pull</command>, the <command role="hg-cmd">hg push</command> 1.518 + command does not update the working directory in the 1.519 + repository that it's pushing changes into. Unlike <command 1.520 + role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg 1.521 + push</command> does not provide a <literal>-u</literal> 1.522 + option that updates the other repository's working directory. 1.523 + This asymmetry is deliberate: the repository we're pushing to 1.524 + might be on a remote server and shared between several people. 1.525 + If we were to update its working directory while someone was 1.526 + working in it, their work would be disrupted.</para> 1.527 1.528 <para id="x_6a">What happens if we try to pull or push changes 1.529 and the receiving repository already has those changes?