comparison en/ch04-daily.xml @ 810:1a0a78e197c3

Incorporate feedback from Greg Lindahl.

809:ef53d025f410

<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->

<chapter id="chap:daily">
  <?dbhtml filename="mercurial-in-daily-use.html"?>
  <title>Mercurial in daily use</title>

  <sect1>
    <title>Telling Mercurial which files to track</title>

	  role="hg-opt-resolve">--unmark</option> option.  This allows
	us to clean up a particularly messy merge by hand, and to keep
	track of our progress with each file as we go.</para>
    </sect2>
  </sect1>
</chapter>

<!--
local variables: 
sgml-parent-document: ("00book.xml" "book" "chapter")

810:1a0a78e197c3

<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->

<chapter &#105;id="chap:daily">
  <?dbhtml filename="mercurial-in-daily-use.html"?>
  <title>Mercurial in daily use</title>

  <sect1>
    <title>Telling Mercurial which files to track</title>

	  role="hg-opt-resolve">--unmark</option> option.  This allows
	us to clean up a particularly messy merge by hand, and to keep
	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>

<!--
local variables: 
sgml-parent-document: ("00book.xml" "book" "chapter")