Mercurial > hgbook

changeset 826:a17d6390a480

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More fixes to chapters 1 and 2.
author Bryan O'Sullivan <bos@serpentine.com>
date Sun, 03 May 2009 20:27:09 -0700
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
diffstat 5 files changed, 157 insertions(+), 41 deletions(-) [+]
line wrap: on
line diff
--- a/en/ch01-tour-basic.xml	Sun May 03 19:23:31 2009 -0700
+++ b/en/ch01-tour-basic.xml	Sun May 03 20:27:09 2009 -0700
@@ -867,9 +867,7 @@
 	    linkend="sec:tour:pull"/> when we ran it without <option
 	  role="hg-opt-pull">-u</option>, you can see that it printed
 	a helpful reminder that we'd have to take an explicit step to
-	update the working directory:</para>
-
-      <!-- &interaction.xxx.fixme; -->
+	update the working directory.</para>
 
       <para id="x_62">To find out what revision the working directory
 	is at, use the <command role="hg-cmd">hg parents</command>
@@ -990,6 +988,44 @@
       &interaction.tour.push.net;
     </sect2>
   </sect1>
+
+  <sect1>
+    <title>Starting a new project</title>
+
+    <para>It is just as easy to begin a new project as to work on one
+      that already exists.  The <command>hg init</command> command
+      creates a new, empty Mercurial repository.</para>
+
+    &interaction.ch01-new.init;
+
+    <para>This simply creates a repository named
+      <filename>myproject</filename> in the current directory.</para>
+
+    &interaction.ch01-new.ls;
+
+    <para>We can tell that <filename>myproject</filename> is a
+      Mercurial repository, because it contains a
+      <filename>.hg</filename> directory.</para>
+
+    &interaction.ch01-new.ls2;
+
+    <para>If we want to add some pre-existing files to the repository,
+      we copy them into place, and tell Mercurial to start tracking
+      them using the <command>hg add</command> command.</para>
+
+    &interaction.ch01-new.add;
+
+    <para>Once we are satisfied that our project looks right, we
+      commit our changes.</para>
+
+    &interaction.ch01-new.commit;
+
+    <para>It takes just a few moments to start using Mercurial on a
+      new project, which is part of its appeal. Revision control is
+      now so easy to work with, we can use it on the smallest of
+      projects that we might not have considered with a more
+      complicated tool.</para>
+  </sect1>
 </chapter>
 
 <!--
--- a/en/ch02-tour-merge.xml	Sun May 03 19:23:31 2009 -0700
+++ b/en/ch02-tour-merge.xml	Sun May 03 20:27:09 2009 -0700
@@ -13,24 +13,29 @@
     <title>Merging streams of work</title>
 
     <para id="x_339">Merging is a fundamental part of working with a distributed
-      revision control tool.</para>
+      revision control tool.  Here are a few cases in which the need
+      to merge work arises.</para>
     <itemizedlist>
-      <listitem><para id="x_33a">Alice and Bob each have a personal copy of a
+      <listitem>
+	<para id="x_33a">Alice and Bob each have a personal copy of a
 	  repository for a project they're collaborating on.  Alice
 	  fixes a bug in her repository; Bob adds a new feature in
 	  his.  They want the shared repository to contain both the
 	  bug fix and the new feature.</para>
       </listitem>
-      <listitem><para id="x_33b">I frequently work on several different tasks for
-	  a single project at once, each safely isolated in its own
-	  repository. Working this way means that I often need to
-	  merge one piece of my own work with another.</para>
-      </listitem></itemizedlist>
+      <listitem>
+	<para id="x_33b">Cynthia frequently works on several different
+	  tasks for a single project at once, each safely isolated in
+	  its own repository. Working this way means that she often
+	  needs to merge one piece of her own work with
+	  another.</para>
+      </listitem>
+    </itemizedlist>
 
-    <para id="x_33c">Because merging is such a common thing to need to do,
-      Mercurial makes it easy.  Let's walk through the process.  We'll
-      begin by cloning yet another repository (see how often they
-      spring up?) and making a change in it.</para>
+    <para id="x_33c">Because we need to merge often, Mercurial makes
+      the process easy.  Let's walk through a merge.  We'll begin by
+      cloning yet another repository (see how often they spring up?)
+      and making a change in it.</para>
 
     &interaction.tour.merge.clone;
 
@@ -38,9 +43,15 @@
       <filename>hello.c</filename> with different contents.  The
       histories of the two repositories have also diverged, as
       illustrated in <xref
-	linkend="fig:tour-merge:sep-repos"/>.</para>
+	linkend="fig:tour-merge:sep-repos"/>.  Here is a copy of our
+      file from one repository.</para>
+
+    &interaction.tour.merge.cat1;
 
