1.1 --- a/en/ch04-daily.xml	Thu Apr 23 22:24:02 2009 -0700
     1.2 +++ b/en/ch04-daily.xml	Fri Apr 24 00:27:05 2009 -0700
     1.3 @@ -1,6 +1,6 @@
     1.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5  
     1.6 -<chapter id="chap:daily">
     1.7 +<chapter &#105;id="chap:daily">
     1.8    <?dbhtml filename="mercurial-in-daily-use.html"?>
     1.9    <title>Mercurial in daily use</title>
    1.10  
    1.11 @@ -673,6 +673,162 @@
    1.12  	track of our progress with each file as we go.</para>
    1.13      </sect2>
    1.14    </sect1>
    1.15 +
    1.16 +  <sect1>
    1.17 +    <title>More useful diffs</title>
    1.18 +
    1.19 +    <para>The default output of the <command role="hg-cmd">hg
    1.20 +	diff</command> command is backwards compatible with the
    1.21 +      regular <command>diff</command> command, but this has some
    1.22 +      drawbacks.</para>
    1.23 +
    1.24 +    <para>Consider the case where we use <command role="hg-cmd">hg
    1.25 +	rename</command> to rename a file.</para>
    1.26 +
    1.27 +    &interaction.ch04-diff.rename.basic;
    1.28 +
    1.29 +    <para>The output of <command role="hg-cmd">hg diff</command> above
    1.30 +      obscures the fact that we simply renamed a file.  The <command
    1.31 +	role="hg-cmd">hg diff</command> command accepts an option,
    1.32 +      <option>--git</option> or <option>-g</option>, to use a newer
    1.33 +      diff format that displays such information in a more readable
    1.34 +      form.</para>
    1.35 +
    1.36 +    &interaction.ch04-diff.rename.git;
    1.37 +
    1.38 +    <para>This option also helps with a case that can otherwise be
    1.39 +      confusing: a file that appears to be modified according to
    1.40 +      <command role="hg-cmd">hg status</command>, but for which
    1.41 +      <command role="hg-cmd">hg diff</command> prints nothing. This
    1.42 +      situation can arise if we change the file's execute
    1.43 +      permissions.</para>
    1.44 +
    1.45 +    &interaction.ch04-diff.chmod;
    1.46 +
    1.47 +    <para>The normal <command>diff</command> command pays no attention
    1.48 +      to file permissions, which is why <command role="hg-cmd">hg
    1.49 +	diff</command> prints nothing by default.  If we supply it
    1.50 +      with the <option>-g</option> option, it tells us what really
    1.51 +      happened.</para>
    1.52 +
    1.53 +    &interaction.ch04-diff.chmod.git;
    1.54 +  </sect1>
    1.55 +
    1.56 +  <sect1>
    1.57 +    <title>Which files to manage, and which to avoid</title>
    1.58 +
    1.59 +    <para>Revision control systems are generally best at managing text
    1.60 +      files that are written by humans, such as source code, where the
    1.61 +      files do not change much from one revision to the next.  Some
    1.62 +      centralized revision control systems can also deal tolerably
    1.63 +      well with binary files, such as bitmap images.</para>
    1.64 +
    1.65 +    <para>For instance, a game development team will typically manage
    1.66 +      both its source code and all of its binary assets (e.g. geometry
    1.67 +      data, textures, map layouts) in a revision control
    1.68 +      system.</para>
    1.69 +
    1.70 +    <para>Because it is usually impossible to merge two conflicting
    1.71 +      modifications to a binary file, centralized systems often
    1.72 +      provide a file locking mechanism that allow a user to say
    1.73 +      <quote>I am the only person who can edit this
    1.74 +	file</quote>.</para>
    1.75 +
    1.76 +    <para>Compared to a centralized system, a distributed revision
    1.77 +      control system changes some of the factors that guide decisions
    1.78 +      over which files to manage and how.</para>
    1.79 +
    1.80 +    <para>For instance, a distributed revision control system cannot,
    1.81 +      by its nature, offer a file locking facility.  There is thus no
    1.82 +      built-in mechanism to prevent two people from making conflicting
    1.83 +      changes to a binary file.  If you have a team where several
    1.84 +      people may be editing binary files frequently, it may not be a
    1.85 +      good idea to use Mercurial&emdash;or any other distributed
    1.86 +      revision control system&emdash;to manage those files.</para>
    1.87 +
    1.88 +    <para>When storing modifications to a file, Mercurial usually
    1.89 +      saves only the differences between the previous and current
    1.90 +      versions of the file.  For most text files, this is extremely
    1.91 +      efficient. However, some files (particularly binary files) are
    1.92 +      laid out in such a way that even a small change to a file's
    1.93 +      logical content results in many or most of the bytes inside the
    1.94 +      file changing.  For instance, compressed files are particularly
    1.95 +      susceptible to this. If the differences between each successive
    1.96 +      version of a file are always large, Mercurial will not be able
    1.97 +      to store the file's revision history very efficiently.  This can
    1.98 +      affect both local storage needs and the amount of time it takes
    1.99 +      to clone a repository.</para>
   1.100 +
   1.101 +    <para>To get an idea of how this could affect you in practice,
   1.102 +      suppose you want to use Mercurial to manage an OpenOffice
   1.103 +      document.  OpenOffice stores documents on disk as compressed zip
   1.104 +      files. Edit even a single letter of your document in OpenOffice,
   1.105 +      and almost every byte in the entire file will change when you
   1.106 +      save it. Now suppose that file is 2MB in size.  Because most of
   1.107 +      the file changes every time you save, Mercurial will have to
   1.108 +      store all 2MB of the file every time you commit, even though
   1.109 +      from your perspective, perhaps only a few words are changing
   1.110 +      each time.  A single frequently-edited file that is not friendly
   1.111 +      to Mercurial's storage assumptions can easily have an outsized
   1.112 +      effect on the size of the repository.</para>
   1.113 +
   1.114 +    <para>Even worse, if both you and someone else edit the OpenOffice
   1.115 +      document you're working on, there is no useful way to merge your
   1.116 +      work. In fact, there isn't even a good way to tell what the
   1.117 +      differences are between your respective changes.</para>
   1.118 +
   1.119 +    <para>There are thus a few clear recommendations about specific
   1.120 +      kinds of files to be very careful with.</para>
   1.121 +
   1.122 +    <itemizedlist>
   1.123 +      <listitem>
   1.124 +	<para>Files that are very large and incompressible, e.g. ISO
   1.125 +	  CD-ROM images, will by virtue of sheer size make clones over
   1.126 +	  a network very slow.</para>
   1.127 +      </listitem>
   1.128 +      <listitem>
   1.129 +	<para>Files that change a lot from one revision to the next
   1.130 +	  may be expensive to store if you edit them frequently, and
   1.131 +	  conflicts due to concurrent edits may be difficult to
   1.132 +	  resolve.</para>
   1.133 +      </listitem>
   1.134 +    </itemizedlist>
   1.135 +  </sect1>
   1.136 +
   1.137 +  <sect1>
   1.138 +    <title>Backups and mirroring</title>
   1.139 +
   1.140 +    <para>Since Mercurial maintains a complete copy of history in each
   1.141 +      clone, everyone who uses Mercurial to collaborate on a project
   1.142 +      can potentially act as a source of backups in the event of a
   1.143 +      catastrophe.  If a central repository becomes unavailable, you
   1.144 +      can construct a replacement simply by cloning a copy of the
   1.145 +      repository from one contributor, and pulling any changes they
   1.146 +      may not have seen from others.</para>
   1.147 +
   1.148 +    <para>It is simple to use Mercurial to perform off-site backups
   1.149 +      and remote mirrors.  Set up a periodic job (e.g. via the
   1.150 +      <command>cron</command> command) on a remote server to pull
   1.151 +      changes from your master repositories every hour.  This will
   1.152 +      only be tricky in the unlikely case that the number of master
   1.153 +      repositories you maintain changes frequently, in which case
   1.154 +      you'll need to do a little scripting to refresh the list of
   1.155 +      repositories to back up.</para>
   1.156 +
   1.157 +    <para>If you perform traditional backups of your master
   1.158 +      repositories to tape or disk, and you want to back up a
   1.159 +      repository named <filename>myrepo</filename>.  Use <command>hg
   1.160 +	clone -U myrepo myrepo.bak</command> to create a
   1.161 +      clone of <filename>myrepo</filename> before you start your
   1.162 +      backups.  The <option>-U</option> option doesn't check out a
   1.163 +      working directory after the clone completes, since that would be
   1.164 +      superfluous and make the backup take longer.
   1.165 +
   1.166 +    <para>If you then back up <filename>myrepo.bak</filename> instead
   1.167 +      of <filename>myrepo</filename>, you will be guaranteed to have a
   1.168 +      consistent snapshot of your repository that won't be pushed to
   1.169 +      by an insomniac developer in mid-backup.</para>
   1.170 +  </sect1>
   1.171  </chapter>
   1.172  
   1.173  <!--

     2.1 --- a/en/ch08-undo.xml	Thu Apr 23 22:24:02 2009 -0700
     2.2 +++ b/en/ch08-undo.xml	Fri Apr 24 00:27:05 2009 -0700
     2.3 @@ -821,7 +821,7 @@
     2.4      <para id="x_127">The idea behind the <command role="hg-cmd">hg
     2.5  	bisect</command> command is that a changeset has introduced
     2.6        some change of behavior that you can identify with a simple
     2.7 -      binary test.  You don't know which piece of code introduced the
     2.8 +      pass/fail test.  You don't know which piece of code introduced the
     2.9        change, but you know how to test for the presence of the bug.
    2.10        The <command role="hg-cmd">hg bisect</command> command uses your
    2.11        test to direct its search for the changeset that introduced the

     3.1 --- a/en/ch11-mq.xml	Thu Apr 23 22:24:02 2009 -0700
     3.2 +++ b/en/ch11-mq.xml	Fri Apr 24 00:27:05 2009 -0700
     3.3 @@ -793,13 +793,14 @@
     3.4    <sect1 id="sec:mq:perf">
     3.5      <title>Getting the best performance out of MQ</title>
     3.6  
     3.7 -    <para id="x_403">MQ is very efficient at handling a large number of patches.
     3.8 -      I ran some performance experiments in mid-2006 for a talk that I
     3.9 -      gave at the 2006 EuroPython conference.  I used as my data set the
    3.10 -      Linux 2.6.17-mm1 patch series, which consists of 1,738 patches.
    3.11 -      I applied these on top of a Linux kernel repository containing
    3.12 -      all 27,472 revisions between Linux 2.6.12-rc2 and Linux
    3.13 -      2.6.17.</para>
    3.14 +    <para id="x_403">MQ is very efficient at handling a large number
    3.15 +      of patches. I ran some performance experiments in mid-2006 for a
    3.16 +      talk that I gave at the 2006 EuroPython conference (on modern
    3.17 +      hardware, you should expect better performance than you'll see
    3.18 +      below).  I used as my data set the Linux 2.6.17-mm1 patch
    3.19 +      series, which consists of 1,738 patches. I applied these on top
    3.20 +      of a Linux kernel repository containing all 27,472 revisions
    3.21 +      between Linux 2.6.12-rc2 and Linux 2.6.17.</para>
    3.22  
    3.23      <para id="x_404">On my old, slow laptop, I was able to <command
    3.24  	role="hg-cmd">hg qpush <option

     4.1 --- a/en/examples/auto-snippets.xml	Thu Apr 23 22:24:02 2009 -0700
     4.2 +++ b/en/examples/auto-snippets.xml	Fri Apr 24 00:27:05 2009 -0700
     4.3 @@ -51,6 +51,11 @@
     4.4  <!ENTITY interaction.branching.stable SYSTEM "results/branching.stable.lxo">
     4.5  <!ENTITY interaction.branching.tag SYSTEM "results/branching.tag.lxo">
     4.6  <!ENTITY interaction.branching.update SYSTEM "results/branching.update.lxo">
     4.7 +<!ENTITY interaction.ch04-diff.chmod SYSTEM "results/ch04-diff.chmod.lxo">
     4.8 +<!ENTITY interaction.ch04-diff.chmod.git SYSTEM "results/ch04-diff.chmod.git.lxo">
     4.9 +<!ENTITY interaction.ch04-diff.rename.basic SYSTEM "results/ch04-diff.rename.basic.lxo">
    4.10 +<!ENTITY interaction.ch04-diff.rename.git SYSTEM "results/ch04-diff.rename.git.lxo">
    4.11 +<!ENTITY interaction.ch04-rename.basic SYSTEM "results/ch04-rename.basic.lxo">
    4.12  <!ENTITY interaction.ch04-resolve.cifail SYSTEM "results/ch04-resolve.cifail.lxo">
    4.13  <!ENTITY interaction.ch04-resolve.export SYSTEM "results/ch04-resolve.export.lxo">
    4.14  <!ENTITY interaction.ch04-resolve.heads SYSTEM "results/ch04-resolve.heads.lxo">

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/examples/ch04/diff	Fri Apr 24 00:27:05 2009 -0700
     5.3 @@ -0,0 +1,30 @@
     5.4 +#!/bin/bash
     5.5 +
     5.6 +hg init a
     5.7 +cd a
     5.8 +echo a > a
     5.9 +hg ci -Ama
    5.10 +
    5.11 +#$ name: rename.basic
    5.12 +
    5.13 +hg rename a b
    5.14 +hg diff
    5.15 +
    5.16 +#$ name: rename.git
    5.17 +
    5.18 +hg diff -g
    5.19 +
    5.20 +#$ name:
    5.21 +
    5.22 +hg revert -a
    5.23 +rm b
    5.24 +
    5.25 +#$ name: chmod
    5.26 +
    5.27 +chmod +x a
    5.28 +hg st
    5.29 +hg diff
    5.30 +
    5.31 +#$ name: chmod.git
    5.32 +
    5.33 +hg diff -g

     6.1 --- a/web/index.html.in	Thu Apr 23 22:24:02 2009 -0700
     6.2 +++ b/web/index.html.in	Fri Apr 24 00:27:05 2009 -0700
     6.3 @@ -19,10 +19,14 @@
     6.4  
     6.5    <h2>You can contribute!</h2>
     6.6  
     6.7 -  <p>I publish the <a href="http://hgbook.red-bean.com/">source
     6.8 -      code</a> for this book as a Mercurial repository.  Please feel
     6.9 +  <p>I publish the source code for this book
    6.10 +    as <a href="http://hg.serpentine.com/mercurial/book">a
    6.11 +      Mercurial repository</a>.  Please feel
    6.12      welcome to clone it, make modifications to your copy, and send me
    6.13 -    changes.</p>
    6.14 +    changes.  Getting a copy of the source takes just a few seconds if
    6.15 +    you have Mercurial installed:</p>
    6.16 +
    6.17 +  <pre class="screen">hg clone http://hg.serpentine.com/mercurial/book</pre>
    6.18  
    6.19    <p>The online version of the book includes a comment system
    6.20      that you can use to send feedback involving errors, omissions, and