Mercurial > hgbook

changeset 805:743dc55775fe

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged upstream
author Raphael Borun Das Gupta <hg@raphael.dasgupta.ch>
date Sat, 18 Apr 2009 17:45:54 +0200
parents 83540574ee49 (current diff) 29f0f79cf614 (diff)
children 06458701453c
files en/ch05-collab.xml
diffstat 7 files changed, 390 insertions(+), 211 deletions(-) [+]
line wrap: on
line diff
--- a/en/ch01-tour-basic.xml	Sat Apr 18 17:38:07 2009 +0200
+++ b/en/ch01-tour-basic.xml	Sat Apr 18 17:45:54 2009 +0200
@@ -131,7 +131,7 @@
 
       &interaction.tour.clone;
 
-      <para>One advantage of using <command role="hg-cmd">hg
+      <para id="x_67c">One advantage of using <command role="hg-cmd">hg
 	  clone</command> is that, as we can see above, it lets us clone
 	repositories over the network.  Another is that it remembers
 	where we cloned from, which we'll find useful soon when we
@@ -233,7 +233,7 @@
 	  the text message that the creator of the changeset entered
 	  to describe the changeset.</para></listitem>
       <listitem>
-	<para>Some changesets, such as the first in the list above,
+	<para id="x_67d">Some changesets, such as the first in the list above,
 	  have a <literal>tag</literal> field.  A tag is another way
 	  to identify a changeset, by giving it an easy-to-remember
 	  name. (The tag named <literal>tip</literal> is special: it
@@ -364,7 +364,7 @@
 
       &interaction.tour.log-vp;
 
-      <para>The <option role="hg-opt-log">-p</option> option is
+      <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
 	tremendously useful, so it's well worth remembering.</para>
 
     </sect2>
@@ -410,7 +410,7 @@
 	    role="hg-opt-log">--rev</option> arguments.</para>
       </listitem>
       <listitem>
-	<para>If you are using short options, you can save typing by
+	<para id="x_67f">If you are using short options, you can save typing by
 	  running them together. For example, the command <command
 	    role="hg-cmd">hg log -v -p -r 2</command> can be written
 	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
@@ -430,7 +430,7 @@
     <note>
       <title>Option naming consistency</title>
 
-      <para>Almost always, Mercurial commands use consistent option
+      <para id="x_680">Almost always, Mercurial commands use consistent option
 	names to refer to the same concepts.  For instance, if a
 	command deals with changesets, you'll always identify them
 	with <option role="hg-opt-log">--rev</option> or <option
@@ -454,7 +454,7 @@
       locally, we can just clone that instead.  This is much faster
       than cloning over the network, and cloning a local repository
       uses less disk space in most cases, too<footnote>
-	<para>The saving of space arises when source and destination
+	<para id="x_681">The saving of space arises when source and destination
 	  repositories are on the same filesystem, in which case
 	  Mercurial will use hardlinks to do copy-on-write sharing of
 	  its internal metadata.  If that explanation meant nothing to
@@ -479,7 +479,7 @@
 
     &interaction.tour.cat1;
 
-    <para>Let's edit this file so that it prints a second line of
+    <para id="x_682">Let's edit this file so that it prints a second line of
       output.</para>
 
     &interaction.tour.cat2;
@@ -516,7 +516,7 @@
     <tip>
       <title>Understanding patches</title>
 
-      <para>Remember to take a look at <xref
+      <para id="x_683">Remember to take a look at <xref
 	  linkend="sec:mq:patch"/> if you don't know how to read
 	output above.</para>
     </tip>
@@ -726,7 +726,7 @@
 	repository as the <emphasis>tip revision</emphasis>, or simply
 	the <emphasis>tip</emphasis>.</para>
 
-      <para>By the way, the <command role="hg-cmd">hg tip</command>
+      <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
 	command accepts many of the same options as <command
 	  role="hg-cmd">hg log</command>, so <option
 	  role="hg-opt-global">-v</option> above indicates <quote>be
--- a/en/ch02-tour-merge.xml	Sat Apr 18 17:38:07 2009 +0200
+++ b/en/ch02-tour-merge.xml	Sat Apr 18 17:45:54 2009 +0200
@@ -164,7 +164,7 @@
 	</mediaobject>
       </figure>
 
-      <para>We sometimes talk about a merge having
+      <para id="x_69c">We sometimes talk about a merge having
 	<emphasis>sides</emphasis>: the left side is the first parent
 	in the output of <command role="hg-cmd">hg parents</command>,
 	and the right side is the second.  If the working directory
--- a/en/ch03-concepts.xml	Sat Apr 18 17:38:07 2009 +0200
+++ b/en/ch03-concepts.xml	Sat Apr 18 17:45:54 2009 +0200
@@ -524,13 +524,13 @@
     <sect2>
       <title>Merging and renames</title>
 
-      <para>A surprising number of revision control systems pay little
+      <para id="x_69a">A surprising number of revision control systems pay little
 	or no attention to a file's <emphasis>name</emphasis> over
 	time.  For instance, it used to be common that if a file got
 	renamed on one side of a merge, the changes from the other
 	side would be silently dropped.</para>
 
-      <para>Mercurial records metadata when you tell it to perform a
+      <para id="x_69b">Mercurial records metadata when you tell it to perform a
 	rename or copy. It uses this metadata during a merge to do the
 	right thing in the case of a merge.  For instance, if I rename
 	a file, and you edit it without renaming it, when we merge our
--- a/en/ch04-daily.xml	Sat Apr 18 17:38:07 2009 +0200
+++ b/en/ch04-daily.xml	Sat Apr 18 17:45:54 2009 +0200
@@ -357,7 +357,7 @@
 	<emphasis>destination</emphasis>, and all others are
 	<emphasis>sources</emphasis>.</para>
 
-      <para>If you pass <command role="hg-cmd">hg copy</command> a
+      <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a
 	single file as the source, and the destination does not exist,
 	it creates a new file with that name.</para>
 
@@ -430,7 +430,7 @@
       similar to the <command role="hg-cmd">hg copy</command>
       command.</para>
 
-    <para>If you're familiar with the Unix command line, you'll be
+    <para id="x_686">If you're familiar with the Unix command line, you'll be
       glad to know that <command role="hg-cmd">hg rename</command>
       command can be invoked as <command role="hg-cmd">hg
 	mv</command>.</para>
@@ -550,37 +550,37 @@
   <sect1>
     <title>Dealing with tricky merges</title>
 
-    <para>In a complicated or large project, it's not unusual for a
+    <para id="x_687">In a complicated or large project, it's not unusual for a
       merge of two changesets to result in some headaches.  Suppose
       there's a big source file that's been extensively edited by each
       side of a merge: this is almost inevitably going to result in
       conflicts, some of which can take a few tries to sort
       out.</para>
 
-    <para>Let's develop a simple case of this and see how to deal with
+    <para id="x_688">Let's develop a simple case of this and see how to deal with
       it.  We'll start off with a repository containing one file, and
       clone it twice.</para>
 
     &interaction.ch04-resolve.init;
 
-    <para>In one clone, we'll modify the file in one way.</para>
+    <para id="x_689">In one clone, we'll modify the file in one way.</para>
 
     &interaction.ch04-resolve.left;
 
-    <para>In another, we'll modify the file differently.</para>
+    <para id="x_68a">In another, we'll modify the file differently.</para>
 
     &interaction.ch04-resolve.right;
 
-    <para>Next, we'll pull each set of changes into our original
+    <para id="x_68b">Next, we'll pull each set of changes into our original
       repo.</para>
 
     &interaction.ch04-resolve.pull;
 
-    <para>We expect our repository to now contain two heads.</para>
+    <para id="x_68c">We expect our repository to now contain two heads.</para>
 
     &interaction.ch04-resolve.heads;
 
-    <para>Normally, if we run <command role="hg-cmd">hg
+    <para id="x_68d">Normally, if we run <command role="hg-cmd">hg
 	merge</command> at this point, it will drop us into a GUI that
       will let us manually resolve the conflicting edits to
       <filename>myfile.txt</filename>.  However, to simplify things
@@ -589,24 +589,24 @@
 
     &interaction.ch04-resolve.export;
 
-    <para>We've told Mercurial's merge machinery to run the command
+    <para id="x_68e">We've told Mercurial's merge machinery to run the command
       <command>false</command> (which, as we desire, fails
       immediately) if it detects a merge that it can't sort out
       automatically.</para>
 
-    <para>If we now fire up <command role="hg-cmd">hg
+    <para id="x_68f">If we now fire up <command role="hg-cmd">hg
 	merge</command>, it should grind to a halt and report a
 	failure.</para>
 
     &interaction.ch04-resolve.merge;
 
-    <para>Even if we don't notice that the merge failed, Mercurial
+    <para id="x_690">Even if we don't notice that the merge failed, Mercurial
       will prevent us from accidentally committing the result of a
       failed merge.</para>
 
     &interaction.ch04-resolve.cifail;
 
-    <para>When <command role="hg-cmd">hg commit</command> fails in
+    <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in
       this case, it suggests that we use the unfamiliar <command
 	role="hg-cmd">hg resolve</command> command.  As usual,
 	<command role="hg-cmd">hg help resolve</command> will print a
@@ -615,35 +615,35 @@
     <sect2>
       <title>File resolution states</title>
 
-      <para>When a merge occurs, most files will usually remain
+      <para id="x_692">When a merge occurs, most files will usually remain
 	unmodified.  For each file where Mercurial has to do
 	something, it tracks the state of the file.</para>
 
       <itemizedlist>
 	<listitem>
-	  <para>A <emphasis>resolved</emphasis> file has been
+	  <para id="x_693">A <emphasis>resolved</emphasis> file has been
 	    successfully merged, either automatically by Mercurial or
 	    manually with human intervention.</para>
 	</listitem>
 	<listitem>
-	  <para>An <emphasis>unresolved</emphasis> file was not merged
+	  <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged
 	    successfully, and needs more attention.</para>
 	</listitem>
       </itemizedlist>
 
-      <para>If Mercurial sees <emphasis>any</emphasis> file in the
+      <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the
 	unresolved state after a merge, it considers the merge to have
 	failed.  Fortunately, we do not need to restart the entire
 	merge from scratch.</para>
 
-      <para>The <option role="hg-opt-resolve">--list</option> or
+      <para id="x_696">The <option role="hg-opt-resolve">--list</option> or
 	<option role="hg-opt-resolve">-l</option> option to <command
 	  role="hg-cmd">hg resolve</command> prints out the state of
 	each merged file.</para>
 
       &interaction.ch04-resolve.list;
 
-      <para>In the output from <command role="hg-cmd">hg
+      <para id="x_697">In the output from <command role="hg-cmd">hg
 	  resolve</command>, a resolved file is marked with
 	<literal>R</literal>, while an unresolved file is marked with
 	<literal>U</literal>.  If any files are listed with
@@ -654,7 +654,7 @@
     <sect2>
       <title>Resolving a file merge</title>
 
-      <para>We have several options to move a file from the unresolved
+      <para id="x_698">We have several options to move a file from the unresolved
 	into the resolved state.  By far the most common is to rerun
 	<command role="hg-cmd">hg resolve</command>.  If we pass the
 	names of individual files or directories, it will retry the
@@ -664,7 +664,7 @@
 	will retry the merges of <emphasis>all</emphasis> unresolved
 	files.</para>
 
-      <para>Mercurial also lets us modify the resolution state of a
+      <para id="x_699">Mercurial also lets us modify the resolution state of a
 	file directly.  We can manually mark a file as resolved using
 	the <option role="hg-opt-resolve">--mark</option> option, or
 	as unresolved using the <option
--- a/en/ch05-collab.xml	Sat Apr 18 17:38:07 2009 +0200
+++ b/en/ch05-collab.xml	Sat Apr 18 17:45:54 2009 +0200
@@ -19,10 +19,12 @@
     <para id="x_44c">For interactive use, the web interface lets you browse a
       single repository or a collection of repositories.  You can view
       the history of a repository, examine each change (comments and
-      diffs), and view the contents of each directory and file.</para>
+      diffs), and view the contents of each directory and file.  You
+      can even get a view of history that gives a graphical view of
+      the relationships between individual changes and merges.</para>
 