-    &interaction.tour.merge.cat;
+    <para>And here is our slightly different version from the other
+      repository.</para>
+
+    &interaction.tour.merge.cat2;
 
     <figure id="fig:tour-merge:sep-repos">
       <title>Divergent recent histories of the <filename
@@ -65,10 +76,12 @@
     <sect2>
       <title>Head changesets</title>
 
-      <para id="x_341">A head is a change that has no descendants, or children,
-	as they're also known.  The tip revision is thus a head,
-	because the newest revision in a repository doesn't have any
-	children, but a repository can contain more than one
+      <para id="x_341">Remember that Mercurial records what the parent
+	of each change is.  If a change has a parent, we call it a
+	child or descendant of the parent.  A head is a change that
+	has no children.  The tip revision is thus a head, because the
+	newest revision in a repository doesn't have any children.
+	There are times when a repository can contain more than one
 	head.</para>
 
       <figure id="fig:tour-merge:pull">
@@ -99,8 +112,8 @@
 	  role="hg-cmd">hg heads</command> command.</para>
 
       &interaction.tour.merge.heads;
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Performing the merge</title>
 
@@ -110,23 +123,28 @@
 
       &interaction.tour.merge.update;
 
-      <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg
-	  update</command> command won't do a merge; it won't update
-	the working directory when it thinks we might want to do
-	a merge, unless we force it to do so.  Instead, we use the
-	<command role="hg-cmd">hg merge</command> command to merge the
-	two heads.</para>
+      <para id="x_345">Mercurial is telling us that the <command
+	  role="hg-cmd">hg update</command> command won't do a merge;
+	it won't update the working directory when it thinks we might
+	want to do a merge, unless we force it to do so.
+	(Incidentally, forcing the update with <command>hg update
+	  -C</command> would revert any uncommitted changes in the
+	working directory.)</para>
+
+      <para>To start a merge between the two heads, we use the
+	<command role="hg-cmd">hg merge</command> command.</para>
 
       &interaction.tour.merge.merge;
 
-      <para id="x_347">This updates the working directory so that it contains
-	changes from <emphasis>both</emphasis> heads, which is
-	reflected in both the output of <command role="hg-cmd">hg
+      <para id="x_347">We resolve the contents of <filename>hello.c</filename>
+
+This updates the working directory so that it
+	contains changes from <emphasis>both</emphasis> heads, which
+	is reflected in both the output of <command role="hg-cmd">hg
 	  parents</command> and the contents of
 	<filename>hello.c</filename>.</para>
 
       &interaction.tour.merge.parents;
-
     </sect2>
     <sect2>
       <title>Committing the results of the merge</title>
@@ -208,8 +226,8 @@
       human guidance) or aren't present, it tries a few
       different graphical merging tools.</para>
 
-    <para id="x_34f">It's also possible to get Mercurial to run another program
-      or script instead of <command>hgmerge</command>, by setting the
+    <para id="x_34f">It's also possible to get Mercurial to run a
+      specific program or script, by setting the
       <envar>HGMERGE</envar> environment variable to the name of your
       preferred program.</para>
 
@@ -310,7 +328,8 @@
 	non-interactive <command>merge</command> command.  This is
 	bundled with many Unix-like systems. (If you're following this
 	example on your computer, don't bother setting
-	<envar>HGMERGE</envar>.)</para>
+	<envar>HGMERGE</envar>.  You'll get dropped into a GUI file
+	merge tool instead, which is much preferable.)</para>
 
       &interaction.tour-merge-conflict.merge;
 
@@ -333,6 +352,17 @@
 
       &interaction.tour-merge-conflict.commit;
 
+      <note>
+	<title>Where is the <command>hg resolve</command> command?</title>
+
+	<para>The <command>hg resolve</command> command was introduced
+	  in Mercurial 1.1, which was released in December 2008. If
+	  you are using an older version of Mercurial (run <command>hg
+	    version</command> to see), this command will not be
+	  present.  If your version of Mercurial is older than 1.1,
+	  you should strongly consider upgrading to a newer version
+	  before trying to tackle complicated merges.</para>
+      </note>
     </sect2>
   </sect1>
   <sect1 id="sec:tour-merge:fetch">
@@ -358,7 +388,7 @@
       Mercurial small and easy to deal with.  Some extensions add new
       commands that you can use from the command line, while others
       work <quote>behind the scenes,</quote> for example adding
-      capabilities to the server.</para>
+      capabilities to Mercurial's built-in server mode.</para>
 
     <para id="x_366">The <literal role="hg-ext">fetch</literal>
       extension adds a new command called, not surprisingly, <command
