Mercurial > hgbook
diff en/ch04-daily.xml @ 810:1a0a78e197c3
Incorporate feedback from Greg Lindahl.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Fri, 24 Apr 2009 00:27:05 -0700 |
parents | 29f0f79cf614 |
children | a66f6d499afa |
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 iid="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> <!--