1HG(1) Mercurial Manual HG(1)
2
6 hg - Mercurial source code management system
7
9 hg command [option]... [argument]...
10
12 The hg command provides a command line interface to the Mercurial sys‐
13 tem.
14
16 files...
17 indicates one or more filename or relative path filenames; see
18 File Name Patterns for information on pattern matching
19 path indicates a path on the local machine
21 revision
23 indicates a changeset which can be specified as a changeset re‐
24 vision number, a tag, or a unique substring of the changeset
25 hash value
26 repository path
28 either the pathname of a local repository or the URI of a remote
29 repository.
30
32 -R,--repository <REPO>
33 repository root directory or name of overlay bundle file
34 --cwd <DIR>
36 change working directory
37 -y, --noninteractive
39 do not prompt, automatically pick the first choice for all
40 prompts
41 -q, --quiet
43 suppress output
44 -v, --verbose
46 enable additional output
47 --color <TYPE>
49 when to colorize (boolean, always, auto, never, or debug)
50 --config <CONFIG[+]>
52 set/override config option (use 'section.name=value')
53 --debug
55 enable debugging output
56 --debugger
58 start debugger
59 --encoding <ENCODE>
61 set the charset encoding (default: UTF-8)
62 --encodingmode <MODE>
64 set the charset encoding mode (default: strict)
65 --traceback
67 always print a traceback on exception
68 --time time how long the command takes
70 --profile
72 print command execution profile
73 --version
75 output version information and exit
76 -h, --help
78 display help and exit
79 --hidden
81 consider hidden changesets
82 --pager <TYPE>
84 when to paginate (boolean, always, auto, or never) (default:
85 auto)
86 [+] marked option can be specified multiple times
88
90 Repository creation
91 clone
92 make a copy of an existing repository:
93 hg clone [OPTION]... SOURCE [DEST]
95 Create a copy of an existing repository in a new directory.
97 If no destination directory name is specified, it defaults to the base‐
99 name of the source.
100 The location of the source is added to the new repository's .hg/hgrc
102 file, as the default to be used for future pulls.
103 Only local paths and ssh:// URLs are supported as destinations. For
105 ssh:// destinations, no working directory or .hg/hgrc will be created
106 on the remote side.
107 If the source repository has a bookmark called '@' set, that revision
109 will be checked out in the new repository by default.
110 To check out a particular version, use -u/--update, or -U/--noupdate to
112 create a clone with no working directory.
113 To pull only a subset of changesets, specify one or more revisions
115 identifiers with -r/--rev or branches with -b/--branch. The resulting
116 clone will contain only the specified changesets and their ancestors.
117 These options (or 'clone src#rev dest') imply --pull, even for local
118 source repositories.
119 In normal clone mode, the remote normalizes repository data into a com‐
121 mon exchange format and the receiving end translates this data into its
122 local storage format. --stream activates a different clone mode that
123 essentially copies repository files from the remote with minimal data
124 processing. This significantly reduces the CPU cost of a clone both re‐
125 motely and locally. However, it often increases the transferred data
126 size by 30-40%. This can result in substantially faster clones where
127 I/O throughput is plentiful, especially for larger repositories. A
128 side-effect of --stream clones is that storage settings and require‐
129 ments on the remote are applied locally: a modern client may inherit
130 legacy or inefficient storage used by the remote or a legacy Mercurial
131 client may not be able to clone from a modern Mercurial remote.
132 Note Specifying a tag will include the tagged changeset but not the
134 changeset containing the tag.
135 For efficiency, hardlinks are used for cloning whenever the source and
137 destination are on the same filesystem (note this applies only to the
138 repository data, not to the working directory). Some filesystems, such
139 as AFS, implement hardlinking incorrectly, but do not report errors. In
140 these cases, use the --pull option to avoid hardlinking.
141 Mercurial will update the working directory to the first applicable re‐
143 vision from this list:
144 a. null if -U or the source repository has no changesets
146 b. if -u . and the source repository is local, the first parent of the
148 source repository's working directory
149 c. the changeset specified with -u (if a branch name, this means the
151 latest head of that branch)
152 d. the changeset specified with -r
154 e. the tipmost head specified with -b
156 f. the tipmost head specified with the url#branch source syntax
158 g. the revision marked with the '@' bookmark, if present
160 h. the tipmost head of the default branch
162 i. tip
164 When cloning from servers that support it, Mercurial may fetch pre-gen‐
166 erated data from a server-advertised URL or inline from the same
167 stream. When this is done, hooks operating on incoming changesets and
168 changegroups may fire more than once, once for each pre-generated bun‐
169 dle and as well as for any additional remaining data. In addition, if
170 an error occurs, the repository may be rolled back to a partial clone.
171 This behavior may change in future releases. See hg help -e cloneb‐
172 undles for more.
173 Examples:
175 • clone a remote repository to a new directory named hg/:
177 hg clone https://www.mercurial-scm.org/repo/hg/
179 • create a lightweight local clone:
181 hg clone project/ project-feature/
183 • clone from an absolute path on an ssh server (note double-slash):
185 hg clone ssh://user@server//home/projects/alpha/
187 • do a streaming clone while checking out a specified version:
189 hg clone --stream http://server/repo -u 1.5
191 • create a repository without changesets after a particular revision:
193 hg clone -r 04e544 experimental/ good/
195 • clone (and track) a particular named branch:
197 hg clone https://www.mercurial-scm.org/repo/hg/#stable
199 See hg help urls for details on specifying URLs.
201 Returns 0 on success.
203 Options:
205 -U, --noupdate
207 the clone will include an empty working directory (only a repos‐
208 itory)
209 -u,--updaterev <REV>
211 revision, tag, or branch to check out
212 -r,--rev <REV[+]>
214 do not clone everything, but include this changeset and its an‐
215 cestors
216 -b,--branch <BRANCH[+]>
218 do not clone everything, but include this branch's changesets
219 and their ancestors
220 --pull use pull protocol to copy metadata
222 --uncompressed
224 an alias to --stream (DEPRECATED)
225 --stream
227 clone with minimal data processing
228 -e,--ssh <CMD>
230 specify ssh command to use
231 --remotecmd <CMD>
233 specify hg command to run on the remote side
234 --insecure
236 do not verify server certificate (ignoring web.cacerts config)
237 [+] marked option can be specified multiple times
239 init
241 create a new repository in the given directory:
242 hg init [-e CMD] [--remotecmd CMD] [DEST]
244 Initialize a new repository in the given directory. If the given direc‐
246 tory does not exist, it will be created.
247 If no directory is given, the current directory is used.
249 It is possible to specify an ssh:// URL as the destination. See hg
251 help urls for more information.
252 Returns 0 on success.
254 Options:
256 -e,--ssh <CMD>
258 specify ssh command to use
259 --remotecmd <CMD>
261 specify hg command to run on the remote side
262 --insecure
264 do not verify server certificate (ignoring web.cacerts config)
265 Remote repository management
267 incoming
268 show new changesets found in source:
269 hg incoming [-p] [-n] [-M] [-f] [-r REV]... [--bundle FILENAME] [SOURCE]
271 Show new changesets found in the specified path/URL or the default pull
273 location. These are the changesets that would have been pulled by hg
274 pull at the time you issued this command.
275 See pull for valid source format details.
277 With -B/--bookmarks, the result of bookmark comparison between local
279 and remote repositories is displayed. With -v/--verbose, status is also
280 displayed for each bookmark like below:
281 BM1 01234567890a added
283 BM2 1234567890ab advanced
284 BM3 234567890abc diverged
285 BM4 34567890abcd changed
286 The action taken locally when pulling depends on the status of each
288 bookmark:
289 added
291 pull will create it
293 advanced
295 pull will update it
297 diverged
299 pull will create a divergent bookmark
301 changed
303 result depends on remote changesets
305 From the point of view of pulling behavior, bookmark existing only in
307 the remote repository are treated as added, even if it is in fact lo‐
308 cally deleted.
309 For remote repository, using --bundle avoids downloading the changesets
311 twice if the incoming is followed by a pull.
312 Examples:
314 • show incoming changes with patches and full description:
316 hg incoming -vp
318 • show incoming changes excluding merges, store a bundle:
320 hg in -vpM --bundle incoming.hg
322 hg pull incoming.hg
323 • briefly list changes inside a bundle:
325 hg in changes.hg -T "{desc|firstline}\n"
327 Returns 0 if there are incoming changes, 1 otherwise.
329 Options:
331 -f, --force
333 run even if remote repository is unrelated
334 -n, --newest-first
336 show newest record first
337 --bundle <FILE>
339 file to store the bundles into
340 -r,--rev <REV[+]>
342 a remote changeset intended to be added
343 -B, --bookmarks
345 compare bookmarks
346 -b,--branch <BRANCH[+]>
348 a specific branch you would like to pull
349 -p, --patch
351 show patch
352 -g, --git
354 use git extended diff format
355 -l,--limit <NUM>
357 limit number of changes displayed
358 -M, --no-merges
360 do not show merges
361 --stat output diffstat-style summary of changes
363 -G, --graph
365 show the revision DAG
366 --style <STYLE>
368 display using template map file (DEPRECATED)
369 -T,--template <TEMPLATE>
371 display with template
372 -e,--ssh <CMD>
374 specify ssh command to use
375 --remotecmd <CMD>
377 specify hg command to run on the remote side
378 --insecure
380 do not verify server certificate (ignoring web.cacerts config)
381 -S, --subrepos
383 recurse into subrepositories
384 [+] marked option can be specified multiple times
386 aliases: in
388 outgoing
390 show changesets not found in the destination:
391 hg outgoing [-M] [-p] [-n] [-f] [-r REV]... [DEST]
393 Show changesets not found in the specified destination repository or
395 the default push location. These are the changesets that would be
396 pushed if a push was requested.
397 See pull for details of valid destination formats.
399 With -B/--bookmarks, the result of bookmark comparison between local
401 and remote repositories is displayed. With -v/--verbose, status is also
402 displayed for each bookmark like below:
403 BM1 01234567890a added
405 BM2 deleted
406 BM3 234567890abc advanced
407 BM4 34567890abcd diverged
408 BM5 4567890abcde changed
409 The action taken when pushing depends on the status of each bookmark:
411 added
413 push with -B will create it
415 deleted
417 push with -B will delete it
419 advanced
421 push will update it
423 diverged
425 push with -B will update it
427 changed
429 push with -B will update it
431 From the point of view of pushing behavior, bookmarks existing only in
433 the remote repository are treated as deleted, even if it is in fact
434 added remotely.
435 Returns 0 if there are outgoing changes, 1 otherwise.
437 Options:
439 -f, --force
441 run even when the destination is unrelated
442 -r,--rev <REV[+]>
444 a changeset intended to be included in the destination
445 -n, --newest-first
447 show newest record first
448 -B, --bookmarks
450 compare bookmarks
451 -b,--branch <BRANCH[+]>
453 a specific branch you would like to push
454 -p, --patch
456 show patch
457 -g, --git
459 use git extended diff format
460 -l,--limit <NUM>
462 limit number of changes displayed
463 -M, --no-merges
465 do not show merges
466 --stat output diffstat-style summary of changes
468 -G, --graph
470 show the revision DAG
471 --style <STYLE>
473 display using template map file (DEPRECATED)
474 -T,--template <TEMPLATE>
476 display with template
477 -e,--ssh <CMD>
479 specify ssh command to use
480 --remotecmd <CMD>
482 specify hg command to run on the remote side
483 --insecure
485 do not verify server certificate (ignoring web.cacerts config)
486 -S, --subrepos
488 recurse into subrepositories
489 [+] marked option can be specified multiple times
491 aliases: out
493 paths
495 show aliases for remote repositories:
496 hg paths [NAME]
498 Show definition of symbolic path name NAME. If no name is given, show
500 definition of all available names.
501 Option -q/--quiet suppresses all output when searching for NAME and
503 shows only the path names when listing all definitions.
504 Path names are defined in the [paths] section of your configuration
506 file and in /etc/mercurial/hgrc. If run inside a repository, .hg/hgrc
507 is used, too.
508 The path names default and default-push have a special meaning. When
510 performing a push or pull operation, they are used as fallbacks if no
511 location is specified on the command-line. When default-push is set,
512 it will be used for push and default will be used for pull; otherwise
513 default is used as the fallback for both. When cloning a repository,
514 the clone source is written as default in .hg/hgrc.
515 Note default and default-push apply to all inbound (e.g. hg incoming
517 ) and outbound (e.g. hg outgoing, hg email and hg bundle) opera‐
518 tions.
519 See hg help urls for more information.
521 Template:
523 The following keywords are supported. See also hg help templates.
525 name String. Symbolic name of the path alias.
527 pushurl
529 String. URL for push operations.
530 url String. URL or directory path for the other operations.
532 Returns 0 on success.
534 Options:
536 -T,--template <TEMPLATE>
538 display with template
539 pull
541 pull changes from the specified source:
542 hg pull [-u] [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [SOURCE]
544 Pull changes from a remote repository to a local one.
546 This finds all changes from the repository at the specified path or URL
548 and adds them to a local repository (the current one unless -R is spec‐
549 ified). By default, this does not update the copy of the project in the
550 working directory.
551 When cloning from servers that support it, Mercurial may fetch pre-gen‐
553 erated data. When this is done, hooks operating on incoming changesets
554 and changegroups may fire more than once, once for each pre-generated
555 bundle and as well as for any additional remaining data. See hg help -e
556 clonebundles for more.
557 Use hg incoming if you want to see what would have been added by a pull
559 at the time you issued this command. If you then decide to add those
560 changes to the repository, you should use hg pull -r X where X is the
561 last changeset listed by hg incoming.
562 If SOURCE is omitted, the 'default' path will be used. See hg help
564 urls for more information.
565 Specifying bookmark as . is equivalent to specifying the active book‐
567 mark's name.
568 Returns 0 on success, 1 if an update had unresolved files.
570 Options:
572 -u, --update
574 update to new branch head if new descendants were pulled
575 -f, --force
577 run even when remote repository is unrelated
578 --confirm
580 confirm pull before applying changes
581 -r,--rev <REV[+]>
583 a remote changeset intended to be added
584 -B,--bookmark <BOOKMARK[+]>
586 bookmark to pull
587 -b,--branch <BRANCH[+]>
589 a specific branch you would like to pull
590 -e,--ssh <CMD>
592 specify ssh command to use
593 --remotecmd <CMD>
595 specify hg command to run on the remote side
596 --insecure
598 do not verify server certificate (ignoring web.cacerts config)
599 [+] marked option can be specified multiple times
601 push
603 push changes to the specified destination:
604 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]
606 Push changesets from the local repository to the specified destination.
608 This operation is symmetrical to pull: it is identical to a pull in the
610 destination repository from the current one.
611 By default, push will not allow creation of new heads at the destina‐
613 tion, since multiple heads would make it unclear which head to use. In
614 this situation, it is recommended to pull and merge before pushing.
615 Use --new-branch if you want to allow push to create a new named branch
617 that is not present at the destination. This allows you to only create
618 a new branch without forcing other changes.
619 Note Extra care should be taken with the -f/--force option, which
621 will push all new heads on all branches, an action which will
622 almost always cause confusion for collaborators.
623 If -r/--rev is used, the specified revision and all its ancestors will
625 be pushed to the remote repository.
626 If -B/--bookmark is used, the specified bookmarked revision, its ances‐
628 tors, and the bookmark will be pushed to the remote repository. Speci‐
629 fying . is equivalent to specifying the active bookmark's name. Use the
630 --all-bookmarks option for pushing all current bookmarks.
631 Please see hg help urls for important details about ssh:// URLs. If
633 DESTINATION is omitted, a default path will be used.
634 The --pushvars option sends strings to the server that become environ‐
636 ment variables prepended with HG_USERVAR_. For example, --pushvars EN‐
637 ABLE_FEATURE=true, provides the server side hooks with HG_USERVAR_EN‐
638 ABLE_FEATURE=true as part of their environment.
639 pushvars can provide for user-overridable hooks as well as set debug
641 levels. One example is having a hook that blocks commits containing
642 conflict markers, but enables the user to override the hook if the file
643 is using conflict markers for testing purposes or the file format has
644 strings that look like conflict markers.
645 By default, servers will ignore --pushvars. To enable it add the fol‐
647 lowing to your configuration file:
648 [push]
650 pushvars.server = true
651 Returns 0 if push was successful, 1 if nothing to push.
653 Options:
655 -f, --force
657 force push
658 -r,--rev <REV[+]>
660 a changeset intended to be included in the destination
661 -B,--bookmark <BOOKMARK[+]>
663 bookmark to push
664 --all-bookmarks
666 push all bookmarks (EXPERIMENTAL)
667 -b,--branch <BRANCH[+]>
669 a specific branch you would like to push
670 --new-branch
672 allow pushing a new branch
673 --pushvars <VALUE[+]>
675 variables that can be sent to server (ADVANCED)
676 --publish
678 push the changeset as public (EXPERIMENTAL)
679 -e,--ssh <CMD>
681 specify ssh command to use
682 --remotecmd <CMD>
684 specify hg command to run on the remote side
685 --insecure
687 do not verify server certificate (ignoring web.cacerts config)
688 [+] marked option can be specified multiple times
690 serve
692 start stand-alone webserver:
693 hg serve [OPTION]...
695 Start a local HTTP repository browser and pull server. You can use this
697 for ad-hoc sharing and browsing of repositories. It is recommended to
698 use a real web server to serve a repository for longer periods of time.
699 Please note that the server does not implement access control. This
701 means that, by default, anybody can read from the server and nobody can
702 write to it by default. Set the web.allow-push option to * to allow ev‐
703 erybody to push to the server. You should use a real web server if you
704 need to authenticate users.
705 By default, the server logs accesses to stdout and errors to stderr.
707 Use the -A/--accesslog and -E/--errorlog options to log to files.
708 To have the server choose a free port number to listen on, specify a
710 port number of 0; in this case, the server will print the port number
711 it uses.
712 Returns 0 on success.
714 Options:
716 -A,--accesslog <FILE>
718 name of access log file to write to
719 -d, --daemon
721 run server in background
722 --daemon-postexec <VALUE[+]>
724 used internally by daemon mode
725 -E,--errorlog <FILE>
727 name of error log file to write to
728 -p,--port <PORT>
730 port to listen on (default: 8000)
731 -a,--address <ADDR>
733 address to listen on (default: all interfaces)
734 --prefix <PREFIX>
736 prefix path to serve from (default: server root)
737 -n,--name <NAME>
739 name to show in web pages (default: working directory)
740 --web-conf <FILE>
742 name of the hgweb config file (see 'hg help hgweb')
743 --webdir-conf <FILE>
745 name of the hgweb config file (DEPRECATED)
746 --pid-file <FILE>
748 name of file to write process ID to
749 --stdio
751 for remote clients (ADVANCED)
752 --cmdserver <MODE>
754 for remote clients (ADVANCED)
755 -t,--templates <TEMPLATE>
757 web templates to use
758 --style <STYLE>
760 template style to use
761 -6, --ipv6
763 use IPv6 in addition to IPv4
764 --certificate <FILE>
766 SSL certificate file
767 --print-url
769 start and print only the URL
770 -S, --subrepos
772 recurse into subrepositories
773 [+] marked option can be specified multiple times
775 Change creation
777 commit
778 commit the specified files or all outstanding changes:
779 hg commit [OPTION]... [FILE]...
781 Commit changes to the given files into the repository. Unlike a cen‐
783 tralized SCM, this operation is a local operation. See hg push for a
784 way to actively distribute your changes.
785 If a list of files is omitted, all changes reported by hg status will
787 be committed.
788 If you are committing the result of a merge, do not provide any file‐
790 names or -I/-X filters.
791 If no commit message is specified, Mercurial starts your configured ed‐
793 itor where you can enter a message. In case your commit fails, you will
794 find a backup of your message in .hg/last-message.txt.
795 The --close-branch flag can be used to mark the current branch head
797 closed. When all heads of a branch are closed, the branch will be con‐
798 sidered closed and no longer listed.
799 The --amend flag can be used to amend the parent of the working direc‐
801 tory with a new commit that contains the changes in the parent in addi‐
802 tion to those currently reported by hg status, if there are any. The
803 old commit is stored in a backup bundle in .hg/strip-backup (see hg
804 help bundle and hg help unbundle on how to restore it).
805 Message, user and date are taken from the amended commit unless speci‐
807 fied. When a message isn't specified on the command line, the editor
808 will open with the message of the amended commit.
809 It is not possible to amend public changesets (see hg help phases) or
811 changesets that have children.
812 See hg help dates for a list of formats valid for -d/--date.
814 Returns 0 on success, 1 if nothing changed.
816 Examples:
818 • commit all files ending in .py:
820 hg commit --include "set:**.py"
822 • commit all non-binary files:
824 hg commit --exclude "set:binary()"
826 • amend the current commit and set the date to now:
828 hg commit --amend --date now
830 Options:
832 -A, --addremove
834 mark new/missing files as added/removed before committing
835 --close-branch
837 mark a branch head as closed
838 --amend
840 amend the parent of the working directory
841 -s, --secret
843 use the secret phase for committing
844 -e, --edit
846 invoke editor on commit messages
847 --force-close-branch
849 forcibly close branch from a non-head changeset (ADVANCED)
850 -i, --interactive
852 use interactive mode
853 -I,--include <PATTERN[+]>
855 include names matching the given patterns
856 -X,--exclude <PATTERN[+]>
858 exclude names matching the given patterns
859 -m,--message <TEXT>
861 use text as commit message
862 -l,--logfile <FILE>
864 read commit message from file
865 -d,--date <DATE>
867 record the specified date as commit date
868 -u,--user <USER>
870 record the specified user as committer
871 -S, --subrepos
873 recurse into subrepositories
874 [+] marked option can be specified multiple times
876 aliases: ci
878 Change manipulation
880 abort
881 abort an unfinished operation (EXPERIMENTAL):
882 hg abort
884 Aborts a multistep operation like graft, histedit, rebase, merge, and
886 unshelve if they are in an unfinished state.
887 use --dry-run/-n to dry run the command.
889 Options:
891 -n, --dry-run
893 do not perform actions, just print output
894 backout
896 reverse effect of earlier changeset:
897 hg backout [OPTION]... [-r] REV
899 Prepare a new changeset with the effect of REV undone in the current
901 working directory. If no conflicts were encountered, it will be commit‐
902 ted immediately.
903 If REV is the parent of the working directory, then this new changeset
905 is committed automatically (unless --no-commit is specified).
906 Note hg backout cannot be used to fix either an unwanted or incorrect
908 merge.
909 Examples:
911 • Reverse the effect of the parent of the working directory. This
913 backout will be committed immediately:
914 hg backout -r .
916 • Reverse the effect of previous bad revision 23:
918 hg backout -r 23
920 • Reverse the effect of previous bad revision 23 and leave changes un‐
922 committed:
923 hg backout -r 23 --no-commit
925 hg commit -m "Backout revision 23"
926 By default, the pending changeset will have one parent, maintaining a
928 linear history. With --merge, the pending changeset will instead have
929 two parents: the old parent of the working directory and a new child of
930 REV that simply undoes REV.
931 Before version 1.7, the behavior without --merge was equivalent to
933 specifying --merge followed by hg update --clean . to cancel the merge
934 and leave the child of REV as a head to be merged separately.
935 See hg help dates for a list of formats valid for -d/--date.
937 See hg help revert for a way to restore files to the state of another
939 revision.
940 Returns 0 on success, 1 if nothing to backout or there are unresolved
942 files.
943 Options:
945 --merge
947 merge with old dirstate parent after backout
948 --commit
950 commit if no conflicts were encountered (DEPRECATED)
951 --no-commit
953 do not commit
954 --parent <REV>
956 parent to choose when backing out merge (DEPRECATED)
957 -r,--rev <REV>
959 revision to backout
960 -e, --edit
962 invoke editor on commit messages
963 -t,--tool <TOOL>
965 specify merge tool
966 -I,--include <PATTERN[+]>
968 include names matching the given patterns
969 -X,--exclude <PATTERN[+]>
971 exclude names matching the given patterns
972 -m,--message <TEXT>
974 use text as commit message
975 -l,--logfile <FILE>
977 read commit message from file
978 -d,--date <DATE>
980 record the specified date as commit date
981 -u,--user <USER>
983 record the specified user as committer
984 [+] marked option can be specified multiple times
986 continue
988 resumes an interrupted operation (EXPERIMENTAL):
989 hg continue
991 Finishes a multistep operation like graft, histedit, rebase, merge, and
993 unshelve if they are in an interrupted state.
994 use --dry-run/-n to dry run the command.
996 Options:
998 -n, --dry-run
1000 do not perform actions, just print output
1001 graft
1003 copy changes from other branches onto the current branch:
1004 hg graft [OPTION]... [-r REV]... REV...
1006 This command uses Mercurial's merge logic to copy individual changes
1008 from other branches without merging branches in the history graph. This
1009 is sometimes known as 'backporting' or 'cherry-picking'. By default,
1010 graft will copy user, date, and description from the source changesets.
1011 Changesets that are ancestors of the current revision, that have al‐
1013 ready been grafted, or that are merges will be skipped.
1014 If --log is specified, log messages will have a comment appended of the
1016 form:
1017 (grafted from CHANGESETHASH)
1019 If --force is specified, revisions will be grafted even if they are al‐
1021 ready ancestors of, or have been grafted to, the destination. This is
1022 useful when the revisions have since been backed out.
1023 If a graft merge results in conflicts, the graft process is interrupted
1025 so that the current merge can be manually resolved. Once all conflicts
1026 are addressed, the graft process can be continued with the -c/--con‐
1027 tinue option.
1028 The -c/--continue option reapplies all the earlier options.
1030 The --base option exposes more of how graft internally uses merge with
1032 a custom base revision. --base can be used to specify another ancestor
1033 than the first and only parent.
1034 The command:
1036 hg graft -r 345 --base 234
1038 is thus pretty much the same as:
1040 hg diff --from 234 --to 345 | hg import
1042 but using merge to resolve conflicts and track moved files.
1044 The result of a merge can thus be backported as a single commit by
1046 specifying one of the merge parents as base, and thus effectively
1047 grafting the changes from the other side.
1048 It is also possible to collapse multiple changesets and clean up his‐
1050 tory by specifying another ancestor as base, much like rebase --col‐
1051 lapse --keep.
1052 The commit message can be tweaked after the fact using commit --amend .
1054 For using non-ancestors as the base to backout changes, see the backout
1056 command and the hidden --parent option.
1057 Examples:
1059 • copy a single change to the stable branch and edit its description:
1061 hg update stable
1063 hg graft --edit 9393
1064 • graft a range of changesets with one exception, updating dates:
1066 hg graft -D "2085::2093 and not 2091"
1068 • continue a graft after resolving conflicts:
1070 hg graft -c
1072 • show the source of a grafted changeset:
1074 hg log --debug -r .
1076 • show revisions sorted by date:
1078 hg log -r "sort(all(), date)"
1080 • backport the result of a merge as a single commit:
1082 hg graft -r 123 --base 123^
1084 • land a feature branch as one changeset:
1086 hg up -cr default
1088 hg graft -r featureX --base "ancestor('featureX', 'default')"
1089 See hg help revisions for more about specifying revisions.
1091 Returns 0 on successful completion, 1 if there are unresolved files.
1093 Options:
1095 -r,--rev <REV[+]>
1097 revisions to graft
1098 --base <REV>
1100 base revision when doing the graft merge (ADVANCED)
1101 -c, --continue
1103 resume interrupted graft
1104 --stop stop interrupted graft
1106 --abort
1108 abort interrupted graft
1109 -e, --edit
1111 invoke editor on commit messages
1112 --log append graft info to log message
1114 --no-commit
1116 don't commit, just apply the changes in working directory
1117 -f, --force
1119 force graft
1120 -D, --currentdate
1122 record the current date as commit date
1123 -U, --currentuser
1125 record the current user as committer
1126 -d,--date <DATE>
1128 record the specified date as commit date
1129 -u,--user <USER>
1131 record the specified user as committer
1132 -t,--tool <TOOL>
1134 specify merge tool
1135 -n, --dry-run
1137 do not perform actions, just print output
1138 [+] marked option can be specified multiple times
1140 merge
1142 merge another revision into working directory:
1143 hg merge [-P] [[-r] REV]
1145 The current working directory is updated with all changes made in the
1147 requested revision since the last common predecessor revision.
1148 Files that changed between either parent are marked as changed for the
1150 next commit and a commit must be performed before any further updates
1151 to the repository are allowed. The next commit will have two parents.
1152 --tool can be used to specify the merge tool used for file merges. It
1154 overrides the HGMERGE environment variable and your configuration
1155 files. See hg help merge-tools for options.
1156 If no revision is specified, the working directory's parent is a head
1158 revision, and the current branch contains exactly one other head, the
1159 other head is merged with by default. Otherwise, an explicit revision
1160 with which to merge must be provided.
1161 See hg help resolve for information on handling file conflicts.
1163 To undo an uncommitted merge, use hg merge --abort which will check out
1165 a clean copy of the original merge parent, losing all changes.
1166 Returns 0 on success, 1 if there are unresolved files.
1168 Options:
1170 -f, --force
1172 force a merge including outstanding changes (DEPRECATED)
1173 -r,--rev <REV>
1175 revision to merge
1176 -P, --preview
1178 review revisions to merge (no merge is performed)
1179 --abort
1181 abort the ongoing merge
1182 -t,--tool <TOOL>
1184 specify merge tool
1185 Change organization
1187 bookmarks
1188 create a new bookmark or list existing bookmarks:
1189 hg bookmarks [OPTIONS]... [NAME]...
1191 Bookmarks are labels on changesets to help track lines of development.
1193 Bookmarks are unversioned and can be moved, renamed and deleted.
1194 Deleting or moving a bookmark has no effect on the associated change‐
1195 sets.
1196 Creating or updating to a bookmark causes it to be marked as 'active'.
1198 The active bookmark is indicated with a '*'. When a commit is made,
1199 the active bookmark will advance to the new commit. A plain hg update
1200 will also advance an active bookmark, if possible. Updating away from
1201 a bookmark will cause it to be deactivated.
1202 Bookmarks can be pushed and pulled between repositories (see hg help
1204 push and hg help pull). If a shared bookmark has diverged, a new 'di‐
1205 vergent bookmark' of the form 'name@path' will be created. Using hg
1206 merge will resolve the divergence.
1207 Specifying bookmark as '.' to -m/-d/-l options is equivalent to speci‐
1209 fying the active bookmark's name.
1210 A bookmark named '@' has the special property that hg clone will check
1212 it out by default if it exists.
1213 Template:
1215 The following keywords are supported in addition to the common template
1217 keywords and functions such as {bookmark}. See also hg help templates.
1218 active Boolean. True if the bookmark is active.
1220 Examples:
1222 • create an active bookmark for a new line of development:
1224 hg book new-feature
1226 • create an inactive bookmark as a place marker:
1228 hg book -i reviewed
1230 • create an inactive bookmark on another changeset:
1232 hg book -r .^ tested
1234 • rename bookmark turkey to dinner:
1236 hg book -m turkey dinner
1238 • move the '@' bookmark from another branch:
1240 hg book -f @
1242 • print only the active bookmark name:
1244 hg book -ql .
1246 Options:
1248 -f, --force
1250 force
1251 -r,--rev <REV>
1253 revision for bookmark action
1254 -d, --delete
1256 delete a given bookmark
1257 -m,--rename <OLD>
1259 rename a given bookmark
1260 -i, --inactive
1262 mark a bookmark inactive
1263 -l, --list
1265 list existing bookmarks
1266 -T,--template <TEMPLATE>
1268 display with template
1269 aliases: bookmark
1271 branch
1273 set or show the current branch name:
1274 hg branch [-fC] [NAME]
1276 Note Branch names are permanent and global. Use hg bookmark to create
1278 a light-weight bookmark instead. See hg help glossary for more
1279 information about named branches and bookmarks.
1280 With no argument, show the current branch name. With one argument, set
1282 the working directory branch name (the branch will not exist in the
1283 repository until the next commit). Standard practice recommends that
1284 primary development take place on the 'default' branch.
1285 Unless -f/--force is specified, branch will not let you set a branch
1287 name that already exists.
1288 Use -C/--clean to reset the working directory branch to that of the
1290 parent of the working directory, negating a previous branch change.
1291 Use the command hg update to switch to an existing branch. Use hg com‐
1293 mit --close-branch to mark this branch head as closed. When all heads
1294 of a branch are closed, the branch will be considered closed.
1295 Returns 0 on success.
1297 Options:
1299 -f, --force
1301 set branch name even if it shadows an existing branch
1302 -C, --clean
1304 reset branch name to parent branch name
1305 -r,--rev <VALUE[+]>
1307 change branches of the given revs (EXPERIMENTAL)
1308 [+] marked option can be specified multiple times
1310 branches
1312 list repository named branches:
1313 hg branches [-c]
1315 List the repository's named branches, indicating which ones are inac‐
1317 tive. If -c/--closed is specified, also list branches which have been
1318 marked closed (see hg commit --close-branch).
1319 Use the command hg update to switch to an existing branch.
1321 Template:
1323 The following keywords are supported in addition to the common template
1325 keywords and functions such as {branch}. See also hg help templates.
1326 active Boolean. True if the branch is active.
1328 closed Boolean. True if the branch is closed.
1330 current
1332 Boolean. True if it is the current branch.
1333 Returns 0.
1335 Options:
1337 -a, --active
1339 show only branches that have unmerged heads (DEPRECATED)
1340 -c, --closed
1342 show normal and closed branches
1343 -r,--rev <VALUE[+]>
1345 show branch name(s) of the given rev
1346 -T,--template <TEMPLATE>
1348 display with template
1349 [+] marked option can be specified multiple times
1351 phase
1353 set or show the current phase name:
1354 hg phase [-p|-d|-s] [-f] [-r] [REV...]
1356 With no argument, show the phase name of the current revision(s).
1358 With one of -p/--public, -d/--draft or -s/--secret, change the phase
1360 value of the specified revisions.
1361 Unless -f/--force is specified, hg phase won't move changesets from a
1363 lower phase to a higher phase. Phases are ordered as follows:
1364 public < draft < secret
1366 Returns 0 on success, 1 if some phases could not be changed.
1368 (For more information about the phases concept, see hg help phases.)
1370 Options:
1372 -p, --public
1374 set changeset phase to public
1375 -d, --draft
1377 set changeset phase to draft
1378 -s, --secret
1380 set changeset phase to secret
1381 -f, --force
1383 allow to move boundary backward
1384 -r,--rev <REV[+]>
1386 target revision
1387 [+] marked option can be specified multiple times
1389 tag
1391 add one or more tags for the current or given revision:
1392 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
1394 Name a particular revision using <name>.
1396 Tags are used to name particular revisions of the repository and are
1398 very useful to compare different revisions, to go back to significant
1399 earlier versions or to mark branch points as releases, etc. Changing an
1400 existing tag is normally disallowed; use -f/--force to override.
1401 If no revision is given, the parent of the working directory is used.
1403 To facilitate version control, distribution, and merging of tags, they
1405 are stored as a file named ".hgtags" which is managed similarly to
1406 other project files and can be hand-edited if necessary. This also
1407 means that tagging creates a new commit. The file ".hg/localtags" is
1408 used for local tags (not shared among repositories).
1409 Tag commits are usually made at the head of a branch. If the parent of
1411 the working directory is not a branch head, hg tag aborts; use
1412 -f/--force to force the tag commit to be based on a non-head changeset.
1413 See hg help dates for a list of formats valid for -d/--date.
1415 Since tag names have priority over branch names during revision lookup,
1417 using an existing branch name as a tag name is discouraged.
1418 Returns 0 on success.
1420 Options:
1422 -f, --force
1424 force tag
1425 -l, --local
1427 make the tag local
1428 -r,--rev <REV>
1430 revision to tag
1431 --remove
1433 remove a tag
1434 -e, --edit
1436 invoke editor on commit messages
1437 -m,--message <TEXT>
1439 use text as commit message
1440 -d,--date <DATE>
1442 record the specified date as commit date
1443 -u,--user <USER>
1445 record the specified user as committer
1446 tags
1448 list repository tags:
1449 hg tags
1451 This lists both regular and local tags. When the -v/--verbose switch is
1453 used, a third column "local" is printed for local tags. When the
1454 -q/--quiet switch is used, only the tag name is printed.
1455 Template:
1457 The following keywords are supported in addition to the common template
1459 keywords and functions such as {tag}. See also hg help templates.
1460 type String. local for local tags.
1462 Returns 0 on success.
1464 Options:
1466 -T,--template <TEMPLATE>
1468 display with template
1469 File content management
1471 annotate
1472 show changeset information by line for each file:
1473 hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...
1475 List changes in files, showing the revision id responsible for each
1477 line.
1478 This command is useful for discovering when a change was made and by
1480 whom.
1481 If you include --file, --user, or --date, the revision number is sup‐
1483 pressed unless you also include --number.
1484 Without the -a/--text option, annotate will avoid processing files it
1486 detects as binary. With -a, annotate will annotate the file anyway, al‐
1487 though the results will probably be neither useful nor desirable.
1488 Template:
1490 The following keywords are supported in addition to the common template
1492 keywords and functions. See also hg help templates.
1493 lines List of lines with annotation data.
1495 path String. Repository-absolute path of the specified file.
1497 And each entry of {lines} provides the following sub-keywords in addi‐
1499 tion to {date}, {node}, {rev}, {user}, etc.
1500 line String. Line content.
1502 lineno Integer. Line number at that revision.
1504 path String. Repository-absolute path of the file at that revision.
1506 See hg help templates.operators for the list expansion syntax.
1508 Returns 0 on success.
1510 Options:
1512 -r,--rev <REV>
1514 annotate the specified revision
1515 --follow
1517 follow copies/renames and list the filename (DEPRECATED)
1518 --no-follow
1520 don't follow copies and renames
1521 -a, --text
1523 treat all files as text
1524 -u, --user
1526 list the author (long with -v)
1527 -f, --file
1529 list the filename
1530 -d, --date
1532 list the date (short with -q)
1533 -n, --number
1535 list the revision number (default)
1536 -c, --changeset
1538 list the changeset
1539 -l, --line-number
1541 show line number at the first appearance
1542 --skip <REV[+]>
1544 revset to not display (EXPERIMENTAL)
1545 -w, --ignore-all-space
1547 ignore white space when comparing lines
1548 -b, --ignore-space-change
1550 ignore changes in the amount of white space
1551 -B, --ignore-blank-lines
1553 ignore changes whose lines are all blank
1554 -Z, --ignore-space-at-eol
1556 ignore changes in whitespace at EOL
1557 -I,--include <PATTERN[+]>
1559 include names matching the given patterns
1560 -X,--exclude <PATTERN[+]>
1562 exclude names matching the given patterns
1563 -T,--template <TEMPLATE>
1565 display with template
1566 [+] marked option can be specified multiple times
1568 aliases: blame
1570 cat
1572 output the current or given revision of files:
1573 hg cat [OPTION]... FILE...
1575 Print the specified files as they were at the given revision. If no re‐
1577 vision is given, the parent of the working directory is used.
1578 Output may be to a file, in which case the name of the file is given
1580 using a template string. See hg help templates. In addition to the com‐
1581 mon template keywords, the following formatting rules are supported:
1582 %%
1584 literal "%" character
1586 %s
1588 basename of file being printed
1590 %d
1592 dirname of file being printed, or '.' if in repository root
1594 %p
1596 root-relative path name of file being printed
1598 %H
1600 changeset hash (40 hexadecimal digits)
1602 %R
1604 changeset revision number
1606 %h
1608 short-form changeset hash (12 hexadecimal digits)
1610 %r
1612 zero-padded changeset revision number
1614 %b
1616 basename of the exporting repository
1618 \
1620 literal "" character
1622 Template:
1624 The following keywords are supported in addition to the common template
1626 keywords and functions. See also hg help templates.
1627 data String. File content.
1629 path String. Repository-absolute path of the file.
1631 Returns 0 on success.
1633 Options:
1635 -o,--output <FORMAT>
1637 print output to file with formatted name
1638 -r,--rev <REV>
1640 print the given revision
1641 --decode
1643 apply any matching decode filter
1644 -I,--include <PATTERN[+]>
1646 include names matching the given patterns
1647 -X,--exclude <PATTERN[+]>
1649 exclude names matching the given patterns
1650 -T,--template <TEMPLATE>
1652 display with template
1653 [+] marked option can be specified multiple times
1655 copy
1657 mark files as copied for the next commit:
1658 hg copy [OPTION]... (SOURCE... DEST | --forget DEST...)
1660 Mark dest as having copies of source files. If dest is a directory,
1662 copies are put in that directory. If dest is a file, the source must be
1663 a single file.
1664 By default, this command copies the contents of files as they exist in
1666 the working directory. If invoked with -A/--after, the operation is
1667 recorded, but no copying is performed.
1668 To undo marking a destination file as copied, use --forget. With that
1670 option, all given (positional) arguments are unmarked as copies. The
1671 destination file(s) will be left in place (still tracked).
1672 This command takes effect with the next commit by default.
1674 Returns 0 on success, 1 if errors are encountered.
1676 Options:
1678 --forget
1680 unmark a destination file as copied
1681 -A, --after
1683 record a copy that has already occurred
1684 --at-rev <REV>
1686 (un)mark copies in the given revision (EXPERIMENTAL)
1687 -f, --force
1689 forcibly copy over an existing managed file
1690 -I,--include <PATTERN[+]>
1692 include names matching the given patterns
1693 -X,--exclude <PATTERN[+]>
1695 exclude names matching the given patterns
1696 -n, --dry-run
1698 do not perform actions, just print output
1699 [+] marked option can be specified multiple times
1701 aliases: cp
1703 diff
1705 diff repository (or selected files):
1706 hg diff [OPTION]... ([-c REV] | [--from REV1] [--to REV2]) [FILE]...
1708 Show differences between revisions for the specified files.
1710 Differences between files are shown using the unified diff format.
1712 Note hg diff may generate unexpected results for merges, as it will
1714 default to comparing against the working directory's first par‐
1715 ent changeset if no revisions are specified.
1716 By default, the working directory files are compared to its first par‐
1718 ent. To see the differences from another revision, use --from. To see
1719 the difference to another revision, use --to. For example, hg diff
1720 --from .^ will show the differences from the working copy's grandparent
1721 to the working copy, hg diff --to . will show the diff from the working
1722 copy to its parent (i.e. the reverse of the default), and hg diff
1723 --from 1.0 --to 1.2 will show the diff between those two revisions.
1724 Alternatively you can specify -c/--change with a revision to see the
1726 changes in that changeset relative to its first parent (i.e. hg diff -c
1727 42 is equivalent to hg diff --from 42^ --to 42)
1728 Without the -a/--text option, diff will avoid generating diffs of files
1730 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1731 bly with undesirable results.
1732 Use the -g/--git option to generate diffs in the git extended diff for‐
1734 mat. For more information, read hg help diffs.
1735 Examples:
1737 • compare a file in the current working directory to its parent:
1739 hg diff foo.c
1741 • compare two historical versions of a directory, with rename info:
1743 hg diff --git --from 1.0 --to 1.2 lib/
1745 • get change stats relative to the last change on some date:
1747 hg diff --stat --from "date('may 2')"
1749 • diff all newly-added files that contain a keyword:
1751 hg diff "set:added() and grep(GNU)"
1753 • compare a revision and its parents:
1755 hg diff -c 9353 # compare against first parent
1757 hg diff --from 9353^ --to 9353 # same using revset syntax
1758 hg diff --from 9353^2 --to 9353 # compare against the second parent
1759 Returns 0 on success.
1761 Options:
1763 -r,--rev <REV[+]>
1765 revision (DEPRECATED)
1766 --from <REV1>
1768 revision to diff from
1769 --to <REV2>
1771 revision to diff to
1772 -c,--change <REV>
1774 change made by revision
1775 -a, --text
1777 treat all files as text
1778 -g, --git
1780 use git extended diff format (DEFAULT: diff.git)
1781 --binary
1783 generate binary diffs in git mode (default)
1784 --nodates
1786 omit dates from diff headers
1787 --noprefix
1789 omit a/ and b/ prefixes from filenames
1790 -p, --show-function
1792 show which function each change is in (DEFAULT: diff.showfunc)
1793 --reverse
1795 produce a diff that undoes the changes
1796 -w, --ignore-all-space
1798 ignore white space when comparing lines
1799 -b, --ignore-space-change
1801 ignore changes in the amount of white space
1802 -B, --ignore-blank-lines
1804 ignore changes whose lines are all blank
1805 -Z, --ignore-space-at-eol
1807 ignore changes in whitespace at EOL
1808 -U,--unified <NUM>
1810 number of lines of context to show
1811 --stat output diffstat-style summary of changes
1813 --root <DIR>
1815 produce diffs relative to subdirectory
1816 -I,--include <PATTERN[+]>
1818 include names matching the given patterns
1819 -X,--exclude <PATTERN[+]>
1821 exclude names matching the given patterns
1822 -S, --subrepos
1824 recurse into subrepositories
1825 [+] marked option can be specified multiple times
1827 grep
1829 search for a pattern in specified files:
1830 hg grep [--diff] [OPTION]... PATTERN [FILE]...
1832 Search the working directory or revision history for a regular expres‐
1834 sion in the specified files for the entire repository.
1835 By default, grep searches the repository files in the working directory
1837 and prints the files where it finds a match. To specify historical re‐
1838 visions instead of the working directory, use the --rev flag.
1839 To search instead historical revision differences that contains a
1841 change in match status ("-" for a match that becomes a non-match, or
1842 "+" for a non-match that becomes a match), use the --diff flag.
1843 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1845 If no FILEs are specified and the --rev flag isn't supplied, all files
1847 in the working directory are searched. When using the --rev flag and
1848 specifying FILEs, use the --follow argument to also follow the speci‐
1849 fied FILEs across renames and copies.
1850 Template:
1852 The following keywords are supported in addition to the common template
1854 keywords and functions. See also hg help templates.
1855 change String. Character denoting insertion + or removal -. Available
1857 if --diff is specified.
1858 lineno Integer. Line number of the match.
1860 path String. Repository-absolute path of the file.
1862 texts List of text chunks.
1864 And each entry of {texts} provides the following sub-keywords.
1866 matched
1868 Boolean. True if the chunk matches the specified pattern.
1869 text String. Chunk content.
1871 See hg help templates.operators for the list expansion syntax.
1873 Returns 0 if a match is found, 1 otherwise.
1875 Options:
1877 -0, --print0
1879 end fields with NUL
1880 --all an alias to --diff (DEPRECATED)
1882 --diff search revision differences for when the pattern was added or
1884 removed
1885 -a, --text
1887 treat all files as text
1888 -f, --follow
1890 follow changeset history, or file history across copies and re‐
1891 names
1892 -i, --ignore-case
1894 ignore case when matching
1895 -l, --files-with-matches
1897 print only filenames and revisions that match
1898 -n, --line-number
1900 print matching line numbers
1901 -r,--rev <REV[+]>
1903 search files changed within revision range
1904 --all-files
1906 include all files in the changeset while grepping (DEPRECATED)
1907 -u, --user
1909 list the author (long with -v)
1910 -d, --date
1912 list the date (short with -q)
1913 -T,--template <TEMPLATE>
1915 display with template
1916 -I,--include <PATTERN[+]>
1918 include names matching the given patterns
1919 -X,--exclude <PATTERN[+]>
1921 exclude names matching the given patterns
1922 [+] marked option can be specified multiple times
1924 Change navigation
1926 bisect
1927 subdivision search of changesets:
1928 hg bisect [-gbsr] [-U] [-c CMD] [REV]
1930 This command helps to find changesets which introduce problems. To use,
1932 mark the earliest changeset you know exhibits the problem as bad, then
1933 mark the latest changeset which is free from the problem as good. Bi‐
1934 sect will update your working directory to a revision for testing (un‐
1935 less the -U/--noupdate option is specified). Once you have performed
1936 tests, mark the working directory as good or bad, and bisect will ei‐
1937 ther update to another candidate changeset or announce that it has
1938 found the bad revision.
1939 As a shortcut, you can also use the revision argument to mark a revi‐
1941 sion as good or bad without checking it out first.
1942 If you supply a command, it will be used for automatic bisection. The
1944 environment variable HG_NODE will contain the ID of the changeset being
1945 tested. The exit status of the command will be used to mark revisions
1946 as good or bad: status 0 means good, 125 means to skip the revision,
1947 127 (command not found) will abort the bisection, and any other
1948 non-zero exit status means the revision is bad.
1949 Some examples:
1951 • start a bisection with known bad revision 34, and good revision 12:
1953 hg bisect --bad 34
1955 hg bisect --good 12
1956 • advance the current bisection by marking current revision as good or
1958 bad:
1959 hg bisect --good
1961 hg bisect --bad
1962 • mark the current revision, or a known revision, to be skipped (e.g.
1964 if that revision is not usable because of another issue):
1965 hg bisect --skip
1967 hg bisect --skip 23
1968 • skip all revisions that do not touch directories foo or bar:
1970 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
1972 • forget the current bisection:
1974 hg bisect --reset
1976 • use 'make && make tests' to automatically find the first broken revi‐
1978 sion:
1979 hg bisect --reset
1981 hg bisect --bad 34
1982 hg bisect --good 12
1983 hg bisect --command "make && make tests"
1984 • see all changesets whose states are already known in the current bi‐
1986 section:
1987 hg log -r "bisect(pruned)"
1989 • see the changeset currently being bisected (especially useful if run‐
1991 ning with -U/--noupdate):
1992 hg log -r "bisect(current)"
1994 • see all changesets that took part in the current bisection:
1996 hg log -r "bisect(range)"
1998 • you can even get a nice graph:
2000 hg log --graph -r "bisect(range)"
2002 See hg help revisions.bisect for more about the bisect() predicate.
2004 Returns 0 on success.
2006 Options:
2008 -r, --reset
2010 reset bisect state
2011 -g, --good
2013 mark changeset good
2014 -b, --bad
2016 mark changeset bad
2017 -s, --skip
2019 skip testing changeset
2020 -e, --extend
2022 extend the bisect range
2023 -c,--command <CMD>
2025 use command to check changeset state
2026 -U, --noupdate
2028 do not update to target
2029 heads
2031 show branch heads:
2032 hg heads [-ct] [-r STARTREV] [REV]...
2034 With no arguments, show all open branch heads in the repository.
2036 Branch heads are changesets that have no descendants on the same
2037 branch. They are where development generally takes place and are the
2038 usual targets for update and merge operations.
2039 If one or more REVs are given, only open branch heads on the branches
2041 associated with the specified changesets are shown. This means that you
2042 can use hg heads . to see the heads on the currently checked-out
2043 branch.
2044 If -c/--closed is specified, also show branch heads marked closed (see
2046 hg commit --close-branch).
2047 If STARTREV is specified, only those heads that are descendants of
2049 STARTREV will be displayed.
2050 If -t/--topo is specified, named branch mechanics will be ignored and
2052 only topological heads (changesets with no children) will be shown.
2053 Returns 0 if matching heads are found, 1 if not.
2055 Options:
2057 -r,--rev <STARTREV>
2059 show only heads which are descendants of STARTREV
2060 -t, --topo
2062 show topological heads only
2063 -a, --active
2065 show active branchheads only (DEPRECATED)
2066 -c, --closed
2068 show normal and closed branch heads
2069 --style <STYLE>
2071 display using template map file (DEPRECATED)
2072 -T,--template <TEMPLATE>
2074 display with template
2075 identify
2077 identify the working directory or specified revision:
2078 hg identify [-nibtB] [-r REV] [SOURCE]
2080 Print a summary identifying the repository state at REV using one or
2082 two parent hash identifiers, followed by a "+" if the working directory
2083 has uncommitted changes, the branch name (if not default), a list of
2084 tags, and a list of bookmarks.
2085 When REV is not given, print a summary of the current state of the
2087 repository including the working directory. Specify -r. to get informa‐
2088 tion of the working directory parent without scanning uncommitted
2089 changes.
2090 Specifying a path to a repository root or Mercurial bundle will cause
2092 lookup to operate on that repository/bundle.
2093 Template:
2095 The following keywords are supported in addition to the common template
2097 keywords and functions. See also hg help templates.
2098 dirty String. Character + denoting if the working directory has uncom‐
2100 mitted changes.
2101 id String. One or two nodes, optionally followed by +.
2103 parents
2105 List of strings. Parent nodes of the changeset.
2106 Examples:
2108 • generate a build identifier for the working directory:
2110 hg id --id > build-id.dat
2112 • find the revision corresponding to a tag:
2114 hg id -n -r 1.3
2116 • check the most recent revision of a remote repository:
2118 hg id -r tip https://www.mercurial-scm.org/repo/hg/
2120 See hg log for generating more information about specific revisions,
2122 including full hash identifiers.
2123 Returns 0 if successful.
2125 Options:
2127 -r,--rev <REV>
2129 identify the specified revision
2130 -n, --num
2132 show local revision number
2133 -i, --id
2135 show global revision id
2136 -b, --branch
2138 show branch
2139 -t, --tags
2141 show tags
2142 -B, --bookmarks
2144 show bookmarks
2145 -e,--ssh <CMD>
2147 specify ssh command to use
2148 --remotecmd <CMD>
2150 specify hg command to run on the remote side
2151 --insecure
2153 do not verify server certificate (ignoring web.cacerts config)
2154 -T,--template <TEMPLATE>
2156 display with template
2157 aliases: id
2159 log
2161 show revision history of entire repository or files:
2162 hg log [OPTION]... [FILE]
2164 Print the revision history of the specified files or the entire
2166 project.
2167 If no revision range is specified, the default is tip:0 unless --follow
2169 is set.
2170 File history is shown without following rename or copy history of
2172 files. Use -f/--follow with a filename to follow history across renames
2173 and copies. --follow without a filename will only show ancestors of the
2174 starting revisions. The starting revisions can be specified by
2175 -r/--rev, which default to the working directory parent.
2176 By default this command prints revision number and changeset id, tags,
2178 non-trivial parents, user, date and time, and a summary for each com‐
2179 mit. When the -v/--verbose switch is used, the list of changed files
2180 and full commit message are shown.
2181 With --graph the revisions are shown as an ASCII art DAG with the most
2183 recent changeset at the top. 'o' is a changeset, '@' is a working di‐
2184 rectory parent, '%' is a changeset involved in an unresolved merge con‐
2185 flict, '_' closes a branch, 'x' is obsolete, '*' is unstable, and '+'
2186 represents a fork where the changeset from the lines below is a parent
2187 of the 'o' merge on the same line. Paths in the DAG are represented
2188 with '|', '/' and so forth. ':' in place of a '|' indicates one or more
2189 revisions in a path are omitted.
2190 Use -L/--line-range FILE,M:N options to follow the history of lines
2192 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2193 fied line range will be shown. This option requires --follow; it can be
2194 specified multiple times. Currently, this option is not compatible with
2195 --graph. This option is experimental.
2196 Note hg log --patch may generate unexpected diff output for merge
2198 changesets, as it will only compare the merge changeset against
2199 its first parent. Also, only files different from BOTH parents
2200 will appear in files:.
2201 Note For performance reasons, hg log FILE may omit duplicate changes
2203 made on branches and will not show removals or mode changes. To
2204 see all such changes, use the --removed switch.
2205 Note The history resulting from -L/--line-range options depends on
2207 diff options; for instance if white-spaces are ignored, respec‐
2208 tive changes with only white-spaces in specified line range will
2209 not be listed.
2210 Some examples:
2212 • changesets with full descriptions and file lists:
2214 hg log -v
2216 • changesets ancestral to the working directory:
2218 hg log -f
2220 • last 10 commits on the current branch:
2222 hg log -l 10 -b .
2224 • changesets showing all modifications of a file, including removals:
2226 hg log --removed file.c
2228 • all changesets that touch a directory, with diffs, excluding merges:
2230 hg log -Mp lib/
2232 • all revision numbers that match a keyword:
2234 hg log -k bug --template "{rev}\n"
2236 • the full hash identifier of the working directory parent:
2238 hg log -r . --template "{node}\n"
2240 • list available log templates:
2242 hg log -T list
2244 • check if a given changeset is included in a tagged release:
2246 hg log -r "a21ccf and ancestor(1.9)"
2248 • find all changesets by some user in a date range:
2250 hg log -k alice -d "may 2008 to jul 2008"
2252 • summary of all changesets after the last tag:
2254 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2256 • changesets touching lines 13 to 23 for file.c:
2258 hg log -L file.c,13:23
2260 • changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2262 main.c with patch:
2263 hg log -L file.c,13:23 -L main.c,2:6 -p
2265 See hg help dates for a list of formats valid for -d/--date.
2267 See hg help revisions for more about specifying and ordering revisions.
2269 See hg help templates for more about pre-packaged styles and specifying
2271 custom templates. The default template used by the log command can be
2272 customized via the command-templates.log configuration setting.
2273 Returns 0 on success.
2275 Options:
2277 -f, --follow
2279 follow changeset history, or file history across copies and re‐
2280 names
2281 --follow-first
2283 only follow the first parent of merge changesets (DEPRECATED)
2284 -d,--date <DATE>
2286 show revisions matching date spec
2287 -C, --copies
2289 show copied files
2290 -k,--keyword <TEXT[+]>
2292 do case-insensitive search for a given text
2293 -r,--rev <REV[+]>
2295 revisions to select or follow from
2296 -L,--line-range <FILE,RANGE[+]>
2298 follow line range of specified file (EXPERIMENTAL)
2299 --removed
2301 include revisions where files were removed
2302 -m, --only-merges
2304 show only merges (DEPRECATED) (use -r "merge()" instead)
2305 -u,--user <USER[+]>
2307 revisions committed by user
2308 --only-branch <BRANCH[+]>
2310 show only changesets within the given named branch (DEPRECATED)
2311 -b,--branch <BRANCH[+]>
2313 show changesets within the given named branch
2314 -B,--bookmark <BOOKMARK[+]>
2316 show changesets within the given bookmark
2317 -P,--prune <REV[+]>
2319 do not display revision or any of its ancestors
2320 -p, --patch
2322 show patch
2323 -g, --git
2325 use git extended diff format
2326 -l,--limit <NUM>
2328 limit number of changes displayed
2329 -M, --no-merges
2331 do not show merges
2332 --stat output diffstat-style summary of changes
2334 -G, --graph
2336 show the revision DAG
2337 --style <STYLE>
2339 display using template map file (DEPRECATED)
2340 -T,--template <TEMPLATE>
2342 display with template
2343 -I,--include <PATTERN[+]>
2345 include names matching the given patterns
2346 -X,--exclude <PATTERN[+]>
2348 exclude names matching the given patterns
2349 [+] marked option can be specified multiple times
2351 aliases: history
2353 parents
2355 show the parents of the working directory or revision (DEPRECATED):
2356 hg parents [-r REV] [FILE]
2358 Print the working directory's parent revisions. If a revision is given
2360 via -r/--rev, the parent of that revision will be printed. If a file
2361 argument is given, the revision in which the file was last changed (be‐
2362 fore the working directory revision or the argument to --rev if given)
2363 is printed.
2364 This command is equivalent to:
2366 hg log -r "p1()+p2()" or
2368 hg log -r "p1(REV)+p2(REV)" or
2369 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2370 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2371 See hg summary and hg help revsets for related information.
2373 Returns 0 on success.
2375 Options:
2377 -r,--rev <REV>
2379 show parents of the specified revision
2380 --style <STYLE>
2382 display using template map file (DEPRECATED)
2383 -T,--template <TEMPLATE>
2385 display with template
2386 tip
2388 show the tip revision (DEPRECATED):
2389 hg tip [-p] [-g]
2391 The tip revision (usually just called the tip) is the changeset most
2393 recently added to the repository (and therefore the most recently
2394 changed head).
2395 If you have just made a commit, that commit will be the tip. If you
2397 have just pulled changes from another repository, the tip of that
2398 repository becomes the current tip. The "tip" tag is special and cannot
2399 be renamed or assigned to a different changeset.
2400 This command is deprecated, please use hg heads instead.
2402 Returns 0 on success.
2404 Options:
2406 -p, --patch
2408 show patch
2409 -g, --git
2411 use git extended diff format
2412 --style <STYLE>
2414 display using template map file (DEPRECATED)
2415 -T,--template <TEMPLATE>
2417 display with template
2418 Working directory management
2420 add
2421 add the specified files on the next commit:
2422 hg add [OPTION]... [FILE]...
2424 Schedule files to be version controlled and added to the repository.
2426 The files will be added to the repository at the next commit. To undo
2428 an add before that, see hg forget.
2429 If no names are given, add all files to the repository (except files
2431 matching .hgignore).
2432 Examples:
2434 • New (unknown) files are added automatically by hg add:
2436 $ ls
2438 foo.c
2439 $ hg status
2440 ? foo.c
2441 $ hg add
2442 adding foo.c
2443 $ hg status
2444 A foo.c
2445 • Specific files to be added can be specified:
2447 $ ls
2449 bar.c foo.c
2450 $ hg status
2451 ? bar.c
2452 ? foo.c
2453 $ hg add bar.c
2454 $ hg status
2455 A bar.c
2456 ? foo.c
2457 Returns 0 if all files are successfully added.
2459 Options:
2461 -I,--include <PATTERN[+]>
2463 include names matching the given patterns
2464 -X,--exclude <PATTERN[+]>
2466 exclude names matching the given patterns
2467 -S, --subrepos
2469 recurse into subrepositories
2470 -n, --dry-run
2472 do not perform actions, just print output
2473 [+] marked option can be specified multiple times
2475 addremove
2477 add all new files, delete all missing files:
2478 hg addremove [OPTION]... [FILE]...
2480 Add all new files and remove all missing files from the repository.
2482 Unless names are given, new files are ignored if they match any of the
2484 patterns in .hgignore. As with add, these changes take effect at the
2485 next commit.
2486 Use the -s/--similarity option to detect renamed files. This option
2488 takes a percentage between 0 (disabled) and 100 (files must be identi‐
2489 cal) as its parameter. With a parameter greater than 0, this compares
2490 every removed file with every added file and records those similar
2491 enough as renames. Detecting renamed files this way can be expensive.
2492 After using this option, hg status -C can be used to check which files
2493 were identified as moved or renamed. If not specified, -s/--similarity
2494 defaults to 100 and only renames of identical files are detected.
2495 Examples:
2497 • A number of files (bar.c and foo.c) are new, while foobar.c has
2499 been removed (without using hg remove) from the repository:
2500 $ ls
2502 bar.c foo.c
2503 $ hg status
2504 ! foobar.c
2505 ? bar.c
2506 ? foo.c
2507 $ hg addremove
2508 adding bar.c
2509 adding foo.c
2510 removing foobar.c
2511 $ hg status
2512 A bar.c
2513 A foo.c
2514 R foobar.c
2515 • A file foobar.c was moved to foo.c without using hg rename. Af‐
2517 terwards, it was edited slightly:
2518 $ ls
2520 foo.c
2521 $ hg status
2522 ! foobar.c
2523 ? foo.c
2524 $ hg addremove --similarity 90
2525 removing foobar.c
2526 adding foo.c
2527 recording removal of foobar.c as rename to foo.c (94% similar)
2528 $ hg status -C
2529 A foo.c
2530 foobar.c
2531 R foobar.c
2532 Returns 0 if all files are successfully added.
2534 Options:
2536 -s,--similarity <SIMILARITY>
2538 guess renamed files by similarity (0<=s<=100)
2539 -S, --subrepos
2541 recurse into subrepositories
2542 -I,--include <PATTERN[+]>
2544 include names matching the given patterns
2545 -X,--exclude <PATTERN[+]>
2547 exclude names matching the given patterns
2548 -n, --dry-run
2550 do not perform actions, just print output
2551 [+] marked option can be specified multiple times
2553 files
2555 list tracked files:
2556 hg files [OPTION]... [FILE]...
2558 Print files under Mercurial control in the working directory or speci‐
2560 fied revision for given files (excluding removed files). Files can be
2561 specified as filenames or filesets.
2562 If no files are given to match, this command prints the names of all
2564 files under Mercurial control.
2565 Template:
2567 The following keywords are supported in addition to the common template
2569 keywords and functions. See also hg help templates.
2570 flags String. Character denoting file's symlink and executable bits.
2572 path String. Repository-absolute path of the file.
2574 size Integer. Size of the file in bytes.
2576 Examples:
2578 • list all files under the current directory:
2580 hg files .
2582 • shows sizes and flags for current revision:
2584 hg files -vr .
2586 • list all files named README:
2588 hg files -I "**/README"
2590 • list all binary files:
2592 hg files "set:binary()"
2594 • find files containing a regular expression:
2596 hg files "set:grep('bob')"
2598 • search tracked file contents with xargs and grep:
2600 hg files -0 | xargs -0 grep foo
2602 See hg help patterns and hg help filesets for more information on spec‐
2604 ifying file patterns.
2605 Returns 0 if a match is found, 1 otherwise.
2607 Options:
2609 -r,--rev <REV>
2611 search the repository as it is in REV
2612 -0, --print0
2614 end filenames with NUL, for use with xargs
2615 -I,--include <PATTERN[+]>
2617 include names matching the given patterns
2618 -X,--exclude <PATTERN[+]>
2620 exclude names matching the given patterns
2621 -T,--template <TEMPLATE>
2623 display with template
2624 -S, --subrepos
2626 recurse into subrepositories
2627 [+] marked option can be specified multiple times
2629 forget
2631 forget the specified files on the next commit:
2632 hg forget [OPTION]... FILE...
2634 Mark the specified files so they will no longer be tracked after the
2636 next commit.
2637 This only removes files from the current branch, not from the entire
2639 project history, and it does not delete them from the working direc‐
2640 tory.
2641 To delete the file from the working directory, see hg remove.
2643 To undo a forget before the next commit, see hg add.
2645 Examples:
2647 • forget newly-added binary files:
2649 hg forget "set:added() and binary()"
2651 • forget files that would be excluded by .hgignore:
2653 hg forget "set:hgignore()"
2655 Returns 0 on success.
2657 Options:
2659 -i, --interactive
2661 use interactive mode
2662 -I,--include <PATTERN[+]>
2664 include names matching the given patterns
2665 -X,--exclude <PATTERN[+]>
2667 exclude names matching the given patterns
2668 -n, --dry-run
2670 do not perform actions, just print output
2671 [+] marked option can be specified multiple times
2673 locate
2675 locate files matching specific patterns (DEPRECATED):
2676 hg locate [OPTION]... [PATTERN]...
2678 Print files under Mercurial control in the working directory whose
2680 names match the given patterns.
2681 By default, this command searches all directories in the working direc‐
2683 tory. To search just the current directory and its subdirectories, use
2684 "--include .".
2685 If no patterns are given to match, this command prints the names of all
2687 files under Mercurial control in the working directory.
2688 If you want to feed the output of this command into the "xargs" com‐
2690 mand, use the -0 option to both this command and "xargs". This will
2691 avoid the problem of "xargs" treating single filenames that contain
2692 whitespace as multiple filenames.
2693 See hg help files for a more versatile command.
2695 Returns 0 if a match is found, 1 otherwise.
2697 Options:
2699 -r,--rev <REV>
2701 search the repository as it is in REV
2702 -0, --print0
2704 end filenames with NUL, for use with xargs
2705 -f, --fullpath
2707 print complete paths from the filesystem root
2708 -I,--include <PATTERN[+]>
2710 include names matching the given patterns
2711 -X,--exclude <PATTERN[+]>
2713 exclude names matching the given patterns
2714 [+] marked option can be specified multiple times
2716 remove
2718 remove the specified files on the next commit:
2719 hg remove [OPTION]... FILE...
2721 Schedule the indicated files for removal from the current branch.
2723 This command schedules the files to be removed at the next commit. To
2725 undo a remove before that, see hg revert. To undo added files, see hg
2726 forget.
2727 -A/--after can be used to remove only files that have already been
2729 deleted, -f/--force can be used to force deletion, and -Af can be used
2730 to remove files from the next revision without deleting them from the
2731 working directory.
2732 The following table details the behavior of remove for different file
2734 states (columns) and option combinations (rows). The file states are
2735 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2736 status). The actions are Warn, Remove (from branch) and Delete (from
2737 disk):
2738 ┌──────────┬───┬────┬────┬───┐
2740 │opt/state │ A │ C │ M │ ! │
2741 ├──────────┼───┼────┼────┼───┤
2742 │none │ W │ RD │ W │ R │
2743 ├──────────┼───┼────┼────┼───┤
2744 │-f │ R │ RD │ RD │ R │
2745 ├──────────┼───┼────┼────┼───┤
2746 │-A │ W │ W │ W │ R │
2747 ├──────────┼───┼────┼────┼───┤
2748 │-Af │ R │ R │ R │ R │
2749 └──────────┴───┴────┴────┴───┘
2750 Note hg remove never deletes files in Added [A] state from the work‐
2752 ing directory, not even if --force is specified.
2753 Returns 0 on success, 1 if any warnings encountered.
2755 Options:
2757 -A, --after
2759 record delete for missing files
2760 -f, --force
2762 forget added files, delete modified files
2763 -S, --subrepos
2765 recurse into subrepositories
2766 -I,--include <PATTERN[+]>
2768 include names matching the given patterns
2769 -X,--exclude <PATTERN[+]>
2771 exclude names matching the given patterns
2772 -n, --dry-run
2774 do not perform actions, just print output
2775 [+] marked option can be specified multiple times
2777 aliases: rm
2779 rename
2781 rename files; equivalent of copy + remove:
2782 hg rename [OPTION]... SOURCE... DEST
2784 Mark dest as copies of sources; mark sources for deletion. If dest is a
2786 directory, copies are put in that directory. If dest is a file, there
2787 can only be one source.
2788 By default, this command copies the contents of files as they exist in
2790 the working directory. If invoked with -A/--after, the operation is
2791 recorded, but no copying is performed.
2792 This command takes effect at the next commit. To undo a rename before
2794 that, see hg revert.
2795 Returns 0 on success, 1 if errors are encountered.
2797 Options:
2799 -A, --after
2801 record a rename that has already occurred
2802 --at-rev <REV>
2804 (un)mark renames in the given revision (EXPERIMENTAL)
2805 -f, --force
2807 forcibly move over an existing managed file
2808 -I,--include <PATTERN[+]>
2810 include names matching the given patterns
2811 -X,--exclude <PATTERN[+]>
2813 exclude names matching the given patterns
2814 -n, --dry-run
2816 do not perform actions, just print output
2817 [+] marked option can be specified multiple times
2819 aliases: move mv
2821 resolve
2823 redo merges or set/view the merge status of files:
2824 hg resolve [OPTION]... [FILE]...
2826 Merges with unresolved conflicts are often the result of non-interac‐
2828 tive merging using the internal:merge configuration setting, or a com‐
2829 mand-line merge tool like diff3. The resolve command is used to manage
2830 the files involved in a merge, after hg merge has been run, and before
2831 hg commit is run (i.e. the working directory must have two parents).
2832 See hg help merge-tools for information on configuring merge tools.
2833 The resolve command can be used in the following ways:
2835 • hg resolve [--re-merge] [--tool TOOL] FILE...: attempt to re-merge
2837 the specified files, discarding any previous merge attempts. Re-merg‐
2838 ing is not performed for files already marked as resolved. Use
2839 --all/-a to select all unresolved files. --tool can be used to spec‐
2840 ify the merge tool used for the given files. It overrides the HGMERGE
2841 environment variable and your configuration files. Previous file
2842 contents are saved with a .orig suffix.
2843 • hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
2845 having manually fixed-up the files). The default is to mark all unre‐
2846 solved files.
2847 • hg resolve -u [FILE]...: mark a file as unresolved. The default is to
2849 mark all resolved files.
2850 • hg resolve -l: list files which had or still have conflicts. In the
2852 printed list, U = unresolved and R = resolved. You can use set:unre‐
2853 solved() or set:resolved() to filter the list. See hg help filesets
2854 for details.
2855 Note Mercurial will not let you commit files with unresolved merge
2857 conflicts. You must use hg resolve -m ... before you can commit
2858 after a conflicting merge.
2859 Template:
2861 The following keywords are supported in addition to the common template
2863 keywords and functions. See also hg help templates.
2864 mergestatus
2866 String. Character denoting merge conflicts, U or R.
2867 path String. Repository-absolute path of the file.
2869 Returns 0 on success, 1 if any files fail a resolve attempt.
2871 Options:
2873 -a, --all
2875 select all unresolved files
2876 -l, --list
2878 list state of files needing merge
2879 -m, --mark
2881 mark files as resolved
2882 -u, --unmark
2884 mark files as unresolved
2885 -n, --no-status
2887 hide status prefix
2888 --re-merge
2890 re-merge files
2891 -t,--tool <TOOL>
2893 specify merge tool
2894 -I,--include <PATTERN[+]>
2896 include names matching the given patterns
2897 -X,--exclude <PATTERN[+]>
2899 exclude names matching the given patterns
2900 -T,--template <TEMPLATE>
2902 display with template
2903 [+] marked option can be specified multiple times
2905 revert
2907 restore files to their checkout state:
2908 hg revert [OPTION]... [-r REV] [NAME]...
2910 Note To check out earlier revisions, you should use hg update REV.
2912 To cancel an uncommitted merge (and lose your changes), use hg
2913 merge --abort.
2914 With no revision specified, revert the specified files or directories
2916 to the contents they had in the parent of the working directory. This
2917 restores the contents of files to an unmodified state and unschedules
2918 adds, removes, copies, and renames. If the working directory has two
2919 parents, you must explicitly specify a revision.
2920 Using the -r/--rev or -d/--date options, revert the given files or di‐
2922 rectories to their states as of a specific revision. Because revert
2923 does not change the working directory parents, this will cause these
2924 files to appear modified. This can be helpful to "back out" some or all
2925 of an earlier change. See hg backout for a related method.
2926 Modified files are saved with a .orig suffix before reverting. To dis‐
2928 able these backups, use --no-backup. It is possible to store the backup
2929 files in a custom directory relative to the root of the repository by
2930 setting the ui.origbackuppath configuration option.
2931 See hg help dates for a list of formats valid for -d/--date.
2933 See hg help backout for a way to reverse the effect of an earlier
2935 changeset.
2936 Returns 0 on success.
2938 Options:
2940 -a, --all
2942 revert all changes when no arguments given
2943 -d,--date <DATE>
2945 tipmost revision matching date
2946 -r,--rev <REV>
2948 revert to the specified revision
2949 -C, --no-backup
2951 do not save backup copies of files
2952 -i, --interactive
2954 interactively select the changes
2955 -I,--include <PATTERN[+]>
2957 include names matching the given patterns
2958 -X,--exclude <PATTERN[+]>
2960 exclude names matching the given patterns
2961 -n, --dry-run
2963 do not perform actions, just print output
2964 [+] marked option can be specified multiple times
2966 root
2968 print the root (top) of the current working directory:
2969 hg root
2971 Print the root directory of the current repository.
2973 Template:
2975 The following keywords are supported in addition to the common template
2977 keywords and functions. See also hg help templates.
2978 hgpath String. Path to the .hg directory.
2980 storepath
2982 String. Path to the directory holding versioned data.
2983 Returns 0 on success.
2985 Options:
2987 -T,--template <TEMPLATE>
2989 display with template
2990 shelve
2992 save and set aside changes from the working directory:
2993 hg shelve [OPTION]... [FILE]...
2995 Shelving takes files that "hg status" reports as not clean, saves the
2997 modifications to a bundle (a shelved change), and reverts the files so
2998 that their state in the working directory becomes clean.
2999 To restore these changes to the working directory, using "hg unshelve";
3001 this will work even if you switch to a different commit.
3002 When no files are specified, "hg shelve" saves all not-clean files. If
3004 specific files or directories are named, only changes to those files
3005 are shelved.
3006 In bare shelve (when no files are specified, without interactive, in‐
3008 clude and exclude option), shelving remembers information if the work‐
3009 ing directory was on newly created branch, in other words working di‐
3010 rectory was on different branch than its first parent. In this situa‐
3011 tion unshelving restores branch information to the working directory.
3012 Each shelved change has a name that makes it easier to find later. The
3014 name of a shelved change defaults to being based on the active book‐
3015 mark, or if there is no active bookmark, the current named branch. To
3016 specify a different name, use --name.
3017 To see a list of existing shelved changes, use the --list option. For
3019 each shelved change, this will print its name, age, and description;
3020 use --patch or --stat for more details.
3021 To delete specific shelved changes, use --delete. To delete all shelved
3023 changes, use --cleanup.
3024 Options:
3026 -A, --addremove
3028 mark new/missing files as added/removed before shelving
3029 -u, --unknown
3031 store unknown files in the shelve
3032 --cleanup
3034 delete all shelved changes
3035 --date <DATE>
3037 shelve with the specified commit date
3038 -d, --delete
3040 delete the named shelved change(s)
3041 -e, --edit
3043 invoke editor on commit messages
3044 -k, --keep
3046 shelve, but keep changes in the working directory
3047 -l, --list
3049 list current shelves
3050 -m,--message <TEXT>
3052 use text as shelve message
3053 -n,--name <NAME>
3055 use the given name for the shelved commit
3056 -p, --patch
3058 output patches for changes (provide the names of the shelved
3059 changes as positional arguments)
3060 -i, --interactive
3062 interactive mode
3063 --stat output diffstat-style summary of changes (provide the names of
3065 the shelved changes as positional arguments)
3066 -I,--include <PATTERN[+]>
3068 include names matching the given patterns
3069 -X,--exclude <PATTERN[+]>
3071 exclude names matching the given patterns
3072 [+] marked option can be specified multiple times
3074 status
3076 show changed files in the working directory:
3077 hg status [OPTION]... [FILE]...
3079 Show status of files in the repository. If names are given, only files
3081 that match are shown. Files that are clean or ignored or the source of
3082 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3083 -C/--copies or -A/--all are given. Unless options described with "show
3084 only ..." are given, the options -mardu are used.
3085 Option -q/--quiet hides untracked (unknown and ignored) files unless
3087 explicitly requested with -u/--unknown or -i/--ignored.
3088 Note hg status may appear to disagree with diff if permissions have
3090 changed or a merge has occurred. The standard diff format does
3091 not report permission changes and diff only reports changes rel‐
3092 ative to one merge parent.
3093 If one revision is given, it is used as the base revision. If two re‐
3095 visions are given, the differences between them are shown. The --change
3096 option can also be used as a shortcut to list the changed files of a
3097 revision from its first parent.
3098 The codes used to show the status of files are:
3100 M = modified
3102 A = added
3103 R = removed
3104 C = clean
3105 ! = missing (deleted by non-hg command, but still tracked)
3106 ? = not tracked
3107 I = ignored
3108 = origin of the previous file (with --copies)
3109 The -t/--terse option abbreviates the output by showing only the direc‐
3111 tory name if all the files in it share the same status. The option
3112 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3113 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3114 'unknown', 'i' for 'ignored' and 'c' for clean.
3115 It abbreviates only those statuses which are passed. Note that clean
3117 and ignored files are not displayed with '--terse ic' unless the
3118 -c/--clean and -i/--ignored options are also used.
3119 The -v/--verbose option shows information when the repository is in an
3121 unfinished merge, shelve, rebase state etc. You can have this behavior
3122 turned on by default by enabling the commands.status.verbose option.
3123 You can skip displaying some of these states by setting commands.sta‐
3125 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3126 'merge', 'rebase', or 'unshelve'.
3127 Template:
3129 The following keywords are supported in addition to the common template
3131 keywords and functions. See also hg help templates.
3132 path String. Repository-absolute path of the file.
3134 source String. Repository-absolute path of the file originated from.
3136 Available if --copies is specified.
3137 status String. Character denoting file's status.
3139 Examples:
3141 • show changes in the working directory relative to a changeset:
3143 hg status --rev 9353
3145 • show changes in the working directory relative to the current direc‐
3147 tory (see hg help patterns for more information):
3148 hg status re:
3150 • show all changes including copies in an existing changeset:
3152 hg status --copies --change 9353
3154 • get a NUL separated list of added files, suitable for xargs:
3156 hg status -an0
3158 • show more information about the repository status, abbreviating
3160 added, removed, modified, deleted, and untracked paths:
3161 hg status -v -t mardu
3163 Returns 0 on success.
3165 Options:
3167 -A, --all
3169 show status of all files
3170 -m, --modified
3172 show only modified files
3173 -a, --added
3175 show only added files
3176 -r, --removed
3178 show only removed files
3179 -d, --deleted
3181 show only missing files
3182 -c, --clean
3184 show only files without changes
3185 -u, --unknown
3187 show only unknown (not tracked) files
3188 -i, --ignored
3190 show only ignored files
3191 -n, --no-status
3193 hide status prefix
3194 -t,--terse <VALUE>
3196 show the terse output (EXPERIMENTAL) (default: nothing)
3197 -C, --copies
3199 show source of copied files (DEFAULT: ui.statuscopies)
3200 -0, --print0
3202 end filenames with NUL, for use with xargs
3203 --rev <REV[+]>
3205 show difference from revision
3206 --change <REV>
3208 list the changed files of a revision
3209 -I,--include <PATTERN[+]>
3211 include names matching the given patterns
3212 -X,--exclude <PATTERN[+]>
3214 exclude names matching the given patterns
3215 -S, --subrepos
3217 recurse into subrepositories
3218 -T,--template <TEMPLATE>
3220 display with template
3221 [+] marked option can be specified multiple times
3223 aliases: st
3225 summary
3227 summarize working directory state:
3228 hg summary [--remote]
3230 This generates a brief summary of the working directory state, includ‐
3232 ing parents, branch, commit status, phase and available updates.
3233 With the --remote option, this will check the default paths for incom‐
3235 ing and outgoing changes. This can be time-consuming.
3236 Returns 0 on success.
3238 Options:
3240 --remote
3242 check for push and pull
3243 aliases: sum
3245 unshelve
3247 restore a shelved change to the working directory:
3248 hg unshelve [OPTION]... [[-n] SHELVED]
3250 This command accepts an optional name of a shelved change to restore.
3252 If none is given, the most recent shelved change is used.
3253 If a shelved change is applied successfully, the bundle that contains
3255 the shelved changes is moved to a backup location (.hg/shelve-backup).
3256 Since you can restore a shelved change on top of an arbitrary commit,
3258 it is possible that unshelving will result in a conflict between your
3259 changes and the commits you are unshelving onto. If this occurs, you
3260 must resolve the conflict, then use --continue to complete the unshelve
3261 operation. (The bundle will not be moved until you successfully com‐
3262 plete the unshelve.)
3263 (Alternatively, you can use --abort to abandon an unshelve that causes
3265 a conflict. This reverts the unshelved changes, and leaves the bundle
3266 in place.)
3267 If bare shelved change (without interactive, include and exclude op‐
3269 tion) was done on newly created branch it would restore branch informa‐
3270 tion to the working directory.
3271 After a successful unshelve, the shelved changes are stored in a backup
3273 directory. Only the N most recent backups are kept. N defaults to 10
3274 but can be overridden using the shelve.maxbackups configuration option.
3275 Timestamp in seconds is used to decide order of backups. More than
3277 maxbackups backups are kept, if same timestamp prevents from deciding
3278 exact order of them, for safety.
3279 Selected changes can be unshelved with --interactive flag. The working
3281 directory is updated with the selected changes, and only the unselected
3282 changes remain shelved. Note: The whole shelve is applied to working
3283 directory first before running interactively. So, this will bring up
3284 all the conflicts between working directory and the shelve, irrespec‐
3285 tive of which changes will be unshelved.
3286 Options:
3288 -a, --abort
3290 abort an incomplete unshelve operation
3291 -c, --continue
3293 continue an incomplete unshelve operation
3294 -i, --interactive
3296 use interactive mode (EXPERIMENTAL)
3297 -k, --keep
3299 keep shelve after unshelving
3300 -n,--name <NAME>
3302 restore shelved change with given name
3303 -t,--tool <VALUE>
3305 specify merge tool
3306 --date <DATE>
3308 set date for temporary commits (DEPRECATED)
3309 update
3311 update working directory (or switch revisions):
3312 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3314 Update the repository's working directory to the specified changeset.
3316 If no changeset is specified, update to the tip of the current named
3317 branch and move the active bookmark (see hg help bookmarks).
3318 Update sets the working directory's parent revision to the specified
3320 changeset (see hg help parents).
3321 If the changeset is not a descendant or ancestor of the working direc‐
3323 tory's parent and there are uncommitted changes, the update is aborted.
3324 With the -c/--check option, the working directory is checked for uncom‐
3325 mitted changes; if none are found, the working directory is updated to
3326 the specified changeset.
3327 The -C/--clean, -c/--check, and -m/--merge options control what happens
3329 if the working directory contains uncommitted changes. At most of one
3330 of them can be specified.
3331 1. If no option is specified, and if the requested changeset is an an‐
3333 cestor or descendant of the working directory's parent, the uncom‐
3334 mitted changes are merged into the requested changeset and the
3335 merged result is left uncommitted. If the requested changeset is not
3336 an ancestor or descendant (that is, it is on another branch), the
3337 update is aborted and the uncommitted changes are preserved.
3338 2. With the -m/--merge option, the update is allowed even if the re‐
3340 quested changeset is not an ancestor or descendant of the working
3341 directory's parent.
3342 3. With the -c/--check option, the update is aborted and the uncommit‐
3344 ted changes are preserved.
3345 4. With the -C/--clean option, uncommitted changes are discarded and
3347 the working directory is updated to the requested changeset.
3348 To cancel an uncommitted merge (and lose your changes), use hg merge
3350 --abort.
3351 Use null as the changeset to remove the working directory (like hg
3353 clone -U).
3354 If you want to revert just one file to an older revision, use hg revert
3356 [-r REV] NAME.
3357 See hg help dates for a list of formats valid for -d/--date.
3359 Returns 0 on success, 1 if there are unresolved files.
3361 Options:
3363 -C, --clean
3365 discard uncommitted changes (no backup)
3366 -c, --check
3368 require clean working directory
3369 -m, --merge
3371 merge uncommitted changes
3372 -d,--date <DATE>
3374 tipmost revision matching date
3375 -r,--rev <REV>
3377 revision
3378 -t,--tool <TOOL>
3380 specify merge tool
3381 aliases: up checkout co
3383 Change import/export
3385 archive
3386 create an unversioned archive of a repository revision:
3387 hg archive [OPTION]... DEST
3389 By default, the revision used is the parent of the working directory;
3391 use -r/--rev to specify a different revision.
3392 The archive type is automatically detected based on file extension (to
3394 override, use -t/--type).
3395 Examples:
3397 • create a zip file containing the 1.0 release:
3399 hg archive -r 1.0 project-1.0.zip
3401 • create a tarball excluding .hg files:
3403 hg archive project.tar.gz -X ".hg*"
3405 Valid types are:
3407 files
3409 a directory full of files (default)
3411 tar
3413 tar archive, uncompressed
3415 tbz2
3417 tar archive, compressed using bzip2
3419 tgz
3421 tar archive, compressed using gzip
3423 txz
3425 tar archive, compressed using lzma (only in Python 3)
3427 uzip
3429 zip archive, uncompressed
3431 zip
3433 zip archive, compressed using deflate
3435 The exact name of the destination archive or directory is given using a
3437 format string; see hg help export for details.
3438 Each member added to an archive file has a directory prefix prepended.
3440 Use -p/--prefix to specify a format string for the prefix. The default
3441 is the basename of the archive, with suffixes removed.
3442 Returns 0 on success.
3444 Options:
3446 --no-decode
3448 do not pass files through decoders
3449 -p,--prefix <PREFIX>
3451 directory prefix for files in archive
3452 -r,--rev <REV>
3454 revision to distribute
3455 -t,--type <TYPE>
3457 type of distribution to create
3458 -S, --subrepos
3460 recurse into subrepositories
3461 -I,--include <PATTERN[+]>
3463 include names matching the given patterns
3464 -X,--exclude <PATTERN[+]>
3466 exclude names matching the given patterns
3467 [+] marked option can be specified multiple times
3469 bundle
3471 create a bundle file:
3472 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]
3474 Generate a bundle file containing data to be transferred to another
3476 repository.
3477 To create a bundle containing all changesets, use -a/--all (or --base
3479 null). Otherwise, hg assumes the destination will have all the nodes
3480 you specify with --base parameters. Otherwise, hg will assume the
3481 repository has all the nodes in destination, or default-push/default if
3482 no destination is specified, where destination is the repository you
3483 provide through DEST option.
3484 You can change bundle format with the -t/--type option. See hg help
3486 bundlespec for documentation on this format. By default, the most ap‐
3487 propriate format is used and compression defaults to bzip2.
3488 The bundle file can then be transferred using conventional means and
3490 applied to another repository with the unbundle or pull command. This
3491 is useful when direct push and pull are not available or when exporting
3492 an entire repository is undesirable.
3493 Applying bundles preserves all changeset contents including permis‐
3495 sions, copy/rename information, and revision history.
3496 Returns 0 on success, 1 if no changes found.
3498 Options:
3500 -f, --force
3502 run even when the destination is unrelated
3503 -r,--rev <REV[+]>
3505 a changeset intended to be added to the destination
3506 -b,--branch <BRANCH[+]>
3508 a specific branch you would like to bundle
3509 --base <REV[+]>
3511 a base changeset assumed to be available at the destination
3512 -a, --all
3514 bundle all changesets in the repository
3515 -t,--type <TYPE>
3517 bundle compression type to use (default: bzip2)
3518 -e,--ssh <CMD>
3520 specify ssh command to use
3521 --remotecmd <CMD>
3523 specify hg command to run on the remote side
3524 --insecure
3526 do not verify server certificate (ignoring web.cacerts config)
3527 [+] marked option can be specified multiple times
3529 export
3531 dump the header and diffs for one or more changesets:
3532 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
3534 Print the changeset header and diffs for one or more revisions. If no
3536 revision is given, the parent of the working directory is used.
3537 The information shown in the changeset header is: author, date, branch
3539 name (if non-default), changeset hash, parent(s) and commit comment.
3540 Note hg export may generate unexpected diff output for merge change‐
3542 sets, as it will compare the merge changeset against its first
3543 parent only.
3544 Output may be to a file, in which case the name of the file is given
3546 using a template string. See hg help templates. In addition to the com‐
3547 mon template keywords, the following formatting rules are supported:
3548 %%
3550 literal "%" character
3552 %H
3554 changeset hash (40 hexadecimal digits)
3556 %N
3558 number of patches being generated
3560 %R
3562 changeset revision number
3564 %b
3566 basename of the exporting repository
3568 %h
3570 short-form changeset hash (12 hexadecimal digits)
3572 %m
3574 first line of the commit message (only alphanumeric characters)
3576 %n
3578 zero-padded sequence number, starting at 1
3580 %r
3582 zero-padded changeset revision number
3584 \
3586 literal "" character
3588 Without the -a/--text option, export will avoid generating diffs of
3590 files it detects as binary. With -a, export will generate a diff any‐
3591 way, probably with undesirable results.
3592 With -B/--bookmark changesets reachable by the given bookmark are se‐
3594 lected.
3595 Use the -g/--git option to generate diffs in the git extended diff for‐
3597 mat. See hg help diffs for more information.
3598 With the --switch-parent option, the diff will be against the second
3600 parent. It can be useful to review a merge.
3601 Template:
3603 The following keywords are supported in addition to the common template
3605 keywords and functions. See also hg help templates.
3606 diff String. Diff content.
3608 parents
3610 List of strings. Parent nodes of the changeset.
3611 Examples:
3613 • use export and import to transplant a bugfix to the current branch:
3615 hg export -r 9353 | hg import -
3617 • export all the changesets between two revisions to a file with rename
3619 information:
3620 hg export --git -r 123:150 > changes.txt
3622 • split outgoing changes into a series of patches with descriptive
3624 names:
3625 hg export -r "outgoing()" -o "%n-%m.patch"
3627 Returns 0 on success.
3629 Options:
3631 -B,--bookmark <BOOKMARK>
3633 export changes only reachable by given bookmark
3634 -o,--output <FORMAT>
3636 print output to file with formatted name
3637 --switch-parent
3639 diff against the second parent
3640 -r,--rev <REV[+]>
3642 revisions to export
3643 -a, --text
3645 treat all files as text
3646 -g, --git
3648 use git extended diff format (DEFAULT: diff.git)
3649 --binary
3651 generate binary diffs in git mode (default)
3652 --nodates
3654 omit dates from diff headers
3655 -T,--template <TEMPLATE>
3657 display with template
3658 [+] marked option can be specified multiple times
3660 import
3662 import an ordered set of patches:
3663 hg import [OPTION]... PATCH...
3665 Import a list of patches and commit them individually (unless --no-com‐
3667 mit is specified).
3668 To read a patch from standard input (stdin), use "-" as the patch name.
3670 If a URL is specified, the patch will be downloaded from there.
3671 Import first applies changes to the working directory (unless --bypass
3673 is specified), import will abort if there are outstanding changes.
3674 Use --bypass to apply and commit patches directly to the repository,
3676 without affecting the working directory. Without --exact, patches will
3677 be applied on top of the working directory parent revision.
3678 You can import a patch straight from a mail message. Even patches as
3680 attachments work (to use the body part, it must have type text/plain or
3681 text/x-patch). From and Subject headers of email message are used as
3682 default committer and commit message. All text/plain body parts before
3683 first diff are added to the commit message.
3684 If the imported patch was generated by hg export, user and description
3686 from patch override values from message headers and body. Values given
3687 on command line with -m/--message and -u/--user override these.
3688 If --exact is specified, import will set the working directory to the
3690 parent of each patch before applying it, and will abort if the result‐
3691 ing changeset has a different ID than the one recorded in the patch.
3692 This will guard against various ways that portable patch formats and
3693 mail systems might fail to transfer Mercurial data or metadata. See hg
3694 bundle for lossless transmission.
3695 Use --partial to ensure a changeset will be created from the patch even
3697 if some hunks fail to apply. Hunks that fail to apply will be written
3698 to a <target-file>.rej file. Conflicts can then be resolved by hand be‐
3699 fore hg commit --amend is run to update the created changeset. This
3700 flag exists to let people import patches that partially apply without
3701 losing the associated metadata (author, date, description, ...).
3702 Note When no hunks apply cleanly, hg import --partial will create an
3704 empty changeset, importing only the patch metadata.
3705 With -s/--similarity, hg will attempt to discover renames and copies in
3707 the patch in the same way as hg addremove.
3708 It is possible to use external patch programs to perform the patch by
3710 setting the ui.patch configuration option. For the default internal
3711 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
3712 fig for more information about configuration files and how to use these
3713 options.
3714 See hg help dates for a list of formats valid for -d/--date.
3716 Examples:
3718 • import a traditional patch from a website and detect renames:
3720 hg import -s 80 http://example.com/bugfix.patch
3722 • import a changeset from an hgweb server:
3724 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
3726 • import all the patches in an Unix-style mbox:
3728 hg import incoming-patches.mbox
3730 • import patches from stdin:
3732 hg import -
3734 • attempt to exactly restore an exported changeset (not always possi‐
3736 ble):
3737 hg import --exact proposed-fix.patch
3739 • use an external tool to apply a patch which is too fuzzy for the de‐
3741 fault internal tool.
3742 hg import --config ui.patch="patch --merge" fuzzy.patch
3744 • change the default fuzzing from 2 to a less strict 7
3746 hg import --config ui.fuzz=7 fuzz.patch
3748 Returns 0 on success, 1 on partial success (see --partial).
3750 Options:
3752 -p,--strip <NUM>
3754 directory strip option for patch. This has the same meaning as
3755 the corresponding patch option (default: 1)
3756 -b,--base <PATH>
3758 base path (DEPRECATED)
3759 --secret
3761 use the secret phase for committing
3762 -e, --edit
3764 invoke editor on commit messages
3765 -f, --force
3767 skip check for outstanding uncommitted changes (DEPRECATED)
3768 --no-commit
3770 don't commit, just update the working directory
3771 --bypass
3773 apply patch without touching the working directory
3774 --partial
3776 commit even if some hunks fail
3777 --exact
3779 abort if patch would apply lossily
3780 --prefix <DIR>
3782 apply patch to subdirectory
3783 --import-branch
3785 use any branch information in patch (implied by --exact)
3786 -m,--message <TEXT>
3788 use text as commit message
3789 -l,--logfile <FILE>
3791 read commit message from file
3792 -d,--date <DATE>
3794 record the specified date as commit date
3795 -u,--user <USER>
3797 record the specified user as committer
3798 -s,--similarity <SIMILARITY>
3800 guess renamed files by similarity (0<=s<=100)
3801 aliases: patch
3803 unbundle
3805 apply one or more bundle files:
3806 hg unbundle [-u] FILE...
3808 Apply one or more bundle files generated by hg bundle.
3810 Returns 0 on success, 1 if an update has unresolved files.
3812 Options:
3814 -u, --update
3816 update to new branch head if changesets were unbundled
3817 Repository maintenance
3819 manifest
3820 output the current or given revision of the project manifest:
3821 hg manifest [-r REV]
3823 Print a list of version controlled files for the given revision. If no
3825 revision is given, the first parent of the working directory is used,
3826 or the null revision if no revision is checked out.
3827 With -v, print file permissions, symlink and executable bits. With
3829 --debug, print file revision hashes.
3830 If option --all is specified, the list of all files from all revisions
3832 is printed. This includes deleted and renamed files.
3833 Returns 0 on success.
3835 Options:
3837 -r,--rev <REV>
3839 revision to display
3840 --all list files from all revisions
3842 -T,--template <TEMPLATE>
3844 display with template
3845 recover
3847 roll back an interrupted transaction:
3848 hg recover
3850 Recover from an interrupted commit or pull.
3852 This command tries to fix the repository status after an interrupted
3854 operation. It should only be necessary when Mercurial suggests it.
3855 Returns 0 if successful, 1 if nothing to recover or verify fails.
3857 Options:
3859 --verify
3861 run hg verify after successful recover
3862 rollback
3864 roll back the last transaction (DANGEROUS) (DEPRECATED):
3865 hg rollback
3867 Please use hg commit --amend instead of rollback to correct mistakes in
3869 the last commit.
3870 This command should be used with care. There is only one level of roll‐
3872 back, and there is no way to undo a rollback. It will also restore the
3873 dirstate at the time of the last transaction, losing any dirstate
3874 changes since that time. This command does not alter the working direc‐
3875 tory.
3876 Transactions are used to encapsulate the effects of all commands that
3878 create new changesets or propagate existing changesets into a reposi‐
3879 tory.
3880 For example, the following commands are transactional, and their ef‐
3882 fects can be rolled back:
3883 • commit
3885 • import
3887 • pull
3889 • push (with this repository as the destination)
3891 • unbundle
3893 To avoid permanent data loss, rollback will refuse to rollback a commit
3895 transaction if it isn't checked out. Use --force to override this pro‐
3896 tection.
3897 The rollback command can be entirely disabled by setting the ui.roll‐
3899 back configuration setting to false. If you're here because you want to
3900 use rollback and it's disabled, you can re-enable the command by set‐
3901 ting ui.rollback to true.
3902 This command is not intended for use on public repositories. Once
3904 changes are visible for pull by other users, rolling a transaction back
3905 locally is ineffective (someone else may already have pulled the
3906 changes). Furthermore, a race is possible with readers of the reposi‐
3907 tory; for example an in-progress pull from the repository may fail if a
3908 rollback is performed.
3909 Returns 0 on success, 1 if no rollback data is available.
3911 Options:
3913 -n, --dry-run
3915 do not perform actions, just print output
3916 -f, --force
3918 ignore safety measures
3919 verify
3921 verify the integrity of the repository:
3922 hg verify
3924 Verify the integrity of the current repository.
3926 This will perform an extensive check of the repository's integrity,
3928 validating the hashes and checksums of each entry in the changelog,
3929 manifest, and tracked files, as well as the integrity of their
3930 crosslinks and indices.
3931 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
3933 information about recovery from corruption of the repository.
3934 Returns 0 on success, 1 if errors are encountered.
3936 Options:
3938 --full perform more checks (EXPERIMENTAL)
3940 Help
3942 config
3943 show combined config settings from all hgrc files:
3944 hg config [-u] [NAME]...
3946 With no arguments, print names and values of all config items.
3948 With one argument of the form section.name, print just the value of
3950 that config item.
3951 With multiple arguments, print names and values of all config items
3953 with matching section names or section.names.
3954 With --edit, start an editor on the user-level config file. With
3956 --global, edit the system-wide config file. With --local, edit the
3957 repository-level config file.
3958 With --debug, the source (filename and line number) is printed for each
3960 config item.
3961 See hg help config for more information about config files.
3963 --non-shared flag is used to edit .hg/hgrc-not-shared config file.
3965 This file is not shared across shares when in share-safe mode.
3966 Template:
3968 The following keywords are supported. See also hg help templates.
3970 name String. Config name.
3972 source String. Filename and line number where the item is defined.
3974 value String. Config value.
3976 The --shared flag can be used to edit the config file of shared source
3978 repository. It only works when you have shared using the experimental
3979 share safe feature.
3980 Returns 0 on success, 1 if NAME does not exist.
3982 Options:
3984 -u, --untrusted
3986 show untrusted configuration options
3987 -e, --edit
3989 edit user config
3990 -l, --local
3992 edit repository config
3993 --shared
3995 edit shared source repository config (EXPERIMENTAL)
3996 --non-shared
3998 edit non shared config (EXPERIMENTAL)
3999 -g, --global
4001 edit global config
4002 -T,--template <TEMPLATE>
4004 display with template
4005 aliases: showconfig debugconfig
4007 help
4009 show help for a given topic or a help overview:
4010 hg help [-eck] [-s PLATFORM] [TOPIC]
4012 With no arguments, print a list of commands with short help messages.
4014 Given a topic, extension, or command name, print help for that topic.
4016 Returns 0 if successful.
4018 Options:
4020 -e, --extension
4022 show only help for extensions
4023 -c, --command
4025 show only help for commands
4026 -k, --keyword
4028 show topics matching keyword
4029 -s,--system <PLATFORM[+]>
4031 show help for specific platform(s)
4032 [+] marked option can be specified multiple times
4034 version
4036 output version and copyright information:
4037 hg version
4039 Template:
4041 The following keywords are supported. See also hg help templates.
4043 extensions
4045 List of extensions.
4046 ver String. Version number.
4048 And each entry of {extensions} provides the following sub-keywords in
4050 addition to {ver}.
4051 bundled
4053 Boolean. True if included in the release.
4054 name String. Extension name.
4056 Options:
4058 -T,--template <TEMPLATE>
4060 display with template
4061 Uncategorized commands
4064 Mercurial supports generating standalone "bundle" files that hold
4065 repository data. These "bundles" are typically saved locally and used
4066 later or exchanged between different repositories, possibly on differ‐
4067 ent machines. Example commands using bundles are hg bundle and hg un‐
4068 bundle.
4069 Generation of bundle files is controlled by a "bundle specification"
4071 ("bundlespec") string. This string tells the bundle generation process
4072 how to create the bundle.
4073 A "bundlespec" string is composed of the following elements:
4075 type A string denoting the bundle format to use.
4077 compression
4079 Denotes the compression engine to use compressing the raw bundle
4080 data.
4081 parameters
4083 Arbitrary key-value parameters to further control bundle genera‐
4084 tion.
4085 A "bundlespec" string has the following formats:
4087 <type> The literal bundle format string is used.
4089 <compression>-<type>
4091 The compression engine and format are delimited by a hyphen (-).
4092 Optional parameters follow the <type>. Parameters are URI escaped
4094 key=value pairs. Each pair is delimited by a semicolon (;). The first
4095 parameter begins after a ; immediately following the <type> value.
4096 Available Types
4098 The following bundle <type> strings are available:
4099 v1 Produces a legacy "changegroup" version 1 bundle.
4101 This format is compatible with nearly all Mercurial clients be‐
4103 cause it is the oldest. However, it has some limitations, which
4104 is why it is no longer the default for new repositories.
4105 v1 bundles can be used with modern repositories using the "gen‐
4107 eraldelta" storage format. However, it may take longer to pro‐
4108 duce the bundle and the resulting bundle may be significantly
4109 larger than a v2 bundle.
4110 v1 bundles can only use the gzip, bzip2, and none compression
4112 formats.
4113 v2 Produces a version 2 bundle.
4115 Version 2 bundles are an extensible format that can store addi‐
4117 tional repository data (such as bookmarks and phases informa‐
4118 tion) and they can store data more efficiently, resulting in
4119 smaller bundles.
4120 Version 2 bundles can also use modern compression engines, such
4122 as zstd, making them faster to compress and often smaller.
4123 Available Compression Engines
4125 The following bundle <compression> engines can be used:
4126 bzip2
4128 An algorithm that produces smaller bundles than gzip.
4130 All Mercurial clients should support this format.
4132 This engine will likely produce smaller bundles than gzip but
4134 will be significantly slower, both during compression and decom‐
4135 pression.
4136 If available, the zstd engine can yield similar or better com‐
4138 pression at much higher speeds.
4139 gzip
4141 zlib compression using the DEFLATE algorithm.
4143 All Mercurial clients should support this format. The compres‐
4145 sion algorithm strikes a reasonable balance between compression
4146 ratio and size.
4147 none
4149 No compression is performed.
4151 Use this compression engine to explicitly disable compression.
4153 Examples
4155 v2
4156 Produce a v2 bundle using default options, including compres‐
4158 sion.
4159 none-v1
4161 Produce a v1 bundle with no compression.
4163 zstd-v2
4165 Produce a v2 bundle with zstandard compression using default
4167 settings.
4168 zstd-v1
4170 This errors because zstd is not supported for v1 types.
4172
4174 Mercurial colorizes output from several commands.
4175 For example, the diff command shows additions in green and deletions in
4177 red, while the status command shows modified files in magenta. Many
4178 other commands have analogous colors. It is possible to customize these
4179 colors.
4180 To enable color (default) whenever possible use:
4182 [ui]
4184 color = yes
4185 To disable color use:
4187 [ui]
4189 color = no
4190 See hg help config.ui.color for details.
4192 The default pager on Windows does not support color, so enabling the
4194 pager will effectively disable color. See hg help config.ui.paginate
4195 to disable the pager. Alternately, MSYS and Cygwin shells provide less
4196 as a pager, which can be configured to support ANSI color mode. Win‐
4197 dows 10 natively supports ANSI color mode.
4198 Mode
4200 Mercurial can use various systems to display color. The supported modes
4201 are ansi, win32, and terminfo. See hg help config.color for details
4202 about how to control the mode.
4203 Effects
4205 Other effects in addition to color, like bold and underlined text, are
4206 also available. By default, the terminfo database is used to find the
4207 terminal codes used to change color and effect. If terminfo is not
4208 available, then effects are rendered with the ECMA-48 SGR control func‐
4209 tion (aka ANSI escape codes).
4210 The available effects in terminfo mode are 'blink', 'bold', 'dim', 'in‐
4212 verse', 'invisible', 'italic', 'standout', and 'underline'; in ECMA-48
4213 mode, the options are 'bold', 'inverse', 'italic', and 'underline'.
4214 How each is rendered depends on the terminal emulator. Some may not be
4215 available for a given terminal type, and will be silently ignored.
4216 If the terminfo entry for your terminal is missing codes for an effect
4218 or has the wrong codes, you can add or override those codes in your
4219 configuration:
4220 [color]
4222 terminfo.dim = \E[2m
4223 where 'E' is substituted with an escape character.
4225 Labels
4227 Text receives color effects depending on the labels that it has. Many
4228 default Mercurial commands emit labelled text. You can also define your
4229 own labels in templates using the label function, see hg help templates
4230 . A single portion of text may have more than one label. In that case,
4231 effects given to the last label will override any other effects. This
4232 includes the special "none" effect, which nullifies other effects.
4233 Labels are normally invisible. In order to see these labels and their
4235 position in the text, use the global --color=debug option. The same an‐
4236 chor text may be associated to multiple labels, e.g.
4237 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
4239 The following are the default effects for some default labels. Default
4241 effects may be overridden from your configuration file:
4242 [color]
4244 status.modified = blue bold underline red_background
4245 status.added = green bold
4246 status.removed = red bold blue_background
4247 status.deleted = cyan bold underline
4248 status.unknown = magenta bold underline
4249 status.ignored = black bold
4250 # 'none' turns off all effects
4252 status.clean = none
4253 status.copied = none
4254 qseries.applied = blue bold underline
4256 qseries.unapplied = black bold
4257 qseries.missing = red bold
4258 diff.diffline = bold
4260 diff.extended = cyan bold
4261 diff.file_a = red bold
4262 diff.file_b = green bold
4263 diff.hunk = magenta
4264 diff.deleted = red
4265 diff.inserted = green
4266 diff.changed = white
4267 diff.tab =
4268 diff.trailingwhitespace = bold red_background
4269 # Blank so it inherits the style of the surrounding label
4271 changeset.public =
4272 changeset.draft =
4273 changeset.secret =
4274 resolve.unresolved = red bold
4276 resolve.resolved = green bold
4277 bookmarks.active = green
4279 branches.active = none
4281 branches.closed = black bold
4282 branches.current = green
4283 branches.inactive = none
4284 tags.normal = green
4286 tags.local = black bold
4287 rebase.rebased = blue
4289 rebase.remaining = red bold
4290 shelve.age = cyan
4292 shelve.newest = green bold
4293 shelve.name = blue bold
4294 histedit.remaining = red bold
4296 Custom colors
4298 Because there are only eight standard colors, Mercurial allows you to
4299 define color names for other color slots which might be available for
4300 your terminal type, assuming terminfo mode. For instance:
4301 color.brightblue = 12
4303 color.pink = 207
4304 color.orange = 202
4305 to set 'brightblue' to color slot 12 (useful for 16 color terminals
4307 that have brighter colors defined in the upper eight) and, 'pink' and
4308 'orange' to colors in 256-color xterm's default color cube. These de‐
4309 fined colors may then be used as any of the pre-defined eight, includ‐
4310 ing appending '_background' to set the background to that color.
4311
4313 Some commands allow the user to specify a date, e.g.:
4314 • backout, commit, import, tag: Specify the commit date.
4316 • log, revert, update: Select revision(s) by date.
4318 Many date formats are valid. Here are some examples:
4320 • Wed Dec 6 13:18:29 2006 (local timezone assumed)
4322 • Dec 6 13:18 -0600 (year assumed, time offset provided)
4324 • Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
4326 • Dec 6 (midnight)
4328 • 13:18 (today assumed)
4330 • 3:39 (3:39AM assumed)
4332 • 3:39pm (15:39)
4334 • 2006-12-06 13:18:29 (ISO 8601 format)
4336 • 2006-12-6 13:18
4338 • 2006-12-6
4340 • 12-6
4342 • 12/6
4344 • 12/6/6 (Dec 6 2006)
4346 • today (midnight)
4348 • yesterday (midnight)
4350 • now - right now
4352 Lastly, there is Mercurial's internal format:
4354 • 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
4356 This is the internal representation format for dates. The first number
4358 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
4359 second is the offset of the local timezone, in seconds west of UTC
4360 (negative if the timezone is east of UTC).
4361 The log command also accepts date ranges:
4363 • <DATE - at or before a given date/time
4365 • >DATE - on or after a given date/time
4367 • DATE to DATE - a date range, inclusive
4369 • -DAYS - within a given number of days from today
4371
4373 Mercurial evolves over time, some features, options, commands may be
4374 replaced by better and more secure alternatives. This topic will help
4375 you migrating your existing usage and/or configuration to newer fea‐
4376 tures.
4377 Commands
4379 The following commands are still available but their use are not recom‐
4380 mended:
4381 locate
4383 This command has been replaced by hg files.
4385 parents
4387 This command can be replaced by hg summary or hg log with appropriate
4389 revsets. See hg help revsets for more information.
4390 tip
4392 The recommended alternative is hg heads.
4394 Options
4396 web.allowpull
4397 Renamed to allow-pull.
4399 web.allow_push
4401 Renamed to allow-push.
4403
4405 Mercurial's default format for showing changes between two versions of
4406 a file is compatible with the unified format of GNU diff, which can be
4407 used by GNU patch and many other standard tools.
4408 While this standard format is often enough, it does not encode the fol‐
4410 lowing information:
4411 • executable status and other permission bits
4413 • copy or rename information
4415 • changes in binary files
4417 • creation or deletion of empty files
4419 Mercurial also supports the extended diff format from the git VCS which
4421 addresses these limitations. The git diff format is not produced by de‐
4422 fault because a few widespread tools still do not understand this for‐
4423 mat.
4424 This means that when generating diffs from a Mercurial repository (e.g.
4426 with hg export), you should be careful about things like file copies
4427 and renames or other things mentioned above, because when applying a
4428 standard diff to a different repository, this extra information is
4429 lost. Mercurial's internal operations (like push and pull) are not af‐
4430 fected by this, because they use an internal binary format for communi‐
4431 cating changes.
4432 To make Mercurial produce the git extended diff format, use the --git
4434 option available for many commands, or set 'git = True' in the [diff]
4435 section of your configuration file. You do not need to set this option
4436 when importing diffs in this format or using them in the mq extension.
4437
4439 HG Path to the 'hg' executable, automatically passed when running
4440 hooks, extensions or external tools. If unset or empty, this is
4441 the hg executable's name if it's frozen, or an executable named
4442 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
4443 on Windows) is searched.
4444 HGEDITOR
4446 This is the name of the editor to run when committing. See EDI‐
4447 TOR.
4448 (deprecated, see hg help config.ui.editor)
4450 HGENCODING
4452 This overrides the default locale setting detected by Mercurial.
4453 This setting is used to convert data including usernames,
4454 changeset descriptions, tag names, and branches. This setting
4455 can be overridden with the --encoding command-line option.
4456 HGENCODINGMODE
4458 This sets Mercurial's behavior for handling unknown characters
4459 while transcoding user input. The default is "strict", which
4460 causes Mercurial to abort if it can't map a character. Other
4461 settings include "replace", which replaces unknown characters,
4462 and "ignore", which drops them. This setting can be overridden
4463 with the --encodingmode command-line option.
4464 HGENCODINGAMBIGUOUS
4466 This sets Mercurial's behavior for handling characters with "am‐
4467 biguous" widths like accented Latin characters with East Asian
4468 fonts. By default, Mercurial assumes ambiguous characters are
4469 narrow, set this variable to "wide" if such characters cause
4470 formatting problems.
4471 HGMERGE
4473 An executable to use for resolving merge conflicts. The program
4474 will be executed with three arguments: local file, remote file,
4475 ancestor file.
4476 (deprecated, see hg help config.ui.merge)
4478 HGRCPATH
4480 A list of files or directories to search for configuration
4481 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
4482 PATH is not set, platform default search path is used. If empty,
4483 only the .hg/hgrc from the current repository is read.
4484 For each element in HGRCPATH:
4486 • if it's a directory, all files ending with .rc are added
4488 • otherwise, the file itself will be added
4490 HGRCSKIPREPO
4492 When set, the .hg/hgrc from repositories are not read.
4493 HGPLAIN
4495 When set, this disables any configuration settings that might
4496 change Mercurial's default output. This includes encoding, de‐
4497 faults, verbose mode, debug mode, quiet mode, tracebacks, and
4498 localization. This can be useful when scripting against Mercu‐
4499 rial in the face of existing user configuration.
4500 In addition to the features disabled by HGPLAIN=, the following
4502 values can be specified to adjust behavior:
4503 +strictflags
4505 Restrict parsing of command line flags.
4507 Equivalent options set via command line flags or environment
4509 variables are not overridden.
4510 See hg help scripting for details.
4512 HGPLAINEXCEPT
4514 This is a comma-separated list of features to preserve when HG‐
4515 PLAIN is enabled. Currently the following values are supported:
4516 alias
4518 Don't remove aliases.
4520 color
4522 Don't disable colored output.
4524 i18n
4526 Preserve internationalization.
4528 revsetalias
4530 Don't remove revset aliases.
4532 templatealias
4534 Don't remove template aliases.
4536 progress
4538 Don't hide progress output.
4540 Setting HGPLAINEXCEPT to anything (even an empty string) will
4542 enable plain mode.
4543 HGUSER This is the string used as the author of a commit. If not set,
4545 available values will be considered in this order:
4546 • HGUSER (deprecated)
4548 • configuration files from the HGRCPATH
4550 • EMAIL
4552 • interactive prompt
4554 • LOGNAME (with @hostname appended)
4556 (deprecated, see hg help config.ui.username)
4558 EMAIL May be used as the author of a commit; see HGUSER.
4560 LOGNAME
4562 May be used as the author of a commit; see HGUSER.
4563 VISUAL This is the name of the editor to use when committing. See EDI‐
4565 TOR.
4566 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
4568 user to modify, for example when writing commit messages. The
4569 editor it uses is determined by looking at the environment vari‐
4570 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
4571 non-empty one is chosen. If all of them are empty, the editor
4572 defaults to 'vi'.
4573 PYTHONPATH
4575 This is used by Python to find imported modules and may need to
4576 be set appropriately if this Mercurial is not installed sys‐
4577 tem-wide.
4578
4580 Mercurial has the ability to add new features through the use of exten‐
4581 sions. Extensions may add new commands, add options to existing com‐
4582 mands, change the default behavior of commands, or implement hooks.
4583 To enable the "foo" extension, either shipped with Mercurial or in the
4585 Python search path, create an entry for it in your configuration file,
4586 like this:
4587 [extensions]
4589 foo =
4590 You may also specify the full path to an extension:
4592 [extensions]
4594 myfeature = ~/.hgext/myfeature.py
4595 See hg help config for more information on configuration files.
4597 Extensions are not loaded by default for a variety of reasons: they can
4599 increase startup overhead; they may be meant for advanced usage only;
4600 they may provide potentially dangerous abilities (such as letting you
4601 destroy or modify history); they might not be ready for prime time; or
4602 they may alter some usual behaviors of stock Mercurial. It is thus up
4603 to the user to activate extensions as needed.
4604 To explicitly disable an extension enabled in a configuration file of
4606 broader scope, prepend its path with !:
4607 [extensions]
4609 # disabling extension bar residing in /path/to/extension/bar.py
4610 bar = !/path/to/extension/bar.py
4611 # ditto, but no path was supplied for extension baz
4612 baz = !
4613 disabled extensions:
4615 acl hooks for controlling repository access
4617 blackbox
4619 log repository events to a blackbox for debugging
4620 bugzilla
4622 hooks for integrating with the Bugzilla bug tracker
4623 censor erase file content at a given revision
4625 churn command to display statistics about repository history
4627 clonebundles
4629 advertise pre-generated bundles to seed clones
4630 closehead
4632 close arbitrary heads without checking them out first
4633 convert
4635 import revisions from foreign VCS repositories into Mercurial
4636 eol automatically manage newlines in repository files
4638 extdiff
4640 command to allow external programs to compare revisions
4641 factotum
4643 http authentication with factotum
4644 fastexport
4646 export repositories as git fast-import stream
4647 githelp
4649 try mapping git commands to Mercurial commands
4650 gpg commands to sign and verify changesets
4652 hgk browse the repository in a graphical way
4654 highlight
4656 syntax highlighting for hgweb (requires Pygments)
4657 histedit
4659 interactive history editing
4660 keyword
4662 expand keywords in tracked files
4663 largefiles
4665 track large binary files
4666 mq manage a stack of patches
4668 notify hooks for sending email push notifications
4670 patchbomb
4672 command to send changesets as (a series of) patch emails
4673 purge command to delete untracked files from the working directory
4675 rebase command to move sets of revisions to a different ancestor
4677 relink recreates hardlinks between repository clones
4679 schemes
4681 extend schemes with shortcuts to repository swarms
4682 share share a common history between several working directories
4684 transplant
4686 command to transplant changesets from another branch
4687 win32mbcs
4689 allow the use of MBCS paths with problematic encodings
4690 zeroconf
4692 discover and advertise repositories on the local network
4693
4695 Mercurial supports a functional language for selecting a set of files.
4696 Like other file patterns, this pattern type is indicated by a prefix,
4698 'set:'. The language supports a number of predicates which are joined
4699 by infix operators. Parenthesis can be used for grouping.
4700 Identifiers such as filenames or patterns must be quoted with single or
4702 double quotes if they contain characters outside of
4703 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4704 predicates. This generally applies to file patterns other than globs
4705 and arguments for predicates. Pattern prefixes such as path: may be
4706 specified without quoting.
4707 Special characters can be used in quoted identifiers by escaping them,
4709 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4710 preted, strings can be prefixed with r, e.g. r'...'.
4711 See also hg help patterns.
4713 Operators
4715 There is a single prefix operator:
4716 not x
4718 Files not in x. Short form is ! x.
4720 These are the supported infix operators:
4722 x and y
4724 The intersection of files in x and y. Short form is x & y.
4726 x or y
4728 The union of files in x and y. There are two alternative short
4730 forms: x | y and x + y.
4731 x - y
4733 Files in x but not in y.
4735 Predicates
4737 The following predicates are supported:
4738 added()
4740 File that is added according to hg status.
4742 binary()
4744 File that appears to be binary (contains NUL bytes).
4746 clean()
4748 File that is clean according to hg status.
4750 copied()
4752 File that is recorded as being copied.
4754 deleted()
4756 Alias for missing().
4758 encoding(name)
4760 File can be successfully decoded with the given character encod‐
4762 ing. May not be useful for encodings other than ASCII and UTF-8.
4763 eol(style)
4765 File contains newlines of the given style (dos, unix, mac). Bi‐
4767 nary files are excluded, files with mixed line endings match
4768 multiple styles.
4769 exec()
4771 File that is marked as executable.
4773 grep(regex)
4775 File contains the given regular expression.
4777 hgignore()
4779 File that matches the active .hgignore pattern.
4781 ignored()
4783 File that is ignored according to hg status.
4785 missing()
4787 File that is missing according to hg status.
4789 modified()
4791 File that is modified according to hg status.
4793 portable()
4795 File that has a portable name. (This doesn't include filenames
4797 with case collisions.)
4798 removed()
4800 File that is removed according to hg status.
4802 resolved()
4804 File that is marked resolved according to hg resolve -l.
4806 revs(revs, pattern)
4808 Evaluate set in the specified revisions. If the revset match
4810 multiple revs, this will return file matching pattern in any of
4811 the revision.
4812 size(expression)
4814 File size matches the given expression. Examples:
4816 • size('1k') - files from 1024 to 2047 bytes
4818 • size('< 20k') - files less than 20480 bytes
4820 • size('>= .5MB') - files at least 524288 bytes
4822 • size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
4824 status(base, rev, pattern)
4826 Evaluate predicate using status change between base and rev. Ex‐
4828 amples:
4829 • status(3, 7, added()) - matches files added from "3" to "7"
4831 subrepo([pattern])
4833 Subrepositories whose paths match the given pattern.
4835 symlink()
4837 File that is marked as a symlink.
4839 tracked()
4841 File that is under Mercurial control.
4843 unknown()
4845 File that is unknown according to hg status.
4847 unresolved()
4849 File that is marked unresolved according to hg resolve -l.
4851 Examples
4853 Some sample queries:
4854 • Show status of files that appear to be binary in the working direc‐
4856 tory:
4857 hg status -A "set:binary()"
4859 • Forget files that are in .hgignore but are already tracked:
4861 hg forget "set:hgignore() and not ignored()"
4863 • Find text files that contain a string:
4865 hg files "set:grep(magic) and not binary()"
4867 • Find C files in a non-standard encoding:
4869 hg files "set:**.c and not encoding('UTF-8')"
4871 • Revert copies of large binary files:
4873 hg revert "set:copied() and binary() and size('>1M')"
4875 • Revert files that were added to the working directory:
4877 hg revert "set:revs('wdir()', added())"
4879 • Remove files listed in foo.lst that contain the letter a or b:
4881 hg remove "set: listfile:foo.lst and (**a* or **b*)"
4883
4885 Most Mercurial commands accept various flags.
4886 Flag names
4888 Flags for each command are listed in hg help for that command. Addi‐
4889 tionally, some flags, such as --repository, are global and can be used
4890 with any command - those are seen in hg help -v, and can be specified
4891 before or after the command.
4892 Every flag has at least a long name, such as --repository. Some flags
4894 may also have a short one-letter name, such as the equivalent -R. Using
4895 the short or long name is equivalent and has the same effect. The long
4896 name may be abbreviated to any unambiguous prefix. For example, hg com‐
4897 mit --amend can be abbreviated to hg commit --am.
4898 Flags that have a short name can also be bundled together - for in‐
4900 stance, to specify both --edit (short -e) and --interactive (short -i),
4901 one could use:
4902 hg commit -ei
4904 If any of the bundled flags takes a value (i.e. is not a boolean), it
4906 must be last, followed by the value:
4907 hg commit -im 'Message'
4909 Flag types
4911 Mercurial command-line flags can be strings, numbers, booleans, or
4912 lists of strings.
4913 Specifying flag values
4915 The following syntaxes are allowed, assuming a flag 'flagname' with
4916 short name 'f':
4917 --flagname=foo
4919 --flagname foo
4920 -f foo
4921 -ffoo
4922 This syntax applies to all non-boolean flags (strings, numbers or
4924 lists).
4925 Specifying boolean flags
4927 Boolean flags do not take a value parameter. To specify a boolean, use
4928 the flag name to set it to true, or the same name prefixed with 'no-'
4929 to set it to false:
4930 hg commit --interactive
4932 hg commit --no-interactive
4933 Specifying list flags
4935 List flags take multiple values. To specify them, pass the flag multi‐
4936 ple times:
4937 hg files --include mercurial --include tests
4939 Setting flag defaults
4941 In order to set a default value for a flag in an hgrc file, it is rec‐
4942 ommended to use aliases:
4943 [alias]
4945 commit = commit --interactive
4946 For more information on hgrc files, see hg help config.
4948 Overriding flags on the command line
4950 If the same non-list flag is specified multiple times on the command
4951 line, the latest specification is used:
4952 hg commit -m "Ignored value" -m "Used value"
4954 This includes the use of aliases - e.g., if one has:
4956 [alias]
4958 committemp = commit -m "Ignored value"
4959 then the following command will override that -m:
4961 hg committemp -m "Used value"
4963 Overriding flag defaults
4965 Every flag has a default value, and you may also set your own defaults
4966 in hgrc as described above. Except for list flags, defaults can be
4967 overridden on the command line simply by specifying the flag in that
4968 location.
4969 Hidden flags
4971 Some flags are not shown in a command's help by default - specifically,
4972 those that are deemed to be experimental, deprecated or advanced. To
4973 show all flags, add the --verbose flag for the help command:
4974 hg help --verbose commit
4976
4978 Ancestor
4979 Any changeset that can be reached by an unbroken chain of parent
4980 changesets from a given changeset. More precisely, the ancestors
4981 of a changeset can be defined by two properties: a parent of a
4982 changeset is an ancestor, and a parent of an ancestor is an an‐
4983 cestor. See also: 'Descendant'.
4984 Bookmark
4986 Bookmarks are pointers to certain commits that move when commit‐
4987 ting. They are similar to tags in that it is possible to use
4988 bookmark names in all places where Mercurial expects a changeset
4989 ID, e.g., with hg update. Unlike tags, bookmarks move along when
4990 you make a commit.
4991 Bookmarks can be renamed, copied and deleted. Bookmarks are lo‐
4993 cal, unless they are explicitly pushed or pulled between reposi‐
4994 tories. Pushing and pulling bookmarks allow you to collaborate
4995 with others on a branch without creating a named branch.
4996 Branch (Noun) A child changeset that has been created from a parent
4998 that is not a head. These are known as topological branches, see
4999 'Branch, topological'. If a topological branch is named, it be‐
5000 comes a named branch. If a topological branch is not named, it
5001 becomes an anonymous branch. See 'Branch, anonymous' and
5002 'Branch, named'.
5003 Branches may be created when changes are pulled from or pushed
5005 to a remote repository, since new heads may be created by these
5006 operations. Note that the term branch can also be used infor‐
5007 mally to describe a development process in which certain devel‐
5008 opment is done independently of other development. This is some‐
5009 times done explicitly with a named branch, but it can also be
5010 done locally, using bookmarks or clones and anonymous branches.
5011 Example: "The experimental branch."
5013 (Verb) The action of creating a child changeset which results in
5015 its parent having more than one child.
5016 Example: "I'm going to branch at X."
5018 Branch, anonymous
5020 Every time a new child changeset is created from a parent that
5021 is not a head and the name of the branch is not changed, a new
5022 anonymous branch is created.
5023 Branch, closed
5025 A named branch whose branch heads have all been closed.
5026 Branch, default
5028 The branch assigned to a changeset when no name has previously
5029 been assigned.
5030 Branch head
5032 See 'Head, branch'.
5033 Branch, inactive
5035 If a named branch has no topological heads, it is considered to
5036 be inactive. As an example, a feature branch becomes inactive
5037 when it is merged into the default branch. The hg branches com‐
5038 mand shows inactive branches by default, though they can be hid‐
5039 den with hg branches --active.
5040 NOTE: this concept is deprecated because it is too implicit.
5042 Branches should now be explicitly closed using hg commit
5043 --close-branch when they are no longer needed.
5044 Branch, named
5046 A collection of changesets which have the same branch name. By
5047 default, children of a changeset in a named branch belong to the
5048 same named branch. A child can be explicitly assigned to a dif‐
5049 ferent branch. See hg help branch, hg help branches and hg com‐
5050 mit --close-branch for more information on managing branches.
5051 Named branches can be thought of as a kind of namespace, divid‐
5053 ing the collection of changesets that comprise the repository
5054 into a collection of disjoint subsets. A named branch is not
5055 necessarily a topological branch. If a new named branch is cre‐
5056 ated from the head of another named branch, or the default
5057 branch, but no further changesets are added to that previous
5058 branch, then that previous branch will be a branch in name only.
5059 Branch tip
5061 See 'Tip, branch'.
5062 Branch, topological
5064 Every time a new child changeset is created from a parent that
5065 is not a head, a new topological branch is created. If a topo‐
5066 logical branch is named, it becomes a named branch. If a topo‐
5067 logical branch is not named, it becomes an anonymous branch of
5068 the current, possibly default, branch.
5069 Changelog
5071 A record of the changesets in the order in which they were added
5072 to the repository. This includes details such as changeset id,
5073 author, commit message, date, and list of changed files.
5074 Changeset
5076 A snapshot of the state of the repository used to record a
5077 change.
5078 Changeset, child
5080 The converse of parent changeset: if P is a parent of C, then C
5081 is a child of P. There is no limit to the number of children
5082 that a changeset may have.
5083 Changeset id
5085 A SHA-1 hash that uniquely identifies a changeset. It may be
5086 represented as either a "long" 40 hexadecimal digit string, or a
5087 "short" 12 hexadecimal digit string.
5088 Changeset, merge
5090 A changeset with two parents. This occurs when a merge is com‐
5091 mitted.
5092 Changeset, parent
5094 A revision upon which a child changeset is based. Specifically,
5095 a parent changeset of a changeset C is a changeset whose node
5096 immediately precedes C in the DAG. Changesets have at most two
5097 parents.
5098 Checkout
5100 (Noun) The working directory being updated to a specific revi‐
5101 sion. This use should probably be avoided where possible, as
5102 changeset is much more appropriate than checkout in this con‐
5103 text.
5104 Example: "I'm using checkout X."
5106 (Verb) Updating the working directory to a specific changeset.
5108 See hg help update.
5109 Example: "I'm going to check out changeset X."
5111 Child changeset
5113 See 'Changeset, child'.
5114 Close changeset
5116 See 'Head, closed branch'.
5117 Closed branch
5119 See 'Branch, closed'.
5120 Clone (Noun) An entire or partial copy of a repository. The partial
5122 clone must be in the form of a revision and its ancestors.
5123 Example: "Is your clone up to date?"
5125 (Verb) The process of creating a clone, using hg clone.
5127 Example: "I'm going to clone the repository."
5129 Closed branch head
5131 See 'Head, closed branch'.
5132 Commit (Noun) A synonym for changeset.
5134 Example: "Is the bug fixed in your recent commit?"
5136 (Verb) The act of recording changes to a repository. When files
5138 are committed in a working directory, Mercurial finds the dif‐
5139 ferences between the committed files and their parent changeset,
5140 creating a new changeset in the repository.
5141 Example: "You should commit those changes now."
5143 Cset A common abbreviation of the term changeset.
5145 DAG The repository of changesets of a distributed version control
5147 system (DVCS) can be described as a directed acyclic graph
5148 (DAG), consisting of nodes and edges, where nodes correspond to
5149 changesets and edges imply a parent -> child relation. This
5150 graph can be visualized by graphical tools such as hg log
5151 --graph. In Mercurial, the DAG is limited by the requirement for
5152 children to have at most two parents.
5153 Deprecated
5155 Feature removed from documentation, but not scheduled for re‐
5156 moval.
5157 Default branch
5159 See 'Branch, default'.
5160 Descendant
5162 Any changeset that can be reached by a chain of child changesets
5163 from a given changeset. More precisely, the descendants of a
5164 changeset can be defined by two properties: the child of a
5165 changeset is a descendant, and the child of a descendant is a
5166 descendant. See also: 'Ancestor'.
5167 Diff (Noun) The difference between the contents and attributes of
5169 files in two changesets or a changeset and the current working
5170 directory. The difference is usually represented in a standard
5171 form called a "diff" or "patch". The "git diff" format is used
5172 when the changes include copies, renames, or changes to file at‐
5173 tributes, none of which can be represented/handled by classic
5174 "diff" and "patch".
5175 Example: "Did you see my correction in the diff?"
5177 (Verb) Diffing two changesets is the action of creating a diff
5179 or patch.
5180 Example: "If you diff with changeset X, you will see what I
5182 mean."
5183 Directory, working
5185 The working directory represents the state of the files tracked
5186 by Mercurial, that will be recorded in the next commit. The
5187 working directory initially corresponds to the snapshot at an
5188 existing changeset, known as the parent of the working direc‐
5189 tory. See 'Parent, working directory'. The state may be modified
5190 by changes to the files introduced manually or by a merge. The
5191 repository metadata exists in the .hg directory inside the work‐
5192 ing directory.
5193 Draft Changesets in the draft phase have not been shared with publish‐
5195 ing repositories and may thus be safely changed by history-modi‐
5196 fying extensions. See hg help phases.
5197 Experimental
5199 Feature that may change or be removed at a later date.
5200 Graph See DAG and hg log --graph.
5202 Head The term 'head' may be used to refer to both a branch head or a
5204 repository head, depending on the context. See 'Head, branch'
5205 and 'Head, repository' for specific definitions.
5206 Heads are where development generally takes place and are the
5208 usual targets for update and merge operations.
5209 Head, branch
5211 A changeset with no descendants on the same named branch.
5212 Head, closed branch
5214 A changeset that marks a head as no longer interesting. The
5215 closed head is no longer listed by hg heads. A branch is consid‐
5216 ered closed when all its heads are closed and consequently is
5217 not listed by hg branches.
5218 Closed heads can be re-opened by committing new changeset as the
5220 child of the changeset that marks a head as closed.
5221 Head, repository
5223 A topological head which has not been closed.
5224 Head, topological
5226 A changeset with no children in the repository.
5227 History, immutable
5229 Once committed, changesets cannot be altered. Extensions which
5230 appear to change history actually create new changesets that re‐
5231 place existing ones, and then destroy the old changesets. Doing
5232 so in public repositories can result in old changesets being
5233 reintroduced to the repository.
5234 History, rewriting
5236 The changesets in a repository are immutable. However, exten‐
5237 sions to Mercurial can be used to alter the repository, usually
5238 in such a way as to preserve changeset contents.
5239 Immutable history
5241 See 'History, immutable'.
5242 Merge changeset
5244 See 'Changeset, merge'.
5245 Manifest
5247 Each changeset has a manifest, which is the list of files that
5248 are tracked by the changeset.
5249 Merge Used to bring together divergent branches of work. When you up‐
5251 date to a changeset and then merge another changeset, you bring
5252 the history of the latter changeset into your working directory.
5253 Once conflicts are resolved (and marked), this merge may be com‐
5254 mitted as a merge changeset, bringing two branches together in
5255 the DAG.
5256 Named branch
5258 See 'Branch, named'.
5259 Null changeset
5261 The empty changeset. It is the parent state of newly-initialized
5262 repositories and repositories with no checked out revision. It
5263 is thus the parent of root changesets and the effective ancestor
5264 when merging unrelated changesets. Can be specified by the alias
5265 'null' or by the changeset ID '000000000000'.
5266 Parent See 'Changeset, parent'.
5268 Parent changeset
5270 See 'Changeset, parent'.
5271 Parent, working directory
5273 The working directory parent reflects a virtual revision which
5274 is the child of the changeset (or two changesets with an uncom‐
5275 mitted merge) shown by hg parents. This is changed with hg up‐
5276 date. Other commands to see the working directory parent are hg
5277 summary and hg id. Can be specified by the alias ".".
5278 Patch (Noun) The product of a diff operation.
5280 Example: "I've sent you my patch."
5282 (Verb) The process of using a patch file to transform one
5284 changeset into another.
5285 Example: "You will need to patch that revision."
5287 Phase A per-changeset state tracking how the changeset has been or
5289 should be shared. See hg help phases.
5290 Public Changesets in the public phase have been shared with publishing
5292 repositories and are therefore considered immutable. See hg help
5293 phases.
5294 Pull An operation in which changesets in a remote repository which
5296 are not in the local repository are brought into the local
5297 repository. Note that this operation without special arguments
5298 only updates the repository, it does not update the files in the
5299 working directory. See hg help pull.
5300 Push An operation in which changesets in a local repository which are
5302 not in a remote repository are sent to the remote repository.
5303 Note that this operation only adds changesets which have been
5304 committed locally to the remote repository. Uncommitted changes
5305 are not sent. See hg help push.
5306 Repository
5308 The metadata describing all recorded states of a collection of
5309 files. Each recorded state is represented by a changeset. A
5310 repository is usually (but not always) found in the .hg subdi‐
5311 rectory of a working directory. Any recorded state can be recre‐
5312 ated by "updating" a working directory to a specific changeset.
5313 Repository head
5315 See 'Head, repository'.
5316 Revision
5318 A state of the repository at some point in time. Earlier revi‐
5319 sions can be updated to by using hg update. See also 'Revision
5320 number'; See also 'Changeset'.
5321 Revision number
5323 This integer uniquely identifies a changeset in a specific
5324 repository. It represents the order in which changesets were
5325 added to a repository, starting with revision number 0. Note
5326 that the revision number may be different in each clone of a
5327 repository. To identify changesets uniquely between different
5328 clones, see 'Changeset id'.
5329 Revlog History storage mechanism used by Mercurial. It is a form of
5331 delta encoding, with occasional full revision of data followed
5332 by delta of each successive revision. It includes data and an
5333 index pointing to the data.
5334 Rewriting history
5336 See 'History, rewriting'.
5337 Root A changeset that has only the null changeset as its parent. Most
5339 repositories have only a single root changeset.
5340 Secret Changesets in the secret phase may not be shared via push, pull,
5342 or clone. See hg help phases.
5343 Tag An alternative name given to a changeset. Tags can be used in
5345 all places where Mercurial expects a changeset ID, e.g., with hg
5346 update. The creation of a tag is stored in the history and will
5347 thus automatically be shared with other using push and pull.
5348 Tip The changeset with the highest revision number. It is the
5350 changeset most recently added in a repository.
5351 Tip, branch
5353 The head of a given branch with the highest revision number.
5354 When a branch name is used as a revision identifier, it refers
5355 to the branch tip. See also 'Branch, head'. Note that because
5356 revision numbers may be different in different repository
5357 clones, the branch tip may be different in different cloned
5358 repositories.
5359 Update (Noun) Another synonym of changeset.
5361 Example: "I've pushed an update."
5363 (Verb) This term is usually used to describe updating the state
5365 of the working directory to that of a specific changeset. See hg
5366 help update.
5367 Example: "You should update."
5369 Working directory
5371 See 'Directory, working'.
5372 Working directory parent
5374 See 'Parent, working directory'.
5375
5377 Synopsis
5378 The Mercurial system uses a file called .hgignore in the root directory
5379 of a repository to control its behavior when it searches for files that
5380 it is not currently tracking.
5381 Description
5383 The working directory of a Mercurial repository will often contain
5384 files that should not be tracked by Mercurial. These include backup
5385 files created by editors and build products created by compilers.
5386 These files can be ignored by listing them in a .hgignore file in the
5387 root of the working directory. The .hgignore file must be created manu‐
5388 ally. It is typically put under version control, so that the settings
5389 will propagate to other repositories with push and pull.
5390 An untracked file is ignored if its path relative to the repository
5392 root directory, or any prefix path of that path, is matched against any
5393 pattern in .hgignore.
5394 For example, say we have an untracked file, file.c, at a/b/file.c in‐
5396 side our repository. Mercurial will ignore file.c if any pattern in
5397 .hgignore matches a/b/file.c, a/b or a.
5398 In addition, a Mercurial configuration file can reference a set of
5400 per-user or global ignore files. See the ignore configuration key on
5401 the [ui] section of hg help config for details of how to configure
5402 these files.
5403 To control Mercurial's handling of files that it manages, many commands
5405 support the -I and -X options; see hg help <command> and hg help pat‐
5406 terns for details.
5407 Files that are already tracked are not affected by .hgignore, even if
5409 they appear in .hgignore. An untracked file X can be explicitly added
5410 with hg add X, even if X would be excluded by a pattern in .hgignore.
5411 Syntax
5413 An ignore file is a plain text file consisting of a list of patterns,
5414 with one pattern per line. Empty lines are skipped. The # character is
5415 treated as a comment character, and the \ character is treated as an
5416 escape character.
5417 Mercurial supports several pattern syntaxes. The default syntax used is
5419 Python/Perl-style regular expressions.
5420 To change the syntax used, use a line of the following form:
5422 syntax: NAME
5424 where NAME is one of the following:
5426 regexp
5428 Regular expression, Python/Perl syntax.
5430 glob
5432 Shell-style glob.
5434 rootglob
5436 A variant of glob that is rooted (see below).
5438 The chosen syntax stays in effect when parsing all patterns that fol‐
5440 low, until another syntax is selected.
5441 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
5443 the form *.c will match a file ending in .c in any directory, and a
5444 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
5445 tern, start it with ^. To get the same effect with glob-syntax, you
5446 have to use rootglob.
5447 Subdirectories can have their own .hgignore settings by adding subin‐
5449 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
5450 terns for details on subinclude: and include:.
5451 Note Patterns specified in other than .hgignore are always rooted.
5453 Please see hg help patterns for details.
5454 Example
5456 Here is an example ignore file.
5457 # use glob syntax.
5459 syntax: glob
5460 *.elc
5462 *.pyc
5463 *~
5464 # switch to regexp syntax.
5466 syntax: regexp
5467 ^\.pc/
5468 Debugging
5470 Use the debugignore command to see if and why a file is ignored, or to
5471 see the combined ignore pattern. See hg help debugignore for details.
5472
5474 Mercurial's internal web server, hgweb, can serve either a single
5475 repository, or a tree of repositories. In the second case, repository
5476 paths and global options can be defined using a dedicated configuration
5477 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
5478 This file uses the same syntax as other Mercurial configuration files
5480 but recognizes only the following sections:
5481 • web
5483 • paths
5485 • collections
5487 The web options are thoroughly described in hg help config.
5489 The paths section maps URL paths to paths of repositories in the
5491 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
5492 rial repositories can be published and only according to the configura‐
5493 tion.
5494 The left hand side is the path in the URL. Note that hgweb reserves
5496 subpaths like rev or file, try using different names for nested reposi‐
5497 tories to avoid confusing effects.
5498 The right hand side is the path in the filesystem. If the specified
5500 path ends with * or ** the filesystem will be searched recursively for
5501 repositories below that point. With * it will not recurse into the
5502 repositories it finds (except for .hg/patches). With ** it will also
5503 search inside repository working directories and possibly find sub‐
5504 repositories.
5505 In this example:
5507 [paths]
5509 /projects/a = /srv/tmprepos/a
5510 /projects/b = c:/repos/b
5511 / = /srv/repos/*
5512 /user/bob = /home/bob/repos/**
5513 • The first two entries make two repositories in different directories
5515 appear under the same directory in the web interface
5516 • The third entry will publish every Mercurial repository found in
5518 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
5519 as http://server/quux/
5520 • The fourth entry will publish both http://server/user/bob/quux/ and
5522 http://server/user/bob/quux/testsubrepo/
5523 The collections section is deprecated and has been superseded by paths.
5525 URLs and Common Arguments
5527 URLs under each repository have the form /{command}[/{arguments}] where
5528 {command} represents the name of a command or handler and {arguments}
5529 represents any number of additional URL parameters to that command.
5530 The web server has a default style associated with it. Styles map to a
5532 collection of named templates. Each template is used to render a spe‐
5533 cific piece of data, such as a changeset or diff.
5534 The style for the current request can be overridden two ways. First, if
5536 {command} contains a hyphen (-), the text before the hyphen defines the
5537 style. For example, /atom-log will render the log command handler with
5538 the atom style. The second way to set the style is with the style query
5539 string argument. For example, /log?style=atom. The hyphenated URL pa‐
5540 rameter is preferred.
5541 Not all templates are available for all styles. Attempting to use a
5543 style that doesn't have all templates defined may result in an error
5544 rendering the page.
5545 Many commands take a {revision} URL parameter. This defines the change‐
5547 set to operate on. This is commonly specified as the short, 12 digit
5548 hexadecimal abbreviation for the full 40 character unique revision
5549 identifier. However, any value described by hg help revisions typically
5550 works.
5551 Commands and URLs
5553 The following web commands and their URLs are available:
5554 /annotate/{revision}/{path}
5556 Show changeset information for each line in a file.
5557 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
5559 string arguments have the same meaning as their [annotate] config
5560 equivalents. It uses the hgrc boolean parsing logic to interpret the
5561 value. e.g. 0 and false are false and 1 and true are true. If not de‐
5562 fined, the server default settings are used.
5563 The fileannotate template is rendered.
5565 /archive/{revision}.{format}[/{path}]
5567 Obtain an archive of repository content.
5568 The content and type of the archive is defined by a URL path parameter.
5570 format is the file extension of the archive type to be generated. e.g.
5571 zip or tar.bz2. Not all archive types may be allowed by your server
5572 configuration.
5573 The optional path URL parameter controls content to include in the ar‐
5575 chive. If omitted, every file in the specified revision is present in
5576 the archive. If included, only the specified file or contents of the
5577 specified directory will be included in the archive.
5578 No template is used for this handler. Raw, binary content is generated.
5580 /bookmarks
5582 Show information about bookmarks.
5583 No arguments are accepted.
5585 The bookmarks template is rendered.
5587 /branches
5589 Show information about branches.
5590 All known branches are contained in the output, even closed branches.
5592 No arguments are accepted.
5594 The branches template is rendered.
5596 /changelog[/{revision}]
5598 Show information about multiple changesets.
5599 If the optional revision URL argument is absent, information about all
5601 changesets starting at tip will be rendered. If the revision argument
5602 is present, changesets will be shown starting from the specified revi‐
5603 sion.
5604 If revision is absent, the rev query string argument may be defined.
5606 This will perform a search for changesets.
5607 The argument for rev can be a single revision, a revision set, or a
5609 literal keyword to search for in changeset data (equivalent to hg log
5610 -k).
5611 The revcount query string argument defines the maximum numbers of
5613 changesets to render.
5614 For non-searches, the changelog template will be rendered.
5616 /changeset[/{revision}]
5618 Show information about a single changeset.
5619 A URL path argument is the changeset identifier to show. See hg help
5621 revisions for possible values. If not defined, the tip changeset will
5622 be shown.
5623 The changeset template is rendered. Contents of the changesettag,
5625 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5626 lated to diffs may all be used to produce the output.
5627 /comparison/{revision}/{path}
5629 Show a comparison between the old and new versions of a file from
5630 changes made on a particular revision.
5631 This is similar to the diff handler. However, this form features a
5633 split or side-by-side diff rather than a unified diff.
5634 The context query string argument can be used to control the lines of
5636 context in the diff.
5637 The filecomparison template is rendered.
5639 /diff/{revision}/{path}
5641 Show how a file changed in a particular commit.
5642 The filediff template is rendered.
5644 This handler is registered under both the /diff and /filediff paths.
5646 /diff is used in modern code.
5647 /file/{revision}[/{path}]
5649 Show information about a directory or file in the repository.
5650 Info about the path given as a URL parameter will be rendered.
5652 If path is a directory, information about the entries in that directory
5654 will be rendered. This form is equivalent to the manifest handler.
5655 If path is a file, information about that file will be shown via the
5657 filerevision template.
5658 If path is not defined, information about the root directory will be
5660 rendered.
5661 /diff/{revision}/{path}
5663 Show how a file changed in a particular commit.
5664 The filediff template is rendered.
5666 This handler is registered under both the /diff and /filediff paths.
5668 /diff is used in modern code.
5669 /filelog/{revision}/{path}
5671 Show information about the history of a file in the repository.
5672 The revcount query string argument can be defined to control the maxi‐
5674 mum number of entries to show.
5675 The filelog template will be rendered.
5677 /graph[/{revision}]
5679 Show information about the graphical topology of the repository.
5680 Information rendered by this handler can be used to create visual rep‐
5682 resentations of repository topology.
5683 The revision URL parameter controls the starting changeset. If it's ab‐
5685 sent, the default is tip.
5686 The revcount query string argument can define the number of changesets
5688 to show information for.
5689 The graphtop query string argument can specify the starting changeset
5691 for producing jsdata variable that is used for rendering graph in Java‐
5692 Script. By default it has the same value as revision.
5693 This handler will render the graph template.
5695 /help[/{topic}]
5697 Render help documentation.
5698 This web command is roughly equivalent to hg help. If a topic is de‐
5700 fined, that help topic will be rendered. If not, an index of available
5701 help topics will be rendered.
5702 The help template will be rendered when requesting help for a topic.
5704 helptopics will be rendered for the index of help topics.
5705 /log[/{revision}[/{path}]]
5707 Show repository or file history.
5708 For URLs of the form /log/{revision}, a list of changesets starting at
5710 the specified changeset identifier is shown. If {revision} is not de‐
5711 fined, the default is tip. This form is equivalent to the changelog
5712 handler.
5713 For URLs of the form /log/{revision}/{file}, the history for a specific
5715 file will be shown. This form is equivalent to the filelog handler.
5716 /manifest[/{revision}[/{path}]]
5718 Show information about a directory.
5719 If the URL path arguments are omitted, information about the root di‐
5721 rectory for the tip changeset will be shown.
5722 Because this handler can only show information for directories, it is
5724 recommended to use the file handler instead, as it can handle both di‐
5725 rectories and files.
5726 The manifest template will be rendered for this handler.
5728 /changeset[/{revision}]
5730 Show information about a single changeset.
5731 A URL path argument is the changeset identifier to show. See hg help
5733 revisions for possible values. If not defined, the tip changeset will
5734 be shown.
5735 The changeset template is rendered. Contents of the changesettag,
5737 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5738 lated to diffs may all be used to produce the output.
5739 /shortlog
5741 Show basic information about a set of changesets.
5742 This accepts the same parameters as the changelog handler. The only
5744 difference is the shortlog template will be rendered instead of the
5745 changelog template.
5746 /summary
5748 Show a summary of repository state.
5749 Information about the latest changesets, bookmarks, tags, and branches
5751 is captured by this handler.
5752 The summary template is rendered.
5754 /tags
5756 Show information about tags.
5757 No arguments are accepted.
5759 The tags template is rendered.
5761
5763 To access a subtopic, use "hg help internals.{subtopic-name}"
5764 bid-merge
5766 Bid Merge Algorithm
5767 bundle2
5769 Bundle2
5770 bundles
5772 Bundles
5773 cbor CBOR
5775 censor Censor
5777 changegroups
5779 Changegroups
5780 config Config Registrar
5782 extensions
5784 Extension API
5785 mergestate
5787 Mergestate
5788 requirements
5790 Repository Requirements
5791 revlogs
5793 Revision Logs
5794 wireprotocol
5796 Wire Protocol
5797 wireprotocolrpc
5799 Wire Protocol RPC
5800 wireprotocolv2
5802 Wire Protocol Version 2
5803
5805 To merge files Mercurial uses merge tools.
5806 A merge tool combines two different versions of a file into a merged
5808 file. Merge tools are given the two files and the greatest common an‐
5809 cestor of the two file versions, so they can determine the changes made
5810 on both branches.
5811 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
5813 out and in several extensions.
5814 Usually, the merge tool tries to automatically reconcile the files by
5816 combining all non-overlapping changes that occurred separately in the
5817 two different evolutions of the same initial base file. Furthermore,
5818 some interactive merge programs make it easier to manually resolve con‐
5819 flicting merges, either in a graphical way, or by inserting some con‐
5820 flict markers. Mercurial does not include any interactive merge pro‐
5821 grams but relies on external tools for that.
5822 Available merge tools
5824 External merge tools and their properties are configured in the
5825 merge-tools configuration section - see hgrc(5) - but they can often
5826 just be named by their executable.
5827 A merge tool is generally usable if its executable can be found on the
5829 system and if it can handle the merge. The executable is found if it is
5830 an absolute or relative executable path or the name of an application
5831 in the executable search path. The tool is assumed to be able to handle
5832 the merge if it can handle symlinks if the file is a symlink, if it can
5833 handle binary files if the file is binary, and if a GUI is available if
5834 the tool requires a GUI.
5835 There are some internal merge tools which can be used. The internal
5837 merge tools are:
5838 :dump
5840 Creates three versions of the files to merge, containing the
5842 contents of local, other and base. These files can then be used
5843 to perform a merge manually. If the file to be merged is named
5844 a.txt, these files will accordingly be named a.txt.local,
5845 a.txt.other and a.txt.base and they will be placed in the same
5846 directory as a.txt.
5847 This implies premerge. Therefore, files aren't dumped, if pre‐
5849 merge runs successfully. Use :forcedump to forcibly write files
5850 out.
5851 (actual capabilities: binary, symlink)
5853 :fail
5855 Rather than attempting to merge files that were modified on both
5857 branches, it marks them as unresolved. The resolve command must
5858 be used to resolve these conflicts.
5859 (actual capabilities: binary, symlink)
5861 :forcedump
5863 Creates three versions of the files as same as :dump, but omits
5865 premerge.
5866 (actual capabilities: binary, symlink)
5868 :local
5870 Uses the local p1() version of files as the merged version.
5872 (actual capabilities: binary, symlink)
5874 :merge
5876 Uses the internal non-interactive simple merge algorithm for
5878 merging files. It will fail if there are any conflicts and leave
5879 markers in the partially merged file. Markers will have two sec‐
5880 tions, one for each side of merge.
5881 :merge-local
5883 Like :merge, but resolve all conflicts non-interactively in fa‐
5885 vor of the local p1() changes.
5886 :merge-other
5888 Like :merge, but resolve all conflicts non-interactively in fa‐
5890 vor of the other p2() changes.
5891 :merge3
5893 Uses the internal non-interactive simple merge algorithm for
5895 merging files. It will fail if there are any conflicts and leave
5896 markers in the partially merged file. Marker will have three
5897 sections, one from each side of the merge and one for the base
5898 content.
5899 :mergediff
5901 Uses the internal non-interactive simple merge algorithm for
5903 merging files. It will fail if there are any conflicts and leave
5904 markers in the partially merged file. The marker will have two
5905 sections, one with the content from one side of the merge, and
5906 one with a diff from the base content to the content on the
5907 other side. (experimental)
5908 :other
5910 Uses the other p2() version of files as the merged version.
5912 (actual capabilities: binary, symlink)
5914 :prompt
5916 Asks the user which of the local p1() or the other p2() version
5918 to keep as the merged version.
5919 (actual capabilities: binary, symlink)
5921 :tagmerge
5923 Uses the internal tag merge algorithm (experimental).
5925 :union
5927 Uses the internal non-interactive simple merge algorithm for
5929 merging files. It will use both left and right sides for con‐
5930 flict regions. No markers are inserted.
5931 Internal tools are always available and do not require a GUI but will
5933 by default not handle symlinks or binary files. See next section for
5934 detail about "actual capabilities" described above.
5935 Choosing a merge tool
5937 Mercurial uses these rules when deciding which merge tool to use:
5938 1. If a tool has been specified with the --tool option to merge or re‐
5940 solve, it is used. If it is the name of a tool in the merge-tools
5941 configuration, its configuration is used. Otherwise the specified
5942 tool must be executable by the shell.
5943 2. If the HGMERGE environment variable is present, its value is used
5945 and must be executable by the shell.
5946 3. If the filename of the file to be merged matches any of the patterns
5948 in the merge-patterns configuration section, the first usable merge
5949 tool corresponding to a matching pattern is used.
5950 4. If ui.merge is set it will be considered next. If the value is not
5952 the name of a configured tool, the specified value is used and must
5953 be executable by the shell. Otherwise the named tool is used if it
5954 is usable.
5955 5. If any usable merge tools are present in the merge-tools configura‐
5957 tion section, the one with the highest priority is used.
5958 6. If a program named hgmerge can be found on the system, it is used -
5960 but it will by default not be used for symlinks and binary files.
5961 7. If the file to be merged is not binary and is not a symlink, then
5963 internal :merge is used.
5964 8. Otherwise, :prompt is used.
5966 For historical reason, Mercurial treats merge tools as below while ex‐
5968 amining rules above.
5969 ┌───────────┬────────────────┬────────┬─────────┐
5971 │step │ specified via │ binary │ symlink │
5972 ├───────────┼────────────────┼────────┼─────────┤
5973 │ │ --tool │ o/o │ o/o │
5974 │ 1. │ │ │ │
5975 ├───────────┼────────────────┼────────┼─────────┤
5976 │ │ HGMERGE │ o/o │ o/o │
5977 │ 2. │ │ │ │
5978 ├───────────┼────────────────┼────────┼─────────┤
5979 │ │ merge-patterns │ o/o(*) │ x/?(*) │
5980 │ 3. │ │ │ │
5981 ├───────────┼────────────────┼────────┼─────────┤
5982 │ │ ui.merge │ x/?(*) │ x/?(*) │
5983 │ 4. │ │ │ │
5984 └───────────┴────────────────┴────────┴─────────┘
5985 Each capability column indicates Mercurial behavior for internal/exter‐
5987 nal merge tools at examining each rule.
5988 • "o": "assume that a tool has capability"
5990 • "x": "assume that a tool does not have capability"
5992 • "?": "check actual capability of a tool"
5994 If merge.strict-capability-check configuration is true, Mercurial
5996 checks capabilities of merge tools strictly in (*) cases above (= each
5997 capability column becomes "?/?"). It is false by default for backward
5998 compatibility.
5999 Note After selecting a merge program, Mercurial will by default at‐
6001 tempt to merge the files using a simple merge algorithm first.
6002 Only if it doesn't succeed because of conflicting changes will
6003 Mercurial actually execute the merge program. Whether to use the
6004 simple merge algorithm first can be controlled by the premerge
6005 setting of the merge tool. Premerge is enabled by default unless
6006 the file is binary or a symlink.
6007 See the merge-tools and ui sections of hgrc(5) for details on the con‐
6009 figuration of merge tools.
6010
6012 Some Mercurial commands can produce a lot of output, and Mercurial will
6013 attempt to use a pager to make those commands more pleasant.
6014 To set the pager that should be used, set the application variable:
6016 [pager]
6018 pager = less -FRX
6019 If no pager is set in the user or repository configuration, Mercurial
6021 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
6022 from the default or system configuration is used. If none of these are
6023 set, a default pager will be used, typically less on Unix and more on
6024 Windows.
6025 On Windows, more is not color aware, so using it effectively disables
6027 color. MSYS and Cygwin shells provide less as a pager, which can be
6028 configured to support ANSI color codes. See hg help con‐
6029 fig.color.pagermode to configure the color mode when invoking a pager.
6030 You can disable the pager for certain commands by adding them to the
6032 pager.ignore list:
6033 [pager]
6035 ignore = version, help, update
6036 To ignore global commands like hg version or hg help, you have to spec‐
6038 ify them in your user configuration file.
6039 To control whether the pager is used at all for an individual command,
6041 you can use --pager=<value>:
6042 • use as needed: auto.
6044 • require the pager: yes or on.
6046 • suppress the pager: no or off (any unrecognized value will also
6048 work).
6049 To globally turn off all attempts to use a pager, set:
6051 [ui]
6053 paginate = never
6054 which will prevent the pager from running.
6056
6058 Mercurial accepts several notations for identifying one or more files
6059 at a time.
6060 By default, Mercurial treats filenames as shell-style extended glob
6062 patterns.
6063 Alternate pattern notations must be specified explicitly.
6065 Note Patterns specified in .hgignore are not rooted. Please see hg
6067 help hgignore for details.
6068 To use a plain path name without any pattern matching, start it with
6070 path:. These path names must completely match starting at the current
6071 repository root, and when the path points to a directory, it is matched
6072 recursively. To match all files in a directory non-recursively (not in‐
6073 cluding any files in subdirectories), rootfilesin: can be used, speci‐
6074 fying an absolute path (relative to the repository root).
6075 To use an extended glob, start a name with glob:. Globs are rooted at
6077 the current directory; a glob such as *.c will only match files in the
6078 current directory ending with .c. rootglob: can be used instead of
6079 glob: for a glob that is rooted at the root of the repository.
6080 The supported glob syntax extensions are ** to match any string across
6082 path separators and {a,b} to mean "a or b".
6083 To use a Perl/Python regular expression, start a name with re:. Regexp
6085 pattern matching is anchored at the root of the repository.
6086 To read name patterns from a file, use listfile: or listfile0:. The
6088 latter expects null delimited patterns while the former expects line
6089 feeds. Each string read from the file is itself treated as a file pat‐
6090 tern.
6091 To read a set of patterns from a file, use include: or subinclude:.
6093 include: will use all the patterns from the given file and treat them
6094 as if they had been passed in manually. subinclude: will only apply
6095 the patterns against files that are under the subinclude file's direc‐
6096 tory. See hg help hgignore for details on the format of these files.
6097 All patterns, except for glob: specified in command line (not for -I or
6099 -X options), can match also against directories: files under matched
6100 directories are treated as matched. For -I and -X options, glob: will
6101 match directories recursively.
6102 Plain examples:
6104 path:foo/bar a name bar in a directory named foo in the root
6106 of the repository
6107 path:path:name a file or directory named "path:name"
6108 rootfilesin:foo/bar the files in a directory called foo/bar, but not any files
6109 in its subdirectories and not a file bar in directory foo
6110 Glob examples:
6112 glob:*.c any name ending in ".c" in the current directory
6114 *.c any name ending in ".c" in the current directory
6115 **.c any name ending in ".c" in any subdirectory of the
6116 current directory including itself.
6117 foo/* any file in directory foo
6118 foo/** any file in directory foo plus all its subdirectories,
6119 recursively
6120 foo/*.c any name ending in ".c" in the directory foo
6121 foo/**.c any name ending in ".c" in any subdirectory of foo
6122 including itself.
6123 rootglob:*.c any name ending in ".c" in the root of the repository
6124 Regexp examples:
6126 re:.*\.c$ any name ending in ".c", anywhere in the repository
6128 File examples:
6130 listfile:list.txt read list from list.txt with one file pattern per line
6132 listfile0:list.txt read list from list.txt with null byte delimiters
6133 See also hg help filesets.
6135 Include examples:
6137 include:path/to/mypatternfile reads patterns to be applied to all paths
6139 subinclude:path/to/subignorefile reads patterns specifically for paths in the
6140 subdirectory
6141
6143 What are phases?
6144 Phases are a system for tracking which changesets have been or should
6145 be shared. This helps prevent common mistakes when modifying history
6146 (for instance, with the mq or rebase extensions).
6147 Each changeset in a repository is in one of the following phases:
6149 • public : changeset is visible on a public server
6151 • draft : changeset is not yet published
6153 • secret : changeset should not be pushed, pulled, or cloned
6155 These phases are ordered (public < draft < secret) and no changeset can
6157 be in a lower phase than its ancestors. For instance, if a changeset is
6158 public, all its ancestors are also public. Lastly, changeset phases
6159 should only be changed towards the public phase.
6160 How are phases managed?
6162 For the most part, phases should work transparently. By default, a
6163 changeset is created in the draft phase and is moved into the public
6164 phase when it is pushed to another repository.
6165 Once changesets become public, extensions like mq and rebase will
6167 refuse to operate on them to prevent creating duplicate changesets.
6168 Phases can also be manually manipulated with the hg phase command if
6169 needed. See hg help -v phase for examples.
6170 To make your commits secret by default, put this in your configuration
6172 file:
6173 [phases]
6175 new-commit = secret
6176 Phases and servers
6178 Normally, all servers are publishing by default. This means:
6179 - all draft changesets that are pulled or cloned appear in phase
6181 public on the client
6182 - all draft changesets that are pushed appear as public on both
6184 client and server
6185 - secret changesets are neither pushed, pulled, or cloned
6187 Note Pulling a draft changeset from a publishing server does not mark
6189 it as public on the server side due to the read-only nature of
6190 pull.
6191 Sometimes it may be desirable to push and pull changesets in the draft
6193 phase to share unfinished work. This can be done by setting a reposi‐
6194 tory to disable publishing in its configuration file:
6195 [phases]
6197 publish = False
6198 See hg help config for more information on configuration files.
6200 Note Servers running older versions of Mercurial are treated as pub‐
6202 lishing.
6203 Note Changesets in secret phase are not exchanged with the server.
6205 This applies to their content: file names, file contents, and
6206 changeset metadata. For technical reasons, the identifier (e.g.
6207 d825e4025e39) of the secret changeset may be communicated to the
6208 server.
6209 Examples
6211 • list changesets in draft or secret phase:
6212 hg log -r "not public()"
6214 • change all secret changesets to draft:
6216 hg phase --draft "secret()"
6218 • forcibly move the current changeset and descendants from public to
6220 draft:
6221 hg phase --force --draft .
6223 • show a list of changeset revisions and each corresponding phase:
6225 hg log --template "{rev} {phase}\n"
6227 • resynchronize draft changesets relative to a remote repository:
6229 hg phase -fd "outgoing(URL)"
6231 See hg help phase for more information on manually manipulating phases.
6233
6235 Mercurial supports several ways to specify revisions.
6236 Specifying single revisions
6238 A plain integer is treated as a revision number. Negative integers are
6239 treated as sequential offsets from the tip, with -1 denoting the tip,
6240 -2 denoting the revision prior to the tip, and so forth.
6241 A 40-digit hexadecimal string is treated as a unique revision identi‐
6243 fier. A hexadecimal string less than 40 characters long is treated as
6244 a unique revision identifier and is referred to as a short-form identi‐
6245 fier. A short-form identifier is only valid if it is the prefix of ex‐
6246 actly one full-length identifier.
6247 Any other string is treated as a bookmark, tag, or branch name. A book‐
6249 mark is a movable pointer to a revision. A tag is a permanent name as‐
6250 sociated with a revision. A branch name denotes the tipmost open branch
6251 head of that branch - or if they are all closed, the tipmost closed
6252 head of the branch. Bookmark, tag, and branch names must not contain
6253 the ":" character.
6254 The reserved name "tip" always identifies the most recent revision.
6256 The reserved name "null" indicates the null revision. This is the revi‐
6258 sion of an empty repository, and the parent of revision 0.
6259 The reserved name "." indicates the working directory parent. If no
6261 working directory is checked out, it is equivalent to null. If an un‐
6262 committed merge is in progress, "." is the revision of the first par‐
6263 ent.
6264 Finally, commands that expect a single revision (like hg update) also
6266 accept revsets (see below for details). When given a revset, they use
6267 the last revision of the revset. A few commands accept two single revi‐
6268 sions (like hg diff). When given a revset, they use the first and the
6269 last revisions of the revset.
6270 Specifying multiple revisions
6272 Mercurial supports a functional language for selecting a set of revi‐
6273 sions. Expressions in this language are called revsets.
6274 The language supports a number of predicates which are joined by infix
6276 operators. Parenthesis can be used for grouping.
6277 Identifiers such as branch names may need quoting with single or double
6279 quotes if they contain characters like - or if they match one of the
6280 predefined predicates.
6281 Special characters can be used in quoted identifiers by escaping them,
6283 e.g., \n is interpreted as a newline. To prevent them from being inter‐
6284 preted, strings can be prefixed with r, e.g. r'...'.
6285 Operators
6287 There is a single prefix operator:
6288 not x
6290 Changesets not in x. Short form is ! x.
6292 These are the supported infix operators:
6294 x::y
6296 A DAG range, meaning all changesets that are descendants of x
6298 and ancestors of y, including x and y themselves. If the first
6299 endpoint is left out, this is equivalent to ancestors(y), if the
6300 second is left out it is equivalent to descendants(x).
6301 An alternative syntax is x..y.
6303 x:y
6305 All changesets with revision numbers between x and y, both in‐
6307 clusive. Either endpoint can be left out, they default to 0 and
6308 tip.
6309 x and y
6311 The intersection of changesets in x and y. Short form is x & y.
6313 x or y
6315 The union of changesets in x and y. There are two alternative
6317 short forms: x | y and x + y.
6318 x - y
6320 Changesets in x but not in y.
6322 x % y
6324 Changesets that are ancestors of x but not ancestors of y (i.e.
6326 ::x - ::y). This is shorthand notation for only(x, y) (see be‐
6327 low). The second argument is optional and, if left out, is
6328 equivalent to only(x).
6329 x^n
6331 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
6333 1, the first parent of each changeset in x; for n == 2, the sec‐
6334 ond parent of changeset in x.
6335 x~n
6337 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
6339 the nth unambiguous descendent of x.
6340 x ## y
6342 Concatenate strings and identifiers into one string.
6344 All other prefix, infix and postfix operators have lower prior‐
6346 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
6347 a2)~2.
6348 For example:
6350 [revsetalias]
6352 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
6353 issue(1234) is equivalent to grep(r'\bissue[
6355 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
6356 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
6357 There is a single postfix operator:
6359 x^
6361 Equivalent to x^1, the first parent of each changeset in x.
6363 Patterns
6365 Where noted, predicates that perform string matching can accept a pat‐
6366 tern string. The pattern may be either a literal, or a regular expres‐
6367 sion. If the pattern starts with re:, the remainder of the pattern is
6368 treated as a regular expression. Otherwise, it is treated as a literal.
6369 To match a pattern that actually starts with re:, use the prefix lit‐
6370 eral:.
6371 Matching is case-sensitive, unless otherwise noted. To perform a case-
6373 insensitive match on a case-sensitive predicate, use a regular expres‐
6374 sion, prefixed with (?i).
6375 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
6377 "Release", etc.
6378 Predicates
6380 The following predicates are supported:
6381 adds(pattern)
6383 Changesets that add a file matching pattern.
6385 The pattern without explicit kind like glob: is expected to be
6387 relative to the current directory and match against a file or a
6388 directory.
6389 all()
6391 All changesets, the same as 0:tip.
6393 ancestor(*changeset)
6395 A greatest common ancestor of the changesets.
6397 Accepts 0 or more changesets. Will return empty list when
6399 passed no args. Greatest common ancestor of a single changeset
6400 is that changeset.
6401 ancestors(set[, depth])
6403 Changesets that are ancestors of changesets in set, including
6405 the given changesets themselves.
6406 If depth is specified, the result only includes changesets up to
6408 the specified generation.
6409 author(string)
6411 Alias for user(string).
6413 bisect(string)
6415 Changesets marked in the specified bisect status:
6417 • good, bad, skip: csets explicitly marked as good/bad/skip
6419 • goods, bads : csets topologically good/bad
6421 • range : csets taking part in the bisection
6423 • pruned : csets that are goods, bads or skipped
6425 • untested : csets whose fate is yet unknown
6427 • ignored : csets ignored due to DAG topology
6429 • current : the cset currently being bisected
6431 bookmark([name])
6433 The named bookmark or all bookmarks.
6435 Pattern matching is supported for name. See hg help revi‐
6437 sions.patterns.
6438 branch(string or set)
6440 All changesets belonging to the given branch or the branches of
6442 the given changesets.
6443 Pattern matching is supported for string. See hg help revi‐
6445 sions.patterns.
6446 branchpoint()
6448 Changesets with more than one child.
6450 bundle()
6452 Changesets in the bundle.
6454 Bundle must be specified by the -R option.
6456 children(set)
6458 Child changesets of changesets in set.
6460 closed()
6462 Changeset is closed.
6464 commonancestors(set)
6466 Changesets that are ancestors of every changeset in set.
6468 conflictlocal()
6470 The local side of the merge, if currently in an unresolved
6472 merge.
6473 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6475 'hg graft'.
6476 conflictother()
6478 The other side of the merge, if currently in an unresolved
6480 merge.
6481 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6483 'hg graft'.
6484 contains(pattern)
6486 The revision's manifest contains a file matching pattern (but
6488 might not modify it). See hg help patterns for information about
6489 file patterns.
6490 The pattern without explicit kind like glob: is expected to be
6492 relative to the current directory and match against a file ex‐
6493 actly for efficiency.
6494 converted([id])
6496 Changesets converted from the given identifier in the old repos‐
6498 itory if present, or all converted changesets if no identifier
6499 is specified.
6500 date(interval)
6502 Changesets within the interval, see hg help dates.
6504 desc(string)
6506 Search commit message for string. The match is case-insensitive.
6508 Pattern matching is supported for string. See hg help revi‐
6510 sions.patterns.
6511 descendants(set[, depth])
6513 Changesets which are descendants of changesets in set, including
6515 the given changesets themselves.
6516 If depth is specified, the result only includes changesets up to
6518 the specified generation.
6519 destination([set])
6521 Changesets that were created by a graft, transplant or rebase
6523 operation, with the given revisions specified as the source.
6524 Omitting the optional set is the same as passing all().
6525 diffcontains(pattern)
6527 Search revision differences for when the pattern was added or
6529 removed.
6530 The pattern may be a substring literal or a regular expression.
6532 See hg help revisions.patterns.
6533 draft()
6535 Changeset in draft phase.
6537 expectsize(set[, size])
6539 Return the given revset if size matches the revset size. Abort
6541 if the revset doesn't expect given size. size can either be an
6542 integer range or an integer.
6543 For example, expectsize(0:1, 3:5) will abort as revset size is 2
6545 and 2 is not between 3 and 5 inclusive.
6546 extra(label, [value])
6548 Changesets with the given label in the extra metadata, with the
6550 given optional value.
6551 Pattern matching is supported for value. See hg help revi‐
6553 sions.patterns.
6554 file(pattern)
6556 Changesets affecting files matched by pattern.
6558 For a faster but less accurate result, consider using filelog()
6560 instead.
6561 This predicate uses glob: as the default kind of pattern.
6563 filelog(pattern)
6565 Changesets connected to the specified filelog.
6567 For performance reasons, visits only revisions mentioned in the
6569 file-level filelog, rather than filtering through all changesets
6570 (much faster, but doesn't include deletes or duplicate changes).
6571 For a slower, more accurate result, use file().
6572 The pattern without explicit kind like glob: is expected to be
6574 relative to the current directory and match against a file ex‐
6575 actly for efficiency.
6576 first(set, [n])
6578 An alias for limit().
6580 follow([file[, startrev]])
6582 An alias for ::. (ancestors of the working directory's first
6584 parent). If file pattern is specified, the histories of files
6585 matching given pattern in the revision given by startrev are
6586 followed, including copies.
6587 followlines(file, fromline:toline[, startrev=., descend=False])
6589 Changesets modifying file in line range ('fromline', 'toline').
6591 Line range corresponds to 'file' content at 'startrev' and
6593 should hence be consistent with file size. If startrev is not
6594 specified, working directory's parent is used.
6595 By default, ancestors of 'startrev' are returned. If 'descend'
6597 is True, descendants of 'startrev' are returned though renames
6598 are (currently) not followed in this direction.
6599 grep(regex)
6601 Like keyword(string) but accepts a regex. Use grep(r'...') to
6603 ensure special escape characters are handled correctly. Unlike
6604 keyword(string), the match is case-sensitive.
6605 head()
6607 Changeset is a named branch head.
6609 heads(set)
6611 Members of set with no children in set.
6613 hidden()
6615 Hidden changesets.
6617 id(string)
6619 Revision non-ambiguously specified by the given hex string pre‐
6621 fix.
6622 keyword(string)
6624 Search commit message, user name, and names of changed files for
6626 string. The match is case-insensitive.
6627 For a regular expression or case sensitive search of these
6629 fields, use grep(regex).
6630 last(set, [n])
6632 Last n members of set, defaulting to 1.
6634 limit(set[, n[, offset]])
6636 First n members of set, defaulting to 1, starting from offset.
6638 matching(revision [, field])
6640 Changesets in which a given set of fields match the set of
6642 fields in the selected revision or set.
6643 To match more than one field pass the list of fields to match
6645 separated by spaces (e.g. author description).
6646 Valid fields are most regular revision fields and some special
6648 fields.
6649 Regular revision fields are description, author, branch, date,
6651 files, phase, parents, substate, user and diff. Note that au‐
6652 thor and user are synonyms. diff refers to the contents of the
6653 revision. Two revisions matching their diff will also match
6654 their files.
6655 Special fields are summary and metadata: summary matches the
6657 first line of the description. metadata is equivalent to match‐
6658 ing description user date (i.e. it matches the main metadata
6659 fields).
6660 metadata is the default field which is used when no fields are
6662 specified. You can match more than one field at a time.
6663 max(set)
6665 Changeset with highest revision number in set.
6667 merge()
6669 Changeset is a merge changeset.
6671 min(set)
6673 Changeset with lowest revision number in set.
6675 modifies(pattern)
6677 Changesets modifying files matched by pattern.
6679 The pattern without explicit kind like glob: is expected to be
6681 relative to the current directory and match against a file or a
6682 directory.
6683 named(namespace)
6685 The changesets in a given namespace.
6687 Pattern matching is supported for namespace. See hg help revi‐
6689 sions.patterns.
6690 none()
6692 No changesets.
6694 only(set, [set])
6696 Changesets that are ancestors of the first set that are not an‐
6698 cestors of any other head in the repo. If a second set is speci‐
6699 fied, the result is ancestors of the first set that are not an‐
6700 cestors of the second set (i.e. ::<set1> - ::<set2>).
6701 origin([set])
6703 Changesets that were specified as a source for the grafts,
6705 transplants or rebases that created the given revisions. Omit‐
6706 ting the optional set is the same as passing all(). If a
6707 changeset created by these operations is itself specified as a
6708 source for one of these operations, only the source changeset
6709 for the first operation is selected.
6710 outgoing([path])
6712 Changesets not found in the specified destination repository, or
6714 the default push location.
6715 p1([set])
6717 First parent of changesets in set, or the working directory.
6719 p2([set])
6721 Second parent of changesets in set, or the working directory.
6723 parents([set])
6725 The set of all parents for all changesets in set, or the working
6727 directory.
6728 present(set)
6730 An empty set, if any revision in set isn't found; otherwise, all
6732 revisions in set.
6733 If any of specified revisions is not present in the local repos‐
6735 itory, the query is normally aborted. But this predicate allows
6736 the query to continue even in such cases.
6737 public()
6739 Changeset in public phase.
6741 remote([id [,path]])
6743 Local revision that corresponds to the given identifier in a re‐
6745 mote repository, if present. Here, the '.' identifier is a syn‐
6746 onym for the current local branch.
6747 removes(pattern)
6749 Changesets which remove files matching pattern.
6751 The pattern without explicit kind like glob: is expected to be
6753 relative to the current directory and match against a file or a
6754 directory.
6755 rev(number)
6757 Revision with the given numeric identifier.
6759 reverse(set)
6761 Reverse order of set.
6763 revset(set)
6765 Strictly interpret the content as a revset.
6767 The content of this special predicate will be strictly inter‐
6769 preted as a revset. For example, revset(id(0)) will be inter‐
6770 preted as "id(0)" without possible ambiguity with a "id(0)"
6771 bookmark or tag.
6772 roots(set)
6774 Changesets in set with no parent changeset in set.
6776 secret()
6778 Changeset in secret phase.
6780 sort(set[, [-]key... [, ...]])
6782 Sort set by keys. The default sort order is ascending, specify a
6784 key as -key to sort in descending order.
6785 The keys can be:
6787 • rev for the revision number,
6789 • branch for the branch name,
6791 • desc for the commit message (description),
6793 • user for user name (author can be used as an alias),
6795 • date for the commit date
6797 • topo for a reverse topographical sort
6799 • node the nodeid of the revision
6801 The topo sort order cannot be combined with other sort keys.
6803 This sort takes one optional argument, topo.firstbranch, which
6804 takes a revset that specifies what topographical branches to
6805 prioritize in the sort.
6806 subrepo([pattern])
6808 Changesets that add, modify or remove the given subrepo. If no
6810 subrepo pattern is named, any subrepo changes are returned.
6811 tag([name])
6813 The specified tag by name, or all tagged revisions if no name is
6815 given.
6816 Pattern matching is supported for name. See hg help revi‐
6818 sions.patterns.
6819 user(string)
6821 User name contains string. The match is case-insensitive.
6823 Pattern matching is supported for string. See hg help revi‐
6825 sions.patterns.
6826 Aliases
6828 New predicates (known as "aliases") can be defined, using any combina‐
6829 tion of existing predicates or other aliases. An alias definition looks
6830 like:
6831 <alias> = <definition>
6833 in the revsetalias section of a Mercurial configuration file. Arguments
6835 of the form a1, a2, etc. are substituted from the alias into the defi‐
6836 nition.
6837 For example,
6839 [revsetalias]
6841 h = heads()
6842 d(s) = sort(s, date)
6843 rs(s, k) = reverse(sort(s, k))
6844 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
6846 equivalent to reverse(sort(0:tip, author)).
6847 Equivalents
6849 Command line equivalents for hg log:
6850 -f -> ::.
6852 -d x -> date(x)
6853 -k x -> keyword(x)
6854 -m -> merge()
6855 -u x -> user(x)
6856 -b x -> branch(x)
6857 -P x -> !::x
6858 -l x -> limit(expr, x)
6859 Examples
6861 Some sample queries:
6862 • Changesets on the default branch:
6864 hg log -r "branch(default)"
6866 • Changesets on the default branch since tag 1.5 (excluding merges):
6868 hg log -r "branch(default) and 1.5:: and not merge()"
6870 • Open branch heads:
6872 hg log -r "head() and not closed()"
6874 • Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
6876 hgext/*:
6877 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
6879 • Changesets committed in May 2008, sorted by user:
6881 hg log -r "sort(date('May 2008'), user)"
6883 • Changesets mentioning "bug" or "issue" that are not in a tagged re‐
6885 lease:
6886 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
6888 • Update to the commit that bookmark @ is pointing to, without activat‐
6890 ing the bookmark (this works because the last revision of the revset
6891 is used):
6892 hg update :@
6894 • Show diff between tags 1.3 and 1.5 (this works because the first and
6896 the last revisions of the revset are used):
6897 hg diff -r 1.3::1.5
6899
6901 It is common for machines (as opposed to humans) to consume Mercurial.
6902 This help topic describes some of the considerations for interfacing
6903 machines with Mercurial.
6904 Choosing an Interface
6906 Machines have a choice of several methods to interface with Mercurial.
6907 These include:
6908 • Executing the hg process
6910 • Querying a HTTP server
6912 • Calling out to a command server
6914 Executing hg processes is very similar to how humans interact with Mer‐
6916 curial in the shell. It should already be familiar to you.
6917 hg serve can be used to start a server. By default, this will start a
6919 "hgweb" HTTP server. This HTTP server has support for machine-readable
6920 output, such as JSON. For more, see hg help hgweb.
6921 hg serve can also start a "command server." Clients can connect to this
6923 server and issue Mercurial commands over a special protocol. For more
6924 details on the command server, including links to client libraries, see
6925 https://www.mercurial-scm.org/wiki/CommandServer.
6926 hg serve based interfaces (the hgweb and command servers) have the ad‐
6928 vantage over simple hg process invocations in that they are likely more
6929 efficient. This is because there is significant overhead to spawn new
6930 Python processes.
6931 Tip If you need to invoke several hg processes in short order and/or
6933 performance is important to you, use of a server-based interface
6934 is highly recommended.
6935 Environment Variables
6937 As documented in hg help environment, various environment variables in‐
6938 fluence the operation of Mercurial. The following are particularly rel‐
6939 evant for machines consuming Mercurial:
6940 HGPLAIN
6942 If not set, Mercurial's output could be influenced by configura‐
6943 tion settings that impact its encoding, verbose mode, localiza‐
6944 tion, etc.
6945 It is highly recommended for machines to set this variable when
6947 invoking hg processes.
6948 HGENCODING
6950 If not set, the locale used by Mercurial will be detected from
6951 the environment. If the determined locale does not support dis‐
6952 play of certain characters, Mercurial may render these character
6953 sequences incorrectly (often by using "?" as a placeholder for
6954 invalid characters in the current locale).
6955 Explicitly setting this environment variable is a good practice
6957 to guarantee consistent results. "utf-8" is a good choice on
6958 UNIX-like environments.
6959 HGRCPATH
6961 If not set, Mercurial will inherit config options from config
6962 files using the process described in hg help config. This in‐
6963 cludes inheriting user or system-wide config files.
6964 When utmost control over the Mercurial configuration is desired,
6966 the value of HGRCPATH can be set to an explicit file with known
6967 good configs. In rare cases, the value can be set to an empty
6968 file or the null device (often /dev/null) to bypass loading of
6969 any user or system config files. Note that these approaches can
6970 have unintended consequences, as the user and system config
6971 files often define things like the username and extensions that
6972 may be required to interface with a repository.
6973 HGRCSKIPREPO
6975 When set, the .hg/hgrc from repositories are not read.
6976 Note that not reading the repository's configuration can have
6978 unintended consequences, as the repository config files can de‐
6979 fine things like extensions that are required for access to the
6980 repository.
6981 Command-line Flags
6983 Mercurial's default command-line parser is designed for humans, and is
6984 not robust against malicious input. For instance, you can start a de‐
6985 bugger by passing --debugger as an option value:
6986 $ REV=--debugger sh -c 'hg log -r "$REV"'
6988 This happens because several command-line flags need to be scanned
6990 without using a concrete command table, which may be modified while
6991 loading repository settings and extensions.
6992 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
6994 setting HGPLAIN=+strictflags. When this feature is enabled, all early
6995 options (e.g. -R/--repository, --cwd, --config) must be specified first
6996 amongst the other global options, and cannot be injected to an arbi‐
6997 trary location:
6998 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
7000 In earlier Mercurial versions where +strictflags isn't available, you
7002 can mitigate the issue by concatenating an option value with its flag:
7003 $ hg log -r"$REV" --keyword="$KEYWORD"
7005 Consuming Command Output
7007 It is common for machines to need to parse the output of Mercurial com‐
7008 mands for relevant data. This section describes the various techniques
7009 for doing so.
7010 Parsing Raw Command Output
7012 Likely the simplest and most effective solution for consuming command
7013 output is to simply invoke hg commands as you would as a user and parse
7014 their output.
7015 The output of many commands can easily be parsed with tools like grep,
7017 sed, and awk.
7018 A potential downside with parsing command output is that the output of
7020 commands can change when Mercurial is upgraded. While Mercurial does
7021 generally strive for strong backwards compatibility, command output
7022 does occasionally change. Having tests for your automated interactions
7023 with hg commands is generally recommended, but is even more important
7024 when raw command output parsing is involved.
7025 Using Templates to Control Output
7027 Many hg commands support templatized output via the -T/--template argu‐
7028 ment. For more, see hg help templates.
7029 Templates are useful for explicitly controlling output so that you get
7031 exactly the data you want formatted how you want it. For example, log
7032 -T {node}\n can be used to print a newline delimited list of changeset
7033 nodes instead of a human-tailored output containing authors, dates, de‐
7034 scriptions, etc.
7035 Tip If parsing raw command output is too complicated, consider using
7037 templates to make your life easier.
7038 The -T/--template argument allows specifying pre-defined styles. Mer‐
7040 curial ships with the machine-readable styles cbor, json, and xml,
7041 which provide CBOR, JSON, and XML output, respectively. These are use‐
7042 ful for producing output that is machine readable as-is.
7043 (Mercurial 5.0 is required for CBOR style.)
7045 Important
7047 The json and xml styles are considered experimental. While they
7048 may be attractive to use for easily obtaining machine-readable
7049 output, their behavior may change in subsequent versions.
7050 These styles may also exhibit unexpected results when dealing
7052 with certain encodings. Mercurial treats things like filenames
7053 as a series of bytes and normalizing certain byte sequences to
7054 JSON or XML with certain encoding settings can lead to sur‐
7055 prises.
7056 Command Server Output
7058 If using the command server to interact with Mercurial, you are likely
7059 using an existing library/API that abstracts implementation details of
7060 the command server. If so, this interface layer may perform parsing for
7061 you, saving you the work of implementing it yourself.
7062 Output Verbosity
7064 Commands often have varying output verbosity, even when machine read‐
7065 able styles are being used (e.g. -T json). Adding -v/--verbose and
7066 --debug to the command's arguments can increase the amount of data ex‐
7067 posed by Mercurial.
7068 An alternate way to get the data you need is by explicitly specifying a
7070 template.
7071 Other Topics
7073 revsets
7074 Revisions sets is a functional query language for selecting a
7075 set of revisions. Think of it as SQL for Mercurial repositories.
7076 Revsets are useful for querying repositories for specific data.
7077 See hg help revsets for more.
7079 share extension
7081 The share extension provides functionality for sharing reposi‐
7082 tory data across several working copies. It can even automati‐
7083 cally "pool" storage for logically related repositories when
7084 cloning.
7085 Configuring the share extension can lead to significant resource
7087 utilization reduction, particularly around disk space and the
7088 network. This is especially true for continuous integration (CI)
7089 environments.
7090 See hg help -e share for more.
7092
7094 Subrepositories let you nest external repositories or projects into a
7095 parent Mercurial repository, and make commands operate on them as a
7096 group.
7097 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
7099 tories.
7100 Subrepositories are made of three components:
7102 1. Nested repository checkouts. They can appear anywhere in the parent
7104 working directory.
7105 2. Nested repository references. They are defined in .hgsub, which
7107 should be placed in the root of working directory, and tell where
7108 the subrepository checkouts come from. Mercurial subrepositories are
7109 referenced like:
7110 path/to/nested = https://example.com/nested/repo/path
7112 Git and Subversion subrepos are also supported:
7114 path/to/nested = [git]git://example.com/nested/repo/path
7116 path/to/nested = [svn]https://example.com/nested/trunk/path
7117 where path/to/nested is the checkout location relatively to the par‐
7119 ent Mercurial root, and https://example.com/nested/repo/path is the
7120 source repository path. The source can also reference a filesystem
7121 path.
7122 Note that .hgsub does not exist by default in Mercurial reposito‐
7124 ries, you have to create and add it to the parent repository before
7125 using subrepositories.
7126 3. Nested repository states. They are defined in .hgsubstate, which is
7128 placed in the root of working directory, and capture whatever infor‐
7129 mation is required to restore the subrepositories to the state they
7130 were committed in a parent repository changeset. Mercurial automati‐
7131 cally record the nested repositories states when committing in the
7132 parent repository.
7133 Note
7135 The .hgsubstate file should not be edited manually.
7136 Adding a Subrepository
7138 If .hgsub does not exist, create it and add it to the parent reposi‐
7139 tory. Clone or checkout the external projects where you want it to live
7140 in the parent repository. Edit .hgsub and add the subrepository entry
7141 as described above. At this point, the subrepository is tracked and the
7142 next commit will record its state in .hgsubstate and bind it to the
7143 committed changeset.
7144 Synchronizing a Subrepository
7146 Subrepos do not automatically track the latest changeset of their
7147 sources. Instead, they are updated to the changeset that corresponds
7148 with the changeset checked out in the top-level changeset. This is so
7149 developers always get a consistent set of compatible code and libraries
7150 when they update.
7151 Thus, updating subrepos is a manual process. Simply check out target
7153 subrepo at the desired revision, test in the top-level repo, then com‐
7154 mit in the parent repository to record the new combination.
7155 Deleting a Subrepository
7157 To remove a subrepository from the parent repository, delete its refer‐
7158 ence from .hgsub, then remove its files.
7159 Interaction with Mercurial Commands
7161 add add does not recurse in subrepos unless -S/--subrepos is speci‐
7162 fied. However, if you specify the full path of a file in a sub‐
7163 repo, it will be added even without -S/--subrepos specified.
7164 Subversion subrepositories are currently silently ignored.
7165 addremove
7167 addremove does not recurse into subrepos unless -S/--subrepos is
7168 specified. However, if you specify the full path of a directory
7169 in a subrepo, addremove will be performed on it even without
7170 -S/--subrepos being specified. Git and Subversion subreposito‐
7171 ries will print a warning and continue.
7172 archive
7174 archive does not recurse in subrepositories unless -S/--subrepos
7175 is specified.
7176 cat Git subrepositories only support exact file matches. Subversion
7178 subrepositories are currently ignored.
7179 commit commit creates a consistent snapshot of the state of the entire
7181 project and its subrepositories. If any subrepositories have
7182 been modified, Mercurial will abort. Mercurial can be made to
7183 instead commit all modified subrepositories by specifying
7184 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
7185 ration file (see hg help config). After there are no longer any
7186 modified subrepositories, it records their state and finally
7187 commits it in the parent repository. The --addremove option
7188 also honors the -S/--subrepos option. However, Git and Subver‐
7189 sion subrepositories will print a warning and abort.
7190 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
7192 fied. However, if you specify the full path of a file or direc‐
7193 tory in a subrepo, it will be diffed even without -S/--subrepos
7194 being specified. Subversion subrepositories are currently
7195 silently ignored.
7196 files files does not recurse into subrepos unless -S/--subrepos is
7198 specified. However, if you specify the full path of a file or
7199 directory in a subrepo, it will be displayed even without
7200 -S/--subrepos being specified. Git and Subversion subreposito‐
7201 ries are currently silently ignored.
7202 forget forget currently only handles exact file matches in subrepos.
7204 Git and Subversion subrepositories are currently silently ig‐
7205 nored.
7206 incoming
7208 incoming does not recurse in subrepos unless -S/--subrepos is
7209 specified. Git and Subversion subrepositories are currently
7210 silently ignored.
7211 outgoing
7213 outgoing does not recurse in subrepos unless -S/--subrepos is
7214 specified. Git and Subversion subrepositories are currently
7215 silently ignored.
7216 pull pull is not recursive since it is not clear what to pull prior
7218 to running hg update. Listing and retrieving all subrepositories
7219 changes referenced by the parent repository pulled changesets is
7220 expensive at best, impossible in the Subversion case.
7221 push Mercurial will automatically push all subrepositories first when
7223 the parent repository is being pushed. This ensures new sub‐
7224 repository changes are available when referenced by top-level
7225 repositories. Push is a no-op for Subversion subrepositories.
7226 serve serve does not recurse into subrepositories unless -S/--subrepos
7228 is specified. Git and Subversion subrepositories are currently
7229 silently ignored.
7230 status status does not recurse into subrepositories unless -S/--subre‐
7232 pos is specified. Subrepository changes are displayed as regular
7233 Mercurial changes on the subrepository elements. Subversion sub‐
7234 repositories are currently silently ignored.
7235 remove remove does not recurse into subrepositories unless -S/--subre‐
7237 pos is specified. However, if you specify a file or directory
7238 path in a subrepo, it will be removed even without -S/--subre‐
7239 pos. Git and Subversion subrepositories are currently silently
7240 ignored.
7241 update update restores the subrepos in the state they were originally
7243 committed in target changeset. If the recorded changeset is not
7244 available in the current subrepository, Mercurial will pull it
7245 in first before updating. This means that updating can require
7246 network access when using subrepositories.
7247 Remapping Subrepositories Sources
7249 A subrepository source location may change during a project life, in‐
7250 validating references stored in the parent repository history. To fix
7251 this, rewriting rules can be defined in parent repository hgrc file or
7252 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
7253 more details.
7254
7256 Mercurial allows you to customize output of commands through templates.
7257 You can either pass in a template or select an existing template-style
7258 from the command line, via the --template option.
7259 You can customize output for any "log-like" command: log, outgoing, in‐
7261 coming, tip, parents, and heads.
7262 Some built-in styles are packaged with Mercurial. These can be listed
7264 with hg log --template list. Example usage:
7265 $ hg log -r1.0::1.1 --template changelog
7267 A template is a piece of text, with markup to invoke variable expan‐
7269 sion:
7270 $ hg log -r1 --template "{node}\n"
7272 b56ce7b07c52de7d5fd79fb89701ea538af65746
7273 Keywords
7275 Strings in curly braces are called keywords. The availability of key‐
7276 words depends on the exact context of the templater. These keywords are
7277 usually available for templating a log-like command:
7278 activebookmark
7280 String. The active bookmark, if it is associated with the
7281 changeset.
7282 author Alias for {user}
7284 bisect String. The changeset bisection status.
7286 bookmarks
7288 List of strings. Any bookmarks associated with the changeset.
7289 Also sets 'active', the name of the active bookmark.
7290 branch String. The name of the branch on which the changeset was com‐
7292 mitted.
7293 changessincelatesttag
7295 Integer. All ancestors not in the latest tag.
7296 children
7298 List of strings. The children of the changeset.
7299 date Date information. The date when the changeset was committed.
7301 desc String. The text of the changeset description.
7303 diffstat
7305 String. Statistics of changes with the following format: "modi‐
7306 fied files: +added/-removed lines"
7307 extras List of dicts with key, value entries of the 'extras' field of
7309 this changeset.
7310 file_adds
7312 List of strings. Files added by this changeset.
7313 file_copies
7315 List of strings. Files copied in this changeset with their
7316 sources.
7317 file_copies_switch
7319 List of strings. Like "file_copies" but displayed only if the
7320 --copied switch is set.
7321 file_dels
7323 List of strings. Files removed by this changeset.
7324 file_mods
7326 List of strings. Files modified by this changeset.
7327 files List of strings. All files modified, added, or removed by this
7329 changeset.
7330 graphnode
7332 String. The character representing the changeset node in an
7333 ASCII revision graph.
7334 graphwidth
7336 Integer. The width of the graph drawn by 'log --graph' or zero.
7337 index Integer. The current iteration of the loop. (0 indexed)
7339 latesttag
7341 List of strings. The global tags on the most recent globally
7342 tagged ancestor of this changeset. If no such tags exist, the
7343 list consists of the single string "null".
7344 latesttagdistance
7346 Integer. Longest path to the latest tag.
7347 namespaces
7349 Dict of lists. Names attached to this changeset per namespace.
7350 negrev Integer. The repository-local changeset negative revision num‐
7352 ber, which counts in the opposite direction.
7353 node String. The changeset identification hash, as a 40 hexadecimal
7355 digit string.
7356 onelinesummary
7358 String. A one-line summary for the ctx (not including trailing
7359 newline). The default template be overridden in command-tem‐
7360 plates.oneline-summary.
7361 p1 Changeset. The changeset's first parent. {p1.rev} for the revi‐
7363 sion number, and {p1.node} for the identification hash.
7364 p2 Changeset. The changeset's second parent. {p2.rev} for the revi‐
7366 sion number, and {p2.node} for the identification hash.
7367 parents
7369 List of strings. The parents of the changeset in "rev:node" for‐
7370 mat. If the changeset has only one "natural" parent (the prede‐
7371 cessor revision) nothing is shown.
7372 peerurls
7374 A dictionary of repository locations defined in the [paths] sec‐
7375 tion of your configuration file.
7376 phase String. The changeset phase name.
7378 reporoot
7380 String. The root directory of the current repository.
7381 rev Integer. The repository-local changeset revision number.
7383 subrepos
7385 List of strings. Updated subrepositories in the changeset.
7386 tags List of strings. Any tags associated with the changeset.
7388 termwidth
7390 Integer. The width of the current terminal.
7391 user String. The unmodified author of the changeset.
7393 verbosity
7395 String. The current output verbosity in 'debug', 'quiet', 'ver‐
7396 bose', or ''.
7397 The "date" keyword does not produce human-readable output. If you want
7399 to use a date in your output, you can use a filter to process it. Fil‐
7400 ters are functions which return a string based on the input variable.
7401 Be sure to use the stringify filter first when you're applying a
7402 string-input filter to a list-like input variable. You can also use a
7403 chain of filters to get the desired output:
7404 $ hg tip --template "{date|isodate}\n"
7406 2008-08-21 18:22 +0000
7407 Filters
7409 List of filters:
7410 addbreaks
7412 Any text. Add an XHTML "<br />" tag before the end of every line
7413 except the last.
7414 age Date. Returns a human-readable date/time difference between the
7416 given date/time and the current date/time.
7417 basename
7419 Any text. Treats the text as a path, and returns the last compo‐
7420 nent of the path after splitting by the path separator. For ex‐
7421 ample, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
7422 cbor Any object. Serializes the object to CBOR bytes.
7424 commondir
7426 List of text. Treats each list item as file name with / as path
7427 separator and returns the longest common directory prefix shared
7428 by all list items. Returns the empty string if no common prefix
7429 exists.
7430 The list items are not normalized, i.e. "foo/../bar" is handled
7432 as file "bar" in the directory "foo/..". Leading slashes are ig‐
7433 nored.
7434 For example, ["foo/bar/baz", "foo/baz/bar"] becomes "foo" and
7436 ["foo/bar", "baz"] becomes "".
7437 count List or text. Returns the length as an integer.
7439 dirname
7441 Any text. Treats the text as a path, and strips the last compo‐
7442 nent of the path after splitting by the path separator.
7443 domain Any text. Finds the first string that looks like an email ad‐
7445 dress, and extracts just the domain component. Example: User
7446 <user@example.com> becomes example.com.
7447 email Any text. Extracts the first string that looks like an email ad‐
7449 dress. Example: User <user@example.com> becomes user@exam‐
7450 ple.com.
7451 emailuser
7453 Any text. Returns the user portion of an email address.
7454 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
7456 ">" with XML entities, and filters out NUL characters.
7457 fill68 Any text. Wraps the text to fit in 68 columns.
7459 fill76 Any text. Wraps the text to fit in 76 columns.
7461 firstline
7463 Any text. Returns the first line of text.
7464 hex Any text. Convert a binary Mercurial node identifier into its
7466 long hexadecimal representation.
7467 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
7469 (Unix timestamp, timezone offset).
7470 isodate
7472 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
7473 +0200".
7474 isodatesec
7476 Date. Returns the date in ISO 8601 format, including seconds:
7477 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
7478 json Any object. Serializes the object to a JSON formatted text.
7480 lower Any text. Converts the text to lowercase.
7482 nonempty
7484 Any text. Returns '(none)' if the string is empty.
7485 obfuscate
7487 Any text. Returns the input text rendered as a sequence of XML
7488 entities.
7489 person Any text. Returns the name before an email address, interpreting
7491 it as per RFC 5322.
7492 revescape
7494 Any text. Escapes all "special" characters, except @. Forward
7495 slashes are escaped twice to prevent web servers from prema‐
7496 turely unescaping them. For example, "@foo bar/baz" becomes
7497 "@foo%20bar%252Fbaz".
7498 rfc3339date
7500 Date. Returns a date using the Internet date format specified in
7501 RFC 3339: "2009-08-18T13:00:13+02:00".
7502 rfc822date
7504 Date. Returns a date using the same format used in email head‐
7505 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
7506 short Changeset hash. Returns the short form of a changeset hash, i.e.
7508 a 12 hexadecimal digit string.
7509 shortbisect
7511 Any text. Treats label as a bisection status, and returns a sin‐
7512 gle-character representing the status (G: good, B: bad, S:
7513 skipped, U: untested, I: ignored). Returns single space if text
7514 is not a valid bisection status.
7515 shortdate
7517 Date. Returns a date like "2006-09-18".
7518 slashpath
7520 Any text. Replaces the native path separator with slash.
7521 splitlines
7523 Any text. Split text into a list of lines.
7524 stringify
7526 Any type. Turns the value into text by converting values into
7527 text and concatenating them.
7528 stripdir
7530 Treat the text as path and strip a directory level, if possible.
7531 For example, "foo" and "foo/bar" becomes "foo".
7532 tabindent
7534 Any text. Returns the text, with every non-empty line except the
7535 first starting with a tab character.
7536 upper Any text. Converts the text to uppercase.
7538 urlescape
7540 Any text. Escapes all "special" characters. For example, "foo
7541 bar" becomes "foo%20bar".
7542 user Any text. Returns a short representation of a user name or email
7544 address.
7545 utf8 Any text. Converts from the local character encoding to UTF-8.
7547 Note that a filter is nothing more than a function call, i.e.
7549 expr|filter is equivalent to filter(expr).
7550 Functions
7552 In addition to filters, there are some basic built-in functions:
7553 config(section, name[, default])
7555 Returns the requested hgrc config option as a string.
7556 configbool(section, name[, default])
7558 Returns the requested hgrc config option as a boolean.
7559 configint(section, name[, default])
7561 Returns the requested hgrc config option as an integer.
7562 date(date[, fmt])
7564 Format a date. See hg help dates for formatting strings. The de‐
7565 fault is a Unix date format, including the timezone: "Mon Sep 04
7566 15:13:13 2006 0700".
7567 dict([[key=]value...])
7569 Construct a dict from key-value pairs. A key may be omitted if a
7570 value expression can provide an unambiguous name.
7571 diff([includepattern [, excludepattern]])
7573 Show a diff, optionally specifying files to include or exclude.
7574 files(pattern)
7576 All files of the current changeset matching the pattern. See hg
7577 help patterns.
7578 fill(text[, width[, initialident[, hangindent]]])
7580 Fill many paragraphs with optional indentation. See the "fill"
7581 filter.
7582 filter(iterable[, expr])
7584 Remove empty elements from a list or a dict. If expr specified,
7585 it's applied to each element to test emptiness.
7586 get(dict, key)
7588 Get an attribute/key from an object. Some keywords are complex
7589 types. This function allows you to obtain the value of an attri‐
7590 bute on these types.
7591 if(expr, then[, else])
7593 Conditionally execute based on the result of an expression.
7594 ifcontains(needle, haystack, then[, else])
7596 Conditionally execute based on whether the item "needle" is in
7597 "haystack".
7598 ifeq(expr1, expr2, then[, else])
7600 Conditionally execute based on whether 2 items are equivalent.
7601 indent(text, indentchars[, firstline])
7603 Indents all non-empty lines with the characters given in the in‐
7604 dentchars string. An optional third parameter will override the
7605 indent for the first line only if present.
7606 join(list, sep)
7608 Join items in a list with a delimiter.
7609 label(label, expr)
7611 Apply a label to generated content. Content with a label applied
7612 can result in additional post-processing, such as automatic col‐
7613 orization.
7614 latesttag([pattern])
7616 The global tags matching the given pattern on the most recent
7617 globally tagged ancestor of this changeset. If no such tags ex‐
7618 ist, the "{tag}" template resolves to the string "null". See hg
7619 help revisions.patterns for the pattern syntax.
7620 localdate(date[, tz])
7622 Converts a date to the specified timezone. The default is local
7623 date.
7624 mailmap(author)
7626 Return the author, updated according to the value set in the
7627 .mailmap file
7628 max(iterable)
7630 Return the max of an iterable
7631 min(iterable)
7633 Return the min of an iterable
7634 mod(a, b)
7636 Calculate a mod b such that a / b + a mod b == a
7637 pad(text, width[, fillchar=' '[, left=False[, truncate=False]]])
7639 Pad text with a fill character.
7640 relpath(path)
7642 Convert a repository-absolute path into a filesystem path rela‐
7643 tive to the current working directory.
7644 revset(query[, formatargs...])
7646 Execute a revision set query. See hg help revset.
7647 rstdoc(text, style)
7649 Format reStructuredText.
7650 search(pattern, text)
7652 Look for the first text matching the regular expression pattern.
7653 Groups are accessible as {1}, {2}, ... in %-mapped template.
7654 separate(sep, args...)
7656 Add a separator between non-empty arguments.
7657 shortest(node, minlength=4)
7659 Obtain the shortest representation of a node.
7660 startswith(pattern, text)
7662 Returns the value from the "text" argument if it begins with the
7663 content from the "pattern" argument.
7664 strip(text[, chars])
7666 Strip characters from a string. By default, strips all leading
7667 and trailing whitespace.
7668 sub(pattern, replacement, expression)
7670 Perform text substitution using regular expressions.
7671 subsetparents(rev, revset)
7673 Look up parents of the rev in the sub graph given by the revset.
7674 word(number, text[, separator])
7676 Return the nth word from a string.
7677 Operators
7679 We provide a limited set of infix arithmetic operations on integers:
7680 + for addition
7682 - for subtraction
7683 * for multiplication
7684 / for floor division (division rounded to integer nearest -infinity)
7685 Division fulfills the law x = x / y + mod(x, y).
7687 Also, for any expression that returns a list, there is a list operator:
7689 expr % "{template}"
7691 As seen in the above example, {template} is interpreted as a template.
7693 To prevent it from being interpreted, you can use an escape character
7694 \{ or a raw string prefix, r'...'.
7695 The dot operator can be used as a shorthand for accessing a sub item:
7697 • expr.member is roughly equivalent to expr % '{member}' if expr re‐
7699 turns a non-list/dict. The returned value is not stringified.
7700 • dict.key is identical to get(dict, 'key').
7702 Aliases
7704 New keywords and functions can be defined in the templatealias section
7705 of a Mercurial configuration file:
7706 <alias> = <definition>
7708 Arguments of the form a1, a2, etc. are substituted from the alias into
7710 the definition.
7711 For example,
7713 [templatealias]
7715 r = rev
7716 rn = "{r}:{node|short}"
7717 leftpad(s, w) = pad(s, w, ' ', True)
7718 defines two symbol aliases, r and rn, and a function alias leftpad().
7720 It's also possible to specify complete template strings, using the tem‐
7722 plates section. The syntax used is the general template string syntax.
7723 For example,
7725 [templates]
7727 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
7728 defines a template, nodedate, which can be called like:
7730 $ hg log -r . -Tnodedate
7732 A template defined in templates section can also be referenced from an‐
7734 other template:
7735 $ hg log -r . -T "{rev} {nodedate}"
7737 but be aware that the keywords cannot be overridden by templates. For
7739 example, a template defined as templates.rev cannot be referenced as
7740 {rev}.
7741 A template defined in templates section may have sub templates which
7743 are inserted before/after/between items:
7744 [templates]
7746 myjson = ' {dict(rev, node|short)|json}'
7747 myjson:docheader = '\{\n'
7748 myjson:docfooter = '\n}\n'
7749 myjson:separator = ',\n'
7750 Examples
7752 Some sample command line templates:
7753 • Format lists, e.g. files:
7755 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
7757 • Join the list of files with a ", ":
7759 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
7761 • Join the list of files ending with ".py" with a ", ":
7763 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
7765 • Separate non-empty arguments by a " ":
7767 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
7769 • Modify each line of a commit description:
7771 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
7773 • Format date:
7775 $ hg log -r 0 --template "{date(date, '%Y')}\n"
7777 • Display date in UTC:
7779 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
7781 • Output the description set to a fill-width of 30:
7783 $ hg log -r 0 --template "{fill(desc, 30)}"
7785 • Use a conditional to test for the default branch:
7787 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
7789 'on branch {branch}')}\n"
7790 • Append a newline if not empty:
7792 $ hg tip --template "{if(author, '{author}\n')}"
7794 • Label the output for use with the color extension:
7796 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
7798 • Invert the firstline filter, i.e. everything but the first line:
7800 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
7802 • Display the contents of the 'extra' field, one per line:
7804 $ hg log -r 0 --template "{join(extras, '\n')}\n"
7806 • Mark the active bookmark with '*':
7808 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
7810 • Find the previous release candidate tag, the distance and changes
7812 since the tag:
7813 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
7815 • Mark the working copy parent with '@':
7817 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
7819 • Show details of parent revisions:
7821 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
7823 • Show only commit descriptions that start with "template":
7825 $ hg log --template "{startswith('template', firstline(desc))}\n"
7827 • Print the first word of each line of a commit message:
7829 $ hg log --template "{word(0, desc)}\n"
7831
7833 Valid URLs are of the form:
7834 local/filesystem/path[#revision]
7836 file://local/filesystem/path[#revision]
7837 http://[user[:pass]@]host[:port]/[path][#revision]
7838 https://[user[:pass]@]host[:port]/[path][#revision]
7839 ssh://[user@]host[:port]/[path][#revision]
7840 Paths in the local filesystem can either point to Mercurial reposito‐
7842 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
7843 dle). See also hg help paths.
7844 An optional identifier after # indicates a particular branch, tag, or
7846 changeset to use from the remote repository. See also hg help revisions
7847 .
7848 Some features, such as pushing to http:// and https:// URLs are only
7850 possible if the feature is explicitly enabled on the remote Mercurial
7851 server.
7852 Note that the security of HTTPS URLs depends on proper configuration of
7854 web.cacerts.
7855 Some notes about using SSH with Mercurial:
7857 • SSH requires an accessible shell account on the destination machine
7859 and a copy of hg in the remote path or specified with remotecmd.
7860 • path is relative to the remote user's home directory by default. Use
7862 an extra slash at the start of a path to specify an absolute path:
7863 ssh://example.com//tmp/repository
7865 • Mercurial doesn't use its own compression via SSH; the right thing to
7867 do is to configure it in your ~/.ssh/config, e.g.:
7868 Host *.mylocalnetwork.example.com
7870 Compression no
7871 Host *
7872 Compression yes
7873 Alternatively specify "ssh -C" as your ssh command in your configura‐
7875 tion file or with the --ssh command line option.
7876 These URLs can all be stored in your configuration file with path
7878 aliases under the [paths] section like so:
7879 [paths]
7881 alias1 = URL1
7882 alias2 = URL2
7883 ...
7884 You can then use the alias for any command that uses a URL (for example
7886 hg pull alias1 will be treated as hg pull URL1).
7887 Two path aliases are special because they are used as defaults when you
7889 do not provide the URL to a command:
7890 default:
7892 When you create a repository with hg clone, the clone command
7893 saves the location of the source repository as the new reposi‐
7894 tory's 'default' path. This is then used when you omit path from
7895 push- and pull-like commands (including incoming and outgoing).
7896 default-push:
7898 The push command will look for a path named 'default-push', and
7899 prefer it over 'default' if both are defined.
7900
7902 This section contains help for extensions that are distributed together
7903 with Mercurial. Help for other extensions is available in the help sys‐
7904 tem.
7905 absorb
7907 apply working directory changes to changesets (EXPERIMENTAL)
7908 The absorb extension provides a command to use annotate information to
7910 amend modified chunks into the corresponding non-public changesets.
7911 [absorb]
7913 # only check 50 recent non-public changesets at most
7914 max-stack-size = 50
7915 # whether to add noise to new commits to avoid obsolescence cycle
7916 add-noise = 1
7917 # make `amend --correlated` a shortcut to the main command
7918 amend-flag = correlated
7919 [color]
7921 absorb.description = yellow
7922 absorb.node = blue bold
7923 absorb.path = bold
7924 Commands
7926 Change creation
7927 absorb
7928 incorporate corrections into the stack of draft changesets:
7929 hg absorb [OPTION] [FILE]...
7931 absorb analyzes each change in your working directory and attempts to
7933 amend the changed lines into the changesets in your stack that first
7934 introduced those lines.
7935 If absorb cannot find an unambiguous changeset to amend for a change,
7937 that change will be left in the working directory, untouched. They can
7938 be observed by hg status or hg diff afterwards. In other words, absorb
7939 does not write to the working directory.
7940 Changesets outside the revset ::. and not public() and not merge() will
7942 not be changed.
7943 Changesets that become empty after applying the changes will be
7945 deleted.
7946 By default, absorb will show what it plans to do and prompt for confir‐
7948 mation. If you are confident that the changes will be absorbed to the
7949 correct place, run hg absorb -a to apply the changes immediately.
7950 Returns 0 on success, 1 if all chunks were ignored and nothing amended.
7952 Options:
7954 -a, --apply-changes
7956 apply changes without prompting for confirmation
7957 -p, --print-changes
7959 always print which changesets are modified by which changes
7960 -i, --interactive
7962 interactively select which chunks to apply
7963 -e, --edit-lines
7965 edit what lines belong to which changesets before commit (EXPER‐
7966 IMENTAL)
7967 -n, --dry-run
7969 do not perform actions, just print output
7970 --style <STYLE>
7972 display using template map file (DEPRECATED)
7973 -T,--template <TEMPLATE>
7975 display with template
7976 -I,--include <PATTERN[+]>
7978 include names matching the given patterns
7979 -X,--exclude <PATTERN[+]>
7981 exclude names matching the given patterns
7982 [+] marked option can be specified multiple times
7984 acl
7986 hooks for controlling repository access
7987 This hook makes it possible to allow or deny write access to given
7989 branches and paths of a repository when receiving incoming changesets
7990 via pretxnchangegroup and pretxncommit.
7991 The authorization is matched based on the local user name on the system
7993 where the hook runs, and not the committer of the original changeset
7994 (since the latter is merely informative).
7995 The acl hook is best used along with a restricted shell like hgsh, pre‐
7997 venting authenticating users from doing anything other than pushing or
7998 pulling. The hook is not safe to use if users have interactive shell
7999 access, as they can then disable the hook. Nor is it safe if remote
8000 users share an account, because then there is no way to distinguish
8001 them.
8002 The order in which access checks are performed is:
8004 1. Deny list for branches (section acl.deny.branches)
8006 2. Allow list for branches (section acl.allow.branches)
8008 3. Deny list for paths (section acl.deny)
8010 4. Allow list for paths (section acl.allow)
8012 The allow and deny sections take key-value pairs.
8014 Branch-based Access Control
8016 Use the acl.deny.branches and acl.allow.branches sections to have
8017 branch-based access control. Keys in these sections can be either:
8018 • a branch name, or
8020 • an asterisk, to match any branch;
8022 The corresponding values can be either:
8024 • a comma-separated list containing users and groups, or
8026 • an asterisk, to match anyone;
8028 You can add the "!" prefix to a user or group name to invert the sense
8030 of the match.
8031 Path-based Access Control
8033 Use the acl.deny and acl.allow sections to have path-based access con‐
8034 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
8035 tax by default). The corresponding values follow the same syntax as the
8036 other sections above.
8037 Bookmark-based Access Control
8039 Use the acl.deny.bookmarks and acl.allow.bookmarks sections to have
8040 bookmark-based access control. Keys in these sections can be either:
8041 • a bookmark name, or
8043 • an asterisk, to match any bookmark;
8045 The corresponding values can be either:
8047 • a comma-separated list containing users and groups, or
8049 • an asterisk, to match anyone;
8051 You can add the "!" prefix to a user or group name to invert the sense
8053 of the match.
8054 Note: for interactions between clients and servers using Mercurial 3.6+
8056 a rejection will generally reject the entire push, for interactions in‐
8057 volving older clients, the commit transactions will already be ac‐
8058 cepted, and only the bookmark movement will be rejected.
8059 Groups
8061 Group names must be prefixed with an @ symbol. Specifying a group name
8062 has the same effect as specifying all the users in that group.
8063 You can define group members in the acl.groups section. If a group
8065 name is not defined there, and Mercurial is running under a Unix-like
8066 system, the list of users will be taken from the OS. Otherwise, an ex‐
8067 ception will be raised.
8068 Example Configuration
8070 [hooks]
8071 # Use this if you want to check access restrictions at commit time
8073 pretxncommit.acl = python:hgext.acl.hook
8074 # Use this if you want to check access restrictions for pull, push,
8076 # bundle and serve.
8077 pretxnchangegroup.acl = python:hgext.acl.hook
8078 [acl]
8080 # Allow or deny access for incoming changes only if their source is
8081 # listed here, let them pass otherwise. Source is "serve" for all
8082 # remote access (http or ssh), "push", "pull" or "bundle" when the
8083 # related commands are run locally.
8084 # Default: serve
8085 sources = serve
8086 [acl.deny.branches]
8088 # Everyone is denied to the frozen branch:
8090 frozen-branch = *
8091 # A bad user is denied on all branches:
8093 * = bad-user
8094 [acl.allow.branches]
8096 # A few users are allowed on branch-a:
8098 branch-a = user-1, user-2, user-3
8099 # Only one user is allowed on branch-b:
8101 branch-b = user-1
8102 # The super user is allowed on any branch:
8104 * = super-user
8105 # Everyone is allowed on branch-for-tests:
8107 branch-for-tests = *
8108 [acl.deny]
8110 # This list is checked first. If a match is found, acl.allow is not
8111 # checked. All users are granted access if acl.deny is not present.
8112 # Format for both lists: glob pattern = user, ..., @group, ...
8113 # To match everyone, use an asterisk for the user:
8115 # my/glob/pattern = *
8116 # user6 will not have write access to any file:
8118 ** = user6
8119 # Group "hg-denied" will not have write access to any file:
8121 ** = @hg-denied
8122 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
8124 # everyone being able to change all other files. See below.
8125 src/main/resources/DONT-TOUCH-THIS.txt = *
8126 [acl.allow]
8128 # if acl.allow is not present, all users are allowed by default
8129 # empty acl.allow = no users allowed
8130 # User "doc_writer" has write access to any file under the "docs"
8132 # folder:
8133 docs/** = doc_writer
8134 # User "jack" and group "designers" have write access to any file
8136 # under the "images" folder:
8137 images/** = jack, @designers
8138 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
8140 # will have write access to any file under the "resources" folder
8141 # (except for 1 file. See acl.deny):
8142 src/main/resources/** = *
8143 .hgtags = release_engineer
8145 Examples using the ! prefix
8147 Suppose there's a branch that only a given user (or group) should be
8148 able to push to, and you don't want to restrict access to any other
8149 branch that may be created.
8150 The "!" prefix allows you to prevent anyone except a given user or
8152 group to push changesets in a given branch or path.
8153 In the examples below, we will: 1) Deny access to branch "ring" to any‐
8155 one but user "gollum" 2) Deny access to branch "lake" to anyone but
8156 members of the group "hobbit" 3) Deny access to a file to anyone but
8157 user "gollum"
8158 [acl.allow.branches]
8160 # Empty
8161 [acl.deny.branches]
8163 # 1) only 'gollum' can commit to branch 'ring';
8165 # 'gollum' and anyone else can still commit to any other branch.
8166 ring = !gollum
8167 # 2) only members of the group 'hobbit' can commit to branch 'lake';
8169 # 'hobbit' members and anyone else can still commit to any other branch.
8170 lake = !@hobbit
8171 # You can also deny access based on file paths:
8173 [acl.allow]
8175 # Empty
8176 [acl.deny]
8178 # 3) only 'gollum' can change the file below;
8179 # 'gollum' and anyone else can still change any other file.
8180 /misty/mountains/cave/ring = !gollum
8181 amend
8183 provide the amend command (EXPERIMENTAL)
8184 This extension provides an amend command that is similar to commit
8186 --amend but does not prompt an editor.
8187 Commands
8189 Change creation
8190 amend
8191 amend the working copy parent with all or specified outstanding
8192 changes:
8193 hg amend [OPTION]... [FILE]...
8195 Similar to hg commit --amend, but reuse the commit message without in‐
8197 voking editor, unless --edit was set.
8198 See hg help commit for more details.
8200 Options:
8202 -A, --addremove
8204 mark new/missing files as added/removed before committing
8205 -e, --edit
8207 invoke editor on commit messages
8208 -i, --interactive
8210 use interactive mode
8211 --close-branch
8213 mark a branch as closed, hiding it from the branch list
8214 -s, --secret
8216 use the secret phase for committing
8217 -n,--note <VALUE>
8219 store a note on the amend
8220 -I,--include <PATTERN[+]>
8222 include names matching the given patterns
8223 -X,--exclude <PATTERN[+]>
8225 exclude names matching the given patterns
8226 -m,--message <TEXT>
8228 use text as commit message
8229 -l,--logfile <FILE>
8231 read commit message from file
8232 -d,--date <DATE>
8234 record the specified date as commit date
8235 -u,--user <USER>
8237 record the specified user as committer
8238 -D, --currentdate
8240 record the current date as commit date
8241 -U, --currentuser
8243 record the current user as committer
8244 [+] marked option can be specified multiple times
8246 automv
8248 check for unrecorded moves at commit time (EXPERIMENTAL)
8249 This extension checks at commit/amend time if any of the committed
8251 files comes from an unrecorded mv.
8252 The threshold at which a file is considered a move can be set with the
8254 automv.similarity config option. This option takes a percentage between
8255 0 (disabled) and 100 (files must be identical), the default is 95.
8256 beautifygraph
8258 beautify log -G output by using Unicode characters (EXPERIMENTAL)
8259 A terminal with UTF-8 support and monospace narrow text are re‐
8261 quired.
8262 blackbox
8264 log repository events to a blackbox for debugging
8265 Logs event information to .hg/blackbox.log to help debug and diagnose
8267 problems. The events that get logged can be configured via the black‐
8268 box.track and blackbox.ignore config keys.
8269 Examples:
8271 [blackbox]
8273 track = *
8274 ignore = pythonhook
8275 # dirty is *EXPENSIVE* (slow);
8276 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
8277 dirty = True
8278 # record the source of log messages
8279 logsource = True
8280 [blackbox]
8282 track = command, commandfinish, commandexception, exthook, pythonhook
8283 [blackbox]
8285 track = incoming
8286 [blackbox]
8288 # limit the size of a log file
8289 maxsize = 1.5 MB
8290 # rotate up to N log files when the current one gets too big
8291 maxfiles = 3
8292 [blackbox]
8294 # Include nanoseconds in log entries with %f (see Python function
8295 # datetime.datetime.strftime)
8296 date-format = '%Y-%m-%d @ %H:%M:%S.%f'
8297 Commands
8299 Repository maintenance
8300 blackbox
8301 view the recent repository events:
8302 hg blackbox [OPTION]...
8304 view the recent repository events
8306 Options:
8308 -l,--limit <VALUE>
8310 the number of events to show (default: 10)
8311 bookflow
8313 implements bookmark-based branching (EXPERIMENTAL)
8314 • Disables creation of new branches (config: enable_branches=False).
8316 • Requires an active bookmark on commit (config: require_book‐
8318 mark=True).
8319 • Doesn't move the active bookmark on update, only on commit.
8321 • Requires '--rev' for moving an existing bookmark.
8323 • Protects special bookmarks (config: protect=@).
8325 flow related commands
8327 hg book NAME
8329 create a new bookmark
8330 hg book NAME -r REV
8332 move bookmark to revision (fast-forward)
8333 hg up|co NAME
8335 switch to bookmark
8336 hg push -B .
8338 push active bookmark
8339 bugzilla
8341 hooks for integrating with the Bugzilla bug tracker
8342 This hook extension adds comments on bugs in Bugzilla when changesets
8344 that refer to bugs by Bugzilla ID are seen. The comment is formatted
8345 using the Mercurial template mechanism.
8346 The bug references can optionally include an update for Bugzilla of the
8348 hours spent working on the bug. Bugs can also be marked fixed.
8349 Four basic modes of access to Bugzilla are provided:
8351 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
8353 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
8355 later.
8356 3. Check data via the Bugzilla XMLRPC interface and submit bug change
8358 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
8359 later.
8360 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
8362 tions using MySQL are supported. Requires Python MySQLdb.
8363 Writing directly to the database is susceptible to schema changes, and
8365 relies on a Bugzilla contrib script to send out bug change notification
8366 emails. This script runs as the user running Mercurial, must be run on
8367 the host with the Bugzilla install, and requires permission to read
8368 Bugzilla configuration details and the necessary MySQL user and pass‐
8369 word to have full access rights to the Bugzilla database. For these
8370 reasons this access mode is now considered deprecated, and will not be
8371 updated for new Bugzilla versions going forward. Only adding comments
8372 is supported in this access mode.
8373 Access via XMLRPC needs a Bugzilla username and password to be speci‐
8375 fied in the configuration. Comments are added under that username.
8376 Since the configuration must be readable by all Mercurial users, it is
8377 recommended that the rights of that user are restricted in Bugzilla to
8378 the minimum necessary to add comments. Marking bugs fixed requires
8379 Bugzilla 4.0 and later.
8380 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
8382 to the Bugzilla email interface to submit comments to bugs. The From:
8383 address in the email is set to the email address of the Mercurial user,
8384 so the comment appears to come from the Mercurial user. In the event
8385 that the Mercurial user email is not recognized by Bugzilla as a
8386 Bugzilla user, the email associated with the Bugzilla username used to
8387 log into Bugzilla is used instead as the source of the comment. Marking
8388 bugs fixed works on all supported Bugzilla versions.
8389 Access via the REST-API needs either a Bugzilla username and password
8391 or an apikey specified in the configuration. Comments are made under
8392 the given username or the user associated with the apikey in Bugzilla.
8393 Configuration items common to all access modes:
8395 bugzilla.version
8397 The access type to use. Values recognized are:
8398 restapi
8400 Bugzilla REST-API, Bugzilla 5.0 and later.
8402 xmlrpc
8404 Bugzilla XMLRPC interface.
8406 xmlrpc+email
8408 Bugzilla XMLRPC and email interfaces.
8410 3.0
8412 MySQL access, Bugzilla 3.0 and later.
8414 2.18
8416 MySQL access, Bugzilla 2.18 and up to but not including
8418 3.0.
8419 2.16
8421 MySQL access, Bugzilla 2.16 and up to but not including
8423 2.18.
8424 bugzilla.regexp
8426 Regular expression to match bug IDs for update in changeset com‐
8427 mit message. It must contain one "()" named group <ids> con‐
8428 taining the bug IDs separated by non-digit characters. It may
8429 also contain a named group <hours> with a floating-point number
8430 giving the hours worked on the bug. If no named groups are
8431 present, the first "()" group is assumed to contain the bug IDs,
8432 and work time is not updated. The default expression matches Bug
8433 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
8434 and 5678 and variations thereof, followed by an hours number
8435 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
8436 sitive.
8437 bugzilla.fixregexp
8439 Regular expression to match bug IDs for marking fixed in change‐
8440 set commit message. This must contain a "()" named group <ids>`
8441 containing the bug IDs separated by non-digit characters. It may
8442 also contain a named group ``<hours> with a floating-point num‐
8443 ber giving the hours worked on the bug. If no named groups are
8444 present, the first "()" group is assumed to contain the bug IDs,
8445 and work time is not updated. The default expression matches
8446 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
8447 5678 and variations thereof, followed by an hours number pre‐
8448 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
8449 tive.
8450 bugzilla.fixstatus
8452 The status to set a bug to when marking fixed. Default RESOLVED.
8453 bugzilla.fixresolution
8455 The resolution to set a bug to when marking fixed. Default
8456 FIXED.
8457 bugzilla.style
8459 The style file to use when formatting comments.
8460 bugzilla.template
8462 Template to use when formatting comments. Overrides style if
8463 specified. In addition to the usual Mercurial keywords, the ex‐
8464 tension specifies:
8465 {bug}
8467 The Bugzilla bug ID.
8469 {root}
8471 The full pathname of the Mercurial repository.
8473 {webroot}
8475 Stripped pathname of the Mercurial repository.
8477 {hgweb}
8479 Base URL for browsing Mercurial repositories.
8481 Default changeset {node|short} in repo {root} refers to bug
8483 {bug}.\ndetails:\n\t{desc|tabindent}
8484 bugzilla.strip
8486 The number of path separator characters to strip from the front
8487 of the Mercurial repository path ({root} in templates) to pro‐
8488 duce {webroot}. For example, a repository with {root} /var/lo‐
8489 cal/my-project with a strip of 2 gives a value for {webroot} of
8490 my-project. Default 0.
8491 web.baseurl
8493 Base URL for browsing Mercurial repositories. Referenced from
8494 templates as {hgweb}.
8495 Configuration items common to XMLRPC+email and MySQL access modes:
8497 bugzilla.usermap
8499 Path of file containing Mercurial committer email to Bugzilla
8500 user email mappings. If specified, the file should contain one
8501 mapping per line:
8502 committer = Bugzilla user
8504 See also the [usermap] section.
8506 The [usermap] section is used to specify mappings of Mercurial commit‐
8508 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
8509 entries of the form committer = Bugzilla user.
8510 XMLRPC and REST-API access mode configuration:
8512 bugzilla.bzurl
8514 The base URL for the Bugzilla installation. Default http://lo‐
8515 calhost/bugzilla.
8516 bugzilla.user
8518 The username to use to log into Bugzilla via XMLRPC. Default
8519 bugs.
8520 bugzilla.password
8522 The password for Bugzilla login.
8523 REST-API access mode uses the options listed above as well as:
8525 bugzilla.apikey
8527 An apikey generated on the Bugzilla instance for api access.
8528 Using an apikey removes the need to store the user and password
8529 options.
8530 XMLRPC+email access mode uses the XMLRPC access mode configuration
8532 items, and also:
8533 bugzilla.bzemail
8535 The Bugzilla email address.
8536 In addition, the Mercurial email settings must be configured. See the
8538 documentation in hgrc(5), sections [email] and [smtp].
8539 MySQL access mode configuration:
8541 bugzilla.host
8543 Hostname of the MySQL server holding the Bugzilla database. De‐
8544 fault localhost.
8545 bugzilla.db
8547 Name of the Bugzilla database in MySQL. Default bugs.
8548 bugzilla.user
8550 Username to use to access MySQL server. Default bugs.
8551 bugzilla.password
8553 Password to use to access MySQL server.
8554 bugzilla.timeout
8556 Database connection timeout (seconds). Default 5.
8557 bugzilla.bzuser
8559 Fallback Bugzilla user name to record comments with, if change‐
8560 set committer cannot be found as a Bugzilla user.
8561 bugzilla.bzdir
8563 Bugzilla install directory. Used by default notify. Default
8564 /var/www/html/bugzilla.
8565 bugzilla.notify
8567 The command to run to get Bugzilla to send bug change notifica‐
8568 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
8569 id) and user (committer bugzilla email). Default depends on ver‐
8570 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
8571 mail.pl %(id)s %(user)s".
8572 Activating the extension:
8574 [extensions]
8576 bugzilla =
8577 [hooks]
8579 # run bugzilla hook on every change pulled or pushed in here
8580 incoming.bugzilla = python:hgext.bugzilla.hook
8581 Example configurations:
8583 XMLRPC example configuration. This uses the Bugzilla at
8585 http://my-project.org/bugzilla, logging in as user bug‐
8586 mail@my-project.org with password plugh. It is used with a collection
8587 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8588 at http://my-project.org/hg.
8589 [bugzilla]
8591 bzurl=http://my-project.org/bugzilla
8592 user=bugmail@my-project.org
8593 password=plugh
8594 version=xmlrpc
8595 template=Changeset {node|short} in {root|basename}.
8596 {hgweb}/{webroot}/rev/{node|short}\n
8597 {desc}\n
8598 strip=5
8599 [web]
8601 baseurl=http://my-project.org/hg
8602 XMLRPC+email example configuration. This uses the Bugzilla at
8604 http://my-project.org/bugzilla, logging in as user bug‐
8605 mail@my-project.org with password plugh. It is used with a collection
8606 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8607 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
8608 email address bugzilla@my-project.org.
8609 [bugzilla]
8611 bzurl=http://my-project.org/bugzilla
8612 user=bugmail@my-project.org
8613 password=plugh
8614 version=xmlrpc+email
8615 bzemail=bugzilla@my-project.org
8616 template=Changeset {node|short} in {root|basename}.
8617 {hgweb}/{webroot}/rev/{node|short}\n
8618 {desc}\n
8619 strip=5
8620 [web]
8622 baseurl=http://my-project.org/hg
8623 [usermap]
8625 user@emaildomain.com=user.name@bugzilladomain.com
8626 MySQL example configuration. This has a local Bugzilla 3.2 installation
8628 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
8629 database name is bugs and MySQL is accessed with MySQL username bugs
8630 password XYZZY. It is used with a collection of Mercurial repositories
8631 in /var/local/hg/repos/, with a web interface at
8632 http://my-project.org/hg.
8633 [bugzilla]
8635 host=localhost
8636 password=XYZZY
8637 version=3.0
8638 bzuser=unknown@domain.com
8639 bzdir=/opt/bugzilla-3.2
8640 template=Changeset {node|short} in {root|basename}.
8641 {hgweb}/{webroot}/rev/{node|short}\n
8642 {desc}\n
8643 strip=5
8644 [web]
8646 baseurl=http://my-project.org/hg
8647 [usermap]
8649 user@emaildomain.com=user.name@bugzilladomain.com
8650 All the above add a comment to the Bugzilla bug record of the form:
8652 Changeset 3b16791d6642 in repository-name.
8654 http://my-project.org/hg/repository-name/rev/3b16791d6642
8655 Changeset commit comment. Bug 1234.
8657 censor
8659 erase file content at a given revision
8660 The censor command instructs Mercurial to erase all content of a file
8662 at a given revision without updating the changeset hash. This allows
8663 existing history to remain valid while preventing future clones/pulls
8664 from receiving the erased data.
8665 Typical uses for censor are due to security or legal requirements, in‐
8667 cluding:
8668 * Passwords, private keys, cryptographic material
8670 * Licensed data/code/libraries for which the license has expired
8671 * Personally Identifiable Information or other private data
8672 Censored nodes can interrupt mercurial's typical operation whenever the
8674 excised data needs to be materialized. Some commands, like hg cat/hg
8675 revert, simply fail when asked to produce censored data. Others, like
8676 hg verify and hg update, must be capable of tolerating censored data to
8677 continue to function in a meaningful way. Such commands only tolerate
8678 censored file revisions if they are allowed by the "censor.policy=ig‐
8679 nore" config option.
8680 A few informative commands such as hg grep will unconditionally ignore
8682 censored data and merely report that it was encountered.
8683 Commands
8685 Repository maintenance
8686 censor
8687 hg censor -r REV [-t TEXT] [FILE]
8688 Options:
8690 -r,--rev <REV>
8692 censor file from specified revision
8693 -t,--tombstone <TEXT>
8695 replacement tombstone data
8696 children
8698 command to display child changesets (DEPRECATED)
8699 This extension is deprecated. You should use hg log -r "children(REV)"
8701 instead.
8702 Commands
8704 Change navigation
8705 children
8706 show the children of the given or working directory revision:
8707 hg children [-r REV] [FILE]
8709 Print the children of the working directory's revisions. If a revision
8711 is given via -r/--rev, the children of that revision will be printed.
8712 If a file argument is given, revision in which the file was last
8713 changed (after the working directory revision or the argument to --rev
8714 if given) is printed.
8715 Please use hg log instead:
8717 hg children => hg log -r "children(.)"
8719 hg children -r REV => hg log -r "children(REV)"
8720 See hg help log and hg help revsets.children.
8722 Options:
8724 -r,--rev <REV>
8726 show children of the specified revision (default: .)
8727 --style <STYLE>
8729 display using template map file (DEPRECATED)
8730 -T,--template <TEMPLATE>
8732 display with template
8733 churn
8735 command to display statistics about repository history
8736 Commands
8738 Repository maintenance
8739 churn
8740 histogram of changes to the repository:
8741 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
8743 This command will display a histogram representing the number of
8745 changed lines or revisions, grouped according to the given template.
8746 The default template will group changes by author. The --dateformat
8747 option may be used to group the results by date instead.
8748 Statistics are based on the number of changed lines, or alternatively
8750 the number of matching revisions if the --changesets option is speci‐
8751 fied.
8752 Examples:
8754 # display count of changed lines for every committer
8756 hg churn -T "{author|email}"
8757 # display daily activity graph
8759 hg churn -f "%H" -s -c
8760 # display activity of developers by month
8762 hg churn -f "%Y-%m" -s -c
8763 # display count of lines changed in every year
8765 hg churn -f "%Y" -s
8766 # display count of lines changed in a time range
8768 hg churn -d "2020-04 to 2020-09"
8769 It is possible to map alternate email addresses to a main address by
8771 providing a file using the following format:
8772 <alias email> = <actual email>
8774 Such a file may be specified with the --aliases option, otherwise a
8776 .hgchurn file will be looked for in the working directory root.
8777 Aliases will be split from the rightmost "=".
8778 Options:
8780 -r,--rev <REV[+]>
8782 count rate for the specified revision or revset
8783 -d,--date <DATE>
8785 count rate for revisions matching date spec
8786 -t,--oldtemplate <TEMPLATE>
8788 template to group changesets (DEPRECATED)
8789 -T,--template <TEMPLATE>
8791 template to group changesets (default: {author|email})
8792 -f,--dateformat <FORMAT>
8794 strftime-compatible format for grouping by date
8795 -c, --changesets
8797 count rate by number of changesets
8798 -s, --sort
8800 sort by key (default: sort by count)
8801 --diffstat
8803 display added/removed lines separately
8804 --aliases <FILE>
8806 file with email aliases
8807 -I,--include <PATTERN[+]>
8809 include names matching the given patterns
8810 -X,--exclude <PATTERN[+]>
8812 exclude names matching the given patterns
8813 [+] marked option can be specified multiple times
8815 clonebundles
8817 advertise pre-generated bundles to seed clones
8818 "clonebundles" is a server-side extension used to advertise the exis‐
8820 tence of pre-generated, externally hosted bundle files to clients that
8821 are cloning so that cloning can be faster, more reliable, and require
8822 less resources on the server. "pullbundles" is a related feature for
8823 sending pre-generated bundle files to clients as part of pull opera‐
8824 tions.
8825 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
8827 ally, the server, in response to a client's request to clone, dynami‐
8828 cally generates a bundle containing the entire repository content and
8829 sends it to the client. There is no caching on the server and the
8830 server will have to redundantly generate the same outgoing bundle in
8831 response to each clone request. For servers with large repositories or
8832 with high clone volume, the load from clones can make scaling the
8833 server challenging and costly.
8834 This extension provides server operators the ability to offload poten‐
8836 tially expensive clone load to an external service. Pre-generated bun‐
8837 dles also allow using more CPU intensive compression, reducing the ef‐
8838 fective bandwidth requirements.
8839 Here's how clone bundles work:
8841 1. A server operator establishes a mechanism for making bundle files
8843 available on a hosting service where Mercurial clients can fetch
8844 them.
8845 2. A manifest file listing available bundle URLs and some optional
8847 metadata is added to the Mercurial repository on the server.
8848 3. A client initiates a clone against a clone bundles aware server.
8850 4. The client sees the server is advertising clone bundles and fetches
8852 the manifest listing available bundles.
8853 5. The client filters and sorts the available bundles based on what it
8855 supports and prefers.
8856 6. The client downloads and applies an available bundle from the
8858 server-specified URL.
8859 7. The client reconnects to the original server and performs the equiv‐
8861 alent of hg pull to retrieve all repository data not in the bundle.
8862 (The repository could have been updated between when the bundle was
8863 created and when the client started the clone.) This may use "pull‐
8864 bundles".
8865 Instead of the server generating full repository bundles for every
8867 clone request, it generates full bundles once and they are subsequently
8868 reused to bootstrap new clones. The server may still transfer data at
8869 clone time. However, this is only data that has been added/changed
8870 since the bundle was created. For large, established repositories, this
8871 can reduce server load for clones to less than 1% of original.
8872 Here's how pullbundles work:
8874 1. A manifest file listing available bundles and describing the revi‐
8876 sions is added to the Mercurial repository on the server.
8877 2. A new-enough client informs the server that it supports partial
8879 pulls and initiates a pull.
8880 3. If the server has pull bundles enabled and sees the client advertis‐
8882 ing partial pulls, it checks for a matching pull bundle in the mani‐
8883 fest. A bundle matches if the format is supported by the client,
8884 the client has the required revisions already and needs something
8885 from the bundle.
8886 4. If there is at least one matching bundle, the server sends it to the
8888 client.
8889 5. The client applies the bundle and notices that the server reply was
8891 incomplete. It initiates another pull.
8892 To work, this extension requires the following of server operators:
8894 • Generating bundle files of repository content (typically periodi‐
8896 cally, such as once per day).
8897 • Clone bundles: A file server that clients have network access to and
8899 that Python knows how to talk to through its normal URL handling fa‐
8900 cility (typically an HTTP/HTTPS server).
8901 • A process for keeping the bundles manifest in sync with available
8903 bundle files.
8904 Strictly speaking, using a static file hosting server isn't required: a
8906 server operator could use a dynamic service for retrieving bundle data.
8907 However, static file hosting services are simple and scalable and
8908 should be sufficient for most needs.
8909 Bundle files can be generated with the hg bundle command. Typically hg
8911 bundle --all is used to produce a bundle of the entire repository.
8912 hg debugcreatestreamclonebundle can be used to produce a special
8914 streaming clonebundle. These are bundle files that are extremely effi‐
8915 cient to produce and consume (read: fast). However, they are larger
8916 than traditional bundle formats and require that clients support the
8917 exact set of repository data store formats in use by the repository
8918 that created them. Typically, a newer server can serve data that is
8919 compatible with older clients. However, streaming clone bundles don't
8920 have this guarantee. Server operators need to be aware that newer ver‐
8921 sions of Mercurial may produce streaming clone bundles incompatible
8922 with older Mercurial versions.
8923 A server operator is responsible for creating a .hg/clonebundles.mani‐
8925 fest file containing the list of available bundle files suitable for
8926 seeding clones. If this file does not exist, the repository will not
8927 advertise the existence of clone bundles when clients connect. For pull
8928 bundles, .hg/pullbundles.manifest is used.
8929 The manifest file contains a newline (n) delimited list of entries.
8931 Each line in this file defines an available bundle. Lines have the for‐
8933 mat:
8934 <URL> [<key>=<value>[ <key>=<value>]]
8936 That is, a URL followed by an optional, space-delimited list of
8938 key=value pairs describing additional properties of this bundle. Both
8939 keys and values are URI encoded.
8940 For pull bundles, the URL is a path under the .hg directory of the
8942 repository.
8943 Keys in UPPERCASE are reserved for use by Mercurial and are defined be‐
8945 low. All non-uppercase keys can be used by site installations. An ex‐
8946 ample use for custom properties is to use the datacenter attribute to
8947 define which data center a file is hosted in. Clients could then prefer
8948 a server in the data center closest to them.
8949 The following reserved keys are currently defined:
8951 BUNDLESPEC
8953 A "bundle specification" string that describes the type of the
8954 bundle.
8955 These are string values that are accepted by the "--type" argu‐
8957 ment of hg bundle.
8958 The values are parsed in strict mode, which means they must be
8960 of the "<compression>-<type>" form. See mercurial.ex‐
8961 change.parsebundlespec() for more details.
8962 hg debugbundle --spec can be used to print the bundle specifica‐
8964 tion string for a bundle file. The output of this command can be
8965 used verbatim for the value of BUNDLESPEC (it is already es‐
8966 caped).
8967 Clients will automatically filter out specifications that are
8969 unknown or unsupported so they won't attempt to download some‐
8970 thing that likely won't apply.
8971 The actual value doesn't impact client behavior beyond filter‐
8973 ing: clients will still sniff the bundle type from the header of
8974 downloaded files.
8975 Use of this key is highly recommended, as it allows clients to
8977 easily skip unsupported bundles. If this key is not defined, an
8978 old client may attempt to apply a bundle that it is incapable of
8979 reading.
8980 REQUIRESNI
8982 Whether Server Name Indication (SNI) is required to connect to
8983 the URL. SNI allows servers to use multiple certificates on the
8984 same IP. It is somewhat common in CDNs and other hosting
8985 providers. Older Python versions do not support SNI. Defining
8986 this attribute enables clients with older Python versions to
8987 filter this entry without experiencing an opaque SSL failure at
8988 connection time.
8989 If this is defined, it is important to advertise a non-SNI fall‐
8991 back URL or clients running old Python releases may not be able
8992 to clone with the clonebundles facility.
8993 Value should be "true".
8995 REQUIREDRAM
8997 Value specifies expected memory requirements to decode the pay‐
8998 load. Values can have suffixes for common bytes sizes. e.g.
8999 "64MB".
9000 This key is often used with zstd-compressed bundles using a high
9002 compression level / window size, which can require 100+ MB of
9003 memory to decode.
9004 heads Used for pull bundles. This contains the ; separated changeset
9006 hashes of the heads of the bundle content.
9007 bases Used for pull bundles. This contains the ; separated changeset
9009 hashes of the roots of the bundle content. This can be skipped
9010 if the bundle was created without --base.
9011 Manifests can contain multiple entries. Assuming metadata is defined,
9013 clients will filter entries from the manifest that they don't support.
9014 The remaining entries are optionally sorted by client preferences
9015 (ui.clonebundleprefers config option). The client then attempts to
9016 fetch the bundle at the first URL in the remaining list.
9017 Errors when downloading a bundle will fail the entire clone operation:
9019 clients do not automatically fall back to a traditional clone. The rea‐
9020 son for this is that if a server is using clone bundles, it is probably
9021 doing so because the feature is necessary to help it scale. In other
9022 words, there is an assumption that clone load will be offloaded to an‐
9023 other service and that the Mercurial server isn't responsible for serv‐
9024 ing this clone load. If that other service experiences issues and
9025 clients start mass falling back to the original Mercurial server, the
9026 added clone load could overwhelm the server due to unexpected load and
9027 effectively take it offline. Not having clients automatically fall back
9028 to cloning from the original server mitigates this scenario.
9029 Because there is no automatic Mercurial server fallback on failure of
9031 the bundle hosting service, it is important for server operators to
9032 view the bundle hosting service as an extension of the Mercurial server
9033 in terms of availability and service level agreements: if the bundle
9034 hosting service goes down, so does the ability for clients to clone.
9035 Note: clients will see a message informing them how to bypass the clone
9036 bundles facility when a failure occurs. So server operators should pre‐
9037 pare for some people to follow these instructions when a failure oc‐
9038 curs, thus driving more load to the original Mercurial server when the
9039 bundle hosting service fails.
9040 closehead
9042 close arbitrary heads without checking them out first
9043 Commands
9045 Change manipulation
9046 close-head
9047 close the given head revisions:
9048 hg close-head [OPTION]... [REV]...
9050 This is equivalent to checking out each revision in a clean tree and
9052 running hg commit --close-branch, except that it doesn't change the
9053 working directory.
9054 The commit message must be specified with -l or -m.
9056 Options:
9058 -m,--message <TEXT>
9060 use text as commit message
9061 -l,--logfile <FILE>
9063 read commit message from file
9064 -d,--date <DATE>
9066 record the specified date as commit date
9067 -u,--user <USER>
9069 record the specified user as committer
9070 -r,--rev <REV[+]>
9072 revision to check
9073 [+] marked option can be specified multiple times
9075 aliases: close-heads
9077 commitextras
9079 adds a new flag extras to commit (ADVANCED)
9080 convert
9082 import revisions from foreign VCS repositories into Mercurial
9083 Commands
9085 Uncategorized commands
9086 convert
9087 convert a foreign SCM repository to a Mercurial one.:
9088 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
9090 Accepted source formats [identifiers]:
9092 • Mercurial [hg]
9094 • CVS [cvs]
9096 • Darcs [darcs]
9098 • git [git]
9100 • Subversion [svn]
9102 • Monotone [mtn]
9104 • GNU Arch [gnuarch]
9106 • Bazaar [bzr]
9108 • Perforce [p4]
9110 Accepted destination formats [identifiers]:
9112 • Mercurial [hg]
9114 • Subversion [svn] (history on branches is not preserved)
9116 If no revision is given, all revisions will be converted. Otherwise,
9118 convert will only import up to the named revision (given in a format
9119 understood by the source).
9120 If no destination directory name is specified, it defaults to the base‐
9122 name of the source with -hg appended. If the destination repository
9123 doesn't exist, it will be created.
9124 By default, all sources except Mercurial will use --branchsort. Mercu‐
9126 rial uses --sourcesort to preserve original revision numbers order.
9127 Sort modes have the following effects:
9128 --branchsort
9130 convert from parent to child revision when possible, which means
9131 branches are usually converted one after the other. It generates
9132 more compact repositories.
9133 --datesort
9135 sort revisions by date. Converted repositories have good-looking
9136 changelogs but are often an order of magnitude larger than the
9137 same ones generated by --branchsort.
9138 --sourcesort
9140 try to preserve source revisions order, only supported by Mercu‐
9141 rial sources.
9142 --closesort
9144 try to move closed revisions as close as possible to parent
9145 branches, only supported by Mercurial sources.
9146 If REVMAP isn't given, it will be put in a default location
9148 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
9149 maps each source commit ID to the destination ID for that revision,
9150 like so:
9151 <source ID> <destination ID>
9153 If the file doesn't exist, it's automatically created. It's updated on
9155 each commit copied, so hg convert can be interrupted and can be run re‐
9156 peatedly to copy new commits.
9157 The authormap is a simple text file that maps each source commit author
9159 to a destination commit author. It is handy for source SCMs that use
9160 unix logins to identify authors (e.g.: CVS). One line per author map‐
9161 ping and the line format is:
9162 source author = destination author
9164 Empty lines and lines starting with a # are ignored.
9166 The filemap is a file that allows filtering and remapping of files and
9168 directories. Each line can contain one of the following directives:
9169 include path/to/file-or-dir
9171 exclude path/to/file-or-dir
9173 rename path/to/source path/to/destination
9175 Comment lines start with #. A specified path matches if it equals the
9177 full relative name of a file or one of its parent directories. The in‐
9178 clude or exclude directive with the longest matching path applies, so
9179 line order does not matter.
9180 The include directive causes a file, or all files under a directory, to
9182 be included in the destination repository. The default if there are no
9183 include statements is to include everything. If there are any include
9184 statements, nothing else is included. The exclude directive causes
9185 files or directories to be omitted. The rename directive renames a file
9186 or directory if it is converted. To rename from a subdirectory into the
9187 root of the repository, use . as the path to rename to.
9188 --full will make sure the converted changesets contain exactly the
9190 right files with the right content. It will make a full conversion of
9191 all files, not just the ones that have changed. Files that already are
9192 correct will not be changed. This can be used to apply filemap changes
9193 when converting incrementally. This is currently only supported for
9194 Mercurial and Subversion.
9195 The splicemap is a file that allows insertion of synthetic history,
9197 letting you specify the parents of a revision. This is useful if you
9198 want to e.g. give a Subversion merge two parents, or graft two discon‐
9199 nected series of history together. Each entry contains a key, followed
9200 by a space, followed by one or two comma-separated values:
9201 key parent1, parent2
9203 The key is the revision ID in the source revision control system whose
9205 parents should be modified (same format as a key in .hg/shamap). The
9206 values are the revision IDs (in either the source or destination revi‐
9207 sion control system) that should be used as the new parents for that
9208 node. For example, if you have merged "release-1.0" into "trunk", then
9209 you should specify the revision on "trunk" as the first parent and the
9210 one on the "release-1.0" branch as the second.
9211 The branchmap is a file that allows you to rename a branch when it is
9213 being brought in from whatever external repository. When used in con‐
9214 junction with a splicemap, it allows for a powerful combination to help
9215 fix even the most badly mismanaged repositories and turn them into
9216 nicely structured Mercurial repositories. The branchmap contains lines
9217 of the form:
9218 original_branch_name new_branch_name
9220 where "original_branch_name" is the name of the branch in the source
9222 repository, and "new_branch_name" is the name of the branch is the des‐
9223 tination repository. No whitespace is allowed in the new branch name.
9224 This can be used to (for instance) move code in one repository from
9225 "default" to a named branch.
9226 Mercurial Source
9228 The Mercurial source recognizes the following configuration options,
9229 which you can set on the command line with --config:
9230 convert.hg.ignoreerrors
9232 ignore integrity errors when reading. Use it to fix Mercurial
9233 repositories with missing revlogs, by converting from and to
9234 Mercurial. Default is False.
9235 convert.hg.saverev
9237 store original revision ID in changeset (forces target IDs to
9238 change). It takes a boolean argument and defaults to False.
9239 convert.hg.startrev
9241 specify the initial Mercurial revision. The default is 0.
9242 convert.hg.revs
9244 revset specifying the source revisions to convert.
9245 Bazaar Source
9247 The following options can be used with --config:
9248 convert.bzr.saverev
9250 whether to store the original Bazaar commit ID in the metadata
9251 of the destination commit. The default is True.
9252 CVS Source
9254 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to in‐
9255 dicate the starting point of what will be converted. Direct access to
9256 the repository files is not needed, unless of course the repository is
9257 :local:. The conversion uses the top level directory in the sandbox to
9258 find the CVS repository, and then uses CVS rlog commands to find files
9259 to convert. This means that unless a filemap is given, all files under
9260 the starting directory will be converted, and that any directory reor‐
9261 ganization in the CVS sandbox is ignored.
9262 The following options can be used with --config:
9264 convert.cvsps.cache
9266 Set to False to disable remote log caching, for testing and de‐
9267 bugging purposes. Default is True.
9268 convert.cvsps.fuzz
9270 Specify the maximum time (in seconds) that is allowed between
9271 commits with identical user and log message in a single change‐
9272 set. When very large files were checked in as part of a change‐
9273 set then the default may not be long enough. The default is 60.
9274 convert.cvsps.logencoding
9276 Specify encoding name to be used for transcoding CVS log mes‐
9277 sages. Multiple encoding names can be specified as a list (see
9278 hg help config.Syntax), but only the first acceptable encoding
9279 in the list is used per CVS log entries. This transcoding is ex‐
9280 ecuted before cvslog hook below.
9281 convert.cvsps.mergeto
9283 Specify a regular expression to which commit log messages are
9284 matched. If a match occurs, then the conversion process will in‐
9285 sert a dummy revision merging the branch on which this log mes‐
9286 sage occurs to the branch indicated in the regex. Default is
9287 {{mergetobranch ([-\w]+)}}
9288 convert.cvsps.mergefrom
9290 Specify a regular expression to which commit log messages are
9291 matched. If a match occurs, then the conversion process will add
9292 the most recent revision on the branch indicated in the regex as
9293 the second parent of the changeset. Default is {{mergefrombranch
9294 ([-\w]+)}}
9295 convert.localtimezone
9297 use local time (as determined by the TZ environment variable)
9298 for changeset date/times. The default is False (use UTC).
9299 hooks.cvslog
9301 Specify a Python function to be called at the end of gathering
9302 the CVS log. The function is passed a list with the log entries,
9303 and can modify the entries in-place, or add or delete them.
9304 hooks.cvschangesets
9306 Specify a Python function to be called after the changesets are
9307 calculated from the CVS log. The function is passed a list with
9308 the changeset entries, and can modify the changesets in-place,
9309 or add or delete them.
9310 An additional "debugcvsps" Mercurial command allows the builtin change‐
9312 set merging code to be run without doing a conversion. Its parameters
9313 and output are similar to that of cvsps 2.1. Please see the command
9314 help for more details.
9315 Subversion Source
9317 Subversion source detects classical trunk/branches/tags layouts. By
9318 default, the supplied svn://repo/path/ source URL is converted as a
9319 single branch. If svn://repo/path/trunk exists it replaces the default
9320 branch. If svn://repo/path/branches exists, its subdirectories are
9321 listed as possible branches. If svn://repo/path/tags exists, it is
9322 looked for tags referencing converted branches. Default trunk, branches
9323 and tags values can be overridden with following options. Set them to
9324 paths relative to the source URL, or leave them blank to disable auto
9325 detection.
9326 The following options can be set with --config:
9328 convert.svn.branches
9330 specify the directory containing branches. The default is
9331 branches.
9332 convert.svn.tags
9334 specify the directory containing tags. The default is tags.
9335 convert.svn.trunk
9337 specify the name of the trunk branch. The default is trunk.
9338 convert.localtimezone
9340 use local time (as determined by the TZ environment variable)
9341 for changeset date/times. The default is False (use UTC).
9342 Source history can be retrieved starting at a specific revision, in‐
9344 stead of being integrally converted. Only single branch conversions are
9345 supported.
9346 convert.svn.startrev
9348 specify start Subversion revision number. The default is 0.
9349 Git Source
9351 The Git importer converts commits from all reachable branches (refs in
9352 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
9353 are converted to bookmarks with the same name, with the leading
9354 'refs/heads' stripped. Git submodules are converted to Git subrepos in
9355 Mercurial.
9356 The following options can be set with --config:
9358 convert.git.similarity
9360 specify how similar files modified in a commit must be to be im‐
9361 ported as renames or copies, as a percentage between 0 (dis‐
9362 abled) and 100 (files must be identical). For example, 90 means
9363 that a delete/add pair will be imported as a rename if more than
9364 90% of the file hasn't changed. The default is 50.
9365 convert.git.findcopiesharder
9367 while detecting copies, look at all files in the working copy
9368 instead of just changed ones. This is very expensive for large
9369 projects, and is only effective when convert.git.similarity is
9370 greater than 0. The default is False.
9371 convert.git.renamelimit
9373 perform rename and copy detection up to this many changed files
9374 in a commit. Increasing this will make rename and copy detection
9375 more accurate but will significantly slow down computation on
9376 large projects. The option is only relevant if convert.git.simi‐
9377 larity is greater than 0. The default is 400.
9378 convert.git.committeractions
9380 list of actions to take when processing author and committer
9381 values.
9382 Git commits have separate author (who wrote the commit) and com‐
9384 mitter (who applied the commit) fields. Not all destinations
9385 support separate author and committer fields (including Mercu‐
9386 rial). This config option controls what to do with these author
9387 and committer fields during conversion.
9388 A value of messagedifferent will append a committer: ... line
9390 to the commit message if the Git committer is different from the
9391 author. The prefix of that line can be specified using the syn‐
9392 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
9393 ter:. When a prefix is specified, a space will always be in‐
9394 serted between the prefix and the value.
9395 messagealways behaves like messagedifferent except it will al‐
9397 ways result in a committer: ... line being appended to the com‐
9398 mit message. This value is mutually exclusive with messagedif‐
9399 ferent.
9400 dropcommitter will remove references to the committer. Only ref‐
9402 erences to the author will remain. Actions that add references
9403 to the committer will have no effect when this is set.
9404 replaceauthor will replace the value of the author field with
9406 the committer. Other actions that add references to the commit‐
9407 ter will still take effect when this is set.
9408 The default is messagedifferent.
9410 convert.git.extrakeys
9412 list of extra keys from commit metadata to copy to the destina‐
9413 tion. Some Git repositories store extra metadata in commits. By
9414 default, this non-default metadata will be lost during conver‐
9415 sion. Setting this config option can retain that metadata. Some
9416 built-in keys such as parent and branch are not allowed to be
9417 copied.
9418 convert.git.remoteprefix
9420 remote refs are converted as bookmarks with convert.git.re‐
9421 moteprefix as a prefix followed by a /. The default is 'remote'.
9422 convert.git.saverev
9424 whether to store the original Git commit ID in the metadata of
9425 the destination commit. The default is True.
9426 convert.git.skipsubmodules
9428 does not convert root level .gitmodules files or files with
9429 160000 mode indicating a submodule. Default is False.
9430 Perforce Source
9432 The Perforce (P4) importer can be given a p4 depot path or a client
9433 specification as source. It will convert all files in the source to a
9434 flat Mercurial repository, ignoring labels, branches and integrations.
9435 Note that when a depot path is given you then usually should specify a
9436 target directory, because otherwise the target may be named ...-hg.
9437 The following options can be set with --config:
9439 convert.p4.encoding
9441 specify the encoding to use when decoding standard output of the
9442 Perforce command line tool. The default is default system encod‐
9443 ing.
9444 convert.p4.startrev
9446 specify initial Perforce revision (a Perforce changelist num‐
9447 ber).
9448 Mercurial Destination
9450 The Mercurial destination will recognize Mercurial subrepositories in
9451 the destination directory, and update the .hgsubstate file automati‐
9452 cally if the destination subrepositories contain the
9453 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
9454 tories requires converting a single repository at a time, from the bot‐
9455 tom up.
9456 An example showing how to convert a repository with subrepositories:
9458 # so convert knows the type when it sees a non empty destination
9460 $ hg init converted
9461 $ hg convert orig/sub1 converted/sub1
9463 $ hg convert orig/sub2 converted/sub2
9464 $ hg convert orig converted
9465 The following options are supported:
9467 convert.hg.clonebranches
9469 dispatch source branches in separate clones. The default is
9470 False.
9471 convert.hg.tagsbranch
9473 branch name for tag revisions, defaults to default.
9474 convert.hg.usebranchnames
9476 preserve branch names. The default is True.
9477 convert.hg.sourcename
9479 records the given string as a 'convert_source' extra value on
9480 each commit made in the target repository. The default is None.
9481 convert.hg.preserve-hash
9483 only works with mercurial sources. Make convert prevent perfor‐
9484 mance improvement to the list of modified files in commits when
9485 such an improvement would cause the hash of a commit to change.
9486 The default is False.
9487 All Destinations
9489 All destination types accept the following options:
9490 convert.skiptags
9492 does not convert tags from the source repo to the target repo.
9493 The default is False.
9494 Options:
9496 --authors <FILE>
9498 username mapping filename (DEPRECATED) (use --authormap instead)
9499 -s,--source-type <TYPE>
9501 source repository type
9502 -d,--dest-type <TYPE>
9504 destination repository type
9505 -r,--rev <REV[+]>
9507 import up to source revision REV
9508 -A,--authormap <FILE>
9510 remap usernames using this file
9511 --filemap <FILE>
9513 remap file names using contents of file
9514 --full apply filemap changes by converting all files again
9516 --splicemap <FILE>
9518 splice synthesized history into place
9519 --branchmap <FILE>
9521 change branch names while converting
9522 --branchsort
9524 try to sort changesets by branches
9525 --datesort
9527 try to sort changesets by date
9528 --sourcesort
9530 preserve source changesets order
9531 --closesort
9533 try to reorder closed revisions
9534 [+] marked option can be specified multiple times
9536 eol
9538 automatically manage newlines in repository files
9539 This extension allows you to manage the type of line endings (CRLF or
9541 LF) that are used in the repository and in the local working directory.
9542 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
9543 thereby letting everybody use their OS native line endings.
9544 The extension reads its configuration from a versioned .hgeol configu‐
9546 ration file found in the root of the working directory. The .hgeol file
9547 use the same syntax as all other Mercurial configuration files. It uses
9548 two sections, [patterns] and [repository].
9549 The [patterns] section specifies how line endings should be converted
9551 between the working directory and the repository. The format is speci‐
9552 fied by a file pattern. The first match is used, so put more specific
9553 patterns first. The available line endings are LF, CRLF, and BIN.
9554 Files with the declared format of CRLF or LF are always checked out and
9556 stored in the repository in that format and files declared to be binary
9557 (BIN) are left unchanged. Additionally, native is an alias for checking
9558 out in the platform's default line ending: LF on Unix (including Mac OS
9559 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
9560 Mercurial's default behavior; it is only needed if you need to override
9561 a later, more general pattern.
9562 The optional [repository] section specifies the line endings to use for
9564 files stored in the repository. It has a single setting, native, which
9565 determines the storage line endings for files declared as native in the
9566 [patterns] section. It can be set to LF or CRLF. The default is LF. For
9567 example, this means that on Windows, files configured as native (CRLF
9568 by default) will be converted to LF when stored in the repository.
9569 Files declared as LF, CRLF, or BIN in the [patterns] section are always
9570 stored as-is in the repository.
9571 Example versioned .hgeol file:
9573 [patterns]
9575 **.py = native
9576 **.vcproj = CRLF
9577 **.txt = native
9578 Makefile = LF
9579 **.jpg = BIN
9580 [repository]
9582 native = LF
9583 Note The rules will first apply when files are touched in the working
9585 directory, e.g. by updating to null and back to tip to touch all
9586 files.
9587 The extension uses an optional [eol] section read from both the normal
9589 Mercurial configuration files and the .hgeol file, with the latter
9590 overriding the former. You can use that section to control the overall
9591 behavior. There are three settings:
9592 • eol.native (default os.linesep) can be set to LF or CRLF to override
9594 the default interpretation of native for checkout. This can be used
9595 with hg archive on Unix, say, to generate an archive where files have
9596 line endings for Windows.
9597 • eol.only-consistent (default True) can be set to False to make the
9599 extension convert files with inconsistent EOLs. Inconsistent means
9600 that there is both CRLF and LF present in the file. Such files are
9601 normally not touched under the assumption that they have mixed EOLs
9602 on purpose.
9603 • eol.fix-trailing-newline (default False) can be set to True to ensure
9605 that converted files end with a EOL character (either \n or \r\n as
9606 per the configured patterns).
9607 The extension provides cleverencode: and cleverdecode: filters like the
9609 deprecated win32text extension does. This means that you can disable
9610 win32text and enable eol and your filters will still work. You only
9611 need to these filters until you have prepared a .hgeol file.
9612 The win32text.forbid* hooks provided by the win32text extension have
9614 been unified into a single hook named eol.checkheadshook. The hook will
9615 lookup the expected line endings from the .hgeol file, which means you
9616 must migrate to a .hgeol file first before using the hook. eol.check‐
9617 headshook only checks heads, intermediate invalid revisions will be
9618 pushed. To forbid them completely, use the eol.checkallhook hook. These
9619 hooks are best used as pretxnchangegroup hooks.
9620 See hg help patterns for more information about the glob patterns used.
9622 extdiff
9624 command to allow external programs to compare revisions
9625 The extdiff Mercurial extension allows you to use external programs to
9627 compare revisions, or revision with working directory. The external
9628 diff programs are called with a configurable set of options and two
9629 non-option arguments: paths to directories containing snapshots of
9630 files to compare.
9631 If there is more than one file being compared and the "child" revision
9633 is the working directory, any modifications made in the external diff
9634 program will be copied back to the working directory from the temporary
9635 directory.
9636 The extdiff extension also allows you to configure new diff commands,
9638 so you do not need to type hg extdiff -p kdiff3 always.
9639 [extdiff]
9641 # add new command that runs GNU diff(1) in 'context diff' mode
9642 cdiff = gdiff -Nprc5
9643 ## or the old way:
9644 #cmd.cdiff = gdiff
9645 #opts.cdiff = -Nprc5
9646 # add new command called meld, runs meld (no need to name twice). If
9648 # the meld executable is not available, the meld tool in [merge-tools]
9649 # will be used, if available
9650 meld =
9651 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
9653 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
9654 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
9655 # your .vimrc
9656 vimdiff = gvim -f "+next" \
9657 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
9658 Tool arguments can include variables that are expanded at runtime:
9660 $parent1, $plabel1 - filename, descriptive label of first parent
9662 $child, $clabel - filename, descriptive label of child revision
9663 $parent2, $plabel2 - filename, descriptive label of second parent
9664 $root - repository root
9665 $parent is an alias for $parent1.
9666 The extdiff extension will look in your [diff-tools] and [merge-tools]
9668 sections for diff tool arguments, when none are specified in [extdiff].
9669 [extdiff]
9671 kdiff3 =
9672 [diff-tools]
9674 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9675 If a program has a graphical interface, it might be interesting to tell
9677 Mercurial about it. It will prevent the program from being mistakenly
9678 used in a terminal-only environment (such as an SSH terminal session),
9679 and will make hg extdiff --per-file open multiple file diffs at once
9680 instead of one by one (if you still want to open file diffs one by one,
9681 you can use the --confirm option).
9682 Declaring that a tool has a graphical interface can be done with the
9684 gui flag next to where diffargs are specified:
9685 [diff-tools]
9687 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9688 kdiff3.gui = true
9689 You can use -I/-X and list of file or directory names like normal hg
9691 diff command. The extdiff extension makes snapshots of only needed
9692 files, so running the external diff program will actually be pretty
9693 fast (at least faster than having to compare the entire tree).
9694 Commands
9696 File content management
9697 extdiff
9698 use external program to diff repository (or selected files):
9699 hg extdiff [OPT]... [FILE]...
9701 Show differences between revisions for the specified files, using an
9703 external program. The default program used is diff, with default op‐
9704 tions "-Npru".
9705 To select a different program, use the -p/--program option. The program
9707 will be passed the names of two directories to compare, unless the
9708 --per-file option is specified (see below). To pass additional options
9709 to the program, use -o/--option. These will be passed before the names
9710 of the directories or files to compare.
9711 The --from, --to, and --change options work the same way they do for hg
9713 diff.
9714 The --per-file option runs the external program repeatedly on each file
9716 to diff, instead of once on two directories. By default, this happens
9717 one by one, where the next file diff is open in the external program
9718 only once the previous external program (for the previous file diff)
9719 has exited. If the external program has a graphical interface, it can
9720 open all the file diffs at once instead of one by one. See hg help -e
9721 extdiff for information about how to tell Mercurial that a given pro‐
9722 gram has a graphical interface.
9723 The --confirm option will prompt the user before each invocation of the
9725 external program. It is ignored if --per-file isn't specified.
9726 Options:
9728 -p,--program <CMD>
9730 comparison program to run
9731 -o,--option <OPT[+]>
9733 pass option to comparison program
9734 -r,--rev <REV[+]>
9736 revision (DEPRECATED)
9737 --from <REV1>
9739 revision to diff from
9740 --to <REV2>
9742 revision to diff to
9743 -c,--change <REV>
9745 change made by revision
9746 --per-file
9748 compare each file instead of revision snapshots
9749 --confirm
9751 prompt user before each external program invocation
9752 --patch
9754 compare patches for two revisions
9755 -I,--include <PATTERN[+]>
9757 include names matching the given patterns
9758 -X,--exclude <PATTERN[+]>
9760 exclude names matching the given patterns
9761 -S, --subrepos
9763 recurse into subrepositories
9764 [+] marked option can be specified multiple times
9766 factotum
9768 http authentication with factotum
9769 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
9771 platforms to provide authentication information for HTTP access. Con‐
9772 figuration entries specified in the auth section as well as authentica‐
9773 tion information provided in the repository URL are fully supported. If
9774 no prefix is specified, a value of "*" will be assumed.
9775 By default, keys are specified as:
9777 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
9779 If the factotum extension is unable to read the required key, one will
9781 be requested interactively.
9782 A configuration section is available to customize runtime behavior. By
9784 default, these entries are:
9785 [factotum]
9787 executable = /bin/auth/factotum
9788 mountpoint = /mnt/factotum
9789 service = hg
9790 The executable entry defines the full path to the factotum binary. The
9792 mountpoint entry defines the path to the factotum file service. Lastly,
9793 the service entry controls the service name used when reading keys.
9794 fastannotate
9796 yet another annotate implementation that might be faster (EXPERIMENTAL)
9797 The fastannotate extension provides a 'fastannotate' command that makes
9799 use of the linelog data structure as a cache layer and is expected to
9800 be faster than the vanilla 'annotate' if the cache is present.
9801 In most cases, fastannotate requires a setup that mainbranch is some
9803 pointer that always moves forward, to be most efficient.
9804 Using fastannotate together with linkrevcache would speed up building
9806 the annotate cache greatly. Run "debugbuildlinkrevcache" before "debug‐
9807 buildannotatecache".
9808 [fastannotate]
9810 # specify the main branch head. the internal linelog will only contain
9811 # the linear (ignoring p2) "mainbranch". since linelog cannot move
9812 # backwards without a rebuild, this should be something that always moves
9813 # forward, usually it is "master" or "@".
9814 mainbranch = master
9815 # fastannotate supports different modes to expose its feature.
9817 # a list of combination:
9818 # - fastannotate: expose the feature via the "fastannotate" command which
9819 # deals with everything in a most efficient way, and provides extra
9820 # features like --deleted etc.
9821 # - fctx: replace fctx.annotate implementation. note:
9822 # a. it is less efficient than the "fastannotate" command
9823 # b. it will make it practically impossible to access the old (disk
9824 # side-effect free) annotate implementation
9825 # c. it implies "hgweb".
9826 # - hgweb: replace hgweb's annotate implementation. conflict with "fctx".
9827 # (default: fastannotate)
9828 modes = fastannotate
9829 # default format when no format flags are used (default: number)
9831 defaultformat = changeset, user, date
9832 # serve the annotate cache via wire protocol (default: False)
9834 # tip: the .hg/fastannotate directory is portable - can be rsynced
9835 server = True
9836 # build annotate cache on demand for every client request (default: True)
9838 # disabling it could make server response faster, useful when there is a
9839 # cronjob building the cache.
9840 serverbuildondemand = True
9841 # update local annotate cache from remote on demand
9843 client = False
9844 # path to use when connecting to the remote server (default: default)
9846 remotepath = default
9847 # minimal length of the history of a file required to fetch linelog from
9849 # the server. (default: 10)
9850 clientfetchthreshold = 10
9851 # for "fctx" mode, always follow renames regardless of command line option.
9853 # this is a BC with the original command but will reduced the space needed
9854 # for annotate cache, and is useful for client-server setup since the
9855 # server will only provide annotate cache with default options (i.e. with
9856 # follow). do not affect "fastannotate" mode. (default: True)
9857 forcefollow = True
9858 # for "fctx" mode, always treat file as text files, to skip the "isbinary"
9860 # check. this is consistent with the "fastannotate" command and could help
9861 # to avoid a file fetch if remotefilelog is used. (default: True)
9862 forcetext = True
9863 # use unfiltered repo for better performance.
9865 unfilteredrepo = True
9866 # sacrifice correctness in some corner cases for performance. it does not
9868 # affect the correctness of the annotate cache being built. the option
9869 # is experimental and may disappear in the future (default: False)
9870 perfhack = True
9871 Commands
9873 Uncategorized commands
9874 fastexport
9875 export repositories as git fast-import stream
9876 Commands
9878 Change import/export
9879 fastexport
9880 export repository as git fast-import stream:
9881 hg fastexport [OPTION]... [REV]...
9883 This command lets you dump a repository as a human-readable text
9885 stream. It can be piped into corresponding import routines like "git
9886 fast-import". Incremental dumps can be created by using marks files.
9887 Options:
9889 -r,--rev <REV[+]>
9891 revisions to export
9892 -i,--import-marks <FILE>
9894 old marks file to read
9895 -e,--export-marks <FILE>
9897 new marks file to write
9898 -A,--authormap <FILE>
9900 remap usernames using this file
9901 [+] marked option can be specified multiple times
9903 fetch
9905 pull, update and merge in one command (DEPRECATED)
9906 Commands
9908 Remote repository management
9909 fetch
9910 pull changes from a remote repository, merge new changes if needed.:
9911 hg fetch [SOURCE]
9913 This finds all changes from the repository at the specified path or URL
9915 and adds them to the local repository.
9916 If the pulled changes add a new branch head, the head is automatically
9918 merged, and the result of the merge is committed. Otherwise, the work‐
9919 ing directory is updated to include the new changes.
9920 When a merge is needed, the working directory is first updated to the
9922 newly pulled changes. Local changes are then merged into the pulled
9923 changes. To switch the merge order, use --switch-parent.
9924 See hg help dates for a list of formats valid for -d/--date.
9926 Returns 0 on success.
9928 Options:
9930 -r,--rev <REV[+]>
9932 a specific revision you would like to pull
9933 --edit invoke editor on commit messages
9935 --force-editor
9937 edit commit message (DEPRECATED)
9938 --switch-parent
9940 switch parents when merging
9941 -m,--message <TEXT>
9943 use text as commit message
9944 -l,--logfile <FILE>
9946 read commit message from file
9947 -d,--date <DATE>
9949 record the specified date as commit date
9950 -u,--user <USER>
9952 record the specified user as committer
9953 -e,--ssh <CMD>
9955 specify ssh command to use
9956 --remotecmd <CMD>
9958 specify hg command to run on the remote side
9959 --insecure
9961 do not verify server certificate (ignoring web.cacerts config)
9962 [+] marked option can be specified multiple times
9964 fix
9966 rewrite file content in changesets or working copy (EXPERIMENTAL)
9967 Provides a command that runs configured tools on the contents of modi‐
9969 fied files, writing back any fixes to the working copy or replacing
9970 changesets.
9971 Here is an example configuration that causes hg fix to apply automatic
9973 formatting fixes to modified lines in C++ code:
9974 [fix]
9976 clang-format:command=clang-format --assume-filename={rootpath}
9977 clang-format:linerange=--lines={first}:{last}
9978 clang-format:pattern=set:**.cpp or **.hpp
9979 The :command suboption forms the first part of the shell command that
9981 will be used to fix a file. The content of the file is passed on stan‐
9982 dard input, and the fixed file content is expected on standard output.
9983 Any output on standard error will be displayed as a warning. If the
9984 exit status is not zero, the file will not be affected. A placeholder
9985 warning is displayed if there is a non-zero exit status but no standard
9986 error output. Some values may be substituted into the command:
9987 {rootpath} The path of the file being fixed, relative to the repo root
9989 {basename} The name of the file being fixed, without the directory path
9990 If the :linerange suboption is set, the tool will only be run if there
9992 are changed lines in a file. The value of this suboption is appended to
9993 the shell command once for every range of changed lines in the file.
9994 Some values may be substituted into the command:
9995 {first} The 1-based line number of the first line in the modified range
9997 {last} The 1-based line number of the last line in the modified range
9998 Deleted sections of a file will be ignored by :linerange, because there
10000 is no corresponding line range in the version being fixed.
10001 By default, tools that set :linerange will only be executed if there is
10003 at least one changed line range. This is meant to prevent accidents
10004 like running a code formatter in such a way that it unexpectedly refor‐
10005 mats the whole file. If such a tool needs to operate on unchanged
10006 files, it should set the :skipclean suboption to false.
10007 The :pattern suboption determines which files will be passed through
10009 each configured tool. See hg help patterns for possible values. How‐
10010 ever, all patterns are relative to the repo root, even if that text
10011 says they are relative to the current working directory. If there are
10012 file arguments to hg fix, the intersection of these patterns is used.
10013 There is also a configurable limit for the maximum size of file that
10015 will be processed by hg fix:
10016 [fix]
10018 maxfilesize = 2MB
10019 Normally, execution of configured tools will continue after a failure
10021 (indicated by a non-zero exit status). It can also be configured to
10022 abort after the first such failure, so that no files will be affected
10023 if any tool fails. This abort will also cause hg fix to exit with a
10024 non-zero status:
10025 [fix]
10027 failure = abort
10028 When multiple tools are configured to affect a file, they execute in an
10030 order defined by the :priority suboption. The priority suboption has a
10031 default value of zero for each tool. Tools are executed in order of de‐
10032 scending priority. The execution order of tools with equal priority is
10033 unspecified. For example, you could use the 'sort' and 'head' utilities
10034 to keep only the 10 smallest numbers in a text file by ensuring that
10035 'sort' runs before 'head':
10036 [fix]
10038 sort:command = sort -n
10039 head:command = head -n 10
10040 sort:pattern = numbers.txt
10041 head:pattern = numbers.txt
10042 sort:priority = 2
10043 head:priority = 1
10044 To account for changes made by each tool, the line numbers used for in‐
10046 cremental formatting are recomputed before executing the next tool. So,
10047 each tool may see different values for the arguments added by the :lin‐
10048 erange suboption.
10049 Each fixer tool is allowed to return some metadata in addition to the
10051 fixed file content. The metadata must be placed before the file content
10052 on stdout, separated from the file content by a zero byte. The metadata
10053 is parsed as a JSON value (so, it should be UTF-8 encoded and contain
10054 no zero bytes). A fixer tool is expected to produce this metadata en‐
10055 coding if and only if the :metadata suboption is true:
10056 [fix]
10058 tool:command = tool --prepend-json-metadata
10059 tool:metadata = true
10060 The metadata values are passed to hooks, which can be used to print
10062 summaries or perform other post-fixing work. The supported hooks are:
10063 "postfixfile"
10065 Run once for each file in each revision where any fixer tools made changes
10066 to the file content. Provides "$HG_REV" and "$HG_PATH" to identify the file,
10067 and "$HG_METADATA" with a map of fixer names to metadata values from fixer
10068 tools that affected the file. Fixer tools that didn't affect the file have a
10069 value of None. Only fixer tools that executed are present in the metadata.
10070 "postfix"
10072 Run once after all files and revisions have been handled. Provides
10073 "$HG_REPLACEMENTS" with information about what revisions were created and
10074 made obsolete. Provides a boolean "$HG_WDIRWRITTEN" to indicate whether any
10075 files in the working copy were updated. Provides a list "$HG_METADATA"
10076 mapping fixer tool names to lists of metadata values returned from
10077 executions that modified a file. This aggregates the same metadata
10078 previously passed to the "postfixfile" hook.
10079 Fixer tools are run in the repository's root directory. This allows
10081 them to read configuration files from the working copy, or even write
10082 to the working copy. The working copy is not updated to match the re‐
10083 vision being fixed. In fact, several revisions may be fixed in paral‐
10084 lel. Writes to the working copy are not amended into the revision being
10085 fixed; fixer tools should always write fixed file content back to std‐
10086 out as documented above.
10087 Commands
10089 File content management
10090 fix
10091 rewrite file content in changesets or working directory:
10092 hg fix [OPTION]... [FILE]...
10094 Runs any configured tools to fix the content of files. Only affects
10096 files with changes, unless file arguments are provided. Only affects
10097 changed lines of files, unless the --whole flag is used. Some tools may
10098 always affect the whole file regardless of --whole.
10099 If --working-dir is used, files with uncommitted changes in the working
10101 copy will be fixed. Note that no backup are made.
10102 If revisions are specified with --source, those revisions and their de‐
10104 scendants will be checked, and they may be replaced with new revisions
10105 that have fixed file content. By automatically including the descen‐
10106 dants, no merging, rebasing, or evolution will be required. If an an‐
10107 cestor of the working copy is included, then the working copy itself
10108 will also be fixed, and the working copy will be updated to the fixed
10109 parent.
10110 When determining what lines of each file to fix at each revision, the
10112 whole set of revisions being fixed is considered, so that fixes to ear‐
10113 lier revisions are not forgotten in later ones. The --base flag can be
10114 used to override this default behavior, though it is not usually desir‐
10115 able to do so.
10116 Options:
10118 --all fix all non-public non-obsolete revisions
10120 --base <REV[+]>
10122 revisions to diff against (overrides automatic selection, and
10123 applies to every revision being fixed)
10124 -r,--rev <REV[+]>
10126 revisions to fix (ADVANCED)
10127 -s,--source <REV[+]>
10129 fix the specified revisions and their descendants
10130 -w, --working-dir
10132 fix the working directory
10133 --whole
10135 always fix every line of a file
10136 [+] marked option can be specified multiple times
10138 fsmonitor
10140 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
10141 Integrates the file-watching program Watchman with Mercurial to produce
10143 faster status results.
10144 On a particular Linux system, for a real-world repository with over
10146 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
10147 the same system, with fsmonitor it takes about 0.3 seconds.
10148 fsmonitor requires no configuration -- it will tell Watchman about your
10150 repository as necessary. You'll need to install Watchman from
10151 https://facebook.github.io/watchman/ and make sure it is in your PATH.
10152 fsmonitor is incompatible with the largefiles and eol extensions, and
10154 will disable itself if any of those are active.
10155 The following configuration options exist:
10157 [fsmonitor]
10159 mode = {off, on, paranoid}
10160 When mode = off, fsmonitor will disable itself (similar to not loading
10162 the extension at all). When mode = on, fsmonitor will be enabled (the
10163 default). When mode = paranoid, fsmonitor will query both Watchman and
10164 the filesystem, and ensure that the results are consistent.
10165 [fsmonitor]
10167 timeout = (float)
10168 A value, in seconds, that determines how long fsmonitor will wait for
10170 Watchman to return results. Defaults to 2.0.
10171 [fsmonitor]
10173 blacklistusers = (list of userids)
10174 A list of usernames for which fsmonitor will disable itself altogether.
10176 [fsmonitor]
10178 walk_on_invalidate = (boolean)
10179 Whether or not to walk the whole repo ourselves when our cached state
10181 has been invalidated, for example when Watchman has been restarted or
10182 .hgignore rules have been changed. Walking the repo in that case can
10183 result in competing for I/O with Watchman. For large repos it is recom‐
10184 mended to set this value to false. You may wish to set this to true if
10185 you have a very fast filesystem that can outpace the IPC overhead of
10186 getting the result data for the full repo from Watchman. Defaults to
10187 false.
10188 [fsmonitor]
10190 warn_when_unused = (boolean)
10191 Whether to print a warning during certain operations when fsmonitor
10193 would be beneficial to performance but isn't enabled.
10194 [fsmonitor]
10196 warn_update_file_count = (integer)
10197 # or when mercurial is built with rust support
10198 warn_update_file_count_rust = (integer)
10199 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
10201 be printed during working directory updates if this many files will be
10202 created.
10203 git
10205 grant Mercurial the ability to operate on Git repositories. (EXPERIMEN‐
10206 TAL)
10207 This is currently super experimental. It probably will consume your
10209 firstborn a la Rumpelstiltskin, etc.
10210 githelp
10212 try mapping git commands to Mercurial commands
10213 Tries to map a given git command to a Mercurial command:
10215 $ hg githelp -- git checkout master hg update master
10217 If an unknown command or parameter combination is detected, an error is
10219 produced.
10220 Commands
10222 Help
10223 githelp
10224 suggests the Mercurial equivalent of the given git command:
10225 hg githelp
10227 Usage: hg githelp -- <git command>
10229 aliases: git
10231 gpg
10233 commands to sign and verify changesets
10234 Commands
10236 Signing changes (GPG)
10237 sigcheck
10238 verify all the signatures there may be for a particular revision:
10239 hg sigcheck REV
10241 verify all the signatures there may be for a particular revision
10243 sign
10245 add a signature for the current or given revision:
10246 hg sign [OPTION]... [REV]...
10248 If no revision is given, the parent of the working directory is used,
10250 or tip if no revision is checked out.
10251 The gpg.cmd config setting can be used to specify the command to run. A
10253 default key can be specified with gpg.key.
10254 See hg help dates for a list of formats valid for -d/--date.
10256 Options:
10258 -l, --local
10260 make the signature local
10261 -f, --force
10263 sign even if the sigfile is modified
10264 --no-commit
10266 do not commit the sigfile after signing
10267 -k,--key <ID>
10269 the key id to sign with
10270 -m,--message <TEXT>
10272 use text as commit message
10273 -e, --edit
10275 invoke editor on commit messages
10276 -d,--date <DATE>
10278 record the specified date as commit date
10279 -u,--user <USER>
10281 record the specified user as committer
10282 sigs
10284 list signed changesets:
10285 hg sigs
10287 list signed changesets
10289 graphlog
10291 command to view revision graphs from a shell (DEPRECATED)
10292 The functionality of this extension has been include in core Mercurial
10294 since version 2.3. Please use hg log -G ... instead.
10295 This extension adds a --graph option to the incoming, outgoing and log
10297 commands. When this options is given, an ASCII representation of the
10298 revision graph is also shown.
10299 Commands
10301 Change navigation
10302 glog
10303 show revision history alongside an ASCII revision graph:
10304 hg glog [OPTION]... [FILE]
10306 Print a revision history alongside a revision graph drawn with ASCII
10308 characters.
10309 Nodes printed as an @ character are parents of the working directory.
10311 This is an alias to hg log -G.
10313 Options:
10315 -f, --follow
10317 follow changeset history, or file history across copies and re‐
10318 names
10319 --follow-first
10321 only follow the first parent of merge changesets (DEPRECATED)
10322 -d,--date <DATE>
10324 show revisions matching date spec
10325 -C, --copies
10327 show copied files
10328 -k,--keyword <TEXT[+]>
10330 do case-insensitive search for a given text
10331 -r,--rev <REV[+]>
10333 show the specified revision or revset
10334 --removed
10336 include revisions where files were removed
10337 -m, --only-merges
10339 show only merges (DEPRECATED)
10340 -u,--user <USER[+]>
10342 revisions committed by user
10343 --only-branch <BRANCH[+]>
10345 show only changesets within the given named branch (DEPRECATED)
10346 -b,--branch <BRANCH[+]>
10348 show changesets within the given named branch
10349 -P,--prune <REV[+]>
10351 do not display revision or any of its ancestors
10352 -p, --patch
10354 show patch
10355 -g, --git
10357 use git extended diff format
10358 -l,--limit <NUM>
10360 limit number of changes displayed
10361 -M, --no-merges
10363 do not show merges
10364 --stat output diffstat-style summary of changes
10366 -G, --graph
10368 show the revision DAG
10369 --style <STYLE>
10371 display using template map file (DEPRECATED)
10372 -T,--template <TEMPLATE>
10374 display with template
10375 -I,--include <PATTERN[+]>
10377 include names matching the given patterns
10378 -X,--exclude <PATTERN[+]>
10380 exclude names matching the given patterns
10381 [+] marked option can be specified multiple times
10383 hgk
10385 browse the repository in a graphical way
10386 The hgk extension allows browsing the history of a repository in a
10388 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
10389 distributed with Mercurial.)
10390 hgk consists of two parts: a Tcl script that does the displaying and
10392 querying of information, and an extension to Mercurial named hgk.py,
10393 which provides hooks for hgk to get information. hgk can be found in
10394 the contrib directory, and the extension is shipped in the hgext repos‐
10395 itory, and needs to be enabled.
10396 The hg view command will launch the hgk Tcl script. For this command to
10398 work, hgk must be in your search path. Alternately, you can specify the
10399 path to hgk in your configuration file:
10400 [hgk]
10402 path = /location/of/hgk
10403 hgk can make use of the extdiff extension to visualize revisions. As‐
10405 suming you had already configured extdiff vdiff command, just add:
10406 [hgk]
10408 vdiff=vdiff
10409 Revisions context menu will now display additional entries to fire vd‐
10411 iff on hovered and selected revisions.
10412 Commands
10414 Change navigation
10415 view
10416 start interactive history viewer:
10417 hg view [-l LIMIT] [REVRANGE]
10419 start interactive history viewer
10421 Options:
10423 -l,--limit <NUM>
10425 limit number of changes displayed
10426 Uncategorized commands
10428 highlight
10429 syntax highlighting for hgweb (requires Pygments)
10430 It depends on the Pygments syntax highlighting library:
10432 http://pygments.org/
10433 There are the following configuration options:
10435 [web]
10437 pygments_style = <style> (default: colorful)
10438 highlightfiles = <fileset> (default: size('<5M'))
10439 highlightonlymatchfilename = <bool> (default False)
10440 highlightonlymatchfilename will only highlight files if their type
10442 could be identified by their filename. When this is not enabled (the
10443 default), Pygments will try very hard to identify the file type from
10444 content and any match (even matches with a low confidence score) will
10445 be used.
10446 histedit
10448 interactive history editing
10449 With this extension installed, Mercurial gains one new command: histe‐
10451 dit. Usage is as follows, assuming the following history:
10452 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
10454 | Add delta
10455 |
10456 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
10457 | Add gamma
10458 |
10459 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
10460 | Add beta
10461 |
10462 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10463 Add alpha
10464 If you were to run hg histedit c561b4e977df, you would see the follow‐
10466 ing file open in your editor:
10467 pick c561b4e977df Add beta
10469 pick 030b686bedc4 Add gamma
10470 pick 7c2fd3b9020c Add delta
10471 # Edit history between c561b4e977df and 7c2fd3b9020c
10473 #
10474 # Commits are listed from least to most recent
10475 #
10476 # Commands:
10477 # p, pick = use commit
10478 # e, edit = use commit, but allow edits before making new commit
10479 # f, fold = use commit, but combine it with the one above
10480 # r, roll = like fold, but discard this commit's description and date
10481 # d, drop = remove commit from history
10482 # m, mess = edit commit message without changing commit content
10483 # b, base = checkout changeset and apply further changesets from there
10484 #
10485 In this file, lines beginning with # are ignored. You must specify a
10487 rule for each revision in your history. For example, if you had meant
10488 to add gamma before beta, and then wanted to add delta in the same re‐
10489 vision as beta, you would reorganize the file to look like this:
10490 pick 030b686bedc4 Add gamma
10492 pick c561b4e977df Add beta
10493 fold 7c2fd3b9020c Add delta
10494 # Edit history between c561b4e977df and 7c2fd3b9020c
10496 #
10497 # Commits are listed from least to most recent
10498 #
10499 # Commands:
10500 # p, pick = use commit
10501 # e, edit = use commit, but allow edits before making new commit
10502 # f, fold = use commit, but combine it with the one above
10503 # r, roll = like fold, but discard this commit's description and date
10504 # d, drop = remove commit from history
10505 # m, mess = edit commit message without changing commit content
10506 # b, base = checkout changeset and apply further changesets from there
10507 #
10508 At which point you close the editor and histedit starts working. When
10510 you specify a fold operation, histedit will open an editor when it
10511 folds those revisions together, offering you a chance to clean up the
10512 commit message:
10513 Add beta
10515 ***
10516 Add delta
10517 Edit the commit message to your liking, then close the editor. The date
10519 used for the commit will be the later of the two commits' dates. For
10520 this example, let's assume that the commit message was changed to Add
10521 beta and delta. After histedit has run and had a chance to remove any
10522 old or temporary revisions it needed, the history looks like this:
10523 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
10525 | Add beta and delta.
10526 |
10527 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10528 | Add gamma
10529 |
10530 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10531 Add alpha
10532 Note that histedit does not remove any revisions (even its own tempo‐
10534 rary ones) until after it has completed all the editing operations, so
10535 it will probably perform several strip operations when it's done. For
10536 the above example, it had to run strip twice. Strip can be slow depend‐
10537 ing on a variety of factors, so you might need to be a little patient.
10538 You can choose to keep the original revisions by passing the --keep
10539 flag.
10540 The edit operation will drop you back to a command prompt, allowing you
10542 to edit files freely, or even use hg record to commit some changes as a
10543 separate commit. When you're done, any remaining uncommitted changes
10544 will be committed as well. When done, run hg histedit --continue to
10545 finish this step. If there are uncommitted changes, you'll be prompted
10546 for a new commit message, but the default commit message will be the
10547 original message for the edit ed revision, and the date of the original
10548 commit will be preserved.
10549 The message operation will give you a chance to revise a commit message
10551 without changing the contents. It's a shortcut for doing edit immedi‐
10552 ately followed by hg histedit --continue`.
10553 If histedit encounters a conflict when moving a revision (while han‐
10555 dling pick or fold), it'll stop in a similar manner to edit with the
10556 difference that it won't prompt you for a commit message when done. If
10557 you decide at this point that you don't like how much work it will be
10558 to rearrange history, or that you made a mistake, you can use hg histe‐
10559 dit --abort to abandon the new changes you have made and return to the
10560 state before you attempted to edit your history.
10561 If we clone the histedit-ed example repository above and add four more
10563 changes, such that we have the following history:
10564 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
10566 | Add theta
10567 |
10568 o 5 140988835471 2009-04-27 18:04 -0500 stefan
10569 | Add eta
10570 |
10571 o 4 122930637314 2009-04-27 18:04 -0500 stefan
10572 | Add zeta
10573 |
10574 o 3 836302820282 2009-04-27 18:04 -0500 stefan
10575 | Add epsilon
10576 |
10577 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
10578 | Add beta and delta.
10579 |
10580 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10581 | Add gamma
10582 |
10583 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10584 Add alpha
10585 If you run hg histedit --outgoing on the clone then it is the same as
10587 running hg histedit 836302820282. If you need plan to push to a reposi‐
10588 tory that Mercurial does not detect to be related to the source repo,
10589 you can add a --force option.
10590 Config
10592 Histedit rule lines are truncated to 80 characters by default. You can
10593 customize this behavior by setting a different length in your configu‐
10594 ration file:
10595 [histedit]
10597 linelen = 120 # truncate rule lines at 120 characters
10598 The summary of a change can be customized as well:
10600 [histedit]
10602 summary-template = '{rev} {bookmarks} {desc|firstline}'
10603 The customized summary should be kept short enough that rule lines will
10605 fit in the configured line length. See above if that requires cus‐
10606 tomization.
10607 hg histedit attempts to automatically choose an appropriate base revi‐
10609 sion to use. To change which base revision is used, define a revset in
10610 your configuration file:
10611 [histedit]
10613 defaultrev = only(.) & draft()
10614 By default each edited revision needs to be present in histedit com‐
10616 mands. To remove revision you need to use drop operation. You can con‐
10617 figure the drop to be implicit for missing commits by adding:
10618 [histedit]
10620 dropmissing = True
10621 By default, histedit will close the transaction after each action. For
10623 performance purposes, you can configure histedit to use a single trans‐
10624 action across the entire histedit. WARNING: This setting introduces a
10625 significant risk of losing the work you've done in a histedit if the
10626 histedit aborts unexpectedly:
10627 [histedit]
10629 singletransaction = True
10630 Commands
10632 Change manipulation
10633 histedit
10634 interactively edit changeset history:
10635 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
10637 This command lets you edit a linear series of changesets (up to and in‐
10639 cluding the working directory, which should be clean). You can:
10640 • pick to [re]order a changeset
10642 • drop to omit changeset
10644 • mess to reword the changeset commit message
10646 • fold to combine it with the preceding changeset (using the later
10648 date)
10649 • roll like fold, but discarding this commit's description and date
10651 • edit to edit this changeset (preserving date)
10653 • base to checkout changeset and apply further changesets from there
10655 There are a number of ways to select the root changeset:
10657 • Specify ANCESTOR directly
10659 • Use --outgoing -- it will be the first linear changeset not included
10661 in destination. (See hg help config.paths.default-push)
10662 • Otherwise, the value from the "histedit.defaultrev" config option is
10664 used as a revset to select the base revision when ANCESTOR is not
10665 specified. The first revision returned by the revset is used. By de‐
10666 fault, this selects the editable history that is unique to the ances‐
10667 try of the working directory.
10668 If you use --outgoing, this command will abort if there are ambiguous
10670 outgoing revisions. For example, if there are multiple branches con‐
10671 taining outgoing revisions.
10672 Use "min(outgoing() and ::.)" or similar revset specification instead
10674 of --outgoing to specify edit target revision exactly in such ambiguous
10675 situation. See hg help revsets for detail about selecting revisions.
10676 Examples:
10678 • A number of changes have been made. Revision 3 is no longer
10680 needed.
10681 Start history editing from revision 3:
10683 hg histedit -r 3
10685 An editor opens, containing the list of revisions, with specific
10687 actions specified:
10688 pick 5339bf82f0ca 3 Zworgle the foobar
10690 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10691 pick 0a9639fcda9d 5 Morgify the cromulancy
10692 Additional information about the possible actions to take appears
10694 below the list of revisions.
10695 To remove revision 3 from the history, its action (at the begin‐
10697 ning of the relevant line) is changed to 'drop':
10698 drop 5339bf82f0ca 3 Zworgle the foobar
10700 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10701 pick 0a9639fcda9d 5 Morgify the cromulancy
10702 • A number of changes have been made. Revision 2 and 4 need to be
10704 swapped.
10705 Start history editing from revision 2:
10707 hg histedit -r 2
10709 An editor opens, containing the list of revisions, with specific
10711 actions specified:
10712 pick 252a1af424ad 2 Blorb a morgwazzle
10714 pick 5339bf82f0ca 3 Zworgle the foobar
10715 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10716 To swap revision 2 and 4, its lines are swapped in the editor:
10718 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10720 pick 5339bf82f0ca 3 Zworgle the foobar
10721 pick 252a1af424ad 2 Blorb a morgwazzle
10722 Returns 0 on success, 1 if user intervention is required (not only for
10724 intentional "edit" command, but also for resolving unexpected con‐
10725 flicts).
10726 Options:
10728 --commands <FILE>
10730 read history edits from the specified file
10731 -c, --continue
10733 continue an edit already in progress
10734 --edit-plan
10736 edit remaining actions list
10737 -k, --keep
10739 don't strip old nodes after edit is complete
10740 --abort
10742 abort an edit in progress
10743 -o, --outgoing
10745 changesets not found in destination
10746 -f, --force
10748 force outgoing even for unrelated repositories
10749 -r,--rev <REV[+]>
10751 first revision to be edited
10752 -T,--template <TEMPLATE>
10754 display with template
10755 [+] marked option can be specified multiple times
10757 hooklib
10759 collection of simple hooks for common tasks (EXPERIMENTAL)
10760 This extension provides a number of simple hooks to handle issues com‐
10762 monly found in repositories with many contributors: - email notifica‐
10763 tion when changesets move from draft to public phase - email notifica‐
10764 tion when changesets are obsoleted - enforcement of draft phase for all
10765 incoming changesets - enforcement of a no-branch-merge policy - en‐
10766 forcement of a no-multiple-heads policy
10767 The implementation of the hooks is subject to change, e.g. whether to
10769 implement them as individual hooks or merge them into the notify exten‐
10770 sion as option. The functionality itself is planned to be supported
10771 long-term.
10772 infinitepush
10774 store some pushes in a remote blob store on the server (EXPERIMEN‐
10775 TAL)
10776 IMPORTANT: if you use this extension, please contact
10778 mercurial-devel@mercurial-scm.org ASAP. This extension is believed to
10779 be unused and barring learning of users of this functionality, we will
10780 delete this code at the end of 2020.
10781 [infinitepush] # Server-side and client-side option. Pattern of the
10783 infinitepush bookmark branchpattern = PATTERN
10784 # Server or client server = False
10786 # Server-side option. Possible values: 'disk' or 'sql'. Fails if not
10788 set indextype = disk
10789 # Server-side option. Used only if indextype=sql. # Format:
10791 'IP:PORT:DB_NAME:USER:PASSWORD' sqlhost = IP:PORT:DB_NAME:USER:PASS‐
10792 WORD
10793 # Server-side option. Used only if indextype=disk. # Filesystem
10795 path to the index store indexpath = PATH
10796 # Server-side option. Possible values: 'disk' or 'external' # Fails
10798 if not set storetype = disk
10799 # Server-side option. # Path to the binary that will save bundle to
10801 the bundlestore # Formatted cmd line will be passed to it (see
10802 put_args) put_binary = put
10803 # Serser-side option. Used only if storetype=external. # Format
10805 cmd-line string for put binary. Placeholder: {filename} put_args =
10806 {filename}
10807 # Server-side option. # Path to the binary that get bundle from the
10809 bundlestore. # Formatted cmd line will be passed to it (see
10810 get_args) get_binary = get
10811 # Serser-side option. Used only if storetype=external. # Format
10813 cmd-line string for get binary. Placeholders: {filename} {handle}
10814 get_args = {filename} {handle}
10815 # Server-side option logfile = FIlE
10817 # Server-side option loglevel = DEBUG
10819 # Server-side option. Used only if indextype=sql. # Sets mysql
10821 wait_timeout option. waittimeout = 300
10822 # Server-side option. Used only if indextype=sql. # Sets mysql inn‐
10824 odb_lock_wait_timeout option. locktimeout = 120
10825 # Server-side option. Used only if indextype=sql. # Name of the
10827 repository reponame = ''
10828 # Client-side option. Used by --list-remote option. List of remote
10830 scratch # patterns to list if no patterns are specified. default‐
10831 remotepatterns = ['*']
10832 # Instructs infinitepush to forward all received bundle2 parts to
10834 the # bundle for storage. Defaults to False. storeallparts = True
10835 # routes each incoming push to the bundlestore. defaults to False
10837 pushtobundlestore = True
10838 [remotenames] # Client-side option # This option should be set only
10840 if remotenames extension is enabled. # Whether remote bookmarks are
10841 tracked by remotenames extension. bookmarks = True
10842 journal
10844 track previous positions of bookmarks (EXPERIMENTAL)
10845 This extension adds a new command: hg journal, which shows you where
10847 bookmarks were previously located.
10848 Commands
10850 Change organization
10851 journal
10852 show the previous position of bookmarks and the working copy:
10853 hg journal [OPTION]... [BOOKMARKNAME]
10855 The journal is used to see the previous commits that bookmarks and the
10857 working copy pointed to. By default the previous locations for the
10858 working copy. Passing a bookmark name will show all the previous posi‐
10859 tions of that bookmark. Use the --all switch to show previous locations
10860 for all bookmarks and the working copy; each line will then include the
10861 bookmark name, or '.' for the working copy, as well.
10862 If name starts with re:, the remainder of the name is treated as a reg‐
10864 ular expression. To match a name that actually starts with re:, use the
10865 prefix literal:.
10866 By default hg journal only shows the commit hash and the command that
10868 was running at that time. -v/--verbose will show the prior hash, the
10869 user, and the time at which it happened.
10870 Use -c/--commits to output log information on each commit hash; at this
10872 point you can use the usual --patch, --git, --stat and --template
10873 switches to alter the log output for these.
10874 hg journal -T json can be used to produce machine readable output.
10876 Options:
10878 --all show history for all names
10880 -c, --commits
10882 show commit metadata
10883 -p, --patch
10885 show patch
10886 -g, --git
10888 use git extended diff format
10889 -l,--limit <NUM>
10891 limit number of changes displayed
10892 --stat output diffstat-style summary of changes
10894 --style <STYLE>
10896 display using template map file (DEPRECATED)
10897 -T,--template <TEMPLATE>
10899 display with template
10900 keyword
10902 expand keywords in tracked files
10903 This extension expands RCS/CVS-like or self-customized $Keywords$ in
10905 tracked text files selected by your configuration.
10906 Keywords are only expanded in local repositories and not stored in the
10908 change history. The mechanism can be regarded as a convenience for the
10909 current user or for archive distribution.
10910 Keywords expand to the changeset data pertaining to the latest change
10912 relative to the working directory parent of each file.
10913 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
10915 sections of hgrc files.
10916 Example:
10918 [keyword]
10920 # expand keywords in every python file except those matching "x*"
10921 **.py =
10922 x* = ignore
10923 [keywordset]
10925 # prefer svn- over cvs-like default keywordmaps
10926 svn = True
10927 Note The more specific you are in your filename patterns the less you
10929 lose speed in huge repositories.
10930 For [keywordmaps] template mapping and expansion demonstration and con‐
10932 trol run hg kwdemo. See hg help templates for a list of available tem‐
10933 plates and filters.
10934 Three additional date template filters are provided:
10936 utcdate
10938 "2006/09/18 15:13:13"
10940 svnutcdate
10942 "2006-09-18 15:13:13Z"
10944 svnisodate
10946 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
10948 The default template mappings (view with hg kwdemo -d) can be replaced
10950 with customized keywords and templates. Again, run hg kwdemo to control
10951 the results of your configuration changes.
10952 Before changing/disabling active keywords, you must run hg kwshrink to
10954 avoid storing expanded keywords in the change history.
10955 To force expansion after enabling it, or a configuration change, run hg
10957 kwexpand.
10958 Expansions spanning more than one line and incremental expansions, like
10960 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
10961 expands to the first line of the changeset description.
10962 Commands
10964 Uncategorized commands
10965 kwdemo
10966 print [keywordmaps] configuration and an expansion example:
10967 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
10969 Show current, custom, or default keyword template maps and their expan‐
10971 sions.
10972 Extend the current configuration by specifying maps as arguments and
10974 using -f/--rcfile to source an external hgrc file.
10975 Use -d/--default to disable current configuration.
10977 See hg help templates for information on templates and filters.
10979 Options:
10981 -d, --default
10983 show default keyword template maps
10984 -f,--rcfile <FILE>
10986 read maps from rcfile
10987 kwexpand
10989 expand keywords in the working directory:
10990 hg kwexpand [OPTION]... [FILE]...
10992 Run after (re)enabling keyword expansion.
10994 kwexpand refuses to run if given files contain local changes.
10996 Options:
10998 -I,--include <PATTERN[+]>
11000 include names matching the given patterns
11001 -X,--exclude <PATTERN[+]>
11003 exclude names matching the given patterns
11004 [+] marked option can be specified multiple times
11006 kwfiles
11008 show files configured for keyword expansion:
11009 hg kwfiles [OPTION]... [FILE]...
11011 List which files in the working directory are matched by the [keyword]
11013 configuration patterns.
11014 Useful to prevent inadvertent keyword expansion and to speed up execu‐
11016 tion by including only files that are actual candidates for expansion.
11017 See hg help keyword on how to construct patterns both for inclusion and
11019 exclusion of files.
11020 With -A/--all and -v/--verbose the codes used to show the status of
11022 files are:
11023 K = keyword expansion candidate
11025 k = keyword expansion candidate (not tracked)
11026 I = ignored
11027 i = ignored (not tracked)
11028 Options:
11030 -A, --all
11032 show keyword status flags of all files
11033 -i, --ignore
11035 show files excluded from expansion
11036 -u, --unknown
11038 only show unknown (not tracked) files
11039 -I,--include <PATTERN[+]>
11041 include names matching the given patterns
11042 -X,--exclude <PATTERN[+]>
11044 exclude names matching the given patterns
11045 [+] marked option can be specified multiple times
11047 kwshrink
11049 revert expanded keywords in the working directory:
11050 hg kwshrink [OPTION]... [FILE]...
11052 Must be run before changing/disabling active keywords.
11054 kwshrink refuses to run if given files contain local changes.
11056 Options:
11058 -I,--include <PATTERN[+]>
11060 include names matching the given patterns
11061 -X,--exclude <PATTERN[+]>
11063 exclude names matching the given patterns
11064 [+] marked option can be specified multiple times
11066 largefiles
11068 track large binary files
11069 Large binary files tend to be not very compressible, not very diffable,
11071 and not at all mergeable. Such files are not handled efficiently by
11072 Mercurial's storage format (revlog), which is based on compressed bi‐
11073 nary deltas; storing large binary files as regular Mercurial files
11074 wastes bandwidth and disk space and increases Mercurial's memory usage.
11075 The largefiles extension addresses these problems by adding a central‐
11076 ized client-server layer on top of Mercurial: largefiles live in a cen‐
11077 tral store out on the network somewhere, and you only fetch the revi‐
11078 sions that you need when you need them.
11079 largefiles works by maintaining a "standin file" in .hglf/ for each
11081 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
11082 line) and are tracked by Mercurial. Largefile revisions are identified
11083 by the SHA-1 hash of their contents, which is written to the standin.
11084 largefiles uses that revision ID to get/put largefile revisions from/to
11085 the central store. This saves both disk space and bandwidth, since you
11086 don't need to retrieve all historical revisions of large files when you
11087 clone or pull.
11088 To start a new repository or add new large binary files, just add
11090 --large to your hg add command. For example:
11091 $ dd if=/dev/urandom of=randomdata count=2000
11093 $ hg add --large randomdata
11094 $ hg commit -m "add randomdata as a largefile"
11095 When you push a changeset that adds/modifies largefiles to a remote
11097 repository, its largefile revisions will be uploaded along with it.
11098 Note that the remote Mercurial must also have the largefiles extension
11099 enabled for this to work.
11100 When you pull a changeset that affects largefiles from a remote reposi‐
11102 tory, the largefiles for the changeset will by default not be pulled
11103 down. However, when you update to such a revision, any largefiles
11104 needed by that revision are downloaded and cached (if they have never
11105 been downloaded before). One way to pull largefiles when pulling is
11106 thus to use --update, which will update your working copy to the latest
11107 pulled revision (and thereby downloading any new largefiles).
11108 If you want to pull largefiles you don't need for update yet, then you
11110 can use pull with the --lfrev option or the hg lfpull command.
11111 If you know you are pulling from a non-default location and want to
11113 download all the largefiles that correspond to the new changesets at
11114 the same time, then you can pull with --lfrev "pulled()".
11115 If you just want to ensure that you will have the largefiles needed to
11117 merge or rebase with new heads that you are pulling, then you can pull
11118 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
11119 files that are new in the heads you are pulling.
11120 Keep in mind that network access may now be required to update to
11122 changesets that you have not previously updated to. The nature of the
11123 largefiles extension means that updating is no longer guaranteed to be
11124 a local-only operation.
11125 If you already have large files tracked by Mercurial without the large‐
11127 files extension, you will need to convert your repository in order to
11128 benefit from largefiles. This is done with the hg lfconvert command:
11129 $ hg lfconvert --size 10 oldrepo newrepo
11131 In repositories that already have largefiles in them, any new file over
11133 10MB will automatically be added as a largefile. To change this thresh‐
11134 old, set largefiles.minsize in your Mercurial config file to the mini‐
11135 mum size in megabytes to track as a largefile, or use the --lfsize op‐
11136 tion to the add command (also in megabytes):
11137 [largefiles]
11139 minsize = 2
11140 $ hg add --lfsize 2
11142 The largefiles.patterns config option allows you to specify a list of
11144 filename patterns (see hg help patterns) that should always be tracked
11145 as largefiles:
11146 [largefiles]
11148 patterns =
11149 *.jpg
11150 re:.*\.(png|bmp)$
11151 library.zip
11152 content/audio/*
11153 Files that match one of these patterns will be added as largefiles re‐
11155 gardless of their size.
11156 The largefiles.minsize and largefiles.patterns config options will be
11158 ignored for any repositories not already containing a largefile. To add
11159 the first largefile to a repository, you must explicitly do so with the
11160 --large flag passed to the hg add command.
11161 Commands
11163 Uncategorized commands
11164 lfconvert
11165 convert a normal repository to a largefiles repository:
11166 hg lfconvert SOURCE DEST [FILE ...]
11168 Convert repository SOURCE to a new repository DEST, identical to SOURCE
11170 except that certain files will be converted as largefiles: specifi‐
11171 cally, any file that matches any PATTERN or whose size is above the
11172 minimum size threshold is converted as a largefile. The size used to
11173 determine whether or not to track a file as a largefile is the size of
11174 the first version of the file. The minimum size can be specified either
11175 with --size or in configuration as largefiles.size.
11176 After running this command you will need to make sure that largefiles
11178 is enabled anywhere you intend to push the new repository.
11179 Use --to-normal to convert largefiles back to normal files; after this,
11181 the DEST repository can be used without largefiles at all.
11182 Options:
11184 -s,--size <SIZE>
11186 minimum size (MB) for files to be converted as largefiles
11187 --to-normal
11189 convert from a largefiles repo to a normal repo
11190 lfpull
11192 pull largefiles for the specified revisions from the specified source:
11193 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
11195 Pull largefiles that are referenced from local changesets but missing
11197 locally, pulling from a remote repository to the local cache.
11198 If SOURCE is omitted, the 'default' path will be used. See hg help
11200 urls for more information.
11201 Some examples:
11203 • pull largefiles for all branch heads:
11205 hg lfpull -r "head() and not closed()"
11207 • pull largefiles on the default branch:
11209 hg lfpull -r "branch(default)"
11211 Options:
11213 -r,--rev <VALUE[+]>
11215 pull largefiles for these revisions
11216 -e,--ssh <CMD>
11218 specify ssh command to use
11219 --remotecmd <CMD>
11221 specify hg command to run on the remote side
11222 --insecure
11224 do not verify server certificate (ignoring web.cacerts config)
11225 [+] marked option can be specified multiple times
11227 lfs
11229 lfs - large file support (EXPERIMENTAL)
11230 This extension allows large files to be tracked outside of the normal
11232 repository storage and stored on a centralized server, similar to the
11233 largefiles extension. The git-lfs protocol is used when communicating
11234 with the server, so existing git infrastructure can be harnessed. Even
11235 though the files are stored outside of the repository, they are still
11236 integrity checked in the same manner as normal files.
11237 The files stored outside of the repository are downloaded on demand,
11239 which reduces the time to clone, and possibly the local disk usage.
11240 This changes fundamental workflows in a DVCS, so careful thought should
11241 be given before deploying it. hg convert can be used to convert LFS
11242 repositories to normal repositories that no longer require this exten‐
11243 sion, and do so without changing the commit hashes. This allows the
11244 extension to be disabled if the centralized workflow becomes burden‐
11245 some. However, the pre and post convert clones will not be able to
11246 communicate with each other unless the extension is enabled on both.
11247 To start a new repository, or to add LFS files to an existing one, just
11249 create an .hglfs file as described below in the root directory of the
11250 repository. Typically, this file should be put under version control,
11251 so that the settings will propagate to other repositories with push and
11252 pull. During any commit, Mercurial will consult this file to determine
11253 if an added or modified file should be stored externally. The type of
11254 storage depends on the characteristics of the file at each commit. A
11255 file that is near a size threshold may switch back and forth between
11256 LFS and normal storage, as needed.
11257 Alternately, both normal repositories and largefile controlled reposi‐
11259 tories can be converted to LFS by using hg convert and the lfs.track
11260 config option described below. The .hglfs file should then be created
11261 and added, to control subsequent LFS selection. The hashes are also
11262 unchanged in this case. The LFS and non-LFS repositories can be dis‐
11263 tinguished because the LFS repository will abort any command if this
11264 extension is disabled.
11265 Committed LFS files are held locally, until the repository is pushed.
11267 Prior to pushing the normal repository data, the LFS files that are
11268 tracked by the outgoing commits are automatically uploaded to the con‐
11269 figured central server. No LFS files are transferred on hg pull or hg
11270 clone. Instead, the files are downloaded on demand as they need to be
11271 read, if a cached copy cannot be found locally. Both committing and
11272 downloading an LFS file will link the file to a usercache, to speed up
11273 future access. See the usercache config setting described below.
11274 The extension reads its configuration from a versioned .hglfs configu‐
11276 ration file found in the root of the working directory. The .hglfs file
11277 uses the same syntax as all other Mercurial configuration files. It
11278 uses a single section, [track].
11279 The [track] section specifies which files are stored as LFS (or not).
11281 Each line is keyed by a file pattern, with a predicate value. The
11282 first file pattern match is used, so put more specific patterns first.
11283 The available predicates are all(), none(), and size(). See "hg help
11284 filesets.size" for the latter.
11285 Example versioned .hglfs file:
11287 [track]
11289 # No Makefile or python file, anywhere, will be LFS
11290 **Makefile = none()
11291 **.py = none()
11292 **.zip = all()
11294 **.exe = size(">1MB")
11295 # Catchall for everything not matched above
11297 ** = size(">10MB")
11298 Configs:
11300 [lfs]
11302 # Remote endpoint. Multiple protocols are supported:
11303 # - http(s)://user:pass@example.com/path
11304 # git-lfs endpoint
11305 # - file:///tmp/path
11306 # local filesystem, usually for testing
11307 # if unset, lfs will assume the remote repository also handles blob storage
11308 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
11309 # use this value.
11310 # (default: unset)
11311 url = https://example.com/repo.git/info/lfs
11312 # Which files to track in LFS. Path tests are "**.extname" for file
11314 # extensions, and "path:under/some/directory" for path prefix. Both
11315 # are relative to the repository root.
11316 # File size can be tested with the "size()" fileset, and tests can be
11317 # joined with fileset operators. (See "hg help filesets.operators".)
11318 #
11319 # Some examples:
11320 # - all() # everything
11321 # - none() # nothing
11322 # - size(">20MB") # larger than 20MB
11323 # - !**.txt # anything not a *.txt file
11324 # - **.zip | **.tar.gz | **.7z # some types of compressed files
11325 # - path:bin # files under "bin" in the project root
11326 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
11327 # | (path:bin & !path:/bin/README) | size(">1GB")
11328 # (default: none())
11329 #
11330 # This is ignored if there is a tracked '.hglfs' file, and this setting
11331 # will eventually be deprecated and removed.
11332 track = size(">10M")
11333 # how many times to retry before giving up on transferring an object
11335 retry = 5
11336 # the local directory to store lfs files for sharing across local clones.
11338 # If not set, the cache is located in an OS specific cache location.
11339 usercache = /path/to/global/cache
11340 Commands
11342 Uncategorized commands
11343 logtoprocess
11344 send ui.log() data to a subprocess (EXPERIMENTAL)
11345 This extension lets you specify a shell command per ui.log() event,
11347 sending all remaining arguments to as environment variables to that
11348 command.
11349 Positional arguments construct a log message, which is passed in the
11351 MSG1 environment variables. Each keyword argument is set as a OPT_UP‐
11352 PERCASE_KEY variable (so the key is uppercased, and prefixed with
11353 OPT_). The original event name is passed in the EVENT environment vari‐
11354 able, and the process ID of mercurial is given in HGPID.
11355 So given a call ui.log('foo', 'bar %s ', 'baz', spam='eggs'), a script
11357 configured for the `foo event can expect an environment with MSG1=bar
11358 baz, and OPT_SPAM=eggs.
11359 Scripts are configured in the [logtoprocess] section, each key an event
11361 name. For example:
11362 [logtoprocess]
11364 commandexception = echo "$MSG1" > /var/log/mercurial_exceptions.log
11365 would log the warning message and traceback of any failed command dis‐
11367 patch.
11368 Scripts are run asynchronously as detached daemon processes; mercurial
11370 will not ensure that they exit cleanly.
11371 mq
11373 manage a stack of patches
11374 This extension lets you work with a stack of patches in a Mercurial
11376 repository. It manages two stacks of patches - all known patches, and
11377 applied patches (subset of known patches).
11378 Known patches are represented as patch files in the .hg/patches direc‐
11380 tory. Applied patches are both patch files and changesets.
11381 Common tasks (use hg help COMMAND for more details):
11383 create new patch qnew
11385 import existing patch qimport
11386 print patch series qseries
11388 print applied patches qapplied
11389 add known patch to applied stack qpush
11391 remove patch from applied stack qpop
11392 refresh contents of top applied patch qrefresh
11393 By default, mq will automatically use git patches when required to
11395 avoid losing file mode changes, copy records, binary files or empty
11396 files creations or deletions. This behavior can be configured with:
11397 [mq]
11399 git = auto/keep/yes/no
11400 If set to 'keep', mq will obey the [diff] section configuration while
11402 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
11403 mq will override the [diff] section and always generate git or regular
11404 patches, possibly losing data in the second case.
11405 It may be desirable for mq changesets to be kept in the secret phase
11407 (see hg help phases), which can be enabled with the following setting:
11408 [mq]
11410 secret = True
11411 You will by default be managing a patch queue named "patches". You can
11413 create other, independent patch queues with the hg qqueue command.
11414 If the working directory contains uncommitted files, qpush, qpop and
11416 qgoto abort immediately. If -f/--force is used, the changes are dis‐
11417 carded. Setting:
11418 [mq]
11420 keepchanges = True
11421 make them behave as if --keep-changes were passed, and non-conflicting
11423 local changes will be tolerated and preserved. If incompatible options
11424 such as -f/--force or --exact are passed, this setting is ignored.
11425 This extension used to provide a strip command. This command now lives
11427 in the strip extension.
11428 Commands
11430 Repository creation
11431 qclone
11432 clone main and patch repository at same time:
11433 hg qclone [OPTION]... SOURCE [DEST]
11435 If source is local, destination will have no patches applied. If source
11437 is remote, this command can not check if patches are applied in source,
11438 so cannot guarantee that patches are not applied in destination. If you
11439 clone remote repository, be sure before that it has no patches applied.
11440 Source patch repository is looked for in <src>/.hg/patches by default.
11442 Use -p <url> to change.
11443 The patch directory must be a nested Mercurial repository, as would be
11445 created by hg init --mq.
11446 Return 0 on success.
11448 Options:
11450 --pull use pull protocol to copy metadata
11452 -U, --noupdate
11454 do not update the new working directories
11455 --uncompressed
11457 use uncompressed transfer (fast over LAN)
11458 -p,--patches <REPO>
11460 location of source patch repository
11461 -e,--ssh <CMD>
11463 specify ssh command to use
11464 --remotecmd <CMD>
11466 specify hg command to run on the remote side
11467 --insecure
11469 do not verify server certificate (ignoring web.cacerts config)
11470 qinit
11472 init a new queue repository (DEPRECATED):
11473 hg qinit [-c]
11475 The queue repository is unversioned by default. If -c/--create-repo is
11477 specified, qinit will create a separate nested repository for patches
11478 (qinit -c may also be run later to convert an unversioned patch reposi‐
11479 tory into a versioned one). You can use qcommit to commit changes to
11480 this queue repository.
11481 This command is deprecated. Without -c, it's implied by other relevant
11483 commands. With -c, use hg init --mq instead.
11484 Options:
11486 -c, --create-repo
11488 create queue repository
11489 Change creation
11491 qcommit
11492 commit changes in the queue repository (DEPRECATED):
11493 hg qcommit [OPTION]... [FILE]...
11495 This command is deprecated; use hg commit --mq instead.
11497 Options:
11499 -A, --addremove
11501 mark new/missing files as added/removed before committing
11502 --close-branch
11504 mark a branch head as closed
11505 --amend
11507 amend the parent of the working directory
11508 -s, --secret
11510 use the secret phase for committing
11511 -e, --edit
11513 invoke editor on commit messages
11514 --force-close-branch
11516 forcibly close branch from a non-head changeset (ADVANCED)
11517 -i, --interactive
11519 use interactive mode
11520 -I,--include <PATTERN[+]>
11522 include names matching the given patterns
11523 -X,--exclude <PATTERN[+]>
11525 exclude names matching the given patterns
11526 -m,--message <TEXT>
11528 use text as commit message
11529 -l,--logfile <FILE>
11531 read commit message from file
11532 -d,--date <DATE>
11534 record the specified date as commit date
11535 -u,--user <USER>
11537 record the specified user as committer
11538 -S, --subrepos
11540 recurse into subrepositories
11541 [+] marked option can be specified multiple times
11543 aliases: qci
11545 qnew
11547 create a new patch:
11548 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
11550 qnew creates a new patch on top of the currently-applied patch (if
11552 any). The patch will be initialized with any outstanding changes in the
11553 working directory. You may also use -I/--include, -X/--exclude, and/or
11554 a list of files after the patch name to add only changes to matching
11555 files to the new patch, leaving the rest as uncommitted modifications.
11556 -u/--user and -d/--date can be used to set the (given) user and date,
11558 respectively. -U/--currentuser and -D/--currentdate set user to current
11559 user and date to current date.
11560 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
11562 the commit message. If none is specified, the header is empty and the
11563 commit message is '[mq]: PATCH'.
11564 Use the -g/--git option to keep the patch in the git extended diff for‐
11566 mat. Read the diffs help topic for more information on why this is im‐
11567 portant for preserving permission changes and copy/rename information.
11568 Returns 0 on successful creation of a new patch.
11570 Options:
11572 -e, --edit
11574 invoke editor on commit messages
11575 -f, --force
11577 import uncommitted changes (DEPRECATED)
11578 -g, --git
11580 use git extended diff format
11581 -U, --currentuser
11583 add "From: <current user>" to patch
11584 -u,--user <USER>
11586 add "From: <USER>" to patch
11587 -D, --currentdate
11589 add "Date: <current date>" to patch
11590 -d,--date <DATE>
11592 add "Date: <DATE>" to patch
11593 -I,--include <PATTERN[+]>
11595 include names matching the given patterns
11596 -X,--exclude <PATTERN[+]>
11598 exclude names matching the given patterns
11599 -m,--message <TEXT>
11601 use text as commit message
11602 -l,--logfile <FILE>
11604 read commit message from file
11605 [+] marked option can be specified multiple times
11607 qrefresh
11609 update the current patch:
11610 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
11612 If any file patterns are provided, the refreshed patch will contain
11614 only the modifications that match those patterns; the remaining modifi‐
11615 cations will remain in the working directory.
11616 If -s/--short is specified, files currently included in the patch will
11618 be refreshed just like matched files and remain in the patch.
11619 If -e/--edit is specified, Mercurial will start your configured editor
11621 for you to enter a message. In case qrefresh fails, you will find a
11622 backup of your message in .hg/last-message.txt.
11623 hg add/remove/copy/rename work as usual, though you might want to use
11625 git-style patches (-g/--git or [diff] git=1) to track copies and re‐
11626 names. See the diffs help topic for more information on the git diff
11627 format.
11628 Returns 0 on success.
11630 Options:
11632 -e, --edit
11634 invoke editor on commit messages
11635 -g, --git
11637 use git extended diff format
11638 -s, --short
11640 refresh only files already in the patch and specified files
11641 -U, --currentuser
11643 add/update author field in patch with current user
11644 -u,--user <USER>
11646 add/update author field in patch with given user
11647 -D, --currentdate
11649 add/update date field in patch with current date
11650 -d,--date <DATE>
11652 add/update date field in patch with given date
11653 -I,--include <PATTERN[+]>
11655 include names matching the given patterns
11656 -X,--exclude <PATTERN[+]>
11658 exclude names matching the given patterns
11659 -m,--message <TEXT>
11661 use text as commit message
11662 -l,--logfile <FILE>
11664 read commit message from file
11665 [+] marked option can be specified multiple times
11667 Change manipulation
11669 qfold
11670 fold the named patches into the current patch:
11671 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
11673 Patches must not yet be applied. Each patch will be successively ap‐
11675 plied to the current patch in the order given. If all the patches apply
11676 successfully, the current patch will be refreshed with the new cumula‐
11677 tive patch, and the folded patches will be deleted. With -k/--keep, the
11678 folded patch files will not be removed afterwards.
11679 The header for each folded patch will be concatenated with the current
11681 patch header, separated by a line of * * *.
11682 Returns 0 on success.
11684 Options:
11686 -e, --edit
11688 invoke editor on commit messages
11689 -k, --keep
11691 keep folded patch files
11692 -m,--message <TEXT>
11694 use text as commit message
11695 -l,--logfile <FILE>
11697 read commit message from file
11698 Change organization
11700 qapplied
11701 print the patches already applied:
11702 hg qapplied [-1] [-s] [PATCH]
11704 Returns 0 on success.
11706 Options:
11708 -1, --last
11710 show only the preceding applied patch
11711 -s, --summary
11713 print first line of patch header
11714 qdelete
11716 remove patches from queue:
11717 hg qdelete [-k] [PATCH]...
11719 The patches must not be applied, and at least one patch is required.
11721 Exact patch identifiers must be given. With -k/--keep, the patch files
11722 are preserved in the patch directory.
11723 To stop managing a patch and move it into permanent history, use the hg
11725 qfinish command.
11726 Options:
11728 -k, --keep
11730 keep patch file
11731 -r,--rev <REV[+]>
11733 stop managing a revision (DEPRECATED)
11734 [+] marked option can be specified multiple times
11736 aliases: qremove qrm
11738 qfinish
11740 move applied patches into repository history:
11741 hg qfinish [-a] [REV]...
11743 Finishes the specified revisions (corresponding to applied patches) by
11745 moving them out of mq control into regular repository history.
11746 Accepts a revision range or the -a/--applied option. If --applied is
11748 specified, all applied mq revisions are removed from mq control. Other‐
11749 wise, the given revisions must be at the base of the stack of applied
11750 patches.
11751 This can be especially useful if your changes have been applied to an
11753 upstream repository, or if you are about to push your changes to up‐
11754 stream.
11755 Returns 0 on success.
11757 Options:
11759 -a, --applied
11761 finish all applied changesets
11762 qgoto
11764 push or pop patches until named patch is at top of stack:
11765 hg qgoto [OPTION]... PATCH
11767 Returns 0 on success.
11769 Options:
11771 --keep-changes
11773 tolerate non-conflicting local changes
11774 -f, --force
11776 overwrite any local changes
11777 --no-backup
11779 do not save backup copies of files
11780 qguard
11782 set or print guards for a patch:
11783 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
11785 Guards control whether a patch can be pushed. A patch with no guards is
11787 always pushed. A patch with a positive guard ("+foo") is pushed only if
11788 the hg qselect command has activated it. A patch with a negative guard
11789 ("-foo") is never pushed if the hg qselect command has activated it.
11790 With no arguments, print the currently active guards. With arguments,
11792 set guards for the named patch.
11793 Note Specifying negative guards now requires '--'.
11795 To set guards on another patch:
11797 hg qguard other.patch -- +2.6.17 -stable
11799 Returns 0 on success.
11801 Options:
11803 -l, --list
11805 list all patches and guards
11806 -n, --none
11808 drop all guards
11809 qheader
11811 print the header of the topmost or specified patch:
11812 hg qheader [PATCH]
11814 Returns 0 on success.
11816 qnext
11818 print the name of the next pushable patch:
11819 hg qnext [-s]
11821 Returns 0 on success.
11823 Options:
11825 -s, --summary
11827 print first line of patch header
11828 qpop
11830 pop the current patch off the stack:
11831 hg qpop [-a] [-f] [PATCH | INDEX]
11833 Without argument, pops off the top of the patch stack. If given a patch
11835 name, keeps popping off patches until the named patch is at the top of
11836 the stack.
11837 By default, abort if the working directory contains uncommitted
11839 changes. With --keep-changes, abort only if the uncommitted files over‐
11840 lap with patched files. With -f/--force, backup and discard changes
11841 made to such files.
11842 Return 0 on success.
11844 Options:
11846 -a, --all
11848 pop all patches
11849 -n,--name <NAME>
11851 queue name to pop (DEPRECATED)
11852 --keep-changes
11854 tolerate non-conflicting local changes
11855 -f, --force
11857 forget any local changes to patched files
11858 --no-backup
11860 do not save backup copies of files
11861 qprev
11863 print the name of the preceding applied patch:
11864 hg qprev [-s]
11866 Returns 0 on success.
11868 Options:
11870 -s, --summary
11872 print first line of patch header
11873 qpush
11875 push the next patch onto the stack:
11876 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
11878 By default, abort if the working directory contains uncommitted
11880 changes. With --keep-changes, abort only if the uncommitted files over‐
11881 lap with patched files. With -f/--force, backup and patch over uncom‐
11882 mitted changes.
11883 Return 0 on success.
11885 Options:
11887 --keep-changes
11889 tolerate non-conflicting local changes
11890 -f, --force
11892 apply on top of local changes
11893 -e, --exact
11895 apply the target patch to its recorded parent
11896 -l, --list
11898 list patch name in commit text
11899 -a, --all
11901 apply all patches
11902 -m, --merge
11904 merge from another queue (DEPRECATED)
11905 -n,--name <NAME>
11907 merge queue name (DEPRECATED)
11908 --move reorder patch series and apply only the patch
11910 --no-backup
11912 do not save backup copies of files
11913 qqueue
11915 manage multiple patch queues:
11916 hg qqueue [OPTION] [QUEUE]
11918 Supports switching between different patch queues, as well as creating
11920 new patch queues and deleting existing ones.
11921 Omitting a queue name or specifying -l/--list will show you the regis‐
11923 tered queues - by default the "normal" patches queue is registered. The
11924 currently active queue will be marked with "(active)". Specifying --ac‐
11925 tive will print only the name of the active queue.
11926 To create a new queue, use -c/--create. The queue is automatically made
11928 active, except in the case where there are applied patches from the
11929 currently active queue in the repository. Then the queue will only be
11930 created and switching will fail.
11931 To delete an existing queue, use --delete. You cannot delete the cur‐
11933 rently active queue.
11934 Returns 0 on success.
11936 Options:
11938 -l, --list
11940 list all available queues
11941 --active
11943 print name of active queue
11944 -c, --create
11946 create new queue
11947 --rename
11949 rename active queue
11950 --delete
11952 delete reference to queue
11953 --purge
11955 delete queue, and remove patch dir
11956 qrename
11958 rename a patch:
11959 hg qrename PATCH1 [PATCH2]
11961 With one argument, renames the current patch to PATCH1. With two argu‐
11963 ments, renames PATCH1 to PATCH2.
11964 Returns 0 on success.
11966 aliases: qmv
11968 qrestore
11970 restore the queue state saved by a revision (DEPRECATED):
11971 hg qrestore [-d] [-u] REV
11973 This command is deprecated, use hg rebase instead.
11975 Options:
11977 -d, --delete
11979 delete save entry
11980 -u, --update
11982 update queue working directory
11983 qsave
11985 save current queue state (DEPRECATED):
11986 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
11988 This command is deprecated, use hg rebase instead.
11990 Options:
11992 -c, --copy
11994 copy patch directory
11995 -n,--name <NAME>
11997 copy directory name
11998 -e, --empty
12000 clear queue status file
12001 -f, --force
12003 force copy
12004 -m,--message <TEXT>
12006 use text as commit message
12007 -l,--logfile <FILE>
12009 read commit message from file
12010 qselect
12012 set or print guarded patches to push:
12013 hg qselect [OPTION]... [GUARD]...
12015 Use the hg qguard command to set or print guards on patch, then use qs‐
12017 elect to tell mq which guards to use. A patch will be pushed if it has
12018 no guards or any positive guards match the currently selected guard,
12019 but will not be pushed if any negative guards match the current guard.
12020 For example:
12021 qguard foo.patch -- -stable (negative guard)
12023 qguard bar.patch +stable (positive guard)
12024 qselect stable
12025 This activates the "stable" guard. mq will skip foo.patch (because it
12027 has a negative match) but push bar.patch (because it has a positive
12028 match).
12029 With no arguments, prints the currently active guards. With one argu‐
12031 ment, sets the active guard.
12032 Use -n/--none to deactivate guards (no other arguments needed). When
12034 no guards are active, patches with positive guards are skipped and
12035 patches with negative guards are pushed.
12036 qselect can change the guards on applied patches. It does not pop
12038 guarded patches by default. Use --pop to pop back to the last applied
12039 patch that is not guarded. Use --reapply (which implies --pop) to push
12040 back to the current patch afterwards, but skip guarded patches.
12041 Use -s/--series to print a list of all guards in the series file (no
12043 other arguments needed). Use -v for more information.
12044 Returns 0 on success.
12046 Options:
12048 -n, --none
12050 disable all guards
12051 -s, --series
12053 list all guards in series file
12054 --pop pop to before first guarded applied patch
12056 --reapply
12058 pop, then reapply patches
12059 qseries
12061 print the entire series file:
12062 hg qseries [-ms]
12064 Returns 0 on success.
12066 Options:
12068 -m, --missing
12070 print patches not in series
12071 -s, --summary
12073 print first line of patch header
12074 qtop
12076 print the name of the current patch:
12077 hg qtop [-s]
12079 Returns 0 on success.
12081 Options:
12083 -s, --summary
12085 print first line of patch header
12086 qunapplied
12088 print the patches not yet applied:
12089 hg qunapplied [-1] [-s] [PATCH]
12091 Returns 0 on success.
12093 Options:
12095 -1, --first
12097 show only the first patch
12098 -s, --summary
12100 print first line of patch header
12101 File content management
12103 qdiff
12104 diff of the current patch and subsequent modifications:
12105 hg qdiff [OPTION]... [FILE]...
12107 Shows a diff which includes the current patch as well as any changes
12109 which have been made in the working directory since the last refresh
12110 (thus showing what the current patch would become after a qrefresh).
12111 Use hg diff if you only want to see the changes made since the last
12113 qrefresh, or hg export qtip if you want to see changes made by the cur‐
12114 rent patch without including changes made since the qrefresh.
12115 Returns 0 on success.
12117 Options:
12119 -a, --text
12121 treat all files as text
12122 -g, --git
12124 use git extended diff format (DEFAULT: diff.git)
12125 --binary
12127 generate binary diffs in git mode (default)
12128 --nodates
12130 omit dates from diff headers
12131 --noprefix
12133 omit a/ and b/ prefixes from filenames
12134 -p, --show-function
12136 show which function each change is in (DEFAULT: diff.showfunc)
12137 --reverse
12139 produce a diff that undoes the changes
12140 -w, --ignore-all-space
12142 ignore white space when comparing lines
12143 -b, --ignore-space-change
12145 ignore changes in the amount of white space
12146 -B, --ignore-blank-lines
12148 ignore changes whose lines are all blank
12149 -Z, --ignore-space-at-eol
12151 ignore changes in whitespace at EOL
12152 -U,--unified <NUM>
12154 number of lines of context to show
12155 --stat output diffstat-style summary of changes
12157 --root <DIR>
12159 produce diffs relative to subdirectory
12160 -I,--include <PATTERN[+]>
12162 include names matching the given patterns
12163 -X,--exclude <PATTERN[+]>
12165 exclude names matching the given patterns
12166 [+] marked option can be specified multiple times
12168 Change import/export
12170 qimport
12171 import a patch or existing changeset:
12172 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
12174 The patch is inserted into the series after the last applied patch. If
12176 no patches have been applied, qimport prepends the patch to the series.
12177 The patch will have the same name as its source file unless you give it
12179 a new one with -n/--name.
12180 You can register an existing patch inside the patch directory with the
12182 -e/--existing flag.
12183 With -f/--force, an existing patch of the same name will be overwrit‐
12185 ten.
12186 An existing changeset may be placed under mq control with -r/--rev
12188 (e.g. qimport --rev . -n patch will place the current revision under mq
12189 control). With -g/--git, patches imported with --rev will use the git
12190 diff format. See the diffs help topic for information on why this is
12191 important for preserving rename/copy information and permission
12192 changes. Use hg qfinish to remove changesets from mq control.
12193 To import a patch from standard input, pass - as the patch file. When
12195 importing from standard input, a patch name must be specified using the
12196 --name flag.
12197 To import an existing patch while renaming it:
12199 hg qimport -e existing-patch -n new-name
12201 Returns 0 if import succeeded.
12203 Options:
12205 -e, --existing
12207 import file in patch directory
12208 -n,--name <NAME>
12210 name of patch file
12211 -f, --force
12213 overwrite existing files
12214 -r,--rev <REV[+]>
12216 place existing revisions under mq control
12217 -g, --git
12219 use git extended diff format
12220 -P, --push
12222 qpush after importing
12223 [+] marked option can be specified multiple times
12225 narrow
12227 create clones which fetch history data for subset of files (EXPERIMEN‐
12228 TAL)
12229 Commands
12231 Repository maintenance
12232 tracked
12233 show or change the current narrowspec:
12234 hg tracked [OPTIONS]... [REMOTE]
12236 With no argument, shows the current narrowspec entries, one per line.
12238 Each line will be prefixed with 'I' or 'X' for included or excluded
12239 patterns, respectively.
12240 The narrowspec is comprised of expressions to match remote files and/or
12242 directories that should be pulled into your client. The narrowspec has
12243 include and exclude expressions, with excludes always trumping in‐
12244 cludes: that is, if a file matches an exclude expression, it will be
12245 excluded even if it also matches an include expression. Excluding
12246 files that were never included has no effect.
12247 Each included or excluded entry is in the format described by 'hg help
12249 patterns'.
12250 The options allow you to add or remove included and excluded expres‐
12252 sions.
12253 If --clear is specified, then all previous includes and excludes are
12255 DROPPED and replaced by the new ones specified to --addinclude and
12256 --addexclude. If --clear is specified without any further options, the
12257 narrowspec will be empty and will not match any files.
12258 If --auto-remove-includes is specified, then those includes that don't
12260 match any files modified by currently visible local commits (those not
12261 shared by the remote) will be added to the set of explicitly specified
12262 includes to remove.
12263 --import-rules accepts a path to a file containing rules, allowing you
12265 to add --addinclude, --addexclude rules in bulk. Like the other include
12266 and exclude switches, the changes are applied immediately.
12267 Options:
12269 --addinclude <VALUE[+]>
12271 new paths to include
12272 --removeinclude <VALUE[+]>
12274 old paths to no longer include
12275 --auto-remove-includes
12277 automatically choose unused includes to remove
12278 --addexclude <VALUE[+]>
12280 new paths to exclude
12281 --import-rules <VALUE>
12283 import narrowspecs from a file
12284 --removeexclude <VALUE[+]>
12286 old paths to no longer exclude
12287 --clear
12289 whether to replace the existing narrowspec
12290 --force-delete-local-changes
12292 forces deletion of local changes when narrowing
12293 --update-working-copy
12295 update working copy when the store has changed
12296 -e,--ssh <CMD>
12298 specify ssh command to use
12299 --remotecmd <CMD>
12301 specify hg command to run on the remote side
12302 --insecure
12304 do not verify server certificate (ignoring web.cacerts config)
12305 [+] marked option can be specified multiple times
12307 notify
12309 hooks for sending email push notifications
12310 This extension implements hooks to send email notifications when
12312 changesets are sent from or received by the local repository.
12313 First, enable the extension as explained in hg help extensions, and
12315 register the hook you want to run. incoming and changegroup hooks are
12316 run when changesets are received, while outgoing hooks are for change‐
12317 sets sent to another repository:
12318 [hooks]
12320 # one email for each incoming changeset
12321 incoming.notify = python:hgext.notify.hook
12322 # one email for all incoming changesets
12323 changegroup.notify = python:hgext.notify.hook
12324 # one email for all outgoing changesets
12326 outgoing.notify = python:hgext.notify.hook
12327 This registers the hooks. To enable notification, subscribers must be
12329 assigned to repositories. The [usersubs] section maps multiple reposi‐
12330 tories to a given recipient. The [reposubs] section maps multiple re‐
12331 cipients to a single repository:
12332 [usersubs]
12334 # key is subscriber email, value is a comma-separated list of repo patterns
12335 user@host = pattern
12336 [reposubs]
12338 # key is repo pattern, value is a comma-separated list of subscriber emails
12339 pattern = user@host
12340 A pattern is a glob matching the absolute path to a repository, option‐
12342 ally combined with a revset expression. A revset expression, if
12343 present, is separated from the glob by a hash. Example:
12344 [reposubs]
12346 */widgets#branch(release) = qa-team@example.com
12347 This sends to qa-team@example.com whenever a changeset on the release
12349 branch triggers a notification in any repository ending in widgets.
12350 In order to place them under direct user management, [usersubs] and
12352 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
12353 rated by reference:
12354 [notify]
12356 config = /path/to/subscriptionsfile
12357 Notifications will not be sent until the notify.test value is set to
12359 False; see below.
12360 Notifications content can be tweaked with the following configuration
12362 entries:
12363 notify.test
12365 If True, print messages to stdout instead of sending them. De‐
12366 fault: True.
12367 notify.sources
12369 Space-separated list of change sources. Notifications are acti‐
12370 vated only when a changeset's source is in this list. Sources
12371 may be:
12372 serve
12374 changesets received via http or ssh
12376 pull
12378 changesets received via hg pull
12380 unbundle
12382 changesets received via hg unbundle
12384 push
12386 changesets sent or received via hg push
12388 bundle
12390 changesets sent via hg unbundle
12392 Default: serve.
12394 notify.strip
12396 Number of leading slashes to strip from url paths. By default,
12397 notifications reference repositories with their absolute path.
12398 notify.strip lets you turn them into relative paths. For exam‐
12399 ple, notify.strip=3 will change /long/path/repository into
12400 repository. Default: 0.
12401 notify.domain
12403 Default email domain for sender or recipients with no explicit
12404 domain. It is also used for the domain part of the Message-Id
12405 when using notify.messageidseed.
12406 notify.messageidseed
12408 Create deterministic Message-Id headers for the mails based on
12409 the seed and the revision identifier of the first commit in the
12410 changeset.
12411 notify.style
12413 Style file to use when formatting emails.
12414 notify.template
12416 Template to use when formatting emails.
12417 notify.incoming
12419 Template to use when run as an incoming hook, overriding no‐
12420 tify.template.
12421 notify.outgoing
12423 Template to use when run as an outgoing hook, overriding no‐
12424 tify.template.
12425 notify.changegroup
12427 Template to use when running as a changegroup hook, overriding
12428 notify.template.
12429 notify.maxdiff
12431 Maximum number of diff lines to include in notification email.
12432 Set to 0 to disable the diff, or -1 to include all of it. De‐
12433 fault: 300.
12434 notify.maxdiffstat
12436 Maximum number of diffstat lines to include in notification
12437 email. Set to -1 to include all of it. Default: -1.
12438 notify.maxsubject
12440 Maximum number of characters in email's subject line. Default:
12441 67.
12442 notify.diffstat
12444 Set to True to include a diffstat before diff content. Default:
12445 True.
12446 notify.showfunc
12448 If set, override diff.showfunc for the diff content. Default:
12449 None.
12450 notify.merge
12452 If True, send notifications for merge changesets. Default: True.
12453 notify.mbox
12455 If set, append mails to this mbox file instead of sending. De‐
12456 fault: None.
12457 notify.fromauthor
12459 If set, use the committer of the first changeset in a change‐
12460 group for the "From" field of the notification mail. If not set,
12461 take the user from the pushing repo. Default: False.
12462 notify.reply-to-predecessor (EXPERIMENTAL)
12464 If set and the changeset has a predecessor in the repository,
12465 try to thread the notification mail with the predecessor. This
12466 adds the "In-Reply-To" header to the notification mail with a
12467 reference to the predecessor with the smallest revision number.
12468 Mail threads can still be torn, especially when changesets are
12469 folded.
12470 This option must be used in combination with notify.messageid‐
12472 seed.
12473 If set, the following entries will also be used to customize the noti‐
12475 fications:
12476 email.from
12478 Email From address to use if none can be found in the generated
12479 email content.
12480 web.baseurl
12482 Root repository URL to combine with repository paths when making
12483 references. See also notify.strip.
12484 pager
12486 browse command output with an external pager (DEPRECATED)
12487 Forcibly enable paging for individual commands that don't typically re‐
12489 quest pagination with the attend-<command> option. This setting takes
12490 precedence over ignore options and defaults:
12491 [pager]
12493 attend-cat = false
12494 patchbomb
12496 command to send changesets as (a series of) patch emails
12497 The series is started off with a "[PATCH 0 of N]" introduction, which
12499 describes the series as a whole.
12500 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12502 first line of the changeset description as the subject text. The mes‐
12503 sage contains two or three body parts:
12504 • The changeset description.
12506 • [Optional] The result of running diffstat on the patch.
12508 • The patch itself, as generated by hg export.
12510 Each message refers to the first in the series using the In-Reply-To
12512 and References headers, so they will show up as a sequence in threaded
12513 mail and news readers, and in mail archives.
12514 To configure other defaults, add a section like this to your configura‐
12516 tion file:
12517 [email]
12519 from = My Name <my@email>
12520 to = recipient1, recipient2, ...
12521 cc = cc1, cc2, ...
12522 bcc = bcc1, bcc2, ...
12523 reply-to = address1, address2, ...
12524 Use [patchbomb] as configuration section name if you need to override
12526 global [email] address settings.
12527 Then you can use the hg email command to mail a series of changesets as
12529 a patchbomb.
12530 You can also either configure the method option in the email section to
12532 be a sendmail compatible mailer or fill out the [smtp] section so that
12533 the patchbomb extension can automatically send patchbombs directly from
12534 the commandline. See the [email] and [smtp] sections in hgrc(5) for de‐
12535 tails.
12536 By default, hg email will prompt for a To or CC header if you do not
12538 supply one via configuration or the command line. You can override
12539 this to never prompt by configuring an empty value:
12540 [email]
12542 cc =
12543 You can control the default inclusion of an introduction message with
12545 the patchbomb.intro configuration option. The configuration is always
12546 overwritten by command line flags like --intro and --desc:
12547 [patchbomb]
12549 intro=auto # include introduction message if more than 1 patch (default)
12550 intro=never # never include an introduction message
12551 intro=always # always include an introduction message
12552 You can specify a template for flags to be added in subject prefixes.
12554 Flags specified by --flag option are exported as {flags} keyword:
12555 [patchbomb]
12557 flagtemplate = "{separate(' ',
12558 ifeq(branch, 'default', '', branch|upper),
12559 flags)}"
12560 You can set patchbomb to always ask for confirmation by setting patch‐
12562 bomb.confirm to true.
12563 Commands
12565 Change import/export
12566 email
12567 send changesets by email:
12568 hg email [OPTION]... [DEST]...
12570 By default, diffs are sent in the format generated by hg export, one
12572 per message. The series starts with a "[PATCH 0 of N]" introduction,
12573 which describes the series as a whole.
12574 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12576 first line of the changeset description as the subject text. The mes‐
12577 sage contains two or three parts. First, the changeset description.
12578 With the -d/--diffstat option, if the diffstat program is installed,
12580 the result of running diffstat on the patch is inserted.
12581 Finally, the patch itself, as generated by hg export.
12583 With the -d/--diffstat or --confirm options, you will be presented with
12585 a final summary of all messages and asked for confirmation before the
12586 messages are sent.
12587 By default the patch is included as text in the email body for easy re‐
12589 viewing. Using the -a/--attach option will instead create an attachment
12590 for the patch. With -i/--inline an inline attachment will be created.
12591 You can include a patch both as text in the email body and as a regular
12592 or an inline attachment by combining the -a/--attach or -i/--inline
12593 with the --body option.
12594 With -B/--bookmark changesets reachable by the given bookmark are se‐
12596 lected.
12597 With -o/--outgoing, emails will be generated for patches not found in
12599 the destination repository (or only those which are ancestors of the
12600 specified revisions if any are provided)
12601 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
12603 gle email containing a binary Mercurial bundle as an attachment will be
12604 sent. Use the patchbomb.bundletype config option to control the bundle
12605 type as with hg bundle --type.
12606 With -m/--mbox, instead of previewing each patchbomb message in a pager
12608 or sending the messages directly, it will create a UNIX mailbox file
12609 with the patch emails. This mailbox file can be previewed with any mail
12610 user agent which supports UNIX mbox files.
12611 With -n/--test, all steps will run, but mail will not be sent. You
12613 will be prompted for an email recipient address, a subject and an in‐
12614 troductory message describing the patches of your patchbomb. Then when
12615 all is done, patchbomb messages are displayed.
12616 In case email sending fails, you will find a backup of your series in‐
12618 troductory message in .hg/last-email.txt.
12619 The default behavior of this command can be customized through configu‐
12621 ration. (See hg help patchbomb for details)
12622 Examples:
12624 hg email -r 3000 # send patch 3000 only
12626 hg email -r 3000 -r 3001 # send patches 3000 and 3001
12627 hg email -r 3000:3005 # send patches 3000 through 3005
12628 hg email 3000 # send patch 3000 (deprecated)
12629 hg email -o # send all patches not in default
12631 hg email -o DEST # send all patches not in DEST
12632 hg email -o -r 3000 # send all ancestors of 3000 not in default
12633 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
12634 hg email -B feature # send all ancestors of feature bookmark
12636 hg email -b # send bundle of all patches not in default
12638 hg email -b DEST # send bundle of all patches not in DEST
12639 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
12640 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
12641 hg email -o -m mbox && # generate an mbox file...
12643 mutt -R -f mbox # ... and view it with mutt
12644 hg email -o -m mbox && # generate an mbox file ...
12645 formail -s sendmail \ # ... and use formail to send from the mbox
12646 -bm -t < mbox # ... using sendmail
12647 Before using this command, you will need to enable email in your hgrc.
12649 See the [email] section in hgrc(5) for details.
12650 Options:
12652 -g, --git
12654 use git extended diff format
12655 --plain
12657 omit hg patch header
12658 -o, --outgoing
12660 send changes not found in the target repository
12661 -b, --bundle
12663 send changes not in target as a binary bundle
12664 -B,--bookmark <BOOKMARK>
12666 send changes only reachable by given bookmark
12667 --bundlename <NAME>
12669 name of the bundle attachment file (default: bundle)
12670 -r,--rev <REV[+]>
12672 a revision to send
12673 --force
12675 run even when remote repository is unrelated (with -b/--bundle)
12676 --base <REV[+]>
12678 a base changeset to specify instead of a destination (with
12679 -b/--bundle)
12680 --intro
12682 send an introduction email for a single patch
12683 --body send patches as inline message text (default)
12685 -a, --attach
12687 send patches as attachments
12688 -i, --inline
12690 send patches as inline attachments
12691 --bcc <EMAIL[+]>
12693 email addresses of blind carbon copy recipients
12694 -c,--cc <EMAIL[+]>
12696 email addresses of copy recipients
12697 --confirm
12699 ask for confirmation before sending
12700 -d, --diffstat
12702 add diffstat output to messages
12703 --date <DATE>
12705 use the given date as the sending date
12706 --desc <FILE>
12708 use the given file as the series description
12709 -f,--from <EMAIL>
12711 email address of sender
12712 -n, --test
12714 print messages that would be sent
12715 -m,--mbox <FILE>
12717 write messages to mbox file instead of sending them
12718 --reply-to <EMAIL[+]>
12720 email addresses replies should be sent to
12721 -s,--subject <TEXT>
12723 subject of first message (intro or single patch)
12724 --in-reply-to <MSGID>
12726 message identifier to reply to
12727 --flag <FLAG[+]>
12729 flags to add in subject prefixes
12730 -t,--to <EMAIL[+]>
12732 email addresses of recipients
12733 -e,--ssh <CMD>
12735 specify ssh command to use
12736 --remotecmd <CMD>
12738 specify hg command to run on the remote side
12739 --insecure
12741 do not verify server certificate (ignoring web.cacerts config)
12742 [+] marked option can be specified multiple times
12744 phabricator
12746 simple Phabricator integration (EXPERIMENTAL)
12747 This extension provides a phabsend command which sends a stack of
12749 changesets to Phabricator, and a phabread command which prints a stack
12750 of revisions in a format suitable for hg import, and a phabupdate com‐
12751 mand to update statuses in batch.
12752 A "phabstatus" view for hg show is also provided; it displays status
12754 information of Phabricator differentials associated with unfinished
12755 changesets.
12756 By default, Phabricator requires Test Plan which might prevent some
12758 changeset from being sent. The requirement could be disabled by chang‐
12759 ing differential.require-test-plan-field config server side.
12760 Config:
12762 [phabricator]
12764 # Phabricator URL
12765 url = https://phab.example.com/
12766 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
12768 # callsign is "FOO".
12769 callsign = FOO
12770 # curl command to use. If not set (default), use builtin HTTP library to
12772 # communicate. If set, use the specified curl command. This could be useful
12773 # if you need to specify advanced options that is not easily supported by
12774 # the internal library.
12775 curlcmd = curl --connect-timeout 2 --retry 3 --silent
12776 # retry failed command N time (default 0). Useful when using the extension
12778 # over flakly connection.
12779 #
12780 # We wait `retry.interval` between each retry, in seconds.
12781 # (default 1 second).
12782 retry = 3
12783 retry.interval = 10
12784 # the retry option can combine well with the http.timeout one.
12786 #
12787 # For example to give up on http request after 20 seconds:
12788 [http]
12789 timeout=20
12790 [auth]
12792 example.schemes = https
12793 example.prefix = phab.example.com
12794 # API token. Get it from https://$HOST/conduit/login/
12796 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
12797 Commands
12799 Change import/export
12800 phabimport
12801 import patches from Phabricator for the specified Differential Revi‐
12802 sions:
12803 hg phabimport DREVSPEC... [OPTIONS]
12805 The patches are read and applied starting at the parent of the working
12807 directory.
12808 See hg help phabread for how to specify DREVSPEC.
12810 Options:
12812 --stack
12814 import dependencies as well
12815 --test-vcr <VALUE>
12817 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12818 script, otherwise will mock all http requests using the speci‐
12819 fied vcr file. (ADVANCED)
12820 phabread
12822 print patches from Phabricator suitable for importing:
12823 hg phabread DREVSPEC... [OPTIONS]
12825 DREVSPEC could be a Differential Revision identity, like D123, or just
12827 the number 123. It could also have common operators like +, -, &, (, )
12828 for complex queries. Prefix : could be used to select a stack. If mul‐
12829 tiple DREVSPEC values are given, the result is the union of each indi‐
12830 vidually evaluated value. No attempt is currently made to reorder the
12831 values to run from parent to child.
12832 abandoned, accepted, closed, needsreview, needsrevision could be used
12834 to filter patches by status. For performance reason, they only repre‐
12835 sent a subset of non-status selections and cannot be used alone.
12836 For example, :D6+8-(2+D4) selects a stack up to D6, plus D8 and exclude
12838 D2 and D4. :D9 & needsreview selects "Needs Review" revisions in a
12839 stack up to D9.
12840 If --stack is given, follow dependencies information and read all
12842 patches. It is equivalent to the : operator.
12843 Options:
12845 --stack
12847 read dependencies
12848 --test-vcr <VALUE>
12850 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12851 script, otherwise will mock all http requests using the speci‐
12852 fied vcr file. (ADVANCED)
12853 phabsend
12855 upload changesets to Phabricator:
12856 hg phabsend REV [OPTIONS]
12858 If there are multiple revisions specified, they will be send as a stack
12860 with a linear dependencies relationship using the order specified by
12861 the revset.
12862 For the first time uploading changesets, local tags will be created to
12864 maintain the association. After the first time, phabsend will check ob‐
12865 sstore and tags information so it can figure out whether to update an
12866 existing Differential Revision, or create a new one.
12867 If --amend is set, update commit messages so they have the Differential
12869 Revision URL, remove related tags. This is similar to what arcanist
12870 will do, and is more desired in author-push workflows. Otherwise, use
12871 local tags to record the Differential Revision association.
12872 The --confirm option lets you confirm changesets before sending them.
12874 You can also add following to your configuration file to make it de‐
12875 fault behaviour:
12876 [phabsend]
12878 confirm = true
12879 By default, a separate review will be created for each commit that is
12881 selected, and will have the same parent/child relationship in Phabrica‐
12882 tor. If --fold is set, multiple commits are rolled up into a single
12883 review as if diffed from the parent of the first revision to the last.
12884 The commit messages are concatenated in the summary field on Phabrica‐
12885 tor.
12886 phabsend will check obsstore and the above association to decide
12888 whether to update an existing Differential Revision, or create a new
12889 one.
12890 Options:
12892 -r,--rev <REV[+]>
12894 revisions to send
12895 --amend
12897 update commit messages (default: True)
12898 --reviewer <VALUE[+]>
12900 specify reviewers
12901 --blocker <VALUE[+]>
12903 specify blocking reviewers
12904 -m,--comment <VALUE>
12906 add a comment to Revisions with new/updated Diffs
12907 --confirm
12909 ask for confirmation before sending
12910 --fold combine the revisions into one review
12912 --test-vcr <VALUE>
12914 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12915 script, otherwise will mock all http requests using the speci‐
12916 fied vcr file. (ADVANCED)
12917 [+] marked option can be specified multiple times
12919 phabupdate
12921 update Differential Revision in batch:
12922 hg phabupdate [DREVSPEC...| -r REV...] [OPTIONS]
12924 DREVSPEC selects revisions. See hg help phabread for its usage.
12926 Options:
12928 --accept
12930 accept revisions
12931 --reject
12933 reject revisions
12934 --request-review
12936 request review on revisions
12937 --abandon
12939 abandon revisions
12940 --reclaim
12942 reclaim revisions
12943 --close
12945 close revisions
12946 --reopen
12948 reopen revisions
12949 --plan-changes
12951 plan changes for revisions
12952 --resign
12954 resign as a reviewer from revisions
12955 --commandeer
12957 commandeer revisions
12958 -m,--comment <VALUE>
12960 comment on the last revision
12961 -r,--rev <REV>
12963 local revision to update
12964 --test-vcr <VALUE>
12966 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12967 script, otherwise will mock all http requests using the speci‐
12968 fied vcr file. (ADVANCED)
12969 Uncategorized commands
12971 purge
12972 command to delete untracked files from the working directory
12973 Commands
12975 Working directory management
12976 purge
12977 removes files not tracked by Mercurial:
12978 hg purge [OPTION]... [DIR]...
12980 Delete files not known to Mercurial. This is useful to test local and
12982 uncommitted changes in an otherwise-clean source tree.
12983 This means that purge will delete the following by default:
12985 • Unknown files: files marked with "?" by hg status
12987 • Empty directories: in fact Mercurial ignores directories unless they
12989 contain files under source control management
12990 But it will leave untouched:
12992 • Modified and unmodified tracked files
12994 • Ignored files (unless -i or --all is specified)
12996 • New files added to the repository (with hg add)
12998 The --files and --dirs options can be used to direct purge to delete
13000 only files, only directories, or both. If neither option is given, both
13001 will be deleted.
13002 If directories are given on the command line, only files in these di‐
13004 rectories are considered.
13005 Be careful with purge, as you could irreversibly delete some files you
13007 forgot to add to the repository. If you only want to print the list of
13008 files that this program would delete, use the --print option.
13009 Options:
13011 -a, --abort-on-err
13013 abort if an error occurs
13014 --all purge ignored files too
13016 -i, --ignored
13018 purge only ignored files
13019 --dirs purge empty directories
13021 --files
13023 purge files
13024 -p, --print
13026 print filenames instead of deleting them
13027 -0, --print0
13029 end filenames with NUL, for use with xargs (implies -p/--print)
13030 -I,--include <PATTERN[+]>
13032 include names matching the given patterns
13033 -X,--exclude <PATTERN[+]>
13035 exclude names matching the given patterns
13036 [+] marked option can be specified multiple times
13038 aliases: clean
13040 rebase
13042 command to move sets of revisions to a different ancestor
13043 This extension lets you rebase changesets in an existing Mercurial
13045 repository.
13046 For more information: https://mercurial-scm.org/wiki/RebaseExtension
13048 Commands
13050 Change manipulation
13051 rebase
13052 move changeset (and descendants) to a different branch:
13053 hg rebase [[-s REV]... | [-b REV]... | [-r REV]...] [-d REV] [OPTION]...
13055 Rebase uses repeated merging to graft changesets from one part of his‐
13057 tory (the source) onto another (the destination). This can be useful
13058 for linearizing local changes relative to a master development tree.
13059 Published commits cannot be rebased (see hg help phases). To copy com‐
13061 mits, see hg help graft.
13062 If you don't specify a destination changeset (-d/--dest), rebase will
13064 use the same logic as hg merge to pick a destination. if the current
13065 branch contains exactly one other head, the other head is merged with
13066 by default. Otherwise, an explicit revision with which to merge with
13067 must be provided. (destination changeset is not modified by rebasing,
13068 but new changesets are added as its descendants.)
13069 Here are the ways to select changesets:
13071 1. Explicitly select them using --rev.
13073 2. Use --source to select a root changeset and include all of its
13075 descendants.
13076 3. Use --base to select a changeset; rebase will find ancestors and
13078 their descendants which are not also ancestors of the destina‐
13079 tion.
13080 4. If you do not specify any of --rev, --source, or --base, rebase
13082 will use --base . as above.
13083 If --source or --rev is used, special names SRC and ALLSRC can be used
13085 in --dest. Destination would be calculated per source revision with SRC
13086 substituted by that single source revision and ALLSRC substituted by
13087 all source revisions.
13088 Rebase will destroy original changesets unless you use --keep. It will
13090 also move your bookmarks (even if you do).
13091 Some changesets may be dropped if they do not contribute changes (e.g.
13093 merges from the destination branch).
13094 Unlike merge, rebase will do nothing if you are at the branch tip of a
13096 named branch with two heads. You will need to explicitly specify source
13097 and/or destination.
13098 If you need to use a tool to automate merge/conflict decisions, you can
13100 specify one with --tool, see hg help merge-tools. As a caveat: the
13101 tool will not be used to mediate when a file was deleted, there is no
13102 hook presently available for this.
13103 If a rebase is interrupted to manually resolve a conflict, it can be
13105 continued with --continue/-c, aborted with --abort/-a, or stopped with
13106 --stop.
13107 Examples:
13109 • move "local changes" (current commit back to branching point) to the
13111 current branch tip after a pull:
13112 hg rebase
13114 • move a single changeset to the stable branch:
13116 hg rebase -r 5f493448 -d stable
13118 • splice a commit and all its descendants onto another part of history:
13120 hg rebase --source c0c3 --dest 4cf9
13122 • rebase everything on a branch marked by a bookmark onto the default
13124 branch:
13125 hg rebase --base myfeature --dest default
13127 • collapse a sequence of changes into a single commit:
13129 hg rebase --collapse -r 1520:1525 -d .
13131 • move a named branch while preserving its name:
13133 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
13135 • stabilize orphaned changesets so history looks linear:
13137 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
13139 Configuration Options:
13141 You can make rebase require a destination if you set the following con‐
13143 fig option:
13144 [commands]
13146 rebase.requiredest = True
13147 By default, rebase will close the transaction after each commit. For
13149 performance purposes, you can configure rebase to use a single transac‐
13150 tion across the entire rebase. WARNING: This setting introduces a sig‐
13151 nificant risk of losing the work you've done in a rebase if the rebase
13152 aborts unexpectedly:
13153 [rebase]
13155 singletransaction = True
13156 By default, rebase writes to the working copy, but you can configure it
13158 to run in-memory for better performance. When the rebase is not moving
13159 the parent(s) of the working copy (AKA the "currently checked out
13160 changesets"), this may also allow it to run even if the working copy is
13161 dirty:
13162 [rebase]
13164 experimental.inmemory = True
13165 Return Values:
13167 Returns 0 on success, 1 if nothing to rebase or there are unresolved
13169 conflicts.
13170 Options:
13172 -s,--source <REV[+]>
13174 rebase the specified changesets and their descendants
13175 -b,--base <REV[+]>
13177 rebase everything from branching point of specified changeset
13178 -r,--rev <REV[+]>
13180 rebase these revisions
13181 -d,--dest <REV>
13183 rebase onto the specified changeset
13184 --collapse
13186 collapse the rebased changesets
13187 -m,--message <TEXT>
13189 use text as collapse commit message
13190 -e, --edit
13192 invoke editor on commit messages
13193 -l,--logfile <FILE>
13195 read collapse commit message from file
13196 -k, --keep
13198 keep original changesets
13199 --keepbranches
13201 keep original branch names
13202 -D, --detach
13204 (DEPRECATED)
13205 -i, --interactive
13207 (DEPRECATED)
13208 -t,--tool <VALUE>
13210 specify merge tool
13211 --stop stop interrupted rebase
13213 -c, --continue
13215 continue an interrupted rebase
13216 -a, --abort
13218 abort an interrupted rebase
13219 --auto-orphans <VALUE>
13221 automatically rebase orphan revisions in the specified revset
13222 (EXPERIMENTAL)
13223 -n, --dry-run
13225 do not perform actions, just print output
13226 -T,--template <TEMPLATE>
13228 display with template
13229 --confirm
13231 ask before applying actions
13232 [+] marked option can be specified multiple times
13234 record
13236 commands to interactively select changes for commit/qrefresh (DEPRE‐
13237 CATED)
13238 The feature provided by this extension has been moved into core Mercu‐
13240 rial as hg commit --interactive.
13241 Commands
13243 Change creation
13244 qrecord
13245 interactively record a new patch:
13246 hg qrecord [OPTION]... PATCH [FILE]...
13248 See hg help qnew & hg help record for more information and usage.
13250 record
13252 interactively select changes to commit:
13253 hg record [OPTION]... [FILE]...
13255 If a list of files is omitted, all changes reported by hg status will
13257 be candidates for recording.
13258 See hg help dates for a list of formats valid for -d/--date.
13260 If using the text interface (see hg help config), you will be prompted
13262 for whether to record changes to each modified file, and for files with
13263 multiple changes, for each change to use. For each query, the following
13264 responses are possible:
13265 y - record this change
13267 n - skip this change
13268 e - edit this change manually
13269 s - skip remaining changes to this file
13271 f - record remaining changes to this file
13272 d - done, skip remaining changes and files
13274 a - record all changes to all remaining files
13275 q - quit, recording no changes
13276 ? - display help
13278 This command is not available when committing a merge.
13280 Options:
13282 -A, --addremove
13284 mark new/missing files as added/removed before committing
13285 --close-branch
13287 mark a branch head as closed
13288 --amend
13290 amend the parent of the working directory
13291 -s, --secret
13293 use the secret phase for committing
13294 -e, --edit
13296 invoke editor on commit messages
13297 --force-close-branch
13299 forcibly close branch from a non-head changeset (ADVANCED)
13300 -I,--include <PATTERN[+]>
13302 include names matching the given patterns
13303 -X,--exclude <PATTERN[+]>
13305 exclude names matching the given patterns
13306 -m,--message <TEXT>
13308 use text as commit message
13309 -l,--logfile <FILE>
13311 read commit message from file
13312 -d,--date <DATE>
13314 record the specified date as commit date
13315 -u,--user <USER>
13317 record the specified user as committer
13318 -S, --subrepos
13320 recurse into subrepositories
13321 -w, --ignore-all-space
13323 ignore white space when comparing lines
13324 -b, --ignore-space-change
13326 ignore changes in the amount of white space
13327 -B, --ignore-blank-lines
13329 ignore changes whose lines are all blank
13330 -Z, --ignore-space-at-eol
13332 ignore changes in whitespace at EOL
13333 [+] marked option can be specified multiple times
13335 releasenotes
13337 generate release notes from commit messages (EXPERIMENTAL)
13338 It is common to maintain files detailing changes in a project between
13340 releases. Maintaining these files can be difficult and time consuming.
13341 The hg releasenotes command provided by this extension makes the
13342 process simpler by automating it.
13343 Commands
13345 Change navigation
13346 releasenotes
13347 parse release notes from commit messages into an output file:
13348 hg releasenotes [-r REV] [-c] FILE
13350 Given an output file and set of revisions, this command will parse com‐
13352 mit messages for release notes then add them to the output file.
13353 Release notes are defined in commit messages as ReStructuredText direc‐
13355 tives. These have the form:
13356 .. directive:: title
13358 content
13360 Each directive maps to an output section in a generated release notes
13362 file, which itself is ReStructuredText. For example, the .. feature::
13363 directive would map to a New Features section.
13364 Release note directives can be either short-form or long-form. In
13366 short- form, title is omitted and the release note is rendered as a
13367 bullet list. In long form, a sub-section with the title title is added
13368 to the section.
13369 The FILE argument controls the output file to write gathered release
13371 notes to. The format of the file is:
13372 Section 1
13374 =========
13375 ...
13377 Section 2
13379 =========
13380 ...
13382 Only sections with defined release notes are emitted.
13384 If a section only has short-form notes, it will consist of bullet list:
13386 Section
13388 =======
13389 * Release note 1
13391 * Release note 2
13392 If a section has long-form notes, sub-sections will be emitted:
13394 Section
13396 =======
13397 Note 1 Title
13399 ------------
13400 Description of the first long-form note.
13402 Note 2 Title
13404 ------------
13405 Description of the second long-form note.
13407 If the FILE argument points to an existing file, that file will be
13409 parsed for release notes having the format that would be generated by
13410 this command. The notes from the processed commit messages will be
13411 merged into this parsed set.
13412 During release notes merging:
13414 • Duplicate items are automatically ignored
13416 • Items that are different are automatically ignored if the similarity
13418 is greater than a threshold.
13419 This means that the release notes file can be updated independently
13421 from this command and changes should not be lost when running this com‐
13422 mand on that file. A particular use case for this is to tweak the word‐
13423 ing of a release note after it has been added to the release notes
13424 file.
13425 The -c/--check option checks the commit message for invalid admoni‐
13427 tions.
13428 The -l/--list option, presents the user with a list of existing avail‐
13430 able admonitions along with their title. This also includes the custom
13431 admonitions (if any).
13432 Options:
13434 -r,--rev <REV>
13436 revisions to process for release notes
13437 -c, --check
13439 checks for validity of admonitions (if any)
13440 -l, --list
13442 list the available admonitions with their title
13443 Uncategorized commands
13445 relink
13446 recreates hardlinks between repository clones
13447 Commands
13449 Repository maintenance
13450 relink
13451 recreate hardlinks between two repositories:
13452 hg relink [ORIGIN]
13454 When repositories are cloned locally, their data files will be
13456 hardlinked so that they only use the space of a single repository.
13457 Unfortunately, subsequent pulls into either repository will break
13459 hardlinks for any files touched by the new changesets, even if both
13460 repositories end up pulling the same changes.
13461 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
13463 falling back to a complete copy of the source repository.
13464 This command lets you recreate those hardlinks and reclaim that wasted
13466 space.
13467 This repository will be relinked to share space with ORIGIN, which must
13469 be on the same local disk. If ORIGIN is omitted, looks for "default-re‐
13470 link", then "default", in [paths].
13471 Do not attempt any read operations on this repository while the command
13473 is running. (Both repositories will be locked against writes.)
13474 remotefilelog
13476 remotefilelog causes Mercurial to lazilly fetch file contents (EXPERI‐
13477 MENTAL)
13478 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13480 BILITY GUARANTEES. This means that repositories created with this ex‐
13481 tension may only be usable with the exact version of this exten‐
13482 sion/Mercurial that was used. The extension attempts to enforce this in
13483 order to prevent repository corruption.
13484 remotefilelog works by fetching file contents lazily and storing them
13486 in a cache on the client rather than in revlogs. This allows enormous
13487 histories to be transferred only partially, making them easier to oper‐
13488 ate on.
13489 Configs:
13491 packs.maxchainlen specifies the maximum delta chain length in pack
13493 files
13494 packs.maxpacksize specifies the maximum pack file size
13496 packs.maxpackfilecount specifies the maximum number of packs in the
13498 shared cache (trees only for now)
13500 remotefilelog.backgroundprefetch runs prefetch in background when
13502 True
13503 remotefilelog.bgprefetchrevs specifies revisions to fetch on commit
13505 and
13506 update, and on other commands that use them. Different from
13508 pullprefetch.
13509 remotefilelog.gcrepack does garbage collection during repack when
13511 True
13512 remotefilelog.nodettl specifies maximum TTL of a node in seconds be‐
13514 fore
13515 it is garbage collected
13517 remotefilelog.repackonhggc runs repack on hg gc when True
13519 remotefilelog.prefetchdays specifies the maximum age of a commit in
13521 days after which it is no longer prefetched.
13523 remotefilelog.prefetchdelay specifies delay between background
13525 prefetches in seconds after operations that change the work‐
13527 ing copy parent
13528 remotefilelog.data.gencountlimit constraints the minimum number of
13530 data
13531 pack files required to be considered part of a generation. In
13533 particular, minimum number of packs files > gencountlimit.
13534 remotefilelog.data.generations list for specifying the lower bound
13536 of
13537 each generation of the data pack files. For example, list
13539 ['100MB','1MB'] or ['1MB', '100MB'] will lead to three gener‐
13540 ations: [0, 1MB), [ 1MB, 100MB) and [100MB, infinity).
13541 remotefilelog.data.maxrepackpacks the maximum number of pack files
13543 to
13544 include in an incremental data repack.
13546 remotefilelog.data.repackmaxpacksize the maximum size of a pack file
13548 for
13549 it to be considered for an incremental data repack.
13551 remotefilelog.data.repacksizelimit the maximum total size of pack
13553 files
13554 to include in an incremental data repack.
13556 remotefilelog.history.gencountlimit constraints the minimum number
13558 of
13559 history pack files required to be considered part of a gener‐
13561 ation. In particular, minimum number of packs files > gen‐
13562 countlimit.
13563 remotefilelog.history.generations list for specifying the lower
13565 bound of
13566 each generation of the history pack files. For example, list
13568 [ '100MB', '1MB'] or ['1MB', '100MB'] will lead to three gen‐
13569 erations: [ 0, 1MB), [1MB, 100MB) and [100MB, infinity).
13570 remotefilelog.history.maxrepackpacks the maximum number of pack
13572 files to
13573 include in an incremental history repack.
13575 remotefilelog.history.repackmaxpacksize the maximum size of a pack
13577 file
13578 for it to be considered for an incremental history repack.
13580 remotefilelog.history.repacksizelimit the maximum total size of pack
13582 files to include in an incremental history repack.
13584 remotefilelog.backgroundrepack automatically consolidate packs in
13586 the
13587 background
13589 remotefilelog.cachepath path to cache
13591 remotefilelog.cachegroup if set, make cache directory sgid to this
13593 group
13595 remotefilelog.cacheprocess binary to invoke for fetching file data
13597 remotefilelog.debug turn on remotefilelog-specific debug output
13599 remotefilelog.excludepattern pattern of files to exclude from pulls
13601 remotefilelog.includepattern pattern of files to include in pulls
13603 remotefilelog.fetchwarning: message to print when too many
13605 single-file fetches occur
13607 remotefilelog.getfilesstep number of files to request in a single
13609 RPC
13610 remotefilelog.getfilestype if set to 'threaded' use threads to fetch
13612 files, otherwise use optimistic fetching
13614 remotefilelog.pullprefetch revset for selecting files that should be
13616 eagerly downloaded rather than lazily
13618 remotefilelog.reponame name of the repo. If set, used to partition
13620 data from other repos in a shared store.
13622 remotefilelog.server if true, enable server-side functionality
13624 remotefilelog.servercachepath path for caching blobs on the server
13626 remotefilelog.serverexpiration number of days to keep cached server
13628 blobs
13630 remotefilelog.validatecache if set, check cache entries for corrup‐
13632 tion
13633 before returning blobs
13635 remotefilelog.validatecachelog if set, check cache entries for
13637 corruption before returning metadata
13639 Commands
13641 Repository maintenance
13642 prefetch
13643 prefetch file revisions from the server:
13644 hg prefetch [OPTIONS] [FILE...]
13646 Prefetchs file revisions for the specified revs and stores them in the
13648 local remotefilelog cache. If no rev is specified, the default rev is
13649 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
13650 File names or patterns can be used to limit which files are downloaded.
13651 Return 0 on success.
13653 Options:
13655 -r,--rev <REV[+]>
13657 prefetch the specified revisions
13658 --repack
13660 run repack after prefetch
13661 -b,--base <VALUE>
13663 rev that is assumed to already be local
13664 -I,--include <PATTERN[+]>
13666 include names matching the given patterns
13667 -X,--exclude <PATTERN[+]>
13669 exclude names matching the given patterns
13670 [+] marked option can be specified multiple times
13672 Uncategorized commands
13674 gc
13675 garbage collect the client and server filelog caches:
13676 hg gc [REPO...]
13678 garbage collect the client and server filelog caches
13680 repack
13682 hg repack [OPTIONS]
13683 Options:
13685 --background
13687 run in a background process
13688 --incremental
13690 do an incremental repack
13691 --packsonly
13693 only repack packs (skip loose objects)
13694 verifyremotefilelog
13696 hg verifyremotefilelogs <directory>
13697 Options:
13699 -d, --decompress
13701 decompress the filelogs first
13702 remotenames
13704 showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)
13705 By default both remotebookmarks and remotebranches are turned on. Con‐
13707 fig knob to control the individually are as follows.
13708 Config options to tweak the default behaviour:
13710 remotenames.bookmarks
13712 Boolean value to enable or disable showing of remotebookmarks
13713 (default: True)
13714 remotenames.branches
13716 Boolean value to enable or disable showing of remotebranches
13717 (default: True)
13718 remotenames.hoistedpeer
13720 Name of the peer whose remotebookmarks should be hoisted into
13721 the top-level namespace (default: 'default')
13722 schemes
13724 extend schemes with shortcuts to repository swarms
13725 This extension allows you to specify shortcuts for parent URLs with a
13727 lot of repositories to act like a scheme, for example:
13728 [schemes]
13730 py = http://code.python.org/hg/
13731 After that you can use it like:
13733 hg clone py://trunk/
13735 Additionally there is support for some more complex schemas, for exam‐
13737 ple used by Google Code:
13738 [schemes]
13740 gcode = http://{1}.googlecode.com/hg/
13741 The syntax is taken from Mercurial templates, and you have unlimited
13743 number of variables, starting with {1} and continuing with {2}, {3} and
13744 so on. This variables will receive parts of URL supplied, split by /.
13745 Anything not specified as {part} will be just appended to an URL.
13746 For convenience, the extension adds these schemes by default:
13748 [schemes]
13750 py = http://hg.python.org/
13751 bb = https://bitbucket.org/
13752 bb+ssh = ssh://hg@bitbucket.org/
13753 gcode = https://{1}.googlecode.com/hg/
13754 kiln = https://{1}.kilnhg.com/Repo/
13755 You can override a predefined scheme by defining a new scheme with the
13757 same name.
13758 Commands
13760 Uncategorized commands
13761 share
13762 share a common history between several working directories
13763 The share extension introduces a new command hg share to create a new
13765 working directory. This is similar to hg clone, but doesn't involve
13766 copying or linking the storage of the repository. This allows working
13767 on different branches or changes in parallel without the associated
13768 cost in terms of disk space.
13769 Note: destructive operations or extensions like hg rollback should be
13771 used with care as they can result in confusing problems.
13772 Automatic Pooled Storage for Clones
13774 When this extension is active, hg clone can be configured to automati‐
13775 cally share/pool storage across multiple clones. This mode effectively
13776 converts hg clone to hg clone + hg share. The benefit of using this
13777 mode is the automatic management of store paths and intelligent pooling
13778 of related repositories.
13779 The following share. config options influence this feature:
13781 share.pool
13783 Filesystem path where shared repository data will be stored.
13785 When defined, hg clone will automatically use shared repository
13786 storage instead of creating a store inside each clone.
13787 share.poolnaming
13789 How directory names in share.pool are constructed.
13791 "identity" means the name is derived from the first changeset in
13793 the repository. In this mode, different remotes share storage if
13794 their root/initial changeset is identical. In this mode, the lo‐
13795 cal shared repository is an aggregate of all encountered remote
13796 repositories.
13797 "remote" means the name is derived from the source repository's
13799 path or URL. In this mode, storage is only shared if the path or
13800 URL requested in the hg clone command matches exactly to a
13801 repository that was cloned before.
13802 The default naming mode is "identity".
13804 Sharing requirements and configs of source repository with shares:
13806 By default creating a shared repository only enables sharing a common
13808 history and does not share requirements and configs between them. This
13809 may lead to problems in some cases, for example when you upgrade the
13810 storage format from one repository but does not set related configs in
13811 the shares.
13812 Setting format.exp-share-safe = True enables sharing configs and re‐
13814 quirements. This only applies to shares which are done after enabling
13815 the config option.
13816 For enabling this in existing shares, enable the config option and re‐
13818 share.
13819 For resharing existing shares, make sure your working directory is
13821 clean and there are no untracked files, delete that share and create a
13822 new share.
13823 Commands
13825 Repository creation
13826 share
13827 create a new shared repository:
13828 hg share [-U] [-B] SOURCE [DEST]
13830 Initialize a new repository and working directory that shares its his‐
13832 tory (and optionally bookmarks) with another repository.
13833 Note using rollback or extensions that destroy/modify history (mq,
13835 rebase, etc.) can cause considerable confusion with shared
13836 clones. In particular, if two shared clones are both updated to
13837 the same changeset, and one of them destroys that changeset with
13838 rollback, the other clone will suddenly stop working: all opera‐
13839 tions will fail with "abort: working directory has unknown par‐
13840 ent". The only known workaround is to use debugsetparents on the
13841 broken clone to reset it to a changeset that still exists.
13842 Options:
13844 -U, --noupdate
13846 do not create a working directory
13847 -B, --bookmarks
13849 also share bookmarks
13850 --relative
13852 point to source using a relative path
13853 Repository maintenance
13855 unshare
13856 convert a shared repository to a normal one:
13857 hg unshare
13859 Copy the store data to the repo and remove the sharedpath data.
13861 show
13863 unified command to show various repository information (EXPERIMENTAL)
13864 This extension provides the hg show command, which provides a central
13866 command for displaying commonly-accessed repository data and views of
13867 that data.
13868 The following config options can influence operation.
13870 commands
13872 show.aliasprefix
13873 List of strings that will register aliases for views. e.g. s
13875 will effectively set config options alias.s<view> = show <view>
13876 for all views. i.e. hg swork would execute hg show work.
13877 Aliases that would conflict with existing registrations will not
13879 be performed.
13880 Commands
13882 Change navigation
13883 show
13884 show various repository information:
13885 hg show VIEW
13887 A requested view of repository data is displayed.
13889 If no view is requested, the list of available views is shown and the
13891 command aborts.
13892 Note There are no backwards compatibility guarantees for the output
13894 of this command. Output may change in any future Mercurial re‐
13895 lease.
13896 Consumers wanting stable command output should specify a tem‐
13898 plate via -T/--template.
13899 List of available views:
13901 bookmarks bookmarks and their associated changeset
13903 stack current line of work
13905 work changesets that aren't finished
13907 Options:
13909 -T,--template <TEMPLATE>
13911 display with template
13912 sparse
13914 allow sparse checkouts of the working directory (EXPERIMENTAL)
13915 (This extension is not yet protected by backwards compatibility guaran‐
13917 tees. Any aspect may break in future releases until this notice is re‐
13918 moved.)
13919 This extension allows the working directory to only consist of a subset
13921 of files for the revision. This allows specific files or directories to
13922 be explicitly included or excluded. Many repository operations have
13923 performance proportional to the number of files in the working direc‐
13924 tory. So only realizing a subset of files in the working directory can
13925 improve performance.
13926 Sparse Config Files
13928 The set of files that are part of a sparse checkout are defined by a
13929 sparse config file. The file defines 3 things: includes (files to in‐
13930 clude in the sparse checkout), excludes (files to exclude from the
13931 sparse checkout), and profiles (links to other config files).
13932 The file format is newline delimited. Empty lines and lines beginning
13934 with # are ignored.
13935 Lines beginning with %include `` denote another sparse config file to
13937 include. e.g. ``%include tests.sparse. The filename is relative to the
13938 repository root.
13939 The special lines [include] and [exclude] denote the section for in‐
13941 cludes and excludes that follow, respectively. It is illegal to have
13942 [include] after [exclude].
13943 Non-special lines resemble file patterns to be added to either includes
13945 or excludes. The syntax of these lines is documented by hg help pat‐
13946 terns. Patterns are interpreted as glob: by default and match against
13947 the root of the repository.
13948 Exclusion patterns take precedence over inclusion patterns. So even if
13950 a file is explicitly included, an [exclude] entry can remove it.
13951 For example, say you have a repository with 3 directories, frontend/,
13953 backend/, and tools/. frontend/ and backend/ correspond to different
13954 projects and it is uncommon for someone working on one to need the
13955 files for the other. But tools/ contains files shared between both
13956 projects. Your sparse config files may resemble:
13957 # frontend.sparse
13959 frontend/**
13960 tools/**
13961 # backend.sparse
13963 backend/**
13964 tools/**
13965 Say the backend grows in size. Or there's a directory with thousands of
13967 files you wish to exclude. You can modify the profile to exclude cer‐
13968 tain files:
13969 [include]
13971 backend/**
13972 tools/**
13973 [exclude]
13975 tools/tests/**
13976 Commands
13978 Uncategorized commands
13979 split
13980 command to split a changeset into smaller ones (EXPERIMENTAL)
13981 Commands
13983 Change manipulation
13984 split
13985 split a changeset into smaller ones:
13986 hg split [--no-rebase] [[-r] REV]
13988 Repeatedly prompt changes and commit message for new changesets until
13990 there is nothing left in the original changeset.
13991 If --rev was not given, split the working directory parent.
13993 By default, rebase connected non-obsoleted descendants onto the new
13995 changeset. Use --no-rebase to avoid the rebase.
13996 Options:
13998 -r,--rev <REV>
14000 revision to split
14001 --rebase
14003 rebase descendants after split (default: True)
14004 -d,--date <DATE>
14006 record the specified date as commit date
14007 -u,--user <USER>
14009 record the specified user as committer
14010 sqlitestore
14012 store repository data in SQLite (EXPERIMENTAL)
14013 The sqlitestore extension enables the storage of repository data in
14015 SQLite.
14016 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
14018 BILITY GUARANTEES. This means that repositories created with this ex‐
14019 tension may only be usable with the exact version of this exten‐
14020 sion/Mercurial that was used. The extension attempts to enforce this in
14021 order to prevent repository corruption.
14022 In addition, several features are not yet supported or have known bugs:
14024 • Only some data is stored in SQLite. Changeset, manifest, and other
14026 repository data is not yet stored in SQLite.
14027 • Transactions are not robust. If the process is aborted at the right
14029 time during transaction close/rollback, the repository could be in an
14030 inconsistent state. This problem will diminish once all repository
14031 data is tracked by SQLite.
14032 • Bundle repositories do not work (the ability to use e.g. hg -R <bun‐
14034 dle-file> log to automatically overlay a bundle on top of the exist‐
14035 ing repository).
14036 • Various other features don't work.
14038 This extension should work for basic clone/pull, update, and commit
14040 workflows. Some history rewriting operations may fail due to lack of
14041 support for bundle repositories.
14042 To use, activate the extension and set the storage.new-repo-backend
14044 config option to sqlite to enable new repositories to use SQLite for
14045 storage.
14046 strip
14048 strip changesets and their descendants from history (DEPRECATED)
14049 The functionality of this extension has been included in core Mercurial
14051 since version 5.7. Please use hg debugstrip ... instead.
14052 This extension allows you to strip changesets and all their descendants
14054 from the repository. See the command help for details.
14055 transplant
14057 command to transplant changesets from another branch
14058 This extension allows you to transplant changes to another parent revi‐
14060 sion, possibly in another repository. The transplant is done using
14061 'diff' patches.
14062 Transplanted patches are recorded in .hg/transplant/transplants, as a
14064 map from a changeset hash to its hash in the source repository.
14065 Commands
14067 Change manipulation
14068 transplant
14069 transplant changesets from another branch:
14070 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
14072 Selected changesets will be applied on top of the current working di‐
14074 rectory with the log of the original changeset. The changesets are
14075 copied and will thus appear twice in the history with different identi‐
14076 ties.
14077 Consider using the graft command if everything is inside the same
14079 repository - it will use merges and will usually give a better result.
14080 Use the rebase extension if the changesets are unpublished and you want
14081 to move them instead of copying them.
14082 If --log is specified, log messages will have a comment appended of the
14084 form:
14085 (transplanted from CHANGESETHASH)
14087 You can rewrite the changelog message with the --filter option. Its
14089 argument will be invoked with the current changelog message as $1 and
14090 the patch as $2.
14091 --source/-s specifies another repository to use for selecting change‐
14093 sets, just as if it temporarily had been pulled. If --branch/-b is
14094 specified, these revisions will be used as heads when deciding which
14095 changesets to transplant, just as if only these revisions had been
14096 pulled. If --all/-a is specified, all the revisions up to the heads
14097 specified with --branch will be transplanted.
14098 Example:
14100 • transplant all changes up to REV on top of your current revision:
14102 hg transplant --branch REV --all
14104 You can optionally mark selected transplanted changesets as merge
14106 changesets. You will not be prompted to transplant any ancestors of a
14107 merged transplant, and you can merge descendants of them normally in‐
14108 stead of transplanting them.
14109 Merge changesets may be transplanted directly by specifying the proper
14111 parent changeset by calling hg transplant --parent.
14112 If no merges or revisions are provided, hg transplant will start an in‐
14114 teractive changeset browser.
14115 If a changeset application fails, you can fix the merge by hand and
14117 then resume where you left off by calling hg transplant --continue/-c.
14118 Options:
14120 -s,--source <REPO>
14122 transplant changesets from REPO
14123 -b,--branch <REV[+]>
14125 use this source changeset as head
14126 -a, --all
14128 pull all changesets up to the --branch revisions
14129 -p,--prune <REV[+]>
14131 skip over REV
14132 -m,--merge <REV[+]>
14134 merge at REV
14135 --parent <REV>
14137 parent to choose when transplanting merge
14138 -e, --edit
14140 invoke editor on commit messages
14141 --log append transplant info to log message
14143 --stop stop interrupted transplant
14145 -c, --continue
14147 continue last transplant session after fixing conflicts
14148 --filter <CMD>
14150 filter changesets through command
14151 [+] marked option can be specified multiple times
14153 uncommit
14155 uncommit part or all of a local changeset (EXPERIMENTAL)
14156 This command undoes the effect of a local commit, returning the af‐
14158 fected files to their uncommitted state. This means that files modi‐
14159 fied, added or removed in the changeset will be left unchanged, and so
14160 will remain modified, added and removed in the working directory.
14161 Commands
14163 Change manipulation
14164 unamend
14165 undo the most recent amend operation on a current changeset:
14166 hg unamend
14168 This command will roll back to the previous version of a changeset,
14170 leaving working directory in state in which it was before running hg
14171 amend (e.g. files modified as part of an amend will be marked as modi‐
14172 fied hg status)
14173 uncommit
14175 uncommit part or all of a local changeset:
14176 hg uncommit [OPTION]... [FILE]...
14178 This command undoes the effect of a local commit, returning the af‐
14180 fected files to their uncommitted state. This means that files modified
14181 or deleted in the changeset will be left unchanged, and so will remain
14182 modified in the working directory.
14183 If no files are specified, the commit will be pruned, unless --keep is
14185 given.
14186 Options:
14188 --keep allow an empty commit after uncommitting
14190 --allow-dirty-working-copy
14192 allow uncommit with outstanding changes
14193 -n,--note <TEXT>
14195 store a note on uncommit
14196 -I,--include <PATTERN[+]>
14198 include names matching the given patterns
14199 -X,--exclude <PATTERN[+]>
14201 exclude names matching the given patterns
14202 -m,--message <TEXT>
14204 use text as commit message
14205 -l,--logfile <FILE>
14207 read commit message from file
14208 -d,--date <DATE>
14210 record the specified date as commit date
14211 -u,--user <USER>
14213 record the specified user as committer
14214 -D, --currentdate
14216 record the current date as commit date
14217 -U, --currentuser
14219 record the current user as committer
14220 [+] marked option can be specified multiple times
14222 win32mbcs
14224 allow the use of MBCS paths with problematic encodings
14225 Some MBCS encodings are not good for some path operations (i.e. split‐
14227 ting path, case conversion, etc.) with its encoded bytes. We call such
14228 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
14229 extension can be used to fix the issue with those encodings by wrapping
14230 some functions to convert to Unicode string before path operation.
14231 This extension is useful for:
14233 • Japanese Windows users using shift_jis encoding.
14235 • Chinese Windows users using big5 encoding.
14237 • All users who use a repository with one of problematic encodings on
14239 case-insensitive file system.
14240 This extension is not needed for:
14242 • Any user who use only ASCII chars in path.
14244 • Any user who do not use any of problematic encodings.
14246 Note that there are some limitations on using this extension:
14248 • You should use single encoding in one repository.
14250 • If the repository path ends with 0x5c, .hg/hgrc cannot be read.
14252 • win32mbcs is not compatible with fixutf8 extension.
14254 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
14256 can specify the encoding by config option:
14257 [win32mbcs]
14259 encoding = sjis
14260 It is useful for the users who want to commit with UTF-8 log message.
14262 win32text
14264 perform automatic newline conversion (DEPRECATED)
14265 Deprecation: The win32text extension requires each user to configure
14267 the extension again and again for each clone since the configuration
14268 is not copied when cloning.
14269 We have therefore made the eol as an alternative. The eol uses a
14271 version controlled file for its configuration and each clone will
14272 therefore use the right settings from the start.
14273 To perform automatic newline conversion, use:
14275 [extensions]
14277 win32text =
14278 [encode]
14279 ** = cleverencode:
14280 # or ** = macencode:
14281 [decode]
14283 ** = cleverdecode:
14284 # or ** = macdecode:
14285 If not doing conversion, to make sure you do not commit CRLF/CR by ac‐
14287 cident:
14288 [hooks]
14290 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
14291 # or pretxncommit.cr = python:hgext.win32text.forbidcr
14292 To do the same check on a server to prevent CRLF/CR from being pushed
14294 or pulled:
14295 [hooks]
14297 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
14298 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
14299 zeroconf
14301 discover and advertise repositories on the local network
14302 The zeroconf extension will advertise hg serve instances over DNS-SD so
14304 that they can be discovered using the hg paths command without knowing
14305 the server's IP address.
14306 To allow other people to discover your repository using run hg serve in
14308 your repository:
14309 $ cd test
14311 $ hg serve
14312 You can discover Zeroconf-enabled repositories by running hg paths:
14314 $ hg paths
14316 zc-test = http://example.com:8000/test
14317
14319 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
14320 This file contains defaults and configuration. Values in
14322 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
14323 tings made in the global /etc/mercurial/hgrc configuration. See
14324 hgrc(5) for details of the contents and format of these files.
14325 .hgignore
14327 This file contains regular expressions (one per line) that de‐
14329 scribe file names that should be ignored by hg. For details, see
14330 hgignore(5).
14331 .hgsub
14333 This file defines the locations of all subrepositories, and
14335 tells where the subrepository checkouts came from. For details,
14336 see hg help subrepos.
14337 .hgsubstate
14339 This file is where Mercurial stores all nested repository
14341 states. NB: This file should not be edited manually.
14342 .hgtags
14344 This file contains changeset hash values and text tag names (one
14346 of each separated by spaces) that correspond to tagged versions
14347 of the repository contents. The file content is encoded using
14348 UTF-8.
14349 .hg/last-message.txt
14351 This file is used by hg commit to store a backup of the commit
14353 message in case the commit fails.
14354 .hg/localtags
14356 This file can be used to define local tags which are not shared
14358 among repositories. The file format is the same as for .hgtags,
14359 but it is encoded using the local system encoding.
14360 Some commands (e.g. revert) produce backup files ending in .orig, if
14362 the .orig file already exists and is not tracked by Mercurial, it will
14363 be overwritten.
14364
14366 Probably lots, please post them to the mailing list (see Resources
14367 below) when you find them.
14368
14370 hgignore(5), hgrc(5)
14371
14373 Written by Matt Mackall <mpm@selenic.com>
14374
14376 Main Web Site: https://mercurial-scm.org/
14377 Source code repository: https://www.mercurial-scm.org/repo/hg
14379 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
14381
14383 Copyright (C) 2005-2021 Matt Mackall. Free use of this software is
14384 granted under the terms of the GNU General Public License version 2 or
14385 any later version.
14386
14388 Matt Mackall <mpm@selenic.com>
14389 Organization: Mercurial
14391 HG(1)