@@ -368,10 +398,11 @@
 	role="hg-cmd">hg commit</command>.  It begins by pulling
       changes from another repository into the current repository.  If
       it finds that the changes added a new head to the repository, it
-      begins a merge, then (if the merge succeeded) commits the result
-      of the merge with an automatically-generated commit message.  If
-      no new heads were added, it updates the working directory to the
-      new tip changeset.</para>
+      updates to the new head, begins a merge, then (if the merge
+      succeeded) commits the result of the merge with an
+      automatically-generated commit message.  If no new heads were
+      added, it updates the working directory to the new tip
+      changeset.</para>
 
     <para id="x_367">Enabling the <literal
 	role="hg-ext">fetch</literal> extension is easy.  Edit the
--- a/en/examples/auto-snippets.xml	Sun May 03 19:23:31 2009 -0700
+++ b/en/examples/auto-snippets.xml	Sun May 03 20:27:09 2009 -0700
@@ -52,6 +52,11 @@
 <!ENTITY interaction.branching.stable SYSTEM "results/branching.stable.lxo">
 <!ENTITY interaction.branching.tag SYSTEM "results/branching.tag.lxo">
 <!ENTITY interaction.branching.update SYSTEM "results/branching.update.lxo">
+<!ENTITY interaction.ch01-new.add SYSTEM "results/ch01-new.add.lxo">
+<!ENTITY interaction.ch01-new.commit SYSTEM "results/ch01-new.commit.lxo">
+<!ENTITY interaction.ch01-new.init SYSTEM "results/ch01-new.init.lxo">
+<!ENTITY interaction.ch01-new.ls SYSTEM "results/ch01-new.ls.lxo">
+<!ENTITY interaction.ch01-new.ls2 SYSTEM "results/ch01-new.ls2.lxo">
 <!ENTITY interaction.ch04-diff.chmod SYSTEM "results/ch04-diff.chmod.lxo">
 <!ENTITY interaction.ch04-diff.chmod.git SYSTEM "results/ch04-diff.chmod.git.lxo">
 <!ENTITY interaction.ch04-diff.rename.basic SYSTEM "results/ch04-diff.rename.basic.lxo">
@@ -219,6 +224,8 @@
 <!ENTITY interaction.tour.lxogoing SYSTEM "results/tour.lxogoing.lxo">
 <!ENTITY interaction.tour.lxogoing.net SYSTEM "results/tour.lxogoing.net.lxo">
 <!ENTITY interaction.tour.merge.cat SYSTEM "results/tour.merge.cat.lxo">
+<!ENTITY interaction.tour.merge.cat1 SYSTEM "results/tour.merge.cat1.lxo">
+<!ENTITY interaction.tour.merge.cat2 SYSTEM "results/tour.merge.cat2.lxo">
 <!ENTITY interaction.tour.merge.clone SYSTEM "results/tour.merge.clone.lxo">
 <!ENTITY interaction.tour.merge.commit SYSTEM "results/tour.merge.commit.lxo">
 <!ENTITY interaction.tour.merge.dummy1 SYSTEM "results/tour.merge.dummy1.lxo">
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/ch01/new	Sun May 03 20:27:09 2009 -0700
@@ -0,0 +1,39 @@
+#!/bin/bash
+
+cat > hello.c <<EOF
+int main()
+{
+    printf("hello world!\n");
+}
+EOF
+
+cat > goodbye.c <<EOF
+int main()
+{
+    printf("goodbye world!\n");
+}
+EOF
+
+#$ name: init
+
+hg init myproject
+
+#$ name: ls
+
+ls -l
+
+#$ name: ls2
+
+ls -al myproject
+
+#$ name: add
+
+cd myproject
+cp ../hello.c .
+cp ../goodbye.c .
+hg add
+hg status
+
+#$ name: commit
+
+hg commit -m 'Initial commit'
--- a/en/examples/tour	Sun May 03 19:23:31 2009 -0700
+++ b/en/examples/tour	Sun May 03 20:27:09 2009 -0700
@@ -149,7 +149,7 @@
 
 #$ name:
 cp hello.c ../new-hello.c
-sed -i '/printf/i\\tprintf("once more, hello.\\n");' ../new-hello.c
+sed -i '/printf("hello,/i\\tprintf("once more, hello.\\n");' ../new-hello.c
 
 #$ name: merge.clone
 
@@ -164,9 +164,12 @@
 
 hg log -r 5 | grep changeset | cut -c 16-19 2>/dev/null > /tmp/REV5.my-new-hello
 
-#$ name: merge.cat
+#$ name: merge.cat1
 
 cat hello.c
+
+#$ name: merge.cat2
+
 cat ../my-hello/hello.c
 
 #$ name: merge.pull