-    <para id="x_44d">Also for human consumption, the web interface provides an
-      RSS feed of the changes in a repository.  This lets you
+    <para id="x_44d">Also for human consumption, the web interface provides
+      Atom and RSS feeds of the changes in a repository.  This lets you
       <quote>subscribe</quote> to a repository using your favorite
       feed reader, and be automatically notified of activity in that
       repository as soon as it happens.  I find this capability much
@@ -40,22 +42,40 @@
     <para id="x_44f">The easiest way to get started with the web interface is to
       use your web browser to visit an existing repository, such as
       the master Mercurial repository at <ulink
-	url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
+	url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
 
     <para id="x_450">If you're interested in providing a web interface
-      to your own repositories, Mercurial provides two ways to do
-      this.  The first is using the <command role="hg-cmd">hg
+      to your own repositories, there are several good ways to do
+      this.</para>
+
+    <para id="x_69d">The easiest and fastest way to get started in an informal
+      environment is to use the <command role="hg-cmd">hg
 	serve</command> command, which is best suited to short-term
       <quote>lightweight</quote> serving.  See <xref
 	linkend="sec:collab:serve"/> below for details of how to use
-      this command.  If you have a long-lived repository that you'd
-      like to make permanently available, Mercurial has built-in
-      support for the CGI (Common Gateway Interface) standard, which
-      all common web servers support.  See <xref
-	linkend="sec:collab:cgi"/> for details of CGI
+      this command.</para>
+
+    <para id="x_69e">For longer-lived repositories that you'd like to have
+      permanently available, there are several public hosting services
+      available.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para id="x_69f">Bitbucket, at <ulink
+	    url="http://bitbucket.org/">http://bitbucket.org/</ulink>,
+	  provides free hosting for open source projects, and paid
+	  hosting for commercial projects.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
+      has built-in support for several popular hosting technologies,
+      most notably CGI (Common Gateway Interface), and WSGI (Web
+      Services Gateway Interface).  See <xref
+	linkend="sec:collab:cgi"/> for details of CGI and WSGI
       configuration.</para>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Collaboration models</title>
 
