Mercurial > hgbook

changeset 810:1a0a78e197c3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Incorporate feedback from Greg Lindahl.
author Bryan O'Sullivan <bos@serpentine.com>
date Fri, 24 Apr 2009 00:27:05 -0700
parents ef53d025f410
children a66f6d499afa
files en/ch04-daily.xml en/ch08-undo.xml en/ch11-mq.xml en/examples/auto-snippets.xml en/examples/ch04/diff web/index.html.in
diffstat 6 files changed, 208 insertions(+), 12 deletions(-) [+]
line wrap: on
line diff
--- a/en/ch04-daily.xml	Thu Apr 23 22:24:02 2009 -0700
+++ b/en/ch04-daily.xml	Fri Apr 24 00:27:05 2009 -0700
@@ -1,6 +1,6 @@
 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
 
-<chapter id="chap:daily">
+<chapter &#105;id="chap:daily">
   <?dbhtml filename="mercurial-in-daily-use.html"?>
   <title>Mercurial in daily use</title>
 
@@ -673,6 +673,162 @@
 	track of our progress with each file as we go.</para>
     </sect2>
   </sect1>
+
+  <sect1>
+    <title>More useful diffs</title>
+
+    <para>The default output of the <command role="hg-cmd">hg
+	diff</command> command is backwards compatible with the
+      regular <command>diff</command> command, but this has some
+      drawbacks.</para>
+
+    <para>Consider the case where we use <command role="hg-cmd">hg
+	rename</command> to rename a file.</para>
+
+    &interaction.ch04-diff.rename.basic;
+
+    <para>The output of <command role="hg-cmd">hg diff</command> above
+      obscures the fact that we simply renamed a file.  The <command
+	role="hg-cmd">hg diff</command> command accepts an option,
+      <option>--git</option> or <option>-g</option>, to use a newer
+      diff format that displays such information in a more readable
+      form.</para>
+
+    &interaction.ch04-diff.rename.git;
+
+    <para>This option also helps with a case that can otherwise be
+      confusing: a file that appears to be modified according to
+      <command role="hg-cmd">hg status</command>, but for which
+      <command role="hg-cmd">hg diff</command> prints nothing. This
+      situation can arise if we change the file's execute
+      permissions.</para>
+
+    &interaction.ch04-diff.chmod;
+
+    <para>The normal <command>diff</command> command pays no attention
+      to file permissions, which is why <command role="hg-cmd">hg
+	diff</command> prints nothing by default.  If we supply it
+      with the <option>-g</option> option, it tells us what really
+      happened.</para>
+
+    &interaction.ch04-diff.chmod.git;
+  </sect1>
+
+  <sect1>
+    <title>Which files to manage, and which to avoid</title>
+
+    <para>Revision control systems are generally best at managing text
+      files that are written by humans, such as source code, where the
+      files do not change much from one revision to the next.  Some
+      centralized revision control systems can also deal tolerably
+      well with binary files, such as bitmap images.</para>
+
+    <para>For instance, a game development team will typically manage
+      both its source code and all of its binary assets (e.g. geometry
+      data, textures, map layouts) in a revision control
+      system.</para>
+
+    <para>Because it is usually impossible to merge two conflicting
+      modifications to a binary file, centralized systems often
+      provide a file locking mechanism that allow a user to say
+      <quote>I am the only person who can edit this
+	file</quote>.</para>
+
+    <para>Compared to a centralized system, a distributed revision
+      control system changes some of the factors that guide decisions
+      over which files to manage and how.</para>
+
+    <para>For instance, a distributed revision control system cannot,
+      by its nature, offer a file locking facility.  There is thus no
+      built-in mechanism to prevent two people from making conflicting
+      changes to a binary file.  If you have a team where several
+      people may be editing binary files frequently, it may not be a
+      good idea to use Mercurial&emdash;or any other distributed
+      revision control system&emdash;to manage those files.</para>
+
+    <para>When storing modifications to a file, Mercurial usually
+      saves only the differences between the previous and current
+      versions of the file.  For most text files, this is extremely
+      efficient. However, some files (particularly binary files) are
+      laid out in such a way that even a small change to a file's
+      logical content results in many or most of the bytes inside the
+      file changing.  For instance, compressed files are particularly
+      susceptible to this. If the differences between each successive
+      version of a file are always large, Mercurial will not be able
+      to store the file's revision history very efficiently.  This can
+      affect both local storage needs and the amount of time it takes
+      to clone a repository.</para>
+
+    <para>To get an idea of how this could affect you in practice,
+      suppose you want to use Mercurial to manage an OpenOffice
+      document.  OpenOffice stores documents on disk as compressed zip
+      files. Edit even a single letter of your document in OpenOffice,
+      and almost every byte in the entire file will change when you
+      save it. Now suppose that file is 2MB in size.  Because most of
+      the file changes every time you save, Mercurial will have to
+      store all 2MB of the file every time you commit, even though
+      from your perspective, perhaps only a few words are changing
+      each time.  A single frequently-edited file that is not friendly
+      to Mercurial's storage assumptions can easily have an outsized
+      effect on the size of the repository.</para>
+
+    <para>Even worse, if both you and someone else edit the OpenOffice
+      document you're working on, there is no useful way to merge your
+      work. In fact, there isn't even a good way to tell what the
+      differences are between your respective changes.</para>
+
+    <para>There are thus a few clear recommendations about specific
+      kinds of files to be very careful with.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Files that are very large and incompressible, e.g. ISO
+	  CD-ROM images, will by virtue of sheer size make clones over
+	  a network very slow.</para>
+      </listitem>
+      <listitem>
+	<para>Files that change a lot from one revision to the next
+	  may be expensive to store if you edit them frequently, and
+	  conflicts due to concurrent edits may be difficult to
+	  resolve.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>Backups and mirroring</title>
+
+    <para>Since Mercurial maintains a complete copy of history in each
+      clone, everyone who uses Mercurial to collaborate on a project
+      can potentially act as a source of backups in the event of a
+      catastrophe.  If a central repository becomes unavailable, you
+      can construct a replacement simply by cloning a copy of the
+      repository from one contributor, and pulling any changes they
+      may not have seen from others.</para>
+
+    <para>It is simple to use Mercurial to perform off-site backups
+      and remote mirrors.  Set up a periodic job (e.g. via the
+      <command>cron</command> command) on a remote server to pull
+      changes from your master repositories every hour.  This will
+      only be tricky in the unlikely case that the number of master
+      repositories you maintain changes frequently, in which case
+      you'll need to do a little scripting to refresh the list of
+      repositories to back up.</para>
+
+    <para>If you perform traditional backups of your master
+      repositories to tape or disk, and you want to back up a
+      repository named <filename>myrepo</filename>.  Use <command>hg
+	clone -U myrepo myrepo.bak</command> to create a
+      clone of <filename>myrepo</filename> before you start your
+      backups.  The <option>-U</option> option doesn't check out a
+      working directory after the clone completes, since that would be
+      superfluous and make the backup take longer.
+
+    <para>If you then back up <filename>myrepo.bak</filename> instead
+      of <filename>myrepo</filename>, you will be guaranteed to have a
+      consistent snapshot of your repository that won't be pushed to
+      by an insomniac developer in mid-backup.</para>
+  </sect1>
 </chapter>
 
 <!--
