Mercurial Queues Reference - Open Source Mercurial: The Definitive Guideby Bryan O'Sullivan
This excerpt is from Mercurial: The Definitive Guide . This definitive guide takes you step by step through ways to track, merge, and manage both open source and commercial software projects with Mercurial, using Windows, Mac OS X, Linux, Solaris, and other systems.
command commits any outstanding changes in the
repository. This command only works if the
.hg/patches directory is a
repository, i.e., you created the directory using hg qinit
-c or ran hg init in the directory after running
command removes the entry for a patch from the
series file in the
directory. It does not pop the patch if the patch is already
applied. By default, it does not delete the patch file; use the
-f option to do
The patches to fold must not be applied; qfold will exit with an error if this is
the case. The order in which patches are folded is significant:
hg qfold a b means “apply the
current topmost patch, followed by
a, followed by
The comments from the folded patches are appended to
the comments of the destination patch, with each block of comments
separated by three asterisk (*) characters. Use the
-e option to edit the commit
message for the combined patch/changeset after the folding has
command adds an entry for an external patch to the
series file, and copies the patch into the
directory. It adds the entry immediately after the topmost applied
patch, but does not push the patch.
The qnew command
creates a new patch. It takes one mandatory argument, the name to use for
the patch file. The newly created patch is created empty by default.
It is added to the
after the current topmost applied patch, and is immediately pushed on
top of that patch.
If qnew finds
modified files in the working directory, it will refuse to create a
new patch unless the
option is used (see below). This behavior allows you to qrefresh your topmost applied patch before
you apply a new patch on top of it.
-f: Create a new patch if the contents of the working directory are modified. Any outstanding modifications are added to the newly created patch, so after this command completes, the working directory will no longer be modified.
The qpop command takes an optional argument, which it uses as the name or index of the patch to pop to. If given a name, it will pop patches until the named patch is the topmost applied patch. If given a number, qpop treats the number as an index into the entries in the series file, counting from zero (empty lines and lines containing only comments do not count). It pops patches until the patch identified by the given index is the topmost applied patch.
The qpop command
does not read or write patches or the
series file. It is thus safe to qpop a patch that you have removed from the
series file, or a patch that you
have renamed or deleted entirely. In the latter two cases, use the
name of the patch as it was when you applied it.
By default, the qpop command will not pop any patches if
the working directory has been modified. You can override this
behavior using the
option, which reverts all modifications in the working
The commit date and time zone are the current date and time zone. Because this data is used to compute the identity of a changeset, this means that if you qpop a patch and qpush it again, the changeset that you push will have a different identity from the changeset you popped.
-m: If a patch fails to apply cleanly, use the entry for the patch in another saved queue to compute the parameters for a three-way merge, and perform a three-way merge using the normal Mercurial merge machinery. Use the resolution of the merge as the new patch content.
Added files and copy and rename destinations are added to the patch, while removed files and rename sources are removed.
Even if qrefresh detects no changes, it still recreates the changeset that represents the patch. This causes the identity of the changeset to differ from the previous changeset that identified the patch.
The hg strip command removes a revision, and all of its descendants, from the repository. It undoes the effects of the removed revisions from the repository, and updates the working directory to the first parent of the removed revision.
contains a list of the names of all patches that MQ can
apply. It is represented as a list of names, with one name
saved per line. Leading and trailing whitespace in each line is
You will often need to edit the
series file by hand, hence the support for
comments and empty lines noted above. For example, you can comment out
a patch temporarily, and qpush
will skip over that patch when applying patches. You can also change
the order in which patches are applied by reordering their entries in
series file under revision control is also
supported; it is a good idea to place all of the patches that it
refers to under revision control, as well. If you create a patch
directory using the
option to qinit, this will be done
for you automatically.
contains the names and changeset hashes of all patches that MQ
currently has applied. Unlike the
file, this file is not intended for editing. You should not place this
file under revision control, or modify it in any way. It is used by MQ
strictly for internal bookkeeping.