@@ -96,8 +116,8 @@
 	could avoid this particular problem by writing a hook that
 	prevents changes from being merged from an inappropriate
 	branch.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Informal anarchy</title>
 
@@ -115,7 +135,7 @@
 	place) and spend several days more or less locked in there,
 	hacking intensely on a handful of projects.</para>
 
-      <para id="x_457">A sprint is the perfect place to use the
+      <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
 	<command role="hg-cmd">hg serve</command> command, since
 	<command role="hg-cmd">hg serve</command> does not require any
 	fancy server infrastructure.  You can get started with
@@ -129,14 +149,15 @@
 	they can clone a branch containing a new feature and try it
 	out.</para>
 
-      <para id="x_458">The charm, and the problem, with doing things in an ad hoc
-	fashion like this is that only people who know about your
-	changes, and where they are, can see them.  Such an informal
-	approach simply doesn't scale beyond a handful people, because
-	each individual needs to know about $n$ different repositories
-	to pull from.</para>
+      <para id="x_458">The charm, and the problem, with doing things
+	in an ad hoc fashion like this is that only people who know
+	about your changes, and where they are, can see them.  Such an
+	informal approach simply doesn't scale beyond a handful
+	people, because each individual needs to know about
+	<emphasis>n</emphasis> different repositories to pull
+	from.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>A single central repository</title>
 
@@ -162,17 +183,39 @@
 	lets us put off publishing the potentially unsafe change until
 	it has had a little testing.</para>
 
-      <para id="x_45c">In this kind of scenario, people usually use
-	the <command>ssh</command> protocol to securely push changes
-	to the central repository, as documented in <xref
+      <para id="x_45c">If a team is hosting its own repository in this
+	kind of scenario, people will usually use the
+	<command>ssh</command> protocol to securely push changes to
+	the central repository, as documented in <xref
 	  linkend="sec:collab:ssh"/>.  It's also usual to publish a
-	read-only copy of the repository over HTTP using CGI, as in
-	<xref linkend="sec:collab:cgi"/>. Publishing
-	over HTTP satisfies the needs of people who don't have push
-	access, and those who want to use web browsers to browse the
-	repository's history.</para>
+	read-only copy of the repository over HTTP, as in
+	<xref linkend="sec:collab:cgi"/>. Publishing over HTTP
+	satisfies the needs of people who don't have push access, and
+	those who want to use web browsers to browse the repository's
+	history.</para>
+    </sect2>
+
+    <sect2>
+      <title>A hosted central repository</title>
 
+      <para id="x_6a1">A wonderful thing about public hosting services like
+	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
+	not only do they handle the fiddly server configuration
+	details, such as user accounts, authentication, and secure
+	wire protocols, they provide additional infrastructure to make
+	this model work well.</para>
+
+      <para id="x_6a2">For instance, a well-engineered hosting service will let
+	people clone their own copies of a repository with a single
+	click.  This lets people work in separate spaces and share
+	their changes when they're ready.</para>
+
+      <para id="x_6a3">In addition, a good hosting service will let people
+	communicate with each other, for instance to say <quote>there
+	  are changes ready for you to review in this
+	  tree</quote>.</para>
     </sect2>