--- a/en/ch08-undo.xml	Thu Apr 23 22:24:02 2009 -0700
+++ b/en/ch08-undo.xml	Fri Apr 24 00:27:05 2009 -0700
@@ -821,7 +821,7 @@
     <para id="x_127">The idea behind the <command role="hg-cmd">hg
 	bisect</command> command is that a changeset has introduced
       some change of behavior that you can identify with a simple
-      binary test.  You don't know which piece of code introduced the
+      pass/fail test.  You don't know which piece of code introduced the
       change, but you know how to test for the presence of the bug.
       The <command role="hg-cmd">hg bisect</command> command uses your
       test to direct its search for the changeset that introduced the
--- a/en/ch11-mq.xml	Thu Apr 23 22:24:02 2009 -0700
+++ b/en/ch11-mq.xml	Fri Apr 24 00:27:05 2009 -0700
@@ -793,13 +793,14 @@
   <sect1 id="sec:mq:perf">
     <title>Getting the best performance out of MQ</title>
 
-    <para id="x_403">MQ is very efficient at handling a large number of patches.
-      I ran some performance experiments in mid-2006 for a talk that I
-      gave at the 2006 EuroPython conference.  I used as my data set the
-      Linux 2.6.17-mm1 patch series, which consists of 1,738 patches.
-      I applied these on top of a Linux kernel repository containing
-      all 27,472 revisions between Linux 2.6.12-rc2 and Linux
-      2.6.17.</para>
+    <para id="x_403">MQ is very efficient at handling a large number
+      of patches. I ran some performance experiments in mid-2006 for a
+      talk that I gave at the 2006 EuroPython conference (on modern
+      hardware, you should expect better performance than you'll see
+      below).  I used as my data set the Linux 2.6.17-mm1 patch
+      series, which consists of 1,738 patches. I applied these on top
+      of a Linux kernel repository containing all 27,472 revisions
+      between Linux 2.6.12-rc2 and Linux 2.6.17.</para>
 
     <para id="x_404">On my old, slow laptop, I was able to <command
 	role="hg-cmd">hg qpush <option
