Mercurial > hgbook

changeset 824:c8d662d3cb40

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Improve chapter 1 further, based on comments.
author Bryan O'Sullivan <bos@serpentine.com>
date Sun, 03 May 2009 19:23:08 -0700
parents 9e33729cafae
children d7d09cda83d2
files en/ch01-tour-basic.xml en/examples/auto-snippets.xml en/examples/tour
diffstat 3 files changed, 219 insertions(+), 148 deletions(-) [+]
line wrap: on
line diff
--- a/en/ch01-tour-basic.xml	Tue Apr 28 23:33:11 2009 -0700
+++ b/en/ch01-tour-basic.xml	Sun May 03 19:23:08 2009 -0700
@@ -51,8 +51,10 @@
       <itemizedlist>
 	<listitem><para id="x_4">Ubuntu and Debian:</para>
 	  <programlisting>apt-get install mercurial</programlisting></listitem>
-	<listitem><para id="x_5">Fedora and OpenSUSE:</para>
+	<listitem><para id="x_5">Fedora:</para>
 	  <programlisting>yum install mercurial</programlisting></listitem>
+	<listitem><para>OpenSUSE:</para>
+	  <programlisting>zypper install mercurial</programlisting></listitem>
 	<listitem><para id="x_6">Gentoo:</para>
 	  <programlisting>emerge mercurial</programlisting></listitem>
       </itemizedlist>
@@ -74,9 +76,9 @@
 
     <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
 	version</command> command to find out whether Mercurial is
-      actually installed properly.  The actual version information
-      that it prints isn't so important; it's whether it prints
-      anything at all that we care about.</para>
+      installed properly.  The actual version information that it
+      prints isn't so important; we simply care whether the command
+      runs and prints anything at all.</para>
 
     &interaction.tour.version;
 
@@ -213,12 +215,11 @@
 	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
 	  string.  These are <emphasis>identifiers</emphasis> for the
 	  changeset.  The hex string is a unique identifier: the same
-	  hex string will always refer to the same changeset. The
+	  hex string will always refer to the same changeset in every
+	  copy of this repository. The
 	  number is shorter and easier to type than the hex string,
 	  but it isn't unique: the same number in two different clones
-	  of a repository may identify different changesets.  Why
-	  provide the number at all, then?  For local
-	  convenience.</para>
+	  of a repository may identify different changesets.</para>
       </listitem>
       <listitem><para id="x_1f"><literal>user</literal>: The identity of the
 	  person who created the changeset.  This is a free-form
@@ -417,9 +418,9 @@
       </listitem>
     </itemizedlist>
 
-    <para id="x_36">In the examples throughout this book, I use short options
-      instead of long.  This just reflects my own preference, so don't
-      read anything significant into it.</para>
+    <para id="x_36">In the examples throughout this book, I usually
+      use short options instead of long.  This simply reflects my own
+      preference, so don't read anything significant into it.</para>
 
     <para id="x_37">Most commands that print output of some kind will print more
       output when passed a <option role="hg-opt-global">-v</option>
@@ -590,19 +591,30 @@
 	<title>Creating a Mercurial configuration file</title>
 
 	<para id="x_4a">To set a user name, use your favorite editor
-	    to create a file called <filename
-	      role="special">.hgrc</filename> in your home directory.
-	    Mercurial will use this file to look up your personalised
-	    configuration settings.  The initial contents of your
-	    <filename role="special">.hgrc</filename> should look like
-	    this.</para>
+	  to create a file called <filename
+	    role="special">.hgrc</filename> in your home directory.
+	  Mercurial will use this file to look up your personalised
+	  configuration settings.  The initial contents of your
+	  <filename role="special">.hgrc</filename> should look like
+	  this.</para>
+
+	<tip>
+	  <title><quote>Home directory</quote> on Windows</title>
 