+
     <sect2>
       <title>Working with multiple branches</title>
 
@@ -196,7 +239,7 @@
 	another as the need arises.  Because repositories are
 	independent of each other, unstable changes in a development
 	branch will never affect a stable branch unless someone
-	explicitly merges those changes in.</para>
+	explicitly merges those changes into the stable branch.</para>
 
       <para id="x_45f">Here's an example of how this can work in practice.  Let's
 	say you have one <quote>main branch</quote> on a central
@@ -227,38 +270,41 @@
       &interaction.branching.update;
 
       <para id="x_464">In addition, immediately after the main branch is tagged,
-	someone can then clone the main branch on the server to a new
+	we can then clone the main branch on the server to a new
 	<quote>stable</quote> branch, also on the server.</para>
 
       &interaction.branching.clone;
 
-      <para id="x_465">Someone who needs to make a change to the stable branch
-	can then clone <emphasis>that</emphasis> repository, make
-	their changes, commit, and push their changes back there.</para>
+      <para id="x_465">If we need to make a change to the stable
+	branch, we can then clone <emphasis>that</emphasis>
+	repository, make our changes, commit, and push our changes
+	back there.</para>
 
       &interaction.branching.stable;
 
       <para id="x_466">Because Mercurial repositories are independent, and
 	Mercurial doesn't move changes around automatically, the
 	stable and main branches are <emphasis>isolated</emphasis>
-	from each other.  The changes that you made on the main branch
+	from each other.  The changes that we made on the main branch
 	don't <quote>leak</quote> to the stable branch, and vice
 	versa.</para>
 
-      <para id="x_467">You'll often want all of your bugfixes on the stable
+      <para id="x_467">We'll often want all of our bugfixes on the stable
 	branch to show up on the main branch, too.  Rather than
-	rewrite a bugfix on the main branch, you can simply pull and
+	rewrite a bugfix on the main branch, we can simply pull and
 	merge changes from the stable to the main branch, and
-	Mercurial will bring those bugfixes in for you.</para>
+	Mercurial will bring those bugfixes in for us.</para>
+
+      &interaction.branching.merge;
 
-	&interaction.branching.merge;
+      <para id="x_468">The main branch will still contain changes that
+	are not on the stable branch, but it will also contain all of
+	the bugfixes from the stable branch.  The stable branch
+	remains unaffected by these changes, since changes are only
+	flowing from the stable to the main branch, and not the other
+	way.</para>
+    </sect2>
 
-      <para id="x_468">The main branch will still contain changes that are not on
-	the stable branch, but it will also contain all of the
-	bugfixes from the stable branch.  The stable branch remains
-	unaffected by these changes.</para>
-
-    </sect2>
     <sect2>
       <title>Feature branches</title>
 
@@ -281,8 +327,8 @@
 	shape, someone on that feature team pulls and merges from the
 	master branch into the feature branch, then pushes back up to
 	the master branch.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>The release train</title>
 
@@ -297,8 +343,8 @@
 	went out on that train release into the feature branch, and
 	the team continues its work on top of that release so that
 	their feature can make the next release.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>The Linux kernel model</title>
 
@@ -372,8 +418,8 @@
 	it appropriate; and the pace of development is astounding.
 	And yet Linux is a highly successful, well-regarded piece of
 	software.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Pull-only versus shared-push collaboration</title>
 
@@ -391,12 +437,11 @@
 	you'll have to roll your own approach on top (such as applying
 	a patch by hand).</para>
 
-      <para id="x_478">A good distributed revision control tool, such as
-	Mercurial, will support both models.  You and your
-	collaborators can then structure how you work together based
-	on your own needs and preferences, not on what contortions
-	your tools force you into.</para>
-
+      <para id="x_478">A good distributed revision control tool will
+	support both models.  You and your collaborators can then
+	structure how you work together based on your own needs and
+	preferences, not on what contortions your tools force you
+	into.</para>
     </sect2>
     <sect2>
       <title>Where collaboration meets branch management</title>
@@ -409,16 +454,16 @@
 	Even though this subject is intimately related to how your
 	team collaborates, it's dense enough to merit treatment of its
 	own, in <xref linkend="chap:branch"/>.</para>
-
     </sect2>
   </sect1>
+
   <sect1>
     <title>The technical side of sharing</title>
 
     <para id="x_47a">The remainder of this chapter is devoted to the question of
-      serving data to your collaborators.</para>
+      sharing changes with your collaborators.</para>
+  </sect1>
 
-  </sect1>
   <sect1 id="sec:collab:serve">
     <title>Informal sharing with <command role="hg-cmd">hg
 	serve</command></title>
@@ -495,9 +540,9 @@
 	find out what URL you should send to your collaborators, start
 	it with the <option role="hg-opt-global">-v</option>
 	option.</para>
-
     </sect2>
   </sect1>
+
   <sect1 id="sec:collab:ssh">
     <title>Using the Secure Shell (ssh) protocol</title>
 
@@ -506,11 +551,11 @@
       protocol.  To use this successfully, you may have to do a little
       bit of configuration on the client or server sides.</para>
 
-    <para id="x_487">If you're not familiar with ssh, it's a network protocol
-      that lets you securely communicate with another computer.  To
-      use it with Mercurial, you'll be setting up one or more user
-      accounts on a server so that remote users can log in and execute
-      commands.</para>
+    <para id="x_487">If you're not familiar with ssh, it's the name of
+      both a command and a network protocol that let you securely
+      communicate with another computer.  To use it with Mercurial,
+      you'll be setting up one or more user accounts on a server so
+      that remote users can log in and execute commands.</para>
 
     <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
       probably find some of the material that follows to be elementary
