mq

Description

This extension lets you work with a stack of patches in a Mercurial repository. It manages two stacks of patches - all known patches, and applied patches (subset of known patches).

Known patches are represented as patch files in the .hg/patches directory. Applied patches are both patch files and changesets.

Common tasks (use hg help COMMAND for more details):

create new patch                          qnew
import existing patch                     qimport

print patch series                        qseries
print applied patches                     qapplied

add known patch to applied stack          qpush
remove patch from applied stack           qpop
refresh contents of top applied patch     qrefresh

By default, mq will automatically use git patches when required to avoid losing file mode changes, copy records, binary files or empty files creations or deletions. This behavior can be configured with:

[mq]
git = auto/keep/yes/no

If set to 'keep', mq will obey the [diff] section configuration while preserving existing git patches upon qrefresh. If set to 'yes' or 'no', mq will override the [diff] section and always generate git or regular patches, possibly losing data in the second case.

It may be desirable for mq changesets to be kept in the secret phase (see hg help phases), which can be enabled with the following setting:

[mq]
secret = True

You will by default be managing a patch queue named "patches". You can create other, independent patch queues with the hg qqueue command.

If the working directory contains uncommitted files, qpush, qpop and qgoto abort immediately. If -f/--force is used, the changes are discarded. Setting:

[mq]
keepchanges = True

make them behave as if --keep-changes were passed, and non-conflicting local changes will be tolerated and preserved. If incompatible options such as -f/--force or --exact are passed, this setting is ignored.

This extension used to provide a strip command. This command now lives in the strip extension.

Commands

qapplied

print the patches already applied:

hg qapplied [-1] [-s] [PATCH]

Returns 0 on success.

Options:

-1, --last show only the preceding applied patch
-s, --summary print first line of patch header

qclone

clone main and patch repository at same time:

hg qclone [OPTION]... SOURCE [DEST]

If source is local, destination will have no patches applied. If source is remote, this command can not check if patches are applied in source, so cannot guarantee that patches are not applied in destination. If you clone remote repository, be sure before that it has no patches applied.

Source patch repository is looked for in <src>/.hg/patches by default. Use -p <url> to change.

The patch directory must be a nested Mercurial repository, as would be created by hg init --mq.

Return 0 on success.

Options:

--pull use pull protocol to copy metadata
-U, --noupdate do not update the new working directories
--uncompressed use uncompressed transfer (fast over LAN)
-p, --patches <REPO>
 location of source patch repository
-e, --ssh <CMD>
 specify ssh command to use
--remotecmd <CMD>
 specify hg command to run on the remote side
--insecure do not verify server certificate (ignoring web.cacerts config)

qcommit

commit changes in the queue repository (DEPRECATED):

hg qcommit [OPTION]... [FILE]...

This command is deprecated; use hg commit --mq instead.

Options:

-A, --addremove
 mark new/missing files as added/removed before committing
--close-branch mark a branch head as closed
--amend amend the parent of the working directory
-s, --secret use the secret phase for committing
-e, --edit invoke editor on commit messages
-i, --interactive
 use interactive mode
-I, --include <PATTERN[+]>
 include names matching the given patterns
-X, --exclude <PATTERN[+]>
 exclude names matching the given patterns
-m, --message <TEXT>
 use text as commit message
-l, --logfile <FILE>
 read commit message from file
-d, --date <DATE>
 record the specified date as commit date
-u, --user <USER>
 record the specified user as committer
-S, --subrepos recurse into subrepositories

[+] marked option can be specified multiple times

aliases: qci

qdelete

remove patches from queue:

hg qdelete [-k] [PATCH]...

The patches must not be applied, and at least one patch is required. Exact patch identifiers must be given. With -k/--keep, the patch files are preserved in the patch directory.

To stop managing a patch and move it into permanent history, use the hg qfinish command.

Options:

-k, --keep keep patch file
-r, --rev <REV[+]>
 stop managing a revision (DEPRECATED)

[+] marked option can be specified multiple times

aliases: qremove qrm

qdiff

diff of the current patch and subsequent modifications:

hg qdiff [OPTION]... [FILE]...

