Mercurial > hgbook
changeset 666:8fcd44708f41
Uncomment all the mangled interaction examples.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Mon, 09 Mar 2009 23:22:09 -0700 |
| parents | 27043f385f3f |
| children | a8160b8a4f15 |
| files | en/ch03-tour-merge.xml en/ch05-daily.xml en/ch06-collab.xml en/ch07-filenames.xml en/ch08-branch.xml en/ch09-undo.xml en/ch10-hook.xml en/ch11-template.xml en/ch12-mq.xml en/ch13-mq-collab.xml en/ch14-hgext.xml |
| diffstat | 11 files changed, 638 insertions(+), 388 deletions(-) [+] |
line wrap: on
line diff
--- a/en/ch03-tour-merge.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch03-tour-merge.xml Mon Mar 09 23:22:09 2009 -0700 @@ -31,7 +31,7 @@ begin by cloning yet another repository (see how often they spring up?) and making a change in it.</para> - <!-- &interaction.tour.merge.clone; --> + &interaction.tour.merge.clone; <para>We should now have two copies of <filename>hello.c</filename> with different contents. The @@ -39,7 +39,7 @@ illustrated in figure <xref linkend="fig:tour-merge:sep-repos"/>.</para> - <!-- &interaction.tour.merge.cat; --> + &interaction.tour.merge.cat; <informalfigure id="fig:tour-merge:sep-repos"> <mediaobject> @@ -56,7 +56,7 @@ class="directory">my-hello</filename> repository will have no effect on the working directory.</para> - <!-- &interaction.tour.merge.pull; --> + &interaction.tour.merge.pull; <para>However, the <command role="hg-cmd">hg pull</command> command says something about <quote>heads</quote>.</para> @@ -96,7 +96,7 @@ We can view the heads in a repository using the <command role="hg-cmd">hg heads</command> command.</para> - <!-- &interaction.tour.merge.heads; --> + &interaction.tour.merge.heads; </sect2> <sect2> @@ -106,7 +106,7 @@ role="hg-cmd">hg update</command> command to update to the new tip?</para> - <!-- &interaction.tour.merge.update; --> + &interaction.tour.merge.update; <para>Mercurial is telling us that the <command role="hg-cmd">hg update</command> command won't do a merge; it won't update @@ -115,7 +115,7 @@ <command role="hg-cmd">hg merge</command> command to merge the two heads.</para> - <!-- &interaction.tour.merge.merge; --> + &interaction.tour.merge.merge; <informalfigure id="fig:tour-merge:merge"> @@ -133,7 +133,7 @@ parents</command> and the contents of <filename>hello.c</filename>.</para> - <!-- &interaction.tour.merge.parents; --> + &interaction.tour.merge.parents; </sect2> <sect2> @@ -144,14 +144,14 @@ role="hg-cmd">hg commit</command> the results of the merge.</para> - <!-- &interaction.tour.merge.commit; --> + &interaction.tour.merge.commit; <para>We now have a new tip revision; notice that it has <emphasis>both</emphasis> of our former heads as its parents. These are the same revisions that were previously displayed by <command role="hg-cmd">hg parents</command>.</para> - <!-- &interaction.tour.merge.tip; --> + &interaction.tour.merge.tip; <para>In figure <xref linkend="fig:tour-merge:merge"/>, you can see a @@ -273,12 +273,12 @@ above. Let's begin by creating a repository with a base version of our document.</para> - <!-- &interaction.tour-merge-conflict.wife; --> + &interaction.tour-merge-conflict.wife; <para>We'll clone the repository and make a change to the file.</para> - <!-- &interaction.tour-merge-conflict.cousin; --> + &interaction.tour-merge-conflict.cousin; <para>And another clone, to simulate someone else making a change to the file. (This hints at the idea that it's not all @@ -286,13 +286,13 @@ separate repositories, and indeed to find and resolve conflicts while doing so.)</para> - <!-- &interaction.tour-merge-conflict.son; --> + &interaction.tour-merge-conflict.son; <para>Having created two different versions of the file, we'll set up an environment suitable for running our merge.</para> - <!-- &interaction.tour-merge-conflict.pull; --> + &interaction.tour-merge-conflict.pull; <para>In this example, I won't use Mercurial's normal <command>hgmerge</command> program to do the merge, because it @@ -307,7 +307,7 @@ <para><emphasis role="bold">XXX FIX THIS EXAMPLE.</emphasis></para> - <!-- &interaction.tour-merge-conflict.merge; --> + &interaction.tour-merge-conflict.merge; <para>Because <command>merge</command> can't resolve the conflicting changes, it leaves <emphasis>merge @@ -326,7 +326,7 @@ prevent us from <quote>fixing up</quote> the affected files ourselves, and committing the results of our merge:</para> - <!-- &interaction.tour-merge-conflict.commit; --> + &interaction.tour-merge-conflict.commit; </sect2> </sect1>
--- a/en/ch05-daily.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch05-daily.xml Mon Mar 09 23:22:09 2009 -0700 @@ -18,8 +18,9 @@ file, the entry in the output of <command role="hg-cmd">hg status</command> for that file changes from <quote><literal>?</literal></quote> to - <quote><literal>A</literal></quote>. <!-- - &interaction.daily.files.add; --></para> + <quote><literal>A</literal></quote>.</para> + + &interaction.daily.files.add; <para>After you run a <command role="hg-cmd">hg commit</command>, the files that you added before the commit will no longer be @@ -45,11 +46,14 @@ <para>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 <quote>I want to operate on every file in - this directory and its subdirectories</quote>. <!-- - &interaction.daily.files.add-dir; --> 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 - <filename>a</filename> in the earlier example.</para> + this directory and its subdirectories</quote>.</para> + + &interaction.daily.files.add-dir; + + <para>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 <filename>a</filename> in the earlier + example.</para> <para>What's going on is that in the former case, we explicitly named the file to add on the command line, so the assumption @@ -92,7 +96,7 @@ most commands and GUI tools. This approach is illustrated below.</para> -<!-- &interaction.daily.files.hidden; --> +&interaction.daily.files.hidden; <para>Another way to tackle a need for an empty directory is to simply create one in your automated build scripts before they @@ -108,8 +112,9 @@ command; this deletes the file, and tells Mercurial to stop tracking it. A removed file is represented in the output of <command role="hg-cmd">hg status</command> with a - <quote><literal>R</literal></quote>. <!-- - &interaction.daily.files.remove; --></para> + <quote><literal>R</literal></quote>.</para> + + &interaction.daily.files.remove; <para>After you <command role="hg-cmd">hg remove</command> a file, Mercurial will no longer track changes to that file, even if you @@ -152,7 +157,9 @@ represented with <quote><literal>!</literal></quote> in the output of <command role="hg-cmd">hg status</command>. Mercurial commands will not generally do anything with missing - files. <!-- &interaction.daily.files.missing; --></para> + files.</para> + + &interaction.daily.files.missing; <para>If your repository contains a file that <command role="hg-cmd">hg status</command> reports as missing, and @@ -160,15 +167,16 @@ role="hg-cmd">hg remove <option role="hg-opt-remove">--after</option></command> at any time later on, to tell Mercurial that you really did mean to - remove the file. <!-- &interaction.daily.files.remove-after; - --></para> + remove the file.</para> + + &interaction.daily.files.remove-after; <para>On the other hand, if you deleted the missing file by accident, give <command role="hg-cmd">hg revert</command> the name of the file to recover. It will reappear, in unmodified form.</para> -<!-- &interaction.daily.files.recover-missing; --> +&interaction.daily.files.recover-missing; </sect2> <sect2> @@ -191,12 +199,16 @@ <para>Mercurial offers a combination command, <command role="hg-cmd">hg addremove</command>, that adds untracked - files and marks missing files as removed. <!-- - &interaction.daily.files.addremove; --> The <command - role="hg-cmd">hg commit</command> command also provides a - <option role="hg-opt-commit">-A</option> option that performs - this same add-and-remove, immediately followed by a commit. - <!-- &interaction.daily.files.commit-addremove; --></para> + files and marks missing files as removed.</para> + + &interaction.daily.files.addremove; + + <para>The <command role="hg-cmd">hg commit</command> command + also provides a <option role="hg-opt-commit">-A</option> + option that performs this same add-and-remove, immediately + followed by a commit.</para> + + &interaction.daily.files.commit-addremove; </sect2> </sect1> @@ -216,34 +228,49 @@ <para>What happens during a merge is that changes <quote>follow</quote> a copy. To best illustrate what this means, let's create an example. We'll start with the usual - tiny repository that contains a single file. <!-- - &interaction.daily.copy.init; --> We need to do some work in + tiny repository that contains a single file.</para> + + &interaction.daily.copy.init; + + <para>We need to do some work in parallel, so that we'll have something to merge. So let's - clone our repository. <!-- &interaction.daily.copy.clone; --> - Back in our initial repository, let's use the <command + clone our repository.</para> + + &interaction.daily.copy.clone; + + <para>Back in our initial repository, let's use the <command role="hg-cmd">hg copy</command> command to make a copy of - the first file we created. <!-- &interaction.daily.copy.copy; - --></para> + the first file we created.</para> + + &interaction.daily.copy.copy; <para>If we look at the output of the <command role="hg-cmd">hg status</command> command afterwards, the copied file looks - just like a normal added file. <!-- - &interaction.daily.copy.status; --> But if we pass the <option + just like a normal added file.</para> + + &interaction.daily.copy.status; + + <para>But if we pass the <option role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command>, it prints another line of output: this is the file that our newly-added file was copied - <emphasis>from</emphasis>. <!-- - &interaction.daily.copy.status-copy; --></para> + <emphasis>from</emphasis>.</para> + + &interaction.daily.copy.status-copy; <para>Now, back in the repository we cloned, let's make a change in parallel. We'll add a line of content to the original file - that we created. <!-- &interaction.daily.copy.other; --> Now - we have a modified <filename>file</filename> in this + that we created.</para> + + &interaction.daily.copy.other; + + <para>Now we have a modified <filename>file</filename> in this repository. When we pull the changes from the first repository, and merge the two heads, Mercurial will propagate the changes that we made locally to <filename>file</filename> - into its copy, <filename>new-file</filename>. <!-- - &interaction.daily.copy.merge; --></para> + into its copy, <filename>new-file</filename>.</para> + + &interaction.daily.copy.merge; </sect2> <sect2 id="sec:daily:why-copy"> @@ -327,22 +354,33 @@ <emphasis>destination</emphasis>, and all prior arguments are <emphasis>sources</emphasis>. If you pass it a single file as the source, and the destination does not exist, it creates a - new file with that name. <!-- &interaction.daily.copy.simple; - --> If the destination is a directory, Mercurial copies its - sources into that directory. <!-- - &interaction.daily.copy.dir-dest; --> Copying a directory is + new file with that name.</para> + + &interaction.daily.copy.simple; + + <para>If the destination is a directory, Mercurial copies its + sources into that directory.</para> + + &interaction.daily.copy.dir-dest; + + <para>Copying a directory is recursive, and preserves the directory structure of the - source. <!-- &interaction.daily.copy.dir-src; --> If the - source and destination are both directories, the source tree - is recreated in the destination directory. <!-- - &interaction.daily.copy.dir-src-dest; --></para> + source.</para> + + &interaction.daily.copy.dir-src; + + <para>If the source and destination are both directories, the + source tree is recreated in the destination directory.</para> + + &interaction.daily.copy.dir-src-dest; <para>As with the <command role="hg-cmd">hg rename</command> command, if you copy a file manually and then want Mercurial to know that you've copied the file, simply use the <option role="hg-opt-copy">--after</option> option to <command - role="hg-cmd">hg copy</command>. <!-- - &interaction.daily.copy.after; --></para> + role="hg-cmd">hg copy</command>.</para> + + &interaction.daily.copy.after; </sect2> </sect1> @@ -359,17 +397,24 @@ <para>When you use the <command role="hg-cmd">hg rename</command> command, Mercurial makes a copy of each source file, then - deletes it and marks the file as removed. <!-- - &interaction.daily.rename.rename; --> The <command - role="hg-cmd">hg status</command> command shows the newly - copied file as added, and the copied-from file as removed. <!-- - &interaction.daily.rename.status; --> As with the results of a - <command role="hg-cmd">hg copy</command>, we must use the - <option role="hg-opt-status">-C</option> option to <command + deletes it and marks the file as removed.</para> + + &interaction.daily.rename.rename; + + <para>The <command role="hg-cmd">hg status</command> command shows + the newly copied file as added, and the copied-from file as + removed.</para> + + &interaction.daily.rename.status; + + <para>As with the results of a <command role="hg-cmd">hg + copy</command>, we must use the <option + role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command> to see that the added file is really being tracked by Mercurial as a copy of the original, - now removed, file. <!-- &interaction.daily.rename.status-copy; - --></para> + now removed, file.</para> + + &interaction.daily.rename.status-copy; <para>As with <command role="hg-cmd">hg remove</command> and <command role="hg-cmd">hg copy</command>, you can tell Mercurial @@ -410,11 +455,16 @@ <filename>foo</filename>&emdash;in their respective repositories.</para> - <para><!-- &interaction.rename.divergent.clone; --> Anne renames - the file to <filename>bar</filename>. <!-- - &interaction.rename.divergent.rename.anne; --> Meanwhile, Bob - renames it to <filename>quux</filename>. <!-- - &interaction.rename.divergent.rename.bob; --></para> + &interaction.rename.divergent.clone; + + <para>Anne renames the file to <filename>bar</filename>.</para> + + &interaction.rename.divergent.rename.anne; + + <para>Meanwhile, Bob renames it to + <filename>quux</filename>.</para> + + &interaction.rename.divergent.rename.bob; <para>I like to think of this as a conflict because each developer has expressed different intentions about what the @@ -423,8 +473,9 @@ <para>What do you think should happen when they merge their work? Mercurial's actual behaviour is that it always preserves <emphasis>both</emphasis> names when it merges changesets that - contain divergent renames. <!-- - &interaction.rename.divergent.merge; --></para> + contain divergent renames.</para> + + &interaction.rename.divergent.merge; <para>Notice that Mercurial does warn about the divergent renames, but it leaves it up to you to do something about the @@ -449,7 +500,9 @@ while another has a directory with the same name. This is documented as <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue29">issue - 29</ulink>. <!-- &interaction.issue29.go; --></para> + 29</ulink>.</para> + + &interaction.issue29.go; </sect2> </sect1>
--- a/en/ch06-collab.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch06-collab.xml Mon Mar 09 23:22:09 2009 -0700 @@ -200,45 +200,63 @@ <para>Here's an example of how this can work in practice. Let's say you have one <quote>main branch</quote> on a central - server. <!-- &interaction.branching.init; --> People clone it, - make changes locally, test them, and push them back.</para> + server.</para> + + &interaction.branching.init; + + <para>People clone it, make changes locally, test them, and push + them back.</para> <para>Once the main branch reaches a release milestone, you can use the <command role="hg-cmd">hg tag</command> command to - give a permanent name to the milestone revision. <!-- - &interaction.branching.tag; --> Let's say some ongoing - development occurs on the main branch. <!-- - &interaction.branching.main; --> Using the tag that was - recorded at the milestone, people who clone that repository at - any time in the future can use <command role="hg-cmd">hg - update</command> to get a copy of the working directory - exactly as it was when that tagged revision was committed. - <!-- &interaction.branching.update; --></para> + give a permanent name to the milestone revision.</para> + + &interaction.branching.tag; + + <para>Let's say some ongoing + development occurs on the main branch.</para> + + &interaction.branching.main; + + <para>Using the tag that was recorded at the milestone, people + who clone that repository at any time in the future can use + <command role="hg-cmd">hg update</command> to get a copy of + the working directory exactly as it was when that tagged + revision was committed.</para> + + &interaction.branching.update; <para>In addition, immediately after the main branch is tagged, someone can then clone the main branch on the server to a new - <quote>stable</quote> branch, also on the server. <!-- - &interaction.branching.clone; --></para> + <quote>stable</quote> branch, also on the server.</para> + + &interaction.branching.clone; <para>Someone who needs to make a change to the stable branch can then clone <emphasis>that</emphasis> repository, make - their changes, commit, and push their changes back there. <!-- - &interaction.branching.stable; --> Because Mercurial - repositories are independent, and Mercurial doesn't move - changes around automatically, the stable and main branches are - <emphasis>isolated</emphasis> from each other. The changes - that you made on the main branch don't <quote>leak</quote> to - the stable branch, and vice versa.</para> + their changes, commit, and push their changes back there.</para> + + &interaction.branching.stable; + + <para>Because Mercurial repositories are independent, and + Mercurial doesn't move changes around automatically, the + stable and main branches are <emphasis>isolated</emphasis> + from each other. The changes that you made on the main branch + don't <quote>leak</quote> to the stable branch, and vice + versa.</para> <para>You'll often want all of your bugfixes on the stable branch to show up on the main branch, too. Rather than rewrite a bugfix on the main branch, you can simply pull and merge changes from the stable to the main branch, and - Mercurial will bring those bugfixes in for you. <!-- - &interaction.branching.merge; --> The main branch will still - contain changes that are not on the stable branch, but it will - also contain all of the bugfixes from the stable branch. The - stable branch remains unaffected by these changes.</para> + Mercurial will bring those bugfixes in for you.</para> + + &interaction.branching.merge; + + <para>The main branch will still contain changes that are not on + the stable branch, but it will also contain all of the + bugfixes from the stable branch. The stable branch remains + unaffected by these changes.</para> </sect2> <sect2>
--- a/en/ch07-filenames.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch07-filenames.xml Mon Mar 09 23:22:09 2009 -0700 @@ -16,15 +16,16 @@ <para>If you explicitly name real files on the command line, Mercurial works with exactly those files, as you would expect. - <!-- &interaction.filenames.files; --></para> + &interaction.filenames.files;</para> <para>When you provide a directory name, Mercurial will interpret this as <quote>operate on every file in this directory and its subdirectories</quote>. Mercurial traverses the files and subdirectories in a directory in alphabetical order. When it encounters a subdirectory, it will traverse that subdirectory - before continuing with the current directory. <!-- - &interaction.filenames.dirs; --></para> + before continuing with the current directory.</para> + + &interaction.filenames.dirs; </sect1> <sect1> @@ -53,8 +54,9 @@ 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 - <quote><filename class="directory">.</filename></quote>. <!-- - &interaction.filenames.wdir-subdir; --></para> + <quote><filename class="directory">.</filename></quote>.</para> + + &interaction.filenames.wdir-subdir; <para>Along the same lines, some commands normally print file names relative to the root of the repository, even if you're @@ -64,8 +66,9 @@ status</command> from a subdirectory, and get it to operate on the entire working directory while printing file names relative to our subdirectory, by passing it the output of the <command - role="hg-cmd">hg root</command> command. <!-- - &interaction.filenames.wdir-relname; --></para> + role="hg-cmd">hg root</command> command.</para> + + &interaction.filenames.wdir-relname; </sect1> <sect1> @@ -139,18 +142,21 @@ when you're matching on glob patterns.</para> <para>The <quote><literal>*</literal></quote> character matches - any string, within a single directory. <!-- - &interaction.filenames.glob.star; --></para> + any string, within a single directory.</para> + + &interaction.filenames.glob.star; <para>The <quote><literal>**</literal></quote> pattern matches any string, and crosses directory boundaries. It's not a standard Unix glob token, but it's accepted by several popular - Unix shells, and is very useful. <!-- - &interaction.filenames.glob.starstar; --></para> + Unix shells, and is very useful.</para> + + &interaction.filenames.glob.starstar; <para>The <quote><literal>?</literal></quote> pattern matches - any single character. <!-- - &interaction.filenames.glob.question; --></para> + any single character.</para> + + &interaction.filenames.glob.question; <para>The <quote><literal>[</literal></quote> character begins a <emphasis>character class</emphasis>. This matches any single @@ -158,19 +164,23 @@ <quote><literal>]</literal></quote> character. A class may contain multiple <emphasis>range</emphasis>s of the form <quote><literal>a-f</literal></quote>, which is shorthand for - <quote><literal>abcdef</literal></quote>. <!-- - &interaction.filenames.glob.range; --> If the first character - after the <quote><literal>[</literal></quote> in a character - class is a <quote><literal>!</literal></quote>, it + <quote><literal>abcdef</literal></quote>.</para> + + &interaction.filenames.glob.range; + + <para>If the first character after the + <quote><literal>[</literal></quote> in a character class is a + <quote><literal>!</literal></quote>, it <emphasis>negates</emphasis> the class, making it match any single character not in the class.</para> <para>A <quote><literal>{</literal></quote> begins a group of subpatterns, where the whole group matches if any subpattern in the group matches. The <quote><literal>,</literal></quote> - character separates subpatterns, and <quote><literal>}</literal></quote> - ends the group. <!-- &interaction.filenames.glob.group; - --></para> + character separates subpatterns, and + <quote><literal>}</literal></quote> ends the group.</para> + + &interaction.filenames.glob.group; <sect3> <title>Watch out!</title> @@ -180,8 +190,9 @@ <quote><literal>*</literal></quote> match-any token, as this will only match within one directory. Instead, use the <quote><literal>**</literal></quote> token. This small - example illustrates the difference between the two. <!-- - &interaction.filenames.glob.star-starstar; --></para> + example illustrates the difference between the two.</para> + + &interaction.filenames.glob.star-starstar; </sect3> </sect2> @@ -245,11 +256,15 @@ <para>You can read a <option role="hg-opt-global">-I</option> filter as <quote>process only the files that match this - filter</quote>. <!-- &interaction.filenames.filter.include; - --> The <option role="hg-opt-global">-X</option> filter is best + filter</quote>.</para> + + &interaction.filenames.filter.include; + + <para>The <option role="hg-opt-global">-X</option> filter is best read as <quote>process only the files that don't match this - pattern</quote>. <!-- &interaction.filenames.filter.exclude; - --></para> + pattern</quote>.</para> + + &interaction.filenames.filter.exclude; </sect1> <sect1>
--- a/en/ch08-branch.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch08-branch.xml Mon Mar 09 23:22:09 2009 -0700 @@ -28,12 +28,13 @@ the identity of that revision. This will let you reproduce that release at a later date, for whatever purpose you might need at the time (reproducing a bug, porting to a new platform, etc). - <!-- &interaction.tag.init; --></para> + &interaction.tag.init;</para> <para>Mercurial lets you give a permanent name to any revision using the <command role="hg-cmd">hg tag</command> command. Not - surprisingly, these names are called <quote>tags</quote>. <!-- - &interaction.tag.tag; --></para> + surprisingly, these names are called <quote>tags</quote>.</para> + + &interaction.tag.tag; <para>A tag is nothing more than a <quote>symbolic name</quote> for a revision. Tags exist purely for your convenience, so that @@ -58,11 +59,15 @@ command to display the tags present in your repository. In the output, each tagged revision is identified first by its name, then by revision number, and finally by the unique hash of the - revision. <!-- &interaction.tag.tags; --> Notice that - <literal>tip</literal> is listed in the output of <command - role="hg-cmd">hg tags</command>. The <literal>tip</literal> - tag is a special <quote>floating</quote> tag, which always - identifies the newest revision in the repository.</para> + revision.</para> + + &interaction.tag.tags; + + <para>Notice that <literal>tip</literal> is listed in the output + of <command role="hg-cmd">hg tags</command>. The + <literal>tip</literal> tag is a special <quote>floating</quote> + tag, which always identifies the newest revision in the + repository.</para> <para>In the output of the <command role="hg-cmd">hg tags</command> command, tags are listed in reverse order, by @@ -73,13 +78,16 @@ <para>When you run <command role="hg-cmd">hg log</command>, if it displays a revision that has tags associated with it, it will - print those tags. <!-- &interaction.tag.log; --></para> + print those tags.</para> + + &interaction.tag.log; <para>Any time you need to provide a revision ID to a Mercurial command, the command will accept a tag name in its place. Internally, Mercurial will translate your tag name into the - corresponding revision ID, then use that. <!-- - &interaction.tag.log.v1.0; --></para> + corresponding revision ID, then use that.</para> + + &interaction.tag.log.v1.0; <para>There's no limit on the number of tags you can have in a repository, or on the number of tags that a single revision can @@ -98,18 +106,24 @@ or simply not use tags to track buildability.</para> <para>If you want to remove a tag that you no longer want, use - <command role="hg-cmd">hg tag --remove</command>. <!-- - &interaction.tag.remove; --> You can also modify a tag at any - time, so that it identifies a different revision, by simply - issuing a new <command role="hg-cmd">hg tag</command> command. - You'll have to use the <option role="hg-opt-tag">-f</option> - option to tell Mercurial that you <emphasis>really</emphasis> - want to update the tag. <!-- &interaction.tag.replace; --> There - will still be a permanent record of the previous identity of the - tag, but Mercurial will no longer use it. There's thus no - penalty to tagging the wrong revision; all you have to do is - turn around and tag the correct revision once you discover your - error.</para> + <command role="hg-cmd">hg tag --remove</command>.</para> + + &interaction.tag.remove; + + <para>You can also modify a tag at any time, so that it identifies + a different revision, by simply issuing a new <command + role="hg-cmd">hg tag</command> command. You'll have to use the + <option role="hg-opt-tag">-f</option> option to tell Mercurial + that you <emphasis>really</emphasis> want to update the + tag.</para> + + &interaction.tag.replace; + + <para>There will still be a permanent record of the previous + identity of the tag, but Mercurial will no longer use it. + There's thus no penalty to tagging the wrong revision; all you + have to do is turn around and tag the correct revision once you + discover your error.</para> <para>Mercurial stores tags in a normal revision-controlled file in your repository. If you've created any tags, you'll find @@ -119,8 +133,9 @@ this file, then automatically commits the change to it. This means that every time you run <command role="hg-cmd">hg tag</command>, you'll see a corresponding changeset in the - output of <command role="hg-cmd">hg log</command>. <!-- - &interaction.tag.tip; --></para> + output of <command role="hg-cmd">hg log</command>.</para> + + &interaction.tag.tip; <sect2> <title>Handling tag conflicts during a merge</title> @@ -247,19 +262,28 @@ <literal>myproject</literal>&emdash;that reaches a <quote>1.0</quote> milestone, you can start to prepare for future maintenance releases on top of version 1.0 by tagging the - revision from which you prepared the 1.0 release. <!-- - &interaction.branch-repo.tag; --> You can then clone a new - shared <literal>myproject-1.0.1</literal> repository as of that - tag. <!-- &interaction.branch-repo.clone; --></para> + revision from which you prepared the 1.0 release.</para> + + &interaction.branch-repo.tag; + + <para>You can then clone a new shared + <literal>myproject-1.0.1</literal> repository as of that + tag.</para> + + &interaction.branch-repo.clone; <para>Afterwards, if someone needs to work on a bug fix that ought to go into an upcoming 1.0.1 minor release, they clone the <literal>myproject-1.0.1</literal> repository, make their - changes, and push them back. <!-- - &interaction.branch-repo.bugfix; --> Meanwhile, development for + changes, and push them back.</para> + + &interaction.branch-repo.bugfix; + + <para>Meanwhile, development for the next major release can continue, isolated and unabated, in - the <literal>myproject</literal> repository. <!-- - &interaction.branch-repo.new; --></para> + the <literal>myproject</literal> repository.</para> + + &interaction.branch-repo.new; </sect1> <sect1> @@ -275,9 +299,14 @@ <para>In the simplest instance, all you need to do is pull changes from your maintenance branch into your local clone of the target - branch. <!-- &interaction.branch-repo.pull; --> You'll then need - to merge the heads of the two branches, and push back to the - main branch. <!-- &interaction.branch-repo.merge; --></para> + branch.</para> + + &interaction.branch-repo.pull; + + <para>You'll then need to merge the heads of the two branches, and + push back to the main branch.</para> + + &interaction.branch-repo.merge; </sect1> <sect1> @@ -318,27 +347,34 @@ <para>To start working with named branches, use the <command role="hg-cmd">hg branches</command> command. This command lists the named branches already present in your repository, - telling you which changeset is the tip of each. <!-- - &interaction.branch-named.branches; --> Since you haven't - created any named branches yet, the only one that exists is - <literal>default</literal>.</para> + telling you which changeset is the tip of each.</para> + + &interaction.branch-named.branches; + + <para>Since you haven't created any named branches yet, the only + one that exists is <literal>default</literal>.</para> <para>To find out what the <quote>current</quote> branch is, run the <command role="hg-cmd">hg branch</command> command, giving it no arguments. This tells you what branch the parent of the - current changeset is on. <!-- &interaction.branch-named.branch; - --></para> + current changeset is on.</para> + + &interaction.branch-named.branch; <para>To create a new branch, run the <command role="hg-cmd">hg branch</command> command again. This time, give it one - argument: the name of the branch you want to create. <!-- - &interaction.branch-named.create; --></para> + argument: the name of the branch you want to create.</para> + + &interaction.branch-named.create; <para>After you've created a branch, you might wonder what effect the <command role="hg-cmd">hg branch</command> command has had. What do the <command role="hg-cmd">hg status</command> and - <command role="hg-cmd">hg tip</command> commands report? <!-- - &interaction.branch-named.status; --> Nothing has changed in the + <command role="hg-cmd">hg tip</command> commands report?</para> + + &interaction.branch-named.status; + + <para>Nothing has changed in the working directory, and there's been no new history created. As this suggests, running the <command role="hg-cmd">hg branch</command> command has no permanent effect; it only @@ -351,10 +387,12 @@ you'll see the name of the new branch show up in the output of <command role="hg-cmd">hg log</command>, <command role="hg-cmd">hg tip</command>, and other commands that - display the same kind of output. <!-- - &interaction.branch-named.commit; --> The <command - role="hg-cmd">hg log</command>-like commands will print the - branch name of every changeset that's not on the + display the same kind of output.</para> + + &interaction.branch-named.commit; + + <para>The <command role="hg-cmd">hg log</command>-like commands + will print the branch name of every changeset that's not on the <literal>default</literal> branch. As a result, if you never use named branches, you'll never see this information.</para> @@ -362,11 +400,13 @@ name, every subsequent commit that descends from that change will inherit the same branch name. You can change the name of a branch at any time, using the <command role="hg-cmd">hg - branch</command> command. <!-- - &interaction.branch-named.rebranch; --> In practice, this is - something you won't do very often, as branch names tend to have - fairly long lifetimes. (This isn't a rule, just an - observation.)</para> + branch</command> command.</para> + + &interaction.branch-named.rebranch; + + <para>In practice, this is something you won't do very often, as + branch names tend to have fairly long lifetimes. (This isn't a + rule, just an observation.)</para> </sect1> <sect1> @@ -385,28 +425,34 @@ <para>This behaviour is a little subtle, so let's see it in action. First, let's remind ourselves what branch we're - currently on, and what branches are in our repository. <!-- - &interaction.branch-named.parents; --> We're on the - <literal>bar</literal> branch, but there also exists an older - <command role="hg-cmd">hg foo</command> branch.</para> + currently on, and what branches are in our repository.</para> + + &interaction.branch-named.parents; + + <para>We're on the <literal>bar</literal> branch, but there also + exists an older <command role="hg-cmd">hg foo</command> + branch.</para> <para>We can <command role="hg-cmd">hg update</command> back and forth between the tips of the <literal>foo</literal> and <literal>bar</literal> branches without needing to use the <option role="hg-opt-update">-C</option> option, because this only involves going backwards and forwards linearly through our - change history. <!-- &interaction.branch-named.update-switchy; - --></para> + change history.</para> + + &interaction.branch-named.update-switchy; <para>If we go back to the <literal>foo</literal> branch and then run <command role="hg-cmd">hg update</command>, it will keep us on <literal>foo</literal>, not move us to the tip of - <literal>bar</literal>. <!-- - &interaction.branch-named.update-nothing; --></para> + <literal>bar</literal>.</para> + + &interaction.branch-named.update-nothing; <para>Committing a new change on the <literal>foo</literal> branch - introduces a new head. <!-- - &interaction.branch-named.foo-commit; --></para> + introduces a new head.</para> + + &interaction.branch-named.foo-commit; </sect1> <sect1> @@ -439,8 +485,9 @@ <para>But if I'm working on the <literal>bar</literal> branch, and I merge work from the <literal>foo</literal> branch, the result - will remain on the <literal>bar</literal> branch. <!-- - &interaction.branch-named.merge; --></para> + will remain on the <literal>bar</literal> branch.</para> + + &interaction.branch-named.merge; <para>To give a more concrete example, if I'm working on the <literal>bleeding-edge</literal> branch, and I want to bring in
--- a/en/ch09-undo.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch09-undo.xml Mon Mar 09 23:22:09 2009 -0700 @@ -41,32 +41,43 @@ <para>Here's a mistake that I often find myself making: committing a change in which I've created a new file, but - forgotten to <command role="hg-cmd">hg add</command> it. <!-- - &interaction.rollback.commit; --> Looking at the output of - <command role="hg-cmd">hg status</command> after the commit - immediately confirms the error. <!-- - &interaction.rollback.status; --> The commit captured the - changes to the file <filename>a</filename>, but not the new - file <filename>b</filename>. If I were to push this changeset - to a repository that I shared with a colleague, the chances - are high that something in <filename>a</filename> would refer - to <filename>b</filename>, which would not be present in their + forgotten to <command role="hg-cmd">hg add</command> + it.</para> + + &interaction.rollback.commit; + + <para>Looking at the output of <command role="hg-cmd">hg + status</command> after the commit immediately confirms the + error.</para> + + &interaction.rollback.status; + + <para>The commit captured the changes to the file + <filename>a</filename>, but not the new file + <filename>b</filename>. If I were to push this changeset to a + repository that I shared with a colleague, the chances are + high that something in <filename>a</filename> would refer to + <filename>b</filename>, which would not be present in their repository when they pulled my changes. I would thus become the object of some indignation.</para> <para>However, luck is with me&emdash;I've caught my error before I pushed the changeset. I use the <command role="hg-cmd">hg rollback</command> command, and Mercurial - makes that last changeset vanish. <!-- - &interaction.rollback.rollback; --> Notice that the changeset - is no longer present in the repository's history, and the - working directory once again thinks that the file - <filename>a</filename> is modified. The commit and rollback - have left the working directory exactly as it was prior to the - commit; the changeset has been completely erased. I can now - safely <command role="hg-cmd">hg add</command> the file - <filename>b</filename>, and rerun my commit. <!-- - &interaction.rollback.add; --></para> + makes that last changeset vanish.</para> + + &interaction.rollback.rollback; + + <para>Notice that the changeset is no longer present in the + repository's history, and the working directory once again + thinks that the file <filename>a</filename> is modified. The + commit and rollback have left the working directory exactly as + it was prior to the commit; the changeset has been completely + erased. I can now safely <command role="hg-cmd">hg + add</command> the file <filename>b</filename>, and rerun my + commit.</para> + + &interaction.rollback.add; </sect2> <sect2> @@ -139,9 +150,12 @@ occurred in the repository. This means that you can only roll back one transaction. If you expect to be able to roll back one transaction, then its predecessor, this is not the - behaviour you will get. <!-- &interaction.rollback.twice; --> - Once you've rolled back one transaction in a repository, you - can't roll back again in that repository until you perform + behaviour you will get.</para> + + &interaction.rollback.twice; + + <para>Once you've rolled back one transaction in a repository, + you can't roll back again in that repository until you perform another commit or pull.</para> </sect2> @@ -161,14 +175,22 @@ <para>Let's illustrate how the <command role="hg-cmd">hg revert</command> command works with yet another small example. We'll begin by modifying a file that Mercurial is already - tracking. <!-- &interaction.daily.revert.modify; --> If we don't + tracking.</para> + + &interaction.daily.revert.modify; + + <para>If we don't want that change, we can simply <command role="hg-cmd">hg - revert</command> the file. <!-- - &interaction.daily.revert.unmodify; --> The <command - role="hg-cmd">hg revert</command> command provides us with an - extra degree of safety by saving our modified file with a - <filename>.orig</filename> extension. <!-- - &interaction.daily.revert.status; --></para> + revert</command> the file.</para> + + &interaction.daily.revert.unmodify; + + <para>The <command role="hg-cmd">hg revert</command> command + provides us with an extra degree of safety by saving our + modified file with a <filename>.orig</filename> + extension.</para> + + &interaction.daily.revert.status; <para>Here is a summary of the cases that the <command role="hg-cmd">hg revert</command> command can deal with. We @@ -204,25 +226,28 @@ then decide that in fact you don't want Mercurial to track it, use <command role="hg-cmd">hg revert</command> to undo the add. Don't worry; Mercurial will not modify the file in any - way. It will just <quote>unmark</quote> the file. <!-- - &interaction.daily.revert.add; --></para> + way. It will just <quote>unmark</quote> the file.</para> + + &interaction.daily.revert.add; <para>Similarly, if you ask Mercurial to <command role="hg-cmd">hg remove</command> a file, you can use <command role="hg-cmd">hg revert</command> to restore it to the contents it had as of the parent of the working directory. - <!-- &interaction.daily.revert.remove; --> This works just as + &interaction.daily.revert.remove; This works just as well for a file that you deleted by hand, without telling Mercurial (recall that in Mercurial terminology, this kind of - file is called <quote>missing</quote>). <!-- - &interaction.daily.revert.missing; --></para> + file is called <quote>missing</quote>).</para> + + &interaction.daily.revert.missing; <para>If you revert a <command role="hg-cmd">hg copy</command>, the copied-to file remains in your working directory afterwards, untracked. Since a copy doesn't affect the copied-from file in any way, Mercurial doesn't do anything - with the copied-from file. <!-- - &interaction.daily.revert.copy; --></para> + with the copied-from file.</para> + + &interaction.daily.revert.copy; <sect3> <title>A slightly special case: reverting a rename</title> @@ -231,17 +256,23 @@ file, there is one small detail that you should remember. When you <command role="hg-cmd">hg revert</command> a rename, it's not enough to provide the name of the - renamed-to file, as you can see here. <!-- - &interaction.daily.revert.rename; --> As you can see from - the output of <command role="hg-cmd">hg status</command>, - the renamed-to file is no longer identified as added, but - the renamed-<emphasis>from</emphasis> file is still removed! + renamed-to file, as you can see here.</para> + + &interaction.daily.revert.rename; + + <para>As you can see from the output of <command + role="hg-cmd">hg status</command>, the renamed-to file is + no longer identified as added, but the + renamed-<emphasis>from</emphasis> file is still removed! This is counter-intuitive (at least to me), but at least - it's easy to deal with. <!-- - &interaction.daily.revert.rename-orig; --> So remember, to - revert a <command role="hg-cmd">hg rename</command>, you - must provide <emphasis>both</emphasis> the source and - destination names.</para> + it's easy to deal with.</para> + + &interaction.daily.revert.rename-orig; + + <para>So remember, to revert a <command role="hg-cmd">hg + rename</command>, you must provide + <emphasis>both</emphasis> the source and destination + names.</para> <para>% TODO: the output doesn't look like it will be removed!</para> @@ -291,8 +322,9 @@ <para>The operation of the <command role="hg-cmd">hg backout</command> command is a little intricate, so let's illustrate it with some examples. First, we'll create a - repository with some simple changes. <!-- - &interaction.backout.init; --></para> + repository with some simple changes.</para> + + &interaction.backout.init; <para>The <command role="hg-cmd">hg backout</command> command takes a single changeset ID as its argument; this is the @@ -308,15 +340,19 @@ <title>Backing out the tip changeset</title> <para>We're going to start by backing out the last changeset we - committed. <!-- &interaction.backout.simple; --> You can see - that the second line from <filename>myfile</filename> is no - longer present. Taking a look at the output of <command - role="hg-cmd">hg log</command> gives us an idea of what the - <command role="hg-cmd">hg backout</command> command has done. - <!-- &interaction.backout.simple.log; --> Notice that the new - changeset that <command role="hg-cmd">hg backout</command> has - created is a child of the changeset we backed out. It's - easier to see this in figure <xref + committed.</para> + + &interaction.backout.simple; + + <para>You can see that the second line from + <filename>myfile</filename> is no longer present. Taking a + look at the output of <command role="hg-cmd">hg log</command> + gives us an idea of what the <command role="hg-cmd">hg + backout</command> command has done. + &interaction.backout.simple.log; Notice that the new changeset + that <command role="hg-cmd">hg backout</command> has created + is a child of the changeset we backed out. It's easier to see + this in figure <xref linkend="fig:undo:backout"/>, which presents a graphical view of the change history. As you can see, the history is nice and linear.</para> @@ -338,16 +374,22 @@ <para>If you want to back out a change other than the last one you committed, pass the <option role="hg-opt-backout">--merge</option> option to the - <command role="hg-cmd">hg backout</command> command. <!-- - &interaction.backout.non-tip.clone; --> This makes backing out - any changeset a <quote>one-shot</quote> operation that's - usually simple and fast. <!-- - &interaction.backout.non-tip.backout; --></para> + <command role="hg-cmd">hg backout</command> command.</para> + + &interaction.backout.non-tip.clone; + + <para>This makes backing out any changeset a + <quote>one-shot</quote> operation that's usually simple and + fast.</para> + + &interaction.backout.non-tip.backout; <para>If you take a look at the contents of <filename>myfile</filename> after the backout finishes, you'll see that the first and third changes are present, but not the - second. <!-- &interaction.backout.non-tip.cat; --></para> + second.</para> + + &interaction.backout.non-tip.cat; <para>As the graphical history in figure <xref linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial @@ -404,15 +446,21 @@ clone our first repository, but omit the backout change that it contains.</para> - <para><!-- &interaction.backout.manual.clone; --> As with our + &interaction.backout.manual.clone; + + <para>As with our earlier example, We'll commit a third changeset, then back out - its parent, and see what happens. <!-- - &interaction.backout.manual.backout; --> Our new changeset is - again a descendant of the changeset we backout out; it's thus - a new head, <emphasis>not</emphasis> a descendant of the - changeset that was the tip. The <command role="hg-cmd">hg - backout</command> command was quite explicit in telling us - this. <!-- &interaction.backout.manual.log; --></para> + its parent, and see what happens.</para> + + &interaction.backout.manual.backout; + + <para>Our new changeset is again a descendant of the changeset + we backout out; it's thus a new head, <emphasis>not</emphasis> + a descendant of the changeset that was the tip. The <command + role="hg-cmd">hg backout</command> command was quite + explicit in telling us this.</para> + + &interaction.backout.manual.log; <para>Again, it's easier to see what has happened by looking at a graph of the revision history, in figure <xref @@ -435,9 +483,13 @@ <para>After the <command role="hg-cmd">hg backout</command> command has completed, it leaves the new <quote>backout</quote> changeset as the parent of the working - directory. <!-- &interaction.backout.manual.parents; --> Now - we have two isolated sets of changes. <!-- - &interaction.backout.manual.heads; --></para> + directory.</para> + + &interaction.backout.manual.parents; + + <para>Now we have two isolated sets of changes.</para> + + &interaction.backout.manual.heads; <para>Let's think about what we expect to see as the contents of <filename>myfile</filename> now. The first change should be @@ -445,11 +497,17 @@ should be missing, as that's the change we backed out. Since the history graph shows the third change as a separate head, we <emphasis>don't</emphasis> expect to see the third change - present in <filename>myfile</filename>. <!-- - &interaction.backout.manual.cat; --> To get the third change - back into the file, we just do a normal merge of our two - heads. <!-- &interaction.backout.manual.merge; --> Afterwards, - the graphical history of our repository looks like figure + present in <filename>myfile</filename>.</para> + + &interaction.backout.manual.cat; + + <para>To get the third change back into the file, we just do a + normal merge of our two heads.</para> + + &interaction.backout.manual.merge; + + <para>Afterwards, the graphical history of our repository looks + like figure <xref linkend="fig:undo:backout-manual-merge"/>.</para> <informalfigure id="fig:undo:backout-manual-merge"> @@ -731,19 +789,26 @@ <para>Now let's create a repository, so that we can try out the <command role="hg-cmd">hg bisect</command> command in - isolation. <!-- &interaction.bisect.init; --> We'll simulate a - project that has a bug in it in a simple-minded way: create - trivial changes in a loop, and nominate one specific change - that will have the <quote>bug</quote>. This loop creates 35 - changesets, each adding a single file to the repository. - We'll represent our <quote>bug</quote> with a file that - contains the text <quote>i have a gub</quote>. <!-- - &interaction.bisect.commits; --></para> + isolation.</para> + + &interaction.bisect.init; + + <para>We'll simulate a project that has a bug in it in a + simple-minded way: create trivial changes in a loop, and + nominate one specific change that will have the + <quote>bug</quote>. This loop creates 35 changesets, each + adding a single file to the repository. We'll represent our + <quote>bug</quote> with a file that contains the text <quote>i + have a gub</quote>.</para> + + &interaction.bisect.commits; <para>The next thing that we'd like to do is figure out how to use the <command role="hg-cmd">hg bisect</command> command. We can use Mercurial's normal built-in help mechanism for - this. <!-- &interaction.bisect.help; --></para> + this.</para> + + &interaction.bisect.help; <para>The <command role="hg-cmd">hg bisect</command> command works in steps. Each step proceeds as follows.</para> @@ -771,8 +836,9 @@ <quote>succeeding</quote> to <quote>failing</quote>.</para> <para>To start the search, we must run the <command - role="hg-cmd">hg bisect --reset</command> command. <!-- - &interaction.bisect.search.init; --></para> + role="hg-cmd">hg bisect --reset</command> command.</para> + + &interaction.bisect.search.init; <para>In our case, the binary test we use is simple: we check to see if any file in the repository contains the string <quote>i @@ -785,8 +851,9 @@ <para>Most of the time, the revision to which the working directory is synced (usually the tip) already exhibits the problem introduced by the buggy change, so we'll mark it as - <quote>bad</quote>. <!-- &interaction.bisect.search.bad-init; - --></para> + <quote>bad</quote>.</para> + + &interaction.bisect.search.bad-init; <para>Our next task is to nominate a changeset that we know <emphasis>doesn't</emphasis> have the bug; the <command @@ -794,8 +861,9 @@ <quote>bracket</quote> its search between the first pair of good and bad changesets. In our case, we know that revision 10 didn't have the bug. (I'll have more words about choosing - the first <quote>good</quote> changeset later.) <!-- - &interaction.bisect.search.good-init; --></para> + the first <quote>good</quote> changeset later.)</para> + + &interaction.bisect.search.good-init; <para>Notice that this command printed some output.</para> <itemizedlist> @@ -812,16 +880,21 @@ <command>grep</command> command to see if our <quote>bad</quote> file is present in the working directory. If it is, this revision is bad; if not, this revision is good. - <!-- &interaction.bisect.search.step1; --></para> + &interaction.bisect.search.step1;</para> <para>This test looks like a perfect candidate for automation, - so let's turn it into a shell function. <!-- - &interaction.bisect.search.mytest; --> We can now run an - entire test step with a single command, - <literal>mytest</literal>. <!-- - &interaction.bisect.search.step2; --> A few more invocations - of our canned test step command, and we're done. <!-- - &interaction.bisect.search.rest; --></para> + so let's turn it into a shell function.</para> + &interaction.bisect.search.mytest; + + <para>We can now run an entire test step with a single command, + <literal>mytest</literal>.</para> + + &interaction.bisect.search.step2; + + <para>A few more invocations of our canned test step command, + and we're done.</para> + + &interaction.bisect.search.rest; <para>Even though we had 40 changesets to search through, the <command role="hg-cmd">hg bisect</command> command let us find @@ -844,8 +917,9 @@ forget to run this command. However, <command role="hg-cmd">hg bisect</command> won't let you start a new search in that repository until you do a <command - role="hg-cmd">hg bisect reset</command>. <!-- - &interaction.bisect.search.reset; --></para> + role="hg-cmd">hg bisect reset</command>.</para> + + &interaction.bisect.search.reset; </sect2> </sect1>
--- a/en/ch10-hook.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch10-hook.xml Mon Mar 09 23:22:09 2009 -0700 @@ -354,7 +354,7 @@ <para>All hooks follow the pattern in this example.</para> -<!-- &interaction.hook.simple.init; --> +&interaction.hook.simple.init; <para>You add an entry to the <literal role="rc-hooks">hooks</literal> section of your <filename @@ -371,7 +371,7 @@ <para>Quite often, you will want to define more than one hook for a particular kind of event, as shown below.</para> -<!-- &interaction.hook.simple.ext; --> +&interaction.hook.simple.ext; <para>Mercurial lets you do this by adding an <emphasis>extension</emphasis> to the end of a hook's name. @@ -438,7 +438,7 @@ <literal role="hook">commit</literal> hook is not run. </para> -<!-- &interaction.hook.simple.pretxncommit; --> +&interaction.hook.simple.pretxncommit; <para>The hook in the example above checks that a commit comment contains a bug ID. If it does, the commit can complete. If @@ -621,7 +621,7 @@ changeset with a message that is less than ten bytes long. </para> -<!-- &interaction.hook.msglen.go; --> +&interaction.hook.msglen.go; </sect2> <sect2> @@ -665,7 +665,7 @@ role="hg-cmd">hg commit</command> again. </para> -<!-- &interaction.hook.ws.simple; --> +&interaction.hook.ws.simple; <para>In this example, we introduce a simple <literal role="hook">pretxncommit</literal> hook that checks for @@ -690,7 +690,7 @@ the saved commit message once you've corrected the problem. </para> -<!-- &interaction.hook.ws.better; --> +&interaction.hook.ws.better; <para>As a final aside, note in the example above the use of <command>perl</command>'s in-place editing feature to get rid
--- a/en/ch11-template.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch11-template.xml Mon Mar 09 23:22:09 2009 -0700 @@ -20,21 +20,21 @@ <para>Before we take a look at Mercurial's bundled styles, let's review its normal output.</para> - <para><!-- &interaction.template.simple.normal; --></para> + &interaction.template.simple.normal; <para>This is somewhat informative, but it takes up a lot of space&emdash;five lines of output per changeset. The <literal>compact</literal> style reduces this to three lines, presented in a sparse manner.</para> - <para><!-- &interaction.template.simple.compact; --></para> + &interaction.template.simple.compact; <para>The <literal>changelog</literal> style hints at the expressive power of Mercurial's templating engine. This style attempts to follow the GNU Project's changelog guidelines<citation>web:changelog</citation>.</para> - <para><!-- &interaction.template.simple.changelog; --></para> + &interaction.template.simple.changelog; <para>You will not be shocked to learn that Mercurial's default output style is named <literal>default</literal>.</para> @@ -85,12 +85,12 @@ <para>Before we continue, let's look again at a simple example of Mercurial's normal output.</para> - <para><!-- &interaction.template.simple.normal; --></para> + &interaction.template.simple.normal; <para>Now, let's run the same command, but using a template to change its output.</para> - <para><!-- &interaction.template.simple.simplest; --></para> + &interaction.template.simple.simplest; <para>The example above illustrates the simplest possible template; it's just a piece of static text, printed once for @@ -112,7 +112,7 @@ isn't very useful; let's try something a bit more complex.</para> - <para><!-- &interaction.template.simple.simplesub; --></para> + &interaction.template.simple.simplesub; <para>As you can see, the string <quote><literal>{desc}</literal></quote> in the template has @@ -190,7 +190,7 @@ <para>A few simple experiments will show us what to expect when we use these keywords; you can see the results below.</para> -<!-- &interaction.template.simple.keywords; --> +&interaction.template.simple.keywords; <para>As we noted above, the date keyword does not produce human-readable output, so we must treat it specially. This @@ -198,7 +198,7 @@ in section <xref linkend="sec:template:filter"/>.</para> - <para><!-- &interaction.template.simple.datekeyword; --></para> + &interaction.template.simple.datekeyword; </sect1> <sect1 id="sec:template:escape"> @@ -410,7 +410,7 @@ <quote><literal>bos</literal></quote>.</para> </listitem></itemizedlist> -<!-- &interaction.template.simple.manyfilters; --> +&interaction.template.simple.manyfilters; <note> <para> If you try to apply a filter to a piece of data that it @@ -431,7 +431,7 @@ on Unix-like systems, where a tab is conventionally 8 characters wide).</para> - <para><!-- &interaction.template.simple.combine; --></para> + &interaction.template.simple.combine; <para>Note the use of <quote><literal>\t</literal></quote> (a tab character) in the template to force the first line to be @@ -467,7 +467,7 @@ <para>Our simple style file contains just one line:</para> - <para><!-- &interaction.template.simple.rev; --></para> + &interaction.template.simple.rev; <para>This tells Mercurial, <quote>if you're printing a changeset, use the text on the right as the @@ -532,15 +532,14 @@ working on, it prints a terse error message that, once you figure out what it means, is actually quite useful.</para> -<!-- &interaction.template.svnstyle.syntax.input; --> +&interaction.template.svnstyle.syntax.input; <para>Notice that <filename>broken.style</filename> attempts to define a <literal>changeset</literal> keyword, but forgets to give any content for it. When instructed to use this style file, Mercurial promptly complains.</para> - <para><!-- &interaction.template.svnstyle.syntax.error; - --></para> + &interaction.template.svnstyle.syntax.error; <para>This error message looks intimidating, but it is not too hard to follow.</para> @@ -580,9 +579,12 @@ <para>If you would like to be able to identify a Mercurial repository <quote>fairly uniquely</quote> 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 nevertheless useful - in many cases.</para> + repository.</para> + + &interaction.template.svnstyle.id; + + <para>This is not guaranteed to be unique, but it is + nevertheless useful in many cases.</para> <itemizedlist> <listitem><para>It will not work in a completely empty repository, because such a repository does not have a @@ -611,14 +613,16 @@ <title>Mimicking Subversion's output</title> <para>Let's try to emulate the default output format used by - another revision control tool, Subversion. <!-- - &interaction.template.svnstyle.short; --></para> + another revision control tool, Subversion.</para> + + &interaction.template.svnstyle.short; <para>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; --></para> + template values we'd like to see expanded.</para> + + &interaction.template.svnstyle.template; <para>There are a few small ways in which this template deviates from the output produced by Subversion.</para> @@ -648,8 +652,9 @@ <para>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; --></para> + file simply refers to the template.</para> + + &interaction.template.svnstyle.style; <para>We could have included the text of the template file directly in the style file by enclosing it in quotes and
--- a/en/ch12-mq.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch12-mq.xml Mon Mar 09 23:22:09 2009 -0700 @@ -196,7 +196,7 @@ file. Take a look below for a simple example of these commands in action.</para> -<!-- &interaction.mq.dodiff.diff; --> +&interaction.mq.dodiff.diff; <para>The type of file that <command>diff</command> generates (and <command>patch</command> takes as input) is called a @@ -263,14 +263,14 @@ the <command role="hg-ext-mq">qinit</command> command is now available.</para> -<!-- &interaction.mq.qinit-help.help; --> +&interaction.mq.qinit-help.help; <para>You can use MQ with <emphasis>any</emphasis> Mercurial repository, and its commands only operate within that repository. To get started, simply prepare the repository using the <command role="hg-ext-mq">qinit</command> command.</para> -<!-- &interaction.mq.tutorial.qinit; --> +&interaction.mq.tutorial.qinit; <para>This command creates an empty directory called <filename role="special" class="directory">.hg/patches</filename>, where @@ -290,7 +290,7 @@ class="directory">.hg/patches</filename> directory, as you can see below.</para> -<!-- &interaction.mq.tutorial.qnew; --> +&interaction.mq.tutorial.qnew; <para>Also newly present in the <filename role="special" class="directory">.hg/patches</filename> directory are two @@ -327,7 +327,7 @@ use the <command role="hg-ext-mq">qrefresh</command> command to update the patch you are working on.</para> -<!-- &interaction.mq.tutorial.qrefresh; --> +&interaction.mq.tutorial.qrefresh; <para>This command folds the changes you have made in the working directory into your patch, and updates its @@ -340,7 +340,7 @@ doesn't work out, <command role="hg-cmd">hg revert</command> your modifications back to the last time you refreshed.</para> -<!-- &interaction.mq.tutorial.qrefresh2; --> +&interaction.mq.tutorial.qrefresh2; </sect2> <sect2> @@ -352,7 +352,7 @@ new patch. Mercurial will apply this patch on top of your existing patch.</para> -<!-- &interaction.mq.tutorial.qnew2; --> +&interaction.mq.tutorial.qnew2; <para>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 <command role="hg-cmd">hg @@ -365,7 +365,7 @@ many commands that are easier to use when you are thinking about patches, as illustrated below.</para> -<!-- &interaction.mq.tutorial.qseries; --> +&interaction.mq.tutorial.qseries; <itemizedlist> <listitem><para>The <command @@ -417,7 +417,7 @@ directory. See below for examples of <command role="hg-ext-mq">qpop</command> and <command role="hg-ext-mq">qpush</command> in action.</para> -<!-- &interaction.mq.tutorial.qpop; --> +&interaction.mq.tutorial.qpop; <para>Notice that once we have popped a patch or two patches, the output of <command role="hg-ext-mq">qseries</command> @@ -442,7 +442,7 @@ see section <xref linkend="sec:mq:perf"/> below.)</para> -<!-- &interaction.mq.tutorial.qpush-a; --> +&interaction.mq.tutorial.qpush-a; </sect2> <sect2> @@ -458,7 +458,7 @@ case by the <command role="hg-cmd">hg add</command> of <filename>file3</filename>.</para> -<!-- &interaction.mq.tutorial.add; --> +&interaction.mq.tutorial.add; <para>Commands that check the working directory all take an <quote>I know what I'm doing</quote> option, which is always @@ -969,7 +969,7 @@ few normal Mercurial commands in use with applied patches.</para> -<!-- &interaction.mq.id.output; --> +&interaction.mq.id.output; </sect1> <sect1> @@ -1126,7 +1126,7 @@ prefixes of file names that inevitably confuse at least me.)</para> -<!-- &interaction.mq.tools.tools; --> +&interaction.mq.tools.tools; <para>The <literal role="package">patchutils</literal> package <citation>web:patchutils</citation> is invaluable. It provides a @@ -1196,16 +1196,22 @@ changes to a source tarball that you downloaded.</para> <para>Begin by downloading and unpacking the source tarball, and - turning it into a Mercurial repository. <!-- - &interaction.mq.tarball.download; --></para> + turning it into a Mercurial repository.</para> + + &interaction.mq.tarball.download; <para>Continue by creating a patch stack and making your - changes. <!-- &interaction.mq.tarball.qinit; --></para> + changes.</para> + + &interaction.mq.tarball.qinit; <para>Let's say a few weeks or months pass, and your package author releases a new version. First, bring their changes - into the repository. <!-- &interaction.mq.tarball.newsource; - --> The pipeline starting with <command role="hg-cmd">hg + into the repository.</para> + + &interaction.mq.tarball.newsource; + + <para>The pipeline starting with <command role="hg-cmd">hg locate</command> above deletes all files in the working directory, so that <command role="hg-cmd">hg commit</command>'s <option @@ -1214,7 +1220,9 @@ newer version of the source.</para> <para>Finally, you can apply your patches on top of the new - tree. <!-- &interaction.mq.tarball.repush; --></para> + tree.</para> + + &interaction.mq.tarball.repush; </sect2> <sect2 id="sec:mq:combine"> @@ -1262,7 +1270,9 @@ file, and you only want to move a few of those hunks, the job becomes more messy, but you can still partly automate it. Use <command>lsdiff -nvv</command> to print some metadata about - the patch. <!-- &interaction.mq.tools.lsdiff; --></para> + the patch.</para> + + &interaction.mq.tools.lsdiff; <para>This command prints three different kinds of number:</para>
--- a/en/ch13-mq-collab.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch13-mq-collab.xml Mon Mar 09 23:22:09 2009 -0700 @@ -108,10 +108,13 @@ situation. MQ provides a feature called <quote>guards</quote> (which originates with quilt's <literal>guards</literal> command) that does just this. To start off, let's create a - simple repository for experimenting in. <!-- - &interaction.mq.guards.init; --> This gives us a tiny repository - that contains two patches that don't have any dependencies on - each other, because they touch different files.</para> + simple repository for experimenting in.</para> + + &interaction.mq.guards.init; + + <para>This gives us a tiny repository that contains two patches + that don't have any dependencies on each other, because they + touch different files.</para> <para>The idea behind conditional application is that you can <quote>tag</quote> a patch with a <emphasis>guard</emphasis>, @@ -133,14 +136,20 @@ <para>The <command role="hg-ext-mq">qguard</command> command lets you determine which guards should apply to a patch, or display the guards that are already in effect. Without any arguments, it - displays the guards on the current topmost patch. <!-- - &interaction.mq.guards.qguard; --> To set a positive guard on a - patch, prefix the name of the guard with a - <quote><literal>+</literal></quote>. <!-- - &interaction.mq.guards.qguard.pos; --> To set a negative guard + displays the guards on the current topmost patch.</para> + + &interaction.mq.guards.qguard; + + <para>To set a positive guard on a patch, prefix the name of the + guard with a <quote><literal>+</literal></quote>.</para> + + &interaction.mq.guards.qguard.pos; + + <para>To set a negative guard on a patch, prefix the name of the guard with a - <quote><literal>-</literal></quote>. <!-- - &interaction.mq.guards.qguard.neg; --></para> + <quote><literal>-</literal></quote>.</para> + + &interaction.mq.guards.qguard.neg; <note> <para> The <command role="hg-ext-mq">qguard</command> command @@ -158,8 +167,9 @@ other words, you don't have to use the <command role="hg-ext-mq">qguard</command> command if you don't want to; it's okay to simply edit the <filename - role="special">series</filename> file.) <!-- - &interaction.mq.guards.series; --></para> + role="special">series</filename> file.)</para> + + &interaction.mq.guards.series; </sect1> <sect1> @@ -175,26 +185,38 @@ <para>With no arguments, the <command role="hg-ext-mq">qselect</command> command lists the guards currently in effect, one per line of output. Each argument is - treated as the name of a guard to apply. <!-- - &interaction.mq.guards.qselect.foo; --> In case you're - interested, the currently selected guards are stored in the - <filename role="special">guards</filename> file. <!-- - &interaction.mq.guards.qselect.cat; --> We can see the effect - the selected guards have when we run <command - role="hg-ext-mq">qpush</command>. <!-- - &interaction.mq.guards.qselect.qpush; --></para> + treated as the name of a guard to apply.</para> + + &interaction.mq.guards.qselect.foo; + + <para>In case you're interested, the currently selected guards are + stored in the <filename role="special">guards</filename> file.</para> + + &interaction.mq.guards.qselect.cat; + + <para>We can see the effect the selected guards have when we run + <command role="hg-ext-mq">qpush</command>.</para> + + &interaction.mq.guards.qselect.qpush; <para>A guard cannot start with a <quote><literal>+</literal></quote> or <quote><literal>-</literal></quote> character. The name of a guard must not contain white space, but most other characters are acceptable. If you try to use a guard with an invalid name, - MQ will complain: <!-- &interaction.mq.guards.qselect.error; --> - Changing the selected guards changes the patches that are - applied. <!-- &interaction.mq.guards.qselect.quux; --> You can - see in the example below that negative guards take precedence - over positive guards. <!-- - &interaction.mq.guards.qselect.foobar; --></para> + MQ will complain:</para> + + &interaction.mq.guards.qselect.error; + + <para>Changing the selected guards changes the patches that are + applied.</para> + + &interaction.mq.guards.qselect.quux; + + <para>You can see in the example below that negative guards take + precedence over positive guards.</para> + + &interaction.mq.guards.qselect.foobar; </sect1> <sect1>
--- a/en/ch14-hgext.xml Mon Mar 09 22:55:38 2009 -0700 +++ b/en/ch14-hgext.xml Mon Mar 09 23:22:09 2009 -0700 @@ -267,11 +267,14 @@ role="hg-ext">extdiff</literal> extension</title> <para>Mercurial's built-in <command role="hg-cmd">hg - diff</command> command outputs plaintext unified diffs. <!-- - &interaction.extdiff.diff; --> If you would like to use an - external tool to display modifications, you'll want to use the - <literal role="hg-ext">extdiff</literal> extension. This will - let you use, for example, a graphical diff tool.</para> + diff</command> command outputs plaintext unified diffs.</para> + + &interaction.extdiff.diff; + + <para>If you would like to use an external tool to display + modifications, you'll want to use the <literal + role="hg-ext">extdiff</literal> extension. This will let you + use, for example, a graphical diff tool.</para> <para>The <literal role="hg-ext">extdiff</literal> extension is bundled with Mercurial, so it's easy to set up. In the <literal @@ -283,12 +286,14 @@ role="hg-ext-extdiff">extdiff</command>, which by default uses your system's <command>diff</command> command to generate a unified diff in the same form as the built-in <command - role="hg-cmd">hg diff</command> command. <!-- - &interaction.extdiff.extdiff; --> The result won't be exactly - the same as with the built-in <command role="hg-cmd">hg - diff</command> variations, because the output of - <command>diff</command> varies from one system to another, even - when passed the same options.</para> + role="hg-cmd">hg diff</command> command.</para> + + &interaction.extdiff.extdiff; + + <para>The result won't be exactly the same as with the built-in + <command role="hg-cmd">hg diff</command> variations, because the + output of <command>diff</command> varies from one system to + another, even when passed the same options.</para> <para>As the <quote><literal>making snapshot</literal></quote> lines of output above imply, the <command @@ -341,8 +346,9 @@ diffs (using the <option role="cmd-opt-diff">-c</option> option) instead of unified diffs, and five lines of context instead of the default three (passing <literal>5</literal> as the argument - to the <option role="cmd-opt-diff">-C</option> option). <!-- - &interaction.extdiff.extdiff-ctx; --></para> + to the <option role="cmd-opt-diff">-C</option> option).</para> + + &interaction.extdiff.extdiff-ctx; <para>Launching a visual diff tool is just as easy. Here's how to launch the <command>kdiff3</command> viewer.</para>