--- a/en/examples/auto-snippets.xml	Thu Apr 23 22:24:02 2009 -0700
+++ b/en/examples/auto-snippets.xml	Fri Apr 24 00:27:05 2009 -0700
@@ -51,6 +51,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.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">
+<!ENTITY interaction.ch04-diff.rename.git SYSTEM "results/ch04-diff.rename.git.lxo">
+<!ENTITY interaction.ch04-rename.basic SYSTEM "results/ch04-rename.basic.lxo">
 <!ENTITY interaction.ch04-resolve.cifail SYSTEM "results/ch04-resolve.cifail.lxo">
 <!ENTITY interaction.ch04-resolve.export SYSTEM "results/ch04-resolve.export.lxo">
 <!ENTITY interaction.ch04-resolve.heads SYSTEM "results/ch04-resolve.heads.lxo">
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/ch04/diff	Fri Apr 24 00:27:05 2009 -0700
@@ -0,0 +1,30 @@
+#!/bin/bash
+
+hg init a
+cd a
+echo a > a
+hg ci -Ama
+
+#$ name: rename.basic
+
+hg rename a b
+hg diff
+
+#$ name: rename.git
+
+hg diff -g
+
+#$ name:
+
+hg revert -a
+rm b
+
+#$ name: chmod
+
+chmod +x a
+hg st
+hg diff
+
+#$ name: chmod.git
+
+hg diff -g
--- a/web/index.html.in	Thu Apr 23 22:24:02 2009 -0700
+++ b/web/index.html.in	Fri Apr 24 00:27:05 2009 -0700
@@ -19,10 +19,14 @@
 
   <h2>You can contribute!</h2>
 
-  <p>I publish the <a href="http://hgbook.red-bean.com/">source
-      code</a> for this book as a Mercurial repository.  Please feel
+  <p>I publish the source code for this book
+    as <a href="http://hg.serpentine.com/mercurial/book">a
+      Mercurial repository</a>.  Please feel
     welcome to clone it, make modifications to your copy, and send me
-    changes.</p>
+    changes.  Getting a copy of the source takes just a few seconds if
+    you have Mercurial installed:</p>
+
+  <pre class="screen">hg clone http://hg.serpentine.com/mercurial/book</pre>
 
   <p>The online version of the book includes a comment system
     that you can use to send feedback involving errors, omissions, and