Contents
manage a stack of patches
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.
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) |
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 | |
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 |
| --draft | use the draft phase for committing |
| -e, --edit | invoke editor on commit messages |
| --force-close-branch | |
| forcibly close branch from a non-head changeset (ADVANCED) | |
| -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
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
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
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 | |
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 |
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
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 |
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 |
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 |
print the header of the topmost or specified patch:
hg qheader [PATCH]
Returns 0 on success.
print the name of the next pushable patch:
hg qnext [-s]
Returns 0 on success.
Options:
| -s, --summary | print first line of patch header |
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 |
print the name of the preceding applied patch:
hg qprev [-s]
Returns 0 on success.
Options:
| -s, --summary | print first line of patch header |
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 |
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 |
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
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 |
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 | |
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 |
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 |
print the name of the current patch:
hg qtop [-s]
Returns 0 on success.
Options:
| -s, --summary | print first line of patch header |
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 |
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 (DEFAULT: diff.git) |
| --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 (DEFAULT: diff.showfunc) | |
| --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
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