-	<remark>Figure out what the appropriate directory is on
-	  Windows.</remark>
+	  <para>When we refer to your home directory, on an English
+	    language installation of Windows this will usually be a
+	    folder named after your user name in
+	    <filename>C:\Documents and Settings</filename>.  You can
+	    find out the exact name of your home directory by opening
+	    a command prompt window and running the following
+	    command.</para>
+
+	  <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen>
+	</tip>
 
 	<programlisting># This is a Mercurial configuration file.
 [ui]
-username = Firstname Lastname &lt;email.address@domain.net&gt;</programlisting>
+username = Firstname Lastname &lt;email.address@example.net&gt;</programlisting>
 
 	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
 	  <emphasis>section</emphasis> of the config file, so you can
@@ -620,38 +632,37 @@
 	<title>Choosing a user name</title>
 
 	<para id="x_4c">You can use any text you like as the value of
-	    the <literal>username</literal> config item, since this
-	    information is for reading by other people, but will not be
-	    interpreted by Mercurial.  The convention that most
-	    people follow is to use their name and email address, as
-	    in the example above.</para>
+	  the <literal>username</literal> config item, since this
+	  information is for reading by other people, but will not be
+	  interpreted by Mercurial.  The convention that most people
+	  follow is to use their name and email address, as in the
+	  example above.</para>
 	<note>
 	  <para id="x_4d">Mercurial's built-in web server obfuscates
-	      email addresses, to make it more difficult for the email
-	      harvesting tools that spammers use. This reduces the
-	      likelihood that you'll start receiving more junk email
-	      if you publish a Mercurial repository on the
-	      web.</para></note>
-
+	    email addresses, to make it more difficult for the email
+	    harvesting tools that spammers use. This reduces the
+	    likelihood that you'll start receiving more junk email if
+	    you publish a Mercurial repository on the
+	    web.</para></note>
       </sect3>
     </sect2>
     <sect2>
       <title>Writing a commit message</title>
 
       <para id="x_4e">When we commit a change, Mercurial drops us into
-	  a text editor, to enter a message that will describe the
-	  modifications we've made in this changeset.  This is called
-	  the <emphasis>commit message</emphasis>.  It will be a
-	  record for readers of what we did and why, and it will be
-	  printed by <command role="hg-cmd">hg log</command> after
-	  we've finished committing.</para>
+	a text editor, to enter a message that will describe the
+	modifications we've made in this changeset.  This is called
+	the <emphasis>commit message</emphasis>.  It will be a record
+	for readers of what we did and why, and it will be printed by
+	<command role="hg-cmd">hg log</command> after we've finished
+	committing.</para>
 
        &interaction.tour.commit;
 
       <para id="x_4f">The editor that the <command role="hg-cmd">hg
-	    commit</command> command drops us into will contain an
-	  empty line or two, followed by a number of lines starting with
-	  <quote><literal>HG:</literal></quote>.</para>
+	  commit</command> command drops us into will contain an empty
+	line or two, followed by a number of lines starting with
+	<quote><literal>HG:</literal></quote>.</para>
 
     <programlisting>
 This is where I type my commit comment.
@@ -663,20 +674,19 @@
 HG: changed hello.c</programlisting>
 
       <para id="x_50">Mercurial ignores the lines that start with
-	  <quote><literal>HG:</literal></quote>; it uses them only to
-	  tell us which files it's recording changes to.  Modifying or
-	  deleting these lines has no effect.</para>
+	<quote><literal>HG:</literal></quote>; it uses them only to
+	tell us which files it's recording changes to.  Modifying or
+	deleting these lines has no effect.</para>
     </sect2>
     <sect2>
       <title>Writing a good commit message</title>
 
       <para id="x_51">Since <command role="hg-cmd">hg log</command>
-	  only prints the first line of a commit message by default,
-	  it's best to write a commit message whose first line stands
-	  alone.  Here's a real example of a commit message that
-	  <emphasis>doesn't</emphasis> follow this guideline, and
-	  hence has a summary that is not
-	  readable.</para>
+	only prints the first line of a commit message by default,
+	it's best to write a commit message whose first line stands
+	alone.  Here's a real example of a commit message that
+	<emphasis>doesn't</emphasis> follow this guideline, and hence
+	has a summary that is not readable.</para>
 
       <programlisting>
 changeset:   73:584af0e231be
