Mercurial: The Definitive Guide

Good Ways to Work with Patches

Whether you are working on a patch series to submit to a free software or open source project, or a series that you intend to treat as a sequence of regular changesets when you’re done, you can use some simple techniques to keep your work well organized.

Give your patches descriptive names. A good name for a patch might be rework-device-alloc.patch, because it will immediately give you a hint of the purpose of the patch. Long names shouldn’t be a problem; you won’t be typing the names often, but you will be running commands like qapplied and qtop over and over. Good naming becomes especially important when you have a number of patches to work with, or if you are juggling a number of different tasks and your patches only get a fraction of your attention.

Be aware of what patch you’re working on. Use the qtop command and skim over the text of your patches frequently—for example, using hg tip -p—to be sure of where you stand. I have several times worked on and qrefreshed a patch other than the one I intended, and it’s often tricky to migrate changes into the right patch after making them in the wrong one.

For this reason, it is very much worth investing a little time to learn how to use some of the third-party tools I described in Third-Party Tools for Working with Patches, particularly diffstat and filterdiff. The former will give you a quick idea of what changes your patch is making, while the latter makes it easy to splice hunks selectively out of one ...