Add note about hg push aborting with patches applied
|Deletions are marked like this.||Additions are marked like this.|
|Line 1:||Line 1:|
|= Introduction =||== Mercurial Queues Extension ==
'''This extension is currently being distributed along with Mercurial.'''
=== Introduction ===
|Line 8:||Line 11:|
|= Download and install =||=== Download and install ===|
|Line 15:||Line 18:|
|= Using Mercurial Queues =||=== Using Mercurial Queues ===|
|Line 19:||Line 22:|
|= Merging patches with new upstream revisions =||=== Merging patches with new upstream revisions ===|
|Line 24:||Line 27:|
|= Tutorial =||=== Tutorial ===|
|Line 28:||Line 31:|
|= Hook Examples =||=== Hook Examples ===|
|Line 44:||Line 47:|
|= Command Examples =||=== Command Examples ===|
Mercurial Queues Extension
This extension is currently being distributed along with Mercurial.
In a distributed development model, changesets are traditionally immutable. Once a commit is done, it lives in the project history forever. This can make it difficult to develop a set of individual changes for submission to a project maintainer. Over time, the development repository will contain a number of merges, and a long line of changes as the code matures. This history is important for the individual developer, but when the changes are sent upstream they will be very difficult to review.
Andrew Morton originally developed a set of scripts for maintaining kernel patches outside of any SCM tool. Others extended these into a suite called [http://savannah.nongnu.org/projects/quilt quilt]. The basic idea behind quilt is to maintain patches instead of maintaining source files. Patches can be added, removed or reordered, and they can be refreshed as you fix bugs or update to a new base revision. quilt is very powerful, but it is not integrated with the underlying SCM tools. This makes it difficult to visualize your changes.
The patch queue extension integrates quilt functionality into Mercurial. Changes are maintained as patches which are committed into Mercurial. Commits can be removed or reordered, and the underlying patch can be refreshed based on changes made in the working directory. The patch directory can also be placed under revision control, so you can have a separate history of changes made to your patches.
2. Download and install
Mq is now included in the main Mercurial tree. The older version is pullable from [http://hg.serpentine.com/mercurial/mq] for versions up to 0.8.
The first step is to enable the mq extension. In the Mercurial source directory, hgext/mq.py is the extension source file. Copy this to a suitable location, and enable the mq extension as described in the ExtensionHowto.
3. Using Mercurial Queues
After the extension is properly installed, hg help will include the mq commands. These all start with q, and try to mimic commands under quilt. The patch queue lives in a directory named .hg/patches. You can edit the patch files themselves to change the comments used in the Mercurial commit messages. .hg/patches/series lists the patches in the order they will be applied. You can change the patch order simply by moving them around in the series file. Make sure to only change entries in the series file for patches that are not currently applied.
4. Merging patches with new upstream revisions
MqMerge describes this in detail.
Find out more about mq in MqTutorial.
6. Hook Examples
You will often not want to push or pull changes from a repository which has patches applied to it. To prevent yourself from doing this accidentally, you can add these hooks to your repository .hg/hgrc.
[hooks] # Prevent "hg pull" if MQ patches are applied. prechangegroup.mq-no-pull = ! hg qtop > /dev/null 2>&1 # Prevent "hg push" if MQ patches are applied. preoutgoing.mq-no-push = ! hg qtop > /dev/null 2>&1
7. Command Examples
cd some_existing_hg_repository # setup the patch queue directory hg qinit # create a new patch named firstpatch hg qnew firstpatch # edit some files vi filename # update the patch to contain your changes hg qrefresh # vi .hg/patches/firstpatch to see the result # print the current patch to the screen hg qdiff # make some more changes vi filename # see the differences not yet stored in the patch hg diff # update the patch hg qrefresh # create another patch hg qnew secondpatch # Make more changes, and update the new patch vi filename hg qrefresh # Look at the patches you have applied # Look at all the patches in the queue hg qapplied hg qseries # remove the top patch hg qpop # apply the patch again hg qpush # remove all patches hg qpop -a # apply all patches hg qpush -a