@@ -685,40 +695,51 @@
 summary:     include buildmeister/commondefs. Add exports.</programlisting>
 
       <para id="x_52">As far as the remainder of the contents of the
-	  commit message are concerned, there are no hard-and-fast
-	  rules.  Mercurial itself doesn't interpret or care about the
-	  contents of the commit message, though your project may have
-	  policies that dictate a certain kind of
-	  formatting.</para>
+	commit message are concerned, there are no hard-and-fast
+	rules.  Mercurial itself doesn't interpret or care about the
+	contents of the commit message, though your project may have
+	policies that dictate a certain kind of formatting.</para>
       <para id="x_53">My personal preference is for short, but
-	  informative, commit messages that tell me something that I
-	  can't figure out with a quick glance at the output of
-	  <command role="hg-cmd">hg log
-	    --patch</command>.</para>
+	informative, commit messages that tell me something that I
+	can't figure out with a quick glance at the output of <command
+	  role="hg-cmd">hg log --patch</command>.</para>
+      <para id="x_55">If we run the <command role="hg-cmd">hg
+	  commit</command> command without any arguments, it records
+	all of the changes we've made, as reported by <command
+	  role="hg-cmd">hg status</command> and <command
+	  role="hg-cmd">hg diff</command>.</para>
+
+      <note>
+	<title>A surprise for Subversion users</title>
+
+	<para>Like other Mercurial commands, if we don't supply
+	  explicit names to commit to the <command role="hg-cmd">hg
+	    commit</command>, it will operate across a repository's
+	  entire working directory.  Be wary of this if you're coming
+	  from the Subversion or CVS world, since you might expect it
+	  to operate only on the current directory that you happen to
+	  be visiting and its subdirectories.</para>
+      </note>
     </sect2>
+
     <sect2>
       <title>Aborting a commit</title>
 
       <para id="x_54">If you decide that you don't want to commit
-	  while in the middle of editing a commit message, simply exit
-	  from your editor without saving the file that it's editing.
-	  This will cause nothing to happen to either the repository
-	  or the working directory.</para>
-      <para id="x_55">If we run the <command role="hg-cmd">hg
-	    commit</command> command without any arguments, it records
-	  all of the changes we've made, as reported by <command
-	    role="hg-cmd">hg status</command> and <command
-	    role="hg-cmd">hg diff</command>.</para>
+	while in the middle of editing a commit message, simply exit
+	from your editor without saving the file that it's editing.
+	This will cause nothing to happen to either the repository or
+	the working directory.</para>
     </sect2>
+
     <sect2>
       <title>Admiring our new handiwork</title>
 
       <para id="x_56">Once we've finished the commit, we can use the
-	  <command role="hg-cmd">hg tip</command> command to display
-	  the changeset we just created.  This command produces output
-	  that is identical to <command role="hg-cmd">hg
-	    log</command>, but it only displays the newest revision in
-	  the repository.</para>
+	<command role="hg-cmd">hg tip</command> command to display the
+	changeset we just created.  This command produces output that
+	is identical to <command role="hg-cmd">hg log</command>, but
+	it only displays the newest revision in the repository.</para>
 
       &interaction.tour.tip;
 
@@ -741,57 +762,74 @@
     <title>Sharing changes</title>
 
     <para id="x_58">We mentioned earlier that repositories in
-	Mercurial are self-contained.  This means that the changeset
-	we just created exists only in our <filename
-	  class="directory">my-hello</filename> repository.  Let's
-	look at a few ways that we can propagate this change into
-	other repositories.</para>
+      Mercurial are self-contained.  This means that the changeset we
+      just created exists only in our <filename
+	class="directory">my-hello</filename> repository.  Let's look
+      at a few ways that we can propagate this change into other
+      repositories.</para>
 
     <sect2 id="sec:tour:pull">
       <title>Pulling changes from another repository</title>
