hgbook
changeset 699:a17d6390a480
More fixes to chapters 1 and 2.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Sun May 03 20:27:09 2009 -0700 (2009-05-03) |
parents | d7d09cda83d2 |
children | d2aacc06e562 |
files | en/ch01-tour-basic.xml en/ch02-tour-merge.xml en/examples/auto-snippets.xml en/examples/ch01/new en/examples/tour |
line diff
1.1 --- a/en/ch01-tour-basic.xml Sun May 03 19:23:31 2009 -0700 1.2 +++ b/en/ch01-tour-basic.xml Sun May 03 20:27:09 2009 -0700 1.3 @@ -867,9 +867,7 @@ 1.4 linkend="sec:tour:pull"/> when we ran it without <option 1.5 role="hg-opt-pull">-u</option>, you can see that it printed 1.6 a helpful reminder that we'd have to take an explicit step to 1.7 - update the working directory:</para> 1.8 - 1.9 - <!-- &interaction.xxx.fixme; --> 1.10 + update the working directory.</para> 1.11 1.12 <para id="x_62">To find out what revision the working directory 1.13 is at, use the <command role="hg-cmd">hg parents</command> 1.14 @@ -990,6 +988,44 @@ 1.15 &interaction.tour.push.net; 1.16 </sect2> 1.17 </sect1> 1.18 + 1.19 + <sect1> 1.20 + <title>Starting a new project</title> 1.21 + 1.22 + <para>It is just as easy to begin a new project as to work on one 1.23 + that already exists. The <command>hg init</command> command 1.24 + creates a new, empty Mercurial repository.</para> 1.25 + 1.26 + &interaction.ch01-new.init; 1.27 + 1.28 + <para>This simply creates a repository named 1.29 + <filename>myproject</filename> in the current directory.</para> 1.30 + 1.31 + &interaction.ch01-new.ls; 1.32 + 1.33 + <para>We can tell that <filename>myproject</filename> is a 1.34 + Mercurial repository, because it contains a 1.35 + <filename>.hg</filename> directory.</para> 1.36 + 1.37 + &interaction.ch01-new.ls2; 1.38 + 1.39 + <para>If we want to add some pre-existing files to the repository, 1.40 + we copy them into place, and tell Mercurial to start tracking 1.41 + them using the <command>hg add</command> command.</para> 1.42 + 1.43 + &interaction.ch01-new.add; 1.44 + 1.45 + <para>Once we are satisfied that our project looks right, we 1.46 + commit our changes.</para> 1.47 + 1.48 + &interaction.ch01-new.commit; 1.49 + 1.50 + <para>It takes just a few moments to start using Mercurial on a 1.51 + new project, which is part of its appeal. Revision control is 1.52 + now so easy to work with, we can use it on the smallest of 1.53 + projects that we might not have considered with a more 1.54 + complicated tool.</para> 1.55 + </sect1> 1.56 </chapter> 1.57 1.58 <!--
2.1 --- a/en/ch02-tour-merge.xml Sun May 03 19:23:31 2009 -0700 2.2 +++ b/en/ch02-tour-merge.xml Sun May 03 20:27:09 2009 -0700 2.3 @@ -13,24 +13,29 @@ 2.4 <title>Merging streams of work</title> 2.5 2.6 <para id="x_339">Merging is a fundamental part of working with a distributed 2.7 - revision control tool.</para> 2.8 + revision control tool. Here are a few cases in which the need 2.9 + to merge work arises.</para> 2.10 <itemizedlist> 2.11 - <listitem><para id="x_33a">Alice and Bob each have a personal copy of a 2.12 + <listitem> 2.13 + <para id="x_33a">Alice and Bob each have a personal copy of a 2.14 repository for a project they're collaborating on. Alice 2.15 fixes a bug in her repository; Bob adds a new feature in 2.16 his. They want the shared repository to contain both the 2.17 bug fix and the new feature.</para> 2.18 </listitem> 2.19 - <listitem><para id="x_33b">I frequently work on several different tasks for 2.20 - a single project at once, each safely isolated in its own 2.21 - repository. Working this way means that I often need to 2.22 - merge one piece of my own work with another.</para> 2.23 - </listitem></itemizedlist> 2.24 - 2.25 - <para id="x_33c">Because merging is such a common thing to need to do, 2.26 - Mercurial makes it easy. Let's walk through the process. We'll 2.27 - begin by cloning yet another repository (see how often they 2.28 - spring up?) and making a change in it.</para> 2.29 + <listitem> 2.30 + <para id="x_33b">Cynthia frequently works on several different 2.31 + tasks for a single project at once, each safely isolated in 2.32 + its own repository. Working this way means that she often 2.33 + needs to merge one piece of her own work with 2.34 + another.</para> 2.35 + </listitem> 2.36 + </itemizedlist> 2.37 + 2.38 + <para id="x_33c">Because we need to merge often, Mercurial makes 2.39 + the process easy. Let's walk through a merge. We'll begin by 2.40 + cloning yet another repository (see how often they spring up?) 2.41 + and making a change in it.</para> 2.42 2.43 &interaction.tour.merge.clone; 2.44 2.45 @@ -38,9 +43,15 @@ 2.46 <filename>hello.c</filename> with different contents. The 2.47 histories of the two repositories have also diverged, as 2.48 illustrated in <xref 2.49 - linkend="fig:tour-merge:sep-repos"/>.</para> 2.50 - 2.51 - &interaction.tour.merge.cat; 2.52 + linkend="fig:tour-merge:sep-repos"/>. Here is a copy of our 2.53 + file from one repository.</para> 2.54 + 2.55 + &interaction.tour.merge.cat1; 2.56 + 2.57 + <para>And here is our slightly different version from the other 2.58 + repository.</para> 2.59 + 2.60 + &interaction.tour.merge.cat2; 2.61 2.62 <figure id="fig:tour-merge:sep-repos"> 2.63 <title>Divergent recent histories of the <filename 2.64 @@ -65,10 +76,12 @@ 2.65 <sect2> 2.66 <title>Head changesets</title> 2.67 2.68 - <para id="x_341">A head is a change that has no descendants, or children, 2.69 - as they're also known. The tip revision is thus a head, 2.70 - because the newest revision in a repository doesn't have any 2.71 - children, but a repository can contain more than one 2.72 + <para id="x_341">Remember that Mercurial records what the parent 2.73 + of each change is. If a change has a parent, we call it a 2.74 + child or descendant of the parent. A head is a change that 2.75 + has no children. The tip revision is thus a head, because the 2.76 + newest revision in a repository doesn't have any children. 2.77 + There are times when a repository can contain more than one 2.78 head.</para> 2.79 2.80 <figure id="fig:tour-merge:pull"> 2.81 @@ -99,8 +112,8 @@ 2.82 role="hg-cmd">hg heads</command> command.</para> 2.83 2.84 &interaction.tour.merge.heads; 2.85 - 2.86 </sect2> 2.87 + 2.88 <sect2> 2.89 <title>Performing the merge</title> 2.90 2.91 @@ -110,23 +123,28 @@ 2.92 2.93 &interaction.tour.merge.update; 2.94 2.95 - <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg 2.96 - update</command> command won't do a merge; it won't update 2.97 - the working directory when it thinks we might want to do 2.98 - a merge, unless we force it to do so. Instead, we use the 2.99 - <command role="hg-cmd">hg merge</command> command to merge the 2.100 - two heads.</para> 2.101 + <para id="x_345">Mercurial is telling us that the <command 2.102 + role="hg-cmd">hg update</command> command won't do a merge; 2.103 + it won't update the working directory when it thinks we might 2.104 + want to do a merge, unless we force it to do so. 2.105 + (Incidentally, forcing the update with <command>hg update 2.106 + -C</command> would revert any uncommitted changes in the 2.107 + working directory.)</para> 2.108 + 2.109 + <para>To start a merge between the two heads, we use the 2.110 + <command role="hg-cmd">hg merge</command> command.</para> 2.111 2.112 &interaction.tour.merge.merge; 2.113 2.114 - <para id="x_347">This updates the working directory so that it contains 2.115 - changes from <emphasis>both</emphasis> heads, which is 2.116 - reflected in both the output of <command role="hg-cmd">hg 2.117 + <para id="x_347">We resolve the contents of <filename>hello.c</filename> 2.118 + 2.119 +This updates the working directory so that it 2.120 + contains changes from <emphasis>both</emphasis> heads, which 2.121 + is reflected in both the output of <command role="hg-cmd">hg 2.122 parents</command> and the contents of 2.123 <filename>hello.c</filename>.</para> 2.124 2.125 &interaction.tour.merge.parents; 2.126 - 2.127 </sect2> 2.128 <sect2> 2.129 <title>Committing the results of the merge</title> 2.130 @@ -208,8 +226,8 @@ 2.131 human guidance) or aren't present, it tries a few 2.132 different graphical merging tools.</para> 2.133 2.134 - <para id="x_34f">It's also possible to get Mercurial to run another program 2.135 - or script instead of <command>hgmerge</command>, by setting the 2.136 + <para id="x_34f">It's also possible to get Mercurial to run a 2.137 + specific program or script, by setting the 2.138 <envar>HGMERGE</envar> environment variable to the name of your 2.139 preferred program.</para> 2.140 2.141 @@ -310,7 +328,8 @@ 2.142 non-interactive <command>merge</command> command. This is 2.143 bundled with many Unix-like systems. (If you're following this 2.144 example on your computer, don't bother setting 2.145 - <envar>HGMERGE</envar>.)</para> 2.146 + <envar>HGMERGE</envar>. You'll get dropped into a GUI file 2.147 + merge tool instead, which is much preferable.)</para> 2.148 2.149 &interaction.tour-merge-conflict.merge; 2.150 2.151 @@ -333,6 +352,17 @@ 2.152 2.153 &interaction.tour-merge-conflict.commit; 2.154 2.155 + <note> 2.156 + <title>Where is the <command>hg resolve</command> command?</title> 2.157 + 2.158 + <para>The <command>hg resolve</command> command was introduced 2.159 + in Mercurial 1.1, which was released in December 2008. If 2.160 + you are using an older version of Mercurial (run <command>hg 2.161 + version</command> to see), this command will not be 2.162 + present. If your version of Mercurial is older than 1.1, 2.163 + you should strongly consider upgrading to a newer version 2.164 + before trying to tackle complicated merges.</para> 2.165 + </note> 2.166 </sect2> 2.167 </sect1> 2.168 <sect1 id="sec:tour-merge:fetch"> 2.169 @@ -358,7 +388,7 @@ 2.170 Mercurial small and easy to deal with. Some extensions add new 2.171 commands that you can use from the command line, while others 2.172 work <quote>behind the scenes,</quote> for example adding 2.173 - capabilities to the server.</para> 2.174 + capabilities to Mercurial's built-in server mode.</para> 2.175 2.176 <para id="x_366">The <literal role="hg-ext">fetch</literal> 2.177 extension adds a new command called, not surprisingly, <command 2.178 @@ -368,10 +398,11 @@ 2.179 role="hg-cmd">hg commit</command>. It begins by pulling 2.180 changes from another repository into the current repository. If 2.181 it finds that the changes added a new head to the repository, it 2.182 - begins a merge, then (if the merge succeeded) commits the result 2.183 - of the merge with an automatically-generated commit message. If 2.184 - no new heads were added, it updates the working directory to the 2.185 - new tip changeset.</para> 2.186 + updates to the new head, begins a merge, then (if the merge 2.187 + succeeded) commits the result of the merge with an 2.188 + automatically-generated commit message. If no new heads were 2.189 + added, it updates the working directory to the new tip 2.190 + changeset.</para> 2.191 2.192 <para id="x_367">Enabling the <literal 2.193 role="hg-ext">fetch</literal> extension is easy. Edit the
3.1 --- a/en/examples/auto-snippets.xml Sun May 03 19:23:31 2009 -0700 3.2 +++ b/en/examples/auto-snippets.xml Sun May 03 20:27:09 2009 -0700 3.3 @@ -52,6 +52,11 @@ 3.4 <!ENTITY interaction.branching.stable SYSTEM "results/branching.stable.lxo"> 3.5 <!ENTITY interaction.branching.tag SYSTEM "results/branching.tag.lxo"> 3.6 <!ENTITY interaction.branching.update SYSTEM "results/branching.update.lxo"> 3.7 +<!ENTITY interaction.ch01-new.add SYSTEM "results/ch01-new.add.lxo"> 3.8 +<!ENTITY interaction.ch01-new.commit SYSTEM "results/ch01-new.commit.lxo"> 3.9 +<!ENTITY interaction.ch01-new.init SYSTEM "results/ch01-new.init.lxo"> 3.10 +<!ENTITY interaction.ch01-new.ls SYSTEM "results/ch01-new.ls.lxo"> 3.11 +<!ENTITY interaction.ch01-new.ls2 SYSTEM "results/ch01-new.ls2.lxo"> 3.12 <!ENTITY interaction.ch04-diff.chmod SYSTEM "results/ch04-diff.chmod.lxo"> 3.13 <!ENTITY interaction.ch04-diff.chmod.git SYSTEM "results/ch04-diff.chmod.git.lxo"> 3.14 <!ENTITY interaction.ch04-diff.rename.basic SYSTEM "results/ch04-diff.rename.basic.lxo"> 3.15 @@ -219,6 +224,8 @@ 3.16 <!ENTITY interaction.tour.lxogoing SYSTEM "results/tour.lxogoing.lxo"> 3.17 <!ENTITY interaction.tour.lxogoing.net SYSTEM "results/tour.lxogoing.net.lxo"> 3.18 <!ENTITY interaction.tour.merge.cat SYSTEM "results/tour.merge.cat.lxo"> 3.19 +<!ENTITY interaction.tour.merge.cat1 SYSTEM "results/tour.merge.cat1.lxo"> 3.20 +<!ENTITY interaction.tour.merge.cat2 SYSTEM "results/tour.merge.cat2.lxo"> 3.21 <!ENTITY interaction.tour.merge.clone SYSTEM "results/tour.merge.clone.lxo"> 3.22 <!ENTITY interaction.tour.merge.commit SYSTEM "results/tour.merge.commit.lxo"> 3.23 <!ENTITY interaction.tour.merge.dummy1 SYSTEM "results/tour.merge.dummy1.lxo">
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 4.2 +++ b/en/examples/ch01/new Sun May 03 20:27:09 2009 -0700 4.3 @@ -0,0 +1,39 @@ 4.4 +#!/bin/bash 4.5 + 4.6 +cat > hello.c <<EOF 4.7 +int main() 4.8 +{ 4.9 + printf("hello world!\n"); 4.10 +} 4.11 +EOF 4.12 + 4.13 +cat > goodbye.c <<EOF 4.14 +int main() 4.15 +{ 4.16 + printf("goodbye world!\n"); 4.17 +} 4.18 +EOF 4.19 + 4.20 +#$ name: init 4.21 + 4.22 +hg init myproject 4.23 + 4.24 +#$ name: ls 4.25 + 4.26 +ls -l 4.27 + 4.28 +#$ name: ls2 4.29 + 4.30 +ls -al myproject 4.31 + 4.32 +#$ name: add 4.33 + 4.34 +cd myproject 4.35 +cp ../hello.c . 4.36 +cp ../goodbye.c . 4.37 +hg add 4.38 +hg status 4.39 + 4.40 +#$ name: commit 4.41 + 4.42 +hg commit -m 'Initial commit'
5.1 --- a/en/examples/tour Sun May 03 19:23:31 2009 -0700 5.2 +++ b/en/examples/tour Sun May 03 20:27:09 2009 -0700 5.3 @@ -149,7 +149,7 @@ 5.4 5.5 #$ name: 5.6 cp hello.c ../new-hello.c 5.7 -sed -i '/printf/i\\tprintf("once more, hello.\\n");' ../new-hello.c 5.8 +sed -i '/printf("hello,/i\\tprintf("once more, hello.\\n");' ../new-hello.c 5.9 5.10 #$ name: merge.clone 5.11 5.12 @@ -164,9 +164,12 @@ 5.13 5.14 hg log -r 5 | grep changeset | cut -c 16-19 2>/dev/null > /tmp/REV5.my-new-hello 5.15 5.16 -#$ name: merge.cat 5.17 - 5.18 -cat hello.c 5.19 +#$ name: merge.cat1 5.20 + 5.21 +cat hello.c 5.22 + 5.23 +#$ name: merge.cat2 5.24 + 5.25 cat ../my-hello/hello.c 5.26 5.27 #$ name: merge.pull