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 -r,--rev <REV[+]>
580 a remote changeset intended to be added
581 -B,--bookmark <BOOKMARK[+]>
583 bookmark to pull
584 -b,--branch <BRANCH[+]>
586 a specific branch you would like to pull
587 -e,--ssh <CMD>
589 specify ssh command to use
590 --remotecmd <CMD>
592 specify hg command to run on the remote side
593 --insecure
595 do not verify server certificate (ignoring web.cacerts config)
596 [+] marked option can be specified multiple times
598 push
600 push changes to the specified destination:
601 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]
603 Push changesets from the local repository to the specified destination.
605 This operation is symmetrical to pull: it is identical to a pull in the
607 destination repository from the current one.
608 By default, push will not allow creation of new heads at the destina‐
610 tion, since multiple heads would make it unclear which head to use. In
611 this situation, it is recommended to pull and merge before pushing.
612 Use --new-branch if you want to allow push to create a new named branch
614 that is not present at the destination. This allows you to only create
615 a new branch without forcing other changes.
616 Note Extra care should be taken with the -f/--force option, which
618 will push all new heads on all branches, an action which will
619 almost always cause confusion for collaborators.
620 If -r/--rev is used, the specified revision and all its ancestors will
622 be pushed to the remote repository.
623 If -B/--bookmark is used, the specified bookmarked revision, its ances‐
625 tors, and the bookmark will be pushed to the remote repository. Speci‐
626 fying . is equivalent to specifying the active bookmark's name.
627 Please see hg help urls for important details about ssh:// URLs. If
629 DESTINATION is omitted, a default path will be used.
630 The --pushvars option sends strings to the server that become environ‐
632 ment variables prepended with HG_USERVAR_. For example, --pushvars
633 ENABLE_FEATURE=true, provides the server side hooks with HG_USER‐
634 VAR_ENABLE_FEATURE=true as part of their environment.
635 pushvars can provide for user-overridable hooks as well as set debug
637 levels. One example is having a hook that blocks commits containing
638 conflict markers, but enables the user to override the hook if the file
639 is using conflict markers for testing purposes or the file format has
640 strings that look like conflict markers.
641 By default, servers will ignore --pushvars. To enable it add the fol‐
643 lowing to your configuration file:
644 [push]
646 pushvars.server = true
647 Returns 0 if push was successful, 1 if nothing to push.
649 Options:
651 -f, --force
653 force push
654 -r,--rev <REV[+]>
656 a changeset intended to be included in the destination
657 -B,--bookmark <BOOKMARK[+]>
659 bookmark to push
660 -b,--branch <BRANCH[+]>
662 a specific branch you would like to push
663 --new-branch
665 allow pushing a new branch
666 --pushvars <VALUE[+]>
668 variables that can be sent to server (ADVANCED)
669 --publish
671 push the changeset as public (EXPERIMENTAL)
672 -e,--ssh <CMD>
674 specify ssh command to use
675 --remotecmd <CMD>
677 specify hg command to run on the remote side
678 --insecure
680 do not verify server certificate (ignoring web.cacerts config)
681 [+] marked option can be specified multiple times
683 serve
685 start stand-alone webserver:
686 hg serve [OPTION]...
688 Start a local HTTP repository browser and pull server. You can use this
690 for ad-hoc sharing and browsing of repositories. It is recommended to
691 use a real web server to serve a repository for longer periods of time.
692 Please note that the server does not implement access control. This
694 means that, by default, anybody can read from the server and nobody can
695 write to it by default. Set the web.allow-push option to * to allow
696 everybody to push to the server. You should use a real web server if
697 you need to authenticate users.
698 By default, the server logs accesses to stdout and errors to stderr.
700 Use the -A/--accesslog and -E/--errorlog options to log to files.
701 To have the server choose a free port number to listen on, specify a
703 port number of 0; in this case, the server will print the port number
704 it uses.
705 Returns 0 on success.
707 Options:
709 -A,--accesslog <FILE>
711 name of access log file to write to
712 -d, --daemon
714 run server in background
715 --daemon-postexec <VALUE[+]>
717 used internally by daemon mode
718 -E,--errorlog <FILE>
720 name of error log file to write to
721 -p,--port <PORT>
723 port to listen on (default: 8000)
724 -a,--address <ADDR>
726 address to listen on (default: all interfaces)
727 --prefix <PREFIX>
729 prefix path to serve from (default: server root)
730 -n,--name <NAME>
732 name to show in web pages (default: working directory)
733 --web-conf <FILE>
735 name of the hgweb config file (see 'hg help hgweb')
736 --webdir-conf <FILE>
738 name of the hgweb config file (DEPRECATED)
739 --pid-file <FILE>
741 name of file to write process ID to
742 --stdio
744 for remote clients (ADVANCED)
745 --cmdserver <MODE>
747 for remote clients (ADVANCED)
748 -t,--templates <TEMPLATE>
750 web templates to use
751 --style <STYLE>
753 template style to use
754 -6, --ipv6
756 use IPv6 in addition to IPv4
757 --certificate <FILE>
759 SSL certificate file
760 --print-url
762 start and print only the URL
763 -S, --subrepos
765 recurse into subrepositories
766 [+] marked option can be specified multiple times
768 Change creation
770 commit
771 commit the specified files or all outstanding changes:
772 hg commit [OPTION]... [FILE]...
774 Commit changes to the given files into the repository. Unlike a cen‐
776 tralized SCM, this operation is a local operation. See hg push for a
777 way to actively distribute your changes.
778 If a list of files is omitted, all changes reported by hg status will
780 be committed.
781 If you are committing the result of a merge, do not provide any file‐
783 names or -I/-X filters.
784 If no commit message is specified, Mercurial starts your configured
786 editor where you can enter a message. In case your commit fails, you
787 will find a backup of your message in .hg/last-message.txt.
788 The --close-branch flag can be used to mark the current branch head
790 closed. When all heads of a branch are closed, the branch will be con‐
791 sidered closed and no longer listed.
792 The --amend flag can be used to amend the parent of the working direc‐
794 tory with a new commit that contains the changes in the parent in addi‐
795 tion to those currently reported by hg status, if there are any. The
796 old commit is stored in a backup bundle in .hg/strip-backup (see hg
797 help bundle and hg help unbundle on how to restore it).
798 Message, user and date are taken from the amended commit unless speci‐
800 fied. When a message isn't specified on the command line, the editor
801 will open with the message of the amended commit.
802 It is not possible to amend public changesets (see hg help phases) or
804 changesets that have children.
805 See hg help dates for a list of formats valid for -d/--date.
807 Returns 0 on success, 1 if nothing changed.
809 Examples:
811 · commit all files ending in .py:
813 hg commit --include "set:**.py"
815 · commit all non-binary files:
817 hg commit --exclude "set:binary()"
819 · amend the current commit and set the date to now:
821 hg commit --amend --date now
823 Options:
825 -A, --addremove
827 mark new/missing files as added/removed before committing
828 --close-branch
830 mark a branch head as closed
831 --amend
833 amend the parent of the working directory
834 -s, --secret
836 use the secret phase for committing
837 -e, --edit
839 invoke editor on commit messages
840 --force-close-branch
842 forcibly close branch from a non-head changeset (ADVANCED)
843 -i, --interactive
845 use interactive mode
846 -I,--include <PATTERN[+]>
848 include names matching the given patterns
849 -X,--exclude <PATTERN[+]>
851 exclude names matching the given patterns
852 -m,--message <TEXT>
854 use text as commit message
855 -l,--logfile <FILE>
857 read commit message from file
858 -d,--date <DATE>
860 record the specified date as commit date
861 -u,--user <USER>
863 record the specified user as committer
864 -S, --subrepos
866 recurse into subrepositories
867 [+] marked option can be specified multiple times
869 aliases: ci
871 Change manipulation
873 abort
874 abort an unfinished operation (EXPERIMENTAL):
875 hg abort
877 Aborts a multistep operation like graft, histedit, rebase, merge, and
879 unshelve if they are in an unfinished state.
880 use --dry-run/-n to dry run the command.
882 Options:
884 -n, --dry-run
886 do not perform actions, just print output
887 backout
889 reverse effect of earlier changeset:
890 hg backout [OPTION]... [-r] REV
892 Prepare a new changeset with the effect of REV undone in the current
894 working directory. If no conflicts were encountered, it will be commit‐
895 ted immediately.
896 If REV is the parent of the working directory, then this new changeset
898 is committed automatically (unless --no-commit is specified).
899 Note hg backout cannot be used to fix either an unwanted or incorrect
901 merge.
902 Examples:
904 · Reverse the effect of the parent of the working directory. This
906 backout will be committed immediately:
907 hg backout -r .
909 · Reverse the effect of previous bad revision 23:
911 hg backout -r 23
913 · Reverse the effect of previous bad revision 23 and leave changes
915 uncommitted:
916 hg backout -r 23 --no-commit
918 hg commit -m "Backout revision 23"
919 By default, the pending changeset will have one parent, maintaining a
921 linear history. With --merge, the pending changeset will instead have
922 two parents: the old parent of the working directory and a new child of
923 REV that simply undoes REV.
924 Before version 1.7, the behavior without --merge was equivalent to
926 specifying --merge followed by hg update --clean . to cancel the merge
927 and leave the child of REV as a head to be merged separately.
928 See hg help dates for a list of formats valid for -d/--date.
930 See hg help revert for a way to restore files to the state of another
932 revision.
933 Returns 0 on success, 1 if nothing to backout or there are unresolved
935 files.
936 Options:
938 --merge
940 merge with old dirstate parent after backout
941 --commit
943 commit if no conflicts were encountered (DEPRECATED)
944 --no-commit
946 do not commit
947 --parent <REV>
949 parent to choose when backing out merge (DEPRECATED)
950 -r,--rev <REV>
952 revision to backout
953 -e, --edit
955 invoke editor on commit messages
956 -t,--tool <TOOL>
958 specify merge tool
959 -I,--include <PATTERN[+]>
961 include names matching the given patterns
962 -X,--exclude <PATTERN[+]>
964 exclude names matching the given patterns
965 -m,--message <TEXT>
967 use text as commit message
968 -l,--logfile <FILE>
970 read commit message from file
971 -d,--date <DATE>
973 record the specified date as commit date
974 -u,--user <USER>
976 record the specified user as committer
977 [+] marked option can be specified multiple times
979 continue
981 resumes an interrupted operation (EXPERIMENTAL):
982 hg continue
984 Finishes a multistep operation like graft, histedit, rebase, merge, and
986 unshelve if they are in an interrupted state.
987 use --dry-run/-n to dry run the command.
989 Options:
991 -n, --dry-run
993 do not perform actions, just print output
994 graft
996 copy changes from other branches onto the current branch:
997 hg graft [OPTION]... [-r REV]... REV...
999 This command uses Mercurial's merge logic to copy individual changes
1001 from other branches without merging branches in the history graph. This
1002 is sometimes known as 'backporting' or 'cherry-picking'. By default,
1003 graft will copy user, date, and description from the source changesets.
1004 Changesets that are ancestors of the current revision, that have
1006 already been grafted, or that are merges will be skipped.
1007 If --log is specified, log messages will have a comment appended of the
1009 form:
1010 (grafted from CHANGESETHASH)
1012 If --force is specified, revisions will be grafted even if they are
1014 already ancestors of, or have been grafted to, the destination. This
1015 is useful when the revisions have since been backed out.
1016 If a graft merge results in conflicts, the graft process is interrupted
1018 so that the current merge can be manually resolved. Once all conflicts
1019 are addressed, the graft process can be continued with the -c/--con‐
1020 tinue option.
1021 The -c/--continue option reapplies all the earlier options.
1023 The --base option exposes more of how graft internally uses merge with
1025 a custom base revision. --base can be used to specify another ancestor
1026 than the first and only parent.
1027 The command:
1029 hg graft -r 345 --base 234
1031 is thus pretty much the same as:
1033 hg diff -r 234 -r 345 | hg import
1035 but using merge to resolve conflicts and track moved files.
1037 The result of a merge can thus be backported as a single commit by
1039 specifying one of the merge parents as base, and thus effectively
1040 grafting the changes from the other side.
1041 It is also possible to collapse multiple changesets and clean up his‐
1043 tory by specifying another ancestor as base, much like rebase --col‐
1044 lapse --keep.
1045 The commit message can be tweaked after the fact using commit --amend .
1047 For using non-ancestors as the base to backout changes, see the backout
1049 command and the hidden --parent option.
1050 Examples:
1052 · copy a single change to the stable branch and edit its description:
1054 hg update stable
1056 hg graft --edit 9393
1057 · graft a range of changesets with one exception, updating dates:
1059 hg graft -D "2085::2093 and not 2091"
1061 · continue a graft after resolving conflicts:
1063 hg graft -c
1065 · show the source of a grafted changeset:
1067 hg log --debug -r .
1069 · show revisions sorted by date:
1071 hg log -r "sort(all(), date)"
1073 · backport the result of a merge as a single commit:
1075 hg graft -r 123 --base 123^
1077 · land a feature branch as one changeset:
1079 hg up -cr default
1081 hg graft -r featureX --base "ancestor('featureX', 'default')"
1082 See hg help revisions for more about specifying revisions.
1084 Returns 0 on successful completion.
1086 Options:
1088 -r,--rev <REV[+]>
1090 revisions to graft
1091 --base <REV>
1093 base revision when doing the graft merge (ADVANCED)
1094 -c, --continue
1096 resume interrupted graft
1097 --stop stop interrupted graft
1099 --abort
1101 abort interrupted graft
1102 -e, --edit
1104 invoke editor on commit messages
1105 --log append graft info to log message
1107 --no-commit
1109 don't commit, just apply the changes in working directory
1110 -f, --force
1112 force graft
1113 -D, --currentdate
1115 record the current date as commit date
1116 -U, --currentuser
1118 record the current user as committer
1119 -d,--date <DATE>
1121 record the specified date as commit date
1122 -u,--user <USER>
1124 record the specified user as committer
1125 -t,--tool <TOOL>
1127 specify merge tool
1128 -n, --dry-run
1130 do not perform actions, just print output
1131 [+] marked option can be specified multiple times
1133 merge
1135 merge another revision into working directory:
1136 hg merge [-P] [[-r] REV]
1138 The current working directory is updated with all changes made in the
1140 requested revision since the last common predecessor revision.
1141 Files that changed between either parent are marked as changed for the
1143 next commit and a commit must be performed before any further updates
1144 to the repository are allowed. The next commit will have two parents.
1145 --tool can be used to specify the merge tool used for file merges. It
1147 overrides the HGMERGE environment variable and your configuration
1148 files. See hg help merge-tools for options.
1149 If no revision is specified, the working directory's parent is a head
1151 revision, and the current branch contains exactly one other head, the
1152 other head is merged with by default. Otherwise, an explicit revision
1153 with which to merge must be provided.
1154 See hg help resolve for information on handling file conflicts.
1156 To undo an uncommitted merge, use hg merge --abort which will check out
1158 a clean copy of the original merge parent, losing all changes.
1159 Returns 0 on success, 1 if there are unresolved files.
1161 Options:
1163 -f, --force
1165 force a merge including outstanding changes (DEPRECATED)
1166 -r,--rev <REV>
1168 revision to merge
1169 -P, --preview
1171 review revisions to merge (no merge is performed)
1172 --abort
1174 abort the ongoing merge
1175 -t,--tool <TOOL>
1177 specify merge tool
1178 Change organization
1180 bookmarks
1181 create a new bookmark or list existing bookmarks:
1182 hg bookmarks [OPTIONS]... [NAME]...
1184 Bookmarks are labels on changesets to help track lines of development.
1186 Bookmarks are unversioned and can be moved, renamed and deleted.
1187 Deleting or moving a bookmark has no effect on the associated change‐
1188 sets.
1189 Creating or updating to a bookmark causes it to be marked as 'active'.
1191 The active bookmark is indicated with a '*'. When a commit is made,
1192 the active bookmark will advance to the new commit. A plain hg update
1193 will also advance an active bookmark, if possible. Updating away from
1194 a bookmark will cause it to be deactivated.
1195 Bookmarks can be pushed and pulled between repositories (see hg help
1197 push and hg help pull). If a shared bookmark has diverged, a new
1198 'divergent bookmark' of the form 'name@path' will be created. Using hg
1199 merge will resolve the divergence.
1200 Specifying bookmark as '.' to -m/-d/-l options is equivalent to speci‐
1202 fying the active bookmark's name.
1203 A bookmark named '@' has the special property that hg clone will check
1205 it out by default if it exists.
1206 Template:
1208 The following keywords are supported in addition to the common template
1210 keywords and functions such as {bookmark}. See also hg help templates.
1211 active Boolean. True if the bookmark is active.
1213 Examples:
1215 · create an active bookmark for a new line of development:
1217 hg book new-feature
1219 · create an inactive bookmark as a place marker:
1221 hg book -i reviewed
1223 · create an inactive bookmark on another changeset:
1225 hg book -r .^ tested
1227 · rename bookmark turkey to dinner:
1229 hg book -m turkey dinner
1231 · move the '@' bookmark from another branch:
1233 hg book -f @
1235 · print only the active bookmark name:
1237 hg book -ql .
1239 Options:
1241 -f, --force
1243 force
1244 -r,--rev <REV>
1246 revision for bookmark action
1247 -d, --delete
1249 delete a given bookmark
1250 -m,--rename <OLD>
1252 rename a given bookmark
1253 -i, --inactive
1255 mark a bookmark inactive
1256 -l, --list
1258 list existing bookmarks
1259 -T,--template <TEMPLATE>
1261 display with template
1262 aliases: bookmark
1264 branch
1266 set or show the current branch name:
1267 hg branch [-fC] [NAME]
1269 Note Branch names are permanent and global. Use hg bookmark to create
1271 a light-weight bookmark instead. See hg help glossary for more
1272 information about named branches and bookmarks.
1273 With no argument, show the current branch name. With one argument, set
1275 the working directory branch name (the branch will not exist in the
1276 repository until the next commit). Standard practice recommends that
1277 primary development take place on the 'default' branch.
1278 Unless -f/--force is specified, branch will not let you set a branch
1280 name that already exists.
1281 Use -C/--clean to reset the working directory branch to that of the
1283 parent of the working directory, negating a previous branch change.
1284 Use the command hg update to switch to an existing branch. Use hg com‐
1286 mit --close-branch to mark this branch head as closed. When all heads
1287 of a branch are closed, the branch will be considered closed.
1288 Returns 0 on success.
1290 Options:
1292 -f, --force
1294 set branch name even if it shadows an existing branch
1295 -C, --clean
1297 reset branch name to parent branch name
1298 -r,--rev <VALUE[+]>
1300 change branches of the given revs (EXPERIMENTAL)
1301 [+] marked option can be specified multiple times
1303 branches
1305 list repository named branches:
1306 hg branches [-c]
1308 List the repository's named branches, indicating which ones are inac‐
1310 tive. If -c/--closed is specified, also list branches which have been
1311 marked closed (see hg commit --close-branch).
1312 Use the command hg update to switch to an existing branch.
1314 Template:
1316 The following keywords are supported in addition to the common template
1318 keywords and functions such as {branch}. See also hg help templates.
1319 active Boolean. True if the branch is active.
1321 closed Boolean. True if the branch is closed.
1323 current
1325 Boolean. True if it is the current branch.
1326 Returns 0.
1328 Options:
1330 -a, --active
1332 show only branches that have unmerged heads (DEPRECATED)
1333 -c, --closed
1335 show normal and closed branches
1336 -r,--rev <VALUE[+]>
1338 show branch name(s) of the given rev
1339 -T,--template <TEMPLATE>
1341 display with template
1342 [+] marked option can be specified multiple times
1344 phase
1346 set or show the current phase name:
1347 hg phase [-p|-d|-s] [-f] [-r] [REV...]
1349 With no argument, show the phase name of the current revision(s).
1351 With one of -p/--public, -d/--draft or -s/--secret, change the phase
1353 value of the specified revisions.
1354 Unless -f/--force is specified, hg phase won't move changesets from a
1356 lower phase to a higher phase. Phases are ordered as follows:
1357 public < draft < secret
1359 Returns 0 on success, 1 if some phases could not be changed.
1361 (For more information about the phases concept, see hg help phases.)
1363 Options:
1365 -p, --public
1367 set changeset phase to public
1368 -d, --draft
1370 set changeset phase to draft
1371 -s, --secret
1373 set changeset phase to secret
1374 -f, --force
1376 allow to move boundary backward
1377 -r,--rev <REV[+]>
1379 target revision
1380 [+] marked option can be specified multiple times
1382 tag
1384 add one or more tags for the current or given revision:
1385 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
1387 Name a particular revision using <name>.
1389 Tags are used to name particular revisions of the repository and are
1391 very useful to compare different revisions, to go back to significant
1392 earlier versions or to mark branch points as releases, etc. Changing an
1393 existing tag is normally disallowed; use -f/--force to override.
1394 If no revision is given, the parent of the working directory is used.
1396 To facilitate version control, distribution, and merging of tags, they
1398 are stored as a file named ".hgtags" which is managed similarly to
1399 other project files and can be hand-edited if necessary. This also
1400 means that tagging creates a new commit. The file ".hg/localtags" is
1401 used for local tags (not shared among repositories).
1402 Tag commits are usually made at the head of a branch. If the parent of
1404 the working directory is not a branch head, hg tag aborts; use
1405 -f/--force to force the tag commit to be based on a non-head changeset.
1406 See hg help dates for a list of formats valid for -d/--date.
1408 Since tag names have priority over branch names during revision lookup,
1410 using an existing branch name as a tag name is discouraged.
1411 Returns 0 on success.
1413 Options:
1415 -f, --force
1417 force tag
1418 -l, --local
1420 make the tag local
1421 -r,--rev <REV>
1423 revision to tag
1424 --remove
1426 remove a tag
1427 -e, --edit
1429 invoke editor on commit messages
1430 -m,--message <TEXT>
1432 use text as commit message
1433 -d,--date <DATE>
1435 record the specified date as commit date
1436 -u,--user <USER>
1438 record the specified user as committer
1439 tags
1441 list repository tags:
1442 hg tags
1444 This lists both regular and local tags. When the -v/--verbose switch is
1446 used, a third column "local" is printed for local tags. When the
1447 -q/--quiet switch is used, only the tag name is printed.
1448 Template:
1450 The following keywords are supported in addition to the common template
1452 keywords and functions such as {tag}. See also hg help templates.
1453 type String. local for local tags.
1455 Returns 0 on success.
1457 Options:
1459 -T,--template <TEMPLATE>
1461 display with template
1462 File content management
1464 annotate
1465 show changeset information by line for each file:
1466 hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...
1468 List changes in files, showing the revision id responsible for each
1470 line.
1471 This command is useful for discovering when a change was made and by
1473 whom.
1474 If you include --file, --user, or --date, the revision number is sup‐
1476 pressed unless you also include --number.
1477 Without the -a/--text option, annotate will avoid processing files it
1479 detects as binary. With -a, annotate will annotate the file anyway,
1480 although the results will probably be neither useful nor desirable.
1481 Template:
1483 The following keywords are supported in addition to the common template
1485 keywords and functions. See also hg help templates.
1486 lines List of lines with annotation data.
1488 path String. Repository-absolute path of the specified file.
1490 And each entry of {lines} provides the following sub-keywords in addi‐
1492 tion to {date}, {node}, {rev}, {user}, etc.
1493 line String. Line content.
1495 lineno Integer. Line number at that revision.
1497 path String. Repository-absolute path of the file at that revision.
1499 See hg help templates.operators for the list expansion syntax.
1501 Returns 0 on success.
1503 Options:
1505 -r,--rev <REV>
1507 annotate the specified revision
1508 --follow
1510 follow copies/renames and list the filename (DEPRECATED)
1511 --no-follow
1513 don't follow copies and renames
1514 -a, --text
1516 treat all files as text
1517 -u, --user
1519 list the author (long with -v)
1520 -f, --file
1522 list the filename
1523 -d, --date
1525 list the date (short with -q)
1526 -n, --number
1528 list the revision number (default)
1529 -c, --changeset
1531 list the changeset
1532 -l, --line-number
1534 show line number at the first appearance
1535 --skip <REV[+]>
1537 revision to not display (EXPERIMENTAL)
1538 -w, --ignore-all-space
1540 ignore white space when comparing lines
1541 -b, --ignore-space-change
1543 ignore changes in the amount of white space
1544 -B, --ignore-blank-lines
1546 ignore changes whose lines are all blank
1547 -Z, --ignore-space-at-eol
1549 ignore changes in whitespace at EOL
1550 -I,--include <PATTERN[+]>
1552 include names matching the given patterns
1553 -X,--exclude <PATTERN[+]>
1555 exclude names matching the given patterns
1556 -T,--template <TEMPLATE>
1558 display with template
1559 [+] marked option can be specified multiple times
1561 aliases: blame
1563 cat
1565 output the current or given revision of files:
1566 hg cat [OPTION]... FILE...
1568 Print the specified files as they were at the given revision. If no
1570 revision is given, the parent of the working directory is used.
1571 Output may be to a file, in which case the name of the file is given
1573 using a template string. See hg help templates. In addition to the com‐
1574 mon template keywords, the following formatting rules are supported:
1575 %%
1577 literal "%" character
1579 %s
1581 basename of file being printed
1583 %d
1585 dirname of file being printed, or '.' if in repository root
1587 %p
1589 root-relative path name of file being printed
1591 %H
1593 changeset hash (40 hexadecimal digits)
1595 %R
1597 changeset revision number
1599 %h
1601 short-form changeset hash (12 hexadecimal digits)
1603 %r
1605 zero-padded changeset revision number
1607 %b
1609 basename of the exporting repository
1611 \
1613 literal "" character
1615 Template:
1617 The following keywords are supported in addition to the common template
1619 keywords and functions. See also hg help templates.
1620 data String. File content.
1622 path String. Repository-absolute path of the file.
1624 Returns 0 on success.
1626 Options:
1628 -o,--output <FORMAT>
1630 print output to file with formatted name
1631 -r,--rev <REV>
1633 print the given revision
1634 --decode
1636 apply any matching decode filter
1637 -I,--include <PATTERN[+]>
1639 include names matching the given patterns
1640 -X,--exclude <PATTERN[+]>
1642 exclude names matching the given patterns
1643 -T,--template <TEMPLATE>
1645 display with template
1646 [+] marked option can be specified multiple times
1648 copy
1650 mark files as copied for the next commit:
1651 hg copy [OPTION]... SOURCE... DEST
1653 Mark dest as having copies of source files. If dest is a directory,
1655 copies are put in that directory. If dest is a file, the source must be
1656 a single file.
1657 By default, this command copies the contents of files as they exist in
1659 the working directory. If invoked with -A/--after, the operation is
1660 recorded, but no copying is performed.
1661 This command takes effect with the next commit. To undo a copy before
1663 that, see hg revert.
1664 Returns 0 on success, 1 if errors are encountered.
1666 Options:
1668 -A, --after
1670 record a copy that has already occurred
1671 -f, --force
1673 forcibly copy over an existing managed file
1674 -I,--include <PATTERN[+]>
1676 include names matching the given patterns
1677 -X,--exclude <PATTERN[+]>
1679 exclude names matching the given patterns
1680 -n, --dry-run
1682 do not perform actions, just print output
1683 [+] marked option can be specified multiple times
1685 aliases: cp
1687 diff
1689 diff repository (or selected files):
1690 hg diff [OPTION]... ([-c REV] | [-r REV1 [-r REV2]]) [FILE]...
1692 Show differences between revisions for the specified files.
1694 Differences between files are shown using the unified diff format.
1696 Note hg diff may generate unexpected results for merges, as it will
1698 default to comparing against the working directory's first par‐
1699 ent changeset if no revisions are specified.
1700 When two revision arguments are given, then changes are shown between
1702 those revisions. If only one revision is specified then that revision
1703 is compared to the working directory, and, when no revisions are speci‐
1704 fied, the working directory files are compared to its first parent.
1705 Alternatively you can specify -c/--change with a revision to see the
1707 changes in that changeset relative to its first parent.
1708 Without the -a/--text option, diff will avoid generating diffs of files
1710 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1711 bly with undesirable results.
1712 Use the -g/--git option to generate diffs in the git extended diff for‐
1714 mat. For more information, read hg help diffs.
1715 Examples:
1717 · compare a file in the current working directory to its parent:
1719 hg diff foo.c
1721 · compare two historical versions of a directory, with rename info:
1723 hg diff --git -r 1.0:1.2 lib/
1725 · get change stats relative to the last change on some date:
1727 hg diff --stat -r "date('may 2')"
1729 · diff all newly-added files that contain a keyword:
1731 hg diff "set:added() and grep(GNU)"
1733 · compare a revision and its parents:
1735 hg diff -c 9353 # compare against first parent
1737 hg diff -r 9353^:9353 # same using revset syntax
1738 hg diff -r 9353^2:9353 # compare against the second parent
1739 Returns 0 on success.
1741 Options:
1743 -r,--rev <REV[+]>
1745 revision
1746 -c,--change <REV>
1748 change made by revision
1749 -a, --text
1751 treat all files as text
1752 -g, --git
1754 use git extended diff format
1755 --binary
1757 generate binary diffs in git mode (default)
1758 --nodates
1760 omit dates from diff headers
1761 --noprefix
1763 omit a/ and b/ prefixes from filenames
1764 -p, --show-function
1766 show which function each change is in
1767 --reverse
1769 produce a diff that undoes the changes
1770 -w, --ignore-all-space
1772 ignore white space when comparing lines
1773 -b, --ignore-space-change
1775 ignore changes in the amount of white space
1776 -B, --ignore-blank-lines
1778 ignore changes whose lines are all blank
1779 -Z, --ignore-space-at-eol
1781 ignore changes in whitespace at EOL
1782 -U,--unified <NUM>
1784 number of lines of context to show
1785 --stat output diffstat-style summary of changes
1787 --root <DIR>
1789 produce diffs relative to subdirectory
1790 -I,--include <PATTERN[+]>
1792 include names matching the given patterns
1793 -X,--exclude <PATTERN[+]>
1795 exclude names matching the given patterns
1796 -S, --subrepos
1798 recurse into subrepositories
1799 [+] marked option can be specified multiple times
1801 grep
1803 search for a pattern in specified files:
1804 hg grep [--diff] [OPTION]... PATTERN [FILE]...
1806 Search the working directory or revision history for a regular expres‐
1808 sion in the specified files for the entire repository.
1809 By default, grep searches the repository files in the working directory
1811 and prints the files where it finds a match. To specify historical
1812 revisions instead of the working directory, use the --rev flag.
1813 To search instead historical revision differences that contains a
1815 change in match status ("-" for a match that becomes a non-match, or
1816 "+" for a non-match that becomes a match), use the --diff flag.
1817 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1819 If no FILEs are specified and the --rev flag isn't supplied, all files
1821 in the working directory are searched. When using the --rev flag and
1822 specifying FILEs, use the --follow argument to also follow the speci‐
1823 fied FILEs across renames and copies.
1824 Template:
1826 The following keywords are supported in addition to the common template
1828 keywords and functions. See also hg help templates.
1829 change String. Character denoting insertion + or removal -. Available
1831 if --diff is specified.
1832 lineno Integer. Line number of the match.
1834 path String. Repository-absolute path of the file.
1836 texts List of text chunks.
1838 And each entry of {texts} provides the following sub-keywords.
1840 matched
1842 Boolean. True if the chunk matches the specified pattern.
1843 text String. Chunk content.
1845 See hg help templates.operators for the list expansion syntax.
1847 Returns 0 if a match is found, 1 otherwise.
1849 Options:
1851 -0, --print0
1853 end fields with NUL
1854 --all print all revisions that match (DEPRECATED)
1856 --diff search revision differences for when the pattern was added or
1858 removed
1859 -a, --text
1861 treat all files as text
1862 -f, --follow
1864 follow changeset history, or file history across copies and
1865 renames
1866 -i, --ignore-case
1868 ignore case when matching
1869 -l, --files-with-matches
1871 print only filenames and revisions that match
1872 -n, --line-number
1874 print matching line numbers
1875 -r,--rev <REV[+]>
1877 search files changed within revision range
1878 --all-files
1880 include all files in the changeset while grepping (DEPRECATED)
1881 -u, --user
1883 list the author (long with -v)
1884 -d, --date
1886 list the date (short with -q)
1887 -T,--template <TEMPLATE>
1889 display with template
1890 -I,--include <PATTERN[+]>
1892 include names matching the given patterns
1893 -X,--exclude <PATTERN[+]>
1895 exclude names matching the given patterns
1896 [+] marked option can be specified multiple times
1898 Change navigation
1900 bisect
1901 subdivision search of changesets:
1902 hg bisect [-gbsr] [-U] [-c CMD] [REV]
1904 This command helps to find changesets which introduce problems. To use,
1906 mark the earliest changeset you know exhibits the problem as bad, then
1907 mark the latest changeset which is free from the problem as good.
1908 Bisect will update your working directory to a revision for testing
1909 (unless the -U/--noupdate option is specified). Once you have performed
1910 tests, mark the working directory as good or bad, and bisect will
1911 either update to another candidate changeset or announce that it has
1912 found the bad revision.
1913 As a shortcut, you can also use the revision argument to mark a revi‐
1915 sion as good or bad without checking it out first.
1916 If you supply a command, it will be used for automatic bisection. The
1918 environment variable HG_NODE will contain the ID of the changeset being
1919 tested. The exit status of the command will be used to mark revisions
1920 as good or bad: status 0 means good, 125 means to skip the revision,
1921 127 (command not found) will abort the bisection, and any other
1922 non-zero exit status means the revision is bad.
1923 Some examples:
1925 · start a bisection with known bad revision 34, and good revision 12:
1927 hg bisect --bad 34
1929 hg bisect --good 12
1930 · advance the current bisection by marking current revision as good or
1932 bad:
1933 hg bisect --good
1935 hg bisect --bad
1936 · mark the current revision, or a known revision, to be skipped (e.g.
1938 if that revision is not usable because of another issue):
1939 hg bisect --skip
1941 hg bisect --skip 23
1942 · skip all revisions that do not touch directories foo or bar:
1944 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
1946 · forget the current bisection:
1948 hg bisect --reset
1950 · use 'make && make tests' to automatically find the first broken revi‐
1952 sion:
1953 hg bisect --reset
1955 hg bisect --bad 34
1956 hg bisect --good 12
1957 hg bisect --command "make && make tests"
1958 · see all changesets whose states are already known in the current
1960 bisection:
1961 hg log -r "bisect(pruned)"
1963 · see the changeset currently being bisected (especially useful if run‐
1965 ning with -U/--noupdate):
1966 hg log -r "bisect(current)"
1968 · see all changesets that took part in the current bisection:
1970 hg log -r "bisect(range)"
1972 · you can even get a nice graph:
1974 hg log --graph -r "bisect(range)"
1976 See hg help revisions.bisect for more about the bisect() predicate.
1978 Returns 0 on success.
1980 Options:
1982 -r, --reset
1984 reset bisect state
1985 -g, --good
1987 mark changeset good
1988 -b, --bad
1990 mark changeset bad
1991 -s, --skip
1993 skip testing changeset
1994 -e, --extend
1996 extend the bisect range
1997 -c,--command <CMD>
1999 use command to check changeset state
2000 -U, --noupdate
2002 do not update to target
2003 heads
2005 show branch heads:
2006 hg heads [-ct] [-r STARTREV] [REV]...
2008 With no arguments, show all open branch heads in the repository.
2010 Branch heads are changesets that have no descendants on the same
2011 branch. They are where development generally takes place and are the
2012 usual targets for update and merge operations.
2013 If one or more REVs are given, only open branch heads on the branches
2015 associated with the specified changesets are shown. This means that you
2016 can use hg heads . to see the heads on the currently checked-out
2017 branch.
2018 If -c/--closed is specified, also show branch heads marked closed (see
2020 hg commit --close-branch).
2021 If STARTREV is specified, only those heads that are descendants of
2023 STARTREV will be displayed.
2024 If -t/--topo is specified, named branch mechanics will be ignored and
2026 only topological heads (changesets with no children) will be shown.
2027 Returns 0 if matching heads are found, 1 if not.
2029 Options:
2031 -r,--rev <STARTREV>
2033 show only heads which are descendants of STARTREV
2034 -t, --topo
2036 show topological heads only
2037 -a, --active
2039 show active branchheads only (DEPRECATED)
2040 -c, --closed
2042 show normal and closed branch heads
2043 --style <STYLE>
2045 display using template map file (DEPRECATED)
2046 -T,--template <TEMPLATE>
2048 display with template
2049 identify
2051 identify the working directory or specified revision:
2052 hg identify [-nibtB] [-r REV] [SOURCE]
2054 Print a summary identifying the repository state at REV using one or
2056 two parent hash identifiers, followed by a "+" if the working directory
2057 has uncommitted changes, the branch name (if not default), a list of
2058 tags, and a list of bookmarks.
2059 When REV is not given, print a summary of the current state of the
2061 repository including the working directory. Specify -r. to get informa‐
2062 tion of the working directory parent without scanning uncommitted
2063 changes.
2064 Specifying a path to a repository root or Mercurial bundle will cause
2066 lookup to operate on that repository/bundle.
2067 Template:
2069 The following keywords are supported in addition to the common template
2071 keywords and functions. See also hg help templates.
2072 dirty String. Character + denoting if the working directory has uncom‐
2074 mitted changes.
2075 id String. One or two nodes, optionally followed by +.
2077 parents
2079 List of strings. Parent nodes of the changeset.
2080 Examples:
2082 · generate a build identifier for the working directory:
2084 hg id --id > build-id.dat
2086 · find the revision corresponding to a tag:
2088 hg id -n -r 1.3
2090 · check the most recent revision of a remote repository:
2092 hg id -r tip https://www.mercurial-scm.org/repo/hg/
2094 See hg log for generating more information about specific revisions,
2096 including full hash identifiers.
2097 Returns 0 if successful.
2099 Options:
2101 -r,--rev <REV>
2103 identify the specified revision
2104 -n, --num
2106 show local revision number
2107 -i, --id
2109 show global revision id
2110 -b, --branch
2112 show branch
2113 -t, --tags
2115 show tags
2116 -B, --bookmarks
2118 show bookmarks
2119 -e,--ssh <CMD>
2121 specify ssh command to use
2122 --remotecmd <CMD>
2124 specify hg command to run on the remote side
2125 --insecure
2127 do not verify server certificate (ignoring web.cacerts config)
2128 -T,--template <TEMPLATE>
2130 display with template
2131 aliases: id
2133 log
2135 show revision history of entire repository or files:
2136 hg log [OPTION]... [FILE]
2138 Print the revision history of the specified files or the entire
2140 project.
2141 If no revision range is specified, the default is tip:0 unless --follow
2143 is set, in which case the working directory parent is used as the
2144 starting revision.
2145 File history is shown without following rename or copy history of
2147 files. Use -f/--follow with a filename to follow history across renames
2148 and copies. --follow without a filename will only show ancestors of the
2149 starting revision.
2150 By default this command prints revision number and changeset id, tags,
2152 non-trivial parents, user, date and time, and a summary for each com‐
2153 mit. When the -v/--verbose switch is used, the list of changed files
2154 and full commit message are shown.
2155 With --graph the revisions are shown as an ASCII art DAG with the most
2157 recent changeset at the top. 'o' is a changeset, '@' is a working
2158 directory parent, '_' closes a branch, 'x' is obsolete, '*' is unsta‐
2159 ble, and '+' represents a fork where the changeset from the lines below
2160 is a parent of the 'o' merge on the same line. Paths in the DAG are
2161 represented with '|', '/' and so forth. ':' in place of a '|' indicates
2162 one or more revisions in a path are omitted.
2163 Use -L/--line-range FILE,M:N options to follow the history of lines
2165 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2166 fied line range will be shown. This option requires --follow; it can be
2167 specified multiple times. Currently, this option is not compatible with
2168 --graph. This option is experimental.
2169 Note hg log --patch may generate unexpected diff output for merge
2171 changesets, as it will only compare the merge changeset against
2172 its first parent. Also, only files different from BOTH parents
2173 will appear in files:.
2174 Note For performance reasons, hg log FILE may omit duplicate changes
2176 made on branches and will not show removals or mode changes. To
2177 see all such changes, use the --removed switch.
2178 Note The history resulting from -L/--line-range options depends on
2180 diff options; for instance if white-spaces are ignored, respec‐
2181 tive changes with only white-spaces in specified line range will
2182 not be listed.
2183 Some examples:
2185 · changesets with full descriptions and file lists:
2187 hg log -v
2189 · changesets ancestral to the working directory:
2191 hg log -f
2193 · last 10 commits on the current branch:
2195 hg log -l 10 -b .
2197 · changesets showing all modifications of a file, including removals:
2199 hg log --removed file.c
2201 · all changesets that touch a directory, with diffs, excluding merges:
2203 hg log -Mp lib/
2205 · all revision numbers that match a keyword:
2207 hg log -k bug --template "{rev}\n"
2209 · the full hash identifier of the working directory parent:
2211 hg log -r . --template "{node}\n"
2213 · list available log templates:
2215 hg log -T list
2217 · check if a given changeset is included in a tagged release:
2219 hg log -r "a21ccf and ancestor(1.9)"
2221 · find all changesets by some user in a date range:
2223 hg log -k alice -d "may 2008 to jul 2008"
2225 · summary of all changesets after the last tag:
2227 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2229 · changesets touching lines 13 to 23 for file.c:
2231 hg log -L file.c,13:23
2233 · changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2235 main.c with patch:
2236 hg log -L file.c,13:23 -L main.c,2:6 -p
2238 See hg help dates for a list of formats valid for -d/--date.
2240 See hg help revisions for more about specifying and ordering revisions.
2242 See hg help templates for more about pre-packaged styles and specifying
2244 custom templates. The default template used by the log command can be
2245 customized via the ui.logtemplate configuration setting.
2246 Returns 0 on success.
2248 Options:
2250 -f, --follow
2252 follow changeset history, or file history across copies and
2253 renames
2254 --follow-first
2256 only follow the first parent of merge changesets (DEPRECATED)
2257 -d,--date <DATE>
2259 show revisions matching date spec
2260 -C, --copies
2262 show copied files
2263 -k,--keyword <TEXT[+]>
2265 do case-insensitive search for a given text
2266 -r,--rev <REV[+]>
2268 show the specified revision or revset
2269 -L,--line-range <FILE,RANGE[+]>
2271 follow line range of specified file (EXPERIMENTAL)
2272 --removed
2274 include revisions where files were removed
2275 -m, --only-merges
2277 show only merges (DEPRECATED) (use -r "merge()" instead)
2278 -u,--user <USER[+]>
2280 revisions committed by user
2281 --only-branch <BRANCH[+]>
2283 show only changesets within the given named branch (DEPRECATED)
2284 -b,--branch <BRANCH[+]>
2286 show changesets within the given named branch
2287 -P,--prune <REV[+]>
2289 do not display revision or any of its ancestors
2290 -p, --patch
2292 show patch
2293 -g, --git
2295 use git extended diff format
2296 -l,--limit <NUM>
2298 limit number of changes displayed
2299 -M, --no-merges
2301 do not show merges
2302 --stat output diffstat-style summary of changes
2304 -G, --graph
2306 show the revision DAG
2307 --style <STYLE>
2309 display using template map file (DEPRECATED)
2310 -T,--template <TEMPLATE>
2312 display with template
2313 -I,--include <PATTERN[+]>
2315 include names matching the given patterns
2316 -X,--exclude <PATTERN[+]>
2318 exclude names matching the given patterns
2319 [+] marked option can be specified multiple times
2321 aliases: history
2323 parents
2325 show the parents of the working directory or revision (DEPRECATED):
2326 hg parents [-r REV] [FILE]
2328 Print the working directory's parent revisions. If a revision is given
2330 via -r/--rev, the parent of that revision will be printed. If a file
2331 argument is given, the revision in which the file was last changed
2332 (before the working directory revision or the argument to --rev if
2333 given) is printed.
2334 This command is equivalent to:
2336 hg log -r "p1()+p2()" or
2338 hg log -r "p1(REV)+p2(REV)" or
2339 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2340 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2341 See hg summary and hg help revsets for related information.
2343 Returns 0 on success.
2345 Options:
2347 -r,--rev <REV>
2349 show parents of the specified revision
2350 --style <STYLE>
2352 display using template map file (DEPRECATED)
2353 -T,--template <TEMPLATE>
2355 display with template
2356 tip
2358 show the tip revision (DEPRECATED):
2359 hg tip [-p] [-g]
2361 The tip revision (usually just called the tip) is the changeset most
2363 recently added to the repository (and therefore the most recently
2364 changed head).
2365 If you have just made a commit, that commit will be the tip. If you
2367 have just pulled changes from another repository, the tip of that
2368 repository becomes the current tip. The "tip" tag is special and cannot
2369 be renamed or assigned to a different changeset.
2370 This command is deprecated, please use hg heads instead.
2372 Returns 0 on success.
2374 Options:
2376 -p, --patch
2378 show patch
2379 -g, --git
2381 use git extended diff format
2382 --style <STYLE>
2384 display using template map file (DEPRECATED)
2385 -T,--template <TEMPLATE>
2387 display with template
2388 Working directory management
2390 add
2391 add the specified files on the next commit:
2392 hg add [OPTION]... [FILE]...
2394 Schedule files to be version controlled and added to the repository.
2396 The files will be added to the repository at the next commit. To undo
2398 an add before that, see hg forget.
2399 If no names are given, add all files to the repository (except files
2401 matching .hgignore).
2402 Examples:
2404 · New (unknown) files are added automatically by hg add:
2406 $ ls
2408 foo.c
2409 $ hg status
2410 ? foo.c
2411 $ hg add
2412 adding foo.c
2413 $ hg status
2414 A foo.c
2415 · Specific files to be added can be specified:
2417 $ ls
2419 bar.c foo.c
2420 $ hg status
2421 ? bar.c
2422 ? foo.c
2423 $ hg add bar.c
2424 $ hg status
2425 A bar.c
2426 ? foo.c
2427 Returns 0 if all files are successfully added.
2429 Options:
2431 -I,--include <PATTERN[+]>
2433 include names matching the given patterns
2434 -X,--exclude <PATTERN[+]>
2436 exclude names matching the given patterns
2437 -S, --subrepos
2439 recurse into subrepositories
2440 -n, --dry-run
2442 do not perform actions, just print output
2443 [+] marked option can be specified multiple times
2445 addremove
2447 add all new files, delete all missing files:
2448 hg addremove [OPTION]... [FILE]...
2450 Add all new files and remove all missing files from the repository.
2452 Unless names are given, new files are ignored if they match any of the
2454 patterns in .hgignore. As with add, these changes take effect at the
2455 next commit.
2456 Use the -s/--similarity option to detect renamed files. This option
2458 takes a percentage between 0 (disabled) and 100 (files must be identi‐
2459 cal) as its parameter. With a parameter greater than 0, this compares
2460 every removed file with every added file and records those similar
2461 enough as renames. Detecting renamed files this way can be expensive.
2462 After using this option, hg status -C can be used to check which files
2463 were identified as moved or renamed. If not specified, -s/--similarity
2464 defaults to 100 and only renames of identical files are detected.
2465 Examples:
2467 · A number of files (bar.c and foo.c) are new, while foobar.c has
2469 been removed (without using hg remove) from the repository:
2470 $ ls
2472 bar.c foo.c
2473 $ hg status
2474 ! foobar.c
2475 ? bar.c
2476 ? foo.c
2477 $ hg addremove
2478 adding bar.c
2479 adding foo.c
2480 removing foobar.c
2481 $ hg status
2482 A bar.c
2483 A foo.c
2484 R foobar.c
2485 · A file foobar.c was moved to foo.c without using hg rename.
2487 Afterwards, it was edited slightly:
2488 $ ls
2490 foo.c
2491 $ hg status
2492 ! foobar.c
2493 ? foo.c
2494 $ hg addremove --similarity 90
2495 removing foobar.c
2496 adding foo.c
2497 recording removal of foobar.c as rename to foo.c (94% similar)
2498 $ hg status -C
2499 A foo.c
2500 foobar.c
2501 R foobar.c
2502 Returns 0 if all files are successfully added.
2504 Options:
2506 -s,--similarity <SIMILARITY>
2508 guess renamed files by similarity (0<=s<=100)
2509 -S, --subrepos
2511 recurse into subrepositories
2512 -I,--include <PATTERN[+]>
2514 include names matching the given patterns
2515 -X,--exclude <PATTERN[+]>
2517 exclude names matching the given patterns
2518 -n, --dry-run
2520 do not perform actions, just print output
2521 [+] marked option can be specified multiple times
2523 files
2525 list tracked files:
2526 hg files [OPTION]... [FILE]...
2528 Print files under Mercurial control in the working directory or speci‐
2530 fied revision for given files (excluding removed files). Files can be
2531 specified as filenames or filesets.
2532 If no files are given to match, this command prints the names of all
2534 files under Mercurial control.
2535 Template:
2537 The following keywords are supported in addition to the common template
2539 keywords and functions. See also hg help templates.
2540 flags String. Character denoting file's symlink and executable bits.
2542 path String. Repository-absolute path of the file.
2544 size Integer. Size of the file in bytes.
2546 Examples:
2548 · list all files under the current directory:
2550 hg files .
2552 · shows sizes and flags for current revision:
2554 hg files -vr .
2556 · list all files named README:
2558 hg files -I "**/README"
2560 · list all binary files:
2562 hg files "set:binary()"
2564 · find files containing a regular expression:
2566 hg files "set:grep('bob')"
2568 · search tracked file contents with xargs and grep:
2570 hg files -0 | xargs -0 grep foo
2572 See hg help patterns and hg help filesets for more information on spec‐
2574 ifying file patterns.
2575 Returns 0 if a match is found, 1 otherwise.
2577 Options:
2579 -r,--rev <REV>
2581 search the repository as it is in REV
2582 -0, --print0
2584 end filenames with NUL, for use with xargs
2585 -I,--include <PATTERN[+]>
2587 include names matching the given patterns
2588 -X,--exclude <PATTERN[+]>
2590 exclude names matching the given patterns
2591 -T,--template <TEMPLATE>
2593 display with template
2594 -S, --subrepos
2596 recurse into subrepositories
2597 [+] marked option can be specified multiple times
2599 forget
2601 forget the specified files on the next commit:
2602 hg forget [OPTION]... FILE...
2604 Mark the specified files so they will no longer be tracked after the
2606 next commit.
2607 This only removes files from the current branch, not from the entire
2609 project history, and it does not delete them from the working direc‐
2610 tory.
2611 To delete the file from the working directory, see hg remove.
2613 To undo a forget before the next commit, see hg add.
2615 Examples:
2617 · forget newly-added binary files:
2619 hg forget "set:added() and binary()"
2621 · forget files that would be excluded by .hgignore:
2623 hg forget "set:hgignore()"
2625 Returns 0 on success.
2627 Options:
2629 -i, --interactive
2631 use interactive mode
2632 -I,--include <PATTERN[+]>
2634 include names matching the given patterns
2635 -X,--exclude <PATTERN[+]>
2637 exclude names matching the given patterns
2638 -n, --dry-run
2640 do not perform actions, just print output
2641 [+] marked option can be specified multiple times
2643 locate
2645 locate files matching specific patterns (DEPRECATED):
2646 hg locate [OPTION]... [PATTERN]...
2648 Print files under Mercurial control in the working directory whose
2650 names match the given patterns.
2651 By default, this command searches all directories in the working direc‐
2653 tory. To search just the current directory and its subdirectories, use
2654 "--include .".
2655 If no patterns are given to match, this command prints the names of all
2657 files under Mercurial control in the working directory.
2658 If you want to feed the output of this command into the "xargs" com‐
2660 mand, use the -0 option to both this command and "xargs". This will
2661 avoid the problem of "xargs" treating single filenames that contain
2662 whitespace as multiple filenames.
2663 See hg help files for a more versatile command.
2665 Returns 0 if a match is found, 1 otherwise.
2667 Options:
2669 -r,--rev <REV>
2671 search the repository as it is in REV
2672 -0, --print0
2674 end filenames with NUL, for use with xargs
2675 -f, --fullpath
2677 print complete paths from the filesystem root
2678 -I,--include <PATTERN[+]>
2680 include names matching the given patterns
2681 -X,--exclude <PATTERN[+]>
2683 exclude names matching the given patterns
2684 [+] marked option can be specified multiple times
2686 remove
2688 remove the specified files on the next commit:
2689 hg remove [OPTION]... FILE...
2691 Schedule the indicated files for removal from the current branch.
2693 This command schedules the files to be removed at the next commit. To
2695 undo a remove before that, see hg revert. To undo added files, see hg
2696 forget.
2697 -A/--after can be used to remove only files that have already been
2699 deleted, -f/--force can be used to force deletion, and -Af can be used
2700 to remove files from the next revision without deleting them from the
2701 working directory.
2702 The following table details the behavior of remove for different file
2704 states (columns) and option combinations (rows). The file states are
2705 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2706 status). The actions are Warn, Remove (from branch) and Delete (from
2707 disk):
2708 ┌──────────┬───┬────┬────┬───┐
2710 │opt/state │ A │ C │ M │ ! │
2711 ├──────────┼───┼────┼────┼───┤
2712 │none │ W │ RD │ W │ R │
2713 ├──────────┼───┼────┼────┼───┤
2714 │-f │ R │ RD │ RD │ R │
2715 ├──────────┼───┼────┼────┼───┤
2716 │-A │ W │ W │ W │ R │
2717 ├──────────┼───┼────┼────┼───┤
2718 │-Af │ R │ R │ R │ R │
2719 └──────────┴───┴────┴────┴───┘
2720 Note hg remove never deletes files in Added [A] state from the work‐
2722 ing directory, not even if --force is specified.
2723 Returns 0 on success, 1 if any warnings encountered.
2725 Options:
2727 -A, --after
2729 record delete for missing files
2730 -f, --force
2732 forget added files, delete modified files
2733 -S, --subrepos
2735 recurse into subrepositories
2736 -I,--include <PATTERN[+]>
2738 include names matching the given patterns
2739 -X,--exclude <PATTERN[+]>
2741 exclude names matching the given patterns
2742 -n, --dry-run
2744 do not perform actions, just print output
2745 [+] marked option can be specified multiple times
2747 aliases: rm
2749 rename
2751 rename files; equivalent of copy + remove:
2752 hg rename [OPTION]... SOURCE... DEST
2754 Mark dest as copies of sources; mark sources for deletion. If dest is a
2756 directory, copies are put in that directory. If dest is a file, there
2757 can only be one source.
2758 By default, this command copies the contents of files as they exist in
2760 the working directory. If invoked with -A/--after, the operation is
2761 recorded, but no copying is performed.
2762 This command takes effect at the next commit. To undo a rename before
2764 that, see hg revert.
2765 Returns 0 on success, 1 if errors are encountered.
2767 Options:
2769 -A, --after
2771 record a rename that has already occurred
2772 -f, --force
2774 forcibly move over an existing managed file
2775 -I,--include <PATTERN[+]>
2777 include names matching the given patterns
2778 -X,--exclude <PATTERN[+]>
2780 exclude names matching the given patterns
2781 -n, --dry-run
2783 do not perform actions, just print output
2784 [+] marked option can be specified multiple times
2786 aliases: move mv
2788 resolve
2790 redo merges or set/view the merge status of files:
2791 hg resolve [OPTION]... [FILE]...
2793 Merges with unresolved conflicts are often the result of non-interac‐
2795 tive merging using the internal:merge configuration setting, or a com‐
2796 mand-line merge tool like diff3. The resolve command is used to manage
2797 the files involved in a merge, after hg merge has been run, and before
2798 hg commit is run (i.e. the working directory must have two parents).
2799 See hg help merge-tools for information on configuring merge tools.
2800 The resolve command can be used in the following ways:
2802 · hg resolve [--re-merge] [--tool TOOL] FILE...: attempt to re-merge
2804 the specified files, discarding any previous merge attempts. Re-merg‐
2805 ing is not performed for files already marked as resolved. Use
2806 --all/-a to select all unresolved files. --tool can be used to spec‐
2807 ify the merge tool used for the given files. It overrides the HGMERGE
2808 environment variable and your configuration files. Previous file
2809 contents are saved with a .orig suffix.
2810 · hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
2812 having manually fixed-up the files). The default is to mark all unre‐
2813 solved files.
2814 · hg resolve -u [FILE]...: mark a file as unresolved. The default is to
2816 mark all resolved files.
2817 · hg resolve -l: list files which had or still have conflicts. In the
2819 printed list, U = unresolved and R = resolved. You can use set:unre‐
2820 solved() or set:resolved() to filter the list. See hg help filesets
2821 for details.
2822 Note Mercurial will not let you commit files with unresolved merge
2824 conflicts. You must use hg resolve -m ... before you can commit
2825 after a conflicting merge.
2826 Template:
2828 The following keywords are supported in addition to the common template
2830 keywords and functions. See also hg help templates.
2831 mergestatus
2833 String. Character denoting merge conflicts, U or R.
2834 path String. Repository-absolute path of the file.
2836 Returns 0 on success, 1 if any files fail a resolve attempt.
2838 Options:
2840 -a, --all
2842 select all unresolved files
2843 -l, --list
2845 list state of files needing merge
2846 -m, --mark
2848 mark files as resolved
2849 -u, --unmark
2851 mark files as unresolved
2852 -n, --no-status
2854 hide status prefix
2855 --re-merge
2857 re-merge files
2858 -t,--tool <TOOL>
2860 specify merge tool
2861 -I,--include <PATTERN[+]>
2863 include names matching the given patterns
2864 -X,--exclude <PATTERN[+]>
2866 exclude names matching the given patterns
2867 -T,--template <TEMPLATE>
2869 display with template
2870 [+] marked option can be specified multiple times
2872 revert
2874 restore files to their checkout state:
2875 hg revert [OPTION]... [-r REV] [NAME]...
2877 Note To check out earlier revisions, you should use hg update REV.
2879 To cancel an uncommitted merge (and lose your changes), use hg
2880 merge --abort.
2881 With no revision specified, revert the specified files or directories
2883 to the contents they had in the parent of the working directory. This
2884 restores the contents of files to an unmodified state and unschedules
2885 adds, removes, copies, and renames. If the working directory has two
2886 parents, you must explicitly specify a revision.
2887 Using the -r/--rev or -d/--date options, revert the given files or
2889 directories to their states as of a specific revision. Because revert
2890 does not change the working directory parents, this will cause these
2891 files to appear modified. This can be helpful to "back out" some or all
2892 of an earlier change. See hg backout for a related method.
2893 Modified files are saved with a .orig suffix before reverting. To dis‐
2895 able these backups, use --no-backup. It is possible to store the backup
2896 files in a custom directory relative to the root of the repository by
2897 setting the ui.origbackuppath configuration option.
2898 See hg help dates for a list of formats valid for -d/--date.
2900 See hg help backout for a way to reverse the effect of an earlier
2902 changeset.
2903 Returns 0 on success.
2905 Options:
2907 -a, --all
2909 revert all changes when no arguments given
2910 -d,--date <DATE>
2912 tipmost revision matching date
2913 -r,--rev <REV>
2915 revert to the specified revision
2916 -C, --no-backup
2918 do not save backup copies of files
2919 -i, --interactive
2921 interactively select the changes
2922 -I,--include <PATTERN[+]>
2924 include names matching the given patterns
2925 -X,--exclude <PATTERN[+]>
2927 exclude names matching the given patterns
2928 -n, --dry-run
2930 do not perform actions, just print output
2931 [+] marked option can be specified multiple times
2933 root
2935 print the root (top) of the current working directory:
2936 hg root
2938 Print the root directory of the current repository.
2940 Template:
2942 The following keywords are supported in addition to the common template
2944 keywords and functions. See also hg help templates.
2945 hgpath String. Path to the .hg directory.
2947 storepath
2949 String. Path to the directory holding versioned data.
2950 Returns 0 on success.
2952 Options:
2954 -T,--template <TEMPLATE>
2956 display with template
2957 shelve
2959 save and set aside changes from the working directory:
2960 hg shelve [OPTION]... [FILE]...
2962 Shelving takes files that "hg status" reports as not clean, saves the
2964 modifications to a bundle (a shelved change), and reverts the files so
2965 that their state in the working directory becomes clean.
2966 To restore these changes to the working directory, using "hg unshelve";
2968 this will work even if you switch to a different commit.
2969 When no files are specified, "hg shelve" saves all not-clean files. If
2971 specific files or directories are named, only changes to those files
2972 are shelved.
2973 In bare shelve (when no files are specified, without interactive,
2975 include and exclude option), shelving remembers information if the
2976 working directory was on newly created branch, in other words working
2977 directory was on different branch than its first parent. In this situa‐
2978 tion unshelving restores branch information to the working directory.
2979 Each shelved change has a name that makes it easier to find later. The
2981 name of a shelved change defaults to being based on the active book‐
2982 mark, or if there is no active bookmark, the current named branch. To
2983 specify a different name, use --name.
2984 To see a list of existing shelved changes, use the --list option. For
2986 each shelved change, this will print its name, age, and description;
2987 use --patch or --stat for more details.
2988 To delete specific shelved changes, use --delete. To delete all shelved
2990 changes, use --cleanup.
2991 Options:
2993 -A, --addremove
2995 mark new/missing files as added/removed before shelving
2996 -u, --unknown
2998 store unknown files in the shelve
2999 --cleanup
3001 delete all shelved changes
3002 --date <DATE>
3004 shelve with the specified commit date
3005 -d, --delete
3007 delete the named shelved change(s)
3008 -e, --edit
3010 invoke editor on commit messages
3011 -k, --keep
3013 shelve, but keep changes in the working directory
3014 -l, --list
3016 list current shelves
3017 -m,--message <TEXT>
3019 use text as shelve message
3020 -n,--name <NAME>
3022 use the given name for the shelved commit
3023 -p, --patch
3025 output patches for changes (provide the names of the shelved
3026 changes as positional arguments)
3027 -i, --interactive
3029 interactive mode
3030 --stat output diffstat-style summary of changes (provide the names of
3032 the shelved changes as positional arguments)
3033 -I,--include <PATTERN[+]>
3035 include names matching the given patterns
3036 -X,--exclude <PATTERN[+]>
3038 exclude names matching the given patterns
3039 [+] marked option can be specified multiple times
3041 status
3043 show changed files in the working directory:
3044 hg status [OPTION]... [FILE]...
3046 Show status of files in the repository. If names are given, only files
3048 that match are shown. Files that are clean or ignored or the source of
3049 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3050 -C/--copies or -A/--all are given. Unless options described with "show
3051 only ..." are given, the options -mardu are used.
3052 Option -q/--quiet hides untracked (unknown and ignored) files unless
3054 explicitly requested with -u/--unknown or -i/--ignored.
3055 Note hg status may appear to disagree with diff if permissions have
3057 changed or a merge has occurred. The standard diff format does
3058 not report permission changes and diff only reports changes rel‐
3059 ative to one merge parent.
3060 If one revision is given, it is used as the base revision. If two
3062 revisions are given, the differences between them are shown. The
3063 --change option can also be used as a shortcut to list the changed
3064 files of a revision from its first parent.
3065 The codes used to show the status of files are:
3067 M = modified
3069 A = added
3070 R = removed
3071 C = clean
3072 ! = missing (deleted by non-hg command, but still tracked)
3073 ? = not tracked
3074 I = ignored
3075 = origin of the previous file (with --copies)
3076 The -t/--terse option abbreviates the output by showing only the direc‐
3078 tory name if all the files in it share the same status. The option
3079 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3080 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3081 'unknown', 'i' for 'ignored' and 'c' for clean.
3082 It abbreviates only those statuses which are passed. Note that clean
3084 and ignored files are not displayed with '--terse ic' unless the
3085 -c/--clean and -i/--ignored options are also used.
3086 The -v/--verbose option shows information when the repository is in an
3088 unfinished merge, shelve, rebase state etc. You can have this behavior
3089 turned on by default by enabling the commands.status.verbose option.
3090 You can skip displaying some of these states by setting commands.sta‐
3092 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3093 'merge', 'rebase', or 'unshelve'.
3094 Template:
3096 The following keywords are supported in addition to the common template
3098 keywords and functions. See also hg help templates.
3099 path String. Repository-absolute path of the file.
3101 source String. Repository-absolute path of the file originated from.
3103 Available if --copies is specified.
3104 status String. Character denoting file's status.
3106 Examples:
3108 · show changes in the working directory relative to a changeset:
3110 hg status --rev 9353
3112 · show changes in the working directory relative to the current direc‐
3114 tory (see hg help patterns for more information):
3115 hg status re:
3117 · show all changes including copies in an existing changeset:
3119 hg status --copies --change 9353
3121 · get a NUL separated list of added files, suitable for xargs:
3123 hg status -an0
3125 · show more information about the repository status, abbreviating
3127 added, removed, modified, deleted, and untracked paths:
3128 hg status -v -t mardu
3130 Returns 0 on success.
3132 Options:
3134 -A, --all
3136 show status of all files
3137 -m, --modified
3139 show only modified files
3140 -a, --added
3142 show only added files
3143 -r, --removed
3145 show only removed files
3146 -d, --deleted
3148 show only deleted (but tracked) files
3149 -c, --clean
3151 show only files without changes
3152 -u, --unknown
3154 show only unknown (not tracked) files
3155 -i, --ignored
3157 show only ignored files
3158 -n, --no-status
3160 hide status prefix
3161 -t,--terse <VALUE>
3163 show the terse output (EXPERIMENTAL) (default: nothing)
3164 -C, --copies
3166 show source of copied files
3167 -0, --print0
3169 end filenames with NUL, for use with xargs
3170 --rev <REV[+]>
3172 show difference from revision
3173 --change <REV>
3175 list the changed files of a revision
3176 -I,--include <PATTERN[+]>
3178 include names matching the given patterns
3179 -X,--exclude <PATTERN[+]>
3181 exclude names matching the given patterns
3182 -S, --subrepos
3184 recurse into subrepositories
3185 -T,--template <TEMPLATE>
3187 display with template
3188 [+] marked option can be specified multiple times
3190 aliases: st
3192 summary
3194 summarize working directory state:
3195 hg summary [--remote]
3197 This generates a brief summary of the working directory state, includ‐
3199 ing parents, branch, commit status, phase and available updates.
3200 With the --remote option, this will check the default paths for incom‐
3202 ing and outgoing changes. This can be time-consuming.
3203 Returns 0 on success.
3205 Options:
3207 --remote
3209 check for push and pull
3210 aliases: sum
3212 unshelve
3214 restore a shelved change to the working directory:
3215 hg unshelve [OPTION]... [FILE]... [-n SHELVED]
3217 This command accepts an optional name of a shelved change to restore.
3219 If none is given, the most recent shelved change is used.
3220 If a shelved change is applied successfully, the bundle that contains
3222 the shelved changes is moved to a backup location (.hg/shelve-backup).
3223 Since you can restore a shelved change on top of an arbitrary commit,
3225 it is possible that unshelving will result in a conflict between your
3226 changes and the commits you are unshelving onto. If this occurs, you
3227 must resolve the conflict, then use --continue to complete the unshelve
3228 operation. (The bundle will not be moved until you successfully com‐
3229 plete the unshelve.)
3230 (Alternatively, you can use --abort to abandon an unshelve that causes
3232 a conflict. This reverts the unshelved changes, and leaves the bundle
3233 in place.)
3234 If bare shelved change (when no files are specified, without interac‐
3236 tive, include and exclude option) was done on newly created branch it
3237 would restore branch information to the working directory.
3238 After a successful unshelve, the shelved changes are stored in a backup
3240 directory. Only the N most recent backups are kept. N defaults to 10
3241 but can be overridden using the shelve.maxbackups configuration option.
3242 Timestamp in seconds is used to decide order of backups. More than
3244 maxbackups backups are kept, if same timestamp prevents from deciding
3245 exact order of them, for safety.
3246 Selected changes can be unshelved with --interactive flag. The working
3248 directory is updated with the selected changes, and only the unselected
3249 changes remain shelved. Note: The whole shelve is applied to working
3250 directory first before running interactively. So, this will bring up
3251 all the conflicts between working directory and the shelve, irrespec‐
3252 tive of which changes will be unshelved.
3253 Options:
3255 -a, --abort
3257 abort an incomplete unshelve operation
3258 -c, --continue
3260 continue an incomplete unshelve operation
3261 -i, --interactive
3263 use interactive mode (EXPERIMENTAL)
3264 -k, --keep
3266 keep shelve after unshelving
3267 -n,--name <NAME>
3269 restore shelved change with given name
3270 -t,--tool <VALUE>
3272 specify merge tool
3273 --date <DATE>
3275 set date for temporary commits (DEPRECATED)
3276 update
3278 update working directory (or switch revisions):
3279 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3281 Update the repository's working directory to the specified changeset.
3283 If no changeset is specified, update to the tip of the current named
3284 branch and move the active bookmark (see hg help bookmarks).
3285 Update sets the working directory's parent revision to the specified
3287 changeset (see hg help parents).
3288 If the changeset is not a descendant or ancestor of the working direc‐
3290 tory's parent and there are uncommitted changes, the update is aborted.
3291 With the -c/--check option, the working directory is checked for uncom‐
3292 mitted changes; if none are found, the working directory is updated to
3293 the specified changeset.
3294 The -C/--clean, -c/--check, and -m/--merge options control what happens
3296 if the working directory contains uncommitted changes. At most of one
3297 of them can be specified.
3298 1. If no option is specified, and if the requested changeset is an
3300 ancestor or descendant of the working directory's parent, the uncom‐
3301 mitted changes are merged into the requested changeset and the
3302 merged result is left uncommitted. If the requested changeset is not
3303 an ancestor or descendant (that is, it is on another branch), the
3304 update is aborted and the uncommitted changes are preserved.
3305 2. With the -m/--merge option, the update is allowed even if the
3307 requested changeset is not an ancestor or descendant of the working
3308 directory's parent.
3309 3. With the -c/--check option, the update is aborted and the uncommit‐
3311 ted changes are preserved.
3312 4. With the -C/--clean option, uncommitted changes are discarded and
3314 the working directory is updated to the requested changeset.
3315 To cancel an uncommitted merge (and lose your changes), use hg merge
3317 --abort.
3318 Use null as the changeset to remove the working directory (like hg
3320 clone -U).
3321 If you want to revert just one file to an older revision, use hg revert
3323 [-r REV] NAME.
3324 See hg help dates for a list of formats valid for -d/--date.
3326 Returns 0 on success, 1 if there are unresolved files.
3328 Options:
3330 -C, --clean
3332 discard uncommitted changes (no backup)
3333 -c, --check
3335 require clean working directory
3336 -m, --merge
3338 merge uncommitted changes
3339 -d,--date <DATE>
3341 tipmost revision matching date
3342 -r,--rev <REV>
3344 revision
3345 -t,--tool <TOOL>
3347 specify merge tool
3348 aliases: up checkout co
3350 Change import/export
3352 archive
3353 create an unversioned archive of a repository revision:
3354 hg archive [OPTION]... DEST
3356 By default, the revision used is the parent of the working directory;
3358 use -r/--rev to specify a different revision.
3359 The archive type is automatically detected based on file extension (to
3361 override, use -t/--type).
3362 Examples:
3364 · create a zip file containing the 1.0 release:
3366 hg archive -r 1.0 project-1.0.zip
3368 · create a tarball excluding .hg files:
3370 hg archive project.tar.gz -X ".hg*"
3372 Valid types are:
3374 files
3376 a directory full of files (default)
3378 tar
3380 tar archive, uncompressed
3382 tbz2
3384 tar archive, compressed using bzip2
3386 tgz
3388 tar archive, compressed using gzip
3390 txz
3392 tar archive, compressed using lzma (only in Python 3)
3394 uzip
3396 zip archive, uncompressed
3398 zip
3400 zip archive, compressed using deflate
3402 The exact name of the destination archive or directory is given using a
3404 format string; see hg help export for details.
3405 Each member added to an archive file has a directory prefix prepended.
3407 Use -p/--prefix to specify a format string for the prefix. The default
3408 is the basename of the archive, with suffixes removed.
3409 Returns 0 on success.
3411 Options:
3413 --no-decode
3415 do not pass files through decoders
3416 -p,--prefix <PREFIX>
3418 directory prefix for files in archive
3419 -r,--rev <REV>
3421 revision to distribute
3422 -t,--type <TYPE>
3424 type of distribution to create
3425 -S, --subrepos
3427 recurse into subrepositories
3428 -I,--include <PATTERN[+]>
3430 include names matching the given patterns
3431 -X,--exclude <PATTERN[+]>
3433 exclude names matching the given patterns
3434 [+] marked option can be specified multiple times
3436 bundle
3438 create a bundle file:
3439 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]
3441 Generate a bundle file containing data to be transferred to another
3443 repository.
3444 To create a bundle containing all changesets, use -a/--all (or --base
3446 null). Otherwise, hg assumes the destination will have all the nodes
3447 you specify with --base parameters. Otherwise, hg will assume the
3448 repository has all the nodes in destination, or default-push/default if
3449 no destination is specified, where destination is the repository you
3450 provide through DEST option.
3451 You can change bundle format with the -t/--type option. See hg help
3453 bundlespec for documentation on this format. By default, the most
3454 appropriate format is used and compression defaults to bzip2.
3455 The bundle file can then be transferred using conventional means and
3457 applied to another repository with the unbundle or pull command. This
3458 is useful when direct push and pull are not available or when exporting
3459 an entire repository is undesirable.
3460 Applying bundles preserves all changeset contents including permis‐
3462 sions, copy/rename information, and revision history.
3463 Returns 0 on success, 1 if no changes found.
3465 Options:
3467 -f, --force
3469 run even when the destination is unrelated
3470 -r,--rev <REV[+]>
3472 a changeset intended to be added to the destination
3473 -b,--branch <BRANCH[+]>
3475 a specific branch you would like to bundle
3476 --base <REV[+]>
3478 a base changeset assumed to be available at the destination
3479 -a, --all
3481 bundle all changesets in the repository
3482 -t,--type <TYPE>
3484 bundle compression type to use (default: bzip2)
3485 -e,--ssh <CMD>
3487 specify ssh command to use
3488 --remotecmd <CMD>
3490 specify hg command to run on the remote side
3491 --insecure
3493 do not verify server certificate (ignoring web.cacerts config)
3494 [+] marked option can be specified multiple times
3496 export
3498 dump the header and diffs for one or more changesets:
3499 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
3501 Print the changeset header and diffs for one or more revisions. If no
3503 revision is given, the parent of the working directory is used.
3504 The information shown in the changeset header is: author, date, branch
3506 name (if non-default), changeset hash, parent(s) and commit comment.
3507 Note hg export may generate unexpected diff output for merge change‐
3509 sets, as it will compare the merge changeset against its first
3510 parent only.
3511 Output may be to a file, in which case the name of the file is given
3513 using a template string. See hg help templates. In addition to the com‐
3514 mon template keywords, the following formatting rules are supported:
3515 %%
3517 literal "%" character
3519 %H
3521 changeset hash (40 hexadecimal digits)
3523 %N
3525 number of patches being generated
3527 %R
3529 changeset revision number
3531 %b
3533 basename of the exporting repository
3535 %h
3537 short-form changeset hash (12 hexadecimal digits)
3539 %m
3541 first line of the commit message (only alphanumeric characters)
3543 %n
3545 zero-padded sequence number, starting at 1
3547 %r
3549 zero-padded changeset revision number
3551 \
3553 literal "" character
3555 Without the -a/--text option, export will avoid generating diffs of
3557 files it detects as binary. With -a, export will generate a diff any‐
3558 way, probably with undesirable results.
3559 With -B/--bookmark changesets reachable by the given bookmark are
3561 selected.
3562 Use the -g/--git option to generate diffs in the git extended diff for‐
3564 mat. See hg help diffs for more information.
3565 With the --switch-parent option, the diff will be against the second
3567 parent. It can be useful to review a merge.
3568 Template:
3570 The following keywords are supported in addition to the common template
3572 keywords and functions. See also hg help templates.
3573 diff String. Diff content.
3575 parents
3577 List of strings. Parent nodes of the changeset.
3578 Examples:
3580 · use export and import to transplant a bugfix to the current branch:
3582 hg export -r 9353 | hg import -
3584 · export all the changesets between two revisions to a file with rename
3586 information:
3587 hg export --git -r 123:150 > changes.txt
3589 · split outgoing changes into a series of patches with descriptive
3591 names:
3592 hg export -r "outgoing()" -o "%n-%m.patch"
3594 Returns 0 on success.
3596 Options:
3598 -B,--bookmark <BOOKMARK>
3600 export changes only reachable by given bookmark
3601 -o,--output <FORMAT>
3603 print output to file with formatted name
3604 --switch-parent
3606 diff against the second parent
3607 -r,--rev <REV[+]>
3609 revisions to export
3610 -a, --text
3612 treat all files as text
3613 -g, --git
3615 use git extended diff format
3616 --binary
3618 generate binary diffs in git mode (default)
3619 --nodates
3621 omit dates from diff headers
3622 -T,--template <TEMPLATE>
3624 display with template
3625 [+] marked option can be specified multiple times
3627 import
3629 import an ordered set of patches:
3630 hg import [OPTION]... PATCH...
3632 Import a list of patches and commit them individually (unless --no-com‐
3634 mit is specified).
3635 To read a patch from standard input (stdin), use "-" as the patch name.
3637 If a URL is specified, the patch will be downloaded from there.
3638 Import first applies changes to the working directory (unless --bypass
3640 is specified), import will abort if there are outstanding changes.
3641 Use --bypass to apply and commit patches directly to the repository,
3643 without affecting the working directory. Without --exact, patches will
3644 be applied on top of the working directory parent revision.
3645 You can import a patch straight from a mail message. Even patches as
3647 attachments work (to use the body part, it must have type text/plain or
3648 text/x-patch). From and Subject headers of email message are used as
3649 default committer and commit message. All text/plain body parts before
3650 first diff are added to the commit message.
3651 If the imported patch was generated by hg export, user and description
3653 from patch override values from message headers and body. Values given
3654 on command line with -m/--message and -u/--user override these.
3655 If --exact is specified, import will set the working directory to the
3657 parent of each patch before applying it, and will abort if the result‐
3658 ing changeset has a different ID than the one recorded in the patch.
3659 This will guard against various ways that portable patch formats and
3660 mail systems might fail to transfer Mercurial data or metadata. See hg
3661 bundle for lossless transmission.
3662 Use --partial to ensure a changeset will be created from the patch even
3664 if some hunks fail to apply. Hunks that fail to apply will be written
3665 to a <target-file>.rej file. Conflicts can then be resolved by hand
3666 before hg commit --amend is run to update the created changeset. This
3667 flag exists to let people import patches that partially apply without
3668 losing the associated metadata (author, date, description, ...).
3669 Note When no hunks apply cleanly, hg import --partial will create an
3671 empty changeset, importing only the patch metadata.
3672 With -s/--similarity, hg will attempt to discover renames and copies in
3674 the patch in the same way as hg addremove.
3675 It is possible to use external patch programs to perform the patch by
3677 setting the ui.patch configuration option. For the default internal
3678 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
3679 fig for more information about configuration files and how to use these
3680 options.
3681 See hg help dates for a list of formats valid for -d/--date.
3683 Examples:
3685 · import a traditional patch from a website and detect renames:
3687 hg import -s 80 http://example.com/bugfix.patch
3689 · import a changeset from an hgweb server:
3691 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
3693 · import all the patches in an Unix-style mbox:
3695 hg import incoming-patches.mbox
3697 · import patches from stdin:
3699 hg import -
3701 · attempt to exactly restore an exported changeset (not always possi‐
3703 ble):
3704 hg import --exact proposed-fix.patch
3706 · use an external tool to apply a patch which is too fuzzy for the
3708 default internal tool.
3709 hg import --config ui.patch="patch --merge" fuzzy.patch
3711 · change the default fuzzing from 2 to a less strict 7
3713 hg import --config ui.fuzz=7 fuzz.patch
3715 Returns 0 on success, 1 on partial success (see --partial).
3717 Options:
3719 -p,--strip <NUM>
3721 directory strip option for patch. This has the same meaning as
3722 the corresponding patch option (default: )
3723 -b,--base <PATH>
3725 base path (DEPRECATED)
3726 -e, --edit
3728 invoke editor on commit messages
3729 -f, --force
3731 skip check for outstanding uncommitted changes (DEPRECATED)
3732 --no-commit
3734 don't commit, just update the working directory
3735 --bypass
3737 apply patch without touching the working directory
3738 --partial
3740 commit even if some hunks fail
3741 --exact
3743 abort if patch would apply lossily
3744 --prefix <DIR>
3746 apply patch to subdirectory
3747 --import-branch
3749 use any branch information in patch (implied by --exact)
3750 -m,--message <TEXT>
3752 use text as commit message
3753 -l,--logfile <FILE>
3755 read commit message from file
3756 -d,--date <DATE>
3758 record the specified date as commit date
3759 -u,--user <USER>
3761 record the specified user as committer
3762 -s,--similarity <SIMILARITY>
3764 guess renamed files by similarity (0<=s<=100)
3765 aliases: patch
3767 unbundle
3769 apply one or more bundle files:
3770 hg unbundle [-u] FILE...
3772 Apply one or more bundle files generated by hg bundle.
3774 Returns 0 on success, 1 if an update has unresolved files.
3776 Options:
3778 -u, --update
3780 update to new branch head if changesets were unbundled
3781 Repository maintenance
3783 manifest
3784 output the current or given revision of the project manifest:
3785 hg manifest [-r REV]
3787 Print a list of version controlled files for the given revision. If no
3789 revision is given, the first parent of the working directory is used,
3790 or the null revision if no revision is checked out.
3791 With -v, print file permissions, symlink and executable bits. With
3793 --debug, print file revision hashes.
3794 If option --all is specified, the list of all files from all revisions
3796 is printed. This includes deleted and renamed files.
3797 Returns 0 on success.
3799 Options:
3801 -r,--rev <REV>
3803 revision to display
3804 --all list files from all revisions
3806 -T,--template <TEMPLATE>
3808 display with template
3809 recover
3811 roll back an interrupted transaction:
3812 hg recover
3814 Recover from an interrupted commit or pull.
3816 This command tries to fix the repository status after an interrupted
3818 operation. It should only be necessary when Mercurial suggests it.
3819 Returns 0 if successful, 1 if nothing to recover or verify fails.
3821 Options:
3823 --verify
3825 run hg verify after succesful recover (default: )
3826 rollback
3828 roll back the last transaction (DANGEROUS) (DEPRECATED):
3829 hg rollback
3831 Please use hg commit --amend instead of rollback to correct mistakes in
3833 the last commit.
3834 This command should be used with care. There is only one level of roll‐
3836 back, and there is no way to undo a rollback. It will also restore the
3837 dirstate at the time of the last transaction, losing any dirstate
3838 changes since that time. This command does not alter the working direc‐
3839 tory.
3840 Transactions are used to encapsulate the effects of all commands that
3842 create new changesets or propagate existing changesets into a reposi‐
3843 tory.
3844 For example, the following commands are transactional, and their
3846 effects can be rolled back:
3847 · commit
3849 · import
3851 · pull
3853 · push (with this repository as the destination)
3855 · unbundle
3857 To avoid permanent data loss, rollback will refuse to rollback a commit
3859 transaction if it isn't checked out. Use --force to override this pro‐
3860 tection.
3861 The rollback command can be entirely disabled by setting the ui.roll‐
3863 back configuration setting to false. If you're here because you want to
3864 use rollback and it's disabled, you can re-enable the command by set‐
3865 ting ui.rollback to true.
3866 This command is not intended for use on public repositories. Once
3868 changes are visible for pull by other users, rolling a transaction back
3869 locally is ineffective (someone else may already have pulled the
3870 changes). Furthermore, a race is possible with readers of the reposi‐
3871 tory; for example an in-progress pull from the repository may fail if a
3872 rollback is performed.
3873 Returns 0 on success, 1 if no rollback data is available.
3875 Options:
3877 -n, --dry-run
3879 do not perform actions, just print output
3880 -f, --force
3882 ignore safety measures
3883 verify
3885 verify the integrity of the repository:
3886 hg verify
3888 Verify the integrity of the current repository.
3890 This will perform an extensive check of the repository's integrity,
3892 validating the hashes and checksums of each entry in the changelog,
3893 manifest, and tracked files, as well as the integrity of their
3894 crosslinks and indices.
3895 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
3897 information about recovery from corruption of the repository.
3898 Returns 0 on success, 1 if errors are encountered.
3900 Options:
3902 --full perform more checks (EXPERIMENTAL)
3904 Help
3906 config
3907 show combined config settings from all hgrc files:
3908 hg config [-u] [NAME]...
3910 With no arguments, print names and values of all config items.
3912 With one argument of the form section.name, print just the value of
3914 that config item.
3915 With multiple arguments, print names and values of all config items
3917 with matching section names or section.names.
3918 With --edit, start an editor on the user-level config file. With
3920 --global, edit the system-wide config file. With --local, edit the
3921 repository-level config file.
3922 With --debug, the source (filename and line number) is printed for each
3924 config item.
3925 See hg help config for more information about config files.
3927 Template:
3929 The following keywords are supported. See also hg help templates.
3931 name String. Config name.
3933 source String. Filename and line number where the item is defined.
3935 value String. Config value.
3937 Returns 0 on success, 1 if NAME does not exist.
3939 Options:
3941 -u, --untrusted
3943 show untrusted configuration options
3944 -e, --edit
3946 edit user config
3947 -l, --local
3949 edit repository config
3950 -g, --global
3952 edit global config
3953 -T,--template <TEMPLATE>
3955 display with template
3956 aliases: showconfig debugconfig
3958 help
3960 show help for a given topic or a help overview:
3961 hg help [-eck] [-s PLATFORM] [TOPIC]
3963 With no arguments, print a list of commands with short help messages.
3965 Given a topic, extension, or command name, print help for that topic.
3967 Returns 0 if successful.
3969 Options:
3971 -e, --extension
3973 show only help for extensions
3974 -c, --command
3976 show only help for commands
3977 -k, --keyword
3979 show topics matching keyword
3980 -s,--system <PLATFORM[+]>
3982 show help for specific platform(s)
3983 [+] marked option can be specified multiple times
3985 version
3987 output version and copyright information:
3988 hg version
3990 Template:
3992 The following keywords are supported. See also hg help templates.
3994 extensions
3996 List of extensions.
3997 ver String. Version number.
3999 And each entry of {extensions} provides the following sub-keywords in
4001 addition to {ver}.
4002 bundled
4004 Boolean. True if included in the release.
4005 name String. Extension name.
4007 Options:
4009 -T,--template <TEMPLATE>
4011 display with template
4012 Uncategorized commands
4015 Mercurial supports generating standalone "bundle" files that hold
4016 repository data. These "bundles" are typically saved locally and used
4017 later or exchanged between different repositories, possibly on differ‐
4018 ent machines. Example commands using bundles are hg bundle and hg
4019 unbundle.
4020 Generation of bundle files is controlled by a "bundle specification"
4022 ("bundlespec") string. This string tells the bundle generation process
4023 how to create the bundle.
4024 A "bundlespec" string is composed of the following elements:
4026 type A string denoting the bundle format to use.
4028 compression
4030 Denotes the compression engine to use compressing the raw bundle
4031 data.
4032 parameters
4034 Arbitrary key-value parameters to further control bundle genera‐
4035 tion.
4036 A "bundlespec" string has the following formats:
4038 <type> The literal bundle format string is used.
4040 <compression>-<type>
4042 The compression engine and format are delimited by a hyphen (-).
4043 Optional parameters follow the <type>. Parameters are URI escaped
4045 key=value pairs. Each pair is delimited by a semicolon (;). The first
4046 parameter begins after a ; immediately following the <type> value.
4047 Available Types
4049 The following bundle <type> strings are available:
4050 v1 Produces a legacy "changegroup" version 1 bundle.
4052 This format is compatible with nearly all Mercurial clients
4054 because it is the oldest. However, it has some limitations,
4055 which is why it is no longer the default for new repositories.
4056 v1 bundles can be used with modern repositories using the "gen‐
4058 eraldelta" storage format. However, it may take longer to pro‐
4059 duce the bundle and the resulting bundle may be significantly
4060 larger than a v2 bundle.
4061 v1 bundles can only use the gzip, bzip2, and none compression
4063 formats.
4064 v2 Produces a version 2 bundle.
4066 Version 2 bundles are an extensible format that can store addi‐
4068 tional repository data (such as bookmarks and phases informa‐
4069 tion) and they can store data more efficiently, resulting in
4070 smaller bundles.
4071 Version 2 bundles can also use modern compression engines, such
4073 as zstd, making them faster to compress and often smaller.
4074 Available Compression Engines
4076 The following bundle <compression> engines can be used:
4077 bzip2
4079 An algorithm that produces smaller bundles than gzip.
4081 All Mercurial clients should support this format.
4083 This engine will likely produce smaller bundles than gzip but
4085 will be significantly slower, both during compression and decom‐
4086 pression.
4087 If available, the zstd engine can yield similar or better com‐
4089 pression at much higher speeds.
4090 gzip
4092 zlib compression using the DEFLATE algorithm.
4094 All Mercurial clients should support this format. The compres‐
4096 sion algorithm strikes a reasonable balance between compression
4097 ratio and size.
4098 none
4100 No compression is performed.
4102 Use this compression engine to explicitly disable compression.
4104 Examples
4106 v2
4107 Produce a v2 bundle using default options, including compres‐
4109 sion.
4110 none-v1
4112 Produce a v1 bundle with no compression.
4114 zstd-v2
4116 Produce a v2 bundle with zstandard compression using default
4118 settings.
4119 zstd-v1
4121 This errors because zstd is not supported for v1 types.
4123
4125 Mercurial colorizes output from several commands.
4126 For example, the diff command shows additions in green and deletions in
4128 red, while the status command shows modified files in magenta. Many
4129 other commands have analogous colors. It is possible to customize these
4130 colors.
4131 To enable color (default) whenever possible use:
4133 [ui]
4135 color = yes
4136 To disable color use:
4138 [ui]
4140 color = no
4141 See hg help config.ui.color for details.
4143 The default pager on Windows does not support color, so enabling the
4145 pager will effectively disable color. See hg help config.ui.paginate
4146 to disable the pager. Alternately, MSYS and Cygwin shells provide less
4147 as a pager, which can be configured to support ANSI color mode. Win‐
4148 dows 10 natively supports ANSI color mode.
4149 Mode
4151 Mercurial can use various systems to display color. The supported modes
4152 are ansi, win32, and terminfo. See hg help config.color for details
4153 about how to control the mode.
4154 Effects
4156 Other effects in addition to color, like bold and underlined text, are
4157 also available. By default, the terminfo database is used to find the
4158 terminal codes used to change color and effect. If terminfo is not
4159 available, then effects are rendered with the ECMA-48 SGR control func‐
4160 tion (aka ANSI escape codes).
4161 The available effects in terminfo mode are 'blink', 'bold', 'dim',
4163 'inverse', 'invisible', 'italic', 'standout', and 'underline'; in
4164 ECMA-48 mode, the options are 'bold', 'inverse', 'italic', and 'under‐
4165 line'. How each is rendered depends on the terminal emulator. Some
4166 may not be available for a given terminal type, and will be silently
4167 ignored.
4168 If the terminfo entry for your terminal is missing codes for an effect
4170 or has the wrong codes, you can add or override those codes in your
4171 configuration:
4172 [color]
4174 terminfo.dim = \E[2m
4175 where 'E' is substituted with an escape character.
4177 Labels
4179 Text receives color effects depending on the labels that it has. Many
4180 default Mercurial commands emit labelled text. You can also define your
4181 own labels in templates using the label function, see hg help templates
4182 . A single portion of text may have more than one label. In that case,
4183 effects given to the last label will override any other effects. This
4184 includes the special "none" effect, which nullifies other effects.
4185 Labels are normally invisible. In order to see these labels and their
4187 position in the text, use the global --color=debug option. The same
4188 anchor text may be associated to multiple labels, e.g.
4189 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
4191 The following are the default effects for some default labels. Default
4193 effects may be overridden from your configuration file:
4194 [color]
4196 status.modified = blue bold underline red_background
4197 status.added = green bold
4198 status.removed = red bold blue_background
4199 status.deleted = cyan bold underline
4200 status.unknown = magenta bold underline
4201 status.ignored = black bold
4202 # 'none' turns off all effects
4204 status.clean = none
4205 status.copied = none
4206 qseries.applied = blue bold underline
4208 qseries.unapplied = black bold
4209 qseries.missing = red bold
4210 diff.diffline = bold
4212 diff.extended = cyan bold
4213 diff.file_a = red bold
4214 diff.file_b = green bold
4215 diff.hunk = magenta
4216 diff.deleted = red
4217 diff.inserted = green
4218 diff.changed = white
4219 diff.tab =
4220 diff.trailingwhitespace = bold red_background
4221 # Blank so it inherits the style of the surrounding label
4223 changeset.public =
4224 changeset.draft =
4225 changeset.secret =
4226 resolve.unresolved = red bold
4228 resolve.resolved = green bold
4229 bookmarks.active = green
4231 branches.active = none
4233 branches.closed = black bold
4234 branches.current = green
4235 branches.inactive = none
4236 tags.normal = green
4238 tags.local = black bold
4239 rebase.rebased = blue
4241 rebase.remaining = red bold
4242 shelve.age = cyan
4244 shelve.newest = green bold
4245 shelve.name = blue bold
4246 histedit.remaining = red bold
4248 Custom colors
4250 Because there are only eight standard colors, Mercurial allows you to
4251 define color names for other color slots which might be available for
4252 your terminal type, assuming terminfo mode. For instance:
4253 color.brightblue = 12
4255 color.pink = 207
4256 color.orange = 202
4257 to set 'brightblue' to color slot 12 (useful for 16 color terminals
4259 that have brighter colors defined in the upper eight) and, 'pink' and
4260 'orange' to colors in 256-color xterm's default color cube. These
4261 defined colors may then be used as any of the pre-defined eight,
4262 including appending '_background' to set the background to that color.
4263
4265 Some commands allow the user to specify a date, e.g.:
4266 · backout, commit, import, tag: Specify the commit date.
4268 · log, revert, update: Select revision(s) by date.
4270 Many date formats are valid. Here are some examples:
4272 · Wed Dec 6 13:18:29 2006 (local timezone assumed)
4274 · Dec 6 13:18 -0600 (year assumed, time offset provided)
4276 · Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
4278 · Dec 6 (midnight)
4280 · 13:18 (today assumed)
4282 · 3:39 (3:39AM assumed)
4284 · 3:39pm (15:39)
4286 · 2006-12-06 13:18:29 (ISO 8601 format)
4288 · 2006-12-6 13:18
4290 · 2006-12-6
4292 · 12-6
4294 · 12/6
4296 · 12/6/6 (Dec 6 2006)
4298 · today (midnight)
4300 · yesterday (midnight)
4302 · now - right now
4304 Lastly, there is Mercurial's internal format:
4306 · 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
4308 This is the internal representation format for dates. The first number
4310 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
4311 second is the offset of the local timezone, in seconds west of UTC
4312 (negative if the timezone is east of UTC).
4313 The log command also accepts date ranges:
4315 · <DATE - at or before a given date/time
4317 · >DATE - on or after a given date/time
4319 · DATE to DATE - a date range, inclusive
4321 · -DAYS - within a given number of days of today
4323
4325 Mercurial evolves over time, some features, options, commands may be
4326 replaced by better and more secure alternatives. This topic will help
4327 you migrating your existing usage and/or configuration to newer fea‐
4328 tures.
4329 Commands
4331 The following commands are still available but their use are not recom‐
4332 mended:
4333 locate
4335 This command has been replaced by hg files.
4337 parents
4339 This command can be replaced by hg summary or hg log with appropriate
4341 revsets. See hg help revsets for more information.
4342 tip
4344 The recommended alternative is hg heads.
4346 Options
4348 web.allowpull
4349 Renamed to allow-pull.
4351 web.allow_push
4353 Renamed to allow-push.
4355
4357 Mercurial's default format for showing changes between two versions of
4358 a file is compatible with the unified format of GNU diff, which can be
4359 used by GNU patch and many other standard tools.
4360 While this standard format is often enough, it does not encode the fol‐
4362 lowing information:
4363 · executable status and other permission bits
4365 · copy or rename information
4367 · changes in binary files
4369 · creation or deletion of empty files
4371 Mercurial also supports the extended diff format from the git VCS which
4373 addresses these limitations. The git diff format is not produced by
4374 default because a few widespread tools still do not understand this
4375 format.
4376 This means that when generating diffs from a Mercurial repository (e.g.
4378 with hg export), you should be careful about things like file copies
4379 and renames or other things mentioned above, because when applying a
4380 standard diff to a different repository, this extra information is
4381 lost. Mercurial's internal operations (like push and pull) are not
4382 affected by this, because they use an internal binary format for commu‐
4383 nicating changes.
4384 To make Mercurial produce the git extended diff format, use the --git
4386 option available for many commands, or set 'git = True' in the [diff]
4387 section of your configuration file. You do not need to set this option
4388 when importing diffs in this format or using them in the mq extension.
4389
4391 HG Path to the 'hg' executable, automatically passed when running
4392 hooks, extensions or external tools. If unset or empty, this is
4393 the hg executable's name if it's frozen, or an executable named
4394 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
4395 on Windows) is searched.
4396 HGEDITOR
4398 This is the name of the editor to run when committing. See EDI‐
4399 TOR.
4400 (deprecated, see hg help config.ui.editor)
4402 HGENCODING
4404 This overrides the default locale setting detected by Mercurial.
4405 This setting is used to convert data including usernames,
4406 changeset descriptions, tag names, and branches. This setting
4407 can be overridden with the --encoding command-line option.
4408 HGENCODINGMODE
4410 This sets Mercurial's behavior for handling unknown characters
4411 while transcoding user input. The default is "strict", which
4412 causes Mercurial to abort if it can't map a character. Other
4413 settings include "replace", which replaces unknown characters,
4414 and "ignore", which drops them. This setting can be overridden
4415 with the --encodingmode command-line option.
4416 HGENCODINGAMBIGUOUS
4418 This sets Mercurial's behavior for handling characters with
4419 "ambiguous" widths like accented Latin characters with East
4420 Asian fonts. By default, Mercurial assumes ambiguous characters
4421 are narrow, set this variable to "wide" if such characters cause
4422 formatting problems.
4423 HGMERGE
4425 An executable to use for resolving merge conflicts. The program
4426 will be executed with three arguments: local file, remote file,
4427 ancestor file.
4428 (deprecated, see hg help config.ui.merge)
4430 HGRCPATH
4432 A list of files or directories to search for configuration
4433 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
4434 PATH is not set, platform default search path is used. If empty,
4435 only the .hg/hgrc from the current repository is read.
4436 For each element in HGRCPATH:
4438 · if it's a directory, all files ending with .rc are added
4440 · otherwise, the file itself will be added
4442 HGPLAIN
4444 When set, this disables any configuration settings that might
4445 change Mercurial's default output. This includes encoding,
4446 defaults, verbose mode, debug mode, quiet mode, tracebacks, and
4447 localization. This can be useful when scripting against Mercu‐
4448 rial in the face of existing user configuration.
4449 In addition to the features disabled by HGPLAIN=, the following
4451 values can be specified to adjust behavior:
4452 +strictflags
4454 Restrict parsing of command line flags.
4456 Equivalent options set via command line flags or environment
4458 variables are not overridden.
4459 See hg help scripting for details.
4461 HGPLAINEXCEPT
4463 This is a comma-separated list of features to preserve when
4464 HGPLAIN is enabled. Currently the following values are sup‐
4465 ported:
4466 alias
4468 Don't remove aliases.
4470 color
4472 Don't disable colored output.
4474 i18n
4476 Preserve internationalization.
4478 revsetalias
4480 Don't remove revset aliases.
4482 templatealias
4484 Don't remove template aliases.
4486 progress
4488 Don't hide progress output.
4490 Setting HGPLAINEXCEPT to anything (even an empty string) will
4492 enable plain mode.
4493 HGUSER This is the string used as the author of a commit. If not set,
4495 available values will be considered in this order:
4496 · HGUSER (deprecated)
4498 · configuration files from the HGRCPATH
4500 · EMAIL
4502 · interactive prompt
4504 · LOGNAME (with @hostname appended)
4506 (deprecated, see hg help config.ui.username)
4508 EMAIL May be used as the author of a commit; see HGUSER.
4510 LOGNAME
4512 May be used as the author of a commit; see HGUSER.
4513 VISUAL This is the name of the editor to use when committing. See EDI‐
4515 TOR.
4516 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
4518 user to modify, for example when writing commit messages. The
4519 editor it uses is determined by looking at the environment vari‐
4520 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
4521 non-empty one is chosen. If all of them are empty, the editor
4522 defaults to 'vi'.
4523 PYTHONPATH
4525 This is used by Python to find imported modules and may need to
4526 be set appropriately if this Mercurial is not installed sys‐
4527 tem-wide.
4528
4530 Mercurial has the ability to add new features through the use of exten‐
4531 sions. Extensions may add new commands, add options to existing com‐
4532 mands, change the default behavior of commands, or implement hooks.
4533 To enable the "foo" extension, either shipped with Mercurial or in the
4535 Python search path, create an entry for it in your configuration file,
4536 like this:
4537 [extensions]
4539 foo =
4540 You may also specify the full path to an extension:
4542 [extensions]
4544 myfeature = ~/.hgext/myfeature.py
4545 See hg help config for more information on configuration files.
4547 Extensions are not loaded by default for a variety of reasons: they can
4549 increase startup overhead; they may be meant for advanced usage only;
4550 they may provide potentially dangerous abilities (such as letting you
4551 destroy or modify history); they might not be ready for prime time; or
4552 they may alter some usual behaviors of stock Mercurial. It is thus up
4553 to the user to activate extensions as needed.
4554 To explicitly disable an extension enabled in a configuration file of
4556 broader scope, prepend its path with !:
4557 [extensions]
4559 # disabling extension bar residing in /path/to/extension/bar.py
4560 bar = !/path/to/extension/bar.py
4561 # ditto, but no path was supplied for extension baz
4562 baz = !
4563 disabled extensions:
4565 acl hooks for controlling repository access
4567 blackbox
4569 log repository events to a blackbox for debugging
4570 bugzilla
4572 hooks for integrating with the Bugzilla bug tracker
4573 censor erase file content at a given revision
4575 churn command to display statistics about repository history
4577 clonebundles
4579 advertise pre-generated bundles to seed clones
4580 closehead
4582 close arbitrary heads without checking them out first
4583 convert
4585 import revisions from foreign VCS repositories into Mercurial
4586 eol automatically manage newlines in repository files
4588 extdiff
4590 command to allow external programs to compare revisions
4591 factotum
4593 http authentication with factotum
4594 githelp
4596 try mapping git commands to Mercurial commands
4597 gpg commands to sign and verify changesets
4599 hgk browse the repository in a graphical way
4601 highlight
4603 syntax highlighting for hgweb (requires Pygments)
4604 histedit
4606 interactive history editing
4607 keyword
4609 expand keywords in tracked files
4610 largefiles
4612 track large binary files
4613 mq manage a stack of patches
4615 notify hooks for sending email push notifications
4617 patchbomb
4619 command to send changesets as (a series of) patch emails
4620 purge command to delete untracked files from the working directory
4622 rebase command to move sets of revisions to a different ancestor
4624 relink recreates hardlinks between repository clones
4626 schemes
4628 extend schemes with shortcuts to repository swarms
4629 share share a common history between several working directories
4631 strip strip changesets and their descendants from history
4633 transplant
4635 command to transplant changesets from another branch
4636 win32mbcs
4638 allow the use of MBCS paths with problematic encodings
4639 zeroconf
4641 discover and advertise repositories on the local network
4642
4644 Mercurial supports a functional language for selecting a set of files.
4645 Like other file patterns, this pattern type is indicated by a prefix,
4647 'set:'. The language supports a number of predicates which are joined
4648 by infix operators. Parenthesis can be used for grouping.
4649 Identifiers such as filenames or patterns must be quoted with single or
4651 double quotes if they contain characters outside of
4652 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4653 predicates. This generally applies to file patterns other than globs
4654 and arguments for predicates. Pattern prefixes such as path: may be
4655 specified without quoting.
4656 Special characters can be used in quoted identifiers by escaping them,
4658 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4659 preted, strings can be prefixed with r, e.g. r'...'.
4660 See also hg help patterns.
4662 Operators
4664 There is a single prefix operator:
4665 not x
4667 Files not in x. Short form is ! x.
4669 These are the supported infix operators:
4671 x and y
4673 The intersection of files in x and y. Short form is x & y.
4675 x or y
4677 The union of files in x and y. There are two alternative short
4679 forms: x | y and x + y.
4680 x - y
4682 Files in x but not in y.
4684 Predicates
4686 The following predicates are supported:
4687 added()
4689 File that is added according to hg status.
4691 binary()
4693 File that appears to be binary (contains NUL bytes).
4695 clean()
4697 File that is clean according to hg status.
4699 copied()
4701 File that is recorded as being copied.
4703 deleted()
4705 Alias for missing().
4707 encoding(name)
4709 File can be successfully decoded with the given character encod‐
4711 ing. May not be useful for encodings other than ASCII and UTF-8.
4712 eol(style)
4714 File contains newlines of the given style (dos, unix, mac).
4716 Binary files are excluded, files with mixed line endings match
4717 multiple styles.
4718 exec()
4720 File that is marked as executable.
4722 grep(regex)
4724 File contains the given regular expression.
4726 hgignore()
4728 File that matches the active .hgignore pattern.
4730 ignored()
4732 File that is ignored according to hg status.
4734 missing()
4736 File that is missing according to hg status.
4738 modified()
4740 File that is modified according to hg status.
4742 portable()
4744 File that has a portable name. (This doesn't include filenames
4746 with case collisions.)
4747 removed()
4749 File that is removed according to hg status.
4751 resolved()
4753 File that is marked resolved according to hg resolve -l.
4755 revs(revs, pattern)
4757 Evaluate set in the specified revisions. If the revset match
4759 multiple revs, this will return file matching pattern in any of
4760 the revision.
4761 size(expression)
4763 File size matches the given expression. Examples:
4765 · size('1k') - files from 1024 to 2047 bytes
4767 · size('< 20k') - files less than 20480 bytes
4769 · size('>= .5MB') - files at least 524288 bytes
4771 · size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
4773 status(base, rev, pattern)
4775 Evaluate predicate using status change between base and rev.
4777 Examples:
4778 · status(3, 7, added()) - matches files added from "3" to "7"
4780 subrepo([pattern])
4782 Subrepositories whose paths match the given pattern.
4784 symlink()
4786 File that is marked as a symlink.
4788 tracked()
4790 File that is under Mercurial control.
4792 unknown()
4794 File that is unknown according to hg status.
4796 unresolved()
4798 File that is marked unresolved according to hg resolve -l.
4800 Examples
4802 Some sample queries:
4803 · Show status of files that appear to be binary in the working direc‐
4805 tory:
4806 hg status -A "set:binary()"
4808 · Forget files that are in .hgignore but are already tracked:
4810 hg forget "set:hgignore() and not ignored()"
4812 · Find text files that contain a string:
4814 hg files "set:grep(magic) and not binary()"
4816 · Find C files in a non-standard encoding:
4818 hg files "set:**.c and not encoding('UTF-8')"
4820 · Revert copies of large binary files:
4822 hg revert "set:copied() and binary() and size('>1M')"
4824 · Revert files that were added to the working directory:
4826 hg revert "set:revs('wdir()', added())"
4828 · Remove files listed in foo.lst that contain the letter a or b:
4830 hg remove "set: listfile:foo.lst and (**a* or **b*)"
4832
4834 Most Mercurial commands accept various flags.
4835 Flag names
4837 Flags for each command are listed in hg help for that command. Addi‐
4838 tionally, some flags, such as --repository, are global and can be used
4839 with any command - those are seen in hg help -v, and can be specified
4840 before or after the command.
4841 Every flag has at least a long name, such as --repository. Some flags
4843 may also have a short one-letter name, such as the equivalent -R. Using
4844 the short or long name is equivalent and has the same effect.
4845 Flags that have a short name can also be bundled together - for
4847 instance, to specify both --edit (short -e) and --interactive (short
4848 -i), one could use:
4849 hg commit -ei
4851 If any of the bundled flags takes a value (i.e. is not a boolean), it
4853 must be last, followed by the value:
4854 hg commit -im 'Message'
4856 Flag types
4858 Mercurial command-line flags can be strings, numbers, booleans, or
4859 lists of strings.
4860 Specifying flag values
4862 The following syntaxes are allowed, assuming a flag 'flagname' with
4863 short name 'f':
4864 --flagname=foo
4866 --flagname foo
4867 -f foo
4868 -ffoo
4869 This syntax applies to all non-boolean flags (strings, numbers or
4871 lists).
4872 Specifying boolean flags
4874 Boolean flags do not take a value parameter. To specify a boolean, use
4875 the flag name to set it to true, or the same name prefixed with 'no-'
4876 to set it to false:
4877 hg commit --interactive
4879 hg commit --no-interactive
4880 Specifying list flags
4882 List flags take multiple values. To specify them, pass the flag multi‐
4883 ple times:
4884 hg files --include mercurial --include tests
4886 Setting flag defaults
4888 In order to set a default value for a flag in an hgrc file, it is rec‐
4889 ommended to use aliases:
4890 [alias]
4892 commit = commit --interactive
4893 For more information on hgrc files, see hg help config.
4895 Overriding flags on the command line
4897 If the same non-list flag is specified multiple times on the command
4898 line, the latest specification is used:
4899 hg commit -m "Ignored value" -m "Used value"
4901 This includes the use of aliases - e.g., if one has:
4903 [alias]
4905 committemp = commit -m "Ignored value"
4906 then the following command will override that -m:
4908 hg committemp -m "Used value"
4910 Overriding flag defaults
4912 Every flag has a default value, and you may also set your own defaults
4913 in hgrc as described above. Except for list flags, defaults can be
4914 overridden on the command line simply by specifying the flag in that
4915 location.
4916 Hidden flags
4918 Some flags are not shown in a command's help by default - specifically,
4919 those that are deemed to be experimental, deprecated or advanced. To
4920 show all flags, add the --verbose flag for the help command:
4921 hg help --verbose commit
4923
4925 Ancestor
4926 Any changeset that can be reached by an unbroken chain of parent
4927 changesets from a given changeset. More precisely, the ancestors
4928 of a changeset can be defined by two properties: a parent of a
4929 changeset is an ancestor, and a parent of an ancestor is an
4930 ancestor. See also: 'Descendant'.
4931 Bookmark
4933 Bookmarks are pointers to certain commits that move when commit‐
4934 ting. They are similar to tags in that it is possible to use
4935 bookmark names in all places where Mercurial expects a changeset
4936 ID, e.g., with hg update. Unlike tags, bookmarks move along when
4937 you make a commit.
4938 Bookmarks can be renamed, copied and deleted. Bookmarks are
4940 local, unless they are explicitly pushed or pulled between
4941 repositories. Pushing and pulling bookmarks allow you to col‐
4942 laborate with others on a branch without creating a named
4943 branch.
4944 Branch (Noun) A child changeset that has been created from a parent
4946 that is not a head. These are known as topological branches, see
4947 'Branch, topological'. If a topological branch is named, it
4948 becomes a named branch. If a topological branch is not named, it
4949 becomes an anonymous branch. See 'Branch, anonymous' and
4950 'Branch, named'.
4951 Branches may be created when changes are pulled from or pushed
4953 to a remote repository, since new heads may be created by these
4954 operations. Note that the term branch can also be used infor‐
4955 mally to describe a development process in which certain devel‐
4956 opment is done independently of other development. This is some‐
4957 times done explicitly with a named branch, but it can also be
4958 done locally, using bookmarks or clones and anonymous branches.
4959 Example: "The experimental branch."
4961 (Verb) The action of creating a child changeset which results in
4963 its parent having more than one child.
4964 Example: "I'm going to branch at X."
4966 Branch, anonymous
4968 Every time a new child changeset is created from a parent that
4969 is not a head and the name of the branch is not changed, a new
4970 anonymous branch is created.
4971 Branch, closed
4973 A named branch whose branch heads have all been closed.
4974 Branch, default
4976 The branch assigned to a changeset when no name has previously
4977 been assigned.
4978 Branch head
4980 See 'Head, branch'.
4981 Branch, inactive
4983 If a named branch has no topological heads, it is considered to
4984 be inactive. As an example, a feature branch becomes inactive
4985 when it is merged into the default branch. The hg branches com‐
4986 mand shows inactive branches by default, though they can be hid‐
4987 den with hg branches --active.
4988 NOTE: this concept is deprecated because it is too implicit.
4990 Branches should now be explicitly closed using hg commit
4991 --close-branch when they are no longer needed.
4992 Branch, named
4994 A collection of changesets which have the same branch name. By
4995 default, children of a changeset in a named branch belong to the
4996 same named branch. A child can be explicitly assigned to a dif‐
4997 ferent branch. See hg help branch, hg help branches and hg com‐
4998 mit --close-branch for more information on managing branches.
4999 Named branches can be thought of as a kind of namespace, divid‐
5001 ing the collection of changesets that comprise the repository
5002 into a collection of disjoint subsets. A named branch is not
5003 necessarily a topological branch. If a new named branch is cre‐
5004 ated from the head of another named branch, or the default
5005 branch, but no further changesets are added to that previous
5006 branch, then that previous branch will be a branch in name only.
5007 Branch tip
5009 See 'Tip, branch'.
5010 Branch, topological
5012 Every time a new child changeset is created from a parent that
5013 is not a head, a new topological branch is created. If a topo‐
5014 logical branch is named, it becomes a named branch. If a topo‐
5015 logical branch is not named, it becomes an anonymous branch of
5016 the current, possibly default, branch.
5017 Changelog
5019 A record of the changesets in the order in which they were added
5020 to the repository. This includes details such as changeset id,
5021 author, commit message, date, and list of changed files.
5022 Changeset
5024 A snapshot of the state of the repository used to record a
5025 change.
5026 Changeset, child
5028 The converse of parent changeset: if P is a parent of C, then C
5029 is a child of P. There is no limit to the number of children
5030 that a changeset may have.
5031 Changeset id
5033 A SHA-1 hash that uniquely identifies a changeset. It may be
5034 represented as either a "long" 40 hexadecimal digit string, or a
5035 "short" 12 hexadecimal digit string.
5036 Changeset, merge
5038 A changeset with two parents. This occurs when a merge is com‐
5039 mitted.
5040 Changeset, parent
5042 A revision upon which a child changeset is based. Specifically,
5043 a parent changeset of a changeset C is a changeset whose node
5044 immediately precedes C in the DAG. Changesets have at most two
5045 parents.
5046 Checkout
5048 (Noun) The working directory being updated to a specific revi‐
5049 sion. This use should probably be avoided where possible, as
5050 changeset is much more appropriate than checkout in this con‐
5051 text.
5052 Example: "I'm using checkout X."
5054 (Verb) Updating the working directory to a specific changeset.
5056 See hg help update.
5057 Example: "I'm going to check out changeset X."
5059 Child changeset
5061 See 'Changeset, child'.
5062 Close changeset
5064 See 'Head, closed branch'.
5065 Closed branch
5067 See 'Branch, closed'.
5068 Clone (Noun) An entire or partial copy of a repository. The partial
5070 clone must be in the form of a revision and its ancestors.
5071 Example: "Is your clone up to date?"
5073 (Verb) The process of creating a clone, using hg clone.
5075 Example: "I'm going to clone the repository."
5077 Closed branch head
5079 See 'Head, closed branch'.
5080 Commit (Noun) A synonym for changeset.
5082 Example: "Is the bug fixed in your recent commit?"
5084 (Verb) The act of recording changes to a repository. When files
5086 are committed in a working directory, Mercurial finds the dif‐
5087 ferences between the committed files and their parent changeset,
5088 creating a new changeset in the repository.
5089 Example: "You should commit those changes now."
5091 Cset A common abbreviation of the term changeset.
5093 DAG The repository of changesets of a distributed version control
5095 system (DVCS) can be described as a directed acyclic graph
5096 (DAG), consisting of nodes and edges, where nodes correspond to
5097 changesets and edges imply a parent -> child relation. This
5098 graph can be visualized by graphical tools such as hg log
5099 --graph. In Mercurial, the DAG is limited by the requirement for
5100 children to have at most two parents.
5101 Deprecated
5103 Feature removed from documentation, but not scheduled for
5104 removal.
5105 Default branch
5107 See 'Branch, default'.
5108 Descendant
5110 Any changeset that can be reached by a chain of child changesets
5111 from a given changeset. More precisely, the descendants of a
5112 changeset can be defined by two properties: the child of a
5113 changeset is a descendant, and the child of a descendant is a
5114 descendant. See also: 'Ancestor'.
5115 Diff (Noun) The difference between the contents and attributes of
5117 files in two changesets or a changeset and the current working
5118 directory. The difference is usually represented in a standard
5119 form called a "diff" or "patch". The "git diff" format is used
5120 when the changes include copies, renames, or changes to file
5121 attributes, none of which can be represented/handled by classic
5122 "diff" and "patch".
5123 Example: "Did you see my correction in the diff?"
5125 (Verb) Diffing two changesets is the action of creating a diff
5127 or patch.
5128 Example: "If you diff with changeset X, you will see what I
5130 mean."
5131 Directory, working
5133 The working directory represents the state of the files tracked
5134 by Mercurial, that will be recorded in the next commit. The
5135 working directory initially corresponds to the snapshot at an
5136 existing changeset, known as the parent of the working direc‐
5137 tory. See 'Parent, working directory'. The state may be modified
5138 by changes to the files introduced manually or by a merge. The
5139 repository metadata exists in the .hg directory inside the work‐
5140 ing directory.
5141 Draft Changesets in the draft phase have not been shared with publish‐
5143 ing repositories and may thus be safely changed by history-modi‐
5144 fying extensions. See hg help phases.
5145 Experimental
5147 Feature that may change or be removed at a later date.
5148 Graph See DAG and hg log --graph.
5150 Head The term 'head' may be used to refer to both a branch head or a
5152 repository head, depending on the context. See 'Head, branch'
5153 and 'Head, repository' for specific definitions.
5154 Heads are where development generally takes place and are the
5156 usual targets for update and merge operations.
5157 Head, branch
5159 A changeset with no descendants on the same named branch.
5160 Head, closed branch
5162 A changeset that marks a head as no longer interesting. The
5163 closed head is no longer listed by hg heads. A branch is consid‐
5164 ered closed when all its heads are closed and consequently is
5165 not listed by hg branches.
5166 Closed heads can be re-opened by committing new changeset as the
5168 child of the changeset that marks a head as closed.
5169 Head, repository
5171 A topological head which has not been closed.
5172 Head, topological
5174 A changeset with no children in the repository.
5175 History, immutable
5177 Once committed, changesets cannot be altered. Extensions which
5178 appear to change history actually create new changesets that
5179 replace existing ones, and then destroy the old changesets.
5180 Doing so in public repositories can result in old changesets
5181 being reintroduced to the repository.
5182 History, rewriting
5184 The changesets in a repository are immutable. However, exten‐
5185 sions to Mercurial can be used to alter the repository, usually
5186 in such a way as to preserve changeset contents.
5187 Immutable history
5189 See 'History, immutable'.
5190 Merge changeset
5192 See 'Changeset, merge'.
5193 Manifest
5195 Each changeset has a manifest, which is the list of files that
5196 are tracked by the changeset.
5197 Merge Used to bring together divergent branches of work. When you
5199 update to a changeset and then merge another changeset, you
5200 bring the history of the latter changeset into your working
5201 directory. Once conflicts are resolved (and marked), this merge
5202 may be committed as a merge changeset, bringing two branches
5203 together in the DAG.
5204 Named branch
5206 See 'Branch, named'.
5207 Null changeset
5209 The empty changeset. It is the parent state of newly-initialized
5210 repositories and repositories with no checked out revision. It
5211 is thus the parent of root changesets and the effective ancestor
5212 when merging unrelated changesets. Can be specified by the alias
5213 'null' or by the changeset ID '000000000000'.
5214 Parent See 'Changeset, parent'.
5216 Parent changeset
5218 See 'Changeset, parent'.
5219 Parent, working directory
5221 The working directory parent reflects a virtual revision which
5222 is the child of the changeset (or two changesets with an uncom‐
5223 mitted merge) shown by hg parents. This is changed with hg
5224 update. Other commands to see the working directory parent are
5225 hg summary and hg id. Can be specified by the alias ".".
5226 Patch (Noun) The product of a diff operation.
5228 Example: "I've sent you my patch."
5230 (Verb) The process of using a patch file to transform one
5232 changeset into another.
5233 Example: "You will need to patch that revision."
5235 Phase A per-changeset state tracking how the changeset has been or
5237 should be shared. See hg help phases.
5238 Public Changesets in the public phase have been shared with publishing
5240 repositories and are therefore considered immutable. See hg help
5241 phases.
5242 Pull An operation in which changesets in a remote repository which
5244 are not in the local repository are brought into the local
5245 repository. Note that this operation without special arguments
5246 only updates the repository, it does not update the files in the
5247 working directory. See hg help pull.
5248 Push An operation in which changesets in a local repository which are
5250 not in a remote repository are sent to the remote repository.
5251 Note that this operation only adds changesets which have been
5252 committed locally to the remote repository. Uncommitted changes
5253 are not sent. See hg help push.
5254 Repository
5256 The metadata describing all recorded states of a collection of
5257 files. Each recorded state is represented by a changeset. A
5258 repository is usually (but not always) found in the .hg subdi‐
5259 rectory of a working directory. Any recorded state can be recre‐
5260 ated by "updating" a working directory to a specific changeset.
5261 Repository head
5263 See 'Head, repository'.
5264 Revision
5266 A state of the repository at some point in time. Earlier revi‐
5267 sions can be updated to by using hg update. See also 'Revision
5268 number'; See also 'Changeset'.
5269 Revision number
5271 This integer uniquely identifies a changeset in a specific
5272 repository. It represents the order in which changesets were
5273 added to a repository, starting with revision number 0. Note
5274 that the revision number may be different in each clone of a
5275 repository. To identify changesets uniquely between different
5276 clones, see 'Changeset id'.
5277 Revlog History storage mechanism used by Mercurial. It is a form of
5279 delta encoding, with occasional full revision of data followed
5280 by delta of each successive revision. It includes data and an
5281 index pointing to the data.
5282 Rewriting history
5284 See 'History, rewriting'.
5285 Root A changeset that has only the null changeset as its parent. Most
5287 repositories have only a single root changeset.
5288 Secret Changesets in the secret phase may not be shared via push, pull,
5290 or clone. See hg help phases.
5291 Tag An alternative name given to a changeset. Tags can be used in
5293 all places where Mercurial expects a changeset ID, e.g., with hg
5294 update. The creation of a tag is stored in the history and will
5295 thus automatically be shared with other using push and pull.
5296 Tip The changeset with the highest revision number. It is the
5298 changeset most recently added in a repository.
5299 Tip, branch
5301 The head of a given branch with the highest revision number.
5302 When a branch name is used as a revision identifier, it refers
5303 to the branch tip. See also 'Branch, head'. Note that because
5304 revision numbers may be different in different repository
5305 clones, the branch tip may be different in different cloned
5306 repositories.
5307 Update (Noun) Another synonym of changeset.
5309 Example: "I've pushed an update."
5311 (Verb) This term is usually used to describe updating the state
5313 of the working directory to that of a specific changeset. See hg
5314 help update.
5315 Example: "You should update."
5317 Working directory
5319 See 'Directory, working'.
5320 Working directory parent
5322 See 'Parent, working directory'.
5323
5325 Synopsis
5326 The Mercurial system uses a file called .hgignore in the root directory
5327 of a repository to control its behavior when it searches for files that
5328 it is not currently tracking.
5329 Description
5331 The working directory of a Mercurial repository will often contain
5332 files that should not be tracked by Mercurial. These include backup
5333 files created by editors and build products created by compilers.
5334 These files can be ignored by listing them in a .hgignore file in the
5335 root of the working directory. The .hgignore file must be created manu‐
5336 ally. It is typically put under version control, so that the settings
5337 will propagate to other repositories with push and pull.
5338 An untracked file is ignored if its path relative to the repository
5340 root directory, or any prefix path of that path, is matched against any
5341 pattern in .hgignore.
5342 For example, say we have an untracked file, file.c, at a/b/file.c
5344 inside our repository. Mercurial will ignore file.c if any pattern in
5345 .hgignore matches a/b/file.c, a/b or a.
5346 In addition, a Mercurial configuration file can reference a set of
5348 per-user or global ignore files. See the ignore configuration key on
5349 the [ui] section of hg help config for details of how to configure
5350 these files.
5351 To control Mercurial's handling of files that it manages, many commands
5353 support the -I and -X options; see hg help <command> and hg help pat‐
5354 terns for details.
5355 Files that are already tracked are not affected by .hgignore, even if
5357 they appear in .hgignore. An untracked file X can be explicitly added
5358 with hg add X, even if X would be excluded by a pattern in .hgignore.
5359 Syntax
5361 An ignore file is a plain text file consisting of a list of patterns,
5362 with one pattern per line. Empty lines are skipped. The # character is
5363 treated as a comment character, and the \ character is treated as an
5364 escape character.
5365 Mercurial supports several pattern syntaxes. The default syntax used is
5367 Python/Perl-style regular expressions.
5368 To change the syntax used, use a line of the following form:
5370 syntax: NAME
5372 where NAME is one of the following:
5374 regexp
5376 Regular expression, Python/Perl syntax.
5378 glob
5380 Shell-style glob.
5382 rootglob
5384 A variant of glob that is rooted (see below).
5386 The chosen syntax stays in effect when parsing all patterns that fol‐
5388 low, until another syntax is selected.
5389 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
5391 the form *.c will match a file ending in .c in any directory, and a
5392 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
5393 tern, start it with ^. To get the same effect with glob-syntax, you
5394 have to use rootglob.
5395 Subdirectories can have their own .hgignore settings by adding subin‐
5397 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
5398 terns for details on subinclude: and include:.
5399 Note Patterns specified in other than .hgignore are always rooted.
5401 Please see hg help patterns for details.
5402 Example
5404 Here is an example ignore file.
5405 # use glob syntax.
5407 syntax: glob
5408 *.elc
5410 *.pyc
5411 *~
5412 # switch to regexp syntax.
5414 syntax: regexp
5415 ^\.pc/
5416
5418 Mercurial's internal web server, hgweb, can serve either a single
5419 repository, or a tree of repositories. In the second case, repository
5420 paths and global options can be defined using a dedicated configuration
5421 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
5422 This file uses the same syntax as other Mercurial configuration files
5424 but recognizes only the following sections:
5425 · web
5427 · paths
5429 · collections
5431 The web options are thoroughly described in hg help config.
5433 The paths section maps URL paths to paths of repositories in the
5435 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
5436 rial repositories can be published and only according to the configura‐
5437 tion.
5438 The left hand side is the path in the URL. Note that hgweb reserves
5440 subpaths like rev or file, try using different names for nested reposi‐
5441 tories to avoid confusing effects.
5442 The right hand side is the path in the filesystem. If the specified
5444 path ends with * or ** the filesystem will be searched recursively for
5445 repositories below that point. With * it will not recurse into the
5446 repositories it finds (except for .hg/patches). With ** it will also
5447 search inside repository working directories and possibly find sub‐
5448 repositories.
5449 In this example:
5451 [paths]
5453 /projects/a = /srv/tmprepos/a
5454 /projects/b = c:/repos/b
5455 / = /srv/repos/*
5456 /user/bob = /home/bob/repos/**
5457 · The first two entries make two repositories in different directories
5459 appear under the same directory in the web interface
5460 · The third entry will publish every Mercurial repository found in
5462 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
5463 as http://server/quux/
5464 · The fourth entry will publish both http://server/user/bob/quux/ and
5466 http://server/user/bob/quux/testsubrepo/
5467 The collections section is deprecated and has been superseded by paths.
5469 URLs and Common Arguments
5471 URLs under each repository have the form /{command}[/{arguments}] where
5472 {command} represents the name of a command or handler and {arguments}
5473 represents any number of additional URL parameters to that command.
5474 The web server has a default style associated with it. Styles map to a
5476 collection of named templates. Each template is used to render a spe‐
5477 cific piece of data, such as a changeset or diff.
5478 The style for the current request can be overwritten two ways. First,
5480 if {command} contains a hyphen (-), the text before the hyphen defines
5481 the style. For example, /atom-log will render the log command handler
5482 with the atom style. The second way to set the style is with the style
5483 query string argument. For example, /log?style=atom. The hyphenated URL
5484 parameter is preferred.
5485 Not all templates are available for all styles. Attempting to use a
5487 style that doesn't have all templates defined may result in an error
5488 rendering the page.
5489 Many commands take a {revision} URL parameter. This defines the change‐
5491 set to operate on. This is commonly specified as the short, 12 digit
5492 hexadecimal abbreviation for the full 40 character unique revision
5493 identifier. However, any value described by hg help revisions typically
5494 works.
5495 Commands and URLs
5497 The following web commands and their URLs are available:
5498 /annotate/{revision}/{path}
5500 Show changeset information for each line in a file.
5501 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
5503 string arguments have the same meaning as their [annotate] config
5504 equivalents. It uses the hgrc boolean parsing logic to interpret the
5505 value. e.g. 0 and false are false and 1 and true are true. If not
5506 defined, the server default settings are used.
5507 The fileannotate template is rendered.
5509 /archive/{revision}.{format}[/{path}]
5511 Obtain an archive of repository content.
5512 The content and type of the archive is defined by a URL path parameter.
5514 format is the file extension of the archive type to be generated. e.g.
5515 zip or tar.bz2. Not all archive types may be allowed by your server
5516 configuration.
5517 The optional path URL parameter controls content to include in the ar‐
5519 chive. If omitted, every file in the specified revision is present in
5520 the archive. If included, only the specified file or contents of the
5521 specified directory will be included in the archive.
5522 No template is used for this handler. Raw, binary content is generated.
5524 /bookmarks
5526 Show information about bookmarks.
5527 No arguments are accepted.
5529 The bookmarks template is rendered.
5531 /branches
5533 Show information about branches.
5534 All known branches are contained in the output, even closed branches.
5536 No arguments are accepted.
5538 The branches template is rendered.
5540 /changelog[/{revision}]
5542 Show information about multiple changesets.
5543 If the optional revision URL argument is absent, information about all
5545 changesets starting at tip will be rendered. If the revision argument
5546 is present, changesets will be shown starting from the specified revi‐
5547 sion.
5548 If revision is absent, the rev query string argument may be defined.
5550 This will perform a search for changesets.
5551 The argument for rev can be a single revision, a revision set, or a
5553 literal keyword to search for in changeset data (equivalent to hg log
5554 -k).
5555 The revcount query string argument defines the maximum numbers of
5557 changesets to render.
5558 For non-searches, the changelog template will be rendered.
5560 /changeset[/{revision}]
5562 Show information about a single changeset.
5563 A URL path argument is the changeset identifier to show. See hg help
5565 revisions for possible values. If not defined, the tip changeset will
5566 be shown.
5567 The changeset template is rendered. Contents of the changesettag,
5569 changesetbookmark, filenodelink, filenolink, and the many templates
5570 related to diffs may all be used to produce the output.
5571 /comparison/{revision}/{path}
5573 Show a comparison between the old and new versions of a file from
5574 changes made on a particular revision.
5575 This is similar to the diff handler. However, this form features a
5577 split or side-by-side diff rather than a unified diff.
5578 The context query string argument can be used to control the lines of
5580 context in the diff.
5581 The filecomparison template is rendered.
5583 /diff/{revision}/{path}
5585 Show how a file changed in a particular commit.
5586 The filediff template is rendered.
5588 This handler is registered under both the /diff and /filediff paths.
5590 /diff is used in modern code.
5591 /file/{revision}[/{path}]
5593 Show information about a directory or file in the repository.
5594 Info about the path given as a URL parameter will be rendered.
5596 If path is a directory, information about the entries in that directory
5598 will be rendered. This form is equivalent to the manifest handler.
5599 If path is a file, information about that file will be shown via the
5601 filerevision template.
5602 If path is not defined, information about the root directory will be
5604 rendered.
5605 /diff/{revision}/{path}
5607 Show how a file changed in a particular commit.
5608 The filediff template is rendered.
5610 This handler is registered under both the /diff and /filediff paths.
5612 /diff is used in modern code.
5613 /filelog/{revision}/{path}
5615 Show information about the history of a file in the repository.
5616 The revcount query string argument can be defined to control the maxi‐
5618 mum number of entries to show.
5619 The filelog template will be rendered.
5621 /graph[/{revision}]
5623 Show information about the graphical topology of the repository.
5624 Information rendered by this handler can be used to create visual rep‐
5626 resentations of repository topology.
5627 The revision URL parameter controls the starting changeset. If it's
5629 absent, the default is tip.
5630 The revcount query string argument can define the number of changesets
5632 to show information for.
5633 The graphtop query string argument can specify the starting changeset
5635 for producing jsdata variable that is used for rendering graph in
5636 JavaScript. By default it has the same value as revision.
5637 This handler will render the graph template.
5639 /help[/{topic}]
5641 Render help documentation.
5642 This web command is roughly equivalent to hg help. If a topic is
5644 defined, that help topic will be rendered. If not, an index of avail‐
5645 able help topics will be rendered.
5646 The help template will be rendered when requesting help for a topic.
5648 helptopics will be rendered for the index of help topics.
5649 /log[/{revision}[/{path}]]
5651 Show repository or file history.
5652 For URLs of the form /log/{revision}, a list of changesets starting at
5654 the specified changeset identifier is shown. If {revision} is not
5655 defined, the default is tip. This form is equivalent to the changelog
5656 handler.
5657 For URLs of the form /log/{revision}/{file}, the history for a specific
5659 file will be shown. This form is equivalent to the filelog handler.
5660 /manifest[/{revision}[/{path}]]
5662 Show information about a directory.
5663 If the URL path arguments are omitted, information about the root
5665 directory for the tip changeset will be shown.
5666 Because this handler can only show information for directories, it is
5668 recommended to use the file handler instead, as it can handle both
5669 directories and files.
5670 The manifest template will be rendered for this handler.
5672 /changeset[/{revision}]
5674 Show information about a single changeset.
5675 A URL path argument is the changeset identifier to show. See hg help
5677 revisions for possible values. If not defined, the tip changeset will
5678 be shown.
5679 The changeset template is rendered. Contents of the changesettag,
5681 changesetbookmark, filenodelink, filenolink, and the many templates
5682 related to diffs may all be used to produce the output.
5683 /shortlog
5685 Show basic information about a set of changesets.
5686 This accepts the same parameters as the changelog handler. The only
5688 difference is the shortlog template will be rendered instead of the
5689 changelog template.
5690 /summary
5692 Show a summary of repository state.
5693 Information about the latest changesets, bookmarks, tags, and branches
5695 is captured by this handler.
5696 The summary template is rendered.
5698 /tags
5700 Show information about tags.
5701 No arguments are accepted.
5703 The tags template is rendered.
5705
5707 To access a subtopic, use "hg help internals.{subtopic-name}"
5708 bundle2
5710 Bundle2
5711 bundles
5713 Bundles
5714 cbor CBOR
5716 censor Censor
5718 changegroups
5720 Changegroups
5721 config Config Registrar
5723 extensions
5725 Extension API
5726 mergestate
5728 Mergestate
5729 requirements
5731 Repository Requirements
5732 revlogs
5734 Revision Logs
5735 wireprotocol
5737 Wire Protocol
5738 wireprotocolrpc
5740 Wire Protocol RPC
5741 wireprotocolv2
5743 Wire Protocol Version 2
5744
5746 To merge files Mercurial uses merge tools.
5747 A merge tool combines two different versions of a file into a merged
5749 file. Merge tools are given the two files and the greatest common
5750 ancestor of the two file versions, so they can determine the changes
5751 made on both branches.
5752 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
5754 out and in several extensions.
5755 Usually, the merge tool tries to automatically reconcile the files by
5757 combining all non-overlapping changes that occurred separately in the
5758 two different evolutions of the same initial base file. Furthermore,
5759 some interactive merge programs make it easier to manually resolve con‐
5760 flicting merges, either in a graphical way, or by inserting some con‐
5761 flict markers. Mercurial does not include any interactive merge pro‐
5762 grams but relies on external tools for that.
5763 Available merge tools
5765 External merge tools and their properties are configured in the
5766 merge-tools configuration section - see hgrc(5) - but they can often
5767 just be named by their executable.
5768 A merge tool is generally usable if its executable can be found on the
5770 system and if it can handle the merge. The executable is found if it is
5771 an absolute or relative executable path or the name of an application
5772 in the executable search path. The tool is assumed to be able to handle
5773 the merge if it can handle symlinks if the file is a symlink, if it can
5774 handle binary files if the file is binary, and if a GUI is available if
5775 the tool requires a GUI.
5776 There are some internal merge tools which can be used. The internal
5778 merge tools are:
5779 :dump
5781 Creates three versions of the files to merge, containing the
5783 contents of local, other and base. These files can then be used
5784 to perform a merge manually. If the file to be merged is named
5785 a.txt, these files will accordingly be named a.txt.local,
5786 a.txt.other and a.txt.base and they will be placed in the same
5787 directory as a.txt.
5788 This implies premerge. Therefore, files aren't dumped, if pre‐
5790 merge runs successfully. Use :forcedump to forcibly write files
5791 out.
5792 (actual capabilities: binary, symlink)
5794 :fail
5796 Rather than attempting to merge files that were modified on both
5798 branches, it marks them as unresolved. The resolve command must
5799 be used to resolve these conflicts.
5800 (actual capabilities: binary, symlink)
5802 :forcedump
5804 Creates three versions of the files as same as :dump, but omits
5806 premerge.
5807 (actual capabilities: binary, symlink)
5809 :local
5811 Uses the local p1() version of files as the merged version.
5813 (actual capabilities: binary, symlink)
5815 :merge
5817 Uses the internal non-interactive simple merge algorithm for
5819 merging files. It will fail if there are any conflicts and leave
5820 markers in the partially merged file. Markers will have two sec‐
5821 tions, one for each side of merge.
5822 :merge-local
5824 Like :merge, but resolve all conflicts non-interactively in
5826 favor of the local p1() changes.
5827 :merge-other
5829 Like :merge, but resolve all conflicts non-interactively in
5831 favor of the other p2() changes.
5832 :merge3
5834 Uses the internal non-interactive simple merge algorithm for
5836 merging files. It will fail if there are any conflicts and leave
5837 markers in the partially merged file. Marker will have three
5838 sections, one from each side of the merge and one for the base
5839 content.
5840 :other
5842 Uses the other p2() version of files as the merged version.
5844 (actual capabilities: binary, symlink)
5846 :prompt
5848 Asks the user which of the local p1() or the other p2() version
5850 to keep as the merged version.
5851 (actual capabilities: binary, symlink)
5853 :tagmerge
5855 Uses the internal tag merge algorithm (experimental).
5857 :union
5859 Uses the internal non-interactive simple merge algorithm for
5861 merging files. It will use both left and right sides for con‐
5862 flict regions. No markers are inserted.
5863 Internal tools are always available and do not require a GUI but will
5865 by default not handle symlinks or binary files. See next section for
5866 detail about "actual capabilities" described above.
5867 Choosing a merge tool
5869 Mercurial uses these rules when deciding which merge tool to use:
5870 1. If a tool has been specified with the --tool option to merge or
5872 resolve, it is used. If it is the name of a tool in the merge-tools
5873 configuration, its configuration is used. Otherwise the specified
5874 tool must be executable by the shell.
5875 2. If the HGMERGE environment variable is present, its value is used
5877 and must be executable by the shell.
5878 3. If the filename of the file to be merged matches any of the patterns
5880 in the merge-patterns configuration section, the first usable merge
5881 tool corresponding to a matching pattern is used.
5882 4. If ui.merge is set it will be considered next. If the value is not
5884 the name of a configured tool, the specified value is used and must
5885 be executable by the shell. Otherwise the named tool is used if it
5886 is usable.
5887 5. If any usable merge tools are present in the merge-tools configura‐
5889 tion section, the one with the highest priority is used.
5890 6. If a program named hgmerge can be found on the system, it is used -
5892 but it will by default not be used for symlinks and binary files.
5893 7. If the file to be merged is not binary and is not a symlink, then
5895 internal :merge is used.
5896 8. Otherwise, :prompt is used.
5898 For historical reason, Mercurial treats merge tools as below while
5900 examining rules above.
5901 ┌───────────┬────────────────┬────────┬─────────┐
5903 │step │ specified via │ binary │ symlink │
5904 ├───────────┼────────────────┼────────┼─────────┤
5905 │ │ --tool │ o/o │ o/o │
5906 │ 1. │ │ │ │
5907 ├───────────┼────────────────┼────────┼─────────┤
5908 │ │ HGMERGE │ o/o │ o/o │
5909 │ 2. │ │ │ │
5910 ├───────────┼────────────────┼────────┼─────────┤
5911 │ │ merge-patterns │ o/o(*) │ x/?(*) │
5912 │ 3. │ │ │ │
5913 └───────────┴────────────────┴────────┴─────────┘
5914 │ │ ui.merge │ x/?(*) │ x/?(*) │
5916 │ 4. │ │ │ │
5917 └───────────┴────────────────┴────────┴─────────┘
5918 Each capability column indicates Mercurial behavior for internal/exter‐
5920 nal merge tools at examining each rule.
5921 · "o": "assume that a tool has capability"
5923 · "x": "assume that a tool does not have capability"
5925 · "?": "check actual capability of a tool"
5927 If merge.strict-capability-check configuration is true, Mercurial
5929 checks capabilities of merge tools strictly in (*) cases above (= each
5930 capability column becomes "?/?"). It is false by default for backward
5931 compatibility.
5932 Note After selecting a merge program, Mercurial will by default
5934 attempt to merge the files using a simple merge algorithm first.
5935 Only if it doesn't succeed because of conflicting changes will
5936 Mercurial actually execute the merge program. Whether to use the
5937 simple merge algorithm first can be controlled by the premerge
5938 setting of the merge tool. Premerge is enabled by default unless
5939 the file is binary or a symlink.
5940 See the merge-tools and ui sections of hgrc(5) for details on the con‐
5942 figuration of merge tools.
5943
5945 Some Mercurial commands can produce a lot of output, and Mercurial will
5946 attempt to use a pager to make those commands more pleasant.
5947 To set the pager that should be used, set the application variable:
5949 [pager]
5951 pager = less -FRX
5952 If no pager is set in the user or repository configuration, Mercurial
5954 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
5955 from the default or system configuration is used. If none of these are
5956 set, a default pager will be used, typically less on Unix and more on
5957 Windows.
5958 On Windows, more is not color aware, so using it effectively disables
5960 color. MSYS and Cygwin shells provide less as a pager, which can be
5961 configured to support ANSI color codes. See hg help con‐
5962 fig.color.pagermode to configure the color mode when invoking a pager.
5963 You can disable the pager for certain commands by adding them to the
5965 pager.ignore list:
5966 [pager]
5968 ignore = version, help, update
5969 To ignore global commands like hg version or hg help, you have to spec‐
5971 ify them in your user configuration file.
5972 To control whether the pager is used at all for an individual command,
5974 you can use --pager=<value>:
5975 · use as needed: auto.
5977 · require the pager: yes or on.
5979 · suppress the pager: no or off (any unrecognized value will also
5981 work).
5982 To globally turn off all attempts to use a pager, set:
5984 [ui]
5986 paginate = never
5987 which will prevent the pager from running.
5989
5991 Mercurial accepts several notations for identifying one or more files
5992 at a time.
5993 By default, Mercurial treats filenames as shell-style extended glob
5995 patterns.
5996 Alternate pattern notations must be specified explicitly.
5998 Note Patterns specified in .hgignore are not rooted. Please see hg
6000 help hgignore for details.
6001 To use a plain path name without any pattern matching, start it with
6003 path:. These path names must completely match starting at the current
6004 repository root, and when the path points to a directory, it is matched
6005 recursively. To match all files in a directory non-recursively (not
6006 including any files in subdirectories), rootfilesin: can be used, spec‐
6007 ifying an absolute path (relative to the repository root).
6008 To use an extended glob, start a name with glob:. Globs are rooted at
6010 the current directory; a glob such as *.c will only match files in the
6011 current directory ending with .c. rootglob: can be used instead of
6012 glob: for a glob that is rooted at the root of the repository.
6013 The supported glob syntax extensions are ** to match any string across
6015 path separators and {a,b} to mean "a or b".
6016 To use a Perl/Python regular expression, start a name with re:. Regexp
6018 pattern matching is anchored at the root of the repository.
6019 To read name patterns from a file, use listfile: or listfile0:. The
6021 latter expects null delimited patterns while the former expects line
6022 feeds. Each string read from the file is itself treated as a file pat‐
6023 tern.
6024 To read a set of patterns from a file, use include: or subinclude:.
6026 include: will use all the patterns from the given file and treat them
6027 as if they had been passed in manually. subinclude: will only apply
6028 the patterns against files that are under the subinclude file's direc‐
6029 tory. See hg help hgignore for details on the format of these files.
6030 All patterns, except for glob: specified in command line (not for -I or
6032 -X options), can match also against directories: files under matched
6033 directories are treated as matched. For -I and -X options, glob: will
6034 match directories recursively.
6035 Plain examples:
6037 path:foo/bar a name bar in a directory named foo in the root
6039 of the repository
6040 path:path:name a file or directory named "path:name"
6041 rootfilesin:foo/bar the files in a directory called foo/bar, but not any files
6042 in its subdirectories and not a file bar in directory foo
6043 Glob examples:
6045 glob:*.c any name ending in ".c" in the current directory
6047 *.c any name ending in ".c" in the current directory
6048 **.c any name ending in ".c" in any subdirectory of the
6049 current directory including itself.
6050 foo/* any file in directory foo
6051 foo/** any file in directory foo plus all its subdirectories,
6052 recursively
6053 foo/*.c any name ending in ".c" in the directory foo
6054 foo/**.c any name ending in ".c" in any subdirectory of foo
6055 including itself.
6056 rootglob:*.c any name ending in ".c" in the root of the repository
6057 Regexp examples:
6059 re:.*\.c$ any name ending in ".c", anywhere in the repository
6061 File examples:
6063 listfile:list.txt read list from list.txt with one file pattern per line
6065 listfile0:list.txt read list from list.txt with null byte delimiters
6066 See also hg help filesets.
6068 Include examples:
6070 include:path/to/mypatternfile reads patterns to be applied to all paths
6072 subinclude:path/to/subignorefile reads patterns specifically for paths in the
6073 subdirectory
6074
6076 What are phases?
6077 Phases are a system for tracking which changesets have been or should
6078 be shared. This helps prevent common mistakes when modifying history
6079 (for instance, with the mq or rebase extensions).
6080 Each changeset in a repository is in one of the following phases:
6082 · public : changeset is visible on a public server
6084 · draft : changeset is not yet published
6086 · secret : changeset should not be pushed, pulled, or cloned
6088 These phases are ordered (public < draft < secret) and no changeset can
6090 be in a lower phase than its ancestors. For instance, if a changeset is
6091 public, all its ancestors are also public. Lastly, changeset phases
6092 should only be changed towards the public phase.
6093 How are phases managed?
6095 For the most part, phases should work transparently. By default, a
6096 changeset is created in the draft phase and is moved into the public
6097 phase when it is pushed to another repository.
6098 Once changesets become public, extensions like mq and rebase will
6100 refuse to operate on them to prevent creating duplicate changesets.
6101 Phases can also be manually manipulated with the hg phase command if
6102 needed. See hg help -v phase for examples.
6103 To make your commits secret by default, put this in your configuration
6105 file:
6106 [phases]
6108 new-commit = secret
6109 Phases and servers
6111 Normally, all servers are publishing by default. This means:
6112 - all draft changesets that are pulled or cloned appear in phase
6114 public on the client
6115 - all draft changesets that are pushed appear as public on both
6117 client and server
6118 - secret changesets are neither pushed, pulled, or cloned
6120 Note Pulling a draft changeset from a publishing server does not mark
6122 it as public on the server side due to the read-only nature of
6123 pull.
6124 Sometimes it may be desirable to push and pull changesets in the draft
6126 phase to share unfinished work. This can be done by setting a reposi‐
6127 tory to disable publishing in its configuration file:
6128 [phases]
6130 publish = False
6131 See hg help config for more information on configuration files.
6133 Note Servers running older versions of Mercurial are treated as pub‐
6135 lishing.
6136 Note Changesets in secret phase are not exchanged with the server.
6138 This applies to their content: file names, file contents, and
6139 changeset metadata. For technical reasons, the identifier (e.g.
6140 d825e4025e39) of the secret changeset may be communicated to the
6141 server.
6142 Examples
6144 · list changesets in draft or secret phase:
6145 hg log -r "not public()"
6147 · change all secret changesets to draft:
6149 hg phase --draft "secret()"
6151 · forcibly move the current changeset and descendants from public to
6153 draft:
6154 hg phase --force --draft .
6156 · show a list of changeset revisions and each corresponding phase:
6158 hg log --template "{rev} {phase}\n"
6160 · resynchronize draft changesets relative to a remote repository:
6162 hg phase -fd "outgoing(URL)"
6164 See hg help phase for more information on manually manipulating phases.
6166
6168 Mercurial supports several ways to specify revisions.
6169 Specifying single revisions
6171 A plain integer is treated as a revision number. Negative integers are
6172 treated as sequential offsets from the tip, with -1 denoting the tip,
6173 -2 denoting the revision prior to the tip, and so forth.
6174 A 40-digit hexadecimal string is treated as a unique revision identi‐
6176 fier. A hexadecimal string less than 40 characters long is treated as
6177 a unique revision identifier and is referred to as a short-form identi‐
6178 fier. A short-form identifier is only valid if it is the prefix of
6179 exactly one full-length identifier.
6180 Any other string is treated as a bookmark, tag, or branch name. A book‐
6182 mark is a movable pointer to a revision. A tag is a permanent name
6183 associated with a revision. A branch name denotes the tipmost open
6184 branch head of that branch - or if they are all closed, the tipmost
6185 closed head of the branch. Bookmark, tag, and branch names must not
6186 contain the ":" character.
6187 The reserved name "tip" always identifies the most recent revision.
6189 The reserved name "null" indicates the null revision. This is the revi‐
6191 sion of an empty repository, and the parent of revision 0.
6192 The reserved name "." indicates the working directory parent. If no
6194 working directory is checked out, it is equivalent to null. If an
6195 uncommitted merge is in progress, "." is the revision of the first par‐
6196 ent.
6197 Finally, commands that expect a single revision (like hg update) also
6199 accept revsets (see below for details). When given a revset, they use
6200 the last revision of the revset. A few commands accept two single revi‐
6201 sions (like hg diff). When given a revset, they use the first and the
6202 last revisions of the revset.
6203 Specifying multiple revisions
6205 Mercurial supports a functional language for selecting a set of revi‐
6206 sions. Expressions in this language are called revsets.
6207 The language supports a number of predicates which are joined by infix
6209 operators. Parenthesis can be used for grouping.
6210 Identifiers such as branch names may need quoting with single or double
6212 quotes if they contain characters like - or if they match one of the
6213 predefined predicates.
6214 Special characters can be used in quoted identifiers by escaping them,
6216 e.g., \n is interpreted as a newline. To prevent them from being inter‐
6217 preted, strings can be prefixed with r, e.g. r'...'.
6218 Operators
6220 There is a single prefix operator:
6221 not x
6223 Changesets not in x. Short form is ! x.
6225 These are the supported infix operators:
6227 x::y
6229 A DAG range, meaning all changesets that are descendants of x
6231 and ancestors of y, including x and y themselves. If the first
6232 endpoint is left out, this is equivalent to ancestors(y), if the
6233 second is left out it is equivalent to descendants(x).
6234 An alternative syntax is x..y.
6236 x:y
6238 All changesets with revision numbers between x and y, both
6240 inclusive. Either endpoint can be left out, they default to 0
6241 and tip.
6242 x and y
6244 The intersection of changesets in x and y. Short form is x & y.
6246 x or y
6248 The union of changesets in x and y. There are two alternative
6250 short forms: x | y and x + y.
6251 x - y
6253 Changesets in x but not in y.
6255 x % y
6257 Changesets that are ancestors of x but not ancestors of y (i.e.
6259 ::x - ::y). This is shorthand notation for only(x, y) (see
6260 below). The second argument is optional and, if left out, is
6261 equivalent to only(x).
6262 x^n
6264 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
6266 1, the first parent of each changeset in x; for n == 2, the sec‐
6267 ond parent of changeset in x.
6268 x~n
6270 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
6272 the nth unambiguous descendent of x.
6273 x ## y
6275 Concatenate strings and identifiers into one string.
6277 All other prefix, infix and postfix operators have lower prior‐
6279 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
6280 a2)~2.
6281 For example:
6283 [revsetalias]
6285 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
6286 issue(1234) is equivalent to grep(r'\bissue[
6288 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
6289 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
6290 There is a single postfix operator:
6292 x^
6294 Equivalent to x^1, the first parent of each changeset in x.
6296 Patterns
6298 Where noted, predicates that perform string matching can accept a pat‐
6299 tern string. The pattern may be either a literal, or a regular expres‐
6300 sion. If the pattern starts with re:, the remainder of the pattern is
6301 treated as a regular expression. Otherwise, it is treated as a literal.
6302 To match a pattern that actually starts with re:, use the prefix lit‐
6303 eral:.
6304 Matching is case-sensitive, unless otherwise noted. To perform a case-
6306 insensitive match on a case-sensitive predicate, use a regular expres‐
6307 sion, prefixed with (?i).
6308 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
6310 "Release", etc.
6311 Predicates
6313 The following predicates are supported:
6314 adds(pattern)
6316 Changesets that add a file matching pattern.
6318 The pattern without explicit kind like glob: is expected to be
6320 relative to the current directory and match against a file or a
6321 directory.
6322 all()
6324 All changesets, the same as 0:tip.
6326 ancestor(*changeset)
6328 A greatest common ancestor of the changesets.
6330 Accepts 0 or more changesets. Will return empty list when
6332 passed no args. Greatest common ancestor of a single changeset
6333 is that changeset.
6334 ancestors(set[, depth])
6336 Changesets that are ancestors of changesets in set, including
6338 the given changesets themselves.
6339 If depth is specified, the result only includes changesets up to
6341 the specified generation.
6342 author(string)
6344 Alias for user(string).
6346 bisect(string)
6348 Changesets marked in the specified bisect status:
6350 · good, bad, skip: csets explicitly marked as good/bad/skip
6352 · goods, bads : csets topologically good/bad
6354 · range : csets taking part in the bisection
6356 · pruned : csets that are goods, bads or skipped
6358 · untested : csets whose fate is yet unknown
6360 · ignored : csets ignored due to DAG topology
6362 · current : the cset currently being bisected
6364 bookmark([name])
6366 The named bookmark or all bookmarks.
6368 Pattern matching is supported for name. See hg help revi‐
6370 sions.patterns.
6371 branch(string or set)
6373 All changesets belonging to the given branch or the branches of
6375 the given changesets.
6376 Pattern matching is supported for string. See hg help revi‐
6378 sions.patterns.
6379 branchpoint()
6381 Changesets with more than one child.
6383 bundle()
6385 Changesets in the bundle.
6387 Bundle must be specified by the -R option.
6389 children(set)
6391 Child changesets of changesets in set.
6393 closed()
6395 Changeset is closed.
6397 commonancestors(set)
6399 Changesets that are ancestors of every changeset in set.
6401 contains(pattern)
6403 The revision's manifest contains a file matching pattern (but
6405 might not modify it). See hg help patterns for information about
6406 file patterns.
6407 The pattern without explicit kind like glob: is expected to be
6409 relative to the current directory and match against a file
6410 exactly for efficiency.
6411 converted([id])
6413 Changesets converted from the given identifier in the old repos‐
6415 itory if present, or all converted changesets if no identifier
6416 is specified.
6417 date(interval)
6419 Changesets within the interval, see hg help dates.
6421 desc(string)
6423 Search commit message for string. The match is case-insensitive.
6425 Pattern matching is supported for string. See hg help revi‐
6427 sions.patterns.
6428 descendants(set[, depth])
6430 Changesets which are descendants of changesets in set, including
6432 the given changesets themselves.
6433 If depth is specified, the result only includes changesets up to
6435 the specified generation.
6436 destination([set])
6438 Changesets that were created by a graft, transplant or rebase
6440 operation, with the given revisions specified as the source.
6441 Omitting the optional set is the same as passing all().
6442 draft()
6444 Changeset in draft phase.
6446 expectsize(set[, size])
6448 Return the given revset if size matches the revset size. Abort
6450 if the revset doesn't expect given size. size can either be an
6451 integer range or an integer.
6452 For example, expectsize(0:1, 3:5) will abort as revset size is 2
6454 and 2 is not between 3 and 5 inclusive.
6455 extinct()
6457 Obsolete changesets with obsolete descendants only.
6459 extra(label, [value])
6461 Changesets with the given label in the extra metadata, with the
6463 given optional value.
6464 Pattern matching is supported for value. See hg help revi‐
6466 sions.patterns.
6467 file(pattern)
6469 Changesets affecting files matched by pattern.
6471 For a faster but less accurate result, consider using filelog()
6473 instead.
6474 This predicate uses glob: as the default kind of pattern.
6476 filelog(pattern)
6478 Changesets connected to the specified filelog.
6480 For performance reasons, visits only revisions mentioned in the
6482 file-level filelog, rather than filtering through all changesets
6483 (much faster, but doesn't include deletes or duplicate changes).
6484 For a slower, more accurate result, use file().
6485 The pattern without explicit kind like glob: is expected to be
6487 relative to the current directory and match against a file
6488 exactly for efficiency.
6489 first(set, [n])
6491 An alias for limit().
6493 follow([file[, startrev]])
6495 An alias for ::. (ancestors of the working directory's first
6497 parent). If file pattern is specified, the histories of files
6498 matching given pattern in the revision given by startrev are
6499 followed, including copies.
6500 followlines(file, fromline:toline[, startrev=., descend=False])
6502 Changesets modifying file in line range ('fromline', 'toline').
6504 Line range corresponds to 'file' content at 'startrev' and
6506 should hence be consistent with file size. If startrev is not
6507 specified, working directory's parent is used.
6508 By default, ancestors of 'startrev' are returned. If 'descend'
6510 is True, descendants of 'startrev' are returned though renames
6511 are (currently) not followed in this direction.
6512 grep(regex)
6514 Like keyword(string) but accepts a regex. Use grep(r'...') to
6516 ensure special escape characters are handled correctly. Unlike
6517 keyword(string), the match is case-sensitive.
6518 head()
6520 Changeset is a named branch head.
6522 heads(set)
6524 Members of set with no children in set.
6526 hidden()
6528 Hidden changesets.
6530 id(string)
6532 Revision non-ambiguously specified by the given hex string pre‐
6534 fix.
6535 keyword(string)
6537 Search commit message, user name, and names of changed files for
6539 string. The match is case-insensitive.
6540 For a regular expression or case sensitive search of these
6542 fields, use grep(regex).
6543 last(set, [n])
6545 Last n members of set, defaulting to 1.
6547 limit(set[, n[, offset]])
6549 First n members of set, defaulting to 1, starting from offset.
6551 matching(revision [, field])
6553 Changesets in which a given set of fields match the set of
6555 fields in the selected revision or set.
6556 To match more than one field pass the list of fields to match
6558 separated by spaces (e.g. author description).
6559 Valid fields are most regular revision fields and some special
6561 fields.
6562 Regular revision fields are description, author, branch, date,
6564 files, phase, parents, substate, user and diff. Note that
6565 author and user are synonyms. diff refers to the contents of the
6566 revision. Two revisions matching their diff will also match
6567 their files.
6568 Special fields are summary and metadata: summary matches the
6570 first line of the description. metadata is equivalent to match‐
6571 ing description user date (i.e. it matches the main metadata
6572 fields).
6573 metadata is the default field which is used when no fields are
6575 specified. You can match more than one field at a time.
6576 max(set)
6578 Changeset with highest revision number in set.
6580 merge()
6582 Changeset is a merge changeset.
6584 min(set)
6586 Changeset with lowest revision number in set.
6588 modifies(pattern)
6590 Changesets modifying files matched by pattern.
6592 The pattern without explicit kind like glob: is expected to be
6594 relative to the current directory and match against a file or a
6595 directory.
6596 named(namespace)
6598 The changesets in a given namespace.
6600 Pattern matching is supported for namespace. See hg help revi‐
6602 sions.patterns.
6603 none()
6605 No changesets.
6607 obsolete()
6609 Mutable changeset with a newer version.
6611 only(set, [set])
6613 Changesets that are ancestors of the first set that are not
6615 ancestors of any other head in the repo. If a second set is
6616 specified, the result is ancestors of the first set that are not
6617 ancestors of the second set (i.e. ::<set1> - ::<set2>).
6618 origin([set])
6620 Changesets that were specified as a source for the grafts,
6622 transplants or rebases that created the given revisions. Omit‐
6623 ting the optional set is the same as passing all(). If a
6624 changeset created by these operations is itself specified as a
6625 source for one of these operations, only the source changeset
6626 for the first operation is selected.
6627 outgoing([path])
6629 Changesets not found in the specified destination repository, or
6631 the default push location.
6632 p1([set])
6634 First parent of changesets in set, or the working directory.
6636 p2([set])
6638 Second parent of changesets in set, or the working directory.
6640 parents([set])
6642 The set of all parents for all changesets in set, or the working
6644 directory.
6645 present(set)
6647 An empty set, if any revision in set isn't found; otherwise, all
6649 revisions in set.
6650 If any of specified revisions is not present in the local repos‐
6652 itory, the query is normally aborted. But this predicate allows
6653 the query to continue even in such cases.
6654 public()
6656 Changeset in public phase.
6658 remote([id [,path]])
6660 Local revision that corresponds to the given identifier in a
6662 remote repository, if present. Here, the '.' identifier is a
6663 synonym for the current local branch.
6664 removes(pattern)
6666 Changesets which remove files matching pattern.
6668 The pattern without explicit kind like glob: is expected to be
6670 relative to the current directory and match against a file or a
6671 directory.
6672 rev(number)
6674 Revision with the given numeric identifier.
6676 reverse(set)
6678 Reverse order of set.
6680 revset(set)
6682 Strictly interpret the content as a revset.
6684 The content of this special predicate will be strictly inter‐
6686 preted as a revset. For example, revset(id(0)) will be inter‐
6687 preted as "id(0)" without possible ambiguity with a "id(0)"
6688 bookmark or tag.
6689 roots(set)
6691 Changesets in set with no parent changeset in set.
6693 secret()
6695 Changeset in secret phase.
6697 sort(set[, [-]key... [, ...]])
6699 Sort set by keys. The default sort order is ascending, specify a
6701 key as -key to sort in descending order.
6702 The keys can be:
6704 · rev for the revision number,
6706 · branch for the branch name,
6708 · desc for the commit message (description),
6710 · user for user name (author can be used as an alias),
6712 · date for the commit date
6714 · topo for a reverse topographical sort
6716 The topo sort order cannot be combined with other sort keys.
6718 This sort takes one optional argument, topo.firstbranch, which
6719 takes a revset that specifies what topographical branches to
6720 prioritize in the sort.
6721 subrepo([pattern])
6723 Changesets that add, modify or remove the given subrepo. If no
6725 subrepo pattern is named, any subrepo changes are returned.
6726 successors(set)
6728 All successors for set, including the given set themselves
6730 tag([name])
6732 The specified tag by name, or all tagged revisions if no name is
6734 given.
6735 Pattern matching is supported for name. See hg help revi‐
6737 sions.patterns.
6738 user(string)
6740 User name contains string. The match is case-insensitive.
6742 Pattern matching is supported for string. See hg help revi‐
6744 sions.patterns.
6745 Aliases
6747 New predicates (known as "aliases") can be defined, using any combina‐
6748 tion of existing predicates or other aliases. An alias definition looks
6749 like:
6750 <alias> = <definition>
6752 in the revsetalias section of a Mercurial configuration file. Arguments
6754 of the form a1, a2, etc. are substituted from the alias into the defi‐
6755 nition.
6756 For example,
6758 [revsetalias]
6760 h = heads()
6761 d(s) = sort(s, date)
6762 rs(s, k) = reverse(sort(s, k))
6763 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
6765 equivalent to reverse(sort(0:tip, author)).
6766 Equivalents
6768 Command line equivalents for hg log:
6769 -f -> ::.
6771 -d x -> date(x)
6772 -k x -> keyword(x)
6773 -m -> merge()
6774 -u x -> user(x)
6775 -b x -> branch(x)
6776 -P x -> !::x
6777 -l x -> limit(expr, x)
6778 Examples
6780 Some sample queries:
6781 · Changesets on the default branch:
6783 hg log -r "branch(default)"
6785 · Changesets on the default branch since tag 1.5 (excluding merges):
6787 hg log -r "branch(default) and 1.5:: and not merge()"
6789 · Open branch heads:
6791 hg log -r "head() and not closed()"
6793 · Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
6795 hgext/*:
6796 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
6798 · Changesets committed in May 2008, sorted by user:
6800 hg log -r "sort(date('May 2008'), user)"
6802 · Changesets mentioning "bug" or "issue" that are not in a tagged
6804 release:
6805 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
6807 · Update to the commit that bookmark @ is pointing to, without activat‐
6809 ing the bookmark (this works because the last revision of the revset
6810 is used):
6811 hg update :@
6813 · Show diff between tags 1.3 and 1.5 (this works because the first and
6815 the last revisions of the revset are used):
6816 hg diff -r 1.3::1.5
6818
6820 It is common for machines (as opposed to humans) to consume Mercurial.
6821 This help topic describes some of the considerations for interfacing
6822 machines with Mercurial.
6823 Choosing an Interface
6825 Machines have a choice of several methods to interface with Mercurial.
6826 These include:
6827 · Executing the hg process
6829 · Querying a HTTP server
6831 · Calling out to a command server
6833 Executing hg processes is very similar to how humans interact with Mer‐
6835 curial in the shell. It should already be familiar to you.
6836 hg serve can be used to start a server. By default, this will start a
6838 "hgweb" HTTP server. This HTTP server has support for machine-readable
6839 output, such as JSON. For more, see hg help hgweb.
6840 hg serve can also start a "command server." Clients can connect to this
6842 server and issue Mercurial commands over a special protocol. For more
6843 details on the command server, including links to client libraries, see
6844 https://www.mercurial-scm.org/wiki/CommandServer.
6845 hg serve based interfaces (the hgweb and command servers) have the
6847 advantage over simple hg process invocations in that they are likely
6848 more efficient. This is because there is significant overhead to spawn
6849 new Python processes.
6850 Tip If you need to invoke several hg processes in short order and/or
6852 performance is important to you, use of a server-based interface
6853 is highly recommended.
6854 Environment Variables
6856 As documented in hg help environment, various environment variables
6857 influence the operation of Mercurial. The following are particularly
6858 relevant for machines consuming Mercurial:
6859 HGPLAIN
6861 If not set, Mercurial's output could be influenced by configura‐
6862 tion settings that impact its encoding, verbose mode, localiza‐
6863 tion, etc.
6864 It is highly recommended for machines to set this variable when
6866 invoking hg processes.
6867 HGENCODING
6869 If not set, the locale used by Mercurial will be detected from
6870 the environment. If the determined locale does not support dis‐
6871 play of certain characters, Mercurial may render these character
6872 sequences incorrectly (often by using "?" as a placeholder for
6873 invalid characters in the current locale).
6874 Explicitly setting this environment variable is a good practice
6876 to guarantee consistent results. "utf-8" is a good choice on
6877 UNIX-like environments.
6878 HGRCPATH
6880 If not set, Mercurial will inherit config options from config
6881 files using the process described in hg help config. This
6882 includes inheriting user or system-wide config files.
6883 When utmost control over the Mercurial configuration is desired,
6885 the value of HGRCPATH can be set to an explicit file with known
6886 good configs. In rare cases, the value can be set to an empty
6887 file or the null device (often /dev/null) to bypass loading of
6888 any user or system config files. Note that these approaches can
6889 have unintended consequences, as the user and system config
6890 files often define things like the username and extensions that
6891 may be required to interface with a repository.
6892 Command-line Flags
6894 Mercurial's default command-line parser is designed for humans, and is
6895 not robust against malicious input. For instance, you can start a
6896 debugger by passing --debugger as an option value:
6897 $ REV=--debugger sh -c 'hg log -r "$REV"'
6899 This happens because several command-line flags need to be scanned
6901 without using a concrete command table, which may be modified while
6902 loading repository settings and extensions.
6903 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
6905 setting HGPLAIN=+strictflags. When this feature is enabled, all early
6906 options (e.g. -R/--repository, --cwd, --config) must be specified first
6907 amongst the other global options, and cannot be injected to an arbi‐
6908 trary location:
6909 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
6911 In earlier Mercurial versions where +strictflags isn't available, you
6913 can mitigate the issue by concatenating an option value with its flag:
6914 $ hg log -r"$REV" --keyword="$KEYWORD"
6916 Consuming Command Output
6918 It is common for machines to need to parse the output of Mercurial com‐
6919 mands for relevant data. This section describes the various techniques
6920 for doing so.
6921 Parsing Raw Command Output
6923 Likely the simplest and most effective solution for consuming command
6924 output is to simply invoke hg commands as you would as a user and parse
6925 their output.
6926 The output of many commands can easily be parsed with tools like grep,
6928 sed, and awk.
6929 A potential downside with parsing command output is that the output of
6931 commands can change when Mercurial is upgraded. While Mercurial does
6932 generally strive for strong backwards compatibility, command output
6933 does occasionally change. Having tests for your automated interactions
6934 with hg commands is generally recommended, but is even more important
6935 when raw command output parsing is involved.
6936 Using Templates to Control Output
6938 Many hg commands support templatized output via the -T/--template argu‐
6939 ment. For more, see hg help templates.
6940 Templates are useful for explicitly controlling output so that you get
6942 exactly the data you want formatted how you want it. For example, log
6943 -T {node}\n can be used to print a newline delimited list of changeset
6944 nodes instead of a human-tailored output containing authors, dates,
6945 descriptions, etc.
6946 Tip If parsing raw command output is too complicated, consider using
6948 templates to make your life easier.
6949 The -T/--template argument allows specifying pre-defined styles. Mer‐
6951 curial ships with the machine-readable styles cbor, json, and xml,
6952 which provide CBOR, JSON, and XML output, respectively. These are use‐
6953 ful for producing output that is machine readable as-is.
6954 (Mercurial 5.0 is required for CBOR style.)
6956 Important
6958 The json and xml styles are considered experimental. While they
6959 may be attractive to use for easily obtaining machine-readable
6960 output, their behavior may change in subsequent versions.
6961 These styles may also exhibit unexpected results when dealing
6963 with certain encodings. Mercurial treats things like filenames
6964 as a series of bytes and normalizing certain byte sequences to
6965 JSON or XML with certain encoding settings can lead to sur‐
6966 prises.
6967 Command Server Output
6969 If using the command server to interact with Mercurial, you are likely
6970 using an existing library/API that abstracts implementation details of
6971 the command server. If so, this interface layer may perform parsing for
6972 you, saving you the work of implementing it yourself.
6973 Output Verbosity
6975 Commands often have varying output verbosity, even when machine read‐
6976 able styles are being used (e.g. -T json). Adding -v/--verbose and
6977 --debug to the command's arguments can increase the amount of data
6978 exposed by Mercurial.
6979 An alternate way to get the data you need is by explicitly specifying a
6981 template.
6982 Other Topics
6984 revsets
6985 Revisions sets is a functional query language for selecting a
6986 set of revisions. Think of it as SQL for Mercurial repositories.
6987 Revsets are useful for querying repositories for specific data.
6988 See hg help revsets for more.
6990 share extension
6992 The share extension provides functionality for sharing reposi‐
6993 tory data across several working copies. It can even automati‐
6994 cally "pool" storage for logically related repositories when
6995 cloning.
6996 Configuring the share extension can lead to significant resource
6998 utilization reduction, particularly around disk space and the
6999 network. This is especially true for continuous integration (CI)
7000 environments.
7001 See hg help -e share for more.
7003
7005 Subrepositories let you nest external repositories or projects into a
7006 parent Mercurial repository, and make commands operate on them as a
7007 group.
7008 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
7010 tories.
7011 Subrepositories are made of three components:
7013 1. Nested repository checkouts. They can appear anywhere in the parent
7015 working directory.
7016 2. Nested repository references. They are defined in .hgsub, which
7018 should be placed in the root of working directory, and tell where
7019 the subrepository checkouts come from. Mercurial subrepositories are
7020 referenced like:
7021 path/to/nested = https://example.com/nested/repo/path
7023 Git and Subversion subrepos are also supported:
7025 path/to/nested = [git]git://example.com/nested/repo/path
7027 path/to/nested = [svn]https://example.com/nested/trunk/path
7028 where path/to/nested is the checkout location relatively to the par‐
7030 ent Mercurial root, and https://example.com/nested/repo/path is the
7031 source repository path. The source can also reference a filesystem
7032 path.
7033 Note that .hgsub does not exist by default in Mercurial reposito‐
7035 ries, you have to create and add it to the parent repository before
7036 using subrepositories.
7037 3. Nested repository states. They are defined in .hgsubstate, which is
7039 placed in the root of working directory, and capture whatever infor‐
7040 mation is required to restore the subrepositories to the state they
7041 were committed in a parent repository changeset. Mercurial automati‐
7042 cally record the nested repositories states when committing in the
7043 parent repository.
7044 Note
7046 The .hgsubstate file should not be edited manually.
7047 Adding a Subrepository
7049 If .hgsub does not exist, create it and add it to the parent reposi‐
7050 tory. Clone or checkout the external projects where you want it to live
7051 in the parent repository. Edit .hgsub and add the subrepository entry
7052 as described above. At this point, the subrepository is tracked and the
7053 next commit will record its state in .hgsubstate and bind it to the
7054 committed changeset.
7055 Synchronizing a Subrepository
7057 Subrepos do not automatically track the latest changeset of their
7058 sources. Instead, they are updated to the changeset that corresponds
7059 with the changeset checked out in the top-level changeset. This is so
7060 developers always get a consistent set of compatible code and libraries
7061 when they update.
7062 Thus, updating subrepos is a manual process. Simply check out target
7064 subrepo at the desired revision, test in the top-level repo, then com‐
7065 mit in the parent repository to record the new combination.
7066 Deleting a Subrepository
7068 To remove a subrepository from the parent repository, delete its refer‐
7069 ence from .hgsub, then remove its files.
7070 Interaction with Mercurial Commands
7072 add add does not recurse in subrepos unless -S/--subrepos is speci‐
7073 fied. However, if you specify the full path of a file in a sub‐
7074 repo, it will be added even without -S/--subrepos specified.
7075 Subversion subrepositories are currently silently ignored.
7076 addremove
7078 addremove does not recurse into subrepos unless -S/--subrepos is
7079 specified. However, if you specify the full path of a directory
7080 in a subrepo, addremove will be performed on it even without
7081 -S/--subrepos being specified. Git and Subversion subreposito‐
7082 ries will print a warning and continue.
7083 archive
7085 archive does not recurse in subrepositories unless -S/--subrepos
7086 is specified.
7087 cat Git subrepositories only support exact file matches. Subversion
7089 subrepositories are currently ignored.
7090 commit commit creates a consistent snapshot of the state of the entire
7092 project and its subrepositories. If any subrepositories have
7093 been modified, Mercurial will abort. Mercurial can be made to
7094 instead commit all modified subrepositories by specifying
7095 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
7096 ration file (see hg help config). After there are no longer any
7097 modified subrepositories, it records their state and finally
7098 commits it in the parent repository. The --addremove option
7099 also honors the -S/--subrepos option. However, Git and Subver‐
7100 sion subrepositories will print a warning and abort.
7101 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
7103 fied. However, if you specify the full path of a file or direc‐
7104 tory in a subrepo, it will be diffed even without -S/--subrepos
7105 being specified. Subversion subrepositories are currently
7106 silently ignored.
7107 files files does not recurse into subrepos unless -S/--subrepos is
7109 specified. However, if you specify the full path of a file or
7110 directory in a subrepo, it will be displayed even without
7111 -S/--subrepos being specified. Git and Subversion subreposito‐
7112 ries are currently silently ignored.
7113 forget forget currently only handles exact file matches in subrepos.
7115 Git and Subversion subrepositories are currently silently
7116 ignored.
7117 incoming
7119 incoming does not recurse in subrepos unless -S/--subrepos is
7120 specified. Git and Subversion subrepositories are currently
7121 silently ignored.
7122 outgoing
7124 outgoing does not recurse in subrepos unless -S/--subrepos is
7125 specified. Git and Subversion subrepositories are currently
7126 silently ignored.
7127 pull pull is not recursive since it is not clear what to pull prior
7129 to running hg update. Listing and retrieving all subrepositories
7130 changes referenced by the parent repository pulled changesets is
7131 expensive at best, impossible in the Subversion case.
7132 push Mercurial will automatically push all subrepositories first when
7134 the parent repository is being pushed. This ensures new sub‐
7135 repository changes are available when referenced by top-level
7136 repositories. Push is a no-op for Subversion subrepositories.
7137 serve serve does not recurse into subrepositories unless -S/--subrepos
7139 is specified. Git and Subversion subrepositories are currently
7140 silently ignored.
7141 status status does not recurse into subrepositories unless -S/--subre‐
7143 pos is specified. Subrepository changes are displayed as regular
7144 Mercurial changes on the subrepository elements. Subversion sub‐
7145 repositories are currently silently ignored.
7146 remove remove does not recurse into subrepositories unless -S/--subre‐
7148 pos is specified. However, if you specify a file or directory
7149 path in a subrepo, it will be removed even without -S/--subre‐
7150 pos. Git and Subversion subrepositories are currently silently
7151 ignored.
7152 update update restores the subrepos in the state they were originally
7154 committed in target changeset. If the recorded changeset is not
7155 available in the current subrepository, Mercurial will pull it
7156 in first before updating. This means that updating can require
7157 network access when using subrepositories.
7158 Remapping Subrepositories Sources
7160 A subrepository source location may change during a project life,
7161 invalidating references stored in the parent repository history. To fix
7162 this, rewriting rules can be defined in parent repository hgrc file or
7163 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
7164 more details.
7165
7167 Mercurial allows you to customize output of commands through templates.
7168 You can either pass in a template or select an existing template-style
7169 from the command line, via the --template option.
7170 You can customize output for any "log-like" command: log, outgoing,
7172 incoming, tip, parents, and heads.
7173 Some built-in styles are packaged with Mercurial. These can be listed
7175 with hg log --template list. Example usage:
7176 $ hg log -r1.0::1.1 --template changelog
7178 A template is a piece of text, with markup to invoke variable expan‐
7180 sion:
7181 $ hg log -r1 --template "{node}\n"
7183 b56ce7b07c52de7d5fd79fb89701ea538af65746
7184 Keywords
7186 Strings in curly braces are called keywords. The availability of key‐
7187 words depends on the exact context of the templater. These keywords are
7188 usually available for templating a log-like command:
7189 activebookmark
7191 String. The active bookmark, if it is associated with the
7192 changeset.
7193 author Alias for {user}
7195 bisect String. The changeset bisection status.
7197 bookmarks
7199 List of strings. Any bookmarks associated with the changeset.
7200 Also sets 'active', the name of the active bookmark.
7201 branch String. The name of the branch on which the changeset was com‐
7203 mitted.
7204 changessincelatesttag
7206 Integer. All ancestors not in the latest tag.
7207 children
7209 List of strings. The children of the changeset.
7210 date Date information. The date when the changeset was committed.
7212 desc String. The text of the changeset description.
7214 diffstat
7216 String. Statistics of changes with the following format: "modi‐
7217 fied files: +added/-removed lines"
7218 extras List of dicts with key, value entries of the 'extras' field of
7220 this changeset.
7221 file_adds
7223 List of strings. Files added by this changeset.
7224 file_copies
7226 List of strings. Files copied in this changeset with their
7227 sources.
7228 file_copies_switch
7230 List of strings. Like "file_copies" but displayed only if the
7231 --copied switch is set.
7232 file_dels
7234 List of strings. Files removed by this changeset.
7235 file_mods
7237 List of strings. Files modified by this changeset.
7238 files List of strings. All files modified, added, or removed by this
7240 changeset.
7241 graphnode
7243 String. The character representing the changeset node in an
7244 ASCII revision graph.
7245 graphwidth
7247 Integer. The width of the graph drawn by 'log --graph' or zero.
7248 index Integer. The current iteration of the loop. (0 indexed)
7250 latesttag
7252 List of strings. The global tags on the most recent globally
7253 tagged ancestor of this changeset. If no such tags exist, the
7254 list consists of the single string "null".
7255 latesttagdistance
7257 Integer. Longest path to the latest tag.
7258 namespaces
7260 Dict of lists. Names attached to this changeset per namespace.
7261 negrev Integer. The repository-local changeset negative revision num‐
7263 ber, which counts in the opposite direction.
7264 node String. The changeset identification hash, as a 40 hexadecimal
7266 digit string.
7267 p1 Changeset. The changeset's first parent. {p1.rev} for the revi‐
7269 sion number, and {p1.node} for the identification hash.
7270 p2 Changeset. The changeset's second parent. {p2.rev} for the revi‐
7272 sion number, and {p2.node} for the identification hash.
7273 parents
7275 List of strings. The parents of the changeset in "rev:node" for‐
7276 mat. If the changeset has only one "natural" parent (the prede‐
7277 cessor revision) nothing is shown.
7278 peerurls
7280 A dictionary of repository locations defined in the [paths] sec‐
7281 tion of your configuration file.
7282 phase String. The changeset phase name.
7284 reporoot
7286 String. The root directory of the current repository.
7287 rev Integer. The repository-local changeset revision number.
7289 subrepos
7291 List of strings. Updated subrepositories in the changeset.
7292 tags List of strings. Any tags associated with the changeset.
7294 termwidth
7296 Integer. The width of the current terminal.
7297 user String. The unmodified author of the changeset.
7299 verbosity
7301 String. The current output verbosity in 'debug', 'quiet', 'ver‐
7302 bose', or ''.
7303 The "date" keyword does not produce human-readable output. If you want
7305 to use a date in your output, you can use a filter to process it. Fil‐
7306 ters are functions which return a string based on the input variable.
7307 Be sure to use the stringify filter first when you're applying a
7308 string-input filter to a list-like input variable. You can also use a
7309 chain of filters to get the desired output:
7310 $ hg tip --template "{date|isodate}\n"
7312 2008-08-21 18:22 +0000
7313 Filters
7315 List of filters:
7316 addbreaks
7318 Any text. Add an XHTML "<br />" tag before the end of every line
7319 except the last.
7320 age Date. Returns a human-readable date/time difference between the
7322 given date/time and the current date/time.
7323 basename
7325 Any text. Treats the text as a path, and returns the last compo‐
7326 nent of the path after splitting by the path separator. For
7327 example, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
7328 cbor Any object. Serializes the object to CBOR bytes.
7330 commondir
7332 List of text. Treats each list item as file name with / as path
7333 separator and returns the longest common directory prefix shared
7334 by all list items. Returns the empty string if no common prefix
7335 exists.
7336 The list items are not normalized, i.e. "foo/../bar" is handled
7338 as file "bar" in the directory "foo/..". Leading slashes are
7339 ignored.
7340 For example, ["foo/bar/baz", "foo/baz/bar"] becomes "foo" and
7342 ["foo/bar", "baz"] becomes "".
7343 count List or text. Returns the length as an integer.
7345 dirname
7347 Any text. Treats the text as a path, and strips the last compo‐
7348 nent of the path after splitting by the path separator.
7349 domain Any text. Finds the first string that looks like an email
7351 address, and extracts just the domain component. Example: User
7352 <user@example.com> becomes example.com.
7353 email Any text. Extracts the first string that looks like an email
7355 address. Example: User <user@example.com> becomes user@exam‐
7356 ple.com.
7357 emailuser
7359 Any text. Returns the user portion of an email address.
7360 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
7362 ">" with XML entities, and filters out NUL characters.
7363 fill68 Any text. Wraps the text to fit in 68 columns.
7365 fill76 Any text. Wraps the text to fit in 76 columns.
7367 firstline
7369 Any text. Returns the first line of text.
7370 hex Any text. Convert a binary Mercurial node identifier into its
7372 long hexadecimal representation.
7373 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
7375 (Unix timestamp, timezone offset).
7376 isodate
7378 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
7379 +0200".
7380 isodatesec
7382 Date. Returns the date in ISO 8601 format, including seconds:
7383 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
7384 json Any object. Serializes the object to a JSON formatted text.
7386 lower Any text. Converts the text to lowercase.
7388 nonempty
7390 Any text. Returns '(none)' if the string is empty.
7391 obfuscate
7393 Any text. Returns the input text rendered as a sequence of XML
7394 entities.
7395 person Any text. Returns the name before an email address, interpreting
7397 it as per RFC 5322.
7398 revescape
7400 Any text. Escapes all "special" characters, except @. Forward
7401 slashes are escaped twice to prevent web servers from prema‐
7402 turely unescaping them. For example, "@foo bar/baz" becomes
7403 "@foo%20bar%252Fbaz".
7404 rfc3339date
7406 Date. Returns a date using the Internet date format specified in
7407 RFC 3339: "2009-08-18T13:00:13+02:00".
7408 rfc822date
7410 Date. Returns a date using the same format used in email head‐
7411 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
7412 short Changeset hash. Returns the short form of a changeset hash, i.e.
7414 a 12 hexadecimal digit string.
7415 shortbisect
7417 Any text. Treats label as a bisection status, and returns a sin‐
7418 gle-character representing the status (G: good, B: bad, S:
7419 skipped, U: untested, I: ignored). Returns single space if text
7420 is not a valid bisection status.
7421 shortdate
7423 Date. Returns a date like "2006-09-18".
7424 slashpath
7426 Any text. Replaces the native path separator with slash.
7427 splitlines
7429 Any text. Split text into a list of lines.
7430 stringify
7432 Any type. Turns the value into text by converting values into
7433 text and concatenating them.
7434 stripdir
7436 Treat the text as path and strip a directory level, if possible.
7437 For example, "foo" and "foo/bar" becomes "foo".
7438 tabindent
7440 Any text. Returns the text, with every non-empty line except the
7441 first starting with a tab character.
7442 upper Any text. Converts the text to uppercase.
7444 urlescape
7446 Any text. Escapes all "special" characters. For example, "foo
7447 bar" becomes "foo%20bar".
7448 user Any text. Returns a short representation of a user name or email
7450 address.
7451 utf8 Any text. Converts from the local character encoding to UTF-8.
7453 Note that a filter is nothing more than a function call, i.e.
7455 expr|filter is equivalent to filter(expr).
7456 Functions
7458 In addition to filters, there are some basic built-in functions:
7459 config(section, name[, default])
7461 Returns the requested hgrc config option as a string.
7462 configbool(section, name[, default])
7464 Returns the requested hgrc config option as a boolean.
7465 configint(section, name[, default])
7467 Returns the requested hgrc config option as an integer.
7468 date(date[, fmt])
7470 Format a date. See hg help dates for formatting strings. The
7471 default is a Unix date format, including the timezone: "Mon Sep
7472 04 15:13:13 2006 0700".
7473 dict([[key=]value...])
7475 Construct a dict from key-value pairs. A key may be omitted if a
7476 value expression can provide an unambiguous name.
7477 diff([includepattern [, excludepattern]])
7479 Show a diff, optionally specifying files to include or exclude.
7480 files(pattern)
7482 All files of the current changeset matching the pattern. See hg
7483 help patterns.
7484 fill(text[, width[, initialident[, hangindent]]])
7486 Fill many paragraphs with optional indentation. See the "fill"
7487 filter.
7488 filter(iterable[, expr])
7490 Remove empty elements from a list or a dict. If expr specified,
7491 it's applied to each element to test emptiness.
7492 get(dict, key)
7494 Get an attribute/key from an object. Some keywords are complex
7495 types. This function allows you to obtain the value of an
7496 attribute on these types.
7497 if(expr, then[, else])
7499 Conditionally execute based on the result of an expression.
7500 ifcontains(needle, haystack, then[, else])
7502 Conditionally execute based on whether the item "needle" is in
7503 "haystack".
7504 ifeq(expr1, expr2, then[, else])
7506 Conditionally execute based on whether 2 items are equivalent.
7507 indent(text, indentchars[, firstline])
7509 Indents all non-empty lines with the characters given in the
7510 indentchars string. An optional third parameter will override
7511 the indent for the first line only if present.
7512 join(list, sep)
7514 Join items in a list with a delimiter.
7515 label(label, expr)
7517 Apply a label to generated content. Content with a label applied
7518 can result in additional post-processing, such as automatic col‐
7519 orization.
7520 latesttag([pattern])
7522 The global tags matching the given pattern on the most recent
7523 globally tagged ancestor of this changeset. If no such tags
7524 exist, the "{tag}" template resolves to the string "null". See
7525 hg help revisions.patterns for the pattern syntax.
7526 localdate(date[, tz])
7528 Converts a date to the specified timezone. The default is local
7529 date.
7530 mailmap(author)
7532 Return the author, updated according to the value set in the
7533 .mailmap file
7534 max(iterable)
7536 Return the max of an iterable
7537 min(iterable)
7539 Return the min of an iterable
7540 mod(a, b)
7542 Calculate a mod b such that a / b + a mod b == a
7543 pad(text, width[, fillchar=' '[, left=False[, truncate=False]]])
7545 Pad text with a fill character.
7546 relpath(path)
7548 Convert a repository-absolute path into a filesystem path rela‐
7549 tive to the current working directory.
7550 revset(query[, formatargs...])
7552 Execute a revision set query. See hg help revset.
7553 rstdoc(text, style)
7555 Format reStructuredText.
7556 search(pattern, text)
7558 Look for the first text matching the regular expression pattern.
7559 Groups are accessible as {1}, {2}, ... in %-mapped template.
7560 separate(sep, args...)
7562 Add a separator between non-empty arguments.
7563 shortest(node, minlength=4)
7565 Obtain the shortest representation of a node.
7566 startswith(pattern, text)
7568 Returns the value from the "text" argument if it begins with the
7569 content from the "pattern" argument.
7570 strip(text[, chars])
7572 Strip characters from a string. By default, strips all leading
7573 and trailing whitespace.
7574 sub(pattern, replacement, expression)
7576 Perform text substitution using regular expressions.
7577 word(number, text[, separator])
7579 Return the nth word from a string.
7580 Operators
7582 We provide a limited set of infix arithmetic operations on integers:
7583 + for addition
7585 - for subtraction
7586 * for multiplication
7587 / for floor division (division rounded to integer nearest -infinity)
7588 Division fulfills the law x = x / y + mod(x, y).
7590 Also, for any expression that returns a list, there is a list operator:
7592 expr % "{template}"
7594 As seen in the above example, {template} is interpreted as a template.
7596 To prevent it from being interpreted, you can use an escape character
7597 \{ or a raw string prefix, r'...'.
7598 The dot operator can be used as a shorthand for accessing a sub item:
7600 · expr.member is roughly equivalent to expr % '{member}' if expr
7602 returns a non-list/dict. The returned value is not stringified.
7603 · dict.key is identical to get(dict, 'key').
7605 Aliases
7607 New keywords and functions can be defined in the templatealias section
7608 of a Mercurial configuration file:
7609 <alias> = <definition>
7611 Arguments of the form a1, a2, etc. are substituted from the alias into
7613 the definition.
7614 For example,
7616 [templatealias]
7618 r = rev
7619 rn = "{r}:{node|short}"
7620 leftpad(s, w) = pad(s, w, ' ', True)
7621 defines two symbol aliases, r and rn, and a function alias leftpad().
7623 It's also possible to specify complete template strings, using the tem‐
7625 plates section. The syntax used is the general template string syntax.
7626 For example,
7628 [templates]
7630 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
7631 defines a template, nodedate, which can be called like:
7633 $ hg log -r . -Tnodedate
7635 A template defined in templates section can also be referenced from
7637 another template:
7638 $ hg log -r . -T "{rev} {nodedate}"
7640 but be aware that the keywords cannot be overridden by templates. For
7642 example, a template defined as templates.rev cannot be referenced as
7643 {rev}.
7644 A template defined in templates section may have sub templates which
7646 are inserted before/after/between items:
7647 [templates]
7649 myjson = ' {dict(rev, node|short)|json}'
7650 myjson:docheader = '\{\n'
7651 myjson:docfooter = '\n}\n'
7652 myjson:separator = ',\n'
7653 Examples
7655 Some sample command line templates:
7656 · Format lists, e.g. files:
7658 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
7660 · Join the list of files with a ", ":
7662 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
7664 · Join the list of files ending with ".py" with a ", ":
7666 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
7668 · Separate non-empty arguments by a " ":
7670 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
7672 · Modify each line of a commit description:
7674 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
7676 · Format date:
7678 $ hg log -r 0 --template "{date(date, '%Y')}\n"
7680 · Display date in UTC:
7682 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
7684 · Output the description set to a fill-width of 30:
7686 $ hg log -r 0 --template "{fill(desc, 30)}"
7688 · Use a conditional to test for the default branch:
7690 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
7692 'on branch {branch}')}\n"
7693 · Append a newline if not empty:
7695 $ hg tip --template "{if(author, '{author}\n')}"
7697 · Label the output for use with the color extension:
7699 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
7701 · Invert the firstline filter, i.e. everything but the first line:
7703 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
7705 · Display the contents of the 'extra' field, one per line:
7707 $ hg log -r 0 --template "{join(extras, '\n')}\n"
7709 · Mark the active bookmark with '*':
7711 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
7713 · Find the previous release candidate tag, the distance and changes
7715 since the tag:
7716 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
7718 · Mark the working copy parent with '@':
7720 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
7722 · Show details of parent revisions:
7724 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
7726 · Show only commit descriptions that start with "template":
7728 $ hg log --template "{startswith('template', firstline(desc))}\n"
7730 · Print the first word of each line of a commit message:
7732 $ hg log --template "{word(0, desc)}\n"
7734
7736 Valid URLs are of the form:
7737 local/filesystem/path[#revision]
7739 file://local/filesystem/path[#revision]
7740 http://[user[:pass]@]host[:port]/[path][#revision]
7741 https://[user[:pass]@]host[:port]/[path][#revision]
7742 ssh://[user@]host[:port]/[path][#revision]
7743 Paths in the local filesystem can either point to Mercurial reposito‐
7745 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
7746 dle). See also hg help paths.
7747 An optional identifier after # indicates a particular branch, tag, or
7749 changeset to use from the remote repository. See also hg help revisions
7750 .
7751 Some features, such as pushing to http:// and https:// URLs are only
7753 possible if the feature is explicitly enabled on the remote Mercurial
7754 server.
7755 Note that the security of HTTPS URLs depends on proper configuration of
7757 web.cacerts.
7758 Some notes about using SSH with Mercurial:
7760 · SSH requires an accessible shell account on the destination machine
7762 and a copy of hg in the remote path or specified with remotecmd.
7763 · path is relative to the remote user's home directory by default. Use
7765 an extra slash at the start of a path to specify an absolute path:
7766 ssh://example.com//tmp/repository
7768 · Mercurial doesn't use its own compression via SSH; the right thing to
7770 do is to configure it in your ~/.ssh/config, e.g.:
7771 Host *.mylocalnetwork.example.com
7773 Compression no
7774 Host *
7775 Compression yes
7776 Alternatively specify "ssh -C" as your ssh command in your configura‐
7778 tion file or with the --ssh command line option.
7779 These URLs can all be stored in your configuration file with path
7781 aliases under the [paths] section like so:
7782 [paths]
7784 alias1 = URL1
7785 alias2 = URL2
7786 ...
7787 You can then use the alias for any command that uses a URL (for example
7789 hg pull alias1 will be treated as hg pull URL1).
7790 Two path aliases are special because they are used as defaults when you
7792 do not provide the URL to a command:
7793 default:
7795 When you create a repository with hg clone, the clone command
7796 saves the location of the source repository as the new reposi‐
7797 tory's 'default' path. This is then used when you omit path from
7798 push- and pull-like commands (including incoming and outgoing).
7799 default-push:
7801 The push command will look for a path named 'default-push', and
7802 prefer it over 'default' if both are defined.
7803
7805 This section contains help for extensions that are distributed together
7806 with Mercurial. Help for other extensions is available in the help sys‐
7807 tem.
7808 absorb
7810 apply working directory changes to changesets (EXPERIMENTAL)
7811 The absorb extension provides a command to use annotate information to
7813 amend modified chunks into the corresponding non-public changesets.
7814 [absorb]
7816 # only check 50 recent non-public changesets at most
7817 max-stack-size = 50
7818 # whether to add noise to new commits to avoid obsolescence cycle
7819 add-noise = 1
7820 # make `amend --correlated` a shortcut to the main command
7821 amend-flag = correlated
7822 [color]
7824 absorb.description = yellow
7825 absorb.node = blue bold
7826 absorb.path = bold
7827 Commands
7829 Change creation
7830 absorb
7831 incorporate corrections into the stack of draft changesets:
7832 hg absorb [OPTION] [FILE]...
7834 absorb analyzes each change in your working directory and attempts to
7836 amend the changed lines into the changesets in your stack that first
7837 introduced those lines.
7838 If absorb cannot find an unambiguous changeset to amend for a change,
7840 that change will be left in the working directory, untouched. They can
7841 be observed by hg status or hg diff afterwards. In other words, absorb
7842 does not write to the working directory.
7843 Changesets outside the revset ::. and not public() and not merge() will
7845 not be changed.
7846 Changesets that become empty after applying the changes will be
7848 deleted.
7849 By default, absorb will show what it plans to do and prompt for confir‐
7851 mation. If you are confident that the changes will be absorbed to the
7852 correct place, run hg absorb -a to apply the changes immediately.
7853 Returns 0 on success, 1 if all chunks were ignored and nothing amended.
7855 Options:
7857 -a, --apply-changes
7859 apply changes without prompting for confirmation
7860 -p, --print-changes
7862 always print which changesets are modified by which changes
7863 -i, --interactive
7865 interactively select which chunks to apply (EXPERIMENTAL)
7866 -e, --edit-lines
7868 edit what lines belong to which changesets before commit (EXPER‐
7869 IMENTAL)
7870 -n, --dry-run
7872 do not perform actions, just print output
7873 --style <STYLE>
7875 display using template map file (DEPRECATED)
7876 -T,--template <TEMPLATE>
7878 display with template
7879 -I,--include <PATTERN[+]>
7881 include names matching the given patterns
7882 -X,--exclude <PATTERN[+]>
7884 exclude names matching the given patterns
7885 [+] marked option can be specified multiple times
7887 acl
7889 hooks for controlling repository access
7890 This hook makes it possible to allow or deny write access to given
7892 branches and paths of a repository when receiving incoming changesets
7893 via pretxnchangegroup and pretxncommit.
7894 The authorization is matched based on the local user name on the system
7896 where the hook runs, and not the committer of the original changeset
7897 (since the latter is merely informative).
7898 The acl hook is best used along with a restricted shell like hgsh, pre‐
7900 venting authenticating users from doing anything other than pushing or
7901 pulling. The hook is not safe to use if users have interactive shell
7902 access, as they can then disable the hook. Nor is it safe if remote
7903 users share an account, because then there is no way to distinguish
7904 them.
7905 The order in which access checks are performed is:
7907 1. Deny list for branches (section acl.deny.branches)
7909 2. Allow list for branches (section acl.allow.branches)
7911 3. Deny list for paths (section acl.deny)
7913 4. Allow list for paths (section acl.allow)
7915 The allow and deny sections take key-value pairs.
7917 Branch-based Access Control
7919 Use the acl.deny.branches and acl.allow.branches sections to have
7920 branch-based access control. Keys in these sections can be either:
7921 · a branch name, or
7923 · an asterisk, to match any branch;
7925 The corresponding values can be either:
7927 · a comma-separated list containing users and groups, or
7929 · an asterisk, to match anyone;
7931 You can add the "!" prefix to a user or group name to invert the sense
7933 of the match.
7934 Path-based Access Control
7936 Use the acl.deny and acl.allow sections to have path-based access con‐
7937 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
7938 tax by default). The corresponding values follow the same syntax as the
7939 other sections above.
7940 Bookmark-based Access Control
7942 Use the acl.deny.bookmarks and acl.allow.bookmarks sections to have
7943 bookmark-based access control. Keys in these sections can be either:
7944 · a bookmark name, or
7946 · an asterisk, to match any bookmark;
7948 The corresponding values can be either:
7950 · a comma-separated list containing users and groups, or
7952 · an asterisk, to match anyone;
7954 You can add the "!" prefix to a user or group name to invert the sense
7956 of the match.
7957 Note: for interactions between clients and servers using Mercurial 3.6+
7959 a rejection will generally reject the entire push, for interactions
7960 involving older clients, the commit transactions will already be
7961 accepted, and only the bookmark movement will be rejected.
7962 Groups
7964 Group names must be prefixed with an @ symbol. Specifying a group name
7965 has the same effect as specifying all the users in that group.
7966 You can define group members in the acl.groups section. If a group
7968 name is not defined there, and Mercurial is running under a Unix-like
7969 system, the list of users will be taken from the OS. Otherwise, an
7970 exception will be raised.
7971 Example Configuration
7973 [hooks]
7974 # Use this if you want to check access restrictions at commit time
7976 pretxncommit.acl = python:hgext.acl.hook
7977 # Use this if you want to check access restrictions for pull, push,
7979 # bundle and serve.
7980 pretxnchangegroup.acl = python:hgext.acl.hook
7981 [acl]
7983 # Allow or deny access for incoming changes only if their source is
7984 # listed here, let them pass otherwise. Source is "serve" for all
7985 # remote access (http or ssh), "push", "pull" or "bundle" when the
7986 # related commands are run locally.
7987 # Default: serve
7988 sources = serve
7989 [acl.deny.branches]
7991 # Everyone is denied to the frozen branch:
7993 frozen-branch = *
7994 # A bad user is denied on all branches:
7996 * = bad-user
7997 [acl.allow.branches]
7999 # A few users are allowed on branch-a:
8001 branch-a = user-1, user-2, user-3
8002 # Only one user is allowed on branch-b:
8004 branch-b = user-1
8005 # The super user is allowed on any branch:
8007 * = super-user
8008 # Everyone is allowed on branch-for-tests:
8010 branch-for-tests = *
8011 [acl.deny]
8013 # This list is checked first. If a match is found, acl.allow is not
8014 # checked. All users are granted access if acl.deny is not present.
8015 # Format for both lists: glob pattern = user, ..., @group, ...
8016 # To match everyone, use an asterisk for the user:
8018 # my/glob/pattern = *
8019 # user6 will not have write access to any file:
8021 ** = user6
8022 # Group "hg-denied" will not have write access to any file:
8024 ** = @hg-denied
8025 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
8027 # everyone being able to change all other files. See below.
8028 src/main/resources/DONT-TOUCH-THIS.txt = *
8029 [acl.allow]
8031 # if acl.allow is not present, all users are allowed by default
8032 # empty acl.allow = no users allowed
8033 # User "doc_writer" has write access to any file under the "docs"
8035 # folder:
8036 docs/** = doc_writer
8037 # User "jack" and group "designers" have write access to any file
8039 # under the "images" folder:
8040 images/** = jack, @designers
8041 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
8043 # will have write access to any file under the "resources" folder
8044 # (except for 1 file. See acl.deny):
8045 src/main/resources/** = *
8046 .hgtags = release_engineer
8048 Examples using the ! prefix
8050 Suppose there's a branch that only a given user (or group) should be
8051 able to push to, and you don't want to restrict access to any other
8052 branch that may be created.
8053 The "!" prefix allows you to prevent anyone except a given user or
8055 group to push changesets in a given branch or path.
8056 In the examples below, we will: 1) Deny access to branch "ring" to any‐
8058 one but user "gollum" 2) Deny access to branch "lake" to anyone but
8059 members of the group "hobbit" 3) Deny access to a file to anyone but
8060 user "gollum"
8061 [acl.allow.branches]
8063 # Empty
8064 [acl.deny.branches]
8066 # 1) only 'gollum' can commit to branch 'ring';
8068 # 'gollum' and anyone else can still commit to any other branch.
8069 ring = !gollum
8070 # 2) only members of the group 'hobbit' can commit to branch 'lake';
8072 # 'hobbit' members and anyone else can still commit to any other branch.
8073 lake = !@hobbit
8074 # You can also deny access based on file paths:
8076 [acl.allow]
8078 # Empty
8079 [acl.deny]
8081 # 3) only 'gollum' can change the file below;
8082 # 'gollum' and anyone else can still change any other file.
8083 /misty/mountains/cave/ring = !gollum
8084 amend
8086 provide the amend command (EXPERIMENTAL)
8087 This extension provides an amend command that is similar to commit
8089 --amend but does not prompt an editor.
8090 Commands
8092 Change creation
8093 amend
8094 amend the working copy parent with all or specified outstanding
8095 changes:
8096 hg amend [OPTION]... [FILE]...
8098 Similar to hg commit --amend, but reuse the commit message without
8100 invoking editor, unless --edit was set.
8101 See hg help commit for more details.
8103 Options:
8105 -A, --addremove
8107 mark new/missing files as added/removed before committing
8108 -e, --edit
8110 invoke editor on commit messages
8111 -i, --interactive
8113 use interactive mode
8114 --close-branch
8116 mark a branch as closed, hiding it from the branch list
8117 -s, --secret
8119 use the secret phase for committing
8120 -n,--note <VALUE>
8122 store a note on the amend
8123 -I,--include <PATTERN[+]>
8125 include names matching the given patterns
8126 -X,--exclude <PATTERN[+]>
8128 exclude names matching the given patterns
8129 -m,--message <TEXT>
8131 use text as commit message
8132 -l,--logfile <FILE>
8134 read commit message from file
8135 -d,--date <DATE>
8137 record the specified date as commit date
8138 -u,--user <USER>
8140 record the specified user as committer
8141 -D, --currentdate
8143 record the current date as commit date
8144 -U, --currentuser
8146 record the current user as committer
8147 [+] marked option can be specified multiple times
8149 automv
8151 check for unrecorded moves at commit time (EXPERIMENTAL)
8152 This extension checks at commit/amend time if any of the committed
8154 files comes from an unrecorded mv.
8155 The threshold at which a file is considered a move can be set with the
8157 automv.similarity config option. This option takes a percentage between
8158 0 (disabled) and 100 (files must be identical), the default is 95.
8159 beautifygraph
8161 beautify log -G output by using Unicode characters (EXPERIMENTAL)
8162 A terminal with UTF-8 support and monospace narrow text are
8164 required.
8165 blackbox
8167 log repository events to a blackbox for debugging
8168 Logs event information to .hg/blackbox.log to help debug and diagnose
8170 problems. The events that get logged can be configured via the black‐
8171 box.track and blackbox.ignore config keys.
8172 Examples:
8174 [blackbox]
8176 track = *
8177 ignore = pythonhook
8178 # dirty is *EXPENSIVE* (slow);
8179 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
8180 dirty = True
8181 # record the source of log messages
8182 logsource = True
8183 [blackbox]
8185 track = command, commandfinish, commandexception, exthook, pythonhook
8186 [blackbox]
8188 track = incoming
8189 [blackbox]
8191 # limit the size of a log file
8192 maxsize = 1.5 MB
8193 # rotate up to N log files when the current one gets too big
8194 maxfiles = 3
8195 [blackbox]
8197 # Include nanoseconds in log entries with %f (see Python function
8198 # datetime.datetime.strftime)
8199 date-format = '%Y-%m-%d @ %H:%M:%S.%f'
8200 Commands
8202 Repository maintenance
8203 blackbox
8204 view the recent repository events:
8205 hg blackbox [OPTION]...
8207 view the recent repository events
8209 Options:
8211 -l,--limit <VALUE>
8213 the number of events to show (default: )
8214 bookflow
8216 implements bookmark-based branching (EXPERIMENTAL)
8217 · Disables creation of new branches (config: enable_branches=False).
8219 · Requires an active bookmark on commit (config: require_book‐
8221 mark=True).
8222 · Doesn't move the active bookmark on update, only on commit.
8224 · Requires '--rev' for moving an existing bookmark.
8226 · Protects special bookmarks (config: protect=@).
8228 flow related commands
8230 hg book NAME
8232 create a new bookmark
8233 hg book NAME -r REV
8235 move bookmark to revision (fast-forward)
8236 hg up|co NAME
8238 switch to bookmark
8239 hg push -B .
8241 push active bookmark
8242 bugzilla
8244 hooks for integrating with the Bugzilla bug tracker
8245 This hook extension adds comments on bugs in Bugzilla when changesets
8247 that refer to bugs by Bugzilla ID are seen. The comment is formatted
8248 using the Mercurial template mechanism.
8249 The bug references can optionally include an update for Bugzilla of the
8251 hours spent working on the bug. Bugs can also be marked fixed.
8252 Four basic modes of access to Bugzilla are provided:
8254 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
8256 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
8258 later.
8259 3. Check data via the Bugzilla XMLRPC interface and submit bug change
8261 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
8262 later.
8263 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
8265 tions using MySQL are supported. Requires Python MySQLdb.
8266 Writing directly to the database is susceptible to schema changes, and
8268 relies on a Bugzilla contrib script to send out bug change notification
8269 emails. This script runs as the user running Mercurial, must be run on
8270 the host with the Bugzilla install, and requires permission to read
8271 Bugzilla configuration details and the necessary MySQL user and pass‐
8272 word to have full access rights to the Bugzilla database. For these
8273 reasons this access mode is now considered deprecated, and will not be
8274 updated for new Bugzilla versions going forward. Only adding comments
8275 is supported in this access mode.
8276 Access via XMLRPC needs a Bugzilla username and password to be speci‐
8278 fied in the configuration. Comments are added under that username.
8279 Since the configuration must be readable by all Mercurial users, it is
8280 recommended that the rights of that user are restricted in Bugzilla to
8281 the minimum necessary to add comments. Marking bugs fixed requires
8282 Bugzilla 4.0 and later.
8283 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
8285 to the Bugzilla email interface to submit comments to bugs. The From:
8286 address in the email is set to the email address of the Mercurial user,
8287 so the comment appears to come from the Mercurial user. In the event
8288 that the Mercurial user email is not recognized by Bugzilla as a
8289 Bugzilla user, the email associated with the Bugzilla username used to
8290 log into Bugzilla is used instead as the source of the comment. Marking
8291 bugs fixed works on all supported Bugzilla versions.
8292 Access via the REST-API needs either a Bugzilla username and password
8294 or an apikey specified in the configuration. Comments are made under
8295 the given username or the user associated with the apikey in Bugzilla.
8296 Configuration items common to all access modes:
8298 bugzilla.version
8300 The access type to use. Values recognized are:
8301 restapi
8303 Bugzilla REST-API, Bugzilla 5.0 and later.
8305 xmlrpc
8307 Bugzilla XMLRPC interface.
8309 xmlrpc+email
8311 Bugzilla XMLRPC and email interfaces.
8313 3.0
8315 MySQL access, Bugzilla 3.0 and later.
8317 2.18
8319 MySQL access, Bugzilla 2.18 and up to but not including
8321 3.0.
8322 2.16
8324 MySQL access, Bugzilla 2.16 and up to but not including
8326 2.18.
8327 bugzilla.regexp
8329 Regular expression to match bug IDs for update in changeset com‐
8330 mit message. It must contain one "()" named group <ids> con‐
8331 taining the bug IDs separated by non-digit characters. It may
8332 also contain a named group <hours> with a floating-point number
8333 giving the hours worked on the bug. If no named groups are
8334 present, the first "()" group is assumed to contain the bug IDs,
8335 and work time is not updated. The default expression matches Bug
8336 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
8337 and 5678 and variations thereof, followed by an hours number
8338 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
8339 sitive.
8340 bugzilla.fixregexp
8342 Regular expression to match bug IDs for marking fixed in change‐
8343 set commit message. This must contain a "()" named group <ids>`
8344 containing the bug IDs separated by non-digit characters. It may
8345 also contain a named group ``<hours> with a floating-point num‐
8346 ber giving the hours worked on the bug. If no named groups are
8347 present, the first "()" group is assumed to contain the bug IDs,
8348 and work time is not updated. The default expression matches
8349 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
8350 5678 and variations thereof, followed by an hours number pre‐
8351 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
8352 tive.
8353 bugzilla.fixstatus
8355 The status to set a bug to when marking fixed. Default RESOLVED.
8356 bugzilla.fixresolution
8358 The resolution to set a bug to when marking fixed. Default
8359 FIXED.
8360 bugzilla.style
8362 The style file to use when formatting comments.
8363 bugzilla.template
8365 Template to use when formatting comments. Overrides style if
8366 specified. In addition to the usual Mercurial keywords, the
8367 extension specifies:
8368 {bug}
8370 The Bugzilla bug ID.
8372 {root}
8374 The full pathname of the Mercurial repository.
8376 {webroot}
8378 Stripped pathname of the Mercurial repository.
8380 {hgweb}
8382 Base URL for browsing Mercurial repositories.
8384 Default changeset {node|short} in repo {root} refers to bug
8386 {bug}.\ndetails:\n\t{desc|tabindent}
8387 bugzilla.strip
8389 The number of path separator characters to strip from the front
8390 of the Mercurial repository path ({root} in templates) to pro‐
8391 duce {webroot}. For example, a repository with {root}
8392 /var/local/my-project with a strip of 2 gives a value for {web‐
8393 root} of my-project. Default 0.
8394 web.baseurl
8396 Base URL for browsing Mercurial repositories. Referenced from
8397 templates as {hgweb}.
8398 Configuration items common to XMLRPC+email and MySQL access modes:
8400 bugzilla.usermap
8402 Path of file containing Mercurial committer email to Bugzilla
8403 user email mappings. If specified, the file should contain one
8404 mapping per line:
8405 committer = Bugzilla user
8407 See also the [usermap] section.
8409 The [usermap] section is used to specify mappings of Mercurial commit‐
8411 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
8412 entries of the form committer = Bugzilla user.
8413 XMLRPC and REST-API access mode configuration:
8415 bugzilla.bzurl
8417 The base URL for the Bugzilla installation. Default
8418 http://localhost/bugzilla.
8419 bugzilla.user
8421 The username to use to log into Bugzilla via XMLRPC. Default
8422 bugs.
8423 bugzilla.password
8425 The password for Bugzilla login.
8426 REST-API access mode uses the options listed above as well as:
8428 bugzilla.apikey
8430 An apikey generated on the Bugzilla instance for api access.
8431 Using an apikey removes the need to store the user and password
8432 options.
8433 XMLRPC+email access mode uses the XMLRPC access mode configuration
8435 items, and also:
8436 bugzilla.bzemail
8438 The Bugzilla email address.
8439 In addition, the Mercurial email settings must be configured. See the
8441 documentation in hgrc(5), sections [email] and [smtp].
8442 MySQL access mode configuration:
8444 bugzilla.host
8446 Hostname of the MySQL server holding the Bugzilla database.
8447 Default localhost.
8448 bugzilla.db
8450 Name of the Bugzilla database in MySQL. Default bugs.
8451 bugzilla.user
8453 Username to use to access MySQL server. Default bugs.
8454 bugzilla.password
8456 Password to use to access MySQL server.
8457 bugzilla.timeout
8459 Database connection timeout (seconds). Default 5.
8460 bugzilla.bzuser
8462 Fallback Bugzilla user name to record comments with, if change‐
8463 set committer cannot be found as a Bugzilla user.
8464 bugzilla.bzdir
8466 Bugzilla install directory. Used by default notify. Default
8467 /var/www/html/bugzilla.
8468 bugzilla.notify
8470 The command to run to get Bugzilla to send bug change notifica‐
8471 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
8472 id) and user (committer bugzilla email). Default depends on ver‐
8473 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
8474 mail.pl %(id)s %(user)s".
8475 Activating the extension:
8477 [extensions]
8479 bugzilla =
8480 [hooks]
8482 # run bugzilla hook on every change pulled or pushed in here
8483 incoming.bugzilla = python:hgext.bugzilla.hook
8484 Example configurations:
8486 XMLRPC example configuration. This uses the Bugzilla at
8488 http://my-project.org/bugzilla, logging in as user bug‐
8489 mail@my-project.org with password plugh. It is used with a collection
8490 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8491 at http://my-project.org/hg.
8492 [bugzilla]
8494 bzurl=http://my-project.org/bugzilla
8495 user=bugmail@my-project.org
8496 password=plugh
8497 version=xmlrpc
8498 template=Changeset {node|short} in {root|basename}.
8499 {hgweb}/{webroot}/rev/{node|short}\n
8500 {desc}\n
8501 strip=5
8502 [web]
8504 baseurl=http://my-project.org/hg
8505 XMLRPC+email example configuration. This uses the Bugzilla at
8507 http://my-project.org/bugzilla, logging in as user bug‐
8508 mail@my-project.org with password plugh. It is used with a collection
8509 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8510 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
8511 email address bugzilla@my-project.org.
8512 [bugzilla]
8514 bzurl=http://my-project.org/bugzilla
8515 user=bugmail@my-project.org
8516 password=plugh
8517 version=xmlrpc+email
8518 bzemail=bugzilla@my-project.org
8519 template=Changeset {node|short} in {root|basename}.
8520 {hgweb}/{webroot}/rev/{node|short}\n
8521 {desc}\n
8522 strip=5
8523 [web]
8525 baseurl=http://my-project.org/hg
8526 [usermap]
8528 user@emaildomain.com=user.name@bugzilladomain.com
8529 MySQL example configuration. This has a local Bugzilla 3.2 installation
8531 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
8532 database name is bugs and MySQL is accessed with MySQL username bugs
8533 password XYZZY. It is used with a collection of Mercurial repositories
8534 in /var/local/hg/repos/, with a web interface at
8535 http://my-project.org/hg.
8536 [bugzilla]
8538 host=localhost
8539 password=XYZZY
8540 version=3.0
8541 bzuser=unknown@domain.com
8542 bzdir=/opt/bugzilla-3.2
8543 template=Changeset {node|short} in {root|basename}.
8544 {hgweb}/{webroot}/rev/{node|short}\n
8545 {desc}\n
8546 strip=5
8547 [web]
8549 baseurl=http://my-project.org/hg
8550 [usermap]
8552 user@emaildomain.com=user.name@bugzilladomain.com
8553 All the above add a comment to the Bugzilla bug record of the form:
8555 Changeset 3b16791d6642 in repository-name.
8557 http://my-project.org/hg/repository-name/rev/3b16791d6642
8558 Changeset commit comment. Bug 1234.
8560 censor
8562 erase file content at a given revision
8563 The censor command instructs Mercurial to erase all content of a file
8565 at a given revision without updating the changeset hash. This allows
8566 existing history to remain valid while preventing future clones/pulls
8567 from receiving the erased data.
8568 Typical uses for censor are due to security or legal requirements,
8570 including:
8571 * Passwords, private keys, cryptographic material
8573 * Licensed data/code/libraries for which the license has expired
8574 * Personally Identifiable Information or other private data
8575 Censored nodes can interrupt mercurial's typical operation whenever the
8577 excised data needs to be materialized. Some commands, like hg cat/hg
8578 revert, simply fail when asked to produce censored data. Others, like
8579 hg verify and hg update, must be capable of tolerating censored data to
8580 continue to function in a meaningful way. Such commands only tolerate
8581 censored file revisions if they are allowed by the "censor.pol‐
8582 icy=ignore" config option.
8583 Commands
8585 Repository maintenance
8586 censor
8587 hg censor -r REV [-t TEXT] [FILE]
8588 Options:
8590 -r,--rev <REV>
8592 censor file from specified revision
8593 -t,--tombstone <TEXT>
8595 replacement tombstone data
8596 children
8598 command to display child changesets (DEPRECATED)
8599 This extension is deprecated. You should use hg log -r "children(REV)"
8601 instead.
8602 Commands
8604 Change navigation
8605 children
8606 show the children of the given or working directory revision:
8607 hg children [-r REV] [FILE]
8609 Print the children of the working directory's revisions. If a revision
8611 is given via -r/--rev, the children of that revision will be printed.
8612 If a file argument is given, revision in which the file was last
8613 changed (after the working directory revision or the argument to --rev
8614 if given) is printed.
8615 Please use hg log instead:
8617 hg children => hg log -r "children(.)"
8619 hg children -r REV => hg log -r "children(REV)"
8620 See hg help log and hg help revsets.children.
8622 Options:
8624 -r,--rev <REV>
8626 show children of the specified revision (default: .)
8627 --style <STYLE>
8629 display using template map file (DEPRECATED)
8630 -T,--template <TEMPLATE>
8632 display with template
8633 churn
8635 command to display statistics about repository history
8636 Commands
8638 Repository maintenance
8639 churn
8640 histogram of changes to the repository:
8641 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
8643 This command will display a histogram representing the number of
8645 changed lines or revisions, grouped according to the given template.
8646 The default template will group changes by author. The --dateformat
8647 option may be used to group the results by date instead.
8648 Statistics are based on the number of changed lines, or alternatively
8650 the number of matching revisions if the --changesets option is speci‐
8651 fied.
8652 Examples:
8654 # display count of changed lines for every committer
8656 hg churn -T "{author|email}"
8657 # display daily activity graph
8659 hg churn -f "%H" -s -c
8660 # display activity of developers by month
8662 hg churn -f "%Y-%m" -s -c
8663 # display count of lines changed in every year
8665 hg churn -f "%Y" -s
8666 It is possible to map alternate email addresses to a main address by
8668 providing a file using the following format:
8669 <alias email> = <actual email>
8671 Such a file may be specified with the --aliases option, otherwise a
8673 .hgchurn file will be looked for in the working directory root.
8674 Aliases will be split from the rightmost "=".
8675 Options:
8677 -r,--rev <REV[+]>
8679 count rate for the specified revision or revset
8680 -d,--date <DATE>
8682 count rate for revisions matching date spec
8683 -t,--oldtemplate <TEMPLATE>
8685 template to group changesets (DEPRECATED)
8686 -T,--template <TEMPLATE>
8688 template to group changesets (default: {author|email})
8689 -f,--dateformat <FORMAT>
8691 strftime-compatible format for grouping by date
8692 -c, --changesets
8694 count rate by number of changesets
8695 -s, --sort
8697 sort by key (default: sort by count)
8698 --diffstat
8700 display added/removed lines separately
8701 --aliases <FILE>
8703 file with email aliases
8704 -I,--include <PATTERN[+]>
8706 include names matching the given patterns
8707 -X,--exclude <PATTERN[+]>
8709 exclude names matching the given patterns
8710 [+] marked option can be specified multiple times
8712 clonebundles
8714 advertise pre-generated bundles to seed clones
8715 "clonebundles" is a server-side extension used to advertise the exis‐
8717 tence of pre-generated, externally hosted bundle files to clients that
8718 are cloning so that cloning can be faster, more reliable, and require
8719 less resources on the server. "pullbundles" is a related feature for
8720 sending pre-generated bundle files to clients as part of pull opera‐
8721 tions.
8722 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
8724 ally, the server, in response to a client's request to clone, dynami‐
8725 cally generates a bundle containing the entire repository content and
8726 sends it to the client. There is no caching on the server and the
8727 server will have to redundantly generate the same outgoing bundle in
8728 response to each clone request. For servers with large repositories or
8729 with high clone volume, the load from clones can make scaling the
8730 server challenging and costly.
8731 This extension provides server operators the ability to offload poten‐
8733 tially expensive clone load to an external service. Pre-generated bun‐
8734 dles also allow using more CPU intensive compression, reducing the
8735 effective bandwidth requirements.
8736 Here's how clone bundles work:
8738 1. A server operator establishes a mechanism for making bundle files
8740 available on a hosting service where Mercurial clients can fetch
8741 them.
8742 2. A manifest file listing available bundle URLs and some optional
8744 metadata is added to the Mercurial repository on the server.
8745 3. A client initiates a clone against a clone bundles aware server.
8747 4. The client sees the server is advertising clone bundles and fetches
8749 the manifest listing available bundles.
8750 5. The client filters and sorts the available bundles based on what it
8752 supports and prefers.
8753 6. The client downloads and applies an available bundle from the
8755 server-specified URL.
8756 7. The client reconnects to the original server and performs the equiv‐
8758 alent of hg pull to retrieve all repository data not in the bundle.
8759 (The repository could have been updated between when the bundle was
8760 created and when the client started the clone.) This may use "pull‐
8761 bundles".
8762 Instead of the server generating full repository bundles for every
8764 clone request, it generates full bundles once and they are subsequently
8765 reused to bootstrap new clones. The server may still transfer data at
8766 clone time. However, this is only data that has been added/changed
8767 since the bundle was created. For large, established repositories, this
8768 can reduce server load for clones to less than 1% of original.
8769 Here's how pullbundles work:
8771 1. A manifest file listing available bundles and describing the revi‐
8773 sions is added to the Mercurial repository on the server.
8774 2. A new-enough client informs the server that it supports partial
8776 pulls and initiates a pull.
8777 3. If the server has pull bundles enabled and sees the client advertis‐
8779 ing partial pulls, it checks for a matching pull bundle in the mani‐
8780 fest. A bundle matches if the format is supported by the client,
8781 the client has the required revisions already and needs something
8782 from the bundle.
8783 4. If there is at least one matching bundle, the server sends it to the
8785 client.
8786 5. The client applies the bundle and notices that the server reply was
8788 incomplete. It initiates another pull.
8789 To work, this extension requires the following of server operators:
8791 · Generating bundle files of repository content (typically periodi‐
8793 cally, such as once per day).
8794 · Clone bundles: A file server that clients have network access to and
8796 that Python knows how to talk to through its normal URL handling
8797 facility (typically an HTTP/HTTPS server).
8798 · A process for keeping the bundles manifest in sync with available
8800 bundle files.
8801 Strictly speaking, using a static file hosting server isn't required: a
8803 server operator could use a dynamic service for retrieving bundle data.
8804 However, static file hosting services are simple and scalable and
8805 should be sufficient for most needs.
8806 Bundle files can be generated with the hg bundle command. Typically hg
8808 bundle --all is used to produce a bundle of the entire repository.
8809 hg debugcreatestreamclonebundle can be used to produce a special
8811 streaming clonebundle. These are bundle files that are extremely effi‐
8812 cient to produce and consume (read: fast). However, they are larger
8813 than traditional bundle formats and require that clients support the
8814 exact set of repository data store formats in use by the repository
8815 that created them. Typically, a newer server can serve data that is
8816 compatible with older clients. However, streaming clone bundles don't
8817 have this guarantee. Server operators need to be aware that newer ver‐
8818 sions of Mercurial may produce streaming clone bundles incompatible
8819 with older Mercurial versions.
8820 A server operator is responsible for creating a .hg/clonebundles.mani‐
8822 fest file containing the list of available bundle files suitable for
8823 seeding clones. If this file does not exist, the repository will not
8824 advertise the existence of clone bundles when clients connect. For pull
8825 bundles, .hg/pullbundles.manifest is used.
8826 The manifest file contains a newline (n) delimited list of entries.
8828 Each line in this file defines an available bundle. Lines have the for‐
8830 mat:
8831 <URL> [<key>=<value>[ <key>=<value>]]
8833 That is, a URL followed by an optional, space-delimited list of
8835 key=value pairs describing additional properties of this bundle. Both
8836 keys and values are URI encoded.
8837 For pull bundles, the URL is a path under the .hg directory of the
8839 repository.
8840 Keys in UPPERCASE are reserved for use by Mercurial and are defined
8842 below. All non-uppercase keys can be used by site installations. An
8843 example use for custom properties is to use the datacenter attribute to
8844 define which data center a file is hosted in. Clients could then prefer
8845 a server in the data center closest to them.
8846 The following reserved keys are currently defined:
8848 BUNDLESPEC
8850 A "bundle specification" string that describes the type of the
8851 bundle.
8852 These are string values that are accepted by the "--type" argu‐
8854 ment of hg bundle.
8855 The values are parsed in strict mode, which means they must be
8857 of the "<compression>-<type>" form. See mercu‐
8858 rial.exchange.parsebundlespec() for more details.
8859 hg debugbundle --spec can be used to print the bundle specifica‐
8861 tion string for a bundle file. The output of this command can be
8862 used verbatim for the value of BUNDLESPEC (it is already
8863 escaped).
8864 Clients will automatically filter out specifications that are
8866 unknown or unsupported so they won't attempt to download some‐
8867 thing that likely won't apply.
8868 The actual value doesn't impact client behavior beyond filter‐
8870 ing: clients will still sniff the bundle type from the header of
8871 downloaded files.
8872 Use of this key is highly recommended, as it allows clients to
8874 easily skip unsupported bundles. If this key is not defined, an
8875 old client may attempt to apply a bundle that it is incapable of
8876 reading.
8877 REQUIRESNI
8879 Whether Server Name Indication (SNI) is required to connect to
8880 the URL. SNI allows servers to use multiple certificates on the
8881 same IP. It is somewhat common in CDNs and other hosting
8882 providers. Older Python versions do not support SNI. Defining
8883 this attribute enables clients with older Python versions to
8884 filter this entry without experiencing an opaque SSL failure at
8885 connection time.
8886 If this is defined, it is important to advertise a non-SNI fall‐
8888 back URL or clients running old Python releases may not be able
8889 to clone with the clonebundles facility.
8890 Value should be "true".
8892 heads Used for pull bundles. This contains the ; separated changeset
8894 hashes of the heads of the bundle content.
8895 bases Used for pull bundles. This contains the ; separated changeset
8897 hashes of the roots of the bundle content. This can be skipped
8898 if the bundle was created without --base.
8899 Manifests can contain multiple entries. Assuming metadata is defined,
8901 clients will filter entries from the manifest that they don't support.
8902 The remaining entries are optionally sorted by client preferences
8903 (ui.clonebundleprefers config option). The client then attempts to
8904 fetch the bundle at the first URL in the remaining list.
8905 Errors when downloading a bundle will fail the entire clone operation:
8907 clients do not automatically fall back to a traditional clone. The rea‐
8908 son for this is that if a server is using clone bundles, it is probably
8909 doing so because the feature is necessary to help it scale. In other
8910 words, there is an assumption that clone load will be offloaded to
8911 another service and that the Mercurial server isn't responsible for
8912 serving this clone load. If that other service experiences issues and
8913 clients start mass falling back to the original Mercurial server, the
8914 added clone load could overwhelm the server due to unexpected load and
8915 effectively take it offline. Not having clients automatically fall back
8916 to cloning from the original server mitigates this scenario.
8917 Because there is no automatic Mercurial server fallback on failure of
8919 the bundle hosting service, it is important for server operators to
8920 view the bundle hosting service as an extension of the Mercurial server
8921 in terms of availability and service level agreements: if the bundle
8922 hosting service goes down, so does the ability for clients to clone.
8923 Note: clients will see a message informing them how to bypass the clone
8924 bundles facility when a failure occurs. So server operators should pre‐
8925 pare for some people to follow these instructions when a failure
8926 occurs, thus driving more load to the original Mercurial server when
8927 the bundle hosting service fails.
8928 closehead
8930 close arbitrary heads without checking them out first
8931 Commands
8933 Change manipulation
8934 close-head
8935 close the given head revisions:
8936 hg close-head [OPTION]... [REV]...
8938 This is equivalent to checking out each revision in a clean tree and
8940 running hg commit --close-branch, except that it doesn't change the
8941 working directory.
8942 The commit message must be specified with -l or -m.
8944 Options:
8946 -m,--message <TEXT>
8948 use text as commit message
8949 -l,--logfile <FILE>
8951 read commit message from file
8952 -d,--date <DATE>
8954 record the specified date as commit date
8955 -u,--user <USER>
8957 record the specified user as committer
8958 -r,--rev <REV[+]>
8960 revision to check
8961 [+] marked option can be specified multiple times
8963 aliases: close-heads
8965 commitextras
8967 adds a new flag extras to commit (ADVANCED)
8968 convert
8970 import revisions from foreign VCS repositories into Mercurial
8971 Commands
8973 Uncategorized commands
8974 convert
8975 convert a foreign SCM repository to a Mercurial one.:
8976 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
8978 Accepted source formats [identifiers]:
8980 · Mercurial [hg]
8982 · CVS [cvs]
8984 · Darcs [darcs]
8986 · git [git]
8988 · Subversion [svn]
8990 · Monotone [mtn]
8992 · GNU Arch [gnuarch]
8994 · Bazaar [bzr]
8996 · Perforce [p4]
8998 Accepted destination formats [identifiers]:
9000 · Mercurial [hg]
9002 · Subversion [svn] (history on branches is not preserved)
9004 If no revision is given, all revisions will be converted. Otherwise,
9006 convert will only import up to the named revision (given in a format
9007 understood by the source).
9008 If no destination directory name is specified, it defaults to the base‐
9010 name of the source with -hg appended. If the destination repository
9011 doesn't exist, it will be created.
9012 By default, all sources except Mercurial will use --branchsort. Mercu‐
9014 rial uses --sourcesort to preserve original revision numbers order.
9015 Sort modes have the following effects:
9016 --branchsort
9018 convert from parent to child revision when possible, which means
9019 branches are usually converted one after the other. It generates
9020 more compact repositories.
9021 --datesort
9023 sort revisions by date. Converted repositories have good-looking
9024 changelogs but are often an order of magnitude larger than the
9025 same ones generated by --branchsort.
9026 --sourcesort
9028 try to preserve source revisions order, only supported by Mercu‐
9029 rial sources.
9030 --closesort
9032 try to move closed revisions as close as possible to parent
9033 branches, only supported by Mercurial sources.
9034 If REVMAP isn't given, it will be put in a default location
9036 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
9037 maps each source commit ID to the destination ID for that revision,
9038 like so:
9039 <source ID> <destination ID>
9041 If the file doesn't exist, it's automatically created. It's updated on
9043 each commit copied, so hg convert can be interrupted and can be run
9044 repeatedly to copy new commits.
9045 The authormap is a simple text file that maps each source commit author
9047 to a destination commit author. It is handy for source SCMs that use
9048 unix logins to identify authors (e.g.: CVS). One line per author map‐
9049 ping and the line format is:
9050 source author = destination author
9052 Empty lines and lines starting with a # are ignored.
9054 The filemap is a file that allows filtering and remapping of files and
9056 directories. Each line can contain one of the following directives:
9057 include path/to/file-or-dir
9059 exclude path/to/file-or-dir
9061 rename path/to/source path/to/destination
9063 Comment lines start with #. A specified path matches if it equals the
9065 full relative name of a file or one of its parent directories. The
9066 include or exclude directive with the longest matching path applies, so
9067 line order does not matter.
9068 The include directive causes a file, or all files under a directory, to
9070 be included in the destination repository. The default if there are no
9071 include statements is to include everything. If there are any include
9072 statements, nothing else is included. The exclude directive causes
9073 files or directories to be omitted. The rename directive renames a file
9074 or directory if it is converted. To rename from a subdirectory into the
9075 root of the repository, use . as the path to rename to.
9076 --full will make sure the converted changesets contain exactly the
9078 right files with the right content. It will make a full conversion of
9079 all files, not just the ones that have changed. Files that already are
9080 correct will not be changed. This can be used to apply filemap changes
9081 when converting incrementally. This is currently only supported for
9082 Mercurial and Subversion.
9083 The splicemap is a file that allows insertion of synthetic history,
9085 letting you specify the parents of a revision. This is useful if you
9086 want to e.g. give a Subversion merge two parents, or graft two discon‐
9087 nected series of history together. Each entry contains a key, followed
9088 by a space, followed by one or two comma-separated values:
9089 key parent1, parent2
9091 The key is the revision ID in the source revision control system whose
9093 parents should be modified (same format as a key in .hg/shamap). The
9094 values are the revision IDs (in either the source or destination revi‐
9095 sion control system) that should be used as the new parents for that
9096 node. For example, if you have merged "release-1.0" into "trunk", then
9097 you should specify the revision on "trunk" as the first parent and the
9098 one on the "release-1.0" branch as the second.
9099 The branchmap is a file that allows you to rename a branch when it is
9101 being brought in from whatever external repository. When used in con‐
9102 junction with a splicemap, it allows for a powerful combination to help
9103 fix even the most badly mismanaged repositories and turn them into
9104 nicely structured Mercurial repositories. The branchmap contains lines
9105 of the form:
9106 original_branch_name new_branch_name
9108 where "original_branch_name" is the name of the branch in the source
9110 repository, and "new_branch_name" is the name of the branch is the des‐
9111 tination repository. No whitespace is allowed in the new branch name.
9112 This can be used to (for instance) move code in one repository from
9113 "default" to a named branch.
9114 Mercurial Source
9116 The Mercurial source recognizes the following configuration options,
9117 which you can set on the command line with --config:
9118 convert.hg.ignoreerrors
9120 ignore integrity errors when reading. Use it to fix Mercurial
9121 repositories with missing revlogs, by converting from and to
9122 Mercurial. Default is False.
9123 convert.hg.saverev
9125 store original revision ID in changeset (forces target IDs to
9126 change). It takes a boolean argument and defaults to False.
9127 convert.hg.startrev
9129 specify the initial Mercurial revision. The default is 0.
9130 convert.hg.revs
9132 revset specifying the source revisions to convert.
9133 Bazaar Source
9135 The following options can be used with --config:
9136 convert.bzr.saverev
9138 whether to store the original Bazaar commit ID in the metadata
9139 of the destination commit. The default is True.
9140 CVS Source
9142 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to
9143 indicate the starting point of what will be converted. Direct access to
9144 the repository files is not needed, unless of course the repository is
9145 :local:. The conversion uses the top level directory in the sandbox to
9146 find the CVS repository, and then uses CVS rlog commands to find files
9147 to convert. This means that unless a filemap is given, all files under
9148 the starting directory will be converted, and that any directory reor‐
9149 ganization in the CVS sandbox is ignored.
9150 The following options can be used with --config:
9152 convert.cvsps.cache
9154 Set to False to disable remote log caching, for testing and
9155 debugging purposes. Default is True.
9156 convert.cvsps.fuzz
9158 Specify the maximum time (in seconds) that is allowed between
9159 commits with identical user and log message in a single change‐
9160 set. When very large files were checked in as part of a change‐
9161 set then the default may not be long enough. The default is 60.
9162 convert.cvsps.logencoding
9164 Specify encoding name to be used for transcoding CVS log mes‐
9165 sages. Multiple encoding names can be specified as a list (see
9166 hg help config.Syntax), but only the first acceptable encoding
9167 in the list is used per CVS log entries. This transcoding is
9168 executed before cvslog hook below.
9169 convert.cvsps.mergeto
9171 Specify a regular expression to which commit log messages are
9172 matched. If a match occurs, then the conversion process will
9173 insert a dummy revision merging the branch on which this log
9174 message occurs to the branch indicated in the regex. Default is
9175 {{mergetobranch ([-\w]+)}}
9176 convert.cvsps.mergefrom
9178 Specify a regular expression to which commit log messages are
9179 matched. If a match occurs, then the conversion process will add
9180 the most recent revision on the branch indicated in the regex as
9181 the second parent of the changeset. Default is {{mergefrombranch
9182 ([-\w]+)}}
9183 convert.localtimezone
9185 use local time (as determined by the TZ environment variable)
9186 for changeset date/times. The default is False (use UTC).
9187 hooks.cvslog
9189 Specify a Python function to be called at the end of gathering
9190 the CVS log. The function is passed a list with the log entries,
9191 and can modify the entries in-place, or add or delete them.
9192 hooks.cvschangesets
9194 Specify a Python function to be called after the changesets are
9195 calculated from the CVS log. The function is passed a list with
9196 the changeset entries, and can modify the changesets in-place,
9197 or add or delete them.
9198 An additional "debugcvsps" Mercurial command allows the builtin change‐
9200 set merging code to be run without doing a conversion. Its parameters
9201 and output are similar to that of cvsps 2.1. Please see the command
9202 help for more details.
9203 Subversion Source
9205 Subversion source detects classical trunk/branches/tags layouts. By
9206 default, the supplied svn://repo/path/ source URL is converted as a
9207 single branch. If svn://repo/path/trunk exists it replaces the default
9208 branch. If svn://repo/path/branches exists, its subdirectories are
9209 listed as possible branches. If svn://repo/path/tags exists, it is
9210 looked for tags referencing converted branches. Default trunk, branches
9211 and tags values can be overridden with following options. Set them to
9212 paths relative to the source URL, or leave them blank to disable auto
9213 detection.
9214 The following options can be set with --config:
9216 convert.svn.branches
9218 specify the directory containing branches. The default is
9219 branches.
9220 convert.svn.tags
9222 specify the directory containing tags. The default is tags.
9223 convert.svn.trunk
9225 specify the name of the trunk branch. The default is trunk.
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 Source history can be retrieved starting at a specific revision,
9232 instead of being integrally converted. Only single branch conversions
9233 are supported.
9234 convert.svn.startrev
9236 specify start Subversion revision number. The default is 0.
9237 Git Source
9239 The Git importer converts commits from all reachable branches (refs in
9240 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
9241 are converted to bookmarks with the same name, with the leading
9242 'refs/heads' stripped. Git submodules are converted to Git subrepos in
9243 Mercurial.
9244 The following options can be set with --config:
9246 convert.git.similarity
9248 specify how similar files modified in a commit must be to be
9249 imported as renames or copies, as a percentage between 0 (dis‐
9250 abled) and 100 (files must be identical). For example, 90 means
9251 that a delete/add pair will be imported as a rename if more than
9252 90% of the file hasn't changed. The default is 50.
9253 convert.git.findcopiesharder
9255 while detecting copies, look at all files in the working copy
9256 instead of just changed ones. This is very expensive for large
9257 projects, and is only effective when convert.git.similarity is
9258 greater than 0. The default is False.
9259 convert.git.renamelimit
9261 perform rename and copy detection up to this many changed files
9262 in a commit. Increasing this will make rename and copy detection
9263 more accurate but will significantly slow down computation on
9264 large projects. The option is only relevant if convert.git.simi‐
9265 larity is greater than 0. The default is 400.
9266 convert.git.committeractions
9268 list of actions to take when processing author and committer
9269 values.
9270 Git commits have separate author (who wrote the commit) and com‐
9272 mitter (who applied the commit) fields. Not all destinations
9273 support separate author and committer fields (including Mercu‐
9274 rial). This config option controls what to do with these author
9275 and committer fields during conversion.
9276 A value of messagedifferent will append a committer: ... line
9278 to the commit message if the Git committer is different from the
9279 author. The prefix of that line can be specified using the syn‐
9280 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
9281 ter:. When a prefix is specified, a space will always be
9282 inserted between the prefix and the value.
9283 messagealways behaves like messagedifferent except it will
9285 always result in a committer: ... line being appended to the
9286 commit message. This value is mutually exclusive with messaged‐
9287 ifferent.
9288 dropcommitter will remove references to the committer. Only ref‐
9290 erences to the author will remain. Actions that add references
9291 to the committer will have no effect when this is set.
9292 replaceauthor will replace the value of the author field with
9294 the committer. Other actions that add references to the commit‐
9295 ter will still take effect when this is set.
9296 The default is messagedifferent.
9298 convert.git.extrakeys
9300 list of extra keys from commit metadata to copy to the destina‐
9301 tion. Some Git repositories store extra metadata in commits. By
9302 default, this non-default metadata will be lost during conver‐
9303 sion. Setting this config option can retain that metadata. Some
9304 built-in keys such as parent and branch are not allowed to be
9305 copied.
9306 convert.git.remoteprefix
9308 remote refs are converted as bookmarks with con‐
9309 vert.git.remoteprefix as a prefix followed by a /. The default
9310 is 'remote'.
9311 convert.git.saverev
9313 whether to store the original Git commit ID in the metadata of
9314 the destination commit. The default is True.
9315 convert.git.skipsubmodules
9317 does not convert root level .gitmodules files or files with
9318 160000 mode indicating a submodule. Default is False.
9319 Perforce Source
9321 The Perforce (P4) importer can be given a p4 depot path or a client
9322 specification as source. It will convert all files in the source to a
9323 flat Mercurial repository, ignoring labels, branches and integrations.
9324 Note that when a depot path is given you then usually should specify a
9325 target directory, because otherwise the target may be named ...-hg.
9326 The following options can be set with --config:
9328 convert.p4.encoding
9330 specify the encoding to use when decoding standard output of the
9331 Perforce command line tool. The default is default system encod‐
9332 ing.
9333 convert.p4.startrev
9335 specify initial Perforce revision (a Perforce changelist num‐
9336 ber).
9337 Mercurial Destination
9339 The Mercurial destination will recognize Mercurial subrepositories in
9340 the destination directory, and update the .hgsubstate file automati‐
9341 cally if the destination subrepositories contain the
9342 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
9343 tories requires converting a single repository at a time, from the bot‐
9344 tom up.
9345 An example showing how to convert a repository with subrepositories:
9347 # so convert knows the type when it sees a non empty destination
9349 $ hg init converted
9350 $ hg convert orig/sub1 converted/sub1
9352 $ hg convert orig/sub2 converted/sub2
9353 $ hg convert orig converted
9354 The following options are supported:
9356 convert.hg.clonebranches
9358 dispatch source branches in separate clones. The default is
9359 False.
9360 convert.hg.tagsbranch
9362 branch name for tag revisions, defaults to default.
9363 convert.hg.usebranchnames
9365 preserve branch names. The default is True.
9366 convert.hg.sourcename
9368 records the given string as a 'convert_source' extra value on
9369 each commit made in the target repository. The default is None.
9370 convert.hg.preserve-hash
9372 only works with mercurial sources. Make convert prevent perfor‐
9373 mance improvement to the list of modified files in commits when
9374 such an improvement would cause the hash of a commit to change.
9375 The default is False.
9376 All Destinations
9378 All destination types accept the following options:
9379 convert.skiptags
9381 does not convert tags from the source repo to the target repo.
9382 The default is False.
9383 Options:
9385 --authors <FILE>
9387 username mapping filename (DEPRECATED) (use --authormap instead)
9388 -s,--source-type <TYPE>
9390 source repository type
9391 -d,--dest-type <TYPE>
9393 destination repository type
9394 -r,--rev <REV[+]>
9396 import up to source revision REV
9397 -A,--authormap <FILE>
9399 remap usernames using this file
9400 --filemap <FILE>
9402 remap file names using contents of file
9403 --full apply filemap changes by converting all files again
9405 --splicemap <FILE>
9407 splice synthesized history into place
9408 --branchmap <FILE>
9410 change branch names while converting
9411 --branchsort
9413 try to sort changesets by branches
9414 --datesort
9416 try to sort changesets by date
9417 --sourcesort
9419 preserve source changesets order
9420 --closesort
9422 try to reorder closed revisions
9423 [+] marked option can be specified multiple times
9425 eol
9427 automatically manage newlines in repository files
9428 This extension allows you to manage the type of line endings (CRLF or
9430 LF) that are used in the repository and in the local working directory.
9431 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
9432 thereby letting everybody use their OS native line endings.
9433 The extension reads its configuration from a versioned .hgeol configu‐
9435 ration file found in the root of the working directory. The .hgeol file
9436 use the same syntax as all other Mercurial configuration files. It uses
9437 two sections, [patterns] and [repository].
9438 The [patterns] section specifies how line endings should be converted
9440 between the working directory and the repository. The format is speci‐
9441 fied by a file pattern. The first match is used, so put more specific
9442 patterns first. The available line endings are LF, CRLF, and BIN.
9443 Files with the declared format of CRLF or LF are always checked out and
9445 stored in the repository in that format and files declared to be binary
9446 (BIN) are left unchanged. Additionally, native is an alias for checking
9447 out in the platform's default line ending: LF on Unix (including Mac OS
9448 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
9449 Mercurial's default behavior; it is only needed if you need to override
9450 a later, more general pattern.
9451 The optional [repository] section specifies the line endings to use for
9453 files stored in the repository. It has a single setting, native, which
9454 determines the storage line endings for files declared as native in the
9455 [patterns] section. It can be set to LF or CRLF. The default is LF. For
9456 example, this means that on Windows, files configured as native (CRLF
9457 by default) will be converted to LF when stored in the repository.
9458 Files declared as LF, CRLF, or BIN in the [patterns] section are always
9459 stored as-is in the repository.
9460 Example versioned .hgeol file:
9462 [patterns]
9464 **.py = native
9465 **.vcproj = CRLF
9466 **.txt = native
9467 Makefile = LF
9468 **.jpg = BIN
9469 [repository]
9471 native = LF
9472 Note The rules will first apply when files are touched in the working
9474 directory, e.g. by updating to null and back to tip to touch all
9475 files.
9476 The extension uses an optional [eol] section read from both the normal
9478 Mercurial configuration files and the .hgeol file, with the latter
9479 overriding the former. You can use that section to control the overall
9480 behavior. There are three settings:
9481 · eol.native (default os.linesep) can be set to LF or CRLF to override
9483 the default interpretation of native for checkout. This can be used
9484 with hg archive on Unix, say, to generate an archive where files have
9485 line endings for Windows.
9486 · eol.only-consistent (default True) can be set to False to make the
9488 extension convert files with inconsistent EOLs. Inconsistent means
9489 that there is both CRLF and LF present in the file. Such files are
9490 normally not touched under the assumption that they have mixed EOLs
9491 on purpose.
9492 · eol.fix-trailing-newline (default False) can be set to True to ensure
9494 that converted files end with a EOL character (either \n or \r\n as
9495 per the configured patterns).
9496 The extension provides cleverencode: and cleverdecode: filters like the
9498 deprecated win32text extension does. This means that you can disable
9499 win32text and enable eol and your filters will still work. You only
9500 need to these filters until you have prepared a .hgeol file.
9501 The win32text.forbid* hooks provided by the win32text extension have
9503 been unified into a single hook named eol.checkheadshook. The hook will
9504 lookup the expected line endings from the .hgeol file, which means you
9505 must migrate to a .hgeol file first before using the hook. eol.check‐
9506 headshook only checks heads, intermediate invalid revisions will be
9507 pushed. To forbid them completely, use the eol.checkallhook hook. These
9508 hooks are best used as pretxnchangegroup hooks.
9509 See hg help patterns for more information about the glob patterns used.
9511 extdiff
9513 command to allow external programs to compare revisions
9514 The extdiff Mercurial extension allows you to use external programs to
9516 compare revisions, or revision with working directory. The external
9517 diff programs are called with a configurable set of options and two
9518 non-option arguments: paths to directories containing snapshots of
9519 files to compare.
9520 If there is more than one file being compared and the "child" revision
9522 is the working directory, any modifications made in the external diff
9523 program will be copied back to the working directory from the temporary
9524 directory.
9525 The extdiff extension also allows you to configure new diff commands,
9527 so you do not need to type hg extdiff -p kdiff3 always.
9528 [extdiff]
9530 # add new command that runs GNU diff(1) in 'context diff' mode
9531 cdiff = gdiff -Nprc5
9532 ## or the old way:
9533 #cmd.cdiff = gdiff
9534 #opts.cdiff = -Nprc5
9535 # add new command called meld, runs meld (no need to name twice). If
9537 # the meld executable is not available, the meld tool in [merge-tools]
9538 # will be used, if available
9539 meld =
9540 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
9542 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
9543 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
9544 # your .vimrc
9545 vimdiff = gvim -f "+next" \
9546 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
9547 Tool arguments can include variables that are expanded at runtime:
9549 $parent1, $plabel1 - filename, descriptive label of first parent
9551 $child, $clabel - filename, descriptive label of child revision
9552 $parent2, $plabel2 - filename, descriptive label of second parent
9553 $root - repository root
9554 $parent is an alias for $parent1.
9555 The extdiff extension will look in your [diff-tools] and [merge-tools]
9557 sections for diff tool arguments, when none are specified in [extdiff].
9558 [extdiff]
9560 kdiff3 =
9561 [diff-tools]
9563 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9564 If a program has a graphical interface, it might be interesting to tell
9566 Mercurial about it. It will prevent the program from being mistakenly
9567 used in a terminal-only environment (such as an SSH terminal session),
9568 and will make hg extdiff --per-file open multiple file diffs at once
9569 instead of one by one (if you still want to open file diffs one by one,
9570 you can use the --confirm option).
9571 Declaring that a tool has a graphical interface can be done with the
9573 gui flag next to where diffargs are specified:
9574 [diff-tools]
9576 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9577 kdiff3.gui = true
9578 You can use -I/-X and list of file or directory names like normal hg
9580 diff command. The extdiff extension makes snapshots of only needed
9581 files, so running the external diff program will actually be pretty
9582 fast (at least faster than having to compare the entire tree).
9583 Commands
9585 File content management
9586 extdiff
9587 use external program to diff repository (or selected files):
9588 hg extdiff [OPT]... [FILE]...
9590 Show differences between revisions for the specified files, using an
9592 external program. The default program used is diff, with default
9593 options "-Npru".
9594 To select a different program, use the -p/--program option. The program
9596 will be passed the names of two directories to compare, unless the
9597 --per-file option is specified (see below). To pass additional options
9598 to the program, use -o/--option. These will be passed before the names
9599 of the directories or files to compare.
9600 When two revision arguments are given, then changes are shown between
9602 those revisions. If only one revision is specified then that revision
9603 is compared to the working directory, and, when no revisions are speci‐
9604 fied, the working directory files are compared to its parent.
9605 The --per-file option runs the external program repeatedly on each file
9607 to diff, instead of once on two directories. By default, this happens
9608 one by one, where the next file diff is open in the external program
9609 only once the previous external program (for the previous file diff)
9610 has exited. If the external program has a graphical interface, it can
9611 open all the file diffs at once instead of one by one. See hg help -e
9612 extdiff for information about how to tell Mercurial that a given pro‐
9613 gram has a graphical interface.
9614 The --confirm option will prompt the user before each invocation of the
9616 external program. It is ignored if --per-file isn't specified.
9617 Options:
9619 -p,--program <CMD>
9621 comparison program to run
9622 -o,--option <OPT[+]>
9624 pass option to comparison program
9625 -r,--rev <REV[+]>
9627 revision
9628 -c,--change <REV>
9630 change made by revision
9631 --per-file
9633 compare each file instead of revision snapshots
9634 --confirm
9636 prompt user before each external program invocation
9637 --patch
9639 compare patches for two revisions
9640 -I,--include <PATTERN[+]>
9642 include names matching the given patterns
9643 -X,--exclude <PATTERN[+]>
9645 exclude names matching the given patterns
9646 -S, --subrepos
9648 recurse into subrepositories
9649 [+] marked option can be specified multiple times
9651 factotum
9653 http authentication with factotum
9654 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
9656 platforms to provide authentication information for HTTP access. Con‐
9657 figuration entries specified in the auth section as well as authentica‐
9658 tion information provided in the repository URL are fully supported. If
9659 no prefix is specified, a value of "*" will be assumed.
9660 By default, keys are specified as:
9662 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
9664 If the factotum extension is unable to read the required key, one will
9666 be requested interactively.
9667 A configuration section is available to customize runtime behavior. By
9669 default, these entries are:
9670 [factotum]
9672 executable = /bin/auth/factotum
9673 mountpoint = /mnt/factotum
9674 service = hg
9675 The executable entry defines the full path to the factotum binary. The
9677 mountpoint entry defines the path to the factotum file service. Lastly,
9678 the service entry controls the service name used when reading keys.
9679 fastannotate
9681 yet another annotate implementation that might be faster (EXPERIMENTAL)
9682 The fastannotate extension provides a 'fastannotate' command that makes
9684 use of the linelog data structure as a cache layer and is expected to
9685 be faster than the vanilla 'annotate' if the cache is present.
9686 In most cases, fastannotate requires a setup that mainbranch is some
9688 pointer that always moves forward, to be most efficient.
9689 Using fastannotate together with linkrevcache would speed up building
9691 the annotate cache greatly. Run "debugbuildlinkrevcache" before "debug‐
9692 buildannotatecache".
9693 [fastannotate]
9695 # specify the main branch head. the internal linelog will only contain
9696 # the linear (ignoring p2) "mainbranch". since linelog cannot move
9697 # backwards without a rebuild, this should be something that always moves
9698 # forward, usually it is "master" or "@".
9699 mainbranch = master
9700 # fastannotate supports different modes to expose its feature.
9702 # a list of combination:
9703 # - fastannotate: expose the feature via the "fastannotate" command which
9704 # deals with everything in a most efficient way, and provides extra
9705 # features like --deleted etc.
9706 # - fctx: replace fctx.annotate implementation. note:
9707 # a. it is less efficient than the "fastannotate" command
9708 # b. it will make it practically impossible to access the old (disk
9709 # side-effect free) annotate implementation
9710 # c. it implies "hgweb".
9711 # - hgweb: replace hgweb's annotate implementation. conflict with "fctx".
9712 # (default: fastannotate)
9713 modes = fastannotate
9714 # default format when no format flags are used (default: number)
9716 defaultformat = changeset, user, date
9717 # serve the annotate cache via wire protocol (default: False)
9719 # tip: the .hg/fastannotate directory is portable - can be rsynced
9720 server = True
9721 # build annotate cache on demand for every client request (default: True)
9723 # disabling it could make server response faster, useful when there is a
9724 # cronjob building the cache.
9725 serverbuildondemand = True
9726 # update local annotate cache from remote on demand
9728 client = False
9729 # path to use when connecting to the remote server (default: default)
9731 remotepath = default
9732 # minimal length of the history of a file required to fetch linelog from
9734 # the server. (default: 10)
9735 clientfetchthreshold = 10
9736 # for "fctx" mode, always follow renames regardless of command line option.
9738 # this is a BC with the original command but will reduced the space needed
9739 # for annotate cache, and is useful for client-server setup since the
9740 # server will only provide annotate cache with default options (i.e. with
9741 # follow). do not affect "fastannotate" mode. (default: True)
9742 forcefollow = True
9743 # for "fctx" mode, always treat file as text files, to skip the "isbinary"
9745 # check. this is consistent with the "fastannotate" command and could help
9746 # to avoid a file fetch if remotefilelog is used. (default: True)
9747 forcetext = True
9748 # use unfiltered repo for better performance.
9750 unfilteredrepo = True
9751 # sacrifice correctness in some corner cases for performance. it does not
9753 # affect the correctness of the annotate cache being built. the option
9754 # is experimental and may disappear in the future (default: False)
9755 perfhack = True
9756 Commands
9758 Uncategorized commands
9759 fetch
9760 pull, update and merge in one command (DEPRECATED)
9761 Commands
9763 Remote repository management
9764 fetch
9765 pull changes from a remote repository, merge new changes if needed.:
9766 hg fetch [SOURCE]
9768 This finds all changes from the repository at the specified path or URL
9770 and adds them to the local repository.
9771 If the pulled changes add a new branch head, the head is automatically
9773 merged, and the result of the merge is committed. Otherwise, the work‐
9774 ing directory is updated to include the new changes.
9775 When a merge is needed, the working directory is first updated to the
9777 newly pulled changes. Local changes are then merged into the pulled
9778 changes. To switch the merge order, use --switch-parent.
9779 See hg help dates for a list of formats valid for -d/--date.
9781 Returns 0 on success.
9783 Options:
9785 -r,--rev <REV[+]>
9787 a specific revision you would like to pull
9788 --edit invoke editor on commit messages
9790 --force-editor
9792 edit commit message (DEPRECATED)
9793 --switch-parent
9795 switch parents when merging
9796 -m,--message <TEXT>
9798 use text as commit message
9799 -l,--logfile <FILE>
9801 read commit message from file
9802 -d,--date <DATE>
9804 record the specified date as commit date
9805 -u,--user <USER>
9807 record the specified user as committer
9808 -e,--ssh <CMD>
9810 specify ssh command to use
9811 --remotecmd <CMD>
9813 specify hg command to run on the remote side
9814 --insecure
9816 do not verify server certificate (ignoring web.cacerts config)
9817 [+] marked option can be specified multiple times
9819 fix
9821 rewrite file content in changesets or working copy (EXPERIMENTAL)
9822 Provides a command that runs configured tools on the contents of modi‐
9824 fied files, writing back any fixes to the working copy or replacing
9825 changesets.
9826 Here is an example configuration that causes hg fix to apply automatic
9828 formatting fixes to modified lines in C++ code:
9829 [fix]
9831 clang-format:command=clang-format --assume-filename={rootpath}
9832 clang-format:linerange=--lines={first}:{last}
9833 clang-format:pattern=set:**.cpp or **.hpp
9834 The :command suboption forms the first part of the shell command that
9836 will be used to fix a file. The content of the file is passed on stan‐
9837 dard input, and the fixed file content is expected on standard output.
9838 Any output on standard error will be displayed as a warning. If the
9839 exit status is not zero, the file will not be affected. A placeholder
9840 warning is displayed if there is a non-zero exit status but no standard
9841 error output. Some values may be substituted into the command:
9842 {rootpath} The path of the file being fixed, relative to the repo root
9844 {basename} The name of the file being fixed, without the directory path
9845 If the :linerange suboption is set, the tool will only be run if there
9847 are changed lines in a file. The value of this suboption is appended to
9848 the shell command once for every range of changed lines in the file.
9849 Some values may be substituted into the command:
9850 {first} The 1-based line number of the first line in the modified range
9852 {last} The 1-based line number of the last line in the modified range
9853 Deleted sections of a file will be ignored by :linerange, because there
9855 is no corresponding line range in the version being fixed.
9856 By default, tools that set :linerange will only be executed if there is
9858 at least one changed line range. This is meant to prevent accidents
9859 like running a code formatter in such a way that it unexpectedly refor‐
9860 mats the whole file. If such a tool needs to operate on unchanged
9861 files, it should set the :skipclean suboption to false.
9862 The :pattern suboption determines which files will be passed through
9864 each configured tool. See hg help patterns for possible values. How‐
9865 ever, all patterns are relative to the repo root, even if that text
9866 says they are relative to the current working directory. If there are
9867 file arguments to hg fix, the intersection of these patterns is used.
9868 There is also a configurable limit for the maximum size of file that
9870 will be processed by hg fix:
9871 [fix]
9873 maxfilesize = 2MB
9874 Normally, execution of configured tools will continue after a failure
9876 (indicated by a non-zero exit status). It can also be configured to
9877 abort after the first such failure, so that no files will be affected
9878 if any tool fails. This abort will also cause hg fix to exit with a
9879 non-zero status:
9880 [fix]
9882 failure = abort
9883 When multiple tools are configured to affect a file, they execute in an
9885 order defined by the :priority suboption. The priority suboption has a
9886 default value of zero for each tool. Tools are executed in order of
9887 descending priority. The execution order of tools with equal priority
9888 is unspecified. For example, you could use the 'sort' and 'head' utili‐
9889 ties to keep only the 10 smallest numbers in a text file by ensuring
9890 that 'sort' runs before 'head':
9891 [fix]
9893 sort:command = sort -n
9894 head:command = head -n 10
9895 sort:pattern = numbers.txt
9896 head:pattern = numbers.txt
9897 sort:priority = 2
9898 head:priority = 1
9899 To account for changes made by each tool, the line numbers used for
9901 incremental formatting are recomputed before executing the next tool.
9902 So, each tool may see different values for the arguments added by the
9903 :linerange suboption.
9904 Each fixer tool is allowed to return some metadata in addition to the
9906 fixed file content. The metadata must be placed before the file content
9907 on stdout, separated from the file content by a zero byte. The metadata
9908 is parsed as a JSON value (so, it should be UTF-8 encoded and contain
9909 no zero bytes). A fixer tool is expected to produce this metadata
9910 encoding if and only if the :metadata suboption is true:
9911 [fix]
9913 tool:command = tool --prepend-json-metadata
9914 tool:metadata = true
9915 The metadata values are passed to hooks, which can be used to print
9917 summaries or perform other post-fixing work. The supported hooks are:
9918 "postfixfile"
9920 Run once for each file in each revision where any fixer tools made changes
9921 to the file content. Provides "$HG_REV" and "$HG_PATH" to identify the file,
9922 and "$HG_METADATA" with a map of fixer names to metadata values from fixer
9923 tools that affected the file. Fixer tools that didn't affect the file have a
9924 valueof None. Only fixer tools that executed are present in the metadata.
9925 "postfix"
9927 Run once after all files and revisions have been handled. Provides
9928 "$HG_REPLACEMENTS" with information about what revisions were created and
9929 made obsolete. Provides a boolean "$HG_WDIRWRITTEN" to indicate whether any
9930 files in the working copy were updated. Provides a list "$HG_METADATA"
9931 mapping fixer tool names to lists of metadata values returned from
9932 executions that modified a file. This aggregates the same metadata
9933 previously passed to the "postfixfile" hook.
9934 Fixer tools are run the in repository's root directory. This allows
9936 them to read configuration files from the working copy, or even write
9937 to the working copy. The working copy is not updated to match the
9938 revision being fixed. In fact, several revisions may be fixed in paral‐
9939 lel. Writes to the working copy are not amended into the revision being
9940 fixed; fixer tools should always write fixed file content back to std‐
9941 out as documented above.
9942 Commands
9944 File content management
9945 fix
9946 rewrite file content in changesets or working directory:
9947 hg fix [OPTION]... [FILE]...
9949 Runs any configured tools to fix the content of files. Only affects
9951 files with changes, unless file arguments are provided. Only affects
9952 changed lines of files, unless the --whole flag is used. Some tools may
9953 always affect the whole file regardless of --whole.
9954 If revisions are specified with --rev, those revisions will be checked,
9956 and they may be replaced with new revisions that have fixed file con‐
9957 tent. It is desirable to specify all descendants of each specified
9958 revision, so that the fixes propagate to the descendants. If all
9959 descendants are fixed at the same time, no merging, rebasing, or evolu‐
9960 tion will be required.
9961 If --working-dir is used, files with uncommitted changes in the working
9963 copy will be fixed. If the checked-out revision is also fixed, the
9964 working directory will update to the replacement revision.
9965 When determining what lines of each file to fix at each revision, the
9967 whole set of revisions being fixed is considered, so that fixes to ear‐
9968 lier revisions are not forgotten in later ones. The --base flag can be
9969 used to override this default behavior, though it is not usually desir‐
9970 able to do so.
9971 Options:
9973 --all fix all non-public non-obsolete revisions
9975 --base <REV[+]>
9977 revisions to diff against (overrides automatic selection, and
9978 applies to every revision being fixed)
9979 -r,--rev <REV[+]>
9981 revisions to fix
9982 -w, --working-dir
9984 fix the working directory
9985 --whole
9987 always fix every line of a file
9988 [+] marked option can be specified multiple times
9990 fsmonitor
9992 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
9993 Integrates the file-watching program Watchman with Mercurial to produce
9995 faster status results.
9996 On a particular Linux system, for a real-world repository with over
9998 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
9999 the same system, with fsmonitor it takes about 0.3 seconds.
10000 fsmonitor requires no configuration -- it will tell Watchman about your
10002 repository as necessary. You'll need to install Watchman from
10003 https://facebook.github.io/watchman/ and make sure it is in your PATH.
10004 fsmonitor is incompatible with the largefiles and eol extensions, and
10006 will disable itself if any of those are active.
10007 The following configuration options exist:
10009 [fsmonitor]
10011 mode = {off, on, paranoid}
10012 When mode = off, fsmonitor will disable itself (similar to not loading
10014 the extension at all). When mode = on, fsmonitor will be enabled (the
10015 default). When mode = paranoid, fsmonitor will query both Watchman and
10016 the filesystem, and ensure that the results are consistent.
10017 [fsmonitor]
10019 timeout = (float)
10020 A value, in seconds, that determines how long fsmonitor will wait for
10022 Watchman to return results. Defaults to 2.0.
10023 [fsmonitor]
10025 blacklistusers = (list of userids)
10026 A list of usernames for which fsmonitor will disable itself altogether.
10028 [fsmonitor]
10030 walk_on_invalidate = (boolean)
10031 Whether or not to walk the whole repo ourselves when our cached state
10033 has been invalidated, for example when Watchman has been restarted or
10034 .hgignore rules have been changed. Walking the repo in that case can
10035 result in competing for I/O with Watchman. For large repos it is recom‐
10036 mended to set this value to false. You may wish to set this to true if
10037 you have a very fast filesystem that can outpace the IPC overhead of
10038 getting the result data for the full repo from Watchman. Defaults to
10039 false.
10040 [fsmonitor]
10042 warn_when_unused = (boolean)
10043 Whether to print a warning during certain operations when fsmonitor
10045 would be beneficial to performance but isn't enabled.
10046 [fsmonitor]
10048 warn_update_file_count = (integer)
10049 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
10051 be printed during working directory updates if this many files will be
10052 created.
10053 githelp
10055 try mapping git commands to Mercurial commands
10056 Tries to map a given git command to a Mercurial command:
10058 $ hg githelp -- git checkout master hg update master
10060 If an unknown command or parameter combination is detected, an error is
10062 produced.
10063 Commands
10065 Help
10066 githelp
10067 suggests the Mercurial equivalent of the given git command:
10068 hg githelp
10070 Usage: hg githelp -- <git command>
10072 aliases: git
10074 gpg
10076 commands to sign and verify changesets
10077 Commands
10079 Signing changes (GPG)
10080 sigcheck
10081 verify all the signatures there may be for a particular revision:
10082 hg sigcheck REV
10084 verify all the signatures there may be for a particular revision
10086 sign
10088 add a signature for the current or given revision:
10089 hg sign [OPTION]... [REV]...
10091 If no revision is given, the parent of the working directory is used,
10093 or tip if no revision is checked out.
10094 The gpg.cmd config setting can be used to specify the command to run. A
10096 default key can be specified with gpg.key.
10097 See hg help dates for a list of formats valid for -d/--date.
10099 Options:
10101 -l, --local
10103 make the signature local
10104 -f, --force
10106 sign even if the sigfile is modified
10107 --no-commit
10109 do not commit the sigfile after signing
10110 -k,--key <ID>
10112 the key id to sign with
10113 -m,--message <TEXT>
10115 use text as commit message
10116 -e, --edit
10118 invoke editor on commit messages
10119 -d,--date <DATE>
10121 record the specified date as commit date
10122 -u,--user <USER>
10124 record the specified user as committer
10125 sigs
10127 list signed changesets:
10128 hg sigs
10130 list signed changesets
10132 graphlog
10134 command to view revision graphs from a shell (DEPRECATED)
10135 The functionality of this extension has been include in core Mercurial
10137 since version 2.3. Please use hg log -G ... instead.
10138 This extension adds a --graph option to the incoming, outgoing and log
10140 commands. When this options is given, an ASCII representation of the
10141 revision graph is also shown.
10142 Commands
10144 Change navigation
10145 glog
10146 show revision history alongside an ASCII revision graph:
10147 hg glog [OPTION]... [FILE]
10149 Print a revision history alongside a revision graph drawn with ASCII
10151 characters.
10152 Nodes printed as an @ character are parents of the working directory.
10154 This is an alias to hg log -G.
10156 Options:
10158 -f, --follow
10160 follow changeset history, or file history across copies and
10161 renames
10162 --follow-first
10164 only follow the first parent of merge changesets (DEPRECATED)
10165 -d,--date <DATE>
10167 show revisions matching date spec
10168 -C, --copies
10170 show copied files
10171 -k,--keyword <TEXT[+]>
10173 do case-insensitive search for a given text
10174 -r,--rev <REV[+]>
10176 show the specified revision or revset
10177 --removed
10179 include revisions where files were removed
10180 -m, --only-merges
10182 show only merges (DEPRECATED)
10183 -u,--user <USER[+]>
10185 revisions committed by user
10186 --only-branch <BRANCH[+]>
10188 show only changesets within the given named branch (DEPRECATED)
10189 -b,--branch <BRANCH[+]>
10191 show changesets within the given named branch
10192 -P,--prune <REV[+]>
10194 do not display revision or any of its ancestors
10195 -p, --patch
10197 show patch
10198 -g, --git
10200 use git extended diff format
10201 -l,--limit <NUM>
10203 limit number of changes displayed
10204 -M, --no-merges
10206 do not show merges
10207 --stat output diffstat-style summary of changes
10209 -G, --graph
10211 show the revision DAG
10212 --style <STYLE>
10214 display using template map file (DEPRECATED)
10215 -T,--template <TEMPLATE>
10217 display with template
10218 -I,--include <PATTERN[+]>
10220 include names matching the given patterns
10221 -X,--exclude <PATTERN[+]>
10223 exclude names matching the given patterns
10224 [+] marked option can be specified multiple times
10226 hgk
10228 browse the repository in a graphical way
10229 The hgk extension allows browsing the history of a repository in a
10231 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
10232 distributed with Mercurial.)
10233 hgk consists of two parts: a Tcl script that does the displaying and
10235 querying of information, and an extension to Mercurial named hgk.py,
10236 which provides hooks for hgk to get information. hgk can be found in
10237 the contrib directory, and the extension is shipped in the hgext repos‐
10238 itory, and needs to be enabled.
10239 The hg view command will launch the hgk Tcl script. For this command to
10241 work, hgk must be in your search path. Alternately, you can specify the
10242 path to hgk in your configuration file:
10243 [hgk]
10245 path = /location/of/hgk
10246 hgk can make use of the extdiff extension to visualize revisions.
10248 Assuming you had already configured extdiff vdiff command, just add:
10249 [hgk]
10251 vdiff=vdiff
10252 Revisions context menu will now display additional entries to fire
10254 vdiff on hovered and selected revisions.
10255 Commands
10257 Change navigation
10258 view
10259 hg view [-l LIMIT] [REVRANGE]
10260 Options:
10262 -l,--limit <NUM>
10264 limit number of changes displayed
10265 Uncategorized commands
10267 highlight
10268 syntax highlighting for hgweb (requires Pygments)
10269 It depends on the Pygments syntax highlighting library:
10271 http://pygments.org/
10272 There are the following configuration options:
10274 [web]
10276 pygments_style = <style> (default: colorful)
10277 highlightfiles = <fileset> (default: size('<5M'))
10278 highlightonlymatchfilename = <bool> (default False)
10279 highlightonlymatchfilename will only highlight files if their type
10281 could be identified by their filename. When this is not enabled (the
10282 default), Pygments will try very hard to identify the file type from
10283 content and any match (even matches with a low confidence score) will
10284 be used.
10285 histedit
10287 interactive history editing
10288 With this extension installed, Mercurial gains one new command: histe‐
10290 dit. Usage is as follows, assuming the following history:
10291 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
10293 | Add delta
10294 |
10295 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
10296 | Add gamma
10297 |
10298 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
10299 | Add beta
10300 |
10301 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10302 Add alpha
10303 If you were to run hg histedit c561b4e977df, you would see the follow‐
10305 ing file open in your editor:
10306 pick c561b4e977df Add beta
10308 pick 030b686bedc4 Add gamma
10309 pick 7c2fd3b9020c Add delta
10310 # Edit history between c561b4e977df and 7c2fd3b9020c
10312 #
10313 # Commits are listed from least to most recent
10314 #
10315 # Commands:
10316 # p, pick = use commit
10317 # e, edit = use commit, but stop for amending
10318 # f, fold = use commit, but combine it with the one above
10319 # r, roll = like fold, but discard this commit's description and date
10320 # d, drop = remove commit from history
10321 # m, mess = edit commit message without changing commit content
10322 # b, base = checkout changeset and apply further changesets from there
10323 #
10324 In this file, lines beginning with # are ignored. You must specify a
10326 rule for each revision in your history. For example, if you had meant
10327 to add gamma before beta, and then wanted to add delta in the same
10328 revision as beta, you would reorganize the file to look like this:
10329 pick 030b686bedc4 Add gamma
10331 pick c561b4e977df Add beta
10332 fold 7c2fd3b9020c Add delta
10333 # Edit history between c561b4e977df and 7c2fd3b9020c
10335 #
10336 # Commits are listed from least to most recent
10337 #
10338 # Commands:
10339 # p, pick = use commit
10340 # e, edit = use commit, but stop for amending
10341 # f, fold = use commit, but combine it with the one above
10342 # r, roll = like fold, but discard this commit's description and date
10343 # d, drop = remove commit from history
10344 # m, mess = edit commit message without changing commit content
10345 # b, base = checkout changeset and apply further changesets from there
10346 #
10347 At which point you close the editor and histedit starts working. When
10349 you specify a fold operation, histedit will open an editor when it
10350 folds those revisions together, offering you a chance to clean up the
10351 commit message:
10352 Add beta
10354 ***
10355 Add delta
10356 Edit the commit message to your liking, then close the editor. The date
10358 used for the commit will be the later of the two commits' dates. For
10359 this example, let's assume that the commit message was changed to Add
10360 beta and delta. After histedit has run and had a chance to remove any
10361 old or temporary revisions it needed, the history looks like this:
10362 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
10364 | Add beta and delta.
10365 |
10366 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10367 | Add gamma
10368 |
10369 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10370 Add alpha
10371 Note that histedit does not remove any revisions (even its own tempo‐
10373 rary ones) until after it has completed all the editing operations, so
10374 it will probably perform several strip operations when it's done. For
10375 the above example, it had to run strip twice. Strip can be slow depend‐
10376 ing on a variety of factors, so you might need to be a little patient.
10377 You can choose to keep the original revisions by passing the --keep
10378 flag.
10379 The edit operation will drop you back to a command prompt, allowing you
10381 to edit files freely, or even use hg record to commit some changes as a
10382 separate commit. When you're done, any remaining uncommitted changes
10383 will be committed as well. When done, run hg histedit --continue to
10384 finish this step. If there are uncommitted changes, you'll be prompted
10385 for a new commit message, but the default commit message will be the
10386 original message for the edit ed revision, and the date of the original
10387 commit will be preserved.
10388 The message operation will give you a chance to revise a commit message
10390 without changing the contents. It's a shortcut for doing edit immedi‐
10391 ately followed by hg histedit --continue`.
10392 If histedit encounters a conflict when moving a revision (while han‐
10394 dling pick or fold), it'll stop in a similar manner to edit with the
10395 difference that it won't prompt you for a commit message when done. If
10396 you decide at this point that you don't like how much work it will be
10397 to rearrange history, or that you made a mistake, you can use hg histe‐
10398 dit --abort to abandon the new changes you have made and return to the
10399 state before you attempted to edit your history.
10400 If we clone the histedit-ed example repository above and add four more
10402 changes, such that we have the following history:
10403 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
10405 | Add theta
10406 |
10407 o 5 140988835471 2009-04-27 18:04 -0500 stefan
10408 | Add eta
10409 |
10410 o 4 122930637314 2009-04-27 18:04 -0500 stefan
10411 | Add zeta
10412 |
10413 o 3 836302820282 2009-04-27 18:04 -0500 stefan
10414 | Add epsilon
10415 |
10416 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
10417 | Add beta and delta.
10418 |
10419 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10420 | Add gamma
10421 |
10422 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10423 Add alpha
10424 If you run hg histedit --outgoing on the clone then it is the same as
10426 running hg histedit 836302820282. If you need plan to push to a reposi‐
10427 tory that Mercurial does not detect to be related to the source repo,
10428 you can add a --force option.
10429 Config
10431 Histedit rule lines are truncated to 80 characters by default. You can
10432 customize this behavior by setting a different length in your configu‐
10433 ration file:
10434 [histedit]
10436 linelen = 120 # truncate rule lines at 120 characters
10437 The summary of a change can be customized as well:
10439 [histedit]
10441 summary-template = '{rev} {bookmarks} {desc|firstline}'
10442 The customized summary should be kept short enough that rule lines will
10444 fit in the configured line length. See above if that requires cus‐
10445 tomization.
10446 hg histedit attempts to automatically choose an appropriate base revi‐
10448 sion to use. To change which base revision is used, define a revset in
10449 your configuration file:
10450 [histedit]
10452 defaultrev = only(.) & draft()
10453 By default each edited revision needs to be present in histedit com‐
10455 mands. To remove revision you need to use drop operation. You can con‐
10456 figure the drop to be implicit for missing commits by adding:
10457 [histedit]
10459 dropmissing = True
10460 By default, histedit will close the transaction after each action. For
10462 performance purposes, you can configure histedit to use a single trans‐
10463 action across the entire histedit. WARNING: This setting introduces a
10464 significant risk of losing the work you've done in a histedit if the
10465 histedit aborts unexpectedly:
10466 [histedit]
10468 singletransaction = True
10469 Commands
10471 Change manipulation
10472 histedit
10473 interactively edit changeset history:
10474 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
10476 This command lets you edit a linear series of changesets (up to and
10478 including the working directory, which should be clean). You can:
10479 · pick to [re]order a changeset
10481 · drop to omit changeset
10483 · mess to reword the changeset commit message
10485 · fold to combine it with the preceding changeset (using the later
10487 date)
10488 · roll like fold, but discarding this commit's description and date
10490 · edit to edit this changeset (preserving date)
10492 · base to checkout changeset and apply further changesets from there
10494 There are a number of ways to select the root changeset:
10496 · Specify ANCESTOR directly
10498 · Use --outgoing -- it will be the first linear changeset not included
10500 in destination. (See hg help config.paths.default-push)
10501 · Otherwise, the value from the "histedit.defaultrev" config option is
10503 used as a revset to select the base revision when ANCESTOR is not
10504 specified. The first revision returned by the revset is used. By
10505 default, this selects the editable history that is unique to the
10506 ancestry of the working directory.
10507 If you use --outgoing, this command will abort if there are ambiguous
10509 outgoing revisions. For example, if there are multiple branches con‐
10510 taining outgoing revisions.
10511 Use "min(outgoing() and ::.)" or similar revset specification instead
10513 of --outgoing to specify edit target revision exactly in such ambiguous
10514 situation. See hg help revsets for detail about selecting revisions.
10515 Examples:
10517 · A number of changes have been made. Revision 3 is no longer
10519 needed.
10520 Start history editing from revision 3:
10522 hg histedit -r 3
10524 An editor opens, containing the list of revisions, with specific
10526 actions specified:
10527 pick 5339bf82f0ca 3 Zworgle the foobar
10529 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10530 pick 0a9639fcda9d 5 Morgify the cromulancy
10531 Additional information about the possible actions to take appears
10533 below the list of revisions.
10534 To remove revision 3 from the history, its action (at the begin‐
10536 ning of the relevant line) is changed to 'drop':
10537 drop 5339bf82f0ca 3 Zworgle the foobar
10539 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10540 pick 0a9639fcda9d 5 Morgify the cromulancy
10541 · A number of changes have been made. Revision 2 and 4 need to be
10543 swapped.
10544 Start history editing from revision 2:
10546 hg histedit -r 2
10548 An editor opens, containing the list of revisions, with specific
10550 actions specified:
10551 pick 252a1af424ad 2 Blorb a morgwazzle
10553 pick 5339bf82f0ca 3 Zworgle the foobar
10554 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10555 To swap revision 2 and 4, its lines are swapped in the editor:
10557 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10559 pick 5339bf82f0ca 3 Zworgle the foobar
10560 pick 252a1af424ad 2 Blorb a morgwazzle
10561 Returns 0 on success, 1 if user intervention is required (not only for
10563 intentional "edit" command, but also for resolving unexpected con‐
10564 flicts).
10565 Options:
10567 --commands <FILE>
10569 read history edits from the specified file
10570 -c, --continue
10572 continue an edit already in progress
10573 --edit-plan
10575 edit remaining actions list
10576 -k, --keep
10578 don't strip old nodes after edit is complete
10579 --abort
10581 abort an edit in progress
10582 -o, --outgoing
10584 changesets not found in destination
10585 -f, --force
10587 force outgoing even for unrelated repositories
10588 -r,--rev <REV[+]>
10590 first revision to be edited
10591 -T,--template <TEMPLATE>
10593 display with template
10594 [+] marked option can be specified multiple times
10596 infinitepush
10598 store some pushes in a remote blob store on the server (EXPERIMEN‐
10599 TAL)
10600 IMPORTANT: if you use this extension, please contact
10602 mercurial-devel@mercurial-scm.org ASAP. This extension is believed to
10603 be unused and barring learning of users of this functionality, we will
10604 delete this code at the end of 2020.
10605 [infinitepush] # Server-side and client-side option. Pattern of the
10607 infinitepush bookmark branchpattern = PATTERN
10608 # Server or client server = False
10610 # Server-side option. Possible values: 'disk' or 'sql'. Fails if not
10612 set indextype = disk
10613 # Server-side option. Used only if indextype=sql. # Format:
10615 'IP:PORT:DB_NAME:USER:PASSWORD' sqlhost = IP:PORT:DB_NAME:USER:PASS‐
10616 WORD
10617 # Server-side option. Used only if indextype=disk. # Filesystem
10619 path to the index store indexpath = PATH
10620 # Server-side option. Possible values: 'disk' or 'external' # Fails
10622 if not set storetype = disk
10623 # Server-side option. # Path to the binary that will save bundle to
10625 the bundlestore # Formatted cmd line will be passed to it (see
10626 put_args) put_binary = put
10627 # Serser-side option. Used only if storetype=external. # Format
10629 cmd-line string for put binary. Placeholder: {filename} put_args =
10630 {filename}
10631 # Server-side option. # Path to the binary that get bundle from the
10633 bundlestore. # Formatted cmd line will be passed to it (see
10634 get_args) get_binary = get
10635 # Serser-side option. Used only if storetype=external. # Format
10637 cmd-line string for get binary. Placeholders: {filename} {handle}
10638 get_args = {filename} {handle}
10639 # Server-side option logfile = FIlE
10641 # Server-side option loglevel = DEBUG
10643 # Server-side option. Used only if indextype=sql. # Sets mysql
10645 wait_timeout option. waittimeout = 300
10646 # Server-side option. Used only if indextype=sql. # Sets mysql inn‐
10648 odb_lock_wait_timeout option. locktimeout = 120
10649 # Server-side option. Used only if indextype=sql. # Name of the
10651 repository reponame = ''
10652 # Client-side option. Used by --list-remote option. List of remote
10654 scratch # patterns to list if no patterns are specified. default‐
10655 remotepatterns = ['*']
10656 # Instructs infinitepush to forward all received bundle2 parts to
10658 the # bundle for storage. Defaults to False. storeallparts = True
10659 # routes each incoming push to the bundlestore. defaults to False
10661 pushtobundlestore = True
10662 [remotenames] # Client-side option # This option should be set only
10664 if remotenames extension is enabled. # Whether remote bookmarks are
10665 tracked by remotenames extension. bookmarks = True
10666 journal
10668 track previous positions of bookmarks (EXPERIMENTAL)
10669 This extension adds a new command: hg journal, which shows you where
10671 bookmarks were previously located.
10672 Commands
10674 Change organization
10675 journal
10676 show the previous position of bookmarks and the working copy:
10677 hg journal [OPTION]... [BOOKMARKNAME]
10679 The journal is used to see the previous commits that bookmarks and the
10681 working copy pointed to. By default the previous locations for the
10682 working copy. Passing a bookmark name will show all the previous posi‐
10683 tions of that bookmark. Use the --all switch to show previous locations
10684 for all bookmarks and the working copy; each line will then include the
10685 bookmark name, or '.' for the working copy, as well.
10686 If name starts with re:, the remainder of the name is treated as a reg‐
10688 ular expression. To match a name that actually starts with re:, use the
10689 prefix literal:.
10690 By default hg journal only shows the commit hash and the command that
10692 was running at that time. -v/--verbose will show the prior hash, the
10693 user, and the time at which it happened.
10694 Use -c/--commits to output log information on each commit hash; at this
10696 point you can use the usual --patch, --git, --stat and --template
10697 switches to alter the log output for these.
10698 hg journal -T json can be used to produce machine readable output.
10700 Options:
10702 --all show history for all names
10704 -c, --commits
10706 show commit metadata
10707 -p, --patch
10709 show patch
10710 -g, --git
10712 use git extended diff format
10713 -l,--limit <NUM>
10715 limit number of changes displayed
10716 --stat output diffstat-style summary of changes
10718 --style <STYLE>
10720 display using template map file (DEPRECATED)
10721 -T,--template <TEMPLATE>
10723 display with template
10724 keyword
10726 expand keywords in tracked files
10727 This extension expands RCS/CVS-like or self-customized $Keywords$ in
10729 tracked text files selected by your configuration.
10730 Keywords are only expanded in local repositories and not stored in the
10732 change history. The mechanism can be regarded as a convenience for the
10733 current user or for archive distribution.
10734 Keywords expand to the changeset data pertaining to the latest change
10736 relative to the working directory parent of each file.
10737 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
10739 sections of hgrc files.
10740 Example:
10742 [keyword]
10744 # expand keywords in every python file except those matching "x*"
10745 **.py =
10746 x* = ignore
10747 [keywordset]
10749 # prefer svn- over cvs-like default keywordmaps
10750 svn = True
10751 Note The more specific you are in your filename patterns the less you
10753 lose speed in huge repositories.
10754 For [keywordmaps] template mapping and expansion demonstration and con‐
10756 trol run hg kwdemo. See hg help templates for a list of available tem‐
10757 plates and filters.
10758 Three additional date template filters are provided:
10760 utcdate
10762 "2006/09/18 15:13:13"
10764 svnutcdate
10766 "2006-09-18 15:13:13Z"
10768 svnisodate
10770 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
10772 The default template mappings (view with hg kwdemo -d) can be replaced
10774 with customized keywords and templates. Again, run hg kwdemo to control
10775 the results of your configuration changes.
10776 Before changing/disabling active keywords, you must run hg kwshrink to
10778 avoid storing expanded keywords in the change history.
10779 To force expansion after enabling it, or a configuration change, run hg
10781 kwexpand.
10782 Expansions spanning more than one line and incremental expansions, like
10784 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
10785 expands to the first line of the changeset description.
10786 Commands
10788 Uncategorized commands
10789 kwdemo
10790 print [keywordmaps] configuration and an expansion example:
10791 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
10793 Show current, custom, or default keyword template maps and their expan‐
10795 sions.
10796 Extend the current configuration by specifying maps as arguments and
10798 using -f/--rcfile to source an external hgrc file.
10799 Use -d/--default to disable current configuration.
10801 See hg help templates for information on templates and filters.
10803 Options:
10805 -d, --default
10807 show default keyword template maps
10808 -f,--rcfile <FILE>
10810 read maps from rcfile
10811 kwexpand
10813 expand keywords in the working directory:
10814 hg kwexpand [OPTION]... [FILE]...
10816 Run after (re)enabling keyword expansion.
10818 kwexpand refuses to run if given files contain local changes.
10820 Options:
10822 -I,--include <PATTERN[+]>
10824 include names matching the given patterns
10825 -X,--exclude <PATTERN[+]>
10827 exclude names matching the given patterns
10828 [+] marked option can be specified multiple times
10830 kwfiles
10832 show files configured for keyword expansion:
10833 hg kwfiles [OPTION]... [FILE]...
10835 List which files in the working directory are matched by the [keyword]
10837 configuration patterns.
10838 Useful to prevent inadvertent keyword expansion and to speed up execu‐
10840 tion by including only files that are actual candidates for expansion.
10841 See hg help keyword on how to construct patterns both for inclusion and
10843 exclusion of files.
10844 With -A/--all and -v/--verbose the codes used to show the status of
10846 files are:
10847 K = keyword expansion candidate
10849 k = keyword expansion candidate (not tracked)
10850 I = ignored
10851 i = ignored (not tracked)
10852 Options:
10854 -A, --all
10856 show keyword status flags of all files
10857 -i, --ignore
10859 show files excluded from expansion
10860 -u, --unknown
10862 only show unknown (not tracked) files
10863 -I,--include <PATTERN[+]>
10865 include names matching the given patterns
10866 -X,--exclude <PATTERN[+]>
10868 exclude names matching the given patterns
10869 [+] marked option can be specified multiple times
10871 kwshrink
10873 revert expanded keywords in the working directory:
10874 hg kwshrink [OPTION]... [FILE]...
10876 Must be run before changing/disabling active keywords.
10878 kwshrink refuses to run if given files contain local changes.
10880 Options:
10882 -I,--include <PATTERN[+]>
10884 include names matching the given patterns
10885 -X,--exclude <PATTERN[+]>
10887 exclude names matching the given patterns
10888 [+] marked option can be specified multiple times
10890 largefiles
10892 track large binary files
10893 Large binary files tend to be not very compressible, not very diffable,
10895 and not at all mergeable. Such files are not handled efficiently by
10896 Mercurial's storage format (revlog), which is based on compressed
10897 binary deltas; storing large binary files as regular Mercurial files
10898 wastes bandwidth and disk space and increases Mercurial's memory usage.
10899 The largefiles extension addresses these problems by adding a central‐
10900 ized client-server layer on top of Mercurial: largefiles live in a cen‐
10901 tral store out on the network somewhere, and you only fetch the revi‐
10902 sions that you need when you need them.
10903 largefiles works by maintaining a "standin file" in .hglf/ for each
10905 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
10906 line) and are tracked by Mercurial. Largefile revisions are identified
10907 by the SHA-1 hash of their contents, which is written to the standin.
10908 largefiles uses that revision ID to get/put largefile revisions from/to
10909 the central store. This saves both disk space and bandwidth, since you
10910 don't need to retrieve all historical revisions of large files when you
10911 clone or pull.
10912 To start a new repository or add new large binary files, just add
10914 --large to your hg add command. For example:
10915 $ dd if=/dev/urandom of=randomdata count=2000
10917 $ hg add --large randomdata
10918 $ hg commit -m "add randomdata as a largefile"
10919 When you push a changeset that adds/modifies largefiles to a remote
10921 repository, its largefile revisions will be uploaded along with it.
10922 Note that the remote Mercurial must also have the largefiles extension
10923 enabled for this to work.
10924 When you pull a changeset that affects largefiles from a remote reposi‐
10926 tory, the largefiles for the changeset will by default not be pulled
10927 down. However, when you update to such a revision, any largefiles
10928 needed by that revision are downloaded and cached (if they have never
10929 been downloaded before). One way to pull largefiles when pulling is
10930 thus to use --update, which will update your working copy to the latest
10931 pulled revision (and thereby downloading any new largefiles).
10932 If you want to pull largefiles you don't need for update yet, then you
10934 can use pull with the --lfrev option or the hg lfpull command.
10935 If you know you are pulling from a non-default location and want to
10937 download all the largefiles that correspond to the new changesets at
10938 the same time, then you can pull with --lfrev "pulled()".
10939 If you just want to ensure that you will have the largefiles needed to
10941 merge or rebase with new heads that you are pulling, then you can pull
10942 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
10943 files that are new in the heads you are pulling.
10944 Keep in mind that network access may now be required to update to
10946 changesets that you have not previously updated to. The nature of the
10947 largefiles extension means that updating is no longer guaranteed to be
10948 a local-only operation.
10949 If you already have large files tracked by Mercurial without the large‐
10951 files extension, you will need to convert your repository in order to
10952 benefit from largefiles. This is done with the hg lfconvert command:
10953 $ hg lfconvert --size 10 oldrepo newrepo
10955 In repositories that already have largefiles in them, any new file over
10957 10MB will automatically be added as a largefile. To change this thresh‐
10958 old, set largefiles.minsize in your Mercurial config file to the mini‐
10959 mum size in megabytes to track as a largefile, or use the --lfsize
10960 option to the add command (also in megabytes):
10961 [largefiles]
10963 minsize = 2
10964 $ hg add --lfsize 2
10966 The largefiles.patterns config option allows you to specify a list of
10968 filename patterns (see hg help patterns) that should always be tracked
10969 as largefiles:
10970 [largefiles]
10972 patterns =
10973 *.jpg
10974 re:.*\.(png|bmp)$
10975 library.zip
10976 content/audio/*
10977 Files that match one of these patterns will be added as largefiles
10979 regardless of their size.
10980 The largefiles.minsize and largefiles.patterns config options will be
10982 ignored for any repositories not already containing a largefile. To add
10983 the first largefile to a repository, you must explicitly do so with the
10984 --large flag passed to the hg add command.
10985 Commands
10987 Uncategorized commands
10988 lfconvert
10989 convert a normal repository to a largefiles repository:
10990 hg lfconvert SOURCE DEST [FILE ...]
10992 Convert repository SOURCE to a new repository DEST, identical to SOURCE
10994 except that certain files will be converted as largefiles: specifi‐
10995 cally, any file that matches any PATTERN or whose size is above the
10996 minimum size threshold is converted as a largefile. The size used to
10997 determine whether or not to track a file as a largefile is the size of
10998 the first version of the file. The minimum size can be specified either
10999 with --size or in configuration as largefiles.size.
11000 After running this command you will need to make sure that largefiles
11002 is enabled anywhere you intend to push the new repository.
11003 Use --to-normal to convert largefiles back to normal files; after this,
11005 the DEST repository can be used without largefiles at all.
11006 Options:
11008 -s,--size <SIZE>
11010 minimum size (MB) for files to be converted as largefiles
11011 --to-normal
11013 convert from a largefiles repo to a normal repo
11014 lfpull
11016 pull largefiles for the specified revisions from the specified source:
11017 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
11019 Pull largefiles that are referenced from local changesets but missing
11021 locally, pulling from a remote repository to the local cache.
11022 If SOURCE is omitted, the 'default' path will be used. See hg help
11024 urls for more information.
11025 Some examples:
11027 · pull largefiles for all branch heads:
11029 hg lfpull -r "head() and not closed()"
11031 · pull largefiles on the default branch:
11033 hg lfpull -r "branch(default)"
11035 Options:
11037 -r,--rev <VALUE[+]>
11039 pull largefiles for these revisions
11040 -e,--ssh <CMD>
11042 specify ssh command to use
11043 --remotecmd <CMD>
11045 specify hg command to run on the remote side
11046 --insecure
11048 do not verify server certificate (ignoring web.cacerts config)
11049 [+] marked option can be specified multiple times
11051 lfs
11053 lfs - large file support (EXPERIMENTAL)
11054 This extension allows large files to be tracked outside of the normal
11056 repository storage and stored on a centralized server, similar to the
11057 largefiles extension. The git-lfs protocol is used when communicating
11058 with the server, so existing git infrastructure can be harnessed. Even
11059 though the files are stored outside of the repository, they are still
11060 integrity checked in the same manner as normal files.
11061 The files stored outside of the repository are downloaded on demand,
11063 which reduces the time to clone, and possibly the local disk usage.
11064 This changes fundamental workflows in a DVCS, so careful thought should
11065 be given before deploying it. hg convert can be used to convert LFS
11066 repositories to normal repositories that no longer require this exten‐
11067 sion, and do so without changing the commit hashes. This allows the
11068 extension to be disabled if the centralized workflow becomes burden‐
11069 some. However, the pre and post convert clones will not be able to
11070 communicate with each other unless the extension is enabled on both.
11071 To start a new repository, or to add LFS files to an existing one, just
11073 create an .hglfs file as described below in the root directory of the
11074 repository. Typically, this file should be put under version control,
11075 so that the settings will propagate to other repositories with push and
11076 pull. During any commit, Mercurial will consult this file to determine
11077 if an added or modified file should be stored externally. The type of
11078 storage depends on the characteristics of the file at each commit. A
11079 file that is near a size threshold may switch back and forth between
11080 LFS and normal storage, as needed.
11081 Alternately, both normal repositories and largefile controlled reposi‐
11083 tories can be converted to LFS by using hg convert and the lfs.track
11084 config option described below. The .hglfs file should then be created
11085 and added, to control subsequent LFS selection. The hashes are also
11086 unchanged in this case. The LFS and non-LFS repositories can be dis‐
11087 tinguished because the LFS repository will abort any command if this
11088 extension is disabled.
11089 Committed LFS files are held locally, until the repository is pushed.
11091 Prior to pushing the normal repository data, the LFS files that are
11092 tracked by the outgoing commits are automatically uploaded to the con‐
11093 figured central server. No LFS files are transferred on hg pull or hg
11094 clone. Instead, the files are downloaded on demand as they need to be
11095 read, if a cached copy cannot be found locally. Both committing and
11096 downloading an LFS file will link the file to a usercache, to speed up
11097 future access. See the usercache config setting described below.
11098 The extension reads its configuration from a versioned .hglfs configu‐
11100 ration file found in the root of the working directory. The .hglfs file
11101 uses the same syntax as all other Mercurial configuration files. It
11102 uses a single section, [track].
11103 The [track] section specifies which files are stored as LFS (or not).
11105 Each line is keyed by a file pattern, with a predicate value. The
11106 first file pattern match is used, so put more specific patterns first.
11107 The available predicates are all(), none(), and size(). See "hg help
11108 filesets.size" for the latter.
11109 Example versioned .hglfs file:
11111 [track]
11113 # No Makefile or python file, anywhere, will be LFS
11114 **Makefile = none()
11115 **.py = none()
11116 **.zip = all()
11118 **.exe = size(">1MB")
11119 # Catchall for everything not matched above
11121 ** = size(">10MB")
11122 Configs:
11124 [lfs]
11126 # Remote endpoint. Multiple protocols are supported:
11127 # - http(s)://user:pass@example.com/path
11128 # git-lfs endpoint
11129 # - file:///tmp/path
11130 # local filesystem, usually for testing
11131 # if unset, lfs will assume the remote repository also handles blob storage
11132 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
11133 # use this value.
11134 # (default: unset)
11135 url = https://example.com/repo.git/info/lfs
11136 # Which files to track in LFS. Path tests are "**.extname" for file
11138 # extensions, and "path:under/some/directory" for path prefix. Both
11139 # are relative to the repository root.
11140 # File size can be tested with the "size()" fileset, and tests can be
11141 # joined with fileset operators. (See "hg help filesets.operators".)
11142 #
11143 # Some examples:
11144 # - all() # everything
11145 # - none() # nothing
11146 # - size(">20MB") # larger than 20MB
11147 # - !**.txt # anything not a *.txt file
11148 # - **.zip | **.tar.gz | **.7z # some types of compressed files
11149 # - path:bin # files under "bin" in the project root
11150 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
11151 # | (path:bin & !path:/bin/README) | size(">1GB")
11152 # (default: none())
11153 #
11154 # This is ignored if there is a tracked '.hglfs' file, and this setting
11155 # will eventually be deprecated and removed.
11156 track = size(">10M")
11157 # how many times to retry before giving up on transferring an object
11159 retry = 5
11160 # the local directory to store lfs files for sharing across local clones.
11162 # If not set, the cache is located in an OS specific cache location.
11163 usercache = /path/to/global/cache
11164 Commands
11166 Uncategorized commands
11167 logtoprocess
11168 send ui.log() data to a subprocess (EXPERIMENTAL)
11169 This extension lets you specify a shell command per ui.log() event,
11171 sending all remaining arguments to as environment variables to that
11172 command.
11173 Positional arguments construct a log message, which is passed in the
11175 MSG1 environment variables. Each keyword argument is set as a
11176 OPT_UPPERCASE_KEY variable (so the key is uppercased, and prefixed with
11177 OPT_). The original event name is passed in the EVENT environment vari‐
11178 able, and the process ID of mercurial is given in HGPID.
11179 So given a call ui.log('foo', 'bar %s ', 'baz', spam='eggs'), a script
11181 configured for the `foo event can expect an environment with MSG1=bar
11182 baz, and OPT_SPAM=eggs.
11183 Scripts are configured in the [logtoprocess] section, each key an event
11185 name. For example:
11186 [logtoprocess]
11188 commandexception = echo "$MSG1" > /var/log/mercurial_exceptions.log
11189 would log the warning message and traceback of any failed command dis‐
11191 patch.
11192 Scripts are run asynchronously as detached daemon processes; mercurial
11194 will not ensure that they exit cleanly.
11195 mq
11197 manage a stack of patches
11198 This extension lets you work with a stack of patches in a Mercurial
11200 repository. It manages two stacks of patches - all known patches, and
11201 applied patches (subset of known patches).
11202 Known patches are represented as patch files in the .hg/patches direc‐
11204 tory. Applied patches are both patch files and changesets.
11205 Common tasks (use hg help COMMAND for more details):
11207 create new patch qnew
11209 import existing patch qimport
11210 print patch series qseries
11212 print applied patches qapplied
11213 add known patch to applied stack qpush
11215 remove patch from applied stack qpop
11216 refresh contents of top applied patch qrefresh
11217 By default, mq will automatically use git patches when required to
11219 avoid losing file mode changes, copy records, binary files or empty
11220 files creations or deletions. This behavior can be configured with:
11221 [mq]
11223 git = auto/keep/yes/no
11224 If set to 'keep', mq will obey the [diff] section configuration while
11226 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
11227 mq will override the [diff] section and always generate git or regular
11228 patches, possibly losing data in the second case.
11229 It may be desirable for mq changesets to be kept in the secret phase
11231 (see hg help phases), which can be enabled with the following setting:
11232 [mq]
11234 secret = True
11235 You will by default be managing a patch queue named "patches". You can
11237 create other, independent patch queues with the hg qqueue command.
11238 If the working directory contains uncommitted files, qpush, qpop and
11240 qgoto abort immediately. If -f/--force is used, the changes are dis‐
11241 carded. Setting:
11242 [mq]
11244 keepchanges = True
11245 make them behave as if --keep-changes were passed, and non-conflicting
11247 local changes will be tolerated and preserved. If incompatible options
11248 such as -f/--force or --exact are passed, this setting is ignored.
11249 This extension used to provide a strip command. This command now lives
11251 in the strip extension.
11252 Commands
11254 Repository creation
11255 qclone
11256 clone main and patch repository at same time:
11257 hg qclone [OPTION]... SOURCE [DEST]
11259 If source is local, destination will have no patches applied. If source
11261 is remote, this command can not check if patches are applied in source,
11262 so cannot guarantee that patches are not applied in destination. If you
11263 clone remote repository, be sure before that it has no patches applied.
11264 Source patch repository is looked for in <src>/.hg/patches by default.
11266 Use -p <url> to change.
11267 The patch directory must be a nested Mercurial repository, as would be
11269 created by hg init --mq.
11270 Return 0 on success.
11272 Options:
11274 --pull use pull protocol to copy metadata
11276 -U, --noupdate
11278 do not update the new working directories
11279 --uncompressed
11281 use uncompressed transfer (fast over LAN)
11282 -p,--patches <REPO>
11284 location of source patch repository
11285 -e,--ssh <CMD>
11287 specify ssh command to use
11288 --remotecmd <CMD>
11290 specify hg command to run on the remote side
11291 --insecure
11293 do not verify server certificate (ignoring web.cacerts config)
11294 qinit
11296 init a new queue repository (DEPRECATED):
11297 hg qinit [-c]
11299 The queue repository is unversioned by default. If -c/--create-repo is
11301 specified, qinit will create a separate nested repository for patches
11302 (qinit -c may also be run later to convert an unversioned patch reposi‐
11303 tory into a versioned one). You can use qcommit to commit changes to
11304 this queue repository.
11305 This command is deprecated. Without -c, it's implied by other relevant
11307 commands. With -c, use hg init --mq instead.
11308 Options:
11310 -c, --create-repo
11312 create queue repository
11313 Change creation
11315 qcommit
11316 commit changes in the queue repository (DEPRECATED):
11317 hg qcommit [OPTION]... [FILE]...
11319 This command is deprecated; use hg commit --mq instead.
11321 Options:
11323 -A, --addremove
11325 mark new/missing files as added/removed before committing
11326 --close-branch
11328 mark a branch head as closed
11329 --amend
11331 amend the parent of the working directory
11332 -s, --secret
11334 use the secret phase for committing
11335 -e, --edit
11337 invoke editor on commit messages
11338 --force-close-branch
11340 forcibly close branch from a non-head changeset (ADVANCED)
11341 -i, --interactive
11343 use interactive mode
11344 -I,--include <PATTERN[+]>
11346 include names matching the given patterns
11347 -X,--exclude <PATTERN[+]>
11349 exclude names matching the given patterns
11350 -m,--message <TEXT>
11352 use text as commit message
11353 -l,--logfile <FILE>
11355 read commit message from file
11356 -d,--date <DATE>
11358 record the specified date as commit date
11359 -u,--user <USER>
11361 record the specified user as committer
11362 -S, --subrepos
11364 recurse into subrepositories
11365 [+] marked option can be specified multiple times
11367 aliases: qci
11369 qnew
11371 create a new patch:
11372 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
11374 qnew creates a new patch on top of the currently-applied patch (if
11376 any). The patch will be initialized with any outstanding changes in the
11377 working directory. You may also use -I/--include, -X/--exclude, and/or
11378 a list of files after the patch name to add only changes to matching
11379 files to the new patch, leaving the rest as uncommitted modifications.
11380 -u/--user and -d/--date can be used to set the (given) user and date,
11382 respectively. -U/--currentuser and -D/--currentdate set user to current
11383 user and date to current date.
11384 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
11386 the commit message. If none is specified, the header is empty and the
11387 commit message is '[mq]: PATCH'.
11388 Use the -g/--git option to keep the patch in the git extended diff for‐
11390 mat. Read the diffs help topic for more information on why this is
11391 important for preserving permission changes and copy/rename informa‐
11392 tion.
11393 Returns 0 on successful creation of a new patch.
11395 Options:
11397 -e, --edit
11399 invoke editor on commit messages
11400 -f, --force
11402 import uncommitted changes (DEPRECATED)
11403 -g, --git
11405 use git extended diff format
11406 -U, --currentuser
11408 add "From: <current user>" to patch
11409 -u,--user <USER>
11411 add "From: <USER>" to patch
11412 -D, --currentdate
11414 add "Date: <current date>" to patch
11415 -d,--date <DATE>
11417 add "Date: <DATE>" to patch
11418 -I,--include <PATTERN[+]>
11420 include names matching the given patterns
11421 -X,--exclude <PATTERN[+]>
11423 exclude names matching the given patterns
11424 -m,--message <TEXT>
11426 use text as commit message
11427 -l,--logfile <FILE>
11429 read commit message from file
11430 [+] marked option can be specified multiple times
11432 qrefresh
11434 update the current patch:
11435 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
11437 If any file patterns are provided, the refreshed patch will contain
11439 only the modifications that match those patterns; the remaining modifi‐
11440 cations will remain in the working directory.
11441 If -s/--short is specified, files currently included in the patch will
11443 be refreshed just like matched files and remain in the patch.
11444 If -e/--edit is specified, Mercurial will start your configured editor
11446 for you to enter a message. In case qrefresh fails, you will find a
11447 backup of your message in .hg/last-message.txt.
11448 hg add/remove/copy/rename work as usual, though you might want to use
11450 git-style patches (-g/--git or [diff] git=1) to track copies and
11451 renames. See the diffs help topic for more information on the git diff
11452 format.
11453 Returns 0 on success.
11455 Options:
11457 -e, --edit
11459 invoke editor on commit messages
11460 -g, --git
11462 use git extended diff format
11463 -s, --short
11465 refresh only files already in the patch and specified files
11466 -U, --currentuser
11468 add/update author field in patch with current user
11469 -u,--user <USER>
11471 add/update author field in patch with given user
11472 -D, --currentdate
11474 add/update date field in patch with current date
11475 -d,--date <DATE>
11477 add/update date field in patch with given date
11478 -I,--include <PATTERN[+]>
11480 include names matching the given patterns
11481 -X,--exclude <PATTERN[+]>
11483 exclude names matching the given patterns
11484 -m,--message <TEXT>
11486 use text as commit message
11487 -l,--logfile <FILE>
11489 read commit message from file
11490 [+] marked option can be specified multiple times
11492 Change manipulation
11494 qfold
11495 fold the named patches into the current patch:
11496 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
11498 Patches must not yet be applied. Each patch will be successively
11500 applied to the current patch in the order given. If all the patches
11501 apply successfully, the current patch will be refreshed with the new
11502 cumulative patch, and the folded patches will be deleted. With
11503 -k/--keep, the folded patch files will not be removed afterwards.
11504 The header for each folded patch will be concatenated with the current
11506 patch header, separated by a line of * * *.
11507 Returns 0 on success.
11509 Options:
11511 -e, --edit
11513 invoke editor on commit messages
11514 -k, --keep
11516 keep folded patch files
11517 -m,--message <TEXT>
11519 use text as commit message
11520 -l,--logfile <FILE>
11522 read commit message from file
11523 Change organization
11525 qapplied
11526 print the patches already applied:
11527 hg qapplied [-1] [-s] [PATCH]
11529 Returns 0 on success.
11531 Options:
11533 -1, --last
11535 show only the preceding applied patch
11536 -s, --summary
11538 print first line of patch header
11539 qdelete
11541 remove patches from queue:
11542 hg qdelete [-k] [PATCH]...
11544 The patches must not be applied, and at least one patch is required.
11546 Exact patch identifiers must be given. With -k/--keep, the patch files
11547 are preserved in the patch directory.
11548 To stop managing a patch and move it into permanent history, use the hg
11550 qfinish command.
11551 Options:
11553 -k, --keep
11555 keep patch file
11556 -r,--rev <REV[+]>
11558 stop managing a revision (DEPRECATED)
11559 [+] marked option can be specified multiple times
11561 aliases: qremove qrm
11563 qfinish
11565 move applied patches into repository history:
11566 hg qfinish [-a] [REV]...
11568 Finishes the specified revisions (corresponding to applied patches) by
11570 moving them out of mq control into regular repository history.
11571 Accepts a revision range or the -a/--applied option. If --applied is
11573 specified, all applied mq revisions are removed from mq control. Other‐
11574 wise, the given revisions must be at the base of the stack of applied
11575 patches.
11576 This can be especially useful if your changes have been applied to an
11578 upstream repository, or if you are about to push your changes to
11579 upstream.
11580 Returns 0 on success.
11582 Options:
11584 -a, --applied
11586 finish all applied changesets
11587 qgoto
11589 push or pop patches until named patch is at top of stack:
11590 hg qgoto [OPTION]... PATCH
11592 Returns 0 on success.
11594 Options:
11596 --keep-changes
11598 tolerate non-conflicting local changes
11599 -f, --force
11601 overwrite any local changes
11602 --no-backup
11604 do not save backup copies of files
11605 qguard
11607 set or print guards for a patch:
11608 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
11610 Guards control whether a patch can be pushed. A patch with no guards is
11612 always pushed. A patch with a positive guard ("+foo") is pushed only if
11613 the hg qselect command has activated it. A patch with a negative guard
11614 ("-foo") is never pushed if the hg qselect command has activated it.
11615 With no arguments, print the currently active guards. With arguments,
11617 set guards for the named patch.
11618 Note Specifying negative guards now requires '--'.
11620 To set guards on another patch:
11622 hg qguard other.patch -- +2.6.17 -stable
11624 Returns 0 on success.
11626 Options:
11628 -l, --list
11630 list all patches and guards
11631 -n, --none
11633 drop all guards
11634 qheader
11636 print the header of the topmost or specified patch:
11637 hg qheader [PATCH]
11639 Returns 0 on success.
11641 qnext
11643 print the name of the next pushable patch:
11644 hg qnext [-s]
11646 Returns 0 on success.
11648 Options:
11650 -s, --summary
11652 print first line of patch header
11653 qpop
11655 pop the current patch off the stack:
11656 hg qpop [-a] [-f] [PATCH | INDEX]
11658 Without argument, pops off the top of the patch stack. If given a patch
11660 name, keeps popping off patches until the named patch is at the top of
11661 the stack.
11662 By default, abort if the working directory contains uncommitted
11664 changes. With --keep-changes, abort only if the uncommitted files over‐
11665 lap with patched files. With -f/--force, backup and discard changes
11666 made to such files.
11667 Return 0 on success.
11669 Options:
11671 -a, --all
11673 pop all patches
11674 -n,--name <NAME>
11676 queue name to pop (DEPRECATED)
11677 --keep-changes
11679 tolerate non-conflicting local changes
11680 -f, --force
11682 forget any local changes to patched files
11683 --no-backup
11685 do not save backup copies of files
11686 qprev
11688 print the name of the preceding applied patch:
11689 hg qprev [-s]
11691 Returns 0 on success.
11693 Options:
11695 -s, --summary
11697 print first line of patch header
11698 qpush
11700 push the next patch onto the stack:
11701 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
11703 By default, abort if the working directory contains uncommitted
11705 changes. With --keep-changes, abort only if the uncommitted files over‐
11706 lap with patched files. With -f/--force, backup and patch over uncom‐
11707 mitted changes.
11708 Return 0 on success.
11710 Options:
11712 --keep-changes
11714 tolerate non-conflicting local changes
11715 -f, --force
11717 apply on top of local changes
11718 -e, --exact
11720 apply the target patch to its recorded parent
11721 -l, --list
11723 list patch name in commit text
11724 -a, --all
11726 apply all patches
11727 -m, --merge
11729 merge from another queue (DEPRECATED)
11730 -n,--name <NAME>
11732 merge queue name (DEPRECATED)
11733 --move reorder patch series and apply only the patch
11735 --no-backup
11737 do not save backup copies of files
11738 qqueue
11740 manage multiple patch queues:
11741 hg qqueue [OPTION] [QUEUE]
11743 Supports switching between different patch queues, as well as creating
11745 new patch queues and deleting existing ones.
11746 Omitting a queue name or specifying -l/--list will show you the regis‐
11748 tered queues - by default the "normal" patches queue is registered. The
11749 currently active queue will be marked with "(active)". Specifying
11750 --active will print only the name of the active queue.
11751 To create a new queue, use -c/--create. The queue is automatically made
11753 active, except in the case where there are applied patches from the
11754 currently active queue in the repository. Then the queue will only be
11755 created and switching will fail.
11756 To delete an existing queue, use --delete. You cannot delete the cur‐
11758 rently active queue.
11759 Returns 0 on success.
11761 Options:
11763 -l, --list
11765 list all available queues
11766 --active
11768 print name of active queue
11769 -c, --create
11771 create new queue
11772 --rename
11774 rename active queue
11775 --delete
11777 delete reference to queue
11778 --purge
11780 delete queue, and remove patch dir
11781 qrename
11783 rename a patch:
11784 hg qrename PATCH1 [PATCH2]
11786 With one argument, renames the current patch to PATCH1. With two argu‐
11788 ments, renames PATCH1 to PATCH2.
11789 Returns 0 on success.
11791 aliases: qmv
11793 qrestore
11795 restore the queue state saved by a revision (DEPRECATED):
11796 hg qrestore [-d] [-u] REV
11798 This command is deprecated, use hg rebase instead.
11800 Options:
11802 -d, --delete
11804 delete save entry
11805 -u, --update
11807 update queue working directory
11808 qsave
11810 save current queue state (DEPRECATED):
11811 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
11813 This command is deprecated, use hg rebase instead.
11815 Options:
11817 -c, --copy
11819 copy patch directory
11820 -n,--name <NAME>
11822 copy directory name
11823 -e, --empty
11825 clear queue status file
11826 -f, --force
11828 force copy
11829 -m,--message <TEXT>
11831 use text as commit message
11832 -l,--logfile <FILE>
11834 read commit message from file
11835 qselect
11837 set or print guarded patches to push:
11838 hg qselect [OPTION]... [GUARD]...
11840 Use the hg qguard command to set or print guards on patch, then use
11842 qselect to tell mq which guards to use. A patch will be pushed if it
11843 has no guards or any positive guards match the currently selected
11844 guard, but will not be pushed if any negative guards match the current
11845 guard. For example:
11846 qguard foo.patch -- -stable (negative guard)
11848 qguard bar.patch +stable (positive guard)
11849 qselect stable
11850 This activates the "stable" guard. mq will skip foo.patch (because it
11852 has a negative match) but push bar.patch (because it has a positive
11853 match).
11854 With no arguments, prints the currently active guards. With one argu‐
11856 ment, sets the active guard.
11857 Use -n/--none to deactivate guards (no other arguments needed). When
11859 no guards are active, patches with positive guards are skipped and
11860 patches with negative guards are pushed.
11861 qselect can change the guards on applied patches. It does not pop
11863 guarded patches by default. Use --pop to pop back to the last applied
11864 patch that is not guarded. Use --reapply (which implies --pop) to push
11865 back to the current patch afterwards, but skip guarded patches.
11866 Use -s/--series to print a list of all guards in the series file (no
11868 other arguments needed). Use -v for more information.
11869 Returns 0 on success.
11871 Options:
11873 -n, --none
11875 disable all guards
11876 -s, --series
11878 list all guards in series file
11879 --pop pop to before first guarded applied patch
11881 --reapply
11883 pop, then reapply patches
11884 qseries
11886 print the entire series file:
11887 hg qseries [-ms]
11889 Returns 0 on success.
11891 Options:
11893 -m, --missing
11895 print patches not in series
11896 -s, --summary
11898 print first line of patch header
11899 qtop
11901 print the name of the current patch:
11902 hg qtop [-s]
11904 Returns 0 on success.
11906 Options:
11908 -s, --summary
11910 print first line of patch header
11911 qunapplied
11913 print the patches not yet applied:
11914 hg qunapplied [-1] [-s] [PATCH]
11916 Returns 0 on success.
11918 Options:
11920 -1, --first
11922 show only the first patch
11923 -s, --summary
11925 print first line of patch header
11926 File content management
11928 qdiff
11929 diff of the current patch and subsequent modifications:
11930 hg qdiff [OPTION]... [FILE]...
11932 Shows a diff which includes the current patch as well as any changes
11934 which have been made in the working directory since the last refresh
11935 (thus showing what the current patch would become after a qrefresh).
11936 Use hg diff if you only want to see the changes made since the last
11938 qrefresh, or hg export qtip if you want to see changes made by the cur‐
11939 rent patch without including changes made since the qrefresh.
11940 Returns 0 on success.
11942 Options:
11944 -a, --text
11946 treat all files as text
11947 -g, --git
11949 use git extended diff format
11950 --binary
11952 generate binary diffs in git mode (default)
11953 --nodates
11955 omit dates from diff headers
11956 --noprefix
11958 omit a/ and b/ prefixes from filenames
11959 -p, --show-function
11961 show which function each change is in
11962 --reverse
11964 produce a diff that undoes the changes
11965 -w, --ignore-all-space
11967 ignore white space when comparing lines
11968 -b, --ignore-space-change
11970 ignore changes in the amount of white space
11971 -B, --ignore-blank-lines
11973 ignore changes whose lines are all blank
11974 -Z, --ignore-space-at-eol
11976 ignore changes in whitespace at EOL
11977 -U,--unified <NUM>
11979 number of lines of context to show
11980 --stat output diffstat-style summary of changes
11982 --root <DIR>
11984 produce diffs relative to subdirectory
11985 -I,--include <PATTERN[+]>
11987 include names matching the given patterns
11988 -X,--exclude <PATTERN[+]>
11990 exclude names matching the given patterns
11991 [+] marked option can be specified multiple times
11993 Change import/export
11995 qimport
11996 import a patch or existing changeset:
11997 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
11999 The patch is inserted into the series after the last applied patch. If
12001 no patches have been applied, qimport prepends the patch to the series.
12002 The patch will have the same name as its source file unless you give it
12004 a new one with -n/--name.
12005 You can register an existing patch inside the patch directory with the
12007 -e/--existing flag.
12008 With -f/--force, an existing patch of the same name will be overwrit‐
12010 ten.
12011 An existing changeset may be placed under mq control with -r/--rev
12013 (e.g. qimport --rev . -n patch will place the current revision under mq
12014 control). With -g/--git, patches imported with --rev will use the git
12015 diff format. See the diffs help topic for information on why this is
12016 important for preserving rename/copy information and permission
12017 changes. Use hg qfinish to remove changesets from mq control.
12018 To import a patch from standard input, pass - as the patch file. When
12020 importing from standard input, a patch name must be specified using the
12021 --name flag.
12022 To import an existing patch while renaming it:
12024 hg qimport -e existing-patch -n new-name
12026 Returns 0 if import succeeded.
12028 Options:
12030 -e, --existing
12032 import file in patch directory
12033 -n,--name <NAME>
12035 name of patch file
12036 -f, --force
12038 overwrite existing files
12039 -r,--rev <REV[+]>
12041 place existing revisions under mq control
12042 -g, --git
12044 use git extended diff format
12045 -P, --push
12047 qpush after importing
12048 [+] marked option can be specified multiple times
12050 narrow
12052 create clones which fetch history data for subset of files (EXPERIMEN‐
12053 TAL)
12054 Commands
12056 Repository maintenance
12057 tracked
12058 show or change the current narrowspec:
12059 hg tracked [OPTIONS]... [REMOTE]
12061 With no argument, shows the current narrowspec entries, one per line.
12063 Each line will be prefixed with 'I' or 'X' for included or excluded
12064 patterns, respectively.
12065 The narrowspec is comprised of expressions to match remote files and/or
12067 directories that should be pulled into your client. The narrowspec has
12068 include and exclude expressions, with excludes always trumping
12069 includes: that is, if a file matches an exclude expression, it will be
12070 excluded even if it also matches an include expression. Excluding
12071 files that were never included has no effect.
12072 Each included or excluded entry is in the format described by 'hg help
12074 patterns'.
12075 The options allow you to add or remove included and excluded expres‐
12077 sions.
12078 If --clear is specified, then all previous includes and excludes are
12080 DROPPED and replaced by the new ones specified to --addinclude and
12081 --addexclude. If --clear is specified without any further options, the
12082 narrowspec will be empty and will not match any files.
12083 If --auto-remove-includes is specified, then those includes that don't
12085 match any files modified by currently visible local commits (those not
12086 shared by the remote) will be added to the set of explicitly specified
12087 includes to remove.
12088 --import-rules accepts a path to a file containing rules, allowing you
12090 to add --addinclude, --addexclude rules in bulk. Like the other include
12091 and exclude switches, the changes are applied immediately.
12092 Options:
12094 --addinclude <VALUE[+]>
12096 new paths to include
12097 --removeinclude <VALUE[+]>
12099 old paths to no longer include
12100 --auto-remove-includes
12102 automatically choose unused includes to remove
12103 --addexclude <VALUE[+]>
12105 new paths to exclude
12106 --import-rules <VALUE>
12108 import narrowspecs from a file
12109 --removeexclude <VALUE[+]>
12111 old paths to no longer exclude
12112 --clear
12114 whether to replace the existing narrowspec
12115 --force-delete-local-changes
12117 forces deletion of local changes when narrowing
12118 --update-working-copy
12120 update working copy when the store has changed
12121 -e,--ssh <CMD>
12123 specify ssh command to use
12124 --remotecmd <CMD>
12126 specify hg command to run on the remote side
12127 --insecure
12129 do not verify server certificate (ignoring web.cacerts config)
12130 [+] marked option can be specified multiple times
12132 notify
12134 hooks for sending email push notifications
12135 This extension implements hooks to send email notifications when
12137 changesets are sent from or received by the local repository.
12138 First, enable the extension as explained in hg help extensions, and
12140 register the hook you want to run. incoming and changegroup hooks are
12141 run when changesets are received, while outgoing hooks are for change‐
12142 sets sent to another repository:
12143 [hooks]
12145 # one email for each incoming changeset
12146 incoming.notify = python:hgext.notify.hook
12147 # one email for all incoming changesets
12148 changegroup.notify = python:hgext.notify.hook
12149 # one email for all outgoing changesets
12151 outgoing.notify = python:hgext.notify.hook
12152 This registers the hooks. To enable notification, subscribers must be
12154 assigned to repositories. The [usersubs] section maps multiple reposi‐
12155 tories to a given recipient. The [reposubs] section maps multiple
12156 recipients to a single repository:
12157 [usersubs]
12159 # key is subscriber email, value is a comma-separated list of repo patterns
12160 user@host = pattern
12161 [reposubs]
12163 # key is repo pattern, value is a comma-separated list of subscriber emails
12164 pattern = user@host
12165 A pattern is a glob matching the absolute path to a repository, option‐
12167 ally combined with a revset expression. A revset expression, if
12168 present, is separated from the glob by a hash. Example:
12169 [reposubs]
12171 */widgets#branch(release) = qa-team@example.com
12172 This sends to qa-team@example.com whenever a changeset on the release
12174 branch triggers a notification in any repository ending in widgets.
12175 In order to place them under direct user management, [usersubs] and
12177 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
12178 rated by reference:
12179 [notify]
12181 config = /path/to/subscriptionsfile
12182 Notifications will not be sent until the notify.test value is set to
12184 False; see below.
12185 Notifications content can be tweaked with the following configuration
12187 entries:
12188 notify.test
12190 If True, print messages to stdout instead of sending them.
12191 Default: True.
12192 notify.sources
12194 Space-separated list of change sources. Notifications are acti‐
12195 vated only when a changeset's source is in this list. Sources
12196 may be:
12197 serve
12199 changesets received via http or ssh
12201 pull
12203 changesets received via hg pull
12205 unbundle
12207 changesets received via hg unbundle
12209 push
12211 changesets sent or received via hg push
12213 bundle
12215 changesets sent via hg unbundle
12217 Default: serve.
12219 notify.strip
12221 Number of leading slashes to strip from url paths. By default,
12222 notifications reference repositories with their absolute path.
12223 notify.strip lets you turn them into relative paths. For exam‐
12224 ple, notify.strip=3 will change /long/path/repository into
12225 repository. Default: 0.
12226 notify.domain
12228 Default email domain for sender or recipients with no explicit
12229 domain. It is also used for the domain part of the Message-Id
12230 when using notify.messageidseed.
12231 notify.messageidseed
12233 Create deterministic Message-Id headers for the mails based on
12234 the seed and the revision identifier of the first commit in the
12235 changeset.
12236 notify.style
12238 Style file to use when formatting emails.
12239 notify.template
12241 Template to use when formatting emails.
12242 notify.incoming
12244 Template to use when run as an incoming hook, overriding
12245 notify.template.
12246 notify.outgoing
12248 Template to use when run as an outgoing hook, overriding
12249 notify.template.
12250 notify.changegroup
12252 Template to use when running as a changegroup hook, overriding
12253 notify.template.
12254 notify.maxdiff
12256 Maximum number of diff lines to include in notification email.
12257 Set to 0 to disable the diff, or -1 to include all of it.
12258 Default: 300.
12259 notify.maxdiffstat
12261 Maximum number of diffstat lines to include in notification
12262 email. Set to -1 to include all of it. Default: -1.
12263 notify.maxsubject
12265 Maximum number of characters in email's subject line. Default:
12266 67.
12267 notify.diffstat
12269 Set to True to include a diffstat before diff content. Default:
12270 True.
12271 notify.showfunc
12273 If set, override diff.showfunc for the diff content. Default:
12274 None.
12275 notify.merge
12277 If True, send notifications for merge changesets. Default: True.
12278 notify.mbox
12280 If set, append mails to this mbox file instead of sending.
12281 Default: None.
12282 notify.fromauthor
12284 If set, use the committer of the first changeset in a change‐
12285 group for the "From" field of the notification mail. If not set,
12286 take the user from the pushing repo. Default: False.
12287 If set, the following entries will also be used to customize the noti‐
12289 fications:
12290 email.from
12292 Email From address to use if none can be found in the generated
12293 email content.
12294 web.baseurl
12296 Root repository URL to combine with repository paths when making
12297 references. See also notify.strip.
12298 pager
12300 browse command output with an external pager (DEPRECATED)
12301 Forcibly enable paging for individual commands that don't typically
12303 request pagination with the attend-<command> option. This setting takes
12304 precedence over ignore options and defaults:
12305 [pager]
12307 attend-cat = false
12308 patchbomb
12310 command to send changesets as (a series of) patch emails
12311 The series is started off with a "[PATCH 0 of N]" introduction, which
12313 describes the series as a whole.
12314 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12316 first line of the changeset description as the subject text. The mes‐
12317 sage contains two or three body parts:
12318 · The changeset description.
12320 · [Optional] The result of running diffstat on the patch.
12322 · The patch itself, as generated by hg export.
12324 Each message refers to the first in the series using the In-Reply-To
12326 and References headers, so they will show up as a sequence in threaded
12327 mail and news readers, and in mail archives.
12328 To configure other defaults, add a section like this to your configura‐
12330 tion file:
12331 [email]
12333 from = My Name <my@email>
12334 to = recipient1, recipient2, ...
12335 cc = cc1, cc2, ...
12336 bcc = bcc1, bcc2, ...
12337 reply-to = address1, address2, ...
12338 Use [patchbomb] as configuration section name if you need to override
12340 global [email] address settings.
12341 Then you can use the hg email command to mail a series of changesets as
12343 a patchbomb.
12344 You can also either configure the method option in the email section to
12346 be a sendmail compatible mailer or fill out the [smtp] section so that
12347 the patchbomb extension can automatically send patchbombs directly from
12348 the commandline. See the [email] and [smtp] sections in hgrc(5) for
12349 details.
12350 By default, hg email will prompt for a To or CC header if you do not
12352 supply one via configuration or the command line. You can override
12353 this to never prompt by configuring an empty value:
12354 [email]
12356 cc =
12357 You can control the default inclusion of an introduction message with
12359 the patchbomb.intro configuration option. The configuration is always
12360 overwritten by command line flags like --intro and --desc:
12361 [patchbomb]
12363 intro=auto # include introduction message if more than 1 patch (default)
12364 intro=never # never include an introduction message
12365 intro=always # always include an introduction message
12366 You can specify a template for flags to be added in subject prefixes.
12368 Flags specified by --flag option are exported as {flags} keyword:
12369 [patchbomb]
12371 flagtemplate = "{separate(' ',
12372 ifeq(branch, 'default', '', branch|upper),
12373 flags)}"
12374 You can set patchbomb to always ask for confirmation by setting patch‐
12376 bomb.confirm to true.
12377 Commands
12379 Change import/export
12380 email
12381 send changesets by email:
12382 hg email [OPTION]... [DEST]...
12384 By default, diffs are sent in the format generated by hg export, one
12386 per message. The series starts with a "[PATCH 0 of N]" introduction,
12387 which describes the series as a whole.
12388 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12390 first line of the changeset description as the subject text. The mes‐
12391 sage contains two or three parts. First, the changeset description.
12392 With the -d/--diffstat option, if the diffstat program is installed,
12394 the result of running diffstat on the patch is inserted.
12395 Finally, the patch itself, as generated by hg export.
12397 With the -d/--diffstat or --confirm options, you will be presented with
12399 a final summary of all messages and asked for confirmation before the
12400 messages are sent.
12401 By default the patch is included as text in the email body for easy
12403 reviewing. Using the -a/--attach option will instead create an attach‐
12404 ment for the patch. With -i/--inline an inline attachment will be cre‐
12405 ated. You can include a patch both as text in the email body and as a
12406 regular or an inline attachment by combining the -a/--attach or
12407 -i/--inline with the --body option.
12408 With -B/--bookmark changesets reachable by the given bookmark are
12410 selected.
12411 With -o/--outgoing, emails will be generated for patches not found in
12413 the destination repository (or only those which are ancestors of the
12414 specified revisions if any are provided)
12415 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
12417 gle email containing a binary Mercurial bundle as an attachment will be
12418 sent. Use the patchbomb.bundletype config option to control the bundle
12419 type as with hg bundle --type.
12420 With -m/--mbox, instead of previewing each patchbomb message in a pager
12422 or sending the messages directly, it will create a UNIX mailbox file
12423 with the patch emails. This mailbox file can be previewed with any mail
12424 user agent which supports UNIX mbox files.
12425 With -n/--test, all steps will run, but mail will not be sent. You
12427 will be prompted for an email recipient address, a subject and an
12428 introductory message describing the patches of your patchbomb. Then
12429 when all is done, patchbomb messages are displayed.
12430 In case email sending fails, you will find a backup of your series
12432 introductory message in .hg/last-email.txt.
12433 The default behavior of this command can be customized through configu‐
12435 ration. (See hg help patchbomb for details)
12436 Examples:
12438 hg email -r 3000 # send patch 3000 only
12440 hg email -r 3000 -r 3001 # send patches 3000 and 3001
12441 hg email -r 3000:3005 # send patches 3000 through 3005
12442 hg email 3000 # send patch 3000 (deprecated)
12443 hg email -o # send all patches not in default
12445 hg email -o DEST # send all patches not in DEST
12446 hg email -o -r 3000 # send all ancestors of 3000 not in default
12447 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
12448 hg email -B feature # send all ancestors of feature bookmark
12450 hg email -b # send bundle of all patches not in default
12452 hg email -b DEST # send bundle of all patches not in DEST
12453 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
12454 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
12455 hg email -o -m mbox && # generate an mbox file...
12457 mutt -R -f mbox # ... and view it with mutt
12458 hg email -o -m mbox && # generate an mbox file ...
12459 formail -s sendmail \ # ... and use formail to send from the mbox
12460 -bm -t < mbox # ... using sendmail
12461 Before using this command, you will need to enable email in your hgrc.
12463 See the [email] section in hgrc(5) for details.
12464 Options:
12466 -g, --git
12468 use git extended diff format
12469 --plain
12471 omit hg patch header
12472 -o, --outgoing
12474 send changes not found in the target repository
12475 -b, --bundle
12477 send changes not in target as a binary bundle
12478 -B,--bookmark <BOOKMARK>
12480 send changes only reachable by given bookmark
12481 --bundlename <NAME>
12483 name of the bundle attachment file (default: bundle)
12484 -r,--rev <REV[+]>
12486 a revision to send
12487 --force
12489 run even when remote repository is unrelated (with -b/--bundle)
12490 --base <REV[+]>
12492 a base changeset to specify instead of a destination (with
12493 -b/--bundle)
12494 --intro
12496 send an introduction email for a single patch
12497 --body send patches as inline message text (default)
12499 -a, --attach
12501 send patches as attachments
12502 -i, --inline
12504 send patches as inline attachments
12505 --bcc <EMAIL[+]>
12507 email addresses of blind carbon copy recipients
12508 -c,--cc <EMAIL[+]>
12510 email addresses of copy recipients
12511 --confirm
12513 ask for confirmation before sending
12514 -d, --diffstat
12516 add diffstat output to messages
12517 --date <DATE>
12519 use the given date as the sending date
12520 --desc <FILE>
12522 use the given file as the series description
12523 -f,--from <EMAIL>
12525 email address of sender
12526 -n, --test
12528 print messages that would be sent
12529 -m,--mbox <FILE>
12531 write messages to mbox file instead of sending them
12532 --reply-to <EMAIL[+]>
12534 email addresses replies should be sent to
12535 -s,--subject <TEXT>
12537 subject of first message (intro or single patch)
12538 --in-reply-to <MSGID>
12540 message identifier to reply to
12541 --flag <FLAG[+]>
12543 flags to add in subject prefixes
12544 -t,--to <EMAIL[+]>
12546 email addresses of recipients
12547 -e,--ssh <CMD>
12549 specify ssh command to use
12550 --remotecmd <CMD>
12552 specify hg command to run on the remote side
12553 --insecure
12555 do not verify server certificate (ignoring web.cacerts config)
12556 [+] marked option can be specified multiple times
12558 phabricator
12560 simple Phabricator integration (EXPERIMENTAL)
12561 This extension provides a phabsend command which sends a stack of
12563 changesets to Phabricator, and a phabread command which prints a stack
12564 of revisions in a format suitable for hg import, and a phabupdate com‐
12565 mand to update statuses in batch.
12566 By default, Phabricator requires Test Plan which might prevent some
12568 changeset from being sent. The requirement could be disabled by chang‐
12569 ing differential.require-test-plan-field config server side.
12570 Config:
12572 [phabricator]
12574 # Phabricator URL
12575 url = https://phab.example.com/
12576 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
12578 # callsign is "FOO".
12579 callsign = FOO
12580 # curl command to use. If not set (default), use builtin HTTP library to
12582 # communicate. If set, use the specified curl command. This could be useful
12583 # if you need to specify advanced options that is not easily supported by
12584 # the internal library.
12585 curlcmd = curl --connect-timeout 2 --retry 3 --silent
12586 [auth]
12588 example.schemes = https
12589 example.prefix = phab.example.com
12590 # API token. Get it from https://$HOST/conduit/login/
12592 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
12593 Commands
12595 Change import/export
12596 phabread
12597 print patches from Phabricator suitable for importing:
12598 hg phabread DREVSPEC [OPTIONS]
12600 DREVSPEC could be a Differential Revision identity, like D123, or just
12602 the number 123. It could also have common operators like +, -, &, (, )
12603 for complex queries. Prefix : could be used to select a stack.
12604 abandoned, accepted, closed, needsreview, needsrevision could be used
12606 to filter patches by status. For performance reason, they only repre‐
12607 sent a subset of non-status selections and cannot be used alone.
12608 For example, :D6+8-(2+D4) selects a stack up to D6, plus D8 and exclude
12610 D2 and D4. :D9 & needsreview selects "Needs Review" revisions in a
12611 stack up to D9.
12612 If --stack is given, follow dependencies information and read all
12614 patches. It is equivalent to the : operator.
12615 Options:
12617 --stack
12619 read dependencies
12620 --test-vcr <VALUE>
12622 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12623 script, otherwise will mock all http requests using the speci‐
12624 fied vcr file. (ADVANCED)
12625 phabsend
12627 upload changesets to Phabricator:
12628 hg phabsend REV [OPTIONS]
12630 If there are multiple revisions specified, they will be send as a stack
12632 with a linear dependencies relationship using the order specified by
12633 the revset.
12634 For the first time uploading changesets, local tags will be created to
12636 maintain the association. After the first time, phabsend will check
12637 obsstore and tags information so it can figure out whether to update an
12638 existing Differential Revision, or create a new one.
12639 If --amend is set, update commit messages so they have the Differential
12641 Revision URL, remove related tags. This is similar to what arcanist
12642 will do, and is more desired in author-push workflows. Otherwise, use
12643 local tags to record the Differential Revision association.
12644 The --confirm option lets you confirm changesets before sending them.
12646 You can also add following to your configuration file to make it
12647 default behaviour:
12648 [phabsend]
12650 confirm = true
12651 phabsend will check obsstore and the above association to decide
12653 whether to update an existing Differential Revision, or create a new
12654 one.
12655 Options:
12657 -r,--rev <REV[+]>
12659 revisions to send
12660 --amend
12662 update commit messages (default: )
12663 --reviewer <VALUE[+]>
12665 specify reviewers
12666 --blocker <VALUE[+]>
12668 specify blocking reviewers
12669 -m,--comment <VALUE>
12671 add a comment to Revisions with new/updated Diffs
12672 --confirm
12674 ask for confirmation before sending
12675 --test-vcr <VALUE>
12677 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12678 script, otherwise will mock all http requests using the speci‐
12679 fied vcr file. (ADVANCED)
12680 [+] marked option can be specified multiple times
12682 phabupdate
12684 update Differential Revision in batch:
12685 hg phabupdate DREVSPEC [OPTIONS]
12687 DREVSPEC selects revisions. See hg help phabread for its usage.
12689 Options:
12691 --accept
12693 accept revisions
12694 --reject
12696 reject revisions
12697 --abandon
12699 abandon revisions
12700 --reclaim
12702 reclaim revisions
12703 -m,--comment <VALUE>
12705 comment on the last revision
12706 --test-vcr <VALUE>
12708 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12709 script, otherwise will mock all http requests using the speci‐
12710 fied vcr file. (ADVANCED)
12711 Uncategorized commands
12713 purge
12714 command to delete untracked files from the working directory
12715 Commands
12717 Repository maintenance
12718 purge
12719 removes files not tracked by Mercurial:
12720 hg purge [OPTION]... [DIR]...
12722 Delete files not known to Mercurial. This is useful to test local and
12724 uncommitted changes in an otherwise-clean source tree.
12725 This means that purge will delete the following by default:
12727 · Unknown files: files marked with "?" by hg status
12729 · Empty directories: in fact Mercurial ignores directories unless they
12731 contain files under source control management
12732 But it will leave untouched:
12734 · Modified and unmodified tracked files
12736 · Ignored files (unless --all is specified)
12738 · New files added to the repository (with hg add)
12740 The --files and --dirs options can be used to direct purge to delete
12742 only files, only directories, or both. If neither option is given, both
12743 will be deleted.
12744 If directories are given on the command line, only files in these
12746 directories are considered.
12747 Be careful with purge, as you could irreversibly delete some files you
12749 forgot to add to the repository. If you only want to print the list of
12750 files that this program would delete, use the --print option.
12751 Options:
12753 -a, --abort-on-err
12755 abort if an error occurs
12756 --all purge ignored files too
12758 --dirs purge empty directories
12760 --files
12762 purge files
12763 -p, --print
12765 print filenames instead of deleting them
12766 -0, --print0
12768 end filenames with NUL, for use with xargs (implies -p/--print)
12769 -I,--include <PATTERN[+]>
12771 include names matching the given patterns
12772 -X,--exclude <PATTERN[+]>
12774 exclude names matching the given patterns
12775 [+] marked option can be specified multiple times
12777 aliases: clean
12779 rebase
12781 command to move sets of revisions to a different ancestor
12782 This extension lets you rebase changesets in an existing Mercurial
12784 repository.
12785 For more information: https://mercurial-scm.org/wiki/RebaseExtension
12787 Commands
12789 Change manipulation
12790 rebase
12791 move changeset (and descendants) to a different branch:
12792 hg rebase [-s REV | -b REV] [-d REV] [OPTION]
12794 Rebase uses repeated merging to graft changesets from one part of his‐
12796 tory (the source) onto another (the destination). This can be useful
12797 for linearizing local changes relative to a master development tree.
12798 Published commits cannot be rebased (see hg help phases). To copy com‐
12800 mits, see hg help graft.
12801 If you don't specify a destination changeset (-d/--dest), rebase will
12803 use the same logic as hg merge to pick a destination. if the current
12804 branch contains exactly one other head, the other head is merged with
12805 by default. Otherwise, an explicit revision with which to merge with
12806 must be provided. (destination changeset is not modified by rebasing,
12807 but new changesets are added as its descendants.)
12808 Here are the ways to select changesets:
12810 1. Explicitly select them using --rev.
12812 2. Use --source to select a root changeset and include all of its
12814 descendants.
12815 3. Use --base to select a changeset; rebase will find ancestors and
12817 their descendants which are not also ancestors of the destina‐
12818 tion.
12819 4. If you do not specify any of --rev, --source, or --base, rebase
12821 will use --base . as above.
12822 If --source or --rev is used, special names SRC and ALLSRC can be used
12824 in --dest. Destination would be calculated per source revision with SRC
12825 substituted by that single source revision and ALLSRC substituted by
12826 all source revisions.
12827 Rebase will destroy original changesets unless you use --keep. It will
12829 also move your bookmarks (even if you do).
12830 Some changesets may be dropped if they do not contribute changes (e.g.
12832 merges from the destination branch).
12833 Unlike merge, rebase will do nothing if you are at the branch tip of a
12835 named branch with two heads. You will need to explicitly specify source
12836 and/or destination.
12837 If you need to use a tool to automate merge/conflict decisions, you can
12839 specify one with --tool, see hg help merge-tools. As a caveat: the
12840 tool will not be used to mediate when a file was deleted, there is no
12841 hook presently available for this.
12842 If a rebase is interrupted to manually resolve a conflict, it can be
12844 continued with --continue/-c, aborted with --abort/-a, or stopped with
12845 --stop.
12846 Examples:
12848 · move "local changes" (current commit back to branching point) to the
12850 current branch tip after a pull:
12851 hg rebase
12853 · move a single changeset to the stable branch:
12855 hg rebase -r 5f493448 -d stable
12857 · splice a commit and all its descendants onto another part of history:
12859 hg rebase --source c0c3 --dest 4cf9
12861 · rebase everything on a branch marked by a bookmark onto the default
12863 branch:
12864 hg rebase --base myfeature --dest default
12866 · collapse a sequence of changes into a single commit:
12868 hg rebase --collapse -r 1520:1525 -d .
12870 · move a named branch while preserving its name:
12872 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
12874 · stabilize orphaned changesets so history looks linear:
12876 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
12878 Configuration Options:
12880 You can make rebase require a destination if you set the following con‐
12882 fig option:
12883 [commands]
12885 rebase.requiredest = True
12886 By default, rebase will close the transaction after each commit. For
12888 performance purposes, you can configure rebase to use a single transac‐
12889 tion across the entire rebase. WARNING: This setting introduces a sig‐
12890 nificant risk of losing the work you've done in a rebase if the rebase
12891 aborts unexpectedly:
12892 [rebase]
12894 singletransaction = True
12895 By default, rebase writes to the working copy, but you can configure it
12897 to run in-memory for better performance. When the rebase is not moving
12898 the parent(s) of the working copy (AKA the "currently checked out
12899 changesets"), this may also allow it to run even if the working copy is
12900 dirty:
12901 [rebase]
12903 experimental.inmemory = True
12904 Return Values:
12906 Returns 0 on success, 1 if nothing to rebase or there are unresolved
12908 conflicts.
12909 Options:
12911 -s,--source <REV>
12913 rebase the specified changeset and descendants
12914 -b,--base <REV>
12916 rebase everything from branching point of specified changeset
12917 -r,--rev <REV[+]>
12919 rebase these revisions
12920 -d,--dest <REV>
12922 rebase onto the specified changeset
12923 --collapse
12925 collapse the rebased changesets
12926 -m,--message <TEXT>
12928 use text as collapse commit message
12929 -e, --edit
12931 invoke editor on commit messages
12932 -l,--logfile <FILE>
12934 read collapse commit message from file
12935 -k, --keep
12937 keep original changesets
12938 --keepbranches
12940 keep original branch names
12941 -D, --detach
12943 (DEPRECATED)
12944 -i, --interactive
12946 (DEPRECATED)
12947 -t,--tool <VALUE>
12949 specify merge tool
12950 --stop stop interrupted rebase
12952 -c, --continue
12954 continue an interrupted rebase
12955 -a, --abort
12957 abort an interrupted rebase
12958 --auto-orphans <VALUE>
12960 automatically rebase orphan revisions in the specified revset
12961 (EXPERIMENTAL)
12962 -n, --dry-run
12964 do not perform actions, just print output
12965 -T,--template <TEMPLATE>
12967 display with template
12968 --confirm
12970 ask before applying actions
12971 [+] marked option can be specified multiple times
12973 record
12975 commands to interactively select changes for commit/qrefresh (DEPRE‐
12976 CATED)
12977 The feature provided by this extension has been moved into core Mercu‐
12979 rial as hg commit --interactive.
12980 Commands
12982 Change creation
12983 qrecord
12984 interactively record a new patch:
12985 hg qrecord [OPTION]... PATCH [FILE]...
12987 See hg help qnew & hg help record for more information and usage.
12989 record
12991 interactively select changes to commit:
12992 hg record [OPTION]... [FILE]...
12994 If a list of files is omitted, all changes reported by hg status will
12996 be candidates for recording.
12997 See hg help dates for a list of formats valid for -d/--date.
12999 If using the text interface (see hg help config), you will be prompted
13001 for whether to record changes to each modified file, and for files with
13002 multiple changes, for each change to use. For each query, the following
13003 responses are possible:
13004 y - record this change
13006 n - skip this change
13007 e - edit this change manually
13008 s - skip remaining changes to this file
13010 f - record remaining changes to this file
13011 d - done, skip remaining changes and files
13013 a - record all changes to all remaining files
13014 q - quit, recording no changes
13015 ? - display help
13017 This command is not available when committing a merge.
13019 Options:
13021 -A, --addremove
13023 mark new/missing files as added/removed before committing
13024 --close-branch
13026 mark a branch head as closed
13027 --amend
13029 amend the parent of the working directory
13030 -s, --secret
13032 use the secret phase for committing
13033 -e, --edit
13035 invoke editor on commit messages
13036 --force-close-branch
13038 forcibly close branch from a non-head changeset (ADVANCED)
13039 -I,--include <PATTERN[+]>
13041 include names matching the given patterns
13042 -X,--exclude <PATTERN[+]>
13044 exclude names matching the given patterns
13045 -m,--message <TEXT>
13047 use text as commit message
13048 -l,--logfile <FILE>
13050 read commit message from file
13051 -d,--date <DATE>
13053 record the specified date as commit date
13054 -u,--user <USER>
13056 record the specified user as committer
13057 -S, --subrepos
13059 recurse into subrepositories
13060 -w, --ignore-all-space
13062 ignore white space when comparing lines
13063 -b, --ignore-space-change
13065 ignore changes in the amount of white space
13066 -B, --ignore-blank-lines
13068 ignore changes whose lines are all blank
13069 -Z, --ignore-space-at-eol
13071 ignore changes in whitespace at EOL
13072 [+] marked option can be specified multiple times
13074 releasenotes
13076 generate release notes from commit messages (EXPERIMENTAL)
13077 It is common to maintain files detailing changes in a project between
13079 releases. Maintaining these files can be difficult and time consuming.
13080 The hg releasenotes command provided by this extension makes the
13081 process simpler by automating it.
13082 Commands
13084 Change navigation
13085 releasenotes
13086 parse release notes from commit messages into an output file:
13087 hg releasenotes [-r REV] [-c] FILE
13089 Given an output file and set of revisions, this command will parse com‐
13091 mit messages for release notes then add them to the output file.
13092 Release notes are defined in commit messages as ReStructuredText direc‐
13094 tives. These have the form:
13095 .. directive:: title
13097 content
13099 Each directive maps to an output section in a generated release notes
13101 file, which itself is ReStructuredText. For example, the .. feature::
13102 directive would map to a New Features section.
13103 Release note directives can be either short-form or long-form. In
13105 short- form, title is omitted and the release note is rendered as a
13106 bullet list. In long form, a sub-section with the title title is added
13107 to the section.
13108 The FILE argument controls the output file to write gathered release
13110 notes to. The format of the file is:
13111 Section 1
13113 =========
13114 ...
13116 Section 2
13118 =========
13119 ...
13121 Only sections with defined release notes are emitted.
13123 If a section only has short-form notes, it will consist of bullet list:
13125 Section
13127 =======
13128 * Release note 1
13130 * Release note 2
13131 If a section has long-form notes, sub-sections will be emitted:
13133 Section
13135 =======
13136 Note 1 Title
13138 ------------
13139 Description of the first long-form note.
13141 Note 2 Title
13143 ------------
13144 Description of the second long-form note.
13146 If the FILE argument points to an existing file, that file will be
13148 parsed for release notes having the format that would be generated by
13149 this command. The notes from the processed commit messages will be
13150 merged into this parsed set.
13151 During release notes merging:
13153 · Duplicate items are automatically ignored
13155 · Items that are different are automatically ignored if the similarity
13157 is greater than a threshold.
13158 This means that the release notes file can be updated independently
13160 from this command and changes should not be lost when running this com‐
13161 mand on that file. A particular use case for this is to tweak the word‐
13162 ing of a release note after it has been added to the release notes
13163 file.
13164 The -c/--check option checks the commit message for invalid admoni‐
13166 tions.
13167 The -l/--list option, presents the user with a list of existing avail‐
13169 able admonitions along with their title. This also includes the custom
13170 admonitions (if any).
13171 Options:
13173 -r,--rev <REV>
13175 revisions to process for release notes
13176 -c, --check
13178 checks for validity of admonitions (if any)
13179 -l, --list
13181 list the available admonitions with their title
13182 Uncategorized commands
13184 relink
13185 recreates hardlinks between repository clones
13186 Commands
13188 Repository maintenance
13189 relink
13190 recreate hardlinks between two repositories:
13191 hg relink [ORIGIN]
13193 When repositories are cloned locally, their data files will be
13195 hardlinked so that they only use the space of a single repository.
13196 Unfortunately, subsequent pulls into either repository will break
13198 hardlinks for any files touched by the new changesets, even if both
13199 repositories end up pulling the same changes.
13200 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
13202 falling back to a complete copy of the source repository.
13203 This command lets you recreate those hardlinks and reclaim that wasted
13205 space.
13206 This repository will be relinked to share space with ORIGIN, which must
13208 be on the same local disk. If ORIGIN is omitted, looks for
13209 "default-relink", then "default", in [paths].
13210 Do not attempt any read operations on this repository while the command
13212 is running. (Both repositories will be locked against writes.)
13213 remotefilelog
13215 remotefilelog causes Mercurial to lazilly fetch file contents (EXPERI‐
13216 MENTAL)
13217 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13219 BILITY GUARANTEES. This means that repositories created with this
13220 extension may only be usable with the exact version of this exten‐
13221 sion/Mercurial that was used. The extension attempts to enforce this in
13222 order to prevent repository corruption.
13223 remotefilelog works by fetching file contents lazily and storing them
13225 in a cache on the client rather than in revlogs. This allows enormous
13226 histories to be transferred only partially, making them easier to oper‐
13227 ate on.
13228 Configs:
13230 packs.maxchainlen specifies the maximum delta chain length in pack
13232 files
13233 packs.maxpacksize specifies the maximum pack file size
13235 packs.maxpackfilecount specifies the maximum number of packs in the
13237 shared cache (trees only for now)
13239 remotefilelog.backgroundprefetch runs prefetch in background when
13241 True
13242 remotefilelog.bgprefetchrevs specifies revisions to fetch on commit
13244 and
13245 update, and on other commands that use them. Different from
13247 pullprefetch.
13248 remotefilelog.gcrepack does garbage collection during repack when
13250 True
13251 remotefilelog.nodettl specifies maximum TTL of a node in seconds
13253 before
13254 it is garbage collected
13256 remotefilelog.repackonhggc runs repack on hg gc when True
13258 remotefilelog.prefetchdays specifies the maximum age of a commit in
13260 days after which it is no longer prefetched.
13262 remotefilelog.prefetchdelay specifies delay between background
13264 prefetches in seconds after operations that change the work‐
13266 ing copy parent
13267 remotefilelog.data.gencountlimit constraints the minimum number of
13269 data
13270 pack files required to be considered part of a generation. In
13272 particular, minimum number of packs files > gencountlimit.
13273 remotefilelog.data.generations list for specifying the lower bound
13275 of
13276 each generation of the data pack files. For example, list
13278 ['100MB','1MB'] or ['1MB', '100MB'] will lead to three gener‐
13279 ations: [0, 1MB), [ 1MB, 100MB) and [100MB, infinity).
13280 remotefilelog.data.maxrepackpacks the maximum number of pack files
13282 to
13283 include in an incremental data repack.
13285 remotefilelog.data.repackmaxpacksize the maximum size of a pack file
13287 for
13288 it to be considered for an incremental data repack.
13290 remotefilelog.data.repacksizelimit the maximum total size of pack
13292 files
13293 to include in an incremental data repack.
13295 remotefilelog.history.gencountlimit constraints the minimum number
13297 of
13298 history pack files required to be considered part of a gener‐
13300 ation. In particular, minimum number of packs files > gen‐
13301 countlimit.
13302 remotefilelog.history.generations list for specifying the lower
13304 bound of
13305 each generation of the history pack files. For example, list
13307 [ '100MB', '1MB'] or ['1MB', '100MB'] will lead to three gen‐
13308 erations: [ 0, 1MB), [1MB, 100MB) and [100MB, infinity).
13309 remotefilelog.history.maxrepackpacks the maximum number of pack
13311 files to
13312 include in an incremental history repack.
13314 remotefilelog.history.repackmaxpacksize the maximum size of a pack
13316 file
13317 for it to be considered for an incremental history repack.
13319 remotefilelog.history.repacksizelimit the maximum total size of pack
13321 files to include in an incremental history repack.
13323 remotefilelog.backgroundrepack automatically consolidate packs in
13325 the
13326 background
13328 remotefilelog.cachepath path to cache
13330 remotefilelog.cachegroup if set, make cache directory sgid to this
13332 group
13334 remotefilelog.cacheprocess binary to invoke for fetching file data
13336 remotefilelog.debug turn on remotefilelog-specific debug output
13338 remotefilelog.excludepattern pattern of files to exclude from pulls
13340 remotefilelog.includepattern pattern of files to include in pulls
13342 remotefilelog.fetchwarning: message to print when too many
13344 single-file fetches occur
13346 remotefilelog.getfilesstep number of files to request in a single
13348 RPC
13349 remotefilelog.getfilestype if set to 'threaded' use threads to fetch
13351 files, otherwise use optimistic fetching
13353 remotefilelog.pullprefetch revset for selecting files that should be
13355 eagerly downloaded rather than lazily
13357 remotefilelog.reponame name of the repo. If set, used to partition
13359 data from other repos in a shared store.
13361 remotefilelog.server if true, enable server-side functionality
13363 remotefilelog.servercachepath path for caching blobs on the server
13365 remotefilelog.serverexpiration number of days to keep cached server
13367 blobs
13369 remotefilelog.validatecache if set, check cache entries for corrup‐
13371 tion
13372 before returning blobs
13374 remotefilelog.validatecachelog if set, check cache entries for
13376 corruption before returning metadata
13378 Commands
13380 Repository maintenance
13381 prefetch
13382 prefetch file revisions from the server:
13383 hg prefetch [OPTIONS] [FILE...]
13385 Prefetchs file revisions for the specified revs and stores them in the
13387 local remotefilelog cache. If no rev is specified, the default rev is
13388 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
13389 File names or patterns can be used to limit which files are downloaded.
13390 Return 0 on success.
13392 Options:
13394 -r,--rev <REV[+]>
13396 prefetch the specified revisions
13397 --repack
13399 run repack after prefetch
13400 -b,--base <VALUE>
13402 rev that is assumed to already be local
13403 -I,--include <PATTERN[+]>
13405 include names matching the given patterns
13406 -X,--exclude <PATTERN[+]>
13408 exclude names matching the given patterns
13409 [+] marked option can be specified multiple times
13411 Uncategorized commands
13413 gc
13414 garbage collect the client and server filelog caches:
13415 hg gc [REPO...]
13417 garbage collect the client and server filelog caches
13419 repack
13421 hg repack [OPTIONS]
13422 Options:
13424 --background
13426 run in a background process
13427 --incremental
13429 do an incremental repack
13430 --packsonly
13432 only repack packs (skip loose objects)
13433 verifyremotefilelog
13435 hg verifyremotefilelogs <directory>
13436 Options:
13438 -d, --decompress
13440 decompress the filelogs first
13441 remotenames
13443 showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)
13444 By default both remotebookmarks and remotebranches are turned on. Con‐
13446 fig knob to control the individually are as follows.
13447 Config options to tweak the default behaviour:
13449 remotenames.bookmarks
13451 Boolean value to enable or disable showing of remotebookmarks
13452 (default: True)
13453 remotenames.branches
13455 Boolean value to enable or disable showing of remotebranches
13456 (default: True)
13457 remotenames.hoistedpeer
13459 Name of the peer whose remotebookmarks should be hoisted into
13460 the top-level namespace (default: 'default')
13461 schemes
13463 extend schemes with shortcuts to repository swarms
13464 This extension allows you to specify shortcuts for parent URLs with a
13466 lot of repositories to act like a scheme, for example:
13467 [schemes]
13469 py = http://code.python.org/hg/
13470 After that you can use it like:
13472 hg clone py://trunk/
13474 Additionally there is support for some more complex schemas, for exam‐
13476 ple used by Google Code:
13477 [schemes]
13479 gcode = http://{1}.googlecode.com/hg/
13480 The syntax is taken from Mercurial templates, and you have unlimited
13482 number of variables, starting with {1} and continuing with {2}, {3} and
13483 so on. This variables will receive parts of URL supplied, split by /.
13484 Anything not specified as {part} will be just appended to an URL.
13485 For convenience, the extension adds these schemes by default:
13487 [schemes]
13489 py = http://hg.python.org/
13490 bb = https://bitbucket.org/
13491 bb+ssh = ssh://hg@bitbucket.org/
13492 gcode = https://{1}.googlecode.com/hg/
13493 kiln = https://{1}.kilnhg.com/Repo/
13494 You can override a predefined scheme by defining a new scheme with the
13496 same name.
13497 Commands
13499 Uncategorized commands
13500 share
13501 share a common history between several working directories
13502 Automatic Pooled Storage for Clones
13504 When this extension is active, hg clone can be configured to automati‐
13505 cally share/pool storage across multiple clones. This mode effectively
13506 converts hg clone to hg clone + hg share. The benefit of using this
13507 mode is the automatic management of store paths and intelligent pooling
13508 of related repositories.
13509 The following share. config options influence this feature:
13511 share.pool
13513 Filesystem path where shared repository data will be stored.
13515 When defined, hg clone will automatically use shared repository
13516 storage instead of creating a store inside each clone.
13517 share.poolnaming
13519 How directory names in share.pool are constructed.
13521 "identity" means the name is derived from the first changeset in
13523 the repository. In this mode, different remotes share storage if
13524 their root/initial changeset is identical. In this mode, the
13525 local shared repository is an aggregate of all encountered
13526 remote repositories.
13527 "remote" means the name is derived from the source repository's
13529 path or URL. In this mode, storage is only shared if the path or
13530 URL requested in the hg clone command matches exactly to a
13531 repository that was cloned before.
13532 The default naming mode is "identity".
13534 Commands
13536 Repository creation
13537 share
13538 create a new shared repository:
13539 hg share [-U] [-B] SOURCE [DEST]
13541 Initialize a new repository and working directory that shares its his‐
13543 tory (and optionally bookmarks) with another repository.
13544 Note using rollback or extensions that destroy/modify history (mq,
13546 rebase, etc.) can cause considerable confusion with shared
13547 clones. In particular, if two shared clones are both updated to
13548 the same changeset, and one of them destroys that changeset with
13549 rollback, the other clone will suddenly stop working: all opera‐
13550 tions will fail with "abort: working directory has unknown par‐
13551 ent". The only known workaround is to use debugsetparents on the
13552 broken clone to reset it to a changeset that still exists.
13553 Options:
13555 -U, --noupdate
13557 do not create a working directory
13558 -B, --bookmarks
13560 also share bookmarks
13561 --relative
13563 point to source using a relative path
13564 Repository maintenance
13566 unshare
13567 convert a shared repository to a normal one:
13568 hg unshare
13570 Copy the store data to the repo and remove the sharedpath data.
13572 show
13574 unified command to show various repository information (EXPERIMENTAL)
13575 This extension provides the hg show command, which provides a central
13577 command for displaying commonly-accessed repository data and views of
13578 that data.
13579 The following config options can influence operation.
13581 commands
13583 show.aliasprefix
13584 List of strings that will register aliases for views. e.g. s
13586 will effectively set config options alias.s<view> = show <view>
13587 for all views. i.e. hg swork would execute hg show work.
13588 Aliases that would conflict with existing registrations will not
13590 be performed.
13591 Commands
13593 Change navigation
13594 show
13595 show various repository information:
13596 hg show VIEW
13598 A requested view of repository data is displayed.
13600 If no view is requested, the list of available views is shown and the
13602 command aborts.
13603 Note There are no backwards compatibility guarantees for the output
13605 of this command. Output may change in any future Mercurial
13606 release.
13607 Consumers wanting stable command output should specify a tem‐
13609 plate via -T/--template.
13610 List of available views:
13612 bookmarks bookmarks and their associated changeset
13614 stack current line of work
13616 work changesets that aren't finished
13618 Options:
13620 -T,--template <TEMPLATE>
13622 display with template
13623 sparse
13625 allow sparse checkouts of the working directory (EXPERIMENTAL)
13626 (This extension is not yet protected by backwards compatibility guaran‐
13628 tees. Any aspect may break in future releases until this notice is
13629 removed.)
13630 This extension allows the working directory to only consist of a subset
13632 of files for the revision. This allows specific files or directories to
13633 be explicitly included or excluded. Many repository operations have
13634 performance proportional to the number of files in the working direc‐
13635 tory. So only realizing a subset of files in the working directory can
13636 improve performance.
13637 Sparse Config Files
13639 The set of files that are part of a sparse checkout are defined by a
13640 sparse config file. The file defines 3 things: includes (files to
13641 include in the sparse checkout), excludes (files to exclude from the
13642 sparse checkout), and profiles (links to other config files).
13643 The file format is newline delimited. Empty lines and lines beginning
13645 with # are ignored.
13646 Lines beginning with %include `` denote another sparse config file to
13648 include. e.g. ``%include tests.sparse. The filename is relative to the
13649 repository root.
13650 The special lines [include] and [exclude] denote the section for
13652 includes and excludes that follow, respectively. It is illegal to have
13653 [include] after [exclude].
13654 Non-special lines resemble file patterns to be added to either includes
13656 or excludes. The syntax of these lines is documented by hg help pat‐
13657 terns. Patterns are interpreted as glob: by default and match against
13658 the root of the repository.
13659 Exclusion patterns take precedence over inclusion patterns. So even if
13661 a file is explicitly included, an [exclude] entry can remove it.
13662 For example, say you have a repository with 3 directories, frontend/,
13664 backend/, and tools/. frontend/ and backend/ correspond to different
13665 projects and it is uncommon for someone working on one to need the
13666 files for the other. But tools/ contains files shared between both
13667 projects. Your sparse config files may resemble:
13668 # frontend.sparse
13670 frontend/**
13671 tools/**
13672 # backend.sparse
13674 backend/**
13675 tools/**
13676 Say the backend grows in size. Or there's a directory with thousands of
13678 files you wish to exclude. You can modify the profile to exclude cer‐
13679 tain files:
13680 [include]
13682 backend/**
13683 tools/**
13684 [exclude]
13686 tools/tests/**
13687 Commands
13689 Uncategorized commands
13690 split
13691 command to split a changeset into smaller ones (EXPERIMENTAL)
13692 Commands
13694 Change manipulation
13695 split
13696 split a changeset into smaller ones:
13697 hg split [--no-rebase] [[-r] REV]
13699 Repeatedly prompt changes and commit message for new changesets until
13701 there is nothing left in the original changeset.
13702 If --rev was not given, split the working directory parent.
13704 By default, rebase connected non-obsoleted descendants onto the new
13706 changeset. Use --no-rebase to avoid the rebase.
13707 Options:
13709 -r,--rev <REV>
13711 revision to split
13712 --rebase
13714 rebase descendants after split (default: )
13715 -d,--date <DATE>
13717 record the specified date as commit date
13718 -u,--user <USER>
13720 record the specified user as committer
13721 sqlitestore
13723 store repository data in SQLite (EXPERIMENTAL)
13724 The sqlitestore extension enables the storage of repository data in
13726 SQLite.
13727 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13729 BILITY GUARANTEES. This means that repositories created with this
13730 extension may only be usable with the exact version of this exten‐
13731 sion/Mercurial that was used. The extension attempts to enforce this in
13732 order to prevent repository corruption.
13733 In addition, several features are not yet supported or have known bugs:
13735 · Only some data is stored in SQLite. Changeset, manifest, and other
13737 repository data is not yet stored in SQLite.
13738 · Transactions are not robust. If the process is aborted at the right
13740 time during transaction close/rollback, the repository could be in an
13741 inconsistent state. This problem will diminish once all repository
13742 data is tracked by SQLite.
13743 · Bundle repositories do not work (the ability to use e.g. hg -R <bun‐
13745 dle-file> log to automatically overlay a bundle on top of the exist‐
13746 ing repository).
13747 · Various other features don't work.
13749 This extension should work for basic clone/pull, update, and commit
13751 workflows. Some history rewriting operations may fail due to lack of
13752 support for bundle repositories.
13753 To use, activate the extension and set the storage.new-repo-backend
13755 config option to sqlite to enable new repositories to use SQLite for
13756 storage.
13757 strip
13759 strip changesets and their descendants from history
13760 This extension allows you to strip changesets and all their descendants
13762 from the repository. See the command help for details.
13763 Commands
13765 Repository maintenance
13766 strip
13767 strip changesets and all their descendants from the repository:
13768 hg strip [-k] [-f] [-B bookmark] [-r] REV...
13770 The strip command removes the specified changesets and all their
13772 descendants. If the working directory has uncommitted changes, the
13773 operation is aborted unless the --force flag is supplied, in which case
13774 changes will be discarded.
13775 If a parent of the working directory is stripped, then the working
13777 directory will automatically be updated to the most recent available
13778 ancestor of the stripped parent after the operation completes.
13779 Any stripped changesets are stored in .hg/strip-backup as a bundle (see
13781 hg help bundle and hg help unbundle). They can be restored by running
13782 hg unbundle .hg/strip-backup/BUNDLE, where BUNDLE is the bundle file
13783 created by the strip. Note that the local revision numbers will in gen‐
13784 eral be different after the restore.
13785 Use the --no-backup option to discard the backup bundle once the opera‐
13787 tion completes.
13788 Strip is not a history-rewriting operation and can be used on change‐
13790 sets in the public phase. But if the stripped changesets have been
13791 pushed to a remote repository you will likely pull them again.
13792 Return 0 on success.
13794 Options:
13796 -r,--rev <REV[+]>
13798 strip specified revision (optional, can specify revisions with‐
13799 out this option)
13800 -f, --force
13802 force removal of changesets, discard uncommitted changes (no
13803 backup)
13804 --no-backup
13806 do not save backup bundle
13807 --nobackup
13809 do not save backup bundle (DEPRECATED)
13810 -n ignored (DEPRECATED)
13812 -k, --keep
13814 do not modify working directory during strip
13815 -B,--bookmark <BOOKMARK[+]>
13817 remove revs only reachable from given bookmark
13818 --soft simply drop changesets from visible history (EXPERIMENTAL)
13820 [+] marked option can be specified multiple times
13822 transplant
13824 command to transplant changesets from another branch
13825 This extension allows you to transplant changes to another parent revi‐
13827 sion, possibly in another repository. The transplant is done using
13828 'diff' patches.
13829 Transplanted patches are recorded in .hg/transplant/transplants, as a
13831 map from a changeset hash to its hash in the source repository.
13832 Commands
13834 Change manipulation
13835 transplant
13836 transplant changesets from another branch:
13837 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
13839 Selected changesets will be applied on top of the current working
13841 directory with the log of the original changeset. The changesets are
13842 copied and will thus appear twice in the history with different identi‐
13843 ties.
13844 Consider using the graft command if everything is inside the same
13846 repository - it will use merges and will usually give a better result.
13847 Use the rebase extension if the changesets are unpublished and you want
13848 to move them instead of copying them.
13849 If --log is specified, log messages will have a comment appended of the
13851 form:
13852 (transplanted from CHANGESETHASH)
13854 You can rewrite the changelog message with the --filter option. Its
13856 argument will be invoked with the current changelog message as $1 and
13857 the patch as $2.
13858 --source/-s specifies another repository to use for selecting change‐
13860 sets, just as if it temporarily had been pulled. If --branch/-b is
13861 specified, these revisions will be used as heads when deciding which
13862 changesets to transplant, just as if only these revisions had been
13863 pulled. If --all/-a is specified, all the revisions up to the heads
13864 specified with --branch will be transplanted.
13865 Example:
13867 · transplant all changes up to REV on top of your current revision:
13869 hg transplant --branch REV --all
13871 You can optionally mark selected transplanted changesets as merge
13873 changesets. You will not be prompted to transplant any ancestors of a
13874 merged transplant, and you can merge descendants of them normally
13875 instead of transplanting them.
13876 Merge changesets may be transplanted directly by specifying the proper
13878 parent changeset by calling hg transplant --parent.
13879 If no merges or revisions are provided, hg transplant will start an
13881 interactive changeset browser.
13882 If a changeset application fails, you can fix the merge by hand and
13884 then resume where you left off by calling hg transplant --continue/-c.
13885 Options:
13887 -s,--source <REPO>
13889 transplant changesets from REPO
13890 -b,--branch <REV[+]>
13892 use this source changeset as head
13893 -a, --all
13895 pull all changesets up to the --branch revisions
13896 -p,--prune <REV[+]>
13898 skip over REV
13899 -m,--merge <REV[+]>
13901 merge at REV
13902 --parent <REV>
13904 parent to choose when transplanting merge
13905 -e, --edit
13907 invoke editor on commit messages
13908 --log append transplant info to log message
13910 --stop stop interrupted transplant
13912 -c, --continue
13914 continue last transplant session after fixing conflicts
13915 --filter <CMD>
13917 filter changesets through command
13918 [+] marked option can be specified multiple times
13920 uncommit
13922 uncommit part or all of a local changeset (EXPERIMENTAL)
13923 This command undoes the effect of a local commit, returning the
13925 affected files to their uncommitted state. This means that files modi‐
13926 fied, added or removed in the changeset will be left unchanged, and so
13927 will remain modified, added and removed in the working directory.
13928 Commands
13930 Change manipulation
13931 unamend
13932 undo the most recent amend operation on a current changeset:
13933 hg unamend
13935 This command will roll back to the previous version of a changeset,
13937 leaving working directory in state in which it was before running hg
13938 amend (e.g. files modified as part of an amend will be marked as modi‐
13939 fied hg status)
13940 uncommit
13942 uncommit part or all of a local changeset:
13943 hg uncommit [OPTION]... [FILE]...
13945 This command undoes the effect of a local commit, returning the
13947 affected files to their uncommitted state. This means that files modi‐
13948 fied or deleted in the changeset will be left unchanged, and so will
13949 remain modified in the working directory.
13950 If no files are specified, the commit will be pruned, unless --keep is
13952 given.
13953 Options:
13955 --keep allow an empty commit after uncommitting
13957 --allow-dirty-working-copy
13959 allow uncommit with outstanding changes
13960 -n,--note <TEXT>
13962 store a note on uncommit
13963 -I,--include <PATTERN[+]>
13965 include names matching the given patterns
13966 -X,--exclude <PATTERN[+]>
13968 exclude names matching the given patterns
13969 -m,--message <TEXT>
13971 use text as commit message
13972 -l,--logfile <FILE>
13974 read commit message from file
13975 -d,--date <DATE>
13977 record the specified date as commit date
13978 -u,--user <USER>
13980 record the specified user as committer
13981 -D, --currentdate
13983 record the current date as commit date
13984 -U, --currentuser
13986 record the current user as committer
13987 [+] marked option can be specified multiple times
13989 win32mbcs
13991 allow the use of MBCS paths with problematic encodings
13992 Some MBCS encodings are not good for some path operations (i.e. split‐
13994 ting path, case conversion, etc.) with its encoded bytes. We call such
13995 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
13996 extension can be used to fix the issue with those encodings by wrapping
13997 some functions to convert to Unicode string before path operation.
13998 This extension is useful for:
14000 · Japanese Windows users using shift_jis encoding.
14002 · Chinese Windows users using big5 encoding.
14004 · All users who use a repository with one of problematic encodings on
14006 case-insensitive file system.
14007 This extension is not needed for:
14009 · Any user who use only ASCII chars in path.
14011 · Any user who do not use any of problematic encodings.
14013 Note that there are some limitations on using this extension:
14015 · You should use single encoding in one repository.
14017 · If the repository path ends with 0x5c, .hg/hgrc cannot be read.
14019 · win32mbcs is not compatible with fixutf8 extension.
14021 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
14023 can specify the encoding by config option:
14024 [win32mbcs]
14026 encoding = sjis
14027 It is useful for the users who want to commit with UTF-8 log message.
14029 win32text
14031 perform automatic newline conversion (DEPRECATED)
14032 Deprecation: The win32text extension requires each user to configure
14034 the extension again and again for each clone since the configuration
14035 is not copied when cloning.
14036 We have therefore made the eol as an alternative. The eol uses a
14038 version controlled file for its configuration and each clone will
14039 therefore use the right settings from the start.
14040 To perform automatic newline conversion, use:
14042 [extensions]
14044 win32text =
14045 [encode]
14046 ** = cleverencode:
14047 # or ** = macencode:
14048 [decode]
14050 ** = cleverdecode:
14051 # or ** = macdecode:
14052 If not doing conversion, to make sure you do not commit CRLF/CR by
14054 accident:
14055 [hooks]
14057 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
14058 # or pretxncommit.cr = python:hgext.win32text.forbidcr
14059 To do the same check on a server to prevent CRLF/CR from being pushed
14061 or pulled:
14062 [hooks]
14064 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
14065 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
14066 zeroconf
14068 discover and advertise repositories on the local network
14069 Zeroconf-enabled repositories will be announced in a network without
14071 the need to configure a server or a service. They can be discovered
14072 without knowing their actual IP address.
14073 To allow other people to discover your repository using run hg serve in
14075 your repository:
14076 $ cd test
14078 $ hg serve
14079 You can discover Zeroconf-enabled repositories by running hg paths:
14081 $ hg paths
14083 zc-test = http://example.com:8000/test
14084
14086 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
14087 This file contains defaults and configuration. Values in
14089 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
14090 tings made in the global /etc/mercurial/hgrc configuration. See
14091 hgrc(5) for details of the contents and format of these files.
14092 .hgignore
14094 This file contains regular expressions (one per line) that
14096 describe file names that should be ignored by hg. For details,
14097 see hgignore(5).
14098 .hgsub
14100 This file defines the locations of all subrepositories, and
14102 tells where the subrepository checkouts came from. For details,
14103 see hg help subrepos.
14104 .hgsubstate
14106 This file is where Mercurial stores all nested repository
14108 states. NB: This file should not be edited manually.
14109 .hgtags
14111 This file contains changeset hash values and text tag names (one
14113 of each separated by spaces) that correspond to tagged versions
14114 of the repository contents. The file content is encoded using
14115 UTF-8.
14116 .hg/last-message.txt
14118 This file is used by hg commit to store a backup of the commit
14120 message in case the commit fails.
14121 .hg/localtags
14123 This file can be used to define local tags which are not shared
14125 among repositories. The file format is the same as for .hgtags,
14126 but it is encoded using the local system encoding.
14127 Some commands (e.g. revert) produce backup files ending in .orig, if
14129 the .orig file already exists and is not tracked by Mercurial, it will
14130 be overwritten.
14131
14133 Probably lots, please post them to the mailing list (see Resources
14134 below) when you find them.
14135
14137 hgignore(5), hgrc(5)
14138
14140 Written by Matt Mackall <mpm@selenic.com>
14141
14143 Main Web Site: https://mercurial-scm.org/
14144 Source code repository: https://www.mercurial-scm.org/repo/hg
14146 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
14148
14150 Copyright (C) 2005-2019 Matt Mackall. Free use of this software is
14151 granted under the terms of the GNU General Public License version 2 or
14152 any later version.
14153
14155 Matt Mackall <mpm@selenic.com>
14156 Organization: Mercurial
14158 HG(1)