@@ -569,8 +614,8 @@
 	<emphasis>absolute</emphasis> path on the server, begin the
 	path component with two slashes, as in this example.</para>
       <programlisting>ssh://server//absolute/path</programlisting>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Finding an ssh client for your system</title>
 
@@ -582,44 +627,44 @@
 	unlikely event that it isn't present, take a look at your
 	system documentation to figure out how to install it.</para>
 
-      <para id="x_494">On Windows, you'll first need to download a suitable ssh
-	client.  There are two alternatives.</para>
-      <itemizedlist>
-	<listitem><para id="x_495">Simon Tatham's excellent PuTTY package
-	    <citation>web:putty</citation> provides a complete suite
-	    of ssh client commands.</para>
-	</listitem>
-	<listitem><para id="x_496">If you have a high tolerance for pain, you can
-	    use the Cygwin port of OpenSSH.</para>
-	</listitem></itemizedlist>
-      <para id="x_497">In either case, you'll need to edit your <filename
-      role="special">hg.ini</filename> file to
-	tell Mercurial where to find the actual client command.  For
-	example, if you're using PuTTY, you'll need to use the
-	<command>plink</command> command as a command-line ssh
-	client.</para>
-      <programlisting>[ui]
-ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"</programlisting>
+      <para id="x_494">On Windows, the TortoiseHg package is bundled
+	with a version of Simon Tatham's excellent
+	<command>plink</command> command, and you should not need to
+	do any further configuration.</para>
+    </sect2>
 
-      <note>
-	<para id="x_498">  The path to <command>plink</command> shouldn't contain
-	  any whitespace characters, or Mercurial may not be able to
-	  run it correctly (so putting it in <filename
-	    class="directory">C:\Program Files</filename> is probably
-	  not a good idea).</para>
-      </note>
-
-    </sect2>
     <sect2>
       <title>Generating a key pair</title>
 
-      <para id="x_499">To avoid the need to repetitively type a password every
-	time you need to use your ssh client, I recommend generating a
-	key pair.  On a Unix-like system, the
-	<command>ssh-keygen</command> command will do the trick. On
-	Windows, if you're using PuTTY, the
-	<command>puttygen</command> command is what you'll
-	need.</para>
+      <para id="x_499">To avoid the need to repetitively type a
+	password every time you need to use your ssh client, I
+	recommend generating a key pair.</para>
+
+      <tip>
+	<title>Key pairs are not mandatory</title>
+
+	<para id="x_6a4">Mercurial knows nothing about ssh authentication or key
+	  pairs.  You can, if you like, safely ignore this section and
+	  the one that follows until you grow tired of repeatedly
+	  typing ssh passwords.</para>
+      </tip>
+
+      <itemizedlist>
+	<listitem>
+	  <para id="x_6a5">On a Unix-like system, the
+	    <command>ssh-keygen</command> command will do the
+	    trick.</para>
+	  <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
+	    to download a command named <command>puttygen</command>
+	    from <ulink
+	      url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
+	      PuTTY web site</ulink> to generate a key pair.  See
+	    <ulink
+	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 
+	      <command>puttygen</command> documentation</ulink> for
+	    details of how use the command.</para>
+	</listitem>
+      </itemizedlist>
 
       <para id="x_49a">When you generate a key pair, it's usually
 	<emphasis>highly</emphasis> advisable to protect it with a
@@ -642,7 +687,6 @@
 	public key to a file of your choosing, or paste it from the
 	window it's displayed in straight into the <filename
 	  role="special">authorized_keys</filename> file.</para>
-
     </sect2>
     <sect2>
       <title>Using an authentication agent</title>
@@ -663,21 +707,34 @@
 	judgment as to whether this is an acceptable risk.  It
 	certainly saves a lot of repeated typing.</para>
 
-      <para id="x_49f">On Unix-like systems, the agent is called
-	<command>ssh-agent</command>, and it's often run automatically
-	for you when you log in.  You'll need to use the
-	<command>ssh-add</command> command to add passphrases to the
-	agent's store.  On Windows, if you're using PuTTY, the
-	<command>pageant</command> command acts as the agent.  It adds
-	an icon to your system tray that will let you manage stored
-	passphrases.</para>
+      <itemizedlist>
+	<listitem>
+	  <para id="x_49f">On Unix-like systems, the agent is called
+	    <command>ssh-agent</command>, and it's often run
+	    automatically for you when you log in.  You'll need to use
+	    the <command>ssh-add</command> command to add passphrases
+	    to the agent's store.</para>
+	</listitem>
+	<listitem>
+	  <para id="x_6a7">On Windows, if you're using TortoiseHg, the
+	    <command>pageant</command> command acts as the agent.  As
+	    with <command>puttygen</command>, you'll need to <ulink
+	      url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
+	      <command>pageant</command></ulink> from the PuTTY web
+	    site and read <ulink
+	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 
+	      documentation</ulink>.  The <command>pageant</command>
+	    command adds an icon to your system tray that will let you
+	    manage stored passphrases.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Configuring the server side properly</title>
 
       <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
-	there's a variety of things that can go wrong.  Add Mercurial
+	a variety of things can go wrong.  Add Mercurial
 	on top, and there's plenty more scope for head-scratching.
 	Most of these potential problems occur on the server side, not
 	the client side.  The good news is that once you've gotten a
@@ -821,7 +878,6 @@
 	If you run into problems with Mercurial and ssh at this point,
 	try using the <option role="hg-opt-global">--debug</option>
 	option to get a clearer picture of what's going on.</para>
-
     </sect2>
     <sect2>
       <title>Using compression with ssh</title>
