Although you can pull changes directly from other people’s repositories too, and this may the best way to handle very large external contributions such as reintegrating forks, generally external contributions are still handled via patches. There’s a difference between patches in Mercurial and patches for Subversion or CVS though, because patches in centralised systems are always a one-shot deal of a working copy compared against a single upstream version. In Mercurial, because contributors can commit locally, patches are actually exported changesets, with a full commit history. This fine grained change information can make patches easier to integrate, but it also comes with some added considerations. We’ll talk about generating and consuming patches in this section.
This is the recommended approach to generating patches. As mentioned above, in Mercurial you can generate patches from your local commits. This is quite simple:
hg export --git -o %b_patch%nof%N_%h.patch REVS
Replace REVS with a list of revisions, or a range such as REV1:REV2. It will create one file per changeset named something like ogre_patch1of2_f0c47360a828.diff. You should zip them up and send them to the patch list. If you’ve configured Mercurial the way we recommended in the Mercurial configuration section, the --git is unecessary because it’s the default, but it’s included for completeness.
There are alternative ways to generate patches, but they’re not recommended unless you know what you’re doing.
- Piped output
- It’s possible to just pipe the output from "hg export" to a single file for multiple changesets, instead of saving each changeset to its own file. However with a single file, a failure to import one of the changesets will cause the entire file to fail, so it’s more fragile when importing. Separate patch files are easier to process.
- Working copy diff
- You can also generate patches from your working copy if you want, using "hg diff" but these patches lack context so are not a good substitute for exporting actual commits which specify their parents. You might want to use this to post something quickly on a forum as a test, or to exchange work-in-progress information, but not for submitting patches.
- PatchBomb extension
- The PatchBomb extension can be used to email many patches at once, but its reliance on email (and thus mailing lists) makes it not that useful to us, since we use a dedicated patch list.
- Mercurial Queues (MQ)
- MQ allows vastly more complex handling of patches, particularly for those wanting to keep track of non-core alterations and to consolidate sets of commits into a smaller list for submission upstream. You can read about them in the Mercurial Manual. We won’t talk about MQ here because it isn’t needed unless your requirements are fairly complex.
Applying patches is also fairly simple in itself, but there are a couple of nuances. Here’s the standard command:
hg import PATCH_FILES...
It doesn’t matter whether the patch file is in GNU style or Git style, it will work either way. But it’s important to understand what this does - each patch file (usually) contains a single commit, and those commits are applied on top of your current repository, on to your current branch. Unlike a patch for Subversion, which applies to your working copy which you then need to commit, this actually transfers commits directly, including the original author names & emails.
![[Note]](images/icons/note.png){kind=icon} | Note |
|---|---|
Well, at least it tries to preserve the author & commit message, if the patch was generated from a commit using hg export. If alternatively the patch was generated from hg diff in a working copy, or the header was chopped off by someone before submission, then actually hg import will bring up your editor and asks you to provide a new commit message (and will commit it under your own name). |
![[Tip]](images/icons/tip.png){kind=icon} | Tip |
|---|---|
If you would prefer to just import the patch into your working copy rather than as a commit, use "hg import --no-commit PATCH_FILES…" |
Because it tries to apply the commits in the patch to the current base, failures are possible if conflicting changes have occurred. In this case, hg import just aborts. A good way to deal with this is to use the --exact parameter, which then applies the changes to the revision that is listed as the base in the patch file (which should therefore always succeed unless the patch is broken). This will create one or more new heads on the branch in question which you should then merge or rebase into your own branch, resolving the conflicts as appropriate. See Parallel Development for more information.