We are currently indexing your data, so search results may be incomplete until we finish.
|
|
*******
Patches
*******
.. module:: patches
:synopsis: Describe patch operations
Defining a patch
================
These links are recommended reading for understanding the history and nature
of patches and how they can be used with Mercurial.
* `The patch management problem <http://tortoisehg.bitbucket.org/hgbook/1.7/managing-change-with-mercurial-queues.html#sec:mq:patch-mgmt>`_
* `Understanding patches <http://tortoisehg.bitbucket.org/hgbook/1.7/managing-change-with-mercurial-queues.html#sec:mq:patch>`_
* `More about patches <http://tortoisehg.bitbucket.org/hgbook/1.7/managing-change-with-mercurial-queues.html#sec:mq:adv-patch>`_
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 its 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 <http://www.selenic.com/mercurial/hgrc.5.html#diff>`_ 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
.. note::
When eol is set to *auto*, the patching engine will preserve the line
endings of the patched file regardless of the line endings in the
patch itself. You almost always want eol to be configured to *auto*.
The only downside is that you cannot make a patch that changes the
line endings of a source file.
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 <http://www.selenic.com/mercurial/hgrc.5.html#patch>`_
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 2.0 includes a :command:`thg
rejects` command that can aid in the merging of the rejected chunks into
the source file.
Export Patches
==============
Changeset
---------
To export a changeset as a patch file, use the changeset context menu of
the Workbench to select :menuselection:`Export --> Export Patch`. It
writes the changeset to a file in the repository root folder.
Changeset Ranges
----------------
Select the start and end of a range of changesets in the Workbench and
open the special revision range context menu. From this menu you can
generate patches, generate a bundle, send emails, or visually diff the
accumulated changes.
This is a very powerful feature and there is no restriction on the base
and target changesets you can select.
Email
-----
.. figure:: figures/email.png
:alt: Email dialog
Email dialog of Workbench
To send a changeset as an email, use the changeset context menu of the
Workbench. :menuselection:`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 Workbench and select :menuselection:`Email selected...` or
:menuselection:`Email DAG range...`.
Lastly, you can use the :guilabel:`Email` button on the sync tab of the
Workbench to email all outgoing changes to the selected remote
repository.
.. note::
You must configure
`SMTP <http://www.selenic.com/mercurial/hgrc.5.html#smtp>`_
to send patches via email
Cherry Picking
--------------
Use the changeset range selection feature of the Repository Explorer and
select :menuselection:`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
:guilabel:`Save Preview` tab. Pressing :guilabel:`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.
Import Patches
==============
.. figure:: figures/import.png
:alt: 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 :command:`thg import`. The dialog supports
file and directory drag and drop.
You have the choice of importing directly into the repository, the
working folder, or 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.
Patch Queues
============
.. figure:: figures/patchqueue.png
:alt: 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.
.. vim: noet ts=4
|
Loading...