+
       <para id="x_59">To get started, let's clone our original
-	  <filename class="directory">hello</filename> repository,
-	  which does not contain the change we just committed.  We'll
-	  call our temporary repository <filename
-	    class="directory">hello-pull</filename>.</para>
+	<filename class="directory">hello</filename> repository, which
+	does not contain the change we just committed.  We'll call our
+	temporary repository <filename
+	  class="directory">hello-pull</filename>.</para>
 
       &interaction.tour.clone-pull;
 
       <para id="x_5a">We'll use the <command role="hg-cmd">hg
-	    pull</command> command to bring changes from <filename
-	    class="directory">my-hello</filename> into <filename
-	    class="directory">hello-pull</filename>.  However, blindly
-	  pulling unknown changes into a repository is a somewhat
-	  scary prospect.  Mercurial provides the <command
-	    role="hg-cmd">hg incoming</command> command to tell us
-	  what changes the <command role="hg-cmd">hg pull</command>
-	  command <emphasis>would</emphasis> pull into the repository,
-	  without actually pulling the changes in.</para>
+	  pull</command> command to bring changes from <filename
+	  class="directory">my-hello</filename> into <filename
+	  class="directory">hello-pull</filename>.  However, blindly
+	pulling unknown changes into a repository is a somewhat scary
+	prospect.  Mercurial provides the <command role="hg-cmd">hg
+	  incoming</command> command to tell us what changes the
+	<command role="hg-cmd">hg pull</command> command
+	<emphasis>would</emphasis> pull into the repository, without
+	actually pulling the changes in.</para>
 
       &interaction.tour.incoming;
 
-      <para id="x_5b">Suppose you're pulling changes from a repository
-      on the network somewhere. While you are looking at the <command
-	  role="hg-cmd">hg incoming</command> output, and before you
-	pull those changes, someone might have committed something in
-	the remote repository. This means that it's possible to pull
-	more changes than you saw when using <command
-	  role="hg-cmd">hg incoming</command>.</para>
-
       <para id="x_5c">Bringing changes into a repository is a simple
-	  matter of running the <command role="hg-cmd">hg
-	    pull</command> command, and telling it which repository to
-	  pull from.</para>
+	matter of running the <command role="hg-cmd">hg pull</command>
+	command, and optionally telling it which repository to pull from.</para>
 
       &interaction.tour.pull;
 
-      <para id="x_5d">As you can see
-	  from the before-and-after output of <command
-	    role="hg-cmd">hg tip</command>, we have successfully
-	  pulled changes into our repository.  There remains one step
-	  before we can see these changes in the working
-	  directory.</para>
+      <para id="x_5d">As you can see from the before-and-after output
+	of <command role="hg-cmd">hg tip</command>, we have
+	successfully pulled changes into our repository.  However,
+	Mercurial separates pulling changes in from updating the
+	working directory. There remains one step before we will see
+	the changes that we just pulled appear in the working
+	directory.</para>
+
+      <tip>
+	<title>Pulling specific changes</title>
+
+	<para id="x_5b">It is possible that due to the delay between
+	  running <command role="hg-cmd">hg incoming</command> and
+	  <command role="hg-cmd">hg pull</command>, you may not see
+	  all changesets that will be brought from the other
+	  repository. Suppose you're pulling changes from a repository
+	  on the network somewhere. While you are looking at the
+	  <command role="hg-cmd">hg incoming</command> output, and
+	  before you pull those changes, someone might have committed
+	  something in the remote repository. This means that it's
+	  possible to pull more changes than you saw when using
+	  <command role="hg-cmd">hg incoming</command>.</para>
+
+	<para>If you only want to pull precisely the changes that were
+	  listed by <command role="hg-cmd">hg incoming</command>, or
+	  you have some other reason to pull a subset of changes,
+	  simply identify the change that you want to pull by its
+	  changeset ID, e.g. <command>hg pull
+	    -r7e95bb</command>.</para>
+      </tip>
     </sect2>