Shows a diff which includes the current patch as well as any changes which have been made in the working directory since the last refresh (thus showing what the current patch would become after a qrefresh).

Use hg diff if you only want to see the changes made since the last qrefresh, or hg export qtip if you want to see changes made by the current patch without including changes made since the qrefresh.

Returns 0 on success.

Options:

-a, --text treat all files as text
-g, --git use git extended diff format
--binary generate binary diffs in git mode (default)
--nodates omit dates from diff headers
--noprefix omit a/ and b/ prefixes from filenames
-p, --show-function
 show which function each change is in
--reverse produce a diff that undoes the changes
-w, --ignore-all-space
 ignore white space when comparing lines
-b, --ignore-space-change
 ignore changes in the amount of white space
-B, --ignore-blank-lines
 ignore changes whose lines are all blank
-Z, --ignore-space-at-eol
 ignore changes in whitespace at EOL
-U, --unified <NUM>
 number of lines of context to show
--stat output diffstat-style summary of changes
--root <DIR> produce diffs relative to subdirectory
-I, --include <PATTERN[+]>
 include names matching the given patterns
-X, --exclude <PATTERN[+]>
 exclude names matching the given patterns

[+] marked option can be specified multiple times

qfinish

move applied patches into repository history:

hg qfinish [-a] [REV]...

Finishes the specified revisions (corresponding to applied patches) by moving them out of mq control into regular repository history.

Accepts a revision range or the -a/--applied option. If --applied is specified, all applied mq revisions are removed from mq control. Otherwise, the given revisions must be at the base of the stack of applied patches.

This can be especially useful if your changes have been applied to an upstream repository, or if you are about to push your changes to upstream.

Returns 0 on success.

Options:

-a, --applied finish all applied changesets

qfold

fold the named patches into the current patch:

hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...

Patches must not yet be applied. Each patch will be successively applied to the current patch in the order given. If all the patches apply successfully, the current patch will be refreshed with the new cumulative patch, and the folded patches will be deleted. With -k/--keep, the folded patch files will not be removed afterwards.

The header for each folded patch will be concatenated with the current patch header, separated by a line of * * *.

Returns 0 on success.

Options:

-e, --edit invoke editor on commit messages
-k, --keep keep folded patch files
-m, --message <TEXT>
 use text as commit message
-l, --logfile <FILE>
 read commit message from file

qgoto

push or pop patches until named patch is at top of stack:

hg qgoto [OPTION]... PATCH

Returns 0 on success.

Options:

--keep-changes tolerate non-conflicting local changes
-f, --force overwrite any local changes
--no-backup do not save backup copies of files

qguard

set or print guards for a patch:

hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]

Guards control whether a patch can be pushed. A patch with no guards is always pushed. A patch with a positive guard ("+foo") is pushed only if the hg qselect command has activated it. A patch with a negative guard ("-foo") is never pushed if the hg qselect command has activated it.

With no arguments, print the currently active guards. With arguments, set guards for the named patch.

Note

Specifying negative guards now requires '--'.

To set guards on another patch:

hg qguard other.patch -- +2.6.17 -stable

Returns 0 on success.

Options:

-l, --list list all patches and guards
-n, --none drop all guards

qheader

print the header of the topmost or specified patch:

hg qheader [PATCH]

Returns 0 on success.

qimport

import a patch or existing changeset:

hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...

The patch is inserted into the series after the last applied patch. If no patches have been applied, qimport prepends the patch to the series.

The patch will have the same name as its source file unless you give it a new one with -n/--name.

You can register an existing patch inside the patch directory with the -e/--existing flag.

With -f/--force, an existing patch of the same name will be overwritten.

An existing changeset may be placed under mq control with -r/--rev (e.g. qimport --rev . -n patch will place the current revision under mq control). With -g/--git, patches imported with --rev will use the git diff format. See the diffs help topic for information on why this is important for preserving rename/copy information and permission changes. Use hg qfinish to remove changesets from mq control.

To import a patch from standard input, pass - as the patch file. When importing from standard input, a patch name must be specified using the --name flag.

To import an existing patch while renaming it:

hg qimport -e existing-patch -n new-name

Returns 0 if import succeeded.

Options:

-e, --existing import file in patch directory
-n, --name <NAME>
 name of patch file
