Watch out!

# HG changeset patch # User Bryan O'Sullivan # Date 1236666129 25200 # Node ID 8fcd44708f41bbc96f87ec4b9018fd381becca06 # Parent 27043f385f3fbcc4e2907c261c5f1481f12573bd Uncomment all the mangled interaction examples. diff -r 27043f385f3f -r 8fcd44708f41 en/ch03-tour-merge.xml --- 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. - + &interaction.tour.merge.clone; We should now have two copies of hello.c with different contents. The @@ -39,7 +39,7 @@ illustrated in figure . - + &interaction.tour.merge.cat; @@ -56,7 +56,7 @@ class="directory">my-hello repository will have no effect on the working directory. - + &interaction.tour.merge.pull; However, the hg pull command says something about heads. @@ -96,7 +96,7 @@ We can view the heads in a repository using the hg heads command. - + &interaction.tour.merge.heads; @@ -106,7 +106,7 @@ role="hg-cmd">hg update command to update to the new tip? - + &interaction.tour.merge.update; Mercurial is telling us that the hg update command won't do a merge; it won't update @@ -115,7 +115,7 @@ hg merge command to merge the two heads. - + &interaction.tour.merge.merge; @@ -133,7 +133,7 @@ parents and the contents of hello.c. - + &interaction.tour.merge.parents; @@ -144,14 +144,14 @@ role="hg-cmd">hg commit the results of the merge. - + &interaction.tour.merge.commit; 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 , you can see a @@ -273,12 +273,12 @@ 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 file. - + &interaction.tour-merge-conflict.cousin; 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.) - + &interaction.tour-merge-conflict.son; 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 hgmerge program to do the merge, because it @@ -307,7 +307,7 @@ XXX FIX THIS EXAMPLE. - + &interaction.tour-merge-conflict.merge; Because merge can't resolve the conflicting changes, it leaves merge @@ -326,7 +326,7 @@ prevent us from fixing up the affected files ourselves, and committing the results of our merge: - + &interaction.tour-merge-conflict.commit; diff -r 27043f385f3f -r 8fcd44708f41 en/ch05-daily.xml --- 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 hg status for that file changes from ? to - A. + A. + + &interaction.daily.files.add; After you run a hg commit, the files that you added before the commit will no longer be @@ -45,11 +46,14 @@ 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. 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. + this directory and its subdirectories. + + &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 a in the earlier + example. 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. - +&interaction.daily.files.hidden; 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 hg status with a - R. + R. + + &interaction.daily.files.remove; After you hg remove a file, Mercurial will no longer track changes to that file, even if you @@ -152,7 +157,9 @@ represented with ! in the output of hg status. Mercurial commands will not generally do anything with missing - files. + files. + + &interaction.daily.files.missing; If your repository contains a file that hg status reports as missing, and @@ -160,15 +167,16 @@ role="hg-cmd">hg remove at any time later on, to tell Mercurial that you really did mean to - remove the file. + remove the file. + + &interaction.daily.files.remove-after; On the other hand, if you deleted the missing file by accident, give hg revert the name of the file to recover. It will reappear, in unmodified form. - +&interaction.daily.files.recover-missing; @@ -191,12 +199,16 @@ Mercurial offers a combination command, hg addremove, that adds untracked - files and marks missing files as removed. The hg commit command also provides a - option that performs - this same add-and-remove, immediately followed by a commit. - + files and marks missing files as removed. + + &interaction.daily.files.addremove; + + The hg commit command + also provides a + option that performs this same add-and-remove, immediately + followed by a commit. + + &interaction.daily.files.commit-addremove; @@ -216,34 +228,49 @@ What happens during a merge is that changes follow 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. We need to do some work in + tiny repository that contains a single file. + + &interaction.daily.copy.init; + + We need to do some work in parallel, so that we'll have something to merge. So let's - clone our repository. - Back in our initial repository, let's use the + + &interaction.daily.copy.clone; + + Back in our initial repository, let's use the hg copy command to make a copy of - the first file we created. + the first file we created. + + &interaction.daily.copy.copy; If we look at the output of the hg status command afterwards, the copied file looks - just like a normal added file. But if we pass the + + &interaction.daily.copy.status-copy; 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. Now - we have a modified file in this + that we created. + + &interaction.daily.copy.other; + + Now we have a modified file 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 file - into its copy, new-file. + into its copy, new-file. + + &interaction.daily.copy.merge; @@ -327,22 +354,33 @@ destination, and all prior arguments are sources. If you pass it a single file as the source, and the destination does not exist, it creates a - new file with that name. If the destination is a directory, Mercurial copies its - sources into that directory. Copying a directory is + 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 recursive, and preserves the directory structure of the - source. If the - source and destination are both directories, the source tree - is recreated in the destination directory. + 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; As with the hg rename command, if you copy a file manually and then want Mercurial to know that you've copied the file, simply use the option to hg copy. + role="hg-cmd">hg copy. + + &interaction.daily.copy.after; @@ -359,17 +397,24 @@ When you use the hg rename command, Mercurial makes a copy of each source file, then - deletes it and marks the file as removed. The hg status command shows the newly - copied file as added, and the copied-from file as removed. As with the results of a - hg copy, we must use the - option to + + &interaction.daily.rename.rename; + + The hg status 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 hg + copy, we must use the option to hg status to see that the added file is really being tracked by Mercurial as a copy of the original, - now removed, file. + now removed, file. + + &interaction.daily.rename.status-copy; As with hg remove and hg copy, you can tell Mercurial @@ -410,11 +455,16 @@ foo&emdash;in their respective repositories. - Anne renames - the file to bar. Meanwhile, Bob - renames it to quux. + &interaction.rename.divergent.clone; + + Anne renames the file to bar. + + &interaction.rename.divergent.rename.anne; + + Meanwhile, Bob renames it to + quux. + + &interaction.rename.divergent.rename.bob; I like to think of this as a conflict because each developer has expressed different intentions about what the @@ -423,8 +473,9 @@ What do you think should happen when they merge their work? Mercurial's actual behaviour is that it always preserves both names when it merges changesets that - contain divergent renames. + contain divergent renames. + + &interaction.rename.divergent.merge; 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 issue - 29. + 29. + + &interaction.issue29.go; diff -r 27043f385f3f -r 8fcd44708f41 en/ch06-collab.xml --- 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 @@ Here's an example of how this can work in practice. Let's say you have one main branch on a central - server. People clone it, - make changes locally, test them, and push them back. + server. + + &interaction.branching.init; + + People clone it, make changes locally, test them, and push + them back. Once the main branch reaches a release milestone, you can use the hg tag command to - give a permanent name to the milestone revision. Let's say some ongoing - development occurs on the main branch. Using the tag that was - recorded at the milestone, people who clone that repository at - any time in the future can use hg - update to get a copy of the working directory - exactly as it was when that tagged revision was committed. - + 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 + hg update to get a copy of + the working directory exactly as it was when that tagged + revision was committed. + + &interaction.branching.update; In addition, immediately after the main branch is tagged, someone can then clone the main branch on the server to a new - stable branch, also on the server. + stable branch, also on the server. + + &interaction.branching.clone; Someone who needs to make a change to the stable branch can then clone that repository, make - their changes, commit, and push their changes back there. Because Mercurial - repositories are independent, and Mercurial doesn't move - changes around automatically, the stable and main branches are - isolated from each other. The changes - that you made on the main branch don't leak to - the stable branch, and vice versa. + 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 isolated + from each other. The changes that you made on the main branch + don't leak to the stable branch, and vice + versa. 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. 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. + 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. diff -r 27043f385f3f -r 8fcd44708f41 en/ch07-filenames.xml --- 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 @@ 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 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 encounters a subdirectory, it will traverse that subdirectory - before continuing with the current directory. + before continuing with the current directory. + + &interaction.filenames.dirs; @@ -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 - .. + .. + + &interaction.filenames.wdir-subdir; 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 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 hg root command. + role="hg-cmd">hg root command. + + &interaction.filenames.wdir-relname; @@ -139,18 +142,21 @@ when you're matching on glob patterns. The * character matches - any string, within a single directory. + any string, within a single directory. + + &interaction.filenames.glob.star; The ** 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. + Unix shells, and is very useful. + + &interaction.filenames.glob.starstar; The ? pattern matches - any single character. + any single character. + + &interaction.filenames.glob.question; The [ character begins a character class. This matches any single @@ -158,19 +164,23 @@ ] character. A class may contain multiple ranges of the form a-f, which is shorthand for - abcdef. If the first character - after the [ in a character - class is a !, it + abcdef. + + &interaction.filenames.glob.range; + + If the first character after the + [ in a character class is a + !, it negates the class, making it match any single character not in the class. A { begins a group of subpatterns, where the whole group matches if any subpattern in the group matches. The , - character separates subpatterns, and } - ends the group. + character separates subpatterns, and + } ends the group. + + &interaction.filenames.glob.group; Watch out! @@ -180,8 +190,9 @@ * match-any token, as this will only match within one directory. Instead, use the ** token. This small - example illustrates the difference between the two. + example illustrates the difference between the two. + + &interaction.filenames.glob.star-starstar; @@ -245,11 +256,15 @@ You can read a filter as process only the files that match this - filter. The filter is best + filter. + + &interaction.filenames.filter.include; + + The filter is best read as process only the files that don't match this - pattern. + pattern. + + &interaction.filenames.filter.exclude; diff -r 27043f385f3f -r 8fcd44708f41 en/ch08-branch.xml --- 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; Mercurial lets you give a permanent name to any revision using the hg tag command. Not - surprisingly, these names are called tags. + surprisingly, these names are called tags. + + &interaction.tag.tag; A tag is nothing more than a symbolic name 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. Notice that - tip is listed in the output of hg tags. The tip - tag is a special floating tag, which always - identifies the newest revision in the repository. + revision. + + &interaction.tag.tags; + + Notice that tip is listed in the output + of hg tags. The + tip tag is a special floating + tag, which always identifies the newest revision in the + repository. In the output of the hg tags command, tags are listed in reverse order, by @@ -73,13 +78,16 @@ When you run hg log, if it displays a revision that has tags associated with it, it will - print those tags. + print those tags. + + &interaction.tag.log; 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. + corresponding revision ID, then use that. + + &interaction.tag.log.v1.0; 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. If you want to remove a tag that you no longer want, use - hg tag --remove. You can also modify a tag at any - time, so that it identifies a different revision, by simply - issuing a new hg tag command. - You'll have to use the - option to tell Mercurial that you really - want to update the tag. 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. + hg tag --remove. + + &interaction.tag.remove; + + You can also modify a tag at any time, so that it identifies + a different revision, by simply issuing a new hg tag command. You'll have to use the + option to tell Mercurial + that you really 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. 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 hg tag, you'll see a corresponding changeset in the - output of hg log. + output of hg log. + + &interaction.tag.tip; Handling tag conflicts during a merge @@ -247,19 +262,28 @@ myproject&emdash;that reaches a 1.0 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. You can then clone a new - shared myproject-1.0.1 repository as of that - tag. + revision from which you prepared the 1.0 release. + + &interaction.branch-repo.tag; + + You can then clone a new shared + myproject-1.0.1 repository as of that + tag. + + &interaction.branch-repo.clone; 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 myproject-1.0.1 repository, make their - changes, and push them back. Meanwhile, development for + changes, and push them back. + + &interaction.branch-repo.bugfix; + + Meanwhile, development for the next major release can continue, isolated and unabated, in - the myproject repository. + the myproject repository. + + &interaction.branch-repo.new; @@ -275,9 +299,14 @@ In the simplest instance, all you need to do is pull changes from your maintenance branch into your local clone of the target - branch. You'll then need - to merge the heads of the two branches, and push back to the - main branch. + 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; @@ -318,27 +347,34 @@ To start working with named branches, use the hg branches command. This command lists the named branches already present in your repository, - telling you which changeset is the tip of each. Since you haven't - created any named branches yet, the only one that exists is - default. + 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 default. To find out what the current branch is, run the hg branch command, giving it no arguments. This tells you what branch the parent of the - current changeset is on. + current changeset is on. + + &interaction.branch-named.branch; To create a new branch, run the hg branch command again. This time, give it one - argument: the name of the branch you want to create. + argument: the name of the branch you want to create. + + &interaction.branch-named.create; After you've created a branch, you might wonder what effect the hg branch command has had. What do the hg status and - hg tip commands report? Nothing has changed in the + hg tip commands report? + + &interaction.branch-named.status; + + Nothing has changed in the working directory, and there's been no new history created. As this suggests, running the hg branch 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 hg log, hg tip, and other commands that - display the same kind of output. The hg log-like commands will print the - branch name of every changeset that's not on the + display the same kind of output. + + &interaction.branch-named.commit; + + The hg log-like commands + will print the branch name of every changeset that's not on the default branch. As a result, if you never use named branches, you'll never see this information. @@ -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 hg - branch command. 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.) + branch 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.) @@ -385,28 +425,34 @@ 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. We're on the - bar branch, but there also exists an older - hg foo branch. + currently on, and what branches are in our repository. + + &interaction.branch-named.parents; + + We're on the bar branch, but there also + exists an older hg foo + branch. We can hg update back and forth between the tips of the foo and bar branches without needing to use the option, because this only involves going backwards and forwards linearly through our - change history. + change history. + + &interaction.branch-named.update-switchy; If we go back to the foo branch and then run hg update, it will keep us on foo, not move us to the tip of - bar. + bar. + + &interaction.branch-named.update-nothing; Committing a new change on the foo branch - introduces a new head. + introduces a new head. + + &interaction.branch-named.foo-commit; @@ -439,8 +485,9 @@ But if I'm working on the bar branch, and I merge work from the foo branch, the result - will remain on the bar branch. + will remain on the bar branch. + + &interaction.branch-named.merge; To give a more concrete example, if I'm working on the bleeding-edge branch, and I want to bring in diff -r 27043f385f3f -r 8fcd44708f41 en/ch09-undo.xml --- 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 @@ Here's a mistake that I often find myself making: committing a change in which I've created a new file, but - forgotten to hg add it. Looking at the output of - hg status after the commit - immediately confirms the error. The commit captured the - changes to the file a, but not the new - file b. If I were to push this changeset - to a repository that I shared with a colleague, the chances - are high that something in a would refer - to b, which would not be present in their + forgotten to hg add + it. + + &interaction.rollback.commit; + + Looking at the output of hg + status after the commit immediately confirms the + error. + + &interaction.rollback.status; + + The commit captured the changes to the file + a, but not the new file + b. If I were to push this changeset to a + repository that I shared with a colleague, the chances are + high that something in a would refer to + b, which would not be present in their repository when they pulled my changes. I would thus become the object of some indignation. However, luck is with me&emdash;I've caught my error before I pushed the changeset. I use the hg rollback command, and Mercurial - makes that last changeset vanish. Notice that the changeset - is no longer present in the repository's history, and the - working directory once again thinks that the file - a 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 hg add the file - b, and rerun my commit. + 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 a 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 hg + add the file b, and rerun my + commit. + + &interaction.rollback.add; @@ -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. - 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. + + &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 another commit or pull. @@ -161,14 +175,22 @@ Let's illustrate how the hg revert command works with yet another small example. We'll begin by modifying a file that Mercurial is already - tracking. If we don't + tracking. + + &interaction.daily.revert.modify; + + If we don't want that change, we can simply hg - revert the file. The hg revert command provides us with an - extra degree of safety by saving our modified file with a - .orig extension. + revert the file. + + &interaction.daily.revert.unmodify; + + The hg revert command + provides us with an extra degree of safety by saving our + modified file with a .orig + extension. + + &interaction.daily.revert.status; Here is a summary of the cases that the hg revert command can deal with. We @@ -204,25 +226,28 @@ then decide that in fact you don't want Mercurial to track it, use hg revert to undo the add. Don't worry; Mercurial will not modify the file in any - way. It will just unmark the file. + way. It will just unmark the file. + + &interaction.daily.revert.add; Similarly, if you ask Mercurial to hg remove a file, you can use hg revert to restore it to the contents it had as of the parent of the working directory. - 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 missing). + file is called missing). + + &interaction.daily.revert.missing; If you revert a hg copy, 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. + with the copied-from file. + + &interaction.daily.revert.copy; A slightly special case: reverting a rename @@ -231,17 +256,23 @@ file, there is one small detail that you should remember. When you hg revert a rename, it's not enough to provide the name of the - renamed-to file, as you can see here. As you can see from - the output of hg status, - the renamed-to file is no longer identified as added, but - the renamed-from file is still removed! + renamed-to file, as you can see here. + + &interaction.daily.revert.rename; + + As you can see from the output of hg status, the renamed-to file is + no longer identified as added, but the + renamed-from file is still removed! This is counter-intuitive (at least to me), but at least - it's easy to deal with. So remember, to - revert a hg rename, you - must provide both the source and - destination names. + it's easy to deal with. + + &interaction.daily.revert.rename-orig; + + So remember, to revert a hg + rename, you must provide + both the source and destination + names. % TODO: the output doesn't look like it will be removed! @@ -291,8 +322,9 @@ The operation of the hg backout command is a little intricate, so let's illustrate it with some examples. First, we'll create a - repository with some simple changes. + repository with some simple changes. + + &interaction.backout.init; The hg backout command takes a single changeset ID as its argument; this is the @@ -308,15 +340,19 @@ Backing out the tip changeset We're going to start by backing out the last changeset we - committed. You can see - that the second line from myfile is no - longer present. Taking a look at the output of hg log gives us an idea of what the - hg backout command has done. - Notice that the new - changeset that hg backout has - created is a child of the changeset we backed out. It's - easier to see this in figure + + &interaction.backout.simple; + + You can see that the second line from + myfile is no longer present. Taking a + look at the output of hg log + gives us an idea of what the hg + backout command has done. + &interaction.backout.simple.log; Notice that the new changeset + that hg backout has created + is a child of the changeset we backed out. It's easier to see + this in figure , which presents a graphical view of the change history. As you can see, the history is nice and linear. @@ -338,16 +374,22 @@ If you want to back out a change other than the last one you committed, pass the option to the - hg backout command. This makes backing out - any changeset a one-shot operation that's - usually simple and fast. + hg backout command. + + &interaction.backout.non-tip.clone; + + This makes backing out any changeset a + one-shot operation that's usually simple and + fast. + + &interaction.backout.non-tip.backout; If you take a look at the contents of myfile after the backout finishes, you'll see that the first and third changes are present, but not the - second. + second. + + &interaction.backout.non-tip.cat; As the graphical history in figure illustrates, Mercurial @@ -404,15 +446,21 @@ clone our first repository, but omit the backout change that it contains. - As with our + &interaction.backout.manual.clone; + + As with our earlier example, We'll commit a third changeset, then back out - its parent, and see what happens. Our new changeset is - again a descendant of the changeset we backout out; it's thus - a new head, not a descendant of the - changeset that was the tip. The hg - backout command was quite explicit in telling us - this. + 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, not + a descendant of the changeset that was the tip. The hg backout command was quite + explicit in telling us this. + + &interaction.backout.manual.log; Again, it's easier to see what has happened by looking at a graph of the revision history, in figure After the hg backout command has completed, it leaves the new backout changeset as the parent of the working - directory. Now - we have two isolated sets of changes. + directory. + + &interaction.backout.manual.parents; + + Now we have two isolated sets of changes. + + &interaction.backout.manual.heads; Let's think about what we expect to see as the contents of myfile 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 don't expect to see the third change - present in myfile. To get the third change - back into the file, we just do a normal merge of our two - heads. Afterwards, - the graphical history of our repository looks like figure + present in myfile. + + &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 . @@ -731,19 +789,26 @@ Now let's create a repository, so that we can try out the hg bisect command in - isolation. 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 bug. This loop creates 35 - changesets, each adding a single file to the repository. - We'll represent our bug with a file that - contains the text i have a gub. + 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 + bug. This loop creates 35 changesets, each + adding a single file to the repository. We'll represent our + bug with a file that contains the text i + have a gub. + + &interaction.bisect.commits; The next thing that we'd like to do is figure out how to use the hg bisect command. We can use Mercurial's normal built-in help mechanism for - this. + this. + + &interaction.bisect.help; The hg bisect command works in steps. Each step proceeds as follows. @@ -771,8 +836,9 @@ succeeding to failing. To start the search, we must run the hg bisect --reset command. + role="hg-cmd">hg bisect --reset command. + + &interaction.bisect.search.init; In our case, the binary test we use is simple: we check to see if any file in the repository contains the string i @@ -785,8 +851,9 @@ 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 - bad. + bad. + + &interaction.bisect.search.bad-init; Our next task is to nominate a changeset that we know doesn't have the bug; the bracket 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 good changeset later.) + the first good changeset later.) + + &interaction.bisect.search.good-init; Notice that this command printed some output. @@ -812,16 +880,21 @@ grep command to see if our bad file is present in the working directory. If it is, this revision is bad; if not, this revision is good. - + &interaction.bisect.search.step1; This test looks like a perfect candidate for automation, - so let's turn it into a shell function. We can now run an - entire test step with a single command, - mytest. A few more invocations - of our canned test step command, and we're done. + 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, + mytest. + + &interaction.bisect.search.step2; + + A few more invocations of our canned test step command, + and we're done. + + &interaction.bisect.search.rest; Even though we had 40 changesets to search through, the hg bisect command let us find @@ -844,8 +917,9 @@ forget to run this command. However, hg bisect won't let you start a new search in that repository until you do a hg bisect reset. + role="hg-cmd">hg bisect reset. + + &interaction.bisect.search.reset; diff -r 27043f385f3f -r 8fcd44708f41 en/ch10-hook.xml --- 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 @@ All hooks follow the pattern in this example. - +&interaction.hook.simple.init; You add an entry to the hooks section of your 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 extension to the end of a hook's name. @@ -438,7 +438,7 @@ commit hook is not run. - +&interaction.hook.simple.pretxncommit; 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. - +&interaction.hook.msglen.go; @@ -665,7 +665,7 @@ role="hg-cmd">hg commit again. - +&interaction.hook.ws.simple; In this example, we introduce a simple pretxncommit hook that checks for @@ -690,7 +690,7 @@ the saved commit message once you've corrected the problem. - +&interaction.hook.ws.better; As a final aside, note in the example above the use of perl's in-place editing feature to get rid diff -r 27043f385f3f -r 8fcd44708f41 en/ch11-template.xml --- 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 @@ 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 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 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 output style is named default. @@ -85,12 +85,12 @@ 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 change its output. - + &interaction.template.simple.simplest; 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. - + &interaction.template.simple.simplesub; As you can see, the string {desc} in the template has @@ -190,7 +190,7 @@ 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 human-readable output, so we must treat it specially. This @@ -198,7 +198,7 @@ in section . - + &interaction.template.simple.datekeyword; @@ -410,7 +410,7 @@ bos. - +&interaction.template.simple.manyfilters; 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). - + &interaction.template.simple.combine; Note the use of \t (a tab character) in the template to force the first line to be @@ -467,7 +467,7 @@ Our simple style file contains just one line: - + &interaction.template.simple.rev; This tells Mercurial, 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. - +&interaction.template.svnstyle.syntax.input; 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 hard to follow. @@ -580,9 +579,12 @@ 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. This - is not guaranteed to be unique, but it is nevertheless useful - in many cases. + repository. + + &interaction.template.svnstyle.id; + + This is not guaranteed to be unique, but it is + nevertheless useful in many cases. It will not work in a completely empty repository, because such a repository does not have a @@ -611,14 +613,16 @@ Mimicking Subversion's output Let's try to emulate the default output format used by - another revision control tool, Subversion. + another revision control tool, Subversion. + + &interaction.template.svnstyle.short; 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. + template values we'd like to see expanded. + + &interaction.template.svnstyle.template; There are a few small ways in which this template deviates from the output produced by Subversion. @@ -648,8 +652,9 @@ 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. + file simply refers to the template. + + &interaction.template.svnstyle.style; We could have included the text of the template file directly in the style file by enclosing it in quotes and diff -r 27043f385f3f -r 8fcd44708f41 en/ch12-mq.xml --- 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. - +&interaction.mq.dodiff.diff; The type of file that diff generates (and patch takes as input) is called a @@ -263,14 +263,14 @@ the qinit command is now available. - +&interaction.mq.qinit-help.help; 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 .hg/patches, where @@ -290,7 +290,7 @@ class="directory">.hg/patches directory, as you can see below. - +&interaction.mq.tutorial.qnew; Also newly present in the .hg/patches directory are two @@ -327,7 +327,7 @@ 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 working directory into your patch, and updates its @@ -340,7 +340,7 @@ doesn't work out, hg revert your modifications back to the last time you refreshed. - +&interaction.mq.tutorial.qrefresh2; @@ -352,7 +352,7 @@ 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 patch as part of its context (you can see this more clearly in the output of hg @@ -365,7 +365,7 @@ many commands that are easier to use when you are thinking about patches, as illustrated below. - +&interaction.mq.tutorial.qseries; The qpop and qpush in action. - +&interaction.mq.tutorial.qpop; Notice that once we have popped a patch or two patches, the output of qseries @@ -442,7 +442,7 @@ see section below.) - +&interaction.mq.tutorial.qpush-a; @@ -458,7 +458,7 @@ case by the hg add of file3. - +&interaction.mq.tutorial.add; Commands that check the working directory all take an I know what I'm doing option, which is always @@ -969,7 +969,7 @@ few normal Mercurial commands in use with applied patches. - +&interaction.mq.id.output; @@ -1126,7 +1126,7 @@ prefixes of file names that inevitably confuse at least me.) - +&interaction.mq.tools.tools; The patchutils package web:patchutils is invaluable. It provides a @@ -1196,16 +1196,22 @@ changes to a source tarball that you downloaded. Begin by downloading and unpacking the source tarball, and - turning it into a Mercurial repository. + turning it into a Mercurial repository. + + &interaction.mq.tarball.download; Continue by creating a patch stack and making your - changes. + changes. + + &interaction.mq.tarball.qinit; Let's say a few weeks or months pass, and your package author releases a new version. First, bring their changes - into the repository. The pipeline starting with hg + into the repository. + + &interaction.mq.tarball.newsource; + + The pipeline starting with hg locate above deletes all files in the working directory, so that hg commit's + + &interaction.mq.tarball.repush; @@ -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 lsdiff -nvv to print some metadata about - the patch. + the patch. + + &interaction.mq.tools.lsdiff; This command prints three different kinds of number: diff -r 27043f385f3f -r 8fcd44708f41 en/ch13-mq-collab.xml --- 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 guards (which originates with quilt's guards command) that does just this. To start off, let's create a - simple repository for experimenting in. This gives us a tiny repository - that contains two patches that don't have any dependencies on - each other, because they touch different files. + 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. The idea behind conditional application is that you can tag a patch with a guard, @@ -133,14 +136,20 @@ The qguard 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. To set a positive guard on a - patch, prefix the name of the guard with a - +. To set a negative guard + 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 +. + + &interaction.mq.guards.qguard.pos; + + To set a negative guard on a patch, prefix the name of the guard with a - -. + -. + + &interaction.mq.guards.qguard.neg; The qguard command @@ -158,8 +167,9 @@ other words, you don't have to use the qguard command if you don't want to; it's okay to simply edit the series file.) + role="special">series file.) + + &interaction.mq.guards.series; @@ -175,26 +185,38 @@ With no arguments, the qselect command lists the guards currently in effect, one per line of output. Each argument is - treated as the name of a guard to apply. In case you're - interested, the currently selected guards are stored in the - guards file. We can see the effect - the selected guards have when we run qpush. + 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 guards file. + + &interaction.mq.guards.qselect.cat; + + We can see the effect the selected guards have when we run + qpush. + + &interaction.mq.guards.qselect.qpush; A guard cannot start with a + or - 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: - Changing the selected guards changes the patches that are - applied. You can - see in the example below that negative guards take precedence - over positive guards. + 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; diff -r 27043f385f3f -r 8fcd44708f41 en/ch14-hgext.xml --- 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 extension Mercurial's built-in hg - diff command outputs plaintext unified diffs. If you would like to use an - external tool to display modifications, you'll want to use the - extdiff extension. This will - let you use, for example, a graphical diff tool. + diff 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 extdiff extension. This will let you + use, for example, a graphical diff tool. The extdiff extension is bundled with Mercurial, so it's easy to set up. In the extdiff, which by default uses your system's diff command to generate a unified diff in the same form as the built-in hg diff command. The result won't be exactly - the same as with the built-in hg - diff variations, because the output of - diff varies from one system to another, even - when passed the same options. + role="hg-cmd">hg diff command. + + &interaction.extdiff.extdiff; + + The result won't be exactly the same as with the built-in + hg diff variations, because the + output of diff varies from one system to + another, even when passed the same options. As the making snapshot lines of output above imply, the -c option) instead of unified diffs, and five lines of context instead of the default three (passing 5 as the argument - to the option). + to the option). + + &interaction.extdiff.extdiff-ctx; Launching a visual diff tool is just as easy. Here's how to launch the kdiff3 viewer.