@@ -842,31 +898,40 @@
 	accept a <option role="cmd-opt-ssh">-C</option> option which
 	turns on compression.  You can easily edit your <filename
 	  role="special">~/.hgrc</filename> to enable compression for
-	all of Mercurial's uses of the ssh protocol.</para>
+	all of Mercurial's uses of the ssh protocol.  Here is how to
+	do so for regular <command>ssh</command> on Unix-like systems,
+	for example.</para>
       <programlisting>[ui]
 ssh = ssh -C</programlisting>
 
-      <para id="x_4b9">If you use <command>ssh</command>, you can configure it to
-	always use compression when talking to your server.  To do
-	this, edit your <filename
-	  role="special">.ssh/config</filename> file (which may not
-	yet exist), as follows.</para>
+      <para id="x_4b9">If you use <command>ssh</command> on a
+	Unix-like system, you can configure it to always use
+	compression when talking to your server.  To do this, edit
+	your <filename role="special">.ssh/config</filename> file
+	(which may not yet exist), as follows.</para>
+
       <programlisting>Host hg
   Compression yes
   HostName hg.example.com</programlisting>
-      <para id="x_4ba">This defines an alias, <literal>hg</literal>.  When you
-	use it on the <command>ssh</command> command line or in a
-	Mercurial <literal>ssh</literal>-protocol URL, it will cause
+
+      <para id="x_4ba">This defines a hostname alias,
+	<literal>hg</literal>.  When you use that hostname on the
+	<command>ssh</command> command line or in a Mercurial
+	<literal>ssh</literal>-protocol URL, it will cause
 	<command>ssh</command> to connect to
 	<literal>hg.example.com</literal> and use compression.  This
 	gives you both a shorter name to type and compression, each of
 	which is a good thing in its own right.</para>
-
     </sect2>
   </sect1>
+
   <sect1 id="sec:collab:cgi">
     <title>Serving over HTTP using CGI</title>
 
+    <para id="x_6a8">The simplest way to host one or more repositories in a
+      permanent way is to use a web server and Mercurial's CGI
+      support.</para>
+
     <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
       CGI interface can take anything from a few moments to several
       hours.</para>
@@ -877,13 +942,20 @@
       your web server's configuration.</para>
 
     <note>
-      <para id="x_4bd">  Configuring a web server is a complex, fiddly, and
-	highly system-dependent activity.  I can't possibly give you
-	instructions that will cover anything like all of the cases
-	you will encounter. Please use your discretion and judgment in
-	following the sections below.  Be prepared to make plenty of
-	mistakes, and to spend a lot of time reading your server's
-	error logs.</para>
+      <title>High pain tolerance required</title>
+
+      <para id="x_4bd">Configuring a web server is a complex, fiddly,
+	and highly system-dependent activity.  I can't possibly give
+	you instructions that will cover anything like all of the
+	cases you will encounter. Please use your discretion and
+	judgment in following the sections below.  Be prepared to make
+	plenty of mistakes, and to spend a lot of time reading your
+	server's error logs.</para>
+
+      <para id="x_6a9">If you don't have a strong stomach for tweaking
+	configurations over and over, or a compelling need to host
+	your own services, you might want to try one of the public
+	hosting services that I mentioned earlier.</para>
     </note>
 
     <sect2>
@@ -893,9 +965,10 @@
 	aspects of your system's setup.</para>
 
       <orderedlist>
-	<listitem><para id="x_4bf">Do you have a web server installed at all?
-	    Mac OS X ships with Apache, but many other systems may not
-	    have a web server installed.</para>
+	<listitem><para id="x_4bf">Do you have a web server installed
+	    at all? Mac OS X and some Linux distributions ship with
+	    Apache, but many other systems may not have a web server
+	    installed.</para>
 	</listitem>
 	<listitem><para id="x_4c0">If you have a web server installed, is it
 	    actually running?  On most systems, even if one is
@@ -917,8 +990,8 @@
 	repositories.  And <literal>lighttpd</literal> is undeniably
 	<emphasis>much</emphasis> easier to get started with than
 	Apache.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Basic CGI configuration</title>
 
@@ -1048,8 +1121,8 @@
 	<para id="x_4d0">At this point, when you try to reload the page, you
 	  should be presented with a nice HTML view of your
 	  repository's history.  Whew!</para>
+      </sect3>
 
-      </sect3>
       <sect3>
 	<title>Configuring lighttpd</title>
 
@@ -1084,9 +1157,9 @@
 	  configure than Apache, even though I've used Apache for over
 	  a decade, and this was my first exposure to
 	  <literal>lighttpd</literal>.</para>
-
       </sect3>
     </sect2>
+
     <sect2>
       <title>Sharing multiple repositories with one CGI script</title>
 
@@ -1215,14 +1288,16 @@
 	  file.</para>
 
 	<note>
-	  <para id="x_4e2">  If multiple repositories have the same virtual path,
-	    <filename role="special">hgwebdir.cgi</filename> will not
-	    report an error.  Instead, it will behave
-	    unpredictably.</para>
+	  <title>Beware duplicate virtual paths</title>
+
+	  <para id="x_4e2">  If several repositories have the same
+	    virtual path, <filename
+	      role="special">hgwebdir.cgi</filename> will not report
+	    an error.  Instead, it will behave unpredictably.</para>
 	</note>
-
       </sect3>
     </sect2>
+
     <sect2>
       <title>Downloading source archives</title>
 
@@ -1235,8 +1310,7 @@
 	you'll need to add an <envar
 	  role="rc-item-web">allow_archive</envar> item to the
 	<literal role="rc-web">web</literal> section of your <filename
-	  role="special">~/.hgrc</filename>.</para>
-
+	  role="special">~/.hgrc</filename>; see below for details.</para>
     </sect2>
     <sect2>
       <title>Web configuration options</title>