+
     <sect2>
       <title>Updating the working directory</title>
 
@@ -807,20 +845,21 @@
 
       &interaction.tour.update;
 
-      <para id="x_5f">It might seem a bit strange that <command role="hg-cmd">hg
-	  pull</command> doesn't update the working directory
-	automatically.  There's actually a good reason for this: you
-	can use <command role="hg-cmd">hg update</command> to update
-	the working directory to the state it was in at <emphasis>any
-	  revision</emphasis> in the history of the repository.  If
-	you had the working directory updated to an old revision&emdash;to
-	hunt down the origin of a bug, say&emdash;and ran a <command
-	  role="hg-cmd">hg pull</command> which automatically updated
-	the working directory to a new revision, you might not be
-	terribly happy.</para>
-      <para id="x_60">However, since pull-then-update is such a common thing to
-	do, Mercurial lets you combine the two by passing the <option
-	  role="hg-opt-pull">-u</option> option to <command
+      <para id="x_5f">It might seem a bit strange that <command
+	  role="hg-cmd">hg pull</command> doesn't update the working
+	directory automatically.  There's actually a good reason for
+	this: you can use <command role="hg-cmd">hg update</command>
+	to update the working directory to the state it was in at
+	<emphasis>any revision</emphasis> in the history of the
+	repository.  If you had the working directory updated to an
+	old revision&emdash;to hunt down the origin of a bug,
+	say&emdash;and ran a <command role="hg-cmd">hg pull</command>
+	which automatically updated the working directory to a new
+	revision, you might not be terribly happy.</para>
+
+      <para id="x_60">Since pull-then-update is such a common sequence
+	of operations, Mercurial lets you combine the two by passing
+	the <option role="hg-opt-pull">-u</option> option to <command
 	  role="hg-cmd">hg pull</command>.</para>
 
       <para id="x_61">If you look back at the output of <command
@@ -832,25 +871,24 @@
 
       <!-- &interaction.xxx.fixme; -->
 
-      <para id="x_62">To find out what revision the working directory is at, use
-	the <command role="hg-cmd">hg parents</command>
+      <para id="x_62">To find out what revision the working directory
+	is at, use the <command role="hg-cmd">hg parents</command>
 	command.</para>
 
       &interaction.tour.parents;
 
       <para id="x_63">If you look back at <xref
-	  linkend="fig:tour-basic:history"/>,
-	you'll see arrows connecting each changeset.  The node that
-	the arrow leads <emphasis>from</emphasis> in each case is a
-	parent, and the node that the arrow leads
-	<emphasis>to</emphasis> is its child.  The working directory
-	has a parent in just the same way; this is the changeset that
-	the working directory currently contains.</para>
+	  linkend="fig:tour-basic:history"/>, you'll see arrows
+	connecting each changeset.  The node that the arrow leads
+	<emphasis>from</emphasis> in each case is a parent, and the
+	node that the arrow leads <emphasis>to</emphasis> is its
+	child.  The working directory has a parent in just the same
+	way; this is the changeset that the working directory
+	currently contains.</para>
 
-      <para id="x_64">To update the working directory to a particular revision,
-
-	give a revision number or changeset ID to the <command
-	  role="hg-cmd">hg update</command> command.</para>
+      <para id="x_64">To update the working directory to a particular
+	revision, give a revision number or changeset ID to the
+	<command role="hg-cmd">hg update</command> command.</para>
 
       &interaction.tour.older;
 
@@ -865,22 +903,21 @@
       <title>Pushing changes to another repository</title>
 
       <para id="x_66">Mercurial lets us push changes to another
-	  repository, from the repository we're currently visiting.
-	  As with the example of <command role="hg-cmd">hg
-	    pull</command> above, we'll create a temporary repository
-	  to push our changes into.</para>
+	repository, from the repository we're currently visiting. As
+	with the example of <command role="hg-cmd">hg pull</command>
+	above, we'll create a temporary repository to push our changes
+	into.</para>
 
       &interaction.tour.clone-push;
 
