7. Patches

7.1. Defining a patch

These links are recommended reading for understanding the history and nature of patches and how they can be used with Mercurial.

7.2. Pitfalls

The standard patch format cannot describe binary files, renames, copies, or permission changes. If your patch needs to record any of those things, you will need to enable git patches via:

[diff]
git=True

Mercurial 1.5 improves it’s behavior in this regard. It will warn you when git diffs are required, or sometimes upgrade to the git format automatically. See also the diff section of the hgrc documentation.

Mercurial’s patch routines do not deal well with mixed EOLN between source files and patches. The patch.eol setting was introduced in 1.3 to improve this situation:

[patch]
eol = auto #strict, lf, or crlf

The work on the hgeol extension is also improving this area. Perhaps it will be resolved by hg-1.5. See also the patch section of the hgrc documentation.

Applying a patch is not a foolproof operation. If the source file has diverged from the file that was used to create the patch, there may be conflicts during the patch application. These are written to a file with an .rej extension. TortoiseHg 1.0 includes an experimental hgtk mpatch command that can try harder to apply the rejected patch hunks. This command is based on Chris Mason’s mpatch utility. If mpatch cannot apply the rejected hunks, your only remaining choice is to apply them by hand.

7.3. Export Patches

7.3.1. Changeset

To export a changeset as a patch file, use the changeset context menu of the Repository Explorer to select Export ‣ Export Patch. You will be asked to provide a filename.

7.3.2. Changeset Ranges

Select a range of changesets in the Repository Explorer. Left click on the first (base) changeset, then right click on the last (target) changeset. This opens a special revision range context menu. From this menu you can generate patches, generate a bundle, send emails, or view the accumulated changes.

This is a very powerful feature and there is no restriction on the base and target changesets you can select.

7.3.3. Email

Email dialog

Email dialog of Repository Explorer

To send a changeset as an email, use the changeset context menu of the Repository Explorer. Export ‣ Email Patch. This opens the e-mail dialog for this single changeset.

To send a changeset range, use the changeset range selection feature of the Repository Explorer and select Email from here to selected...

Lastly, you can use the Email button on the syncbar of the Repository Explorer to email all outgoing changes to the selected remote repository.

Note

You must configure SMTP to send patches via email

7.3.4. Cherry Picking

Use the changeset range selection feature of the Repository Explorer and select Diff with selected. This opens up a status viewer showing you the accumulated changes between your base and target changesets.

From the status viewer, you can select files and diff hunks just as you can in the commit tool, and preview the final result in the Save Preview tab. Pressing Save As will save the selected changes to a patch file.

For even finer cherry-picking, you can highlight a number of diff-hunks in the hunk selection pane and hit CTRL-C. This will copy the highlighted (mouse selected, not toggled) hunks to the clipboard.

Note

Reversing the order of your changeset selection reverses the effect of the patch.

7.4. Import Patches

Import tool

Import dialog of Repository Explorer

The import dialog can be opened from the sync bar or menu of the Repository Explorer, or via hgtk import. The dialog supports file and directory drag and drop. The drop down menu in the upper right corner next to the Browse button has the options: Browse Directory.. and Import from Clipboard.

You have the choice of importing directly into the repository, or importing into your patch queue.

Note

Importing a patch requires a clean working directory state. You must commit, revert, or shelve changes before importing a patch.

Warning

If the patch you are importing does not have a commit message, Mercurial will try to launch your editor, just as if you had tried to import the patch from the command line. Your ui.editor needs to be a GUI app to make this work correctly.

7.5. Patch Queues

Patch Queue

Patch Queue panel in the Repository Explorer

Both the Repository Explorer and Commit Tool have an optional Patch Queue panel that is only available when the user has enabled the MQ extension. It allows the user to perform most patch queue operations including push, pop, rename, and finish. It’s recommended to learn the MQ extension before using the Patch Queue panel.