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.
1724 By default, the working directory files are compared to its first par‐
1726 ent. To see the differences from another revision, use --from. To see
1727 the difference to another revision, use --to. For example, hg diff
1728 --from .^ will show the differences from the working copy's grandparent
1729 to the working copy, hg diff --to . will show the diff from the working
1730 copy to its parent (i.e. the reverse of the default), and hg diff
1731 --from 1.0 --to 1.2 will show the diff between those two revisions.
1732 Alternatively you can specify -c/--change with a revision to see the
1734 changes in that changeset relative to its first parent (i.e. hg diff -c
1735 42 is equivalent to hg diff --from 42^ --to 42)
1736 Without the -a/--text option, diff will avoid generating diffs of files
1738 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1739 bly with undesirable results.
1740 Use the -g/--git option to generate diffs in the git extended diff for‐
1742 mat. For more information, read hg help diffs.
1743 Examples:
1745 • compare a file in the current working directory to its parent:
1747 hg diff foo.c
1749 • compare two historical versions of a directory, with rename info:
1751 hg diff --git --from 1.0 --to 1.2 lib/
1753 • get change stats relative to the last change on some date:
1755 hg diff --stat --from "date('may 2')"
1757 • diff all newly-added files that contain a keyword:
1759 hg diff "set:added() and grep(GNU)"
1761 • compare a revision and its parents:
1763 hg diff -c 9353 # compare against first parent
1765 hg diff --from 9353^ --to 9353 # same using revset syntax
1766 hg diff --from 9353^2 --to 9353 # compare against the second parent
1767 Returns 0 on success.
1769 Options:
1771 -r,--rev <REV[+]>
1773 revision (DEPRECATED)
1774 --from <REV1>
1776 revision to diff from
1777 --to <REV2>
1779 revision to diff to
1780 -c,--change <REV>
1782 change made by revision
1783 -a, --text
1785 treat all files as text
1786 -g, --git
1788 use git extended diff format (DEFAULT: diff.git)
1789 --binary
1791 generate binary diffs in git mode (default)
1792 --nodates
1794 omit dates from diff headers
1795 --noprefix
1797 omit a/ and b/ prefixes from filenames
1798 -p, --show-function
1800 show which function each change is in (DEFAULT: diff.showfunc)
1801 --reverse
1803 produce a diff that undoes the changes
1804 -w, --ignore-all-space
1806 ignore white space when comparing lines
1807 -b, --ignore-space-change
1809 ignore changes in the amount of white space
1810 -B, --ignore-blank-lines
1812 ignore changes whose lines are all blank
1813 -Z, --ignore-space-at-eol
1815 ignore changes in whitespace at EOL
1816 -U,--unified <NUM>
1818 number of lines of context to show
1819 --stat output diffstat-style summary of changes
1821 --root <DIR>
1823 produce diffs relative to subdirectory
1824 -I,--include <PATTERN[+]>
1826 include names matching the given patterns
1827 -X,--exclude <PATTERN[+]>
1829 exclude names matching the given patterns
1830 -S, --subrepos
1832 recurse into subrepositories
1833 [+] marked option can be specified multiple times
1835 grep
1837 search for a pattern in specified files:
1838 hg grep [--diff] [OPTION]... PATTERN [FILE]...
1840 Search the working directory or revision history for a regular expres‐
1842 sion in the specified files for the entire repository.
1843 By default, grep searches the repository files in the working directory
1845 and prints the files where it finds a match. To specify historical re‐
1846 visions instead of the working directory, use the --rev flag.
1847 To search instead historical revision differences that contains a
1849 change in match status ("-" for a match that becomes a non-match, or
1850 "+" for a non-match that becomes a match), use the --diff flag.
1851 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1853 If no FILEs are specified and the --rev flag isn't supplied, all files
1855 in the working directory are searched. When using the --rev flag and
1856 specifying FILEs, use the --follow argument to also follow the speci‐
1857 fied FILEs across renames and copies.
1858 Template:
1860 The following keywords are supported in addition to the common template
1862 keywords and functions. See also hg help templates.
1863 change String. Character denoting insertion + or removal -. Available
1865 if --diff is specified.
1866 lineno Integer. Line number of the match.
1868 path String. Repository-absolute path of the file.
1870 texts List of text chunks.
1872 And each entry of {texts} provides the following sub-keywords.
1874 matched
1876 Boolean. True if the chunk matches the specified pattern.
1877 text String. Chunk content.
1879 See hg help templates.operators for the list expansion syntax.
1881 Returns 0 if a match is found, 1 otherwise.
1883 Options:
1885 -0, --print0
1887 end fields with NUL
1888 --all an alias to --diff (DEPRECATED)
1890 --diff search revision differences for when the pattern was added or
1892 removed
1893 -a, --text
1895 treat all files as text
1896 -f, --follow
1898 follow changeset history, or file history across copies and re‐
1899 names
1900 -i, --ignore-case
1902 ignore case when matching
1903 -l, --files-with-matches
1905 print only filenames and revisions that match
1906 -n, --line-number
1908 print matching line numbers
1909 -r,--rev <REV[+]>
1911 search files changed within revision range
1912 --all-files
1914 include all files in the changeset while grepping (DEPRECATED)
1915 -u, --user
1917 list the author (long with -v)
1918 -d, --date
1920 list the date (short with -q)
1921 -T,--template <TEMPLATE>
1923 display with template
1924 -I,--include <PATTERN[+]>
1926 include names matching the given patterns
1927 -X,--exclude <PATTERN[+]>
1929 exclude names matching the given patterns
1930 [+] marked option can be specified multiple times
1932 Change navigation
1934 bisect
1935 subdivision search of changesets:
1936 hg bisect [-gbsr] [-U] [-c CMD] [REV]
1938 This command helps to find changesets which introduce problems. To use,
1940 mark the earliest changeset you know exhibits the problem as bad, then
1941 mark the latest changeset which is free from the problem as good. Bi‐
1942 sect will update your working directory to a revision for testing (un‐
1943 less the -U/--noupdate option is specified). Once you have performed
1944 tests, mark the working directory as good or bad, and bisect will ei‐
1945 ther update to another candidate changeset or announce that it has
1946 found the bad revision.
1947 As a shortcut, you can also use the revision argument to mark a revi‐
1949 sion as good or bad without checking it out first.
1950 If you supply a command, it will be used for automatic bisection. The
1952 environment variable HG_NODE will contain the ID of the changeset being
1953 tested. The exit status of the command will be used to mark revisions
1954 as good or bad: status 0 means good, 125 means to skip the revision,
1955 127 (command not found) will abort the bisection, and any other
1956 non-zero exit status means the revision is bad.
1957 Some examples:
1959 • start a bisection with known bad revision 34, and good revision 12:
1961 hg bisect --bad 34
1963 hg bisect --good 12
1964 • advance the current bisection by marking current revision as good or
1966 bad:
1967 hg bisect --good
1969 hg bisect --bad
1970 • mark the current revision, or a known revision, to be skipped (e.g.
1972 if that revision is not usable because of another issue):
1973 hg bisect --skip
1975 hg bisect --skip 23
1976 • skip all revisions that do not touch directories foo or bar:
1978 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
1980 • forget the current bisection:
1982 hg bisect --reset
1984 • use 'make && make tests' to automatically find the first broken revi‐
1986 sion:
1987 hg bisect --reset
1989 hg bisect --bad 34
1990 hg bisect --good 12
1991 hg bisect --command "make && make tests"
1992 • see all changesets whose states are already known in the current bi‐
1994 section:
1995 hg log -r "bisect(pruned)"
1997 • see the changeset currently being bisected (especially useful if run‐
1999 ning with -U/--noupdate):
2000 hg log -r "bisect(current)"
2002 • see all changesets that took part in the current bisection:
2004 hg log -r "bisect(range)"
2006 • you can even get a nice graph:
2008 hg log --graph -r "bisect(range)"
2010 See hg help revisions.bisect for more about the bisect() predicate.
2012 Returns 0 on success.
2014 Options:
2016 -r, --reset
2018 reset bisect state
2019 -g, --good
2021 mark changeset good
2022 -b, --bad
2024 mark changeset bad
2025 -s, --skip
2027 skip testing changeset
2028 -e, --extend
2030 extend the bisect range
2031 -c,--command <CMD>
2033 use command to check changeset state
2034 -U, --noupdate
2036 do not update to target
2037 heads
2039 show branch heads:
2040 hg heads [-ct] [-r STARTREV] [REV]...
2042 With no arguments, show all open branch heads in the repository.
2044 Branch heads are changesets that have no descendants on the same
2045 branch. They are where development generally takes place and are the
2046 usual targets for update and merge operations.
2047 If one or more REVs are given, only open branch heads on the branches
2049 associated with the specified changesets are shown. This means that you
2050 can use hg heads . to see the heads on the currently checked-out
2051 branch.
2052 If -c/--closed is specified, also show branch heads marked closed (see
2054 hg commit --close-branch).
2055 If STARTREV is specified, only those heads that are descendants of
2057 STARTREV will be displayed.
2058 If -t/--topo is specified, named branch mechanics will be ignored and
2060 only topological heads (changesets with no children) will be shown.
2061 Returns 0 if matching heads are found, 1 if not.
2063 Options:
2065 -r,--rev <STARTREV>
2067 show only heads which are descendants of STARTREV
2068 -t, --topo
2070 show topological heads only
2071 -a, --active
2073 show active branchheads only (DEPRECATED)
2074 -c, --closed
2076 show normal and closed branch heads
2077 --style <STYLE>
2079 display using template map file (DEPRECATED)
2080 -T,--template <TEMPLATE>
2082 display with template
2083 identify
2085 identify the working directory or specified revision:
2086 hg identify [-nibtB] [-r REV] [SOURCE]
2088 Print a summary identifying the repository state at REV using one or
2090 two parent hash identifiers, followed by a "+" if the working directory
2091 has uncommitted changes, the branch name (if not default), a list of
2092 tags, and a list of bookmarks.
2093 When REV is not given, print a summary of the current state of the
2095 repository including the working directory. Specify -r. to get informa‐
2096 tion of the working directory parent without scanning uncommitted
2097 changes.
2098 Specifying a path to a repository root or Mercurial bundle will cause
2100 lookup to operate on that repository/bundle.
2101 Template:
2103 The following keywords are supported in addition to the common template
2105 keywords and functions. See also hg help templates.
2106 dirty String. Character + denoting if the working directory has uncom‐
2108 mitted changes.
2109 id String. One or two nodes, optionally followed by +.
2111 parents
2113 List of strings. Parent nodes of the changeset.
2114 Examples:
2116 • generate a build identifier for the working directory:
2118 hg id --id > build-id.dat
2120 • find the revision corresponding to a tag:
2122 hg id -n -r 1.3
2124 • check the most recent revision of a remote repository:
2126 hg id -r tip https://www.mercurial-scm.org/repo/hg/
2128 See hg log for generating more information about specific revisions,
2130 including full hash identifiers.
2131 Returns 0 if successful.
2133 Options:
2135 -r,--rev <REV>
2137 identify the specified revision
2138 -n, --num
2140 show local revision number
2141 -i, --id
2143 show global revision id
2144 -b, --branch
2146 show branch
2147 -t, --tags
2149 show tags
2150 -B, --bookmarks
2152 show bookmarks
2153 -e,--ssh <CMD>
2155 specify ssh command to use
2156 --remotecmd <CMD>
2158 specify hg command to run on the remote side
2159 --insecure
2161 do not verify server certificate (ignoring web.cacerts config)
2162 -T,--template <TEMPLATE>
2164 display with template
2165 aliases: id
2167 log
2169 show revision history of entire repository or files:
2170 hg log [OPTION]... [FILE]
2172 Print the revision history of the specified files or the entire
2174 project.
2175 If no revision range is specified, the default is tip:0 unless --follow
2177 is set.
2178 File history is shown without following rename or copy history of
2180 files. Use -f/--follow with a filename to follow history across renames
2181 and copies. --follow without a filename will only show ancestors of the
2182 starting revisions. The starting revisions can be specified by
2183 -r/--rev, which default to the working directory parent.
2184 By default this command prints revision number and changeset id, tags,
2186 non-trivial parents, user, date and time, and a summary for each com‐
2187 mit. When the -v/--verbose switch is used, the list of changed files
2188 and full commit message are shown.
2189 With --graph the revisions are shown as an ASCII art DAG with the most
2191 recent changeset at the top. 'o' is a changeset, '@' is a working di‐
2192 rectory parent, '%' is a changeset involved in an unresolved merge con‐
2193 flict, '_' closes a branch, 'x' is obsolete, '*' is unstable, and '+'
2194 represents a fork where the changeset from the lines below is a parent
2195 of the 'o' merge on the same line. Paths in the DAG are represented
2196 with '|', '/' and so forth. ':' in place of a '|' indicates one or more
2197 revisions in a path are omitted.
2198 Use -L/--line-range FILE,M:N options to follow the history of lines
2200 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2201 fied line range will be shown. This option requires --follow; it can be
2202 specified multiple times. Currently, this option is not compatible with
2203 --graph. This option is experimental.
2204 Note hg log --patch may generate unexpected diff output for merge
2206 changesets, as it will only compare the merge changeset against
2207 its first parent. Also, only files different from BOTH parents
2208 will appear in files:.
2209 Note For performance reasons, hg log FILE may omit duplicate changes
2211 made on branches and will not show removals or mode changes. To
2212 see all such changes, use the --removed switch.
2213 Note The history resulting from -L/--line-range options depends on
2215 diff options; for instance if white-spaces are ignored, respec‐
2216 tive changes with only white-spaces in specified line range will
2217 not be listed.
2218 Some examples:
2220 • changesets with full descriptions and file lists:
2222 hg log -v
2224 • changesets ancestral to the working directory:
2226 hg log -f
2228 • last 10 commits on the current branch:
2230 hg log -l 10 -b .
2232 • changesets showing all modifications of a file, including removals:
2234 hg log --removed file.c
2236 • all changesets that touch a directory, with diffs, excluding merges:
2238 hg log -Mp lib/
2240 • all revision numbers that match a keyword:
2242 hg log -k bug --template "{rev}\n"
2244 • the full hash identifier of the working directory parent:
2246 hg log -r . --template "{node}\n"
2248 • list available log templates:
2250 hg log -T list
2252 • check if a given changeset is included in a tagged release:
2254 hg log -r "a21ccf and ancestor(1.9)"
2256 • find all changesets by some user in a date range:
2258 hg log -k alice -d "may 2008 to jul 2008"
2260 • summary of all changesets after the last tag:
2262 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2264 • changesets touching lines 13 to 23 for file.c:
2266 hg log -L file.c,13:23
2268 • changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2270 main.c with patch:
2271 hg log -L file.c,13:23 -L main.c,2:6 -p
2273 See hg help dates for a list of formats valid for -d/--date.
2275 See hg help revisions for more about specifying and ordering revisions.
2277 See hg help templates for more about pre-packaged styles and specifying
2279 custom templates. The default template used by the log command can be
2280 customized via the command-templates.log configuration setting.
2281 Returns 0 on success.
2283 Options:
2285 -f, --follow
2287 follow changeset history, or file history across copies and re‐
2288 names
2289 --follow-first
2291 only follow the first parent of merge changesets (DEPRECATED)
2292 -d,--date <DATE>
2294 show revisions matching date spec
2295 -C, --copies
2297 show copied files
2298 -k,--keyword <TEXT[+]>
2300 do case-insensitive search for a given text
2301 -r,--rev <REV[+]>
2303 revisions to select or follow from
2304 -L,--line-range <FILE,RANGE[+]>
2306 follow line range of specified file (EXPERIMENTAL)
2307 --removed
2309 include revisions where files were removed
2310 -m, --only-merges
2312 show only merges (DEPRECATED) (use -r "merge()" instead)
2313 -u,--user <USER[+]>
2315 revisions committed by user
2316 --only-branch <BRANCH[+]>
2318 show only changesets within the given named branch (DEPRECATED)
2319 -b,--branch <BRANCH[+]>
2321 show changesets within the given named branch
2322 -B,--bookmark <BOOKMARK[+]>
2324 show changesets within the given bookmark
2325 -P,--prune <REV[+]>
2327 do not display revision or any of its ancestors
2328 -p, --patch
2330 show patch
2331 -g, --git
2333 use git extended diff format
2334 -l,--limit <NUM>
2336 limit number of changes displayed
2337 -M, --no-merges
2339 do not show merges
2340 --stat output diffstat-style summary of changes
2342 -G, --graph
2344 show the revision DAG
2345 --style <STYLE>
2347 display using template map file (DEPRECATED)
2348 -T,--template <TEMPLATE>
2350 display with template
2351 -I,--include <PATTERN[+]>
2353 include names matching the given patterns
2354 -X,--exclude <PATTERN[+]>
2356 exclude names matching the given patterns
2357 [+] marked option can be specified multiple times
2359 aliases: history
2361 parents
2363 show the parents of the working directory or revision (DEPRECATED):
2364 hg parents [-r REV] [FILE]
2366 Print the working directory's parent revisions. If a revision is given
2368 via -r/--rev, the parent of that revision will be printed. If a file
2369 argument is given, the revision in which the file was last changed (be‐
2370 fore the working directory revision or the argument to --rev if given)
2371 is printed.
2372 This command is equivalent to:
2374 hg log -r "p1()+p2()" or
2376 hg log -r "p1(REV)+p2(REV)" or
2377 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2378 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2379 See hg summary and hg help revsets for related information.
2381 Returns 0 on success.
2383 Options:
2385 -r,--rev <REV>
2387 show parents of the specified revision
2388 --style <STYLE>
2390 display using template map file (DEPRECATED)
2391 -T,--template <TEMPLATE>
2393 display with template
2394 tip
2396 show the tip revision (DEPRECATED):
2397 hg tip [-p] [-g]
2399 The tip revision (usually just called the tip) is the changeset most
2401 recently added to the repository (and therefore the most recently
2402 changed head).
2403 If you have just made a commit, that commit will be the tip. If you
2405 have just pulled changes from another repository, the tip of that
2406 repository becomes the current tip. The "tip" tag is special and cannot
2407 be renamed or assigned to a different changeset.
2408 This command is deprecated, please use hg heads instead.
2410 Returns 0 on success.
2412 Options:
2414 -p, --patch
2416 show patch
2417 -g, --git
2419 use git extended diff format
2420 --style <STYLE>
2422 display using template map file (DEPRECATED)
2423 -T,--template <TEMPLATE>
2425 display with template
2426 Working directory management
2428 add
2429 add the specified files on the next commit:
2430 hg add [OPTION]... [FILE]...
2432 Schedule files to be version controlled and added to the repository.
2434 The files will be added to the repository at the next commit. To undo
2436 an add before that, see hg forget.
2437 If no names are given, add all files to the repository (except files
2439 matching .hgignore).
2440 Examples:
2442 • New (unknown) files are added automatically by hg add:
2444 $ ls
2446 foo.c
2447 $ hg status
2448 ? foo.c
2449 $ hg add
2450 adding foo.c
2451 $ hg status
2452 A foo.c
2453 • Specific files to be added can be specified:
2455 $ ls
2457 bar.c foo.c
2458 $ hg status
2459 ? bar.c
2460 ? foo.c
2461 $ hg add bar.c
2462 $ hg status
2463 A bar.c
2464 ? foo.c
2465 Returns 0 if all files are successfully added.
2467 Options:
2469 -I,--include <PATTERN[+]>
2471 include names matching the given patterns
2472 -X,--exclude <PATTERN[+]>
2474 exclude names matching the given patterns
2475 -S, --subrepos
2477 recurse into subrepositories
2478 -n, --dry-run
2480 do not perform actions, just print output
2481 [+] marked option can be specified multiple times
2483 addremove
2485 add all new files, delete all missing files:
2486 hg addremove [OPTION]... [FILE]...
2488 Add all new files and remove all missing files from the repository.
2490 Unless names are given, new files are ignored if they match any of the
2492 patterns in .hgignore. As with add, these changes take effect at the
2493 next commit.
2494 Use the -s/--similarity option to detect renamed files. This option
2496 takes a percentage between 0 (disabled) and 100 (files must be identi‐
2497 cal) as its parameter. With a parameter greater than 0, this compares
2498 every removed file with every added file and records those similar
2499 enough as renames. Detecting renamed files this way can be expensive.
2500 After using this option, hg status -C can be used to check which files
2501 were identified as moved or renamed. If not specified, -s/--similarity
2502 defaults to 100 and only renames of identical files are detected.
2503 Examples:
2505 • A number of files (bar.c and foo.c) are new, while foobar.c has
2507 been removed (without using hg remove) from the repository:
2508 $ ls
2510 bar.c foo.c
2511 $ hg status
2512 ! foobar.c
2513 ? bar.c
2514 ? foo.c
2515 $ hg addremove
2516 adding bar.c
2517 adding foo.c
2518 removing foobar.c
2519 $ hg status
2520 A bar.c
2521 A foo.c
2522 R foobar.c
2523 • A file foobar.c was moved to foo.c without using hg rename. Af‐
2525 terwards, it was edited slightly:
2526 $ ls
2528 foo.c
2529 $ hg status
2530 ! foobar.c
2531 ? foo.c
2532 $ hg addremove --similarity 90
2533 removing foobar.c
2534 adding foo.c
2535 recording removal of foobar.c as rename to foo.c (94% similar)
2536 $ hg status -C
2537 A foo.c
2538 foobar.c
2539 R foobar.c
2540 Returns 0 if all files are successfully added.
2542 Options:
2544 -s,--similarity <SIMILARITY>
2546 guess renamed files by similarity (0<=s<=100)
2547 -S, --subrepos
2549 recurse into subrepositories
2550 -I,--include <PATTERN[+]>
2552 include names matching the given patterns
2553 -X,--exclude <PATTERN[+]>
2555 exclude names matching the given patterns
2556 -n, --dry-run
2558 do not perform actions, just print output
2559 [+] marked option can be specified multiple times
2561 files
2563 list tracked files:
2564 hg files [OPTION]... [FILE]...
2566 Print files under Mercurial control in the working directory or speci‐
2568 fied revision for given files (excluding removed files). Files can be
2569 specified as filenames or filesets.
2570 If no files are given to match, this command prints the names of all
2572 files under Mercurial control.
2573 Template:
2575 The following keywords are supported in addition to the common template
2577 keywords and functions. See also hg help templates.
2578 flags String. Character denoting file's symlink and executable bits.
2580 path String. Repository-absolute path of the file.
2582 size Integer. Size of the file in bytes.
2584 Examples:
2586 • list all files under the current directory:
2588 hg files .
2590 • shows sizes and flags for current revision:
2592 hg files -vr .
2594 • list all files named README:
2596 hg files -I "**/README"
2598 • list all binary files:
2600 hg files "set:binary()"
2602 • find files containing a regular expression:
2604 hg files "set:grep('bob')"
2606 • search tracked file contents with xargs and grep:
2608 hg files -0 | xargs -0 grep foo
2610 See hg help patterns and hg help filesets for more information on spec‐
2612 ifying file patterns.
2613 Returns 0 if a match is found, 1 otherwise.
2615 Options:
2617 -r,--rev <REV>
2619 search the repository as it is in REV
2620 -0, --print0
2622 end filenames with NUL, for use with xargs
2623 -I,--include <PATTERN[+]>
2625 include names matching the given patterns
2626 -X,--exclude <PATTERN[+]>
2628 exclude names matching the given patterns
2629 -T,--template <TEMPLATE>
2631 display with template
2632 -S, --subrepos
2634 recurse into subrepositories
2635 [+] marked option can be specified multiple times
2637 forget
2639 forget the specified files on the next commit:
2640 hg forget [OPTION]... FILE...
2642 Mark the specified files so they will no longer be tracked after the
2644 next commit.
2645 This only removes files from the current branch, not from the entire
2647 project history, and it does not delete them from the working direc‐
2648 tory.
2649 To delete the file from the working directory, see hg remove.
2651 To undo a forget before the next commit, see hg add.
2653 Examples:
2655 • forget newly-added binary files:
2657 hg forget "set:added() and binary()"
2659 • forget files that would be excluded by .hgignore:
2661 hg forget "set:hgignore()"
2663 Returns 0 on success.
2665 Options:
2667 -i, --interactive
2669 use interactive mode
2670 -I,--include <PATTERN[+]>
2672 include names matching the given patterns
2673 -X,--exclude <PATTERN[+]>
2675 exclude names matching the given patterns
2676 -n, --dry-run
2678 do not perform actions, just print output
2679 [+] marked option can be specified multiple times
2681 locate
2683 locate files matching specific patterns (DEPRECATED):
2684 hg locate [OPTION]... [PATTERN]...
2686 Print files under Mercurial control in the working directory whose
2688 names match the given patterns.
2689 By default, this command searches all directories in the working direc‐
2691 tory. To search just the current directory and its subdirectories, use
2692 "--include .".
2693 If no patterns are given to match, this command prints the names of all
2695 files under Mercurial control in the working directory.
2696 If you want to feed the output of this command into the "xargs" com‐
2698 mand, use the -0 option to both this command and "xargs". This will
2699 avoid the problem of "xargs" treating single filenames that contain
2700 whitespace as multiple filenames.
2701 See hg help files for a more versatile command.
2703 Returns 0 if a match is found, 1 otherwise.
2705 Options:
2707 -r,--rev <REV>
2709 search the repository as it is in REV
2710 -0, --print0
2712 end filenames with NUL, for use with xargs
2713 -f, --fullpath
2715 print complete paths from the filesystem root
2716 -I,--include <PATTERN[+]>
2718 include names matching the given patterns
2719 -X,--exclude <PATTERN[+]>
2721 exclude names matching the given patterns
2722 [+] marked option can be specified multiple times
2724 purge
2726 removes files not tracked by Mercurial:
2727 hg purge [OPTION]... [DIR]...
2729 Delete files not known to Mercurial. This is useful to test local and
2731 uncommitted changes in an otherwise-clean source tree.
2732 This means that purge will delete the following by default:
2734 • Unknown files: files marked with "?" by hg status
2736 • Empty directories: in fact Mercurial ignores directories unless they
2738 contain files under source control management
2739 But it will leave untouched:
2741 • Modified and unmodified tracked files
2743 • Ignored files (unless -i or --all is specified)
2745 • New files added to the repository (with hg add)
2747 The --files and --dirs options can be used to direct purge to delete
2749 only files, only directories, or both. If neither option is given, both
2750 will be deleted.
2751 If directories are given on the command line, only files in these di‐
2753 rectories are considered.
2754 Be careful with purge, as you could irreversibly delete some files you
2756 forgot to add to the repository. If you only want to print the list of
2757 files that this program would delete, use the --print option.
2758 Options:
2760 -a, --abort-on-err
2762 abort if an error occurs
2763 --all purge ignored files too
2765 -i, --ignored
2767 purge only ignored files
2768 --dirs purge empty directories
2770 --files
2772 purge files
2773 -p, --print
2775 print filenames instead of deleting them
2776 -0, --print0
2778 end filenames with NUL, for use with xargs (implies -p/--print)
2779 --confirm
2781 ask before permanently deleting files
2782 -I,--include <PATTERN[+]>
2784 include names matching the given patterns
2785 -X,--exclude <PATTERN[+]>
2787 exclude names matching the given patterns
2788 [+] marked option can be specified multiple times
2790 aliases: clean
2792 remove
2794 remove the specified files on the next commit:
2795 hg remove [OPTION]... FILE...
2797 Schedule the indicated files for removal from the current branch.
2799 This command schedules the files to be removed at the next commit. To
2801 undo a remove before that, see hg revert. To undo added files, see hg
2802 forget.
2803 -A/--after can be used to remove only files that have already been
2805 deleted, -f/--force can be used to force deletion, and -Af can be used
2806 to remove files from the next revision without deleting them from the
2807 working directory.
2808 The following table details the behavior of remove for different file
2810 states (columns) and option combinations (rows). The file states are
2811 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2812 status). The actions are Warn, Remove (from branch) and Delete (from
2813 disk):
2814 ┌──────────┬───┬────┬────┬───┐
2816 │opt/state │ A │ C │ M │ ! │
2817 ├──────────┼───┼────┼────┼───┤
2818 │none │ W │ RD │ W │ R │
2819 ├──────────┼───┼────┼────┼───┤
2820 │-f │ R │ RD │ RD │ R │
2821 ├──────────┼───┼────┼────┼───┤
2822 │-A │ W │ W │ W │ R │
2823 ├──────────┼───┼────┼────┼───┤
2824 │-Af │ R │ R │ R │ R │
2825 └──────────┴───┴────┴────┴───┘
2826 Note hg remove never deletes files in Added [A] state from the work‐
2828 ing directory, not even if --force is specified.
2829 Returns 0 on success, 1 if any warnings encountered.
2831 Options:
2833 -A, --after
2835 record delete for missing files
2836 -f, --force
2838 forget added files, delete modified files
2839 -S, --subrepos
2841 recurse into subrepositories
2842 -I,--include <PATTERN[+]>
2844 include names matching the given patterns
2845 -X,--exclude <PATTERN[+]>
2847 exclude names matching the given patterns
2848 -n, --dry-run
2850 do not perform actions, just print output
2851 [+] marked option can be specified multiple times
2853 aliases: rm
2855 rename
2857 rename files; equivalent of copy + remove:
2858 hg rename [OPTION]... SOURCE... DEST
2860 Mark dest as copies of sources; mark sources for deletion. If dest is a
2862 directory, copies are put in that directory. If dest is a file, there
2863 can only be one source.
2864 By default, this command copies the contents of files as they exist in
2866 the working directory. If invoked with -A/--after, the operation is
2867 recorded, but no copying is performed.
2868 To undo marking a destination file as renamed, use --forget. With that
2870 option, all given (positional) arguments are unmarked as renames. The
2871 destination file(s) will be left in place (still tracked). The source
2872 file(s) will not be restored. Note that hg rename --forget behaves the
2873 same way as hg copy --forget.
2874 This command takes effect with the next commit by default.
2876 Returns 0 on success, 1 if errors are encountered.
2878 Options:
2880 --forget
2882 unmark a destination file as renamed
2883 -A, --after
2885 record a rename that has already occurred
2886 --at-rev <REV>
2888 (un)mark renames in the given revision (EXPERIMENTAL)
2889 -f, --force
2891 forcibly move over an existing managed file
2892 -I,--include <PATTERN[+]>
2894 include names matching the given patterns
2895 -X,--exclude <PATTERN[+]>
2897 exclude names matching the given patterns
2898 -n, --dry-run
2900 do not perform actions, just print output
2901 [+] marked option can be specified multiple times
2903 aliases: move mv
2905 resolve
2907 redo merges or set/view the merge status of files:
2908 hg resolve [OPTION]... [FILE]...
2910 Merges with unresolved conflicts are often the result of non-interac‐
2912 tive merging using the internal:merge configuration setting, or a com‐
2913 mand-line merge tool like diff3. The resolve command is used to manage
2914 the files involved in a merge, after hg merge has been run, and before
2915 hg commit is run (i.e. the working directory must have two parents).
2916 See hg help merge-tools for information on configuring merge tools.
2917 The resolve command can be used in the following ways:
2919 • hg resolve [--re-merge] [--tool TOOL] FILE...: attempt to re-merge
2921 the specified files, discarding any previous merge attempts. Re-merg‐
2922 ing is not performed for files already marked as resolved. Use
2923 --all/-a to select all unresolved files. --tool can be used to spec‐
2924 ify the merge tool used for the given files. It overrides the HGMERGE
2925 environment variable and your configuration files. Previous file
2926 contents are saved with a .orig suffix.
2927 • hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
2929 having manually fixed-up the files). The default is to mark all unre‐
2930 solved files.
2931 • hg resolve -u [FILE]...: mark a file as unresolved. The default is to
2933 mark all resolved files.
2934 • hg resolve -l: list files which had or still have conflicts. In the
2936 printed list, U = unresolved and R = resolved. You can use set:unre‐
2937 solved() or set:resolved() to filter the list. See hg help filesets
2938 for details.
2939 Note Mercurial will not let you commit files with unresolved merge
2941 conflicts. You must use hg resolve -m ... before you can commit
2942 after a conflicting merge.
2943 Template:
2945 The following keywords are supported in addition to the common template
2947 keywords and functions. See also hg help templates.
2948 mergestatus
2950 String. Character denoting merge conflicts, U or R.
2951 path String. Repository-absolute path of the file.
2953 Returns 0 on success, 1 if any files fail a resolve attempt.
2955 Options:
2957 -a, --all
2959 select all unresolved files
2960 -l, --list
2962 list state of files needing merge
2963 -m, --mark
2965 mark files as resolved
2966 -u, --unmark
2968 mark files as unresolved
2969 -n, --no-status
2971 hide status prefix
2972 --re-merge
2974 re-merge files
2975 -t,--tool <TOOL>
2977 specify merge tool
2978 -I,--include <PATTERN[+]>
2980 include names matching the given patterns
2981 -X,--exclude <PATTERN[+]>
2983 exclude names matching the given patterns
2984 -T,--template <TEMPLATE>
2986 display with template
2987 [+] marked option can be specified multiple times
2989 revert
2991 restore files to their checkout state:
2992 hg revert [OPTION]... [-r REV] [NAME]...
2994 Note To check out earlier revisions, you should use hg update REV.
2996 To cancel an uncommitted merge (and lose your changes), use hg
2997 merge --abort.
2998 With no revision specified, revert the specified files or directories
3000 to the contents they had in the parent of the working directory. This
3001 restores the contents of files to an unmodified state and unschedules
3002 adds, removes, copies, and renames. If the working directory has two
3003 parents, you must explicitly specify a revision.
3004 Using the -r/--rev or -d/--date options, revert the given files or di‐
3006 rectories to their states as of a specific revision. Because revert
3007 does not change the working directory parents, this will cause these
3008 files to appear modified. This can be helpful to "back out" some or all
3009 of an earlier change. See hg backout for a related method.
3010 Modified files are saved with a .orig suffix before reverting. To dis‐
3012 able these backups, use --no-backup. It is possible to store the backup
3013 files in a custom directory relative to the root of the repository by
3014 setting the ui.origbackuppath configuration option.
3015 See hg help dates for a list of formats valid for -d/--date.
3017 See hg help backout for a way to reverse the effect of an earlier
3019 changeset.
3020 Returns 0 on success.
3022 Options:
3024 -a, --all
3026 revert all changes when no arguments given
3027 -d,--date <DATE>
3029 tipmost revision matching date
3030 -r,--rev <REV>
3032 revert to the specified revision
3033 -C, --no-backup
3035 do not save backup copies of files
3036 -i, --interactive
3038 interactively select the changes
3039 -I,--include <PATTERN[+]>
3041 include names matching the given patterns
3042 -X,--exclude <PATTERN[+]>
3044 exclude names matching the given patterns
3045 -n, --dry-run
3047 do not perform actions, just print output
3048 [+] marked option can be specified multiple times
3050 root
3052 print the root (top) of the current working directory:
3053 hg root
3055 Print the root directory of the current repository.
3057 Template:
3059 The following keywords are supported in addition to the common template
3061 keywords and functions. See also hg help templates.
3062 hgpath String. Path to the .hg directory.
3064 storepath
3066 String. Path to the directory holding versioned data.
3067 Returns 0 on success.
3069 Options:
3071 -T,--template <TEMPLATE>
3073 display with template
3074 shelve
3076 save and set aside changes from the working directory:
3077 hg shelve [OPTION]... [FILE]...
3079 Shelving takes files that "hg status" reports as not clean, saves the
3081 modifications to a bundle (a shelved change), and reverts the files so
3082 that their state in the working directory becomes clean.
3083 To restore these changes to the working directory, using "hg unshelve";
3085 this will work even if you switch to a different commit.
3086 When no files are specified, "hg shelve" saves all not-clean files. If
3088 specific files or directories are named, only changes to those files
3089 are shelved.
3090 In bare shelve (when no files are specified, without interactive, in‐
3092 clude and exclude option), shelving remembers information if the work‐
3093 ing directory was on newly created branch, in other words working di‐
3094 rectory was on different branch than its first parent. In this situa‐
3095 tion unshelving restores branch information to the working directory.
3096 Each shelved change has a name that makes it easier to find later. The
3098 name of a shelved change defaults to being based on the active book‐
3099 mark, or if there is no active bookmark, the current named branch. To
3100 specify a different name, use --name.
3101 To see a list of existing shelved changes, use the --list option. For
3103 each shelved change, this will print its name, age, and description;
3104 use --patch or --stat for more details.
3105 To delete specific shelved changes, use --delete. To delete all shelved
3107 changes, use --cleanup.
3108 Options:
3110 -A, --addremove
3112 mark new/missing files as added/removed before shelving
3113 -u, --unknown
3115 store unknown files in the shelve
3116 --cleanup
3118 delete all shelved changes
3119 --date <DATE>
3121 shelve with the specified commit date
3122 -d, --delete
3124 delete the named shelved change(s)
3125 -e, --edit
3127 invoke editor on commit messages
3128 -k, --keep
3130 shelve, but keep changes in the working directory
3131 -l, --list
3133 list current shelves
3134 -m,--message <TEXT>
3136 use text as shelve message
3137 -n,--name <NAME>
3139 use the given name for the shelved commit
3140 -p, --patch
3142 output patches for changes (provide the names of the shelved
3143 changes as positional arguments)
3144 -i, --interactive
3146 interactive mode
3147 --stat output diffstat-style summary of changes (provide the names of
3149 the shelved changes as positional arguments)
3150 -I,--include <PATTERN[+]>
3152 include names matching the given patterns
3153 -X,--exclude <PATTERN[+]>
3155 exclude names matching the given patterns
3156 [+] marked option can be specified multiple times
3158 status
3160 show changed files in the working directory:
3161 hg status [OPTION]... [FILE]...
3163 Show status of files in the repository. If names are given, only files
3165 that match are shown. Files that are clean or ignored or the source of
3166 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3167 -C/--copies or -A/--all are given. Unless options described with "show
3168 only ..." are given, the options -mardu are used.
3169 Option -q/--quiet hides untracked (unknown and ignored) files unless
3171 explicitly requested with -u/--unknown or -i/--ignored.
3172 Note hg status may appear to disagree with diff if permissions have
3174 changed or a merge has occurred. The standard diff format does
3175 not report permission changes and diff only reports changes rel‐
3176 ative to one merge parent.
3177 If one revision is given, it is used as the base revision. If two re‐
3179 visions are given, the differences between them are shown. The --change
3180 option can also be used as a shortcut to list the changed files of a
3181 revision from its first parent.
3182 The codes used to show the status of files are:
3184 M = modified
3186 A = added
3187 R = removed
3188 C = clean
3189 ! = missing (deleted by non-hg command, but still tracked)
3190 ? = not tracked
3191 I = ignored
3192 = origin of the previous file (with --copies)
3193 The -t/--terse option abbreviates the output by showing only the direc‐
3195 tory name if all the files in it share the same status. The option
3196 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3197 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3198 'unknown', 'i' for 'ignored' and 'c' for clean.
3199 It abbreviates only those statuses which are passed. Note that clean
3201 and ignored files are not displayed with '--terse ic' unless the
3202 -c/--clean and -i/--ignored options are also used.
3203 The -v/--verbose option shows information when the repository is in an
3205 unfinished merge, shelve, rebase state etc. You can have this behavior
3206 turned on by default by enabling the commands.status.verbose option.
3207 You can skip displaying some of these states by setting commands.sta‐
3209 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3210 'merge', 'rebase', or 'unshelve'.
3211 Template:
3213 The following keywords are supported in addition to the common template
3215 keywords and functions. See also hg help templates.
3216 path String. Repository-absolute path of the file.
3218 source String. Repository-absolute path of the file originated from.
3220 Available if --copies is specified.
3221 status String. Character denoting file's status.
3223 Examples:
3225 • show changes in the working directory relative to a changeset:
3227 hg status --rev 9353
3229 • show changes in the working directory relative to the current direc‐
3231 tory (see hg help patterns for more information):
3232 hg status re:
3234 • show all changes including copies in an existing changeset:
3236 hg status --copies --change 9353
3238 • get a NUL separated list of added files, suitable for xargs:
3240 hg status -an0
3242 • show more information about the repository status, abbreviating
3244 added, removed, modified, deleted, and untracked paths:
3245 hg status -v -t mardu
3247 Returns 0 on success.
3249 Options:
3251 -A, --all
3253 show status of all files
3254 -m, --modified
3256 show only modified files
3257 -a, --added
3259 show only added files
3260 -r, --removed
3262 show only removed files
3263 -d, --deleted
3265 show only missing files
3266 -c, --clean
3268 show only files without changes
3269 -u, --unknown
3271 show only unknown (not tracked) files
3272 -i, --ignored
3274 show only ignored files
3275 -n, --no-status
3277 hide status prefix
3278 -t,--terse <VALUE>
3280 show the terse output (EXPERIMENTAL) (default: nothing)
3281 -C, --copies
3283 show source of copied files (DEFAULT: ui.statuscopies)
3284 -0, --print0
3286 end filenames with NUL, for use with xargs
3287 --rev <REV[+]>
3289 show difference from revision
3290 --change <REV>
3292 list the changed files of a revision
3293 -I,--include <PATTERN[+]>
3295 include names matching the given patterns
3296 -X,--exclude <PATTERN[+]>
3298 exclude names matching the given patterns
3299 -S, --subrepos
3301 recurse into subrepositories
3302 -T,--template <TEMPLATE>
3304 display with template
3305 [+] marked option can be specified multiple times
3307 aliases: st
3309 summary
3311 summarize working directory state:
3312 hg summary [--remote]
3314 This generates a brief summary of the working directory state, includ‐
3316 ing parents, branch, commit status, phase and available updates.
3317 With the --remote option, this will check the default paths for incom‐
3319 ing and outgoing changes. This can be time-consuming.
3320 Returns 0 on success.
3322 Options:
3324 --remote
3326 check for push and pull
3327 aliases: sum
3329 unshelve
3331 restore a shelved change to the working directory:
3332 hg unshelve [OPTION]... [[-n] SHELVED]
3334 This command accepts an optional name of a shelved change to restore.
3336 If none is given, the most recent shelved change is used.
3337 If a shelved change is applied successfully, the bundle that contains
3339 the shelved changes is moved to a backup location (.hg/shelve-backup).
3340 Since you can restore a shelved change on top of an arbitrary commit,
3342 it is possible that unshelving will result in a conflict between your
3343 changes and the commits you are unshelving onto. If this occurs, you
3344 must resolve the conflict, then use --continue to complete the unshelve
3345 operation. (The bundle will not be moved until you successfully com‐
3346 plete the unshelve.)
3347 (Alternatively, you can use --abort to abandon an unshelve that causes
3349 a conflict. This reverts the unshelved changes, and leaves the bundle
3350 in place.)
3351 If bare shelved change (without interactive, include and exclude op‐
3353 tion) was done on newly created branch it would restore branch informa‐
3354 tion to the working directory.
3355 After a successful unshelve, the shelved changes are stored in a backup
3357 directory. Only the N most recent backups are kept. N defaults to 10
3358 but can be overridden using the shelve.maxbackups configuration option.
3359 Timestamp in seconds is used to decide order of backups. More than
3361 maxbackups backups are kept, if same timestamp prevents from deciding
3362 exact order of them, for safety.
3363 Selected changes can be unshelved with --interactive flag. The working
3365 directory is updated with the selected changes, and only the unselected
3366 changes remain shelved. Note: The whole shelve is applied to working
3367 directory first before running interactively. So, this will bring up
3368 all the conflicts between working directory and the shelve, irrespec‐
3369 tive of which changes will be unshelved.
3370 Options:
3372 -a, --abort
3374 abort an incomplete unshelve operation
3375 -c, --continue
3377 continue an incomplete unshelve operation
3378 -i, --interactive
3380 use interactive mode (EXPERIMENTAL)
3381 -k, --keep
3383 keep shelve after unshelving
3384 -n,--name <NAME>
3386 restore shelved change with given name
3387 -t,--tool <VALUE>
3389 specify merge tool
3390 --date <DATE>
3392 set date for temporary commits (DEPRECATED)
3393 update
3395 update working directory (or switch revisions):
3396 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3398 Update the repository's working directory to the specified changeset.
3400 If no changeset is specified, update to the tip of the current named
3401 branch and move the active bookmark (see hg help bookmarks).
3402 Update sets the working directory's parent revision to the specified
3404 changeset (see hg help parents).
3405 If the changeset is not a descendant or ancestor of the working direc‐
3407 tory's parent and there are uncommitted changes, the update is aborted.
3408 With the -c/--check option, the working directory is checked for uncom‐
3409 mitted changes; if none are found, the working directory is updated to
3410 the specified changeset.
3411 The -C/--clean, -c/--check, and -m/--merge options control what happens
3413 if the working directory contains uncommitted changes. At most of one
3414 of them can be specified.
3415 1. If no option is specified, and if the requested changeset is an an‐
3417 cestor or descendant of the working directory's parent, the uncom‐
3418 mitted changes are merged into the requested changeset and the
3419 merged result is left uncommitted. If the requested changeset is not
3420 an ancestor or descendant (that is, it is on another branch), the
3421 update is aborted and the uncommitted changes are preserved.
3422 2. With the -m/--merge option, the update is allowed even if the re‐
3424 quested changeset is not an ancestor or descendant of the working
3425 directory's parent.
3426 3. With the -c/--check option, the update is aborted and the uncommit‐
3428 ted changes are preserved.
3429 4. With the -C/--clean option, uncommitted changes are discarded and
3431 the working directory is updated to the requested changeset.
3432 To cancel an uncommitted merge (and lose your changes), use hg merge
3434 --abort.
3435 Use null as the changeset to remove the working directory (like hg
3437 clone -U).
3438 If you want to revert just one file to an older revision, use hg revert
3440 [-r REV] NAME.
3441 See hg help dates for a list of formats valid for -d/--date.
3443 Returns 0 on success, 1 if there are unresolved files.
3445 Options:
3447 -C, --clean
3449 discard uncommitted changes (no backup)
3450 -c, --check
3452 require clean working directory
3453 -m, --merge
3455 merge uncommitted changes
3456 -d,--date <DATE>
3458 tipmost revision matching date
3459 -r,--rev <REV>
3461 revision
3462 -t,--tool <TOOL>
3464 specify merge tool
3465 aliases: up checkout co
3467 Change import/export
3469 archive
3470 create an unversioned archive of a repository revision:
3471 hg archive [OPTION]... DEST
3473 By default, the revision used is the parent of the working directory;
3475 use -r/--rev to specify a different revision.
3476 The archive type is automatically detected based on file extension (to
3478 override, use -t/--type).
3479 Examples:
3481 • create a zip file containing the 1.0 release:
3483 hg archive -r 1.0 project-1.0.zip
3485 • create a tarball excluding .hg files:
3487 hg archive project.tar.gz -X ".hg*"
3489 Valid types are:
3491 files
3493 a directory full of files (default)
3495 tar
3497 tar archive, uncompressed
3499 tbz2
3501 tar archive, compressed using bzip2
3503 tgz
3505 tar archive, compressed using gzip
3507 txz
3509 tar archive, compressed using lzma (only in Python 3)
3511 uzip
3513 zip archive, uncompressed
3515 zip
3517 zip archive, compressed using deflate
3519 The exact name of the destination archive or directory is given using a
3521 format string; see hg help export for details.
3522 Each member added to an archive file has a directory prefix prepended.
3524 Use -p/--prefix to specify a format string for the prefix. The default
3525 is the basename of the archive, with suffixes removed.
3526 Returns 0 on success.
3528 Options:
3530 --no-decode
3532 do not pass files through decoders
3533 -p,--prefix <PREFIX>
3535 directory prefix for files in archive
3536 -r,--rev <REV>
3538 revision to distribute
3539 -t,--type <TYPE>
3541 type of distribution to create
3542 -S, --subrepos
3544 recurse into subrepositories
3545 -I,--include <PATTERN[+]>
3547 include names matching the given patterns
3548 -X,--exclude <PATTERN[+]>
3550 exclude names matching the given patterns
3551 [+] marked option can be specified multiple times
3553 bundle
3555 create a bundle file:
3556 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]...
3558 Generate a bundle file containing data to be transferred to another
3560 repository.
3561 To create a bundle containing all changesets, use -a/--all (or --base
3563 null). Otherwise, hg assumes the destination will have all the nodes
3564 you specify with --base parameters. Otherwise, hg will assume the
3565 repository has all the nodes in destination, or default-push/default if
3566 no destination is specified, where destination is the repositories you
3567 provide through DEST option.
3568 You can change bundle format with the -t/--type option. See hg help
3570 bundlespec for documentation on this format. By default, the most ap‐
3571 propriate format is used and compression defaults to bzip2.
3572 The bundle file can then be transferred using conventional means and
3574 applied to another repository with the unbundle or pull command. This
3575 is useful when direct push and pull are not available or when exporting
3576 an entire repository is undesirable.
3577 Applying bundles preserves all changeset contents including permis‐
3579 sions, copy/rename information, and revision history.
3580 Returns 0 on success, 1 if no changes found.
3582 Options:
3584 -f, --force
3586 run even when the destination is unrelated
3587 -r,--rev <REV[+]>
3589 a changeset intended to be added to the destination
3590 -b,--branch <BRANCH[+]>
3592 a specific branch you would like to bundle
3593 --base <REV[+]>
3595 a base changeset assumed to be available at the destination
3596 -a, --all
3598 bundle all changesets in the repository
3599 -t,--type <TYPE>
3601 bundle compression type to use (default: bzip2)
3602 -e,--ssh <CMD>
3604 specify ssh command to use
3605 --remotecmd <CMD>
3607 specify hg command to run on the remote side
3608 --insecure
3610 do not verify server certificate (ignoring web.cacerts config)
3611 [+] marked option can be specified multiple times
3613 export
3615 dump the header and diffs for one or more changesets:
3616 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
3618 Print the changeset header and diffs for one or more revisions. If no
3620 revision is given, the parent of the working directory is used.
3621 The information shown in the changeset header is: author, date, branch
3623 name (if non-default), changeset hash, parent(s) and commit comment.
3624 Note hg export may generate unexpected diff output for merge change‐
3626 sets, as it will compare the merge changeset against its first
3627 parent only.
3628 Output may be to a file, in which case the name of the file is given
3630 using a template string. See hg help templates. In addition to the com‐
3631 mon template keywords, the following formatting rules are supported:
3632 %%
3634 literal "%" character
3636 %H
3638 changeset hash (40 hexadecimal digits)
3640 %N
3642 number of patches being generated
3644 %R
3646 changeset revision number
3648 %b
3650 basename of the exporting repository
3652 %h
3654 short-form changeset hash (12 hexadecimal digits)
3656 %m
3658 first line of the commit message (only alphanumeric characters)
3660 %n
3662 zero-padded sequence number, starting at 1
3664 %r
3666 zero-padded changeset revision number
3668 \
3670 literal "" character
3672 Without the -a/--text option, export will avoid generating diffs of
3674 files it detects as binary. With -a, export will generate a diff any‐
3675 way, probably with undesirable results.
3676 With -B/--bookmark changesets reachable by the given bookmark are se‐
3678 lected.
3679 Use the -g/--git option to generate diffs in the git extended diff for‐
3681 mat. See hg help diffs for more information.
3682 With the --switch-parent option, the diff will be against the second
3684 parent. It can be useful to review a merge.
3685 Template:
3687 The following keywords are supported in addition to the common template
3689 keywords and functions. See also hg help templates.
3690 diff String. Diff content.
3692 parents
3694 List of strings. Parent nodes of the changeset.
3695 Examples:
3697 • use export and import to transplant a bugfix to the current branch:
3699 hg export -r 9353 | hg import -
3701 • export all the changesets between two revisions to a file with rename
3703 information:
3704 hg export --git -r 123:150 > changes.txt
3706 • split outgoing changes into a series of patches with descriptive
3708 names:
3709 hg export -r "outgoing()" -o "%n-%m.patch"
3711 Returns 0 on success.
3713 Options:
3715 -B,--bookmark <BOOKMARK>
3717 export changes only reachable by given bookmark
3718 -o,--output <FORMAT>
3720 print output to file with formatted name
3721 --switch-parent
3723 diff against the second parent
3724 -r,--rev <REV[+]>
3726 revisions to export
3727 -a, --text
3729 treat all files as text
3730 -g, --git
3732 use git extended diff format (DEFAULT: diff.git)
3733 --binary
3735 generate binary diffs in git mode (default)
3736 --nodates
3738 omit dates from diff headers
3739 -T,--template <TEMPLATE>
3741 display with template
3742 [+] marked option can be specified multiple times
3744 import
3746 import an ordered set of patches:
3747 hg import [OPTION]... PATCH...
3749 Import a list of patches and commit them individually (unless --no-com‐
3751 mit is specified).
3752 To read a patch from standard input (stdin), use "-" as the patch name.
3754 If a URL is specified, the patch will be downloaded from there.
3755 Import first applies changes to the working directory (unless --bypass
3757 is specified), import will abort if there are outstanding changes.
3758 Use --bypass to apply and commit patches directly to the repository,
3760 without affecting the working directory. Without --exact, patches will
3761 be applied on top of the working directory parent revision.
3762 You can import a patch straight from a mail message. Even patches as
3764 attachments work (to use the body part, it must have type text/plain or
3765 text/x-patch). From and Subject headers of email message are used as
3766 default committer and commit message. All text/plain body parts before
3767 first diff are added to the commit message.
3768 If the imported patch was generated by hg export, user and description
3770 from patch override values from message headers and body. Values given
3771 on command line with -m/--message and -u/--user override these.
3772 If --exact is specified, import will set the working directory to the
3774 parent of each patch before applying it, and will abort if the result‐
3775 ing changeset has a different ID than the one recorded in the patch.
3776 This will guard against various ways that portable patch formats and
3777 mail systems might fail to transfer Mercurial data or metadata. See hg
3778 bundle for lossless transmission.
3779 Use --partial to ensure a changeset will be created from the patch even
3781 if some hunks fail to apply. Hunks that fail to apply will be written
3782 to a <target-file>.rej file. Conflicts can then be resolved by hand be‐
3783 fore hg commit --amend is run to update the created changeset. This
3784 flag exists to let people import patches that partially apply without
3785 losing the associated metadata (author, date, description, ...).
3786 Note When no hunks apply cleanly, hg import --partial will create an
3788 empty changeset, importing only the patch metadata.
3789 With -s/--similarity, hg will attempt to discover renames and copies in
3791 the patch in the same way as hg addremove.
3792 It is possible to use external patch programs to perform the patch by
3794 setting the ui.patch configuration option. For the default internal
3795 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
3796 fig for more information about configuration files and how to use these
3797 options.
3798 See hg help dates for a list of formats valid for -d/--date.
3800 Examples:
3802 • import a traditional patch from a website and detect renames:
3804 hg import -s 80 http://example.com/bugfix.patch
3806 • import a changeset from an hgweb server:
3808 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
3810 • import all the patches in an Unix-style mbox:
3812 hg import incoming-patches.mbox
3814 • import patches from stdin:
3816 hg import -
3818 • attempt to exactly restore an exported changeset (not always possi‐
3820 ble):
3821 hg import --exact proposed-fix.patch
3823 • use an external tool to apply a patch which is too fuzzy for the de‐
3825 fault internal tool.
3826 hg import --config ui.patch="patch --merge" fuzzy.patch
3828 • change the default fuzzing from 2 to a less strict 7
3830 hg import --config ui.fuzz=7 fuzz.patch
3832 Returns 0 on success, 1 on partial success (see --partial).
3834 Options:
3836 -p,--strip <NUM>
3838 directory strip option for patch. This has the same meaning as
3839 the corresponding patch option (default: 1)
3840 -b,--base <PATH>
3842 base path (DEPRECATED)
3843 --secret
3845 use the secret phase for committing
3846 -e, --edit
3848 invoke editor on commit messages
3849 -f, --force
3851 skip check for outstanding uncommitted changes (DEPRECATED)
3852 --no-commit
3854 don't commit, just update the working directory
3855 --bypass
3857 apply patch without touching the working directory
3858 --partial
3860 commit even if some hunks fail
3861 --exact
3863 abort if patch would apply lossily
3864 --prefix <DIR>
3866 apply patch to subdirectory
3867 --import-branch
3869 use any branch information in patch (implied by --exact)
3870 -m,--message <TEXT>
3872 use text as commit message
3873 -l,--logfile <FILE>
3875 read commit message from file
3876 -d,--date <DATE>
3878 record the specified date as commit date
3879 -u,--user <USER>
3881 record the specified user as committer
3882 -s,--similarity <SIMILARITY>
3884 guess renamed files by similarity (0<=s<=100)
3885 aliases: patch
3887 unbundle
3889 apply one or more bundle files:
3890 hg unbundle [-u] FILE...
3892 Apply one or more bundle files generated by hg bundle.
3894 Returns 0 on success, 1 if an update has unresolved files.
3896 Options:
3898 -u, --update
3900 update to new branch head if changesets were unbundled
3901 Repository maintenance
3903 manifest
3904 output the current or given revision of the project manifest:
3905 hg manifest [-r REV]
3907 Print a list of version controlled files for the given revision. If no
3909 revision is given, the first parent of the working directory is used,
3910 or the null revision if no revision is checked out.
3911 With -v, print file permissions, symlink and executable bits. With
3913 --debug, print file revision hashes.
3914 If option --all is specified, the list of all files from all revisions
3916 is printed. This includes deleted and renamed files.
3917 Returns 0 on success.
3919 Options:
3921 -r,--rev <REV>
3923 revision to display
3924 --all list files from all revisions
3926 -T,--template <TEMPLATE>
3928 display with template
3929 recover
3931 roll back an interrupted transaction:
3932 hg recover
3934 Recover from an interrupted commit or pull.
3936 This command tries to fix the repository status after an interrupted
3938 operation. It should only be necessary when Mercurial suggests it.
3939 Returns 0 if successful, 1 if nothing to recover or verify fails.
3941 Options:
3943 --verify
3945 run hg verify after successful recover
3946 rollback
3948 roll back the last transaction (DANGEROUS) (DEPRECATED):
3949 hg rollback
3951 Please use hg commit --amend instead of rollback to correct mistakes in
3953 the last commit.
3954 This command should be used with care. There is only one level of roll‐
3956 back, and there is no way to undo a rollback. It will also restore the
3957 dirstate at the time of the last transaction, losing any dirstate
3958 changes since that time. This command does not alter the working direc‐
3959 tory.
3960 Transactions are used to encapsulate the effects of all commands that
3962 create new changesets or propagate existing changesets into a reposi‐
3963 tory.
3964 For example, the following commands are transactional, and their ef‐
3966 fects can be rolled back:
3967 • commit
3969 • import
3971 • pull
3973 • push (with this repository as the destination)
3975 • unbundle
3977 To avoid permanent data loss, rollback will refuse to rollback a commit
3979 transaction if it isn't checked out. Use --force to override this pro‐
3980 tection.
3981 The rollback command can be entirely disabled by setting the ui.roll‐
3983 back configuration setting to false. If you're here because you want to
3984 use rollback and it's disabled, you can re-enable the command by set‐
3985 ting ui.rollback to true.
3986 This command is not intended for use on public repositories. Once
3988 changes are visible for pull by other users, rolling a transaction back
3989 locally is ineffective (someone else may already have pulled the
3990 changes). Furthermore, a race is possible with readers of the reposi‐
3991 tory; for example an in-progress pull from the repository may fail if a
3992 rollback is performed.
3993 Returns 0 on success, 1 if no rollback data is available.
3995 Options:
3997 -n, --dry-run
3999 do not perform actions, just print output
4000 -f, --force
4002 ignore safety measures
4003 verify
4005 verify the integrity of the repository:
4006 hg verify
4008 Verify the integrity of the current repository.
4010 This will perform an extensive check of the repository's integrity,
4012 validating the hashes and checksums of each entry in the changelog,
4013 manifest, and tracked files, as well as the integrity of their
4014 crosslinks and indices.
4015 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
4017 information about recovery from corruption of the repository.
4018 Returns 0 on success, 1 if errors are encountered.
4020 Options:
4022 --full perform more checks (EXPERIMENTAL)
4024 Help
4026 config
4027 show combined config settings from all hgrc files:
4028 hg config [-u] [NAME]...
4030 With no arguments, print names and values of all config items.
4032 With one argument of the form section.name, print just the value of
4034 that config item.
4035 With multiple arguments, print names and values of all config items
4037 with matching section names or section.names.
4038 With --edit, start an editor on the user-level config file. With
4040 --global, edit the system-wide config file. With --local, edit the
4041 repository-level config file.
4042 With --source, the source (filename and line number) is printed for
4044 each config item.
4045 See hg help config for more information about config files.
4047 --non-shared flag is used to edit .hg/hgrc-not-shared config file.
4049 This file is not shared across shares when in share-safe mode.
4050 Template:
4052 The following keywords are supported. See also hg help templates.
4054 name String. Config name.
4056 source String. Filename and line number where the item is defined.
4058 value String. Config value.
4060 The --shared flag can be used to edit the config file of shared source
4062 repository. It only works when you have shared using the experimental
4063 share safe feature.
4064 Returns 0 on success, 1 if NAME does not exist.
4066 Options:
4068 -u, --untrusted
4070 show untrusted configuration options
4071 --exp-all-known
4073 show all known config option (EXPERIMENTAL)
4074 -e, --edit
4076 edit user config
4077 -l, --local
4079 edit repository config
4080 --source
4082 show source of configuration value
4083 --shared
4085 edit shared source repository config (EXPERIMENTAL)
4086 --non-shared
4088 edit non shared config (EXPERIMENTAL)
4089 -g, --global
4091 edit global config
4092 -T,--template <TEMPLATE>
4094 display with template
4095 aliases: showconfig debugconfig
4097 help
4099 show help for a given topic or a help overview:
4100 hg help [-eck] [-s PLATFORM] [TOPIC]
4102 With no arguments, print a list of commands with short help messages.
4104 Given a topic, extension, or command name, print help for that topic.
4106 Returns 0 if successful.
4108 Options:
4110 -e, --extension
4112 show only help for extensions
4113 -c, --command
4115 show only help for commands
4116 -k, --keyword
4118 show topics matching keyword
4119 -s,--system <PLATFORM[+]>
4121 show help for specific platform(s)
4122 [+] marked option can be specified multiple times
4124 version
4126 output version and copyright information:
4127 hg version
4129 Template:
4131 The following keywords are supported. See also hg help templates.
4133 extensions
4135 List of extensions.
4136 ver String. Version number.
4138 And each entry of {extensions} provides the following sub-keywords in
4140 addition to {ver}.
4141 bundled
4143 Boolean. True if included in the release.
4144 name String. Extension name.
4146 Options:
4148 -T,--template <TEMPLATE>
4150 display with template
4151 Uncategorized commands
4154 Mercurial supports generating standalone "bundle" files that hold
4155 repository data. These "bundles" are typically saved locally and used
4156 later or exchanged between different repositories, possibly on differ‐
4157 ent machines. Example commands using bundles are hg bundle and hg un‐
4158 bundle.
4159 Generation of bundle files is controlled by a "bundle specification"
4161 ("bundlespec") string. This string tells the bundle generation process
4162 how to create the bundle.
4163 A "bundlespec" string is composed of the following elements:
4165 type A string denoting the bundle format to use.
4167 compression
4169 Denotes the compression engine to use compressing the raw bundle
4170 data.
4171 parameters
4173 Arbitrary key-value parameters to further control bundle genera‐
4174 tion.
4175 A "bundlespec" string has the following formats:
4177 <type> The literal bundle format string is used.
4179 <compression>-<type>
4181 The compression engine and format are delimited by a hyphen (-).
4182 Optional parameters follow the <type>. Parameters are URI escaped
4184 key=value pairs. Each pair is delimited by a semicolon (;). The first
4185 parameter begins after a ; immediately following the <type> value.
4186 Available Types
4188 The following bundle <type> strings are available:
4189 v1 Produces a legacy "changegroup" version 1 bundle.
4191 This format is compatible with nearly all Mercurial clients be‐
4193 cause it is the oldest. However, it has some limitations, which
4194 is why it is no longer the default for new repositories.
4195 v1 bundles can be used with modern repositories using the "gen‐
4197 eraldelta" storage format. However, it may take longer to pro‐
4198 duce the bundle and the resulting bundle may be significantly
4199 larger than a v2 bundle.
4200 v1 bundles can only use the gzip, bzip2, and none compression
4202 formats.
4203 v2 Produces a version 2 bundle.
4205 Version 2 bundles are an extensible format that can store addi‐
4207 tional repository data (such as bookmarks and phases informa‐
4208 tion) and they can store data more efficiently, resulting in
4209 smaller bundles.
4210 Version 2 bundles can also use modern compression engines, such
4212 as zstd, making them faster to compress and often smaller.
4213 Available Compression Engines
4215 The following bundle <compression> engines can be used:
4216 bzip2
4218 An algorithm that produces smaller bundles than gzip.
4220 All Mercurial clients should support this format.
4222 This engine will likely produce smaller bundles than gzip but
4224 will be significantly slower, both during compression and decom‐
4225 pression.
4226 If available, the zstd engine can yield similar or better com‐
4228 pression at much higher speeds.
4229 gzip
4231 zlib compression using the DEFLATE algorithm.
4233 All Mercurial clients should support this format. The compres‐
4235 sion algorithm strikes a reasonable balance between compression
4236 ratio and size.
4237 none
4239 No compression is performed.
4241 Use this compression engine to explicitly disable compression.
4243 Examples
4245 v2
4246 Produce a v2 bundle using default options, including compres‐
4248 sion.
4249 none-v1
4251 Produce a v1 bundle with no compression.
4253 zstd-v2
4255 Produce a v2 bundle with zstandard compression using default
4257 settings.
4258 zstd-v1
4260 This errors because zstd is not supported for v1 types.
4262
4264 Mercurial colorizes output from several commands.
4265 For example, the diff command shows additions in green and deletions in
4267 red, while the status command shows modified files in magenta. Many
4268 other commands have analogous colors. It is possible to customize these
4269 colors.
4270 To enable color (default) whenever possible use:
4272 [ui]
4274 color = yes
4275 To disable color use:
4277 [ui]
4279 color = no
4280 See hg help config.ui.color for details.
4282 The default pager on Windows does not support color, so enabling the
4284 pager will effectively disable color. See hg help config.ui.paginate
4285 to disable the pager. Alternately, MSYS and Cygwin shells provide less
4286 as a pager, which can be configured to support ANSI color mode. Win‐
4287 dows 10 natively supports ANSI color mode.
4288 Mode
4290 Mercurial can use various systems to display color. The supported modes
4291 are ansi, win32, and terminfo. See hg help config.color for details
4292 about how to control the mode.
4293 Effects
4295 Other effects in addition to color, like bold and underlined text, are
4296 also available. By default, the terminfo database is used to find the
4297 terminal codes used to change color and effect. If terminfo is not
4298 available, then effects are rendered with the ECMA-48 SGR control func‐
4299 tion (aka ANSI escape codes).
4300 The available effects in terminfo mode are 'blink', 'bold', 'dim', 'in‐
4302 verse', 'invisible', 'italic', 'standout', and 'underline'; in ECMA-48
4303 mode, the options are 'bold', 'inverse', 'italic', and 'underline'.
4304 How each is rendered depends on the terminal emulator. Some may not be
4305 available for a given terminal type, and will be silently ignored.
4306 If the terminfo entry for your terminal is missing codes for an effect
4308 or has the wrong codes, you can add or override those codes in your
4309 configuration:
4310 [color]
4312 terminfo.dim = \E[2m
4313 where 'E' is substituted with an escape character.
4315 Labels
4317 Text receives color effects depending on the labels that it has. Many
4318 default Mercurial commands emit labelled text. You can also define your
4319 own labels in templates using the label function, see hg help templates
4320 . A single portion of text may have more than one label. In that case,
4321 effects given to the last label will override any other effects. This
4322 includes the special "none" effect, which nullifies other effects.
4323 Labels are normally invisible. In order to see these labels and their
4325 position in the text, use the global --color=debug option. The same an‐
4326 chor text may be associated to multiple labels, e.g.
4327 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
4329 The following are the default effects for some default labels. Default
4331 effects may be overridden from your configuration file:
4332 [color]
4334 status.modified = blue bold underline red_background
4335 status.added = green bold
4336 status.removed = red bold blue_background
4337 status.deleted = cyan bold underline
4338 status.unknown = magenta bold underline
4339 status.ignored = black bold
4340 # 'none' turns off all effects
4342 status.clean = none
4343 status.copied = none
4344 qseries.applied = blue bold underline
4346 qseries.unapplied = black bold
4347 qseries.missing = red bold
4348 diff.diffline = bold
4350 diff.extended = cyan bold
4351 diff.file_a = red bold
4352 diff.file_b = green bold
4353 diff.hunk = magenta
4354 diff.deleted = red
4355 diff.inserted = green
4356 diff.changed = white
4357 diff.tab =
4358 diff.trailingwhitespace = bold red_background
4359 # Blank so it inherits the style of the surrounding label
4361 changeset.public =
4362 changeset.draft =
4363 changeset.secret =
4364 resolve.unresolved = red bold
4366 resolve.resolved = green bold
4367 bookmarks.active = green
4369 branches.active = none
4371 branches.closed = black bold
4372 branches.current = green
4373 branches.inactive = none
4374 tags.normal = green
4376 tags.local = black bold
4377 rebase.rebased = blue
4379 rebase.remaining = red bold
4380 shelve.age = cyan
4382 shelve.newest = green bold
4383 shelve.name = blue bold
4384 histedit.remaining = red bold
4386 Custom colors
4388 Because there are only eight standard colors, Mercurial allows you to
4389 define color names for other color slots which might be available for
4390 your terminal type, assuming terminfo mode. For instance:
4391 color.brightblue = 12
4393 color.pink = 207
4394 color.orange = 202
4395 to set 'brightblue' to color slot 12 (useful for 16 color terminals
4397 that have brighter colors defined in the upper eight) and, 'pink' and
4398 'orange' to colors in 256-color xterm's default color cube. These de‐
4399 fined colors may then be used as any of the pre-defined eight, includ‐
4400 ing appending '_background' to set the background to that color.
4401
4403 Some commands allow the user to specify a date, e.g.:
4404 • backout, commit, import, tag: Specify the commit date.
4406 • log, revert, update: Select revision(s) by date.
4408 Many date formats are valid. Here are some examples:
4410 • Wed Dec 6 13:18:29 2006 (local timezone assumed)
4412 • Dec 6 13:18 -0600 (year assumed, time offset provided)
4414 • Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
4416 • Dec 6 (midnight)
4418 • 13:18 (today assumed)
4420 • 3:39 (3:39AM assumed)
4422 • 3:39pm (15:39)
4424 • 2006-12-06 13:18:29 (ISO 8601 format)
4426 • 2006-12-6 13:18
4428 • 2006-12-6
4430 • 12-6
4432 • 12/6
4434 • 12/6/6 (Dec 6 2006)
4436 • today (midnight)
4438 • yesterday (midnight)
4440 • now - right now
4442 Lastly, there is Mercurial's internal format:
4444 • 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
4446 This is the internal representation format for dates. The first number
4448 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
4449 second is the offset of the local timezone, in seconds west of UTC
4450 (negative if the timezone is east of UTC).
4451 The log command also accepts date ranges:
4453 • <DATE - at or before a given date/time
4455 • >DATE - on or after a given date/time
4457 • DATE to DATE - a date range, inclusive
4459 • -DAYS - within a given number of days from today
4461
4463 Mercurial evolves over time, some features, options, commands may be
4464 replaced by better and more secure alternatives. This topic will help
4465 you migrating your existing usage and/or configuration to newer fea‐
4466 tures.
4467 Commands
4469 The following commands are still available but their use are not recom‐
4470 mended:
4471 locate
4473 This command has been replaced by hg files.
4475 parents
4477 This command can be replaced by hg summary or hg log with appropriate
4479 revsets. See hg help revsets for more information.
4480 tip
4482 The recommended alternative is hg heads.
4484 Options
4486 web.allowpull
4487 Renamed to allow-pull.
4489 web.allow_push
4491 Renamed to allow-push.
4493
4495 Mercurial's default format for showing changes between two versions of
4496 a file is compatible with the unified format of GNU diff, which can be
4497 used by GNU patch and many other standard tools.
4498 While this standard format is often enough, it does not encode the fol‐
4500 lowing information:
4501 • executable status and other permission bits
4503 • copy or rename information
4505 • changes in binary files
4507 • creation or deletion of empty files
4509 Mercurial also supports the extended diff format from the git VCS which
4511 addresses these limitations. The git diff format is not produced by de‐
4512 fault because a few widespread tools still do not understand this for‐
4513 mat.
4514 This means that when generating diffs from a Mercurial repository (e.g.
4516 with hg export), you should be careful about things like file copies
4517 and renames or other things mentioned above, because when applying a
4518 standard diff to a different repository, this extra information is
4519 lost. Mercurial's internal operations (like push and pull) are not af‐
4520 fected by this, because they use an internal binary format for communi‐
4521 cating changes.
4522 To make Mercurial produce the git extended diff format, use the --git
4524 option available for many commands, or set 'git = True' in the [diff]
4525 section of your configuration file. You do not need to set this option
4526 when importing diffs in this format or using them in the mq extension.
4527
4529 HG Path to the 'hg' executable, automatically passed when running
4530 hooks, extensions or external tools. If unset or empty, this is
4531 the hg executable's name if it's frozen, or an executable named
4532 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
4533 on Windows) is searched.
4534 HGEDITOR
4536 This is the name of the editor to run when committing. See EDI‐
4537 TOR.
4538 (deprecated, see hg help config.ui.editor)
4540 HGENCODING
4542 This overrides the default locale setting detected by Mercurial.
4543 This setting is used to convert data including usernames,
4544 changeset descriptions, tag names, and branches. This setting
4545 can be overridden with the --encoding command-line option.
4546 HGENCODINGMODE
4548 This sets Mercurial's behavior for handling unknown characters
4549 while transcoding user input. The default is "strict", which
4550 causes Mercurial to abort if it can't map a character. Other
4551 settings include "replace", which replaces unknown characters,
4552 and "ignore", which drops them. This setting can be overridden
4553 with the --encodingmode command-line option.
4554 HGENCODINGAMBIGUOUS
4556 This sets Mercurial's behavior for handling characters with "am‐
4557 biguous" widths like accented Latin characters with East Asian
4558 fonts. By default, Mercurial assumes ambiguous characters are
4559 narrow, set this variable to "wide" if such characters cause
4560 formatting problems.
4561 HGMERGE
4563 An executable to use for resolving merge conflicts. The program
4564 will be executed with three arguments: local file, remote file,
4565 ancestor file.
4566 (deprecated, see hg help config.ui.merge)
4568 HGRCPATH
4570 A list of files or directories to search for configuration
4571 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
4572 PATH is not set, platform default search path is used. If empty,
4573 only the .hg/hgrc from the current repository is read.
4574 For each element in HGRCPATH:
4576 • if it's a directory, all files ending with .rc are added
4578 • otherwise, the file itself will be added
4580 HGRCSKIPREPO
4582 When set, the .hg/hgrc from repositories are not read.
4583 HGPLAIN
4585 When set, this disables any configuration settings that might
4586 change Mercurial's default output. This includes encoding, de‐
4587 faults, verbose mode, debug mode, quiet mode, tracebacks, and
4588 localization. This can be useful when scripting against Mercu‐
4589 rial in the face of existing user configuration.
4590 In addition to the features disabled by HGPLAIN=, the following
4592 values can be specified to adjust behavior:
4593 +strictflags
4595 Restrict parsing of command line flags.
4597 Equivalent options set via command line flags or environment
4599 variables are not overridden.
4600 See hg help scripting for details.
4602 HGPLAINEXCEPT
4604 This is a comma-separated list of features to preserve when HG‐
4605 PLAIN is enabled. Currently the following values are supported:
4606 alias
4608 Don't remove aliases.
4610 color
4612 Don't disable colored output.
4614 i18n
4616 Preserve internationalization.
4618 revsetalias
4620 Don't remove revset aliases.
4622 templatealias
4624 Don't remove template aliases.
4626 progress
4628 Don't hide progress output.
4630 Setting HGPLAINEXCEPT to anything (even an empty string) will
4632 enable plain mode.
4633 HGUSER This is the string used as the author of a commit. If not set,
4635 available values will be considered in this order:
4636 • HGUSER (deprecated)
4638 • configuration files from the HGRCPATH
4640 • EMAIL
4642 • interactive prompt
4644 • LOGNAME (with @hostname appended)
4646 (deprecated, see hg help config.ui.username)
4648 EMAIL May be used as the author of a commit; see HGUSER.
4650 LOGNAME
4652 May be used as the author of a commit; see HGUSER.
4653 VISUAL This is the name of the editor to use when committing. See EDI‐
4655 TOR.
4656 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
4658 user to modify, for example when writing commit messages. The
4659 editor it uses is determined by looking at the environment vari‐
4660 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
4661 non-empty one is chosen. If all of them are empty, the editor
4662 defaults to 'vi'.
4663 PYTHONPATH
4665 This is used by Python to find imported modules and may need to
4666 be set appropriately if this Mercurial is not installed sys‐
4667 tem-wide.
4668
4670 Obsolescence markers make it possible to mark changesets that have been
4671 deleted or superseded in a new version of the changeset.
4672 Unlike the previous way of handling such changes, by stripping the old
4674 changesets from the repository, obsolescence markers can be propagated
4675 between repositories. This allows for a safe and simple way of exchang‐
4676 ing mutable history and altering it after the fact. Changeset phases
4677 are respected, such that only draft and secret changesets can be al‐
4678 tered (see hg help phases for details).
4679 Obsolescence is tracked using "obsolescence markers", a piece of meta‐
4681 data tracking which changesets have been made obsolete, potential suc‐
4682 cessors for a given changeset, the moment the changeset was marked as
4683 obsolete, and the user who performed the rewriting operation. The mark‐
4684 ers are stored separately from standard changeset data can be exchanged
4685 without any of the precursor changesets, preventing unnecessary ex‐
4686 change of obsolescence data.
4687 The complete set of obsolescence markers describes a history of change‐
4689 set modifications that is orthogonal to the repository history of file
4690 modifications. This changeset history allows for detection and auto‐
4691 matic resolution of edge cases arising from multiple users rewriting
4692 the same part of history concurrently.
4693 Current feature status
4695 This feature is still in development.
4696 Instability
4698 Rewriting changesets might introduce instability.
4699 There are two main kinds of instability: orphaning and diverging.
4701 Orphans are changesets left behind when their ancestors are rewritten.
4703 Divergence has two variants:
4704 • Content-divergence occurs when independent rewrites of the same
4706 changesets lead to different results.
4707 • Phase-divergence occurs when the old (obsolete) version of a change‐
4709 set becomes public.
4710 It is possible to prevent local creation of orphans by using the fol‐
4712 lowing config:
4713 [experimental]
4715 evolution.createmarkers = true
4716 evolution.exchange = true
4717 You can also enable that option explicitly:
4719 [experimental]
4721 evolution.createmarkers = true
4722 evolution.exchange = true
4723 evolution.allowunstable = true
4724
4726 Mercurial has the ability to add new features through the use of exten‐
4727 sions. Extensions may add new commands, add options to existing com‐
4728 mands, change the default behavior of commands, or implement hooks.
4729 To enable the "foo" extension, either shipped with Mercurial or in the
4731 Python search path, create an entry for it in your configuration file,
4732 like this:
4733 [extensions]
4735 foo =
4736 You may also specify the full path to an extension:
4738 [extensions]
4740 myfeature = ~/.hgext/myfeature.py
4741 See hg help config for more information on configuration files.
4743 Extensions are not loaded by default for a variety of reasons: they can
4745 increase startup overhead; they may be meant for advanced usage only;
4746 they may provide potentially dangerous abilities (such as letting you
4747 destroy or modify history); they might not be ready for prime time; or
4748 they may alter some usual behaviors of stock Mercurial. It is thus up
4749 to the user to activate extensions as needed.
4750 To explicitly disable an extension enabled in a configuration file of
4752 broader scope, prepend its path with !:
4753 [extensions]
4755 # disabling extension bar residing in /path/to/extension/bar.py
4756 bar = !/path/to/extension/bar.py
4757 # ditto, but no path was supplied for extension baz
4758 baz = !
4759 disabled extensions:
4761 acl hooks for controlling repository access
4763 blackbox
4765 log repository events to a blackbox for debugging
4766 bugzilla
4768 hooks for integrating with the Bugzilla bug tracker
4769 censor erase file content at a given revision
4771 churn command to display statistics about repository history
4773 clonebundles
4775 advertise pre-generated bundles to seed clones
4776 closehead
4778 close arbitrary heads without checking them out first
4779 convert
4781 import revisions from foreign VCS repositories into Mercurial
4782 eol automatically manage newlines in repository files
4784 extdiff
4786 command to allow external programs to compare revisions
4787 factotum
4789 http authentication with factotum
4790 fastexport
4792 export repositories as git fast-import stream
4793 githelp
4795 try mapping git commands to Mercurial commands
4796 gpg commands to sign and verify changesets
4798 hgk browse the repository in a graphical way
4800 highlight
4802 syntax highlighting for hgweb (requires Pygments)
4803 histedit
4805 interactive history editing
4806 keyword
4808 expand keywords in tracked files
4809 largefiles
4811 track large binary files
4812 mq manage a stack of patches
4814 notify hooks for sending email push notifications
4816 patchbomb
4818 command to send changesets as (a series of) patch emails
4819 rebase command to move sets of revisions to a different ancestor
4821 relink recreates hardlinks between repository clones
4823 schemes
4825 extend schemes with shortcuts to repository swarms
4826 share share a common history between several working directories
4828 transplant
4830 command to transplant changesets from another branch
4831 win32mbcs
4833 allow the use of MBCS paths with problematic encodings
4834 zeroconf
4836 discover and advertise repositories on the local network
4837
4839 Mercurial supports a functional language for selecting a set of files.
4840 Like other file patterns, this pattern type is indicated by a prefix,
4842 'set:'. The language supports a number of predicates which are joined
4843 by infix operators. Parenthesis can be used for grouping.
4844 Identifiers such as filenames or patterns must be quoted with single or
4846 double quotes if they contain characters outside of
4847 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4848 predicates. This generally applies to file patterns other than globs
4849 and arguments for predicates. Pattern prefixes such as path: may be
4850 specified without quoting.
4851 Special characters can be used in quoted identifiers by escaping them,
4853 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4854 preted, strings can be prefixed with r, e.g. r'...'.
4855 See also hg help patterns.
4857 Operators
4859 There is a single prefix operator:
4860 not x
4862 Files not in x. Short form is ! x.
4864 These are the supported infix operators:
4866 x and y
4868 The intersection of files in x and y. Short form is x & y.
4870 x or y
4872 The union of files in x and y. There are two alternative short
4874 forms: x | y and x + y.
4875 x - y
4877 Files in x but not in y.
4879 Predicates
4881 The following predicates are supported:
4882 added()
4884 File that is added according to hg status.
4886 binary()
4888 File that appears to be binary (contains NUL bytes).
4890 clean()
4892 File that is clean according to hg status.
4894 copied()
4896 File that is recorded as being copied.
4898 deleted()
4900 Alias for missing().
4902 encoding(name)
4904 File can be successfully decoded with the given character encod‐
4906 ing. May not be useful for encodings other than ASCII and UTF-8.
4907 eol(style)
4909 File contains newlines of the given style (dos, unix, mac). Bi‐
4911 nary files are excluded, files with mixed line endings match
4912 multiple styles.
4913 exec()
4915 File that is marked as executable.
4917 grep(regex)
4919 File contains the given regular expression.
4921 hgignore()
4923 File that matches the active .hgignore pattern.
4925 ignored()
4927 File that is ignored according to hg status.
4929 missing()
4931 File that is missing according to hg status.
4933 modified()
4935 File that is modified according to hg status.
4937 portable()
4939 File that has a portable name. (This doesn't include filenames
4941 with case collisions.)
4942 removed()
4944 File that is removed according to hg status.
4946 resolved()
4948 File that is marked resolved according to hg resolve -l.
4950 revs(revs, pattern)
4952 Evaluate set in the specified revisions. If the revset match
4954 multiple revs, this will return file matching pattern in any of
4955 the revision.
4956 size(expression)
4958 File size matches the given expression. Examples:
4960 • size('1k') - files from 1024 to 2047 bytes
4962 • size('< 20k') - files less than 20480 bytes
4964 • size('>= .5MB') - files at least 524288 bytes
4966 • size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
4968 status(base, rev, pattern)
4970 Evaluate predicate using status change between base and rev. Ex‐
4972 amples:
4973 • status(3, 7, added()) - matches files added from "3" to "7"
4975 subrepo([pattern])
4977 Subrepositories whose paths match the given pattern.
4979 symlink()
4981 File that is marked as a symlink.
4983 tracked()
4985 File that is under Mercurial control.
4987 unknown()
4989 File that is unknown according to hg status.
4991 unresolved()
4993 File that is marked unresolved according to hg resolve -l.
4995 Examples
4997 Some sample queries:
4998 • Show status of files that appear to be binary in the working direc‐
5000 tory:
5001 hg status -A "set:binary()"
5003 • Forget files that are in .hgignore but are already tracked:
5005 hg forget "set:hgignore() and not ignored()"
5007 • Find text files that contain a string:
5009 hg files "set:grep(magic) and not binary()"
5011 • Find C files in a non-standard encoding:
5013 hg files "set:**.c and not encoding('UTF-8')"
5015 • Revert copies of large binary files:
5017 hg revert "set:copied() and binary() and size('>1M')"
5019 • Revert files that were added to the working directory:
5021 hg revert "set:revs('wdir()', added())"
5023 • Remove files listed in foo.lst that contain the letter a or b:
5025 hg remove "set: listfile:foo.lst and (**a* or **b*)"
5027
5029 Most Mercurial commands accept various flags.
5030 Flag names
5032 Flags for each command are listed in hg help for that command. Addi‐
5033 tionally, some flags, such as --repository, are global and can be used
5034 with any command - those are seen in hg help -v, and can be specified
5035 before or after the command.
5036 Every flag has at least a long name, such as --repository. Some flags
5038 may also have a short one-letter name, such as the equivalent -R. Using
5039 the short or long name is equivalent and has the same effect. The long
5040 name may be abbreviated to any unambiguous prefix. For example, hg com‐
5041 mit --amend can be abbreviated to hg commit --am.
5042 Flags that have a short name can also be bundled together - for in‐
5044 stance, to specify both --edit (short -e) and --interactive (short -i),
5045 one could use:
5046 hg commit -ei
5048 If any of the bundled flags takes a value (i.e. is not a boolean), it
5050 must be last, followed by the value:
5051 hg commit -im 'Message'
5053 Flag types
5055 Mercurial command-line flags can be strings, numbers, booleans, or
5056 lists of strings.
5057 Specifying flag values
5059 The following syntaxes are allowed, assuming a flag 'flagname' with
5060 short name 'f':
5061 --flagname=foo
5063 --flagname foo
5064 -f foo
5065 -ffoo
5066 This syntax applies to all non-boolean flags (strings, numbers or
5068 lists).
5069 Specifying boolean flags
5071 Boolean flags do not take a value parameter. To specify a boolean, use
5072 the flag name to set it to true, or the same name prefixed with 'no-'
5073 to set it to false:
5074 hg commit --interactive
5076 hg commit --no-interactive
5077 Specifying list flags
5079 List flags take multiple values. To specify them, pass the flag multi‐
5080 ple times:
5081 hg files --include mercurial --include tests
5083 Setting flag defaults
5085 In order to set a default value for a flag in an hgrc file, it is rec‐
5086 ommended to use aliases:
5087 [alias]
5089 commit = commit --interactive
5090 For more information on hgrc files, see hg help config.
5092 Overriding flags on the command line
5094 If the same non-list flag is specified multiple times on the command
5095 line, the latest specification is used:
5096 hg commit -m "Ignored value" -m "Used value"
5098 This includes the use of aliases - e.g., if one has:
5100 [alias]
5102 committemp = commit -m "Ignored value"
5103 then the following command will override that -m:
5105 hg committemp -m "Used value"
5107 Overriding flag defaults
5109 Every flag has a default value, and you may also set your own defaults
5110 in hgrc as described above. Except for list flags, defaults can be
5111 overridden on the command line simply by specifying the flag in that
5112 location.
5113 Hidden flags
5115 Some flags are not shown in a command's help by default - specifically,
5116 those that are deemed to be experimental, deprecated or advanced. To
5117 show all flags, add the --verbose flag for the help command:
5118 hg help --verbose commit
5120
5122 Ancestor
5123 Any changeset that can be reached by an unbroken chain of parent
5124 changesets from a given changeset. More precisely, the ancestors
5125 of a changeset can be defined by two properties: a parent of a
5126 changeset is an ancestor, and a parent of an ancestor is an an‐
5127 cestor. See also: 'Descendant'.
5128 Bookmark
5130 Bookmarks are pointers to certain commits that move when commit‐
5131 ting. They are similar to tags in that it is possible to use
5132 bookmark names in all places where Mercurial expects a changeset
5133 ID, e.g., with hg update. Unlike tags, bookmarks move along when
5134 you make a commit.
5135 Bookmarks can be renamed, copied and deleted. Bookmarks are lo‐
5137 cal, unless they are explicitly pushed or pulled between reposi‐
5138 tories. Pushing and pulling bookmarks allow you to collaborate
5139 with others on a branch without creating a named branch.
5140 Branch (Noun) A child changeset that has been created from a parent
5142 that is not a head. These are known as topological branches, see
5143 'Branch, topological'. If a topological branch is named, it be‐
5144 comes a named branch. If a topological branch is not named, it
5145 becomes an anonymous branch. See 'Branch, anonymous' and
5146 'Branch, named'.
5147 Branches may be created when changes are pulled from or pushed
5149 to a remote repository, since new heads may be created by these
5150 operations. Note that the term branch can also be used infor‐
5151 mally to describe a development process in which certain devel‐
5152 opment is done independently of other development. This is some‐
5153 times done explicitly with a named branch, but it can also be
5154 done locally, using bookmarks or clones and anonymous branches.
5155 Example: "The experimental branch."
5157 (Verb) The action of creating a child changeset which results in
5159 its parent having more than one child.
5160 Example: "I'm going to branch at X."
5162 Branch, anonymous
5164 Every time a new child changeset is created from a parent that
5165 is not a head and the name of the branch is not changed, a new
5166 anonymous branch is created.
5167 Branch, closed
5169 A named branch whose branch heads have all been closed.
5170 Branch, default
5172 The branch assigned to a changeset when no name has previously
5173 been assigned.
5174 Branch head
5176 See 'Head, branch'.
5177 Branch, inactive
5179 If a named branch has no topological heads, it is considered to
5180 be inactive. As an example, a feature branch becomes inactive
5181 when it is merged into the default branch. The hg branches com‐
5182 mand shows inactive branches by default, though they can be hid‐
5183 den with hg branches --active.
5184 NOTE: this concept is deprecated because it is too implicit.
5186 Branches should now be explicitly closed using hg commit
5187 --close-branch when they are no longer needed.
5188 Branch, named
5190 A collection of changesets which have the same branch name. By
5191 default, children of a changeset in a named branch belong to the
5192 same named branch. A child can be explicitly assigned to a dif‐
5193 ferent branch. See hg help branch, hg help branches and hg com‐
5194 mit --close-branch for more information on managing branches.
5195 Named branches can be thought of as a kind of namespace, divid‐
5197 ing the collection of changesets that comprise the repository
5198 into a collection of disjoint subsets. A named branch is not
5199 necessarily a topological branch. If a new named branch is cre‐
5200 ated from the head of another named branch, or the default
5201 branch, but no further changesets are added to that previous
5202 branch, then that previous branch will be a branch in name only.
5203 Branch tip
5205 See 'Tip, branch'.
5206 Branch, topological
5208 Every time a new child changeset is created from a parent that
5209 is not a head, a new topological branch is created. If a topo‐
5210 logical branch is named, it becomes a named branch. If a topo‐
5211 logical branch is not named, it becomes an anonymous branch of
5212 the current, possibly default, branch.
5213 Changelog
5215 A record of the changesets in the order in which they were added
5216 to the repository. This includes details such as changeset id,
5217 author, commit message, date, and list of changed files.
5218 Changeset
5220 A snapshot of the state of the repository used to record a
5221 change.
5222 Changeset, child
5224 The converse of parent changeset: if P is a parent of C, then C
5225 is a child of P. There is no limit to the number of children
5226 that a changeset may have.
5227 Changeset id
5229 A SHA-1 hash that uniquely identifies a changeset. It may be
5230 represented as either a "long" 40 hexadecimal digit string, or a
5231 "short" 12 hexadecimal digit string.
5232 Changeset, merge
5234 A changeset with two parents. This occurs when a merge is com‐
5235 mitted.
5236 Changeset, parent
5238 A revision upon which a child changeset is based. Specifically,
5239 a parent changeset of a changeset C is a changeset whose node
5240 immediately precedes C in the DAG. Changesets have at most two
5241 parents.
5242 Checkout
5244 (Noun) The working directory being updated to a specific revi‐
5245 sion. This use should probably be avoided where possible, as
5246 changeset is much more appropriate than checkout in this con‐
5247 text.
5248 Example: "I'm using checkout X."
5250 (Verb) Updating the working directory to a specific changeset.
5252 See hg help update.
5253 Example: "I'm going to check out changeset X."
5255 Child changeset
5257 See 'Changeset, child'.
5258 Close changeset
5260 See 'Head, closed branch'.
5261 Closed branch
5263 See 'Branch, closed'.
5264 Clone (Noun) An entire or partial copy of a repository. The partial
5266 clone must be in the form of a revision and its ancestors.
5267 Example: "Is your clone up to date?"
5269 (Verb) The process of creating a clone, using hg clone.
5271 Example: "I'm going to clone the repository."
5273 Closed branch head
5275 See 'Head, closed branch'.
5276 Commit (Noun) A synonym for changeset.
5278 Example: "Is the bug fixed in your recent commit?"
5280 (Verb) The act of recording changes to a repository. When files
5282 are committed in a working directory, Mercurial finds the dif‐
5283 ferences between the committed files and their parent changeset,
5284 creating a new changeset in the repository.
5285 Example: "You should commit those changes now."
5287 Cset A common abbreviation of the term changeset.
5289 DAG The repository of changesets of a distributed version control
5291 system (DVCS) can be described as a directed acyclic graph
5292 (DAG), consisting of nodes and edges, where nodes correspond to
5293 changesets and edges imply a parent -> child relation. This
5294 graph can be visualized by graphical tools such as hg log
5295 --graph. In Mercurial, the DAG is limited by the requirement for
5296 children to have at most two parents.
5297 Deprecated
5299 Feature removed from documentation, but not scheduled for re‐
5300 moval.
5301 Default branch
5303 See 'Branch, default'.
5304 Descendant
5306 Any changeset that can be reached by a chain of child changesets
5307 from a given changeset. More precisely, the descendants of a
5308 changeset can be defined by two properties: the child of a
5309 changeset is a descendant, and the child of a descendant is a
5310 descendant. See also: 'Ancestor'.
5311 Diff (Noun) The difference between the contents and attributes of
5313 files in two changesets or a changeset and the current working
5314 directory. The difference is usually represented in a standard
5315 form called a "diff" or "patch". The "git diff" format is used
5316 when the changes include copies, renames, or changes to file at‐
5317 tributes, none of which can be represented/handled by classic
5318 "diff" and "patch".
5319 Example: "Did you see my correction in the diff?"
5321 (Verb) Diffing two changesets is the action of creating a diff
5323 or patch.
5324 Example: "If you diff with changeset X, you will see what I
5326 mean."
5327 Directory, working
5329 The working directory represents the state of the files tracked
5330 by Mercurial, that will be recorded in the next commit. The
5331 working directory initially corresponds to the snapshot at an
5332 existing changeset, known as the parent of the working direc‐
5333 tory. See 'Parent, working directory'. The state may be modified
5334 by changes to the files introduced manually or by a merge. The
5335 repository metadata exists in the .hg directory inside the work‐
5336 ing directory.
5337 Draft Changesets in the draft phase have not been shared with publish‐
5339 ing repositories and may thus be safely changed by history-modi‐
5340 fying extensions. See hg help phases.
5341 Experimental
5343 Feature that may change or be removed at a later date.
5344 Graph See DAG and hg log --graph.
5346 Head The term 'head' may be used to refer to both a branch head or a
5348 repository head, depending on the context. See 'Head, branch'
5349 and 'Head, repository' for specific definitions.
5350 Heads are where development generally takes place and are the
5352 usual targets for update and merge operations.
5353 Head, branch
5355 A changeset with no descendants on the same named branch.
5356 Head, closed branch
5358 A changeset that marks a head as no longer interesting. The
5359 closed head is no longer listed by hg heads. A branch is consid‐
5360 ered closed when all its heads are closed and consequently is
5361 not listed by hg branches.
5362 Closed heads can be re-opened by committing new changeset as the
5364 child of the changeset that marks a head as closed.
5365 Head, repository
5367 A topological head which has not been closed.
5368 Head, topological
5370 A changeset with no children in the repository.
5371 History, immutable
5373 Once committed, changesets cannot be altered. Extensions which
5374 appear to change history actually create new changesets that re‐
5375 place existing ones, and then destroy the old changesets. Doing
5376 so in public repositories can result in old changesets being
5377 reintroduced to the repository.
5378 History, rewriting
5380 The changesets in a repository are immutable. However, exten‐
5381 sions to Mercurial can be used to alter the repository, usually
5382 in such a way as to preserve changeset contents.
5383 Immutable history
5385 See 'History, immutable'.
5386 Merge changeset
5388 See 'Changeset, merge'.
5389 Manifest
5391 Each changeset has a manifest, which is the list of files that
5392 are tracked by the changeset.
5393 Merge Used to bring together divergent branches of work. When you up‐
5395 date to a changeset and then merge another changeset, you bring
5396 the history of the latter changeset into your working directory.
5397 Once conflicts are resolved (and marked), this merge may be com‐
5398 mitted as a merge changeset, bringing two branches together in
5399 the DAG.
5400 Named branch
5402 See 'Branch, named'.
5403 Null changeset
5405 The empty changeset. It is the parent state of newly-initialized
5406 repositories and repositories with no checked out revision. It
5407 is thus the parent of root changesets and the effective ancestor
5408 when merging unrelated changesets. Can be specified by the alias
5409 'null' or by the changeset ID '000000000000'.
5410 Parent See 'Changeset, parent'.
5412 Parent changeset
5414 See 'Changeset, parent'.
5415 Parent, working directory
5417 The working directory parent reflects a virtual revision which
5418 is the child of the changeset (or two changesets with an uncom‐
5419 mitted merge) shown by hg parents. This is changed with hg up‐
5420 date. Other commands to see the working directory parent are hg
5421 summary and hg id. Can be specified by the alias ".".
5422 Patch (Noun) The product of a diff operation.
5424 Example: "I've sent you my patch."
5426 (Verb) The process of using a patch file to transform one
5428 changeset into another.
5429 Example: "You will need to patch that revision."
5431 Phase A per-changeset state tracking how the changeset has been or
5433 should be shared. See hg help phases.
5434 Public Changesets in the public phase have been shared with publishing
5436 repositories and are therefore considered immutable. See hg help
5437 phases.
5438 Pull An operation in which changesets in a remote repository which
5440 are not in the local repository are brought into the local
5441 repository. Note that this operation without special arguments
5442 only updates the repository, it does not update the files in the
5443 working directory. See hg help pull.
5444 Push An operation in which changesets in a local repository which are
5446 not in a remote repository are sent to the remote repository.
5447 Note that this operation only adds changesets which have been
5448 committed locally to the remote repository. Uncommitted changes
5449 are not sent. See hg help push.
5450 Repository
5452 The metadata describing all recorded states of a collection of
5453 files. Each recorded state is represented by a changeset. A
5454 repository is usually (but not always) found in the .hg subdi‐
5455 rectory of a working directory. Any recorded state can be recre‐
5456 ated by "updating" a working directory to a specific changeset.
5457 Repository head
5459 See 'Head, repository'.
5460 Revision
5462 A state of the repository at some point in time. Earlier revi‐
5463 sions can be updated to by using hg update. See also 'Revision
5464 number'; See also 'Changeset'.
5465 Revision number
5467 This integer uniquely identifies a changeset in a specific
5468 repository. It represents the order in which changesets were
5469 added to a repository, starting with revision number 0. Note
5470 that the revision number may be different in each clone of a
5471 repository. To identify changesets uniquely between different
5472 clones, see 'Changeset id'.
5473 Revlog History storage mechanism used by Mercurial. It is a form of
5475 delta encoding, with occasional full revision of data followed
5476 by delta of each successive revision. It includes data and an
5477 index pointing to the data.
5478 Rewriting history
5480 See 'History, rewriting'.
5481 Root A changeset that has only the null changeset as its parent. Most
5483 repositories have only a single root changeset.
5484 Secret Changesets in the secret phase may not be shared via push, pull,
5486 or clone. See hg help phases.
5487 Tag An alternative name given to a changeset. Tags can be used in
5489 all places where Mercurial expects a changeset ID, e.g., with hg
5490 update. The creation of a tag is stored in the history and will
5491 thus automatically be shared with other using push and pull.
5492 Tip The changeset with the highest revision number. It is the
5494 changeset most recently added in a repository.
5495 Tip, branch
5497 The head of a given branch with the highest revision number.
5498 When a branch name is used as a revision identifier, it refers
5499 to the branch tip. See also 'Branch, head'. Note that because
5500 revision numbers may be different in different repository
5501 clones, the branch tip may be different in different cloned
5502 repositories.
5503 Update (Noun) Another synonym of changeset.
5505 Example: "I've pushed an update."
5507 (Verb) This term is usually used to describe updating the state
5509 of the working directory to that of a specific changeset. See hg
5510 help update.
5511 Example: "You should update."
5513 Working directory
5515 See 'Directory, working'.
5516 Working directory parent
5518 See 'Parent, working directory'.
5519
5521 Synopsis
5522 The Mercurial system uses a file called .hgignore in the root directory
5523 of a repository to control its behavior when it searches for files that
5524 it is not currently tracking.
5525 Description
5527 The working directory of a Mercurial repository will often contain
5528 files that should not be tracked by Mercurial. These include backup
5529 files created by editors and build products created by compilers.
5530 These files can be ignored by listing them in a .hgignore file in the
5531 root of the working directory. The .hgignore file must be created manu‐
5532 ally. It is typically put under version control, so that the settings
5533 will propagate to other repositories with push and pull.
5534 An untracked file is ignored if its path relative to the repository
5536 root directory, or any prefix path of that path, is matched against any
5537 pattern in .hgignore.
5538 For example, say we have an untracked file, file.c, at a/b/file.c in‐
5540 side our repository. Mercurial will ignore file.c if any pattern in
5541 .hgignore matches a/b/file.c, a/b or a.
5542 In addition, a Mercurial configuration file can reference a set of
5544 per-user or global ignore files. See the ignore configuration key on
5545 the [ui] section of hg help config for details of how to configure
5546 these files.
5547 To control Mercurial's handling of files that it manages, many commands
5549 support the -I and -X options; see hg help <command> and hg help pat‐
5550 terns for details.
5551 Files that are already tracked are not affected by .hgignore, even if
5553 they appear in .hgignore. An untracked file X can be explicitly added
5554 with hg add X, even if X would be excluded by a pattern in .hgignore.
5555 Syntax
5557 An ignore file is a plain text file consisting of a list of patterns,
5558 with one pattern per line. Empty lines are skipped. The # character is
5559 treated as a comment character, and the \ character is treated as an
5560 escape character.
5561 Mercurial supports several pattern syntaxes. The default syntax used is
5563 Python/Perl-style regular expressions.
5564 To change the syntax used, use a line of the following form:
5566 syntax: NAME
5568 where NAME is one of the following:
5570 regexp
5572 Regular expression, Python/Perl syntax.
5574 glob
5576 Shell-style glob.
5578 rootglob
5580 A variant of glob that is rooted (see below).
5582 The chosen syntax stays in effect when parsing all patterns that fol‐
5584 low, until another syntax is selected.
5585 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
5587 the form *.c will match a file ending in .c in any directory, and a
5588 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
5589 tern, start it with ^. To get the same effect with glob-syntax, you
5590 have to use rootglob.
5591 Subdirectories can have their own .hgignore settings by adding subin‐
5593 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
5594 terns for details on subinclude: and include:.
5595 Note Patterns specified in other than .hgignore are always rooted.
5597 Please see hg help patterns for details.
5598 Example
5600 Here is an example ignore file.
5601 # use glob syntax.
5603 syntax: glob
5604 *.elc
5606 *.pyc
5607 *~
5608 # switch to regexp syntax.
5610 syntax: regexp
5611 ^\.pc/
5612 Debugging
5614 Use the debugignore command to see if and why a file is ignored, or to
5615 see the combined ignore pattern. See hg help debugignore for details.
5616
5618 Mercurial's internal web server, hgweb, can serve either a single
5619 repository, or a tree of repositories. In the second case, repository
5620 paths and global options can be defined using a dedicated configuration
5621 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
5622 This file uses the same syntax as other Mercurial configuration files
5624 but recognizes only the following sections:
5625 • web
5627 • paths
5629 • collections
5631 The web options are thoroughly described in hg help config.
5633 The paths section maps URL paths to paths of repositories in the
5635 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
5636 rial repositories can be published and only according to the configura‐
5637 tion.
5638 The left hand side is the path in the URL. Note that hgweb reserves
5640 subpaths like rev or file, try using different names for nested reposi‐
5641 tories to avoid confusing effects.
5642 The right hand side is the path in the filesystem. If the specified
5644 path ends with * or ** the filesystem will be searched recursively for
5645 repositories below that point. With * it will not recurse into the
5646 repositories it finds (except for .hg/patches). With ** it will also
5647 search inside repository working directories and possibly find sub‐
5648 repositories.
5649 In this example:
5651 [paths]
5653 /projects/a = /srv/tmprepos/a
5654 /projects/b = c:/repos/b
5655 / = /srv/repos/*
5656 /user/bob = /home/bob/repos/**
5657 • The first two entries make two repositories in different directories
5659 appear under the same directory in the web interface
5660 • The third entry will publish every Mercurial repository found in
5662 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
5663 as http://server/quux/
5664 • The fourth entry will publish both http://server/user/bob/quux/ and
5666 http://server/user/bob/quux/testsubrepo/
5667 The collections section is deprecated and has been superseded by paths.
5669 URLs and Common Arguments
5671 URLs under each repository have the form /{command}[/{arguments}] where
5672 {command} represents the name of a command or handler and {arguments}
5673 represents any number of additional URL parameters to that command.
5674 The web server has a default style associated with it. Styles map to a
5676 collection of named templates. Each template is used to render a spe‐
5677 cific piece of data, such as a changeset or diff.
5678 The style for the current request can be overridden two ways. First, if
5680 {command} contains a hyphen (-), the text before the hyphen defines the
5681 style. For example, /atom-log will render the log command handler with
5682 the atom style. The second way to set the style is with the style query
5683 string argument. For example, /log?style=atom. The hyphenated URL pa‐
5684 rameter is preferred.
5685 Not all templates are available for all styles. Attempting to use a
5687 style that doesn't have all templates defined may result in an error
5688 rendering the page.
5689 Many commands take a {revision} URL parameter. This defines the change‐
5691 set to operate on. This is commonly specified as the short, 12 digit
5692 hexadecimal abbreviation for the full 40 character unique revision
5693 identifier. However, any value described by hg help revisions typically
5694 works.
5695 Commands and URLs
5697 The following web commands and their URLs are available:
5698 /annotate/{revision}/{path}
5700 Show changeset information for each line in a file.
5701 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
5703 string arguments have the same meaning as their [annotate] config
5704 equivalents. It uses the hgrc boolean parsing logic to interpret the
5705 value. e.g. 0 and false are false and 1 and true are true. If not de‐
5706 fined, the server default settings are used.
5707 The fileannotate template is rendered.
5709 /archive/{revision}.{format}[/{path}]
5711 Obtain an archive of repository content.
5712 The content and type of the archive is defined by a URL path parameter.
5714 format is the file extension of the archive type to be generated. e.g.
5715 zip or tar.bz2. Not all archive types may be allowed by your server
5716 configuration.
5717 The optional path URL parameter controls content to include in the ar‐
5719 chive. If omitted, every file in the specified revision is present in
5720 the archive. If included, only the specified file or contents of the
5721 specified directory will be included in the archive.
5722 No template is used for this handler. Raw, binary content is generated.
5724 /bookmarks
5726 Show information about bookmarks.
5727 No arguments are accepted.
5729 The bookmarks template is rendered.
5731 /branches
5733 Show information about branches.
5734 All known branches are contained in the output, even closed branches.
5736 No arguments are accepted.
5738 The branches template is rendered.
5740 /changelog[/{revision}]
5742 Show information about multiple changesets.
5743 If the optional revision URL argument is absent, information about all
5745 changesets starting at tip will be rendered. If the revision argument
5746 is present, changesets will be shown starting from the specified revi‐
5747 sion.
5748 If revision is absent, the rev query string argument may be defined.
5750 This will perform a search for changesets.
5751 The argument for rev can be a single revision, a revision set, or a
5753 literal keyword to search for in changeset data (equivalent to hg log
5754 -k).
5755 The revcount query string argument defines the maximum numbers of
5757 changesets to render.
5758 For non-searches, the changelog template will be rendered.
5760 /changeset[/{revision}]
5762 Show information about a single changeset.
5763 A URL path argument is the changeset identifier to show. See hg help
5765 revisions for possible values. If not defined, the tip changeset will
5766 be shown.
5767 The changeset template is rendered. Contents of the changesettag,
5769 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5770 lated to diffs may all be used to produce the output.
5771 /comparison/{revision}/{path}
5773 Show a comparison between the old and new versions of a file from
5774 changes made on a particular revision.
5775 This is similar to the diff handler. However, this form features a
5777 split or side-by-side diff rather than a unified diff.
5778 The context query string argument can be used to control the lines of
5780 context in the diff.
5781 The filecomparison template is rendered.
5783 /diff/{revision}/{path}
5785 Show how a file changed in a particular commit.
5786 The filediff template is rendered.
5788 This handler is registered under both the /diff and /filediff paths.
5790 /diff is used in modern code.
5791 /file/{revision}[/{path}]
5793 Show information about a directory or file in the repository.
5794 Info about the path given as a URL parameter will be rendered.
5796 If path is a directory, information about the entries in that directory
5798 will be rendered. This form is equivalent to the manifest handler.
5799 If path is a file, information about that file will be shown via the
5801 filerevision template.
5802 If path is not defined, information about the root directory will be
5804 rendered.
5805 /diff/{revision}/{path}
5807 Show how a file changed in a particular commit.
5808 The filediff template is rendered.
5810 This handler is registered under both the /diff and /filediff paths.
5812 /diff is used in modern code.
5813 /filelog/{revision}/{path}
5815 Show information about the history of a file in the repository.
5816 The revcount query string argument can be defined to control the maxi‐
5818 mum number of entries to show.
5819 The filelog template will be rendered.
5821 /graph[/{revision}]
5823 Show information about the graphical topology of the repository.
5824 Information rendered by this handler can be used to create visual rep‐
5826 resentations of repository topology.
5827 The revision URL parameter controls the starting changeset. If it's ab‐
5829 sent, the default is tip.
5830 The revcount query string argument can define the number of changesets
5832 to show information for.
5833 The graphtop query string argument can specify the starting changeset
5835 for producing jsdata variable that is used for rendering graph in Java‐
5836 Script. By default it has the same value as revision.
5837 This handler will render the graph template.
5839 /help[/{topic}]
5841 Render help documentation.
5842 This web command is roughly equivalent to hg help. If a topic is de‐
5844 fined, that help topic will be rendered. If not, an index of available
5845 help topics will be rendered.
5846 The help template will be rendered when requesting help for a topic.
5848 helptopics will be rendered for the index of help topics.
5849 /log[/{revision}[/{path}]]
5851 Show repository or file history.
5852 For URLs of the form /log/{revision}, a list of changesets starting at
5854 the specified changeset identifier is shown. If {revision} is not de‐
5855 fined, the default is tip. This form is equivalent to the changelog
5856 handler.
5857 For URLs of the form /log/{revision}/{file}, the history for a specific
5859 file will be shown. This form is equivalent to the filelog handler.
5860 /manifest[/{revision}[/{path}]]
5862 Show information about a directory.
5863 If the URL path arguments are omitted, information about the root di‐
5865 rectory for the tip changeset will be shown.
5866 Because this handler can only show information for directories, it is
5868 recommended to use the file handler instead, as it can handle both di‐
5869 rectories and files.
5870 The manifest template will be rendered for this handler.
5872 /changeset[/{revision}]
5874 Show information about a single changeset.
5875 A URL path argument is the changeset identifier to show. See hg help
5877 revisions for possible values. If not defined, the tip changeset will
5878 be shown.
5879 The changeset template is rendered. Contents of the changesettag,
5881 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5882 lated to diffs may all be used to produce the output.
5883 /shortlog
5885 Show basic information about a set of changesets.
5886 This accepts the same parameters as the changelog handler. The only
5888 difference is the shortlog template will be rendered instead of the
5889 changelog template.
5890 /summary
5892 Show a summary of repository state.
5893 Information about the latest changesets, bookmarks, tags, and branches
5895 is captured by this handler.
5896 The summary template is rendered.
5898 /tags
5900 Show information about tags.
5901 No arguments are accepted.
5903 The tags template is rendered.
5905
5907 To access a subtopic, use "hg help internals.{subtopic-name}"
5908 bid-merge
5910 Bid Merge Algorithm
5911 bundle2
5913 Bundle2
5914 bundles
5916 Bundles
5917 cbor CBOR
5919 censor Censor
5921 changegroups
5923 Changegroups
5924 config Config Registrar
5926 dirstate-v2
5928 dirstate-v2 file format
5929 extensions
5931 Extension API
5932 mergestate
5934 Mergestate
5935 requirements
5937 Repository Requirements
5938 revlogs
5940 Revision Logs
5941 wireprotocol
5943 Wire Protocol
5944 wireprotocolrpc
5946 Wire Protocol RPC
5947 wireprotocolv2
5949 Wire Protocol Version 2
5950
5952 To merge files Mercurial uses merge tools.
5953 A merge tool combines two different versions of a file into a merged
5955 file. Merge tools are given the two files and the greatest common an‐
5956 cestor of the two file versions, so they can determine the changes made
5957 on both branches.
5958 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
5960 out and in several extensions.
5961 Usually, the merge tool tries to automatically reconcile the files by
5963 combining all non-overlapping changes that occurred separately in the
5964 two different evolutions of the same initial base file. Furthermore,
5965 some interactive merge programs make it easier to manually resolve con‐
5966 flicting merges, either in a graphical way, or by inserting some con‐
5967 flict markers. Mercurial does not include any interactive merge pro‐
5968 grams but relies on external tools for that.
5969 Available merge tools
5971 External merge tools and their properties are configured in the
5972 merge-tools configuration section - see hgrc(5) - but they can often
5973 just be named by their executable.
5974 A merge tool is generally usable if its executable can be found on the
5976 system and if it can handle the merge. The executable is found if it is
5977 an absolute or relative executable path or the name of an application
5978 in the executable search path. The tool is assumed to be able to handle
5979 the merge if it can handle symlinks if the file is a symlink, if it can
5980 handle binary files if the file is binary, and if a GUI is available if
5981 the tool requires a GUI.
5982 There are some internal merge tools which can be used. The internal
5984 merge tools are:
5985 :dump
5987 Creates three versions of the files to merge, containing the
5989 contents of local, other and base. These files can then be used
5990 to perform a merge manually. If the file to be merged is named
5991 a.txt, these files will accordingly be named a.txt.local,
5992 a.txt.other and a.txt.base and they will be placed in the same
5993 directory as a.txt.
5994 This implies premerge. Therefore, files aren't dumped, if pre‐
5996 merge runs successfully. Use :forcedump to forcibly write files
5997 out.
5998 (actual capabilities: binary, symlink)
6000 :fail
6002 Rather than attempting to merge files that were modified on both
6004 branches, it marks them as unresolved. The resolve command must
6005 be used to resolve these conflicts.
6006 (actual capabilities: binary, symlink)
6008 :forcedump
6010 Creates three versions of the files as same as :dump, but omits
6012 premerge.
6013 (actual capabilities: binary, symlink)
6015 :local
6017 Uses the local p1() version of files as the merged version.
6019 (actual capabilities: binary, symlink)
6021 :merge
6023 Uses the internal non-interactive simple merge algorithm for
6025 merging files. It will fail if there are any conflicts and leave
6026 markers in the partially merged file. Markers will have two sec‐
6027 tions, one for each side of merge.
6028 :merge-local
6030 Like :merge, but resolve all conflicts non-interactively in fa‐
6032 vor of the local p1() changes.
6033 :merge-other
6035 Like :merge, but resolve all conflicts non-interactively in fa‐
6037 vor of the other p2() changes.
6038 :merge3
6040 Uses the internal non-interactive simple merge algorithm for
6042 merging files. It will fail if there are any conflicts and leave
6043 markers in the partially merged file. Marker will have three
6044 sections, one from each side of the merge and one for the base
6045 content.
6046 :mergediff
6048 Uses the internal non-interactive simple merge algorithm for
6050 merging files. It will fail if there are any conflicts and leave
6051 markers in the partially merged file. The marker will have two
6052 sections, one with the content from one side of the merge, and
6053 one with a diff from the base content to the content on the
6054 other side. (experimental)
6055 :other
6057 Uses the other p2() version of files as the merged version.
6059 (actual capabilities: binary, symlink)
6061 :prompt
6063 Asks the user which of the local p1() or the other p2() version
6065 to keep as the merged version.
6066 (actual capabilities: binary, symlink)
6068 :tagmerge
6070 Uses the internal tag merge algorithm (experimental).
6072 :union
6074 Uses the internal non-interactive simple merge algorithm for
6076 merging files. It will use both left and right sides for con‐
6077 flict regions. No markers are inserted.
6078 Internal tools are always available and do not require a GUI but will
6080 by default not handle symlinks or binary files. See next section for
6081 detail about "actual capabilities" described above.
6082 Choosing a merge tool
6084 Mercurial uses these rules when deciding which merge tool to use:
6085 1. If a tool has been specified with the --tool option to merge or re‐
6087 solve, it is used. If it is the name of a tool in the merge-tools
6088 configuration, its configuration is used. Otherwise the specified
6089 tool must be executable by the shell.
6090 2. If the HGMERGE environment variable is present, its value is used
6092 and must be executable by the shell.
6093 3. If the filename of the file to be merged matches any of the patterns
6095 in the merge-patterns configuration section, the first usable merge
6096 tool corresponding to a matching pattern is used.
6097 4. If ui.merge is set it will be considered next. If the value is not
6099 the name of a configured tool, the specified value is used and must
6100 be executable by the shell. Otherwise the named tool is used if it
6101 is usable.
6102 5. If any usable merge tools are present in the merge-tools configura‐
6104 tion section, the one with the highest priority is used.
6105 6. If a program named hgmerge can be found on the system, it is used -
6107 but it will by default not be used for symlinks and binary files.
6108 7. If the file to be merged is not binary and is not a symlink, then
6110 internal :merge is used.
6111 8. Otherwise, :prompt is used.
6113 For historical reason, Mercurial treats merge tools as below while ex‐
6115 amining rules above.
6116 ┌───────────┬────────────────┬────────┬─────────┐
6118 │step │ specified via │ binary │ symlink │
6119 ├───────────┼────────────────┼────────┼─────────┤
6120 │ │ --tool │ o/o │ o/o │
6121 │ 1. │ │ │ │
6122 ├───────────┼────────────────┼────────┼─────────┤
6123 │ │ HGMERGE │ o/o │ o/o │
6124 │ 2. │ │ │ │
6125 ├───────────┼────────────────┼────────┼─────────┤
6126 │ │ merge-patterns │ o/o(*) │ x/?(*) │
6127 │ 3. │ │ │ │
6128 ├───────────┼────────────────┼────────┼─────────┤
6129 │ │ ui.merge │ x/?(*) │ x/?(*) │
6130 │ 4. │ │ │ │
6131 └───────────┴────────────────┴────────┴─────────┘
6132 Each capability column indicates Mercurial behavior for internal/exter‐
6134 nal merge tools at examining each rule.
6135 • "o": "assume that a tool has capability"
6137 • "x": "assume that a tool does not have capability"
6139 • "?": "check actual capability of a tool"
6141 If merge.strict-capability-check configuration is true, Mercurial
6143 checks capabilities of merge tools strictly in (*) cases above (= each
6144 capability column becomes "?/?"). It is false by default for backward
6145 compatibility.
6146 Note After selecting a merge program, Mercurial will by default at‐
6148 tempt to merge the files using a simple merge algorithm first.
6149 Only if it doesn't succeed because of conflicting changes will
6150 Mercurial actually execute the merge program. Whether to use the
6151 simple merge algorithm first can be controlled by the premerge
6152 setting of the merge tool. Premerge is enabled by default unless
6153 the file is binary or a symlink.
6154 See the merge-tools and ui sections of hgrc(5) for details on the con‐
6156 figuration of merge tools.
6157
6159 Some Mercurial commands can produce a lot of output, and Mercurial will
6160 attempt to use a pager to make those commands more pleasant.
6161 To set the pager that should be used, set the application variable:
6163 [pager]
6165 pager = less -FRX
6166 If no pager is set in the user or repository configuration, Mercurial
6168 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
6169 from the default or system configuration is used. If none of these are
6170 set, a default pager will be used, typically less on Unix and more on
6171 Windows.
6172 On Windows, more is not color aware, so using it effectively disables
6174 color. MSYS and Cygwin shells provide less as a pager, which can be
6175 configured to support ANSI color codes. See hg help con‐
6176 fig.color.pagermode to configure the color mode when invoking a pager.
6177 You can disable the pager for certain commands by adding them to the
6179 pager.ignore list:
6180 [pager]
6182 ignore = version, help, update
6183 To ignore global commands like hg version or hg help, you have to spec‐
6185 ify them in your user configuration file.
6186 To control whether the pager is used at all for an individual command,
6188 you can use --pager=<value>:
6189 • use as needed: auto.
6191 • require the pager: yes or on.
6193 • suppress the pager: no or off (any unrecognized value will also
6195 work).
6196 To globally turn off all attempts to use a pager, set:
6198 [ui]
6200 paginate = never
6201 which will prevent the pager from running.
6203
6205 Mercurial accepts several notations for identifying one or more files
6206 at a time.
6207 By default, Mercurial treats filenames verbatim without pattern match‐
6209 ing, relative to the current working directory. Note that your system
6210 shell might perform pattern matching of its own before passing file‐
6211 names into Mercurial.
6212 Alternate pattern notations must be specified explicitly.
6214 Note Patterns specified in .hgignore are not rooted. Please see hg
6216 help hgignore for details.
6217 To use a plain path name without any pattern matching, start it with
6219 path:. These path names must completely match starting at the current
6220 repository root, and when the path points to a directory, it is matched
6221 recursively. To match all files in a directory non-recursively (not in‐
6222 cluding any files in subdirectories), rootfilesin: can be used, speci‐
6223 fying an absolute path (relative to the repository root).
6224 To use an extended glob, start a name with glob:. Globs are rooted at
6226 the current directory; a glob such as *.c will only match files in the
6227 current directory ending with .c. rootglob: can be used instead of
6228 glob: for a glob that is rooted at the root of the repository.
6229 The supported glob syntax extensions are ** to match any string across
6231 path separators and {a,b} to mean "a or b".
6232 To use a Perl/Python regular expression, start a name with re:. Regexp
6234 pattern matching is anchored at the root of the repository.
6235 To read name patterns from a file, use listfile: or listfile0:. The
6237 latter expects null delimited patterns while the former expects line
6238 feeds. Each string read from the file is itself treated as a file pat‐
6239 tern.
6240 To read a set of patterns from a file, use include: or subinclude:.
6242 include: will use all the patterns from the given file and treat them
6243 as if they had been passed in manually. subinclude: will only apply
6244 the patterns against files that are under the subinclude file's direc‐
6245 tory. See hg help hgignore for details on the format of these files.
6246 All patterns, except for glob: specified in command line (not for -I or
6248 -X options), can match also against directories: files under matched
6249 directories are treated as matched. For -I and -X options, glob: will
6250 match directories recursively.
6251 Plain examples:
6253 path:foo/bar a name bar in a directory named foo in the root
6255 of the repository
6256 path:path:name a file or directory named "path:name"
6257 rootfilesin:foo/bar the files in a directory called foo/bar, but not any files
6258 in its subdirectories and not a file bar in directory foo
6259 Glob examples:
6261 glob:*.c any name ending in ".c" in the current directory
6263 *.c any name ending in ".c" in the current directory
6264 **.c any name ending in ".c" in any subdirectory of the
6265 current directory including itself.
6266 foo/* any file in directory foo
6267 foo/** any file in directory foo plus all its subdirectories,
6268 recursively
6269 foo/*.c any name ending in ".c" in the directory foo
6270 foo/**.c any name ending in ".c" in any subdirectory of foo
6271 including itself.
6272 rootglob:*.c any name ending in ".c" in the root of the repository
6273 Regexp examples:
6275 re:.*\.c$ any name ending in ".c", anywhere in the repository
6277 File examples:
6279 listfile:list.txt read list from list.txt with one file pattern per line
6281 listfile0:list.txt read list from list.txt with null byte delimiters
6282 See also hg help filesets.
6284 Include examples:
6286 include:path/to/mypatternfile reads patterns to be applied to all paths
6288 subinclude:path/to/subignorefile reads patterns specifically for paths in the
6289 subdirectory
6290
6292 What are phases?
6293 Phases are a system for tracking which changesets have been or should
6294 be shared. This helps prevent common mistakes when modifying history
6295 (for instance, with the mq or rebase extensions).
6296 Each changeset in a repository is in one of the following phases:
6298 • public : changeset is visible on a public server
6300 • draft : changeset is not yet published
6302 • secret : changeset should not be pushed, pulled, or cloned
6304 These phases are ordered (public < draft < secret) and no changeset can
6306 be in a lower phase than its ancestors. For instance, if a changeset is
6307 public, all its ancestors are also public. Lastly, changeset phases
6308 should only be changed towards the public phase.
6309 How are phases managed?
6311 For the most part, phases should work transparently. By default, a
6312 changeset is created in the draft phase and is moved into the public
6313 phase when it is pushed to another repository.
6314 Once changesets become public, extensions like mq and rebase will
6316 refuse to operate on them to prevent creating duplicate changesets.
6317 Phases can also be manually manipulated with the hg phase command if
6318 needed. See hg help -v phase for examples.
6319 To make your commits secret by default, put this in your configuration
6321 file:
6322 [phases]
6324 new-commit = secret
6325 Phases and servers
6327 Normally, all servers are publishing by default. This means:
6328 - all draft changesets that are pulled or cloned appear in phase
6330 public on the client
6331 - all draft changesets that are pushed appear as public on both
6333 client and server
6334 - secret changesets are neither pushed, pulled, or cloned
6336 Note Pulling a draft changeset from a publishing server does not mark
6338 it as public on the server side due to the read-only nature of
6339 pull.
6340 Sometimes it may be desirable to push and pull changesets in the draft
6342 phase to share unfinished work. This can be done by setting a reposi‐
6343 tory to disable publishing in its configuration file:
6344 [phases]
6346 publish = False
6347 See hg help config for more information on configuration files.
6349 Note Servers running older versions of Mercurial are treated as pub‐
6351 lishing.
6352 Note Changesets in secret phase are not exchanged with the server.
6354 This applies to their content: file names, file contents, and
6355 changeset metadata. For technical reasons, the identifier (e.g.
6356 d825e4025e39) of the secret changeset may be communicated to the
6357 server.
6358 Examples
6360 • list changesets in draft or secret phase:
6361 hg log -r "not public()"
6363 • change all secret changesets to draft:
6365 hg phase --draft "secret()"
6367 • forcibly move the current changeset and descendants from public to
6369 draft:
6370 hg phase --force --draft .
6372 • show a list of changeset revisions and each corresponding phase:
6374 hg log --template "{rev} {phase}\n"
6376 • resynchronize draft changesets relative to a remote repository:
6378 hg phase -fd "outgoing(URL)"
6380 See hg help phase for more information on manually manipulating phases.
6382
6384 Mercurial supports several ways to specify revisions.
6385 Specifying single revisions
6387 A plain integer is treated as a revision number. Negative integers are
6388 treated as sequential offsets from the tip, with -1 denoting the tip,
6389 -2 denoting the revision prior to the tip, and so forth.
6390 A 40-digit hexadecimal string is treated as a unique revision identi‐
6392 fier. A hexadecimal string less than 40 characters long is treated as
6393 a unique revision identifier and is referred to as a short-form identi‐
6394 fier. A short-form identifier is only valid if it is the prefix of ex‐
6395 actly one full-length identifier.
6396 Any other string is treated as a bookmark, tag, or branch name. A book‐
6398 mark is a movable pointer to a revision. A tag is a permanent name as‐
6399 sociated with a revision. A branch name denotes the tipmost open branch
6400 head of that branch - or if they are all closed, the tipmost closed
6401 head of the branch. Bookmark, tag, and branch names must not contain
6402 the ":" character.
6403 The reserved name "tip" always identifies the most recent revision.
6405 The reserved name "null" indicates the null revision. This is the revi‐
6407 sion of an empty repository, and the parent of revision 0.
6408 The reserved name "." indicates the working directory parent. If no
6410 working directory is checked out, it is equivalent to null. If an un‐
6411 committed merge is in progress, "." is the revision of the first par‐
6412 ent.
6413 Finally, commands that expect a single revision (like hg update) also
6415 accept revsets (see below for details). When given a revset, they use
6416 the last revision of the revset. A few commands accept two single revi‐
6417 sions (like hg diff). When given a revset, they use the first and the
6418 last revisions of the revset.
6419 Specifying multiple revisions
6421 Mercurial supports a functional language for selecting a set of revi‐
6422 sions. Expressions in this language are called revsets.
6423 The language supports a number of predicates which are joined by infix
6425 operators. Parenthesis can be used for grouping.
6426 Identifiers such as branch names may need quoting with single or double
6428 quotes if they contain characters like - or if they match one of the
6429 predefined predicates.
6430 Special characters can be used in quoted identifiers by escaping them,
6432 e.g., \n is interpreted as a newline. To prevent them from being inter‐
6433 preted, strings can be prefixed with r, e.g. r'...'.
6434 Operators
6436 There is a single prefix operator:
6437 not x
6439 Changesets not in x. Short form is ! x.
6441 These are the supported infix operators:
6443 x::y
6445 A DAG range, meaning all changesets that are descendants of x
6447 and ancestors of y, including x and y themselves. If the first
6448 endpoint is left out, this is equivalent to ancestors(y), if the
6449 second is left out it is equivalent to descendants(x).
6450 An alternative syntax is x..y.
6452 x:y
6454 All changesets with revision numbers between x and y, both in‐
6456 clusive. Either endpoint can be left out, they default to 0 and
6457 tip.
6458 x and y
6460 The intersection of changesets in x and y. Short form is x & y.
6462 x or y
6464 The union of changesets in x and y. There are two alternative
6466 short forms: x | y and x + y.
6467 x - y
6469 Changesets in x but not in y.
6471 x % y
6473 Changesets that are ancestors of x but not ancestors of y (i.e.
6475 ::x - ::y). This is shorthand notation for only(x, y) (see be‐
6476 low). The second argument is optional and, if left out, is
6477 equivalent to only(x).
6478 x^n
6480 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
6482 1, the first parent of each changeset in x; for n == 2, the sec‐
6483 ond parent of changeset in x.
6484 x~n
6486 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
6488 the nth unambiguous descendent of x.
6489 x ## y
6491 Concatenate strings and identifiers into one string.
6493 All other prefix, infix and postfix operators have lower prior‐
6495 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
6496 a2)~2.
6497 For example:
6499 [revsetalias]
6501 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
6502 issue(1234) is equivalent to grep(r'\bissue[
6504 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
6505 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
6506 There is a single postfix operator:
6508 x^
6510 Equivalent to x^1, the first parent of each changeset in x.
6512 Patterns
6514 Where noted, predicates that perform string matching can accept a pat‐
6515 tern string. The pattern may be either a literal, or a regular expres‐
6516 sion. If the pattern starts with re:, the remainder of the pattern is
6517 treated as a regular expression. Otherwise, it is treated as a literal.
6518 To match a pattern that actually starts with re:, use the prefix lit‐
6519 eral:.
6520 Matching is case-sensitive, unless otherwise noted. To perform a case-
6522 insensitive match on a case-sensitive predicate, use a regular expres‐
6523 sion, prefixed with (?i).
6524 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
6526 "Release", etc.
6527 Predicates
6529 The following predicates are supported:
6530 adds(pattern)
6532 Changesets that add a file matching pattern.
6534 The pattern without explicit kind like glob: is expected to be
6536 relative to the current directory and match against a file or a
6537 directory.
6538 all()
6540 All changesets, the same as 0:tip.
6542 ancestor(*changeset)
6544 A greatest common ancestor of the changesets.
6546 Accepts 0 or more changesets. Will return empty list when
6548 passed no args. Greatest common ancestor of a single changeset
6549 is that changeset.
6550 ancestors(set[, depth])
6552 Changesets that are ancestors of changesets in set, including
6554 the given changesets themselves.
6555 If depth is specified, the result only includes changesets up to
6557 the specified generation.
6558 author(string)
6560 Alias for user(string).
6562 bisect(string)
6564 Changesets marked in the specified bisect status:
6566 • good, bad, skip: csets explicitly marked as good/bad/skip
6568 • goods, bads : csets topologically good/bad
6570 • range : csets taking part in the bisection
6572 • pruned : csets that are goods, bads or skipped
6574 • untested : csets whose fate is yet unknown
6576 • ignored : csets ignored due to DAG topology
6578 • current : the cset currently being bisected
6580 bookmark([name])
6582 The named bookmark or all bookmarks.
6584 Pattern matching is supported for name. See hg help revi‐
6586 sions.patterns.
6587 branch(string or set)
6589 All changesets belonging to the given branch or the branches of
6591 the given changesets.
6592 Pattern matching is supported for string. See hg help revi‐
6594 sions.patterns.
6595 branchpoint()
6597 Changesets with more than one child.
6599 bundle()
6601 Changesets in the bundle.
6603 Bundle must be specified by the -R option.
6605 children(set)
6607 Child changesets of changesets in set.
6609 closed()
6611 Changeset is closed.
6613 commonancestors(set)
6615 Changesets that are ancestors of every changeset in set.
6617 conflictlocal()
6619 The local side of the merge, if currently in an unresolved
6621 merge.
6622 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6624 'hg graft'.
6625 conflictother()
6627 The other side of the merge, if currently in an unresolved
6629 merge.
6630 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6632 'hg graft'.
6633 contains(pattern)
6635 The revision's manifest contains a file matching pattern (but
6637 might not modify it). See hg help patterns for information about
6638 file patterns.
6639 The pattern without explicit kind like glob: is expected to be
6641 relative to the current directory and match against a file ex‐
6642 actly for efficiency.
6643 converted([id])
6645 Changesets converted from the given identifier in the old repos‐
6647 itory if present, or all converted changesets if no identifier
6648 is specified.
6649 date(interval)
6651 Changesets within the interval, see hg help dates.
6653 desc(string)
6655 Search commit message for string. The match is case-insensitive.
6657 Pattern matching is supported for string. See hg help revi‐
6659 sions.patterns.
6660 descendants(set[, depth])
6662 Changesets which are descendants of changesets in set, including
6664 the given changesets themselves.
6665 If depth is specified, the result only includes changesets up to
6667 the specified generation.
6668 destination([set])
6670 Changesets that were created by a graft, transplant or rebase
6672 operation, with the given revisions specified as the source.
6673 Omitting the optional set is the same as passing all().
6674 diffcontains(pattern)
6676 Search revision differences for when the pattern was added or
6678 removed.
6679 The pattern may be a substring literal or a regular expression.
6681 See hg help revisions.patterns.
6682 draft()
6684 Changeset in draft phase.
6686 expectsize(set[, size])
6688 Return the given revset if size matches the revset size. Abort
6690 if the revset doesn't expect given size. size can either be an
6691 integer range or an integer.
6692 For example, expectsize(0:1, 3:5) will abort as revset size is 2
6694 and 2 is not between 3 and 5 inclusive.
6695 extra(label, [value])
6697 Changesets with the given label in the extra metadata, with the
6699 given optional value.
6700 Pattern matching is supported for value. See hg help revi‐
6702 sions.patterns.
6703 file(pattern)
6705 Changesets affecting files matched by pattern.
6707 For a faster but less accurate result, consider using filelog()
6709 instead.
6710 This predicate uses glob: as the default kind of pattern.
6712 filelog(pattern)
6714 Changesets connected to the specified filelog.
6716 For performance reasons, visits only revisions mentioned in the
6718 file-level filelog, rather than filtering through all changesets
6719 (much faster, but doesn't include deletes or duplicate changes).
6720 For a slower, more accurate result, use file().
6721 The pattern without explicit kind like glob: is expected to be
6723 relative to the current directory and match against a file ex‐
6724 actly for efficiency.
6725 first(set, [n])
6727 An alias for limit().
6729 follow([file[, startrev]])
6731 An alias for ::. (ancestors of the working directory's first
6733 parent). If file pattern is specified, the histories of files
6734 matching given pattern in the revision given by startrev are
6735 followed, including copies.
6736 followlines(file, fromline:toline[, startrev=., descend=False])
6738 Changesets modifying file in line range ('fromline', 'toline').
6740 Line range corresponds to 'file' content at 'startrev' and
6742 should hence be consistent with file size. If startrev is not
6743 specified, working directory's parent is used.
6744 By default, ancestors of 'startrev' are returned. If 'descend'
6746 is True, descendants of 'startrev' are returned though renames
6747 are (currently) not followed in this direction.
6748 grep(regex)
6750 Like keyword(string) but accepts a regex. Use grep(r'...') to
6752 ensure special escape characters are handled correctly. Unlike
6753 keyword(string), the match is case-sensitive.
6754 head()
6756 Changeset is a named branch head.
6758 heads(set)
6760 Members of set with no children in set.
6762 hidden()
6764 Hidden changesets.
6766 id(string)
6768 Revision non-ambiguously specified by the given hex string pre‐
6770 fix.
6771 keyword(string)
6773 Search commit message, user name, and names of changed files for
6775 string. The match is case-insensitive.
6776 For a regular expression or case sensitive search of these
6778 fields, use grep(regex).
6779 last(set, [n])
6781 Last n members of set, defaulting to 1.
6783 limit(set[, n[, offset]])
6785 First n members of set, defaulting to 1, starting from offset.
6787 matching(revision [, field])
6789 Changesets in which a given set of fields match the set of
6791 fields in the selected revision or set.
6792 To match more than one field pass the list of fields to match
6794 separated by spaces (e.g. author description).
6795 Valid fields are most regular revision fields and some special
6797 fields.
6798 Regular revision fields are description, author, branch, date,
6800 files, phase, parents, substate, user and diff. Note that au‐
6801 thor and user are synonyms. diff refers to the contents of the
6802 revision. Two revisions matching their diff will also match
6803 their files.
6804 Special fields are summary and metadata: summary matches the
6806 first line of the description. metadata is equivalent to match‐
6807 ing description user date (i.e. it matches the main metadata
6808 fields).
6809 metadata is the default field which is used when no fields are
6811 specified. You can match more than one field at a time.
6812 max(set)
6814 Changeset with highest revision number in set.
6816 merge()
6818 Changeset is a merge changeset.
6820 min(set)
6822 Changeset with lowest revision number in set.
6824 modifies(pattern)
6826 Changesets modifying files matched by pattern.
6828 The pattern without explicit kind like glob: is expected to be
6830 relative to the current directory and match against a file or a
6831 directory.
6832 named(namespace)
6834 The changesets in a given namespace.
6836 Pattern matching is supported for namespace. See hg help revi‐
6838 sions.patterns.
6839 nodefromfile(path)
6841 Read a list of nodes from the file at path.
6843 This applies id(LINE) to each line of the file.
6845 This is useful when the amount of nodes you need to specify gets
6847 too large for the command line.
6848 none()
6850 No changesets.
6852 only(set, [set])
6854 Changesets that are ancestors of the first set that are not an‐
6856 cestors of any other head in the repo. If a second set is speci‐
6857 fied, the result is ancestors of the first set that are not an‐
6858 cestors of the second set (i.e. ::<set1> - ::<set2>).
6859 origin([set])
6861 Changesets that were specified as a source for the grafts,
6863 transplants or rebases that created the given revisions. Omit‐
6864 ting the optional set is the same as passing all(). If a
6865 changeset created by these operations is itself specified as a
6866 source for one of these operations, only the source changeset
6867 for the first operation is selected.
6868 outgoing([path])
6870 Changesets not found in the specified destination repository, or
6872 the default push location.
6873 If the location resolve to multiple repositories, the union of
6875 all outgoing changeset will be used.
6876 p1([set])
6878 First parent of changesets in set, or the working directory.
6880 p2([set])
6882 Second parent of changesets in set, or the working directory.
6884 parents([set])
6886 The set of all parents for all changesets in set, or the working
6888 directory.
6889 present(set)
6891 An empty set, if any revision in set isn't found; otherwise, all
6893 revisions in set.
6894 If any of specified revisions is not present in the local repos‐
6896 itory, the query is normally aborted. But this predicate allows
6897 the query to continue even in such cases.
6898 public()
6900 Changeset in public phase.
6902 remote([id [,path]])
6904 Local revision that corresponds to the given identifier in a re‐
6906 mote repository, if present. Here, the '.' identifier is a syn‐
6907 onym for the current local branch.
6908 removes(pattern)
6910 Changesets which remove files matching pattern.
6912 The pattern without explicit kind like glob: is expected to be
6914 relative to the current directory and match against a file or a
6915 directory.
6916 rev(number)
6918 Revision with the given numeric identifier.
6920 reverse(set)
6922 Reverse order of set.
6924 revset(set)
6926 Strictly interpret the content as a revset.
6928 The content of this special predicate will be strictly inter‐
6930 preted as a revset. For example, revset(id(0)) will be inter‐
6931 preted as "id(0)" without possible ambiguity with a "id(0)"
6932 bookmark or tag.
6933 roots(set)
6935 Changesets in set with no parent changeset in set.
6937 secret()
6939 Changeset in secret phase.
6941 sort(set[, [-]key... [, ...]])
6943 Sort set by keys. The default sort order is ascending, specify a
6945 key as -key to sort in descending order.
6946 The keys can be:
6948 • rev for the revision number,
6950 • branch for the branch name,
6952 • desc for the commit message (description),
6954 • user for user name (author can be used as an alias),
6956 • date for the commit date
6958 • topo for a reverse topographical sort
6960 • node the nodeid of the revision
6962 The topo sort order cannot be combined with other sort keys.
6964 This sort takes one optional argument, topo.firstbranch, which
6965 takes a revset that specifies what topographical branches to
6966 prioritize in the sort.
6967 subrepo([pattern])
6969 Changesets that add, modify or remove the given subrepo. If no
6971 subrepo pattern is named, any subrepo changes are returned.
6972 tag([name])
6974 The specified tag by name, or all tagged revisions if no name is
6976 given.
6977 Pattern matching is supported for name. See hg help revi‐
6979 sions.patterns.
6980 user(string)
6982 User name contains string. The match is case-insensitive.
6984 Pattern matching is supported for string. See hg help revi‐
6986 sions.patterns.
6987 Aliases
6989 New predicates (known as "aliases") can be defined, using any combina‐
6990 tion of existing predicates or other aliases. An alias definition looks
6991 like:
6992 <alias> = <definition>
6994 in the revsetalias section of a Mercurial configuration file. Arguments
6996 of the form a1, a2, etc. are substituted from the alias into the defi‐
6997 nition.
6998 For example,
7000 [revsetalias]
7002 h = heads()
7003 d(s) = sort(s, date)
7004 rs(s, k) = reverse(sort(s, k))
7005 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
7007 equivalent to reverse(sort(0:tip, author)).
7008 Equivalents
7010 Command line equivalents for hg log:
7011 -f -> ::.
7013 -d x -> date(x)
7014 -k x -> keyword(x)
7015 -m -> merge()
7016 -u x -> user(x)
7017 -b x -> branch(x)
7018 -P x -> !::x
7019 -l x -> limit(expr, x)
7020 Examples
7022 Some sample queries:
7023 • Changesets on the default branch:
7025 hg log -r "branch(default)"
7027 • Changesets on the default branch since tag 1.5 (excluding merges):
7029 hg log -r "branch(default) and 1.5:: and not merge()"
7031 • Open branch heads:
7033 hg log -r "head() and not closed()"
7035 • Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
7037 hgext/*:
7038 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
7040 • Changesets committed in May 2008, sorted by user:
7042 hg log -r "sort(date('May 2008'), user)"
7044 • Changesets mentioning "bug" or "issue" that are not in a tagged re‐
7046 lease:
7047 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
7049 • Update to the commit that bookmark @ is pointing to, without activat‐
7051 ing the bookmark (this works because the last revision of the revset
7052 is used):
7053 hg update :@
7055 • Show diff between tags 1.3 and 1.5 (this works because the first and
7057 the last revisions of the revset are used):
7058 hg diff -r 1.3::1.5
7060
7062 Mercurial can be augmented with Rust extensions for speeding up certain
7063 operations.
7064 Compatibility
7066 Though the Rust extensions are only tested by the project under Linux,
7067 users of MacOS, FreeBSD and other UNIX-likes have been using the Rust
7068 extensions. Your mileage may vary, but by all means do give us feedback
7069 or signal your interest for better support.
7070 No Rust extensions are available for Windows at this time.
7072 Features
7074 The following operations are sped up when using Rust:
7075 • discovery of differences between repositories (pull/push)
7077 • nodemap (see hg help config.format.use-persistent-nodemap)
7079 • all commands using the dirstate (status, commit, diff, add, up‐
7081 date, etc.)
7082 • dirstate-v2 (see hg help config.format.use-dirstate-v2)
7084 • iteration over ancestors in a graph
7086 More features are in the works, and improvements on the above listed
7088 are still in progress. For more experimental work see the "rhg" sec‐
7089 tion.
7090 Checking for Rust
7092 You may already have the Rust extensions depending on how you install
7093 Mercurial:
7094 $ hg debuginstall | grep -i rust
7096 checking Rust extensions (installed)
7097 checking module policy (rust+c-allow)
7098 If those lines don't even exist, you're using an old version of hg
7100 which does not have any Rust extensions yet.
7101 Installing
7103 You will need cargo to be in your $PATH. See the "MSRV" section for
7104 which version to use.
7105 Using pip
7107 Users of pip can install the Rust extensions with the following com‐
7108 mand:
7109 $ pip install mercurial --global-option --rust --no-use-pep517
7111 --no-use-pep517 is here to tell pip to preserve backwards compatibility
7113 with the legacy setup.py system. Mercurial has not yet migrated its
7114 complex setup to the new system, so we still need this to add compiled
7115 extensions.
7116 This might take a couple of minutes because you're compiling every‐
7118 thing.
7119 See the "Checking for Rust" section to see if the install succeeded.
7121 From your distribution
7123 Some distributions are shipping Mercurial with Rust extensions enabled
7124 and pre-compiled (meaning you won't have to install cargo), or allow
7125 you to specify an install flag. Check with your specific distribution
7126 for how to do that, or ask their team to add support for hg+Rust!
7127 From source
7129 Please refer to the rust/README.rst file in the Mercurial repository
7130 for instructions on how to install from source.
7131 MSRV
7133 The minimum supported Rust version is currently 1.48.0. The project's
7134 policy is to follow the version from Debian stable, to make the distri‐
7135 butions' job easier.
7136 rhg
7138 There exists an experimental pure-Rust version of Mercurial called rhg
7139 with a fallback mechanism for unsupported invocations. It allows for
7140 much faster execution of certain commands while adding no discernable
7141 overhead for the rest.
7142 The only way of trying it out is by building it from source. Please re‐
7144 fer to rust/README.rst in the Mercurial repository.
7145 Contributing
7147 If you would like to help the Rust endeavor, please refer to
7148 rust/README.rst in the Mercurial repository.
7149
7151 It is common for machines (as opposed to humans) to consume Mercurial.
7152 This help topic describes some of the considerations for interfacing
7153 machines with Mercurial.
7154 Choosing an Interface
7156 Machines have a choice of several methods to interface with Mercurial.
7157 These include:
7158 • Executing the hg process
7160 • Querying a HTTP server
7162 • Calling out to a command server
7164 Executing hg processes is very similar to how humans interact with Mer‐
7166 curial in the shell. It should already be familiar to you.
7167 hg serve can be used to start a server. By default, this will start a
7169 "hgweb" HTTP server. This HTTP server has support for machine-readable
7170 output, such as JSON. For more, see hg help hgweb.
7171 hg serve can also start a "command server." Clients can connect to this
7173 server and issue Mercurial commands over a special protocol. For more
7174 details on the command server, including links to client libraries, see
7175 https://www.mercurial-scm.org/wiki/CommandServer.
7176 hg serve based interfaces (the hgweb and command servers) have the ad‐
7178 vantage over simple hg process invocations in that they are likely more
7179 efficient. This is because there is significant overhead to spawn new
7180 Python processes.
7181 Tip If you need to invoke several hg processes in short order and/or
7183 performance is important to you, use of a server-based interface
7184 is highly recommended.
7185 Environment Variables
7187 As documented in hg help environment, various environment variables in‐
7188 fluence the operation of Mercurial. The following are particularly rel‐
7189 evant for machines consuming Mercurial:
7190 HGPLAIN
7192 If not set, Mercurial's output could be influenced by configura‐
7193 tion settings that impact its encoding, verbose mode, localiza‐
7194 tion, etc.
7195 It is highly recommended for machines to set this variable when
7197 invoking hg processes.
7198 HGENCODING
7200 If not set, the locale used by Mercurial will be detected from
7201 the environment. If the determined locale does not support dis‐
7202 play of certain characters, Mercurial may render these character
7203 sequences incorrectly (often by using "?" as a placeholder for
7204 invalid characters in the current locale).
7205 Explicitly setting this environment variable is a good practice
7207 to guarantee consistent results. "utf-8" is a good choice on
7208 UNIX-like environments.
7209 HGRCPATH
7211 If not set, Mercurial will inherit config options from config
7212 files using the process described in hg help config. This in‐
7213 cludes inheriting user or system-wide config files.
7214 When utmost control over the Mercurial configuration is desired,
7216 the value of HGRCPATH can be set to an explicit file with known
7217 good configs. In rare cases, the value can be set to an empty
7218 file or the null device (often /dev/null) to bypass loading of
7219 any user or system config files. Note that these approaches can
7220 have unintended consequences, as the user and system config
7221 files often define things like the username and extensions that
7222 may be required to interface with a repository.
7223 HGRCSKIPREPO
7225 When set, the .hg/hgrc from repositories are not read.
7226 Note that not reading the repository's configuration can have
7228 unintended consequences, as the repository config files can de‐
7229 fine things like extensions that are required for access to the
7230 repository.
7231 Command-line Flags
7233 Mercurial's default command-line parser is designed for humans, and is
7234 not robust against malicious input. For instance, you can start a de‐
7235 bugger by passing --debugger as an option value:
7236 $ REV=--debugger sh -c 'hg log -r "$REV"'
7238 This happens because several command-line flags need to be scanned
7240 without using a concrete command table, which may be modified while
7241 loading repository settings and extensions.
7242 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
7244 setting HGPLAIN=+strictflags. When this feature is enabled, all early
7245 options (e.g. -R/--repository, --cwd, --config) must be specified first
7246 amongst the other global options, and cannot be injected to an arbi‐
7247 trary location:
7248 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
7250 In earlier Mercurial versions where +strictflags isn't available, you
7252 can mitigate the issue by concatenating an option value with its flag:
7253 $ hg log -r"$REV" --keyword="$KEYWORD"
7255 Consuming Command Output
7257 It is common for machines to need to parse the output of Mercurial com‐
7258 mands for relevant data. This section describes the various techniques
7259 for doing so.
7260 Parsing Raw Command Output
7262 Likely the simplest and most effective solution for consuming command
7263 output is to simply invoke hg commands as you would as a user and parse
7264 their output.
7265 The output of many commands can easily be parsed with tools like grep,
7267 sed, and awk.
7268 A potential downside with parsing command output is that the output of
7270 commands can change when Mercurial is upgraded. While Mercurial does
7271 generally strive for strong backwards compatibility, command output
7272 does occasionally change. Having tests for your automated interactions
7273 with hg commands is generally recommended, but is even more important
7274 when raw command output parsing is involved.
7275 Using Templates to Control Output
7277 Many hg commands support templatized output via the -T/--template argu‐
7278 ment. For more, see hg help templates.
7279 Templates are useful for explicitly controlling output so that you get
7281 exactly the data you want formatted how you want it. For example, log
7282 -T {node}\n can be used to print a newline delimited list of changeset
7283 nodes instead of a human-tailored output containing authors, dates, de‐
7284 scriptions, etc.
7285 Tip If parsing raw command output is too complicated, consider using
7287 templates to make your life easier.
7288 The -T/--template argument allows specifying pre-defined styles. Mer‐
7290 curial ships with the machine-readable styles cbor, json, and xml,
7291 which provide CBOR, JSON, and XML output, respectively. These are use‐
7292 ful for producing output that is machine readable as-is.
7293 (Mercurial 5.0 is required for CBOR style.)
7295 Important
7297 The json and xml styles are considered experimental. While they
7298 may be attractive to use for easily obtaining machine-readable
7299 output, their behavior may change in subsequent versions.
7300 These styles may also exhibit unexpected results when dealing
7302 with certain encodings. Mercurial treats things like filenames
7303 as a series of bytes and normalizing certain byte sequences to
7304 JSON or XML with certain encoding settings can lead to sur‐
7305 prises.
7306 Command Server Output
7308 If using the command server to interact with Mercurial, you are likely
7309 using an existing library/API that abstracts implementation details of
7310 the command server. If so, this interface layer may perform parsing for
7311 you, saving you the work of implementing it yourself.
7312 Output Verbosity
7314 Commands often have varying output verbosity, even when machine read‐
7315 able styles are being used (e.g. -T json). Adding -v/--verbose and
7316 --debug to the command's arguments can increase the amount of data ex‐
7317 posed by Mercurial.
7318 An alternate way to get the data you need is by explicitly specifying a
7320 template.
7321 Other Topics
7323 revsets
7324 Revisions sets is a functional query language for selecting a
7325 set of revisions. Think of it as SQL for Mercurial repositories.
7326 Revsets are useful for querying repositories for specific data.
7327 See hg help revsets for more.
7329 share extension
7331 The share extension provides functionality for sharing reposi‐
7332 tory data across several working copies. It can even automati‐
7333 cally "pool" storage for logically related repositories when
7334 cloning.
7335 Configuring the share extension can lead to significant resource
7337 utilization reduction, particularly around disk space and the
7338 network. This is especially true for continuous integration (CI)
7339 environments.
7340 See hg help -e share for more.
7342
7344 Subrepositories let you nest external repositories or projects into a
7345 parent Mercurial repository, and make commands operate on them as a
7346 group.
7347 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
7349 tories.
7350 Subrepositories are made of three components:
7352 1. Nested repository checkouts. They can appear anywhere in the parent
7354 working directory.
7355 2. Nested repository references. They are defined in .hgsub, which
7357 should be placed in the root of working directory, and tell where
7358 the subrepository checkouts come from. Mercurial subrepositories are
7359 referenced like:
7360 path/to/nested = https://example.com/nested/repo/path
7362 Git and Subversion subrepos are also supported:
7364 path/to/nested = [git]git://example.com/nested/repo/path
7366 path/to/nested = [svn]https://example.com/nested/trunk/path
7367 where path/to/nested is the checkout location relatively to the par‐
7369 ent Mercurial root, and https://example.com/nested/repo/path is the
7370 source repository path. The source can also reference a filesystem
7371 path.
7372 Note that .hgsub does not exist by default in Mercurial reposito‐
7374 ries, you have to create and add it to the parent repository before
7375 using subrepositories.
7376 3. Nested repository states. They are defined in .hgsubstate, which is
7378 placed in the root of working directory, and capture whatever infor‐
7379 mation is required to restore the subrepositories to the state they
7380 were committed in a parent repository changeset. Mercurial automati‐
7381 cally record the nested repositories states when committing in the
7382 parent repository.
7383 Note
7385 The .hgsubstate file should not be edited manually.
7386 Adding a Subrepository
7388 If .hgsub does not exist, create it and add it to the parent reposi‐
7389 tory. Clone or checkout the external projects where you want it to live
7390 in the parent repository. Edit .hgsub and add the subrepository entry
7391 as described above. At this point, the subrepository is tracked and the
7392 next commit will record its state in .hgsubstate and bind it to the
7393 committed changeset.
7394 Synchronizing a Subrepository
7396 Subrepos do not automatically track the latest changeset of their
7397 sources. Instead, they are updated to the changeset that corresponds
7398 with the changeset checked out in the top-level changeset. This is so
7399 developers always get a consistent set of compatible code and libraries
7400 when they update.
7401 Thus, updating subrepos is a manual process. Simply check out target
7403 subrepo at the desired revision, test in the top-level repo, then com‐
7404 mit in the parent repository to record the new combination.
7405 Deleting a Subrepository
7407 To remove a subrepository from the parent repository, delete its refer‐
7408 ence from .hgsub, then remove its files.
7409 Interaction with Mercurial Commands
7411 add add does not recurse in subrepos unless -S/--subrepos is speci‐
7412 fied. However, if you specify the full path of a file in a sub‐
7413 repo, it will be added even without -S/--subrepos specified.
7414 Subversion subrepositories are currently silently ignored.
7415 addremove
7417 addremove does not recurse into subrepos unless -S/--subrepos is
7418 specified. However, if you specify the full path of a directory
7419 in a subrepo, addremove will be performed on it even without
7420 -S/--subrepos being specified. Git and Subversion subreposito‐
7421 ries will print a warning and continue.
7422 archive
7424 archive does not recurse in subrepositories unless -S/--subrepos
7425 is specified.
7426 cat Git subrepositories only support exact file matches. Subversion
7428 subrepositories are currently ignored.
7429 commit commit creates a consistent snapshot of the state of the entire
7431 project and its subrepositories. If any subrepositories have
7432 been modified, Mercurial will abort. Mercurial can be made to
7433 instead commit all modified subrepositories by specifying
7434 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
7435 ration file (see hg help config). After there are no longer any
7436 modified subrepositories, it records their state and finally
7437 commits it in the parent repository. The --addremove option
7438 also honors the -S/--subrepos option. However, Git and Subver‐
7439 sion subrepositories will print a warning and abort.
7440 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
7442 fied. However, if you specify the full path of a file or direc‐
7443 tory in a subrepo, it will be diffed even without -S/--subrepos
7444 being specified. Subversion subrepositories are currently
7445 silently ignored.
7446 files files does not recurse into subrepos unless -S/--subrepos is
7448 specified. However, if you specify the full path of a file or
7449 directory in a subrepo, it will be displayed even without
7450 -S/--subrepos being specified. Git and Subversion subreposito‐
7451 ries are currently silently ignored.
7452 forget forget currently only handles exact file matches in subrepos.
7454 Git and Subversion subrepositories are currently silently ig‐
7455 nored.
7456 incoming
7458 incoming does not recurse in subrepos unless -S/--subrepos is
7459 specified. Git and Subversion subrepositories are currently
7460 silently ignored.
7461 outgoing
7463 outgoing does not recurse in subrepos unless -S/--subrepos is
7464 specified. Git and Subversion subrepositories are currently
7465 silently ignored.
7466 pull pull is not recursive since it is not clear what to pull prior
7468 to running hg update. Listing and retrieving all subrepositories
7469 changes referenced by the parent repository pulled changesets is
7470 expensive at best, impossible in the Subversion case.
7471 push Mercurial will automatically push all subrepositories first when
7473 the parent repository is being pushed. This ensures new sub‐
7474 repository changes are available when referenced by top-level
7475 repositories. Push is a no-op for Subversion subrepositories.
7476 serve serve does not recurse into subrepositories unless -S/--subrepos
7478 is specified. Git and Subversion subrepositories are currently
7479 silently ignored.
7480 status status does not recurse into subrepositories unless -S/--subre‐
7482 pos is specified. Subrepository changes are displayed as regular
7483 Mercurial changes on the subrepository elements. Subversion sub‐
7484 repositories are currently silently ignored.
7485 remove remove does not recurse into subrepositories unless -S/--subre‐
7487 pos is specified. However, if you specify a file or directory
7488 path in a subrepo, it will be removed even without -S/--subre‐
7489 pos. Git and Subversion subrepositories are currently silently
7490 ignored.
7491 update update restores the subrepos in the state they were originally
7493 committed in target changeset. If the recorded changeset is not
7494 available in the current subrepository, Mercurial will pull it
7495 in first before updating. This means that updating can require
7496 network access when using subrepositories.
7497 Remapping Subrepositories Sources
7499 A subrepository source location may change during a project life, in‐
7500 validating references stored in the parent repository history. To fix
7501 this, rewriting rules can be defined in parent repository hgrc file or
7502 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
7503 more details.
7504
7506 Mercurial allows you to customize output of commands through templates.
7507 You can either pass in a template or select an existing template-style
7508 from the command line, via the --template option.
7509 You can customize output for any "log-like" command: log, outgoing, in‐
7511 coming, tip, parents, and heads.
7512 Some built-in styles are packaged with Mercurial. These can be listed
7514 with hg log --template list. Example usage:
7515 $ hg log -r1.0::1.1 --template changelog
7517 A template is a piece of text, with markup to invoke variable expan‐
7519 sion:
7520 $ hg log -r1 --template "{node}\n"
7522 b56ce7b07c52de7d5fd79fb89701ea538af65746
7523 Keywords
7525 Strings in curly braces are called keywords. The availability of key‐
7526 words depends on the exact context of the templater. These keywords are
7527 usually available for templating a log-like command:
7528 _fast_rank
7530 the rank of a changeset if cached
7531 The rank of a revision is the size of the sub-graph it defines
7533 as a head. Equivalently, the rank of a revision r is the size
7534 of the set ancestors(r), r included.
7535 activebookmark
7537 String. The active bookmark, if it is associated with the
7538 changeset.
7539 author Alias for {user}
7541 bisect String. The changeset bisection status.
7543 bookmarks
7545 List of strings. Any bookmarks associated with the changeset.
7546 Also sets 'active', the name of the active bookmark.
7547 branch String. The name of the branch on which the changeset was com‐
7549 mitted.
7550 changessincelatesttag
7552 Integer. All ancestors not in the latest tag.
7553 children
7555 List of strings. The children of the changeset.
7556 date Date information. The date when the changeset was committed.
7558 desc String. The text of the changeset description.
7560 diffstat
7562 String. Statistics of changes with the following format: "modi‐
7563 fied files: +added/-removed lines"
7564 extras List of dicts with key, value entries of the 'extras' field of
7566 this changeset.
7567 file_adds
7569 List of strings. Files added by this changeset.
7570 file_copies
7572 List of strings. Files copied in this changeset with their
7573 sources.
7574 file_copies_switch
7576 List of strings. Like "file_copies" but displayed only if the
7577 --copied switch is set.
7578 file_dels
7580 List of strings. Files removed by this changeset.
7581 file_mods
7583 List of strings. Files modified by this changeset.
7584 files List of strings. All files modified, added, or removed by this
7586 changeset.
7587 graphnode
7589 String. The character representing the changeset node in an
7590 ASCII revision graph.
7591 graphwidth
7593 Integer. The width of the graph drawn by 'log --graph' or zero.
7594 index Integer. The current iteration of the loop. (0 indexed)
7596 latesttag
7598 List of strings. The global tags on the most recent globally
7599 tagged ancestor of this changeset. If no such tags exist, the
7600 list consists of the single string "null".
7601 latesttagdistance
7603 Integer. Longest path to the latest tag.
7604 namespaces
7606 Dict of lists. Names attached to this changeset per namespace.
7607 negrev Integer. The repository-local changeset negative revision num‐
7609 ber, which counts in the opposite direction.
7610 node String. The changeset identification hash, as a 40 hexadecimal
7612 digit string.
7613 onelinesummary
7615 String. A one-line summary for the ctx (not including trailing
7616 newline). The default template be overridden in command-tem‐
7617 plates.oneline-summary.
7618 p1 Changeset. The changeset's first parent. {p1.rev} for the revi‐
7620 sion number, and {p1.node} for the identification hash.
7621 p2 Changeset. The changeset's second parent. {p2.rev} for the revi‐
7623 sion number, and {p2.node} for the identification hash.
7624 parents
7626 List of strings. The parents of the changeset in "rev:node" for‐
7627 mat. If the changeset has only one "natural" parent (the prede‐
7628 cessor revision) nothing is shown.
7629 peerurls
7631 A dictionary of repository locations defined in the [paths] sec‐
7632 tion of your configuration file.
7633 phase String. The changeset phase name.
7635 reporoot
7637 String. The root directory of the current repository.
7638 rev Integer. The repository-local changeset revision number.
7640 subrepos
7642 List of strings. Updated subrepositories in the changeset.
7643 tags List of strings. Any tags associated with the changeset.
7645 termwidth
7647 Integer. The width of the current terminal.
7648 user String. The unmodified author of the changeset.
7650 verbosity
7652 String. The current output verbosity in 'debug', 'quiet', 'ver‐
7653 bose', or ''.
7654 The "date" keyword does not produce human-readable output. If you want
7656 to use a date in your output, you can use a filter to process it. Fil‐
7657 ters are functions which return a string based on the input variable.
7658 Be sure to use the stringify filter first when you're applying a
7659 string-input filter to a list-like input variable. You can also use a
7660 chain of filters to get the desired output:
7661 $ hg tip --template "{date|isodate}\n"
7663 2008-08-21 18:22 +0000
7664 Filters
7666 List of filters:
7667 addbreaks
7669 Any text. Add an XHTML "<br />" tag before the end of every line
7670 except the last.
7671 age Date. Returns a human-readable date/time difference between the
7673 given date/time and the current date/time.
7674 basename
7676 Any text. Treats the text as a path, and returns the last compo‐
7677 nent of the path after splitting by the path separator. For ex‐
7678 ample, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
7679 cbor Any object. Serializes the object to CBOR bytes.
7681 commondir
7683 List of text. Treats each list item as file name with / as path
7684 separator and returns the longest common directory prefix shared
7685 by all list items. Returns the empty string if no common prefix
7686 exists.
7687 The list items are not normalized, i.e. "foo/../bar" is handled
7689 as file "bar" in the directory "foo/..". Leading slashes are ig‐
7690 nored.
7691 For example, ["foo/bar/baz", "foo/baz/bar"] becomes "foo" and
7693 ["foo/bar", "baz"] becomes "".
7694 count List or text. Returns the length as an integer.
7696 dirname
7698 Any text. Treats the text as a path, and strips the last compo‐
7699 nent of the path after splitting by the path separator.
7700 domain Any text. Finds the first string that looks like an email ad‐
7702 dress, and extracts just the domain component. Example: User
7703 <user@example.com> becomes example.com.
7704 email Any text. Extracts the first string that looks like an email ad‐
7706 dress. Example: User <user@example.com> becomes user@exam‐
7707 ple.com.
7708 emailuser
7710 Any text. Returns the user portion of an email address.
7711 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
7713 ">" with XML entities, and filters out NUL characters.
7714 fill68 Any text. Wraps the text to fit in 68 columns.
7716 fill76 Any text. Wraps the text to fit in 76 columns.
7718 firstline
7720 Any text. Returns the first line of text.
7721 hex Any text. Convert a binary Mercurial node identifier into its
7723 long hexadecimal representation.
7724 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
7726 (Unix timestamp, timezone offset).
7727 isodate
7729 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
7730 +0200".
7731 isodatesec
7733 Date. Returns the date in ISO 8601 format, including seconds:
7734 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
7735 json Any object. Serializes the object to a JSON formatted text.
7737 lower Any text. Converts the text to lowercase.
7739 nonempty
7741 Any text. Returns '(none)' if the string is empty.
7742 obfuscate
7744 Any text. Returns the input text rendered as a sequence of XML
7745 entities.
7746 person Any text. Returns the name before an email address, interpreting
7748 it as per RFC 5322.
7749 revescape
7751 Any text. Escapes all "special" characters, except @. Forward
7752 slashes are escaped twice to prevent web servers from prema‐
7753 turely unescaping them. For example, "@foo bar/baz" becomes
7754 "@foo%20bar%252Fbaz".
7755 rfc3339date
7757 Date. Returns a date using the Internet date format specified in
7758 RFC 3339: "2009-08-18T13:00:13+02:00".
7759 rfc822date
7761 Date. Returns a date using the same format used in email head‐
7762 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
7763 short Changeset hash. Returns the short form of a changeset hash, i.e.
7765 a 12 hexadecimal digit string.
7766 shortbisect
7768 Any text. Treats label as a bisection status, and returns a sin‐
7769 gle-character representing the status (G: good, B: bad, S:
7770 skipped, U: untested, I: ignored). Returns single space if text
7771 is not a valid bisection status.
7772 shortdate
7774 Date. Returns a date like "2006-09-18".
7775 slashpath
7777 Any text. Replaces the native path separator with slash.
7778 splitlines
7780 Any text. Split text into a list of lines.
7781 stringify
7783 Any type. Turns the value into text by converting values into
7784 text and concatenating them.
7785 stripdir
7787 Treat the text as path and strip a directory level, if possible.
7788 For example, "foo" and "foo/bar" becomes "foo".
7789 tabindent
7791 Any text. Returns the text, with every non-empty line except the
7792 first starting with a tab character.
7793 upper Any text. Converts the text to uppercase.
7795 urlescape
7797 Any text. Escapes all "special" characters. For example, "foo
7798 bar" becomes "foo%20bar".
7799 user Any text. Returns a short representation of a user name or email
7801 address.
7802 utf8 Any text. Converts from the local character encoding to UTF-8.
7804 Note that a filter is nothing more than a function call, i.e.
7806 expr|filter is equivalent to filter(expr).
7807 Functions
7809 In addition to filters, there are some basic built-in functions:
7810 config(section, name[, default])
7812 Returns the requested hgrc config option as a string.
7813 configbool(section, name[, default])
7815 Returns the requested hgrc config option as a boolean.
7816 configint(section, name[, default])
7818 Returns the requested hgrc config option as an integer.
7819 date(date[, fmt])
7821 Format a date. See hg help dates for formatting strings. The de‐
7822 fault is a Unix date format, including the timezone: "Mon Sep 04
7823 15:13:13 2006 0700".
7824 dict([[key=]value...])
7826 Construct a dict from key-value pairs. A key may be omitted if a
7827 value expression can provide an unambiguous name.
7828 diff([includepattern [, excludepattern]])
7830 Show a diff, optionally specifying files to include or exclude.
7831 files(pattern)
7833 All files of the current changeset matching the pattern. See hg
7834 help patterns.
7835 fill(text[, width[, initialident[, hangindent]]])
7837 Fill many paragraphs with optional indentation. See the "fill"
7838 filter.
7839 filter(iterable[, expr])
7841 Remove empty elements from a list or a dict. If expr specified,
7842 it's applied to each element to test emptiness.
7843 get(dict, key)
7845 Get an attribute/key from an object. Some keywords are complex
7846 types. This function allows you to obtain the value of an attri‐
7847 bute on these types.
7848 if(expr, then[, else])
7850 Conditionally execute based on the result of an expression.
7851 ifcontains(needle, haystack, then[, else])
7853 Conditionally execute based on whether the item "needle" is in
7854 "haystack".
7855 ifeq(expr1, expr2, then[, else])
7857 Conditionally execute based on whether 2 items are equivalent.
7858 indent(text, indentchars[, firstline])
7860 Indents all non-empty lines with the characters given in the in‐
7861 dentchars string. An optional third parameter will override the
7862 indent for the first line only if present.
7863 join(list, sep)
7865 Join items in a list with a delimiter.
7866 label(label, expr)
7868 Apply a label to generated content. Content with a label applied
7869 can result in additional post-processing, such as automatic col‐
7870 orization.
7871 latesttag([pattern])
7873 The global tags matching the given pattern on the most recent
7874 globally tagged ancestor of this changeset. If no such tags ex‐
7875 ist, the "{tag}" template resolves to the string "null". See hg
7876 help revisions.patterns for the pattern syntax.
7877 localdate(date[, tz])
7879 Converts a date to the specified timezone. The default is local
7880 date.
7881 mailmap(author)
7883 Return the author, updated according to the value set in the
7884 .mailmap file
7885 max(iterable)
7887 Return the max of an iterable
7888 min(iterable)
7890 Return the min of an iterable
7891 mod(a, b)
7893 Calculate a mod b such that a / b + a mod b == a
7894 pad(text, width[, fillchar=' '[, left=False[, truncate=False]]])
7896 Pad text with a fill character.
7897 relpath(path)
7899 Convert a repository-absolute path into a filesystem path rela‐
7900 tive to the current working directory.
7901 revset(query[, formatargs...])
7903 Execute a revision set query. See hg help revset.
7904 rstdoc(text, style)
7906 Format reStructuredText.
7907 search(pattern, text)
7909 Look for the first text matching the regular expression pattern.
7910 Groups are accessible as {1}, {2}, ... in %-mapped template.
7911 separate(sep, args...)
7913 Add a separator between non-empty arguments.
7914 shortest(node, minlength=4)
7916 Obtain the shortest representation of a node.
7917 startswith(pattern, text)
7919 Returns the value from the "text" argument if it begins with the
7920 content from the "pattern" argument.
7921 strip(text[, chars])
7923 Strip characters from a string. By default, strips all leading
7924 and trailing whitespace.
7925 sub(pattern, replacement, expression)
7927 Perform text substitution using regular expressions.
7928 subsetparents(rev, revset)
7930 Look up parents of the rev in the sub graph given by the revset.
7931 word(number, text[, separator])
7933 Return the nth word from a string.
7934 Operators
7936 We provide a limited set of infix arithmetic operations on integers:
7937 + for addition
7939 - for subtraction
7940 * for multiplication
7941 / for floor division (division rounded to integer nearest -infinity)
7942 Division fulfills the law x = x / y + mod(x, y).
7944 Also, for any expression that returns a list, there is a list operator:
7946 expr % "{template}"
7948 As seen in the above example, {template} is interpreted as a template.
7950 To prevent it from being interpreted, you can use an escape character
7951 \{ or a raw string prefix, r'...'.
7952 The dot operator can be used as a shorthand for accessing a sub item:
7954 • expr.member is roughly equivalent to expr % '{member}' if expr re‐
7956 turns a non-list/dict. The returned value is not stringified.
7957 • dict.key is identical to get(dict, 'key').
7959 Aliases
7961 New keywords and functions can be defined in the templatealias section
7962 of a Mercurial configuration file:
7963 <alias> = <definition>
7965 Arguments of the form a1, a2, etc. are substituted from the alias into
7967 the definition.
7968 For example,
7970 [templatealias]
7972 r = rev
7973 rn = "{r}:{node|short}"
7974 leftpad(s, w) = pad(s, w, ' ', True)
7975 defines two symbol aliases, r and rn, and a function alias leftpad().
7977 It's also possible to specify complete template strings, using the tem‐
7979 plates section. The syntax used is the general template string syntax.
7980 For example,
7982 [templates]
7984 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
7985 defines a template, nodedate, which can be called like:
7987 $ hg log -r . -Tnodedate
7989 A template defined in templates section can also be referenced from an‐
7991 other template:
7992 $ hg log -r . -T "{rev} {nodedate}"
7994 but be aware that the keywords cannot be overridden by templates. For
7996 example, a template defined as templates.rev cannot be referenced as
7997 {rev}.
7998 A template defined in templates section may have sub templates which
8000 are inserted before/after/between items:
8001 [templates]
8003 myjson = ' {dict(rev, node|short)|json}'
8004 myjson:docheader = '\{\n'
8005 myjson:docfooter = '\n}\n'
8006 myjson:separator = ',\n'
8007 Examples
8009 Some sample command line templates:
8010 • Format lists, e.g. files:
8012 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
8014 • Join the list of files with a ", ":
8016 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
8018 • Join the list of files ending with ".py" with a ", ":
8020 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
8022 • Separate non-empty arguments by a " ":
8024 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
8026 • Modify each line of a commit description:
8028 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
8030 • Format date:
8032 $ hg log -r 0 --template "{date(date, '%Y')}\n"
8034 • Display date in UTC:
8036 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
8038 • Output the description set to a fill-width of 30:
8040 $ hg log -r 0 --template "{fill(desc, 30)}"
8042 • Use a conditional to test for the default branch:
8044 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
8046 'on branch {branch}')}\n"
8047 • Append a newline if not empty:
8049 $ hg tip --template "{if(author, '{author}\n')}"
8051 • Label the output for use with the color extension:
8053 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
8055 • Invert the firstline filter, i.e. everything but the first line:
8057 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
8059 • Display the contents of the 'extra' field, one per line:
8061 $ hg log -r 0 --template "{join(extras, '\n')}\n"
8063 • Mark the active bookmark with '*':
8065 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
8067 • Find the previous release candidate tag, the distance and changes
8069 since the tag:
8070 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
8072 • Mark the working copy parent with '@':
8074 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
8076 • Show details of parent revisions:
8078 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
8080 • Show only commit descriptions that start with "template":
8082 $ hg log --template "{startswith('template', firstline(desc))}\n"
8084 • Print the first word of each line of a commit message:
8086 $ hg log --template "{word(0, desc)}\n"
8088
8090 Valid URLs are of the form:
8091 local/filesystem/path[#revision]
8093 file://local/filesystem/path[#revision]
8094 http://[user[:pass]@]host[:port]/[path][#revision]
8095 https://[user[:pass]@]host[:port]/[path][#revision]
8096 ssh://[user@]host[:port]/[path][#revision]
8097 path://pathname
8098 Paths in the local filesystem can either point to Mercurial reposito‐
8100 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
8101 dle). See also hg help paths.
8102 An optional identifier after # indicates a particular branch, tag, or
8104 changeset to use from the remote repository. See also hg help revisions
8105 .
8106 Some features, such as pushing to http:// and https:// URLs are only
8108 possible if the feature is explicitly enabled on the remote Mercurial
8109 server.
8110 Note that the security of HTTPS URLs depends on proper configuration of
8112 web.cacerts.
8113 Some notes about using SSH with Mercurial:
8115 • SSH requires an accessible shell account on the destination machine
8117 and a copy of hg in the remote path or specified with remotecmd.
8118 • path is relative to the remote user's home directory by default. Use
8120 an extra slash at the start of a path to specify an absolute path:
8121 ssh://example.com//tmp/repository
8123 • Mercurial doesn't use its own compression via SSH; the right thing to
8125 do is to configure it in your ~/.ssh/config, e.g.:
8126 Host *.mylocalnetwork.example.com
8128 Compression no
8129 Host *
8130 Compression yes
8131 Alternatively specify "ssh -C" as your ssh command in your configura‐
8133 tion file or with the --ssh command line option.
8134 These URLs can all be stored in your configuration file with path
8136 aliases under the [paths] section like so:
8137 [paths]
8139 alias1 = URL1
8140 alias2 = URL2
8141 ...
8142 You can then use the alias for any command that uses a URL (for example
8144 hg pull alias1 will be treated as hg pull URL1).
8145 Two path aliases are special because they are used as defaults when you
8147 do not provide the URL to a command:
8148 default:
8150 When you create a repository with hg clone, the clone command
8151 saves the location of the source repository as the new reposi‐
8152 tory's 'default' path. This is then used when you omit path from
8153 push- and pull-like commands (including incoming and outgoing).
8154 default-push:
8156 The push command will look for a path named 'default-push', and
8157 prefer it over 'default' if both are defined.
8158 These alias can also be use in the path:// scheme:
8160 [paths]
8162 alias1 = URL1
8163 alias2 = path://alias1
8164 ...
8165 check hg help config.paths for details about the behavior of such
8167 "sub-path".
8168
8170 This section contains help for extensions that are distributed together
8171 with Mercurial. Help for other extensions is available in the help sys‐
8172 tem.
8173 absorb
8175 apply working directory changes to changesets (EXPERIMENTAL)
8176 The absorb extension provides a command to use annotate information to
8178 amend modified chunks into the corresponding non-public changesets.
8179 [absorb]
8181 # only check 50 recent non-public changesets at most
8182 max-stack-size = 50
8183 # whether to add noise to new commits to avoid obsolescence cycle
8184 add-noise = 1
8185 # make `amend --correlated` a shortcut to the main command
8186 amend-flag = correlated
8187 [color]
8189 absorb.description = yellow
8190 absorb.node = blue bold
8191 absorb.path = bold
8192 Commands
8194 Change creation
8195 absorb
8196 incorporate corrections into the stack of draft changesets:
8197 hg absorb [OPTION] [FILE]...
8199 absorb analyzes each change in your working directory and attempts to
8201 amend the changed lines into the changesets in your stack that first
8202 introduced those lines.
8203 If absorb cannot find an unambiguous changeset to amend for a change,
8205 that change will be left in the working directory, untouched. They can
8206 be observed by hg status or hg diff afterwards. In other words, absorb
8207 does not write to the working directory.
8208 Changesets outside the revset ::. and not public() and not merge() will
8210 not be changed.
8211 Changesets that become empty after applying the changes will be
8213 deleted.
8214 By default, absorb will show what it plans to do and prompt for confir‐
8216 mation. If you are confident that the changes will be absorbed to the
8217 correct place, run hg absorb -a to apply the changes immediately.
8218 Returns 0 on success, 1 if all chunks were ignored and nothing amended.
8220 Options:
8222 -a, --apply-changes
8224 apply changes without prompting for confirmation
8225 -p, --print-changes
8227 always print which changesets are modified by which changes
8228 -i, --interactive
8230 interactively select which chunks to apply
8231 -e, --edit-lines
8233 edit what lines belong to which changesets before commit (EXPER‐
8234 IMENTAL)
8235 -n, --dry-run
8237 do not perform actions, just print output
8238 --style <STYLE>
8240 display using template map file (DEPRECATED)
8241 -T,--template <TEMPLATE>
8243 display with template
8244 -I,--include <PATTERN[+]>
8246 include names matching the given patterns
8247 -X,--exclude <PATTERN[+]>
8249 exclude names matching the given patterns
8250 [+] marked option can be specified multiple times
8252 acl
8254 hooks for controlling repository access
8255 This hook makes it possible to allow or deny write access to given
8257 branches and paths of a repository when receiving incoming changesets
8258 via pretxnchangegroup and pretxncommit.
8259 The authorization is matched based on the local user name on the system
8261 where the hook runs, and not the committer of the original changeset
8262 (since the latter is merely informative).
8263 The acl hook is best used along with a restricted shell like hgsh, pre‐
8265 venting authenticating users from doing anything other than pushing or
8266 pulling. The hook is not safe to use if users have interactive shell
8267 access, as they can then disable the hook. Nor is it safe if remote
8268 users share an account, because then there is no way to distinguish
8269 them.
8270 The order in which access checks are performed is:
8272 1. Deny list for branches (section acl.deny.branches)
8274 2. Allow list for branches (section acl.allow.branches)
8276 3. Deny list for paths (section acl.deny)
8278 4. Allow list for paths (section acl.allow)
8280 The allow and deny sections take key-value pairs.
8282 Branch-based Access Control
8284 Use the acl.deny.branches and acl.allow.branches sections to have
8285 branch-based access control. Keys in these sections can be either:
8286 • a branch name, or
8288 • an asterisk, to match any branch;
8290 The corresponding values can be either:
8292 • a comma-separated list containing users and groups, or
8294 • an asterisk, to match anyone;
8296 You can add the "!" prefix to a user or group name to invert the sense
8298 of the match.
8299 Path-based Access Control
8301 Use the acl.deny and acl.allow sections to have path-based access con‐
8302 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
8303 tax by default). The corresponding values follow the same syntax as the
8304 other sections above.
8305 Bookmark-based Access Control
8307 Use the acl.deny.bookmarks and acl.allow.bookmarks sections to have
8308 bookmark-based access control. Keys in these sections can be either:
8309 • a bookmark name, or
8311 • an asterisk, to match any bookmark;
8313 The corresponding values can be either:
8315 • a comma-separated list containing users and groups, or
8317 • an asterisk, to match anyone;
8319 You can add the "!" prefix to a user or group name to invert the sense
8321 of the match.
8322 Note: for interactions between clients and servers using Mercurial 3.6+
8324 a rejection will generally reject the entire push, for interactions in‐
8325 volving older clients, the commit transactions will already be ac‐
8326 cepted, and only the bookmark movement will be rejected.
8327 Groups
8329 Group names must be prefixed with an @ symbol. Specifying a group name
8330 has the same effect as specifying all the users in that group.
8331 You can define group members in the acl.groups section. If a group
8333 name is not defined there, and Mercurial is running under a Unix-like
8334 system, the list of users will be taken from the OS. Otherwise, an ex‐
8335 ception will be raised.
8336 Example Configuration
8338 [hooks]
8339 # Use this if you want to check access restrictions at commit time
8341 pretxncommit.acl = python:hgext.acl.hook
8342 # Use this if you want to check access restrictions for pull, push,
8344 # bundle and serve.
8345 pretxnchangegroup.acl = python:hgext.acl.hook
8346 [acl]
8348 # Allow or deny access for incoming changes only if their source is
8349 # listed here, let them pass otherwise. Source is "serve" for all
8350 # remote access (http or ssh), "push", "pull" or "bundle" when the
8351 # related commands are run locally.
8352 # Default: serve
8353 sources = serve
8354 [acl.deny.branches]
8356 # Everyone is denied to the frozen branch:
8358 frozen-branch = *
8359 # A bad user is denied on all branches:
8361 * = bad-user
8362 [acl.allow.branches]
8364 # A few users are allowed on branch-a:
8366 branch-a = user-1, user-2, user-3
8367 # Only one user is allowed on branch-b:
8369 branch-b = user-1
8370 # The super user is allowed on any branch:
8372 * = super-user
8373 # Everyone is allowed on branch-for-tests:
8375 branch-for-tests = *
8376 [acl.deny]
8378 # This list is checked first. If a match is found, acl.allow is not
8379 # checked. All users are granted access if acl.deny is not present.
8380 # Format for both lists: glob pattern = user, ..., @group, ...
8381 # To match everyone, use an asterisk for the user:
8383 # my/glob/pattern = *
8384 # user6 will not have write access to any file:
8386 ** = user6
8387 # Group "hg-denied" will not have write access to any file:
8389 ** = @hg-denied
8390 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
8392 # everyone being able to change all other files. See below.
8393 src/main/resources/DONT-TOUCH-THIS.txt = *
8394 [acl.allow]
8396 # if acl.allow is not present, all users are allowed by default
8397 # empty acl.allow = no users allowed
8398 # User "doc_writer" has write access to any file under the "docs"
8400 # folder:
8401 docs/** = doc_writer
8402 # User "jack" and group "designers" have write access to any file
8404 # under the "images" folder:
8405 images/** = jack, @designers
8406 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
8408 # will have write access to any file under the "resources" folder
8409 # (except for 1 file. See acl.deny):
8410 src/main/resources/** = *
8411 .hgtags = release_engineer
8413 Examples using the ! prefix
8415 Suppose there's a branch that only a given user (or group) should be
8416 able to push to, and you don't want to restrict access to any other
8417 branch that may be created.
8418 The "!" prefix allows you to prevent anyone except a given user or
8420 group to push changesets in a given branch or path.
8421 In the examples below, we will: 1) Deny access to branch "ring" to any‐
8423 one but user "gollum" 2) Deny access to branch "lake" to anyone but
8424 members of the group "hobbit" 3) Deny access to a file to anyone but
8425 user "gollum"
8426 [acl.allow.branches]
8428 # Empty
8429 [acl.deny.branches]
8431 # 1) only 'gollum' can commit to branch 'ring';
8433 # 'gollum' and anyone else can still commit to any other branch.
8434 ring = !gollum
8435 # 2) only members of the group 'hobbit' can commit to branch 'lake';
8437 # 'hobbit' members and anyone else can still commit to any other branch.
8438 lake = !@hobbit
8439 # You can also deny access based on file paths:
8441 [acl.allow]
8443 # Empty
8444 [acl.deny]
8446 # 3) only 'gollum' can change the file below;
8447 # 'gollum' and anyone else can still change any other file.
8448 /misty/mountains/cave/ring = !gollum
8449 amend
8451 provide the amend command (EXPERIMENTAL)
8452 This extension provides an amend command that is similar to commit
8454 --amend but does not prompt an editor.
8455 Commands
8457 Change creation
8458 amend
8459 amend the working copy parent with all or specified outstanding
8460 changes:
8461 hg amend [OPTION]... [FILE]...
8463 Similar to hg commit --amend, but reuse the commit message without in‐
8465 voking editor, unless --edit was set.
8466 See hg help commit for more details.
8468 Options:
8470 -A, --addremove
8472 mark new/missing files as added/removed before committing
8473 -e, --edit
8475 invoke editor on commit messages
8476 -i, --interactive
8478 use interactive mode
8479 --close-branch
8481 mark a branch as closed, hiding it from the branch list
8482 -s, --secret
8484 use the secret phase for committing
8485 -n,--note <VALUE>
8487 store a note on the amend
8488 -I,--include <PATTERN[+]>
8490 include names matching the given patterns
8491 -X,--exclude <PATTERN[+]>
8493 exclude names matching the given patterns
8494 -m,--message <TEXT>
8496 use text as commit message
8497 -l,--logfile <FILE>
8499 read commit message from file
8500 -d,--date <DATE>
8502 record the specified date as commit date
8503 -u,--user <USER>
8505 record the specified user as committer
8506 -D, --currentdate
8508 record the current date as commit date
8509 -U, --currentuser
8511 record the current user as committer
8512 [+] marked option can be specified multiple times
8514 automv
8516 check for unrecorded moves at commit time (EXPERIMENTAL)
8517 This extension checks at commit/amend time if any of the committed
8519 files comes from an unrecorded mv.
8520 The threshold at which a file is considered a move can be set with the
8522 automv.similarity config option. This option takes a percentage between
8523 0 (disabled) and 100 (files must be identical), the default is 95.
8524 beautifygraph
8526 beautify log -G output by using Unicode characters (EXPERIMENTAL)
8527 A terminal with UTF-8 support and monospace narrow text are re‐
8529 quired.
8530 blackbox
8532 log repository events to a blackbox for debugging
8533 Logs event information to .hg/blackbox.log to help debug and diagnose
8535 problems. The events that get logged can be configured via the black‐
8536 box.track and blackbox.ignore config keys.
8537 Examples:
8539 [blackbox]
8541 track = *
8542 ignore = pythonhook
8543 # dirty is *EXPENSIVE* (slow);
8544 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
8545 dirty = True
8546 # record the source of log messages
8547 logsource = True
8548 [blackbox]
8550 track = command, commandfinish, commandexception, exthook, pythonhook
8551 [blackbox]
8553 track = incoming
8554 [blackbox]
8556 # limit the size of a log file
8557 maxsize = 1.5 MB
8558 # rotate up to N log files when the current one gets too big
8559 maxfiles = 3
8560 [blackbox]
8562 # Include microseconds in log entries with %f (see Python function
8563 # datetime.datetime.strftime)
8564 date-format = %Y-%m-%d @ %H:%M:%S.%f
8565 Commands
8567 Repository maintenance
8568 blackbox
8569 view the recent repository events:
8570 hg blackbox [OPTION]...
8572 view the recent repository events
8574 Options:
8576 -l,--limit <VALUE>
8578 the number of events to show (default: 10)
8579 bookflow
8581 implements bookmark-based branching (EXPERIMENTAL)
8582 • Disables creation of new branches (config: enable_branches=False).
8584 • Requires an active bookmark on commit (config: require_book‐
8586 mark=True).
8587 • Doesn't move the active bookmark on update, only on commit.
8589 • Requires '--rev' for moving an existing bookmark.
8591 • Protects special bookmarks (config: protect=@).
8593 flow related commands
8595 hg book NAME
8597 create a new bookmark
8598 hg book NAME -r REV
8600 move bookmark to revision (fast-forward)
8601 hg up|co NAME
8603 switch to bookmark
8604 hg push -B .
8606 push active bookmark
8607 bugzilla
8609 hooks for integrating with the Bugzilla bug tracker
8610 This hook extension adds comments on bugs in Bugzilla when changesets
8612 that refer to bugs by Bugzilla ID are seen. The comment is formatted
8613 using the Mercurial template mechanism.
8614 The bug references can optionally include an update for Bugzilla of the
8616 hours spent working on the bug. Bugs can also be marked fixed.
8617 Four basic modes of access to Bugzilla are provided:
8619 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
8621 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
8623 later.
8624 3. Check data via the Bugzilla XMLRPC interface and submit bug change
8626 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
8627 later.
8628 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
8630 tions using MySQL are supported. Requires Python MySQLdb.
8631 Writing directly to the database is susceptible to schema changes, and
8633 relies on a Bugzilla contrib script to send out bug change notification
8634 emails. This script runs as the user running Mercurial, must be run on
8635 the host with the Bugzilla install, and requires permission to read
8636 Bugzilla configuration details and the necessary MySQL user and pass‐
8637 word to have full access rights to the Bugzilla database. For these
8638 reasons this access mode is now considered deprecated, and will not be
8639 updated for new Bugzilla versions going forward. Only adding comments
8640 is supported in this access mode.
8641 Access via XMLRPC needs a Bugzilla username and password to be speci‐
8643 fied in the configuration. Comments are added under that username.
8644 Since the configuration must be readable by all Mercurial users, it is
8645 recommended that the rights of that user are restricted in Bugzilla to
8646 the minimum necessary to add comments. Marking bugs fixed requires
8647 Bugzilla 4.0 and later.
8648 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
8650 to the Bugzilla email interface to submit comments to bugs. The From:
8651 address in the email is set to the email address of the Mercurial user,
8652 so the comment appears to come from the Mercurial user. In the event
8653 that the Mercurial user email is not recognized by Bugzilla as a
8654 Bugzilla user, the email associated with the Bugzilla username used to
8655 log into Bugzilla is used instead as the source of the comment. Marking
8656 bugs fixed works on all supported Bugzilla versions.
8657 Access via the REST-API needs either a Bugzilla username and password
8659 or an apikey specified in the configuration. Comments are made under
8660 the given username or the user associated with the apikey in Bugzilla.
8661 Configuration items common to all access modes:
8663 bugzilla.version
8665 The access type to use. Values recognized are:
8666 restapi
8668 Bugzilla REST-API, Bugzilla 5.0 and later.
8670 xmlrpc
8672 Bugzilla XMLRPC interface.
8674 xmlrpc+email
8676 Bugzilla XMLRPC and email interfaces.
8678 3.0
8680 MySQL access, Bugzilla 3.0 and later.
8682 2.18
8684 MySQL access, Bugzilla 2.18 and up to but not including
8686 3.0.
8687 2.16
8689 MySQL access, Bugzilla 2.16 and up to but not including
8691 2.18.
8692 bugzilla.regexp
8694 Regular expression to match bug IDs for update in changeset com‐
8695 mit message. It must contain one "()" named group <ids> con‐
8696 taining the bug IDs separated by non-digit characters. It may
8697 also contain a named group <hours> with a floating-point number
8698 giving the hours worked on the bug. If no named groups are
8699 present, the first "()" group is assumed to contain the bug IDs,
8700 and work time is not updated. The default expression matches Bug
8701 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
8702 and 5678 and variations thereof, followed by an hours number
8703 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
8704 sitive.
8705 bugzilla.fixregexp
8707 Regular expression to match bug IDs for marking fixed in change‐
8708 set commit message. This must contain a "()" named group <ids>`
8709 containing the bug IDs separated by non-digit characters. It may
8710 also contain a named group ``<hours> with a floating-point num‐
8711 ber giving the hours worked on the bug. If no named groups are
8712 present, the first "()" group is assumed to contain the bug IDs,
8713 and work time is not updated. The default expression matches
8714 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
8715 5678 and variations thereof, followed by an hours number pre‐
8716 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
8717 tive.
8718 bugzilla.fixstatus
8720 The status to set a bug to when marking fixed. Default RESOLVED.
8721 bugzilla.fixresolution
8723 The resolution to set a bug to when marking fixed. Default
8724 FIXED.
8725 bugzilla.style
8727 The style file to use when formatting comments.
8728 bugzilla.template
8730 Template to use when formatting comments. Overrides style if
8731 specified. In addition to the usual Mercurial keywords, the ex‐
8732 tension specifies:
8733 {bug}
8735 The Bugzilla bug ID.
8737 {root}
8739 The full pathname of the Mercurial repository.
8741 {webroot}
8743 Stripped pathname of the Mercurial repository.
8745 {hgweb}
8747 Base URL for browsing Mercurial repositories.
8749 Default changeset {node|short} in repo {root} refers to bug
8751 {bug}.\ndetails:\n\t{desc|tabindent}
8752 bugzilla.strip
8754 The number of path separator characters to strip from the front
8755 of the Mercurial repository path ({root} in templates) to pro‐
8756 duce {webroot}. For example, a repository with {root} /var/lo‐
8757 cal/my-project with a strip of 2 gives a value for {webroot} of
8758 my-project. Default 0.
8759 web.baseurl
8761 Base URL for browsing Mercurial repositories. Referenced from
8762 templates as {hgweb}.
8763 Configuration items common to XMLRPC+email and MySQL access modes:
8765 bugzilla.usermap
8767 Path of file containing Mercurial committer email to Bugzilla
8768 user email mappings. If specified, the file should contain one
8769 mapping per line:
8770 committer = Bugzilla user
8772 See also the [usermap] section.
8774 The [usermap] section is used to specify mappings of Mercurial commit‐
8776 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
8777 entries of the form committer = Bugzilla user.
8778 XMLRPC and REST-API access mode configuration:
8780 bugzilla.bzurl
8782 The base URL for the Bugzilla installation. Default http://lo‐
8783 calhost/bugzilla.
8784 bugzilla.user
8786 The username to use to log into Bugzilla via XMLRPC. Default
8787 bugs.
8788 bugzilla.password
8790 The password for Bugzilla login.
8791 REST-API access mode uses the options listed above as well as:
8793 bugzilla.apikey
8795 An apikey generated on the Bugzilla instance for api access.
8796 Using an apikey removes the need to store the user and password
8797 options.
8798 XMLRPC+email access mode uses the XMLRPC access mode configuration
8800 items, and also:
8801 bugzilla.bzemail
8803 The Bugzilla email address.
8804 In addition, the Mercurial email settings must be configured. See the
8806 documentation in hgrc(5), sections [email] and [smtp].
8807 MySQL access mode configuration:
8809 bugzilla.host
8811 Hostname of the MySQL server holding the Bugzilla database. De‐
8812 fault localhost.
8813 bugzilla.db
8815 Name of the Bugzilla database in MySQL. Default bugs.
8816 bugzilla.user
8818 Username to use to access MySQL server. Default bugs.
8819 bugzilla.password
8821 Password to use to access MySQL server.
8822 bugzilla.timeout
8824 Database connection timeout (seconds). Default 5.
8825 bugzilla.bzuser
8827 Fallback Bugzilla user name to record comments with, if change‐
8828 set committer cannot be found as a Bugzilla user.
8829 bugzilla.bzdir
8831 Bugzilla install directory. Used by default notify. Default
8832 /var/www/html/bugzilla.
8833 bugzilla.notify
8835 The command to run to get Bugzilla to send bug change notifica‐
8836 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
8837 id) and user (committer bugzilla email). Default depends on ver‐
8838 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
8839 mail.pl %(id)s %(user)s".
8840 Activating the extension:
8842 [extensions]
8844 bugzilla =
8845 [hooks]
8847 # run bugzilla hook on every change pulled or pushed in here
8848 incoming.bugzilla = python:hgext.bugzilla.hook
8849 Example configurations:
8851 XMLRPC example configuration. This uses the Bugzilla at
8853 http://my-project.org/bugzilla, logging in as user bug‐
8854 mail@my-project.org with password plugh. It is used with a collection
8855 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8856 at http://my-project.org/hg.
8857 [bugzilla]
8859 bzurl=http://my-project.org/bugzilla
8860 user=bugmail@my-project.org
8861 password=plugh
8862 version=xmlrpc
8863 template=Changeset {node|short} in {root|basename}.
8864 {hgweb}/{webroot}/rev/{node|short}\n
8865 {desc}\n
8866 strip=5
8867 [web]
8869 baseurl=http://my-project.org/hg
8870 XMLRPC+email example configuration. This uses the Bugzilla at
8872 http://my-project.org/bugzilla, logging in as user bug‐
8873 mail@my-project.org with password plugh. It is used with a collection
8874 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8875 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
8876 email address bugzilla@my-project.org.
8877 [bugzilla]
8879 bzurl=http://my-project.org/bugzilla
8880 user=bugmail@my-project.org
8881 password=plugh
8882 version=xmlrpc+email
8883 bzemail=bugzilla@my-project.org
8884 template=Changeset {node|short} in {root|basename}.
8885 {hgweb}/{webroot}/rev/{node|short}\n
8886 {desc}\n
8887 strip=5
8888 [web]
8890 baseurl=http://my-project.org/hg
8891 [usermap]
8893 user@emaildomain.com=user.name@bugzilladomain.com
8894 MySQL example configuration. This has a local Bugzilla 3.2 installation
8896 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
8897 database name is bugs and MySQL is accessed with MySQL username bugs
8898 password XYZZY. It is used with a collection of Mercurial repositories
8899 in /var/local/hg/repos/, with a web interface at
8900 http://my-project.org/hg.
8901 [bugzilla]
8903 host=localhost
8904 password=XYZZY
8905 version=3.0
8906 bzuser=unknown@domain.com
8907 bzdir=/opt/bugzilla-3.2
8908 template=Changeset {node|short} in {root|basename}.
8909 {hgweb}/{webroot}/rev/{node|short}\n
8910 {desc}\n
8911 strip=5
8912 [web]
8914 baseurl=http://my-project.org/hg
8915 [usermap]
8917 user@emaildomain.com=user.name@bugzilladomain.com
8918 All the above add a comment to the Bugzilla bug record of the form:
8920 Changeset 3b16791d6642 in repository-name.
8922 http://my-project.org/hg/repository-name/rev/3b16791d6642
8923 Changeset commit comment. Bug 1234.
8925 censor
8927 erase file content at a given revision
8928 The censor command instructs Mercurial to erase all content of a file
8930 at a given revision without updating the changeset hash. This allows
8931 existing history to remain valid while preventing future clones/pulls
8932 from receiving the erased data.
8933 Typical uses for censor are due to security or legal requirements, in‐
8935 cluding:
8936 * Passwords, private keys, cryptographic material
8938 * Licensed data/code/libraries for which the license has expired
8939 * Personally Identifiable Information or other private data
8940 Censored nodes can interrupt mercurial's typical operation whenever the
8942 excised data needs to be materialized. Some commands, like hg cat/hg
8943 revert, simply fail when asked to produce censored data. Others, like
8944 hg verify and hg update, must be capable of tolerating censored data to
8945 continue to function in a meaningful way. Such commands only tolerate
8946 censored file revisions if they are allowed by the "censor.policy=ig‐
8947 nore" config option.
8948 A few informative commands such as hg grep will unconditionally ignore
8950 censored data and merely report that it was encountered.
8951 Commands
8953 Repository maintenance
8954 censor
8955 hg censor -r REV [-t TEXT] [FILE]
8956 Options:
8958 -r,--rev <REV>
8960 censor file from specified revision
8961 -t,--tombstone <TEXT>
8963 replacement tombstone data
8964 children
8966 command to display child changesets (DEPRECATED)
8967 This extension is deprecated. You should use hg log -r "children(REV)"
8969 instead.
8970 Commands
8972 Change navigation
8973 children
8974 show the children of the given or working directory revision:
8975 hg children [-r REV] [FILE]
8977 Print the children of the working directory's revisions. If a revision
8979 is given via -r/--rev, the children of that revision will be printed.
8980 If a file argument is given, revision in which the file was last
8981 changed (after the working directory revision or the argument to --rev
8982 if given) is printed.
8983 Please use hg log instead:
8985 hg children => hg log -r "children(.)"
8987 hg children -r REV => hg log -r "children(REV)"
8988 See hg help log and hg help revsets.children.
8990 Options:
8992 -r,--rev <REV>
8994 show children of the specified revision (default: .)
8995 --style <STYLE>
8997 display using template map file (DEPRECATED)
8998 -T,--template <TEMPLATE>
9000 display with template
9001 churn
9003 command to display statistics about repository history
9004 Commands
9006 Repository maintenance
9007 churn
9008 histogram of changes to the repository:
9009 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
9011 This command will display a histogram representing the number of
9013 changed lines or revisions, grouped according to the given template.
9014 The default template will group changes by author. The --dateformat
9015 option may be used to group the results by date instead.
9016 Statistics are based on the number of changed lines, or alternatively
9018 the number of matching revisions if the --changesets option is speci‐
9019 fied.
9020 Examples:
9022 # display count of changed lines for every committer
9024 hg churn -T "{author|email}"
9025 # display daily activity graph
9027 hg churn -f "%H" -s -c
9028 # display activity of developers by month
9030 hg churn -f "%Y-%m" -s -c
9031 # display count of lines changed in every year
9033 hg churn -f "%Y" -s
9034 # display count of lines changed in a time range
9036 hg churn -d "2020-04 to 2020-09"
9037 It is possible to map alternate email addresses to a main address by
9039 providing a file using the following format:
9040 <alias email> = <actual email>
9042 Such a file may be specified with the --aliases option, otherwise a
9044 .hgchurn file will be looked for in the working directory root.
9045 Aliases will be split from the rightmost "=".
9046 Options:
9048 -r,--rev <REV[+]>
9050 count rate for the specified revision or revset
9051 -d,--date <DATE>
9053 count rate for revisions matching date spec
9054 -t,--oldtemplate <TEMPLATE>
9056 template to group changesets (DEPRECATED)
9057 -T,--template <TEMPLATE>
9059 template to group changesets (default: {author|email})
9060 -f,--dateformat <FORMAT>
9062 strftime-compatible format for grouping by date
9063 -c, --changesets
9065 count rate by number of changesets
9066 -s, --sort
9068 sort by key (default: sort by count)
9069 --diffstat
9071 display added/removed lines separately
9072 --aliases <FILE>
9074 file with email aliases
9075 -I,--include <PATTERN[+]>
9077 include names matching the given patterns
9078 -X,--exclude <PATTERN[+]>
9080 exclude names matching the given patterns
9081 [+] marked option can be specified multiple times
9083 clonebundles
9085 advertise pre-generated bundles to seed clones
9086 "clonebundles" is a server-side extension used to advertise the exis‐
9088 tence of pre-generated, externally hosted bundle files to clients that
9089 are cloning so that cloning can be faster, more reliable, and require
9090 less resources on the server. "pullbundles" is a related feature for
9091 sending pre-generated bundle files to clients as part of pull opera‐
9092 tions.
9093 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
9095 ally, the server, in response to a client's request to clone, dynami‐
9096 cally generates a bundle containing the entire repository content and
9097 sends it to the client. There is no caching on the server and the
9098 server will have to redundantly generate the same outgoing bundle in
9099 response to each clone request. For servers with large repositories or
9100 with high clone volume, the load from clones can make scaling the
9101 server challenging and costly.
9102 This extension provides server operators the ability to offload poten‐
9104 tially expensive clone load to an external service. Pre-generated bun‐
9105 dles also allow using more CPU intensive compression, reducing the ef‐
9106 fective bandwidth requirements.
9107 Here's how clone bundles work:
9109 1. A server operator establishes a mechanism for making bundle files
9111 available on a hosting service where Mercurial clients can fetch
9112 them.
9113 2. A manifest file listing available bundle URLs and some optional
9115 metadata is added to the Mercurial repository on the server.
9116 3. A client initiates a clone against a clone bundles aware server.
9118 4. The client sees the server is advertising clone bundles and fetches
9120 the manifest listing available bundles.
9121 5. The client filters and sorts the available bundles based on what it
9123 supports and prefers.
9124 6. The client downloads and applies an available bundle from the
9126 server-specified URL.
9127 7. The client reconnects to the original server and performs the equiv‐
9129 alent of hg pull to retrieve all repository data not in the bundle.
9130 (The repository could have been updated between when the bundle was
9131 created and when the client started the clone.) This may use "pull‐
9132 bundles".
9133 Instead of the server generating full repository bundles for every
9135 clone request, it generates full bundles once and they are subsequently
9136 reused to bootstrap new clones. The server may still transfer data at
9137 clone time. However, this is only data that has been added/changed
9138 since the bundle was created. For large, established repositories, this
9139 can reduce server load for clones to less than 1% of original.
9140 Here's how pullbundles work:
9142 1. A manifest file listing available bundles and describing the revi‐
9144 sions is added to the Mercurial repository on the server.
9145 2. A new-enough client informs the server that it supports partial
9147 pulls and initiates a pull.
9148 3. If the server has pull bundles enabled and sees the client advertis‐
9150 ing partial pulls, it checks for a matching pull bundle in the mani‐
9151 fest. A bundle matches if the format is supported by the client,
9152 the client has the required revisions already and needs something
9153 from the bundle.
9154 4. If there is at least one matching bundle, the server sends it to the
9156 client.
9157 5. The client applies the bundle and notices that the server reply was
9159 incomplete. It initiates another pull.
9160 To work, this extension requires the following of server operators:
9162 • Generating bundle files of repository content (typically periodi‐
9164 cally, such as once per day).
9165 • Clone bundles: A file server that clients have network access to and
9167 that Python knows how to talk to through its normal URL handling fa‐
9168 cility (typically an HTTP/HTTPS server).
9169 • A process for keeping the bundles manifest in sync with available
9171 bundle files.
9172 Strictly speaking, using a static file hosting server isn't required: a
9174 server operator could use a dynamic service for retrieving bundle data.
9175 However, static file hosting services are simple and scalable and
9176 should be sufficient for most needs.
9177 Bundle files can be generated with the hg bundle command. Typically hg
9179 bundle --all is used to produce a bundle of the entire repository.
9180 hg debugcreatestreamclonebundle can be used to produce a special
9182 streaming clonebundle. These are bundle files that are extremely effi‐
9183 cient to produce and consume (read: fast). However, they are larger
9184 than traditional bundle formats and require that clients support the
9185 exact set of repository data store formats in use by the repository
9186 that created them. Typically, a newer server can serve data that is
9187 compatible with older clients. However, streaming clone bundles don't
9188 have this guarantee. Server operators need to be aware that newer ver‐
9189 sions of Mercurial may produce streaming clone bundles incompatible
9190 with older Mercurial versions.
9191 A server operator is responsible for creating a .hg/clonebundles.mani‐
9193 fest file containing the list of available bundle files suitable for
9194 seeding clones. If this file does not exist, the repository will not
9195 advertise the existence of clone bundles when clients connect. For pull
9196 bundles, .hg/pullbundles.manifest is used.
9197 The manifest file contains a newline (n) delimited list of entries.
9199 Each line in this file defines an available bundle. Lines have the for‐
9201 mat:
9202 <URL> [<key>=<value>[ <key>=<value>]]
9204 That is, a URL followed by an optional, space-delimited list of
9206 key=value pairs describing additional properties of this bundle. Both
9207 keys and values are URI encoded.
9208 For pull bundles, the URL is a path under the .hg directory of the
9210 repository.
9211 Keys in UPPERCASE are reserved for use by Mercurial and are defined be‐
9213 low. All non-uppercase keys can be used by site installations. An ex‐
9214 ample use for custom properties is to use the datacenter attribute to
9215 define which data center a file is hosted in. Clients could then prefer
9216 a server in the data center closest to them.
9217 The following reserved keys are currently defined:
9219 BUNDLESPEC
9221 A "bundle specification" string that describes the type of the
9222 bundle.
9223 These are string values that are accepted by the "--type" argu‐
9225 ment of hg bundle.
9226 The values are parsed in strict mode, which means they must be
9228 of the "<compression>-<type>" form. See mercurial.ex‐
9229 change.parsebundlespec() for more details.
9230 hg debugbundle --spec can be used to print the bundle specifica‐
9232 tion string for a bundle file. The output of this command can be
9233 used verbatim for the value of BUNDLESPEC (it is already es‐
9234 caped).
9235 Clients will automatically filter out specifications that are
9237 unknown or unsupported so they won't attempt to download some‐
9238 thing that likely won't apply.
9239 The actual value doesn't impact client behavior beyond filter‐
9241 ing: clients will still sniff the bundle type from the header of
9242 downloaded files.
9243 Use of this key is highly recommended, as it allows clients to
9245 easily skip unsupported bundles. If this key is not defined, an
9246 old client may attempt to apply a bundle that it is incapable of
9247 reading.
9248 REQUIRESNI
9250 Whether Server Name Indication (SNI) is required to connect to
9251 the URL. SNI allows servers to use multiple certificates on the
9252 same IP. It is somewhat common in CDNs and other hosting
9253 providers. Older Python versions do not support SNI. Defining
9254 this attribute enables clients with older Python versions to
9255 filter this entry without experiencing an opaque SSL failure at
9256 connection time.
9257 If this is defined, it is important to advertise a non-SNI fall‐
9259 back URL or clients running old Python releases may not be able
9260 to clone with the clonebundles facility.
9261 Value should be "true".
9263 REQUIREDRAM
9265 Value specifies expected memory requirements to decode the pay‐
9266 load. Values can have suffixes for common bytes sizes. e.g.
9267 "64MB".
9268 This key is often used with zstd-compressed bundles using a high
9270 compression level / window size, which can require 100+ MB of
9271 memory to decode.
9272 heads Used for pull bundles. This contains the ; separated changeset
9274 hashes of the heads of the bundle content.
9275 bases Used for pull bundles. This contains the ; separated changeset
9277 hashes of the roots of the bundle content. This can be skipped
9278 if the bundle was created without --base.
9279 Manifests can contain multiple entries. Assuming metadata is defined,
9281 clients will filter entries from the manifest that they don't support.
9282 The remaining entries are optionally sorted by client preferences
9283 (ui.clonebundleprefers config option). The client then attempts to
9284 fetch the bundle at the first URL in the remaining list.
9285 Errors when downloading a bundle will fail the entire clone operation:
9287 clients do not automatically fall back to a traditional clone. The rea‐
9288 son for this is that if a server is using clone bundles, it is probably
9289 doing so because the feature is necessary to help it scale. In other
9290 words, there is an assumption that clone load will be offloaded to an‐
9291 other service and that the Mercurial server isn't responsible for serv‐
9292 ing this clone load. If that other service experiences issues and
9293 clients start mass falling back to the original Mercurial server, the
9294 added clone load could overwhelm the server due to unexpected load and
9295 effectively take it offline. Not having clients automatically fall back
9296 to cloning from the original server mitigates this scenario.
9297 Because there is no automatic Mercurial server fallback on failure of
9299 the bundle hosting service, it is important for server operators to
9300 view the bundle hosting service as an extension of the Mercurial server
9301 in terms of availability and service level agreements: if the bundle
9302 hosting service goes down, so does the ability for clients to clone.
9303 Note: clients will see a message informing them how to bypass the clone
9304 bundles facility when a failure occurs. So server operators should pre‐
9305 pare for some people to follow these instructions when a failure oc‐
9306 curs, thus driving more load to the original Mercurial server when the
9307 bundle hosting service fails.
9308 closehead
9310 close arbitrary heads without checking them out first
9311 Commands
9313 Change manipulation
9314 close-head
9315 close the given head revisions:
9316 hg close-head [OPTION]... [REV]...
9318 This is equivalent to checking out each revision in a clean tree and
9320 running hg commit --close-branch, except that it doesn't change the
9321 working directory.
9322 The commit message must be specified with -l or -m.
9324 Options:
9326 -m,--message <TEXT>
9328 use text as commit message
9329 -l,--logfile <FILE>
9331 read commit message from file
9332 -d,--date <DATE>
9334 record the specified date as commit date
9335 -u,--user <USER>
9337 record the specified user as committer
9338 -r,--rev <REV[+]>
9340 revision to check
9341 [+] marked option can be specified multiple times
9343 aliases: close-heads
9345 commitextras
9347 adds a new flag extras to commit (ADVANCED)
9348 convert
9350 import revisions from foreign VCS repositories into Mercurial
9351 Commands
9353 Uncategorized commands
9354 convert
9355 convert a foreign SCM repository to a Mercurial one.:
9356 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
9358 Accepted source formats [identifiers]:
9360 • Mercurial [hg]
9362 • CVS [cvs]
9364 • Darcs [darcs]
9366 • git [git]
9368 • Subversion [svn]
9370 • Monotone [mtn]
9372 • GNU Arch [gnuarch]
9374 • Bazaar [bzr]
9376 • Perforce [p4]
9378 Accepted destination formats [identifiers]:
9380 • Mercurial [hg]
9382 • Subversion [svn] (history on branches is not preserved)
9384 If no revision is given, all revisions will be converted. Otherwise,
9386 convert will only import up to the named revision (given in a format
9387 understood by the source).
9388 If no destination directory name is specified, it defaults to the base‐
9390 name of the source with -hg appended. If the destination repository
9391 doesn't exist, it will be created.
9392 By default, all sources except Mercurial will use --branchsort. Mercu‐
9394 rial uses --sourcesort to preserve original revision numbers order.
9395 Sort modes have the following effects:
9396 --branchsort
9398 convert from parent to child revision when possible, which means
9399 branches are usually converted one after the other. It generates
9400 more compact repositories.
9401 --datesort
9403 sort revisions by date. Converted repositories have good-looking
9404 changelogs but are often an order of magnitude larger than the
9405 same ones generated by --branchsort.
9406 --sourcesort
9408 try to preserve source revisions order, only supported by Mercu‐
9409 rial sources.
9410 --closesort
9412 try to move closed revisions as close as possible to parent
9413 branches, only supported by Mercurial sources.
9414 If REVMAP isn't given, it will be put in a default location
9416 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
9417 maps each source commit ID to the destination ID for that revision,
9418 like so:
9419 <source ID> <destination ID>
9421 If the file doesn't exist, it's automatically created. It's updated on
9423 each commit copied, so hg convert can be interrupted and can be run re‐
9424 peatedly to copy new commits.
9425 The authormap is a simple text file that maps each source commit author
9427 to a destination commit author. It is handy for source SCMs that use
9428 unix logins to identify authors (e.g.: CVS). One line per author map‐
9429 ping and the line format is:
9430 source author = destination author
9432 Empty lines and lines starting with a # are ignored.
9434 The filemap is a file that allows filtering and remapping of files and
9436 directories. Each line can contain one of the following directives:
9437 include path/to/file-or-dir
9439 exclude path/to/file-or-dir
9441 rename path/to/source path/to/destination
9443 Comment lines start with #. A specified path matches if it equals the
9445 full relative name of a file or one of its parent directories. The in‐
9446 clude or exclude directive with the longest matching path applies, so
9447 line order does not matter.
9448 The include directive causes a file, or all files under a directory, to
9450 be included in the destination repository. The default if there are no
9451 include statements is to include everything. If there are any include
9452 statements, nothing else is included. The exclude directive causes
9453 files or directories to be omitted. The rename directive renames a file
9454 or directory if it is converted. To rename from a subdirectory into the
9455 root of the repository, use . as the path to rename to.
9456 --full will make sure the converted changesets contain exactly the
9458 right files with the right content. It will make a full conversion of
9459 all files, not just the ones that have changed. Files that already are
9460 correct will not be changed. This can be used to apply filemap changes
9461 when converting incrementally. This is currently only supported for
9462 Mercurial and Subversion.
9463 The splicemap is a file that allows insertion of synthetic history,
9465 letting you specify the parents of a revision. This is useful if you
9466 want to e.g. give a Subversion merge two parents, or graft two discon‐
9467 nected series of history together. Each entry contains a key, followed
9468 by a space, followed by one or two comma-separated values:
9469 key parent1, parent2
9471 The key is the revision ID in the source revision control system whose
9473 parents should be modified (same format as a key in .hg/shamap). The
9474 values are the revision IDs (in either the source or destination revi‐
9475 sion control system) that should be used as the new parents for that
9476 node. For example, if you have merged "release-1.0" into "trunk", then
9477 you should specify the revision on "trunk" as the first parent and the
9478 one on the "release-1.0" branch as the second.
9479 The branchmap is a file that allows you to rename a branch when it is
9481 being brought in from whatever external repository. When used in con‐
9482 junction with a splicemap, it allows for a powerful combination to help
9483 fix even the most badly mismanaged repositories and turn them into
9484 nicely structured Mercurial repositories. The branchmap contains lines
9485 of the form:
9486 original_branch_name new_branch_name
9488 where "original_branch_name" is the name of the branch in the source
9490 repository, and "new_branch_name" is the name of the branch is the des‐
9491 tination repository. No whitespace is allowed in the new branch name.
9492 This can be used to (for instance) move code in one repository from
9493 "default" to a named branch.
9494 Mercurial Source
9496 The Mercurial source recognizes the following configuration options,
9497 which you can set on the command line with --config:
9498 convert.hg.ignoreerrors
9500 ignore integrity errors when reading. Use it to fix Mercurial
9501 repositories with missing revlogs, by converting from and to
9502 Mercurial. Default is False.
9503 convert.hg.saverev
9505 store original revision ID in changeset (forces target IDs to
9506 change). It takes a boolean argument and defaults to False.
9507 convert.hg.startrev
9509 specify the initial Mercurial revision. The default is 0.
9510 convert.hg.revs
9512 revset specifying the source revisions to convert.
9513 Bazaar Source
9515 The following options can be used with --config:
9516 convert.bzr.saverev
9518 whether to store the original Bazaar commit ID in the metadata
9519 of the destination commit. The default is True.
9520 CVS Source
9522 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to in‐
9523 dicate the starting point of what will be converted. Direct access to
9524 the repository files is not needed, unless of course the repository is
9525 :local:. The conversion uses the top level directory in the sandbox to
9526 find the CVS repository, and then uses CVS rlog commands to find files
9527 to convert. This means that unless a filemap is given, all files under
9528 the starting directory will be converted, and that any directory reor‐
9529 ganization in the CVS sandbox is ignored.
9530 The following options can be used with --config:
9532 convert.cvsps.cache
9534 Set to False to disable remote log caching, for testing and de‐
9535 bugging purposes. Default is True.
9536 convert.cvsps.fuzz
9538 Specify the maximum time (in seconds) that is allowed between
9539 commits with identical user and log message in a single change‐
9540 set. When very large files were checked in as part of a change‐
9541 set then the default may not be long enough. The default is 60.
9542 convert.cvsps.logencoding
9544 Specify encoding name to be used for transcoding CVS log mes‐
9545 sages. Multiple encoding names can be specified as a list (see
9546 hg help config.Syntax), but only the first acceptable encoding
9547 in the list is used per CVS log entries. This transcoding is ex‐
9548 ecuted before cvslog hook below.
9549 convert.cvsps.mergeto
9551 Specify a regular expression to which commit log messages are
9552 matched. If a match occurs, then the conversion process will in‐
9553 sert a dummy revision merging the branch on which this log mes‐
9554 sage occurs to the branch indicated in the regex. Default is
9555 {{mergetobranch ([-\w]+)}}
9556 convert.cvsps.mergefrom
9558 Specify a regular expression to which commit log messages are
9559 matched. If a match occurs, then the conversion process will add
9560 the most recent revision on the branch indicated in the regex as
9561 the second parent of the changeset. Default is {{mergefrombranch
9562 ([-\w]+)}}
9563 convert.localtimezone
9565 use local time (as determined by the TZ environment variable)
9566 for changeset date/times. The default is False (use UTC).
9567 hooks.cvslog
9569 Specify a Python function to be called at the end of gathering
9570 the CVS log. The function is passed a list with the log entries,
9571 and can modify the entries in-place, or add or delete them.
9572 hooks.cvschangesets
9574 Specify a Python function to be called after the changesets are
9575 calculated from the CVS log. The function is passed a list with
9576 the changeset entries, and can modify the changesets in-place,
9577 or add or delete them.
9578 An additional "debugcvsps" Mercurial command allows the builtin change‐
9580 set merging code to be run without doing a conversion. Its parameters
9581 and output are similar to that of cvsps 2.1. Please see the command
9582 help for more details.
9583 Subversion Source
9585 Subversion source detects classical trunk/branches/tags layouts. By
9586 default, the supplied svn://repo/path/ source URL is converted as a
9587 single branch. If svn://repo/path/trunk exists it replaces the default
9588 branch. If svn://repo/path/branches exists, its subdirectories are
9589 listed as possible branches. If svn://repo/path/tags exists, it is
9590 looked for tags referencing converted branches. Default trunk, branches
9591 and tags values can be overridden with following options. Set them to
9592 paths relative to the source URL, or leave them blank to disable auto
9593 detection.
9594 The following options can be set with --config:
9596 convert.svn.branches
9598 specify the directory containing branches. The default is
9599 branches.
9600 convert.svn.tags
9602 specify the directory containing tags. The default is tags.
9603 convert.svn.trunk
9605 specify the name of the trunk branch. The default is trunk.
9606 convert.localtimezone
9608 use local time (as determined by the TZ environment variable)
9609 for changeset date/times. The default is False (use UTC).
9610 Source history can be retrieved starting at a specific revision, in‐
9612 stead of being integrally converted. Only single branch conversions are
9613 supported.
9614 convert.svn.startrev
9616 specify start Subversion revision number. The default is 0.
9617 Git Source
9619 The Git importer converts commits from all reachable branches (refs in
9620 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
9621 are converted to bookmarks with the same name, with the leading
9622 'refs/heads' stripped. Git submodules are converted to Git subrepos in
9623 Mercurial.
9624 The following options can be set with --config:
9626 convert.git.similarity
9628 specify how similar files modified in a commit must be to be im‐
9629 ported as renames or copies, as a percentage between 0 (dis‐
9630 abled) and 100 (files must be identical). For example, 90 means
9631 that a delete/add pair will be imported as a rename if more than
9632 90% of the file hasn't changed. The default is 50.
9633 convert.git.findcopiesharder
9635 while detecting copies, look at all files in the working copy
9636 instead of just changed ones. This is very expensive for large
9637 projects, and is only effective when convert.git.similarity is
9638 greater than 0. The default is False.
9639 convert.git.renamelimit
9641 perform rename and copy detection up to this many changed files
9642 in a commit. Increasing this will make rename and copy detection
9643 more accurate but will significantly slow down computation on
9644 large projects. The option is only relevant if convert.git.simi‐
9645 larity is greater than 0. The default is 400.
9646 convert.git.committeractions
9648 list of actions to take when processing author and committer
9649 values.
9650 Git commits have separate author (who wrote the commit) and com‐
9652 mitter (who applied the commit) fields. Not all destinations
9653 support separate author and committer fields (including Mercu‐
9654 rial). This config option controls what to do with these author
9655 and committer fields during conversion.
9656 A value of messagedifferent will append a committer: ... line
9658 to the commit message if the Git committer is different from the
9659 author. The prefix of that line can be specified using the syn‐
9660 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
9661 ter:. When a prefix is specified, a space will always be in‐
9662 serted between the prefix and the value.
9663 messagealways behaves like messagedifferent except it will al‐
9665 ways result in a committer: ... line being appended to the com‐
9666 mit message. This value is mutually exclusive with messagedif‐
9667 ferent.
9668 dropcommitter will remove references to the committer. Only ref‐
9670 erences to the author will remain. Actions that add references
9671 to the committer will have no effect when this is set.
9672 replaceauthor will replace the value of the author field with
9674 the committer. Other actions that add references to the commit‐
9675 ter will still take effect when this is set.
9676 The default is messagedifferent.
9678 convert.git.extrakeys
9680 list of extra keys from commit metadata to copy to the destina‐
9681 tion. Some Git repositories store extra metadata in commits. By
9682 default, this non-default metadata will be lost during conver‐
9683 sion. Setting this config option can retain that metadata. Some
9684 built-in keys such as parent and branch are not allowed to be
9685 copied.
9686 convert.git.remoteprefix
9688 remote refs are converted as bookmarks with convert.git.re‐
9689 moteprefix as a prefix followed by a /. The default is 'remote'.
9690 convert.git.saverev
9692 whether to store the original Git commit ID in the metadata of
9693 the destination commit. The default is True.
9694 convert.git.skipsubmodules
9696 does not convert root level .gitmodules files or files with
9697 160000 mode indicating a submodule. Default is False.
9698 Perforce Source
9700 The Perforce (P4) importer can be given a p4 depot path or a client
9701 specification as source. It will convert all files in the source to a
9702 flat Mercurial repository, ignoring labels, branches and integrations.
9703 Note that when a depot path is given you then usually should specify a
9704 target directory, because otherwise the target may be named ...-hg.
9705 The following options can be set with --config:
9707 convert.p4.encoding
9709 specify the encoding to use when decoding standard output of the
9710 Perforce command line tool. The default is default system encod‐
9711 ing.
9712 convert.p4.startrev
9714 specify initial Perforce revision (a Perforce changelist num‐
9715 ber).
9716 Mercurial Destination
9718 The Mercurial destination will recognize Mercurial subrepositories in
9719 the destination directory, and update the .hgsubstate file automati‐
9720 cally if the destination subrepositories contain the
9721 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
9722 tories requires converting a single repository at a time, from the bot‐
9723 tom up.
9724 An example showing how to convert a repository with subrepositories:
9726 # so convert knows the type when it sees a non empty destination
9728 $ hg init converted
9729 $ hg convert orig/sub1 converted/sub1
9731 $ hg convert orig/sub2 converted/sub2
9732 $ hg convert orig converted
9733 The following options are supported:
9735 convert.hg.clonebranches
9737 dispatch source branches in separate clones. The default is
9738 False.
9739 convert.hg.tagsbranch
9741 branch name for tag revisions, defaults to default.
9742 convert.hg.usebranchnames
9744 preserve branch names. The default is True.
9745 convert.hg.sourcename
9747 records the given string as a 'convert_source' extra value on
9748 each commit made in the target repository. The default is None.
9749 convert.hg.preserve-hash
9751 only works with mercurial sources. Make convert prevent perfor‐
9752 mance improvement to the list of modified files in commits when
9753 such an improvement would cause the hash of a commit to change.
9754 The default is False.
9755 All Destinations
9757 All destination types accept the following options:
9758 convert.skiptags
9760 does not convert tags from the source repo to the target repo.
9761 The default is False.
9762 Subversion Destination
9764 Original commit dates are not preserved by default.
9765 convert.svn.dangerous-set-commit-dates
9767 preserve original commit dates, forcefully setting svn:date re‐
9768 vision properties. This option is DANGEROUS and may break some
9769 subversion functionality for the resulting repository (e.g. fil‐
9770 tering revisions with date ranges in svn log), as original com‐
9771 mit dates are not guaranteed to be monotonically increasing.
9772 For commit dates setting to work destination repository must have
9774 pre-revprop-change hook configured to allow setting of svn:date revi‐
9775 sion properties. See Subversion documentation for more details.
9776 Options:
9778 --authors <FILE>
9780 username mapping filename (DEPRECATED) (use --authormap instead)
9781 -s,--source-type <TYPE>
9783 source repository type
9784 -d,--dest-type <TYPE>
9786 destination repository type
9787 -r,--rev <REV[+]>
9789 import up to source revision REV
9790 -A,--authormap <FILE>
9792 remap usernames using this file
9793 --filemap <FILE>
9795 remap file names using contents of file
9796 --full apply filemap changes by converting all files again
9798 --splicemap <FILE>
9800 splice synthesized history into place
9801 --branchmap <FILE>
9803 change branch names while converting
9804 --branchsort
9806 try to sort changesets by branches
9807 --datesort
9809 try to sort changesets by date
9810 --sourcesort
9812 preserve source changesets order
9813 --closesort
9815 try to reorder closed revisions
9816 [+] marked option can be specified multiple times
9818 eol
9820 automatically manage newlines in repository files
9821 This extension allows you to manage the type of line endings (CRLF or
9823 LF) that are used in the repository and in the local working directory.
9824 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
9825 thereby letting everybody use their OS native line endings.
9826 The extension reads its configuration from a versioned .hgeol configu‐
9828 ration file found in the root of the working directory. The .hgeol file
9829 use the same syntax as all other Mercurial configuration files. It uses
9830 two sections, [patterns] and [repository].
9831 The [patterns] section specifies how line endings should be converted
9833 between the working directory and the repository. The format is speci‐
9834 fied by a file pattern. The first match is used, so put more specific
9835 patterns first. The available line endings are LF, CRLF, and BIN.
9836 Files with the declared format of CRLF or LF are always checked out and
9838 stored in the repository in that format and files declared to be binary
9839 (BIN) are left unchanged. Additionally, native is an alias for checking
9840 out in the platform's default line ending: LF on Unix (including Mac OS
9841 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
9842 Mercurial's default behavior; it is only needed if you need to override
9843 a later, more general pattern.
9844 The optional [repository] section specifies the line endings to use for
9846 files stored in the repository. It has a single setting, native, which
9847 determines the storage line endings for files declared as native in the
9848 [patterns] section. It can be set to LF or CRLF. The default is LF. For
9849 example, this means that on Windows, files configured as native (CRLF
9850 by default) will be converted to LF when stored in the repository.
9851 Files declared as LF, CRLF, or BIN in the [patterns] section are always
9852 stored as-is in the repository.
9853 Example versioned .hgeol file:
9855 [patterns]
9857 **.py = native
9858 **.vcproj = CRLF
9859 **.txt = native
9860 Makefile = LF
9861 **.jpg = BIN
9862 [repository]
9864 native = LF
9865 Note The rules will first apply when files are touched in the working
9867 directory, e.g. by updating to null and back to tip to touch all
9868 files.
9869 The extension uses an optional [eol] section read from both the normal
9871 Mercurial configuration files and the .hgeol file, with the latter
9872 overriding the former. You can use that section to control the overall
9873 behavior. There are three settings:
9874 • eol.native (default os.linesep) can be set to LF or CRLF to override
9876 the default interpretation of native for checkout. This can be used
9877 with hg archive on Unix, say, to generate an archive where files have
9878 line endings for Windows.
9879 • eol.only-consistent (default True) can be set to False to make the
9881 extension convert files with inconsistent EOLs. Inconsistent means
9882 that there is both CRLF and LF present in the file. Such files are
9883 normally not touched under the assumption that they have mixed EOLs
9884 on purpose.
9885 • eol.fix-trailing-newline (default False) can be set to True to ensure
9887 that converted files end with a EOL character (either \n or \r\n as
9888 per the configured patterns).
9889 The extension provides cleverencode: and cleverdecode: filters like the
9891 deprecated win32text extension does. This means that you can disable
9892 win32text and enable eol and your filters will still work. You only
9893 need to these filters until you have prepared a .hgeol file.
9894 The win32text.forbid* hooks provided by the win32text extension have
9896 been unified into a single hook named eol.checkheadshook. The hook will
9897 lookup the expected line endings from the .hgeol file, which means you
9898 must migrate to a .hgeol file first before using the hook. eol.check‐
9899 headshook only checks heads, intermediate invalid revisions will be
9900 pushed. To forbid them completely, use the eol.checkallhook hook. These
9901 hooks are best used as pretxnchangegroup hooks.
9902 See hg help patterns for more information about the glob patterns used.
9904 extdiff
9906 command to allow external programs to compare revisions
9907 The extdiff Mercurial extension allows you to use external programs to
9909 compare revisions, or revision with working directory. The external
9910 diff programs are called with a configurable set of options and two
9911 non-option arguments: paths to directories containing snapshots of
9912 files to compare.
9913 If there is more than one file being compared and the "child" revision
9915 is the working directory, any modifications made in the external diff
9916 program will be copied back to the working directory from the temporary
9917 directory.
9918 The extdiff extension also allows you to configure new diff commands,
9920 so you do not need to type hg extdiff -p kdiff3 always.
9921 [extdiff]
9923 # add new command that runs GNU diff(1) in 'context diff' mode
9924 cdiff = gdiff -Nprc5
9925 ## or the old way:
9926 #cmd.cdiff = gdiff
9927 #opts.cdiff = -Nprc5
9928 # add new command called meld, runs meld (no need to name twice). If
9930 # the meld executable is not available, the meld tool in [merge-tools]
9931 # will be used, if available
9932 meld =
9933 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
9935 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
9936 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
9937 # your .vimrc
9938 vimdiff = gvim -f "+next" \
9939 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
9940 Tool arguments can include variables that are expanded at runtime:
9942 $parent1, $plabel1 - filename, descriptive label of first parent
9944 $child, $clabel - filename, descriptive label of child revision
9945 $parent2, $plabel2 - filename, descriptive label of second parent
9946 $root - repository root
9947 $parent is an alias for $parent1.
9948 The extdiff extension will look in your [diff-tools] and [merge-tools]
9950 sections for diff tool arguments, when none are specified in [extdiff].
9951 [extdiff]
9953 kdiff3 =
9954 [diff-tools]
9956 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9957 If a program has a graphical interface, it might be interesting to tell
9959 Mercurial about it. It will prevent the program from being mistakenly
9960 used in a terminal-only environment (such as an SSH terminal session),
9961 and will make hg extdiff --per-file open multiple file diffs at once
9962 instead of one by one (if you still want to open file diffs one by one,
9963 you can use the --confirm option).
9964 Declaring that a tool has a graphical interface can be done with the
9966 gui flag next to where diffargs are specified:
9967 [diff-tools]
9969 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9970 kdiff3.gui = true
9971 You can use -I/-X and list of file or directory names like normal hg
9973 diff command. The extdiff extension makes snapshots of only needed
9974 files, so running the external diff program will actually be pretty
9975 fast (at least faster than having to compare the entire tree).
9976 Commands
9978 File content management
9979 extdiff
9980 use external program to diff repository (or selected files):
9981 hg extdiff [OPT]... [FILE]...
9983 Show differences between revisions for the specified files, using an
9985 external program. The default program used is diff, with default op‐
9986 tions "-Npru".
9987 To select a different program, use the -p/--program option. The program
9989 will be passed the names of two directories to compare, unless the
9990 --per-file option is specified (see below). To pass additional options
9991 to the program, use -o/--option. These will be passed before the names
9992 of the directories or files to compare.
9993 The --from, --to, and --change options work the same way they do for hg
9995 diff.
9996 The --per-file option runs the external program repeatedly on each file
9998 to diff, instead of once on two directories. By default, this happens
9999 one by one, where the next file diff is open in the external program
10000 only once the previous external program (for the previous file diff)
10001 has exited. If the external program has a graphical interface, it can
10002 open all the file diffs at once instead of one by one. See hg help -e
10003 extdiff for information about how to tell Mercurial that a given pro‐
10004 gram has a graphical interface.
10005 The --confirm option will prompt the user before each invocation of the
10007 external program. It is ignored if --per-file isn't specified.
10008 Options:
10010 -p,--program <CMD>
10012 comparison program to run
10013 -o,--option <OPT[+]>
10015 pass option to comparison program
10016 -r,--rev <REV[+]>
10018 revision (DEPRECATED)
10019 --from <REV1>
10021 revision to diff from
10022 --to <REV2>
10024 revision to diff to
10025 -c,--change <REV>
10027 change made by revision
10028 --per-file
10030 compare each file instead of revision snapshots
10031 --confirm
10033 prompt user before each external program invocation
10034 --patch
10036 compare patches for two revisions
10037 -I,--include <PATTERN[+]>
10039 include names matching the given patterns
10040 -X,--exclude <PATTERN[+]>
10042 exclude names matching the given patterns
10043 -S, --subrepos
10045 recurse into subrepositories
10046 [+] marked option can be specified multiple times
10048 factotum
10050 http authentication with factotum
10051 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
10053 platforms to provide authentication information for HTTP access. Con‐
10054 figuration entries specified in the auth section as well as authentica‐
10055 tion information provided in the repository URL are fully supported. If
10056 no prefix is specified, a value of "*" will be assumed.
10057 By default, keys are specified as:
10059 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
10061 If the factotum extension is unable to read the required key, one will
10063 be requested interactively.
10064 A configuration section is available to customize runtime behavior. By
10066 default, these entries are:
10067 [factotum]
10069 executable = /bin/auth/factotum
10070 mountpoint = /mnt/factotum
10071 service = hg
10072 The executable entry defines the full path to the factotum binary. The
10074 mountpoint entry defines the path to the factotum file service. Lastly,
10075 the service entry controls the service name used when reading keys.
10076 fastannotate
10078 yet another annotate implementation that might be faster (EXPERIMENTAL)
10079 The fastannotate extension provides a 'fastannotate' command that makes
10081 use of the linelog data structure as a cache layer and is expected to
10082 be faster than the vanilla 'annotate' if the cache is present.
10083 In most cases, fastannotate requires a setup that mainbranch is some
10085 pointer that always moves forward, to be most efficient.
10086 Using fastannotate together with linkrevcache would speed up building
10088 the annotate cache greatly. Run "debugbuildlinkrevcache" before "debug‐
10089 buildannotatecache".
10090 [fastannotate]
10092 # specify the main branch head. the internal linelog will only contain
10093 # the linear (ignoring p2) "mainbranch". since linelog cannot move
10094 # backwards without a rebuild, this should be something that always moves
10095 # forward, usually it is "master" or "@".
10096 mainbranch = master
10097 # fastannotate supports different modes to expose its feature.
10099 # a list of combination:
10100 # - fastannotate: expose the feature via the "fastannotate" command which
10101 # deals with everything in a most efficient way, and provides extra
10102 # features like --deleted etc.
10103 # - fctx: replace fctx.annotate implementation. note:
10104 # a. it is less efficient than the "fastannotate" command
10105 # b. it will make it practically impossible to access the old (disk
10106 # side-effect free) annotate implementation
10107 # c. it implies "hgweb".
10108 # - hgweb: replace hgweb's annotate implementation. conflict with "fctx".
10109 # (default: fastannotate)
10110 modes = fastannotate
10111 # default format when no format flags are used (default: number)
10113 defaultformat = changeset, user, date
10114 # serve the annotate cache via wire protocol (default: False)
10116 # tip: the .hg/fastannotate directory is portable - can be rsynced
10117 server = True
10118 # build annotate cache on demand for every client request (default: True)
10120 # disabling it could make server response faster, useful when there is a
10121 # cronjob building the cache.
10122 serverbuildondemand = True
10123 # update local annotate cache from remote on demand
10125 client = False
10126 # path to use when connecting to the remote server (default: default)
10128 remotepath = default
10129 # minimal length of the history of a file required to fetch linelog from
10131 # the server. (default: 10)
10132 clientfetchthreshold = 10
10133 # for "fctx" mode, always follow renames regardless of command line option.
10135 # this is a BC with the original command but will reduced the space needed
10136 # for annotate cache, and is useful for client-server setup since the
10137 # server will only provide annotate cache with default options (i.e. with
10138 # follow). do not affect "fastannotate" mode. (default: True)
10139 forcefollow = True
10140 # for "fctx" mode, always treat file as text files, to skip the "isbinary"
10142 # check. this is consistent with the "fastannotate" command and could help
10143 # to avoid a file fetch if remotefilelog is used. (default: True)
10144 forcetext = True
10145 # use unfiltered repo for better performance.
10147 unfilteredrepo = True
10148 # sacrifice correctness in some corner cases for performance. it does not
10150 # affect the correctness of the annotate cache being built. the option
10151 # is experimental and may disappear in the future (default: False)
10152 perfhack = True
10153 Commands
10155 Uncategorized commands
10156 fastexport
10157 export repositories as git fast-import stream
10158 Commands
10160 Change import/export
10161 fastexport
10162 export repository as git fast-import stream:
10163 hg fastexport [OPTION]... [REV]...
10165 This command lets you dump a repository as a human-readable text
10167 stream. It can be piped into corresponding import routines like "git
10168 fast-import". Incremental dumps can be created by using marks files.
10169 Options:
10171 -r,--rev <REV[+]>
10173 revisions to export
10174 -i,--import-marks <FILE>
10176 old marks file to read
10177 -e,--export-marks <FILE>
10179 new marks file to write
10180 -A,--authormap <FILE>
10182 remap usernames using this file
10183 [+] marked option can be specified multiple times
10185 fetch
10187 pull, update and merge in one command (DEPRECATED)
10188 Commands
10190 Remote repository management
10191 fetch
10192 pull changes from a remote repository, merge new changes if needed.:
10193 hg fetch [SOURCE]
10195 This finds all changes from the repository at the specified path or URL
10197 and adds them to the local repository.
10198 If the pulled changes add a new branch head, the head is automatically
10200 merged, and the result of the merge is committed. Otherwise, the work‐
10201 ing directory is updated to include the new changes.
10202 When a merge is needed, the working directory is first updated to the
10204 newly pulled changes. Local changes are then merged into the pulled
10205 changes. To switch the merge order, use --switch-parent.
10206 See hg help dates for a list of formats valid for -d/--date.
10208 Returns 0 on success.
10210 Options:
10212 -r,--rev <REV[+]>
10214 a specific revision you would like to pull
10215 --edit invoke editor on commit messages
10217 --force-editor
10219 edit commit message (DEPRECATED)
10220 --switch-parent
10222 switch parents when merging
10223 -m,--message <TEXT>
10225 use text as commit message
10226 -l,--logfile <FILE>
10228 read commit message from file
10229 -d,--date <DATE>
10231 record the specified date as commit date
10232 -u,--user <USER>
10234 record the specified user as committer
10235 -e,--ssh <CMD>
10237 specify ssh command to use
10238 --remotecmd <CMD>
10240 specify hg command to run on the remote side
10241 --insecure
10243 do not verify server certificate (ignoring web.cacerts config)
10244 [+] marked option can be specified multiple times
10246 fix
10248 rewrite file content in changesets or working copy (EXPERIMENTAL)
10249 Provides a command that runs configured tools on the contents of modi‐
10251 fied files, writing back any fixes to the working copy or replacing
10252 changesets.
10253 Here is an example configuration that causes hg fix to apply automatic
10255 formatting fixes to modified lines in C++ code:
10256 [fix]
10258 clang-format:command=clang-format --assume-filename={rootpath}
10259 clang-format:linerange=--lines={first}:{last}
10260 clang-format:pattern=set:**.cpp or **.hpp
10261 The :command suboption forms the first part of the shell command that
10263 will be used to fix a file. The content of the file is passed on stan‐
10264 dard input, and the fixed file content is expected on standard output.
10265 Any output on standard error will be displayed as a warning. If the
10266 exit status is not zero, the file will not be affected. A placeholder
10267 warning is displayed if there is a non-zero exit status but no standard
10268 error output. Some values may be substituted into the command:
10269 {rootpath} The path of the file being fixed, relative to the repo root
10271 {basename} The name of the file being fixed, without the directory path
10272 If the :linerange suboption is set, the tool will only be run if there
10274 are changed lines in a file. The value of this suboption is appended to
10275 the shell command once for every range of changed lines in the file.
10276 Some values may be substituted into the command:
10277 {first} The 1-based line number of the first line in the modified range
10279 {last} The 1-based line number of the last line in the modified range
10280 Deleted sections of a file will be ignored by :linerange, because there
10282 is no corresponding line range in the version being fixed.
10283 By default, tools that set :linerange will only be executed if there is
10285 at least one changed line range. This is meant to prevent accidents
10286 like running a code formatter in such a way that it unexpectedly refor‐
10287 mats the whole file. If such a tool needs to operate on unchanged
10288 files, it should set the :skipclean suboption to false.
10289 The :pattern suboption determines which files will be passed through
10291 each configured tool. See hg help patterns for possible values. How‐
10292 ever, all patterns are relative to the repo root, even if that text
10293 says they are relative to the current working directory. If there are
10294 file arguments to hg fix, the intersection of these patterns is used.
10295 There is also a configurable limit for the maximum size of file that
10297 will be processed by hg fix:
10298 [fix]
10300 maxfilesize = 2MB
10301 Normally, execution of configured tools will continue after a failure
10303 (indicated by a non-zero exit status). It can also be configured to
10304 abort after the first such failure, so that no files will be affected
10305 if any tool fails. This abort will also cause hg fix to exit with a
10306 non-zero status:
10307 [fix]
10309 failure = abort
10310 When multiple tools are configured to affect a file, they execute in an
10312 order defined by the :priority suboption. The priority suboption has a
10313 default value of zero for each tool. Tools are executed in order of de‐
10314 scending priority. The execution order of tools with equal priority is
10315 unspecified. For example, you could use the 'sort' and 'head' utilities
10316 to keep only the 10 smallest numbers in a text file by ensuring that
10317 'sort' runs before 'head':
10318 [fix]
10320 sort:command = sort -n
10321 head:command = head -n 10
10322 sort:pattern = numbers.txt
10323 head:pattern = numbers.txt
10324 sort:priority = 2
10325 head:priority = 1
10326 To account for changes made by each tool, the line numbers used for in‐
10328 cremental formatting are recomputed before executing the next tool. So,
10329 each tool may see different values for the arguments added by the :lin‐
10330 erange suboption.
10331 Each fixer tool is allowed to return some metadata in addition to the
10333 fixed file content. The metadata must be placed before the file content
10334 on stdout, separated from the file content by a zero byte. The metadata
10335 is parsed as a JSON value (so, it should be UTF-8 encoded and contain
10336 no zero bytes). A fixer tool is expected to produce this metadata en‐
10337 coding if and only if the :metadata suboption is true:
10338 [fix]
10340 tool:command = tool --prepend-json-metadata
10341 tool:metadata = true
10342 The metadata values are passed to hooks, which can be used to print
10344 summaries or perform other post-fixing work. The supported hooks are:
10345 "postfixfile"
10347 Run once for each file in each revision where any fixer tools made changes
10348 to the file content. Provides "$HG_REV" and "$HG_PATH" to identify the file,
10349 and "$HG_METADATA" with a map of fixer names to metadata values from fixer
10350 tools that affected the file. Fixer tools that didn't affect the file have a
10351 value of None. Only fixer tools that executed are present in the metadata.
10352 "postfix"
10354 Run once after all files and revisions have been handled. Provides
10355 "$HG_REPLACEMENTS" with information about what revisions were created and
10356 made obsolete. Provides a boolean "$HG_WDIRWRITTEN" to indicate whether any
10357 files in the working copy were updated. Provides a list "$HG_METADATA"
10358 mapping fixer tool names to lists of metadata values returned from
10359 executions that modified a file. This aggregates the same metadata
10360 previously passed to the "postfixfile" hook.
10361 Fixer tools are run in the repository's root directory. This allows
10363 them to read configuration files from the working copy, or even write
10364 to the working copy. The working copy is not updated to match the re‐
10365 vision being fixed. In fact, several revisions may be fixed in paral‐
10366 lel. Writes to the working copy are not amended into the revision being
10367 fixed; fixer tools should always write fixed file content back to std‐
10368 out as documented above.
10369 Commands
10371 File content management
10372 fix
10373 rewrite file content in changesets or working directory:
10374 hg fix [OPTION]... [FILE]...
10376 Runs any configured tools to fix the content of files. Only affects
10378 files with changes, unless file arguments are provided. Only affects
10379 changed lines of files, unless the --whole flag is used. Some tools may
10380 always affect the whole file regardless of --whole.
10381 If --working-dir is used, files with uncommitted changes in the working
10383 copy will be fixed. Note that no backup are made.
10384 If revisions are specified with --source, those revisions and their de‐
10386 scendants will be checked, and they may be replaced with new revisions
10387 that have fixed file content. By automatically including the descen‐
10388 dants, no merging, rebasing, or evolution will be required. If an an‐
10389 cestor of the working copy is included, then the working copy itself
10390 will also be fixed, and the working copy will be updated to the fixed
10391 parent.
10392 When determining what lines of each file to fix at each revision, the
10394 whole set of revisions being fixed is considered, so that fixes to ear‐
10395 lier revisions are not forgotten in later ones. The --base flag can be
10396 used to override this default behavior, though it is not usually desir‐
10397 able to do so.
10398 Options:
10400 --all fix all non-public non-obsolete revisions
10402 --base <REV[+]>
10404 revisions to diff against (overrides automatic selection, and
10405 applies to every revision being fixed)
10406 -r,--rev <REV[+]>
10408 revisions to fix (ADVANCED)
10409 -s,--source <REV[+]>
10411 fix the specified revisions and their descendants
10412 -w, --working-dir
10414 fix the working directory
10415 --whole
10417 always fix every line of a file
10418 [+] marked option can be specified multiple times
10420 fsmonitor
10422 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
10423 Integrates the file-watching program Watchman with Mercurial to produce
10425 faster status results.
10426 On a particular Linux system, for a real-world repository with over
10428 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
10429 the same system, with fsmonitor it takes about 0.3 seconds.
10430 fsmonitor requires no configuration -- it will tell Watchman about your
10432 repository as necessary. You'll need to install Watchman from
10433 https://facebook.github.io/watchman/ and make sure it is in your PATH.
10434 fsmonitor is incompatible with the largefiles and eol extensions, and
10436 will disable itself if any of those are active.
10437 The following configuration options exist:
10439 [fsmonitor]
10441 mode = {off, on, paranoid}
10442 When mode = off, fsmonitor will disable itself (similar to not loading
10444 the extension at all). When mode = on, fsmonitor will be enabled (the
10445 default). When mode = paranoid, fsmonitor will query both Watchman and
10446 the filesystem, and ensure that the results are consistent.
10447 [fsmonitor]
10449 timeout = (float)
10450 A value, in seconds, that determines how long fsmonitor will wait for
10452 Watchman to return results. Defaults to 2.0.
10453 [fsmonitor]
10455 blacklistusers = (list of userids)
10456 A list of usernames for which fsmonitor will disable itself altogether.
10458 [fsmonitor]
10460 walk_on_invalidate = (boolean)
10461 Whether or not to walk the whole repo ourselves when our cached state
10463 has been invalidated, for example when Watchman has been restarted or
10464 .hgignore rules have been changed. Walking the repo in that case can
10465 result in competing for I/O with Watchman. For large repos it is recom‐
10466 mended to set this value to false. You may wish to set this to true if
10467 you have a very fast filesystem that can outpace the IPC overhead of
10468 getting the result data for the full repo from Watchman. Defaults to
10469 false.
10470 [fsmonitor]
10472 warn_when_unused = (boolean)
10473 Whether to print a warning during certain operations when fsmonitor
10475 would be beneficial to performance but isn't enabled.
10476 [fsmonitor]
10478 warn_update_file_count = (integer)
10479 # or when mercurial is built with rust support
10480 warn_update_file_count_rust = (integer)
10481 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
10483 be printed during working directory updates if this many files will be
10484 created.
10485 git
10487 grant Mercurial the ability to operate on Git repositories. (EXPERIMEN‐
10488 TAL)
10489 This is currently super experimental. It probably will consume your
10491 firstborn a la Rumpelstiltskin, etc.
10492 githelp
10494 try mapping git commands to Mercurial commands
10495 Tries to map a given git command to a Mercurial command:
10497 $ hg githelp -- git checkout master hg update master
10499 If an unknown command or parameter combination is detected, an error is
10501 produced.
10502 Commands
10504 Help
10505 githelp
10506 suggests the Mercurial equivalent of the given git command:
10507 hg githelp
10509 Usage: hg githelp -- <git command>
10511 aliases: git
10513 gpg
10515 commands to sign and verify changesets
10516 Commands
10518 Signing changes (GPG)
10519 sigcheck
10520 verify all the signatures there may be for a particular revision:
10521 hg sigcheck REV
10523 verify all the signatures there may be for a particular revision
10525 sign
10527 add a signature for the current or given revision:
10528 hg sign [OPTION]... [REV]...
10530 If no revision is given, the parent of the working directory is used,
10532 or tip if no revision is checked out.
10533 The gpg.cmd config setting can be used to specify the command to run. A
10535 default key can be specified with gpg.key.
10536 See hg help dates for a list of formats valid for -d/--date.
10538 Options:
10540 -l, --local
10542 make the signature local
10543 -f, --force
10545 sign even if the sigfile is modified
10546 --no-commit
10548 do not commit the sigfile after signing
10549 -k,--key <ID>
10551 the key id to sign with
10552 -m,--message <TEXT>
10554 use text as commit message
10555 -e, --edit
10557 invoke editor on commit messages
10558 -d,--date <DATE>
10560 record the specified date as commit date
10561 -u,--user <USER>
10563 record the specified user as committer
10564 sigs
10566 list signed changesets:
10567 hg sigs
10569 list signed changesets
10571 graphlog
10573 command to view revision graphs from a shell (DEPRECATED)
10574 The functionality of this extension has been include in core Mercurial
10576 since version 2.3. Please use hg log -G ... instead.
10577 This extension adds a --graph option to the incoming, outgoing and log
10579 commands. When this options is given, an ASCII representation of the
10580 revision graph is also shown.
10581 Commands
10583 Change navigation
10584 glog
10585 show revision history alongside an ASCII revision graph:
10586 hg glog [OPTION]... [FILE]
10588 Print a revision history alongside a revision graph drawn with ASCII
10590 characters.
10591 Nodes printed as an @ character are parents of the working directory.
10593 This is an alias to hg log -G.
10595 Options:
10597 -f, --follow
10599 follow changeset history, or file history across copies and re‐
10600 names
10601 --follow-first
10603 only follow the first parent of merge changesets (DEPRECATED)
10604 -d,--date <DATE>
10606 show revisions matching date spec
10607 -C, --copies
10609 show copied files
10610 -k,--keyword <TEXT[+]>
10612 do case-insensitive search for a given text
10613 -r,--rev <REV[+]>
10615 show the specified revision or revset
10616 --removed
10618 include revisions where files were removed
10619 -m, --only-merges
10621 show only merges (DEPRECATED)
10622 -u,--user <USER[+]>
10624 revisions committed by user
10625 --only-branch <BRANCH[+]>
10627 show only changesets within the given named branch (DEPRECATED)
10628 -b,--branch <BRANCH[+]>
10630 show changesets within the given named branch
10631 -P,--prune <REV[+]>
10633 do not display revision or any of its ancestors
10634 -p, --patch
10636 show patch
10637 -g, --git
10639 use git extended diff format
10640 -l,--limit <NUM>
10642 limit number of changes displayed
10643 -M, --no-merges
10645 do not show merges
10646 --stat output diffstat-style summary of changes
10648 -G, --graph
10650 show the revision DAG
10651 --style <STYLE>
10653 display using template map file (DEPRECATED)
10654 -T,--template <TEMPLATE>
10656 display with template
10657 -I,--include <PATTERN[+]>
10659 include names matching the given patterns
10660 -X,--exclude <PATTERN[+]>
10662 exclude names matching the given patterns
10663 [+] marked option can be specified multiple times
10665 hgk
10667 browse the repository in a graphical way
10668 The hgk extension allows browsing the history of a repository in a
10670 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
10671 distributed with Mercurial.)
10672 hgk consists of two parts: a Tcl script that does the displaying and
10674 querying of information, and an extension to Mercurial named hgk.py,
10675 which provides hooks for hgk to get information. hgk can be found in
10676 the contrib directory, and the extension is shipped in the hgext repos‐
10677 itory, and needs to be enabled.
10678 The hg view command will launch the hgk Tcl script. For this command to
10680 work, hgk must be in your search path. Alternately, you can specify the
10681 path to hgk in your configuration file:
10682 [hgk]
10684 path = /location/of/hgk
10685 hgk can make use of the extdiff extension to visualize revisions. As‐
10687 suming you had already configured extdiff vdiff command, just add:
10688 [hgk]
10690 vdiff=vdiff
10691 Revisions context menu will now display additional entries to fire vd‐
10693 iff on hovered and selected revisions.
10694 Commands
10696 Change navigation
10697 view
10698 start interactive history viewer:
10699 hg view [-l LIMIT] [REVRANGE]
10701 start interactive history viewer
10703 Options:
10705 -l,--limit <NUM>
10707 limit number of changes displayed
10708 Uncategorized commands
10710 highlight
10711 syntax highlighting for hgweb (requires Pygments)
10712 It depends on the Pygments syntax highlighting library:
10714 http://pygments.org/
10715 There are the following configuration options:
10717 [web]
10719 pygments_style = <style> (default: colorful)
10720 highlightfiles = <fileset> (default: size('<5M'))
10721 highlightonlymatchfilename = <bool> (default False)
10722 highlightonlymatchfilename will only highlight files if their type
10724 could be identified by their filename. When this is not enabled (the
10725 default), Pygments will try very hard to identify the file type from
10726 content and any match (even matches with a low confidence score) will
10727 be used.
10728 histedit
10730 interactive history editing
10731 With this extension installed, Mercurial gains one new command: histe‐
10733 dit. Usage is as follows, assuming the following history:
10734 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
10736 | Add delta
10737 |
10738 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
10739 | Add gamma
10740 |
10741 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
10742 | Add beta
10743 |
10744 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10745 Add alpha
10746 If you were to run hg histedit c561b4e977df, you would see the follow‐
10748 ing file open in your editor:
10749 pick c561b4e977df Add beta
10751 pick 030b686bedc4 Add gamma
10752 pick 7c2fd3b9020c Add delta
10753 # Edit history between c561b4e977df and 7c2fd3b9020c
10755 #
10756 # Commits are listed from least to most recent
10757 #
10758 # Commands:
10759 # p, pick = use commit
10760 # e, edit = use commit, but allow edits before making new commit
10761 # f, fold = use commit, but combine it with the one above
10762 # r, roll = like fold, but discard this commit's description and date
10763 # d, drop = remove commit from history
10764 # m, mess = edit commit message without changing commit content
10765 # b, base = checkout changeset and apply further changesets from there
10766 #
10767 In this file, lines beginning with # are ignored. You must specify a
10769 rule for each revision in your history. For example, if you had meant
10770 to add gamma before beta, and then wanted to add delta in the same re‐
10771 vision as beta, you would reorganize the file to look like this:
10772 pick 030b686bedc4 Add gamma
10774 pick c561b4e977df Add beta
10775 fold 7c2fd3b9020c Add delta
10776 # Edit history between c561b4e977df and 7c2fd3b9020c
10778 #
10779 # Commits are listed from least to most recent
10780 #
10781 # Commands:
10782 # p, pick = use commit
10783 # e, edit = use commit, but allow edits before making new commit
10784 # f, fold = use commit, but combine it with the one above
10785 # r, roll = like fold, but discard this commit's description and date
10786 # d, drop = remove commit from history
10787 # m, mess = edit commit message without changing commit content
10788 # b, base = checkout changeset and apply further changesets from there
10789 #
10790 At which point you close the editor and histedit starts working. When
10792 you specify a fold operation, histedit will open an editor when it
10793 folds those revisions together, offering you a chance to clean up the
10794 commit message:
10795 Add beta
10797 ***
10798 Add delta
10799 Edit the commit message to your liking, then close the editor. The date
10801 used for the commit will be the later of the two commits' dates. For
10802 this example, let's assume that the commit message was changed to Add
10803 beta and delta. After histedit has run and had a chance to remove any
10804 old or temporary revisions it needed, the history looks like this:
10805 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
10807 | Add beta and delta.
10808 |
10809 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10810 | Add gamma
10811 |
10812 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10813 Add alpha
10814 Note that histedit does not remove any revisions (even its own tempo‐
10816 rary ones) until after it has completed all the editing operations, so
10817 it will probably perform several strip operations when it's done. For
10818 the above example, it had to run strip twice. Strip can be slow depend‐
10819 ing on a variety of factors, so you might need to be a little patient.
10820 You can choose to keep the original revisions by passing the --keep
10821 flag.
10822 The edit operation will drop you back to a command prompt, allowing you
10824 to edit files freely, or even use hg record to commit some changes as a
10825 separate commit. When you're done, any remaining uncommitted changes
10826 will be committed as well. When done, run hg histedit --continue to
10827 finish this step. If there are uncommitted changes, you'll be prompted
10828 for a new commit message, but the default commit message will be the
10829 original message for the edit ed revision, and the date of the original
10830 commit will be preserved.
10831 The message operation will give you a chance to revise a commit message
10833 without changing the contents. It's a shortcut for doing edit immedi‐
10834 ately followed by hg histedit --continue`.
10835 If histedit encounters a conflict when moving a revision (while han‐
10837 dling pick or fold), it'll stop in a similar manner to edit with the
10838 difference that it won't prompt you for a commit message when done. If
10839 you decide at this point that you don't like how much work it will be
10840 to rearrange history, or that you made a mistake, you can use hg histe‐
10841 dit --abort to abandon the new changes you have made and return to the
10842 state before you attempted to edit your history.
10843 If we clone the histedit-ed example repository above and add four more
10845 changes, such that we have the following history:
10846 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
10848 | Add theta
10849 |
10850 o 5 140988835471 2009-04-27 18:04 -0500 stefan
10851 | Add eta
10852 |
10853 o 4 122930637314 2009-04-27 18:04 -0500 stefan
10854 | Add zeta
10855 |
10856 o 3 836302820282 2009-04-27 18:04 -0500 stefan
10857 | Add epsilon
10858 |
10859 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
10860 | Add beta and delta.
10861 |
10862 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10863 | Add gamma
10864 |
10865 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10866 Add alpha
10867 If you run hg histedit --outgoing on the clone then it is the same as
10869 running hg histedit 836302820282. If you need plan to push to a reposi‐
10870 tory that Mercurial does not detect to be related to the source repo,
10871 you can add a --force option.
10872 Config
10874 Histedit rule lines are truncated to 80 characters by default. You can
10875 customize this behavior by setting a different length in your configu‐
10876 ration file:
10877 [histedit]
10879 linelen = 120 # truncate rule lines at 120 characters
10880 The summary of a change can be customized as well:
10882 [histedit]
10884 summary-template = '{rev} {bookmarks} {desc|firstline}'
10885 The customized summary should be kept short enough that rule lines will
10887 fit in the configured line length. See above if that requires cus‐
10888 tomization.
10889 hg histedit attempts to automatically choose an appropriate base revi‐
10891 sion to use. To change which base revision is used, define a revset in
10892 your configuration file:
10893 [histedit]
10895 defaultrev = only(.) & draft()
10896 By default each edited revision needs to be present in histedit com‐
10898 mands. To remove revision you need to use drop operation. You can con‐
10899 figure the drop to be implicit for missing commits by adding:
10900 [histedit]
10902 dropmissing = True
10903 By default, histedit will close the transaction after each action. For
10905 performance purposes, you can configure histedit to use a single trans‐
10906 action across the entire histedit. WARNING: This setting introduces a
10907 significant risk of losing the work you've done in a histedit if the
10908 histedit aborts unexpectedly:
10909 [histedit]
10911 singletransaction = True
10912 Commands
10914 Change manipulation
10915 histedit
10916 interactively edit changeset history:
10917 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
10919 This command lets you edit a linear series of changesets (up to and in‐
10921 cluding the working directory, which should be clean). You can:
10922 • pick to [re]order a changeset
10924 • drop to omit changeset
10926 • mess to reword the changeset commit message
10928 • fold to combine it with the preceding changeset (using the later
10930 date)
10931 • roll like fold, but discarding this commit's description and date
10933 • edit to edit this changeset (preserving date)
10935 • base to checkout changeset and apply further changesets from there
10937 There are a number of ways to select the root changeset:
10939 • Specify ANCESTOR directly
10941 • Use --outgoing -- it will be the first linear changeset not included
10943 in destination. (See hg help config.paths.default-push)
10944 • Otherwise, the value from the "histedit.defaultrev" config option is
10946 used as a revset to select the base revision when ANCESTOR is not
10947 specified. The first revision returned by the revset is used. By de‐
10948 fault, this selects the editable history that is unique to the ances‐
10949 try of the working directory.
10950 If you use --outgoing, this command will abort if there are ambiguous
10952 outgoing revisions. For example, if there are multiple branches con‐
10953 taining outgoing revisions.
10954 Use "min(outgoing() and ::.)" or similar revset specification instead
10956 of --outgoing to specify edit target revision exactly in such ambiguous
10957 situation. See hg help revsets for detail about selecting revisions.
10958 Examples:
10960 • A number of changes have been made. Revision 3 is no longer
10962 needed.
10963 Start history editing from revision 3:
10965 hg histedit -r 3
10967 An editor opens, containing the list of revisions, with specific
10969 actions specified:
10970 pick 5339bf82f0ca 3 Zworgle the foobar
10972 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10973 pick 0a9639fcda9d 5 Morgify the cromulancy
10974 Additional information about the possible actions to take appears
10976 below the list of revisions.
10977 To remove revision 3 from the history, its action (at the begin‐
10979 ning of the relevant line) is changed to 'drop':
10980 drop 5339bf82f0ca 3 Zworgle the foobar
10982 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10983 pick 0a9639fcda9d 5 Morgify the cromulancy
10984 • A number of changes have been made. Revision 2 and 4 need to be
10986 swapped.
10987 Start history editing from revision 2:
10989 hg histedit -r 2
10991 An editor opens, containing the list of revisions, with specific
10993 actions specified:
10994 pick 252a1af424ad 2 Blorb a morgwazzle
10996 pick 5339bf82f0ca 3 Zworgle the foobar
10997 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10998 To swap revision 2 and 4, its lines are swapped in the editor:
11000 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11002 pick 5339bf82f0ca 3 Zworgle the foobar
11003 pick 252a1af424ad 2 Blorb a morgwazzle
11004 Returns 0 on success, 1 if user intervention is required (not only for
11006 intentional "edit" command, but also for resolving unexpected con‐
11007 flicts).
11008 Options:
11010 --commands <FILE>
11012 read history edits from the specified file
11013 -c, --continue
11015 continue an edit already in progress
11016 --edit-plan
11018 edit remaining actions list
11019 -k, --keep
11021 don't strip old nodes after edit is complete
11022 --abort
11024 abort an edit in progress
11025 -o, --outgoing
11027 changesets not found in destination
11028 -f, --force
11030 force outgoing even for unrelated repositories
11031 -r,--rev <REV[+]>
11033 first revision to be edited
11034 -T,--template <TEMPLATE>
11036 display with template
11037 [+] marked option can be specified multiple times
11039 hooklib
11041 collection of simple hooks for common tasks (EXPERIMENTAL)
11042 This extension provides a number of simple hooks to handle issues com‐
11044 monly found in repositories with many contributors: - email notifica‐
11045 tion when changesets move from draft to public phase - email notifica‐
11046 tion when changesets are obsoleted - enforcement of draft phase for all
11047 incoming changesets - enforcement of a no-branch-merge policy - en‐
11048 forcement of a no-multiple-heads policy
11049 The implementation of the hooks is subject to change, e.g. whether to
11051 implement them as individual hooks or merge them into the notify exten‐
11052 sion as option. The functionality itself is planned to be supported
11053 long-term.
11054 infinitepush
11056 store some pushes in a remote blob store on the server (EXPERIMEN‐
11057 TAL)
11058 IMPORTANT: if you use this extension, please contact
11060 mercurial-devel@mercurial-scm.org ASAP. This extension is believed to
11061 be unused and barring learning of users of this functionality, we will
11062 delete this code at the end of 2020.
11063 [infinitepush] # Server-side and client-side option. Pattern of the
11065 infinitepush bookmark branchpattern = PATTERN
11066 # Server or client server = False
11068 # Server-side option. Possible values: 'disk' or 'sql'. Fails if not
11070 set indextype = disk
11071 # Server-side option. Used only if indextype=sql. # Format:
11073 'IP:PORT:DB_NAME:USER:PASSWORD' sqlhost = IP:PORT:DB_NAME:USER:PASS‐
11074 WORD
11075 # Server-side option. Used only if indextype=disk. # Filesystem
11077 path to the index store indexpath = PATH
11078 # Server-side option. Possible values: 'disk' or 'external' # Fails
11080 if not set storetype = disk
11081 # Server-side option. # Path to the binary that will save bundle to
11083 the bundlestore # Formatted cmd line will be passed to it (see
11084 put_args) put_binary = put
11085 # Serser-side option. Used only if storetype=external. # Format
11087 cmd-line string for put binary. Placeholder: {filename} put_args =
11088 {filename}
11089 # Server-side option. # Path to the binary that get bundle from the
11091 bundlestore. # Formatted cmd line will be passed to it (see
11092 get_args) get_binary = get
11093 # Serser-side option. Used only if storetype=external. # Format
11095 cmd-line string for get binary. Placeholders: {filename} {handle}
11096 get_args = {filename} {handle}
11097 # Server-side option logfile = FIlE
11099 # Server-side option loglevel = DEBUG
11101 # Server-side option. Used only if indextype=sql. # Sets mysql
11103 wait_timeout option. waittimeout = 300
11104 # Server-side option. Used only if indextype=sql. # Sets mysql inn‐
11106 odb_lock_wait_timeout option. locktimeout = 120
11107 # Server-side option. Used only if indextype=sql. # Name of the
11109 repository reponame = ''
11110 # Client-side option. Used by --list-remote option. List of remote
11112 scratch # patterns to list if no patterns are specified. default‐
11113 remotepatterns = ['*']
11114 # Instructs infinitepush to forward all received bundle2 parts to
11116 the # bundle for storage. Defaults to False. storeallparts = True
11117 # routes each incoming push to the bundlestore. defaults to False
11119 pushtobundlestore = True
11120 [remotenames] # Client-side option # This option should be set only
11122 if remotenames extension is enabled. # Whether remote bookmarks are
11123 tracked by remotenames extension. bookmarks = True
11124 journal
11126 track previous positions of bookmarks (EXPERIMENTAL)
11127 This extension adds a new command: hg journal, which shows you where
11129 bookmarks were previously located.
11130 Commands
11132 Change organization
11133 journal
11134 show the previous position of bookmarks and the working copy:
11135 hg journal [OPTION]... [BOOKMARKNAME]
11137 The journal is used to see the previous commits that bookmarks and the
11139 working copy pointed to. By default the previous locations for the
11140 working copy. Passing a bookmark name will show all the previous posi‐
11141 tions of that bookmark. Use the --all switch to show previous locations
11142 for all bookmarks and the working copy; each line will then include the
11143 bookmark name, or '.' for the working copy, as well.
11144 If name starts with re:, the remainder of the name is treated as a reg‐
11146 ular expression. To match a name that actually starts with re:, use the
11147 prefix literal:.
11148 By default hg journal only shows the commit hash and the command that
11150 was running at that time. -v/--verbose will show the prior hash, the
11151 user, and the time at which it happened.
11152 Use -c/--commits to output log information on each commit hash; at this
11154 point you can use the usual --patch, --git, --stat and --template
11155 switches to alter the log output for these.
11156 hg journal -T json can be used to produce machine readable output.
11158 Options:
11160 --all show history for all names
11162 -c, --commits
11164 show commit metadata
11165 -p, --patch
11167 show patch
11168 -g, --git
11170 use git extended diff format
11171 -l,--limit <NUM>
11173 limit number of changes displayed
11174 --stat output diffstat-style summary of changes
11176 --style <STYLE>
11178 display using template map file (DEPRECATED)
11179 -T,--template <TEMPLATE>
11181 display with template
11182 keyword
11184 expand keywords in tracked files
11185 This extension expands RCS/CVS-like or self-customized $Keywords$ in
11187 tracked text files selected by your configuration.
11188 Keywords are only expanded in local repositories and not stored in the
11190 change history. The mechanism can be regarded as a convenience for the
11191 current user or for archive distribution.
11192 Keywords expand to the changeset data pertaining to the latest change
11194 relative to the working directory parent of each file.
11195 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
11197 sections of hgrc files.
11198 Example:
11200 [keyword]
11202 # expand keywords in every python file except those matching "x*"
11203 **.py =
11204 x* = ignore
11205 [keywordset]
11207 # prefer svn- over cvs-like default keywordmaps
11208 svn = True
11209 Note The more specific you are in your filename patterns the less you
11211 lose speed in huge repositories.
11212 For [keywordmaps] template mapping and expansion demonstration and con‐
11214 trol run hg kwdemo. See hg help templates for a list of available tem‐
11215 plates and filters.
11216 Three additional date template filters are provided:
11218 utcdate
11220 "2006/09/18 15:13:13"
11222 svnutcdate
11224 "2006-09-18 15:13:13Z"
11226 svnisodate
11228 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
11230 The default template mappings (view with hg kwdemo -d) can be replaced
11232 with customized keywords and templates. Again, run hg kwdemo to control
11233 the results of your configuration changes.
11234 Before changing/disabling active keywords, you must run hg kwshrink to
11236 avoid storing expanded keywords in the change history.
11237 To force expansion after enabling it, or a configuration change, run hg
11239 kwexpand.
11240 Expansions spanning more than one line and incremental expansions, like
11242 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
11243 expands to the first line of the changeset description.
11244 Commands
11246 Uncategorized commands
11247 kwdemo
11248 print [keywordmaps] configuration and an expansion example:
11249 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
11251 Show current, custom, or default keyword template maps and their expan‐
11253 sions.
11254 Extend the current configuration by specifying maps as arguments and
11256 using -f/--rcfile to source an external hgrc file.
11257 Use -d/--default to disable current configuration.
11259 See hg help templates for information on templates and filters.
11261 Options:
11263 -d, --default
11265 show default keyword template maps
11266 -f,--rcfile <FILE>
11268 read maps from rcfile
11269 kwexpand
11271 expand keywords in the working directory:
11272 hg kwexpand [OPTION]... [FILE]...
11274 Run after (re)enabling keyword expansion.
11276 kwexpand refuses to run if given files contain local changes.
11278 Options:
11280 -I,--include <PATTERN[+]>
11282 include names matching the given patterns
11283 -X,--exclude <PATTERN[+]>
11285 exclude names matching the given patterns
11286 [+] marked option can be specified multiple times
11288 kwfiles
11290 show files configured for keyword expansion:
11291 hg kwfiles [OPTION]... [FILE]...
11293 List which files in the working directory are matched by the [keyword]
11295 configuration patterns.
11296 Useful to prevent inadvertent keyword expansion and to speed up execu‐
11298 tion by including only files that are actual candidates for expansion.
11299 See hg help keyword on how to construct patterns both for inclusion and
11301 exclusion of files.
11302 With -A/--all and -v/--verbose the codes used to show the status of
11304 files are:
11305 K = keyword expansion candidate
11307 k = keyword expansion candidate (not tracked)
11308 I = ignored
11309 i = ignored (not tracked)
11310 Options:
11312 -A, --all
11314 show keyword status flags of all files
11315 -i, --ignore
11317 show files excluded from expansion
11318 -u, --unknown
11320 only show unknown (not tracked) files
11321 -I,--include <PATTERN[+]>
11323 include names matching the given patterns
11324 -X,--exclude <PATTERN[+]>
11326 exclude names matching the given patterns
11327 [+] marked option can be specified multiple times
11329 kwshrink
11331 revert expanded keywords in the working directory:
11332 hg kwshrink [OPTION]... [FILE]...
11334 Must be run before changing/disabling active keywords.
11336 kwshrink refuses to run if given files contain local changes.
11338 Options:
11340 -I,--include <PATTERN[+]>
11342 include names matching the given patterns
11343 -X,--exclude <PATTERN[+]>
11345 exclude names matching the given patterns
11346 [+] marked option can be specified multiple times
11348 largefiles
11350 track large binary files
11351 Large binary files tend to be not very compressible, not very diffable,
11353 and not at all mergeable. Such files are not handled efficiently by
11354 Mercurial's storage format (revlog), which is based on compressed bi‐
11355 nary deltas; storing large binary files as regular Mercurial files
11356 wastes bandwidth and disk space and increases Mercurial's memory usage.
11357 The largefiles extension addresses these problems by adding a central‐
11358 ized client-server layer on top of Mercurial: largefiles live in a cen‐
11359 tral store out on the network somewhere, and you only fetch the revi‐
11360 sions that you need when you need them.
11361 largefiles works by maintaining a "standin file" in .hglf/ for each
11363 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
11364 line) and are tracked by Mercurial. Largefile revisions are identified
11365 by the SHA-1 hash of their contents, which is written to the standin.
11366 largefiles uses that revision ID to get/put largefile revisions from/to
11367 the central store. This saves both disk space and bandwidth, since you
11368 don't need to retrieve all historical revisions of large files when you
11369 clone or pull.
11370 To start a new repository or add new large binary files, just add
11372 --large to your hg add command. For example:
11373 $ dd if=/dev/urandom of=randomdata count=2000
11375 $ hg add --large randomdata
11376 $ hg commit -m "add randomdata as a largefile"
11377 When you push a changeset that adds/modifies largefiles to a remote
11379 repository, its largefile revisions will be uploaded along with it.
11380 Note that the remote Mercurial must also have the largefiles extension
11381 enabled for this to work.
11382 When you pull a changeset that affects largefiles from a remote reposi‐
11384 tory, the largefiles for the changeset will by default not be pulled
11385 down. However, when you update to such a revision, any largefiles
11386 needed by that revision are downloaded and cached (if they have never
11387 been downloaded before). One way to pull largefiles when pulling is
11388 thus to use --update, which will update your working copy to the latest
11389 pulled revision (and thereby downloading any new largefiles).
11390 If you want to pull largefiles you don't need for update yet, then you
11392 can use pull with the --lfrev option or the hg lfpull command.
11393 If you know you are pulling from a non-default location and want to
11395 download all the largefiles that correspond to the new changesets at
11396 the same time, then you can pull with --lfrev "pulled()".
11397 If you just want to ensure that you will have the largefiles needed to
11399 merge or rebase with new heads that you are pulling, then you can pull
11400 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
11401 files that are new in the heads you are pulling.
11402 Keep in mind that network access may now be required to update to
11404 changesets that you have not previously updated to. The nature of the
11405 largefiles extension means that updating is no longer guaranteed to be
11406 a local-only operation.
11407 If you already have large files tracked by Mercurial without the large‐
11409 files extension, you will need to convert your repository in order to
11410 benefit from largefiles. This is done with the hg lfconvert command:
11411 $ hg lfconvert --size 10 oldrepo newrepo
11413 In repositories that already have largefiles in them, any new file over
11415 10MB will automatically be added as a largefile. To change this thresh‐
11416 old, set largefiles.minsize in your Mercurial config file to the mini‐
11417 mum size in megabytes to track as a largefile, or use the --lfsize op‐
11418 tion to the add command (also in megabytes):
11419 [largefiles]
11421 minsize = 2
11422 $ hg add --lfsize 2
11424 The largefiles.patterns config option allows you to specify a list of
11426 filename patterns (see hg help patterns) that should always be tracked
11427 as largefiles:
11428 [largefiles]
11430 patterns =
11431 *.jpg
11432 re:.*\.(png|bmp)$
11433 library.zip
11434 content/audio/*
11435 Files that match one of these patterns will be added as largefiles re‐
11437 gardless of their size.
11438 The largefiles.minsize and largefiles.patterns config options will be
11440 ignored for any repositories not already containing a largefile. To add
11441 the first largefile to a repository, you must explicitly do so with the
11442 --large flag passed to the hg add command.
11443 Commands
11445 Uncategorized commands
11446 lfconvert
11447 convert a normal repository to a largefiles repository:
11448 hg lfconvert SOURCE DEST [FILE ...]
11450 Convert repository SOURCE to a new repository DEST, identical to SOURCE
11452 except that certain files will be converted as largefiles: specifi‐
11453 cally, any file that matches any PATTERN or whose size is above the
11454 minimum size threshold is converted as a largefile. The size used to
11455 determine whether or not to track a file as a largefile is the size of
11456 the first version of the file. The minimum size can be specified either
11457 with --size or in configuration as largefiles.size.
11458 After running this command you will need to make sure that largefiles
11460 is enabled anywhere you intend to push the new repository.
11461 Use --to-normal to convert largefiles back to normal files; after this,
11463 the DEST repository can be used without largefiles at all.
11464 Options:
11466 -s,--size <SIZE>
11468 minimum size (MB) for files to be converted as largefiles
11469 --to-normal
11471 convert from a largefiles repo to a normal repo
11472 lfpull
11474 pull largefiles for the specified revisions from the specified source:
11475 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
11477 Pull largefiles that are referenced from local changesets but missing
11479 locally, pulling from a remote repository to the local cache.
11480 If SOURCE is omitted, the 'default' path will be used. See hg help
11482 urls for more information.
11483 Some examples:
11485 • pull largefiles for all branch heads:
11487 hg lfpull -r "head() and not closed()"
11489 • pull largefiles on the default branch:
11491 hg lfpull -r "branch(default)"
11493 Options:
11495 -r,--rev <VALUE[+]>
11497 pull largefiles for these revisions
11498 -e,--ssh <CMD>
11500 specify ssh command to use
11501 --remotecmd <CMD>
11503 specify hg command to run on the remote side
11504 --insecure
11506 do not verify server certificate (ignoring web.cacerts config)
11507 [+] marked option can be specified multiple times
11509 lfs
11511 lfs - large file support (EXPERIMENTAL)
11512 This extension allows large files to be tracked outside of the normal
11514 repository storage and stored on a centralized server, similar to the
11515 largefiles extension. The git-lfs protocol is used when communicating
11516 with the server, so existing git infrastructure can be harnessed. Even
11517 though the files are stored outside of the repository, they are still
11518 integrity checked in the same manner as normal files.
11519 The files stored outside of the repository are downloaded on demand,
11521 which reduces the time to clone, and possibly the local disk usage.
11522 This changes fundamental workflows in a DVCS, so careful thought should
11523 be given before deploying it. hg convert can be used to convert LFS
11524 repositories to normal repositories that no longer require this exten‐
11525 sion, and do so without changing the commit hashes. This allows the
11526 extension to be disabled if the centralized workflow becomes burden‐
11527 some. However, the pre and post convert clones will not be able to
11528 communicate with each other unless the extension is enabled on both.
11529 To start a new repository, or to add LFS files to an existing one, just
11531 create an .hglfs file as described below in the root directory of the
11532 repository. Typically, this file should be put under version control,
11533 so that the settings will propagate to other repositories with push and
11534 pull. During any commit, Mercurial will consult this file to determine
11535 if an added or modified file should be stored externally. The type of
11536 storage depends on the characteristics of the file at each commit. A
11537 file that is near a size threshold may switch back and forth between
11538 LFS and normal storage, as needed.
11539 Alternately, both normal repositories and largefile controlled reposi‐
11541 tories can be converted to LFS by using hg convert and the lfs.track
11542 config option described below. The .hglfs file should then be created
11543 and added, to control subsequent LFS selection. The hashes are also
11544 unchanged in this case. The LFS and non-LFS repositories can be dis‐
11545 tinguished because the LFS repository will abort any command if this
11546 extension is disabled.
11547 Committed LFS files are held locally, until the repository is pushed.
11549 Prior to pushing the normal repository data, the LFS files that are
11550 tracked by the outgoing commits are automatically uploaded to the con‐
11551 figured central server. No LFS files are transferred on hg pull or hg
11552 clone. Instead, the files are downloaded on demand as they need to be
11553 read, if a cached copy cannot be found locally. Both committing and
11554 downloading an LFS file will link the file to a usercache, to speed up
11555 future access. See the usercache config setting described below.
11556 The extension reads its configuration from a versioned .hglfs configu‐
11558 ration file found in the root of the working directory. The .hglfs file
11559 uses the same syntax as all other Mercurial configuration files. It
11560 uses a single section, [track].
11561 The [track] section specifies which files are stored as LFS (or not).
11563 Each line is keyed by a file pattern, with a predicate value. The
11564 first file pattern match is used, so put more specific patterns first.
11565 The available predicates are all(), none(), and size(). See "hg help
11566 filesets.size" for the latter.
11567 Example versioned .hglfs file:
11569 [track]
11571 # No Makefile or python file, anywhere, will be LFS
11572 **Makefile = none()
11573 **.py = none()
11574 **.zip = all()
11576 **.exe = size(">1MB")
11577 # Catchall for everything not matched above
11579 ** = size(">10MB")
11580 Configs:
11582 [lfs]
11584 # Remote endpoint. Multiple protocols are supported:
11585 # - http(s)://user:pass@example.com/path
11586 # git-lfs endpoint
11587 # - file:///tmp/path
11588 # local filesystem, usually for testing
11589 # if unset, lfs will assume the remote repository also handles blob storage
11590 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
11591 # use this value.
11592 # (default: unset)
11593 url = https://example.com/repo.git/info/lfs
11594 # Which files to track in LFS. Path tests are "**.extname" for file
11596 # extensions, and "path:under/some/directory" for path prefix. Both
11597 # are relative to the repository root.
11598 # File size can be tested with the "size()" fileset, and tests can be
11599 # joined with fileset operators. (See "hg help filesets.operators".)
11600 #
11601 # Some examples:
11602 # - all() # everything
11603 # - none() # nothing
11604 # - size(">20MB") # larger than 20MB
11605 # - !**.txt # anything not a *.txt file
11606 # - **.zip | **.tar.gz | **.7z # some types of compressed files
11607 # - path:bin # files under "bin" in the project root
11608 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
11609 # | (path:bin & !path:/bin/README) | size(">1GB")
11610 # (default: none())
11611 #
11612 # This is ignored if there is a tracked '.hglfs' file, and this setting
11613 # will eventually be deprecated and removed.
11614 track = size(">10M")
11615 # how many times to retry before giving up on transferring an object
11617 retry = 5
11618 # the local directory to store lfs files for sharing across local clones.
11620 # If not set, the cache is located in an OS specific cache location.
11621 usercache = /path/to/global/cache
11622 Commands
11624 Uncategorized commands
11625 logtoprocess
11626 send ui.log() data to a subprocess (EXPERIMENTAL)
11627 This extension lets you specify a shell command per ui.log() event,
11629 sending all remaining arguments to as environment variables to that
11630 command.
11631 Positional arguments construct a log message, which is passed in the
11633 MSG1 environment variables. Each keyword argument is set as a OPT_UP‐
11634 PERCASE_KEY variable (so the key is uppercased, and prefixed with
11635 OPT_). The original event name is passed in the EVENT environment vari‐
11636 able, and the process ID of mercurial is given in HGPID.
11637 So given a call ui.log('foo', 'bar %s ', 'baz', spam='eggs'), a script
11639 configured for the `foo event can expect an environment with MSG1=bar
11640 baz, and OPT_SPAM=eggs.
11641 Scripts are configured in the [logtoprocess] section, each key an event
11643 name. For example:
11644 [logtoprocess]
11646 commandexception = echo "$MSG1" > /var/log/mercurial_exceptions.log
11647 would log the warning message and traceback of any failed command dis‐
11649 patch.
11650 Scripts are run asynchronously as detached daemon processes; mercurial
11652 will not ensure that they exit cleanly.
11653 mq
11655 manage a stack of patches
11656 This extension lets you work with a stack of patches in a Mercurial
11658 repository. It manages two stacks of patches - all known patches, and
11659 applied patches (subset of known patches).
11660 Known patches are represented as patch files in the .hg/patches direc‐
11662 tory. Applied patches are both patch files and changesets.
11663 Common tasks (use hg help COMMAND for more details):
11665 create new patch qnew
11667 import existing patch qimport
11668 print patch series qseries
11670 print applied patches qapplied
11671 add known patch to applied stack qpush
11673 remove patch from applied stack qpop
11674 refresh contents of top applied patch qrefresh
11675 By default, mq will automatically use git patches when required to
11677 avoid losing file mode changes, copy records, binary files or empty
11678 files creations or deletions. This behavior can be configured with:
11679 [mq]
11681 git = auto/keep/yes/no
11682 If set to 'keep', mq will obey the [diff] section configuration while
11684 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
11685 mq will override the [diff] section and always generate git or regular
11686 patches, possibly losing data in the second case.
11687 It may be desirable for mq changesets to be kept in the secret phase
11689 (see hg help phases), which can be enabled with the following setting:
11690 [mq]
11692 secret = True
11693 You will by default be managing a patch queue named "patches". You can
11695 create other, independent patch queues with the hg qqueue command.
11696 If the working directory contains uncommitted files, qpush, qpop and
11698 qgoto abort immediately. If -f/--force is used, the changes are dis‐
11699 carded. Setting:
11700 [mq]
11702 keepchanges = True
11703 make them behave as if --keep-changes were passed, and non-conflicting
11705 local changes will be tolerated and preserved. If incompatible options
11706 such as -f/--force or --exact are passed, this setting is ignored.
11707 This extension used to provide a strip command. This command now lives
11709 in the strip extension.
11710 Commands
11712 Repository creation
11713 qclone
11714 clone main and patch repository at same time:
11715 hg qclone [OPTION]... SOURCE [DEST]
11717 If source is local, destination will have no patches applied. If source
11719 is remote, this command can not check if patches are applied in source,
11720 so cannot guarantee that patches are not applied in destination. If you
11721 clone remote repository, be sure before that it has no patches applied.
11722 Source patch repository is looked for in <src>/.hg/patches by default.
11724 Use -p <url> to change.
11725 The patch directory must be a nested Mercurial repository, as would be
11727 created by hg init --mq.
11728 Return 0 on success.
11730 Options:
11732 --pull use pull protocol to copy metadata
11734 -U, --noupdate
11736 do not update the new working directories
11737 --uncompressed
11739 use uncompressed transfer (fast over LAN)
11740 -p,--patches <REPO>
11742 location of source patch repository
11743 -e,--ssh <CMD>
11745 specify ssh command to use
11746 --remotecmd <CMD>
11748 specify hg command to run on the remote side
11749 --insecure
11751 do not verify server certificate (ignoring web.cacerts config)
11752 qinit
11754 init a new queue repository (DEPRECATED):
11755 hg qinit [-c]
11757 The queue repository is unversioned by default. If -c/--create-repo is
11759 specified, qinit will create a separate nested repository for patches
11760 (qinit -c may also be run later to convert an unversioned patch reposi‐
11761 tory into a versioned one). You can use qcommit to commit changes to
11762 this queue repository.
11763 This command is deprecated. Without -c, it's implied by other relevant
11765 commands. With -c, use hg init --mq instead.
11766 Options:
11768 -c, --create-repo
11770 create queue repository
11771 Change creation
11773 qcommit
11774 commit changes in the queue repository (DEPRECATED):
11775 hg qcommit [OPTION]... [FILE]...
11777 This command is deprecated; use hg commit --mq instead.
11779 Options:
11781 -A, --addremove
11783 mark new/missing files as added/removed before committing
11784 --close-branch
11786 mark a branch head as closed
11787 --amend
11789 amend the parent of the working directory
11790 -s, --secret
11792 use the secret phase for committing
11793 -e, --edit
11795 invoke editor on commit messages
11796 --force-close-branch
11798 forcibly close branch from a non-head changeset (ADVANCED)
11799 -i, --interactive
11801 use interactive mode
11802 -I,--include <PATTERN[+]>
11804 include names matching the given patterns
11805 -X,--exclude <PATTERN[+]>
11807 exclude names matching the given patterns
11808 -m,--message <TEXT>
11810 use text as commit message
11811 -l,--logfile <FILE>
11813 read commit message from file
11814 -d,--date <DATE>
11816 record the specified date as commit date
11817 -u,--user <USER>
11819 record the specified user as committer
11820 -S, --subrepos
11822 recurse into subrepositories
11823 [+] marked option can be specified multiple times
11825 aliases: qci
11827 qnew
11829 create a new patch:
11830 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
11832 qnew creates a new patch on top of the currently-applied patch (if
11834 any). The patch will be initialized with any outstanding changes in the
11835 working directory. You may also use -I/--include, -X/--exclude, and/or
11836 a list of files after the patch name to add only changes to matching
11837 files to the new patch, leaving the rest as uncommitted modifications.
11838 -u/--user and -d/--date can be used to set the (given) user and date,
11840 respectively. -U/--currentuser and -D/--currentdate set user to current
11841 user and date to current date.
11842 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
11844 the commit message. If none is specified, the header is empty and the
11845 commit message is '[mq]: PATCH'.
11846 Use the -g/--git option to keep the patch in the git extended diff for‐
11848 mat. Read the diffs help topic for more information on why this is im‐
11849 portant for preserving permission changes and copy/rename information.
11850 Returns 0 on successful creation of a new patch.
11852 Options:
11854 -e, --edit
11856 invoke editor on commit messages
11857 -f, --force
11859 import uncommitted changes (DEPRECATED)
11860 -g, --git
11862 use git extended diff format
11863 -U, --currentuser
11865 add "From: <current user>" to patch
11866 -u,--user <USER>
11868 add "From: <USER>" to patch
11869 -D, --currentdate
11871 add "Date: <current date>" to patch
11872 -d,--date <DATE>
11874 add "Date: <DATE>" to patch
11875 -I,--include <PATTERN[+]>
11877 include names matching the given patterns
11878 -X,--exclude <PATTERN[+]>
11880 exclude names matching the given patterns
11881 -m,--message <TEXT>
11883 use text as commit message
11884 -l,--logfile <FILE>
11886 read commit message from file
11887 [+] marked option can be specified multiple times
11889 qrefresh
11891 update the current patch:
11892 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
11894 If any file patterns are provided, the refreshed patch will contain
11896 only the modifications that match those patterns; the remaining modifi‐
11897 cations will remain in the working directory.
11898 If -s/--short is specified, files currently included in the patch will
11900 be refreshed just like matched files and remain in the patch.
11901 If -e/--edit is specified, Mercurial will start your configured editor
11903 for you to enter a message. In case qrefresh fails, you will find a
11904 backup of your message in .hg/last-message.txt.
11905 hg add/remove/copy/rename work as usual, though you might want to use
11907 git-style patches (-g/--git or [diff] git=1) to track copies and re‐
11908 names. See the diffs help topic for more information on the git diff
11909 format.
11910 Returns 0 on success.
11912 Options:
11914 -e, --edit
11916 invoke editor on commit messages
11917 -g, --git
11919 use git extended diff format
11920 -s, --short
11922 refresh only files already in the patch and specified files
11923 -U, --currentuser
11925 add/update author field in patch with current user
11926 -u,--user <USER>
11928 add/update author field in patch with given user
11929 -D, --currentdate
11931 add/update date field in patch with current date
11932 -d,--date <DATE>
11934 add/update date field in patch with given date
11935 -I,--include <PATTERN[+]>
11937 include names matching the given patterns
11938 -X,--exclude <PATTERN[+]>
11940 exclude names matching the given patterns
11941 -m,--message <TEXT>
11943 use text as commit message
11944 -l,--logfile <FILE>
11946 read commit message from file
11947 [+] marked option can be specified multiple times
11949 Change manipulation
11951 qfold
11952 fold the named patches into the current patch:
11953 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
11955 Patches must not yet be applied. Each patch will be successively ap‐
11957 plied to the current patch in the order given. If all the patches apply
11958 successfully, the current patch will be refreshed with the new cumula‐
11959 tive patch, and the folded patches will be deleted. With -k/--keep, the
11960 folded patch files will not be removed afterwards.
11961 The header for each folded patch will be concatenated with the current
11963 patch header, separated by a line of * * *.
11964 Returns 0 on success.
11966 Options:
11968 -e, --edit
11970 invoke editor on commit messages
11971 -k, --keep
11973 keep folded patch files
11974 -m,--message <TEXT>
11976 use text as commit message
11977 -l,--logfile <FILE>
11979 read commit message from file
11980 Change organization
11982 qapplied
11983 print the patches already applied:
11984 hg qapplied [-1] [-s] [PATCH]
11986 Returns 0 on success.
11988 Options:
11990 -1, --last
11992 show only the preceding applied patch
11993 -s, --summary
11995 print first line of patch header
11996 qdelete
11998 remove patches from queue:
11999 hg qdelete [-k] [PATCH]...
12001 The patches must not be applied, and at least one patch is required.
12003 Exact patch identifiers must be given. With -k/--keep, the patch files
12004 are preserved in the patch directory.
12005 To stop managing a patch and move it into permanent history, use the hg
12007 qfinish command.
12008 Options:
12010 -k, --keep
12012 keep patch file
12013 -r,--rev <REV[+]>
12015 stop managing a revision (DEPRECATED)
12016 [+] marked option can be specified multiple times
12018 aliases: qremove qrm
12020 qfinish
12022 move applied patches into repository history:
12023 hg qfinish [-a] [REV]...
12025 Finishes the specified revisions (corresponding to applied patches) by
12027 moving them out of mq control into regular repository history.
12028 Accepts a revision range or the -a/--applied option. If --applied is
12030 specified, all applied mq revisions are removed from mq control. Other‐
12031 wise, the given revisions must be at the base of the stack of applied
12032 patches.
12033 This can be especially useful if your changes have been applied to an
12035 upstream repository, or if you are about to push your changes to up‐
12036 stream.
12037 Returns 0 on success.
12039 Options:
12041 -a, --applied
12043 finish all applied changesets
12044 qgoto
12046 push or pop patches until named patch is at top of stack:
12047 hg qgoto [OPTION]... PATCH
12049 Returns 0 on success.
12051 Options:
12053 --keep-changes
12055 tolerate non-conflicting local changes
12056 -f, --force
12058 overwrite any local changes
12059 --no-backup
12061 do not save backup copies of files
12062 qguard
12064 set or print guards for a patch:
12065 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
12067 Guards control whether a patch can be pushed. A patch with no guards is
12069 always pushed. A patch with a positive guard ("+foo") is pushed only if
12070 the hg qselect command has activated it. A patch with a negative guard
12071 ("-foo") is never pushed if the hg qselect command has activated it.
12072 With no arguments, print the currently active guards. With arguments,
12074 set guards for the named patch.
12075 Note Specifying negative guards now requires '--'.
12077 To set guards on another patch:
12079 hg qguard other.patch -- +2.6.17 -stable
12081 Returns 0 on success.
12083 Options:
12085 -l, --list
12087 list all patches and guards
12088 -n, --none
12090 drop all guards
12091 qheader
12093 print the header of the topmost or specified patch:
12094 hg qheader [PATCH]
12096 Returns 0 on success.
12098 qnext
12100 print the name of the next pushable patch:
12101 hg qnext [-s]
12103 Returns 0 on success.
12105 Options:
12107 -s, --summary
12109 print first line of patch header
12110 qpop
12112 pop the current patch off the stack:
12113 hg qpop [-a] [-f] [PATCH | INDEX]
12115 Without argument, pops off the top of the patch stack. If given a patch
12117 name, keeps popping off patches until the named patch is at the top of
12118 the stack.
12119 By default, abort if the working directory contains uncommitted
12121 changes. With --keep-changes, abort only if the uncommitted files over‐
12122 lap with patched files. With -f/--force, backup and discard changes
12123 made to such files.
12124 Return 0 on success.
12126 Options:
12128 -a, --all
12130 pop all patches
12131 -n,--name <NAME>
12133 queue name to pop (DEPRECATED)
12134 --keep-changes
12136 tolerate non-conflicting local changes
12137 -f, --force
12139 forget any local changes to patched files
12140 --no-backup
12142 do not save backup copies of files
12143 qprev
12145 print the name of the preceding applied patch:
12146 hg qprev [-s]
12148 Returns 0 on success.
12150 Options:
12152 -s, --summary
12154 print first line of patch header
12155 qpush
12157 push the next patch onto the stack:
12158 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
12160 By default, abort if the working directory contains uncommitted
12162 changes. With --keep-changes, abort only if the uncommitted files over‐
12163 lap with patched files. With -f/--force, backup and patch over uncom‐
12164 mitted changes.
12165 Return 0 on success.
12167 Options:
12169 --keep-changes
12171 tolerate non-conflicting local changes
12172 -f, --force
12174 apply on top of local changes
12175 -e, --exact
12177 apply the target patch to its recorded parent
12178 -l, --list
12180 list patch name in commit text
12181 -a, --all
12183 apply all patches
12184 -m, --merge
12186 merge from another queue (DEPRECATED)
12187 -n,--name <NAME>
12189 merge queue name (DEPRECATED)
12190 --move reorder patch series and apply only the patch
12192 --no-backup
12194 do not save backup copies of files
12195 qqueue
12197 manage multiple patch queues:
12198 hg qqueue [OPTION] [QUEUE]
12200 Supports switching between different patch queues, as well as creating
12202 new patch queues and deleting existing ones.
12203 Omitting a queue name or specifying -l/--list will show you the regis‐
12205 tered queues - by default the "normal" patches queue is registered. The
12206 currently active queue will be marked with "(active)". Specifying --ac‐
12207 tive will print only the name of the active queue.
12208 To create a new queue, use -c/--create. The queue is automatically made
12210 active, except in the case where there are applied patches from the
12211 currently active queue in the repository. Then the queue will only be
12212 created and switching will fail.
12213 To delete an existing queue, use --delete. You cannot delete the cur‐
12215 rently active queue.
12216 Returns 0 on success.
12218 Options:
12220 -l, --list
12222 list all available queues
12223 --active
12225 print name of active queue
12226 -c, --create
12228 create new queue
12229 --rename
12231 rename active queue
12232 --delete
12234 delete reference to queue
12235 --purge
12237 delete queue, and remove patch dir
12238 qrename
12240 rename a patch:
12241 hg qrename PATCH1 [PATCH2]
12243 With one argument, renames the current patch to PATCH1. With two argu‐
12245 ments, renames PATCH1 to PATCH2.
12246 Returns 0 on success.
12248 aliases: qmv
12250 qrestore
12252 restore the queue state saved by a revision (DEPRECATED):
12253 hg qrestore [-d] [-u] REV
12255 This command is deprecated, use hg rebase instead.
12257 Options:
12259 -d, --delete
12261 delete save entry
12262 -u, --update
12264 update queue working directory
12265 qsave
12267 save current queue state (DEPRECATED):
12268 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
12270 This command is deprecated, use hg rebase instead.
12272 Options:
12274 -c, --copy
12276 copy patch directory
12277 -n,--name <NAME>
12279 copy directory name
12280 -e, --empty
12282 clear queue status file
12283 -f, --force
12285 force copy
12286 -m,--message <TEXT>
12288 use text as commit message
12289 -l,--logfile <FILE>
12291 read commit message from file
12292 qselect
12294 set or print guarded patches to push:
12295 hg qselect [OPTION]... [GUARD]...
12297 Use the hg qguard command to set or print guards on patch, then use qs‐
12299 elect to tell mq which guards to use. A patch will be pushed if it has
12300 no guards or any positive guards match the currently selected guard,
12301 but will not be pushed if any negative guards match the current guard.
12302 For example:
12303 qguard foo.patch -- -stable (negative guard)
12305 qguard bar.patch +stable (positive guard)
12306 qselect stable
12307 This activates the "stable" guard. mq will skip foo.patch (because it
12309 has a negative match) but push bar.patch (because it has a positive
12310 match).
12311 With no arguments, prints the currently active guards. With one argu‐
12313 ment, sets the active guard.
12314 Use -n/--none to deactivate guards (no other arguments needed). When
12316 no guards are active, patches with positive guards are skipped and
12317 patches with negative guards are pushed.
12318 qselect can change the guards on applied patches. It does not pop
12320 guarded patches by default. Use --pop to pop back to the last applied
12321 patch that is not guarded. Use --reapply (which implies --pop) to push
12322 back to the current patch afterwards, but skip guarded patches.
12323 Use -s/--series to print a list of all guards in the series file (no
12325 other arguments needed). Use -v for more information.
12326 Returns 0 on success.
12328 Options:
12330 -n, --none
12332 disable all guards
12333 -s, --series
12335 list all guards in series file
12336 --pop pop to before first guarded applied patch
12338 --reapply
12340 pop, then reapply patches
12341 qseries
12343 print the entire series file:
12344 hg qseries [-ms]
12346 Returns 0 on success.
12348 Options:
12350 -m, --missing
12352 print patches not in series
12353 -s, --summary
12355 print first line of patch header
12356 qtop
12358 print the name of the current patch:
12359 hg qtop [-s]
12361 Returns 0 on success.
12363 Options:
12365 -s, --summary
12367 print first line of patch header
12368 qunapplied
12370 print the patches not yet applied:
12371 hg qunapplied [-1] [-s] [PATCH]
12373 Returns 0 on success.
12375 Options:
12377 -1, --first
12379 show only the first patch
12380 -s, --summary
12382 print first line of patch header
12383 File content management
12385 qdiff
12386 diff of the current patch and subsequent modifications:
12387 hg qdiff [OPTION]... [FILE]...
12389 Shows a diff which includes the current patch as well as any changes
12391 which have been made in the working directory since the last refresh
12392 (thus showing what the current patch would become after a qrefresh).
12393 Use hg diff if you only want to see the changes made since the last
12395 qrefresh, or hg export qtip if you want to see changes made by the cur‐
12396 rent patch without including changes made since the qrefresh.
12397 Returns 0 on success.
12399 Options:
12401 -a, --text
12403 treat all files as text
12404 -g, --git
12406 use git extended diff format (DEFAULT: diff.git)
12407 --binary
12409 generate binary diffs in git mode (default)
12410 --nodates
12412 omit dates from diff headers
12413 --noprefix
12415 omit a/ and b/ prefixes from filenames
12416 -p, --show-function
12418 show which function each change is in (DEFAULT: diff.showfunc)
12419 --reverse
12421 produce a diff that undoes the changes
12422 -w, --ignore-all-space
12424 ignore white space when comparing lines
12425 -b, --ignore-space-change
12427 ignore changes in the amount of white space
12428 -B, --ignore-blank-lines
12430 ignore changes whose lines are all blank
12431 -Z, --ignore-space-at-eol
12433 ignore changes in whitespace at EOL
12434 -U,--unified <NUM>
12436 number of lines of context to show
12437 --stat output diffstat-style summary of changes
12439 --root <DIR>
12441 produce diffs relative to subdirectory
12442 -I,--include <PATTERN[+]>
12444 include names matching the given patterns
12445 -X,--exclude <PATTERN[+]>
12447 exclude names matching the given patterns
12448 [+] marked option can be specified multiple times
12450 Change import/export
12452 qimport
12453 import a patch or existing changeset:
12454 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
12456 The patch is inserted into the series after the last applied patch. If
12458 no patches have been applied, qimport prepends the patch to the series.
12459 The patch will have the same name as its source file unless you give it
12461 a new one with -n/--name.
12462 You can register an existing patch inside the patch directory with the
12464 -e/--existing flag.
12465 With -f/--force, an existing patch of the same name will be overwrit‐
12467 ten.
12468 An existing changeset may be placed under mq control with -r/--rev
12470 (e.g. qimport --rev . -n patch will place the current revision under mq
12471 control). With -g/--git, patches imported with --rev will use the git
12472 diff format. See the diffs help topic for information on why this is
12473 important for preserving rename/copy information and permission
12474 changes. Use hg qfinish to remove changesets from mq control.
12475 To import a patch from standard input, pass - as the patch file. When
12477 importing from standard input, a patch name must be specified using the
12478 --name flag.
12479 To import an existing patch while renaming it:
12481 hg qimport -e existing-patch -n new-name
12483 Returns 0 if import succeeded.
12485 Options:
12487 -e, --existing
12489 import file in patch directory
12490 -n,--name <NAME>
12492 name of patch file
12493 -f, --force
12495 overwrite existing files
12496 -r,--rev <REV[+]>
12498 place existing revisions under mq control
12499 -g, --git
12501 use git extended diff format
12502 -P, --push
12504 qpush after importing
12505 [+] marked option can be specified multiple times
12507 narrow
12509 create clones which fetch history data for subset of files (EXPERIMEN‐
12510 TAL)
12511 Commands
12513 Repository maintenance
12514 tracked
12515 show or change the current narrowspec:
12516 hg tracked [OPTIONS]... [REMOTE]
12518 With no argument, shows the current narrowspec entries, one per line.
12520 Each line will be prefixed with 'I' or 'X' for included or excluded
12521 patterns, respectively.
12522 The narrowspec is comprised of expressions to match remote files and/or
12524 directories that should be pulled into your client. The narrowspec has
12525 include and exclude expressions, with excludes always trumping in‐
12526 cludes: that is, if a file matches an exclude expression, it will be
12527 excluded even if it also matches an include expression. Excluding
12528 files that were never included has no effect.
12529 Each included or excluded entry is in the format described by 'hg help
12531 patterns'.
12532 The options allow you to add or remove included and excluded expres‐
12534 sions.
12535 If --clear is specified, then all previous includes and excludes are
12537 DROPPED and replaced by the new ones specified to --addinclude and
12538 --addexclude. If --clear is specified without any further options, the
12539 narrowspec will be empty and will not match any files.
12540 If --auto-remove-includes is specified, then those includes that don't
12542 match any files modified by currently visible local commits (those not
12543 shared by the remote) will be added to the set of explicitly specified
12544 includes to remove.
12545 --import-rules accepts a path to a file containing rules, allowing you
12547 to add --addinclude, --addexclude rules in bulk. Like the other include
12548 and exclude switches, the changes are applied immediately.
12549 Options:
12551 --addinclude <VALUE[+]>
12553 new paths to include
12554 --removeinclude <VALUE[+]>
12556 old paths to no longer include
12557 --auto-remove-includes
12559 automatically choose unused includes to remove
12560 --addexclude <VALUE[+]>
12562 new paths to exclude
12563 --import-rules <VALUE>
12565 import narrowspecs from a file
12566 --removeexclude <VALUE[+]>
12568 old paths to no longer exclude
12569 --clear
12571 whether to replace the existing narrowspec
12572 --force-delete-local-changes
12574 forces deletion of local changes when narrowing
12575 --backup
12577 back up local changes when narrowing (default: True)
12578 --update-working-copy
12580 update working copy when the store has changed
12581 -e,--ssh <CMD>
12583 specify ssh command to use
12584 --remotecmd <CMD>
12586 specify hg command to run on the remote side
12587 --insecure
12589 do not verify server certificate (ignoring web.cacerts config)
12590 [+] marked option can be specified multiple times
12592 notify
12594 hooks for sending email push notifications
12595 This extension implements hooks to send email notifications when
12597 changesets are sent from or received by the local repository.
12598 First, enable the extension as explained in hg help extensions, and
12600 register the hook you want to run. incoming and changegroup hooks are
12601 run when changesets are received, while outgoing hooks are for change‐
12602 sets sent to another repository:
12603 [hooks]
12605 # one email for each incoming changeset
12606 incoming.notify = python:hgext.notify.hook
12607 # one email for all incoming changesets
12608 changegroup.notify = python:hgext.notify.hook
12609 # one email for all outgoing changesets
12611 outgoing.notify = python:hgext.notify.hook
12612 This registers the hooks. To enable notification, subscribers must be
12614 assigned to repositories. The [usersubs] section maps multiple reposi‐
12615 tories to a given recipient. The [reposubs] section maps multiple re‐
12616 cipients to a single repository:
12617 [usersubs]
12619 # key is subscriber email, value is a comma-separated list of repo patterns
12620 user@host = pattern
12621 [reposubs]
12623 # key is repo pattern, value is a comma-separated list of subscriber emails
12624 pattern = user@host
12625 A pattern is a glob matching the absolute path to a repository, option‐
12627 ally combined with a revset expression. A revset expression, if
12628 present, is separated from the glob by a hash. Example:
12629 [reposubs]
12631 */widgets#branch(release) = qa-team@example.com
12632 This sends to qa-team@example.com whenever a changeset on the release
12634 branch triggers a notification in any repository ending in widgets.
12635 In order to place them under direct user management, [usersubs] and
12637 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
12638 rated by reference:
12639 [notify]
12641 config = /path/to/subscriptionsfile
12642 Notifications will not be sent until the notify.test value is set to
12644 False; see below.
12645 Notifications content can be tweaked with the following configuration
12647 entries:
12648 notify.test
12650 If True, print messages to stdout instead of sending them. De‐
12651 fault: True.
12652 notify.sources
12654 Space-separated list of change sources. Notifications are acti‐
12655 vated only when a changeset's source is in this list. Sources
12656 may be:
12657 serve
12659 changesets received via http or ssh
12661 pull
12663 changesets received via hg pull
12665 unbundle
12667 changesets received via hg unbundle
12669 push
12671 changesets sent or received via hg push
12673 bundle
12675 changesets sent via hg unbundle
12677 Default: serve.
12679 notify.strip
12681 Number of leading slashes to strip from url paths. By default,
12682 notifications reference repositories with their absolute path.
12683 notify.strip lets you turn them into relative paths. For exam‐
12684 ple, notify.strip=3 will change /long/path/repository into
12685 repository. Default: 0.
12686 notify.domain
12688 Default email domain for sender or recipients with no explicit
12689 domain. It is also used for the domain part of the Message-Id
12690 when using notify.messageidseed.
12691 notify.messageidseed
12693 Create deterministic Message-Id headers for the mails based on
12694 the seed and the revision identifier of the first commit in the
12695 changeset.
12696 notify.style
12698 Style file to use when formatting emails.
12699 notify.template
12701 Template to use when formatting emails.
12702 notify.incoming
12704 Template to use when run as an incoming hook, overriding no‐
12705 tify.template.
12706 notify.outgoing
12708 Template to use when run as an outgoing hook, overriding no‐
12709 tify.template.
12710 notify.changegroup
12712 Template to use when running as a changegroup hook, overriding
12713 notify.template.
12714 notify.maxdiff
12716 Maximum number of diff lines to include in notification email.
12717 Set to 0 to disable the diff, or -1 to include all of it. De‐
12718 fault: 300.
12719 notify.maxdiffstat
12721 Maximum number of diffstat lines to include in notification
12722 email. Set to -1 to include all of it. Default: -1.
12723 notify.maxsubject
12725 Maximum number of characters in email's subject line. Default:
12726 67.
12727 notify.diffstat
12729 Set to True to include a diffstat before diff content. Default:
12730 True.
12731 notify.showfunc
12733 If set, override diff.showfunc for the diff content. Default:
12734 None.
12735 notify.merge
12737 If True, send notifications for merge changesets. Default: True.
12738 notify.mbox
12740 If set, append mails to this mbox file instead of sending. De‐
12741 fault: None.
12742 notify.fromauthor
12744 If set, use the committer of the first changeset in a change‐
12745 group for the "From" field of the notification mail. If not set,
12746 take the user from the pushing repo. Default: False.
12747 notify.reply-to-predecessor (EXPERIMENTAL)
12749 If set and the changeset has a predecessor in the repository,
12750 try to thread the notification mail with the predecessor. This
12751 adds the "In-Reply-To" header to the notification mail with a
12752 reference to the predecessor with the smallest revision number.
12753 Mail threads can still be torn, especially when changesets are
12754 folded.
12755 This option must be used in combination with notify.messageid‐
12757 seed.
12758 If set, the following entries will also be used to customize the noti‐
12760 fications:
12761 email.from
12763 Email From address to use if none can be found in the generated
12764 email content.
12765 web.baseurl
12767 Root repository URL to combine with repository paths when making
12768 references. See also notify.strip.
12769 pager
12771 browse command output with an external pager (DEPRECATED)
12772 Forcibly enable paging for individual commands that don't typically re‐
12774 quest pagination with the attend-<command> option. This setting takes
12775 precedence over ignore options and defaults:
12776 [pager]
12778 attend-cat = false
12779 patchbomb
12781 command to send changesets as (a series of) patch emails
12782 The series is started off with a "[PATCH 0 of N]" introduction, which
12784 describes the series as a whole.
12785 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12787 first line of the changeset description as the subject text. The mes‐
12788 sage contains two or three body parts:
12789 • The changeset description.
12791 • [Optional] The result of running diffstat on the patch.
12793 • The patch itself, as generated by hg export.
12795 Each message refers to the first in the series using the In-Reply-To
12797 and References headers, so they will show up as a sequence in threaded
12798 mail and news readers, and in mail archives.
12799 To configure other defaults, add a section like this to your configura‐
12801 tion file:
12802 [email]
12804 from = My Name <my@email>
12805 to = recipient1, recipient2, ...
12806 cc = cc1, cc2, ...
12807 bcc = bcc1, bcc2, ...
12808 reply-to = address1, address2, ...
12809 Use [patchbomb] as configuration section name if you need to override
12811 global [email] address settings.
12812 Then you can use the hg email command to mail a series of changesets as
12814 a patchbomb.
12815 You can also either configure the method option in the email section to
12817 be a sendmail compatible mailer or fill out the [smtp] section so that
12818 the patchbomb extension can automatically send patchbombs directly from
12819 the commandline. See the [email] and [smtp] sections in hgrc(5) for de‐
12820 tails.
12821 By default, hg email will prompt for a To or CC header if you do not
12823 supply one via configuration or the command line. You can override
12824 this to never prompt by configuring an empty value:
12825 [email]
12827 cc =
12828 You can control the default inclusion of an introduction message with
12830 the patchbomb.intro configuration option. The configuration is always
12831 overwritten by command line flags like --intro and --desc:
12832 [patchbomb]
12834 intro=auto # include introduction message if more than 1 patch (default)
12835 intro=never # never include an introduction message
12836 intro=always # always include an introduction message
12837 You can specify a template for flags to be added in subject prefixes.
12839 Flags specified by --flag option are exported as {flags} keyword:
12840 [patchbomb]
12842 flagtemplate = "{separate(' ',
12843 ifeq(branch, 'default', '', branch|upper),
12844 flags)}"
12845 You can set patchbomb to always ask for confirmation by setting patch‐
12847 bomb.confirm to true.
12848 Commands
12850 Change import/export
12851 email
12852 send changesets by email:
12853 hg email [OPTION]... [DEST]...
12855 By default, diffs are sent in the format generated by hg export, one
12857 per message. The series starts with a "[PATCH 0 of N]" introduction,
12858 which describes the series as a whole.
12859 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12861 first line of the changeset description as the subject text. The mes‐
12862 sage contains two or three parts. First, the changeset description.
12863 With the -d/--diffstat option, if the diffstat program is installed,
12865 the result of running diffstat on the patch is inserted.
12866 Finally, the patch itself, as generated by hg export.
12868 With the -d/--diffstat or --confirm options, you will be presented with
12870 a final summary of all messages and asked for confirmation before the
12871 messages are sent.
12872 By default the patch is included as text in the email body for easy re‐
12874 viewing. Using the -a/--attach option will instead create an attachment
12875 for the patch. With -i/--inline an inline attachment will be created.
12876 You can include a patch both as text in the email body and as a regular
12877 or an inline attachment by combining the -a/--attach or -i/--inline
12878 with the --body option.
12879 With -B/--bookmark changesets reachable by the given bookmark are se‐
12881 lected.
12882 With -o/--outgoing, emails will be generated for patches not found in
12884 the destination repository (or only those which are ancestors of the
12885 specified revisions if any are provided)
12886 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
12888 gle email containing a binary Mercurial bundle as an attachment will be
12889 sent. Use the patchbomb.bundletype config option to control the bundle
12890 type as with hg bundle --type.
12891 With -m/--mbox, instead of previewing each patchbomb message in a pager
12893 or sending the messages directly, it will create a UNIX mailbox file
12894 with the patch emails. This mailbox file can be previewed with any mail
12895 user agent which supports UNIX mbox files.
12896 With -n/--test, all steps will run, but mail will not be sent. You
12898 will be prompted for an email recipient address, a subject and an in‐
12899 troductory message describing the patches of your patchbomb. Then when
12900 all is done, patchbomb messages are displayed.
12901 In case email sending fails, you will find a backup of your series in‐
12903 troductory message in .hg/last-email.txt.
12904 The default behavior of this command can be customized through configu‐
12906 ration. (See hg help patchbomb for details)
12907 Examples:
12909 hg email -r 3000 # send patch 3000 only
12911 hg email -r 3000 -r 3001 # send patches 3000 and 3001
12912 hg email -r 3000:3005 # send patches 3000 through 3005
12913 hg email 3000 # send patch 3000 (deprecated)
12914 hg email -o # send all patches not in default
12916 hg email -o DEST # send all patches not in DEST
12917 hg email -o -r 3000 # send all ancestors of 3000 not in default
12918 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
12919 hg email -B feature # send all ancestors of feature bookmark
12921 hg email -b # send bundle of all patches not in default
12923 hg email -b DEST # send bundle of all patches not in DEST
12924 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
12925 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
12926 hg email -o -m mbox && # generate an mbox file...
12928 mutt -R -f mbox # ... and view it with mutt
12929 hg email -o -m mbox && # generate an mbox file ...
12930 formail -s sendmail \ # ... and use formail to send from the mbox
12931 -bm -t < mbox # ... using sendmail
12932 Before using this command, you will need to enable email in your hgrc.
12934 See the [email] section in hgrc(5) for details.
12935 Options:
12937 -g, --git
12939 use git extended diff format
12940 --plain
12942 omit hg patch header
12943 -o, --outgoing
12945 send changes not found in the target repository
12946 -b, --bundle
12948 send changes not in target as a binary bundle
12949 -B,--bookmark <BOOKMARK>
12951 send changes only reachable by given bookmark
12952 --bundlename <NAME>
12954 name of the bundle attachment file (default: bundle)
12955 -r,--rev <REV[+]>
12957 a revision to send
12958 --force
12960 run even when remote repository is unrelated (with -b/--bundle)
12961 --base <REV[+]>
12963 a base changeset to specify instead of a destination (with
12964 -b/--bundle)
12965 --intro
12967 send an introduction email for a single patch
12968 --body send patches as inline message text (default)
12970 -a, --attach
12972 send patches as attachments
12973 -i, --inline
12975 send patches as inline attachments
12976 --bcc <EMAIL[+]>
12978 email addresses of blind carbon copy recipients
12979 -c,--cc <EMAIL[+]>
12981 email addresses of copy recipients
12982 --confirm
12984 ask for confirmation before sending
12985 -d, --diffstat
12987 add diffstat output to messages
12988 --date <DATE>
12990 use the given date as the sending date
12991 --desc <FILE>
12993 use the given file as the series description
12994 -f,--from <EMAIL>
12996 email address of sender
12997 -n, --test
12999 print messages that would be sent
13000 -m,--mbox <FILE>
13002 write messages to mbox file instead of sending them
13003 --reply-to <EMAIL[+]>
13005 email addresses replies should be sent to
13006 -s,--subject <TEXT>
13008 subject of first message (intro or single patch)
13009 --in-reply-to <MSGID>
13011 message identifier to reply to
13012 --flag <FLAG[+]>
13014 flags to add in subject prefixes
13015 -t,--to <EMAIL[+]>
13017 email addresses of recipients
13018 -e,--ssh <CMD>
13020 specify ssh command to use
13021 --remotecmd <CMD>
13023 specify hg command to run on the remote side
13024 --insecure
13026 do not verify server certificate (ignoring web.cacerts config)
13027 [+] marked option can be specified multiple times
13029 phabricator
13031 simple Phabricator integration (EXPERIMENTAL)
13032 This extension provides a phabsend command which sends a stack of
13034 changesets to Phabricator, and a phabread command which prints a stack
13035 of revisions in a format suitable for hg import, and a phabupdate com‐
13036 mand to update statuses in batch.
13037 A "phabstatus" view for hg show is also provided; it displays status
13039 information of Phabricator differentials associated with unfinished
13040 changesets.
13041 By default, Phabricator requires Test Plan which might prevent some
13043 changeset from being sent. The requirement could be disabled by chang‐
13044 ing differential.require-test-plan-field config server side.
13045 Config:
13047 [phabricator]
13049 # Phabricator URL
13050 url = https://phab.example.com/
13051 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
13053 # callsign is "FOO".
13054 callsign = FOO
13055 # curl command to use. If not set (default), use builtin HTTP library to
13057 # communicate. If set, use the specified curl command. This could be useful
13058 # if you need to specify advanced options that is not easily supported by
13059 # the internal library.
13060 curlcmd = curl --connect-timeout 2 --retry 3 --silent
13061 # retry failed command N time (default 0). Useful when using the extension
13063 # over flakly connection.
13064 #
13065 # We wait `retry.interval` between each retry, in seconds.
13066 # (default 1 second).
13067 retry = 3
13068 retry.interval = 10
13069 # the retry option can combine well with the http.timeout one.
13071 #
13072 # For example to give up on http request after 20 seconds:
13073 [http]
13074 timeout=20
13075 [auth]
13077 example.schemes = https
13078 example.prefix = phab.example.com
13079 # API token. Get it from https://$HOST/conduit/login/
13081 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
13082 Commands
13084 Change import/export
13085 phabimport
13086 import patches from Phabricator for the specified Differential Revi‐
13087 sions:
13088 hg phabimport DREVSPEC... [OPTIONS]
13090 The patches are read and applied starting at the parent of the working
13092 directory.
13093 See hg help phabread for how to specify DREVSPEC.
13095 Options:
13097 --stack
13099 import dependencies as well
13100 --test-vcr <VALUE>
13102 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13103 script, otherwise will mock all http requests using the speci‐
13104 fied vcr file. (ADVANCED)
13105 phabread
13107 print patches from Phabricator suitable for importing:
13108 hg phabread DREVSPEC... [OPTIONS]
13110 DREVSPEC could be a Differential Revision identity, like D123, or just
13112 the number 123. It could also have common operators like +, -, &, (, )
13113 for complex queries. Prefix : could be used to select a stack. If mul‐
13114 tiple DREVSPEC values are given, the result is the union of each indi‐
13115 vidually evaluated value. No attempt is currently made to reorder the
13116 values to run from parent to child.
13117 abandoned, accepted, closed, needsreview, needsrevision could be used
13119 to filter patches by status. For performance reason, they only repre‐
13120 sent a subset of non-status selections and cannot be used alone.
13121 For example, :D6+8-(2+D4) selects a stack up to D6, plus D8 and exclude
13123 D2 and D4. :D9 & needsreview selects "Needs Review" revisions in a
13124 stack up to D9.
13125 If --stack is given, follow dependencies information and read all
13127 patches. It is equivalent to the : operator.
13128 Options:
13130 --stack
13132 read dependencies
13133 --test-vcr <VALUE>
13135 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13136 script, otherwise will mock all http requests using the speci‐
13137 fied vcr file. (ADVANCED)
13138 phabsend
13140 upload changesets to Phabricator:
13141 hg phabsend REV [OPTIONS]
13143 If there are multiple revisions specified, they will be send as a stack
13145 with a linear dependencies relationship using the order specified by
13146 the revset.
13147 For the first time uploading changesets, local tags will be created to
13149 maintain the association. After the first time, phabsend will check ob‐
13150 sstore and tags information so it can figure out whether to update an
13151 existing Differential Revision, or create a new one.
13152 If --amend is set, update commit messages so they have the Differential
13154 Revision URL, remove related tags. This is similar to what arcanist
13155 will do, and is more desired in author-push workflows. Otherwise, use
13156 local tags to record the Differential Revision association.
13157 The --confirm option lets you confirm changesets before sending them.
13159 You can also add following to your configuration file to make it de‐
13160 fault behaviour:
13161 [phabsend]
13163 confirm = true
13164 By default, a separate review will be created for each commit that is
13166 selected, and will have the same parent/child relationship in Phabrica‐
13167 tor. If --fold is set, multiple commits are rolled up into a single
13168 review as if diffed from the parent of the first revision to the last.
13169 The commit messages are concatenated in the summary field on Phabrica‐
13170 tor.
13171 phabsend will check obsstore and the above association to decide
13173 whether to update an existing Differential Revision, or create a new
13174 one.
13175 Options:
13177 -r,--rev <REV[+]>
13179 revisions to send
13180 --amend
13182 update commit messages (default: True)
13183 --reviewer <VALUE[+]>
13185 specify reviewers
13186 --blocker <VALUE[+]>
13188 specify blocking reviewers
13189 -m,--comment <VALUE>
13191 add a comment to Revisions with new/updated Diffs
13192 --confirm
13194 ask for confirmation before sending
13195 --fold combine the revisions into one review
13197 --test-vcr <VALUE>
13199 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13200 script, otherwise will mock all http requests using the speci‐
13201 fied vcr file. (ADVANCED)
13202 [+] marked option can be specified multiple times
13204 phabupdate
13206 update Differential Revision in batch:
13207 hg phabupdate [DREVSPEC...| -r REV...] [OPTIONS]
13209 DREVSPEC selects revisions. See hg help phabread for its usage.
13211 Options:
13213 --accept
13215 accept revisions
13216 --reject
13218 reject revisions
13219 --request-review
13221 request review on revisions
13222 --abandon
13224 abandon revisions
13225 --reclaim
13227 reclaim revisions
13228 --close
13230 close revisions
13231 --reopen
13233 reopen revisions
13234 --plan-changes
13236 plan changes for revisions
13237 --resign
13239 resign as a reviewer from revisions
13240 --commandeer
13242 commandeer revisions
13243 -m,--comment <VALUE>
13245 comment on the last revision
13246 -r,--rev <REV>
13248 local revision to update
13249 --test-vcr <VALUE>
13251 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13252 script, otherwise will mock all http requests using the speci‐
13253 fied vcr file. (ADVANCED)
13254 Uncategorized commands
13256 purge
13257 command to delete untracked files from the working directory (DEPRE‐
13258 CATED)
13259 The functionality of this extension has been included in core Mercurial
13261 since version 5.7. Please use hg purge ... instead. hg purge --confirm
13262 is now the default, unless the extension is enabled for backward com‐
13263 patibility.
13264 rebase
13266 command to move sets of revisions to a different ancestor
13267 This extension lets you rebase changesets in an existing Mercurial
13269 repository.
13270 For more information: https://mercurial-scm.org/wiki/RebaseExtension
13272 Commands
13274 Change manipulation
13275 rebase
13276 move changeset (and descendants) to a different branch:
13277 hg rebase [[-s REV]... | [-b REV]... | [-r REV]...] [-d REV] [OPTION]...
13279 Rebase uses repeated merging to graft changesets from one part of his‐
13281 tory (the source) onto another (the destination). This can be useful
13282 for linearizing local changes relative to a master development tree.
13283 Published commits cannot be rebased (see hg help phases). To copy com‐
13285 mits, see hg help graft.
13286 If you don't specify a destination changeset (-d/--dest), rebase will
13288 use the same logic as hg merge to pick a destination. if the current
13289 branch contains exactly one other head, the other head is merged with
13290 by default. Otherwise, an explicit revision with which to merge with
13291 must be provided. (destination changeset is not modified by rebasing,
13292 but new changesets are added as its descendants.)
13293 Here are the ways to select changesets:
13295 1. Explicitly select them using --rev.
13297 2. Use --source to select a root changeset and include all of its
13299 descendants.
13300 3. Use --base to select a changeset; rebase will find ancestors and
13302 their descendants which are not also ancestors of the destina‐
13303 tion.
13304 4. If you do not specify any of --rev, --source, or --base, rebase
13306 will use --base . as above.
13307 If --source or --rev is used, special names SRC and ALLSRC can be used
13309 in --dest. Destination would be calculated per source revision with SRC
13310 substituted by that single source revision and ALLSRC substituted by
13311 all source revisions.
13312 Rebase will destroy original changesets unless you use --keep. It will
13314 also move your bookmarks (even if you do).
13315 Some changesets may be dropped if they do not contribute changes (e.g.
13317 merges from the destination branch).
13318 Unlike merge, rebase will do nothing if you are at the branch tip of a
13320 named branch with two heads. You will need to explicitly specify source
13321 and/or destination.
13322 If you need to use a tool to automate merge/conflict decisions, you can
13324 specify one with --tool, see hg help merge-tools. As a caveat: the
13325 tool will not be used to mediate when a file was deleted, there is no
13326 hook presently available for this.
13327 If a rebase is interrupted to manually resolve a conflict, it can be
13329 continued with --continue/-c, aborted with --abort/-a, or stopped with
13330 --stop.
13331 Examples:
13333 • move "local changes" (current commit back to branching point) to the
13335 current branch tip after a pull:
13336 hg rebase
13338 • move a single changeset to the stable branch:
13340 hg rebase -r 5f493448 -d stable
13342 • splice a commit and all its descendants onto another part of history:
13344 hg rebase --source c0c3 --dest 4cf9
13346 • rebase everything on a branch marked by a bookmark onto the default
13348 branch:
13349 hg rebase --base myfeature --dest default
13351 • collapse a sequence of changes into a single commit:
13353 hg rebase --collapse -r 1520:1525 -d .
13355 • move a named branch while preserving its name:
13357 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
13359 • stabilize orphaned changesets so history looks linear:
13361 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
13363 Configuration Options:
13365 You can make rebase require a destination if you set the following con‐
13367 fig option:
13368 [commands]
13370 rebase.requiredest = True
13371 By default, rebase will close the transaction after each commit. For
13373 performance purposes, you can configure rebase to use a single transac‐
13374 tion across the entire rebase. WARNING: This setting introduces a sig‐
13375 nificant risk of losing the work you've done in a rebase if the rebase
13376 aborts unexpectedly:
13377 [rebase]
13379 singletransaction = True
13380 By default, rebase writes to the working copy, but you can configure it
13382 to run in-memory for better performance. When the rebase is not moving
13383 the parent(s) of the working copy (AKA the "currently checked out
13384 changesets"), this may also allow it to run even if the working copy is
13385 dirty:
13386 [rebase]
13388 experimental.inmemory = True
13389 Return Values:
13391 Returns 0 on success, 1 if nothing to rebase or there are unresolved
13393 conflicts.
13394 Options:
13396 -s,--source <REV[+]>
13398 rebase the specified changesets and their descendants
13399 -b,--base <REV[+]>
13401 rebase everything from branching point of specified changeset
13402 -r,--rev <REV[+]>
13404 rebase these revisions
13405 -d,--dest <REV>
13407 rebase onto the specified changeset
13408 --collapse
13410 collapse the rebased changesets
13411 -m,--message <TEXT>
13413 use text as collapse commit message
13414 -e, --edit
13416 invoke editor on commit messages
13417 -l,--logfile <FILE>
13419 read collapse commit message from file
13420 -k, --keep
13422 keep original changesets
13423 --keepbranches
13425 keep original branch names
13426 -D, --detach
13428 (DEPRECATED)
13429 -i, --interactive
13431 (DEPRECATED)
13432 -t,--tool <VALUE>
13434 specify merge tool
13435 --stop stop interrupted rebase
13437 -c, --continue
13439 continue an interrupted rebase
13440 -a, --abort
13442 abort an interrupted rebase
13443 --auto-orphans <VALUE>
13445 automatically rebase orphan revisions in the specified revset
13446 (EXPERIMENTAL)
13447 -n, --dry-run
13449 do not perform actions, just print output
13450 -T,--template <TEMPLATE>
13452 display with template
13453 --confirm
13455 ask before applying actions
13456 [+] marked option can be specified multiple times
13458 record
13460 commands to interactively select changes for commit/qrefresh (DEPRE‐
13461 CATED)
13462 The feature provided by this extension has been moved into core Mercu‐
13464 rial as hg commit --interactive.
13465 Commands
13467 Change creation
13468 qrecord
13469 interactively record a new patch:
13470 hg qrecord [OPTION]... PATCH [FILE]...
13472 See hg help qnew & hg help record for more information and usage.
13474 record
13476 interactively select changes to commit:
13477 hg record [OPTION]... [FILE]...
13479 If a list of files is omitted, all changes reported by hg status will
13481 be candidates for recording.
13482 See hg help dates for a list of formats valid for -d/--date.
13484 If using the text interface (see hg help config), you will be prompted
13486 for whether to record changes to each modified file, and for files with
13487 multiple changes, for each change to use. For each query, the following
13488 responses are possible:
13489 y - record this change
13491 n - skip this change
13492 e - edit this change manually
13493 s - skip remaining changes to this file
13495 f - record remaining changes to this file
13496 d - done, skip remaining changes and files
13498 a - record all changes to all remaining files
13499 q - quit, recording no changes
13500 ? - display help
13502 This command is not available when committing a merge.
13504 Options:
13506 -A, --addremove
13508 mark new/missing files as added/removed before committing
13509 --close-branch
13511 mark a branch head as closed
13512 --amend
13514 amend the parent of the working directory
13515 -s, --secret
13517 use the secret phase for committing
13518 -e, --edit
13520 invoke editor on commit messages
13521 --force-close-branch
13523 forcibly close branch from a non-head changeset (ADVANCED)
13524 -I,--include <PATTERN[+]>
13526 include names matching the given patterns
13527 -X,--exclude <PATTERN[+]>
13529 exclude names matching the given patterns
13530 -m,--message <TEXT>
13532 use text as commit message
13533 -l,--logfile <FILE>
13535 read commit message from file
13536 -d,--date <DATE>
13538 record the specified date as commit date
13539 -u,--user <USER>
13541 record the specified user as committer
13542 -S, --subrepos
13544 recurse into subrepositories
13545 -w, --ignore-all-space
13547 ignore white space when comparing lines
13548 -b, --ignore-space-change
13550 ignore changes in the amount of white space
13551 -B, --ignore-blank-lines
13553 ignore changes whose lines are all blank
13554 -Z, --ignore-space-at-eol
13556 ignore changes in whitespace at EOL
13557 [+] marked option can be specified multiple times
13559 releasenotes
13561 generate release notes from commit messages (EXPERIMENTAL)
13562 It is common to maintain files detailing changes in a project between
13564 releases. Maintaining these files can be difficult and time consuming.
13565 The hg releasenotes command provided by this extension makes the
13566 process simpler by automating it.
13567 Commands
13569 Change navigation
13570 releasenotes
13571 parse release notes from commit messages into an output file:
13572 hg releasenotes [-r REV] [-c] FILE
13574 Given an output file and set of revisions, this command will parse com‐
13576 mit messages for release notes then add them to the output file.
13577 Release notes are defined in commit messages as ReStructuredText direc‐
13579 tives. These have the form:
13580 .. directive:: title
13582 content
13584 Each directive maps to an output section in a generated release notes
13586 file, which itself is ReStructuredText. For example, the .. feature::
13587 directive would map to a New Features section.
13588 Release note directives can be either short-form or long-form. In
13590 short- form, title is omitted and the release note is rendered as a
13591 bullet list. In long form, a sub-section with the title title is added
13592 to the section.
13593 The FILE argument controls the output file to write gathered release
13595 notes to. The format of the file is:
13596 Section 1
13598 =========
13599 ...
13601 Section 2
13603 =========
13604 ...
13606 Only sections with defined release notes are emitted.
13608 If a section only has short-form notes, it will consist of bullet list:
13610 Section
13612 =======
13613 * Release note 1
13615 * Release note 2
13616 If a section has long-form notes, sub-sections will be emitted:
13618 Section
13620 =======
13621 Note 1 Title
13623 ------------
13624 Description of the first long-form note.
13626 Note 2 Title
13628 ------------
13629 Description of the second long-form note.
13631 If the FILE argument points to an existing file, that file will be
13633 parsed for release notes having the format that would be generated by
13634 this command. The notes from the processed commit messages will be
13635 merged into this parsed set.
13636 During release notes merging:
13638 • Duplicate items are automatically ignored
13640 • Items that are different are automatically ignored if the similarity
13642 is greater than a threshold.
13643 This means that the release notes file can be updated independently
13645 from this command and changes should not be lost when running this com‐
13646 mand on that file. A particular use case for this is to tweak the word‐
13647 ing of a release note after it has been added to the release notes
13648 file.
13649 The -c/--check option checks the commit message for invalid admoni‐
13651 tions.
13652 The -l/--list option, presents the user with a list of existing avail‐
13654 able admonitions along with their title. This also includes the custom
13655 admonitions (if any).
13656 Options:
13658 -r,--rev <REV>
13660 revisions to process for release notes
13661 -c, --check
13663 checks for validity of admonitions (if any)
13664 -l, --list
13666 list the available admonitions with their title
13667 Uncategorized commands
13669 relink
13670 recreates hardlinks between repository clones
13671 Commands
13673 Repository maintenance
13674 relink
13675 recreate hardlinks between two repositories:
13676 hg relink [ORIGIN]
13678 When repositories are cloned locally, their data files will be
13680 hardlinked so that they only use the space of a single repository.
13681 Unfortunately, subsequent pulls into either repository will break
13683 hardlinks for any files touched by the new changesets, even if both
13684 repositories end up pulling the same changes.
13685 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
13687 falling back to a complete copy of the source repository.
13688 This command lets you recreate those hardlinks and reclaim that wasted
13690 space.
13691 This repository will be relinked to share space with ORIGIN, which must
13693 be on the same local disk. If ORIGIN is omitted, looks for "default-re‐
13694 link", then "default", in [paths].
13695 Do not attempt any read operations on this repository while the command
13697 is running. (Both repositories will be locked against writes.)
13698 remotefilelog
13700 remotefilelog causes Mercurial to lazilly fetch file contents (EXPERI‐
13701 MENTAL)
13702 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13704 BILITY GUARANTEES. This means that repositories created with this ex‐
13705 tension may only be usable with the exact version of this exten‐
13706 sion/Mercurial that was used. The extension attempts to enforce this in
13707 order to prevent repository corruption.
13708 remotefilelog works by fetching file contents lazily and storing them
13710 in a cache on the client rather than in revlogs. This allows enormous
13711 histories to be transferred only partially, making them easier to oper‐
13712 ate on.
13713 Configs:
13715 packs.maxchainlen specifies the maximum delta chain length in pack
13717 files
13718 packs.maxpacksize specifies the maximum pack file size
13720 packs.maxpackfilecount specifies the maximum number of packs in the
13722 shared cache (trees only for now)
13724 remotefilelog.backgroundprefetch runs prefetch in background when
13726 True
13727 remotefilelog.bgprefetchrevs specifies revisions to fetch on commit
13729 and
13730 update, and on other commands that use them. Different from
13732 pullprefetch.
13733 remotefilelog.gcrepack does garbage collection during repack when
13735 True
13736 remotefilelog.nodettl specifies maximum TTL of a node in seconds be‐
13738 fore
13739 it is garbage collected
13741 remotefilelog.repackonhggc runs repack on hg gc when True
13743 remotefilelog.prefetchdays specifies the maximum age of a commit in
13745 days after which it is no longer prefetched.
13747 remotefilelog.prefetchdelay specifies delay between background
13749 prefetches in seconds after operations that change the work‐
13751 ing copy parent
13752 remotefilelog.data.gencountlimit constraints the minimum number of
13754 data
13755 pack files required to be considered part of a generation. In
13757 particular, minimum number of packs files > gencountlimit.
13758 remotefilelog.data.generations list for specifying the lower bound
13760 of
13761 each generation of the data pack files. For example, list
13763 ['100MB','1MB'] or ['1MB', '100MB'] will lead to three gener‐
13764 ations: [0, 1MB), [ 1MB, 100MB) and [100MB, infinity).
13765 remotefilelog.data.maxrepackpacks the maximum number of pack files
13767 to
13768 include in an incremental data repack.
13770 remotefilelog.data.repackmaxpacksize the maximum size of a pack file
13772 for
13773 it to be considered for an incremental data repack.
13775 remotefilelog.data.repacksizelimit the maximum total size of pack
13777 files
13778 to include in an incremental data repack.
13780 remotefilelog.history.gencountlimit constraints the minimum number
13782 of
13783 history pack files required to be considered part of a gener‐
13785 ation. In particular, minimum number of packs files > gen‐
13786 countlimit.
13787 remotefilelog.history.generations list for specifying the lower
13789 bound of
13790 each generation of the history pack files. For example, list
13792 [ '100MB', '1MB'] or ['1MB', '100MB'] will lead to three gen‐
13793 erations: [ 0, 1MB), [1MB, 100MB) and [100MB, infinity).
13794 remotefilelog.history.maxrepackpacks the maximum number of pack
13796 files to
13797 include in an incremental history repack.
13799 remotefilelog.history.repackmaxpacksize the maximum size of a pack
13801 file
13802 for it to be considered for an incremental history repack.
13804 remotefilelog.history.repacksizelimit the maximum total size of pack
13806 files to include in an incremental history repack.
13808 remotefilelog.backgroundrepack automatically consolidate packs in
13810 the
13811 background
13813 remotefilelog.cachepath path to cache
13815 remotefilelog.cachegroup if set, make cache directory sgid to this
13817 group
13819 remotefilelog.cacheprocess binary to invoke for fetching file data
13821 remotefilelog.debug turn on remotefilelog-specific debug output
13823 remotefilelog.excludepattern pattern of files to exclude from pulls
13825 remotefilelog.includepattern pattern of files to include in pulls
13827 remotefilelog.fetchwarning: message to print when too many
13829 single-file fetches occur
13831 remotefilelog.getfilesstep number of files to request in a single
13833 RPC
13834 remotefilelog.getfilestype if set to 'threaded' use threads to fetch
13836 files, otherwise use optimistic fetching
13838 remotefilelog.pullprefetch revset for selecting files that should be
13840 eagerly downloaded rather than lazily
13842 remotefilelog.reponame name of the repo. If set, used to partition
13844 data from other repos in a shared store.
13846 remotefilelog.server if true, enable server-side functionality
13848 remotefilelog.servercachepath path for caching blobs on the server
13850 remotefilelog.serverexpiration number of days to keep cached server
13852 blobs
13854 remotefilelog.validatecache if set, check cache entries for corrup‐
13856 tion
13857 before returning blobs
13859 remotefilelog.validatecachelog if set, check cache entries for
13861 corruption before returning metadata
13863 Commands
13865 Repository maintenance
13866 prefetch
13867 prefetch file revisions from the server:
13868 hg prefetch [OPTIONS] [FILE...]
13870 Prefetchs file revisions for the specified revs and stores them in the
13872 local remotefilelog cache. If no rev is specified, the default rev is
13873 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
13874 File names or patterns can be used to limit which files are downloaded.
13875 Return 0 on success.
13877 Options:
13879 -r,--rev <REV[+]>
13881 prefetch the specified revisions
13882 --repack
13884 run repack after prefetch
13885 -b,--base <VALUE>
13887 rev that is assumed to already be local
13888 -I,--include <PATTERN[+]>
13890 include names matching the given patterns
13891 -X,--exclude <PATTERN[+]>
13893 exclude names matching the given patterns
13894 [+] marked option can be specified multiple times
13896 Uncategorized commands
13898 gc
13899 garbage collect the client and server filelog caches:
13900 hg gc [REPO...]
13902 garbage collect the client and server filelog caches
13904 repack
13906 hg repack [OPTIONS]
13907 Options:
13909 --background
13911 run in a background process
13912 --incremental
13914 do an incremental repack
13915 --packsonly
13917 only repack packs (skip loose objects)
13918 verifyremotefilelog
13920 hg verifyremotefilelogs <directory>
13921 Options:
13923 -d, --decompress
13925 decompress the filelogs first
13926 remotenames
13928 showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)
13929 By default both remotebookmarks and remotebranches are turned on. Con‐
13931 fig knob to control the individually are as follows.
13932 Config options to tweak the default behaviour:
13934 remotenames.bookmarks
13936 Boolean value to enable or disable showing of remotebookmarks
13937 (default: True)
13938 remotenames.branches
13940 Boolean value to enable or disable showing of remotebranches
13941 (default: True)
13942 remotenames.hoistedpeer
13944 Name of the peer whose remotebookmarks should be hoisted into
13945 the top-level namespace (default: 'default')
13946 schemes
13948 extend schemes with shortcuts to repository swarms
13949 This extension allows you to specify shortcuts for parent URLs with a
13951 lot of repositories to act like a scheme, for example:
13952 [schemes]
13954 py = http://code.python.org/hg/
13955 After that you can use it like:
13957 hg clone py://trunk/
13959 Additionally there is support for some more complex schemas, for exam‐
13961 ple used by Google Code:
13962 [schemes]
13964 gcode = http://{1}.googlecode.com/hg/
13965 The syntax is taken from Mercurial templates, and you have unlimited
13967 number of variables, starting with {1} and continuing with {2}, {3} and
13968 so on. This variables will receive parts of URL supplied, split by /.
13969 Anything not specified as {part} will be just appended to an URL.
13970 For convenience, the extension adds these schemes by default:
13972 [schemes]
13974 py = http://hg.python.org/
13975 bb = https://bitbucket.org/
13976 bb+ssh = ssh://hg@bitbucket.org/
13977 gcode = https://{1}.googlecode.com/hg/
13978 kiln = https://{1}.kilnhg.com/Repo/
13979 You can override a predefined scheme by defining a new scheme with the
13981 same name.
13982 Commands
13984 Uncategorized commands
13985 share
13986 share a common history between several working directories
13987 The share extension introduces a new command hg share to create a new
13989 working directory. This is similar to hg clone, but doesn't involve
13990 copying or linking the storage of the repository. This allows working
13991 on different branches or changes in parallel without the associated
13992 cost in terms of disk space.
13993 Note: destructive operations or extensions like hg rollback should be
13995 used with care as they can result in confusing problems.
13996 Automatic Pooled Storage for Clones
13998 When this extension is active, hg clone can be configured to automati‐
13999 cally share/pool storage across multiple clones. This mode effectively
14000 converts hg clone to hg clone + hg share. The benefit of using this
14001 mode is the automatic management of store paths and intelligent pooling
14002 of related repositories.
14003 The following share. config options influence this feature:
14005 share.pool
14007 Filesystem path where shared repository data will be stored.
14009 When defined, hg clone will automatically use shared repository
14010 storage instead of creating a store inside each clone.
14011 share.poolnaming
14013 How directory names in share.pool are constructed.
14015 "identity" means the name is derived from the first changeset in
14017 the repository. In this mode, different remotes share storage if
14018 their root/initial changeset is identical. In this mode, the lo‐
14019 cal shared repository is an aggregate of all encountered remote
14020 repositories.
14021 "remote" means the name is derived from the source repository's
14023 path or URL. In this mode, storage is only shared if the path or
14024 URL requested in the hg clone command matches exactly to a
14025 repository that was cloned before.
14026 The default naming mode is "identity".
14028 Sharing requirements and configs of source repository with shares:
14030 By default creating a shared repository only enables sharing a common
14032 history and does not share requirements and configs between them. This
14033 may lead to problems in some cases, for example when you upgrade the
14034 storage format from one repository but does not set related configs in
14035 the shares.
14036 Setting format.exp-share-safe = True enables sharing configs and re‐
14038 quirements. This only applies to shares which are done after enabling
14039 the config option.
14040 For enabling this in existing shares, enable the config option and re‐
14042 share.
14043 For resharing existing shares, make sure your working directory is
14045 clean and there are no untracked files, delete that share and create a
14046 new share.
14047 Commands
14049 Repository creation
14050 share
14051 create a new shared repository:
14052 hg share [-U] [-B] SOURCE [DEST]
14054 Initialize a new repository and working directory that shares its his‐
14056 tory (and optionally bookmarks) with another repository.
14057 Note using rollback or extensions that destroy/modify history (mq,
14059 rebase, etc.) can cause considerable confusion with shared
14060 clones. In particular, if two shared clones are both updated to
14061 the same changeset, and one of them destroys that changeset with
14062 rollback, the other clone will suddenly stop working: all opera‐
14063 tions will fail with "abort: working directory has unknown par‐
14064 ent". The only known workaround is to use debugsetparents on the
14065 broken clone to reset it to a changeset that still exists.
14066 Options:
14068 -U, --noupdate
14070 do not create a working directory
14071 -B, --bookmarks
14073 also share bookmarks
14074 --relative
14076 point to source using a relative path
14077 Repository maintenance
14079 unshare
14080 convert a shared repository to a normal one:
14081 hg unshare
14083 Copy the store data to the repo and remove the sharedpath data.
14085 show
14087 unified command to show various repository information (EXPERIMENTAL)
14088 This extension provides the hg show command, which provides a central
14090 command for displaying commonly-accessed repository data and views of
14091 that data.
14092 The following config options can influence operation.
14094 commands
14096 show.aliasprefix
14097 List of strings that will register aliases for views. e.g. s
14099 will effectively set config options alias.s<view> = show <view>
14100 for all views. i.e. hg swork would execute hg show work.
14101 Aliases that would conflict with existing registrations will not
14103 be performed.
14104 Commands
14106 Change navigation
14107 show
14108 show various repository information:
14109 hg show VIEW
14111 A requested view of repository data is displayed.
14113 If no view is requested, the list of available views is shown and the
14115 command aborts.
14116 Note There are no backwards compatibility guarantees for the output
14118 of this command. Output may change in any future Mercurial re‐
14119 lease.
14120 Consumers wanting stable command output should specify a tem‐
14122 plate via -T/--template.
14123 List of available views:
14125 bookmarks bookmarks and their associated changeset
14127 stack current line of work
14129 work changesets that aren't finished
14131 Options:
14133 -T,--template <TEMPLATE>
14135 display with template
14136 sparse
14138 allow sparse checkouts of the working directory (EXPERIMENTAL)
14139 (This extension is not yet protected by backwards compatibility guaran‐
14141 tees. Any aspect may break in future releases until this notice is re‐
14142 moved.)
14143 This extension allows the working directory to only consist of a subset
14145 of files for the revision. This allows specific files or directories to
14146 be explicitly included or excluded. Many repository operations have
14147 performance proportional to the number of files in the working direc‐
14148 tory. So only realizing a subset of files in the working directory can
14149 improve performance.
14150 Sparse Config Files
14152 The set of files that are part of a sparse checkout are defined by a
14153 sparse config file. The file defines 3 things: includes (files to in‐
14154 clude in the sparse checkout), excludes (files to exclude from the
14155 sparse checkout), and profiles (links to other config files).
14156 The file format is newline delimited. Empty lines and lines beginning
14158 with # are ignored.
14159 Lines beginning with %include `` denote another sparse config file to
14161 include. e.g. ``%include tests.sparse. The filename is relative to the
14162 repository root.
14163 The special lines [include] and [exclude] denote the section for in‐
14165 cludes and excludes that follow, respectively. It is illegal to have
14166 [include] after [exclude].
14167 Non-special lines resemble file patterns to be added to either includes
14169 or excludes. The syntax of these lines is documented by hg help pat‐
14170 terns. Patterns are interpreted as glob: by default and match against
14171 the root of the repository.
14172 Exclusion patterns take precedence over inclusion patterns. So even if
14174 a file is explicitly included, an [exclude] entry can remove it.
14175 For example, say you have a repository with 3 directories, frontend/,
14177 backend/, and tools/. frontend/ and backend/ correspond to different
14178 projects and it is uncommon for someone working on one to need the
14179 files for the other. But tools/ contains files shared between both
14180 projects. Your sparse config files may resemble:
14181 # frontend.sparse
14183 frontend/**
14184 tools/**
14185 # backend.sparse
14187 backend/**
14188 tools/**
14189 Say the backend grows in size. Or there's a directory with thousands of
14191 files you wish to exclude. You can modify the profile to exclude cer‐
14192 tain files:
14193 [include]
14195 backend/**
14196 tools/**
14197 [exclude]
14199 tools/tests/**
14200 Commands
14202 Uncategorized commands
14203 split
14204 command to split a changeset into smaller ones (EXPERIMENTAL)
14205 Commands
14207 Change manipulation
14208 split
14209 split a changeset into smaller ones:
14210 hg split [--no-rebase] [[-r] REV]
14212 Repeatedly prompt changes and commit message for new changesets until
14214 there is nothing left in the original changeset.
14215 If --rev was not given, split the working directory parent.
14217 By default, rebase connected non-obsoleted descendants onto the new
14219 changeset. Use --no-rebase to avoid the rebase.
14220 Options:
14222 -r,--rev <REV>
14224 revision to split
14225 --rebase
14227 rebase descendants after split (default: True)
14228 -d,--date <DATE>
14230 record the specified date as commit date
14231 -u,--user <USER>
14233 record the specified user as committer
14234 sqlitestore
14236 store repository data in SQLite (EXPERIMENTAL)
14237 The sqlitestore extension enables the storage of repository data in
14239 SQLite.
14240 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
14242 BILITY GUARANTEES. This means that repositories created with this ex‐
14243 tension may only be usable with the exact version of this exten‐
14244 sion/Mercurial that was used. The extension attempts to enforce this in
14245 order to prevent repository corruption.
14246 In addition, several features are not yet supported or have known bugs:
14248 • Only some data is stored in SQLite. Changeset, manifest, and other
14250 repository data is not yet stored in SQLite.
14251 • Transactions are not robust. If the process is aborted at the right
14253 time during transaction close/rollback, the repository could be in an
14254 inconsistent state. This problem will diminish once all repository
14255 data is tracked by SQLite.
14256 • Bundle repositories do not work (the ability to use e.g. hg -R <bun‐
14258 dle-file> log to automatically overlay a bundle on top of the exist‐
14259 ing repository).
14260 • Various other features don't work.
14262 This extension should work for basic clone/pull, update, and commit
14264 workflows. Some history rewriting operations may fail due to lack of
14265 support for bundle repositories.
14266 To use, activate the extension and set the storage.new-repo-backend
14268 config option to sqlite to enable new repositories to use SQLite for
14269 storage.
14270 strip
14272 strip changesets and their descendants from history (DEPRECATED)
14273 The functionality of this extension has been included in core Mercurial
14275 since version 5.7. Please use hg debugstrip ... instead.
14276 This extension allows you to strip changesets and all their descendants
14278 from the repository. See the command help for details.
14279 transplant
14281 command to transplant changesets from another branch
14282 This extension allows you to transplant changes to another parent revi‐
14284 sion, possibly in another repository. The transplant is done using
14285 'diff' patches.
14286 Transplanted patches are recorded in .hg/transplant/transplants, as a
14288 map from a changeset hash to its hash in the source repository.
14289 Commands
14291 Change manipulation
14292 transplant
14293 transplant changesets from another branch:
14294 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
14296 Selected changesets will be applied on top of the current working di‐
14298 rectory with the log of the original changeset. The changesets are
14299 copied and will thus appear twice in the history with different identi‐
14300 ties.
14301 Consider using the graft command if everything is inside the same
14303 repository - it will use merges and will usually give a better result.
14304 Use the rebase extension if the changesets are unpublished and you want
14305 to move them instead of copying them.
14306 If --log is specified, log messages will have a comment appended of the
14308 form:
14309 (transplanted from CHANGESETHASH)
14311 You can rewrite the changelog message with the --filter option. Its
14313 argument will be invoked with the current changelog message as $1 and
14314 the patch as $2.
14315 --source/-s specifies another repository to use for selecting change‐
14317 sets, just as if it temporarily had been pulled. If --branch/-b is
14318 specified, these revisions will be used as heads when deciding which
14319 changesets to transplant, just as if only these revisions had been
14320 pulled. If --all/-a is specified, all the revisions up to the heads
14321 specified with --branch will be transplanted.
14322 Example:
14324 • transplant all changes up to REV on top of your current revision:
14326 hg transplant --branch REV --all
14328 You can optionally mark selected transplanted changesets as merge
14330 changesets. You will not be prompted to transplant any ancestors of a
14331 merged transplant, and you can merge descendants of them normally in‐
14332 stead of transplanting them.
14333 Merge changesets may be transplanted directly by specifying the proper
14335 parent changeset by calling hg transplant --parent.
14336 If no merges or revisions are provided, hg transplant will start an in‐
14338 teractive changeset browser.
14339 If a changeset application fails, you can fix the merge by hand and
14341 then resume where you left off by calling hg transplant --continue/-c.
14342 Options:
14344 -s,--source <REPO>
14346 transplant changesets from REPO
14347 -b,--branch <REV[+]>
14349 use this source changeset as head
14350 -a, --all
14352 pull all changesets up to the --branch revisions
14353 -p,--prune <REV[+]>
14355 skip over REV
14356 -m,--merge <REV[+]>
14358 merge at REV
14359 --parent <REV>
14361 parent to choose when transplanting merge
14362 -e, --edit
14364 invoke editor on commit messages
14365 --log append transplant info to log message
14367 --stop stop interrupted transplant
14369 -c, --continue
14371 continue last transplant session after fixing conflicts
14372 --filter <CMD>
14374 filter changesets through command
14375 [+] marked option can be specified multiple times
14377 uncommit
14379 uncommit part or all of a local changeset (EXPERIMENTAL)
14380 This command undoes the effect of a local commit, returning the af‐
14382 fected files to their uncommitted state. This means that files modi‐
14383 fied, added or removed in the changeset will be left unchanged, and so
14384 will remain modified, added and removed in the working directory.
14385 Commands
14387 Change manipulation
14388 unamend
14389 undo the most recent amend operation on a current changeset:
14390 hg unamend
14392 This command will roll back to the previous version of a changeset,
14394 leaving working directory in state in which it was before running hg
14395 amend (e.g. files modified as part of an amend will be marked as modi‐
14396 fied hg status)
14397 uncommit
14399 uncommit part or all of a local changeset:
14400 hg uncommit [OPTION]... [FILE]...
14402 This command undoes the effect of a local commit, returning the af‐
14404 fected files to their uncommitted state. This means that files modified
14405 or deleted in the changeset will be left unchanged, and so will remain
14406 modified in the working directory.
14407 If no files are specified, the commit will be pruned, unless --keep is
14409 given.
14410 Options:
14412 --keep allow an empty commit after uncommitting
14414 --allow-dirty-working-copy
14416 allow uncommit with outstanding changes
14417 -n,--note <TEXT>
14419 store a note on uncommit
14420 -I,--include <PATTERN[+]>
14422 include names matching the given patterns
14423 -X,--exclude <PATTERN[+]>
14425 exclude names matching the given patterns
14426 -m,--message <TEXT>
14428 use text as commit message
14429 -l,--logfile <FILE>
14431 read commit message from file
14432 -d,--date <DATE>
14434 record the specified date as commit date
14435 -u,--user <USER>
14437 record the specified user as committer
14438 -D, --currentdate
14440 record the current date as commit date
14441 -U, --currentuser
14443 record the current user as committer
14444 [+] marked option can be specified multiple times
14446 win32mbcs
14448 allow the use of MBCS paths with problematic encodings
14449 Some MBCS encodings are not good for some path operations (i.e. split‐
14451 ting path, case conversion, etc.) with its encoded bytes. We call such
14452 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
14453 extension can be used to fix the issue with those encodings by wrapping
14454 some functions to convert to Unicode string before path operation.
14455 This extension is useful for:
14457 • Japanese Windows users using shift_jis encoding.
14459 • Chinese Windows users using big5 encoding.
14461 • All users who use a repository with one of problematic encodings on
14463 case-insensitive file system.
14464 This extension is not needed for:
14466 • Any user who use only ASCII chars in path.
14468 • Any user who do not use any of problematic encodings.
14470 Note that there are some limitations on using this extension:
14472 • You should use single encoding in one repository.
14474 • If the repository path ends with 0x5c, .hg/hgrc cannot be read.
14476 • win32mbcs is not compatible with fixutf8 extension.
14478 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
14480 can specify the encoding by config option:
14481 [win32mbcs]
14483 encoding = sjis
14484 It is useful for the users who want to commit with UTF-8 log message.
14486 win32text
14488 perform automatic newline conversion (DEPRECATED)
14489 Deprecation: The win32text extension requires each user to configure
14491 the extension again and again for each clone since the configuration
14492 is not copied when cloning.
14493 We have therefore made the eol as an alternative. The eol uses a
14495 version controlled file for its configuration and each clone will
14496 therefore use the right settings from the start.
14497 To perform automatic newline conversion, use:
14499 [extensions]
14501 win32text =
14502 [encode]
14503 ** = cleverencode:
14504 # or ** = macencode:
14505 [decode]
14507 ** = cleverdecode:
14508 # or ** = macdecode:
14509 If not doing conversion, to make sure you do not commit CRLF/CR by ac‐
14511 cident:
14512 [hooks]
14514 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
14515 # or pretxncommit.cr = python:hgext.win32text.forbidcr
14516 To do the same check on a server to prevent CRLF/CR from being pushed
14518 or pulled:
14519 [hooks]
14521 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
14522 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
14523 zeroconf
14525 discover and advertise repositories on the local network
14526 The zeroconf extension will advertise hg serve instances over DNS-SD so
14528 that they can be discovered using the hg paths command without knowing
14529 the server's IP address.
14530 To allow other people to discover your repository using run hg serve in
14532 your repository:
14533 $ cd test
14535 $ hg serve
14536 You can discover Zeroconf-enabled repositories by running hg paths:
14538 $ hg paths
14540 zc-test = http://example.com:8000/test
14541
14543 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
14544 This file contains defaults and configuration. Values in
14546 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
14547 tings made in the global /etc/mercurial/hgrc configuration. See
14548 hgrc(5) for details of the contents and format of these files.
14549 .hgignore
14551 This file contains regular expressions (one per line) that de‐
14553 scribe file names that should be ignored by hg. For details, see
14554 hgignore(5).
14555 .hgsub
14557 This file defines the locations of all subrepositories, and
14559 tells where the subrepository checkouts came from. For details,
14560 see hg help subrepos.
14561 .hgsubstate
14563 This file is where Mercurial stores all nested repository
14565 states. NB: This file should not be edited manually.
14566 .hgtags
14568 This file contains changeset hash values and text tag names (one
14570 of each separated by spaces) that correspond to tagged versions
14571 of the repository contents. The file content is encoded using
14572 UTF-8.
14573 .hg/last-message.txt
14575 This file is used by hg commit to store a backup of the commit
14577 message in case the commit fails.
14578 .hg/localtags
14580 This file can be used to define local tags which are not shared
14582 among repositories. The file format is the same as for .hgtags,
14583 but it is encoded using the local system encoding.
14584 Some commands (e.g. revert) produce backup files ending in .orig, if
14586 the .orig file already exists and is not tracked by Mercurial, it will
14587 be overwritten.
14588
14590 Probably lots, please post them to the mailing list (see Resources
14591 below) when you find them.
14592
14594 hgignore(5), hgrc(5)
14595
14597 Written by Olivia Mackall <olivia@selenic.com>
14598
14600 Main Web Site: https://mercurial-scm.org/
14601 Source code repository: https://www.mercurial-scm.org/repo/hg
14603 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
14605
14607 Copyright (C) 2005-2022 Olivia Mackall. Free use of this software is
14608 granted under the terms of the GNU General Public License version 2 or
14609 any later version.
14610
14612 Olivia Mackall <olivia@selenic.com>
14613 Organization: Mercurial
14615 HG(1)