-      <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command
-	  tells us what changes would be pushed into another
-	  repository.</para>
+      <para id="x_67">The <command role="hg-cmd">hg outgoing</command>
+	command tells us what changes would be pushed into another
+	repository.</para>
 
       &interaction.tour.outgoing;
 
-      <para id="x_68">And the
-	  <command role="hg-cmd">hg push</command> command does the
-	  actual push.</para>
+      <para id="x_68">And the <command role="hg-cmd">hg push</command>
+	command does the actual push.</para>
 
       &interaction.tour.push;
 
@@ -902,6 +939,38 @@
 
       &interaction.tour.push.nothing;
     </sect2>
+
+    <sect2>
+      <title>Default locations</title>
+
+      <para>When we clone a repository, Mercurial records the location
+	of the repository we cloned in the
+	<filename>.hg/hgrc</filename> file of the new repository.  If
+	we don't supply a location to <command>hg pull</command> from
+	or <command>hg push</command> to, those commands will use this
+	location as a default.  The <command>hg incoming</command>
+	and <command>hg outgoing</command> commands do so too.</para>
+
+      <para>If you open a repository's <filename>.hg/hgrc</filename>
+	file in a text editor, you will see contents like the
+	following.</para>
+
+      <programlisting>[paths]
+default = http://www.selenic.com/repo/hg</programlisting>
+
+      <para>It is possible&emdash;and often useful&emdash;to have the
+	default location for <command>hg push</command> and
+	<command>hg outgoing</command> be different from those for
+	<command>hg pull</command> and <command>hg incoming</command>.
+	We can do this by adding a <literal>default-push</literal>
+	entry to the <literal>[paths]</literal> section of the
+	<filename>.hg/hgrc</filename> file, as follows.</para>
+
+      <programlisting>[paths]
+default = http://www.selenic.com/repo/hg
+default-push = http://hg.example.com/hg</programlisting>
+    </sect2>
+
     <sect2>
       <title>Sharing changes over a network</title>
 
@@ -913,10 +982,10 @@
 	
       &interaction.tour.outgoing.net;
 
-      <para id="x_6c">In this example, we
-	  can see what changes we could push to the remote repository,
-	  but the repository is understandably not set up to let
-	  anonymous users push to it.</para>
+      <para id="x_6c">In this example, we can see what changes we
+	could push to the remote repository, but the repository is
+	understandably not set up to let anonymous users push to
+	it.</para>
 
       &interaction.tour.push.net;
     </sect2>
--- a/en/examples/auto-snippets.xml	Tue Apr 28 23:33:11 2009 -0700
+++ b/en/examples/auto-snippets.xml	Sun May 03 19:23:08 2009 -0700
@@ -69,6 +69,7 @@
 <!ENTITY interaction.ch09-hook.ws.better SYSTEM "results/ch09-hook.ws.better.lxo">
 <!ENTITY interaction.ch09-hook.ws.simple SYSTEM "results/ch09-hook.ws.simple.lxo">
 <!ENTITY interaction.ch10-multiline.go SYSTEM "results/ch10-multiline.go.lxo">
+<!ENTITY interaction.ch10-multiline.orig.go SYSTEM "results/ch10-multiline.orig.go.lxo">
 <!ENTITY interaction.ch11-qdelete.convert SYSTEM "results/ch11-qdelete.convert.lxo">
 <!ENTITY interaction.ch11-qdelete.go SYSTEM "results/ch11-qdelete.go.lxo">
 <!ENTITY interaction.ch11-qdelete.import SYSTEM "results/ch11-qdelete.import.lxo">
--- a/en/examples/tour	Tue Apr 28 23:33:11 2009 -0700
+++ b/en/examples/tour	Sun May 03 19:23:08 2009 -0700
@@ -119,6 +119,7 @@
 hg update 2
 hg parents
 hg update
+hg parents
 
 #$ name: clone-push