@@ -1318,9 +1392,28 @@
 	<listitem><para id="x_4f0"><envar
 	      role="rc-item-web">style</envar>: Controls the template
 	    Mercurial uses to display the web interface.  Mercurial
-	    ships with two web templates, named
-	    <literal>default</literal> and <literal>gitweb</literal>
-	    (the latter is much more visually attractive).  You can
+	    ships with several web templates.</para>
+	  <itemizedlist>
+	    <listitem>
+	      <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ab"><literal>gitweb</literal> emulates the visual
+		style of git's web interface.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
+		greys.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ad"><literal>paper</literal> is the default.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ae"><literal>spartan</literal> was the default for a
+		long time.</para>
+	    </listitem>
+	  </itemizedlist>
+	  <para id="x_6af">You can
 	    also specify a custom template of your own; see 
 	    <xref linkend="chap:template"/> for details. Here, you can
 	    see how to enable the <literal>gitweb</literal>
@@ -1361,8 +1454,8 @@
 	      interface.  This overrides the default name, which is
 	      the last component of the repository's path.</para>
 	  </listitem></itemizedlist>
+      </sect3>
 
-      </sect3>
       <sect3>
 	<title>Options specific to the <command role="hg-cmd">hg
 	    serve</command> command</title>
@@ -1400,8 +1493,8 @@
 	      Integer.  The TCP port number on which the server should
 	      listen.  The default port number used is 8000.</para>
 	  </listitem></itemizedlist>
+      </sect3>
 
-      </sect3>
       <sect3>
 	<title>Choosing the right <filename
 	    role="special">~/.hgrc</filename> file to add <literal
@@ -1423,10 +1516,55 @@
 	  <filename role="special">~/.hgrc</filename> file in the
 	  home directory of the user ID that runs your web server, or
 	  add those settings to a system-wide <filename
-	    role="special">~/.hgrc</filename> file.</para>
+	    role="special">hgrc</filename> file.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>System-wide configuration</title>
+
+    <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
+      server to which people publish changes), it often makes sense to
+      set up some global default behaviors, such as what theme to use
+      in web interfaces.</para>
+
+    <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
+      exists, Mercurial will read it at startup time and apply any
+      configuration settings it finds in that file.  It will also look
+      for files ending in a <literal>.rc</literal> extension in a
+      directory named <filename>/etc/mercurial/hgrc.d</filename>, and
+      apply any configuration settings it finds in each of those
+      files.</para>
+
+    <sect2>
+      <title>Making Mercurial more trusting</title>
 
+      <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
+	can be useful is if users are pulling changes owned by other
+	users.  By default, Mercurial will not trust most of the
+	configuration items in a <filename>.hg/hgrc</filename> file
+	inside a repository that is owned by a different user. If we
+	clone or pull changes from such a repository, Mercurial will
+	print a warning stating that it does not trust their
+	<filename>.hg/hgrc</filename>.</para>
 
-      </sect3>
+      <para id="x_6b3">If everyone in a particular Unix group is on the same team
+	and <emphasis>should</emphasis> trust each other's
+	configuration settings, or we want to trust particular users,
+	we can override Mercurial's skeptical defaults by creating a
+	system-wide <filename>hgrc</filename> file such as the
+	following:</para>
+
+    <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
+[trusted]
+# Trust all entries in any hgrc file owned by the "editors" or
+# "www-data" groups.
+groups = editors, www-data
+
+# Trust entries in hgrc files owned by the following users.
+users = apache, bobo
+</programlisting>
     </sect2>
   </sect1>
 </chapter>
--- a/en/ch06-filenames.xml	Sat Apr 18 17:38:07 2009 +0200
+++ b/en/ch06-filenames.xml	Sat Apr 18 17:45:54 2009 +0200
@@ -27,8 +27,8 @@
       before continuing with the current directory.</para>
 
       &interaction.filenames.dirs;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Running commands without any file names</title>
 
@@ -70,8 +70,8 @@
 	role="hg-cmd">hg root</command> command.</para>
 
       &interaction.filenames.wdir-relname;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Telling you what's going on</title>
 
@@ -85,17 +85,17 @@
     <para id="x_54d">The principle here is of <emphasis>least
 	surprise</emphasis>.  If you've exactly named a file on the
       command line, there's no point in repeating it back at you.  If
-      Mercurial is acting on a file <emphasis>implicitly</emphasis>,
+      Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g.
       because you provided no names, or a directory, or a pattern (see
-      below), it's safest to tell you what it's doing.</para>
+      below), it is safest to tell you what files it's operating on.</para>
 
     <para id="x_54e">For commands that behave this way, you can silence them
       using the <option role="hg-opt-global">-q</option> option.  You
       can also get them to print the name of every file, even those
       you've named explicitly, using the <option
 	role="hg-opt-global">-v</option> option.</para>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Using patterns to identify files</title>
 
@@ -194,9 +194,9 @@
 	  example illustrates the difference between the two.</para>
 
 	  &interaction.filenames.glob.star-starstar;
-
       </sect3>
     </sect2>
+
     <sect2>
       <title>Regular expression matching with <literal>re</literal>
 	patterns</title>
@@ -227,9 +227,9 @@
 	string; it doesn't look for a match anywhere within the
 	string.  To match anywhere in a string, start your pattern
 	with <quote><literal>.*</literal></quote>.</para>
-
     </sect2>
   </sect1>
+
   <sect1>
     <title>Filtering files</title>
 
@@ -266,14 +266,65 @@
 	pattern</quote>.</para>
 
     &interaction.filenames.filter.exclude;
+  </sect1>
 
-  </sect1>
   <sect1>
