1HG(1) Mercurial Manual HG(1)
2
6 hg - Mercurial source code management system
7
9 hg command [option]... [argument]...
10
12 The hg command provides a command line interface to the Mercurial sys‐
13 tem.
14
16 files...
17 indicates one or more filename or relative path filenames; see
18 File Name Patterns for information on pattern matching
19 path indicates a path on the local machine
21 revision
23 indicates a changeset which can be specified as a changeset re‐
24 vision number, a tag, or a unique substring of the changeset
25 hash value
26 repository path
28 either the pathname of a local repository or the URI of a remote
29 repository.
30
32 -R,--repository <REPO>
33 repository root directory or name of overlay bundle file
34 --cwd <DIR>
36 change working directory
37 -y, --noninteractive
39 do not prompt, automatically pick the first choice for all
40 prompts
41 -q, --quiet
43 suppress output
44 -v, --verbose
46 enable additional output
47 --color <TYPE>
49 when to colorize (boolean, always, auto, never, or debug)
50 --config <CONFIG[+]>
52 set/override config option (use 'section.name=value')
53 --debug
55 enable debugging output
56 --debugger
58 start debugger
59 --encoding <ENCODE>
61 set the charset encoding (default: UTF-8)
62 --encodingmode <MODE>
64 set the charset encoding mode (default: strict)
65 --traceback
67 always print a traceback on exception
68 --time time how long the command takes
70 --profile
72 print command execution profile
73 --version
75 output version information and exit
76 -h, --help
78 display help and exit
79 --hidden
81 consider hidden changesets
82 --pager <TYPE>
84 when to paginate (boolean, always, auto, or never) (default:
85 auto)
86 [+] marked option can be specified multiple times
88
90 Repository creation
91 clone
92 make a copy of an existing repository:
93 hg clone [OPTION]... SOURCE [DEST]
95 Create a copy of an existing repository in a new directory.
97 If no destination directory name is specified, it defaults to the base‐
99 name of the source.
100 The location of the source is added to the new repository's .hg/hgrc
102 file, as the default to be used for future pulls.
103 Only local paths and ssh:// URLs are supported as destinations. For
105 ssh:// destinations, no working directory or .hg/hgrc will be created
106 on the remote side.
107 If the source repository has a bookmark called '@' set, that revision
109 will be checked out in the new repository by default.
110 To check out a particular version, use -u/--update, or -U/--noupdate to
112 create a clone with no working directory.
113 To pull only a subset of changesets, specify one or more revisions
115 identifiers with -r/--rev or branches with -b/--branch. The resulting
116 clone will contain only the specified changesets and their ancestors.
117 These options (or 'clone src#rev dest') imply --pull, even for local
118 source repositories.
119 In normal clone mode, the remote normalizes repository data into a com‐
121 mon exchange format and the receiving end translates this data into its
122 local storage format. --stream activates a different clone mode that
123 essentially copies repository files from the remote with minimal data
124 processing. This significantly reduces the CPU cost of a clone both re‐
125 motely and locally. However, it often increases the transferred data
126 size by 30-40%. This can result in substantially faster clones where
127 I/O throughput is plentiful, especially for larger repositories. A
128 side-effect of --stream clones is that storage settings and require‐
129 ments on the remote are applied locally: a modern client may inherit
130 legacy or inefficient storage used by the remote or a legacy Mercurial
131 client may not be able to clone from a modern Mercurial remote.
132 Note Specifying a tag will include the tagged changeset but not the
134 changeset containing the tag.
135 For efficiency, hardlinks are used for cloning whenever the source and
137 destination are on the same filesystem (note this applies only to the
138 repository data, not to the working directory). Some filesystems, such
139 as AFS, implement hardlinking incorrectly, but do not report errors. In
140 these cases, use the --pull option to avoid hardlinking.
141 Mercurial will update the working directory to the first applicable re‐
143 vision from this list:
144 a. null if -U or the source repository has no changesets
146 b. if -u . and the source repository is local, the first parent of the
148 source repository's working directory
149 c. the changeset specified with -u (if a branch name, this means the
151 latest head of that branch)
152 d. the changeset specified with -r
154 e. the tipmost head specified with -b
156 f. the tipmost head specified with the url#branch source syntax
158 g. the revision marked with the '@' bookmark, if present
160 h. the tipmost head of the default branch
162 i. tip
164 When cloning from servers that support it, Mercurial may fetch pre-gen‐
166 erated data from a server-advertised URL or inline from the same
167 stream. When this is done, hooks operating on incoming changesets and
168 changegroups may fire more than once, once for each pre-generated bun‐
169 dle and as well as for any additional remaining data. In addition, if
170 an error occurs, the repository may be rolled back to a partial clone.
171 This behavior may change in future releases. See hg help -e cloneb‐
172 undles for more.
173 Examples:
175 • clone a remote repository to a new directory named hg/:
177 hg clone https://www.mercurial-scm.org/repo/hg/
179 • create a lightweight local clone:
181 hg clone project/ project-feature/
183 • clone from an absolute path on an ssh server (note double-slash):
185 hg clone ssh://user@server//home/projects/alpha/
187 • do a streaming clone while checking out a specified version:
189 hg clone --stream http://server/repo -u 1.5
191 • create a repository without changesets after a particular revision:
193 hg clone -r 04e544 experimental/ good/
195 • clone (and track) a particular named branch:
197 hg clone https://www.mercurial-scm.org/repo/hg/#stable
199 See hg help urls for details on specifying URLs.
201 Returns 0 on success.
203 Options:
205 -U, --noupdate
207 the clone will include an empty working directory (only a repos‐
208 itory)
209 -u,--updaterev <REV>
211 revision, tag, or branch to check out
212 -r,--rev <REV[+]>
214 do not clone everything, but include this changeset and its an‐
215 cestors
216 -b,--branch <BRANCH[+]>
218 do not clone everything, but include this branch's changesets
219 and their ancestors
220 --pull use pull protocol to copy metadata
222 --uncompressed
224 an alias to --stream (DEPRECATED)
225 --stream
227 clone with minimal data processing
228 -e,--ssh <CMD>
230 specify ssh command to use
231 --remotecmd <CMD>
233 specify hg command to run on the remote side
234 --insecure
236 do not verify server certificate (ignoring web.cacerts config)
237 [+] marked option can be specified multiple times
239 init
241 create a new repository in the given directory:
242 hg init [-e CMD] [--remotecmd CMD] [DEST]
244 Initialize a new repository in the given directory. If the given direc‐
246 tory does not exist, it will be created.
247 If no directory is given, the current directory is used.
249 It is possible to specify an ssh:// URL as the destination. See hg
251 help urls for more information.
252 Returns 0 on success.
254 Options:
256 -e,--ssh <CMD>
258 specify ssh command to use
259 --remotecmd <CMD>
261 specify hg command to run on the remote side
262 --insecure
264 do not verify server certificate (ignoring web.cacerts config)
265 Remote repository management
267 incoming
268 show new changesets found in source:
269 hg incoming [-p] [-n] [-M] [-f] [-r REV]... [--bundle FILENAME] [SOURCE]
271 Show new changesets found in the specified path/URL or the default pull
273 location. These are the changesets that would have been pulled by hg
274 pull at the time you issued this command.
275 See pull for valid source format details.
277 With -B/--bookmarks, the result of bookmark comparison between local
279 and remote repositories is displayed. With -v/--verbose, status is also
280 displayed for each bookmark like below:
281 BM1 01234567890a added
283 BM2 1234567890ab advanced
284 BM3 234567890abc diverged
285 BM4 34567890abcd changed
286 The action taken locally when pulling depends on the status of each
288 bookmark:
289 added
291 pull will create it
293 advanced
295 pull will update it
297 diverged
299 pull will create a divergent bookmark
301 changed
303 result depends on remote changesets
305 From the point of view of pulling behavior, bookmark existing only in
307 the remote repository are treated as added, even if it is in fact lo‐
308 cally deleted.
309 For remote repository, using --bundle avoids downloading the changesets
311 twice if the incoming is followed by a pull.
312 Examples:
314 • show incoming changes with patches and full description:
316 hg incoming -vp
318 • show incoming changes excluding merges, store a bundle:
320 hg in -vpM --bundle incoming.hg
322 hg pull incoming.hg
323 • briefly list changes inside a bundle:
325 hg in changes.hg -T "{desc|firstline}\n"
327 Returns 0 if there are incoming changes, 1 otherwise.
329 Options:
331 -f, --force
333 run even if remote repository is unrelated
334 -n, --newest-first
336 show newest record first
337 --bundle <FILE>
339 file to store the bundles into
340 -r,--rev <REV[+]>
342 a remote changeset intended to be added
343 -B, --bookmarks
345 compare bookmarks
346 -b,--branch <BRANCH[+]>
348 a specific branch you would like to pull
349 -p, --patch
351 show patch
352 -g, --git
354 use git extended diff format
355 -l,--limit <NUM>
357 limit number of changes displayed
358 -M, --no-merges
360 do not show merges
361 --stat output diffstat-style summary of changes
363 -G, --graph
365 show the revision DAG
366 --style <STYLE>
368 display using template map file (DEPRECATED)
369 -T,--template <TEMPLATE>
371 display with template
372 -e,--ssh <CMD>
374 specify ssh command to use
375 --remotecmd <CMD>
377 specify hg command to run on the remote side
378 --insecure
380 do not verify server certificate (ignoring web.cacerts config)
381 -S, --subrepos
383 recurse into subrepositories
384 [+] marked option can be specified multiple times
386 aliases: in
388 outgoing
390 show changesets not found in the destination:
391 hg outgoing [-M] [-p] [-n] [-f] [-r REV]... [DEST]...
393 Show changesets not found in the specified destination repository or
395 the default push location. These are the changesets that would be
396 pushed if a push was requested.
397 See pull for details of valid destination formats.
399 With -B/--bookmarks, the result of bookmark comparison between local
401 and remote repositories is displayed. With -v/--verbose, status is also
402 displayed for each bookmark like below:
403 BM1 01234567890a added
405 BM2 deleted
406 BM3 234567890abc advanced
407 BM4 34567890abcd diverged
408 BM5 4567890abcde changed
409 The action taken when pushing depends on the status of each bookmark:
411 added
413 push with -B will create it
415 deleted
417 push with -B will delete it
419 advanced
421 push will update it
423 diverged
425 push with -B will update it
427 changed
429 push with -B will update it
431 From the point of view of pushing behavior, bookmarks existing only in
433 the remote repository are treated as deleted, even if it is in fact
434 added remotely.
435 Returns 0 if there are outgoing changes, 1 otherwise.
437 Options:
439 -f, --force
441 run even when the destination is unrelated
442 -r,--rev <REV[+]>
444 a changeset intended to be included in the destination
445 -n, --newest-first
447 show newest record first
448 -B, --bookmarks
450 compare bookmarks
451 -b,--branch <BRANCH[+]>
453 a specific branch you would like to push
454 -p, --patch
456 show patch
457 -g, --git
459 use git extended diff format
460 -l,--limit <NUM>
462 limit number of changes displayed
463 -M, --no-merges
465 do not show merges
466 --stat output diffstat-style summary of changes
468 -G, --graph
470 show the revision DAG
471 --style <STYLE>
473 display using template map file (DEPRECATED)
474 -T,--template <TEMPLATE>
476 display with template
477 -e,--ssh <CMD>
479 specify ssh command to use
480 --remotecmd <CMD>
482 specify hg command to run on the remote side
483 --insecure
485 do not verify server certificate (ignoring web.cacerts config)
486 -S, --subrepos
488 recurse into subrepositories
489 [+] marked option can be specified multiple times
491 aliases: out
493 paths
495 show aliases for remote repositories:
496 hg paths [NAME]
498 Show definition of symbolic path name NAME. If no name is given, show
500 definition of all available names.
501 Option -q/--quiet suppresses all output when searching for NAME and
503 shows only the path names when listing all definitions.
504 Path names are defined in the [paths] section of your configuration
506 file and in /etc/mercurial/hgrc. If run inside a repository, .hg/hgrc
507 is used, too.
508 The path names default and default-push have a special meaning. When
510 performing a push or pull operation, they are used as fallbacks if no
511 location is specified on the command-line. When default-push is set,
512 it will be used for push and default will be used for pull; otherwise
513 default is used as the fallback for both. When cloning a repository,
514 the clone source is written as default in .hg/hgrc.
515 Note default and default-push apply to all inbound (e.g. hg incoming
517 ) and outbound (e.g. hg outgoing, hg email and hg bundle) opera‐
518 tions.
519 See hg help urls for more information.
521 Template:
523 The following keywords are supported. See also hg help templates.
525 name String. Symbolic name of the path alias.
527 pushurl
529 String. URL for push operations.
530 url String. URL or directory path for the other operations.
532 Returns 0 on success.
534 Options:
536 -T,--template <TEMPLATE>
538 display with template
539 pull
541 pull changes from the specified source:
542 hg pull [-u] [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [SOURCE]...
544 Pull changes from a remote repository to a local one.
546 This finds all changes from the repository at the specified path or URL
548 and adds them to a local repository (the current one unless -R is spec‐
549 ified). By default, this does not update the copy of the project in the
550 working directory.
551 When cloning from servers that support it, Mercurial may fetch pre-gen‐
553 erated data. When this is done, hooks operating on incoming changesets
554 and changegroups may fire more than once, once for each pre-generated
555 bundle and as well as for any additional remaining data. See hg help -e
556 clonebundles for more.
557 Use hg incoming if you want to see what would have been added by a pull
559 at the time you issued this command. If you then decide to add those
560 changes to the repository, you should use hg pull -r X where X is the
561 last changeset listed by hg incoming.
562 If SOURCE is omitted, the 'default' path will be used. See hg help
564 urls for more information.
565 If multiple sources are specified, they will be pulled sequentially as
567 if the command was run multiple time. If --update is specify and the
568 command will stop at the first failed --update.
569 Specifying bookmark as . is equivalent to specifying the active book‐
571 mark's name.
572 Returns 0 on success, 1 if an update had unresolved files.
574 Options:
576 -u, --update
578 update to new branch head if new descendants were pulled
579 -f, --force
581 run even when remote repository is unrelated
582 --confirm
584 confirm pull before applying changes
585 -r,--rev <REV[+]>
587 a remote changeset intended to be added
588 -B,--bookmark <BOOKMARK[+]>
590 bookmark to pull
591 -b,--branch <BRANCH[+]>
593 a specific branch you would like to pull
594 -e,--ssh <CMD>
596 specify ssh command to use
597 --remotecmd <CMD>
599 specify hg command to run on the remote side
600 --insecure
602 do not verify server certificate (ignoring web.cacerts config)
603 [+] marked option can be specified multiple times
605 push
607 push changes to the specified destination:
608 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]...
610 Push changesets from the local repository to the specified destination.
612 This operation is symmetrical to pull: it is identical to a pull in the
614 destination repository from the current one.
615 By default, push will not allow creation of new heads at the destina‐
617 tion, since multiple heads would make it unclear which head to use. In
618 this situation, it is recommended to pull and merge before pushing.
619 Use --new-branch if you want to allow push to create a new named branch
621 that is not present at the destination. This allows you to only create
622 a new branch without forcing other changes.
623 Note Extra care should be taken with the -f/--force option, which
625 will push all new heads on all branches, an action which will
626 almost always cause confusion for collaborators.
627 If -r/--rev is used, the specified revision and all its ancestors will
629 be pushed to the remote repository.
630 If -B/--bookmark is used, the specified bookmarked revision, its ances‐
632 tors, and the bookmark will be pushed to the remote repository. Speci‐
633 fying . is equivalent to specifying the active bookmark's name. Use the
634 --all-bookmarks option for pushing all current bookmarks.
635 Please see hg help urls for important details about ssh:// URLs. If
637 DESTINATION is omitted, a default path will be used.
638 When passed multiple destinations, push will process them one after the
640 other, but stop should an error occur.
641 The --pushvars option sends strings to the server that become environ‐
643 ment variables prepended with HG_USERVAR_. For example, --pushvars EN‐
644 ABLE_FEATURE=true, provides the server side hooks with HG_USERVAR_EN‐
645 ABLE_FEATURE=true as part of their environment.
646 pushvars can provide for user-overridable hooks as well as set debug
648 levels. One example is having a hook that blocks commits containing
649 conflict markers, but enables the user to override the hook if the file
650 is using conflict markers for testing purposes or the file format has
651 strings that look like conflict markers.
652 By default, servers will ignore --pushvars. To enable it add the fol‐
654 lowing to your configuration file:
655 [push]
657 pushvars.server = true
658 Returns 0 if push was successful, 1 if nothing to push.
660 Options:
662 -f, --force
664 force push
665 -r,--rev <REV[+]>
667 a changeset intended to be included in the destination
668 -B,--bookmark <BOOKMARK[+]>
670 bookmark to push
671 --all-bookmarks
673 push all bookmarks (EXPERIMENTAL)
674 -b,--branch <BRANCH[+]>
676 a specific branch you would like to push
677 --new-branch
679 allow pushing a new branch
680 --pushvars <VALUE[+]>
682 variables that can be sent to server (ADVANCED)
683 --publish
685 push the changeset as public (EXPERIMENTAL)
686 -e,--ssh <CMD>
688 specify ssh command to use
689 --remotecmd <CMD>
691 specify hg command to run on the remote side
692 --insecure
694 do not verify server certificate (ignoring web.cacerts config)
695 [+] marked option can be specified multiple times
697 serve
699 start stand-alone webserver:
700 hg serve [OPTION]...
702 Start a local HTTP repository browser and pull server. You can use this
704 for ad-hoc sharing and browsing of repositories. It is recommended to
705 use a real web server to serve a repository for longer periods of time.
706 Please note that the server does not implement access control. This
708 means that, by default, anybody can read from the server and nobody can
709 write to it by default. Set the web.allow-push option to * to allow ev‐
710 erybody to push to the server. You should use a real web server if you
711 need to authenticate users.
712 By default, the server logs accesses to stdout and errors to stderr.
714 Use the -A/--accesslog and -E/--errorlog options to log to files.
715 To have the server choose a free port number to listen on, specify a
717 port number of 0; in this case, the server will print the port number
718 it uses.
719 Returns 0 on success.
721 Options:
723 -A,--accesslog <FILE>
725 name of access log file to write to
726 -d, --daemon
728 run server in background
729 --daemon-postexec <VALUE[+]>
731 used internally by daemon mode
732 -E,--errorlog <FILE>
734 name of error log file to write to
735 -p,--port <PORT>
737 port to listen on (default: 8000)
738 -a,--address <ADDR>
740 address to listen on (default: all interfaces)
741 --prefix <PREFIX>
743 prefix path to serve from (default: server root)
744 -n,--name <NAME>
746 name to show in web pages (default: working directory)
747 --web-conf <FILE>
749 name of the hgweb config file (see 'hg help hgweb')
750 --webdir-conf <FILE>
752 name of the hgweb config file (DEPRECATED)
753 --pid-file <FILE>
755 name of file to write process ID to
756 --stdio
758 for remote clients (ADVANCED)
759 --cmdserver <MODE>
761 for remote clients (ADVANCED)
762 -t,--templates <TEMPLATE>
764 web templates to use
765 --style <STYLE>
767 template style to use
768 -6, --ipv6
770 use IPv6 in addition to IPv4
771 --certificate <FILE>
773 SSL certificate file
774 --print-url
776 start and print only the URL
777 -S, --subrepos
779 recurse into subrepositories
780 [+] marked option can be specified multiple times
782 Change creation
784 commit
785 commit the specified files or all outstanding changes:
786 hg commit [OPTION]... [FILE]...
788 Commit changes to the given files into the repository. Unlike a cen‐
790 tralized SCM, this operation is a local operation. See hg push for a
791 way to actively distribute your changes.
792 If a list of files is omitted, all changes reported by hg status will
794 be committed.
795 If you are committing the result of a merge, do not provide any file‐
797 names or -I/-X filters.
798 If no commit message is specified, Mercurial starts your configured ed‐
800 itor where you can enter a message. In case your commit fails, you will
801 find a backup of your message in .hg/last-message.txt.
802 The --close-branch flag can be used to mark the current branch head
804 closed. When all heads of a branch are closed, the branch will be con‐
805 sidered closed and no longer listed.
806 The --amend flag can be used to amend the parent of the working direc‐
808 tory with a new commit that contains the changes in the parent in addi‐
809 tion to those currently reported by hg status, if there are any. The
810 old commit is stored in a backup bundle in .hg/strip-backup (see hg
811 help bundle and hg help unbundle on how to restore it).
812 Message, user and date are taken from the amended commit unless speci‐
814 fied. When a message isn't specified on the command line, the editor
815 will open with the message of the amended commit.
816 It is not possible to amend public changesets (see hg help phases) or
818 changesets that have children.
819 See hg help dates for a list of formats valid for -d/--date.
821 Returns 0 on success, 1 if nothing changed.
823 Examples:
825 • commit all files ending in .py:
827 hg commit --include "set:**.py"
829 • commit all non-binary files:
831 hg commit --exclude "set:binary()"
833 • amend the current commit and set the date to now:
835 hg commit --amend --date now
837 Options:
839 -A, --addremove
841 mark new/missing files as added/removed before committing
842 --close-branch
844 mark a branch head as closed
845 --amend
847 amend the parent of the working directory
848 -s, --secret
850 use the secret phase for committing
851 -e, --edit
853 invoke editor on commit messages
854 --force-close-branch
856 forcibly close branch from a non-head changeset (ADVANCED)
857 -i, --interactive
859 use interactive mode
860 -I,--include <PATTERN[+]>
862 include names matching the given patterns
863 -X,--exclude <PATTERN[+]>
865 exclude names matching the given patterns
866 -m,--message <TEXT>
868 use text as commit message
869 -l,--logfile <FILE>
871 read commit message from file
872 -d,--date <DATE>
874 record the specified date as commit date
875 -u,--user <USER>
877 record the specified user as committer
878 -S, --subrepos
880 recurse into subrepositories
881 [+] marked option can be specified multiple times
883 aliases: ci
885 Change manipulation
887 abort
888 abort an unfinished operation (EXPERIMENTAL):
889 hg abort
891 Aborts a multistep operation like graft, histedit, rebase, merge, and
893 unshelve if they are in an unfinished state.
894 use --dry-run/-n to dry run the command.
896 Options:
898 -n, --dry-run
900 do not perform actions, just print output
901 backout
903 reverse effect of earlier changeset:
904 hg backout [OPTION]... [-r] REV
906 Prepare a new changeset with the effect of REV undone in the current
908 working directory. If no conflicts were encountered, it will be commit‐
909 ted immediately.
910 If REV is the parent of the working directory, then this new changeset
912 is committed automatically (unless --no-commit is specified).
913 Note hg backout cannot be used to fix either an unwanted or incorrect
915 merge.
916 Examples:
918 • Reverse the effect of the parent of the working directory. This
920 backout will be committed immediately:
921 hg backout -r .
923 • Reverse the effect of previous bad revision 23:
925 hg backout -r 23
927 • Reverse the effect of previous bad revision 23 and leave changes un‐
929 committed:
930 hg backout -r 23 --no-commit
932 hg commit -m "Backout revision 23"
933 By default, the pending changeset will have one parent, maintaining a
935 linear history. With --merge, the pending changeset will instead have
936 two parents: the old parent of the working directory and a new child of
937 REV that simply undoes REV.
938 Before version 1.7, the behavior without --merge was equivalent to
940 specifying --merge followed by hg update --clean . to cancel the merge
941 and leave the child of REV as a head to be merged separately.
942 See hg help dates for a list of formats valid for -d/--date.
944 See hg help revert for a way to restore files to the state of another
946 revision.
947 Returns 0 on success, 1 if nothing to backout or there are unresolved
949 files.
950 Options:
952 --merge
954 merge with old dirstate parent after backout
955 --commit
957 commit if no conflicts were encountered (DEPRECATED)
958 --no-commit
960 do not commit
961 --parent <REV>
963 parent to choose when backing out merge (DEPRECATED)
964 -r,--rev <REV>
966 revision to backout
967 -e, --edit
969 invoke editor on commit messages
970 -t,--tool <TOOL>
972 specify merge tool
973 -I,--include <PATTERN[+]>
975 include names matching the given patterns
976 -X,--exclude <PATTERN[+]>
978 exclude names matching the given patterns
979 -m,--message <TEXT>
981 use text as commit message
982 -l,--logfile <FILE>
984 read commit message from file
985 -d,--date <DATE>
987 record the specified date as commit date
988 -u,--user <USER>
990 record the specified user as committer
991 [+] marked option can be specified multiple times
993 continue
995 resumes an interrupted operation (EXPERIMENTAL):
996 hg continue
998 Finishes a multistep operation like graft, histedit, rebase, merge, and
1000 unshelve if they are in an interrupted state.
1001 use --dry-run/-n to dry run the command.
1003 Options:
1005 -n, --dry-run
1007 do not perform actions, just print output
1008 graft
1010 copy changes from other branches onto the current branch:
1011 hg graft [OPTION]... [-r REV]... REV...
1013 This command uses Mercurial's merge logic to copy individual changes
1015 from other branches without merging branches in the history graph. This
1016 is sometimes known as 'backporting' or 'cherry-picking'. By default,
1017 graft will copy user, date, and description from the source changesets.
1018 Changesets that are ancestors of the current revision, that have al‐
1020 ready been grafted, or that are merges will be skipped.
1021 If --log is specified, log messages will have a comment appended of the
1023 form:
1024 (grafted from CHANGESETHASH)
1026 If --force is specified, revisions will be grafted even if they are al‐
1028 ready ancestors of, or have been grafted to, the destination. This is
1029 useful when the revisions have since been backed out.
1030 If a graft merge results in conflicts, the graft process is interrupted
1032 so that the current merge can be manually resolved. Once all conflicts
1033 are addressed, the graft process can be continued with the -c/--con‐
1034 tinue option.
1035 The -c/--continue option reapplies all the earlier options.
1037 The --base option exposes more of how graft internally uses merge with
1039 a custom base revision. --base can be used to specify another ancestor
1040 than the first and only parent.
1041 The command:
1043 hg graft -r 345 --base 234
1045 is thus pretty much the same as:
1047 hg diff --from 234 --to 345 | hg import
1049 but using merge to resolve conflicts and track moved files.
1051 The result of a merge can thus be backported as a single commit by
1053 specifying one of the merge parents as base, and thus effectively
1054 grafting the changes from the other side.
1055 It is also possible to collapse multiple changesets and clean up his‐
1057 tory by specifying another ancestor as base, much like rebase --col‐
1058 lapse --keep.
1059 The commit message can be tweaked after the fact using commit --amend .
1061 For using non-ancestors as the base to backout changes, see the backout
1063 command and the hidden --parent option.
1064 Examples:
1066 • copy a single change to the stable branch and edit its description:
1068 hg update stable
1070 hg graft --edit 9393
1071 • graft a range of changesets with one exception, updating dates:
1073 hg graft -D "2085::2093 and not 2091"
1075 • continue a graft after resolving conflicts:
1077 hg graft -c
1079 • show the source of a grafted changeset:
1081 hg log --debug -r .
1083 • show revisions sorted by date:
1085 hg log -r "sort(all(), date)"
1087 • backport the result of a merge as a single commit:
1089 hg graft -r 123 --base 123^
1091 • land a feature branch as one changeset:
1093 hg up -cr default
1095 hg graft -r featureX --base "ancestor('featureX', 'default')"
1096 See hg help revisions for more about specifying revisions.
1098 Returns 0 on successful completion, 1 if there are unresolved files.
1100 Options:
1102 -r,--rev <REV[+]>
1104 revisions to graft
1105 --base <REV>
1107 base revision when doing the graft merge (ADVANCED)
1108 -c, --continue
1110 resume interrupted graft
1111 --stop stop interrupted graft
1113 --abort
1115 abort interrupted graft
1116 -e, --edit
1118 invoke editor on commit messages
1119 --log append graft info to log message
1121 --no-commit
1123 don't commit, just apply the changes in working directory
1124 -f, --force
1126 force graft
1127 -D, --currentdate
1129 record the current date as commit date
1130 -U, --currentuser
1132 record the current user as committer
1133 -d,--date <DATE>
1135 record the specified date as commit date
1136 -u,--user <USER>
1138 record the specified user as committer
1139 -t,--tool <TOOL>
1141 specify merge tool
1142 -n, --dry-run
1144 do not perform actions, just print output
1145 [+] marked option can be specified multiple times
1147 merge
1149 merge another revision into working directory:
1150 hg merge [-P] [[-r] REV]
1152 The current working directory is updated with all changes made in the
1154 requested revision since the last common predecessor revision.
1155 Files that changed between either parent are marked as changed for the
1157 next commit and a commit must be performed before any further updates
1158 to the repository are allowed. The next commit will have two parents.
1159 --tool can be used to specify the merge tool used for file merges. It
1161 overrides the HGMERGE environment variable and your configuration
1162 files. See hg help merge-tools for options.
1163 If no revision is specified, the working directory's parent is a head
1165 revision, and the current branch contains exactly one other head, the
1166 other head is merged with by default. Otherwise, an explicit revision
1167 with which to merge must be provided.
1168 See hg help resolve for information on handling file conflicts.
1170 To undo an uncommitted merge, use hg merge --abort which will check out
1172 a clean copy of the original merge parent, losing all changes.
1173 Returns 0 on success, 1 if there are unresolved files.
1175 Options:
1177 -f, --force
1179 force a merge including outstanding changes (DEPRECATED)
1180 -r,--rev <REV>
1182 revision to merge
1183 -P, --preview
1185 review revisions to merge (no merge is performed)
1186 --abort
1188 abort the ongoing merge
1189 -t,--tool <TOOL>
1191 specify merge tool
1192 Change organization
1194 bookmarks
1195 create a new bookmark or list existing bookmarks:
1196 hg bookmarks [OPTIONS]... [NAME]...
1198 Bookmarks are labels on changesets to help track lines of development.
1200 Bookmarks are unversioned and can be moved, renamed and deleted.
1201 Deleting or moving a bookmark has no effect on the associated change‐
1202 sets.
1203 Creating or updating to a bookmark causes it to be marked as 'active'.
1205 The active bookmark is indicated with a '*'. When a commit is made,
1206 the active bookmark will advance to the new commit. A plain hg update
1207 will also advance an active bookmark, if possible. Updating away from
1208 a bookmark will cause it to be deactivated.
1209 Bookmarks can be pushed and pulled between repositories (see hg help
1211 push and hg help pull). If a shared bookmark has diverged, a new 'di‐
1212 vergent bookmark' of the form 'name@path' will be created. Using hg
1213 merge will resolve the divergence.
1214 Specifying bookmark as '.' to -m/-d/-l options is equivalent to speci‐
1216 fying the active bookmark's name.
1217 A bookmark named '@' has the special property that hg clone will check
1219 it out by default if it exists.
1220 Template:
1222 The following keywords are supported in addition to the common template
1224 keywords and functions such as {bookmark}. See also hg help templates.
1225 active Boolean. True if the bookmark is active.
1227 Examples:
1229 • create an active bookmark for a new line of development:
1231 hg book new-feature
1233 • create an inactive bookmark as a place marker:
1235 hg book -i reviewed
1237 • create an inactive bookmark on another changeset:
1239 hg book -r .^ tested
1241 • rename bookmark turkey to dinner:
1243 hg book -m turkey dinner
1245 • move the '@' bookmark from another branch:
1247 hg book -f @
1249 • print only the active bookmark name:
1251 hg book -ql .
1253 Options:
1255 -f, --force
1257 force
1258 -r,--rev <REV>
1260 revision for bookmark action
1261 -d, --delete
1263 delete a given bookmark
1264 -m,--rename <OLD>
1266 rename a given bookmark
1267 -i, --inactive
1269 mark a bookmark inactive
1270 -l, --list
1272 list existing bookmarks
1273 -T,--template <TEMPLATE>
1275 display with template
1276 aliases: bookmark
1278 branch
1280 set or show the current branch name:
1281 hg branch [-fC] [NAME]
1283 Note Branch names are permanent and global. Use hg bookmark to create
1285 a light-weight bookmark instead. See hg help glossary for more
1286 information about named branches and bookmarks.
1287 With no argument, show the current branch name. With one argument, set
1289 the working directory branch name (the branch will not exist in the
1290 repository until the next commit). Standard practice recommends that
1291 primary development take place on the 'default' branch.
1292 Unless -f/--force is specified, branch will not let you set a branch
1294 name that already exists.
1295 Use -C/--clean to reset the working directory branch to that of the
1297 parent of the working directory, negating a previous branch change.
1298 Use the command hg update to switch to an existing branch. Use hg com‐
1300 mit --close-branch to mark this branch head as closed. When all heads
1301 of a branch are closed, the branch will be considered closed.
1302 Returns 0 on success.
1304 Options:
1306 -f, --force
1308 set branch name even if it shadows an existing branch
1309 -C, --clean
1311 reset branch name to parent branch name
1312 -r,--rev <VALUE[+]>
1314 change branches of the given revs (EXPERIMENTAL)
1315 [+] marked option can be specified multiple times
1317 branches
1319 list repository named branches:
1320 hg branches [-c]
1322 List the repository's named branches, indicating which ones are inac‐
1324 tive. If -c/--closed is specified, also list branches which have been
1325 marked closed (see hg commit --close-branch).
1326 Use the command hg update to switch to an existing branch.
1328 Template:
1330 The following keywords are supported in addition to the common template
1332 keywords and functions such as {branch}. See also hg help templates.
1333 active Boolean. True if the branch is active.
1335 closed Boolean. True if the branch is closed.
1337 current
1339 Boolean. True if it is the current branch.
1340 Returns 0.
1342 Options:
1344 -a, --active
1346 show only branches that have unmerged heads (DEPRECATED)
1347 -c, --closed
1349 show normal and closed branches
1350 -r,--rev <VALUE[+]>
1352 show branch name(s) of the given rev
1353 -T,--template <TEMPLATE>
1355 display with template
1356 [+] marked option can be specified multiple times
1358 phase
1360 set or show the current phase name:
1361 hg phase [-p|-d|-s] [-f] [-r] [REV...]
1363 With no argument, show the phase name of the current revision(s).
1365 With one of -p/--public, -d/--draft or -s/--secret, change the phase
1367 value of the specified revisions.
1368 Unless -f/--force is specified, hg phase won't move changesets from a
1370 lower phase to a higher phase. Phases are ordered as follows:
1371 public < draft < secret
1373 Returns 0 on success, 1 if some phases could not be changed.
1375 (For more information about the phases concept, see hg help phases.)
1377 Options:
1379 -p, --public
1381 set changeset phase to public
1382 -d, --draft
1384 set changeset phase to draft
1385 -s, --secret
1387 set changeset phase to secret
1388 -f, --force
1390 allow to move boundary backward
1391 -r,--rev <REV[+]>
1393 target revision
1394 [+] marked option can be specified multiple times
1396 tag
1398 add one or more tags for the current or given revision:
1399 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
1401 Name a particular revision using <name>.
1403 Tags are used to name particular revisions of the repository and are
1405 very useful to compare different revisions, to go back to significant
1406 earlier versions or to mark branch points as releases, etc. Changing an
1407 existing tag is normally disallowed; use -f/--force to override.
1408 If no revision is given, the parent of the working directory is used.
1410 To facilitate version control, distribution, and merging of tags, they
1412 are stored as a file named ".hgtags" which is managed similarly to
1413 other project files and can be hand-edited if necessary. This also
1414 means that tagging creates a new commit. The file ".hg/localtags" is
1415 used for local tags (not shared among repositories).
1416 Tag commits are usually made at the head of a branch. If the parent of
1418 the working directory is not a branch head, hg tag aborts; use
1419 -f/--force to force the tag commit to be based on a non-head changeset.
1420 See hg help dates for a list of formats valid for -d/--date.
1422 Since tag names have priority over branch names during revision lookup,
1424 using an existing branch name as a tag name is discouraged.
1425 Returns 0 on success.
1427 Options:
1429 -f, --force
1431 force tag
1432 -l, --local
1434 make the tag local
1435 -r,--rev <REV>
1437 revision to tag
1438 --remove
1440 remove a tag
1441 -e, --edit
1443 invoke editor on commit messages
1444 -m,--message <TEXT>
1446 use text as commit message
1447 -d,--date <DATE>
1449 record the specified date as commit date
1450 -u,--user <USER>
1452 record the specified user as committer
1453 tags
1455 list repository tags:
1456 hg tags
1458 This lists both regular and local tags. When the -v/--verbose switch is
1460 used, a third column "local" is printed for local tags. When the
1461 -q/--quiet switch is used, only the tag name is printed.
1462 Template:
1464 The following keywords are supported in addition to the common template
1466 keywords and functions such as {tag}. See also hg help templates.
1467 type String. local for local tags.
1469 Returns 0 on success.
1471 Options:
1473 -T,--template <TEMPLATE>
1475 display with template
1476 File content management
1478 annotate
1479 show changeset information by line for each file:
1480 hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...
1482 List changes in files, showing the revision id responsible for each
1484 line.
1485 This command is useful for discovering when a change was made and by
1487 whom.
1488 If you include --file, --user, or --date, the revision number is sup‐
1490 pressed unless you also include --number.
1491 Without the -a/--text option, annotate will avoid processing files it
1493 detects as binary. With -a, annotate will annotate the file anyway, al‐
1494 though the results will probably be neither useful nor desirable.
1495 Template:
1497 The following keywords are supported in addition to the common template
1499 keywords and functions. See also hg help templates.
1500 lines List of lines with annotation data.
1502 path String. Repository-absolute path of the specified file.
1504 And each entry of {lines} provides the following sub-keywords in addi‐
1506 tion to {date}, {node}, {rev}, {user}, etc.
1507 line String. Line content.
1509 lineno Integer. Line number at that revision.
1511 path String. Repository-absolute path of the file at that revision.
1513 See hg help templates.operators for the list expansion syntax.
1515 Returns 0 on success.
1517 Options:
1519 -r,--rev <REV>
1521 annotate the specified revision
1522 --follow
1524 follow copies/renames and list the filename (DEPRECATED)
1525 --no-follow
1527 don't follow copies and renames
1528 -a, --text
1530 treat all files as text
1531 -u, --user
1533 list the author (long with -v)
1534 -f, --file
1536 list the filename
1537 -d, --date
1539 list the date (short with -q)
1540 -n, --number
1542 list the revision number (default)
1543 -c, --changeset
1545 list the changeset
1546 -l, --line-number
1548 show line number at the first appearance
1549 --skip <REV[+]>
1551 revset to not display (EXPERIMENTAL)
1552 -w, --ignore-all-space
1554 ignore white space when comparing lines
1555 -b, --ignore-space-change
1557 ignore changes in the amount of white space
1558 -B, --ignore-blank-lines
1560 ignore changes whose lines are all blank
1561 -Z, --ignore-space-at-eol
1563 ignore changes in whitespace at EOL
1564 -I,--include <PATTERN[+]>
1566 include names matching the given patterns
1567 -X,--exclude <PATTERN[+]>
1569 exclude names matching the given patterns
1570 -T,--template <TEMPLATE>
1572 display with template
1573 [+] marked option can be specified multiple times
1575 aliases: blame
1577 cat
1579 output the current or given revision of files:
1580 hg cat [OPTION]... FILE...
1582 Print the specified files as they were at the given revision. If no re‐
1584 vision is given, the parent of the working directory is used.
1585 Output may be to a file, in which case the name of the file is given
1587 using a template string. See hg help templates. In addition to the com‐
1588 mon template keywords, the following formatting rules are supported:
1589 %%
1591 literal "%" character
1593 %s
1595 basename of file being printed
1597 %d
1599 dirname of file being printed, or '.' if in repository root
1601 %p
1603 root-relative path name of file being printed
1605 %H
1607 changeset hash (40 hexadecimal digits)
1609 %R
1611 changeset revision number
1613 %h
1615 short-form changeset hash (12 hexadecimal digits)
1617 %r
1619 zero-padded changeset revision number
1621 %b
1623 basename of the exporting repository
1625 \
1627 literal "" character
1629 Template:
1631 The following keywords are supported in addition to the common template
1633 keywords and functions. See also hg help templates.
1634 data String. File content.
1636 path String. Repository-absolute path of the file.
1638 Returns 0 on success.
1640 Options:
1642 -o,--output <FORMAT>
1644 print output to file with formatted name
1645 -r,--rev <REV>
1647 print the given revision
1648 --decode
1650 apply any matching decode filter
1651 -I,--include <PATTERN[+]>
1653 include names matching the given patterns
1654 -X,--exclude <PATTERN[+]>
1656 exclude names matching the given patterns
1657 -T,--template <TEMPLATE>
1659 display with template
1660 [+] marked option can be specified multiple times
1662 copy
1664 mark files as copied for the next commit:
1665 hg copy [OPTION]... (SOURCE... DEST | --forget DEST...)
1667 Mark dest as having copies of source files. If dest is a directory,
1669 copies are put in that directory. If dest is a file, the source must be
1670 a single file.
1671 By default, this command copies the contents of files as they exist in
1673 the working directory. If invoked with -A/--after, the operation is
1674 recorded, but no copying is performed.
1675 To undo marking a destination file as copied, use --forget. With that
1677 option, all given (positional) arguments are unmarked as copies. The
1678 destination file(s) will be left in place (still tracked). Note that hg
1679 copy --forget behaves the same way as hg rename --forget.
1680 This command takes effect with the next commit by default.
1682 Returns 0 on success, 1 if errors are encountered.
1684 Options:
1686 --forget
1688 unmark a destination file as copied
1689 -A, --after
1691 record a copy that has already occurred
1692 --at-rev <REV>
1694 (un)mark copies in the given revision (EXPERIMENTAL)
1695 -f, --force
1697 forcibly copy over an existing managed file
1698 -I,--include <PATTERN[+]>
1700 include names matching the given patterns
1701 -X,--exclude <PATTERN[+]>
1703 exclude names matching the given patterns
1704 -n, --dry-run
1706 do not perform actions, just print output
1707 [+] marked option can be specified multiple times
1709 aliases: cp
1711 diff
1713 diff repository (or selected files):
1714 hg diff [OPTION]... ([-c REV] | [--from REV1] [--to REV2]) [FILE]...
1716 Show differences between revisions for the specified files.
1718 Differences between files are shown using the unified diff format.
1720 Note hg diff may generate unexpected results for merges, as it will
1722 default to comparing against the working directory's first par‐
1723 ent changeset if no revisions are specified. To diff against
1724 the conflict regions, you can use --config diff.merge=yes.
1725 By default, the working directory files are compared to its first par‐
1727 ent. To see the differences from another revision, use --from. To see
1728 the difference to another revision, use --to. For example, hg diff
1729 --from .^ will show the differences from the working copy's grandparent
1730 to the working copy, hg diff --to . will show the diff from the working
1731 copy to its parent (i.e. the reverse of the default), and hg diff
1732 --from 1.0 --to 1.2 will show the diff between those two revisions.
1733 Alternatively you can specify -c/--change with a revision to see the
1735 changes in that changeset relative to its first parent (i.e. hg diff -c
1736 42 is equivalent to hg diff --from 42^ --to 42)
1737 Without the -a/--text option, diff will avoid generating diffs of files
1739 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1740 bly with undesirable results.
1741 Use the -g/--git option to generate diffs in the git extended diff for‐
1743 mat. For more information, read hg help diffs.
1744 Examples:
1746 • compare a file in the current working directory to its parent:
1748 hg diff foo.c
1750 • compare two historical versions of a directory, with rename info:
1752 hg diff --git --from 1.0 --to 1.2 lib/
1754 • get change stats relative to the last change on some date:
1756 hg diff --stat --from "date('may 2')"
1758 • diff all newly-added files that contain a keyword:
1760 hg diff "set:added() and grep(GNU)"
1762 • compare a revision and its parents:
1764 hg diff -c 9353 # compare against first parent
1766 hg diff --from 9353^ --to 9353 # same using revset syntax
1767 hg diff --from 9353^2 --to 9353 # compare against the second parent
1768 Returns 0 on success.
1770 Options:
1772 -r,--rev <REV[+]>
1774 revision (DEPRECATED)
1775 --from <REV1>
1777 revision to diff from
1778 --to <REV2>
1780 revision to diff to
1781 -c,--change <REV>
1783 change made by revision
1784 -a, --text
1786 treat all files as text
1787 -g, --git
1789 use git extended diff format (DEFAULT: diff.git)
1790 --binary
1792 generate binary diffs in git mode (default)
1793 --nodates
1795 omit dates from diff headers
1796 --noprefix
1798 omit a/ and b/ prefixes from filenames
1799 -p, --show-function
1801 show which function each change is in (DEFAULT: diff.showfunc)
1802 --reverse
1804 produce a diff that undoes the changes
1805 -w, --ignore-all-space
1807 ignore white space when comparing lines
1808 -b, --ignore-space-change
1810 ignore changes in the amount of white space
1811 -B, --ignore-blank-lines
1813 ignore changes whose lines are all blank
1814 -Z, --ignore-space-at-eol
1816 ignore changes in whitespace at EOL
1817 -U,--unified <NUM>
1819 number of lines of context to show
1820 --stat output diffstat-style summary of changes
1822 --root <DIR>
1824 produce diffs relative to subdirectory
1825 -I,--include <PATTERN[+]>
1827 include names matching the given patterns
1828 -X,--exclude <PATTERN[+]>
1830 exclude names matching the given patterns
1831 -S, --subrepos
1833 recurse into subrepositories
1834 [+] marked option can be specified multiple times
1836 grep
1838 search for a pattern in specified files:
1839 hg grep [--diff] [OPTION]... PATTERN [FILE]...
1841 Search the working directory or revision history for a regular expres‐
1843 sion in the specified files for the entire repository.
1844 By default, grep searches the repository files in the working directory
1846 and prints the files where it finds a match. To specify historical re‐
1847 visions instead of the working directory, use the --rev flag.
1848 To search instead historical revision differences that contains a
1850 change in match status ("-" for a match that becomes a non-match, or
1851 "+" for a non-match that becomes a match), use the --diff flag.
1852 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1854 If no FILEs are specified and the --rev flag isn't supplied, all files
1856 in the working directory are searched. When using the --rev flag and
1857 specifying FILEs, use the --follow argument to also follow the speci‐
1858 fied FILEs across renames and copies.
1859 Template:
1861 The following keywords are supported in addition to the common template
1863 keywords and functions. See also hg help templates.
1864 change String. Character denoting insertion + or removal -. Available
1866 if --diff is specified.
1867 lineno Integer. Line number of the match.
1869 path String. Repository-absolute path of the file.
1871 texts List of text chunks.
1873 And each entry of {texts} provides the following sub-keywords.
1875 matched
1877 Boolean. True if the chunk matches the specified pattern.
1878 text String. Chunk content.
1880 See hg help templates.operators for the list expansion syntax.
1882 Returns 0 if a match is found, 1 otherwise.
1884 Options:
1886 -0, --print0
1888 end fields with NUL
1889 --all an alias to --diff (DEPRECATED)
1891 --diff search revision differences for when the pattern was added or
1893 removed
1894 -a, --text
1896 treat all files as text
1897 -f, --follow
1899 follow changeset history, or file history across copies and re‐
1900 names
1901 -i, --ignore-case
1903 ignore case when matching
1904 -l, --files-with-matches
1906 print only filenames and revisions that match
1907 -n, --line-number
1909 print matching line numbers
1910 -r,--rev <REV[+]>
1912 search files changed within revision range
1913 --all-files
1915 include all files in the changeset while grepping (DEPRECATED)
1916 -u, --user
1918 list the author (long with -v)
1919 -d, --date
1921 list the date (short with -q)
1922 -T,--template <TEMPLATE>
1924 display with template
1925 -I,--include <PATTERN[+]>
1927 include names matching the given patterns
1928 -X,--exclude <PATTERN[+]>
1930 exclude names matching the given patterns
1931 [+] marked option can be specified multiple times
1933 Change navigation
1935 bisect
1936 subdivision search of changesets:
1937 hg bisect [-gbsr] [-U] [-c CMD] [REV]
1939 This command helps to find changesets which introduce problems. To use,
1941 mark the earliest changeset you know exhibits the problem as bad, then
1942 mark the latest changeset which is free from the problem as good. Bi‐
1943 sect will update your working directory to a revision for testing (un‐
1944 less the -U/--noupdate option is specified). Once you have performed
1945 tests, mark the working directory as good or bad, and bisect will ei‐
1946 ther update to another candidate changeset or announce that it has
1947 found the bad revision.
1948 As a shortcut, you can also use the revision argument to mark a revi‐
1950 sion as good or bad without checking it out first.
1951 If you supply a command, it will be used for automatic bisection. The
1953 environment variable HG_NODE will contain the ID of the changeset being
1954 tested. The exit status of the command will be used to mark revisions
1955 as good or bad: status 0 means good, 125 means to skip the revision,
1956 127 (command not found) will abort the bisection, and any other
1957 non-zero exit status means the revision is bad.
1958 Some examples:
1960 • start a bisection with known bad revision 34, and good revision 12:
1962 hg bisect --bad 34
1964 hg bisect --good 12
1965 • advance the current bisection by marking current revision as good or
1967 bad:
1968 hg bisect --good
1970 hg bisect --bad
1971 • mark the current revision, or a known revision, to be skipped (e.g.
1973 if that revision is not usable because of another issue):
1974 hg bisect --skip
1976 hg bisect --skip 23
1977 • skip all revisions that do not touch directories foo or bar:
1979 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
1981 • forget the current bisection:
1983 hg bisect --reset
1985 • use 'make && make tests' to automatically find the first broken revi‐
1987 sion:
1988 hg bisect --reset
1990 hg bisect --bad 34
1991 hg bisect --good 12
1992 hg bisect --command "make && make tests"
1993 • see all changesets whose states are already known in the current bi‐
1995 section:
1996 hg log -r "bisect(pruned)"
1998 • see the changeset currently being bisected (especially useful if run‐
2000 ning with -U/--noupdate):
2001 hg log -r "bisect(current)"
2003 • see all changesets that took part in the current bisection:
2005 hg log -r "bisect(range)"
2007 • you can even get a nice graph:
2009 hg log --graph -r "bisect(range)"
2011 See hg help revisions.bisect for more about the bisect() predicate.
2013 Returns 0 on success.
2015 Options:
2017 -r, --reset
2019 reset bisect state
2020 -g, --good
2022 mark changeset good
2023 -b, --bad
2025 mark changeset bad
2026 -s, --skip
2028 skip testing changeset
2029 -e, --extend
2031 extend the bisect range
2032 -c,--command <CMD>
2034 use command to check changeset state
2035 -U, --noupdate
2037 do not update to target
2038 heads
2040 show branch heads:
2041 hg heads [-ct] [-r STARTREV] [REV]...
2043 With no arguments, show all open branch heads in the repository.
2045 Branch heads are changesets that have no descendants on the same
2046 branch. They are where development generally takes place and are the
2047 usual targets for update and merge operations.
2048 If one or more REVs are given, only open branch heads on the branches
2050 associated with the specified changesets are shown. This means that you
2051 can use hg heads . to see the heads on the currently checked-out
2052 branch.
2053 If -c/--closed is specified, also show branch heads marked closed (see
2055 hg commit --close-branch).
2056 If STARTREV is specified, only those heads that are descendants of
2058 STARTREV will be displayed.
2059 If -t/--topo is specified, named branch mechanics will be ignored and
2061 only topological heads (changesets with no children) will be shown.
2062 Returns 0 if matching heads are found, 1 if not.
2064 Options:
2066 -r,--rev <STARTREV>
2068 show only heads which are descendants of STARTREV
2069 -t, --topo
2071 show topological heads only
2072 -a, --active
2074 show active branchheads only (DEPRECATED)
2075 -c, --closed
2077 show normal and closed branch heads
2078 --style <STYLE>
2080 display using template map file (DEPRECATED)
2081 -T,--template <TEMPLATE>
2083 display with template
2084 identify
2086 identify the working directory or specified revision:
2087 hg identify [-nibtB] [-r REV] [SOURCE]
2089 Print a summary identifying the repository state at REV using one or
2091 two parent hash identifiers, followed by a "+" if the working directory
2092 has uncommitted changes, the branch name (if not default), a list of
2093 tags, and a list of bookmarks.
2094 When REV is not given, print a summary of the current state of the
2096 repository including the working directory. Specify -r. to get informa‐
2097 tion of the working directory parent without scanning uncommitted
2098 changes.
2099 Specifying a path to a repository root or Mercurial bundle will cause
2101 lookup to operate on that repository/bundle.
2102 Template:
2104 The following keywords are supported in addition to the common template
2106 keywords and functions. See also hg help templates.
2107 dirty String. Character + denoting if the working directory has uncom‐
2109 mitted changes.
2110 id String. One or two nodes, optionally followed by +.
2112 parents
2114 List of strings. Parent nodes of the changeset.
2115 Examples:
2117 • generate a build identifier for the working directory:
2119 hg id --id > build-id.dat
2121 • find the revision corresponding to a tag:
2123 hg id -n -r 1.3
2125 • check the most recent revision of a remote repository:
2127 hg id -r tip https://www.mercurial-scm.org/repo/hg/
2129 See hg log for generating more information about specific revisions,
2131 including full hash identifiers.
2132 Returns 0 if successful.
2134 Options:
2136 -r,--rev <REV>
2138 identify the specified revision
2139 -n, --num
2141 show local revision number
2142 -i, --id
2144 show global revision id
2145 -b, --branch
2147 show branch
2148 -t, --tags
2150 show tags
2151 -B, --bookmarks
2153 show bookmarks
2154 -e,--ssh <CMD>
2156 specify ssh command to use
2157 --remotecmd <CMD>
2159 specify hg command to run on the remote side
2160 --insecure
2162 do not verify server certificate (ignoring web.cacerts config)
2163 -T,--template <TEMPLATE>
2165 display with template
2166 aliases: id
2168 log
2170 show revision history of entire repository or files:
2171 hg log [OPTION]... [FILE]
2173 Print the revision history of the specified files or the entire
2175 project.
2176 If no revision range is specified, the default is tip:0 unless --follow
2178 is set.
2179 File history is shown without following rename or copy history of
2181 files. Use -f/--follow with a filename to follow history across renames
2182 and copies. --follow without a filename will only show ancestors of the
2183 starting revisions. The starting revisions can be specified by
2184 -r/--rev, which default to the working directory parent.
2185 By default this command prints revision number and changeset id, tags,
2187 non-trivial parents, user, date and time, and a summary for each com‐
2188 mit. When the -v/--verbose switch is used, the list of changed files
2189 and full commit message are shown.
2190 With --graph the revisions are shown as an ASCII art DAG with the most
2192 recent changeset at the top. 'o' is a changeset, '@' is a working di‐
2193 rectory parent, '%' is a changeset involved in an unresolved merge con‐
2194 flict, '_' closes a branch, 'x' is obsolete, '*' is unstable, and '+'
2195 represents a fork where the changeset from the lines below is a parent
2196 of the 'o' merge on the same line. Paths in the DAG are represented
2197 with '|', '/' and so forth. ':' in place of a '|' indicates one or more
2198 revisions in a path are omitted.
2199 Use -L/--line-range FILE,M:N options to follow the history of lines
2201 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2202 fied line range will be shown. This option requires --follow; it can be
2203 specified multiple times. Currently, this option is not compatible with
2204 --graph. This option is experimental.
2205 Note hg log --patch may generate unexpected diff output for merge
2207 changesets, as it will only compare the merge changeset against
2208 its first parent. Also, only files different from BOTH parents
2209 will appear in files:.
2210 Note For performance reasons, hg log FILE may omit duplicate changes
2212 made on branches and will not show removals or mode changes. To
2213 see all such changes, use the --removed switch.
2214 Note The history resulting from -L/--line-range options depends on
2216 diff options; for instance if white-spaces are ignored, respec‐
2217 tive changes with only white-spaces in specified line range will
2218 not be listed.
2219 Some examples:
2221 • changesets with full descriptions and file lists:
2223 hg log -v
2225 • changesets ancestral to the working directory:
2227 hg log -f
2229 • last 10 commits on the current branch:
2231 hg log -l 10 -b .
2233 • changesets showing all modifications of a file, including removals:
2235 hg log --removed file.c
2237 • all changesets that touch a directory, with diffs, excluding merges:
2239 hg log -Mp lib/
2241 • all revision numbers that match a keyword:
2243 hg log -k bug --template "{rev}\n"
2245 • the full hash identifier of the working directory parent:
2247 hg log -r . --template "{node}\n"
2249 • list available log templates:
2251 hg log -T list
2253 • check if a given changeset is included in a tagged release:
2255 hg log -r "a21ccf and ancestor(1.9)"
2257 • find all changesets by some user in a date range:
2259 hg log -k alice -d "may 2008 to jul 2008"
2261 • summary of all changesets after the last tag:
2263 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2265 • changesets touching lines 13 to 23 for file.c:
2267 hg log -L file.c,13:23
2269 • changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2271 main.c with patch:
2272 hg log -L file.c,13:23 -L main.c,2:6 -p
2274 See hg help dates for a list of formats valid for -d/--date.
2276 See hg help revisions for more about specifying and ordering revisions.
2278 See hg help templates for more about pre-packaged styles and specifying
2280 custom templates. The default template used by the log command can be
2281 customized via the command-templates.log configuration setting.
2282 Returns 0 on success.
2284 Options:
2286 -f, --follow
2288 follow changeset history, or file history across copies and re‐
2289 names
2290 --follow-first
2292 only follow the first parent of merge changesets (DEPRECATED)
2293 -d,--date <DATE>
2295 show revisions matching date spec
2296 -C, --copies
2298 show copied files
2299 -k,--keyword <TEXT[+]>
2301 do case-insensitive search for a given text
2302 -r,--rev <REV[+]>
2304 revisions to select or follow from
2305 -L,--line-range <FILE,RANGE[+]>
2307 follow line range of specified file (EXPERIMENTAL)
2308 --removed
2310 include revisions where files were removed
2311 -m, --only-merges
2313 show only merges (DEPRECATED) (use -r "merge()" instead)
2314 -u,--user <USER[+]>
2316 revisions committed by user
2317 --only-branch <BRANCH[+]>
2319 show only changesets within the given named branch (DEPRECATED)
2320 -b,--branch <BRANCH[+]>
2322 show changesets within the given named branch
2323 -B,--bookmark <BOOKMARK[+]>
2325 show changesets within the given bookmark
2326 -P,--prune <REV[+]>
2328 do not display revision or any of its ancestors
2329 -p, --patch
2331 show patch
2332 -g, --git
2334 use git extended diff format
2335 -l,--limit <NUM>
2337 limit number of changes displayed
2338 -M, --no-merges
2340 do not show merges
2341 --stat output diffstat-style summary of changes
2343 -G, --graph
2345 show the revision DAG
2346 --style <STYLE>
2348 display using template map file (DEPRECATED)
2349 -T,--template <TEMPLATE>
2351 display with template
2352 -I,--include <PATTERN[+]>
2354 include names matching the given patterns
2355 -X,--exclude <PATTERN[+]>
2357 exclude names matching the given patterns
2358 [+] marked option can be specified multiple times
2360 aliases: history
2362 parents
2364 show the parents of the working directory or revision (DEPRECATED):
2365 hg parents [-r REV] [FILE]
2367 Print the working directory's parent revisions. If a revision is given
2369 via -r/--rev, the parent of that revision will be printed. If a file
2370 argument is given, the revision in which the file was last changed (be‐
2371 fore the working directory revision or the argument to --rev if given)
2372 is printed.
2373 This command is equivalent to:
2375 hg log -r "p1()+p2()" or
2377 hg log -r "p1(REV)+p2(REV)" or
2378 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2379 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2380 See hg summary and hg help revsets for related information.
2382 Returns 0 on success.
2384 Options:
2386 -r,--rev <REV>
2388 show parents of the specified revision
2389 --style <STYLE>
2391 display using template map file (DEPRECATED)
2392 -T,--template <TEMPLATE>
2394 display with template
2395 tip
2397 show the tip revision (DEPRECATED):
2398 hg tip [-p] [-g]
2400 The tip revision (usually just called the tip) is the changeset most
2402 recently added to the repository (and therefore the most recently
2403 changed head).
2404 If you have just made a commit, that commit will be the tip. If you
2406 have just pulled changes from another repository, the tip of that
2407 repository becomes the current tip. The "tip" tag is special and cannot
2408 be renamed or assigned to a different changeset.
2409 This command is deprecated, please use hg heads instead.
2411 Returns 0 on success.
2413 Options:
2415 -p, --patch
2417 show patch
2418 -g, --git
2420 use git extended diff format
2421 --style <STYLE>
2423 display using template map file (DEPRECATED)
2424 -T,--template <TEMPLATE>
2426 display with template
2427 Working directory management
2429 add
2430 add the specified files on the next commit:
2431 hg add [OPTION]... [FILE]...
2433 Schedule files to be version controlled and added to the repository.
2435 The files will be added to the repository at the next commit. To undo
2437 an add before that, see hg forget.
2438 If no names are given, add all files to the repository (except files
2440 matching .hgignore).
2441 Examples:
2443 • New (unknown) files are added automatically by hg add:
2445 $ ls
2447 foo.c
2448 $ hg status
2449 ? foo.c
2450 $ hg add
2451 adding foo.c
2452 $ hg status
2453 A foo.c
2454 • Specific files to be added can be specified:
2456 $ ls
2458 bar.c foo.c
2459 $ hg status
2460 ? bar.c
2461 ? foo.c
2462 $ hg add bar.c
2463 $ hg status
2464 A bar.c
2465 ? foo.c
2466 Returns 0 if all files are successfully added.
2468 Options:
2470 -I,--include <PATTERN[+]>
2472 include names matching the given patterns
2473 -X,--exclude <PATTERN[+]>
2475 exclude names matching the given patterns
2476 -S, --subrepos
2478 recurse into subrepositories
2479 -n, --dry-run
2481 do not perform actions, just print output
2482 [+] marked option can be specified multiple times
2484 addremove
2486 add all new files, delete all missing files:
2487 hg addremove [OPTION]... [FILE]...
2489 Add all new files and remove all missing files from the repository.
2491 Unless names are given, new files are ignored if they match any of the
2493 patterns in .hgignore. As with add, these changes take effect at the
2494 next commit.
2495 Use the -s/--similarity option to detect renamed files. This option
2497 takes a percentage between 0 (disabled) and 100 (files must be identi‐
2498 cal) as its parameter. With a parameter greater than 0, this compares
2499 every removed file with every added file and records those similar
2500 enough as renames. Detecting renamed files this way can be expensive.
2501 After using this option, hg status -C can be used to check which files
2502 were identified as moved or renamed. If not specified, -s/--similarity
2503 defaults to 100 and only renames of identical files are detected.
2504 Examples:
2506 • A number of files (bar.c and foo.c) are new, while foobar.c has
2508 been removed (without using hg remove) from the repository:
2509 $ ls
2511 bar.c foo.c
2512 $ hg status
2513 ! foobar.c
2514 ? bar.c
2515 ? foo.c
2516 $ hg addremove
2517 adding bar.c
2518 adding foo.c
2519 removing foobar.c
2520 $ hg status
2521 A bar.c
2522 A foo.c
2523 R foobar.c
2524 • A file foobar.c was moved to foo.c without using hg rename. Af‐
2526 terwards, it was edited slightly:
2527 $ ls
2529 foo.c
2530 $ hg status
2531 ! foobar.c
2532 ? foo.c
2533 $ hg addremove --similarity 90
2534 removing foobar.c
2535 adding foo.c
2536 recording removal of foobar.c as rename to foo.c (94% similar)
2537 $ hg status -C
2538 A foo.c
2539 foobar.c
2540 R foobar.c
2541 Returns 0 if all files are successfully added.
2543 Options:
2545 -s,--similarity <SIMILARITY>
2547 guess renamed files by similarity (0<=s<=100)
2548 -S, --subrepos
2550 recurse into subrepositories
2551 -I,--include <PATTERN[+]>
2553 include names matching the given patterns
2554 -X,--exclude <PATTERN[+]>
2556 exclude names matching the given patterns
2557 -n, --dry-run
2559 do not perform actions, just print output
2560 [+] marked option can be specified multiple times
2562 files
2564 list tracked files:
2565 hg files [OPTION]... [FILE]...
2567 Print files under Mercurial control in the working directory or speci‐
2569 fied revision for given files (excluding removed files). Files can be
2570 specified as filenames or filesets.
2571 If no files are given to match, this command prints the names of all
2573 files under Mercurial control.
2574 Template:
2576 The following keywords are supported in addition to the common template
2578 keywords and functions. See also hg help templates.
2579 flags String. Character denoting file's symlink and executable bits.
2581 path String. Repository-absolute path of the file.
2583 size Integer. Size of the file in bytes.
2585 Examples:
2587 • list all files under the current directory:
2589 hg files .
2591 • shows sizes and flags for current revision:
2593 hg files -vr .
2595 • list all files named README:
2597 hg files -I "**/README"
2599 • list all binary files:
2601 hg files "set:binary()"
2603 • find files containing a regular expression:
2605 hg files "set:grep('bob')"
2607 • search tracked file contents with xargs and grep:
2609 hg files -0 | xargs -0 grep foo
2611 See hg help patterns and hg help filesets for more information on spec‐
2613 ifying file patterns.
2614 Returns 0 if a match is found, 1 otherwise.
2616 Options:
2618 -r,--rev <REV>
2620 search the repository as it is in REV
2621 -0, --print0
2623 end filenames with NUL, for use with xargs
2624 -I,--include <PATTERN[+]>
2626 include names matching the given patterns
2627 -X,--exclude <PATTERN[+]>
2629 exclude names matching the given patterns
2630 -T,--template <TEMPLATE>
2632 display with template
2633 -S, --subrepos
2635 recurse into subrepositories
2636 [+] marked option can be specified multiple times
2638 forget
2640 forget the specified files on the next commit:
2641 hg forget [OPTION]... FILE...
2643 Mark the specified files so they will no longer be tracked after the
2645 next commit.
2646 This only removes files from the current branch, not from the entire
2648 project history, and it does not delete them from the working direc‐
2649 tory.
2650 To delete the file from the working directory, see hg remove.
2652 To undo a forget before the next commit, see hg add.
2654 Examples:
2656 • forget newly-added binary files:
2658 hg forget "set:added() and binary()"
2660 • forget files that would be excluded by .hgignore:
2662 hg forget "set:hgignore()"
2664 Returns 0 on success.
2666 Options:
2668 -i, --interactive
2670 use interactive mode
2671 -I,--include <PATTERN[+]>
2673 include names matching the given patterns
2674 -X,--exclude <PATTERN[+]>
2676 exclude names matching the given patterns
2677 -n, --dry-run
2679 do not perform actions, just print output
2680 [+] marked option can be specified multiple times
2682 locate
2684 locate files matching specific patterns (DEPRECATED):
2685 hg locate [OPTION]... [PATTERN]...
2687 Print files under Mercurial control in the working directory whose
2689 names match the given patterns.
2690 By default, this command searches all directories in the working direc‐
2692 tory. To search just the current directory and its subdirectories, use
2693 "--include .".
2694 If no patterns are given to match, this command prints the names of all
2696 files under Mercurial control in the working directory.
2697 If you want to feed the output of this command into the "xargs" com‐
2699 mand, use the -0 option to both this command and "xargs". This will
2700 avoid the problem of "xargs" treating single filenames that contain
2701 whitespace as multiple filenames.
2702 See hg help files for a more versatile command.
2704 Returns 0 if a match is found, 1 otherwise.
2706 Options:
2708 -r,--rev <REV>
2710 search the repository as it is in REV
2711 -0, --print0
2713 end filenames with NUL, for use with xargs
2714 -f, --fullpath
2716 print complete paths from the filesystem root
2717 -I,--include <PATTERN[+]>
2719 include names matching the given patterns
2720 -X,--exclude <PATTERN[+]>
2722 exclude names matching the given patterns
2723 [+] marked option can be specified multiple times
2725 purge
2727 removes files not tracked by Mercurial:
2728 hg purge [OPTION]... [DIR]...
2730 Delete files not known to Mercurial. This is useful to test local and
2732 uncommitted changes in an otherwise-clean source tree.
2733 This means that purge will delete the following by default:
2735 • Unknown files: files marked with "?" by hg status
2737 • Empty directories: in fact Mercurial ignores directories unless they
2739 contain files under source control management
2740 But it will leave untouched:
2742 • Modified and unmodified tracked files
2744 • Ignored files (unless -i or --all is specified)
2746 • New files added to the repository (with hg add)
2748 The --files and --dirs options can be used to direct purge to delete
2750 only files, only directories, or both. If neither option is given, both
2751 will be deleted.
2752 If directories are given on the command line, only files in these di‐
2754 rectories are considered.
2755 Be careful with purge, as you could irreversibly delete some files you
2757 forgot to add to the repository. If you only want to print the list of
2758 files that this program would delete, use the --print option.
2759 Options:
2761 -a, --abort-on-err
2763 abort if an error occurs
2764 --all purge ignored files too
2766 -i, --ignored
2768 purge only ignored files
2769 --dirs purge empty directories
2771 --files
2773 purge files
2774 -p, --print
2776 print filenames instead of deleting them
2777 -0, --print0
2779 end filenames with NUL, for use with xargs (implies -p/--print)
2780 --confirm
2782 ask before permanently deleting files
2783 -I,--include <PATTERN[+]>
2785 include names matching the given patterns
2786 -X,--exclude <PATTERN[+]>
2788 exclude names matching the given patterns
2789 [+] marked option can be specified multiple times
2791 aliases: clean
2793 remove
2795 remove the specified files on the next commit:
2796 hg remove [OPTION]... FILE...
2798 Schedule the indicated files for removal from the current branch.
2800 This command schedules the files to be removed at the next commit. To
2802 undo a remove before that, see hg revert. To undo added files, see hg
2803 forget.
2804 -A/--after can be used to remove only files that have already been
2806 deleted, -f/--force can be used to force deletion, and -Af can be used
2807 to remove files from the next revision without deleting them from the
2808 working directory.
2809 The following table details the behavior of remove for different file
2811 states (columns) and option combinations (rows). The file states are
2812 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2813 status). The actions are Warn, Remove (from branch) and Delete (from
2814 disk):
2815 ┌──────────┬───┬────┬────┬───┐
2817 │opt/state │ A │ C │ M │ ! │
2818 ├──────────┼───┼────┼────┼───┤
2819 │none │ W │ RD │ W │ R │
2820 ├──────────┼───┼────┼────┼───┤
2821 │-f │ R │ RD │ RD │ R │
2822 ├──────────┼───┼────┼────┼───┤
2823 │-A │ W │ W │ W │ R │
2824 ├──────────┼───┼────┼────┼───┤
2825 │-Af │ R │ R │ R │ R │
2826 └──────────┴───┴────┴────┴───┘
2827 Note hg remove never deletes files in Added [A] state from the work‐
2829 ing directory, not even if --force is specified.
2830 Returns 0 on success, 1 if any warnings encountered.
2832 Options:
2834 -A, --after
2836 record delete for missing files
2837 -f, --force
2839 forget added files, delete modified files
2840 -S, --subrepos
2842 recurse into subrepositories
2843 -I,--include <PATTERN[+]>
2845 include names matching the given patterns
2846 -X,--exclude <PATTERN[+]>
2848 exclude names matching the given patterns
2849 -n, --dry-run
2851 do not perform actions, just print output
2852 [+] marked option can be specified multiple times
2854 aliases: rm
2856 rename
2858 rename files; equivalent of copy + remove:
2859 hg rename [OPTION]... SOURCE... DEST
2861 Mark dest as copies of sources; mark sources for deletion. If dest is a
2863 directory, copies are put in that directory. If dest is a file, there
2864 can only be one source.
2865 By default, this command copies the contents of files as they exist in
2867 the working directory. If invoked with -A/--after, the operation is
2868 recorded, but no copying is performed.
2869 To undo marking a destination file as renamed, use --forget. With that
2871 option, all given (positional) arguments are unmarked as renames. The
2872 destination file(s) will be left in place (still tracked). The source
2873 file(s) will not be restored. Note that hg rename --forget behaves the
2874 same way as hg copy --forget.
2875 This command takes effect with the next commit by default.
2877 Returns 0 on success, 1 if errors are encountered.
2879 Options:
2881 --forget
2883 unmark a destination file as renamed
2884 -A, --after
2886 record a rename that has already occurred
2887 --at-rev <REV>
2889 (un)mark renames in the given revision (EXPERIMENTAL)
2890 -f, --force
2892 forcibly move over an existing managed file
2893 -I,--include <PATTERN[+]>
2895 include names matching the given patterns
2896 -X,--exclude <PATTERN[+]>
2898 exclude names matching the given patterns
2899 -n, --dry-run
2901 do not perform actions, just print output
2902 [+] marked option can be specified multiple times
2904 aliases: move mv
2906 resolve
2908 redo merges or set/view the merge status of files:
2909 hg resolve [OPTION]... [FILE]...
2911 Merges with unresolved conflicts are often the result of non-interac‐
2913 tive merging using the internal:merge configuration setting, or a com‐
2914 mand-line merge tool like diff3. The resolve command is used to manage
2915 the files involved in a merge, after hg merge has been run, and before
2916 hg commit is run (i.e. the working directory must have two parents).
2917 See hg help merge-tools for information on configuring merge tools.
2918 The resolve command can be used in the following ways:
2920 • hg resolve [--re-merge] [--tool TOOL] FILE...: attempt to re-merge
2922 the specified files, discarding any previous merge attempts. Re-merg‐
2923 ing is not performed for files already marked as resolved. Use
2924 --all/-a to select all unresolved files. --tool can be used to spec‐
2925 ify the merge tool used for the given files. It overrides the HGMERGE
2926 environment variable and your configuration files. Previous file
2927 contents are saved with a .orig suffix.
2928 • hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
2930 having manually fixed-up the files). The default is to mark all unre‐
2931 solved files.
2932 • hg resolve -u [FILE]...: mark a file as unresolved. The default is to
2934 mark all resolved files.
2935 • hg resolve -l: list files which had or still have conflicts. In the
2937 printed list, U = unresolved and R = resolved. You can use set:unre‐
2938 solved() or set:resolved() to filter the list. See hg help filesets
2939 for details.
2940 Note Mercurial will not let you commit files with unresolved merge
2942 conflicts. You must use hg resolve -m ... before you can commit
2943 after a conflicting merge.
2944 Template:
2946 The following keywords are supported in addition to the common template
2948 keywords and functions. See also hg help templates.
2949 mergestatus
2951 String. Character denoting merge conflicts, U or R.
2952 path String. Repository-absolute path of the file.
2954 Returns 0 on success, 1 if any files fail a resolve attempt.
2956 Options:
2958 -a, --all
2960 select all unresolved files
2961 -l, --list
2963 list state of files needing merge
2964 -m, --mark
2966 mark files as resolved
2967 -u, --unmark
2969 mark files as unresolved
2970 -n, --no-status
2972 hide status prefix
2973 --re-merge
2975 re-merge files
2976 -t,--tool <TOOL>
2978 specify merge tool
2979 -I,--include <PATTERN[+]>
2981 include names matching the given patterns
2982 -X,--exclude <PATTERN[+]>
2984 exclude names matching the given patterns
2985 -T,--template <TEMPLATE>
2987 display with template
2988 [+] marked option can be specified multiple times
2990 revert
2992 restore files to their checkout state:
2993 hg revert [OPTION]... [-r REV] [NAME]...
2995 Note To check out earlier revisions, you should use hg update REV.
2997 To cancel an uncommitted merge (and lose your changes), use hg
2998 merge --abort.
2999 With no revision specified, revert the specified files or directories
3001 to the contents they had in the parent of the working directory. This
3002 restores the contents of files to an unmodified state and unschedules
3003 adds, removes, copies, and renames. If the working directory has two
3004 parents, you must explicitly specify a revision.
3005 Using the -r/--rev or -d/--date options, revert the given files or di‐
3007 rectories to their states as of a specific revision. Because revert
3008 does not change the working directory parents, this will cause these
3009 files to appear modified. This can be helpful to "back out" some or all
3010 of an earlier change. See hg backout for a related method.
3011 Modified files are saved with a .orig suffix before reverting. To dis‐
3013 able these backups, use --no-backup. It is possible to store the backup
3014 files in a custom directory relative to the root of the repository by
3015 setting the ui.origbackuppath configuration option.
3016 See hg help dates for a list of formats valid for -d/--date.
3018 See hg help backout for a way to reverse the effect of an earlier
3020 changeset.
3021 Returns 0 on success.
3023 Options:
3025 -a, --all
3027 revert all changes when no arguments given
3028 -d,--date <DATE>
3030 tipmost revision matching date
3031 -r,--rev <REV>
3033 revert to the specified revision
3034 -C, --no-backup
3036 do not save backup copies of files
3037 -i, --interactive
3039 interactively select the changes
3040 -I,--include <PATTERN[+]>
3042 include names matching the given patterns
3043 -X,--exclude <PATTERN[+]>
3045 exclude names matching the given patterns
3046 -n, --dry-run
3048 do not perform actions, just print output
3049 [+] marked option can be specified multiple times
3051 root
3053 print the root (top) of the current working directory:
3054 hg root
3056 Print the root directory of the current repository.
3058 Template:
3060 The following keywords are supported in addition to the common template
3062 keywords and functions. See also hg help templates.
3063 hgpath String. Path to the .hg directory.
3065 storepath
3067 String. Path to the directory holding versioned data.
3068 Returns 0 on success.
3070 Options:
3072 -T,--template <TEMPLATE>
3074 display with template
3075 shelve
3077 save and set aside changes from the working directory:
3078 hg shelve [OPTION]... [FILE]...
3080 Shelving takes files that "hg status" reports as not clean, saves the
3082 modifications to a bundle (a shelved change), and reverts the files so
3083 that their state in the working directory becomes clean.
3084 To restore these changes to the working directory, using "hg unshelve";
3086 this will work even if you switch to a different commit.
3087 When no files are specified, "hg shelve" saves all not-clean files. If
3089 specific files or directories are named, only changes to those files
3090 are shelved.
3091 In bare shelve (when no files are specified, without interactive, in‐
3093 clude and exclude option), shelving remembers information if the work‐
3094 ing directory was on newly created branch, in other words working di‐
3095 rectory was on different branch than its first parent. In this situa‐
3096 tion unshelving restores branch information to the working directory.
3097 Each shelved change has a name that makes it easier to find later. The
3099 name of a shelved change defaults to being based on the active book‐
3100 mark, or if there is no active bookmark, the current named branch. To
3101 specify a different name, use --name.
3102 To see a list of existing shelved changes, use the --list option. For
3104 each shelved change, this will print its name, age, and description;
3105 use --patch or --stat for more details.
3106 To delete specific shelved changes, use --delete. To delete all shelved
3108 changes, use --cleanup.
3109 Options:
3111 -A, --addremove
3113 mark new/missing files as added/removed before shelving
3114 -u, --unknown
3116 store unknown files in the shelve
3117 --cleanup
3119 delete all shelved changes
3120 --date <DATE>
3122 shelve with the specified commit date
3123 -d, --delete
3125 delete the named shelved change(s)
3126 -e, --edit
3128 invoke editor on commit messages
3129 -k, --keep
3131 shelve, but keep changes in the working directory
3132 -l, --list
3134 list current shelves
3135 -m,--message <TEXT>
3137 use text as shelve message
3138 -n,--name <NAME>
3140 use the given name for the shelved commit
3141 -p, --patch
3143 output patches for changes (provide the names of the shelved
3144 changes as positional arguments)
3145 -i, --interactive
3147 interactive mode
3148 --stat output diffstat-style summary of changes (provide the names of
3150 the shelved changes as positional arguments)
3151 -I,--include <PATTERN[+]>
3153 include names matching the given patterns
3154 -X,--exclude <PATTERN[+]>
3156 exclude names matching the given patterns
3157 [+] marked option can be specified multiple times
3159 status
3161 show changed files in the working directory:
3162 hg status [OPTION]... [FILE]...
3164 Show status of files in the repository. If names are given, only files
3166 that match are shown. Files that are clean or ignored or the source of
3167 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3168 -C/--copies or -A/--all are given. Unless options described with "show
3169 only ..." are given, the options -mardu are used.
3170 Option -q/--quiet hides untracked (unknown and ignored) files unless
3172 explicitly requested with -u/--unknown or -i/--ignored.
3173 Note hg status may appear to disagree with diff if permissions have
3175 changed or a merge has occurred. The standard diff format does
3176 not report permission changes and diff only reports changes rel‐
3177 ative to one merge parent.
3178 If one revision is given, it is used as the base revision. If two re‐
3180 visions are given, the differences between them are shown. The --change
3181 option can also be used as a shortcut to list the changed files of a
3182 revision from its first parent.
3183 The codes used to show the status of files are:
3185 M = modified
3187 A = added
3188 R = removed
3189 C = clean
3190 ! = missing (deleted by non-hg command, but still tracked)
3191 ? = not tracked
3192 I = ignored
3193 = origin of the previous file (with --copies)
3194 The -t/--terse option abbreviates the output by showing only the direc‐
3196 tory name if all the files in it share the same status. The option
3197 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3198 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3199 'unknown', 'i' for 'ignored' and 'c' for clean.
3200 It abbreviates only those statuses which are passed. Note that clean
3202 and ignored files are not displayed with '--terse ic' unless the
3203 -c/--clean and -i/--ignored options are also used.
3204 The -v/--verbose option shows information when the repository is in an
3206 unfinished merge, shelve, rebase state etc. You can have this behavior
3207 turned on by default by enabling the commands.status.verbose option.
3208 You can skip displaying some of these states by setting commands.sta‐
3210 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3211 'merge', 'rebase', or 'unshelve'.
3212 Template:
3214 The following keywords are supported in addition to the common template
3216 keywords and functions. See also hg help templates.
3217 path String. Repository-absolute path of the file.
3219 source String. Repository-absolute path of the file originated from.
3221 Available if --copies is specified.
3222 status String. Character denoting file's status.
3224 Examples:
3226 • show changes in the working directory relative to a changeset:
3228 hg status --rev 9353
3230 • show changes in the working directory relative to the current direc‐
3232 tory (see hg help patterns for more information):
3233 hg status re:
3235 • show all changes including copies in an existing changeset:
3237 hg status --copies --change 9353
3239 • get a NUL separated list of added files, suitable for xargs:
3241 hg status -an0
3243 • show more information about the repository status, abbreviating
3245 added, removed, modified, deleted, and untracked paths:
3246 hg status -v -t mardu
3248 Returns 0 on success.
3250 Options:
3252 -A, --all
3254 show status of all files
3255 -m, --modified
3257 show only modified files
3258 -a, --added
3260 show only added files
3261 -r, --removed
3263 show only removed files
3264 -d, --deleted
3266 show only missing files
3267 -c, --clean
3269 show only files without changes
3270 -u, --unknown
3272 show only unknown (not tracked) files
3273 -i, --ignored
3275 show only ignored files
3276 -n, --no-status
3278 hide status prefix
3279 -t,--terse <VALUE>
3281 show the terse output (EXPERIMENTAL) (default: nothing)
3282 -C, --copies
3284 show source of copied files (DEFAULT: ui.statuscopies)
3285 -0, --print0
3287 end filenames with NUL, for use with xargs
3288 --rev <REV[+]>
3290 show difference from revision
3291 --change <REV>
3293 list the changed files of a revision
3294 -I,--include <PATTERN[+]>
3296 include names matching the given patterns
3297 -X,--exclude <PATTERN[+]>
3299 exclude names matching the given patterns
3300 -S, --subrepos
3302 recurse into subrepositories
3303 -T,--template <TEMPLATE>
3305 display with template
3306 [+] marked option can be specified multiple times
3308 aliases: st
3310 summary
3312 summarize working directory state:
3313 hg summary [--remote]
3315 This generates a brief summary of the working directory state, includ‐
3317 ing parents, branch, commit status, phase and available updates.
3318 With the --remote option, this will check the default paths for incom‐
3320 ing and outgoing changes. This can be time-consuming.
3321 Returns 0 on success.
3323 Options:
3325 --remote
3327 check for push and pull
3328 aliases: sum
3330 unshelve
3332 restore a shelved change to the working directory:
3333 hg unshelve [OPTION]... [[-n] SHELVED]
3335 This command accepts an optional name of a shelved change to restore.
3337 If none is given, the most recent shelved change is used.
3338 If a shelved change is applied successfully, the bundle that contains
3340 the shelved changes is moved to a backup location (.hg/shelve-backup).
3341 Since you can restore a shelved change on top of an arbitrary commit,
3343 it is possible that unshelving will result in a conflict between your
3344 changes and the commits you are unshelving onto. If this occurs, you
3345 must resolve the conflict, then use --continue to complete the unshelve
3346 operation. (The bundle will not be moved until you successfully com‐
3347 plete the unshelve.)
3348 (Alternatively, you can use --abort to abandon an unshelve that causes
3350 a conflict. This reverts the unshelved changes, and leaves the bundle
3351 in place.)
3352 If bare shelved change (without interactive, include and exclude op‐
3354 tion) was done on newly created branch it would restore branch informa‐
3355 tion to the working directory.
3356 After a successful unshelve, the shelved changes are stored in a backup
3358 directory. Only the N most recent backups are kept. N defaults to 10
3359 but can be overridden using the shelve.maxbackups configuration option.
3360 Timestamp in seconds is used to decide order of backups. More than
3362 maxbackups backups are kept, if same timestamp prevents from deciding
3363 exact order of them, for safety.
3364 Selected changes can be unshelved with --interactive flag. The working
3366 directory is updated with the selected changes, and only the unselected
3367 changes remain shelved. Note: The whole shelve is applied to working
3368 directory first before running interactively. So, this will bring up
3369 all the conflicts between working directory and the shelve, irrespec‐
3370 tive of which changes will be unshelved.
3371 Options:
3373 -a, --abort
3375 abort an incomplete unshelve operation
3376 -c, --continue
3378 continue an incomplete unshelve operation
3379 -i, --interactive
3381 use interactive mode (EXPERIMENTAL)
3382 -k, --keep
3384 keep shelve after unshelving
3385 -n,--name <NAME>
3387 restore shelved change with given name
3388 -t,--tool <VALUE>
3390 specify merge tool
3391 --date <DATE>
3393 set date for temporary commits (DEPRECATED)
3394 update
3396 update working directory (or switch revisions):
3397 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3399 Update the repository's working directory to the specified changeset.
3401 If no changeset is specified, update to the tip of the current named
3402 branch and move the active bookmark (see hg help bookmarks).
3403 Update sets the working directory's parent revision to the specified
3405 changeset (see hg help parents).
3406 If the changeset is not a descendant or ancestor of the working direc‐
3408 tory's parent and there are uncommitted changes, the update is aborted.
3409 With the -c/--check option, the working directory is checked for uncom‐
3410 mitted changes; if none are found, the working directory is updated to
3411 the specified changeset.
3412 The -C/--clean, -c/--check, and -m/--merge options control what happens
3414 if the working directory contains uncommitted changes. At most of one
3415 of them can be specified.
3416 1. If no option is specified, and if the requested changeset is an an‐
3418 cestor or descendant of the working directory's parent, the uncom‐
3419 mitted changes are merged into the requested changeset and the
3420 merged result is left uncommitted. If the requested changeset is not
3421 an ancestor or descendant (that is, it is on another branch), the
3422 update is aborted and the uncommitted changes are preserved.
3423 2. With the -m/--merge option, the update is allowed even if the re‐
3425 quested changeset is not an ancestor or descendant of the working
3426 directory's parent.
3427 3. With the -c/--check option, the update is aborted and the uncommit‐
3429 ted changes are preserved.
3430 4. With the -C/--clean option, uncommitted changes are discarded and
3432 the working directory is updated to the requested changeset.
3433 To cancel an uncommitted merge (and lose your changes), use hg merge
3435 --abort.
3436 Use null as the changeset to remove the working directory (like hg
3438 clone -U).
3439 If you want to revert just one file to an older revision, use hg revert
3441 [-r REV] NAME.
3442 See hg help dates for a list of formats valid for -d/--date.
3444 Returns 0 on success, 1 if there are unresolved files.
3446 Options:
3448 -C, --clean
3450 discard uncommitted changes (no backup)
3451 -c, --check
3453 require clean working directory
3454 -m, --merge
3456 merge uncommitted changes
3457 -d,--date <DATE>
3459 tipmost revision matching date
3460 -r,--rev <REV>
3462 revision
3463 -t,--tool <TOOL>
3465 specify merge tool
3466 aliases: up checkout co
3468 Change import/export
3470 archive
3471 create an unversioned archive of a repository revision:
3472 hg archive [OPTION]... DEST
3474 By default, the revision used is the parent of the working directory;
3476 use -r/--rev to specify a different revision.
3477 The archive type is automatically detected based on file extension (to
3479 override, use -t/--type).
3480 Examples:
3482 • create a zip file containing the 1.0 release:
3484 hg archive -r 1.0 project-1.0.zip
3486 • create a tarball excluding .hg files:
3488 hg archive project.tar.gz -X ".hg*"
3490 Valid types are:
3492 files
3494 a directory full of files (default)
3496 tar
3498 tar archive, uncompressed
3500 tbz2
3502 tar archive, compressed using bzip2
3504 tgz
3506 tar archive, compressed using gzip
3508 txz
3510 tar archive, compressed using lzma (only in Python 3)
3512 uzip
3514 zip archive, uncompressed
3516 zip
3518 zip archive, compressed using deflate
3520 The exact name of the destination archive or directory is given using a
3522 format string; see hg help export for details.
3523 Each member added to an archive file has a directory prefix prepended.
3525 Use -p/--prefix to specify a format string for the prefix. The default
3526 is the basename of the archive, with suffixes removed.
3527 Returns 0 on success.
3529 Options:
3531 --no-decode
3533 do not pass files through decoders
3534 -p,--prefix <PREFIX>
3536 directory prefix for files in archive
3537 -r,--rev <REV>
3539 revision to distribute
3540 -t,--type <TYPE>
3542 type of distribution to create
3543 -S, --subrepos
3545 recurse into subrepositories
3546 -I,--include <PATTERN[+]>
3548 include names matching the given patterns
3549 -X,--exclude <PATTERN[+]>
3551 exclude names matching the given patterns
3552 [+] marked option can be specified multiple times
3554 bundle
3556 create a bundle file:
3557 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]...
3559 Generate a bundle file containing data to be transferred to another
3561 repository.
3562 To create a bundle containing all changesets, use -a/--all (or --base
3564 null). Otherwise, hg assumes the destination will have all the nodes
3565 you specify with --base parameters. Otherwise, hg will assume the
3566 repository has all the nodes in destination, or default-push/default if
3567 no destination is specified, where destination is the repositories you
3568 provide through DEST option.
3569 You can change bundle format with the -t/--type option. See hg help
3571 bundlespec for documentation on this format. By default, the most ap‐
3572 propriate format is used and compression defaults to bzip2.
3573 The bundle file can then be transferred using conventional means and
3575 applied to another repository with the unbundle or pull command. This
3576 is useful when direct push and pull are not available or when exporting
3577 an entire repository is undesirable.
3578 Applying bundles preserves all changeset contents including permis‐
3580 sions, copy/rename information, and revision history.
3581 Returns 0 on success, 1 if no changes found.
3583 Options:
3585 --exact
3587 compute the base from the revision specified
3588 -f, --force
3590 run even when the destination is unrelated
3591 -r,--rev <REV[+]>
3593 a changeset intended to be added to the destination
3594 -b,--branch <BRANCH[+]>
3596 a specific branch you would like to bundle
3597 --base <REV[+]>
3599 a base changeset assumed to be available at the destination
3600 -a, --all
3602 bundle all changesets in the repository
3603 -t,--type <TYPE>
3605 bundle compression type to use (default: bzip2)
3606 -e,--ssh <CMD>
3608 specify ssh command to use
3609 --remotecmd <CMD>
3611 specify hg command to run on the remote side
3612 --insecure
3614 do not verify server certificate (ignoring web.cacerts config)
3615 [+] marked option can be specified multiple times
3617 export
3619 dump the header and diffs for one or more changesets:
3620 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
3622 Print the changeset header and diffs for one or more revisions. If no
3624 revision is given, the parent of the working directory is used.
3625 The information shown in the changeset header is: author, date, branch
3627 name (if non-default), changeset hash, parent(s) and commit comment.
3628 Note hg export may generate unexpected diff output for merge change‐
3630 sets, as it will compare the merge changeset against its first
3631 parent only.
3632 Output may be to a file, in which case the name of the file is given
3634 using a template string. See hg help templates. In addition to the com‐
3635 mon template keywords, the following formatting rules are supported:
3636 %%
3638 literal "%" character
3640 %H
3642 changeset hash (40 hexadecimal digits)
3644 %N
3646 number of patches being generated
3648 %R
3650 changeset revision number
3652 %b
3654 basename of the exporting repository
3656 %h
3658 short-form changeset hash (12 hexadecimal digits)
3660 %m
3662 first line of the commit message (only alphanumeric characters)
3664 %n
3666 zero-padded sequence number, starting at 1
3668 %r
3670 zero-padded changeset revision number
3672 \
3674 literal "" character
3676 Without the -a/--text option, export will avoid generating diffs of
3678 files it detects as binary. With -a, export will generate a diff any‐
3679 way, probably with undesirable results.
3680 With -B/--bookmark changesets reachable by the given bookmark are se‐
3682 lected.
3683 Use the -g/--git option to generate diffs in the git extended diff for‐
3685 mat. See hg help diffs for more information.
3686 With the --switch-parent option, the diff will be against the second
3688 parent. It can be useful to review a merge.
3689 Template:
3691 The following keywords are supported in addition to the common template
3693 keywords and functions. See also hg help templates.
3694 diff String. Diff content.
3696 parents
3698 List of strings. Parent nodes of the changeset.
3699 Examples:
3701 • use export and import to transplant a bugfix to the current branch:
3703 hg export -r 9353 | hg import -
3705 • export all the changesets between two revisions to a file with rename
3707 information:
3708 hg export --git -r 123:150 > changes.txt
3710 • split outgoing changes into a series of patches with descriptive
3712 names:
3713 hg export -r "outgoing()" -o "%n-%m.patch"
3715 Returns 0 on success.
3717 Options:
3719 -B,--bookmark <BOOKMARK>
3721 export changes only reachable by given bookmark
3722 -o,--output <FORMAT>
3724 print output to file with formatted name
3725 --switch-parent
3727 diff against the second parent
3728 -r,--rev <REV[+]>
3730 revisions to export
3731 -a, --text
3733 treat all files as text
3734 -g, --git
3736 use git extended diff format (DEFAULT: diff.git)
3737 --binary
3739 generate binary diffs in git mode (default)
3740 --nodates
3742 omit dates from diff headers
3743 -T,--template <TEMPLATE>
3745 display with template
3746 [+] marked option can be specified multiple times
3748 import
3750 import an ordered set of patches:
3751 hg import [OPTION]... PATCH...
3753 Import a list of patches and commit them individually (unless --no-com‐
3755 mit is specified).
3756 To read a patch from standard input (stdin), use "-" as the patch name.
3758 If a URL is specified, the patch will be downloaded from there.
3759 Import first applies changes to the working directory (unless --bypass
3761 is specified), import will abort if there are outstanding changes.
3762 Use --bypass to apply and commit patches directly to the repository,
3764 without affecting the working directory. Without --exact, patches will
3765 be applied on top of the working directory parent revision.
3766 You can import a patch straight from a mail message. Even patches as
3768 attachments work (to use the body part, it must have type text/plain or
3769 text/x-patch). From and Subject headers of email message are used as
3770 default committer and commit message. All text/plain body parts before
3771 first diff are added to the commit message.
3772 If the imported patch was generated by hg export, user and description
3774 from patch override values from message headers and body. Values given
3775 on command line with -m/--message and -u/--user override these.
3776 If --exact is specified, import will set the working directory to the
3778 parent of each patch before applying it, and will abort if the result‐
3779 ing changeset has a different ID than the one recorded in the patch.
3780 This will guard against various ways that portable patch formats and
3781 mail systems might fail to transfer Mercurial data or metadata. See hg
3782 bundle for lossless transmission.
3783 Use --partial to ensure a changeset will be created from the patch even
3785 if some hunks fail to apply. Hunks that fail to apply will be written
3786 to a <target-file>.rej file. Conflicts can then be resolved by hand be‐
3787 fore hg commit --amend is run to update the created changeset. This
3788 flag exists to let people import patches that partially apply without
3789 losing the associated metadata (author, date, description, ...).
3790 Note When no hunks apply cleanly, hg import --partial will create an
3792 empty changeset, importing only the patch metadata.
3793 With -s/--similarity, hg will attempt to discover renames and copies in
3795 the patch in the same way as hg addremove.
3796 It is possible to use external patch programs to perform the patch by
3798 setting the ui.patch configuration option. For the default internal
3799 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
3800 fig for more information about configuration files and how to use these
3801 options.
3802 See hg help dates for a list of formats valid for -d/--date.
3804 Examples:
3806 • import a traditional patch from a website and detect renames:
3808 hg import -s 80 http://example.com/bugfix.patch
3810 • import a changeset from an hgweb server:
3812 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
3814 • import all the patches in an Unix-style mbox:
3816 hg import incoming-patches.mbox
3818 • import patches from stdin:
3820 hg import -
3822 • attempt to exactly restore an exported changeset (not always possi‐
3824 ble):
3825 hg import --exact proposed-fix.patch
3827 • use an external tool to apply a patch which is too fuzzy for the de‐
3829 fault internal tool.
3830 hg import --config ui.patch="patch --merge" fuzzy.patch
3832 • change the default fuzzing from 2 to a less strict 7
3834 hg import --config ui.fuzz=7 fuzz.patch
3836 Returns 0 on success, 1 on partial success (see --partial).
3838 Options:
3840 -p,--strip <NUM>
3842 directory strip option for patch. This has the same meaning as
3843 the corresponding patch option (default: 1)
3844 -b,--base <PATH>
3846 base path (DEPRECATED)
3847 --secret
3849 use the secret phase for committing
3850 -e, --edit
3852 invoke editor on commit messages
3853 -f, --force
3855 skip check for outstanding uncommitted changes (DEPRECATED)
3856 --no-commit
3858 don't commit, just update the working directory
3859 --bypass
3861 apply patch without touching the working directory
3862 --partial
3864 commit even if some hunks fail
3865 --exact
3867 abort if patch would apply lossily
3868 --prefix <DIR>
3870 apply patch to subdirectory
3871 --import-branch
3873 use any branch information in patch (implied by --exact)
3874 -m,--message <TEXT>
3876 use text as commit message
3877 -l,--logfile <FILE>
3879 read commit message from file
3880 -d,--date <DATE>
3882 record the specified date as commit date
3883 -u,--user <USER>
3885 record the specified user as committer
3886 -s,--similarity <SIMILARITY>
3888 guess renamed files by similarity (0<=s<=100)
3889 aliases: patch
3891 unbundle
3893 apply one or more bundle files:
3894 hg unbundle [-u] FILE...
3896 Apply one or more bundle files generated by hg bundle.
3898 Returns 0 on success, 1 if an update has unresolved files.
3900 Options:
3902 -u, --update
3904 update to new branch head if changesets were unbundled
3905 Repository maintenance
3907 manifest
3908 output the current or given revision of the project manifest:
3909 hg manifest [-r REV]
3911 Print a list of version controlled files for the given revision. If no
3913 revision is given, the first parent of the working directory is used,
3914 or the null revision if no revision is checked out.
3915 With -v, print file permissions, symlink and executable bits. With
3917 --debug, print file revision hashes.
3918 If option --all is specified, the list of all files from all revisions
3920 is printed. This includes deleted and renamed files.
3921 Returns 0 on success.
3923 Options:
3925 -r,--rev <REV>
3927 revision to display
3928 --all list files from all revisions
3930 -T,--template <TEMPLATE>
3932 display with template
3933 recover
3935 roll back an interrupted transaction:
3936 hg recover
3938 Recover from an interrupted commit or pull.
3940 This command tries to fix the repository status after an interrupted
3942 operation. It should only be necessary when Mercurial suggests it.
3943 Returns 0 if successful, 1 if nothing to recover or verify fails.
3945 Options:
3947 --verify
3949 run hg verify after successful recover
3950 rollback
3952 roll back the last transaction (DANGEROUS) (DEPRECATED):
3953 hg rollback
3955 Please use hg commit --amend instead of rollback to correct mistakes in
3957 the last commit.
3958 This command should be used with care. There is only one level of roll‐
3960 back, and there is no way to undo a rollback. It will also restore the
3961 dirstate at the time of the last transaction, losing any dirstate
3962 changes since that time. This command does not alter the working direc‐
3963 tory.
3964 Transactions are used to encapsulate the effects of all commands that
3966 create new changesets or propagate existing changesets into a reposi‐
3967 tory.
3968 For example, the following commands are transactional, and their ef‐
3970 fects can be rolled back:
3971 • commit
3973 • import
3975 • pull
3977 • push (with this repository as the destination)
3979 • unbundle
3981 To avoid permanent data loss, rollback will refuse to rollback a commit
3983 transaction if it isn't checked out. Use --force to override this pro‐
3984 tection.
3985 The rollback command can be entirely disabled by setting the ui.roll‐
3987 back configuration setting to false. If you're here because you want to
3988 use rollback and it's disabled, you can re-enable the command by set‐
3989 ting ui.rollback to true.
3990 This command is not intended for use on public repositories. Once
3992 changes are visible for pull by other users, rolling a transaction back
3993 locally is ineffective (someone else may already have pulled the
3994 changes). Furthermore, a race is possible with readers of the reposi‐
3995 tory; for example an in-progress pull from the repository may fail if a
3996 rollback is performed.
3997 Returns 0 on success, 1 if no rollback data is available.
3999 Options:
4001 -n, --dry-run
4003 do not perform actions, just print output
4004 -f, --force
4006 ignore safety measures
4007 verify
4009 verify the integrity of the repository:
4010 hg verify
4012 Verify the integrity of the current repository.
4014 This will perform an extensive check of the repository's integrity,
4016 validating the hashes and checksums of each entry in the changelog,
4017 manifest, and tracked files, as well as the integrity of their
4018 crosslinks and indices.
4019 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
4021 information about recovery from corruption of the repository.
4022 Returns 0 on success, 1 if errors are encountered.
4024 Options:
4026 --full perform more checks (EXPERIMENTAL)
4028 Help
4030 config
4031 show combined config settings from all hgrc files:
4032 hg config [-u] [NAME]...
4034 With no arguments, print names and values of all config items.
4036 With one argument of the form section.name, print just the value of
4038 that config item.
4039 With multiple arguments, print names and values of all config items
4041 with matching section names or section.names.
4042 With --edit, start an editor on the user-level config file. With
4044 --global, edit the system-wide config file. With --local, edit the
4045 repository-level config file.
4046 With --source, the source (filename and line number) is printed for
4048 each config item.
4049 See hg help config for more information about config files.
4051 --non-shared flag is used to edit .hg/hgrc-not-shared config file.
4053 This file is not shared across shares when in share-safe mode.
4054 Template:
4056 The following keywords are supported. See also hg help templates.
4058 name String. Config name.
4060 source String. Filename and line number where the item is defined.
4062 value String. Config value.
4064 The --shared flag can be used to edit the config file of shared source
4066 repository. It only works when you have shared using the experimental
4067 share safe feature.
4068 Returns 0 on success, 1 if NAME does not exist.
4070 Options:
4072 -u, --untrusted
4074 show untrusted configuration options
4075 --exp-all-known
4077 show all known config option (EXPERIMENTAL)
4078 -e, --edit
4080 edit user config
4081 -l, --local
4083 edit repository config
4084 --source
4086 show source of configuration value
4087 --shared
4089 edit shared source repository config (EXPERIMENTAL)
4090 --non-shared
4092 edit non shared config (EXPERIMENTAL)
4093 -g, --global
4095 edit global config
4096 -T,--template <TEMPLATE>
4098 display with template
4099 aliases: showconfig debugconfig
4101 help
4103 show help for a given topic or a help overview:
4104 hg help [-eck] [-s PLATFORM] [TOPIC]
4106 With no arguments, print a list of commands with short help messages.
4108 Given a topic, extension, or command name, print help for that topic.
4110 Returns 0 if successful.
4112 Options:
4114 -e, --extension
4116 show only help for extensions
4117 -c, --command
4119 show only help for commands
4120 -k, --keyword
4122 show topics matching keyword
4123 -s,--system <PLATFORM[+]>
4125 show help for specific platform(s)
4126 [+] marked option can be specified multiple times
4128 version
4130 output version and copyright information:
4131 hg version
4133 Template:
4135 The following keywords are supported. See also hg help templates.
4137 extensions
4139 List of extensions.
4140 ver String. Version number.
4142 And each entry of {extensions} provides the following sub-keywords in
4144 addition to {ver}.
4145 bundled
4147 Boolean. True if included in the release.
4148 name String. Extension name.
4150 Options:
4152 -T,--template <TEMPLATE>
4154 display with template
4155 Uncategorized commands
4158 Mercurial supports generating standalone "bundle" files that hold
4159 repository data. These "bundles" are typically saved locally and used
4160 later or exchanged between different repositories, possibly on differ‐
4161 ent machines. Example commands using bundles are hg bundle and hg un‐
4162 bundle.
4163 Generation of bundle files is controlled by a "bundle specification"
4165 ("bundlespec") string. This string tells the bundle generation process
4166 how to create the bundle.
4167 A "bundlespec" string is composed of the following elements:
4169 type A string denoting the bundle format to use.
4171 compression
4173 Denotes the compression engine to use compressing the raw bundle
4174 data.
4175 parameters
4177 Arbitrary key-value parameters to further control bundle genera‐
4178 tion.
4179 A "bundlespec" string has the following formats:
4181 <type> The literal bundle format string is used.
4183 <compression>-<type>
4185 The compression engine and format are delimited by a hyphen (-).
4186 Optional parameters follow the <type>. Parameters are URI escaped
4188 key=value pairs. Each pair is delimited by a semicolon (;). The first
4189 parameter begins after a ; immediately following the <type> value.
4190 Available Types
4192 The following bundle <type> strings are available:
4193 v1 Produces a legacy "changegroup" version 1 bundle.
4195 This format is compatible with nearly all Mercurial clients be‐
4197 cause it is the oldest. However, it has some limitations, which
4198 is why it is no longer the default for new repositories.
4199 v1 bundles can be used with modern repositories using the "gen‐
4201 eraldelta" storage format. However, it may take longer to pro‐
4202 duce the bundle and the resulting bundle may be significantly
4203 larger than a v2 bundle.
4204 v1 bundles can only use the gzip, bzip2, and none compression
4206 formats.
4207 v2 Produces a version 2 bundle.
4209 Version 2 bundles are an extensible format that can store addi‐
4211 tional repository data (such as bookmarks and phases informa‐
4212 tion) and they can store data more efficiently, resulting in
4213 smaller bundles.
4214 Version 2 bundles can also use modern compression engines, such
4216 as zstd, making them faster to compress and often smaller.
4217 Available Compression Engines
4219 The following bundle <compression> engines can be used:
4220 bzip2
4222 An algorithm that produces smaller bundles than gzip.
4224 All Mercurial clients should support this format.
4226 This engine will likely produce smaller bundles than gzip but
4228 will be significantly slower, both during compression and decom‐
4229 pression.
4230 If available, the zstd engine can yield similar or better com‐
4232 pression at much higher speeds.
4233 gzip
4235 zlib compression using the DEFLATE algorithm.
4237 All Mercurial clients should support this format. The compres‐
4239 sion algorithm strikes a reasonable balance between compression
4240 ratio and size.
4241 none
4243 No compression is performed.
4245 Use this compression engine to explicitly disable compression.
4247 Available Options
4249 The following options exist:
4250 changegroup
4252 Include the changegroup data in the bundle (default to True).
4253 cg.version
4255 Select the version of the changegroup to use. Available options
4256 are : 01, 02 or 03. By default it will be automatically selected
4257 according to the current repository format.
4258 obsolescence
4260 Include obsolescence-markers relevant to the bundled changesets.
4261 phases Include phase information relevant to the bundled changesets.
4263 revbranchcache
4265 Include the "tags-fnodes" cache inside the bundle.
4266 tagsfnodescache
4268 Include the "tags-fnodes" cache inside the bundle.
4269 Examples
4271 v2
4272 Produce a v2 bundle using default options, including compres‐
4274 sion.
4275 none-v1
4277 Produce a v1 bundle with no compression.
4279 zstd-v2
4281 Produce a v2 bundle with zstandard compression using default
4283 settings.
4284 zstd-v1
4286 This errors because zstd is not supported for v1 types.
4288
4290 Mercurial colorizes output from several commands.
4291 For example, the diff command shows additions in green and deletions in
4293 red, while the status command shows modified files in magenta. Many
4294 other commands have analogous colors. It is possible to customize these
4295 colors.
4296 To enable color (default) whenever possible use:
4298 [ui]
4300 color = yes
4301 To disable color use:
4303 [ui]
4305 color = no
4306 See hg help config.ui.color for details.
4308 The default pager on Windows does not support color, so enabling the
4310 pager will effectively disable color. See hg help config.ui.paginate
4311 to disable the pager. Alternately, MSYS and Cygwin shells provide less
4312 as a pager, which can be configured to support ANSI color mode. Win‐
4313 dows 10 natively supports ANSI color mode.
4314 Mode
4316 Mercurial can use various systems to display color. The supported modes
4317 are ansi, win32, and terminfo. See hg help config.color for details
4318 about how to control the mode.
4319 Effects
4321 Other effects in addition to color, like bold and underlined text, are
4322 also available. By default, the terminfo database is used to find the
4323 terminal codes used to change color and effect. If terminfo is not
4324 available, then effects are rendered with the ECMA-48 SGR control func‐
4325 tion (aka ANSI escape codes).
4326 The available effects in terminfo mode are 'blink', 'bold', 'dim', 'in‐
4328 verse', 'invisible', 'italic', 'standout', and 'underline'; in ECMA-48
4329 mode, the options are 'bold', 'inverse', 'italic', and 'underline'.
4330 How each is rendered depends on the terminal emulator. Some may not be
4331 available for a given terminal type, and will be silently ignored.
4332 If the terminfo entry for your terminal is missing codes for an effect
4334 or has the wrong codes, you can add or override those codes in your
4335 configuration:
4336 [color]
4338 terminfo.dim = \E[2m
4339 where 'E' is substituted with an escape character.
4341 Labels
4343 Text receives color effects depending on the labels that it has. Many
4344 default Mercurial commands emit labelled text. You can also define your
4345 own labels in templates using the label function, see hg help templates
4346 . A single portion of text may have more than one label. In that case,
4347 effects given to the last label will override any other effects. This
4348 includes the special "none" effect, which nullifies other effects.
4349 Labels are normally invisible. In order to see these labels and their
4351 position in the text, use the global --color=debug option. The same an‐
4352 chor text may be associated to multiple labels, e.g.
4353 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
4355 The following are the default effects for some default labels. Default
4357 effects may be overridden from your configuration file:
4358 [color]
4360 status.modified = blue bold underline red_background
4361 status.added = green bold
4362 status.removed = red bold blue_background
4363 status.deleted = cyan bold underline
4364 status.unknown = magenta bold underline
4365 status.ignored = black bold
4366 # 'none' turns off all effects
4368 status.clean = none
4369 status.copied = none
4370 qseries.applied = blue bold underline
4372 qseries.unapplied = black bold
4373 qseries.missing = red bold
4374 diff.diffline = bold
4376 diff.extended = cyan bold
4377 diff.file_a = red bold
4378 diff.file_b = green bold
4379 diff.hunk = magenta
4380 diff.deleted = red
4381 diff.inserted = green
4382 diff.changed = white
4383 diff.tab =
4384 diff.trailingwhitespace = bold red_background
4385 # Blank so it inherits the style of the surrounding label
4387 changeset.public =
4388 changeset.draft =
4389 changeset.secret =
4390 resolve.unresolved = red bold
4392 resolve.resolved = green bold
4393 bookmarks.active = green
4395 branches.active = none
4397 branches.closed = black bold
4398 branches.current = green
4399 branches.inactive = none
4400 tags.normal = green
4402 tags.local = black bold
4403 rebase.rebased = blue
4405 rebase.remaining = red bold
4406 shelve.age = cyan
4408 shelve.newest = green bold
4409 shelve.name = blue bold
4410 histedit.remaining = red bold
4412 Custom colors
4414 Because there are only eight standard colors, Mercurial allows you to
4415 define color names for other color slots which might be available for
4416 your terminal type, assuming terminfo mode. For instance:
4417 color.brightblue = 12
4419 color.pink = 207
4420 color.orange = 202
4421 to set 'brightblue' to color slot 12 (useful for 16 color terminals
4423 that have brighter colors defined in the upper eight) and, 'pink' and
4424 'orange' to colors in 256-color xterm's default color cube. These de‐
4425 fined colors may then be used as any of the pre-defined eight, includ‐
4426 ing appending '_background' to set the background to that color.
4427
4429 Some commands allow the user to specify a date, e.g.:
4430 • backout, commit, import, tag: Specify the commit date.
4432 • log, revert, update: Select revision(s) by date.
4434 Many date formats are valid. Here are some examples:
4436 • Wed Dec 6 13:18:29 2006 (local timezone assumed)
4438 • Dec 6 13:18 -0600 (year assumed, time offset provided)
4440 • Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
4442 • Dec 6 (midnight)
4444 • 13:18 (today assumed)
4446 • 3:39 (3:39AM assumed)
4448 • 3:39pm (15:39)
4450 • 2006-12-06 13:18:29 (ISO 8601 format)
4452 • 2006-12-6 13:18
4454 • 2006-12-6
4456 • 12-6
4458 • 12/6
4460 • 12/6/6 (Dec 6 2006)
4462 • today (midnight)
4464 • yesterday (midnight)
4466 • now - right now
4468 Lastly, there is Mercurial's internal format:
4470 • 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
4472 This is the internal representation format for dates. The first number
4474 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
4475 second is the offset of the local timezone, in seconds west of UTC
4476 (negative if the timezone is east of UTC).
4477 The log command also accepts date ranges:
4479 • <DATE - at or before a given date/time
4481 • >DATE - on or after a given date/time
4483 • DATE to DATE - a date range, inclusive
4485 • -DAYS - within a given number of days from today
4487
4489 Mercurial evolves over time, some features, options, commands may be
4490 replaced by better and more secure alternatives. This topic will help
4491 you migrating your existing usage and/or configuration to newer fea‐
4492 tures.
4493 Commands
4495 The following commands are still available but their use are not recom‐
4496 mended:
4497 locate
4499 This command has been replaced by hg files.
4501 parents
4503 This command can be replaced by hg summary or hg log with appropriate
4505 revsets. See hg help revsets for more information.
4506 tip
4508 The recommended alternative is hg heads.
4510 Options
4512 web.allowpull
4513 Renamed to allow-pull.
4515 web.allow_push
4517 Renamed to allow-push.
4519
4521 Mercurial's default format for showing changes between two versions of
4522 a file is compatible with the unified format of GNU diff, which can be
4523 used by GNU patch and many other standard tools.
4524 While this standard format is often enough, it does not encode the fol‐
4526 lowing information:
4527 • executable status and other permission bits
4529 • copy or rename information
4531 • changes in binary files
4533 • creation or deletion of empty files
4535 Mercurial also supports the extended diff format from the git VCS which
4537 addresses these limitations. The git diff format is not produced by de‐
4538 fault because a few widespread tools still do not understand this for‐
4539 mat.
4540 This means that when generating diffs from a Mercurial repository (e.g.
4542 with hg export), you should be careful about things like file copies
4543 and renames or other things mentioned above, because when applying a
4544 standard diff to a different repository, this extra information is
4545 lost. Mercurial's internal operations (like push and pull) are not af‐
4546 fected by this, because they use an internal binary format for communi‐
4547 cating changes.
4548 To make Mercurial produce the git extended diff format, use the --git
4550 option available for many commands, or set 'git = True' in the [diff]
4551 section of your configuration file. You do not need to set this option
4552 when importing diffs in this format or using them in the mq extension.
4553
4555 HG Path to the 'hg' executable, automatically passed when running
4556 hooks, extensions or external tools. If unset or empty, this is
4557 the hg executable's name if it's frozen, or an executable named
4558 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
4559 on Windows) is searched.
4560 HGEDITOR
4562 This is the name of the editor to run when committing. See EDI‐
4563 TOR.
4564 (deprecated, see hg help config.ui.editor)
4566 HGENCODING
4568 This overrides the default locale setting detected by Mercurial.
4569 This setting is used to convert data including usernames,
4570 changeset descriptions, tag names, and branches. This setting
4571 can be overridden with the --encoding command-line option.
4572 HGENCODINGMODE
4574 This sets Mercurial's behavior for handling unknown characters
4575 while transcoding user input. The default is "strict", which
4576 causes Mercurial to abort if it can't map a character. Other
4577 settings include "replace", which replaces unknown characters,
4578 and "ignore", which drops them. This setting can be overridden
4579 with the --encodingmode command-line option.
4580 HGENCODINGAMBIGUOUS
4582 This sets Mercurial's behavior for handling characters with "am‐
4583 biguous" widths like accented Latin characters with East Asian
4584 fonts. By default, Mercurial assumes ambiguous characters are
4585 narrow, set this variable to "wide" if such characters cause
4586 formatting problems.
4587 HGMERGE
4589 An executable to use for resolving merge conflicts. The program
4590 will be executed with three arguments: local file, remote file,
4591 ancestor file.
4592 (deprecated, see hg help config.ui.merge)
4594 HGRCPATH
4596 A list of files or directories to search for configuration
4597 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
4598 PATH is not set, platform default search path is used. If empty,
4599 only the .hg/hgrc from the current repository is read.
4600 For each element in HGRCPATH:
4602 • if it's a directory, all files ending with .rc are added
4604 • otherwise, the file itself will be added
4606 HGRCSKIPREPO
4608 When set, the .hg/hgrc from repositories are not read.
4609 HGPLAIN
4611 When set, this disables any configuration settings that might
4612 change Mercurial's default output. This includes encoding, de‐
4613 faults, verbose mode, debug mode, quiet mode, tracebacks, and
4614 localization. This can be useful when scripting against Mercu‐
4615 rial in the face of existing user configuration.
4616 In addition to the features disabled by HGPLAIN=, the following
4618 values can be specified to adjust behavior:
4619 +strictflags
4621 Restrict parsing of command line flags.
4623 Equivalent options set via command line flags or environment
4625 variables are not overridden.
4626 See hg help scripting for details.
4628 HGPLAINEXCEPT
4630 This is a comma-separated list of features to preserve when HG‐
4631 PLAIN is enabled. Currently the following values are supported:
4632 alias
4634 Don't remove aliases.
4636 color
4638 Don't disable colored output.
4640 i18n
4642 Preserve internationalization.
4644 revsetalias
4646 Don't remove revset aliases.
4648 templatealias
4650 Don't remove template aliases.
4652 progress
4654 Don't hide progress output.
4656 Setting HGPLAINEXCEPT to anything (even an empty string) will
4658 enable plain mode.
4659 HGUSER This is the string used as the author of a commit. If not set,
4661 available values will be considered in this order:
4662 • HGUSER (deprecated)
4664 • configuration files from the HGRCPATH
4666 • EMAIL
4668 • interactive prompt
4670 • LOGNAME (with @hostname appended)
4672 (deprecated, see hg help config.ui.username)
4674 EMAIL May be used as the author of a commit; see HGUSER.
4676 LOGNAME
4678 May be used as the author of a commit; see HGUSER.
4679 VISUAL This is the name of the editor to use when committing. See EDI‐
4681 TOR.
4682 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
4684 user to modify, for example when writing commit messages. The
4685 editor it uses is determined by looking at the environment vari‐
4686 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
4687 non-empty one is chosen. If all of them are empty, the editor
4688 defaults to 'vi'.
4689 PYTHONPATH
4691 This is used by Python to find imported modules and may need to
4692 be set appropriately if this Mercurial is not installed sys‐
4693 tem-wide.
4694
4696 Obsolescence markers make it possible to mark changesets that have been
4697 deleted or superseded in a new version of the changeset.
4698 Unlike the previous way of handling such changes, by stripping the old
4700 changesets from the repository, obsolescence markers can be propagated
4701 between repositories. This allows for a safe and simple way of exchang‐
4702 ing mutable history and altering it after the fact. Changeset phases
4703 are respected, such that only draft and secret changesets can be al‐
4704 tered (see hg help phases for details).
4705 Obsolescence is tracked using "obsolescence markers", a piece of meta‐
4707 data tracking which changesets have been made obsolete, potential suc‐
4708 cessors for a given changeset, the moment the changeset was marked as
4709 obsolete, and the user who performed the rewriting operation. The mark‐
4710 ers are stored separately from standard changeset data can be exchanged
4711 without any of the precursor changesets, preventing unnecessary ex‐
4712 change of obsolescence data.
4713 The complete set of obsolescence markers describes a history of change‐
4715 set modifications that is orthogonal to the repository history of file
4716 modifications. This changeset history allows for detection and auto‐
4717 matic resolution of edge cases arising from multiple users rewriting
4718 the same part of history concurrently.
4719 Current feature status
4721 This feature is still in development.
4722 Instability
4724 Rewriting changesets might introduce instability.
4725 There are two main kinds of instability: orphaning and diverging.
4727 Orphans are changesets left behind when their ancestors are rewritten.
4729 Divergence has two variants:
4730 • Content-divergence occurs when independent rewrites of the same
4732 changesets lead to different results.
4733 • Phase-divergence occurs when the old (obsolete) version of a change‐
4735 set becomes public.
4736 It is possible to prevent local creation of orphans by using the fol‐
4738 lowing config:
4739 [experimental]
4741 evolution.createmarkers = true
4742 evolution.exchange = true
4743 You can also enable that option explicitly:
4745 [experimental]
4747 evolution.createmarkers = true
4748 evolution.exchange = true
4749 evolution.allowunstable = true
4750
4752 Mercurial has the ability to add new features through the use of exten‐
4753 sions. Extensions may add new commands, add options to existing com‐
4754 mands, change the default behavior of commands, or implement hooks.
4755 To enable the "foo" extension, either shipped with Mercurial or in the
4757 Python search path, create an entry for it in your configuration file,
4758 like this:
4759 [extensions]
4761 foo =
4762 You may also specify the full path to an extension:
4764 [extensions]
4766 myfeature = ~/.hgext/myfeature.py
4767 See hg help config for more information on configuration files.
4769 Extensions are not loaded by default for a variety of reasons: they can
4771 increase startup overhead; they may be meant for advanced usage only;
4772 they may provide potentially dangerous abilities (such as letting you
4773 destroy or modify history); they might not be ready for prime time; or
4774 they may alter some usual behaviors of stock Mercurial. It is thus up
4775 to the user to activate extensions as needed.
4776 To explicitly disable an extension enabled in a configuration file of
4778 broader scope, prepend its path with !:
4779 [extensions]
4781 # disabling extension bar residing in /path/to/extension/bar.py
4782 bar = !/path/to/extension/bar.py
4783 # ditto, but no path was supplied for extension baz
4784 baz = !
4785 disabled extensions:
4787 acl hooks for controlling repository access
4789 blackbox
4791 log repository events to a blackbox for debugging
4792 bugzilla
4794 hooks for integrating with the Bugzilla bug tracker
4795 censor erase file content at a given revision
4797 churn command to display statistics about repository history
4799 clonebundles
4801 advertise pre-generated bundles to seed clones
4802 closehead
4804 close arbitrary heads without checking them out first
4805 convert
4807 import revisions from foreign VCS repositories into Mercurial
4808 eol automatically manage newlines in repository files
4810 extdiff
4812 command to allow external programs to compare revisions
4813 factotum
4815 http authentication with factotum
4816 fastexport
4818 export repositories as git fast-import stream
4819 githelp
4821 try mapping git commands to Mercurial commands
4822 gpg commands to sign and verify changesets
4824 hgk browse the repository in a graphical way
4826 highlight
4828 syntax highlighting for hgweb (requires Pygments)
4829 histedit
4831 interactive history editing
4832 keyword
4834 expand keywords in tracked files
4835 largefiles
4837 track large binary files
4838 mq manage a stack of patches
4840 notify hooks for sending email push notifications
4842 patchbomb
4844 command to send changesets as (a series of) patch emails
4845 rebase command to move sets of revisions to a different ancestor
4847 relink recreates hardlinks between repository clones
4849 schemes
4851 extend schemes with shortcuts to repository swarms
4852 share share a common history between several working directories
4854 transplant
4856 command to transplant changesets from another branch
4857 win32mbcs
4859 allow the use of MBCS paths with problematic encodings
4860 zeroconf
4862 discover and advertise repositories on the local network
4863
4865 Mercurial supports a functional language for selecting a set of files.
4866 Like other file patterns, this pattern type is indicated by a prefix,
4868 'set:'. The language supports a number of predicates which are joined
4869 by infix operators. Parenthesis can be used for grouping.
4870 Identifiers such as filenames or patterns must be quoted with single or
4872 double quotes if they contain characters outside of
4873 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4874 predicates. This generally applies to file patterns other than globs
4875 and arguments for predicates. Pattern prefixes such as path: may be
4876 specified without quoting.
4877 Special characters can be used in quoted identifiers by escaping them,
4879 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4880 preted, strings can be prefixed with r, e.g. r'...'.
4881 See also hg help patterns.
4883 Operators
4885 There is a single prefix operator:
4886 not x
4888 Files not in x. Short form is ! x.
4890 These are the supported infix operators:
4892 x and y
4894 The intersection of files in x and y. Short form is x & y.
4896 x or y
4898 The union of files in x and y. There are two alternative short
4900 forms: x | y and x + y.
4901 x - y
4903 Files in x but not in y.
4905 Predicates
4907 The following predicates are supported:
4908 added()
4910 File that is added according to hg status.
4912 binary()
4914 File that appears to be binary (contains NUL bytes).
4916 clean()
4918 File that is clean according to hg status.
4920 copied()
4922 File that is recorded as being copied.
4924 deleted()
4926 Alias for missing().
4928 encoding(name)
4930 File can be successfully decoded with the given character encod‐
4932 ing. May not be useful for encodings other than ASCII and UTF-8.
4933 eol(style)
4935 File contains newlines of the given style (dos, unix, mac). Bi‐
4937 nary files are excluded, files with mixed line endings match
4938 multiple styles.
4939 exec()
4941 File that is marked as executable.
4943 grep(regex)
4945 File contains the given regular expression.
4947 hgignore()
4949 File that matches the active .hgignore pattern.
4951 ignored()
4953 File that is ignored according to hg status.
4955 missing()
4957 File that is missing according to hg status.
4959 modified()
4961 File that is modified according to hg status.
4963 portable()
4965 File that has a portable name. (This doesn't include filenames
4967 with case collisions.)
4968 removed()
4970 File that is removed according to hg status.
4972 resolved()
4974 File that is marked resolved according to hg resolve -l.
4976 revs(revs, pattern)
4978 Evaluate set in the specified revisions. If the revset match
4980 multiple revs, this will return file matching pattern in any of
4981 the revision.
4982 size(expression)
4984 File size matches the given expression. Examples:
4986 • size('1k') - files from 1024 to 2047 bytes
4988 • size('< 20k') - files less than 20480 bytes
4990 • size('>= .5MB') - files at least 524288 bytes
4992 • size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
4994 status(base, rev, pattern)
4996 Evaluate predicate using status change between base and rev. Ex‐
4998 amples:
4999 • status(3, 7, added()) - matches files added from "3" to "7"
5001 subrepo([pattern])
5003 Subrepositories whose paths match the given pattern.
5005 symlink()
5007 File that is marked as a symlink.
5009 tracked()
5011 File that is under Mercurial control.
5013 unknown()
5015 File that is unknown according to hg status.
5017 unresolved()
5019 File that is marked unresolved according to hg resolve -l.
5021 Examples
5023 Some sample queries:
5024 • Show status of files that appear to be binary in the working direc‐
5026 tory:
5027 hg status -A "set:binary()"
5029 • Forget files that are in .hgignore but are already tracked:
5031 hg forget "set:hgignore() and not ignored()"
5033 • Find text files that contain a string:
5035 hg files "set:grep(magic) and not binary()"
5037 • Find C files in a non-standard encoding:
5039 hg files "set:**.c and not encoding('UTF-8')"
5041 • Revert copies of large binary files:
5043 hg revert "set:copied() and binary() and size('>1M')"
5045 • Revert files that were added to the working directory:
5047 hg revert "set:revs('wdir()', added())"
5049 • Remove files listed in foo.lst that contain the letter a or b:
5051 hg remove "set: listfile:foo.lst and (**a* or **b*)"
5053
5055 Most Mercurial commands accept various flags.
5056 Flag names
5058 Flags for each command are listed in hg help for that command. Addi‐
5059 tionally, some flags, such as --repository, are global and can be used
5060 with any command - those are seen in hg help -v, and can be specified
5061 before or after the command.
5062 Every flag has at least a long name, such as --repository. Some flags
5064 may also have a short one-letter name, such as the equivalent -R. Using
5065 the short or long name is equivalent and has the same effect. The long
5066 name may be abbreviated to any unambiguous prefix. For example, hg com‐
5067 mit --amend can be abbreviated to hg commit --am.
5068 Flags that have a short name can also be bundled together - for in‐
5070 stance, to specify both --edit (short -e) and --interactive (short -i),
5071 one could use:
5072 hg commit -ei
5074 If any of the bundled flags takes a value (i.e. is not a boolean), it
5076 must be last, followed by the value:
5077 hg commit -im 'Message'
5079 Flag types
5081 Mercurial command-line flags can be strings, numbers, booleans, or
5082 lists of strings.
5083 Specifying flag values
5085 The following syntaxes are allowed, assuming a flag 'flagname' with
5086 short name 'f':
5087 --flagname=foo
5089 --flagname foo
5090 -f foo
5091 -ffoo
5092 This syntax applies to all non-boolean flags (strings, numbers or
5094 lists).
5095 Specifying boolean flags
5097 Boolean flags do not take a value parameter. To specify a boolean, use
5098 the flag name to set it to true, or the same name prefixed with 'no-'
5099 to set it to false:
5100 hg commit --interactive
5102 hg commit --no-interactive
5103 Specifying list flags
5105 List flags take multiple values. To specify them, pass the flag multi‐
5106 ple times:
5107 hg files --include mercurial --include tests
5109 Setting flag defaults
5111 In order to set a default value for a flag in an hgrc file, it is rec‐
5112 ommended to use aliases:
5113 [alias]
5115 commit = commit --interactive
5116 For more information on hgrc files, see hg help config.
5118 Overriding flags on the command line
5120 If the same non-list flag is specified multiple times on the command
5121 line, the latest specification is used:
5122 hg commit -m "Ignored value" -m "Used value"
5124 This includes the use of aliases - e.g., if one has:
5126 [alias]
5128 committemp = commit -m "Ignored value"
5129 then the following command will override that -m:
5131 hg committemp -m "Used value"
5133 Overriding flag defaults
5135 Every flag has a default value, and you may also set your own defaults
5136 in hgrc as described above. Except for list flags, defaults can be
5137 overridden on the command line simply by specifying the flag in that
5138 location.
5139 Hidden flags
5141 Some flags are not shown in a command's help by default - specifically,
5142 those that are deemed to be experimental, deprecated or advanced. To
5143 show all flags, add the --verbose flag for the help command:
5144 hg help --verbose commit
5146
5148 Ancestor
5149 Any changeset that can be reached by an unbroken chain of parent
5150 changesets from a given changeset. More precisely, the ancestors
5151 of a changeset can be defined by two properties: a parent of a
5152 changeset is an ancestor, and a parent of an ancestor is an an‐
5153 cestor. See also: 'Descendant'.
5154 Bookmark
5156 Bookmarks are pointers to certain commits that move when commit‐
5157 ting. They are similar to tags in that it is possible to use
5158 bookmark names in all places where Mercurial expects a changeset
5159 ID, e.g., with hg update. Unlike tags, bookmarks move along when
5160 you make a commit.
5161 Bookmarks can be renamed, copied and deleted. Bookmarks are lo‐
5163 cal, unless they are explicitly pushed or pulled between reposi‐
5164 tories. Pushing and pulling bookmarks allow you to collaborate
5165 with others on a branch without creating a named branch.
5166 Branch (Noun) A child changeset that has been created from a parent
5168 that is not a head. These are known as topological branches, see
5169 'Branch, topological'. If a topological branch is named, it be‐
5170 comes a named branch. If a topological branch is not named, it
5171 becomes an anonymous branch. See 'Branch, anonymous' and
5172 'Branch, named'.
5173 Branches may be created when changes are pulled from or pushed
5175 to a remote repository, since new heads may be created by these
5176 operations. Note that the term branch can also be used infor‐
5177 mally to describe a development process in which certain devel‐
5178 opment is done independently of other development. This is some‐
5179 times done explicitly with a named branch, but it can also be
5180 done locally, using bookmarks or clones and anonymous branches.
5181 Example: "The experimental branch."
5183 (Verb) The action of creating a child changeset which results in
5185 its parent having more than one child.
5186 Example: "I'm going to branch at X."
5188 Branch, anonymous
5190 Every time a new child changeset is created from a parent that
5191 is not a head and the name of the branch is not changed, a new
5192 anonymous branch is created.
5193 Branch, closed
5195 A named branch whose branch heads have all been closed.
5196 Branch, default
5198 The branch assigned to a changeset when no name has previously
5199 been assigned.
5200 Branch head
5202 See 'Head, branch'.
5203 Branch, inactive
5205 If a named branch has no topological heads, it is considered to
5206 be inactive. As an example, a feature branch becomes inactive
5207 when it is merged into the default branch. The hg branches com‐
5208 mand shows inactive branches by default, though they can be hid‐
5209 den with hg branches --active.
5210 NOTE: this concept is deprecated because it is too implicit.
5212 Branches should now be explicitly closed using hg commit
5213 --close-branch when they are no longer needed.
5214 Branch, named
5216 A collection of changesets which have the same branch name. By
5217 default, children of a changeset in a named branch belong to the
5218 same named branch. A child can be explicitly assigned to a dif‐
5219 ferent branch. See hg help branch, hg help branches and hg com‐
5220 mit --close-branch for more information on managing branches.
5221 Named branches can be thought of as a kind of namespace, divid‐
5223 ing the collection of changesets that comprise the repository
5224 into a collection of disjoint subsets. A named branch is not
5225 necessarily a topological branch. If a new named branch is cre‐
5226 ated from the head of another named branch, or the default
5227 branch, but no further changesets are added to that previous
5228 branch, then that previous branch will be a branch in name only.
5229 Branch tip
5231 See 'Tip, branch'.
5232 Branch, topological
5234 Every time a new child changeset is created from a parent that
5235 is not a head, a new topological branch is created. If a topo‐
5236 logical branch is named, it becomes a named branch. If a topo‐
5237 logical branch is not named, it becomes an anonymous branch of
5238 the current, possibly default, branch.
5239 Changelog
5241 A record of the changesets in the order in which they were added
5242 to the repository. This includes details such as changeset id,
5243 author, commit message, date, and list of changed files.
5244 Changeset
5246 A snapshot of the state of the repository used to record a
5247 change.
5248 Changeset, child
5250 The converse of parent changeset: if P is a parent of C, then C
5251 is a child of P. There is no limit to the number of children
5252 that a changeset may have.
5253 Changeset id
5255 A SHA-1 hash that uniquely identifies a changeset. It may be
5256 represented as either a "long" 40 hexadecimal digit string, or a
5257 "short" 12 hexadecimal digit string.
5258 Changeset, merge
5260 A changeset with two parents. This occurs when a merge is com‐
5261 mitted.
5262 Changeset, parent
5264 A revision upon which a child changeset is based. Specifically,
5265 a parent changeset of a changeset C is a changeset whose node
5266 immediately precedes C in the DAG. Changesets have at most two
5267 parents.
5268 Checkout
5270 (Noun) The working directory being updated to a specific revi‐
5271 sion. This use should probably be avoided where possible, as
5272 changeset is much more appropriate than checkout in this con‐
5273 text.
5274 Example: "I'm using checkout X."
5276 (Verb) Updating the working directory to a specific changeset.
5278 See hg help update.
5279 Example: "I'm going to check out changeset X."
5281 Child changeset
5283 See 'Changeset, child'.
5284 Close changeset
5286 See 'Head, closed branch'.
5287 Closed branch
5289 See 'Branch, closed'.
5290 Clone (Noun) An entire or partial copy of a repository. The partial
5292 clone must be in the form of a revision and its ancestors.
5293 Example: "Is your clone up to date?"
5295 (Verb) The process of creating a clone, using hg clone.
5297 Example: "I'm going to clone the repository."
5299 Closed branch head
5301 See 'Head, closed branch'.
5302 Commit (Noun) A synonym for changeset.
5304 Example: "Is the bug fixed in your recent commit?"
5306 (Verb) The act of recording changes to a repository. When files
5308 are committed in a working directory, Mercurial finds the dif‐
5309 ferences between the committed files and their parent changeset,
5310 creating a new changeset in the repository.
5311 Example: "You should commit those changes now."
5313 Cset A common abbreviation of the term changeset.
5315 DAG The repository of changesets of a distributed version control
5317 system (DVCS) can be described as a directed acyclic graph
5318 (DAG), consisting of nodes and edges, where nodes correspond to
5319 changesets and edges imply a parent -> child relation. This
5320 graph can be visualized by graphical tools such as hg log
5321 --graph. In Mercurial, the DAG is limited by the requirement for
5322 children to have at most two parents.
5323 Deprecated
5325 Feature removed from documentation, but not scheduled for re‐
5326 moval.
5327 Default branch
5329 See 'Branch, default'.
5330 Descendant
5332 Any changeset that can be reached by a chain of child changesets
5333 from a given changeset. More precisely, the descendants of a
5334 changeset can be defined by two properties: the child of a
5335 changeset is a descendant, and the child of a descendant is a
5336 descendant. See also: 'Ancestor'.
5337 Diff (Noun) The difference between the contents and attributes of
5339 files in two changesets or a changeset and the current working
5340 directory. The difference is usually represented in a standard
5341 form called a "diff" or "patch". The "git diff" format is used
5342 when the changes include copies, renames, or changes to file at‐
5343 tributes, none of which can be represented/handled by classic
5344 "diff" and "patch".
5345 Example: "Did you see my correction in the diff?"
5347 (Verb) Diffing two changesets is the action of creating a diff
5349 or patch.
5350 Example: "If you diff with changeset X, you will see what I
5352 mean."
5353 Directory, working
5355 The working directory represents the state of the files tracked
5356 by Mercurial, that will be recorded in the next commit. The
5357 working directory initially corresponds to the snapshot at an
5358 existing changeset, known as the parent of the working direc‐
5359 tory. See 'Parent, working directory'. The state may be modified
5360 by changes to the files introduced manually or by a merge. The
5361 repository metadata exists in the .hg directory inside the work‐
5362 ing directory.
5363 Draft Changesets in the draft phase have not been shared with publish‐
5365 ing repositories and may thus be safely changed by history-modi‐
5366 fying extensions. See hg help phases.
5367 Experimental
5369 Feature that may change or be removed at a later date.
5370 Graph See DAG and hg log --graph.
5372 Head The term 'head' may be used to refer to both a branch head or a
5374 repository head, depending on the context. See 'Head, branch'
5375 and 'Head, repository' for specific definitions.
5376 Heads are where development generally takes place and are the
5378 usual targets for update and merge operations.
5379 Head, branch
5381 A changeset with no descendants on the same named branch.
5382 Head, closed branch
5384 A changeset that marks a head as no longer interesting. The
5385 closed head is no longer listed by hg heads. A branch is consid‐
5386 ered closed when all its heads are closed and consequently is
5387 not listed by hg branches.
5388 Closed heads can be re-opened by committing new changeset as the
5390 child of the changeset that marks a head as closed.
5391 Head, repository
5393 A topological head which has not been closed.
5394 Head, topological
5396 A changeset with no children in the repository.
5397 History, immutable
5399 Once committed, changesets cannot be altered. Extensions which
5400 appear to change history actually create new changesets that re‐
5401 place existing ones, and then destroy the old changesets. Doing
5402 so in public repositories can result in old changesets being
5403 reintroduced to the repository.
5404 History, rewriting
5406 The changesets in a repository are immutable. However, exten‐
5407 sions to Mercurial can be used to alter the repository, usually
5408 in such a way as to preserve changeset contents.
5409 Immutable history
5411 See 'History, immutable'.
5412 Merge changeset
5414 See 'Changeset, merge'.
5415 Manifest
5417 Each changeset has a manifest, which is the list of files that
5418 are tracked by the changeset.
5419 Merge Used to bring together divergent branches of work. When you up‐
5421 date to a changeset and then merge another changeset, you bring
5422 the history of the latter changeset into your working directory.
5423 Once conflicts are resolved (and marked), this merge may be com‐
5424 mitted as a merge changeset, bringing two branches together in
5425 the DAG.
5426 Named branch
5428 See 'Branch, named'.
5429 Null changeset
5431 The empty changeset. It is the parent state of newly-initialized
5432 repositories and repositories with no checked out revision. It
5433 is thus the parent of root changesets and the effective ancestor
5434 when merging unrelated changesets. Can be specified by the alias
5435 'null' or by the changeset ID '000000000000'.
5436 Parent See 'Changeset, parent'.
5438 Parent changeset
5440 See 'Changeset, parent'.
5441 Parent, working directory
5443 The working directory parent reflects a virtual revision which
5444 is the child of the changeset (or two changesets with an uncom‐
5445 mitted merge) shown by hg parents. This is changed with hg up‐
5446 date. Other commands to see the working directory parent are hg
5447 summary and hg id. Can be specified by the alias ".".
5448 Patch (Noun) The product of a diff operation.
5450 Example: "I've sent you my patch."
5452 (Verb) The process of using a patch file to transform one
5454 changeset into another.
5455 Example: "You will need to patch that revision."
5457 Phase A per-changeset state tracking how the changeset has been or
5459 should be shared. See hg help phases.
5460 Public Changesets in the public phase have been shared with publishing
5462 repositories and are therefore considered immutable. See hg help
5463 phases.
5464 Pull An operation in which changesets in a remote repository which
5466 are not in the local repository are brought into the local
5467 repository. Note that this operation without special arguments
5468 only updates the repository, it does not update the files in the
5469 working directory. See hg help pull.
5470 Push An operation in which changesets in a local repository which are
5472 not in a remote repository are sent to the remote repository.
5473 Note that this operation only adds changesets which have been
5474 committed locally to the remote repository. Uncommitted changes
5475 are not sent. See hg help push.
5476 Repository
5478 The metadata describing all recorded states of a collection of
5479 files. Each recorded state is represented by a changeset. A
5480 repository is usually (but not always) found in the .hg subdi‐
5481 rectory of a working directory. Any recorded state can be recre‐
5482 ated by "updating" a working directory to a specific changeset.
5483 Repository head
5485 See 'Head, repository'.
5486 Revision
5488 A state of the repository at some point in time. Earlier revi‐
5489 sions can be updated to by using hg update. See also 'Revision
5490 number'; See also 'Changeset'.
5491 Revision number
5493 This integer uniquely identifies a changeset in a specific
5494 repository. It represents the order in which changesets were
5495 added to a repository, starting with revision number 0. Note
5496 that the revision number may be different in each clone of a
5497 repository. To identify changesets uniquely between different
5498 clones, see 'Changeset id'.
5499 Revlog History storage mechanism used by Mercurial. It is a form of
5501 delta encoding, with occasional full revision of data followed
5502 by delta of each successive revision. It includes data and an
5503 index pointing to the data.
5504 Rewriting history
5506 See 'History, rewriting'.
5507 Root A changeset that has only the null changeset as its parent. Most
5509 repositories have only a single root changeset.
5510 Secret Changesets in the secret phase may not be shared via push, pull,
5512 or clone. See hg help phases.
5513 Tag An alternative name given to a changeset. Tags can be used in
5515 all places where Mercurial expects a changeset ID, e.g., with hg
5516 update. The creation of a tag is stored in the history and will
5517 thus automatically be shared with other using push and pull.
5518 Tip The changeset with the highest revision number. It is the
5520 changeset most recently added in a repository.
5521 Tip, branch
5523 The head of a given branch with the highest revision number.
5524 When a branch name is used as a revision identifier, it refers
5525 to the branch tip. See also 'Branch, head'. Note that because
5526 revision numbers may be different in different repository
5527 clones, the branch tip may be different in different cloned
5528 repositories.
5529 Update (Noun) Another synonym of changeset.
5531 Example: "I've pushed an update."
5533 (Verb) This term is usually used to describe updating the state
5535 of the working directory to that of a specific changeset. See hg
5536 help update.
5537 Example: "You should update."
5539 Working directory
5541 See 'Directory, working'.
5542 Working directory parent
5544 See 'Parent, working directory'.
5545
5547 Synopsis
5548 The Mercurial system uses a file called .hgignore in the root directory
5549 of a repository to control its behavior when it searches for files that
5550 it is not currently tracking.
5551 Description
5553 The working directory of a Mercurial repository will often contain
5554 files that should not be tracked by Mercurial. These include backup
5555 files created by editors and build products created by compilers.
5556 These files can be ignored by listing them in a .hgignore file in the
5557 root of the working directory. The .hgignore file must be created manu‐
5558 ally. It is typically put under version control, so that the settings
5559 will propagate to other repositories with push and pull.
5560 An untracked file is ignored if its path relative to the repository
5562 root directory, or any prefix path of that path, is matched against any
5563 pattern in .hgignore.
5564 For example, say we have an untracked file, file.c, at a/b/file.c in‐
5566 side our repository. Mercurial will ignore file.c if any pattern in
5567 .hgignore matches a/b/file.c, a/b or a.
5568 In addition, a Mercurial configuration file can reference a set of
5570 per-user or global ignore files. See the ignore configuration key on
5571 the [ui] section of hg help config for details of how to configure
5572 these files.
5573 To control Mercurial's handling of files that it manages, many commands
5575 support the -I and -X options; see hg help <command> and hg help pat‐
5576 terns for details.
5577 Files that are already tracked are not affected by .hgignore, even if
5579 they appear in .hgignore. An untracked file X can be explicitly added
5580 with hg add X, even if X would be excluded by a pattern in .hgignore.
5581 Syntax
5583 An ignore file is a plain text file consisting of a list of patterns,
5584 with one pattern per line. Empty lines are skipped. The # character is
5585 treated as a comment character, and the \ character is treated as an
5586 escape character.
5587 Mercurial supports several pattern syntaxes. The default syntax used is
5589 Python/Perl-style regular expressions.
5590 To change the syntax used, use a line of the following form:
5592 syntax: NAME
5594 where NAME is one of the following:
5596 regexp
5598 Regular expression, Python/Perl syntax.
5600 glob
5602 Shell-style glob.
5604 rootglob
5606 A variant of glob that is rooted (see below).
5608 The chosen syntax stays in effect when parsing all patterns that fol‐
5610 low, until another syntax is selected.
5611 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
5613 the form *.c will match a file ending in .c in any directory, and a
5614 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
5615 tern, start it with ^. To get the same effect with glob-syntax, you
5616 have to use rootglob.
5617 Subdirectories can have their own .hgignore settings by adding subin‐
5619 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
5620 terns for details on subinclude: and include:.
5621 Note Patterns specified in other than .hgignore are always rooted.
5623 Please see hg help patterns for details.
5624 Example
5626 Here is an example ignore file.
5627 # use glob syntax.
5629 syntax: glob
5630 *.elc
5632 *.pyc
5633 *~
5634 # switch to regexp syntax.
5636 syntax: regexp
5637 ^\.pc/
5638 Debugging
5640 Use the debugignore command to see if and why a file is ignored, or to
5641 see the combined ignore pattern. See hg help debugignore for details.
5642
5644 Mercurial's internal web server, hgweb, can serve either a single
5645 repository, or a tree of repositories. In the second case, repository
5646 paths and global options can be defined using a dedicated configuration
5647 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
5648 This file uses the same syntax as other Mercurial configuration files
5650 but recognizes only the following sections:
5651 • web
5653 • paths
5655 • collections
5657 The web options are thoroughly described in hg help config.
5659 The paths section maps URL paths to paths of repositories in the
5661 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
5662 rial repositories can be published and only according to the configura‐
5663 tion.
5664 The left hand side is the path in the URL. Note that hgweb reserves
5666 subpaths like rev or file, try using different names for nested reposi‐
5667 tories to avoid confusing effects.
5668 The right hand side is the path in the filesystem. If the specified
5670 path ends with * or ** the filesystem will be searched recursively for
5671 repositories below that point. With * it will not recurse into the
5672 repositories it finds (except for .hg/patches). With ** it will also
5673 search inside repository working directories and possibly find sub‐
5674 repositories.
5675 In this example:
5677 [paths]
5679 /projects/a = /srv/tmprepos/a
5680 /projects/b = c:/repos/b
5681 / = /srv/repos/*
5682 /user/bob = /home/bob/repos/**
5683 • The first two entries make two repositories in different directories
5685 appear under the same directory in the web interface
5686 • The third entry will publish every Mercurial repository found in
5688 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
5689 as http://server/quux/
5690 • The fourth entry will publish both http://server/user/bob/quux/ and
5692 http://server/user/bob/quux/testsubrepo/
5693 The collections section is deprecated and has been superseded by paths.
5695 URLs and Common Arguments
5697 URLs under each repository have the form /{command}[/{arguments}] where
5698 {command} represents the name of a command or handler and {arguments}
5699 represents any number of additional URL parameters to that command.
5700 The web server has a default style associated with it. Styles map to a
5702 collection of named templates. Each template is used to render a spe‐
5703 cific piece of data, such as a changeset or diff.
5704 The style for the current request can be overridden two ways. First, if
5706 {command} contains a hyphen (-), the text before the hyphen defines the
5707 style. For example, /atom-log will render the log command handler with
5708 the atom style. The second way to set the style is with the style query
5709 string argument. For example, /log?style=atom. The hyphenated URL pa‐
5710 rameter is preferred.
5711 Not all templates are available for all styles. Attempting to use a
5713 style that doesn't have all templates defined may result in an error
5714 rendering the page.
5715 Many commands take a {revision} URL parameter. This defines the change‐
5717 set to operate on. This is commonly specified as the short, 12 digit
5718 hexadecimal abbreviation for the full 40 character unique revision
5719 identifier. However, any value described by hg help revisions typically
5720 works.
5721 Commands and URLs
5723 The following web commands and their URLs are available:
5724 /annotate/{revision}/{path}
5726 Show changeset information for each line in a file.
5727 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
5729 string arguments have the same meaning as their [annotate] config
5730 equivalents. It uses the hgrc boolean parsing logic to interpret the
5731 value. e.g. 0 and false are false and 1 and true are true. If not de‐
5732 fined, the server default settings are used.
5733 The fileannotate template is rendered.
5735 /archive/{revision}.{format}[/{path}]
5737 Obtain an archive of repository content.
5738 The content and type of the archive is defined by a URL path parameter.
5740 format is the file extension of the archive type to be generated. e.g.
5741 zip or tar.bz2. Not all archive types may be allowed by your server
5742 configuration.
5743 The optional path URL parameter controls content to include in the ar‐
5745 chive. If omitted, every file in the specified revision is present in
5746 the archive. If included, only the specified file or contents of the
5747 specified directory will be included in the archive.
5748 No template is used for this handler. Raw, binary content is generated.
5750 /bookmarks
5752 Show information about bookmarks.
5753 No arguments are accepted.
5755 The bookmarks template is rendered.
5757 /branches
5759 Show information about branches.
5760 All known branches are contained in the output, even closed branches.
5762 No arguments are accepted.
5764 The branches template is rendered.
5766 /changelog[/{revision}]
5768 Show information about multiple changesets.
5769 If the optional revision URL argument is absent, information about all
5771 changesets starting at tip will be rendered. If the revision argument
5772 is present, changesets will be shown starting from the specified revi‐
5773 sion.
5774 If revision is absent, the rev query string argument may be defined.
5776 This will perform a search for changesets.
5777 The argument for rev can be a single revision, a revision set, or a
5779 literal keyword to search for in changeset data (equivalent to hg log
5780 -k).
5781 The revcount query string argument defines the maximum numbers of
5783 changesets to render.
5784 For non-searches, the changelog template will be rendered.
5786 /changeset[/{revision}]
5788 Show information about a single changeset.
5789 A URL path argument is the changeset identifier to show. See hg help
5791 revisions for possible values. If not defined, the tip changeset will
5792 be shown.
5793 The changeset template is rendered. Contents of the changesettag,
5795 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5796 lated to diffs may all be used to produce the output.
5797 /comparison/{revision}/{path}
5799 Show a comparison between the old and new versions of a file from
5800 changes made on a particular revision.
5801 This is similar to the diff handler. However, this form features a
5803 split or side-by-side diff rather than a unified diff.
5804 The context query string argument can be used to control the lines of
5806 context in the diff.
5807 The filecomparison template is rendered.
5809 /diff/{revision}/{path}
5811 Show how a file changed in a particular commit.
5812 The filediff template is rendered.
5814 This handler is registered under both the /diff and /filediff paths.
5816 /diff is used in modern code.
5817 /file/{revision}[/{path}]
5819 Show information about a directory or file in the repository.
5820 Info about the path given as a URL parameter will be rendered.
5822 If path is a directory, information about the entries in that directory
5824 will be rendered. This form is equivalent to the manifest handler.
5825 If path is a file, information about that file will be shown via the
5827 filerevision template.
5828 If path is not defined, information about the root directory will be
5830 rendered.
5831 /diff/{revision}/{path}
5833 Show how a file changed in a particular commit.
5834 The filediff template is rendered.
5836 This handler is registered under both the /diff and /filediff paths.
5838 /diff is used in modern code.
5839 /filelog/{revision}/{path}
5841 Show information about the history of a file in the repository.
5842 The revcount query string argument can be defined to control the maxi‐
5844 mum number of entries to show.
5845 The filelog template will be rendered.
5847 /graph[/{revision}]
5849 Show information about the graphical topology of the repository.
5850 Information rendered by this handler can be used to create visual rep‐
5852 resentations of repository topology.
5853 The revision URL parameter controls the starting changeset. If it's ab‐
5855 sent, the default is tip.
5856 The revcount query string argument can define the number of changesets
5858 to show information for.
5859 The graphtop query string argument can specify the starting changeset
5861 for producing jsdata variable that is used for rendering graph in Java‐
5862 Script. By default it has the same value as revision.
5863 This handler will render the graph template.
5865 /help[/{topic}]
5867 Render help documentation.
5868 This web command is roughly equivalent to hg help. If a topic is de‐
5870 fined, that help topic will be rendered. If not, an index of available
5871 help topics will be rendered.
5872 The help template will be rendered when requesting help for a topic.
5874 helptopics will be rendered for the index of help topics.
5875 /log[/{revision}[/{path}]]
5877 Show repository or file history.
5878 For URLs of the form /log/{revision}, a list of changesets starting at
5880 the specified changeset identifier is shown. If {revision} is not de‐
5881 fined, the default is tip. This form is equivalent to the changelog
5882 handler.
5883 For URLs of the form /log/{revision}/{file}, the history for a specific
5885 file will be shown. This form is equivalent to the filelog handler.
5886 /manifest[/{revision}[/{path}]]
5888 Show information about a directory.
5889 If the URL path arguments are omitted, information about the root di‐
5891 rectory for the tip changeset will be shown.
5892 Because this handler can only show information for directories, it is
5894 recommended to use the file handler instead, as it can handle both di‐
5895 rectories and files.
5896 The manifest template will be rendered for this handler.
5898 /changeset[/{revision}]
5900 Show information about a single changeset.
5901 A URL path argument is the changeset identifier to show. See hg help
5903 revisions for possible values. If not defined, the tip changeset will
5904 be shown.
5905 The changeset template is rendered. Contents of the changesettag,
5907 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5908 lated to diffs may all be used to produce the output.
5909 /shortlog
5911 Show basic information about a set of changesets.
5912 This accepts the same parameters as the changelog handler. The only
5914 difference is the shortlog template will be rendered instead of the
5915 changelog template.
5916 /summary
5918 Show a summary of repository state.
5919 Information about the latest changesets, bookmarks, tags, and branches
5921 is captured by this handler.
5922 The summary template is rendered.
5924 /tags
5926 Show information about tags.
5927 No arguments are accepted.
5929 The tags template is rendered.
5931
5933 To access a subtopic, use "hg help internals.{subtopic-name}"
5934 bid-merge
5936 Bid Merge Algorithm
5937 bundle2
5939 Bundle2
5940 bundles
5942 Bundles
5943 cbor CBOR
5945 censor Censor
5947 changegroups
5949 Changegroups
5950 config Config Registrar
5952 dirstate-v2
5954 dirstate-v2 file format
5955 extensions
5957 Extension API
5958 mergestate
5960 Mergestate
5961 requirements
5963 Repository Requirements
5964 revlogs
5966 Revision Logs
5967 wireprotocol
5969 Wire Protocol
5970 wireprotocolrpc
5972 Wire Protocol RPC
5973 wireprotocolv2
5975 Wire Protocol Version 2
5976
5978 To merge files Mercurial uses merge tools.
5979 A merge tool combines two different versions of a file into a merged
5981 file. Merge tools are given the two files and the greatest common an‐
5982 cestor of the two file versions, so they can determine the changes made
5983 on both branches.
5984 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
5986 out and in several extensions.
5987 Usually, the merge tool tries to automatically reconcile the files by
5989 combining all non-overlapping changes that occurred separately in the
5990 two different evolutions of the same initial base file. Furthermore,
5991 some interactive merge programs make it easier to manually resolve con‐
5992 flicting merges, either in a graphical way, or by inserting some con‐
5993 flict markers. Mercurial does not include any interactive merge pro‐
5994 grams but relies on external tools for that.
5995 Available merge tools
5997 External merge tools and their properties are configured in the
5998 merge-tools configuration section - see hgrc(5) - but they can often
5999 just be named by their executable.
6000 A merge tool is generally usable if its executable can be found on the
6002 system and if it can handle the merge. The executable is found if it is
6003 an absolute or relative executable path or the name of an application
6004 in the executable search path. The tool is assumed to be able to handle
6005 the merge if it can handle symlinks if the file is a symlink, if it can
6006 handle binary files if the file is binary, and if a GUI is available if
6007 the tool requires a GUI.
6008 There are some internal merge tools which can be used. The internal
6010 merge tools are:
6011 :dump
6013 Creates three versions of the files to merge, containing the
6015 contents of local, other and base. These files can then be used
6016 to perform a merge manually. If the file to be merged is named
6017 a.txt, these files will accordingly be named a.txt.local,
6018 a.txt.other and a.txt.base and they will be placed in the same
6019 directory as a.txt.
6020 This implies premerge. Therefore, files aren't dumped, if pre‐
6022 merge runs successfully. Use :forcedump to forcibly write files
6023 out.
6024 (actual capabilities: binary, symlink)
6026 :fail
6028 Rather than attempting to merge files that were modified on both
6030 branches, it marks them as unresolved. The resolve command must
6031 be used to resolve these conflicts.
6032 (actual capabilities: binary, symlink)
6034 :forcedump
6036 Creates three versions of the files as same as :dump, but omits
6038 premerge.
6039 (actual capabilities: binary, symlink)
6041 :local
6043 Uses the local p1() version of files as the merged version.
6045 (actual capabilities: binary, symlink)
6047 :merge
6049 Uses the internal non-interactive simple merge algorithm for
6051 merging files. It will fail if there are any conflicts and leave
6052 markers in the partially merged file. Markers will have two sec‐
6053 tions, one for each side of merge.
6054 :merge-local
6056 Like :merge, but resolve all conflicts non-interactively in fa‐
6058 vor of the local p1() changes.
6059 :merge-other
6061 Like :merge, but resolve all conflicts non-interactively in fa‐
6063 vor of the other p2() changes.
6064 :merge3
6066 Uses the internal non-interactive simple merge algorithm for
6068 merging files. It will fail if there are any conflicts and leave
6069 markers in the partially merged file. Marker will have three
6070 sections, one from each side of the merge and one for the base
6071 content.
6072 :mergediff
6074 Uses the internal non-interactive simple merge algorithm for
6076 merging files. It will fail if there are any conflicts and leave
6077 markers in the partially merged file. The marker will have two
6078 sections, one with the content from one side of the merge, and
6079 one with a diff from the base content to the content on the
6080 other side. (experimental)
6081 :other
6083 Uses the other p2() version of files as the merged version.
6085 (actual capabilities: binary, symlink)
6087 :prompt
6089 Asks the user which of the local p1() or the other p2() version
6091 to keep as the merged version.
6092 (actual capabilities: binary, symlink)
6094 :tagmerge
6096 Uses the internal tag merge algorithm (experimental).
6098 :union
6100 Uses the internal non-interactive simple merge algorithm for
6102 merging files. It will use both left and right sides for con‐
6103 flict regions. No markers are inserted.
6104 Internal tools are always available and do not require a GUI but will
6106 by default not handle symlinks or binary files. See next section for
6107 detail about "actual capabilities" described above.
6108 Choosing a merge tool
6110 Mercurial uses these rules when deciding which merge tool to use:
6111 1. If a tool has been specified with the --tool option to merge or re‐
6113 solve, it is used. If it is the name of a tool in the merge-tools
6114 configuration, its configuration is used. Otherwise the specified
6115 tool must be executable by the shell.
6116 2. If the HGMERGE environment variable is present, its value is used
6118 and must be executable by the shell.
6119 3. If the filename of the file to be merged matches any of the patterns
6121 in the merge-patterns configuration section, the first usable merge
6122 tool corresponding to a matching pattern is used.
6123 4. If ui.merge is set it will be considered next. If the value is not
6125 the name of a configured tool, the specified value is used and must
6126 be executable by the shell. Otherwise the named tool is used if it
6127 is usable.
6128 5. If any usable merge tools are present in the merge-tools configura‐
6130 tion section, the one with the highest priority is used.
6131 6. If a program named hgmerge can be found on the system, it is used -
6133 but it will by default not be used for symlinks and binary files.
6134 7. If the file to be merged is not binary and is not a symlink, then
6136 internal :merge is used.
6137 8. Otherwise, :prompt is used.
6139 For historical reason, Mercurial treats merge tools as below while ex‐
6141 amining rules above.
6142 ┌───────────┬────────────────┬────────┬─────────┐
6144 │step │ specified via │ binary │ symlink │
6145 ├───────────┼────────────────┼────────┼─────────┤
6146 │ │ --tool │ o/o │ o/o │
6147 │ 1. │ │ │ │
6148 ├───────────┼────────────────┼────────┼─────────┤
6149 │ │ HGMERGE │ o/o │ o/o │
6150 │ 2. │ │ │ │
6151 ├───────────┼────────────────┼────────┼─────────┤
6152 │ │ merge-patterns │ o/o(*) │ x/?(*) │
6153 │ 3. │ │ │ │
6154 ├───────────┼────────────────┼────────┼─────────┤
6155 │ │ ui.merge │ x/?(*) │ x/?(*) │
6156 │ 4. │ │ │ │
6157 └───────────┴────────────────┴────────┴─────────┘
6158 Each capability column indicates Mercurial behavior for internal/exter‐
6160 nal merge tools at examining each rule.
6161 • "o": "assume that a tool has capability"
6163 • "x": "assume that a tool does not have capability"
6165 • "?": "check actual capability of a tool"
6167 If merge.strict-capability-check configuration is true, Mercurial
6169 checks capabilities of merge tools strictly in (*) cases above (= each
6170 capability column becomes "?/?"). It is false by default for backward
6171 compatibility.
6172 Note After selecting a merge program, Mercurial will by default at‐
6174 tempt to merge the files using a simple merge algorithm first.
6175 Only if it doesn't succeed because of conflicting changes will
6176 Mercurial actually execute the merge program. Whether to use the
6177 simple merge algorithm first can be controlled by the premerge
6178 setting of the merge tool. Premerge is enabled by default unless
6179 the file is binary or a symlink.
6180 See the merge-tools and ui sections of hgrc(5) for details on the con‐
6182 figuration of merge tools.
6183
6185 Some Mercurial commands can produce a lot of output, and Mercurial will
6186 attempt to use a pager to make those commands more pleasant.
6187 To set the pager that should be used, set the application variable:
6189 [pager]
6191 pager = less -FRX
6192 If no pager is set in the user or repository configuration, Mercurial
6194 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
6195 from the default or system configuration is used. If none of these are
6196 set, a default pager will be used, typically less on Unix and more on
6197 Windows.
6198 On Windows, more is not color aware, so using it effectively disables
6200 color. MSYS and Cygwin shells provide less as a pager, which can be
6201 configured to support ANSI color codes. See hg help con‐
6202 fig.color.pagermode to configure the color mode when invoking a pager.
6203 You can disable the pager for certain commands by adding them to the
6205 pager.ignore list:
6206 [pager]
6208 ignore = version, help, update
6209 To ignore global commands like hg version or hg help, you have to spec‐
6211 ify them in your user configuration file.
6212 To control whether the pager is used at all for an individual command,
6214 you can use --pager=<value>:
6215 • use as needed: auto.
6217 • require the pager: yes or on.
6219 • suppress the pager: no or off (any unrecognized value will also
6221 work).
6222 To globally turn off all attempts to use a pager, set:
6224 [ui]
6226 paginate = never
6227 which will prevent the pager from running.
6229
6231 Mercurial accepts several notations for identifying one or more files
6232 at a time.
6233 By default, Mercurial treats filenames verbatim without pattern match‐
6235 ing, relative to the current working directory. Note that your system
6236 shell might perform pattern matching of its own before passing file‐
6237 names into Mercurial.
6238 Alternate pattern notations must be specified explicitly.
6240 Note Patterns specified in .hgignore are not rooted. Please see hg
6242 help hgignore for details.
6243 To use a plain path name without any pattern matching, start it with
6245 path:. These path names must completely match starting at the current
6246 repository root, and when the path points to a directory, it is matched
6247 recursively. To match all files in a directory non-recursively (not in‐
6248 cluding any files in subdirectories), rootfilesin: can be used, speci‐
6249 fying an absolute path (relative to the repository root).
6250 To use an extended glob, start a name with glob:. Globs are rooted at
6252 the current directory; a glob such as *.c will only match files in the
6253 current directory ending with .c. rootglob: can be used instead of
6254 glob: for a glob that is rooted at the root of the repository.
6255 The supported glob syntax extensions are ** to match any string across
6257 path separators and {a,b} to mean "a or b".
6258 To use a Perl/Python regular expression, start a name with re:. Regexp
6260 pattern matching is anchored at the root of the repository.
6261 To read name patterns from a file, use listfile: or listfile0:. The
6263 latter expects null delimited patterns while the former expects line
6264 feeds. Each string read from the file is itself treated as a file pat‐
6265 tern.
6266 To read a set of patterns from a file, use include: or subinclude:.
6268 include: will use all the patterns from the given file and treat them
6269 as if they had been passed in manually. subinclude: will only apply
6270 the patterns against files that are under the subinclude file's direc‐
6271 tory. See hg help hgignore for details on the format of these files.
6272 All patterns, except for glob: specified in command line (not for -I or
6274 -X options), can match also against directories: files under matched
6275 directories are treated as matched. For -I and -X options, glob: will
6276 match directories recursively.
6277 Plain examples:
6279 path:foo/bar a name bar in a directory named foo in the root
6281 of the repository
6282 path:path:name a file or directory named "path:name"
6283 rootfilesin:foo/bar the files in a directory called foo/bar, but not any files
6284 in its subdirectories and not a file bar in directory foo
6285 Glob examples:
6287 glob:*.c any name ending in ".c" in the current directory
6289 *.c any name ending in ".c" in the current directory
6290 **.c any name ending in ".c" in any subdirectory of the
6291 current directory including itself.
6292 foo/* any file in directory foo
6293 foo/** any file in directory foo plus all its subdirectories,
6294 recursively
6295 foo/*.c any name ending in ".c" in the directory foo
6296 foo/**.c any name ending in ".c" in any subdirectory of foo
6297 including itself.
6298 rootglob:*.c any name ending in ".c" in the root of the repository
6299 Regexp examples:
6301 re:.*\.c$ any name ending in ".c", anywhere in the repository
6303 File examples:
6305 listfile:list.txt read list from list.txt with one file pattern per line
6307 listfile0:list.txt read list from list.txt with null byte delimiters
6308 See also hg help filesets.
6310 Include examples:
6312 include:path/to/mypatternfile reads patterns to be applied to all paths
6314 subinclude:path/to/subignorefile reads patterns specifically for paths in the
6315 subdirectory
6316
6318 What are phases?
6319 Phases are a system for tracking which changesets have been or should
6320 be shared. This helps prevent common mistakes when modifying history
6321 (for instance, with the mq or rebase extensions).
6322 Each changeset in a repository is in one of the following phases:
6324 • public : changeset is visible on a public server
6326 • draft : changeset is not yet published
6328 • secret : changeset should not be pushed, pulled, or cloned
6330 These phases are ordered (public < draft < secret) and no changeset can
6332 be in a lower phase than its ancestors. For instance, if a changeset is
6333 public, all its ancestors are also public. Lastly, changeset phases
6334 should only be changed towards the public phase.
6335 How are phases managed?
6337 For the most part, phases should work transparently. By default, a
6338 changeset is created in the draft phase and is moved into the public
6339 phase when it is pushed to another repository.
6340 Once changesets become public, extensions like mq and rebase will
6342 refuse to operate on them to prevent creating duplicate changesets.
6343 Phases can also be manually manipulated with the hg phase command if
6344 needed. See hg help -v phase for examples.
6345 To make your commits secret by default, put this in your configuration
6347 file:
6348 [phases]
6350 new-commit = secret
6351 Phases and servers
6353 Normally, all servers are publishing by default. This means:
6354 - all draft changesets that are pulled or cloned appear in phase
6356 public on the client
6357 - all draft changesets that are pushed appear as public on both
6359 client and server
6360 - secret changesets are neither pushed, pulled, or cloned
6362 Note Pulling a draft changeset from a publishing server does not mark
6364 it as public on the server side due to the read-only nature of
6365 pull.
6366 Sometimes it may be desirable to push and pull changesets in the draft
6368 phase to share unfinished work. This can be done by setting a reposi‐
6369 tory to disable publishing in its configuration file:
6370 [phases]
6372 publish = False
6373 See hg help config for more information on configuration files.
6375 Note Servers running older versions of Mercurial are treated as pub‐
6377 lishing.
6378 Note Changesets in secret phase are not exchanged with the server.
6380 This applies to their content: file names, file contents, and
6381 changeset metadata. For technical reasons, the identifier (e.g.
6382 d825e4025e39) of the secret changeset may be communicated to the
6383 server.
6384 Examples
6386 • list changesets in draft or secret phase:
6387 hg log -r "not public()"
6389 • change all secret changesets to draft:
6391 hg phase --draft "secret()"
6393 • forcibly move the current changeset and descendants from public to
6395 draft:
6396 hg phase --force --draft .
6398 • show a list of changeset revisions and each corresponding phase:
6400 hg log --template "{rev} {phase}\n"
6402 • resynchronize draft changesets relative to a remote repository:
6404 hg phase -fd "outgoing(URL)"
6406 See hg help phase for more information on manually manipulating phases.
6408
6410 Mercurial supports several ways to specify revisions.
6411 Specifying single revisions
6413 A plain integer is treated as a revision number. Negative integers are
6414 treated as sequential offsets from the tip, with -1 denoting the tip,
6415 -2 denoting the revision prior to the tip, and so forth.
6416 A 40-digit hexadecimal string is treated as a unique revision identi‐
6418 fier. A hexadecimal string less than 40 characters long is treated as
6419 a unique revision identifier and is referred to as a short-form identi‐
6420 fier. A short-form identifier is only valid if it is the prefix of ex‐
6421 actly one full-length identifier.
6422 Any other string is treated as a bookmark, tag, or branch name. A book‐
6424 mark is a movable pointer to a revision. A tag is a permanent name as‐
6425 sociated with a revision. A branch name denotes the tipmost open branch
6426 head of that branch - or if they are all closed, the tipmost closed
6427 head of the branch. Bookmark, tag, and branch names must not contain
6428 the ":" character.
6429 The reserved name "tip" always identifies the most recent revision.
6431 The reserved name "null" indicates the null revision. This is the revi‐
6433 sion of an empty repository, and the parent of revision 0.
6434 The reserved name "." indicates the working directory parent. If no
6436 working directory is checked out, it is equivalent to null. If an un‐
6437 committed merge is in progress, "." is the revision of the first par‐
6438 ent.
6439 Finally, commands that expect a single revision (like hg update) also
6441 accept revsets (see below for details). When given a revset, they use
6442 the last revision of the revset. A few commands accept two single revi‐
6443 sions (like hg diff). When given a revset, they use the first and the
6444 last revisions of the revset.
6445 Specifying multiple revisions
6447 Mercurial supports a functional language for selecting a set of revi‐
6448 sions. Expressions in this language are called revsets.
6449 The language supports a number of predicates which are joined by infix
6451 operators. Parenthesis can be used for grouping.
6452 Identifiers such as branch names may need quoting with single or double
6454 quotes if they contain characters like - or if they match one of the
6455 predefined predicates.
6456 Special characters can be used in quoted identifiers by escaping them,
6458 e.g., \n is interpreted as a newline. To prevent them from being inter‐
6459 preted, strings can be prefixed with r, e.g. r'...'.
6460 Operators
6462 There is a single prefix operator:
6463 not x
6465 Changesets not in x. Short form is ! x.
6467 These are the supported infix operators:
6469 x::y
6471 A DAG range, meaning all changesets that are descendants of x
6473 and ancestors of y, including x and y themselves. If the first
6474 endpoint is left out, this is equivalent to ancestors(y), if the
6475 second is left out it is equivalent to descendants(x).
6476 An alternative syntax is x..y.
6478 x:y
6480 All changesets with revision numbers between x and y, both in‐
6482 clusive. Either endpoint can be left out, they default to 0 and
6483 tip.
6484 x and y
6486 The intersection of changesets in x and y. Short form is x & y.
6488 x or y
6490 The union of changesets in x and y. There are two alternative
6492 short forms: x | y and x + y.
6493 x - y
6495 Changesets in x but not in y.
6497 x % y
6499 Changesets that are ancestors of x but not ancestors of y (i.e.
6501 ::x - ::y). This is shorthand notation for only(x, y) (see be‐
6502 low). The second argument is optional and, if left out, is
6503 equivalent to only(x).
6504 x^n
6506 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
6508 1, the first parent of each changeset in x; for n == 2, the sec‐
6509 ond parent of changeset in x.
6510 x~n
6512 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
6514 the nth unambiguous descendent of x.
6515 x ## y
6517 Concatenate strings and identifiers into one string.
6519 All other prefix, infix and postfix operators have lower prior‐
6521 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
6522 a2)~2.
6523 For example:
6525 [revsetalias]
6527 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
6528 issue(1234) is equivalent to grep(r'\bissue[
6530 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
6531 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
6532 There is a single postfix operator:
6534 x^
6536 Equivalent to x^1, the first parent of each changeset in x.
6538 Patterns
6540 Where noted, predicates that perform string matching can accept a pat‐
6541 tern string. The pattern may be either a literal, or a regular expres‐
6542 sion. If the pattern starts with re:, the remainder of the pattern is
6543 treated as a regular expression. Otherwise, it is treated as a literal.
6544 To match a pattern that actually starts with re:, use the prefix lit‐
6545 eral:.
6546 Matching is case-sensitive, unless otherwise noted. To perform a case-
6548 insensitive match on a case-sensitive predicate, use a regular expres‐
6549 sion, prefixed with (?i).
6550 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
6552 "Release", etc.
6553 Predicates
6555 The following predicates are supported:
6556 adds(pattern)
6558 Changesets that add a file matching pattern.
6560 The pattern without explicit kind like glob: is expected to be
6562 relative to the current directory and match against a file or a
6563 directory.
6564 all()
6566 All changesets, the same as 0:tip.
6568 ancestor(*changeset)
6570 A greatest common ancestor of the changesets.
6572 Accepts 0 or more changesets. Will return empty list when
6574 passed no args. Greatest common ancestor of a single changeset
6575 is that changeset.
6576 ancestors(set[, depth])
6578 Changesets that are ancestors of changesets in set, including
6580 the given changesets themselves.
6581 If depth is specified, the result only includes changesets up to
6583 the specified generation.
6584 author(string)
6586 Alias for user(string).
6588 bisect(string)
6590 Changesets marked in the specified bisect status:
6592 • good, bad, skip: csets explicitly marked as good/bad/skip
6594 • goods, bads : csets topologically good/bad
6596 • range : csets taking part in the bisection
6598 • pruned : csets that are goods, bads or skipped
6600 • untested : csets whose fate is yet unknown
6602 • ignored : csets ignored due to DAG topology
6604 • current : the cset currently being bisected
6606 bookmark([name])
6608 The named bookmark or all bookmarks.
6610 Pattern matching is supported for name. See hg help revi‐
6612 sions.patterns.
6613 branch(string or set)
6615 All changesets belonging to the given branch or the branches of
6617 the given changesets.
6618 Pattern matching is supported for string. See hg help revi‐
6620 sions.patterns.
6621 branchpoint()
6623 Changesets with more than one child.
6625 bundle()
6627 Changesets in the bundle.
6629 Bundle must be specified by the -R option.
6631 children(set)
6633 Child changesets of changesets in set.
6635 closed()
6637 Changeset is closed.
6639 commonancestors(set)
6641 Changesets that are ancestors of every changeset in set.
6643 conflictlocal()
6645 The local side of the merge, if currently in an unresolved
6647 merge.
6648 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6650 'hg graft'.
6651 conflictother()
6653 The other side of the merge, if currently in an unresolved
6655 merge.
6656 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6658 'hg graft'.
6659 contains(pattern)
6661 The revision's manifest contains a file matching pattern (but
6663 might not modify it). See hg help patterns for information about
6664 file patterns.
6665 The pattern without explicit kind like glob: is expected to be
6667 relative to the current directory and match against a file ex‐
6668 actly for efficiency.
6669 converted([id])
6671 Changesets converted from the given identifier in the old repos‐
6673 itory if present, or all converted changesets if no identifier
6674 is specified.
6675 date(interval)
6677 Changesets within the interval, see hg help dates.
6679 desc(string)
6681 Search commit message for string. The match is case-insensitive.
6683 Pattern matching is supported for string. See hg help revi‐
6685 sions.patterns.
6686 descendants(set[, depth])
6688 Changesets which are descendants of changesets in set, including
6690 the given changesets themselves.
6691 If depth is specified, the result only includes changesets up to
6693 the specified generation.
6694 destination([set])
6696 Changesets that were created by a graft, transplant or rebase
6698 operation, with the given revisions specified as the source.
6699 Omitting the optional set is the same as passing all().
6700 diffcontains(pattern)
6702 Search revision differences for when the pattern was added or
6704 removed.
6705 The pattern may be a substring literal or a regular expression.
6707 See hg help revisions.patterns.
6708 draft()
6710 Changeset in draft phase.
6712 expectsize(set[, size])
6714 Return the given revset if size matches the revset size. Abort
6716 if the revset doesn't expect given size. size can either be an
6717 integer range or an integer.
6718 For example, expectsize(0:1, 3:5) will abort as revset size is 2
6720 and 2 is not between 3 and 5 inclusive.
6721 extra(label, [value])
6723 Changesets with the given label in the extra metadata, with the
6725 given optional value.
6726 Pattern matching is supported for value. See hg help revi‐
6728 sions.patterns.
6729 file(pattern)
6731 Changesets affecting files matched by pattern.
6733 For a faster but less accurate result, consider using filelog()
6735 instead.
6736 This predicate uses glob: as the default kind of pattern.
6738 filelog(pattern)
6740 Changesets connected to the specified filelog.
6742 For performance reasons, visits only revisions mentioned in the
6744 file-level filelog, rather than filtering through all changesets
6745 (much faster, but doesn't include deletes or duplicate changes).
6746 For a slower, more accurate result, use file().
6747 The pattern without explicit kind like glob: is expected to be
6749 relative to the current directory and match against a file ex‐
6750 actly for efficiency.
6751 first(set, [n])
6753 An alias for limit().
6755 follow([file[, startrev]])
6757 An alias for ::. (ancestors of the working directory's first
6759 parent). If file pattern is specified, the histories of files
6760 matching given pattern in the revision given by startrev are
6761 followed, including copies.
6762 followlines(file, fromline:toline[, startrev=., descend=False])
6764 Changesets modifying file in line range ('fromline', 'toline').
6766 Line range corresponds to 'file' content at 'startrev' and
6768 should hence be consistent with file size. If startrev is not
6769 specified, working directory's parent is used.
6770 By default, ancestors of 'startrev' are returned. If 'descend'
6772 is True, descendants of 'startrev' are returned though renames
6773 are (currently) not followed in this direction.
6774 grep(regex)
6776 Like keyword(string) but accepts a regex. Use grep(r'...') to
6778 ensure special escape characters are handled correctly. Unlike
6779 keyword(string), the match is case-sensitive.
6780 head()
6782 Changeset is a named branch head.
6784 heads(set)
6786 Members of set with no children in set.
6788 hidden()
6790 Hidden changesets.
6792 id(string)
6794 Revision non-ambiguously specified by the given hex string pre‐
6796 fix.
6797 keyword(string)
6799 Search commit message, user name, and names of changed files for
6801 string. The match is case-insensitive.
6802 For a regular expression or case sensitive search of these
6804 fields, use grep(regex).
6805 last(set, [n])
6807 Last n members of set, defaulting to 1.
6809 limit(set[, n[, offset]])
6811 First n members of set, defaulting to 1, starting from offset.
6813 matching(revision [, field])
6815 Changesets in which a given set of fields match the set of
6817 fields in the selected revision or set.
6818 To match more than one field pass the list of fields to match
6820 separated by spaces (e.g. author description).
6821 Valid fields are most regular revision fields and some special
6823 fields.
6824 Regular revision fields are description, author, branch, date,
6826 files, phase, parents, substate, user and diff. Note that au‐
6827 thor and user are synonyms. diff refers to the contents of the
6828 revision. Two revisions matching their diff will also match
6829 their files.
6830 Special fields are summary and metadata: summary matches the
6832 first line of the description. metadata is equivalent to match‐
6833 ing description user date (i.e. it matches the main metadata
6834 fields).
6835 metadata is the default field which is used when no fields are
6837 specified. You can match more than one field at a time.
6838 max(set)
6840 Changeset with highest revision number in set.
6842 merge()
6844 Changeset is a merge changeset.
6846 min(set)
6848 Changeset with lowest revision number in set.
6850 modifies(pattern)
6852 Changesets modifying files matched by pattern.
6854 The pattern without explicit kind like glob: is expected to be
6856 relative to the current directory and match against a file or a
6857 directory.
6858 named(namespace)
6860 The changesets in a given namespace.
6862 Pattern matching is supported for namespace. See hg help revi‐
6864 sions.patterns.
6865 nodefromfile(path)
6867 Read a list of nodes from the file at path.
6869 This applies id(LINE) to each line of the file.
6871 This is useful when the amount of nodes you need to specify gets
6873 too large for the command line.
6874 none()
6876 No changesets.
6878 only(set, [set])
6880 Changesets that are ancestors of the first set that are not an‐
6882 cestors of any other head in the repo. If a second set is speci‐
6883 fied, the result is ancestors of the first set that are not an‐
6884 cestors of the second set (i.e. ::<set1> - ::<set2>).
6885 origin([set])
6887 Changesets that were specified as a source for the grafts,
6889 transplants or rebases that created the given revisions. Omit‐
6890 ting the optional set is the same as passing all(). If a
6891 changeset created by these operations is itself specified as a
6892 source for one of these operations, only the source changeset
6893 for the first operation is selected.
6894 outgoing([path])
6896 Changesets not found in the specified destination repository, or
6898 the default push location.
6899 If the location resolve to multiple repositories, the union of
6901 all outgoing changeset will be used.
6902 p1([set])
6904 First parent of changesets in set, or the working directory.
6906 p2([set])
6908 Second parent of changesets in set, or the working directory.
6910 parents([set])
6912 The set of all parents for all changesets in set, or the working
6914 directory.
6915 present(set)
6917 An empty set, if any revision in set isn't found; otherwise, all
6919 revisions in set.
6920 If any of specified revisions is not present in the local repos‐
6922 itory, the query is normally aborted. But this predicate allows
6923 the query to continue even in such cases.
6924 public()
6926 Changeset in public phase.
6928 remote([id [,path]])
6930 Local revision that corresponds to the given identifier in a re‐
6932 mote repository, if present. Here, the '.' identifier is a syn‐
6933 onym for the current local branch.
6934 removes(pattern)
6936 Changesets which remove files matching pattern.
6938 The pattern without explicit kind like glob: is expected to be
6940 relative to the current directory and match against a file or a
6941 directory.
6942 rev(number)
6944 Revision with the given numeric identifier.
6946 reverse(set)
6948 Reverse order of set.
6950 revset(set)
6952 Strictly interpret the content as a revset.
6954 The content of this special predicate will be strictly inter‐
6956 preted as a revset. For example, revset(id(0)) will be inter‐
6957 preted as "id(0)" without possible ambiguity with a "id(0)"
6958 bookmark or tag.
6959 roots(set)
6961 Changesets in set with no parent changeset in set.
6963 secret()
6965 Changeset in secret phase.
6967 sort(set[, [-]key... [, ...]])
6969 Sort set by keys. The default sort order is ascending, specify a
6971 key as -key to sort in descending order.
6972 The keys can be:
6974 • rev for the revision number,
6976 • branch for the branch name,
6978 • desc for the commit message (description),
6980 • user for user name (author can be used as an alias),
6982 • date for the commit date
6984 • topo for a reverse topographical sort
6986 • node the nodeid of the revision
6988 • random randomly shuffle revisions
6990 The topo sort order cannot be combined with other sort keys.
6992 This sort takes one optional argument, topo.firstbranch, which
6993 takes a revset that specifies what topographical branches to
6994 prioritize in the sort.
6995 The random sort takes one optional random.seed argument to con‐
6997 trol the pseudo-randomness of the result.
6998 subrepo([pattern])
7000 Changesets that add, modify or remove the given subrepo. If no
7002 subrepo pattern is named, any subrepo changes are returned.
7003 tag([name])
7005 The specified tag by name, or all tagged revisions if no name is
7007 given.
7008 Pattern matching is supported for name. See hg help revi‐
7010 sions.patterns.
7011 user(string)
7013 User name contains string. The match is case-insensitive.
7015 Pattern matching is supported for string. See hg help revi‐
7017 sions.patterns.
7018 Aliases
7020 New predicates (known as "aliases") can be defined, using any combina‐
7021 tion of existing predicates or other aliases. An alias definition looks
7022 like:
7023 <alias> = <definition>
7025 in the revsetalias section of a Mercurial configuration file. Arguments
7027 of the form a1, a2, etc. are substituted from the alias into the defi‐
7028 nition.
7029 For example,
7031 [revsetalias]
7033 h = heads()
7034 d(s) = sort(s, date)
7035 rs(s, k) = reverse(sort(s, k))
7036 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
7038 equivalent to reverse(sort(0:tip, author)).
7039 Equivalents
7041 Command line equivalents for hg log:
7042 -f -> ::.
7044 -d x -> date(x)
7045 -k x -> keyword(x)
7046 -m -> merge()
7047 -u x -> user(x)
7048 -b x -> branch(x)
7049 -P x -> !::x
7050 -l x -> limit(expr, x)
7051 Examples
7053 Some sample queries:
7054 • Changesets on the default branch:
7056 hg log -r "branch(default)"
7058 • Changesets on the default branch since tag 1.5 (excluding merges):
7060 hg log -r "branch(default) and 1.5:: and not merge()"
7062 • Open branch heads:
7064 hg log -r "head() and not closed()"
7066 • Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
7068 hgext/*:
7069 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
7071 • Changesets committed in May 2008, sorted by user:
7073 hg log -r "sort(date('May 2008'), user)"
7075 • Changesets mentioning "bug" or "issue" that are not in a tagged re‐
7077 lease:
7078 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
7080 • Update to the commit that bookmark @ is pointing to, without activat‐
7082 ing the bookmark (this works because the last revision of the revset
7083 is used):
7084 hg update :@
7086 • Show diff between tags 1.3 and 1.5 (this works because the first and
7088 the last revisions of the revset are used):
7089 hg diff -r 1.3::1.5
7091
7093 Mercurial can be augmented with Rust extensions for speeding up certain
7094 operations.
7095 Compatibility
7097 Though the Rust extensions are only tested by the project under Linux,
7098 users of MacOS, FreeBSD and other UNIX-likes have been using the Rust
7099 extensions. Your mileage may vary, but by all means do give us feedback
7100 or signal your interest for better support.
7101 No Rust extensions are available for Windows at this time.
7103 Features
7105 The following operations are sped up when using Rust:
7106 • discovery of differences between repositories (pull/push)
7108 • nodemap (see hg help config.format.use-persistent-nodemap)
7110 • all commands using the dirstate (status, commit, diff, add, up‐
7112 date, etc.)
7113 • dirstate-v2 (see hg help config.format.use-dirstate-v2)
7115 • iteration over ancestors in a graph
7117 More features are in the works, and improvements on the above listed
7119 are still in progress. For more experimental work see the "rhg" sec‐
7120 tion.
7121 Checking for Rust
7123 You may already have the Rust extensions depending on how you install
7124 Mercurial:
7125 $ hg debuginstall | grep -i rust
7127 checking Rust extensions (installed)
7128 checking module policy (rust+c-allow)
7129 If those lines don't even exist, you're using an old version of hg
7131 which does not have any Rust extensions yet.
7132 Installing
7134 You will need cargo to be in your $PATH. See the "MSRV" section for
7135 which version to use.
7136 Using pip
7138 Users of pip can install the Rust extensions with the following com‐
7139 mand:
7140 $ pip install mercurial --global-option --rust --no-use-pep517
7142 --no-use-pep517 is here to tell pip to preserve backwards compatibility
7144 with the legacy setup.py system. Mercurial has not yet migrated its
7145 complex setup to the new system, so we still need this to add compiled
7146 extensions.
7147 This might take a couple of minutes because you're compiling every‐
7149 thing.
7150 See the "Checking for Rust" section to see if the install succeeded.
7152 From your distribution
7154 Some distributions are shipping Mercurial with Rust extensions enabled
7155 and pre-compiled (meaning you won't have to install cargo), or allow
7156 you to specify an install flag. Check with your specific distribution
7157 for how to do that, or ask their team to add support for hg+Rust!
7158 From source
7160 Please refer to the rust/README.rst file in the Mercurial repository
7161 for instructions on how to install from source.
7162 MSRV
7164 The minimum supported Rust version is currently 1.48.0. The project's
7165 policy is to follow the version from Debian stable, to make the distri‐
7166 butions' job easier.
7167 rhg
7169 There exists an experimental pure-Rust version of Mercurial called rhg
7170 with a fallback mechanism for unsupported invocations. It allows for
7171 much faster execution of certain commands while adding no discernable
7172 overhead for the rest.
7173 The only way of trying it out is by building it from source. Please re‐
7175 fer to rust/README.rst in the Mercurial repository.
7176 See hg help config.rhg for configuration options.
7178 Contributing
7180 If you would like to help the Rust endeavor, please refer to
7181 rust/README.rst in the Mercurial repository.
7182
7184 It is common for machines (as opposed to humans) to consume Mercurial.
7185 This help topic describes some of the considerations for interfacing
7186 machines with Mercurial.
7187 Choosing an Interface
7189 Machines have a choice of several methods to interface with Mercurial.
7190 These include:
7191 • Executing the hg process
7193 • Querying a HTTP server
7195 • Calling out to a command server
7197 Executing hg processes is very similar to how humans interact with Mer‐
7199 curial in the shell. It should already be familiar to you.
7200 hg serve can be used to start a server. By default, this will start a
7202 "hgweb" HTTP server. This HTTP server has support for machine-readable
7203 output, such as JSON. For more, see hg help hgweb.
7204 hg serve can also start a "command server." Clients can connect to this
7206 server and issue Mercurial commands over a special protocol. For more
7207 details on the command server, including links to client libraries, see
7208 https://www.mercurial-scm.org/wiki/CommandServer.
7209 hg serve based interfaces (the hgweb and command servers) have the ad‐
7211 vantage over simple hg process invocations in that they are likely more
7212 efficient. This is because there is significant overhead to spawn new
7213 Python processes.
7214 Tip If you need to invoke several hg processes in short order and/or
7216 performance is important to you, use of a server-based interface
7217 is highly recommended.
7218 Environment Variables
7220 As documented in hg help environment, various environment variables in‐
7221 fluence the operation of Mercurial. The following are particularly rel‐
7222 evant for machines consuming Mercurial:
7223 HGPLAIN
7225 If not set, Mercurial's output could be influenced by configura‐
7226 tion settings that impact its encoding, verbose mode, localiza‐
7227 tion, etc.
7228 It is highly recommended for machines to set this variable when
7230 invoking hg processes.
7231 HGENCODING
7233 If not set, the locale used by Mercurial will be detected from
7234 the environment. If the determined locale does not support dis‐
7235 play of certain characters, Mercurial may render these character
7236 sequences incorrectly (often by using "?" as a placeholder for
7237 invalid characters in the current locale).
7238 Explicitly setting this environment variable is a good practice
7240 to guarantee consistent results. "utf-8" is a good choice on
7241 UNIX-like environments.
7242 HGRCPATH
7244 If not set, Mercurial will inherit config options from config
7245 files using the process described in hg help config. This in‐
7246 cludes inheriting user or system-wide config files.
7247 When utmost control over the Mercurial configuration is desired,
7249 the value of HGRCPATH can be set to an explicit file with known
7250 good configs. In rare cases, the value can be set to an empty
7251 file or the null device (often /dev/null) to bypass loading of
7252 any user or system config files. Note that these approaches can
7253 have unintended consequences, as the user and system config
7254 files often define things like the username and extensions that
7255 may be required to interface with a repository.
7256 HGRCSKIPREPO
7258 When set, the .hg/hgrc from repositories are not read.
7259 Note that not reading the repository's configuration can have
7261 unintended consequences, as the repository config files can de‐
7262 fine things like extensions that are required for access to the
7263 repository.
7264 Command-line Flags
7266 Mercurial's default command-line parser is designed for humans, and is
7267 not robust against malicious input. For instance, you can start a de‐
7268 bugger by passing --debugger as an option value:
7269 $ REV=--debugger sh -c 'hg log -r "$REV"'
7271 This happens because several command-line flags need to be scanned
7273 without using a concrete command table, which may be modified while
7274 loading repository settings and extensions.
7275 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
7277 setting HGPLAIN=+strictflags. When this feature is enabled, all early
7278 options (e.g. -R/--repository, --cwd, --config) must be specified first
7279 amongst the other global options, and cannot be injected to an arbi‐
7280 trary location:
7281 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
7283 In earlier Mercurial versions where +strictflags isn't available, you
7285 can mitigate the issue by concatenating an option value with its flag:
7286 $ hg log -r"$REV" --keyword="$KEYWORD"
7288 Consuming Command Output
7290 It is common for machines to need to parse the output of Mercurial com‐
7291 mands for relevant data. This section describes the various techniques
7292 for doing so.
7293 Parsing Raw Command Output
7295 Likely the simplest and most effective solution for consuming command
7296 output is to simply invoke hg commands as you would as a user and parse
7297 their output.
7298 The output of many commands can easily be parsed with tools like grep,
7300 sed, and awk.
7301 A potential downside with parsing command output is that the output of
7303 commands can change when Mercurial is upgraded. While Mercurial does
7304 generally strive for strong backwards compatibility, command output
7305 does occasionally change. Having tests for your automated interactions
7306 with hg commands is generally recommended, but is even more important
7307 when raw command output parsing is involved.
7308 Using Templates to Control Output
7310 Many hg commands support templatized output via the -T/--template argu‐
7311 ment. For more, see hg help templates.
7312 Templates are useful for explicitly controlling output so that you get
7314 exactly the data you want formatted how you want it. For example, log
7315 -T {node}\n can be used to print a newline delimited list of changeset
7316 nodes instead of a human-tailored output containing authors, dates, de‐
7317 scriptions, etc.
7318 Tip If parsing raw command output is too complicated, consider using
7320 templates to make your life easier.
7321 The -T/--template argument allows specifying pre-defined styles. Mer‐
7323 curial ships with the machine-readable styles cbor, json, and xml,
7324 which provide CBOR, JSON, and XML output, respectively. These are use‐
7325 ful for producing output that is machine readable as-is.
7326 (Mercurial 5.0 is required for CBOR style.)
7328 Important
7330 The json and xml styles are considered experimental. While they
7331 may be attractive to use for easily obtaining machine-readable
7332 output, their behavior may change in subsequent versions.
7333 These styles may also exhibit unexpected results when dealing
7335 with certain encodings. Mercurial treats things like filenames
7336 as a series of bytes and normalizing certain byte sequences to
7337 JSON or XML with certain encoding settings can lead to sur‐
7338 prises.
7339 Command Server Output
7341 If using the command server to interact with Mercurial, you are likely
7342 using an existing library/API that abstracts implementation details of
7343 the command server. If so, this interface layer may perform parsing for
7344 you, saving you the work of implementing it yourself.
7345 Output Verbosity
7347 Commands often have varying output verbosity, even when machine read‐
7348 able styles are being used (e.g. -T json). Adding -v/--verbose and
7349 --debug to the command's arguments can increase the amount of data ex‐
7350 posed by Mercurial.
7351 An alternate way to get the data you need is by explicitly specifying a
7353 template.
7354 Other Topics
7356 revsets
7357 Revisions sets is a functional query language for selecting a
7358 set of revisions. Think of it as SQL for Mercurial repositories.
7359 Revsets are useful for querying repositories for specific data.
7360 See hg help revsets for more.
7362 share extension
7364 The share extension provides functionality for sharing reposi‐
7365 tory data across several working copies. It can even automati‐
7366 cally "pool" storage for logically related repositories when
7367 cloning.
7368 Configuring the share extension can lead to significant resource
7370 utilization reduction, particularly around disk space and the
7371 network. This is especially true for continuous integration (CI)
7372 environments.
7373 See hg help -e share for more.
7375
7377 Subrepositories let you nest external repositories or projects into a
7378 parent Mercurial repository, and make commands operate on them as a
7379 group.
7380 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
7382 tories.
7383 Subrepositories are made of three components:
7385 1. Nested repository checkouts. They can appear anywhere in the parent
7387 working directory.
7388 2. Nested repository references. They are defined in .hgsub, which
7390 should be placed in the root of working directory, and tell where
7391 the subrepository checkouts come from. Mercurial subrepositories are
7392 referenced like:
7393 path/to/nested = https://example.com/nested/repo/path
7395 Git and Subversion subrepos are also supported:
7397 path/to/nested = [git]git://example.com/nested/repo/path
7399 path/to/nested = [svn]https://example.com/nested/trunk/path
7400 where path/to/nested is the checkout location relatively to the par‐
7402 ent Mercurial root, and https://example.com/nested/repo/path is the
7403 source repository path. The source can also reference a filesystem
7404 path.
7405 Note that .hgsub does not exist by default in Mercurial reposito‐
7407 ries, you have to create and add it to the parent repository before
7408 using subrepositories.
7409 3. Nested repository states. They are defined in .hgsubstate, which is
7411 placed in the root of working directory, and capture whatever infor‐
7412 mation is required to restore the subrepositories to the state they
7413 were committed in a parent repository changeset. Mercurial automati‐
7414 cally record the nested repositories states when committing in the
7415 parent repository.
7416 Note
7418 The .hgsubstate file should not be edited manually.
7419 Adding a Subrepository
7421 If .hgsub does not exist, create it and add it to the parent reposi‐
7422 tory. Clone or checkout the external projects where you want it to live
7423 in the parent repository. Edit .hgsub and add the subrepository entry
7424 as described above. At this point, the subrepository is tracked and the
7425 next commit will record its state in .hgsubstate and bind it to the
7426 committed changeset.
7427 Synchronizing a Subrepository
7429 Subrepos do not automatically track the latest changeset of their
7430 sources. Instead, they are updated to the changeset that corresponds
7431 with the changeset checked out in the top-level changeset. This is so
7432 developers always get a consistent set of compatible code and libraries
7433 when they update.
7434 Thus, updating subrepos is a manual process. Simply check out target
7436 subrepo at the desired revision, test in the top-level repo, then com‐
7437 mit in the parent repository to record the new combination.
7438 Deleting a Subrepository
7440 To remove a subrepository from the parent repository, delete its refer‐
7441 ence from .hgsub, then remove its files.
7442 Interaction with Mercurial Commands
7444 add add does not recurse in subrepos unless -S/--subrepos is speci‐
7445 fied. However, if you specify the full path of a file in a sub‐
7446 repo, it will be added even without -S/--subrepos specified.
7447 Subversion subrepositories are currently silently ignored.
7448 addremove
7450 addremove does not recurse into subrepos unless -S/--subrepos is
7451 specified. However, if you specify the full path of a directory
7452 in a subrepo, addremove will be performed on it even without
7453 -S/--subrepos being specified. Git and Subversion subreposito‐
7454 ries will print a warning and continue.
7455 archive
7457 archive does not recurse in subrepositories unless -S/--subrepos
7458 is specified.
7459 cat Git subrepositories only support exact file matches. Subversion
7461 subrepositories are currently ignored.
7462 commit commit creates a consistent snapshot of the state of the entire
7464 project and its subrepositories. If any subrepositories have
7465 been modified, Mercurial will abort. Mercurial can be made to
7466 instead commit all modified subrepositories by specifying
7467 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
7468 ration file (see hg help config). After there are no longer any
7469 modified subrepositories, it records their state and finally
7470 commits it in the parent repository. The --addremove option
7471 also honors the -S/--subrepos option. However, Git and Subver‐
7472 sion subrepositories will print a warning and abort.
7473 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
7475 fied. However, if you specify the full path of a file or direc‐
7476 tory in a subrepo, it will be diffed even without -S/--subrepos
7477 being specified. Subversion subrepositories are currently
7478 silently ignored.
7479 files files does not recurse into subrepos unless -S/--subrepos is
7481 specified. However, if you specify the full path of a file or
7482 directory in a subrepo, it will be displayed even without
7483 -S/--subrepos being specified. Git and Subversion subreposito‐
7484 ries are currently silently ignored.
7485 forget forget currently only handles exact file matches in subrepos.
7487 Git and Subversion subrepositories are currently silently ig‐
7488 nored.
7489 incoming
7491 incoming does not recurse in subrepos unless -S/--subrepos is
7492 specified. Git and Subversion subrepositories are currently
7493 silently ignored.
7494 outgoing
7496 outgoing does not recurse in subrepos unless -S/--subrepos is
7497 specified. Git and Subversion subrepositories are currently
7498 silently ignored.
7499 pull pull is not recursive since it is not clear what to pull prior
7501 to running hg update. Listing and retrieving all subrepositories
7502 changes referenced by the parent repository pulled changesets is
7503 expensive at best, impossible in the Subversion case.
7504 push Mercurial will automatically push all subrepositories first when
7506 the parent repository is being pushed. This ensures new sub‐
7507 repository changes are available when referenced by top-level
7508 repositories. Push is a no-op for Subversion subrepositories.
7509 serve serve does not recurse into subrepositories unless -S/--subrepos
7511 is specified. Git and Subversion subrepositories are currently
7512 silently ignored.
7513 status status does not recurse into subrepositories unless -S/--subre‐
7515 pos is specified. Subrepository changes are displayed as regular
7516 Mercurial changes on the subrepository elements. Subversion sub‐
7517 repositories are currently silently ignored.
7518 remove remove does not recurse into subrepositories unless -S/--subre‐
7520 pos is specified. However, if you specify a file or directory
7521 path in a subrepo, it will be removed even without -S/--subre‐
7522 pos. Git and Subversion subrepositories are currently silently
7523 ignored.
7524 update update restores the subrepos in the state they were originally
7526 committed in target changeset. If the recorded changeset is not
7527 available in the current subrepository, Mercurial will pull it
7528 in first before updating. This means that updating can require
7529 network access when using subrepositories.
7530 Remapping Subrepositories Sources
7532 A subrepository source location may change during a project life, in‐
7533 validating references stored in the parent repository history. To fix
7534 this, rewriting rules can be defined in parent repository hgrc file or
7535 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
7536 more details.
7537
7539 Mercurial allows you to customize output of commands through templates.
7540 You can either pass in a template or select an existing template-style
7541 from the command line, via the --template option.
7542 You can customize output for any "log-like" command: log, outgoing, in‐
7544 coming, tip, parents, and heads.
7545 Some built-in styles are packaged with Mercurial. These can be listed
7547 with hg log --template list. Example usage:
7548 $ hg log -r1.0::1.1 --template changelog
7550 A template is a piece of text, with markup to invoke variable expan‐
7552 sion:
7553 $ hg log -r1 --template "{node}\n"
7555 b56ce7b07c52de7d5fd79fb89701ea538af65746
7556 Keywords
7558 Strings in curly braces are called keywords. The availability of key‐
7559 words depends on the exact context of the templater. These keywords are
7560 usually available for templating a log-like command:
7561 _fast_rank
7563 the rank of a changeset if cached
7564 The rank of a revision is the size of the sub-graph it defines
7566 as a head. Equivalently, the rank of a revision r is the size
7567 of the set ancestors(r), r included.
7568 activebookmark
7570 String. The active bookmark, if it is associated with the
7571 changeset.
7572 author Alias for {user}
7574 bisect String. The changeset bisection status.
7576 bookmarks
7578 List of strings. Any bookmarks associated with the changeset.
7579 Also sets 'active', the name of the active bookmark.
7580 branch String. The name of the branch on which the changeset was com‐
7582 mitted.
7583 changessincelatesttag
7585 Integer. All ancestors not in the latest tag.
7586 children
7588 List of strings. The children of the changeset.
7589 date Date information. The date when the changeset was committed.
7591 desc String. The text of the changeset description.
7593 diffstat
7595 String. Statistics of changes with the following format: "modi‐
7596 fied files: +added/-removed lines"
7597 extras List of dicts with key, value entries of the 'extras' field of
7599 this changeset.
7600 file_adds
7602 List of strings. Files added by this changeset.
7603 file_copies
7605 List of strings. Files copied in this changeset with their
7606 sources.
7607 file_copies_switch
7609 List of strings. Like "file_copies" but displayed only if the
7610 --copied switch is set.
7611 file_dels
7613 List of strings. Files removed by this changeset.
7614 file_mods
7616 List of strings. Files modified by this changeset.
7617 files List of strings. All files modified, added, or removed by this
7619 changeset.
7620 graphnode
7622 String. The character representing the changeset node in an
7623 ASCII revision graph.
7624 graphwidth
7626 Integer. The width of the graph drawn by 'log --graph' or zero.
7627 index Integer. The current iteration of the loop. (0 indexed)
7629 latesttag
7631 List of strings. The global tags on the most recent globally
7632 tagged ancestor of this changeset. If no such tags exist, the
7633 list consists of the single string "null".
7634 latesttagdistance
7636 Integer. Longest path to the latest tag.
7637 namespaces
7639 Dict of lists. Names attached to this changeset per namespace.
7640 negrev Integer. The repository-local changeset negative revision num‐
7642 ber, which counts in the opposite direction.
7643 node String. The changeset identification hash, as a 40 hexadecimal
7645 digit string.
7646 onelinesummary
7648 String. A one-line summary for the ctx (not including trailing
7649 newline). The default template be overridden in command-tem‐
7650 plates.oneline-summary.
7651 p1 Changeset. The changeset's first parent. {p1.rev} for the revi‐
7653 sion number, and {p1.node} for the identification hash.
7654 p2 Changeset. The changeset's second parent. {p2.rev} for the revi‐
7656 sion number, and {p2.node} for the identification hash.
7657 parents
7659 List of strings. The parents of the changeset in "rev:node" for‐
7660 mat. If the changeset has only one "natural" parent (the prede‐
7661 cessor revision) nothing is shown.
7662 peerurls
7664 A dictionary of repository locations defined in the [paths] sec‐
7665 tion of your configuration file.
7666 phase String. The changeset phase name.
7668 reporoot
7670 String. The root directory of the current repository.
7671 rev Integer. The repository-local changeset revision number.
7673 subrepos
7675 List of strings. Updated subrepositories in the changeset.
7676 tags List of strings. Any tags associated with the changeset.
7678 termwidth
7680 Integer. The width of the current terminal.
7681 user String. The unmodified author of the changeset.
7683 verbosity
7685 String. The current output verbosity in 'debug', 'quiet', 'ver‐
7686 bose', or ''.
7687 The "date" keyword does not produce human-readable output. If you want
7689 to use a date in your output, you can use a filter to process it. Fil‐
7690 ters are functions which return a string based on the input variable.
7691 Be sure to use the stringify filter first when you're applying a
7692 string-input filter to a list-like input variable. You can also use a
7693 chain of filters to get the desired output:
7694 $ hg tip --template "{date|isodate}\n"
7696 2008-08-21 18:22 +0000
7697 Filters
7699 List of filters:
7700 addbreaks
7702 Any text. Add an XHTML "<br />" tag before the end of every line
7703 except the last.
7704 age Date. Returns a human-readable date/time difference between the
7706 given date/time and the current date/time.
7707 basename
7709 Any text. Treats the text as a path, and returns the last compo‐
7710 nent of the path after splitting by the path separator. For ex‐
7711 ample, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
7712 cbor Any object. Serializes the object to CBOR bytes.
7714 commondir
7716 List of text. Treats each list item as file name with / as path
7717 separator and returns the longest common directory prefix shared
7718 by all list items. Returns the empty string if no common prefix
7719 exists.
7720 The list items are not normalized, i.e. "foo/../bar" is handled
7722 as file "bar" in the directory "foo/..". Leading slashes are ig‐
7723 nored.
7724 For example, ["foo/bar/baz", "foo/baz/bar"] becomes "foo" and
7726 ["foo/bar", "baz"] becomes "".
7727 count List or text. Returns the length as an integer.
7729 dirname
7731 Any text. Treats the text as a path, and strips the last compo‐
7732 nent of the path after splitting by the path separator.
7733 domain Any text. Finds the first string that looks like an email ad‐
7735 dress, and extracts just the domain component. Example: User
7736 <user@example.com> becomes example.com.
7737 email Any text. Extracts the first string that looks like an email ad‐
7739 dress. Example: User <user@example.com> becomes user@exam‐
7740 ple.com.
7741 emailuser
7743 Any text. Returns the user portion of an email address.
7744 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
7746 ">" with XML entities, and filters out NUL characters.
7747 fill68 Any text. Wraps the text to fit in 68 columns.
7749 fill76 Any text. Wraps the text to fit in 76 columns.
7751 firstline
7753 Any text. Returns the first line of text.
7754 hex Any text. Convert a binary Mercurial node identifier into its
7756 long hexadecimal representation.
7757 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
7759 (Unix timestamp, timezone offset).
7760 isodate
7762 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
7763 +0200".
7764 isodatesec
7766 Date. Returns the date in ISO 8601 format, including seconds:
7767 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
7768 json Any object. Serializes the object to a JSON formatted text.
7770 lower Any text. Converts the text to lowercase.
7772 nonempty
7774 Any text. Returns '(none)' if the string is empty.
7775 obfuscate
7777 Any text. Returns the input text rendered as a sequence of XML
7778 entities.
7779 person Any text. Returns the name before an email address, interpreting
7781 it as per RFC 5322.
7782 reverse
7784 List. Reverses the order of list items.
7785 revescape
7787 Any text. Escapes all "special" characters, except @. Forward
7788 slashes are escaped twice to prevent web servers from prema‐
7789 turely unescaping them. For example, "@foo bar/baz" becomes
7790 "@foo%20bar%252Fbaz".
7791 rfc3339date
7793 Date. Returns a date using the Internet date format specified in
7794 RFC 3339: "2009-08-18T13:00:13+02:00".
7795 rfc822date
7797 Date. Returns a date using the same format used in email head‐
7798 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
7799 short Changeset hash. Returns the short form of a changeset hash, i.e.
7801 a 12 hexadecimal digit string.
7802 shortbisect
7804 Any text. Treats label as a bisection status, and returns a sin‐
7805 gle-character representing the status (G: good, B: bad, S:
7806 skipped, U: untested, I: ignored). Returns single space if text
7807 is not a valid bisection status.
7808 shortdate
7810 Date. Returns a date like "2006-09-18".
7811 slashpath
7813 Any text. Replaces the native path separator with slash.
7814 splitlines
7816 Any text. Split text into a list of lines.
7817 stringify
7819 Any type. Turns the value into text by converting values into
7820 text and concatenating them.
7821 stripdir
7823 Treat the text as path and strip a directory level, if possible.
7824 For example, "foo" and "foo/bar" becomes "foo".
7825 tabindent
7827 Any text. Returns the text, with every non-empty line except the
7828 first starting with a tab character.
7829 upper Any text. Converts the text to uppercase.
7831 urlescape
7833 Any text. Escapes all "special" characters. For example, "foo
7834 bar" becomes "foo%20bar".
7835 user Any text. Returns a short representation of a user name or email
7837 address.
7838 utf8 Any text. Converts from the local character encoding to UTF-8.
7840 Note that a filter is nothing more than a function call, i.e.
7842 expr|filter is equivalent to filter(expr).
7843 Functions
7845 In addition to filters, there are some basic built-in functions:
7846 config(section, name[, default])
7848 Returns the requested hgrc config option as a string.
7849 configbool(section, name[, default])
7851 Returns the requested hgrc config option as a boolean.
7852 configint(section, name[, default])
7854 Returns the requested hgrc config option as an integer.
7855 date(date[, fmt])
7857 Format a date. See hg help dates for formatting strings. The de‐
7858 fault is a Unix date format, including the timezone: "Mon Sep 04
7859 15:13:13 2006 0700".
7860 dict([[key=]value...])
7862 Construct a dict from key-value pairs. A key may be omitted if a
7863 value expression can provide an unambiguous name.
7864 diff([includepattern [, excludepattern]])
7866 Show a diff, optionally specifying files to include or exclude.
7867 files(pattern)
7869 All files of the current changeset matching the pattern. See hg
7870 help patterns.
7871 fill(text[, width[, initialident[, hangindent]]])
7873 Fill many paragraphs with optional indentation. See the "fill"
7874 filter.
7875 filter(iterable[, expr])
7877 Remove empty elements from a list or a dict. If expr specified,
7878 it's applied to each element to test emptiness.
7879 get(dict, key)
7881 Get an attribute/key from an object. Some keywords are complex
7882 types. This function allows you to obtain the value of an attri‐
7883 bute on these types.
7884 if(expr, then[, else])
7886 Conditionally execute based on the result of an expression.
7887 ifcontains(needle, haystack, then[, else])
7889 Conditionally execute based on whether the item "needle" is in
7890 "haystack".
7891 ifeq(expr1, expr2, then[, else])
7893 Conditionally execute based on whether 2 items are equivalent.
7894 indent(text, indentchars[, firstline])
7896 Indents all non-empty lines with the characters given in the in‐
7897 dentchars string. An optional third parameter will override the
7898 indent for the first line only if present.
7899 join(list, sep)
7901 Join items in a list with a delimiter.
7902 label(label, expr)
7904 Apply a label to generated content. Content with a label applied
7905 can result in additional post-processing, such as automatic col‐
7906 orization.
7907 latesttag([pattern])
7909 The global tags matching the given pattern on the most recent
7910 globally tagged ancestor of this changeset. If no such tags ex‐
7911 ist, the "{tag}" template resolves to the string "null". See hg
7912 help revisions.patterns for the pattern syntax.
7913 localdate(date[, tz])
7915 Converts a date to the specified timezone. The default is local
7916 date.
7917 mailmap(author)
7919 Return the author, updated according to the value set in the
7920 .mailmap file
7921 max(iterable)
7923 Return the max of an iterable
7924 min(iterable)
7926 Return the min of an iterable
7927 mod(a, b)
7929 Calculate a mod b such that a / b + a mod b == a
7930 pad(text, width[, fillchar=' '[, left=False[, truncate=False]]])
7932 Pad text with a fill character.
7933 relpath(path)
7935 Convert a repository-absolute path into a filesystem path rela‐
7936 tive to the current working directory.
7937 revset(query[, formatargs...])
7939 Execute a revision set query. See hg help revset.
7940 rstdoc(text, style)
7942 Format reStructuredText.
7943 search(pattern, text)
7945 Look for the first text matching the regular expression pattern.
7946 Groups are accessible as {1}, {2}, ... in %-mapped template.
7947 separate(sep, args...)
7949 Add a separator between non-empty arguments.
7950 shortest(node, minlength=4)
7952 Obtain the shortest representation of a node.
7953 startswith(pattern, text)
7955 Returns the value from the "text" argument if it begins with the
7956 content from the "pattern" argument.
7957 strip(text[, chars])
7959 Strip characters from a string. By default, strips all leading
7960 and trailing whitespace.
7961 sub(pattern, replacement, expression)
7963 Perform text substitution using regular expressions.
7964 subsetparents(rev, revset)
7966 Look up parents of the rev in the sub graph given by the revset.
7967 word(number, text[, separator])
7969 Return the nth word from a string.
7970 Operators
7972 We provide a limited set of infix arithmetic operations on integers:
7973 + for addition
7975 - for subtraction
7976 * for multiplication
7977 / for floor division (division rounded to integer nearest -infinity)
7978 Division fulfills the law x = x / y + mod(x, y).
7980 Also, for any expression that returns a list, there is a list operator:
7982 expr % "{template}"
7984 As seen in the above example, {template} is interpreted as a template.
7986 To prevent it from being interpreted, you can use an escape character
7987 \{ or a raw string prefix, r'...'.
7988 The dot operator can be used as a shorthand for accessing a sub item:
7990 • expr.member is roughly equivalent to expr % '{member}' if expr re‐
7992 turns a non-list/dict. The returned value is not stringified.
7993 • dict.key is identical to get(dict, 'key').
7995 Aliases
7997 New keywords and functions can be defined in the templatealias section
7998 of a Mercurial configuration file:
7999 <alias> = <definition>
8001 Arguments of the form a1, a2, etc. are substituted from the alias into
8003 the definition.
8004 For example,
8006 [templatealias]
8008 r = rev
8009 rn = "{r}:{node|short}"
8010 leftpad(s, w) = pad(s, w, ' ', True)
8011 defines two symbol aliases, r and rn, and a function alias leftpad().
8013 It's also possible to specify complete template strings, using the tem‐
8015 plates section. The syntax used is the general template string syntax.
8016 For example,
8018 [templates]
8020 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
8021 defines a template, nodedate, which can be called like:
8023 $ hg log -r . -Tnodedate
8025 A template defined in templates section can also be referenced from an‐
8027 other template:
8028 $ hg log -r . -T "{rev} {nodedate}"
8030 but be aware that the keywords cannot be overridden by templates. For
8032 example, a template defined as templates.rev cannot be referenced as
8033 {rev}.
8034 A template defined in templates section may have sub templates which
8036 are inserted before/after/between items:
8037 [templates]
8039 myjson = ' {dict(rev, node|short)|json}'
8040 myjson:docheader = '\{\n'
8041 myjson:docfooter = '\n}\n'
8042 myjson:separator = ',\n'
8043 Examples
8045 Some sample command line templates:
8046 • Format lists, e.g. files:
8048 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
8050 • Join the list of files with a ", ":
8052 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
8054 • Join the list of files ending with ".py" with a ", ":
8056 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
8058 • Separate non-empty arguments by a " ":
8060 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
8062 • Modify each line of a commit description:
8064 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
8066 • Format date:
8068 $ hg log -r 0 --template "{date(date, '%Y')}\n"
8070 • Display date in UTC:
8072 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
8074 • Output the description set to a fill-width of 30:
8076 $ hg log -r 0 --template "{fill(desc, 30)}"
8078 • Use a conditional to test for the default branch:
8080 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
8082 'on branch {branch}')}\n"
8083 • Append a newline if not empty:
8085 $ hg tip --template "{if(author, '{author}\n')}"
8087 • Label the output for use with the color extension:
8089 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
8091 • Invert the firstline filter, i.e. everything but the first line:
8093 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
8095 • Display the contents of the 'extra' field, one per line:
8097 $ hg log -r 0 --template "{join(extras, '\n')}\n"
8099 • Mark the active bookmark with '*':
8101 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
8103 • Find the previous release candidate tag, the distance and changes
8105 since the tag:
8106 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
8108 • Mark the working copy parent with '@':
8110 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
8112 • Show details of parent revisions:
8114 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
8116 • Show only commit descriptions that start with "template":
8118 $ hg log --template "{startswith('template', firstline(desc))}\n"
8120 • Print the first word of each line of a commit message:
8122 $ hg log --template "{word(0, desc)}\n"
8124
8126 Valid URLs are of the form:
8127 local/filesystem/path[#revision]
8129 file://local/filesystem/path[#revision]
8130 http://[user[:pass]@]host[:port]/[path][#revision]
8131 https://[user[:pass]@]host[:port]/[path][#revision]
8132 ssh://[user@]host[:port]/[path][#revision]
8133 path://pathname
8134 Paths in the local filesystem can either point to Mercurial reposito‐
8136 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
8137 dle). See also hg help paths.
8138 An optional identifier after # indicates a particular branch, tag, or
8140 changeset to use from the remote repository. See also hg help revisions
8141 .
8142 Some features, such as pushing to http:// and https:// URLs are only
8144 possible if the feature is explicitly enabled on the remote Mercurial
8145 server.
8146 Note that the security of HTTPS URLs depends on proper configuration of
8148 web.cacerts.
8149 Some notes about using SSH with Mercurial:
8151 • SSH requires an accessible shell account on the destination machine
8153 and a copy of hg in the remote path or specified with remotecmd.
8154 • path is relative to the remote user's home directory by default. Use
8156 an extra slash at the start of a path to specify an absolute path:
8157 ssh://example.com//tmp/repository
8159 • Mercurial doesn't use its own compression via SSH; the right thing to
8161 do is to configure it in your ~/.ssh/config, e.g.:
8162 Host *.mylocalnetwork.example.com
8164 Compression no
8165 Host *
8166 Compression yes
8167 Alternatively specify "ssh -C" as your ssh command in your configura‐
8169 tion file or with the --ssh command line option.
8170 These URLs can all be stored in your configuration file with path
8172 aliases under the [paths] section like so:
8173 [paths]
8175 alias1 = URL1
8176 alias2 = URL2
8177 ...
8178 You can then use the alias for any command that uses a URL (for example
8180 hg pull alias1 will be treated as hg pull URL1).
8181 Two path aliases are special because they are used as defaults when you
8183 do not provide the URL to a command:
8184 default:
8186 When you create a repository with hg clone, the clone command
8187 saves the location of the source repository as the new reposi‐
8188 tory's 'default' path. This is then used when you omit path from
8189 push- and pull-like commands (including incoming and outgoing).
8190 default-push:
8192 The push command will look for a path named 'default-push', and
8193 prefer it over 'default' if both are defined.
8194 These alias can also be use in the path:// scheme:
8196 [paths]
8198 alias1 = URL1
8199 alias2 = path://alias1
8200 ...
8201 check hg help config.paths for details about the behavior of such
8203 "sub-path".
8204
8206 This section contains help for extensions that are distributed together
8207 with Mercurial. Help for other extensions is available in the help sys‐
8208 tem.
8209 absorb
8211 apply working directory changes to changesets (EXPERIMENTAL)
8212 The absorb extension provides a command to use annotate information to
8214 amend modified chunks into the corresponding non-public changesets.
8215 [absorb]
8217 # only check 50 recent non-public changesets at most
8218 max-stack-size = 50
8219 # whether to add noise to new commits to avoid obsolescence cycle
8220 add-noise = 1
8221 # make `amend --correlated` a shortcut to the main command
8222 amend-flag = correlated
8223 [color]
8225 absorb.description = yellow
8226 absorb.node = blue bold
8227 absorb.path = bold
8228 Commands
8230 Change creation
8231 absorb
8232 incorporate corrections into the stack of draft changesets:
8233 hg absorb [OPTION] [FILE]...
8235 absorb analyzes each change in your working directory and attempts to
8237 amend the changed lines into the changesets in your stack that first
8238 introduced those lines.
8239 If absorb cannot find an unambiguous changeset to amend for a change,
8241 that change will be left in the working directory, untouched. They can
8242 be observed by hg status or hg diff afterwards. In other words, absorb
8243 does not write to the working directory.
8244 Changesets outside the revset ::. and not public() and not merge() will
8246 not be changed.
8247 Changesets that become empty after applying the changes will be
8249 deleted.
8250 By default, absorb will show what it plans to do and prompt for confir‐
8252 mation. If you are confident that the changes will be absorbed to the
8253 correct place, run hg absorb -a to apply the changes immediately.
8254 Returns 0 on success, 1 if all chunks were ignored and nothing amended.
8256 Options:
8258 -a, --apply-changes
8260 apply changes without prompting for confirmation
8261 -p, --print-changes
8263 always print which changesets are modified by which changes
8264 -i, --interactive
8266 interactively select which chunks to apply
8267 -e, --edit-lines
8269 edit what lines belong to which changesets before commit (EXPER‐
8270 IMENTAL)
8271 -n, --dry-run
8273 do not perform actions, just print output
8274 --style <STYLE>
8276 display using template map file (DEPRECATED)
8277 -T,--template <TEMPLATE>
8279 display with template
8280 -I,--include <PATTERN[+]>
8282 include names matching the given patterns
8283 -X,--exclude <PATTERN[+]>
8285 exclude names matching the given patterns
8286 [+] marked option can be specified multiple times
8288 acl
8290 hooks for controlling repository access
8291 This hook makes it possible to allow or deny write access to given
8293 branches and paths of a repository when receiving incoming changesets
8294 via pretxnchangegroup and pretxncommit.
8295 The authorization is matched based on the local user name on the system
8297 where the hook runs, and not the committer of the original changeset
8298 (since the latter is merely informative).
8299 The acl hook is best used along with a restricted shell like hgsh, pre‐
8301 venting authenticating users from doing anything other than pushing or
8302 pulling. The hook is not safe to use if users have interactive shell
8303 access, as they can then disable the hook. Nor is it safe if remote
8304 users share an account, because then there is no way to distinguish
8305 them.
8306 The order in which access checks are performed is:
8308 1. Deny list for branches (section acl.deny.branches)
8310 2. Allow list for branches (section acl.allow.branches)
8312 3. Deny list for paths (section acl.deny)
8314 4. Allow list for paths (section acl.allow)
8316 The allow and deny sections take key-value pairs.
8318 Branch-based Access Control
8320 Use the acl.deny.branches and acl.allow.branches sections to have
8321 branch-based access control. Keys in these sections can be either:
8322 • a branch name, or
8324 • an asterisk, to match any branch;
8326 The corresponding values can be either:
8328 • a comma-separated list containing users and groups, or
8330 • an asterisk, to match anyone;
8332 You can add the "!" prefix to a user or group name to invert the sense
8334 of the match.
8335 Path-based Access Control
8337 Use the acl.deny and acl.allow sections to have path-based access con‐
8338 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
8339 tax by default). The corresponding values follow the same syntax as the
8340 other sections above.
8341 Bookmark-based Access Control
8343 Use the acl.deny.bookmarks and acl.allow.bookmarks sections to have
8344 bookmark-based access control. Keys in these sections can be either:
8345 • a bookmark name, or
8347 • an asterisk, to match any bookmark;
8349 The corresponding values can be either:
8351 • a comma-separated list containing users and groups, or
8353 • an asterisk, to match anyone;
8355 You can add the "!" prefix to a user or group name to invert the sense
8357 of the match.
8358 Note: for interactions between clients and servers using Mercurial 3.6+
8360 a rejection will generally reject the entire push, for interactions in‐
8361 volving older clients, the commit transactions will already be ac‐
8362 cepted, and only the bookmark movement will be rejected.
8363 Groups
8365 Group names must be prefixed with an @ symbol. Specifying a group name
8366 has the same effect as specifying all the users in that group.
8367 You can define group members in the acl.groups section. If a group
8369 name is not defined there, and Mercurial is running under a Unix-like
8370 system, the list of users will be taken from the OS. Otherwise, an ex‐
8371 ception will be raised.
8372 Example Configuration
8374 [hooks]
8375 # Use this if you want to check access restrictions at commit time
8377 pretxncommit.acl = python:hgext.acl.hook
8378 # Use this if you want to check access restrictions for pull, push,
8380 # bundle and serve.
8381 pretxnchangegroup.acl = python:hgext.acl.hook
8382 [acl]
8384 # Allow or deny access for incoming changes only if their source is
8385 # listed here, let them pass otherwise. Source is "serve" for all
8386 # remote access (http or ssh), "push", "pull" or "bundle" when the
8387 # related commands are run locally.
8388 # Default: serve
8389 sources = serve
8390 [acl.deny.branches]
8392 # Everyone is denied to the frozen branch:
8394 frozen-branch = *
8395 # A bad user is denied on all branches:
8397 * = bad-user
8398 [acl.allow.branches]
8400 # A few users are allowed on branch-a:
8402 branch-a = user-1, user-2, user-3
8403 # Only one user is allowed on branch-b:
8405 branch-b = user-1
8406 # The super user is allowed on any branch:
8408 * = super-user
8409 # Everyone is allowed on branch-for-tests:
8411 branch-for-tests = *
8412 [acl.deny]
8414 # This list is checked first. If a match is found, acl.allow is not
8415 # checked. All users are granted access if acl.deny is not present.
8416 # Format for both lists: glob pattern = user, ..., @group, ...
8417 # To match everyone, use an asterisk for the user:
8419 # my/glob/pattern = *
8420 # user6 will not have write access to any file:
8422 ** = user6
8423 # Group "hg-denied" will not have write access to any file:
8425 ** = @hg-denied
8426 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
8428 # everyone being able to change all other files. See below.
8429 src/main/resources/DONT-TOUCH-THIS.txt = *
8430 [acl.allow]
8432 # if acl.allow is not present, all users are allowed by default
8433 # empty acl.allow = no users allowed
8434 # User "doc_writer" has write access to any file under the "docs"
8436 # folder:
8437 docs/** = doc_writer
8438 # User "jack" and group "designers" have write access to any file
8440 # under the "images" folder:
8441 images/** = jack, @designers
8442 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
8444 # will have write access to any file under the "resources" folder
8445 # (except for 1 file. See acl.deny):
8446 src/main/resources/** = *
8447 .hgtags = release_engineer
8449 Examples using the ! prefix
8451 Suppose there's a branch that only a given user (or group) should be
8452 able to push to, and you don't want to restrict access to any other
8453 branch that may be created.
8454 The "!" prefix allows you to prevent anyone except a given user or
8456 group to push changesets in a given branch or path.
8457 In the examples below, we will: 1) Deny access to branch "ring" to any‐
8459 one but user "gollum" 2) Deny access to branch "lake" to anyone but
8460 members of the group "hobbit" 3) Deny access to a file to anyone but
8461 user "gollum"
8462 [acl.allow.branches]
8464 # Empty
8465 [acl.deny.branches]
8467 # 1) only 'gollum' can commit to branch 'ring';
8469 # 'gollum' and anyone else can still commit to any other branch.
8470 ring = !gollum
8471 # 2) only members of the group 'hobbit' can commit to branch 'lake';
8473 # 'hobbit' members and anyone else can still commit to any other branch.
8474 lake = !@hobbit
8475 # You can also deny access based on file paths:
8477 [acl.allow]
8479 # Empty
8480 [acl.deny]
8482 # 3) only 'gollum' can change the file below;
8483 # 'gollum' and anyone else can still change any other file.
8484 /misty/mountains/cave/ring = !gollum
8485 amend
8487 provide the amend command (EXPERIMENTAL)
8488 This extension provides an amend command that is similar to commit
8490 --amend but does not prompt an editor.
8491 Commands
8493 Change creation
8494 amend
8495 amend the working copy parent with all or specified outstanding
8496 changes:
8497 hg amend [OPTION]... [FILE]...
8499 Similar to hg commit --amend, but reuse the commit message without in‐
8501 voking editor, unless --edit was set.
8502 See hg help commit for more details.
8504 Options:
8506 -A, --addremove
8508 mark new/missing files as added/removed before committing
8509 -e, --edit
8511 invoke editor on commit messages
8512 -i, --interactive
8514 use interactive mode
8515 --close-branch
8517 mark a branch as closed, hiding it from the branch list
8518 -s, --secret
8520 use the secret phase for committing
8521 -n,--note <VALUE>
8523 store a note on the amend
8524 -I,--include <PATTERN[+]>
8526 include names matching the given patterns
8527 -X,--exclude <PATTERN[+]>
8529 exclude names matching the given patterns
8530 -m,--message <TEXT>
8532 use text as commit message
8533 -l,--logfile <FILE>
8535 read commit message from file
8536 -d,--date <DATE>
8538 record the specified date as commit date
8539 -u,--user <USER>
8541 record the specified user as committer
8542 -D, --currentdate
8544 record the current date as commit date
8545 -U, --currentuser
8547 record the current user as committer
8548 [+] marked option can be specified multiple times
8550 automv
8552 check for unrecorded moves at commit time (EXPERIMENTAL)
8553 This extension checks at commit/amend time if any of the committed
8555 files comes from an unrecorded mv.
8556 The threshold at which a file is considered a move can be set with the
8558 automv.similarity config option. This option takes a percentage between
8559 0 (disabled) and 100 (files must be identical), the default is 95.
8560 beautifygraph
8562 beautify log -G output by using Unicode characters (EXPERIMENTAL)
8563 A terminal with UTF-8 support and monospace narrow text are re‐
8565 quired.
8566 blackbox
8568 log repository events to a blackbox for debugging
8569 Logs event information to .hg/blackbox.log to help debug and diagnose
8571 problems. The events that get logged can be configured via the black‐
8572 box.track and blackbox.ignore config keys.
8573 Examples:
8575 [blackbox]
8577 track = *
8578 ignore = pythonhook
8579 # dirty is *EXPENSIVE* (slow);
8580 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
8581 dirty = True
8582 # record the source of log messages
8583 logsource = True
8584 [blackbox]
8586 track = command, commandfinish, commandexception, exthook, pythonhook
8587 [blackbox]
8589 track = incoming
8590 [blackbox]
8592 # limit the size of a log file
8593 maxsize = 1.5 MB
8594 # rotate up to N log files when the current one gets too big
8595 maxfiles = 3
8596 [blackbox]
8598 # Include microseconds in log entries with %f (see Python function
8599 # datetime.datetime.strftime)
8600 date-format = %Y-%m-%d @ %H:%M:%S.%f
8601 Commands
8603 Repository maintenance
8604 blackbox
8605 view the recent repository events:
8606 hg blackbox [OPTION]...
8608 view the recent repository events
8610 Options:
8612 -l,--limit <VALUE>
8614 the number of events to show (default: 10)
8615 bookflow
8617 implements bookmark-based branching (EXPERIMENTAL)
8618 • Disables creation of new branches (config: enable_branches=False).
8620 • Requires an active bookmark on commit (config: require_book‐
8622 mark=True).
8623 • Doesn't move the active bookmark on update, only on commit.
8625 • Requires '--rev' for moving an existing bookmark.
8627 • Protects special bookmarks (config: protect=@).
8629 flow related commands
8631 hg book NAME
8633 create a new bookmark
8634 hg book NAME -r REV
8636 move bookmark to revision (fast-forward)
8637 hg up|co NAME
8639 switch to bookmark
8640 hg push -B .
8642 push active bookmark
8643 bugzilla
8645 hooks for integrating with the Bugzilla bug tracker
8646 This hook extension adds comments on bugs in Bugzilla when changesets
8648 that refer to bugs by Bugzilla ID are seen. The comment is formatted
8649 using the Mercurial template mechanism.
8650 The bug references can optionally include an update for Bugzilla of the
8652 hours spent working on the bug. Bugs can also be marked fixed.
8653 Four basic modes of access to Bugzilla are provided:
8655 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
8657 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
8659 later.
8660 3. Check data via the Bugzilla XMLRPC interface and submit bug change
8662 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
8663 later.
8664 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
8666 tions using MySQL are supported. Requires Python MySQLdb.
8667 Writing directly to the database is susceptible to schema changes, and
8669 relies on a Bugzilla contrib script to send out bug change notification
8670 emails. This script runs as the user running Mercurial, must be run on
8671 the host with the Bugzilla install, and requires permission to read
8672 Bugzilla configuration details and the necessary MySQL user and pass‐
8673 word to have full access rights to the Bugzilla database. For these
8674 reasons this access mode is now considered deprecated, and will not be
8675 updated for new Bugzilla versions going forward. Only adding comments
8676 is supported in this access mode.
8677 Access via XMLRPC needs a Bugzilla username and password to be speci‐
8679 fied in the configuration. Comments are added under that username.
8680 Since the configuration must be readable by all Mercurial users, it is
8681 recommended that the rights of that user are restricted in Bugzilla to
8682 the minimum necessary to add comments. Marking bugs fixed requires
8683 Bugzilla 4.0 and later.
8684 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
8686 to the Bugzilla email interface to submit comments to bugs. The From:
8687 address in the email is set to the email address of the Mercurial user,
8688 so the comment appears to come from the Mercurial user. In the event
8689 that the Mercurial user email is not recognized by Bugzilla as a
8690 Bugzilla user, the email associated with the Bugzilla username used to
8691 log into Bugzilla is used instead as the source of the comment. Marking
8692 bugs fixed works on all supported Bugzilla versions.
8693 Access via the REST-API needs either a Bugzilla username and password
8695 or an apikey specified in the configuration. Comments are made under
8696 the given username or the user associated with the apikey in Bugzilla.
8697 Configuration items common to all access modes:
8699 bugzilla.version
8701 The access type to use. Values recognized are:
8702 restapi
8704 Bugzilla REST-API, Bugzilla 5.0 and later.
8706 xmlrpc
8708 Bugzilla XMLRPC interface.
8710 xmlrpc+email
8712 Bugzilla XMLRPC and email interfaces.
8714 3.0
8716 MySQL access, Bugzilla 3.0 and later.
8718 2.18
8720 MySQL access, Bugzilla 2.18 and up to but not including
8722 3.0.
8723 2.16
8725 MySQL access, Bugzilla 2.16 and up to but not including
8727 2.18.
8728 bugzilla.regexp
8730 Regular expression to match bug IDs for update in changeset com‐
8731 mit message. It must contain one "()" named group <ids> con‐
8732 taining the bug IDs separated by non-digit characters. It may
8733 also contain a named group <hours> with a floating-point number
8734 giving the hours worked on the bug. If no named groups are
8735 present, the first "()" group is assumed to contain the bug IDs,
8736 and work time is not updated. The default expression matches Bug
8737 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
8738 and 5678 and variations thereof, followed by an hours number
8739 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
8740 sitive.
8741 bugzilla.fixregexp
8743 Regular expression to match bug IDs for marking fixed in change‐
8744 set commit message. This must contain a "()" named group <ids>`
8745 containing the bug IDs separated by non-digit characters. It may
8746 also contain a named group ``<hours> with a floating-point num‐
8747 ber giving the hours worked on the bug. If no named groups are
8748 present, the first "()" group is assumed to contain the bug IDs,
8749 and work time is not updated. The default expression matches
8750 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
8751 5678 and variations thereof, followed by an hours number pre‐
8752 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
8753 tive.
8754 bugzilla.fixstatus
8756 The status to set a bug to when marking fixed. Default RESOLVED.
8757 bugzilla.fixresolution
8759 The resolution to set a bug to when marking fixed. Default
8760 FIXED.
8761 bugzilla.style
8763 The style file to use when formatting comments.
8764 bugzilla.template
8766 Template to use when formatting comments. Overrides style if
8767 specified. In addition to the usual Mercurial keywords, the ex‐
8768 tension specifies:
8769 {bug}
8771 The Bugzilla bug ID.
8773 {root}
8775 The full pathname of the Mercurial repository.
8777 {webroot}
8779 Stripped pathname of the Mercurial repository.
8781 {hgweb}
8783 Base URL for browsing Mercurial repositories.
8785 Default changeset {node|short} in repo {root} refers to bug
8787 {bug}.\ndetails:\n\t{desc|tabindent}
8788 bugzilla.strip
8790 The number of path separator characters to strip from the front
8791 of the Mercurial repository path ({root} in templates) to pro‐
8792 duce {webroot}. For example, a repository with {root} /var/lo‐
8793 cal/my-project with a strip of 2 gives a value for {webroot} of
8794 my-project. Default 0.
8795 web.baseurl
8797 Base URL for browsing Mercurial repositories. Referenced from
8798 templates as {hgweb}.
8799 Configuration items common to XMLRPC+email and MySQL access modes:
8801 bugzilla.usermap
8803 Path of file containing Mercurial committer email to Bugzilla
8804 user email mappings. If specified, the file should contain one
8805 mapping per line:
8806 committer = Bugzilla user
8808 See also the [usermap] section.
8810 The [usermap] section is used to specify mappings of Mercurial commit‐
8812 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
8813 entries of the form committer = Bugzilla user.
8814 XMLRPC and REST-API access mode configuration:
8816 bugzilla.bzurl
8818 The base URL for the Bugzilla installation. Default http://lo‐
8819 calhost/bugzilla.
8820 bugzilla.user
8822 The username to use to log into Bugzilla via XMLRPC. Default
8823 bugs.
8824 bugzilla.password
8826 The password for Bugzilla login.
8827 REST-API access mode uses the options listed above as well as:
8829 bugzilla.apikey
8831 An apikey generated on the Bugzilla instance for api access.
8832 Using an apikey removes the need to store the user and password
8833 options.
8834 XMLRPC+email access mode uses the XMLRPC access mode configuration
8836 items, and also:
8837 bugzilla.bzemail
8839 The Bugzilla email address.
8840 In addition, the Mercurial email settings must be configured. See the
8842 documentation in hgrc(5), sections [email] and [smtp].
8843 MySQL access mode configuration:
8845 bugzilla.host
8847 Hostname of the MySQL server holding the Bugzilla database. De‐
8848 fault localhost.
8849 bugzilla.db
8851 Name of the Bugzilla database in MySQL. Default bugs.
8852 bugzilla.user
8854 Username to use to access MySQL server. Default bugs.
8855 bugzilla.password
8857 Password to use to access MySQL server.
8858 bugzilla.timeout
8860 Database connection timeout (seconds). Default 5.
8861 bugzilla.bzuser
8863 Fallback Bugzilla user name to record comments with, if change‐
8864 set committer cannot be found as a Bugzilla user.
8865 bugzilla.bzdir
8867 Bugzilla install directory. Used by default notify. Default
8868 /var/www/html/bugzilla.
8869 bugzilla.notify
8871 The command to run to get Bugzilla to send bug change notifica‐
8872 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
8873 id) and user (committer bugzilla email). Default depends on ver‐
8874 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
8875 mail.pl %(id)s %(user)s".
8876 Activating the extension:
8878 [extensions]
8880 bugzilla =
8881 [hooks]
8883 # run bugzilla hook on every change pulled or pushed in here
8884 incoming.bugzilla = python:hgext.bugzilla.hook
8885 Example configurations:
8887 XMLRPC example configuration. This uses the Bugzilla at
8889 http://my-project.org/bugzilla, logging in as user bug‐
8890 mail@my-project.org with password plugh. It is used with a collection
8891 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8892 at http://my-project.org/hg.
8893 [bugzilla]
8895 bzurl=http://my-project.org/bugzilla
8896 user=bugmail@my-project.org
8897 password=plugh
8898 version=xmlrpc
8899 template=Changeset {node|short} in {root|basename}.
8900 {hgweb}/{webroot}/rev/{node|short}\n
8901 {desc}\n
8902 strip=5
8903 [web]
8905 baseurl=http://my-project.org/hg
8906 XMLRPC+email example configuration. This uses the Bugzilla at
8908 http://my-project.org/bugzilla, logging in as user bug‐
8909 mail@my-project.org with password plugh. It is used with a collection
8910 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8911 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
8912 email address bugzilla@my-project.org.
8913 [bugzilla]
8915 bzurl=http://my-project.org/bugzilla
8916 user=bugmail@my-project.org
8917 password=plugh
8918 version=xmlrpc+email
8919 bzemail=bugzilla@my-project.org
8920 template=Changeset {node|short} in {root|basename}.
8921 {hgweb}/{webroot}/rev/{node|short}\n
8922 {desc}\n
8923 strip=5
8924 [web]
8926 baseurl=http://my-project.org/hg
8927 [usermap]
8929 user@emaildomain.com=user.name@bugzilladomain.com
8930 MySQL example configuration. This has a local Bugzilla 3.2 installation
8932 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
8933 database name is bugs and MySQL is accessed with MySQL username bugs
8934 password XYZZY. It is used with a collection of Mercurial repositories
8935 in /var/local/hg/repos/, with a web interface at
8936 http://my-project.org/hg.
8937 [bugzilla]
8939 host=localhost
8940 password=XYZZY
8941 version=3.0
8942 bzuser=unknown@domain.com
8943 bzdir=/opt/bugzilla-3.2
8944 template=Changeset {node|short} in {root|basename}.
8945 {hgweb}/{webroot}/rev/{node|short}\n
8946 {desc}\n
8947 strip=5
8948 [web]
8950 baseurl=http://my-project.org/hg
8951 [usermap]
8953 user@emaildomain.com=user.name@bugzilladomain.com
8954 All the above add a comment to the Bugzilla bug record of the form:
8956 Changeset 3b16791d6642 in repository-name.
8958 http://my-project.org/hg/repository-name/rev/3b16791d6642
8959 Changeset commit comment. Bug 1234.
8961 censor
8963 erase file content at a given revision
8964 The censor command instructs Mercurial to erase all content of a file
8966 at a given revision without updating the changeset hash. This allows
8967 existing history to remain valid while preventing future clones/pulls
8968 from receiving the erased data.
8969 Typical uses for censor are due to security or legal requirements, in‐
8971 cluding:
8972 * Passwords, private keys, cryptographic material
8974 * Licensed data/code/libraries for which the license has expired
8975 * Personally Identifiable Information or other private data
8976 Censored nodes can interrupt mercurial's typical operation whenever the
8978 excised data needs to be materialized. Some commands, like hg cat/hg
8979 revert, simply fail when asked to produce censored data. Others, like
8980 hg verify and hg update, must be capable of tolerating censored data to
8981 continue to function in a meaningful way. Such commands only tolerate
8982 censored file revisions if they are allowed by the "censor.policy=ig‐
8983 nore" config option.
8984 A few informative commands such as hg grep will unconditionally ignore
8986 censored data and merely report that it was encountered.
8987 Commands
8989 Repository maintenance
8990 censor
8991 hg censor -r REV [-t TEXT] [FILE]
8992 Options:
8994 -r,--rev <REV>
8996 censor file from specified revision
8997 -t,--tombstone <TEXT>
8999 replacement tombstone data
9000 children
9002 command to display child changesets (DEPRECATED)
9003 This extension is deprecated. You should use hg log -r "children(REV)"
9005 instead.
9006 Commands
9008 Change navigation
9009 children
9010 show the children of the given or working directory revision:
9011 hg children [-r REV] [FILE]
9013 Print the children of the working directory's revisions. If a revision
9015 is given via -r/--rev, the children of that revision will be printed.
9016 If a file argument is given, revision in which the file was last
9017 changed (after the working directory revision or the argument to --rev
9018 if given) is printed.
9019 Please use hg log instead:
9021 hg children => hg log -r "children(.)"
9023 hg children -r REV => hg log -r "children(REV)"
9024 See hg help log and hg help revsets.children.
9026 Options:
9028 -r,--rev <REV>
9030 show children of the specified revision (default: .)
9031 --style <STYLE>
9033 display using template map file (DEPRECATED)
9034 -T,--template <TEMPLATE>
9036 display with template
9037 churn
9039 command to display statistics about repository history
9040 Commands
9042 Repository maintenance
9043 churn
9044 histogram of changes to the repository:
9045 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
9047 This command will display a histogram representing the number of
9049 changed lines or revisions, grouped according to the given template.
9050 The default template will group changes by author. The --dateformat
9051 option may be used to group the results by date instead.
9052 Statistics are based on the number of changed lines, or alternatively
9054 the number of matching revisions if the --changesets option is speci‐
9055 fied.
9056 Examples:
9058 # display count of changed lines for every committer
9060 hg churn -T "{author|email}"
9061 # display daily activity graph
9063 hg churn -f "%H" -s -c
9064 # display activity of developers by month
9066 hg churn -f "%Y-%m" -s -c
9067 # display count of lines changed in every year
9069 hg churn -f "%Y" -s
9070 # display count of lines changed in a time range
9072 hg churn -d "2020-04 to 2020-09"
9073 It is possible to map alternate email addresses to a main address by
9075 providing a file using the following format:
9076 <alias email> = <actual email>
9078 Such a file may be specified with the --aliases option, otherwise a
9080 .hgchurn file will be looked for in the working directory root.
9081 Aliases will be split from the rightmost "=".
9082 Options:
9084 -r,--rev <REV[+]>
9086 count rate for the specified revision or revset
9087 -d,--date <DATE>
9089 count rate for revisions matching date spec
9090 -t,--oldtemplate <TEMPLATE>
9092 template to group changesets (DEPRECATED)
9093 -T,--template <TEMPLATE>
9095 template to group changesets (default: {author|email})
9096 -f,--dateformat <FORMAT>
9098 strftime-compatible format for grouping by date
9099 -c, --changesets
9101 count rate by number of changesets
9102 -s, --sort
9104 sort by key (default: sort by count)
9105 --diffstat
9107 display added/removed lines separately
9108 --aliases <FILE>
9110 file with email aliases
9111 -I,--include <PATTERN[+]>
9113 include names matching the given patterns
9114 -X,--exclude <PATTERN[+]>
9116 exclude names matching the given patterns
9117 [+] marked option can be specified multiple times
9119 clonebundles
9121 advertise pre-generated bundles to seed clones
9122 "clonebundles" is a server-side extension used to advertise the exis‐
9124 tence of pre-generated, externally hosted bundle files to clients that
9125 are cloning so that cloning can be faster, more reliable, and require
9126 less resources on the server. "pullbundles" is a related feature for
9127 sending pre-generated bundle files to clients as part of pull opera‐
9128 tions.
9129 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
9131 ally, the server, in response to a client's request to clone, dynami‐
9132 cally generates a bundle containing the entire repository content and
9133 sends it to the client. There is no caching on the server and the
9134 server will have to redundantly generate the same outgoing bundle in
9135 response to each clone request. For servers with large repositories or
9136 with high clone volume, the load from clones can make scaling the
9137 server challenging and costly.
9138 This extension provides server operators the ability to offload poten‐
9140 tially expensive clone load to an external service. Pre-generated bun‐
9141 dles also allow using more CPU intensive compression, reducing the ef‐
9142 fective bandwidth requirements.
9143 Here's how clone bundles work:
9145 1. A server operator establishes a mechanism for making bundle files
9147 available on a hosting service where Mercurial clients can fetch
9148 them.
9149 2. A manifest file listing available bundle URLs and some optional
9151 metadata is added to the Mercurial repository on the server.
9152 3. A client initiates a clone against a clone bundles aware server.
9154 4. The client sees the server is advertising clone bundles and fetches
9156 the manifest listing available bundles.
9157 5. The client filters and sorts the available bundles based on what it
9159 supports and prefers.
9160 6. The client downloads and applies an available bundle from the
9162 server-specified URL.
9163 7. The client reconnects to the original server and performs the equiv‐
9165 alent of hg pull to retrieve all repository data not in the bundle.
9166 (The repository could have been updated between when the bundle was
9167 created and when the client started the clone.) This may use "pull‐
9168 bundles".
9169 Instead of the server generating full repository bundles for every
9171 clone request, it generates full bundles once and they are subsequently
9172 reused to bootstrap new clones. The server may still transfer data at
9173 clone time. However, this is only data that has been added/changed
9174 since the bundle was created. For large, established repositories, this
9175 can reduce server load for clones to less than 1% of original.
9176 Here's how pullbundles work:
9178 1. A manifest file listing available bundles and describing the revi‐
9180 sions is added to the Mercurial repository on the server.
9181 2. A new-enough client informs the server that it supports partial
9183 pulls and initiates a pull.
9184 3. If the server has pull bundles enabled and sees the client advertis‐
9186 ing partial pulls, it checks for a matching pull bundle in the mani‐
9187 fest. A bundle matches if the format is supported by the client,
9188 the client has the required revisions already and needs something
9189 from the bundle.
9190 4. If there is at least one matching bundle, the server sends it to the
9192 client.
9193 5. The client applies the bundle and notices that the server reply was
9195 incomplete. It initiates another pull.
9196 To work, this extension requires the following of server operators:
9198 • Generating bundle files of repository content (typically periodi‐
9200 cally, such as once per day).
9201 • Clone bundles: A file server that clients have network access to and
9203 that Python knows how to talk to through its normal URL handling fa‐
9204 cility (typically an HTTP/HTTPS server).
9205 • A process for keeping the bundles manifest in sync with available
9207 bundle files.
9208 Strictly speaking, using a static file hosting server isn't required: a
9210 server operator could use a dynamic service for retrieving bundle data.
9211 However, static file hosting services are simple and scalable and
9212 should be sufficient for most needs.
9213 Bundle files can be generated with the hg bundle command. Typically hg
9215 bundle --all is used to produce a bundle of the entire repository.
9216 hg debugcreatestreamclonebundle can be used to produce a special
9218 streaming clonebundle. These are bundle files that are extremely effi‐
9219 cient to produce and consume (read: fast). However, they are larger
9220 than traditional bundle formats and require that clients support the
9221 exact set of repository data store formats in use by the repository
9222 that created them. Typically, a newer server can serve data that is
9223 compatible with older clients. However, streaming clone bundles don't
9224 have this guarantee. Server operators need to be aware that newer ver‐
9225 sions of Mercurial may produce streaming clone bundles incompatible
9226 with older Mercurial versions.
9227 A server operator is responsible for creating a .hg/clonebundles.mani‐
9229 fest file containing the list of available bundle files suitable for
9230 seeding clones. If this file does not exist, the repository will not
9231 advertise the existence of clone bundles when clients connect. For pull
9232 bundles, .hg/pullbundles.manifest is used.
9233 The manifest file contains a newline (n) delimited list of entries.
9235 Each line in this file defines an available bundle. Lines have the for‐
9237 mat:
9238 <URL> [<key>=<value>[ <key>=<value>]]
9240 That is, a URL followed by an optional, space-delimited list of
9242 key=value pairs describing additional properties of this bundle. Both
9243 keys and values are URI encoded.
9244 For pull bundles, the URL is a path under the .hg directory of the
9246 repository.
9247 Keys in UPPERCASE are reserved for use by Mercurial and are defined be‐
9249 low. All non-uppercase keys can be used by site installations. An ex‐
9250 ample use for custom properties is to use the datacenter attribute to
9251 define which data center a file is hosted in. Clients could then prefer
9252 a server in the data center closest to them.
9253 The following reserved keys are currently defined:
9255 BUNDLESPEC
9257 A "bundle specification" string that describes the type of the
9258 bundle.
9259 These are string values that are accepted by the "--type" argu‐
9261 ment of hg bundle.
9262 The values are parsed in strict mode, which means they must be
9264 of the "<compression>-<type>" form. See mercurial.ex‐
9265 change.parsebundlespec() for more details.
9266 hg debugbundle --spec can be used to print the bundle specifica‐
9268 tion string for a bundle file. The output of this command can be
9269 used verbatim for the value of BUNDLESPEC (it is already es‐
9270 caped).
9271 Clients will automatically filter out specifications that are
9273 unknown or unsupported so they won't attempt to download some‐
9274 thing that likely won't apply.
9275 The actual value doesn't impact client behavior beyond filter‐
9277 ing: clients will still sniff the bundle type from the header of
9278 downloaded files.
9279 Use of this key is highly recommended, as it allows clients to
9281 easily skip unsupported bundles. If this key is not defined, an
9282 old client may attempt to apply a bundle that it is incapable of
9283 reading.
9284 REQUIRESNI
9286 Whether Server Name Indication (SNI) is required to connect to
9287 the URL. SNI allows servers to use multiple certificates on the
9288 same IP. It is somewhat common in CDNs and other hosting
9289 providers. Older Python versions do not support SNI. Defining
9290 this attribute enables clients with older Python versions to
9291 filter this entry without experiencing an opaque SSL failure at
9292 connection time.
9293 If this is defined, it is important to advertise a non-SNI fall‐
9295 back URL or clients running old Python releases may not be able
9296 to clone with the clonebundles facility.
9297 Value should be "true".
9299 REQUIREDRAM
9301 Value specifies expected memory requirements to decode the pay‐
9302 load. Values can have suffixes for common bytes sizes. e.g.
9303 "64MB".
9304 This key is often used with zstd-compressed bundles using a high
9306 compression level / window size, which can require 100+ MB of
9307 memory to decode.
9308 heads Used for pull bundles. This contains the ; separated changeset
9310 hashes of the heads of the bundle content.
9311 bases Used for pull bundles. This contains the ; separated changeset
9313 hashes of the roots of the bundle content. This can be skipped
9314 if the bundle was created without --base.
9315 Manifests can contain multiple entries. Assuming metadata is defined,
9317 clients will filter entries from the manifest that they don't support.
9318 The remaining entries are optionally sorted by client preferences
9319 (ui.clonebundleprefers config option). The client then attempts to
9320 fetch the bundle at the first URL in the remaining list.
9321 Errors when downloading a bundle will fail the entire clone operation:
9323 clients do not automatically fall back to a traditional clone. The rea‐
9324 son for this is that if a server is using clone bundles, it is probably
9325 doing so because the feature is necessary to help it scale. In other
9326 words, there is an assumption that clone load will be offloaded to an‐
9327 other service and that the Mercurial server isn't responsible for serv‐
9328 ing this clone load. If that other service experiences issues and
9329 clients start mass falling back to the original Mercurial server, the
9330 added clone load could overwhelm the server due to unexpected load and
9331 effectively take it offline. Not having clients automatically fall back
9332 to cloning from the original server mitigates this scenario.
9333 Because there is no automatic Mercurial server fallback on failure of
9335 the bundle hosting service, it is important for server operators to
9336 view the bundle hosting service as an extension of the Mercurial server
9337 in terms of availability and service level agreements: if the bundle
9338 hosting service goes down, so does the ability for clients to clone.
9339 Note: clients will see a message informing them how to bypass the clone
9340 bundles facility when a failure occurs. So server operators should pre‐
9341 pare for some people to follow these instructions when a failure oc‐
9342 curs, thus driving more load to the original Mercurial server when the
9343 bundle hosting service fails.
9344 closehead
9346 close arbitrary heads without checking them out first
9347 Commands
9349 Change manipulation
9350 close-head
9351 close the given head revisions:
9352 hg close-head [OPTION]... [REV]...
9354 This is equivalent to checking out each revision in a clean tree and
9356 running hg commit --close-branch, except that it doesn't change the
9357 working directory.
9358 The commit message must be specified with -l or -m.
9360 Options:
9362 -m,--message <TEXT>
9364 use text as commit message
9365 -l,--logfile <FILE>
9367 read commit message from file
9368 -d,--date <DATE>
9370 record the specified date as commit date
9371 -u,--user <USER>
9373 record the specified user as committer
9374 -r,--rev <REV[+]>
9376 revision to check
9377 [+] marked option can be specified multiple times
9379 aliases: close-heads
9381 commitextras
9383 adds a new flag extras to commit (ADVANCED)
9384 convert
9386 import revisions from foreign VCS repositories into Mercurial
9387 Commands
9389 Uncategorized commands
9390 convert
9391 convert a foreign SCM repository to a Mercurial one.:
9392 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
9394 Accepted source formats [identifiers]:
9396 • Mercurial [hg]
9398 • CVS [cvs]
9400 • Darcs [darcs]
9402 • git [git]
9404 • Subversion [svn]
9406 • Monotone [mtn]
9408 • GNU Arch [gnuarch]
9410 • Bazaar [bzr]
9412 • Perforce [p4]
9414 Accepted destination formats [identifiers]:
9416 • Mercurial [hg]
9418 • Subversion [svn] (history on branches is not preserved)
9420 If no revision is given, all revisions will be converted. Otherwise,
9422 convert will only import up to the named revision (given in a format
9423 understood by the source).
9424 If no destination directory name is specified, it defaults to the base‐
9426 name of the source with -hg appended. If the destination repository
9427 doesn't exist, it will be created.
9428 By default, all sources except Mercurial will use --branchsort. Mercu‐
9430 rial uses --sourcesort to preserve original revision numbers order.
9431 Sort modes have the following effects:
9432 --branchsort
9434 convert from parent to child revision when possible, which means
9435 branches are usually converted one after the other. It generates
9436 more compact repositories.
9437 --datesort
9439 sort revisions by date. Converted repositories have good-looking
9440 changelogs but are often an order of magnitude larger than the
9441 same ones generated by --branchsort.
9442 --sourcesort
9444 try to preserve source revisions order, only supported by Mercu‐
9445 rial sources.
9446 --closesort
9448 try to move closed revisions as close as possible to parent
9449 branches, only supported by Mercurial sources.
9450 If REVMAP isn't given, it will be put in a default location
9452 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
9453 maps each source commit ID to the destination ID for that revision,
9454 like so:
9455 <source ID> <destination ID>
9457 If the file doesn't exist, it's automatically created. It's updated on
9459 each commit copied, so hg convert can be interrupted and can be run re‐
9460 peatedly to copy new commits.
9461 The authormap is a simple text file that maps each source commit author
9463 to a destination commit author. It is handy for source SCMs that use
9464 unix logins to identify authors (e.g.: CVS). One line per author map‐
9465 ping and the line format is:
9466 source author = destination author
9468 Empty lines and lines starting with a # are ignored.
9470 The filemap is a file that allows filtering and remapping of files and
9472 directories. Each line can contain one of the following directives:
9473 include path/to/file-or-dir
9475 exclude path/to/file-or-dir
9477 rename path/to/source path/to/destination
9479 Comment lines start with #. A specified path matches if it equals the
9481 full relative name of a file or one of its parent directories. The in‐
9482 clude or exclude directive with the longest matching path applies, so
9483 line order does not matter.
9484 The include directive causes a file, or all files under a directory, to
9486 be included in the destination repository. The default if there are no
9487 include statements is to include everything. If there are any include
9488 statements, nothing else is included. The exclude directive causes
9489 files or directories to be omitted. The rename directive renames a file
9490 or directory if it is converted. To rename from a subdirectory into the
9491 root of the repository, use . as the path to rename to.
9492 --full will make sure the converted changesets contain exactly the
9494 right files with the right content. It will make a full conversion of
9495 all files, not just the ones that have changed. Files that already are
9496 correct will not be changed. This can be used to apply filemap changes
9497 when converting incrementally. This is currently only supported for
9498 Mercurial and Subversion.
9499 The splicemap is a file that allows insertion of synthetic history,
9501 letting you specify the parents of a revision. This is useful if you
9502 want to e.g. give a Subversion merge two parents, or graft two discon‐
9503 nected series of history together. Each entry contains a key, followed
9504 by a space, followed by one or two comma-separated values:
9505 key parent1, parent2
9507 The key is the revision ID in the source revision control system whose
9509 parents should be modified (same format as a key in .hg/shamap). The
9510 values are the revision IDs (in either the source or destination revi‐
9511 sion control system) that should be used as the new parents for that
9512 node. For example, if you have merged "release-1.0" into "trunk", then
9513 you should specify the revision on "trunk" as the first parent and the
9514 one on the "release-1.0" branch as the second.
9515 The branchmap is a file that allows you to rename a branch when it is
9517 being brought in from whatever external repository. When used in con‐
9518 junction with a splicemap, it allows for a powerful combination to help
9519 fix even the most badly mismanaged repositories and turn them into
9520 nicely structured Mercurial repositories. The branchmap contains lines
9521 of the form:
9522 original_branch_name new_branch_name
9524 where "original_branch_name" is the name of the branch in the source
9526 repository, and "new_branch_name" is the name of the branch is the des‐
9527 tination repository. No whitespace is allowed in the new branch name.
9528 This can be used to (for instance) move code in one repository from
9529 "default" to a named branch.
9530 Mercurial Source
9532 The Mercurial source recognizes the following configuration options,
9533 which you can set on the command line with --config:
9534 convert.hg.ignoreerrors
9536 ignore integrity errors when reading. Use it to fix Mercurial
9537 repositories with missing revlogs, by converting from and to
9538 Mercurial. Default is False.
9539 convert.hg.saverev
9541 store original revision ID in changeset (forces target IDs to
9542 change). It takes a boolean argument and defaults to False.
9543 convert.hg.startrev
9545 specify the initial Mercurial revision. The default is 0.
9546 convert.hg.revs
9548 revset specifying the source revisions to convert.
9549 Bazaar Source
9551 The following options can be used with --config:
9552 convert.bzr.saverev
9554 whether to store the original Bazaar commit ID in the metadata
9555 of the destination commit. The default is True.
9556 CVS Source
9558 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to in‐
9559 dicate the starting point of what will be converted. Direct access to
9560 the repository files is not needed, unless of course the repository is
9561 :local:. The conversion uses the top level directory in the sandbox to
9562 find the CVS repository, and then uses CVS rlog commands to find files
9563 to convert. This means that unless a filemap is given, all files under
9564 the starting directory will be converted, and that any directory reor‐
9565 ganization in the CVS sandbox is ignored.
9566 The following options can be used with --config:
9568 convert.cvsps.cache
9570 Set to False to disable remote log caching, for testing and de‐
9571 bugging purposes. Default is True.
9572 convert.cvsps.fuzz
9574 Specify the maximum time (in seconds) that is allowed between
9575 commits with identical user and log message in a single change‐
9576 set. When very large files were checked in as part of a change‐
9577 set then the default may not be long enough. The default is 60.
9578 convert.cvsps.logencoding
9580 Specify encoding name to be used for transcoding CVS log mes‐
9581 sages. Multiple encoding names can be specified as a list (see
9582 hg help config.Syntax), but only the first acceptable encoding
9583 in the list is used per CVS log entries. This transcoding is ex‐
9584 ecuted before cvslog hook below.
9585 convert.cvsps.mergeto
9587 Specify a regular expression to which commit log messages are
9588 matched. If a match occurs, then the conversion process will in‐
9589 sert a dummy revision merging the branch on which this log mes‐
9590 sage occurs to the branch indicated in the regex. Default is
9591 {{mergetobranch ([-\w]+)}}
9592 convert.cvsps.mergefrom
9594 Specify a regular expression to which commit log messages are
9595 matched. If a match occurs, then the conversion process will add
9596 the most recent revision on the branch indicated in the regex as
9597 the second parent of the changeset. Default is {{mergefrombranch
9598 ([-\w]+)}}
9599 convert.localtimezone
9601 use local time (as determined by the TZ environment variable)
9602 for changeset date/times. The default is False (use UTC).
9603 hooks.cvslog
9605 Specify a Python function to be called at the end of gathering
9606 the CVS log. The function is passed a list with the log entries,
9607 and can modify the entries in-place, or add or delete them.
9608 hooks.cvschangesets
9610 Specify a Python function to be called after the changesets are
9611 calculated from the CVS log. The function is passed a list with
9612 the changeset entries, and can modify the changesets in-place,
9613 or add or delete them.
9614 An additional "debugcvsps" Mercurial command allows the builtin change‐
9616 set merging code to be run without doing a conversion. Its parameters
9617 and output are similar to that of cvsps 2.1. Please see the command
9618 help for more details.
9619 Subversion Source
9621 Subversion source detects classical trunk/branches/tags layouts. By
9622 default, the supplied svn://repo/path/ source URL is converted as a
9623 single branch. If svn://repo/path/trunk exists it replaces the default
9624 branch. If svn://repo/path/branches exists, its subdirectories are
9625 listed as possible branches. If svn://repo/path/tags exists, it is
9626 looked for tags referencing converted branches. Default trunk, branches
9627 and tags values can be overridden with following options. Set them to
9628 paths relative to the source URL, or leave them blank to disable auto
9629 detection.
9630 The following options can be set with --config:
9632 convert.svn.branches
9634 specify the directory containing branches. The default is
9635 branches.
9636 convert.svn.tags
9638 specify the directory containing tags. The default is tags.
9639 convert.svn.trunk
9641 specify the name of the trunk branch. The default is trunk.
9642 convert.localtimezone
9644 use local time (as determined by the TZ environment variable)
9645 for changeset date/times. The default is False (use UTC).
9646 Source history can be retrieved starting at a specific revision, in‐
9648 stead of being integrally converted. Only single branch conversions are
9649 supported.
9650 convert.svn.startrev
9652 specify start Subversion revision number. The default is 0.
9653 Git Source
9655 The Git importer converts commits from all reachable branches (refs in
9656 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
9657 are converted to bookmarks with the same name, with the leading
9658 'refs/heads' stripped. Git submodules are converted to Git subrepos in
9659 Mercurial.
9660 The following options can be set with --config:
9662 convert.git.similarity
9664 specify how similar files modified in a commit must be to be im‐
9665 ported as renames or copies, as a percentage between 0 (dis‐
9666 abled) and 100 (files must be identical). For example, 90 means
9667 that a delete/add pair will be imported as a rename if more than
9668 90% of the file hasn't changed. The default is 50.
9669 convert.git.findcopiesharder
9671 while detecting copies, look at all files in the working copy
9672 instead of just changed ones. This is very expensive for large
9673 projects, and is only effective when convert.git.similarity is
9674 greater than 0. The default is False.
9675 convert.git.renamelimit
9677 perform rename and copy detection up to this many changed files
9678 in a commit. Increasing this will make rename and copy detection
9679 more accurate but will significantly slow down computation on
9680 large projects. The option is only relevant if convert.git.simi‐
9681 larity is greater than 0. The default is 400.
9682 convert.git.committeractions
9684 list of actions to take when processing author and committer
9685 values.
9686 Git commits have separate author (who wrote the commit) and com‐
9688 mitter (who applied the commit) fields. Not all destinations
9689 support separate author and committer fields (including Mercu‐
9690 rial). This config option controls what to do with these author
9691 and committer fields during conversion.
9692 A value of messagedifferent will append a committer: ... line
9694 to the commit message if the Git committer is different from the
9695 author. The prefix of that line can be specified using the syn‐
9696 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
9697 ter:. When a prefix is specified, a space will always be in‐
9698 serted between the prefix and the value.
9699 messagealways behaves like messagedifferent except it will al‐
9701 ways result in a committer: ... line being appended to the com‐
9702 mit message. This value is mutually exclusive with messagedif‐
9703 ferent.
9704 dropcommitter will remove references to the committer. Only ref‐
9706 erences to the author will remain. Actions that add references
9707 to the committer will have no effect when this is set.
9708 replaceauthor will replace the value of the author field with
9710 the committer. Other actions that add references to the commit‐
9711 ter will still take effect when this is set.
9712 The default is messagedifferent.
9714 convert.git.extrakeys
9716 list of extra keys from commit metadata to copy to the destina‐
9717 tion. Some Git repositories store extra metadata in commits. By
9718 default, this non-default metadata will be lost during conver‐
9719 sion. Setting this config option can retain that metadata. Some
9720 built-in keys such as parent and branch are not allowed to be
9721 copied.
9722 convert.git.remoteprefix
9724 remote refs are converted as bookmarks with convert.git.re‐
9725 moteprefix as a prefix followed by a /. The default is 'remote'.
9726 convert.git.saverev
9728 whether to store the original Git commit ID in the metadata of
9729 the destination commit. The default is True.
9730 convert.git.skipsubmodules
9732 does not convert root level .gitmodules files or files with
9733 160000 mode indicating a submodule. Default is False.
9734 Perforce Source
9736 The Perforce (P4) importer can be given a p4 depot path or a client
9737 specification as source. It will convert all files in the source to a
9738 flat Mercurial repository, ignoring labels, branches and integrations.
9739 Note that when a depot path is given you then usually should specify a
9740 target directory, because otherwise the target may be named ...-hg.
9741 The following options can be set with --config:
9743 convert.p4.encoding
9745 specify the encoding to use when decoding standard output of the
9746 Perforce command line tool. The default is default system encod‐
9747 ing.
9748 convert.p4.startrev
9750 specify initial Perforce revision (a Perforce changelist num‐
9751 ber).
9752 Mercurial Destination
9754 The Mercurial destination will recognize Mercurial subrepositories in
9755 the destination directory, and update the .hgsubstate file automati‐
9756 cally if the destination subrepositories contain the
9757 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
9758 tories requires converting a single repository at a time, from the bot‐
9759 tom up.
9760 An example showing how to convert a repository with subrepositories:
9762 # so convert knows the type when it sees a non empty destination
9764 $ hg init converted
9765 $ hg convert orig/sub1 converted/sub1
9767 $ hg convert orig/sub2 converted/sub2
9768 $ hg convert orig converted
9769 The following options are supported:
9771 convert.hg.clonebranches
9773 dispatch source branches in separate clones. The default is
9774 False.
9775 convert.hg.tagsbranch
9777 branch name for tag revisions, defaults to default.
9778 convert.hg.usebranchnames
9780 preserve branch names. The default is True.
9781 convert.hg.sourcename
9783 records the given string as a 'convert_source' extra value on
9784 each commit made in the target repository. The default is None.
9785 convert.hg.preserve-hash
9787 only works with mercurial sources. Make convert prevent perfor‐
9788 mance improvement to the list of modified files in commits when
9789 such an improvement would cause the hash of a commit to change.
9790 The default is False.
9791 All Destinations
9793 All destination types accept the following options:
9794 convert.skiptags
9796 does not convert tags from the source repo to the target repo.
9797 The default is False.
9798 Subversion Destination
9800 Original commit dates are not preserved by default.
9801 convert.svn.dangerous-set-commit-dates
9803 preserve original commit dates, forcefully setting svn:date re‐
9804 vision properties. This option is DANGEROUS and may break some
9805 subversion functionality for the resulting repository (e.g. fil‐
9806 tering revisions with date ranges in svn log), as original com‐
9807 mit dates are not guaranteed to be monotonically increasing.
9808 For commit dates setting to work destination repository must have
9810 pre-revprop-change hook configured to allow setting of svn:date revi‐
9811 sion properties. See Subversion documentation for more details.
9812 Options:
9814 --authors <FILE>
9816 username mapping filename (DEPRECATED) (use --authormap instead)
9817 -s,--source-type <TYPE>
9819 source repository type
9820 -d,--dest-type <TYPE>
9822 destination repository type
9823 -r,--rev <REV[+]>
9825 import up to source revision REV
9826 -A,--authormap <FILE>
9828 remap usernames using this file
9829 --filemap <FILE>
9831 remap file names using contents of file
9832 --full apply filemap changes by converting all files again
9834 --splicemap <FILE>
9836 splice synthesized history into place
9837 --branchmap <FILE>
9839 change branch names while converting
9840 --branchsort
9842 try to sort changesets by branches
9843 --datesort
9845 try to sort changesets by date
9846 --sourcesort
9848 preserve source changesets order
9849 --closesort
9851 try to reorder closed revisions
9852 [+] marked option can be specified multiple times
9854 eol
9856 automatically manage newlines in repository files
9857 This extension allows you to manage the type of line endings (CRLF or
9859 LF) that are used in the repository and in the local working directory.
9860 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
9861 thereby letting everybody use their OS native line endings.
9862 The extension reads its configuration from a versioned .hgeol configu‐
9864 ration file found in the root of the working directory. The .hgeol file
9865 use the same syntax as all other Mercurial configuration files. It uses
9866 two sections, [patterns] and [repository].
9867 The [patterns] section specifies how line endings should be converted
9869 between the working directory and the repository. The format is speci‐
9870 fied by a file pattern. The first match is used, so put more specific
9871 patterns first. The available line endings are LF, CRLF, and BIN.
9872 Files with the declared format of CRLF or LF are always checked out and
9874 stored in the repository in that format and files declared to be binary
9875 (BIN) are left unchanged. Additionally, native is an alias for checking
9876 out in the platform's default line ending: LF on Unix (including Mac OS
9877 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
9878 Mercurial's default behavior; it is only needed if you need to override
9879 a later, more general pattern.
9880 The optional [repository] section specifies the line endings to use for
9882 files stored in the repository. It has a single setting, native, which
9883 determines the storage line endings for files declared as native in the
9884 [patterns] section. It can be set to LF or CRLF. The default is LF. For
9885 example, this means that on Windows, files configured as native (CRLF
9886 by default) will be converted to LF when stored in the repository.
9887 Files declared as LF, CRLF, or BIN in the [patterns] section are always
9888 stored as-is in the repository.
9889 Example versioned .hgeol file:
9891 [patterns]
9893 **.py = native
9894 **.vcproj = CRLF
9895 **.txt = native
9896 Makefile = LF
9897 **.jpg = BIN
9898 [repository]
9900 native = LF
9901 Note The rules will first apply when files are touched in the working
9903 directory, e.g. by updating to null and back to tip to touch all
9904 files.
9905 The extension uses an optional [eol] section read from both the normal
9907 Mercurial configuration files and the .hgeol file, with the latter
9908 overriding the former. You can use that section to control the overall
9909 behavior. There are three settings:
9910 • eol.native (default os.linesep) can be set to LF or CRLF to override
9912 the default interpretation of native for checkout. This can be used
9913 with hg archive on Unix, say, to generate an archive where files have
9914 line endings for Windows.
9915 • eol.only-consistent (default True) can be set to False to make the
9917 extension convert files with inconsistent EOLs. Inconsistent means
9918 that there is both CRLF and LF present in the file. Such files are
9919 normally not touched under the assumption that they have mixed EOLs
9920 on purpose.
9921 • eol.fix-trailing-newline (default False) can be set to True to ensure
9923 that converted files end with a EOL character (either \n or \r\n as
9924 per the configured patterns).
9925 The extension provides cleverencode: and cleverdecode: filters like the
9927 deprecated win32text extension does. This means that you can disable
9928 win32text and enable eol and your filters will still work. You only
9929 need to these filters until you have prepared a .hgeol file.
9930 The win32text.forbid* hooks provided by the win32text extension have
9932 been unified into a single hook named eol.checkheadshook. The hook will
9933 lookup the expected line endings from the .hgeol file, which means you
9934 must migrate to a .hgeol file first before using the hook. eol.check‐
9935 headshook only checks heads, intermediate invalid revisions will be
9936 pushed. To forbid them completely, use the eol.checkallhook hook. These
9937 hooks are best used as pretxnchangegroup hooks.
9938 See hg help patterns for more information about the glob patterns used.
9940 extdiff
9942 command to allow external programs to compare revisions
9943 The extdiff Mercurial extension allows you to use external programs to
9945 compare revisions, or revision with working directory. The external
9946 diff programs are called with a configurable set of options and two
9947 non-option arguments: paths to directories containing snapshots of
9948 files to compare.
9949 If there is more than one file being compared and the "child" revision
9951 is the working directory, any modifications made in the external diff
9952 program will be copied back to the working directory from the temporary
9953 directory.
9954 The extdiff extension also allows you to configure new diff commands,
9956 so you do not need to type hg extdiff -p kdiff3 always.
9957 [extdiff]
9959 # add new command that runs GNU diff(1) in 'context diff' mode
9960 cdiff = gdiff -Nprc5
9961 ## or the old way:
9962 #cmd.cdiff = gdiff
9963 #opts.cdiff = -Nprc5
9964 # add new command called meld, runs meld (no need to name twice). If
9966 # the meld executable is not available, the meld tool in [merge-tools]
9967 # will be used, if available
9968 meld =
9969 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
9971 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
9972 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
9973 # your .vimrc
9974 vimdiff = gvim -f "+next" \
9975 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
9976 Tool arguments can include variables that are expanded at runtime:
9978 $parent1, $plabel1 - filename, descriptive label of first parent
9980 $child, $clabel - filename, descriptive label of child revision
9981 $parent2, $plabel2 - filename, descriptive label of second parent
9982 $root - repository root
9983 $parent is an alias for $parent1.
9984 The extdiff extension will look in your [diff-tools] and [merge-tools]
9986 sections for diff tool arguments, when none are specified in [extdiff].
9987 [extdiff]
9989 kdiff3 =
9990 [diff-tools]
9992 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9993 If a program has a graphical interface, it might be interesting to tell
9995 Mercurial about it. It will prevent the program from being mistakenly
9996 used in a terminal-only environment (such as an SSH terminal session),
9997 and will make hg extdiff --per-file open multiple file diffs at once
9998 instead of one by one (if you still want to open file diffs one by one,
9999 you can use the --confirm option).
10000 Declaring that a tool has a graphical interface can be done with the
10002 gui flag next to where diffargs are specified:
10003 [diff-tools]
10005 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
10006 kdiff3.gui = true
10007 You can use -I/-X and list of file or directory names like normal hg
10009 diff command. The extdiff extension makes snapshots of only needed
10010 files, so running the external diff program will actually be pretty
10011 fast (at least faster than having to compare the entire tree).
10012 Commands
10014 File content management
10015 extdiff
10016 use external program to diff repository (or selected files):
10017 hg extdiff [OPT]... [FILE]...
10019 Show differences between revisions for the specified files, using an
10021 external program. The default program used is diff, with default op‐
10022 tions "-Npru".
10023 To select a different program, use the -p/--program option. The program
10025 will be passed the names of two directories to compare, unless the
10026 --per-file option is specified (see below). To pass additional options
10027 to the program, use -o/--option. These will be passed before the names
10028 of the directories or files to compare.
10029 The --from, --to, and --change options work the same way they do for hg
10031 diff.
10032 The --per-file option runs the external program repeatedly on each file
10034 to diff, instead of once on two directories. By default, this happens
10035 one by one, where the next file diff is open in the external program
10036 only once the previous external program (for the previous file diff)
10037 has exited. If the external program has a graphical interface, it can
10038 open all the file diffs at once instead of one by one. See hg help -e
10039 extdiff for information about how to tell Mercurial that a given pro‐
10040 gram has a graphical interface.
10041 The --confirm option will prompt the user before each invocation of the
10043 external program. It is ignored if --per-file isn't specified.
10044 Options:
10046 -p,--program <CMD>
10048 comparison program to run
10049 -o,--option <OPT[+]>
10051 pass option to comparison program
10052 -r,--rev <REV[+]>
10054 revision (DEPRECATED)
10055 --from <REV1>
10057 revision to diff from
10058 --to <REV2>
10060 revision to diff to
10061 -c,--change <REV>
10063 change made by revision
10064 --per-file
10066 compare each file instead of revision snapshots
10067 --confirm
10069 prompt user before each external program invocation
10070 --patch
10072 compare patches for two revisions
10073 -I,--include <PATTERN[+]>
10075 include names matching the given patterns
10076 -X,--exclude <PATTERN[+]>
10078 exclude names matching the given patterns
10079 -S, --subrepos
10081 recurse into subrepositories
10082 [+] marked option can be specified multiple times
10084 factotum
10086 http authentication with factotum
10087 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
10089 platforms to provide authentication information for HTTP access. Con‐
10090 figuration entries specified in the auth section as well as authentica‐
10091 tion information provided in the repository URL are fully supported. If
10092 no prefix is specified, a value of "*" will be assumed.
10093 By default, keys are specified as:
10095 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
10097 If the factotum extension is unable to read the required key, one will
10099 be requested interactively.
10100 A configuration section is available to customize runtime behavior. By
10102 default, these entries are:
10103 [factotum]
10105 executable = /bin/auth/factotum
10106 mountpoint = /mnt/factotum
10107 service = hg
10108 The executable entry defines the full path to the factotum binary. The
10110 mountpoint entry defines the path to the factotum file service. Lastly,
10111 the service entry controls the service name used when reading keys.
10112 fastannotate
10114 yet another annotate implementation that might be faster (EXPERIMENTAL)
10115 The fastannotate extension provides a 'fastannotate' command that makes
10117 use of the linelog data structure as a cache layer and is expected to
10118 be faster than the vanilla 'annotate' if the cache is present.
10119 In most cases, fastannotate requires a setup that mainbranch is some
10121 pointer that always moves forward, to be most efficient.
10122 Using fastannotate together with linkrevcache would speed up building
10124 the annotate cache greatly. Run "debugbuildlinkrevcache" before "debug‐
10125 buildannotatecache".
10126 [fastannotate]
10128 # specify the main branch head. the internal linelog will only contain
10129 # the linear (ignoring p2) "mainbranch". since linelog cannot move
10130 # backwards without a rebuild, this should be something that always moves
10131 # forward, usually it is "master" or "@".
10132 mainbranch = master
10133 # fastannotate supports different modes to expose its feature.
10135 # a list of combination:
10136 # - fastannotate: expose the feature via the "fastannotate" command which
10137 # deals with everything in a most efficient way, and provides extra
10138 # features like --deleted etc.
10139 # - fctx: replace fctx.annotate implementation. note:
10140 # a. it is less efficient than the "fastannotate" command
10141 # b. it will make it practically impossible to access the old (disk
10142 # side-effect free) annotate implementation
10143 # c. it implies "hgweb".
10144 # - hgweb: replace hgweb's annotate implementation. conflict with "fctx".
10145 # (default: fastannotate)
10146 modes = fastannotate
10147 # default format when no format flags are used (default: number)
10149 defaultformat = changeset, user, date
10150 # serve the annotate cache via wire protocol (default: False)
10152 # tip: the .hg/fastannotate directory is portable - can be rsynced
10153 server = True
10154 # build annotate cache on demand for every client request (default: True)
10156 # disabling it could make server response faster, useful when there is a
10157 # cronjob building the cache.
10158 serverbuildondemand = True
10159 # update local annotate cache from remote on demand
10161 client = False
10162 # path to use when connecting to the remote server (default: default)
10164 remotepath = default
10165 # minimal length of the history of a file required to fetch linelog from
10167 # the server. (default: 10)
10168 clientfetchthreshold = 10
10169 # for "fctx" mode, always follow renames regardless of command line option.
10171 # this is a BC with the original command but will reduced the space needed
10172 # for annotate cache, and is useful for client-server setup since the
10173 # server will only provide annotate cache with default options (i.e. with
10174 # follow). do not affect "fastannotate" mode. (default: True)
10175 forcefollow = True
10176 # for "fctx" mode, always treat file as text files, to skip the "isbinary"
10178 # check. this is consistent with the "fastannotate" command and could help
10179 # to avoid a file fetch if remotefilelog is used. (default: True)
10180 forcetext = True
10181 # use unfiltered repo for better performance.
10183 unfilteredrepo = True
10184 # sacrifice correctness in some corner cases for performance. it does not
10186 # affect the correctness of the annotate cache being built. the option
10187 # is experimental and may disappear in the future (default: False)
10188 perfhack = True
10189 Commands
10191 Uncategorized commands
10192 fastexport
10193 export repositories as git fast-import stream
10194 Commands
10196 Change import/export
10197 fastexport
10198 export repository as git fast-import stream:
10199 hg fastexport [OPTION]... [REV]...
10201 This command lets you dump a repository as a human-readable text
10203 stream. It can be piped into corresponding import routines like "git
10204 fast-import". Incremental dumps can be created by using marks files.
10205 Options:
10207 -r,--rev <REV[+]>
10209 revisions to export
10210 -i,--import-marks <FILE>
10212 old marks file to read
10213 -e,--export-marks <FILE>
10215 new marks file to write
10216 -A,--authormap <FILE>
10218 remap usernames using this file
10219 [+] marked option can be specified multiple times
10221 fetch
10223 pull, update and merge in one command (DEPRECATED)
10224 Commands
10226 Remote repository management
10227 fetch
10228 pull changes from a remote repository, merge new changes if needed.:
10229 hg fetch [SOURCE]
10231 This finds all changes from the repository at the specified path or URL
10233 and adds them to the local repository.
10234 If the pulled changes add a new branch head, the head is automatically
10236 merged, and the result of the merge is committed. Otherwise, the work‐
10237 ing directory is updated to include the new changes.
10238 When a merge is needed, the working directory is first updated to the
10240 newly pulled changes. Local changes are then merged into the pulled
10241 changes. To switch the merge order, use --switch-parent.
10242 See hg help dates for a list of formats valid for -d/--date.
10244 Returns 0 on success.
10246 Options:
10248 -r,--rev <REV[+]>
10250 a specific revision you would like to pull
10251 --edit invoke editor on commit messages
10253 --force-editor
10255 edit commit message (DEPRECATED)
10256 --switch-parent
10258 switch parents when merging
10259 -m,--message <TEXT>
10261 use text as commit message
10262 -l,--logfile <FILE>
10264 read commit message from file
10265 -d,--date <DATE>
10267 record the specified date as commit date
10268 -u,--user <USER>
10270 record the specified user as committer
10271 -e,--ssh <CMD>
10273 specify ssh command to use
10274 --remotecmd <CMD>
10276 specify hg command to run on the remote side
10277 --insecure
10279 do not verify server certificate (ignoring web.cacerts config)
10280 [+] marked option can be specified multiple times
10282 fix
10284 rewrite file content in changesets or working copy (EXPERIMENTAL)
10285 Provides a command that runs configured tools on the contents of modi‐
10287 fied files, writing back any fixes to the working copy or replacing
10288 changesets.
10289 Here is an example configuration that causes hg fix to apply automatic
10291 formatting fixes to modified lines in C++ code:
10292 [fix]
10294 clang-format:command=clang-format --assume-filename={rootpath}
10295 clang-format:linerange=--lines={first}:{last}
10296 clang-format:pattern=set:**.cpp or **.hpp
10297 The :command suboption forms the first part of the shell command that
10299 will be used to fix a file. The content of the file is passed on stan‐
10300 dard input, and the fixed file content is expected on standard output.
10301 Any output on standard error will be displayed as a warning. If the
10302 exit status is not zero, the file will not be affected. A placeholder
10303 warning is displayed if there is a non-zero exit status but no standard
10304 error output. Some values may be substituted into the command:
10305 {rootpath} The path of the file being fixed, relative to the repo root
10307 {basename} The name of the file being fixed, without the directory path
10308 If the :linerange suboption is set, the tool will only be run if there
10310 are changed lines in a file. The value of this suboption is appended to
10311 the shell command once for every range of changed lines in the file.
10312 Some values may be substituted into the command:
10313 {first} The 1-based line number of the first line in the modified range
10315 {last} The 1-based line number of the last line in the modified range
10316 Deleted sections of a file will be ignored by :linerange, because there
10318 is no corresponding line range in the version being fixed.
10319 By default, tools that set :linerange will only be executed if there is
10321 at least one changed line range. This is meant to prevent accidents
10322 like running a code formatter in such a way that it unexpectedly refor‐
10323 mats the whole file. If such a tool needs to operate on unchanged
10324 files, it should set the :skipclean suboption to false.
10325 The :pattern suboption determines which files will be passed through
10327 each configured tool. See hg help patterns for possible values. How‐
10328 ever, all patterns are relative to the repo root, even if that text
10329 says they are relative to the current working directory. If there are
10330 file arguments to hg fix, the intersection of these patterns is used.
10331 There is also a configurable limit for the maximum size of file that
10333 will be processed by hg fix:
10334 [fix]
10336 maxfilesize = 2MB
10337 Normally, execution of configured tools will continue after a failure
10339 (indicated by a non-zero exit status). It can also be configured to
10340 abort after the first such failure, so that no files will be affected
10341 if any tool fails. This abort will also cause hg fix to exit with a
10342 non-zero status:
10343 [fix]
10345 failure = abort
10346 When multiple tools are configured to affect a file, they execute in an
10348 order defined by the :priority suboption. The priority suboption has a
10349 default value of zero for each tool. Tools are executed in order of de‐
10350 scending priority. The execution order of tools with equal priority is
10351 unspecified. For example, you could use the 'sort' and 'head' utilities
10352 to keep only the 10 smallest numbers in a text file by ensuring that
10353 'sort' runs before 'head':
10354 [fix]
10356 sort:command = sort -n
10357 head:command = head -n 10
10358 sort:pattern = numbers.txt
10359 head:pattern = numbers.txt
10360 sort:priority = 2
10361 head:priority = 1
10362 To account for changes made by each tool, the line numbers used for in‐
10364 cremental formatting are recomputed before executing the next tool. So,
10365 each tool may see different values for the arguments added by the :lin‐
10366 erange suboption.
10367 Each fixer tool is allowed to return some metadata in addition to the
10369 fixed file content. The metadata must be placed before the file content
10370 on stdout, separated from the file content by a zero byte. The metadata
10371 is parsed as a JSON value (so, it should be UTF-8 encoded and contain
10372 no zero bytes). A fixer tool is expected to produce this metadata en‐
10373 coding if and only if the :metadata suboption is true:
10374 [fix]
10376 tool:command = tool --prepend-json-metadata
10377 tool:metadata = true
10378 The metadata values are passed to hooks, which can be used to print
10380 summaries or perform other post-fixing work. The supported hooks are:
10381 "postfixfile"
10383 Run once for each file in each revision where any fixer tools made changes
10384 to the file content. Provides "$HG_REV" and "$HG_PATH" to identify the file,
10385 and "$HG_METADATA" with a map of fixer names to metadata values from fixer
10386 tools that affected the file. Fixer tools that didn't affect the file have a
10387 value of None. Only fixer tools that executed are present in the metadata.
10388 "postfix"
10390 Run once after all files and revisions have been handled. Provides
10391 "$HG_REPLACEMENTS" with information about what revisions were created and
10392 made obsolete. Provides a boolean "$HG_WDIRWRITTEN" to indicate whether any
10393 files in the working copy were updated. Provides a list "$HG_METADATA"
10394 mapping fixer tool names to lists of metadata values returned from
10395 executions that modified a file. This aggregates the same metadata
10396 previously passed to the "postfixfile" hook.
10397 Fixer tools are run in the repository's root directory. This allows
10399 them to read configuration files from the working copy, or even write
10400 to the working copy. The working copy is not updated to match the re‐
10401 vision being fixed. In fact, several revisions may be fixed in paral‐
10402 lel. Writes to the working copy are not amended into the revision being
10403 fixed; fixer tools should always write fixed file content back to std‐
10404 out as documented above.
10405 Commands
10407 File content management
10408 fix
10409 rewrite file content in changesets or working directory:
10410 hg fix [OPTION]... [FILE]...
10412 Runs any configured tools to fix the content of files. Only affects
10414 files with changes, unless file arguments are provided. Only affects
10415 changed lines of files, unless the --whole flag is used. Some tools may
10416 always affect the whole file regardless of --whole.
10417 If --working-dir is used, files with uncommitted changes in the working
10419 copy will be fixed. Note that no backup are made.
10420 If revisions are specified with --source, those revisions and their de‐
10422 scendants will be checked, and they may be replaced with new revisions
10423 that have fixed file content. By automatically including the descen‐
10424 dants, no merging, rebasing, or evolution will be required. If an an‐
10425 cestor of the working copy is included, then the working copy itself
10426 will also be fixed, and the working copy will be updated to the fixed
10427 parent.
10428 When determining what lines of each file to fix at each revision, the
10430 whole set of revisions being fixed is considered, so that fixes to ear‐
10431 lier revisions are not forgotten in later ones. The --base flag can be
10432 used to override this default behavior, though it is not usually desir‐
10433 able to do so.
10434 Options:
10436 --all fix all non-public non-obsolete revisions
10438 --base <REV[+]>
10440 revisions to diff against (overrides automatic selection, and
10441 applies to every revision being fixed)
10442 -r,--rev <REV[+]>
10444 revisions to fix (ADVANCED)
10445 -s,--source <REV[+]>
10447 fix the specified revisions and their descendants
10448 -w, --working-dir
10450 fix the working directory
10451 --whole
10453 always fix every line of a file
10454 [+] marked option can be specified multiple times
10456 fsmonitor
10458 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
10459 Integrates the file-watching program Watchman with Mercurial to produce
10461 faster status results.
10462 On a particular Linux system, for a real-world repository with over
10464 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
10465 the same system, with fsmonitor it takes about 0.3 seconds.
10466 fsmonitor requires no configuration -- it will tell Watchman about your
10468 repository as necessary. You'll need to install Watchman from
10469 https://facebook.github.io/watchman/ and make sure it is in your PATH.
10470 fsmonitor is incompatible with the largefiles and eol extensions, and
10472 will disable itself if any of those are active.
10473 The following configuration options exist:
10475 [fsmonitor]
10477 mode = {off, on, paranoid}
10478 When mode = off, fsmonitor will disable itself (similar to not loading
10480 the extension at all). When mode = on, fsmonitor will be enabled (the
10481 default). When mode = paranoid, fsmonitor will query both Watchman and
10482 the filesystem, and ensure that the results are consistent.
10483 [fsmonitor]
10485 timeout = (float)
10486 A value, in seconds, that determines how long fsmonitor will wait for
10488 Watchman to return results. Defaults to 2.0.
10489 [fsmonitor]
10491 blacklistusers = (list of userids)
10492 A list of usernames for which fsmonitor will disable itself altogether.
10494 [fsmonitor]
10496 walk_on_invalidate = (boolean)
10497 Whether or not to walk the whole repo ourselves when our cached state
10499 has been invalidated, for example when Watchman has been restarted or
10500 .hgignore rules have been changed. Walking the repo in that case can
10501 result in competing for I/O with Watchman. For large repos it is recom‐
10502 mended to set this value to false. You may wish to set this to true if
10503 you have a very fast filesystem that can outpace the IPC overhead of
10504 getting the result data for the full repo from Watchman. Defaults to
10505 false.
10506 [fsmonitor]
10508 warn_when_unused = (boolean)
10509 Whether to print a warning during certain operations when fsmonitor
10511 would be beneficial to performance but isn't enabled.
10512 [fsmonitor]
10514 warn_update_file_count = (integer)
10515 # or when mercurial is built with rust support
10516 warn_update_file_count_rust = (integer)
10517 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
10519 be printed during working directory updates if this many files will be
10520 created.
10521 git
10523 grant Mercurial the ability to operate on Git repositories. (EXPERIMEN‐
10524 TAL)
10525 This is currently super experimental. It probably will consume your
10527 firstborn a la Rumpelstiltskin, etc.
10528 githelp
10530 try mapping git commands to Mercurial commands
10531 Tries to map a given git command to a Mercurial command:
10533 $ hg githelp -- git checkout master hg update master
10535 If an unknown command or parameter combination is detected, an error is
10537 produced.
10538 Commands
10540 Help
10541 githelp
10542 suggests the Mercurial equivalent of the given git command:
10543 hg githelp
10545 Usage: hg githelp -- <git command>
10547 aliases: git
10549 gpg
10551 commands to sign and verify changesets
10552 Commands
10554 Signing changes (GPG)
10555 sigcheck
10556 verify all the signatures there may be for a particular revision:
10557 hg sigcheck REV
10559 verify all the signatures there may be for a particular revision
10561 sign
10563 add a signature for the current or given revision:
10564 hg sign [OPTION]... [REV]...
10566 If no revision is given, the parent of the working directory is used,
10568 or tip if no revision is checked out.
10569 The gpg.cmd config setting can be used to specify the command to run. A
10571 default key can be specified with gpg.key.
10572 See hg help dates for a list of formats valid for -d/--date.
10574 Options:
10576 -l, --local
10578 make the signature local
10579 -f, --force
10581 sign even if the sigfile is modified
10582 --no-commit
10584 do not commit the sigfile after signing
10585 -k,--key <ID>
10587 the key id to sign with
10588 -m,--message <TEXT>
10590 use text as commit message
10591 -e, --edit
10593 invoke editor on commit messages
10594 -d,--date <DATE>
10596 record the specified date as commit date
10597 -u,--user <USER>
10599 record the specified user as committer
10600 sigs
10602 list signed changesets:
10603 hg sigs
10605 list signed changesets
10607 graphlog
10609 command to view revision graphs from a shell (DEPRECATED)
10610 The functionality of this extension has been include in core Mercurial
10612 since version 2.3. Please use hg log -G ... instead.
10613 This extension adds a --graph option to the incoming, outgoing and log
10615 commands. When this options is given, an ASCII representation of the
10616 revision graph is also shown.
10617 Commands
10619 Change navigation
10620 glog
10621 show revision history alongside an ASCII revision graph:
10622 hg glog [OPTION]... [FILE]
10624 Print a revision history alongside a revision graph drawn with ASCII
10626 characters.
10627 Nodes printed as an @ character are parents of the working directory.
10629 This is an alias to hg log -G.
10631 Options:
10633 -f, --follow
10635 follow changeset history, or file history across copies and re‐
10636 names
10637 --follow-first
10639 only follow the first parent of merge changesets (DEPRECATED)
10640 -d,--date <DATE>
10642 show revisions matching date spec
10643 -C, --copies
10645 show copied files
10646 -k,--keyword <TEXT[+]>
10648 do case-insensitive search for a given text
10649 -r,--rev <REV[+]>
10651 show the specified revision or revset
10652 --removed
10654 include revisions where files were removed
10655 -m, --only-merges
10657 show only merges (DEPRECATED)
10658 -u,--user <USER[+]>
10660 revisions committed by user
10661 --only-branch <BRANCH[+]>
10663 show only changesets within the given named branch (DEPRECATED)
10664 -b,--branch <BRANCH[+]>
10666 show changesets within the given named branch
10667 -P,--prune <REV[+]>
10669 do not display revision or any of its ancestors
10670 -p, --patch
10672 show patch
10673 -g, --git
10675 use git extended diff format
10676 -l,--limit <NUM>
10678 limit number of changes displayed
10679 -M, --no-merges
10681 do not show merges
10682 --stat output diffstat-style summary of changes
10684 -G, --graph
10686 show the revision DAG
10687 --style <STYLE>
10689 display using template map file (DEPRECATED)
10690 -T,--template <TEMPLATE>
10692 display with template
10693 -I,--include <PATTERN[+]>
10695 include names matching the given patterns
10696 -X,--exclude <PATTERN[+]>
10698 exclude names matching the given patterns
10699 [+] marked option can be specified multiple times
10701 hgk
10703 browse the repository in a graphical way
10704 The hgk extension allows browsing the history of a repository in a
10706 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
10707 distributed with Mercurial.)
10708 hgk consists of two parts: a Tcl script that does the displaying and
10710 querying of information, and an extension to Mercurial named hgk.py,
10711 which provides hooks for hgk to get information. hgk can be found in
10712 the contrib directory, and the extension is shipped in the hgext repos‐
10713 itory, and needs to be enabled.
10714 The hg view command will launch the hgk Tcl script. For this command to
10716 work, hgk must be in your search path. Alternately, you can specify the
10717 path to hgk in your configuration file:
10718 [hgk]
10720 path = /location/of/hgk
10721 hgk can make use of the extdiff extension to visualize revisions. As‐
10723 suming you had already configured extdiff vdiff command, just add:
10724 [hgk]
10726 vdiff=vdiff
10727 Revisions context menu will now display additional entries to fire vd‐
10729 iff on hovered and selected revisions.
10730 Commands
10732 Change navigation
10733 view
10734 start interactive history viewer:
10735 hg view [-l LIMIT] [REVRANGE]
10737 start interactive history viewer
10739 Options:
10741 -l,--limit <NUM>
10743 limit number of changes displayed
10744 Uncategorized commands
10746 highlight
10747 syntax highlighting for hgweb (requires Pygments)
10748 It depends on the Pygments syntax highlighting library:
10750 http://pygments.org/
10751 There are the following configuration options:
10753 [web]
10755 pygments_style = <style> (default: colorful)
10756 highlightfiles = <fileset> (default: size('<5M'))
10757 highlightonlymatchfilename = <bool> (default False)
10758 highlightonlymatchfilename will only highlight files if their type
10760 could be identified by their filename. When this is not enabled (the
10761 default), Pygments will try very hard to identify the file type from
10762 content and any match (even matches with a low confidence score) will
10763 be used.
10764 histedit
10766 interactive history editing
10767 With this extension installed, Mercurial gains one new command: histe‐
10769 dit. Usage is as follows, assuming the following history:
10770 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
10772 | Add delta
10773 |
10774 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
10775 | Add gamma
10776 |
10777 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
10778 | Add beta
10779 |
10780 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10781 Add alpha
10782 If you were to run hg histedit c561b4e977df, you would see the follow‐
10784 ing file open in your editor:
10785 pick c561b4e977df Add beta
10787 pick 030b686bedc4 Add gamma
10788 pick 7c2fd3b9020c Add delta
10789 # Edit history between c561b4e977df and 7c2fd3b9020c
10791 #
10792 # Commits are listed from least to most recent
10793 #
10794 # Commands:
10795 # p, pick = use commit
10796 # e, edit = use commit, but allow edits before making new commit
10797 # f, fold = use commit, but combine it with the one above
10798 # r, roll = like fold, but discard this commit's description and date
10799 # d, drop = remove commit from history
10800 # m, mess = edit commit message without changing commit content
10801 # b, base = checkout changeset and apply further changesets from there
10802 #
10803 In this file, lines beginning with # are ignored. You must specify a
10805 rule for each revision in your history. For example, if you had meant
10806 to add gamma before beta, and then wanted to add delta in the same re‐
10807 vision as beta, you would reorganize the file to look like this:
10808 pick 030b686bedc4 Add gamma
10810 pick c561b4e977df Add beta
10811 fold 7c2fd3b9020c Add delta
10812 # Edit history between c561b4e977df and 7c2fd3b9020c
10814 #
10815 # Commits are listed from least to most recent
10816 #
10817 # Commands:
10818 # p, pick = use commit
10819 # e, edit = use commit, but allow edits before making new commit
10820 # f, fold = use commit, but combine it with the one above
10821 # r, roll = like fold, but discard this commit's description and date
10822 # d, drop = remove commit from history
10823 # m, mess = edit commit message without changing commit content
10824 # b, base = checkout changeset and apply further changesets from there
10825 #
10826 At which point you close the editor and histedit starts working. When
10828 you specify a fold operation, histedit will open an editor when it
10829 folds those revisions together, offering you a chance to clean up the
10830 commit message:
10831 Add beta
10833 ***
10834 Add delta
10835 Edit the commit message to your liking, then close the editor. The date
10837 used for the commit will be the later of the two commits' dates. For
10838 this example, let's assume that the commit message was changed to Add
10839 beta and delta. After histedit has run and had a chance to remove any
10840 old or temporary revisions it needed, the history looks like this:
10841 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
10843 | Add beta and delta.
10844 |
10845 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10846 | Add gamma
10847 |
10848 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10849 Add alpha
10850 Note that histedit does not remove any revisions (even its own tempo‐
10852 rary ones) until after it has completed all the editing operations, so
10853 it will probably perform several strip operations when it's done. For
10854 the above example, it had to run strip twice. Strip can be slow depend‐
10855 ing on a variety of factors, so you might need to be a little patient.
10856 You can choose to keep the original revisions by passing the --keep
10857 flag.
10858 The edit operation will drop you back to a command prompt, allowing you
10860 to edit files freely, or even use hg record to commit some changes as a
10861 separate commit. When you're done, any remaining uncommitted changes
10862 will be committed as well. When done, run hg histedit --continue to
10863 finish this step. If there are uncommitted changes, you'll be prompted
10864 for a new commit message, but the default commit message will be the
10865 original message for the edit ed revision, and the date of the original
10866 commit will be preserved.
10867 The message operation will give you a chance to revise a commit message
10869 without changing the contents. It's a shortcut for doing edit immedi‐
10870 ately followed by hg histedit --continue`.
10871 If histedit encounters a conflict when moving a revision (while han‐
10873 dling pick or fold), it'll stop in a similar manner to edit with the
10874 difference that it won't prompt you for a commit message when done. If
10875 you decide at this point that you don't like how much work it will be
10876 to rearrange history, or that you made a mistake, you can use hg histe‐
10877 dit --abort to abandon the new changes you have made and return to the
10878 state before you attempted to edit your history.
10879 If we clone the histedit-ed example repository above and add four more
10881 changes, such that we have the following history:
10882 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
10884 | Add theta
10885 |
10886 o 5 140988835471 2009-04-27 18:04 -0500 stefan
10887 | Add eta
10888 |
10889 o 4 122930637314 2009-04-27 18:04 -0500 stefan
10890 | Add zeta
10891 |
10892 o 3 836302820282 2009-04-27 18:04 -0500 stefan
10893 | Add epsilon
10894 |
10895 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
10896 | Add beta and delta.
10897 |
10898 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10899 | Add gamma
10900 |
10901 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10902 Add alpha
10903 If you run hg histedit --outgoing on the clone then it is the same as
10905 running hg histedit 836302820282. If you need plan to push to a reposi‐
10906 tory that Mercurial does not detect to be related to the source repo,
10907 you can add a --force option.
10908 Config
10910 Histedit rule lines are truncated to 80 characters by default. You can
10911 customize this behavior by setting a different length in your configu‐
10912 ration file:
10913 [histedit]
10915 linelen = 120 # truncate rule lines at 120 characters
10916 The summary of a change can be customized as well:
10918 [histedit]
10920 summary-template = '{rev} {bookmarks} {desc|firstline}'
10921 The customized summary should be kept short enough that rule lines will
10923 fit in the configured line length. See above if that requires cus‐
10924 tomization.
10925 hg histedit attempts to automatically choose an appropriate base revi‐
10927 sion to use. To change which base revision is used, define a revset in
10928 your configuration file:
10929 [histedit]
10931 defaultrev = only(.) & draft()
10932 By default each edited revision needs to be present in histedit com‐
10934 mands. To remove revision you need to use drop operation. You can con‐
10935 figure the drop to be implicit for missing commits by adding:
10936 [histedit]
10938 dropmissing = True
10939 By default, histedit will close the transaction after each action. For
10941 performance purposes, you can configure histedit to use a single trans‐
10942 action across the entire histedit. WARNING: This setting introduces a
10943 significant risk of losing the work you've done in a histedit if the
10944 histedit aborts unexpectedly:
10945 [histedit]
10947 singletransaction = True
10948 Commands
10950 Change manipulation
10951 histedit
10952 interactively edit changeset history:
10953 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
10955 This command lets you edit a linear series of changesets (up to and in‐
10957 cluding the working directory, which should be clean). You can:
10958 • pick to [re]order a changeset
10960 • drop to omit changeset
10962 • mess to reword the changeset commit message
10964 • fold to combine it with the preceding changeset (using the later
10966 date)
10967 • roll like fold, but discarding this commit's description and date
10969 • edit to edit this changeset (preserving date)
10971 • base to checkout changeset and apply further changesets from there
10973 There are a number of ways to select the root changeset:
10975 • Specify ANCESTOR directly
10977 • Use --outgoing -- it will be the first linear changeset not included
10979 in destination. (See hg help config.paths.default-push)
10980 • Otherwise, the value from the "histedit.defaultrev" config option is
10982 used as a revset to select the base revision when ANCESTOR is not
10983 specified. The first revision returned by the revset is used. By de‐
10984 fault, this selects the editable history that is unique to the ances‐
10985 try of the working directory.
10986 If you use --outgoing, this command will abort if there are ambiguous
10988 outgoing revisions. For example, if there are multiple branches con‐
10989 taining outgoing revisions.
10990 Use "min(outgoing() and ::.)" or similar revset specification instead
10992 of --outgoing to specify edit target revision exactly in such ambiguous
10993 situation. See hg help revsets for detail about selecting revisions.
10994 Examples:
10996 • A number of changes have been made. Revision 3 is no longer
10998 needed.
10999 Start history editing from revision 3:
11001 hg histedit -r 3
11003 An editor opens, containing the list of revisions, with specific
11005 actions specified:
11006 pick 5339bf82f0ca 3 Zworgle the foobar
11008 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11009 pick 0a9639fcda9d 5 Morgify the cromulancy
11010 Additional information about the possible actions to take appears
11012 below the list of revisions.
11013 To remove revision 3 from the history, its action (at the begin‐
11015 ning of the relevant line) is changed to 'drop':
11016 drop 5339bf82f0ca 3 Zworgle the foobar
11018 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11019 pick 0a9639fcda9d 5 Morgify the cromulancy
11020 • A number of changes have been made. Revision 2 and 4 need to be
11022 swapped.
11023 Start history editing from revision 2:
11025 hg histedit -r 2
11027 An editor opens, containing the list of revisions, with specific
11029 actions specified:
11030 pick 252a1af424ad 2 Blorb a morgwazzle
11032 pick 5339bf82f0ca 3 Zworgle the foobar
11033 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11034 To swap revision 2 and 4, its lines are swapped in the editor:
11036 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11038 pick 5339bf82f0ca 3 Zworgle the foobar
11039 pick 252a1af424ad 2 Blorb a morgwazzle
11040 Returns 0 on success, 1 if user intervention is required (not only for
11042 intentional "edit" command, but also for resolving unexpected con‐
11043 flicts).
11044 Options:
11046 --commands <FILE>
11048 read history edits from the specified file
11049 -c, --continue
11051 continue an edit already in progress
11052 --edit-plan
11054 edit remaining actions list
11055 -k, --keep
11057 don't strip old nodes after edit is complete
11058 --abort
11060 abort an edit in progress
11061 -o, --outgoing
11063 changesets not found in destination
11064 -f, --force
11066 force outgoing even for unrelated repositories
11067 -r,--rev <REV[+]>
11069 first revision to be edited
11070 -T,--template <TEMPLATE>
11072 display with template
11073 [+] marked option can be specified multiple times
11075 hooklib
11077 collection of simple hooks for common tasks (EXPERIMENTAL)
11078 This extension provides a number of simple hooks to handle issues com‐
11080 monly found in repositories with many contributors: - email notifica‐
11081 tion when changesets move from draft to public phase - email notifica‐
11082 tion when changesets are obsoleted - enforcement of draft phase for all
11083 incoming changesets - enforcement of a no-branch-merge policy - en‐
11084 forcement of a no-multiple-heads policy
11085 The implementation of the hooks is subject to change, e.g. whether to
11087 implement them as individual hooks or merge them into the notify exten‐
11088 sion as option. The functionality itself is planned to be supported
11089 long-term.
11090 infinitepush
11092 store some pushes in a remote blob store on the server (EXPERIMEN‐
11093 TAL)
11094 IMPORTANT: if you use this extension, please contact
11096 mercurial-devel@mercurial-scm.org ASAP. This extension is believed to
11097 be unused and barring learning of users of this functionality, we will
11098 delete this code at the end of 2020.
11099 [infinitepush] # Server-side and client-side option. Pattern of the
11101 infinitepush bookmark branchpattern = PATTERN
11102 # Server or client server = False
11104 # Server-side option. Possible values: 'disk' or 'sql'. Fails if not
11106 set indextype = disk
11107 # Server-side option. Used only if indextype=sql. # Format:
11109 'IP:PORT:DB_NAME:USER:PASSWORD' sqlhost = IP:PORT:DB_NAME:USER:PASS‐
11110 WORD
11111 # Server-side option. Used only if indextype=disk. # Filesystem
11113 path to the index store indexpath = PATH
11114 # Server-side option. Possible values: 'disk' or 'external' # Fails
11116 if not set storetype = disk
11117 # Server-side option. # Path to the binary that will save bundle to
11119 the bundlestore # Formatted cmd line will be passed to it (see
11120 put_args) put_binary = put
11121 # Serser-side option. Used only if storetype=external. # Format
11123 cmd-line string for put binary. Placeholder: {filename} put_args =
11124 {filename}
11125 # Server-side option. # Path to the binary that get bundle from the
11127 bundlestore. # Formatted cmd line will be passed to it (see
11128 get_args) get_binary = get
11129 # Serser-side option. Used only if storetype=external. # Format
11131 cmd-line string for get binary. Placeholders: {filename} {handle}
11132 get_args = {filename} {handle}
11133 # Server-side option logfile = FIlE
11135 # Server-side option loglevel = DEBUG
11137 # Server-side option. Used only if indextype=sql. # Sets mysql
11139 wait_timeout option. waittimeout = 300
11140 # Server-side option. Used only if indextype=sql. # Sets mysql inn‐
11142 odb_lock_wait_timeout option. locktimeout = 120
11143 # Server-side option. Used only if indextype=sql. # Name of the
11145 repository reponame = ''
11146 # Client-side option. Used by --list-remote option. List of remote
11148 scratch # patterns to list if no patterns are specified. default‐
11149 remotepatterns = ['*']
11150 # Instructs infinitepush to forward all received bundle2 parts to
11152 the # bundle for storage. Defaults to False. storeallparts = True
11153 # routes each incoming push to the bundlestore. defaults to False
11155 pushtobundlestore = True
11156 [remotenames] # Client-side option # This option should be set only
11158 if remotenames extension is enabled. # Whether remote bookmarks are
11159 tracked by remotenames extension. bookmarks = True
11160 journal
11162 track previous positions of bookmarks (EXPERIMENTAL)
11163 This extension adds a new command: hg journal, which shows you where
11165 bookmarks were previously located.
11166 Commands
11168 Change organization
11169 journal
11170 show the previous position of bookmarks and the working copy:
11171 hg journal [OPTION]... [BOOKMARKNAME]
11173 The journal is used to see the previous commits that bookmarks and the
11175 working copy pointed to. By default the previous locations for the
11176 working copy. Passing a bookmark name will show all the previous posi‐
11177 tions of that bookmark. Use the --all switch to show previous locations
11178 for all bookmarks and the working copy; each line will then include the
11179 bookmark name, or '.' for the working copy, as well.
11180 If name starts with re:, the remainder of the name is treated as a reg‐
11182 ular expression. To match a name that actually starts with re:, use the
11183 prefix literal:.
11184 By default hg journal only shows the commit hash and the command that
11186 was running at that time. -v/--verbose will show the prior hash, the
11187 user, and the time at which it happened.
11188 Use -c/--commits to output log information on each commit hash; at this
11190 point you can use the usual --patch, --git, --stat and --template
11191 switches to alter the log output for these.
11192 hg journal -T json can be used to produce machine readable output.
11194 Options:
11196 --all show history for all names
11198 -c, --commits
11200 show commit metadata
11201 -p, --patch
11203 show patch
11204 -g, --git
11206 use git extended diff format
11207 -l,--limit <NUM>
11209 limit number of changes displayed
11210 --stat output diffstat-style summary of changes
11212 --style <STYLE>
11214 display using template map file (DEPRECATED)
11215 -T,--template <TEMPLATE>
11217 display with template
11218 keyword
11220 expand keywords in tracked files
11221 This extension expands RCS/CVS-like or self-customized $Keywords$ in
11223 tracked text files selected by your configuration.
11224 Keywords are only expanded in local repositories and not stored in the
11226 change history. The mechanism can be regarded as a convenience for the
11227 current user or for archive distribution.
11228 Keywords expand to the changeset data pertaining to the latest change
11230 relative to the working directory parent of each file.
11231 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
11233 sections of hgrc files.
11234 Example:
11236 [keyword]
11238 # expand keywords in every python file except those matching "x*"
11239 **.py =
11240 x* = ignore
11241 [keywordset]
11243 # prefer svn- over cvs-like default keywordmaps
11244 svn = True
11245 Note The more specific you are in your filename patterns the less you
11247 lose speed in huge repositories.
11248 For [keywordmaps] template mapping and expansion demonstration and con‐
11250 trol run hg kwdemo. See hg help templates for a list of available tem‐
11251 plates and filters.
11252 Three additional date template filters are provided:
11254 utcdate
11256 "2006/09/18 15:13:13"
11258 svnutcdate
11260 "2006-09-18 15:13:13Z"
11262 svnisodate
11264 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
11266 The default template mappings (view with hg kwdemo -d) can be replaced
11268 with customized keywords and templates. Again, run hg kwdemo to control
11269 the results of your configuration changes.
11270 Before changing/disabling active keywords, you must run hg kwshrink to
11272 avoid storing expanded keywords in the change history.
11273 To force expansion after enabling it, or a configuration change, run hg
11275 kwexpand.
11276 Expansions spanning more than one line and incremental expansions, like
11278 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
11279 expands to the first line of the changeset description.
11280 Commands
11282 Uncategorized commands
11283 kwdemo
11284 print [keywordmaps] configuration and an expansion example:
11285 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
11287 Show current, custom, or default keyword template maps and their expan‐
11289 sions.
11290 Extend the current configuration by specifying maps as arguments and
11292 using -f/--rcfile to source an external hgrc file.
11293 Use -d/--default to disable current configuration.
11295 See hg help templates for information on templates and filters.
11297 Options:
11299 -d, --default
11301 show default keyword template maps
11302 -f,--rcfile <FILE>
11304 read maps from rcfile
11305 kwexpand
11307 expand keywords in the working directory:
11308 hg kwexpand [OPTION]... [FILE]...
11310 Run after (re)enabling keyword expansion.
11312 kwexpand refuses to run if given files contain local changes.
11314 Options:
11316 -I,--include <PATTERN[+]>
11318 include names matching the given patterns
11319 -X,--exclude <PATTERN[+]>
11321 exclude names matching the given patterns
11322 [+] marked option can be specified multiple times
11324 kwfiles
11326 show files configured for keyword expansion:
11327 hg kwfiles [OPTION]... [FILE]...
11329 List which files in the working directory are matched by the [keyword]
11331 configuration patterns.
11332 Useful to prevent inadvertent keyword expansion and to speed up execu‐
11334 tion by including only files that are actual candidates for expansion.
11335 See hg help keyword on how to construct patterns both for inclusion and
11337 exclusion of files.
11338 With -A/--all and -v/--verbose the codes used to show the status of
11340 files are:
11341 K = keyword expansion candidate
11343 k = keyword expansion candidate (not tracked)
11344 I = ignored
11345 i = ignored (not tracked)
11346 Options:
11348 -A, --all
11350 show keyword status flags of all files
11351 -i, --ignore
11353 show files excluded from expansion
11354 -u, --unknown
11356 only show unknown (not tracked) files
11357 -I,--include <PATTERN[+]>
11359 include names matching the given patterns
11360 -X,--exclude <PATTERN[+]>
11362 exclude names matching the given patterns
11363 [+] marked option can be specified multiple times
11365 kwshrink
11367 revert expanded keywords in the working directory:
11368 hg kwshrink [OPTION]... [FILE]...
11370 Must be run before changing/disabling active keywords.
11372 kwshrink refuses to run if given files contain local changes.
11374 Options:
11376 -I,--include <PATTERN[+]>
11378 include names matching the given patterns
11379 -X,--exclude <PATTERN[+]>
11381 exclude names matching the given patterns
11382 [+] marked option can be specified multiple times
11384 largefiles
11386 track large binary files
11387 Large binary files tend to be not very compressible, not very diffable,
11389 and not at all mergeable. Such files are not handled efficiently by
11390 Mercurial's storage format (revlog), which is based on compressed bi‐
11391 nary deltas; storing large binary files as regular Mercurial files
11392 wastes bandwidth and disk space and increases Mercurial's memory usage.
11393 The largefiles extension addresses these problems by adding a central‐
11394 ized client-server layer on top of Mercurial: largefiles live in a cen‐
11395 tral store out on the network somewhere, and you only fetch the revi‐
11396 sions that you need when you need them.
11397 largefiles works by maintaining a "standin file" in .hglf/ for each
11399 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
11400 line) and are tracked by Mercurial. Largefile revisions are identified
11401 by the SHA-1 hash of their contents, which is written to the standin.
11402 largefiles uses that revision ID to get/put largefile revisions from/to
11403 the central store. This saves both disk space and bandwidth, since you
11404 don't need to retrieve all historical revisions of large files when you
11405 clone or pull.
11406 To start a new repository or add new large binary files, just add
11408 --large to your hg add command. For example:
11409 $ dd if=/dev/urandom of=randomdata count=2000
11411 $ hg add --large randomdata
11412 $ hg commit -m "add randomdata as a largefile"
11413 When you push a changeset that adds/modifies largefiles to a remote
11415 repository, its largefile revisions will be uploaded along with it.
11416 Note that the remote Mercurial must also have the largefiles extension
11417 enabled for this to work.
11418 When you pull a changeset that affects largefiles from a remote reposi‐
11420 tory, the largefiles for the changeset will by default not be pulled
11421 down. However, when you update to such a revision, any largefiles
11422 needed by that revision are downloaded and cached (if they have never
11423 been downloaded before). One way to pull largefiles when pulling is
11424 thus to use --update, which will update your working copy to the latest
11425 pulled revision (and thereby downloading any new largefiles).
11426 If you want to pull largefiles you don't need for update yet, then you
11428 can use pull with the --lfrev option or the hg lfpull command.
11429 If you know you are pulling from a non-default location and want to
11431 download all the largefiles that correspond to the new changesets at
11432 the same time, then you can pull with --lfrev "pulled()".
11433 If you just want to ensure that you will have the largefiles needed to
11435 merge or rebase with new heads that you are pulling, then you can pull
11436 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
11437 files that are new in the heads you are pulling.
11438 Keep in mind that network access may now be required to update to
11440 changesets that you have not previously updated to. The nature of the
11441 largefiles extension means that updating is no longer guaranteed to be
11442 a local-only operation.
11443 If you already have large files tracked by Mercurial without the large‐
11445 files extension, you will need to convert your repository in order to
11446 benefit from largefiles. This is done with the hg lfconvert command:
11447 $ hg lfconvert --size 10 oldrepo newrepo
11449 In repositories that already have largefiles in them, any new file over
11451 10MB will automatically be added as a largefile. To change this thresh‐
11452 old, set largefiles.minsize in your Mercurial config file to the mini‐
11453 mum size in megabytes to track as a largefile, or use the --lfsize op‐
11454 tion to the add command (also in megabytes):
11455 [largefiles]
11457 minsize = 2
11458 $ hg add --lfsize 2
11460 The largefiles.patterns config option allows you to specify a list of
11462 filename patterns (see hg help patterns) that should always be tracked
11463 as largefiles:
11464 [largefiles]
11466 patterns =
11467 *.jpg
11468 re:.*\.(png|bmp)$
11469 library.zip
11470 content/audio/*
11471 Files that match one of these patterns will be added as largefiles re‐
11473 gardless of their size.
11474 The largefiles.minsize and largefiles.patterns config options will be
11476 ignored for any repositories not already containing a largefile. To add
11477 the first largefile to a repository, you must explicitly do so with the
11478 --large flag passed to the hg add command.
11479 Commands
11481 Uncategorized commands
11482 lfconvert
11483 convert a normal repository to a largefiles repository:
11484 hg lfconvert SOURCE DEST [FILE ...]
11486 Convert repository SOURCE to a new repository DEST, identical to SOURCE
11488 except that certain files will be converted as largefiles: specifi‐
11489 cally, any file that matches any PATTERN or whose size is above the
11490 minimum size threshold is converted as a largefile. The size used to
11491 determine whether or not to track a file as a largefile is the size of
11492 the first version of the file. The minimum size can be specified either
11493 with --size or in configuration as largefiles.size.
11494 After running this command you will need to make sure that largefiles
11496 is enabled anywhere you intend to push the new repository.
11497 Use --to-normal to convert largefiles back to normal files; after this,
11499 the DEST repository can be used without largefiles at all.
11500 Options:
11502 -s,--size <SIZE>
11504 minimum size (MB) for files to be converted as largefiles
11505 --to-normal
11507 convert from a largefiles repo to a normal repo
11508 lfpull
11510 pull largefiles for the specified revisions from the specified source:
11511 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
11513 Pull largefiles that are referenced from local changesets but missing
11515 locally, pulling from a remote repository to the local cache.
11516 If SOURCE is omitted, the 'default' path will be used. See hg help
11518 urls for more information.
11519 Some examples:
11521 • pull largefiles for all branch heads:
11523 hg lfpull -r "head() and not closed()"
11525 • pull largefiles on the default branch:
11527 hg lfpull -r "branch(default)"
11529 Options:
11531 -r,--rev <VALUE[+]>
11533 pull largefiles for these revisions
11534 -e,--ssh <CMD>
11536 specify ssh command to use
11537 --remotecmd <CMD>
11539 specify hg command to run on the remote side
11540 --insecure
11542 do not verify server certificate (ignoring web.cacerts config)
11543 [+] marked option can be specified multiple times
11545 lfs
11547 lfs - large file support (EXPERIMENTAL)
11548 This extension allows large files to be tracked outside of the normal
11550 repository storage and stored on a centralized server, similar to the
11551 largefiles extension. The git-lfs protocol is used when communicating
11552 with the server, so existing git infrastructure can be harnessed. Even
11553 though the files are stored outside of the repository, they are still
11554 integrity checked in the same manner as normal files.
11555 The files stored outside of the repository are downloaded on demand,
11557 which reduces the time to clone, and possibly the local disk usage.
11558 This changes fundamental workflows in a DVCS, so careful thought should
11559 be given before deploying it. hg convert can be used to convert LFS
11560 repositories to normal repositories that no longer require this exten‐
11561 sion, and do so without changing the commit hashes. This allows the
11562 extension to be disabled if the centralized workflow becomes burden‐
11563 some. However, the pre and post convert clones will not be able to
11564 communicate with each other unless the extension is enabled on both.
11565 To start a new repository, or to add LFS files to an existing one, just
11567 create an .hglfs file as described below in the root directory of the
11568 repository. Typically, this file should be put under version control,
11569 so that the settings will propagate to other repositories with push and
11570 pull. During any commit, Mercurial will consult this file to determine
11571 if an added or modified file should be stored externally. The type of
11572 storage depends on the characteristics of the file at each commit. A
11573 file that is near a size threshold may switch back and forth between
11574 LFS and normal storage, as needed.
11575 Alternately, both normal repositories and largefile controlled reposi‐
11577 tories can be converted to LFS by using hg convert and the lfs.track
11578 config option described below. The .hglfs file should then be created
11579 and added, to control subsequent LFS selection. The hashes are also
11580 unchanged in this case. The LFS and non-LFS repositories can be dis‐
11581 tinguished because the LFS repository will abort any command if this
11582 extension is disabled.
11583 Committed LFS files are held locally, until the repository is pushed.
11585 Prior to pushing the normal repository data, the LFS files that are
11586 tracked by the outgoing commits are automatically uploaded to the con‐
11587 figured central server. No LFS files are transferred on hg pull or hg
11588 clone. Instead, the files are downloaded on demand as they need to be
11589 read, if a cached copy cannot be found locally. Both committing and
11590 downloading an LFS file will link the file to a usercache, to speed up
11591 future access. See the usercache config setting described below.
11592 The extension reads its configuration from a versioned .hglfs configu‐
11594 ration file found in the root of the working directory. The .hglfs file
11595 uses the same syntax as all other Mercurial configuration files. It
11596 uses a single section, [track].
11597 The [track] section specifies which files are stored as LFS (or not).
11599 Each line is keyed by a file pattern, with a predicate value. The
11600 first file pattern match is used, so put more specific patterns first.
11601 The available predicates are all(), none(), and size(). See "hg help
11602 filesets.size" for the latter.
11603 Example versioned .hglfs file:
11605 [track]
11607 # No Makefile or python file, anywhere, will be LFS
11608 **Makefile = none()
11609 **.py = none()
11610 **.zip = all()
11612 **.exe = size(">1MB")
11613 # Catchall for everything not matched above
11615 ** = size(">10MB")
11616 Configs:
11618 [lfs]
11620 # Remote endpoint. Multiple protocols are supported:
11621 # - http(s)://user:pass@example.com/path
11622 # git-lfs endpoint
11623 # - file:///tmp/path
11624 # local filesystem, usually for testing
11625 # if unset, lfs will assume the remote repository also handles blob storage
11626 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
11627 # use this value.
11628 # (default: unset)
11629 url = https://example.com/repo.git/info/lfs
11630 # Which files to track in LFS. Path tests are "**.extname" for file
11632 # extensions, and "path:under/some/directory" for path prefix. Both
11633 # are relative to the repository root.
11634 # File size can be tested with the "size()" fileset, and tests can be
11635 # joined with fileset operators. (See "hg help filesets.operators".)
11636 #
11637 # Some examples:
11638 # - all() # everything
11639 # - none() # nothing
11640 # - size(">20MB") # larger than 20MB
11641 # - !**.txt # anything not a *.txt file
11642 # - **.zip | **.tar.gz | **.7z # some types of compressed files
11643 # - path:bin # files under "bin" in the project root
11644 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
11645 # | (path:bin & !path:/bin/README) | size(">1GB")
11646 # (default: none())
11647 #
11648 # This is ignored if there is a tracked '.hglfs' file, and this setting
11649 # will eventually be deprecated and removed.
11650 track = size(">10M")
11651 # how many times to retry before giving up on transferring an object
11653 retry = 5
11654 # the local directory to store lfs files for sharing across local clones.
11656 # If not set, the cache is located in an OS specific cache location.
11657 usercache = /path/to/global/cache
11658 Commands
11660 Uncategorized commands
11661 logtoprocess
11662 send ui.log() data to a subprocess (EXPERIMENTAL)
11663 This extension lets you specify a shell command per ui.log() event,
11665 sending all remaining arguments to as environment variables to that
11666 command.
11667 Positional arguments construct a log message, which is passed in the
11669 MSG1 environment variables. Each keyword argument is set as a OPT_UP‐
11670 PERCASE_KEY variable (so the key is uppercased, and prefixed with
11671 OPT_). The original event name is passed in the EVENT environment vari‐
11672 able, and the process ID of mercurial is given in HGPID.
11673 So given a call ui.log('foo', 'bar %s ', 'baz', spam='eggs'), a script
11675 configured for the `foo event can expect an environment with MSG1=bar
11676 baz, and OPT_SPAM=eggs.
11677 Scripts are configured in the [logtoprocess] section, each key an event
11679 name. For example:
11680 [logtoprocess]
11682 commandexception = echo "$MSG1" > /var/log/mercurial_exceptions.log
11683 would log the warning message and traceback of any failed command dis‐
11685 patch.
11686 Scripts are run asynchronously as detached daemon processes; mercurial
11688 will not ensure that they exit cleanly.
11689 mq
11691 manage a stack of patches
11692 This extension lets you work with a stack of patches in a Mercurial
11694 repository. It manages two stacks of patches - all known patches, and
11695 applied patches (subset of known patches).
11696 Known patches are represented as patch files in the .hg/patches direc‐
11698 tory. Applied patches are both patch files and changesets.
11699 Common tasks (use hg help COMMAND for more details):
11701 create new patch qnew
11703 import existing patch qimport
11704 print patch series qseries
11706 print applied patches qapplied
11707 add known patch to applied stack qpush
11709 remove patch from applied stack qpop
11710 refresh contents of top applied patch qrefresh
11711 By default, mq will automatically use git patches when required to
11713 avoid losing file mode changes, copy records, binary files or empty
11714 files creations or deletions. This behavior can be configured with:
11715 [mq]
11717 git = auto/keep/yes/no
11718 If set to 'keep', mq will obey the [diff] section configuration while
11720 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
11721 mq will override the [diff] section and always generate git or regular
11722 patches, possibly losing data in the second case.
11723 It may be desirable for mq changesets to be kept in the secret phase
11725 (see hg help phases), which can be enabled with the following setting:
11726 [mq]
11728 secret = True
11729 You will by default be managing a patch queue named "patches". You can
11731 create other, independent patch queues with the hg qqueue command.
11732 If the working directory contains uncommitted files, qpush, qpop and
11734 qgoto abort immediately. If -f/--force is used, the changes are dis‐
11735 carded. Setting:
11736 [mq]
11738 keepchanges = True
11739 make them behave as if --keep-changes were passed, and non-conflicting
11741 local changes will be tolerated and preserved. If incompatible options
11742 such as -f/--force or --exact are passed, this setting is ignored.
11743 This extension used to provide a strip command. This command now lives
11745 in the strip extension.
11746 Commands
11748 Repository creation
11749 qclone
11750 clone main and patch repository at same time:
11751 hg qclone [OPTION]... SOURCE [DEST]
11753 If source is local, destination will have no patches applied. If source
11755 is remote, this command can not check if patches are applied in source,
11756 so cannot guarantee that patches are not applied in destination. If you
11757 clone remote repository, be sure before that it has no patches applied.
11758 Source patch repository is looked for in <src>/.hg/patches by default.
11760 Use -p <url> to change.
11761 The patch directory must be a nested Mercurial repository, as would be
11763 created by hg init --mq.
11764 Return 0 on success.
11766 Options:
11768 --pull use pull protocol to copy metadata
11770 -U, --noupdate
11772 do not update the new working directories
11773 --uncompressed
11775 use uncompressed transfer (fast over LAN)
11776 -p,--patches <REPO>
11778 location of source patch repository
11779 -e,--ssh <CMD>
11781 specify ssh command to use
11782 --remotecmd <CMD>
11784 specify hg command to run on the remote side
11785 --insecure
11787 do not verify server certificate (ignoring web.cacerts config)
11788 qinit
11790 init a new queue repository (DEPRECATED):
11791 hg qinit [-c]
11793 The queue repository is unversioned by default. If -c/--create-repo is
11795 specified, qinit will create a separate nested repository for patches
11796 (qinit -c may also be run later to convert an unversioned patch reposi‐
11797 tory into a versioned one). You can use qcommit to commit changes to
11798 this queue repository.
11799 This command is deprecated. Without -c, it's implied by other relevant
11801 commands. With -c, use hg init --mq instead.
11802 Options:
11804 -c, --create-repo
11806 create queue repository
11807 Change creation
11809 qcommit
11810 commit changes in the queue repository (DEPRECATED):
11811 hg qcommit [OPTION]... [FILE]...
11813 This command is deprecated; use hg commit --mq instead.
11815 Options:
11817 -A, --addremove
11819 mark new/missing files as added/removed before committing
11820 --close-branch
11822 mark a branch head as closed
11823 --amend
11825 amend the parent of the working directory
11826 -s, --secret
11828 use the secret phase for committing
11829 -e, --edit
11831 invoke editor on commit messages
11832 --force-close-branch
11834 forcibly close branch from a non-head changeset (ADVANCED)
11835 -i, --interactive
11837 use interactive mode
11838 -I,--include <PATTERN[+]>
11840 include names matching the given patterns
11841 -X,--exclude <PATTERN[+]>
11843 exclude names matching the given patterns
11844 -m,--message <TEXT>
11846 use text as commit message
11847 -l,--logfile <FILE>
11849 read commit message from file
11850 -d,--date <DATE>
11852 record the specified date as commit date
11853 -u,--user <USER>
11855 record the specified user as committer
11856 -S, --subrepos
11858 recurse into subrepositories
11859 [+] marked option can be specified multiple times
11861 aliases: qci
11863 qnew
11865 create a new patch:
11866 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
11868 qnew creates a new patch on top of the currently-applied patch (if
11870 any). The patch will be initialized with any outstanding changes in the
11871 working directory. You may also use -I/--include, -X/--exclude, and/or
11872 a list of files after the patch name to add only changes to matching
11873 files to the new patch, leaving the rest as uncommitted modifications.
11874 -u/--user and -d/--date can be used to set the (given) user and date,
11876 respectively. -U/--currentuser and -D/--currentdate set user to current
11877 user and date to current date.
11878 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
11880 the commit message. If none is specified, the header is empty and the
11881 commit message is '[mq]: PATCH'.
11882 Use the -g/--git option to keep the patch in the git extended diff for‐
11884 mat. Read the diffs help topic for more information on why this is im‐
11885 portant for preserving permission changes and copy/rename information.
11886 Returns 0 on successful creation of a new patch.
11888 Options:
11890 -e, --edit
11892 invoke editor on commit messages
11893 -f, --force
11895 import uncommitted changes (DEPRECATED)
11896 -g, --git
11898 use git extended diff format
11899 -U, --currentuser
11901 add "From: <current user>" to patch
11902 -u,--user <USER>
11904 add "From: <USER>" to patch
11905 -D, --currentdate
11907 add "Date: <current date>" to patch
11908 -d,--date <DATE>
11910 add "Date: <DATE>" to patch
11911 -I,--include <PATTERN[+]>
11913 include names matching the given patterns
11914 -X,--exclude <PATTERN[+]>
11916 exclude names matching the given patterns
11917 -m,--message <TEXT>
11919 use text as commit message
11920 -l,--logfile <FILE>
11922 read commit message from file
11923 [+] marked option can be specified multiple times
11925 qrefresh
11927 update the current patch:
11928 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
11930 If any file patterns are provided, the refreshed patch will contain
11932 only the modifications that match those patterns; the remaining modifi‐
11933 cations will remain in the working directory.
11934 If -s/--short is specified, files currently included in the patch will
11936 be refreshed just like matched files and remain in the patch.
11937 If -e/--edit is specified, Mercurial will start your configured editor
11939 for you to enter a message. In case qrefresh fails, you will find a
11940 backup of your message in .hg/last-message.txt.
11941 hg add/remove/copy/rename work as usual, though you might want to use
11943 git-style patches (-g/--git or [diff] git=1) to track copies and re‐
11944 names. See the diffs help topic for more information on the git diff
11945 format.
11946 Returns 0 on success.
11948 Options:
11950 -e, --edit
11952 invoke editor on commit messages
11953 -g, --git
11955 use git extended diff format
11956 -s, --short
11958 refresh only files already in the patch and specified files
11959 -U, --currentuser
11961 add/update author field in patch with current user
11962 -u,--user <USER>
11964 add/update author field in patch with given user
11965 -D, --currentdate
11967 add/update date field in patch with current date
11968 -d,--date <DATE>
11970 add/update date field in patch with given date
11971 -I,--include <PATTERN[+]>
11973 include names matching the given patterns
11974 -X,--exclude <PATTERN[+]>
11976 exclude names matching the given patterns
11977 -m,--message <TEXT>
11979 use text as commit message
11980 -l,--logfile <FILE>
11982 read commit message from file
11983 [+] marked option can be specified multiple times
11985 Change manipulation
11987 qfold
11988 fold the named patches into the current patch:
11989 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
11991 Patches must not yet be applied. Each patch will be successively ap‐
11993 plied to the current patch in the order given. If all the patches apply
11994 successfully, the current patch will be refreshed with the new cumula‐
11995 tive patch, and the folded patches will be deleted. With -k/--keep, the
11996 folded patch files will not be removed afterwards.
11997 The header for each folded patch will be concatenated with the current
11999 patch header, separated by a line of * * *.
12000 Returns 0 on success.
12002 Options:
12004 -e, --edit
12006 invoke editor on commit messages
12007 -k, --keep
12009 keep folded patch files
12010 -m,--message <TEXT>
12012 use text as commit message
12013 -l,--logfile <FILE>
12015 read commit message from file
12016 Change organization
12018 qapplied
12019 print the patches already applied:
12020 hg qapplied [-1] [-s] [PATCH]
12022 Returns 0 on success.
12024 Options:
12026 -1, --last
12028 show only the preceding applied patch
12029 -s, --summary
12031 print first line of patch header
12032 qdelete
12034 remove patches from queue:
12035 hg qdelete [-k] [PATCH]...
12037 The patches must not be applied, and at least one patch is required.
12039 Exact patch identifiers must be given. With -k/--keep, the patch files
12040 are preserved in the patch directory.
12041 To stop managing a patch and move it into permanent history, use the hg
12043 qfinish command.
12044 Options:
12046 -k, --keep
12048 keep patch file
12049 -r,--rev <REV[+]>
12051 stop managing a revision (DEPRECATED)
12052 [+] marked option can be specified multiple times
12054 aliases: qremove qrm
12056 qfinish
12058 move applied patches into repository history:
12059 hg qfinish [-a] [REV]...
12061 Finishes the specified revisions (corresponding to applied patches) by
12063 moving them out of mq control into regular repository history.
12064 Accepts a revision range or the -a/--applied option. If --applied is
12066 specified, all applied mq revisions are removed from mq control. Other‐
12067 wise, the given revisions must be at the base of the stack of applied
12068 patches.
12069 This can be especially useful if your changes have been applied to an
12071 upstream repository, or if you are about to push your changes to up‐
12072 stream.
12073 Returns 0 on success.
12075 Options:
12077 -a, --applied
12079 finish all applied changesets
12080 qgoto
12082 push or pop patches until named patch is at top of stack:
12083 hg qgoto [OPTION]... PATCH
12085 Returns 0 on success.
12087 Options:
12089 --keep-changes
12091 tolerate non-conflicting local changes
12092 -f, --force
12094 overwrite any local changes
12095 --no-backup
12097 do not save backup copies of files
12098 qguard
12100 set or print guards for a patch:
12101 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
12103 Guards control whether a patch can be pushed. A patch with no guards is
12105 always pushed. A patch with a positive guard ("+foo") is pushed only if
12106 the hg qselect command has activated it. A patch with a negative guard
12107 ("-foo") is never pushed if the hg qselect command has activated it.
12108 With no arguments, print the currently active guards. With arguments,
12110 set guards for the named patch.
12111 Note Specifying negative guards now requires '--'.
12113 To set guards on another patch:
12115 hg qguard other.patch -- +2.6.17 -stable
12117 Returns 0 on success.
12119 Options:
12121 -l, --list
12123 list all patches and guards
12124 -n, --none
12126 drop all guards
12127 qheader
12129 print the header of the topmost or specified patch:
12130 hg qheader [PATCH]
12132 Returns 0 on success.
12134 qnext
12136 print the name of the next pushable patch:
12137 hg qnext [-s]
12139 Returns 0 on success.
12141 Options:
12143 -s, --summary
12145 print first line of patch header
12146 qpop
12148 pop the current patch off the stack:
12149 hg qpop [-a] [-f] [PATCH | INDEX]
12151 Without argument, pops off the top of the patch stack. If given a patch
12153 name, keeps popping off patches until the named patch is at the top of
12154 the stack.
12155 By default, abort if the working directory contains uncommitted
12157 changes. With --keep-changes, abort only if the uncommitted files over‐
12158 lap with patched files. With -f/--force, backup and discard changes
12159 made to such files.
12160 Return 0 on success.
12162 Options:
12164 -a, --all
12166 pop all patches
12167 -n,--name <NAME>
12169 queue name to pop (DEPRECATED)
12170 --keep-changes
12172 tolerate non-conflicting local changes
12173 -f, --force
12175 forget any local changes to patched files
12176 --no-backup
12178 do not save backup copies of files
12179 qprev
12181 print the name of the preceding applied patch:
12182 hg qprev [-s]
12184 Returns 0 on success.
12186 Options:
12188 -s, --summary
12190 print first line of patch header
12191 qpush
12193 push the next patch onto the stack:
12194 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
12196 By default, abort if the working directory contains uncommitted
12198 changes. With --keep-changes, abort only if the uncommitted files over‐
12199 lap with patched files. With -f/--force, backup and patch over uncom‐
12200 mitted changes.
12201 Return 0 on success.
12203 Options:
12205 --keep-changes
12207 tolerate non-conflicting local changes
12208 -f, --force
12210 apply on top of local changes
12211 -e, --exact
12213 apply the target patch to its recorded parent
12214 -l, --list
12216 list patch name in commit text
12217 -a, --all
12219 apply all patches
12220 -m, --merge
12222 merge from another queue (DEPRECATED)
12223 -n,--name <NAME>
12225 merge queue name (DEPRECATED)
12226 --move reorder patch series and apply only the patch
12228 --no-backup
12230 do not save backup copies of files
12231 qqueue
12233 manage multiple patch queues:
12234 hg qqueue [OPTION] [QUEUE]
12236 Supports switching between different patch queues, as well as creating
12238 new patch queues and deleting existing ones.
12239 Omitting a queue name or specifying -l/--list will show you the regis‐
12241 tered queues - by default the "normal" patches queue is registered. The
12242 currently active queue will be marked with "(active)". Specifying --ac‐
12243 tive will print only the name of the active queue.
12244 To create a new queue, use -c/--create. The queue is automatically made
12246 active, except in the case where there are applied patches from the
12247 currently active queue in the repository. Then the queue will only be
12248 created and switching will fail.
12249 To delete an existing queue, use --delete. You cannot delete the cur‐
12251 rently active queue.
12252 Returns 0 on success.
12254 Options:
12256 -l, --list
12258 list all available queues
12259 --active
12261 print name of active queue
12262 -c, --create
12264 create new queue
12265 --rename
12267 rename active queue
12268 --delete
12270 delete reference to queue
12271 --purge
12273 delete queue, and remove patch dir
12274 qrename
12276 rename a patch:
12277 hg qrename PATCH1 [PATCH2]
12279 With one argument, renames the current patch to PATCH1. With two argu‐
12281 ments, renames PATCH1 to PATCH2.
12282 Returns 0 on success.
12284 aliases: qmv
12286 qrestore
12288 restore the queue state saved by a revision (DEPRECATED):
12289 hg qrestore [-d] [-u] REV
12291 This command is deprecated, use hg rebase instead.
12293 Options:
12295 -d, --delete
12297 delete save entry
12298 -u, --update
12300 update queue working directory
12301 qsave
12303 save current queue state (DEPRECATED):
12304 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
12306 This command is deprecated, use hg rebase instead.
12308 Options:
12310 -c, --copy
12312 copy patch directory
12313 -n,--name <NAME>
12315 copy directory name
12316 -e, --empty
12318 clear queue status file
12319 -f, --force
12321 force copy
12322 -m,--message <TEXT>
12324 use text as commit message
12325 -l,--logfile <FILE>
12327 read commit message from file
12328 qselect
12330 set or print guarded patches to push:
12331 hg qselect [OPTION]... [GUARD]...
12333 Use the hg qguard command to set or print guards on patch, then use qs‐
12335 elect to tell mq which guards to use. A patch will be pushed if it has
12336 no guards or any positive guards match the currently selected guard,
12337 but will not be pushed if any negative guards match the current guard.
12338 For example:
12339 qguard foo.patch -- -stable (negative guard)
12341 qguard bar.patch +stable (positive guard)
12342 qselect stable
12343 This activates the "stable" guard. mq will skip foo.patch (because it
12345 has a negative match) but push bar.patch (because it has a positive
12346 match).
12347 With no arguments, prints the currently active guards. With one argu‐
12349 ment, sets the active guard.
12350 Use -n/--none to deactivate guards (no other arguments needed). When
12352 no guards are active, patches with positive guards are skipped and
12353 patches with negative guards are pushed.
12354 qselect can change the guards on applied patches. It does not pop
12356 guarded patches by default. Use --pop to pop back to the last applied
12357 patch that is not guarded. Use --reapply (which implies --pop) to push
12358 back to the current patch afterwards, but skip guarded patches.
12359 Use -s/--series to print a list of all guards in the series file (no
12361 other arguments needed). Use -v for more information.
12362 Returns 0 on success.
12364 Options:
12366 -n, --none
12368 disable all guards
12369 -s, --series
12371 list all guards in series file
12372 --pop pop to before first guarded applied patch
12374 --reapply
12376 pop, then reapply patches
12377 qseries
12379 print the entire series file:
12380 hg qseries [-ms]
12382 Returns 0 on success.
12384 Options:
12386 -m, --missing
12388 print patches not in series
12389 -s, --summary
12391 print first line of patch header
12392 qtop
12394 print the name of the current patch:
12395 hg qtop [-s]
12397 Returns 0 on success.
12399 Options:
12401 -s, --summary
12403 print first line of patch header
12404 qunapplied
12406 print the patches not yet applied:
12407 hg qunapplied [-1] [-s] [PATCH]
12409 Returns 0 on success.
12411 Options:
12413 -1, --first
12415 show only the first patch
12416 -s, --summary
12418 print first line of patch header
12419 File content management
12421 qdiff
12422 diff of the current patch and subsequent modifications:
12423 hg qdiff [OPTION]... [FILE]...
12425 Shows a diff which includes the current patch as well as any changes
12427 which have been made in the working directory since the last refresh
12428 (thus showing what the current patch would become after a qrefresh).
12429 Use hg diff if you only want to see the changes made since the last
12431 qrefresh, or hg export qtip if you want to see changes made by the cur‐
12432 rent patch without including changes made since the qrefresh.
12433 Returns 0 on success.
12435 Options:
12437 -a, --text
12439 treat all files as text
12440 -g, --git
12442 use git extended diff format (DEFAULT: diff.git)
12443 --binary
12445 generate binary diffs in git mode (default)
12446 --nodates
12448 omit dates from diff headers
12449 --noprefix
12451 omit a/ and b/ prefixes from filenames
12452 -p, --show-function
12454 show which function each change is in (DEFAULT: diff.showfunc)
12455 --reverse
12457 produce a diff that undoes the changes
12458 -w, --ignore-all-space
12460 ignore white space when comparing lines
12461 -b, --ignore-space-change
12463 ignore changes in the amount of white space
12464 -B, --ignore-blank-lines
12466 ignore changes whose lines are all blank
12467 -Z, --ignore-space-at-eol
12469 ignore changes in whitespace at EOL
12470 -U,--unified <NUM>
12472 number of lines of context to show
12473 --stat output diffstat-style summary of changes
12475 --root <DIR>
12477 produce diffs relative to subdirectory
12478 -I,--include <PATTERN[+]>
12480 include names matching the given patterns
12481 -X,--exclude <PATTERN[+]>
12483 exclude names matching the given patterns
12484 [+] marked option can be specified multiple times
12486 Change import/export
12488 qimport
12489 import a patch or existing changeset:
12490 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
12492 The patch is inserted into the series after the last applied patch. If
12494 no patches have been applied, qimport prepends the patch to the series.
12495 The patch will have the same name as its source file unless you give it
12497 a new one with -n/--name.
12498 You can register an existing patch inside the patch directory with the
12500 -e/--existing flag.
12501 With -f/--force, an existing patch of the same name will be overwrit‐
12503 ten.
12504 An existing changeset may be placed under mq control with -r/--rev
12506 (e.g. qimport --rev . -n patch will place the current revision under mq
12507 control). With -g/--git, patches imported with --rev will use the git
12508 diff format. See the diffs help topic for information on why this is
12509 important for preserving rename/copy information and permission
12510 changes. Use hg qfinish to remove changesets from mq control.
12511 To import a patch from standard input, pass - as the patch file. When
12513 importing from standard input, a patch name must be specified using the
12514 --name flag.
12515 To import an existing patch while renaming it:
12517 hg qimport -e existing-patch -n new-name
12519 Returns 0 if import succeeded.
12521 Options:
12523 -e, --existing
12525 import file in patch directory
12526 -n,--name <NAME>
12528 name of patch file
12529 -f, --force
12531 overwrite existing files
12532 -r,--rev <REV[+]>
12534 place existing revisions under mq control
12535 -g, --git
12537 use git extended diff format
12538 -P, --push
12540 qpush after importing
12541 [+] marked option can be specified multiple times
12543 narrow
12545 create clones which fetch history data for subset of files (EXPERIMEN‐
12546 TAL)
12547 Commands
12549 Repository maintenance
12550 tracked
12551 show or change the current narrowspec:
12552 hg tracked [OPTIONS]... [REMOTE]
12554 With no argument, shows the current narrowspec entries, one per line.
12556 Each line will be prefixed with 'I' or 'X' for included or excluded
12557 patterns, respectively.
12558 The narrowspec is comprised of expressions to match remote files and/or
12560 directories that should be pulled into your client. The narrowspec has
12561 include and exclude expressions, with excludes always trumping in‐
12562 cludes: that is, if a file matches an exclude expression, it will be
12563 excluded even if it also matches an include expression. Excluding
12564 files that were never included has no effect.
12565 Each included or excluded entry is in the format described by 'hg help
12567 patterns'.
12568 The options allow you to add or remove included and excluded expres‐
12570 sions.
12571 If --clear is specified, then all previous includes and excludes are
12573 DROPPED and replaced by the new ones specified to --addinclude and
12574 --addexclude. If --clear is specified without any further options, the
12575 narrowspec will be empty and will not match any files.
12576 If --auto-remove-includes is specified, then those includes that don't
12578 match any files modified by currently visible local commits (those not
12579 shared by the remote) will be added to the set of explicitly specified
12580 includes to remove.
12581 --import-rules accepts a path to a file containing rules, allowing you
12583 to add --addinclude, --addexclude rules in bulk. Like the other include
12584 and exclude switches, the changes are applied immediately.
12585 Options:
12587 --addinclude <VALUE[+]>
12589 new paths to include
12590 --removeinclude <VALUE[+]>
12592 old paths to no longer include
12593 --auto-remove-includes
12595 automatically choose unused includes to remove
12596 --addexclude <VALUE[+]>
12598 new paths to exclude
12599 --import-rules <VALUE>
12601 import narrowspecs from a file
12602 --removeexclude <VALUE[+]>
12604 old paths to no longer exclude
12605 --clear
12607 whether to replace the existing narrowspec
12608 --force-delete-local-changes
12610 forces deletion of local changes when narrowing
12611 --backup
12613 back up local changes when narrowing (default: True)
12614 --update-working-copy
12616 update working copy when the store has changed
12617 -e,--ssh <CMD>
12619 specify ssh command to use
12620 --remotecmd <CMD>
12622 specify hg command to run on the remote side
12623 --insecure
12625 do not verify server certificate (ignoring web.cacerts config)
12626 [+] marked option can be specified multiple times
12628 notify
12630 hooks for sending email push notifications
12631 This extension implements hooks to send email notifications when
12633 changesets are sent from or received by the local repository.
12634 First, enable the extension as explained in hg help extensions, and
12636 register the hook you want to run. incoming and changegroup hooks are
12637 run when changesets are received, while outgoing hooks are for change‐
12638 sets sent to another repository:
12639 [hooks]
12641 # one email for each incoming changeset
12642 incoming.notify = python:hgext.notify.hook
12643 # one email for all incoming changesets
12644 changegroup.notify = python:hgext.notify.hook
12645 # one email for all outgoing changesets
12647 outgoing.notify = python:hgext.notify.hook
12648 This registers the hooks. To enable notification, subscribers must be
12650 assigned to repositories. The [usersubs] section maps multiple reposi‐
12651 tories to a given recipient. The [reposubs] section maps multiple re‐
12652 cipients to a single repository:
12653 [usersubs]
12655 # key is subscriber email, value is a comma-separated list of repo patterns
12656 user@host = pattern
12657 [reposubs]
12659 # key is repo pattern, value is a comma-separated list of subscriber emails
12660 pattern = user@host
12661 A pattern is a glob matching the absolute path to a repository, option‐
12663 ally combined with a revset expression. A revset expression, if
12664 present, is separated from the glob by a hash. Example:
12665 [reposubs]
12667 */widgets#branch(release) = qa-team@example.com
12668 This sends to qa-team@example.com whenever a changeset on the release
12670 branch triggers a notification in any repository ending in widgets.
12671 In order to place them under direct user management, [usersubs] and
12673 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
12674 rated by reference:
12675 [notify]
12677 config = /path/to/subscriptionsfile
12678 Notifications will not be sent until the notify.test value is set to
12680 False; see below.
12681 Notifications content can be tweaked with the following configuration
12683 entries:
12684 notify.test
12686 If True, print messages to stdout instead of sending them. De‐
12687 fault: True.
12688 notify.sources
12690 Space-separated list of change sources. Notifications are acti‐
12691 vated only when a changeset's source is in this list. Sources
12692 may be:
12693 serve
12695 changesets received via http or ssh
12697 pull
12699 changesets received via hg pull
12701 unbundle
12703 changesets received via hg unbundle
12705 push
12707 changesets sent or received via hg push
12709 bundle
12711 changesets sent via hg unbundle
12713 Default: serve.
12715 notify.strip
12717 Number of leading slashes to strip from url paths. By default,
12718 notifications reference repositories with their absolute path.
12719 notify.strip lets you turn them into relative paths. For exam‐
12720 ple, notify.strip=3 will change /long/path/repository into
12721 repository. Default: 0.
12722 notify.domain
12724 Default email domain for sender or recipients with no explicit
12725 domain. It is also used for the domain part of the Message-Id
12726 when using notify.messageidseed.
12727 notify.messageidseed
12729 Create deterministic Message-Id headers for the mails based on
12730 the seed and the revision identifier of the first commit in the
12731 changeset.
12732 notify.style
12734 Style file to use when formatting emails.
12735 notify.template
12737 Template to use when formatting emails.
12738 notify.incoming
12740 Template to use when run as an incoming hook, overriding no‐
12741 tify.template.
12742 notify.outgoing
12744 Template to use when run as an outgoing hook, overriding no‐
12745 tify.template.
12746 notify.changegroup
12748 Template to use when running as a changegroup hook, overriding
12749 notify.template.
12750 notify.maxdiff
12752 Maximum number of diff lines to include in notification email.
12753 Set to 0 to disable the diff, or -1 to include all of it. De‐
12754 fault: 300.
12755 notify.maxdiffstat
12757 Maximum number of diffstat lines to include in notification
12758 email. Set to -1 to include all of it. Default: -1.
12759 notify.maxsubject
12761 Maximum number of characters in email's subject line. Default:
12762 67.
12763 notify.diffstat
12765 Set to True to include a diffstat before diff content. Default:
12766 True.
12767 notify.showfunc
12769 If set, override diff.showfunc for the diff content. Default:
12770 None.
12771 notify.merge
12773 If True, send notifications for merge changesets. Default: True.
12774 notify.mbox
12776 If set, append mails to this mbox file instead of sending. De‐
12777 fault: None.
12778 notify.fromauthor
12780 If set, use the committer of the first changeset in a change‐
12781 group for the "From" field of the notification mail. If not set,
12782 take the user from the pushing repo. Default: False.
12783 notify.reply-to-predecessor (EXPERIMENTAL)
12785 If set and the changeset has a predecessor in the repository,
12786 try to thread the notification mail with the predecessor. This
12787 adds the "In-Reply-To" header to the notification mail with a
12788 reference to the predecessor with the smallest revision number.
12789 Mail threads can still be torn, especially when changesets are
12790 folded.
12791 This option must be used in combination with notify.messageid‐
12793 seed.
12794 If set, the following entries will also be used to customize the noti‐
12796 fications:
12797 email.from
12799 Email From address to use if none can be found in the generated
12800 email content.
12801 web.baseurl
12803 Root repository URL to combine with repository paths when making
12804 references. See also notify.strip.
12805 pager
12807 browse command output with an external pager (DEPRECATED)
12808 Forcibly enable paging for individual commands that don't typically re‐
12810 quest pagination with the attend-<command> option. This setting takes
12811 precedence over ignore options and defaults:
12812 [pager]
12814 attend-cat = false
12815 patchbomb
12817 command to send changesets as (a series of) patch emails
12818 The series is started off with a "[PATCH 0 of N]" introduction, which
12820 describes the series as a whole.
12821 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12823 first line of the changeset description as the subject text. The mes‐
12824 sage contains two or three body parts:
12825 • The changeset description.
12827 • [Optional] The result of running diffstat on the patch.
12829 • The patch itself, as generated by hg export.
12831 Each message refers to the first in the series using the In-Reply-To
12833 and References headers, so they will show up as a sequence in threaded
12834 mail and news readers, and in mail archives.
12835 To configure other defaults, add a section like this to your configura‐
12837 tion file:
12838 [email]
12840 from = My Name <my@email>
12841 to = recipient1, recipient2, ...
12842 cc = cc1, cc2, ...
12843 bcc = bcc1, bcc2, ...
12844 reply-to = address1, address2, ...
12845 Use [patchbomb] as configuration section name if you need to override
12847 global [email] address settings.
12848 Then you can use the hg email command to mail a series of changesets as
12850 a patchbomb.
12851 You can also either configure the method option in the email section to
12853 be a sendmail compatible mailer or fill out the [smtp] section so that
12854 the patchbomb extension can automatically send patchbombs directly from
12855 the commandline. See the [email] and [smtp] sections in hgrc(5) for de‐
12856 tails.
12857 By default, hg email will prompt for a To or CC header if you do not
12859 supply one via configuration or the command line. You can override
12860 this to never prompt by configuring an empty value:
12861 [email]
12863 cc =
12864 You can control the default inclusion of an introduction message with
12866 the patchbomb.intro configuration option. The configuration is always
12867 overwritten by command line flags like --intro and --desc:
12868 [patchbomb]
12870 intro=auto # include introduction message if more than 1 patch (default)
12871 intro=never # never include an introduction message
12872 intro=always # always include an introduction message
12873 You can specify a template for flags to be added in subject prefixes.
12875 Flags specified by --flag option are exported as {flags} keyword:
12876 [patchbomb]
12878 flagtemplate = "{separate(' ',
12879 ifeq(branch, 'default', '', branch|upper),
12880 flags)}"
12881 You can set patchbomb to always ask for confirmation by setting patch‐
12883 bomb.confirm to true.
12884 Commands
12886 Change import/export
12887 email
12888 send changesets by email:
12889 hg email [OPTION]... [DEST]...
12891 By default, diffs are sent in the format generated by hg export, one
12893 per message. The series starts with a "[PATCH 0 of N]" introduction,
12894 which describes the series as a whole.
12895 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12897 first line of the changeset description as the subject text. The mes‐
12898 sage contains two or three parts. First, the changeset description.
12899 With the -d/--diffstat option, if the diffstat program is installed,
12901 the result of running diffstat on the patch is inserted.
12902 Finally, the patch itself, as generated by hg export.
12904 With the -d/--diffstat or --confirm options, you will be presented with
12906 a final summary of all messages and asked for confirmation before the
12907 messages are sent.
12908 By default the patch is included as text in the email body for easy re‐
12910 viewing. Using the -a/--attach option will instead create an attachment
12911 for the patch. With -i/--inline an inline attachment will be created.
12912 You can include a patch both as text in the email body and as a regular
12913 or an inline attachment by combining the -a/--attach or -i/--inline
12914 with the --body option.
12915 With -B/--bookmark changesets reachable by the given bookmark are se‐
12917 lected.
12918 With -o/--outgoing, emails will be generated for patches not found in
12920 the destination repository (or only those which are ancestors of the
12921 specified revisions if any are provided)
12922 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
12924 gle email containing a binary Mercurial bundle as an attachment will be
12925 sent. Use the patchbomb.bundletype config option to control the bundle
12926 type as with hg bundle --type.
12927 With -m/--mbox, instead of previewing each patchbomb message in a pager
12929 or sending the messages directly, it will create a UNIX mailbox file
12930 with the patch emails. This mailbox file can be previewed with any mail
12931 user agent which supports UNIX mbox files.
12932 With -n/--test, all steps will run, but mail will not be sent. You
12934 will be prompted for an email recipient address, a subject and an in‐
12935 troductory message describing the patches of your patchbomb. Then when
12936 all is done, patchbomb messages are displayed.
12937 In case email sending fails, you will find a backup of your series in‐
12939 troductory message in .hg/last-email.txt.
12940 The default behavior of this command can be customized through configu‐
12942 ration. (See hg help patchbomb for details)
12943 Examples:
12945 hg email -r 3000 # send patch 3000 only
12947 hg email -r 3000 -r 3001 # send patches 3000 and 3001
12948 hg email -r 3000:3005 # send patches 3000 through 3005
12949 hg email 3000 # send patch 3000 (deprecated)
12950 hg email -o # send all patches not in default
12952 hg email -o DEST # send all patches not in DEST
12953 hg email -o -r 3000 # send all ancestors of 3000 not in default
12954 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
12955 hg email -B feature # send all ancestors of feature bookmark
12957 hg email -b # send bundle of all patches not in default
12959 hg email -b DEST # send bundle of all patches not in DEST
12960 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
12961 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
12962 hg email -o -m mbox && # generate an mbox file...
12964 mutt -R -f mbox # ... and view it with mutt
12965 hg email -o -m mbox && # generate an mbox file ...
12966 formail -s sendmail \ # ... and use formail to send from the mbox
12967 -bm -t < mbox # ... using sendmail
12968 Before using this command, you will need to enable email in your hgrc.
12970 See the [email] section in hgrc(5) for details.
12971 Options:
12973 -g, --git
12975 use git extended diff format
12976 --plain
12978 omit hg patch header
12979 -o, --outgoing
12981 send changes not found in the target repository
12982 -b, --bundle
12984 send changes not in target as a binary bundle
12985 -B,--bookmark <BOOKMARK>
12987 send changes only reachable by given bookmark
12988 --bundlename <NAME>
12990 name of the bundle attachment file (default: bundle)
12991 -r,--rev <REV[+]>
12993 a revision to send
12994 --force
12996 run even when remote repository is unrelated (with -b/--bundle)
12997 --base <REV[+]>
12999 a base changeset to specify instead of a destination (with
13000 -b/--bundle)
13001 --intro
13003 send an introduction email for a single patch
13004 --body send patches as inline message text (default)
13006 -a, --attach
13008 send patches as attachments
13009 -i, --inline
13011 send patches as inline attachments
13012 --bcc <EMAIL[+]>
13014 email addresses of blind carbon copy recipients
13015 -c,--cc <EMAIL[+]>
13017 email addresses of copy recipients
13018 --confirm
13020 ask for confirmation before sending
13021 -d, --diffstat
13023 add diffstat output to messages
13024 --date <DATE>
13026 use the given date as the sending date
13027 --desc <FILE>
13029 use the given file as the series description
13030 -f,--from <EMAIL>
13032 email address of sender
13033 -n, --test
13035 print messages that would be sent
13036 -m,--mbox <FILE>
13038 write messages to mbox file instead of sending them
13039 --reply-to <EMAIL[+]>
13041 email addresses replies should be sent to
13042 -s,--subject <TEXT>
13044 subject of first message (intro or single patch)
13045 --in-reply-to <MSGID>
13047 message identifier to reply to
13048 --flag <FLAG[+]>
13050 flags to add in subject prefixes
13051 -t,--to <EMAIL[+]>
13053 email addresses of recipients
13054 -e,--ssh <CMD>
13056 specify ssh command to use
13057 --remotecmd <CMD>
13059 specify hg command to run on the remote side
13060 --insecure
13062 do not verify server certificate (ignoring web.cacerts config)
13063 [+] marked option can be specified multiple times
13065 phabricator
13067 simple Phabricator integration (EXPERIMENTAL)
13068 This extension provides a phabsend command which sends a stack of
13070 changesets to Phabricator, and a phabread command which prints a stack
13071 of revisions in a format suitable for hg import, and a phabupdate com‐
13072 mand to update statuses in batch.
13073 A "phabstatus" view for hg show is also provided; it displays status
13075 information of Phabricator differentials associated with unfinished
13076 changesets.
13077 By default, Phabricator requires Test Plan which might prevent some
13079 changeset from being sent. The requirement could be disabled by chang‐
13080 ing differential.require-test-plan-field config server side.
13081 Config:
13083 [phabricator]
13085 # Phabricator URL
13086 url = https://phab.example.com/
13087 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
13089 # callsign is "FOO".
13090 callsign = FOO
13091 # curl command to use. If not set (default), use builtin HTTP library to
13093 # communicate. If set, use the specified curl command. This could be useful
13094 # if you need to specify advanced options that is not easily supported by
13095 # the internal library.
13096 curlcmd = curl --connect-timeout 2 --retry 3 --silent
13097 # retry failed command N time (default 0). Useful when using the extension
13099 # over flakly connection.
13100 #
13101 # We wait `retry.interval` between each retry, in seconds.
13102 # (default 1 second).
13103 retry = 3
13104 retry.interval = 10
13105 # the retry option can combine well with the http.timeout one.
13107 #
13108 # For example to give up on http request after 20 seconds:
13109 [http]
13110 timeout=20
13111 [auth]
13113 example.schemes = https
13114 example.prefix = phab.example.com
13115 # API token. Get it from https://$HOST/conduit/login/
13117 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
13118 Commands
13120 Change import/export
13121 phabimport
13122 import patches from Phabricator for the specified Differential Revi‐
13123 sions:
13124 hg phabimport DREVSPEC... [OPTIONS]
13126 The patches are read and applied starting at the parent of the working
13128 directory.
13129 See hg help phabread for how to specify DREVSPEC.
13131 Options:
13133 --stack
13135 import dependencies as well
13136 --test-vcr <VALUE>
13138 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13139 script, otherwise will mock all http requests using the speci‐
13140 fied vcr file. (ADVANCED)
13141 phabread
13143 print patches from Phabricator suitable for importing:
13144 hg phabread DREVSPEC... [OPTIONS]
13146 DREVSPEC could be a Differential Revision identity, like D123, or just
13148 the number 123. It could also have common operators like +, -, &, (, )
13149 for complex queries. Prefix : could be used to select a stack. If mul‐
13150 tiple DREVSPEC values are given, the result is the union of each indi‐
13151 vidually evaluated value. No attempt is currently made to reorder the
13152 values to run from parent to child.
13153 abandoned, accepted, closed, needsreview, needsrevision could be used
13155 to filter patches by status. For performance reason, they only repre‐
13156 sent a subset of non-status selections and cannot be used alone.
13157 For example, :D6+8-(2+D4) selects a stack up to D6, plus D8 and exclude
13159 D2 and D4. :D9 & needsreview selects "Needs Review" revisions in a
13160 stack up to D9.
13161 If --stack is given, follow dependencies information and read all
13163 patches. It is equivalent to the : operator.
13164 Options:
13166 --stack
13168 read dependencies
13169 --test-vcr <VALUE>
13171 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13172 script, otherwise will mock all http requests using the speci‐
13173 fied vcr file. (ADVANCED)
13174 phabsend
13176 upload changesets to Phabricator:
13177 hg phabsend REV [OPTIONS]
13179 If there are multiple revisions specified, they will be send as a stack
13181 with a linear dependencies relationship using the order specified by
13182 the revset.
13183 For the first time uploading changesets, local tags will be created to
13185 maintain the association. After the first time, phabsend will check ob‐
13186 sstore and tags information so it can figure out whether to update an
13187 existing Differential Revision, or create a new one.
13188 If --amend is set, update commit messages so they have the Differential
13190 Revision URL, remove related tags. This is similar to what arcanist
13191 will do, and is more desired in author-push workflows. Otherwise, use
13192 local tags to record the Differential Revision association.
13193 The --confirm option lets you confirm changesets before sending them.
13195 You can also add following to your configuration file to make it de‐
13196 fault behaviour:
13197 [phabsend]
13199 confirm = true
13200 By default, a separate review will be created for each commit that is
13202 selected, and will have the same parent/child relationship in Phabrica‐
13203 tor. If --fold is set, multiple commits are rolled up into a single
13204 review as if diffed from the parent of the first revision to the last.
13205 The commit messages are concatenated in the summary field on Phabrica‐
13206 tor.
13207 phabsend will check obsstore and the above association to decide
13209 whether to update an existing Differential Revision, or create a new
13210 one.
13211 Options:
13213 -r,--rev <REV[+]>
13215 revisions to send
13216 --amend
13218 update commit messages (default: True)
13219 --reviewer <VALUE[+]>
13221 specify reviewers
13222 --blocker <VALUE[+]>
13224 specify blocking reviewers
13225 -m,--comment <VALUE>
13227 add a comment to Revisions with new/updated Diffs
13228 --confirm
13230 ask for confirmation before sending
13231 --fold combine the revisions into one review
13233 --test-vcr <VALUE>
13235 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13236 script, otherwise will mock all http requests using the speci‐
13237 fied vcr file. (ADVANCED)
13238 [+] marked option can be specified multiple times
13240 phabupdate
13242 update Differential Revision in batch:
13243 hg phabupdate [DREVSPEC...| -r REV...] [OPTIONS]
13245 DREVSPEC selects revisions. See hg help phabread for its usage.
13247 Options:
13249 --accept
13251 accept revisions
13252 --reject
13254 reject revisions
13255 --request-review
13257 request review on revisions
13258 --abandon
13260 abandon revisions
13261 --reclaim
13263 reclaim revisions
13264 --close
13266 close revisions
13267 --reopen
13269 reopen revisions
13270 --plan-changes
13272 plan changes for revisions
13273 --resign
13275 resign as a reviewer from revisions
13276 --commandeer
13278 commandeer revisions
13279 -m,--comment <VALUE>
13281 comment on the last revision
13282 -r,--rev <REV>
13284 local revision to update
13285 --test-vcr <VALUE>
13287 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13288 script, otherwise will mock all http requests using the speci‐
13289 fied vcr file. (ADVANCED)
13290 Uncategorized commands
13292 purge
13293 command to delete untracked files from the working directory (DEPRE‐
13294 CATED)
13295 The functionality of this extension has been included in core Mercurial
13297 since version 5.7. Please use hg purge ... instead. hg purge --confirm
13298 is now the default, unless the extension is enabled for backward com‐
13299 patibility.
13300 rebase
13302 command to move sets of revisions to a different ancestor
13303 This extension lets you rebase changesets in an existing Mercurial
13305 repository.
13306 For more information: https://mercurial-scm.org/wiki/RebaseExtension
13308 Commands
13310 Change manipulation
13311 rebase
13312 move changeset (and descendants) to a different branch:
13313 hg rebase [[-s REV]... | [-b REV]... | [-r REV]...] [-d REV] [OPTION]...
13315 Rebase uses repeated merging to graft changesets from one part of his‐
13317 tory (the source) onto another (the destination). This can be useful
13318 for linearizing local changes relative to a master development tree.
13319 Published commits cannot be rebased (see hg help phases). To copy com‐
13321 mits, see hg help graft.
13322 If you don't specify a destination changeset (-d/--dest), rebase will
13324 use the same logic as hg merge to pick a destination. if the current
13325 branch contains exactly one other head, the other head is merged with
13326 by default. Otherwise, an explicit revision with which to merge with
13327 must be provided. (destination changeset is not modified by rebasing,
13328 but new changesets are added as its descendants.)
13329 Here are the ways to select changesets:
13331 1. Explicitly select them using --rev.
13333 2. Use --source to select a root changeset and include all of its
13335 descendants.
13336 3. Use --base to select a changeset; rebase will find ancestors and
13338 their descendants which are not also ancestors of the destina‐
13339 tion.
13340 4. If you do not specify any of --rev, --source, or --base, rebase
13342 will use --base . as above.
13343 If --source or --rev is used, special names SRC and ALLSRC can be used
13345 in --dest. Destination would be calculated per source revision with SRC
13346 substituted by that single source revision and ALLSRC substituted by
13347 all source revisions.
13348 Rebase will destroy original changesets unless you use --keep. It will
13350 also move your bookmarks (even if you do).
13351 Some changesets may be dropped if they do not contribute changes (e.g.
13353 merges from the destination branch).
13354 Unlike merge, rebase will do nothing if you are at the branch tip of a
13356 named branch with two heads. You will need to explicitly specify source
13357 and/or destination.
13358 If you need to use a tool to automate merge/conflict decisions, you can
13360 specify one with --tool, see hg help merge-tools. As a caveat: the
13361 tool will not be used to mediate when a file was deleted, there is no
13362 hook presently available for this.
13363 If a rebase is interrupted to manually resolve a conflict, it can be
13365 continued with --continue/-c, aborted with --abort/-a, or stopped with
13366 --stop.
13367 Examples:
13369 • move "local changes" (current commit back to branching point) to the
13371 current branch tip after a pull:
13372 hg rebase
13374 • move a single changeset to the stable branch:
13376 hg rebase -r 5f493448 -d stable
13378 • splice a commit and all its descendants onto another part of history:
13380 hg rebase --source c0c3 --dest 4cf9
13382 • rebase everything on a branch marked by a bookmark onto the default
13384 branch:
13385 hg rebase --base myfeature --dest default
13387 • collapse a sequence of changes into a single commit:
13389 hg rebase --collapse -r 1520:1525 -d .
13391 • move a named branch while preserving its name:
13393 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
13395 • stabilize orphaned changesets so history looks linear:
13397 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
13399 Configuration Options:
13401 You can make rebase require a destination if you set the following con‐
13403 fig option:
13404 [commands]
13406 rebase.requiredest = True
13407 By default, rebase will close the transaction after each commit. For
13409 performance purposes, you can configure rebase to use a single transac‐
13410 tion across the entire rebase. WARNING: This setting introduces a sig‐
13411 nificant risk of losing the work you've done in a rebase if the rebase
13412 aborts unexpectedly:
13413 [rebase]
13415 singletransaction = True
13416 By default, rebase writes to the working copy, but you can configure it
13418 to run in-memory for better performance. When the rebase is not moving
13419 the parent(s) of the working copy (AKA the "currently checked out
13420 changesets"), this may also allow it to run even if the working copy is
13421 dirty:
13422 [rebase]
13424 experimental.inmemory = True
13425 Return Values:
13427 Returns 0 on success, 1 if nothing to rebase or there are unresolved
13429 conflicts.
13430 Options:
13432 -s,--source <REV[+]>
13434 rebase the specified changesets and their descendants
13435 -b,--base <REV[+]>
13437 rebase everything from branching point of specified changeset
13438 -r,--rev <REV[+]>
13440 rebase these revisions
13441 -d,--dest <REV>
13443 rebase onto the specified changeset
13444 --collapse
13446 collapse the rebased changesets
13447 -m,--message <TEXT>
13449 use text as collapse commit message
13450 -e, --edit
13452 invoke editor on commit messages
13453 -l,--logfile <FILE>
13455 read collapse commit message from file
13456 -k, --keep
13458 keep original changesets
13459 --keepbranches
13461 keep original branch names
13462 -D, --detach
13464 (DEPRECATED)
13465 -i, --interactive
13467 (DEPRECATED)
13468 -t,--tool <VALUE>
13470 specify merge tool
13471 --stop stop interrupted rebase
13473 -c, --continue
13475 continue an interrupted rebase
13476 -a, --abort
13478 abort an interrupted rebase
13479 --auto-orphans <VALUE>
13481 automatically rebase orphan revisions in the specified revset
13482 (EXPERIMENTAL)
13483 -n, --dry-run
13485 do not perform actions, just print output
13486 -T,--template <TEMPLATE>
13488 display with template
13489 --confirm
13491 ask before applying actions
13492 [+] marked option can be specified multiple times
13494 record
13496 commands to interactively select changes for commit/qrefresh (DEPRE‐
13497 CATED)
13498 The feature provided by this extension has been moved into core Mercu‐
13500 rial as hg commit --interactive.
13501 Commands
13503 Change creation
13504 qrecord
13505 interactively record a new patch:
13506 hg qrecord [OPTION]... PATCH [FILE]...
13508 See hg help qnew & hg help record for more information and usage.
13510 record
13512 interactively select changes to commit:
13513 hg record [OPTION]... [FILE]...
13515 If a list of files is omitted, all changes reported by hg status will
13517 be candidates for recording.
13518 See hg help dates for a list of formats valid for -d/--date.
13520 If using the text interface (see hg help config), you will be prompted
13522 for whether to record changes to each modified file, and for files with
13523 multiple changes, for each change to use. For each query, the following
13524 responses are possible:
13525 y - record this change
13527 n - skip this change
13528 e - edit this change manually
13529 s - skip remaining changes to this file
13531 f - record remaining changes to this file
13532 d - done, skip remaining changes and files
13534 a - record all changes to all remaining files
13535 q - quit, recording no changes
13536 ? - display help
13538 This command is not available when committing a merge.
13540 Options:
13542 -A, --addremove
13544 mark new/missing files as added/removed before committing
13545 --close-branch
13547 mark a branch head as closed
13548 --amend
13550 amend the parent of the working directory
13551 -s, --secret
13553 use the secret phase for committing
13554 -e, --edit
13556 invoke editor on commit messages
13557 --force-close-branch
13559 forcibly close branch from a non-head changeset (ADVANCED)
13560 -I,--include <PATTERN[+]>
13562 include names matching the given patterns
13563 -X,--exclude <PATTERN[+]>
13565 exclude names matching the given patterns
13566 -m,--message <TEXT>
13568 use text as commit message
13569 -l,--logfile <FILE>
13571 read commit message from file
13572 -d,--date <DATE>
13574 record the specified date as commit date
13575 -u,--user <USER>
13577 record the specified user as committer
13578 -S, --subrepos
13580 recurse into subrepositories
13581 -w, --ignore-all-space
13583 ignore white space when comparing lines
13584 -b, --ignore-space-change
13586 ignore changes in the amount of white space
13587 -B, --ignore-blank-lines
13589 ignore changes whose lines are all blank
13590 -Z, --ignore-space-at-eol
13592 ignore changes in whitespace at EOL
13593 [+] marked option can be specified multiple times
13595 releasenotes
13597 generate release notes from commit messages (EXPERIMENTAL)
13598 It is common to maintain files detailing changes in a project between
13600 releases. Maintaining these files can be difficult and time consuming.
13601 The hg releasenotes command provided by this extension makes the
13602 process simpler by automating it.
13603 Commands
13605 Change navigation
13606 releasenotes
13607 parse release notes from commit messages into an output file:
13608 hg releasenotes [-r REV] [-c] FILE
13610 Given an output file and set of revisions, this command will parse com‐
13612 mit messages for release notes then add them to the output file.
13613 Release notes are defined in commit messages as ReStructuredText direc‐
13615 tives. These have the form:
13616 .. directive:: title
13618 content
13620 Each directive maps to an output section in a generated release notes
13622 file, which itself is ReStructuredText. For example, the .. feature::
13623 directive would map to a New Features section.
13624 Release note directives can be either short-form or long-form. In
13626 short- form, title is omitted and the release note is rendered as a
13627 bullet list. In long form, a sub-section with the title title is added
13628 to the section.
13629 The FILE argument controls the output file to write gathered release
13631 notes to. The format of the file is:
13632 Section 1
13634 =========
13635 ...
13637 Section 2
13639 =========
13640 ...
13642 Only sections with defined release notes are emitted.
13644 If a section only has short-form notes, it will consist of bullet list:
13646 Section
13648 =======
13649 * Release note 1
13651 * Release note 2
13652 If a section has long-form notes, sub-sections will be emitted:
13654 Section
13656 =======
13657 Note 1 Title
13659 ------------
13660 Description of the first long-form note.
13662 Note 2 Title
13664 ------------
13665 Description of the second long-form note.
13667 If the FILE argument points to an existing file, that file will be
13669 parsed for release notes having the format that would be generated by
13670 this command. The notes from the processed commit messages will be
13671 merged into this parsed set.
13672 During release notes merging:
13674 • Duplicate items are automatically ignored
13676 • Items that are different are automatically ignored if the similarity
13678 is greater than a threshold.
13679 This means that the release notes file can be updated independently
13681 from this command and changes should not be lost when running this com‐
13682 mand on that file. A particular use case for this is to tweak the word‐
13683 ing of a release note after it has been added to the release notes
13684 file.
13685 The -c/--check option checks the commit message for invalid admoni‐
13687 tions.
13688 The -l/--list option, presents the user with a list of existing avail‐
13690 able admonitions along with their title. This also includes the custom
13691 admonitions (if any).
13692 Options:
13694 -r,--rev <REV>
13696 revisions to process for release notes
13697 -c, --check
13699 checks for validity of admonitions (if any)
13700 -l, --list
13702 list the available admonitions with their title
13703 Uncategorized commands
13705 relink
13706 recreates hardlinks between repository clones
13707 Commands
13709 Repository maintenance
13710 relink
13711 recreate hardlinks between two repositories:
13712 hg relink [ORIGIN]
13714 When repositories are cloned locally, their data files will be
13716 hardlinked so that they only use the space of a single repository.
13717 Unfortunately, subsequent pulls into either repository will break
13719 hardlinks for any files touched by the new changesets, even if both
13720 repositories end up pulling the same changes.
13721 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
13723 falling back to a complete copy of the source repository.
13724 This command lets you recreate those hardlinks and reclaim that wasted
13726 space.
13727 This repository will be relinked to share space with ORIGIN, which must
13729 be on the same local disk. If ORIGIN is omitted, looks for "default-re‐
13730 link", then "default", in [paths].
13731 Do not attempt any read operations on this repository while the command
13733 is running. (Both repositories will be locked against writes.)
13734 remotefilelog
13736 remotefilelog causes Mercurial to lazilly fetch file contents (EXPERI‐
13737 MENTAL)
13738 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13740 BILITY GUARANTEES. This means that repositories created with this ex‐
13741 tension may only be usable with the exact version of this exten‐
13742 sion/Mercurial that was used. The extension attempts to enforce this in
13743 order to prevent repository corruption.
13744 remotefilelog works by fetching file contents lazily and storing them
13746 in a cache on the client rather than in revlogs. This allows enormous
13747 histories to be transferred only partially, making them easier to oper‐
13748 ate on.
13749 Configs:
13751 packs.maxchainlen specifies the maximum delta chain length in pack
13753 files
13754 packs.maxpacksize specifies the maximum pack file size
13756 packs.maxpackfilecount specifies the maximum number of packs in the
13758 shared cache (trees only for now)
13760 remotefilelog.backgroundprefetch runs prefetch in background when
13762 True
13763 remotefilelog.bgprefetchrevs specifies revisions to fetch on commit
13765 and
13766 update, and on other commands that use them. Different from
13768 pullprefetch.
13769 remotefilelog.gcrepack does garbage collection during repack when
13771 True
13772 remotefilelog.nodettl specifies maximum TTL of a node in seconds be‐
13774 fore
13775 it is garbage collected
13777 remotefilelog.repackonhggc runs repack on hg gc when True
13779 remotefilelog.prefetchdays specifies the maximum age of a commit in
13781 days after which it is no longer prefetched.
13783 remotefilelog.prefetchdelay specifies delay between background
13785 prefetches in seconds after operations that change the work‐
13787 ing copy parent
13788 remotefilelog.data.gencountlimit constraints the minimum number of
13790 data
13791 pack files required to be considered part of a generation. In
13793 particular, minimum number of packs files > gencountlimit.
13794 remotefilelog.data.generations list for specifying the lower bound
13796 of
13797 each generation of the data pack files. For example, list
13799 ['100MB','1MB'] or ['1MB', '100MB'] will lead to three gener‐
13800 ations: [0, 1MB), [ 1MB, 100MB) and [100MB, infinity).
13801 remotefilelog.data.maxrepackpacks the maximum number of pack files
13803 to
13804 include in an incremental data repack.
13806 remotefilelog.data.repackmaxpacksize the maximum size of a pack file
13808 for
13809 it to be considered for an incremental data repack.
13811 remotefilelog.data.repacksizelimit the maximum total size of pack
13813 files
13814 to include in an incremental data repack.
13816 remotefilelog.history.gencountlimit constraints the minimum number
13818 of
13819 history pack files required to be considered part of a gener‐
13821 ation. In particular, minimum number of packs files > gen‐
13822 countlimit.
13823 remotefilelog.history.generations list for specifying the lower
13825 bound of
13826 each generation of the history pack files. For example, list
13828 [ '100MB', '1MB'] or ['1MB', '100MB'] will lead to three gen‐
13829 erations: [ 0, 1MB), [1MB, 100MB) and [100MB, infinity).
13830 remotefilelog.history.maxrepackpacks the maximum number of pack
13832 files to
13833 include in an incremental history repack.
13835 remotefilelog.history.repackmaxpacksize the maximum size of a pack
13837 file
13838 for it to be considered for an incremental history repack.
13840 remotefilelog.history.repacksizelimit the maximum total size of pack
13842 files to include in an incremental history repack.
13844 remotefilelog.backgroundrepack automatically consolidate packs in
13846 the
13847 background
13849 remotefilelog.cachepath path to cache
13851 remotefilelog.cachegroup if set, make cache directory sgid to this
13853 group
13855 remotefilelog.cacheprocess binary to invoke for fetching file data
13857 remotefilelog.debug turn on remotefilelog-specific debug output
13859 remotefilelog.excludepattern pattern of files to exclude from pulls
13861 remotefilelog.includepattern pattern of files to include in pulls
13863 remotefilelog.fetchwarning: message to print when too many
13865 single-file fetches occur
13867 remotefilelog.getfilesstep number of files to request in a single
13869 RPC
13870 remotefilelog.getfilestype if set to 'threaded' use threads to fetch
13872 files, otherwise use optimistic fetching
13874 remotefilelog.pullprefetch revset for selecting files that should be
13876 eagerly downloaded rather than lazily
13878 remotefilelog.reponame name of the repo. If set, used to partition
13880 data from other repos in a shared store.
13882 remotefilelog.server if true, enable server-side functionality
13884 remotefilelog.servercachepath path for caching blobs on the server
13886 remotefilelog.serverexpiration number of days to keep cached server
13888 blobs
13890 remotefilelog.validatecache if set, check cache entries for corrup‐
13892 tion
13893 before returning blobs
13895 remotefilelog.validatecachelog if set, check cache entries for
13897 corruption before returning metadata
13899 Commands
13901 Repository maintenance
13902 prefetch
13903 prefetch file revisions from the server:
13904 hg prefetch [OPTIONS] [FILE...]
13906 Prefetchs file revisions for the specified revs and stores them in the
13908 local remotefilelog cache. If no rev is specified, the default rev is
13909 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
13910 File names or patterns can be used to limit which files are downloaded.
13911 Return 0 on success.
13913 Options:
13915 -r,--rev <REV[+]>
13917 prefetch the specified revisions
13918 --repack
13920 run repack after prefetch
13921 -b,--base <VALUE>
13923 rev that is assumed to already be local
13924 -I,--include <PATTERN[+]>
13926 include names matching the given patterns
13927 -X,--exclude <PATTERN[+]>
13929 exclude names matching the given patterns
13930 [+] marked option can be specified multiple times
13932 Uncategorized commands
13934 gc
13935 garbage collect the client and server filelog caches:
13936 hg gc [REPO...]
13938 garbage collect the client and server filelog caches
13940 repack
13942 hg repack [OPTIONS]
13943 Options:
13945 --background
13947 run in a background process
13948 --incremental
13950 do an incremental repack
13951 --packsonly
13953 only repack packs (skip loose objects)
13954 verifyremotefilelog
13956 hg verifyremotefilelogs <directory>
13957 Options:
13959 -d, --decompress
13961 decompress the filelogs first
13962 remotenames
13964 showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)
13965 By default both remotebookmarks and remotebranches are turned on. Con‐
13967 fig knob to control the individually are as follows.
13968 Config options to tweak the default behaviour:
13970 remotenames.bookmarks
13972 Boolean value to enable or disable showing of remotebookmarks
13973 (default: True)
13974 remotenames.branches
13976 Boolean value to enable or disable showing of remotebranches
13977 (default: True)
13978 remotenames.hoistedpeer
13980 Name of the peer whose remotebookmarks should be hoisted into
13981 the top-level namespace (default: 'default')
13982 schemes
13984 extend schemes with shortcuts to repository swarms
13985 This extension allows you to specify shortcuts for parent URLs with a
13987 lot of repositories to act like a scheme, for example:
13988 [schemes]
13990 py = http://code.python.org/hg/
13991 After that you can use it like:
13993 hg clone py://trunk/
13995 Additionally there is support for some more complex schemas, for exam‐
13997 ple used by Google Code:
13998 [schemes]
14000 gcode = http://{1}.googlecode.com/hg/
14001 The syntax is taken from Mercurial templates, and you have unlimited
14003 number of variables, starting with {1} and continuing with {2}, {3} and
14004 so on. This variables will receive parts of URL supplied, split by /.
14005 Anything not specified as {part} will be just appended to an URL.
14006 For convenience, the extension adds these schemes by default:
14008 [schemes]
14010 py = http://hg.python.org/
14011 bb = https://bitbucket.org/
14012 bb+ssh = ssh://hg@bitbucket.org/
14013 gcode = https://{1}.googlecode.com/hg/
14014 kiln = https://{1}.kilnhg.com/Repo/
14015 You can override a predefined scheme by defining a new scheme with the
14017 same name.
14018 Commands
14020 Uncategorized commands
14021 share
14022 share a common history between several working directories
14023 The share extension introduces a new command hg share to create a new
14025 working directory. This is similar to hg clone, but doesn't involve
14026 copying or linking the storage of the repository. This allows working
14027 on different branches or changes in parallel without the associated
14028 cost in terms of disk space.
14029 Note: destructive operations or extensions like hg rollback should be
14031 used with care as they can result in confusing problems.
14032 Automatic Pooled Storage for Clones
14034 When this extension is active, hg clone can be configured to automati‐
14035 cally share/pool storage across multiple clones. This mode effectively
14036 converts hg clone to hg clone + hg share. The benefit of using this
14037 mode is the automatic management of store paths and intelligent pooling
14038 of related repositories.
14039 The following share. config options influence this feature:
14041 share.pool
14043 Filesystem path where shared repository data will be stored.
14045 When defined, hg clone will automatically use shared repository
14046 storage instead of creating a store inside each clone.
14047 share.poolnaming
14049 How directory names in share.pool are constructed.
14051 "identity" means the name is derived from the first changeset in
14053 the repository. In this mode, different remotes share storage if
14054 their root/initial changeset is identical. In this mode, the lo‐
14055 cal shared repository is an aggregate of all encountered remote
14056 repositories.
14057 "remote" means the name is derived from the source repository's
14059 path or URL. In this mode, storage is only shared if the path or
14060 URL requested in the hg clone command matches exactly to a
14061 repository that was cloned before.
14062 The default naming mode is "identity".
14064 Sharing requirements and configs of source repository with shares:
14066 By default creating a shared repository only enables sharing a common
14068 history and does not share requirements and configs between them. This
14069 may lead to problems in some cases, for example when you upgrade the
14070 storage format from one repository but does not set related configs in
14071 the shares.
14072 Setting format.exp-share-safe = True enables sharing configs and re‐
14074 quirements. This only applies to shares which are done after enabling
14075 the config option.
14076 For enabling this in existing shares, enable the config option and re‐
14078 share.
14079 For resharing existing shares, make sure your working directory is
14081 clean and there are no untracked files, delete that share and create a
14082 new share.
14083 Commands
14085 Repository creation
14086 share
14087 create a new shared repository:
14088 hg share [-U] [-B] SOURCE [DEST]
14090 Initialize a new repository and working directory that shares its his‐
14092 tory (and optionally bookmarks) with another repository.
14093 Note using rollback or extensions that destroy/modify history (mq,
14095 rebase, etc.) can cause considerable confusion with shared
14096 clones. In particular, if two shared clones are both updated to
14097 the same changeset, and one of them destroys that changeset with
14098 rollback, the other clone will suddenly stop working: all opera‐
14099 tions will fail with "abort: working directory has unknown par‐
14100 ent". The only known workaround is to use debugsetparents on the
14101 broken clone to reset it to a changeset that still exists.
14102 Options:
14104 -U, --noupdate
14106 do not create a working directory
14107 -B, --bookmarks
14109 also share bookmarks
14110 --relative
14112 point to source using a relative path
14113 Repository maintenance
14115 unshare
14116 convert a shared repository to a normal one:
14117 hg unshare
14119 Copy the store data to the repo and remove the sharedpath data.
14121 show
14123 unified command to show various repository information (EXPERIMENTAL)
14124 This extension provides the hg show command, which provides a central
14126 command for displaying commonly-accessed repository data and views of
14127 that data.
14128 The following config options can influence operation.
14130 commands
14132 show.aliasprefix
14133 List of strings that will register aliases for views. e.g. s
14135 will effectively set config options alias.s<view> = show <view>
14136 for all views. i.e. hg swork would execute hg show work.
14137 Aliases that would conflict with existing registrations will not
14139 be performed.
14140 Commands
14142 Change navigation
14143 show
14144 show various repository information:
14145 hg show VIEW
14147 A requested view of repository data is displayed.
14149 If no view is requested, the list of available views is shown and the
14151 command aborts.
14152 Note There are no backwards compatibility guarantees for the output
14154 of this command. Output may change in any future Mercurial re‐
14155 lease.
14156 Consumers wanting stable command output should specify a tem‐
14158 plate via -T/--template.
14159 List of available views:
14161 bookmarks bookmarks and their associated changeset
14163 stack current line of work
14165 work changesets that aren't finished
14167 Options:
14169 -T,--template <TEMPLATE>
14171 display with template
14172 sparse
14174 allow sparse checkouts of the working directory (EXPERIMENTAL)
14175 (This extension is not yet protected by backwards compatibility guaran‐
14177 tees. Any aspect may break in future releases until this notice is re‐
14178 moved.)
14179 This extension allows the working directory to only consist of a subset
14181 of files for the revision. This allows specific files or directories to
14182 be explicitly included or excluded. Many repository operations have
14183 performance proportional to the number of files in the working direc‐
14184 tory. So only realizing a subset of files in the working directory can
14185 improve performance.
14186 Sparse Config Files
14188 The set of files that are part of a sparse checkout are defined by a
14189 sparse config file. The file defines 3 things: includes (files to in‐
14190 clude in the sparse checkout), excludes (files to exclude from the
14191 sparse checkout), and profiles (links to other config files).
14192 The file format is newline delimited. Empty lines and lines beginning
14194 with # are ignored.
14195 Lines beginning with %include `` denote another sparse config file to
14197 include. e.g. ``%include tests.sparse. The filename is relative to the
14198 repository root.
14199 The special lines [include] and [exclude] denote the section for in‐
14201 cludes and excludes that follow, respectively. It is illegal to have
14202 [include] after [exclude].
14203 Non-special lines resemble file patterns to be added to either includes
14205 or excludes. The syntax of these lines is documented by hg help pat‐
14206 terns. Patterns are interpreted as glob: by default and match against
14207 the root of the repository.
14208 Exclusion patterns take precedence over inclusion patterns. So even if
14210 a file is explicitly included, an [exclude] entry can remove it.
14211 For example, say you have a repository with 3 directories, frontend/,
14213 backend/, and tools/. frontend/ and backend/ correspond to different
14214 projects and it is uncommon for someone working on one to need the
14215 files for the other. But tools/ contains files shared between both
14216 projects. Your sparse config files may resemble:
14217 # frontend.sparse
14219 frontend/**
14220 tools/**
14221 # backend.sparse
14223 backend/**
14224 tools/**
14225 Say the backend grows in size. Or there's a directory with thousands of
14227 files you wish to exclude. You can modify the profile to exclude cer‐
14228 tain files:
14229 [include]
14231 backend/**
14232 tools/**
14233 [exclude]
14235 tools/tests/**
14236 Commands
14238 Uncategorized commands
14239 split
14240 command to split a changeset into smaller ones (EXPERIMENTAL)
14241 Commands
14243 Change manipulation
14244 split
14245 split a changeset into smaller ones:
14246 hg split [--no-rebase] [[-r] REV]
14248 Repeatedly prompt changes and commit message for new changesets until
14250 there is nothing left in the original changeset.
14251 If --rev was not given, split the working directory parent.
14253 By default, rebase connected non-obsoleted descendants onto the new
14255 changeset. Use --no-rebase to avoid the rebase.
14256 Options:
14258 -r,--rev <REV>
14260 revision to split
14261 --rebase
14263 rebase descendants after split (default: True)
14264 -d,--date <DATE>
14266 record the specified date as commit date
14267 -u,--user <USER>
14269 record the specified user as committer
14270 sqlitestore
14272 store repository data in SQLite (EXPERIMENTAL)
14273 The sqlitestore extension enables the storage of repository data in
14275 SQLite.
14276 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
14278 BILITY GUARANTEES. This means that repositories created with this ex‐
14279 tension may only be usable with the exact version of this exten‐
14280 sion/Mercurial that was used. The extension attempts to enforce this in
14281 order to prevent repository corruption.
14282 In addition, several features are not yet supported or have known bugs:
14284 • Only some data is stored in SQLite. Changeset, manifest, and other
14286 repository data is not yet stored in SQLite.
14287 • Transactions are not robust. If the process is aborted at the right
14289 time during transaction close/rollback, the repository could be in an
14290 inconsistent state. This problem will diminish once all repository
14291 data is tracked by SQLite.
14292 • Bundle repositories do not work (the ability to use e.g. hg -R <bun‐
14294 dle-file> log to automatically overlay a bundle on top of the exist‐
14295 ing repository).
14296 • Various other features don't work.
14298 This extension should work for basic clone/pull, update, and commit
14300 workflows. Some history rewriting operations may fail due to lack of
14301 support for bundle repositories.
14302 To use, activate the extension and set the storage.new-repo-backend
14304 config option to sqlite to enable new repositories to use SQLite for
14305 storage.
14306 strip
14308 strip changesets and their descendants from history (DEPRECATED)
14309 The functionality of this extension has been included in core Mercurial
14311 since version 5.7. Please use hg debugstrip ... instead.
14312 This extension allows you to strip changesets and all their descendants
14314 from the repository. See the command help for details.
14315 transplant
14317 command to transplant changesets from another branch
14318 This extension allows you to transplant changes to another parent revi‐
14320 sion, possibly in another repository. The transplant is done using
14321 'diff' patches.
14322 Transplanted patches are recorded in .hg/transplant/transplants, as a
14324 map from a changeset hash to its hash in the source repository.
14325 Commands
14327 Change manipulation
14328 transplant
14329 transplant changesets from another branch:
14330 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
14332 Selected changesets will be applied on top of the current working di‐
14334 rectory with the log of the original changeset. The changesets are
14335 copied and will thus appear twice in the history with different identi‐
14336 ties.
14337 Consider using the graft command if everything is inside the same
14339 repository - it will use merges and will usually give a better result.
14340 Use the rebase extension if the changesets are unpublished and you want
14341 to move them instead of copying them.
14342 If --log is specified, log messages will have a comment appended of the
14344 form:
14345 (transplanted from CHANGESETHASH)
14347 You can rewrite the changelog message with the --filter option. Its
14349 argument will be invoked with the current changelog message as $1 and
14350 the patch as $2.
14351 --source/-s specifies another repository to use for selecting change‐
14353 sets, just as if it temporarily had been pulled. If --branch/-b is
14354 specified, these revisions will be used as heads when deciding which
14355 changesets to transplant, just as if only these revisions had been
14356 pulled. If --all/-a is specified, all the revisions up to the heads
14357 specified with --branch will be transplanted.
14358 Example:
14360 • transplant all changes up to REV on top of your current revision:
14362 hg transplant --branch REV --all
14364 You can optionally mark selected transplanted changesets as merge
14366 changesets. You will not be prompted to transplant any ancestors of a
14367 merged transplant, and you can merge descendants of them normally in‐
14368 stead of transplanting them.
14369 Merge changesets may be transplanted directly by specifying the proper
14371 parent changeset by calling hg transplant --parent.
14372 If no merges or revisions are provided, hg transplant will start an in‐
14374 teractive changeset browser.
14375 If a changeset application fails, you can fix the merge by hand and
14377 then resume where you left off by calling hg transplant --continue/-c.
14378 Options:
14380 -s,--source <REPO>
14382 transplant changesets from REPO
14383 -b,--branch <REV[+]>
14385 use this source changeset as head
14386 -a, --all
14388 pull all changesets up to the --branch revisions
14389 -p,--prune <REV[+]>
14391 skip over REV
14392 -m,--merge <REV[+]>
14394 merge at REV
14395 --parent <REV>
14397 parent to choose when transplanting merge
14398 -e, --edit
14400 invoke editor on commit messages
14401 --log append transplant info to log message
14403 --stop stop interrupted transplant
14405 -c, --continue
14407 continue last transplant session after fixing conflicts
14408 --filter <CMD>
14410 filter changesets through command
14411 [+] marked option can be specified multiple times
14413 uncommit
14415 uncommit part or all of a local changeset (EXPERIMENTAL)
14416 This command undoes the effect of a local commit, returning the af‐
14418 fected files to their uncommitted state. This means that files modi‐
14419 fied, added or removed in the changeset will be left unchanged, and so
14420 will remain modified, added and removed in the working directory.
14421 Commands
14423 Change manipulation
14424 unamend
14425 undo the most recent amend operation on a current changeset:
14426 hg unamend
14428 This command will roll back to the previous version of a changeset,
14430 leaving working directory in state in which it was before running hg
14431 amend (e.g. files modified as part of an amend will be marked as modi‐
14432 fied hg status)
14433 uncommit
14435 uncommit part or all of a local changeset:
14436 hg uncommit [OPTION]... [FILE]...
14438 This command undoes the effect of a local commit, returning the af‐
14440 fected files to their uncommitted state. This means that files modified
14441 or deleted in the changeset will be left unchanged, and so will remain
14442 modified in the working directory.
14443 If no files are specified, the commit will be pruned, unless --keep is
14445 given.
14446 Options:
14448 --keep allow an empty commit after uncommitting
14450 --allow-dirty-working-copy
14452 allow uncommit with outstanding changes
14453 -n,--note <TEXT>
14455 store a note on uncommit
14456 -I,--include <PATTERN[+]>
14458 include names matching the given patterns
14459 -X,--exclude <PATTERN[+]>
14461 exclude names matching the given patterns
14462 -m,--message <TEXT>
14464 use text as commit message
14465 -l,--logfile <FILE>
14467 read commit message from file
14468 -d,--date <DATE>
14470 record the specified date as commit date
14471 -u,--user <USER>
14473 record the specified user as committer
14474 -D, --currentdate
14476 record the current date as commit date
14477 -U, --currentuser
14479 record the current user as committer
14480 [+] marked option can be specified multiple times
14482 win32mbcs
14484 allow the use of MBCS paths with problematic encodings
14485 Some MBCS encodings are not good for some path operations (i.e. split‐
14487 ting path, case conversion, etc.) with its encoded bytes. We call such
14488 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
14489 extension can be used to fix the issue with those encodings by wrapping
14490 some functions to convert to Unicode string before path operation.
14491 This extension is useful for:
14493 • Japanese Windows users using shift_jis encoding.
14495 • Chinese Windows users using big5 encoding.
14497 • All users who use a repository with one of problematic encodings on
14499 case-insensitive file system.
14500 This extension is not needed for:
14502 • Any user who use only ASCII chars in path.
14504 • Any user who do not use any of problematic encodings.
14506 Note that there are some limitations on using this extension:
14508 • You should use single encoding in one repository.
14510 • If the repository path ends with 0x5c, .hg/hgrc cannot be read.
14512 • win32mbcs is not compatible with fixutf8 extension.
14514 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
14516 can specify the encoding by config option:
14517 [win32mbcs]
14519 encoding = sjis
14520 It is useful for the users who want to commit with UTF-8 log message.
14522 win32text
14524 perform automatic newline conversion (DEPRECATED)
14525 Deprecation: The win32text extension requires each user to configure
14527 the extension again and again for each clone since the configuration
14528 is not copied when cloning.
14529 We have therefore made the eol as an alternative. The eol uses a
14531 version controlled file for its configuration and each clone will
14532 therefore use the right settings from the start.
14533 To perform automatic newline conversion, use:
14535 [extensions]
14537 win32text =
14538 [encode]
14539 ** = cleverencode:
14540 # or ** = macencode:
14541 [decode]
14543 ** = cleverdecode:
14544 # or ** = macdecode:
14545 If not doing conversion, to make sure you do not commit CRLF/CR by ac‐
14547 cident:
14548 [hooks]
14550 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
14551 # or pretxncommit.cr = python:hgext.win32text.forbidcr
14552 To do the same check on a server to prevent CRLF/CR from being pushed
14554 or pulled:
14555 [hooks]
14557 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
14558 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
14559 zeroconf
14561 discover and advertise repositories on the local network
14562 The zeroconf extension will advertise hg serve instances over DNS-SD so
14564 that they can be discovered using the hg paths command without knowing
14565 the server's IP address.
14566 To allow other people to discover your repository using run hg serve in
14568 your repository:
14569 $ cd test
14571 $ hg serve
14572 You can discover Zeroconf-enabled repositories by running hg paths:
14574 $ hg paths
14576 zc-test = http://example.com:8000/test
14577
14579 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
14580 This file contains defaults and configuration. Values in
14582 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
14583 tings made in the global /etc/mercurial/hgrc configuration. See
14584 hgrc(5) for details of the contents and format of these files.
14585 .hgignore
14587 This file contains regular expressions (one per line) that de‐
14589 scribe file names that should be ignored by hg. For details, see
14590 hgignore(5).
14591 .hgsub
14593 This file defines the locations of all subrepositories, and
14595 tells where the subrepository checkouts came from. For details,
14596 see hg help subrepos.
14597 .hgsubstate
14599 This file is where Mercurial stores all nested repository
14601 states. NB: This file should not be edited manually.
14602 .hgtags
14604 This file contains changeset hash values and text tag names (one
14606 of each separated by spaces) that correspond to tagged versions
14607 of the repository contents. The file content is encoded using
14608 UTF-8.
14609 .hg/last-message.txt
14611 This file is used by hg commit to store a backup of the commit
14613 message in case the commit fails.
14614 .hg/localtags
14616 This file can be used to define local tags which are not shared
14618 among repositories. The file format is the same as for .hgtags,
14619 but it is encoded using the local system encoding.
14620 Some commands (e.g. revert) produce backup files ending in .orig, if
14622 the .orig file already exists and is not tracked by Mercurial, it will
14623 be overwritten.
14624
14626 Probably lots, please post them to the mailing list (see Resources
14627 below) when you find them.
14628
14630 hgignore(5), hgrc(5)
14631
14633 Written by Olivia Mackall <olivia@selenic.com>
14634
14636 Main Web Site: https://mercurial-scm.org/
14637 Source code repository: https://www.mercurial-scm.org/repo/hg
14639 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
14641
14643 Copyright (C) 2005-2023 Olivia Mackall. Free use of this software is
14644 granted under the terms of the GNU General Public License version 2 or
14645 any later version.
14646
14648 Olivia Mackall <olivia@selenic.com>
14649 Organization: Mercurial
14651 HG(1)