Mercurial_ The Definitive Guide - Bryan O'Sullivan [96]
patch cannot represent empty files, so you cannot use a patch to represent the notion “I added this empty file to the tree.”
Beware the Fuzz
Although applying a hunk at an offset, or with a fuzz factor, will often be completely successful, these inexact techniques naturally leave open the possibility of corrupting the patched file. The most common cases typically involve applying a patch twice, or at an incorrect location in the file. If patch or qpush ever mentions an offset or fuzz factor, you should make sure that the modified files are correct afterwards.
It’s often a good idea to refresh a patch that has applied with an offset or fuzz factor; refreshing the patch generates new context information that will make it apply cleanly. I say “often,” not “always,” because sometimes refreshing a patch will make it fail to apply against a different revision of the underlying files. In some cases, such as when you’re maintaining a patch that must sit on top of multiple versions of a source tree, it’s acceptable to have a patch apply with some fuzz, provided you’ve verified the results of the patching process in such cases.
Handling Rejection
If qpush fails to apply a patch, it will print an error message and exit. If it has left .rej files behind, it is usually best to fix up the rejected hunks before you push more patches or do any further work.
If your patch used to apply cleanly, and no longer does because you’ve changed the underlying code that your patches are based on, Mercurial Queues can help; see Updating Your Patches When the Underlying Code Changes for details.
Unfortunately, there aren’t any great techniques for dealing with rejected hunks. Most often, you’ll need to view the .rej file and edit the target file, applying the rejected hunks by hand.
A Linux kernel hacker, Chris Mason (the author of Mercurial Queues), wrote a tool called mpatch (http://oss.oracle.com/~mason/mpatch/), which takes a simple approach to automating the application of hunks rejected by patch. The mpatch command can help with four common reasons that a hunk may be rejected:
The context in the middle of a hunk has changed.
A hunk is missing some context at the beginning or end.
A large hunk might apply better—either entirely or in part—if it was broken up into smaller hunks.
A hunk removes lines with slightly different content than those currently present in the file.
If you use mpatch, you should be doubly careful to check your results when you’re done. In fact, mpatch enforces this method of double-checking the tool’s output, by automatically dropping you into a merge program when it has done its job so that you can verify its work and finish off any remaining merges.
More on Patch Management
As you grow familiar with MQ, you will find yourself wanting to perform other kinds of patch management operations.
Deleting Unwanted Patches
If you want to get rid of a patch, use the hg qdelete command to delete the patch file and remove its entry from the patch series. If you try to delete a patch that is still applied, hg qdelete will refuse.
$ hg init myrepo
$ cd myrepo
$ hg qinit
$ hg qnew bad.patch
$ echo a > a
$ hg add a
$ hg qrefresh
$ hg qdelete bad.patch
abort: cannot delete applied patch bad.patch
$ hg qpop
patch queue now empty
$ hg qdelete bad.patch
Converting to and from Permanent Revisions
Once you’re done working on a patch and want to turn it into a permanent changeset, use the hg qfinish command. Pass a revision to the command to identify the patch that you want to turn into a regular changeset; this patch must already be applied.
$ hg qnew good.patch
$ echo a > a
$ hg add a
$ hg qrefresh -m 'Good change'
$ hg qfinish tip
$ hg qapplied
$ hg tip --style=compact
0[tip] 3c8b7fe3998b 2009-05-05 06:44 +0000 bos
Good change
The hg qfinish command accepts an --all or -a