-    <title>Ignoring unwanted files and directories</title>
+    <title>Permanently ignoring unwanted files and directories</title>
+
+    <para id="x_569">When you create a new repository, the chances are
+      that over time it will grow to contain files that ought to
+      <emphasis>not</emphasis> be managed by Mercurial, but which you
+      don't want to see listed every time you run <command>hg
+	status</command>.  For instance, <quote>build products</quote>
+      are files that are created as part of a build but which should
+      not be managed by a revision control system.  The most common
+      build products are output files produced by software tools such
+      as compilers.  As another example, many text editors litter a
+      directory with lock files, temporary working files, and backup
+      files, which it also makes no sense to manage.</para>
+
+    <para id="x_6b4">To have Mercurial permanently ignore such files, create a
+      file named <filename>.hgignore</filename> in the root of your
+      repository.  You <emphasis>should</emphasis> <command>hg
+      add</command> this file so that it gets tracked with the rest of
+      your repository contents, since your collaborators will probably
+      find it useful too.</para>
+
+    <para id="x_6b5">By default, the <filename>.hgignore</filename> file should
+      contain a list of regular expressions, one per line.  Empty
+      lines are skipped. Most people prefer to describe the files they
+      want to ignore using the <quote>glob</quote> syntax that we
+      described above, so a typical <filename>.hgignore</filename>
+      file will start with this directive:</para>
 
-    <para id="x_569">XXX.</para>
+    <programlisting>syntax: glob</programlisting>
+
+    <para id="x_6b6">This tells Mercurial to interpret the lines that follow as
+      glob patterns, not regular expressions.</para>
+
+    <para id="x_6b7">Here is a typical-looking <filename>.hgignore</filename>
+      file.</para>
+
+    <programlisting>syntax: glob
+# This line is a comment, and will be skipped.
+# Empty lines are skipped too.
 
+# Backup files left behind by the Emacs editor.
+*~
+
+# Lock files used by the Emacs editor.
+# Notice that the "#" character is quoted with a backslash.
+# This prevents it from being interpreted as starting a comment.
+.\#*
+
+# Temporary files used by the vim editor.
+.*.swp
+
+# A hidden file created by the Mac OS X Finder.
+.DS_Store
+</programlisting>
   </sect1>
+
   <sect1 id="sec:names:case">
     <title>Case sensitivity</title>
 
@@ -361,8 +412,8 @@
 	conflict between the two file names that the filesystem would
 	treat as the same, and forbid the update or merge from
 	occurring.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Fixing a case conflict</title>
 
@@ -388,15 +439,6 @@
 	<command role="hg-cmd">hg update</command> your working
 	directory to that changeset on a Windows or MacOS system, but
 	you can continue development unimpeded.</para>
-
-      <note>
-	<para id="x_577">  Prior to version 0.9.3, Mercurial did not use a case
-	  safe repository storage mechanism, and did not detect case
-	  folding conflicts.  If you are using an older version of
-	  Mercurial on Windows or MacOS, I strongly recommend that you
-	  upgrade.</para>
-      </note>
-
     </sect2>
   </sect1>
 </chapter>
--- a/en/ch07-branch.xml	Sat Apr 18 17:38:07 2009 +0200
+++ b/en/ch07-branch.xml	Sat Apr 18 17:45:54 2009 +0200
@@ -128,7 +128,7 @@
 
     <para id="x_37c">Mercurial stores tags in a normal revision-controlled file
       in your repository.  If you've created any tags, you'll find
-      them in a file named <filename
+      them in a file in the root of your repository named <filename
 	role="special">.hgtags</filename>.  When you run the <command
 	role="hg-cmd">hg tag</command> command, Mercurial modifies
       this file, then automatically commits the change to it.  This
@@ -170,8 +170,8 @@
 	location of the error, which you can then fix and commit.  You
 	should then run <command role="hg-cmd">hg tags</command>
 	again, just to be sure that your fix is correct.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>Tags and cloning</title>
 
@@ -195,8 +195,8 @@
 	project's history in the new repository, but
 	<emphasis>not</emphasis> the tag you might have
 	expected.</para>
+    </sect2>
 
-    </sect2>
     <sect2>
       <title>When permanent tags are too much</title>
 
@@ -221,9 +221,9 @@
 	controlled.  Any tags you create using <option
 	  role="hg-opt-tag">-l</option> remain strictly local to the
 	repository you're currently working in.</para>
-
     </sect2>
   </sect1>
+
   <sect1>
     <title>The flow of changes&emdash;big picture vs. little</title>
 
@@ -252,8 +252,8 @@
 	  merging changes.  They expose the narrative of how the code
 	  was developed.</para>
       </listitem></itemizedlist>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Managing big-picture branches in repositories</title>
 
@@ -285,8 +285,8 @@
       the <literal>myproject</literal> repository.</para>
 
     &interaction.branch-repo.new;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Don't repeat yourself: merging across branches</title>
 
@@ -308,8 +308,8 @@
       push back to the main branch.</para>
 
     &interaction.branch-repo.merge;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Naming branches within one repository</title>
 
@@ -408,8 +408,8 @@
     <para id="x_39d">In practice, this is something you won't do very often, as
       branch names tend to have fairly long lifetimes.  (This isn't a
       rule, just an observation.)</para>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Dealing with multiple named branches in a
       repository</title>
@@ -454,8 +454,8 @@
       introduces a new head.</para>
 
     &interaction.branch-named.foo-commit;
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Branch names and merging</title>
 
@@ -496,8 +496,8 @@
       Mercurial will choose the <quote>right</quote>
       (<literal>bleeding-edge</literal>) branch name when I pull and
       merge from <literal>stable</literal>.</para>
+  </sect1>
 
-  </sect1>
   <sect1>
     <title>Branch naming is generally useful</title>
 
@@ -522,7 +522,6 @@
 	/.hgrc</filename>.</para>
     <programlisting>[hooks]
 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
-
   </sect1>
 </chapter>