/doc/source/patches.txt

  1*******
  2Patches
  3*******
  4
  5.. module:: patches
  6	:synopsis: Describe patch operations
  7
  8Defining a patch
  9================
 10
 11These links are recommended reading for understanding the history and nature
 12of patches and how they can be used with Mercurial.
 13
 14* `The patch management problem <http://tortoisehg.bitbucket.org/hgbook/1.7/managing-change-with-mercurial-queues.html#sec:mq:patch-mgmt>`_
 15* `Understanding patches <http://tortoisehg.bitbucket.org/hgbook/1.7/managing-change-with-mercurial-queues.html#sec:mq:patch>`_
 16* `More about patches <http://tortoisehg.bitbucket.org/hgbook/1.7/managing-change-with-mercurial-queues.html#sec:mq:adv-patch>`_
 17
 18Pitfalls
 19========
 20
 21The standard patch format cannot describe binary files, renames, copies,
 22or permission changes.  If your patch needs to record any of those
 23things, you will need to enable **git** patches via::
 24
 25	[diff]
 26	git=True
 27
 28Mercurial 1.5 improves it's behavior in this regard.  It will warn you
 29when git diffs are required, or sometimes upgrade to the git format
 30automatically.  See also the
 31`diff section <http://www.selenic.com/mercurial/hgrc.5.html#diff>`_ of
 32the hgrc documentation.
 33
 34Mercurial's patch routines do not deal well with mixed EOLN between
 35source files and patches.  The **patch.eol** setting was introduced in
 361.3 to improve this situation::
 37
 38	[patch]
 39	eol = auto #strict, lf, or crlf
 40
 41The work on the hgeol extension is also improving this area.  Perhaps it
 42will be resolved by hg-1.5.  See also the
 43`patch section <http://www.selenic.com/mercurial/hgrc.5.html#patch>`_
 44of the hgrc documentation.
 45
 46Applying a patch is not a foolproof operation.  If the source file has
 47diverged from the file that was used to create the patch, there may be
 48conflicts during the patch application.  These are written to a file
 49with an .rej extension.  TortoiseHg 1.0 includes an experimental
 50:command:`hgtk mpatch` command that can try *harder* to apply the
 51rejected patch hunks.  This command is based on Chris Mason's `mpatch
 52<http://oss.oracle.com/~mason/mpatch/>`_ utility.  If mpatch cannot
 53apply the rejected hunks, your only remaining choice is to apply them by
 54hand.
 55
 56
 57Export Patches
 58==============
 59
 60Changeset
 61---------
 62
 63To export a changeset as a patch file, use the changeset context menu of
 64the Repository Explorer to select :menuselection:`Export --> Export Patch`.
 65You will be asked to provide a filename.
 66
 67Changeset Ranges
 68----------------
 69
 70Select a range of changesets in the Repository Explorer.  Left click on
 71the first (base) changeset, then right click on the last (target)
 72changeset.  This opens a special revision range context menu.  From this
 73menu you can generate patches, generate a bundle, send emails, or view
 74the accumulated changes.
 75
 76This is a very powerful feature and there is no restriction on the base
 77and target changesets you can select.
 78
 79Email
 80-----
 81
 82.. figure:: figures/email.png
 83	:alt: Email dialog
 84
 85	Email dialog of Repository Explorer
 86
 87To send a changeset as an email, use the changeset context menu of the
 88Repository Explorer. :menuselection:`Export --> Email Patch`.  This
 89opens the e-mail dialog for this single changeset.
 90
 91To send a changeset range, use the changeset range selection feature of
 92the Repository Explorer and select
 93:menuselection:`Email from here to selected...`
 94
 95Lastly, you can use the :guilabel:`Email` button on the syncbar of the
 96Repository Explorer to email all outgoing changes to the selected remote
 97repository.
 98
 99.. note::
100	You must configure
101	`SMTP <http://www.selenic.com/mercurial/hgrc.5.html#smtp>`_
102	to send patches via email
103
104Cherry Picking
105--------------
106
107Use the changeset range selection feature of the Repository Explorer and
108select :menuselection:`Diff with selected`.  This opens up a status
109viewer showing you the accumulated changes between your base and target
110changesets.
111
112From the status viewer, you can select files and diff hunks just as you
113can in the commit tool, and preview the final result in the
114:guilabel:`Save Preview` tab.  Pressing :guilabel:`Save As` will save
115the selected changes to a patch file.
116
117For even finer cherry-picking, you can highlight a number of diff-hunks
118in the hunk selection pane and hit CTRL-C.  This will copy the
119highlighted (mouse selected, not toggled) hunks to the clipboard.
120
121.. note::
122	Reversing the order of your changeset selection reverses the effect
123	of the patch.
124
125
126Import Patches
127==============
128
129.. figure:: figures/import.png
130	:alt: Import tool
131
132	Import dialog of Repository Explorer
133
134The import dialog can be opened from the sync bar or menu of the
135Repository Explorer, or via :command:`hgtk import`.  The dialog supports
136file and directory drag and drop.  The drop down menu in the upper right
137corner next to the :guilabel:`Browse` button has the options:
138:guilabel:`Browse Directory..` and :guilabel:`Import from Clipboard`.
139
140You have the choice of importing directly into the repository, or
141importing into your patch queue.
142
143.. note::
144	Importing a patch requires a clean working directory state.  You
145	must commit, revert, or shelve changes before importing a patch.
146
147.. warning::
148	If the patch you are importing does not have a commit
149	message, Mercurial will try to launch your editor, just as if you
150	had tried to import the patch from the command line.  Your ui.editor
151	needs to be a GUI app to make this work correctly.
152
153
154Patch Queues
155============
156
157.. figure:: figures/patchqueue.png
158	:alt: Patch Queue
159
160	Patch Queue panel in the Repository Explorer
161
162Both the Repository Explorer and Commit Tool have an optional Patch
163Queue panel that is only available when the user has enabled the MQ
164extension.  It allows the user to perform most patch queue operations
165including push, pop, rename, and finish.  It's recommended to learn the
166MQ extension before using the Patch Queue panel.
167
168.. vim: noet ts=4