1HG(1) Mercurial Manual HG(1)
2
6 hg - Mercurial source code management system
7
9 hg command [option]... [argument]...
10
12 The hg command provides a command line interface to the Mercurial sys‐
13 tem.
14
16 files...
17 indicates one or more filename or relative path filenames; see
18 File Name Patterns for information on pattern matching
19 path indicates a path on the local machine
21 revision
23 indicates a changeset which can be specified as a changeset re‐
24 vision number, a tag, or a unique substring of the changeset
25 hash value
26 repository path
28 either the pathname of a local repository or the URI of a remote
29 repository.
30
32 -R,--repository <REPO>
33 repository root directory or name of overlay bundle file
34 --cwd <DIR>
36 change working directory
37 -y, --noninteractive
39 do not prompt, automatically pick the first choice for all
40 prompts
41 -q, --quiet
43 suppress output
44 -v, --verbose
46 enable additional output
47 --color <TYPE>
49 when to colorize (boolean, always, auto, never, or debug)
50 --config <CONFIG[+]>
52 set/override config option (use 'section.name=value')
53 --debug
55 enable debugging output
56 --debugger
58 start debugger
59 --encoding <ENCODE>
61 set the charset encoding (default: UTF-8)
62 --encodingmode <MODE>
64 set the charset encoding mode (default: strict)
65 --traceback
67 always print a traceback on exception
68 --time time how long the command takes
70 --profile
72 print command execution profile
73 --version
75 output version information and exit
76 -h, --help
78 display help and exit
79 --hidden
81 consider hidden changesets
82 --pager <TYPE>
84 when to paginate (boolean, always, auto, or never) (default:
85 auto)
86 [+] marked option can be specified multiple times
88
90 Repository creation
91 clone
92 make a copy of an existing repository:
93 hg clone [OPTION]... SOURCE [DEST]
95 Create a copy of an existing repository in a new directory.
97 If no destination directory name is specified, it defaults to the base‐
99 name of the source.
100 The location of the source is added to the new repository's .hg/hgrc
102 file, as the default to be used for future pulls.
103 Only local paths and ssh:// URLs are supported as destinations. For
105 ssh:// destinations, no working directory or .hg/hgrc will be created
106 on the remote side.
107 If the source repository has a bookmark called '@' set, that revision
109 will be checked out in the new repository by default.
110 To check out a particular version, use -u/--update, or -U/--noupdate to
112 create a clone with no working directory.
113 To pull only a subset of changesets, specify one or more revisions
115 identifiers with -r/--rev or branches with -b/--branch. The resulting
116 clone will contain only the specified changesets and their ancestors.
117 These options (or 'clone src#rev dest') imply --pull, even for local
118 source repositories.
119 In normal clone mode, the remote normalizes repository data into a com‐
121 mon exchange format and the receiving end translates this data into its
122 local storage format. --stream activates a different clone mode that
123 essentially copies repository files from the remote with minimal data
124 processing. This significantly reduces the CPU cost of a clone both re‐
125 motely and locally. However, it often increases the transferred data
126 size by 30-40%. This can result in substantially faster clones where
127 I/O throughput is plentiful, especially for larger repositories. A
128 side-effect of --stream clones is that storage settings and require‐
129 ments on the remote are applied locally: a modern client may inherit
130 legacy or inefficient storage used by the remote or a legacy Mercurial
131 client may not be able to clone from a modern Mercurial remote.
132 Note Specifying a tag will include the tagged changeset but not the
134 changeset containing the tag.
135 For efficiency, hardlinks are used for cloning whenever the source and
137 destination are on the same filesystem (note this applies only to the
138 repository data, not to the working directory). Some filesystems, such
139 as AFS, implement hardlinking incorrectly, but do not report errors. In
140 these cases, use the --pull option to avoid hardlinking.
141 Mercurial will update the working directory to the first applicable re‐
143 vision from this list:
144 a. null if -U or the source repository has no changesets
146 b. if -u . and the source repository is local, the first parent of the
148 source repository's working directory
149 c. the changeset specified with -u (if a branch name, this means the
151 latest head of that branch)
152 d. the changeset specified with -r
154 e. the tipmost head specified with -b
156 f. the tipmost head specified with the url#branch source syntax
158 g. the revision marked with the '@' bookmark, if present
160 h. the tipmost head of the default branch
162 i. tip
164 When cloning from servers that support it, Mercurial may fetch pre-gen‐
166 erated data from a server-advertised URL or inline from the same
167 stream. When this is done, hooks operating on incoming changesets and
168 changegroups may fire more than once, once for each pre-generated bun‐
169 dle and as well as for any additional remaining data. In addition, if
170 an error occurs, the repository may be rolled back to a partial clone.
171 This behavior may change in future releases. See hg help -e cloneb‐
172 undles for more.
173 Examples:
175 • clone a remote repository to a new directory named hg/:
177 hg clone https://www.mercurial-scm.org/repo/hg/
179 • create a lightweight local clone:
181 hg clone project/ project-feature/
183 • clone from an absolute path on an ssh server (note double-slash):
185 hg clone ssh://user@server//home/projects/alpha/
187 • do a streaming clone while checking out a specified version:
189 hg clone --stream http://server/repo -u 1.5
191 • create a repository without changesets after a particular revision:
193 hg clone -r 04e544 experimental/ good/
195 • clone (and track) a particular named branch:
197 hg clone https://www.mercurial-scm.org/repo/hg/#stable
199 See hg help urls for details on specifying URLs.
201 Returns 0 on success.
203 Options:
205 -U, --noupdate
207 the clone will include an empty working directory (only a repos‐
208 itory)
209 -u,--updaterev <REV>
211 revision, tag, or branch to check out
212 -r,--rev <REV[+]>
214 do not clone everything, but include this changeset and its an‐
215 cestors
216 -b,--branch <BRANCH[+]>
218 do not clone everything, but include this branch's changesets
219 and their ancestors
220 --pull use pull protocol to copy metadata
222 --uncompressed
224 an alias to --stream (DEPRECATED)
225 --stream
227 clone with minimal data processing
228 -e,--ssh <CMD>
230 specify ssh command to use
231 --remotecmd <CMD>
233 specify hg command to run on the remote side
234 --insecure
236 do not verify server certificate (ignoring web.cacerts config)
237 [+] marked option can be specified multiple times
239 init
241 create a new repository in the given directory:
242 hg init [-e CMD] [--remotecmd CMD] [DEST]
244 Initialize a new repository in the given directory. If the given direc‐
246 tory does not exist, it will be created.
247 If no directory is given, the current directory is used.
249 It is possible to specify an ssh:// URL as the destination. See hg
251 help urls for more information.
252 Returns 0 on success.
254 Options:
256 -e,--ssh <CMD>
258 specify ssh command to use
259 --remotecmd <CMD>
261 specify hg command to run on the remote side
262 --insecure
264 do not verify server certificate (ignoring web.cacerts config)
265 Remote repository management
267 incoming
268 show new changesets found in source:
269 hg incoming [-p] [-n] [-M] [-f] [-r REV]... [--bundle FILENAME] [SOURCE]
271 Show new changesets found in the specified path/URL or the default pull
273 location. These are the changesets that would have been pulled by hg
274 pull at the time you issued this command.
275 See pull for valid source format details.
277 With -B/--bookmarks, the result of bookmark comparison between local
279 and remote repositories is displayed. With -v/--verbose, status is also
280 displayed for each bookmark like below:
281 BM1 01234567890a added
283 BM2 1234567890ab advanced
284 BM3 234567890abc diverged
285 BM4 34567890abcd changed
286 The action taken locally when pulling depends on the status of each
288 bookmark:
289 added
291 pull will create it
293 advanced
295 pull will update it
297 diverged
299 pull will create a divergent bookmark
301 changed
303 result depends on remote changesets
305 From the point of view of pulling behavior, bookmark existing only in
307 the remote repository are treated as added, even if it is in fact lo‐
308 cally deleted.
309 For remote repository, using --bundle avoids downloading the changesets
311 twice if the incoming is followed by a pull.
312 Examples:
314 • show incoming changes with patches and full description:
316 hg incoming -vp
318 • show incoming changes excluding merges, store a bundle:
320 hg in -vpM --bundle incoming.hg
322 hg pull incoming.hg
323 • briefly list changes inside a bundle:
325 hg in changes.hg -T "{desc|firstline}\n"
327 Returns 0 if there are incoming changes, 1 otherwise.
329 Options:
331 -f, --force
333 run even if remote repository is unrelated
334 -n, --newest-first
336 show newest record first
337 --bundle <FILE>
339 file to store the bundles into
340 -r,--rev <REV[+]>
342 a remote changeset intended to be added
343 -B, --bookmarks
345 compare bookmarks
346 -b,--branch <BRANCH[+]>
348 a specific branch you would like to pull
349 -p, --patch
351 show patch
352 -g, --git
354 use git extended diff format
355 -l,--limit <NUM>
357 limit number of changes displayed
358 -M, --no-merges
360 do not show merges
361 --stat output diffstat-style summary of changes
363 -G, --graph
365 show the revision DAG
366 --style <STYLE>
368 display using template map file (DEPRECATED)
369 -T,--template <TEMPLATE>
371 display with template
372 -e,--ssh <CMD>
374 specify ssh command to use
375 --remotecmd <CMD>
377 specify hg command to run on the remote side
378 --insecure
380 do not verify server certificate (ignoring web.cacerts config)
381 -S, --subrepos
383 recurse into subrepositories
384 [+] marked option can be specified multiple times
386 aliases: in
388 outgoing
390 show changesets not found in the destination:
391 hg outgoing [-M] [-p] [-n] [-f] [-r REV]... [DEST]...
393 Show changesets not found in the specified destination repository or
395 the default push location. These are the changesets that would be
396 pushed if a push was requested.
397 See pull for details of valid destination formats.
399 With -B/--bookmarks, the result of bookmark comparison between local
401 and remote repositories is displayed. With -v/--verbose, status is also
402 displayed for each bookmark like below:
403 BM1 01234567890a added
405 BM2 deleted
406 BM3 234567890abc advanced
407 BM4 34567890abcd diverged
408 BM5 4567890abcde changed
409 The action taken when pushing depends on the status of each bookmark:
411 added
413 push with -B will create it
415 deleted
417 push with -B will delete it
419 advanced
421 push will update it
423 diverged
425 push with -B will update it
427 changed
429 push with -B will update it
431 From the point of view of pushing behavior, bookmarks existing only in
433 the remote repository are treated as deleted, even if it is in fact
434 added remotely.
435 Returns 0 if there are outgoing changes, 1 otherwise.
437 Options:
439 -f, --force
441 run even when the destination is unrelated
442 -r,--rev <REV[+]>
444 a changeset intended to be included in the destination
445 -n, --newest-first
447 show newest record first
448 -B, --bookmarks
450 compare bookmarks
451 -b,--branch <BRANCH[+]>
453 a specific branch you would like to push
454 -p, --patch
456 show patch
457 -g, --git
459 use git extended diff format
460 -l,--limit <NUM>
462 limit number of changes displayed
463 -M, --no-merges
465 do not show merges
466 --stat output diffstat-style summary of changes
468 -G, --graph
470 show the revision DAG
471 --style <STYLE>
473 display using template map file (DEPRECATED)
474 -T,--template <TEMPLATE>
476 display with template
477 -e,--ssh <CMD>
479 specify ssh command to use
480 --remotecmd <CMD>
482 specify hg command to run on the remote side
483 --insecure
485 do not verify server certificate (ignoring web.cacerts config)
486 -S, --subrepos
488 recurse into subrepositories
489 [+] marked option can be specified multiple times
491 aliases: out
493 paths
495 show aliases for remote repositories:
496 hg paths [NAME]
498 Show definition of symbolic path name NAME. If no name is given, show
500 definition of all available names.
501 Option -q/--quiet suppresses all output when searching for NAME and
503 shows only the path names when listing all definitions.
504 Path names are defined in the [paths] section of your configuration
506 file and in /etc/mercurial/hgrc. If run inside a repository, .hg/hgrc
507 is used, too.
508 The path names default and default-push have a special meaning. When
510 performing a push or pull operation, they are used as fallbacks if no
511 location is specified on the command-line. When default-push is set,
512 it will be used for push and default will be used for pull; otherwise
513 default is used as the fallback for both. When cloning a repository,
514 the clone source is written as default in .hg/hgrc.
515 Note default and default-push apply to all inbound (e.g. hg incoming
517 ) and outbound (e.g. hg outgoing, hg email and hg bundle) opera‐
518 tions.
519 See hg help urls for more information.
521 Template:
523 The following keywords are supported. See also hg help templates.
525 name String. Symbolic name of the path alias.
527 pushurl
529 String. URL for push operations.
530 url String. URL or directory path for the other operations.
532 Returns 0 on success.
534 Options:
536 -T,--template <TEMPLATE>
538 display with template
539 pull
541 pull changes from the specified source:
542 hg pull [-u] [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [SOURCE]...
544 Pull changes from a remote repository to a local one.
546 This finds all changes from the repository at the specified path or URL
548 and adds them to a local repository (the current one unless -R is spec‐
549 ified). By default, this does not update the copy of the project in the
550 working directory.
551 When cloning from servers that support it, Mercurial may fetch pre-gen‐
553 erated data. When this is done, hooks operating on incoming changesets
554 and changegroups may fire more than once, once for each pre-generated
555 bundle and as well as for any additional remaining data. See hg help -e
556 clonebundles for more.
557 Use hg incoming if you want to see what would have been added by a pull
559 at the time you issued this command. If you then decide to add those
560 changes to the repository, you should use hg pull -r X where X is the
561 last changeset listed by hg incoming.
562 If SOURCE is omitted, the 'default' path will be used. See hg help
564 urls for more information.
565 If multiple sources are specified, they will be pulled sequentially as
567 if the command was run multiple time. If --update is specify and the
568 command will stop at the first failed --update.
569 Specifying bookmark as . is equivalent to specifying the active book‐
571 mark's name.
572 Returns 0 on success, 1 if an update had unresolved files.
574 Options:
576 -u, --update
578 update to new branch head if new descendants were pulled
579 -f, --force
581 run even when remote repository is unrelated
582 --confirm
584 confirm pull before applying changes
585 -r,--rev <REV[+]>
587 a remote changeset intended to be added
588 -B,--bookmark <BOOKMARK[+]>
590 bookmark to pull
591 -b,--branch <BRANCH[+]>
593 a specific branch you would like to pull
594 -e,--ssh <CMD>
596 specify ssh command to use
597 --remotecmd <CMD>
599 specify hg command to run on the remote side
600 --insecure
602 do not verify server certificate (ignoring web.cacerts config)
603 [+] marked option can be specified multiple times
605 push
607 push changes to the specified destination:
608 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]...
610 Push changesets from the local repository to the specified destination.
612 This operation is symmetrical to pull: it is identical to a pull in the
614 destination repository from the current one.
615 By default, push will not allow creation of new heads at the destina‐
617 tion, since multiple heads would make it unclear which head to use. In
618 this situation, it is recommended to pull and merge before pushing.
619 Use --new-branch if you want to allow push to create a new named branch
621 that is not present at the destination. This allows you to only create
622 a new branch without forcing other changes.
623 Note Extra care should be taken with the -f/--force option, which
625 will push all new heads on all branches, an action which will
626 almost always cause confusion for collaborators.
627 If -r/--rev is used, the specified revision and all its ancestors will
629 be pushed to the remote repository.
630 If -B/--bookmark is used, the specified bookmarked revision, its ances‐
632 tors, and the bookmark will be pushed to the remote repository. Speci‐
633 fying . is equivalent to specifying the active bookmark's name. Use the
634 --all-bookmarks option for pushing all current bookmarks.
635 Please see hg help urls for important details about ssh:// URLs. If
637 DESTINATION is omitted, a default path will be used.
638 When passed multiple destinations, push will process them one after the
640 other, but stop should an error occur.
641 The --pushvars option sends strings to the server that become environ‐
643 ment variables prepended with HG_USERVAR_. For example, --pushvars EN‐
644 ABLE_FEATURE=true, provides the server side hooks with HG_USERVAR_EN‐
645 ABLE_FEATURE=true as part of their environment.
646 pushvars can provide for user-overridable hooks as well as set debug
648 levels. One example is having a hook that blocks commits containing
649 conflict markers, but enables the user to override the hook if the file
650 is using conflict markers for testing purposes or the file format has
651 strings that look like conflict markers.
652 By default, servers will ignore --pushvars. To enable it add the fol‐
654 lowing to your configuration file:
655 [push]
657 pushvars.server = true
658 Returns 0 if push was successful, 1 if nothing to push.
660 Options:
662 -f, --force
664 force push
665 -r,--rev <REV[+]>
667 a changeset intended to be included in the destination
668 -B,--bookmark <BOOKMARK[+]>
670 bookmark to push
671 --all-bookmarks
673 push all bookmarks (EXPERIMENTAL)
674 -b,--branch <BRANCH[+]>
676 a specific branch you would like to push
677 --new-branch
679 allow pushing a new branch
680 --pushvars <VALUE[+]>
682 variables that can be sent to server (ADVANCED)
683 --publish
685 push the changeset as public (EXPERIMENTAL)
686 -e,--ssh <CMD>
688 specify ssh command to use
689 --remotecmd <CMD>
691 specify hg command to run on the remote side
692 --insecure
694 do not verify server certificate (ignoring web.cacerts config)
695 [+] marked option can be specified multiple times
697 serve
699 start stand-alone webserver:
700 hg serve [OPTION]...
702 Start a local HTTP repository browser and pull server. You can use this
704 for ad-hoc sharing and browsing of repositories. It is recommended to
705 use a real web server to serve a repository for longer periods of time.
706 Please note that the server does not implement access control. This
708 means that, by default, anybody can read from the server and nobody can
709 write to it by default. Set the web.allow-push option to * to allow ev‐
710 erybody to push to the server. You should use a real web server if you
711 need to authenticate users.
712 By default, the server logs accesses to stdout and errors to stderr.
714 Use the -A/--accesslog and -E/--errorlog options to log to files.
715 To have the server choose a free port number to listen on, specify a
717 port number of 0; in this case, the server will print the port number
718 it uses.
719 Returns 0 on success.
721 Options:
723 -A,--accesslog <FILE>
725 name of access log file to write to
726 -d, --daemon
728 run server in background
729 --daemon-postexec <VALUE[+]>
731 used internally by daemon mode
732 -E,--errorlog <FILE>
734 name of error log file to write to
735 -p,--port <PORT>
737 port to listen on (default: 8000)
738 -a,--address <ADDR>
740 address to listen on (default: all interfaces)
741 --prefix <PREFIX>
743 prefix path to serve from (default: server root)
744 -n,--name <NAME>
746 name to show in web pages (default: working directory)
747 --web-conf <FILE>
749 name of the hgweb config file (see 'hg help hgweb')
750 --webdir-conf <FILE>
752 name of the hgweb config file (DEPRECATED)
753 --pid-file <FILE>
755 name of file to write process ID to
756 --stdio
758 for remote clients (ADVANCED)
759 --cmdserver <MODE>
761 for remote clients (ADVANCED)
762 -t,--templates <TEMPLATE>
764 web templates to use
765 --style <STYLE>
767 template style to use
768 -6, --ipv6
770 use IPv6 in addition to IPv4
771 --certificate <FILE>
773 SSL certificate file
774 --print-url
776 start and print only the URL
777 -S, --subrepos
779 recurse into subrepositories
780 [+] marked option can be specified multiple times
782 Change creation
784 commit
785 commit the specified files or all outstanding changes:
786 hg commit [OPTION]... [FILE]...
788 Commit changes to the given files into the repository. Unlike a cen‐
790 tralized SCM, this operation is a local operation. See hg push for a
791 way to actively distribute your changes.
792 If a list of files is omitted, all changes reported by hg status will
794 be committed.
795 If you are committing the result of a merge, do not provide any file‐
797 names or -I/-X filters.
798 If no commit message is specified, Mercurial starts your configured ed‐
800 itor where you can enter a message. In case your commit fails, you will
801 find a backup of your message in .hg/last-message.txt.
802 The --close-branch flag can be used to mark the current branch head
804 closed. When all heads of a branch are closed, the branch will be con‐
805 sidered closed and no longer listed.
806 The --amend flag can be used to amend the parent of the working direc‐
808 tory with a new commit that contains the changes in the parent in addi‐
809 tion to those currently reported by hg status, if there are any. The
810 old commit is stored in a backup bundle in .hg/strip-backup (see hg
811 help bundle and hg help unbundle on how to restore it).
812 Message, user and date are taken from the amended commit unless speci‐
814 fied. When a message isn't specified on the command line, the editor
815 will open with the message of the amended commit.
816 It is not possible to amend public changesets (see hg help phases) or
818 changesets that have children.
819 See hg help dates for a list of formats valid for -d/--date.
821 Returns 0 on success, 1 if nothing changed.
823 Examples:
825 • commit all files ending in .py:
827 hg commit --include "set:**.py"
829 • commit all non-binary files:
831 hg commit --exclude "set:binary()"
833 • amend the current commit and set the date to now:
835 hg commit --amend --date now
837 Options:
839 -A, --addremove
841 mark new/missing files as added/removed before committing
842 --close-branch
844 mark a branch head as closed
845 --amend
847 amend the parent of the working directory
848 -s, --secret
850 use the secret phase for committing
851 -e, --edit
853 invoke editor on commit messages
854 --force-close-branch
856 forcibly close branch from a non-head changeset (ADVANCED)
857 -i, --interactive
859 use interactive mode
860 -I,--include <PATTERN[+]>
862 include names matching the given patterns
863 -X,--exclude <PATTERN[+]>
865 exclude names matching the given patterns
866 -m,--message <TEXT>
868 use text as commit message
869 -l,--logfile <FILE>
871 read commit message from file
872 -d,--date <DATE>
874 record the specified date as commit date
875 -u,--user <USER>
877 record the specified user as committer
878 -S, --subrepos
880 recurse into subrepositories
881 [+] marked option can be specified multiple times
883 aliases: ci
885 Change manipulation
887 abort
888 abort an unfinished operation (EXPERIMENTAL):
889 hg abort
891 Aborts a multistep operation like graft, histedit, rebase, merge, and
893 unshelve if they are in an unfinished state.
894 use --dry-run/-n to dry run the command.
896 Options:
898 -n, --dry-run
900 do not perform actions, just print output
901 backout
903 reverse effect of earlier changeset:
904 hg backout [OPTION]... [-r] REV
906 Prepare a new changeset with the effect of REV undone in the current
908 working directory. If no conflicts were encountered, it will be commit‐
909 ted immediately.
910 If REV is the parent of the working directory, then this new changeset
912 is committed automatically (unless --no-commit is specified).
913 Note hg backout cannot be used to fix either an unwanted or incorrect
915 merge.
916 Examples:
918 • Reverse the effect of the parent of the working directory. This
920 backout will be committed immediately:
921 hg backout -r .
923 • Reverse the effect of previous bad revision 23:
925 hg backout -r 23
927 • Reverse the effect of previous bad revision 23 and leave changes un‐
929 committed:
930 hg backout -r 23 --no-commit
932 hg commit -m "Backout revision 23"
933 By default, the pending changeset will have one parent, maintaining a
935 linear history. With --merge, the pending changeset will instead have
936 two parents: the old parent of the working directory and a new child of
937 REV that simply undoes REV.
938 Before version 1.7, the behavior without --merge was equivalent to
940 specifying --merge followed by hg update --clean . to cancel the merge
941 and leave the child of REV as a head to be merged separately.
942 See hg help dates for a list of formats valid for -d/--date.
944 See hg help revert for a way to restore files to the state of another
946 revision.
947 Returns 0 on success, 1 if nothing to backout or there are unresolved
949 files.
950 Options:
952 --merge
954 merge with old dirstate parent after backout
955 --commit
957 commit if no conflicts were encountered (DEPRECATED)
958 --no-commit
960 do not commit
961 --parent <REV>
963 parent to choose when backing out merge (DEPRECATED)
964 -r,--rev <REV>
966 revision to backout
967 -e, --edit
969 invoke editor on commit messages
970 -t,--tool <TOOL>
972 specify merge tool
973 -I,--include <PATTERN[+]>
975 include names matching the given patterns
976 -X,--exclude <PATTERN[+]>
978 exclude names matching the given patterns
979 -m,--message <TEXT>
981 use text as commit message
982 -l,--logfile <FILE>
984 read commit message from file
985 -d,--date <DATE>
987 record the specified date as commit date
988 -u,--user <USER>
990 record the specified user as committer
991 [+] marked option can be specified multiple times
993 continue
995 resumes an interrupted operation (EXPERIMENTAL):
996 hg continue
998 Finishes a multistep operation like graft, histedit, rebase, merge, and
1000 unshelve if they are in an interrupted state.
1001 use --dry-run/-n to dry run the command.
1003 Options:
1005 -n, --dry-run
1007 do not perform actions, just print output
1008 graft
1010 copy changes from other branches onto the current branch:
1011 hg graft [OPTION]... [-r REV]... REV...
1013 This command uses Mercurial's merge logic to copy individual changes
1015 from other branches without merging branches in the history graph. This
1016 is sometimes known as 'backporting' or 'cherry-picking'. By default,
1017 graft will copy user, date, and description from the source changesets.
1018 Changesets that are ancestors of the current revision, that have al‐
1020 ready been grafted, or that are merges will be skipped.
1021 If --log is specified, log messages will have a comment appended of the
1023 form:
1024 (grafted from CHANGESETHASH)
1026 If --force is specified, revisions will be grafted even if they are al‐
1028 ready ancestors of, or have been grafted to, the destination. This is
1029 useful when the revisions have since been backed out.
1030 If a graft merge results in conflicts, the graft process is interrupted
1032 so that the current merge can be manually resolved. Once all conflicts
1033 are addressed, the graft process can be continued with the -c/--con‐
1034 tinue option.
1035 The -c/--continue option reapplies all the earlier options.
1037 The --base option exposes more of how graft internally uses merge with
1039 a custom base revision. --base can be used to specify another ancestor
1040 than the first and only parent.
1041 The command:
1043 hg graft -r 345 --base 234
1045 is thus pretty much the same as:
1047 hg diff --from 234 --to 345 | hg import
1049 but using merge to resolve conflicts and track moved files.
1051 The result of a merge can thus be backported as a single commit by
1053 specifying one of the merge parents as base, and thus effectively
1054 grafting the changes from the other side.
1055 It is also possible to collapse multiple changesets and clean up his‐
1057 tory by specifying another ancestor as base, much like rebase --col‐
1058 lapse --keep.
1059 The commit message can be tweaked after the fact using commit --amend .
1061 For using non-ancestors as the base to backout changes, see the backout
1063 command and the hidden --parent option.
1064 Examples:
1066 • copy a single change to the stable branch and edit its description:
1068 hg update stable
1070 hg graft --edit 9393
1071 • graft a range of changesets with one exception, updating dates:
1073 hg graft -D "2085::2093 and not 2091"
1075 • continue a graft after resolving conflicts:
1077 hg graft -c
1079 • show the source of a grafted changeset:
1081 hg log --debug -r .
1083 • show revisions sorted by date:
1085 hg log -r "sort(all(), date)"
1087 • backport the result of a merge as a single commit:
1089 hg graft -r 123 --base 123^
1091 • land a feature branch as one changeset:
1093 hg up -cr default
1095 hg graft -r featureX --base "ancestor('featureX', 'default')"
1096 See hg help revisions for more about specifying revisions.
1098 Returns 0 on successful completion, 1 if there are unresolved files.
1100 Options:
1102 -r,--rev <REV[+]>
1104 revisions to graft
1105 --base <REV>
1107 base revision when doing the graft merge (ADVANCED)
1108 -c, --continue
1110 resume interrupted graft
1111 --stop stop interrupted graft
1113 --abort
1115 abort interrupted graft
1116 -e, --edit
1118 invoke editor on commit messages
1119 --log append graft info to log message
1121 --no-commit
1123 don't commit, just apply the changes in working directory
1124 -f, --force
1126 force graft
1127 -D, --currentdate
1129 record the current date as commit date
1130 -U, --currentuser
1132 record the current user as committer
1133 -d,--date <DATE>
1135 record the specified date as commit date
1136 -u,--user <USER>
1138 record the specified user as committer
1139 -t,--tool <TOOL>
1141 specify merge tool
1142 -n, --dry-run
1144 do not perform actions, just print output
1145 [+] marked option can be specified multiple times
1147 merge
1149 merge another revision into working directory:
1150 hg merge [-P] [[-r] REV]
1152 The current working directory is updated with all changes made in the
1154 requested revision since the last common predecessor revision.
1155 Files that changed between either parent are marked as changed for the
1157 next commit and a commit must be performed before any further updates
1158 to the repository are allowed. The next commit will have two parents.
1159 --tool can be used to specify the merge tool used for file merges. It
1161 overrides the HGMERGE environment variable and your configuration
1162 files. See hg help merge-tools for options.
1163 If no revision is specified, the working directory's parent is a head
1165 revision, and the current branch contains exactly one other head, the
1166 other head is merged with by default. Otherwise, an explicit revision
1167 with which to merge must be provided.
1168 See hg help resolve for information on handling file conflicts.
1170 To undo an uncommitted merge, use hg merge --abort which will check out
1172 a clean copy of the original merge parent, losing all changes.
1173 Returns 0 on success, 1 if there are unresolved files.
1175 Options:
1177 -f, --force
1179 force a merge including outstanding changes (DEPRECATED)
1180 -r,--rev <REV>
1182 revision to merge
1183 -P, --preview
1185 review revisions to merge (no merge is performed)
1186 --abort
1188 abort the ongoing merge
1189 -t,--tool <TOOL>
1191 specify merge tool
1192 Change organization
1194 bookmarks
1195 create a new bookmark or list existing bookmarks:
1196 hg bookmarks [OPTIONS]... [NAME]...
1198 Bookmarks are labels on changesets to help track lines of development.
1200 Bookmarks are unversioned and can be moved, renamed and deleted.
1201 Deleting or moving a bookmark has no effect on the associated change‐
1202 sets.
1203 Creating or updating to a bookmark causes it to be marked as 'active'.
1205 The active bookmark is indicated with a '*'. When a commit is made,
1206 the active bookmark will advance to the new commit. A plain hg update
1207 will also advance an active bookmark, if possible. Updating away from
1208 a bookmark will cause it to be deactivated.
1209 Bookmarks can be pushed and pulled between repositories (see hg help
1211 push and hg help pull). If a shared bookmark has diverged, a new 'di‐
1212 vergent bookmark' of the form 'name@path' will be created. Using hg
1213 merge will resolve the divergence.
1214 Specifying bookmark as '.' to -m/-d/-l options is equivalent to speci‐
1216 fying the active bookmark's name.
1217 A bookmark named '@' has the special property that hg clone will check
1219 it out by default if it exists.
1220 Template:
1222 The following keywords are supported in addition to the common template
1224 keywords and functions such as {bookmark}. See also hg help templates.
1225 active Boolean. True if the bookmark is active.
1227 Examples:
1229 • create an active bookmark for a new line of development:
1231 hg book new-feature
1233 • create an inactive bookmark as a place marker:
1235 hg book -i reviewed
1237 • create an inactive bookmark on another changeset:
1239 hg book -r .^ tested
1241 • rename bookmark turkey to dinner:
1243 hg book -m turkey dinner
1245 • move the '@' bookmark from another branch:
1247 hg book -f @
1249 • print only the active bookmark name:
1251 hg book -ql .
1253 Options:
1255 -f, --force
1257 force
1258 -r,--rev <REV>
1260 revision for bookmark action
1261 -d, --delete
1263 delete a given bookmark
1264 -m,--rename <OLD>
1266 rename a given bookmark
1267 -i, --inactive
1269 mark a bookmark inactive
1270 -l, --list
1272 list existing bookmarks
1273 -T,--template <TEMPLATE>
1275 display with template
1276 aliases: bookmark
1278 branch
1280 set or show the current branch name:
1281 hg branch [-fC] [NAME]
1283 Note Branch names are permanent and global. Use hg bookmark to create
1285 a light-weight bookmark instead. See hg help glossary for more
1286 information about named branches and bookmarks.
1287 With no argument, show the current branch name. With one argument, set
1289 the working directory branch name (the branch will not exist in the
1290 repository until the next commit). Standard practice recommends that
1291 primary development take place on the 'default' branch.
1292 Unless -f/--force is specified, branch will not let you set a branch
1294 name that already exists.
1295 Use -C/--clean to reset the working directory branch to that of the
1297 parent of the working directory, negating a previous branch change.
1298 Use the command hg update to switch to an existing branch. Use hg com‐
1300 mit --close-branch to mark this branch head as closed. When all heads
1301 of a branch are closed, the branch will be considered closed.
1302 Returns 0 on success.
1304 Options:
1306 -f, --force
1308 set branch name even if it shadows an existing branch
1309 -C, --clean
1311 reset branch name to parent branch name
1312 -r,--rev <VALUE[+]>
1314 change branches of the given revs (EXPERIMENTAL)
1315 [+] marked option can be specified multiple times
1317 branches
1319 list repository named branches:
1320 hg branches [-c]
1322 List the repository's named branches, indicating which ones are inac‐
1324 tive. If -c/--closed is specified, also list branches which have been
1325 marked closed (see hg commit --close-branch).
1326 Use the command hg update to switch to an existing branch.
1328 Template:
1330 The following keywords are supported in addition to the common template
1332 keywords and functions such as {branch}. See also hg help templates.
1333 active Boolean. True if the branch is active.
1335 closed Boolean. True if the branch is closed.
1337 current
1339 Boolean. True if it is the current branch.
1340 Returns 0.
1342 Options:
1344 -a, --active
1346 show only branches that have unmerged heads (DEPRECATED)
1347 -c, --closed
1349 show normal and closed branches
1350 -r,--rev <VALUE[+]>
1352 show branch name(s) of the given rev
1353 -T,--template <TEMPLATE>
1355 display with template
1356 [+] marked option can be specified multiple times
1358 phase
1360 set or show the current phase name:
1361 hg phase [-p|-d|-s] [-f] [-r] [REV...]
1363 With no argument, show the phase name of the current revision(s).
1365 With one of -p/--public, -d/--draft or -s/--secret, change the phase
1367 value of the specified revisions.
1368 Unless -f/--force is specified, hg phase won't move changesets from a
1370 lower phase to a higher phase. Phases are ordered as follows:
1371 public < draft < secret
1373 Returns 0 on success, 1 if some phases could not be changed.
1375 (For more information about the phases concept, see hg help phases.)
1377 Options:
1379 -p, --public
1381 set changeset phase to public
1382 -d, --draft
1384 set changeset phase to draft
1385 -s, --secret
1387 set changeset phase to secret
1388 -f, --force
1390 allow to move boundary backward
1391 -r,--rev <REV[+]>
1393 target revision
1394 [+] marked option can be specified multiple times
1396 tag
1398 add one or more tags for the current or given revision:
1399 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
1401 Name a particular revision using <name>.
1403 Tags are used to name particular revisions of the repository and are
1405 very useful to compare different revisions, to go back to significant
1406 earlier versions or to mark branch points as releases, etc. Changing an
1407 existing tag is normally disallowed; use -f/--force to override.
1408 If no revision is given, the parent of the working directory is used.
1410 To facilitate version control, distribution, and merging of tags, they
1412 are stored as a file named ".hgtags" which is managed similarly to
1413 other project files and can be hand-edited if necessary. This also
1414 means that tagging creates a new commit. The file ".hg/localtags" is
1415 used for local tags (not shared among repositories).
1416 Tag commits are usually made at the head of a branch. If the parent of
1418 the working directory is not a branch head, hg tag aborts; use
1419 -f/--force to force the tag commit to be based on a non-head changeset.
1420 See hg help dates for a list of formats valid for -d/--date.
1422 Since tag names have priority over branch names during revision lookup,
1424 using an existing branch name as a tag name is discouraged.
1425 Returns 0 on success.
1427 Options:
1429 -f, --force
1431 force tag
1432 -l, --local
1434 make the tag local
1435 -r,--rev <REV>
1437 revision to tag
1438 --remove
1440 remove a tag
1441 -e, --edit
1443 invoke editor on commit messages
1444 -m,--message <TEXT>
1446 use text as commit message
1447 -d,--date <DATE>
1449 record the specified date as commit date
1450 -u,--user <USER>
1452 record the specified user as committer
1453 tags
1455 list repository tags:
1456 hg tags
1458 This lists both regular and local tags. When the -v/--verbose switch is
1460 used, a third column "local" is printed for local tags. When the
1461 -q/--quiet switch is used, only the tag name is printed.
1462 Template:
1464 The following keywords are supported in addition to the common template
1466 keywords and functions such as {tag}. See also hg help templates.
1467 type String. local for local tags.
1469 Returns 0 on success.
1471 Options:
1473 -T,--template <TEMPLATE>
1475 display with template
1476 File content management
1478 annotate
1479 show changeset information by line for each file:
1480 hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...
1482 List changes in files, showing the revision id responsible for each
1484 line.
1485 This command is useful for discovering when a change was made and by
1487 whom.
1488 If you include --file, --user, or --date, the revision number is sup‐
1490 pressed unless you also include --number.
1491 Without the -a/--text option, annotate will avoid processing files it
1493 detects as binary. With -a, annotate will annotate the file anyway, al‐
1494 though the results will probably be neither useful nor desirable.
1495 Template:
1497 The following keywords are supported in addition to the common template
1499 keywords and functions. See also hg help templates.
1500 lines List of lines with annotation data.
1502 path String. Repository-absolute path of the specified file.
1504 And each entry of {lines} provides the following sub-keywords in addi‐
1506 tion to {date}, {node}, {rev}, {user}, etc.
1507 line String. Line content.
1509 lineno Integer. Line number at that revision.
1511 path String. Repository-absolute path of the file at that revision.
1513 See hg help templates.operators for the list expansion syntax.
1515 Returns 0 on success.
1517 Options:
1519 -r,--rev <REV>
1521 annotate the specified revision
1522 --follow
1524 follow copies/renames and list the filename (DEPRECATED)
1525 --no-follow
1527 don't follow copies and renames
1528 -a, --text
1530 treat all files as text
1531 -u, --user
1533 list the author (long with -v)
1534 -f, --file
1536 list the filename
1537 -d, --date
1539 list the date (short with -q)
1540 -n, --number
1542 list the revision number (default)
1543 -c, --changeset
1545 list the changeset
1546 -l, --line-number
1548 show line number at the first appearance
1549 --skip <REV[+]>
1551 revset to not display (EXPERIMENTAL)
1552 -w, --ignore-all-space
1554 ignore white space when comparing lines
1555 -b, --ignore-space-change
1557 ignore changes in the amount of white space
1558 -B, --ignore-blank-lines
1560 ignore changes whose lines are all blank
1561 -Z, --ignore-space-at-eol
1563 ignore changes in whitespace at EOL
1564 -I,--include <PATTERN[+]>
1566 include names matching the given patterns
1567 -X,--exclude <PATTERN[+]>
1569 exclude names matching the given patterns
1570 -T,--template <TEMPLATE>
1572 display with template
1573 [+] marked option can be specified multiple times
1575 aliases: blame
1577 cat
1579 output the current or given revision of files:
1580 hg cat [OPTION]... FILE...
1582 Print the specified files as they were at the given revision. If no re‐
1584 vision is given, the parent of the working directory is used.
1585 Output may be to a file, in which case the name of the file is given
1587 using a template string. See hg help templates. In addition to the com‐
1588 mon template keywords, the following formatting rules are supported:
1589 %%
1591 literal "%" character
1593 %s
1595 basename of file being printed
1597 %d
1599 dirname of file being printed, or '.' if in repository root
1601 %p
1603 root-relative path name of file being printed
1605 %H
1607 changeset hash (40 hexadecimal digits)
1609 %R
1611 changeset revision number
1613 %h
1615 short-form changeset hash (12 hexadecimal digits)
1617 %r
1619 zero-padded changeset revision number
1621 %b
1623 basename of the exporting repository
1625 \
1627 literal "" character
1629 Template:
1631 The following keywords are supported in addition to the common template
1633 keywords and functions. See also hg help templates.
1634 data String. File content.
1636 path String. Repository-absolute path of the file.
1638 Returns 0 on success.
1640 Options:
1642 -o,--output <FORMAT>
1644 print output to file with formatted name
1645 -r,--rev <REV>
1647 print the given revision
1648 --decode
1650 apply any matching decode filter
1651 -I,--include <PATTERN[+]>
1653 include names matching the given patterns
1654 -X,--exclude <PATTERN[+]>
1656 exclude names matching the given patterns
1657 -T,--template <TEMPLATE>
1659 display with template
1660 [+] marked option can be specified multiple times
1662 copy
1664 mark files as copied for the next commit:
1665 hg copy [OPTION]... (SOURCE... DEST | --forget DEST...)
1667 Mark dest as having copies of source files. If dest is a directory,
1669 copies are put in that directory. If dest is a file, the source must be
1670 a single file.
1671 By default, this command copies the contents of files as they exist in
1673 the working directory. If invoked with -A/--after, the operation is
1674 recorded, but no copying is performed.
1675 To undo marking a destination file as copied, use --forget. With that
1677 option, all given (positional) arguments are unmarked as copies. The
1678 destination file(s) will be left in place (still tracked). Note that hg
1679 copy --forget behaves the same way as hg rename --forget.
1680 This command takes effect with the next commit by default.
1682 Returns 0 on success, 1 if errors are encountered.
1684 Options:
1686 --forget
1688 unmark a destination file as copied
1689 -A, --after
1691 record a copy that has already occurred
1692 --at-rev <REV>
1694 (un)mark copies in the given revision (EXPERIMENTAL)
1695 -f, --force
1697 forcibly copy over an existing managed file
1698 -I,--include <PATTERN[+]>
1700 include names matching the given patterns
1701 -X,--exclude <PATTERN[+]>
1703 exclude names matching the given patterns
1704 -n, --dry-run
1706 do not perform actions, just print output
1707 [+] marked option can be specified multiple times
1709 aliases: cp
1711 diff
1713 diff repository (or selected files):
1714 hg diff [OPTION]... ([-c REV] | [--from REV1] [--to REV2]) [FILE]...
1716 Show differences between revisions for the specified files.
1718 Differences between files are shown using the unified diff format.
1720 Note hg diff may generate unexpected results for merges, as it will
1722 default to comparing against the working directory's first par‐
1723 ent changeset if no revisions are specified. To diff against
1724 the conflict regions, you can use --config diff.merge=yes.
1725 By default, the working directory files are compared to its first par‐
1727 ent. To see the differences from another revision, use --from. To see
1728 the difference to another revision, use --to. For example, hg diff
1729 --from .^ will show the differences from the working copy's grandparent
1730 to the working copy, hg diff --to . will show the diff from the working
1731 copy to its parent (i.e. the reverse of the default), and hg diff
1732 --from 1.0 --to 1.2 will show the diff between those two revisions.
1733 Alternatively you can specify -c/--change with a revision to see the
1735 changes in that changeset relative to its first parent (i.e. hg diff -c
1736 42 is equivalent to hg diff --from 42^ --to 42)
1737 Without the -a/--text option, diff will avoid generating diffs of files
1739 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1740 bly with undesirable results.
1741 Use the -g/--git option to generate diffs in the git extended diff for‐
1743 mat. For more information, read hg help diffs.
1744 Examples:
1746 • compare a file in the current working directory to its parent:
1748 hg diff foo.c
1750 • compare two historical versions of a directory, with rename info:
1752 hg diff --git --from 1.0 --to 1.2 lib/
1754 • get change stats relative to the last change on some date:
1756 hg diff --stat --from "date('may 2')"
1758 • diff all newly-added files that contain a keyword:
1760 hg diff "set:added() and grep(GNU)"
1762 • compare a revision and its parents:
1764 hg diff -c 9353 # compare against first parent
1766 hg diff --from 9353^ --to 9353 # same using revset syntax
1767 hg diff --from 9353^2 --to 9353 # compare against the second parent
1768 Returns 0 on success.
1770 Options:
1772 -r,--rev <REV[+]>
1774 revision (DEPRECATED)
1775 --from <REV1>
1777 revision to diff from
1778 --to <REV2>
1780 revision to diff to
1781 -c,--change <REV>
1783 change made by revision
1784 -a, --text
1786 treat all files as text
1787 -g, --git
1789 use git extended diff format (DEFAULT: diff.git)
1790 --binary
1792 generate binary diffs in git mode (default)
1793 --nodates
1795 omit dates from diff headers
1796 --noprefix
1798 omit a/ and b/ prefixes from filenames
1799 -p, --show-function
1801 show which function each change is in (DEFAULT: diff.showfunc)
1802 --reverse
1804 produce a diff that undoes the changes
1805 -w, --ignore-all-space
1807 ignore white space when comparing lines
1808 -b, --ignore-space-change
1810 ignore changes in the amount of white space
1811 -B, --ignore-blank-lines
1813 ignore changes whose lines are all blank
1814 -Z, --ignore-space-at-eol
1816 ignore changes in whitespace at EOL
1817 -U,--unified <NUM>
1819 number of lines of context to show
1820 --stat output diffstat-style summary of changes
1822 --root <DIR>
1824 produce diffs relative to subdirectory
1825 -I,--include <PATTERN[+]>
1827 include names matching the given patterns
1828 -X,--exclude <PATTERN[+]>
1830 exclude names matching the given patterns
1831 -S, --subrepos
1833 recurse into subrepositories
1834 [+] marked option can be specified multiple times
1836 grep
1838 search for a pattern in specified files:
1839 hg grep [--diff] [OPTION]... PATTERN [FILE]...
1841 Search the working directory or revision history for a regular expres‐
1843 sion in the specified files for the entire repository.
1844 By default, grep searches the repository files in the working directory
1846 and prints the files where it finds a match. To specify historical re‐
1847 visions instead of the working directory, use the --rev flag.
1848 To search instead historical revision differences that contains a
1850 change in match status ("-" for a match that becomes a non-match, or
1851 "+" for a non-match that becomes a match), use the --diff flag.
1852 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1854 If no FILEs are specified and the --rev flag isn't supplied, all files
1856 in the working directory are searched. When using the --rev flag and
1857 specifying FILEs, use the --follow argument to also follow the speci‐
1858 fied FILEs across renames and copies.
1859 Template:
1861 The following keywords are supported in addition to the common template
1863 keywords and functions. See also hg help templates.
1864 change String. Character denoting insertion + or removal -. Available
1866 if --diff is specified.
1867 lineno Integer. Line number of the match.
1869 path String. Repository-absolute path of the file.
1871 texts List of text chunks.
1873 And each entry of {texts} provides the following sub-keywords.
1875 matched
1877 Boolean. True if the chunk matches the specified pattern.
1878 text String. Chunk content.
1880 See hg help templates.operators for the list expansion syntax.
1882 Returns 0 if a match is found, 1 otherwise.
1884 Options:
1886 -0, --print0
1888 end fields with NUL
1889 --all an alias to --diff (DEPRECATED)
1891 --diff search revision differences for when the pattern was added or
1893 removed
1894 -a, --text
1896 treat all files as text
1897 -f, --follow
1899 follow changeset history, or file history across copies and re‐
1900 names
1901 -i, --ignore-case
1903 ignore case when matching
1904 -l, --files-with-matches
1906 print only filenames and revisions that match
1907 -n, --line-number
1909 print matching line numbers
1910 -r,--rev <REV[+]>
1912 search files changed within revision range
1913 --all-files
1915 include all files in the changeset while grepping (DEPRECATED)
1916 -u, --user
1918 list the author (long with -v)
1919 -d, --date
1921 list the date (short with -q)
1922 -T,--template <TEMPLATE>
1924 display with template
1925 -I,--include <PATTERN[+]>
1927 include names matching the given patterns
1928 -X,--exclude <PATTERN[+]>
1930 exclude names matching the given patterns
1931 [+] marked option can be specified multiple times
1933 Change navigation
1935 bisect
1936 subdivision search of changesets:
1937 hg bisect [-gbsr] [-U] [-c CMD] [REV]
1939 This command helps to find changesets which introduce problems. To use,
1941 mark the earliest changeset you know exhibits the problem as bad, then
1942 mark the latest changeset which is free from the problem as good. Bi‐
1943 sect will update your working directory to a revision for testing (un‐
1944 less the -U/--noupdate option is specified). Once you have performed
1945 tests, mark the working directory as good or bad, and bisect will ei‐
1946 ther update to another candidate changeset or announce that it has
1947 found the bad revision.
1948 As a shortcut, you can also use the revision argument to mark a revi‐
1950 sion as good or bad without checking it out first.
1951 If you supply a command, it will be used for automatic bisection. The
1953 environment variable HG_NODE will contain the ID of the changeset being
1954 tested. The exit status of the command will be used to mark revisions
1955 as good or bad: status 0 means good, 125 means to skip the revision,
1956 127 (command not found) will abort the bisection, and any other
1957 non-zero exit status means the revision is bad.
1958 Some examples:
1960 • start a bisection with known bad revision 34, and good revision 12:
1962 hg bisect --bad 34
1964 hg bisect --good 12
1965 • advance the current bisection by marking current revision as good or
1967 bad:
1968 hg bisect --good
1970 hg bisect --bad
1971 • mark the current revision, or a known revision, to be skipped (e.g.
1973 if that revision is not usable because of another issue):
1974 hg bisect --skip
1976 hg bisect --skip 23
1977 • skip all revisions that do not touch directories foo or bar:
1979 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
1981 • forget the current bisection:
1983 hg bisect --reset
1985 • use 'make && make tests' to automatically find the first broken revi‐
1987 sion:
1988 hg bisect --reset
1990 hg bisect --bad 34
1991 hg bisect --good 12
1992 hg bisect --command "make && make tests"
1993 • see all changesets whose states are already known in the current bi‐
1995 section:
1996 hg log -r "bisect(pruned)"
1998 • see the changeset currently being bisected (especially useful if run‐
2000 ning with -U/--noupdate):
2001 hg log -r "bisect(current)"
2003 • see all changesets that took part in the current bisection:
2005 hg log -r "bisect(range)"
2007 • you can even get a nice graph:
2009 hg log --graph -r "bisect(range)"
2011 See hg help revisions.bisect for more about the bisect() predicate.
2013 Returns 0 on success.
2015 Options:
2017 -r, --reset
2019 reset bisect state
2020 -g, --good
2022 mark changeset good
2023 -b, --bad
2025 mark changeset bad
2026 -s, --skip
2028 skip testing changeset
2029 -e, --extend
2031 extend the bisect range
2032 -c,--command <CMD>
2034 use command to check changeset state
2035 -U, --noupdate
2037 do not update to target
2038 heads
2040 show branch heads:
2041 hg heads [-ct] [-r STARTREV] [REV]...
2043 With no arguments, show all open branch heads in the repository.
2045 Branch heads are changesets that have no descendants on the same
2046 branch. They are where development generally takes place and are the
2047 usual targets for update and merge operations.
2048 If one or more REVs are given, only open branch heads on the branches
2050 associated with the specified changesets are shown. This means that you
2051 can use hg heads . to see the heads on the currently checked-out
2052 branch.
2053 If -c/--closed is specified, also show branch heads marked closed (see
2055 hg commit --close-branch).
2056 If STARTREV is specified, only those heads that are descendants of
2058 STARTREV will be displayed.
2059 If -t/--topo is specified, named branch mechanics will be ignored and
2061 only topological heads (changesets with no children) will be shown.
2062 Returns 0 if matching heads are found, 1 if not.
2064 Options:
2066 -r,--rev <STARTREV>
2068 show only heads which are descendants of STARTREV
2069 -t, --topo
2071 show topological heads only
2072 -a, --active
2074 show active branchheads only (DEPRECATED)
2075 -c, --closed
2077 show normal and closed branch heads
2078 --style <STYLE>
2080 display using template map file (DEPRECATED)
2081 -T,--template <TEMPLATE>
2083 display with template
2084 identify
2086 identify the working directory or specified revision:
2087 hg identify [-nibtB] [-r REV] [SOURCE]
2089 Print a summary identifying the repository state at REV using one or
2091 two parent hash identifiers, followed by a "+" if the working directory
2092 has uncommitted changes, the branch name (if not default), a list of
2093 tags, and a list of bookmarks.
2094 When REV is not given, print a summary of the current state of the
2096 repository including the working directory. Specify -r. to get informa‐
2097 tion of the working directory parent without scanning uncommitted
2098 changes.
2099 Specifying a path to a repository root or Mercurial bundle will cause
2101 lookup to operate on that repository/bundle.
2102 Template:
2104 The following keywords are supported in addition to the common template
2106 keywords and functions. See also hg help templates.
2107 dirty String. Character + denoting if the working directory has uncom‐
2109 mitted changes.
2110 id String. One or two nodes, optionally followed by +.
2112 parents
2114 List of strings. Parent nodes of the changeset.
2115 Examples:
2117 • generate a build identifier for the working directory:
2119 hg id --id > build-id.dat
2121 • find the revision corresponding to a tag:
2123 hg id -n -r 1.3
2125 • check the most recent revision of a remote repository:
2127 hg id -r tip https://www.mercurial-scm.org/repo/hg/
2129 See hg log for generating more information about specific revisions,
2131 including full hash identifiers.
2132 Returns 0 if successful.
2134 Options:
2136 -r,--rev <REV>
2138 identify the specified revision
2139 -n, --num
2141 show local revision number
2142 -i, --id
2144 show global revision id
2145 -b, --branch
2147 show branch
2148 -t, --tags
2150 show tags
2151 -B, --bookmarks
2153 show bookmarks
2154 -e,--ssh <CMD>
2156 specify ssh command to use
2157 --remotecmd <CMD>
2159 specify hg command to run on the remote side
2160 --insecure
2162 do not verify server certificate (ignoring web.cacerts config)
2163 -T,--template <TEMPLATE>
2165 display with template
2166 aliases: id
2168 log
2170 show revision history of entire repository or files:
2171 hg log [OPTION]... [FILE]
2173 Print the revision history of the specified files or the entire
2175 project.
2176 If no revision range is specified, the default is tip:0 unless --follow
2178 is set.
2179 File history is shown without following rename or copy history of
2181 files. Use -f/--follow with a filename to follow history across renames
2182 and copies. --follow without a filename will only show ancestors of the
2183 starting revisions. The starting revisions can be specified by
2184 -r/--rev, which default to the working directory parent.
2185 By default this command prints revision number and changeset id, tags,
2187 non-trivial parents, user, date and time, and a summary for each com‐
2188 mit. When the -v/--verbose switch is used, the list of changed files
2189 and full commit message are shown.
2190 With --graph the revisions are shown as an ASCII art DAG with the most
2192 recent changeset at the top. 'o' is a changeset, '@' is a working di‐
2193 rectory parent, '%' is a changeset involved in an unresolved merge con‐
2194 flict, '_' closes a branch, 'x' is obsolete, '*' is unstable, and '+'
2195 represents a fork where the changeset from the lines below is a parent
2196 of the 'o' merge on the same line. Paths in the DAG are represented
2197 with '|', '/' and so forth. ':' in place of a '|' indicates one or more
2198 revisions in a path are omitted.
2199 Use -L/--line-range FILE,M:N options to follow the history of lines
2201 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2202 fied line range will be shown. This option requires --follow; it can be
2203 specified multiple times. Currently, this option is not compatible with
2204 --graph. This option is experimental.
2205 Note hg log --patch may generate unexpected diff output for merge
2207 changesets, as it will only compare the merge changeset against
2208 its first parent. Also, only files different from BOTH parents
2209 will appear in files:.
2210 Note For performance reasons, hg log FILE may omit duplicate changes
2212 made on branches and will not show removals or mode changes. To
2213 see all such changes, use the --removed switch.
2214 Note The history resulting from -L/--line-range options depends on
2216 diff options; for instance if white-spaces are ignored, respec‐
2217 tive changes with only white-spaces in specified line range will
2218 not be listed.
2219 Some examples:
2221 • changesets with full descriptions and file lists:
2223 hg log -v
2225 • changesets ancestral to the working directory:
2227 hg log -f
2229 • last 10 commits on the current branch:
2231 hg log -l 10 -b .
2233 • changesets showing all modifications of a file, including removals:
2235 hg log --removed file.c
2237 • all changesets that touch a directory, with diffs, excluding merges:
2239 hg log -Mp lib/
2241 • all revision numbers that match a keyword:
2243 hg log -k bug --template "{rev}\n"
2245 • the full hash identifier of the working directory parent:
2247 hg log -r . --template "{node}\n"
2249 • list available log templates:
2251 hg log -T list
2253 • check if a given changeset is included in a tagged release:
2255 hg log -r "a21ccf and ancestor(1.9)"
2257 • find all changesets by some user in a date range:
2259 hg log -k alice -d "may 2008 to jul 2008"
2261 • summary of all changesets after the last tag:
2263 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2265 • changesets touching lines 13 to 23 for file.c:
2267 hg log -L file.c,13:23
2269 • changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2271 main.c with patch:
2272 hg log -L file.c,13:23 -L main.c,2:6 -p
2274 See hg help dates for a list of formats valid for -d/--date.
2276 See hg help revisions for more about specifying and ordering revisions.
2278 See hg help templates for more about pre-packaged styles and specifying
2280 custom templates. The default template used by the log command can be
2281 customized via the command-templates.log configuration setting.
2282 Returns 0 on success.
2284 Options:
2286 -f, --follow
2288 follow changeset history, or file history across copies and re‐
2289 names
2290 --follow-first
2292 only follow the first parent of merge changesets (DEPRECATED)
2293 -d,--date <DATE>
2295 show revisions matching date spec
2296 -C, --copies
2298 show copied files
2299 -k,--keyword <TEXT[+]>
2301 do case-insensitive search for a given text
2302 -r,--rev <REV[+]>
2304 revisions to select or follow from
2305 -L,--line-range <FILE,RANGE[+]>
2307 follow line range of specified file (EXPERIMENTAL)
2308 --removed
2310 include revisions where files were removed
2311 -m, --only-merges
2313 show only merges (DEPRECATED) (use -r "merge()" instead)
2314 -u,--user <USER[+]>
2316 revisions committed by user
2317 --only-branch <BRANCH[+]>
2319 show only changesets within the given named branch (DEPRECATED)
2320 -b,--branch <BRANCH[+]>
2322 show changesets within the given named branch
2323 -B,--bookmark <BOOKMARK[+]>
2325 show changesets within the given bookmark
2326 -P,--prune <REV[+]>
2328 do not display revision or any of its ancestors
2329 -p, --patch
2331 show patch
2332 -g, --git
2334 use git extended diff format
2335 -l,--limit <NUM>
2337 limit number of changes displayed
2338 -M, --no-merges
2340 do not show merges
2341 --stat output diffstat-style summary of changes
2343 -G, --graph
2345 show the revision DAG
2346 --style <STYLE>
2348 display using template map file (DEPRECATED)
2349 -T,--template <TEMPLATE>
2351 display with template
2352 -I,--include <PATTERN[+]>
2354 include names matching the given patterns
2355 -X,--exclude <PATTERN[+]>
2357 exclude names matching the given patterns
2358 [+] marked option can be specified multiple times
2360 aliases: history
2362 parents
2364 show the parents of the working directory or revision (DEPRECATED):
2365 hg parents [-r REV] [FILE]
2367 Print the working directory's parent revisions. If a revision is given
2369 via -r/--rev, the parent of that revision will be printed. If a file
2370 argument is given, the revision in which the file was last changed (be‐
2371 fore the working directory revision or the argument to --rev if given)
2372 is printed.
2373 This command is equivalent to:
2375 hg log -r "p1()+p2()" or
2377 hg log -r "p1(REV)+p2(REV)" or
2378 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2379 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2380 See hg summary and hg help revsets for related information.
2382 Returns 0 on success.
2384 Options:
2386 -r,--rev <REV>
2388 show parents of the specified revision
2389 --style <STYLE>
2391 display using template map file (DEPRECATED)
2392 -T,--template <TEMPLATE>
2394 display with template
2395 tip
2397 show the tip revision (DEPRECATED):
2398 hg tip [-p] [-g]
2400 The tip revision (usually just called the tip) is the changeset most
2402 recently added to the repository (and therefore the most recently
2403 changed head).
2404 If you have just made a commit, that commit will be the tip. If you
2406 have just pulled changes from another repository, the tip of that
2407 repository becomes the current tip. The "tip" tag is special and cannot
2408 be renamed or assigned to a different changeset.
2409 This command is deprecated, please use hg heads instead.
2411 Returns 0 on success.
2413 Options:
2415 -p, --patch
2417 show patch
2418 -g, --git
2420 use git extended diff format
2421 --style <STYLE>
2423 display using template map file (DEPRECATED)
2424 -T,--template <TEMPLATE>
2426 display with template
2427 Working directory management
2429 add
2430 add the specified files on the next commit:
2431 hg add [OPTION]... [FILE]...
2433 Schedule files to be version controlled and added to the repository.
2435 The files will be added to the repository at the next commit. To undo
2437 an add before that, see hg forget.
2438 If no names are given, add all files to the repository (except files
2440 matching .hgignore).
2441 Examples:
2443 • New (unknown) files are added automatically by hg add:
2445 $ ls
2447 foo.c
2448 $ hg status
2449 ? foo.c
2450 $ hg add
2451 adding foo.c
2452 $ hg status
2453 A foo.c
2454 • Specific files to be added can be specified:
2456 $ ls
2458 bar.c foo.c
2459 $ hg status
2460 ? bar.c
2461 ? foo.c
2462 $ hg add bar.c
2463 $ hg status
2464 A bar.c
2465 ? foo.c
2466 Returns 0 if all files are successfully added.
2468 Options:
2470 -I,--include <PATTERN[+]>
2472 include names matching the given patterns
2473 -X,--exclude <PATTERN[+]>
2475 exclude names matching the given patterns
2476 -S, --subrepos
2478 recurse into subrepositories
2479 -n, --dry-run
2481 do not perform actions, just print output
2482 [+] marked option can be specified multiple times
2484 addremove
2486 add all new files, delete all missing files:
2487 hg addremove [OPTION]... [FILE]...
2489 Add all new files and remove all missing files from the repository.
2491 Unless names are given, new files are ignored if they match any of the
2493 patterns in .hgignore. As with add, these changes take effect at the
2494 next commit.
2495 Use the -s/--similarity option to detect renamed files. This option
2497 takes a percentage between 0 (disabled) and 100 (files must be identi‐
2498 cal) as its parameter. With a parameter greater than 0, this compares
2499 every removed file with every added file and records those similar
2500 enough as renames. Detecting renamed files this way can be expensive.
2501 After using this option, hg status -C can be used to check which files
2502 were identified as moved or renamed. If not specified, -s/--similarity
2503 defaults to 100 and only renames of identical files are detected.
2504 Examples:
2506 • A number of files (bar.c and foo.c) are new, while foobar.c has
2508 been removed (without using hg remove) from the repository:
2509 $ ls
2511 bar.c foo.c
2512 $ hg status
2513 ! foobar.c
2514 ? bar.c
2515 ? foo.c
2516 $ hg addremove
2517 adding bar.c
2518 adding foo.c
2519 removing foobar.c
2520 $ hg status
2521 A bar.c
2522 A foo.c
2523 R foobar.c
2524 • A file foobar.c was moved to foo.c without using hg rename. Af‐
2526 terwards, it was edited slightly:
2527 $ ls
2529 foo.c
2530 $ hg status
2531 ! foobar.c
2532 ? foo.c
2533 $ hg addremove --similarity 90
2534 removing foobar.c
2535 adding foo.c
2536 recording removal of foobar.c as rename to foo.c (94% similar)
2537 $ hg status -C
2538 A foo.c
2539 foobar.c
2540 R foobar.c
2541 Returns 0 if all files are successfully added.
2543 Options:
2545 -s,--similarity <SIMILARITY>
2547 guess renamed files by similarity (0<=s<=100)
2548 -S, --subrepos
2550 recurse into subrepositories
2551 -I,--include <PATTERN[+]>
2553 include names matching the given patterns
2554 -X,--exclude <PATTERN[+]>
2556 exclude names matching the given patterns
2557 -n, --dry-run
2559 do not perform actions, just print output
2560 [+] marked option can be specified multiple times
2562 files
2564 list tracked files:
2565 hg files [OPTION]... [FILE]...
2567 Print files under Mercurial control in the working directory or speci‐
2569 fied revision for given files (excluding removed files). Files can be
2570 specified as filenames or filesets.
2571 If no files are given to match, this command prints the names of all
2573 files under Mercurial control.
2574 Template:
2576 The following keywords are supported in addition to the common template
2578 keywords and functions. See also hg help templates.
2579 flags String. Character denoting file's symlink and executable bits.
2581 path String. Repository-absolute path of the file.
2583 size Integer. Size of the file in bytes.
2585 Examples:
2587 • list all files under the current directory:
2589 hg files .
2591 • shows sizes and flags for current revision:
2593 hg files -vr .
2595 • list all files named README:
2597 hg files -I "**/README"
2599 • list all binary files:
2601 hg files "set:binary()"
2603 • find files containing a regular expression:
2605 hg files "set:grep('bob')"
2607 • search tracked file contents with xargs and grep:
2609 hg files -0 | xargs -0 grep foo
2611 See hg help patterns and hg help filesets for more information on spec‐
2613 ifying file patterns.
2614 Returns 0 if a match is found, 1 otherwise.
2616 Options:
2618 -r,--rev <REV>
2620 search the repository as it is in REV
2621 -0, --print0
2623 end filenames with NUL, for use with xargs
2624 -I,--include <PATTERN[+]>
2626 include names matching the given patterns
2627 -X,--exclude <PATTERN[+]>
2629 exclude names matching the given patterns
2630 -T,--template <TEMPLATE>
2632 display with template
2633 -S, --subrepos
2635 recurse into subrepositories
2636 [+] marked option can be specified multiple times
2638 forget
2640 forget the specified files on the next commit:
2641 hg forget [OPTION]... FILE...
2643 Mark the specified files so they will no longer be tracked after the
2645 next commit.
2646 This only removes files from the current branch, not from the entire
2648 project history, and it does not delete them from the working direc‐
2649 tory.
2650 To delete the file from the working directory, see hg remove.
2652 To undo a forget before the next commit, see hg add.
2654 Examples:
2656 • forget newly-added binary files:
2658 hg forget "set:added() and binary()"
2660 • forget files that would be excluded by .hgignore:
2662 hg forget "set:hgignore()"
2664 Returns 0 on success.
2666 Options:
2668 -i, --interactive
2670 use interactive mode
2671 -I,--include <PATTERN[+]>
2673 include names matching the given patterns
2674 -X,--exclude <PATTERN[+]>
2676 exclude names matching the given patterns
2677 -n, --dry-run
2679 do not perform actions, just print output
2680 [+] marked option can be specified multiple times
2682 locate
2684 locate files matching specific patterns (DEPRECATED):
2685 hg locate [OPTION]... [PATTERN]...
2687 Print files under Mercurial control in the working directory whose
2689 names match the given patterns.
2690 By default, this command searches all directories in the working direc‐
2692 tory. To search just the current directory and its subdirectories, use
2693 "--include .".
2694 If no patterns are given to match, this command prints the names of all
2696 files under Mercurial control in the working directory.
2697 If you want to feed the output of this command into the "xargs" com‐
2699 mand, use the -0 option to both this command and "xargs". This will
2700 avoid the problem of "xargs" treating single filenames that contain
2701 whitespace as multiple filenames.
2702 See hg help files for a more versatile command.
2704 Returns 0 if a match is found, 1 otherwise.
2706 Options:
2708 -r,--rev <REV>
2710 search the repository as it is in REV
2711 -0, --print0
2713 end filenames with NUL, for use with xargs
2714 -f, --fullpath
2716 print complete paths from the filesystem root
2717 -I,--include <PATTERN[+]>
2719 include names matching the given patterns
2720 -X,--exclude <PATTERN[+]>
2722 exclude names matching the given patterns
2723 [+] marked option can be specified multiple times
2725 purge
2727 removes files not tracked by Mercurial:
2728 hg purge [OPTION]... [DIR]...
2730 Delete files not known to Mercurial. This is useful to test local and
2732 uncommitted changes in an otherwise-clean source tree.
2733 This means that purge will delete the following by default:
2735 • Unknown files: files marked with "?" by hg status
2737 • Empty directories: in fact Mercurial ignores directories unless they
2739 contain files under source control management
2740 But it will leave untouched:
2742 • Modified and unmodified tracked files
2744 • Ignored files (unless -i or --all is specified)
2746 • New files added to the repository (with hg add)
2748 The --files and --dirs options can be used to direct purge to delete
2750 only files, only directories, or both. If neither option is given, both
2751 will be deleted.
2752 If directories are given on the command line, only files in these di‐
2754 rectories are considered.
2755 Be careful with purge, as you could irreversibly delete some files you
2757 forgot to add to the repository. If you only want to print the list of
2758 files that this program would delete, use the --print option.
2759 Options:
2761 -a, --abort-on-err
2763 abort if an error occurs
2764 --all purge ignored files too
2766 -i, --ignored
2768 purge only ignored files
2769 --dirs purge empty directories
2771 --files
2773 purge files
2774 -p, --print
2776 print filenames instead of deleting them
2777 -0, --print0
2779 end filenames with NUL, for use with xargs (implies -p/--print)
2780 --confirm
2782 ask before permanently deleting files
2783 -I,--include <PATTERN[+]>
2785 include names matching the given patterns
2786 -X,--exclude <PATTERN[+]>
2788 exclude names matching the given patterns
2789 [+] marked option can be specified multiple times
2791 aliases: clean
2793 remove
2795 remove the specified files on the next commit:
2796 hg remove [OPTION]... FILE...
2798 Schedule the indicated files for removal from the current branch.
2800 This command schedules the files to be removed at the next commit. To
2802 undo a remove before that, see hg revert. To undo added files, see hg
2803 forget.
2804 -A/--after can be used to remove only files that have already been
2806 deleted, -f/--force can be used to force deletion, and -Af can be used
2807 to remove files from the next revision without deleting them from the
2808 working directory.
2809 The following table details the behavior of remove for different file
2811 states (columns) and option combinations (rows). The file states are
2812 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2813 status). The actions are Warn, Remove (from branch) and Delete (from
2814 disk):
2815 ┌──────────┬───┬────┬────┬───┐
2817 │opt/state │ A │ C │ M │ ! │
2818 ├──────────┼───┼────┼────┼───┤
2819 │none │ W │ RD │ W │ R │
2820 ├──────────┼───┼────┼────┼───┤
2821 │-f │ R │ RD │ RD │ R │
2822 ├──────────┼───┼────┼────┼───┤
2823 │-A │ W │ W │ W │ R │
2824 ├──────────┼───┼────┼────┼───┤
2825 │-Af │ R │ R │ R │ R │
2826 └──────────┴───┴────┴────┴───┘
2827 Note hg remove never deletes files in Added [A] state from the work‐
2829 ing directory, not even if --force is specified.
2830 Returns 0 on success, 1 if any warnings encountered.
2832 Options:
2834 -A, --after
2836 record delete for missing files
2837 -f, --force
2839 forget added files, delete modified files
2840 -S, --subrepos
2842 recurse into subrepositories
2843 -I,--include <PATTERN[+]>
2845 include names matching the given patterns
2846 -X,--exclude <PATTERN[+]>
2848 exclude names matching the given patterns
2849 -n, --dry-run
2851 do not perform actions, just print output
2852 [+] marked option can be specified multiple times
2854 aliases: rm
2856 rename
2858 rename files; equivalent of copy + remove:
2859 hg rename [OPTION]... SOURCE... DEST
2861 Mark dest as copies of sources; mark sources for deletion. If dest is a
2863 directory, copies are put in that directory. If dest is a file, there
2864 can only be one source.
2865 By default, this command copies the contents of files as they exist in
2867 the working directory. If invoked with -A/--after, the operation is
2868 recorded, but no copying is performed.
2869 To undo marking a destination file as renamed, use --forget. With that
2871 option, all given (positional) arguments are unmarked as renames. The
2872 destination file(s) will be left in place (still tracked). The source
2873 file(s) will not be restored. Note that hg rename --forget behaves the
2874 same way as hg copy --forget.
2875 This command takes effect with the next commit by default.
2877 Returns 0 on success, 1 if errors are encountered.
2879 Options:
2881 --forget
2883 unmark a destination file as renamed
2884 -A, --after
2886 record a rename that has already occurred
2887 --at-rev <REV>
2889 (un)mark renames in the given revision (EXPERIMENTAL)
2890 -f, --force
2892 forcibly move over an existing managed file
2893 -I,--include <PATTERN[+]>
2895 include names matching the given patterns
2896 -X,--exclude <PATTERN[+]>
2898 exclude names matching the given patterns
2899 -n, --dry-run
2901 do not perform actions, just print output
2902 [+] marked option can be specified multiple times
2904 aliases: move mv
2906 resolve
2908 redo merges or set/view the merge status of files:
2909 hg resolve [OPTION]... [FILE]...
2911 Merges with unresolved conflicts are often the result of non-interac‐
2913 tive merging using the internal:merge configuration setting, or a com‐
2914 mand-line merge tool like diff3. The resolve command is used to manage
2915 the files involved in a merge, after hg merge has been run, and before
2916 hg commit is run (i.e. the working directory must have two parents).
2917 See hg help merge-tools for information on configuring merge tools.
2918 The resolve command can be used in the following ways:
2920 • hg resolve [--re-merge] [--tool TOOL] FILE...: attempt to re-merge
2922 the specified files, discarding any previous merge attempts. Re-merg‐
2923 ing is not performed for files already marked as resolved. Use
2924 --all/-a to select all unresolved files. --tool can be used to spec‐
2925 ify the merge tool used for the given files. It overrides the HGMERGE
2926 environment variable and your configuration files. Previous file
2927 contents are saved with a .orig suffix.
2928 • hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
2930 having manually fixed-up the files). The default is to mark all unre‐
2931 solved files.
2932 • hg resolve -u [FILE]...: mark a file as unresolved. The default is to
2934 mark all resolved files.
2935 • hg resolve -l: list files which had or still have conflicts. In the
2937 printed list, U = unresolved and R = resolved. You can use set:unre‐
2938 solved() or set:resolved() to filter the list. See hg help filesets
2939 for details.
2940 Note Mercurial will not let you commit files with unresolved merge
2942 conflicts. You must use hg resolve -m ... before you can commit
2943 after a conflicting merge.
2944 Template:
2946 The following keywords are supported in addition to the common template
2948 keywords and functions. See also hg help templates.
2949 mergestatus
2951 String. Character denoting merge conflicts, U or R.
2952 path String. Repository-absolute path of the file.
2954 Returns 0 on success, 1 if any files fail a resolve attempt.
2956 Options:
2958 -a, --all
2960 select all unresolved files
2961 -l, --list
2963 list state of files needing merge
2964 -m, --mark
2966 mark files as resolved
2967 -u, --unmark
2969 mark files as unresolved
2970 -n, --no-status
2972 hide status prefix
2973 --re-merge
2975 re-merge files
2976 -t,--tool <TOOL>
2978 specify merge tool
2979 -I,--include <PATTERN[+]>
2981 include names matching the given patterns
2982 -X,--exclude <PATTERN[+]>
2984 exclude names matching the given patterns
2985 -T,--template <TEMPLATE>
2987 display with template
2988 [+] marked option can be specified multiple times
2990 revert
2992 restore files to their checkout state:
2993 hg revert [OPTION]... [-r REV] [NAME]...
2995 Note To check out earlier revisions, you should use hg update REV.
2997 To cancel an uncommitted merge (and lose your changes), use hg
2998 merge --abort.
2999 With no revision specified, revert the specified files or directories
3001 to the contents they had in the parent of the working directory. This
3002 restores the contents of files to an unmodified state and unschedules
3003 adds, removes, copies, and renames. If the working directory has two
3004 parents, you must explicitly specify a revision.
3005 Using the -r/--rev or -d/--date options, revert the given files or di‐
3007 rectories to their states as of a specific revision. Because revert
3008 does not change the working directory parents, this will cause these
3009 files to appear modified. This can be helpful to "back out" some or all
3010 of an earlier change. See hg backout for a related method.
3011 Modified files are saved with a .orig suffix before reverting. To dis‐
3013 able these backups, use --no-backup. It is possible to store the backup
3014 files in a custom directory relative to the root of the repository by
3015 setting the ui.origbackuppath configuration option.
3016 See hg help dates for a list of formats valid for -d/--date.
3018 See hg help backout for a way to reverse the effect of an earlier
3020 changeset.
3021 Returns 0 on success.
3023 Options:
3025 -a, --all
3027 revert all changes when no arguments given
3028 -d,--date <DATE>
3030 tipmost revision matching date
3031 -r,--rev <REV>
3033 revert to the specified revision
3034 -C, --no-backup
3036 do not save backup copies of files
3037 -i, --interactive
3039 interactively select the changes
3040 -I,--include <PATTERN[+]>
3042 include names matching the given patterns
3043 -X,--exclude <PATTERN[+]>
3045 exclude names matching the given patterns
3046 -n, --dry-run
3048 do not perform actions, just print output
3049 [+] marked option can be specified multiple times
3051 root
3053 print the root (top) of the current working directory:
3054 hg root
3056 Print the root directory of the current repository.
3058 Template:
3060 The following keywords are supported in addition to the common template
3062 keywords and functions. See also hg help templates.
3063 hgpath String. Path to the .hg directory.
3065 storepath
3067 String. Path to the directory holding versioned data.
3068 Returns 0 on success.
3070 Options:
3072 -T,--template <TEMPLATE>
3074 display with template
3075 shelve
3077 save and set aside changes from the working directory:
3078 hg shelve [OPTION]... [FILE]...
3080 Shelving takes files that "hg status" reports as not clean, saves the
3082 modifications to a bundle (a shelved change), and reverts the files so
3083 that their state in the working directory becomes clean.
3084 To restore these changes to the working directory, using "hg unshelve";
3086 this will work even if you switch to a different commit.
3087 When no files are specified, "hg shelve" saves all not-clean files. If
3089 specific files or directories are named, only changes to those files
3090 are shelved.
3091 In bare shelve (when no files are specified, without interactive, in‐
3093 clude and exclude option), shelving remembers information if the work‐
3094 ing directory was on newly created branch, in other words working di‐
3095 rectory was on different branch than its first parent. In this situa‐
3096 tion unshelving restores branch information to the working directory.
3097 Each shelved change has a name that makes it easier to find later. The
3099 name of a shelved change defaults to being based on the active book‐
3100 mark, or if there is no active bookmark, the current named branch. To
3101 specify a different name, use --name.
3102 To see a list of existing shelved changes, use the --list option. For
3104 each shelved change, this will print its name, age, and description;
3105 use --patch or --stat for more details.
3106 To delete specific shelved changes, use --delete. To delete all shelved
3108 changes, use --cleanup.
3109 Options:
3111 -A, --addremove
3113 mark new/missing files as added/removed before shelving
3114 -u, --unknown
3116 store unknown files in the shelve
3117 --cleanup
3119 delete all shelved changes
3120 --date <DATE>
3122 shelve with the specified commit date
3123 -d, --delete
3125 delete the named shelved change(s)
3126 -e, --edit
3128 invoke editor on commit messages
3129 -k, --keep
3131 shelve, but keep changes in the working directory
3132 -l, --list
3134 list current shelves
3135 -m,--message <TEXT>
3137 use text as shelve message
3138 -n,--name <NAME>
3140 use the given name for the shelved commit
3141 -p, --patch
3143 output patches for changes (provide the names of the shelved
3144 changes as positional arguments)
3145 -i, --interactive
3147 interactive mode
3148 --stat output diffstat-style summary of changes (provide the names of
3150 the shelved changes as positional arguments)
3151 -I,--include <PATTERN[+]>
3153 include names matching the given patterns
3154 -X,--exclude <PATTERN[+]>
3156 exclude names matching the given patterns
3157 [+] marked option can be specified multiple times
3159 status
3161 show changed files in the working directory:
3162 hg status [OPTION]... [FILE]...
3164 Show status of files in the repository. If names are given, only files
3166 that match are shown. Files that are clean or ignored or the source of
3167 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3168 -C/--copies or -A/--all are given. Unless options described with "show
3169 only ..." are given, the options -mardu are used.
3170 Option -q/--quiet hides untracked (unknown and ignored) files unless
3172 explicitly requested with -u/--unknown or -i/--ignored.
3173 Note hg status may appear to disagree with diff if permissions have
3175 changed or a merge has occurred. The standard diff format does
3176 not report permission changes and diff only reports changes rel‐
3177 ative to one merge parent.
3178 If one revision is given, it is used as the base revision. If two re‐
3180 visions are given, the differences between them are shown. The --change
3181 option can also be used as a shortcut to list the changed files of a
3182 revision from its first parent.
3183 The codes used to show the status of files are:
3185 M = modified
3187 A = added
3188 R = removed
3189 C = clean
3190 ! = missing (deleted by non-hg command, but still tracked)
3191 ? = not tracked
3192 I = ignored
3193 = origin of the previous file (with --copies)
3194 The -t/--terse option abbreviates the output by showing only the direc‐
3196 tory name if all the files in it share the same status. The option
3197 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3198 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3199 'unknown', 'i' for 'ignored' and 'c' for clean.
3200 It abbreviates only those statuses which are passed. Note that clean
3202 and ignored files are not displayed with '--terse ic' unless the
3203 -c/--clean and -i/--ignored options are also used.
3204 The -v/--verbose option shows information when the repository is in an
3206 unfinished merge, shelve, rebase state etc. You can have this behavior
3207 turned on by default by enabling the commands.status.verbose option.
3208 You can skip displaying some of these states by setting commands.sta‐
3210 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3211 'merge', 'rebase', or 'unshelve'.
3212 Template:
3214 The following keywords are supported in addition to the common template
3216 keywords and functions. See also hg help templates.
3217 path String. Repository-absolute path of the file.
3219 source String. Repository-absolute path of the file originated from.
3221 Available if --copies is specified.
3222 status String. Character denoting file's status.
3224 Examples:
3226 • show changes in the working directory relative to a changeset:
3228 hg status --rev 9353
3230 • show changes in the working directory relative to the current direc‐
3232 tory (see hg help patterns for more information):
3233 hg status re:
3235 • show all changes including copies in an existing changeset:
3237 hg status --copies --change 9353
3239 • get a NUL separated list of added files, suitable for xargs:
3241 hg status -an0
3243 • show more information about the repository status, abbreviating
3245 added, removed, modified, deleted, and untracked paths:
3246 hg status -v -t mardu
3248 Returns 0 on success.
3250 Options:
3252 -A, --all
3254 show status of all files
3255 -m, --modified
3257 show only modified files
3258 -a, --added
3260 show only added files
3261 -r, --removed
3263 show only removed files
3264 -d, --deleted
3266 show only missing files
3267 -c, --clean
3269 show only files without changes
3270 -u, --unknown
3272 show only unknown (not tracked) files
3273 -i, --ignored
3275 show only ignored files
3276 -n, --no-status
3278 hide status prefix
3279 -t,--terse <VALUE>
3281 show the terse output (EXPERIMENTAL) (default: nothing)
3282 -C, --copies
3284 show source of copied files (DEFAULT: ui.statuscopies)
3285 -0, --print0
3287 end filenames with NUL, for use with xargs
3288 --rev <REV[+]>
3290 show difference from revision
3291 --change <REV>
3293 list the changed files of a revision
3294 -I,--include <PATTERN[+]>
3296 include names matching the given patterns
3297 -X,--exclude <PATTERN[+]>
3299 exclude names matching the given patterns
3300 -S, --subrepos
3302 recurse into subrepositories
3303 -T,--template <TEMPLATE>
3305 display with template
3306 [+] marked option can be specified multiple times
3308 aliases: st
3310 summary
3312 summarize working directory state:
3313 hg summary [--remote]
3315 This generates a brief summary of the working directory state, includ‐
3317 ing parents, branch, commit status, phase and available updates.
3318 With the --remote option, this will check the default paths for incom‐
3320 ing and outgoing changes. This can be time-consuming.
3321 Returns 0 on success.
3323 Options:
3325 --remote
3327 check for push and pull
3328 aliases: sum
3330 unshelve
3332 restore a shelved change to the working directory:
3333 hg unshelve [OPTION]... [[-n] SHELVED]
3335 This command accepts an optional name of a shelved change to restore.
3337 If none is given, the most recent shelved change is used.
3338 If a shelved change is applied successfully, the bundle that contains
3340 the shelved changes is moved to a backup location (.hg/shelve-backup).
3341 Since you can restore a shelved change on top of an arbitrary commit,
3343 it is possible that unshelving will result in a conflict between your
3344 changes and the commits you are unshelving onto. If this occurs, you
3345 must resolve the conflict, then use --continue to complete the unshelve
3346 operation. (The bundle will not be moved until you successfully com‐
3347 plete the unshelve.)
3348 (Alternatively, you can use --abort to abandon an unshelve that causes
3350 a conflict. This reverts the unshelved changes, and leaves the bundle
3351 in place.)
3352 If bare shelved change (without interactive, include and exclude op‐
3354 tion) was done on newly created branch it would restore branch informa‐
3355 tion to the working directory.
3356 After a successful unshelve, the shelved changes are stored in a backup
3358 directory. Only the N most recent backups are kept. N defaults to 10
3359 but can be overridden using the shelve.maxbackups configuration option.
3360 Timestamp in seconds is used to decide order of backups. More than
3362 maxbackups backups are kept, if same timestamp prevents from deciding
3363 exact order of them, for safety.
3364 Selected changes can be unshelved with --interactive flag. The working
3366 directory is updated with the selected changes, and only the unselected
3367 changes remain shelved. Note: The whole shelve is applied to working
3368 directory first before running interactively. So, this will bring up
3369 all the conflicts between working directory and the shelve, irrespec‐
3370 tive of which changes will be unshelved.
3371 Options:
3373 -a, --abort
3375 abort an incomplete unshelve operation
3376 -c, --continue
3378 continue an incomplete unshelve operation
3379 -i, --interactive
3381 use interactive mode (EXPERIMENTAL)
3382 -k, --keep
3384 keep shelve after unshelving
3385 -n,--name <NAME>
3387 restore shelved change with given name
3388 -t,--tool <VALUE>
3390 specify merge tool
3391 --date <DATE>
3393 set date for temporary commits (DEPRECATED)
3394 update
3396 update working directory (or switch revisions):
3397 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3399 Update the repository's working directory to the specified changeset.
3401 If no changeset is specified, update to the tip of the current named
3402 branch and move the active bookmark (see hg help bookmarks).
3403 Update sets the working directory's parent revision to the specified
3405 changeset (see hg help parents).
3406 If the changeset is not a descendant or ancestor of the working direc‐
3408 tory's parent and there are uncommitted changes, the update is aborted.
3409 With the -c/--check option, the working directory is checked for uncom‐
3410 mitted changes; if none are found, the working directory is updated to
3411 the specified changeset.
3412 The -C/--clean, -c/--check, and -m/--merge options control what happens
3414 if the working directory contains uncommitted changes. At most of one
3415 of them can be specified.
3416 1. If no option is specified, and if the requested changeset is an an‐
3418 cestor or descendant of the working directory's parent, the uncom‐
3419 mitted changes are merged into the requested changeset and the
3420 merged result is left uncommitted. If the requested changeset is not
3421 an ancestor or descendant (that is, it is on another branch), the
3422 update is aborted and the uncommitted changes are preserved.
3423 2. With the -m/--merge option, the update is allowed even if the re‐
3425 quested changeset is not an ancestor or descendant of the working
3426 directory's parent.
3427 3. With the -c/--check option, the update is aborted and the uncommit‐
3429 ted changes are preserved.
3430 4. With the -C/--clean option, uncommitted changes are discarded and
3432 the working directory is updated to the requested changeset.
3433 To cancel an uncommitted merge (and lose your changes), use hg merge
3435 --abort.
3436 Use null as the changeset to remove the working directory (like hg
3438 clone -U).
3439 If you want to revert just one file to an older revision, use hg revert
3441 [-r REV] NAME.
3442 See hg help dates for a list of formats valid for -d/--date.
3444 Returns 0 on success, 1 if there are unresolved files.
3446 Options:
3448 -C, --clean
3450 discard uncommitted changes (no backup)
3451 -c, --check
3453 require clean working directory
3454 -m, --merge
3456 merge uncommitted changes
3457 -d,--date <DATE>
3459 tipmost revision matching date
3460 -r,--rev <REV>
3462 revision
3463 -t,--tool <TOOL>
3465 specify merge tool
3466 aliases: up checkout co
3468 Change import/export
3470 archive
3471 create an unversioned archive of a repository revision:
3472 hg archive [OPTION]... DEST
3474 By default, the revision used is the parent of the working directory;
3476 use -r/--rev to specify a different revision.
3477 The archive type is automatically detected based on file extension (to
3479 override, use -t/--type).
3480 Examples:
3482 • create a zip file containing the 1.0 release:
3484 hg archive -r 1.0 project-1.0.zip
3486 • create a tarball excluding .hg files:
3488 hg archive project.tar.gz -X ".hg*"
3490 Valid types are:
3492 files
3494 a directory full of files (default)
3496 tar
3498 tar archive, uncompressed
3500 tbz2
3502 tar archive, compressed using bzip2
3504 tgz
3506 tar archive, compressed using gzip
3508 txz
3510 tar archive, compressed using lzma (only in Python 3)
3512 uzip
3514 zip archive, uncompressed
3516 zip
3518 zip archive, compressed using deflate
3520 The exact name of the destination archive or directory is given using a
3522 format string; see hg help export for details.
3523 Each member added to an archive file has a directory prefix prepended.
3525 Use -p/--prefix to specify a format string for the prefix. The default
3526 is the basename of the archive, with suffixes removed.
3527 Returns 0 on success.
3529 Options:
3531 --no-decode
3533 do not pass files through decoders
3534 -p,--prefix <PREFIX>
3536 directory prefix for files in archive
3537 -r,--rev <REV>
3539 revision to distribute
3540 -t,--type <TYPE>
3542 type of distribution to create
3543 -S, --subrepos
3545 recurse into subrepositories
3546 -I,--include <PATTERN[+]>
3548 include names matching the given patterns
3549 -X,--exclude <PATTERN[+]>
3551 exclude names matching the given patterns
3552 [+] marked option can be specified multiple times
3554 bundle
3556 create a bundle file:
3557 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]...
3559 Generate a bundle file containing data to be transferred to another
3561 repository.
3562 To create a bundle containing all changesets, use -a/--all (or --base
3564 null). Otherwise, hg assumes the destination will have all the nodes
3565 you specify with --base parameters. Otherwise, hg will assume the
3566 repository has all the nodes in destination, or default-push/default if
3567 no destination is specified, where destination is the repositories you
3568 provide through DEST option.
3569 You can change bundle format with the -t/--type option. See hg help
3571 bundlespec for documentation on this format. By default, the most ap‐
3572 propriate format is used and compression defaults to bzip2.
3573 The bundle file can then be transferred using conventional means and
3575 applied to another repository with the unbundle or pull command. This
3576 is useful when direct push and pull are not available or when exporting
3577 an entire repository is undesirable.
3578 Applying bundles preserves all changeset contents including permis‐
3580 sions, copy/rename information, and revision history.
3581 Returns 0 on success, 1 if no changes found.
3583 Options:
3585 -f, --force
3587 run even when the destination is unrelated
3588 -r,--rev <REV[+]>
3590 a changeset intended to be added to the destination
3591 -b,--branch <BRANCH[+]>
3593 a specific branch you would like to bundle
3594 --base <REV[+]>
3596 a base changeset assumed to be available at the destination
3597 -a, --all
3599 bundle all changesets in the repository
3600 -t,--type <TYPE>
3602 bundle compression type to use (default: bzip2)
3603 -e,--ssh <CMD>
3605 specify ssh command to use
3606 --remotecmd <CMD>
3608 specify hg command to run on the remote side
3609 --insecure
3611 do not verify server certificate (ignoring web.cacerts config)
3612 [+] marked option can be specified multiple times
3614 export
3616 dump the header and diffs for one or more changesets:
3617 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
3619 Print the changeset header and diffs for one or more revisions. If no
3621 revision is given, the parent of the working directory is used.
3622 The information shown in the changeset header is: author, date, branch
3624 name (if non-default), changeset hash, parent(s) and commit comment.
3625 Note hg export may generate unexpected diff output for merge change‐
3627 sets, as it will compare the merge changeset against its first
3628 parent only.
3629 Output may be to a file, in which case the name of the file is given
3631 using a template string. See hg help templates. In addition to the com‐
3632 mon template keywords, the following formatting rules are supported:
3633 %%
3635 literal "%" character
3637 %H
3639 changeset hash (40 hexadecimal digits)
3641 %N
3643 number of patches being generated
3645 %R
3647 changeset revision number
3649 %b
3651 basename of the exporting repository
3653 %h
3655 short-form changeset hash (12 hexadecimal digits)
3657 %m
3659 first line of the commit message (only alphanumeric characters)
3661 %n
3663 zero-padded sequence number, starting at 1
3665 %r
3667 zero-padded changeset revision number
3669 \
3671 literal "" character
3673 Without the -a/--text option, export will avoid generating diffs of
3675 files it detects as binary. With -a, export will generate a diff any‐
3676 way, probably with undesirable results.
3677 With -B/--bookmark changesets reachable by the given bookmark are se‐
3679 lected.
3680 Use the -g/--git option to generate diffs in the git extended diff for‐
3682 mat. See hg help diffs for more information.
3683 With the --switch-parent option, the diff will be against the second
3685 parent. It can be useful to review a merge.
3686 Template:
3688 The following keywords are supported in addition to the common template
3690 keywords and functions. See also hg help templates.
3691 diff String. Diff content.
3693 parents
3695 List of strings. Parent nodes of the changeset.
3696 Examples:
3698 • use export and import to transplant a bugfix to the current branch:
3700 hg export -r 9353 | hg import -
3702 • export all the changesets between two revisions to a file with rename
3704 information:
3705 hg export --git -r 123:150 > changes.txt
3707 • split outgoing changes into a series of patches with descriptive
3709 names:
3710 hg export -r "outgoing()" -o "%n-%m.patch"
3712 Returns 0 on success.
3714 Options:
3716 -B,--bookmark <BOOKMARK>
3718 export changes only reachable by given bookmark
3719 -o,--output <FORMAT>
3721 print output to file with formatted name
3722 --switch-parent
3724 diff against the second parent
3725 -r,--rev <REV[+]>
3727 revisions to export
3728 -a, --text
3730 treat all files as text
3731 -g, --git
3733 use git extended diff format (DEFAULT: diff.git)
3734 --binary
3736 generate binary diffs in git mode (default)
3737 --nodates
3739 omit dates from diff headers
3740 -T,--template <TEMPLATE>
3742 display with template
3743 [+] marked option can be specified multiple times
3745 import
3747 import an ordered set of patches:
3748 hg import [OPTION]... PATCH...
3750 Import a list of patches and commit them individually (unless --no-com‐
3752 mit is specified).
3753 To read a patch from standard input (stdin), use "-" as the patch name.
3755 If a URL is specified, the patch will be downloaded from there.
3756 Import first applies changes to the working directory (unless --bypass
3758 is specified), import will abort if there are outstanding changes.
3759 Use --bypass to apply and commit patches directly to the repository,
3761 without affecting the working directory. Without --exact, patches will
3762 be applied on top of the working directory parent revision.
3763 You can import a patch straight from a mail message. Even patches as
3765 attachments work (to use the body part, it must have type text/plain or
3766 text/x-patch). From and Subject headers of email message are used as
3767 default committer and commit message. All text/plain body parts before
3768 first diff are added to the commit message.
3769 If the imported patch was generated by hg export, user and description
3771 from patch override values from message headers and body. Values given
3772 on command line with -m/--message and -u/--user override these.
3773 If --exact is specified, import will set the working directory to the
3775 parent of each patch before applying it, and will abort if the result‐
3776 ing changeset has a different ID than the one recorded in the patch.
3777 This will guard against various ways that portable patch formats and
3778 mail systems might fail to transfer Mercurial data or metadata. See hg
3779 bundle for lossless transmission.
3780 Use --partial to ensure a changeset will be created from the patch even
3782 if some hunks fail to apply. Hunks that fail to apply will be written
3783 to a <target-file>.rej file. Conflicts can then be resolved by hand be‐
3784 fore hg commit --amend is run to update the created changeset. This
3785 flag exists to let people import patches that partially apply without
3786 losing the associated metadata (author, date, description, ...).
3787 Note When no hunks apply cleanly, hg import --partial will create an
3789 empty changeset, importing only the patch metadata.
3790 With -s/--similarity, hg will attempt to discover renames and copies in
3792 the patch in the same way as hg addremove.
3793 It is possible to use external patch programs to perform the patch by
3795 setting the ui.patch configuration option. For the default internal
3796 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
3797 fig for more information about configuration files and how to use these
3798 options.
3799 See hg help dates for a list of formats valid for -d/--date.
3801 Examples:
3803 • import a traditional patch from a website and detect renames:
3805 hg import -s 80 http://example.com/bugfix.patch
3807 • import a changeset from an hgweb server:
3809 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
3811 • import all the patches in an Unix-style mbox:
3813 hg import incoming-patches.mbox
3815 • import patches from stdin:
3817 hg import -
3819 • attempt to exactly restore an exported changeset (not always possi‐
3821 ble):
3822 hg import --exact proposed-fix.patch
3824 • use an external tool to apply a patch which is too fuzzy for the de‐
3826 fault internal tool.
3827 hg import --config ui.patch="patch --merge" fuzzy.patch
3829 • change the default fuzzing from 2 to a less strict 7
3831 hg import --config ui.fuzz=7 fuzz.patch
3833 Returns 0 on success, 1 on partial success (see --partial).
3835 Options:
3837 -p,--strip <NUM>
3839 directory strip option for patch. This has the same meaning as
3840 the corresponding patch option (default: 1)
3841 -b,--base <PATH>
3843 base path (DEPRECATED)
3844 --secret
3846 use the secret phase for committing
3847 -e, --edit
3849 invoke editor on commit messages
3850 -f, --force
3852 skip check for outstanding uncommitted changes (DEPRECATED)
3853 --no-commit
3855 don't commit, just update the working directory
3856 --bypass
3858 apply patch without touching the working directory
3859 --partial
3861 commit even if some hunks fail
3862 --exact
3864 abort if patch would apply lossily
3865 --prefix <DIR>
3867 apply patch to subdirectory
3868 --import-branch
3870 use any branch information in patch (implied by --exact)
3871 -m,--message <TEXT>
3873 use text as commit message
3874 -l,--logfile <FILE>
3876 read commit message from file
3877 -d,--date <DATE>
3879 record the specified date as commit date
3880 -u,--user <USER>
3882 record the specified user as committer
3883 -s,--similarity <SIMILARITY>
3885 guess renamed files by similarity (0<=s<=100)
3886 aliases: patch
3888 unbundle
3890 apply one or more bundle files:
3891 hg unbundle [-u] FILE...
3893 Apply one or more bundle files generated by hg bundle.
3895 Returns 0 on success, 1 if an update has unresolved files.
3897 Options:
3899 -u, --update
3901 update to new branch head if changesets were unbundled
3902 Repository maintenance
3904 manifest
3905 output the current or given revision of the project manifest:
3906 hg manifest [-r REV]
3908 Print a list of version controlled files for the given revision. If no
3910 revision is given, the first parent of the working directory is used,
3911 or the null revision if no revision is checked out.
3912 With -v, print file permissions, symlink and executable bits. With
3914 --debug, print file revision hashes.
3915 If option --all is specified, the list of all files from all revisions
3917 is printed. This includes deleted and renamed files.
3918 Returns 0 on success.
3920 Options:
3922 -r,--rev <REV>
3924 revision to display
3925 --all list files from all revisions
3927 -T,--template <TEMPLATE>
3929 display with template
3930 recover
3932 roll back an interrupted transaction:
3933 hg recover
3935 Recover from an interrupted commit or pull.
3937 This command tries to fix the repository status after an interrupted
3939 operation. It should only be necessary when Mercurial suggests it.
3940 Returns 0 if successful, 1 if nothing to recover or verify fails.
3942 Options:
3944 --verify
3946 run hg verify after successful recover
3947 rollback
3949 roll back the last transaction (DANGEROUS) (DEPRECATED):
3950 hg rollback
3952 Please use hg commit --amend instead of rollback to correct mistakes in
3954 the last commit.
3955 This command should be used with care. There is only one level of roll‐
3957 back, and there is no way to undo a rollback. It will also restore the
3958 dirstate at the time of the last transaction, losing any dirstate
3959 changes since that time. This command does not alter the working direc‐
3960 tory.
3961 Transactions are used to encapsulate the effects of all commands that
3963 create new changesets or propagate existing changesets into a reposi‐
3964 tory.
3965 For example, the following commands are transactional, and their ef‐
3967 fects can be rolled back:
3968 • commit
3970 • import
3972 • pull
3974 • push (with this repository as the destination)
3976 • unbundle
3978 To avoid permanent data loss, rollback will refuse to rollback a commit
3980 transaction if it isn't checked out. Use --force to override this pro‐
3981 tection.
3982 The rollback command can be entirely disabled by setting the ui.roll‐
3984 back configuration setting to false. If you're here because you want to
3985 use rollback and it's disabled, you can re-enable the command by set‐
3986 ting ui.rollback to true.
3987 This command is not intended for use on public repositories. Once
3989 changes are visible for pull by other users, rolling a transaction back
3990 locally is ineffective (someone else may already have pulled the
3991 changes). Furthermore, a race is possible with readers of the reposi‐
3992 tory; for example an in-progress pull from the repository may fail if a
3993 rollback is performed.
3994 Returns 0 on success, 1 if no rollback data is available.
3996 Options:
3998 -n, --dry-run
4000 do not perform actions, just print output
4001 -f, --force
4003 ignore safety measures
4004 verify
4006 verify the integrity of the repository:
4007 hg verify
4009 Verify the integrity of the current repository.
4011 This will perform an extensive check of the repository's integrity,
4013 validating the hashes and checksums of each entry in the changelog,
4014 manifest, and tracked files, as well as the integrity of their
4015 crosslinks and indices.
4016 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
4018 information about recovery from corruption of the repository.
4019 Returns 0 on success, 1 if errors are encountered.
4021 Options:
4023 --full perform more checks (EXPERIMENTAL)
4025 Help
4027 config
4028 show combined config settings from all hgrc files:
4029 hg config [-u] [NAME]...
4031 With no arguments, print names and values of all config items.
4033 With one argument of the form section.name, print just the value of
4035 that config item.
4036 With multiple arguments, print names and values of all config items
4038 with matching section names or section.names.
4039 With --edit, start an editor on the user-level config file. With
4041 --global, edit the system-wide config file. With --local, edit the
4042 repository-level config file.
4043 With --source, the source (filename and line number) is printed for
4045 each config item.
4046 See hg help config for more information about config files.
4048 --non-shared flag is used to edit .hg/hgrc-not-shared config file.
4050 This file is not shared across shares when in share-safe mode.
4051 Template:
4053 The following keywords are supported. See also hg help templates.
4055 name String. Config name.
4057 source String. Filename and line number where the item is defined.
4059 value String. Config value.
4061 The --shared flag can be used to edit the config file of shared source
4063 repository. It only works when you have shared using the experimental
4064 share safe feature.
4065 Returns 0 on success, 1 if NAME does not exist.
4067 Options:
4069 -u, --untrusted
4071 show untrusted configuration options
4072 --exp-all-known
4074 show all known config option (EXPERIMENTAL)
4075 -e, --edit
4077 edit user config
4078 -l, --local
4080 edit repository config
4081 --source
4083 show source of configuration value
4084 --shared
4086 edit shared source repository config (EXPERIMENTAL)
4087 --non-shared
4089 edit non shared config (EXPERIMENTAL)
4090 -g, --global
4092 edit global config
4093 -T,--template <TEMPLATE>
4095 display with template
4096 aliases: showconfig debugconfig
4098 help
4100 show help for a given topic or a help overview:
4101 hg help [-eck] [-s PLATFORM] [TOPIC]
4103 With no arguments, print a list of commands with short help messages.
4105 Given a topic, extension, or command name, print help for that topic.
4107 Returns 0 if successful.
4109 Options:
4111 -e, --extension
4113 show only help for extensions
4114 -c, --command
4116 show only help for commands
4117 -k, --keyword
4119 show topics matching keyword
4120 -s,--system <PLATFORM[+]>
4122 show help for specific platform(s)
4123 [+] marked option can be specified multiple times
4125 version
4127 output version and copyright information:
4128 hg version
4130 Template:
4132 The following keywords are supported. See also hg help templates.
4134 extensions
4136 List of extensions.
4137 ver String. Version number.
4139 And each entry of {extensions} provides the following sub-keywords in
4141 addition to {ver}.
4142 bundled
4144 Boolean. True if included in the release.
4145 name String. Extension name.
4147 Options:
4149 -T,--template <TEMPLATE>
4151 display with template
4152 Uncategorized commands
4155 Mercurial supports generating standalone "bundle" files that hold
4156 repository data. These "bundles" are typically saved locally and used
4157 later or exchanged between different repositories, possibly on differ‐
4158 ent machines. Example commands using bundles are hg bundle and hg un‐
4159 bundle.
4160 Generation of bundle files is controlled by a "bundle specification"
4162 ("bundlespec") string. This string tells the bundle generation process
4163 how to create the bundle.
4164 A "bundlespec" string is composed of the following elements:
4166 type A string denoting the bundle format to use.
4168 compression
4170 Denotes the compression engine to use compressing the raw bundle
4171 data.
4172 parameters
4174 Arbitrary key-value parameters to further control bundle genera‐
4175 tion.
4176 A "bundlespec" string has the following formats:
4178 <type> The literal bundle format string is used.
4180 <compression>-<type>
4182 The compression engine and format are delimited by a hyphen (-).
4183 Optional parameters follow the <type>. Parameters are URI escaped
4185 key=value pairs. Each pair is delimited by a semicolon (;). The first
4186 parameter begins after a ; immediately following the <type> value.
4187 Available Types
4189 The following bundle <type> strings are available:
4190 v1 Produces a legacy "changegroup" version 1 bundle.
4192 This format is compatible with nearly all Mercurial clients be‐
4194 cause it is the oldest. However, it has some limitations, which
4195 is why it is no longer the default for new repositories.
4196 v1 bundles can be used with modern repositories using the "gen‐
4198 eraldelta" storage format. However, it may take longer to pro‐
4199 duce the bundle and the resulting bundle may be significantly
4200 larger than a v2 bundle.
4201 v1 bundles can only use the gzip, bzip2, and none compression
4203 formats.
4204 v2 Produces a version 2 bundle.
4206 Version 2 bundles are an extensible format that can store addi‐
4208 tional repository data (such as bookmarks and phases informa‐
4209 tion) and they can store data more efficiently, resulting in
4210 smaller bundles.
4211 Version 2 bundles can also use modern compression engines, such
4213 as zstd, making them faster to compress and often smaller.
4214 Available Compression Engines
4216 The following bundle <compression> engines can be used:
4217 bzip2
4219 An algorithm that produces smaller bundles than gzip.
4221 All Mercurial clients should support this format.
4223 This engine will likely produce smaller bundles than gzip but
4225 will be significantly slower, both during compression and decom‐
4226 pression.
4227 If available, the zstd engine can yield similar or better com‐
4229 pression at much higher speeds.
4230 gzip
4232 zlib compression using the DEFLATE algorithm.
4234 All Mercurial clients should support this format. The compres‐
4236 sion algorithm strikes a reasonable balance between compression
4237 ratio and size.
4238 none
4240 No compression is performed.
4242 Use this compression engine to explicitly disable compression.
4244 Examples
4246 v2
4247 Produce a v2 bundle using default options, including compres‐
4249 sion.
4250 none-v1
4252 Produce a v1 bundle with no compression.
4254 zstd-v2
4256 Produce a v2 bundle with zstandard compression using default
4258 settings.
4259 zstd-v1
4261 This errors because zstd is not supported for v1 types.
4263
4265 Mercurial colorizes output from several commands.
4266 For example, the diff command shows additions in green and deletions in
4268 red, while the status command shows modified files in magenta. Many
4269 other commands have analogous colors. It is possible to customize these
4270 colors.
4271 To enable color (default) whenever possible use:
4273 [ui]
4275 color = yes
4276 To disable color use:
4278 [ui]
4280 color = no
4281 See hg help config.ui.color for details.
4283 The default pager on Windows does not support color, so enabling the
4285 pager will effectively disable color. See hg help config.ui.paginate
4286 to disable the pager. Alternately, MSYS and Cygwin shells provide less
4287 as a pager, which can be configured to support ANSI color mode. Win‐
4288 dows 10 natively supports ANSI color mode.
4289 Mode
4291 Mercurial can use various systems to display color. The supported modes
4292 are ansi, win32, and terminfo. See hg help config.color for details
4293 about how to control the mode.
4294 Effects
4296 Other effects in addition to color, like bold and underlined text, are
4297 also available. By default, the terminfo database is used to find the
4298 terminal codes used to change color and effect. If terminfo is not
4299 available, then effects are rendered with the ECMA-48 SGR control func‐
4300 tion (aka ANSI escape codes).
4301 The available effects in terminfo mode are 'blink', 'bold', 'dim', 'in‐
4303 verse', 'invisible', 'italic', 'standout', and 'underline'; in ECMA-48
4304 mode, the options are 'bold', 'inverse', 'italic', and 'underline'.
4305 How each is rendered depends on the terminal emulator. Some may not be
4306 available for a given terminal type, and will be silently ignored.
4307 If the terminfo entry for your terminal is missing codes for an effect
4309 or has the wrong codes, you can add or override those codes in your
4310 configuration:
4311 [color]
4313 terminfo.dim = \E[2m
4314 where 'E' is substituted with an escape character.
4316 Labels
4318 Text receives color effects depending on the labels that it has. Many
4319 default Mercurial commands emit labelled text. You can also define your
4320 own labels in templates using the label function, see hg help templates
4321 . A single portion of text may have more than one label. In that case,
4322 effects given to the last label will override any other effects. This
4323 includes the special "none" effect, which nullifies other effects.
4324 Labels are normally invisible. In order to see these labels and their
4326 position in the text, use the global --color=debug option. The same an‐
4327 chor text may be associated to multiple labels, e.g.
4328 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
4330 The following are the default effects for some default labels. Default
4332 effects may be overridden from your configuration file:
4333 [color]
4335 status.modified = blue bold underline red_background
4336 status.added = green bold
4337 status.removed = red bold blue_background
4338 status.deleted = cyan bold underline
4339 status.unknown = magenta bold underline
4340 status.ignored = black bold
4341 # 'none' turns off all effects
4343 status.clean = none
4344 status.copied = none
4345 qseries.applied = blue bold underline
4347 qseries.unapplied = black bold
4348 qseries.missing = red bold
4349 diff.diffline = bold
4351 diff.extended = cyan bold
4352 diff.file_a = red bold
4353 diff.file_b = green bold
4354 diff.hunk = magenta
4355 diff.deleted = red
4356 diff.inserted = green
4357 diff.changed = white
4358 diff.tab =
4359 diff.trailingwhitespace = bold red_background
4360 # Blank so it inherits the style of the surrounding label
4362 changeset.public =
4363 changeset.draft =
4364 changeset.secret =
4365 resolve.unresolved = red bold
4367 resolve.resolved = green bold
4368 bookmarks.active = green
4370 branches.active = none
4372 branches.closed = black bold
4373 branches.current = green
4374 branches.inactive = none
4375 tags.normal = green
4377 tags.local = black bold
4378 rebase.rebased = blue
4380 rebase.remaining = red bold
4381 shelve.age = cyan
4383 shelve.newest = green bold
4384 shelve.name = blue bold
4385 histedit.remaining = red bold
4387 Custom colors
4389 Because there are only eight standard colors, Mercurial allows you to
4390 define color names for other color slots which might be available for
4391 your terminal type, assuming terminfo mode. For instance:
4392 color.brightblue = 12
4394 color.pink = 207
4395 color.orange = 202
4396 to set 'brightblue' to color slot 12 (useful for 16 color terminals
4398 that have brighter colors defined in the upper eight) and, 'pink' and
4399 'orange' to colors in 256-color xterm's default color cube. These de‐
4400 fined colors may then be used as any of the pre-defined eight, includ‐
4401 ing appending '_background' to set the background to that color.
4402
4404 Some commands allow the user to specify a date, e.g.:
4405 • backout, commit, import, tag: Specify the commit date.
4407 • log, revert, update: Select revision(s) by date.
4409 Many date formats are valid. Here are some examples:
4411 • Wed Dec 6 13:18:29 2006 (local timezone assumed)
4413 • Dec 6 13:18 -0600 (year assumed, time offset provided)
4415 • Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
4417 • Dec 6 (midnight)
4419 • 13:18 (today assumed)
4421 • 3:39 (3:39AM assumed)
4423 • 3:39pm (15:39)
4425 • 2006-12-06 13:18:29 (ISO 8601 format)
4427 • 2006-12-6 13:18
4429 • 2006-12-6
4431 • 12-6
4433 • 12/6
4435 • 12/6/6 (Dec 6 2006)
4437 • today (midnight)
4439 • yesterday (midnight)
4441 • now - right now
4443 Lastly, there is Mercurial's internal format:
4445 • 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
4447 This is the internal representation format for dates. The first number
4449 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
4450 second is the offset of the local timezone, in seconds west of UTC
4451 (negative if the timezone is east of UTC).
4452 The log command also accepts date ranges:
4454 • <DATE - at or before a given date/time
4456 • >DATE - on or after a given date/time
4458 • DATE to DATE - a date range, inclusive
4460 • -DAYS - within a given number of days from today
4462
4464 Mercurial evolves over time, some features, options, commands may be
4465 replaced by better and more secure alternatives. This topic will help
4466 you migrating your existing usage and/or configuration to newer fea‐
4467 tures.
4468 Commands
4470 The following commands are still available but their use are not recom‐
4471 mended:
4472 locate
4474 This command has been replaced by hg files.
4476 parents
4478 This command can be replaced by hg summary or hg log with appropriate
4480 revsets. See hg help revsets for more information.
4481 tip
4483 The recommended alternative is hg heads.
4485 Options
4487 web.allowpull
4488 Renamed to allow-pull.
4490 web.allow_push
4492 Renamed to allow-push.
4494
4496 Mercurial's default format for showing changes between two versions of
4497 a file is compatible with the unified format of GNU diff, which can be
4498 used by GNU patch and many other standard tools.
4499 While this standard format is often enough, it does not encode the fol‐
4501 lowing information:
4502 • executable status and other permission bits
4504 • copy or rename information
4506 • changes in binary files
4508 • creation or deletion of empty files
4510 Mercurial also supports the extended diff format from the git VCS which
4512 addresses these limitations. The git diff format is not produced by de‐
4513 fault because a few widespread tools still do not understand this for‐
4514 mat.
4515 This means that when generating diffs from a Mercurial repository (e.g.
4517 with hg export), you should be careful about things like file copies
4518 and renames or other things mentioned above, because when applying a
4519 standard diff to a different repository, this extra information is
4520 lost. Mercurial's internal operations (like push and pull) are not af‐
4521 fected by this, because they use an internal binary format for communi‐
4522 cating changes.
4523 To make Mercurial produce the git extended diff format, use the --git
4525 option available for many commands, or set 'git = True' in the [diff]
4526 section of your configuration file. You do not need to set this option
4527 when importing diffs in this format or using them in the mq extension.
4528
4530 HG Path to the 'hg' executable, automatically passed when running
4531 hooks, extensions or external tools. If unset or empty, this is
4532 the hg executable's name if it's frozen, or an executable named
4533 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
4534 on Windows) is searched.
4535 HGEDITOR
4537 This is the name of the editor to run when committing. See EDI‐
4538 TOR.
4539 (deprecated, see hg help config.ui.editor)
4541 HGENCODING
4543 This overrides the default locale setting detected by Mercurial.
4544 This setting is used to convert data including usernames,
4545 changeset descriptions, tag names, and branches. This setting
4546 can be overridden with the --encoding command-line option.
4547 HGENCODINGMODE
4549 This sets Mercurial's behavior for handling unknown characters
4550 while transcoding user input. The default is "strict", which
4551 causes Mercurial to abort if it can't map a character. Other
4552 settings include "replace", which replaces unknown characters,
4553 and "ignore", which drops them. This setting can be overridden
4554 with the --encodingmode command-line option.
4555 HGENCODINGAMBIGUOUS
4557 This sets Mercurial's behavior for handling characters with "am‐
4558 biguous" widths like accented Latin characters with East Asian
4559 fonts. By default, Mercurial assumes ambiguous characters are
4560 narrow, set this variable to "wide" if such characters cause
4561 formatting problems.
4562 HGMERGE
4564 An executable to use for resolving merge conflicts. The program
4565 will be executed with three arguments: local file, remote file,
4566 ancestor file.
4567 (deprecated, see hg help config.ui.merge)
4569 HGRCPATH
4571 A list of files or directories to search for configuration
4572 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
4573 PATH is not set, platform default search path is used. If empty,
4574 only the .hg/hgrc from the current repository is read.
4575 For each element in HGRCPATH:
4577 • if it's a directory, all files ending with .rc are added
4579 • otherwise, the file itself will be added
4581 HGRCSKIPREPO
4583 When set, the .hg/hgrc from repositories are not read.
4584 HGPLAIN
4586 When set, this disables any configuration settings that might
4587 change Mercurial's default output. This includes encoding, de‐
4588 faults, verbose mode, debug mode, quiet mode, tracebacks, and
4589 localization. This can be useful when scripting against Mercu‐
4590 rial in the face of existing user configuration.
4591 In addition to the features disabled by HGPLAIN=, the following
4593 values can be specified to adjust behavior:
4594 +strictflags
4596 Restrict parsing of command line flags.
4598 Equivalent options set via command line flags or environment
4600 variables are not overridden.
4601 See hg help scripting for details.
4603 HGPLAINEXCEPT
4605 This is a comma-separated list of features to preserve when HG‐
4606 PLAIN is enabled. Currently the following values are supported:
4607 alias
4609 Don't remove aliases.
4611 color
4613 Don't disable colored output.
4615 i18n
4617 Preserve internationalization.
4619 revsetalias
4621 Don't remove revset aliases.
4623 templatealias
4625 Don't remove template aliases.
4627 progress
4629 Don't hide progress output.
4631 Setting HGPLAINEXCEPT to anything (even an empty string) will
4633 enable plain mode.
4634 HGUSER This is the string used as the author of a commit. If not set,
4636 available values will be considered in this order:
4637 • HGUSER (deprecated)
4639 • configuration files from the HGRCPATH
4641 • EMAIL
4643 • interactive prompt
4645 • LOGNAME (with @hostname appended)
4647 (deprecated, see hg help config.ui.username)
4649 EMAIL May be used as the author of a commit; see HGUSER.
4651 LOGNAME
4653 May be used as the author of a commit; see HGUSER.
4654 VISUAL This is the name of the editor to use when committing. See EDI‐
4656 TOR.
4657 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
4659 user to modify, for example when writing commit messages. The
4660 editor it uses is determined by looking at the environment vari‐
4661 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
4662 non-empty one is chosen. If all of them are empty, the editor
4663 defaults to 'vi'.
4664 PYTHONPATH
4666 This is used by Python to find imported modules and may need to
4667 be set appropriately if this Mercurial is not installed sys‐
4668 tem-wide.
4669
4671 Obsolescence markers make it possible to mark changesets that have been
4672 deleted or superseded in a new version of the changeset.
4673 Unlike the previous way of handling such changes, by stripping the old
4675 changesets from the repository, obsolescence markers can be propagated
4676 between repositories. This allows for a safe and simple way of exchang‐
4677 ing mutable history and altering it after the fact. Changeset phases
4678 are respected, such that only draft and secret changesets can be al‐
4679 tered (see hg help phases for details).
4680 Obsolescence is tracked using "obsolescence markers", a piece of meta‐
4682 data tracking which changesets have been made obsolete, potential suc‐
4683 cessors for a given changeset, the moment the changeset was marked as
4684 obsolete, and the user who performed the rewriting operation. The mark‐
4685 ers are stored separately from standard changeset data can be exchanged
4686 without any of the precursor changesets, preventing unnecessary ex‐
4687 change of obsolescence data.
4688 The complete set of obsolescence markers describes a history of change‐
4690 set modifications that is orthogonal to the repository history of file
4691 modifications. This changeset history allows for detection and auto‐
4692 matic resolution of edge cases arising from multiple users rewriting
4693 the same part of history concurrently.
4694 Current feature status
4696 This feature is still in development.
4697 Instability
4699 Rewriting changesets might introduce instability.
4700 There are two main kinds of instability: orphaning and diverging.
4702 Orphans are changesets left behind when their ancestors are rewritten.
4704 Divergence has two variants:
4705 • Content-divergence occurs when independent rewrites of the same
4707 changesets lead to different results.
4708 • Phase-divergence occurs when the old (obsolete) version of a change‐
4710 set becomes public.
4711 It is possible to prevent local creation of orphans by using the fol‐
4713 lowing config:
4714 [experimental]
4716 evolution.createmarkers = true
4717 evolution.exchange = true
4718 You can also enable that option explicitly:
4720 [experimental]
4722 evolution.createmarkers = true
4723 evolution.exchange = true
4724 evolution.allowunstable = true
4725
4727 Mercurial has the ability to add new features through the use of exten‐
4728 sions. Extensions may add new commands, add options to existing com‐
4729 mands, change the default behavior of commands, or implement hooks.
4730 To enable the "foo" extension, either shipped with Mercurial or in the
4732 Python search path, create an entry for it in your configuration file,
4733 like this:
4734 [extensions]
4736 foo =
4737 You may also specify the full path to an extension:
4739 [extensions]
4741 myfeature = ~/.hgext/myfeature.py
4742 See hg help config for more information on configuration files.
4744 Extensions are not loaded by default for a variety of reasons: they can
4746 increase startup overhead; they may be meant for advanced usage only;
4747 they may provide potentially dangerous abilities (such as letting you
4748 destroy or modify history); they might not be ready for prime time; or
4749 they may alter some usual behaviors of stock Mercurial. It is thus up
4750 to the user to activate extensions as needed.
4751 To explicitly disable an extension enabled in a configuration file of
4753 broader scope, prepend its path with !:
4754 [extensions]
4756 # disabling extension bar residing in /path/to/extension/bar.py
4757 bar = !/path/to/extension/bar.py
4758 # ditto, but no path was supplied for extension baz
4759 baz = !
4760 disabled extensions:
4762 acl hooks for controlling repository access
4764 blackbox
4766 log repository events to a blackbox for debugging
4767 bugzilla
4769 hooks for integrating with the Bugzilla bug tracker
4770 censor erase file content at a given revision
4772 churn command to display statistics about repository history
4774 clonebundles
4776 advertise pre-generated bundles to seed clones
4777 closehead
4779 close arbitrary heads without checking them out first
4780 convert
4782 import revisions from foreign VCS repositories into Mercurial
4783 eol automatically manage newlines in repository files
4785 extdiff
4787 command to allow external programs to compare revisions
4788 factotum
4790 http authentication with factotum
4791 fastexport
4793 export repositories as git fast-import stream
4794 githelp
4796 try mapping git commands to Mercurial commands
4797 gpg commands to sign and verify changesets
4799 hgk browse the repository in a graphical way
4801 highlight
4803 syntax highlighting for hgweb (requires Pygments)
4804 histedit
4806 interactive history editing
4807 keyword
4809 expand keywords in tracked files
4810 largefiles
4812 track large binary files
4813 mq manage a stack of patches
4815 notify hooks for sending email push notifications
4817 patchbomb
4819 command to send changesets as (a series of) patch emails
4820 rebase command to move sets of revisions to a different ancestor
4822 relink recreates hardlinks between repository clones
4824 schemes
4826 extend schemes with shortcuts to repository swarms
4827 share share a common history between several working directories
4829 transplant
4831 command to transplant changesets from another branch
4832 win32mbcs
4834 allow the use of MBCS paths with problematic encodings
4835 zeroconf
4837 discover and advertise repositories on the local network
4838
4840 Mercurial supports a functional language for selecting a set of files.
4841 Like other file patterns, this pattern type is indicated by a prefix,
4843 'set:'. The language supports a number of predicates which are joined
4844 by infix operators. Parenthesis can be used for grouping.
4845 Identifiers such as filenames or patterns must be quoted with single or
4847 double quotes if they contain characters outside of
4848 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4849 predicates. This generally applies to file patterns other than globs
4850 and arguments for predicates. Pattern prefixes such as path: may be
4851 specified without quoting.
4852 Special characters can be used in quoted identifiers by escaping them,
4854 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4855 preted, strings can be prefixed with r, e.g. r'...'.
4856 See also hg help patterns.
4858 Operators
4860 There is a single prefix operator:
4861 not x
4863 Files not in x. Short form is ! x.
4865 These are the supported infix operators:
4867 x and y
4869 The intersection of files in x and y. Short form is x & y.
4871 x or y
4873 The union of files in x and y. There are two alternative short
4875 forms: x | y and x + y.
4876 x - y
4878 Files in x but not in y.
4880 Predicates
4882 The following predicates are supported:
4883 added()
4885 File that is added according to hg status.
4887 binary()
4889 File that appears to be binary (contains NUL bytes).
4891 clean()
4893 File that is clean according to hg status.
4895 copied()
4897 File that is recorded as being copied.
4899 deleted()
4901 Alias for missing().
4903 encoding(name)
4905 File can be successfully decoded with the given character encod‐
4907 ing. May not be useful for encodings other than ASCII and UTF-8.
4908 eol(style)
4910 File contains newlines of the given style (dos, unix, mac). Bi‐
4912 nary files are excluded, files with mixed line endings match
4913 multiple styles.
4914 exec()
4916 File that is marked as executable.
4918 grep(regex)
4920 File contains the given regular expression.
4922 hgignore()
4924 File that matches the active .hgignore pattern.
4926 ignored()
4928 File that is ignored according to hg status.
4930 missing()
4932 File that is missing according to hg status.
4934 modified()
4936 File that is modified according to hg status.
4938 portable()
4940 File that has a portable name. (This doesn't include filenames
4942 with case collisions.)
4943 removed()
4945 File that is removed according to hg status.
4947 resolved()
4949 File that is marked resolved according to hg resolve -l.
4951 revs(revs, pattern)
4953 Evaluate set in the specified revisions. If the revset match
4955 multiple revs, this will return file matching pattern in any of
4956 the revision.
4957 size(expression)
4959 File size matches the given expression. Examples:
4961 • size('1k') - files from 1024 to 2047 bytes
4963 • size('< 20k') - files less than 20480 bytes
4965 • size('>= .5MB') - files at least 524288 bytes
4967 • size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
4969 status(base, rev, pattern)
4971 Evaluate predicate using status change between base and rev. Ex‐
4973 amples:
4974 • status(3, 7, added()) - matches files added from "3" to "7"
4976 subrepo([pattern])
4978 Subrepositories whose paths match the given pattern.
4980 symlink()
4982 File that is marked as a symlink.
4984 tracked()
4986 File that is under Mercurial control.
4988 unknown()
4990 File that is unknown according to hg status.
4992 unresolved()
4994 File that is marked unresolved according to hg resolve -l.
4996 Examples
4998 Some sample queries:
4999 • Show status of files that appear to be binary in the working direc‐
5001 tory:
5002 hg status -A "set:binary()"
5004 • Forget files that are in .hgignore but are already tracked:
5006 hg forget "set:hgignore() and not ignored()"
5008 • Find text files that contain a string:
5010 hg files "set:grep(magic) and not binary()"
5012 • Find C files in a non-standard encoding:
5014 hg files "set:**.c and not encoding('UTF-8')"
5016 • Revert copies of large binary files:
5018 hg revert "set:copied() and binary() and size('>1M')"
5020 • Revert files that were added to the working directory:
5022 hg revert "set:revs('wdir()', added())"
5024 • Remove files listed in foo.lst that contain the letter a or b:
5026 hg remove "set: listfile:foo.lst and (**a* or **b*)"
5028
5030 Most Mercurial commands accept various flags.
5031 Flag names
5033 Flags for each command are listed in hg help for that command. Addi‐
5034 tionally, some flags, such as --repository, are global and can be used
5035 with any command - those are seen in hg help -v, and can be specified
5036 before or after the command.
5037 Every flag has at least a long name, such as --repository. Some flags
5039 may also have a short one-letter name, such as the equivalent -R. Using
5040 the short or long name is equivalent and has the same effect. The long
5041 name may be abbreviated to any unambiguous prefix. For example, hg com‐
5042 mit --amend can be abbreviated to hg commit --am.
5043 Flags that have a short name can also be bundled together - for in‐
5045 stance, to specify both --edit (short -e) and --interactive (short -i),
5046 one could use:
5047 hg commit -ei
5049 If any of the bundled flags takes a value (i.e. is not a boolean), it
5051 must be last, followed by the value:
5052 hg commit -im 'Message'
5054 Flag types
5056 Mercurial command-line flags can be strings, numbers, booleans, or
5057 lists of strings.
5058 Specifying flag values
5060 The following syntaxes are allowed, assuming a flag 'flagname' with
5061 short name 'f':
5062 --flagname=foo
5064 --flagname foo
5065 -f foo
5066 -ffoo
5067 This syntax applies to all non-boolean flags (strings, numbers or
5069 lists).
5070 Specifying boolean flags
5072 Boolean flags do not take a value parameter. To specify a boolean, use
5073 the flag name to set it to true, or the same name prefixed with 'no-'
5074 to set it to false:
5075 hg commit --interactive
5077 hg commit --no-interactive
5078 Specifying list flags
5080 List flags take multiple values. To specify them, pass the flag multi‐
5081 ple times:
5082 hg files --include mercurial --include tests
5084 Setting flag defaults
5086 In order to set a default value for a flag in an hgrc file, it is rec‐
5087 ommended to use aliases:
5088 [alias]
5090 commit = commit --interactive
5091 For more information on hgrc files, see hg help config.
5093 Overriding flags on the command line
5095 If the same non-list flag is specified multiple times on the command
5096 line, the latest specification is used:
5097 hg commit -m "Ignored value" -m "Used value"
5099 This includes the use of aliases - e.g., if one has:
5101 [alias]
5103 committemp = commit -m "Ignored value"
5104 then the following command will override that -m:
5106 hg committemp -m "Used value"
5108 Overriding flag defaults
5110 Every flag has a default value, and you may also set your own defaults
5111 in hgrc as described above. Except for list flags, defaults can be
5112 overridden on the command line simply by specifying the flag in that
5113 location.
5114 Hidden flags
5116 Some flags are not shown in a command's help by default - specifically,
5117 those that are deemed to be experimental, deprecated or advanced. To
5118 show all flags, add the --verbose flag for the help command:
5119 hg help --verbose commit
5121
5123 Ancestor
5124 Any changeset that can be reached by an unbroken chain of parent
5125 changesets from a given changeset. More precisely, the ancestors
5126 of a changeset can be defined by two properties: a parent of a
5127 changeset is an ancestor, and a parent of an ancestor is an an‐
5128 cestor. See also: 'Descendant'.
5129 Bookmark
5131 Bookmarks are pointers to certain commits that move when commit‐
5132 ting. They are similar to tags in that it is possible to use
5133 bookmark names in all places where Mercurial expects a changeset
5134 ID, e.g., with hg update. Unlike tags, bookmarks move along when
5135 you make a commit.
5136 Bookmarks can be renamed, copied and deleted. Bookmarks are lo‐
5138 cal, unless they are explicitly pushed or pulled between reposi‐
5139 tories. Pushing and pulling bookmarks allow you to collaborate
5140 with others on a branch without creating a named branch.
5141 Branch (Noun) A child changeset that has been created from a parent
5143 that is not a head. These are known as topological branches, see
5144 'Branch, topological'. If a topological branch is named, it be‐
5145 comes a named branch. If a topological branch is not named, it
5146 becomes an anonymous branch. See 'Branch, anonymous' and
5147 'Branch, named'.
5148 Branches may be created when changes are pulled from or pushed
5150 to a remote repository, since new heads may be created by these
5151 operations. Note that the term branch can also be used infor‐
5152 mally to describe a development process in which certain devel‐
5153 opment is done independently of other development. This is some‐
5154 times done explicitly with a named branch, but it can also be
5155 done locally, using bookmarks or clones and anonymous branches.
5156 Example: "The experimental branch."
5158 (Verb) The action of creating a child changeset which results in
5160 its parent having more than one child.
5161 Example: "I'm going to branch at X."
5163 Branch, anonymous
5165 Every time a new child changeset is created from a parent that
5166 is not a head and the name of the branch is not changed, a new
5167 anonymous branch is created.
5168 Branch, closed
5170 A named branch whose branch heads have all been closed.
5171 Branch, default
5173 The branch assigned to a changeset when no name has previously
5174 been assigned.
5175 Branch head
5177 See 'Head, branch'.
5178 Branch, inactive
5180 If a named branch has no topological heads, it is considered to
5181 be inactive. As an example, a feature branch becomes inactive
5182 when it is merged into the default branch. The hg branches com‐
5183 mand shows inactive branches by default, though they can be hid‐
5184 den with hg branches --active.
5185 NOTE: this concept is deprecated because it is too implicit.
5187 Branches should now be explicitly closed using hg commit
5188 --close-branch when they are no longer needed.
5189 Branch, named
5191 A collection of changesets which have the same branch name. By
5192 default, children of a changeset in a named branch belong to the
5193 same named branch. A child can be explicitly assigned to a dif‐
5194 ferent branch. See hg help branch, hg help branches and hg com‐
5195 mit --close-branch for more information on managing branches.
5196 Named branches can be thought of as a kind of namespace, divid‐
5198 ing the collection of changesets that comprise the repository
5199 into a collection of disjoint subsets. A named branch is not
5200 necessarily a topological branch. If a new named branch is cre‐
5201 ated from the head of another named branch, or the default
5202 branch, but no further changesets are added to that previous
5203 branch, then that previous branch will be a branch in name only.
5204 Branch tip
5206 See 'Tip, branch'.
5207 Branch, topological
5209 Every time a new child changeset is created from a parent that
5210 is not a head, a new topological branch is created. If a topo‐
5211 logical branch is named, it becomes a named branch. If a topo‐
5212 logical branch is not named, it becomes an anonymous branch of
5213 the current, possibly default, branch.
5214 Changelog
5216 A record of the changesets in the order in which they were added
5217 to the repository. This includes details such as changeset id,
5218 author, commit message, date, and list of changed files.
5219 Changeset
5221 A snapshot of the state of the repository used to record a
5222 change.
5223 Changeset, child
5225 The converse of parent changeset: if P is a parent of C, then C
5226 is a child of P. There is no limit to the number of children
5227 that a changeset may have.
5228 Changeset id
5230 A SHA-1 hash that uniquely identifies a changeset. It may be
5231 represented as either a "long" 40 hexadecimal digit string, or a
5232 "short" 12 hexadecimal digit string.
5233 Changeset, merge
5235 A changeset with two parents. This occurs when a merge is com‐
5236 mitted.
5237 Changeset, parent
5239 A revision upon which a child changeset is based. Specifically,
5240 a parent changeset of a changeset C is a changeset whose node
5241 immediately precedes C in the DAG. Changesets have at most two
5242 parents.
5243 Checkout
5245 (Noun) The working directory being updated to a specific revi‐
5246 sion. This use should probably be avoided where possible, as
5247 changeset is much more appropriate than checkout in this con‐
5248 text.
5249 Example: "I'm using checkout X."
5251 (Verb) Updating the working directory to a specific changeset.
5253 See hg help update.
5254 Example: "I'm going to check out changeset X."
5256 Child changeset
5258 See 'Changeset, child'.
5259 Close changeset
5261 See 'Head, closed branch'.
5262 Closed branch
5264 See 'Branch, closed'.
5265 Clone (Noun) An entire or partial copy of a repository. The partial
5267 clone must be in the form of a revision and its ancestors.
5268 Example: "Is your clone up to date?"
5270 (Verb) The process of creating a clone, using hg clone.
5272 Example: "I'm going to clone the repository."
5274 Closed branch head
5276 See 'Head, closed branch'.
5277 Commit (Noun) A synonym for changeset.
5279 Example: "Is the bug fixed in your recent commit?"
5281 (Verb) The act of recording changes to a repository. When files
5283 are committed in a working directory, Mercurial finds the dif‐
5284 ferences between the committed files and their parent changeset,
5285 creating a new changeset in the repository.
5286 Example: "You should commit those changes now."
5288 Cset A common abbreviation of the term changeset.
5290 DAG The repository of changesets of a distributed version control
5292 system (DVCS) can be described as a directed acyclic graph
5293 (DAG), consisting of nodes and edges, where nodes correspond to
5294 changesets and edges imply a parent -> child relation. This
5295 graph can be visualized by graphical tools such as hg log
5296 --graph. In Mercurial, the DAG is limited by the requirement for
5297 children to have at most two parents.
5298 Deprecated
5300 Feature removed from documentation, but not scheduled for re‐
5301 moval.
5302 Default branch
5304 See 'Branch, default'.
5305 Descendant
5307 Any changeset that can be reached by a chain of child changesets
5308 from a given changeset. More precisely, the descendants of a
5309 changeset can be defined by two properties: the child of a
5310 changeset is a descendant, and the child of a descendant is a
5311 descendant. See also: 'Ancestor'.
5312 Diff (Noun) The difference between the contents and attributes of
5314 files in two changesets or a changeset and the current working
5315 directory. The difference is usually represented in a standard
5316 form called a "diff" or "patch". The "git diff" format is used
5317 when the changes include copies, renames, or changes to file at‐
5318 tributes, none of which can be represented/handled by classic
5319 "diff" and "patch".
5320 Example: "Did you see my correction in the diff?"
5322 (Verb) Diffing two changesets is the action of creating a diff
5324 or patch.
5325 Example: "If you diff with changeset X, you will see what I
5327 mean."
5328 Directory, working
5330 The working directory represents the state of the files tracked
5331 by Mercurial, that will be recorded in the next commit. The
5332 working directory initially corresponds to the snapshot at an
5333 existing changeset, known as the parent of the working direc‐
5334 tory. See 'Parent, working directory'. The state may be modified
5335 by changes to the files introduced manually or by a merge. The
5336 repository metadata exists in the .hg directory inside the work‐
5337 ing directory.
5338 Draft Changesets in the draft phase have not been shared with publish‐
5340 ing repositories and may thus be safely changed by history-modi‐
5341 fying extensions. See hg help phases.
5342 Experimental
5344 Feature that may change or be removed at a later date.
5345 Graph See DAG and hg log --graph.
5347 Head The term 'head' may be used to refer to both a branch head or a
5349 repository head, depending on the context. See 'Head, branch'
5350 and 'Head, repository' for specific definitions.
5351 Heads are where development generally takes place and are the
5353 usual targets for update and merge operations.
5354 Head, branch
5356 A changeset with no descendants on the same named branch.
5357 Head, closed branch
5359 A changeset that marks a head as no longer interesting. The
5360 closed head is no longer listed by hg heads. A branch is consid‐
5361 ered closed when all its heads are closed and consequently is
5362 not listed by hg branches.
5363 Closed heads can be re-opened by committing new changeset as the
5365 child of the changeset that marks a head as closed.
5366 Head, repository
5368 A topological head which has not been closed.
5369 Head, topological
5371 A changeset with no children in the repository.
5372 History, immutable
5374 Once committed, changesets cannot be altered. Extensions which
5375 appear to change history actually create new changesets that re‐
5376 place existing ones, and then destroy the old changesets. Doing
5377 so in public repositories can result in old changesets being
5378 reintroduced to the repository.
5379 History, rewriting
5381 The changesets in a repository are immutable. However, exten‐
5382 sions to Mercurial can be used to alter the repository, usually
5383 in such a way as to preserve changeset contents.
5384 Immutable history
5386 See 'History, immutable'.
5387 Merge changeset
5389 See 'Changeset, merge'.
5390 Manifest
5392 Each changeset has a manifest, which is the list of files that
5393 are tracked by the changeset.
5394 Merge Used to bring together divergent branches of work. When you up‐
5396 date to a changeset and then merge another changeset, you bring
5397 the history of the latter changeset into your working directory.
5398 Once conflicts are resolved (and marked), this merge may be com‐
5399 mitted as a merge changeset, bringing two branches together in
5400 the DAG.
5401 Named branch
5403 See 'Branch, named'.
5404 Null changeset
5406 The empty changeset. It is the parent state of newly-initialized
5407 repositories and repositories with no checked out revision. It
5408 is thus the parent of root changesets and the effective ancestor
5409 when merging unrelated changesets. Can be specified by the alias
5410 'null' or by the changeset ID '000000000000'.
5411 Parent See 'Changeset, parent'.
5413 Parent changeset
5415 See 'Changeset, parent'.
5416 Parent, working directory
5418 The working directory parent reflects a virtual revision which
5419 is the child of the changeset (or two changesets with an uncom‐
5420 mitted merge) shown by hg parents. This is changed with hg up‐
5421 date. Other commands to see the working directory parent are hg
5422 summary and hg id. Can be specified by the alias ".".
5423 Patch (Noun) The product of a diff operation.
5425 Example: "I've sent you my patch."
5427 (Verb) The process of using a patch file to transform one
5429 changeset into another.
5430 Example: "You will need to patch that revision."
5432 Phase A per-changeset state tracking how the changeset has been or
5434 should be shared. See hg help phases.
5435 Public Changesets in the public phase have been shared with publishing
5437 repositories and are therefore considered immutable. See hg help
5438 phases.
5439 Pull An operation in which changesets in a remote repository which
5441 are not in the local repository are brought into the local
5442 repository. Note that this operation without special arguments
5443 only updates the repository, it does not update the files in the
5444 working directory. See hg help pull.
5445 Push An operation in which changesets in a local repository which are
5447 not in a remote repository are sent to the remote repository.
5448 Note that this operation only adds changesets which have been
5449 committed locally to the remote repository. Uncommitted changes
5450 are not sent. See hg help push.
5451 Repository
5453 The metadata describing all recorded states of a collection of
5454 files. Each recorded state is represented by a changeset. A
5455 repository is usually (but not always) found in the .hg subdi‐
5456 rectory of a working directory. Any recorded state can be recre‐
5457 ated by "updating" a working directory to a specific changeset.
5458 Repository head
5460 See 'Head, repository'.
5461 Revision
5463 A state of the repository at some point in time. Earlier revi‐
5464 sions can be updated to by using hg update. See also 'Revision
5465 number'; See also 'Changeset'.
5466 Revision number
5468 This integer uniquely identifies a changeset in a specific
5469 repository. It represents the order in which changesets were
5470 added to a repository, starting with revision number 0. Note
5471 that the revision number may be different in each clone of a
5472 repository. To identify changesets uniquely between different
5473 clones, see 'Changeset id'.
5474 Revlog History storage mechanism used by Mercurial. It is a form of
5476 delta encoding, with occasional full revision of data followed
5477 by delta of each successive revision. It includes data and an
5478 index pointing to the data.
5479 Rewriting history
5481 See 'History, rewriting'.
5482 Root A changeset that has only the null changeset as its parent. Most
5484 repositories have only a single root changeset.
5485 Secret Changesets in the secret phase may not be shared via push, pull,
5487 or clone. See hg help phases.
5488 Tag An alternative name given to a changeset. Tags can be used in
5490 all places where Mercurial expects a changeset ID, e.g., with hg
5491 update. The creation of a tag is stored in the history and will
5492 thus automatically be shared with other using push and pull.
5493 Tip The changeset with the highest revision number. It is the
5495 changeset most recently added in a repository.
5496 Tip, branch
5498 The head of a given branch with the highest revision number.
5499 When a branch name is used as a revision identifier, it refers
5500 to the branch tip. See also 'Branch, head'. Note that because
5501 revision numbers may be different in different repository
5502 clones, the branch tip may be different in different cloned
5503 repositories.
5504 Update (Noun) Another synonym of changeset.
5506 Example: "I've pushed an update."
5508 (Verb) This term is usually used to describe updating the state
5510 of the working directory to that of a specific changeset. See hg
5511 help update.
5512 Example: "You should update."
5514 Working directory
5516 See 'Directory, working'.
5517 Working directory parent
5519 See 'Parent, working directory'.
5520
5522 Synopsis
5523 The Mercurial system uses a file called .hgignore in the root directory
5524 of a repository to control its behavior when it searches for files that
5525 it is not currently tracking.
5526 Description
5528 The working directory of a Mercurial repository will often contain
5529 files that should not be tracked by Mercurial. These include backup
5530 files created by editors and build products created by compilers.
5531 These files can be ignored by listing them in a .hgignore file in the
5532 root of the working directory. The .hgignore file must be created manu‐
5533 ally. It is typically put under version control, so that the settings
5534 will propagate to other repositories with push and pull.
5535 An untracked file is ignored if its path relative to the repository
5537 root directory, or any prefix path of that path, is matched against any
5538 pattern in .hgignore.
5539 For example, say we have an untracked file, file.c, at a/b/file.c in‐
5541 side our repository. Mercurial will ignore file.c if any pattern in
5542 .hgignore matches a/b/file.c, a/b or a.
5543 In addition, a Mercurial configuration file can reference a set of
5545 per-user or global ignore files. See the ignore configuration key on
5546 the [ui] section of hg help config for details of how to configure
5547 these files.
5548 To control Mercurial's handling of files that it manages, many commands
5550 support the -I and -X options; see hg help <command> and hg help pat‐
5551 terns for details.
5552 Files that are already tracked are not affected by .hgignore, even if
5554 they appear in .hgignore. An untracked file X can be explicitly added
5555 with hg add X, even if X would be excluded by a pattern in .hgignore.
5556 Syntax
5558 An ignore file is a plain text file consisting of a list of patterns,
5559 with one pattern per line. Empty lines are skipped. The # character is
5560 treated as a comment character, and the \ character is treated as an
5561 escape character.
5562 Mercurial supports several pattern syntaxes. The default syntax used is
5564 Python/Perl-style regular expressions.
5565 To change the syntax used, use a line of the following form:
5567 syntax: NAME
5569 where NAME is one of the following:
5571 regexp
5573 Regular expression, Python/Perl syntax.
5575 glob
5577 Shell-style glob.
5579 rootglob
5581 A variant of glob that is rooted (see below).
5583 The chosen syntax stays in effect when parsing all patterns that fol‐
5585 low, until another syntax is selected.
5586 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
5588 the form *.c will match a file ending in .c in any directory, and a
5589 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
5590 tern, start it with ^. To get the same effect with glob-syntax, you
5591 have to use rootglob.
5592 Subdirectories can have their own .hgignore settings by adding subin‐
5594 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
5595 terns for details on subinclude: and include:.
5596 Note Patterns specified in other than .hgignore are always rooted.
5598 Please see hg help patterns for details.
5599 Example
5601 Here is an example ignore file.
5602 # use glob syntax.
5604 syntax: glob
5605 *.elc
5607 *.pyc
5608 *~
5609 # switch to regexp syntax.
5611 syntax: regexp
5612 ^\.pc/
5613 Debugging
5615 Use the debugignore command to see if and why a file is ignored, or to
5616 see the combined ignore pattern. See hg help debugignore for details.
5617
5619 Mercurial's internal web server, hgweb, can serve either a single
5620 repository, or a tree of repositories. In the second case, repository
5621 paths and global options can be defined using a dedicated configuration
5622 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
5623 This file uses the same syntax as other Mercurial configuration files
5625 but recognizes only the following sections:
5626 • web
5628 • paths
5630 • collections
5632 The web options are thoroughly described in hg help config.
5634 The paths section maps URL paths to paths of repositories in the
5636 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
5637 rial repositories can be published and only according to the configura‐
5638 tion.
5639 The left hand side is the path in the URL. Note that hgweb reserves
5641 subpaths like rev or file, try using different names for nested reposi‐
5642 tories to avoid confusing effects.
5643 The right hand side is the path in the filesystem. If the specified
5645 path ends with * or ** the filesystem will be searched recursively for
5646 repositories below that point. With * it will not recurse into the
5647 repositories it finds (except for .hg/patches). With ** it will also
5648 search inside repository working directories and possibly find sub‐
5649 repositories.
5650 In this example:
5652 [paths]
5654 /projects/a = /srv/tmprepos/a
5655 /projects/b = c:/repos/b
5656 / = /srv/repos/*
5657 /user/bob = /home/bob/repos/**
5658 • The first two entries make two repositories in different directories
5660 appear under the same directory in the web interface
5661 • The third entry will publish every Mercurial repository found in
5663 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
5664 as http://server/quux/
5665 • The fourth entry will publish both http://server/user/bob/quux/ and
5667 http://server/user/bob/quux/testsubrepo/
5668 The collections section is deprecated and has been superseded by paths.
5670 URLs and Common Arguments
5672 URLs under each repository have the form /{command}[/{arguments}] where
5673 {command} represents the name of a command or handler and {arguments}
5674 represents any number of additional URL parameters to that command.
5675 The web server has a default style associated with it. Styles map to a
5677 collection of named templates. Each template is used to render a spe‐
5678 cific piece of data, such as a changeset or diff.
5679 The style for the current request can be overridden two ways. First, if
5681 {command} contains a hyphen (-), the text before the hyphen defines the
5682 style. For example, /atom-log will render the log command handler with
5683 the atom style. The second way to set the style is with the style query
5684 string argument. For example, /log?style=atom. The hyphenated URL pa‐
5685 rameter is preferred.
5686 Not all templates are available for all styles. Attempting to use a
5688 style that doesn't have all templates defined may result in an error
5689 rendering the page.
5690 Many commands take a {revision} URL parameter. This defines the change‐
5692 set to operate on. This is commonly specified as the short, 12 digit
5693 hexadecimal abbreviation for the full 40 character unique revision
5694 identifier. However, any value described by hg help revisions typically
5695 works.
5696 Commands and URLs
5698 The following web commands and their URLs are available:
5699 /annotate/{revision}/{path}
5701 Show changeset information for each line in a file.
5702 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
5704 string arguments have the same meaning as their [annotate] config
5705 equivalents. It uses the hgrc boolean parsing logic to interpret the
5706 value. e.g. 0 and false are false and 1 and true are true. If not de‐
5707 fined, the server default settings are used.
5708 The fileannotate template is rendered.
5710 /archive/{revision}.{format}[/{path}]
5712 Obtain an archive of repository content.
5713 The content and type of the archive is defined by a URL path parameter.
5715 format is the file extension of the archive type to be generated. e.g.
5716 zip or tar.bz2. Not all archive types may be allowed by your server
5717 configuration.
5718 The optional path URL parameter controls content to include in the ar‐
5720 chive. If omitted, every file in the specified revision is present in
5721 the archive. If included, only the specified file or contents of the
5722 specified directory will be included in the archive.
5723 No template is used for this handler. Raw, binary content is generated.
5725 /bookmarks
5727 Show information about bookmarks.
5728 No arguments are accepted.
5730 The bookmarks template is rendered.
5732 /branches
5734 Show information about branches.
5735 All known branches are contained in the output, even closed branches.
5737 No arguments are accepted.
5739 The branches template is rendered.
5741 /changelog[/{revision}]
5743 Show information about multiple changesets.
5744 If the optional revision URL argument is absent, information about all
5746 changesets starting at tip will be rendered. If the revision argument
5747 is present, changesets will be shown starting from the specified revi‐
5748 sion.
5749 If revision is absent, the rev query string argument may be defined.
5751 This will perform a search for changesets.
5752 The argument for rev can be a single revision, a revision set, or a
5754 literal keyword to search for in changeset data (equivalent to hg log
5755 -k).
5756 The revcount query string argument defines the maximum numbers of
5758 changesets to render.
5759 For non-searches, the changelog template will be rendered.
5761 /changeset[/{revision}]
5763 Show information about a single changeset.
5764 A URL path argument is the changeset identifier to show. See hg help
5766 revisions for possible values. If not defined, the tip changeset will
5767 be shown.
5768 The changeset template is rendered. Contents of the changesettag,
5770 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5771 lated to diffs may all be used to produce the output.
5772 /comparison/{revision}/{path}
5774 Show a comparison between the old and new versions of a file from
5775 changes made on a particular revision.
5776 This is similar to the diff handler. However, this form features a
5778 split or side-by-side diff rather than a unified diff.
5779 The context query string argument can be used to control the lines of
5781 context in the diff.
5782 The filecomparison template is rendered.
5784 /diff/{revision}/{path}
5786 Show how a file changed in a particular commit.
5787 The filediff template is rendered.
5789 This handler is registered under both the /diff and /filediff paths.
5791 /diff is used in modern code.
5792 /file/{revision}[/{path}]
5794 Show information about a directory or file in the repository.
5795 Info about the path given as a URL parameter will be rendered.
5797 If path is a directory, information about the entries in that directory
5799 will be rendered. This form is equivalent to the manifest handler.
5800 If path is a file, information about that file will be shown via the
5802 filerevision template.
5803 If path is not defined, information about the root directory will be
5805 rendered.
5806 /diff/{revision}/{path}
5808 Show how a file changed in a particular commit.
5809 The filediff template is rendered.
5811 This handler is registered under both the /diff and /filediff paths.
5813 /diff is used in modern code.
5814 /filelog/{revision}/{path}
5816 Show information about the history of a file in the repository.
5817 The revcount query string argument can be defined to control the maxi‐
5819 mum number of entries to show.
5820 The filelog template will be rendered.
5822 /graph[/{revision}]
5824 Show information about the graphical topology of the repository.
5825 Information rendered by this handler can be used to create visual rep‐
5827 resentations of repository topology.
5828 The revision URL parameter controls the starting changeset. If it's ab‐
5830 sent, the default is tip.
5831 The revcount query string argument can define the number of changesets
5833 to show information for.
5834 The graphtop query string argument can specify the starting changeset
5836 for producing jsdata variable that is used for rendering graph in Java‐
5837 Script. By default it has the same value as revision.
5838 This handler will render the graph template.
5840 /help[/{topic}]
5842 Render help documentation.
5843 This web command is roughly equivalent to hg help. If a topic is de‐
5845 fined, that help topic will be rendered. If not, an index of available
5846 help topics will be rendered.
5847 The help template will be rendered when requesting help for a topic.
5849 helptopics will be rendered for the index of help topics.
5850 /log[/{revision}[/{path}]]
5852 Show repository or file history.
5853 For URLs of the form /log/{revision}, a list of changesets starting at
5855 the specified changeset identifier is shown. If {revision} is not de‐
5856 fined, the default is tip. This form is equivalent to the changelog
5857 handler.
5858 For URLs of the form /log/{revision}/{file}, the history for a specific
5860 file will be shown. This form is equivalent to the filelog handler.
5861 /manifest[/{revision}[/{path}]]
5863 Show information about a directory.
5864 If the URL path arguments are omitted, information about the root di‐
5866 rectory for the tip changeset will be shown.
5867 Because this handler can only show information for directories, it is
5869 recommended to use the file handler instead, as it can handle both di‐
5870 rectories and files.
5871 The manifest template will be rendered for this handler.
5873 /changeset[/{revision}]
5875 Show information about a single changeset.
5876 A URL path argument is the changeset identifier to show. See hg help
5878 revisions for possible values. If not defined, the tip changeset will
5879 be shown.
5880 The changeset template is rendered. Contents of the changesettag,
5882 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5883 lated to diffs may all be used to produce the output.
5884 /shortlog
5886 Show basic information about a set of changesets.
5887 This accepts the same parameters as the changelog handler. The only
5889 difference is the shortlog template will be rendered instead of the
5890 changelog template.
5891 /summary
5893 Show a summary of repository state.
5894 Information about the latest changesets, bookmarks, tags, and branches
5896 is captured by this handler.
5897 The summary template is rendered.
5899 /tags
5901 Show information about tags.
5902 No arguments are accepted.
5904 The tags template is rendered.
5906
5908 To access a subtopic, use "hg help internals.{subtopic-name}"
5909 bid-merge
5911 Bid Merge Algorithm
5912 bundle2
5914 Bundle2
5915 bundles
5917 Bundles
5918 cbor CBOR
5920 censor Censor
5922 changegroups
5924 Changegroups
5925 config Config Registrar
5927 dirstate-v2
5929 dirstate-v2 file format
5930 extensions
5932 Extension API
5933 mergestate
5935 Mergestate
5936 requirements
5938 Repository Requirements
5939 revlogs
5941 Revision Logs
5942 wireprotocol
5944 Wire Protocol
5945 wireprotocolrpc
5947 Wire Protocol RPC
5948 wireprotocolv2
5950 Wire Protocol Version 2
5951
5953 To merge files Mercurial uses merge tools.
5954 A merge tool combines two different versions of a file into a merged
5956 file. Merge tools are given the two files and the greatest common an‐
5957 cestor of the two file versions, so they can determine the changes made
5958 on both branches.
5959 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
5961 out and in several extensions.
5962 Usually, the merge tool tries to automatically reconcile the files by
5964 combining all non-overlapping changes that occurred separately in the
5965 two different evolutions of the same initial base file. Furthermore,
5966 some interactive merge programs make it easier to manually resolve con‐
5967 flicting merges, either in a graphical way, or by inserting some con‐
5968 flict markers. Mercurial does not include any interactive merge pro‐
5969 grams but relies on external tools for that.
5970 Available merge tools
5972 External merge tools and their properties are configured in the
5973 merge-tools configuration section - see hgrc(5) - but they can often
5974 just be named by their executable.
5975 A merge tool is generally usable if its executable can be found on the
5977 system and if it can handle the merge. The executable is found if it is
5978 an absolute or relative executable path or the name of an application
5979 in the executable search path. The tool is assumed to be able to handle
5980 the merge if it can handle symlinks if the file is a symlink, if it can
5981 handle binary files if the file is binary, and if a GUI is available if
5982 the tool requires a GUI.
5983 There are some internal merge tools which can be used. The internal
5985 merge tools are:
5986 :dump
5988 Creates three versions of the files to merge, containing the
5990 contents of local, other and base. These files can then be used
5991 to perform a merge manually. If the file to be merged is named
5992 a.txt, these files will accordingly be named a.txt.local,
5993 a.txt.other and a.txt.base and they will be placed in the same
5994 directory as a.txt.
5995 This implies premerge. Therefore, files aren't dumped, if pre‐
5997 merge runs successfully. Use :forcedump to forcibly write files
5998 out.
5999 (actual capabilities: binary, symlink)
6001 :fail
6003 Rather than attempting to merge files that were modified on both
6005 branches, it marks them as unresolved. The resolve command must
6006 be used to resolve these conflicts.
6007 (actual capabilities: binary, symlink)
6009 :forcedump
6011 Creates three versions of the files as same as :dump, but omits
6013 premerge.
6014 (actual capabilities: binary, symlink)
6016 :local
6018 Uses the local p1() version of files as the merged version.
6020 (actual capabilities: binary, symlink)
6022 :merge
6024 Uses the internal non-interactive simple merge algorithm for
6026 merging files. It will fail if there are any conflicts and leave
6027 markers in the partially merged file. Markers will have two sec‐
6028 tions, one for each side of merge.
6029 :merge-local
6031 Like :merge, but resolve all conflicts non-interactively in fa‐
6033 vor of the local p1() changes.
6034 :merge-other
6036 Like :merge, but resolve all conflicts non-interactively in fa‐
6038 vor of the other p2() changes.
6039 :merge3
6041 Uses the internal non-interactive simple merge algorithm for
6043 merging files. It will fail if there are any conflicts and leave
6044 markers in the partially merged file. Marker will have three
6045 sections, one from each side of the merge and one for the base
6046 content.
6047 :mergediff
6049 Uses the internal non-interactive simple merge algorithm for
6051 merging files. It will fail if there are any conflicts and leave
6052 markers in the partially merged file. The marker will have two
6053 sections, one with the content from one side of the merge, and
6054 one with a diff from the base content to the content on the
6055 other side. (experimental)
6056 :other
6058 Uses the other p2() version of files as the merged version.
6060 (actual capabilities: binary, symlink)
6062 :prompt
6064 Asks the user which of the local p1() or the other p2() version
6066 to keep as the merged version.
6067 (actual capabilities: binary, symlink)
6069 :tagmerge
6071 Uses the internal tag merge algorithm (experimental).
6073 :union
6075 Uses the internal non-interactive simple merge algorithm for
6077 merging files. It will use both left and right sides for con‐
6078 flict regions. No markers are inserted.
6079 Internal tools are always available and do not require a GUI but will
6081 by default not handle symlinks or binary files. See next section for
6082 detail about "actual capabilities" described above.
6083 Choosing a merge tool
6085 Mercurial uses these rules when deciding which merge tool to use:
6086 1. If a tool has been specified with the --tool option to merge or re‐
6088 solve, it is used. If it is the name of a tool in the merge-tools
6089 configuration, its configuration is used. Otherwise the specified
6090 tool must be executable by the shell.
6091 2. If the HGMERGE environment variable is present, its value is used
6093 and must be executable by the shell.
6094 3. If the filename of the file to be merged matches any of the patterns
6096 in the merge-patterns configuration section, the first usable merge
6097 tool corresponding to a matching pattern is used.
6098 4. If ui.merge is set it will be considered next. If the value is not
6100 the name of a configured tool, the specified value is used and must
6101 be executable by the shell. Otherwise the named tool is used if it
6102 is usable.
6103 5. If any usable merge tools are present in the merge-tools configura‐
6105 tion section, the one with the highest priority is used.
6106 6. If a program named hgmerge can be found on the system, it is used -
6108 but it will by default not be used for symlinks and binary files.
6109 7. If the file to be merged is not binary and is not a symlink, then
6111 internal :merge is used.
6112 8. Otherwise, :prompt is used.
6114 For historical reason, Mercurial treats merge tools as below while ex‐
6116 amining rules above.
6117 ┌───────────┬────────────────┬────────┬─────────┐
6119 │step │ specified via │ binary │ symlink │
6120 ├───────────┼────────────────┼────────┼─────────┤
6121 │ │ --tool │ o/o │ o/o │
6122 │ 1. │ │ │ │
6123 ├───────────┼────────────────┼────────┼─────────┤
6124 │ │ HGMERGE │ o/o │ o/o │
6125 │ 2. │ │ │ │
6126 ├───────────┼────────────────┼────────┼─────────┤
6127 │ │ merge-patterns │ o/o(*) │ x/?(*) │
6128 │ 3. │ │ │ │
6129 ├───────────┼────────────────┼────────┼─────────┤
6130 │ │ ui.merge │ x/?(*) │ x/?(*) │
6131 │ 4. │ │ │ │
6132 └───────────┴────────────────┴────────┴─────────┘
6133 Each capability column indicates Mercurial behavior for internal/exter‐
6135 nal merge tools at examining each rule.
6136 • "o": "assume that a tool has capability"
6138 • "x": "assume that a tool does not have capability"
6140 • "?": "check actual capability of a tool"
6142 If merge.strict-capability-check configuration is true, Mercurial
6144 checks capabilities of merge tools strictly in (*) cases above (= each
6145 capability column becomes "?/?"). It is false by default for backward
6146 compatibility.
6147 Note After selecting a merge program, Mercurial will by default at‐
6149 tempt to merge the files using a simple merge algorithm first.
6150 Only if it doesn't succeed because of conflicting changes will
6151 Mercurial actually execute the merge program. Whether to use the
6152 simple merge algorithm first can be controlled by the premerge
6153 setting of the merge tool. Premerge is enabled by default unless
6154 the file is binary or a symlink.
6155 See the merge-tools and ui sections of hgrc(5) for details on the con‐
6157 figuration of merge tools.
6158
6160 Some Mercurial commands can produce a lot of output, and Mercurial will
6161 attempt to use a pager to make those commands more pleasant.
6162 To set the pager that should be used, set the application variable:
6164 [pager]
6166 pager = less -FRX
6167 If no pager is set in the user or repository configuration, Mercurial
6169 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
6170 from the default or system configuration is used. If none of these are
6171 set, a default pager will be used, typically less on Unix and more on
6172 Windows.
6173 On Windows, more is not color aware, so using it effectively disables
6175 color. MSYS and Cygwin shells provide less as a pager, which can be
6176 configured to support ANSI color codes. See hg help con‐
6177 fig.color.pagermode to configure the color mode when invoking a pager.
6178 You can disable the pager for certain commands by adding them to the
6180 pager.ignore list:
6181 [pager]
6183 ignore = version, help, update
6184 To ignore global commands like hg version or hg help, you have to spec‐
6186 ify them in your user configuration file.
6187 To control whether the pager is used at all for an individual command,
6189 you can use --pager=<value>:
6190 • use as needed: auto.
6192 • require the pager: yes or on.
6194 • suppress the pager: no or off (any unrecognized value will also
6196 work).
6197 To globally turn off all attempts to use a pager, set:
6199 [ui]
6201 paginate = never
6202 which will prevent the pager from running.
6204
6206 Mercurial accepts several notations for identifying one or more files
6207 at a time.
6208 By default, Mercurial treats filenames verbatim without pattern match‐
6210 ing, relative to the current working directory. Note that your system
6211 shell might perform pattern matching of its own before passing file‐
6212 names into Mercurial.
6213 Alternate pattern notations must be specified explicitly.
6215 Note Patterns specified in .hgignore are not rooted. Please see hg
6217 help hgignore for details.
6218 To use a plain path name without any pattern matching, start it with
6220 path:. These path names must completely match starting at the current
6221 repository root, and when the path points to a directory, it is matched
6222 recursively. To match all files in a directory non-recursively (not in‐
6223 cluding any files in subdirectories), rootfilesin: can be used, speci‐
6224 fying an absolute path (relative to the repository root).
6225 To use an extended glob, start a name with glob:. Globs are rooted at
6227 the current directory; a glob such as *.c will only match files in the
6228 current directory ending with .c. rootglob: can be used instead of
6229 glob: for a glob that is rooted at the root of the repository.
6230 The supported glob syntax extensions are ** to match any string across
6232 path separators and {a,b} to mean "a or b".
6233 To use a Perl/Python regular expression, start a name with re:. Regexp
6235 pattern matching is anchored at the root of the repository.
6236 To read name patterns from a file, use listfile: or listfile0:. The
6238 latter expects null delimited patterns while the former expects line
6239 feeds. Each string read from the file is itself treated as a file pat‐
6240 tern.
6241 To read a set of patterns from a file, use include: or subinclude:.
6243 include: will use all the patterns from the given file and treat them
6244 as if they had been passed in manually. subinclude: will only apply
6245 the patterns against files that are under the subinclude file's direc‐
6246 tory. See hg help hgignore for details on the format of these files.
6247 All patterns, except for glob: specified in command line (not for -I or
6249 -X options), can match also against directories: files under matched
6250 directories are treated as matched. For -I and -X options, glob: will
6251 match directories recursively.
6252 Plain examples:
6254 path:foo/bar a name bar in a directory named foo in the root
6256 of the repository
6257 path:path:name a file or directory named "path:name"
6258 rootfilesin:foo/bar the files in a directory called foo/bar, but not any files
6259 in its subdirectories and not a file bar in directory foo
6260 Glob examples:
6262 glob:*.c any name ending in ".c" in the current directory
6264 *.c any name ending in ".c" in the current directory
6265 **.c any name ending in ".c" in any subdirectory of the
6266 current directory including itself.
6267 foo/* any file in directory foo
6268 foo/** any file in directory foo plus all its subdirectories,
6269 recursively
6270 foo/*.c any name ending in ".c" in the directory foo
6271 foo/**.c any name ending in ".c" in any subdirectory of foo
6272 including itself.
6273 rootglob:*.c any name ending in ".c" in the root of the repository
6274 Regexp examples:
6276 re:.*\.c$ any name ending in ".c", anywhere in the repository
6278 File examples:
6280 listfile:list.txt read list from list.txt with one file pattern per line
6282 listfile0:list.txt read list from list.txt with null byte delimiters
6283 See also hg help filesets.
6285 Include examples:
6287 include:path/to/mypatternfile reads patterns to be applied to all paths
6289 subinclude:path/to/subignorefile reads patterns specifically for paths in the
6290 subdirectory
6291
6293 What are phases?
6294 Phases are a system for tracking which changesets have been or should
6295 be shared. This helps prevent common mistakes when modifying history
6296 (for instance, with the mq or rebase extensions).
6297 Each changeset in a repository is in one of the following phases:
6299 • public : changeset is visible on a public server
6301 • draft : changeset is not yet published
6303 • secret : changeset should not be pushed, pulled, or cloned
6305 These phases are ordered (public < draft < secret) and no changeset can
6307 be in a lower phase than its ancestors. For instance, if a changeset is
6308 public, all its ancestors are also public. Lastly, changeset phases
6309 should only be changed towards the public phase.
6310 How are phases managed?
6312 For the most part, phases should work transparently. By default, a
6313 changeset is created in the draft phase and is moved into the public
6314 phase when it is pushed to another repository.
6315 Once changesets become public, extensions like mq and rebase will
6317 refuse to operate on them to prevent creating duplicate changesets.
6318 Phases can also be manually manipulated with the hg phase command if
6319 needed. See hg help -v phase for examples.
6320 To make your commits secret by default, put this in your configuration
6322 file:
6323 [phases]
6325 new-commit = secret
6326 Phases and servers
6328 Normally, all servers are publishing by default. This means:
6329 - all draft changesets that are pulled or cloned appear in phase
6331 public on the client
6332 - all draft changesets that are pushed appear as public on both
6334 client and server
6335 - secret changesets are neither pushed, pulled, or cloned
6337 Note Pulling a draft changeset from a publishing server does not mark
6339 it as public on the server side due to the read-only nature of
6340 pull.
6341 Sometimes it may be desirable to push and pull changesets in the draft
6343 phase to share unfinished work. This can be done by setting a reposi‐
6344 tory to disable publishing in its configuration file:
6345 [phases]
6347 publish = False
6348 See hg help config for more information on configuration files.
6350 Note Servers running older versions of Mercurial are treated as pub‐
6352 lishing.
6353 Note Changesets in secret phase are not exchanged with the server.
6355 This applies to their content: file names, file contents, and
6356 changeset metadata. For technical reasons, the identifier (e.g.
6357 d825e4025e39) of the secret changeset may be communicated to the
6358 server.
6359 Examples
6361 • list changesets in draft or secret phase:
6362 hg log -r "not public()"
6364 • change all secret changesets to draft:
6366 hg phase --draft "secret()"
6368 • forcibly move the current changeset and descendants from public to
6370 draft:
6371 hg phase --force --draft .
6373 • show a list of changeset revisions and each corresponding phase:
6375 hg log --template "{rev} {phase}\n"
6377 • resynchronize draft changesets relative to a remote repository:
6379 hg phase -fd "outgoing(URL)"
6381 See hg help phase for more information on manually manipulating phases.
6383
6385 Mercurial supports several ways to specify revisions.
6386 Specifying single revisions
6388 A plain integer is treated as a revision number. Negative integers are
6389 treated as sequential offsets from the tip, with -1 denoting the tip,
6390 -2 denoting the revision prior to the tip, and so forth.
6391 A 40-digit hexadecimal string is treated as a unique revision identi‐
6393 fier. A hexadecimal string less than 40 characters long is treated as
6394 a unique revision identifier and is referred to as a short-form identi‐
6395 fier. A short-form identifier is only valid if it is the prefix of ex‐
6396 actly one full-length identifier.
6397 Any other string is treated as a bookmark, tag, or branch name. A book‐
6399 mark is a movable pointer to a revision. A tag is a permanent name as‐
6400 sociated with a revision. A branch name denotes the tipmost open branch
6401 head of that branch - or if they are all closed, the tipmost closed
6402 head of the branch. Bookmark, tag, and branch names must not contain
6403 the ":" character.
6404 The reserved name "tip" always identifies the most recent revision.
6406 The reserved name "null" indicates the null revision. This is the revi‐
6408 sion of an empty repository, and the parent of revision 0.
6409 The reserved name "." indicates the working directory parent. If no
6411 working directory is checked out, it is equivalent to null. If an un‐
6412 committed merge is in progress, "." is the revision of the first par‐
6413 ent.
6414 Finally, commands that expect a single revision (like hg update) also
6416 accept revsets (see below for details). When given a revset, they use
6417 the last revision of the revset. A few commands accept two single revi‐
6418 sions (like hg diff). When given a revset, they use the first and the
6419 last revisions of the revset.
6420 Specifying multiple revisions
6422 Mercurial supports a functional language for selecting a set of revi‐
6423 sions. Expressions in this language are called revsets.
6424 The language supports a number of predicates which are joined by infix
6426 operators. Parenthesis can be used for grouping.
6427 Identifiers such as branch names may need quoting with single or double
6429 quotes if they contain characters like - or if they match one of the
6430 predefined predicates.
6431 Special characters can be used in quoted identifiers by escaping them,
6433 e.g., \n is interpreted as a newline. To prevent them from being inter‐
6434 preted, strings can be prefixed with r, e.g. r'...'.
6435 Operators
6437 There is a single prefix operator:
6438 not x
6440 Changesets not in x. Short form is ! x.
6442 These are the supported infix operators:
6444 x::y
6446 A DAG range, meaning all changesets that are descendants of x
6448 and ancestors of y, including x and y themselves. If the first
6449 endpoint is left out, this is equivalent to ancestors(y), if the
6450 second is left out it is equivalent to descendants(x).
6451 An alternative syntax is x..y.
6453 x:y
6455 All changesets with revision numbers between x and y, both in‐
6457 clusive. Either endpoint can be left out, they default to 0 and
6458 tip.
6459 x and y
6461 The intersection of changesets in x and y. Short form is x & y.
6463 x or y
6465 The union of changesets in x and y. There are two alternative
6467 short forms: x | y and x + y.
6468 x - y
6470 Changesets in x but not in y.
6472 x % y
6474 Changesets that are ancestors of x but not ancestors of y (i.e.
6476 ::x - ::y). This is shorthand notation for only(x, y) (see be‐
6477 low). The second argument is optional and, if left out, is
6478 equivalent to only(x).
6479 x^n
6481 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
6483 1, the first parent of each changeset in x; for n == 2, the sec‐
6484 ond parent of changeset in x.
6485 x~n
6487 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
6489 the nth unambiguous descendent of x.
6490 x ## y
6492 Concatenate strings and identifiers into one string.
6494 All other prefix, infix and postfix operators have lower prior‐
6496 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
6497 a2)~2.
6498 For example:
6500 [revsetalias]
6502 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
6503 issue(1234) is equivalent to grep(r'\bissue[
6505 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
6506 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
6507 There is a single postfix operator:
6509 x^
6511 Equivalent to x^1, the first parent of each changeset in x.
6513 Patterns
6515 Where noted, predicates that perform string matching can accept a pat‐
6516 tern string. The pattern may be either a literal, or a regular expres‐
6517 sion. If the pattern starts with re:, the remainder of the pattern is
6518 treated as a regular expression. Otherwise, it is treated as a literal.
6519 To match a pattern that actually starts with re:, use the prefix lit‐
6520 eral:.
6521 Matching is case-sensitive, unless otherwise noted. To perform a case-
6523 insensitive match on a case-sensitive predicate, use a regular expres‐
6524 sion, prefixed with (?i).
6525 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
6527 "Release", etc.
6528 Predicates
6530 The following predicates are supported:
6531 adds(pattern)
6533 Changesets that add a file matching pattern.
6535 The pattern without explicit kind like glob: is expected to be
6537 relative to the current directory and match against a file or a
6538 directory.
6539 all()
6541 All changesets, the same as 0:tip.
6543 ancestor(*changeset)
6545 A greatest common ancestor of the changesets.
6547 Accepts 0 or more changesets. Will return empty list when
6549 passed no args. Greatest common ancestor of a single changeset
6550 is that changeset.
6551 ancestors(set[, depth])
6553 Changesets that are ancestors of changesets in set, including
6555 the given changesets themselves.
6556 If depth is specified, the result only includes changesets up to
6558 the specified generation.
6559 author(string)
6561 Alias for user(string).
6563 bisect(string)
6565 Changesets marked in the specified bisect status:
6567 • good, bad, skip: csets explicitly marked as good/bad/skip
6569 • goods, bads : csets topologically good/bad
6571 • range : csets taking part in the bisection
6573 • pruned : csets that are goods, bads or skipped
6575 • untested : csets whose fate is yet unknown
6577 • ignored : csets ignored due to DAG topology
6579 • current : the cset currently being bisected
6581 bookmark([name])
6583 The named bookmark or all bookmarks.
6585 Pattern matching is supported for name. See hg help revi‐
6587 sions.patterns.
6588 branch(string or set)
6590 All changesets belonging to the given branch or the branches of
6592 the given changesets.
6593 Pattern matching is supported for string. See hg help revi‐
6595 sions.patterns.
6596 branchpoint()
6598 Changesets with more than one child.
6600 bundle()
6602 Changesets in the bundle.
6604 Bundle must be specified by the -R option.
6606 children(set)
6608 Child changesets of changesets in set.
6610 closed()
6612 Changeset is closed.
6614 commonancestors(set)
6616 Changesets that are ancestors of every changeset in set.
6618 conflictlocal()
6620 The local side of the merge, if currently in an unresolved
6622 merge.
6623 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6625 'hg graft'.
6626 conflictother()
6628 The other side of the merge, if currently in an unresolved
6630 merge.
6631 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6633 'hg graft'.
6634 contains(pattern)
6636 The revision's manifest contains a file matching pattern (but
6638 might not modify it). See hg help patterns for information about
6639 file patterns.
6640 The pattern without explicit kind like glob: is expected to be
6642 relative to the current directory and match against a file ex‐
6643 actly for efficiency.
6644 converted([id])
6646 Changesets converted from the given identifier in the old repos‐
6648 itory if present, or all converted changesets if no identifier
6649 is specified.
6650 date(interval)
6652 Changesets within the interval, see hg help dates.
6654 desc(string)
6656 Search commit message for string. The match is case-insensitive.
6658 Pattern matching is supported for string. See hg help revi‐
6660 sions.patterns.
6661 descendants(set[, depth])
6663 Changesets which are descendants of changesets in set, including
6665 the given changesets themselves.
6666 If depth is specified, the result only includes changesets up to
6668 the specified generation.
6669 destination([set])
6671 Changesets that were created by a graft, transplant or rebase
6673 operation, with the given revisions specified as the source.
6674 Omitting the optional set is the same as passing all().
6675 diffcontains(pattern)
6677 Search revision differences for when the pattern was added or
6679 removed.
6680 The pattern may be a substring literal or a regular expression.
6682 See hg help revisions.patterns.
6683 draft()
6685 Changeset in draft phase.
6687 expectsize(set[, size])
6689 Return the given revset if size matches the revset size. Abort
6691 if the revset doesn't expect given size. size can either be an
6692 integer range or an integer.
6693 For example, expectsize(0:1, 3:5) will abort as revset size is 2
6695 and 2 is not between 3 and 5 inclusive.
6696 extra(label, [value])
6698 Changesets with the given label in the extra metadata, with the
6700 given optional value.
6701 Pattern matching is supported for value. See hg help revi‐
6703 sions.patterns.
6704 file(pattern)
6706 Changesets affecting files matched by pattern.
6708 For a faster but less accurate result, consider using filelog()
6710 instead.
6711 This predicate uses glob: as the default kind of pattern.
6713 filelog(pattern)
6715 Changesets connected to the specified filelog.
6717 For performance reasons, visits only revisions mentioned in the
6719 file-level filelog, rather than filtering through all changesets
6720 (much faster, but doesn't include deletes or duplicate changes).
6721 For a slower, more accurate result, use file().
6722 The pattern without explicit kind like glob: is expected to be
6724 relative to the current directory and match against a file ex‐
6725 actly for efficiency.
6726 first(set, [n])
6728 An alias for limit().
6730 follow([file[, startrev]])
6732 An alias for ::. (ancestors of the working directory's first
6734 parent). If file pattern is specified, the histories of files
6735 matching given pattern in the revision given by startrev are
6736 followed, including copies.
6737 followlines(file, fromline:toline[, startrev=., descend=False])
6739 Changesets modifying file in line range ('fromline', 'toline').
6741 Line range corresponds to 'file' content at 'startrev' and
6743 should hence be consistent with file size. If startrev is not
6744 specified, working directory's parent is used.
6745 By default, ancestors of 'startrev' are returned. If 'descend'
6747 is True, descendants of 'startrev' are returned though renames
6748 are (currently) not followed in this direction.
6749 grep(regex)
6751 Like keyword(string) but accepts a regex. Use grep(r'...') to
6753 ensure special escape characters are handled correctly. Unlike
6754 keyword(string), the match is case-sensitive.
6755 head()
6757 Changeset is a named branch head.
6759 heads(set)
6761 Members of set with no children in set.
6763 hidden()
6765 Hidden changesets.
6767 id(string)
6769 Revision non-ambiguously specified by the given hex string pre‐
6771 fix.
6772 keyword(string)
6774 Search commit message, user name, and names of changed files for
6776 string. The match is case-insensitive.
6777 For a regular expression or case sensitive search of these
6779 fields, use grep(regex).
6780 last(set, [n])
6782 Last n members of set, defaulting to 1.
6784 limit(set[, n[, offset]])
6786 First n members of set, defaulting to 1, starting from offset.
6788 matching(revision [, field])
6790 Changesets in which a given set of fields match the set of
6792 fields in the selected revision or set.
6793 To match more than one field pass the list of fields to match
6795 separated by spaces (e.g. author description).
6796 Valid fields are most regular revision fields and some special
6798 fields.
6799 Regular revision fields are description, author, branch, date,
6801 files, phase, parents, substate, user and diff. Note that au‐
6802 thor and user are synonyms. diff refers to the contents of the
6803 revision. Two revisions matching their diff will also match
6804 their files.
6805 Special fields are summary and metadata: summary matches the
6807 first line of the description. metadata is equivalent to match‐
6808 ing description user date (i.e. it matches the main metadata
6809 fields).
6810 metadata is the default field which is used when no fields are
6812 specified. You can match more than one field at a time.
6813 max(set)
6815 Changeset with highest revision number in set.
6817 merge()
6819 Changeset is a merge changeset.
6821 min(set)
6823 Changeset with lowest revision number in set.
6825 modifies(pattern)
6827 Changesets modifying files matched by pattern.
6829 The pattern without explicit kind like glob: is expected to be
6831 relative to the current directory and match against a file or a
6832 directory.
6833 named(namespace)
6835 The changesets in a given namespace.
6837 Pattern matching is supported for namespace. See hg help revi‐
6839 sions.patterns.
6840 nodefromfile(path)
6842 Read a list of nodes from the file at path.
6844 This applies id(LINE) to each line of the file.
6846 This is useful when the amount of nodes you need to specify gets
6848 too large for the command line.
6849 none()
6851 No changesets.
6853 only(set, [set])
6855 Changesets that are ancestors of the first set that are not an‐
6857 cestors of any other head in the repo. If a second set is speci‐
6858 fied, the result is ancestors of the first set that are not an‐
6859 cestors of the second set (i.e. ::<set1> - ::<set2>).
6860 origin([set])
6862 Changesets that were specified as a source for the grafts,
6864 transplants or rebases that created the given revisions. Omit‐
6865 ting the optional set is the same as passing all(). If a
6866 changeset created by these operations is itself specified as a
6867 source for one of these operations, only the source changeset
6868 for the first operation is selected.
6869 outgoing([path])
6871 Changesets not found in the specified destination repository, or
6873 the default push location.
6874 If the location resolve to multiple repositories, the union of
6876 all outgoing changeset will be used.
6877 p1([set])
6879 First parent of changesets in set, or the working directory.
6881 p2([set])
6883 Second parent of changesets in set, or the working directory.
6885 parents([set])
6887 The set of all parents for all changesets in set, or the working
6889 directory.
6890 present(set)
6892 An empty set, if any revision in set isn't found; otherwise, all
6894 revisions in set.
6895 If any of specified revisions is not present in the local repos‐
6897 itory, the query is normally aborted. But this predicate allows
6898 the query to continue even in such cases.
6899 public()
6901 Changeset in public phase.
6903 remote([id [,path]])
6905 Local revision that corresponds to the given identifier in a re‐
6907 mote repository, if present. Here, the '.' identifier is a syn‐
6908 onym for the current local branch.
6909 removes(pattern)
6911 Changesets which remove files matching pattern.
6913 The pattern without explicit kind like glob: is expected to be
6915 relative to the current directory and match against a file or a
6916 directory.
6917 rev(number)
6919 Revision with the given numeric identifier.
6921 reverse(set)
6923 Reverse order of set.
6925 revset(set)
6927 Strictly interpret the content as a revset.
6929 The content of this special predicate will be strictly inter‐
6931 preted as a revset. For example, revset(id(0)) will be inter‐
6932 preted as "id(0)" without possible ambiguity with a "id(0)"
6933 bookmark or tag.
6934 roots(set)
6936 Changesets in set with no parent changeset in set.
6938 secret()
6940 Changeset in secret phase.
6942 sort(set[, [-]key... [, ...]])
6944 Sort set by keys. The default sort order is ascending, specify a
6946 key as -key to sort in descending order.
6947 The keys can be:
6949 • rev for the revision number,
6951 • branch for the branch name,
6953 • desc for the commit message (description),
6955 • user for user name (author can be used as an alias),
6957 • date for the commit date
6959 • topo for a reverse topographical sort
6961 • node the nodeid of the revision
6963 The topo sort order cannot be combined with other sort keys.
6965 This sort takes one optional argument, topo.firstbranch, which
6966 takes a revset that specifies what topographical branches to
6967 prioritize in the sort.
6968 subrepo([pattern])
6970 Changesets that add, modify or remove the given subrepo. If no
6972 subrepo pattern is named, any subrepo changes are returned.
6973 tag([name])
6975 The specified tag by name, or all tagged revisions if no name is
6977 given.
6978 Pattern matching is supported for name. See hg help revi‐
6980 sions.patterns.
6981 user(string)
6983 User name contains string. The match is case-insensitive.
6985 Pattern matching is supported for string. See hg help revi‐
6987 sions.patterns.
6988 Aliases
6990 New predicates (known as "aliases") can be defined, using any combina‐
6991 tion of existing predicates or other aliases. An alias definition looks
6992 like:
6993 <alias> = <definition>
6995 in the revsetalias section of a Mercurial configuration file. Arguments
6997 of the form a1, a2, etc. are substituted from the alias into the defi‐
6998 nition.
6999 For example,
7001 [revsetalias]
7003 h = heads()
7004 d(s) = sort(s, date)
7005 rs(s, k) = reverse(sort(s, k))
7006 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
7008 equivalent to reverse(sort(0:tip, author)).
7009 Equivalents
7011 Command line equivalents for hg log:
7012 -f -> ::.
7014 -d x -> date(x)
7015 -k x -> keyword(x)
7016 -m -> merge()
7017 -u x -> user(x)
7018 -b x -> branch(x)
7019 -P x -> !::x
7020 -l x -> limit(expr, x)
7021 Examples
7023 Some sample queries:
7024 • Changesets on the default branch:
7026 hg log -r "branch(default)"
7028 • Changesets on the default branch since tag 1.5 (excluding merges):
7030 hg log -r "branch(default) and 1.5:: and not merge()"
7032 • Open branch heads:
7034 hg log -r "head() and not closed()"
7036 • Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
7038 hgext/*:
7039 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
7041 • Changesets committed in May 2008, sorted by user:
7043 hg log -r "sort(date('May 2008'), user)"
7045 • Changesets mentioning "bug" or "issue" that are not in a tagged re‐
7047 lease:
7048 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
7050 • Update to the commit that bookmark @ is pointing to, without activat‐
7052 ing the bookmark (this works because the last revision of the revset
7053 is used):
7054 hg update :@
7056 • Show diff between tags 1.3 and 1.5 (this works because the first and
7058 the last revisions of the revset are used):
7059 hg diff -r 1.3::1.5
7061
7063 Mercurial can be augmented with Rust extensions for speeding up certain
7064 operations.
7065 Compatibility
7067 Though the Rust extensions are only tested by the project under Linux,
7068 users of MacOS, FreeBSD and other UNIX-likes have been using the Rust
7069 extensions. Your mileage may vary, but by all means do give us feedback
7070 or signal your interest for better support.
7071 No Rust extensions are available for Windows at this time.
7073 Features
7075 The following operations are sped up when using Rust:
7076 • discovery of differences between repositories (pull/push)
7078 • nodemap (see hg help config.format.use-persistent-nodemap)
7080 • all commands using the dirstate (status, commit, diff, add, up‐
7082 date, etc.)
7083 • dirstate-v2 (see hg help config.format.use-dirstate-v2)
7085 • iteration over ancestors in a graph
7087 More features are in the works, and improvements on the above listed
7089 are still in progress. For more experimental work see the "rhg" sec‐
7090 tion.
7091 Checking for Rust
7093 You may already have the Rust extensions depending on how you install
7094 Mercurial:
7095 $ hg debuginstall | grep -i rust
7097 checking Rust extensions (installed)
7098 checking module policy (rust+c-allow)
7099 If those lines don't even exist, you're using an old version of hg
7101 which does not have any Rust extensions yet.
7102 Installing
7104 You will need cargo to be in your $PATH. See the "MSRV" section for
7105 which version to use.
7106 Using pip
7108 Users of pip can install the Rust extensions with the following com‐
7109 mand:
7110 $ pip install mercurial --global-option --rust --no-use-pep517
7112 --no-use-pep517 is here to tell pip to preserve backwards compatibility
7114 with the legacy setup.py system. Mercurial has not yet migrated its
7115 complex setup to the new system, so we still need this to add compiled
7116 extensions.
7117 This might take a couple of minutes because you're compiling every‐
7119 thing.
7120 See the "Checking for Rust" section to see if the install succeeded.
7122 From your distribution
7124 Some distributions are shipping Mercurial with Rust extensions enabled
7125 and pre-compiled (meaning you won't have to install cargo), or allow
7126 you to specify an install flag. Check with your specific distribution
7127 for how to do that, or ask their team to add support for hg+Rust!
7128 From source
7130 Please refer to the rust/README.rst file in the Mercurial repository
7131 for instructions on how to install from source.
7132 MSRV
7134 The minimum supported Rust version is currently 1.48.0. The project's
7135 policy is to follow the version from Debian stable, to make the distri‐
7136 butions' job easier.
7137 rhg
7139 There exists an experimental pure-Rust version of Mercurial called rhg
7140 with a fallback mechanism for unsupported invocations. It allows for
7141 much faster execution of certain commands while adding no discernable
7142 overhead for the rest.
7143 The only way of trying it out is by building it from source. Please re‐
7145 fer to rust/README.rst in the Mercurial repository.
7146 Contributing
7148 If you would like to help the Rust endeavor, please refer to
7149 rust/README.rst in the Mercurial repository.
7150
7152 It is common for machines (as opposed to humans) to consume Mercurial.
7153 This help topic describes some of the considerations for interfacing
7154 machines with Mercurial.
7155 Choosing an Interface
7157 Machines have a choice of several methods to interface with Mercurial.
7158 These include:
7159 • Executing the hg process
7161 • Querying a HTTP server
7163 • Calling out to a command server
7165 Executing hg processes is very similar to how humans interact with Mer‐
7167 curial in the shell. It should already be familiar to you.
7168 hg serve can be used to start a server. By default, this will start a
7170 "hgweb" HTTP server. This HTTP server has support for machine-readable
7171 output, such as JSON. For more, see hg help hgweb.
7172 hg serve can also start a "command server." Clients can connect to this
7174 server and issue Mercurial commands over a special protocol. For more
7175 details on the command server, including links to client libraries, see
7176 https://www.mercurial-scm.org/wiki/CommandServer.
7177 hg serve based interfaces (the hgweb and command servers) have the ad‐
7179 vantage over simple hg process invocations in that they are likely more
7180 efficient. This is because there is significant overhead to spawn new
7181 Python processes.
7182 Tip If you need to invoke several hg processes in short order and/or
7184 performance is important to you, use of a server-based interface
7185 is highly recommended.
7186 Environment Variables
7188 As documented in hg help environment, various environment variables in‐
7189 fluence the operation of Mercurial. The following are particularly rel‐
7190 evant for machines consuming Mercurial:
7191 HGPLAIN
7193 If not set, Mercurial's output could be influenced by configura‐
7194 tion settings that impact its encoding, verbose mode, localiza‐
7195 tion, etc.
7196 It is highly recommended for machines to set this variable when
7198 invoking hg processes.
7199 HGENCODING
7201 If not set, the locale used by Mercurial will be detected from
7202 the environment. If the determined locale does not support dis‐
7203 play of certain characters, Mercurial may render these character
7204 sequences incorrectly (often by using "?" as a placeholder for
7205 invalid characters in the current locale).
7206 Explicitly setting this environment variable is a good practice
7208 to guarantee consistent results. "utf-8" is a good choice on
7209 UNIX-like environments.
7210 HGRCPATH
7212 If not set, Mercurial will inherit config options from config
7213 files using the process described in hg help config. This in‐
7214 cludes inheriting user or system-wide config files.
7215 When utmost control over the Mercurial configuration is desired,
7217 the value of HGRCPATH can be set to an explicit file with known
7218 good configs. In rare cases, the value can be set to an empty
7219 file or the null device (often /dev/null) to bypass loading of
7220 any user or system config files. Note that these approaches can
7221 have unintended consequences, as the user and system config
7222 files often define things like the username and extensions that
7223 may be required to interface with a repository.
7224 HGRCSKIPREPO
7226 When set, the .hg/hgrc from repositories are not read.
7227 Note that not reading the repository's configuration can have
7229 unintended consequences, as the repository config files can de‐
7230 fine things like extensions that are required for access to the
7231 repository.
7232 Command-line Flags
7234 Mercurial's default command-line parser is designed for humans, and is
7235 not robust against malicious input. For instance, you can start a de‐
7236 bugger by passing --debugger as an option value:
7237 $ REV=--debugger sh -c 'hg log -r "$REV"'
7239 This happens because several command-line flags need to be scanned
7241 without using a concrete command table, which may be modified while
7242 loading repository settings and extensions.
7243 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
7245 setting HGPLAIN=+strictflags. When this feature is enabled, all early
7246 options (e.g. -R/--repository, --cwd, --config) must be specified first
7247 amongst the other global options, and cannot be injected to an arbi‐
7248 trary location:
7249 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
7251 In earlier Mercurial versions where +strictflags isn't available, you
7253 can mitigate the issue by concatenating an option value with its flag:
7254 $ hg log -r"$REV" --keyword="$KEYWORD"
7256 Consuming Command Output
7258 It is common for machines to need to parse the output of Mercurial com‐
7259 mands for relevant data. This section describes the various techniques
7260 for doing so.
7261 Parsing Raw Command Output
7263 Likely the simplest and most effective solution for consuming command
7264 output is to simply invoke hg commands as you would as a user and parse
7265 their output.
7266 The output of many commands can easily be parsed with tools like grep,
7268 sed, and awk.
7269 A potential downside with parsing command output is that the output of
7271 commands can change when Mercurial is upgraded. While Mercurial does
7272 generally strive for strong backwards compatibility, command output
7273 does occasionally change. Having tests for your automated interactions
7274 with hg commands is generally recommended, but is even more important
7275 when raw command output parsing is involved.
7276 Using Templates to Control Output
7278 Many hg commands support templatized output via the -T/--template argu‐
7279 ment. For more, see hg help templates.
7280 Templates are useful for explicitly controlling output so that you get
7282 exactly the data you want formatted how you want it. For example, log
7283 -T {node}\n can be used to print a newline delimited list of changeset
7284 nodes instead of a human-tailored output containing authors, dates, de‐
7285 scriptions, etc.
7286 Tip If parsing raw command output is too complicated, consider using
7288 templates to make your life easier.
7289 The -T/--template argument allows specifying pre-defined styles. Mer‐
7291 curial ships with the machine-readable styles cbor, json, and xml,
7292 which provide CBOR, JSON, and XML output, respectively. These are use‐
7293 ful for producing output that is machine readable as-is.
7294 (Mercurial 5.0 is required for CBOR style.)
7296 Important
7298 The json and xml styles are considered experimental. While they
7299 may be attractive to use for easily obtaining machine-readable
7300 output, their behavior may change in subsequent versions.
7301 These styles may also exhibit unexpected results when dealing
7303 with certain encodings. Mercurial treats things like filenames
7304 as a series of bytes and normalizing certain byte sequences to
7305 JSON or XML with certain encoding settings can lead to sur‐
7306 prises.
7307 Command Server Output
7309 If using the command server to interact with Mercurial, you are likely
7310 using an existing library/API that abstracts implementation details of
7311 the command server. If so, this interface layer may perform parsing for
7312 you, saving you the work of implementing it yourself.
7313 Output Verbosity
7315 Commands often have varying output verbosity, even when machine read‐
7316 able styles are being used (e.g. -T json). Adding -v/--verbose and
7317 --debug to the command's arguments can increase the amount of data ex‐
7318 posed by Mercurial.
7319 An alternate way to get the data you need is by explicitly specifying a
7321 template.
7322 Other Topics
7324 revsets
7325 Revisions sets is a functional query language for selecting a
7326 set of revisions. Think of it as SQL for Mercurial repositories.
7327 Revsets are useful for querying repositories for specific data.
7328 See hg help revsets for more.
7330 share extension
7332 The share extension provides functionality for sharing reposi‐
7333 tory data across several working copies. It can even automati‐
7334 cally "pool" storage for logically related repositories when
7335 cloning.
7336 Configuring the share extension can lead to significant resource
7338 utilization reduction, particularly around disk space and the
7339 network. This is especially true for continuous integration (CI)
7340 environments.
7341 See hg help -e share for more.
7343
7345 Subrepositories let you nest external repositories or projects into a
7346 parent Mercurial repository, and make commands operate on them as a
7347 group.
7348 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
7350 tories.
7351 Subrepositories are made of three components:
7353 1. Nested repository checkouts. They can appear anywhere in the parent
7355 working directory.
7356 2. Nested repository references. They are defined in .hgsub, which
7358 should be placed in the root of working directory, and tell where
7359 the subrepository checkouts come from. Mercurial subrepositories are
7360 referenced like:
7361 path/to/nested = https://example.com/nested/repo/path
7363 Git and Subversion subrepos are also supported:
7365 path/to/nested = [git]git://example.com/nested/repo/path
7367 path/to/nested = [svn]https://example.com/nested/trunk/path
7368 where path/to/nested is the checkout location relatively to the par‐
7370 ent Mercurial root, and https://example.com/nested/repo/path is the
7371 source repository path. The source can also reference a filesystem
7372 path.
7373 Note that .hgsub does not exist by default in Mercurial reposito‐
7375 ries, you have to create and add it to the parent repository before
7376 using subrepositories.
7377 3. Nested repository states. They are defined in .hgsubstate, which is
7379 placed in the root of working directory, and capture whatever infor‐
7380 mation is required to restore the subrepositories to the state they
7381 were committed in a parent repository changeset. Mercurial automati‐
7382 cally record the nested repositories states when committing in the
7383 parent repository.
7384 Note
7386 The .hgsubstate file should not be edited manually.
7387 Adding a Subrepository
7389 If .hgsub does not exist, create it and add it to the parent reposi‐
7390 tory. Clone or checkout the external projects where you want it to live
7391 in the parent repository. Edit .hgsub and add the subrepository entry
7392 as described above. At this point, the subrepository is tracked and the
7393 next commit will record its state in .hgsubstate and bind it to the
7394 committed changeset.
7395 Synchronizing a Subrepository
7397 Subrepos do not automatically track the latest changeset of their
7398 sources. Instead, they are updated to the changeset that corresponds
7399 with the changeset checked out in the top-level changeset. This is so
7400 developers always get a consistent set of compatible code and libraries
7401 when they update.
7402 Thus, updating subrepos is a manual process. Simply check out target
7404 subrepo at the desired revision, test in the top-level repo, then com‐
7405 mit in the parent repository to record the new combination.
7406 Deleting a Subrepository
7408 To remove a subrepository from the parent repository, delete its refer‐
7409 ence from .hgsub, then remove its files.
7410 Interaction with Mercurial Commands
7412 add add does not recurse in subrepos unless -S/--subrepos is speci‐
7413 fied. However, if you specify the full path of a file in a sub‐
7414 repo, it will be added even without -S/--subrepos specified.
7415 Subversion subrepositories are currently silently ignored.
7416 addremove
7418 addremove does not recurse into subrepos unless -S/--subrepos is
7419 specified. However, if you specify the full path of a directory
7420 in a subrepo, addremove will be performed on it even without
7421 -S/--subrepos being specified. Git and Subversion subreposito‐
7422 ries will print a warning and continue.
7423 archive
7425 archive does not recurse in subrepositories unless -S/--subrepos
7426 is specified.
7427 cat Git subrepositories only support exact file matches. Subversion
7429 subrepositories are currently ignored.
7430 commit commit creates a consistent snapshot of the state of the entire
7432 project and its subrepositories. If any subrepositories have
7433 been modified, Mercurial will abort. Mercurial can be made to
7434 instead commit all modified subrepositories by specifying
7435 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
7436 ration file (see hg help config). After there are no longer any
7437 modified subrepositories, it records their state and finally
7438 commits it in the parent repository. The --addremove option
7439 also honors the -S/--subrepos option. However, Git and Subver‐
7440 sion subrepositories will print a warning and abort.
7441 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
7443 fied. However, if you specify the full path of a file or direc‐
7444 tory in a subrepo, it will be diffed even without -S/--subrepos
7445 being specified. Subversion subrepositories are currently
7446 silently ignored.
7447 files files does not recurse into subrepos unless -S/--subrepos is
7449 specified. However, if you specify the full path of a file or
7450 directory in a subrepo, it will be displayed even without
7451 -S/--subrepos being specified. Git and Subversion subreposito‐
7452 ries are currently silently ignored.
7453 forget forget currently only handles exact file matches in subrepos.
7455 Git and Subversion subrepositories are currently silently ig‐
7456 nored.
7457 incoming
7459 incoming does not recurse in subrepos unless -S/--subrepos is
7460 specified. Git and Subversion subrepositories are currently
7461 silently ignored.
7462 outgoing
7464 outgoing does not recurse in subrepos unless -S/--subrepos is
7465 specified. Git and Subversion subrepositories are currently
7466 silently ignored.
7467 pull pull is not recursive since it is not clear what to pull prior
7469 to running hg update. Listing and retrieving all subrepositories
7470 changes referenced by the parent repository pulled changesets is
7471 expensive at best, impossible in the Subversion case.
7472 push Mercurial will automatically push all subrepositories first when
7474 the parent repository is being pushed. This ensures new sub‐
7475 repository changes are available when referenced by top-level
7476 repositories. Push is a no-op for Subversion subrepositories.
7477 serve serve does not recurse into subrepositories unless -S/--subrepos
7479 is specified. Git and Subversion subrepositories are currently
7480 silently ignored.
7481 status status does not recurse into subrepositories unless -S/--subre‐
7483 pos is specified. Subrepository changes are displayed as regular
7484 Mercurial changes on the subrepository elements. Subversion sub‐
7485 repositories are currently silently ignored.
7486 remove remove does not recurse into subrepositories unless -S/--subre‐
7488 pos is specified. However, if you specify a file or directory
7489 path in a subrepo, it will be removed even without -S/--subre‐
7490 pos. Git and Subversion subrepositories are currently silently
7491 ignored.
7492 update update restores the subrepos in the state they were originally
7494 committed in target changeset. If the recorded changeset is not
7495 available in the current subrepository, Mercurial will pull it
7496 in first before updating. This means that updating can require
7497 network access when using subrepositories.
7498 Remapping Subrepositories Sources
7500 A subrepository source location may change during a project life, in‐
7501 validating references stored in the parent repository history. To fix
7502 this, rewriting rules can be defined in parent repository hgrc file or
7503 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
7504 more details.
7505
7507 Mercurial allows you to customize output of commands through templates.
7508 You can either pass in a template or select an existing template-style
7509 from the command line, via the --template option.
7510 You can customize output for any "log-like" command: log, outgoing, in‐
7512 coming, tip, parents, and heads.
7513 Some built-in styles are packaged with Mercurial. These can be listed
7515 with hg log --template list. Example usage:
7516 $ hg log -r1.0::1.1 --template changelog
7518 A template is a piece of text, with markup to invoke variable expan‐
7520 sion:
7521 $ hg log -r1 --template "{node}\n"
7523 b56ce7b07c52de7d5fd79fb89701ea538af65746
7524 Keywords
7526 Strings in curly braces are called keywords. The availability of key‐
7527 words depends on the exact context of the templater. These keywords are
7528 usually available for templating a log-like command:
7529 _fast_rank
7531 the rank of a changeset if cached
7532 The rank of a revision is the size of the sub-graph it defines
7534 as a head. Equivalently, the rank of a revision r is the size
7535 of the set ancestors(r), r included.
7536 activebookmark
7538 String. The active bookmark, if it is associated with the
7539 changeset.
7540 author Alias for {user}
7542 bisect String. The changeset bisection status.
7544 bookmarks
7546 List of strings. Any bookmarks associated with the changeset.
7547 Also sets 'active', the name of the active bookmark.
7548 branch String. The name of the branch on which the changeset was com‐
7550 mitted.
7551 changessincelatesttag
7553 Integer. All ancestors not in the latest tag.
7554 children
7556 List of strings. The children of the changeset.
7557 date Date information. The date when the changeset was committed.
7559 desc String. The text of the changeset description.
7561 diffstat
7563 String. Statistics of changes with the following format: "modi‐
7564 fied files: +added/-removed lines"
7565 extras List of dicts with key, value entries of the 'extras' field of
7567 this changeset.
7568 file_adds
7570 List of strings. Files added by this changeset.
7571 file_copies
7573 List of strings. Files copied in this changeset with their
7574 sources.
7575 file_copies_switch
7577 List of strings. Like "file_copies" but displayed only if the
7578 --copied switch is set.
7579 file_dels
7581 List of strings. Files removed by this changeset.
7582 file_mods
7584 List of strings. Files modified by this changeset.
7585 files List of strings. All files modified, added, or removed by this
7587 changeset.
7588 graphnode
7590 String. The character representing the changeset node in an
7591 ASCII revision graph.
7592 graphwidth
7594 Integer. The width of the graph drawn by 'log --graph' or zero.
7595 index Integer. The current iteration of the loop. (0 indexed)
7597 latesttag
7599 List of strings. The global tags on the most recent globally
7600 tagged ancestor of this changeset. If no such tags exist, the
7601 list consists of the single string "null".
7602 latesttagdistance
7604 Integer. Longest path to the latest tag.
7605 namespaces
7607 Dict of lists. Names attached to this changeset per namespace.
7608 negrev Integer. The repository-local changeset negative revision num‐
7610 ber, which counts in the opposite direction.
7611 node String. The changeset identification hash, as a 40 hexadecimal
7613 digit string.
7614 onelinesummary
7616 String. A one-line summary for the ctx (not including trailing
7617 newline). The default template be overridden in command-tem‐
7618 plates.oneline-summary.
7619 p1 Changeset. The changeset's first parent. {p1.rev} for the revi‐
7621 sion number, and {p1.node} for the identification hash.
7622 p2 Changeset. The changeset's second parent. {p2.rev} for the revi‐
7624 sion number, and {p2.node} for the identification hash.
7625 parents
7627 List of strings. The parents of the changeset in "rev:node" for‐
7628 mat. If the changeset has only one "natural" parent (the prede‐
7629 cessor revision) nothing is shown.
7630 peerurls
7632 A dictionary of repository locations defined in the [paths] sec‐
7633 tion of your configuration file.
7634 phase String. The changeset phase name.
7636 reporoot
7638 String. The root directory of the current repository.
7639 rev Integer. The repository-local changeset revision number.
7641 subrepos
7643 List of strings. Updated subrepositories in the changeset.
7644 tags List of strings. Any tags associated with the changeset.
7646 termwidth
7648 Integer. The width of the current terminal.
7649 user String. The unmodified author of the changeset.
7651 verbosity
7653 String. The current output verbosity in 'debug', 'quiet', 'ver‐
7654 bose', or ''.
7655 The "date" keyword does not produce human-readable output. If you want
7657 to use a date in your output, you can use a filter to process it. Fil‐
7658 ters are functions which return a string based on the input variable.
7659 Be sure to use the stringify filter first when you're applying a
7660 string-input filter to a list-like input variable. You can also use a
7661 chain of filters to get the desired output:
7662 $ hg tip --template "{date|isodate}\n"
7664 2008-08-21 18:22 +0000
7665 Filters
7667 List of filters:
7668 addbreaks
7670 Any text. Add an XHTML "<br />" tag before the end of every line
7671 except the last.
7672 age Date. Returns a human-readable date/time difference between the
7674 given date/time and the current date/time.
7675 basename
7677 Any text. Treats the text as a path, and returns the last compo‐
7678 nent of the path after splitting by the path separator. For ex‐
7679 ample, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
7680 cbor Any object. Serializes the object to CBOR bytes.
7682 commondir
7684 List of text. Treats each list item as file name with / as path
7685 separator and returns the longest common directory prefix shared
7686 by all list items. Returns the empty string if no common prefix
7687 exists.
7688 The list items are not normalized, i.e. "foo/../bar" is handled
7690 as file "bar" in the directory "foo/..". Leading slashes are ig‐
7691 nored.
7692 For example, ["foo/bar/baz", "foo/baz/bar"] becomes "foo" and
7694 ["foo/bar", "baz"] becomes "".
7695 count List or text. Returns the length as an integer.
7697 dirname
7699 Any text. Treats the text as a path, and strips the last compo‐
7700 nent of the path after splitting by the path separator.
7701 domain Any text. Finds the first string that looks like an email ad‐
7703 dress, and extracts just the domain component. Example: User
7704 <user@example.com> becomes example.com.
7705 email Any text. Extracts the first string that looks like an email ad‐
7707 dress. Example: User <user@example.com> becomes user@exam‐
7708 ple.com.
7709 emailuser
7711 Any text. Returns the user portion of an email address.
7712 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
7714 ">" with XML entities, and filters out NUL characters.
7715 fill68 Any text. Wraps the text to fit in 68 columns.
7717 fill76 Any text. Wraps the text to fit in 76 columns.
7719 firstline
7721 Any text. Returns the first line of text.
7722 hex Any text. Convert a binary Mercurial node identifier into its
7724 long hexadecimal representation.
7725 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
7727 (Unix timestamp, timezone offset).
7728 isodate
7730 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
7731 +0200".
7732 isodatesec
7734 Date. Returns the date in ISO 8601 format, including seconds:
7735 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
7736 json Any object. Serializes the object to a JSON formatted text.
7738 lower Any text. Converts the text to lowercase.
7740 nonempty
7742 Any text. Returns '(none)' if the string is empty.
7743 obfuscate
7745 Any text. Returns the input text rendered as a sequence of XML
7746 entities.
7747 person Any text. Returns the name before an email address, interpreting
7749 it as per RFC 5322.
7750 revescape
7752 Any text. Escapes all "special" characters, except @. Forward
7753 slashes are escaped twice to prevent web servers from prema‐
7754 turely unescaping them. For example, "@foo bar/baz" becomes
7755 "@foo%20bar%252Fbaz".
7756 rfc3339date
7758 Date. Returns a date using the Internet date format specified in
7759 RFC 3339: "2009-08-18T13:00:13+02:00".
7760 rfc822date
7762 Date. Returns a date using the same format used in email head‐
7763 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
7764 short Changeset hash. Returns the short form of a changeset hash, i.e.
7766 a 12 hexadecimal digit string.
7767 shortbisect
7769 Any text. Treats label as a bisection status, and returns a sin‐
7770 gle-character representing the status (G: good, B: bad, S:
7771 skipped, U: untested, I: ignored). Returns single space if text
7772 is not a valid bisection status.
7773 shortdate
7775 Date. Returns a date like "2006-09-18".
7776 slashpath
7778 Any text. Replaces the native path separator with slash.
7779 splitlines
7781 Any text. Split text into a list of lines.
7782 stringify
7784 Any type. Turns the value into text by converting values into
7785 text and concatenating them.
7786 stripdir
7788 Treat the text as path and strip a directory level, if possible.
7789 For example, "foo" and "foo/bar" becomes "foo".
7790 tabindent
7792 Any text. Returns the text, with every non-empty line except the
7793 first starting with a tab character.
7794 upper Any text. Converts the text to uppercase.
7796 urlescape
7798 Any text. Escapes all "special" characters. For example, "foo
7799 bar" becomes "foo%20bar".
7800 user Any text. Returns a short representation of a user name or email
7802 address.
7803 utf8 Any text. Converts from the local character encoding to UTF-8.
7805 Note that a filter is nothing more than a function call, i.e.
7807 expr|filter is equivalent to filter(expr).
7808 Functions
7810 In addition to filters, there are some basic built-in functions:
7811 config(section, name[, default])
7813 Returns the requested hgrc config option as a string.
7814 configbool(section, name[, default])
7816 Returns the requested hgrc config option as a boolean.
7817 configint(section, name[, default])
7819 Returns the requested hgrc config option as an integer.
7820 date(date[, fmt])
7822 Format a date. See hg help dates for formatting strings. The de‐
7823 fault is a Unix date format, including the timezone: "Mon Sep 04
7824 15:13:13 2006 0700".
7825 dict([[key=]value...])
7827 Construct a dict from key-value pairs. A key may be omitted if a
7828 value expression can provide an unambiguous name.
7829 diff([includepattern [, excludepattern]])
7831 Show a diff, optionally specifying files to include or exclude.
7832 files(pattern)
7834 All files of the current changeset matching the pattern. See hg
7835 help patterns.
7836 fill(text[, width[, initialident[, hangindent]]])
7838 Fill many paragraphs with optional indentation. See the "fill"
7839 filter.
7840 filter(iterable[, expr])
7842 Remove empty elements from a list or a dict. If expr specified,
7843 it's applied to each element to test emptiness.
7844 get(dict, key)
7846 Get an attribute/key from an object. Some keywords are complex
7847 types. This function allows you to obtain the value of an attri‐
7848 bute on these types.
7849 if(expr, then[, else])
7851 Conditionally execute based on the result of an expression.
7852 ifcontains(needle, haystack, then[, else])
7854 Conditionally execute based on whether the item "needle" is in
7855 "haystack".
7856 ifeq(expr1, expr2, then[, else])
7858 Conditionally execute based on whether 2 items are equivalent.
7859 indent(text, indentchars[, firstline])
7861 Indents all non-empty lines with the characters given in the in‐
7862 dentchars string. An optional third parameter will override the
7863 indent for the first line only if present.
7864 join(list, sep)
7866 Join items in a list with a delimiter.
7867 label(label, expr)
7869 Apply a label to generated content. Content with a label applied
7870 can result in additional post-processing, such as automatic col‐
7871 orization.
7872 latesttag([pattern])
7874 The global tags matching the given pattern on the most recent
7875 globally tagged ancestor of this changeset. If no such tags ex‐
7876 ist, the "{tag}" template resolves to the string "null". See hg
7877 help revisions.patterns for the pattern syntax.
7878 localdate(date[, tz])
7880 Converts a date to the specified timezone. The default is local
7881 date.
7882 mailmap(author)
7884 Return the author, updated according to the value set in the
7885 .mailmap file
7886 max(iterable)
7888 Return the max of an iterable
7889 min(iterable)
7891 Return the min of an iterable
7892 mod(a, b)
7894 Calculate a mod b such that a / b + a mod b == a
7895 pad(text, width[, fillchar=' '[, left=False[, truncate=False]]])
7897 Pad text with a fill character.
7898 relpath(path)
7900 Convert a repository-absolute path into a filesystem path rela‐
7901 tive to the current working directory.
7902 revset(query[, formatargs...])
7904 Execute a revision set query. See hg help revset.
7905 rstdoc(text, style)
7907 Format reStructuredText.
7908 search(pattern, text)
7910 Look for the first text matching the regular expression pattern.
7911 Groups are accessible as {1}, {2}, ... in %-mapped template.
7912 separate(sep, args...)
7914 Add a separator between non-empty arguments.
7915 shortest(node, minlength=4)
7917 Obtain the shortest representation of a node.
7918 startswith(pattern, text)
7920 Returns the value from the "text" argument if it begins with the
7921 content from the "pattern" argument.
7922 strip(text[, chars])
7924 Strip characters from a string. By default, strips all leading
7925 and trailing whitespace.
7926 sub(pattern, replacement, expression)
7928 Perform text substitution using regular expressions.
7929 subsetparents(rev, revset)
7931 Look up parents of the rev in the sub graph given by the revset.
7932 word(number, text[, separator])
7934 Return the nth word from a string.
7935 Operators
7937 We provide a limited set of infix arithmetic operations on integers:
7938 + for addition
7940 - for subtraction
7941 * for multiplication
7942 / for floor division (division rounded to integer nearest -infinity)
7943 Division fulfills the law x = x / y + mod(x, y).
7945 Also, for any expression that returns a list, there is a list operator:
7947 expr % "{template}"
7949 As seen in the above example, {template} is interpreted as a template.
7951 To prevent it from being interpreted, you can use an escape character
7952 \{ or a raw string prefix, r'...'.
7953 The dot operator can be used as a shorthand for accessing a sub item:
7955 • expr.member is roughly equivalent to expr % '{member}' if expr re‐
7957 turns a non-list/dict. The returned value is not stringified.
7958 • dict.key is identical to get(dict, 'key').
7960 Aliases
7962 New keywords and functions can be defined in the templatealias section
7963 of a Mercurial configuration file:
7964 <alias> = <definition>
7966 Arguments of the form a1, a2, etc. are substituted from the alias into
7968 the definition.
7969 For example,
7971 [templatealias]
7973 r = rev
7974 rn = "{r}:{node|short}"
7975 leftpad(s, w) = pad(s, w, ' ', True)
7976 defines two symbol aliases, r and rn, and a function alias leftpad().
7978 It's also possible to specify complete template strings, using the tem‐
7980 plates section. The syntax used is the general template string syntax.
7981 For example,
7983 [templates]
7985 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
7986 defines a template, nodedate, which can be called like:
7988 $ hg log -r . -Tnodedate
7990 A template defined in templates section can also be referenced from an‐
7992 other template:
7993 $ hg log -r . -T "{rev} {nodedate}"
7995 but be aware that the keywords cannot be overridden by templates. For
7997 example, a template defined as templates.rev cannot be referenced as
7998 {rev}.
7999 A template defined in templates section may have sub templates which
8001 are inserted before/after/between items:
8002 [templates]
8004 myjson = ' {dict(rev, node|short)|json}'
8005 myjson:docheader = '\{\n'
8006 myjson:docfooter = '\n}\n'
8007 myjson:separator = ',\n'
8008 Examples
8010 Some sample command line templates:
8011 • Format lists, e.g. files:
8013 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
8015 • Join the list of files with a ", ":
8017 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
8019 • Join the list of files ending with ".py" with a ", ":
8021 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
8023 • Separate non-empty arguments by a " ":
8025 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
8027 • Modify each line of a commit description:
8029 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
8031 • Format date:
8033 $ hg log -r 0 --template "{date(date, '%Y')}\n"
8035 • Display date in UTC:
8037 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
8039 • Output the description set to a fill-width of 30:
8041 $ hg log -r 0 --template "{fill(desc, 30)}"
8043 • Use a conditional to test for the default branch:
8045 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
8047 'on branch {branch}')}\n"
8048 • Append a newline if not empty:
8050 $ hg tip --template "{if(author, '{author}\n')}"
8052 • Label the output for use with the color extension:
8054 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
8056 • Invert the firstline filter, i.e. everything but the first line:
8058 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
8060 • Display the contents of the 'extra' field, one per line:
8062 $ hg log -r 0 --template "{join(extras, '\n')}\n"
8064 • Mark the active bookmark with '*':
8066 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
8068 • Find the previous release candidate tag, the distance and changes
8070 since the tag:
8071 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
8073 • Mark the working copy parent with '@':
8075 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
8077 • Show details of parent revisions:
8079 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
8081 • Show only commit descriptions that start with "template":
8083 $ hg log --template "{startswith('template', firstline(desc))}\n"
8085 • Print the first word of each line of a commit message:
8087 $ hg log --template "{word(0, desc)}\n"
8089
8091 Valid URLs are of the form:
8092 local/filesystem/path[#revision]
8094 file://local/filesystem/path[#revision]
8095 http://[user[:pass]@]host[:port]/[path][#revision]
8096 https://[user[:pass]@]host[:port]/[path][#revision]
8097 ssh://[user@]host[:port]/[path][#revision]
8098 path://pathname
8099 Paths in the local filesystem can either point to Mercurial reposito‐
8101 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
8102 dle). See also hg help paths.
8103 An optional identifier after # indicates a particular branch, tag, or
8105 changeset to use from the remote repository. See also hg help revisions
8106 .
8107 Some features, such as pushing to http:// and https:// URLs are only
8109 possible if the feature is explicitly enabled on the remote Mercurial
8110 server.
8111 Note that the security of HTTPS URLs depends on proper configuration of
8113 web.cacerts.
8114 Some notes about using SSH with Mercurial:
8116 • SSH requires an accessible shell account on the destination machine
8118 and a copy of hg in the remote path or specified with remotecmd.
8119 • path is relative to the remote user's home directory by default. Use
8121 an extra slash at the start of a path to specify an absolute path:
8122 ssh://example.com//tmp/repository
8124 • Mercurial doesn't use its own compression via SSH; the right thing to
8126 do is to configure it in your ~/.ssh/config, e.g.:
8127 Host *.mylocalnetwork.example.com
8129 Compression no
8130 Host *
8131 Compression yes
8132 Alternatively specify "ssh -C" as your ssh command in your configura‐
8134 tion file or with the --ssh command line option.
8135 These URLs can all be stored in your configuration file with path
8137 aliases under the [paths] section like so:
8138 [paths]
8140 alias1 = URL1
8141 alias2 = URL2
8142 ...
8143 You can then use the alias for any command that uses a URL (for example
8145 hg pull alias1 will be treated as hg pull URL1).
8146 Two path aliases are special because they are used as defaults when you
8148 do not provide the URL to a command:
8149 default:
8151 When you create a repository with hg clone, the clone command
8152 saves the location of the source repository as the new reposi‐
8153 tory's 'default' path. This is then used when you omit path from
8154 push- and pull-like commands (including incoming and outgoing).
8155 default-push:
8157 The push command will look for a path named 'default-push', and
8158 prefer it over 'default' if both are defined.
8159 These alias can also be use in the path:// scheme:
8161 [paths]
8163 alias1 = URL1
8164 alias2 = path://alias1
8165 ...
8166 check hg help config.paths for details about the behavior of such
8168 "sub-path".
8169
8171 This section contains help for extensions that are distributed together
8172 with Mercurial. Help for other extensions is available in the help sys‐
8173 tem.
8174 absorb
8176 apply working directory changes to changesets (EXPERIMENTAL)
8177 The absorb extension provides a command to use annotate information to
8179 amend modified chunks into the corresponding non-public changesets.
8180 [absorb]
8182 # only check 50 recent non-public changesets at most
8183 max-stack-size = 50
8184 # whether to add noise to new commits to avoid obsolescence cycle
8185 add-noise = 1
8186 # make `amend --correlated` a shortcut to the main command
8187 amend-flag = correlated
8188 [color]
8190 absorb.description = yellow
8191 absorb.node = blue bold
8192 absorb.path = bold
8193 Commands
8195 Change creation
8196 absorb
8197 incorporate corrections into the stack of draft changesets:
8198 hg absorb [OPTION] [FILE]...
8200 absorb analyzes each change in your working directory and attempts to
8202 amend the changed lines into the changesets in your stack that first
8203 introduced those lines.
8204 If absorb cannot find an unambiguous changeset to amend for a change,
8206 that change will be left in the working directory, untouched. They can
8207 be observed by hg status or hg diff afterwards. In other words, absorb
8208 does not write to the working directory.
8209 Changesets outside the revset ::. and not public() and not merge() will
8211 not be changed.
8212 Changesets that become empty after applying the changes will be
8214 deleted.
8215 By default, absorb will show what it plans to do and prompt for confir‐
8217 mation. If you are confident that the changes will be absorbed to the
8218 correct place, run hg absorb -a to apply the changes immediately.
8219 Returns 0 on success, 1 if all chunks were ignored and nothing amended.
8221 Options:
8223 -a, --apply-changes
8225 apply changes without prompting for confirmation
8226 -p, --print-changes
8228 always print which changesets are modified by which changes
8229 -i, --interactive
8231 interactively select which chunks to apply
8232 -e, --edit-lines
8234 edit what lines belong to which changesets before commit (EXPER‐
8235 IMENTAL)
8236 -n, --dry-run
8238 do not perform actions, just print output
8239 --style <STYLE>
8241 display using template map file (DEPRECATED)
8242 -T,--template <TEMPLATE>
8244 display with template
8245 -I,--include <PATTERN[+]>
8247 include names matching the given patterns
8248 -X,--exclude <PATTERN[+]>
8250 exclude names matching the given patterns
8251 [+] marked option can be specified multiple times
8253 acl
8255 hooks for controlling repository access
8256 This hook makes it possible to allow or deny write access to given
8258 branches and paths of a repository when receiving incoming changesets
8259 via pretxnchangegroup and pretxncommit.
8260 The authorization is matched based on the local user name on the system
8262 where the hook runs, and not the committer of the original changeset
8263 (since the latter is merely informative).
8264 The acl hook is best used along with a restricted shell like hgsh, pre‐
8266 venting authenticating users from doing anything other than pushing or
8267 pulling. The hook is not safe to use if users have interactive shell
8268 access, as they can then disable the hook. Nor is it safe if remote
8269 users share an account, because then there is no way to distinguish
8270 them.
8271 The order in which access checks are performed is:
8273 1. Deny list for branches (section acl.deny.branches)
8275 2. Allow list for branches (section acl.allow.branches)
8277 3. Deny list for paths (section acl.deny)
8279 4. Allow list for paths (section acl.allow)
8281 The allow and deny sections take key-value pairs.
8283 Branch-based Access Control
8285 Use the acl.deny.branches and acl.allow.branches sections to have
8286 branch-based access control. Keys in these sections can be either:
8287 • a branch name, or
8289 • an asterisk, to match any branch;
8291 The corresponding values can be either:
8293 • a comma-separated list containing users and groups, or
8295 • an asterisk, to match anyone;
8297 You can add the "!" prefix to a user or group name to invert the sense
8299 of the match.
8300 Path-based Access Control
8302 Use the acl.deny and acl.allow sections to have path-based access con‐
8303 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
8304 tax by default). The corresponding values follow the same syntax as the
8305 other sections above.
8306 Bookmark-based Access Control
8308 Use the acl.deny.bookmarks and acl.allow.bookmarks sections to have
8309 bookmark-based access control. Keys in these sections can be either:
8310 • a bookmark name, or
8312 • an asterisk, to match any bookmark;
8314 The corresponding values can be either:
8316 • a comma-separated list containing users and groups, or
8318 • an asterisk, to match anyone;
8320 You can add the "!" prefix to a user or group name to invert the sense
8322 of the match.
8323 Note: for interactions between clients and servers using Mercurial 3.6+
8325 a rejection will generally reject the entire push, for interactions in‐
8326 volving older clients, the commit transactions will already be ac‐
8327 cepted, and only the bookmark movement will be rejected.
8328 Groups
8330 Group names must be prefixed with an @ symbol. Specifying a group name
8331 has the same effect as specifying all the users in that group.
8332 You can define group members in the acl.groups section. If a group
8334 name is not defined there, and Mercurial is running under a Unix-like
8335 system, the list of users will be taken from the OS. Otherwise, an ex‐
8336 ception will be raised.
8337 Example Configuration
8339 [hooks]
8340 # Use this if you want to check access restrictions at commit time
8342 pretxncommit.acl = python:hgext.acl.hook
8343 # Use this if you want to check access restrictions for pull, push,
8345 # bundle and serve.
8346 pretxnchangegroup.acl = python:hgext.acl.hook
8347 [acl]
8349 # Allow or deny access for incoming changes only if their source is
8350 # listed here, let them pass otherwise. Source is "serve" for all
8351 # remote access (http or ssh), "push", "pull" or "bundle" when the
8352 # related commands are run locally.
8353 # Default: serve
8354 sources = serve
8355 [acl.deny.branches]
8357 # Everyone is denied to the frozen branch:
8359 frozen-branch = *
8360 # A bad user is denied on all branches:
8362 * = bad-user
8363 [acl.allow.branches]
8365 # A few users are allowed on branch-a:
8367 branch-a = user-1, user-2, user-3
8368 # Only one user is allowed on branch-b:
8370 branch-b = user-1
8371 # The super user is allowed on any branch:
8373 * = super-user
8374 # Everyone is allowed on branch-for-tests:
8376 branch-for-tests = *
8377 [acl.deny]
8379 # This list is checked first. If a match is found, acl.allow is not
8380 # checked. All users are granted access if acl.deny is not present.
8381 # Format for both lists: glob pattern = user, ..., @group, ...
8382 # To match everyone, use an asterisk for the user:
8384 # my/glob/pattern = *
8385 # user6 will not have write access to any file:
8387 ** = user6
8388 # Group "hg-denied" will not have write access to any file:
8390 ** = @hg-denied
8391 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
8393 # everyone being able to change all other files. See below.
8394 src/main/resources/DONT-TOUCH-THIS.txt = *
8395 [acl.allow]
8397 # if acl.allow is not present, all users are allowed by default
8398 # empty acl.allow = no users allowed
8399 # User "doc_writer" has write access to any file under the "docs"
8401 # folder:
8402 docs/** = doc_writer
8403 # User "jack" and group "designers" have write access to any file
8405 # under the "images" folder:
8406 images/** = jack, @designers
8407 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
8409 # will have write access to any file under the "resources" folder
8410 # (except for 1 file. See acl.deny):
8411 src/main/resources/** = *
8412 .hgtags = release_engineer
8414 Examples using the ! prefix
8416 Suppose there's a branch that only a given user (or group) should be
8417 able to push to, and you don't want to restrict access to any other
8418 branch that may be created.
8419 The "!" prefix allows you to prevent anyone except a given user or
8421 group to push changesets in a given branch or path.
8422 In the examples below, we will: 1) Deny access to branch "ring" to any‐
8424 one but user "gollum" 2) Deny access to branch "lake" to anyone but
8425 members of the group "hobbit" 3) Deny access to a file to anyone but
8426 user "gollum"
8427 [acl.allow.branches]
8429 # Empty
8430 [acl.deny.branches]
8432 # 1) only 'gollum' can commit to branch 'ring';
8434 # 'gollum' and anyone else can still commit to any other branch.
8435 ring = !gollum
8436 # 2) only members of the group 'hobbit' can commit to branch 'lake';
8438 # 'hobbit' members and anyone else can still commit to any other branch.
8439 lake = !@hobbit
8440 # You can also deny access based on file paths:
8442 [acl.allow]
8444 # Empty
8445 [acl.deny]
8447 # 3) only 'gollum' can change the file below;
8448 # 'gollum' and anyone else can still change any other file.
8449 /misty/mountains/cave/ring = !gollum
8450 amend
8452 provide the amend command (EXPERIMENTAL)
8453 This extension provides an amend command that is similar to commit
8455 --amend but does not prompt an editor.
8456 Commands
8458 Change creation
8459 amend
8460 amend the working copy parent with all or specified outstanding
8461 changes:
8462 hg amend [OPTION]... [FILE]...
8464 Similar to hg commit --amend, but reuse the commit message without in‐
8466 voking editor, unless --edit was set.
8467 See hg help commit for more details.
8469 Options:
8471 -A, --addremove
8473 mark new/missing files as added/removed before committing
8474 -e, --edit
8476 invoke editor on commit messages
8477 -i, --interactive
8479 use interactive mode
8480 --close-branch
8482 mark a branch as closed, hiding it from the branch list
8483 -s, --secret
8485 use the secret phase for committing
8486 -n,--note <VALUE>
8488 store a note on the amend
8489 -I,--include <PATTERN[+]>
8491 include names matching the given patterns
8492 -X,--exclude <PATTERN[+]>
8494 exclude names matching the given patterns
8495 -m,--message <TEXT>
8497 use text as commit message
8498 -l,--logfile <FILE>
8500 read commit message from file
8501 -d,--date <DATE>
8503 record the specified date as commit date
8504 -u,--user <USER>
8506 record the specified user as committer
8507 -D, --currentdate
8509 record the current date as commit date
8510 -U, --currentuser
8512 record the current user as committer
8513 [+] marked option can be specified multiple times
8515 automv
8517 check for unrecorded moves at commit time (EXPERIMENTAL)
8518 This extension checks at commit/amend time if any of the committed
8520 files comes from an unrecorded mv.
8521 The threshold at which a file is considered a move can be set with the
8523 automv.similarity config option. This option takes a percentage between
8524 0 (disabled) and 100 (files must be identical), the default is 95.
8525 beautifygraph
8527 beautify log -G output by using Unicode characters (EXPERIMENTAL)
8528 A terminal with UTF-8 support and monospace narrow text are re‐
8530 quired.
8531 blackbox
8533 log repository events to a blackbox for debugging
8534 Logs event information to .hg/blackbox.log to help debug and diagnose
8536 problems. The events that get logged can be configured via the black‐
8537 box.track and blackbox.ignore config keys.
8538 Examples:
8540 [blackbox]
8542 track = *
8543 ignore = pythonhook
8544 # dirty is *EXPENSIVE* (slow);
8545 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
8546 dirty = True
8547 # record the source of log messages
8548 logsource = True
8549 [blackbox]
8551 track = command, commandfinish, commandexception, exthook, pythonhook
8552 [blackbox]
8554 track = incoming
8555 [blackbox]
8557 # limit the size of a log file
8558 maxsize = 1.5 MB
8559 # rotate up to N log files when the current one gets too big
8560 maxfiles = 3
8561 [blackbox]
8563 # Include microseconds in log entries with %f (see Python function
8564 # datetime.datetime.strftime)
8565 date-format = %Y-%m-%d @ %H:%M:%S.%f
8566 Commands
8568 Repository maintenance
8569 blackbox
8570 view the recent repository events:
8571 hg blackbox [OPTION]...
8573 view the recent repository events
8575 Options:
8577 -l,--limit <VALUE>
8579 the number of events to show (default: 10)
8580 bookflow
8582 implements bookmark-based branching (EXPERIMENTAL)
8583 • Disables creation of new branches (config: enable_branches=False).
8585 • Requires an active bookmark on commit (config: require_book‐
8587 mark=True).
8588 • Doesn't move the active bookmark on update, only on commit.
8590 • Requires '--rev' for moving an existing bookmark.
8592 • Protects special bookmarks (config: protect=@).
8594 flow related commands
8596 hg book NAME
8598 create a new bookmark
8599 hg book NAME -r REV
8601 move bookmark to revision (fast-forward)
8602 hg up|co NAME
8604 switch to bookmark
8605 hg push -B .
8607 push active bookmark
8608 bugzilla
8610 hooks for integrating with the Bugzilla bug tracker
8611 This hook extension adds comments on bugs in Bugzilla when changesets
8613 that refer to bugs by Bugzilla ID are seen. The comment is formatted
8614 using the Mercurial template mechanism.
8615 The bug references can optionally include an update for Bugzilla of the
8617 hours spent working on the bug. Bugs can also be marked fixed.
8618 Four basic modes of access to Bugzilla are provided:
8620 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
8622 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
8624 later.
8625 3. Check data via the Bugzilla XMLRPC interface and submit bug change
8627 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
8628 later.
8629 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
8631 tions using MySQL are supported. Requires Python MySQLdb.
8632 Writing directly to the database is susceptible to schema changes, and
8634 relies on a Bugzilla contrib script to send out bug change notification
8635 emails. This script runs as the user running Mercurial, must be run on
8636 the host with the Bugzilla install, and requires permission to read
8637 Bugzilla configuration details and the necessary MySQL user and pass‐
8638 word to have full access rights to the Bugzilla database. For these
8639 reasons this access mode is now considered deprecated, and will not be
8640 updated for new Bugzilla versions going forward. Only adding comments
8641 is supported in this access mode.
8642 Access via XMLRPC needs a Bugzilla username and password to be speci‐
8644 fied in the configuration. Comments are added under that username.
8645 Since the configuration must be readable by all Mercurial users, it is
8646 recommended that the rights of that user are restricted in Bugzilla to
8647 the minimum necessary to add comments. Marking bugs fixed requires
8648 Bugzilla 4.0 and later.
8649 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
8651 to the Bugzilla email interface to submit comments to bugs. The From:
8652 address in the email is set to the email address of the Mercurial user,
8653 so the comment appears to come from the Mercurial user. In the event
8654 that the Mercurial user email is not recognized by Bugzilla as a
8655 Bugzilla user, the email associated with the Bugzilla username used to
8656 log into Bugzilla is used instead as the source of the comment. Marking
8657 bugs fixed works on all supported Bugzilla versions.
8658 Access via the REST-API needs either a Bugzilla username and password
8660 or an apikey specified in the configuration. Comments are made under
8661 the given username or the user associated with the apikey in Bugzilla.
8662 Configuration items common to all access modes:
8664 bugzilla.version
8666 The access type to use. Values recognized are:
8667 restapi
8669 Bugzilla REST-API, Bugzilla 5.0 and later.
8671 xmlrpc
8673 Bugzilla XMLRPC interface.
8675 xmlrpc+email
8677 Bugzilla XMLRPC and email interfaces.
8679 3.0
8681 MySQL access, Bugzilla 3.0 and later.
8683 2.18
8685 MySQL access, Bugzilla 2.18 and up to but not including
8687 3.0.
8688 2.16
8690 MySQL access, Bugzilla 2.16 and up to but not including
8692 2.18.
8693 bugzilla.regexp
8695 Regular expression to match bug IDs for update in changeset com‐
8696 mit message. It must contain one "()" named group <ids> con‐
8697 taining the bug IDs separated by non-digit characters. It may
8698 also contain a named group <hours> with a floating-point number
8699 giving the hours worked on the bug. If no named groups are
8700 present, the first "()" group is assumed to contain the bug IDs,
8701 and work time is not updated. The default expression matches Bug
8702 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
8703 and 5678 and variations thereof, followed by an hours number
8704 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
8705 sitive.
8706 bugzilla.fixregexp
8708 Regular expression to match bug IDs for marking fixed in change‐
8709 set commit message. This must contain a "()" named group <ids>`
8710 containing the bug IDs separated by non-digit characters. It may
8711 also contain a named group ``<hours> with a floating-point num‐
8712 ber giving the hours worked on the bug. If no named groups are
8713 present, the first "()" group is assumed to contain the bug IDs,
8714 and work time is not updated. The default expression matches
8715 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
8716 5678 and variations thereof, followed by an hours number pre‐
8717 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
8718 tive.
8719 bugzilla.fixstatus
8721 The status to set a bug to when marking fixed. Default RESOLVED.
8722 bugzilla.fixresolution
8724 The resolution to set a bug to when marking fixed. Default
8725 FIXED.
8726 bugzilla.style
8728 The style file to use when formatting comments.
8729 bugzilla.template
8731 Template to use when formatting comments. Overrides style if
8732 specified. In addition to the usual Mercurial keywords, the ex‐
8733 tension specifies:
8734 {bug}
8736 The Bugzilla bug ID.
8738 {root}
8740 The full pathname of the Mercurial repository.
8742 {webroot}
8744 Stripped pathname of the Mercurial repository.
8746 {hgweb}
8748 Base URL for browsing Mercurial repositories.
8750 Default changeset {node|short} in repo {root} refers to bug
8752 {bug}.\ndetails:\n\t{desc|tabindent}
8753 bugzilla.strip
8755 The number of path separator characters to strip from the front
8756 of the Mercurial repository path ({root} in templates) to pro‐
8757 duce {webroot}. For example, a repository with {root} /var/lo‐
8758 cal/my-project with a strip of 2 gives a value for {webroot} of
8759 my-project. Default 0.
8760 web.baseurl
8762 Base URL for browsing Mercurial repositories. Referenced from
8763 templates as {hgweb}.
8764 Configuration items common to XMLRPC+email and MySQL access modes:
8766 bugzilla.usermap
8768 Path of file containing Mercurial committer email to Bugzilla
8769 user email mappings. If specified, the file should contain one
8770 mapping per line:
8771 committer = Bugzilla user
8773 See also the [usermap] section.
8775 The [usermap] section is used to specify mappings of Mercurial commit‐
8777 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
8778 entries of the form committer = Bugzilla user.
8779 XMLRPC and REST-API access mode configuration:
8781 bugzilla.bzurl
8783 The base URL for the Bugzilla installation. Default http://lo‐
8784 calhost/bugzilla.
8785 bugzilla.user
8787 The username to use to log into Bugzilla via XMLRPC. Default
8788 bugs.
8789 bugzilla.password
8791 The password for Bugzilla login.
8792 REST-API access mode uses the options listed above as well as:
8794 bugzilla.apikey
8796 An apikey generated on the Bugzilla instance for api access.
8797 Using an apikey removes the need to store the user and password
8798 options.
8799 XMLRPC+email access mode uses the XMLRPC access mode configuration
8801 items, and also:
8802 bugzilla.bzemail
8804 The Bugzilla email address.
8805 In addition, the Mercurial email settings must be configured. See the
8807 documentation in hgrc(5), sections [email] and [smtp].
8808 MySQL access mode configuration:
8810 bugzilla.host
8812 Hostname of the MySQL server holding the Bugzilla database. De‐
8813 fault localhost.
8814 bugzilla.db
8816 Name of the Bugzilla database in MySQL. Default bugs.
8817 bugzilla.user
8819 Username to use to access MySQL server. Default bugs.
8820 bugzilla.password
8822 Password to use to access MySQL server.
8823 bugzilla.timeout
8825 Database connection timeout (seconds). Default 5.
8826 bugzilla.bzuser
8828 Fallback Bugzilla user name to record comments with, if change‐
8829 set committer cannot be found as a Bugzilla user.
8830 bugzilla.bzdir
8832 Bugzilla install directory. Used by default notify. Default
8833 /var/www/html/bugzilla.
8834 bugzilla.notify
8836 The command to run to get Bugzilla to send bug change notifica‐
8837 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
8838 id) and user (committer bugzilla email). Default depends on ver‐
8839 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
8840 mail.pl %(id)s %(user)s".
8841 Activating the extension:
8843 [extensions]
8845 bugzilla =
8846 [hooks]
8848 # run bugzilla hook on every change pulled or pushed in here
8849 incoming.bugzilla = python:hgext.bugzilla.hook
8850 Example configurations:
8852 XMLRPC example configuration. This uses the Bugzilla at
8854 http://my-project.org/bugzilla, logging in as user bug‐
8855 mail@my-project.org with password plugh. It is used with a collection
8856 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8857 at http://my-project.org/hg.
8858 [bugzilla]
8860 bzurl=http://my-project.org/bugzilla
8861 user=bugmail@my-project.org
8862 password=plugh
8863 version=xmlrpc
8864 template=Changeset {node|short} in {root|basename}.
8865 {hgweb}/{webroot}/rev/{node|short}\n
8866 {desc}\n
8867 strip=5
8868 [web]
8870 baseurl=http://my-project.org/hg
8871 XMLRPC+email example configuration. This uses the Bugzilla at
8873 http://my-project.org/bugzilla, logging in as user bug‐
8874 mail@my-project.org with password plugh. It is used with a collection
8875 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8876 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
8877 email address bugzilla@my-project.org.
8878 [bugzilla]
8880 bzurl=http://my-project.org/bugzilla
8881 user=bugmail@my-project.org
8882 password=plugh
8883 version=xmlrpc+email
8884 bzemail=bugzilla@my-project.org
8885 template=Changeset {node|short} in {root|basename}.
8886 {hgweb}/{webroot}/rev/{node|short}\n
8887 {desc}\n
8888 strip=5
8889 [web]
8891 baseurl=http://my-project.org/hg
8892 [usermap]
8894 user@emaildomain.com=user.name@bugzilladomain.com
8895 MySQL example configuration. This has a local Bugzilla 3.2 installation
8897 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
8898 database name is bugs and MySQL is accessed with MySQL username bugs
8899 password XYZZY. It is used with a collection of Mercurial repositories
8900 in /var/local/hg/repos/, with a web interface at
8901 http://my-project.org/hg.
8902 [bugzilla]
8904 host=localhost
8905 password=XYZZY
8906 version=3.0
8907 bzuser=unknown@domain.com
8908 bzdir=/opt/bugzilla-3.2
8909 template=Changeset {node|short} in {root|basename}.
8910 {hgweb}/{webroot}/rev/{node|short}\n
8911 {desc}\n
8912 strip=5
8913 [web]
8915 baseurl=http://my-project.org/hg
8916 [usermap]
8918 user@emaildomain.com=user.name@bugzilladomain.com
8919 All the above add a comment to the Bugzilla bug record of the form:
8921 Changeset 3b16791d6642 in repository-name.
8923 http://my-project.org/hg/repository-name/rev/3b16791d6642
8924 Changeset commit comment. Bug 1234.
8926 censor
8928 erase file content at a given revision
8929 The censor command instructs Mercurial to erase all content of a file
8931 at a given revision without updating the changeset hash. This allows
8932 existing history to remain valid while preventing future clones/pulls
8933 from receiving the erased data.
8934 Typical uses for censor are due to security or legal requirements, in‐
8936 cluding:
8937 * Passwords, private keys, cryptographic material
8939 * Licensed data/code/libraries for which the license has expired
8940 * Personally Identifiable Information or other private data
8941 Censored nodes can interrupt mercurial's typical operation whenever the
8943 excised data needs to be materialized. Some commands, like hg cat/hg
8944 revert, simply fail when asked to produce censored data. Others, like
8945 hg verify and hg update, must be capable of tolerating censored data to
8946 continue to function in a meaningful way. Such commands only tolerate
8947 censored file revisions if they are allowed by the "censor.policy=ig‐
8948 nore" config option.
8949 A few informative commands such as hg grep will unconditionally ignore
8951 censored data and merely report that it was encountered.
8952 Commands
8954 Repository maintenance
8955 censor
8956 hg censor -r REV [-t TEXT] [FILE]
8957 Options:
8959 -r,--rev <REV>
8961 censor file from specified revision
8962 -t,--tombstone <TEXT>
8964 replacement tombstone data
8965 children
8967 command to display child changesets (DEPRECATED)
8968 This extension is deprecated. You should use hg log -r "children(REV)"
8970 instead.
8971 Commands
8973 Change navigation
8974 children
8975 show the children of the given or working directory revision:
8976 hg children [-r REV] [FILE]
8978 Print the children of the working directory's revisions. If a revision
8980 is given via -r/--rev, the children of that revision will be printed.
8981 If a file argument is given, revision in which the file was last
8982 changed (after the working directory revision or the argument to --rev
8983 if given) is printed.
8984 Please use hg log instead:
8986 hg children => hg log -r "children(.)"
8988 hg children -r REV => hg log -r "children(REV)"
8989 See hg help log and hg help revsets.children.
8991 Options:
8993 -r,--rev <REV>
8995 show children of the specified revision (default: .)
8996 --style <STYLE>
8998 display using template map file (DEPRECATED)
8999 -T,--template <TEMPLATE>
9001 display with template
9002 churn
9004 command to display statistics about repository history
9005 Commands
9007 Repository maintenance
9008 churn
9009 histogram of changes to the repository:
9010 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
9012 This command will display a histogram representing the number of
9014 changed lines or revisions, grouped according to the given template.
9015 The default template will group changes by author. The --dateformat
9016 option may be used to group the results by date instead.
9017 Statistics are based on the number of changed lines, or alternatively
9019 the number of matching revisions if the --changesets option is speci‐
9020 fied.
9021 Examples:
9023 # display count of changed lines for every committer
9025 hg churn -T "{author|email}"
9026 # display daily activity graph
9028 hg churn -f "%H" -s -c
9029 # display activity of developers by month
9031 hg churn -f "%Y-%m" -s -c
9032 # display count of lines changed in every year
9034 hg churn -f "%Y" -s
9035 # display count of lines changed in a time range
9037 hg churn -d "2020-04 to 2020-09"
9038 It is possible to map alternate email addresses to a main address by
9040 providing a file using the following format:
9041 <alias email> = <actual email>
9043 Such a file may be specified with the --aliases option, otherwise a
9045 .hgchurn file will be looked for in the working directory root.
9046 Aliases will be split from the rightmost "=".
9047 Options:
9049 -r,--rev <REV[+]>
9051 count rate for the specified revision or revset
9052 -d,--date <DATE>
9054 count rate for revisions matching date spec
9055 -t,--oldtemplate <TEMPLATE>
9057 template to group changesets (DEPRECATED)
9058 -T,--template <TEMPLATE>
9060 template to group changesets (default: {author|email})
9061 -f,--dateformat <FORMAT>
9063 strftime-compatible format for grouping by date
9064 -c, --changesets
9066 count rate by number of changesets
9067 -s, --sort
9069 sort by key (default: sort by count)
9070 --diffstat
9072 display added/removed lines separately
9073 --aliases <FILE>
9075 file with email aliases
9076 -I,--include <PATTERN[+]>
9078 include names matching the given patterns
9079 -X,--exclude <PATTERN[+]>
9081 exclude names matching the given patterns
9082 [+] marked option can be specified multiple times
9084 clonebundles
9086 advertise pre-generated bundles to seed clones
9087 "clonebundles" is a server-side extension used to advertise the exis‐
9089 tence of pre-generated, externally hosted bundle files to clients that
9090 are cloning so that cloning can be faster, more reliable, and require
9091 less resources on the server. "pullbundles" is a related feature for
9092 sending pre-generated bundle files to clients as part of pull opera‐
9093 tions.
9094 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
9096 ally, the server, in response to a client's request to clone, dynami‐
9097 cally generates a bundle containing the entire repository content and
9098 sends it to the client. There is no caching on the server and the
9099 server will have to redundantly generate the same outgoing bundle in
9100 response to each clone request. For servers with large repositories or
9101 with high clone volume, the load from clones can make scaling the
9102 server challenging and costly.
9103 This extension provides server operators the ability to offload poten‐
9105 tially expensive clone load to an external service. Pre-generated bun‐
9106 dles also allow using more CPU intensive compression, reducing the ef‐
9107 fective bandwidth requirements.
9108 Here's how clone bundles work:
9110 1. A server operator establishes a mechanism for making bundle files
9112 available on a hosting service where Mercurial clients can fetch
9113 them.
9114 2. A manifest file listing available bundle URLs and some optional
9116 metadata is added to the Mercurial repository on the server.
9117 3. A client initiates a clone against a clone bundles aware server.
9119 4. The client sees the server is advertising clone bundles and fetches
9121 the manifest listing available bundles.
9122 5. The client filters and sorts the available bundles based on what it
9124 supports and prefers.
9125 6. The client downloads and applies an available bundle from the
9127 server-specified URL.
9128 7. The client reconnects to the original server and performs the equiv‐
9130 alent of hg pull to retrieve all repository data not in the bundle.
9131 (The repository could have been updated between when the bundle was
9132 created and when the client started the clone.) This may use "pull‐
9133 bundles".
9134 Instead of the server generating full repository bundles for every
9136 clone request, it generates full bundles once and they are subsequently
9137 reused to bootstrap new clones. The server may still transfer data at
9138 clone time. However, this is only data that has been added/changed
9139 since the bundle was created. For large, established repositories, this
9140 can reduce server load for clones to less than 1% of original.
9141 Here's how pullbundles work:
9143 1. A manifest file listing available bundles and describing the revi‐
9145 sions is added to the Mercurial repository on the server.
9146 2. A new-enough client informs the server that it supports partial
9148 pulls and initiates a pull.
9149 3. If the server has pull bundles enabled and sees the client advertis‐
9151 ing partial pulls, it checks for a matching pull bundle in the mani‐
9152 fest. A bundle matches if the format is supported by the client,
9153 the client has the required revisions already and needs something
9154 from the bundle.
9155 4. If there is at least one matching bundle, the server sends it to the
9157 client.
9158 5. The client applies the bundle and notices that the server reply was
9160 incomplete. It initiates another pull.
9161 To work, this extension requires the following of server operators:
9163 • Generating bundle files of repository content (typically periodi‐
9165 cally, such as once per day).
9166 • Clone bundles: A file server that clients have network access to and
9168 that Python knows how to talk to through its normal URL handling fa‐
9169 cility (typically an HTTP/HTTPS server).
9170 • A process for keeping the bundles manifest in sync with available
9172 bundle files.
9173 Strictly speaking, using a static file hosting server isn't required: a
9175 server operator could use a dynamic service for retrieving bundle data.
9176 However, static file hosting services are simple and scalable and
9177 should be sufficient for most needs.
9178 Bundle files can be generated with the hg bundle command. Typically hg
9180 bundle --all is used to produce a bundle of the entire repository.
9181 hg debugcreatestreamclonebundle can be used to produce a special
9183 streaming clonebundle. These are bundle files that are extremely effi‐
9184 cient to produce and consume (read: fast). However, they are larger
9185 than traditional bundle formats and require that clients support the
9186 exact set of repository data store formats in use by the repository
9187 that created them. Typically, a newer server can serve data that is
9188 compatible with older clients. However, streaming clone bundles don't
9189 have this guarantee. Server operators need to be aware that newer ver‐
9190 sions of Mercurial may produce streaming clone bundles incompatible
9191 with older Mercurial versions.
9192 A server operator is responsible for creating a .hg/clonebundles.mani‐
9194 fest file containing the list of available bundle files suitable for
9195 seeding clones. If this file does not exist, the repository will not
9196 advertise the existence of clone bundles when clients connect. For pull
9197 bundles, .hg/pullbundles.manifest is used.
9198 The manifest file contains a newline (n) delimited list of entries.
9200 Each line in this file defines an available bundle. Lines have the for‐
9202 mat:
9203 <URL> [<key>=<value>[ <key>=<value>]]
9205 That is, a URL followed by an optional, space-delimited list of
9207 key=value pairs describing additional properties of this bundle. Both
9208 keys and values are URI encoded.
9209 For pull bundles, the URL is a path under the .hg directory of the
9211 repository.
9212 Keys in UPPERCASE are reserved for use by Mercurial and are defined be‐
9214 low. All non-uppercase keys can be used by site installations. An ex‐
9215 ample use for custom properties is to use the datacenter attribute to
9216 define which data center a file is hosted in. Clients could then prefer
9217 a server in the data center closest to them.
9218 The following reserved keys are currently defined:
9220 BUNDLESPEC
9222 A "bundle specification" string that describes the type of the
9223 bundle.
9224 These are string values that are accepted by the "--type" argu‐
9226 ment of hg bundle.
9227 The values are parsed in strict mode, which means they must be
9229 of the "<compression>-<type>" form. See mercurial.ex‐
9230 change.parsebundlespec() for more details.
9231 hg debugbundle --spec can be used to print the bundle specifica‐
9233 tion string for a bundle file. The output of this command can be
9234 used verbatim for the value of BUNDLESPEC (it is already es‐
9235 caped).
9236 Clients will automatically filter out specifications that are
9238 unknown or unsupported so they won't attempt to download some‐
9239 thing that likely won't apply.
9240 The actual value doesn't impact client behavior beyond filter‐
9242 ing: clients will still sniff the bundle type from the header of
9243 downloaded files.
9244 Use of this key is highly recommended, as it allows clients to
9246 easily skip unsupported bundles. If this key is not defined, an
9247 old client may attempt to apply a bundle that it is incapable of
9248 reading.
9249 REQUIRESNI
9251 Whether Server Name Indication (SNI) is required to connect to
9252 the URL. SNI allows servers to use multiple certificates on the
9253 same IP. It is somewhat common in CDNs and other hosting
9254 providers. Older Python versions do not support SNI. Defining
9255 this attribute enables clients with older Python versions to
9256 filter this entry without experiencing an opaque SSL failure at
9257 connection time.
9258 If this is defined, it is important to advertise a non-SNI fall‐
9260 back URL or clients running old Python releases may not be able
9261 to clone with the clonebundles facility.
9262 Value should be "true".
9264 REQUIREDRAM
9266 Value specifies expected memory requirements to decode the pay‐
9267 load. Values can have suffixes for common bytes sizes. e.g.
9268 "64MB".
9269 This key is often used with zstd-compressed bundles using a high
9271 compression level / window size, which can require 100+ MB of
9272 memory to decode.
9273 heads Used for pull bundles. This contains the ; separated changeset
9275 hashes of the heads of the bundle content.
9276 bases Used for pull bundles. This contains the ; separated changeset
9278 hashes of the roots of the bundle content. This can be skipped
9279 if the bundle was created without --base.
9280 Manifests can contain multiple entries. Assuming metadata is defined,
9282 clients will filter entries from the manifest that they don't support.
9283 The remaining entries are optionally sorted by client preferences
9284 (ui.clonebundleprefers config option). The client then attempts to
9285 fetch the bundle at the first URL in the remaining list.
9286 Errors when downloading a bundle will fail the entire clone operation:
9288 clients do not automatically fall back to a traditional clone. The rea‐
9289 son for this is that if a server is using clone bundles, it is probably
9290 doing so because the feature is necessary to help it scale. In other
9291 words, there is an assumption that clone load will be offloaded to an‐
9292 other service and that the Mercurial server isn't responsible for serv‐
9293 ing this clone load. If that other service experiences issues and
9294 clients start mass falling back to the original Mercurial server, the
9295 added clone load could overwhelm the server due to unexpected load and
9296 effectively take it offline. Not having clients automatically fall back
9297 to cloning from the original server mitigates this scenario.
9298 Because there is no automatic Mercurial server fallback on failure of
9300 the bundle hosting service, it is important for server operators to
9301 view the bundle hosting service as an extension of the Mercurial server
9302 in terms of availability and service level agreements: if the bundle
9303 hosting service goes down, so does the ability for clients to clone.
9304 Note: clients will see a message informing them how to bypass the clone
9305 bundles facility when a failure occurs. So server operators should pre‐
9306 pare for some people to follow these instructions when a failure oc‐
9307 curs, thus driving more load to the original Mercurial server when the
9308 bundle hosting service fails.
9309 closehead
9311 close arbitrary heads without checking them out first
9312 Commands
9314 Change manipulation
9315 close-head
9316 close the given head revisions:
9317 hg close-head [OPTION]... [REV]...
9319 This is equivalent to checking out each revision in a clean tree and
9321 running hg commit --close-branch, except that it doesn't change the
9322 working directory.
9323 The commit message must be specified with -l or -m.
9325 Options:
9327 -m,--message <TEXT>
9329 use text as commit message
9330 -l,--logfile <FILE>
9332 read commit message from file
9333 -d,--date <DATE>
9335 record the specified date as commit date
9336 -u,--user <USER>
9338 record the specified user as committer
9339 -r,--rev <REV[+]>
9341 revision to check
9342 [+] marked option can be specified multiple times
9344 aliases: close-heads
9346 commitextras
9348 adds a new flag extras to commit (ADVANCED)
9349 convert
9351 import revisions from foreign VCS repositories into Mercurial
9352 Commands
9354 Uncategorized commands
9355 convert
9356 convert a foreign SCM repository to a Mercurial one.:
9357 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
9359 Accepted source formats [identifiers]:
9361 • Mercurial [hg]
9363 • CVS [cvs]
9365 • Darcs [darcs]
9367 • git [git]
9369 • Subversion [svn]
9371 • Monotone [mtn]
9373 • GNU Arch [gnuarch]
9375 • Bazaar [bzr]
9377 • Perforce [p4]
9379 Accepted destination formats [identifiers]:
9381 • Mercurial [hg]
9383 • Subversion [svn] (history on branches is not preserved)
9385 If no revision is given, all revisions will be converted. Otherwise,
9387 convert will only import up to the named revision (given in a format
9388 understood by the source).
9389 If no destination directory name is specified, it defaults to the base‐
9391 name of the source with -hg appended. If the destination repository
9392 doesn't exist, it will be created.
9393 By default, all sources except Mercurial will use --branchsort. Mercu‐
9395 rial uses --sourcesort to preserve original revision numbers order.
9396 Sort modes have the following effects:
9397 --branchsort
9399 convert from parent to child revision when possible, which means
9400 branches are usually converted one after the other. It generates
9401 more compact repositories.
9402 --datesort
9404 sort revisions by date. Converted repositories have good-looking
9405 changelogs but are often an order of magnitude larger than the
9406 same ones generated by --branchsort.
9407 --sourcesort
9409 try to preserve source revisions order, only supported by Mercu‐
9410 rial sources.
9411 --closesort
9413 try to move closed revisions as close as possible to parent
9414 branches, only supported by Mercurial sources.
9415 If REVMAP isn't given, it will be put in a default location
9417 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
9418 maps each source commit ID to the destination ID for that revision,
9419 like so:
9420 <source ID> <destination ID>
9422 If the file doesn't exist, it's automatically created. It's updated on
9424 each commit copied, so hg convert can be interrupted and can be run re‐
9425 peatedly to copy new commits.
9426 The authormap is a simple text file that maps each source commit author
9428 to a destination commit author. It is handy for source SCMs that use
9429 unix logins to identify authors (e.g.: CVS). One line per author map‐
9430 ping and the line format is:
9431 source author = destination author
9433 Empty lines and lines starting with a # are ignored.
9435 The filemap is a file that allows filtering and remapping of files and
9437 directories. Each line can contain one of the following directives:
9438 include path/to/file-or-dir
9440 exclude path/to/file-or-dir
9442 rename path/to/source path/to/destination
9444 Comment lines start with #. A specified path matches if it equals the
9446 full relative name of a file or one of its parent directories. The in‐
9447 clude or exclude directive with the longest matching path applies, so
9448 line order does not matter.
9449 The include directive causes a file, or all files under a directory, to
9451 be included in the destination repository. The default if there are no
9452 include statements is to include everything. If there are any include
9453 statements, nothing else is included. The exclude directive causes
9454 files or directories to be omitted. The rename directive renames a file
9455 or directory if it is converted. To rename from a subdirectory into the
9456 root of the repository, use . as the path to rename to.
9457 --full will make sure the converted changesets contain exactly the
9459 right files with the right content. It will make a full conversion of
9460 all files, not just the ones that have changed. Files that already are
9461 correct will not be changed. This can be used to apply filemap changes
9462 when converting incrementally. This is currently only supported for
9463 Mercurial and Subversion.
9464 The splicemap is a file that allows insertion of synthetic history,
9466 letting you specify the parents of a revision. This is useful if you
9467 want to e.g. give a Subversion merge two parents, or graft two discon‐
9468 nected series of history together. Each entry contains a key, followed
9469 by a space, followed by one or two comma-separated values:
9470 key parent1, parent2
9472 The key is the revision ID in the source revision control system whose
9474 parents should be modified (same format as a key in .hg/shamap). The
9475 values are the revision IDs (in either the source or destination revi‐
9476 sion control system) that should be used as the new parents for that
9477 node. For example, if you have merged "release-1.0" into "trunk", then
9478 you should specify the revision on "trunk" as the first parent and the
9479 one on the "release-1.0" branch as the second.
9480 The branchmap is a file that allows you to rename a branch when it is
9482 being brought in from whatever external repository. When used in con‐
9483 junction with a splicemap, it allows for a powerful combination to help
9484 fix even the most badly mismanaged repositories and turn them into
9485 nicely structured Mercurial repositories. The branchmap contains lines
9486 of the form:
9487 original_branch_name new_branch_name
9489 where "original_branch_name" is the name of the branch in the source
9491 repository, and "new_branch_name" is the name of the branch is the des‐
9492 tination repository. No whitespace is allowed in the new branch name.
9493 This can be used to (for instance) move code in one repository from
9494 "default" to a named branch.
9495 Mercurial Source
9497 The Mercurial source recognizes the following configuration options,
9498 which you can set on the command line with --config:
9499 convert.hg.ignoreerrors
9501 ignore integrity errors when reading. Use it to fix Mercurial
9502 repositories with missing revlogs, by converting from and to
9503 Mercurial. Default is False.
9504 convert.hg.saverev
9506 store original revision ID in changeset (forces target IDs to
9507 change). It takes a boolean argument and defaults to False.
9508 convert.hg.startrev
9510 specify the initial Mercurial revision. The default is 0.
9511 convert.hg.revs
9513 revset specifying the source revisions to convert.
9514 Bazaar Source
9516 The following options can be used with --config:
9517 convert.bzr.saverev
9519 whether to store the original Bazaar commit ID in the metadata
9520 of the destination commit. The default is True.
9521 CVS Source
9523 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to in‐
9524 dicate the starting point of what will be converted. Direct access to
9525 the repository files is not needed, unless of course the repository is
9526 :local:. The conversion uses the top level directory in the sandbox to
9527 find the CVS repository, and then uses CVS rlog commands to find files
9528 to convert. This means that unless a filemap is given, all files under
9529 the starting directory will be converted, and that any directory reor‐
9530 ganization in the CVS sandbox is ignored.
9531 The following options can be used with --config:
9533 convert.cvsps.cache
9535 Set to False to disable remote log caching, for testing and de‐
9536 bugging purposes. Default is True.
9537 convert.cvsps.fuzz
9539 Specify the maximum time (in seconds) that is allowed between
9540 commits with identical user and log message in a single change‐
9541 set. When very large files were checked in as part of a change‐
9542 set then the default may not be long enough. The default is 60.
9543 convert.cvsps.logencoding
9545 Specify encoding name to be used for transcoding CVS log mes‐
9546 sages. Multiple encoding names can be specified as a list (see
9547 hg help config.Syntax), but only the first acceptable encoding
9548 in the list is used per CVS log entries. This transcoding is ex‐
9549 ecuted before cvslog hook below.
9550 convert.cvsps.mergeto
9552 Specify a regular expression to which commit log messages are
9553 matched. If a match occurs, then the conversion process will in‐
9554 sert a dummy revision merging the branch on which this log mes‐
9555 sage occurs to the branch indicated in the regex. Default is
9556 {{mergetobranch ([-\w]+)}}
9557 convert.cvsps.mergefrom
9559 Specify a regular expression to which commit log messages are
9560 matched. If a match occurs, then the conversion process will add
9561 the most recent revision on the branch indicated in the regex as
9562 the second parent of the changeset. Default is {{mergefrombranch
9563 ([-\w]+)}}
9564 convert.localtimezone
9566 use local time (as determined by the TZ environment variable)
9567 for changeset date/times. The default is False (use UTC).
9568 hooks.cvslog
9570 Specify a Python function to be called at the end of gathering
9571 the CVS log. The function is passed a list with the log entries,
9572 and can modify the entries in-place, or add or delete them.
9573 hooks.cvschangesets
9575 Specify a Python function to be called after the changesets are
9576 calculated from the CVS log. The function is passed a list with
9577 the changeset entries, and can modify the changesets in-place,
9578 or add or delete them.
9579 An additional "debugcvsps" Mercurial command allows the builtin change‐
9581 set merging code to be run without doing a conversion. Its parameters
9582 and output are similar to that of cvsps 2.1. Please see the command
9583 help for more details.
9584 Subversion Source
9586 Subversion source detects classical trunk/branches/tags layouts. By
9587 default, the supplied svn://repo/path/ source URL is converted as a
9588 single branch. If svn://repo/path/trunk exists it replaces the default
9589 branch. If svn://repo/path/branches exists, its subdirectories are
9590 listed as possible branches. If svn://repo/path/tags exists, it is
9591 looked for tags referencing converted branches. Default trunk, branches
9592 and tags values can be overridden with following options. Set them to
9593 paths relative to the source URL, or leave them blank to disable auto
9594 detection.
9595 The following options can be set with --config:
9597 convert.svn.branches
9599 specify the directory containing branches. The default is
9600 branches.
9601 convert.svn.tags
9603 specify the directory containing tags. The default is tags.
9604 convert.svn.trunk
9606 specify the name of the trunk branch. The default is trunk.
9607 convert.localtimezone
9609 use local time (as determined by the TZ environment variable)
9610 for changeset date/times. The default is False (use UTC).
9611 Source history can be retrieved starting at a specific revision, in‐
9613 stead of being integrally converted. Only single branch conversions are
9614 supported.
9615 convert.svn.startrev
9617 specify start Subversion revision number. The default is 0.
9618 Git Source
9620 The Git importer converts commits from all reachable branches (refs in
9621 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
9622 are converted to bookmarks with the same name, with the leading
9623 'refs/heads' stripped. Git submodules are converted to Git subrepos in
9624 Mercurial.
9625 The following options can be set with --config:
9627 convert.git.similarity
9629 specify how similar files modified in a commit must be to be im‐
9630 ported as renames or copies, as a percentage between 0 (dis‐
9631 abled) and 100 (files must be identical). For example, 90 means
9632 that a delete/add pair will be imported as a rename if more than
9633 90% of the file hasn't changed. The default is 50.
9634 convert.git.findcopiesharder
9636 while detecting copies, look at all files in the working copy
9637 instead of just changed ones. This is very expensive for large
9638 projects, and is only effective when convert.git.similarity is
9639 greater than 0. The default is False.
9640 convert.git.renamelimit
9642 perform rename and copy detection up to this many changed files
9643 in a commit. Increasing this will make rename and copy detection
9644 more accurate but will significantly slow down computation on
9645 large projects. The option is only relevant if convert.git.simi‐
9646 larity is greater than 0. The default is 400.
9647 convert.git.committeractions
9649 list of actions to take when processing author and committer
9650 values.
9651 Git commits have separate author (who wrote the commit) and com‐
9653 mitter (who applied the commit) fields. Not all destinations
9654 support separate author and committer fields (including Mercu‐
9655 rial). This config option controls what to do with these author
9656 and committer fields during conversion.
9657 A value of messagedifferent will append a committer: ... line
9659 to the commit message if the Git committer is different from the
9660 author. The prefix of that line can be specified using the syn‐
9661 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
9662 ter:. When a prefix is specified, a space will always be in‐
9663 serted between the prefix and the value.
9664 messagealways behaves like messagedifferent except it will al‐
9666 ways result in a committer: ... line being appended to the com‐
9667 mit message. This value is mutually exclusive with messagedif‐
9668 ferent.
9669 dropcommitter will remove references to the committer. Only ref‐
9671 erences to the author will remain. Actions that add references
9672 to the committer will have no effect when this is set.
9673 replaceauthor will replace the value of the author field with
9675 the committer. Other actions that add references to the commit‐
9676 ter will still take effect when this is set.
9677 The default is messagedifferent.
9679 convert.git.extrakeys
9681 list of extra keys from commit metadata to copy to the destina‐
9682 tion. Some Git repositories store extra metadata in commits. By
9683 default, this non-default metadata will be lost during conver‐
9684 sion. Setting this config option can retain that metadata. Some
9685 built-in keys such as parent and branch are not allowed to be
9686 copied.
9687 convert.git.remoteprefix
9689 remote refs are converted as bookmarks with convert.git.re‐
9690 moteprefix as a prefix followed by a /. The default is 'remote'.
9691 convert.git.saverev
9693 whether to store the original Git commit ID in the metadata of
9694 the destination commit. The default is True.
9695 convert.git.skipsubmodules
9697 does not convert root level .gitmodules files or files with
9698 160000 mode indicating a submodule. Default is False.
9699 Perforce Source
9701 The Perforce (P4) importer can be given a p4 depot path or a client
9702 specification as source. It will convert all files in the source to a
9703 flat Mercurial repository, ignoring labels, branches and integrations.
9704 Note that when a depot path is given you then usually should specify a
9705 target directory, because otherwise the target may be named ...-hg.
9706 The following options can be set with --config:
9708 convert.p4.encoding
9710 specify the encoding to use when decoding standard output of the
9711 Perforce command line tool. The default is default system encod‐
9712 ing.
9713 convert.p4.startrev
9715 specify initial Perforce revision (a Perforce changelist num‐
9716 ber).
9717 Mercurial Destination
9719 The Mercurial destination will recognize Mercurial subrepositories in
9720 the destination directory, and update the .hgsubstate file automati‐
9721 cally if the destination subrepositories contain the
9722 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
9723 tories requires converting a single repository at a time, from the bot‐
9724 tom up.
9725 An example showing how to convert a repository with subrepositories:
9727 # so convert knows the type when it sees a non empty destination
9729 $ hg init converted
9730 $ hg convert orig/sub1 converted/sub1
9732 $ hg convert orig/sub2 converted/sub2
9733 $ hg convert orig converted
9734 The following options are supported:
9736 convert.hg.clonebranches
9738 dispatch source branches in separate clones. The default is
9739 False.
9740 convert.hg.tagsbranch
9742 branch name for tag revisions, defaults to default.
9743 convert.hg.usebranchnames
9745 preserve branch names. The default is True.
9746 convert.hg.sourcename
9748 records the given string as a 'convert_source' extra value on
9749 each commit made in the target repository. The default is None.
9750 convert.hg.preserve-hash
9752 only works with mercurial sources. Make convert prevent perfor‐
9753 mance improvement to the list of modified files in commits when
9754 such an improvement would cause the hash of a commit to change.
9755 The default is False.
9756 All Destinations
9758 All destination types accept the following options:
9759 convert.skiptags
9761 does not convert tags from the source repo to the target repo.
9762 The default is False.
9763 Subversion Destination
9765 Original commit dates are not preserved by default.
9766 convert.svn.dangerous-set-commit-dates
9768 preserve original commit dates, forcefully setting svn:date re‐
9769 vision properties. This option is DANGEROUS and may break some
9770 subversion functionality for the resulting repository (e.g. fil‐
9771 tering revisions with date ranges in svn log), as original com‐
9772 mit dates are not guaranteed to be monotonically increasing.
9773 For commit dates setting to work destination repository must have
9775 pre-revprop-change hook configured to allow setting of svn:date revi‐
9776 sion properties. See Subversion documentation for more details.
9777 Options:
9779 --authors <FILE>
9781 username mapping filename (DEPRECATED) (use --authormap instead)
9782 -s,--source-type <TYPE>
9784 source repository type
9785 -d,--dest-type <TYPE>
9787 destination repository type
9788 -r,--rev <REV[+]>
9790 import up to source revision REV
9791 -A,--authormap <FILE>
9793 remap usernames using this file
9794 --filemap <FILE>
9796 remap file names using contents of file
9797 --full apply filemap changes by converting all files again
9799 --splicemap <FILE>
9801 splice synthesized history into place
9802 --branchmap <FILE>
9804 change branch names while converting
9805 --branchsort
9807 try to sort changesets by branches
9808 --datesort
9810 try to sort changesets by date
9811 --sourcesort
9813 preserve source changesets order
9814 --closesort
9816 try to reorder closed revisions
9817 [+] marked option can be specified multiple times
9819 eol
9821 automatically manage newlines in repository files
9822 This extension allows you to manage the type of line endings (CRLF or
9824 LF) that are used in the repository and in the local working directory.
9825 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
9826 thereby letting everybody use their OS native line endings.
9827 The extension reads its configuration from a versioned .hgeol configu‐
9829 ration file found in the root of the working directory. The .hgeol file
9830 use the same syntax as all other Mercurial configuration files. It uses
9831 two sections, [patterns] and [repository].
9832 The [patterns] section specifies how line endings should be converted
9834 between the working directory and the repository. The format is speci‐
9835 fied by a file pattern. The first match is used, so put more specific
9836 patterns first. The available line endings are LF, CRLF, and BIN.
9837 Files with the declared format of CRLF or LF are always checked out and
9839 stored in the repository in that format and files declared to be binary
9840 (BIN) are left unchanged. Additionally, native is an alias for checking
9841 out in the platform's default line ending: LF on Unix (including Mac OS
9842 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
9843 Mercurial's default behavior; it is only needed if you need to override
9844 a later, more general pattern.
9845 The optional [repository] section specifies the line endings to use for
9847 files stored in the repository. It has a single setting, native, which
9848 determines the storage line endings for files declared as native in the
9849 [patterns] section. It can be set to LF or CRLF. The default is LF. For
9850 example, this means that on Windows, files configured as native (CRLF
9851 by default) will be converted to LF when stored in the repository.
9852 Files declared as LF, CRLF, or BIN in the [patterns] section are always
9853 stored as-is in the repository.
9854 Example versioned .hgeol file:
9856 [patterns]
9858 **.py = native
9859 **.vcproj = CRLF
9860 **.txt = native
9861 Makefile = LF
9862 **.jpg = BIN
9863 [repository]
9865 native = LF
9866 Note The rules will first apply when files are touched in the working
9868 directory, e.g. by updating to null and back to tip to touch all
9869 files.
9870 The extension uses an optional [eol] section read from both the normal
9872 Mercurial configuration files and the .hgeol file, with the latter
9873 overriding the former. You can use that section to control the overall
9874 behavior. There are three settings:
9875 • eol.native (default os.linesep) can be set to LF or CRLF to override
9877 the default interpretation of native for checkout. This can be used
9878 with hg archive on Unix, say, to generate an archive where files have
9879 line endings for Windows.
9880 • eol.only-consistent (default True) can be set to False to make the
9882 extension convert files with inconsistent EOLs. Inconsistent means
9883 that there is both CRLF and LF present in the file. Such files are
9884 normally not touched under the assumption that they have mixed EOLs
9885 on purpose.
9886 • eol.fix-trailing-newline (default False) can be set to True to ensure
9888 that converted files end with a EOL character (either \n or \r\n as
9889 per the configured patterns).
9890 The extension provides cleverencode: and cleverdecode: filters like the
9892 deprecated win32text extension does. This means that you can disable
9893 win32text and enable eol and your filters will still work. You only
9894 need to these filters until you have prepared a .hgeol file.
9895 The win32text.forbid* hooks provided by the win32text extension have
9897 been unified into a single hook named eol.checkheadshook. The hook will
9898 lookup the expected line endings from the .hgeol file, which means you
9899 must migrate to a .hgeol file first before using the hook. eol.check‐
9900 headshook only checks heads, intermediate invalid revisions will be
9901 pushed. To forbid them completely, use the eol.checkallhook hook. These
9902 hooks are best used as pretxnchangegroup hooks.
9903 See hg help patterns for more information about the glob patterns used.
9905 extdiff
9907 command to allow external programs to compare revisions
9908 The extdiff Mercurial extension allows you to use external programs to
9910 compare revisions, or revision with working directory. The external
9911 diff programs are called with a configurable set of options and two
9912 non-option arguments: paths to directories containing snapshots of
9913 files to compare.
9914 If there is more than one file being compared and the "child" revision
9916 is the working directory, any modifications made in the external diff
9917 program will be copied back to the working directory from the temporary
9918 directory.
9919 The extdiff extension also allows you to configure new diff commands,
9921 so you do not need to type hg extdiff -p kdiff3 always.
9922 [extdiff]
9924 # add new command that runs GNU diff(1) in 'context diff' mode
9925 cdiff = gdiff -Nprc5
9926 ## or the old way:
9927 #cmd.cdiff = gdiff
9928 #opts.cdiff = -Nprc5
9929 # add new command called meld, runs meld (no need to name twice). If
9931 # the meld executable is not available, the meld tool in [merge-tools]
9932 # will be used, if available
9933 meld =
9934 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
9936 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
9937 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
9938 # your .vimrc
9939 vimdiff = gvim -f "+next" \
9940 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
9941 Tool arguments can include variables that are expanded at runtime:
9943 $parent1, $plabel1 - filename, descriptive label of first parent
9945 $child, $clabel - filename, descriptive label of child revision
9946 $parent2, $plabel2 - filename, descriptive label of second parent
9947 $root - repository root
9948 $parent is an alias for $parent1.
9949 The extdiff extension will look in your [diff-tools] and [merge-tools]
9951 sections for diff tool arguments, when none are specified in [extdiff].
9952 [extdiff]
9954 kdiff3 =
9955 [diff-tools]
9957 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9958 If a program has a graphical interface, it might be interesting to tell
9960 Mercurial about it. It will prevent the program from being mistakenly
9961 used in a terminal-only environment (such as an SSH terminal session),
9962 and will make hg extdiff --per-file open multiple file diffs at once
9963 instead of one by one (if you still want to open file diffs one by one,
9964 you can use the --confirm option).
9965 Declaring that a tool has a graphical interface can be done with the
9967 gui flag next to where diffargs are specified:
9968 [diff-tools]
9970 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9971 kdiff3.gui = true
9972 You can use -I/-X and list of file or directory names like normal hg
9974 diff command. The extdiff extension makes snapshots of only needed
9975 files, so running the external diff program will actually be pretty
9976 fast (at least faster than having to compare the entire tree).
9977 Commands
9979 File content management
9980 extdiff
9981 use external program to diff repository (or selected files):
9982 hg extdiff [OPT]... [FILE]...
9984 Show differences between revisions for the specified files, using an
9986 external program. The default program used is diff, with default op‐
9987 tions "-Npru".
9988 To select a different program, use the -p/--program option. The program
9990 will be passed the names of two directories to compare, unless the
9991 --per-file option is specified (see below). To pass additional options
9992 to the program, use -o/--option. These will be passed before the names
9993 of the directories or files to compare.
9994 The --from, --to, and --change options work the same way they do for hg
9996 diff.
9997 The --per-file option runs the external program repeatedly on each file
9999 to diff, instead of once on two directories. By default, this happens
10000 one by one, where the next file diff is open in the external program
10001 only once the previous external program (for the previous file diff)
10002 has exited. If the external program has a graphical interface, it can
10003 open all the file diffs at once instead of one by one. See hg help -e
10004 extdiff for information about how to tell Mercurial that a given pro‐
10005 gram has a graphical interface.
10006 The --confirm option will prompt the user before each invocation of the
10008 external program. It is ignored if --per-file isn't specified.
10009 Options:
10011 -p,--program <CMD>
10013 comparison program to run
10014 -o,--option <OPT[+]>
10016 pass option to comparison program
10017 -r,--rev <REV[+]>
10019 revision (DEPRECATED)
10020 --from <REV1>
10022 revision to diff from
10023 --to <REV2>
10025 revision to diff to
10026 -c,--change <REV>
10028 change made by revision
10029 --per-file
10031 compare each file instead of revision snapshots
10032 --confirm
10034 prompt user before each external program invocation
10035 --patch
10037 compare patches for two revisions
10038 -I,--include <PATTERN[+]>
10040 include names matching the given patterns
10041 -X,--exclude <PATTERN[+]>
10043 exclude names matching the given patterns
10044 -S, --subrepos
10046 recurse into subrepositories
10047 [+] marked option can be specified multiple times
10049 factotum
10051 http authentication with factotum
10052 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
10054 platforms to provide authentication information for HTTP access. Con‐
10055 figuration entries specified in the auth section as well as authentica‐
10056 tion information provided in the repository URL are fully supported. If
10057 no prefix is specified, a value of "*" will be assumed.
10058 By default, keys are specified as:
10060 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
10062 If the factotum extension is unable to read the required key, one will
10064 be requested interactively.
10065 A configuration section is available to customize runtime behavior. By
10067 default, these entries are:
10068 [factotum]
10070 executable = /bin/auth/factotum
10071 mountpoint = /mnt/factotum
10072 service = hg
10073 The executable entry defines the full path to the factotum binary. The
10075 mountpoint entry defines the path to the factotum file service. Lastly,
10076 the service entry controls the service name used when reading keys.
10077 fastannotate
10079 yet another annotate implementation that might be faster (EXPERIMENTAL)
10080 The fastannotate extension provides a 'fastannotate' command that makes
10082 use of the linelog data structure as a cache layer and is expected to
10083 be faster than the vanilla 'annotate' if the cache is present.
10084 In most cases, fastannotate requires a setup that mainbranch is some
10086 pointer that always moves forward, to be most efficient.
10087 Using fastannotate together with linkrevcache would speed up building
10089 the annotate cache greatly. Run "debugbuildlinkrevcache" before "debug‐
10090 buildannotatecache".
10091 [fastannotate]
10093 # specify the main branch head. the internal linelog will only contain
10094 # the linear (ignoring p2) "mainbranch". since linelog cannot move
10095 # backwards without a rebuild, this should be something that always moves
10096 # forward, usually it is "master" or "@".
10097 mainbranch = master
10098 # fastannotate supports different modes to expose its feature.
10100 # a list of combination:
10101 # - fastannotate: expose the feature via the "fastannotate" command which
10102 # deals with everything in a most efficient way, and provides extra
10103 # features like --deleted etc.
10104 # - fctx: replace fctx.annotate implementation. note:
10105 # a. it is less efficient than the "fastannotate" command
10106 # b. it will make it practically impossible to access the old (disk
10107 # side-effect free) annotate implementation
10108 # c. it implies "hgweb".
10109 # - hgweb: replace hgweb's annotate implementation. conflict with "fctx".
10110 # (default: fastannotate)
10111 modes = fastannotate
10112 # default format when no format flags are used (default: number)
10114 defaultformat = changeset, user, date
10115 # serve the annotate cache via wire protocol (default: False)
10117 # tip: the .hg/fastannotate directory is portable - can be rsynced
10118 server = True
10119 # build annotate cache on demand for every client request (default: True)
10121 # disabling it could make server response faster, useful when there is a
10122 # cronjob building the cache.
10123 serverbuildondemand = True
10124 # update local annotate cache from remote on demand
10126 client = False
10127 # path to use when connecting to the remote server (default: default)
10129 remotepath = default
10130 # minimal length of the history of a file required to fetch linelog from
10132 # the server. (default: 10)
10133 clientfetchthreshold = 10
10134 # for "fctx" mode, always follow renames regardless of command line option.
10136 # this is a BC with the original command but will reduced the space needed
10137 # for annotate cache, and is useful for client-server setup since the
10138 # server will only provide annotate cache with default options (i.e. with
10139 # follow). do not affect "fastannotate" mode. (default: True)
10140 forcefollow = True
10141 # for "fctx" mode, always treat file as text files, to skip the "isbinary"
10143 # check. this is consistent with the "fastannotate" command and could help
10144 # to avoid a file fetch if remotefilelog is used. (default: True)
10145 forcetext = True
10146 # use unfiltered repo for better performance.
10148 unfilteredrepo = True
10149 # sacrifice correctness in some corner cases for performance. it does not
10151 # affect the correctness of the annotate cache being built. the option
10152 # is experimental and may disappear in the future (default: False)
10153 perfhack = True
10154 Commands
10156 Uncategorized commands
10157 fastexport
10158 export repositories as git fast-import stream
10159 Commands
10161 Change import/export
10162 fastexport
10163 export repository as git fast-import stream:
10164 hg fastexport [OPTION]... [REV]...
10166 This command lets you dump a repository as a human-readable text
10168 stream. It can be piped into corresponding import routines like "git
10169 fast-import". Incremental dumps can be created by using marks files.
10170 Options:
10172 -r,--rev <REV[+]>
10174 revisions to export
10175 -i,--import-marks <FILE>
10177 old marks file to read
10178 -e,--export-marks <FILE>
10180 new marks file to write
10181 -A,--authormap <FILE>
10183 remap usernames using this file
10184 [+] marked option can be specified multiple times
10186 fetch
10188 pull, update and merge in one command (DEPRECATED)
10189 Commands
10191 Remote repository management
10192 fetch
10193 pull changes from a remote repository, merge new changes if needed.:
10194 hg fetch [SOURCE]
10196 This finds all changes from the repository at the specified path or URL
10198 and adds them to the local repository.
10199 If the pulled changes add a new branch head, the head is automatically
10201 merged, and the result of the merge is committed. Otherwise, the work‐
10202 ing directory is updated to include the new changes.
10203 When a merge is needed, the working directory is first updated to the
10205 newly pulled changes. Local changes are then merged into the pulled
10206 changes. To switch the merge order, use --switch-parent.
10207 See hg help dates for a list of formats valid for -d/--date.
10209 Returns 0 on success.
10211 Options:
10213 -r,--rev <REV[+]>
10215 a specific revision you would like to pull
10216 --edit invoke editor on commit messages
10218 --force-editor
10220 edit commit message (DEPRECATED)
10221 --switch-parent
10223 switch parents when merging
10224 -m,--message <TEXT>
10226 use text as commit message
10227 -l,--logfile <FILE>
10229 read commit message from file
10230 -d,--date <DATE>
10232 record the specified date as commit date
10233 -u,--user <USER>
10235 record the specified user as committer
10236 -e,--ssh <CMD>
10238 specify ssh command to use
10239 --remotecmd <CMD>
10241 specify hg command to run on the remote side
10242 --insecure
10244 do not verify server certificate (ignoring web.cacerts config)
10245 [+] marked option can be specified multiple times
10247 fix
10249 rewrite file content in changesets or working copy (EXPERIMENTAL)
10250 Provides a command that runs configured tools on the contents of modi‐
10252 fied files, writing back any fixes to the working copy or replacing
10253 changesets.
10254 Here is an example configuration that causes hg fix to apply automatic
10256 formatting fixes to modified lines in C++ code:
10257 [fix]
10259 clang-format:command=clang-format --assume-filename={rootpath}
10260 clang-format:linerange=--lines={first}:{last}
10261 clang-format:pattern=set:**.cpp or **.hpp
10262 The :command suboption forms the first part of the shell command that
10264 will be used to fix a file. The content of the file is passed on stan‐
10265 dard input, and the fixed file content is expected on standard output.
10266 Any output on standard error will be displayed as a warning. If the
10267 exit status is not zero, the file will not be affected. A placeholder
10268 warning is displayed if there is a non-zero exit status but no standard
10269 error output. Some values may be substituted into the command:
10270 {rootpath} The path of the file being fixed, relative to the repo root
10272 {basename} The name of the file being fixed, without the directory path
10273 If the :linerange suboption is set, the tool will only be run if there
10275 are changed lines in a file. The value of this suboption is appended to
10276 the shell command once for every range of changed lines in the file.
10277 Some values may be substituted into the command:
10278 {first} The 1-based line number of the first line in the modified range
10280 {last} The 1-based line number of the last line in the modified range
10281 Deleted sections of a file will be ignored by :linerange, because there
10283 is no corresponding line range in the version being fixed.
10284 By default, tools that set :linerange will only be executed if there is
10286 at least one changed line range. This is meant to prevent accidents
10287 like running a code formatter in such a way that it unexpectedly refor‐
10288 mats the whole file. If such a tool needs to operate on unchanged
10289 files, it should set the :skipclean suboption to false.
10290 The :pattern suboption determines which files will be passed through
10292 each configured tool. See hg help patterns for possible values. How‐
10293 ever, all patterns are relative to the repo root, even if that text
10294 says they are relative to the current working directory. If there are
10295 file arguments to hg fix, the intersection of these patterns is used.
10296 There is also a configurable limit for the maximum size of file that
10298 will be processed by hg fix:
10299 [fix]
10301 maxfilesize = 2MB
10302 Normally, execution of configured tools will continue after a failure
10304 (indicated by a non-zero exit status). It can also be configured to
10305 abort after the first such failure, so that no files will be affected
10306 if any tool fails. This abort will also cause hg fix to exit with a
10307 non-zero status:
10308 [fix]
10310 failure = abort
10311 When multiple tools are configured to affect a file, they execute in an
10313 order defined by the :priority suboption. The priority suboption has a
10314 default value of zero for each tool. Tools are executed in order of de‐
10315 scending priority. The execution order of tools with equal priority is
10316 unspecified. For example, you could use the 'sort' and 'head' utilities
10317 to keep only the 10 smallest numbers in a text file by ensuring that
10318 'sort' runs before 'head':
10319 [fix]
10321 sort:command = sort -n
10322 head:command = head -n 10
10323 sort:pattern = numbers.txt
10324 head:pattern = numbers.txt
10325 sort:priority = 2
10326 head:priority = 1
10327 To account for changes made by each tool, the line numbers used for in‐
10329 cremental formatting are recomputed before executing the next tool. So,
10330 each tool may see different values for the arguments added by the :lin‐
10331 erange suboption.
10332 Each fixer tool is allowed to return some metadata in addition to the
10334 fixed file content. The metadata must be placed before the file content
10335 on stdout, separated from the file content by a zero byte. The metadata
10336 is parsed as a JSON value (so, it should be UTF-8 encoded and contain
10337 no zero bytes). A fixer tool is expected to produce this metadata en‐
10338 coding if and only if the :metadata suboption is true:
10339 [fix]
10341 tool:command = tool --prepend-json-metadata
10342 tool:metadata = true
10343 The metadata values are passed to hooks, which can be used to print
10345 summaries or perform other post-fixing work. The supported hooks are:
10346 "postfixfile"
10348 Run once for each file in each revision where any fixer tools made changes
10349 to the file content. Provides "$HG_REV" and "$HG_PATH" to identify the file,
10350 and "$HG_METADATA" with a map of fixer names to metadata values from fixer
10351 tools that affected the file. Fixer tools that didn't affect the file have a
10352 value of None. Only fixer tools that executed are present in the metadata.
10353 "postfix"
10355 Run once after all files and revisions have been handled. Provides
10356 "$HG_REPLACEMENTS" with information about what revisions were created and
10357 made obsolete. Provides a boolean "$HG_WDIRWRITTEN" to indicate whether any
10358 files in the working copy were updated. Provides a list "$HG_METADATA"
10359 mapping fixer tool names to lists of metadata values returned from
10360 executions that modified a file. This aggregates the same metadata
10361 previously passed to the "postfixfile" hook.
10362 Fixer tools are run in the repository's root directory. This allows
10364 them to read configuration files from the working copy, or even write
10365 to the working copy. The working copy is not updated to match the re‐
10366 vision being fixed. In fact, several revisions may be fixed in paral‐
10367 lel. Writes to the working copy are not amended into the revision being
10368 fixed; fixer tools should always write fixed file content back to std‐
10369 out as documented above.
10370 Commands
10372 File content management
10373 fix
10374 rewrite file content in changesets or working directory:
10375 hg fix [OPTION]... [FILE]...
10377 Runs any configured tools to fix the content of files. Only affects
10379 files with changes, unless file arguments are provided. Only affects
10380 changed lines of files, unless the --whole flag is used. Some tools may
10381 always affect the whole file regardless of --whole.
10382 If --working-dir is used, files with uncommitted changes in the working
10384 copy will be fixed. Note that no backup are made.
10385 If revisions are specified with --source, those revisions and their de‐
10387 scendants will be checked, and they may be replaced with new revisions
10388 that have fixed file content. By automatically including the descen‐
10389 dants, no merging, rebasing, or evolution will be required. If an an‐
10390 cestor of the working copy is included, then the working copy itself
10391 will also be fixed, and the working copy will be updated to the fixed
10392 parent.
10393 When determining what lines of each file to fix at each revision, the
10395 whole set of revisions being fixed is considered, so that fixes to ear‐
10396 lier revisions are not forgotten in later ones. The --base flag can be
10397 used to override this default behavior, though it is not usually desir‐
10398 able to do so.
10399 Options:
10401 --all fix all non-public non-obsolete revisions
10403 --base <REV[+]>
10405 revisions to diff against (overrides automatic selection, and
10406 applies to every revision being fixed)
10407 -r,--rev <REV[+]>
10409 revisions to fix (ADVANCED)
10410 -s,--source <REV[+]>
10412 fix the specified revisions and their descendants
10413 -w, --working-dir
10415 fix the working directory
10416 --whole
10418 always fix every line of a file
10419 [+] marked option can be specified multiple times
10421 fsmonitor
10423 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
10424 Integrates the file-watching program Watchman with Mercurial to produce
10426 faster status results.
10427 On a particular Linux system, for a real-world repository with over
10429 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
10430 the same system, with fsmonitor it takes about 0.3 seconds.
10431 fsmonitor requires no configuration -- it will tell Watchman about your
10433 repository as necessary. You'll need to install Watchman from
10434 https://facebook.github.io/watchman/ and make sure it is in your PATH.
10435 fsmonitor is incompatible with the largefiles and eol extensions, and
10437 will disable itself if any of those are active.
10438 The following configuration options exist:
10440 [fsmonitor]
10442 mode = {off, on, paranoid}
10443 When mode = off, fsmonitor will disable itself (similar to not loading
10445 the extension at all). When mode = on, fsmonitor will be enabled (the
10446 default). When mode = paranoid, fsmonitor will query both Watchman and
10447 the filesystem, and ensure that the results are consistent.
10448 [fsmonitor]
10450 timeout = (float)
10451 A value, in seconds, that determines how long fsmonitor will wait for
10453 Watchman to return results. Defaults to 2.0.
10454 [fsmonitor]
10456 blacklistusers = (list of userids)
10457 A list of usernames for which fsmonitor will disable itself altogether.
10459 [fsmonitor]
10461 walk_on_invalidate = (boolean)
10462 Whether or not to walk the whole repo ourselves when our cached state
10464 has been invalidated, for example when Watchman has been restarted or
10465 .hgignore rules have been changed. Walking the repo in that case can
10466 result in competing for I/O with Watchman. For large repos it is recom‐
10467 mended to set this value to false. You may wish to set this to true if
10468 you have a very fast filesystem that can outpace the IPC overhead of
10469 getting the result data for the full repo from Watchman. Defaults to
10470 false.
10471 [fsmonitor]
10473 warn_when_unused = (boolean)
10474 Whether to print a warning during certain operations when fsmonitor
10476 would be beneficial to performance but isn't enabled.
10477 [fsmonitor]
10479 warn_update_file_count = (integer)
10480 # or when mercurial is built with rust support
10481 warn_update_file_count_rust = (integer)
10482 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
10484 be printed during working directory updates if this many files will be
10485 created.
10486 git
10488 grant Mercurial the ability to operate on Git repositories. (EXPERIMEN‐
10489 TAL)
10490 This is currently super experimental. It probably will consume your
10492 firstborn a la Rumpelstiltskin, etc.
10493 githelp
10495 try mapping git commands to Mercurial commands
10496 Tries to map a given git command to a Mercurial command:
10498 $ hg githelp -- git checkout master hg update master
10500 If an unknown command or parameter combination is detected, an error is
10502 produced.
10503 Commands
10505 Help
10506 githelp
10507 suggests the Mercurial equivalent of the given git command:
10508 hg githelp
10510 Usage: hg githelp -- <git command>
10512 aliases: git
10514 gpg
10516 commands to sign and verify changesets
10517 Commands
10519 Signing changes (GPG)
10520 sigcheck
10521 verify all the signatures there may be for a particular revision:
10522 hg sigcheck REV
10524 verify all the signatures there may be for a particular revision
10526 sign
10528 add a signature for the current or given revision:
10529 hg sign [OPTION]... [REV]...
10531 If no revision is given, the parent of the working directory is used,
10533 or tip if no revision is checked out.
10534 The gpg.cmd config setting can be used to specify the command to run. A
10536 default key can be specified with gpg.key.
10537 See hg help dates for a list of formats valid for -d/--date.
10539 Options:
10541 -l, --local
10543 make the signature local
10544 -f, --force
10546 sign even if the sigfile is modified
10547 --no-commit
10549 do not commit the sigfile after signing
10550 -k,--key <ID>
10552 the key id to sign with
10553 -m,--message <TEXT>
10555 use text as commit message
10556 -e, --edit
10558 invoke editor on commit messages
10559 -d,--date <DATE>
10561 record the specified date as commit date
10562 -u,--user <USER>
10564 record the specified user as committer
10565 sigs
10567 list signed changesets:
10568 hg sigs
10570 list signed changesets
10572 graphlog
10574 command to view revision graphs from a shell (DEPRECATED)
10575 The functionality of this extension has been include in core Mercurial
10577 since version 2.3. Please use hg log -G ... instead.
10578 This extension adds a --graph option to the incoming, outgoing and log
10580 commands. When this options is given, an ASCII representation of the
10581 revision graph is also shown.
10582 Commands
10584 Change navigation
10585 glog
10586 show revision history alongside an ASCII revision graph:
10587 hg glog [OPTION]... [FILE]
10589 Print a revision history alongside a revision graph drawn with ASCII
10591 characters.
10592 Nodes printed as an @ character are parents of the working directory.
10594 This is an alias to hg log -G.
10596 Options:
10598 -f, --follow
10600 follow changeset history, or file history across copies and re‐
10601 names
10602 --follow-first
10604 only follow the first parent of merge changesets (DEPRECATED)
10605 -d,--date <DATE>
10607 show revisions matching date spec
10608 -C, --copies
10610 show copied files
10611 -k,--keyword <TEXT[+]>
10613 do case-insensitive search for a given text
10614 -r,--rev <REV[+]>
10616 show the specified revision or revset
10617 --removed
10619 include revisions where files were removed
10620 -m, --only-merges
10622 show only merges (DEPRECATED)
10623 -u,--user <USER[+]>
10625 revisions committed by user
10626 --only-branch <BRANCH[+]>
10628 show only changesets within the given named branch (DEPRECATED)
10629 -b,--branch <BRANCH[+]>
10631 show changesets within the given named branch
10632 -P,--prune <REV[+]>
10634 do not display revision or any of its ancestors
10635 -p, --patch
10637 show patch
10638 -g, --git
10640 use git extended diff format
10641 -l,--limit <NUM>
10643 limit number of changes displayed
10644 -M, --no-merges
10646 do not show merges
10647 --stat output diffstat-style summary of changes
10649 -G, --graph
10651 show the revision DAG
10652 --style <STYLE>
10654 display using template map file (DEPRECATED)
10655 -T,--template <TEMPLATE>
10657 display with template
10658 -I,--include <PATTERN[+]>
10660 include names matching the given patterns
10661 -X,--exclude <PATTERN[+]>
10663 exclude names matching the given patterns
10664 [+] marked option can be specified multiple times
10666 hgk
10668 browse the repository in a graphical way
10669 The hgk extension allows browsing the history of a repository in a
10671 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
10672 distributed with Mercurial.)
10673 hgk consists of two parts: a Tcl script that does the displaying and
10675 querying of information, and an extension to Mercurial named hgk.py,
10676 which provides hooks for hgk to get information. hgk can be found in
10677 the contrib directory, and the extension is shipped in the hgext repos‐
10678 itory, and needs to be enabled.
10679 The hg view command will launch the hgk Tcl script. For this command to
10681 work, hgk must be in your search path. Alternately, you can specify the
10682 path to hgk in your configuration file:
10683 [hgk]
10685 path = /location/of/hgk
10686 hgk can make use of the extdiff extension to visualize revisions. As‐
10688 suming you had already configured extdiff vdiff command, just add:
10689 [hgk]
10691 vdiff=vdiff
10692 Revisions context menu will now display additional entries to fire vd‐
10694 iff on hovered and selected revisions.
10695 Commands
10697 Change navigation
10698 view
10699 start interactive history viewer:
10700 hg view [-l LIMIT] [REVRANGE]
10702 start interactive history viewer
10704 Options:
10706 -l,--limit <NUM>
10708 limit number of changes displayed
10709 Uncategorized commands
10711 highlight
10712 syntax highlighting for hgweb (requires Pygments)
10713 It depends on the Pygments syntax highlighting library:
10715 http://pygments.org/
10716 There are the following configuration options:
10718 [web]
10720 pygments_style = <style> (default: colorful)
10721 highlightfiles = <fileset> (default: size('<5M'))
10722 highlightonlymatchfilename = <bool> (default False)
10723 highlightonlymatchfilename will only highlight files if their type
10725 could be identified by their filename. When this is not enabled (the
10726 default), Pygments will try very hard to identify the file type from
10727 content and any match (even matches with a low confidence score) will
10728 be used.
10729 histedit
10731 interactive history editing
10732 With this extension installed, Mercurial gains one new command: histe‐
10734 dit. Usage is as follows, assuming the following history:
10735 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
10737 | Add delta
10738 |
10739 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
10740 | Add gamma
10741 |
10742 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
10743 | Add beta
10744 |
10745 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10746 Add alpha
10747 If you were to run hg histedit c561b4e977df, you would see the follow‐
10749 ing file open in your editor:
10750 pick c561b4e977df Add beta
10752 pick 030b686bedc4 Add gamma
10753 pick 7c2fd3b9020c Add delta
10754 # Edit history between c561b4e977df and 7c2fd3b9020c
10756 #
10757 # Commits are listed from least to most recent
10758 #
10759 # Commands:
10760 # p, pick = use commit
10761 # e, edit = use commit, but allow edits before making new commit
10762 # f, fold = use commit, but combine it with the one above
10763 # r, roll = like fold, but discard this commit's description and date
10764 # d, drop = remove commit from history
10765 # m, mess = edit commit message without changing commit content
10766 # b, base = checkout changeset and apply further changesets from there
10767 #
10768 In this file, lines beginning with # are ignored. You must specify a
10770 rule for each revision in your history. For example, if you had meant
10771 to add gamma before beta, and then wanted to add delta in the same re‐
10772 vision as beta, you would reorganize the file to look like this:
10773 pick 030b686bedc4 Add gamma
10775 pick c561b4e977df Add beta
10776 fold 7c2fd3b9020c Add delta
10777 # Edit history between c561b4e977df and 7c2fd3b9020c
10779 #
10780 # Commits are listed from least to most recent
10781 #
10782 # Commands:
10783 # p, pick = use commit
10784 # e, edit = use commit, but allow edits before making new commit
10785 # f, fold = use commit, but combine it with the one above
10786 # r, roll = like fold, but discard this commit's description and date
10787 # d, drop = remove commit from history
10788 # m, mess = edit commit message without changing commit content
10789 # b, base = checkout changeset and apply further changesets from there
10790 #
10791 At which point you close the editor and histedit starts working. When
10793 you specify a fold operation, histedit will open an editor when it
10794 folds those revisions together, offering you a chance to clean up the
10795 commit message:
10796 Add beta
10798 ***
10799 Add delta
10800 Edit the commit message to your liking, then close the editor. The date
10802 used for the commit will be the later of the two commits' dates. For
10803 this example, let's assume that the commit message was changed to Add
10804 beta and delta. After histedit has run and had a chance to remove any
10805 old or temporary revisions it needed, the history looks like this:
10806 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
10808 | Add beta and delta.
10809 |
10810 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10811 | Add gamma
10812 |
10813 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10814 Add alpha
10815 Note that histedit does not remove any revisions (even its own tempo‐
10817 rary ones) until after it has completed all the editing operations, so
10818 it will probably perform several strip operations when it's done. For
10819 the above example, it had to run strip twice. Strip can be slow depend‐
10820 ing on a variety of factors, so you might need to be a little patient.
10821 You can choose to keep the original revisions by passing the --keep
10822 flag.
10823 The edit operation will drop you back to a command prompt, allowing you
10825 to edit files freely, or even use hg record to commit some changes as a
10826 separate commit. When you're done, any remaining uncommitted changes
10827 will be committed as well. When done, run hg histedit --continue to
10828 finish this step. If there are uncommitted changes, you'll be prompted
10829 for a new commit message, but the default commit message will be the
10830 original message for the edit ed revision, and the date of the original
10831 commit will be preserved.
10832 The message operation will give you a chance to revise a commit message
10834 without changing the contents. It's a shortcut for doing edit immedi‐
10835 ately followed by hg histedit --continue`.
10836 If histedit encounters a conflict when moving a revision (while han‐
10838 dling pick or fold), it'll stop in a similar manner to edit with the
10839 difference that it won't prompt you for a commit message when done. If
10840 you decide at this point that you don't like how much work it will be
10841 to rearrange history, or that you made a mistake, you can use hg histe‐
10842 dit --abort to abandon the new changes you have made and return to the
10843 state before you attempted to edit your history.
10844 If we clone the histedit-ed example repository above and add four more
10846 changes, such that we have the following history:
10847 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
10849 | Add theta
10850 |
10851 o 5 140988835471 2009-04-27 18:04 -0500 stefan
10852 | Add eta
10853 |
10854 o 4 122930637314 2009-04-27 18:04 -0500 stefan
10855 | Add zeta
10856 |
10857 o 3 836302820282 2009-04-27 18:04 -0500 stefan
10858 | Add epsilon
10859 |
10860 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
10861 | Add beta and delta.
10862 |
10863 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10864 | Add gamma
10865 |
10866 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10867 Add alpha
10868 If you run hg histedit --outgoing on the clone then it is the same as
10870 running hg histedit 836302820282. If you need plan to push to a reposi‐
10871 tory that Mercurial does not detect to be related to the source repo,
10872 you can add a --force option.
10873 Config
10875 Histedit rule lines are truncated to 80 characters by default. You can
10876 customize this behavior by setting a different length in your configu‐
10877 ration file:
10878 [histedit]
10880 linelen = 120 # truncate rule lines at 120 characters
10881 The summary of a change can be customized as well:
10883 [histedit]
10885 summary-template = '{rev} {bookmarks} {desc|firstline}'
10886 The customized summary should be kept short enough that rule lines will
10888 fit in the configured line length. See above if that requires cus‐
10889 tomization.
10890 hg histedit attempts to automatically choose an appropriate base revi‐
10892 sion to use. To change which base revision is used, define a revset in
10893 your configuration file:
10894 [histedit]
10896 defaultrev = only(.) & draft()
10897 By default each edited revision needs to be present in histedit com‐
10899 mands. To remove revision you need to use drop operation. You can con‐
10900 figure the drop to be implicit for missing commits by adding:
10901 [histedit]
10903 dropmissing = True
10904 By default, histedit will close the transaction after each action. For
10906 performance purposes, you can configure histedit to use a single trans‐
10907 action across the entire histedit. WARNING: This setting introduces a
10908 significant risk of losing the work you've done in a histedit if the
10909 histedit aborts unexpectedly:
10910 [histedit]
10912 singletransaction = True
10913 Commands
10915 Change manipulation
10916 histedit
10917 interactively edit changeset history:
10918 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
10920 This command lets you edit a linear series of changesets (up to and in‐
10922 cluding the working directory, which should be clean). You can:
10923 • pick to [re]order a changeset
10925 • drop to omit changeset
10927 • mess to reword the changeset commit message
10929 • fold to combine it with the preceding changeset (using the later
10931 date)
10932 • roll like fold, but discarding this commit's description and date
10934 • edit to edit this changeset (preserving date)
10936 • base to checkout changeset and apply further changesets from there
10938 There are a number of ways to select the root changeset:
10940 • Specify ANCESTOR directly
10942 • Use --outgoing -- it will be the first linear changeset not included
10944 in destination. (See hg help config.paths.default-push)
10945 • Otherwise, the value from the "histedit.defaultrev" config option is
10947 used as a revset to select the base revision when ANCESTOR is not
10948 specified. The first revision returned by the revset is used. By de‐
10949 fault, this selects the editable history that is unique to the ances‐
10950 try of the working directory.
10951 If you use --outgoing, this command will abort if there are ambiguous
10953 outgoing revisions. For example, if there are multiple branches con‐
10954 taining outgoing revisions.
10955 Use "min(outgoing() and ::.)" or similar revset specification instead
10957 of --outgoing to specify edit target revision exactly in such ambiguous
10958 situation. See hg help revsets for detail about selecting revisions.
10959 Examples:
10961 • A number of changes have been made. Revision 3 is no longer
10963 needed.
10964 Start history editing from revision 3:
10966 hg histedit -r 3
10968 An editor opens, containing the list of revisions, with specific
10970 actions specified:
10971 pick 5339bf82f0ca 3 Zworgle the foobar
10973 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10974 pick 0a9639fcda9d 5 Morgify the cromulancy
10975 Additional information about the possible actions to take appears
10977 below the list of revisions.
10978 To remove revision 3 from the history, its action (at the begin‐
10980 ning of the relevant line) is changed to 'drop':
10981 drop 5339bf82f0ca 3 Zworgle the foobar
10983 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10984 pick 0a9639fcda9d 5 Morgify the cromulancy
10985 • A number of changes have been made. Revision 2 and 4 need to be
10987 swapped.
10988 Start history editing from revision 2:
10990 hg histedit -r 2
10992 An editor opens, containing the list of revisions, with specific
10994 actions specified:
10995 pick 252a1af424ad 2 Blorb a morgwazzle
10997 pick 5339bf82f0ca 3 Zworgle the foobar
10998 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10999 To swap revision 2 and 4, its lines are swapped in the editor:
11001 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11003 pick 5339bf82f0ca 3 Zworgle the foobar
11004 pick 252a1af424ad 2 Blorb a morgwazzle
11005 Returns 0 on success, 1 if user intervention is required (not only for
11007 intentional "edit" command, but also for resolving unexpected con‐
11008 flicts).
11009 Options:
11011 --commands <FILE>
11013 read history edits from the specified file
11014 -c, --continue
11016 continue an edit already in progress
11017 --edit-plan
11019 edit remaining actions list
11020 -k, --keep
11022 don't strip old nodes after edit is complete
11023 --abort
11025 abort an edit in progress
11026 -o, --outgoing
11028 changesets not found in destination
11029 -f, --force
11031 force outgoing even for unrelated repositories
11032 -r,--rev <REV[+]>
11034 first revision to be edited
11035 -T,--template <TEMPLATE>
11037 display with template
11038 [+] marked option can be specified multiple times
11040 hooklib
11042 collection of simple hooks for common tasks (EXPERIMENTAL)
11043 This extension provides a number of simple hooks to handle issues com‐
11045 monly found in repositories with many contributors: - email notifica‐
11046 tion when changesets move from draft to public phase - email notifica‐
11047 tion when changesets are obsoleted - enforcement of draft phase for all
11048 incoming changesets - enforcement of a no-branch-merge policy - en‐
11049 forcement of a no-multiple-heads policy
11050 The implementation of the hooks is subject to change, e.g. whether to
11052 implement them as individual hooks or merge them into the notify exten‐
11053 sion as option. The functionality itself is planned to be supported
11054 long-term.
11055 infinitepush
11057 store some pushes in a remote blob store on the server (EXPERIMEN‐
11058 TAL)
11059 IMPORTANT: if you use this extension, please contact
11061 mercurial-devel@mercurial-scm.org ASAP. This extension is believed to
11062 be unused and barring learning of users of this functionality, we will
11063 delete this code at the end of 2020.
11064 [infinitepush] # Server-side and client-side option. Pattern of the
11066 infinitepush bookmark branchpattern = PATTERN
11067 # Server or client server = False
11069 # Server-side option. Possible values: 'disk' or 'sql'. Fails if not
11071 set indextype = disk
11072 # Server-side option. Used only if indextype=sql. # Format:
11074 'IP:PORT:DB_NAME:USER:PASSWORD' sqlhost = IP:PORT:DB_NAME:USER:PASS‐
11075 WORD
11076 # Server-side option. Used only if indextype=disk. # Filesystem
11078 path to the index store indexpath = PATH
11079 # Server-side option. Possible values: 'disk' or 'external' # Fails
11081 if not set storetype = disk
11082 # Server-side option. # Path to the binary that will save bundle to
11084 the bundlestore # Formatted cmd line will be passed to it (see
11085 put_args) put_binary = put
11086 # Serser-side option. Used only if storetype=external. # Format
11088 cmd-line string for put binary. Placeholder: {filename} put_args =
11089 {filename}
11090 # Server-side option. # Path to the binary that get bundle from the
11092 bundlestore. # Formatted cmd line will be passed to it (see
11093 get_args) get_binary = get
11094 # Serser-side option. Used only if storetype=external. # Format
11096 cmd-line string for get binary. Placeholders: {filename} {handle}
11097 get_args = {filename} {handle}
11098 # Server-side option logfile = FIlE
11100 # Server-side option loglevel = DEBUG
11102 # Server-side option. Used only if indextype=sql. # Sets mysql
11104 wait_timeout option. waittimeout = 300
11105 # Server-side option. Used only if indextype=sql. # Sets mysql inn‐
11107 odb_lock_wait_timeout option. locktimeout = 120
11108 # Server-side option. Used only if indextype=sql. # Name of the
11110 repository reponame = ''
11111 # Client-side option. Used by --list-remote option. List of remote
11113 scratch # patterns to list if no patterns are specified. default‐
11114 remotepatterns = ['*']
11115 # Instructs infinitepush to forward all received bundle2 parts to
11117 the # bundle for storage. Defaults to False. storeallparts = True
11118 # routes each incoming push to the bundlestore. defaults to False
11120 pushtobundlestore = True
11121 [remotenames] # Client-side option # This option should be set only
11123 if remotenames extension is enabled. # Whether remote bookmarks are
11124 tracked by remotenames extension. bookmarks = True
11125 journal
11127 track previous positions of bookmarks (EXPERIMENTAL)
11128 This extension adds a new command: hg journal, which shows you where
11130 bookmarks were previously located.
11131 Commands
11133 Change organization
11134 journal
11135 show the previous position of bookmarks and the working copy:
11136 hg journal [OPTION]... [BOOKMARKNAME]
11138 The journal is used to see the previous commits that bookmarks and the
11140 working copy pointed to. By default the previous locations for the
11141 working copy. Passing a bookmark name will show all the previous posi‐
11142 tions of that bookmark. Use the --all switch to show previous locations
11143 for all bookmarks and the working copy; each line will then include the
11144 bookmark name, or '.' for the working copy, as well.
11145 If name starts with re:, the remainder of the name is treated as a reg‐
11147 ular expression. To match a name that actually starts with re:, use the
11148 prefix literal:.
11149 By default hg journal only shows the commit hash and the command that
11151 was running at that time. -v/--verbose will show the prior hash, the
11152 user, and the time at which it happened.
11153 Use -c/--commits to output log information on each commit hash; at this
11155 point you can use the usual --patch, --git, --stat and --template
11156 switches to alter the log output for these.
11157 hg journal -T json can be used to produce machine readable output.
11159 Options:
11161 --all show history for all names
11163 -c, --commits
11165 show commit metadata
11166 -p, --patch
11168 show patch
11169 -g, --git
11171 use git extended diff format
11172 -l,--limit <NUM>
11174 limit number of changes displayed
11175 --stat output diffstat-style summary of changes
11177 --style <STYLE>
11179 display using template map file (DEPRECATED)
11180 -T,--template <TEMPLATE>
11182 display with template
11183 keyword
11185 expand keywords in tracked files
11186 This extension expands RCS/CVS-like or self-customized $Keywords$ in
11188 tracked text files selected by your configuration.
11189 Keywords are only expanded in local repositories and not stored in the
11191 change history. The mechanism can be regarded as a convenience for the
11192 current user or for archive distribution.
11193 Keywords expand to the changeset data pertaining to the latest change
11195 relative to the working directory parent of each file.
11196 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
11198 sections of hgrc files.
11199 Example:
11201 [keyword]
11203 # expand keywords in every python file except those matching "x*"
11204 **.py =
11205 x* = ignore
11206 [keywordset]
11208 # prefer svn- over cvs-like default keywordmaps
11209 svn = True
11210 Note The more specific you are in your filename patterns the less you
11212 lose speed in huge repositories.
11213 For [keywordmaps] template mapping and expansion demonstration and con‐
11215 trol run hg kwdemo. See hg help templates for a list of available tem‐
11216 plates and filters.
11217 Three additional date template filters are provided:
11219 utcdate
11221 "2006/09/18 15:13:13"
11223 svnutcdate
11225 "2006-09-18 15:13:13Z"
11227 svnisodate
11229 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
11231 The default template mappings (view with hg kwdemo -d) can be replaced
11233 with customized keywords and templates. Again, run hg kwdemo to control
11234 the results of your configuration changes.
11235 Before changing/disabling active keywords, you must run hg kwshrink to
11237 avoid storing expanded keywords in the change history.
11238 To force expansion after enabling it, or a configuration change, run hg
11240 kwexpand.
11241 Expansions spanning more than one line and incremental expansions, like
11243 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
11244 expands to the first line of the changeset description.
11245 Commands
11247 Uncategorized commands
11248 kwdemo
11249 print [keywordmaps] configuration and an expansion example:
11250 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
11252 Show current, custom, or default keyword template maps and their expan‐
11254 sions.
11255 Extend the current configuration by specifying maps as arguments and
11257 using -f/--rcfile to source an external hgrc file.
11258 Use -d/--default to disable current configuration.
11260 See hg help templates for information on templates and filters.
11262 Options:
11264 -d, --default
11266 show default keyword template maps
11267 -f,--rcfile <FILE>
11269 read maps from rcfile
11270 kwexpand
11272 expand keywords in the working directory:
11273 hg kwexpand [OPTION]... [FILE]...
11275 Run after (re)enabling keyword expansion.
11277 kwexpand refuses to run if given files contain local changes.
11279 Options:
11281 -I,--include <PATTERN[+]>
11283 include names matching the given patterns
11284 -X,--exclude <PATTERN[+]>
11286 exclude names matching the given patterns
11287 [+] marked option can be specified multiple times
11289 kwfiles
11291 show files configured for keyword expansion:
11292 hg kwfiles [OPTION]... [FILE]...
11294 List which files in the working directory are matched by the [keyword]
11296 configuration patterns.
11297 Useful to prevent inadvertent keyword expansion and to speed up execu‐
11299 tion by including only files that are actual candidates for expansion.
11300 See hg help keyword on how to construct patterns both for inclusion and
11302 exclusion of files.
11303 With -A/--all and -v/--verbose the codes used to show the status of
11305 files are:
11306 K = keyword expansion candidate
11308 k = keyword expansion candidate (not tracked)
11309 I = ignored
11310 i = ignored (not tracked)
11311 Options:
11313 -A, --all
11315 show keyword status flags of all files
11316 -i, --ignore
11318 show files excluded from expansion
11319 -u, --unknown
11321 only show unknown (not tracked) files
11322 -I,--include <PATTERN[+]>
11324 include names matching the given patterns
11325 -X,--exclude <PATTERN[+]>
11327 exclude names matching the given patterns
11328 [+] marked option can be specified multiple times
11330 kwshrink
11332 revert expanded keywords in the working directory:
11333 hg kwshrink [OPTION]... [FILE]...
11335 Must be run before changing/disabling active keywords.
11337 kwshrink refuses to run if given files contain local changes.
11339 Options:
11341 -I,--include <PATTERN[+]>
11343 include names matching the given patterns
11344 -X,--exclude <PATTERN[+]>
11346 exclude names matching the given patterns
11347 [+] marked option can be specified multiple times
11349 largefiles
11351 track large binary files
11352 Large binary files tend to be not very compressible, not very diffable,
11354 and not at all mergeable. Such files are not handled efficiently by
11355 Mercurial's storage format (revlog), which is based on compressed bi‐
11356 nary deltas; storing large binary files as regular Mercurial files
11357 wastes bandwidth and disk space and increases Mercurial's memory usage.
11358 The largefiles extension addresses these problems by adding a central‐
11359 ized client-server layer on top of Mercurial: largefiles live in a cen‐
11360 tral store out on the network somewhere, and you only fetch the revi‐
11361 sions that you need when you need them.
11362 largefiles works by maintaining a "standin file" in .hglf/ for each
11364 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
11365 line) and are tracked by Mercurial. Largefile revisions are identified
11366 by the SHA-1 hash of their contents, which is written to the standin.
11367 largefiles uses that revision ID to get/put largefile revisions from/to
11368 the central store. This saves both disk space and bandwidth, since you
11369 don't need to retrieve all historical revisions of large files when you
11370 clone or pull.
11371 To start a new repository or add new large binary files, just add
11373 --large to your hg add command. For example:
11374 $ dd if=/dev/urandom of=randomdata count=2000
11376 $ hg add --large randomdata
11377 $ hg commit -m "add randomdata as a largefile"
11378 When you push a changeset that adds/modifies largefiles to a remote
11380 repository, its largefile revisions will be uploaded along with it.
11381 Note that the remote Mercurial must also have the largefiles extension
11382 enabled for this to work.
11383 When you pull a changeset that affects largefiles from a remote reposi‐
11385 tory, the largefiles for the changeset will by default not be pulled
11386 down. However, when you update to such a revision, any largefiles
11387 needed by that revision are downloaded and cached (if they have never
11388 been downloaded before). One way to pull largefiles when pulling is
11389 thus to use --update, which will update your working copy to the latest
11390 pulled revision (and thereby downloading any new largefiles).
11391 If you want to pull largefiles you don't need for update yet, then you
11393 can use pull with the --lfrev option or the hg lfpull command.
11394 If you know you are pulling from a non-default location and want to
11396 download all the largefiles that correspond to the new changesets at
11397 the same time, then you can pull with --lfrev "pulled()".
11398 If you just want to ensure that you will have the largefiles needed to
11400 merge or rebase with new heads that you are pulling, then you can pull
11401 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
11402 files that are new in the heads you are pulling.
11403 Keep in mind that network access may now be required to update to
11405 changesets that you have not previously updated to. The nature of the
11406 largefiles extension means that updating is no longer guaranteed to be
11407 a local-only operation.
11408 If you already have large files tracked by Mercurial without the large‐
11410 files extension, you will need to convert your repository in order to
11411 benefit from largefiles. This is done with the hg lfconvert command:
11412 $ hg lfconvert --size 10 oldrepo newrepo
11414 In repositories that already have largefiles in them, any new file over
11416 10MB will automatically be added as a largefile. To change this thresh‐
11417 old, set largefiles.minsize in your Mercurial config file to the mini‐
11418 mum size in megabytes to track as a largefile, or use the --lfsize op‐
11419 tion to the add command (also in megabytes):
11420 [largefiles]
11422 minsize = 2
11423 $ hg add --lfsize 2
11425 The largefiles.patterns config option allows you to specify a list of
11427 filename patterns (see hg help patterns) that should always be tracked
11428 as largefiles:
11429 [largefiles]
11431 patterns =
11432 *.jpg
11433 re:.*\.(png|bmp)$
11434 library.zip
11435 content/audio/*
11436 Files that match one of these patterns will be added as largefiles re‐
11438 gardless of their size.
11439 The largefiles.minsize and largefiles.patterns config options will be
11441 ignored for any repositories not already containing a largefile. To add
11442 the first largefile to a repository, you must explicitly do so with the
11443 --large flag passed to the hg add command.
11444 Commands
11446 Uncategorized commands
11447 lfconvert
11448 convert a normal repository to a largefiles repository:
11449 hg lfconvert SOURCE DEST [FILE ...]
11451 Convert repository SOURCE to a new repository DEST, identical to SOURCE
11453 except that certain files will be converted as largefiles: specifi‐
11454 cally, any file that matches any PATTERN or whose size is above the
11455 minimum size threshold is converted as a largefile. The size used to
11456 determine whether or not to track a file as a largefile is the size of
11457 the first version of the file. The minimum size can be specified either
11458 with --size or in configuration as largefiles.size.
11459 After running this command you will need to make sure that largefiles
11461 is enabled anywhere you intend to push the new repository.
11462 Use --to-normal to convert largefiles back to normal files; after this,
11464 the DEST repository can be used without largefiles at all.
11465 Options:
11467 -s,--size <SIZE>
11469 minimum size (MB) for files to be converted as largefiles
11470 --to-normal
11472 convert from a largefiles repo to a normal repo
11473 lfpull
11475 pull largefiles for the specified revisions from the specified source:
11476 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
11478 Pull largefiles that are referenced from local changesets but missing
11480 locally, pulling from a remote repository to the local cache.
11481 If SOURCE is omitted, the 'default' path will be used. See hg help
11483 urls for more information.
11484 Some examples:
11486 • pull largefiles for all branch heads:
11488 hg lfpull -r "head() and not closed()"
11490 • pull largefiles on the default branch:
11492 hg lfpull -r "branch(default)"
11494 Options:
11496 -r,--rev <VALUE[+]>
11498 pull largefiles for these revisions
11499 -e,--ssh <CMD>
11501 specify ssh command to use
11502 --remotecmd <CMD>
11504 specify hg command to run on the remote side
11505 --insecure
11507 do not verify server certificate (ignoring web.cacerts config)
11508 [+] marked option can be specified multiple times
11510 lfs
11512 lfs - large file support (EXPERIMENTAL)
11513 This extension allows large files to be tracked outside of the normal
11515 repository storage and stored on a centralized server, similar to the
11516 largefiles extension. The git-lfs protocol is used when communicating
11517 with the server, so existing git infrastructure can be harnessed. Even
11518 though the files are stored outside of the repository, they are still
11519 integrity checked in the same manner as normal files.
11520 The files stored outside of the repository are downloaded on demand,
11522 which reduces the time to clone, and possibly the local disk usage.
11523 This changes fundamental workflows in a DVCS, so careful thought should
11524 be given before deploying it. hg convert can be used to convert LFS
11525 repositories to normal repositories that no longer require this exten‐
11526 sion, and do so without changing the commit hashes. This allows the
11527 extension to be disabled if the centralized workflow becomes burden‐
11528 some. However, the pre and post convert clones will not be able to
11529 communicate with each other unless the extension is enabled on both.
11530 To start a new repository, or to add LFS files to an existing one, just
11532 create an .hglfs file as described below in the root directory of the
11533 repository. Typically, this file should be put under version control,
11534 so that the settings will propagate to other repositories with push and
11535 pull. During any commit, Mercurial will consult this file to determine
11536 if an added or modified file should be stored externally. The type of
11537 storage depends on the characteristics of the file at each commit. A
11538 file that is near a size threshold may switch back and forth between
11539 LFS and normal storage, as needed.
11540 Alternately, both normal repositories and largefile controlled reposi‐
11542 tories can be converted to LFS by using hg convert and the lfs.track
11543 config option described below. The .hglfs file should then be created
11544 and added, to control subsequent LFS selection. The hashes are also
11545 unchanged in this case. The LFS and non-LFS repositories can be dis‐
11546 tinguished because the LFS repository will abort any command if this
11547 extension is disabled.
11548 Committed LFS files are held locally, until the repository is pushed.
11550 Prior to pushing the normal repository data, the LFS files that are
11551 tracked by the outgoing commits are automatically uploaded to the con‐
11552 figured central server. No LFS files are transferred on hg pull or hg
11553 clone. Instead, the files are downloaded on demand as they need to be
11554 read, if a cached copy cannot be found locally. Both committing and
11555 downloading an LFS file will link the file to a usercache, to speed up
11556 future access. See the usercache config setting described below.
11557 The extension reads its configuration from a versioned .hglfs configu‐
11559 ration file found in the root of the working directory. The .hglfs file
11560 uses the same syntax as all other Mercurial configuration files. It
11561 uses a single section, [track].
11562 The [track] section specifies which files are stored as LFS (or not).
11564 Each line is keyed by a file pattern, with a predicate value. The
11565 first file pattern match is used, so put more specific patterns first.
11566 The available predicates are all(), none(), and size(). See "hg help
11567 filesets.size" for the latter.
11568 Example versioned .hglfs file:
11570 [track]
11572 # No Makefile or python file, anywhere, will be LFS
11573 **Makefile = none()
11574 **.py = none()
11575 **.zip = all()
11577 **.exe = size(">1MB")
11578 # Catchall for everything not matched above
11580 ** = size(">10MB")
11581 Configs:
11583 [lfs]
11585 # Remote endpoint. Multiple protocols are supported:
11586 # - http(s)://user:pass@example.com/path
11587 # git-lfs endpoint
11588 # - file:///tmp/path
11589 # local filesystem, usually for testing
11590 # if unset, lfs will assume the remote repository also handles blob storage
11591 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
11592 # use this value.
11593 # (default: unset)
11594 url = https://example.com/repo.git/info/lfs
11595 # Which files to track in LFS. Path tests are "**.extname" for file
11597 # extensions, and "path:under/some/directory" for path prefix. Both
11598 # are relative to the repository root.
11599 # File size can be tested with the "size()" fileset, and tests can be
11600 # joined with fileset operators. (See "hg help filesets.operators".)
11601 #
11602 # Some examples:
11603 # - all() # everything
11604 # - none() # nothing
11605 # - size(">20MB") # larger than 20MB
11606 # - !**.txt # anything not a *.txt file
11607 # - **.zip | **.tar.gz | **.7z # some types of compressed files
11608 # - path:bin # files under "bin" in the project root
11609 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
11610 # | (path:bin & !path:/bin/README) | size(">1GB")
11611 # (default: none())
11612 #
11613 # This is ignored if there is a tracked '.hglfs' file, and this setting
11614 # will eventually be deprecated and removed.
11615 track = size(">10M")
11616 # how many times to retry before giving up on transferring an object
11618 retry = 5
11619 # the local directory to store lfs files for sharing across local clones.
11621 # If not set, the cache is located in an OS specific cache location.
11622 usercache = /path/to/global/cache
11623 Commands
11625 Uncategorized commands
11626 logtoprocess
11627 send ui.log() data to a subprocess (EXPERIMENTAL)
11628 This extension lets you specify a shell command per ui.log() event,
11630 sending all remaining arguments to as environment variables to that
11631 command.
11632 Positional arguments construct a log message, which is passed in the
11634 MSG1 environment variables. Each keyword argument is set as a OPT_UP‐
11635 PERCASE_KEY variable (so the key is uppercased, and prefixed with
11636 OPT_). The original event name is passed in the EVENT environment vari‐
11637 able, and the process ID of mercurial is given in HGPID.
11638 So given a call ui.log('foo', 'bar %s ', 'baz', spam='eggs'), a script
11640 configured for the `foo event can expect an environment with MSG1=bar
11641 baz, and OPT_SPAM=eggs.
11642 Scripts are configured in the [logtoprocess] section, each key an event
11644 name. For example:
11645 [logtoprocess]
11647 commandexception = echo "$MSG1" > /var/log/mercurial_exceptions.log
11648 would log the warning message and traceback of any failed command dis‐
11650 patch.
11651 Scripts are run asynchronously as detached daemon processes; mercurial
11653 will not ensure that they exit cleanly.
11654 mq
11656 manage a stack of patches
11657 This extension lets you work with a stack of patches in a Mercurial
11659 repository. It manages two stacks of patches - all known patches, and
11660 applied patches (subset of known patches).
11661 Known patches are represented as patch files in the .hg/patches direc‐
11663 tory. Applied patches are both patch files and changesets.
11664 Common tasks (use hg help COMMAND for more details):
11666 create new patch qnew
11668 import existing patch qimport
11669 print patch series qseries
11671 print applied patches qapplied
11672 add known patch to applied stack qpush
11674 remove patch from applied stack qpop
11675 refresh contents of top applied patch qrefresh
11676 By default, mq will automatically use git patches when required to
11678 avoid losing file mode changes, copy records, binary files or empty
11679 files creations or deletions. This behavior can be configured with:
11680 [mq]
11682 git = auto/keep/yes/no
11683 If set to 'keep', mq will obey the [diff] section configuration while
11685 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
11686 mq will override the [diff] section and always generate git or regular
11687 patches, possibly losing data in the second case.
11688 It may be desirable for mq changesets to be kept in the secret phase
11690 (see hg help phases), which can be enabled with the following setting:
11691 [mq]
11693 secret = True
11694 You will by default be managing a patch queue named "patches". You can
11696 create other, independent patch queues with the hg qqueue command.
11697 If the working directory contains uncommitted files, qpush, qpop and
11699 qgoto abort immediately. If -f/--force is used, the changes are dis‐
11700 carded. Setting:
11701 [mq]
11703 keepchanges = True
11704 make them behave as if --keep-changes were passed, and non-conflicting
11706 local changes will be tolerated and preserved. If incompatible options
11707 such as -f/--force or --exact are passed, this setting is ignored.
11708 This extension used to provide a strip command. This command now lives
11710 in the strip extension.
11711 Commands
11713 Repository creation
11714 qclone
11715 clone main and patch repository at same time:
11716 hg qclone [OPTION]... SOURCE [DEST]
11718 If source is local, destination will have no patches applied. If source
11720 is remote, this command can not check if patches are applied in source,
11721 so cannot guarantee that patches are not applied in destination. If you
11722 clone remote repository, be sure before that it has no patches applied.
11723 Source patch repository is looked for in <src>/.hg/patches by default.
11725 Use -p <url> to change.
11726 The patch directory must be a nested Mercurial repository, as would be
11728 created by hg init --mq.
11729 Return 0 on success.
11731 Options:
11733 --pull use pull protocol to copy metadata
11735 -U, --noupdate
11737 do not update the new working directories
11738 --uncompressed
11740 use uncompressed transfer (fast over LAN)
11741 -p,--patches <REPO>
11743 location of source patch repository
11744 -e,--ssh <CMD>
11746 specify ssh command to use
11747 --remotecmd <CMD>
11749 specify hg command to run on the remote side
11750 --insecure
11752 do not verify server certificate (ignoring web.cacerts config)
11753 qinit
11755 init a new queue repository (DEPRECATED):
11756 hg qinit [-c]
11758 The queue repository is unversioned by default. If -c/--create-repo is
11760 specified, qinit will create a separate nested repository for patches
11761 (qinit -c may also be run later to convert an unversioned patch reposi‐
11762 tory into a versioned one). You can use qcommit to commit changes to
11763 this queue repository.
11764 This command is deprecated. Without -c, it's implied by other relevant
11766 commands. With -c, use hg init --mq instead.
11767 Options:
11769 -c, --create-repo
11771 create queue repository
11772 Change creation
11774 qcommit
11775 commit changes in the queue repository (DEPRECATED):
11776 hg qcommit [OPTION]... [FILE]...
11778 This command is deprecated; use hg commit --mq instead.
11780 Options:
11782 -A, --addremove
11784 mark new/missing files as added/removed before committing
11785 --close-branch
11787 mark a branch head as closed
11788 --amend
11790 amend the parent of the working directory
11791 -s, --secret
11793 use the secret phase for committing
11794 -e, --edit
11796 invoke editor on commit messages
11797 --force-close-branch
11799 forcibly close branch from a non-head changeset (ADVANCED)
11800 -i, --interactive
11802 use interactive mode
11803 -I,--include <PATTERN[+]>
11805 include names matching the given patterns
11806 -X,--exclude <PATTERN[+]>
11808 exclude names matching the given patterns
11809 -m,--message <TEXT>
11811 use text as commit message
11812 -l,--logfile <FILE>
11814 read commit message from file
11815 -d,--date <DATE>
11817 record the specified date as commit date
11818 -u,--user <USER>
11820 record the specified user as committer
11821 -S, --subrepos
11823 recurse into subrepositories
11824 [+] marked option can be specified multiple times
11826 aliases: qci
11828 qnew
11830 create a new patch:
11831 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
11833 qnew creates a new patch on top of the currently-applied patch (if
11835 any). The patch will be initialized with any outstanding changes in the
11836 working directory. You may also use -I/--include, -X/--exclude, and/or
11837 a list of files after the patch name to add only changes to matching
11838 files to the new patch, leaving the rest as uncommitted modifications.
11839 -u/--user and -d/--date can be used to set the (given) user and date,
11841 respectively. -U/--currentuser and -D/--currentdate set user to current
11842 user and date to current date.
11843 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
11845 the commit message. If none is specified, the header is empty and the
11846 commit message is '[mq]: PATCH'.
11847 Use the -g/--git option to keep the patch in the git extended diff for‐
11849 mat. Read the diffs help topic for more information on why this is im‐
11850 portant for preserving permission changes and copy/rename information.
11851 Returns 0 on successful creation of a new patch.
11853 Options:
11855 -e, --edit
11857 invoke editor on commit messages
11858 -f, --force
11860 import uncommitted changes (DEPRECATED)
11861 -g, --git
11863 use git extended diff format
11864 -U, --currentuser
11866 add "From: <current user>" to patch
11867 -u,--user <USER>
11869 add "From: <USER>" to patch
11870 -D, --currentdate
11872 add "Date: <current date>" to patch
11873 -d,--date <DATE>
11875 add "Date: <DATE>" to patch
11876 -I,--include <PATTERN[+]>
11878 include names matching the given patterns
11879 -X,--exclude <PATTERN[+]>
11881 exclude names matching the given patterns
11882 -m,--message <TEXT>
11884 use text as commit message
11885 -l,--logfile <FILE>
11887 read commit message from file
11888 [+] marked option can be specified multiple times
11890 qrefresh
11892 update the current patch:
11893 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
11895 If any file patterns are provided, the refreshed patch will contain
11897 only the modifications that match those patterns; the remaining modifi‐
11898 cations will remain in the working directory.
11899 If -s/--short is specified, files currently included in the patch will
11901 be refreshed just like matched files and remain in the patch.
11902 If -e/--edit is specified, Mercurial will start your configured editor
11904 for you to enter a message. In case qrefresh fails, you will find a
11905 backup of your message in .hg/last-message.txt.
11906 hg add/remove/copy/rename work as usual, though you might want to use
11908 git-style patches (-g/--git or [diff] git=1) to track copies and re‐
11909 names. See the diffs help topic for more information on the git diff
11910 format.
11911 Returns 0 on success.
11913 Options:
11915 -e, --edit
11917 invoke editor on commit messages
11918 -g, --git
11920 use git extended diff format
11921 -s, --short
11923 refresh only files already in the patch and specified files
11924 -U, --currentuser
11926 add/update author field in patch with current user
11927 -u,--user <USER>
11929 add/update author field in patch with given user
11930 -D, --currentdate
11932 add/update date field in patch with current date
11933 -d,--date <DATE>
11935 add/update date field in patch with given date
11936 -I,--include <PATTERN[+]>
11938 include names matching the given patterns
11939 -X,--exclude <PATTERN[+]>
11941 exclude names matching the given patterns
11942 -m,--message <TEXT>
11944 use text as commit message
11945 -l,--logfile <FILE>
11947 read commit message from file
11948 [+] marked option can be specified multiple times
11950 Change manipulation
11952 qfold
11953 fold the named patches into the current patch:
11954 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
11956 Patches must not yet be applied. Each patch will be successively ap‐
11958 plied to the current patch in the order given. If all the patches apply
11959 successfully, the current patch will be refreshed with the new cumula‐
11960 tive patch, and the folded patches will be deleted. With -k/--keep, the
11961 folded patch files will not be removed afterwards.
11962 The header for each folded patch will be concatenated with the current
11964 patch header, separated by a line of * * *.
11965 Returns 0 on success.
11967 Options:
11969 -e, --edit
11971 invoke editor on commit messages
11972 -k, --keep
11974 keep folded patch files
11975 -m,--message <TEXT>
11977 use text as commit message
11978 -l,--logfile <FILE>
11980 read commit message from file
11981 Change organization
11983 qapplied
11984 print the patches already applied:
11985 hg qapplied [-1] [-s] [PATCH]
11987 Returns 0 on success.
11989 Options:
11991 -1, --last
11993 show only the preceding applied patch
11994 -s, --summary
11996 print first line of patch header
11997 qdelete
11999 remove patches from queue:
12000 hg qdelete [-k] [PATCH]...
12002 The patches must not be applied, and at least one patch is required.
12004 Exact patch identifiers must be given. With -k/--keep, the patch files
12005 are preserved in the patch directory.
12006 To stop managing a patch and move it into permanent history, use the hg
12008 qfinish command.
12009 Options:
12011 -k, --keep
12013 keep patch file
12014 -r,--rev <REV[+]>
12016 stop managing a revision (DEPRECATED)
12017 [+] marked option can be specified multiple times
12019 aliases: qremove qrm
12021 qfinish
12023 move applied patches into repository history:
12024 hg qfinish [-a] [REV]...
12026 Finishes the specified revisions (corresponding to applied patches) by
12028 moving them out of mq control into regular repository history.
12029 Accepts a revision range or the -a/--applied option. If --applied is
12031 specified, all applied mq revisions are removed from mq control. Other‐
12032 wise, the given revisions must be at the base of the stack of applied
12033 patches.
12034 This can be especially useful if your changes have been applied to an
12036 upstream repository, or if you are about to push your changes to up‐
12037 stream.
12038 Returns 0 on success.
12040 Options:
12042 -a, --applied
12044 finish all applied changesets
12045 qgoto
12047 push or pop patches until named patch is at top of stack:
12048 hg qgoto [OPTION]... PATCH
12050 Returns 0 on success.
12052 Options:
12054 --keep-changes
12056 tolerate non-conflicting local changes
12057 -f, --force
12059 overwrite any local changes
12060 --no-backup
12062 do not save backup copies of files
12063 qguard
12065 set or print guards for a patch:
12066 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
12068 Guards control whether a patch can be pushed. A patch with no guards is
12070 always pushed. A patch with a positive guard ("+foo") is pushed only if
12071 the hg qselect command has activated it. A patch with a negative guard
12072 ("-foo") is never pushed if the hg qselect command has activated it.
12073 With no arguments, print the currently active guards. With arguments,
12075 set guards for the named patch.
12076 Note Specifying negative guards now requires '--'.
12078 To set guards on another patch:
12080 hg qguard other.patch -- +2.6.17 -stable
12082 Returns 0 on success.
12084 Options:
12086 -l, --list
12088 list all patches and guards
12089 -n, --none
12091 drop all guards
12092 qheader
12094 print the header of the topmost or specified patch:
12095 hg qheader [PATCH]
12097 Returns 0 on success.
12099 qnext
12101 print the name of the next pushable patch:
12102 hg qnext [-s]
12104 Returns 0 on success.
12106 Options:
12108 -s, --summary
12110 print first line of patch header
12111 qpop
12113 pop the current patch off the stack:
12114 hg qpop [-a] [-f] [PATCH | INDEX]
12116 Without argument, pops off the top of the patch stack. If given a patch
12118 name, keeps popping off patches until the named patch is at the top of
12119 the stack.
12120 By default, abort if the working directory contains uncommitted
12122 changes. With --keep-changes, abort only if the uncommitted files over‐
12123 lap with patched files. With -f/--force, backup and discard changes
12124 made to such files.
12125 Return 0 on success.
12127 Options:
12129 -a, --all
12131 pop all patches
12132 -n,--name <NAME>
12134 queue name to pop (DEPRECATED)
12135 --keep-changes
12137 tolerate non-conflicting local changes
12138 -f, --force
12140 forget any local changes to patched files
12141 --no-backup
12143 do not save backup copies of files
12144 qprev
12146 print the name of the preceding applied patch:
12147 hg qprev [-s]
12149 Returns 0 on success.
12151 Options:
12153 -s, --summary
12155 print first line of patch header
12156 qpush
12158 push the next patch onto the stack:
12159 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
12161 By default, abort if the working directory contains uncommitted
12163 changes. With --keep-changes, abort only if the uncommitted files over‐
12164 lap with patched files. With -f/--force, backup and patch over uncom‐
12165 mitted changes.
12166 Return 0 on success.
12168 Options:
12170 --keep-changes
12172 tolerate non-conflicting local changes
12173 -f, --force
12175 apply on top of local changes
12176 -e, --exact
12178 apply the target patch to its recorded parent
12179 -l, --list
12181 list patch name in commit text
12182 -a, --all
12184 apply all patches
12185 -m, --merge
12187 merge from another queue (DEPRECATED)
12188 -n,--name <NAME>
12190 merge queue name (DEPRECATED)
12191 --move reorder patch series and apply only the patch
12193 --no-backup
12195 do not save backup copies of files
12196 qqueue
12198 manage multiple patch queues:
12199 hg qqueue [OPTION] [QUEUE]
12201 Supports switching between different patch queues, as well as creating
12203 new patch queues and deleting existing ones.
12204 Omitting a queue name or specifying -l/--list will show you the regis‐
12206 tered queues - by default the "normal" patches queue is registered. The
12207 currently active queue will be marked with "(active)". Specifying --ac‐
12208 tive will print only the name of the active queue.
12209 To create a new queue, use -c/--create. The queue is automatically made
12211 active, except in the case where there are applied patches from the
12212 currently active queue in the repository. Then the queue will only be
12213 created and switching will fail.
12214 To delete an existing queue, use --delete. You cannot delete the cur‐
12216 rently active queue.
12217 Returns 0 on success.
12219 Options:
12221 -l, --list
12223 list all available queues
12224 --active
12226 print name of active queue
12227 -c, --create
12229 create new queue
12230 --rename
12232 rename active queue
12233 --delete
12235 delete reference to queue
12236 --purge
12238 delete queue, and remove patch dir
12239 qrename
12241 rename a patch:
12242 hg qrename PATCH1 [PATCH2]
12244 With one argument, renames the current patch to PATCH1. With two argu‐
12246 ments, renames PATCH1 to PATCH2.
12247 Returns 0 on success.
12249 aliases: qmv
12251 qrestore
12253 restore the queue state saved by a revision (DEPRECATED):
12254 hg qrestore [-d] [-u] REV
12256 This command is deprecated, use hg rebase instead.
12258 Options:
12260 -d, --delete
12262 delete save entry
12263 -u, --update
12265 update queue working directory
12266 qsave
12268 save current queue state (DEPRECATED):
12269 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
12271 This command is deprecated, use hg rebase instead.
12273 Options:
12275 -c, --copy
12277 copy patch directory
12278 -n,--name <NAME>
12280 copy directory name
12281 -e, --empty
12283 clear queue status file
12284 -f, --force
12286 force copy
12287 -m,--message <TEXT>
12289 use text as commit message
12290 -l,--logfile <FILE>
12292 read commit message from file
12293 qselect
12295 set or print guarded patches to push:
12296 hg qselect [OPTION]... [GUARD]...
12298 Use the hg qguard command to set or print guards on patch, then use qs‐
12300 elect to tell mq which guards to use. A patch will be pushed if it has
12301 no guards or any positive guards match the currently selected guard,
12302 but will not be pushed if any negative guards match the current guard.
12303 For example:
12304 qguard foo.patch -- -stable (negative guard)
12306 qguard bar.patch +stable (positive guard)
12307 qselect stable
12308 This activates the "stable" guard. mq will skip foo.patch (because it
12310 has a negative match) but push bar.patch (because it has a positive
12311 match).
12312 With no arguments, prints the currently active guards. With one argu‐
12314 ment, sets the active guard.
12315 Use -n/--none to deactivate guards (no other arguments needed). When
12317 no guards are active, patches with positive guards are skipped and
12318 patches with negative guards are pushed.
12319 qselect can change the guards on applied patches. It does not pop
12321 guarded patches by default. Use --pop to pop back to the last applied
12322 patch that is not guarded. Use --reapply (which implies --pop) to push
12323 back to the current patch afterwards, but skip guarded patches.
12324 Use -s/--series to print a list of all guards in the series file (no
12326 other arguments needed). Use -v for more information.
12327 Returns 0 on success.
12329 Options:
12331 -n, --none
12333 disable all guards
12334 -s, --series
12336 list all guards in series file
12337 --pop pop to before first guarded applied patch
12339 --reapply
12341 pop, then reapply patches
12342 qseries
12344 print the entire series file:
12345 hg qseries [-ms]
12347 Returns 0 on success.
12349 Options:
12351 -m, --missing
12353 print patches not in series
12354 -s, --summary
12356 print first line of patch header
12357 qtop
12359 print the name of the current patch:
12360 hg qtop [-s]
12362 Returns 0 on success.
12364 Options:
12366 -s, --summary
12368 print first line of patch header
12369 qunapplied
12371 print the patches not yet applied:
12372 hg qunapplied [-1] [-s] [PATCH]
12374 Returns 0 on success.
12376 Options:
12378 -1, --first
12380 show only the first patch
12381 -s, --summary
12383 print first line of patch header
12384 File content management
12386 qdiff
12387 diff of the current patch and subsequent modifications:
12388 hg qdiff [OPTION]... [FILE]...
12390 Shows a diff which includes the current patch as well as any changes
12392 which have been made in the working directory since the last refresh
12393 (thus showing what the current patch would become after a qrefresh).
12394 Use hg diff if you only want to see the changes made since the last
12396 qrefresh, or hg export qtip if you want to see changes made by the cur‐
12397 rent patch without including changes made since the qrefresh.
12398 Returns 0 on success.
12400 Options:
12402 -a, --text
12404 treat all files as text
12405 -g, --git
12407 use git extended diff format (DEFAULT: diff.git)
12408 --binary
12410 generate binary diffs in git mode (default)
12411 --nodates
12413 omit dates from diff headers
12414 --noprefix
12416 omit a/ and b/ prefixes from filenames
12417 -p, --show-function
12419 show which function each change is in (DEFAULT: diff.showfunc)
12420 --reverse
12422 produce a diff that undoes the changes
12423 -w, --ignore-all-space
12425 ignore white space when comparing lines
12426 -b, --ignore-space-change
12428 ignore changes in the amount of white space
12429 -B, --ignore-blank-lines
12431 ignore changes whose lines are all blank
12432 -Z, --ignore-space-at-eol
12434 ignore changes in whitespace at EOL
12435 -U,--unified <NUM>
12437 number of lines of context to show
12438 --stat output diffstat-style summary of changes
12440 --root <DIR>
12442 produce diffs relative to subdirectory
12443 -I,--include <PATTERN[+]>
12445 include names matching the given patterns
12446 -X,--exclude <PATTERN[+]>
12448 exclude names matching the given patterns
12449 [+] marked option can be specified multiple times
12451 Change import/export
12453 qimport
12454 import a patch or existing changeset:
12455 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
12457 The patch is inserted into the series after the last applied patch. If
12459 no patches have been applied, qimport prepends the patch to the series.
12460 The patch will have the same name as its source file unless you give it
12462 a new one with -n/--name.
12463 You can register an existing patch inside the patch directory with the
12465 -e/--existing flag.
12466 With -f/--force, an existing patch of the same name will be overwrit‐
12468 ten.
12469 An existing changeset may be placed under mq control with -r/--rev
12471 (e.g. qimport --rev . -n patch will place the current revision under mq
12472 control). With -g/--git, patches imported with --rev will use the git
12473 diff format. See the diffs help topic for information on why this is
12474 important for preserving rename/copy information and permission
12475 changes. Use hg qfinish to remove changesets from mq control.
12476 To import a patch from standard input, pass - as the patch file. When
12478 importing from standard input, a patch name must be specified using the
12479 --name flag.
12480 To import an existing patch while renaming it:
12482 hg qimport -e existing-patch -n new-name
12484 Returns 0 if import succeeded.
12486 Options:
12488 -e, --existing
12490 import file in patch directory
12491 -n,--name <NAME>
12493 name of patch file
12494 -f, --force
12496 overwrite existing files
12497 -r,--rev <REV[+]>
12499 place existing revisions under mq control
12500 -g, --git
12502 use git extended diff format
12503 -P, --push
12505 qpush after importing
12506 [+] marked option can be specified multiple times
12508 narrow
12510 create clones which fetch history data for subset of files (EXPERIMEN‐
12511 TAL)
12512 Commands
12514 Repository maintenance
12515 tracked
12516 show or change the current narrowspec:
12517 hg tracked [OPTIONS]... [REMOTE]
12519 With no argument, shows the current narrowspec entries, one per line.
12521 Each line will be prefixed with 'I' or 'X' for included or excluded
12522 patterns, respectively.
12523 The narrowspec is comprised of expressions to match remote files and/or
12525 directories that should be pulled into your client. The narrowspec has
12526 include and exclude expressions, with excludes always trumping in‐
12527 cludes: that is, if a file matches an exclude expression, it will be
12528 excluded even if it also matches an include expression. Excluding
12529 files that were never included has no effect.
12530 Each included or excluded entry is in the format described by 'hg help
12532 patterns'.
12533 The options allow you to add or remove included and excluded expres‐
12535 sions.
12536 If --clear is specified, then all previous includes and excludes are
12538 DROPPED and replaced by the new ones specified to --addinclude and
12539 --addexclude. If --clear is specified without any further options, the
12540 narrowspec will be empty and will not match any files.
12541 If --auto-remove-includes is specified, then those includes that don't
12543 match any files modified by currently visible local commits (those not
12544 shared by the remote) will be added to the set of explicitly specified
12545 includes to remove.
12546 --import-rules accepts a path to a file containing rules, allowing you
12548 to add --addinclude, --addexclude rules in bulk. Like the other include
12549 and exclude switches, the changes are applied immediately.
12550 Options:
12552 --addinclude <VALUE[+]>
12554 new paths to include
12555 --removeinclude <VALUE[+]>
12557 old paths to no longer include
12558 --auto-remove-includes
12560 automatically choose unused includes to remove
12561 --addexclude <VALUE[+]>
12563 new paths to exclude
12564 --import-rules <VALUE>
12566 import narrowspecs from a file
12567 --removeexclude <VALUE[+]>
12569 old paths to no longer exclude
12570 --clear
12572 whether to replace the existing narrowspec
12573 --force-delete-local-changes
12575 forces deletion of local changes when narrowing
12576 --backup
12578 back up local changes when narrowing (default: True)
12579 --update-working-copy
12581 update working copy when the store has changed
12582 -e,--ssh <CMD>
12584 specify ssh command to use
12585 --remotecmd <CMD>
12587 specify hg command to run on the remote side
12588 --insecure
12590 do not verify server certificate (ignoring web.cacerts config)
12591 [+] marked option can be specified multiple times
12593 notify
12595 hooks for sending email push notifications
12596 This extension implements hooks to send email notifications when
12598 changesets are sent from or received by the local repository.
12599 First, enable the extension as explained in hg help extensions, and
12601 register the hook you want to run. incoming and changegroup hooks are
12602 run when changesets are received, while outgoing hooks are for change‐
12603 sets sent to another repository:
12604 [hooks]
12606 # one email for each incoming changeset
12607 incoming.notify = python:hgext.notify.hook
12608 # one email for all incoming changesets
12609 changegroup.notify = python:hgext.notify.hook
12610 # one email for all outgoing changesets
12612 outgoing.notify = python:hgext.notify.hook
12613 This registers the hooks. To enable notification, subscribers must be
12615 assigned to repositories. The [usersubs] section maps multiple reposi‐
12616 tories to a given recipient. The [reposubs] section maps multiple re‐
12617 cipients to a single repository:
12618 [usersubs]
12620 # key is subscriber email, value is a comma-separated list of repo patterns
12621 user@host = pattern
12622 [reposubs]
12624 # key is repo pattern, value is a comma-separated list of subscriber emails
12625 pattern = user@host
12626 A pattern is a glob matching the absolute path to a repository, option‐
12628 ally combined with a revset expression. A revset expression, if
12629 present, is separated from the glob by a hash. Example:
12630 [reposubs]
12632 */widgets#branch(release) = qa-team@example.com
12633 This sends to qa-team@example.com whenever a changeset on the release
12635 branch triggers a notification in any repository ending in widgets.
12636 In order to place them under direct user management, [usersubs] and
12638 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
12639 rated by reference:
12640 [notify]
12642 config = /path/to/subscriptionsfile
12643 Notifications will not be sent until the notify.test value is set to
12645 False; see below.
12646 Notifications content can be tweaked with the following configuration
12648 entries:
12649 notify.test
12651 If True, print messages to stdout instead of sending them. De‐
12652 fault: True.
12653 notify.sources
12655 Space-separated list of change sources. Notifications are acti‐
12656 vated only when a changeset's source is in this list. Sources
12657 may be:
12658 serve
12660 changesets received via http or ssh
12662 pull
12664 changesets received via hg pull
12666 unbundle
12668 changesets received via hg unbundle
12670 push
12672 changesets sent or received via hg push
12674 bundle
12676 changesets sent via hg unbundle
12678 Default: serve.
12680 notify.strip
12682 Number of leading slashes to strip from url paths. By default,
12683 notifications reference repositories with their absolute path.
12684 notify.strip lets you turn them into relative paths. For exam‐
12685 ple, notify.strip=3 will change /long/path/repository into
12686 repository. Default: 0.
12687 notify.domain
12689 Default email domain for sender or recipients with no explicit
12690 domain. It is also used for the domain part of the Message-Id
12691 when using notify.messageidseed.
12692 notify.messageidseed
12694 Create deterministic Message-Id headers for the mails based on
12695 the seed and the revision identifier of the first commit in the
12696 changeset.
12697 notify.style
12699 Style file to use when formatting emails.
12700 notify.template
12702 Template to use when formatting emails.
12703 notify.incoming
12705 Template to use when run as an incoming hook, overriding no‐
12706 tify.template.
12707 notify.outgoing
12709 Template to use when run as an outgoing hook, overriding no‐
12710 tify.template.
12711 notify.changegroup
12713 Template to use when running as a changegroup hook, overriding
12714 notify.template.
12715 notify.maxdiff
12717 Maximum number of diff lines to include in notification email.
12718 Set to 0 to disable the diff, or -1 to include all of it. De‐
12719 fault: 300.
12720 notify.maxdiffstat
12722 Maximum number of diffstat lines to include in notification
12723 email. Set to -1 to include all of it. Default: -1.
12724 notify.maxsubject
12726 Maximum number of characters in email's subject line. Default:
12727 67.
12728 notify.diffstat
12730 Set to True to include a diffstat before diff content. Default:
12731 True.
12732 notify.showfunc
12734 If set, override diff.showfunc for the diff content. Default:
12735 None.
12736 notify.merge
12738 If True, send notifications for merge changesets. Default: True.
12739 notify.mbox
12741 If set, append mails to this mbox file instead of sending. De‐
12742 fault: None.
12743 notify.fromauthor
12745 If set, use the committer of the first changeset in a change‐
12746 group for the "From" field of the notification mail. If not set,
12747 take the user from the pushing repo. Default: False.
12748 notify.reply-to-predecessor (EXPERIMENTAL)
12750 If set and the changeset has a predecessor in the repository,
12751 try to thread the notification mail with the predecessor. This
12752 adds the "In-Reply-To" header to the notification mail with a
12753 reference to the predecessor with the smallest revision number.
12754 Mail threads can still be torn, especially when changesets are
12755 folded.
12756 This option must be used in combination with notify.messageid‐
12758 seed.
12759 If set, the following entries will also be used to customize the noti‐
12761 fications:
12762 email.from
12764 Email From address to use if none can be found in the generated
12765 email content.
12766 web.baseurl
12768 Root repository URL to combine with repository paths when making
12769 references. See also notify.strip.
12770 pager
12772 browse command output with an external pager (DEPRECATED)
12773 Forcibly enable paging for individual commands that don't typically re‐
12775 quest pagination with the attend-<command> option. This setting takes
12776 precedence over ignore options and defaults:
12777 [pager]
12779 attend-cat = false
12780 patchbomb
12782 command to send changesets as (a series of) patch emails
12783 The series is started off with a "[PATCH 0 of N]" introduction, which
12785 describes the series as a whole.
12786 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12788 first line of the changeset description as the subject text. The mes‐
12789 sage contains two or three body parts:
12790 • The changeset description.
12792 • [Optional] The result of running diffstat on the patch.
12794 • The patch itself, as generated by hg export.
12796 Each message refers to the first in the series using the In-Reply-To
12798 and References headers, so they will show up as a sequence in threaded
12799 mail and news readers, and in mail archives.
12800 To configure other defaults, add a section like this to your configura‐
12802 tion file:
12803 [email]
12805 from = My Name <my@email>
12806 to = recipient1, recipient2, ...
12807 cc = cc1, cc2, ...
12808 bcc = bcc1, bcc2, ...
12809 reply-to = address1, address2, ...
12810 Use [patchbomb] as configuration section name if you need to override
12812 global [email] address settings.
12813 Then you can use the hg email command to mail a series of changesets as
12815 a patchbomb.
12816 You can also either configure the method option in the email section to
12818 be a sendmail compatible mailer or fill out the [smtp] section so that
12819 the patchbomb extension can automatically send patchbombs directly from
12820 the commandline. See the [email] and [smtp] sections in hgrc(5) for de‐
12821 tails.
12822 By default, hg email will prompt for a To or CC header if you do not
12824 supply one via configuration or the command line. You can override
12825 this to never prompt by configuring an empty value:
12826 [email]
12828 cc =
12829 You can control the default inclusion of an introduction message with
12831 the patchbomb.intro configuration option. The configuration is always
12832 overwritten by command line flags like --intro and --desc:
12833 [patchbomb]
12835 intro=auto # include introduction message if more than 1 patch (default)
12836 intro=never # never include an introduction message
12837 intro=always # always include an introduction message
12838 You can specify a template for flags to be added in subject prefixes.
12840 Flags specified by --flag option are exported as {flags} keyword:
12841 [patchbomb]
12843 flagtemplate = "{separate(' ',
12844 ifeq(branch, 'default', '', branch|upper),
12845 flags)}"
12846 You can set patchbomb to always ask for confirmation by setting patch‐
12848 bomb.confirm to true.
12849 Commands
12851 Change import/export
12852 email
12853 send changesets by email:
12854 hg email [OPTION]... [DEST]...
12856 By default, diffs are sent in the format generated by hg export, one
12858 per message. The series starts with a "[PATCH 0 of N]" introduction,
12859 which describes the series as a whole.
12860 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12862 first line of the changeset description as the subject text. The mes‐
12863 sage contains two or three parts. First, the changeset description.
12864 With the -d/--diffstat option, if the diffstat program is installed,
12866 the result of running diffstat on the patch is inserted.
12867 Finally, the patch itself, as generated by hg export.
12869 With the -d/--diffstat or --confirm options, you will be presented with
12871 a final summary of all messages and asked for confirmation before the
12872 messages are sent.
12873 By default the patch is included as text in the email body for easy re‐
12875 viewing. Using the -a/--attach option will instead create an attachment
12876 for the patch. With -i/--inline an inline attachment will be created.
12877 You can include a patch both as text in the email body and as a regular
12878 or an inline attachment by combining the -a/--attach or -i/--inline
12879 with the --body option.
12880 With -B/--bookmark changesets reachable by the given bookmark are se‐
12882 lected.
12883 With -o/--outgoing, emails will be generated for patches not found in
12885 the destination repository (or only those which are ancestors of the
12886 specified revisions if any are provided)
12887 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
12889 gle email containing a binary Mercurial bundle as an attachment will be
12890 sent. Use the patchbomb.bundletype config option to control the bundle
12891 type as with hg bundle --type.
12892 With -m/--mbox, instead of previewing each patchbomb message in a pager
12894 or sending the messages directly, it will create a UNIX mailbox file
12895 with the patch emails. This mailbox file can be previewed with any mail
12896 user agent which supports UNIX mbox files.
12897 With -n/--test, all steps will run, but mail will not be sent. You
12899 will be prompted for an email recipient address, a subject and an in‐
12900 troductory message describing the patches of your patchbomb. Then when
12901 all is done, patchbomb messages are displayed.
12902 In case email sending fails, you will find a backup of your series in‐
12904 troductory message in .hg/last-email.txt.
12905 The default behavior of this command can be customized through configu‐
12907 ration. (See hg help patchbomb for details)
12908 Examples:
12910 hg email -r 3000 # send patch 3000 only
12912 hg email -r 3000 -r 3001 # send patches 3000 and 3001
12913 hg email -r 3000:3005 # send patches 3000 through 3005
12914 hg email 3000 # send patch 3000 (deprecated)
12915 hg email -o # send all patches not in default
12917 hg email -o DEST # send all patches not in DEST
12918 hg email -o -r 3000 # send all ancestors of 3000 not in default
12919 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
12920 hg email -B feature # send all ancestors of feature bookmark
12922 hg email -b # send bundle of all patches not in default
12924 hg email -b DEST # send bundle of all patches not in DEST
12925 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
12926 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
12927 hg email -o -m mbox && # generate an mbox file...
12929 mutt -R -f mbox # ... and view it with mutt
12930 hg email -o -m mbox && # generate an mbox file ...
12931 formail -s sendmail \ # ... and use formail to send from the mbox
12932 -bm -t < mbox # ... using sendmail
12933 Before using this command, you will need to enable email in your hgrc.
12935 See the [email] section in hgrc(5) for details.
12936 Options:
12938 -g, --git
12940 use git extended diff format
12941 --plain
12943 omit hg patch header
12944 -o, --outgoing
12946 send changes not found in the target repository
12947 -b, --bundle
12949 send changes not in target as a binary bundle
12950 -B,--bookmark <BOOKMARK>
12952 send changes only reachable by given bookmark
12953 --bundlename <NAME>
12955 name of the bundle attachment file (default: bundle)
12956 -r,--rev <REV[+]>
12958 a revision to send
12959 --force
12961 run even when remote repository is unrelated (with -b/--bundle)
12962 --base <REV[+]>
12964 a base changeset to specify instead of a destination (with
12965 -b/--bundle)
12966 --intro
12968 send an introduction email for a single patch
12969 --body send patches as inline message text (default)
12971 -a, --attach
12973 send patches as attachments
12974 -i, --inline
12976 send patches as inline attachments
12977 --bcc <EMAIL[+]>
12979 email addresses of blind carbon copy recipients
12980 -c,--cc <EMAIL[+]>
12982 email addresses of copy recipients
12983 --confirm
12985 ask for confirmation before sending
12986 -d, --diffstat
12988 add diffstat output to messages
12989 --date <DATE>
12991 use the given date as the sending date
12992 --desc <FILE>
12994 use the given file as the series description
12995 -f,--from <EMAIL>
12997 email address of sender
12998 -n, --test
13000 print messages that would be sent
13001 -m,--mbox <FILE>
13003 write messages to mbox file instead of sending them
13004 --reply-to <EMAIL[+]>
13006 email addresses replies should be sent to
13007 -s,--subject <TEXT>
13009 subject of first message (intro or single patch)
13010 --in-reply-to <MSGID>
13012 message identifier to reply to
13013 --flag <FLAG[+]>
13015 flags to add in subject prefixes
13016 -t,--to <EMAIL[+]>
13018 email addresses of recipients
13019 -e,--ssh <CMD>
13021 specify ssh command to use
13022 --remotecmd <CMD>
13024 specify hg command to run on the remote side
13025 --insecure
13027 do not verify server certificate (ignoring web.cacerts config)
13028 [+] marked option can be specified multiple times
13030 phabricator
13032 simple Phabricator integration (EXPERIMENTAL)
13033 This extension provides a phabsend command which sends a stack of
13035 changesets to Phabricator, and a phabread command which prints a stack
13036 of revisions in a format suitable for hg import, and a phabupdate com‐
13037 mand to update statuses in batch.
13038 A "phabstatus" view for hg show is also provided; it displays status
13040 information of Phabricator differentials associated with unfinished
13041 changesets.
13042 By default, Phabricator requires Test Plan which might prevent some
13044 changeset from being sent. The requirement could be disabled by chang‐
13045 ing differential.require-test-plan-field config server side.
13046 Config:
13048 [phabricator]
13050 # Phabricator URL
13051 url = https://phab.example.com/
13052 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
13054 # callsign is "FOO".
13055 callsign = FOO
13056 # curl command to use. If not set (default), use builtin HTTP library to
13058 # communicate. If set, use the specified curl command. This could be useful
13059 # if you need to specify advanced options that is not easily supported by
13060 # the internal library.
13061 curlcmd = curl --connect-timeout 2 --retry 3 --silent
13062 # retry failed command N time (default 0). Useful when using the extension
13064 # over flakly connection.
13065 #
13066 # We wait `retry.interval` between each retry, in seconds.
13067 # (default 1 second).
13068 retry = 3
13069 retry.interval = 10
13070 # the retry option can combine well with the http.timeout one.
13072 #
13073 # For example to give up on http request after 20 seconds:
13074 [http]
13075 timeout=20
13076 [auth]
13078 example.schemes = https
13079 example.prefix = phab.example.com
13080 # API token. Get it from https://$HOST/conduit/login/
13082 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
13083 Commands
13085 Change import/export
13086 phabimport
13087 import patches from Phabricator for the specified Differential Revi‐
13088 sions:
13089 hg phabimport DREVSPEC... [OPTIONS]
13091 The patches are read and applied starting at the parent of the working
13093 directory.
13094 See hg help phabread for how to specify DREVSPEC.
13096 Options:
13098 --stack
13100 import dependencies as well
13101 --test-vcr <VALUE>
13103 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13104 script, otherwise will mock all http requests using the speci‐
13105 fied vcr file. (ADVANCED)
13106 phabread
13108 print patches from Phabricator suitable for importing:
13109 hg phabread DREVSPEC... [OPTIONS]
13111 DREVSPEC could be a Differential Revision identity, like D123, or just
13113 the number 123. It could also have common operators like +, -, &, (, )
13114 for complex queries. Prefix : could be used to select a stack. If mul‐
13115 tiple DREVSPEC values are given, the result is the union of each indi‐
13116 vidually evaluated value. No attempt is currently made to reorder the
13117 values to run from parent to child.
13118 abandoned, accepted, closed, needsreview, needsrevision could be used
13120 to filter patches by status. For performance reason, they only repre‐
13121 sent a subset of non-status selections and cannot be used alone.
13122 For example, :D6+8-(2+D4) selects a stack up to D6, plus D8 and exclude
13124 D2 and D4. :D9 & needsreview selects "Needs Review" revisions in a
13125 stack up to D9.
13126 If --stack is given, follow dependencies information and read all
13128 patches. It is equivalent to the : operator.
13129 Options:
13131 --stack
13133 read dependencies
13134 --test-vcr <VALUE>
13136 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13137 script, otherwise will mock all http requests using the speci‐
13138 fied vcr file. (ADVANCED)
13139 phabsend
13141 upload changesets to Phabricator:
13142 hg phabsend REV [OPTIONS]
13144 If there are multiple revisions specified, they will be send as a stack
13146 with a linear dependencies relationship using the order specified by
13147 the revset.
13148 For the first time uploading changesets, local tags will be created to
13150 maintain the association. After the first time, phabsend will check ob‐
13151 sstore and tags information so it can figure out whether to update an
13152 existing Differential Revision, or create a new one.
13153 If --amend is set, update commit messages so they have the Differential
13155 Revision URL, remove related tags. This is similar to what arcanist
13156 will do, and is more desired in author-push workflows. Otherwise, use
13157 local tags to record the Differential Revision association.
13158 The --confirm option lets you confirm changesets before sending them.
13160 You can also add following to your configuration file to make it de‐
13161 fault behaviour:
13162 [phabsend]
13164 confirm = true
13165 By default, a separate review will be created for each commit that is
13167 selected, and will have the same parent/child relationship in Phabrica‐
13168 tor. If --fold is set, multiple commits are rolled up into a single
13169 review as if diffed from the parent of the first revision to the last.
13170 The commit messages are concatenated in the summary field on Phabrica‐
13171 tor.
13172 phabsend will check obsstore and the above association to decide
13174 whether to update an existing Differential Revision, or create a new
13175 one.
13176 Options:
13178 -r,--rev <REV[+]>
13180 revisions to send
13181 --amend
13183 update commit messages (default: True)
13184 --reviewer <VALUE[+]>
13186 specify reviewers
13187 --blocker <VALUE[+]>
13189 specify blocking reviewers
13190 -m,--comment <VALUE>
13192 add a comment to Revisions with new/updated Diffs
13193 --confirm
13195 ask for confirmation before sending
13196 --fold combine the revisions into one review
13198 --test-vcr <VALUE>
13200 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13201 script, otherwise will mock all http requests using the speci‐
13202 fied vcr file. (ADVANCED)
13203 [+] marked option can be specified multiple times
13205 phabupdate
13207 update Differential Revision in batch:
13208 hg phabupdate [DREVSPEC...| -r REV...] [OPTIONS]
13210 DREVSPEC selects revisions. See hg help phabread for its usage.
13212 Options:
13214 --accept
13216 accept revisions
13217 --reject
13219 reject revisions
13220 --request-review
13222 request review on revisions
13223 --abandon
13225 abandon revisions
13226 --reclaim
13228 reclaim revisions
13229 --close
13231 close revisions
13232 --reopen
13234 reopen revisions
13235 --plan-changes
13237 plan changes for revisions
13238 --resign
13240 resign as a reviewer from revisions
13241 --commandeer
13243 commandeer revisions
13244 -m,--comment <VALUE>
13246 comment on the last revision
13247 -r,--rev <REV>
13249 local revision to update
13250 --test-vcr <VALUE>
13252 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13253 script, otherwise will mock all http requests using the speci‐
13254 fied vcr file. (ADVANCED)
13255 Uncategorized commands
13257 purge
13258 command to delete untracked files from the working directory (DEPRE‐
13259 CATED)
13260 The functionality of this extension has been included in core Mercurial
13262 since version 5.7. Please use hg purge ... instead. hg purge --confirm
13263 is now the default, unless the extension is enabled for backward com‐
13264 patibility.
13265 rebase
13267 command to move sets of revisions to a different ancestor
13268 This extension lets you rebase changesets in an existing Mercurial
13270 repository.
13271 For more information: https://mercurial-scm.org/wiki/RebaseExtension
13273 Commands
13275 Change manipulation
13276 rebase
13277 move changeset (and descendants) to a different branch:
13278 hg rebase [[-s REV]... | [-b REV]... | [-r REV]...] [-d REV] [OPTION]...
13280 Rebase uses repeated merging to graft changesets from one part of his‐
13282 tory (the source) onto another (the destination). This can be useful
13283 for linearizing local changes relative to a master development tree.
13284 Published commits cannot be rebased (see hg help phases). To copy com‐
13286 mits, see hg help graft.
13287 If you don't specify a destination changeset (-d/--dest), rebase will
13289 use the same logic as hg merge to pick a destination. if the current
13290 branch contains exactly one other head, the other head is merged with
13291 by default. Otherwise, an explicit revision with which to merge with
13292 must be provided. (destination changeset is not modified by rebasing,
13293 but new changesets are added as its descendants.)
13294 Here are the ways to select changesets:
13296 1. Explicitly select them using --rev.
13298 2. Use --source to select a root changeset and include all of its
13300 descendants.
13301 3. Use --base to select a changeset; rebase will find ancestors and
13303 their descendants which are not also ancestors of the destina‐
13304 tion.
13305 4. If you do not specify any of --rev, --source, or --base, rebase
13307 will use --base . as above.
13308 If --source or --rev is used, special names SRC and ALLSRC can be used
13310 in --dest. Destination would be calculated per source revision with SRC
13311 substituted by that single source revision and ALLSRC substituted by
13312 all source revisions.
13313 Rebase will destroy original changesets unless you use --keep. It will
13315 also move your bookmarks (even if you do).
13316 Some changesets may be dropped if they do not contribute changes (e.g.
13318 merges from the destination branch).
13319 Unlike merge, rebase will do nothing if you are at the branch tip of a
13321 named branch with two heads. You will need to explicitly specify source
13322 and/or destination.
13323 If you need to use a tool to automate merge/conflict decisions, you can
13325 specify one with --tool, see hg help merge-tools. As a caveat: the
13326 tool will not be used to mediate when a file was deleted, there is no
13327 hook presently available for this.
13328 If a rebase is interrupted to manually resolve a conflict, it can be
13330 continued with --continue/-c, aborted with --abort/-a, or stopped with
13331 --stop.
13332 Examples:
13334 • move "local changes" (current commit back to branching point) to the
13336 current branch tip after a pull:
13337 hg rebase
13339 • move a single changeset to the stable branch:
13341 hg rebase -r 5f493448 -d stable
13343 • splice a commit and all its descendants onto another part of history:
13345 hg rebase --source c0c3 --dest 4cf9
13347 • rebase everything on a branch marked by a bookmark onto the default
13349 branch:
13350 hg rebase --base myfeature --dest default
13352 • collapse a sequence of changes into a single commit:
13354 hg rebase --collapse -r 1520:1525 -d .
13356 • move a named branch while preserving its name:
13358 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
13360 • stabilize orphaned changesets so history looks linear:
13362 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
13364 Configuration Options:
13366 You can make rebase require a destination if you set the following con‐
13368 fig option:
13369 [commands]
13371 rebase.requiredest = True
13372 By default, rebase will close the transaction after each commit. For
13374 performance purposes, you can configure rebase to use a single transac‐
13375 tion across the entire rebase. WARNING: This setting introduces a sig‐
13376 nificant risk of losing the work you've done in a rebase if the rebase
13377 aborts unexpectedly:
13378 [rebase]
13380 singletransaction = True
13381 By default, rebase writes to the working copy, but you can configure it
13383 to run in-memory for better performance. When the rebase is not moving
13384 the parent(s) of the working copy (AKA the "currently checked out
13385 changesets"), this may also allow it to run even if the working copy is
13386 dirty:
13387 [rebase]
13389 experimental.inmemory = True
13390 Return Values:
13392 Returns 0 on success, 1 if nothing to rebase or there are unresolved
13394 conflicts.
13395 Options:
13397 -s,--source <REV[+]>
13399 rebase the specified changesets and their descendants
13400 -b,--base <REV[+]>
13402 rebase everything from branching point of specified changeset
13403 -r,--rev <REV[+]>
13405 rebase these revisions
13406 -d,--dest <REV>
13408 rebase onto the specified changeset
13409 --collapse
13411 collapse the rebased changesets
13412 -m,--message <TEXT>
13414 use text as collapse commit message
13415 -e, --edit
13417 invoke editor on commit messages
13418 -l,--logfile <FILE>
13420 read collapse commit message from file
13421 -k, --keep
13423 keep original changesets
13424 --keepbranches
13426 keep original branch names
13427 -D, --detach
13429 (DEPRECATED)
13430 -i, --interactive
13432 (DEPRECATED)
13433 -t,--tool <VALUE>
13435 specify merge tool
13436 --stop stop interrupted rebase
13438 -c, --continue
13440 continue an interrupted rebase
13441 -a, --abort
13443 abort an interrupted rebase
13444 --auto-orphans <VALUE>
13446 automatically rebase orphan revisions in the specified revset
13447 (EXPERIMENTAL)
13448 -n, --dry-run
13450 do not perform actions, just print output
13451 -T,--template <TEMPLATE>
13453 display with template
13454 --confirm
13456 ask before applying actions
13457 [+] marked option can be specified multiple times
13459 record
13461 commands to interactively select changes for commit/qrefresh (DEPRE‐
13462 CATED)
13463 The feature provided by this extension has been moved into core Mercu‐
13465 rial as hg commit --interactive.
13466 Commands
13468 Change creation
13469 qrecord
13470 interactively record a new patch:
13471 hg qrecord [OPTION]... PATCH [FILE]...
13473 See hg help qnew & hg help record for more information and usage.
13475 record
13477 interactively select changes to commit:
13478 hg record [OPTION]... [FILE]...
13480 If a list of files is omitted, all changes reported by hg status will
13482 be candidates for recording.
13483 See hg help dates for a list of formats valid for -d/--date.
13485 If using the text interface (see hg help config), you will be prompted
13487 for whether to record changes to each modified file, and for files with
13488 multiple changes, for each change to use. For each query, the following
13489 responses are possible:
13490 y - record this change
13492 n - skip this change
13493 e - edit this change manually
13494 s - skip remaining changes to this file
13496 f - record remaining changes to this file
13497 d - done, skip remaining changes and files
13499 a - record all changes to all remaining files
13500 q - quit, recording no changes
13501 ? - display help
13503 This command is not available when committing a merge.
13505 Options:
13507 -A, --addremove
13509 mark new/missing files as added/removed before committing
13510 --close-branch
13512 mark a branch head as closed
13513 --amend
13515 amend the parent of the working directory
13516 -s, --secret
13518 use the secret phase for committing
13519 -e, --edit
13521 invoke editor on commit messages
13522 --force-close-branch
13524 forcibly close branch from a non-head changeset (ADVANCED)
13525 -I,--include <PATTERN[+]>
13527 include names matching the given patterns
13528 -X,--exclude <PATTERN[+]>
13530 exclude names matching the given patterns
13531 -m,--message <TEXT>
13533 use text as commit message
13534 -l,--logfile <FILE>
13536 read commit message from file
13537 -d,--date <DATE>
13539 record the specified date as commit date
13540 -u,--user <USER>
13542 record the specified user as committer
13543 -S, --subrepos
13545 recurse into subrepositories
13546 -w, --ignore-all-space
13548 ignore white space when comparing lines
13549 -b, --ignore-space-change
13551 ignore changes in the amount of white space
13552 -B, --ignore-blank-lines
13554 ignore changes whose lines are all blank
13555 -Z, --ignore-space-at-eol
13557 ignore changes in whitespace at EOL
13558 [+] marked option can be specified multiple times
13560 releasenotes
13562 generate release notes from commit messages (EXPERIMENTAL)
13563 It is common to maintain files detailing changes in a project between
13565 releases. Maintaining these files can be difficult and time consuming.
13566 The hg releasenotes command provided by this extension makes the
13567 process simpler by automating it.
13568 Commands
13570 Change navigation
13571 releasenotes
13572 parse release notes from commit messages into an output file:
13573 hg releasenotes [-r REV] [-c] FILE
13575 Given an output file and set of revisions, this command will parse com‐
13577 mit messages for release notes then add them to the output file.
13578 Release notes are defined in commit messages as ReStructuredText direc‐
13580 tives. These have the form:
13581 .. directive:: title
13583 content
13585 Each directive maps to an output section in a generated release notes
13587 file, which itself is ReStructuredText. For example, the .. feature::
13588 directive would map to a New Features section.
13589 Release note directives can be either short-form or long-form. In
13591 short- form, title is omitted and the release note is rendered as a
13592 bullet list. In long form, a sub-section with the title title is added
13593 to the section.
13594 The FILE argument controls the output file to write gathered release
13596 notes to. The format of the file is:
13597 Section 1
13599 =========
13600 ...
13602 Section 2
13604 =========
13605 ...
13607 Only sections with defined release notes are emitted.
13609 If a section only has short-form notes, it will consist of bullet list:
13611 Section
13613 =======
13614 * Release note 1
13616 * Release note 2
13617 If a section has long-form notes, sub-sections will be emitted:
13619 Section
13621 =======
13622 Note 1 Title
13624 ------------
13625 Description of the first long-form note.
13627 Note 2 Title
13629 ------------
13630 Description of the second long-form note.
13632 If the FILE argument points to an existing file, that file will be
13634 parsed for release notes having the format that would be generated by
13635 this command. The notes from the processed commit messages will be
13636 merged into this parsed set.
13637 During release notes merging:
13639 • Duplicate items are automatically ignored
13641 • Items that are different are automatically ignored if the similarity
13643 is greater than a threshold.
13644 This means that the release notes file can be updated independently
13646 from this command and changes should not be lost when running this com‐
13647 mand on that file. A particular use case for this is to tweak the word‐
13648 ing of a release note after it has been added to the release notes
13649 file.
13650 The -c/--check option checks the commit message for invalid admoni‐
13652 tions.
13653 The -l/--list option, presents the user with a list of existing avail‐
13655 able admonitions along with their title. This also includes the custom
13656 admonitions (if any).
13657 Options:
13659 -r,--rev <REV>
13661 revisions to process for release notes
13662 -c, --check
13664 checks for validity of admonitions (if any)
13665 -l, --list
13667 list the available admonitions with their title
13668 Uncategorized commands
13670 relink
13671 recreates hardlinks between repository clones
13672 Commands
13674 Repository maintenance
13675 relink
13676 recreate hardlinks between two repositories:
13677 hg relink [ORIGIN]
13679 When repositories are cloned locally, their data files will be
13681 hardlinked so that they only use the space of a single repository.
13682 Unfortunately, subsequent pulls into either repository will break
13684 hardlinks for any files touched by the new changesets, even if both
13685 repositories end up pulling the same changes.
13686 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
13688 falling back to a complete copy of the source repository.
13689 This command lets you recreate those hardlinks and reclaim that wasted
13691 space.
13692 This repository will be relinked to share space with ORIGIN, which must
13694 be on the same local disk. If ORIGIN is omitted, looks for "default-re‐
13695 link", then "default", in [paths].
13696 Do not attempt any read operations on this repository while the command
13698 is running. (Both repositories will be locked against writes.)
13699 remotefilelog
13701 remotefilelog causes Mercurial to lazilly fetch file contents (EXPERI‐
13702 MENTAL)
13703 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13705 BILITY GUARANTEES. This means that repositories created with this ex‐
13706 tension may only be usable with the exact version of this exten‐
13707 sion/Mercurial that was used. The extension attempts to enforce this in
13708 order to prevent repository corruption.
13709 remotefilelog works by fetching file contents lazily and storing them
13711 in a cache on the client rather than in revlogs. This allows enormous
13712 histories to be transferred only partially, making them easier to oper‐
13713 ate on.
13714 Configs:
13716 packs.maxchainlen specifies the maximum delta chain length in pack
13718 files
13719 packs.maxpacksize specifies the maximum pack file size
13721 packs.maxpackfilecount specifies the maximum number of packs in the
13723 shared cache (trees only for now)
13725 remotefilelog.backgroundprefetch runs prefetch in background when
13727 True
13728 remotefilelog.bgprefetchrevs specifies revisions to fetch on commit
13730 and
13731 update, and on other commands that use them. Different from
13733 pullprefetch.
13734 remotefilelog.gcrepack does garbage collection during repack when
13736 True
13737 remotefilelog.nodettl specifies maximum TTL of a node in seconds be‐
13739 fore
13740 it is garbage collected
13742 remotefilelog.repackonhggc runs repack on hg gc when True
13744 remotefilelog.prefetchdays specifies the maximum age of a commit in
13746 days after which it is no longer prefetched.
13748 remotefilelog.prefetchdelay specifies delay between background
13750 prefetches in seconds after operations that change the work‐
13752 ing copy parent
13753 remotefilelog.data.gencountlimit constraints the minimum number of
13755 data
13756 pack files required to be considered part of a generation. In
13758 particular, minimum number of packs files > gencountlimit.
13759 remotefilelog.data.generations list for specifying the lower bound
13761 of
13762 each generation of the data pack files. For example, list
13764 ['100MB','1MB'] or ['1MB', '100MB'] will lead to three gener‐
13765 ations: [0, 1MB), [ 1MB, 100MB) and [100MB, infinity).
13766 remotefilelog.data.maxrepackpacks the maximum number of pack files
13768 to
13769 include in an incremental data repack.
13771 remotefilelog.data.repackmaxpacksize the maximum size of a pack file
13773 for
13774 it to be considered for an incremental data repack.
13776 remotefilelog.data.repacksizelimit the maximum total size of pack
13778 files
13779 to include in an incremental data repack.
13781 remotefilelog.history.gencountlimit constraints the minimum number
13783 of
13784 history pack files required to be considered part of a gener‐
13786 ation. In particular, minimum number of packs files > gen‐
13787 countlimit.
13788 remotefilelog.history.generations list for specifying the lower
13790 bound of
13791 each generation of the history pack files. For example, list
13793 [ '100MB', '1MB'] or ['1MB', '100MB'] will lead to three gen‐
13794 erations: [ 0, 1MB), [1MB, 100MB) and [100MB, infinity).
13795 remotefilelog.history.maxrepackpacks the maximum number of pack
13797 files to
13798 include in an incremental history repack.
13800 remotefilelog.history.repackmaxpacksize the maximum size of a pack
13802 file
13803 for it to be considered for an incremental history repack.
13805 remotefilelog.history.repacksizelimit the maximum total size of pack
13807 files to include in an incremental history repack.
13809 remotefilelog.backgroundrepack automatically consolidate packs in
13811 the
13812 background
13814 remotefilelog.cachepath path to cache
13816 remotefilelog.cachegroup if set, make cache directory sgid to this
13818 group
13820 remotefilelog.cacheprocess binary to invoke for fetching file data
13822 remotefilelog.debug turn on remotefilelog-specific debug output
13824 remotefilelog.excludepattern pattern of files to exclude from pulls
13826 remotefilelog.includepattern pattern of files to include in pulls
13828 remotefilelog.fetchwarning: message to print when too many
13830 single-file fetches occur
13832 remotefilelog.getfilesstep number of files to request in a single
13834 RPC
13835 remotefilelog.getfilestype if set to 'threaded' use threads to fetch
13837 files, otherwise use optimistic fetching
13839 remotefilelog.pullprefetch revset for selecting files that should be
13841 eagerly downloaded rather than lazily
13843 remotefilelog.reponame name of the repo. If set, used to partition
13845 data from other repos in a shared store.
13847 remotefilelog.server if true, enable server-side functionality
13849 remotefilelog.servercachepath path for caching blobs on the server
13851 remotefilelog.serverexpiration number of days to keep cached server
13853 blobs
13855 remotefilelog.validatecache if set, check cache entries for corrup‐
13857 tion
13858 before returning blobs
13860 remotefilelog.validatecachelog if set, check cache entries for
13862 corruption before returning metadata
13864 Commands
13866 Repository maintenance
13867 prefetch
13868 prefetch file revisions from the server:
13869 hg prefetch [OPTIONS] [FILE...]
13871 Prefetchs file revisions for the specified revs and stores them in the
13873 local remotefilelog cache. If no rev is specified, the default rev is
13874 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
13875 File names or patterns can be used to limit which files are downloaded.
13876 Return 0 on success.
13878 Options:
13880 -r,--rev <REV[+]>
13882 prefetch the specified revisions
13883 --repack
13885 run repack after prefetch
13886 -b,--base <VALUE>
13888 rev that is assumed to already be local
13889 -I,--include <PATTERN[+]>
13891 include names matching the given patterns
13892 -X,--exclude <PATTERN[+]>
13894 exclude names matching the given patterns
13895 [+] marked option can be specified multiple times
13897 Uncategorized commands
13899 gc
13900 garbage collect the client and server filelog caches:
13901 hg gc [REPO...]
13903 garbage collect the client and server filelog caches
13905 repack
13907 hg repack [OPTIONS]
13908 Options:
13910 --background
13912 run in a background process
13913 --incremental
13915 do an incremental repack
13916 --packsonly
13918 only repack packs (skip loose objects)
13919 verifyremotefilelog
13921 hg verifyremotefilelogs <directory>
13922 Options:
13924 -d, --decompress
13926 decompress the filelogs first
13927 remotenames
13929 showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)
13930 By default both remotebookmarks and remotebranches are turned on. Con‐
13932 fig knob to control the individually are as follows.
13933 Config options to tweak the default behaviour:
13935 remotenames.bookmarks
13937 Boolean value to enable or disable showing of remotebookmarks
13938 (default: True)
13939 remotenames.branches
13941 Boolean value to enable or disable showing of remotebranches
13942 (default: True)
13943 remotenames.hoistedpeer
13945 Name of the peer whose remotebookmarks should be hoisted into
13946 the top-level namespace (default: 'default')
13947 schemes
13949 extend schemes with shortcuts to repository swarms
13950 This extension allows you to specify shortcuts for parent URLs with a
13952 lot of repositories to act like a scheme, for example:
13953 [schemes]
13955 py = http://code.python.org/hg/
13956 After that you can use it like:
13958 hg clone py://trunk/
13960 Additionally there is support for some more complex schemas, for exam‐
13962 ple used by Google Code:
13963 [schemes]
13965 gcode = http://{1}.googlecode.com/hg/
13966 The syntax is taken from Mercurial templates, and you have unlimited
13968 number of variables, starting with {1} and continuing with {2}, {3} and
13969 so on. This variables will receive parts of URL supplied, split by /.
13970 Anything not specified as {part} will be just appended to an URL.
13971 For convenience, the extension adds these schemes by default:
13973 [schemes]
13975 py = http://hg.python.org/
13976 bb = https://bitbucket.org/
13977 bb+ssh = ssh://hg@bitbucket.org/
13978 gcode = https://{1}.googlecode.com/hg/
13979 kiln = https://{1}.kilnhg.com/Repo/
13980 You can override a predefined scheme by defining a new scheme with the
13982 same name.
13983 Commands
13985 Uncategorized commands
13986 share
13987 share a common history between several working directories
13988 The share extension introduces a new command hg share to create a new
13990 working directory. This is similar to hg clone, but doesn't involve
13991 copying or linking the storage of the repository. This allows working
13992 on different branches or changes in parallel without the associated
13993 cost in terms of disk space.
13994 Note: destructive operations or extensions like hg rollback should be
13996 used with care as they can result in confusing problems.
13997 Automatic Pooled Storage for Clones
13999 When this extension is active, hg clone can be configured to automati‐
14000 cally share/pool storage across multiple clones. This mode effectively
14001 converts hg clone to hg clone + hg share. The benefit of using this
14002 mode is the automatic management of store paths and intelligent pooling
14003 of related repositories.
14004 The following share. config options influence this feature:
14006 share.pool
14008 Filesystem path where shared repository data will be stored.
14010 When defined, hg clone will automatically use shared repository
14011 storage instead of creating a store inside each clone.
14012 share.poolnaming
14014 How directory names in share.pool are constructed.
14016 "identity" means the name is derived from the first changeset in
14018 the repository. In this mode, different remotes share storage if
14019 their root/initial changeset is identical. In this mode, the lo‐
14020 cal shared repository is an aggregate of all encountered remote
14021 repositories.
14022 "remote" means the name is derived from the source repository's
14024 path or URL. In this mode, storage is only shared if the path or
14025 URL requested in the hg clone command matches exactly to a
14026 repository that was cloned before.
14027 The default naming mode is "identity".
14029 Sharing requirements and configs of source repository with shares:
14031 By default creating a shared repository only enables sharing a common
14033 history and does not share requirements and configs between them. This
14034 may lead to problems in some cases, for example when you upgrade the
14035 storage format from one repository but does not set related configs in
14036 the shares.
14037 Setting format.exp-share-safe = True enables sharing configs and re‐
14039 quirements. This only applies to shares which are done after enabling
14040 the config option.
14041 For enabling this in existing shares, enable the config option and re‐
14043 share.
14044 For resharing existing shares, make sure your working directory is
14046 clean and there are no untracked files, delete that share and create a
14047 new share.
14048 Commands
14050 Repository creation
14051 share
14052 create a new shared repository:
14053 hg share [-U] [-B] SOURCE [DEST]
14055 Initialize a new repository and working directory that shares its his‐
14057 tory (and optionally bookmarks) with another repository.
14058 Note using rollback or extensions that destroy/modify history (mq,
14060 rebase, etc.) can cause considerable confusion with shared
14061 clones. In particular, if two shared clones are both updated to
14062 the same changeset, and one of them destroys that changeset with
14063 rollback, the other clone will suddenly stop working: all opera‐
14064 tions will fail with "abort: working directory has unknown par‐
14065 ent". The only known workaround is to use debugsetparents on the
14066 broken clone to reset it to a changeset that still exists.
14067 Options:
14069 -U, --noupdate
14071 do not create a working directory
14072 -B, --bookmarks
14074 also share bookmarks
14075 --relative
14077 point to source using a relative path
14078 Repository maintenance
14080 unshare
14081 convert a shared repository to a normal one:
14082 hg unshare
14084 Copy the store data to the repo and remove the sharedpath data.
14086 show
14088 unified command to show various repository information (EXPERIMENTAL)
14089 This extension provides the hg show command, which provides a central
14091 command for displaying commonly-accessed repository data and views of
14092 that data.
14093 The following config options can influence operation.
14095 commands
14097 show.aliasprefix
14098 List of strings that will register aliases for views. e.g. s
14100 will effectively set config options alias.s<view> = show <view>
14101 for all views. i.e. hg swork would execute hg show work.
14102 Aliases that would conflict with existing registrations will not
14104 be performed.
14105 Commands
14107 Change navigation
14108 show
14109 show various repository information:
14110 hg show VIEW
14112 A requested view of repository data is displayed.
14114 If no view is requested, the list of available views is shown and the
14116 command aborts.
14117 Note There are no backwards compatibility guarantees for the output
14119 of this command. Output may change in any future Mercurial re‐
14120 lease.
14121 Consumers wanting stable command output should specify a tem‐
14123 plate via -T/--template.
14124 List of available views:
14126 bookmarks bookmarks and their associated changeset
14128 stack current line of work
14130 work changesets that aren't finished
14132 Options:
14134 -T,--template <TEMPLATE>
14136 display with template
14137 sparse
14139 allow sparse checkouts of the working directory (EXPERIMENTAL)
14140 (This extension is not yet protected by backwards compatibility guaran‐
14142 tees. Any aspect may break in future releases until this notice is re‐
14143 moved.)
14144 This extension allows the working directory to only consist of a subset
14146 of files for the revision. This allows specific files or directories to
14147 be explicitly included or excluded. Many repository operations have
14148 performance proportional to the number of files in the working direc‐
14149 tory. So only realizing a subset of files in the working directory can
14150 improve performance.
14151 Sparse Config Files
14153 The set of files that are part of a sparse checkout are defined by a
14154 sparse config file. The file defines 3 things: includes (files to in‐
14155 clude in the sparse checkout), excludes (files to exclude from the
14156 sparse checkout), and profiles (links to other config files).
14157 The file format is newline delimited. Empty lines and lines beginning
14159 with # are ignored.
14160 Lines beginning with %include `` denote another sparse config file to
14162 include. e.g. ``%include tests.sparse. The filename is relative to the
14163 repository root.
14164 The special lines [include] and [exclude] denote the section for in‐
14166 cludes and excludes that follow, respectively. It is illegal to have
14167 [include] after [exclude].
14168 Non-special lines resemble file patterns to be added to either includes
14170 or excludes. The syntax of these lines is documented by hg help pat‐
14171 terns. Patterns are interpreted as glob: by default and match against
14172 the root of the repository.
14173 Exclusion patterns take precedence over inclusion patterns. So even if
14175 a file is explicitly included, an [exclude] entry can remove it.
14176 For example, say you have a repository with 3 directories, frontend/,
14178 backend/, and tools/. frontend/ and backend/ correspond to different
14179 projects and it is uncommon for someone working on one to need the
14180 files for the other. But tools/ contains files shared between both
14181 projects. Your sparse config files may resemble:
14182 # frontend.sparse
14184 frontend/**
14185 tools/**
14186 # backend.sparse
14188 backend/**
14189 tools/**
14190 Say the backend grows in size. Or there's a directory with thousands of
14192 files you wish to exclude. You can modify the profile to exclude cer‐
14193 tain files:
14194 [include]
14196 backend/**
14197 tools/**
14198 [exclude]
14200 tools/tests/**
14201 Commands
14203 Uncategorized commands
14204 split
14205 command to split a changeset into smaller ones (EXPERIMENTAL)
14206 Commands
14208 Change manipulation
14209 split
14210 split a changeset into smaller ones:
14211 hg split [--no-rebase] [[-r] REV]
14213 Repeatedly prompt changes and commit message for new changesets until
14215 there is nothing left in the original changeset.
14216 If --rev was not given, split the working directory parent.
14218 By default, rebase connected non-obsoleted descendants onto the new
14220 changeset. Use --no-rebase to avoid the rebase.
14221 Options:
14223 -r,--rev <REV>
14225 revision to split
14226 --rebase
14228 rebase descendants after split (default: True)
14229 -d,--date <DATE>
14231 record the specified date as commit date
14232 -u,--user <USER>
14234 record the specified user as committer
14235 sqlitestore
14237 store repository data in SQLite (EXPERIMENTAL)
14238 The sqlitestore extension enables the storage of repository data in
14240 SQLite.
14241 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
14243 BILITY GUARANTEES. This means that repositories created with this ex‐
14244 tension may only be usable with the exact version of this exten‐
14245 sion/Mercurial that was used. The extension attempts to enforce this in
14246 order to prevent repository corruption.
14247 In addition, several features are not yet supported or have known bugs:
14249 • Only some data is stored in SQLite. Changeset, manifest, and other
14251 repository data is not yet stored in SQLite.
14252 • Transactions are not robust. If the process is aborted at the right
14254 time during transaction close/rollback, the repository could be in an
14255 inconsistent state. This problem will diminish once all repository
14256 data is tracked by SQLite.
14257 • Bundle repositories do not work (the ability to use e.g. hg -R <bun‐
14259 dle-file> log to automatically overlay a bundle on top of the exist‐
14260 ing repository).
14261 • Various other features don't work.
14263 This extension should work for basic clone/pull, update, and commit
14265 workflows. Some history rewriting operations may fail due to lack of
14266 support for bundle repositories.
14267 To use, activate the extension and set the storage.new-repo-backend
14269 config option to sqlite to enable new repositories to use SQLite for
14270 storage.
14271 strip
14273 strip changesets and their descendants from history (DEPRECATED)
14274 The functionality of this extension has been included in core Mercurial
14276 since version 5.7. Please use hg debugstrip ... instead.
14277 This extension allows you to strip changesets and all their descendants
14279 from the repository. See the command help for details.
14280 transplant
14282 command to transplant changesets from another branch
14283 This extension allows you to transplant changes to another parent revi‐
14285 sion, possibly in another repository. The transplant is done using
14286 'diff' patches.
14287 Transplanted patches are recorded in .hg/transplant/transplants, as a
14289 map from a changeset hash to its hash in the source repository.
14290 Commands
14292 Change manipulation
14293 transplant
14294 transplant changesets from another branch:
14295 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
14297 Selected changesets will be applied on top of the current working di‐
14299 rectory with the log of the original changeset. The changesets are
14300 copied and will thus appear twice in the history with different identi‐
14301 ties.
14302 Consider using the graft command if everything is inside the same
14304 repository - it will use merges and will usually give a better result.
14305 Use the rebase extension if the changesets are unpublished and you want
14306 to move them instead of copying them.
14307 If --log is specified, log messages will have a comment appended of the
14309 form:
14310 (transplanted from CHANGESETHASH)
14312 You can rewrite the changelog message with the --filter option. Its
14314 argument will be invoked with the current changelog message as $1 and
14315 the patch as $2.
14316 --source/-s specifies another repository to use for selecting change‐
14318 sets, just as if it temporarily had been pulled. If --branch/-b is
14319 specified, these revisions will be used as heads when deciding which
14320 changesets to transplant, just as if only these revisions had been
14321 pulled. If --all/-a is specified, all the revisions up to the heads
14322 specified with --branch will be transplanted.
14323 Example:
14325 • transplant all changes up to REV on top of your current revision:
14327 hg transplant --branch REV --all
14329 You can optionally mark selected transplanted changesets as merge
14331 changesets. You will not be prompted to transplant any ancestors of a
14332 merged transplant, and you can merge descendants of them normally in‐
14333 stead of transplanting them.
14334 Merge changesets may be transplanted directly by specifying the proper
14336 parent changeset by calling hg transplant --parent.
14337 If no merges or revisions are provided, hg transplant will start an in‐
14339 teractive changeset browser.
14340 If a changeset application fails, you can fix the merge by hand and
14342 then resume where you left off by calling hg transplant --continue/-c.
14343 Options:
14345 -s,--source <REPO>
14347 transplant changesets from REPO
14348 -b,--branch <REV[+]>
14350 use this source changeset as head
14351 -a, --all
14353 pull all changesets up to the --branch revisions
14354 -p,--prune <REV[+]>
14356 skip over REV
14357 -m,--merge <REV[+]>
14359 merge at REV
14360 --parent <REV>
14362 parent to choose when transplanting merge
14363 -e, --edit
14365 invoke editor on commit messages
14366 --log append transplant info to log message
14368 --stop stop interrupted transplant
14370 -c, --continue
14372 continue last transplant session after fixing conflicts
14373 --filter <CMD>
14375 filter changesets through command
14376 [+] marked option can be specified multiple times
14378 uncommit
14380 uncommit part or all of a local changeset (EXPERIMENTAL)
14381 This command undoes the effect of a local commit, returning the af‐
14383 fected files to their uncommitted state. This means that files modi‐
14384 fied, added or removed in the changeset will be left unchanged, and so
14385 will remain modified, added and removed in the working directory.
14386 Commands
14388 Change manipulation
14389 unamend
14390 undo the most recent amend operation on a current changeset:
14391 hg unamend
14393 This command will roll back to the previous version of a changeset,
14395 leaving working directory in state in which it was before running hg
14396 amend (e.g. files modified as part of an amend will be marked as modi‐
14397 fied hg status)
14398 uncommit
14400 uncommit part or all of a local changeset:
14401 hg uncommit [OPTION]... [FILE]...
14403 This command undoes the effect of a local commit, returning the af‐
14405 fected files to their uncommitted state. This means that files modified
14406 or deleted in the changeset will be left unchanged, and so will remain
14407 modified in the working directory.
14408 If no files are specified, the commit will be pruned, unless --keep is
14410 given.
14411 Options:
14413 --keep allow an empty commit after uncommitting
14415 --allow-dirty-working-copy
14417 allow uncommit with outstanding changes
14418 -n,--note <TEXT>
14420 store a note on uncommit
14421 -I,--include <PATTERN[+]>
14423 include names matching the given patterns
14424 -X,--exclude <PATTERN[+]>
14426 exclude names matching the given patterns
14427 -m,--message <TEXT>
14429 use text as commit message
14430 -l,--logfile <FILE>
14432 read commit message from file
14433 -d,--date <DATE>
14435 record the specified date as commit date
14436 -u,--user <USER>
14438 record the specified user as committer
14439 -D, --currentdate
14441 record the current date as commit date
14442 -U, --currentuser
14444 record the current user as committer
14445 [+] marked option can be specified multiple times
14447 win32mbcs
14449 allow the use of MBCS paths with problematic encodings
14450 Some MBCS encodings are not good for some path operations (i.e. split‐
14452 ting path, case conversion, etc.) with its encoded bytes. We call such
14453 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
14454 extension can be used to fix the issue with those encodings by wrapping
14455 some functions to convert to Unicode string before path operation.
14456 This extension is useful for:
14458 • Japanese Windows users using shift_jis encoding.
14460 • Chinese Windows users using big5 encoding.
14462 • All users who use a repository with one of problematic encodings on
14464 case-insensitive file system.
14465 This extension is not needed for:
14467 • Any user who use only ASCII chars in path.
14469 • Any user who do not use any of problematic encodings.
14471 Note that there are some limitations on using this extension:
14473 • You should use single encoding in one repository.
14475 • If the repository path ends with 0x5c, .hg/hgrc cannot be read.
14477 • win32mbcs is not compatible with fixutf8 extension.
14479 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
14481 can specify the encoding by config option:
14482 [win32mbcs]
14484 encoding = sjis
14485 It is useful for the users who want to commit with UTF-8 log message.
14487 win32text
14489 perform automatic newline conversion (DEPRECATED)
14490 Deprecation: The win32text extension requires each user to configure
14492 the extension again and again for each clone since the configuration
14493 is not copied when cloning.
14494 We have therefore made the eol as an alternative. The eol uses a
14496 version controlled file for its configuration and each clone will
14497 therefore use the right settings from the start.
14498 To perform automatic newline conversion, use:
14500 [extensions]
14502 win32text =
14503 [encode]
14504 ** = cleverencode:
14505 # or ** = macencode:
14506 [decode]
14508 ** = cleverdecode:
14509 # or ** = macdecode:
14510 If not doing conversion, to make sure you do not commit CRLF/CR by ac‐
14512 cident:
14513 [hooks]
14515 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
14516 # or pretxncommit.cr = python:hgext.win32text.forbidcr
14517 To do the same check on a server to prevent CRLF/CR from being pushed
14519 or pulled:
14520 [hooks]
14522 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
14523 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
14524 zeroconf
14526 discover and advertise repositories on the local network
14527 The zeroconf extension will advertise hg serve instances over DNS-SD so
14529 that they can be discovered using the hg paths command without knowing
14530 the server's IP address.
14531 To allow other people to discover your repository using run hg serve in
14533 your repository:
14534 $ cd test
14536 $ hg serve
14537 You can discover Zeroconf-enabled repositories by running hg paths:
14539 $ hg paths
14541 zc-test = http://example.com:8000/test
14542
14544 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
14545 This file contains defaults and configuration. Values in
14547 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
14548 tings made in the global /etc/mercurial/hgrc configuration. See
14549 hgrc(5) for details of the contents and format of these files.
14550 .hgignore
14552 This file contains regular expressions (one per line) that de‐
14554 scribe file names that should be ignored by hg. For details, see
14555 hgignore(5).
14556 .hgsub
14558 This file defines the locations of all subrepositories, and
14560 tells where the subrepository checkouts came from. For details,
14561 see hg help subrepos.
14562 .hgsubstate
14564 This file is where Mercurial stores all nested repository
14566 states. NB: This file should not be edited manually.
14567 .hgtags
14569 This file contains changeset hash values and text tag names (one
14571 of each separated by spaces) that correspond to tagged versions
14572 of the repository contents. The file content is encoded using
14573 UTF-8.
14574 .hg/last-message.txt
14576 This file is used by hg commit to store a backup of the commit
14578 message in case the commit fails.
14579 .hg/localtags
14581 This file can be used to define local tags which are not shared
14583 among repositories. The file format is the same as for .hgtags,
14584 but it is encoded using the local system encoding.
14585 Some commands (e.g. revert) produce backup files ending in .orig, if
14587 the .orig file already exists and is not tracked by Mercurial, it will
14588 be overwritten.
14589
14591 Probably lots, please post them to the mailing list (see Resources
14592 below) when you find them.
14593
14595 hgignore(5), hgrc(5)
14596
14598 Written by Olivia Mackall <olivia@selenic.com>
14599
14601 Main Web Site: https://mercurial-scm.org/
14602 Source code repository: https://www.mercurial-scm.org/repo/hg
14604 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
14606
14608 Copyright (C) 2005-2022 Olivia Mackall. Free use of this software is
14609 granted under the terms of the GNU General Public License version 2 or
14610 any later version.
14611
14613 Olivia Mackall <olivia@selenic.com>
14614 Organization: Mercurial
14616 HG(1)