-f, --force overwrite existing files
-r, --rev <REV[+]>
 place existing revisions under mq control
-g, --git use git extended diff format
-P, --push qpush after importing

[+] marked option can be specified multiple times

qinit

init a new queue repository (DEPRECATED):

hg qinit [-c]

The queue repository is unversioned by default. If -c/--create-repo is specified, qinit will create a separate nested repository for patches (qinit -c may also be run later to convert an unversioned patch repository into a versioned one). You can use qcommit to commit changes to this queue repository.

This command is deprecated. Without -c, it's implied by other relevant commands. With -c, use hg init --mq instead.

Options:

-c, --create-repo
 create queue repository

qnew

create a new patch:

hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...

qnew creates a new patch on top of the currently-applied patch (if any). The patch will be initialized with any outstanding changes in the working directory. You may also use -I/--include, -X/--exclude, and/or a list of files after the patch name to add only changes to matching files to the new patch, leaving the rest as uncommitted modifications.

-u/--user and -d/--date can be used to set the (given) user and date, respectively. -U/--currentuser and -D/--currentdate set user to current user and date to current date.

-e/--edit, -m/--message or -l/--logfile set the patch header as well as the commit message. If none is specified, the header is empty and the commit message is '[mq]: PATCH'.

Use the -g/--git option to keep the patch in the git extended diff format. Read the diffs help topic for more information on why this is important for preserving permission changes and copy/rename information.

Returns 0 on successful creation of a new patch.

Options:

-e, --edit invoke editor on commit messages
-f, --force import uncommitted changes (DEPRECATED)
-g, --git use git extended diff format
-U, --currentuser
 add "From: <current user>" to patch
-u, --user <USER>
 add "From: <USER>" to patch
-D, --currentdate
 add "Date: <current date>" to patch
-d, --date <DATE>
 add "Date: <DATE>" to patch
-I, --include <PATTERN[+]>
 include names matching the given patterns
-X, --exclude <PATTERN[+]>
 exclude names matching the given patterns
-m, --message <TEXT>
 use text as commit message
-l, --logfile <FILE>
 read commit message from file

[+] marked option can be specified multiple times

qnext

print the name of the next pushable patch:

hg qnext [-s]

Returns 0 on success.

Options:

-s, --summary print first line of patch header

qpop

pop the current patch off the stack:

hg qpop [-a] [-f] [PATCH | INDEX]

Without argument, pops off the top of the patch stack. If given a patch name, keeps popping off patches until the named patch is at the top of the stack.

By default, abort if the working directory contains uncommitted changes. With --keep-changes, abort only if the uncommitted files overlap with patched files. With -f/--force, backup and discard changes made to such files.

Return 0 on success.

Options:

-a, --all pop all patches
-n, --name <NAME>
 queue name to pop (DEPRECATED)
--keep-changes tolerate non-conflicting local changes
-f, --force forget any local changes to patched files
--no-backup do not save backup copies of files

qprev

print the name of the preceding applied patch:

hg qprev [-s]

Returns 0 on success.

Options:

-s, --summary print first line of patch header

qpush

push the next patch onto the stack:

hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]

By default, abort if the working directory contains uncommitted changes. With --keep-changes, abort only if the uncommitted files overlap with patched files. With -f/--force, backup and patch over uncommitted changes.

Return 0 on success.

Options:

--keep-changes tolerate non-conflicting local changes
-f, --force apply on top of local changes
-e, --exact apply the target patch to its recorded parent
-l, --list list patch name in commit text
-a, --all apply all patches
-m, --merge merge from another queue (DEPRECATED)
-n, --name <NAME>
 merge queue name (DEPRECATED)
--move reorder patch series and apply only the patch
--no-backup do not save backup copies of files

qqueue

manage multiple patch queues:

hg qqueue [OPTION] [QUEUE]

Supports switching between different patch queues, as well as creating new patch queues and deleting existing ones.

Omitting a queue name or specifying -l/--list will show you the registered queues - by default the "normal" patches queue is registered. The currently active queue will be marked with "(active)". Specifying --active will print only the name of the active queue.

