# HG changeset patch # User Bryan O'Sullivan # Date 1237522732 25200 # Node ID c838b3975bc6700f0671ba73940e6cc5f11c606f # Parent 28b5a5befb08db24ff12b7099a3f459c6c0c4766 Add IDs to paragraphs. diff -r 28b5a5befb08 -r c838b3975bc6 en/appA-cmdref.xml --- a/en/appA-cmdref.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/appA-cmdref.xml Thu Mar 19 21:18:52 2009 -0700 @@ -3,113 +3,113 @@ Command reference -\cmdref{add}{add files at the next commit} +\cmdref{add}{add files at the next commit} \optref{add}{I}{include} \optref{add}{X}{exclude} \optref{add}{n}{dry-run} -\cmdref{diff}{print changes in history or working directory} +\cmdref{diff}{print changes in history or working directory} -Show differences between revisions for the specified files or +Show differences between revisions for the specified files or directories, using the unified diff format. For a description of the unified diff format, see section . -By default, this command does not print diffs for files that Mercurial +By default, this command does not print diffs for files that Mercurial considers to contain binary data. To control this behaviour, see the and options. Options -\loptref{diff}{nodates} +\loptref{diff}{nodates} -Omit date and time information when printing diff headers. +Omit date and time information when printing diff headers. -\optref{diff}{B}{ignore-blank-lines} +\optref{diff}{B}{ignore-blank-lines} -Do not print changes that only insert or delete blank lines. A line +Do not print changes that only insert or delete blank lines. A line that contains only whitespace is not considered blank. -\optref{diff}{I}{include} +\optref{diff}{I}{include} -Include files and directories whose names match the given patterns. +Include files and directories whose names match the given patterns. -\optref{diff}{X}{exclude} +\optref{diff}{X}{exclude} -Exclude files and directories whose names match the given patterns. +Exclude files and directories whose names match the given patterns. -\optref{diff}{a}{text} +\optref{diff}{a}{text} -If this option is not specified, hg diff will refuse to print +If this option is not specified, hg diff will refuse to print diffs for files that it detects as binary. Specifying forces hg diff to treat all files as text, and generate diffs for all of them. -This option is useful for files that are mostly text but have a +This option is useful for files that are mostly text but have a few embedded NUL characters. If you use it on files that contain a lot of binary data, its output will be incomprehensible. -\optref{diff}{b}{ignore-space-change} +\optref{diff}{b}{ignore-space-change} -Do not print a line if the only change to that line is in the amount +Do not print a line if the only change to that line is in the amount of white space it contains. -\optref{diff}{g}{git} +\optref{diff}{g}{git} -Print git-compatible diffs. XXX reference a format +Print git-compatible diffs. XXX reference a format description. -\optref{diff}{p}{show-function} +\optref{diff}{p}{show-function} -Display the name of the enclosing function in a hunk header, using a +Display the name of the enclosing function in a hunk header, using a simple heuristic. This functionality is enabled by default, so the option has no effect unless you change the value of the showfunc config item, as in the following example. -\optref{diff}{r}{rev} +\optref{diff}{r}{rev} -Specify one or more revisions to compare. The hg diff command +Specify one or more revisions to compare. The hg diff command accepts up to two options to specify the revisions to compare. -Display the differences between the parent revision of the +Display the differences between the parent revision of the working directory and the working directory. -Display the differences between the specified changeset and the +Display the differences between the specified changeset and the working directory. -Display the differences between the two specified changesets. +Display the differences between the two specified changesets. -You can specify two revisions using either two +You can specify two revisions using either two options or revision range notation. For example, the two revision specifications below are equivalent. hg diff -r 10 -r 20 hg diff -r10:20 -When you provide two revisions, Mercurial treats the order of those +When you provide two revisions, Mercurial treats the order of those revisions as significant. Thus, hg diff -r10:20 will produce a diff that will transform files from their contents as of revision 10 to their contents as of revision 20, while @@ -119,23 +119,23 @@ diffing against the working directory. -\optref{diff}{w}{ignore-all-space} +\optref{diff}{w}{ignore-all-space} -\cmdref{version}{print version and copyright information} +\cmdref{version}{print version and copyright information} -This command displays the version of Mercurial you are running, and +This command displays the version of Mercurial you are running, and its copyright license. There are four kinds of version string that you may see. -The string unknown. This version of Mercurial was +The string unknown. This version of Mercurial was not built in a Mercurial repository, and cannot determine its own version. -A short numeric string, such as 1.1. This is a +A short numeric string, such as 1.1. This is a build of a revision of Mercurial that was identified by a specific tag in the repository where it was built. (This doesn't necessarily mean that you're running an official release; someone else could @@ -143,11 +143,11 @@ built Mercurial.) -A hexadecimal string, such as 875489e31abe. This +A hexadecimal string, such as 875489e31abe. This is a build of the given revision of Mercurial. -A hexadecimal string followed by a date, such as +A hexadecimal string followed by a date, such as 875489e31abe+20070205. This is a build of the given revision of Mercurial, where the build repository contained some local changes that had not been committed. @@ -161,14 +161,14 @@ Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ? -When you run the hg status command, you'll see a list of files +When you run the hg status command, you'll see a list of files that Mercurial will record changes for the next time you perform a commit. If you run the hg diff command, you may notice that it prints diffs for only a subset of the files that hg status listed. There are two possible reasons for this. -The first is that hg status prints some kinds of modifications +The first is that hg status prints some kinds of modifications that hg diff doesn't normally display. The hg diff command normally outputs unified diffs, which don't have the ability to represent some changes that Mercurial can track. Most notably, @@ -176,12 +176,12 @@ executable, but Mercurial records this information. -If you use the option to hg diff, it will +If you use the option to hg diff, it will display git-compatible diffs that can display this extra information. -The second possible reason that hg diff might be printing diffs +The second possible reason that hg diff might be printing diffs for a subset of the files displayed by hg status is that if you invoke it without any arguments, hg diff prints diffs against the first parent of the working directory. If you have run hg merge @@ -199,14 +199,14 @@ Generating safe binary diffs -If you use the option to force Mercurial to print +If you use the option to force Mercurial to print diffs of files that are either mostly text or contain lots of binary data, those diffs cannot subsequently be applied by either Mercurial's hg import command or the system's patch command. -If you want to generate a diff of a binary file that is safe to use as +If you want to generate a diff of a binary file that is safe to use as input for hg import, use the hg diff{--git} option when you generate the patch. The system patch command cannot handle binary patches at all. diff -r 28b5a5befb08 -r c838b3975bc6 en/appB-mq-ref.xml --- a/en/appB-mq-ref.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/appB-mq-ref.xml Thu Mar 19 21:18:52 2009 -0700 @@ -7,14 +7,14 @@ MQ command reference - For an overview of the commands provided by MQ, use the + For an overview of the commands provided by MQ, use the command hg help mq. <command role="hg-ext-mq">qapplied</command>&emdash;print applied patches - The qapplied command + The qapplied command prints the current stack of applied patches. Patches are printed in oldest-to-newest order, so the last patch in the list is the top patch. @@ -24,7 +24,7 @@ <command role="hg-ext-mq">qcommit</command>&emdash;commit changes in the queue repository - The qcommit command + The qcommit command commits any outstanding changes in the .hg/patches repository. This command only works if the qinit. - This command is shorthand for hg + This command is shorthand for hg commit --cwd .hg/patches. @@ -45,7 +45,7 @@ from the series file} - The qdelete command + The qdelete command removes the entry for a patch from the series file in the .hg/patches @@ -54,9 +54,9 @@ the option to do that. - Options: + Options: - @@ -66,7 +66,7 @@ <command role="hg-ext-mq">qdiff</command>&emdash;print a diff of the topmost applied patch - The qdiff command + The qdiff command prints a diff of the topmost applied patch. It is equivalent to hg diff -r-2:-1. @@ -75,12 +75,12 @@ <command role="hg-ext-mq">qfold</command>&emdash;merge (<quote>fold</quote>) several patches into one - The qfold command + The qfold command merges multiple patches into the topmost applied patch, so that the topmost applied patch makes the union of all of the changes in the patches in question. - The patches to fold must not be applied; The patches to fold must not be applied; qfold will exit with an error if any is. The order in which patches are folded is significant; hg qfold a b means @@ -88,7 +88,7 @@ a, followed by b. - The comments from the folded patches are appended to the + The comments from the folded patches are appended to the comments of the destination patch, with each block of comments separated by three asterisk (*) characters. Use the @@ -96,19 +96,19 @@ edit the commit message for the combined patch/changeset after the folding has completed. - Options: + Options: - - - <command role="hg-ext-mq">qsave</command>&emdash;save current queue state - XXX Likewise. + XXX Likewise. <command role="hg-ext-mq">qseries</command>&emdash;print the entire patch series - The qseries command + The qseries command prints the entire patch series from the series file. It prints only patch names, not empty lines or comments. It prints in order from @@ -464,7 +464,7 @@ <command role="hg-ext-mq">qtop</command>&emdash;print the name of the current patch - The qtop prints the + The qtop prints the name of the topmost currently applied patch. @@ -473,7 +473,7 @@ role="hg-ext-mq">qunapplied&emdash;print patches not yet applied - The qunapplied command + The qunapplied command prints the names of patches from the series file that are not yet applied. It prints them in order from the next patch that @@ -484,28 +484,28 @@ <command role="hg-cmd">hg strip</command>&emdash;remove a revision and descendants - The hg strip command + The hg strip command removes a revision, and all of its descendants, from the repository. It undoes the effects of the removed revisions from the repository, and updates the working directory to the first parent of the removed revision. - The hg strip command + The hg strip command saves a backup of the removed changesets in a bundle, so that they can be reapplied if removed in error. - Options: + Options: - : Save + : Save unrelated changesets that are intermixed with the stripped changesets in the backup bundle. - : If a + : If a branch has multiple heads, remove all heads. XXX This should be renamed, and use -f to strip revs when there are pending changes. - : Do + : Do not save a backup bundle. @@ -518,18 +518,18 @@ The <filename role="special">series</filename> file - The series file + The series file contains a list of the names of all patches that MQ can apply. It is represented as a list of names, with one name saved per line. Leading and trailing white space in each line are ignored. - Lines may contain comments. A comment begins with the + Lines may contain comments. A comment begins with the # character, and extends to the end of the line. Empty lines, and lines that contain only comments, are ignored. - You will often need to edit the You will often need to edit the series file by hand, hence the support for comments and empty lines noted above. For example, you can comment out a patch temporarily, and series file. - Placing the series + Placing the series file under revision control is also supported; it is a good idea to place all of the patches that it refers to under revision control, as well. If you create a patch directory @@ -551,7 +551,7 @@ The <filename role="special">status</filename> file - The status file + The status file contains the names and changeset hashes of all patches that MQ currently has applied. Unlike the series file, this file is not diff -r 28b5a5befb08 -r c838b3975bc6 en/appC-srcinstall.xml --- a/en/appC-srcinstall.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/appC-srcinstall.xml Thu Mar 19 21:18:52 2009 -0700 @@ -7,29 +7,29 @@ On a Unix-like system - If you are using a Unix-like system that has a sufficiently + If you are using a Unix-like system that has a sufficiently recent version of Python (2.3 or newer) available, it is easy to install Mercurial from source. - Download a recent source tarball from Download a recent source tarball from http://www.selenic.com/mercurial/download. - Unpack the tarball: + Unpack the tarball: gzip -dc mercurial-MYVERSION.tar.gz | tar xf - - Go into the source directory and run the + Go into the source directory and run the installer script. This will build Mercurial and install it in your home directory. cd mercurial-MYVERSION python setup.py install --force --home=$HOME - Once the install finishes, Mercurial will be in the + Once the install finishes, Mercurial will be in the bin subdirectory of your home directory. Don't forget to make sure that this directory is present in your shell's search path. - You will probably need to set the PYTHONPATH + You will probably need to set the PYTHONPATH environment variable so that the Mercurial executable can find the rest of the Mercurial packages. For example, on my laptop, I have set it to /home/bos/lib/python. The @@ -43,14 +43,14 @@ On Windows - Building and installing Mercurial on Windows requires a + Building and installing Mercurial on Windows requires a variety of tools, a fair amount of technical knowledge, and considerable patience. I very much do not recommend this route if you are a casual user. Unless you intend to hack on Mercurial, I strongly suggest that you use a binary package instead. - If you are intent on building Mercurial from source on + If you are intent on building Mercurial from source on Windows, follow the hard way directions on the Mercurial wiki at http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall, diff -r 28b5a5befb08 -r c838b3975bc6 en/appD-license.xml --- a/en/appD-license.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/appD-license.xml Thu Mar 19 21:18:52 2009 -0700 @@ -4,24 +4,24 @@ Open Publication License - Version 1.0, 8 June 1999 + Version 1.0, 8 June 1999 Requirements on both unmodified and modified versions - The Open Publication works may be reproduced and distributed + The Open Publication works may be reproduced and distributed in whole or in part, in any medium physical or electronic, provided that the terms of this license are adhered to, and that this license or an incorporation of it by reference (with any options elected by the author(s) and/or publisher) is displayed in the reproduction. - Proper form for an incorporation by reference is as + Proper form for an incorporation by reference is as follows:
- Copyright (c) year by + Copyright (c) year by author's name or designee. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, @@ -30,14 +30,14 @@ url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/).
- The reference must be immediately followed with any options + The reference must be immediately followed with any options elected by the author(s) and/or publisher of the document (see section ). - Commercial redistribution of Open Publication-licensed + Commercial redistribution of Open Publication-licensed material is permitted. - Any publication in standard (paper) book form shall require + Any publication in standard (paper) book form shall require the citation of the original publisher and author. The publisher and author's names shall appear on all outer surfaces of the book. On all outer surfaces of the book the original publisher's @@ -48,30 +48,30 @@ Copyright - The copyright to each Open Publication is owned by its + The copyright to each Open Publication is owned by its author(s) or designee. Scope of license - The following license terms apply to all Open Publication + The following license terms apply to all Open Publication works, unless otherwise explicitly stated in the document. - Mere aggregation of Open Publication works or a portion of + Mere aggregation of Open Publication works or a portion of an Open Publication work with other works or programs on the same media shall not cause this license to apply to those other works. The aggregate work shall contain a notice specifying the inclusion of the Open Publication material and appropriate copyright notice. - Severability. If any part + Severability. If any part of this license is found to be unenforceable in any jurisdiction, the remaining portions of the license remain in force. - No warranty. Open + No warranty. Open Publication works are licensed and provided as is without warranty of any kind, express or implied, including, but not limited to, the implied warranties of merchantability and @@ -82,25 +82,25 @@ Requirements on modified works - All modified versions of documents covered by this license, + All modified versions of documents covered by this license, including translations, anthologies, compilations and partial documents, must meet the following requirements: - The modified version must be labeled as + The modified version must be labeled as such. - The person making the modifications must be + The person making the modifications must be identified and the modifications dated. - Acknowledgement of the original author and + Acknowledgement of the original author and publisher if applicable must be retained according to normal academic citation practices. - The location of the original unmodified document + The location of the original unmodified document must be identified. - The original author's (or authors') name(s) may + The original author's (or authors') name(s) may not be used to assert or imply endorsement of the resulting document without the original author's (or authors') permission. @@ -110,23 +110,23 @@ Good-practice recommendations - In addition to the requirements of this license, it is + In addition to the requirements of this license, it is requested from and strongly recommended of redistributors that: - If you are distributing Open Publication works + If you are distributing Open Publication works on hardcopy or CD-ROM, you provide email notification to the authors of your intent to redistribute at least thirty days before your manuscript or media freeze, to give the authors time to provide updated documents. This notification should describe modifications, if any, made to the document. - All substantive modifications (including + All substantive modifications (including deletions) be either clearly marked up in the document or else described in an attachment to the document. - Finally, while it is not mandatory under this + Finally, while it is not mandatory under this license, it is considered good form to offer a free copy of any hardcopy and CD-ROM expression of an Open Publication-licensed work to its author(s). @@ -136,7 +136,7 @@ License options - The author(s) and/or publisher of an Open + The author(s) and/or publisher of an Open Publication-licensed document may elect certain options by appending language to the reference to or copy of the license. These options are considered part of the license instance and @@ -144,25 +144,25 @@ reference) in derived works. - To prohibit distribution of substantively + To prohibit distribution of substantively modified versions without the explicit permission of the author(s). Substantive modification is defined as a change to the semantic content of the document, and excludes mere changes in format or typographical corrections. - To accomplish this, add the phrase + To accomplish this, add the phrase Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. to the license reference or copy. - To prohibit any publication of this work or + To prohibit any publication of this work or derivative works in whole or in part in standard (paper) book form for commercial purposes is prohibited unless prior permission is obtained from the copyright holder. - To accomplish this, add the phrase + To accomplish this, add the phrase Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder. diff -r 28b5a5befb08 -r c838b3975bc6 en/autoid.py --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/en/autoid.py Thu Mar 19 21:18:52 2009 -0700 @@ -0,0 +1,47 @@ +#!/usr/bin/env python +# +# Add unique ID attributes to para tags. This script should only be +# run by one person, since otherwise it introduces the possibility of +# chaotic conflicts among tags. + +import glob, os, re, sys + +tagged = re.compile(']* id="x_([0-9a-f]+)"[^>]*>', re.M) +untagged = re.compile('') + +names = glob.glob('ch*.xml') + glob.glob('app*.xml') + +# First pass: find the highest-numbered paragraph ID. + +biggest_id = 0 +seen = set() +errs = 0 + +for name in names: + for m in tagged.finditer(open(name).read()): + i = int(m.group(1),16) + if i in seen: + print >> sys.stderr, '%s: duplication of ID %s' % (name, i) + errs += 1 + seen.add(i) + if i > biggest_id: + biggest_id = i + +def retag(s): + global biggest_id + biggest_id += 1 + return '' % biggest_id + +# Second pass: add IDs to paragraphs that currently lack them. + +for name in names: + f = open(name).read() + f1 = untagged.sub(retag, f) + if f1 != f: + tmpname = name + '.tmp' + fp = open(tmpname, 'w') + fp.write(f1) + fp.close() + os.rename(tmpname, name) + +sys.exit(errs) diff -r 28b5a5befb08 -r c838b3975bc6 en/ch00-preface.xml --- a/en/ch00-preface.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/ch00-preface.xml Thu Mar 19 21:18:52 2009 -0700 @@ -6,13 +6,13 @@ Why revision control? Why Mercurial? - Revision control is the process of managing multiple + Revision control is the process of managing multiple versions of a piece of information. In its simplest form, this is something that many people do by hand: every time you modify a file, save it under a new name that contains a number, each one higher than the number of the preceding version. - Manually managing multiple versions of even a single file is + Manually managing multiple versions of even a single file is an error-prone task, though, so software tools to help automate this process have long been available. The earliest automated revision control tools were intended to help a single user to @@ -23,11 +23,11 @@ problem coping with thousands of people working together on projects that consist of hundreds of thousands of files. - The arrival of distributed revision control is relatively + The arrival of distributed revision control is relatively recent, and so far this new field has grown due to people's willingness to explore ill-charted territory. - I am writing a book about distributed revision control + I am writing a book about distributed revision control because I believe that it is an important subject that deserves a field guide. I chose to write about Mercurial because it is the easiest tool to learn the terrain with, and yet it scales to @@ -37,41 +37,41 @@ Why use revision control? - There are a number of reasons why you or your team might + There are a number of reasons why you or your team might want to use an automated revision control tool for a project. - It will track the history and evolution of + It will track the history and evolution of your project, so you don't have to. For every change, you'll have a log of who made it; why they made it; when they made it; and what the change was. - When you're working with other people, + When you're working with other people, revision control software makes it easier for you to collaborate. For example, when people more or less simultaneously make potentially incompatible changes, the software will help you to identify and resolve those conflicts. - It can help you to recover from mistakes. If + It can help you to recover from mistakes. If you make a change that later turns out to be in error, you can revert to an earlier version of one or more files. In fact, a really good revision control tool will even help you to efficiently figure out exactly when a problem was introduced (see section for details). - It will help you to work simultaneously on, + It will help you to work simultaneously on, and manage the drift between, multiple versions of your project. - Most of these reasons are equally valid---at least in + Most of these reasons are equally valid---at least in theory---whether you're working on a project by yourself, or with a hundred other people. - A key question about the practicality of revision control + A key question about the practicality of revision control at these two different scales (lone hacker and huge team) is how its benefits compare to its @@ -79,19 +79,19 @@ difficult to understand or use is going to impose a high cost. - A five-hundred-person project is likely to collapse under + A five-hundred-person project is likely to collapse under its own weight almost immediately without a revision control tool and process. In this case, the cost of using revision control might hardly seem worth considering, since without it, failure is almost guaranteed. - On the other hand, a one-person quick hack + On the other hand, a one-person quick hack might seem like a poor place to use a revision control tool, because surely the cost of using one must be close to the overall cost of the project. Right? - Mercurial uniquely supports both of + Mercurial uniquely supports both of these scales of development. You can learn the basics in just a few minutes, and due to its low overhead, you can apply revision control to the smallest of projects with ease. Its @@ -101,7 +101,7 @@ time, Mercurial's high performance and peer-to-peer nature let you scale painlessly to handle large projects. - No revision control tool can rescue a poorly run project, + No revision control tool can rescue a poorly run project, but a good choice of tools can make a huge difference to the fluidity with which you can work on a project. @@ -110,19 +110,19 @@ The many names of revision control - Revision control is a diverse field, so much so that it is + Revision control is a diverse field, so much so that it is referred to by many names and acronyms. Here are a few of the more common variations you'll encounter: - Revision control (RCS) - Software configuration management (SCM), or + Revision control (RCS) + Software configuration management (SCM), or configuration management - Source code management - Source code control, or source + Source code management + Source code control, or source control - Version control + Version control (VCS) - Some people claim that these terms actually have different + Some people claim that these terms actually have different meanings, but in practice they overlap so much that there's no agreed or even useful way to tease them apart. @@ -132,7 +132,7 @@ This book is a work in progress - I am releasing this book while I am still writing it, in the + I am releasing this book while I am still writing it, in the hope that it will prove useful to others. I am writing under an open license in the hope that you, my readers, will contribute feedback and perhaps content of your own. @@ -141,21 +141,21 @@ About the examples in this book - This book takes an unusual approach to code samples. Every + This book takes an unusual approach to code samples. Every example is live---each one is actually the result of a shell script that executes the Mercurial commands you see. Every time an image of the book is built from its sources, all the example scripts are automatically run, and their current results compared against their expected results. - The advantage of this approach is that the examples are + The advantage of this approach is that the examples are always accurate; they describe exactly the behaviour of the version of Mercurial that's mentioned at the front of the book. If I update the version of Mercurial that I'm documenting, and the output of some command changes, the build fails. - There is a small disadvantage to this approach, which is + There is a small disadvantage to this approach, which is that the dates and times you'll see in examples tend to be squashed together in a way that they wouldn't be if the same commands were being typed by a human. Where a human @@ -163,13 +163,13 @@ resulting timestamps correspondingly spread out, my automated example scripts run many commands in one second. - As an instance of this, several consecutive commits in an + As an instance of this, several consecutive commits in an example can show up as having occurred during the same second. You can see this occur in the bisect example in section , for instance. - So when you're reading examples, don't place too much weight + So when you're reading examples, don't place too much weight on the dates or times you see in the output of commands. But do be confident that the behaviour you're seeing is consistent and reproducible. @@ -179,18 +179,18 @@ Trends in the field - There has been an unmistakable trend in the development and + There has been an unmistakable trend in the development and use of revision control tools over the past four decades, as people have become familiar with the capabilities of their tools and constrained by their limitations. - The first generation began by managing single files on + The first generation began by managing single files on individual computers. Although these tools represented a huge advance over ad-hoc manual revision control, their locking model and reliance on a single computer limited them to small, tightly-knit teams. - The second generation loosened these constraints by moving + The second generation loosened these constraints by moving to network-centered architectures, and managing entire projects at a time. As projects grew larger, they ran into new problems. With clients needing to talk to servers very frequently, server @@ -202,7 +202,7 @@ tools to interact with a project in a natural way, as they could not record their changes. - The current generation of revision control tools is + The current generation of revision control tools is peer-to-peer in nature. All of these systems have dropped the dependency on a single central server, and allow people to distribute their revision control data to where it's actually @@ -217,14 +217,14 @@ A few of the advantages of distributed revision control - Even though distributed revision control tools have for + Even though distributed revision control tools have for several years been as robust and usable as their previous-generation counterparts, people using older tools have not yet necessarily woken up to their advantages. There are a number of ways in which distributed tools shine relative to centralised ones. - For an individual developer, distributed tools are almost + For an individual developer, distributed tools are almost always much faster than centralised tools. This is for a simple reason: a centralised tool needs to talk over the network for many common operations, because most metadata is stored in a @@ -235,7 +235,7 @@ going to spend a lot of time interacting with your revision control software. - Distributed tools are indifferent to the vagaries of your + Distributed tools are indifferent to the vagaries of your server infrastructure, again because they replicate metadata to so many locations. If you use a centralised system and your server catches fire, you'd better hope that your backup media @@ -243,7 +243,7 @@ worked. With a distributed tool, you have many backups available on every contributor's computer. - The reliability of your network will affect distributed + The reliability of your network will affect distributed tools far less than it will centralised tools. You can't even use a centralised tool without a network connection, except for a few highly constrained commands. With a distributed tool, if @@ -256,7 +256,7 @@ Advantages for open source projects - If you take a shine to an open source project and decide + If you take a shine to an open source project and decide that you would like to start hacking on it, and that project uses a distributed revision control tool, you are at once a peer with the people who consider themselves the @@ -274,7 +274,7 @@ The forking non-problem - It has been suggested that distributed revision control + It has been suggested that distributed revision control tools pose some sort of risk to open source projects because they make it easy to fork the development of a project. A fork happens when there are differences in @@ -284,7 +284,7 @@ project's source code, and goes off in its own direction. - Sometimes the camps in a fork decide to reconcile their + Sometimes the camps in a fork decide to reconcile their differences. With a centralised revision control system, the technical process of reconciliation is painful, and has to be performed largely by hand. You have @@ -293,7 +293,7 @@ the tree somehow. This usually loses some or all of one side's revision history. - What distributed tools do with respect to forking is + What distributed tools do with respect to forking is they make forking the only way to develop a project. Every single change that you make is potentially a fork point. The great strength of this @@ -302,23 +302,23 @@ because forks are absolutely fundamental: they happen all the time. - If every piece of work that everybody does, all the + If every piece of work that everybody does, all the time, is framed in terms of forking and merging, then what the open source world refers to as a fork becomes purely a social issue. If anything, distributed tools lower the likelihood of a fork: - They eliminate the social distinction that + They eliminate the social distinction that centralised tools impose: that between insiders (people with commit access) and outsiders (people without). - They make it easier to reconcile after a + They make it easier to reconcile after a social fork, because all that's involved from the perspective of the revision control software is just another merge. - Some people resist distributed tools because they want + Some people resist distributed tools because they want to retain tight control over their projects, and they believe that centralised tools give them this control. However, if you're of this belief, and you publish your CVS @@ -335,7 +335,7 @@ Advantages for commercial projects - Many commercial projects are undertaken by teams that are + Many commercial projects are undertaken by teams that are scattered across the globe. Contributors who are far from a central server will see slower command execution and perhaps less reliability. Commercial revision control systems attempt @@ -347,7 +347,7 @@ there's no redundant communication between repositories over expensive long-haul network links. - Centralised revision control systems tend to have + Centralised revision control systems tend to have relatively low scalability. It's not unusual for an expensive centralised system to fall over under the combined load of just a few dozen concurrent users. Once again, the typical @@ -359,7 +359,7 @@ replication to balance load becomes a simple matter of scripting. - If you have an employee in the field, troubleshooting a + If you have an employee in the field, troubleshooting a problem at a customer's site, they'll benefit from distributed revision control. The tool will let them generate custom builds, try different fixes in isolation from each other, and @@ -372,35 +372,35 @@ Why choose Mercurial? - Mercurial has a unique set of properties that make it a + Mercurial has a unique set of properties that make it a particularly good choice as a revision control system. - It is easy to learn and use. - It is lightweight. - It scales excellently. - It is easy to + It is easy to learn and use. + It is lightweight. + It scales excellently. + It is easy to customise. - If you are at all familiar with revision control systems, + If you are at all familiar with revision control systems, you should be able to get up and running with Mercurial in less than five minutes. Even if not, it will take no more than a few minutes longer. Mercurial's command and feature sets are generally uniform and consistent, so you can keep track of a few general rules instead of a host of exceptions. - On a small project, you can start working with Mercurial in + On a small project, you can start working with Mercurial in moments. Creating new changes and branches; transferring changes around (whether locally or over a network); and history and status operations are all fast. Mercurial attempts to stay nimble and largely out of your way by combining low cognitive overhead with blazingly fast operations. - The usefulness of Mercurial is not limited to small + The usefulness of Mercurial is not limited to small projects: it is used by projects with hundreds to thousands of contributors, each containing tens of thousands of files and hundreds of megabytes of source code. - If the core functionality of Mercurial is not enough for + If the core functionality of Mercurial is not enough for you, it's easy to build on. Mercurial is well suited to scripting tasks, and its clean internals and implementation in Python make it easy to add features in the form of extensions. @@ -412,7 +412,7 @@ Mercurial compared with other tools - Before you read on, please understand that this section + Before you read on, please understand that this section necessarily reflects my own experiences, interests, and (dare I say it) biases. I have used every one of the revision control tools listed below, in most cases for several years at a @@ -422,22 +422,22 @@ Subversion - Subversion is a popular revision control tool, developed + Subversion is a popular revision control tool, developed to replace CVS. It has a centralised client/server architecture. - Subversion and Mercurial have similarly named commands for + Subversion and Mercurial have similarly named commands for performing the same operations, so if you're familiar with one, it is easy to learn to use the other. Both tools are portable to all popular operating systems. - Prior to version 1.5, Subversion had no useful support for + Prior to version 1.5, Subversion had no useful support for merges. At the time of writing, its merge tracking capability is new, and known to be complicated and buggy. - Mercurial has a substantial performance advantage over + Mercurial has a substantial performance advantage over Subversion on every revision control operation I have benchmarked. I have measured its advantage as ranging from a factor of two to a factor of six when compared with Subversion @@ -450,7 +450,7 @@ and network bandwidth become bottlenecks for modestly large projects. - Additionally, Subversion incurs substantial storage + Additionally, Subversion incurs substantial storage overhead to avoid network transactions for a few common operations, such as finding modified files (status) and displaying modifications @@ -460,13 +460,13 @@ even though the Mercurial repository contains a complete history of the project. - Subversion is widely supported by third party tools. + Subversion is widely supported by third party tools. Mercurial currently lags considerably in this area. This gap is closing, however, and indeed some of Mercurial's GUI tools now outshine their Subversion equivalents. Like Mercurial, Subversion has an excellent user manual. - Because Subversion doesn't store revision history on the + Because Subversion doesn't store revision history on the client, it is well suited to managing projects that deal with lots of large, opaque binary files. If you check in fifty revisions to an incompressible 10MB file, Subversion's @@ -475,14 +475,14 @@ of revisions, because the differences between each revision are large. - In addition, it's often difficult or, more usually, + In addition, it's often difficult or, more usually, impossible to merge different versions of a binary file. Subversion's ability to let a user lock a file, so that they temporarily have the exclusive right to commit changes to it, can be a significant advantage to a project where binary files are widely used. - Mercurial can import revision history from a Subversion + Mercurial can import revision history from a Subversion repository. It can also export revision history to a Subversion repository. This makes it easy to test the waters and use Mercurial and Subversion in parallel @@ -496,24 +496,24 @@ Git - Git is a distributed revision control tool that was + Git is a distributed revision control tool that was developed for managing the Linux kernel source tree. Like Mercurial, its early design was somewhat influenced by Monotone. - Git has a very large command set, with version 1.5.0 + Git has a very large command set, with version 1.5.0 providing 139 individual commands. It has something of a reputation for being difficult to learn. Compared to Git, Mercurial has a strong focus on simplicity. - In terms of performance, Git is extremely fast. In + In terms of performance, Git is extremely fast. In several cases, it is faster than Mercurial, at least on Linux, while Mercurial performs better on other operations. However, on Windows, the performance and general level of support that Git provides is, at the time of writing, far behind that of Mercurial. - While a Mercurial repository needs no maintenance, a Git + While a Mercurial repository needs no maintenance, a Git repository requires frequent manual repacks of its metadata. Without these, performance degrades, while space usage grows rapidly. A server that contains many Git @@ -524,13 +524,13 @@ slightly smaller than a Mercurial repository, but an unpacked repository is several orders of magnitude larger. - The core of Git is written in C. Many Git commands are + The core of Git is written in C. Many Git commands are implemented as shell or Perl scripts, and the quality of these scripts varies widely. I have encountered several instances where scripts charged along blindly in the presence of errors that should have been fatal. - Mercurial can import revision history from a Git + Mercurial can import revision history from a Git repository. @@ -538,11 +538,11 @@ CVS - CVS is probably the most widely used revision control tool + CVS is probably the most widely used revision control tool in the world. Due to its age and internal untidiness, it has been only lightly maintained for many years. - It has a centralised client/server architecture. It does + It has a centralised client/server architecture. It does not group related file changes into atomic commits, making it easy for people to break the build: one person can successfully commit part of a change and then be blocked @@ -554,7 +554,7 @@ the changes made to each file involved (if you even know what those files were). - CVS has a muddled notion of tags and branches that I will + CVS has a muddled notion of tags and branches that I will not attempt to even describe. It does not support renaming of files or directories well, making it easy to corrupt a repository. It has almost no internal consistency checking @@ -562,7 +562,7 @@ whether or how a repository is corrupt. I would not recommend CVS for any project, existing or new. - Mercurial can import CVS revision history. However, there + Mercurial can import CVS revision history. However, there are a few caveats that apply; these are true of every other revision control tool's CVS importer, too. Due to CVS's lack of atomic changes and unversioned filesystem hierarchy, it is @@ -576,7 +576,7 @@ the less interesting problems I can recall from personal experience). - Mercurial can import revision history from a CVS + Mercurial can import revision history from a CVS repository. @@ -584,13 +584,13 @@ Commercial tools - Perforce has a centralised client/server architecture, + Perforce has a centralised client/server architecture, with no client-side caching of any data. Unlike modern revision control tools, Perforce requires that a user run a command to inform the server about every file they intend to edit. - The performance of Perforce is quite good for small teams, + The performance of Perforce is quite good for small teams, but it falls off rapidly as the number of users grows beyond a few dozen. Modestly large Perforce installations require the deployment of proxies to cope with the load their users @@ -601,16 +601,16 @@ Choosing a revision control tool - With the exception of CVS, all of the tools listed above + With the exception of CVS, all of the tools listed above have unique strengths that suit them to particular styles of work. There is no single revision control tool that is best in all situations. - As an example, Subversion is a good choice for working + As an example, Subversion is a good choice for working with frequently edited binary files, due to its centralised nature and support for file locking. - I personally find Mercurial's properties of simplicity, + I personally find Mercurial's properties of simplicity, performance, and good merge support to be a compelling combination that has served me well for several years. @@ -620,7 +620,7 @@ Switching from another tool to Mercurial - Mercurial is bundled with an extension named Mercurial is bundled with an extension named convert, which can incrementally import revision history from several other revision control tools. By incremental, I mean that you can @@ -628,21 +628,21 @@ the conversion later to obtain new changes that happened after the initial conversion. - The revision control tools supported by The revision control tools supported by convert are as follows: - Subversion - CVS - Git - Darcs + Subversion + CVS + Git + Darcs
- In addition, convert can + In addition, convert can export changes from Mercurial to Subversion. This makes it possible to try Subversion and Mercurial in parallel before committing to a switchover, without risking the loss of any work. - The convert command + The convert command is easy to use. Simply point it at the path or URL of the source repository, optionally give it the name of the destination repository, and it will start working. After the @@ -653,7 +653,7 @@ A short history of revision control - The best known of the old-time revision control tools is + The best known of the old-time revision control tools is SCCS (Source Code Control System), which Marc Rochkind wrote at Bell Labs, in the early 1970s. SCCS operated on individual files, and required every person working on a project to have @@ -664,13 +664,13 @@ modifying those files without the help of an administrator. - Walter Tichy developed a free alternative to SCCS in the + Walter Tichy developed a free alternative to SCCS in the early 1980s; he called his program RCS (Revision Control System). Like SCCS, RCS required developers to work in a single shared workspace, and to lock files to prevent multiple people from modifying them simultaneously. - Later in the 1980s, Dick Grune used RCS as a building block + Later in the 1980s, Dick Grune used RCS as a building block for a set of shell scripts he initially called cmt, but then renamed to CVS (Concurrent Versions System). The big innovation of CVS was that it let developers work simultaneously and @@ -681,7 +681,7 @@ their copies independently. They had to merge their edits prior to committing changes to the central repository. - Brian Berliner took Grune's original scripts and rewrote + Brian Berliner took Grune's original scripts and rewrote them in C, releasing in 1989 the code that has since developed into the modern version of CVS. CVS subsequently acquired the ability to operate over a network connection, giving it a @@ -692,14 +692,14 @@ server is. CVS has been enormously successful; it is probably the world's most widely used revision control system. - In the early 1990s, Sun Microsystems developed an early + In the early 1990s, Sun Microsystems developed an early distributed revision control system, called TeamWare. A TeamWare workspace contains a complete copy of the project's history. TeamWare has no notion of a central repository. (CVS relied upon RCS for its history storage; TeamWare used SCCS.) - As the 1990s progressed, awareness grew of a number of + As the 1990s progressed, awareness grew of a number of problems with CVS. It records simultaneous changes to multiple files individually, instead of grouping them together as a single logically atomic operation. It does not manage its file @@ -709,7 +709,7 @@ level of fixing these architectural problems prohibitive. - In 2001, Jim Blandy and Karl Fogel, two developers who had + In 2001, Jim Blandy and Karl Fogel, two developers who had worked on CVS, started a project to replace it with a tool that would have a better architecture and cleaner code. The result, Subversion, does not stray from CVS's centralised client/server @@ -718,7 +718,7 @@ generally better tool than CVS. Since its initial release, it has rapidly grown in popularity. - More or less simultaneously, Graydon Hoare began working on + More or less simultaneously, Graydon Hoare began working on an ambitious distributed revision control system that he named Monotone. While Monotone addresses many of CVS's design flaws and has a peer-to-peer architecture, it goes beyond earlier (and @@ -727,7 +727,7 @@ integral notion of trust for code from different sources. - Mercurial began life in 2005. While a few aspects of its + Mercurial began life in 2005. While a few aspects of its design are influenced by Monotone, Mercurial focuses on ease of use, high performance, and scalability to very large projects. @@ -737,12 +737,12 @@ Colophon&emdash;this book is Free - This book is licensed under the Open Publication License, + This book is licensed under the Open Publication License, and is produced entirely using Free Software tools. It is typeset with DocBook XML. Illustrations are drawn and rendered with Inkscape. - The complete source code for this book is published as a + The complete source code for this book is published as a Mercurial repository, at http://hg.serpentine.com/mercurial/book. diff -r 28b5a5befb08 -r c838b3975bc6 en/ch01-tour-basic.xml --- a/en/ch01-tour-basic.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/ch01-tour-basic.xml Thu Mar 19 21:18:52 2009 -0700 @@ -7,21 +7,21 @@ Installing Mercurial on your system - Prebuilt binary packages of Mercurial are available for + Prebuilt binary packages of Mercurial are available for every popular operating system. These make it easy to start using Mercurial on your computer immediately. Linux - Because each Linux distribution has its own packaging + Because each Linux distribution has its own packaging tools, policies, and rate of development, it's difficult to give a comprehensive set of instructions on how to install Mercurial binaries. The version of Mercurial that you will end up with can vary depending on how active the person is who maintains the package for your distribution. - To keep things simple, I will focus on installing + To keep things simple, I will focus on installing Mercurial from the command line under the most popular Linux distributions. Most of these distributions provide graphical package managers that will let you install Mercurial with a @@ -29,15 +29,15 @@ mercurial. - Debian: + Debian: apt-get install mercurial - Fedora Core: + Fedora Core: yum install mercurial - Gentoo: + Gentoo: emerge mercurial - OpenSUSE: + OpenSUSE: yum install mercurial - Ubuntu: Ubuntu's Mercurial package is based on + Ubuntu: Ubuntu's Mercurial package is based on Debian's. To install it, run the following command. apt-get install mercurial @@ -47,7 +47,7 @@ Solaris - SunFreeWare, at SunFreeWare, at http://www.sunfreeware.com, is a good source for a large number of pre-built Solaris packages for 32 and 64 bit Intel and Sparc architectures, @@ -57,7 +57,7 @@ Mac OS X - Lee Cantey publishes an installer of Mercurial for Mac OS + Lee Cantey publishes an installer of Mercurial for Mac OS X at http://mercurial.berkwood.com. This package works on both Intel- and Power-based Macs. Before @@ -66,7 +66,7 @@ is easy to do; simply follow the instructions on Lee's site. - It's also possible to install Mercurial using Fink or + It's also possible to install Mercurial using Fink or MacPorts, two popular free package managers for Mac OS X. If you have Fink, use sudo apt-get install mercurial-py25. If MacPorts, sudo port @@ -76,14 +76,14 @@ Windows - Lee Cantey publishes an installer of Mercurial for Windows + Lee Cantey publishes an installer of Mercurial for Windows at http://mercurial.berkwood.com. This package has no external dependencies; it just works. - The Windows version of Mercurial does not + The Windows version of Mercurial does not automatically convert line endings between Windows and Unix styles. If you want to share work with Unix users, you must do a little additional configuration work. XXX Flesh this @@ -95,7 +95,7 @@ Getting started - To begin, we'll use the hg + To begin, we'll use the hg version command to find out whether Mercurial is actually installed properly. The actual version information that it prints isn't so important; it's whether it prints @@ -106,7 +106,7 @@ Built-in help - Mercurial provides a built-in help system. This is + Mercurial provides a built-in help system. This is invaluable for those times when you find yourself stuck trying to remember how to run a command. If you are completely stuck, simply run hg @@ -117,7 +117,7 @@ &interaction.tour.help; - For a more impressive level of detail (which you won't + For a more impressive level of detail (which you won't usually need) run hg help . The option is short for @@ -130,13 +130,13 @@ Working with a repository - In Mercurial, everything happens inside a + In Mercurial, everything happens inside a repository. The repository for a project contains all of the files that belong to that project, along with a historical record of the project's files. - There's nothing particularly magical about a repository; it + There's nothing particularly magical about a repository; it is simply a directory tree in your filesystem that Mercurial treats as special. You can rename or delete a repository any time you like, using either the command line or your file @@ -145,7 +145,7 @@ Making a local copy of a repository - Copying a repository is just a little + Copying a repository is just a little bit special. While you could use a normal file copying command to make a copy of a repository, it's best to use a built-in command that Mercurial provides. This command is @@ -154,23 +154,23 @@ &interaction.tour.clone; - If our clone succeeded, we should now have a local + If our clone succeeded, we should now have a local directory called hello. This directory will contain some files. &interaction.tour.ls; - These files have the same contents and history in our + These files have the same contents and history in our repository as they do in the repository we cloned. - Every Mercurial repository is complete, self-contained, + Every Mercurial repository is complete, self-contained, and independent. It contains its own private copy of a project's files and history. A cloned repository remembers the location of the repository it was cloned from, but it does not communicate with that repository, or any other, unless you tell it to. - What this means for now is that we're free to experiment + What this means for now is that we're free to experiment with our repository, safe in the knowledge that it's a private sandbox that won't affect anyone else. @@ -178,20 +178,20 @@ What's in a repository? - When we take a more detailed look inside a repository, we + When we take a more detailed look inside a repository, we can see that it contains a directory named .hg. This is where Mercurial keeps all of its metadata for the repository. &interaction.tour.ls-a; - The contents of the The contents of the .hg directory and its subdirectories are private to Mercurial. Every other file and directory in the repository is yours to do with as you please. - To introduce a little terminology, the To introduce a little terminology, the .hg directory is the real repository, and all of the files and directories that coexist with it are said to live in the @@ -208,45 +208,45 @@ A tour through history - One of the first things we might want to do with a new, + One of the first things we might want to do with a new, unfamiliar repository is understand its history. The hg log command gives us a view of history. &interaction.tour.log; - By default, this command prints a brief paragraph of output + By default, this command prints a brief paragraph of output for each change to the project that was recorded. In Mercurial terminology, we call each of these recorded events a changeset, because it can contain a record of changes to several files. - The fields in a record of output from The fields in a record of output from hg log are as follows. - changeset: This field has the + changeset: This field has the format of a number, followed by a colon, followed by a hexadecimal string. These are identifiers for the changeset. There are two identifiers because the number is shorter and easier to type than the hex string. - user: The identity of the + user: The identity of the person who created the changeset. This is a free-form field, but it most often contains a person's name and email address. - date: The date and time on + date: The date and time on which the changeset was created, and the timezone in which it was created. (The date and time are local to that timezone; they display what time and date it was for the person who created the changeset.) - summary: The first line of + summary: The first line of the text message that the creator of the changeset entered to describe the changeset. - The default output printed by hg + The default output printed by hg log is purely a summary; it is missing a lot of detail. - Figure provides a + Figure provides a graphical representation of the history of the hello repository, to make it a little easier to see which direction history is @@ -258,7 +258,7 @@ XXX add text - Graphical history of the Graphical history of the hello repository @@ -268,7 +268,7 @@ Changesets, revisions, and talking to other people - As English is a notoriously sloppy language, and computer + As English is a notoriously sloppy language, and computer science has a hallowed history of terminological confusion (why use one term when four will do?), revision control has a variety of words and phrases that mean the same thing. If you @@ -278,7 +278,7 @@ cset, and sometimes a changeset is referred to as a revision or a rev. - While it doesn't matter what word you + While it doesn't matter what word you use to refer to the concept of a changeset, the identifier that you use to refer to a specific changeset is of @@ -287,14 +287,14 @@ log identifies a changeset using both a number and a hexadecimal string. - The revision number is only valid in + The revision number is only valid in that repository, - while the hex string is the + while the hex string is the permanent, unchanging identifier that will always identify that exact changeset in every copy of the repository. - This distinction is important. If you send someone an + This distinction is important. If you send someone an email talking about revision 33, there's a high likelihood that their revision 33 will not be the same as yours. The reason for this is that a @@ -304,7 +304,7 @@ repositories. Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, while in another as $1,0,2$. - Mercurial uses revision numbers purely as a convenient + Mercurial uses revision numbers purely as a convenient shorthand. If you need to discuss a changeset with someone, or make a record of a changeset for some other reason (for example, in a bug report), use the hexadecimal @@ -314,7 +314,7 @@ Viewing specific revisions - To narrow the output of hg + To narrow the output of hg log down to a single revision, use the (or ) option. You can use @@ -323,7 +323,7 @@ &interaction.tour.log-r; - If you want to see the history of several revisions + If you want to see the history of several revisions without having to list each one, you can use range notation; this lets you express the idea I want all revisions between abc and @@ -331,7 +331,7 @@ &interaction.tour.log.range; - Mercurial also honours the order in which you specify + Mercurial also honours the order in which you specify revisions, so hg log -r 2:4 prints 2, 3, and 4. while hg log -r 4:2 prints 4, 3, and 2. @@ -340,7 +340,7 @@ More detailed information - While the summary information printed by While the summary information printed by hg log is useful if you already know what you're looking for, you may need to see a complete description of the change, or a list of the files changed, if @@ -352,7 +352,7 @@ &interaction.tour.log-v; - If you want to see both the description and content of a + If you want to see both the description and content of a change, add the (or ) option. This displays the content of a change as a unified @@ -367,39 +367,39 @@ All about command options - Let's take a brief break from exploring Mercurial commands + Let's take a brief break from exploring Mercurial commands to discuss a pattern in the way that they work; you may find this useful to keep in mind as we continue our tour. - Mercurial has a consistent and straightforward approach to + Mercurial has a consistent and straightforward approach to dealing with the options that you can pass to commands. It follows the conventions for options that are common to modern Linux and Unix systems. - Every option has a long name. For example, as + Every option has a long name. For example, as we've already seen, the hg log command accepts a option. - Most options have short names, too. Instead of + Most options have short names, too. Instead of , we can use . (The reason that some options don't have short names is that the options in question are rarely used.) - Long options start with two dashes (e.g. - Option naming and usage is consistent across + Option naming and usage is consistent across commands. For example, every command that lets you specify a changeset ID or revision number accepts both and arguments. - In the examples throughout this book, I use short options + In the examples throughout this book, I use short options instead of long. This just reflects my own preference, so don't read anything significant into it. - Most commands that print output of some kind will print more + Most commands that print output of some kind will print more output when passed a (or ) option, and less when passed (or @@ -409,11 +409,11 @@ Making and reviewing changes - Now that we have a grasp of viewing history in Mercurial, + Now that we have a grasp of viewing history in Mercurial, let's take a look at making some changes and examining them. - The first thing we'll do is isolate our experiment in a + The first thing we'll do is isolate our experiment in a repository of its own. We use the hg clone command, but we don't need to clone a copy of the remote repository. Since we already have a copy of it @@ -423,7 +423,7 @@ &interaction.tour.reclone; - As an aside, it's often good practice to keep a + As an aside, it's often good practice to keep a pristine copy of a remote repository around, which you can then make temporary clones of to create sandboxes for each task you want to work on. This lets you work on @@ -432,7 +432,7 @@ local clones are so cheap, there's almost no overhead to cloning and destroying repositories whenever you want. - In our my-hello + In our my-hello repository, we have a file hello.c that contains the classic hello, world program. Let's use the ancient and venerable sed command to @@ -445,20 +445,20 @@ &interaction.tour.sed; - Mercurial's hg status + Mercurial's hg status command will tell us what Mercurial knows about the files in the repository. &interaction.tour.status; - The hg status command + The hg status command prints no output for some files, but a line starting with M for hello.c. Unless you tell it to, hg status will not print any output for files that have not been modified. - The M indicates that + The M indicates that Mercurial has noticed that we modified hello.c. We didn't need to inform Mercurial that we were going to @@ -466,7 +466,7 @@ file after we were done; it was able to figure this out itself. - It's a little bit helpful to know that we've modified + It's a little bit helpful to know that we've modified hello.c, but we might prefer to know exactly what changes we've made to it. To do this, we use the hg diff @@ -478,14 +478,14 @@ Recording changes in a new changeset - We can modify files, build and test our changes, and use + We can modify files, build and test our changes, and use hg status and hg diff to review our changes, until we're satisfied with what we've done and arrive at a natural stopping point where we want to record our work in a new changeset. - The hg commit command lets + The hg commit command lets us create a new changeset; we'll usually refer to this as making a commit or committing. @@ -493,7 +493,7 @@ Setting up a username - When you try to run hg + When you try to run hg commit for the first time, it is not guaranteed to succeed. Mercurial records your name and address with each change that you commit, so that you and others will later be @@ -502,36 +502,36 @@ change with. It will attempt each of the following methods, in order: - If you specify a - If you have set the HGUSER + If you have set the HGUSER environment variable, this is checked next. - If you create a file in your home directory + If you create a file in your home directory called .hgrc, with a username entry, that will be used next. To see what the contents of this file should look like, refer to section below. - If you have set the EMAIL + If you have set the EMAIL environment variable, this will be used next. - Mercurial will query your system to find out + Mercurial will query your system to find out your local user name and host name, and construct a username from these components. Since this often results in a username that is not very useful, it will print a warning if it has to do this. - If all of these mechanisms fail, Mercurial will + If all of these mechanisms fail, Mercurial will fail, printing an error message. In this case, it will not let you commit until you set up a username. - You should think of the HGUSER environment + You should think of the HGUSER environment variable and the option to the hg commit command as ways to override Mercurial's @@ -542,7 +542,7 @@ Creating a Mercurial configuration file - To set a user name, use your favourite editor + To set a user name, use your favourite editor to create a file called .hgrc in your home directory. Mercurial will use this file to look up your personalised @@ -554,7 +554,7 @@ username = Firstname Lastname <email.address@domain.net> - The [ui] line begins a + The [ui] line begins a section of the config file, so you can read the username = ... line as meaning set the value of the @@ -569,14 +569,14 @@ Choosing a user name - You can use any text you like as the value of + You can use any text you like as the value of the username config item, since this information is for reading by other people, but for interpreting by Mercurial. The convention that most people follow is to use their name and email address, as in the example above. - Mercurial's built-in web server obfuscates + Mercurial's built-in web server obfuscates email addresses, to make it more difficult for the email harvesting tools that spammers use. This reduces the likelihood that you'll start receiving more junk email @@ -588,7 +588,7 @@ Writing a commit message - When we commit a change, Mercurial drops us into + When we commit a change, Mercurial drops us into a text editor, to enter a message that will describe the modifications we've made in this changeset. This is called the commit message. It will be a @@ -598,14 +598,14 @@ &interaction.tour.commit; - The editor that the hg + The editor that the hg commit command drops us into will contain an empty line, followed by a number of lines starting with HG:. XXX fix this XXX - Mercurial ignores the lines that start with + Mercurial ignores the lines that start with HG:; it uses them only to tell us which files it's recording changes to. Modifying or deleting these lines has no effect. @@ -613,7 +613,7 @@ Writing a good commit message - Since hg log + Since hg log only prints the first line of a commit message by default, it's best to write a commit message whose first line stands alone. Here's a real example of a commit message that @@ -627,13 +627,13 @@ date: Tue Sep 26 21:37:07 2006 -0700 summary: include buildmeister/commondefs. Add exports. - As far as the remainder of the contents of the + As far as the remainder of the contents of the commit message are concerned, there are no hard-and-fast rules. Mercurial itself doesn't interpret or care about the contents of the commit message, though your project may have policies that dictate a certain kind of formatting. - My personal preference is for short, but + My personal preference is for short, but informative, commit messages that tell me something that I can't figure out with a quick glance at the output of hg log @@ -642,12 +642,12 @@ Aborting a commit - If you decide that you don't want to commit + If you decide that you don't want to commit while in the middle of editing a commit message, simply exit from your editor without saving the file that it's editing. This will cause nothing to happen to either the repository or the working directory. - If we run the hg + If we run the hg commit command without any arguments, it records all of the changes we've made, as reported by hg status and Admiring our new handiwork - Once we've finished the commit, we can use the + Once we've finished the commit, we can use the hg tip command to display the changeset we just created. This command produces output that is identical to hg @@ -665,7 +665,7 @@ &interaction.tour.tip; - We refer to + We refer to the newest revision in the repository as the tip revision, or simply the tip. @@ -674,7 +674,7 @@ Sharing changes - We mentioned earlier that repositories in + We mentioned earlier that repositories in Mercurial are self-contained. This means that the changeset we just created exists only in our my-hello repository. Let's @@ -683,7 +683,7 @@ Pulling changes from another repository - To get started, let's clone our original + To get started, let's clone our original hello repository, which does not contain the change we just committed. We'll call our temporary repository We'll use the hg + We'll use the hg pull command to bring changes from my-hello into hello-pull. However, blindly @@ -704,21 +704,21 @@ &interaction.tour.incoming; - (Of course, someone could + (Of course, someone could cause more changesets to appear in the repository that we ran hg incoming in, before we get a chance to hg pull the changes, so that we could end up pulling changes that we didn't expect.) - Bringing changes into a repository is a simple + Bringing changes into a repository is a simple matter of running the hg pull command, and telling it which repository to pull from. &interaction.tour.pull; - As you can see + As you can see from the before-and-after output of hg tip, we have successfully pulled changes into our repository. There remains one step @@ -728,7 +728,7 @@ Updating the working directory - We have so far glossed over the relationship between a + We have so far glossed over the relationship between a repository and its working directory. The hg pull command that we ran in section brought changes @@ -740,7 +740,7 @@ &interaction.tour.update; - It might seem a bit strange that hg + It might seem a bit strange that hg pull doesn't update the working directory automatically. There's actually a good reason for this: you can use hg update to update @@ -751,12 +751,12 @@ role="hg-cmd">hg pull which automatically updated the working directory to a new revision, you might not be terribly happy. - However, since pull-then-update is such a common thing to + However, since pull-then-update is such a common thing to do, Mercurial lets you combine the two by passing the option to hg pull. - If you look back at the output of If you look back at the output of hg pull in section when we ran it without , you can see that it printed @@ -765,13 +765,13 @@ - To find out what revision the working directory is at, use + To find out what revision the working directory is at, use the hg parents command. &interaction.tour.parents; - If you look back at figure If you look back at figure , you'll see arrows connecting each changeset. The node that the arrow leads from in each case is a @@ -780,14 +780,14 @@ has a parent in just the same way; this is the changeset that the working directory currently contains. - To update the working directory to a particular revision, + To update the working directory to a particular revision, give a revision number or changeset ID to the hg update command. &interaction.tour.older; - If you omit an explicit revision, If you omit an explicit revision, hg update will update to the tip revision, as shown by the second call to hg update in the example @@ -797,7 +797,7 @@ Pushing changes to another repository - Mercurial lets us push changes to another + Mercurial lets us push changes to another repository, from the repository we're currently visiting. As with the example of hg pull above, we'll create a temporary repository @@ -805,19 +805,19 @@ &interaction.tour.clone-push; - The hg outgoing command + The hg outgoing command tells us what changes would be pushed into another repository. &interaction.tour.outgoing; - And the + And the hg push command does the actual push. &interaction.tour.push; - As with + As with hg pull, the hg push command does not update the working directory in the repository that it's pushing @@ -826,7 +826,7 @@ does not provide a -u option that updates the other repository's working directory.) - What happens if we try to pull or push changes + What happens if we try to pull or push changes and the receiving repository already has those changes? Nothing too exciting. @@ -835,7 +835,7 @@ Sharing changes over a network - The commands we have covered in the previous few + The commands we have covered in the previous few sections are not limited to working with local repositories. Each works in exactly the same fashion over a network connection; simply pass in a URL instead of a local @@ -843,7 +843,7 @@ &interaction.tour.outgoing.net; - In this example, we + In this example, we can see what changes we could push to the remote repository, but the repository is understandably not set up to let anonymous users push to it. diff -r 28b5a5befb08 -r c838b3975bc6 en/ch02-tour-merge.xml --- a/en/ch02-tour-merge.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/ch02-tour-merge.xml Thu Mar 19 21:18:52 2009 -0700 @@ -4,7 +4,7 @@ A tour of Mercurial: merging work - We've now covered cloning a repository, making changes in a + We've now covered cloning a repository, making changes in a repository, and pulling or pushing changes from one repository into another. Our next step is merging changes from separate repositories. @@ -12,29 +12,29 @@ Merging streams of work - Merging is a fundamental part of working with a distributed + Merging is a fundamental part of working with a distributed revision control tool. - Alice and Bob each have a personal copy of a + Alice and Bob each have a personal copy of a repository for a project they're collaborating on. Alice fixes a bug in her repository; Bob adds a new feature in his. They want the shared repository to contain both the bug fix and the new feature. - I frequently work on several different tasks for + I frequently work on several different tasks for a single project at once, each safely isolated in its own repository. Working this way means that I often need to merge one piece of my own work with another. - Because merging is such a common thing to need to do, + Because merging is such a common thing to need to do, Mercurial makes it easy. Let's walk through the process. We'll begin by cloning yet another repository (see how often they spring up?) and making a change in it. &interaction.tour.merge.clone; - We should now have two copies of + We should now have two copies of hello.c with different contents. The histories of the two repositories have also diverged, as illustrated in figure XXX add text - Divergent recent histories of the Divergent recent histories of the my-hello and my-new-hello repositories - We already know that pulling changes from our We already know that pulling changes from our my-hello repository will have no effect on the working directory. &interaction.tour.merge.pull; - However, the hg pull + However, the hg pull command says something about heads. Head changesets - A head is a change that has no descendants, or children, + A head is a change that has no descendants, or children, as they're also known. The tip revision is thus a head, because the newest revision in a repository doesn't have any children, but a repository can contain more than one @@ -75,14 +75,14 @@ XXX add text - Repository contents after pulling from + Repository contents after pulling from my-hello into my-new-hello - In figure , you can + In figure , you can see the effect of the pull from my-hello into my-new-hello. The history that @@ -103,13 +103,13 @@ Performing the merge - What happens if we try to use the normal What happens if we try to use the normal hg update command to update to the new tip? &interaction.tour.merge.update; - Mercurial is telling us that the hg + Mercurial is telling us that the hg update command won't do a merge; it won't update the working directory when it thinks we might be wanting to do a merge, unless we force it to do so. Instead, we use the @@ -123,12 +123,12 @@ XXX add text - Working directory and repository during + Working directory and repository during merge, and following commit - This updates the working directory so that it contains + This updates the working directory so that it contains changes from both heads, which is reflected in both the output of hg parents and the contents of @@ -140,21 +140,21 @@ Committing the results of the merge - Whenever we've done a merge, hg + Whenever we've done a merge, hg parents will display two parents until we hg commit the results of the merge. &interaction.tour.merge.commit; - We now have a new tip revision; notice that it has + We now have a new tip revision; notice that it has both of our former heads as its parents. These are the same revisions that were previously displayed by hg parents. &interaction.tour.merge.tip; - In figure In figure , you can see a representation of what happens to the working directory during the merge, and how this affects the repository when the commit @@ -167,7 +167,7 @@ Merging conflicting changes - Most merges are simple affairs, but sometimes you'll find + Most merges are simple affairs, but sometimes you'll find yourself merging changes where each modifies the same portions of the same files. Unless both modifications are identical, this results in a conflict, where you have @@ -179,18 +179,18 @@ XXX add text - Conflicting changes to a + Conflicting changes to a document - Figure illustrates + Figure illustrates an instance of two conflicting changes to a document. We started with a single version of the file; then we made some changes; while someone else made different changes to the same text. Our task in resolving the conflicting changes is to decide what the file should look like. - Mercurial doesn't have a built-in facility for handling + Mercurial doesn't have a built-in facility for handling conflicts. Instead, it runs an external program called hgmerge. This is a shell script that is bundled with Mercurial; you can change it to behave however you @@ -201,7 +201,7 @@ human guidance) or aren't present, the script tries a few different graphical merging tools. - It's also possible to get Mercurial to run another program + It's also possible to get Mercurial to run another program or script instead of hgmerge, by setting the HGMERGE environment variable to the name of your preferred program. @@ -209,7 +209,7 @@ Using a graphical merge tool - My preferred graphical merge tool is + My preferred graphical merge tool is kdiff3, which I'll use to describe the features that are common to graphical file merging tools. You can see a screenshot of kdiff3 in action in @@ -219,26 +219,26 @@ of the file of interest to us. The tool thus splits the upper portion of the window into three panes: - At the left is the base + At the left is the base version of the file, i.e. the most recent version from which the two versions we're trying to merge are descended. - In the middle is our version of + In the middle is our version of the file, with the contents that we modified. - On the right is their version + On the right is their version of the file, the one that from the changeset that we're trying to merge with. - In the pane below these is the current + In the pane below these is the current result of the merge. Our task is to replace all of the red text, which indicates unresolved conflicts, with some sensible merger of the ours and theirs versions of the file. - All four of these panes are locked + All four of these panes are locked together; if we scroll vertically or horizontally in any of them, the others are updated to display the corresponding sections of their respective files. @@ -247,18 +247,18 @@ XXX add text - Using kdiff3 to merge + Using kdiff3 to merge versions of a file - For each conflicting portion of the file, we can choose to + For each conflicting portion of the file, we can choose to resolve the conflict using some combination of text from the base version, ours, or theirs. We can also manually edit the merged file at any time, in case we need to make further modifications. - There are many file merging tools + There are many file merging tools available, too many to cover here. They vary in which platforms they are available for, and in their particular strengths and weaknesses. Most are tuned for merging files @@ -269,19 +269,19 @@ A worked example - In this example, we will reproduce the file modification + In this example, we will reproduce the file modification history of figure above. Let's begin by creating a repository with a base version of our document. &interaction.tour-merge-conflict.wife; - We'll clone the repository and make a change to the + We'll clone the repository and make a change to the file. &interaction.tour-merge-conflict.cousin; - And another clone, to simulate someone else making a + And another clone, to simulate someone else making a change to the file. (This hints at the idea that it's not all that unusual to merge with yourself when you isolate tasks in separate repositories, and indeed to find and resolve @@ -289,13 +289,13 @@ &interaction.tour-merge-conflict.son; - Having created two + Having created two different versions of the file, we'll set up an environment suitable for running our merge. &interaction.tour-merge-conflict.pull; - In this example, I won't use Mercurial's normal + In this example, I won't use Mercurial's normal hgmerge program to do the merge, because it would drop my nice automated example-running tool into a graphical user interface. Instead, I'll set @@ -305,25 +305,25 @@ example on your computer, don't bother setting HGMERGE. - XXX FIX THIS + XXX FIX THIS EXAMPLE. &interaction.tour-merge-conflict.merge; - Because merge can't resolve the + Because merge can't resolve the conflicting changes, it leaves merge markers inside the file that has conflicts, indicating which lines have conflicts, and whether they came from our version of the file or theirs. - Mercurial can tell from the way merge + Mercurial can tell from the way merge exits that it wasn't able to merge successfully, so it tells us what commands we'll need to run if we want to redo the merging operation. This could be useful if, for example, we were running a graphical merge tool and quit because we were confused or realised we had made a mistake. - If automatic or manual merges fail, there's nothing to + If automatic or manual merges fail, there's nothing to prevent us from fixing up the affected files ourselves, and committing the results of our merge: @@ -334,29 +334,29 @@ Simplifying the pull-merge-commit sequence - The process of merging changes as outlined above is + The process of merging changes as outlined above is straightforward, but requires running three commands in sequence. hg pull hg merge hg commit -m 'Merged remote changes' - In the case of the final commit, you also need to enter a + In the case of the final commit, you also need to enter a commit message, which is almost always going to be a piece of uninteresting boilerplate text. - It would be nice to reduce the number of steps needed, if + It would be nice to reduce the number of steps needed, if this were possible. Indeed, Mercurial is distributed with an extension called fetch that does just this. - Mercurial provides a flexible extension mechanism that lets + Mercurial provides a flexible extension mechanism that lets people extend its functionality, while keeping the core of Mercurial small and easy to deal with. Some extensions add new commands that you can use from the command line, while others work behind the scenes, for example adding capabilities to the server. - The fetch extension adds a + The fetch extension adds a new command called, not surprisingly, hg fetch. This extension acts as a combination of hg pull, - Enabling the fetch + Enabling the fetch extension is easy. Edit your .hgrc, and either go to the extensions section or create an @@ -378,7 +378,7 @@ . [extensions] fetch = - (Normally, on the right-hand side of the + (Normally, on the right-hand side of the = would appear the location of the extension, but since the fetch extension is in the standard diff -r 28b5a5befb08 -r c838b3975bc6 en/ch03-concepts.xml --- a/en/ch03-concepts.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/ch03-concepts.xml Thu Mar 19 21:18:52 2009 -0700 @@ -4,20 +4,20 @@ Behind the scenes - Unlike many revision control systems, the concepts upon which + Unlike many revision control systems, the concepts upon which Mercurial is built are simple enough that it's easy to understand how the software really works. Knowing this certainly isn't necessary, but I find it useful to have a mental model of what's going on. - This understanding gives me confidence that Mercurial has been + This understanding gives me confidence that Mercurial has been carefully designed to be both safe and efficient. And just as importantly, if it's easy for me to retain a good idea of what the software is doing when I perform a revision control task, I'm less likely to be surprised by its behaviour. - In this chapter, we'll initially cover the core concepts + In this chapter, we'll initially cover the core concepts behind Mercurial's design, then continue to discuss some of the interesting details of its implementation. @@ -27,7 +27,7 @@ Tracking the history of a single file - When Mercurial tracks modifications to a file, it stores + When Mercurial tracks modifications to a file, it stores the history of that file in a metadata object called a filelog. Each entry in the filelog contains enough information to reconstruct one revision of the @@ -38,7 +38,7 @@ an index to help Mercurial to find a revision efficiently. - A file that is large, or has a lot of history, has its + A file that is large, or has a lot of history, has its filelog stored in separate data (.d suffix) and index (.i suffix) files. For @@ -53,7 +53,7 @@ XXX add text - Relationships between files in working + Relationships between files in working directory and filelogs in repository @@ -62,7 +62,7 @@ Managing tracked files - Mercurial uses a structure called a + Mercurial uses a structure called a manifest to collect together information about the files that it tracks. Each entry in the manifest contains information about the files present in a single @@ -74,7 +74,7 @@ Recording changeset information - The changelog contains information + The changelog contains information about each changeset. Each revision records who committed a change, the changeset comment, other pieces of changeset-related information, and the revision of the @@ -84,14 +84,14 @@ Relationships between revisions - Within a changelog, a manifest, or a filelog, each + Within a changelog, a manifest, or a filelog, each revision stores a pointer to its immediate parent (or to its two parents, if it's a merge revision). As I mentioned above, there are also relationships between revisions across these structures, and they are hierarchical in nature. - For every changeset in a repository, there is exactly one + For every changeset in a repository, there is exactly one revision stored in the changelog. Each revision of the changelog contains a pointer to a single revision of the manifest. A revision of the manifest stores a pointer to a @@ -102,12 +102,12 @@ XXX - add textMetadata + add textMetadata relationships - As the illustration shows, there is + As the illustration shows, there is not a one to one relationship between revisions in the changelog, manifest, or filelog. If the manifest hasn't changed between two @@ -122,14 +122,14 @@ Safe, efficient storage - The underpinnings of changelogs, manifests, and filelogs are + The underpinnings of changelogs, manifests, and filelogs are provided by a single structure called the revlog. Efficient storage - The revlog provides efficient storage of revisions using a + The revlog provides efficient storage of revisions using a delta mechanism. Instead of storing a complete copy of a file for each revision, it stores the changes needed to transform an older revision into the new @@ -137,7 +137,7 @@ typically a fraction of a percent of the size of a full copy of a file. - Some obsolete revision control systems can only work with + Some obsolete revision control systems can only work with deltas of text files. They must either store binary files as complete snapshots or encoded into a text representation, both of which are wasteful approaches. Mercurial can efficiently @@ -148,13 +148,13 @@ Safe operation - Mercurial only ever appends data to + Mercurial only ever appends data to the end of a revlog file. It never modifies a section of a file after it has written it. This is both more robust and efficient than schemes that need to modify or rewrite data. - In addition, Mercurial treats every write as part of a + In addition, Mercurial treats every write as part of a transaction that can span a number of files. A transaction is atomic: either the entire transaction succeeds and its effects are all @@ -164,7 +164,7 @@ writing it, the reader will never see a partially written result that might confuse it. - The fact that Mercurial only appends to files makes it + The fact that Mercurial only appends to files makes it easier to provide this transactional guarantee. The easier it is to do stuff like this, the more confident you should be that it's done correctly. @@ -173,7 +173,7 @@ Fast retrieval - Mercurial cleverly avoids a pitfall common to all earlier + Mercurial cleverly avoids a pitfall common to all earlier revision control systems: the problem of inefficient retrieval. Most revision control systems store the contents of a revision as an incremental series of @@ -187,12 +187,12 @@ XXX - add textSnapshot of + add textSnapshot of a revlog, with incremental deltas - The innovation that Mercurial applies to this problem is + The innovation that Mercurial applies to this problem is simple but effective. Once the cumulative amount of delta information stored since the last snapshot exceeds a fixed threshold, it stores a new snapshot (compressed, of course), @@ -201,7 +201,7 @@ quickly. This approach works so well that it has since been copied by several other revision control systems. - Figure illustrates + Figure illustrates the idea. In an entry in a revlog's index file, Mercurial stores the range of entries from the data file that it must read to reconstruct a particular revision. @@ -209,7 +209,7 @@ Aside: the influence of video compression - If you're familiar with video compression or have ever + If you're familiar with video compression or have ever watched a TV feed through a digital cable or satellite service, you may know that most video compression schemes store each frame of video as a delta against its predecessor @@ -218,7 +218,7 @@ visual errors accumulate over the course of a number of inter-frame deltas. - Because it's possible for a video stream to drop + Because it's possible for a video stream to drop out occasionally due to signal glitches, and to limit the accumulation of artefacts introduced by the lossy compression process, video encoders periodically insert a @@ -234,24 +234,24 @@ Identification and strong integrity - Along with delta or snapshot information, a revlog entry + Along with delta or snapshot information, a revlog entry contains a cryptographic hash of the data that it represents. This makes it difficult to forge the contents of a revision, and easy to detect accidental corruption. - Hashes provide more than a mere check against corruption; + Hashes provide more than a mere check against corruption; they are used as the identifiers for revisions. The changeset identification hashes that you see as an end user are from revisions of the changelog. Although filelogs and the manifest also use hashes, Mercurial only uses these behind the scenes. - Mercurial verifies that hashes are correct when it + Mercurial verifies that hashes are correct when it retrieves file revisions and when it pulls changes from another repository. If it encounters an integrity problem, it will complain and stop whatever it's doing. - In addition to the effect it has on retrieval efficiency, + In addition to the effect it has on retrieval efficiency, Mercurial's use of periodic snapshots makes it more robust against partial data corruption. If a revlog becomes partly corrupted due to a hardware error or system bug, it's often @@ -265,7 +265,7 @@ Revision history, branching, and merging - Every entry in a Mercurial revlog knows the identity of its + Every entry in a Mercurial revlog knows the identity of its immediate ancestor revision, usually referred to as its parent. In fact, a revision contains room for not one parent, but two. Mercurial uses a special hash, @@ -273,13 +273,13 @@ there is no parent here. This hash is simply a string of zeroes. - In figure , you can see + In figure , you can see an example of the conceptual structure of a revlog. Filelogs, manifests, and changelogs all have this same structure; they differ only in the kind of data stored in each delta or snapshot. - The first revision in a revlog (at the bottom of the image) + The first revision in a revlog (at the bottom of the image) has the null ID in both of its parent slots. For a normal revision, its first parent slot contains the ID of its parent revision, and its second contains the null @@ -298,10 +298,10 @@ The working directory - In the working directory, Mercurial stores a snapshot of the + In the working directory, Mercurial stores a snapshot of the files from the repository as of a particular changeset. - The working directory knows which changeset + The working directory knows which changeset it contains. When you update the working directory to contain a particular changeset, Mercurial looks up the appropriate revision of the manifest to find out which files it was tracking @@ -310,13 +310,13 @@ those files, with the same contents it had when the changeset was committed. - The dirstate contains Mercurial's + The dirstate contains Mercurial's knowledge of the working directory. This details which changeset the working directory is updated to, and all of the files that Mercurial is tracking in the working directory. - Just as a revision of a revlog has room for two parents, so + Just as a revision of a revlog has room for two parents, so that it can represent either a normal revision (with one parent) or a merge of two earlier revisions, the dirstate has slots for two parents. When you use the hg @@ -332,7 +332,7 @@ What happens when you commit - The dirstate stores parent information for more than just + The dirstate stores parent information for more than just book-keeping purposes. Mercurial uses the parents of the dirstate as the parents of a new changeset when you perform a commit. @@ -340,12 +340,12 @@ XXX - add textThe working + add textThe working directory can have two parents - Figure shows the + Figure shows the normal state of the working directory, where it has a single changeset as parent. That changeset is the tip, the newest changeset in the @@ -354,12 +354,12 @@ XXX - add textThe working + add textThe working directory gains new parents after a commit - It's useful to think of the working directory as + It's useful to think of the working directory as the changeset I'm about to commit. Any files that you tell Mercurial that you've added, removed, renamed, or copied will be reflected in that changeset, as will @@ -367,7 +367,7 @@ the new changeset will have the parents of the working directory as its parents. - After a commit, Mercurial will update the parents of the + After a commit, Mercurial will update the parents of the working directory, so that the first parent is the ID of the new changeset, and the second is the null ID. This is shown in figure . @@ -380,7 +380,7 @@ Creating a new head - It's perfectly normal to update the working directory to a + It's perfectly normal to update the working directory to a changeset other than the current tip. For example, you might want to know what your project looked like last Tuesday, or you could be looking through changesets to see which one @@ -394,12 +394,12 @@ XXX - add textThe working + add textThe working directory, updated to an older changeset - Having updated the working directory to an older + Having updated the working directory to an older changeset, what happens if you make some changes, and then commit? Mercurial behaves in the same way as I outlined above. The parents of the working directory become the @@ -413,13 +413,13 @@ XXX - add textAfter a + add textAfter a commit made while synced to an older changeset - If you're new to Mercurial, you should keep in mind a + If you're new to Mercurial, you should keep in mind a common error, which is to use the hg pull command without any options. By default, the hg @@ -431,7 +431,7 @@ a new head, because your working directory isn't synced to whatever the current tip is. - I put the word error in quotes because + I put the word error in quotes because all that you need to do to rectify this situation is hg merge, then hg commit. In other words, this @@ -445,7 +445,7 @@ Merging heads - When you run the hg merge + When you run the hg merge command, Mercurial leaves the first parent of the working directory unchanged, and sets the second parent to the changeset you're merging with, as shown in figure XXX - add textMerging two + add textMerging two heads - Mercurial also has to modify the working directory, to + Mercurial also has to modify the working directory, to merge the files managed in the two changesets. Simplified a little, the merging process goes like this, for every file in the manifests of both changesets. - If neither changeset has modified a file, do + If neither changeset has modified a file, do nothing with that file. - If one changeset has modified a file, and the + If one changeset has modified a file, and the other hasn't, create the modified copy of the file in the working directory. - If one changeset has removed a file, and the + If one changeset has removed a file, and the other hasn't (or has also deleted it), delete the file from the working directory. - If one changeset has removed a file, but the + If one changeset has removed a file, but the other has modified the file, ask the user what to do: keep the modified file, or remove it? - If both changesets have modified a file, + If both changesets have modified a file, invoke an external merge program to choose the new contents for the merged file. This may require input from the user. - If one changeset has modified a file, and the + If one changeset has modified a file, and the other has renamed or copied the file, make sure that the changes follow the new name of the file. - There are more details&emdash;merging has plenty of corner + There are more details&emdash;merging has plenty of corner cases&emdash;but these are the most common choices that are involved in a merge. As you can see, most cases are completely automatic, and indeed most merges finish automatically, without requiring your input to resolve any conflicts. - When you're thinking about what happens when you commit + When you're thinking about what happens when you commit after a merge, once again the working directory is the changeset I'm about to commit. After the hg merge command completes, the working directory has two parents; these will become the parents of the new changeset. - Mercurial lets you perform multiple merges, but you must + Mercurial lets you perform multiple merges, but you must commit the results of each individual merge as you go. This is necessary because Mercurial only tracks two parents for both revisions and the working directory. While it would be @@ -514,7 +514,7 @@ Other interesting design features - In the sections above, I've tried to highlight some of the + In the sections above, I've tried to highlight some of the most important aspects of Mercurial's design, to illustrate that it pays careful attention to reliability and performance. However, the attention to detail doesn't stop there. There are @@ -527,13 +527,13 @@ Clever compression - When appropriate, Mercurial will store both snapshots and + When appropriate, Mercurial will store both snapshots and deltas in compressed form. It does this by always trying to compress a snapshot or delta, but only storing the compressed version if it's smaller than the uncompressed version. - This means that Mercurial does the right + This means that Mercurial does the right thing when storing a file whose native form is compressed, such as a zip archive or a JPEG image. When these types of files are compressed a second @@ -541,7 +541,7 @@ once-compressed form, and so Mercurial will store the plain zip or JPEG. - Deltas between revisions of a compressed file are usually + Deltas between revisions of a compressed file are usually larger than snapshots of the file, and Mercurial again does the right thing in these cases. It finds that such a delta exceeds the threshold at which it should store a @@ -552,7 +552,7 @@ Network recompression - When storing revisions on disk, Mercurial uses the + When storing revisions on disk, Mercurial uses the deflate compression algorithm (the same one used by the popular zip archive format), which balances good speed with a respectable compression @@ -560,7 +560,7 @@ network connection, Mercurial uncompresses the compressed revision data. - If the connection is over HTTP, Mercurial recompresses + If the connection is over HTTP, Mercurial recompresses the entire stream of data using a compression algorithm that gives a better compression ratio (the Burrows-Wheeler algorithm from the widely used bzip2 @@ -570,7 +570,7 @@ transferred, yielding better network performance over almost all kinds of network. - (If the connection is over ssh, + (If the connection is over ssh, Mercurial doesn't recompress the stream, because ssh can already do this itself.) @@ -580,7 +580,7 @@ Read/write ordering and atomicity - Appending to files isn't the whole story when it comes to + Appending to files isn't the whole story when it comes to guaranteeing that a reader won't see a partial write. If you recall figure , revisions in the @@ -588,12 +588,12 @@ the manifest point to revisions in filelogs. This hierarchy is deliberate. - A writer starts a transaction by writing filelog and + A writer starts a transaction by writing filelog and manifest data, and doesn't write any changelog data until those are finished. A reader starts by reading changelog data, then manifest data, followed by filelog data. - Since the writer has always finished writing filelog and + Since the writer has always finished writing filelog and manifest data before it writes to the changelog, a reader will never read a pointer to a partially written manifest revision from the changelog, and it will never read a pointer to a @@ -603,7 +603,7 @@ Concurrent access - The read/write ordering and atomicity guarantees mean that + The read/write ordering and atomicity guarantees mean that Mercurial never needs to lock a repository when it's reading data, even if the repository is being written to while the read is occurring. This has a big @@ -612,7 +612,7 @@ safely all at once, no matter whether it's being written to or not. - The lockless nature of reading means that if you're + The lockless nature of reading means that if you're sharing a repository on a multi-user system, you don't need to grant other local users permission to write to your repository in order for @@ -625,7 +625,7 @@ which of course makes for all kinds of nasty and annoying security and administrative problems.) - Mercurial uses locks to ensure that only one process can + Mercurial uses locks to ensure that only one process can write to a repository at a time (the locking mechanism is safe even over filesystems that are notoriously hostile to locking, such as NFS). If a repository is locked, a writer will wait @@ -639,7 +639,7 @@ Safe dirstate access - As with revision data, Mercurial doesn't take a lock to + As with revision data, Mercurial doesn't take a lock to read the dirstate file; it does acquire a lock to write it. To avoid the possibility of reading a partially written copy of the dirstate file, Mercurial writes to a file with a @@ -654,17 +654,17 @@ Avoiding seeks - Critical to Mercurial's performance is the avoidance of + Critical to Mercurial's performance is the avoidance of seeks of the disk head, since any seek is far more expensive than even a comparatively large read operation. - This is why, for example, the dirstate is stored in a + This is why, for example, the dirstate is stored in a single file. If there were a dirstate file per directory that Mercurial tracked, the disk would seek once per directory. Instead, Mercurial reads the entire single dirstate file in one step. - Mercurial also uses a copy on write scheme + Mercurial also uses a copy on write scheme when cloning a repository on local storage. Instead of copying every revlog file from the old repository into the new repository, it makes a hard link, which is a @@ -675,7 +675,7 @@ one repository is using the file, so Mercurial makes a new copy of the file that is private to this repository. - A few revision control developers have pointed out that + A few revision control developers have pointed out that this idea of making a complete private copy of a file is not very efficient in its use of storage. While this is true, storage is cheap, and this method gives the highest @@ -689,21 +689,21 @@ Other contents of the dirstate - Because Mercurial doesn't force you to tell it when you're + Because Mercurial doesn't force you to tell it when you're modifying a file, it uses the dirstate to store some extra information so it can determine efficiently whether you have modified a file. For each file in the working directory, it stores the time that it last modified the file itself, and the size of the file at that time. - When you explicitly hg + When you explicitly hg add, hg remove, hg rename or hg copy files, Mercurial updates the dirstate so that it knows what to do with those files when you commit. - When Mercurial is checking the states of files in the + When Mercurial is checking the states of files in the working directory, it first checks a file's modification time. If that has not changed, the file must not have been modified. If the file's size has changed, the file must have been diff -r 28b5a5befb08 -r c838b3975bc6 en/ch04-daily.xml --- a/en/ch04-daily.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/ch04-daily.xml Thu Mar 19 21:18:52 2009 -0700 @@ -7,14 +7,14 @@ Telling Mercurial which files to track - Mercurial does not work with files in your repository unless + Mercurial does not work with files in your repository unless you tell it to manage them. The hg status command will tell you which files Mercurial doesn't know about; it uses a ? to display such files. - To tell Mercurial to track a file, use the To tell Mercurial to track a file, use the hg add command. Once you have added a file, the entry in the output of hg status for that file changes from @@ -23,7 +23,7 @@ &interaction.daily.files.add; - After you run a hg commit, + After you run a hg commit, the files that you added before the commit will no longer be listed in the output of hg status. The reason for this is that - Once you add a file, Mercurial doesn't do anything with it + Once you add a file, Mercurial doesn't do anything with it immediately. Instead, it will take a snapshot of the file's state the next time you perform a commit. It will then continue to track the changes you make to the file every time you commit, @@ -44,24 +44,24 @@ Explicit versus implicit file naming - A useful behaviour that Mercurial has is that if you pass + A useful behaviour that Mercurial has is that if you pass the name of a directory to a command, every Mercurial command will treat this as I want to operate on every file in this directory and its subdirectories. &interaction.daily.files.add-dir; - Notice in this example that Mercurial printed the names of + Notice in this example that Mercurial printed the names of the files it added, whereas it didn't do so when we added the file named a in the earlier example. - What's going on is that in the former case, we explicitly + What's going on is that in the former case, we explicitly named the file to add on the command line, so the assumption that Mercurial makes in such cases is that you know what you were doing, and it doesn't print any output. - However, when we imply the names of + However, when we imply the names of files by giving the name of a directory, Mercurial takes the extra step of printing the name of each file that it does something with. This makes it more clear what is happening, @@ -72,7 +72,7 @@ Aside: Mercurial tracks files, not directories - Mercurial does not track directory information. Instead, + Mercurial does not track directory information. Instead, it tracks the path to a file. Before creating a file, it first creates any missing directory components of the path. After it deletes a file, it then deletes any empty directories @@ -81,14 +81,14 @@ consequence: it is not possible to represent a completely empty directory in Mercurial. - Empty directories are rarely useful, and there are + Empty directories are rarely useful, and there are unintrusive workarounds that you can use to achieve an appropriate effect. The developers of Mercurial thus felt that the complexity that would be required to manage empty directories was not worth the limited benefit this feature would bring. - If you need an empty directory in your repository, there + If you need an empty directory in your repository, there are a few ways to achieve this. One is to create a directory, then hg add a hidden file to that directory. On Unix-like @@ -99,7 +99,7 @@ &interaction.daily.files.hidden; - Another way to tackle a need for an empty directory is to + Another way to tackle a need for an empty directory is to simply create one in your automated build scripts before they will need it. @@ -108,7 +108,7 @@ How to stop tracking a file - Once you decide that a file no longer belongs in your + Once you decide that a file no longer belongs in your repository, use the hg remove command; this deletes the file, and tells Mercurial to stop tracking it. A removed file is represented in the output of @@ -117,7 +117,7 @@ &interaction.daily.files.remove; - After you hg remove a file, + After you hg remove a file, Mercurial will no longer track changes to that file, even if you recreate a file with the same name in your working directory. If you do recreate a file with the same name and want Mercurial @@ -128,19 +128,19 @@ Removing a file does not affect its history - It is important to understand that removing a file has + It is important to understand that removing a file has only two effects. - It removes the current version of the file + It removes the current version of the file from the working directory. - It stops Mercurial from tracking changes to + It stops Mercurial from tracking changes to the file, from the time of the next commit. - Removing a file does not in any way + Removing a file does not in any way alter the history of the file. - If you update the working directory to a changeset in + If you update the working directory to a changeset in which a file that you have removed was still tracked, it will reappear in the working directory, with the contents it had when you committed that changeset. If you then update the @@ -152,7 +152,7 @@ Missing files - Mercurial considers a file that you have deleted, but not + Mercurial considers a file that you have deleted, but not used hg remove to delete, to be missing. A missing file is represented with ! in the @@ -162,7 +162,7 @@ &interaction.daily.files.missing; - If your repository contains a file that If your repository contains a file that hg status reports as missing, and you want the file to stay gone, you can run hg remove directory will often cause this symptom. - The user's The user's authorized_keys file may have a problem. If anyone other than the user owns or can write to that file, the ssh daemon will not trust or read it. - In the ideal world, you should be able to run the + In the ideal world, you should be able to run the following command successfully, and it should print exactly one line of output, the current date and time. ssh myserver date - If, on your server, you have login scripts that print + If, on your server, you have login scripts that print banners or other junk even when running non-interactive commands like this, you should fix them before you continue, so that they only print output if they're run interactively. @@ -778,43 +778,43 @@ shell is to check the return code from the command tty -s.) - Once you've verified that plain old ssh is working with + Once you've verified that plain old ssh is working with your server, the next step is to ensure that Mercurial runs on the server. The following command should run successfully: ssh myserver hg version - If you see an error message instead of normal If you see an error message instead of normal hg version output, this is usually because you haven't installed Mercurial to /usr/bin. Don't worry if this is the case; you don't need to do that. But you should check for a few possible problems. - Is Mercurial really installed on the server at + Is Mercurial really installed on the server at all? I know this sounds trivial, but it's worth checking! - Maybe your shell's search path (usually set + Maybe your shell's search path (usually set via the PATH environment variable) is simply misconfigured. - Perhaps your PATH environment + Perhaps your PATH environment variable is only being set to point to the location of the hg executable if the login session is interactive. This can happen if you're setting the path in the wrong shell login script. See your shell's documentation for details. - The PYTHONPATH environment + The PYTHONPATH environment variable may need to contain the path to the Mercurial Python modules. It might not be set at all; it could be incorrect; or it may be set only if the login is interactive. - If you can run hg version + If you can run hg version over an ssh connection, well done! You've got the server and client sorted out. You should now be able to use Mercurial to access repositories hosted by that username on that server. @@ -826,19 +826,19 @@ Using compression with ssh - Mercurial does not compress data when it uses the ssh + Mercurial does not compress data when it uses the ssh protocol, because the ssh protocol can transparently compress data. However, the default behaviour of ssh clients is not to request compression. - Over any network other than a fast LAN (even a wireless + Over any network other than a fast LAN (even a wireless network), using compression is likely to significantly speed up Mercurial's network operations. For example, over a WAN, someone measured compression as reducing the amount of time required to clone a particularly large repository from 51 minutes to 17 minutes. - Both ssh and plink + Both ssh and plink accept a option which turns on compression. You can easily edit your ~/.hgrc to enable compression for @@ -846,7 +846,7 @@ [ui] ssh = ssh -C - If you use ssh, you can configure it to + If you use ssh, you can configure it to always use compression when talking to your server. To do this, edit your .ssh/config file (which may not @@ -854,7 +854,7 @@ Host hg Compression yes HostName hg.example.com - This defines an alias, hg. When you + This defines an alias, hg. When you use it on the ssh command line or in a Mercurial ssh-protocol URL, it will cause ssh to connect to @@ -867,17 +867,17 @@ Serving over HTTP using CGI - Depending on how ambitious you are, configuring Mercurial's + Depending on how ambitious you are, configuring Mercurial's CGI interface can take anything from a few moments to several hours. - We'll begin with the simplest of examples, and work our way + We'll begin with the simplest of examples, and work our way towards a more complex configuration. Even for the most basic case, you're almost certainly going to need to read and modify your web server's configuration. - Configuring a web server is a complex, fiddly, and + 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 @@ -889,25 +889,25 @@ Web server configuration checklist - Before you continue, do take a few moments to check a few + Before you continue, do take a few moments to check a few aspects of your system's setup. - Do you have a web server installed at all? + 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. - If you have a web server installed, is it + If you have a web server installed, is it actually running? On most systems, even if one is present, it will be disabled by default. - Is your server configured to allow you to run + Is your server configured to allow you to run CGI programs in the directory where you plan to do so? Most servers default to explicitly disabling the ability to run CGI programs. - If you don't have a web server installed, and don't have + If you don't have a web server installed, and don't have substantial experience configuring Apache, you should consider using the lighttpd web server instead of Apache. Apache has a well-deserved reputation for baroque and @@ -922,7 +922,7 @@ Basic CGI configuration - On Unix-like systems, it's common for users to have a + On Unix-like systems, it's common for users to have a subdirectory named something like public_html in their home directory, from which they can serve up web pages. A file @@ -930,19 +930,19 @@ accessible at a URL of the form http://www.example.com/username/foo. - To get started, find the To get started, find the hgweb.cgi script that should be present in your Mercurial installation. If you can't quickly find a local copy on your system, simply download one from the master Mercurial repository at http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi. - You'll need to copy this script into your You'll need to copy this script into your public_html directory, and ensure that it's executable. cp .../hgweb.cgi ~/public_html chmod 755 ~/public_html/hgweb.cgi - The 755 argument to + The 755 argument to chmod is a little more general than just making the script executable: it ensures that the script is executable by anyone, and that group and @@ -959,7 +959,7 @@ What could <emphasis>possibly</emphasis> go wrong? - Once you've copied the CGI script into place, go into a + Once you've copied the CGI script into place, go into a web browser, and try to open the URL http://myhostname/ @@ -973,7 +973,7 @@ fresh installation of Apache, and a user account that I created specially to perform this exercise. - Your web server may have per-user directories disabled. + Your web server may have per-user directories disabled. If you're using Apache, search your config file for a UserDir directive. If there's none present, per-user directories will be disabled. If one @@ -984,7 +984,7 @@ directory, for example public_html. - Your file access permissions may be too restrictive. + Your file access permissions may be too restrictive. The web server must be able to traverse your home directory and directories under your public_html directory, and @@ -994,34 +994,34 @@ find ~/public_html -type d -print0 | xargs -0r chmod 755 find ~/public_html -type f -print0 | xargs -0r chmod 644 - The other possibility with permissions is that you might + The other possibility with permissions is that you might get a completely empty window when you try to load the script. In this case, it's likely that your access permissions are too permissive. Apache's suexec subsystem won't execute a script that's group- or world-writable, for example. - Your web server may be configured to disallow execution + Your web server may be configured to disallow execution of CGI programs in your per-user web directory. Here's Apache's default per-user configuration from my Fedora system. &ch06-apache-config.lst; - If you find a similar-looking + If you find a similar-looking Directory group in your Apache configuration, the directive to look at inside it is Options. Add ExecCGI to the end of this list if it's missing, and restart the web server. - If you find that Apache serves you the text of the CGI + If you find that Apache serves you the text of the CGI script instead of executing it, you may need to either uncomment (if already present) or add a directive like this. AddHandler cgi-script .cgi - The next possibility is that you might be served with a + The next possibility is that you might be served with a colourful Python backtrace claiming that it can't import a mercurial-related module. This is actually progress! The server is now capable of executing @@ -1035,7 +1035,7 @@ directions inside it to correctly set your PYTHONPATH environment variable. - Finally, you are certain to by + Finally, you are certain to by served with another colourful Python backtrace: this one will complain that it can't find /path/to/repository. Edit @@ -1045,7 +1045,7 @@ with the complete path to the repository you want to serve up. - At this point, when you try to reload the page, you + 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! @@ -1053,7 +1053,7 @@ Configuring lighttpd - To be exhaustive in my experiments, I tried configuring + To be exhaustive in my experiments, I tried configuring the increasingly popular lighttpd web server to serve the same repository as I described with Apache above. I had already overcome all of the problems I @@ -1063,7 +1063,7 @@ role="special">hgweb.cgi script was properly edited. - Once I had Apache running, getting + Once I had Apache running, getting lighttpd to serve the repository was a snap (in other words, even if you're trying to use lighttpd, you should read the Apache @@ -1075,7 +1075,7 @@ end of the config file, to configure these modules. userdir.path = "public_html" cgi.assign = (".cgi" => "" ) - With this done, lighttpd ran + With this done, lighttpd ran immediately for me. If I had configured lighttpd before Apache, I'd almost certainly have run into many of the same system-level @@ -1090,7 +1090,7 @@ Sharing multiple repositories with one CGI script - The hgweb.cgi script + The hgweb.cgi script only lets you publish a single repository, which is an annoying restriction. If you want to publish more than one without wracking yourself with multiple copies of the same @@ -1098,7 +1098,7 @@ the hgwebdir.cgi script. - The procedure to configure The procedure to configure hgwebdir.cgi is only a little more involved than for hgweb.cgi. First, you must obtain @@ -1106,12 +1106,12 @@ download a copy from the master Mercurial repository at http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi. - You'll need to copy this script into your You'll need to copy this script into your public_html directory, and ensure that it's executable. cp .../hgwebdir.cgi ~/public_html chmod 755 ~/public_html ~/public_html/hgwebdir.cgi - With basic configuration out of the way, try to visit + With basic configuration out of the way, try to visit http://myhostname/ myuser/hgwebdir.cgi in your browser. It should @@ -1120,7 +1120,7 @@ potential problems in section . - The hgwebdir.cgi + The hgwebdir.cgi script relies on an external configuration file. By default, it searches for a file named hgweb.config in the same directory @@ -1130,7 +1130,7 @@ ConfigParser web:configparser module. - The easiest way to configure The easiest way to configure hgwebdir.cgi is with a section named collections. This will automatically publish every repository under the @@ -1138,7 +1138,7 @@ this: [collections] /my/root = /my/root - Mercurial interprets this by looking at the directory name + Mercurial interprets this by looking at the directory name on the right hand side of the = sign; finding repositories in that directory hierarchy; and using the text on the @@ -1147,7 +1147,7 @@ remaining component of a path after this stripping has occurred is called a virtual path. - Given the example above, if we have a repository whose + Given the example above, if we have a repository whose local path is /my/root/this/repo, the CGI script will strip the leading http://myhostname/ myuser/hgwebdir.cgi/this/repo. - If we replace If we replace /my/root on the left hand side of this example with /my, then root/this/repo instead of this/repo. - The hgwebdir.cgi + The hgwebdir.cgi script will recursively search each directory listed in the collections section of its configuration file, but it will not recurse into the repositories it finds. - The collections mechanism makes it easy + The collections mechanism makes it easy to publish many repositories in a fire and forget manner. You only need to set up the CGI script and configuration file one time. Afterwards, you can @@ -1190,7 +1190,7 @@ Explicitly specifying which repositories to publish - In addition to the collections + In addition to the collections mechanism, the hgwebdir.cgi script allows you to publish a specific list of repositories. To do so, @@ -1199,20 +1199,20 @@ [paths] repo1 = /my/path/to/some/repo repo2 = /some/path/to/another - In this case, the virtual path (the component that will + In this case, the virtual path (the component that will appear in a URL) is on the left hand side of each definition, while the path to the repository is on the right. Notice that there does not need to be any relationship between the virtual path you choose and the location of a repository in your filesystem. - If you wish, you can use both the + If you wish, you can use both the collections and paths mechanisms simultaneously in a single configuration file. - If multiple repositories have the same virtual path, + If multiple repositories have the same virtual path, hgwebdir.cgi will not report an error. Instead, it will behave unpredictably. @@ -1223,12 +1223,12 @@ Downloading source archives - Mercurial's web interface lets users download an archive + Mercurial's web interface lets users download an archive of any revision. This archive will contain a snapshot of the working directory as of that revision, but it will not contain a copy of the repository data. - By default, this feature is not enabled. To enable it, + By default, this feature is not enabled. To enable it, you'll need to add an allow_archive item to the web section of your Web configuration options - Mercurial's web interfaces (the hg + Mercurial's web interfaces (the hg serve command, and the hgweb.cgi and hgwebdir.cgi scripts) have a @@ -1246,7 +1246,7 @@ belong in a section named web. - allow_archive: Determines which (if any) archive download mechanisms Mercurial supports. If you enable this feature, users of the web @@ -1255,30 +1255,30 @@ archive feature, this item must take the form of a sequence of words drawn from the list below. - bz2: A + bz2: A tar archive, compressed using bzip2 compression. This has the best compression ratio, but uses the most CPU time on the server. - gz: A + gz: A tar archive, compressed using gzip compression. - zip: A + zip: A zip archive, compressed using LZW compression. This format has the worst compression ratio, but is widely used in the Windows world. - If you provide an empty list, or don't have an + If you provide an empty list, or don't have an allow_archive entry at all, this feature will be disabled. Here is an example of how to enable all three supported formats. [web] allow_archive = bz2 gz zip - allowpull: + allowpull: Boolean. Determines whether the web interface allows remote users to hg pull and hg clone this @@ -1287,7 +1287,7 @@ human-oriented portion of the web interface is available. - contact: + contact: String. A free-form (but preferably brief) string identifying the person or group in charge of the repository. This often contains the name and email @@ -1298,21 +1298,21 @@ role="special">~/.hgrc if every repository has a single maintainer. - maxchanges: + maxchanges: Integer. The default maximum number of changesets to display in a single page of output. - maxfiles: + maxfiles: Integer. The default maximum number of modified files to display in a single page of output. - stripes: + stripes: Integer. If the web interface displays alternating stripes to make it easier to visually align rows when you are looking at a table, this number controls the number of rows in each stripe. - style: + style: Controls the template Mercurial uses to display the web interface. Mercurial ships with two web templates, named default and gitweb @@ -1324,12 +1324,12 @@ [web] style = gitweb - templates: + templates: Path. The directory in which to search for template files. By default, Mercurial searches in the directory in which it was installed. - If you are using If you are using hgwebdir.cgi, you can place a few configuration items in a web section of the Options specific to an individual repository - A few web configuration + A few web configuration items ought to be placed in a repository's local .hg/hgrc, rather than a user's or global ~/.hgrc. - description: String. A free-form (but preferably brief) string that describes the contents or purpose of the repository. - name: + name: String. The name to use for the repository in the web interface. This overrides the default name, which is the last component of the repository's path. @@ -1363,13 +1363,13 @@ Options specific to the <command role="hg-cmd">hg serve</command> command - Some of the items in the Some of the items in the web section of a ~/.hgrc file are only for use with the hg serve command. - accesslog: + accesslog: Path. The name of a file into which to write an access log. By default, the hg serve command writes this information to @@ -1377,22 +1377,22 @@ in the standard combined file format used by almost all web servers. - address: + address: String. The local address on which the server should listen for incoming connections. By default, the server listens on all addresses. - errorlog: + errorlog: Path. The name of a file into which to write an error log. By default, the hg serve command writes this information to standard error, not to a file. - ipv6: + ipv6: Boolean. Whether to use the IPv6 protocol. By default, IPv6 is not used. - port: + port: Integer. The TCP port number on which the server should listen. The default port number used is 8000. @@ -1403,14 +1403,14 @@ role="special">~/.hgrc file to add web items to - It is important to remember that a web server like + It is important to remember that a web server like Apache or lighttpd will run under a user ID that is different to yours. CGI scripts run by your server, such as hgweb.cgi, will usually also run under that user ID. - If you add web items to + If you add web items to your own personal ~/.hgrc file, CGI scripts won't read that ~/.hgrc file. Those settings will thus only affect the behaviour of the File names and pattern matching - Mercurial provides mechanisms that let you work with file + Mercurial provides mechanisms that let you work with file names in a consistent and expressive way. Simple file naming - Mercurial uses a unified piece of machinery under the + Mercurial uses a unified piece of machinery under the hood to handle file names. Every command behaves uniformly with respect to file names. The way in which commands work with file names is as follows. - If you explicitly name real files on the command line, + If you explicitly name real files on the command line, Mercurial works with exactly those files, as you would expect. &interaction.filenames.files; - When you provide a directory name, Mercurial will interpret + When you provide a directory name, Mercurial will interpret this as operate on every file in this directory and its subdirectories. Mercurial traverses the files and subdirectories in a directory in alphabetical order. When it @@ -32,18 +32,18 @@ Running commands without any file names - Mercurial's commands that work with file names have useful + Mercurial's commands that work with file names have useful default behaviours when you invoke them without providing any file names or patterns. What kind of behaviour you should expect depends on what the command does. Here are a few rules of thumb you can use to predict what a command is likely to do if you don't give it any names to work with. - Most commands will operate on the entire working + Most commands will operate on the entire working directory. This is what the hg add command does, for example. - If the command has effects that are difficult or + If the command has effects that are difficult or impossible to reverse, it will force you to explicitly provide at least one name or pattern (see below). This protects you from accidentally deleting files by running @@ -51,7 +51,7 @@ arguments, for example. - It's easy to work around these default behaviours if they + It's easy to work around these default behaviours if they don't suit you. If a command normally operates on the whole working directory, you can invoke it on just the current directory and its subdirectories by giving it the name @@ -59,7 +59,7 @@ &interaction.filenames.wdir-subdir; - Along the same lines, some commands normally print file + Along the same lines, some commands normally print file names relative to the root of the repository, even if you're invoking them from a subdirectory. Such a command will print file names relative to your subdirectory if you give it explicit @@ -75,21 +75,21 @@ Telling you what's going on - The hg add example in the + The hg add example in the preceding section illustrates something else that's helpful about Mercurial commands. If a command operates on a file that you didn't name explicitly on the command line, it will usually print the name of the file, so that you will not be surprised what's going on. - The principle here is of least + The principle here is of least surprise. 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 implicitly, because you provided no names, or a directory, or a pattern (see below), it's safest to tell you what it's doing. - For commands that behave this way, you can silence them + For commands that behave this way, you can silence them using the option. You can also get them to print the name of every file, even those you've named explicitly, using the , and the older changeset is good. - If you're having trouble remembering when a suitable + If you're having trouble remembering when a suitable good change was, so that you can tell hg bisect, you could do worse than testing changesets at random. Just remember to eliminate @@ -1055,7 +1055,7 @@ where another problem masks the bug (as I discussed above). - Even if you end up early by thousands of + Even if you end up early by thousands of changesets or months of history, you will only add a handful of tests to the total number that hg bisect must perform, thanks to its logarithmic diff -r 28b5a5befb08 -r c838b3975bc6 en/ch09-hook.xml --- a/en/ch09-hook.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/ch09-hook.xml Thu Mar 19 21:18:52 2009 -0700 @@ -4,12 +4,12 @@ Handling repository events with hooks - Mercurial offers a powerful mechanism to let you perform + Mercurial offers a powerful mechanism to let you perform automated actions in response to events that occur in a repository. In some cases, you can even control Mercurial's response to those events. - The name Mercurial uses for one of these actions is a + The name Mercurial uses for one of these actions is a hook. Hooks are called triggers in some revision control systems, but the two names refer to the same idea. @@ -17,49 +17,49 @@ An overview of hooks in Mercurial - Here is a brief list of the hooks that Mercurial supports. + Here is a brief list of the hooks that Mercurial supports. We will revisit each of these hooks in more detail later, in section . - changegroup: This + changegroup: This is run after a group of changesets has been brought into the repository from elsewhere. - commit: This is + commit: This is run after a new changeset has been created in the local repository. - incoming: This is + incoming: This is run once for each new changeset that is brought into the repository from elsewhere. Notice the difference from changegroup, which is run once per group of changesets brought in. - outgoing: This is + outgoing: This is run after a group of changesets has been transmitted from this repository. - prechangegroup: + prechangegroup: This is run before starting to bring a group of changesets into the repository. - precommit: + precommit: Controlling. This is run before starting a commit. - preoutgoing: + preoutgoing: Controlling. This is run before starting to transmit a group of changesets from this repository. - pretag: + pretag: Controlling. This is run before creating a tag. - pretxnchangegroup: Controlling. This is run after a group of changesets has been brought into the local repository from another, but before the transaction @@ -67,27 +67,27 @@ repository. - pretxncommit: + pretxncommit: Controlling. This is run after a new changeset has been created in the local repository, but before the transaction completes that will make it permanent. - preupdate: + preupdate: Controlling. This is run before starting an update or merge of the working directory. - tag: This is run + tag: This is run after a tag is created. - update: This is + update: This is run after an update or merge of the working directory has finished. - Each of the hooks whose description begins with the word + Each of the hooks whose description begins with the word Controlling has the ability to determine whether an activity can proceed. If the hook succeeds, the activity may proceed; if it fails, the activity is either not permitted or @@ -101,7 +101,7 @@ Hooks are run with your privileges - When you run a Mercurial command in a repository, and the + When you run a Mercurial command in a repository, and the command causes a hook to run, that hook runs on your system, under your user account, with @@ -112,14 +112,14 @@ it does. - In some cases, you may be exposed to hooks that you did + In some cases, you may be exposed to hooks that you did not install yourself. If you work with Mercurial on an unfamiliar system, Mercurial will run hooks defined in that system's global ~/.hgrc file. - If you are working with a repository owned by another + If you are working with a repository owned by another user, Mercurial can run hooks defined in that user's repository, but it will still run them as you. For example, if you hg pull @@ -131,7 +131,7 @@ - This only applies if you are pulling from a repository + This only applies if you are pulling from a repository on a local or network filesystem. If you're pulling over http or ssh, any outgoing hook will run under whatever account is executing the server @@ -139,7 +139,7 @@ - XXX To see what hooks are defined in a repository, use the + XXX To see what hooks are defined in a repository, use the hg config hooks command. If you are working in one repository, but talking to another that you do not own (e.g. using hg @@ -152,27 +152,27 @@ Hooks do not propagate - In Mercurial, hooks are not revision controlled, and do + In Mercurial, hooks are not revision controlled, and do not propagate when you clone, or pull from, a repository. The reason for this is simple: a hook is a completely arbitrary piece of executable code. It runs under your user identity, with your privilege level, on your machine. - It would be extremely reckless for any distributed + It would be extremely reckless for any distributed revision control system to implement revision-controlled hooks, as this would offer an easily exploitable way to subvert the accounts of users of the revision control system. - Since Mercurial does not propagate hooks, if you are + Since Mercurial does not propagate hooks, if you are collaborating with other people on a common project, you should not assume that they are using the same Mercurial hooks as you are, or that theirs are correctly configured. You should document the hooks you expect people to use. - In a corporate intranet, this is somewhat easier to + In a corporate intranet, this is somewhat easier to control, as you can for example provide a standard installation of Mercurial on an NFS filesystem, and use a site-wide ~/.hgrc file to define hooks that all users will @@ -183,12 +183,12 @@ Hooks can be overridden - Mercurial allows you to override a hook definition by + Mercurial allows you to override a hook definition by redefining the hook. You can disable it by setting its value to the empty string, or change its behaviour as you wish. - If you deploy a system- or site-wide If you deploy a system- or site-wide ~/.hgrc file that defines some hooks, you should thus understand that your users can disable or override those hooks. @@ -198,7 +198,7 @@ Ensuring that critical hooks are run - Sometimes you may want to enforce a policy that you do not + Sometimes you may want to enforce a policy that you do not want others to be able to work around. For example, you may have a requirement that every changeset must pass a rigorous set of tests. Defining this requirement via a hook in a @@ -207,13 +207,13 @@ can subvert it at will by overriding the hook. - Instead, you can set up your policies for use of Mercurial + Instead, you can set up your policies for use of Mercurial so that people are expected to propagate changes through a well-known canonical server that you have locked down and configured appropriately. - One way to do this is via a combination of social + One way to do this is via a combination of social engineering and technology. Set up a restricted-access account; users can push changes over the network to repositories managed by this account, but they cannot log into @@ -222,7 +222,7 @@ they want. - When someone pushes a changeset to the server that + When someone pushes a changeset to the server that everyone pulls from, the server will test the changeset before it accepts it as permanent, and reject it if it fails to pass the test suite. If people only pull changes from this @@ -236,19 +236,19 @@ Care with <literal>pretxn</literal> hooks in a shared-access repository - If you want to use hooks to do some automated work in a + If you want to use hooks to do some automated work in a repository that a number of people have shared access to, you need to be careful in how you do this. - Mercurial only locks a repository when it is writing to the + Mercurial only locks a repository when it is writing to the repository, and only the parts of Mercurial that write to the repository pay attention to locks. Write locks are necessary to prevent multiple simultaneous writers from scribbling on each other's work, corrupting the repository. - Because Mercurial is careful with the order in which it + Because Mercurial is careful with the order in which it reads and writes data, it does not need to acquire a lock when it wants to read data from the repository. The parts of Mercurial that read from the repository never pay attention to @@ -256,14 +256,14 @@ performance and concurrency. - With great performance comes a trade-off, though, one which + With great performance comes a trade-off, though, one which has the potential to cause you trouble unless you're aware of it. To describe this requires a little detail about how Mercurial adds changesets to a repository and reads those changes. - When Mercurial writes metadata, it + When Mercurial writes metadata, it writes it straight into the destination file. It writes file data first, then manifest data (which contains pointers to the new file data), then changelog data (which contains pointers to @@ -274,13 +274,13 @@ before the transaction began. - When Mercurial reads metadata, it reads + When Mercurial reads metadata, it reads the changelog first, then everything else. Since a reader will only access parts of the manifest or file metadata that it can see in the changelog, it can never see partially written data. - Some controlling hooks (Some controlling hooks (pretxncommit and pretxnchangegroup) run when a transaction is almost complete. All of the metadata has been @@ -288,7 +288,7 @@ cause the newly-written data to disappear. - If one of these hooks runs for long, it opens a window of + If one of these hooks runs for long, it opens a window of time during which a reader can see the metadata for changesets that are not yet permanent, and should not be thought of as really there. The longer the hook runs, the @@ -298,7 +298,7 @@ The problem illustrated - In principle, a good use for the In principle, a good use for the pretxnchangegroup hook would be to automatically build and test incoming changes before they are accepted into a central repository. This could let you @@ -309,7 +309,7 @@ potentially breaking their build. - The safest technological answer to this challenge is to + The safest technological answer to this challenge is to set up such a gatekeeper repository as unidirectional. Let it take changes pushed in from the outside, but do not allow anyone to pull @@ -321,7 +321,7 @@ can pull from. - In practice, putting a centralised bottleneck like this in + In practice, putting a centralised bottleneck like this in place is not often a good idea, and transaction visibility has nothing to do with the problem. As the size of a project&emdash;and the time it takes to build and @@ -332,7 +332,7 @@ involved. - An approach that scales better is to get people to build + An approach that scales better is to get people to build and test before they push, then run automated builds and tests centrally after a push, to be sure all is well. The advantage of this approach is that it does not @@ -345,18 +345,18 @@ A short tutorial on using hooks - It is easy to write a Mercurial hook. Let's start with a + It is easy to write a Mercurial hook. Let's start with a hook that runs when you finish a hg commit, and simply prints the hash of the changeset you just created. The hook is called commit. - All hooks follow the pattern in this example. + All hooks follow the pattern in this example. &interaction.hook.simple.init; - You add an entry to the You add an entry to the hooks section of your ~/.hgrc. On the left is the name of the event to trigger on; on the right is the action to take. As @@ -368,12 +368,12 @@ Performing multiple actions per event - Quite often, you will want to define more than one hook + Quite often, you will want to define more than one hook for a particular kind of event, as shown below. &interaction.hook.simple.ext; - Mercurial lets you do this by adding an + Mercurial lets you do this by adding an extension to the end of a hook's name. You extend a hook's name by giving the name of the hook, followed by a full stop (the @@ -384,7 +384,7 @@ commit event occurs. - To give a well-defined order of execution when there are + To give a well-defined order of execution when there are multiple hooks defined for an event, Mercurial sorts hooks by extension, and executes the hook commands in this sorted order. In the above example, it will execute @@ -393,7 +393,7 @@ before both. - It is a good idea to use a somewhat descriptive extension + It is a good idea to use a somewhat descriptive extension when you define a new hook. This will help you to remember what the hook was for. If the hook fails, you'll get an error message that contains the hook name and extension, so using a @@ -406,20 +406,20 @@ Controlling whether an activity can proceed - In our earlier examples, we used the In our earlier examples, we used the commit hook, which is run after a commit has completed. This is one of several Mercurial hooks that run after an activity finishes. Such hooks have no way of influencing the activity itself. - Mercurial defines a number of events that occur before an + Mercurial defines a number of events that occur before an activity starts; or after it starts, but before it finishes. Hooks that trigger on these events have the added ability to choose whether the activity can continue, or will abort. - The pretxncommit hook runs + The pretxncommit hook runs after a commit has all but completed. In other words, the metadata representing the changeset has been written out to disk, but the transaction has not yet been allowed to @@ -428,7 +428,7 @@ complete, or must be rolled back. - If the pretxncommit hook + If the pretxncommit hook exits with a status code of zero, the transaction is allowed to complete; the commit finishes; and the commit hook is run. If the The hook in the example above checks that a commit comment + The hook in the example above checks that a commit comment contains a bug ID. If it does, the commit can complete. If not, the commit is rolled back. @@ -450,7 +450,7 @@ Writing your own hooks - When you are writing a hook, you might find it useful to run + When you are writing a hook, you might find it useful to run Mercurial either with the option, or the verbose config item set to @@ -461,19 +461,19 @@ Choosing how your hook should run - You can write a hook either as a normal + You can write a hook either as a normal program&emdash;typically a shell script&emdash;or as a Python function that is executed within the Mercurial process. - Writing a hook as an external program has the advantage + Writing a hook as an external program has the advantage that it requires no knowledge of Mercurial's internals. You can call normal Mercurial commands to get any added information you need. The trade-off is that external hooks are slower than in-process hooks. - An in-process Python hook has complete access to the + An in-process Python hook has complete access to the Mercurial API, and does not shell out to another process, so it is inherently faster than an external hook. It is also easier to obtain much of the information @@ -481,7 +481,7 @@ running Mercurial commands. - If you are comfortable with Python, or require high + If you are comfortable with Python, or require high performance, writing your hooks in Python may be a good choice. However, when you have a straightforward hook to write and you don't need to care about performance (probably @@ -492,13 +492,13 @@ Hook parameters - Mercurial calls each hook with a set of well-defined + Mercurial calls each hook with a set of well-defined parameters. In Python, a parameter is passed as a keyword argument to your hook function. For an external program, a parameter is passed as an environment variable. - Whether your hook is written in Python or as a shell + Whether your hook is written in Python or as a shell script, the hook-specific parameter names and values will be the same. A boolean parameter will be represented as a boolean value in Python, but as the number 1 (for @@ -514,7 +514,7 @@ Hook return values and activity control - A hook that executes successfully must exit with a status + A hook that executes successfully must exit with a status of zero if external, or return boolean false if in-process. Failure is indicated with a non-zero exit status from an external hook, or an in-process hook returning boolean @@ -522,7 +522,7 @@ exception, the hook is considered to have failed. - For a hook that controls whether an activity can proceed, + For a hook that controls whether an activity can proceed, zero/false means allow, while non-zero/true/exception means deny. @@ -531,23 +531,23 @@ Writing an external hook - When you define an external hook in your When you define an external hook in your ~/.hgrc and the hook is run, its value is passed to your shell, which interprets it. This means that you can use normal shell constructs in the body of the hook. - An executable hook is always run with its current + An executable hook is always run with its current directory set to a repository's root directory. - Each hook parameter is passed in as an environment + Each hook parameter is passed in as an environment variable; the name is upper-cased, and prefixed with the string HG_. - With the exception of hook parameters, Mercurial does not + With the exception of hook parameters, Mercurial does not set or modify any environment variables when running a hook. This is useful to remember if you are writing a site-wide hook that may be run by a number of different users with differing @@ -560,7 +560,7 @@ Telling Mercurial to use an in-process hook - The ~/.hgrc syntax + The ~/.hgrc syntax for defining an in-process hook is slightly different than for an executable hook. The value of the hook must start with the text python:, and continue @@ -568,19 +568,19 @@ the hook's value. - The module in which a hook lives is automatically imported + The module in which a hook lives is automatically imported when a hook is run. So long as you have the module name and PYTHONPATH right, it should just work. - The following ~/.hgrc + The following ~/.hgrc example snippet illustrates the syntax and meaning of the notions we just described. [hooks] commit.example = python:mymodule.submodule.myhook - When Mercurial runs the commit.example + When Mercurial runs the commit.example hook, it imports mymodule.submodule, looks for the callable object named myhook, and calls it. @@ -590,12 +590,12 @@ Writing an in-process hook - The simplest in-process hook does nothing, but illustrates + The simplest in-process hook does nothing, but illustrates the basic shape of the hook API: def myhook(ui, repo, **kwargs): pass - The first argument to a Python hook is always a The first argument to a Python hook is always a ui object. The second is a repository object; at the moment, it is always an instance of Writing meaningful commit messages - It's hard to imagine a useful commit message being very + It's hard to imagine a useful commit message being very short. The simple pretxncommit hook of the example below will prevent you from committing a changeset with a message that is less than ten bytes long. @@ -627,7 +627,7 @@ Checking for trailing whitespace - An interesting use of a commit-related hook is to help you + An interesting use of a commit-related hook is to help you to write cleaner code. A simple example of cleaner code is the dictum that a change should not add any new lines of text that contain trailing @@ -638,7 +638,7 @@ prefer to get rid of it. - You can use either the You can use either the precommit or pretxncommit hook to tell whether you have a trailing whitespace problem. If you use the - Should you choose the Should you choose the pretxncommit hook, the check won't occur until just before the transaction for the commit completes. This will allow you to check for problems only the @@ -667,7 +667,7 @@ &interaction.hook.ws.simple; - In this example, we introduce a simple In this example, we introduce a simple pretxncommit hook that checks for trailing whitespace. This hook is short, but not very helpful. It exits with an error status if a change adds a @@ -678,7 +678,7 @@ trailing whitespace cause problems. - The above version is much more complex, but also more + The above version is much more complex, but also more useful. It parses a unified diff to see if any lines add trailing whitespace, and prints the name of the file and the line number of each such occurrence. Even better, if the @@ -692,7 +692,7 @@ &interaction.hook.ws.better; - As a final aside, note in the example above the use of + As a final aside, note in the example above the use of perl's in-place editing feature to get rid of trailing whitespace from a file. This is concise and useful enough that I will reproduce it here. @@ -704,7 +704,7 @@ Bundled hooks - Mercurial ships with several bundled hooks. You can find + Mercurial ships with several bundled hooks. You can find them in the hgext directory of a Mercurial source tree. If you are using a Mercurial binary package, the hooks will be located in the @@ -716,7 +716,7 @@ <literal role="hg-ext">acl</literal>&emdash;access control for parts of a repository - The acl extension lets + The acl extension lets you control which remote users are allowed to push changesets to a networked server. You can protect any portion of a repository (including the entire repo), so that a specific @@ -724,7 +724,7 @@ portion. - This extension implements access control based on the + This extension implements access control based on the identity of the user performing a push, not on who committed the changesets they're pushing. It makes sense to use this hook only if you @@ -737,7 +737,7 @@ Configuring the <literal role="hook">acl</literal> hook - In order to manage incoming changesets, the In order to manage incoming changesets, the acl hook must be used as a pretxnchangegroup hook. This lets it see which files are modified by each incoming @@ -747,18 +747,18 @@ [hooks] pretxnchangegroup.acl = python:hgext.acl.hook - The acl extension is + The acl extension is configured using three sections. - The acl section has + The acl section has only one entry, sources, which lists the sources of incoming changesets that the hook should pay attention to. You don't normally need to configure this section. - serve: + serve: Control incoming changesets that are arriving from a remote repository over http or ssh. This is the default value of sources, and @@ -766,23 +766,23 @@ configuration item. - pull: + pull: Control incoming changesets that are arriving via a pull from a local repository. - push: + push: Control incoming changesets that are arriving via a push from a local repository. - bundle: + bundle: Control incoming changesets that are arriving from another repository via a bundle. - The acl.allow + The acl.allow section controls the users that are allowed to add changesets to the repository. If this section is not present, all users that are not explicitly denied are @@ -791,13 +791,13 @@ that all users are denied). - The acl.deny + The acl.deny section determines which users are denied from adding changesets to the repository. If this section is not present or is empty, no users are denied. - The syntaxes for the The syntaxes for the acl.allow and acl.deny sections are identical. On the left of each entry is a glob pattern that @@ -805,7 +805,7 @@ repository; on the right, a user name. - In the following example, the user + In the following example, the user docwriter can only push changes to the docs subtree of the repository, while intern can push changes @@ -821,7 +821,7 @@ Testing and troubleshooting - If you want to test the If you want to test the acl hook, run it with Mercurial's debugging output enabled. Since you'll probably be running it on a server where it's not convenient (or sometimes @@ -832,7 +832,7 @@ [ui] debug = true - With this enabled, the With this enabled, the acl hook will print enough information to let you figure out why it is allowing or forbidding pushes from specific users. @@ -845,14 +845,14 @@ role="hg-ext">bugzilla&emdash;integration with Bugzilla - The bugzilla extension + The bugzilla extension adds a comment to a Bugzilla bug whenever it finds a reference to that bug ID in a commit comment. You can install this hook on a shared server, so that any time a remote user pushes changes to this server, the hook gets run. - It adds a comment to the bug that looks like this (you can + It adds a comment to the bug that looks like this (you can configure the contents of the comment&emdash;see below): Changeset aad8b264143a, made by Joe User @@ -861,19 +861,19 @@ http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a Changeset description: Fix bug 10483 by guarding against some NULL pointers - The value of this hook is that it automates the process of + The value of this hook is that it automates the process of updating a bug any time a changeset refers to it. If you configure the hook properly, it makes it easy for people to browse straight from a Bugzilla bug to a changeset that refers to that bug. - You can use the code in this hook as a starting point for + You can use the code in this hook as a starting point for some more exotic Bugzilla integration recipes. Here are a few possibilities: - Require that every changeset pushed to the + Require that every changeset pushed to the server have a valid bug ID in its commit comment. In this case, you'd want to configure the hook as a pretxncommit hook. This would @@ -881,7 +881,7 @@ IDs. - Allow incoming changesets to automatically + Allow incoming changesets to automatically modify the state of a bug, as well as simply adding a comment. For example, the hook could recognise the string fixed bug 31337 as @@ -894,7 +894,7 @@ Configuring the <literal role="hook">bugzilla</literal> hook - You should configure this hook in your server's + You should configure this hook in your server's ~/.hgrc as an incoming hook, for example as follows: @@ -902,25 +902,25 @@ [hooks] incoming.bugzilla = python:hgext.bugzilla.hook - Because of the specialised nature of this hook, and + Because of the specialised nature of this hook, and because Bugzilla was not written with this kind of integration in mind, configuring this hook is a somewhat involved process. - Before you begin, you must install the MySQL bindings + Before you begin, you must install the MySQL bindings for Python on the host(s) where you'll be running the hook. If this is not available as a binary package for your system, you can download it from web:mysql-python. - Configuration information for this hook lives in the + Configuration information for this hook lives in the bugzilla section of your ~/.hgrc. - version: The version of Bugzilla installed on the server. The database schema that Bugzilla uses changes occasionally, so this @@ -929,14 +929,14 @@ 2.16. - host: + host: The hostname of the MySQL server that stores your Bugzilla data. The database must be configured to allow connections from whatever host you are running the bugzilla hook on. - user: + user: The username with which to connect to the MySQL server. The database must be configured to allow this user to connect from whatever host you are running the - password: The MySQL password for the user you configured above. This is stored as plain text, so you should make sure that @@ -956,14 +956,14 @@ store this information. - db: + db: The name of the Bugzilla database on the MySQL server. The default value of this item is bugs, which is the standard name of the MySQL database where Bugzilla stores its data. - notify: If you want Bugzilla to send out a notification email to subscribers after this hook has added a comment to a bug, you will @@ -976,7 +976,7 @@ cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com - The Bugzilla + The Bugzilla processmail program expects to be given a bug ID (the hook replaces %s with the bug ID) @@ -993,7 +993,7 @@ Mapping committer names to Bugzilla user names - By default, the By default, the bugzilla hook tries to use the email address of a changeset's committer as the Bugzilla user name with which to update a bug. If this does not suit @@ -1002,14 +1002,14 @@ role="rc-usermap">usermap section. - Each item in the Each item in the usermap section contains an email address on the left, and a Bugzilla user name on the right. [usermap] jane.user@example.com = jane - You can either keep the You can either keep the usermap data in a normal ~/.hgrc, or tell the bugzilla hook to read the @@ -1025,7 +1025,7 @@ # regular hgrc file refers to external usermap file [bugzilla] usermap = /home/hg/repos/userdata/bugzilla-usermap.conf - While the usermap file that it + While the usermap file that it refers to might look like this: # bugzilla-usermap.conf - inside a hg repository @@ -1035,14 +1035,14 @@ Configuring the text that gets added to a bug - You can configure the text that this hook adds as a + You can configure the text that this hook adds as a comment; you specify it in the form of a Mercurial template. Several ~/.hgrc entries (still in the bugzilla section) control this behaviour. - strip: The number of + strip: The number of leading path elements to strip from a repository's path name to construct a partial path for a URL. For example, if the repositories on your server live under webroot. - template: The text of the + template: The text of the template to use. In addition to the usual changeset-related variables, this template can use hgweb (the value of the @@ -1066,7 +1066,7 @@ - In addition, you can add a In addition, you can add a baseurl item to the web section of your ~/.hgrc. The [web] baseurl = http://hg.domain.com/ - Here is an example set of Here is an example set of bugzilla hook config information. @@ -1088,13 +1088,13 @@ Testing and troubleshooting - The most common problems with configuring the The most common problems with configuring the bugzilla hook relate to running Bugzilla's processmail script and mapping committer names to user names. - Recall from section Recall from section above that the user that runs the Mercurial process on the server is also the one that will run the processmail @@ -1105,19 +1105,19 @@ under. - You can cause processmail to be run + You can cause processmail to be run with the suitable user's identity using the sudo command. Here is an example entry for a sudoers file. hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s - This allows the hg_user user to run a + This allows the hg_user user to run a processmail-wrapper program under the identity of httpd_user. - This indirection through a wrapper script is necessary, + This indirection through a wrapper script is necessary, because processmail expects to be run with its current directory set to wherever you installed Bugzilla; you can't specify that kind of constraint in a @@ -1126,18 +1126,18 @@ #!/bin/sh cd `dirname $0` && ./processmail "$1" nobody@example.com - It doesn't seem to matter what email address you pass to + It doesn't seem to matter what email address you pass to processmail. - If your usermap is + If your usermap is not set up correctly, users will see an error message from the bugzilla hook when they push changes to the server. The error message will look like this: cannot find bugzilla user id for john.q.public@example.com - What this means is that the committer's address, + What this means is that the committer's address, john.q.public@example.com, is not a valid Bugzilla user name, nor does it have an entry in your usermap that maps it to @@ -1150,7 +1150,7 @@ <literal role="hg-ext">notify</literal>&emdash;send email notifications - Although Mercurial's built-in web server provides RSS + Although Mercurial's built-in web server provides RSS feeds of changes in every repository, many people prefer to receive change notifications via email. The notify hook lets you send out @@ -1158,13 +1158,13 @@ arrive that those subscribers are interested in. - As with the bugzilla + As with the bugzilla hook, the notify hook is template-driven, so you can customise the contents of the notification messages that it sends. - By default, the notify + By default, the notify hook includes a diff of every changeset that it sends out; you can limit the size of the diff, or turn this feature off entirely. It is useful for letting subscribers review changes @@ -1175,7 +1175,7 @@ Configuring the <literal role="hg-ext">notify</literal> hook - You can set up the You can set up the notify hook to send one email message per incoming changeset, or one per incoming group of changesets (all those that arrived in a single pull or @@ -1187,12 +1187,12 @@ # send one email per change incoming.notify = python:hgext.notify.hook - Configuration information for this hook lives in the + Configuration information for this hook lives in the notify section of a ~/.hgrc file. - test: + test: By default, this hook does not send out email at all; instead, it prints the message that it would send. Set this item to @@ -1204,7 +1204,7 @@ notifications while you debug your configuration. - config: + config: The path to a configuration file that contains subscription information. This is kept separate from the main ~/.hgrc so @@ -1213,7 +1213,7 @@ subscriptions, and push the changes back to your server. - strip: + strip: The number of leading path separator characters to strip from a repository's path, when deciding whether a repository has subscribers. For example, if the @@ -1230,13 +1230,13 @@ match subscribers against that. - template: The template text to use when sending messages. This specifies both the contents of the message header and its body. - maxdiff: The maximum number of lines of diff data to append to the end of a message. If a diff is longer than this, it is @@ -1245,7 +1245,7 @@ emails. - sources: A list of sources of changesets to consider. This lets you limit notify to only sending @@ -1257,19 +1257,19 @@ - If you set the baseurl + If you set the baseurl item in the web section, you can use it in a template; it will be available as webroot. - Here is an example set of Here is an example set of notify configuration information. &ch10-notify-config.lst; - This will produce a message that looks like the + This will produce a message that looks like the following: @@ -1279,7 +1279,7 @@ Testing and troubleshooting - Do not forget that by default, the Do not forget that by default, the notify extension will not send any mail until you explicitly configure it to do so, by setting test to @@ -1296,11 +1296,11 @@ In-process hook execution - An in-process hook is called with arguments of the + An in-process hook is called with arguments of the following form: def myhook(ui, repo, **kwargs): pass - The ui parameter is a The ui parameter is a ui object. The repo parameter is a localrepository @@ -1309,38 +1309,38 @@ being invoked, with the following common features: - If a parameter is named + If a parameter is named node or parentN, it will contain a hexadecimal changeset ID. The empty string is used to represent null changeset ID instead of a string of zeroes. - If a parameter is named + If a parameter is named url, it will contain the URL of a remote repository, if that can be determined. - Boolean-valued parameters are represented as + Boolean-valued parameters are represented as Python bool objects. - An in-process hook is called without a change to the + An in-process hook is called without a change to the process's working directory (unlike external hooks, which are run in the root of the repository). It must not change the process's working directory, or it will cause any calls it makes into the Mercurial API to fail. - If a hook returns a boolean false value, it + If a hook returns a boolean false value, it is considered to have succeeded. If it returns a boolean true value or raises an exception, it is considered to have failed. A useful way to think of the calling convention is tell me if you fail. - Note that changeset IDs are passed into Python hooks as + Note that changeset IDs are passed into Python hooks as hexadecimal strings, not the binary hashes that Mercurial's APIs normally use. To convert a hash from hex to binary, use the bin function. @@ -1350,7 +1350,7 @@ External hook execution - An external hook is passed to the shell of the user + An external hook is passed to the shell of the user running Mercurial. Features of that shell, such as variable substitution and command redirection, are available. The hook is run in the root directory of the repository (unlike @@ -1358,7 +1358,7 @@ Mercurial was run in). - Hook parameters are passed to the hook as environment + Hook parameters are passed to the hook as environment variables. Each environment variable's name is converted in upper case and prefixed with the string HG_. For example, if the @@ -1367,7 +1367,7 @@ parameter will be HG_NODE. - A boolean parameter is represented as the string + A boolean parameter is represented as the string 1 for true, 0 for false. If an environment variable is named HG_NODE, @@ -1379,7 +1379,7 @@ URL of a remote repository, if that can be determined. - If a hook exits with a status of zero, it is considered to + If a hook exits with a status of zero, it is considered to have succeeded. If it exits with a non-zero status, it is considered to have failed. @@ -1388,7 +1388,7 @@ Finding out where changesets come from - A hook that involves the transfer of changesets between a + A hook that involves the transfer of changesets between a local repository and another may be able to find out information about the far side. Mercurial knows how changes are being transferred, @@ -1399,7 +1399,7 @@ Sources of changesets - Mercurial will tell a hook what means are, or were, used + Mercurial will tell a hook what means are, or were, used to transfer changesets between repositories. This is provided by Mercurial in a Python parameter named source, or an environment variable named @@ -1407,22 +1407,22 @@ - serve: Changesets are + serve: Changesets are transferred to or from a remote repository over http or ssh. - pull: Changesets are + pull: Changesets are being transferred via a pull from one repository into another. - push: Changesets are + push: Changesets are being transferred via a push from one repository into another. - bundle: Changesets are + bundle: Changesets are being transferred to or from a bundle. @@ -1432,7 +1432,7 @@ Where changes are going&emdash;remote repository URLs - When possible, Mercurial will tell a hook the location + When possible, Mercurial will tell a hook the location of the far side of an activity that transfers changeset data between repositories. This is provided by Mercurial in a Python parameter named @@ -1440,26 +1440,26 @@ HG_URL. - This information is not always known. If a hook is + This information is not always known. If a hook is invoked in a repository that is being served via http or ssh, Mercurial cannot tell where the remote repository is, but it may know where the client is connecting from. In such cases, the URL will take one of the following forms: - remote:ssh:1.2.3.4&emdash;remote + remote:ssh:1.2.3.4&emdash;remote ssh client, at the IP address 1.2.3.4. - remote:http:1.2.3.4&emdash;remote + remote:http:1.2.3.4&emdash;remote http client, at the IP address 1.2.3.4. If the client is using SSL, this will be of the form remote:https:1.2.3.4. - Empty&emdash;no information could be + Empty&emdash;no information could be discovered about the remote client. @@ -1474,7 +1474,7 @@ <literal role="hook">changegroup</literal>&emdash;after remote changesets added - This hook is run after a group of pre-existing changesets + This hook is run after a group of pre-existing changesets has been added to the repository, for example via a hg pull or hg unbundle. This hook is run once per operation @@ -1484,16 +1484,16 @@ arrive in a group. - Some possible uses for this hook include kicking off an + Some possible uses for this hook include kicking off an automated build or test of the added changesets, updating a bug database, or notifying subscribers that a repository contains new changes. - Parameters to this hook: + Parameters to this hook: - node: A changeset ID. The + node: A changeset ID. The changeset ID of the first changeset in the group that was added. All changesets between this and tip, inclusive, were added by a single @@ -1502,19 +1502,19 @@ role="hg-cmd">hg unbundle. - source: A string. The + source: A string. The source of these changes. See section for details. - url: A URL. The location + url: A URL. The location of the remote repository, if known. See section for more information. - See also: incoming (section + See also: incoming (section ), prechangegroup (section ), commit&emdash;after a new changeset is created - This hook is run after a new changeset has been created. + This hook is run after a new changeset has been created. - Parameters to this hook: + Parameters to this hook: - node: A changeset ID. The + node: A changeset ID. The changeset ID of the newly committed changeset. - parent1: A changeset ID. + parent1: A changeset ID. The changeset ID of the first parent of the newly committed changeset. - parent2: A changeset ID. + parent2: A changeset ID. The changeset ID of the second parent of the newly committed changeset. - See also: precommit + See also: precommit (section ), pretxncommit (section ) @@ -1559,40 +1559,40 @@ <literal role="hook">incoming</literal>&emdash;after one remote changeset is added - This hook is run after a pre-existing changeset has been + This hook is run after a pre-existing changeset has been added to the repository, for example via a hg push. If a group of changesets was added in a single operation, this hook is called once for each added changeset. - You can use this hook for the same purposes as the + You can use this hook for the same purposes as the changegroup hook (section ); it's simply more convenient sometimes to run a hook once per group of changesets, while other times it's handier once per changeset. - Parameters to this hook: + Parameters to this hook: - node: A changeset ID. The + node: A changeset ID. The ID of the newly added changeset. - source: A string. The + source: A string. The source of these changes. See section for details. - url: A URL. The location + url: A URL. The location of the remote repository, if known. See section for more information. - See also: changegroup + See also: changegroup (section ) prechangegroup (section ), outgoing&emdash;after changesets are propagated - This hook is run after a group of changesets has been + This hook is run after a group of changesets has been propagated out of this repository, for example by a hg push or hg bundle command. - One possible use for this hook is to notify administrators + One possible use for this hook is to notify administrators that changes have been pulled. - Parameters to this hook: + Parameters to this hook: - node: A changeset ID. The + node: A changeset ID. The changeset ID of the first changeset of the group that was sent. - source: A string. The + source: A string. The source of the of the operation (see section ). If a remote client pulled changes from this repository, @@ -1636,14 +1636,14 @@ client performed. - url: A URL. The location + url: A URL. The location of the remote repository, if known. See section for more information. - See also: preoutgoing + See also: preoutgoing (section ) @@ -1653,39 +1653,39 @@ role="hook">prechangegroup&emdash;before starting to add remote changesets - This controlling hook is run before Mercurial begins to + This controlling hook is run before Mercurial begins to add a group of changesets from another repository. - This hook does not have any information about the + This hook does not have any information about the changesets to be added, because it is run before transmission of those changesets is allowed to begin. If this hook fails, the changesets will not be transmitted. - One use for this hook is to prevent external changes from + One use for this hook is to prevent external changes from being added to a repository. For example, you could use this to freeze a server-hosted branch temporarily or permanently so that users cannot push to it, while still allowing a local administrator to modify the repository. - Parameters to this hook: + Parameters to this hook: - source: A string. The + source: A string. The source of these changes. See section for details. - url: A URL. The location + url: A URL. The location of the remote repository, if known. See section for more information. - See also: changegroup + See also: changegroup (section ), incoming (section ), , precommit&emdash;before starting to commit a changeset - This hook is run before Mercurial begins to commit a new + This hook is run before Mercurial begins to commit a new changeset. It is run before Mercurial has any of the metadata for the commit, such as the files to be committed, the commit message, or the commit date. - One use for this hook is to disable the ability to commit + One use for this hook is to disable the ability to commit new changesets, while still allowing incoming changesets. Another is to run a build or test, and only allow the commit to begin if the build or test succeeds. - Parameters to this hook: + Parameters to this hook: - parent1: A changeset ID. + parent1: A changeset ID. The changeset ID of the first parent of the working directory. - parent2: A changeset ID. + parent2: A changeset ID. The changeset ID of the second parent of the working directory. - If the commit proceeds, the parents of the working + If the commit proceeds, the parents of the working directory will become the parents of the new changeset. - See also: commit (section + See also: commit (section ), pretxncommit (section ) @@ -1738,18 +1738,18 @@ <literal role="hook">preoutgoing</literal>&emdash;before starting to propagate changesets - This hook is invoked before Mercurial knows the identities + This hook is invoked before Mercurial knows the identities of the changesets to be transmitted. - One use for this hook is to prevent changes from being + One use for this hook is to prevent changes from being transmitted to another repository. - Parameters to this hook: + Parameters to this hook: - source: A string. The + source: A string. The source of the operation that is attempting to obtain changes from this repository (see section ). See the documentation @@ -1760,14 +1760,14 @@ this parameter. - url: A URL. The location + url: A URL. The location of the remote repository, if known. See section for more information. - See also: outgoing (section + See also: outgoing (section ) @@ -1776,38 +1776,38 @@ <literal role="hook">pretag</literal>&emdash;before tagging a changeset - This controlling hook is run before a tag is created. If + This controlling hook is run before a tag is created. If the hook succeeds, creation of the tag proceeds. If the hook fails, the tag is not created. - Parameters to this hook: + Parameters to this hook: - local: A boolean. Whether + local: A boolean. Whether the tag is local to this repository instance (i.e. stored in .hg/localtags) or managed by Mercurial (stored in .hgtags). - node: A changeset ID. The + node: A changeset ID. The ID of the changeset to be tagged. - tag: A string. The name of + tag: A string. The name of the tag to be created. - If the tag to be created is revision-controlled, the + If the tag to be created is revision-controlled, the precommit and pretxncommit hooks (sections and ) will also be run. - See also: tag (section + See also: tag (section ) @@ -1816,7 +1816,7 @@ role="hook">pretxnchangegroup&emdash;before completing addition of remote changesets - This controlling hook is run before a + This controlling hook is run before a transaction&emdash;that manages the addition of a group of new changesets from outside the repository&emdash;completes. If the hook succeeds, the transaction completes, and all of the @@ -1825,28 +1825,28 @@ the changesets is erased. - This hook can access the metadata associated with the + This hook can access the metadata associated with the almost-added changesets, but it should not do anything permanent with this data. It must also not modify the working directory. - While this hook is running, if other Mercurial processes + While this hook is running, if other Mercurial processes access this repository, they will be able to see the almost-added changesets as if they are permanent. This may lead to race conditions if you do not take steps to avoid them. - This hook can be used to automatically vet a group of + This hook can be used to automatically vet a group of changesets. If the hook fails, all of the changesets are rejected when the transaction rolls back. - Parameters to this hook: + Parameters to this hook: - node: A changeset ID. The + node: A changeset ID. The changeset ID of the first changeset in the group that was added. All changesets between this and tip, @@ -1856,19 +1856,19 @@ role="hg-cmd">hg unbundle. - source: A string. The + source: A string. The source of these changes. See section for details. - url: A URL. The location + url: A URL. The location of the remote repository, if known. See section for more information. - See also: changegroup + See also: changegroup (section ), incoming (section ), pretxncommit&emdash;before completing commit of new changeset - This controlling hook is run before a + This controlling hook is run before a transaction&emdash;that manages a new commit&emdash;completes. If the hook succeeds, the transaction completes and the changeset becomes permanent within this repository. If the @@ -1889,37 +1889,37 @@ data is erased. - This hook can access the metadata associated with the + This hook can access the metadata associated with the almost-new changeset, but it should not do anything permanent with this data. It must also not modify the working directory. - While this hook is running, if other Mercurial processes + While this hook is running, if other Mercurial processes access this repository, they will be able to see the almost-new changeset as if it is permanent. This may lead to race conditions if you do not take steps to avoid them. - Parameters to this hook: + Parameters to this hook: - node: A changeset ID. The + node: A changeset ID. The changeset ID of the newly committed changeset. - parent1: A changeset ID. + parent1: A changeset ID. The changeset ID of the first parent of the newly committed changeset. - parent2: A changeset ID. + parent2: A changeset ID. The changeset ID of the second parent of the newly committed changeset. - See also: precommit + See also: precommit (section ) @@ -1928,30 +1928,30 @@ <literal role="hook">preupdate</literal>&emdash;before updating or merging working directory - This controlling hook is run before an update or merge of + This controlling hook is run before an update or merge of the working directory begins. It is run only if Mercurial's normal pre-update checks determine that the update or merge can proceed. If the hook succeeds, the update or merge may proceed; if it fails, the update or merge does not start. - Parameters to this hook: + Parameters to this hook: - parent1: A changeset ID. + parent1: A changeset ID. The ID of the parent that the working directory is to be updated to. If the working directory is being merged, it will not change this parent. - parent2: A changeset ID. + parent2: A changeset ID. Only set if the working directory is being merged. The ID of the revision that the working directory is being merged with. - See also: update (section + See also: update (section ) @@ -1960,13 +1960,13 @@ <literal role="hook">tag</literal>&emdash;after tagging a changeset - This hook is run after a tag has been created. + This hook is run after a tag has been created. - Parameters to this hook: + Parameters to this hook: - local: A boolean. Whether + local: A boolean. Whether the new tag is local to this repository instance (i.e. stored in .hg/localtags) or managed by @@ -1974,21 +1974,21 @@ role="special">.hgtags). - node: A changeset ID. The + node: A changeset ID. The ID of the changeset that was tagged. - tag: A string. The name of + tag: A string. The name of the tag that was created. - If the created tag is revision-controlled, the If the created tag is revision-controlled, the commit hook (section ) is run before this hook. - See also: pretag (section + See also: pretag (section ) @@ -1997,7 +1997,7 @@ <literal role="hook">update</literal>&emdash;after updating or merging working directory - This hook is run after an update or merge of the working + This hook is run after an update or merge of the working directory completes. Since a merge can fail (if the external hgmerge command fails to resolve conflicts in a file), this hook communicates whether the update or merge @@ -2005,24 +2005,24 @@ - error: A boolean. + error: A boolean. Indicates whether the update or merge completed successfully. - parent1: A changeset ID. + parent1: A changeset ID. The ID of the parent that the working directory was updated to. If the working directory was merged, it will not have changed this parent. - parent2: A changeset ID. + parent2: A changeset ID. Only set if the working directory was merged. The ID of the revision that the working directory was merged with. - See also: preupdate + See also: preupdate (section ) diff -r 28b5a5befb08 -r c838b3975bc6 en/ch10-template.xml --- a/en/ch10-template.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/ch10-template.xml Thu Mar 19 21:18:52 2009 -0700 @@ -4,7 +4,7 @@ Customising the output of Mercurial - Mercurial provides a powerful mechanism to let you control how + Mercurial provides a powerful mechanism to let you control how it displays information. The mechanism is based on templates. You can use templates to generate specific output for a single command, or to customise the entire appearance of the built-in web @@ -13,37 +13,37 @@ Using precanned output styles - Packaged with Mercurial are some output styles that you can + Packaged with Mercurial are some output styles that you can use immediately. A style is simply a precanned template that someone wrote and installed somewhere that Mercurial can find. - Before we take a look at Mercurial's bundled styles, let's + Before we take a look at Mercurial's bundled styles, let's review its normal output. &interaction.template.simple.normal; - This is somewhat informative, but it takes up a lot of + This is somewhat informative, but it takes up a lot of space&emdash;five lines of output per changeset. The compact style reduces this to three lines, presented in a sparse manner. &interaction.template.simple.compact; - The changelog style hints at the + The changelog style hints at the expressive power of Mercurial's templating engine. This style attempts to follow the GNU Project's changelog guidelinesweb:changelog. &interaction.template.simple.changelog; - You will not be shocked to learn that Mercurial's default + You will not be shocked to learn that Mercurial's default output style is named default. Setting a default style - You can modify the output style that Mercurial will use + You can modify the output style that Mercurial will use for every command by editing your ~/.hgrc file, naming the style you would prefer to use. @@ -51,7 +51,7 @@ [ui] style = compact - If you write a style of your own, you can use it by either + If you write a style of your own, you can use it by either providing the path to your style file, or copying your style file into a location where Mercurial can find it (typically the templates subdirectory of your @@ -62,14 +62,14 @@ Commands that support styles and templates - All of Mercurial's + All of Mercurial's log-like commands let you use styles and templates: hg incoming, hg log, hg outgoing, and hg tip. - As I write this manual, these are so far the only commands + As I write this manual, these are so far the only commands that support styles and templates. Since these are the most important commands that need customisable output, there has been little pressure from the Mercurial user community to add style @@ -79,22 +79,22 @@ The basics of templating - At its simplest, a Mercurial template is a piece of text. + At its simplest, a Mercurial template is a piece of text. Some of the text never changes, while other parts are expanded, or replaced with new text, when necessary. - Before we continue, let's look again at a simple example of + Before we continue, let's look again at a simple example of Mercurial's normal output. &interaction.template.simple.normal; - Now, let's run the same command, but using a template to + Now, let's run the same command, but using a template to change its output. &interaction.template.simple.simplest; - The example above illustrates the simplest possible + The example above illustrates the simplest possible template; it's just a piece of static text, printed once for each changeset. The option to the - Notice that the template string above ends with the text + Notice that the template string above ends with the text \n. This is an escape sequence, telling Mercurial to print a newline at the end of each template item. If you omit this @@ -110,13 +110,13 @@ section for more details of escape sequences. - A template that prints a fixed string of text all the time + A template that prints a fixed string of text all the time isn't very useful; let's try something a bit more complex. &interaction.template.simple.simplesub; - As you can see, the string + As you can see, the string {desc} in the template has been replaced in the output with the description of each changeset. Every time Mercurial finds text enclosed in curly @@ -131,21 +131,21 @@ Common template keywords - You can start writing simple templates immediately using the + You can start writing simple templates immediately using the keywords below. - author: String. The unmodified author of the changeset. - branches: String. The name of the branch on which the changeset was committed. Will be empty if the branch name was default. - date: + date: Date information. The date when the changeset was committed. This is not human-readable; you must pass it through a filter that will render it @@ -156,45 +156,45 @@ 1, 1970); the second is the offset of the committer's timezone from UTC, in seconds. - desc: + desc: String. The text of the changeset description. - files: List of strings. All files modified, added, or removed by this changeset. - file_adds: List of strings. Files added by this changeset. - file_dels: List of strings. Files removed by this changeset. - node: + node: String. The changeset identification hash, as a 40-character hexadecimal string. - parents: List of strings. The parents of the changeset. - rev: + rev: Integer. The repository-local changeset revision number. - tags: + tags: List of strings. Any tags associated with the changeset. - A few simple experiments will show us what to expect when we + A few simple experiments will show us what to expect when we use these keywords; you can see the results below. &interaction.template.simple.keywords; - As we noted above, the date keyword does not produce + As we noted above, the date keyword does not produce human-readable output, so we must treat it specially. This involves using a filter, about which more in section Escape sequences - Mercurial's templating engine recognises the most commonly + Mercurial's templating engine recognises the most commonly used escape sequences in strings. When it sees a backslash (\) character, it looks at the following character and substitutes the two characters with a single replacement, as described below. - \: + \: Backslash, \, ASCII 134. - \n: Newline, + \n: Newline, ASCII 12. - \r: Carriage + \r: Carriage return, ASCII 15. - \t: Tab, ASCII + \t: Tab, ASCII 11. - \v: Vertical + \v: Vertical tab, ASCII 13. - {: Open curly + {: Open curly brace, {, ASCII 173. - }: Close curly + }: Close curly brace, }, ASCII 175. - As indicated above, if you want the expansion of a template + As indicated above, if you want the expansion of a template to contain a literal \, {, or { character, you must escape @@ -248,35 +248,35 @@ Filtering keywords to change their results - Some of the results of template expansion are not + Some of the results of template expansion are not immediately easy to use. Mercurial lets you specify an optional chain of filters to modify the result of expanding a keyword. You have already seen a common filter, isodate, in action above, to make a date readable. - Below is a list of the most commonly used filters that + Below is a list of the most commonly used filters that Mercurial supports. While some filters can be applied to any text, others can only be used in specific circumstances. The name of each filter is followed first by an indication of where it can be used, then a description of its effect. - addbreaks: Any text. Add an XHTML <br/> tag before the end of every line except the last. For example, foo\nbar becomes foo<br/>\nbar. - age: date keyword. Render the age of the date, relative to the current time. Yields a string like 10 minutes. - basename: Any text, but most useful for the files keyword and its @@ -285,7 +285,7 @@ foo/bar/baz becomes baz. - date: date keyword. Render a date in a similar format to the Unix Mon Sep 04 15:13:13 2006 -0700. - domain: Any text, but most useful for the author keyword. Finds @@ -303,7 +303,7 @@ <bos@serpentine.com> becomes serpentine.com. - email: Any text, but most useful for the author keyword. Extract @@ -312,7 +312,7 @@ <bos@serpentine.com> becomes bos@serpentine.com. - escape: Any text. Replace the special XML/XHTML characters &, @@ -320,7 +320,7 @@ > with XML entities. - fill68: Any text. Wrap the text to fit in 68 columns. This is useful before you pass text through the - fill76: Any text. Wrap the text to fit in 76 columns. - firstline: Any text. Yield the first line of text, without any trailing newlines. - hgdate: date keyword. Render the date as a pair of readable numbers. Yields a string like 1157407993 25200. - isodate: date keyword. Render the date as a text string in ISO 8601 format. Yields a string like 2006-09-04 15:13:13 -0700. - obfuscate: Any text, but most useful for the author keyword. Yield @@ -359,7 +359,7 @@ helps to defeat some particularly stupid screen-scraping email harvesting spambots. - person: Any text, but most useful for the author keyword. Yield @@ -368,41 +368,41 @@ <bos@serpentine.com> becomes Bryan O'Sullivan. - rfc822date: date keyword. Render a date using the same format used in email headers. Yields a string like Mon, 04 Sep 2006 15:13:13 -0700. - short: Changeset hash. Yield the short form of a changeset hash, i.e. a 12-character hexadecimal string. - shortdate: date keyword. Render the year, month, and day of the date. Yields a string like 2006-09-04. - strip: + strip: Any text. Strip all leading and trailing whitespace from the string. - tabindent: Any text. Yield the text, with every line except the first starting with a tab character. - urlescape: Any text. Escape all characters that are considered special by URL parsers. For example, foo bar becomes foo%20bar. - user: Any text, but most useful for the author keyword. Return @@ -415,7 +415,7 @@ &interaction.template.simple.manyfilters; - If you try to apply a filter to a piece of data that it + If you try to apply a filter to a piece of data that it cannot process, Mercurial will fail and print a Python exception. For example, trying to run the output of the desc keyword into @@ -426,7 +426,7 @@ Combining filters - It is easy to combine filters to yield output in the form + It is easy to combine filters to yield output in the form you would like. The following chain of filters tidies up a description, then makes sure that it fits cleanly into 68 columns, then indents it by a further 8 characters (at least @@ -435,13 +435,13 @@ &interaction.template.simple.combine; - Note the use of \t (a + Note the use of \t (a tab character) in the template to force the first line to be indented; this is necessary since tabindent indents all lines except the first. - Keep in mind that the order of filters in a chain is + Keep in mind that the order of filters in a chain is significant. The first filter is applied to the result of the keyword; the second to the result of the first filter; and so on. For example, using fill68|tabindent @@ -454,12 +454,12 @@ From templates to styles - A command line template provides a quick and simple way to + A command line template provides a quick and simple way to format some output. Templates can become verbose, though, and it's useful to be able to give a template a name. A style file is a template with a name, stored in a file. - More than that, using a style file unlocks the power of + More than that, using a style file unlocks the power of Mercurial's templating engine in ways that are not possible using the command line option. @@ -467,11 +467,11 @@ The simplest of style files - Our simple style file contains just one line: + Our simple style file contains just one line: &interaction.template.simple.rev; - This tells Mercurial, if you're printing a + This tells Mercurial, if you're printing a changeset, use the text on the right as the template. @@ -479,38 +479,38 @@ Style file syntax - The syntax rules for a style file are simple. + The syntax rules for a style file are simple. - The file is processed one line at a + The file is processed one line at a time. - Leading and trailing white space are + Leading and trailing white space are ignored. - Empty lines are skipped. + Empty lines are skipped. - If a line starts with either of the characters + If a line starts with either of the characters # or ;, the entire line is treated as a comment, and skipped as if empty. - A line starts with a keyword. This must start + A line starts with a keyword. This must start with an alphabetic character or underscore, and can subsequently contain any alphanumeric character or underscore. (In regexp notation, a keyword must match [A-Za-z_][A-Za-z0-9_]*.) - The next element must be an + The next element must be an = character, which can be preceded or followed by an arbitrary amount of white space. - If the rest of the line starts and ends with + If the rest of the line starts and ends with matching quote characters (either single or double quote), it is treated as a template body. - If the rest of the line does + If the rest of the line does not start with a quote character, it is treated as the name of a file; the contents of this file will be read and used as a template body. @@ -521,7 +521,7 @@ Style files by example - To illustrate how to write a style file, we will construct a + To illustrate how to write a style file, we will construct a few by example. Rather than provide a complete style file and walk through it, we'll mirror the usual process of developing a style file by starting with something very simple, and walking @@ -530,40 +530,40 @@ Identifying mistakes in style files - If Mercurial encounters a problem in a style file you are + If Mercurial encounters a problem in a style file you are working on, it prints a terse error message that, once you figure out what it means, is actually quite useful. &interaction.template.svnstyle.syntax.input; - Notice that broken.style attempts to + Notice that broken.style attempts to define a changeset keyword, but forgets to give any content for it. When instructed to use this style file, Mercurial promptly complains. &interaction.template.svnstyle.syntax.error; - This error message looks intimidating, but it is not too + This error message looks intimidating, but it is not too hard to follow. - The first component is simply Mercurial's way + The first component is simply Mercurial's way of saying I am giving up. ___abort___: broken.style:1: parse error - Next comes the name of the style file that + Next comes the name of the style file that contains the error. abort: ___broken.style___:1: parse error - Following the file name is the line number + Following the file name is the line number where the error was encountered. abort: broken.style:___1___: parse error - Finally, a description of what went + Finally, a description of what went wrong. abort: broken.style:1: ___parse error___ - The description of the problem is not always + The description of the problem is not always clear (as in this case), but even when it is cryptic, it is almost always trivial to visually inspect the offending line in the style file and see what is wrong. @@ -573,32 +573,32 @@ Uniquely identifying a repository - If you would like to be able to identify a Mercurial + If you would like to be able to identify a Mercurial repository fairly uniquely using a short string as an identifier, you can use the first revision in the repository. &interaction.template.svnstyle.id; - This is not guaranteed to be unique, but it is + This is not guaranteed to be unique, but it is nevertheless useful in many cases. - It will not work in a completely empty + It will not work in a completely empty repository, because such a repository does not have a revision zero. - Neither will it work in the (extremely rare) + Neither will it work in the (extremely rare) case where a repository is a merge of two or more formerly independent repositories, and you still have those repositories around. - Here are some uses to which you could put this + Here are some uses to which you could put this identifier: - As a key into a table for a database that + As a key into a table for a database that manages repositories on a server. - As half of a {repository + As half of a {repository ID, revision ID} tuple. Save this information away when you run an automated build or other activity, so that you can replay @@ -609,29 +609,29 @@ Mimicking Subversion's output - Let's try to emulate the default output format used by + Let's try to emulate the default output format used by another revision control tool, Subversion. &interaction.template.svnstyle.short; - Since Subversion's output style is fairly simple, it is + Since Subversion's output style is fairly simple, it is easy to copy-and-paste a hunk of its output into a file, and replace the text produced above by Subversion with the template values we'd like to see expanded. &interaction.template.svnstyle.template; - There are a few small ways in which this template deviates + There are a few small ways in which this template deviates from the output produced by Subversion. - Subversion prints a readable + Subversion prints a readable date (the Wed, 27 Sep 2006 in the example output above) in parentheses. Mercurial's templating engine does not provide a way to display a date in this format without also printing the time and time zone. - We emulate Subversion's printing of + We emulate Subversion's printing of separator lines full of - characters by ending the template with such a line. We use the templating @@ -640,20 +640,20 @@ output (see below), thus achieving similar output to Subversion. - Subversion's output includes a count in the + Subversion's output includes a count in the header of the number of lines in the commit message. We cannot replicate this in Mercurial; the templating engine does not currently provide a filter that counts the number of lines the template generates. - It took me no more than a minute or two of work to replace + It took me no more than a minute or two of work to replace literal text from an example of Subversion's output with some keywords and filters to give the template above. The style file simply refers to the template. &interaction.template.svnstyle.style; - We could have included the text of the template file + We could have included the text of the template file directly in the style file by enclosing it in quotes and replacing the newlines with \n sequences, but it would diff -r 28b5a5befb08 -r c838b3975bc6 en/ch11-mq.xml --- a/en/ch11-mq.xml Thu Mar 19 20:54:12 2009 -0700 +++ b/en/ch11-mq.xml Thu Mar 19 21:18:52 2009 -0700 @@ -7,7 +7,7 @@ The patch management problem - Here is a common scenario: you need to install a software + Here is a common scenario: you need to install a software package from source, but you find a bug that you must fix in the source before you can start using the package. You make your changes, forget about the package for a while, and a few months @@ -17,24 +17,24 @@ the newer version. This is a tedious task, and it's easy to make mistakes. - This is a simple case of the patch management + This is a simple case of the patch management problem. You have an upstream source tree that you can't change; you need to make some local changes on top of the upstream tree; and you'd like to be able to keep those changes separate, so that you can apply them to newer versions of the upstream source. - The patch management problem arises in many situations. + The patch management problem arises in many situations. Probably the most visible is that a user of an open source software project will contribute a bug fix or new feature to the project's maintainers in the form of a patch. - Distributors of operating systems that include open source + Distributors of operating systems that include open source software often need to make changes to the packages they distribute so that they will build properly in their environments. - When you have few changes to maintain, it is easy to manage + When you have few changes to maintain, it is easy to manage a single patch using the standard diff and patch programs (see section for a discussion of these @@ -49,14 +49,14 @@ your fix in a subsequent release, you can simply drop that single patch when you're updating to the newer release. - Maintaining a single patch against an upstream tree is a + Maintaining a single patch against an upstream tree is a little tedious and error-prone, but not difficult. However, the complexity of the problem grows rapidly as the number of patches you have to maintain increases. With more than a tiny number of patches in hand, understanding which ones you have applied and maintaining them moves from messy to overwhelming. - Fortunately, Mercurial includes a powerful extension, + Fortunately, Mercurial includes a powerful extension, Mercurial Queues (or simply MQ), that massively simplifies the patch management problem. @@ -64,13 +64,13 @@ The prehistory of Mercurial Queues - During the late 1990s, several Linux kernel developers + During the late 1990s, several Linux kernel developers started to maintain patch series that modified the behaviour of the Linux kernel. Some of these series were focused on stability, some on feature coverage, and others were more speculative. - The sizes of these patch series grew rapidly. In 2002, + The sizes of these patch series grew rapidly. In 2002, Andrew Morton published some shell scripts he had been using to automate the task of managing his patch queues. Andrew was successfully using these scripts to manage hundreds (sometimes @@ -79,7 +79,7 @@ A patchwork quilt - In early 2003, Andreas Gruenbacher and Martin Quinson + In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the approach of Andrew's scripts and published a tool called patchwork quilt web:quilt, or simply quilt @@ -88,7 +88,7 @@ management, it rapidly gained a large following among open source software developers. - Quilt manages a stack of patches on + Quilt manages a stack of patches on top of a directory tree. To begin, you tell quilt to manage a directory tree, and tell it which files you want to manage; it stores away the names and contents of those files. To fix a @@ -96,14 +96,14 @@ files you need to fix, then refresh the patch. - The refresh step causes quilt to scan the directory tree; + The refresh step causes quilt to scan the directory tree; it updates the patch with all of the changes you have made. You can create another patch on top of the first, which will track the changes required to modify the tree from tree with one patch applied to tree with two patches applied. - You can change which patches are + You can change which patches are applied to the tree. If you pop a patch, the changes made by that patch will vanish from the directory tree. Quilt remembers which patches you have popped, though, @@ -115,7 +115,7 @@ any time, change both which patches are applied and what modifications those patches make. - Quilt knows nothing about revision control tools, so it + Quilt knows nothing about revision control tools, so it works equally well on top of an unpacked tarball or a Subversion working copy. @@ -123,17 +123,17 @@ From patchwork quilt to Mercurial Queues - In mid-2005, Chris Mason took the features of quilt and + In mid-2005, Chris Mason took the features of quilt and wrote an extension that he called Mercurial Queues, which added quilt-like behaviour to Mercurial. - The key difference between quilt and MQ is that quilt + The key difference between quilt and MQ is that quilt knows nothing about revision control systems, while MQ is integrated into Mercurial. Each patch that you push is represented as a Mercurial changeset. Pop a patch, and the changeset goes away. - Because quilt does not care about revision control tools, + Because quilt does not care about revision control tools, it is still a tremendously useful piece of software to know about for situations where you cannot use Mercurial and MQ. @@ -143,16 +143,16 @@ The huge advantage of MQ - I cannot overstate the value that MQ offers through the + I cannot overstate the value that MQ offers through the unification of patches and revision control. - A major reason that patches have persisted in the free + A major reason that patches have persisted in the free software and open source world&emdash;in spite of the availability of increasingly capable revision control tools over the years&emdash;is the agility they offer. - Traditional revision control tools make a permanent, + Traditional revision control tools make a permanent, irreversible record of everything that you do. While this has great value, it's also somewhat stifling. If you want to perform a wild-eyed experiment, you have to be careful in how @@ -160,7 +160,7 @@ misleading or destabilising&emdash;traces of your missteps and errors in the permanent revision record. - By contrast, MQ's marriage of distributed revision control + By contrast, MQ's marriage of distributed revision control with patches makes it much easier to isolate your work. Your patches live on top of normal revision history, and you can make them disappear or reappear at will. If you don't like a patch, @@ -168,7 +168,7 @@ simply fix it&emdash;as many times as you need to, until you have refined it into the form you desire. - As an example, the integration of patches with revision + As an example, the integration of patches with revision control makes understanding patches and debugging their effects&emdash;and their interplay with the code they're based on&emdash;enormously easier. Since every @@ -186,11 +186,11 @@ Understanding patches - Because MQ doesn't hide its patch-oriented nature, it is + Because MQ doesn't hide its patch-oriented nature, it is helpful to understand what patches are, and a little about the tools that work with them. - The traditional Unix diff command + The traditional Unix diff command compares two files, and prints a list of differences between them. The patch command understands these differences as modifications to make to a @@ -199,20 +199,20 @@ &interaction.mq.dodiff.diff; - The type of file that diff generates (and + The type of file that diff generates (and patch takes as input) is called a patch or a diff; there is no difference between a patch and a diff. (We'll use the term patch, since it's more commonly used.) - A patch file can start with arbitrary text; the + A patch file can start with arbitrary text; the patch command ignores this text, but MQ uses it as the commit message when creating changesets. To find the beginning of the patch content, patch searches for the first line that starts with the string diff -. - MQ works with unified diffs + MQ works with unified diffs (patch can accept several other diff formats, but MQ doesn't). A unified diff contains two kinds of header. The file header describes the file being @@ -220,7 +220,7 @@ patch sees a new file header, it looks for a file with that name to start modifying. - After the file header comes a series of + After the file header comes a series of hunks. Each hunk starts with a header; this identifies the range of line numbers within the file that the hunk should modify. Following the header, a hunk starts and @@ -232,7 +232,7 @@ runs the hunks together, with a few lines of context between modifications. - Each line of context begins with a space character. Within + Each line of context begins with a space character. Within the hunk, a line that begins with - means remove this line, while a line that begins with @@ -240,7 +240,7 @@ line. For example, a line that is modified is represented by one deletion and one insertion. - We will return to some of the more subtle aspects of patches + We will return to some of the more subtle aspects of patches later (in section ), but you should have enough information now to use MQ. @@ -249,7 +249,7 @@ Getting started with Mercurial Queues - Because MQ is implemented as an extension, you must + Because MQ is implemented as an extension, you must explicitly enable before you can use it. (You don't need to download anything; MQ ships with the standard Mercurial distribution.) To enable MQ, edit your [extensions] hgext.mq = - Once the extension is enabled, it will make a number of new + Once the extension is enabled, it will make a number of new commands available. To verify that the extension is working, you can use hg help to see if the qinit command is now @@ -267,14 +267,14 @@ &interaction.mq.qinit-help.help; - You can use MQ with any Mercurial + You can use MQ with any Mercurial repository, and its commands only operate within that repository. To get started, simply prepare the repository using the qinit command. &interaction.mq.tutorial.qinit; - This command creates an empty directory called This command creates an empty directory called .hg/patches, where MQ will keep its metadata. As with many Mercurial commands, the qinit command prints nothing @@ -283,18 +283,18 @@ Creating a new patch - To begin work on a new patch, use the To begin work on a new patch, use the qnew command. This command takes one argument, the name of the patch to create. - MQ will use this as the name of an actual file in the + MQ will use this as the name of an actual file in the .hg/patches directory, as you can see below. &interaction.mq.tutorial.qnew; - Also newly present in the Also newly present in the .hg/patches directory are two other files, series and status. The applied in this repository. - You may sometimes want to edit the You may sometimes want to edit the series file by hand; for example, to change the sequence in which some patches are applied. However, manually editing the - Once you have created your new patch, you can edit files + Once you have created your new patch, you can edit files in the working directory as you usually would. All of the normal Mercurial commands, such as hg diff and hg @@ -325,17 +325,17 @@ Refreshing a patch - When you reach a point where you want to save your work, + When you reach a point where you want to save your work, use the qrefresh command to update the patch you are working on. &interaction.mq.tutorial.qrefresh; - This command folds the changes you have made in the + This command folds the changes you have made in the working directory into your patch, and updates its corresponding changeset to contain those changes. - You can run qrefresh + You can run qrefresh as often as you like, so it's a good way to checkpoint your work. Refresh your patch at an opportune time; try an experiment; and if the experiment @@ -348,19 +348,19 @@ Stacking and tracking patches - Once you have finished working on a patch, or need to work + Once you have finished working on a patch, or need to work on another, you can use the qnew command again to create a new patch. Mercurial will apply this patch on top of your existing patch. &interaction.mq.tutorial.qnew2; - Notice that the patch contains the changes in our prior + Notice that the patch contains the changes in our prior patch as part of its context (you can see this more clearly in the output of hg annotate). - So far, with the exception of So far, with the exception of qnew and qrefresh, we've been careful to only use regular Mercurial commands. However, MQ provides @@ -370,13 +370,13 @@ &interaction.mq.tutorial.qseries; - The The qseries command lists every patch that MQ knows about in this repository, from oldest to newest (most recently created). - The The qapplied command lists every patch that MQ has applied in this repository, again from oldest to newest (most recently @@ -387,12 +387,12 @@ Manipulating the patch stack - The previous discussion implied that there must be a + The previous discussion implied that there must be a difference between known and applied patches, and there is. MQ can manage a patch without it being applied in the repository. - An applied patch has a corresponding + An applied patch has a corresponding changeset in the repository, and the effects of the patch and changeset are visible in the working directory. You can undo the application of a patch using the XXX - add textApplied and + add textApplied and unapplied patches in the MQ patch stack - You can reapply an unapplied, or popped, patch using the + You can reapply an unapplied, or popped, patch using the qpush command. This creates a new changeset to correspond to the patch, and the patch's changes once again become present in the working @@ -421,7 +421,7 @@ role="hg-ext-mq">qpush in action. &interaction.mq.tutorial.qpop; - Notice that once we have popped a patch or two patches, + Notice that once we have popped a patch or two patches, the output of qseries remains the same, while that of qapplied has changed. @@ -431,7 +431,7 @@ Pushing and popping many patches - While qpush and + While qpush and qpop each operate on a single patch at a time by default, you can push and pop many patches in one go. The command and MQ expect patches to have a strip count of one. - If you receive a patch from someone that you want to add + If you receive a patch from someone that you want to add to your patch queue, and the patch needs a strip count other than one, you cannot just qimport the patch, because @@ -583,14 +583,14 @@ Strategies for applying a patch - When patch applies a hunk, it tries a + When patch applies a hunk, it tries a handful of successively less accurate strategies to try to make the hunk apply. This falling-back technique often makes it possible to take a patch that was generated against an old version of a file, and apply it against a newer version of that file. - First, patch tries an exact match, + First, patch tries an exact match, where the line numbers, the context, and the text to be modified must apply exactly. If it cannot make an exact match, it tries to find an exact match for the context, @@ -599,7 +599,7 @@ applied, but at some offset from the original line number. - If a context-only match fails, patch + If a context-only match fails, patch removes the first and last lines of the context, and tries a reduced context-only match. If the hunk with reduced context succeeds, it prints a message saying that @@ -608,7 +608,7 @@ context patch had to trim before the patch applied). - When neither of these techniques works, + When neither of these techniques works, patch prints a message saying that the hunk in question was rejected. It saves rejected hunks (also simply called rejects) to a file with the same @@ -628,36 +628,36 @@ Some quirks of patch representation - There are a few useful things to know about how + There are a few useful things to know about how patch works with files. - This should already be obvious, but + This should already be obvious, but patch cannot handle binary files. - Neither does it care about the executable bit; + Neither does it care about the executable bit; it creates new files as readable, but not executable. - patch treats the removal of + patch treats the removal of a file as a diff between the file to be removed and the empty file. So your idea of I deleted this file looks like every line of this file was deleted in a patch. - It treats the addition of a file as a diff + It treats the addition of a file as a diff between the empty file and the file to be added. So in a patch, your idea of I added this file looks like every line of this file was added. - It treats a renamed file as the removal of the + It treats a renamed file as the removal of the old name, and the addition of the new name. This means that renamed files have a big footprint in patches. (Note also that Mercurial does not currently try to infer when files have been renamed or copied in a patch.) - patch cannot represent + patch cannot represent empty files, so you cannot use a patch to represent the notion I added this empty file to the tree. @@ -666,7 +666,7 @@ Beware the fuzz - While applying a hunk at an offset, or with a fuzz factor, + While applying a hunk at an offset, or with a fuzz factor, will often be completely successful, these inexact techniques naturally leave open the possibility of corrupting the patched file. The most common cases typically involve applying a @@ -676,7 +676,7 @@ fuzz factor, you should make sure that the modified files are correct afterwards. - It's often a good idea to refresh a patch that has applied + It's often a good idea to refresh a patch that has applied with an offset or fuzz factor; refreshing the patch generates new context information that will make it apply cleanly. I say often, not always, because @@ -691,30 +691,30 @@ Handling rejection - If qpush fails to + If qpush fails to apply a patch, it will print an error message and exit. If it has left .rej files behind, it is usually best to fix up the rejected hunks before you push more patches or do any further work. - If your patch used to apply cleanly, + If your patch used to apply cleanly, and no longer does because you've changed the underlying code that your patches are based on, Mercurial Queues can help; see section for details. - Unfortunately, there aren't any great techniques for + Unfortunately, there aren't any great techniques for dealing with rejected hunks. Most often, you'll need to view the .rej file and edit the target file, applying the rejected hunks by hand. - If you're feeling adventurous, Neil Brown, a Linux kernel + If you're feeling adventurous, Neil Brown, a Linux kernel hacker, wrote a tool called wiggle web:wiggle, which is more vigorous than patch in its attempts to make a patch apply. - Another Linux kernel hacker, Chris Mason (the author of + Another Linux kernel hacker, Chris Mason (the author of Mercurial Queues), wrote a similar tool called mpatch web:mpatch, which takes a simple approach to automating the application of @@ -723,21 +723,21 @@ reasons that a hunk may be rejected: - The context in the middle of a hunk has + The context in the middle of a hunk has changed. - A hunk is missing some context at the + A hunk is missing some context at the beginning or end. - A large hunk might apply better&emdash;either + A large hunk might apply better&emdash;either entirely or in part&emdash;if it was broken up into smaller hunks. - A hunk removes lines with slightly different + A hunk removes lines with slightly different content than those currently present in the file. - If you use wiggle or + If you use wiggle or mpatch, you should be doubly careful to check your results when you're done. In fact, mpatch enforces this method of @@ -751,7 +751,7 @@ Getting the best performance out of MQ - MQ is very efficient at handling a large number of patches. + 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 web:europython. I used as my data set the @@ -760,7 +760,7 @@ all 27,472 revisions between Linux 2.6.12-rc2 and Linux 2.6.17. - On my old, slow laptop, I was able to On my old, slow laptop, I was able to hg qpush all 1,738 patches in 3.5 minutes, and hg qpop @@ -771,11 +771,11 @@ (which made 22,779 lines of changes to 287 files) in 6.6 seconds. - Clearly, MQ is well suited to working in large trees, but + Clearly, MQ is well suited to working in large trees, but there are a few tricks you can use to get the best performance of it. - First of all, try to batch operations + First of all, try to batch operations together. Every time you run qpush or qpop, these commands scan the @@ -786,7 +786,7 @@ medium-sized tree (containing tens of thousands of files), it can take a second or more. - The qpush and The qpush and qpop commands allow you to push and pop multiple patches at a time. You can identify the destination patch that you want to end up at. @@ -796,7 +796,7 @@ role="hg-ext-mq">qpop to a destination, MQ will pop patches until the destination patch is at the top. - You can identify a destination patch using either the name + You can identify a destination patch using either the name of the patch, or by number. If you use numeric addressing, patches are counted from zero; this means that the first patch is zero, the second is one, and so on. @@ -806,7 +806,7 @@ Updating your patches when the underlying code changes - It's common to have a stack of patches on top of an + It's common to have a stack of patches on top of an underlying repository that you don't modify directly. If you're working on changes to third-party code, or on a feature that is taking longer to develop than the rate of change of the code @@ -815,7 +815,7 @@ This is called rebasing your patch series. - The simplest way to do this is to hg + The simplest way to do this is to hg qpop your patches, then hg pull changes into the underlying @@ -827,26 +827,26 @@ affected patch, and continue pushing until you have fixed your entire stack. - This approach is easy to use and works well if you don't + This approach is easy to use and works well if you don't expect changes to the underlying code to affect how well your patches apply. If your patch stack touches code that is modified frequently or invasively in the underlying repository, however, fixing up rejected hunks by hand quickly becomes tiresome. - It's possible to partially automate the rebasing process. + It's possible to partially automate the rebasing process. If your patches apply cleanly against some revision of the underlying repo, MQ can use this information to help you to resolve conflicts between your patches and a different revision. - The process is a little involved. + The process is a little involved. - To begin, hg qpush + To begin, hg qpush -a all of your patches on top of the revision where you know that they apply cleanly. - Save a backup copy of your patch directory using + Save a backup copy of your patch directory using hg qsave . @@ -860,17 +860,17 @@ states of the series and status files. - Use hg pull to + Use hg pull to bring new changes into the underlying repository. (Don't run hg pull -u; see below for why.) - Update to the new tip revision, using Update to the new tip revision, using hg update to override the patches you have pushed. - Merge all patches using hg qpush -m + Merge all patches using hg qpush -m -a. The option to qpush tells MQ to @@ -878,7 +878,7 @@ apply. - During the hg qpush - When you finish resolving the effects of a patch, MQ + When you finish resolving the effects of a patch, MQ refreshes your patch based on the result of the merge. - At the end of this process, your repository will have one + At the end of this process, your repository will have one extra head from the old patch queue, and a copy of the old patch queue will be in .hg/patches.N. You can remove the @@ -905,26 +905,26 @@ Identifying patches - MQ commands that work with patches let you refer to a patch + MQ commands that work with patches let you refer to a patch either by using its name or by a number. By name is obvious enough; pass the name foo.patch to qpush, for example, and it will push patches until foo.patch is applied. - As a shortcut, you can refer to a patch using both a name + As a shortcut, you can refer to a patch using both a name and a numeric offset; foo.patch-2 means two patches before foo.patch, while bar.patch+4 means four patches after bar.patch. - Referring to a patch by index isn't much different. The + Referring to a patch by index isn't much different. The first patch printed in the output of qseries is patch zero (yes, it's one of those start-at-zero counting systems); the second is patch one; and so on. - MQ also makes it easy to work with patches when you are + MQ also makes it easy to work with patches when you are using normal Mercurial commands. Every command that accepts a changeset ID will also accept the name of an applied patch. MQ augments the tags normally in the repository with an eponymous @@ -934,28 +934,28 @@ the bottom-most and topmost applied patches, respectively. - These additions to Mercurial's normal tagging capabilities + These additions to Mercurial's normal tagging capabilities make dealing with patches even more of a breeze. - Want to patchbomb a mailing list with your + Want to patchbomb a mailing list with your latest series of changes? hg email qbase:qtip - (Don't know what patchbombing is? See + (Don't know what patchbombing is? See section .) - Need to see all of the patches since + Need to see all of the patches since foo.patch that have touched files in a subdirectory of your tree? hg log -r foo.patch:qtip subdir - Because MQ makes the names of patches available to the rest + Because MQ makes the names of patches available to the rest of Mercurial through its normal internal tag machinery, you don't need to type in the entire name of a patch when you want to identify it by name. - Another nice consequence of representing patch names as tags + Another nice consequence of representing patch names as tags is that when you run the hg log command, it will display a patch's name as a tag, simply as part of its normal output. This makes it easy to visually @@ -970,12 +970,12 @@ Useful things to know about - There are a number of aspects of MQ usage that don't fit + There are a number of aspects of MQ usage that don't fit tidily into sections of their own, but that are good to know. Here they are, in one place. - Normally, when you Normally, when you qpop a patch and qpush it again, the changeset that represents the patch after the pop/push will have a @@ -984,7 +984,7 @@ linkend="sec:mqref:cmd:qpush"/> for information as to why this is. - It's not a good idea to It's not a good idea to hg merge changes from another branch with a patch changeset, at least if you want to maintain the patchiness of that changeset and @@ -997,13 +997,13 @@ Managing patches in a repository - Because MQ's Because MQ's .hg/patches directory resides outside a Mercurial repository's working directory, the underlying Mercurial repository knows nothing about the management or presence of patches. - This presents the interesting possibility of managing the + This presents the interesting possibility of managing the contents of the patch directory as a Mercurial repository in its own right. This can be a useful way to work. For example, you can work on a patch for a while, roll back to that version of the patch later on. - You can then share different versions of the same patch + You can then share different versions of the same patch stack among multiple underlying repositories. I use this when I am developing a Linux kernel feature. I have a pristine copy of my kernel sources for each of several CPU architectures, and a @@ -1022,7 +1022,7 @@ associated with that kernel tree, pop and push all of my patches, and build and test that kernel. - Managing patches in a repository makes it possible for + Managing patches in a repository makes it possible for multiple developers to work on the same patch series without colliding with each other, all on top of an underlying source base that they may or may not control. @@ -1030,7 +1030,7 @@ MQ support for patch repositories - MQ helps you to work with the MQ helps you to work with the .hg/patches directory as a repository; when you prepare a repository for working with patches using qinit, you @@ -1040,7 +1040,7 @@ Mercurial repository. - If you forget to use the option, you can simply go into the .hg/patches directory at any @@ -1049,25 +1049,25 @@ role="special">status file to the .hgignore file, though - (hg qinit - As a convenience, if MQ notices that the As a convenience, if MQ notices that the .hg/patches directory is a repository, it will automatically hg add every patch that you create and import. - MQ provides a shortcut command, MQ provides a shortcut command, qcommit, that runs hg commit in the .hg/patches directory. This saves some bothersome typing. - Finally, as a convenience to manage the patch directory, + Finally, as a convenience to manage the patch directory, you can define the alias mq on Unix systems. For example, on Linux systems using the bash shell, you can include the following @@ -1076,17 +1076,17 @@ alias mq=`hg -R $(hg root)/.hg/patches' - You can then issue commands of the form mq + You can then issue commands of the form mq pull from the main repository. A few things to watch out for - MQ's support for working with a repository full of patches + MQ's support for working with a repository full of patches is limited in a few small respects. - MQ cannot automatically detect changes that you make to + MQ cannot automatically detect changes that you make to the patch directory. If you hg pull, manually edit, or hg update changes to patches or the Third party tools for working with patches - Once you've been working with patches for a while, you'll + Once you've been working with patches for a while, you'll find yourself hungry for tools that will help you to understand and manipulate the patches you're dealing with. - The diffstat command + The diffstat command web:diffstat generates a histogram of the modifications made to each file in a patch. It provides a good way to get a sense of a patch&emdash;which files @@ -1122,7 +1122,7 @@ &interaction.mq.tools.tools; - The patchutils package + The patchutils package web:patchutils is invaluable. It provides a set of small utilities that follow the Unix philosophy; each does one useful thing with a patch. @@ -1140,13 +1140,13 @@ Good ways to work with patches - Whether you are working on a patch series to submit to a + Whether you are working on a patch series to submit to a free software or open source project, or a series that you intend to treat as a sequence of regular changesets when you're done, you can use some simple techniques to keep your work well organised. - Give your patches descriptive names. A good name for a + Give your patches descriptive names. A good name for a patch might be rework-device-alloc.patch, because it will immediately give you a hint what the purpose of the patch is. Long names shouldn't be a problem; you won't be @@ -1158,7 +1158,7 @@ to work with, or if you are juggling a number of different tasks and your patches only get a fraction of your attention. - Be aware of what patch you're working on. Use the Be aware of what patch you're working on. Use the qtop command and skim over the text of your patches frequently&emdash;for example, using hg tip option), this will constrain the revisions sent. - It's perfectly safe to run the It's perfectly safe to run the email command without the names of the people you want to send to: if you do this, it will just prompt you for those values interactively. (If you're @@ -469,12 +469,12 @@ readline-style editing capabilities when entering those headers, too, which is useful.) - When you are sending just one revision, the When you are sending just one revision, the email command will by default use the first line of the changeset description as the subject of the single email message it sends. - If you send multiple revisions, the If you send multiple revisions, the email command will usually send one message per changeset. It will preface the series with an introductory message, in which you should describe the @@ -483,25 +483,25 @@ Changing the behaviour of patchbombs - Not every project has exactly the same conventions for + Not every project has exactly the same conventions for sending changes in email; the patchbomb extension tries to accommodate a number of variations through command line options. - You can write a subject for the introductory + You can write a subject for the introductory message on the command line using the option. This takes one argument, the text of the subject to use. - To change the email address from which the + To change the email address from which the messages originate, use the option. This takes one argument, the email address to use. - The default behaviour is to send unified diffs + The default behaviour is to send unified diffs (see section for a description of the format), one per message. You can send a binary bundle @@ -509,13 +509,13 @@ role="hg-ext-patchbomb-cmd-email-opt">hg -b option. - Unified diffs are normally prefaced with a + Unified diffs are normally prefaced with a metadata header. You can omit this, and send unadorned diffs, with the option. - Diffs are normally sent inline, + Diffs are normally sent inline, in the same body part as the description of a patch. This makes it easiest for the largest number of readers to quote and respond to parts of a diff, as some mail clients @@ -525,14 +525,14 @@ role="hg-ext-patchbomb-cmd-email-opt">hg -a option. - Instead of sending mail messages, you can + Instead of sending mail messages, you can write them to an mbox-format mail folder using the option. That option takes one argument, the name of the file to write to. - If you would like to add a + If you would like to add a diffstat-format summary to each patch, and one to the introductory message, use the