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
24 revision 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
125 remotely 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
143 revision 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
215 ancestors
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
308 locally 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 Specifying bookmark as . is equivalent to specifying the active book‐
567 mark's name.
568 Returns 0 on success, 1 if an update had unresolved files.
570 Options:
572 -u, --update
574 update to new branch head if new descendants were pulled
575 -f, --force
577 run even when remote repository is unrelated
578 --confirm
580 confirm pull before applying changes
581 -r,--rev <REV[+]>
583 a remote changeset intended to be added
584 -B,--bookmark <BOOKMARK[+]>
586 bookmark to pull
587 -b,--branch <BRANCH[+]>
589 a specific branch you would like to pull
590 -e,--ssh <CMD>
592 specify ssh command to use
593 --remotecmd <CMD>
595 specify hg command to run on the remote side
596 --insecure
598 do not verify server certificate (ignoring web.cacerts config)
599 [+] marked option can be specified multiple times
601 push
603 push changes to the specified destination:
604 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]
606 Push changesets from the local repository to the specified destination.
608 This operation is symmetrical to pull: it is identical to a pull in the
610 destination repository from the current one.
611 By default, push will not allow creation of new heads at the destina‐
613 tion, since multiple heads would make it unclear which head to use. In
614 this situation, it is recommended to pull and merge before pushing.
615 Use --new-branch if you want to allow push to create a new named branch
617 that is not present at the destination. This allows you to only create
618 a new branch without forcing other changes.
619 Note Extra care should be taken with the -f/--force option, which
621 will push all new heads on all branches, an action which will
622 almost always cause confusion for collaborators.
623 If -r/--rev is used, the specified revision and all its ancestors will
625 be pushed to the remote repository.
626 If -B/--bookmark is used, the specified bookmarked revision, its ances‐
628 tors, and the bookmark will be pushed to the remote repository. Speci‐
629 fying . is equivalent to specifying the active bookmark's name.
630 Please see hg help urls for important details about ssh:// URLs. If
632 DESTINATION is omitted, a default path will be used.
633 The --pushvars option sends strings to the server that become environ‐
635 ment variables prepended with HG_USERVAR_. For example, --pushvars
636 ENABLE_FEATURE=true, provides the server side hooks with HG_USER‐
637 VAR_ENABLE_FEATURE=true as part of their environment.
638 pushvars can provide for user-overridable hooks as well as set debug
640 levels. One example is having a hook that blocks commits containing
641 conflict markers, but enables the user to override the hook if the file
642 is using conflict markers for testing purposes or the file format has
643 strings that look like conflict markers.
644 By default, servers will ignore --pushvars. To enable it add the fol‐
646 lowing to your configuration file:
647 [push]
649 pushvars.server = true
650 Returns 0 if push was successful, 1 if nothing to push.
652 Options:
654 -f, --force
656 force push
657 -r,--rev <REV[+]>
659 a changeset intended to be included in the destination
660 -B,--bookmark <BOOKMARK[+]>
662 bookmark to push
663 -b,--branch <BRANCH[+]>
665 a specific branch you would like to push
666 --new-branch
668 allow pushing a new branch
669 --pushvars <VALUE[+]>
671 variables that can be sent to server (ADVANCED)
672 --publish
674 push the changeset as public (EXPERIMENTAL)
675 -e,--ssh <CMD>
677 specify ssh command to use
678 --remotecmd <CMD>
680 specify hg command to run on the remote side
681 --insecure
683 do not verify server certificate (ignoring web.cacerts config)
684 [+] marked option can be specified multiple times
686 serve
688 start stand-alone webserver:
689 hg serve [OPTION]...
691 Start a local HTTP repository browser and pull server. You can use this
693 for ad-hoc sharing and browsing of repositories. It is recommended to
694 use a real web server to serve a repository for longer periods of time.
695 Please note that the server does not implement access control. This
697 means that, by default, anybody can read from the server and nobody can
698 write to it by default. Set the web.allow-push option to * to allow
699 everybody to push to the server. You should use a real web server if
700 you need to authenticate users.
701 By default, the server logs accesses to stdout and errors to stderr.
703 Use the -A/--accesslog and -E/--errorlog options to log to files.
704 To have the server choose a free port number to listen on, specify a
706 port number of 0; in this case, the server will print the port number
707 it uses.
708 Returns 0 on success.
710 Options:
712 -A,--accesslog <FILE>
714 name of access log file to write to
715 -d, --daemon
717 run server in background
718 --daemon-postexec <VALUE[+]>
720 used internally by daemon mode
721 -E,--errorlog <FILE>
723 name of error log file to write to
724 -p,--port <PORT>
726 port to listen on (default: 8000)
727 -a,--address <ADDR>
729 address to listen on (default: all interfaces)
730 --prefix <PREFIX>
732 prefix path to serve from (default: server root)
733 -n,--name <NAME>
735 name to show in web pages (default: working directory)
736 --web-conf <FILE>
738 name of the hgweb config file (see 'hg help hgweb')
739 --webdir-conf <FILE>
741 name of the hgweb config file (DEPRECATED)
742 --pid-file <FILE>
744 name of file to write process ID to
745 --stdio
747 for remote clients (ADVANCED)
748 --cmdserver <MODE>
750 for remote clients (ADVANCED)
751 -t,--templates <TEMPLATE>
753 web templates to use
754 --style <STYLE>
756 template style to use
757 -6, --ipv6
759 use IPv6 in addition to IPv4
760 --certificate <FILE>
762 SSL certificate file
763 --print-url
765 start and print only the URL
766 -S, --subrepos
768 recurse into subrepositories
769 [+] marked option can be specified multiple times
771 Change creation
773 commit
774 commit the specified files or all outstanding changes:
775 hg commit [OPTION]... [FILE]...
777 Commit changes to the given files into the repository. Unlike a cen‐
779 tralized SCM, this operation is a local operation. See hg push for a
780 way to actively distribute your changes.
781 If a list of files is omitted, all changes reported by hg status will
783 be committed.
784 If you are committing the result of a merge, do not provide any file‐
786 names or -I/-X filters.
787 If no commit message is specified, Mercurial starts your configured
789 editor where you can enter a message. In case your commit fails, you
790 will find a backup of your message in .hg/last-message.txt.
791 The --close-branch flag can be used to mark the current branch head
793 closed. When all heads of a branch are closed, the branch will be con‐
794 sidered closed and no longer listed.
795 The --amend flag can be used to amend the parent of the working direc‐
797 tory with a new commit that contains the changes in the parent in addi‐
798 tion to those currently reported by hg status, if there are any. The
799 old commit is stored in a backup bundle in .hg/strip-backup (see hg
800 help bundle and hg help unbundle on how to restore it).
801 Message, user and date are taken from the amended commit unless speci‐
803 fied. When a message isn't specified on the command line, the editor
804 will open with the message of the amended commit.
805 It is not possible to amend public changesets (see hg help phases) or
807 changesets that have children.
808 See hg help dates for a list of formats valid for -d/--date.
810 Returns 0 on success, 1 if nothing changed.
812 Examples:
814 · commit all files ending in .py:
816 hg commit --include "set:**.py"
818 · commit all non-binary files:
820 hg commit --exclude "set:binary()"
822 · amend the current commit and set the date to now:
824 hg commit --amend --date now
826 Options:
828 -A, --addremove
830 mark new/missing files as added/removed before committing
831 --close-branch
833 mark a branch head as closed
834 --amend
836 amend the parent of the working directory
837 -s, --secret
839 use the secret phase for committing
840 -e, --edit
842 invoke editor on commit messages
843 --force-close-branch
845 forcibly close branch from a non-head changeset (ADVANCED)
846 -i, --interactive
848 use interactive mode
849 -I,--include <PATTERN[+]>
851 include names matching the given patterns
852 -X,--exclude <PATTERN[+]>
854 exclude names matching the given patterns
855 -m,--message <TEXT>
857 use text as commit message
858 -l,--logfile <FILE>
860 read commit message from file
861 -d,--date <DATE>
863 record the specified date as commit date
864 -u,--user <USER>
866 record the specified user as committer
867 -S, --subrepos
869 recurse into subrepositories
870 [+] marked option can be specified multiple times
872 aliases: ci
874 Change manipulation
876 abort
877 abort an unfinished operation (EXPERIMENTAL):
878 hg abort
880 Aborts a multistep operation like graft, histedit, rebase, merge, and
882 unshelve if they are in an unfinished state.
883 use --dry-run/-n to dry run the command.
885 Options:
887 -n, --dry-run
889 do not perform actions, just print output
890 backout
892 reverse effect of earlier changeset:
893 hg backout [OPTION]... [-r] REV
895 Prepare a new changeset with the effect of REV undone in the current
897 working directory. If no conflicts were encountered, it will be commit‐
898 ted immediately.
899 If REV is the parent of the working directory, then this new changeset
901 is committed automatically (unless --no-commit is specified).
902 Note hg backout cannot be used to fix either an unwanted or incorrect
904 merge.
905 Examples:
907 · Reverse the effect of the parent of the working directory. This
909 backout will be committed immediately:
910 hg backout -r .
912 · Reverse the effect of previous bad revision 23:
914 hg backout -r 23
916 · Reverse the effect of previous bad revision 23 and leave changes
918 uncommitted:
919 hg backout -r 23 --no-commit
921 hg commit -m "Backout revision 23"
922 By default, the pending changeset will have one parent, maintaining a
924 linear history. With --merge, the pending changeset will instead have
925 two parents: the old parent of the working directory and a new child of
926 REV that simply undoes REV.
927 Before version 1.7, the behavior without --merge was equivalent to
929 specifying --merge followed by hg update --clean . to cancel the merge
930 and leave the child of REV as a head to be merged separately.
931 See hg help dates for a list of formats valid for -d/--date.
933 See hg help revert for a way to restore files to the state of another
935 revision.
936 Returns 0 on success, 1 if nothing to backout or there are unresolved
938 files.
939 Options:
941 --merge
943 merge with old dirstate parent after backout
944 --commit
946 commit if no conflicts were encountered (DEPRECATED)
947 --no-commit
949 do not commit
950 --parent <REV>
952 parent to choose when backing out merge (DEPRECATED)
953 -r,--rev <REV>
955 revision to backout
956 -e, --edit
958 invoke editor on commit messages
959 -t,--tool <TOOL>
961 specify merge tool
962 -I,--include <PATTERN[+]>
964 include names matching the given patterns
965 -X,--exclude <PATTERN[+]>
967 exclude names matching the given patterns
968 -m,--message <TEXT>
970 use text as commit message
971 -l,--logfile <FILE>
973 read commit message from file
974 -d,--date <DATE>
976 record the specified date as commit date
977 -u,--user <USER>
979 record the specified user as committer
980 [+] marked option can be specified multiple times
982 continue
984 resumes an interrupted operation (EXPERIMENTAL):
985 hg continue
987 Finishes a multistep operation like graft, histedit, rebase, merge, and
989 unshelve if they are in an interrupted state.
990 use --dry-run/-n to dry run the command.
992 Options:
994 -n, --dry-run
996 do not perform actions, just print output
997 graft
999 copy changes from other branches onto the current branch:
1000 hg graft [OPTION]... [-r REV]... REV...
1002 This command uses Mercurial's merge logic to copy individual changes
1004 from other branches without merging branches in the history graph. This
1005 is sometimes known as 'backporting' or 'cherry-picking'. By default,
1006 graft will copy user, date, and description from the source changesets.
1007 Changesets that are ancestors of the current revision, that have
1009 already been grafted, or that are merges will be skipped.
1010 If --log is specified, log messages will have a comment appended of the
1012 form:
1013 (grafted from CHANGESETHASH)
1015 If --force is specified, revisions will be grafted even if they are
1017 already ancestors of, or have been grafted to, the destination. This
1018 is useful when the revisions have since been backed out.
1019 If a graft merge results in conflicts, the graft process is interrupted
1021 so that the current merge can be manually resolved. Once all conflicts
1022 are addressed, the graft process can be continued with the -c/--con‐
1023 tinue option.
1024 The -c/--continue option reapplies all the earlier options.
1026 The --base option exposes more of how graft internally uses merge with
1028 a custom base revision. --base can be used to specify another ancestor
1029 than the first and only parent.
1030 The command:
1032 hg graft -r 345 --base 234
1034 is thus pretty much the same as:
1036 hg diff -r 234 -r 345 | hg import
1038 but using merge to resolve conflicts and track moved files.
1040 The result of a merge can thus be backported as a single commit by
1042 specifying one of the merge parents as base, and thus effectively
1043 grafting the changes from the other side.
1044 It is also possible to collapse multiple changesets and clean up his‐
1046 tory by specifying another ancestor as base, much like rebase --col‐
1047 lapse --keep.
1048 The commit message can be tweaked after the fact using commit --amend .
1050 For using non-ancestors as the base to backout changes, see the backout
1052 command and the hidden --parent option.
1053 Examples:
1055 · copy a single change to the stable branch and edit its description:
1057 hg update stable
1059 hg graft --edit 9393
1060 · graft a range of changesets with one exception, updating dates:
1062 hg graft -D "2085::2093 and not 2091"
1064 · continue a graft after resolving conflicts:
1066 hg graft -c
1068 · show the source of a grafted changeset:
1070 hg log --debug -r .
1072 · show revisions sorted by date:
1074 hg log -r "sort(all(), date)"
1076 · backport the result of a merge as a single commit:
1078 hg graft -r 123 --base 123^
1080 · land a feature branch as one changeset:
1082 hg up -cr default
1084 hg graft -r featureX --base "ancestor('featureX', 'default')"
1085 See hg help revisions for more about specifying revisions.
1087 Returns 0 on successful completion, 1 if there are unresolved files.
1089 Options:
1091 -r,--rev <REV[+]>
1093 revisions to graft
1094 --base <REV>
1096 base revision when doing the graft merge (ADVANCED)
1097 -c, --continue
1099 resume interrupted graft
1100 --stop stop interrupted graft
1102 --abort
1104 abort interrupted graft
1105 -e, --edit
1107 invoke editor on commit messages
1108 --log append graft info to log message
1110 --no-commit
1112 don't commit, just apply the changes in working directory
1113 -f, --force
1115 force graft
1116 -D, --currentdate
1118 record the current date as commit date
1119 -U, --currentuser
1121 record the current user as committer
1122 -d,--date <DATE>
1124 record the specified date as commit date
1125 -u,--user <USER>
1127 record the specified user as committer
1128 -t,--tool <TOOL>
1130 specify merge tool
1131 -n, --dry-run
1133 do not perform actions, just print output
1134 [+] marked option can be specified multiple times
1136 merge
1138 merge another revision into working directory:
1139 hg merge [-P] [[-r] REV]
1141 The current working directory is updated with all changes made in the
1143 requested revision since the last common predecessor revision.
1144 Files that changed between either parent are marked as changed for the
1146 next commit and a commit must be performed before any further updates
1147 to the repository are allowed. The next commit will have two parents.
1148 --tool can be used to specify the merge tool used for file merges. It
1150 overrides the HGMERGE environment variable and your configuration
1151 files. See hg help merge-tools for options.
1152 If no revision is specified, the working directory's parent is a head
1154 revision, and the current branch contains exactly one other head, the
1155 other head is merged with by default. Otherwise, an explicit revision
1156 with which to merge must be provided.
1157 See hg help resolve for information on handling file conflicts.
1159 To undo an uncommitted merge, use hg merge --abort which will check out
1161 a clean copy of the original merge parent, losing all changes.
1162 Returns 0 on success, 1 if there are unresolved files.
1164 Options:
1166 -f, --force
1168 force a merge including outstanding changes (DEPRECATED)
1169 -r,--rev <REV>
1171 revision to merge
1172 -P, --preview
1174 review revisions to merge (no merge is performed)
1175 --abort
1177 abort the ongoing merge
1178 -t,--tool <TOOL>
1180 specify merge tool
1181 Change organization
1183 bookmarks
1184 create a new bookmark or list existing bookmarks:
1185 hg bookmarks [OPTIONS]... [NAME]...
1187 Bookmarks are labels on changesets to help track lines of development.
1189 Bookmarks are unversioned and can be moved, renamed and deleted.
1190 Deleting or moving a bookmark has no effect on the associated change‐
1191 sets.
1192 Creating or updating to a bookmark causes it to be marked as 'active'.
1194 The active bookmark is indicated with a '*'. When a commit is made,
1195 the active bookmark will advance to the new commit. A plain hg update
1196 will also advance an active bookmark, if possible. Updating away from
1197 a bookmark will cause it to be deactivated.
1198 Bookmarks can be pushed and pulled between repositories (see hg help
1200 push and hg help pull). If a shared bookmark has diverged, a new
1201 'divergent bookmark' of the form 'name@path' will be created. Using hg
1202 merge will resolve the divergence.
1203 Specifying bookmark as '.' to -m/-d/-l options is equivalent to speci‐
1205 fying the active bookmark's name.
1206 A bookmark named '@' has the special property that hg clone will check
1208 it out by default if it exists.
1209 Template:
1211 The following keywords are supported in addition to the common template
1213 keywords and functions such as {bookmark}. See also hg help templates.
1214 active Boolean. True if the bookmark is active.
1216 Examples:
1218 · create an active bookmark for a new line of development:
1220 hg book new-feature
1222 · create an inactive bookmark as a place marker:
1224 hg book -i reviewed
1226 · create an inactive bookmark on another changeset:
1228 hg book -r .^ tested
1230 · rename bookmark turkey to dinner:
1232 hg book -m turkey dinner
1234 · move the '@' bookmark from another branch:
1236 hg book -f @
1238 · print only the active bookmark name:
1240 hg book -ql .
1242 Options:
1244 -f, --force
1246 force
1247 -r,--rev <REV>
1249 revision for bookmark action
1250 -d, --delete
1252 delete a given bookmark
1253 -m,--rename <OLD>
1255 rename a given bookmark
1256 -i, --inactive
1258 mark a bookmark inactive
1259 -l, --list
1261 list existing bookmarks
1262 -T,--template <TEMPLATE>
1264 display with template
1265 aliases: bookmark
1267 branch
1269 set or show the current branch name:
1270 hg branch [-fC] [NAME]
1272 Note Branch names are permanent and global. Use hg bookmark to create
1274 a light-weight bookmark instead. See hg help glossary for more
1275 information about named branches and bookmarks.
1276 With no argument, show the current branch name. With one argument, set
1278 the working directory branch name (the branch will not exist in the
1279 repository until the next commit). Standard practice recommends that
1280 primary development take place on the 'default' branch.
1281 Unless -f/--force is specified, branch will not let you set a branch
1283 name that already exists.
1284 Use -C/--clean to reset the working directory branch to that of the
1286 parent of the working directory, negating a previous branch change.
1287 Use the command hg update to switch to an existing branch. Use hg com‐
1289 mit --close-branch to mark this branch head as closed. When all heads
1290 of a branch are closed, the branch will be considered closed.
1291 Returns 0 on success.
1293 Options:
1295 -f, --force
1297 set branch name even if it shadows an existing branch
1298 -C, --clean
1300 reset branch name to parent branch name
1301 -r,--rev <VALUE[+]>
1303 change branches of the given revs (EXPERIMENTAL)
1304 [+] marked option can be specified multiple times
1306 branches
1308 list repository named branches:
1309 hg branches [-c]
1311 List the repository's named branches, indicating which ones are inac‐
1313 tive. If -c/--closed is specified, also list branches which have been
1314 marked closed (see hg commit --close-branch).
1315 Use the command hg update to switch to an existing branch.
1317 Template:
1319 The following keywords are supported in addition to the common template
1321 keywords and functions such as {branch}. See also hg help templates.
1322 active Boolean. True if the branch is active.
1324 closed Boolean. True if the branch is closed.
1326 current
1328 Boolean. True if it is the current branch.
1329 Returns 0.
1331 Options:
1333 -a, --active
1335 show only branches that have unmerged heads (DEPRECATED)
1336 -c, --closed
1338 show normal and closed branches
1339 -r,--rev <VALUE[+]>
1341 show branch name(s) of the given rev
1342 -T,--template <TEMPLATE>
1344 display with template
1345 [+] marked option can be specified multiple times
1347 phase
1349 set or show the current phase name:
1350 hg phase [-p|-d|-s] [-f] [-r] [REV...]
1352 With no argument, show the phase name of the current revision(s).
1354 With one of -p/--public, -d/--draft or -s/--secret, change the phase
1356 value of the specified revisions.
1357 Unless -f/--force is specified, hg phase won't move changesets from a
1359 lower phase to a higher phase. Phases are ordered as follows:
1360 public < draft < secret
1362 Returns 0 on success, 1 if some phases could not be changed.
1364 (For more information about the phases concept, see hg help phases.)
1366 Options:
1368 -p, --public
1370 set changeset phase to public
1371 -d, --draft
1373 set changeset phase to draft
1374 -s, --secret
1376 set changeset phase to secret
1377 -f, --force
1379 allow to move boundary backward
1380 -r,--rev <REV[+]>
1382 target revision
1383 [+] marked option can be specified multiple times
1385 tag
1387 add one or more tags for the current or given revision:
1388 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
1390 Name a particular revision using <name>.
1392 Tags are used to name particular revisions of the repository and are
1394 very useful to compare different revisions, to go back to significant
1395 earlier versions or to mark branch points as releases, etc. Changing an
1396 existing tag is normally disallowed; use -f/--force to override.
1397 If no revision is given, the parent of the working directory is used.
1399 To facilitate version control, distribution, and merging of tags, they
1401 are stored as a file named ".hgtags" which is managed similarly to
1402 other project files and can be hand-edited if necessary. This also
1403 means that tagging creates a new commit. The file ".hg/localtags" is
1404 used for local tags (not shared among repositories).
1405 Tag commits are usually made at the head of a branch. If the parent of
1407 the working directory is not a branch head, hg tag aborts; use
1408 -f/--force to force the tag commit to be based on a non-head changeset.
1409 See hg help dates for a list of formats valid for -d/--date.
1411 Since tag names have priority over branch names during revision lookup,
1413 using an existing branch name as a tag name is discouraged.
1414 Returns 0 on success.
1416 Options:
1418 -f, --force
1420 force tag
1421 -l, --local
1423 make the tag local
1424 -r,--rev <REV>
1426 revision to tag
1427 --remove
1429 remove a tag
1430 -e, --edit
1432 invoke editor on commit messages
1433 -m,--message <TEXT>
1435 use text as commit message
1436 -d,--date <DATE>
1438 record the specified date as commit date
1439 -u,--user <USER>
1441 record the specified user as committer
1442 tags
1444 list repository tags:
1445 hg tags
1447 This lists both regular and local tags. When the -v/--verbose switch is
1449 used, a third column "local" is printed for local tags. When the
1450 -q/--quiet switch is used, only the tag name is printed.
1451 Template:
1453 The following keywords are supported in addition to the common template
1455 keywords and functions such as {tag}. See also hg help templates.
1456 type String. local for local tags.
1458 Returns 0 on success.
1460 Options:
1462 -T,--template <TEMPLATE>
1464 display with template
1465 File content management
1467 annotate
1468 show changeset information by line for each file:
1469 hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...
1471 List changes in files, showing the revision id responsible for each
1473 line.
1474 This command is useful for discovering when a change was made and by
1476 whom.
1477 If you include --file, --user, or --date, the revision number is sup‐
1479 pressed unless you also include --number.
1480 Without the -a/--text option, annotate will avoid processing files it
1482 detects as binary. With -a, annotate will annotate the file anyway,
1483 although the results will probably be neither useful nor desirable.
1484 Template:
1486 The following keywords are supported in addition to the common template
1488 keywords and functions. See also hg help templates.
1489 lines List of lines with annotation data.
1491 path String. Repository-absolute path of the specified file.
1493 And each entry of {lines} provides the following sub-keywords in addi‐
1495 tion to {date}, {node}, {rev}, {user}, etc.
1496 line String. Line content.
1498 lineno Integer. Line number at that revision.
1500 path String. Repository-absolute path of the file at that revision.
1502 See hg help templates.operators for the list expansion syntax.
1504 Returns 0 on success.
1506 Options:
1508 -r,--rev <REV>
1510 annotate the specified revision
1511 --follow
1513 follow copies/renames and list the filename (DEPRECATED)
1514 --no-follow
1516 don't follow copies and renames
1517 -a, --text
1519 treat all files as text
1520 -u, --user
1522 list the author (long with -v)
1523 -f, --file
1525 list the filename
1526 -d, --date
1528 list the date (short with -q)
1529 -n, --number
1531 list the revision number (default)
1532 -c, --changeset
1534 list the changeset
1535 -l, --line-number
1537 show line number at the first appearance
1538 --skip <REV[+]>
1540 revset to not display (EXPERIMENTAL)
1541 -w, --ignore-all-space
1543 ignore white space when comparing lines
1544 -b, --ignore-space-change
1546 ignore changes in the amount of white space
1547 -B, --ignore-blank-lines
1549 ignore changes whose lines are all blank
1550 -Z, --ignore-space-at-eol
1552 ignore changes in whitespace at EOL
1553 -I,--include <PATTERN[+]>
1555 include names matching the given patterns
1556 -X,--exclude <PATTERN[+]>
1558 exclude names matching the given patterns
1559 -T,--template <TEMPLATE>
1561 display with template
1562 [+] marked option can be specified multiple times
1564 aliases: blame
1566 cat
1568 output the current or given revision of files:
1569 hg cat [OPTION]... FILE...
1571 Print the specified files as they were at the given revision. If no
1573 revision is given, the parent of the working directory is used.
1574 Output may be to a file, in which case the name of the file is given
1576 using a template string. See hg help templates. In addition to the com‐
1577 mon template keywords, the following formatting rules are supported:
1578 %%
1580 literal "%" character
1582 %s
1584 basename of file being printed
1586 %d
1588 dirname of file being printed, or '.' if in repository root
1590 %p
1592 root-relative path name of file being printed
1594 %H
1596 changeset hash (40 hexadecimal digits)
1598 %R
1600 changeset revision number
1602 %h
1604 short-form changeset hash (12 hexadecimal digits)
1606 %r
1608 zero-padded changeset revision number
1610 %b
1612 basename of the exporting repository
1614 \
1616 literal "" character
1618 Template:
1620 The following keywords are supported in addition to the common template
1622 keywords and functions. See also hg help templates.
1623 data String. File content.
1625 path String. Repository-absolute path of the file.
1627 Returns 0 on success.
1629 Options:
1631 -o,--output <FORMAT>
1633 print output to file with formatted name
1634 -r,--rev <REV>
1636 print the given revision
1637 --decode
1639 apply any matching decode filter
1640 -I,--include <PATTERN[+]>
1642 include names matching the given patterns
1643 -X,--exclude <PATTERN[+]>
1645 exclude names matching the given patterns
1646 -T,--template <TEMPLATE>
1648 display with template
1649 [+] marked option can be specified multiple times
1651 copy
1653 mark files as copied for the next commit:
1654 hg copy [OPTION]... SOURCE... DEST
1656 Mark dest as having copies of source files. If dest is a directory,
1658 copies are put in that directory. If dest is a file, the source must be
1659 a single file.
1660 By default, this command copies the contents of files as they exist in
1662 the working directory. If invoked with -A/--after, the operation is
1663 recorded, but no copying is performed.
1664 To undo marking a file as copied, use --forget. With that option, all
1666 given (positional) arguments are unmarked as copies. The destination
1667 file(s) will be left in place (still tracked).
1668 This command takes effect with the next commit by default.
1670 Returns 0 on success, 1 if errors are encountered.
1672 Options:
1674 --forget
1676 unmark a file as copied
1677 -A, --after
1679 record a copy that has already occurred
1680 --at-rev <REV>
1682 (un)mark copies in the given revision (EXPERIMENTAL)
1683 -f, --force
1685 forcibly copy over an existing managed file
1686 -I,--include <PATTERN[+]>
1688 include names matching the given patterns
1689 -X,--exclude <PATTERN[+]>
1691 exclude names matching the given patterns
1692 -n, --dry-run
1694 do not perform actions, just print output
1695 [+] marked option can be specified multiple times
1697 aliases: cp
1699 diff
1701 diff repository (or selected files):
1702 hg diff [OPTION]... ([-c REV] | [-r REV1 [-r REV2]]) [FILE]...
1704 Show differences between revisions for the specified files.
1706 Differences between files are shown using the unified diff format.
1708 Note hg diff may generate unexpected results for merges, as it will
1710 default to comparing against the working directory's first par‐
1711 ent changeset if no revisions are specified.
1712 When two revision arguments are given, then changes are shown between
1714 those revisions. If only one revision is specified then that revision
1715 is compared to the working directory, and, when no revisions are speci‐
1716 fied, the working directory files are compared to its first parent.
1717 Alternatively you can specify -c/--change with a revision to see the
1719 changes in that changeset relative to its first parent.
1720 Without the -a/--text option, diff will avoid generating diffs of files
1722 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1723 bly with undesirable results.
1724 Use the -g/--git option to generate diffs in the git extended diff for‐
1726 mat. For more information, read hg help diffs.
1727 Examples:
1729 · compare a file in the current working directory to its parent:
1731 hg diff foo.c
1733 · compare two historical versions of a directory, with rename info:
1735 hg diff --git -r 1.0:1.2 lib/
1737 · get change stats relative to the last change on some date:
1739 hg diff --stat -r "date('may 2')"
1741 · diff all newly-added files that contain a keyword:
1743 hg diff "set:added() and grep(GNU)"
1745 · compare a revision and its parents:
1747 hg diff -c 9353 # compare against first parent
1749 hg diff -r 9353^:9353 # same using revset syntax
1750 hg diff -r 9353^2:9353 # compare against the second parent
1751 Returns 0 on success.
1753 Options:
1755 -r,--rev <REV[+]>
1757 revision
1758 -c,--change <REV>
1760 change made by revision
1761 -a, --text
1763 treat all files as text
1764 -g, --git
1766 use git extended diff format (DEFAULT: diff.git)
1767 --binary
1769 generate binary diffs in git mode (default)
1770 --nodates
1772 omit dates from diff headers
1773 --noprefix
1775 omit a/ and b/ prefixes from filenames
1776 -p, --show-function
1778 show which function each change is in (DEFAULT: diff.showfunc)
1779 --reverse
1781 produce a diff that undoes the changes
1782 -w, --ignore-all-space
1784 ignore white space when comparing lines
1785 -b, --ignore-space-change
1787 ignore changes in the amount of white space
1788 -B, --ignore-blank-lines
1790 ignore changes whose lines are all blank
1791 -Z, --ignore-space-at-eol
1793 ignore changes in whitespace at EOL
1794 -U,--unified <NUM>
1796 number of lines of context to show
1797 --stat output diffstat-style summary of changes
1799 --root <DIR>
1801 produce diffs relative to subdirectory
1802 -I,--include <PATTERN[+]>
1804 include names matching the given patterns
1805 -X,--exclude <PATTERN[+]>
1807 exclude names matching the given patterns
1808 -S, --subrepos
1810 recurse into subrepositories
1811 [+] marked option can be specified multiple times
1813 grep
1815 search for a pattern in specified files:
1816 hg grep [--diff] [OPTION]... PATTERN [FILE]...
1818 Search the working directory or revision history for a regular expres‐
1820 sion in the specified files for the entire repository.
1821 By default, grep searches the repository files in the working directory
1823 and prints the files where it finds a match. To specify historical
1824 revisions instead of the working directory, use the --rev flag.
1825 To search instead historical revision differences that contains a
1827 change in match status ("-" for a match that becomes a non-match, or
1828 "+" for a non-match that becomes a match), use the --diff flag.
1829 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1831 If no FILEs are specified and the --rev flag isn't supplied, all files
1833 in the working directory are searched. When using the --rev flag and
1834 specifying FILEs, use the --follow argument to also follow the speci‐
1835 fied FILEs across renames and copies.
1836 Template:
1838 The following keywords are supported in addition to the common template
1840 keywords and functions. See also hg help templates.
1841 change String. Character denoting insertion + or removal -. Available
1843 if --diff is specified.
1844 lineno Integer. Line number of the match.
1846 path String. Repository-absolute path of the file.
1848 texts List of text chunks.
1850 And each entry of {texts} provides the following sub-keywords.
1852 matched
1854 Boolean. True if the chunk matches the specified pattern.
1855 text String. Chunk content.
1857 See hg help templates.operators for the list expansion syntax.
1859 Returns 0 if a match is found, 1 otherwise.
1861 Options:
1863 -0, --print0
1865 end fields with NUL
1866 --all print all revisions that match (DEPRECATED)
1868 --diff search revision differences for when the pattern was added or
1870 removed
1871 -a, --text
1873 treat all files as text
1874 -f, --follow
1876 follow changeset history, or file history across copies and
1877 renames
1878 -i, --ignore-case
1880 ignore case when matching
1881 -l, --files-with-matches
1883 print only filenames and revisions that match
1884 -n, --line-number
1886 print matching line numbers
1887 -r,--rev <REV[+]>
1889 search files changed within revision range
1890 --all-files
1892 include all files in the changeset while grepping (DEPRECATED)
1893 -u, --user
1895 list the author (long with -v)
1896 -d, --date
1898 list the date (short with -q)
1899 -T,--template <TEMPLATE>
1901 display with template
1902 -I,--include <PATTERN[+]>
1904 include names matching the given patterns
1905 -X,--exclude <PATTERN[+]>
1907 exclude names matching the given patterns
1908 [+] marked option can be specified multiple times
1910 Change navigation
1912 bisect
1913 subdivision search of changesets:
1914 hg bisect [-gbsr] [-U] [-c CMD] [REV]
1916 This command helps to find changesets which introduce problems. To use,
1918 mark the earliest changeset you know exhibits the problem as bad, then
1919 mark the latest changeset which is free from the problem as good.
1920 Bisect will update your working directory to a revision for testing
1921 (unless the -U/--noupdate option is specified). Once you have performed
1922 tests, mark the working directory as good or bad, and bisect will
1923 either update to another candidate changeset or announce that it has
1924 found the bad revision.
1925 As a shortcut, you can also use the revision argument to mark a revi‐
1927 sion as good or bad without checking it out first.
1928 If you supply a command, it will be used for automatic bisection. The
1930 environment variable HG_NODE will contain the ID of the changeset being
1931 tested. The exit status of the command will be used to mark revisions
1932 as good or bad: status 0 means good, 125 means to skip the revision,
1933 127 (command not found) will abort the bisection, and any other
1934 non-zero exit status means the revision is bad.
1935 Some examples:
1937 · start a bisection with known bad revision 34, and good revision 12:
1939 hg bisect --bad 34
1941 hg bisect --good 12
1942 · advance the current bisection by marking current revision as good or
1944 bad:
1945 hg bisect --good
1947 hg bisect --bad
1948 · mark the current revision, or a known revision, to be skipped (e.g.
1950 if that revision is not usable because of another issue):
1951 hg bisect --skip
1953 hg bisect --skip 23
1954 · skip all revisions that do not touch directories foo or bar:
1956 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
1958 · forget the current bisection:
1960 hg bisect --reset
1962 · use 'make && make tests' to automatically find the first broken revi‐
1964 sion:
1965 hg bisect --reset
1967 hg bisect --bad 34
1968 hg bisect --good 12
1969 hg bisect --command "make && make tests"
1970 · see all changesets whose states are already known in the current
1972 bisection:
1973 hg log -r "bisect(pruned)"
1975 · see the changeset currently being bisected (especially useful if run‐
1977 ning with -U/--noupdate):
1978 hg log -r "bisect(current)"
1980 · see all changesets that took part in the current bisection:
1982 hg log -r "bisect(range)"
1984 · you can even get a nice graph:
1986 hg log --graph -r "bisect(range)"
1988 See hg help revisions.bisect for more about the bisect() predicate.
1990 Returns 0 on success.
1992 Options:
1994 -r, --reset
1996 reset bisect state
1997 -g, --good
1999 mark changeset good
2000 -b, --bad
2002 mark changeset bad
2003 -s, --skip
2005 skip testing changeset
2006 -e, --extend
2008 extend the bisect range
2009 -c,--command <CMD>
2011 use command to check changeset state
2012 -U, --noupdate
2014 do not update to target
2015 heads
2017 show branch heads:
2018 hg heads [-ct] [-r STARTREV] [REV]...
2020 With no arguments, show all open branch heads in the repository.
2022 Branch heads are changesets that have no descendants on the same
2023 branch. They are where development generally takes place and are the
2024 usual targets for update and merge operations.
2025 If one or more REVs are given, only open branch heads on the branches
2027 associated with the specified changesets are shown. This means that you
2028 can use hg heads . to see the heads on the currently checked-out
2029 branch.
2030 If -c/--closed is specified, also show branch heads marked closed (see
2032 hg commit --close-branch).
2033 If STARTREV is specified, only those heads that are descendants of
2035 STARTREV will be displayed.
2036 If -t/--topo is specified, named branch mechanics will be ignored and
2038 only topological heads (changesets with no children) will be shown.
2039 Returns 0 if matching heads are found, 1 if not.
2041 Options:
2043 -r,--rev <STARTREV>
2045 show only heads which are descendants of STARTREV
2046 -t, --topo
2048 show topological heads only
2049 -a, --active
2051 show active branchheads only (DEPRECATED)
2052 -c, --closed
2054 show normal and closed branch heads
2055 --style <STYLE>
2057 display using template map file (DEPRECATED)
2058 -T,--template <TEMPLATE>
2060 display with template
2061 identify
2063 identify the working directory or specified revision:
2064 hg identify [-nibtB] [-r REV] [SOURCE]
2066 Print a summary identifying the repository state at REV using one or
2068 two parent hash identifiers, followed by a "+" if the working directory
2069 has uncommitted changes, the branch name (if not default), a list of
2070 tags, and a list of bookmarks.
2071 When REV is not given, print a summary of the current state of the
2073 repository including the working directory. Specify -r. to get informa‐
2074 tion of the working directory parent without scanning uncommitted
2075 changes.
2076 Specifying a path to a repository root or Mercurial bundle will cause
2078 lookup to operate on that repository/bundle.
2079 Template:
2081 The following keywords are supported in addition to the common template
2083 keywords and functions. See also hg help templates.
2084 dirty String. Character + denoting if the working directory has uncom‐
2086 mitted changes.
2087 id String. One or two nodes, optionally followed by +.
2089 parents
2091 List of strings. Parent nodes of the changeset.
2092 Examples:
2094 · generate a build identifier for the working directory:
2096 hg id --id > build-id.dat
2098 · find the revision corresponding to a tag:
2100 hg id -n -r 1.3
2102 · check the most recent revision of a remote repository:
2104 hg id -r tip https://www.mercurial-scm.org/repo/hg/
2106 See hg log for generating more information about specific revisions,
2108 including full hash identifiers.
2109 Returns 0 if successful.
2111 Options:
2113 -r,--rev <REV>
2115 identify the specified revision
2116 -n, --num
2118 show local revision number
2119 -i, --id
2121 show global revision id
2122 -b, --branch
2124 show branch
2125 -t, --tags
2127 show tags
2128 -B, --bookmarks
2130 show bookmarks
2131 -e,--ssh <CMD>
2133 specify ssh command to use
2134 --remotecmd <CMD>
2136 specify hg command to run on the remote side
2137 --insecure
2139 do not verify server certificate (ignoring web.cacerts config)
2140 -T,--template <TEMPLATE>
2142 display with template
2143 aliases: id
2145 log
2147 show revision history of entire repository or files:
2148 hg log [OPTION]... [FILE]
2150 Print the revision history of the specified files or the entire
2152 project.
2153 If no revision range is specified, the default is tip:0 unless --follow
2155 is set, in which case the working directory parent is used as the
2156 starting revision.
2157 File history is shown without following rename or copy history of
2159 files. Use -f/--follow with a filename to follow history across renames
2160 and copies. --follow without a filename will only show ancestors of the
2161 starting revision.
2162 By default this command prints revision number and changeset id, tags,
2164 non-trivial parents, user, date and time, and a summary for each com‐
2165 mit. When the -v/--verbose switch is used, the list of changed files
2166 and full commit message are shown.
2167 With --graph the revisions are shown as an ASCII art DAG with the most
2169 recent changeset at the top. 'o' is a changeset, '@' is a working
2170 directory parent, '%' is a changeset involved in an unresolved merge
2171 conflict, '_' closes a branch, 'x' is obsolete, '*' is unstable, and
2172 '+' represents a fork where the changeset from the lines below is a
2173 parent of the 'o' merge on the same line. Paths in the DAG are repre‐
2174 sented with '|', '/' and so forth. ':' in place of a '|' indicates one
2175 or more revisions in a path are omitted.
2176 Use -L/--line-range FILE,M:N options to follow the history of lines
2178 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2179 fied line range will be shown. This option requires --follow; it can be
2180 specified multiple times. Currently, this option is not compatible with
2181 --graph. This option is experimental.
2182 Note hg log --patch may generate unexpected diff output for merge
2184 changesets, as it will only compare the merge changeset against
2185 its first parent. Also, only files different from BOTH parents
2186 will appear in files:.
2187 Note For performance reasons, hg log FILE may omit duplicate changes
2189 made on branches and will not show removals or mode changes. To
2190 see all such changes, use the --removed switch.
2191 Note The history resulting from -L/--line-range options depends on
2193 diff options; for instance if white-spaces are ignored, respec‐
2194 tive changes with only white-spaces in specified line range will
2195 not be listed.
2196 Some examples:
2198 · changesets with full descriptions and file lists:
2200 hg log -v
2202 · changesets ancestral to the working directory:
2204 hg log -f
2206 · last 10 commits on the current branch:
2208 hg log -l 10 -b .
2210 · changesets showing all modifications of a file, including removals:
2212 hg log --removed file.c
2214 · all changesets that touch a directory, with diffs, excluding merges:
2216 hg log -Mp lib/
2218 · all revision numbers that match a keyword:
2220 hg log -k bug --template "{rev}\n"
2222 · the full hash identifier of the working directory parent:
2224 hg log -r . --template "{node}\n"
2226 · list available log templates:
2228 hg log -T list
2230 · check if a given changeset is included in a tagged release:
2232 hg log -r "a21ccf and ancestor(1.9)"
2234 · find all changesets by some user in a date range:
2236 hg log -k alice -d "may 2008 to jul 2008"
2238 · summary of all changesets after the last tag:
2240 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2242 · changesets touching lines 13 to 23 for file.c:
2244 hg log -L file.c,13:23
2246 · changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2248 main.c with patch:
2249 hg log -L file.c,13:23 -L main.c,2:6 -p
2251 See hg help dates for a list of formats valid for -d/--date.
2253 See hg help revisions for more about specifying and ordering revisions.
2255 See hg help templates for more about pre-packaged styles and specifying
2257 custom templates. The default template used by the log command can be
2258 customized via the ui.logtemplate configuration setting.
2259 Returns 0 on success.
2261 Options:
2263 -f, --follow
2265 follow changeset history, or file history across copies and
2266 renames
2267 --follow-first
2269 only follow the first parent of merge changesets (DEPRECATED)
2270 -d,--date <DATE>
2272 show revisions matching date spec
2273 -C, --copies
2275 show copied files
2276 -k,--keyword <TEXT[+]>
2278 do case-insensitive search for a given text
2279 -r,--rev <REV[+]>
2281 show the specified revision or revset
2282 -L,--line-range <FILE,RANGE[+]>
2284 follow line range of specified file (EXPERIMENTAL)
2285 --removed
2287 include revisions where files were removed
2288 -m, --only-merges
2290 show only merges (DEPRECATED) (use -r "merge()" instead)
2291 -u,--user <USER[+]>
2293 revisions committed by user
2294 --only-branch <BRANCH[+]>
2296 show only changesets within the given named branch (DEPRECATED)
2297 -b,--branch <BRANCH[+]>
2299 show changesets within the given named branch
2300 -P,--prune <REV[+]>
2302 do not display revision or any of its ancestors
2303 -p, --patch
2305 show patch
2306 -g, --git
2308 use git extended diff format
2309 -l,--limit <NUM>
2311 limit number of changes displayed
2312 -M, --no-merges
2314 do not show merges
2315 --stat output diffstat-style summary of changes
2317 -G, --graph
2319 show the revision DAG
2320 --style <STYLE>
2322 display using template map file (DEPRECATED)
2323 -T,--template <TEMPLATE>
2325 display with template
2326 -I,--include <PATTERN[+]>
2328 include names matching the given patterns
2329 -X,--exclude <PATTERN[+]>
2331 exclude names matching the given patterns
2332 [+] marked option can be specified multiple times
2334 aliases: history
2336 parents
2338 show the parents of the working directory or revision (DEPRECATED):
2339 hg parents [-r REV] [FILE]
2341 Print the working directory's parent revisions. If a revision is given
2343 via -r/--rev, the parent of that revision will be printed. If a file
2344 argument is given, the revision in which the file was last changed
2345 (before the working directory revision or the argument to --rev if
2346 given) is printed.
2347 This command is equivalent to:
2349 hg log -r "p1()+p2()" or
2351 hg log -r "p1(REV)+p2(REV)" or
2352 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2353 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2354 See hg summary and hg help revsets for related information.
2356 Returns 0 on success.
2358 Options:
2360 -r,--rev <REV>
2362 show parents of the specified revision
2363 --style <STYLE>
2365 display using template map file (DEPRECATED)
2366 -T,--template <TEMPLATE>
2368 display with template
2369 tip
2371 show the tip revision (DEPRECATED):
2372 hg tip [-p] [-g]
2374 The tip revision (usually just called the tip) is the changeset most
2376 recently added to the repository (and therefore the most recently
2377 changed head).
2378 If you have just made a commit, that commit will be the tip. If you
2380 have just pulled changes from another repository, the tip of that
2381 repository becomes the current tip. The "tip" tag is special and cannot
2382 be renamed or assigned to a different changeset.
2383 This command is deprecated, please use hg heads instead.
2385 Returns 0 on success.
2387 Options:
2389 -p, --patch
2391 show patch
2392 -g, --git
2394 use git extended diff format
2395 --style <STYLE>
2397 display using template map file (DEPRECATED)
2398 -T,--template <TEMPLATE>
2400 display with template
2401 Working directory management
2403 add
2404 add the specified files on the next commit:
2405 hg add [OPTION]... [FILE]...
2407 Schedule files to be version controlled and added to the repository.
2409 The files will be added to the repository at the next commit. To undo
2411 an add before that, see hg forget.
2412 If no names are given, add all files to the repository (except files
2414 matching .hgignore).
2415 Examples:
2417 · New (unknown) files are added automatically by hg add:
2419 $ ls
2421 foo.c
2422 $ hg status
2423 ? foo.c
2424 $ hg add
2425 adding foo.c
2426 $ hg status
2427 A foo.c
2428 · Specific files to be added can be specified:
2430 $ ls
2432 bar.c foo.c
2433 $ hg status
2434 ? bar.c
2435 ? foo.c
2436 $ hg add bar.c
2437 $ hg status
2438 A bar.c
2439 ? foo.c
2440 Returns 0 if all files are successfully added.
2442 Options:
2444 -I,--include <PATTERN[+]>
2446 include names matching the given patterns
2447 -X,--exclude <PATTERN[+]>
2449 exclude names matching the given patterns
2450 -S, --subrepos
2452 recurse into subrepositories
2453 -n, --dry-run
2455 do not perform actions, just print output
2456 [+] marked option can be specified multiple times
2458 addremove
2460 add all new files, delete all missing files:
2461 hg addremove [OPTION]... [FILE]...
2463 Add all new files and remove all missing files from the repository.
2465 Unless names are given, new files are ignored if they match any of the
2467 patterns in .hgignore. As with add, these changes take effect at the
2468 next commit.
2469 Use the -s/--similarity option to detect renamed files. This option
2471 takes a percentage between 0 (disabled) and 100 (files must be identi‐
2472 cal) as its parameter. With a parameter greater than 0, this compares
2473 every removed file with every added file and records those similar
2474 enough as renames. Detecting renamed files this way can be expensive.
2475 After using this option, hg status -C can be used to check which files
2476 were identified as moved or renamed. If not specified, -s/--similarity
2477 defaults to 100 and only renames of identical files are detected.
2478 Examples:
2480 · A number of files (bar.c and foo.c) are new, while foobar.c has
2482 been removed (without using hg remove) from the repository:
2483 $ ls
2485 bar.c foo.c
2486 $ hg status
2487 ! foobar.c
2488 ? bar.c
2489 ? foo.c
2490 $ hg addremove
2491 adding bar.c
2492 adding foo.c
2493 removing foobar.c
2494 $ hg status
2495 A bar.c
2496 A foo.c
2497 R foobar.c
2498 · A file foobar.c was moved to foo.c without using hg rename.
2500 Afterwards, it was edited slightly:
2501 $ ls
2503 foo.c
2504 $ hg status
2505 ! foobar.c
2506 ? foo.c
2507 $ hg addremove --similarity 90
2508 removing foobar.c
2509 adding foo.c
2510 recording removal of foobar.c as rename to foo.c (94% similar)
2511 $ hg status -C
2512 A foo.c
2513 foobar.c
2514 R foobar.c
2515 Returns 0 if all files are successfully added.
2517 Options:
2519 -s,--similarity <SIMILARITY>
2521 guess renamed files by similarity (0<=s<=100)
2522 -S, --subrepos
2524 recurse into subrepositories
2525 -I,--include <PATTERN[+]>
2527 include names matching the given patterns
2528 -X,--exclude <PATTERN[+]>
2530 exclude names matching the given patterns
2531 -n, --dry-run
2533 do not perform actions, just print output
2534 [+] marked option can be specified multiple times
2536 files
2538 list tracked files:
2539 hg files [OPTION]... [FILE]...
2541 Print files under Mercurial control in the working directory or speci‐
2543 fied revision for given files (excluding removed files). Files can be
2544 specified as filenames or filesets.
2545 If no files are given to match, this command prints the names of all
2547 files under Mercurial control.
2548 Template:
2550 The following keywords are supported in addition to the common template
2552 keywords and functions. See also hg help templates.
2553 flags String. Character denoting file's symlink and executable bits.
2555 path String. Repository-absolute path of the file.
2557 size Integer. Size of the file in bytes.
2559 Examples:
2561 · list all files under the current directory:
2563 hg files .
2565 · shows sizes and flags for current revision:
2567 hg files -vr .
2569 · list all files named README:
2571 hg files -I "**/README"
2573 · list all binary files:
2575 hg files "set:binary()"
2577 · find files containing a regular expression:
2579 hg files "set:grep('bob')"
2581 · search tracked file contents with xargs and grep:
2583 hg files -0 | xargs -0 grep foo
2585 See hg help patterns and hg help filesets for more information on spec‐
2587 ifying file patterns.
2588 Returns 0 if a match is found, 1 otherwise.
2590 Options:
2592 -r,--rev <REV>
2594 search the repository as it is in REV
2595 -0, --print0
2597 end filenames with NUL, for use with xargs
2598 -I,--include <PATTERN[+]>
2600 include names matching the given patterns
2601 -X,--exclude <PATTERN[+]>
2603 exclude names matching the given patterns
2604 -T,--template <TEMPLATE>
2606 display with template
2607 -S, --subrepos
2609 recurse into subrepositories
2610 [+] marked option can be specified multiple times
2612 forget
2614 forget the specified files on the next commit:
2615 hg forget [OPTION]... FILE...
2617 Mark the specified files so they will no longer be tracked after the
2619 next commit.
2620 This only removes files from the current branch, not from the entire
2622 project history, and it does not delete them from the working direc‐
2623 tory.
2624 To delete the file from the working directory, see hg remove.
2626 To undo a forget before the next commit, see hg add.
2628 Examples:
2630 · forget newly-added binary files:
2632 hg forget "set:added() and binary()"
2634 · forget files that would be excluded by .hgignore:
2636 hg forget "set:hgignore()"
2638 Returns 0 on success.
2640 Options:
2642 -i, --interactive
2644 use interactive mode
2645 -I,--include <PATTERN[+]>
2647 include names matching the given patterns
2648 -X,--exclude <PATTERN[+]>
2650 exclude names matching the given patterns
2651 -n, --dry-run
2653 do not perform actions, just print output
2654 [+] marked option can be specified multiple times
2656 locate
2658 locate files matching specific patterns (DEPRECATED):
2659 hg locate [OPTION]... [PATTERN]...
2661 Print files under Mercurial control in the working directory whose
2663 names match the given patterns.
2664 By default, this command searches all directories in the working direc‐
2666 tory. To search just the current directory and its subdirectories, use
2667 "--include .".
2668 If no patterns are given to match, this command prints the names of all
2670 files under Mercurial control in the working directory.
2671 If you want to feed the output of this command into the "xargs" com‐
2673 mand, use the -0 option to both this command and "xargs". This will
2674 avoid the problem of "xargs" treating single filenames that contain
2675 whitespace as multiple filenames.
2676 See hg help files for a more versatile command.
2678 Returns 0 if a match is found, 1 otherwise.
2680 Options:
2682 -r,--rev <REV>
2684 search the repository as it is in REV
2685 -0, --print0
2687 end filenames with NUL, for use with xargs
2688 -f, --fullpath
2690 print complete paths from the filesystem root
2691 -I,--include <PATTERN[+]>
2693 include names matching the given patterns
2694 -X,--exclude <PATTERN[+]>
2696 exclude names matching the given patterns
2697 [+] marked option can be specified multiple times
2699 remove
2701 remove the specified files on the next commit:
2702 hg remove [OPTION]... FILE...
2704 Schedule the indicated files for removal from the current branch.
2706 This command schedules the files to be removed at the next commit. To
2708 undo a remove before that, see hg revert. To undo added files, see hg
2709 forget.
2710 -A/--after can be used to remove only files that have already been
2712 deleted, -f/--force can be used to force deletion, and -Af can be used
2713 to remove files from the next revision without deleting them from the
2714 working directory.
2715 The following table details the behavior of remove for different file
2717 states (columns) and option combinations (rows). The file states are
2718 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2719 status). The actions are Warn, Remove (from branch) and Delete (from
2720 disk):
2721 ┌──────────┬───┬────┬────┬───┐
2723 │opt/state │ A │ C │ M │ ! │
2724 ├──────────┼───┼────┼────┼───┤
2725 │none │ W │ RD │ W │ R │
2726 ├──────────┼───┼────┼────┼───┤
2727 │-f │ R │ RD │ RD │ R │
2728 ├──────────┼───┼────┼────┼───┤
2729 │-A │ W │ W │ W │ R │
2730 ├──────────┼───┼────┼────┼───┤
2731 │-Af │ R │ R │ R │ R │
2732 └──────────┴───┴────┴────┴───┘
2733 Note hg remove never deletes files in Added [A] state from the work‐
2735 ing directory, not even if --force is specified.
2736 Returns 0 on success, 1 if any warnings encountered.
2738 Options:
2740 -A, --after
2742 record delete for missing files
2743 -f, --force
2745 forget added files, delete modified files
2746 -S, --subrepos
2748 recurse into subrepositories
2749 -I,--include <PATTERN[+]>
2751 include names matching the given patterns
2752 -X,--exclude <PATTERN[+]>
2754 exclude names matching the given patterns
2755 -n, --dry-run
2757 do not perform actions, just print output
2758 [+] marked option can be specified multiple times
2760 aliases: rm
2762 rename
2764 rename files; equivalent of copy + remove:
2765 hg rename [OPTION]... SOURCE... DEST
2767 Mark dest as copies of sources; mark sources for deletion. If dest is a
2769 directory, copies are put in that directory. If dest is a file, there
2770 can only be one source.
2771 By default, this command copies the contents of files as they exist in
2773 the working directory. If invoked with -A/--after, the operation is
2774 recorded, but no copying is performed.
2775 This command takes effect at the next commit. To undo a rename before
2777 that, see hg revert.
2778 Returns 0 on success, 1 if errors are encountered.
2780 Options:
2782 -A, --after
2784 record a rename that has already occurred
2785 -f, --force
2787 forcibly move over an existing managed file
2788 -I,--include <PATTERN[+]>
2790 include names matching the given patterns
2791 -X,--exclude <PATTERN[+]>
2793 exclude names matching the given patterns
2794 -n, --dry-run
2796 do not perform actions, just print output
2797 [+] marked option can be specified multiple times
2799 aliases: move mv
2801 resolve
2803 redo merges or set/view the merge status of files:
2804 hg resolve [OPTION]... [FILE]...
2806 Merges with unresolved conflicts are often the result of non-interac‐
2808 tive merging using the internal:merge configuration setting, or a com‐
2809 mand-line merge tool like diff3. The resolve command is used to manage
2810 the files involved in a merge, after hg merge has been run, and before
2811 hg commit is run (i.e. the working directory must have two parents).
2812 See hg help merge-tools for information on configuring merge tools.
2813 The resolve command can be used in the following ways:
2815 · hg resolve [--re-merge] [--tool TOOL] FILE...: attempt to re-merge
2817 the specified files, discarding any previous merge attempts. Re-merg‐
2818 ing is not performed for files already marked as resolved. Use
2819 --all/-a to select all unresolved files. --tool can be used to spec‐
2820 ify the merge tool used for the given files. It overrides the HGMERGE
2821 environment variable and your configuration files. Previous file
2822 contents are saved with a .orig suffix.
2823 · hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
2825 having manually fixed-up the files). The default is to mark all unre‐
2826 solved files.
2827 · hg resolve -u [FILE]...: mark a file as unresolved. The default is to
2829 mark all resolved files.
2830 · hg resolve -l: list files which had or still have conflicts. In the
2832 printed list, U = unresolved and R = resolved. You can use set:unre‐
2833 solved() or set:resolved() to filter the list. See hg help filesets
2834 for details.
2835 Note Mercurial will not let you commit files with unresolved merge
2837 conflicts. You must use hg resolve -m ... before you can commit
2838 after a conflicting merge.
2839 Template:
2841 The following keywords are supported in addition to the common template
2843 keywords and functions. See also hg help templates.
2844 mergestatus
2846 String. Character denoting merge conflicts, U or R.
2847 path String. Repository-absolute path of the file.
2849 Returns 0 on success, 1 if any files fail a resolve attempt.
2851 Options:
2853 -a, --all
2855 select all unresolved files
2856 -l, --list
2858 list state of files needing merge
2859 -m, --mark
2861 mark files as resolved
2862 -u, --unmark
2864 mark files as unresolved
2865 -n, --no-status
2867 hide status prefix
2868 --re-merge
2870 re-merge files
2871 -t,--tool <TOOL>
2873 specify merge tool
2874 -I,--include <PATTERN[+]>
2876 include names matching the given patterns
2877 -X,--exclude <PATTERN[+]>
2879 exclude names matching the given patterns
2880 -T,--template <TEMPLATE>
2882 display with template
2883 [+] marked option can be specified multiple times
2885 revert
2887 restore files to their checkout state:
2888 hg revert [OPTION]... [-r REV] [NAME]...
2890 Note To check out earlier revisions, you should use hg update REV.
2892 To cancel an uncommitted merge (and lose your changes), use hg
2893 merge --abort.
2894 With no revision specified, revert the specified files or directories
2896 to the contents they had in the parent of the working directory. This
2897 restores the contents of files to an unmodified state and unschedules
2898 adds, removes, copies, and renames. If the working directory has two
2899 parents, you must explicitly specify a revision.
2900 Using the -r/--rev or -d/--date options, revert the given files or
2902 directories to their states as of a specific revision. Because revert
2903 does not change the working directory parents, this will cause these
2904 files to appear modified. This can be helpful to "back out" some or all
2905 of an earlier change. See hg backout for a related method.
2906 Modified files are saved with a .orig suffix before reverting. To dis‐
2908 able these backups, use --no-backup. It is possible to store the backup
2909 files in a custom directory relative to the root of the repository by
2910 setting the ui.origbackuppath configuration option.
2911 See hg help dates for a list of formats valid for -d/--date.
2913 See hg help backout for a way to reverse the effect of an earlier
2915 changeset.
2916 Returns 0 on success.
2918 Options:
2920 -a, --all
2922 revert all changes when no arguments given
2923 -d,--date <DATE>
2925 tipmost revision matching date
2926 -r,--rev <REV>
2928 revert to the specified revision
2929 -C, --no-backup
2931 do not save backup copies of files
2932 -i, --interactive
2934 interactively select the changes
2935 -I,--include <PATTERN[+]>
2937 include names matching the given patterns
2938 -X,--exclude <PATTERN[+]>
2940 exclude names matching the given patterns
2941 -n, --dry-run
2943 do not perform actions, just print output
2944 [+] marked option can be specified multiple times
2946 root
2948 print the root (top) of the current working directory:
2949 hg root
2951 Print the root directory of the current repository.
2953 Template:
2955 The following keywords are supported in addition to the common template
2957 keywords and functions. See also hg help templates.
2958 hgpath String. Path to the .hg directory.
2960 storepath
2962 String. Path to the directory holding versioned data.
2963 Returns 0 on success.
2965 Options:
2967 -T,--template <TEMPLATE>
2969 display with template
2970 shelve
2972 save and set aside changes from the working directory:
2973 hg shelve [OPTION]... [FILE]...
2975 Shelving takes files that "hg status" reports as not clean, saves the
2977 modifications to a bundle (a shelved change), and reverts the files so
2978 that their state in the working directory becomes clean.
2979 To restore these changes to the working directory, using "hg unshelve";
2981 this will work even if you switch to a different commit.
2982 When no files are specified, "hg shelve" saves all not-clean files. If
2984 specific files or directories are named, only changes to those files
2985 are shelved.
2986 In bare shelve (when no files are specified, without interactive,
2988 include and exclude option), shelving remembers information if the
2989 working directory was on newly created branch, in other words working
2990 directory was on different branch than its first parent. In this situa‐
2991 tion unshelving restores branch information to the working directory.
2992 Each shelved change has a name that makes it easier to find later. The
2994 name of a shelved change defaults to being based on the active book‐
2995 mark, or if there is no active bookmark, the current named branch. To
2996 specify a different name, use --name.
2997 To see a list of existing shelved changes, use the --list option. For
2999 each shelved change, this will print its name, age, and description;
3000 use --patch or --stat for more details.
3001 To delete specific shelved changes, use --delete. To delete all shelved
3003 changes, use --cleanup.
3004 Options:
3006 -A, --addremove
3008 mark new/missing files as added/removed before shelving
3009 -u, --unknown
3011 store unknown files in the shelve
3012 --cleanup
3014 delete all shelved changes
3015 --date <DATE>
3017 shelve with the specified commit date
3018 -d, --delete
3020 delete the named shelved change(s)
3021 -e, --edit
3023 invoke editor on commit messages
3024 -k, --keep
3026 shelve, but keep changes in the working directory
3027 -l, --list
3029 list current shelves
3030 -m,--message <TEXT>
3032 use text as shelve message
3033 -n,--name <NAME>
3035 use the given name for the shelved commit
3036 -p, --patch
3038 output patches for changes (provide the names of the shelved
3039 changes as positional arguments)
3040 -i, --interactive
3042 interactive mode
3043 --stat output diffstat-style summary of changes (provide the names of
3045 the shelved changes as positional arguments)
3046 -I,--include <PATTERN[+]>
3048 include names matching the given patterns
3049 -X,--exclude <PATTERN[+]>
3051 exclude names matching the given patterns
3052 [+] marked option can be specified multiple times
3054 status
3056 show changed files in the working directory:
3057 hg status [OPTION]... [FILE]...
3059 Show status of files in the repository. If names are given, only files
3061 that match are shown. Files that are clean or ignored or the source of
3062 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3063 -C/--copies or -A/--all are given. Unless options described with "show
3064 only ..." are given, the options -mardu are used.
3065 Option -q/--quiet hides untracked (unknown and ignored) files unless
3067 explicitly requested with -u/--unknown or -i/--ignored.
3068 Note hg status may appear to disagree with diff if permissions have
3070 changed or a merge has occurred. The standard diff format does
3071 not report permission changes and diff only reports changes rel‐
3072 ative to one merge parent.
3073 If one revision is given, it is used as the base revision. If two
3075 revisions are given, the differences between them are shown. The
3076 --change option can also be used as a shortcut to list the changed
3077 files of a revision from its first parent.
3078 The codes used to show the status of files are:
3080 M = modified
3082 A = added
3083 R = removed
3084 C = clean
3085 ! = missing (deleted by non-hg command, but still tracked)
3086 ? = not tracked
3087 I = ignored
3088 = origin of the previous file (with --copies)
3089 The -t/--terse option abbreviates the output by showing only the direc‐
3091 tory name if all the files in it share the same status. The option
3092 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3093 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3094 'unknown', 'i' for 'ignored' and 'c' for clean.
3095 It abbreviates only those statuses which are passed. Note that clean
3097 and ignored files are not displayed with '--terse ic' unless the
3098 -c/--clean and -i/--ignored options are also used.
3099 The -v/--verbose option shows information when the repository is in an
3101 unfinished merge, shelve, rebase state etc. You can have this behavior
3102 turned on by default by enabling the commands.status.verbose option.
3103 You can skip displaying some of these states by setting commands.sta‐
3105 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3106 'merge', 'rebase', or 'unshelve'.
3107 Template:
3109 The following keywords are supported in addition to the common template
3111 keywords and functions. See also hg help templates.
3112 path String. Repository-absolute path of the file.
3114 source String. Repository-absolute path of the file originated from.
3116 Available if --copies is specified.
3117 status String. Character denoting file's status.
3119 Examples:
3121 · show changes in the working directory relative to a changeset:
3123 hg status --rev 9353
3125 · show changes in the working directory relative to the current direc‐
3127 tory (see hg help patterns for more information):
3128 hg status re:
3130 · show all changes including copies in an existing changeset:
3132 hg status --copies --change 9353
3134 · get a NUL separated list of added files, suitable for xargs:
3136 hg status -an0
3138 · show more information about the repository status, abbreviating
3140 added, removed, modified, deleted, and untracked paths:
3141 hg status -v -t mardu
3143 Returns 0 on success.
3145 Options:
3147 -A, --all
3149 show status of all files
3150 -m, --modified
3152 show only modified files
3153 -a, --added
3155 show only added files
3156 -r, --removed
3158 show only removed files
3159 -d, --deleted
3161 show only deleted (but tracked) files
3162 -c, --clean
3164 show only files without changes
3165 -u, --unknown
3167 show only unknown (not tracked) files
3168 -i, --ignored
3170 show only ignored files
3171 -n, --no-status
3173 hide status prefix
3174 -t,--terse <VALUE>
3176 show the terse output (EXPERIMENTAL) (default: nothing)
3177 -C, --copies
3179 show source of copied files (DEFAULT: ui.statuscopies)
3180 -0, --print0
3182 end filenames with NUL, for use with xargs
3183 --rev <REV[+]>
3185 show difference from revision
3186 --change <REV>
3188 list the changed files of a revision
3189 -I,--include <PATTERN[+]>
3191 include names matching the given patterns
3192 -X,--exclude <PATTERN[+]>
3194 exclude names matching the given patterns
3195 -S, --subrepos
3197 recurse into subrepositories
3198 -T,--template <TEMPLATE>
3200 display with template
3201 [+] marked option can be specified multiple times
3203 aliases: st
3205 summary
3207 summarize working directory state:
3208 hg summary [--remote]
3210 This generates a brief summary of the working directory state, includ‐
3212 ing parents, branch, commit status, phase and available updates.
3213 With the --remote option, this will check the default paths for incom‐
3215 ing and outgoing changes. This can be time-consuming.
3216 Returns 0 on success.
3218 Options:
3220 --remote
3222 check for push and pull
3223 aliases: sum
3225 unshelve
3227 restore a shelved change to the working directory:
3228 hg unshelve [OPTION]... [[-n] SHELVED]
3230 This command accepts an optional name of a shelved change to restore.
3232 If none is given, the most recent shelved change is used.
3233 If a shelved change is applied successfully, the bundle that contains
3235 the shelved changes is moved to a backup location (.hg/shelve-backup).
3236 Since you can restore a shelved change on top of an arbitrary commit,
3238 it is possible that unshelving will result in a conflict between your
3239 changes and the commits you are unshelving onto. If this occurs, you
3240 must resolve the conflict, then use --continue to complete the unshelve
3241 operation. (The bundle will not be moved until you successfully com‐
3242 plete the unshelve.)
3243 (Alternatively, you can use --abort to abandon an unshelve that causes
3245 a conflict. This reverts the unshelved changes, and leaves the bundle
3246 in place.)
3247 If bare shelved change (without interactive, include and exclude
3249 option) was done on newly created branch it would restore branch infor‐
3250 mation to the working directory.
3251 After a successful unshelve, the shelved changes are stored in a backup
3253 directory. Only the N most recent backups are kept. N defaults to 10
3254 but can be overridden using the shelve.maxbackups configuration option.
3255 Timestamp in seconds is used to decide order of backups. More than
3257 maxbackups backups are kept, if same timestamp prevents from deciding
3258 exact order of them, for safety.
3259 Selected changes can be unshelved with --interactive flag. The working
3261 directory is updated with the selected changes, and only the unselected
3262 changes remain shelved. Note: The whole shelve is applied to working
3263 directory first before running interactively. So, this will bring up
3264 all the conflicts between working directory and the shelve, irrespec‐
3265 tive of which changes will be unshelved.
3266 Options:
3268 -a, --abort
3270 abort an incomplete unshelve operation
3271 -c, --continue
3273 continue an incomplete unshelve operation
3274 -i, --interactive
3276 use interactive mode (EXPERIMENTAL)
3277 -k, --keep
3279 keep shelve after unshelving
3280 -n,--name <NAME>
3282 restore shelved change with given name
3283 -t,--tool <VALUE>
3285 specify merge tool
3286 --date <DATE>
3288 set date for temporary commits (DEPRECATED)
3289 update
3291 update working directory (or switch revisions):
3292 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3294 Update the repository's working directory to the specified changeset.
3296 If no changeset is specified, update to the tip of the current named
3297 branch and move the active bookmark (see hg help bookmarks).
3298 Update sets the working directory's parent revision to the specified
3300 changeset (see hg help parents).
3301 If the changeset is not a descendant or ancestor of the working direc‐
3303 tory's parent and there are uncommitted changes, the update is aborted.
3304 With the -c/--check option, the working directory is checked for uncom‐
3305 mitted changes; if none are found, the working directory is updated to
3306 the specified changeset.
3307 The -C/--clean, -c/--check, and -m/--merge options control what happens
3309 if the working directory contains uncommitted changes. At most of one
3310 of them can be specified.
3311 1. If no option is specified, and if the requested changeset is an
3313 ancestor or descendant of the working directory's parent, the uncom‐
3314 mitted changes are merged into the requested changeset and the
3315 merged result is left uncommitted. If the requested changeset is not
3316 an ancestor or descendant (that is, it is on another branch), the
3317 update is aborted and the uncommitted changes are preserved.
3318 2. With the -m/--merge option, the update is allowed even if the
3320 requested changeset is not an ancestor or descendant of the working
3321 directory's parent.
3322 3. With the -c/--check option, the update is aborted and the uncommit‐
3324 ted changes are preserved.
3325 4. With the -C/--clean option, uncommitted changes are discarded and
3327 the working directory is updated to the requested changeset.
3328 To cancel an uncommitted merge (and lose your changes), use hg merge
3330 --abort.
3331 Use null as the changeset to remove the working directory (like hg
3333 clone -U).
3334 If you want to revert just one file to an older revision, use hg revert
3336 [-r REV] NAME.
3337 See hg help dates for a list of formats valid for -d/--date.
3339 Returns 0 on success, 1 if there are unresolved files.
3341 Options:
3343 -C, --clean
3345 discard uncommitted changes (no backup)
3346 -c, --check
3348 require clean working directory
3349 -m, --merge
3351 merge uncommitted changes
3352 -d,--date <DATE>
3354 tipmost revision matching date
3355 -r,--rev <REV>
3357 revision
3358 -t,--tool <TOOL>
3360 specify merge tool
3361 aliases: up checkout co
3363 Change import/export
3365 archive
3366 create an unversioned archive of a repository revision:
3367 hg archive [OPTION]... DEST
3369 By default, the revision used is the parent of the working directory;
3371 use -r/--rev to specify a different revision.
3372 The archive type is automatically detected based on file extension (to
3374 override, use -t/--type).
3375 Examples:
3377 · create a zip file containing the 1.0 release:
3379 hg archive -r 1.0 project-1.0.zip
3381 · create a tarball excluding .hg files:
3383 hg archive project.tar.gz -X ".hg*"
3385 Valid types are:
3387 files
3389 a directory full of files (default)
3391 tar
3393 tar archive, uncompressed
3395 tbz2
3397 tar archive, compressed using bzip2
3399 tgz
3401 tar archive, compressed using gzip
3403 txz
3405 tar archive, compressed using lzma (only in Python 3)
3407 uzip
3409 zip archive, uncompressed
3411 zip
3413 zip archive, compressed using deflate
3415 The exact name of the destination archive or directory is given using a
3417 format string; see hg help export for details.
3418 Each member added to an archive file has a directory prefix prepended.
3420 Use -p/--prefix to specify a format string for the prefix. The default
3421 is the basename of the archive, with suffixes removed.
3422 Returns 0 on success.
3424 Options:
3426 --no-decode
3428 do not pass files through decoders
3429 -p,--prefix <PREFIX>
3431 directory prefix for files in archive
3432 -r,--rev <REV>
3434 revision to distribute
3435 -t,--type <TYPE>
3437 type of distribution to create
3438 -S, --subrepos
3440 recurse into subrepositories
3441 -I,--include <PATTERN[+]>
3443 include names matching the given patterns
3444 -X,--exclude <PATTERN[+]>
3446 exclude names matching the given patterns
3447 [+] marked option can be specified multiple times
3449 bundle
3451 create a bundle file:
3452 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]
3454 Generate a bundle file containing data to be transferred to another
3456 repository.
3457 To create a bundle containing all changesets, use -a/--all (or --base
3459 null). Otherwise, hg assumes the destination will have all the nodes
3460 you specify with --base parameters. Otherwise, hg will assume the
3461 repository has all the nodes in destination, or default-push/default if
3462 no destination is specified, where destination is the repository you
3463 provide through DEST option.
3464 You can change bundle format with the -t/--type option. See hg help
3466 bundlespec for documentation on this format. By default, the most
3467 appropriate format is used and compression defaults to bzip2.
3468 The bundle file can then be transferred using conventional means and
3470 applied to another repository with the unbundle or pull command. This
3471 is useful when direct push and pull are not available or when exporting
3472 an entire repository is undesirable.
3473 Applying bundles preserves all changeset contents including permis‐
3475 sions, copy/rename information, and revision history.
3476 Returns 0 on success, 1 if no changes found.
3478 Options:
3480 -f, --force
3482 run even when the destination is unrelated
3483 -r,--rev <REV[+]>
3485 a changeset intended to be added to the destination
3486 -b,--branch <BRANCH[+]>
3488 a specific branch you would like to bundle
3489 --base <REV[+]>
3491 a base changeset assumed to be available at the destination
3492 -a, --all
3494 bundle all changesets in the repository
3495 -t,--type <TYPE>
3497 bundle compression type to use (default: bzip2)
3498 -e,--ssh <CMD>
3500 specify ssh command to use
3501 --remotecmd <CMD>
3503 specify hg command to run on the remote side
3504 --insecure
3506 do not verify server certificate (ignoring web.cacerts config)
3507 [+] marked option can be specified multiple times
3509 export
3511 dump the header and diffs for one or more changesets:
3512 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
3514 Print the changeset header and diffs for one or more revisions. If no
3516 revision is given, the parent of the working directory is used.
3517 The information shown in the changeset header is: author, date, branch
3519 name (if non-default), changeset hash, parent(s) and commit comment.
3520 Note hg export may generate unexpected diff output for merge change‐
3522 sets, as it will compare the merge changeset against its first
3523 parent only.
3524 Output may be to a file, in which case the name of the file is given
3526 using a template string. See hg help templates. In addition to the com‐
3527 mon template keywords, the following formatting rules are supported:
3528 %%
3530 literal "%" character
3532 %H
3534 changeset hash (40 hexadecimal digits)
3536 %N
3538 number of patches being generated
3540 %R
3542 changeset revision number
3544 %b
3546 basename of the exporting repository
3548 %h
3550 short-form changeset hash (12 hexadecimal digits)
3552 %m
3554 first line of the commit message (only alphanumeric characters)
3556 %n
3558 zero-padded sequence number, starting at 1
3560 %r
3562 zero-padded changeset revision number
3564 \
3566 literal "" character
3568 Without the -a/--text option, export will avoid generating diffs of
3570 files it detects as binary. With -a, export will generate a diff any‐
3571 way, probably with undesirable results.
3572 With -B/--bookmark changesets reachable by the given bookmark are
3574 selected.
3575 Use the -g/--git option to generate diffs in the git extended diff for‐
3577 mat. See hg help diffs for more information.
3578 With the --switch-parent option, the diff will be against the second
3580 parent. It can be useful to review a merge.
3581 Template:
3583 The following keywords are supported in addition to the common template
3585 keywords and functions. See also hg help templates.
3586 diff String. Diff content.
3588 parents
3590 List of strings. Parent nodes of the changeset.
3591 Examples:
3593 · use export and import to transplant a bugfix to the current branch:
3595 hg export -r 9353 | hg import -
3597 · export all the changesets between two revisions to a file with rename
3599 information:
3600 hg export --git -r 123:150 > changes.txt
3602 · split outgoing changes into a series of patches with descriptive
3604 names:
3605 hg export -r "outgoing()" -o "%n-%m.patch"
3607 Returns 0 on success.
3609 Options:
3611 -B,--bookmark <BOOKMARK>
3613 export changes only reachable by given bookmark
3614 -o,--output <FORMAT>
3616 print output to file with formatted name
3617 --switch-parent
3619 diff against the second parent
3620 -r,--rev <REV[+]>
3622 revisions to export
3623 -a, --text
3625 treat all files as text
3626 -g, --git
3628 use git extended diff format (DEFAULT: diff.git)
3629 --binary
3631 generate binary diffs in git mode (default)
3632 --nodates
3634 omit dates from diff headers
3635 -T,--template <TEMPLATE>
3637 display with template
3638 [+] marked option can be specified multiple times
3640 import
3642 import an ordered set of patches:
3643 hg import [OPTION]... PATCH...
3645 Import a list of patches and commit them individually (unless --no-com‐
3647 mit is specified).
3648 To read a patch from standard input (stdin), use "-" as the patch name.
3650 If a URL is specified, the patch will be downloaded from there.
3651 Import first applies changes to the working directory (unless --bypass
3653 is specified), import will abort if there are outstanding changes.
3654 Use --bypass to apply and commit patches directly to the repository,
3656 without affecting the working directory. Without --exact, patches will
3657 be applied on top of the working directory parent revision.
3658 You can import a patch straight from a mail message. Even patches as
3660 attachments work (to use the body part, it must have type text/plain or
3661 text/x-patch). From and Subject headers of email message are used as
3662 default committer and commit message. All text/plain body parts before
3663 first diff are added to the commit message.
3664 If the imported patch was generated by hg export, user and description
3666 from patch override values from message headers and body. Values given
3667 on command line with -m/--message and -u/--user override these.
3668 If --exact is specified, import will set the working directory to the
3670 parent of each patch before applying it, and will abort if the result‐
3671 ing changeset has a different ID than the one recorded in the patch.
3672 This will guard against various ways that portable patch formats and
3673 mail systems might fail to transfer Mercurial data or metadata. See hg
3674 bundle for lossless transmission.
3675 Use --partial to ensure a changeset will be created from the patch even
3677 if some hunks fail to apply. Hunks that fail to apply will be written
3678 to a <target-file>.rej file. Conflicts can then be resolved by hand
3679 before hg commit --amend is run to update the created changeset. This
3680 flag exists to let people import patches that partially apply without
3681 losing the associated metadata (author, date, description, ...).
3682 Note When no hunks apply cleanly, hg import --partial will create an
3684 empty changeset, importing only the patch metadata.
3685 With -s/--similarity, hg will attempt to discover renames and copies in
3687 the patch in the same way as hg addremove.
3688 It is possible to use external patch programs to perform the patch by
3690 setting the ui.patch configuration option. For the default internal
3691 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
3692 fig for more information about configuration files and how to use these
3693 options.
3694 See hg help dates for a list of formats valid for -d/--date.
3696 Examples:
3698 · import a traditional patch from a website and detect renames:
3700 hg import -s 80 http://example.com/bugfix.patch
3702 · import a changeset from an hgweb server:
3704 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
3706 · import all the patches in an Unix-style mbox:
3708 hg import incoming-patches.mbox
3710 · import patches from stdin:
3712 hg import -
3714 · attempt to exactly restore an exported changeset (not always possi‐
3716 ble):
3717 hg import --exact proposed-fix.patch
3719 · use an external tool to apply a patch which is too fuzzy for the
3721 default internal tool.
3722 hg import --config ui.patch="patch --merge" fuzzy.patch
3724 · change the default fuzzing from 2 to a less strict 7
3726 hg import --config ui.fuzz=7 fuzz.patch
3728 Returns 0 on success, 1 on partial success (see --partial).
3730 Options:
3732 -p,--strip <NUM>
3734 directory strip option for patch. This has the same meaning as
3735 the corresponding patch option (default: 1)
3736 -b,--base <PATH>
3738 base path (DEPRECATED)
3739 --secret
3741 use the secret phase for committing
3742 -e, --edit
3744 invoke editor on commit messages
3745 -f, --force
3747 skip check for outstanding uncommitted changes (DEPRECATED)
3748 --no-commit
3750 don't commit, just update the working directory
3751 --bypass
3753 apply patch without touching the working directory
3754 --partial
3756 commit even if some hunks fail
3757 --exact
3759 abort if patch would apply lossily
3760 --prefix <DIR>
3762 apply patch to subdirectory
3763 --import-branch
3765 use any branch information in patch (implied by --exact)
3766 -m,--message <TEXT>
3768 use text as commit message
3769 -l,--logfile <FILE>
3771 read commit message from file
3772 -d,--date <DATE>
3774 record the specified date as commit date
3775 -u,--user <USER>
3777 record the specified user as committer
3778 -s,--similarity <SIMILARITY>
3780 guess renamed files by similarity (0<=s<=100)
3781 aliases: patch
3783 unbundle
3785 apply one or more bundle files:
3786 hg unbundle [-u] FILE...
3788 Apply one or more bundle files generated by hg bundle.
3790 Returns 0 on success, 1 if an update has unresolved files.
3792 Options:
3794 -u, --update
3796 update to new branch head if changesets were unbundled
3797 Repository maintenance
3799 manifest
3800 output the current or given revision of the project manifest:
3801 hg manifest [-r REV]
3803 Print a list of version controlled files for the given revision. If no
3805 revision is given, the first parent of the working directory is used,
3806 or the null revision if no revision is checked out.
3807 With -v, print file permissions, symlink and executable bits. With
3809 --debug, print file revision hashes.
3810 If option --all is specified, the list of all files from all revisions
3812 is printed. This includes deleted and renamed files.
3813 Returns 0 on success.
3815 Options:
3817 -r,--rev <REV>
3819 revision to display
3820 --all list files from all revisions
3822 -T,--template <TEMPLATE>
3824 display with template
3825 recover
3827 roll back an interrupted transaction:
3828 hg recover
3830 Recover from an interrupted commit or pull.
3832 This command tries to fix the repository status after an interrupted
3834 operation. It should only be necessary when Mercurial suggests it.
3835 Returns 0 if successful, 1 if nothing to recover or verify fails.
3837 Options:
3839 --verify
3841 run hg verify after successful recover
3842 rollback
3844 roll back the last transaction (DANGEROUS) (DEPRECATED):
3845 hg rollback
3847 Please use hg commit --amend instead of rollback to correct mistakes in
3849 the last commit.
3850 This command should be used with care. There is only one level of roll‐
3852 back, and there is no way to undo a rollback. It will also restore the
3853 dirstate at the time of the last transaction, losing any dirstate
3854 changes since that time. This command does not alter the working direc‐
3855 tory.
3856 Transactions are used to encapsulate the effects of all commands that
3858 create new changesets or propagate existing changesets into a reposi‐
3859 tory.
3860 For example, the following commands are transactional, and their
3862 effects can be rolled back:
3863 · commit
3865 · import
3867 · pull
3869 · push (with this repository as the destination)
3871 · unbundle
3873 To avoid permanent data loss, rollback will refuse to rollback a commit
3875 transaction if it isn't checked out. Use --force to override this pro‐
3876 tection.
3877 The rollback command can be entirely disabled by setting the ui.roll‐
3879 back configuration setting to false. If you're here because you want to
3880 use rollback and it's disabled, you can re-enable the command by set‐
3881 ting ui.rollback to true.
3882 This command is not intended for use on public repositories. Once
3884 changes are visible for pull by other users, rolling a transaction back
3885 locally is ineffective (someone else may already have pulled the
3886 changes). Furthermore, a race is possible with readers of the reposi‐
3887 tory; for example an in-progress pull from the repository may fail if a
3888 rollback is performed.
3889 Returns 0 on success, 1 if no rollback data is available.
3891 Options:
3893 -n, --dry-run
3895 do not perform actions, just print output
3896 -f, --force
3898 ignore safety measures
3899 verify
3901 verify the integrity of the repository:
3902 hg verify
3904 Verify the integrity of the current repository.
3906 This will perform an extensive check of the repository's integrity,
3908 validating the hashes and checksums of each entry in the changelog,
3909 manifest, and tracked files, as well as the integrity of their
3910 crosslinks and indices.
3911 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
3913 information about recovery from corruption of the repository.
3914 Returns 0 on success, 1 if errors are encountered.
3916 Options:
3918 --full perform more checks (EXPERIMENTAL)
3920 Help
3922 config
3923 show combined config settings from all hgrc files:
3924 hg config [-u] [NAME]...
3926 With no arguments, print names and values of all config items.
3928 With one argument of the form section.name, print just the value of
3930 that config item.
3931 With multiple arguments, print names and values of all config items
3933 with matching section names or section.names.
3934 With --edit, start an editor on the user-level config file. With
3936 --global, edit the system-wide config file. With --local, edit the
3937 repository-level config file.
3938 With --debug, the source (filename and line number) is printed for each
3940 config item.
3941 See hg help config for more information about config files.
3943 Template:
3945 The following keywords are supported. See also hg help templates.
3947 name String. Config name.
3949 source String. Filename and line number where the item is defined.
3951 value String. Config value.
3953 Returns 0 on success, 1 if NAME does not exist.
3955 Options:
3957 -u, --untrusted
3959 show untrusted configuration options
3960 -e, --edit
3962 edit user config
3963 -l, --local
3965 edit repository config
3966 -g, --global
3968 edit global config
3969 -T,--template <TEMPLATE>
3971 display with template
3972 aliases: showconfig debugconfig
3974 help
3976 show help for a given topic or a help overview:
3977 hg help [-eck] [-s PLATFORM] [TOPIC]
3979 With no arguments, print a list of commands with short help messages.
3981 Given a topic, extension, or command name, print help for that topic.
3983 Returns 0 if successful.
3985 Options:
3987 -e, --extension
3989 show only help for extensions
3990 -c, --command
3992 show only help for commands
3993 -k, --keyword
3995 show topics matching keyword
3996 -s,--system <PLATFORM[+]>
3998 show help for specific platform(s)
3999 [+] marked option can be specified multiple times
4001 version
4003 output version and copyright information:
4004 hg version
4006 Template:
4008 The following keywords are supported. See also hg help templates.
4010 extensions
4012 List of extensions.
4013 ver String. Version number.
4015 And each entry of {extensions} provides the following sub-keywords in
4017 addition to {ver}.
4018 bundled
4020 Boolean. True if included in the release.
4021 name String. Extension name.
4023 Options:
4025 -T,--template <TEMPLATE>
4027 display with template
4028 Uncategorized commands
4031 Mercurial supports generating standalone "bundle" files that hold
4032 repository data. These "bundles" are typically saved locally and used
4033 later or exchanged between different repositories, possibly on differ‐
4034 ent machines. Example commands using bundles are hg bundle and hg
4035 unbundle.
4036 Generation of bundle files is controlled by a "bundle specification"
4038 ("bundlespec") string. This string tells the bundle generation process
4039 how to create the bundle.
4040 A "bundlespec" string is composed of the following elements:
4042 type A string denoting the bundle format to use.
4044 compression
4046 Denotes the compression engine to use compressing the raw bundle
4047 data.
4048 parameters
4050 Arbitrary key-value parameters to further control bundle genera‐
4051 tion.
4052 A "bundlespec" string has the following formats:
4054 <type> The literal bundle format string is used.
4056 <compression>-<type>
4058 The compression engine and format are delimited by a hyphen (-).
4059 Optional parameters follow the <type>. Parameters are URI escaped
4061 key=value pairs. Each pair is delimited by a semicolon (;). The first
4062 parameter begins after a ; immediately following the <type> value.
4063 Available Types
4065 The following bundle <type> strings are available:
4066 v1 Produces a legacy "changegroup" version 1 bundle.
4068 This format is compatible with nearly all Mercurial clients
4070 because it is the oldest. However, it has some limitations,
4071 which is why it is no longer the default for new repositories.
4072 v1 bundles can be used with modern repositories using the "gen‐
4074 eraldelta" storage format. However, it may take longer to pro‐
4075 duce the bundle and the resulting bundle may be significantly
4076 larger than a v2 bundle.
4077 v1 bundles can only use the gzip, bzip2, and none compression
4079 formats.
4080 v2 Produces a version 2 bundle.
4082 Version 2 bundles are an extensible format that can store addi‐
4084 tional repository data (such as bookmarks and phases informa‐
4085 tion) and they can store data more efficiently, resulting in
4086 smaller bundles.
4087 Version 2 bundles can also use modern compression engines, such
4089 as zstd, making them faster to compress and often smaller.
4090 Available Compression Engines
4092 The following bundle <compression> engines can be used:
4093 bzip2
4095 An algorithm that produces smaller bundles than gzip.
4097 All Mercurial clients should support this format.
4099 This engine will likely produce smaller bundles than gzip but
4101 will be significantly slower, both during compression and decom‐
4102 pression.
4103 If available, the zstd engine can yield similar or better com‐
4105 pression at much higher speeds.
4106 gzip
4108 zlib compression using the DEFLATE algorithm.
4110 All Mercurial clients should support this format. The compres‐
4112 sion algorithm strikes a reasonable balance between compression
4113 ratio and size.
4114 none
4116 No compression is performed.
4118 Use this compression engine to explicitly disable compression.
4120 Examples
4122 v2
4123 Produce a v2 bundle using default options, including compres‐
4125 sion.
4126 none-v1
4128 Produce a v1 bundle with no compression.
4130 zstd-v2
4132 Produce a v2 bundle with zstandard compression using default
4134 settings.
4135 zstd-v1
4137 This errors because zstd is not supported for v1 types.
4139
4141 Mercurial colorizes output from several commands.
4142 For example, the diff command shows additions in green and deletions in
4144 red, while the status command shows modified files in magenta. Many
4145 other commands have analogous colors. It is possible to customize these
4146 colors.
4147 To enable color (default) whenever possible use:
4149 [ui]
4151 color = yes
4152 To disable color use:
4154 [ui]
4156 color = no
4157 See hg help config.ui.color for details.
4159 The default pager on Windows does not support color, so enabling the
4161 pager will effectively disable color. See hg help config.ui.paginate
4162 to disable the pager. Alternately, MSYS and Cygwin shells provide less
4163 as a pager, which can be configured to support ANSI color mode. Win‐
4164 dows 10 natively supports ANSI color mode.
4165 Mode
4167 Mercurial can use various systems to display color. The supported modes
4168 are ansi, win32, and terminfo. See hg help config.color for details
4169 about how to control the mode.
4170 Effects
4172 Other effects in addition to color, like bold and underlined text, are
4173 also available. By default, the terminfo database is used to find the
4174 terminal codes used to change color and effect. If terminfo is not
4175 available, then effects are rendered with the ECMA-48 SGR control func‐
4176 tion (aka ANSI escape codes).
4177 The available effects in terminfo mode are 'blink', 'bold', 'dim',
4179 'inverse', 'invisible', 'italic', 'standout', and 'underline'; in
4180 ECMA-48 mode, the options are 'bold', 'inverse', 'italic', and 'under‐
4181 line'. How each is rendered depends on the terminal emulator. Some
4182 may not be available for a given terminal type, and will be silently
4183 ignored.
4184 If the terminfo entry for your terminal is missing codes for an effect
4186 or has the wrong codes, you can add or override those codes in your
4187 configuration:
4188 [color]
4190 terminfo.dim = \E[2m
4191 where 'E' is substituted with an escape character.
4193 Labels
4195 Text receives color effects depending on the labels that it has. Many
4196 default Mercurial commands emit labelled text. You can also define your
4197 own labels in templates using the label function, see hg help templates
4198 . A single portion of text may have more than one label. In that case,
4199 effects given to the last label will override any other effects. This
4200 includes the special "none" effect, which nullifies other effects.
4201 Labels are normally invisible. In order to see these labels and their
4203 position in the text, use the global --color=debug option. The same
4204 anchor text may be associated to multiple labels, e.g.
4205 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
4207 The following are the default effects for some default labels. Default
4209 effects may be overridden from your configuration file:
4210 [color]
4212 status.modified = blue bold underline red_background
4213 status.added = green bold
4214 status.removed = red bold blue_background
4215 status.deleted = cyan bold underline
4216 status.unknown = magenta bold underline
4217 status.ignored = black bold
4218 # 'none' turns off all effects
4220 status.clean = none
4221 status.copied = none
4222 qseries.applied = blue bold underline
4224 qseries.unapplied = black bold
4225 qseries.missing = red bold
4226 diff.diffline = bold
4228 diff.extended = cyan bold
4229 diff.file_a = red bold
4230 diff.file_b = green bold
4231 diff.hunk = magenta
4232 diff.deleted = red
4233 diff.inserted = green
4234 diff.changed = white
4235 diff.tab =
4236 diff.trailingwhitespace = bold red_background
4237 # Blank so it inherits the style of the surrounding label
4239 changeset.public =
4240 changeset.draft =
4241 changeset.secret =
4242 resolve.unresolved = red bold
4244 resolve.resolved = green bold
4245 bookmarks.active = green
4247 branches.active = none
4249 branches.closed = black bold
4250 branches.current = green
4251 branches.inactive = none
4252 tags.normal = green
4254 tags.local = black bold
4255 rebase.rebased = blue
4257 rebase.remaining = red bold
4258 shelve.age = cyan
4260 shelve.newest = green bold
4261 shelve.name = blue bold
4262 histedit.remaining = red bold
4264 Custom colors
4266 Because there are only eight standard colors, Mercurial allows you to
4267 define color names for other color slots which might be available for
4268 your terminal type, assuming terminfo mode. For instance:
4269 color.brightblue = 12
4271 color.pink = 207
4272 color.orange = 202
4273 to set 'brightblue' to color slot 12 (useful for 16 color terminals
4275 that have brighter colors defined in the upper eight) and, 'pink' and
4276 'orange' to colors in 256-color xterm's default color cube. These
4277 defined colors may then be used as any of the pre-defined eight,
4278 including appending '_background' to set the background to that color.
4279
4281 Some commands allow the user to specify a date, e.g.:
4282 · backout, commit, import, tag: Specify the commit date.
4284 · log, revert, update: Select revision(s) by date.
4286 Many date formats are valid. Here are some examples:
4288 · Wed Dec 6 13:18:29 2006 (local timezone assumed)
4290 · Dec 6 13:18 -0600 (year assumed, time offset provided)
4292 · Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
4294 · Dec 6 (midnight)
4296 · 13:18 (today assumed)
4298 · 3:39 (3:39AM assumed)
4300 · 3:39pm (15:39)
4302 · 2006-12-06 13:18:29 (ISO 8601 format)
4304 · 2006-12-6 13:18
4306 · 2006-12-6
4308 · 12-6
4310 · 12/6
4312 · 12/6/6 (Dec 6 2006)
4314 · today (midnight)
4316 · yesterday (midnight)
4318 · now - right now
4320 Lastly, there is Mercurial's internal format:
4322 · 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
4324 This is the internal representation format for dates. The first number
4326 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
4327 second is the offset of the local timezone, in seconds west of UTC
4328 (negative if the timezone is east of UTC).
4329 The log command also accepts date ranges:
4331 · <DATE - at or before a given date/time
4333 · >DATE - on or after a given date/time
4335 · DATE to DATE - a date range, inclusive
4337 · -DAYS - within a given number of days of today
4339
4341 Mercurial evolves over time, some features, options, commands may be
4342 replaced by better and more secure alternatives. This topic will help
4343 you migrating your existing usage and/or configuration to newer fea‐
4344 tures.
4345 Commands
4347 The following commands are still available but their use are not recom‐
4348 mended:
4349 locate
4351 This command has been replaced by hg files.
4353 parents
4355 This command can be replaced by hg summary or hg log with appropriate
4357 revsets. See hg help revsets for more information.
4358 tip
4360 The recommended alternative is hg heads.
4362 Options
4364 web.allowpull
4365 Renamed to allow-pull.
4367 web.allow_push
4369 Renamed to allow-push.
4371
4373 Mercurial's default format for showing changes between two versions of
4374 a file is compatible with the unified format of GNU diff, which can be
4375 used by GNU patch and many other standard tools.
4376 While this standard format is often enough, it does not encode the fol‐
4378 lowing information:
4379 · executable status and other permission bits
4381 · copy or rename information
4383 · changes in binary files
4385 · creation or deletion of empty files
4387 Mercurial also supports the extended diff format from the git VCS which
4389 addresses these limitations. The git diff format is not produced by
4390 default because a few widespread tools still do not understand this
4391 format.
4392 This means that when generating diffs from a Mercurial repository (e.g.
4394 with hg export), you should be careful about things like file copies
4395 and renames or other things mentioned above, because when applying a
4396 standard diff to a different repository, this extra information is
4397 lost. Mercurial's internal operations (like push and pull) are not
4398 affected by this, because they use an internal binary format for commu‐
4399 nicating changes.
4400 To make Mercurial produce the git extended diff format, use the --git
4402 option available for many commands, or set 'git = True' in the [diff]
4403 section of your configuration file. You do not need to set this option
4404 when importing diffs in this format or using them in the mq extension.
4405
4407 HG Path to the 'hg' executable, automatically passed when running
4408 hooks, extensions or external tools. If unset or empty, this is
4409 the hg executable's name if it's frozen, or an executable named
4410 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
4411 on Windows) is searched.
4412 HGEDITOR
4414 This is the name of the editor to run when committing. See EDI‐
4415 TOR.
4416 (deprecated, see hg help config.ui.editor)
4418 HGENCODING
4420 This overrides the default locale setting detected by Mercurial.
4421 This setting is used to convert data including usernames,
4422 changeset descriptions, tag names, and branches. This setting
4423 can be overridden with the --encoding command-line option.
4424 HGENCODINGMODE
4426 This sets Mercurial's behavior for handling unknown characters
4427 while transcoding user input. The default is "strict", which
4428 causes Mercurial to abort if it can't map a character. Other
4429 settings include "replace", which replaces unknown characters,
4430 and "ignore", which drops them. This setting can be overridden
4431 with the --encodingmode command-line option.
4432 HGENCODINGAMBIGUOUS
4434 This sets Mercurial's behavior for handling characters with
4435 "ambiguous" widths like accented Latin characters with East
4436 Asian fonts. By default, Mercurial assumes ambiguous characters
4437 are narrow, set this variable to "wide" if such characters cause
4438 formatting problems.
4439 HGMERGE
4441 An executable to use for resolving merge conflicts. The program
4442 will be executed with three arguments: local file, remote file,
4443 ancestor file.
4444 (deprecated, see hg help config.ui.merge)
4446 HGRCPATH
4448 A list of files or directories to search for configuration
4449 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
4450 PATH is not set, platform default search path is used. If empty,
4451 only the .hg/hgrc from the current repository is read.
4452 For each element in HGRCPATH:
4454 · if it's a directory, all files ending with .rc are added
4456 · otherwise, the file itself will be added
4458 HGRCSKIPREPO
4460 When set, the .hg/hgrc from repositories are not read.
4461 HGPLAIN
4463 When set, this disables any configuration settings that might
4464 change Mercurial's default output. This includes encoding,
4465 defaults, verbose mode, debug mode, quiet mode, tracebacks, and
4466 localization. This can be useful when scripting against Mercu‐
4467 rial in the face of existing user configuration.
4468 In addition to the features disabled by HGPLAIN=, the following
4470 values can be specified to adjust behavior:
4471 +strictflags
4473 Restrict parsing of command line flags.
4475 Equivalent options set via command line flags or environment
4477 variables are not overridden.
4478 See hg help scripting for details.
4480 HGPLAINEXCEPT
4482 This is a comma-separated list of features to preserve when
4483 HGPLAIN is enabled. Currently the following values are sup‐
4484 ported:
4485 alias
4487 Don't remove aliases.
4489 color
4491 Don't disable colored output.
4493 i18n
4495 Preserve internationalization.
4497 revsetalias
4499 Don't remove revset aliases.
4501 templatealias
4503 Don't remove template aliases.
4505 progress
4507 Don't hide progress output.
4509 Setting HGPLAINEXCEPT to anything (even an empty string) will
4511 enable plain mode.
4512 HGUSER This is the string used as the author of a commit. If not set,
4514 available values will be considered in this order:
4515 · HGUSER (deprecated)
4517 · configuration files from the HGRCPATH
4519 · EMAIL
4521 · interactive prompt
4523 · LOGNAME (with @hostname appended)
4525 (deprecated, see hg help config.ui.username)
4527 EMAIL May be used as the author of a commit; see HGUSER.
4529 LOGNAME
4531 May be used as the author of a commit; see HGUSER.
4532 VISUAL This is the name of the editor to use when committing. See EDI‐
4534 TOR.
4535 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
4537 user to modify, for example when writing commit messages. The
4538 editor it uses is determined by looking at the environment vari‐
4539 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
4540 non-empty one is chosen. If all of them are empty, the editor
4541 defaults to 'vi'.
4542 PYTHONPATH
4544 This is used by Python to find imported modules and may need to
4545 be set appropriately if this Mercurial is not installed sys‐
4546 tem-wide.
4547
4549 Mercurial has the ability to add new features through the use of exten‐
4550 sions. Extensions may add new commands, add options to existing com‐
4551 mands, change the default behavior of commands, or implement hooks.
4552 To enable the "foo" extension, either shipped with Mercurial or in the
4554 Python search path, create an entry for it in your configuration file,
4555 like this:
4556 [extensions]
4558 foo =
4559 You may also specify the full path to an extension:
4561 [extensions]
4563 myfeature = ~/.hgext/myfeature.py
4564 See hg help config for more information on configuration files.
4566 Extensions are not loaded by default for a variety of reasons: they can
4568 increase startup overhead; they may be meant for advanced usage only;
4569 they may provide potentially dangerous abilities (such as letting you
4570 destroy or modify history); they might not be ready for prime time; or
4571 they may alter some usual behaviors of stock Mercurial. It is thus up
4572 to the user to activate extensions as needed.
4573 To explicitly disable an extension enabled in a configuration file of
4575 broader scope, prepend its path with !:
4576 [extensions]
4578 # disabling extension bar residing in /path/to/extension/bar.py
4579 bar = !/path/to/extension/bar.py
4580 # ditto, but no path was supplied for extension baz
4581 baz = !
4582 disabled extensions:
4584 acl hooks for controlling repository access
4586 blackbox
4588 log repository events to a blackbox for debugging
4589 bugzilla
4591 hooks for integrating with the Bugzilla bug tracker
4592 censor erase file content at a given revision
4594 churn command to display statistics about repository history
4596 clonebundles
4598 advertise pre-generated bundles to seed clones
4599 closehead
4601 close arbitrary heads without checking them out first
4602 convert
4604 import revisions from foreign VCS repositories into Mercurial
4605 eol automatically manage newlines in repository files
4607 extdiff
4609 command to allow external programs to compare revisions
4610 factotum
4612 http authentication with factotum
4613 fastexport
4615 export repositories as git fast-import stream
4616 githelp
4618 try mapping git commands to Mercurial commands
4619 gpg commands to sign and verify changesets
4621 hgk browse the repository in a graphical way
4623 highlight
4625 syntax highlighting for hgweb (requires Pygments)
4626 histedit
4628 interactive history editing
4629 keyword
4631 expand keywords in tracked files
4632 largefiles
4634 track large binary files
4635 mq manage a stack of patches
4637 notify hooks for sending email push notifications
4639 patchbomb
4641 command to send changesets as (a series of) patch emails
4642 purge command to delete untracked files from the working directory
4644 rebase command to move sets of revisions to a different ancestor
4646 relink recreates hardlinks between repository clones
4648 schemes
4650 extend schemes with shortcuts to repository swarms
4651 share share a common history between several working directories
4653 strip strip changesets and their descendants from history
4655 transplant
4657 command to transplant changesets from another branch
4658 win32mbcs
4660 allow the use of MBCS paths with problematic encodings
4661 zeroconf
4663 discover and advertise repositories on the local network
4664
4666 Mercurial supports a functional language for selecting a set of files.
4667 Like other file patterns, this pattern type is indicated by a prefix,
4669 'set:'. The language supports a number of predicates which are joined
4670 by infix operators. Parenthesis can be used for grouping.
4671 Identifiers such as filenames or patterns must be quoted with single or
4673 double quotes if they contain characters outside of
4674 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4675 predicates. This generally applies to file patterns other than globs
4676 and arguments for predicates. Pattern prefixes such as path: may be
4677 specified without quoting.
4678 Special characters can be used in quoted identifiers by escaping them,
4680 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4681 preted, strings can be prefixed with r, e.g. r'...'.
4682 See also hg help patterns.
4684 Operators
4686 There is a single prefix operator:
4687 not x
4689 Files not in x. Short form is ! x.
4691 These are the supported infix operators:
4693 x and y
4695 The intersection of files in x and y. Short form is x & y.
4697 x or y
4699 The union of files in x and y. There are two alternative short
4701 forms: x | y and x + y.
4702 x - y
4704 Files in x but not in y.
4706 Predicates
4708 The following predicates are supported:
4709 added()
4711 File that is added according to hg status.
4713 binary()
4715 File that appears to be binary (contains NUL bytes).
4717 clean()
4719 File that is clean according to hg status.
4721 copied()
4723 File that is recorded as being copied.
4725 deleted()
4727 Alias for missing().
4729 encoding(name)
4731 File can be successfully decoded with the given character encod‐
4733 ing. May not be useful for encodings other than ASCII and UTF-8.
4734 eol(style)
4736 File contains newlines of the given style (dos, unix, mac).
4738 Binary files are excluded, files with mixed line endings match
4739 multiple styles.
4740 exec()
4742 File that is marked as executable.
4744 grep(regex)
4746 File contains the given regular expression.
4748 hgignore()
4750 File that matches the active .hgignore pattern.
4752 ignored()
4754 File that is ignored according to hg status.
4756 missing()
4758 File that is missing according to hg status.
4760 modified()
4762 File that is modified according to hg status.
4764 portable()
4766 File that has a portable name. (This doesn't include filenames
4768 with case collisions.)
4769 removed()
4771 File that is removed according to hg status.
4773 resolved()
4775 File that is marked resolved according to hg resolve -l.
4777 revs(revs, pattern)
4779 Evaluate set in the specified revisions. If the revset match
4781 multiple revs, this will return file matching pattern in any of
4782 the revision.
4783 size(expression)
4785 File size matches the given expression. Examples:
4787 · size('1k') - files from 1024 to 2047 bytes
4789 · size('< 20k') - files less than 20480 bytes
4791 · size('>= .5MB') - files at least 524288 bytes
4793 · size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
4795 status(base, rev, pattern)
4797 Evaluate predicate using status change between base and rev.
4799 Examples:
4800 · status(3, 7, added()) - matches files added from "3" to "7"
4802 subrepo([pattern])
4804 Subrepositories whose paths match the given pattern.
4806 symlink()
4808 File that is marked as a symlink.
4810 tracked()
4812 File that is under Mercurial control.
4814 unknown()
4816 File that is unknown according to hg status.
4818 unresolved()
4820 File that is marked unresolved according to hg resolve -l.
4822 Examples
4824 Some sample queries:
4825 · Show status of files that appear to be binary in the working direc‐
4827 tory:
4828 hg status -A "set:binary()"
4830 · Forget files that are in .hgignore but are already tracked:
4832 hg forget "set:hgignore() and not ignored()"
4834 · Find text files that contain a string:
4836 hg files "set:grep(magic) and not binary()"
4838 · Find C files in a non-standard encoding:
4840 hg files "set:**.c and not encoding('UTF-8')"
4842 · Revert copies of large binary files:
4844 hg revert "set:copied() and binary() and size('>1M')"
4846 · Revert files that were added to the working directory:
4848 hg revert "set:revs('wdir()', added())"
4850 · Remove files listed in foo.lst that contain the letter a or b:
4852 hg remove "set: listfile:foo.lst and (**a* or **b*)"
4854
4856 Most Mercurial commands accept various flags.
4857 Flag names
4859 Flags for each command are listed in hg help for that command. Addi‐
4860 tionally, some flags, such as --repository, are global and can be used
4861 with any command - those are seen in hg help -v, and can be specified
4862 before or after the command.
4863 Every flag has at least a long name, such as --repository. Some flags
4865 may also have a short one-letter name, such as the equivalent -R. Using
4866 the short or long name is equivalent and has the same effect.
4867 Flags that have a short name can also be bundled together - for
4869 instance, to specify both --edit (short -e) and --interactive (short
4870 -i), one could use:
4871 hg commit -ei
4873 If any of the bundled flags takes a value (i.e. is not a boolean), it
4875 must be last, followed by the value:
4876 hg commit -im 'Message'
4878 Flag types
4880 Mercurial command-line flags can be strings, numbers, booleans, or
4881 lists of strings.
4882 Specifying flag values
4884 The following syntaxes are allowed, assuming a flag 'flagname' with
4885 short name 'f':
4886 --flagname=foo
4888 --flagname foo
4889 -f foo
4890 -ffoo
4891 This syntax applies to all non-boolean flags (strings, numbers or
4893 lists).
4894 Specifying boolean flags
4896 Boolean flags do not take a value parameter. To specify a boolean, use
4897 the flag name to set it to true, or the same name prefixed with 'no-'
4898 to set it to false:
4899 hg commit --interactive
4901 hg commit --no-interactive
4902 Specifying list flags
4904 List flags take multiple values. To specify them, pass the flag multi‐
4905 ple times:
4906 hg files --include mercurial --include tests
4908 Setting flag defaults
4910 In order to set a default value for a flag in an hgrc file, it is rec‐
4911 ommended to use aliases:
4912 [alias]
4914 commit = commit --interactive
4915 For more information on hgrc files, see hg help config.
4917 Overriding flags on the command line
4919 If the same non-list flag is specified multiple times on the command
4920 line, the latest specification is used:
4921 hg commit -m "Ignored value" -m "Used value"
4923 This includes the use of aliases - e.g., if one has:
4925 [alias]
4927 committemp = commit -m "Ignored value"
4928 then the following command will override that -m:
4930 hg committemp -m "Used value"
4932 Overriding flag defaults
4934 Every flag has a default value, and you may also set your own defaults
4935 in hgrc as described above. Except for list flags, defaults can be
4936 overridden on the command line simply by specifying the flag in that
4937 location.
4938 Hidden flags
4940 Some flags are not shown in a command's help by default - specifically,
4941 those that are deemed to be experimental, deprecated or advanced. To
4942 show all flags, add the --verbose flag for the help command:
4943 hg help --verbose commit
4945
4947 Ancestor
4948 Any changeset that can be reached by an unbroken chain of parent
4949 changesets from a given changeset. More precisely, the ancestors
4950 of a changeset can be defined by two properties: a parent of a
4951 changeset is an ancestor, and a parent of an ancestor is an
4952 ancestor. See also: 'Descendant'.
4953 Bookmark
4955 Bookmarks are pointers to certain commits that move when commit‐
4956 ting. They are similar to tags in that it is possible to use
4957 bookmark names in all places where Mercurial expects a changeset
4958 ID, e.g., with hg update. Unlike tags, bookmarks move along when
4959 you make a commit.
4960 Bookmarks can be renamed, copied and deleted. Bookmarks are
4962 local, unless they are explicitly pushed or pulled between
4963 repositories. Pushing and pulling bookmarks allow you to col‐
4964 laborate with others on a branch without creating a named
4965 branch.
4966 Branch (Noun) A child changeset that has been created from a parent
4968 that is not a head. These are known as topological branches, see
4969 'Branch, topological'. If a topological branch is named, it
4970 becomes a named branch. If a topological branch is not named, it
4971 becomes an anonymous branch. See 'Branch, anonymous' and
4972 'Branch, named'.
4973 Branches may be created when changes are pulled from or pushed
4975 to a remote repository, since new heads may be created by these
4976 operations. Note that the term branch can also be used infor‐
4977 mally to describe a development process in which certain devel‐
4978 opment is done independently of other development. This is some‐
4979 times done explicitly with a named branch, but it can also be
4980 done locally, using bookmarks or clones and anonymous branches.
4981 Example: "The experimental branch."
4983 (Verb) The action of creating a child changeset which results in
4985 its parent having more than one child.
4986 Example: "I'm going to branch at X."
4988 Branch, anonymous
4990 Every time a new child changeset is created from a parent that
4991 is not a head and the name of the branch is not changed, a new
4992 anonymous branch is created.
4993 Branch, closed
4995 A named branch whose branch heads have all been closed.
4996 Branch, default
4998 The branch assigned to a changeset when no name has previously
4999 been assigned.
5000 Branch head
5002 See 'Head, branch'.
5003 Branch, inactive
5005 If a named branch has no topological heads, it is considered to
5006 be inactive. As an example, a feature branch becomes inactive
5007 when it is merged into the default branch. The hg branches com‐
5008 mand shows inactive branches by default, though they can be hid‐
5009 den with hg branches --active.
5010 NOTE: this concept is deprecated because it is too implicit.
5012 Branches should now be explicitly closed using hg commit
5013 --close-branch when they are no longer needed.
5014 Branch, named
5016 A collection of changesets which have the same branch name. By
5017 default, children of a changeset in a named branch belong to the
5018 same named branch. A child can be explicitly assigned to a dif‐
5019 ferent branch. See hg help branch, hg help branches and hg com‐
5020 mit --close-branch for more information on managing branches.
5021 Named branches can be thought of as a kind of namespace, divid‐
5023 ing the collection of changesets that comprise the repository
5024 into a collection of disjoint subsets. A named branch is not
5025 necessarily a topological branch. If a new named branch is cre‐
5026 ated from the head of another named branch, or the default
5027 branch, but no further changesets are added to that previous
5028 branch, then that previous branch will be a branch in name only.
5029 Branch tip
5031 See 'Tip, branch'.
5032 Branch, topological
5034 Every time a new child changeset is created from a parent that
5035 is not a head, a new topological branch is created. If a topo‐
5036 logical branch is named, it becomes a named branch. If a topo‐
5037 logical branch is not named, it becomes an anonymous branch of
5038 the current, possibly default, branch.
5039 Changelog
5041 A record of the changesets in the order in which they were added
5042 to the repository. This includes details such as changeset id,
5043 author, commit message, date, and list of changed files.
5044 Changeset
5046 A snapshot of the state of the repository used to record a
5047 change.
5048 Changeset, child
5050 The converse of parent changeset: if P is a parent of C, then C
5051 is a child of P. There is no limit to the number of children
5052 that a changeset may have.
5053 Changeset id
5055 A SHA-1 hash that uniquely identifies a changeset. It may be
5056 represented as either a "long" 40 hexadecimal digit string, or a
5057 "short" 12 hexadecimal digit string.
5058 Changeset, merge
5060 A changeset with two parents. This occurs when a merge is com‐
5061 mitted.
5062 Changeset, parent
5064 A revision upon which a child changeset is based. Specifically,
5065 a parent changeset of a changeset C is a changeset whose node
5066 immediately precedes C in the DAG. Changesets have at most two
5067 parents.
5068 Checkout
5070 (Noun) The working directory being updated to a specific revi‐
5071 sion. This use should probably be avoided where possible, as
5072 changeset is much more appropriate than checkout in this con‐
5073 text.
5074 Example: "I'm using checkout X."
5076 (Verb) Updating the working directory to a specific changeset.
5078 See hg help update.
5079 Example: "I'm going to check out changeset X."
5081 Child changeset
5083 See 'Changeset, child'.
5084 Close changeset
5086 See 'Head, closed branch'.
5087 Closed branch
5089 See 'Branch, closed'.
5090 Clone (Noun) An entire or partial copy of a repository. The partial
5092 clone must be in the form of a revision and its ancestors.
5093 Example: "Is your clone up to date?"
5095 (Verb) The process of creating a clone, using hg clone.
5097 Example: "I'm going to clone the repository."
5099 Closed branch head
5101 See 'Head, closed branch'.
5102 Commit (Noun) A synonym for changeset.
5104 Example: "Is the bug fixed in your recent commit?"
5106 (Verb) The act of recording changes to a repository. When files
5108 are committed in a working directory, Mercurial finds the dif‐
5109 ferences between the committed files and their parent changeset,
5110 creating a new changeset in the repository.
5111 Example: "You should commit those changes now."
5113 Cset A common abbreviation of the term changeset.
5115 DAG The repository of changesets of a distributed version control
5117 system (DVCS) can be described as a directed acyclic graph
5118 (DAG), consisting of nodes and edges, where nodes correspond to
5119 changesets and edges imply a parent -> child relation. This
5120 graph can be visualized by graphical tools such as hg log
5121 --graph. In Mercurial, the DAG is limited by the requirement for
5122 children to have at most two parents.
5123 Deprecated
5125 Feature removed from documentation, but not scheduled for
5126 removal.
5127 Default branch
5129 See 'Branch, default'.
5130 Descendant
5132 Any changeset that can be reached by a chain of child changesets
5133 from a given changeset. More precisely, the descendants of a
5134 changeset can be defined by two properties: the child of a
5135 changeset is a descendant, and the child of a descendant is a
5136 descendant. See also: 'Ancestor'.
5137 Diff (Noun) The difference between the contents and attributes of
5139 files in two changesets or a changeset and the current working
5140 directory. The difference is usually represented in a standard
5141 form called a "diff" or "patch". The "git diff" format is used
5142 when the changes include copies, renames, or changes to file
5143 attributes, none of which can be represented/handled by classic
5144 "diff" and "patch".
5145 Example: "Did you see my correction in the diff?"
5147 (Verb) Diffing two changesets is the action of creating a diff
5149 or patch.
5150 Example: "If you diff with changeset X, you will see what I
5152 mean."
5153 Directory, working
5155 The working directory represents the state of the files tracked
5156 by Mercurial, that will be recorded in the next commit. The
5157 working directory initially corresponds to the snapshot at an
5158 existing changeset, known as the parent of the working direc‐
5159 tory. See 'Parent, working directory'. The state may be modified
5160 by changes to the files introduced manually or by a merge. The
5161 repository metadata exists in the .hg directory inside the work‐
5162 ing directory.
5163 Draft Changesets in the draft phase have not been shared with publish‐
5165 ing repositories and may thus be safely changed by history-modi‐
5166 fying extensions. See hg help phases.
5167 Experimental
5169 Feature that may change or be removed at a later date.
5170 Graph See DAG and hg log --graph.
5172 Head The term 'head' may be used to refer to both a branch head or a
5174 repository head, depending on the context. See 'Head, branch'
5175 and 'Head, repository' for specific definitions.
5176 Heads are where development generally takes place and are the
5178 usual targets for update and merge operations.
5179 Head, branch
5181 A changeset with no descendants on the same named branch.
5182 Head, closed branch
5184 A changeset that marks a head as no longer interesting. The
5185 closed head is no longer listed by hg heads. A branch is consid‐
5186 ered closed when all its heads are closed and consequently is
5187 not listed by hg branches.
5188 Closed heads can be re-opened by committing new changeset as the
5190 child of the changeset that marks a head as closed.
5191 Head, repository
5193 A topological head which has not been closed.
5194 Head, topological
5196 A changeset with no children in the repository.
5197 History, immutable
5199 Once committed, changesets cannot be altered. Extensions which
5200 appear to change history actually create new changesets that
5201 replace existing ones, and then destroy the old changesets.
5202 Doing so in public repositories can result in old changesets
5203 being reintroduced to the repository.
5204 History, rewriting
5206 The changesets in a repository are immutable. However, exten‐
5207 sions to Mercurial can be used to alter the repository, usually
5208 in such a way as to preserve changeset contents.
5209 Immutable history
5211 See 'History, immutable'.
5212 Merge changeset
5214 See 'Changeset, merge'.
5215 Manifest
5217 Each changeset has a manifest, which is the list of files that
5218 are tracked by the changeset.
5219 Merge Used to bring together divergent branches of work. When you
5221 update to a changeset and then merge another changeset, you
5222 bring the history of the latter changeset into your working
5223 directory. Once conflicts are resolved (and marked), this merge
5224 may be committed as a merge changeset, bringing two branches
5225 together in the DAG.
5226 Named branch
5228 See 'Branch, named'.
5229 Null changeset
5231 The empty changeset. It is the parent state of newly-initialized
5232 repositories and repositories with no checked out revision. It
5233 is thus the parent of root changesets and the effective ancestor
5234 when merging unrelated changesets. Can be specified by the alias
5235 'null' or by the changeset ID '000000000000'.
5236 Parent See 'Changeset, parent'.
5238 Parent changeset
5240 See 'Changeset, parent'.
5241 Parent, working directory
5243 The working directory parent reflects a virtual revision which
5244 is the child of the changeset (or two changesets with an uncom‐
5245 mitted merge) shown by hg parents. This is changed with hg
5246 update. Other commands to see the working directory parent are
5247 hg summary and hg id. Can be specified by the alias ".".
5248 Patch (Noun) The product of a diff operation.
5250 Example: "I've sent you my patch."
5252 (Verb) The process of using a patch file to transform one
5254 changeset into another.
5255 Example: "You will need to patch that revision."
5257 Phase A per-changeset state tracking how the changeset has been or
5259 should be shared. See hg help phases.
5260 Public Changesets in the public phase have been shared with publishing
5262 repositories and are therefore considered immutable. See hg help
5263 phases.
5264 Pull An operation in which changesets in a remote repository which
5266 are not in the local repository are brought into the local
5267 repository. Note that this operation without special arguments
5268 only updates the repository, it does not update the files in the
5269 working directory. See hg help pull.
5270 Push An operation in which changesets in a local repository which are
5272 not in a remote repository are sent to the remote repository.
5273 Note that this operation only adds changesets which have been
5274 committed locally to the remote repository. Uncommitted changes
5275 are not sent. See hg help push.
5276 Repository
5278 The metadata describing all recorded states of a collection of
5279 files. Each recorded state is represented by a changeset. A
5280 repository is usually (but not always) found in the .hg subdi‐
5281 rectory of a working directory. Any recorded state can be recre‐
5282 ated by "updating" a working directory to a specific changeset.
5283 Repository head
5285 See 'Head, repository'.
5286 Revision
5288 A state of the repository at some point in time. Earlier revi‐
5289 sions can be updated to by using hg update. See also 'Revision
5290 number'; See also 'Changeset'.
5291 Revision number
5293 This integer uniquely identifies a changeset in a specific
5294 repository. It represents the order in which changesets were
5295 added to a repository, starting with revision number 0. Note
5296 that the revision number may be different in each clone of a
5297 repository. To identify changesets uniquely between different
5298 clones, see 'Changeset id'.
5299 Revlog History storage mechanism used by Mercurial. It is a form of
5301 delta encoding, with occasional full revision of data followed
5302 by delta of each successive revision. It includes data and an
5303 index pointing to the data.
5304 Rewriting history
5306 See 'History, rewriting'.
5307 Root A changeset that has only the null changeset as its parent. Most
5309 repositories have only a single root changeset.
5310 Secret Changesets in the secret phase may not be shared via push, pull,
5312 or clone. See hg help phases.
5313 Tag An alternative name given to a changeset. Tags can be used in
5315 all places where Mercurial expects a changeset ID, e.g., with hg
5316 update. The creation of a tag is stored in the history and will
5317 thus automatically be shared with other using push and pull.
5318 Tip The changeset with the highest revision number. It is the
5320 changeset most recently added in a repository.
5321 Tip, branch
5323 The head of a given branch with the highest revision number.
5324 When a branch name is used as a revision identifier, it refers
5325 to the branch tip. See also 'Branch, head'. Note that because
5326 revision numbers may be different in different repository
5327 clones, the branch tip may be different in different cloned
5328 repositories.
5329 Update (Noun) Another synonym of changeset.
5331 Example: "I've pushed an update."
5333 (Verb) This term is usually used to describe updating the state
5335 of the working directory to that of a specific changeset. See hg
5336 help update.
5337 Example: "You should update."
5339 Working directory
5341 See 'Directory, working'.
5342 Working directory parent
5344 See 'Parent, working directory'.
5345
5347 Synopsis
5348 The Mercurial system uses a file called .hgignore in the root directory
5349 of a repository to control its behavior when it searches for files that
5350 it is not currently tracking.
5351 Description
5353 The working directory of a Mercurial repository will often contain
5354 files that should not be tracked by Mercurial. These include backup
5355 files created by editors and build products created by compilers.
5356 These files can be ignored by listing them in a .hgignore file in the
5357 root of the working directory. The .hgignore file must be created manu‐
5358 ally. It is typically put under version control, so that the settings
5359 will propagate to other repositories with push and pull.
5360 An untracked file is ignored if its path relative to the repository
5362 root directory, or any prefix path of that path, is matched against any
5363 pattern in .hgignore.
5364 For example, say we have an untracked file, file.c, at a/b/file.c
5366 inside our repository. Mercurial will ignore file.c if any pattern in
5367 .hgignore matches a/b/file.c, a/b or a.
5368 In addition, a Mercurial configuration file can reference a set of
5370 per-user or global ignore files. See the ignore configuration key on
5371 the [ui] section of hg help config for details of how to configure
5372 these files.
5373 To control Mercurial's handling of files that it manages, many commands
5375 support the -I and -X options; see hg help <command> and hg help pat‐
5376 terns for details.
5377 Files that are already tracked are not affected by .hgignore, even if
5379 they appear in .hgignore. An untracked file X can be explicitly added
5380 with hg add X, even if X would be excluded by a pattern in .hgignore.
5381 Syntax
5383 An ignore file is a plain text file consisting of a list of patterns,
5384 with one pattern per line. Empty lines are skipped. The # character is
5385 treated as a comment character, and the \ character is treated as an
5386 escape character.
5387 Mercurial supports several pattern syntaxes. The default syntax used is
5389 Python/Perl-style regular expressions.
5390 To change the syntax used, use a line of the following form:
5392 syntax: NAME
5394 where NAME is one of the following:
5396 regexp
5398 Regular expression, Python/Perl syntax.
5400 glob
5402 Shell-style glob.
5404 rootglob
5406 A variant of glob that is rooted (see below).
5408 The chosen syntax stays in effect when parsing all patterns that fol‐
5410 low, until another syntax is selected.
5411 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
5413 the form *.c will match a file ending in .c in any directory, and a
5414 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
5415 tern, start it with ^. To get the same effect with glob-syntax, you
5416 have to use rootglob.
5417 Subdirectories can have their own .hgignore settings by adding subin‐
5419 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
5420 terns for details on subinclude: and include:.
5421 Note Patterns specified in other than .hgignore are always rooted.
5423 Please see hg help patterns for details.
5424 Example
5426 Here is an example ignore file.
5427 # use glob syntax.
5429 syntax: glob
5430 *.elc
5432 *.pyc
5433 *~
5434 # switch to regexp syntax.
5436 syntax: regexp
5437 ^\.pc/
5438 Debugging
5440 Use the debugignore command to see if and why a file is ignored, or to
5441 see the combined ignore pattern. See hg help debugignore for details.
5442
5444 Mercurial's internal web server, hgweb, can serve either a single
5445 repository, or a tree of repositories. In the second case, repository
5446 paths and global options can be defined using a dedicated configuration
5447 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
5448 This file uses the same syntax as other Mercurial configuration files
5450 but recognizes only the following sections:
5451 · web
5453 · paths
5455 · collections
5457 The web options are thoroughly described in hg help config.
5459 The paths section maps URL paths to paths of repositories in the
5461 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
5462 rial repositories can be published and only according to the configura‐
5463 tion.
5464 The left hand side is the path in the URL. Note that hgweb reserves
5466 subpaths like rev or file, try using different names for nested reposi‐
5467 tories to avoid confusing effects.
5468 The right hand side is the path in the filesystem. If the specified
5470 path ends with * or ** the filesystem will be searched recursively for
5471 repositories below that point. With * it will not recurse into the
5472 repositories it finds (except for .hg/patches). With ** it will also
5473 search inside repository working directories and possibly find sub‐
5474 repositories.
5475 In this example:
5477 [paths]
5479 /projects/a = /srv/tmprepos/a
5480 /projects/b = c:/repos/b
5481 / = /srv/repos/*
5482 /user/bob = /home/bob/repos/**
5483 · The first two entries make two repositories in different directories
5485 appear under the same directory in the web interface
5486 · The third entry will publish every Mercurial repository found in
5488 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
5489 as http://server/quux/
5490 · The fourth entry will publish both http://server/user/bob/quux/ and
5492 http://server/user/bob/quux/testsubrepo/
5493 The collections section is deprecated and has been superseded by paths.
5495 URLs and Common Arguments
5497 URLs under each repository have the form /{command}[/{arguments}] where
5498 {command} represents the name of a command or handler and {arguments}
5499 represents any number of additional URL parameters to that command.
5500 The web server has a default style associated with it. Styles map to a
5502 collection of named templates. Each template is used to render a spe‐
5503 cific piece of data, such as a changeset or diff.
5504 The style for the current request can be overridden two ways. First, if
5506 {command} contains a hyphen (-), the text before the hyphen defines the
5507 style. For example, /atom-log will render the log command handler with
5508 the atom style. The second way to set the style is with the style query
5509 string argument. For example, /log?style=atom. The hyphenated URL
5510 parameter is preferred.
5511 Not all templates are available for all styles. Attempting to use a
5513 style that doesn't have all templates defined may result in an error
5514 rendering the page.
5515 Many commands take a {revision} URL parameter. This defines the change‐
5517 set to operate on. This is commonly specified as the short, 12 digit
5518 hexadecimal abbreviation for the full 40 character unique revision
5519 identifier. However, any value described by hg help revisions typically
5520 works.
5521 Commands and URLs
5523 The following web commands and their URLs are available:
5524 /annotate/{revision}/{path}
5526 Show changeset information for each line in a file.
5527 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
5529 string arguments have the same meaning as their [annotate] config
5530 equivalents. It uses the hgrc boolean parsing logic to interpret the
5531 value. e.g. 0 and false are false and 1 and true are true. If not
5532 defined, the server default settings are used.
5533 The fileannotate template is rendered.
5535 /archive/{revision}.{format}[/{path}]
5537 Obtain an archive of repository content.
5538 The content and type of the archive is defined by a URL path parameter.
5540 format is the file extension of the archive type to be generated. e.g.
5541 zip or tar.bz2. Not all archive types may be allowed by your server
5542 configuration.
5543 The optional path URL parameter controls content to include in the ar‐
5545 chive. If omitted, every file in the specified revision is present in
5546 the archive. If included, only the specified file or contents of the
5547 specified directory will be included in the archive.
5548 No template is used for this handler. Raw, binary content is generated.
5550 /bookmarks
5552 Show information about bookmarks.
5553 No arguments are accepted.
5555 The bookmarks template is rendered.
5557 /branches
5559 Show information about branches.
5560 All known branches are contained in the output, even closed branches.
5562 No arguments are accepted.
5564 The branches template is rendered.
5566 /changelog[/{revision}]
5568 Show information about multiple changesets.
5569 If the optional revision URL argument is absent, information about all
5571 changesets starting at tip will be rendered. If the revision argument
5572 is present, changesets will be shown starting from the specified revi‐
5573 sion.
5574 If revision is absent, the rev query string argument may be defined.
5576 This will perform a search for changesets.
5577 The argument for rev can be a single revision, a revision set, or a
5579 literal keyword to search for in changeset data (equivalent to hg log
5580 -k).
5581 The revcount query string argument defines the maximum numbers of
5583 changesets to render.
5584 For non-searches, the changelog template will be rendered.
5586 /changeset[/{revision}]
5588 Show information about a single changeset.
5589 A URL path argument is the changeset identifier to show. See hg help
5591 revisions for possible values. If not defined, the tip changeset will
5592 be shown.
5593 The changeset template is rendered. Contents of the changesettag,
5595 changesetbookmark, filenodelink, filenolink, and the many templates
5596 related to diffs may all be used to produce the output.
5597 /comparison/{revision}/{path}
5599 Show a comparison between the old and new versions of a file from
5600 changes made on a particular revision.
5601 This is similar to the diff handler. However, this form features a
5603 split or side-by-side diff rather than a unified diff.
5604 The context query string argument can be used to control the lines of
5606 context in the diff.
5607 The filecomparison template is rendered.
5609 /diff/{revision}/{path}
5611 Show how a file changed in a particular commit.
5612 The filediff template is rendered.
5614 This handler is registered under both the /diff and /filediff paths.
5616 /diff is used in modern code.
5617 /file/{revision}[/{path}]
5619 Show information about a directory or file in the repository.
5620 Info about the path given as a URL parameter will be rendered.
5622 If path is a directory, information about the entries in that directory
5624 will be rendered. This form is equivalent to the manifest handler.
5625 If path is a file, information about that file will be shown via the
5627 filerevision template.
5628 If path is not defined, information about the root directory will be
5630 rendered.
5631 /diff/{revision}/{path}
5633 Show how a file changed in a particular commit.
5634 The filediff template is rendered.
5636 This handler is registered under both the /diff and /filediff paths.
5638 /diff is used in modern code.
5639 /filelog/{revision}/{path}
5641 Show information about the history of a file in the repository.
5642 The revcount query string argument can be defined to control the maxi‐
5644 mum number of entries to show.
5645 The filelog template will be rendered.
5647 /graph[/{revision}]
5649 Show information about the graphical topology of the repository.
5650 Information rendered by this handler can be used to create visual rep‐
5652 resentations of repository topology.
5653 The revision URL parameter controls the starting changeset. If it's
5655 absent, the default is tip.
5656 The revcount query string argument can define the number of changesets
5658 to show information for.
5659 The graphtop query string argument can specify the starting changeset
5661 for producing jsdata variable that is used for rendering graph in
5662 JavaScript. By default it has the same value as revision.
5663 This handler will render the graph template.
5665 /help[/{topic}]
5667 Render help documentation.
5668 This web command is roughly equivalent to hg help. If a topic is
5670 defined, that help topic will be rendered. If not, an index of avail‐
5671 able help topics will be rendered.
5672 The help template will be rendered when requesting help for a topic.
5674 helptopics will be rendered for the index of help topics.
5675 /log[/{revision}[/{path}]]
5677 Show repository or file history.
5678 For URLs of the form /log/{revision}, a list of changesets starting at
5680 the specified changeset identifier is shown. If {revision} is not
5681 defined, the default is tip. This form is equivalent to the changelog
5682 handler.
5683 For URLs of the form /log/{revision}/{file}, the history for a specific
5685 file will be shown. This form is equivalent to the filelog handler.
5686 /manifest[/{revision}[/{path}]]
5688 Show information about a directory.
5689 If the URL path arguments are omitted, information about the root
5691 directory for the tip changeset will be shown.
5692 Because this handler can only show information for directories, it is
5694 recommended to use the file handler instead, as it can handle both
5695 directories and files.
5696 The manifest template will be rendered for this handler.
5698 /changeset[/{revision}]
5700 Show information about a single changeset.
5701 A URL path argument is the changeset identifier to show. See hg help
5703 revisions for possible values. If not defined, the tip changeset will
5704 be shown.
5705 The changeset template is rendered. Contents of the changesettag,
5707 changesetbookmark, filenodelink, filenolink, and the many templates
5708 related to diffs may all be used to produce the output.
5709 /shortlog
5711 Show basic information about a set of changesets.
5712 This accepts the same parameters as the changelog handler. The only
5714 difference is the shortlog template will be rendered instead of the
5715 changelog template.
5716 /summary
5718 Show a summary of repository state.
5719 Information about the latest changesets, bookmarks, tags, and branches
5721 is captured by this handler.
5722 The summary template is rendered.
5724 /tags
5726 Show information about tags.
5727 No arguments are accepted.
5729 The tags template is rendered.
5731
5733 To access a subtopic, use "hg help internals.{subtopic-name}"
5734 bundle2
5736 Bundle2
5737 bundles
5739 Bundles
5740 cbor CBOR
5742 censor Censor
5744 changegroups
5746 Changegroups
5747 config Config Registrar
5749 extensions
5751 Extension API
5752 mergestate
5754 Mergestate
5755 requirements
5757 Repository Requirements
5758 revlogs
5760 Revision Logs
5761 wireprotocol
5763 Wire Protocol
5764 wireprotocolrpc
5766 Wire Protocol RPC
5767 wireprotocolv2
5769 Wire Protocol Version 2
5770
5772 To merge files Mercurial uses merge tools.
5773 A merge tool combines two different versions of a file into a merged
5775 file. Merge tools are given the two files and the greatest common
5776 ancestor of the two file versions, so they can determine the changes
5777 made on both branches.
5778 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
5780 out and in several extensions.
5781 Usually, the merge tool tries to automatically reconcile the files by
5783 combining all non-overlapping changes that occurred separately in the
5784 two different evolutions of the same initial base file. Furthermore,
5785 some interactive merge programs make it easier to manually resolve con‐
5786 flicting merges, either in a graphical way, or by inserting some con‐
5787 flict markers. Mercurial does not include any interactive merge pro‐
5788 grams but relies on external tools for that.
5789 Available merge tools
5791 External merge tools and their properties are configured in the
5792 merge-tools configuration section - see hgrc(5) - but they can often
5793 just be named by their executable.
5794 A merge tool is generally usable if its executable can be found on the
5796 system and if it can handle the merge. The executable is found if it is
5797 an absolute or relative executable path or the name of an application
5798 in the executable search path. The tool is assumed to be able to handle
5799 the merge if it can handle symlinks if the file is a symlink, if it can
5800 handle binary files if the file is binary, and if a GUI is available if
5801 the tool requires a GUI.
5802 There are some internal merge tools which can be used. The internal
5804 merge tools are:
5805 :dump
5807 Creates three versions of the files to merge, containing the
5809 contents of local, other and base. These files can then be used
5810 to perform a merge manually. If the file to be merged is named
5811 a.txt, these files will accordingly be named a.txt.local,
5812 a.txt.other and a.txt.base and they will be placed in the same
5813 directory as a.txt.
5814 This implies premerge. Therefore, files aren't dumped, if pre‐
5816 merge runs successfully. Use :forcedump to forcibly write files
5817 out.
5818 (actual capabilities: binary, symlink)
5820 :fail
5822 Rather than attempting to merge files that were modified on both
5824 branches, it marks them as unresolved. The resolve command must
5825 be used to resolve these conflicts.
5826 (actual capabilities: binary, symlink)
5828 :forcedump
5830 Creates three versions of the files as same as :dump, but omits
5832 premerge.
5833 (actual capabilities: binary, symlink)
5835 :local
5837 Uses the local p1() version of files as the merged version.
5839 (actual capabilities: binary, symlink)
5841 :merge
5843 Uses the internal non-interactive simple merge algorithm for
5845 merging files. It will fail if there are any conflicts and leave
5846 markers in the partially merged file. Markers will have two sec‐
5847 tions, one for each side of merge.
5848 :merge-local
5850 Like :merge, but resolve all conflicts non-interactively in
5852 favor of the local p1() changes.
5853 :merge-other
5855 Like :merge, but resolve all conflicts non-interactively in
5857 favor of the other p2() changes.
5858 :merge3
5860 Uses the internal non-interactive simple merge algorithm for
5862 merging files. It will fail if there are any conflicts and leave
5863 markers in the partially merged file. Marker will have three
5864 sections, one from each side of the merge and one for the base
5865 content.
5866 :other
5868 Uses the other p2() version of files as the merged version.
5870 (actual capabilities: binary, symlink)
5872 :prompt
5874 Asks the user which of the local p1() or the other p2() version
5876 to keep as the merged version.
5877 (actual capabilities: binary, symlink)
5879 :tagmerge
5881 Uses the internal tag merge algorithm (experimental).
5883 :union
5885 Uses the internal non-interactive simple merge algorithm for
5887 merging files. It will use both left and right sides for con‐
5888 flict regions. No markers are inserted.
5889 Internal tools are always available and do not require a GUI but will
5891 by default not handle symlinks or binary files. See next section for
5892 detail about "actual capabilities" described above.
5893 Choosing a merge tool
5895 Mercurial uses these rules when deciding which merge tool to use:
5896 1. If a tool has been specified with the --tool option to merge or
5898 resolve, it is used. If it is the name of a tool in the merge-tools
5899 configuration, its configuration is used. Otherwise the specified
5900 tool must be executable by the shell.
5901 2. If the HGMERGE environment variable is present, its value is used
5903 and must be executable by the shell.
5904 3. If the filename of the file to be merged matches any of the patterns
5906 in the merge-patterns configuration section, the first usable merge
5907 tool corresponding to a matching pattern is used.
5908 4. If ui.merge is set it will be considered next. If the value is not
5910 the name of a configured tool, the specified value is used and must
5911 be executable by the shell. Otherwise the named tool is used if it
5912 is usable.
5913 5. If any usable merge tools are present in the merge-tools configura‐
5915 tion section, the one with the highest priority is used.
5916 6. If a program named hgmerge can be found on the system, it is used -
5918 but it will by default not be used for symlinks and binary files.
5919 7. If the file to be merged is not binary and is not a symlink, then
5921 internal :merge is used.
5922 8. Otherwise, :prompt is used.
5924 For historical reason, Mercurial treats merge tools as below while
5926 examining rules above.
5927 ┌───────────┬────────────────┬────────┬─────────┐
5929 │step │ specified via │ binary │ symlink │
5930 ├───────────┼────────────────┼────────┼─────────┤
5931 │ │ --tool │ o/o │ o/o │
5932 │ 1. │ │ │ │
5933 ├───────────┼────────────────┼────────┼─────────┤
5934 │ │ HGMERGE │ o/o │ o/o │
5935 │ 2. │ │ │ │
5936 ├───────────┼────────────────┼────────┼─────────┤
5937 │ │ merge-patterns │ o/o(*) │ x/?(*) │
5938 │ 3. │ │ │ │
5939 ├───────────┼────────────────┼────────┼─────────┤
5940 │ │ ui.merge │ x/?(*) │ x/?(*) │
5941 │ 4. │ │ │ │
5942 └───────────┴────────────────┴────────┴─────────┘
5943 Each capability column indicates Mercurial behavior for internal/exter‐
5945 nal merge tools at examining each rule.
5946 · "o": "assume that a tool has capability"
5948 · "x": "assume that a tool does not have capability"
5950 · "?": "check actual capability of a tool"
5952 If merge.strict-capability-check configuration is true, Mercurial
5954 checks capabilities of merge tools strictly in (*) cases above (= each
5955 capability column becomes "?/?"). It is false by default for backward
5956 compatibility.
5957 Note After selecting a merge program, Mercurial will by default
5959 attempt to merge the files using a simple merge algorithm first.
5960 Only if it doesn't succeed because of conflicting changes will
5961 Mercurial actually execute the merge program. Whether to use the
5962 simple merge algorithm first can be controlled by the premerge
5963 setting of the merge tool. Premerge is enabled by default unless
5964 the file is binary or a symlink.
5965 See the merge-tools and ui sections of hgrc(5) for details on the con‐
5967 figuration of merge tools.
5968
5970 Some Mercurial commands can produce a lot of output, and Mercurial will
5971 attempt to use a pager to make those commands more pleasant.
5972 To set the pager that should be used, set the application variable:
5974 [pager]
5976 pager = less -FRX
5977 If no pager is set in the user or repository configuration, Mercurial
5979 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
5980 from the default or system configuration is used. If none of these are
5981 set, a default pager will be used, typically less on Unix and more on
5982 Windows.
5983 On Windows, more is not color aware, so using it effectively disables
5985 color. MSYS and Cygwin shells provide less as a pager, which can be
5986 configured to support ANSI color codes. See hg help con‐
5987 fig.color.pagermode to configure the color mode when invoking a pager.
5988 You can disable the pager for certain commands by adding them to the
5990 pager.ignore list:
5991 [pager]
5993 ignore = version, help, update
5994 To ignore global commands like hg version or hg help, you have to spec‐
5996 ify them in your user configuration file.
5997 To control whether the pager is used at all for an individual command,
5999 you can use --pager=<value>:
6000 · use as needed: auto.
6002 · require the pager: yes or on.
6004 · suppress the pager: no or off (any unrecognized value will also
6006 work).
6007 To globally turn off all attempts to use a pager, set:
6009 [ui]
6011 paginate = never
6012 which will prevent the pager from running.
6014
6016 Mercurial accepts several notations for identifying one or more files
6017 at a time.
6018 By default, Mercurial treats filenames as shell-style extended glob
6020 patterns.
6021 Alternate pattern notations must be specified explicitly.
6023 Note Patterns specified in .hgignore are not rooted. Please see hg
6025 help hgignore for details.
6026 To use a plain path name without any pattern matching, start it with
6028 path:. These path names must completely match starting at the current
6029 repository root, and when the path points to a directory, it is matched
6030 recursively. To match all files in a directory non-recursively (not
6031 including any files in subdirectories), rootfilesin: can be used, spec‐
6032 ifying an absolute path (relative to the repository root).
6033 To use an extended glob, start a name with glob:. Globs are rooted at
6035 the current directory; a glob such as *.c will only match files in the
6036 current directory ending with .c. rootglob: can be used instead of
6037 glob: for a glob that is rooted at the root of the repository.
6038 The supported glob syntax extensions are ** to match any string across
6040 path separators and {a,b} to mean "a or b".
6041 To use a Perl/Python regular expression, start a name with re:. Regexp
6043 pattern matching is anchored at the root of the repository.
6044 To read name patterns from a file, use listfile: or listfile0:. The
6046 latter expects null delimited patterns while the former expects line
6047 feeds. Each string read from the file is itself treated as a file pat‐
6048 tern.
6049 To read a set of patterns from a file, use include: or subinclude:.
6051 include: will use all the patterns from the given file and treat them
6052 as if they had been passed in manually. subinclude: will only apply
6053 the patterns against files that are under the subinclude file's direc‐
6054 tory. See hg help hgignore for details on the format of these files.
6055 All patterns, except for glob: specified in command line (not for -I or
6057 -X options), can match also against directories: files under matched
6058 directories are treated as matched. For -I and -X options, glob: will
6059 match directories recursively.
6060 Plain examples:
6062 path:foo/bar a name bar in a directory named foo in the root
6064 of the repository
6065 path:path:name a file or directory named "path:name"
6066 rootfilesin:foo/bar the files in a directory called foo/bar, but not any files
6067 in its subdirectories and not a file bar in directory foo
6068 Glob examples:
6070 glob:*.c any name ending in ".c" in the current directory
6072 *.c any name ending in ".c" in the current directory
6073 **.c any name ending in ".c" in any subdirectory of the
6074 current directory including itself.
6075 foo/* any file in directory foo
6076 foo/** any file in directory foo plus all its subdirectories,
6077 recursively
6078 foo/*.c any name ending in ".c" in the directory foo
6079 foo/**.c any name ending in ".c" in any subdirectory of foo
6080 including itself.
6081 rootglob:*.c any name ending in ".c" in the root of the repository
6082 Regexp examples:
6084 re:.*\.c$ any name ending in ".c", anywhere in the repository
6086 File examples:
6088 listfile:list.txt read list from list.txt with one file pattern per line
6090 listfile0:list.txt read list from list.txt with null byte delimiters
6091 See also hg help filesets.
6093 Include examples:
6095 include:path/to/mypatternfile reads patterns to be applied to all paths
6097 subinclude:path/to/subignorefile reads patterns specifically for paths in the
6098 subdirectory
6099
6101 What are phases?
6102 Phases are a system for tracking which changesets have been or should
6103 be shared. This helps prevent common mistakes when modifying history
6104 (for instance, with the mq or rebase extensions).
6105 Each changeset in a repository is in one of the following phases:
6107 · public : changeset is visible on a public server
6109 · draft : changeset is not yet published
6111 · secret : changeset should not be pushed, pulled, or cloned
6113 These phases are ordered (public < draft < secret) and no changeset can
6115 be in a lower phase than its ancestors. For instance, if a changeset is
6116 public, all its ancestors are also public. Lastly, changeset phases
6117 should only be changed towards the public phase.
6118 How are phases managed?
6120 For the most part, phases should work transparently. By default, a
6121 changeset is created in the draft phase and is moved into the public
6122 phase when it is pushed to another repository.
6123 Once changesets become public, extensions like mq and rebase will
6125 refuse to operate on them to prevent creating duplicate changesets.
6126 Phases can also be manually manipulated with the hg phase command if
6127 needed. See hg help -v phase for examples.
6128 To make your commits secret by default, put this in your configuration
6130 file:
6131 [phases]
6133 new-commit = secret
6134 Phases and servers
6136 Normally, all servers are publishing by default. This means:
6137 - all draft changesets that are pulled or cloned appear in phase
6139 public on the client
6140 - all draft changesets that are pushed appear as public on both
6142 client and server
6143 - secret changesets are neither pushed, pulled, or cloned
6145 Note Pulling a draft changeset from a publishing server does not mark
6147 it as public on the server side due to the read-only nature of
6148 pull.
6149 Sometimes it may be desirable to push and pull changesets in the draft
6151 phase to share unfinished work. This can be done by setting a reposi‐
6152 tory to disable publishing in its configuration file:
6153 [phases]
6155 publish = False
6156 See hg help config for more information on configuration files.
6158 Note Servers running older versions of Mercurial are treated as pub‐
6160 lishing.
6161 Note Changesets in secret phase are not exchanged with the server.
6163 This applies to their content: file names, file contents, and
6164 changeset metadata. For technical reasons, the identifier (e.g.
6165 d825e4025e39) of the secret changeset may be communicated to the
6166 server.
6167 Examples
6169 · list changesets in draft or secret phase:
6170 hg log -r "not public()"
6172 · change all secret changesets to draft:
6174 hg phase --draft "secret()"
6176 · forcibly move the current changeset and descendants from public to
6178 draft:
6179 hg phase --force --draft .
6181 · show a list of changeset revisions and each corresponding phase:
6183 hg log --template "{rev} {phase}\n"
6185 · resynchronize draft changesets relative to a remote repository:
6187 hg phase -fd "outgoing(URL)"
6189 See hg help phase for more information on manually manipulating phases.
6191
6193 Mercurial supports several ways to specify revisions.
6194 Specifying single revisions
6196 A plain integer is treated as a revision number. Negative integers are
6197 treated as sequential offsets from the tip, with -1 denoting the tip,
6198 -2 denoting the revision prior to the tip, and so forth.
6199 A 40-digit hexadecimal string is treated as a unique revision identi‐
6201 fier. A hexadecimal string less than 40 characters long is treated as
6202 a unique revision identifier and is referred to as a short-form identi‐
6203 fier. A short-form identifier is only valid if it is the prefix of
6204 exactly one full-length identifier.
6205 Any other string is treated as a bookmark, tag, or branch name. A book‐
6207 mark is a movable pointer to a revision. A tag is a permanent name
6208 associated with a revision. A branch name denotes the tipmost open
6209 branch head of that branch - or if they are all closed, the tipmost
6210 closed head of the branch. Bookmark, tag, and branch names must not
6211 contain the ":" character.
6212 The reserved name "tip" always identifies the most recent revision.
6214 The reserved name "null" indicates the null revision. This is the revi‐
6216 sion of an empty repository, and the parent of revision 0.
6217 The reserved name "." indicates the working directory parent. If no
6219 working directory is checked out, it is equivalent to null. If an
6220 uncommitted merge is in progress, "." is the revision of the first par‐
6221 ent.
6222 Finally, commands that expect a single revision (like hg update) also
6224 accept revsets (see below for details). When given a revset, they use
6225 the last revision of the revset. A few commands accept two single revi‐
6226 sions (like hg diff). When given a revset, they use the first and the
6227 last revisions of the revset.
6228 Specifying multiple revisions
6230 Mercurial supports a functional language for selecting a set of revi‐
6231 sions. Expressions in this language are called revsets.
6232 The language supports a number of predicates which are joined by infix
6234 operators. Parenthesis can be used for grouping.
6235 Identifiers such as branch names may need quoting with single or double
6237 quotes if they contain characters like - or if they match one of the
6238 predefined predicates.
6239 Special characters can be used in quoted identifiers by escaping them,
6241 e.g., \n is interpreted as a newline. To prevent them from being inter‐
6242 preted, strings can be prefixed with r, e.g. r'...'.
6243 Operators
6245 There is a single prefix operator:
6246 not x
6248 Changesets not in x. Short form is ! x.
6250 These are the supported infix operators:
6252 x::y
6254 A DAG range, meaning all changesets that are descendants of x
6256 and ancestors of y, including x and y themselves. If the first
6257 endpoint is left out, this is equivalent to ancestors(y), if the
6258 second is left out it is equivalent to descendants(x).
6259 An alternative syntax is x..y.
6261 x:y
6263 All changesets with revision numbers between x and y, both
6265 inclusive. Either endpoint can be left out, they default to 0
6266 and tip.
6267 x and y
6269 The intersection of changesets in x and y. Short form is x & y.
6271 x or y
6273 The union of changesets in x and y. There are two alternative
6275 short forms: x | y and x + y.
6276 x - y
6278 Changesets in x but not in y.
6280 x % y
6282 Changesets that are ancestors of x but not ancestors of y (i.e.
6284 ::x - ::y). This is shorthand notation for only(x, y) (see
6285 below). The second argument is optional and, if left out, is
6286 equivalent to only(x).
6287 x^n
6289 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
6291 1, the first parent of each changeset in x; for n == 2, the sec‐
6292 ond parent of changeset in x.
6293 x~n
6295 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
6297 the nth unambiguous descendent of x.
6298 x ## y
6300 Concatenate strings and identifiers into one string.
6302 All other prefix, infix and postfix operators have lower prior‐
6304 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
6305 a2)~2.
6306 For example:
6308 [revsetalias]
6310 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
6311 issue(1234) is equivalent to grep(r'\bissue[
6313 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
6314 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
6315 There is a single postfix operator:
6317 x^
6319 Equivalent to x^1, the first parent of each changeset in x.
6321 Patterns
6323 Where noted, predicates that perform string matching can accept a pat‐
6324 tern string. The pattern may be either a literal, or a regular expres‐
6325 sion. If the pattern starts with re:, the remainder of the pattern is
6326 treated as a regular expression. Otherwise, it is treated as a literal.
6327 To match a pattern that actually starts with re:, use the prefix lit‐
6328 eral:.
6329 Matching is case-sensitive, unless otherwise noted. To perform a case-
6331 insensitive match on a case-sensitive predicate, use a regular expres‐
6332 sion, prefixed with (?i).
6333 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
6335 "Release", etc.
6336 Predicates
6338 The following predicates are supported:
6339 adds(pattern)
6341 Changesets that add a file matching pattern.
6343 The pattern without explicit kind like glob: is expected to be
6345 relative to the current directory and match against a file or a
6346 directory.
6347 all()
6349 All changesets, the same as 0:tip.
6351 ancestor(*changeset)
6353 A greatest common ancestor of the changesets.
6355 Accepts 0 or more changesets. Will return empty list when
6357 passed no args. Greatest common ancestor of a single changeset
6358 is that changeset.
6359 ancestors(set[, depth])
6361 Changesets that are ancestors of changesets in set, including
6363 the given changesets themselves.
6364 If depth is specified, the result only includes changesets up to
6366 the specified generation.
6367 author(string)
6369 Alias for user(string).
6371 bisect(string)
6373 Changesets marked in the specified bisect status:
6375 · good, bad, skip: csets explicitly marked as good/bad/skip
6377 · goods, bads : csets topologically good/bad
6379 · range : csets taking part in the bisection
6381 · pruned : csets that are goods, bads or skipped
6383 · untested : csets whose fate is yet unknown
6385 · ignored : csets ignored due to DAG topology
6387 · current : the cset currently being bisected
6389 bookmark([name])
6391 The named bookmark or all bookmarks.
6393 Pattern matching is supported for name. See hg help revi‐
6395 sions.patterns.
6396 branch(string or set)
6398 All changesets belonging to the given branch or the branches of
6400 the given changesets.
6401 Pattern matching is supported for string. See hg help revi‐
6403 sions.patterns.
6404 branchpoint()
6406 Changesets with more than one child.
6408 bundle()
6410 Changesets in the bundle.
6412 Bundle must be specified by the -R option.
6414 children(set)
6416 Child changesets of changesets in set.
6418 closed()
6420 Changeset is closed.
6422 commonancestors(set)
6424 Changesets that are ancestors of every changeset in set.
6426 conflictlocal()
6428 The local side of the merge, if currently in an unresolved
6430 merge.
6431 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6433 'hg graft'.
6434 conflictother()
6436 The other side of the merge, if currently in an unresolved
6438 merge.
6439 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6441 'hg graft'.
6442 contains(pattern)
6444 The revision's manifest contains a file matching pattern (but
6446 might not modify it). See hg help patterns for information about
6447 file patterns.
6448 The pattern without explicit kind like glob: is expected to be
6450 relative to the current directory and match against a file
6451 exactly for efficiency.
6452 converted([id])
6454 Changesets converted from the given identifier in the old repos‐
6456 itory if present, or all converted changesets if no identifier
6457 is specified.
6458 date(interval)
6460 Changesets within the interval, see hg help dates.
6462 desc(string)
6464 Search commit message for string. The match is case-insensitive.
6466 Pattern matching is supported for string. See hg help revi‐
6468 sions.patterns.
6469 descendants(set[, depth])
6471 Changesets which are descendants of changesets in set, including
6473 the given changesets themselves.
6474 If depth is specified, the result only includes changesets up to
6476 the specified generation.
6477 destination([set])
6479 Changesets that were created by a graft, transplant or rebase
6481 operation, with the given revisions specified as the source.
6482 Omitting the optional set is the same as passing all().
6483 draft()
6485 Changeset in draft phase.
6487 expectsize(set[, size])
6489 Return the given revset if size matches the revset size. Abort
6491 if the revset doesn't expect given size. size can either be an
6492 integer range or an integer.
6493 For example, expectsize(0:1, 3:5) will abort as revset size is 2
6495 and 2 is not between 3 and 5 inclusive.
6496 extra(label, [value])
6498 Changesets with the given label in the extra metadata, with the
6500 given optional value.
6501 Pattern matching is supported for value. See hg help revi‐
6503 sions.patterns.
6504 file(pattern)
6506 Changesets affecting files matched by pattern.
6508 For a faster but less accurate result, consider using filelog()
6510 instead.
6511 This predicate uses glob: as the default kind of pattern.
6513 filelog(pattern)
6515 Changesets connected to the specified filelog.
6517 For performance reasons, visits only revisions mentioned in the
6519 file-level filelog, rather than filtering through all changesets
6520 (much faster, but doesn't include deletes or duplicate changes).
6521 For a slower, more accurate result, use file().
6522 The pattern without explicit kind like glob: is expected to be
6524 relative to the current directory and match against a file
6525 exactly for efficiency.
6526 first(set, [n])
6528 An alias for limit().
6530 follow([file[, startrev]])
6532 An alias for ::. (ancestors of the working directory's first
6534 parent). If file pattern is specified, the histories of files
6535 matching given pattern in the revision given by startrev are
6536 followed, including copies.
6537 followlines(file, fromline:toline[, startrev=., descend=False])
6539 Changesets modifying file in line range ('fromline', 'toline').
6541 Line range corresponds to 'file' content at 'startrev' and
6543 should hence be consistent with file size. If startrev is not
6544 specified, working directory's parent is used.
6545 By default, ancestors of 'startrev' are returned. If 'descend'
6547 is True, descendants of 'startrev' are returned though renames
6548 are (currently) not followed in this direction.
6549 grep(regex)
6551 Like keyword(string) but accepts a regex. Use grep(r'...') to
6553 ensure special escape characters are handled correctly. Unlike
6554 keyword(string), the match is case-sensitive.
6555 head()
6557 Changeset is a named branch head.
6559 heads(set)
6561 Members of set with no children in set.
6563 hidden()
6565 Hidden changesets.
6567 id(string)
6569 Revision non-ambiguously specified by the given hex string pre‐
6571 fix.
6572 keyword(string)
6574 Search commit message, user name, and names of changed files for
6576 string. The match is case-insensitive.
6577 For a regular expression or case sensitive search of these
6579 fields, use grep(regex).
6580 last(set, [n])
6582 Last n members of set, defaulting to 1.
6584 limit(set[, n[, offset]])
6586 First n members of set, defaulting to 1, starting from offset.
6588 matching(revision [, field])
6590 Changesets in which a given set of fields match the set of
6592 fields in the selected revision or set.
6593 To match more than one field pass the list of fields to match
6595 separated by spaces (e.g. author description).
6596 Valid fields are most regular revision fields and some special
6598 fields.
6599 Regular revision fields are description, author, branch, date,
6601 files, phase, parents, substate, user and diff. Note that
6602 author and user are synonyms. diff refers to the contents of the
6603 revision. Two revisions matching their diff will also match
6604 their files.
6605 Special fields are summary and metadata: summary matches the
6607 first line of the description. metadata is equivalent to match‐
6608 ing description user date (i.e. it matches the main metadata
6609 fields).
6610 metadata is the default field which is used when no fields are
6612 specified. You can match more than one field at a time.
6613 max(set)
6615 Changeset with highest revision number in set.
6617 merge()
6619 Changeset is a merge changeset.
6621 min(set)
6623 Changeset with lowest revision number in set.
6625 modifies(pattern)
6627 Changesets modifying files matched by pattern.
6629 The pattern without explicit kind like glob: is expected to be
6631 relative to the current directory and match against a file or a
6632 directory.
6633 named(namespace)
6635 The changesets in a given namespace.
6637 Pattern matching is supported for namespace. See hg help revi‐
6639 sions.patterns.
6640 none()
6642 No changesets.
6644 only(set, [set])
6646 Changesets that are ancestors of the first set that are not
6648 ancestors of any other head in the repo. If a second set is
6649 specified, the result is ancestors of the first set that are not
6650 ancestors of the second set (i.e. ::<set1> - ::<set2>).
6651 origin([set])
6653 Changesets that were specified as a source for the grafts,
6655 transplants or rebases that created the given revisions. Omit‐
6656 ting the optional set is the same as passing all(). If a
6657 changeset created by these operations is itself specified as a
6658 source for one of these operations, only the source changeset
6659 for the first operation is selected.
6660 outgoing([path])
6662 Changesets not found in the specified destination repository, or
6664 the default push location.
6665 p1([set])
6667 First parent of changesets in set, or the working directory.
6669 p2([set])
6671 Second parent of changesets in set, or the working directory.
6673 parents([set])
6675 The set of all parents for all changesets in set, or the working
6677 directory.
6678 present(set)
6680 An empty set, if any revision in set isn't found; otherwise, all
6682 revisions in set.
6683 If any of specified revisions is not present in the local repos‐
6685 itory, the query is normally aborted. But this predicate allows
6686 the query to continue even in such cases.
6687 public()
6689 Changeset in public phase.
6691 remote([id [,path]])
6693 Local revision that corresponds to the given identifier in a
6695 remote repository, if present. Here, the '.' identifier is a
6696 synonym for the current local branch.
6697 removes(pattern)
6699 Changesets which remove files matching pattern.
6701 The pattern without explicit kind like glob: is expected to be
6703 relative to the current directory and match against a file or a
6704 directory.
6705 rev(number)
6707 Revision with the given numeric identifier.
6709 reverse(set)
6711 Reverse order of set.
6713 revset(set)
6715 Strictly interpret the content as a revset.
6717 The content of this special predicate will be strictly inter‐
6719 preted as a revset. For example, revset(id(0)) will be inter‐
6720 preted as "id(0)" without possible ambiguity with a "id(0)"
6721 bookmark or tag.
6722 roots(set)
6724 Changesets in set with no parent changeset in set.
6726 secret()
6728 Changeset in secret phase.
6730 sort(set[, [-]key... [, ...]])
6732 Sort set by keys. The default sort order is ascending, specify a
6734 key as -key to sort in descending order.
6735 The keys can be:
6737 · rev for the revision number,
6739 · branch for the branch name,
6741 · desc for the commit message (description),
6743 · user for user name (author can be used as an alias),
6745 · date for the commit date
6747 · topo for a reverse topographical sort
6749 The topo sort order cannot be combined with other sort keys.
6751 This sort takes one optional argument, topo.firstbranch, which
6752 takes a revset that specifies what topographical branches to
6753 prioritize in the sort.
6754 subrepo([pattern])
6756 Changesets that add, modify or remove the given subrepo. If no
6758 subrepo pattern is named, any subrepo changes are returned.
6759 tag([name])
6761 The specified tag by name, or all tagged revisions if no name is
6763 given.
6764 Pattern matching is supported for name. See hg help revi‐
6766 sions.patterns.
6767 user(string)
6769 User name contains string. The match is case-insensitive.
6771 Pattern matching is supported for string. See hg help revi‐
6773 sions.patterns.
6774 Aliases
6776 New predicates (known as "aliases") can be defined, using any combina‐
6777 tion of existing predicates or other aliases. An alias definition looks
6778 like:
6779 <alias> = <definition>
6781 in the revsetalias section of a Mercurial configuration file. Arguments
6783 of the form a1, a2, etc. are substituted from the alias into the defi‐
6784 nition.
6785 For example,
6787 [revsetalias]
6789 h = heads()
6790 d(s) = sort(s, date)
6791 rs(s, k) = reverse(sort(s, k))
6792 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
6794 equivalent to reverse(sort(0:tip, author)).
6795 Equivalents
6797 Command line equivalents for hg log:
6798 -f -> ::.
6800 -d x -> date(x)
6801 -k x -> keyword(x)
6802 -m -> merge()
6803 -u x -> user(x)
6804 -b x -> branch(x)
6805 -P x -> !::x
6806 -l x -> limit(expr, x)
6807 Examples
6809 Some sample queries:
6810 · Changesets on the default branch:
6812 hg log -r "branch(default)"
6814 · Changesets on the default branch since tag 1.5 (excluding merges):
6816 hg log -r "branch(default) and 1.5:: and not merge()"
6818 · Open branch heads:
6820 hg log -r "head() and not closed()"
6822 · Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
6824 hgext/*:
6825 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
6827 · Changesets committed in May 2008, sorted by user:
6829 hg log -r "sort(date('May 2008'), user)"
6831 · Changesets mentioning "bug" or "issue" that are not in a tagged
6833 release:
6834 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
6836 · Update to the commit that bookmark @ is pointing to, without activat‐
6838 ing the bookmark (this works because the last revision of the revset
6839 is used):
6840 hg update :@
6842 · Show diff between tags 1.3 and 1.5 (this works because the first and
6844 the last revisions of the revset are used):
6845 hg diff -r 1.3::1.5
6847
6849 It is common for machines (as opposed to humans) to consume Mercurial.
6850 This help topic describes some of the considerations for interfacing
6851 machines with Mercurial.
6852 Choosing an Interface
6854 Machines have a choice of several methods to interface with Mercurial.
6855 These include:
6856 · Executing the hg process
6858 · Querying a HTTP server
6860 · Calling out to a command server
6862 Executing hg processes is very similar to how humans interact with Mer‐
6864 curial in the shell. It should already be familiar to you.
6865 hg serve can be used to start a server. By default, this will start a
6867 "hgweb" HTTP server. This HTTP server has support for machine-readable
6868 output, such as JSON. For more, see hg help hgweb.
6869 hg serve can also start a "command server." Clients can connect to this
6871 server and issue Mercurial commands over a special protocol. For more
6872 details on the command server, including links to client libraries, see
6873 https://www.mercurial-scm.org/wiki/CommandServer.
6874 hg serve based interfaces (the hgweb and command servers) have the
6876 advantage over simple hg process invocations in that they are likely
6877 more efficient. This is because there is significant overhead to spawn
6878 new Python processes.
6879 Tip If you need to invoke several hg processes in short order and/or
6881 performance is important to you, use of a server-based interface
6882 is highly recommended.
6883 Environment Variables
6885 As documented in hg help environment, various environment variables
6886 influence the operation of Mercurial. The following are particularly
6887 relevant for machines consuming Mercurial:
6888 HGPLAIN
6890 If not set, Mercurial's output could be influenced by configura‐
6891 tion settings that impact its encoding, verbose mode, localiza‐
6892 tion, etc.
6893 It is highly recommended for machines to set this variable when
6895 invoking hg processes.
6896 HGENCODING
6898 If not set, the locale used by Mercurial will be detected from
6899 the environment. If the determined locale does not support dis‐
6900 play of certain characters, Mercurial may render these character
6901 sequences incorrectly (often by using "?" as a placeholder for
6902 invalid characters in the current locale).
6903 Explicitly setting this environment variable is a good practice
6905 to guarantee consistent results. "utf-8" is a good choice on
6906 UNIX-like environments.
6907 HGRCPATH
6909 If not set, Mercurial will inherit config options from config
6910 files using the process described in hg help config. This
6911 includes inheriting user or system-wide config files.
6912 When utmost control over the Mercurial configuration is desired,
6914 the value of HGRCPATH can be set to an explicit file with known
6915 good configs. In rare cases, the value can be set to an empty
6916 file or the null device (often /dev/null) to bypass loading of
6917 any user or system config files. Note that these approaches can
6918 have unintended consequences, as the user and system config
6919 files often define things like the username and extensions that
6920 may be required to interface with a repository.
6921 HGRCSKIPREPO
6923 When set, the .hg/hgrc from repositories are not read.
6924 Note that not reading the repository's configuration can have
6926 unintended consequences, as the repository config files can
6927 define things like extensions that are required for access to
6928 the repository.
6929 Command-line Flags
6931 Mercurial's default command-line parser is designed for humans, and is
6932 not robust against malicious input. For instance, you can start a
6933 debugger by passing --debugger as an option value:
6934 $ REV=--debugger sh -c 'hg log -r "$REV"'
6936 This happens because several command-line flags need to be scanned
6938 without using a concrete command table, which may be modified while
6939 loading repository settings and extensions.
6940 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
6942 setting HGPLAIN=+strictflags. When this feature is enabled, all early
6943 options (e.g. -R/--repository, --cwd, --config) must be specified first
6944 amongst the other global options, and cannot be injected to an arbi‐
6945 trary location:
6946 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
6948 In earlier Mercurial versions where +strictflags isn't available, you
6950 can mitigate the issue by concatenating an option value with its flag:
6951 $ hg log -r"$REV" --keyword="$KEYWORD"
6953 Consuming Command Output
6955 It is common for machines to need to parse the output of Mercurial com‐
6956 mands for relevant data. This section describes the various techniques
6957 for doing so.
6958 Parsing Raw Command Output
6960 Likely the simplest and most effective solution for consuming command
6961 output is to simply invoke hg commands as you would as a user and parse
6962 their output.
6963 The output of many commands can easily be parsed with tools like grep,
6965 sed, and awk.
6966 A potential downside with parsing command output is that the output of
6968 commands can change when Mercurial is upgraded. While Mercurial does
6969 generally strive for strong backwards compatibility, command output
6970 does occasionally change. Having tests for your automated interactions
6971 with hg commands is generally recommended, but is even more important
6972 when raw command output parsing is involved.
6973 Using Templates to Control Output
6975 Many hg commands support templatized output via the -T/--template argu‐
6976 ment. For more, see hg help templates.
6977 Templates are useful for explicitly controlling output so that you get
6979 exactly the data you want formatted how you want it. For example, log
6980 -T {node}\n can be used to print a newline delimited list of changeset
6981 nodes instead of a human-tailored output containing authors, dates,
6982 descriptions, etc.
6983 Tip If parsing raw command output is too complicated, consider using
6985 templates to make your life easier.
6986 The -T/--template argument allows specifying pre-defined styles. Mer‐
6988 curial ships with the machine-readable styles cbor, json, and xml,
6989 which provide CBOR, JSON, and XML output, respectively. These are use‐
6990 ful for producing output that is machine readable as-is.
6991 (Mercurial 5.0 is required for CBOR style.)
6993 Important
6995 The json and xml styles are considered experimental. While they
6996 may be attractive to use for easily obtaining machine-readable
6997 output, their behavior may change in subsequent versions.
6998 These styles may also exhibit unexpected results when dealing
7000 with certain encodings. Mercurial treats things like filenames
7001 as a series of bytes and normalizing certain byte sequences to
7002 JSON or XML with certain encoding settings can lead to sur‐
7003 prises.
7004 Command Server Output
7006 If using the command server to interact with Mercurial, you are likely
7007 using an existing library/API that abstracts implementation details of
7008 the command server. If so, this interface layer may perform parsing for
7009 you, saving you the work of implementing it yourself.
7010 Output Verbosity
7012 Commands often have varying output verbosity, even when machine read‐
7013 able styles are being used (e.g. -T json). Adding -v/--verbose and
7014 --debug to the command's arguments can increase the amount of data
7015 exposed by Mercurial.
7016 An alternate way to get the data you need is by explicitly specifying a
7018 template.
7019 Other Topics
7021 revsets
7022 Revisions sets is a functional query language for selecting a
7023 set of revisions. Think of it as SQL for Mercurial repositories.
7024 Revsets are useful for querying repositories for specific data.
7025 See hg help revsets for more.
7027 share extension
7029 The share extension provides functionality for sharing reposi‐
7030 tory data across several working copies. It can even automati‐
7031 cally "pool" storage for logically related repositories when
7032 cloning.
7033 Configuring the share extension can lead to significant resource
7035 utilization reduction, particularly around disk space and the
7036 network. This is especially true for continuous integration (CI)
7037 environments.
7038 See hg help -e share for more.
7040
7042 Subrepositories let you nest external repositories or projects into a
7043 parent Mercurial repository, and make commands operate on them as a
7044 group.
7045 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
7047 tories.
7048 Subrepositories are made of three components:
7050 1. Nested repository checkouts. They can appear anywhere in the parent
7052 working directory.
7053 2. Nested repository references. They are defined in .hgsub, which
7055 should be placed in the root of working directory, and tell where
7056 the subrepository checkouts come from. Mercurial subrepositories are
7057 referenced like:
7058 path/to/nested = https://example.com/nested/repo/path
7060 Git and Subversion subrepos are also supported:
7062 path/to/nested = [git]git://example.com/nested/repo/path
7064 path/to/nested = [svn]https://example.com/nested/trunk/path
7065 where path/to/nested is the checkout location relatively to the par‐
7067 ent Mercurial root, and https://example.com/nested/repo/path is the
7068 source repository path. The source can also reference a filesystem
7069 path.
7070 Note that .hgsub does not exist by default in Mercurial reposito‐
7072 ries, you have to create and add it to the parent repository before
7073 using subrepositories.
7074 3. Nested repository states. They are defined in .hgsubstate, which is
7076 placed in the root of working directory, and capture whatever infor‐
7077 mation is required to restore the subrepositories to the state they
7078 were committed in a parent repository changeset. Mercurial automati‐
7079 cally record the nested repositories states when committing in the
7080 parent repository.
7081 Note
7083 The .hgsubstate file should not be edited manually.
7084 Adding a Subrepository
7086 If .hgsub does not exist, create it and add it to the parent reposi‐
7087 tory. Clone or checkout the external projects where you want it to live
7088 in the parent repository. Edit .hgsub and add the subrepository entry
7089 as described above. At this point, the subrepository is tracked and the
7090 next commit will record its state in .hgsubstate and bind it to the
7091 committed changeset.
7092 Synchronizing a Subrepository
7094 Subrepos do not automatically track the latest changeset of their
7095 sources. Instead, they are updated to the changeset that corresponds
7096 with the changeset checked out in the top-level changeset. This is so
7097 developers always get a consistent set of compatible code and libraries
7098 when they update.
7099 Thus, updating subrepos is a manual process. Simply check out target
7101 subrepo at the desired revision, test in the top-level repo, then com‐
7102 mit in the parent repository to record the new combination.
7103 Deleting a Subrepository
7105 To remove a subrepository from the parent repository, delete its refer‐
7106 ence from .hgsub, then remove its files.
7107 Interaction with Mercurial Commands
7109 add add does not recurse in subrepos unless -S/--subrepos is speci‐
7110 fied. However, if you specify the full path of a file in a sub‐
7111 repo, it will be added even without -S/--subrepos specified.
7112 Subversion subrepositories are currently silently ignored.
7113 addremove
7115 addremove does not recurse into subrepos unless -S/--subrepos is
7116 specified. However, if you specify the full path of a directory
7117 in a subrepo, addremove will be performed on it even without
7118 -S/--subrepos being specified. Git and Subversion subreposito‐
7119 ries will print a warning and continue.
7120 archive
7122 archive does not recurse in subrepositories unless -S/--subrepos
7123 is specified.
7124 cat Git subrepositories only support exact file matches. Subversion
7126 subrepositories are currently ignored.
7127 commit commit creates a consistent snapshot of the state of the entire
7129 project and its subrepositories. If any subrepositories have
7130 been modified, Mercurial will abort. Mercurial can be made to
7131 instead commit all modified subrepositories by specifying
7132 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
7133 ration file (see hg help config). After there are no longer any
7134 modified subrepositories, it records their state and finally
7135 commits it in the parent repository. The --addremove option
7136 also honors the -S/--subrepos option. However, Git and Subver‐
7137 sion subrepositories will print a warning and abort.
7138 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
7140 fied. However, if you specify the full path of a file or direc‐
7141 tory in a subrepo, it will be diffed even without -S/--subrepos
7142 being specified. Subversion subrepositories are currently
7143 silently ignored.
7144 files files does not recurse into subrepos unless -S/--subrepos is
7146 specified. However, if you specify the full path of a file or
7147 directory in a subrepo, it will be displayed even without
7148 -S/--subrepos being specified. Git and Subversion subreposito‐
7149 ries are currently silently ignored.
7150 forget forget currently only handles exact file matches in subrepos.
7152 Git and Subversion subrepositories are currently silently
7153 ignored.
7154 incoming
7156 incoming does not recurse in subrepos unless -S/--subrepos is
7157 specified. Git and Subversion subrepositories are currently
7158 silently ignored.
7159 outgoing
7161 outgoing does not recurse in subrepos unless -S/--subrepos is
7162 specified. Git and Subversion subrepositories are currently
7163 silently ignored.
7164 pull pull is not recursive since it is not clear what to pull prior
7166 to running hg update. Listing and retrieving all subrepositories
7167 changes referenced by the parent repository pulled changesets is
7168 expensive at best, impossible in the Subversion case.
7169 push Mercurial will automatically push all subrepositories first when
7171 the parent repository is being pushed. This ensures new sub‐
7172 repository changes are available when referenced by top-level
7173 repositories. Push is a no-op for Subversion subrepositories.
7174 serve serve does not recurse into subrepositories unless -S/--subrepos
7176 is specified. Git and Subversion subrepositories are currently
7177 silently ignored.
7178 status status does not recurse into subrepositories unless -S/--subre‐
7180 pos is specified. Subrepository changes are displayed as regular
7181 Mercurial changes on the subrepository elements. Subversion sub‐
7182 repositories are currently silently ignored.
7183 remove remove does not recurse into subrepositories unless -S/--subre‐
7185 pos is specified. However, if you specify a file or directory
7186 path in a subrepo, it will be removed even without -S/--subre‐
7187 pos. Git and Subversion subrepositories are currently silently
7188 ignored.
7189 update update restores the subrepos in the state they were originally
7191 committed in target changeset. If the recorded changeset is not
7192 available in the current subrepository, Mercurial will pull it
7193 in first before updating. This means that updating can require
7194 network access when using subrepositories.
7195 Remapping Subrepositories Sources
7197 A subrepository source location may change during a project life,
7198 invalidating references stored in the parent repository history. To fix
7199 this, rewriting rules can be defined in parent repository hgrc file or
7200 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
7201 more details.
7202
7204 Mercurial allows you to customize output of commands through templates.
7205 You can either pass in a template or select an existing template-style
7206 from the command line, via the --template option.
7207 You can customize output for any "log-like" command: log, outgoing,
7209 incoming, tip, parents, and heads.
7210 Some built-in styles are packaged with Mercurial. These can be listed
7212 with hg log --template list. Example usage:
7213 $ hg log -r1.0::1.1 --template changelog
7215 A template is a piece of text, with markup to invoke variable expan‐
7217 sion:
7218 $ hg log -r1 --template "{node}\n"
7220 b56ce7b07c52de7d5fd79fb89701ea538af65746
7221 Keywords
7223 Strings in curly braces are called keywords. The availability of key‐
7224 words depends on the exact context of the templater. These keywords are
7225 usually available for templating a log-like command:
7226 activebookmark
7228 String. The active bookmark, if it is associated with the
7229 changeset.
7230 author Alias for {user}
7232 bisect String. The changeset bisection status.
7234 bookmarks
7236 List of strings. Any bookmarks associated with the changeset.
7237 Also sets 'active', the name of the active bookmark.
7238 branch String. The name of the branch on which the changeset was com‐
7240 mitted.
7241 changessincelatesttag
7243 Integer. All ancestors not in the latest tag.
7244 children
7246 List of strings. The children of the changeset.
7247 date Date information. The date when the changeset was committed.
7249 desc String. The text of the changeset description.
7251 diffstat
7253 String. Statistics of changes with the following format: "modi‐
7254 fied files: +added/-removed lines"
7255 extras List of dicts with key, value entries of the 'extras' field of
7257 this changeset.
7258 file_adds
7260 List of strings. Files added by this changeset.
7261 file_copies
7263 List of strings. Files copied in this changeset with their
7264 sources.
7265 file_copies_switch
7267 List of strings. Like "file_copies" but displayed only if the
7268 --copied switch is set.
7269 file_dels
7271 List of strings. Files removed by this changeset.
7272 file_mods
7274 List of strings. Files modified by this changeset.
7275 files List of strings. All files modified, added, or removed by this
7277 changeset.
7278 graphnode
7280 String. The character representing the changeset node in an
7281 ASCII revision graph.
7282 graphwidth
7284 Integer. The width of the graph drawn by 'log --graph' or zero.
7285 index Integer. The current iteration of the loop. (0 indexed)
7287 latesttag
7289 List of strings. The global tags on the most recent globally
7290 tagged ancestor of this changeset. If no such tags exist, the
7291 list consists of the single string "null".
7292 latesttagdistance
7294 Integer. Longest path to the latest tag.
7295 namespaces
7297 Dict of lists. Names attached to this changeset per namespace.
7298 negrev Integer. The repository-local changeset negative revision num‐
7300 ber, which counts in the opposite direction.
7301 node String. The changeset identification hash, as a 40 hexadecimal
7303 digit string.
7304 p1 Changeset. The changeset's first parent. {p1.rev} for the revi‐
7306 sion number, and {p1.node} for the identification hash.
7307 p2 Changeset. The changeset's second parent. {p2.rev} for the revi‐
7309 sion number, and {p2.node} for the identification hash.
7310 parents
7312 List of strings. The parents of the changeset in "rev:node" for‐
7313 mat. If the changeset has only one "natural" parent (the prede‐
7314 cessor revision) nothing is shown.
7315 peerurls
7317 A dictionary of repository locations defined in the [paths] sec‐
7318 tion of your configuration file.
7319 phase String. The changeset phase name.
7321 reporoot
7323 String. The root directory of the current repository.
7324 rev Integer. The repository-local changeset revision number.
7326 subrepos
7328 List of strings. Updated subrepositories in the changeset.
7329 tags List of strings. Any tags associated with the changeset.
7331 termwidth
7333 Integer. The width of the current terminal.
7334 user String. The unmodified author of the changeset.
7336 verbosity
7338 String. The current output verbosity in 'debug', 'quiet', 'ver‐
7339 bose', or ''.
7340 The "date" keyword does not produce human-readable output. If you want
7342 to use a date in your output, you can use a filter to process it. Fil‐
7343 ters are functions which return a string based on the input variable.
7344 Be sure to use the stringify filter first when you're applying a
7345 string-input filter to a list-like input variable. You can also use a
7346 chain of filters to get the desired output:
7347 $ hg tip --template "{date|isodate}\n"
7349 2008-08-21 18:22 +0000
7350 Filters
7352 List of filters:
7353 addbreaks
7355 Any text. Add an XHTML "<br />" tag before the end of every line
7356 except the last.
7357 age Date. Returns a human-readable date/time difference between the
7359 given date/time and the current date/time.
7360 basename
7362 Any text. Treats the text as a path, and returns the last compo‐
7363 nent of the path after splitting by the path separator. For
7364 example, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
7365 cbor Any object. Serializes the object to CBOR bytes.
7367 commondir
7369 List of text. Treats each list item as file name with / as path
7370 separator and returns the longest common directory prefix shared
7371 by all list items. Returns the empty string if no common prefix
7372 exists.
7373 The list items are not normalized, i.e. "foo/../bar" is handled
7375 as file "bar" in the directory "foo/..". Leading slashes are
7376 ignored.
7377 For example, ["foo/bar/baz", "foo/baz/bar"] becomes "foo" and
7379 ["foo/bar", "baz"] becomes "".
7380 count List or text. Returns the length as an integer.
7382 dirname
7384 Any text. Treats the text as a path, and strips the last compo‐
7385 nent of the path after splitting by the path separator.
7386 domain Any text. Finds the first string that looks like an email
7388 address, and extracts just the domain component. Example: User
7389 <user@example.com> becomes example.com.
7390 email Any text. Extracts the first string that looks like an email
7392 address. Example: User <user@example.com> becomes user@exam‐
7393 ple.com.
7394 emailuser
7396 Any text. Returns the user portion of an email address.
7397 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
7399 ">" with XML entities, and filters out NUL characters.
7400 fill68 Any text. Wraps the text to fit in 68 columns.
7402 fill76 Any text. Wraps the text to fit in 76 columns.
7404 firstline
7406 Any text. Returns the first line of text.
7407 hex Any text. Convert a binary Mercurial node identifier into its
7409 long hexadecimal representation.
7410 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
7412 (Unix timestamp, timezone offset).
7413 isodate
7415 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
7416 +0200".
7417 isodatesec
7419 Date. Returns the date in ISO 8601 format, including seconds:
7420 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
7421 json Any object. Serializes the object to a JSON formatted text.
7423 lower Any text. Converts the text to lowercase.
7425 nonempty
7427 Any text. Returns '(none)' if the string is empty.
7428 obfuscate
7430 Any text. Returns the input text rendered as a sequence of XML
7431 entities.
7432 person Any text. Returns the name before an email address, interpreting
7434 it as per RFC 5322.
7435 revescape
7437 Any text. Escapes all "special" characters, except @. Forward
7438 slashes are escaped twice to prevent web servers from prema‐
7439 turely unescaping them. For example, "@foo bar/baz" becomes
7440 "@foo%20bar%252Fbaz".
7441 rfc3339date
7443 Date. Returns a date using the Internet date format specified in
7444 RFC 3339: "2009-08-18T13:00:13+02:00".
7445 rfc822date
7447 Date. Returns a date using the same format used in email head‐
7448 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
7449 short Changeset hash. Returns the short form of a changeset hash, i.e.
7451 a 12 hexadecimal digit string.
7452 shortbisect
7454 Any text. Treats label as a bisection status, and returns a sin‐
7455 gle-character representing the status (G: good, B: bad, S:
7456 skipped, U: untested, I: ignored). Returns single space if text
7457 is not a valid bisection status.
7458 shortdate
7460 Date. Returns a date like "2006-09-18".
7461 slashpath
7463 Any text. Replaces the native path separator with slash.
7464 splitlines
7466 Any text. Split text into a list of lines.
7467 stringify
7469 Any type. Turns the value into text by converting values into
7470 text and concatenating them.
7471 stripdir
7473 Treat the text as path and strip a directory level, if possible.
7474 For example, "foo" and "foo/bar" becomes "foo".
7475 tabindent
7477 Any text. Returns the text, with every non-empty line except the
7478 first starting with a tab character.
7479 upper Any text. Converts the text to uppercase.
7481 urlescape
7483 Any text. Escapes all "special" characters. For example, "foo
7484 bar" becomes "foo%20bar".
7485 user Any text. Returns a short representation of a user name or email
7487 address.
7488 utf8 Any text. Converts from the local character encoding to UTF-8.
7490 Note that a filter is nothing more than a function call, i.e.
7492 expr|filter is equivalent to filter(expr).
7493 Functions
7495 In addition to filters, there are some basic built-in functions:
7496 config(section, name[, default])
7498 Returns the requested hgrc config option as a string.
7499 configbool(section, name[, default])
7501 Returns the requested hgrc config option as a boolean.
7502 configint(section, name[, default])
7504 Returns the requested hgrc config option as an integer.
7505 date(date[, fmt])
7507 Format a date. See hg help dates for formatting strings. The
7508 default is a Unix date format, including the timezone: "Mon Sep
7509 04 15:13:13 2006 0700".
7510 dict([[key=]value...])
7512 Construct a dict from key-value pairs. A key may be omitted if a
7513 value expression can provide an unambiguous name.
7514 diff([includepattern [, excludepattern]])
7516 Show a diff, optionally specifying files to include or exclude.
7517 files(pattern)
7519 All files of the current changeset matching the pattern. See hg
7520 help patterns.
7521 fill(text[, width[, initialident[, hangindent]]])
7523 Fill many paragraphs with optional indentation. See the "fill"
7524 filter.
7525 filter(iterable[, expr])
7527 Remove empty elements from a list or a dict. If expr specified,
7528 it's applied to each element to test emptiness.
7529 get(dict, key)
7531 Get an attribute/key from an object. Some keywords are complex
7532 types. This function allows you to obtain the value of an
7533 attribute on these types.
7534 if(expr, then[, else])
7536 Conditionally execute based on the result of an expression.
7537 ifcontains(needle, haystack, then[, else])
7539 Conditionally execute based on whether the item "needle" is in
7540 "haystack".
7541 ifeq(expr1, expr2, then[, else])
7543 Conditionally execute based on whether 2 items are equivalent.
7544 indent(text, indentchars[, firstline])
7546 Indents all non-empty lines with the characters given in the
7547 indentchars string. An optional third parameter will override
7548 the indent for the first line only if present.
7549 join(list, sep)
7551 Join items in a list with a delimiter.
7552 label(label, expr)
7554 Apply a label to generated content. Content with a label applied
7555 can result in additional post-processing, such as automatic col‐
7556 orization.
7557 latesttag([pattern])
7559 The global tags matching the given pattern on the most recent
7560 globally tagged ancestor of this changeset. If no such tags
7561 exist, the "{tag}" template resolves to the string "null". See
7562 hg help revisions.patterns for the pattern syntax.
7563 localdate(date[, tz])
7565 Converts a date to the specified timezone. The default is local
7566 date.
7567 mailmap(author)
7569 Return the author, updated according to the value set in the
7570 .mailmap file
7571 max(iterable)
7573 Return the max of an iterable
7574 min(iterable)
7576 Return the min of an iterable
7577 mod(a, b)
7579 Calculate a mod b such that a / b + a mod b == a
7580 pad(text, width[, fillchar=' '[, left=False[, truncate=False]]])
7582 Pad text with a fill character.
7583 relpath(path)
7585 Convert a repository-absolute path into a filesystem path rela‐
7586 tive to the current working directory.
7587 revset(query[, formatargs...])
7589 Execute a revision set query. See hg help revset.
7590 rstdoc(text, style)
7592 Format reStructuredText.
7593 search(pattern, text)
7595 Look for the first text matching the regular expression pattern.
7596 Groups are accessible as {1}, {2}, ... in %-mapped template.
7597 separate(sep, args...)
7599 Add a separator between non-empty arguments.
7600 shortest(node, minlength=4)
7602 Obtain the shortest representation of a node.
7603 startswith(pattern, text)
7605 Returns the value from the "text" argument if it begins with the
7606 content from the "pattern" argument.
7607 strip(text[, chars])
7609 Strip characters from a string. By default, strips all leading
7610 and trailing whitespace.
7611 sub(pattern, replacement, expression)
7613 Perform text substitution using regular expressions.
7614 subsetparents(rev, revset)
7616 Look up parents of the rev in the sub graph given by the revset.
7617 word(number, text[, separator])
7619 Return the nth word from a string.
7620 Operators
7622 We provide a limited set of infix arithmetic operations on integers:
7623 + for addition
7625 - for subtraction
7626 * for multiplication
7627 / for floor division (division rounded to integer nearest -infinity)
7628 Division fulfills the law x = x / y + mod(x, y).
7630 Also, for any expression that returns a list, there is a list operator:
7632 expr % "{template}"
7634 As seen in the above example, {template} is interpreted as a template.
7636 To prevent it from being interpreted, you can use an escape character
7637 \{ or a raw string prefix, r'...'.
7638 The dot operator can be used as a shorthand for accessing a sub item:
7640 · expr.member is roughly equivalent to expr % '{member}' if expr
7642 returns a non-list/dict. The returned value is not stringified.
7643 · dict.key is identical to get(dict, 'key').
7645 Aliases
7647 New keywords and functions can be defined in the templatealias section
7648 of a Mercurial configuration file:
7649 <alias> = <definition>
7651 Arguments of the form a1, a2, etc. are substituted from the alias into
7653 the definition.
7654 For example,
7656 [templatealias]
7658 r = rev
7659 rn = "{r}:{node|short}"
7660 leftpad(s, w) = pad(s, w, ' ', True)
7661 defines two symbol aliases, r and rn, and a function alias leftpad().
7663 It's also possible to specify complete template strings, using the tem‐
7665 plates section. The syntax used is the general template string syntax.
7666 For example,
7668 [templates]
7670 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
7671 defines a template, nodedate, which can be called like:
7673 $ hg log -r . -Tnodedate
7675 A template defined in templates section can also be referenced from
7677 another template:
7678 $ hg log -r . -T "{rev} {nodedate}"
7680 but be aware that the keywords cannot be overridden by templates. For
7682 example, a template defined as templates.rev cannot be referenced as
7683 {rev}.
7684 A template defined in templates section may have sub templates which
7686 are inserted before/after/between items:
7687 [templates]
7689 myjson = ' {dict(rev, node|short)|json}'
7690 myjson:docheader = '\{\n'
7691 myjson:docfooter = '\n}\n'
7692 myjson:separator = ',\n'
7693 Examples
7695 Some sample command line templates:
7696 · Format lists, e.g. files:
7698 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
7700 · Join the list of files with a ", ":
7702 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
7704 · Join the list of files ending with ".py" with a ", ":
7706 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
7708 · Separate non-empty arguments by a " ":
7710 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
7712 · Modify each line of a commit description:
7714 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
7716 · Format date:
7718 $ hg log -r 0 --template "{date(date, '%Y')}\n"
7720 · Display date in UTC:
7722 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
7724 · Output the description set to a fill-width of 30:
7726 $ hg log -r 0 --template "{fill(desc, 30)}"
7728 · Use a conditional to test for the default branch:
7730 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
7732 'on branch {branch}')}\n"
7733 · Append a newline if not empty:
7735 $ hg tip --template "{if(author, '{author}\n')}"
7737 · Label the output for use with the color extension:
7739 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
7741 · Invert the firstline filter, i.e. everything but the first line:
7743 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
7745 · Display the contents of the 'extra' field, one per line:
7747 $ hg log -r 0 --template "{join(extras, '\n')}\n"
7749 · Mark the active bookmark with '*':
7751 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
7753 · Find the previous release candidate tag, the distance and changes
7755 since the tag:
7756 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
7758 · Mark the working copy parent with '@':
7760 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
7762 · Show details of parent revisions:
7764 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
7766 · Show only commit descriptions that start with "template":
7768 $ hg log --template "{startswith('template', firstline(desc))}\n"
7770 · Print the first word of each line of a commit message:
7772 $ hg log --template "{word(0, desc)}\n"
7774
7776 Valid URLs are of the form:
7777 local/filesystem/path[#revision]
7779 file://local/filesystem/path[#revision]
7780 http://[user[:pass]@]host[:port]/[path][#revision]
7781 https://[user[:pass]@]host[:port]/[path][#revision]
7782 ssh://[user@]host[:port]/[path][#revision]
7783 Paths in the local filesystem can either point to Mercurial reposito‐
7785 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
7786 dle). See also hg help paths.
7787 An optional identifier after # indicates a particular branch, tag, or
7789 changeset to use from the remote repository. See also hg help revisions
7790 .
7791 Some features, such as pushing to http:// and https:// URLs are only
7793 possible if the feature is explicitly enabled on the remote Mercurial
7794 server.
7795 Note that the security of HTTPS URLs depends on proper configuration of
7797 web.cacerts.
7798 Some notes about using SSH with Mercurial:
7800 · SSH requires an accessible shell account on the destination machine
7802 and a copy of hg in the remote path or specified with remotecmd.
7803 · path is relative to the remote user's home directory by default. Use
7805 an extra slash at the start of a path to specify an absolute path:
7806 ssh://example.com//tmp/repository
7808 · Mercurial doesn't use its own compression via SSH; the right thing to
7810 do is to configure it in your ~/.ssh/config, e.g.:
7811 Host *.mylocalnetwork.example.com
7813 Compression no
7814 Host *
7815 Compression yes
7816 Alternatively specify "ssh -C" as your ssh command in your configura‐
7818 tion file or with the --ssh command line option.
7819 These URLs can all be stored in your configuration file with path
7821 aliases under the [paths] section like so:
7822 [paths]
7824 alias1 = URL1
7825 alias2 = URL2
7826 ...
7827 You can then use the alias for any command that uses a URL (for example
7829 hg pull alias1 will be treated as hg pull URL1).
7830 Two path aliases are special because they are used as defaults when you
7832 do not provide the URL to a command:
7833 default:
7835 When you create a repository with hg clone, the clone command
7836 saves the location of the source repository as the new reposi‐
7837 tory's 'default' path. This is then used when you omit path from
7838 push- and pull-like commands (including incoming and outgoing).
7839 default-push:
7841 The push command will look for a path named 'default-push', and
7842 prefer it over 'default' if both are defined.
7843
7845 This section contains help for extensions that are distributed together
7846 with Mercurial. Help for other extensions is available in the help sys‐
7847 tem.
7848 absorb
7850 apply working directory changes to changesets (EXPERIMENTAL)
7851 The absorb extension provides a command to use annotate information to
7853 amend modified chunks into the corresponding non-public changesets.
7854 [absorb]
7856 # only check 50 recent non-public changesets at most
7857 max-stack-size = 50
7858 # whether to add noise to new commits to avoid obsolescence cycle
7859 add-noise = 1
7860 # make `amend --correlated` a shortcut to the main command
7861 amend-flag = correlated
7862 [color]
7864 absorb.description = yellow
7865 absorb.node = blue bold
7866 absorb.path = bold
7867 Commands
7869 Change creation
7870 absorb
7871 incorporate corrections into the stack of draft changesets:
7872 hg absorb [OPTION] [FILE]...
7874 absorb analyzes each change in your working directory and attempts to
7876 amend the changed lines into the changesets in your stack that first
7877 introduced those lines.
7878 If absorb cannot find an unambiguous changeset to amend for a change,
7880 that change will be left in the working directory, untouched. They can
7881 be observed by hg status or hg diff afterwards. In other words, absorb
7882 does not write to the working directory.
7883 Changesets outside the revset ::. and not public() and not merge() will
7885 not be changed.
7886 Changesets that become empty after applying the changes will be
7888 deleted.
7889 By default, absorb will show what it plans to do and prompt for confir‐
7891 mation. If you are confident that the changes will be absorbed to the
7892 correct place, run hg absorb -a to apply the changes immediately.
7893 Returns 0 on success, 1 if all chunks were ignored and nothing amended.
7895 Options:
7897 -a, --apply-changes
7899 apply changes without prompting for confirmation
7900 -p, --print-changes
7902 always print which changesets are modified by which changes
7903 -i, --interactive
7905 interactively select which chunks to apply
7906 -e, --edit-lines
7908 edit what lines belong to which changesets before commit (EXPER‐
7909 IMENTAL)
7910 -n, --dry-run
7912 do not perform actions, just print output
7913 --style <STYLE>
7915 display using template map file (DEPRECATED)
7916 -T,--template <TEMPLATE>
7918 display with template
7919 -I,--include <PATTERN[+]>
7921 include names matching the given patterns
7922 -X,--exclude <PATTERN[+]>
7924 exclude names matching the given patterns
7925 [+] marked option can be specified multiple times
7927 acl
7929 hooks for controlling repository access
7930 This hook makes it possible to allow or deny write access to given
7932 branches and paths of a repository when receiving incoming changesets
7933 via pretxnchangegroup and pretxncommit.
7934 The authorization is matched based on the local user name on the system
7936 where the hook runs, and not the committer of the original changeset
7937 (since the latter is merely informative).
7938 The acl hook is best used along with a restricted shell like hgsh, pre‐
7940 venting authenticating users from doing anything other than pushing or
7941 pulling. The hook is not safe to use if users have interactive shell
7942 access, as they can then disable the hook. Nor is it safe if remote
7943 users share an account, because then there is no way to distinguish
7944 them.
7945 The order in which access checks are performed is:
7947 1. Deny list for branches (section acl.deny.branches)
7949 2. Allow list for branches (section acl.allow.branches)
7951 3. Deny list for paths (section acl.deny)
7953 4. Allow list for paths (section acl.allow)
7955 The allow and deny sections take key-value pairs.
7957 Branch-based Access Control
7959 Use the acl.deny.branches and acl.allow.branches sections to have
7960 branch-based access control. Keys in these sections can be either:
7961 · a branch name, or
7963 · an asterisk, to match any branch;
7965 The corresponding values can be either:
7967 · a comma-separated list containing users and groups, or
7969 · an asterisk, to match anyone;
7971 You can add the "!" prefix to a user or group name to invert the sense
7973 of the match.
7974 Path-based Access Control
7976 Use the acl.deny and acl.allow sections to have path-based access con‐
7977 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
7978 tax by default). The corresponding values follow the same syntax as the
7979 other sections above.
7980 Bookmark-based Access Control
7982 Use the acl.deny.bookmarks and acl.allow.bookmarks sections to have
7983 bookmark-based access control. Keys in these sections can be either:
7984 · a bookmark name, or
7986 · an asterisk, to match any bookmark;
7988 The corresponding values can be either:
7990 · a comma-separated list containing users and groups, or
7992 · an asterisk, to match anyone;
7994 You can add the "!" prefix to a user or group name to invert the sense
7996 of the match.
7997 Note: for interactions between clients and servers using Mercurial 3.6+
7999 a rejection will generally reject the entire push, for interactions
8000 involving older clients, the commit transactions will already be
8001 accepted, and only the bookmark movement will be rejected.
8002 Groups
8004 Group names must be prefixed with an @ symbol. Specifying a group name
8005 has the same effect as specifying all the users in that group.
8006 You can define group members in the acl.groups section. If a group
8008 name is not defined there, and Mercurial is running under a Unix-like
8009 system, the list of users will be taken from the OS. Otherwise, an
8010 exception will be raised.
8011 Example Configuration
8013 [hooks]
8014 # Use this if you want to check access restrictions at commit time
8016 pretxncommit.acl = python:hgext.acl.hook
8017 # Use this if you want to check access restrictions for pull, push,
8019 # bundle and serve.
8020 pretxnchangegroup.acl = python:hgext.acl.hook
8021 [acl]
8023 # Allow or deny access for incoming changes only if their source is
8024 # listed here, let them pass otherwise. Source is "serve" for all
8025 # remote access (http or ssh), "push", "pull" or "bundle" when the
8026 # related commands are run locally.
8027 # Default: serve
8028 sources = serve
8029 [acl.deny.branches]
8031 # Everyone is denied to the frozen branch:
8033 frozen-branch = *
8034 # A bad user is denied on all branches:
8036 * = bad-user
8037 [acl.allow.branches]
8039 # A few users are allowed on branch-a:
8041 branch-a = user-1, user-2, user-3
8042 # Only one user is allowed on branch-b:
8044 branch-b = user-1
8045 # The super user is allowed on any branch:
8047 * = super-user
8048 # Everyone is allowed on branch-for-tests:
8050 branch-for-tests = *
8051 [acl.deny]
8053 # This list is checked first. If a match is found, acl.allow is not
8054 # checked. All users are granted access if acl.deny is not present.
8055 # Format for both lists: glob pattern = user, ..., @group, ...
8056 # To match everyone, use an asterisk for the user:
8058 # my/glob/pattern = *
8059 # user6 will not have write access to any file:
8061 ** = user6
8062 # Group "hg-denied" will not have write access to any file:
8064 ** = @hg-denied
8065 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
8067 # everyone being able to change all other files. See below.
8068 src/main/resources/DONT-TOUCH-THIS.txt = *
8069 [acl.allow]
8071 # if acl.allow is not present, all users are allowed by default
8072 # empty acl.allow = no users allowed
8073 # User "doc_writer" has write access to any file under the "docs"
8075 # folder:
8076 docs/** = doc_writer
8077 # User "jack" and group "designers" have write access to any file
8079 # under the "images" folder:
8080 images/** = jack, @designers
8081 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
8083 # will have write access to any file under the "resources" folder
8084 # (except for 1 file. See acl.deny):
8085 src/main/resources/** = *
8086 .hgtags = release_engineer
8088 Examples using the ! prefix
8090 Suppose there's a branch that only a given user (or group) should be
8091 able to push to, and you don't want to restrict access to any other
8092 branch that may be created.
8093 The "!" prefix allows you to prevent anyone except a given user or
8095 group to push changesets in a given branch or path.
8096 In the examples below, we will: 1) Deny access to branch "ring" to any‐
8098 one but user "gollum" 2) Deny access to branch "lake" to anyone but
8099 members of the group "hobbit" 3) Deny access to a file to anyone but
8100 user "gollum"
8101 [acl.allow.branches]
8103 # Empty
8104 [acl.deny.branches]
8106 # 1) only 'gollum' can commit to branch 'ring';
8108 # 'gollum' and anyone else can still commit to any other branch.
8109 ring = !gollum
8110 # 2) only members of the group 'hobbit' can commit to branch 'lake';
8112 # 'hobbit' members and anyone else can still commit to any other branch.
8113 lake = !@hobbit
8114 # You can also deny access based on file paths:
8116 [acl.allow]
8118 # Empty
8119 [acl.deny]
8121 # 3) only 'gollum' can change the file below;
8122 # 'gollum' and anyone else can still change any other file.
8123 /misty/mountains/cave/ring = !gollum
8124 amend
8126 provide the amend command (EXPERIMENTAL)
8127 This extension provides an amend command that is similar to commit
8129 --amend but does not prompt an editor.
8130 Commands
8132 Change creation
8133 amend
8134 amend the working copy parent with all or specified outstanding
8135 changes:
8136 hg amend [OPTION]... [FILE]...
8138 Similar to hg commit --amend, but reuse the commit message without
8140 invoking editor, unless --edit was set.
8141 See hg help commit for more details.
8143 Options:
8145 -A, --addremove
8147 mark new/missing files as added/removed before committing
8148 -e, --edit
8150 invoke editor on commit messages
8151 -i, --interactive
8153 use interactive mode
8154 --close-branch
8156 mark a branch as closed, hiding it from the branch list
8157 -s, --secret
8159 use the secret phase for committing
8160 -n,--note <VALUE>
8162 store a note on the amend
8163 -I,--include <PATTERN[+]>
8165 include names matching the given patterns
8166 -X,--exclude <PATTERN[+]>
8168 exclude names matching the given patterns
8169 -m,--message <TEXT>
8171 use text as commit message
8172 -l,--logfile <FILE>
8174 read commit message from file
8175 -d,--date <DATE>
8177 record the specified date as commit date
8178 -u,--user <USER>
8180 record the specified user as committer
8181 -D, --currentdate
8183 record the current date as commit date
8184 -U, --currentuser
8186 record the current user as committer
8187 [+] marked option can be specified multiple times
8189 automv
8191 check for unrecorded moves at commit time (EXPERIMENTAL)
8192 This extension checks at commit/amend time if any of the committed
8194 files comes from an unrecorded mv.
8195 The threshold at which a file is considered a move can be set with the
8197 automv.similarity config option. This option takes a percentage between
8198 0 (disabled) and 100 (files must be identical), the default is 95.
8199 beautifygraph
8201 beautify log -G output by using Unicode characters (EXPERIMENTAL)
8202 A terminal with UTF-8 support and monospace narrow text are
8204 required.
8205 blackbox
8207 log repository events to a blackbox for debugging
8208 Logs event information to .hg/blackbox.log to help debug and diagnose
8210 problems. The events that get logged can be configured via the black‐
8211 box.track and blackbox.ignore config keys.
8212 Examples:
8214 [blackbox]
8216 track = *
8217 ignore = pythonhook
8218 # dirty is *EXPENSIVE* (slow);
8219 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
8220 dirty = True
8221 # record the source of log messages
8222 logsource = True
8223 [blackbox]
8225 track = command, commandfinish, commandexception, exthook, pythonhook
8226 [blackbox]
8228 track = incoming
8229 [blackbox]
8231 # limit the size of a log file
8232 maxsize = 1.5 MB
8233 # rotate up to N log files when the current one gets too big
8234 maxfiles = 3
8235 [blackbox]
8237 # Include nanoseconds in log entries with %f (see Python function
8238 # datetime.datetime.strftime)
8239 date-format = '%Y-%m-%d @ %H:%M:%S.%f'
8240 Commands
8242 Repository maintenance
8243 blackbox
8244 view the recent repository events:
8245 hg blackbox [OPTION]...
8247 view the recent repository events
8249 Options:
8251 -l,--limit <VALUE>
8253 the number of events to show (default: 10)
8254 bookflow
8256 implements bookmark-based branching (EXPERIMENTAL)
8257 · Disables creation of new branches (config: enable_branches=False).
8259 · Requires an active bookmark on commit (config: require_book‐
8261 mark=True).
8262 · Doesn't move the active bookmark on update, only on commit.
8264 · Requires '--rev' for moving an existing bookmark.
8266 · Protects special bookmarks (config: protect=@).
8268 flow related commands
8270 hg book NAME
8272 create a new bookmark
8273 hg book NAME -r REV
8275 move bookmark to revision (fast-forward)
8276 hg up|co NAME
8278 switch to bookmark
8279 hg push -B .
8281 push active bookmark
8282 bugzilla
8284 hooks for integrating with the Bugzilla bug tracker
8285 This hook extension adds comments on bugs in Bugzilla when changesets
8287 that refer to bugs by Bugzilla ID are seen. The comment is formatted
8288 using the Mercurial template mechanism.
8289 The bug references can optionally include an update for Bugzilla of the
8291 hours spent working on the bug. Bugs can also be marked fixed.
8292 Four basic modes of access to Bugzilla are provided:
8294 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
8296 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
8298 later.
8299 3. Check data via the Bugzilla XMLRPC interface and submit bug change
8301 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
8302 later.
8303 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
8305 tions using MySQL are supported. Requires Python MySQLdb.
8306 Writing directly to the database is susceptible to schema changes, and
8308 relies on a Bugzilla contrib script to send out bug change notification
8309 emails. This script runs as the user running Mercurial, must be run on
8310 the host with the Bugzilla install, and requires permission to read
8311 Bugzilla configuration details and the necessary MySQL user and pass‐
8312 word to have full access rights to the Bugzilla database. For these
8313 reasons this access mode is now considered deprecated, and will not be
8314 updated for new Bugzilla versions going forward. Only adding comments
8315 is supported in this access mode.
8316 Access via XMLRPC needs a Bugzilla username and password to be speci‐
8318 fied in the configuration. Comments are added under that username.
8319 Since the configuration must be readable by all Mercurial users, it is
8320 recommended that the rights of that user are restricted in Bugzilla to
8321 the minimum necessary to add comments. Marking bugs fixed requires
8322 Bugzilla 4.0 and later.
8323 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
8325 to the Bugzilla email interface to submit comments to bugs. The From:
8326 address in the email is set to the email address of the Mercurial user,
8327 so the comment appears to come from the Mercurial user. In the event
8328 that the Mercurial user email is not recognized by Bugzilla as a
8329 Bugzilla user, the email associated with the Bugzilla username used to
8330 log into Bugzilla is used instead as the source of the comment. Marking
8331 bugs fixed works on all supported Bugzilla versions.
8332 Access via the REST-API needs either a Bugzilla username and password
8334 or an apikey specified in the configuration. Comments are made under
8335 the given username or the user associated with the apikey in Bugzilla.
8336 Configuration items common to all access modes:
8338 bugzilla.version
8340 The access type to use. Values recognized are:
8341 restapi
8343 Bugzilla REST-API, Bugzilla 5.0 and later.
8345 xmlrpc
8347 Bugzilla XMLRPC interface.
8349 xmlrpc+email
8351 Bugzilla XMLRPC and email interfaces.
8353 3.0
8355 MySQL access, Bugzilla 3.0 and later.
8357 2.18
8359 MySQL access, Bugzilla 2.18 and up to but not including
8361 3.0.
8362 2.16
8364 MySQL access, Bugzilla 2.16 and up to but not including
8366 2.18.
8367 bugzilla.regexp
8369 Regular expression to match bug IDs for update in changeset com‐
8370 mit message. It must contain one "()" named group <ids> con‐
8371 taining the bug IDs separated by non-digit characters. It may
8372 also contain a named group <hours> with a floating-point number
8373 giving the hours worked on the bug. If no named groups are
8374 present, the first "()" group is assumed to contain the bug IDs,
8375 and work time is not updated. The default expression matches Bug
8376 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
8377 and 5678 and variations thereof, followed by an hours number
8378 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
8379 sitive.
8380 bugzilla.fixregexp
8382 Regular expression to match bug IDs for marking fixed in change‐
8383 set commit message. This must contain a "()" named group <ids>`
8384 containing the bug IDs separated by non-digit characters. It may
8385 also contain a named group ``<hours> with a floating-point num‐
8386 ber giving the hours worked on the bug. If no named groups are
8387 present, the first "()" group is assumed to contain the bug IDs,
8388 and work time is not updated. The default expression matches
8389 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
8390 5678 and variations thereof, followed by an hours number pre‐
8391 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
8392 tive.
8393 bugzilla.fixstatus
8395 The status to set a bug to when marking fixed. Default RESOLVED.
8396 bugzilla.fixresolution
8398 The resolution to set a bug to when marking fixed. Default
8399 FIXED.
8400 bugzilla.style
8402 The style file to use when formatting comments.
8403 bugzilla.template
8405 Template to use when formatting comments. Overrides style if
8406 specified. In addition to the usual Mercurial keywords, the
8407 extension specifies:
8408 {bug}
8410 The Bugzilla bug ID.
8412 {root}
8414 The full pathname of the Mercurial repository.
8416 {webroot}
8418 Stripped pathname of the Mercurial repository.
8420 {hgweb}
8422 Base URL for browsing Mercurial repositories.
8424 Default changeset {node|short} in repo {root} refers to bug
8426 {bug}.\ndetails:\n\t{desc|tabindent}
8427 bugzilla.strip
8429 The number of path separator characters to strip from the front
8430 of the Mercurial repository path ({root} in templates) to pro‐
8431 duce {webroot}. For example, a repository with {root}
8432 /var/local/my-project with a strip of 2 gives a value for {web‐
8433 root} of my-project. Default 0.
8434 web.baseurl
8436 Base URL for browsing Mercurial repositories. Referenced from
8437 templates as {hgweb}.
8438 Configuration items common to XMLRPC+email and MySQL access modes:
8440 bugzilla.usermap
8442 Path of file containing Mercurial committer email to Bugzilla
8443 user email mappings. If specified, the file should contain one
8444 mapping per line:
8445 committer = Bugzilla user
8447 See also the [usermap] section.
8449 The [usermap] section is used to specify mappings of Mercurial commit‐
8451 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
8452 entries of the form committer = Bugzilla user.
8453 XMLRPC and REST-API access mode configuration:
8455 bugzilla.bzurl
8457 The base URL for the Bugzilla installation. Default
8458 http://localhost/bugzilla.
8459 bugzilla.user
8461 The username to use to log into Bugzilla via XMLRPC. Default
8462 bugs.
8463 bugzilla.password
8465 The password for Bugzilla login.
8466 REST-API access mode uses the options listed above as well as:
8468 bugzilla.apikey
8470 An apikey generated on the Bugzilla instance for api access.
8471 Using an apikey removes the need to store the user and password
8472 options.
8473 XMLRPC+email access mode uses the XMLRPC access mode configuration
8475 items, and also:
8476 bugzilla.bzemail
8478 The Bugzilla email address.
8479 In addition, the Mercurial email settings must be configured. See the
8481 documentation in hgrc(5), sections [email] and [smtp].
8482 MySQL access mode configuration:
8484 bugzilla.host
8486 Hostname of the MySQL server holding the Bugzilla database.
8487 Default localhost.
8488 bugzilla.db
8490 Name of the Bugzilla database in MySQL. Default bugs.
8491 bugzilla.user
8493 Username to use to access MySQL server. Default bugs.
8494 bugzilla.password
8496 Password to use to access MySQL server.
8497 bugzilla.timeout
8499 Database connection timeout (seconds). Default 5.
8500 bugzilla.bzuser
8502 Fallback Bugzilla user name to record comments with, if change‐
8503 set committer cannot be found as a Bugzilla user.
8504 bugzilla.bzdir
8506 Bugzilla install directory. Used by default notify. Default
8507 /var/www/html/bugzilla.
8508 bugzilla.notify
8510 The command to run to get Bugzilla to send bug change notifica‐
8511 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
8512 id) and user (committer bugzilla email). Default depends on ver‐
8513 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
8514 mail.pl %(id)s %(user)s".
8515 Activating the extension:
8517 [extensions]
8519 bugzilla =
8520 [hooks]
8522 # run bugzilla hook on every change pulled or pushed in here
8523 incoming.bugzilla = python:hgext.bugzilla.hook
8524 Example configurations:
8526 XMLRPC example configuration. This uses the Bugzilla at
8528 http://my-project.org/bugzilla, logging in as user bug‐
8529 mail@my-project.org with password plugh. It is used with a collection
8530 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8531 at http://my-project.org/hg.
8532 [bugzilla]
8534 bzurl=http://my-project.org/bugzilla
8535 user=bugmail@my-project.org
8536 password=plugh
8537 version=xmlrpc
8538 template=Changeset {node|short} in {root|basename}.
8539 {hgweb}/{webroot}/rev/{node|short}\n
8540 {desc}\n
8541 strip=5
8542 [web]
8544 baseurl=http://my-project.org/hg
8545 XMLRPC+email example configuration. This uses the Bugzilla at
8547 http://my-project.org/bugzilla, logging in as user bug‐
8548 mail@my-project.org with password plugh. It is used with a collection
8549 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8550 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
8551 email address bugzilla@my-project.org.
8552 [bugzilla]
8554 bzurl=http://my-project.org/bugzilla
8555 user=bugmail@my-project.org
8556 password=plugh
8557 version=xmlrpc+email
8558 bzemail=bugzilla@my-project.org
8559 template=Changeset {node|short} in {root|basename}.
8560 {hgweb}/{webroot}/rev/{node|short}\n
8561 {desc}\n
8562 strip=5
8563 [web]
8565 baseurl=http://my-project.org/hg
8566 [usermap]
8568 user@emaildomain.com=user.name@bugzilladomain.com
8569 MySQL example configuration. This has a local Bugzilla 3.2 installation
8571 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
8572 database name is bugs and MySQL is accessed with MySQL username bugs
8573 password XYZZY. It is used with a collection of Mercurial repositories
8574 in /var/local/hg/repos/, with a web interface at
8575 http://my-project.org/hg.
8576 [bugzilla]
8578 host=localhost
8579 password=XYZZY
8580 version=3.0
8581 bzuser=unknown@domain.com
8582 bzdir=/opt/bugzilla-3.2
8583 template=Changeset {node|short} in {root|basename}.
8584 {hgweb}/{webroot}/rev/{node|short}\n
8585 {desc}\n
8586 strip=5
8587 [web]
8589 baseurl=http://my-project.org/hg
8590 [usermap]
8592 user@emaildomain.com=user.name@bugzilladomain.com
8593 All the above add a comment to the Bugzilla bug record of the form:
8595 Changeset 3b16791d6642 in repository-name.
8597 http://my-project.org/hg/repository-name/rev/3b16791d6642
8598 Changeset commit comment. Bug 1234.
8600 censor
8602 erase file content at a given revision
8603 The censor command instructs Mercurial to erase all content of a file
8605 at a given revision without updating the changeset hash. This allows
8606 existing history to remain valid while preventing future clones/pulls
8607 from receiving the erased data.
8608 Typical uses for censor are due to security or legal requirements,
8610 including:
8611 * Passwords, private keys, cryptographic material
8613 * Licensed data/code/libraries for which the license has expired
8614 * Personally Identifiable Information or other private data
8615 Censored nodes can interrupt mercurial's typical operation whenever the
8617 excised data needs to be materialized. Some commands, like hg cat/hg
8618 revert, simply fail when asked to produce censored data. Others, like
8619 hg verify and hg update, must be capable of tolerating censored data to
8620 continue to function in a meaningful way. Such commands only tolerate
8621 censored file revisions if they are allowed by the "censor.pol‐
8622 icy=ignore" config option.
8623 A few informative commands such as hg grep will unconditionally ignore
8625 censored data and merely report that it was encountered.
8626 Commands
8628 Repository maintenance
8629 censor
8630 hg censor -r REV [-t TEXT] [FILE]
8631 Options:
8633 -r,--rev <REV>
8635 censor file from specified revision
8636 -t,--tombstone <TEXT>
8638 replacement tombstone data
8639 children
8641 command to display child changesets (DEPRECATED)
8642 This extension is deprecated. You should use hg log -r "children(REV)"
8644 instead.
8645 Commands
8647 Change navigation
8648 children
8649 show the children of the given or working directory revision:
8650 hg children [-r REV] [FILE]
8652 Print the children of the working directory's revisions. If a revision
8654 is given via -r/--rev, the children of that revision will be printed.
8655 If a file argument is given, revision in which the file was last
8656 changed (after the working directory revision or the argument to --rev
8657 if given) is printed.
8658 Please use hg log instead:
8660 hg children => hg log -r "children(.)"
8662 hg children -r REV => hg log -r "children(REV)"
8663 See hg help log and hg help revsets.children.
8665 Options:
8667 -r,--rev <REV>
8669 show children of the specified revision (default: .)
8670 --style <STYLE>
8672 display using template map file (DEPRECATED)
8673 -T,--template <TEMPLATE>
8675 display with template
8676 churn
8678 command to display statistics about repository history
8679 Commands
8681 Repository maintenance
8682 churn
8683 histogram of changes to the repository:
8684 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
8686 This command will display a histogram representing the number of
8688 changed lines or revisions, grouped according to the given template.
8689 The default template will group changes by author. The --dateformat
8690 option may be used to group the results by date instead.
8691 Statistics are based on the number of changed lines, or alternatively
8693 the number of matching revisions if the --changesets option is speci‐
8694 fied.
8695 Examples:
8697 # display count of changed lines for every committer
8699 hg churn -T "{author|email}"
8700 # display daily activity graph
8702 hg churn -f "%H" -s -c
8703 # display activity of developers by month
8705 hg churn -f "%Y-%m" -s -c
8706 # display count of lines changed in every year
8708 hg churn -f "%Y" -s
8709 It is possible to map alternate email addresses to a main address by
8711 providing a file using the following format:
8712 <alias email> = <actual email>
8714 Such a file may be specified with the --aliases option, otherwise a
8716 .hgchurn file will be looked for in the working directory root.
8717 Aliases will be split from the rightmost "=".
8718 Options:
8720 -r,--rev <REV[+]>
8722 count rate for the specified revision or revset
8723 -d,--date <DATE>
8725 count rate for revisions matching date spec
8726 -t,--oldtemplate <TEMPLATE>
8728 template to group changesets (DEPRECATED)
8729 -T,--template <TEMPLATE>
8731 template to group changesets (default: {author|email})
8732 -f,--dateformat <FORMAT>
8734 strftime-compatible format for grouping by date
8735 -c, --changesets
8737 count rate by number of changesets
8738 -s, --sort
8740 sort by key (default: sort by count)
8741 --diffstat
8743 display added/removed lines separately
8744 --aliases <FILE>
8746 file with email aliases
8747 -I,--include <PATTERN[+]>
8749 include names matching the given patterns
8750 -X,--exclude <PATTERN[+]>
8752 exclude names matching the given patterns
8753 [+] marked option can be specified multiple times
8755 clonebundles
8757 advertise pre-generated bundles to seed clones
8758 "clonebundles" is a server-side extension used to advertise the exis‐
8760 tence of pre-generated, externally hosted bundle files to clients that
8761 are cloning so that cloning can be faster, more reliable, and require
8762 less resources on the server. "pullbundles" is a related feature for
8763 sending pre-generated bundle files to clients as part of pull opera‐
8764 tions.
8765 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
8767 ally, the server, in response to a client's request to clone, dynami‐
8768 cally generates a bundle containing the entire repository content and
8769 sends it to the client. There is no caching on the server and the
8770 server will have to redundantly generate the same outgoing bundle in
8771 response to each clone request. For servers with large repositories or
8772 with high clone volume, the load from clones can make scaling the
8773 server challenging and costly.
8774 This extension provides server operators the ability to offload poten‐
8776 tially expensive clone load to an external service. Pre-generated bun‐
8777 dles also allow using more CPU intensive compression, reducing the
8778 effective bandwidth requirements.
8779 Here's how clone bundles work:
8781 1. A server operator establishes a mechanism for making bundle files
8783 available on a hosting service where Mercurial clients can fetch
8784 them.
8785 2. A manifest file listing available bundle URLs and some optional
8787 metadata is added to the Mercurial repository on the server.
8788 3. A client initiates a clone against a clone bundles aware server.
8790 4. The client sees the server is advertising clone bundles and fetches
8792 the manifest listing available bundles.
8793 5. The client filters and sorts the available bundles based on what it
8795 supports and prefers.
8796 6. The client downloads and applies an available bundle from the
8798 server-specified URL.
8799 7. The client reconnects to the original server and performs the equiv‐
8801 alent of hg pull to retrieve all repository data not in the bundle.
8802 (The repository could have been updated between when the bundle was
8803 created and when the client started the clone.) This may use "pull‐
8804 bundles".
8805 Instead of the server generating full repository bundles for every
8807 clone request, it generates full bundles once and they are subsequently
8808 reused to bootstrap new clones. The server may still transfer data at
8809 clone time. However, this is only data that has been added/changed
8810 since the bundle was created. For large, established repositories, this
8811 can reduce server load for clones to less than 1% of original.
8812 Here's how pullbundles work:
8814 1. A manifest file listing available bundles and describing the revi‐
8816 sions is added to the Mercurial repository on the server.
8817 2. A new-enough client informs the server that it supports partial
8819 pulls and initiates a pull.
8820 3. If the server has pull bundles enabled and sees the client advertis‐
8822 ing partial pulls, it checks for a matching pull bundle in the mani‐
8823 fest. A bundle matches if the format is supported by the client,
8824 the client has the required revisions already and needs something
8825 from the bundle.
8826 4. If there is at least one matching bundle, the server sends it to the
8828 client.
8829 5. The client applies the bundle and notices that the server reply was
8831 incomplete. It initiates another pull.
8832 To work, this extension requires the following of server operators:
8834 · Generating bundle files of repository content (typically periodi‐
8836 cally, such as once per day).
8837 · Clone bundles: A file server that clients have network access to and
8839 that Python knows how to talk to through its normal URL handling
8840 facility (typically an HTTP/HTTPS server).
8841 · A process for keeping the bundles manifest in sync with available
8843 bundle files.
8844 Strictly speaking, using a static file hosting server isn't required: a
8846 server operator could use a dynamic service for retrieving bundle data.
8847 However, static file hosting services are simple and scalable and
8848 should be sufficient for most needs.
8849 Bundle files can be generated with the hg bundle command. Typically hg
8851 bundle --all is used to produce a bundle of the entire repository.
8852 hg debugcreatestreamclonebundle can be used to produce a special
8854 streaming clonebundle. These are bundle files that are extremely effi‐
8855 cient to produce and consume (read: fast). However, they are larger
8856 than traditional bundle formats and require that clients support the
8857 exact set of repository data store formats in use by the repository
8858 that created them. Typically, a newer server can serve data that is
8859 compatible with older clients. However, streaming clone bundles don't
8860 have this guarantee. Server operators need to be aware that newer ver‐
8861 sions of Mercurial may produce streaming clone bundles incompatible
8862 with older Mercurial versions.
8863 A server operator is responsible for creating a .hg/clonebundles.mani‐
8865 fest file containing the list of available bundle files suitable for
8866 seeding clones. If this file does not exist, the repository will not
8867 advertise the existence of clone bundles when clients connect. For pull
8868 bundles, .hg/pullbundles.manifest is used.
8869 The manifest file contains a newline (n) delimited list of entries.
8871 Each line in this file defines an available bundle. Lines have the for‐
8873 mat:
8874 <URL> [<key>=<value>[ <key>=<value>]]
8876 That is, a URL followed by an optional, space-delimited list of
8878 key=value pairs describing additional properties of this bundle. Both
8879 keys and values are URI encoded.
8880 For pull bundles, the URL is a path under the .hg directory of the
8882 repository.
8883 Keys in UPPERCASE are reserved for use by Mercurial and are defined
8885 below. All non-uppercase keys can be used by site installations. An
8886 example use for custom properties is to use the datacenter attribute to
8887 define which data center a file is hosted in. Clients could then prefer
8888 a server in the data center closest to them.
8889 The following reserved keys are currently defined:
8891 BUNDLESPEC
8893 A "bundle specification" string that describes the type of the
8894 bundle.
8895 These are string values that are accepted by the "--type" argu‐
8897 ment of hg bundle.
8898 The values are parsed in strict mode, which means they must be
8900 of the "<compression>-<type>" form. See mercu‐
8901 rial.exchange.parsebundlespec() for more details.
8902 hg debugbundle --spec can be used to print the bundle specifica‐
8904 tion string for a bundle file. The output of this command can be
8905 used verbatim for the value of BUNDLESPEC (it is already
8906 escaped).
8907 Clients will automatically filter out specifications that are
8909 unknown or unsupported so they won't attempt to download some‐
8910 thing that likely won't apply.
8911 The actual value doesn't impact client behavior beyond filter‐
8913 ing: clients will still sniff the bundle type from the header of
8914 downloaded files.
8915 Use of this key is highly recommended, as it allows clients to
8917 easily skip unsupported bundles. If this key is not defined, an
8918 old client may attempt to apply a bundle that it is incapable of
8919 reading.
8920 REQUIRESNI
8922 Whether Server Name Indication (SNI) is required to connect to
8923 the URL. SNI allows servers to use multiple certificates on the
8924 same IP. It is somewhat common in CDNs and other hosting
8925 providers. Older Python versions do not support SNI. Defining
8926 this attribute enables clients with older Python versions to
8927 filter this entry without experiencing an opaque SSL failure at
8928 connection time.
8929 If this is defined, it is important to advertise a non-SNI fall‐
8931 back URL or clients running old Python releases may not be able
8932 to clone with the clonebundles facility.
8933 Value should be "true".
8935 heads Used for pull bundles. This contains the ; separated changeset
8937 hashes of the heads of the bundle content.
8938 bases Used for pull bundles. This contains the ; separated changeset
8940 hashes of the roots of the bundle content. This can be skipped
8941 if the bundle was created without --base.
8942 Manifests can contain multiple entries. Assuming metadata is defined,
8944 clients will filter entries from the manifest that they don't support.
8945 The remaining entries are optionally sorted by client preferences
8946 (ui.clonebundleprefers config option). The client then attempts to
8947 fetch the bundle at the first URL in the remaining list.
8948 Errors when downloading a bundle will fail the entire clone operation:
8950 clients do not automatically fall back to a traditional clone. The rea‐
8951 son for this is that if a server is using clone bundles, it is probably
8952 doing so because the feature is necessary to help it scale. In other
8953 words, there is an assumption that clone load will be offloaded to
8954 another service and that the Mercurial server isn't responsible for
8955 serving this clone load. If that other service experiences issues and
8956 clients start mass falling back to the original Mercurial server, the
8957 added clone load could overwhelm the server due to unexpected load and
8958 effectively take it offline. Not having clients automatically fall back
8959 to cloning from the original server mitigates this scenario.
8960 Because there is no automatic Mercurial server fallback on failure of
8962 the bundle hosting service, it is important for server operators to
8963 view the bundle hosting service as an extension of the Mercurial server
8964 in terms of availability and service level agreements: if the bundle
8965 hosting service goes down, so does the ability for clients to clone.
8966 Note: clients will see a message informing them how to bypass the clone
8967 bundles facility when a failure occurs. So server operators should pre‐
8968 pare for some people to follow these instructions when a failure
8969 occurs, thus driving more load to the original Mercurial server when
8970 the bundle hosting service fails.
8971 closehead
8973 close arbitrary heads without checking them out first
8974 Commands
8976 Change manipulation
8977 close-head
8978 close the given head revisions:
8979 hg close-head [OPTION]... [REV]...
8981 This is equivalent to checking out each revision in a clean tree and
8983 running hg commit --close-branch, except that it doesn't change the
8984 working directory.
8985 The commit message must be specified with -l or -m.
8987 Options:
8989 -m,--message <TEXT>
8991 use text as commit message
8992 -l,--logfile <FILE>
8994 read commit message from file
8995 -d,--date <DATE>
8997 record the specified date as commit date
8998 -u,--user <USER>
9000 record the specified user as committer
9001 -r,--rev <REV[+]>
9003 revision to check
9004 [+] marked option can be specified multiple times
9006 aliases: close-heads
9008 commitextras
9010 adds a new flag extras to commit (ADVANCED)
9011 convert
9013 import revisions from foreign VCS repositories into Mercurial
9014 Commands
9016 Uncategorized commands
9017 convert
9018 convert a foreign SCM repository to a Mercurial one.:
9019 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
9021 Accepted source formats [identifiers]:
9023 · Mercurial [hg]
9025 · CVS [cvs]
9027 · Darcs [darcs]
9029 · git [git]
9031 · Subversion [svn]
9033 · Monotone [mtn]
9035 · GNU Arch [gnuarch]
9037 · Bazaar [bzr]
9039 · Perforce [p4]
9041 Accepted destination formats [identifiers]:
9043 · Mercurial [hg]
9045 · Subversion [svn] (history on branches is not preserved)
9047 If no revision is given, all revisions will be converted. Otherwise,
9049 convert will only import up to the named revision (given in a format
9050 understood by the source).
9051 If no destination directory name is specified, it defaults to the base‐
9053 name of the source with -hg appended. If the destination repository
9054 doesn't exist, it will be created.
9055 By default, all sources except Mercurial will use --branchsort. Mercu‐
9057 rial uses --sourcesort to preserve original revision numbers order.
9058 Sort modes have the following effects:
9059 --branchsort
9061 convert from parent to child revision when possible, which means
9062 branches are usually converted one after the other. It generates
9063 more compact repositories.
9064 --datesort
9066 sort revisions by date. Converted repositories have good-looking
9067 changelogs but are often an order of magnitude larger than the
9068 same ones generated by --branchsort.
9069 --sourcesort
9071 try to preserve source revisions order, only supported by Mercu‐
9072 rial sources.
9073 --closesort
9075 try to move closed revisions as close as possible to parent
9076 branches, only supported by Mercurial sources.
9077 If REVMAP isn't given, it will be put in a default location
9079 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
9080 maps each source commit ID to the destination ID for that revision,
9081 like so:
9082 <source ID> <destination ID>
9084 If the file doesn't exist, it's automatically created. It's updated on
9086 each commit copied, so hg convert can be interrupted and can be run
9087 repeatedly to copy new commits.
9088 The authormap is a simple text file that maps each source commit author
9090 to a destination commit author. It is handy for source SCMs that use
9091 unix logins to identify authors (e.g.: CVS). One line per author map‐
9092 ping and the line format is:
9093 source author = destination author
9095 Empty lines and lines starting with a # are ignored.
9097 The filemap is a file that allows filtering and remapping of files and
9099 directories. Each line can contain one of the following directives:
9100 include path/to/file-or-dir
9102 exclude path/to/file-or-dir
9104 rename path/to/source path/to/destination
9106 Comment lines start with #. A specified path matches if it equals the
9108 full relative name of a file or one of its parent directories. The
9109 include or exclude directive with the longest matching path applies, so
9110 line order does not matter.
9111 The include directive causes a file, or all files under a directory, to
9113 be included in the destination repository. The default if there are no
9114 include statements is to include everything. If there are any include
9115 statements, nothing else is included. The exclude directive causes
9116 files or directories to be omitted. The rename directive renames a file
9117 or directory if it is converted. To rename from a subdirectory into the
9118 root of the repository, use . as the path to rename to.
9119 --full will make sure the converted changesets contain exactly the
9121 right files with the right content. It will make a full conversion of
9122 all files, not just the ones that have changed. Files that already are
9123 correct will not be changed. This can be used to apply filemap changes
9124 when converting incrementally. This is currently only supported for
9125 Mercurial and Subversion.
9126 The splicemap is a file that allows insertion of synthetic history,
9128 letting you specify the parents of a revision. This is useful if you
9129 want to e.g. give a Subversion merge two parents, or graft two discon‐
9130 nected series of history together. Each entry contains a key, followed
9131 by a space, followed by one or two comma-separated values:
9132 key parent1, parent2
9134 The key is the revision ID in the source revision control system whose
9136 parents should be modified (same format as a key in .hg/shamap). The
9137 values are the revision IDs (in either the source or destination revi‐
9138 sion control system) that should be used as the new parents for that
9139 node. For example, if you have merged "release-1.0" into "trunk", then
9140 you should specify the revision on "trunk" as the first parent and the
9141 one on the "release-1.0" branch as the second.
9142 The branchmap is a file that allows you to rename a branch when it is
9144 being brought in from whatever external repository. When used in con‐
9145 junction with a splicemap, it allows for a powerful combination to help
9146 fix even the most badly mismanaged repositories and turn them into
9147 nicely structured Mercurial repositories. The branchmap contains lines
9148 of the form:
9149 original_branch_name new_branch_name
9151 where "original_branch_name" is the name of the branch in the source
9153 repository, and "new_branch_name" is the name of the branch is the des‐
9154 tination repository. No whitespace is allowed in the new branch name.
9155 This can be used to (for instance) move code in one repository from
9156 "default" to a named branch.
9157 Mercurial Source
9159 The Mercurial source recognizes the following configuration options,
9160 which you can set on the command line with --config:
9161 convert.hg.ignoreerrors
9163 ignore integrity errors when reading. Use it to fix Mercurial
9164 repositories with missing revlogs, by converting from and to
9165 Mercurial. Default is False.
9166 convert.hg.saverev
9168 store original revision ID in changeset (forces target IDs to
9169 change). It takes a boolean argument and defaults to False.
9170 convert.hg.startrev
9172 specify the initial Mercurial revision. The default is 0.
9173 convert.hg.revs
9175 revset specifying the source revisions to convert.
9176 Bazaar Source
9178 The following options can be used with --config:
9179 convert.bzr.saverev
9181 whether to store the original Bazaar commit ID in the metadata
9182 of the destination commit. The default is True.
9183 CVS Source
9185 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to
9186 indicate the starting point of what will be converted. Direct access to
9187 the repository files is not needed, unless of course the repository is
9188 :local:. The conversion uses the top level directory in the sandbox to
9189 find the CVS repository, and then uses CVS rlog commands to find files
9190 to convert. This means that unless a filemap is given, all files under
9191 the starting directory will be converted, and that any directory reor‐
9192 ganization in the CVS sandbox is ignored.
9193 The following options can be used with --config:
9195 convert.cvsps.cache
9197 Set to False to disable remote log caching, for testing and
9198 debugging purposes. Default is True.
9199 convert.cvsps.fuzz
9201 Specify the maximum time (in seconds) that is allowed between
9202 commits with identical user and log message in a single change‐
9203 set. When very large files were checked in as part of a change‐
9204 set then the default may not be long enough. The default is 60.
9205 convert.cvsps.logencoding
9207 Specify encoding name to be used for transcoding CVS log mes‐
9208 sages. Multiple encoding names can be specified as a list (see
9209 hg help config.Syntax), but only the first acceptable encoding
9210 in the list is used per CVS log entries. This transcoding is
9211 executed before cvslog hook below.
9212 convert.cvsps.mergeto
9214 Specify a regular expression to which commit log messages are
9215 matched. If a match occurs, then the conversion process will
9216 insert a dummy revision merging the branch on which this log
9217 message occurs to the branch indicated in the regex. Default is
9218 {{mergetobranch ([-\w]+)}}
9219 convert.cvsps.mergefrom
9221 Specify a regular expression to which commit log messages are
9222 matched. If a match occurs, then the conversion process will add
9223 the most recent revision on the branch indicated in the regex as
9224 the second parent of the changeset. Default is {{mergefrombranch
9225 ([-\w]+)}}
9226 convert.localtimezone
9228 use local time (as determined by the TZ environment variable)
9229 for changeset date/times. The default is False (use UTC).
9230 hooks.cvslog
9232 Specify a Python function to be called at the end of gathering
9233 the CVS log. The function is passed a list with the log entries,
9234 and can modify the entries in-place, or add or delete them.
9235 hooks.cvschangesets
9237 Specify a Python function to be called after the changesets are
9238 calculated from the CVS log. The function is passed a list with
9239 the changeset entries, and can modify the changesets in-place,
9240 or add or delete them.
9241 An additional "debugcvsps" Mercurial command allows the builtin change‐
9243 set merging code to be run without doing a conversion. Its parameters
9244 and output are similar to that of cvsps 2.1. Please see the command
9245 help for more details.
9246 Subversion Source
9248 Subversion source detects classical trunk/branches/tags layouts. By
9249 default, the supplied svn://repo/path/ source URL is converted as a
9250 single branch. If svn://repo/path/trunk exists it replaces the default
9251 branch. If svn://repo/path/branches exists, its subdirectories are
9252 listed as possible branches. If svn://repo/path/tags exists, it is
9253 looked for tags referencing converted branches. Default trunk, branches
9254 and tags values can be overridden with following options. Set them to
9255 paths relative to the source URL, or leave them blank to disable auto
9256 detection.
9257 The following options can be set with --config:
9259 convert.svn.branches
9261 specify the directory containing branches. The default is
9262 branches.
9263 convert.svn.tags
9265 specify the directory containing tags. The default is tags.
9266 convert.svn.trunk
9268 specify the name of the trunk branch. The default is trunk.
9269 convert.localtimezone
9271 use local time (as determined by the TZ environment variable)
9272 for changeset date/times. The default is False (use UTC).
9273 Source history can be retrieved starting at a specific revision,
9275 instead of being integrally converted. Only single branch conversions
9276 are supported.
9277 convert.svn.startrev
9279 specify start Subversion revision number. The default is 0.
9280 Git Source
9282 The Git importer converts commits from all reachable branches (refs in
9283 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
9284 are converted to bookmarks with the same name, with the leading
9285 'refs/heads' stripped. Git submodules are converted to Git subrepos in
9286 Mercurial.
9287 The following options can be set with --config:
9289 convert.git.similarity
9291 specify how similar files modified in a commit must be to be
9292 imported as renames or copies, as a percentage between 0 (dis‐
9293 abled) and 100 (files must be identical). For example, 90 means
9294 that a delete/add pair will be imported as a rename if more than
9295 90% of the file hasn't changed. The default is 50.
9296 convert.git.findcopiesharder
9298 while detecting copies, look at all files in the working copy
9299 instead of just changed ones. This is very expensive for large
9300 projects, and is only effective when convert.git.similarity is
9301 greater than 0. The default is False.
9302 convert.git.renamelimit
9304 perform rename and copy detection up to this many changed files
9305 in a commit. Increasing this will make rename and copy detection
9306 more accurate but will significantly slow down computation on
9307 large projects. The option is only relevant if convert.git.simi‐
9308 larity is greater than 0. The default is 400.
9309 convert.git.committeractions
9311 list of actions to take when processing author and committer
9312 values.
9313 Git commits have separate author (who wrote the commit) and com‐
9315 mitter (who applied the commit) fields. Not all destinations
9316 support separate author and committer fields (including Mercu‐
9317 rial). This config option controls what to do with these author
9318 and committer fields during conversion.
9319 A value of messagedifferent will append a committer: ... line
9321 to the commit message if the Git committer is different from the
9322 author. The prefix of that line can be specified using the syn‐
9323 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
9324 ter:. When a prefix is specified, a space will always be
9325 inserted between the prefix and the value.
9326 messagealways behaves like messagedifferent except it will
9328 always result in a committer: ... line being appended to the
9329 commit message. This value is mutually exclusive with messaged‐
9330 ifferent.
9331 dropcommitter will remove references to the committer. Only ref‐
9333 erences to the author will remain. Actions that add references
9334 to the committer will have no effect when this is set.
9335 replaceauthor will replace the value of the author field with
9337 the committer. Other actions that add references to the commit‐
9338 ter will still take effect when this is set.
9339 The default is messagedifferent.
9341 convert.git.extrakeys
9343 list of extra keys from commit metadata to copy to the destina‐
9344 tion. Some Git repositories store extra metadata in commits. By
9345 default, this non-default metadata will be lost during conver‐
9346 sion. Setting this config option can retain that metadata. Some
9347 built-in keys such as parent and branch are not allowed to be
9348 copied.
9349 convert.git.remoteprefix
9351 remote refs are converted as bookmarks with con‐
9352 vert.git.remoteprefix as a prefix followed by a /. The default
9353 is 'remote'.
9354 convert.git.saverev
9356 whether to store the original Git commit ID in the metadata of
9357 the destination commit. The default is True.
9358 convert.git.skipsubmodules
9360 does not convert root level .gitmodules files or files with
9361 160000 mode indicating a submodule. Default is False.
9362 Perforce Source
9364 The Perforce (P4) importer can be given a p4 depot path or a client
9365 specification as source. It will convert all files in the source to a
9366 flat Mercurial repository, ignoring labels, branches and integrations.
9367 Note that when a depot path is given you then usually should specify a
9368 target directory, because otherwise the target may be named ...-hg.
9369 The following options can be set with --config:
9371 convert.p4.encoding
9373 specify the encoding to use when decoding standard output of the
9374 Perforce command line tool. The default is default system encod‐
9375 ing.
9376 convert.p4.startrev
9378 specify initial Perforce revision (a Perforce changelist num‐
9379 ber).
9380 Mercurial Destination
9382 The Mercurial destination will recognize Mercurial subrepositories in
9383 the destination directory, and update the .hgsubstate file automati‐
9384 cally if the destination subrepositories contain the
9385 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
9386 tories requires converting a single repository at a time, from the bot‐
9387 tom up.
9388 An example showing how to convert a repository with subrepositories:
9390 # so convert knows the type when it sees a non empty destination
9392 $ hg init converted
9393 $ hg convert orig/sub1 converted/sub1
9395 $ hg convert orig/sub2 converted/sub2
9396 $ hg convert orig converted
9397 The following options are supported:
9399 convert.hg.clonebranches
9401 dispatch source branches in separate clones. The default is
9402 False.
9403 convert.hg.tagsbranch
9405 branch name for tag revisions, defaults to default.
9406 convert.hg.usebranchnames
9408 preserve branch names. The default is True.
9409 convert.hg.sourcename
9411 records the given string as a 'convert_source' extra value on
9412 each commit made in the target repository. The default is None.
9413 convert.hg.preserve-hash
9415 only works with mercurial sources. Make convert prevent perfor‐
9416 mance improvement to the list of modified files in commits when
9417 such an improvement would cause the hash of a commit to change.
9418 The default is False.
9419 All Destinations
9421 All destination types accept the following options:
9422 convert.skiptags
9424 does not convert tags from the source repo to the target repo.
9425 The default is False.
9426 Options:
9428 --authors <FILE>
9430 username mapping filename (DEPRECATED) (use --authormap instead)
9431 -s,--source-type <TYPE>
9433 source repository type
9434 -d,--dest-type <TYPE>
9436 destination repository type
9437 -r,--rev <REV[+]>
9439 import up to source revision REV
9440 -A,--authormap <FILE>
9442 remap usernames using this file
9443 --filemap <FILE>
9445 remap file names using contents of file
9446 --full apply filemap changes by converting all files again
9448 --splicemap <FILE>
9450 splice synthesized history into place
9451 --branchmap <FILE>
9453 change branch names while converting
9454 --branchsort
9456 try to sort changesets by branches
9457 --datesort
9459 try to sort changesets by date
9460 --sourcesort
9462 preserve source changesets order
9463 --closesort
9465 try to reorder closed revisions
9466 [+] marked option can be specified multiple times
9468 eol
9470 automatically manage newlines in repository files
9471 This extension allows you to manage the type of line endings (CRLF or
9473 LF) that are used in the repository and in the local working directory.
9474 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
9475 thereby letting everybody use their OS native line endings.
9476 The extension reads its configuration from a versioned .hgeol configu‐
9478 ration file found in the root of the working directory. The .hgeol file
9479 use the same syntax as all other Mercurial configuration files. It uses
9480 two sections, [patterns] and [repository].
9481 The [patterns] section specifies how line endings should be converted
9483 between the working directory and the repository. The format is speci‐
9484 fied by a file pattern. The first match is used, so put more specific
9485 patterns first. The available line endings are LF, CRLF, and BIN.
9486 Files with the declared format of CRLF or LF are always checked out and
9488 stored in the repository in that format and files declared to be binary
9489 (BIN) are left unchanged. Additionally, native is an alias for checking
9490 out in the platform's default line ending: LF on Unix (including Mac OS
9491 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
9492 Mercurial's default behavior; it is only needed if you need to override
9493 a later, more general pattern.
9494 The optional [repository] section specifies the line endings to use for
9496 files stored in the repository. It has a single setting, native, which
9497 determines the storage line endings for files declared as native in the
9498 [patterns] section. It can be set to LF or CRLF. The default is LF. For
9499 example, this means that on Windows, files configured as native (CRLF
9500 by default) will be converted to LF when stored in the repository.
9501 Files declared as LF, CRLF, or BIN in the [patterns] section are always
9502 stored as-is in the repository.
9503 Example versioned .hgeol file:
9505 [patterns]
9507 **.py = native
9508 **.vcproj = CRLF
9509 **.txt = native
9510 Makefile = LF
9511 **.jpg = BIN
9512 [repository]
9514 native = LF
9515 Note The rules will first apply when files are touched in the working
9517 directory, e.g. by updating to null and back to tip to touch all
9518 files.
9519 The extension uses an optional [eol] section read from both the normal
9521 Mercurial configuration files and the .hgeol file, with the latter
9522 overriding the former. You can use that section to control the overall
9523 behavior. There are three settings:
9524 · eol.native (default os.linesep) can be set to LF or CRLF to override
9526 the default interpretation of native for checkout. This can be used
9527 with hg archive on Unix, say, to generate an archive where files have
9528 line endings for Windows.
9529 · eol.only-consistent (default True) can be set to False to make the
9531 extension convert files with inconsistent EOLs. Inconsistent means
9532 that there is both CRLF and LF present in the file. Such files are
9533 normally not touched under the assumption that they have mixed EOLs
9534 on purpose.
9535 · eol.fix-trailing-newline (default False) can be set to True to ensure
9537 that converted files end with a EOL character (either \n or \r\n as
9538 per the configured patterns).
9539 The extension provides cleverencode: and cleverdecode: filters like the
9541 deprecated win32text extension does. This means that you can disable
9542 win32text and enable eol and your filters will still work. You only
9543 need to these filters until you have prepared a .hgeol file.
9544 The win32text.forbid* hooks provided by the win32text extension have
9546 been unified into a single hook named eol.checkheadshook. The hook will
9547 lookup the expected line endings from the .hgeol file, which means you
9548 must migrate to a .hgeol file first before using the hook. eol.check‐
9549 headshook only checks heads, intermediate invalid revisions will be
9550 pushed. To forbid them completely, use the eol.checkallhook hook. These
9551 hooks are best used as pretxnchangegroup hooks.
9552 See hg help patterns for more information about the glob patterns used.
9554 extdiff
9556 command to allow external programs to compare revisions
9557 The extdiff Mercurial extension allows you to use external programs to
9559 compare revisions, or revision with working directory. The external
9560 diff programs are called with a configurable set of options and two
9561 non-option arguments: paths to directories containing snapshots of
9562 files to compare.
9563 If there is more than one file being compared and the "child" revision
9565 is the working directory, any modifications made in the external diff
9566 program will be copied back to the working directory from the temporary
9567 directory.
9568 The extdiff extension also allows you to configure new diff commands,
9570 so you do not need to type hg extdiff -p kdiff3 always.
9571 [extdiff]
9573 # add new command that runs GNU diff(1) in 'context diff' mode
9574 cdiff = gdiff -Nprc5
9575 ## or the old way:
9576 #cmd.cdiff = gdiff
9577 #opts.cdiff = -Nprc5
9578 # add new command called meld, runs meld (no need to name twice). If
9580 # the meld executable is not available, the meld tool in [merge-tools]
9581 # will be used, if available
9582 meld =
9583 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
9585 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
9586 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
9587 # your .vimrc
9588 vimdiff = gvim -f "+next" \
9589 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
9590 Tool arguments can include variables that are expanded at runtime:
9592 $parent1, $plabel1 - filename, descriptive label of first parent
9594 $child, $clabel - filename, descriptive label of child revision
9595 $parent2, $plabel2 - filename, descriptive label of second parent
9596 $root - repository root
9597 $parent is an alias for $parent1.
9598 The extdiff extension will look in your [diff-tools] and [merge-tools]
9600 sections for diff tool arguments, when none are specified in [extdiff].
9601 [extdiff]
9603 kdiff3 =
9604 [diff-tools]
9606 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9607 If a program has a graphical interface, it might be interesting to tell
9609 Mercurial about it. It will prevent the program from being mistakenly
9610 used in a terminal-only environment (such as an SSH terminal session),
9611 and will make hg extdiff --per-file open multiple file diffs at once
9612 instead of one by one (if you still want to open file diffs one by one,
9613 you can use the --confirm option).
9614 Declaring that a tool has a graphical interface can be done with the
9616 gui flag next to where diffargs are specified:
9617 [diff-tools]
9619 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9620 kdiff3.gui = true
9621 You can use -I/-X and list of file or directory names like normal hg
9623 diff command. The extdiff extension makes snapshots of only needed
9624 files, so running the external diff program will actually be pretty
9625 fast (at least faster than having to compare the entire tree).
9626 Commands
9628 File content management
9629 extdiff
9630 use external program to diff repository (or selected files):
9631 hg extdiff [OPT]... [FILE]...
9633 Show differences between revisions for the specified files, using an
9635 external program. The default program used is diff, with default
9636 options "-Npru".
9637 To select a different program, use the -p/--program option. The program
9639 will be passed the names of two directories to compare, unless the
9640 --per-file option is specified (see below). To pass additional options
9641 to the program, use -o/--option. These will be passed before the names
9642 of the directories or files to compare.
9643 When two revision arguments are given, then changes are shown between
9645 those revisions. If only one revision is specified then that revision
9646 is compared to the working directory, and, when no revisions are speci‐
9647 fied, the working directory files are compared to its parent.
9648 The --per-file option runs the external program repeatedly on each file
9650 to diff, instead of once on two directories. By default, this happens
9651 one by one, where the next file diff is open in the external program
9652 only once the previous external program (for the previous file diff)
9653 has exited. If the external program has a graphical interface, it can
9654 open all the file diffs at once instead of one by one. See hg help -e
9655 extdiff for information about how to tell Mercurial that a given pro‐
9656 gram has a graphical interface.
9657 The --confirm option will prompt the user before each invocation of the
9659 external program. It is ignored if --per-file isn't specified.
9660 Options:
9662 -p,--program <CMD>
9664 comparison program to run
9665 -o,--option <OPT[+]>
9667 pass option to comparison program
9668 -r,--rev <REV[+]>
9670 revision
9671 -c,--change <REV>
9673 change made by revision
9674 --per-file
9676 compare each file instead of revision snapshots
9677 --confirm
9679 prompt user before each external program invocation
9680 --patch
9682 compare patches for two revisions
9683 -I,--include <PATTERN[+]>
9685 include names matching the given patterns
9686 -X,--exclude <PATTERN[+]>
9688 exclude names matching the given patterns
9689 -S, --subrepos
9691 recurse into subrepositories
9692 [+] marked option can be specified multiple times
9694 factotum
9696 http authentication with factotum
9697 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
9699 platforms to provide authentication information for HTTP access. Con‐
9700 figuration entries specified in the auth section as well as authentica‐
9701 tion information provided in the repository URL are fully supported. If
9702 no prefix is specified, a value of "*" will be assumed.
9703 By default, keys are specified as:
9705 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
9707 If the factotum extension is unable to read the required key, one will
9709 be requested interactively.
9710 A configuration section is available to customize runtime behavior. By
9712 default, these entries are:
9713 [factotum]
9715 executable = /bin/auth/factotum
9716 mountpoint = /mnt/factotum
9717 service = hg
9718 The executable entry defines the full path to the factotum binary. The
9720 mountpoint entry defines the path to the factotum file service. Lastly,
9721 the service entry controls the service name used when reading keys.
9722 fastannotate
9724 yet another annotate implementation that might be faster (EXPERIMENTAL)
9725 The fastannotate extension provides a 'fastannotate' command that makes
9727 use of the linelog data structure as a cache layer and is expected to
9728 be faster than the vanilla 'annotate' if the cache is present.
9729 In most cases, fastannotate requires a setup that mainbranch is some
9731 pointer that always moves forward, to be most efficient.
9732 Using fastannotate together with linkrevcache would speed up building
9734 the annotate cache greatly. Run "debugbuildlinkrevcache" before "debug‐
9735 buildannotatecache".
9736 [fastannotate]
9738 # specify the main branch head. the internal linelog will only contain
9739 # the linear (ignoring p2) "mainbranch". since linelog cannot move
9740 # backwards without a rebuild, this should be something that always moves
9741 # forward, usually it is "master" or "@".
9742 mainbranch = master
9743 # fastannotate supports different modes to expose its feature.
9745 # a list of combination:
9746 # - fastannotate: expose the feature via the "fastannotate" command which
9747 # deals with everything in a most efficient way, and provides extra
9748 # features like --deleted etc.
9749 # - fctx: replace fctx.annotate implementation. note:
9750 # a. it is less efficient than the "fastannotate" command
9751 # b. it will make it practically impossible to access the old (disk
9752 # side-effect free) annotate implementation
9753 # c. it implies "hgweb".
9754 # - hgweb: replace hgweb's annotate implementation. conflict with "fctx".
9755 # (default: fastannotate)
9756 modes = fastannotate
9757 # default format when no format flags are used (default: number)
9759 defaultformat = changeset, user, date
9760 # serve the annotate cache via wire protocol (default: False)
9762 # tip: the .hg/fastannotate directory is portable - can be rsynced
9763 server = True
9764 # build annotate cache on demand for every client request (default: True)
9766 # disabling it could make server response faster, useful when there is a
9767 # cronjob building the cache.
9768 serverbuildondemand = True
9769 # update local annotate cache from remote on demand
9771 client = False
9772 # path to use when connecting to the remote server (default: default)
9774 remotepath = default
9775 # minimal length of the history of a file required to fetch linelog from
9777 # the server. (default: 10)
9778 clientfetchthreshold = 10
9779 # for "fctx" mode, always follow renames regardless of command line option.
9781 # this is a BC with the original command but will reduced the space needed
9782 # for annotate cache, and is useful for client-server setup since the
9783 # server will only provide annotate cache with default options (i.e. with
9784 # follow). do not affect "fastannotate" mode. (default: True)
9785 forcefollow = True
9786 # for "fctx" mode, always treat file as text files, to skip the "isbinary"
9788 # check. this is consistent with the "fastannotate" command and could help
9789 # to avoid a file fetch if remotefilelog is used. (default: True)
9790 forcetext = True
9791 # use unfiltered repo for better performance.
9793 unfilteredrepo = True
9794 # sacrifice correctness in some corner cases for performance. it does not
9796 # affect the correctness of the annotate cache being built. the option
9797 # is experimental and may disappear in the future (default: False)
9798 perfhack = True
9799 Commands
9801 Uncategorized commands
9802 fastexport
9803 export repositories as git fast-import stream
9804 Commands
9806 Change import/export
9807 fastexport
9808 export repository as git fast-import stream:
9809 hg fastexport [OPTION]... [REV]...
9811 This command lets you dump a repository as a human-readable text
9813 stream. It can be piped into corresponding import routines like "git
9814 fast-import". Incremental dumps can be created by using marks files.
9815 Options:
9817 -r,--rev <REV[+]>
9819 revisions to export
9820 -i,--import-marks <FILE>
9822 old marks file to read
9823 -e,--export-marks <FILE>
9825 new marks file to write
9826 -A,--authormap <FILE>
9828 remap usernames using this file
9829 [+] marked option can be specified multiple times
9831 fetch
9833 pull, update and merge in one command (DEPRECATED)
9834 Commands
9836 Remote repository management
9837 fetch
9838 pull changes from a remote repository, merge new changes if needed.:
9839 hg fetch [SOURCE]
9841 This finds all changes from the repository at the specified path or URL
9843 and adds them to the local repository.
9844 If the pulled changes add a new branch head, the head is automatically
9846 merged, and the result of the merge is committed. Otherwise, the work‐
9847 ing directory is updated to include the new changes.
9848 When a merge is needed, the working directory is first updated to the
9850 newly pulled changes. Local changes are then merged into the pulled
9851 changes. To switch the merge order, use --switch-parent.
9852 See hg help dates for a list of formats valid for -d/--date.
9854 Returns 0 on success.
9856 Options:
9858 -r,--rev <REV[+]>
9860 a specific revision you would like to pull
9861 --edit invoke editor on commit messages
9863 --force-editor
9865 edit commit message (DEPRECATED)
9866 --switch-parent
9868 switch parents when merging
9869 -m,--message <TEXT>
9871 use text as commit message
9872 -l,--logfile <FILE>
9874 read commit message from file
9875 -d,--date <DATE>
9877 record the specified date as commit date
9878 -u,--user <USER>
9880 record the specified user as committer
9881 -e,--ssh <CMD>
9883 specify ssh command to use
9884 --remotecmd <CMD>
9886 specify hg command to run on the remote side
9887 --insecure
9889 do not verify server certificate (ignoring web.cacerts config)
9890 [+] marked option can be specified multiple times
9892 fix
9894 rewrite file content in changesets or working copy (EXPERIMENTAL)
9895 Provides a command that runs configured tools on the contents of modi‐
9897 fied files, writing back any fixes to the working copy or replacing
9898 changesets.
9899 Here is an example configuration that causes hg fix to apply automatic
9901 formatting fixes to modified lines in C++ code:
9902 [fix]
9904 clang-format:command=clang-format --assume-filename={rootpath}
9905 clang-format:linerange=--lines={first}:{last}
9906 clang-format:pattern=set:**.cpp or **.hpp
9907 The :command suboption forms the first part of the shell command that
9909 will be used to fix a file. The content of the file is passed on stan‐
9910 dard input, and the fixed file content is expected on standard output.
9911 Any output on standard error will be displayed as a warning. If the
9912 exit status is not zero, the file will not be affected. A placeholder
9913 warning is displayed if there is a non-zero exit status but no standard
9914 error output. Some values may be substituted into the command:
9915 {rootpath} The path of the file being fixed, relative to the repo root
9917 {basename} The name of the file being fixed, without the directory path
9918 If the :linerange suboption is set, the tool will only be run if there
9920 are changed lines in a file. The value of this suboption is appended to
9921 the shell command once for every range of changed lines in the file.
9922 Some values may be substituted into the command:
9923 {first} The 1-based line number of the first line in the modified range
9925 {last} The 1-based line number of the last line in the modified range
9926 Deleted sections of a file will be ignored by :linerange, because there
9928 is no corresponding line range in the version being fixed.
9929 By default, tools that set :linerange will only be executed if there is
9931 at least one changed line range. This is meant to prevent accidents
9932 like running a code formatter in such a way that it unexpectedly refor‐
9933 mats the whole file. If such a tool needs to operate on unchanged
9934 files, it should set the :skipclean suboption to false.
9935 The :pattern suboption determines which files will be passed through
9937 each configured tool. See hg help patterns for possible values. How‐
9938 ever, all patterns are relative to the repo root, even if that text
9939 says they are relative to the current working directory. If there are
9940 file arguments to hg fix, the intersection of these patterns is used.
9941 There is also a configurable limit for the maximum size of file that
9943 will be processed by hg fix:
9944 [fix]
9946 maxfilesize = 2MB
9947 Normally, execution of configured tools will continue after a failure
9949 (indicated by a non-zero exit status). It can also be configured to
9950 abort after the first such failure, so that no files will be affected
9951 if any tool fails. This abort will also cause hg fix to exit with a
9952 non-zero status:
9953 [fix]
9955 failure = abort
9956 When multiple tools are configured to affect a file, they execute in an
9958 order defined by the :priority suboption. The priority suboption has a
9959 default value of zero for each tool. Tools are executed in order of
9960 descending priority. The execution order of tools with equal priority
9961 is unspecified. For example, you could use the 'sort' and 'head' utili‐
9962 ties to keep only the 10 smallest numbers in a text file by ensuring
9963 that 'sort' runs before 'head':
9964 [fix]
9966 sort:command = sort -n
9967 head:command = head -n 10
9968 sort:pattern = numbers.txt
9969 head:pattern = numbers.txt
9970 sort:priority = 2
9971 head:priority = 1
9972 To account for changes made by each tool, the line numbers used for
9974 incremental formatting are recomputed before executing the next tool.
9975 So, each tool may see different values for the arguments added by the
9976 :linerange suboption.
9977 Each fixer tool is allowed to return some metadata in addition to the
9979 fixed file content. The metadata must be placed before the file content
9980 on stdout, separated from the file content by a zero byte. The metadata
9981 is parsed as a JSON value (so, it should be UTF-8 encoded and contain
9982 no zero bytes). A fixer tool is expected to produce this metadata
9983 encoding if and only if the :metadata suboption is true:
9984 [fix]
9986 tool:command = tool --prepend-json-metadata
9987 tool:metadata = true
9988 The metadata values are passed to hooks, which can be used to print
9990 summaries or perform other post-fixing work. The supported hooks are:
9991 "postfixfile"
9993 Run once for each file in each revision where any fixer tools made changes
9994 to the file content. Provides "$HG_REV" and "$HG_PATH" to identify the file,
9995 and "$HG_METADATA" with a map of fixer names to metadata values from fixer
9996 tools that affected the file. Fixer tools that didn't affect the file have a
9997 value of None. Only fixer tools that executed are present in the metadata.
9998 "postfix"
10000 Run once after all files and revisions have been handled. Provides
10001 "$HG_REPLACEMENTS" with information about what revisions were created and
10002 made obsolete. Provides a boolean "$HG_WDIRWRITTEN" to indicate whether any
10003 files in the working copy were updated. Provides a list "$HG_METADATA"
10004 mapping fixer tool names to lists of metadata values returned from
10005 executions that modified a file. This aggregates the same metadata
10006 previously passed to the "postfixfile" hook.
10007 Fixer tools are run in the repository's root directory. This allows
10009 them to read configuration files from the working copy, or even write
10010 to the working copy. The working copy is not updated to match the
10011 revision being fixed. In fact, several revisions may be fixed in paral‐
10012 lel. Writes to the working copy are not amended into the revision being
10013 fixed; fixer tools should always write fixed file content back to std‐
10014 out as documented above.
10015 Commands
10017 File content management
10018 fix
10019 rewrite file content in changesets or working directory:
10020 hg fix [OPTION]... [FILE]...
10022 Runs any configured tools to fix the content of files. Only affects
10024 files with changes, unless file arguments are provided. Only affects
10025 changed lines of files, unless the --whole flag is used. Some tools may
10026 always affect the whole file regardless of --whole.
10027 If revisions are specified with --rev, those revisions will be checked,
10029 and they may be replaced with new revisions that have fixed file con‐
10030 tent. It is desirable to specify all descendants of each specified
10031 revision, so that the fixes propagate to the descendants. If all
10032 descendants are fixed at the same time, no merging, rebasing, or evolu‐
10033 tion will be required.
10034 If --working-dir is used, files with uncommitted changes in the working
10036 copy will be fixed. If the checked-out revision is also fixed, the
10037 working directory will update to the replacement revision.
10038 When determining what lines of each file to fix at each revision, the
10040 whole set of revisions being fixed is considered, so that fixes to ear‐
10041 lier revisions are not forgotten in later ones. The --base flag can be
10042 used to override this default behavior, though it is not usually desir‐
10043 able to do so.
10044 Options:
10046 --all fix all non-public non-obsolete revisions
10048 --base <REV[+]>
10050 revisions to diff against (overrides automatic selection, and
10051 applies to every revision being fixed)
10052 -r,--rev <REV[+]>
10054 revisions to fix (ADVANCED)
10055 -s,--source <REV[+]>
10057 fix the specified revisions and their descendants
10058 -w, --working-dir
10060 fix the working directory
10061 --whole
10063 always fix every line of a file
10064 [+] marked option can be specified multiple times
10066 fsmonitor
10068 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
10069 Integrates the file-watching program Watchman with Mercurial to produce
10071 faster status results.
10072 On a particular Linux system, for a real-world repository with over
10074 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
10075 the same system, with fsmonitor it takes about 0.3 seconds.
10076 fsmonitor requires no configuration -- it will tell Watchman about your
10078 repository as necessary. You'll need to install Watchman from
10079 https://facebook.github.io/watchman/ and make sure it is in your PATH.
10080 fsmonitor is incompatible with the largefiles and eol extensions, and
10082 will disable itself if any of those are active.
10083 The following configuration options exist:
10085 [fsmonitor]
10087 mode = {off, on, paranoid}
10088 When mode = off, fsmonitor will disable itself (similar to not loading
10090 the extension at all). When mode = on, fsmonitor will be enabled (the
10091 default). When mode = paranoid, fsmonitor will query both Watchman and
10092 the filesystem, and ensure that the results are consistent.
10093 [fsmonitor]
10095 timeout = (float)
10096 A value, in seconds, that determines how long fsmonitor will wait for
10098 Watchman to return results. Defaults to 2.0.
10099 [fsmonitor]
10101 blacklistusers = (list of userids)
10102 A list of usernames for which fsmonitor will disable itself altogether.
10104 [fsmonitor]
10106 walk_on_invalidate = (boolean)
10107 Whether or not to walk the whole repo ourselves when our cached state
10109 has been invalidated, for example when Watchman has been restarted or
10110 .hgignore rules have been changed. Walking the repo in that case can
10111 result in competing for I/O with Watchman. For large repos it is recom‐
10112 mended to set this value to false. You may wish to set this to true if
10113 you have a very fast filesystem that can outpace the IPC overhead of
10114 getting the result data for the full repo from Watchman. Defaults to
10115 false.
10116 [fsmonitor]
10118 warn_when_unused = (boolean)
10119 Whether to print a warning during certain operations when fsmonitor
10121 would be beneficial to performance but isn't enabled.
10122 [fsmonitor]
10124 warn_update_file_count = (integer)
10125 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
10127 be printed during working directory updates if this many files will be
10128 created.
10129 git
10131 grant Mercurial the ability to operate on Git repositories. (EXPERIMEN‐
10132 TAL)
10133 This is currently super experimental. It probably will consume your
10135 firstborn a la Rumpelstiltskin, etc.
10136 githelp
10138 try mapping git commands to Mercurial commands
10139 Tries to map a given git command to a Mercurial command:
10141 $ hg githelp -- git checkout master hg update master
10143 If an unknown command or parameter combination is detected, an error is
10145 produced.
10146 Commands
10148 Help
10149 githelp
10150 suggests the Mercurial equivalent of the given git command:
10151 hg githelp
10153 Usage: hg githelp -- <git command>
10155 aliases: git
10157 gpg
10159 commands to sign and verify changesets
10160 Commands
10162 Signing changes (GPG)
10163 sigcheck
10164 verify all the signatures there may be for a particular revision:
10165 hg sigcheck REV
10167 verify all the signatures there may be for a particular revision
10169 sign
10171 add a signature for the current or given revision:
10172 hg sign [OPTION]... [REV]...
10174 If no revision is given, the parent of the working directory is used,
10176 or tip if no revision is checked out.
10177 The gpg.cmd config setting can be used to specify the command to run. A
10179 default key can be specified with gpg.key.
10180 See hg help dates for a list of formats valid for -d/--date.
10182 Options:
10184 -l, --local
10186 make the signature local
10187 -f, --force
10189 sign even if the sigfile is modified
10190 --no-commit
10192 do not commit the sigfile after signing
10193 -k,--key <ID>
10195 the key id to sign with
10196 -m,--message <TEXT>
10198 use text as commit message
10199 -e, --edit
10201 invoke editor on commit messages
10202 -d,--date <DATE>
10204 record the specified date as commit date
10205 -u,--user <USER>
10207 record the specified user as committer
10208 sigs
10210 list signed changesets:
10211 hg sigs
10213 list signed changesets
10215 graphlog
10217 command to view revision graphs from a shell (DEPRECATED)
10218 The functionality of this extension has been include in core Mercurial
10220 since version 2.3. Please use hg log -G ... instead.
10221 This extension adds a --graph option to the incoming, outgoing and log
10223 commands. When this options is given, an ASCII representation of the
10224 revision graph is also shown.
10225 Commands
10227 Change navigation
10228 glog
10229 show revision history alongside an ASCII revision graph:
10230 hg glog [OPTION]... [FILE]
10232 Print a revision history alongside a revision graph drawn with ASCII
10234 characters.
10235 Nodes printed as an @ character are parents of the working directory.
10237 This is an alias to hg log -G.
10239 Options:
10241 -f, --follow
10243 follow changeset history, or file history across copies and
10244 renames
10245 --follow-first
10247 only follow the first parent of merge changesets (DEPRECATED)
10248 -d,--date <DATE>
10250 show revisions matching date spec
10251 -C, --copies
10253 show copied files
10254 -k,--keyword <TEXT[+]>
10256 do case-insensitive search for a given text
10257 -r,--rev <REV[+]>
10259 show the specified revision or revset
10260 --removed
10262 include revisions where files were removed
10263 -m, --only-merges
10265 show only merges (DEPRECATED)
10266 -u,--user <USER[+]>
10268 revisions committed by user
10269 --only-branch <BRANCH[+]>
10271 show only changesets within the given named branch (DEPRECATED)
10272 -b,--branch <BRANCH[+]>
10274 show changesets within the given named branch
10275 -P,--prune <REV[+]>
10277 do not display revision or any of its ancestors
10278 -p, --patch
10280 show patch
10281 -g, --git
10283 use git extended diff format
10284 -l,--limit <NUM>
10286 limit number of changes displayed
10287 -M, --no-merges
10289 do not show merges
10290 --stat output diffstat-style summary of changes
10292 -G, --graph
10294 show the revision DAG
10295 --style <STYLE>
10297 display using template map file (DEPRECATED)
10298 -T,--template <TEMPLATE>
10300 display with template
10301 -I,--include <PATTERN[+]>
10303 include names matching the given patterns
10304 -X,--exclude <PATTERN[+]>
10306 exclude names matching the given patterns
10307 [+] marked option can be specified multiple times
10309 hgk
10311 browse the repository in a graphical way
10312 The hgk extension allows browsing the history of a repository in a
10314 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
10315 distributed with Mercurial.)
10316 hgk consists of two parts: a Tcl script that does the displaying and
10318 querying of information, and an extension to Mercurial named hgk.py,
10319 which provides hooks for hgk to get information. hgk can be found in
10320 the contrib directory, and the extension is shipped in the hgext repos‐
10321 itory, and needs to be enabled.
10322 The hg view command will launch the hgk Tcl script. For this command to
10324 work, hgk must be in your search path. Alternately, you can specify the
10325 path to hgk in your configuration file:
10326 [hgk]
10328 path = /location/of/hgk
10329 hgk can make use of the extdiff extension to visualize revisions.
10331 Assuming you had already configured extdiff vdiff command, just add:
10332 [hgk]
10334 vdiff=vdiff
10335 Revisions context menu will now display additional entries to fire
10337 vdiff on hovered and selected revisions.
10338 Commands
10340 Change navigation
10341 view
10342 start interactive history viewer:
10343 hg view [-l LIMIT] [REVRANGE]
10345 start interactive history viewer
10347 Options:
10349 -l,--limit <NUM>
10351 limit number of changes displayed
10352 Uncategorized commands
10354 highlight
10355 syntax highlighting for hgweb (requires Pygments)
10356 It depends on the Pygments syntax highlighting library:
10358 http://pygments.org/
10359 There are the following configuration options:
10361 [web]
10363 pygments_style = <style> (default: colorful)
10364 highlightfiles = <fileset> (default: size('<5M'))
10365 highlightonlymatchfilename = <bool> (default False)
10366 highlightonlymatchfilename will only highlight files if their type
10368 could be identified by their filename. When this is not enabled (the
10369 default), Pygments will try very hard to identify the file type from
10370 content and any match (even matches with a low confidence score) will
10371 be used.
10372 histedit
10374 interactive history editing
10375 With this extension installed, Mercurial gains one new command: histe‐
10377 dit. Usage is as follows, assuming the following history:
10378 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
10380 | Add delta
10381 |
10382 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
10383 | Add gamma
10384 |
10385 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
10386 | Add beta
10387 |
10388 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10389 Add alpha
10390 If you were to run hg histedit c561b4e977df, you would see the follow‐
10392 ing file open in your editor:
10393 pick c561b4e977df Add beta
10395 pick 030b686bedc4 Add gamma
10396 pick 7c2fd3b9020c Add delta
10397 # Edit history between c561b4e977df and 7c2fd3b9020c
10399 #
10400 # Commits are listed from least to most recent
10401 #
10402 # Commands:
10403 # p, pick = use commit
10404 # e, edit = use commit, but stop for amending
10405 # f, fold = use commit, but combine it with the one above
10406 # r, roll = like fold, but discard this commit's description and date
10407 # d, drop = remove commit from history
10408 # m, mess = edit commit message without changing commit content
10409 # b, base = checkout changeset and apply further changesets from there
10410 #
10411 In this file, lines beginning with # are ignored. You must specify a
10413 rule for each revision in your history. For example, if you had meant
10414 to add gamma before beta, and then wanted to add delta in the same
10415 revision as beta, you would reorganize the file to look like this:
10416 pick 030b686bedc4 Add gamma
10418 pick c561b4e977df Add beta
10419 fold 7c2fd3b9020c Add delta
10420 # Edit history between c561b4e977df and 7c2fd3b9020c
10422 #
10423 # Commits are listed from least to most recent
10424 #
10425 # Commands:
10426 # p, pick = use commit
10427 # e, edit = use commit, but stop for amending
10428 # f, fold = use commit, but combine it with the one above
10429 # r, roll = like fold, but discard this commit's description and date
10430 # d, drop = remove commit from history
10431 # m, mess = edit commit message without changing commit content
10432 # b, base = checkout changeset and apply further changesets from there
10433 #
10434 At which point you close the editor and histedit starts working. When
10436 you specify a fold operation, histedit will open an editor when it
10437 folds those revisions together, offering you a chance to clean up the
10438 commit message:
10439 Add beta
10441 ***
10442 Add delta
10443 Edit the commit message to your liking, then close the editor. The date
10445 used for the commit will be the later of the two commits' dates. For
10446 this example, let's assume that the commit message was changed to Add
10447 beta and delta. After histedit has run and had a chance to remove any
10448 old or temporary revisions it needed, the history looks like this:
10449 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
10451 | Add beta and delta.
10452 |
10453 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10454 | Add gamma
10455 |
10456 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10457 Add alpha
10458 Note that histedit does not remove any revisions (even its own tempo‐
10460 rary ones) until after it has completed all the editing operations, so
10461 it will probably perform several strip operations when it's done. For
10462 the above example, it had to run strip twice. Strip can be slow depend‐
10463 ing on a variety of factors, so you might need to be a little patient.
10464 You can choose to keep the original revisions by passing the --keep
10465 flag.
10466 The edit operation will drop you back to a command prompt, allowing you
10468 to edit files freely, or even use hg record to commit some changes as a
10469 separate commit. When you're done, any remaining uncommitted changes
10470 will be committed as well. When done, run hg histedit --continue to
10471 finish this step. If there are uncommitted changes, you'll be prompted
10472 for a new commit message, but the default commit message will be the
10473 original message for the edit ed revision, and the date of the original
10474 commit will be preserved.
10475 The message operation will give you a chance to revise a commit message
10477 without changing the contents. It's a shortcut for doing edit immedi‐
10478 ately followed by hg histedit --continue`.
10479 If histedit encounters a conflict when moving a revision (while han‐
10481 dling pick or fold), it'll stop in a similar manner to edit with the
10482 difference that it won't prompt you for a commit message when done. If
10483 you decide at this point that you don't like how much work it will be
10484 to rearrange history, or that you made a mistake, you can use hg histe‐
10485 dit --abort to abandon the new changes you have made and return to the
10486 state before you attempted to edit your history.
10487 If we clone the histedit-ed example repository above and add four more
10489 changes, such that we have the following history:
10490 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
10492 | Add theta
10493 |
10494 o 5 140988835471 2009-04-27 18:04 -0500 stefan
10495 | Add eta
10496 |
10497 o 4 122930637314 2009-04-27 18:04 -0500 stefan
10498 | Add zeta
10499 |
10500 o 3 836302820282 2009-04-27 18:04 -0500 stefan
10501 | Add epsilon
10502 |
10503 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
10504 | Add beta and delta.
10505 |
10506 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10507 | Add gamma
10508 |
10509 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10510 Add alpha
10511 If you run hg histedit --outgoing on the clone then it is the same as
10513 running hg histedit 836302820282. If you need plan to push to a reposi‐
10514 tory that Mercurial does not detect to be related to the source repo,
10515 you can add a --force option.
10516 Config
10518 Histedit rule lines are truncated to 80 characters by default. You can
10519 customize this behavior by setting a different length in your configu‐
10520 ration file:
10521 [histedit]
10523 linelen = 120 # truncate rule lines at 120 characters
10524 The summary of a change can be customized as well:
10526 [histedit]
10528 summary-template = '{rev} {bookmarks} {desc|firstline}'
10529 The customized summary should be kept short enough that rule lines will
10531 fit in the configured line length. See above if that requires cus‐
10532 tomization.
10533 hg histedit attempts to automatically choose an appropriate base revi‐
10535 sion to use. To change which base revision is used, define a revset in
10536 your configuration file:
10537 [histedit]
10539 defaultrev = only(.) & draft()
10540 By default each edited revision needs to be present in histedit com‐
10542 mands. To remove revision you need to use drop operation. You can con‐
10543 figure the drop to be implicit for missing commits by adding:
10544 [histedit]
10546 dropmissing = True
10547 By default, histedit will close the transaction after each action. For
10549 performance purposes, you can configure histedit to use a single trans‐
10550 action across the entire histedit. WARNING: This setting introduces a
10551 significant risk of losing the work you've done in a histedit if the
10552 histedit aborts unexpectedly:
10553 [histedit]
10555 singletransaction = True
10556 Commands
10558 Change manipulation
10559 histedit
10560 interactively edit changeset history:
10561 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
10563 This command lets you edit a linear series of changesets (up to and
10565 including the working directory, which should be clean). You can:
10566 · pick to [re]order a changeset
10568 · drop to omit changeset
10570 · mess to reword the changeset commit message
10572 · fold to combine it with the preceding changeset (using the later
10574 date)
10575 · roll like fold, but discarding this commit's description and date
10577 · edit to edit this changeset (preserving date)
10579 · base to checkout changeset and apply further changesets from there
10581 There are a number of ways to select the root changeset:
10583 · Specify ANCESTOR directly
10585 · Use --outgoing -- it will be the first linear changeset not included
10587 in destination. (See hg help config.paths.default-push)
10588 · Otherwise, the value from the "histedit.defaultrev" config option is
10590 used as a revset to select the base revision when ANCESTOR is not
10591 specified. The first revision returned by the revset is used. By
10592 default, this selects the editable history that is unique to the
10593 ancestry of the working directory.
10594 If you use --outgoing, this command will abort if there are ambiguous
10596 outgoing revisions. For example, if there are multiple branches con‐
10597 taining outgoing revisions.
10598 Use "min(outgoing() and ::.)" or similar revset specification instead
10600 of --outgoing to specify edit target revision exactly in such ambiguous
10601 situation. See hg help revsets for detail about selecting revisions.
10602 Examples:
10604 · A number of changes have been made. Revision 3 is no longer
10606 needed.
10607 Start history editing from revision 3:
10609 hg histedit -r 3
10611 An editor opens, containing the list of revisions, with specific
10613 actions specified:
10614 pick 5339bf82f0ca 3 Zworgle the foobar
10616 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10617 pick 0a9639fcda9d 5 Morgify the cromulancy
10618 Additional information about the possible actions to take appears
10620 below the list of revisions.
10621 To remove revision 3 from the history, its action (at the begin‐
10623 ning of the relevant line) is changed to 'drop':
10624 drop 5339bf82f0ca 3 Zworgle the foobar
10626 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10627 pick 0a9639fcda9d 5 Morgify the cromulancy
10628 · A number of changes have been made. Revision 2 and 4 need to be
10630 swapped.
10631 Start history editing from revision 2:
10633 hg histedit -r 2
10635 An editor opens, containing the list of revisions, with specific
10637 actions specified:
10638 pick 252a1af424ad 2 Blorb a morgwazzle
10640 pick 5339bf82f0ca 3 Zworgle the foobar
10641 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10642 To swap revision 2 and 4, its lines are swapped in the editor:
10644 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10646 pick 5339bf82f0ca 3 Zworgle the foobar
10647 pick 252a1af424ad 2 Blorb a morgwazzle
10648 Returns 0 on success, 1 if user intervention is required (not only for
10650 intentional "edit" command, but also for resolving unexpected con‐
10651 flicts).
10652 Options:
10654 --commands <FILE>
10656 read history edits from the specified file
10657 -c, --continue
10659 continue an edit already in progress
10660 --edit-plan
10662 edit remaining actions list
10663 -k, --keep
10665 don't strip old nodes after edit is complete
10666 --abort
10668 abort an edit in progress
10669 -o, --outgoing
10671 changesets not found in destination
10672 -f, --force
10674 force outgoing even for unrelated repositories
10675 -r,--rev <REV[+]>
10677 first revision to be edited
10678 -T,--template <TEMPLATE>
10680 display with template
10681 [+] marked option can be specified multiple times
10683 hooklib
10685 collection of simple hooks for common tasks (EXPERIMENTAL)
10686 This extension provides a number of simple hooks to handle issues com‐
10688 monly found in repositories with many contributors: - email notifica‐
10689 tion when changesets move from draft to public phase - email notifica‐
10690 tion when changesets are obsoleted - enforcement of draft phase for all
10691 incoming changesets - enforcement of a no-branch-merge policy -
10692 enforcement of a no-multiple-heads policy
10693 The implementation of the hooks is subject to change, e.g. whether to
10695 implement them as individual hooks or merge them into the notify exten‐
10696 sion as option. The functionality itself is planned to be supported
10697 long-term.
10698 infinitepush
10700 store some pushes in a remote blob store on the server (EXPERIMEN‐
10701 TAL)
10702 IMPORTANT: if you use this extension, please contact
10704 mercurial-devel@mercurial-scm.org ASAP. This extension is believed to
10705 be unused and barring learning of users of this functionality, we will
10706 delete this code at the end of 2020.
10707 [infinitepush] # Server-side and client-side option. Pattern of the
10709 infinitepush bookmark branchpattern = PATTERN
10710 # Server or client server = False
10712 # Server-side option. Possible values: 'disk' or 'sql'. Fails if not
10714 set indextype = disk
10715 # Server-side option. Used only if indextype=sql. # Format:
10717 'IP:PORT:DB_NAME:USER:PASSWORD' sqlhost = IP:PORT:DB_NAME:USER:PASS‐
10718 WORD
10719 # Server-side option. Used only if indextype=disk. # Filesystem
10721 path to the index store indexpath = PATH
10722 # Server-side option. Possible values: 'disk' or 'external' # Fails
10724 if not set storetype = disk
10725 # Server-side option. # Path to the binary that will save bundle to
10727 the bundlestore # Formatted cmd line will be passed to it (see
10728 put_args) put_binary = put
10729 # Serser-side option. Used only if storetype=external. # Format
10731 cmd-line string for put binary. Placeholder: {filename} put_args =
10732 {filename}
10733 # Server-side option. # Path to the binary that get bundle from the
10735 bundlestore. # Formatted cmd line will be passed to it (see
10736 get_args) get_binary = get
10737 # Serser-side option. Used only if storetype=external. # Format
10739 cmd-line string for get binary. Placeholders: {filename} {handle}
10740 get_args = {filename} {handle}
10741 # Server-side option logfile = FIlE
10743 # Server-side option loglevel = DEBUG
10745 # Server-side option. Used only if indextype=sql. # Sets mysql
10747 wait_timeout option. waittimeout = 300
10748 # Server-side option. Used only if indextype=sql. # Sets mysql inn‐
10750 odb_lock_wait_timeout option. locktimeout = 120
10751 # Server-side option. Used only if indextype=sql. # Name of the
10753 repository reponame = ''
10754 # Client-side option. Used by --list-remote option. List of remote
10756 scratch # patterns to list if no patterns are specified. default‐
10757 remotepatterns = ['*']
10758 # Instructs infinitepush to forward all received bundle2 parts to
10760 the # bundle for storage. Defaults to False. storeallparts = True
10761 # routes each incoming push to the bundlestore. defaults to False
10763 pushtobundlestore = True
10764 [remotenames] # Client-side option # This option should be set only
10766 if remotenames extension is enabled. # Whether remote bookmarks are
10767 tracked by remotenames extension. bookmarks = True
10768 journal
10770 track previous positions of bookmarks (EXPERIMENTAL)
10771 This extension adds a new command: hg journal, which shows you where
10773 bookmarks were previously located.
10774 Commands
10776 Change organization
10777 journal
10778 show the previous position of bookmarks and the working copy:
10779 hg journal [OPTION]... [BOOKMARKNAME]
10781 The journal is used to see the previous commits that bookmarks and the
10783 working copy pointed to. By default the previous locations for the
10784 working copy. Passing a bookmark name will show all the previous posi‐
10785 tions of that bookmark. Use the --all switch to show previous locations
10786 for all bookmarks and the working copy; each line will then include the
10787 bookmark name, or '.' for the working copy, as well.
10788 If name starts with re:, the remainder of the name is treated as a reg‐
10790 ular expression. To match a name that actually starts with re:, use the
10791 prefix literal:.
10792 By default hg journal only shows the commit hash and the command that
10794 was running at that time. -v/--verbose will show the prior hash, the
10795 user, and the time at which it happened.
10796 Use -c/--commits to output log information on each commit hash; at this
10798 point you can use the usual --patch, --git, --stat and --template
10799 switches to alter the log output for these.
10800 hg journal -T json can be used to produce machine readable output.
10802 Options:
10804 --all show history for all names
10806 -c, --commits
10808 show commit metadata
10809 -p, --patch
10811 show patch
10812 -g, --git
10814 use git extended diff format
10815 -l,--limit <NUM>
10817 limit number of changes displayed
10818 --stat output diffstat-style summary of changes
10820 --style <STYLE>
10822 display using template map file (DEPRECATED)
10823 -T,--template <TEMPLATE>
10825 display with template
10826 keyword
10828 expand keywords in tracked files
10829 This extension expands RCS/CVS-like or self-customized $Keywords$ in
10831 tracked text files selected by your configuration.
10832 Keywords are only expanded in local repositories and not stored in the
10834 change history. The mechanism can be regarded as a convenience for the
10835 current user or for archive distribution.
10836 Keywords expand to the changeset data pertaining to the latest change
10838 relative to the working directory parent of each file.
10839 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
10841 sections of hgrc files.
10842 Example:
10844 [keyword]
10846 # expand keywords in every python file except those matching "x*"
10847 **.py =
10848 x* = ignore
10849 [keywordset]
10851 # prefer svn- over cvs-like default keywordmaps
10852 svn = True
10853 Note The more specific you are in your filename patterns the less you
10855 lose speed in huge repositories.
10856 For [keywordmaps] template mapping and expansion demonstration and con‐
10858 trol run hg kwdemo. See hg help templates for a list of available tem‐
10859 plates and filters.
10860 Three additional date template filters are provided:
10862 utcdate
10864 "2006/09/18 15:13:13"
10866 svnutcdate
10868 "2006-09-18 15:13:13Z"
10870 svnisodate
10872 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
10874 The default template mappings (view with hg kwdemo -d) can be replaced
10876 with customized keywords and templates. Again, run hg kwdemo to control
10877 the results of your configuration changes.
10878 Before changing/disabling active keywords, you must run hg kwshrink to
10880 avoid storing expanded keywords in the change history.
10881 To force expansion after enabling it, or a configuration change, run hg
10883 kwexpand.
10884 Expansions spanning more than one line and incremental expansions, like
10886 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
10887 expands to the first line of the changeset description.
10888 Commands
10890 Uncategorized commands
10891 kwdemo
10892 print [keywordmaps] configuration and an expansion example:
10893 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
10895 Show current, custom, or default keyword template maps and their expan‐
10897 sions.
10898 Extend the current configuration by specifying maps as arguments and
10900 using -f/--rcfile to source an external hgrc file.
10901 Use -d/--default to disable current configuration.
10903 See hg help templates for information on templates and filters.
10905 Options:
10907 -d, --default
10909 show default keyword template maps
10910 -f,--rcfile <FILE>
10912 read maps from rcfile
10913 kwexpand
10915 expand keywords in the working directory:
10916 hg kwexpand [OPTION]... [FILE]...
10918 Run after (re)enabling keyword expansion.
10920 kwexpand refuses to run if given files contain local changes.
10922 Options:
10924 -I,--include <PATTERN[+]>
10926 include names matching the given patterns
10927 -X,--exclude <PATTERN[+]>
10929 exclude names matching the given patterns
10930 [+] marked option can be specified multiple times
10932 kwfiles
10934 show files configured for keyword expansion:
10935 hg kwfiles [OPTION]... [FILE]...
10937 List which files in the working directory are matched by the [keyword]
10939 configuration patterns.
10940 Useful to prevent inadvertent keyword expansion and to speed up execu‐
10942 tion by including only files that are actual candidates for expansion.
10943 See hg help keyword on how to construct patterns both for inclusion and
10945 exclusion of files.
10946 With -A/--all and -v/--verbose the codes used to show the status of
10948 files are:
10949 K = keyword expansion candidate
10951 k = keyword expansion candidate (not tracked)
10952 I = ignored
10953 i = ignored (not tracked)
10954 Options:
10956 -A, --all
10958 show keyword status flags of all files
10959 -i, --ignore
10961 show files excluded from expansion
10962 -u, --unknown
10964 only show unknown (not tracked) files
10965 -I,--include <PATTERN[+]>
10967 include names matching the given patterns
10968 -X,--exclude <PATTERN[+]>
10970 exclude names matching the given patterns
10971 [+] marked option can be specified multiple times
10973 kwshrink
10975 revert expanded keywords in the working directory:
10976 hg kwshrink [OPTION]... [FILE]...
10978 Must be run before changing/disabling active keywords.
10980 kwshrink refuses to run if given files contain local changes.
10982 Options:
10984 -I,--include <PATTERN[+]>
10986 include names matching the given patterns
10987 -X,--exclude <PATTERN[+]>
10989 exclude names matching the given patterns
10990 [+] marked option can be specified multiple times
10992 largefiles
10994 track large binary files
10995 Large binary files tend to be not very compressible, not very diffable,
10997 and not at all mergeable. Such files are not handled efficiently by
10998 Mercurial's storage format (revlog), which is based on compressed
10999 binary deltas; storing large binary files as regular Mercurial files
11000 wastes bandwidth and disk space and increases Mercurial's memory usage.
11001 The largefiles extension addresses these problems by adding a central‐
11002 ized client-server layer on top of Mercurial: largefiles live in a cen‐
11003 tral store out on the network somewhere, and you only fetch the revi‐
11004 sions that you need when you need them.
11005 largefiles works by maintaining a "standin file" in .hglf/ for each
11007 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
11008 line) and are tracked by Mercurial. Largefile revisions are identified
11009 by the SHA-1 hash of their contents, which is written to the standin.
11010 largefiles uses that revision ID to get/put largefile revisions from/to
11011 the central store. This saves both disk space and bandwidth, since you
11012 don't need to retrieve all historical revisions of large files when you
11013 clone or pull.
11014 To start a new repository or add new large binary files, just add
11016 --large to your hg add command. For example:
11017 $ dd if=/dev/urandom of=randomdata count=2000
11019 $ hg add --large randomdata
11020 $ hg commit -m "add randomdata as a largefile"
11021 When you push a changeset that adds/modifies largefiles to a remote
11023 repository, its largefile revisions will be uploaded along with it.
11024 Note that the remote Mercurial must also have the largefiles extension
11025 enabled for this to work.
11026 When you pull a changeset that affects largefiles from a remote reposi‐
11028 tory, the largefiles for the changeset will by default not be pulled
11029 down. However, when you update to such a revision, any largefiles
11030 needed by that revision are downloaded and cached (if they have never
11031 been downloaded before). One way to pull largefiles when pulling is
11032 thus to use --update, which will update your working copy to the latest
11033 pulled revision (and thereby downloading any new largefiles).
11034 If you want to pull largefiles you don't need for update yet, then you
11036 can use pull with the --lfrev option or the hg lfpull command.
11037 If you know you are pulling from a non-default location and want to
11039 download all the largefiles that correspond to the new changesets at
11040 the same time, then you can pull with --lfrev "pulled()".
11041 If you just want to ensure that you will have the largefiles needed to
11043 merge or rebase with new heads that you are pulling, then you can pull
11044 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
11045 files that are new in the heads you are pulling.
11046 Keep in mind that network access may now be required to update to
11048 changesets that you have not previously updated to. The nature of the
11049 largefiles extension means that updating is no longer guaranteed to be
11050 a local-only operation.
11051 If you already have large files tracked by Mercurial without the large‐
11053 files extension, you will need to convert your repository in order to
11054 benefit from largefiles. This is done with the hg lfconvert command:
11055 $ hg lfconvert --size 10 oldrepo newrepo
11057 In repositories that already have largefiles in them, any new file over
11059 10MB will automatically be added as a largefile. To change this thresh‐
11060 old, set largefiles.minsize in your Mercurial config file to the mini‐
11061 mum size in megabytes to track as a largefile, or use the --lfsize
11062 option to the add command (also in megabytes):
11063 [largefiles]
11065 minsize = 2
11066 $ hg add --lfsize 2
11068 The largefiles.patterns config option allows you to specify a list of
11070 filename patterns (see hg help patterns) that should always be tracked
11071 as largefiles:
11072 [largefiles]
11074 patterns =
11075 *.jpg
11076 re:.*\.(png|bmp)$
11077 library.zip
11078 content/audio/*
11079 Files that match one of these patterns will be added as largefiles
11081 regardless of their size.
11082 The largefiles.minsize and largefiles.patterns config options will be
11084 ignored for any repositories not already containing a largefile. To add
11085 the first largefile to a repository, you must explicitly do so with the
11086 --large flag passed to the hg add command.
11087 Commands
11089 Uncategorized commands
11090 lfconvert
11091 convert a normal repository to a largefiles repository:
11092 hg lfconvert SOURCE DEST [FILE ...]
11094 Convert repository SOURCE to a new repository DEST, identical to SOURCE
11096 except that certain files will be converted as largefiles: specifi‐
11097 cally, any file that matches any PATTERN or whose size is above the
11098 minimum size threshold is converted as a largefile. The size used to
11099 determine whether or not to track a file as a largefile is the size of
11100 the first version of the file. The minimum size can be specified either
11101 with --size or in configuration as largefiles.size.
11102 After running this command you will need to make sure that largefiles
11104 is enabled anywhere you intend to push the new repository.
11105 Use --to-normal to convert largefiles back to normal files; after this,
11107 the DEST repository can be used without largefiles at all.
11108 Options:
11110 -s,--size <SIZE>
11112 minimum size (MB) for files to be converted as largefiles
11113 --to-normal
11115 convert from a largefiles repo to a normal repo
11116 lfpull
11118 pull largefiles for the specified revisions from the specified source:
11119 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
11121 Pull largefiles that are referenced from local changesets but missing
11123 locally, pulling from a remote repository to the local cache.
11124 If SOURCE is omitted, the 'default' path will be used. See hg help
11126 urls for more information.
11127 Some examples:
11129 · pull largefiles for all branch heads:
11131 hg lfpull -r "head() and not closed()"
11133 · pull largefiles on the default branch:
11135 hg lfpull -r "branch(default)"
11137 Options:
11139 -r,--rev <VALUE[+]>
11141 pull largefiles for these revisions
11142 -e,--ssh <CMD>
11144 specify ssh command to use
11145 --remotecmd <CMD>
11147 specify hg command to run on the remote side
11148 --insecure
11150 do not verify server certificate (ignoring web.cacerts config)
11151 [+] marked option can be specified multiple times
11153 lfs
11155 lfs - large file support (EXPERIMENTAL)
11156 This extension allows large files to be tracked outside of the normal
11158 repository storage and stored on a centralized server, similar to the
11159 largefiles extension. The git-lfs protocol is used when communicating
11160 with the server, so existing git infrastructure can be harnessed. Even
11161 though the files are stored outside of the repository, they are still
11162 integrity checked in the same manner as normal files.
11163 The files stored outside of the repository are downloaded on demand,
11165 which reduces the time to clone, and possibly the local disk usage.
11166 This changes fundamental workflows in a DVCS, so careful thought should
11167 be given before deploying it. hg convert can be used to convert LFS
11168 repositories to normal repositories that no longer require this exten‐
11169 sion, and do so without changing the commit hashes. This allows the
11170 extension to be disabled if the centralized workflow becomes burden‐
11171 some. However, the pre and post convert clones will not be able to
11172 communicate with each other unless the extension is enabled on both.
11173 To start a new repository, or to add LFS files to an existing one, just
11175 create an .hglfs file as described below in the root directory of the
11176 repository. Typically, this file should be put under version control,
11177 so that the settings will propagate to other repositories with push and
11178 pull. During any commit, Mercurial will consult this file to determine
11179 if an added or modified file should be stored externally. The type of
11180 storage depends on the characteristics of the file at each commit. A
11181 file that is near a size threshold may switch back and forth between
11182 LFS and normal storage, as needed.
11183 Alternately, both normal repositories and largefile controlled reposi‐
11185 tories can be converted to LFS by using hg convert and the lfs.track
11186 config option described below. The .hglfs file should then be created
11187 and added, to control subsequent LFS selection. The hashes are also
11188 unchanged in this case. The LFS and non-LFS repositories can be dis‐
11189 tinguished because the LFS repository will abort any command if this
11190 extension is disabled.
11191 Committed LFS files are held locally, until the repository is pushed.
11193 Prior to pushing the normal repository data, the LFS files that are
11194 tracked by the outgoing commits are automatically uploaded to the con‐
11195 figured central server. No LFS files are transferred on hg pull or hg
11196 clone. Instead, the files are downloaded on demand as they need to be
11197 read, if a cached copy cannot be found locally. Both committing and
11198 downloading an LFS file will link the file to a usercache, to speed up
11199 future access. See the usercache config setting described below.
11200 The extension reads its configuration from a versioned .hglfs configu‐
11202 ration file found in the root of the working directory. The .hglfs file
11203 uses the same syntax as all other Mercurial configuration files. It
11204 uses a single section, [track].
11205 The [track] section specifies which files are stored as LFS (or not).
11207 Each line is keyed by a file pattern, with a predicate value. The
11208 first file pattern match is used, so put more specific patterns first.
11209 The available predicates are all(), none(), and size(). See "hg help
11210 filesets.size" for the latter.
11211 Example versioned .hglfs file:
11213 [track]
11215 # No Makefile or python file, anywhere, will be LFS
11216 **Makefile = none()
11217 **.py = none()
11218 **.zip = all()
11220 **.exe = size(">1MB")
11221 # Catchall for everything not matched above
11223 ** = size(">10MB")
11224 Configs:
11226 [lfs]
11228 # Remote endpoint. Multiple protocols are supported:
11229 # - http(s)://user:pass@example.com/path
11230 # git-lfs endpoint
11231 # - file:///tmp/path
11232 # local filesystem, usually for testing
11233 # if unset, lfs will assume the remote repository also handles blob storage
11234 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
11235 # use this value.
11236 # (default: unset)
11237 url = https://example.com/repo.git/info/lfs
11238 # Which files to track in LFS. Path tests are "**.extname" for file
11240 # extensions, and "path:under/some/directory" for path prefix. Both
11241 # are relative to the repository root.
11242 # File size can be tested with the "size()" fileset, and tests can be
11243 # joined with fileset operators. (See "hg help filesets.operators".)
11244 #
11245 # Some examples:
11246 # - all() # everything
11247 # - none() # nothing
11248 # - size(">20MB") # larger than 20MB
11249 # - !**.txt # anything not a *.txt file
11250 # - **.zip | **.tar.gz | **.7z # some types of compressed files
11251 # - path:bin # files under "bin" in the project root
11252 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
11253 # | (path:bin & !path:/bin/README) | size(">1GB")
11254 # (default: none())
11255 #
11256 # This is ignored if there is a tracked '.hglfs' file, and this setting
11257 # will eventually be deprecated and removed.
11258 track = size(">10M")
11259 # how many times to retry before giving up on transferring an object
11261 retry = 5
11262 # the local directory to store lfs files for sharing across local clones.
11264 # If not set, the cache is located in an OS specific cache location.
11265 usercache = /path/to/global/cache
11266 Commands
11268 Uncategorized commands
11269 logtoprocess
11270 send ui.log() data to a subprocess (EXPERIMENTAL)
11271 This extension lets you specify a shell command per ui.log() event,
11273 sending all remaining arguments to as environment variables to that
11274 command.
11275 Positional arguments construct a log message, which is passed in the
11277 MSG1 environment variables. Each keyword argument is set as a
11278 OPT_UPPERCASE_KEY variable (so the key is uppercased, and prefixed with
11279 OPT_). The original event name is passed in the EVENT environment vari‐
11280 able, and the process ID of mercurial is given in HGPID.
11281 So given a call ui.log('foo', 'bar %s ', 'baz', spam='eggs'), a script
11283 configured for the `foo event can expect an environment with MSG1=bar
11284 baz, and OPT_SPAM=eggs.
11285 Scripts are configured in the [logtoprocess] section, each key an event
11287 name. For example:
11288 [logtoprocess]
11290 commandexception = echo "$MSG1" > /var/log/mercurial_exceptions.log
11291 would log the warning message and traceback of any failed command dis‐
11293 patch.
11294 Scripts are run asynchronously as detached daemon processes; mercurial
11296 will not ensure that they exit cleanly.
11297 mq
11299 manage a stack of patches
11300 This extension lets you work with a stack of patches in a Mercurial
11302 repository. It manages two stacks of patches - all known patches, and
11303 applied patches (subset of known patches).
11304 Known patches are represented as patch files in the .hg/patches direc‐
11306 tory. Applied patches are both patch files and changesets.
11307 Common tasks (use hg help COMMAND for more details):
11309 create new patch qnew
11311 import existing patch qimport
11312 print patch series qseries
11314 print applied patches qapplied
11315 add known patch to applied stack qpush
11317 remove patch from applied stack qpop
11318 refresh contents of top applied patch qrefresh
11319 By default, mq will automatically use git patches when required to
11321 avoid losing file mode changes, copy records, binary files or empty
11322 files creations or deletions. This behavior can be configured with:
11323 [mq]
11325 git = auto/keep/yes/no
11326 If set to 'keep', mq will obey the [diff] section configuration while
11328 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
11329 mq will override the [diff] section and always generate git or regular
11330 patches, possibly losing data in the second case.
11331 It may be desirable for mq changesets to be kept in the secret phase
11333 (see hg help phases), which can be enabled with the following setting:
11334 [mq]
11336 secret = True
11337 You will by default be managing a patch queue named "patches". You can
11339 create other, independent patch queues with the hg qqueue command.
11340 If the working directory contains uncommitted files, qpush, qpop and
11342 qgoto abort immediately. If -f/--force is used, the changes are dis‐
11343 carded. Setting:
11344 [mq]
11346 keepchanges = True
11347 make them behave as if --keep-changes were passed, and non-conflicting
11349 local changes will be tolerated and preserved. If incompatible options
11350 such as -f/--force or --exact are passed, this setting is ignored.
11351 This extension used to provide a strip command. This command now lives
11353 in the strip extension.
11354 Commands
11356 Repository creation
11357 qclone
11358 clone main and patch repository at same time:
11359 hg qclone [OPTION]... SOURCE [DEST]
11361 If source is local, destination will have no patches applied. If source
11363 is remote, this command can not check if patches are applied in source,
11364 so cannot guarantee that patches are not applied in destination. If you
11365 clone remote repository, be sure before that it has no patches applied.
11366 Source patch repository is looked for in <src>/.hg/patches by default.
11368 Use -p <url> to change.
11369 The patch directory must be a nested Mercurial repository, as would be
11371 created by hg init --mq.
11372 Return 0 on success.
11374 Options:
11376 --pull use pull protocol to copy metadata
11378 -U, --noupdate
11380 do not update the new working directories
11381 --uncompressed
11383 use uncompressed transfer (fast over LAN)
11384 -p,--patches <REPO>
11386 location of source patch repository
11387 -e,--ssh <CMD>
11389 specify ssh command to use
11390 --remotecmd <CMD>
11392 specify hg command to run on the remote side
11393 --insecure
11395 do not verify server certificate (ignoring web.cacerts config)
11396 qinit
11398 init a new queue repository (DEPRECATED):
11399 hg qinit [-c]
11401 The queue repository is unversioned by default. If -c/--create-repo is
11403 specified, qinit will create a separate nested repository for patches
11404 (qinit -c may also be run later to convert an unversioned patch reposi‐
11405 tory into a versioned one). You can use qcommit to commit changes to
11406 this queue repository.
11407 This command is deprecated. Without -c, it's implied by other relevant
11409 commands. With -c, use hg init --mq instead.
11410 Options:
11412 -c, --create-repo
11414 create queue repository
11415 Change creation
11417 qcommit
11418 commit changes in the queue repository (DEPRECATED):
11419 hg qcommit [OPTION]... [FILE]...
11421 This command is deprecated; use hg commit --mq instead.
11423 Options:
11425 -A, --addremove
11427 mark new/missing files as added/removed before committing
11428 --close-branch
11430 mark a branch head as closed
11431 --amend
11433 amend the parent of the working directory
11434 -s, --secret
11436 use the secret phase for committing
11437 -e, --edit
11439 invoke editor on commit messages
11440 --force-close-branch
11442 forcibly close branch from a non-head changeset (ADVANCED)
11443 -i, --interactive
11445 use interactive mode
11446 -I,--include <PATTERN[+]>
11448 include names matching the given patterns
11449 -X,--exclude <PATTERN[+]>
11451 exclude names matching the given patterns
11452 -m,--message <TEXT>
11454 use text as commit message
11455 -l,--logfile <FILE>
11457 read commit message from file
11458 -d,--date <DATE>
11460 record the specified date as commit date
11461 -u,--user <USER>
11463 record the specified user as committer
11464 -S, --subrepos
11466 recurse into subrepositories
11467 [+] marked option can be specified multiple times
11469 aliases: qci
11471 qnew
11473 create a new patch:
11474 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
11476 qnew creates a new patch on top of the currently-applied patch (if
11478 any). The patch will be initialized with any outstanding changes in the
11479 working directory. You may also use -I/--include, -X/--exclude, and/or
11480 a list of files after the patch name to add only changes to matching
11481 files to the new patch, leaving the rest as uncommitted modifications.
11482 -u/--user and -d/--date can be used to set the (given) user and date,
11484 respectively. -U/--currentuser and -D/--currentdate set user to current
11485 user and date to current date.
11486 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
11488 the commit message. If none is specified, the header is empty and the
11489 commit message is '[mq]: PATCH'.
11490 Use the -g/--git option to keep the patch in the git extended diff for‐
11492 mat. Read the diffs help topic for more information on why this is
11493 important for preserving permission changes and copy/rename informa‐
11494 tion.
11495 Returns 0 on successful creation of a new patch.
11497 Options:
11499 -e, --edit
11501 invoke editor on commit messages
11502 -f, --force
11504 import uncommitted changes (DEPRECATED)
11505 -g, --git
11507 use git extended diff format
11508 -U, --currentuser
11510 add "From: <current user>" to patch
11511 -u,--user <USER>
11513 add "From: <USER>" to patch
11514 -D, --currentdate
11516 add "Date: <current date>" to patch
11517 -d,--date <DATE>
11519 add "Date: <DATE>" to patch
11520 -I,--include <PATTERN[+]>
11522 include names matching the given patterns
11523 -X,--exclude <PATTERN[+]>
11525 exclude names matching the given patterns
11526 -m,--message <TEXT>
11528 use text as commit message
11529 -l,--logfile <FILE>
11531 read commit message from file
11532 [+] marked option can be specified multiple times
11534 qrefresh
11536 update the current patch:
11537 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
11539 If any file patterns are provided, the refreshed patch will contain
11541 only the modifications that match those patterns; the remaining modifi‐
11542 cations will remain in the working directory.
11543 If -s/--short is specified, files currently included in the patch will
11545 be refreshed just like matched files and remain in the patch.
11546 If -e/--edit is specified, Mercurial will start your configured editor
11548 for you to enter a message. In case qrefresh fails, you will find a
11549 backup of your message in .hg/last-message.txt.
11550 hg add/remove/copy/rename work as usual, though you might want to use
11552 git-style patches (-g/--git or [diff] git=1) to track copies and
11553 renames. See the diffs help topic for more information on the git diff
11554 format.
11555 Returns 0 on success.
11557 Options:
11559 -e, --edit
11561 invoke editor on commit messages
11562 -g, --git
11564 use git extended diff format
11565 -s, --short
11567 refresh only files already in the patch and specified files
11568 -U, --currentuser
11570 add/update author field in patch with current user
11571 -u,--user <USER>
11573 add/update author field in patch with given user
11574 -D, --currentdate
11576 add/update date field in patch with current date
11577 -d,--date <DATE>
11579 add/update date field in patch with given date
11580 -I,--include <PATTERN[+]>
11582 include names matching the given patterns
11583 -X,--exclude <PATTERN[+]>
11585 exclude names matching the given patterns
11586 -m,--message <TEXT>
11588 use text as commit message
11589 -l,--logfile <FILE>
11591 read commit message from file
11592 [+] marked option can be specified multiple times
11594 Change manipulation
11596 qfold
11597 fold the named patches into the current patch:
11598 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
11600 Patches must not yet be applied. Each patch will be successively
11602 applied to the current patch in the order given. If all the patches
11603 apply successfully, the current patch will be refreshed with the new
11604 cumulative patch, and the folded patches will be deleted. With
11605 -k/--keep, the folded patch files will not be removed afterwards.
11606 The header for each folded patch will be concatenated with the current
11608 patch header, separated by a line of * * *.
11609 Returns 0 on success.
11611 Options:
11613 -e, --edit
11615 invoke editor on commit messages
11616 -k, --keep
11618 keep folded patch files
11619 -m,--message <TEXT>
11621 use text as commit message
11622 -l,--logfile <FILE>
11624 read commit message from file
11625 Change organization
11627 qapplied
11628 print the patches already applied:
11629 hg qapplied [-1] [-s] [PATCH]
11631 Returns 0 on success.
11633 Options:
11635 -1, --last
11637 show only the preceding applied patch
11638 -s, --summary
11640 print first line of patch header
11641 qdelete
11643 remove patches from queue:
11644 hg qdelete [-k] [PATCH]...
11646 The patches must not be applied, and at least one patch is required.
11648 Exact patch identifiers must be given. With -k/--keep, the patch files
11649 are preserved in the patch directory.
11650 To stop managing a patch and move it into permanent history, use the hg
11652 qfinish command.
11653 Options:
11655 -k, --keep
11657 keep patch file
11658 -r,--rev <REV[+]>
11660 stop managing a revision (DEPRECATED)
11661 [+] marked option can be specified multiple times
11663 aliases: qremove qrm
11665 qfinish
11667 move applied patches into repository history:
11668 hg qfinish [-a] [REV]...
11670 Finishes the specified revisions (corresponding to applied patches) by
11672 moving them out of mq control into regular repository history.
11673 Accepts a revision range or the -a/--applied option. If --applied is
11675 specified, all applied mq revisions are removed from mq control. Other‐
11676 wise, the given revisions must be at the base of the stack of applied
11677 patches.
11678 This can be especially useful if your changes have been applied to an
11680 upstream repository, or if you are about to push your changes to
11681 upstream.
11682 Returns 0 on success.
11684 Options:
11686 -a, --applied
11688 finish all applied changesets
11689 qgoto
11691 push or pop patches until named patch is at top of stack:
11692 hg qgoto [OPTION]... PATCH
11694 Returns 0 on success.
11696 Options:
11698 --keep-changes
11700 tolerate non-conflicting local changes
11701 -f, --force
11703 overwrite any local changes
11704 --no-backup
11706 do not save backup copies of files
11707 qguard
11709 set or print guards for a patch:
11710 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
11712 Guards control whether a patch can be pushed. A patch with no guards is
11714 always pushed. A patch with a positive guard ("+foo") is pushed only if
11715 the hg qselect command has activated it. A patch with a negative guard
11716 ("-foo") is never pushed if the hg qselect command has activated it.
11717 With no arguments, print the currently active guards. With arguments,
11719 set guards for the named patch.
11720 Note Specifying negative guards now requires '--'.
11722 To set guards on another patch:
11724 hg qguard other.patch -- +2.6.17 -stable
11726 Returns 0 on success.
11728 Options:
11730 -l, --list
11732 list all patches and guards
11733 -n, --none
11735 drop all guards
11736 qheader
11738 print the header of the topmost or specified patch:
11739 hg qheader [PATCH]
11741 Returns 0 on success.
11743 qnext
11745 print the name of the next pushable patch:
11746 hg qnext [-s]
11748 Returns 0 on success.
11750 Options:
11752 -s, --summary
11754 print first line of patch header
11755 qpop
11757 pop the current patch off the stack:
11758 hg qpop [-a] [-f] [PATCH | INDEX]
11760 Without argument, pops off the top of the patch stack. If given a patch
11762 name, keeps popping off patches until the named patch is at the top of
11763 the stack.
11764 By default, abort if the working directory contains uncommitted
11766 changes. With --keep-changes, abort only if the uncommitted files over‐
11767 lap with patched files. With -f/--force, backup and discard changes
11768 made to such files.
11769 Return 0 on success.
11771 Options:
11773 -a, --all
11775 pop all patches
11776 -n,--name <NAME>
11778 queue name to pop (DEPRECATED)
11779 --keep-changes
11781 tolerate non-conflicting local changes
11782 -f, --force
11784 forget any local changes to patched files
11785 --no-backup
11787 do not save backup copies of files
11788 qprev
11790 print the name of the preceding applied patch:
11791 hg qprev [-s]
11793 Returns 0 on success.
11795 Options:
11797 -s, --summary
11799 print first line of patch header
11800 qpush
11802 push the next patch onto the stack:
11803 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
11805 By default, abort if the working directory contains uncommitted
11807 changes. With --keep-changes, abort only if the uncommitted files over‐
11808 lap with patched files. With -f/--force, backup and patch over uncom‐
11809 mitted changes.
11810 Return 0 on success.
11812 Options:
11814 --keep-changes
11816 tolerate non-conflicting local changes
11817 -f, --force
11819 apply on top of local changes
11820 -e, --exact
11822 apply the target patch to its recorded parent
11823 -l, --list
11825 list patch name in commit text
11826 -a, --all
11828 apply all patches
11829 -m, --merge
11831 merge from another queue (DEPRECATED)
11832 -n,--name <NAME>
11834 merge queue name (DEPRECATED)
11835 --move reorder patch series and apply only the patch
11837 --no-backup
11839 do not save backup copies of files
11840 qqueue
11842 manage multiple patch queues:
11843 hg qqueue [OPTION] [QUEUE]
11845 Supports switching between different patch queues, as well as creating
11847 new patch queues and deleting existing ones.
11848 Omitting a queue name or specifying -l/--list will show you the regis‐
11850 tered queues - by default the "normal" patches queue is registered. The
11851 currently active queue will be marked with "(active)". Specifying
11852 --active will print only the name of the active queue.
11853 To create a new queue, use -c/--create. The queue is automatically made
11855 active, except in the case where there are applied patches from the
11856 currently active queue in the repository. Then the queue will only be
11857 created and switching will fail.
11858 To delete an existing queue, use --delete. You cannot delete the cur‐
11860 rently active queue.
11861 Returns 0 on success.
11863 Options:
11865 -l, --list
11867 list all available queues
11868 --active
11870 print name of active queue
11871 -c, --create
11873 create new queue
11874 --rename
11876 rename active queue
11877 --delete
11879 delete reference to queue
11880 --purge
11882 delete queue, and remove patch dir
11883 qrename
11885 rename a patch:
11886 hg qrename PATCH1 [PATCH2]
11888 With one argument, renames the current patch to PATCH1. With two argu‐
11890 ments, renames PATCH1 to PATCH2.
11891 Returns 0 on success.
11893 aliases: qmv
11895 qrestore
11897 restore the queue state saved by a revision (DEPRECATED):
11898 hg qrestore [-d] [-u] REV
11900 This command is deprecated, use hg rebase instead.
11902 Options:
11904 -d, --delete
11906 delete save entry
11907 -u, --update
11909 update queue working directory
11910 qsave
11912 save current queue state (DEPRECATED):
11913 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
11915 This command is deprecated, use hg rebase instead.
11917 Options:
11919 -c, --copy
11921 copy patch directory
11922 -n,--name <NAME>
11924 copy directory name
11925 -e, --empty
11927 clear queue status file
11928 -f, --force
11930 force copy
11931 -m,--message <TEXT>
11933 use text as commit message
11934 -l,--logfile <FILE>
11936 read commit message from file
11937 qselect
11939 set or print guarded patches to push:
11940 hg qselect [OPTION]... [GUARD]...
11942 Use the hg qguard command to set or print guards on patch, then use
11944 qselect to tell mq which guards to use. A patch will be pushed if it
11945 has no guards or any positive guards match the currently selected
11946 guard, but will not be pushed if any negative guards match the current
11947 guard. For example:
11948 qguard foo.patch -- -stable (negative guard)
11950 qguard bar.patch +stable (positive guard)
11951 qselect stable
11952 This activates the "stable" guard. mq will skip foo.patch (because it
11954 has a negative match) but push bar.patch (because it has a positive
11955 match).
11956 With no arguments, prints the currently active guards. With one argu‐
11958 ment, sets the active guard.
11959 Use -n/--none to deactivate guards (no other arguments needed). When
11961 no guards are active, patches with positive guards are skipped and
11962 patches with negative guards are pushed.
11963 qselect can change the guards on applied patches. It does not pop
11965 guarded patches by default. Use --pop to pop back to the last applied
11966 patch that is not guarded. Use --reapply (which implies --pop) to push
11967 back to the current patch afterwards, but skip guarded patches.
11968 Use -s/--series to print a list of all guards in the series file (no
11970 other arguments needed). Use -v for more information.
11971 Returns 0 on success.
11973 Options:
11975 -n, --none
11977 disable all guards
11978 -s, --series
11980 list all guards in series file
11981 --pop pop to before first guarded applied patch
11983 --reapply
11985 pop, then reapply patches
11986 qseries
11988 print the entire series file:
11989 hg qseries [-ms]
11991 Returns 0 on success.
11993 Options:
11995 -m, --missing
11997 print patches not in series
11998 -s, --summary
12000 print first line of patch header
12001 qtop
12003 print the name of the current patch:
12004 hg qtop [-s]
12006 Returns 0 on success.
12008 Options:
12010 -s, --summary
12012 print first line of patch header
12013 qunapplied
12015 print the patches not yet applied:
12016 hg qunapplied [-1] [-s] [PATCH]
12018 Returns 0 on success.
12020 Options:
12022 -1, --first
12024 show only the first patch
12025 -s, --summary
12027 print first line of patch header
12028 File content management
12030 qdiff
12031 diff of the current patch and subsequent modifications:
12032 hg qdiff [OPTION]... [FILE]...
12034 Shows a diff which includes the current patch as well as any changes
12036 which have been made in the working directory since the last refresh
12037 (thus showing what the current patch would become after a qrefresh).
12038 Use hg diff if you only want to see the changes made since the last
12040 qrefresh, or hg export qtip if you want to see changes made by the cur‐
12041 rent patch without including changes made since the qrefresh.
12042 Returns 0 on success.
12044 Options:
12046 -a, --text
12048 treat all files as text
12049 -g, --git
12051 use git extended diff format (DEFAULT: diff.git)
12052 --binary
12054 generate binary diffs in git mode (default)
12055 --nodates
12057 omit dates from diff headers
12058 --noprefix
12060 omit a/ and b/ prefixes from filenames
12061 -p, --show-function
12063 show which function each change is in (DEFAULT: diff.showfunc)
12064 --reverse
12066 produce a diff that undoes the changes
12067 -w, --ignore-all-space
12069 ignore white space when comparing lines
12070 -b, --ignore-space-change
12072 ignore changes in the amount of white space
12073 -B, --ignore-blank-lines
12075 ignore changes whose lines are all blank
12076 -Z, --ignore-space-at-eol
12078 ignore changes in whitespace at EOL
12079 -U,--unified <NUM>
12081 number of lines of context to show
12082 --stat output diffstat-style summary of changes
12084 --root <DIR>
12086 produce diffs relative to subdirectory
12087 -I,--include <PATTERN[+]>
12089 include names matching the given patterns
12090 -X,--exclude <PATTERN[+]>
12092 exclude names matching the given patterns
12093 [+] marked option can be specified multiple times
12095 Change import/export
12097 qimport
12098 import a patch or existing changeset:
12099 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
12101 The patch is inserted into the series after the last applied patch. If
12103 no patches have been applied, qimport prepends the patch to the series.
12104 The patch will have the same name as its source file unless you give it
12106 a new one with -n/--name.
12107 You can register an existing patch inside the patch directory with the
12109 -e/--existing flag.
12110 With -f/--force, an existing patch of the same name will be overwrit‐
12112 ten.
12113 An existing changeset may be placed under mq control with -r/--rev
12115 (e.g. qimport --rev . -n patch will place the current revision under mq
12116 control). With -g/--git, patches imported with --rev will use the git
12117 diff format. See the diffs help topic for information on why this is
12118 important for preserving rename/copy information and permission
12119 changes. Use hg qfinish to remove changesets from mq control.
12120 To import a patch from standard input, pass - as the patch file. When
12122 importing from standard input, a patch name must be specified using the
12123 --name flag.
12124 To import an existing patch while renaming it:
12126 hg qimport -e existing-patch -n new-name
12128 Returns 0 if import succeeded.
12130 Options:
12132 -e, --existing
12134 import file in patch directory
12135 -n,--name <NAME>
12137 name of patch file
12138 -f, --force
12140 overwrite existing files
12141 -r,--rev <REV[+]>
12143 place existing revisions under mq control
12144 -g, --git
12146 use git extended diff format
12147 -P, --push
12149 qpush after importing
12150 [+] marked option can be specified multiple times
12152 narrow
12154 create clones which fetch history data for subset of files (EXPERIMEN‐
12155 TAL)
12156 Commands
12158 Repository maintenance
12159 tracked
12160 show or change the current narrowspec:
12161 hg tracked [OPTIONS]... [REMOTE]
12163 With no argument, shows the current narrowspec entries, one per line.
12165 Each line will be prefixed with 'I' or 'X' for included or excluded
12166 patterns, respectively.
12167 The narrowspec is comprised of expressions to match remote files and/or
12169 directories that should be pulled into your client. The narrowspec has
12170 include and exclude expressions, with excludes always trumping
12171 includes: that is, if a file matches an exclude expression, it will be
12172 excluded even if it also matches an include expression. Excluding
12173 files that were never included has no effect.
12174 Each included or excluded entry is in the format described by 'hg help
12176 patterns'.
12177 The options allow you to add or remove included and excluded expres‐
12179 sions.
12180 If --clear is specified, then all previous includes and excludes are
12182 DROPPED and replaced by the new ones specified to --addinclude and
12183 --addexclude. If --clear is specified without any further options, the
12184 narrowspec will be empty and will not match any files.
12185 If --auto-remove-includes is specified, then those includes that don't
12187 match any files modified by currently visible local commits (those not
12188 shared by the remote) will be added to the set of explicitly specified
12189 includes to remove.
12190 --import-rules accepts a path to a file containing rules, allowing you
12192 to add --addinclude, --addexclude rules in bulk. Like the other include
12193 and exclude switches, the changes are applied immediately.
12194 Options:
12196 --addinclude <VALUE[+]>
12198 new paths to include
12199 --removeinclude <VALUE[+]>
12201 old paths to no longer include
12202 --auto-remove-includes
12204 automatically choose unused includes to remove
12205 --addexclude <VALUE[+]>
12207 new paths to exclude
12208 --import-rules <VALUE>
12210 import narrowspecs from a file
12211 --removeexclude <VALUE[+]>
12213 old paths to no longer exclude
12214 --clear
12216 whether to replace the existing narrowspec
12217 --force-delete-local-changes
12219 forces deletion of local changes when narrowing
12220 --update-working-copy
12222 update working copy when the store has changed
12223 -e,--ssh <CMD>
12225 specify ssh command to use
12226 --remotecmd <CMD>
12228 specify hg command to run on the remote side
12229 --insecure
12231 do not verify server certificate (ignoring web.cacerts config)
12232 [+] marked option can be specified multiple times
12234 notify
12236 hooks for sending email push notifications
12237 This extension implements hooks to send email notifications when
12239 changesets are sent from or received by the local repository.
12240 First, enable the extension as explained in hg help extensions, and
12242 register the hook you want to run. incoming and changegroup hooks are
12243 run when changesets are received, while outgoing hooks are for change‐
12244 sets sent to another repository:
12245 [hooks]
12247 # one email for each incoming changeset
12248 incoming.notify = python:hgext.notify.hook
12249 # one email for all incoming changesets
12250 changegroup.notify = python:hgext.notify.hook
12251 # one email for all outgoing changesets
12253 outgoing.notify = python:hgext.notify.hook
12254 This registers the hooks. To enable notification, subscribers must be
12256 assigned to repositories. The [usersubs] section maps multiple reposi‐
12257 tories to a given recipient. The [reposubs] section maps multiple
12258 recipients to a single repository:
12259 [usersubs]
12261 # key is subscriber email, value is a comma-separated list of repo patterns
12262 user@host = pattern
12263 [reposubs]
12265 # key is repo pattern, value is a comma-separated list of subscriber emails
12266 pattern = user@host
12267 A pattern is a glob matching the absolute path to a repository, option‐
12269 ally combined with a revset expression. A revset expression, if
12270 present, is separated from the glob by a hash. Example:
12271 [reposubs]
12273 */widgets#branch(release) = qa-team@example.com
12274 This sends to qa-team@example.com whenever a changeset on the release
12276 branch triggers a notification in any repository ending in widgets.
12277 In order to place them under direct user management, [usersubs] and
12279 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
12280 rated by reference:
12281 [notify]
12283 config = /path/to/subscriptionsfile
12284 Notifications will not be sent until the notify.test value is set to
12286 False; see below.
12287 Notifications content can be tweaked with the following configuration
12289 entries:
12290 notify.test
12292 If True, print messages to stdout instead of sending them.
12293 Default: True.
12294 notify.sources
12296 Space-separated list of change sources. Notifications are acti‐
12297 vated only when a changeset's source is in this list. Sources
12298 may be:
12299 serve
12301 changesets received via http or ssh
12303 pull
12305 changesets received via hg pull
12307 unbundle
12309 changesets received via hg unbundle
12311 push
12313 changesets sent or received via hg push
12315 bundle
12317 changesets sent via hg unbundle
12319 Default: serve.
12321 notify.strip
12323 Number of leading slashes to strip from url paths. By default,
12324 notifications reference repositories with their absolute path.
12325 notify.strip lets you turn them into relative paths. For exam‐
12326 ple, notify.strip=3 will change /long/path/repository into
12327 repository. Default: 0.
12328 notify.domain
12330 Default email domain for sender or recipients with no explicit
12331 domain. It is also used for the domain part of the Message-Id
12332 when using notify.messageidseed.
12333 notify.messageidseed
12335 Create deterministic Message-Id headers for the mails based on
12336 the seed and the revision identifier of the first commit in the
12337 changeset.
12338 notify.style
12340 Style file to use when formatting emails.
12341 notify.template
12343 Template to use when formatting emails.
12344 notify.incoming
12346 Template to use when run as an incoming hook, overriding
12347 notify.template.
12348 notify.outgoing
12350 Template to use when run as an outgoing hook, overriding
12351 notify.template.
12352 notify.changegroup
12354 Template to use when running as a changegroup hook, overriding
12355 notify.template.
12356 notify.maxdiff
12358 Maximum number of diff lines to include in notification email.
12359 Set to 0 to disable the diff, or -1 to include all of it.
12360 Default: 300.
12361 notify.maxdiffstat
12363 Maximum number of diffstat lines to include in notification
12364 email. Set to -1 to include all of it. Default: -1.
12365 notify.maxsubject
12367 Maximum number of characters in email's subject line. Default:
12368 67.
12369 notify.diffstat
12371 Set to True to include a diffstat before diff content. Default:
12372 True.
12373 notify.showfunc
12375 If set, override diff.showfunc for the diff content. Default:
12376 None.
12377 notify.merge
12379 If True, send notifications for merge changesets. Default: True.
12380 notify.mbox
12382 If set, append mails to this mbox file instead of sending.
12383 Default: None.
12384 notify.fromauthor
12386 If set, use the committer of the first changeset in a change‐
12387 group for the "From" field of the notification mail. If not set,
12388 take the user from the pushing repo. Default: False.
12389 notify.reply-to-predecessor (EXPERIMENTAL)
12391 If set and the changeset has a predecessor in the repository,
12392 try to thread the notification mail with the predecessor. This
12393 adds the "In-Reply-To" header to the notification mail with a
12394 reference to the predecessor with the smallest revision number.
12395 Mail threads can still be torn, especially when changesets are
12396 folded.
12397 This option must be used in combination with notify.messageid‐
12399 seed.
12400 If set, the following entries will also be used to customize the noti‐
12402 fications:
12403 email.from
12405 Email From address to use if none can be found in the generated
12406 email content.
12407 web.baseurl
12409 Root repository URL to combine with repository paths when making
12410 references. See also notify.strip.
12411 pager
12413 browse command output with an external pager (DEPRECATED)
12414 Forcibly enable paging for individual commands that don't typically
12416 request pagination with the attend-<command> option. This setting takes
12417 precedence over ignore options and defaults:
12418 [pager]
12420 attend-cat = false
12421 patchbomb
12423 command to send changesets as (a series of) patch emails
12424 The series is started off with a "[PATCH 0 of N]" introduction, which
12426 describes the series as a whole.
12427 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12429 first line of the changeset description as the subject text. The mes‐
12430 sage contains two or three body parts:
12431 · The changeset description.
12433 · [Optional] The result of running diffstat on the patch.
12435 · The patch itself, as generated by hg export.
12437 Each message refers to the first in the series using the In-Reply-To
12439 and References headers, so they will show up as a sequence in threaded
12440 mail and news readers, and in mail archives.
12441 To configure other defaults, add a section like this to your configura‐
12443 tion file:
12444 [email]
12446 from = My Name <my@email>
12447 to = recipient1, recipient2, ...
12448 cc = cc1, cc2, ...
12449 bcc = bcc1, bcc2, ...
12450 reply-to = address1, address2, ...
12451 Use [patchbomb] as configuration section name if you need to override
12453 global [email] address settings.
12454 Then you can use the hg email command to mail a series of changesets as
12456 a patchbomb.
12457 You can also either configure the method option in the email section to
12459 be a sendmail compatible mailer or fill out the [smtp] section so that
12460 the patchbomb extension can automatically send patchbombs directly from
12461 the commandline. See the [email] and [smtp] sections in hgrc(5) for
12462 details.
12463 By default, hg email will prompt for a To or CC header if you do not
12465 supply one via configuration or the command line. You can override
12466 this to never prompt by configuring an empty value:
12467 [email]
12469 cc =
12470 You can control the default inclusion of an introduction message with
12472 the patchbomb.intro configuration option. The configuration is always
12473 overwritten by command line flags like --intro and --desc:
12474 [patchbomb]
12476 intro=auto # include introduction message if more than 1 patch (default)
12477 intro=never # never include an introduction message
12478 intro=always # always include an introduction message
12479 You can specify a template for flags to be added in subject prefixes.
12481 Flags specified by --flag option are exported as {flags} keyword:
12482 [patchbomb]
12484 flagtemplate = "{separate(' ',
12485 ifeq(branch, 'default', '', branch|upper),
12486 flags)}"
12487 You can set patchbomb to always ask for confirmation by setting patch‐
12489 bomb.confirm to true.
12490 Commands
12492 Change import/export
12493 email
12494 send changesets by email:
12495 hg email [OPTION]... [DEST]...
12497 By default, diffs are sent in the format generated by hg export, one
12499 per message. The series starts with a "[PATCH 0 of N]" introduction,
12500 which describes the series as a whole.
12501 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12503 first line of the changeset description as the subject text. The mes‐
12504 sage contains two or three parts. First, the changeset description.
12505 With the -d/--diffstat option, if the diffstat program is installed,
12507 the result of running diffstat on the patch is inserted.
12508 Finally, the patch itself, as generated by hg export.
12510 With the -d/--diffstat or --confirm options, you will be presented with
12512 a final summary of all messages and asked for confirmation before the
12513 messages are sent.
12514 By default the patch is included as text in the email body for easy
12516 reviewing. Using the -a/--attach option will instead create an attach‐
12517 ment for the patch. With -i/--inline an inline attachment will be cre‐
12518 ated. You can include a patch both as text in the email body and as a
12519 regular or an inline attachment by combining the -a/--attach or
12520 -i/--inline with the --body option.
12521 With -B/--bookmark changesets reachable by the given bookmark are
12523 selected.
12524 With -o/--outgoing, emails will be generated for patches not found in
12526 the destination repository (or only those which are ancestors of the
12527 specified revisions if any are provided)
12528 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
12530 gle email containing a binary Mercurial bundle as an attachment will be
12531 sent. Use the patchbomb.bundletype config option to control the bundle
12532 type as with hg bundle --type.
12533 With -m/--mbox, instead of previewing each patchbomb message in a pager
12535 or sending the messages directly, it will create a UNIX mailbox file
12536 with the patch emails. This mailbox file can be previewed with any mail
12537 user agent which supports UNIX mbox files.
12538 With -n/--test, all steps will run, but mail will not be sent. You
12540 will be prompted for an email recipient address, a subject and an
12541 introductory message describing the patches of your patchbomb. Then
12542 when all is done, patchbomb messages are displayed.
12543 In case email sending fails, you will find a backup of your series
12545 introductory message in .hg/last-email.txt.
12546 The default behavior of this command can be customized through configu‐
12548 ration. (See hg help patchbomb for details)
12549 Examples:
12551 hg email -r 3000 # send patch 3000 only
12553 hg email -r 3000 -r 3001 # send patches 3000 and 3001
12554 hg email -r 3000:3005 # send patches 3000 through 3005
12555 hg email 3000 # send patch 3000 (deprecated)
12556 hg email -o # send all patches not in default
12558 hg email -o DEST # send all patches not in DEST
12559 hg email -o -r 3000 # send all ancestors of 3000 not in default
12560 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
12561 hg email -B feature # send all ancestors of feature bookmark
12563 hg email -b # send bundle of all patches not in default
12565 hg email -b DEST # send bundle of all patches not in DEST
12566 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
12567 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
12568 hg email -o -m mbox && # generate an mbox file...
12570 mutt -R -f mbox # ... and view it with mutt
12571 hg email -o -m mbox && # generate an mbox file ...
12572 formail -s sendmail \ # ... and use formail to send from the mbox
12573 -bm -t < mbox # ... using sendmail
12574 Before using this command, you will need to enable email in your hgrc.
12576 See the [email] section in hgrc(5) for details.
12577 Options:
12579 -g, --git
12581 use git extended diff format
12582 --plain
12584 omit hg patch header
12585 -o, --outgoing
12587 send changes not found in the target repository
12588 -b, --bundle
12590 send changes not in target as a binary bundle
12591 -B,--bookmark <BOOKMARK>
12593 send changes only reachable by given bookmark
12594 --bundlename <NAME>
12596 name of the bundle attachment file (default: bundle)
12597 -r,--rev <REV[+]>
12599 a revision to send
12600 --force
12602 run even when remote repository is unrelated (with -b/--bundle)
12603 --base <REV[+]>
12605 a base changeset to specify instead of a destination (with
12606 -b/--bundle)
12607 --intro
12609 send an introduction email for a single patch
12610 --body send patches as inline message text (default)
12612 -a, --attach
12614 send patches as attachments
12615 -i, --inline
12617 send patches as inline attachments
12618 --bcc <EMAIL[+]>
12620 email addresses of blind carbon copy recipients
12621 -c,--cc <EMAIL[+]>
12623 email addresses of copy recipients
12624 --confirm
12626 ask for confirmation before sending
12627 -d, --diffstat
12629 add diffstat output to messages
12630 --date <DATE>
12632 use the given date as the sending date
12633 --desc <FILE>
12635 use the given file as the series description
12636 -f,--from <EMAIL>
12638 email address of sender
12639 -n, --test
12641 print messages that would be sent
12642 -m,--mbox <FILE>
12644 write messages to mbox file instead of sending them
12645 --reply-to <EMAIL[+]>
12647 email addresses replies should be sent to
12648 -s,--subject <TEXT>
12650 subject of first message (intro or single patch)
12651 --in-reply-to <MSGID>
12653 message identifier to reply to
12654 --flag <FLAG[+]>
12656 flags to add in subject prefixes
12657 -t,--to <EMAIL[+]>
12659 email addresses of recipients
12660 -e,--ssh <CMD>
12662 specify ssh command to use
12663 --remotecmd <CMD>
12665 specify hg command to run on the remote side
12666 --insecure
12668 do not verify server certificate (ignoring web.cacerts config)
12669 [+] marked option can be specified multiple times
12671 phabricator
12673 simple Phabricator integration (EXPERIMENTAL)
12674 This extension provides a phabsend command which sends a stack of
12676 changesets to Phabricator, and a phabread command which prints a stack
12677 of revisions in a format suitable for hg import, and a phabupdate com‐
12678 mand to update statuses in batch.
12679 A "phabstatus" view for hg show is also provided; it displays status
12681 information of Phabricator differentials associated with unfinished
12682 changesets.
12683 By default, Phabricator requires Test Plan which might prevent some
12685 changeset from being sent. The requirement could be disabled by chang‐
12686 ing differential.require-test-plan-field config server side.
12687 Config:
12689 [phabricator]
12691 # Phabricator URL
12692 url = https://phab.example.com/
12693 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
12695 # callsign is "FOO".
12696 callsign = FOO
12697 # curl command to use. If not set (default), use builtin HTTP library to
12699 # communicate. If set, use the specified curl command. This could be useful
12700 # if you need to specify advanced options that is not easily supported by
12701 # the internal library.
12702 curlcmd = curl --connect-timeout 2 --retry 3 --silent
12703 [auth]
12705 example.schemes = https
12706 example.prefix = phab.example.com
12707 # API token. Get it from https://$HOST/conduit/login/
12709 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
12710 Commands
12712 Change import/export
12713 phabimport
12714 import patches from Phabricator for the specified Differential Revi‐
12715 sions:
12716 hg phabimport DREVSPEC... [OPTIONS]
12718 The patches are read and applied starting at the parent of the working
12720 directory.
12721 See hg help phabread for how to specify DREVSPEC.
12723 Options:
12725 --stack
12727 import dependencies as well
12728 --test-vcr <VALUE>
12730 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12731 script, otherwise will mock all http requests using the speci‐
12732 fied vcr file. (ADVANCED)
12733 phabread
12735 print patches from Phabricator suitable for importing:
12736 hg phabread DREVSPEC... [OPTIONS]
12738 DREVSPEC could be a Differential Revision identity, like D123, or just
12740 the number 123. It could also have common operators like +, -, &, (, )
12741 for complex queries. Prefix : could be used to select a stack. If mul‐
12742 tiple DREVSPEC values are given, the result is the union of each indi‐
12743 vidually evaluated value. No attempt is currently made to reorder the
12744 values to run from parent to child.
12745 abandoned, accepted, closed, needsreview, needsrevision could be used
12747 to filter patches by status. For performance reason, they only repre‐
12748 sent a subset of non-status selections and cannot be used alone.
12749 For example, :D6+8-(2+D4) selects a stack up to D6, plus D8 and exclude
12751 D2 and D4. :D9 & needsreview selects "Needs Review" revisions in a
12752 stack up to D9.
12753 If --stack is given, follow dependencies information and read all
12755 patches. It is equivalent to the : operator.
12756 Options:
12758 --stack
12760 read dependencies
12761 --test-vcr <VALUE>
12763 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12764 script, otherwise will mock all http requests using the speci‐
12765 fied vcr file. (ADVANCED)
12766 phabsend
12768 upload changesets to Phabricator:
12769 hg phabsend REV [OPTIONS]
12771 If there are multiple revisions specified, they will be send as a stack
12773 with a linear dependencies relationship using the order specified by
12774 the revset.
12775 For the first time uploading changesets, local tags will be created to
12777 maintain the association. After the first time, phabsend will check
12778 obsstore and tags information so it can figure out whether to update an
12779 existing Differential Revision, or create a new one.
12780 If --amend is set, update commit messages so they have the Differential
12782 Revision URL, remove related tags. This is similar to what arcanist
12783 will do, and is more desired in author-push workflows. Otherwise, use
12784 local tags to record the Differential Revision association.
12785 The --confirm option lets you confirm changesets before sending them.
12787 You can also add following to your configuration file to make it
12788 default behaviour:
12789 [phabsend]
12791 confirm = true
12792 By default, a separate review will be created for each commit that is
12794 selected, and will have the same parent/child relationship in Phabrica‐
12795 tor. If --fold is set, multiple commits are rolled up into a single
12796 review as if diffed from the parent of the first revision to the last.
12797 The commit messages are concatenated in the summary field on Phabrica‐
12798 tor.
12799 phabsend will check obsstore and the above association to decide
12801 whether to update an existing Differential Revision, or create a new
12802 one.
12803 Options:
12805 -r,--rev <REV[+]>
12807 revisions to send
12808 --amend
12810 update commit messages (default: True)
12811 --reviewer <VALUE[+]>
12813 specify reviewers
12814 --blocker <VALUE[+]>
12816 specify blocking reviewers
12817 -m,--comment <VALUE>
12819 add a comment to Revisions with new/updated Diffs
12820 --confirm
12822 ask for confirmation before sending
12823 --fold combine the revisions into one review
12825 --test-vcr <VALUE>
12827 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12828 script, otherwise will mock all http requests using the speci‐
12829 fied vcr file. (ADVANCED)
12830 [+] marked option can be specified multiple times
12832 phabupdate
12834 update Differential Revision in batch:
12835 hg phabupdate DREVSPEC... [OPTIONS]
12837 DREVSPEC selects revisions. See hg help phabread for its usage.
12839 Options:
12841 --accept
12843 accept revisions
12844 --reject
12846 reject revisions
12847 --abandon
12849 abandon revisions
12850 --reclaim
12852 reclaim revisions
12853 -m,--comment <VALUE>
12855 comment on the last revision
12856 --test-vcr <VALUE>
12858 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12859 script, otherwise will mock all http requests using the speci‐
12860 fied vcr file. (ADVANCED)
12861 Uncategorized commands
12863 purge
12864 command to delete untracked files from the working directory
12865 Commands
12867 Repository maintenance
12868 purge
12869 removes files not tracked by Mercurial:
12870 hg purge [OPTION]... [DIR]...
12872 Delete files not known to Mercurial. This is useful to test local and
12874 uncommitted changes in an otherwise-clean source tree.
12875 This means that purge will delete the following by default:
12877 · Unknown files: files marked with "?" by hg status
12879 · Empty directories: in fact Mercurial ignores directories unless they
12881 contain files under source control management
12882 But it will leave untouched:
12884 · Modified and unmodified tracked files
12886 · Ignored files (unless -i or --all is specified)
12888 · New files added to the repository (with hg add)
12890 The --files and --dirs options can be used to direct purge to delete
12892 only files, only directories, or both. If neither option is given, both
12893 will be deleted.
12894 If directories are given on the command line, only files in these
12896 directories are considered.
12897 Be careful with purge, as you could irreversibly delete some files you
12899 forgot to add to the repository. If you only want to print the list of
12900 files that this program would delete, use the --print option.
12901 Options:
12903 -a, --abort-on-err
12905 abort if an error occurs
12906 --all purge ignored files too
12908 -i, --ignored
12910 purge only ignored files
12911 --dirs purge empty directories
12913 --files
12915 purge files
12916 -p, --print
12918 print filenames instead of deleting them
12919 -0, --print0
12921 end filenames with NUL, for use with xargs (implies -p/--print)
12922 -I,--include <PATTERN[+]>
12924 include names matching the given patterns
12925 -X,--exclude <PATTERN[+]>
12927 exclude names matching the given patterns
12928 [+] marked option can be specified multiple times
12930 aliases: clean
12932 rebase
12934 command to move sets of revisions to a different ancestor
12935 This extension lets you rebase changesets in an existing Mercurial
12937 repository.
12938 For more information: https://mercurial-scm.org/wiki/RebaseExtension
12940 Commands
12942 Change manipulation
12943 rebase
12944 move changeset (and descendants) to a different branch:
12945 hg rebase [[-s REV]... | [-b REV]... | [-r REV]...] [-d REV] [OPTION]...
12947 Rebase uses repeated merging to graft changesets from one part of his‐
12949 tory (the source) onto another (the destination). This can be useful
12950 for linearizing local changes relative to a master development tree.
12951 Published commits cannot be rebased (see hg help phases). To copy com‐
12953 mits, see hg help graft.
12954 If you don't specify a destination changeset (-d/--dest), rebase will
12956 use the same logic as hg merge to pick a destination. if the current
12957 branch contains exactly one other head, the other head is merged with
12958 by default. Otherwise, an explicit revision with which to merge with
12959 must be provided. (destination changeset is not modified by rebasing,
12960 but new changesets are added as its descendants.)
12961 Here are the ways to select changesets:
12963 1. Explicitly select them using --rev.
12965 2. Use --source to select a root changeset and include all of its
12967 descendants.
12968 3. Use --base to select a changeset; rebase will find ancestors and
12970 their descendants which are not also ancestors of the destina‐
12971 tion.
12972 4. If you do not specify any of --rev, --source, or --base, rebase
12974 will use --base . as above.
12975 If --source or --rev is used, special names SRC and ALLSRC can be used
12977 in --dest. Destination would be calculated per source revision with SRC
12978 substituted by that single source revision and ALLSRC substituted by
12979 all source revisions.
12980 Rebase will destroy original changesets unless you use --keep. It will
12982 also move your bookmarks (even if you do).
12983 Some changesets may be dropped if they do not contribute changes (e.g.
12985 merges from the destination branch).
12986 Unlike merge, rebase will do nothing if you are at the branch tip of a
12988 named branch with two heads. You will need to explicitly specify source
12989 and/or destination.
12990 If you need to use a tool to automate merge/conflict decisions, you can
12992 specify one with --tool, see hg help merge-tools. As a caveat: the
12993 tool will not be used to mediate when a file was deleted, there is no
12994 hook presently available for this.
12995 If a rebase is interrupted to manually resolve a conflict, it can be
12997 continued with --continue/-c, aborted with --abort/-a, or stopped with
12998 --stop.
12999 Examples:
13001 · move "local changes" (current commit back to branching point) to the
13003 current branch tip after a pull:
13004 hg rebase
13006 · move a single changeset to the stable branch:
13008 hg rebase -r 5f493448 -d stable
13010 · splice a commit and all its descendants onto another part of history:
13012 hg rebase --source c0c3 --dest 4cf9
13014 · rebase everything on a branch marked by a bookmark onto the default
13016 branch:
13017 hg rebase --base myfeature --dest default
13019 · collapse a sequence of changes into a single commit:
13021 hg rebase --collapse -r 1520:1525 -d .
13023 · move a named branch while preserving its name:
13025 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
13027 · stabilize orphaned changesets so history looks linear:
13029 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
13031 Configuration Options:
13033 You can make rebase require a destination if you set the following con‐
13035 fig option:
13036 [commands]
13038 rebase.requiredest = True
13039 By default, rebase will close the transaction after each commit. For
13041 performance purposes, you can configure rebase to use a single transac‐
13042 tion across the entire rebase. WARNING: This setting introduces a sig‐
13043 nificant risk of losing the work you've done in a rebase if the rebase
13044 aborts unexpectedly:
13045 [rebase]
13047 singletransaction = True
13048 By default, rebase writes to the working copy, but you can configure it
13050 to run in-memory for better performance. When the rebase is not moving
13051 the parent(s) of the working copy (AKA the "currently checked out
13052 changesets"), this may also allow it to run even if the working copy is
13053 dirty:
13054 [rebase]
13056 experimental.inmemory = True
13057 Return Values:
13059 Returns 0 on success, 1 if nothing to rebase or there are unresolved
13061 conflicts.
13062 Options:
13064 -s,--source <REV[+]>
13066 rebase the specified changesets and their descendants
13067 -b,--base <REV[+]>
13069 rebase everything from branching point of specified changeset
13070 -r,--rev <REV[+]>
13072 rebase these revisions
13073 -d,--dest <REV>
13075 rebase onto the specified changeset
13076 --collapse
13078 collapse the rebased changesets
13079 -m,--message <TEXT>
13081 use text as collapse commit message
13082 -e, --edit
13084 invoke editor on commit messages
13085 -l,--logfile <FILE>
13087 read collapse commit message from file
13088 -k, --keep
13090 keep original changesets
13091 --keepbranches
13093 keep original branch names
13094 -D, --detach
13096 (DEPRECATED)
13097 -i, --interactive
13099 (DEPRECATED)
13100 -t,--tool <VALUE>
13102 specify merge tool
13103 --stop stop interrupted rebase
13105 -c, --continue
13107 continue an interrupted rebase
13108 -a, --abort
13110 abort an interrupted rebase
13111 --auto-orphans <VALUE>
13113 automatically rebase orphan revisions in the specified revset
13114 (EXPERIMENTAL)
13115 -n, --dry-run
13117 do not perform actions, just print output
13118 -T,--template <TEMPLATE>
13120 display with template
13121 --confirm
13123 ask before applying actions
13124 [+] marked option can be specified multiple times
13126 record
13128 commands to interactively select changes for commit/qrefresh (DEPRE‐
13129 CATED)
13130 The feature provided by this extension has been moved into core Mercu‐
13132 rial as hg commit --interactive.
13133 Commands
13135 Change creation
13136 qrecord
13137 interactively record a new patch:
13138 hg qrecord [OPTION]... PATCH [FILE]...
13140 See hg help qnew & hg help record for more information and usage.
13142 record
13144 interactively select changes to commit:
13145 hg record [OPTION]... [FILE]...
13147 If a list of files is omitted, all changes reported by hg status will
13149 be candidates for recording.
13150 See hg help dates for a list of formats valid for -d/--date.
13152 If using the text interface (see hg help config), you will be prompted
13154 for whether to record changes to each modified file, and for files with
13155 multiple changes, for each change to use. For each query, the following
13156 responses are possible:
13157 y - record this change
13159 n - skip this change
13160 e - edit this change manually
13161 s - skip remaining changes to this file
13163 f - record remaining changes to this file
13164 d - done, skip remaining changes and files
13166 a - record all changes to all remaining files
13167 q - quit, recording no changes
13168 ? - display help
13170 This command is not available when committing a merge.
13172 Options:
13174 -A, --addremove
13176 mark new/missing files as added/removed before committing
13177 --close-branch
13179 mark a branch head as closed
13180 --amend
13182 amend the parent of the working directory
13183 -s, --secret
13185 use the secret phase for committing
13186 -e, --edit
13188 invoke editor on commit messages
13189 --force-close-branch
13191 forcibly close branch from a non-head changeset (ADVANCED)
13192 -I,--include <PATTERN[+]>
13194 include names matching the given patterns
13195 -X,--exclude <PATTERN[+]>
13197 exclude names matching the given patterns
13198 -m,--message <TEXT>
13200 use text as commit message
13201 -l,--logfile <FILE>
13203 read commit message from file
13204 -d,--date <DATE>
13206 record the specified date as commit date
13207 -u,--user <USER>
13209 record the specified user as committer
13210 -S, --subrepos
13212 recurse into subrepositories
13213 -w, --ignore-all-space
13215 ignore white space when comparing lines
13216 -b, --ignore-space-change
13218 ignore changes in the amount of white space
13219 -B, --ignore-blank-lines
13221 ignore changes whose lines are all blank
13222 -Z, --ignore-space-at-eol
13224 ignore changes in whitespace at EOL
13225 [+] marked option can be specified multiple times
13227 releasenotes
13229 generate release notes from commit messages (EXPERIMENTAL)
13230 It is common to maintain files detailing changes in a project between
13232 releases. Maintaining these files can be difficult and time consuming.
13233 The hg releasenotes command provided by this extension makes the
13234 process simpler by automating it.
13235 Commands
13237 Change navigation
13238 releasenotes
13239 parse release notes from commit messages into an output file:
13240 hg releasenotes [-r REV] [-c] FILE
13242 Given an output file and set of revisions, this command will parse com‐
13244 mit messages for release notes then add them to the output file.
13245 Release notes are defined in commit messages as ReStructuredText direc‐
13247 tives. These have the form:
13248 .. directive:: title
13250 content
13252 Each directive maps to an output section in a generated release notes
13254 file, which itself is ReStructuredText. For example, the .. feature::
13255 directive would map to a New Features section.
13256 Release note directives can be either short-form or long-form. In
13258 short- form, title is omitted and the release note is rendered as a
13259 bullet list. In long form, a sub-section with the title title is added
13260 to the section.
13261 The FILE argument controls the output file to write gathered release
13263 notes to. The format of the file is:
13264 Section 1
13266 =========
13267 ...
13269 Section 2
13271 =========
13272 ...
13274 Only sections with defined release notes are emitted.
13276 If a section only has short-form notes, it will consist of bullet list:
13278 Section
13280 =======
13281 * Release note 1
13283 * Release note 2
13284 If a section has long-form notes, sub-sections will be emitted:
13286 Section
13288 =======
13289 Note 1 Title
13291 ------------
13292 Description of the first long-form note.
13294 Note 2 Title
13296 ------------
13297 Description of the second long-form note.
13299 If the FILE argument points to an existing file, that file will be
13301 parsed for release notes having the format that would be generated by
13302 this command. The notes from the processed commit messages will be
13303 merged into this parsed set.
13304 During release notes merging:
13306 · Duplicate items are automatically ignored
13308 · Items that are different are automatically ignored if the similarity
13310 is greater than a threshold.
13311 This means that the release notes file can be updated independently
13313 from this command and changes should not be lost when running this com‐
13314 mand on that file. A particular use case for this is to tweak the word‐
13315 ing of a release note after it has been added to the release notes
13316 file.
13317 The -c/--check option checks the commit message for invalid admoni‐
13319 tions.
13320 The -l/--list option, presents the user with a list of existing avail‐
13322 able admonitions along with their title. This also includes the custom
13323 admonitions (if any).
13324 Options:
13326 -r,--rev <REV>
13328 revisions to process for release notes
13329 -c, --check
13331 checks for validity of admonitions (if any)
13332 -l, --list
13334 list the available admonitions with their title
13335 Uncategorized commands
13337 relink
13338 recreates hardlinks between repository clones
13339 Commands
13341 Repository maintenance
13342 relink
13343 recreate hardlinks between two repositories:
13344 hg relink [ORIGIN]
13346 When repositories are cloned locally, their data files will be
13348 hardlinked so that they only use the space of a single repository.
13349 Unfortunately, subsequent pulls into either repository will break
13351 hardlinks for any files touched by the new changesets, even if both
13352 repositories end up pulling the same changes.
13353 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
13355 falling back to a complete copy of the source repository.
13356 This command lets you recreate those hardlinks and reclaim that wasted
13358 space.
13359 This repository will be relinked to share space with ORIGIN, which must
13361 be on the same local disk. If ORIGIN is omitted, looks for
13362 "default-relink", then "default", in [paths].
13363 Do not attempt any read operations on this repository while the command
13365 is running. (Both repositories will be locked against writes.)
13366 remotefilelog
13368 remotefilelog causes Mercurial to lazilly fetch file contents (EXPERI‐
13369 MENTAL)
13370 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13372 BILITY GUARANTEES. This means that repositories created with this
13373 extension may only be usable with the exact version of this exten‐
13374 sion/Mercurial that was used. The extension attempts to enforce this in
13375 order to prevent repository corruption.
13376 remotefilelog works by fetching file contents lazily and storing them
13378 in a cache on the client rather than in revlogs. This allows enormous
13379 histories to be transferred only partially, making them easier to oper‐
13380 ate on.
13381 Configs:
13383 packs.maxchainlen specifies the maximum delta chain length in pack
13385 files
13386 packs.maxpacksize specifies the maximum pack file size
13388 packs.maxpackfilecount specifies the maximum number of packs in the
13390 shared cache (trees only for now)
13392 remotefilelog.backgroundprefetch runs prefetch in background when
13394 True
13395 remotefilelog.bgprefetchrevs specifies revisions to fetch on commit
13397 and
13398 update, and on other commands that use them. Different from
13400 pullprefetch.
13401 remotefilelog.gcrepack does garbage collection during repack when
13403 True
13404 remotefilelog.nodettl specifies maximum TTL of a node in seconds
13406 before
13407 it is garbage collected
13409 remotefilelog.repackonhggc runs repack on hg gc when True
13411 remotefilelog.prefetchdays specifies the maximum age of a commit in
13413 days after which it is no longer prefetched.
13415 remotefilelog.prefetchdelay specifies delay between background
13417 prefetches in seconds after operations that change the work‐
13419 ing copy parent
13420 remotefilelog.data.gencountlimit constraints the minimum number of
13422 data
13423 pack files required to be considered part of a generation. In
13425 particular, minimum number of packs files > gencountlimit.
13426 remotefilelog.data.generations list for specifying the lower bound
13428 of
13429 each generation of the data pack files. For example, list
13431 ['100MB','1MB'] or ['1MB', '100MB'] will lead to three gener‐
13432 ations: [0, 1MB), [ 1MB, 100MB) and [100MB, infinity).
13433 remotefilelog.data.maxrepackpacks the maximum number of pack files
13435 to
13436 include in an incremental data repack.
13438 remotefilelog.data.repackmaxpacksize the maximum size of a pack file
13440 for
13441 it to be considered for an incremental data repack.
13443 remotefilelog.data.repacksizelimit the maximum total size of pack
13445 files
13446 to include in an incremental data repack.
13448 remotefilelog.history.gencountlimit constraints the minimum number
13450 of
13451 history pack files required to be considered part of a gener‐
13453 ation. In particular, minimum number of packs files > gen‐
13454 countlimit.
13455 remotefilelog.history.generations list for specifying the lower
13457 bound of
13458 each generation of the history pack files. For example, list
13460 [ '100MB', '1MB'] or ['1MB', '100MB'] will lead to three gen‐
13461 erations: [ 0, 1MB), [1MB, 100MB) and [100MB, infinity).
13462 remotefilelog.history.maxrepackpacks the maximum number of pack
13464 files to
13465 include in an incremental history repack.
13467 remotefilelog.history.repackmaxpacksize the maximum size of a pack
13469 file
13470 for it to be considered for an incremental history repack.
13472 remotefilelog.history.repacksizelimit the maximum total size of pack
13474 files to include in an incremental history repack.
13476 remotefilelog.backgroundrepack automatically consolidate packs in
13478 the
13479 background
13481 remotefilelog.cachepath path to cache
13483 remotefilelog.cachegroup if set, make cache directory sgid to this
13485 group
13487 remotefilelog.cacheprocess binary to invoke for fetching file data
13489 remotefilelog.debug turn on remotefilelog-specific debug output
13491 remotefilelog.excludepattern pattern of files to exclude from pulls
13493 remotefilelog.includepattern pattern of files to include in pulls
13495 remotefilelog.fetchwarning: message to print when too many
13497 single-file fetches occur
13499 remotefilelog.getfilesstep number of files to request in a single
13501 RPC
13502 remotefilelog.getfilestype if set to 'threaded' use threads to fetch
13504 files, otherwise use optimistic fetching
13506 remotefilelog.pullprefetch revset for selecting files that should be
13508 eagerly downloaded rather than lazily
13510 remotefilelog.reponame name of the repo. If set, used to partition
13512 data from other repos in a shared store.
13514 remotefilelog.server if true, enable server-side functionality
13516 remotefilelog.servercachepath path for caching blobs on the server
13518 remotefilelog.serverexpiration number of days to keep cached server
13520 blobs
13522 remotefilelog.validatecache if set, check cache entries for corrup‐
13524 tion
13525 before returning blobs
13527 remotefilelog.validatecachelog if set, check cache entries for
13529 corruption before returning metadata
13531 Commands
13533 Repository maintenance
13534 prefetch
13535 prefetch file revisions from the server:
13536 hg prefetch [OPTIONS] [FILE...]
13538 Prefetchs file revisions for the specified revs and stores them in the
13540 local remotefilelog cache. If no rev is specified, the default rev is
13541 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
13542 File names or patterns can be used to limit which files are downloaded.
13543 Return 0 on success.
13545 Options:
13547 -r,--rev <REV[+]>
13549 prefetch the specified revisions
13550 --repack
13552 run repack after prefetch
13553 -b,--base <VALUE>
13555 rev that is assumed to already be local
13556 -I,--include <PATTERN[+]>
13558 include names matching the given patterns
13559 -X,--exclude <PATTERN[+]>
13561 exclude names matching the given patterns
13562 [+] marked option can be specified multiple times
13564 Uncategorized commands
13566 gc
13567 garbage collect the client and server filelog caches:
13568 hg gc [REPO...]
13570 garbage collect the client and server filelog caches
13572 repack
13574 hg repack [OPTIONS]
13575 Options:
13577 --background
13579 run in a background process
13580 --incremental
13582 do an incremental repack
13583 --packsonly
13585 only repack packs (skip loose objects)
13586 verifyremotefilelog
13588 hg verifyremotefilelogs <directory>
13589 Options:
13591 -d, --decompress
13593 decompress the filelogs first
13594 remotenames
13596 showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)
13597 By default both remotebookmarks and remotebranches are turned on. Con‐
13599 fig knob to control the individually are as follows.
13600 Config options to tweak the default behaviour:
13602 remotenames.bookmarks
13604 Boolean value to enable or disable showing of remotebookmarks
13605 (default: True)
13606 remotenames.branches
13608 Boolean value to enable or disable showing of remotebranches
13609 (default: True)
13610 remotenames.hoistedpeer
13612 Name of the peer whose remotebookmarks should be hoisted into
13613 the top-level namespace (default: 'default')
13614 schemes
13616 extend schemes with shortcuts to repository swarms
13617 This extension allows you to specify shortcuts for parent URLs with a
13619 lot of repositories to act like a scheme, for example:
13620 [schemes]
13622 py = http://code.python.org/hg/
13623 After that you can use it like:
13625 hg clone py://trunk/
13627 Additionally there is support for some more complex schemas, for exam‐
13629 ple used by Google Code:
13630 [schemes]
13632 gcode = http://{1}.googlecode.com/hg/
13633 The syntax is taken from Mercurial templates, and you have unlimited
13635 number of variables, starting with {1} and continuing with {2}, {3} and
13636 so on. This variables will receive parts of URL supplied, split by /.
13637 Anything not specified as {part} will be just appended to an URL.
13638 For convenience, the extension adds these schemes by default:
13640 [schemes]
13642 py = http://hg.python.org/
13643 bb = https://bitbucket.org/
13644 bb+ssh = ssh://hg@bitbucket.org/
13645 gcode = https://{1}.googlecode.com/hg/
13646 kiln = https://{1}.kilnhg.com/Repo/
13647 You can override a predefined scheme by defining a new scheme with the
13649 same name.
13650 Commands
13652 Uncategorized commands
13653 share
13654 share a common history between several working directories
13655 The share extension introduces a new command hg share to create a new
13657 working directory. This is similar to hg clone, but doesn't involve
13658 copying or linking the storage of the repository. This allows working
13659 on different branches or changes in parallel without the associated
13660 cost in terms of disk space.
13661 Note: destructive operations or extensions like hg rollback should be
13663 used with care as they can result in confusing problems.
13664 Automatic Pooled Storage for Clones
13666 When this extension is active, hg clone can be configured to automati‐
13667 cally share/pool storage across multiple clones. This mode effectively
13668 converts hg clone to hg clone + hg share. The benefit of using this
13669 mode is the automatic management of store paths and intelligent pooling
13670 of related repositories.
13671 The following share. config options influence this feature:
13673 share.pool
13675 Filesystem path where shared repository data will be stored.
13677 When defined, hg clone will automatically use shared repository
13678 storage instead of creating a store inside each clone.
13679 share.poolnaming
13681 How directory names in share.pool are constructed.
13683 "identity" means the name is derived from the first changeset in
13685 the repository. In this mode, different remotes share storage if
13686 their root/initial changeset is identical. In this mode, the
13687 local shared repository is an aggregate of all encountered
13688 remote repositories.
13689 "remote" means the name is derived from the source repository's
13691 path or URL. In this mode, storage is only shared if the path or
13692 URL requested in the hg clone command matches exactly to a
13693 repository that was cloned before.
13694 The default naming mode is "identity".
13696 Commands
13698 Repository creation
13699 share
13700 create a new shared repository:
13701 hg share [-U] [-B] SOURCE [DEST]
13703 Initialize a new repository and working directory that shares its his‐
13705 tory (and optionally bookmarks) with another repository.
13706 Note using rollback or extensions that destroy/modify history (mq,
13708 rebase, etc.) can cause considerable confusion with shared
13709 clones. In particular, if two shared clones are both updated to
13710 the same changeset, and one of them destroys that changeset with
13711 rollback, the other clone will suddenly stop working: all opera‐
13712 tions will fail with "abort: working directory has unknown par‐
13713 ent". The only known workaround is to use debugsetparents on the
13714 broken clone to reset it to a changeset that still exists.
13715 Options:
13717 -U, --noupdate
13719 do not create a working directory
13720 -B, --bookmarks
13722 also share bookmarks
13723 --relative
13725 point to source using a relative path
13726 Repository maintenance
13728 unshare
13729 convert a shared repository to a normal one:
13730 hg unshare
13732 Copy the store data to the repo and remove the sharedpath data.
13734 show
13736 unified command to show various repository information (EXPERIMENTAL)
13737 This extension provides the hg show command, which provides a central
13739 command for displaying commonly-accessed repository data and views of
13740 that data.
13741 The following config options can influence operation.
13743 commands
13745 show.aliasprefix
13746 List of strings that will register aliases for views. e.g. s
13748 will effectively set config options alias.s<view> = show <view>
13749 for all views. i.e. hg swork would execute hg show work.
13750 Aliases that would conflict with existing registrations will not
13752 be performed.
13753 Commands
13755 Change navigation
13756 show
13757 show various repository information:
13758 hg show VIEW
13760 A requested view of repository data is displayed.
13762 If no view is requested, the list of available views is shown and the
13764 command aborts.
13765 Note There are no backwards compatibility guarantees for the output
13767 of this command. Output may change in any future Mercurial
13768 release.
13769 Consumers wanting stable command output should specify a tem‐
13771 plate via -T/--template.
13772 List of available views:
13774 bookmarks bookmarks and their associated changeset
13776 stack current line of work
13778 work changesets that aren't finished
13780 Options:
13782 -T,--template <TEMPLATE>
13784 display with template
13785 sparse
13787 allow sparse checkouts of the working directory (EXPERIMENTAL)
13788 (This extension is not yet protected by backwards compatibility guaran‐
13790 tees. Any aspect may break in future releases until this notice is
13791 removed.)
13792 This extension allows the working directory to only consist of a subset
13794 of files for the revision. This allows specific files or directories to
13795 be explicitly included or excluded. Many repository operations have
13796 performance proportional to the number of files in the working direc‐
13797 tory. So only realizing a subset of files in the working directory can
13798 improve performance.
13799 Sparse Config Files
13801 The set of files that are part of a sparse checkout are defined by a
13802 sparse config file. The file defines 3 things: includes (files to
13803 include in the sparse checkout), excludes (files to exclude from the
13804 sparse checkout), and profiles (links to other config files).
13805 The file format is newline delimited. Empty lines and lines beginning
13807 with # are ignored.
13808 Lines beginning with %include `` denote another sparse config file to
13810 include. e.g. ``%include tests.sparse. The filename is relative to the
13811 repository root.
13812 The special lines [include] and [exclude] denote the section for
13814 includes and excludes that follow, respectively. It is illegal to have
13815 [include] after [exclude].
13816 Non-special lines resemble file patterns to be added to either includes
13818 or excludes. The syntax of these lines is documented by hg help pat‐
13819 terns. Patterns are interpreted as glob: by default and match against
13820 the root of the repository.
13821 Exclusion patterns take precedence over inclusion patterns. So even if
13823 a file is explicitly included, an [exclude] entry can remove it.
13824 For example, say you have a repository with 3 directories, frontend/,
13826 backend/, and tools/. frontend/ and backend/ correspond to different
13827 projects and it is uncommon for someone working on one to need the
13828 files for the other. But tools/ contains files shared between both
13829 projects. Your sparse config files may resemble:
13830 # frontend.sparse
13832 frontend/**
13833 tools/**
13834 # backend.sparse
13836 backend/**
13837 tools/**
13838 Say the backend grows in size. Or there's a directory with thousands of
13840 files you wish to exclude. You can modify the profile to exclude cer‐
13841 tain files:
13842 [include]
13844 backend/**
13845 tools/**
13846 [exclude]
13848 tools/tests/**
13849 Commands
13851 Uncategorized commands
13852 split
13853 command to split a changeset into smaller ones (EXPERIMENTAL)
13854 Commands
13856 Change manipulation
13857 split
13858 split a changeset into smaller ones:
13859 hg split [--no-rebase] [[-r] REV]
13861 Repeatedly prompt changes and commit message for new changesets until
13863 there is nothing left in the original changeset.
13864 If --rev was not given, split the working directory parent.
13866 By default, rebase connected non-obsoleted descendants onto the new
13868 changeset. Use --no-rebase to avoid the rebase.
13869 Options:
13871 -r,--rev <REV>
13873 revision to split
13874 --rebase
13876 rebase descendants after split (default: True)
13877 -d,--date <DATE>
13879 record the specified date as commit date
13880 -u,--user <USER>
13882 record the specified user as committer
13883 sqlitestore
13885 store repository data in SQLite (EXPERIMENTAL)
13886 The sqlitestore extension enables the storage of repository data in
13888 SQLite.
13889 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13891 BILITY GUARANTEES. This means that repositories created with this
13892 extension may only be usable with the exact version of this exten‐
13893 sion/Mercurial that was used. The extension attempts to enforce this in
13894 order to prevent repository corruption.
13895 In addition, several features are not yet supported or have known bugs:
13897 · Only some data is stored in SQLite. Changeset, manifest, and other
13899 repository data is not yet stored in SQLite.
13900 · Transactions are not robust. If the process is aborted at the right
13902 time during transaction close/rollback, the repository could be in an
13903 inconsistent state. This problem will diminish once all repository
13904 data is tracked by SQLite.
13905 · Bundle repositories do not work (the ability to use e.g. hg -R <bun‐
13907 dle-file> log to automatically overlay a bundle on top of the exist‐
13908 ing repository).
13909 · Various other features don't work.
13911 This extension should work for basic clone/pull, update, and commit
13913 workflows. Some history rewriting operations may fail due to lack of
13914 support for bundle repositories.
13915 To use, activate the extension and set the storage.new-repo-backend
13917 config option to sqlite to enable new repositories to use SQLite for
13918 storage.
13919 strip
13921 strip changesets and their descendants from history
13922 This extension allows you to strip changesets and all their descendants
13924 from the repository. See the command help for details.
13925 Commands
13927 Repository maintenance
13928 strip
13929 strip changesets and all their descendants from the repository:
13930 hg strip [-k] [-f] [-B bookmark] [-r] REV...
13932 The strip command removes the specified changesets and all their
13934 descendants. If the working directory has uncommitted changes, the
13935 operation is aborted unless the --force flag is supplied, in which case
13936 changes will be discarded.
13937 If a parent of the working directory is stripped, then the working
13939 directory will automatically be updated to the most recent available
13940 ancestor of the stripped parent after the operation completes.
13941 Any stripped changesets are stored in .hg/strip-backup as a bundle (see
13943 hg help bundle and hg help unbundle). They can be restored by running
13944 hg unbundle .hg/strip-backup/BUNDLE, where BUNDLE is the bundle file
13945 created by the strip. Note that the local revision numbers will in gen‐
13946 eral be different after the restore.
13947 Use the --no-backup option to discard the backup bundle once the opera‐
13949 tion completes.
13950 Strip is not a history-rewriting operation and can be used on change‐
13952 sets in the public phase. But if the stripped changesets have been
13953 pushed to a remote repository you will likely pull them again.
13954 Return 0 on success.
13956 Options:
13958 -r,--rev <REV[+]>
13960 strip specified revision (optional, can specify revisions with‐
13961 out this option)
13962 -f, --force
13964 force removal of changesets, discard uncommitted changes (no
13965 backup)
13966 --no-backup
13968 do not save backup bundle
13969 --nobackup
13971 do not save backup bundle (DEPRECATED)
13972 -n ignored (DEPRECATED)
13974 -k, --keep
13976 do not modify working directory during strip
13977 -B,--bookmark <BOOKMARK[+]>
13979 remove revs only reachable from given bookmark
13980 --soft simply drop changesets from visible history (EXPERIMENTAL)
13982 [+] marked option can be specified multiple times
13984 transplant
13986 command to transplant changesets from another branch
13987 This extension allows you to transplant changes to another parent revi‐
13989 sion, possibly in another repository. The transplant is done using
13990 'diff' patches.
13991 Transplanted patches are recorded in .hg/transplant/transplants, as a
13993 map from a changeset hash to its hash in the source repository.
13994 Commands
13996 Change manipulation
13997 transplant
13998 transplant changesets from another branch:
13999 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
14001 Selected changesets will be applied on top of the current working
14003 directory with the log of the original changeset. The changesets are
14004 copied and will thus appear twice in the history with different identi‐
14005 ties.
14006 Consider using the graft command if everything is inside the same
14008 repository - it will use merges and will usually give a better result.
14009 Use the rebase extension if the changesets are unpublished and you want
14010 to move them instead of copying them.
14011 If --log is specified, log messages will have a comment appended of the
14013 form:
14014 (transplanted from CHANGESETHASH)
14016 You can rewrite the changelog message with the --filter option. Its
14018 argument will be invoked with the current changelog message as $1 and
14019 the patch as $2.
14020 --source/-s specifies another repository to use for selecting change‐
14022 sets, just as if it temporarily had been pulled. If --branch/-b is
14023 specified, these revisions will be used as heads when deciding which
14024 changesets to transplant, just as if only these revisions had been
14025 pulled. If --all/-a is specified, all the revisions up to the heads
14026 specified with --branch will be transplanted.
14027 Example:
14029 · transplant all changes up to REV on top of your current revision:
14031 hg transplant --branch REV --all
14033 You can optionally mark selected transplanted changesets as merge
14035 changesets. You will not be prompted to transplant any ancestors of a
14036 merged transplant, and you can merge descendants of them normally
14037 instead of transplanting them.
14038 Merge changesets may be transplanted directly by specifying the proper
14040 parent changeset by calling hg transplant --parent.
14041 If no merges or revisions are provided, hg transplant will start an
14043 interactive changeset browser.
14044 If a changeset application fails, you can fix the merge by hand and
14046 then resume where you left off by calling hg transplant --continue/-c.
14047 Options:
14049 -s,--source <REPO>
14051 transplant changesets from REPO
14052 -b,--branch <REV[+]>
14054 use this source changeset as head
14055 -a, --all
14057 pull all changesets up to the --branch revisions
14058 -p,--prune <REV[+]>
14060 skip over REV
14061 -m,--merge <REV[+]>
14063 merge at REV
14064 --parent <REV>
14066 parent to choose when transplanting merge
14067 -e, --edit
14069 invoke editor on commit messages
14070 --log append transplant info to log message
14072 --stop stop interrupted transplant
14074 -c, --continue
14076 continue last transplant session after fixing conflicts
14077 --filter <CMD>
14079 filter changesets through command
14080 [+] marked option can be specified multiple times
14082 uncommit
14084 uncommit part or all of a local changeset (EXPERIMENTAL)
14085 This command undoes the effect of a local commit, returning the
14087 affected files to their uncommitted state. This means that files modi‐
14088 fied, added or removed in the changeset will be left unchanged, and so
14089 will remain modified, added and removed in the working directory.
14090 Commands
14092 Change manipulation
14093 unamend
14094 undo the most recent amend operation on a current changeset:
14095 hg unamend
14097 This command will roll back to the previous version of a changeset,
14099 leaving working directory in state in which it was before running hg
14100 amend (e.g. files modified as part of an amend will be marked as modi‐
14101 fied hg status)
14102 uncommit
14104 uncommit part or all of a local changeset:
14105 hg uncommit [OPTION]... [FILE]...
14107 This command undoes the effect of a local commit, returning the
14109 affected files to their uncommitted state. This means that files modi‐
14110 fied or deleted in the changeset will be left unchanged, and so will
14111 remain modified in the working directory.
14112 If no files are specified, the commit will be pruned, unless --keep is
14114 given.
14115 Options:
14117 --keep allow an empty commit after uncommitting
14119 --allow-dirty-working-copy
14121 allow uncommit with outstanding changes
14122 -n,--note <TEXT>
14124 store a note on uncommit
14125 -I,--include <PATTERN[+]>
14127 include names matching the given patterns
14128 -X,--exclude <PATTERN[+]>
14130 exclude names matching the given patterns
14131 -m,--message <TEXT>
14133 use text as commit message
14134 -l,--logfile <FILE>
14136 read commit message from file
14137 -d,--date <DATE>
14139 record the specified date as commit date
14140 -u,--user <USER>
14142 record the specified user as committer
14143 -D, --currentdate
14145 record the current date as commit date
14146 -U, --currentuser
14148 record the current user as committer
14149 [+] marked option can be specified multiple times
14151 win32mbcs
14153 allow the use of MBCS paths with problematic encodings
14154 Some MBCS encodings are not good for some path operations (i.e. split‐
14156 ting path, case conversion, etc.) with its encoded bytes. We call such
14157 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
14158 extension can be used to fix the issue with those encodings by wrapping
14159 some functions to convert to Unicode string before path operation.
14160 This extension is useful for:
14162 · Japanese Windows users using shift_jis encoding.
14164 · Chinese Windows users using big5 encoding.
14166 · All users who use a repository with one of problematic encodings on
14168 case-insensitive file system.
14169 This extension is not needed for:
14171 · Any user who use only ASCII chars in path.
14173 · Any user who do not use any of problematic encodings.
14175 Note that there are some limitations on using this extension:
14177 · You should use single encoding in one repository.
14179 · If the repository path ends with 0x5c, .hg/hgrc cannot be read.
14181 · win32mbcs is not compatible with fixutf8 extension.
14183 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
14185 can specify the encoding by config option:
14186 [win32mbcs]
14188 encoding = sjis
14189 It is useful for the users who want to commit with UTF-8 log message.
14191 win32text
14193 perform automatic newline conversion (DEPRECATED)
14194 Deprecation: The win32text extension requires each user to configure
14196 the extension again and again for each clone since the configuration
14197 is not copied when cloning.
14198 We have therefore made the eol as an alternative. The eol uses a
14200 version controlled file for its configuration and each clone will
14201 therefore use the right settings from the start.
14202 To perform automatic newline conversion, use:
14204 [extensions]
14206 win32text =
14207 [encode]
14208 ** = cleverencode:
14209 # or ** = macencode:
14210 [decode]
14212 ** = cleverdecode:
14213 # or ** = macdecode:
14214 If not doing conversion, to make sure you do not commit CRLF/CR by
14216 accident:
14217 [hooks]
14219 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
14220 # or pretxncommit.cr = python:hgext.win32text.forbidcr
14221 To do the same check on a server to prevent CRLF/CR from being pushed
14223 or pulled:
14224 [hooks]
14226 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
14227 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
14228 zeroconf
14230 discover and advertise repositories on the local network
14231 The zeroconf extension will advertise hg serve instances over DNS-SD so
14233 that they can be discovered using the hg paths command without knowing
14234 the server's IP address.
14235 To allow other people to discover your repository using run hg serve in
14237 your repository:
14238 $ cd test
14240 $ hg serve
14241 You can discover Zeroconf-enabled repositories by running hg paths:
14243 $ hg paths
14245 zc-test = http://example.com:8000/test
14246
14248 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
14249 This file contains defaults and configuration. Values in
14251 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
14252 tings made in the global /etc/mercurial/hgrc configuration. See
14253 hgrc(5) for details of the contents and format of these files.
14254 .hgignore
14256 This file contains regular expressions (one per line) that
14258 describe file names that should be ignored by hg. For details,
14259 see hgignore(5).
14260 .hgsub
14262 This file defines the locations of all subrepositories, and
14264 tells where the subrepository checkouts came from. For details,
14265 see hg help subrepos.
14266 .hgsubstate
14268 This file is where Mercurial stores all nested repository
14270 states. NB: This file should not be edited manually.
14271 .hgtags
14273 This file contains changeset hash values and text tag names (one
14275 of each separated by spaces) that correspond to tagged versions
14276 of the repository contents. The file content is encoded using
14277 UTF-8.
14278 .hg/last-message.txt
14280 This file is used by hg commit to store a backup of the commit
14282 message in case the commit fails.
14283 .hg/localtags
14285 This file can be used to define local tags which are not shared
14287 among repositories. The file format is the same as for .hgtags,
14288 but it is encoded using the local system encoding.
14289 Some commands (e.g. revert) produce backup files ending in .orig, if
14291 the .orig file already exists and is not tracked by Mercurial, it will
14292 be overwritten.
14293
14295 Probably lots, please post them to the mailing list (see Resources
14296 below) when you find them.
14297
14299 hgignore(5), hgrc(5)
14300
14302 Written by Matt Mackall <mpm@selenic.com>
14303
14305 Main Web Site: https://mercurial-scm.org/
14306 Source code repository: https://www.mercurial-scm.org/repo/hg
14308 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
14310
14312 Copyright (C) 2005-2020 Matt Mackall. Free use of this software is
14313 granted under the terms of the GNU General Public License version 2 or
14314 any later version.
14315
14317 Matt Mackall <mpm@selenic.com>
14318 Organization: Mercurial
14320 HG(1)