To create a new queue, use -c/--create. The queue is automatically made active, except in the case where there are applied patches from the currently active queue in the repository. Then the queue will only be created and switching will fail.

To delete an existing queue, use --delete. You cannot delete the currently active queue.

Returns 0 on success.

Options:

-l, --list list all available queues
--active print name of active queue
-c, --create create new queue
--rename rename active queue
--delete delete reference to queue
--purge delete queue, and remove patch dir

qrefresh

update the current patch:

hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...

If any file patterns are provided, the refreshed patch will contain only the modifications that match those patterns; the remaining modifications will remain in the working directory.

If -s/--short is specified, files currently included in the patch will be refreshed just like matched files and remain in the patch.

If -e/--edit is specified, Mercurial will start your configured editor for you to enter a message. In case qrefresh fails, you will find a backup of your message in .hg/last-message.txt.

hg add/remove/copy/rename work as usual, though you might want to use git-style patches (-g/--git or [diff] git=1) to track copies and renames. See the diffs help topic for more information on the git diff format.

Returns 0 on success.

Options:

-e, --edit invoke editor on commit messages
-g, --git use git extended diff format
-s, --short refresh only files already in the patch and specified files
-U, --currentuser
 add/update author field in patch with current user
-u, --user <USER>
 add/update author field in patch with given user
-D, --currentdate
 add/update date field in patch with current date
-d, --date <DATE>
 add/update date field in patch with given date
-I, --include <PATTERN[+]>
 include names matching the given patterns
-X, --exclude <PATTERN[+]>
 exclude names matching the given patterns
-m, --message <TEXT>
 use text as commit message
-l, --logfile <FILE>
 read commit message from file

[+] marked option can be specified multiple times

qrename

rename a patch:

hg qrename PATCH1 [PATCH2]

With one argument, renames the current patch to PATCH1. With two arguments, renames PATCH1 to PATCH2.

Returns 0 on success.

aliases: qmv

qrestore

restore the queue state saved by a revision (DEPRECATED):

hg qrestore [-d] [-u] REV

This command is deprecated, use hg rebase instead.

Options:

-d, --delete delete save entry
-u, --update update queue working directory

qsave

save current queue state (DEPRECATED):

hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]

This command is deprecated, use hg rebase instead.

Options:

-c, --copy copy patch directory
-n, --name <NAME>
 copy directory name
-e, --empty clear queue status file
-f, --force force copy
-m, --message <TEXT>
 use text as commit message
-l, --logfile <FILE>
 read commit message from file

qselect

set or print guarded patches to push:

hg qselect [OPTION]... [GUARD]...

Use the hg qguard command to set or print guards on patch, then use qselect to tell mq which guards to use. A patch will be pushed if it has no guards or any positive guards match the currently selected guard, but will not be pushed if any negative guards match the current guard. For example:

qguard foo.patch -- -stable    (negative guard)
qguard bar.patch    +stable    (positive guard)
qselect stable

This activates the "stable" guard. mq will skip foo.patch (because it has a negative match) but push bar.patch (because it has a positive match).

With no arguments, prints the currently active guards. With one argument, sets the active guard.

Use -n/--none to deactivate guards (no other arguments needed). When no guards are active, patches with positive guards are skipped and patches with negative guards are pushed.

qselect can change the guards on applied patches. It does not pop guarded patches by default. Use --pop to pop back to the last applied patch that is not guarded. Use --reapply (which implies --pop) to push back to the current patch afterwards, but skip guarded patches.

Use -s/--series to print a list of all guards in the series file (no other arguments needed). Use -v for more information.

Returns 0 on success.

Options:

-n, --none disable all guards
-s, --series list all guards in series file
--pop pop to before first guarded applied patch
--reapply pop, then reapply patches

qseries

print the entire series file:

hg qseries [-ms]

Returns 0 on success.

Options:

-m, --missing print patches not in series
-s, --summary print first line of patch header

qtop

print the name of the current patch:

hg qtop [-s]

Returns 0 on success.

Options:

-s, --summary print first line of patch header

qunapplied

print the patches not yet applied:

hg qunapplied [-1] [-s] [PATCH]

Returns 0 on success.

Options:

-1, --first show only the first patch
-s, --summary print first line of patch header