1HG(1) Mercurial Manual HG(1)
2
6 hg - Mercurial source code management system
7
9 hg command [option]... [argument]...
10
12 The hg command provides a command line interface to the Mercurial sys‐
13 tem.
14
16 files...
17 indicates one or more filename or relative path filenames; see
18 File Name Patterns for information on pattern matching
19 path indicates a path on the local machine
21 revision
23 indicates a changeset which can be specified as a changeset re‐
24 vision number, a tag, or a unique substring of the changeset
25 hash value
26 repository path
28 either the pathname of a local repository or the URI of a remote
29 repository.
30
32 -R,--repository <REPO>
33 repository root directory or name of overlay bundle file
34 --cwd <DIR>
36 change working directory
37 -y, --noninteractive
39 do not prompt, automatically pick the first choice for all
40 prompts
41 -q, --quiet
43 suppress output
44 -v, --verbose
46 enable additional output
47 --color <TYPE>
49 when to colorize (boolean, always, auto, never, or debug)
50 --config <CONFIG[+]>
52 set/override config option (use 'section.name=value')
53 --debug
55 enable debugging output
56 --debugger
58 start debugger
59 --encoding <ENCODE>
61 set the charset encoding (default: UTF-8)
62 --encodingmode <MODE>
64 set the charset encoding mode (default: strict)
65 --traceback
67 always print a traceback on exception
68 --time time how long the command takes
70 --profile
72 print command execution profile
73 --version
75 output version information and exit
76 -h, --help
78 display help and exit
79 --hidden
81 consider hidden changesets
82 --pager <TYPE>
84 when to paginate (boolean, always, auto, or never) (default:
85 auto)
86 [+] marked option can be specified multiple times
88
90 Repository creation
91 clone
92 make a copy of an existing repository:
93 hg clone [OPTION]... SOURCE [DEST]
95 Create a copy of an existing repository in a new directory.
97 If no destination directory name is specified, it defaults to the base‐
99 name of the source.
100 The location of the source is added to the new repository's .hg/hgrc
102 file, as the default to be used for future pulls.
103 Only local paths and ssh:// URLs are supported as destinations. For
105 ssh:// destinations, no working directory or .hg/hgrc will be created
106 on the remote side.
107 If the source repository has a bookmark called '@' set, that revision
109 will be checked out in the new repository by default.
110 To check out a particular version, use -u/--update, or -U/--noupdate to
112 create a clone with no working directory.
113 To pull only a subset of changesets, specify one or more revisions
115 identifiers with -r/--rev or branches with -b/--branch. The resulting
116 clone will contain only the specified changesets and their ancestors.
117 These options (or 'clone src#rev dest') imply --pull, even for local
118 source repositories.
119 In normal clone mode, the remote normalizes repository data into a com‐
121 mon exchange format and the receiving end translates this data into its
122 local storage format. --stream activates a different clone mode that
123 essentially copies repository files from the remote with minimal data
124 processing. This significantly reduces the CPU cost of a clone both re‐
125 motely and locally. However, it often increases the transferred data
126 size by 30-40%. This can result in substantially faster clones where
127 I/O throughput is plentiful, especially for larger repositories. A
128 side-effect of --stream clones is that storage settings and require‐
129 ments on the remote are applied locally: a modern client may inherit
130 legacy or inefficient storage used by the remote or a legacy Mercurial
131 client may not be able to clone from a modern Mercurial remote.
132 Note Specifying a tag will include the tagged changeset but not the
134 changeset containing the tag.
135 For efficiency, hardlinks are used for cloning whenever the source and
137 destination are on the same filesystem (note this applies only to the
138 repository data, not to the working directory). Some filesystems, such
139 as AFS, implement hardlinking incorrectly, but do not report errors. In
140 these cases, use the --pull option to avoid hardlinking.
141 Mercurial will update the working directory to the first applicable re‐
143 vision from this list:
144 a. null if -U or the source repository has no changesets
146 b. if -u . and the source repository is local, the first parent of the
148 source repository's working directory
149 c. the changeset specified with -u (if a branch name, this means the
151 latest head of that branch)
152 d. the changeset specified with -r
154 e. the tipmost head specified with -b
156 f. the tipmost head specified with the url#branch source syntax
158 g. the revision marked with the '@' bookmark, if present
160 h. the tipmost head of the default branch
162 i. tip
164 When cloning from servers that support it, Mercurial may fetch pre-gen‐
166 erated data from a server-advertised URL or inline from the same
167 stream. When this is done, hooks operating on incoming changesets and
168 changegroups may fire more than once, once for each pre-generated bun‐
169 dle and as well as for any additional remaining data. In addition, if
170 an error occurs, the repository may be rolled back to a partial clone.
171 This behavior may change in future releases. See hg help -e cloneb‐
172 undles for more.
173 Examples:
175 • clone a remote repository to a new directory named hg/:
177 hg clone https://www.mercurial-scm.org/repo/hg/
179 • create a lightweight local clone:
181 hg clone project/ project-feature/
183 • clone from an absolute path on an ssh server (note double-slash):
185 hg clone ssh://user@server//home/projects/alpha/
187 • do a streaming clone while checking out a specified version:
189 hg clone --stream http://server/repo -u 1.5
191 • create a repository without changesets after a particular revision:
193 hg clone -r 04e544 experimental/ good/
195 • clone (and track) a particular named branch:
197 hg clone https://www.mercurial-scm.org/repo/hg/#stable
199 See hg help urls for details on specifying URLs.
201 Returns 0 on success.
203 Options:
205 -U, --noupdate
207 the clone will include an empty working directory (only a repos‐
208 itory)
209 -u,--updaterev <REV>
211 revision, tag, or branch to check out
212 -r,--rev <REV[+]>
214 do not clone everything, but include this changeset and its an‐
215 cestors
216 -b,--branch <BRANCH[+]>
218 do not clone everything, but include this branch's changesets
219 and their ancestors
220 --pull use pull protocol to copy metadata
222 --uncompressed
224 an alias to --stream (DEPRECATED)
225 --stream
227 clone with minimal data processing
228 -e,--ssh <CMD>
230 specify ssh command to use
231 --remotecmd <CMD>
233 specify hg command to run on the remote side
234 --insecure
236 do not verify server certificate (ignoring web.cacerts config)
237 [+] marked option can be specified multiple times
239 init
241 create a new repository in the given directory:
242 hg init [-e CMD] [--remotecmd CMD] [DEST]
244 Initialize a new repository in the given directory. If the given direc‐
246 tory does not exist, it will be created.
247 If no directory is given, the current directory is used.
249 It is possible to specify an ssh:// URL as the destination. See hg
251 help urls for more information.
252 Returns 0 on success.
254 Options:
256 -e,--ssh <CMD>
258 specify ssh command to use
259 --remotecmd <CMD>
261 specify hg command to run on the remote side
262 --insecure
264 do not verify server certificate (ignoring web.cacerts config)
265 Remote repository management
267 incoming
268 show new changesets found in source:
269 hg incoming [-p] [-n] [-M] [-f] [-r REV]... [--bundle FILENAME] [SOURCE]
271 Show new changesets found in the specified path/URL or the default pull
273 location. These are the changesets that would have been pulled by hg
274 pull at the time you issued this command.
275 See pull for valid source format details.
277 With -B/--bookmarks, the result of bookmark comparison between local
279 and remote repositories is displayed. With -v/--verbose, status is also
280 displayed for each bookmark like below:
281 BM1 01234567890a added
283 BM2 1234567890ab advanced
284 BM3 234567890abc diverged
285 BM4 34567890abcd changed
286 The action taken locally when pulling depends on the status of each
288 bookmark:
289 added
291 pull will create it
293 advanced
295 pull will update it
297 diverged
299 pull will create a divergent bookmark
301 changed
303 result depends on remote changesets
305 From the point of view of pulling behavior, bookmark existing only in
307 the remote repository are treated as added, even if it is in fact lo‐
308 cally deleted.
309 For remote repository, using --bundle avoids downloading the changesets
311 twice if the incoming is followed by a pull.
312 Examples:
314 • show incoming changes with patches and full description:
316 hg incoming -vp
318 • show incoming changes excluding merges, store a bundle:
320 hg in -vpM --bundle incoming.hg
322 hg pull incoming.hg
323 • briefly list changes inside a bundle:
325 hg in changes.hg -T "{desc|firstline}\n"
327 Returns 0 if there are incoming changes, 1 otherwise.
329 Options:
331 -f, --force
333 run even if remote repository is unrelated
334 -n, --newest-first
336 show newest record first
337 --bundle <FILE>
339 file to store the bundles into
340 -r,--rev <REV[+]>
342 a remote changeset intended to be added
343 -B, --bookmarks
345 compare bookmarks
346 -b,--branch <BRANCH[+]>
348 a specific branch you would like to pull
349 -p, --patch
351 show patch
352 -g, --git
354 use git extended diff format
355 -l,--limit <NUM>
357 limit number of changes displayed
358 -M, --no-merges
360 do not show merges
361 --stat output diffstat-style summary of changes
363 -G, --graph
365 show the revision DAG
366 --style <STYLE>
368 display using template map file (DEPRECATED)
369 -T,--template <TEMPLATE>
371 display with template
372 -e,--ssh <CMD>
374 specify ssh command to use
375 --remotecmd <CMD>
377 specify hg command to run on the remote side
378 --insecure
380 do not verify server certificate (ignoring web.cacerts config)
381 -S, --subrepos
383 recurse into subrepositories
384 [+] marked option can be specified multiple times
386 aliases: in
388 outgoing
390 show changesets not found in the destination:
391 hg outgoing [-M] [-p] [-n] [-f] [-r REV]... [DEST]...
393 Show changesets not found in the specified destination repository or
395 the default push location. These are the changesets that would be
396 pushed if a push was requested.
397 See pull for details of valid destination formats.
399 With -B/--bookmarks, the result of bookmark comparison between local
401 and remote repositories is displayed. With -v/--verbose, status is also
402 displayed for each bookmark like below:
403 BM1 01234567890a added
405 BM2 deleted
406 BM3 234567890abc advanced
407 BM4 34567890abcd diverged
408 BM5 4567890abcde changed
409 The action taken when pushing depends on the status of each bookmark:
411 added
413 push with -B will create it
415 deleted
417 push with -B will delete it
419 advanced
421 push will update it
423 diverged
425 push with -B will update it
427 changed
429 push with -B will update it
431 From the point of view of pushing behavior, bookmarks existing only in
433 the remote repository are treated as deleted, even if it is in fact
434 added remotely.
435 Returns 0 if there are outgoing changes, 1 otherwise.
437 Options:
439 -f, --force
441 run even when the destination is unrelated
442 -r,--rev <REV[+]>
444 a changeset intended to be included in the destination
445 -n, --newest-first
447 show newest record first
448 -B, --bookmarks
450 compare bookmarks
451 -b,--branch <BRANCH[+]>
453 a specific branch you would like to push
454 -p, --patch
456 show patch
457 -g, --git
459 use git extended diff format
460 -l,--limit <NUM>
462 limit number of changes displayed
463 -M, --no-merges
465 do not show merges
466 --stat output diffstat-style summary of changes
468 -G, --graph
470 show the revision DAG
471 --style <STYLE>
473 display using template map file (DEPRECATED)
474 -T,--template <TEMPLATE>
476 display with template
477 -e,--ssh <CMD>
479 specify ssh command to use
480 --remotecmd <CMD>
482 specify hg command to run on the remote side
483 --insecure
485 do not verify server certificate (ignoring web.cacerts config)
486 -S, --subrepos
488 recurse into subrepositories
489 [+] marked option can be specified multiple times
491 aliases: out
493 paths
495 show aliases for remote repositories:
496 hg paths [NAME]
498 Show definition of symbolic path name NAME. If no name is given, show
500 definition of all available names.
501 Option -q/--quiet suppresses all output when searching for NAME and
503 shows only the path names when listing all definitions.
504 Path names are defined in the [paths] section of your configuration
506 file and in /etc/mercurial/hgrc. If run inside a repository, .hg/hgrc
507 is used, too.
508 The path names default and default-push have a special meaning. When
510 performing a push or pull operation, they are used as fallbacks if no
511 location is specified on the command-line. When default-push is set,
512 it will be used for push and default will be used for pull; otherwise
513 default is used as the fallback for both. When cloning a repository,
514 the clone source is written as default in .hg/hgrc.
515 Note default and default-push apply to all inbound (e.g. hg incoming
517 ) and outbound (e.g. hg outgoing, hg email and hg bundle) opera‐
518 tions.
519 See hg help urls for more information.
521 Template:
523 The following keywords are supported. See also hg help templates.
525 name String. Symbolic name of the path alias.
527 pushurl
529 String. URL for push operations.
530 url String. URL or directory path for the other operations.
532 Returns 0 on success.
534 Options:
536 -T,--template <TEMPLATE>
538 display with template
539 pull
541 pull changes from the specified source:
542 hg pull [-u] [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [SOURCE]...
544 Pull changes from a remote repository to a local one.
546 This finds all changes from the repository at the specified path or URL
548 and adds them to a local repository (the current one unless -R is spec‐
549 ified). By default, this does not update the copy of the project in the
550 working directory.
551 When cloning from servers that support it, Mercurial may fetch pre-gen‐
553 erated data. When this is done, hooks operating on incoming changesets
554 and changegroups may fire more than once, once for each pre-generated
555 bundle and as well as for any additional remaining data. See hg help -e
556 clonebundles for more.
557 Use hg incoming if you want to see what would have been added by a pull
559 at the time you issued this command. If you then decide to add those
560 changes to the repository, you should use hg pull -r X where X is the
561 last changeset listed by hg incoming.
562 If SOURCE is omitted, the 'default' path will be used. See hg help
564 urls for more information.
565 If multiple sources are specified, they will be pulled sequentially as
567 if the command was run multiple time. If --update is specify and the
568 command will stop at the first failed --update.
569 Specifying bookmark as . is equivalent to specifying the active book‐
571 mark's name.
572 One can use the --remote-hidden flag to pull changesets hidden on the
574 remote. This flag is "best effort", and will only work if the server
575 supports the feature and is configured to allow the user to access hid‐
576 den changesets. This option is experimental and backwards compatibility
577 is not garanteed.
578 Returns 0 on success, 1 if an update had unresolved files.
580 Options:
582 -u, --update
584 update to new branch head if new descendants were pulled
585 -f, --force
587 run even when remote repository is unrelated
588 --confirm
590 confirm pull before applying changes
591 -r,--rev <REV[+]>
593 a remote changeset intended to be added
594 -B,--bookmark <BOOKMARK[+]>
596 bookmark to pull
597 -b,--branch <BRANCH[+]>
599 a specific branch you would like to pull
600 --remote-hidden
602 include changesets hidden on the remote (EXPERIMENTAL)
603 -e,--ssh <CMD>
605 specify ssh command to use
606 --remotecmd <CMD>
608 specify hg command to run on the remote side
609 --insecure
611 do not verify server certificate (ignoring web.cacerts config)
612 [+] marked option can be specified multiple times
614 push
616 push changes to the specified destination:
617 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]...
619 Push changesets from the local repository to the specified destination.
621 This operation is symmetrical to pull: it is identical to a pull in the
623 destination repository from the current one.
624 By default, push will not allow creation of new heads at the destina‐
626 tion, since multiple heads would make it unclear which head to use. In
627 this situation, it is recommended to pull and merge before pushing.
628 Use --new-branch if you want to allow push to create a new named branch
630 that is not present at the destination. This allows you to only create
631 a new branch without forcing other changes.
632 Note Extra care should be taken with the -f/--force option, which
634 will push all new heads on all branches, an action which will
635 almost always cause confusion for collaborators.
636 If -r/--rev is used, the specified revision and all its ancestors will
638 be pushed to the remote repository.
639 If -B/--bookmark is used, the specified bookmarked revision, its ances‐
641 tors, and the bookmark will be pushed to the remote repository. Speci‐
642 fying . is equivalent to specifying the active bookmark's name. Use the
643 --all-bookmarks option for pushing all current bookmarks.
644 Please see hg help urls for important details about ssh:// URLs. If
646 DESTINATION is omitted, a default path will be used.
647 When passed multiple destinations, push will process them one after the
649 other, but stop should an error occur.
650 The --pushvars option sends strings to the server that become environ‐
652 ment variables prepended with HG_USERVAR_. For example, --pushvars EN‐
653 ABLE_FEATURE=true, provides the server side hooks with HG_USERVAR_EN‐
654 ABLE_FEATURE=true as part of their environment.
655 pushvars can provide for user-overridable hooks as well as set debug
657 levels. One example is having a hook that blocks commits containing
658 conflict markers, but enables the user to override the hook if the file
659 is using conflict markers for testing purposes or the file format has
660 strings that look like conflict markers.
661 By default, servers will ignore --pushvars. To enable it add the fol‐
663 lowing to your configuration file:
664 [push]
666 pushvars.server = true
667 Returns 0 if push was successful, 1 if nothing to push.
669 Options:
671 -f, --force
673 force push
674 -r,--rev <REV[+]>
676 a changeset intended to be included in the destination
677 -B,--bookmark <BOOKMARK[+]>
679 bookmark to push
680 --all-bookmarks
682 push all bookmarks (EXPERIMENTAL)
683 -b,--branch <BRANCH[+]>
685 a specific branch you would like to push
686 --new-branch
688 allow pushing a new branch
689 --pushvars <VALUE[+]>
691 variables that can be sent to server (ADVANCED)
692 --publish
694 push the changeset as public (EXPERIMENTAL)
695 -e,--ssh <CMD>
697 specify ssh command to use
698 --remotecmd <CMD>
700 specify hg command to run on the remote side
701 --insecure
703 do not verify server certificate (ignoring web.cacerts config)
704 [+] marked option can be specified multiple times
706 serve
708 start stand-alone webserver:
709 hg serve [OPTION]...
711 Start a local HTTP repository browser and pull server. You can use this
713 for ad-hoc sharing and browsing of repositories. It is recommended to
714 use a real web server to serve a repository for longer periods of time.
715 Please note that the server does not implement access control. This
717 means that, by default, anybody can read from the server and nobody can
718 write to it by default. Set the web.allow-push option to * to allow ev‐
719 erybody to push to the server. You should use a real web server if you
720 need to authenticate users.
721 By default, the server logs accesses to stdout and errors to stderr.
723 Use the -A/--accesslog and -E/--errorlog options to log to files.
724 To have the server choose a free port number to listen on, specify a
726 port number of 0; in this case, the server will print the port number
727 it uses.
728 Returns 0 on success.
730 Options:
732 -A,--accesslog <FILE>
734 name of access log file to write to
735 -d, --daemon
737 run server in background
738 --daemon-postexec <VALUE[+]>
740 used internally by daemon mode
741 -E,--errorlog <FILE>
743 name of error log file to write to
744 -p,--port <PORT>
746 port to listen on (default: 8000)
747 -a,--address <ADDR>
749 address to listen on (default: all interfaces)
750 --prefix <PREFIX>
752 prefix path to serve from (default: server root)
753 -n,--name <NAME>
755 name to show in web pages (default: working directory)
756 --web-conf <FILE>
758 name of the hgweb config file (see 'hg help hgweb')
759 --webdir-conf <FILE>
761 name of the hgweb config file (DEPRECATED)
762 --pid-file <FILE>
764 name of file to write process ID to
765 --stdio
767 for remote clients (ADVANCED)
768 --cmdserver <MODE>
770 for remote clients (ADVANCED)
771 -t,--templates <TEMPLATE>
773 web templates to use
774 --style <STYLE>
776 template style to use
777 -6, --ipv6
779 use IPv6 instead of IPv4
780 --certificate <FILE>
782 SSL certificate file
783 --print-url
785 start and print only the URL
786 -S, --subrepos
788 recurse into subrepositories
789 [+] marked option can be specified multiple times
791 Change creation
793 commit
794 commit the specified files or all outstanding changes:
795 hg commit [OPTION]... [FILE]...
797 Commit changes to the given files into the repository. Unlike a cen‐
799 tralized SCM, this operation is a local operation. See hg push for a
800 way to actively distribute your changes.
801 If a list of files is omitted, all changes reported by hg status will
803 be committed.
804 If you are committing the result of a merge, do not provide any file‐
806 names or -I/-X filters.
807 If no commit message is specified, Mercurial starts your configured ed‐
809 itor where you can enter a message. In case your commit fails, you will
810 find a backup of your message in .hg/last-message.txt.
811 The --close-branch flag can be used to mark the current branch head
813 closed. When all heads of a branch are closed, the branch will be con‐
814 sidered closed and no longer listed.
815 The --amend flag can be used to amend the parent of the working direc‐
817 tory with a new commit that contains the changes in the parent in addi‐
818 tion to those currently reported by hg status, if there are any. The
819 old commit is stored in a backup bundle in .hg/strip-backup (see hg
820 help bundle and hg help unbundle on how to restore it).
821 Message, user and date are taken from the amended commit unless speci‐
823 fied. When a message isn't specified on the command line, the editor
824 will open with the message of the amended commit.
825 It is not possible to amend public changesets (see hg help phases) or
827 changesets that have children.
828 See hg help dates for a list of formats valid for -d/--date.
830 Returns 0 on success, 1 if nothing changed.
832 Examples:
834 • commit all files ending in .py:
836 hg commit --include "set:**.py"
838 • commit all non-binary files:
840 hg commit --exclude "set:binary()"
842 • amend the current commit and set the date to now:
844 hg commit --amend --date now
846 Options:
848 -A, --addremove
850 mark new/missing files as added/removed before committing
851 --close-branch
853 mark a branch head as closed
854 --amend
856 amend the parent of the working directory
857 -s, --secret
859 use the secret phase for committing
860 --draft
862 use the draft phase for committing
863 -e, --edit
865 invoke editor on commit messages
866 --force-close-branch
868 forcibly close branch from a non-head changeset (ADVANCED)
869 -i, --interactive
871 use interactive mode
872 -I,--include <PATTERN[+]>
874 include names matching the given patterns
875 -X,--exclude <PATTERN[+]>
877 exclude names matching the given patterns
878 -m,--message <TEXT>
880 use text as commit message
881 -l,--logfile <FILE>
883 read commit message from file
884 -d,--date <DATE>
886 record the specified date as commit date
887 -u,--user <USER>
889 record the specified user as committer
890 -S, --subrepos
892 recurse into subrepositories
893 [+] marked option can be specified multiple times
895 aliases: ci
897 Change manipulation
899 abort
900 abort an unfinished operation (EXPERIMENTAL):
901 hg abort
903 Aborts a multistep operation like graft, histedit, rebase, merge, and
905 unshelve if they are in an unfinished state.
906 use --dry-run/-n to dry run the command.
908 Options:
910 -n, --dry-run
912 do not perform actions, just print output
913 backout
915 reverse effect of earlier changeset:
916 hg backout [OPTION]... [-r] REV
918 Prepare a new changeset with the effect of REV undone in the current
920 working directory. If no conflicts were encountered, it will be commit‐
921 ted immediately.
922 If REV is the parent of the working directory, then this new changeset
924 is committed automatically (unless --no-commit is specified).
925 Note hg backout cannot be used to fix either an unwanted or incorrect
927 merge.
928 Examples:
930 • Reverse the effect of the parent of the working directory. This
932 backout will be committed immediately:
933 hg backout -r .
935 • Reverse the effect of previous bad revision 23:
937 hg backout -r 23
939 • Reverse the effect of previous bad revision 23 and leave changes un‐
941 committed:
942 hg backout -r 23 --no-commit
944 hg commit -m "Backout revision 23"
945 By default, the pending changeset will have one parent, maintaining a
947 linear history. With --merge, the pending changeset will instead have
948 two parents: the old parent of the working directory and a new child of
949 REV that simply undoes REV.
950 Before version 1.7, the behavior without --merge was equivalent to
952 specifying --merge followed by hg update --clean . to cancel the merge
953 and leave the child of REV as a head to be merged separately.
954 See hg help dates for a list of formats valid for -d/--date.
956 See hg help revert for a way to restore files to the state of another
958 revision.
959 Returns 0 on success, 1 if nothing to backout or there are unresolved
961 files.
962 Options:
964 --merge
966 merge with old dirstate parent after backout
967 --commit
969 commit if no conflicts were encountered (DEPRECATED)
970 --no-commit
972 do not commit
973 --parent <REV>
975 parent to choose when backing out merge (DEPRECATED)
976 -r,--rev <REV>
978 revision to backout
979 -e, --edit
981 invoke editor on commit messages
982 -t,--tool <TOOL>
984 specify merge tool
985 -I,--include <PATTERN[+]>
987 include names matching the given patterns
988 -X,--exclude <PATTERN[+]>
990 exclude names matching the given patterns
991 -m,--message <TEXT>
993 use text as commit message
994 -l,--logfile <FILE>
996 read commit message from file
997 -d,--date <DATE>
999 record the specified date as commit date
1000 -u,--user <USER>
1002 record the specified user as committer
1003 [+] marked option can be specified multiple times
1005 continue
1007 resumes an interrupted operation (EXPERIMENTAL):
1008 hg continue
1010 Finishes a multistep operation like graft, histedit, rebase, merge, and
1012 unshelve if they are in an interrupted state.
1013 use --dry-run/-n to dry run the command.
1015 Options:
1017 -n, --dry-run
1019 do not perform actions, just print output
1020 graft
1022 copy changes from other branches onto the current branch:
1023 hg graft [OPTION]... [-r REV]... REV...
1025 This command uses Mercurial's merge logic to copy individual changes
1027 from other branches without merging branches in the history graph. This
1028 is sometimes known as 'backporting' or 'cherry-picking'. By default,
1029 graft will copy user, date, and description from the source changesets.
1030 Changesets that are ancestors of the current revision, that have al‐
1032 ready been grafted, or that are merges will be skipped.
1033 If --log is specified, log messages will have a comment appended of the
1035 form:
1036 (grafted from CHANGESETHASH)
1038 If --force is specified, revisions will be grafted even if they are al‐
1040 ready ancestors of, or have been grafted to, the destination. This is
1041 useful when the revisions have since been backed out.
1042 If a graft merge results in conflicts, the graft process is interrupted
1044 so that the current merge can be manually resolved. Once all conflicts
1045 are addressed, the graft process can be continued with the -c/--con‐
1046 tinue option.
1047 The -c/--continue option reapplies all the earlier options.
1049 The --base option exposes more of how graft internally uses merge with
1051 a custom base revision. --base can be used to specify another ancestor
1052 than the first and only parent.
1053 The command:
1055 hg graft -r 345 --base 234
1057 is thus pretty much the same as:
1059 hg diff --from 234 --to 345 | hg import
1061 but using merge to resolve conflicts and track moved files.
1063 The result of a merge can thus be backported as a single commit by
1065 specifying one of the merge parents as base, and thus effectively
1066 grafting the changes from the other side.
1067 It is also possible to collapse multiple changesets and clean up his‐
1069 tory by specifying another ancestor as base, much like rebase --col‐
1070 lapse --keep.
1071 The commit message can be tweaked after the fact using commit --amend .
1073 For using non-ancestors as the base to backout changes, see the backout
1075 command and the hidden --parent option.
1076 Examples:
1078 • copy a single change to the stable branch and edit its description:
1080 hg update stable
1082 hg graft --edit 9393
1083 • graft a range of changesets with one exception, updating dates:
1085 hg graft -D "2085::2093 and not 2091"
1087 • continue a graft after resolving conflicts:
1089 hg graft -c
1091 • show the source of a grafted changeset:
1093 hg log --debug -r .
1095 • show revisions sorted by date:
1097 hg log -r "sort(all(), date)"
1099 • backport the result of a merge as a single commit:
1101 hg graft -r 123 --base 123^
1103 • land a feature branch as one changeset:
1105 hg up -cr default
1107 hg graft -r featureX --base "ancestor('featureX', 'default')"
1108 See hg help revisions for more about specifying revisions.
1110 Returns 0 on successful completion, 1 if there are unresolved files.
1112 Options:
1114 -r,--rev <REV[+]>
1116 revisions to graft
1117 --base <REV>
1119 base revision when doing the graft merge (ADVANCED)
1120 -c, --continue
1122 resume interrupted graft
1123 --stop stop interrupted graft
1125 --abort
1127 abort interrupted graft
1128 -e, --edit
1130 invoke editor on commit messages
1131 --log append graft info to log message
1133 --no-commit
1135 don't commit, just apply the changes in working directory
1136 -f, --force
1138 force graft
1139 -D, --currentdate
1141 record the current date as commit date
1142 -U, --currentuser
1144 record the current user as committer
1145 -d,--date <DATE>
1147 record the specified date as commit date
1148 -u,--user <USER>
1150 record the specified user as committer
1151 -t,--tool <TOOL>
1153 specify merge tool
1154 -n, --dry-run
1156 do not perform actions, just print output
1157 [+] marked option can be specified multiple times
1159 merge
1161 merge another revision into working directory:
1162 hg merge [-P] [[-r] REV]
1164 The current working directory is updated with all changes made in the
1166 requested revision since the last common predecessor revision.
1167 Files that changed between either parent are marked as changed for the
1169 next commit and a commit must be performed before any further updates
1170 to the repository are allowed. The next commit will have two parents.
1171 --tool can be used to specify the merge tool used for file merges. It
1173 overrides the HGMERGE environment variable and your configuration
1174 files. See hg help merge-tools for options.
1175 If no revision is specified, the working directory's parent is a head
1177 revision, and the current branch contains exactly one other head, the
1178 other head is merged with by default. Otherwise, an explicit revision
1179 with which to merge must be provided.
1180 See hg help resolve for information on handling file conflicts.
1182 To undo an uncommitted merge, use hg merge --abort which will check out
1184 a clean copy of the original merge parent, losing all changes.
1185 Returns 0 on success, 1 if there are unresolved files.
1187 Options:
1189 -f, --force
1191 force a merge including outstanding changes (DEPRECATED)
1192 -r,--rev <REV>
1194 revision to merge
1195 -P, --preview
1197 review revisions to merge (no merge is performed)
1198 --abort
1200 abort the ongoing merge
1201 -t,--tool <TOOL>
1203 specify merge tool
1204 Change organization
1206 bookmarks
1207 create a new bookmark or list existing bookmarks:
1208 hg bookmarks [OPTIONS]... [NAME]...
1210 Bookmarks are labels on changesets to help track lines of development.
1212 Bookmarks are unversioned and can be moved, renamed and deleted.
1213 Deleting or moving a bookmark has no effect on the associated change‐
1214 sets.
1215 Creating or updating to a bookmark causes it to be marked as 'active'.
1217 The active bookmark is indicated with a '*'. When a commit is made,
1218 the active bookmark will advance to the new commit. A plain hg update
1219 will also advance an active bookmark, if possible. Updating away from
1220 a bookmark will cause it to be deactivated.
1221 Bookmarks can be pushed and pulled between repositories (see hg help
1223 push and hg help pull). If a shared bookmark has diverged, a new 'di‐
1224 vergent bookmark' of the form 'name@path' will be created. Using hg
1225 merge will resolve the divergence.
1226 Specifying bookmark as '.' to -m/-d/-l options is equivalent to speci‐
1228 fying the active bookmark's name.
1229 A bookmark named '@' has the special property that hg clone will check
1231 it out by default if it exists.
1232 Template:
1234 The following keywords are supported in addition to the common template
1236 keywords and functions such as {bookmark}. See also hg help templates.
1237 active Boolean. True if the bookmark is active.
1239 Examples:
1241 • create an active bookmark for a new line of development:
1243 hg book new-feature
1245 • create an inactive bookmark as a place marker:
1247 hg book -i reviewed
1249 • create an inactive bookmark on another changeset:
1251 hg book -r .^ tested
1253 • rename bookmark turkey to dinner:
1255 hg book -m turkey dinner
1257 • move the '@' bookmark from another branch:
1259 hg book -f @
1261 • print only the active bookmark name:
1263 hg book -ql .
1265 Options:
1267 -f, --force
1269 force
1270 -r,--rev <REV>
1272 revision for bookmark action
1273 -d, --delete
1275 delete a given bookmark
1276 -m,--rename <OLD>
1278 rename a given bookmark
1279 -i, --inactive
1281 mark a bookmark inactive
1282 -l, --list
1284 list existing bookmarks
1285 -T,--template <TEMPLATE>
1287 display with template
1288 aliases: bookmark
1290 branch
1292 set or show the current branch name:
1293 hg branch [-fC] [NAME]
1295 Note Branch names are permanent and global. Use hg bookmark to create
1297 a light-weight bookmark instead. See hg help glossary for more
1298 information about named branches and bookmarks.
1299 With no argument, show the current branch name. With one argument, set
1301 the working directory branch name (the branch will not exist in the
1302 repository until the next commit). Standard practice recommends that
1303 primary development take place on the 'default' branch.
1304 Unless -f/--force is specified, branch will not let you set a branch
1306 name that already exists.
1307 Use -C/--clean to reset the working directory branch to that of the
1309 parent of the working directory, negating a previous branch change.
1310 Use the command hg update to switch to an existing branch. Use hg com‐
1312 mit --close-branch to mark this branch head as closed. When all heads
1313 of a branch are closed, the branch will be considered closed.
1314 Returns 0 on success.
1316 Options:
1318 -f, --force
1320 set branch name even if it shadows an existing branch
1321 -C, --clean
1323 reset branch name to parent branch name
1324 -r,--rev <VALUE[+]>
1326 change branches of the given revs (EXPERIMENTAL)
1327 [+] marked option can be specified multiple times
1329 branches
1331 list repository named branches:
1332 hg branches [-c]
1334 List the repository's named branches, indicating which ones are inac‐
1336 tive. If -c/--closed is specified, also list branches which have been
1337 marked closed (see hg commit --close-branch).
1338 Use the command hg update to switch to an existing branch.
1340 Template:
1342 The following keywords are supported in addition to the common template
1344 keywords and functions such as {branch}. See also hg help templates.
1345 active Boolean. True if the branch is active.
1347 closed Boolean. True if the branch is closed.
1349 current
1351 Boolean. True if it is the current branch.
1352 Returns 0.
1354 Options:
1356 -a, --active
1358 show only branches that have unmerged heads (DEPRECATED)
1359 -c, --closed
1361 show normal and closed branches
1362 -r,--rev <VALUE[+]>
1364 show branch name(s) of the given rev
1365 -T,--template <TEMPLATE>
1367 display with template
1368 [+] marked option can be specified multiple times
1370 phase
1372 set or show the current phase name:
1373 hg phase [-p|-d|-s] [-f] [-r] [REV...]
1375 With no argument, show the phase name of the current revision(s).
1377 With one of -p/--public, -d/--draft or -s/--secret, change the phase
1379 value of the specified revisions.
1380 Unless -f/--force is specified, hg phase won't move changesets from a
1382 lower phase to a higher phase. Phases are ordered as follows:
1383 public < draft < secret
1385 Returns 0 on success, 1 if some phases could not be changed.
1387 (For more information about the phases concept, see hg help phases.)
1389 Options:
1391 -p, --public
1393 set changeset phase to public
1394 -d, --draft
1396 set changeset phase to draft
1397 -s, --secret
1399 set changeset phase to secret
1400 -f, --force
1402 allow to move boundary backward
1403 -r,--rev <REV[+]>
1405 target revision
1406 [+] marked option can be specified multiple times
1408 tag
1410 add one or more tags for the current or given revision:
1411 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
1413 Name a particular revision using <name>.
1415 Tags are used to name particular revisions of the repository and are
1417 very useful to compare different revisions, to go back to significant
1418 earlier versions or to mark branch points as releases, etc. Changing an
1419 existing tag is normally disallowed; use -f/--force to override.
1420 If no revision is given, the parent of the working directory is used.
1422 To facilitate version control, distribution, and merging of tags, they
1424 are stored as a file named ".hgtags" which is managed similarly to
1425 other project files and can be hand-edited if necessary. This also
1426 means that tagging creates a new commit. The file ".hg/localtags" is
1427 used for local tags (not shared among repositories).
1428 Tag commits are usually made at the head of a branch. If the parent of
1430 the working directory is not a branch head, hg tag aborts; use
1431 -f/--force to force the tag commit to be based on a non-head changeset.
1432 See hg help dates for a list of formats valid for -d/--date.
1434 Since tag names have priority over branch names during revision lookup,
1436 using an existing branch name as a tag name is discouraged.
1437 Returns 0 on success.
1439 Options:
1441 -f, --force
1443 force tag
1444 -l, --local
1446 make the tag local
1447 -r,--rev <REV>
1449 revision to tag
1450 --remove
1452 remove a tag
1453 -e, --edit
1455 invoke editor on commit messages
1456 -m,--message <TEXT>
1458 use text as commit message
1459 -d,--date <DATE>
1461 record the specified date as commit date
1462 -u,--user <USER>
1464 record the specified user as committer
1465 tags
1467 list repository tags:
1468 hg tags
1470 This lists both regular and local tags. When the -v/--verbose switch is
1472 used, a third column "local" is printed for local tags. When the
1473 -q/--quiet switch is used, only the tag name is printed.
1474 Template:
1476 The following keywords are supported in addition to the common template
1478 keywords and functions such as {tag}. See also hg help templates.
1479 type String. local for local tags.
1481 Returns 0 on success.
1483 Options:
1485 -T,--template <TEMPLATE>
1487 display with template
1488 File content management
1490 annotate
1491 show changeset information by line for each file:
1492 hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...
1494 List changes in files, showing the revision id responsible for each
1496 line.
1497 This command is useful for discovering when a change was made and by
1499 whom.
1500 If you include --file, --user, or --date, the revision number is sup‐
1502 pressed unless you also include --number.
1503 Without the -a/--text option, annotate will avoid processing files it
1505 detects as binary. With -a, annotate will annotate the file anyway, al‐
1506 though the results will probably be neither useful nor desirable.
1507 Template:
1509 The following keywords are supported in addition to the common template
1511 keywords and functions. See also hg help templates.
1512 lines List of lines with annotation data.
1514 path String. Repository-absolute path of the specified file.
1516 And each entry of {lines} provides the following sub-keywords in addi‐
1518 tion to {date}, {node}, {rev}, {user}, etc.
1519 line String. Line content.
1521 lineno Integer. Line number at that revision.
1523 path String. Repository-absolute path of the file at that revision.
1525 See hg help templates.operators for the list expansion syntax.
1527 Returns 0 on success.
1529 Options:
1531 -r,--rev <REV>
1533 annotate the specified revision
1534 --follow
1536 follow copies/renames and list the filename (DEPRECATED)
1537 --no-follow
1539 don't follow copies and renames
1540 -a, --text
1542 treat all files as text
1543 -u, --user
1545 list the author (long with -v)
1546 -f, --file
1548 list the filename
1549 -d, --date
1551 list the date (short with -q)
1552 -n, --number
1554 list the revision number (default)
1555 -c, --changeset
1557 list the changeset
1558 -l, --line-number
1560 show line number at the first appearance
1561 --skip <REV[+]>
1563 revset to not display (EXPERIMENTAL)
1564 -w, --ignore-all-space
1566 ignore white space when comparing lines
1567 -b, --ignore-space-change
1569 ignore changes in the amount of white space
1570 -B, --ignore-blank-lines
1572 ignore changes whose lines are all blank
1573 -Z, --ignore-space-at-eol
1575 ignore changes in whitespace at EOL
1576 -I,--include <PATTERN[+]>
1578 include names matching the given patterns
1579 -X,--exclude <PATTERN[+]>
1581 exclude names matching the given patterns
1582 -T,--template <TEMPLATE>
1584 display with template
1585 [+] marked option can be specified multiple times
1587 aliases: blame
1589 cat
1591 output the current or given revision of files:
1592 hg cat [OPTION]... FILE...
1594 Print the specified files as they were at the given revision. If no re‐
1596 vision is given, the parent of the working directory is used.
1597 Output may be to a file, in which case the name of the file is given
1599 using a template string. See hg help templates. In addition to the com‐
1600 mon template keywords, the following formatting rules are supported:
1601 %%
1603 literal "%" character
1605 %s
1607 basename of file being printed
1609 %d
1611 dirname of file being printed, or '.' if in repository root
1613 %p
1615 root-relative path name of file being printed
1617 %H
1619 changeset hash (40 hexadecimal digits)
1621 %R
1623 changeset revision number
1625 %h
1627 short-form changeset hash (12 hexadecimal digits)
1629 %r
1631 zero-padded changeset revision number
1633 %b
1635 basename of the exporting repository
1637 \
1639 literal "" character
1641 Template:
1643 The following keywords are supported in addition to the common template
1645 keywords and functions. See also hg help templates.
1646 data String. File content.
1648 path String. Repository-absolute path of the file.
1650 Returns 0 on success.
1652 Options:
1654 -o,--output <FORMAT>
1656 print output to file with formatted name
1657 -r,--rev <REV>
1659 print the given revision
1660 --decode
1662 apply any matching decode filter
1663 -I,--include <PATTERN[+]>
1665 include names matching the given patterns
1666 -X,--exclude <PATTERN[+]>
1668 exclude names matching the given patterns
1669 -T,--template <TEMPLATE>
1671 display with template
1672 [+] marked option can be specified multiple times
1674 copy
1676 mark files as copied for the next commit:
1677 hg copy [OPTION]... (SOURCE... DEST | --forget DEST...)
1679 Mark dest as having copies of source files. If dest is a directory,
1681 copies are put in that directory. If dest is a file, the source must be
1682 a single file.
1683 By default, this command copies the contents of files as they exist in
1685 the working directory. If invoked with -A/--after, the operation is
1686 recorded, but no copying is performed.
1687 To undo marking a destination file as copied, use --forget. With that
1689 option, all given (positional) arguments are unmarked as copies. The
1690 destination file(s) will be left in place (still tracked). Note that hg
1691 copy --forget behaves the same way as hg rename --forget.
1692 This command takes effect with the next commit by default.
1694 Returns 0 on success, 1 if errors are encountered.
1696 Options:
1698 --forget
1700 unmark a destination file as copied
1701 -A, --after
1703 record a copy that has already occurred
1704 --at-rev <REV>
1706 (un)mark copies in the given revision (EXPERIMENTAL)
1707 -f, --force
1709 forcibly copy over an existing managed file
1710 -I,--include <PATTERN[+]>
1712 include names matching the given patterns
1713 -X,--exclude <PATTERN[+]>
1715 exclude names matching the given patterns
1716 -n, --dry-run
1718 do not perform actions, just print output
1719 [+] marked option can be specified multiple times
1721 aliases: cp
1723 diff
1725 diff repository (or selected files):
1726 hg diff [OPTION]... ([-c REV] | [--from REV1] [--to REV2]) [FILE]...
1728 Show differences between revisions for the specified files.
1730 Differences between files are shown using the unified diff format.
1732 Note hg diff may generate unexpected results for merges, as it will
1734 default to comparing against the working directory's first par‐
1735 ent changeset if no revisions are specified. To diff against
1736 the conflict regions, you can use --config diff.merge=yes.
1737 By default, the working directory files are compared to its first par‐
1739 ent. To see the differences from another revision, use --from. To see
1740 the difference to another revision, use --to. For example, hg diff
1741 --from .^ will show the differences from the working copy's grandparent
1742 to the working copy, hg diff --to . will show the diff from the working
1743 copy to its parent (i.e. the reverse of the default), and hg diff
1744 --from 1.0 --to 1.2 will show the diff between those two revisions.
1745 Alternatively you can specify -c/--change with a revision to see the
1747 changes in that changeset relative to its first parent (i.e. hg diff -c
1748 42 is equivalent to hg diff --from 42^ --to 42)
1749 Without the -a/--text option, diff will avoid generating diffs of files
1751 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1752 bly with undesirable results.
1753 Use the -g/--git option to generate diffs in the git extended diff for‐
1755 mat. For more information, read hg help diffs.
1756 Examples:
1758 • compare a file in the current working directory to its parent:
1760 hg diff foo.c
1762 • compare two historical versions of a directory, with rename info:
1764 hg diff --git --from 1.0 --to 1.2 lib/
1766 • get change stats relative to the last change on some date:
1768 hg diff --stat --from "date('may 2')"
1770 • diff all newly-added files that contain a keyword:
1772 hg diff "set:added() and grep(GNU)"
1774 • compare a revision and its parents:
1776 hg diff -c 9353 # compare against first parent
1778 hg diff --from 9353^ --to 9353 # same using revset syntax
1779 hg diff --from 9353^2 --to 9353 # compare against the second parent
1780 Returns 0 on success.
1782 Options:
1784 -r,--rev <REV[+]>
1786 revision (DEPRECATED)
1787 --from <REV1>
1789 revision to diff from
1790 --to <REV2>
1792 revision to diff to
1793 -c,--change <REV>
1795 change made by revision
1796 -a, --text
1798 treat all files as text
1799 -g, --git
1801 use git extended diff format (DEFAULT: diff.git)
1802 --binary
1804 generate binary diffs in git mode (default)
1805 --nodates
1807 omit dates from diff headers
1808 --noprefix
1810 omit a/ and b/ prefixes from filenames
1811 -p, --show-function
1813 show which function each change is in (DEFAULT: diff.showfunc)
1814 --reverse
1816 produce a diff that undoes the changes
1817 -w, --ignore-all-space
1819 ignore white space when comparing lines
1820 -b, --ignore-space-change
1822 ignore changes in the amount of white space
1823 -B, --ignore-blank-lines
1825 ignore changes whose lines are all blank
1826 -Z, --ignore-space-at-eol
1828 ignore changes in whitespace at EOL
1829 -U,--unified <NUM>
1831 number of lines of context to show
1832 --stat output diffstat-style summary of changes
1834 --root <DIR>
1836 produce diffs relative to subdirectory
1837 -I,--include <PATTERN[+]>
1839 include names matching the given patterns
1840 -X,--exclude <PATTERN[+]>
1842 exclude names matching the given patterns
1843 -S, --subrepos
1845 recurse into subrepositories
1846 [+] marked option can be specified multiple times
1848 grep
1850 search for a pattern in specified files:
1851 hg grep [--diff] [OPTION]... PATTERN [FILE]...
1853 Search the working directory or revision history for a regular expres‐
1855 sion in the specified files for the entire repository.
1856 By default, grep searches the repository files in the working directory
1858 and prints the files where it finds a match. To specify historical re‐
1859 visions instead of the working directory, use the --rev flag.
1860 To search instead historical revision differences that contains a
1862 change in match status ("-" for a match that becomes a non-match, or
1863 "+" for a non-match that becomes a match), use the --diff flag.
1864 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1866 If no FILEs are specified and the --rev flag isn't supplied, all files
1868 in the working directory are searched. When using the --rev flag and
1869 specifying FILEs, use the --follow argument to also follow the speci‐
1870 fied FILEs across renames and copies.
1871 Template:
1873 The following keywords are supported in addition to the common template
1875 keywords and functions. See also hg help templates.
1876 change String. Character denoting insertion + or removal -. Available
1878 if --diff is specified.
1879 lineno Integer. Line number of the match.
1881 path String. Repository-absolute path of the file.
1883 texts List of text chunks.
1885 And each entry of {texts} provides the following sub-keywords.
1887 matched
1889 Boolean. True if the chunk matches the specified pattern.
1890 text String. Chunk content.
1892 See hg help templates.operators for the list expansion syntax.
1894 Returns 0 if a match is found, 1 otherwise.
1896 Options:
1898 -0, --print0
1900 end fields with NUL
1901 --all an alias to --diff (DEPRECATED)
1903 --diff search revision differences for when the pattern was added or
1905 removed
1906 -a, --text
1908 treat all files as text
1909 -f, --follow
1911 follow changeset history, or file history across copies and re‐
1912 names
1913 -i, --ignore-case
1915 ignore case when matching
1916 -l, --files-with-matches
1918 print only filenames and revisions that match
1919 -n, --line-number
1921 print matching line numbers
1922 -r,--rev <REV[+]>
1924 search files changed within revision range
1925 --all-files
1927 include all files in the changeset while grepping (DEPRECATED)
1928 -u, --user
1930 list the author (long with -v)
1931 -d, --date
1933 list the date (short with -q)
1934 -T,--template <TEMPLATE>
1936 display with template
1937 -I,--include <PATTERN[+]>
1939 include names matching the given patterns
1940 -X,--exclude <PATTERN[+]>
1942 exclude names matching the given patterns
1943 [+] marked option can be specified multiple times
1945 Change navigation
1947 bisect
1948 subdivision search of changesets:
1949 hg bisect [-gbsr] [-U] [-c CMD] [REV]
1951 This command helps to find changesets which introduce problems. To use,
1953 mark the earliest changeset you know exhibits the problem as bad, then
1954 mark the latest changeset which is free from the problem as good. Bi‐
1955 sect will update your working directory to a revision for testing (un‐
1956 less the -U/--noupdate option is specified). Once you have performed
1957 tests, mark the working directory as good or bad, and bisect will ei‐
1958 ther update to another candidate changeset or announce that it has
1959 found the bad revision.
1960 As a shortcut, you can also use the revision argument to mark a revi‐
1962 sion as good or bad without checking it out first.
1963 If you supply a command, it will be used for automatic bisection. The
1965 environment variable HG_NODE will contain the ID of the changeset being
1966 tested. The exit status of the command will be used to mark revisions
1967 as good or bad: status 0 means good, 125 means to skip the revision,
1968 127 (command not found) will abort the bisection, and any other
1969 non-zero exit status means the revision is bad.
1970 Some examples:
1972 • start a bisection with known bad revision 34, and good revision 12:
1974 hg bisect --bad 34
1976 hg bisect --good 12
1977 • advance the current bisection by marking current revision as good or
1979 bad:
1980 hg bisect --good
1982 hg bisect --bad
1983 • mark the current revision, or a known revision, to be skipped (e.g.
1985 if that revision is not usable because of another issue):
1986 hg bisect --skip
1988 hg bisect --skip 23
1989 • skip all revisions that do not touch directories foo or bar:
1991 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
1993 • forget the current bisection:
1995 hg bisect --reset
1997 • use 'make && make tests' to automatically find the first broken revi‐
1999 sion:
2000 hg bisect --reset
2002 hg bisect --bad 34
2003 hg bisect --good 12
2004 hg bisect --command "make && make tests"
2005 • see all changesets whose states are already known in the current bi‐
2007 section:
2008 hg log -r "bisect(pruned)"
2010 • see the changeset currently being bisected (especially useful if run‐
2012 ning with -U/--noupdate):
2013 hg log -r "bisect(current)"
2015 • see all changesets that took part in the current bisection:
2017 hg log -r "bisect(range)"
2019 • you can even get a nice graph:
2021 hg log --graph -r "bisect(range)"
2023 See hg help revisions.bisect for more about the bisect() predicate.
2025 Returns 0 on success.
2027 Options:
2029 -r, --reset
2031 reset bisect state
2032 -g, --good
2034 mark changeset good
2035 -b, --bad
2037 mark changeset bad
2038 -s, --skip
2040 skip testing changeset
2041 -e, --extend
2043 extend the bisect range
2044 -c,--command <CMD>
2046 use command to check changeset state
2047 -U, --noupdate
2049 do not update to target
2050 heads
2052 show branch heads:
2053 hg heads [-ct] [-r STARTREV] [REV]...
2055 With no arguments, show all open branch heads in the repository.
2057 Branch heads are changesets that have no descendants on the same
2058 branch. They are where development generally takes place and are the
2059 usual targets for update and merge operations.
2060 If one or more REVs are given, only open branch heads on the branches
2062 associated with the specified changesets are shown. This means that you
2063 can use hg heads . to see the heads on the currently checked-out
2064 branch.
2065 If -c/--closed is specified, also show branch heads marked closed (see
2067 hg commit --close-branch).
2068 If STARTREV is specified, only those heads that are descendants of
2070 STARTREV will be displayed.
2071 If -t/--topo is specified, named branch mechanics will be ignored and
2073 only topological heads (changesets with no children) will be shown.
2074 Returns 0 if matching heads are found, 1 if not.
2076 Options:
2078 -r,--rev <STARTREV>
2080 show only heads which are descendants of STARTREV
2081 -t, --topo
2083 show topological heads only
2084 -a, --active
2086 show active branchheads only (DEPRECATED)
2087 -c, --closed
2089 show normal and closed branch heads
2090 --style <STYLE>
2092 display using template map file (DEPRECATED)
2093 -T,--template <TEMPLATE>
2095 display with template
2096 identify
2098 identify the working directory or specified revision:
2099 hg identify [-nibtB] [-r REV] [SOURCE]
2101 Print a summary identifying the repository state at REV using one or
2103 two parent hash identifiers, followed by a "+" if the working directory
2104 has uncommitted changes, the branch name (if not default), a list of
2105 tags, and a list of bookmarks.
2106 When REV is not given, print a summary of the current state of the
2108 repository including the working directory. Specify -r. to get informa‐
2109 tion of the working directory parent without scanning uncommitted
2110 changes.
2111 Specifying a path to a repository root or Mercurial bundle will cause
2113 lookup to operate on that repository/bundle.
2114 Template:
2116 The following keywords are supported in addition to the common template
2118 keywords and functions. See also hg help templates.
2119 dirty String. Character + denoting if the working directory has uncom‐
2121 mitted changes.
2122 id String. One or two nodes, optionally followed by +.
2124 parents
2126 List of strings. Parent nodes of the changeset.
2127 Examples:
2129 • generate a build identifier for the working directory:
2131 hg id --id > build-id.dat
2133 • find the revision corresponding to a tag:
2135 hg id -n -r 1.3
2137 • check the most recent revision of a remote repository:
2139 hg id -r tip https://www.mercurial-scm.org/repo/hg/
2141 See hg log for generating more information about specific revisions,
2143 including full hash identifiers.
2144 Returns 0 if successful.
2146 Options:
2148 -r,--rev <REV>
2150 identify the specified revision
2151 -n, --num
2153 show local revision number
2154 -i, --id
2156 show global revision id
2157 -b, --branch
2159 show branch
2160 -t, --tags
2162 show tags
2163 -B, --bookmarks
2165 show bookmarks
2166 -e,--ssh <CMD>
2168 specify ssh command to use
2169 --remotecmd <CMD>
2171 specify hg command to run on the remote side
2172 --insecure
2174 do not verify server certificate (ignoring web.cacerts config)
2175 -T,--template <TEMPLATE>
2177 display with template
2178 aliases: id
2180 log
2182 show revision history of entire repository or files:
2183 hg log [OPTION]... [FILE]
2185 Print the revision history of the specified files or the entire
2187 project.
2188 If no revision range is specified, the default is tip:0 unless --follow
2190 is set.
2191 File history is shown without following rename or copy history of
2193 files. Use -f/--follow with a filename to follow history across renames
2194 and copies. --follow without a filename will only show ancestors of the
2195 starting revisions. The starting revisions can be specified by
2196 -r/--rev, which default to the working directory parent.
2197 By default this command prints revision number and changeset id, tags,
2199 non-trivial parents, user, date and time, and a summary for each com‐
2200 mit. When the -v/--verbose switch is used, the list of changed files
2201 and full commit message are shown.
2202 With --graph the revisions are shown as an ASCII art DAG with the most
2204 recent changeset at the top. 'o' is a changeset, '@' is a working di‐
2205 rectory parent, '%' is a changeset involved in an unresolved merge con‐
2206 flict, '_' closes a branch, 'x' is obsolete, '*' is unstable, and '+'
2207 represents a fork where the changeset from the lines below is a parent
2208 of the 'o' merge on the same line. Paths in the DAG are represented
2209 with '|', '/' and so forth. ':' in place of a '|' indicates one or more
2210 revisions in a path are omitted.
2211 Use -L/--line-range FILE,M:N options to follow the history of lines
2213 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2214 fied line range will be shown. This option requires --follow; it can be
2215 specified multiple times. Currently, this option is not compatible with
2216 --graph. This option is experimental.
2217 Note hg log --patch may generate unexpected diff output for merge
2219 changesets, as it will only compare the merge changeset against
2220 its first parent. Also, only files different from BOTH parents
2221 will appear in files:.
2222 Note For performance reasons, hg log FILE may omit duplicate changes
2224 made on branches and will not show removals or mode changes. To
2225 see all such changes, use the --removed switch.
2226 Note The history resulting from -L/--line-range options depends on
2228 diff options; for instance if white-spaces are ignored, respec‐
2229 tive changes with only white-spaces in specified line range will
2230 not be listed.
2231 Some examples:
2233 • changesets with full descriptions and file lists:
2235 hg log -v
2237 • changesets ancestral to the working directory:
2239 hg log -f
2241 • last 10 commits on the current branch:
2243 hg log -l 10 -b .
2245 • changesets showing all modifications of a file, including removals:
2247 hg log --removed file.c
2249 • all changesets that touch a directory, with diffs, excluding merges:
2251 hg log -Mp lib/
2253 • all revision numbers that match a keyword:
2255 hg log -k bug --template "{rev}\n"
2257 • the full hash identifier of the working directory parent:
2259 hg log -r . --template "{node}\n"
2261 • list available log templates:
2263 hg log -T list
2265 • check if a given changeset is included in a tagged release:
2267 hg log -r "a21ccf and ancestor(1.9)"
2269 • find all changesets by some user in a date range:
2271 hg log -k alice -d "may 2008 to jul 2008"
2273 • summary of all changesets after the last tag:
2275 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2277 • changesets touching lines 13 to 23 for file.c:
2279 hg log -L file.c,13:23
2281 • changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2283 main.c with patch:
2284 hg log -L file.c,13:23 -L main.c,2:6 -p
2286 See hg help dates for a list of formats valid for -d/--date.
2288 See hg help revisions for more about specifying and ordering revisions.
2290 See hg help templates for more about pre-packaged styles and specifying
2292 custom templates. The default template used by the log command can be
2293 customized via the command-templates.log configuration setting.
2294 Returns 0 on success.
2296 Options:
2298 -f, --follow
2300 follow changeset history, or file history across copies and re‐
2301 names
2302 --follow-first
2304 only follow the first parent of merge changesets (DEPRECATED)
2305 -d,--date <DATE>
2307 show revisions matching date spec
2308 -C, --copies
2310 show copied files
2311 -k,--keyword <TEXT[+]>
2313 do case-insensitive search for a given text
2314 -r,--rev <REV[+]>
2316 revisions to select or follow from
2317 -L,--line-range <FILE,RANGE[+]>
2319 follow line range of specified file (EXPERIMENTAL)
2320 --removed
2322 include revisions where files were removed
2323 -m, --only-merges
2325 show only merges (DEPRECATED) (use -r "merge()" instead)
2326 -u,--user <USER[+]>
2328 revisions committed by user
2329 --only-branch <BRANCH[+]>
2331 show only changesets within the given named branch (DEPRECATED)
2332 -b,--branch <BRANCH[+]>
2334 show changesets within the given named branch
2335 -B,--bookmark <BOOKMARK[+]>
2337 show changesets within the given bookmark
2338 -P,--prune <REV[+]>
2340 do not display revision or any of its ancestors
2341 -p, --patch
2343 show patch
2344 -g, --git
2346 use git extended diff format
2347 -l,--limit <NUM>
2349 limit number of changes displayed
2350 -M, --no-merges
2352 do not show merges
2353 --stat output diffstat-style summary of changes
2355 -G, --graph
2357 show the revision DAG
2358 --style <STYLE>
2360 display using template map file (DEPRECATED)
2361 -T,--template <TEMPLATE>
2363 display with template
2364 -I,--include <PATTERN[+]>
2366 include names matching the given patterns
2367 -X,--exclude <PATTERN[+]>
2369 exclude names matching the given patterns
2370 [+] marked option can be specified multiple times
2372 aliases: history
2374 parents
2376 show the parents of the working directory or revision (DEPRECATED):
2377 hg parents [-r REV] [FILE]
2379 Print the working directory's parent revisions. If a revision is given
2381 via -r/--rev, the parent of that revision will be printed. If a file
2382 argument is given, the revision in which the file was last changed (be‐
2383 fore the working directory revision or the argument to --rev if given)
2384 is printed.
2385 This command is equivalent to:
2387 hg log -r "p1()+p2()" or
2389 hg log -r "p1(REV)+p2(REV)" or
2390 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2391 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2392 See hg summary and hg help revsets for related information.
2394 Returns 0 on success.
2396 Options:
2398 -r,--rev <REV>
2400 show parents of the specified revision
2401 --style <STYLE>
2403 display using template map file (DEPRECATED)
2404 -T,--template <TEMPLATE>
2406 display with template
2407 tip
2409 show the tip revision (DEPRECATED):
2410 hg tip [-p] [-g]
2412 The tip revision (usually just called the tip) is the changeset most
2414 recently added to the repository (and therefore the most recently
2415 changed head).
2416 If you have just made a commit, that commit will be the tip. If you
2418 have just pulled changes from another repository, the tip of that
2419 repository becomes the current tip. The "tip" tag is special and cannot
2420 be renamed or assigned to a different changeset.
2421 This command is deprecated, please use hg heads instead.
2423 Returns 0 on success.
2425 Options:
2427 -p, --patch
2429 show patch
2430 -g, --git
2432 use git extended diff format
2433 --style <STYLE>
2435 display using template map file (DEPRECATED)
2436 -T,--template <TEMPLATE>
2438 display with template
2439 Working directory management
2441 add
2442 add the specified files on the next commit:
2443 hg add [OPTION]... [FILE]...
2445 Schedule files to be version controlled and added to the repository.
2447 The files will be added to the repository at the next commit. To undo
2449 an add before that, see hg forget.
2450 If no names are given, add all files to the repository (except files
2452 matching .hgignore).
2453 Examples:
2455 • New (unknown) files are added automatically by hg add:
2457 $ ls
2459 foo.c
2460 $ hg status
2461 ? foo.c
2462 $ hg add
2463 adding foo.c
2464 $ hg status
2465 A foo.c
2466 • Specific files to be added can be specified:
2468 $ ls
2470 bar.c foo.c
2471 $ hg status
2472 ? bar.c
2473 ? foo.c
2474 $ hg add bar.c
2475 $ hg status
2476 A bar.c
2477 ? foo.c
2478 Returns 0 if all files are successfully added.
2480 Options:
2482 -I,--include <PATTERN[+]>
2484 include names matching the given patterns
2485 -X,--exclude <PATTERN[+]>
2487 exclude names matching the given patterns
2488 -S, --subrepos
2490 recurse into subrepositories
2491 -n, --dry-run
2493 do not perform actions, just print output
2494 [+] marked option can be specified multiple times
2496 addremove
2498 add all new files, delete all missing files:
2499 hg addremove [OPTION]... [FILE]...
2501 Add all new files and remove all missing files from the repository.
2503 Unless names are given, new files are ignored if they match any of the
2505 patterns in .hgignore. As with add, these changes take effect at the
2506 next commit.
2507 Use the -s/--similarity option to detect renamed files. This option
2509 takes a percentage between 0 (disabled) and 100 (files must be identi‐
2510 cal) as its parameter. With a parameter greater than 0, this compares
2511 every removed file with every added file and records those similar
2512 enough as renames. Detecting renamed files this way can be expensive.
2513 After using this option, hg status -C can be used to check which files
2514 were identified as moved or renamed. If not specified, -s/--similarity
2515 defaults to 100 and only renames of identical files are detected.
2516 Examples:
2518 • A number of files (bar.c and foo.c) are new, while foobar.c has
2520 been removed (without using hg remove) from the repository:
2521 $ ls
2523 bar.c foo.c
2524 $ hg status
2525 ! foobar.c
2526 ? bar.c
2527 ? foo.c
2528 $ hg addremove
2529 adding bar.c
2530 adding foo.c
2531 removing foobar.c
2532 $ hg status
2533 A bar.c
2534 A foo.c
2535 R foobar.c
2536 • A file foobar.c was moved to foo.c without using hg rename. Af‐
2538 terwards, it was edited slightly:
2539 $ ls
2541 foo.c
2542 $ hg status
2543 ! foobar.c
2544 ? foo.c
2545 $ hg addremove --similarity 90
2546 removing foobar.c
2547 adding foo.c
2548 recording removal of foobar.c as rename to foo.c (94% similar)
2549 $ hg status -C
2550 A foo.c
2551 foobar.c
2552 R foobar.c
2553 Returns 0 if all files are successfully added.
2555 Options:
2557 -s,--similarity <SIMILARITY>
2559 guess renamed files by similarity (0<=s<=100)
2560 -S, --subrepos
2562 recurse into subrepositories
2563 -I,--include <PATTERN[+]>
2565 include names matching the given patterns
2566 -X,--exclude <PATTERN[+]>
2568 exclude names matching the given patterns
2569 -n, --dry-run
2571 do not perform actions, just print output
2572 [+] marked option can be specified multiple times
2574 files
2576 list tracked files:
2577 hg files [OPTION]... [FILE]...
2579 Print files under Mercurial control in the working directory or speci‐
2581 fied revision for given files (excluding removed files). Files can be
2582 specified as filenames or filesets.
2583 If no files are given to match, this command prints the names of all
2585 files under Mercurial control.
2586 Template:
2588 The following keywords are supported in addition to the common template
2590 keywords and functions. See also hg help templates.
2591 flags String. Character denoting file's symlink and executable bits.
2593 path String. Repository-absolute path of the file.
2595 size Integer. Size of the file in bytes.
2597 Examples:
2599 • list all files under the current directory:
2601 hg files .
2603 • shows sizes and flags for current revision:
2605 hg files -vr .
2607 • list all files named README:
2609 hg files -I "**/README"
2611 • list all binary files:
2613 hg files "set:binary()"
2615 • find files containing a regular expression:
2617 hg files "set:grep('bob')"
2619 • search tracked file contents with xargs and grep:
2621 hg files -0 | xargs -0 grep foo
2623 See hg help patterns and hg help filesets for more information on spec‐
2625 ifying file patterns.
2626 Returns 0 if a match is found, 1 otherwise.
2628 Options:
2630 -r,--rev <REV>
2632 search the repository as it is in REV
2633 -0, --print0
2635 end filenames with NUL, for use with xargs
2636 -I,--include <PATTERN[+]>
2638 include names matching the given patterns
2639 -X,--exclude <PATTERN[+]>
2641 exclude names matching the given patterns
2642 -T,--template <TEMPLATE>
2644 display with template
2645 -S, --subrepos
2647 recurse into subrepositories
2648 [+] marked option can be specified multiple times
2650 forget
2652 forget the specified files on the next commit:
2653 hg forget [OPTION]... FILE...
2655 Mark the specified files so they will no longer be tracked after the
2657 next commit.
2658 This only removes files from the current branch, not from the entire
2660 project history, and it does not delete them from the working direc‐
2661 tory.
2662 To delete the file from the working directory, see hg remove.
2664 To undo a forget before the next commit, see hg add.
2666 Examples:
2668 • forget newly-added binary files:
2670 hg forget "set:added() and binary()"
2672 • forget files that would be excluded by .hgignore:
2674 hg forget "set:hgignore()"
2676 Returns 0 on success.
2678 Options:
2680 -i, --interactive
2682 use interactive mode
2683 -I,--include <PATTERN[+]>
2685 include names matching the given patterns
2686 -X,--exclude <PATTERN[+]>
2688 exclude names matching the given patterns
2689 -n, --dry-run
2691 do not perform actions, just print output
2692 [+] marked option can be specified multiple times
2694 locate
2696 locate files matching specific patterns (DEPRECATED):
2697 hg locate [OPTION]... [PATTERN]...
2699 Print files under Mercurial control in the working directory whose
2701 names match the given patterns.
2702 By default, this command searches all directories in the working direc‐
2704 tory. To search just the current directory and its subdirectories, use
2705 "--include .".
2706 If no patterns are given to match, this command prints the names of all
2708 files under Mercurial control in the working directory.
2709 If you want to feed the output of this command into the "xargs" com‐
2711 mand, use the -0 option to both this command and "xargs". This will
2712 avoid the problem of "xargs" treating single filenames that contain
2713 whitespace as multiple filenames.
2714 See hg help files for a more versatile command.
2716 Returns 0 if a match is found, 1 otherwise.
2718 Options:
2720 -r,--rev <REV>
2722 search the repository as it is in REV
2723 -0, --print0
2725 end filenames with NUL, for use with xargs
2726 -f, --fullpath
2728 print complete paths from the filesystem root
2729 -I,--include <PATTERN[+]>
2731 include names matching the given patterns
2732 -X,--exclude <PATTERN[+]>
2734 exclude names matching the given patterns
2735 [+] marked option can be specified multiple times
2737 purge
2739 removes files not tracked by Mercurial:
2740 hg purge [OPTION]... [DIR]...
2742 Delete files not known to Mercurial. This is useful to test local and
2744 uncommitted changes in an otherwise-clean source tree.
2745 This means that purge will delete the following by default:
2747 • Unknown files: files marked with "?" by hg status
2749 • Empty directories: in fact Mercurial ignores directories unless they
2751 contain files under source control management
2752 But it will leave untouched:
2754 • Modified and unmodified tracked files
2756 • Ignored files (unless -i or --all is specified)
2758 • New files added to the repository (with hg add)
2760 The --files and --dirs options can be used to direct purge to delete
2762 only files, only directories, or both. If neither option is given, both
2763 will be deleted.
2764 If directories are given on the command line, only files in these di‐
2766 rectories are considered.
2767 Be careful with purge, as you could irreversibly delete some files you
2769 forgot to add to the repository. If you only want to print the list of
2770 files that this program would delete, use the --print option.
2771 Options:
2773 -a, --abort-on-err
2775 abort if an error occurs
2776 --all purge ignored files too
2778 -i, --ignored
2780 purge only ignored files
2781 --dirs purge empty directories
2783 --files
2785 purge files
2786 -p, --print
2788 print filenames instead of deleting them
2789 -0, --print0
2791 end filenames with NUL, for use with xargs (implies -p/--print)
2792 --confirm
2794 ask before permanently deleting files
2795 -I,--include <PATTERN[+]>
2797 include names matching the given patterns
2798 -X,--exclude <PATTERN[+]>
2800 exclude names matching the given patterns
2801 [+] marked option can be specified multiple times
2803 aliases: clean
2805 remove
2807 remove the specified files on the next commit:
2808 hg remove [OPTION]... FILE...
2810 Schedule the indicated files for removal from the current branch.
2812 This command schedules the files to be removed at the next commit. To
2814 undo a remove before that, see hg revert. To undo added files, see hg
2815 forget.
2816 -A/--after can be used to remove only files that have already been
2818 deleted, -f/--force can be used to force deletion, and -Af can be used
2819 to remove files from the next revision without deleting them from the
2820 working directory.
2821 The following table details the behavior of remove for different file
2823 states (columns) and option combinations (rows). The file states are
2824 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2825 status). The actions are Warn, Remove (from branch) and Delete (from
2826 disk):
2827 ┌──────────┬───┬────┬────┬───┐
2829 │opt/state │ A │ C │ M │ ! │
2830 ├──────────┼───┼────┼────┼───┤
2831 │none │ W │ RD │ W │ R │
2832 ├──────────┼───┼────┼────┼───┤
2833 │-f │ R │ RD │ RD │ R │
2834 ├──────────┼───┼────┼────┼───┤
2835 │-A │ W │ W │ W │ R │
2836 ├──────────┼───┼────┼────┼───┤
2837 │-Af │ R │ R │ R │ R │
2838 └──────────┴───┴────┴────┴───┘
2839 Note hg remove never deletes files in Added [A] state from the work‐
2841 ing directory, not even if --force is specified.
2842 Returns 0 on success, 1 if any warnings encountered.
2844 Options:
2846 -A, --after
2848 record delete for missing files
2849 -f, --force
2851 forget added files, delete modified files
2852 -S, --subrepos
2854 recurse into subrepositories
2855 -I,--include <PATTERN[+]>
2857 include names matching the given patterns
2858 -X,--exclude <PATTERN[+]>
2860 exclude names matching the given patterns
2861 -n, --dry-run
2863 do not perform actions, just print output
2864 [+] marked option can be specified multiple times
2866 aliases: rm
2868 rename
2870 rename files; equivalent of copy + remove:
2871 hg rename [OPTION]... SOURCE... DEST
2873 Mark dest as copies of sources; mark sources for deletion. If dest is a
2875 directory, copies are put in that directory. If dest is a file, there
2876 can only be one source.
2877 By default, this command copies the contents of files as they exist in
2879 the working directory. If invoked with -A/--after, the operation is
2880 recorded, but no copying is performed.
2881 To undo marking a destination file as renamed, use --forget. With that
2883 option, all given (positional) arguments are unmarked as renames. The
2884 destination file(s) will be left in place (still tracked). The source
2885 file(s) will not be restored. Note that hg rename --forget behaves the
2886 same way as hg copy --forget.
2887 This command takes effect with the next commit by default.
2889 Returns 0 on success, 1 if errors are encountered.
2891 Options:
2893 --forget
2895 unmark a destination file as renamed
2896 -A, --after
2898 record a rename that has already occurred
2899 --at-rev <REV>
2901 (un)mark renames in the given revision (EXPERIMENTAL)
2902 -f, --force
2904 forcibly move over an existing managed file
2905 -I,--include <PATTERN[+]>
2907 include names matching the given patterns
2908 -X,--exclude <PATTERN[+]>
2910 exclude names matching the given patterns
2911 -n, --dry-run
2913 do not perform actions, just print output
2914 [+] marked option can be specified multiple times
2916 aliases: move mv
2918 resolve
2920 redo merges or set/view the merge status of files:
2921 hg resolve [OPTION]... [FILE]...
2923 Merges with unresolved conflicts are often the result of non-interac‐
2925 tive merging using the internal:merge configuration setting, or a com‐
2926 mand-line merge tool like diff3. The resolve command is used to manage
2927 the files involved in a merge, after hg merge has been run, and before
2928 hg commit is run (i.e. the working directory must have two parents).
2929 See hg help merge-tools for information on configuring merge tools.
2930 The resolve command can be used in the following ways:
2932 • hg resolve [--re-merge] [--tool TOOL] FILE...: attempt to re-merge
2934 the specified files, discarding any previous merge attempts. Re-merg‐
2935 ing is not performed for files already marked as resolved. Use
2936 --all/-a to select all unresolved files. --tool can be used to spec‐
2937 ify the merge tool used for the given files. It overrides the HGMERGE
2938 environment variable and your configuration files. Previous file
2939 contents are saved with a .orig suffix.
2940 • hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
2942 having manually fixed-up the files). The default is to mark all unre‐
2943 solved files.
2944 • hg resolve -u [FILE]...: mark a file as unresolved. The default is to
2946 mark all resolved files.
2947 • hg resolve -l: list files which had or still have conflicts. In the
2949 printed list, U = unresolved and R = resolved. You can use set:unre‐
2950 solved() or set:resolved() to filter the list. See hg help filesets
2951 for details.
2952 Note Mercurial will not let you commit files with unresolved merge
2954 conflicts. You must use hg resolve -m ... before you can commit
2955 after a conflicting merge.
2956 Template:
2958 The following keywords are supported in addition to the common template
2960 keywords and functions. See also hg help templates.
2961 mergestatus
2963 String. Character denoting merge conflicts, U or R.
2964 path String. Repository-absolute path of the file.
2966 Returns 0 on success, 1 if any files fail a resolve attempt.
2968 Options:
2970 -a, --all
2972 select all unresolved files
2973 -l, --list
2975 list state of files needing merge
2976 -m, --mark
2978 mark files as resolved
2979 -u, --unmark
2981 mark files as unresolved
2982 -n, --no-status
2984 hide status prefix
2985 --re-merge
2987 re-merge files
2988 -t,--tool <TOOL>
2990 specify merge tool
2991 -I,--include <PATTERN[+]>
2993 include names matching the given patterns
2994 -X,--exclude <PATTERN[+]>
2996 exclude names matching the given patterns
2997 -T,--template <TEMPLATE>
2999 display with template
3000 [+] marked option can be specified multiple times
3002 revert
3004 restore files to their checkout state:
3005 hg revert [OPTION]... [-r REV] [NAME]...
3007 Note To check out earlier revisions, you should use hg update REV.
3009 To cancel an uncommitted merge (and lose your changes), use hg
3010 merge --abort.
3011 With no revision specified, revert the specified files or directories
3013 to the contents they had in the parent of the working directory. This
3014 restores the contents of files to an unmodified state and unschedules
3015 adds, removes, copies, and renames. If the working directory has two
3016 parents, you must explicitly specify a revision.
3017 Using the -r/--rev or -d/--date options, revert the given files or di‐
3019 rectories to their states as of a specific revision. Because revert
3020 does not change the working directory parents, this will cause these
3021 files to appear modified. This can be helpful to "back out" some or all
3022 of an earlier change. See hg backout for a related method.
3023 Modified files are saved with a .orig suffix before reverting. To dis‐
3025 able these backups, use --no-backup. It is possible to store the backup
3026 files in a custom directory relative to the root of the repository by
3027 setting the ui.origbackuppath configuration option.
3028 See hg help dates for a list of formats valid for -d/--date.
3030 See hg help backout for a way to reverse the effect of an earlier
3032 changeset.
3033 Returns 0 on success.
3035 Options:
3037 -a, --all
3039 revert all changes when no arguments given
3040 -d,--date <DATE>
3042 tipmost revision matching date
3043 -r,--rev <REV>
3045 revert to the specified revision
3046 -C, --no-backup
3048 do not save backup copies of files
3049 -i, --interactive
3051 interactively select the changes
3052 -I,--include <PATTERN[+]>
3054 include names matching the given patterns
3055 -X,--exclude <PATTERN[+]>
3057 exclude names matching the given patterns
3058 -n, --dry-run
3060 do not perform actions, just print output
3061 [+] marked option can be specified multiple times
3063 root
3065 print the root (top) of the current working directory:
3066 hg root
3068 Print the root directory of the current repository.
3070 Template:
3072 The following keywords are supported in addition to the common template
3074 keywords and functions. See also hg help templates.
3075 hgpath String. Path to the .hg directory.
3077 storepath
3079 String. Path to the directory holding versioned data.
3080 Returns 0 on success.
3082 Options:
3084 -T,--template <TEMPLATE>
3086 display with template
3087 shelve
3089 save and set aside changes from the working directory:
3090 hg shelve [OPTION]... [FILE]...
3092 Shelving takes files that "hg status" reports as not clean, saves the
3094 modifications to a bundle (a shelved change), and reverts the files so
3095 that their state in the working directory becomes clean.
3096 To restore these changes to the working directory, using "hg unshelve";
3098 this will work even if you switch to a different commit.
3099 When no files are specified, "hg shelve" saves all not-clean files. If
3101 specific files or directories are named, only changes to those files
3102 are shelved.
3103 In bare shelve (when no files are specified, without interactive, in‐
3105 clude and exclude option), shelving remembers information if the work‐
3106 ing directory was on newly created branch, in other words working di‐
3107 rectory was on different branch than its first parent. In this situa‐
3108 tion unshelving restores branch information to the working directory.
3109 Each shelved change has a name that makes it easier to find later. The
3111 name of a shelved change defaults to being based on the active book‐
3112 mark, or if there is no active bookmark, the current named branch. To
3113 specify a different name, use --name.
3114 To see a list of existing shelved changes, use the --list option. For
3116 each shelved change, this will print its name, age, and description;
3117 use --patch or --stat for more details.
3118 To delete specific shelved changes, use --delete. To delete all shelved
3120 changes, use --cleanup.
3121 Options:
3123 -A, --addremove
3125 mark new/missing files as added/removed before shelving
3126 -u, --unknown
3128 store unknown files in the shelve
3129 --cleanup
3131 delete all shelved changes
3132 --date <DATE>
3134 shelve with the specified commit date
3135 -d, --delete
3137 delete the named shelved change(s)
3138 -e, --edit
3140 invoke editor on commit messages
3141 -k, --keep
3143 shelve, but keep changes in the working directory
3144 -l, --list
3146 list current shelves
3147 -m,--message <TEXT>
3149 use text as shelve message
3150 -n,--name <NAME>
3152 use the given name for the shelved commit
3153 -p, --patch
3155 output patches for changes (provide the names of the shelved
3156 changes as positional arguments)
3157 -i, --interactive
3159 interactive mode
3160 --stat output diffstat-style summary of changes (provide the names of
3162 the shelved changes as positional arguments)
3163 -I,--include <PATTERN[+]>
3165 include names matching the given patterns
3166 -X,--exclude <PATTERN[+]>
3168 exclude names matching the given patterns
3169 [+] marked option can be specified multiple times
3171 status
3173 show changed files in the working directory:
3174 hg status [OPTION]... [FILE]...
3176 Show status of files in the repository. If names are given, only files
3178 that match are shown. Files that are clean or ignored or the source of
3179 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3180 -C/--copies or -A/--all are given. Unless options described with "show
3181 only ..." are given, the options -mardu are used.
3182 Option -q/--quiet hides untracked (unknown and ignored) files unless
3184 explicitly requested with -u/--unknown or -i/--ignored.
3185 Note hg status may appear to disagree with diff if permissions have
3187 changed or a merge has occurred. The standard diff format does
3188 not report permission changes and diff only reports changes rel‐
3189 ative to one merge parent.
3190 If one revision is given, it is used as the base revision. If two re‐
3192 visions are given, the differences between them are shown. The --change
3193 option can also be used as a shortcut to list the changed files of a
3194 revision from its first parent.
3195 The codes used to show the status of files are:
3197 M = modified
3199 A = added
3200 R = removed
3201 C = clean
3202 ! = missing (deleted by non-hg command, but still tracked)
3203 ? = not tracked
3204 I = ignored
3205 = origin of the previous file (with --copies)
3206 The -t/--terse option abbreviates the output by showing only the direc‐
3208 tory name if all the files in it share the same status. The option
3209 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3210 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3211 'unknown', 'i' for 'ignored' and 'c' for clean.
3212 It abbreviates only those statuses which are passed. Note that clean
3214 and ignored files are not displayed with '--terse ic' unless the
3215 -c/--clean and -i/--ignored options are also used.
3216 The -v/--verbose option shows information when the repository is in an
3218 unfinished merge, shelve, rebase state etc. You can have this behavior
3219 turned on by default by enabling the commands.status.verbose option.
3220 You can skip displaying some of these states by setting commands.sta‐
3222 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3223 'merge', 'rebase', or 'unshelve'.
3224 Template:
3226 The following keywords are supported in addition to the common template
3228 keywords and functions. See also hg help templates.
3229 path String. Repository-absolute path of the file.
3231 source String. Repository-absolute path of the file originated from.
3233 Available if --copies is specified.
3234 status String. Character denoting file's status.
3236 Examples:
3238 • show changes in the working directory relative to a changeset:
3240 hg status --rev 9353
3242 • show changes in the working directory relative to the current direc‐
3244 tory (see hg help patterns for more information):
3245 hg status re:
3247 • show all changes including copies in an existing changeset:
3249 hg status --copies --change 9353
3251 • get a NUL separated list of added files, suitable for xargs:
3253 hg status -an0
3255 • show more information about the repository status, abbreviating
3257 added, removed, modified, deleted, and untracked paths:
3258 hg status -v -t mardu
3260 Returns 0 on success.
3262 Options:
3264 -A, --all
3266 show status of all files
3267 -m, --modified
3269 show only modified files
3270 -a, --added
3272 show only added files
3273 -r, --removed
3275 show only removed files
3276 -d, --deleted
3278 show only missing files
3279 -c, --clean
3281 show only files without changes
3282 -u, --unknown
3284 show only unknown (not tracked) files
3285 -i, --ignored
3287 show only ignored files
3288 -n, --no-status
3290 hide status prefix
3291 -t,--terse <VALUE>
3293 show the terse output (EXPERIMENTAL) (default: nothing)
3294 -C, --copies
3296 show source of copied files (DEFAULT: ui.statuscopies)
3297 -0, --print0
3299 end filenames with NUL, for use with xargs
3300 --rev <REV[+]>
3302 show difference from revision
3303 --change <REV>
3305 list the changed files of a revision
3306 -I,--include <PATTERN[+]>
3308 include names matching the given patterns
3309 -X,--exclude <PATTERN[+]>
3311 exclude names matching the given patterns
3312 -S, --subrepos
3314 recurse into subrepositories
3315 -T,--template <TEMPLATE>
3317 display with template
3318 [+] marked option can be specified multiple times
3320 aliases: st
3322 summary
3324 summarize working directory state:
3325 hg summary [--remote]
3327 This generates a brief summary of the working directory state, includ‐
3329 ing parents, branch, commit status, phase and available updates.
3330 With the --remote option, this will check the default paths for incom‐
3332 ing and outgoing changes. This can be time-consuming.
3333 Returns 0 on success.
3335 Options:
3337 --remote
3339 check for push and pull
3340 aliases: sum
3342 unshelve
3344 restore a shelved change to the working directory:
3345 hg unshelve [OPTION]... [[-n] SHELVED]
3347 This command accepts an optional name of a shelved change to restore.
3349 If none is given, the most recent shelved change is used.
3350 If a shelved change is applied successfully, the bundle that contains
3352 the shelved changes is moved to a backup location (.hg/shelve-backup).
3353 Since you can restore a shelved change on top of an arbitrary commit,
3355 it is possible that unshelving will result in a conflict between your
3356 changes and the commits you are unshelving onto. If this occurs, you
3357 must resolve the conflict, then use --continue to complete the unshelve
3358 operation. (The bundle will not be moved until you successfully com‐
3359 plete the unshelve.)
3360 (Alternatively, you can use --abort to abandon an unshelve that causes
3362 a conflict. This reverts the unshelved changes, and leaves the bundle
3363 in place.)
3364 If bare shelved change (without interactive, include and exclude op‐
3366 tion) was done on newly created branch it would restore branch informa‐
3367 tion to the working directory.
3368 After a successful unshelve, the shelved changes are stored in a backup
3370 directory. Only the N most recent backups are kept. N defaults to 10
3371 but can be overridden using the shelve.maxbackups configuration option.
3372 Timestamp in seconds is used to decide order of backups. More than
3374 maxbackups backups are kept, if same timestamp prevents from deciding
3375 exact order of them, for safety.
3376 Selected changes can be unshelved with --interactive flag. The working
3378 directory is updated with the selected changes, and only the unselected
3379 changes remain shelved. Note: The whole shelve is applied to working
3380 directory first before running interactively. So, this will bring up
3381 all the conflicts between working directory and the shelve, irrespec‐
3382 tive of which changes will be unshelved.
3383 Options:
3385 -a, --abort
3387 abort an incomplete unshelve operation
3388 -c, --continue
3390 continue an incomplete unshelve operation
3391 -i, --interactive
3393 use interactive mode (EXPERIMENTAL)
3394 -k, --keep
3396 keep shelve after unshelving
3397 -n,--name <NAME>
3399 restore shelved change with given name
3400 -t,--tool <VALUE>
3402 specify merge tool
3403 --date <DATE>
3405 set date for temporary commits (DEPRECATED)
3406 update
3408 update working directory (or switch revisions):
3409 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3411 Update the repository's working directory to the specified changeset.
3413 If no changeset is specified, update to the tip of the current named
3414 branch and move the active bookmark (see hg help bookmarks).
3415 Update sets the working directory's parent revision to the specified
3417 changeset (see hg help parents).
3418 If the changeset is not a descendant or ancestor of the working direc‐
3420 tory's parent and there are uncommitted changes, the update is aborted.
3421 With the -c/--check option, the working directory is checked for uncom‐
3422 mitted changes; if none are found, the working directory is updated to
3423 the specified changeset.
3424 The -C/--clean, -c/--check, and -m/--merge options control what happens
3426 if the working directory contains uncommitted changes. At most of one
3427 of them can be specified.
3428 1. If no option is specified, and if the requested changeset is an an‐
3430 cestor or descendant of the working directory's parent, the uncom‐
3431 mitted changes are merged into the requested changeset and the
3432 merged result is left uncommitted. If the requested changeset is not
3433 an ancestor or descendant (that is, it is on another branch), the
3434 update is aborted and the uncommitted changes are preserved.
3435 2. With the -m/--merge option, the update is allowed even if the re‐
3437 quested changeset is not an ancestor or descendant of the working
3438 directory's parent.
3439 3. With the -c/--check option, the update is aborted and the uncommit‐
3441 ted changes are preserved.
3442 4. With the -C/--clean option, uncommitted changes are discarded and
3444 the working directory is updated to the requested changeset.
3445 To cancel an uncommitted merge (and lose your changes), use hg merge
3447 --abort.
3448 Use null as the changeset to remove the working directory (like hg
3450 clone -U).
3451 If you want to revert just one file to an older revision, use hg revert
3453 [-r REV] NAME.
3454 See hg help dates for a list of formats valid for -d/--date.
3456 Returns 0 on success, 1 if there are unresolved files.
3458 Options:
3460 -C, --clean
3462 discard uncommitted changes (no backup)
3463 -c, --check
3465 require clean working directory
3466 -m, --merge
3468 merge uncommitted changes
3469 -d,--date <DATE>
3471 tipmost revision matching date
3472 -r,--rev <REV>
3474 revision
3475 -t,--tool <TOOL>
3477 specify merge tool
3478 aliases: up checkout co
3480 Change import/export
3482 archive
3483 create an unversioned archive of a repository revision:
3484 hg archive [OPTION]... DEST
3486 By default, the revision used is the parent of the working directory;
3488 use -r/--rev to specify a different revision.
3489 The archive type is automatically detected based on file extension (to
3491 override, use -t/--type).
3492 Examples:
3494 • create a zip file containing the 1.0 release:
3496 hg archive -r 1.0 project-1.0.zip
3498 • create a tarball excluding .hg files:
3500 hg archive project.tar.gz -X ".hg*"
3502 Valid types are:
3504 files
3506 a directory full of files (default)
3508 tar
3510 tar archive, uncompressed
3512 tbz2
3514 tar archive, compressed using bzip2
3516 tgz
3518 tar archive, compressed using gzip
3520 txz
3522 tar archive, compressed using lzma (only in Python 3)
3524 uzip
3526 zip archive, uncompressed
3528 zip
3530 zip archive, compressed using deflate
3532 The exact name of the destination archive or directory is given using a
3534 format string; see hg help export for details.
3535 Each member added to an archive file has a directory prefix prepended.
3537 Use -p/--prefix to specify a format string for the prefix. The default
3538 is the basename of the archive, with suffixes removed.
3539 Returns 0 on success.
3541 Options:
3543 --no-decode
3545 do not pass files through decoders
3546 -p,--prefix <PREFIX>
3548 directory prefix for files in archive
3549 -r,--rev <REV>
3551 revision to distribute
3552 -t,--type <TYPE>
3554 type of distribution to create
3555 -S, --subrepos
3557 recurse into subrepositories
3558 -I,--include <PATTERN[+]>
3560 include names matching the given patterns
3561 -X,--exclude <PATTERN[+]>
3563 exclude names matching the given patterns
3564 [+] marked option can be specified multiple times
3566 bundle
3568 create a bundle file:
3569 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]...
3571 Generate a bundle file containing data to be transferred to another
3573 repository.
3574 To create a bundle containing all changesets, use -a/--all (or --base
3576 null). Otherwise, hg assumes the destination will have all the nodes
3577 you specify with --base parameters. Otherwise, hg will assume the
3578 repository has all the nodes in destination, or default-push/default if
3579 no destination is specified, where destination is the repositories you
3580 provide through DEST option.
3581 You can change bundle format with the -t/--type option. See hg help
3583 bundlespec for documentation on this format. By default, the most ap‐
3584 propriate format is used and compression defaults to bzip2.
3585 The bundle file can then be transferred using conventional means and
3587 applied to another repository with the unbundle or pull command. This
3588 is useful when direct push and pull are not available or when exporting
3589 an entire repository is undesirable.
3590 Applying bundles preserves all changeset contents including permis‐
3592 sions, copy/rename information, and revision history.
3593 Returns 0 on success, 1 if no changes found.
3595 Options:
3597 --exact
3599 compute the base from the revision specified
3600 -f, --force
3602 run even when the destination is unrelated
3603 -r,--rev <REV[+]>
3605 a changeset intended to be added to the destination
3606 -b,--branch <BRANCH[+]>
3608 a specific branch you would like to bundle
3609 --base <REV[+]>
3611 a base changeset assumed to be available at the destination
3612 -a, --all
3614 bundle all changesets in the repository
3615 -t,--type <TYPE>
3617 bundle compression type to use (default: bzip2)
3618 -e,--ssh <CMD>
3620 specify ssh command to use
3621 --remotecmd <CMD>
3623 specify hg command to run on the remote side
3624 --insecure
3626 do not verify server certificate (ignoring web.cacerts config)
3627 [+] marked option can be specified multiple times
3629 export
3631 dump the header and diffs for one or more changesets:
3632 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
3634 Print the changeset header and diffs for one or more revisions. If no
3636 revision is given, the parent of the working directory is used.
3637 The information shown in the changeset header is: author, date, branch
3639 name (if non-default), changeset hash, parent(s) and commit comment.
3640 Note hg export may generate unexpected diff output for merge change‐
3642 sets, as it will compare the merge changeset against its first
3643 parent only.
3644 Output may be to a file, in which case the name of the file is given
3646 using a template string. See hg help templates. In addition to the com‐
3647 mon template keywords, the following formatting rules are supported:
3648 %%
3650 literal "%" character
3652 %H
3654 changeset hash (40 hexadecimal digits)
3656 %N
3658 number of patches being generated
3660 %R
3662 changeset revision number
3664 %b
3666 basename of the exporting repository
3668 %h
3670 short-form changeset hash (12 hexadecimal digits)
3672 %m
3674 first line of the commit message (only alphanumeric characters)
3676 %n
3678 zero-padded sequence number, starting at 1
3680 %r
3682 zero-padded changeset revision number
3684 \
3686 literal "" character
3688 Without the -a/--text option, export will avoid generating diffs of
3690 files it detects as binary. With -a, export will generate a diff any‐
3691 way, probably with undesirable results.
3692 With -B/--bookmark changesets reachable by the given bookmark are se‐
3694 lected.
3695 Use the -g/--git option to generate diffs in the git extended diff for‐
3697 mat. See hg help diffs for more information.
3698 With the --switch-parent option, the diff will be against the second
3700 parent. It can be useful to review a merge.
3701 Template:
3703 The following keywords are supported in addition to the common template
3705 keywords and functions. See also hg help templates.
3706 diff String. Diff content.
3708 parents
3710 List of strings. Parent nodes of the changeset.
3711 Examples:
3713 • use export and import to transplant a bugfix to the current branch:
3715 hg export -r 9353 | hg import -
3717 • export all the changesets between two revisions to a file with rename
3719 information:
3720 hg export --git -r 123:150 > changes.txt
3722 • split outgoing changes into a series of patches with descriptive
3724 names:
3725 hg export -r "outgoing()" -o "%n-%m.patch"
3727 Returns 0 on success.
3729 Options:
3731 -B,--bookmark <BOOKMARK>
3733 export changes only reachable by given bookmark
3734 -o,--output <FORMAT>
3736 print output to file with formatted name
3737 --switch-parent
3739 diff against the second parent
3740 -r,--rev <REV[+]>
3742 revisions to export
3743 -a, --text
3745 treat all files as text
3746 -g, --git
3748 use git extended diff format (DEFAULT: diff.git)
3749 --binary
3751 generate binary diffs in git mode (default)
3752 --nodates
3754 omit dates from diff headers
3755 -T,--template <TEMPLATE>
3757 display with template
3758 [+] marked option can be specified multiple times
3760 import
3762 import an ordered set of patches:
3763 hg import [OPTION]... PATCH...
3765 Import a list of patches and commit them individually (unless --no-com‐
3767 mit is specified).
3768 To read a patch from standard input (stdin), use "-" as the patch name.
3770 If a URL is specified, the patch will be downloaded from there.
3771 Import first applies changes to the working directory (unless --bypass
3773 is specified), import will abort if there are outstanding changes.
3774 Use --bypass to apply and commit patches directly to the repository,
3776 without affecting the working directory. Without --exact, patches will
3777 be applied on top of the working directory parent revision.
3778 You can import a patch straight from a mail message. Even patches as
3780 attachments work (to use the body part, it must have type text/plain or
3781 text/x-patch). From and Subject headers of email message are used as
3782 default committer and commit message. All text/plain body parts before
3783 first diff are added to the commit message.
3784 If the imported patch was generated by hg export, user and description
3786 from patch override values from message headers and body. Values given
3787 on command line with -m/--message and -u/--user override these.
3788 If --exact is specified, import will set the working directory to the
3790 parent of each patch before applying it, and will abort if the result‐
3791 ing changeset has a different ID than the one recorded in the patch.
3792 This will guard against various ways that portable patch formats and
3793 mail systems might fail to transfer Mercurial data or metadata. See hg
3794 bundle for lossless transmission.
3795 Use --partial to ensure a changeset will be created from the patch even
3797 if some hunks fail to apply. Hunks that fail to apply will be written
3798 to a <target-file>.rej file. Conflicts can then be resolved by hand be‐
3799 fore hg commit --amend is run to update the created changeset. This
3800 flag exists to let people import patches that partially apply without
3801 losing the associated metadata (author, date, description, ...).
3802 Note When no hunks apply cleanly, hg import --partial will create an
3804 empty changeset, importing only the patch metadata.
3805 With -s/--similarity, hg will attempt to discover renames and copies in
3807 the patch in the same way as hg addremove.
3808 It is possible to use external patch programs to perform the patch by
3810 setting the ui.patch configuration option. For the default internal
3811 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
3812 fig for more information about configuration files and how to use these
3813 options.
3814 See hg help dates for a list of formats valid for -d/--date.
3816 Examples:
3818 • import a traditional patch from a website and detect renames:
3820 hg import -s 80 http://example.com/bugfix.patch
3822 • import a changeset from an hgweb server:
3824 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
3826 • import all the patches in an Unix-style mbox:
3828 hg import incoming-patches.mbox
3830 • import patches from stdin:
3832 hg import -
3834 • attempt to exactly restore an exported changeset (not always possi‐
3836 ble):
3837 hg import --exact proposed-fix.patch
3839 • use an external tool to apply a patch which is too fuzzy for the de‐
3841 fault internal tool.
3842 hg import --config ui.patch="patch --merge" fuzzy.patch
3844 • change the default fuzzing from 2 to a less strict 7
3846 hg import --config ui.fuzz=7 fuzz.patch
3848 Returns 0 on success, 1 on partial success (see --partial).
3850 Options:
3852 -p,--strip <NUM>
3854 directory strip option for patch. This has the same meaning as
3855 the corresponding patch option (default: 1)
3856 -b,--base <PATH>
3858 base path (DEPRECATED)
3859 --secret
3861 use the secret phase for committing
3862 -e, --edit
3864 invoke editor on commit messages
3865 -f, --force
3867 skip check for outstanding uncommitted changes (DEPRECATED)
3868 --no-commit
3870 don't commit, just update the working directory
3871 --bypass
3873 apply patch without touching the working directory
3874 --partial
3876 commit even if some hunks fail
3877 --exact
3879 abort if patch would apply lossily
3880 --prefix <DIR>
3882 apply patch to subdirectory
3883 --import-branch
3885 use any branch information in patch (implied by --exact)
3886 -m,--message <TEXT>
3888 use text as commit message
3889 -l,--logfile <FILE>
3891 read commit message from file
3892 -d,--date <DATE>
3894 record the specified date as commit date
3895 -u,--user <USER>
3897 record the specified user as committer
3898 -s,--similarity <SIMILARITY>
3900 guess renamed files by similarity (0<=s<=100)
3901 aliases: patch
3903 unbundle
3905 apply one or more bundle files:
3906 hg unbundle [-u] FILE...
3908 Apply one or more bundle files generated by hg bundle.
3910 Returns 0 on success, 1 if an update has unresolved files.
3912 Options:
3914 -u, --update
3916 update to new branch head if changesets were unbundled
3917 Repository maintenance
3919 manifest
3920 output the current or given revision of the project manifest:
3921 hg manifest [-r REV]
3923 Print a list of version controlled files for the given revision. If no
3925 revision is given, the first parent of the working directory is used,
3926 or the null revision if no revision is checked out.
3927 With -v, print file permissions, symlink and executable bits. With
3929 --debug, print file revision hashes.
3930 If option --all is specified, the list of all files from all revisions
3932 is printed. This includes deleted and renamed files.
3933 Returns 0 on success.
3935 Options:
3937 -r,--rev <REV>
3939 revision to display
3940 --all list files from all revisions
3942 -T,--template <TEMPLATE>
3944 display with template
3945 recover
3947 roll back an interrupted transaction:
3948 hg recover
3950 Recover from an interrupted commit or pull.
3952 This command tries to fix the repository status after an interrupted
3954 operation. It should only be necessary when Mercurial suggests it.
3955 Returns 0 if successful, 1 if nothing to recover or verify fails.
3957 Options:
3959 --verify
3961 run hg verify after successful recover
3962 rollback
3964 roll back the last transaction (DANGEROUS) (DEPRECATED):
3965 hg rollback
3967 Please use hg commit --amend instead of rollback to correct mistakes in
3969 the last commit.
3970 This command should be used with care. There is only one level of roll‐
3972 back, and there is no way to undo a rollback. It will also restore the
3973 dirstate at the time of the last transaction, losing any dirstate
3974 changes since that time. This command does not alter the working direc‐
3975 tory.
3976 Transactions are used to encapsulate the effects of all commands that
3978 create new changesets or propagate existing changesets into a reposi‐
3979 tory.
3980 For example, the following commands are transactional, and their ef‐
3982 fects can be rolled back:
3983 • commit
3985 • import
3987 • pull
3989 • push (with this repository as the destination)
3991 • unbundle
3993 To avoid permanent data loss, rollback will refuse to rollback a commit
3995 transaction if it isn't checked out. Use --force to override this pro‐
3996 tection.
3997 The rollback command can be entirely disabled by setting the ui.roll‐
3999 back configuration setting to false. If you're here because you want to
4000 use rollback and it's disabled, you can re-enable the command by set‐
4001 ting ui.rollback to true.
4002 This command is not intended for use on public repositories. Once
4004 changes are visible for pull by other users, rolling a transaction back
4005 locally is ineffective (someone else may already have pulled the
4006 changes). Furthermore, a race is possible with readers of the reposi‐
4007 tory; for example an in-progress pull from the repository may fail if a
4008 rollback is performed.
4009 Returns 0 on success, 1 if no rollback data is available.
4011 Options:
4013 -n, --dry-run
4015 do not perform actions, just print output
4016 -f, --force
4018 ignore safety measures
4019 verify
4021 verify the integrity of the repository:
4022 hg verify
4024 Verify the integrity of the current repository.
4026 This will perform an extensive check of the repository's integrity,
4028 validating the hashes and checksums of each entry in the changelog,
4029 manifest, and tracked files, as well as the integrity of their
4030 crosslinks and indices.
4031 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
4033 information about recovery from corruption of the repository.
4034 Returns 0 on success, 1 if errors are encountered.
4036 Options:
4038 --full perform more checks (EXPERIMENTAL)
4040 Help
4042 config
4043 show combined config settings from all hgrc files:
4044 hg config [-u] [NAME]...
4046 With no arguments, print names and values of all config items.
4048 With one argument of the form section.name, print just the value of
4050 that config item.
4051 With multiple arguments, print names and values of all config items
4053 with matching section names or section.names.
4054 With --edit, start an editor on the user-level config file. With
4056 --global, edit the system-wide config file. With --local, edit the
4057 repository-level config file.
4058 With --source, the source (filename and line number) is printed for
4060 each config item.
4061 See hg help config for more information about config files.
4063 --non-shared flag is used to edit .hg/hgrc-not-shared config file.
4065 This file is not shared across shares when in share-safe mode.
4066 Template:
4068 The following keywords are supported. See also hg help templates.
4070 name String. Config name.
4072 source String. Filename and line number where the item is defined.
4074 value String. Config value.
4076 The --shared flag can be used to edit the config file of shared source
4078 repository. It only works when you have shared using the experimental
4079 share safe feature.
4080 Returns 0 on success, 1 if NAME does not exist.
4082 Options:
4084 -u, --untrusted
4086 show untrusted configuration options
4087 --exp-all-known
4089 show all known config option (EXPERIMENTAL)
4090 -e, --edit
4092 edit user config
4093 -l, --local
4095 edit repository config
4096 --source
4098 show source of configuration value
4099 --shared
4101 edit shared source repository config (EXPERIMENTAL)
4102 --non-shared
4104 edit non shared config (EXPERIMENTAL)
4105 -g, --global
4107 edit global config
4108 -T,--template <TEMPLATE>
4110 display with template
4111 aliases: showconfig debugconfig
4113 help
4115 show help for a given topic or a help overview:
4116 hg help [-eck] [-s PLATFORM] [TOPIC]
4118 With no arguments, print a list of commands with short help messages.
4120 Given a topic, extension, or command name, print help for that topic.
4122 Returns 0 if successful.
4124 Options:
4126 -e, --extension
4128 show only help for extensions
4129 -c, --command
4131 show only help for commands
4132 -k, --keyword
4134 show topics matching keyword
4135 -s,--system <PLATFORM[+]>
4137 show help for specific platform(s)
4138 [+] marked option can be specified multiple times
4140 version
4142 output version and copyright information:
4143 hg version
4145 Template:
4147 The following keywords are supported. See also hg help templates.
4149 extensions
4151 List of extensions.
4152 ver String. Version number.
4154 And each entry of {extensions} provides the following sub-keywords in
4156 addition to {ver}.
4157 bundled
4159 Boolean. True if included in the release.
4160 name String. Extension name.
4162 Options:
4164 -T,--template <TEMPLATE>
4166 display with template
4167 Uncategorized commands
4170 Mercurial supports generating standalone "bundle" files that hold
4171 repository data. These "bundles" are typically saved locally and used
4172 later or exchanged between different repositories, possibly on differ‐
4173 ent machines. Example commands using bundles are hg bundle and hg un‐
4174 bundle.
4175 Generation of bundle files is controlled by a "bundle specification"
4177 ("bundlespec") string. This string tells the bundle generation process
4178 how to create the bundle.
4179 A "bundlespec" string is composed of the following elements:
4181 type A string denoting the bundle format to use.
4183 compression
4185 Denotes the compression engine to use compressing the raw bundle
4186 data.
4187 parameters
4189 Arbitrary key-value parameters to further control bundle genera‐
4190 tion.
4191 A "bundlespec" string has the following formats:
4193 <type> The literal bundle format string is used.
4195 <compression>-<type>
4197 The compression engine and format are delimited by a hyphen (-).
4198 Optional parameters follow the <type>. Parameters are URI escaped
4200 key=value pairs. Each pair is delimited by a semicolon (;). The first
4201 parameter begins after a ; immediately following the <type> value.
4202 Available Types
4204 The following bundle <type> strings are available:
4205 v1 Produces a legacy "changegroup" version 1 bundle.
4207 This format is compatible with nearly all Mercurial clients be‐
4209 cause it is the oldest. However, it has some limitations, which
4210 is why it is no longer the default for new repositories.
4211 v1 bundles can be used with modern repositories using the "gen‐
4213 eraldelta" storage format. However, it may take longer to pro‐
4214 duce the bundle and the resulting bundle may be significantly
4215 larger than a v2 bundle.
4216 v1 bundles can only use the gzip, bzip2, and none compression
4218 formats.
4219 v2 Produces a version 2 bundle.
4221 Version 2 bundles are an extensible format that can store addi‐
4223 tional repository data (such as bookmarks and phases informa‐
4224 tion) and they can store data more efficiently, resulting in
4225 smaller bundles.
4226 Version 2 bundles can also use modern compression engines, such
4228 as zstd, making them faster to compress and often smaller.
4229 Available Compression Engines
4231 The following bundle <compression> engines can be used:
4232 bzip2
4234 An algorithm that produces smaller bundles than gzip.
4236 All Mercurial clients should support this format.
4238 This engine will likely produce smaller bundles than gzip but
4240 will be significantly slower, both during compression and decom‐
4241 pression.
4242 If available, the zstd engine can yield similar or better com‐
4244 pression at much higher speeds.
4245 gzip
4247 zlib compression using the DEFLATE algorithm.
4249 All Mercurial clients should support this format. The compres‐
4251 sion algorithm strikes a reasonable balance between compression
4252 ratio and size.
4253 none
4255 No compression is performed.
4257 Use this compression engine to explicitly disable compression.
4259 The compression engines can be prepended with stream to create a
4261 streaming bundle. These are bundles that are extremely efficient to
4262 produce and consume, but do not have guaranteed compatibility with
4263 older clients.
4264 Available Options
4266 The following options exist:
4267 changegroup
4269 Include the changegroup data in the bundle (default to True).
4270 cg.version
4272 Select the version of the changegroup to use. Available options
4273 are : 01, 02 or 03. By default it will be automatically selected
4274 according to the current repository format.
4275 obsolescence
4277 Include obsolescence-markers relevant to the bundled changesets.
4278 phases Include phase information relevant to the bundled changesets.
4280 revbranchcache
4282 Include the "tags-fnodes" cache inside the bundle.
4283 tagsfnodescache
4285 Include the "tags-fnodes" cache inside the bundle.
4286 Examples
4288 v2
4289 Produce a v2 bundle using default options, including compres‐
4291 sion.
4292 none-v1
4294 Produce a v1 bundle with no compression.
4296 zstd-v2
4298 Produce a v2 bundle with zstandard compression using default
4300 settings.
4301 zstd-v1
4303 This errors because zstd is not supported for v1 types.
4305 none-streamv2
4307 Produce a v2 streaming bundle with no compression.
4309 zstd-v2;obsolescence=true;phases=true
4311 Produce a v2 bundle with zstandard compression which includes
4313 obsolescence markers and phases.
4314
4316 Mercurial colorizes output from several commands.
4317 For example, the diff command shows additions in green and deletions in
4319 red, while the status command shows modified files in magenta. Many
4320 other commands have analogous colors. It is possible to customize these
4321 colors.
4322 To enable color (default) whenever possible use:
4324 [ui]
4326 color = yes
4327 To disable color use:
4329 [ui]
4331 color = no
4332 See hg help config.ui.color for details.
4334 The default pager on Windows does not support color, so enabling the
4336 pager will effectively disable color. See hg help config.ui.paginate
4337 to disable the pager. Alternately, MSYS and Cygwin shells provide less
4338 as a pager, which can be configured to support ANSI color mode. Win‐
4339 dows 10 natively supports ANSI color mode.
4340 Mode
4342 Mercurial can use various systems to display color. The supported modes
4343 are ansi, win32, and terminfo. See hg help config.color for details
4344 about how to control the mode.
4345 Effects
4347 Other effects in addition to color, like bold and underlined text, are
4348 also available. By default, the terminfo database is used to find the
4349 terminal codes used to change color and effect. If terminfo is not
4350 available, then effects are rendered with the ECMA-48 SGR control func‐
4351 tion (aka ANSI escape codes).
4352 The available effects in terminfo mode are 'blink', 'bold', 'dim', 'in‐
4354 verse', 'invisible', 'italic', 'standout', and 'underline'; in ECMA-48
4355 mode, the options are 'bold', 'inverse', 'italic', and 'underline'.
4356 How each is rendered depends on the terminal emulator. Some may not be
4357 available for a given terminal type, and will be silently ignored.
4358 If the terminfo entry for your terminal is missing codes for an effect
4360 or has the wrong codes, you can add or override those codes in your
4361 configuration:
4362 [color]
4364 terminfo.dim = \E[2m
4365 where 'E' is substituted with an escape character.
4367 Labels
4369 Text receives color effects depending on the labels that it has. Many
4370 default Mercurial commands emit labelled text. You can also define your
4371 own labels in templates using the label function, see hg help templates
4372 . A single portion of text may have more than one label. In that case,
4373 effects given to the last label will override any other effects. This
4374 includes the special "none" effect, which nullifies other effects.
4375 Labels are normally invisible. In order to see these labels and their
4377 position in the text, use the global --color=debug option. The same an‐
4378 chor text may be associated to multiple labels, e.g.
4379 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
4381 The following are the default effects for some default labels. Default
4383 effects may be overridden from your configuration file:
4384 [color]
4386 status.modified = blue bold underline red_background
4387 status.added = green bold
4388 status.removed = red bold blue_background
4389 status.deleted = cyan bold underline
4390 status.unknown = magenta bold underline
4391 status.ignored = black bold
4392 # 'none' turns off all effects
4394 status.clean = none
4395 status.copied = none
4396 qseries.applied = blue bold underline
4398 qseries.unapplied = black bold
4399 qseries.missing = red bold
4400 diff.diffline = bold
4402 diff.extended = cyan bold
4403 diff.file_a = red bold
4404 diff.file_b = green bold
4405 diff.hunk = magenta
4406 diff.deleted = red
4407 diff.inserted = green
4408 diff.changed = white
4409 diff.tab =
4410 diff.trailingwhitespace = bold red_background
4411 # Blank so it inherits the style of the surrounding label
4413 changeset.public =
4414 changeset.draft =
4415 changeset.secret =
4416 resolve.unresolved = red bold
4418 resolve.resolved = green bold
4419 bookmarks.active = green
4421 branches.active = none
4423 branches.closed = black bold
4424 branches.current = green
4425 branches.inactive = none
4426 tags.normal = green
4428 tags.local = black bold
4429 rebase.rebased = blue
4431 rebase.remaining = red bold
4432 shelve.age = cyan
4434 shelve.newest = green bold
4435 shelve.name = blue bold
4436 histedit.remaining = red bold
4438 Custom colors
4440 Because there are only eight standard colors, Mercurial allows you to
4441 define color names for other color slots which might be available for
4442 your terminal type, assuming terminfo mode. For instance:
4443 color.brightblue = 12
4445 color.pink = 207
4446 color.orange = 202
4447 to set 'brightblue' to color slot 12 (useful for 16 color terminals
4449 that have brighter colors defined in the upper eight) and, 'pink' and
4450 'orange' to colors in 256-color xterm's default color cube. These de‐
4451 fined colors may then be used as any of the pre-defined eight, includ‐
4452 ing appending '_background' to set the background to that color.
4453
4455 Some commands allow the user to specify a date, e.g.:
4456 • backout, commit, import, tag: Specify the commit date.
4458 • log, revert, update: Select revision(s) by date.
4460 Many date formats are valid. Here are some examples:
4462 • Wed Dec 6 13:18:29 2006 (local timezone assumed)
4464 • Dec 6 13:18 -0600 (year assumed, time offset provided)
4466 • Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
4468 • Dec 6 (midnight)
4470 • 13:18 (today assumed)
4472 • 3:39 (3:39AM assumed)
4474 • 3:39pm (15:39)
4476 • 2006-12-06 13:18:29 (ISO 8601 format)
4478 • 2006-12-6 13:18
4480 • 2006-12-6
4482 • 12-6
4484 • 12/6
4486 • 12/6/6 (Dec 6 2006)
4488 • today (midnight)
4490 • yesterday (midnight)
4492 • now - right now
4494 Lastly, there is Mercurial's internal format:
4496 • 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
4498 This is the internal representation format for dates. The first number
4500 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
4501 second is the offset of the local timezone, in seconds west of UTC
4502 (negative if the timezone is east of UTC).
4503 The log command also accepts date ranges:
4505 • <DATE - at or before a given date/time
4507 • >DATE - on or after a given date/time
4509 • DATE to DATE - a date range, inclusive
4511 • -DAYS - within a given number of days from today
4513
4515 Mercurial evolves over time, some features, options, commands may be
4516 replaced by better and more secure alternatives. This topic will help
4517 you migrating your existing usage and/or configuration to newer fea‐
4518 tures.
4519 Commands
4521 The following commands are still available but their use are not recom‐
4522 mended:
4523 locate
4525 This command has been replaced by hg files.
4527 parents
4529 This command can be replaced by hg summary or hg log with appropriate
4531 revsets. See hg help revsets for more information.
4532 tip
4534 The recommended alternative is hg heads.
4536 Options
4538 web.allowpull
4539 Renamed to allow-pull.
4541 web.allow_push
4543 Renamed to allow-push.
4545
4547 Mercurial's default format for showing changes between two versions of
4548 a file is compatible with the unified format of GNU diff, which can be
4549 used by GNU patch and many other standard tools.
4550 While this standard format is often enough, it does not encode the fol‐
4552 lowing information:
4553 • executable status and other permission bits
4555 • copy or rename information
4557 • changes in binary files
4559 • creation or deletion of empty files
4561 Mercurial also supports the extended diff format from the git VCS which
4563 addresses these limitations. The git diff format is not produced by de‐
4564 fault because a few widespread tools still do not understand this for‐
4565 mat.
4566 This means that when generating diffs from a Mercurial repository (e.g.
4568 with hg export), you should be careful about things like file copies
4569 and renames or other things mentioned above, because when applying a
4570 standard diff to a different repository, this extra information is
4571 lost. Mercurial's internal operations (like push and pull) are not af‐
4572 fected by this, because they use an internal binary format for communi‐
4573 cating changes.
4574 To make Mercurial produce the git extended diff format, use the --git
4576 option available for many commands, or set 'git = True' in the [diff]
4577 section of your configuration file. You do not need to set this option
4578 when importing diffs in this format or using them in the mq extension.
4579
4581 HG Path to the 'hg' executable, automatically passed when running
4582 hooks, extensions or external tools. If unset or empty, this is
4583 the hg executable's name if it's frozen, or an executable named
4584 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
4585 on Windows) is searched.
4586 HGEDITOR
4588 This is the name of the editor to run when committing. See EDI‐
4589 TOR.
4590 (deprecated, see hg help config.ui.editor)
4592 HGENCODING
4594 This overrides the default locale setting detected by Mercurial.
4595 This setting is used to convert data including usernames,
4596 changeset descriptions, tag names, and branches. This setting
4597 can be overridden with the --encoding command-line option.
4598 HGENCODINGMODE
4600 This sets Mercurial's behavior for handling unknown characters
4601 while transcoding user input. The default is "strict", which
4602 causes Mercurial to abort if it can't map a character. Other
4603 settings include "replace", which replaces unknown characters,
4604 and "ignore", which drops them. This setting can be overridden
4605 with the --encodingmode command-line option.
4606 HGENCODINGAMBIGUOUS
4608 This sets Mercurial's behavior for handling characters with "am‐
4609 biguous" widths like accented Latin characters with East Asian
4610 fonts. By default, Mercurial assumes ambiguous characters are
4611 narrow, set this variable to "wide" if such characters cause
4612 formatting problems.
4613 HGMERGE
4615 An executable to use for resolving merge conflicts. The program
4616 will be executed with three arguments: local file, remote file,
4617 ancestor file.
4618 (deprecated, see hg help config.ui.merge)
4620 HGRCPATH
4622 A list of files or directories to search for configuration
4623 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
4624 PATH is not set, platform default search path is used. If empty,
4625 only the .hg/hgrc from the current repository is read.
4626 For each element in HGRCPATH:
4628 • if it's a directory, all files ending with .rc are added
4630 • otherwise, the file itself will be added
4632 HGRCSKIPREPO
4634 When set, the .hg/hgrc from repositories are not read.
4635 HGPLAIN
4637 When set, this disables any configuration settings that might
4638 change Mercurial's default output. This includes encoding, de‐
4639 faults, verbose mode, debug mode, quiet mode, tracebacks, and
4640 localization. This can be useful when scripting against Mercu‐
4641 rial in the face of existing user configuration.
4642 In addition to the features disabled by HGPLAIN=, the following
4644 values can be specified to adjust behavior:
4645 +strictflags
4647 Restrict parsing of command line flags.
4649 Equivalent options set via command line flags or environment
4651 variables are not overridden.
4652 See hg help scripting for details.
4654 HGPLAINEXCEPT
4656 This is a comma-separated list of features to preserve when HG‐
4657 PLAIN is enabled. Currently the following values are supported:
4658 alias
4660 Don't remove aliases.
4662 color
4664 Don't disable colored output.
4666 i18n
4668 Preserve internationalization.
4670 revsetalias
4672 Don't remove revset aliases.
4674 templatealias
4676 Don't remove template aliases.
4678 progress
4680 Don't hide progress output.
4682 Setting HGPLAINEXCEPT to anything (even an empty string) will
4684 enable plain mode.
4685 HGUSER This is the string used as the author of a commit. If not set,
4687 available values will be considered in this order:
4688 • HGUSER (deprecated)
4690 • configuration files from the HGRCPATH
4692 • EMAIL
4694 • interactive prompt
4696 • LOGNAME (with @hostname appended)
4698 (deprecated, see hg help config.ui.username)
4700 EMAIL May be used as the author of a commit; see HGUSER.
4702 LOGNAME
4704 May be used as the author of a commit; see HGUSER.
4705 VISUAL This is the name of the editor to use when committing. See EDI‐
4707 TOR.
4708 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
4710 user to modify, for example when writing commit messages. The
4711 editor it uses is determined by looking at the environment vari‐
4712 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
4713 non-empty one is chosen. If all of them are empty, the editor
4714 defaults to 'vi'.
4715 PYTHONPATH
4717 This is used by Python to find imported modules and may need to
4718 be set appropriately if this Mercurial is not installed sys‐
4719 tem-wide.
4720
4722 Obsolescence markers make it possible to mark changesets that have been
4723 deleted or superseded in a new version of the changeset.
4724 Unlike the previous way of handling such changes, by stripping the old
4726 changesets from the repository, obsolescence markers can be propagated
4727 between repositories. This allows for a safe and simple way of exchang‐
4728 ing mutable history and altering it after the fact. Changeset phases
4729 are respected, such that only draft and secret changesets can be al‐
4730 tered (see hg help phases for details).
4731 Obsolescence is tracked using "obsolescence markers", a piece of meta‐
4733 data tracking which changesets have been made obsolete, potential suc‐
4734 cessors for a given changeset, the moment the changeset was marked as
4735 obsolete, and the user who performed the rewriting operation. The mark‐
4736 ers are stored separately from standard changeset data can be exchanged
4737 without any of the precursor changesets, preventing unnecessary ex‐
4738 change of obsolescence data.
4739 The complete set of obsolescence markers describes a history of change‐
4741 set modifications that is orthogonal to the repository history of file
4742 modifications. This changeset history allows for detection and auto‐
4743 matic resolution of edge cases arising from multiple users rewriting
4744 the same part of history concurrently.
4745 Current feature status
4747 This feature is still in development.
4748 Instability
4750 Rewriting changesets might introduce instability.
4751 There are two main kinds of instability: orphaning and diverging.
4753 Orphans are changesets left behind when their ancestors are rewritten.
4755 Divergence has two variants:
4756 • Content-divergence occurs when independent rewrites of the same
4758 changesets lead to different results.
4759 • Phase-divergence occurs when the old (obsolete) version of a change‐
4761 set becomes public.
4762 It is possible to prevent local creation of orphans by using the fol‐
4764 lowing config:
4765 [experimental]
4767 evolution.createmarkers = true
4768 evolution.exchange = true
4769 You can also enable that option explicitly:
4771 [experimental]
4773 evolution.createmarkers = true
4774 evolution.exchange = true
4775 evolution.allowunstable = true
4776
4778 Mercurial has the ability to add new features through the use of exten‐
4779 sions. Extensions may add new commands, add options to existing com‐
4780 mands, change the default behavior of commands, or implement hooks.
4781 To enable the "foo" extension, either shipped with Mercurial or in the
4783 Python search path, create an entry for it in your configuration file,
4784 like this:
4785 [extensions]
4787 foo =
4788 You may also specify the full path to an extension:
4790 [extensions]
4792 myfeature = ~/.hgext/myfeature.py
4793 See hg help config for more information on configuration files.
4795 Extensions are not loaded by default for a variety of reasons: they can
4797 increase startup overhead; they may be meant for advanced usage only;
4798 they may provide potentially dangerous abilities (such as letting you
4799 destroy or modify history); they might not be ready for prime time; or
4800 they may alter some usual behaviors of stock Mercurial. It is thus up
4801 to the user to activate extensions as needed.
4802 To explicitly disable an extension enabled in a configuration file of
4804 broader scope, prepend its path with !:
4805 [extensions]
4807 # disabling extension bar residing in /path/to/extension/bar.py
4808 bar = !/path/to/extension/bar.py
4809 # ditto, but no path was supplied for extension baz
4810 baz = !
4811 disabled extensions:
4813 acl hooks for controlling repository access
4815 blackbox
4817 log repository events to a blackbox for debugging
4818 bugzilla
4820 hooks for integrating with the Bugzilla bug tracker
4821 censor erase file content at a given revision
4823 churn command to display statistics about repository history
4825 clonebundles
4827 advertise pre-generated bundles to seed clones
4828 closehead
4830 close arbitrary heads without checking them out first
4831 convert
4833 import revisions from foreign VCS repositories into Mercurial
4834 eol automatically manage newlines in repository files
4836 extdiff
4838 command to allow external programs to compare revisions
4839 factotum
4841 http authentication with factotum
4842 fastexport
4844 export repositories as git fast-import stream
4845 githelp
4847 try mapping git commands to Mercurial commands
4848 gpg commands to sign and verify changesets
4850 hgk browse the repository in a graphical way
4852 highlight
4854 syntax highlighting for hgweb (requires Pygments)
4855 histedit
4857 interactive history editing
4858 keyword
4860 expand keywords in tracked files
4861 largefiles
4863 track large binary files
4864 mq manage a stack of patches
4866 notify hooks for sending email push notifications
4868 patchbomb
4870 command to send changesets as (a series of) patch emails
4871 rebase command to move sets of revisions to a different ancestor
4873 relink recreates hardlinks between repository clones
4875 schemes
4877 extend schemes with shortcuts to repository swarms
4878 share share a common history between several working directories
4880 transplant
4882 command to transplant changesets from another branch
4883 win32mbcs
4885 allow the use of MBCS paths with problematic encodings
4886 zeroconf
4888 discover and advertise repositories on the local network
4889
4891 Mercurial supports a functional language for selecting a set of files.
4892 Like other file patterns, this pattern type is indicated by a prefix,
4894 'set:'. The language supports a number of predicates which are joined
4895 by infix operators. Parenthesis can be used for grouping.
4896 Identifiers such as filenames or patterns must be quoted with single or
4898 double quotes if they contain characters outside of
4899 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4900 predicates. This generally applies to file patterns other than globs
4901 and arguments for predicates. Pattern prefixes such as path: may be
4902 specified without quoting.
4903 Special characters can be used in quoted identifiers by escaping them,
4905 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4906 preted, strings can be prefixed with r, e.g. r'...'.
4907 See also hg help patterns.
4909 Operators
4911 There is a single prefix operator:
4912 not x
4914 Files not in x. Short form is ! x.
4916 These are the supported infix operators:
4918 x and y
4920 The intersection of files in x and y. Short form is x & y.
4922 x or y
4924 The union of files in x and y. There are two alternative short
4926 forms: x | y and x + y.
4927 x - y
4929 Files in x but not in y.
4931 Predicates
4933 The following predicates are supported:
4934 added()
4936 File that is added according to hg status.
4938 binary()
4940 File that appears to be binary (contains NUL bytes).
4942 clean()
4944 File that is clean according to hg status.
4946 copied()
4948 File that is recorded as being copied.
4950 deleted()
4952 Alias for missing().
4954 encoding(name)
4956 File can be successfully decoded with the given character encod‐
4958 ing. May not be useful for encodings other than ASCII and UTF-8.
4959 eol(style)
4961 File contains newlines of the given style (dos, unix, mac). Bi‐
4963 nary files are excluded, files with mixed line endings match
4964 multiple styles.
4965 exec()
4967 File that is marked as executable.
4969 grep(regex)
4971 File contains the given regular expression.
4973 hgignore()
4975 File that matches the active .hgignore pattern.
4977 ignored()
4979 File that is ignored according to hg status.
4981 missing()
4983 File that is missing according to hg status.
4985 modified()
4987 File that is modified according to hg status.
4989 portable()
4991 File that has a portable name. (This doesn't include filenames
4993 with case collisions.)
4994 removed()
4996 File that is removed according to hg status.
4998 resolved()
5000 File that is marked resolved according to hg resolve -l.
5002 revs(revs, pattern)
5004 Evaluate set in the specified revisions. If the revset match
5006 multiple revs, this will return file matching pattern in any of
5007 the revision.
5008 size(expression)
5010 File size matches the given expression. Examples:
5012 • size('1k') - files from 1024 to 2047 bytes
5014 • size('< 20k') - files less than 20480 bytes
5016 • size('>= .5MB') - files at least 524288 bytes
5018 • size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
5020 status(base, rev, pattern)
5022 Evaluate predicate using status change between base and rev. Ex‐
5024 amples:
5025 • status(3, 7, added()) - matches files added from "3" to "7"
5027 subrepo([pattern])
5029 Subrepositories whose paths match the given pattern.
5031 symlink()
5033 File that is marked as a symlink.
5035 tracked()
5037 File that is under Mercurial control.
5039 unknown()
5041 File that is unknown according to hg status.
5043 unresolved()
5045 File that is marked unresolved according to hg resolve -l.
5047 Examples
5049 Some sample queries:
5050 • Show status of files that appear to be binary in the working direc‐
5052 tory:
5053 hg status -A "set:binary()"
5055 • Forget files that are in .hgignore but are already tracked:
5057 hg forget "set:hgignore() and not ignored()"
5059 • Find text files that contain a string:
5061 hg files "set:grep(magic) and not binary()"
5063 • Find C files in a non-standard encoding:
5065 hg files "set:**.c and not encoding('UTF-8')"
5067 • Revert copies of large binary files:
5069 hg revert "set:copied() and binary() and size('>1M')"
5071 • Revert files that were added to the working directory:
5073 hg revert "set:revs('wdir()', added())"
5075 • Remove files listed in foo.lst that contain the letter a or b:
5077 hg remove "set: listfile:foo.lst and (**a* or **b*)"
5079
5081 Most Mercurial commands accept various flags.
5082 Flag names
5084 Flags for each command are listed in hg help for that command. Addi‐
5085 tionally, some flags, such as --repository, are global and can be used
5086 with any command - those are seen in hg help -v, and can be specified
5087 before or after the command.
5088 Every flag has at least a long name, such as --repository. Some flags
5090 may also have a short one-letter name, such as the equivalent -R. Using
5091 the short or long name is equivalent and has the same effect. The long
5092 name may be abbreviated to any unambiguous prefix. For example, hg com‐
5093 mit --amend can be abbreviated to hg commit --am.
5094 Flags that have a short name can also be bundled together - for in‐
5096 stance, to specify both --edit (short -e) and --interactive (short -i),
5097 one could use:
5098 hg commit -ei
5100 If any of the bundled flags takes a value (i.e. is not a boolean), it
5102 must be last, followed by the value:
5103 hg commit -im 'Message'
5105 Flag types
5107 Mercurial command-line flags can be strings, numbers, booleans, or
5108 lists of strings.
5109 Specifying flag values
5111 The following syntaxes are allowed, assuming a flag 'flagname' with
5112 short name 'f':
5113 --flagname=foo
5115 --flagname foo
5116 -f foo
5117 -ffoo
5118 This syntax applies to all non-boolean flags (strings, numbers or
5120 lists).
5121 Specifying boolean flags
5123 Boolean flags do not take a value parameter. To specify a boolean, use
5124 the flag name to set it to true, or the same name prefixed with 'no-'
5125 to set it to false:
5126 hg commit --interactive
5128 hg commit --no-interactive
5129 Specifying list flags
5131 List flags take multiple values. To specify them, pass the flag multi‐
5132 ple times:
5133 hg files --include mercurial --include tests
5135 Setting flag defaults
5137 In order to set a default value for a flag in an hgrc file, it is rec‐
5138 ommended to use aliases:
5139 [alias]
5141 commit = commit --interactive
5142 For more information on hgrc files, see hg help config.
5144 Overriding flags on the command line
5146 If the same non-list flag is specified multiple times on the command
5147 line, the latest specification is used:
5148 hg commit -m "Ignored value" -m "Used value"
5150 This includes the use of aliases - e.g., if one has:
5152 [alias]
5154 committemp = commit -m "Ignored value"
5155 then the following command will override that -m:
5157 hg committemp -m "Used value"
5159 Overriding flag defaults
5161 Every flag has a default value, and you may also set your own defaults
5162 in hgrc as described above. Except for list flags, defaults can be
5163 overridden on the command line simply by specifying the flag in that
5164 location.
5165 Hidden flags
5167 Some flags are not shown in a command's help by default - specifically,
5168 those that are deemed to be experimental, deprecated or advanced. To
5169 show all flags, add the --verbose flag for the help command:
5170 hg help --verbose commit
5172
5174 Ancestor
5175 Any changeset that can be reached by an unbroken chain of parent
5176 changesets from a given changeset. More precisely, the ancestors
5177 of a changeset can be defined by two properties: a parent of a
5178 changeset is an ancestor, and a parent of an ancestor is an an‐
5179 cestor. See also: 'Descendant'.
5180 Bookmark
5182 Bookmarks are pointers to certain commits that move when commit‐
5183 ting. They are similar to tags in that it is possible to use
5184 bookmark names in all places where Mercurial expects a changeset
5185 ID, e.g., with hg update. Unlike tags, bookmarks move along when
5186 you make a commit.
5187 Bookmarks can be renamed, copied and deleted. Bookmarks are lo‐
5189 cal, unless they are explicitly pushed or pulled between reposi‐
5190 tories. Pushing and pulling bookmarks allow you to collaborate
5191 with others on a branch without creating a named branch.
5192 Branch (Noun) A child changeset that has been created from a parent
5194 that is not a head. These are known as topological branches, see
5195 'Branch, topological'. If a topological branch is named, it be‐
5196 comes a named branch. If a topological branch is not named, it
5197 becomes an anonymous branch. See 'Branch, anonymous' and
5198 'Branch, named'.
5199 Branches may be created when changes are pulled from or pushed
5201 to a remote repository, since new heads may be created by these
5202 operations. Note that the term branch can also be used infor‐
5203 mally to describe a development process in which certain devel‐
5204 opment is done independently of other development. This is some‐
5205 times done explicitly with a named branch, but it can also be
5206 done locally, using bookmarks or clones and anonymous branches.
5207 Example: "The experimental branch."
5209 (Verb) The action of creating a child changeset which results in
5211 its parent having more than one child.
5212 Example: "I'm going to branch at X."
5214 Branch, anonymous
5216 Every time a new child changeset is created from a parent that
5217 is not a head and the name of the branch is not changed, a new
5218 anonymous branch is created.
5219 Branch, closed
5221 A named branch whose branch heads have all been closed.
5222 Branch, default
5224 The branch assigned to a changeset when no name has previously
5225 been assigned.
5226 Branch head
5228 See 'Head, branch'.
5229 Branch, inactive
5231 If a named branch has no topological heads, it is considered to
5232 be inactive. As an example, a feature branch becomes inactive
5233 when it is merged into the default branch. The hg branches com‐
5234 mand shows inactive branches by default, though they can be hid‐
5235 den with hg branches --active.
5236 NOTE: this concept is deprecated because it is too implicit.
5238 Branches should now be explicitly closed using hg commit
5239 --close-branch when they are no longer needed.
5240 Branch, named
5242 A collection of changesets which have the same branch name. By
5243 default, children of a changeset in a named branch belong to the
5244 same named branch. A child can be explicitly assigned to a dif‐
5245 ferent branch. See hg help branch, hg help branches and hg com‐
5246 mit --close-branch for more information on managing branches.
5247 Named branches can be thought of as a kind of namespace, divid‐
5249 ing the collection of changesets that comprise the repository
5250 into a collection of disjoint subsets. A named branch is not
5251 necessarily a topological branch. If a new named branch is cre‐
5252 ated from the head of another named branch, or the default
5253 branch, but no further changesets are added to that previous
5254 branch, then that previous branch will be a branch in name only.
5255 Branch tip
5257 See 'Tip, branch'.
5258 Branch, topological
5260 Every time a new child changeset is created from a parent that
5261 is not a head, a new topological branch is created. If a topo‐
5262 logical branch is named, it becomes a named branch. If a topo‐
5263 logical branch is not named, it becomes an anonymous branch of
5264 the current, possibly default, branch.
5265 Changelog
5267 A record of the changesets in the order in which they were added
5268 to the repository. This includes details such as changeset id,
5269 author, commit message, date, and list of changed files.
5270 Changeset
5272 A snapshot of the state of the repository used to record a
5273 change.
5274 Changeset, child
5276 The converse of parent changeset: if P is a parent of C, then C
5277 is a child of P. There is no limit to the number of children
5278 that a changeset may have.
5279 Changeset id
5281 A SHA-1 hash that uniquely identifies a changeset. It may be
5282 represented as either a "long" 40 hexadecimal digit string, or a
5283 "short" 12 hexadecimal digit string.
5284 Changeset, merge
5286 A changeset with two parents. This occurs when a merge is com‐
5287 mitted.
5288 Changeset, parent
5290 A revision upon which a child changeset is based. Specifically,
5291 a parent changeset of a changeset C is a changeset whose node
5292 immediately precedes C in the DAG. Changesets have at most two
5293 parents.
5294 Checkout
5296 (Noun) The working directory being updated to a specific revi‐
5297 sion. This use should probably be avoided where possible, as
5298 changeset is much more appropriate than checkout in this con‐
5299 text.
5300 Example: "I'm using checkout X."
5302 (Verb) Updating the working directory to a specific changeset.
5304 See hg help update.
5305 Example: "I'm going to check out changeset X."
5307 Child changeset
5309 See 'Changeset, child'.
5310 Close changeset
5312 See 'Head, closed branch'.
5313 Closed branch
5315 See 'Branch, closed'.
5316 Clone (Noun) An entire or partial copy of a repository. The partial
5318 clone must be in the form of a revision and its ancestors.
5319 Example: "Is your clone up to date?"
5321 (Verb) The process of creating a clone, using hg clone.
5323 Example: "I'm going to clone the repository."
5325 Closed branch head
5327 See 'Head, closed branch'.
5328 Commit (Noun) A synonym for changeset.
5330 Example: "Is the bug fixed in your recent commit?"
5332 (Verb) The act of recording changes to a repository. When files
5334 are committed in a working directory, Mercurial finds the dif‐
5335 ferences between the committed files and their parent changeset,
5336 creating a new changeset in the repository.
5337 Example: "You should commit those changes now."
5339 Cset A common abbreviation of the term changeset.
5341 DAG The repository of changesets of a distributed version control
5343 system (DVCS) can be described as a directed acyclic graph
5344 (DAG), consisting of nodes and edges, where nodes correspond to
5345 changesets and edges imply a parent -> child relation. This
5346 graph can be visualized by graphical tools such as hg log
5347 --graph. In Mercurial, the DAG is limited by the requirement for
5348 children to have at most two parents.
5349 Deprecated
5351 Feature removed from documentation, but not scheduled for re‐
5352 moval.
5353 Default branch
5355 See 'Branch, default'.
5356 Descendant
5358 Any changeset that can be reached by a chain of child changesets
5359 from a given changeset. More precisely, the descendants of a
5360 changeset can be defined by two properties: the child of a
5361 changeset is a descendant, and the child of a descendant is a
5362 descendant. See also: 'Ancestor'.
5363 Diff (Noun) The difference between the contents and attributes of
5365 files in two changesets or a changeset and the current working
5366 directory. The difference is usually represented in a standard
5367 form called a "diff" or "patch". The "git diff" format is used
5368 when the changes include copies, renames, or changes to file at‐
5369 tributes, none of which can be represented/handled by classic
5370 "diff" and "patch".
5371 Example: "Did you see my correction in the diff?"
5373 (Verb) Diffing two changesets is the action of creating a diff
5375 or patch.
5376 Example: "If you diff with changeset X, you will see what I
5378 mean."
5379 Directory, working
5381 The working directory represents the state of the files tracked
5382 by Mercurial, that will be recorded in the next commit. The
5383 working directory initially corresponds to the snapshot at an
5384 existing changeset, known as the parent of the working direc‐
5385 tory. See 'Parent, working directory'. The state may be modified
5386 by changes to the files introduced manually or by a merge. The
5387 repository metadata exists in the .hg directory inside the work‐
5388 ing directory.
5389 Draft Changesets in the draft phase have not been shared with publish‐
5391 ing repositories and may thus be safely changed by history-modi‐
5392 fying extensions. See hg help phases.
5393 Experimental
5395 Feature that may change or be removed at a later date.
5396 Graph See DAG and hg log --graph.
5398 Head The term 'head' may be used to refer to both a branch head or a
5400 repository head, depending on the context. See 'Head, branch'
5401 and 'Head, repository' for specific definitions.
5402 Heads are where development generally takes place and are the
5404 usual targets for update and merge operations.
5405 Head, branch
5407 A changeset with no descendants on the same named branch.
5408 Head, closed branch
5410 A changeset that marks a head as no longer interesting. The
5411 closed head is no longer listed by hg heads. A branch is consid‐
5412 ered closed when all its heads are closed and consequently is
5413 not listed by hg branches.
5414 Closed heads can be re-opened by committing new changeset as the
5416 child of the changeset that marks a head as closed.
5417 Head, repository
5419 A topological head which has not been closed.
5420 Head, topological
5422 A changeset with no children in the repository.
5423 History, immutable
5425 Once committed, changesets cannot be altered. Extensions which
5426 appear to change history actually create new changesets that re‐
5427 place existing ones, and then destroy the old changesets. Doing
5428 so in public repositories can result in old changesets being
5429 reintroduced to the repository.
5430 History, rewriting
5432 The changesets in a repository are immutable. However, exten‐
5433 sions to Mercurial can be used to alter the repository, usually
5434 in such a way as to preserve changeset contents.
5435 Immutable history
5437 See 'History, immutable'.
5438 Merge changeset
5440 See 'Changeset, merge'.
5441 Manifest
5443 Each changeset has a manifest, which is the list of files that
5444 are tracked by the changeset.
5445 Merge Used to bring together divergent branches of work. When you up‐
5447 date to a changeset and then merge another changeset, you bring
5448 the history of the latter changeset into your working directory.
5449 Once conflicts are resolved (and marked), this merge may be com‐
5450 mitted as a merge changeset, bringing two branches together in
5451 the DAG.
5452 Named branch
5454 See 'Branch, named'.
5455 Null changeset
5457 The empty changeset. It is the parent state of newly-initialized
5458 repositories and repositories with no checked out revision. It
5459 is thus the parent of root changesets and the effective ancestor
5460 when merging unrelated changesets. Can be specified by the alias
5461 'null' or by the changeset ID '000000000000'.
5462 Parent See 'Changeset, parent'.
5464 Parent changeset
5466 See 'Changeset, parent'.
5467 Parent, working directory
5469 The working directory parent reflects a virtual revision which
5470 is the child of the changeset (or two changesets with an uncom‐
5471 mitted merge) shown by hg parents. This is changed with hg up‐
5472 date. Other commands to see the working directory parent are hg
5473 summary and hg id. Can be specified by the alias ".".
5474 Patch (Noun) The product of a diff operation.
5476 Example: "I've sent you my patch."
5478 (Verb) The process of using a patch file to transform one
5480 changeset into another.
5481 Example: "You will need to patch that revision."
5483 Phase A per-changeset state tracking how the changeset has been or
5485 should be shared. See hg help phases.
5486 Public Changesets in the public phase have been shared with publishing
5488 repositories and are therefore considered immutable. See hg help
5489 phases.
5490 Pull An operation in which changesets in a remote repository which
5492 are not in the local repository are brought into the local
5493 repository. Note that this operation without special arguments
5494 only updates the repository, it does not update the files in the
5495 working directory. See hg help pull.
5496 Push An operation in which changesets in a local repository which are
5498 not in a remote repository are sent to the remote repository.
5499 Note that this operation only adds changesets which have been
5500 committed locally to the remote repository. Uncommitted changes
5501 are not sent. See hg help push.
5502 Repository
5504 The metadata describing all recorded states of a collection of
5505 files. Each recorded state is represented by a changeset. A
5506 repository is usually (but not always) found in the .hg subdi‐
5507 rectory of a working directory. Any recorded state can be recre‐
5508 ated by "updating" a working directory to a specific changeset.
5509 Repository head
5511 See 'Head, repository'.
5512 Revision
5514 A state of the repository at some point in time. Earlier revi‐
5515 sions can be updated to by using hg update. See also 'Revision
5516 number'; See also 'Changeset'.
5517 Revision number
5519 This integer uniquely identifies a changeset in a specific
5520 repository. It represents the order in which changesets were
5521 added to a repository, starting with revision number 0. Note
5522 that the revision number may be different in each clone of a
5523 repository. To identify changesets uniquely between different
5524 clones, see 'Changeset id'.
5525 Revlog History storage mechanism used by Mercurial. It is a form of
5527 delta encoding, with occasional full revision of data followed
5528 by delta of each successive revision. It includes data and an
5529 index pointing to the data.
5530 Rewriting history
5532 See 'History, rewriting'.
5533 Root A changeset that has only the null changeset as its parent. Most
5535 repositories have only a single root changeset.
5536 Secret Changesets in the secret phase may not be shared via push, pull,
5538 or clone. See hg help phases.
5539 Tag An alternative name given to a changeset. Tags can be used in
5541 all places where Mercurial expects a changeset ID, e.g., with hg
5542 update. The creation of a tag is stored in the history and will
5543 thus automatically be shared with other using push and pull.
5544 Tip The changeset with the highest revision number. It is the
5546 changeset most recently added in a repository.
5547 Tip, branch
5549 The head of a given branch with the highest revision number.
5550 When a branch name is used as a revision identifier, it refers
5551 to the branch tip. See also 'Branch, head'. Note that because
5552 revision numbers may be different in different repository
5553 clones, the branch tip may be different in different cloned
5554 repositories.
5555 Update (Noun) Another synonym of changeset.
5557 Example: "I've pushed an update."
5559 (Verb) This term is usually used to describe updating the state
5561 of the working directory to that of a specific changeset. See hg
5562 help update.
5563 Example: "You should update."
5565 Working directory
5567 See 'Directory, working'.
5568 Working directory parent
5570 See 'Parent, working directory'.
5571
5573 Synopsis
5574 The Mercurial system uses a file called .hgignore in the root directory
5575 of a repository to control its behavior when it searches for files that
5576 it is not currently tracking.
5577 Description
5579 The working directory of a Mercurial repository will often contain
5580 files that should not be tracked by Mercurial. These include backup
5581 files created by editors and build products created by compilers.
5582 These files can be ignored by listing them in a .hgignore file in the
5583 root of the working directory. The .hgignore file must be created manu‐
5584 ally. It is typically put under version control, so that the settings
5585 will propagate to other repositories with push and pull.
5586 An untracked file is ignored if its path relative to the repository
5588 root directory, or any prefix path of that path, is matched against any
5589 pattern in .hgignore.
5590 For example, say we have an untracked file, file.c, at a/b/file.c in‐
5592 side our repository. Mercurial will ignore file.c if any pattern in
5593 .hgignore matches a/b/file.c, a/b or a.
5594 In addition, a Mercurial configuration file can reference a set of
5596 per-user or global ignore files. See the ignore configuration key on
5597 the [ui] section of hg help config for details of how to configure
5598 these files.
5599 To control Mercurial's handling of files that it manages, many commands
5601 support the -I and -X options; see hg help <command> and hg help pat‐
5602 terns for details.
5603 Files that are already tracked are not affected by .hgignore, even if
5605 they appear in .hgignore. An untracked file X can be explicitly added
5606 with hg add X, even if X would be excluded by a pattern in .hgignore.
5607 Syntax
5609 An ignore file is a plain text file consisting of a list of patterns,
5610 with one pattern per line. Empty lines are skipped. The # character is
5611 treated as a comment character, and the \ character is treated as an
5612 escape character.
5613 Mercurial supports several pattern syntaxes. The default syntax used is
5615 Python/Perl-style regular expressions.
5616 To change the syntax used, use a line of the following form:
5618 syntax: NAME
5620 where NAME is one of the following:
5622 regexp
5624 Regular expression, Python/Perl syntax.
5626 glob
5628 Shell-style glob.
5630 rootglob
5632 A variant of glob that is rooted (see below).
5634 The chosen syntax stays in effect when parsing all patterns that fol‐
5636 low, until another syntax is selected.
5637 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
5639 the form *.c will match a file ending in .c in any directory, and a
5640 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
5641 tern, start it with ^. To get the same effect with glob-syntax, you
5642 have to use rootglob.
5643 Subdirectories can have their own .hgignore settings by adding subin‐
5645 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
5646 terns for details on subinclude: and include:.
5647 Note Patterns specified in other than .hgignore are always rooted.
5649 Please see hg help patterns for details.
5650 Example
5652 Here is an example ignore file.
5653 # use glob syntax.
5655 syntax: glob
5656 *.elc
5658 *.pyc
5659 *~
5660 # switch to regexp syntax.
5662 syntax: regexp
5663 ^\.pc/
5664 Debugging
5666 Use the debugignore command to see if and why a file is ignored, or to
5667 see the combined ignore pattern. See hg help debugignore for details.
5668
5670 Mercurial's internal web server, hgweb, can serve either a single
5671 repository, or a tree of repositories. In the second case, repository
5672 paths and global options can be defined using a dedicated configuration
5673 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
5674 This file uses the same syntax as other Mercurial configuration files
5676 but recognizes only the following sections:
5677 • web
5679 • paths
5681 • collections
5683 The web options are thoroughly described in hg help config.
5685 The paths section maps URL paths to paths of repositories in the
5687 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
5688 rial repositories can be published and only according to the configura‐
5689 tion.
5690 The left hand side is the path in the URL. Note that hgweb reserves
5692 subpaths like rev or file, try using different names for nested reposi‐
5693 tories to avoid confusing effects.
5694 The right hand side is the path in the filesystem. If the specified
5696 path ends with * or ** the filesystem will be searched recursively for
5697 repositories below that point. With * it will not recurse into the
5698 repositories it finds (except for .hg/patches). With ** it will also
5699 search inside repository working directories and possibly find sub‐
5700 repositories.
5701 In this example:
5703 [paths]
5705 /projects/a = /srv/tmprepos/a
5706 /projects/b = c:/repos/b
5707 / = /srv/repos/*
5708 /user/bob = /home/bob/repos/**
5709 • The first two entries make two repositories in different directories
5711 appear under the same directory in the web interface
5712 • The third entry will publish every Mercurial repository found in
5714 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
5715 as http://server/quux/
5716 • The fourth entry will publish both http://server/user/bob/quux/ and
5718 http://server/user/bob/quux/testsubrepo/
5719 The collections section is deprecated and has been superseded by paths.
5721 URLs and Common Arguments
5723 URLs under each repository have the form /{command}[/{arguments}] where
5724 {command} represents the name of a command or handler and {arguments}
5725 represents any number of additional URL parameters to that command.
5726 The web server has a default style associated with it. Styles map to a
5728 collection of named templates. Each template is used to render a spe‐
5729 cific piece of data, such as a changeset or diff.
5730 The style for the current request can be overridden two ways. First, if
5732 {command} contains a hyphen (-), the text before the hyphen defines the
5733 style. For example, /atom-log will render the log command handler with
5734 the atom style. The second way to set the style is with the style query
5735 string argument. For example, /log?style=atom. The hyphenated URL pa‐
5736 rameter is preferred.
5737 Not all templates are available for all styles. Attempting to use a
5739 style that doesn't have all templates defined may result in an error
5740 rendering the page.
5741 Many commands take a {revision} URL parameter. This defines the change‐
5743 set to operate on. This is commonly specified as the short, 12 digit
5744 hexadecimal abbreviation for the full 40 character unique revision
5745 identifier. However, any value described by hg help revisions typically
5746 works.
5747 Commands and URLs
5749 The following web commands and their URLs are available:
5750 /annotate/{revision}/{path}
5752 Show changeset information for each line in a file.
5753 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
5755 string arguments have the same meaning as their [annotate] config
5756 equivalents. It uses the hgrc boolean parsing logic to interpret the
5757 value. e.g. 0 and false are false and 1 and true are true. If not de‐
5758 fined, the server default settings are used.
5759 The fileannotate template is rendered.
5761 /archive/{revision}.{format}[/{path}]
5763 Obtain an archive of repository content.
5764 The content and type of the archive is defined by a URL path parameter.
5766 format is the file extension of the archive type to be generated. e.g.
5767 zip or tar.bz2. Not all archive types may be allowed by your server
5768 configuration.
5769 The optional path URL parameter controls content to include in the ar‐
5771 chive. If omitted, every file in the specified revision is present in
5772 the archive. If included, only the specified file or contents of the
5773 specified directory will be included in the archive.
5774 No template is used for this handler. Raw, binary content is generated.
5776 /bookmarks
5778 Show information about bookmarks.
5779 No arguments are accepted.
5781 The bookmarks template is rendered.
5783 /branches
5785 Show information about branches.
5786 All known branches are contained in the output, even closed branches.
5788 No arguments are accepted.
5790 The branches template is rendered.
5792 /changelog[/{revision}]
5794 Show information about multiple changesets.
5795 If the optional revision URL argument is absent, information about all
5797 changesets starting at tip will be rendered. If the revision argument
5798 is present, changesets will be shown starting from the specified revi‐
5799 sion.
5800 If revision is absent, the rev query string argument may be defined.
5802 This will perform a search for changesets.
5803 The argument for rev can be a single revision, a revision set, or a
5805 literal keyword to search for in changeset data (equivalent to hg log
5806 -k).
5807 The revcount query string argument defines the maximum numbers of
5809 changesets to render.
5810 For non-searches, the changelog template will be rendered.
5812 /changeset[/{revision}]
5814 Show information about a single changeset.
5815 A URL path argument is the changeset identifier to show. See hg help
5817 revisions for possible values. If not defined, the tip changeset will
5818 be shown.
5819 The changeset template is rendered. Contents of the changesettag,
5821 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5822 lated to diffs may all be used to produce the output.
5823 /comparison/{revision}/{path}
5825 Show a comparison between the old and new versions of a file from
5826 changes made on a particular revision.
5827 This is similar to the diff handler. However, this form features a
5829 split or side-by-side diff rather than a unified diff.
5830 The context query string argument can be used to control the lines of
5832 context in the diff.
5833 The filecomparison template is rendered.
5835 /diff/{revision}/{path}
5837 Show how a file changed in a particular commit.
5838 The filediff template is rendered.
5840 This handler is registered under both the /diff and /filediff paths.
5842 /diff is used in modern code.
5843 /file/{revision}[/{path}]
5845 Show information about a directory or file in the repository.
5846 Info about the path given as a URL parameter will be rendered.
5848 If path is a directory, information about the entries in that directory
5850 will be rendered. This form is equivalent to the manifest handler.
5851 If path is a file, information about that file will be shown via the
5853 filerevision template.
5854 If path is not defined, information about the root directory will be
5856 rendered.
5857 /diff/{revision}/{path}
5859 Show how a file changed in a particular commit.
5860 The filediff template is rendered.
5862 This handler is registered under both the /diff and /filediff paths.
5864 /diff is used in modern code.
5865 /filelog/{revision}/{path}
5867 Show information about the history of a file in the repository.
5868 The revcount query string argument can be defined to control the maxi‐
5870 mum number of entries to show.
5871 The filelog template will be rendered.
5873 /graph[/{revision}]
5875 Show information about the graphical topology of the repository.
5876 Information rendered by this handler can be used to create visual rep‐
5878 resentations of repository topology.
5879 The revision URL parameter controls the starting changeset. If it's ab‐
5881 sent, the default is tip.
5882 The revcount query string argument can define the number of changesets
5884 to show information for.
5885 The graphtop query string argument can specify the starting changeset
5887 for producing jsdata variable that is used for rendering graph in Java‐
5888 Script. By default it has the same value as revision.
5889 This handler will render the graph template.
5891 /help[/{topic}]
5893 Render help documentation.
5894 This web command is roughly equivalent to hg help. If a topic is de‐
5896 fined, that help topic will be rendered. If not, an index of available
5897 help topics will be rendered.
5898 The help template will be rendered when requesting help for a topic.
5900 helptopics will be rendered for the index of help topics.
5901 /log[/{revision}[/{path}]]
5903 Show repository or file history.
5904 For URLs of the form /log/{revision}, a list of changesets starting at
5906 the specified changeset identifier is shown. If {revision} is not de‐
5907 fined, the default is tip. This form is equivalent to the changelog
5908 handler.
5909 For URLs of the form /log/{revision}/{file}, the history for a specific
5911 file will be shown. This form is equivalent to the filelog handler.
5912 /manifest[/{revision}[/{path}]]
5914 Show information about a directory.
5915 If the URL path arguments are omitted, information about the root di‐
5917 rectory for the tip changeset will be shown.
5918 Because this handler can only show information for directories, it is
5920 recommended to use the file handler instead, as it can handle both di‐
5921 rectories and files.
5922 The manifest template will be rendered for this handler.
5924 /changeset[/{revision}]
5926 Show information about a single changeset.
5927 A URL path argument is the changeset identifier to show. See hg help
5929 revisions for possible values. If not defined, the tip changeset will
5930 be shown.
5931 The changeset template is rendered. Contents of the changesettag,
5933 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5934 lated to diffs may all be used to produce the output.
5935 /shortlog
5937 Show basic information about a set of changesets.
5938 This accepts the same parameters as the changelog handler. The only
5940 difference is the shortlog template will be rendered instead of the
5941 changelog template.
5942 /summary
5944 Show a summary of repository state.
5945 Information about the latest changesets, bookmarks, tags, and branches
5947 is captured by this handler.
5948 The summary template is rendered.
5950 /tags
5952 Show information about tags.
5953 No arguments are accepted.
5955 The tags template is rendered.
5957
5959 To access a subtopic, use "hg help internals.{subtopic-name}"
5960 bid-merge
5962 Bid Merge Algorithm
5963 bundle2
5965 Bundle2
5966 bundles
5968 Bundles
5969 cbor CBOR
5971 censor Censor
5973 changegroups
5975 Changegroups
5976 config Config Registrar
5978 dirstate-v2
5980 dirstate-v2 file format
5981 extensions
5983 Extension API
5984 mergestate
5986 Mergestate
5987 requirements
5989 Repository Requirements
5990 revlogs
5992 Revision Logs
5993 wireprotocol
5995 Wire Protocol
5996 wireprotocolrpc
5998 Wire Protocol RPC
5999 wireprotocolv2
6001 Wire Protocol Version 2
6002
6004 To merge files Mercurial uses merge tools.
6005 A merge tool combines two different versions of a file into a merged
6007 file. Merge tools are given the two files and the greatest common an‐
6008 cestor of the two file versions, so they can determine the changes made
6009 on both branches.
6010 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
6012 out and in several extensions.
6013 Usually, the merge tool tries to automatically reconcile the files by
6015 combining all non-overlapping changes that occurred separately in the
6016 two different evolutions of the same initial base file. Furthermore,
6017 some interactive merge programs make it easier to manually resolve con‐
6018 flicting merges, either in a graphical way, or by inserting some con‐
6019 flict markers. Mercurial does not include any interactive merge pro‐
6020 grams but relies on external tools for that.
6021 Available merge tools
6023 External merge tools and their properties are configured in the
6024 merge-tools configuration section - see hgrc(5) - but they can often
6025 just be named by their executable.
6026 A merge tool is generally usable if its executable can be found on the
6028 system and if it can handle the merge. The executable is found if it is
6029 an absolute or relative executable path or the name of an application
6030 in the executable search path. The tool is assumed to be able to handle
6031 the merge if it can handle symlinks if the file is a symlink, if it can
6032 handle binary files if the file is binary, and if a GUI is available if
6033 the tool requires a GUI.
6034 There are some internal merge tools which can be used. The internal
6036 merge tools are:
6037 :dump
6039 Creates three versions of the files to merge, containing the
6041 contents of local, other and base. These files can then be used
6042 to perform a merge manually. If the file to be merged is named
6043 a.txt, these files will accordingly be named a.txt.local,
6044 a.txt.other and a.txt.base and they will be placed in the same
6045 directory as a.txt.
6046 This implies premerge. Therefore, files aren't dumped, if pre‐
6048 merge runs successfully. Use :forcedump to forcibly write files
6049 out.
6050 (actual capabilities: binary, symlink)
6052 :fail
6054 Rather than attempting to merge files that were modified on both
6056 branches, it marks them as unresolved. The resolve command must
6057 be used to resolve these conflicts.
6058 (actual capabilities: binary, symlink)
6060 :forcedump
6062 Creates three versions of the files as same as :dump, but omits
6064 premerge.
6065 (actual capabilities: binary, symlink)
6067 :local
6069 Uses the local p1() version of files as the merged version.
6071 (actual capabilities: binary, symlink)
6073 :merge
6075 Uses the internal non-interactive simple merge algorithm for
6077 merging files. It will fail if there are any conflicts and leave
6078 markers in the partially merged file. Markers will have two sec‐
6079 tions, one for each side of merge.
6080 :merge-local
6082 Like :merge, but resolve all conflicts non-interactively in fa‐
6084 vor of the local p1() changes.
6085 :merge-other
6087 Like :merge, but resolve all conflicts non-interactively in fa‐
6089 vor of the other p2() changes.
6090 :merge3
6092 Uses the internal non-interactive simple merge algorithm for
6094 merging files. It will fail if there are any conflicts and leave
6095 markers in the partially merged file. Marker will have three
6096 sections, one from each side of the merge and one for the base
6097 content.
6098 :mergediff
6100 Uses the internal non-interactive simple merge algorithm for
6102 merging files. It will fail if there are any conflicts and leave
6103 markers in the partially merged file. The marker will have two
6104 sections, one with the content from one side of the merge, and
6105 one with a diff from the base content to the content on the
6106 other side. (experimental)
6107 :other
6109 Uses the other p2() version of files as the merged version.
6111 (actual capabilities: binary, symlink)
6113 :prompt
6115 Asks the user which of the local p1() or the other p2() version
6117 to keep as the merged version.
6118 (actual capabilities: binary, symlink)
6120 :tagmerge
6122 Uses the internal tag merge algorithm (experimental).
6124 :union
6126 Uses the internal non-interactive simple merge algorithm for
6128 merging files. It will use both local and other sides for con‐
6129 flict regions by adding local on top of other. No markers are
6130 inserted.
6131 :union-other-first
6133 Like :union, but add other on top of local.
6135 Internal tools are always available and do not require a GUI but will
6137 by default not handle symlinks or binary files. See next section for
6138 detail about "actual capabilities" described above.
6139 Choosing a merge tool
6141 Mercurial uses these rules when deciding which merge tool to use:
6142 1. If a tool has been specified with the --tool option to merge or re‐
6144 solve, it is used. If it is the name of a tool in the merge-tools
6145 configuration, its configuration is used. Otherwise the specified
6146 tool must be executable by the shell.
6147 2. If the HGMERGE environment variable is present, its value is used
6149 and must be executable by the shell.
6150 3. If the filename of the file to be merged matches any of the patterns
6152 in the merge-patterns configuration section, the first usable merge
6153 tool corresponding to a matching pattern is used.
6154 4. If ui.merge is set it will be considered next. If the value is not
6156 the name of a configured tool, the specified value is used and must
6157 be executable by the shell. Otherwise the named tool is used if it
6158 is usable.
6159 5. If any usable merge tools are present in the merge-tools configura‐
6161 tion section, the one with the highest priority is used.
6162 6. If a program named hgmerge can be found on the system, it is used -
6164 but it will by default not be used for symlinks and binary files.
6165 7. If the file to be merged is not binary and is not a symlink, then
6167 internal :merge is used.
6168 8. Otherwise, :prompt is used.
6170 For historical reason, Mercurial treats merge tools as below while ex‐
6172 amining rules above.
6173 ┌───────────┬────────────────┬────────┬─────────┐
6175 │step │ specified via │ binary │ symlink │
6176 ├───────────┼────────────────┼────────┼─────────┤
6177 │ │ --tool │ o/o │ o/o │
6178 │ 1. │ │ │ │
6179 ├───────────┼────────────────┼────────┼─────────┤
6180 │ │ HGMERGE │ o/o │ o/o │
6181 │ 2. │ │ │ │
6182 └───────────┴────────────────┴────────┴─────────┘
6183 │ │ merge-patterns │ o/o(*) │ x/?(*) │
6185 │ 3. │ │ │ │
6186 ├───────────┼────────────────┼────────┼─────────┤
6187 │ │ ui.merge │ x/?(*) │ x/?(*) │
6188 │ 4. │ │ │ │
6189 └───────────┴────────────────┴────────┴─────────┘
6190 Each capability column indicates Mercurial behavior for internal/exter‐
6192 nal merge tools at examining each rule.
6193 • "o": "assume that a tool has capability"
6195 • "x": "assume that a tool does not have capability"
6197 • "?": "check actual capability of a tool"
6199 If merge.strict-capability-check configuration is true, Mercurial
6201 checks capabilities of merge tools strictly in (*) cases above (= each
6202 capability column becomes "?/?"). It is false by default for backward
6203 compatibility.
6204 Note After selecting a merge program, Mercurial will by default at‐
6206 tempt to merge the files using a simple merge algorithm first.
6207 Only if it doesn't succeed because of conflicting changes will
6208 Mercurial actually execute the merge program. Whether to use the
6209 simple merge algorithm first can be controlled by the premerge
6210 setting of the merge tool. Premerge is enabled by default unless
6211 the file is binary or a symlink.
6212 See the merge-tools and ui sections of hgrc(5) for details on the con‐
6214 figuration of merge tools.
6215
6217 Some Mercurial commands can produce a lot of output, and Mercurial will
6218 attempt to use a pager to make those commands more pleasant.
6219 To set the pager that should be used, set the application variable:
6221 [pager]
6223 pager = less -FRX
6224 If no pager is set in the user or repository configuration, Mercurial
6226 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
6227 from the default or system configuration is used. If none of these are
6228 set, a default pager will be used, typically less on Unix and more on
6229 Windows.
6230 On Windows, more is not color aware, so using it effectively disables
6232 color. MSYS and Cygwin shells provide less as a pager, which can be
6233 configured to support ANSI color codes. See hg help con‐
6234 fig.color.pagermode to configure the color mode when invoking a pager.
6235 You can disable the pager for certain commands by adding them to the
6237 pager.ignore list:
6238 [pager]
6240 ignore = version, help, update
6241 To ignore global commands like hg version or hg help, you have to spec‐
6243 ify them in your user configuration file.
6244 To control whether the pager is used at all for an individual command,
6246 you can use --pager=<value>:
6247 • use as needed: auto.
6249 • require the pager: yes or on.
6251 • suppress the pager: no or off (any unrecognized value will also
6253 work).
6254 To globally turn off all attempts to use a pager, set:
6256 [ui]
6258 paginate = never
6259 which will prevent the pager from running.
6261
6263 Mercurial accepts several notations for identifying one or more files
6264 at a time.
6265 By default, Mercurial treats filenames verbatim without pattern match‐
6267 ing, relative to the current working directory. Note that your system
6268 shell might perform pattern matching of its own before passing file‐
6269 names into Mercurial.
6270 Alternate pattern notations must be specified explicitly.
6272 Note Patterns specified in .hgignore are not rooted. Please see hg
6274 help hgignore for details.
6275 To use a plain path name without any pattern matching, start it with
6277 path:. These path names must completely match starting at the current
6278 repository root, and when the path points to a directory, it is matched
6279 recursively. To match all files in a directory non-recursively (not in‐
6280 cluding any files in subdirectories), rootfilesin: can be used, speci‐
6281 fying an absolute path (relative to the repository root). To match a
6282 single file exactly, relative to the repository root, you can use
6283 filepath:.
6284 To use an extended glob, start a name with glob:. Globs are rooted at
6286 the current directory; a glob such as *.c will only match files in the
6287 current directory ending with .c. rootglob: can be used instead of
6288 glob: for a glob that is rooted at the root of the repository.
6289 The supported glob syntax extensions are ** to match any string across
6291 path separators and {a,b} to mean "a or b".
6292 To use a Perl/Python regular expression, start a name with re:. Regexp
6294 pattern matching is anchored at the root of the repository.
6295 To read name patterns from a file, use listfile: or listfile0:. The
6297 latter expects null delimited patterns while the former expects line
6298 feeds. Each string read from the file is itself treated as a file pat‐
6299 tern.
6300 To read a set of patterns from a file, use include: or subinclude:.
6302 include: will use all the patterns from the given file and treat them
6303 as if they had been passed in manually. subinclude: will only apply
6304 the patterns against files that are under the subinclude file's direc‐
6305 tory. See hg help hgignore for details on the format of these files.
6306 All patterns, except for glob: specified in command line (not for -I or
6308 -X options), can match also against directories: files under matched
6309 directories are treated as matched. For -I and -X options, glob: will
6310 match directories recursively.
6311 Plain examples:
6313 path:foo/bar a name bar in a directory named foo in the root
6315 of the repository
6316 path:some/path a file or directory named "some/path"
6317 filepath:some/path/to/a/file exactly a single file named
6318 "some/path/to/a/file", relative to the root
6319 of the repository
6320 rootfilesin:foo/bar the files in a directory called foo/bar, but
6321 not any files in its subdirectories and not
6322 a file bar in directory foo
6323 Glob examples:
6325 glob:*.c any name ending in ".c" in the current directory
6327 *.c any name ending in ".c" in the current directory
6328 **.c any name ending in ".c" in any subdirectory of the
6329 current directory including itself.
6330 foo/* any file in directory foo
6331 foo/** any file in directory foo plus all its subdirectories,
6332 recursively
6333 foo/*.c any name ending in ".c" in the directory foo
6334 foo/**.c any name ending in ".c" in any subdirectory of foo
6335 including itself.
6336 rootglob:*.c any name ending in ".c" in the root of the repository
6337 Regexp examples:
6339 re:.*\.c$ any name ending in ".c", anywhere in the repository
6341 File examples:
6343 listfile:list.txt read list from list.txt with one file pattern per line
6345 listfile0:list.txt read list from list.txt with null byte delimiters
6346 See also hg help filesets.
6348 Include examples:
6350 include:path/to/mypatternfile reads patterns to be applied to all paths
6352 subinclude:path/to/subignorefile reads patterns specifically for paths in the
6353 subdirectory
6354
6356 What are phases?
6357 Phases are a system for tracking which changesets have been or should
6358 be shared. This helps prevent common mistakes when modifying history
6359 (for instance, with the mq or rebase extensions).
6360 Each changeset in a repository is in one of the following phases:
6362 • public : changeset is visible on a public server
6364 • draft : changeset is not yet published
6366 • secret : changeset should not be pushed, pulled, or cloned
6368 These phases are ordered (public < draft < secret) and no changeset can
6370 be in a lower phase than its ancestors. For instance, if a changeset is
6371 public, all its ancestors are also public. Lastly, changeset phases
6372 should only be changed towards the public phase.
6373 How are phases managed?
6375 For the most part, phases should work transparently. By default, a
6376 changeset is created in the draft phase and is moved into the public
6377 phase when it is pushed to another repository.
6378 Once changesets become public, extensions like mq and rebase will
6380 refuse to operate on them to prevent creating duplicate changesets.
6381 Phases can also be manually manipulated with the hg phase command if
6382 needed. See hg help -v phase for examples.
6383 To make your commits secret by default, put this in your configuration
6385 file:
6386 [phases]
6388 new-commit = secret
6389 Phases and servers
6391 Normally, all servers are publishing by default. This means:
6392 - all draft changesets that are pulled or cloned appear in phase
6394 public on the client
6395 - all draft changesets that are pushed appear as public on both
6397 client and server
6398 - secret changesets are neither pushed, pulled, or cloned
6400 Note Pulling a draft changeset from a publishing server does not mark
6402 it as public on the server side due to the read-only nature of
6403 pull.
6404 Sometimes it may be desirable to push and pull changesets in the draft
6406 phase to share unfinished work. This can be done by setting a reposi‐
6407 tory to disable publishing in its configuration file:
6408 [phases]
6410 publish = False
6411 See hg help config for more information on configuration files.
6413 Note Servers running older versions of Mercurial are treated as pub‐
6415 lishing.
6416 Note Changesets in secret phase are not exchanged with the server.
6418 This applies to their content: file names, file contents, and
6419 changeset metadata. For technical reasons, the identifier (e.g.
6420 d825e4025e39) of the secret changeset may be communicated to the
6421 server.
6422 Examples
6424 • list changesets in draft or secret phase:
6425 hg log -r "not public()"
6427 • change all secret changesets to draft:
6429 hg phase --draft "secret()"
6431 • forcibly move the current changeset and descendants from public to
6433 draft:
6434 hg phase --force --draft .
6436 • show a list of changeset revisions and each corresponding phase:
6438 hg log --template "{rev} {phase}\n"
6440 • resynchronize draft changesets relative to a remote repository:
6442 hg phase -fd "outgoing(URL)"
6444 See hg help phase for more information on manually manipulating phases.
6446
6448 Mercurial supports several ways to specify revisions.
6449 Specifying single revisions
6451 A plain integer is treated as a revision number. Negative integers are
6452 treated as sequential offsets from the tip, with -1 denoting the tip,
6453 -2 denoting the revision prior to the tip, and so forth.
6454 A 40-digit hexadecimal string is treated as a unique revision identi‐
6456 fier. A hexadecimal string less than 40 characters long is treated as
6457 a unique revision identifier and is referred to as a short-form identi‐
6458 fier. A short-form identifier is only valid if it is the prefix of ex‐
6459 actly one full-length identifier.
6460 Any other string is treated as a bookmark, tag, or branch name. A book‐
6462 mark is a movable pointer to a revision. A tag is a permanent name as‐
6463 sociated with a revision. A branch name denotes the tipmost open branch
6464 head of that branch - or if they are all closed, the tipmost closed
6465 head of the branch. Bookmark, tag, and branch names must not contain
6466 the ":" character.
6467 The reserved name "tip" always identifies the most recent revision.
6469 The reserved name "null" indicates the null revision. This is the revi‐
6471 sion of an empty repository, and the parent of revision 0.
6472 The reserved name "." indicates the working directory parent. If no
6474 working directory is checked out, it is equivalent to null. If an un‐
6475 committed merge is in progress, "." is the revision of the first par‐
6476 ent.
6477 Finally, commands that expect a single revision (like hg update) also
6479 accept revsets (see below for details). When given a revset, they use
6480 the last revision of the revset. A few commands accept two single revi‐
6481 sions (like hg diff). When given a revset, they use the first and the
6482 last revisions of the revset.
6483 Specifying multiple revisions
6485 Mercurial supports a functional language for selecting a set of revi‐
6486 sions. Expressions in this language are called revsets.
6487 The language supports a number of predicates which are joined by infix
6489 operators. Parenthesis can be used for grouping.
6490 Identifiers such as branch names may need quoting with single or double
6492 quotes if they contain characters like - or if they match one of the
6493 predefined predicates.
6494 Special characters can be used in quoted identifiers by escaping them,
6496 e.g., \n is interpreted as a newline. To prevent them from being inter‐
6497 preted, strings can be prefixed with r, e.g. r'...'.
6498 Operators
6500 There is a single prefix operator:
6501 not x
6503 Changesets not in x. Short form is ! x.
6505 These are the supported infix operators:
6507 x::y
6509 A DAG range, meaning all changesets that are descendants of x
6511 and ancestors of y, including x and y themselves. If the first
6512 endpoint is left out, this is equivalent to ancestors(y), if the
6513 second is left out it is equivalent to descendants(x).
6514 An alternative syntax is x..y.
6516 x:y
6518 All changesets with revision numbers between x and y, both in‐
6520 clusive. Either endpoint can be left out, they default to 0 and
6521 tip.
6522 x and y
6524 The intersection of changesets in x and y. Short form is x & y.
6526 x or y
6528 The union of changesets in x and y. There are two alternative
6530 short forms: x | y and x + y.
6531 x - y
6533 Changesets in x but not in y.
6535 x % y
6537 Changesets that are ancestors of x but not ancestors of y (i.e.
6539 ::x - ::y). This is shorthand notation for only(x, y) (see be‐
6540 low). The second argument is optional and, if left out, is
6541 equivalent to only(x).
6542 x^n
6544 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
6546 1, the first parent of each changeset in x; for n == 2, the sec‐
6547 ond parent of changeset in x.
6548 x~n
6550 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
6552 the nth unambiguous descendent of x.
6553 x ## y
6555 Concatenate strings and identifiers into one string.
6557 All other prefix, infix and postfix operators have lower prior‐
6559 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
6560 a2)~2.
6561 For example:
6563 [revsetalias]
6565 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
6566 issue(1234) is equivalent to grep(r'\bissue[
6568 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
6569 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
6570 There is a single postfix operator:
6572 x^
6574 Equivalent to x^1, the first parent of each changeset in x.
6576 Patterns
6578 Where noted, predicates that perform string matching can accept a pat‐
6579 tern string. The pattern may be either a literal, or a regular expres‐
6580 sion. If the pattern starts with re:, the remainder of the pattern is
6581 treated as a regular expression. Otherwise, it is treated as a literal.
6582 To match a pattern that actually starts with re:, use the prefix lit‐
6583 eral:.
6584 Matching is case-sensitive, unless otherwise noted. To perform a case-
6586 insensitive match on a case-sensitive predicate, use a regular expres‐
6587 sion, prefixed with (?i).
6588 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
6590 "Release", etc.
6591 Predicates
6593 The following predicates are supported:
6594 adds(pattern)
6596 Changesets that add a file matching pattern.
6598 The pattern without explicit kind like glob: is expected to be
6600 relative to the current directory and match against a file or a
6601 directory.
6602 all()
6604 All changesets, the same as 0:tip.
6606 ancestor(*changeset)
6608 A greatest common ancestor of the changesets.
6610 Accepts 0 or more changesets. Will return empty list when
6612 passed no args. Greatest common ancestor of a single changeset
6613 is that changeset.
6614 ancestors(set[, depth])
6616 Changesets that are ancestors of changesets in set, including
6618 the given changesets themselves.
6619 If depth is specified, the result only includes changesets up to
6621 the specified generation.
6622 author(string)
6624 Alias for user(string).
6626 bisect(string)
6628 Changesets marked in the specified bisect status:
6630 • good, bad, skip: csets explicitly marked as good/bad/skip
6632 • goods, bads : csets topologically good/bad
6634 • range : csets taking part in the bisection
6636 • pruned : csets that are goods, bads or skipped
6638 • untested : csets whose fate is yet unknown
6640 • ignored : csets ignored due to DAG topology
6642 • current : the cset currently being bisected
6644 bookmark([name])
6646 The named bookmark or all bookmarks.
6648 Pattern matching is supported for name. See hg help revi‐
6650 sions.patterns.
6651 branch(string or set)
6653 All changesets belonging to the given branch or the branches of
6655 the given changesets.
6656 Pattern matching is supported for string. See hg help revi‐
6658 sions.patterns.
6659 branchpoint()
6661 Changesets with more than one child.
6663 bundle()
6665 Changesets in the bundle.
6667 Bundle must be specified by the -R option.
6669 children(set)
6671 Child changesets of changesets in set.
6673 closed()
6675 Changeset is closed.
6677 commonancestors(set)
6679 Changesets that are ancestors of every changeset in set.
6681 conflictlocal()
6683 The local side of the merge, if currently in an unresolved
6685 merge.
6686 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6688 'hg graft'.
6689 conflictother()
6691 The other side of the merge, if currently in an unresolved
6693 merge.
6694 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6696 'hg graft'.
6697 contains(pattern)
6699 The revision's manifest contains a file matching pattern (but
6701 might not modify it). See hg help patterns for information about
6702 file patterns.
6703 The pattern without explicit kind like glob: is expected to be
6705 relative to the current directory and match against a file ex‐
6706 actly for efficiency.
6707 converted([id])
6709 Changesets converted from the given identifier in the old repos‐
6711 itory if present, or all converted changesets if no identifier
6712 is specified.
6713 date(interval)
6715 Changesets within the interval, see hg help dates.
6717 desc(string)
6719 Search commit message for string. The match is case-insensitive.
6721 Pattern matching is supported for string. See hg help revi‐
6723 sions.patterns.
6724 descendants(set[, depth])
6726 Changesets which are descendants of changesets in set, including
6728 the given changesets themselves.
6729 If depth is specified, the result only includes changesets up to
6731 the specified generation.
6732 destination([set])
6734 Changesets that were created by a graft, transplant or rebase
6736 operation, with the given revisions specified as the source.
6737 Omitting the optional set is the same as passing all().
6738 diffcontains(pattern)
6740 Search revision differences for when the pattern was added or
6742 removed.
6743 The pattern may be a substring literal or a regular expression.
6745 See hg help revisions.patterns.
6746 draft()
6748 Changeset in draft phase.
6750 expectsize(set[, size])
6752 Return the given revset if size matches the revset size. Abort
6754 if the revset doesn't expect given size. size can either be an
6755 integer range or an integer.
6756 For example, expectsize(0:1, 3:5) will abort as revset size is 2
6758 and 2 is not between 3 and 5 inclusive.
6759 extra(label, [value])
6761 Changesets with the given label in the extra metadata, with the
6763 given optional value.
6764 Pattern matching is supported for value. See hg help revi‐
6766 sions.patterns.
6767 file(pattern)
6769 Changesets affecting files matched by pattern.
6771 For a faster but less accurate result, consider using filelog()
6773 instead.
6774 This predicate uses glob: as the default kind of pattern.
6776 filelog(pattern)
6778 Changesets connected to the specified filelog.
6780 For performance reasons, visits only revisions mentioned in the
6782 file-level filelog, rather than filtering through all changesets
6783 (much faster, but doesn't include deletes or duplicate changes).
6784 For a slower, more accurate result, use file().
6785 The pattern without explicit kind like glob: is expected to be
6787 relative to the current directory and match against a file ex‐
6788 actly for efficiency.
6789 first(set, [n])
6791 An alias for limit().
6793 follow([file[, startrev]])
6795 An alias for ::. (ancestors of the working directory's first
6797 parent). If file pattern is specified, the histories of files
6798 matching given pattern in the revision given by startrev are
6799 followed, including copies.
6800 followlines(file, fromline:toline[, startrev=., descend=False])
6802 Changesets modifying file in line range ('fromline', 'toline').
6804 Line range corresponds to 'file' content at 'startrev' and
6806 should hence be consistent with file size. If startrev is not
6807 specified, working directory's parent is used.
6808 By default, ancestors of 'startrev' are returned. If 'descend'
6810 is True, descendants of 'startrev' are returned though renames
6811 are (currently) not followed in this direction.
6812 grep(regex)
6814 Like keyword(string) but accepts a regex. Use grep(r'...') to
6816 ensure special escape characters are handled correctly. Unlike
6817 keyword(string), the match is case-sensitive.
6818 head()
6820 Changeset is a named branch head.
6822 heads(set)
6824 Members of set with no children in set.
6826 hidden()
6828 Hidden changesets.
6830 id(string)
6832 Revision non-ambiguously specified by the given hex string pre‐
6834 fix.
6835 keyword(string)
6837 Search commit message, user name, and names of changed files for
6839 string. The match is case-insensitive.
6840 For a regular expression or case sensitive search of these
6842 fields, use grep(regex).
6843 last(set, [n])
6845 Last n members of set, defaulting to 1.
6847 limit(set[, n[, offset]])
6849 First n members of set, defaulting to 1, starting from offset.
6851 matching(revision [, field])
6853 Changesets in which a given set of fields match the set of
6855 fields in the selected revision or set.
6856 To match more than one field pass the list of fields to match
6858 separated by spaces (e.g. author description).
6859 Valid fields are most regular revision fields and some special
6861 fields.
6862 Regular revision fields are description, author, branch, date,
6864 files, phase, parents, substate, user and diff. Note that au‐
6865 thor and user are synonyms. diff refers to the contents of the
6866 revision. Two revisions matching their diff will also match
6867 their files.
6868 Special fields are summary and metadata: summary matches the
6870 first line of the description. metadata is equivalent to match‐
6871 ing description user date (i.e. it matches the main metadata
6872 fields).
6873 metadata is the default field which is used when no fields are
6875 specified. You can match more than one field at a time.
6876 max(set)
6878 Changeset with highest revision number in set.
6880 merge()
6882 Changeset is a merge changeset.
6884 min(set)
6886 Changeset with lowest revision number in set.
6888 modifies(pattern)
6890 Changesets modifying files matched by pattern.
6892 The pattern without explicit kind like glob: is expected to be
6894 relative to the current directory and match against a file or a
6895 directory.
6896 named(namespace)
6898 The changesets in a given namespace.
6900 Pattern matching is supported for namespace. See hg help revi‐
6902 sions.patterns.
6903 nodefromfile(path)
6905 Read a list of nodes from the file at path.
6907 This applies id(LINE) to each line of the file.
6909 This is useful when the amount of nodes you need to specify gets
6911 too large for the command line.
6912 none()
6914 No changesets.
6916 only(set, [set])
6918 Changesets that are ancestors of the first set that are not an‐
6920 cestors of any other head in the repo. If a second set is speci‐
6921 fied, the result is ancestors of the first set that are not an‐
6922 cestors of the second set (i.e. ::<set1> - ::<set2>).
6923 origin([set])
6925 Changesets that were specified as a source for the grafts,
6927 transplants or rebases that created the given revisions. Omit‐
6928 ting the optional set is the same as passing all(). If a
6929 changeset created by these operations is itself specified as a
6930 source for one of these operations, only the source changeset
6931 for the first operation is selected.
6932 outgoing([path])
6934 Changesets not found in the specified destination repository, or
6936 the default push location.
6937 If the location resolve to multiple repositories, the union of
6939 all outgoing changeset will be used.
6940 p1([set])
6942 First parent of changesets in set, or the working directory.
6944 p2([set])
6946 Second parent of changesets in set, or the working directory.
6948 parents([set])
6950 The set of all parents for all changesets in set, or the working
6952 directory.
6953 present(set)
6955 An empty set, if any revision in set isn't found; otherwise, all
6957 revisions in set.
6958 If any of specified revisions is not present in the local repos‐
6960 itory, the query is normally aborted. But this predicate allows
6961 the query to continue even in such cases.
6962 public()
6964 Changeset in public phase.
6966 remote([id [,path]])
6968 Local revision that corresponds to the given identifier in a re‐
6970 mote repository, if present. Here, the '.' identifier is a syn‐
6971 onym for the current local branch.
6972 removes(pattern)
6974 Changesets which remove files matching pattern.
6976 The pattern without explicit kind like glob: is expected to be
6978 relative to the current directory and match against a file or a
6979 directory.
6980 rev(number)
6982 Revision with the given numeric identifier.
6984 reverse(set)
6986 Reverse order of set.
6988 revset(set)
6990 Strictly interpret the content as a revset.
6992 The content of this special predicate will be strictly inter‐
6994 preted as a revset. For example, revset(id(0)) will be inter‐
6995 preted as "id(0)" without possible ambiguity with a "id(0)"
6996 bookmark or tag.
6997 roots(set)
6999 Changesets in set with no parent changeset in set.
7001 secret()
7003 Changeset in secret phase.
7005 sort(set[, [-]key... [, ...]])
7007 Sort set by keys. The default sort order is ascending, specify a
7009 key as -key to sort in descending order.
7010 The keys can be:
7012 • rev for the revision number,
7014 • branch for the branch name,
7016 • desc for the commit message (description),
7018 • user for user name (author can be used as an alias),
7020 • date for the commit date
7022 • topo for a reverse topographical sort
7024 • node the nodeid of the revision
7026 • random randomly shuffle revisions
7028 The topo sort order cannot be combined with other sort keys.
7030 This sort takes one optional argument, topo.firstbranch, which
7031 takes a revset that specifies what topographical branches to
7032 prioritize in the sort.
7033 The random sort takes one optional random.seed argument to con‐
7035 trol the pseudo-randomness of the result.
7036 subrepo([pattern])
7038 Changesets that add, modify or remove the given subrepo. If no
7040 subrepo pattern is named, any subrepo changes are returned.
7041 tag([name])
7043 The specified tag by name, or all tagged revisions if no name is
7045 given.
7046 Pattern matching is supported for name. See hg help revi‐
7048 sions.patterns.
7049 user(string)
7051 User name contains string. The match is case-insensitive.
7053 Pattern matching is supported for string. See hg help revi‐
7055 sions.patterns.
7056 Aliases
7058 New predicates (known as "aliases") can be defined, using any combina‐
7059 tion of existing predicates or other aliases. An alias definition looks
7060 like:
7061 <alias> = <definition>
7063 in the revsetalias section of a Mercurial configuration file. Arguments
7065 of the form a1, a2, etc. are substituted from the alias into the defi‐
7066 nition.
7067 For example,
7069 [revsetalias]
7071 h = heads()
7072 d(s) = sort(s, date)
7073 rs(s, k) = reverse(sort(s, k))
7074 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
7076 equivalent to reverse(sort(0:tip, author)).
7077 Equivalents
7079 Command line equivalents for hg log:
7080 -f -> ::.
7082 -d x -> date(x)
7083 -k x -> keyword(x)
7084 -m -> merge()
7085 -u x -> user(x)
7086 -b x -> branch(x)
7087 -P x -> !::x
7088 -l x -> limit(expr, x)
7089 Examples
7091 Some sample queries:
7092 • Changesets on the default branch:
7094 hg log -r "branch(default)"
7096 • Changesets on the default branch since tag 1.5 (excluding merges):
7098 hg log -r "branch(default) and 1.5:: and not merge()"
7100 • Open branch heads:
7102 hg log -r "head() and not closed()"
7104 • Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
7106 hgext/*:
7107 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
7109 • Changesets committed in May 2008, sorted by user:
7111 hg log -r "sort(date('May 2008'), user)"
7113 • Changesets mentioning "bug" or "issue" that are not in a tagged re‐
7115 lease:
7116 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
7118 • Update to the commit that bookmark @ is pointing to, without activat‐
7120 ing the bookmark (this works because the last revision of the revset
7121 is used):
7122 hg update :@
7124 • Show diff between tags 1.3 and 1.5 (this works because the first and
7126 the last revisions of the revset are used):
7127 hg diff -r 1.3::1.5
7129
7131 Mercurial can be augmented with Rust extensions for speeding up certain
7132 operations.
7133 Compatibility
7135 Though the Rust extensions are only tested by the project under Linux,
7136 users of MacOS, FreeBSD and other UNIX-likes have been using the Rust
7137 extensions. Your mileage may vary, but by all means do give us feedback
7138 or signal your interest for better support.
7139 No Rust extensions are available for Windows at this time.
7141 Features
7143 The following operations are sped up when using Rust:
7144 • discovery of differences between repositories (pull/push)
7146 • nodemap (see hg help config.format.use-persistent-nodemap)
7148 • all commands using the dirstate (status, commit, diff, add, up‐
7150 date, etc.)
7151 • dirstate-v2 (see hg help config.format.use-dirstate-v2)
7153 • iteration over ancestors in a graph
7155 More features are in the works, and improvements on the above listed
7157 are still in progress. For more experimental work see the "rhg" sec‐
7158 tion.
7159 Checking for Rust
7161 You may already have the Rust extensions depending on how you install
7162 Mercurial:
7163 $ hg debuginstall | grep -i rust
7165 checking Rust extensions (installed)
7166 checking module policy (rust+c-allow)
7167 If those lines don't even exist, you're using an old version of hg
7169 which does not have any Rust extensions yet.
7170 Installing
7172 You will need cargo to be in your $PATH. See the "MSRV" section for
7173 which version to use.
7174 Using pip
7176 Users of pip can install the Rust extensions with the following com‐
7177 mand:
7178 $ pip install mercurial --global-option --rust --no-use-pep517
7180 --no-use-pep517 is here to tell pip to preserve backwards compatibility
7182 with the legacy setup.py system. Mercurial has not yet migrated its
7183 complex setup to the new system, so we still need this to add compiled
7184 extensions.
7185 This might take a couple of minutes because you're compiling every‐
7187 thing.
7188 See the "Checking for Rust" section to see if the install succeeded.
7190 From your distribution
7192 Some distributions are shipping Mercurial with Rust extensions enabled
7193 and pre-compiled (meaning you won't have to install cargo), or allow
7194 you to specify an install flag. Check with your specific distribution
7195 for how to do that, or ask their team to add support for hg+Rust!
7196 From source
7198 Please refer to the rust/README.rst file in the Mercurial repository
7199 for instructions on how to install from source.
7200 MSRV
7202 The minimum supported Rust version is defined in rust/clippy.toml. The
7203 project's policy is to keep it at or below the version from Debian
7204 testing, to make the distributions' job easier.
7205 rhg
7207 There exists an experimental pure-Rust version of Mercurial called rhg
7208 with a fallback mechanism for unsupported invocations. It allows for
7209 much faster execution of certain commands while adding no discernable
7210 overhead for the rest.
7211 The only way of trying it out is by building it from source. Please re‐
7213 fer to rust/README.rst in the Mercurial repository.
7214 See hg help config.rhg for configuration options.
7216 Contributing
7218 If you would like to help the Rust endeavor, please refer to
7219 rust/README.rst in the Mercurial repository.
7220
7222 It is common for machines (as opposed to humans) to consume Mercurial.
7223 This help topic describes some of the considerations for interfacing
7224 machines with Mercurial.
7225 Choosing an Interface
7227 Machines have a choice of several methods to interface with Mercurial.
7228 These include:
7229 • Executing the hg process
7231 • Querying a HTTP server
7233 • Calling out to a command server
7235 Executing hg processes is very similar to how humans interact with Mer‐
7237 curial in the shell. It should already be familiar to you.
7238 hg serve can be used to start a server. By default, this will start a
7240 "hgweb" HTTP server. This HTTP server has support for machine-readable
7241 output, such as JSON. For more, see hg help hgweb.
7242 hg serve can also start a "command server." Clients can connect to this
7244 server and issue Mercurial commands over a special protocol. For more
7245 details on the command server, including links to client libraries, see
7246 https://www.mercurial-scm.org/wiki/CommandServer.
7247 hg serve based interfaces (the hgweb and command servers) have the ad‐
7249 vantage over simple hg process invocations in that they are likely more
7250 efficient. This is because there is significant overhead to spawn new
7251 Python processes.
7252 Tip If you need to invoke several hg processes in short order and/or
7254 performance is important to you, use of a server-based interface
7255 is highly recommended.
7256 Environment Variables
7258 As documented in hg help environment, various environment variables in‐
7259 fluence the operation of Mercurial. The following are particularly rel‐
7260 evant for machines consuming Mercurial:
7261 HGPLAIN
7263 If not set, Mercurial's output could be influenced by configura‐
7264 tion settings that impact its encoding, verbose mode, localiza‐
7265 tion, etc.
7266 It is highly recommended for machines to set this variable when
7268 invoking hg processes.
7269 HGENCODING
7271 If not set, the locale used by Mercurial will be detected from
7272 the environment. If the determined locale does not support dis‐
7273 play of certain characters, Mercurial may render these character
7274 sequences incorrectly (often by using "?" as a placeholder for
7275 invalid characters in the current locale).
7276 Explicitly setting this environment variable is a good practice
7278 to guarantee consistent results. "utf-8" is a good choice on
7279 UNIX-like environments.
7280 HGRCPATH
7282 If not set, Mercurial will inherit config options from config
7283 files using the process described in hg help config. This in‐
7284 cludes inheriting user or system-wide config files.
7285 When utmost control over the Mercurial configuration is desired,
7287 the value of HGRCPATH can be set to an explicit file with known
7288 good configs. In rare cases, the value can be set to an empty
7289 file or the null device (often /dev/null) to bypass loading of
7290 any user or system config files. Note that these approaches can
7291 have unintended consequences, as the user and system config
7292 files often define things like the username and extensions that
7293 may be required to interface with a repository.
7294 HGRCSKIPREPO
7296 When set, the .hg/hgrc from repositories are not read.
7297 Note that not reading the repository's configuration can have
7299 unintended consequences, as the repository config files can de‐
7300 fine things like extensions that are required for access to the
7301 repository.
7302 Command-line Flags
7304 Mercurial's default command-line parser is designed for humans, and is
7305 not robust against malicious input. For instance, you can start a de‐
7306 bugger by passing --debugger as an option value:
7307 $ REV=--debugger sh -c 'hg log -r "$REV"'
7309 This happens because several command-line flags need to be scanned
7311 without using a concrete command table, which may be modified while
7312 loading repository settings and extensions.
7313 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
7315 setting HGPLAIN=+strictflags. When this feature is enabled, all early
7316 options (e.g. -R/--repository, --cwd, --config) must be specified first
7317 amongst the other global options, and cannot be injected to an arbi‐
7318 trary location:
7319 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
7321 In earlier Mercurial versions where +strictflags isn't available, you
7323 can mitigate the issue by concatenating an option value with its flag:
7324 $ hg log -r"$REV" --keyword="$KEYWORD"
7326 Consuming Command Output
7328 It is common for machines to need to parse the output of Mercurial com‐
7329 mands for relevant data. This section describes the various techniques
7330 for doing so.
7331 Parsing Raw Command Output
7333 Likely the simplest and most effective solution for consuming command
7334 output is to simply invoke hg commands as you would as a user and parse
7335 their output.
7336 The output of many commands can easily be parsed with tools like grep,
7338 sed, and awk.
7339 A potential downside with parsing command output is that the output of
7341 commands can change when Mercurial is upgraded. While Mercurial does
7342 generally strive for strong backwards compatibility, command output
7343 does occasionally change. Having tests for your automated interactions
7344 with hg commands is generally recommended, but is even more important
7345 when raw command output parsing is involved.
7346 Using Templates to Control Output
7348 Many hg commands support templatized output via the -T/--template argu‐
7349 ment. For more, see hg help templates.
7350 Templates are useful for explicitly controlling output so that you get
7352 exactly the data you want formatted how you want it. For example, log
7353 -T {node}\n can be used to print a newline delimited list of changeset
7354 nodes instead of a human-tailored output containing authors, dates, de‐
7355 scriptions, etc.
7356 Tip If parsing raw command output is too complicated, consider using
7358 templates to make your life easier.
7359 The -T/--template argument allows specifying pre-defined styles. Mer‐
7361 curial ships with the machine-readable styles cbor, json, and xml,
7362 which provide CBOR, JSON, and XML output, respectively. These are use‐
7363 ful for producing output that is machine readable as-is.
7364 (Mercurial 5.0 is required for CBOR style.)
7366 Important
7368 The json and xml styles are considered experimental. While they
7369 may be attractive to use for easily obtaining machine-readable
7370 output, their behavior may change in subsequent versions.
7371 These styles may also exhibit unexpected results when dealing
7373 with certain encodings. Mercurial treats things like filenames
7374 as a series of bytes and normalizing certain byte sequences to
7375 JSON or XML with certain encoding settings can lead to sur‐
7376 prises.
7377 Command Server Output
7379 If using the command server to interact with Mercurial, you are likely
7380 using an existing library/API that abstracts implementation details of
7381 the command server. If so, this interface layer may perform parsing for
7382 you, saving you the work of implementing it yourself.
7383 Output Verbosity
7385 Commands often have varying output verbosity, even when machine read‐
7386 able styles are being used (e.g. -T json). Adding -v/--verbose and
7387 --debug to the command's arguments can increase the amount of data ex‐
7388 posed by Mercurial.
7389 An alternate way to get the data you need is by explicitly specifying a
7391 template.
7392 Other Topics
7394 revsets
7395 Revisions sets is a functional query language for selecting a
7396 set of revisions. Think of it as SQL for Mercurial repositories.
7397 Revsets are useful for querying repositories for specific data.
7398 See hg help revsets for more.
7400 share extension
7402 The share extension provides functionality for sharing reposi‐
7403 tory data across several working copies. It can even automati‐
7404 cally "pool" storage for logically related repositories when
7405 cloning.
7406 Configuring the share extension can lead to significant resource
7408 utilization reduction, particularly around disk space and the
7409 network. This is especially true for continuous integration (CI)
7410 environments.
7411 See hg help -e share for more.
7413
7415 Subrepositories let you nest external repositories or projects into a
7416 parent Mercurial repository, and make commands operate on them as a
7417 group.
7418 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
7420 tories.
7421 Subrepositories are made of three components:
7423 1. Nested repository checkouts. They can appear anywhere in the parent
7425 working directory.
7426 2. Nested repository references. They are defined in .hgsub, which
7428 should be placed in the root of working directory, and tell where
7429 the subrepository checkouts come from. Mercurial subrepositories are
7430 referenced like:
7431 path/to/nested = https://example.com/nested/repo/path
7433 Git and Subversion subrepos are also supported:
7435 path/to/nested = [git]git://example.com/nested/repo/path
7437 path/to/nested = [svn]https://example.com/nested/trunk/path
7438 where path/to/nested is the checkout location relatively to the par‐
7440 ent Mercurial root, and https://example.com/nested/repo/path is the
7441 source repository path. The source can also reference a filesystem
7442 path.
7443 Note that .hgsub does not exist by default in Mercurial reposito‐
7445 ries, you have to create and add it to the parent repository before
7446 using subrepositories.
7447 3. Nested repository states. They are defined in .hgsubstate, which is
7449 placed in the root of working directory, and capture whatever infor‐
7450 mation is required to restore the subrepositories to the state they
7451 were committed in a parent repository changeset. Mercurial automati‐
7452 cally record the nested repositories states when committing in the
7453 parent repository.
7454 Note
7456 The .hgsubstate file should not be edited manually.
7457 Adding a Subrepository
7459 If .hgsub does not exist, create it and add it to the parent reposi‐
7460 tory. Clone or checkout the external projects where you want it to live
7461 in the parent repository. Edit .hgsub and add the subrepository entry
7462 as described above. At this point, the subrepository is tracked and the
7463 next commit will record its state in .hgsubstate and bind it to the
7464 committed changeset.
7465 Synchronizing a Subrepository
7467 Subrepos do not automatically track the latest changeset of their
7468 sources. Instead, they are updated to the changeset that corresponds
7469 with the changeset checked out in the top-level changeset. This is so
7470 developers always get a consistent set of compatible code and libraries
7471 when they update.
7472 Thus, updating subrepos is a manual process. Simply check out target
7474 subrepo at the desired revision, test in the top-level repo, then com‐
7475 mit in the parent repository to record the new combination.
7476 Deleting a Subrepository
7478 To remove a subrepository from the parent repository, delete its refer‐
7479 ence from .hgsub, then remove its files.
7480 Interaction with Mercurial Commands
7482 add add does not recurse in subrepos unless -S/--subrepos is speci‐
7483 fied. However, if you specify the full path of a file in a sub‐
7484 repo, it will be added even without -S/--subrepos specified.
7485 Subversion subrepositories are currently silently ignored.
7486 addremove
7488 addremove does not recurse into subrepos unless -S/--subrepos is
7489 specified. However, if you specify the full path of a directory
7490 in a subrepo, addremove will be performed on it even without
7491 -S/--subrepos being specified. Git and Subversion subreposito‐
7492 ries will print a warning and continue.
7493 archive
7495 archive does not recurse in subrepositories unless -S/--subrepos
7496 is specified.
7497 cat Git subrepositories only support exact file matches. Subversion
7499 subrepositories are currently ignored.
7500 commit commit creates a consistent snapshot of the state of the entire
7502 project and its subrepositories. If any subrepositories have
7503 been modified, Mercurial will abort. Mercurial can be made to
7504 instead commit all modified subrepositories by specifying
7505 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
7506 ration file (see hg help config). After there are no longer any
7507 modified subrepositories, it records their state and finally
7508 commits it in the parent repository. The --addremove option
7509 also honors the -S/--subrepos option. However, Git and Subver‐
7510 sion subrepositories will print a warning and abort.
7511 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
7513 fied. However, if you specify the full path of a file or direc‐
7514 tory in a subrepo, it will be diffed even without -S/--subrepos
7515 being specified. Subversion subrepositories are currently
7516 silently ignored.
7517 files files does not recurse into subrepos unless -S/--subrepos is
7519 specified. However, if you specify the full path of a file or
7520 directory in a subrepo, it will be displayed even without
7521 -S/--subrepos being specified. Git and Subversion subreposito‐
7522 ries are currently silently ignored.
7523 forget forget currently only handles exact file matches in subrepos.
7525 Git and Subversion subrepositories are currently silently ig‐
7526 nored.
7527 incoming
7529 incoming does not recurse in subrepos unless -S/--subrepos is
7530 specified. Git and Subversion subrepositories are currently
7531 silently ignored.
7532 outgoing
7534 outgoing does not recurse in subrepos unless -S/--subrepos is
7535 specified. Git and Subversion subrepositories are currently
7536 silently ignored.
7537 pull pull is not recursive since it is not clear what to pull prior
7539 to running hg update. Listing and retrieving all subrepositories
7540 changes referenced by the parent repository pulled changesets is
7541 expensive at best, impossible in the Subversion case.
7542 push Mercurial will automatically push all subrepositories first when
7544 the parent repository is being pushed. This ensures new sub‐
7545 repository changes are available when referenced by top-level
7546 repositories. Push is a no-op for Subversion subrepositories.
7547 serve serve does not recurse into subrepositories unless -S/--subrepos
7549 is specified. Git and Subversion subrepositories are currently
7550 silently ignored.
7551 status status does not recurse into subrepositories unless -S/--subre‐
7553 pos is specified. Subrepository changes are displayed as regular
7554 Mercurial changes on the subrepository elements. Subversion sub‐
7555 repositories are currently silently ignored.
7556 remove remove does not recurse into subrepositories unless -S/--subre‐
7558 pos is specified. However, if you specify a file or directory
7559 path in a subrepo, it will be removed even without -S/--subre‐
7560 pos. Git and Subversion subrepositories are currently silently
7561 ignored.
7562 update update restores the subrepos in the state they were originally
7564 committed in target changeset. If the recorded changeset is not
7565 available in the current subrepository, Mercurial will pull it
7566 in first before updating. This means that updating can require
7567 network access when using subrepositories.
7568 Remapping Subrepositories Sources
7570 A subrepository source location may change during a project life, in‐
7571 validating references stored in the parent repository history. To fix
7572 this, rewriting rules can be defined in parent repository hgrc file or
7573 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
7574 more details.
7575
7577 Mercurial allows you to customize output of commands through templates.
7578 You can either pass in a template or select an existing template-style
7579 from the command line, via the --template option.
7580 You can customize output for any "log-like" command: log, outgoing, in‐
7582 coming, tip, parents, and heads.
7583 Some built-in styles are packaged with Mercurial. These can be listed
7585 with hg log --template list. Example usage:
7586 $ hg log -r1.0::1.1 --template changelog
7588 A template is a piece of text, with markup to invoke variable expan‐
7590 sion:
7591 $ hg log -r1 --template "{node}\n"
7593 b56ce7b07c52de7d5fd79fb89701ea538af65746
7594 Keywords
7596 Strings in curly braces are called keywords. The availability of key‐
7597 words depends on the exact context of the templater. These keywords are
7598 usually available for templating a log-like command:
7599 _fast_rank
7601 the rank of a changeset if cached
7602 The rank of a revision is the size of the sub-graph it defines
7604 as a head. Equivalently, the rank of a revision r is the size
7605 of the set ancestors(r), r included.
7606 activebookmark
7608 String. The active bookmark, if it is associated with the
7609 changeset.
7610 author Alias for {user}
7612 bisect String. The changeset bisection status.
7614 bookmarks
7616 List of strings. Any bookmarks associated with the changeset.
7617 Also sets 'active', the name of the active bookmark.
7618 branch String. The name of the branch on which the changeset was com‐
7620 mitted.
7621 changessincelatesttag
7623 Integer. All ancestors not in the latest tag.
7624 children
7626 List of strings. The children of the changeset.
7627 date Date information. The date when the changeset was committed.
7629 desc String. The text of the changeset description.
7631 diffstat
7633 String. Statistics of changes with the following format: "modi‐
7634 fied files: +added/-removed lines"
7635 extras List of dicts with key, value entries of the 'extras' field of
7637 this changeset.
7638 file_adds
7640 List of strings. Files added by this changeset.
7641 file_copies
7643 List of strings. Files copied in this changeset with their
7644 sources.
7645 file_copies_switch
7647 List of strings. Like "file_copies" but displayed only if the
7648 --copied switch is set.
7649 file_dels
7651 List of strings. Files removed by this changeset.
7652 file_mods
7654 List of strings. Files modified by this changeset.
7655 files List of strings. All files modified, added, or removed by this
7657 changeset.
7658 graphnode
7660 String. The character representing the changeset node in an
7661 ASCII revision graph.
7662 graphwidth
7664 Integer. The width of the graph drawn by 'log --graph' or zero.
7665 index Integer. The current iteration of the loop. (0 indexed)
7667 latesttag
7669 List of strings. The global tags on the most recent globally
7670 tagged ancestor of this changeset. If no such tags exist, the
7671 list consists of the single string "null".
7672 latesttagdistance
7674 Integer. Longest path to the latest tag.
7675 namespaces
7677 Dict of lists. Names attached to this changeset per namespace.
7678 negrev Integer. The repository-local changeset negative revision num‐
7680 ber, which counts in the opposite direction.
7681 node String. The changeset identification hash, as a 40 hexadecimal
7683 digit string.
7684 onelinesummary
7686 String. A one-line summary for the ctx (not including trailing
7687 newline). The default template be overridden in command-tem‐
7688 plates.oneline-summary.
7689 p1 Changeset. The changeset's first parent. {p1.rev} for the revi‐
7691 sion number, and {p1.node} for the identification hash.
7692 p2 Changeset. The changeset's second parent. {p2.rev} for the revi‐
7694 sion number, and {p2.node} for the identification hash.
7695 parents
7697 List of strings. The parents of the changeset in "rev:node" for‐
7698 mat. If the changeset has only one "natural" parent (the prede‐
7699 cessor revision) nothing is shown.
7700 peerurls
7702 A dictionary of repository locations defined in the [paths] sec‐
7703 tion of your configuration file.
7704 phase String. The changeset phase name.
7706 reporoot
7708 String. The root directory of the current repository.
7709 rev Integer. The repository-local changeset revision number.
7711 subrepos
7713 List of strings. Updated subrepositories in the changeset.
7714 tags List of strings. Any tags associated with the changeset.
7716 termwidth
7718 Integer. The width of the current terminal.
7719 user String. The unmodified author of the changeset.
7721 verbosity
7723 String. The current output verbosity in 'debug', 'quiet', 'ver‐
7724 bose', or ''.
7725 The "date" keyword does not produce human-readable output. If you want
7727 to use a date in your output, you can use a filter to process it. Fil‐
7728 ters are functions which return a string based on the input variable.
7729 Be sure to use the stringify filter first when you're applying a
7730 string-input filter to a list-like input variable. You can also use a
7731 chain of filters to get the desired output:
7732 $ hg tip --template "{date|isodate}\n"
7734 2008-08-21 18:22 +0000
7735 Filters
7737 List of filters:
7738 addbreaks
7740 Any text. Add an XHTML "<br />" tag before the end of every line
7741 except the last.
7742 age Date. Returns a human-readable date/time difference between the
7744 given date/time and the current date/time.
7745 basename
7747 Any text. Treats the text as a path, and returns the last compo‐
7748 nent of the path after splitting by the path separator. For ex‐
7749 ample, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
7750 cbor Any object. Serializes the object to CBOR bytes.
7752 commondir
7754 List of text. Treats each list item as file name with / as path
7755 separator and returns the longest common directory prefix shared
7756 by all list items. Returns the empty string if no common prefix
7757 exists.
7758 The list items are not normalized, i.e. "foo/../bar" is handled
7760 as file "bar" in the directory "foo/..". Leading slashes are ig‐
7761 nored.
7762 For example, ["foo/bar/baz", "foo/baz/bar"] becomes "foo" and
7764 ["foo/bar", "baz"] becomes "".
7765 count List or text. Returns the length as an integer.
7767 dirname
7769 Any text. Treats the text as a path, and strips the last compo‐
7770 nent of the path after splitting by the path separator.
7771 domain Any text. Finds the first string that looks like an email ad‐
7773 dress, and extracts just the domain component. Example: User
7774 <user@example.com> becomes example.com.
7775 email Any text. Extracts the first string that looks like an email ad‐
7777 dress. Example: User <user@example.com> becomes user@exam‐
7778 ple.com.
7779 emailuser
7781 Any text. Returns the user portion of an email address.
7782 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
7784 ">" with XML entities, and filters out NUL characters.
7785 fill68 Any text. Wraps the text to fit in 68 columns.
7787 fill76 Any text. Wraps the text to fit in 76 columns.
7789 firstline
7791 Any text. Returns the first line of text.
7792 hex Any text. Convert a binary Mercurial node identifier into its
7794 long hexadecimal representation.
7795 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
7797 (Unix timestamp, timezone offset).
7798 isodate
7800 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
7801 +0200".
7802 isodatesec
7804 Date. Returns the date in ISO 8601 format, including seconds:
7805 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
7806 json Any object. Serializes the object to a JSON formatted text.
7808 lower Any text. Converts the text to lowercase.
7810 nonempty
7812 Any text. Returns '(none)' if the string is empty.
7813 obfuscate
7815 Any text. Returns the input text rendered as a sequence of XML
7816 entities.
7817 person Any text. Returns the name before an email address, interpreting
7819 it as per RFC 5322.
7820 reverse
7822 List. Reverses the order of list items.
7823 revescape
7825 Any text. Escapes all "special" characters, except @. Forward
7826 slashes are escaped twice to prevent web servers from prema‐
7827 turely unescaping them. For example, "@foo bar/baz" becomes
7828 "@foo%20bar%252Fbaz".
7829 rfc3339date
7831 Date. Returns a date using the Internet date format specified in
7832 RFC 3339: "2009-08-18T13:00:13+02:00".
7833 rfc822date
7835 Date. Returns a date using the same format used in email head‐
7836 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
7837 short Changeset hash. Returns the short form of a changeset hash, i.e.
7839 a 12 hexadecimal digit string.
7840 shortbisect
7842 Any text. Treats label as a bisection status, and returns a sin‐
7843 gle-character representing the status (G: good, B: bad, S:
7844 skipped, U: untested, I: ignored). Returns single space if text
7845 is not a valid bisection status.
7846 shortdate
7848 Date. Returns a date like "2006-09-18".
7849 slashpath
7851 Any text. Replaces the native path separator with slash.
7852 splitlines
7854 Any text. Split text into a list of lines.
7855 stringify
7857 Any type. Turns the value into text by converting values into
7858 text and concatenating them.
7859 stripdir
7861 Treat the text as path and strip a directory level, if possible.
7862 For example, "foo" and "foo/bar" becomes "foo".
7863 tabindent
7865 Any text. Returns the text, with every non-empty line except the
7866 first starting with a tab character.
7867 upper Any text. Converts the text to uppercase.
7869 urlescape
7871 Any text. Escapes all "special" characters. For example, "foo
7872 bar" becomes "foo%20bar".
7873 user Any text. Returns a short representation of a user name or email
7875 address.
7876 utf8 Any text. Converts from the local character encoding to UTF-8.
7878 Note that a filter is nothing more than a function call, i.e.
7880 expr|filter is equivalent to filter(expr).
7881 Functions
7883 In addition to filters, there are some basic built-in functions:
7884 config(section, name[, default])
7886 Returns the requested hgrc config option as a string.
7887 configbool(section, name[, default])
7889 Returns the requested hgrc config option as a boolean.
7890 configint(section, name[, default])
7892 Returns the requested hgrc config option as an integer.
7893 date(date[, fmt])
7895 Format a date. The format string uses the Python strftime for‐
7896 mat. The default is a Unix date format, including the timezone:
7897 "Mon Sep 04 15:13:13 2006 0700".
7898 dict([[key=]value...])
7900 Construct a dict from key-value pairs. A key may be omitted if a
7901 value expression can provide an unambiguous name.
7902 diff([includepattern [, excludepattern]])
7904 Show a diff, optionally specifying files to include or exclude.
7905 files(pattern)
7907 All files of the current changeset matching the pattern. See hg
7908 help patterns.
7909 fill(text[, width[, initialident[, hangindent]]])
7911 Fill many paragraphs with optional indentation. See the "fill"
7912 filter.
7913 filter(iterable[, expr])
7915 Remove empty elements from a list or a dict. If expr specified,
7916 it's applied to each element to test emptiness.
7917 get(dict, key)
7919 Get an attribute/key from an object. Some keywords are complex
7920 types. This function allows you to obtain the value of an attri‐
7921 bute on these types.
7922 if(expr, then[, else])
7924 Conditionally execute based on the result of an expression.
7925 ifcontains(needle, haystack, then[, else])
7927 Conditionally execute based on whether the item "needle" is in
7928 "haystack".
7929 ifeq(expr1, expr2, then[, else])
7931 Conditionally execute based on whether 2 items are equivalent.
7932 indent(text, indentchars[, firstline])
7934 Indents all non-empty lines with the characters given in the in‐
7935 dentchars string. An optional third parameter will override the
7936 indent for the first line only if present.
7937 join(list, sep)
7939 Join items in a list with a delimiter.
7940 label(label, expr)
7942 Apply a label to generated content. Content with a label applied
7943 can result in additional post-processing, such as automatic col‐
7944 orization.
7945 latesttag([pattern])
7947 The global tags matching the given pattern on the most recent
7948 globally tagged ancestor of this changeset. If no such tags ex‐
7949 ist, the "{tag}" template resolves to the string "null". See hg
7950 help revisions.patterns for the pattern syntax.
7951 localdate(date[, tz])
7953 Converts a date to the specified timezone. The default is local
7954 date.
7955 mailmap(author)
7957 Return the author, updated according to the value set in the
7958 .mailmap file
7959 max(iterable)
7961 Return the max of an iterable
7962 min(iterable)
7964 Return the min of an iterable
7965 mod(a, b)
7967 Calculate a mod b such that a / b + a mod b == a
7968 pad(text, width[, fillchar=' '[, left=False[, truncate=False]]])
7970 Pad text with a fill character.
7971 relpath(path)
7973 Convert a repository-absolute path into a filesystem path rela‐
7974 tive to the current working directory.
7975 revset(query[, formatargs...])
7977 Execute a revision set query. See hg help revset.
7978 rstdoc(text, style)
7980 Format reStructuredText.
7981 search(pattern, text)
7983 Look for the first text matching the regular expression pattern.
7984 Groups are accessible as {1}, {2}, ... in %-mapped template.
7985 separate(sep, args...)
7987 Add a separator between non-empty arguments.
7988 shortest(node, minlength=4)
7990 Obtain the shortest representation of a node.
7991 startswith(pattern, text)
7993 Returns the value from the "text" argument if it begins with the
7994 content from the "pattern" argument.
7995 strip(text[, chars])
7997 Strip characters from a string. By default, strips all leading
7998 and trailing whitespace.
7999 sub(pattern, replacement, expression)
8001 Perform text substitution using regular expressions.
8002 subsetparents(rev, revset)
8004 Look up parents of the rev in the sub graph given by the revset.
8005 word(number, text[, separator])
8007 Return the nth word from a string.
8008 Operators
8010 We provide a limited set of infix arithmetic operations on integers:
8011 + for addition
8013 - for subtraction
8014 * for multiplication
8015 / for floor division (division rounded to integer nearest -infinity)
8016 Division fulfills the law x = x / y + mod(x, y).
8018 Also, for any expression that returns a list, there is a list operator:
8020 expr % "{template}"
8022 As seen in the above example, {template} is interpreted as a template.
8024 To prevent it from being interpreted, you can use an escape character
8025 \{ or a raw string prefix, r'...'.
8026 The dot operator can be used as a shorthand for accessing a sub item:
8028 • expr.member is roughly equivalent to expr % '{member}' if expr re‐
8030 turns a non-list/dict. The returned value is not stringified.
8031 • dict.key is identical to get(dict, 'key').
8033 Aliases
8035 New keywords and functions can be defined in the templatealias section
8036 of a Mercurial configuration file:
8037 <alias> = <definition>
8039 Arguments of the form a1, a2, etc. are substituted from the alias into
8041 the definition.
8042 For example,
8044 [templatealias]
8046 r = rev
8047 rn = "{r}:{node|short}"
8048 leftpad(s, w) = pad(s, w, ' ', True)
8049 defines two symbol aliases, r and rn, and a function alias leftpad().
8051 It's also possible to specify complete template strings, using the tem‐
8053 plates section. The syntax used is the general template string syntax.
8054 For example,
8056 [templates]
8058 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
8059 defines a template, nodedate, which can be called like:
8061 $ hg log -r . -Tnodedate
8063 A template defined in templates section can also be referenced from an‐
8065 other template:
8066 $ hg log -r . -T "{rev} {nodedate}"
8068 but be aware that the keywords cannot be overridden by templates. For
8070 example, a template defined as templates.rev cannot be referenced as
8071 {rev}.
8072 A template defined in templates section may have sub templates which
8074 are inserted before/after/between items:
8075 [templates]
8077 myjson = ' {dict(rev, node|short)|json}'
8078 myjson:docheader = '\{\n'
8079 myjson:docfooter = '\n}\n'
8080 myjson:separator = ',\n'
8081 Examples
8083 Some sample command line templates:
8084 • Format lists, e.g. files:
8086 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
8088 • Join the list of files with a ", ":
8090 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
8092 • Join the list of files ending with ".py" with a ", ":
8094 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
8096 • Separate non-empty arguments by a " ":
8098 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
8100 • Modify each line of a commit description:
8102 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
8104 • Format date:
8106 $ hg log -r 0 --template "{date(date, '%Y')}\n"
8108 • Display date in UTC:
8110 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
8112 • Output the description set to a fill-width of 30:
8114 $ hg log -r 0 --template "{fill(desc, 30)}"
8116 • Use a conditional to test for the default branch:
8118 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
8120 'on branch {branch}')}\n"
8121 • Append a newline if not empty:
8123 $ hg tip --template "{if(author, '{author}\n')}"
8125 • Label the output for use with the color extension:
8127 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
8129 • Invert the firstline filter, i.e. everything but the first line:
8131 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
8133 • Display the contents of the 'extra' field, one per line:
8135 $ hg log -r 0 --template "{join(extras, '\n')}\n"
8137 • Mark the active bookmark with '*':
8139 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
8141 • Find the previous release candidate tag, the distance and changes
8143 since the tag:
8144 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
8146 • Mark the working copy parent with '@':
8148 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
8150 • Show details of parent revisions:
8152 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
8154 • Show only commit descriptions that start with "template":
8156 $ hg log --template "{startswith('template', firstline(desc))}\n"
8158 • Print the first word of each line of a commit message:
8160 $ hg log --template "{word(0, desc)}\n"
8162
8164 Valid URLs are of the form:
8165 local/filesystem/path[#revision]
8167 file://local/filesystem/path[#revision]
8168 http://[user[:pass]@]host[:port]/[path][#revision]
8169 https://[user[:pass]@]host[:port]/[path][#revision]
8170 ssh://[user@]host[:port]/[path][#revision]
8171 path://pathname
8172 Paths in the local filesystem can either point to Mercurial reposito‐
8174 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
8175 dle). See also hg help paths.
8176 An optional identifier after # indicates a particular branch, tag, or
8178 changeset to use from the remote repository. See also hg help revisions
8179 .
8180 Some features, such as pushing to http:// and https:// URLs are only
8182 possible if the feature is explicitly enabled on the remote Mercurial
8183 server.
8184 Note that the security of HTTPS URLs depends on proper configuration of
8186 web.cacerts.
8187 Some notes about using SSH with Mercurial:
8189 • SSH requires an accessible shell account on the destination machine
8191 and a copy of hg in the remote path or specified with remotecmd.
8192 • path is relative to the remote user's home directory by default. Use
8194 an extra slash at the start of a path to specify an absolute path:
8195 ssh://example.com//tmp/repository
8197 • Mercurial doesn't use its own compression via SSH; the right thing to
8199 do is to configure it in your ~/.ssh/config, e.g.:
8200 Host *.mylocalnetwork.example.com
8202 Compression no
8203 Host *
8204 Compression yes
8205 Alternatively specify "ssh -C" as your ssh command in your configura‐
8207 tion file or with the --ssh command line option.
8208 These URLs can all be stored in your configuration file with path
8210 aliases under the [paths] section like so:
8211 [paths]
8213 alias1 = URL1
8214 alias2 = URL2
8215 ...
8216 You can then use the alias for any command that uses a URL (for example
8218 hg pull alias1 will be treated as hg pull URL1).
8219 Two path aliases are special because they are used as defaults when you
8221 do not provide the URL to a command:
8222 default:
8224 When you create a repository with hg clone, the clone command
8225 saves the location of the source repository as the new reposi‐
8226 tory's 'default' path. This is then used when you omit path from
8227 push- and pull-like commands (including incoming and outgoing).
8228 default-push:
8230 The push command will look for a path named 'default-push', and
8231 prefer it over 'default' if both are defined.
8232 These alias can also be use in the path:// scheme:
8234 [paths]
8236 alias1 = URL1
8237 alias2 = path://alias1
8238 ...
8239 check hg help config.paths for details about the behavior of such
8241 "sub-path".
8242
8244 This section contains help for extensions that are distributed together
8245 with Mercurial. Help for other extensions is available in the help sys‐
8246 tem.
8247 absorb
8249 apply working directory changes to changesets (EXPERIMENTAL)
8250 The absorb extension provides a command to use annotate information to
8252 amend modified chunks into the corresponding non-public changesets.
8253 [absorb]
8255 # only check 50 recent non-public changesets at most
8256 max-stack-size = 50
8257 # whether to add noise to new commits to avoid obsolescence cycle
8258 add-noise = 1
8259 # make `amend --correlated` a shortcut to the main command
8260 amend-flag = correlated
8261 [color]
8263 absorb.description = yellow
8264 absorb.node = blue bold
8265 absorb.path = bold
8266 Commands
8268 Change creation
8269 absorb
8270 incorporate corrections into the stack of draft changesets:
8271 hg absorb [OPTION] [FILE]...
8273 absorb analyzes each change in your working directory and attempts to
8275 amend the changed lines into the changesets in your stack that first
8276 introduced those lines.
8277 If absorb cannot find an unambiguous changeset to amend for a change,
8279 that change will be left in the working directory, untouched. They can
8280 be observed by hg status or hg diff afterwards. In other words, absorb
8281 does not write to the working directory.
8282 Changesets outside the revset ::. and not public() and not merge() will
8284 not be changed.
8285 Changesets that become empty after applying the changes will be
8287 deleted.
8288 By default, absorb will show what it plans to do and prompt for confir‐
8290 mation. If you are confident that the changes will be absorbed to the
8291 correct place, run hg absorb -a to apply the changes immediately.
8292 Returns 0 on success, 1 if all chunks were ignored and nothing amended.
8294 Options:
8296 -a, --apply-changes
8298 apply changes without prompting for confirmation
8299 -p, --print-changes
8301 always print which changesets are modified by which changes
8302 -i, --interactive
8304 interactively select which chunks to apply
8305 -e, --edit-lines
8307 edit what lines belong to which changesets before commit (EXPER‐
8308 IMENTAL)
8309 -n, --dry-run
8311 do not perform actions, just print output
8312 --style <STYLE>
8314 display using template map file (DEPRECATED)
8315 -T,--template <TEMPLATE>
8317 display with template
8318 -I,--include <PATTERN[+]>
8320 include names matching the given patterns
8321 -X,--exclude <PATTERN[+]>
8323 exclude names matching the given patterns
8324 [+] marked option can be specified multiple times
8326 acl
8328 hooks for controlling repository access
8329 This hook makes it possible to allow or deny write access to given
8331 branches and paths of a repository when receiving incoming changesets
8332 via pretxnchangegroup and pretxncommit.
8333 The authorization is matched based on the local user name on the system
8335 where the hook runs, and not the committer of the original changeset
8336 (since the latter is merely informative).
8337 The acl hook is best used along with a restricted shell like hgsh, pre‐
8339 venting authenticating users from doing anything other than pushing or
8340 pulling. The hook is not safe to use if users have interactive shell
8341 access, as they can then disable the hook. Nor is it safe if remote
8342 users share an account, because then there is no way to distinguish
8343 them.
8344 The order in which access checks are performed is:
8346 1. Deny list for branches (section acl.deny.branches)
8348 2. Allow list for branches (section acl.allow.branches)
8350 3. Deny list for paths (section acl.deny)
8352 4. Allow list for paths (section acl.allow)
8354 The allow and deny sections take key-value pairs.
8356 Branch-based Access Control
8358 Use the acl.deny.branches and acl.allow.branches sections to have
8359 branch-based access control. Keys in these sections can be either:
8360 • a branch name, or
8362 • an asterisk, to match any branch;
8364 The corresponding values can be either:
8366 • a comma-separated list containing users and groups, or
8368 • an asterisk, to match anyone;
8370 You can add the "!" prefix to a user or group name to invert the sense
8372 of the match.
8373 Path-based Access Control
8375 Use the acl.deny and acl.allow sections to have path-based access con‐
8376 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
8377 tax by default). The corresponding values follow the same syntax as the
8378 other sections above.
8379 Bookmark-based Access Control
8381 Use the acl.deny.bookmarks and acl.allow.bookmarks sections to have
8382 bookmark-based access control. Keys in these sections can be either:
8383 • a bookmark name, or
8385 • an asterisk, to match any bookmark;
8387 The corresponding values can be either:
8389 • a comma-separated list containing users and groups, or
8391 • an asterisk, to match anyone;
8393 You can add the "!" prefix to a user or group name to invert the sense
8395 of the match.
8396 Note: for interactions between clients and servers using Mercurial 3.6+
8398 a rejection will generally reject the entire push, for interactions in‐
8399 volving older clients, the commit transactions will already be ac‐
8400 cepted, and only the bookmark movement will be rejected.
8401 Groups
8403 Group names must be prefixed with an @ symbol. Specifying a group name
8404 has the same effect as specifying all the users in that group.
8405 You can define group members in the acl.groups section. If a group
8407 name is not defined there, and Mercurial is running under a Unix-like
8408 system, the list of users will be taken from the OS. Otherwise, an ex‐
8409 ception will be raised.
8410 Example Configuration
8412 [hooks]
8413 # Use this if you want to check access restrictions at commit time
8415 pretxncommit.acl = python:hgext.acl.hook
8416 # Use this if you want to check access restrictions for pull, push,
8418 # bundle and serve.
8419 pretxnchangegroup.acl = python:hgext.acl.hook
8420 [acl]
8422 # Allow or deny access for incoming changes only if their source is
8423 # listed here, let them pass otherwise. Source is "serve" for all
8424 # remote access (http or ssh), "push", "pull" or "bundle" when the
8425 # related commands are run locally.
8426 # Default: serve
8427 sources = serve
8428 [acl.deny.branches]
8430 # Everyone is denied to the frozen branch:
8432 frozen-branch = *
8433 # A bad user is denied on all branches:
8435 * = bad-user
8436 [acl.allow.branches]
8438 # A few users are allowed on branch-a:
8440 branch-a = user-1, user-2, user-3
8441 # Only one user is allowed on branch-b:
8443 branch-b = user-1
8444 # The super user is allowed on any branch:
8446 * = super-user
8447 # Everyone is allowed on branch-for-tests:
8449 branch-for-tests = *
8450 [acl.deny]
8452 # This list is checked first. If a match is found, acl.allow is not
8453 # checked. All users are granted access if acl.deny is not present.
8454 # Format for both lists: glob pattern = user, ..., @group, ...
8455 # To match everyone, use an asterisk for the user:
8457 # my/glob/pattern = *
8458 # user6 will not have write access to any file:
8460 ** = user6
8461 # Group "hg-denied" will not have write access to any file:
8463 ** = @hg-denied
8464 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
8466 # everyone being able to change all other files. See below.
8467 src/main/resources/DONT-TOUCH-THIS.txt = *
8468 [acl.allow]
8470 # if acl.allow is not present, all users are allowed by default
8471 # empty acl.allow = no users allowed
8472 # User "doc_writer" has write access to any file under the "docs"
8474 # folder:
8475 docs/** = doc_writer
8476 # User "jack" and group "designers" have write access to any file
8478 # under the "images" folder:
8479 images/** = jack, @designers
8480 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
8482 # will have write access to any file under the "resources" folder
8483 # (except for 1 file. See acl.deny):
8484 src/main/resources/** = *
8485 .hgtags = release_engineer
8487 Examples using the ! prefix
8489 Suppose there's a branch that only a given user (or group) should be
8490 able to push to, and you don't want to restrict access to any other
8491 branch that may be created.
8492 The "!" prefix allows you to prevent anyone except a given user or
8494 group to push changesets in a given branch or path.
8495 In the examples below, we will: 1) Deny access to branch "ring" to any‐
8497 one but user "gollum" 2) Deny access to branch "lake" to anyone but
8498 members of the group "hobbit" 3) Deny access to a file to anyone but
8499 user "gollum"
8500 [acl.allow.branches]
8502 # Empty
8503 [acl.deny.branches]
8505 # 1) only 'gollum' can commit to branch 'ring';
8507 # 'gollum' and anyone else can still commit to any other branch.
8508 ring = !gollum
8509 # 2) only members of the group 'hobbit' can commit to branch 'lake';
8511 # 'hobbit' members and anyone else can still commit to any other branch.
8512 lake = !@hobbit
8513 # You can also deny access based on file paths:
8515 [acl.allow]
8517 # Empty
8518 [acl.deny]
8520 # 3) only 'gollum' can change the file below;
8521 # 'gollum' and anyone else can still change any other file.
8522 /misty/mountains/cave/ring = !gollum
8523 amend
8525 provide the amend command (EXPERIMENTAL)
8526 This extension provides an amend command that is similar to commit
8528 --amend but does not prompt an editor.
8529 Commands
8531 Change creation
8532 amend
8533 amend the working copy parent with all or specified outstanding
8534 changes:
8535 hg amend [OPTION]... [FILE]...
8537 Similar to hg commit --amend, but reuse the commit message without in‐
8539 voking editor, unless --edit was set.
8540 See hg help commit for more details.
8542 Options:
8544 -A, --addremove
8546 mark new/missing files as added/removed before committing
8547 -e, --edit
8549 invoke editor on commit messages
8550 -i, --interactive
8552 use interactive mode
8553 --close-branch
8555 mark a branch as closed, hiding it from the branch list
8556 -s, --secret
8558 use the secret phase for committing
8559 --draft
8561 use the draft phase for committing
8562 -n,--note <VALUE>
8564 store a note on the amend
8565 -I,--include <PATTERN[+]>
8567 include names matching the given patterns
8568 -X,--exclude <PATTERN[+]>
8570 exclude names matching the given patterns
8571 -m,--message <TEXT>
8573 use text as commit message
8574 -l,--logfile <FILE>
8576 read commit message from file
8577 -d,--date <DATE>
8579 record the specified date as commit date
8580 -u,--user <USER>
8582 record the specified user as committer
8583 -D, --currentdate
8585 record the current date as commit date
8586 -U, --currentuser
8588 record the current user as committer
8589 [+] marked option can be specified multiple times
8591 automv
8593 check for unrecorded moves at commit time (EXPERIMENTAL)
8594 This extension checks at commit/amend time if any of the committed
8596 files comes from an unrecorded mv.
8597 The threshold at which a file is considered a move can be set with the
8599 automv.similarity config option. This option takes a percentage between
8600 0 (disabled) and 100 (files must be identical), the default is 95.
8601 beautifygraph
8603 beautify log -G output by using Unicode characters (EXPERIMENTAL)
8604 A terminal with UTF-8 support and monospace narrow text are re‐
8606 quired.
8607 blackbox
8609 log repository events to a blackbox for debugging
8610 Logs event information to .hg/blackbox.log to help debug and diagnose
8612 problems. The events that get logged can be configured via the black‐
8613 box.track and blackbox.ignore config keys.
8614 Examples:
8616 [blackbox]
8618 track = *
8619 ignore = pythonhook
8620 # dirty is *EXPENSIVE* (slow);
8621 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
8622 dirty = True
8623 # record the source of log messages
8624 logsource = True
8625 [blackbox]
8627 track = command, commandfinish, commandexception, exthook, pythonhook
8628 [blackbox]
8630 track = incoming
8631 [blackbox]
8633 # limit the size of a log file
8634 maxsize = 1.5 MB
8635 # rotate up to N log files when the current one gets too big
8636 maxfiles = 3
8637 [blackbox]
8639 # Include microseconds in log entries with %f (see Python function
8640 # datetime.datetime.strftime)
8641 date-format = %Y-%m-%d @ %H:%M:%S.%f
8642 Commands
8644 Repository maintenance
8645 blackbox
8646 view the recent repository events:
8647 hg blackbox [OPTION]...
8649 view the recent repository events
8651 Options:
8653 -l,--limit <VALUE>
8655 the number of events to show (default: 10)
8656 bookflow
8658 implements bookmark-based branching (EXPERIMENTAL)
8659 • Disables creation of new branches (config: enable_branches=False).
8661 • Requires an active bookmark on commit (config: require_book‐
8663 mark=True).
8664 • Doesn't move the active bookmark on update, only on commit.
8666 • Requires '--rev' for moving an existing bookmark.
8668 • Protects special bookmarks (config: protect=@).
8670 flow related commands
8672 hg book NAME
8674 create a new bookmark
8675 hg book NAME -r REV
8677 move bookmark to revision (fast-forward)
8678 hg up|co NAME
8680 switch to bookmark
8681 hg push -B .
8683 push active bookmark
8684 bugzilla
8686 hooks for integrating with the Bugzilla bug tracker
8687 This hook extension adds comments on bugs in Bugzilla when changesets
8689 that refer to bugs by Bugzilla ID are seen. The comment is formatted
8690 using the Mercurial template mechanism.
8691 The bug references can optionally include an update for Bugzilla of the
8693 hours spent working on the bug. Bugs can also be marked fixed.
8694 Four basic modes of access to Bugzilla are provided:
8696 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
8698 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
8700 later.
8701 3. Check data via the Bugzilla XMLRPC interface and submit bug change
8703 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
8704 later.
8705 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
8707 tions using MySQL are supported. Requires Python MySQLdb.
8708 Writing directly to the database is susceptible to schema changes, and
8710 relies on a Bugzilla contrib script to send out bug change notification
8711 emails. This script runs as the user running Mercurial, must be run on
8712 the host with the Bugzilla install, and requires permission to read
8713 Bugzilla configuration details and the necessary MySQL user and pass‐
8714 word to have full access rights to the Bugzilla database. For these
8715 reasons this access mode is now considered deprecated, and will not be
8716 updated for new Bugzilla versions going forward. Only adding comments
8717 is supported in this access mode.
8718 Access via XMLRPC needs a Bugzilla username and password to be speci‐
8720 fied in the configuration. Comments are added under that username.
8721 Since the configuration must be readable by all Mercurial users, it is
8722 recommended that the rights of that user are restricted in Bugzilla to
8723 the minimum necessary to add comments. Marking bugs fixed requires
8724 Bugzilla 4.0 and later.
8725 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
8727 to the Bugzilla email interface to submit comments to bugs. The From:
8728 address in the email is set to the email address of the Mercurial user,
8729 so the comment appears to come from the Mercurial user. In the event
8730 that the Mercurial user email is not recognized by Bugzilla as a
8731 Bugzilla user, the email associated with the Bugzilla username used to
8732 log into Bugzilla is used instead as the source of the comment. Marking
8733 bugs fixed works on all supported Bugzilla versions.
8734 Access via the REST-API needs either a Bugzilla username and password
8736 or an apikey specified in the configuration. Comments are made under
8737 the given username or the user associated with the apikey in Bugzilla.
8738 Configuration items common to all access modes:
8740 bugzilla.version
8742 The access type to use. Values recognized are:
8743 restapi
8745 Bugzilla REST-API, Bugzilla 5.0 and later.
8747 xmlrpc
8749 Bugzilla XMLRPC interface.
8751 xmlrpc+email
8753 Bugzilla XMLRPC and email interfaces.
8755 3.0
8757 MySQL access, Bugzilla 3.0 and later.
8759 2.18
8761 MySQL access, Bugzilla 2.18 and up to but not including
8763 3.0.
8764 2.16
8766 MySQL access, Bugzilla 2.16 and up to but not including
8768 2.18.
8769 bugzilla.regexp
8771 Regular expression to match bug IDs for update in changeset com‐
8772 mit message. It must contain one "()" named group <ids> con‐
8773 taining the bug IDs separated by non-digit characters. It may
8774 also contain a named group <hours> with a floating-point number
8775 giving the hours worked on the bug. If no named groups are
8776 present, the first "()" group is assumed to contain the bug IDs,
8777 and work time is not updated. The default expression matches Bug
8778 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
8779 and 5678 and variations thereof, followed by an hours number
8780 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
8781 sitive.
8782 bugzilla.fixregexp
8784 Regular expression to match bug IDs for marking fixed in change‐
8785 set commit message. This must contain a "()" named group <ids>`
8786 containing the bug IDs separated by non-digit characters. It may
8787 also contain a named group ``<hours> with a floating-point num‐
8788 ber giving the hours worked on the bug. If no named groups are
8789 present, the first "()" group is assumed to contain the bug IDs,
8790 and work time is not updated. The default expression matches
8791 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
8792 5678 and variations thereof, followed by an hours number pre‐
8793 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
8794 tive.
8795 bugzilla.fixstatus
8797 The status to set a bug to when marking fixed. Default RESOLVED.
8798 bugzilla.fixresolution
8800 The resolution to set a bug to when marking fixed. Default
8801 FIXED.
8802 bugzilla.style
8804 The style file to use when formatting comments.
8805 bugzilla.template
8807 Template to use when formatting comments. Overrides style if
8808 specified. In addition to the usual Mercurial keywords, the ex‐
8809 tension specifies:
8810 {bug}
8812 The Bugzilla bug ID.
8814 {root}
8816 The full pathname of the Mercurial repository.
8818 {webroot}
8820 Stripped pathname of the Mercurial repository.
8822 {hgweb}
8824 Base URL for browsing Mercurial repositories.
8826 Default changeset {node|short} in repo {root} refers to bug
8828 {bug}.\ndetails:\n\t{desc|tabindent}
8829 bugzilla.strip
8831 The number of path separator characters to strip from the front
8832 of the Mercurial repository path ({root} in templates) to pro‐
8833 duce {webroot}. For example, a repository with {root} /var/lo‐
8834 cal/my-project with a strip of 2 gives a value for {webroot} of
8835 my-project. Default 0.
8836 web.baseurl
8838 Base URL for browsing Mercurial repositories. Referenced from
8839 templates as {hgweb}.
8840 Configuration items common to XMLRPC+email and MySQL access modes:
8842 bugzilla.usermap
8844 Path of file containing Mercurial committer email to Bugzilla
8845 user email mappings. If specified, the file should contain one
8846 mapping per line:
8847 committer = Bugzilla user
8849 See also the [usermap] section.
8851 The [usermap] section is used to specify mappings of Mercurial commit‐
8853 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
8854 entries of the form committer = Bugzilla user.
8855 XMLRPC and REST-API access mode configuration:
8857 bugzilla.bzurl
8859 The base URL for the Bugzilla installation. Default http://lo‐
8860 calhost/bugzilla.
8861 bugzilla.user
8863 The username to use to log into Bugzilla via XMLRPC. Default
8864 bugs.
8865 bugzilla.password
8867 The password for Bugzilla login.
8868 REST-API access mode uses the options listed above as well as:
8870 bugzilla.apikey
8872 An apikey generated on the Bugzilla instance for api access.
8873 Using an apikey removes the need to store the user and password
8874 options.
8875 XMLRPC+email access mode uses the XMLRPC access mode configuration
8877 items, and also:
8878 bugzilla.bzemail
8880 The Bugzilla email address.
8881 In addition, the Mercurial email settings must be configured. See the
8883 documentation in hgrc(5), sections [email] and [smtp].
8884 MySQL access mode configuration:
8886 bugzilla.host
8888 Hostname of the MySQL server holding the Bugzilla database. De‐
8889 fault localhost.
8890 bugzilla.db
8892 Name of the Bugzilla database in MySQL. Default bugs.
8893 bugzilla.user
8895 Username to use to access MySQL server. Default bugs.
8896 bugzilla.password
8898 Password to use to access MySQL server.
8899 bugzilla.timeout
8901 Database connection timeout (seconds). Default 5.
8902 bugzilla.bzuser
8904 Fallback Bugzilla user name to record comments with, if change‐
8905 set committer cannot be found as a Bugzilla user.
8906 bugzilla.bzdir
8908 Bugzilla install directory. Used by default notify. Default
8909 /var/www/html/bugzilla.
8910 bugzilla.notify
8912 The command to run to get Bugzilla to send bug change notifica‐
8913 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
8914 id) and user (committer bugzilla email). Default depends on ver‐
8915 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
8916 mail.pl %(id)s %(user)s".
8917 Activating the extension:
8919 [extensions]
8921 bugzilla =
8922 [hooks]
8924 # run bugzilla hook on every change pulled or pushed in here
8925 incoming.bugzilla = python:hgext.bugzilla.hook
8926 Example configurations:
8928 XMLRPC example configuration. This uses the Bugzilla at
8930 http://my-project.org/bugzilla, logging in as user bug‐
8931 mail@my-project.org with password plugh. It is used with a collection
8932 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8933 at http://my-project.org/hg.
8934 [bugzilla]
8936 bzurl=http://my-project.org/bugzilla
8937 user=bugmail@my-project.org
8938 password=plugh
8939 version=xmlrpc
8940 template=Changeset {node|short} in {root|basename}.
8941 {hgweb}/{webroot}/rev/{node|short}\n
8942 {desc}\n
8943 strip=5
8944 [web]
8946 baseurl=http://my-project.org/hg
8947 XMLRPC+email example configuration. This uses the Bugzilla at
8949 http://my-project.org/bugzilla, logging in as user bug‐
8950 mail@my-project.org with password plugh. It is used with a collection
8951 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8952 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
8953 email address bugzilla@my-project.org.
8954 [bugzilla]
8956 bzurl=http://my-project.org/bugzilla
8957 user=bugmail@my-project.org
8958 password=plugh
8959 version=xmlrpc+email
8960 bzemail=bugzilla@my-project.org
8961 template=Changeset {node|short} in {root|basename}.
8962 {hgweb}/{webroot}/rev/{node|short}\n
8963 {desc}\n
8964 strip=5
8965 [web]
8967 baseurl=http://my-project.org/hg
8968 [usermap]
8970 user@emaildomain.com=user.name@bugzilladomain.com
8971 MySQL example configuration. This has a local Bugzilla 3.2 installation
8973 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
8974 database name is bugs and MySQL is accessed with MySQL username bugs
8975 password XYZZY. It is used with a collection of Mercurial repositories
8976 in /var/local/hg/repos/, with a web interface at
8977 http://my-project.org/hg.
8978 [bugzilla]
8980 host=localhost
8981 password=XYZZY
8982 version=3.0
8983 bzuser=unknown@domain.com
8984 bzdir=/opt/bugzilla-3.2
8985 template=Changeset {node|short} in {root|basename}.
8986 {hgweb}/{webroot}/rev/{node|short}\n
8987 {desc}\n
8988 strip=5
8989 [web]
8991 baseurl=http://my-project.org/hg
8992 [usermap]
8994 user@emaildomain.com=user.name@bugzilladomain.com
8995 All the above add a comment to the Bugzilla bug record of the form:
8997 Changeset 3b16791d6642 in repository-name.
8999 http://my-project.org/hg/repository-name/rev/3b16791d6642
9000 Changeset commit comment. Bug 1234.
9002 censor
9004 erase file content at a given revision
9005 The censor command instructs Mercurial to erase all content of a file
9007 at a given revision without updating the changeset hash. This allows
9008 existing history to remain valid while preventing future clones/pulls
9009 from receiving the erased data.
9010 Typical uses for censor are due to security or legal requirements, in‐
9012 cluding:
9013 * Passwords, private keys, cryptographic material
9015 * Licensed data/code/libraries for which the license has expired
9016 * Personally Identifiable Information or other private data
9017 Censored nodes can interrupt mercurial's typical operation whenever the
9019 excised data needs to be materialized. Some commands, like hg cat/hg
9020 revert, simply fail when asked to produce censored data. Others, like
9021 hg verify and hg update, must be capable of tolerating censored data to
9022 continue to function in a meaningful way. Such commands only tolerate
9023 censored file revisions if they are allowed by the "censor.policy=ig‐
9024 nore" config option.
9025 A few informative commands such as hg grep will unconditionally ignore
9027 censored data and merely report that it was encountered.
9028 Commands
9030 Repository maintenance
9031 censor
9032 hg censor -r REV [-t TEXT] [FILE]
9033 Options:
9035 -r,--rev <REV>
9037 censor file from specified revision
9038 -t,--tombstone <TEXT>
9040 replacement tombstone data
9041 children
9043 command to display child changesets (DEPRECATED)
9044 This extension is deprecated. You should use hg log -r "children(REV)"
9046 instead.
9047 Commands
9049 Change navigation
9050 children
9051 show the children of the given or working directory revision:
9052 hg children [-r REV] [FILE]
9054 Print the children of the working directory's revisions. If a revision
9056 is given via -r/--rev, the children of that revision will be printed.
9057 If a file argument is given, revision in which the file was last
9058 changed (after the working directory revision or the argument to --rev
9059 if given) is printed.
9060 Please use hg log instead:
9062 hg children => hg log -r "children(.)"
9064 hg children -r REV => hg log -r "children(REV)"
9065 See hg help log and hg help revsets.children.
9067 Options:
9069 -r,--rev <REV>
9071 show children of the specified revision (default: .)
9072 --style <STYLE>
9074 display using template map file (DEPRECATED)
9075 -T,--template <TEMPLATE>
9077 display with template
9078 churn
9080 command to display statistics about repository history
9081 Commands
9083 Repository maintenance
9084 churn
9085 histogram of changes to the repository:
9086 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
9088 This command will display a histogram representing the number of
9090 changed lines or revisions, grouped according to the given template.
9091 The default template will group changes by author. The --dateformat
9092 option may be used to group the results by date instead.
9093 Statistics are based on the number of changed lines, or alternatively
9095 the number of matching revisions if the --changesets option is speci‐
9096 fied.
9097 Examples:
9099 # display count of changed lines for every committer
9101 hg churn -T "{author|email}"
9102 # display daily activity graph
9104 hg churn -f "%H" -s -c
9105 # display activity of developers by month
9107 hg churn -f "%Y-%m" -s -c
9108 # display count of lines changed in every year
9110 hg churn -f "%Y" -s
9111 # display count of lines changed in a time range
9113 hg churn -d "2020-04 to 2020-09"
9114 It is possible to map alternate email addresses to a main address by
9116 providing a file using the following format:
9117 <alias email> = <actual email>
9119 Such a file may be specified with the --aliases option, otherwise a
9121 .hgchurn file will be looked for in the working directory root.
9122 Aliases will be split from the rightmost "=".
9123 Options:
9125 -r,--rev <REV[+]>
9127 count rate for the specified revision or revset
9128 -d,--date <DATE>
9130 count rate for revisions matching date spec
9131 -t,--oldtemplate <TEMPLATE>
9133 template to group changesets (DEPRECATED)
9134 -T,--template <TEMPLATE>
9136 template to group changesets (default: {author|email})
9137 -f,--dateformat <FORMAT>
9139 strftime-compatible format for grouping by date
9140 -c, --changesets
9142 count rate by number of changesets
9143 -s, --sort
9145 sort by key (default: sort by count)
9146 --diffstat
9148 display added/removed lines separately
9149 --aliases <FILE>
9151 file with email aliases
9152 -I,--include <PATTERN[+]>
9154 include names matching the given patterns
9155 -X,--exclude <PATTERN[+]>
9157 exclude names matching the given patterns
9158 [+] marked option can be specified multiple times
9160 clonebundles
9162 advertise pre-generated bundles to seed clones
9163 "clonebundles" is a server-side extension used to advertise the exis‐
9165 tence of pre-generated, externally hosted bundle files to clients that
9166 are cloning so that cloning can be faster, more reliable, and require
9167 less resources on the server. "pullbundles" is a related feature for
9168 sending pre-generated bundle files to clients as part of pull opera‐
9169 tions.
9170 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
9172 ally, the server, in response to a client's request to clone, dynami‐
9173 cally generates a bundle containing the entire repository content and
9174 sends it to the client. There is no caching on the server and the
9175 server will have to redundantly generate the same outgoing bundle in
9176 response to each clone request. For servers with large repositories or
9177 with high clone volume, the load from clones can make scaling the
9178 server challenging and costly.
9179 This extension provides server operators the ability to offload poten‐
9181 tially expensive clone load to an external service. Pre-generated bun‐
9182 dles also allow using more CPU intensive compression, reducing the ef‐
9183 fective bandwidth requirements.
9184 Here's how clone bundles work:
9186 1. A server operator establishes a mechanism for making bundle files
9188 available on a hosting service where Mercurial clients can fetch
9189 them.
9190 2. A manifest file listing available bundle URLs and some optional
9192 metadata is added to the Mercurial repository on the server.
9193 3. A client initiates a clone against a clone bundles aware server.
9195 4. The client sees the server is advertising clone bundles and fetches
9197 the manifest listing available bundles.
9198 5. The client filters and sorts the available bundles based on what it
9200 supports and prefers.
9201 6. The client downloads and applies an available bundle from the
9203 server-specified URL.
9204 7. The client reconnects to the original server and performs the equiv‐
9206 alent of hg pull to retrieve all repository data not in the bundle.
9207 (The repository could have been updated between when the bundle was
9208 created and when the client started the clone.) This may use "pull‐
9209 bundles".
9210 Instead of the server generating full repository bundles for every
9212 clone request, it generates full bundles once and they are subsequently
9213 reused to bootstrap new clones. The server may still transfer data at
9214 clone time. However, this is only data that has been added/changed
9215 since the bundle was created. For large, established repositories, this
9216 can reduce server load for clones to less than 1% of original.
9217 Here's how pullbundles work:
9219 1. A manifest file listing available bundles and describing the revi‐
9221 sions is added to the Mercurial repository on the server.
9222 2. A new-enough client informs the server that it supports partial
9224 pulls and initiates a pull.
9225 3. If the server has pull bundles enabled and sees the client advertis‐
9227 ing partial pulls, it checks for a matching pull bundle in the mani‐
9228 fest. A bundle matches if the format is supported by the client,
9229 the client has the required revisions already and needs something
9230 from the bundle.
9231 4. If there is at least one matching bundle, the server sends it to the
9233 client.
9234 5. The client applies the bundle and notices that the server reply was
9236 incomplete. It initiates another pull.
9237 To work, this extension requires the following of server operators:
9239 • Generating bundle files of repository content (typically periodi‐
9241 cally, such as once per day).
9242 • Clone bundles: A file server that clients have network access to and
9244 that Python knows how to talk to through its normal URL handling fa‐
9245 cility (typically an HTTP/HTTPS server).
9246 • A process for keeping the bundles manifest in sync with available
9248 bundle files.
9249 Strictly speaking, using a static file hosting server isn't required: a
9251 server operator could use a dynamic service for retrieving bundle data.
9252 However, static file hosting services are simple and scalable and
9253 should be sufficient for most needs.
9254 Bundle files can be generated with the hg bundle command. Typically hg
9256 bundle --all is used to produce a bundle of the entire repository.
9257 The bundlespec option stream (see hg help bundlespec) can be used to
9259 produce a special streaming clonebundle, typically using hg bundle
9260 --all --type="none-streamv2". These are bundle files that are ex‐
9261 tremely efficient to produce and consume (read: fast). However, they
9262 are larger than traditional bundle formats and require that clients
9263 support the exact set of repository data store formats in use by the
9264 repository that created them. Typically, a newer server can serve data
9265 that is compatible with older clients. However, streaming clone bun‐
9266 dles don't have this guarantee. Server operators need to be aware that
9267 newer versions of Mercurial may produce streaming clone bundles incom‐
9268 patible with older Mercurial versions.
9269 A server operator is responsible for creating a .hg/clonebundles.mani‐
9271 fest file containing the list of available bundle files suitable for
9272 seeding clones. If this file does not exist, the repository will not
9273 advertise the existence of clone bundles when clients connect. For pull
9274 bundles, .hg/pullbundles.manifest is used.
9275 The manifest file contains a newline (n) delimited list of entries.
9277 Each line in this file defines an available bundle. Lines have the for‐
9279 mat:
9280 <URL> [<key>=<value>[ <key>=<value>]]
9282 That is, a URL followed by an optional, space-delimited list of
9284 key=value pairs describing additional properties of this bundle. Both
9285 keys and values are URI encoded.
9286 For pull bundles, the URL is a path under the .hg directory of the
9288 repository.
9289 Keys in UPPERCASE are reserved for use by Mercurial and are defined be‐
9291 low. All non-uppercase keys can be used by site installations. An ex‐
9292 ample use for custom properties is to use the datacenter attribute to
9293 define which data center a file is hosted in. Clients could then prefer
9294 a server in the data center closest to them.
9295 The following reserved keys are currently defined:
9297 BUNDLESPEC
9299 A "bundle specification" string that describes the type of the
9300 bundle.
9301 These are string values that are accepted by the "--type" argu‐
9303 ment of hg bundle.
9304 The values are parsed in strict mode, which means they must be
9306 of the "<compression>-<type>" form. See mercurial.ex‐
9307 change.parsebundlespec() for more details.
9308 hg debugbundle --spec can be used to print the bundle specifica‐
9310 tion string for a bundle file. The output of this command can be
9311 used verbatim for the value of BUNDLESPEC (it is already es‐
9312 caped).
9313 Clients will automatically filter out specifications that are
9315 unknown or unsupported so they won't attempt to download some‐
9316 thing that likely won't apply.
9317 The actual value doesn't impact client behavior beyond filter‐
9319 ing: clients will still sniff the bundle type from the header of
9320 downloaded files.
9321 Use of this key is highly recommended, as it allows clients to
9323 easily skip unsupported bundles. If this key is not defined, an
9324 old client may attempt to apply a bundle that it is incapable of
9325 reading.
9326 REQUIRESNI
9328 Whether Server Name Indication (SNI) is required to connect to
9329 the URL. SNI allows servers to use multiple certificates on the
9330 same IP. It is somewhat common in CDNs and other hosting
9331 providers. Older Python versions do not support SNI. Defining
9332 this attribute enables clients with older Python versions to
9333 filter this entry without experiencing an opaque SSL failure at
9334 connection time.
9335 If this is defined, it is important to advertise a non-SNI fall‐
9337 back URL or clients running old Python releases may not be able
9338 to clone with the clonebundles facility.
9339 Value should be "true".
9341 REQUIREDRAM
9343 Value specifies expected memory requirements to decode the pay‐
9344 load. Values can have suffixes for common bytes sizes. e.g.
9345 "64MB".
9346 This key is often used with zstd-compressed bundles using a high
9348 compression level / window size, which can require 100+ MB of
9349 memory to decode.
9350 heads Used for pull bundles. This contains the ; separated changeset
9352 hashes of the heads of the bundle content.
9353 bases Used for pull bundles. This contains the ; separated changeset
9355 hashes of the roots of the bundle content. This can be skipped
9356 if the bundle was created without --base.
9357 Manifests can contain multiple entries. Assuming metadata is defined,
9359 clients will filter entries from the manifest that they don't support.
9360 The remaining entries are optionally sorted by client preferences
9361 (ui.clonebundleprefers config option). The client then attempts to
9362 fetch the bundle at the first URL in the remaining list.
9363 Errors when downloading a bundle will fail the entire clone operation:
9365 clients do not automatically fall back to a traditional clone. The rea‐
9366 son for this is that if a server is using clone bundles, it is probably
9367 doing so because the feature is necessary to help it scale. In other
9368 words, there is an assumption that clone load will be offloaded to an‐
9369 other service and that the Mercurial server isn't responsible for serv‐
9370 ing this clone load. If that other service experiences issues and
9371 clients start mass falling back to the original Mercurial server, the
9372 added clone load could overwhelm the server due to unexpected load and
9373 effectively take it offline. Not having clients automatically fall back
9374 to cloning from the original server mitigates this scenario.
9375 Because there is no automatic Mercurial server fallback on failure of
9377 the bundle hosting service, it is important for server operators to
9378 view the bundle hosting service as an extension of the Mercurial server
9379 in terms of availability and service level agreements: if the bundle
9380 hosting service goes down, so does the ability for clients to clone.
9381 Note: clients will see a message informing them how to bypass the clone
9382 bundles facility when a failure occurs. So server operators should pre‐
9383 pare for some people to follow these instructions when a failure oc‐
9384 curs, thus driving more load to the original Mercurial server when the
9385 bundle hosting service fails.
9386 inline clonebundles
9388 It is possible to transmit clonebundles inline in case repositories are
9389 accessed over SSH. This avoids having to setup an external HTTPS server
9390 and results in the same access control as already present for the SSH
9391 setup.
9392 Inline clonebundles should be placed into the .hg/bundle-cache direc‐
9394 tory. A clonebundle at .hg/bundle-cache/mybundle.bundle is referred to
9395 in the clonebundles.manifest file as peer-bundle-cache://mybundle.bun‐
9396 dle.
9397 auto-generation of clone bundles
9399 It is possible to set Mercurial to automatically re-generate clone bun‐
9400 dles when enough new content is available.
9401 Mercurial will take care of the process asynchronously. The defined
9403 list of bundle-type will be generated, uploaded, and advertised. Older
9404 bundles will get decommissioned as newer ones replace them.
9405 Bundles Generation:
9407 The extension can generate multiple variants of the clone bundle. Each
9408 different variant will be defined by the "bundle-spec" they use:
9409 [clone-bundles]
9411 auto-generate.formats= zstd-v2, gzip-v2
9412 See hg help bundlespec for details about available options.
9414 By default, new bundles are generated when 5% of the repository con‐
9416 tents or at least 1000 revisions are not contained in the cached bun‐
9417 dles. This option can be controlled by the clone-bundles.trigger.be‐
9418 low-bundled-ratio option (default 0.95) and the clone-bundles.trig‐
9419 ger.revs option (default 1000):
9420 [clone-bundles]
9422 trigger.below-bundled-ratio=0.95
9423 trigger.revs=1000
9424 This logic can be manually triggered using the admin::clone-bundles-re‐
9426 fresh command, or automatically on each repository change if clone-bun‐
9427 dles.auto-generate.on-change is set to yes:
9428 [clone-bundles]
9430 auto-generate.on-change=yes
9431 auto-generate.formats= zstd-v2, gzip-v2
9432 Automatic Inline serving
9434 The simplest way to serve the generated bundle is through the Mercurial
9435 protocol. However it is not the most efficient as request will still be
9436 served by that main server. It is useful in case where authentication
9437 is complexe or when an efficient mirror system is already in use any‐
9438 way. See the inline clonebundles section above for details about inline
9439 clonebundles
9440 To automatically serve generated bundle through inline clonebundle,
9442 simply set the following option:
9443 auto-generate.serve-inline=yes
9445 Enabling this option disable the managed upload and serving explained
9447 below.
9448 Bundles Upload and Serving:
9450 This is the most efficient way to serve automatically generated clone
9451 bundles, but requires some setup.
9452 The generated bundles need to be made available to users through a
9454 "public" URL. This should be donne through clone-bundles.upload-com‐
9455 mand configuration. The value of this command should be a shell com‐
9456 mand. It will have access to the bundle file path through the
9457 $HGCB_BUNDLE_PATH variable. And the expected basename in the "public"
9458 URL is accessible at:
9459 [clone-bundles]
9461 upload-command=sftp put $HGCB_BUNDLE_PATH sftp://bundles.host/clone-bundles/$HGCB_BUNDLE_BASENAME
9462 If the file was already uploaded, the command must still succeed.
9464 After upload, the file should be available at an url defined by
9466 clone-bundles.url-template.
9467 [clone-bundles] url-template=https://bundles.host/cache/clone-bun‐
9469 dles/{basename}
9470 Old bundles cleanup:
9472 When new bundles are generated, the older ones are no longer necessary
9473 and can be removed from storage. This is done through the clone-bun‐
9474 dles.delete-command configuration. The command is given the url of the
9475 artifact to delete through the $HGCB_BUNDLE_URL environment variable.
9476 [clone-bundles] delete-command=sftp rm sftp://bun‐
9478 dles.host/clone-bundles/$HGCB_BUNDLE_BASENAME
9479 If the file was already deleted, the command must still succeed.
9481 Commands
9483 Uncategorized commands
9484 admin::clone-bundles-clear
9485 remove existing clone bundle caches:
9486 hg admin::clone-bundles-clear
9488 See hg help admin::clone-bundles-refresh for details on how to regener‐
9490 ate them.
9491 This command will only affect bundles currently available, it will not
9493 affect bundles being asynchronously generated.
9494 admin::clone-bundles-refresh
9496 generate clone bundles according to the configuration:
9497 hg admin::clone-bundles-refresh
9499 This runs the logic for automatic generation, removing outdated bundles
9501 and generating new ones if necessary. See hg help -e clone-bundles for
9502 details about how to configure this feature.
9503 Options:
9505 --background
9507 start bundle generation in the background
9508 closehead
9510 close arbitrary heads without checking them out first
9511 Commands
9513 Change manipulation
9514 close-head
9515 close the given head revisions:
9516 hg close-head [OPTION]... [REV]...
9518 This is equivalent to checking out each revision in a clean tree and
9520 running hg commit --close-branch, except that it doesn't change the
9521 working directory.
9522 The commit message must be specified with -l or -m.
9524 Options:
9526 -m,--message <TEXT>
9528 use text as commit message
9529 -l,--logfile <FILE>
9531 read commit message from file
9532 -d,--date <DATE>
9534 record the specified date as commit date
9535 -u,--user <USER>
9537 record the specified user as committer
9538 -r,--rev <REV[+]>
9540 revision to check
9541 [+] marked option can be specified multiple times
9543 aliases: close-heads
9545 commitextras
9547 adds a new flag extras to commit (ADVANCED)
9548 convert
9550 import revisions from foreign VCS repositories into Mercurial
9551 Commands
9553 Uncategorized commands
9554 convert
9555 convert a foreign SCM repository to a Mercurial one.:
9556 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
9558 Accepted source formats [identifiers]:
9560 • Mercurial [hg]
9562 • CVS [cvs]
9564 • Darcs [darcs]
9566 • git [git]
9568 • Subversion [svn]
9570 • Monotone [mtn]
9572 • GNU Arch [gnuarch]
9574 • Bazaar [bzr]
9576 • Perforce [p4]
9578 Accepted destination formats [identifiers]:
9580 • Mercurial [hg]
9582 • Subversion [svn] (history on branches is not preserved)
9584 If no revision is given, all revisions will be converted. Otherwise,
9586 convert will only import up to the named revision (given in a format
9587 understood by the source).
9588 If no destination directory name is specified, it defaults to the base‐
9590 name of the source with -hg appended. If the destination repository
9591 doesn't exist, it will be created.
9592 By default, all sources except Mercurial will use --branchsort. Mercu‐
9594 rial uses --sourcesort to preserve original revision numbers order.
9595 Sort modes have the following effects:
9596 --branchsort
9598 convert from parent to child revision when possible, which means
9599 branches are usually converted one after the other. It generates
9600 more compact repositories.
9601 --datesort
9603 sort revisions by date. Converted repositories have good-looking
9604 changelogs but are often an order of magnitude larger than the
9605 same ones generated by --branchsort.
9606 --sourcesort
9608 try to preserve source revisions order, only supported by Mercu‐
9609 rial sources.
9610 --closesort
9612 try to move closed revisions as close as possible to parent
9613 branches, only supported by Mercurial sources.
9614 If REVMAP isn't given, it will be put in a default location
9616 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
9617 maps each source commit ID to the destination ID for that revision,
9618 like so:
9619 <source ID> <destination ID>
9621 If the file doesn't exist, it's automatically created. It's updated on
9623 each commit copied, so hg convert can be interrupted and can be run re‐
9624 peatedly to copy new commits.
9625 The authormap is a simple text file that maps each source commit author
9627 to a destination commit author. It is handy for source SCMs that use
9628 unix logins to identify authors (e.g.: CVS). One line per author map‐
9629 ping and the line format is:
9630 source author = destination author
9632 Empty lines and lines starting with a # are ignored.
9634 The filemap is a file that allows filtering and remapping of files and
9636 directories. Each line can contain one of the following directives:
9637 include path/to/file-or-dir
9639 exclude path/to/file-or-dir
9641 rename path/to/source path/to/destination
9643 Comment lines start with #. A specified path matches if it equals the
9645 full relative name of a file or one of its parent directories. The in‐
9646 clude or exclude directive with the longest matching path applies, so
9647 line order does not matter.
9648 The include directive causes a file, or all files under a directory, to
9650 be included in the destination repository. The default if there are no
9651 include statements is to include everything. If there are any include
9652 statements, nothing else is included. The exclude directive causes
9653 files or directories to be omitted. The rename directive renames a file
9654 or directory if it is converted. To rename from a subdirectory into the
9655 root of the repository, use . as the path to rename to.
9656 --full will make sure the converted changesets contain exactly the
9658 right files with the right content. It will make a full conversion of
9659 all files, not just the ones that have changed. Files that already are
9660 correct will not be changed. This can be used to apply filemap changes
9661 when converting incrementally. This is currently only supported for
9662 Mercurial and Subversion.
9663 The splicemap is a file that allows insertion of synthetic history,
9665 letting you specify the parents of a revision. This is useful if you
9666 want to e.g. give a Subversion merge two parents, or graft two discon‐
9667 nected series of history together. Each entry contains a key, followed
9668 by a space, followed by one or two comma-separated values:
9669 key parent1, parent2
9671 The key is the revision ID in the source revision control system whose
9673 parents should be modified (same format as a key in .hg/shamap). The
9674 values are the revision IDs (in either the source or destination revi‐
9675 sion control system) that should be used as the new parents for that
9676 node. For example, if you have merged "release-1.0" into "trunk", then
9677 you should specify the revision on "trunk" as the first parent and the
9678 one on the "release-1.0" branch as the second.
9679 The branchmap is a file that allows you to rename a branch when it is
9681 being brought in from whatever external repository. When used in con‐
9682 junction with a splicemap, it allows for a powerful combination to help
9683 fix even the most badly mismanaged repositories and turn them into
9684 nicely structured Mercurial repositories. The branchmap contains lines
9685 of the form:
9686 original_branch_name new_branch_name
9688 where "original_branch_name" is the name of the branch in the source
9690 repository, and "new_branch_name" is the name of the branch is the des‐
9691 tination repository. No whitespace is allowed in the new branch name.
9692 This can be used to (for instance) move code in one repository from
9693 "default" to a named branch.
9694 Mercurial Source
9696 The Mercurial source recognizes the following configuration options,
9697 which you can set on the command line with --config:
9698 convert.hg.ignoreerrors
9700 ignore integrity errors when reading. Use it to fix Mercurial
9701 repositories with missing revlogs, by converting from and to
9702 Mercurial. Default is False.
9703 convert.hg.saverev
9705 store original revision ID in changeset (forces target IDs to
9706 change). It takes a boolean argument and defaults to False.
9707 convert.hg.startrev
9709 specify the initial Mercurial revision. The default is 0.
9710 convert.hg.revs
9712 revset specifying the source revisions to convert.
9713 Bazaar Source
9715 The following options can be used with --config:
9716 convert.bzr.saverev
9718 whether to store the original Bazaar commit ID in the metadata
9719 of the destination commit. The default is True.
9720 CVS Source
9722 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to in‐
9723 dicate the starting point of what will be converted. Direct access to
9724 the repository files is not needed, unless of course the repository is
9725 :local:. The conversion uses the top level directory in the sandbox to
9726 find the CVS repository, and then uses CVS rlog commands to find files
9727 to convert. This means that unless a filemap is given, all files under
9728 the starting directory will be converted, and that any directory reor‐
9729 ganization in the CVS sandbox is ignored.
9730 The following options can be used with --config:
9732 convert.cvsps.cache
9734 Set to False to disable remote log caching, for testing and de‐
9735 bugging purposes. Default is True.
9736 convert.cvsps.fuzz
9738 Specify the maximum time (in seconds) that is allowed between
9739 commits with identical user and log message in a single change‐
9740 set. When very large files were checked in as part of a change‐
9741 set then the default may not be long enough. The default is 60.
9742 convert.cvsps.logencoding
9744 Specify encoding name to be used for transcoding CVS log mes‐
9745 sages. Multiple encoding names can be specified as a list (see
9746 hg help config.Syntax), but only the first acceptable encoding
9747 in the list is used per CVS log entries. This transcoding is ex‐
9748 ecuted before cvslog hook below.
9749 convert.cvsps.mergeto
9751 Specify a regular expression to which commit log messages are
9752 matched. If a match occurs, then the conversion process will in‐
9753 sert a dummy revision merging the branch on which this log mes‐
9754 sage occurs to the branch indicated in the regex. Default is
9755 {{mergetobranch ([-\w]+)}}
9756 convert.cvsps.mergefrom
9758 Specify a regular expression to which commit log messages are
9759 matched. If a match occurs, then the conversion process will add
9760 the most recent revision on the branch indicated in the regex as
9761 the second parent of the changeset. Default is {{mergefrombranch
9762 ([-\w]+)}}
9763 convert.localtimezone
9765 use local time (as determined by the TZ environment variable)
9766 for changeset date/times. The default is False (use UTC).
9767 hooks.cvslog
9769 Specify a Python function to be called at the end of gathering
9770 the CVS log. The function is passed a list with the log entries,
9771 and can modify the entries in-place, or add or delete them.
9772 hooks.cvschangesets
9774 Specify a Python function to be called after the changesets are
9775 calculated from the CVS log. The function is passed a list with
9776 the changeset entries, and can modify the changesets in-place,
9777 or add or delete them.
9778 An additional "debugcvsps" Mercurial command allows the builtin change‐
9780 set merging code to be run without doing a conversion. Its parameters
9781 and output are similar to that of cvsps 2.1. Please see the command
9782 help for more details.
9783 Subversion Source
9785 Subversion source detects classical trunk/branches/tags layouts. By
9786 default, the supplied svn://repo/path/ source URL is converted as a
9787 single branch. If svn://repo/path/trunk exists it replaces the default
9788 branch. If svn://repo/path/branches exists, its subdirectories are
9789 listed as possible branches. If svn://repo/path/tags exists, it is
9790 looked for tags referencing converted branches. Default trunk, branches
9791 and tags values can be overridden with following options. Set them to
9792 paths relative to the source URL, or leave them blank to disable auto
9793 detection.
9794 The following options can be set with --config:
9796 convert.svn.branches
9798 specify the directory containing branches. The default is
9799 branches.
9800 convert.svn.tags
9802 specify the directory containing tags. The default is tags.
9803 convert.svn.trunk
9805 specify the name of the trunk branch. The default is trunk.
9806 convert.localtimezone
9808 use local time (as determined by the TZ environment variable)
9809 for changeset date/times. The default is False (use UTC).
9810 Source history can be retrieved starting at a specific revision, in‐
9812 stead of being integrally converted. Only single branch conversions are
9813 supported.
9814 convert.svn.startrev
9816 specify start Subversion revision number. The default is 0.
9817 Git Source
9819 The Git importer converts commits from all reachable branches (refs in
9820 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
9821 are converted to bookmarks with the same name, with the leading
9822 'refs/heads' stripped. Git submodules are converted to Git subrepos in
9823 Mercurial.
9824 The following options can be set with --config:
9826 convert.git.similarity
9828 specify how similar files modified in a commit must be to be im‐
9829 ported as renames or copies, as a percentage between 0 (dis‐
9830 abled) and 100 (files must be identical). For example, 90 means
9831 that a delete/add pair will be imported as a rename if more than
9832 90% of the file hasn't changed. The default is 50.
9833 convert.git.findcopiesharder
9835 while detecting copies, look at all files in the working copy
9836 instead of just changed ones. This is very expensive for large
9837 projects, and is only effective when convert.git.similarity is
9838 greater than 0. The default is False.
9839 convert.git.renamelimit
9841 perform rename and copy detection up to this many changed files
9842 in a commit. Increasing this will make rename and copy detection
9843 more accurate but will significantly slow down computation on
9844 large projects. The option is only relevant if convert.git.simi‐
9845 larity is greater than 0. The default is 400.
9846 convert.git.committeractions
9848 list of actions to take when processing author and committer
9849 values.
9850 Git commits have separate author (who wrote the commit) and com‐
9852 mitter (who applied the commit) fields. Not all destinations
9853 support separate author and committer fields (including Mercu‐
9854 rial). This config option controls what to do with these author
9855 and committer fields during conversion.
9856 A value of messagedifferent will append a committer: ... line
9858 to the commit message if the Git committer is different from the
9859 author. The prefix of that line can be specified using the syn‐
9860 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
9861 ter:. When a prefix is specified, a space will always be in‐
9862 serted between the prefix and the value.
9863 messagealways behaves like messagedifferent except it will al‐
9865 ways result in a committer: ... line being appended to the com‐
9866 mit message. This value is mutually exclusive with messagedif‐
9867 ferent.
9868 dropcommitter will remove references to the committer. Only ref‐
9870 erences to the author will remain. Actions that add references
9871 to the committer will have no effect when this is set.
9872 replaceauthor will replace the value of the author field with
9874 the committer. Other actions that add references to the commit‐
9875 ter will still take effect when this is set.
9876 The default is messagedifferent.
9878 convert.git.extrakeys
9880 list of extra keys from commit metadata to copy to the destina‐
9881 tion. Some Git repositories store extra metadata in commits. By
9882 default, this non-default metadata will be lost during conver‐
9883 sion. Setting this config option can retain that metadata. Some
9884 built-in keys such as parent and branch are not allowed to be
9885 copied.
9886 convert.git.remoteprefix
9888 remote refs are converted as bookmarks with convert.git.re‐
9889 moteprefix as a prefix followed by a /. The default is 'remote'.
9890 convert.git.saverev
9892 whether to store the original Git commit ID in the metadata of
9893 the destination commit. The default is True.
9894 convert.git.skipsubmodules
9896 does not convert root level .gitmodules files or files with
9897 160000 mode indicating a submodule. Default is False.
9898 Perforce Source
9900 The Perforce (P4) importer can be given a p4 depot path or a client
9901 specification as source. It will convert all files in the source to a
9902 flat Mercurial repository, ignoring labels, branches and integrations.
9903 Note that when a depot path is given you then usually should specify a
9904 target directory, because otherwise the target may be named ...-hg.
9905 The following options can be set with --config:
9907 convert.p4.encoding
9909 specify the encoding to use when decoding standard output of the
9910 Perforce command line tool. The default is default system encod‐
9911 ing.
9912 convert.p4.startrev
9914 specify initial Perforce revision (a Perforce changelist num‐
9915 ber).
9916 Mercurial Destination
9918 The Mercurial destination will recognize Mercurial subrepositories in
9919 the destination directory, and update the .hgsubstate file automati‐
9920 cally if the destination subrepositories contain the
9921 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
9922 tories requires converting a single repository at a time, from the bot‐
9923 tom up.
9924 An example showing how to convert a repository with subrepositories:
9926 # so convert knows the type when it sees a non empty destination
9928 $ hg init converted
9929 $ hg convert orig/sub1 converted/sub1
9931 $ hg convert orig/sub2 converted/sub2
9932 $ hg convert orig converted
9933 The following options are supported:
9935 convert.hg.clonebranches
9937 dispatch source branches in separate clones. The default is
9938 False.
9939 convert.hg.tagsbranch
9941 branch name for tag revisions, defaults to default.
9942 convert.hg.usebranchnames
9944 preserve branch names. The default is True.
9945 convert.hg.sourcename
9947 records the given string as a 'convert_source' extra value on
9948 each commit made in the target repository. The default is None.
9949 convert.hg.preserve-hash
9951 only works with mercurial sources. Make convert prevent perfor‐
9952 mance improvement to the list of modified files in commits when
9953 such an improvement would cause the hash of a commit to change.
9954 The default is False.
9955 All Destinations
9957 All destination types accept the following options:
9958 convert.skiptags
9960 does not convert tags from the source repo to the target repo.
9961 The default is False.
9962 Subversion Destination
9964 Original commit dates are not preserved by default.
9965 convert.svn.dangerous-set-commit-dates
9967 preserve original commit dates, forcefully setting svn:date re‐
9968 vision properties. This option is DANGEROUS and may break some
9969 subversion functionality for the resulting repository (e.g. fil‐
9970 tering revisions with date ranges in svn log), as original com‐
9971 mit dates are not guaranteed to be monotonically increasing.
9972 For commit dates setting to work destination repository must have
9974 pre-revprop-change hook configured to allow setting of svn:date revi‐
9975 sion properties. See Subversion documentation for more details.
9976 Options:
9978 --authors <FILE>
9980 username mapping filename (DEPRECATED) (use --authormap instead)
9981 -s,--source-type <TYPE>
9983 source repository type
9984 -d,--dest-type <TYPE>
9986 destination repository type
9987 -r,--rev <REV[+]>
9989 import up to source revision REV
9990 -A,--authormap <FILE>
9992 remap usernames using this file
9993 --filemap <FILE>
9995 remap file names using contents of file
9996 --full apply filemap changes by converting all files again
9998 --splicemap <FILE>
10000 splice synthesized history into place
10001 --branchmap <FILE>
10003 change branch names while converting
10004 --branchsort
10006 try to sort changesets by branches
10007 --datesort
10009 try to sort changesets by date
10010 --sourcesort
10012 preserve source changesets order
10013 --closesort
10015 try to reorder closed revisions
10016 [+] marked option can be specified multiple times
10018 eol
10020 automatically manage newlines in repository files
10021 This extension allows you to manage the type of line endings (CRLF or
10023 LF) that are used in the repository and in the local working directory.
10024 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
10025 thereby letting everybody use their OS native line endings.
10026 The extension reads its configuration from a versioned .hgeol configu‐
10028 ration file found in the root of the working directory. The .hgeol file
10029 use the same syntax as all other Mercurial configuration files. It uses
10030 two sections, [patterns] and [repository].
10031 The [patterns] section specifies how line endings should be converted
10033 between the working directory and the repository. The format is speci‐
10034 fied by a file pattern. The first match is used, so put more specific
10035 patterns first. The available line endings are LF, CRLF, and BIN.
10036 Files with the declared format of CRLF or LF are always checked out and
10038 stored in the repository in that format and files declared to be binary
10039 (BIN) are left unchanged. Additionally, native is an alias for checking
10040 out in the platform's default line ending: LF on Unix (including Mac OS
10041 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
10042 Mercurial's default behavior; it is only needed if you need to override
10043 a later, more general pattern.
10044 The optional [repository] section specifies the line endings to use for
10046 files stored in the repository. It has a single setting, native, which
10047 determines the storage line endings for files declared as native in the
10048 [patterns] section. It can be set to LF or CRLF. The default is LF. For
10049 example, this means that on Windows, files configured as native (CRLF
10050 by default) will be converted to LF when stored in the repository.
10051 Files declared as LF, CRLF, or BIN in the [patterns] section are always
10052 stored as-is in the repository.
10053 Example versioned .hgeol file:
10055 [patterns]
10057 **.py = native
10058 **.vcproj = CRLF
10059 **.txt = native
10060 Makefile = LF
10061 **.jpg = BIN
10062 [repository]
10064 native = LF
10065 Note The rules will first apply when files are touched in the working
10067 directory, e.g. by updating to null and back to tip to touch all
10068 files.
10069 The extension uses an optional [eol] section read from both the normal
10071 Mercurial configuration files and the .hgeol file, with the latter
10072 overriding the former. You can use that section to control the overall
10073 behavior. There are three settings:
10074 • eol.native (default os.linesep) can be set to LF or CRLF to override
10076 the default interpretation of native for checkout. This can be used
10077 with hg archive on Unix, say, to generate an archive where files have
10078 line endings for Windows.
10079 • eol.only-consistent (default True) can be set to False to make the
10081 extension convert files with inconsistent EOLs. Inconsistent means
10082 that there is both CRLF and LF present in the file. Such files are
10083 normally not touched under the assumption that they have mixed EOLs
10084 on purpose.
10085 • eol.fix-trailing-newline (default False) can be set to True to ensure
10087 that converted files end with a EOL character (either \n or \r\n as
10088 per the configured patterns).
10089 The extension provides cleverencode: and cleverdecode: filters like the
10091 deprecated win32text extension does. This means that you can disable
10092 win32text and enable eol and your filters will still work. You only
10093 need to these filters until you have prepared a .hgeol file.
10094 The win32text.forbid* hooks provided by the win32text extension have
10096 been unified into a single hook named eol.checkheadshook. The hook will
10097 lookup the expected line endings from the .hgeol file, which means you
10098 must migrate to a .hgeol file first before using the hook. eol.check‐
10099 headshook only checks heads, intermediate invalid revisions will be
10100 pushed. To forbid them completely, use the eol.checkallhook hook. These
10101 hooks are best used as pretxnchangegroup hooks.
10102 See hg help patterns for more information about the glob patterns used.
10104 extdiff
10106 command to allow external programs to compare revisions
10107 The extdiff Mercurial extension allows you to use external programs to
10109 compare revisions, or revision with working directory. The external
10110 diff programs are called with a configurable set of options and two
10111 non-option arguments: paths to directories containing snapshots of
10112 files to compare.
10113 If there is more than one file being compared and the "child" revision
10115 is the working directory, any modifications made in the external diff
10116 program will be copied back to the working directory from the temporary
10117 directory.
10118 The extdiff extension also allows you to configure new diff commands,
10120 so you do not need to type hg extdiff -p kdiff3 always.
10121 [extdiff]
10123 # add new command that runs GNU diff(1) in 'context diff' mode
10124 cdiff = gdiff -Nprc5
10125 ## or the old way:
10126 #cmd.cdiff = gdiff
10127 #opts.cdiff = -Nprc5
10128 # add new command called meld, runs meld (no need to name twice). If
10130 # the meld executable is not available, the meld tool in [merge-tools]
10131 # will be used, if available
10132 meld =
10133 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
10135 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
10136 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
10137 # your .vimrc
10138 vimdiff = gvim -f "+next" \
10139 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
10140 Tool arguments can include variables that are expanded at runtime:
10142 $parent1, $plabel1 - filename, descriptive label of first parent
10144 $child, $clabel - filename, descriptive label of child revision
10145 $parent2, $plabel2 - filename, descriptive label of second parent
10146 $root - repository root
10147 $parent is an alias for $parent1.
10148 The extdiff extension will look in your [diff-tools] and [merge-tools]
10150 sections for diff tool arguments, when none are specified in [extdiff].
10151 [extdiff]
10153 kdiff3 =
10154 [diff-tools]
10156 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
10157 If a program has a graphical interface, it might be interesting to tell
10159 Mercurial about it. It will prevent the program from being mistakenly
10160 used in a terminal-only environment (such as an SSH terminal session),
10161 and will make hg extdiff --per-file open multiple file diffs at once
10162 instead of one by one (if you still want to open file diffs one by one,
10163 you can use the --confirm option).
10164 Declaring that a tool has a graphical interface can be done with the
10166 gui flag next to where diffargs are specified:
10167 [diff-tools]
10169 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
10170 kdiff3.gui = true
10171 You can use -I/-X and list of file or directory names like normal hg
10173 diff command. The extdiff extension makes snapshots of only needed
10174 files, so running the external diff program will actually be pretty
10175 fast (at least faster than having to compare the entire tree).
10176 Commands
10178 File content management
10179 extdiff
10180 use external program to diff repository (or selected files):
10181 hg extdiff [OPT]... [FILE]...
10183 Show differences between revisions for the specified files, using an
10185 external program. The default program used is diff, with default op‐
10186 tions "-Npru".
10187 To select a different program, use the -p/--program option. The program
10189 will be passed the names of two directories to compare, unless the
10190 --per-file option is specified (see below). To pass additional options
10191 to the program, use -o/--option. These will be passed before the names
10192 of the directories or files to compare.
10193 The --from, --to, and --change options work the same way they do for hg
10195 diff.
10196 The --per-file option runs the external program repeatedly on each file
10198 to diff, instead of once on two directories. By default, this happens
10199 one by one, where the next file diff is open in the external program
10200 only once the previous external program (for the previous file diff)
10201 has exited. If the external program has a graphical interface, it can
10202 open all the file diffs at once instead of one by one. See hg help -e
10203 extdiff for information about how to tell Mercurial that a given pro‐
10204 gram has a graphical interface.
10205 The --confirm option will prompt the user before each invocation of the
10207 external program. It is ignored if --per-file isn't specified.
10208 Options:
10210 -p,--program <CMD>
10212 comparison program to run
10213 -o,--option <OPT[+]>
10215 pass option to comparison program
10216 -r,--rev <REV[+]>
10218 revision (DEPRECATED)
10219 --from <REV1>
10221 revision to diff from
10222 --to <REV2>
10224 revision to diff to
10225 -c,--change <REV>
10227 change made by revision
10228 --per-file
10230 compare each file instead of revision snapshots
10231 --confirm
10233 prompt user before each external program invocation
10234 --patch
10236 compare patches for two revisions
10237 -I,--include <PATTERN[+]>
10239 include names matching the given patterns
10240 -X,--exclude <PATTERN[+]>
10242 exclude names matching the given patterns
10243 -S, --subrepos
10245 recurse into subrepositories
10246 [+] marked option can be specified multiple times
10248 factotum
10250 http authentication with factotum
10251 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
10253 platforms to provide authentication information for HTTP access. Con‐
10254 figuration entries specified in the auth section as well as authentica‐
10255 tion information provided in the repository URL are fully supported. If
10256 no prefix is specified, a value of "*" will be assumed.
10257 By default, keys are specified as:
10259 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
10261 If the factotum extension is unable to read the required key, one will
10263 be requested interactively.
10264 A configuration section is available to customize runtime behavior. By
10266 default, these entries are:
10267 [factotum]
10269 executable = /bin/auth/factotum
10270 mountpoint = /mnt/factotum
10271 service = hg
10272 The executable entry defines the full path to the factotum binary. The
10274 mountpoint entry defines the path to the factotum file service. Lastly,
10275 the service entry controls the service name used when reading keys.
10276 fastannotate
10278 yet another annotate implementation that might be faster (EXPERIMENTAL)
10279 The fastannotate extension provides a 'fastannotate' command that makes
10281 use of the linelog data structure as a cache layer and is expected to
10282 be faster than the vanilla 'annotate' if the cache is present.
10283 In most cases, fastannotate requires a setup that mainbranch is some
10285 pointer that always moves forward, to be most efficient.
10286 Using fastannotate together with linkrevcache would speed up building
10288 the annotate cache greatly. Run "debugbuildlinkrevcache" before "debug‐
10289 buildannotatecache".
10290 [fastannotate]
10292 # specify the main branch head. the internal linelog will only contain
10293 # the linear (ignoring p2) "mainbranch". since linelog cannot move
10294 # backwards without a rebuild, this should be something that always moves
10295 # forward, usually it is "master" or "@".
10296 mainbranch = master
10297 # fastannotate supports different modes to expose its feature.
10299 # a list of combination:
10300 # - fastannotate: expose the feature via the "fastannotate" command which
10301 # deals with everything in a most efficient way, and provides extra
10302 # features like --deleted etc.
10303 # - fctx: replace fctx.annotate implementation. note:
10304 # a. it is less efficient than the "fastannotate" command
10305 # b. it will make it practically impossible to access the old (disk
10306 # side-effect free) annotate implementation
10307 # c. it implies "hgweb".
10308 # - hgweb: replace hgweb's annotate implementation. conflict with "fctx".
10309 # (default: fastannotate)
10310 modes = fastannotate
10311 # default format when no format flags are used (default: number)
10313 defaultformat = changeset, user, date
10314 # serve the annotate cache via wire protocol (default: False)
10316 # tip: the .hg/fastannotate directory is portable - can be rsynced
10317 server = True
10318 # build annotate cache on demand for every client request (default: True)
10320 # disabling it could make server response faster, useful when there is a
10321 # cronjob building the cache.
10322 serverbuildondemand = True
10323 # update local annotate cache from remote on demand
10325 client = False
10326 # path to use when connecting to the remote server (default: default)
10328 remotepath = default
10329 # minimal length of the history of a file required to fetch linelog from
10331 # the server. (default: 10)
10332 clientfetchthreshold = 10
10333 # for "fctx" mode, always follow renames regardless of command line option.
10335 # this is a BC with the original command but will reduced the space needed
10336 # for annotate cache, and is useful for client-server setup since the
10337 # server will only provide annotate cache with default options (i.e. with
10338 # follow). do not affect "fastannotate" mode. (default: True)
10339 forcefollow = True
10340 # for "fctx" mode, always treat file as text files, to skip the "isbinary"
10342 # check. this is consistent with the "fastannotate" command and could help
10343 # to avoid a file fetch if remotefilelog is used. (default: True)
10344 forcetext = True
10345 # use unfiltered repo for better performance.
10347 unfilteredrepo = True
10348 # sacrifice correctness in some corner cases for performance. it does not
10350 # affect the correctness of the annotate cache being built. the option
10351 # is experimental and may disappear in the future (default: False)
10352 perfhack = True
10353 Commands
10355 Uncategorized commands
10356 fastexport
10357 export repositories as git fast-import stream
10358 Commands
10360 Change import/export
10361 fastexport
10362 export repository as git fast-import stream:
10363 hg fastexport [OPTION]... [REV]...
10365 This command lets you dump a repository as a human-readable text
10367 stream. It can be piped into corresponding import routines like "git
10368 fast-import". Incremental dumps can be created by using marks files.
10369 Options:
10371 -r,--rev <REV[+]>
10373 revisions to export
10374 -i,--import-marks <FILE>
10376 old marks file to read
10377 -e,--export-marks <FILE>
10379 new marks file to write
10380 -A,--authormap <FILE>
10382 remap usernames using this file
10383 [+] marked option can be specified multiple times
10385 fetch
10387 pull, update and merge in one command (DEPRECATED)
10388 Commands
10390 Remote repository management
10391 fetch
10392 pull changes from a remote repository, merge new changes if needed.:
10393 hg fetch [SOURCE]
10395 This finds all changes from the repository at the specified path or URL
10397 and adds them to the local repository.
10398 If the pulled changes add a new branch head, the head is automatically
10400 merged, and the result of the merge is committed. Otherwise, the work‐
10401 ing directory is updated to include the new changes.
10402 When a merge is needed, the working directory is first updated to the
10404 newly pulled changes. Local changes are then merged into the pulled
10405 changes. To switch the merge order, use --switch-parent.
10406 See hg help dates for a list of formats valid for -d/--date.
10408 Returns 0 on success.
10410 Options:
10412 -r,--rev <REV[+]>
10414 a specific revision you would like to pull
10415 --edit invoke editor on commit messages
10417 --force-editor
10419 edit commit message (DEPRECATED)
10420 --switch-parent
10422 switch parents when merging
10423 -m,--message <TEXT>
10425 use text as commit message
10426 -l,--logfile <FILE>
10428 read commit message from file
10429 -d,--date <DATE>
10431 record the specified date as commit date
10432 -u,--user <USER>
10434 record the specified user as committer
10435 -e,--ssh <CMD>
10437 specify ssh command to use
10438 --remotecmd <CMD>
10440 specify hg command to run on the remote side
10441 --insecure
10443 do not verify server certificate (ignoring web.cacerts config)
10444 [+] marked option can be specified multiple times
10446 fix
10448 rewrite file content in changesets or working copy (EXPERIMENTAL)
10449 Provides a command that runs configured tools on the contents of modi‐
10451 fied files, writing back any fixes to the working copy or replacing
10452 changesets.
10453 Fixer tools are run in the repository's root directory. This allows
10455 them to read configuration files from the working copy, or even write
10456 to the working copy. The working copy is not updated to match the re‐
10457 vision being fixed. In fact, several revisions may be fixed in paral‐
10458 lel. Writes to the working copy are not amended into the revision being
10459 fixed; fixer tools MUST always read content to be fixed from stdin, and
10460 write fixed file content back to stdout.
10461 Here is an example configuration that causes hg fix to apply automatic
10463 formatting fixes to modified lines in C++ code:
10464 [fix]
10466 clang-format:command=clang-format --assume-filename={rootpath}
10467 clang-format:linerange=--lines={first}:{last}
10468 clang-format:pattern=set:**.cpp or **.hpp
10469 The :command suboption forms the first part of the shell command that
10471 will be used to fix a file. The content of the file is passed on stan‐
10472 dard input, and the fixed file content is expected on standard output.
10473 Any output on standard error will be displayed as a warning. If the
10474 exit status is not zero, the file will not be affected. A placeholder
10475 warning is displayed if there is a non-zero exit status but no standard
10476 error output. Some values may be substituted into the command:
10477 {rootpath} The path of the file being fixed, relative to the repo root
10479 {basename} The name of the file being fixed, without the directory path
10480 If the :linerange suboption is set, the tool will only be run if there
10482 are changed lines in a file. The value of this suboption is appended to
10483 the shell command once for every range of changed lines in the file.
10484 Some values may be substituted into the command:
10485 {first} The 1-based line number of the first line in the modified range
10487 {last} The 1-based line number of the last line in the modified range
10488 Deleted sections of a file will be ignored by :linerange, because there
10490 is no corresponding line range in the version being fixed.
10491 By default, tools that set :linerange will only be executed if there is
10493 at least one changed line range. This is meant to prevent accidents
10494 like running a code formatter in such a way that it unexpectedly refor‐
10495 mats the whole file. If such a tool needs to operate on unchanged
10496 files, it should set the :skipclean suboption to false.
10497 The :pattern suboption determines which files will be passed through
10499 each configured tool. See hg help patterns for possible values. How‐
10500 ever, all patterns are relative to the repo root, even if that text
10501 says they are relative to the current working directory. If there are
10502 file arguments to hg fix, the intersection of these patterns is used.
10503 There is also a configurable limit for the maximum size of file that
10505 will be processed by hg fix:
10506 [fix]
10508 maxfilesize = 2MB
10509 Normally, execution of configured tools will continue after a failure
10511 (indicated by a non-zero exit status). It can also be configured to
10512 abort after the first such failure, so that no files will be affected
10513 if any tool fails. This abort will also cause hg fix to exit with a
10514 non-zero status:
10515 [fix]
10517 failure = abort
10518 When multiple tools are configured to affect a file, they execute in an
10520 order defined by the :priority suboption. The priority suboption has a
10521 default value of zero for each tool. Tools are executed in order of de‐
10522 scending priority. The execution order of tools with equal priority is
10523 unspecified. For example, you could use the 'sort' and 'head' utilities
10524 to keep only the 10 smallest numbers in a text file by ensuring that
10525 'sort' runs before 'head':
10526 [fix]
10528 sort:command = sort -n
10529 head:command = head -n 10
10530 sort:pattern = numbers.txt
10531 head:pattern = numbers.txt
10532 sort:priority = 2
10533 head:priority = 1
10534 To account for changes made by each tool, the line numbers used for in‐
10536 cremental formatting are recomputed before executing the next tool. So,
10537 each tool may see different values for the arguments added by the :lin‐
10538 erange suboption.
10539 Each fixer tool is allowed to return some metadata in addition to the
10541 fixed file content. The metadata must be placed before the file content
10542 on stdout, separated from the file content by a zero byte. The metadata
10543 is parsed as a JSON value (so, it should be UTF-8 encoded and contain
10544 no zero bytes). A fixer tool is expected to produce this metadata en‐
10545 coding if and only if the :metadata suboption is true:
10546 [fix]
10548 tool:command = tool --prepend-json-metadata
10549 tool:metadata = true
10550 The metadata values are passed to hooks, which can be used to print
10552 summaries or perform other post-fixing work. The supported hooks are:
10553 "postfixfile"
10555 Run once for each file in each revision where any fixer tools made changes
10556 to the file content. Provides "$HG_REV" and "$HG_PATH" to identify the file,
10557 and "$HG_METADATA" with a map of fixer names to metadata values from fixer
10558 tools that affected the file. Fixer tools that didn't affect the file have a
10559 value of None. Only fixer tools that executed are present in the metadata.
10560 "postfix"
10562 Run once after all files and revisions have been handled. Provides
10563 "$HG_REPLACEMENTS" with information about what revisions were created and
10564 made obsolete. Provides a boolean "$HG_WDIRWRITTEN" to indicate whether any
10565 files in the working copy were updated. Provides a list "$HG_METADATA"
10566 mapping fixer tool names to lists of metadata values returned from
10567 executions that modified a file. This aggregates the same metadata
10568 previously passed to the "postfixfile" hook.
10569 Commands
10571 File content management
10572 fix
10573 rewrite file content in changesets or working directory:
10574 hg fix [OPTION]... [FILE]...
10576 Runs any configured tools to fix the content of files. (See hg help -e
10578 fix for details about configuring tools.) Only affects files with
10579 changes, unless file arguments are provided. Only affects changed lines
10580 of files, unless the --whole flag is used. Some tools may always affect
10581 the whole file regardless of --whole.
10582 If --working-dir is used, files with uncommitted changes in the working
10584 copy will be fixed. Note that no backup are made.
10585 If revisions are specified with --source, those revisions and their de‐
10587 scendants will be checked, and they may be replaced with new revisions
10588 that have fixed file content. By automatically including the descen‐
10589 dants, no merging, rebasing, or evolution will be required. If an an‐
10590 cestor of the working copy is included, then the working copy itself
10591 will also be fixed, and the working copy will be updated to the fixed
10592 parent.
10593 When determining what lines of each file to fix at each revision, the
10595 whole set of revisions being fixed is considered, so that fixes to ear‐
10596 lier revisions are not forgotten in later ones. The --base flag can be
10597 used to override this default behavior, though it is not usually desir‐
10598 able to do so.
10599 Options:
10601 --all fix all non-public non-obsolete revisions
10603 --base <REV[+]>
10605 revisions to diff against (overrides automatic selection, and
10606 applies to every revision being fixed)
10607 -r,--rev <REV[+]>
10609 revisions to fix (ADVANCED)
10610 -s,--source <REV[+]>
10612 fix the specified revisions and their descendants
10613 -w, --working-dir
10615 fix the working directory
10616 --whole
10618 always fix every line of a file
10619 [+] marked option can be specified multiple times
10621 fsmonitor
10623 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
10624 Integrates the file-watching program Watchman with Mercurial to produce
10626 faster status results.
10627 On a particular Linux system, for a real-world repository with over
10629 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
10630 the same system, with fsmonitor it takes about 0.3 seconds.
10631 fsmonitor requires no configuration -- it will tell Watchman about your
10633 repository as necessary. You'll need to install Watchman from
10634 https://facebook.github.io/watchman/ and make sure it is in your PATH.
10635 fsmonitor is incompatible with the largefiles and eol extensions, and
10637 will disable itself if any of those are active.
10638 The following configuration options exist:
10640 [fsmonitor]
10642 mode = {off, on, paranoid}
10643 When mode = off, fsmonitor will disable itself (similar to not loading
10645 the extension at all). When mode = on, fsmonitor will be enabled (the
10646 default). When mode = paranoid, fsmonitor will query both Watchman and
10647 the filesystem, and ensure that the results are consistent.
10648 [fsmonitor]
10650 timeout = (float)
10651 A value, in seconds, that determines how long fsmonitor will wait for
10653 Watchman to return results. Defaults to 2.0.
10654 [fsmonitor]
10656 blacklistusers = (list of userids)
10657 A list of usernames for which fsmonitor will disable itself altogether.
10659 [fsmonitor]
10661 walk_on_invalidate = (boolean)
10662 Whether or not to walk the whole repo ourselves when our cached state
10664 has been invalidated, for example when Watchman has been restarted or
10665 .hgignore rules have been changed. Walking the repo in that case can
10666 result in competing for I/O with Watchman. For large repos it is recom‐
10667 mended to set this value to false. You may wish to set this to true if
10668 you have a very fast filesystem that can outpace the IPC overhead of
10669 getting the result data for the full repo from Watchman. Defaults to
10670 false.
10671 [fsmonitor]
10673 warn_when_unused = (boolean)
10674 Whether to print a warning during certain operations when fsmonitor
10676 would be beneficial to performance but isn't enabled.
10677 [fsmonitor]
10679 warn_update_file_count = (integer)
10680 # or when mercurial is built with rust support
10681 warn_update_file_count_rust = (integer)
10682 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
10684 be printed during working directory updates if this many files will be
10685 created.
10686 git
10688 grant Mercurial the ability to operate on Git repositories. (EXPERIMEN‐
10689 TAL)
10690 This is currently super experimental. It probably will consume your
10692 firstborn a la Rumpelstiltskin, etc.
10693 githelp
10695 try mapping git commands to Mercurial commands
10696 Tries to map a given git command to a Mercurial command:
10698 $ hg githelp -- git checkout master hg update master
10700 If an unknown command or parameter combination is detected, an error is
10702 produced.
10703 Commands
10705 Help
10706 githelp
10707 suggests the Mercurial equivalent of the given git command:
10708 hg githelp
10710 Usage: hg githelp -- <git command>
10712 aliases: git
10714 gpg
10716 commands to sign and verify changesets
10717 Commands
10719 Signing changes (GPG)
10720 sigcheck
10721 verify all the signatures there may be for a particular revision:
10722 hg sigcheck REV
10724 verify all the signatures there may be for a particular revision
10726 sign
10728 add a signature for the current or given revision:
10729 hg sign [OPTION]... [REV]...
10731 If no revision is given, the parent of the working directory is used,
10733 or tip if no revision is checked out.
10734 The gpg.cmd config setting can be used to specify the command to run. A
10736 default key can be specified with gpg.key.
10737 See hg help dates for a list of formats valid for -d/--date.
10739 Options:
10741 -l, --local
10743 make the signature local
10744 -f, --force
10746 sign even if the sigfile is modified
10747 --no-commit
10749 do not commit the sigfile after signing
10750 -k,--key <ID>
10752 the key id to sign with
10753 -m,--message <TEXT>
10755 use text as commit message
10756 -e, --edit
10758 invoke editor on commit messages
10759 -d,--date <DATE>
10761 record the specified date as commit date
10762 -u,--user <USER>
10764 record the specified user as committer
10765 sigs
10767 list signed changesets:
10768 hg sigs
10770 list signed changesets
10772 graphlog
10774 command to view revision graphs from a shell (DEPRECATED)
10775 The functionality of this extension has been include in core Mercurial
10777 since version 2.3. Please use hg log -G ... instead.
10778 This extension adds a --graph option to the incoming, outgoing and log
10780 commands. When this options is given, an ASCII representation of the
10781 revision graph is also shown.
10782 Commands
10784 Change navigation
10785 glog
10786 show revision history alongside an ASCII revision graph:
10787 hg glog [OPTION]... [FILE]
10789 Print a revision history alongside a revision graph drawn with ASCII
10791 characters.
10792 Nodes printed as an @ character are parents of the working directory.
10794 This is an alias to hg log -G.
10796 Options:
10798 -f, --follow
10800 follow changeset history, or file history across copies and re‐
10801 names
10802 --follow-first
10804 only follow the first parent of merge changesets (DEPRECATED)
10805 -d,--date <DATE>
10807 show revisions matching date spec
10808 -C, --copies
10810 show copied files
10811 -k,--keyword <TEXT[+]>
10813 do case-insensitive search for a given text
10814 -r,--rev <REV[+]>
10816 show the specified revision or revset
10817 --removed
10819 include revisions where files were removed
10820 -m, --only-merges
10822 show only merges (DEPRECATED)
10823 -u,--user <USER[+]>
10825 revisions committed by user
10826 --only-branch <BRANCH[+]>
10828 show only changesets within the given named branch (DEPRECATED)
10829 -b,--branch <BRANCH[+]>
10831 show changesets within the given named branch
10832 -P,--prune <REV[+]>
10834 do not display revision or any of its ancestors
10835 -p, --patch
10837 show patch
10838 -g, --git
10840 use git extended diff format
10841 -l,--limit <NUM>
10843 limit number of changes displayed
10844 -M, --no-merges
10846 do not show merges
10847 --stat output diffstat-style summary of changes
10849 -G, --graph
10851 show the revision DAG
10852 --style <STYLE>
10854 display using template map file (DEPRECATED)
10855 -T,--template <TEMPLATE>
10857 display with template
10858 -I,--include <PATTERN[+]>
10860 include names matching the given patterns
10861 -X,--exclude <PATTERN[+]>
10863 exclude names matching the given patterns
10864 [+] marked option can be specified multiple times
10866 hgk
10868 browse the repository in a graphical way
10869 The hgk extension allows browsing the history of a repository in a
10871 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
10872 distributed with Mercurial.)
10873 hgk consists of two parts: a Tcl script that does the displaying and
10875 querying of information, and an extension to Mercurial named hgk.py,
10876 which provides hooks for hgk to get information. hgk can be found in
10877 the contrib directory, and the extension is shipped in the hgext repos‐
10878 itory, and needs to be enabled.
10879 The hg view command will launch the hgk Tcl script. For this command to
10881 work, hgk must be in your search path. Alternately, you can specify the
10882 path to hgk in your configuration file:
10883 [hgk]
10885 path = /location/of/hgk
10886 hgk can make use of the extdiff extension to visualize revisions. As‐
10888 suming you had already configured extdiff vdiff command, just add:
10889 [hgk]
10891 vdiff=vdiff
10892 Revisions context menu will now display additional entries to fire vd‐
10894 iff on hovered and selected revisions.
10895 Commands
10897 Change navigation
10898 view
10899 start interactive history viewer:
10900 hg view [-l LIMIT] [REVRANGE]
10902 start interactive history viewer
10904 Options:
10906 -l,--limit <NUM>
10908 limit number of changes displayed
10909 Uncategorized commands
10911 highlight
10912 syntax highlighting for hgweb (requires Pygments)
10913 It depends on the Pygments syntax highlighting library:
10915 http://pygments.org/
10916 There are the following configuration options:
10918 [web]
10920 pygments_style = <style> (default: colorful)
10921 highlightfiles = <fileset> (default: size('<5M'))
10922 highlightonlymatchfilename = <bool> (default False)
10923 highlightonlymatchfilename will only highlight files if their type
10925 could be identified by their filename. When this is not enabled (the
10926 default), Pygments will try very hard to identify the file type from
10927 content and any match (even matches with a low confidence score) will
10928 be used.
10929 histedit
10931 interactive history editing
10932 With this extension installed, Mercurial gains one new command: histe‐
10934 dit. Usage is as follows, assuming the following history:
10935 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
10937 | Add delta
10938 |
10939 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
10940 | Add gamma
10941 |
10942 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
10943 | Add beta
10944 |
10945 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10946 Add alpha
10947 If you were to run hg histedit c561b4e977df, you would see the follow‐
10949 ing file open in your editor:
10950 pick c561b4e977df Add beta
10952 pick 030b686bedc4 Add gamma
10953 pick 7c2fd3b9020c Add delta
10954 # Edit history between c561b4e977df and 7c2fd3b9020c
10956 #
10957 # Commits are listed from least to most recent
10958 #
10959 # Commands:
10960 # p, pick = use commit
10961 # e, edit = use commit, but allow edits before making new commit
10962 # f, fold = use commit, but combine it with the one above
10963 # r, roll = like fold, but discard this commit's description and date
10964 # d, drop = remove commit from history
10965 # m, mess = edit commit message without changing commit content
10966 # b, base = checkout changeset and apply further changesets from there
10967 #
10968 In this file, lines beginning with # are ignored. You must specify a
10970 rule for each revision in your history. For example, if you had meant
10971 to add gamma before beta, and then wanted to add delta in the same re‐
10972 vision as beta, you would reorganize the file to look like this:
10973 pick 030b686bedc4 Add gamma
10975 pick c561b4e977df Add beta
10976 fold 7c2fd3b9020c Add delta
10977 # Edit history between c561b4e977df and 7c2fd3b9020c
10979 #
10980 # Commits are listed from least to most recent
10981 #
10982 # Commands:
10983 # p, pick = use commit
10984 # e, edit = use commit, but allow edits before making new commit
10985 # f, fold = use commit, but combine it with the one above
10986 # r, roll = like fold, but discard this commit's description and date
10987 # d, drop = remove commit from history
10988 # m, mess = edit commit message without changing commit content
10989 # b, base = checkout changeset and apply further changesets from there
10990 #
10991 At which point you close the editor and histedit starts working. When
10993 you specify a fold operation, histedit will open an editor when it
10994 folds those revisions together, offering you a chance to clean up the
10995 commit message:
10996 Add beta
10998 ***
10999 Add delta
11000 Edit the commit message to your liking, then close the editor. The date
11002 used for the commit will be the later of the two commits' dates. For
11003 this example, let's assume that the commit message was changed to Add
11004 beta and delta. After histedit has run and had a chance to remove any
11005 old or temporary revisions it needed, the history looks like this:
11006 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
11008 | Add beta and delta.
11009 |
11010 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
11011 | Add gamma
11012 |
11013 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
11014 Add alpha
11015 Note that histedit does not remove any revisions (even its own tempo‐
11017 rary ones) until after it has completed all the editing operations, so
11018 it will probably perform several strip operations when it's done. For
11019 the above example, it had to run strip twice. Strip can be slow depend‐
11020 ing on a variety of factors, so you might need to be a little patient.
11021 You can choose to keep the original revisions by passing the --keep
11022 flag.
11023 The edit operation will drop you back to a command prompt, allowing you
11025 to edit files freely, or even use hg record to commit some changes as a
11026 separate commit. When you're done, any remaining uncommitted changes
11027 will be committed as well. When done, run hg histedit --continue to
11028 finish this step. If there are uncommitted changes, you'll be prompted
11029 for a new commit message, but the default commit message will be the
11030 original message for the edit ed revision, and the date of the original
11031 commit will be preserved.
11032 The message operation will give you a chance to revise a commit message
11034 without changing the contents. It's a shortcut for doing edit immedi‐
11035 ately followed by hg histedit --continue`.
11036 If histedit encounters a conflict when moving a revision (while han‐
11038 dling pick or fold), it'll stop in a similar manner to edit with the
11039 difference that it won't prompt you for a commit message when done. If
11040 you decide at this point that you don't like how much work it will be
11041 to rearrange history, or that you made a mistake, you can use hg histe‐
11042 dit --abort to abandon the new changes you have made and return to the
11043 state before you attempted to edit your history.
11044 If we clone the histedit-ed example repository above and add four more
11046 changes, such that we have the following history:
11047 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
11049 | Add theta
11050 |
11051 o 5 140988835471 2009-04-27 18:04 -0500 stefan
11052 | Add eta
11053 |
11054 o 4 122930637314 2009-04-27 18:04 -0500 stefan
11055 | Add zeta
11056 |
11057 o 3 836302820282 2009-04-27 18:04 -0500 stefan
11058 | Add epsilon
11059 |
11060 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
11061 | Add beta and delta.
11062 |
11063 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
11064 | Add gamma
11065 |
11066 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
11067 Add alpha
11068 If you run hg histedit --outgoing on the clone then it is the same as
11070 running hg histedit 836302820282. If you need plan to push to a reposi‐
11071 tory that Mercurial does not detect to be related to the source repo,
11072 you can add a --force option.
11073 Config
11075 Histedit rule lines are truncated to 80 characters by default. You can
11076 customize this behavior by setting a different length in your configu‐
11077 ration file:
11078 [histedit]
11080 linelen = 120 # truncate rule lines at 120 characters
11081 The summary of a change can be customized as well:
11083 [histedit]
11085 summary-template = '{rev} {bookmarks} {desc|firstline}'
11086 The customized summary should be kept short enough that rule lines will
11088 fit in the configured line length. See above if that requires cus‐
11089 tomization.
11090 hg histedit attempts to automatically choose an appropriate base revi‐
11092 sion to use. To change which base revision is used, define a revset in
11093 your configuration file:
11094 [histedit]
11096 defaultrev = only(.) & draft()
11097 By default each edited revision needs to be present in histedit com‐
11099 mands. To remove revision you need to use drop operation. You can con‐
11100 figure the drop to be implicit for missing commits by adding:
11101 [histedit]
11103 dropmissing = True
11104 By default, histedit will close the transaction after each action. For
11106 performance purposes, you can configure histedit to use a single trans‐
11107 action across the entire histedit. WARNING: This setting introduces a
11108 significant risk of losing the work you've done in a histedit if the
11109 histedit aborts unexpectedly:
11110 [histedit]
11112 singletransaction = True
11113 Commands
11115 Change manipulation
11116 histedit
11117 interactively edit changeset history:
11118 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
11120 This command lets you edit a linear series of changesets (up to and in‐
11122 cluding the working directory, which should be clean). You can:
11123 • pick to [re]order a changeset
11125 • drop to omit changeset
11127 • mess to reword the changeset commit message
11129 • fold to combine it with the preceding changeset (using the later
11131 date)
11132 • roll like fold, but discarding this commit's description and date
11134 • edit to edit this changeset (preserving date)
11136 • base to checkout changeset and apply further changesets from there
11138 There are a number of ways to select the root changeset:
11140 • Specify ANCESTOR directly
11142 • Use --outgoing -- it will be the first linear changeset not included
11144 in destination. (See hg help config.paths.default-push)
11145 • Otherwise, the value from the "histedit.defaultrev" config option is
11147 used as a revset to select the base revision when ANCESTOR is not
11148 specified. The first revision returned by the revset is used. By de‐
11149 fault, this selects the editable history that is unique to the ances‐
11150 try of the working directory.
11151 If you use --outgoing, this command will abort if there are ambiguous
11153 outgoing revisions. For example, if there are multiple branches con‐
11154 taining outgoing revisions.
11155 Use "min(outgoing() and ::.)" or similar revset specification instead
11157 of --outgoing to specify edit target revision exactly in such ambiguous
11158 situation. See hg help revsets for detail about selecting revisions.
11159 Examples:
11161 • A number of changes have been made. Revision 3 is no longer
11163 needed.
11164 Start history editing from revision 3:
11166 hg histedit -r 3
11168 An editor opens, containing the list of revisions, with specific
11170 actions specified:
11171 pick 5339bf82f0ca 3 Zworgle the foobar
11173 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11174 pick 0a9639fcda9d 5 Morgify the cromulancy
11175 Additional information about the possible actions to take appears
11177 below the list of revisions.
11178 To remove revision 3 from the history, its action (at the begin‐
11180 ning of the relevant line) is changed to 'drop':
11181 drop 5339bf82f0ca 3 Zworgle the foobar
11183 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11184 pick 0a9639fcda9d 5 Morgify the cromulancy
11185 • A number of changes have been made. Revision 2 and 4 need to be
11187 swapped.
11188 Start history editing from revision 2:
11190 hg histedit -r 2
11192 An editor opens, containing the list of revisions, with specific
11194 actions specified:
11195 pick 252a1af424ad 2 Blorb a morgwazzle
11197 pick 5339bf82f0ca 3 Zworgle the foobar
11198 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11199 To swap revision 2 and 4, its lines are swapped in the editor:
11201 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11203 pick 5339bf82f0ca 3 Zworgle the foobar
11204 pick 252a1af424ad 2 Blorb a morgwazzle
11205 Returns 0 on success, 1 if user intervention is required (not only for
11207 intentional "edit" command, but also for resolving unexpected con‐
11208 flicts).
11209 Options:
11211 --commands <FILE>
11213 read history edits from the specified file
11214 -c, --continue
11216 continue an edit already in progress
11217 --edit-plan
11219 edit remaining actions list
11220 -k, --keep
11222 don't strip old nodes after edit is complete
11223 --abort
11225 abort an edit in progress
11226 -o, --outgoing
11228 changesets not found in destination
11229 -f, --force
11231 force outgoing even for unrelated repositories
11232 -r,--rev <REV[+]>
11234 first revision to be edited
11235 -T,--template <TEMPLATE>
11237 display with template
11238 [+] marked option can be specified multiple times
11240 hooklib
11242 collection of simple hooks for common tasks (EXPERIMENTAL)
11243 This extension provides a number of simple hooks to handle issues com‐
11245 monly found in repositories with many contributors: - email notifica‐
11246 tion when changesets move from draft to public phase - email notifica‐
11247 tion when changesets are obsoleted - enforcement of draft phase for all
11248 incoming changesets - enforcement of a no-branch-merge policy - en‐
11249 forcement of a no-multiple-heads policy
11250 The implementation of the hooks is subject to change, e.g. whether to
11252 implement them as individual hooks or merge them into the notify exten‐
11253 sion as option. The functionality itself is planned to be supported
11254 long-term.
11255 infinitepush
11257 store some pushes in a remote blob store on the server (EXPERIMEN‐
11258 TAL)
11259 IMPORTANT: if you use this extension, please contact
11261 mercurial-devel@mercurial-scm.org ASAP. This extension is believed to
11262 be unused and barring learning of users of this functionality, we will
11263 delete this code at the end of 2020.
11264 [infinitepush] # Server-side and client-side option. Pattern of the
11266 infinitepush bookmark branchpattern = PATTERN
11267 # Server or client server = False
11269 # Server-side option. Possible values: 'disk' or 'sql'. Fails if not
11271 set indextype = disk
11272 # Server-side option. Used only if indextype=sql. # Format:
11274 'IP:PORT:DB_NAME:USER:PASSWORD' sqlhost = IP:PORT:DB_NAME:USER:PASS‐
11275 WORD
11276 # Server-side option. Used only if indextype=disk. # Filesystem
11278 path to the index store indexpath = PATH
11279 # Server-side option. Possible values: 'disk' or 'external' # Fails
11281 if not set storetype = disk
11282 # Server-side option. # Path to the binary that will save bundle to
11284 the bundlestore # Formatted cmd line will be passed to it (see
11285 put_args) put_binary = put
11286 # Serser-side option. Used only if storetype=external. # Format
11288 cmd-line string for put binary. Placeholder: {filename} put_args =
11289 {filename}
11290 # Server-side option. # Path to the binary that get bundle from the
11292 bundlestore. # Formatted cmd line will be passed to it (see
11293 get_args) get_binary = get
11294 # Serser-side option. Used only if storetype=external. # Format
11296 cmd-line string for get binary. Placeholders: {filename} {handle}
11297 get_args = {filename} {handle}
11298 # Server-side option logfile = FIlE
11300 # Server-side option loglevel = DEBUG
11302 # Server-side option. Used only if indextype=sql. # Sets mysql
11304 wait_timeout option. waittimeout = 300
11305 # Server-side option. Used only if indextype=sql. # Sets mysql inn‐
11307 odb_lock_wait_timeout option. locktimeout = 120
11308 # Server-side option. Used only if indextype=sql. # Name of the
11310 repository reponame = ''
11311 # Client-side option. Used by --list-remote option. List of remote
11313 scratch # patterns to list if no patterns are specified. default‐
11314 remotepatterns = ['*']
11315 # Instructs infinitepush to forward all received bundle2 parts to
11317 the # bundle for storage. Defaults to False. storeallparts = True
11318 # routes each incoming push to the bundlestore. defaults to False
11320 pushtobundlestore = True
11321 [remotenames] # Client-side option # This option should be set only
11323 if remotenames extension is enabled. # Whether remote bookmarks are
11324 tracked by remotenames extension. bookmarks = True
11325 journal
11327 track previous positions of bookmarks (EXPERIMENTAL)
11328 This extension adds a new command: hg journal, which shows you where
11330 bookmarks were previously located.
11331 Commands
11333 Change organization
11334 journal
11335 show the previous position of bookmarks and the working copy:
11336 hg journal [OPTION]... [BOOKMARKNAME]
11338 The journal is used to see the previous commits that bookmarks and the
11340 working copy pointed to. By default the previous locations for the
11341 working copy. Passing a bookmark name will show all the previous posi‐
11342 tions of that bookmark. Use the --all switch to show previous locations
11343 for all bookmarks and the working copy; each line will then include the
11344 bookmark name, or '.' for the working copy, as well.
11345 If name starts with re:, the remainder of the name is treated as a reg‐
11347 ular expression. To match a name that actually starts with re:, use the
11348 prefix literal:.
11349 By default hg journal only shows the commit hash and the command that
11351 was running at that time. -v/--verbose will show the prior hash, the
11352 user, and the time at which it happened.
11353 Use -c/--commits to output log information on each commit hash; at this
11355 point you can use the usual --patch, --git, --stat and --template
11356 switches to alter the log output for these.
11357 hg journal -T json can be used to produce machine readable output.
11359 Options:
11361 --all show history for all names
11363 -c, --commits
11365 show commit metadata
11366 -p, --patch
11368 show patch
11369 -g, --git
11371 use git extended diff format
11372 -l,--limit <NUM>
11374 limit number of changes displayed
11375 --stat output diffstat-style summary of changes
11377 --style <STYLE>
11379 display using template map file (DEPRECATED)
11380 -T,--template <TEMPLATE>
11382 display with template
11383 keyword
11385 expand keywords in tracked files
11386 This extension expands RCS/CVS-like or self-customized $Keywords$ in
11388 tracked text files selected by your configuration.
11389 Keywords are only expanded in local repositories and not stored in the
11391 change history. The mechanism can be regarded as a convenience for the
11392 current user or for archive distribution.
11393 Keywords expand to the changeset data pertaining to the latest change
11395 relative to the working directory parent of each file.
11396 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
11398 sections of hgrc files.
11399 Example:
11401 [keyword]
11403 # expand keywords in every python file except those matching "x*"
11404 **.py =
11405 x* = ignore
11406 [keywordset]
11408 # prefer svn- over cvs-like default keywordmaps
11409 svn = True
11410 Note The more specific you are in your filename patterns the less you
11412 lose speed in huge repositories.
11413 For [keywordmaps] template mapping and expansion demonstration and con‐
11415 trol run hg kwdemo. See hg help templates for a list of available tem‐
11416 plates and filters.
11417 Three additional date template filters are provided:
11419 utcdate
11421 "2006/09/18 15:13:13"
11423 svnutcdate
11425 "2006-09-18 15:13:13Z"
11427 svnisodate
11429 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
11431 The default template mappings (view with hg kwdemo -d) can be replaced
11433 with customized keywords and templates. Again, run hg kwdemo to control
11434 the results of your configuration changes.
11435 Before changing/disabling active keywords, you must run hg kwshrink to
11437 avoid storing expanded keywords in the change history.
11438 To force expansion after enabling it, or a configuration change, run hg
11440 kwexpand.
11441 Expansions spanning more than one line and incremental expansions, like
11443 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
11444 expands to the first line of the changeset description.
11445 Commands
11447 Uncategorized commands
11448 kwdemo
11449 print [keywordmaps] configuration and an expansion example:
11450 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
11452 Show current, custom, or default keyword template maps and their expan‐
11454 sions.
11455 Extend the current configuration by specifying maps as arguments and
11457 using -f/--rcfile to source an external hgrc file.
11458 Use -d/--default to disable current configuration.
11460 See hg help templates for information on templates and filters.
11462 Options:
11464 -d, --default
11466 show default keyword template maps
11467 -f,--rcfile <FILE>
11469 read maps from rcfile
11470 kwexpand
11472 expand keywords in the working directory:
11473 hg kwexpand [OPTION]... [FILE]...
11475 Run after (re)enabling keyword expansion.
11477 kwexpand refuses to run if given files contain local changes.
11479 Options:
11481 -I,--include <PATTERN[+]>
11483 include names matching the given patterns
11484 -X,--exclude <PATTERN[+]>
11486 exclude names matching the given patterns
11487 [+] marked option can be specified multiple times
11489 kwfiles
11491 show files configured for keyword expansion:
11492 hg kwfiles [OPTION]... [FILE]...
11494 List which files in the working directory are matched by the [keyword]
11496 configuration patterns.
11497 Useful to prevent inadvertent keyword expansion and to speed up execu‐
11499 tion by including only files that are actual candidates for expansion.
11500 See hg help keyword on how to construct patterns both for inclusion and
11502 exclusion of files.
11503 With -A/--all and -v/--verbose the codes used to show the status of
11505 files are:
11506 K = keyword expansion candidate
11508 k = keyword expansion candidate (not tracked)
11509 I = ignored
11510 i = ignored (not tracked)
11511 Options:
11513 -A, --all
11515 show keyword status flags of all files
11516 -i, --ignore
11518 show files excluded from expansion
11519 -u, --unknown
11521 only show unknown (not tracked) files
11522 -I,--include <PATTERN[+]>
11524 include names matching the given patterns
11525 -X,--exclude <PATTERN[+]>
11527 exclude names matching the given patterns
11528 [+] marked option can be specified multiple times
11530 kwshrink
11532 revert expanded keywords in the working directory:
11533 hg kwshrink [OPTION]... [FILE]...
11535 Must be run before changing/disabling active keywords.
11537 kwshrink refuses to run if given files contain local changes.
11539 Options:
11541 -I,--include <PATTERN[+]>
11543 include names matching the given patterns
11544 -X,--exclude <PATTERN[+]>
11546 exclude names matching the given patterns
11547 [+] marked option can be specified multiple times
11549 largefiles
11551 track large binary files
11552 Large binary files tend to be not very compressible, not very diffable,
11554 and not at all mergeable. Such files are not handled efficiently by
11555 Mercurial's storage format (revlog), which is based on compressed bi‐
11556 nary deltas; storing large binary files as regular Mercurial files
11557 wastes bandwidth and disk space and increases Mercurial's memory usage.
11558 The largefiles extension addresses these problems by adding a central‐
11559 ized client-server layer on top of Mercurial: largefiles live in a cen‐
11560 tral store out on the network somewhere, and you only fetch the revi‐
11561 sions that you need when you need them.
11562 largefiles works by maintaining a "standin file" in .hglf/ for each
11564 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
11565 line) and are tracked by Mercurial. Largefile revisions are identified
11566 by the SHA-1 hash of their contents, which is written to the standin.
11567 largefiles uses that revision ID to get/put largefile revisions from/to
11568 the central store. This saves both disk space and bandwidth, since you
11569 don't need to retrieve all historical revisions of large files when you
11570 clone or pull.
11571 To start a new repository or add new large binary files, just add
11573 --large to your hg add command. For example:
11574 $ dd if=/dev/urandom of=randomdata count=2000
11576 $ hg add --large randomdata
11577 $ hg commit -m "add randomdata as a largefile"
11578 When you push a changeset that adds/modifies largefiles to a remote
11580 repository, its largefile revisions will be uploaded along with it.
11581 Note that the remote Mercurial must also have the largefiles extension
11582 enabled for this to work.
11583 When you pull a changeset that affects largefiles from a remote reposi‐
11585 tory, the largefiles for the changeset will by default not be pulled
11586 down. However, when you update to such a revision, any largefiles
11587 needed by that revision are downloaded and cached (if they have never
11588 been downloaded before). One way to pull largefiles when pulling is
11589 thus to use --update, which will update your working copy to the latest
11590 pulled revision (and thereby downloading any new largefiles).
11591 If you want to pull largefiles you don't need for update yet, then you
11593 can use pull with the --lfrev option or the hg lfpull command.
11594 If you know you are pulling from a non-default location and want to
11596 download all the largefiles that correspond to the new changesets at
11597 the same time, then you can pull with --lfrev "pulled()".
11598 If you just want to ensure that you will have the largefiles needed to
11600 merge or rebase with new heads that you are pulling, then you can pull
11601 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
11602 files that are new in the heads you are pulling.
11603 Keep in mind that network access may now be required to update to
11605 changesets that you have not previously updated to. The nature of the
11606 largefiles extension means that updating is no longer guaranteed to be
11607 a local-only operation.
11608 If you already have large files tracked by Mercurial without the large‐
11610 files extension, you will need to convert your repository in order to
11611 benefit from largefiles. This is done with the hg lfconvert command:
11612 $ hg lfconvert --size 10 oldrepo newrepo
11614 In repositories that already have largefiles in them, any new file over
11616 10MB will automatically be added as a largefile. To change this thresh‐
11617 old, set largefiles.minsize in your Mercurial config file to the mini‐
11618 mum size in megabytes to track as a largefile, or use the --lfsize op‐
11619 tion to the add command (also in megabytes):
11620 [largefiles]
11622 minsize = 2
11623 $ hg add --lfsize 2
11625 The largefiles.patterns config option allows you to specify a list of
11627 filename patterns (see hg help patterns) that should always be tracked
11628 as largefiles:
11629 [largefiles]
11631 patterns =
11632 *.jpg
11633 re:.*\.(png|bmp)$
11634 library.zip
11635 content/audio/*
11636 Files that match one of these patterns will be added as largefiles re‐
11638 gardless of their size.
11639 The largefiles.minsize and largefiles.patterns config options will be
11641 ignored for any repositories not already containing a largefile. To add
11642 the first largefile to a repository, you must explicitly do so with the
11643 --large flag passed to the hg add command.
11644 Commands
11646 Uncategorized commands
11647 lfconvert
11648 convert a normal repository to a largefiles repository:
11649 hg lfconvert SOURCE DEST [FILE ...]
11651 Convert repository SOURCE to a new repository DEST, identical to SOURCE
11653 except that certain files will be converted as largefiles: specifi‐
11654 cally, any file that matches any PATTERN or whose size is above the
11655 minimum size threshold is converted as a largefile. The size used to
11656 determine whether or not to track a file as a largefile is the size of
11657 the first version of the file. The minimum size can be specified either
11658 with --size or in configuration as largefiles.size.
11659 After running this command you will need to make sure that largefiles
11661 is enabled anywhere you intend to push the new repository.
11662 Use --to-normal to convert largefiles back to normal files; after this,
11664 the DEST repository can be used without largefiles at all.
11665 Options:
11667 -s,--size <SIZE>
11669 minimum size (MB) for files to be converted as largefiles
11670 --to-normal
11672 convert from a largefiles repo to a normal repo
11673 lfpull
11675 pull largefiles for the specified revisions from the specified source:
11676 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
11678 Pull largefiles that are referenced from local changesets but missing
11680 locally, pulling from a remote repository to the local cache.
11681 If SOURCE is omitted, the 'default' path will be used. See hg help
11683 urls for more information.
11684 Some examples:
11686 • pull largefiles for all branch heads:
11688 hg lfpull -r "head() and not closed()"
11690 • pull largefiles on the default branch:
11692 hg lfpull -r "branch(default)"
11694 Options:
11696 -r,--rev <VALUE[+]>
11698 pull largefiles for these revisions
11699 -e,--ssh <CMD>
11701 specify ssh command to use
11702 --remotecmd <CMD>
11704 specify hg command to run on the remote side
11705 --insecure
11707 do not verify server certificate (ignoring web.cacerts config)
11708 [+] marked option can be specified multiple times
11710 lfs
11712 lfs - large file support (EXPERIMENTAL)
11713 This extension allows large files to be tracked outside of the normal
11715 repository storage and stored on a centralized server, similar to the
11716 largefiles extension. The git-lfs protocol is used when communicating
11717 with the server, so existing git infrastructure can be harnessed. Even
11718 though the files are stored outside of the repository, they are still
11719 integrity checked in the same manner as normal files.
11720 The files stored outside of the repository are downloaded on demand,
11722 which reduces the time to clone, and possibly the local disk usage.
11723 This changes fundamental workflows in a DVCS, so careful thought should
11724 be given before deploying it. hg convert can be used to convert LFS
11725 repositories to normal repositories that no longer require this exten‐
11726 sion, and do so without changing the commit hashes. This allows the
11727 extension to be disabled if the centralized workflow becomes burden‐
11728 some. However, the pre and post convert clones will not be able to
11729 communicate with each other unless the extension is enabled on both.
11730 To start a new repository, or to add LFS files to an existing one, just
11732 create an .hglfs file as described below in the root directory of the
11733 repository. Typically, this file should be put under version control,
11734 so that the settings will propagate to other repositories with push and
11735 pull. During any commit, Mercurial will consult this file to determine
11736 if an added or modified file should be stored externally. The type of
11737 storage depends on the characteristics of the file at each commit. A
11738 file that is near a size threshold may switch back and forth between
11739 LFS and normal storage, as needed.
11740 Alternately, both normal repositories and largefile controlled reposi‐
11742 tories can be converted to LFS by using hg convert and the lfs.track
11743 config option described below. The .hglfs file should then be created
11744 and added, to control subsequent LFS selection. The hashes are also
11745 unchanged in this case. The LFS and non-LFS repositories can be dis‐
11746 tinguished because the LFS repository will abort any command if this
11747 extension is disabled.
11748 Committed LFS files are held locally, until the repository is pushed.
11750 Prior to pushing the normal repository data, the LFS files that are
11751 tracked by the outgoing commits are automatically uploaded to the con‐
11752 figured central server. No LFS files are transferred on hg pull or hg
11753 clone. Instead, the files are downloaded on demand as they need to be
11754 read, if a cached copy cannot be found locally. Both committing and
11755 downloading an LFS file will link the file to a usercache, to speed up
11756 future access. See the usercache config setting described below.
11757 The extension reads its configuration from a versioned .hglfs configu‐
11759 ration file found in the root of the working directory. The .hglfs file
11760 uses the same syntax as all other Mercurial configuration files. It
11761 uses a single section, [track].
11762 The [track] section specifies which files are stored as LFS (or not).
11764 Each line is keyed by a file pattern, with a predicate value. The
11765 first file pattern match is used, so put more specific patterns first.
11766 The available predicates are all(), none(), and size(). See "hg help
11767 filesets.size" for the latter.
11768 Example versioned .hglfs file:
11770 [track]
11772 # No Makefile or python file, anywhere, will be LFS
11773 **Makefile = none()
11774 **.py = none()
11775 **.zip = all()
11777 **.exe = size(">1MB")
11778 # Catchall for everything not matched above
11780 ** = size(">10MB")
11781 Configs:
11783 [lfs]
11785 # Remote endpoint. Multiple protocols are supported:
11786 # - http(s)://user:pass@example.com/path
11787 # git-lfs endpoint
11788 # - file:///tmp/path
11789 # local filesystem, usually for testing
11790 # if unset, lfs will assume the remote repository also handles blob storage
11791 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
11792 # use this value.
11793 # (default: unset)
11794 url = https://example.com/repo.git/info/lfs
11795 # Which files to track in LFS. Path tests are "**.extname" for file
11797 # extensions, and "path:under/some/directory" for path prefix. Both
11798 # are relative to the repository root.
11799 # File size can be tested with the "size()" fileset, and tests can be
11800 # joined with fileset operators. (See "hg help filesets.operators".)
11801 #
11802 # Some examples:
11803 # - all() # everything
11804 # - none() # nothing
11805 # - size(">20MB") # larger than 20MB
11806 # - !**.txt # anything not a *.txt file
11807 # - **.zip | **.tar.gz | **.7z # some types of compressed files
11808 # - path:bin # files under "bin" in the project root
11809 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
11810 # | (path:bin & !path:/bin/README) | size(">1GB")
11811 # (default: none())
11812 #
11813 # This is ignored if there is a tracked '.hglfs' file, and this setting
11814 # will eventually be deprecated and removed.
11815 track = size(">10M")
11816 # how many times to retry before giving up on transferring an object
11818 retry = 5
11819 # the local directory to store lfs files for sharing across local clones.
11821 # If not set, the cache is located in an OS specific cache location.
11822 usercache = /path/to/global/cache
11823 Commands
11825 Uncategorized commands
11826 logtoprocess
11827 send ui.log() data to a subprocess (EXPERIMENTAL)
11828 This extension lets you specify a shell command per ui.log() event,
11830 sending all remaining arguments to as environment variables to that
11831 command.
11832 Positional arguments construct a log message, which is passed in the
11834 MSG1 environment variables. Each keyword argument is set as a OPT_UP‐
11835 PERCASE_KEY variable (so the key is uppercased, and prefixed with
11836 OPT_). The original event name is passed in the EVENT environment vari‐
11837 able, and the process ID of mercurial is given in HGPID.
11838 So given a call ui.log('foo', 'bar %s ', 'baz', spam='eggs'), a script
11840 configured for the `foo event can expect an environment with MSG1=bar
11841 baz, and OPT_SPAM=eggs.
11842 Scripts are configured in the [logtoprocess] section, each key an event
11844 name. For example:
11845 [logtoprocess]
11847 commandexception = echo "$MSG1" > /var/log/mercurial_exceptions.log
11848 would log the warning message and traceback of any failed command dis‐
11850 patch.
11851 Scripts are run asynchronously as detached daemon processes; mercurial
11853 will not ensure that they exit cleanly.
11854 mq
11856 manage a stack of patches
11857 This extension lets you work with a stack of patches in a Mercurial
11859 repository. It manages two stacks of patches - all known patches, and
11860 applied patches (subset of known patches).
11861 Known patches are represented as patch files in the .hg/patches direc‐
11863 tory. Applied patches are both patch files and changesets.
11864 Common tasks (use hg help COMMAND for more details):
11866 create new patch qnew
11868 import existing patch qimport
11869 print patch series qseries
11871 print applied patches qapplied
11872 add known patch to applied stack qpush
11874 remove patch from applied stack qpop
11875 refresh contents of top applied patch qrefresh
11876 By default, mq will automatically use git patches when required to
11878 avoid losing file mode changes, copy records, binary files or empty
11879 files creations or deletions. This behavior can be configured with:
11880 [mq]
11882 git = auto/keep/yes/no
11883 If set to 'keep', mq will obey the [diff] section configuration while
11885 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
11886 mq will override the [diff] section and always generate git or regular
11887 patches, possibly losing data in the second case.
11888 It may be desirable for mq changesets to be kept in the secret phase
11890 (see hg help phases), which can be enabled with the following setting:
11891 [mq]
11893 secret = True
11894 You will by default be managing a patch queue named "patches". You can
11896 create other, independent patch queues with the hg qqueue command.
11897 If the working directory contains uncommitted files, qpush, qpop and
11899 qgoto abort immediately. If -f/--force is used, the changes are dis‐
11900 carded. Setting:
11901 [mq]
11903 keepchanges = True
11904 make them behave as if --keep-changes were passed, and non-conflicting
11906 local changes will be tolerated and preserved. If incompatible options
11907 such as -f/--force or --exact are passed, this setting is ignored.
11908 This extension used to provide a strip command. This command now lives
11910 in the strip extension.
11911 Commands
11913 Repository creation
11914 qclone
11915 clone main and patch repository at same time:
11916 hg qclone [OPTION]... SOURCE [DEST]
11918 If source is local, destination will have no patches applied. If source
11920 is remote, this command can not check if patches are applied in source,
11921 so cannot guarantee that patches are not applied in destination. If you
11922 clone remote repository, be sure before that it has no patches applied.
11923 Source patch repository is looked for in <src>/.hg/patches by default.
11925 Use -p <url> to change.
11926 The patch directory must be a nested Mercurial repository, as would be
11928 created by hg init --mq.
11929 Return 0 on success.
11931 Options:
11933 --pull use pull protocol to copy metadata
11935 -U, --noupdate
11937 do not update the new working directories
11938 --uncompressed
11940 use uncompressed transfer (fast over LAN)
11941 -p,--patches <REPO>
11943 location of source patch repository
11944 -e,--ssh <CMD>
11946 specify ssh command to use
11947 --remotecmd <CMD>
11949 specify hg command to run on the remote side
11950 --insecure
11952 do not verify server certificate (ignoring web.cacerts config)
11953 qinit
11955 init a new queue repository (DEPRECATED):
11956 hg qinit [-c]
11958 The queue repository is unversioned by default. If -c/--create-repo is
11960 specified, qinit will create a separate nested repository for patches
11961 (qinit -c may also be run later to convert an unversioned patch reposi‐
11962 tory into a versioned one). You can use qcommit to commit changes to
11963 this queue repository.
11964 This command is deprecated. Without -c, it's implied by other relevant
11966 commands. With -c, use hg init --mq instead.
11967 Options:
11969 -c, --create-repo
11971 create queue repository
11972 Change creation
11974 qcommit
11975 commit changes in the queue repository (DEPRECATED):
11976 hg qcommit [OPTION]... [FILE]...
11978 This command is deprecated; use hg commit --mq instead.
11980 Options:
11982 -A, --addremove
11984 mark new/missing files as added/removed before committing
11985 --close-branch
11987 mark a branch head as closed
11988 --amend
11990 amend the parent of the working directory
11991 -s, --secret
11993 use the secret phase for committing
11994 --draft
11996 use the draft phase for committing
11997 -e, --edit
11999 invoke editor on commit messages
12000 --force-close-branch
12002 forcibly close branch from a non-head changeset (ADVANCED)
12003 -i, --interactive
12005 use interactive mode
12006 -I,--include <PATTERN[+]>
12008 include names matching the given patterns
12009 -X,--exclude <PATTERN[+]>
12011 exclude names matching the given patterns
12012 -m,--message <TEXT>
12014 use text as commit message
12015 -l,--logfile <FILE>
12017 read commit message from file
12018 -d,--date <DATE>
12020 record the specified date as commit date
12021 -u,--user <USER>
12023 record the specified user as committer
12024 -S, --subrepos
12026 recurse into subrepositories
12027 [+] marked option can be specified multiple times
12029 aliases: qci
12031 qnew
12033 create a new patch:
12034 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
12036 qnew creates a new patch on top of the currently-applied patch (if
12038 any). The patch will be initialized with any outstanding changes in the
12039 working directory. You may also use -I/--include, -X/--exclude, and/or
12040 a list of files after the patch name to add only changes to matching
12041 files to the new patch, leaving the rest as uncommitted modifications.
12042 -u/--user and -d/--date can be used to set the (given) user and date,
12044 respectively. -U/--currentuser and -D/--currentdate set user to current
12045 user and date to current date.
12046 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
12048 the commit message. If none is specified, the header is empty and the
12049 commit message is '[mq]: PATCH'.
12050 Use the -g/--git option to keep the patch in the git extended diff for‐
12052 mat. Read the diffs help topic for more information on why this is im‐
12053 portant for preserving permission changes and copy/rename information.
12054 Returns 0 on successful creation of a new patch.
12056 Options:
12058 -e, --edit
12060 invoke editor on commit messages
12061 -f, --force
12063 import uncommitted changes (DEPRECATED)
12064 -g, --git
12066 use git extended diff format
12067 -U, --currentuser
12069 add "From: <current user>" to patch
12070 -u,--user <USER>
12072 add "From: <USER>" to patch
12073 -D, --currentdate
12075 add "Date: <current date>" to patch
12076 -d,--date <DATE>
12078 add "Date: <DATE>" to patch
12079 -I,--include <PATTERN[+]>
12081 include names matching the given patterns
12082 -X,--exclude <PATTERN[+]>
12084 exclude names matching the given patterns
12085 -m,--message <TEXT>
12087 use text as commit message
12088 -l,--logfile <FILE>
12090 read commit message from file
12091 [+] marked option can be specified multiple times
12093 qrefresh
12095 update the current patch:
12096 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
12098 If any file patterns are provided, the refreshed patch will contain
12100 only the modifications that match those patterns; the remaining modifi‐
12101 cations will remain in the working directory.
12102 If -s/--short is specified, files currently included in the patch will
12104 be refreshed just like matched files and remain in the patch.
12105 If -e/--edit is specified, Mercurial will start your configured editor
12107 for you to enter a message. In case qrefresh fails, you will find a
12108 backup of your message in .hg/last-message.txt.
12109 hg add/remove/copy/rename work as usual, though you might want to use
12111 git-style patches (-g/--git or [diff] git=1) to track copies and re‐
12112 names. See the diffs help topic for more information on the git diff
12113 format.
12114 Returns 0 on success.
12116 Options:
12118 -e, --edit
12120 invoke editor on commit messages
12121 -g, --git
12123 use git extended diff format
12124 -s, --short
12126 refresh only files already in the patch and specified files
12127 -U, --currentuser
12129 add/update author field in patch with current user
12130 -u,--user <USER>
12132 add/update author field in patch with given user
12133 -D, --currentdate
12135 add/update date field in patch with current date
12136 -d,--date <DATE>
12138 add/update date field in patch with given date
12139 -I,--include <PATTERN[+]>
12141 include names matching the given patterns
12142 -X,--exclude <PATTERN[+]>
12144 exclude names matching the given patterns
12145 -m,--message <TEXT>
12147 use text as commit message
12148 -l,--logfile <FILE>
12150 read commit message from file
12151 [+] marked option can be specified multiple times
12153 Change manipulation
12155 qfold
12156 fold the named patches into the current patch:
12157 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
12159 Patches must not yet be applied. Each patch will be successively ap‐
12161 plied to the current patch in the order given. If all the patches apply
12162 successfully, the current patch will be refreshed with the new cumula‐
12163 tive patch, and the folded patches will be deleted. With -k/--keep, the
12164 folded patch files will not be removed afterwards.
12165 The header for each folded patch will be concatenated with the current
12167 patch header, separated by a line of * * *.
12168 Returns 0 on success.
12170 Options:
12172 -e, --edit
12174 invoke editor on commit messages
12175 -k, --keep
12177 keep folded patch files
12178 -m,--message <TEXT>
12180 use text as commit message
12181 -l,--logfile <FILE>
12183 read commit message from file
12184 Change organization
12186 qapplied
12187 print the patches already applied:
12188 hg qapplied [-1] [-s] [PATCH]
12190 Returns 0 on success.
12192 Options:
12194 -1, --last
12196 show only the preceding applied patch
12197 -s, --summary
12199 print first line of patch header
12200 qdelete
12202 remove patches from queue:
12203 hg qdelete [-k] [PATCH]...
12205 The patches must not be applied, and at least one patch is required.
12207 Exact patch identifiers must be given. With -k/--keep, the patch files
12208 are preserved in the patch directory.
12209 To stop managing a patch and move it into permanent history, use the hg
12211 qfinish command.
12212 Options:
12214 -k, --keep
12216 keep patch file
12217 -r,--rev <REV[+]>
12219 stop managing a revision (DEPRECATED)
12220 [+] marked option can be specified multiple times
12222 aliases: qremove qrm
12224 qfinish
12226 move applied patches into repository history:
12227 hg qfinish [-a] [REV]...
12229 Finishes the specified revisions (corresponding to applied patches) by
12231 moving them out of mq control into regular repository history.
12232 Accepts a revision range or the -a/--applied option. If --applied is
12234 specified, all applied mq revisions are removed from mq control. Other‐
12235 wise, the given revisions must be at the base of the stack of applied
12236 patches.
12237 This can be especially useful if your changes have been applied to an
12239 upstream repository, or if you are about to push your changes to up‐
12240 stream.
12241 Returns 0 on success.
12243 Options:
12245 -a, --applied
12247 finish all applied changesets
12248 qgoto
12250 push or pop patches until named patch is at top of stack:
12251 hg qgoto [OPTION]... PATCH
12253 Returns 0 on success.
12255 Options:
12257 --keep-changes
12259 tolerate non-conflicting local changes
12260 -f, --force
12262 overwrite any local changes
12263 --no-backup
12265 do not save backup copies of files
12266 qguard
12268 set or print guards for a patch:
12269 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
12271 Guards control whether a patch can be pushed. A patch with no guards is
12273 always pushed. A patch with a positive guard ("+foo") is pushed only if
12274 the hg qselect command has activated it. A patch with a negative guard
12275 ("-foo") is never pushed if the hg qselect command has activated it.
12276 With no arguments, print the currently active guards. With arguments,
12278 set guards for the named patch.
12279 Note Specifying negative guards now requires '--'.
12281 To set guards on another patch:
12283 hg qguard other.patch -- +2.6.17 -stable
12285 Returns 0 on success.
12287 Options:
12289 -l, --list
12291 list all patches and guards
12292 -n, --none
12294 drop all guards
12295 qheader
12297 print the header of the topmost or specified patch:
12298 hg qheader [PATCH]
12300 Returns 0 on success.
12302 qnext
12304 print the name of the next pushable patch:
12305 hg qnext [-s]
12307 Returns 0 on success.
12309 Options:
12311 -s, --summary
12313 print first line of patch header
12314 qpop
12316 pop the current patch off the stack:
12317 hg qpop [-a] [-f] [PATCH | INDEX]
12319 Without argument, pops off the top of the patch stack. If given a patch
12321 name, keeps popping off patches until the named patch is at the top of
12322 the stack.
12323 By default, abort if the working directory contains uncommitted
12325 changes. With --keep-changes, abort only if the uncommitted files over‐
12326 lap with patched files. With -f/--force, backup and discard changes
12327 made to such files.
12328 Return 0 on success.
12330 Options:
12332 -a, --all
12334 pop all patches
12335 -n,--name <NAME>
12337 queue name to pop (DEPRECATED)
12338 --keep-changes
12340 tolerate non-conflicting local changes
12341 -f, --force
12343 forget any local changes to patched files
12344 --no-backup
12346 do not save backup copies of files
12347 qprev
12349 print the name of the preceding applied patch:
12350 hg qprev [-s]
12352 Returns 0 on success.
12354 Options:
12356 -s, --summary
12358 print first line of patch header
12359 qpush
12361 push the next patch onto the stack:
12362 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
12364 By default, abort if the working directory contains uncommitted
12366 changes. With --keep-changes, abort only if the uncommitted files over‐
12367 lap with patched files. With -f/--force, backup and patch over uncom‐
12368 mitted changes.
12369 Return 0 on success.
12371 Options:
12373 --keep-changes
12375 tolerate non-conflicting local changes
12376 -f, --force
12378 apply on top of local changes
12379 -e, --exact
12381 apply the target patch to its recorded parent
12382 -l, --list
12384 list patch name in commit text
12385 -a, --all
12387 apply all patches
12388 -m, --merge
12390 merge from another queue (DEPRECATED)
12391 -n,--name <NAME>
12393 merge queue name (DEPRECATED)
12394 --move reorder patch series and apply only the patch
12396 --no-backup
12398 do not save backup copies of files
12399 qqueue
12401 manage multiple patch queues:
12402 hg qqueue [OPTION] [QUEUE]
12404 Supports switching between different patch queues, as well as creating
12406 new patch queues and deleting existing ones.
12407 Omitting a queue name or specifying -l/--list will show you the regis‐
12409 tered queues - by default the "normal" patches queue is registered. The
12410 currently active queue will be marked with "(active)". Specifying --ac‐
12411 tive will print only the name of the active queue.
12412 To create a new queue, use -c/--create. The queue is automatically made
12414 active, except in the case where there are applied patches from the
12415 currently active queue in the repository. Then the queue will only be
12416 created and switching will fail.
12417 To delete an existing queue, use --delete. You cannot delete the cur‐
12419 rently active queue.
12420 Returns 0 on success.
12422 Options:
12424 -l, --list
12426 list all available queues
12427 --active
12429 print name of active queue
12430 -c, --create
12432 create new queue
12433 --rename
12435 rename active queue
12436 --delete
12438 delete reference to queue
12439 --purge
12441 delete queue, and remove patch dir
12442 qrename
12444 rename a patch:
12445 hg qrename PATCH1 [PATCH2]
12447 With one argument, renames the current patch to PATCH1. With two argu‐
12449 ments, renames PATCH1 to PATCH2.
12450 Returns 0 on success.
12452 aliases: qmv
12454 qrestore
12456 restore the queue state saved by a revision (DEPRECATED):
12457 hg qrestore [-d] [-u] REV
12459 This command is deprecated, use hg rebase instead.
12461 Options:
12463 -d, --delete
12465 delete save entry
12466 -u, --update
12468 update queue working directory
12469 qsave
12471 save current queue state (DEPRECATED):
12472 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
12474 This command is deprecated, use hg rebase instead.
12476 Options:
12478 -c, --copy
12480 copy patch directory
12481 -n,--name <NAME>
12483 copy directory name
12484 -e, --empty
12486 clear queue status file
12487 -f, --force
12489 force copy
12490 -m,--message <TEXT>
12492 use text as commit message
12493 -l,--logfile <FILE>
12495 read commit message from file
12496 qselect
12498 set or print guarded patches to push:
12499 hg qselect [OPTION]... [GUARD]...
12501 Use the hg qguard command to set or print guards on patch, then use qs‐
12503 elect to tell mq which guards to use. A patch will be pushed if it has
12504 no guards or any positive guards match the currently selected guard,
12505 but will not be pushed if any negative guards match the current guard.
12506 For example:
12507 qguard foo.patch -- -stable (negative guard)
12509 qguard bar.patch +stable (positive guard)
12510 qselect stable
12511 This activates the "stable" guard. mq will skip foo.patch (because it
12513 has a negative match) but push bar.patch (because it has a positive
12514 match).
12515 With no arguments, prints the currently active guards. With one argu‐
12517 ment, sets the active guard.
12518 Use -n/--none to deactivate guards (no other arguments needed). When
12520 no guards are active, patches with positive guards are skipped and
12521 patches with negative guards are pushed.
12522 qselect can change the guards on applied patches. It does not pop
12524 guarded patches by default. Use --pop to pop back to the last applied
12525 patch that is not guarded. Use --reapply (which implies --pop) to push
12526 back to the current patch afterwards, but skip guarded patches.
12527 Use -s/--series to print a list of all guards in the series file (no
12529 other arguments needed). Use -v for more information.
12530 Returns 0 on success.
12532 Options:
12534 -n, --none
12536 disable all guards
12537 -s, --series
12539 list all guards in series file
12540 --pop pop to before first guarded applied patch
12542 --reapply
12544 pop, then reapply patches
12545 qseries
12547 print the entire series file:
12548 hg qseries [-ms]
12550 Returns 0 on success.
12552 Options:
12554 -m, --missing
12556 print patches not in series
12557 -s, --summary
12559 print first line of patch header
12560 qtop
12562 print the name of the current patch:
12563 hg qtop [-s]
12565 Returns 0 on success.
12567 Options:
12569 -s, --summary
12571 print first line of patch header
12572 qunapplied
12574 print the patches not yet applied:
12575 hg qunapplied [-1] [-s] [PATCH]
12577 Returns 0 on success.
12579 Options:
12581 -1, --first
12583 show only the first patch
12584 -s, --summary
12586 print first line of patch header
12587 File content management
12589 qdiff
12590 diff of the current patch and subsequent modifications:
12591 hg qdiff [OPTION]... [FILE]...
12593 Shows a diff which includes the current patch as well as any changes
12595 which have been made in the working directory since the last refresh
12596 (thus showing what the current patch would become after a qrefresh).
12597 Use hg diff if you only want to see the changes made since the last
12599 qrefresh, or hg export qtip if you want to see changes made by the cur‐
12600 rent patch without including changes made since the qrefresh.
12601 Returns 0 on success.
12603 Options:
12605 -a, --text
12607 treat all files as text
12608 -g, --git
12610 use git extended diff format (DEFAULT: diff.git)
12611 --binary
12613 generate binary diffs in git mode (default)
12614 --nodates
12616 omit dates from diff headers
12617 --noprefix
12619 omit a/ and b/ prefixes from filenames
12620 -p, --show-function
12622 show which function each change is in (DEFAULT: diff.showfunc)
12623 --reverse
12625 produce a diff that undoes the changes
12626 -w, --ignore-all-space
12628 ignore white space when comparing lines
12629 -b, --ignore-space-change
12631 ignore changes in the amount of white space
12632 -B, --ignore-blank-lines
12634 ignore changes whose lines are all blank
12635 -Z, --ignore-space-at-eol
12637 ignore changes in whitespace at EOL
12638 -U,--unified <NUM>
12640 number of lines of context to show
12641 --stat output diffstat-style summary of changes
12643 --root <DIR>
12645 produce diffs relative to subdirectory
12646 -I,--include <PATTERN[+]>
12648 include names matching the given patterns
12649 -X,--exclude <PATTERN[+]>
12651 exclude names matching the given patterns
12652 [+] marked option can be specified multiple times
12654 Change import/export
12656 qimport
12657 import a patch or existing changeset:
12658 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
12660 The patch is inserted into the series after the last applied patch. If
12662 no patches have been applied, qimport prepends the patch to the series.
12663 The patch will have the same name as its source file unless you give it
12665 a new one with -n/--name.
12666 You can register an existing patch inside the patch directory with the
12668 -e/--existing flag.
12669 With -f/--force, an existing patch of the same name will be overwrit‐
12671 ten.
12672 An existing changeset may be placed under mq control with -r/--rev
12674 (e.g. qimport --rev . -n patch will place the current revision under mq
12675 control). With -g/--git, patches imported with --rev will use the git
12676 diff format. See the diffs help topic for information on why this is
12677 important for preserving rename/copy information and permission
12678 changes. Use hg qfinish to remove changesets from mq control.
12679 To import a patch from standard input, pass - as the patch file. When
12681 importing from standard input, a patch name must be specified using the
12682 --name flag.
12683 To import an existing patch while renaming it:
12685 hg qimport -e existing-patch -n new-name
12687 Returns 0 if import succeeded.
12689 Options:
12691 -e, --existing
12693 import file in patch directory
12694 -n,--name <NAME>
12696 name of patch file
12697 -f, --force
12699 overwrite existing files
12700 -r,--rev <REV[+]>
12702 place existing revisions under mq control
12703 -g, --git
12705 use git extended diff format
12706 -P, --push
12708 qpush after importing
12709 [+] marked option can be specified multiple times
12711 narrow
12713 create clones which fetch history data for subset of files (EXPERIMEN‐
12714 TAL)
12715 Commands
12717 Repository maintenance
12718 tracked
12719 show or change the current narrowspec:
12720 hg tracked [OPTIONS]... [REMOTE]
12722 With no argument, shows the current narrowspec entries, one per line.
12724 Each line will be prefixed with 'I' or 'X' for included or excluded
12725 patterns, respectively.
12726 The narrowspec is comprised of expressions to match remote files and/or
12728 directories that should be pulled into your client. The narrowspec has
12729 include and exclude expressions, with excludes always trumping in‐
12730 cludes: that is, if a file matches an exclude expression, it will be
12731 excluded even if it also matches an include expression. Excluding
12732 files that were never included has no effect.
12733 Each included or excluded entry is in the format described by 'hg help
12735 patterns'.
12736 The options allow you to add or remove included and excluded expres‐
12738 sions.
12739 If --clear is specified, then all previous includes and excludes are
12741 DROPPED and replaced by the new ones specified to --addinclude and
12742 --addexclude. If --clear is specified without any further options, the
12743 narrowspec will be empty and will not match any files.
12744 If --auto-remove-includes is specified, then those includes that don't
12746 match any files modified by currently visible local commits (those not
12747 shared by the remote) will be added to the set of explicitly specified
12748 includes to remove.
12749 --import-rules accepts a path to a file containing rules, allowing you
12751 to add --addinclude, --addexclude rules in bulk. Like the other include
12752 and exclude switches, the changes are applied immediately.
12753 Options:
12755 --addinclude <VALUE[+]>
12757 new paths to include
12758 --removeinclude <VALUE[+]>
12760 old paths to no longer include
12761 --auto-remove-includes
12763 automatically choose unused includes to remove
12764 --addexclude <VALUE[+]>
12766 new paths to exclude
12767 --import-rules <VALUE>
12769 import narrowspecs from a file
12770 --removeexclude <VALUE[+]>
12772 old paths to no longer exclude
12773 --clear
12775 whether to replace the existing narrowspec
12776 --force-delete-local-changes
12778 forces deletion of local changes when narrowing
12779 --backup
12781 back up local changes when narrowing (default: True)
12782 --update-working-copy
12784 update working copy when the store has changed
12785 -e,--ssh <CMD>
12787 specify ssh command to use
12788 --remotecmd <CMD>
12790 specify hg command to run on the remote side
12791 --insecure
12793 do not verify server certificate (ignoring web.cacerts config)
12794 [+] marked option can be specified multiple times
12796 notify
12798 hooks for sending email push notifications
12799 This extension implements hooks to send email notifications when
12801 changesets are sent from or received by the local repository.
12802 First, enable the extension as explained in hg help extensions, and
12804 register the hook you want to run. incoming and changegroup hooks are
12805 run when changesets are received, while outgoing hooks are for change‐
12806 sets sent to another repository:
12807 [hooks]
12809 # one email for each incoming changeset
12810 incoming.notify = python:hgext.notify.hook
12811 # one email for all incoming changesets
12812 changegroup.notify = python:hgext.notify.hook
12813 # one email for all outgoing changesets
12815 outgoing.notify = python:hgext.notify.hook
12816 This registers the hooks. To enable notification, subscribers must be
12818 assigned to repositories. The [usersubs] section maps multiple reposi‐
12819 tories to a given recipient. The [reposubs] section maps multiple re‐
12820 cipients to a single repository:
12821 [usersubs]
12823 # key is subscriber email, value is a comma-separated list of repo patterns
12824 user@host = pattern
12825 [reposubs]
12827 # key is repo pattern, value is a comma-separated list of subscriber emails
12828 pattern = user@host
12829 A pattern is a glob matching the absolute path to a repository, option‐
12831 ally combined with a revset expression. A revset expression, if
12832 present, is separated from the glob by a hash. Example:
12833 [reposubs]
12835 */widgets#branch(release) = qa-team@example.com
12836 This sends to qa-team@example.com whenever a changeset on the release
12838 branch triggers a notification in any repository ending in widgets.
12839 In order to place them under direct user management, [usersubs] and
12841 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
12842 rated by reference:
12843 [notify]
12845 config = /path/to/subscriptionsfile
12846 Notifications will not be sent until the notify.test value is set to
12848 False; see below.
12849 Notifications content can be tweaked with the following configuration
12851 entries:
12852 notify.test
12854 If True, print messages to stdout instead of sending them. De‐
12855 fault: True.
12856 notify.sources
12858 Space-separated list of change sources. Notifications are acti‐
12859 vated only when a changeset's source is in this list. Sources
12860 may be:
12861 serve
12863 changesets received via http or ssh
12865 pull
12867 changesets received via hg pull
12869 unbundle
12871 changesets received via hg unbundle
12873 push
12875 changesets sent or received via hg push
12877 bundle
12879 changesets sent via hg unbundle
12881 Default: serve.
12883 notify.strip
12885 Number of leading slashes to strip from url paths. By default,
12886 notifications reference repositories with their absolute path.
12887 notify.strip lets you turn them into relative paths. For exam‐
12888 ple, notify.strip=3 will change /long/path/repository into
12889 repository. Default: 0.
12890 notify.domain
12892 Default email domain for sender or recipients with no explicit
12893 domain. It is also used for the domain part of the Message-Id
12894 when using notify.messageidseed.
12895 notify.messageidseed
12897 Create deterministic Message-Id headers for the mails based on
12898 the seed and the revision identifier of the first commit in the
12899 changeset.
12900 notify.style
12902 Style file to use when formatting emails.
12903 notify.template
12905 Template to use when formatting emails.
12906 notify.incoming
12908 Template to use when run as an incoming hook, overriding no‐
12909 tify.template.
12910 notify.outgoing
12912 Template to use when run as an outgoing hook, overriding no‐
12913 tify.template.
12914 notify.changegroup
12916 Template to use when running as a changegroup hook, overriding
12917 notify.template.
12918 notify.maxdiff
12920 Maximum number of diff lines to include in notification email.
12921 Set to 0 to disable the diff, or -1 to include all of it. De‐
12922 fault: 300.
12923 notify.maxdiffstat
12925 Maximum number of diffstat lines to include in notification
12926 email. Set to -1 to include all of it. Default: -1.
12927 notify.maxsubject
12929 Maximum number of characters in email's subject line. Default:
12930 67.
12931 notify.diffstat
12933 Set to True to include a diffstat before diff content. Default:
12934 True.
12935 notify.showfunc
12937 If set, override diff.showfunc for the diff content. Default:
12938 None.
12939 notify.merge
12941 If True, send notifications for merge changesets. Default: True.
12942 notify.mbox
12944 If set, append mails to this mbox file instead of sending. De‐
12945 fault: None.
12946 notify.fromauthor
12948 If set, use the committer of the first changeset in a change‐
12949 group for the "From" field of the notification mail. If not set,
12950 take the user from the pushing repo. Default: False.
12951 notify.reply-to-predecessor (EXPERIMENTAL)
12953 If set and the changeset has a predecessor in the repository,
12954 try to thread the notification mail with the predecessor. This
12955 adds the "In-Reply-To" header to the notification mail with a
12956 reference to the predecessor with the smallest revision number.
12957 Mail threads can still be torn, especially when changesets are
12958 folded.
12959 This option must be used in combination with notify.messageid‐
12961 seed.
12962 If set, the following entries will also be used to customize the noti‐
12964 fications:
12965 email.from
12967 Email From address to use if none can be found in the generated
12968 email content.
12969 web.baseurl
12971 Root repository URL to combine with repository paths when making
12972 references. See also notify.strip.
12973 pager
12975 browse command output with an external pager (DEPRECATED)
12976 Forcibly enable paging for individual commands that don't typically re‐
12978 quest pagination with the attend-<command> option. This setting takes
12979 precedence over ignore options and defaults:
12980 [pager]
12982 attend-cat = false
12983 patchbomb
12985 command to send changesets as (a series of) patch emails
12986 The series is started off with a "[PATCH 0 of N]" introduction, which
12988 describes the series as a whole.
12989 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12991 first line of the changeset description as the subject text. The mes‐
12992 sage contains two or three body parts:
12993 • The changeset description.
12995 • [Optional] The result of running diffstat on the patch.
12997 • The patch itself, as generated by hg export.
12999 Each message refers to the first in the series using the In-Reply-To
13001 and References headers, so they will show up as a sequence in threaded
13002 mail and news readers, and in mail archives.
13003 To configure other defaults, add a section like this to your configura‐
13005 tion file:
13006 [email]
13008 from = My Name <my@email>
13009 to = recipient1, recipient2, ...
13010 cc = cc1, cc2, ...
13011 bcc = bcc1, bcc2, ...
13012 reply-to = address1, address2, ...
13013 Use [patchbomb] as configuration section name if you need to override
13015 global [email] address settings.
13016 Then you can use the hg email command to mail a series of changesets as
13018 a patchbomb.
13019 You can also either configure the method option in the email section to
13021 be a sendmail compatible mailer or fill out the [smtp] section so that
13022 the patchbomb extension can automatically send patchbombs directly from
13023 the commandline. See the [email] and [smtp] sections in hgrc(5) for de‐
13024 tails.
13025 By default, hg email will prompt for a To or CC header if you do not
13027 supply one via configuration or the command line. You can override
13028 this to never prompt by configuring an empty value:
13029 [email]
13031 cc =
13032 You can control the default inclusion of an introduction message with
13034 the patchbomb.intro configuration option. The configuration is always
13035 overwritten by command line flags like --intro and --desc:
13036 [patchbomb]
13038 intro=auto # include introduction message if more than 1 patch (default)
13039 intro=never # never include an introduction message
13040 intro=always # always include an introduction message
13041 You can specify a template for flags to be added in subject prefixes.
13043 Flags specified by --flag option are exported as {flags} keyword:
13044 [patchbomb]
13046 flagtemplate = "{separate(' ',
13047 ifeq(branch, 'default', '', branch|upper),
13048 flags)}"
13049 You can set patchbomb to always ask for confirmation by setting patch‐
13051 bomb.confirm to true.
13052 Commands
13054 Change import/export
13055 email
13056 send changesets by email:
13057 hg email [OPTION]... [DEST]...
13059 By default, diffs are sent in the format generated by hg export, one
13061 per message. The series starts with a "[PATCH 0 of N]" introduction,
13062 which describes the series as a whole.
13063 Each patch email has a Subject line of "[PATCH M of N] ...", using the
13065 first line of the changeset description as the subject text. The mes‐
13066 sage contains two or three parts. First, the changeset description.
13067 With the -d/--diffstat option, if the diffstat program is installed,
13069 the result of running diffstat on the patch is inserted.
13070 Finally, the patch itself, as generated by hg export.
13072 With the -d/--diffstat or --confirm options, you will be presented with
13074 a final summary of all messages and asked for confirmation before the
13075 messages are sent.
13076 By default the patch is included as text in the email body for easy re‐
13078 viewing. Using the -a/--attach option will instead create an attachment
13079 for the patch. With -i/--inline an inline attachment will be created.
13080 You can include a patch both as text in the email body and as a regular
13081 or an inline attachment by combining the -a/--attach or -i/--inline
13082 with the --body option.
13083 With -B/--bookmark changesets reachable by the given bookmark are se‐
13085 lected.
13086 With -o/--outgoing, emails will be generated for patches not found in
13088 the destination repository (or only those which are ancestors of the
13089 specified revisions if any are provided)
13090 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
13092 gle email containing a binary Mercurial bundle as an attachment will be
13093 sent. Use the patchbomb.bundletype config option to control the bundle
13094 type as with hg bundle --type.
13095 With -m/--mbox, instead of previewing each patchbomb message in a pager
13097 or sending the messages directly, it will create a UNIX mailbox file
13098 with the patch emails. This mailbox file can be previewed with any mail
13099 user agent which supports UNIX mbox files.
13100 With -n/--test, all steps will run, but mail will not be sent. You
13102 will be prompted for an email recipient address, a subject and an in‐
13103 troductory message describing the patches of your patchbomb. Then when
13104 all is done, patchbomb messages are displayed.
13105 In case email sending fails, you will find a backup of your series in‐
13107 troductory message in .hg/last-email.txt.
13108 The default behavior of this command can be customized through configu‐
13110 ration. (See hg help patchbomb for details)
13111 Examples:
13113 hg email -r 3000 # send patch 3000 only
13115 hg email -r 3000 -r 3001 # send patches 3000 and 3001
13116 hg email -r 3000:3005 # send patches 3000 through 3005
13117 hg email 3000 # send patch 3000 (deprecated)
13118 hg email -o # send all patches not in default
13120 hg email -o DEST # send all patches not in DEST
13121 hg email -o -r 3000 # send all ancestors of 3000 not in default
13122 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
13123 hg email -B feature # send all ancestors of feature bookmark
13125 hg email -b # send bundle of all patches not in default
13127 hg email -b DEST # send bundle of all patches not in DEST
13128 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
13129 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
13130 hg email -o -m mbox && # generate an mbox file...
13132 mutt -R -f mbox # ... and view it with mutt
13133 hg email -o -m mbox && # generate an mbox file ...
13134 formail -s sendmail \ # ... and use formail to send from the mbox
13135 -bm -t < mbox # ... using sendmail
13136 Before using this command, you will need to enable email in your hgrc.
13138 See the [email] section in hgrc(5) for details.
13139 Options:
13141 -g, --git
13143 use git extended diff format
13144 --plain
13146 omit hg patch header
13147 -o, --outgoing
13149 send changes not found in the target repository
13150 -b, --bundle
13152 send changes not in target as a binary bundle
13153 -B,--bookmark <BOOKMARK>
13155 send changes only reachable by given bookmark
13156 --bundlename <NAME>
13158 name of the bundle attachment file (default: bundle)
13159 -r,--rev <REV[+]>
13161 a revision to send
13162 --force
13164 run even when remote repository is unrelated (with -b/--bundle)
13165 --base <REV[+]>
13167 a base changeset to specify instead of a destination (with
13168 -b/--bundle)
13169 --intro
13171 send an introduction email for a single patch
13172 --body send patches as inline message text (default)
13174 -a, --attach
13176 send patches as attachments
13177 -i, --inline
13179 send patches as inline attachments
13180 --bcc <EMAIL[+]>
13182 email addresses of blind carbon copy recipients
13183 -c,--cc <EMAIL[+]>
13185 email addresses of copy recipients
13186 --confirm
13188 ask for confirmation before sending
13189 -d, --diffstat
13191 add diffstat output to messages
13192 --date <DATE>
13194 use the given date as the sending date
13195 --desc <FILE>
13197 use the given file as the series description
13198 -f,--from <EMAIL>
13200 email address of sender
13201 -n, --test
13203 print messages that would be sent
13204 -m,--mbox <FILE>
13206 write messages to mbox file instead of sending them
13207 --reply-to <EMAIL[+]>
13209 email addresses replies should be sent to
13210 -s,--subject <TEXT>
13212 subject of first message (intro or single patch)
13213 --in-reply-to <MSGID>
13215 message identifier to reply to
13216 --flag <FLAG[+]>
13218 flags to add in subject prefixes
13219 -t,--to <EMAIL[+]>
13221 email addresses of recipients
13222 -e,--ssh <CMD>
13224 specify ssh command to use
13225 --remotecmd <CMD>
13227 specify hg command to run on the remote side
13228 --insecure
13230 do not verify server certificate (ignoring web.cacerts config)
13231 [+] marked option can be specified multiple times
13233 phabricator
13235 simple Phabricator integration (EXPERIMENTAL)
13236 This extension provides a phabsend command which sends a stack of
13238 changesets to Phabricator, and a phabread command which prints a stack
13239 of revisions in a format suitable for hg import, and a phabupdate com‐
13240 mand to update statuses in batch.
13241 A "phabstatus" view for hg show is also provided; it displays status
13243 information of Phabricator differentials associated with unfinished
13244 changesets.
13245 By default, Phabricator requires Test Plan which might prevent some
13247 changeset from being sent. The requirement could be disabled by chang‐
13248 ing differential.require-test-plan-field config server side.
13249 Config:
13251 [phabricator]
13253 # Phabricator URL
13254 url = https://phab.example.com/
13255 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
13257 # callsign is "FOO".
13258 callsign = FOO
13259 # curl command to use. If not set (default), use builtin HTTP library to
13261 # communicate. If set, use the specified curl command. This could be useful
13262 # if you need to specify advanced options that is not easily supported by
13263 # the internal library.
13264 curlcmd = curl --connect-timeout 2 --retry 3 --silent
13265 # retry failed command N time (default 0). Useful when using the extension
13267 # over flakly connection.
13268 #
13269 # We wait `retry.interval` between each retry, in seconds.
13270 # (default 1 second).
13271 retry = 3
13272 retry.interval = 10
13273 # the retry option can combine well with the http.timeout one.
13275 #
13276 # For example to give up on http request after 20 seconds:
13277 [http]
13278 timeout=20
13279 [auth]
13281 example.schemes = https
13282 example.prefix = phab.example.com
13283 # API token. Get it from https://$HOST/conduit/login/
13285 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
13286 Commands
13288 Change import/export
13289 phabimport
13290 import patches from Phabricator for the specified Differential Revi‐
13291 sions:
13292 hg phabimport DREVSPEC... [OPTIONS]
13294 The patches are read and applied starting at the parent of the working
13296 directory.
13297 See hg help phabread for how to specify DREVSPEC.
13299 Options:
13301 --stack
13303 import dependencies as well
13304 --test-vcr <VALUE>
13306 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13307 script, otherwise will mock all http requests using the speci‐
13308 fied vcr file. (ADVANCED)
13309 phabread
13311 print patches from Phabricator suitable for importing:
13312 hg phabread DREVSPEC... [OPTIONS]
13314 DREVSPEC could be a Differential Revision identity, like D123, or just
13316 the number 123. It could also have common operators like +, -, &, (, )
13317 for complex queries. Prefix : could be used to select a stack. If mul‐
13318 tiple DREVSPEC values are given, the result is the union of each indi‐
13319 vidually evaluated value. No attempt is currently made to reorder the
13320 values to run from parent to child.
13321 abandoned, accepted, closed, needsreview, needsrevision could be used
13323 to filter patches by status. For performance reason, they only repre‐
13324 sent a subset of non-status selections and cannot be used alone.
13325 For example, :D6+8-(2+D4) selects a stack up to D6, plus D8 and exclude
13327 D2 and D4. :D9 & needsreview selects "Needs Review" revisions in a
13328 stack up to D9.
13329 If --stack is given, follow dependencies information and read all
13331 patches. It is equivalent to the : operator.
13332 Options:
13334 --stack
13336 read dependencies
13337 --test-vcr <VALUE>
13339 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13340 script, otherwise will mock all http requests using the speci‐
13341 fied vcr file. (ADVANCED)
13342 phabsend
13344 upload changesets to Phabricator:
13345 hg phabsend REV [OPTIONS]
13347 If there are multiple revisions specified, they will be send as a stack
13349 with a linear dependencies relationship using the order specified by
13350 the revset.
13351 For the first time uploading changesets, local tags will be created to
13353 maintain the association. After the first time, phabsend will check ob‐
13354 sstore and tags information so it can figure out whether to update an
13355 existing Differential Revision, or create a new one.
13356 If --amend is set, update commit messages so they have the Differential
13358 Revision URL, remove related tags. This is similar to what arcanist
13359 will do, and is more desired in author-push workflows. Otherwise, use
13360 local tags to record the Differential Revision association.
13361 The --confirm option lets you confirm changesets before sending them.
13363 You can also add following to your configuration file to make it de‐
13364 fault behaviour:
13365 [phabsend]
13367 confirm = true
13368 By default, a separate review will be created for each commit that is
13370 selected, and will have the same parent/child relationship in Phabrica‐
13371 tor. If --fold is set, multiple commits are rolled up into a single
13372 review as if diffed from the parent of the first revision to the last.
13373 The commit messages are concatenated in the summary field on Phabrica‐
13374 tor.
13375 phabsend will check obsstore and the above association to decide
13377 whether to update an existing Differential Revision, or create a new
13378 one.
13379 Options:
13381 -r,--rev <REV[+]>
13383 revisions to send
13384 --amend
13386 update commit messages (default: True)
13387 --reviewer <VALUE[+]>
13389 specify reviewers
13390 --blocker <VALUE[+]>
13392 specify blocking reviewers
13393 -m,--comment <VALUE>
13395 add a comment to Revisions with new/updated Diffs
13396 --confirm
13398 ask for confirmation before sending
13399 --fold combine the revisions into one review
13401 --test-vcr <VALUE>
13403 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13404 script, otherwise will mock all http requests using the speci‐
13405 fied vcr file. (ADVANCED)
13406 [+] marked option can be specified multiple times
13408 phabupdate
13410 update Differential Revision in batch:
13411 hg phabupdate [DREVSPEC...| -r REV...] [OPTIONS]
13413 DREVSPEC selects revisions. See hg help phabread for its usage.
13415 Options:
13417 --accept
13419 accept revisions
13420 --reject
13422 reject revisions
13423 --request-review
13425 request review on revisions
13426 --abandon
13428 abandon revisions
13429 --reclaim
13431 reclaim revisions
13432 --close
13434 close revisions
13435 --reopen
13437 reopen revisions
13438 --plan-changes
13440 plan changes for revisions
13441 --resign
13443 resign as a reviewer from revisions
13444 --commandeer
13446 commandeer revisions
13447 -m,--comment <VALUE>
13449 comment on the last revision
13450 -r,--rev <REV>
13452 local revision to update
13453 --test-vcr <VALUE>
13455 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13456 script, otherwise will mock all http requests using the speci‐
13457 fied vcr file. (ADVANCED)
13458 Uncategorized commands
13460 purge
13461 command to delete untracked files from the working directory (DEPRE‐
13462 CATED)
13463 The functionality of this extension has been included in core Mercurial
13465 since version 5.7. Please use hg purge ... instead. hg purge --confirm
13466 is now the default, unless the extension is enabled for backward com‐
13467 patibility.
13468 rebase
13470 command to move sets of revisions to a different ancestor
13471 This extension lets you rebase changesets in an existing Mercurial
13473 repository.
13474 For more information: https://mercurial-scm.org/wiki/RebaseExtension
13476 Commands
13478 Change manipulation
13479 rebase
13480 move changeset (and descendants) to a different branch:
13481 hg rebase [[-s REV]... | [-b REV]... | [-r REV]...] [-d REV] [OPTION]...
13483 Rebase uses repeated merging to graft changesets from one part of his‐
13485 tory (the source) onto another (the destination). This can be useful
13486 for linearizing local changes relative to a master development tree.
13487 Published commits cannot be rebased (see hg help phases). To copy com‐
13489 mits, see hg help graft.
13490 If you don't specify a destination changeset (-d/--dest), rebase will
13492 use the same logic as hg merge to pick a destination. if the current
13493 branch contains exactly one other head, the other head is merged with
13494 by default. Otherwise, an explicit revision with which to merge with
13495 must be provided. (destination changeset is not modified by rebasing,
13496 but new changesets are added as its descendants.)
13497 Here are the ways to select changesets:
13499 1. Explicitly select them using --rev.
13501 2. Use --source to select a root changeset and include all of its
13503 descendants.
13504 3. Use --base to select a changeset; rebase will find ancestors and
13506 their descendants which are not also ancestors of the destina‐
13507 tion.
13508 4. If you do not specify any of --rev, --source, or --base, rebase
13510 will use --base . as above.
13511 If --source or --rev is used, special names SRC and ALLSRC can be used
13513 in --dest. Destination would be calculated per source revision with SRC
13514 substituted by that single source revision and ALLSRC substituted by
13515 all source revisions.
13516 Rebase will destroy original changesets unless you use --keep. It will
13518 also move your bookmarks (even if you do).
13519 Some changesets may be dropped if they do not contribute changes (e.g.
13521 merges from the destination branch).
13522 Unlike merge, rebase will do nothing if you are at the branch tip of a
13524 named branch with two heads. You will need to explicitly specify source
13525 and/or destination.
13526 If you need to use a tool to automate merge/conflict decisions, you can
13528 specify one with --tool, see hg help merge-tools. As a caveat: the
13529 tool will not be used to mediate when a file was deleted, there is no
13530 hook presently available for this.
13531 If a rebase is interrupted to manually resolve a conflict, it can be
13533 continued with --continue/-c, aborted with --abort/-a, or stopped with
13534 --stop.
13535 Examples:
13537 • move "local changes" (current commit back to branching point) to the
13539 current branch tip after a pull:
13540 hg rebase
13542 • move a single changeset to the stable branch:
13544 hg rebase -r 5f493448 -d stable
13546 • splice a commit and all its descendants onto another part of history:
13548 hg rebase --source c0c3 --dest 4cf9
13550 • rebase everything on a branch marked by a bookmark onto the default
13552 branch:
13553 hg rebase --base myfeature --dest default
13555 • collapse a sequence of changes into a single commit:
13557 hg rebase --collapse -r 1520:1525 -d .
13559 • move a named branch while preserving its name:
13561 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
13563 • stabilize orphaned changesets so history looks linear:
13565 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
13567 Configuration Options:
13569 You can make rebase require a destination if you set the following con‐
13571 fig option:
13572 [commands]
13574 rebase.requiredest = True
13575 By default, rebase will close the transaction after each commit. For
13577 performance purposes, you can configure rebase to use a single transac‐
13578 tion across the entire rebase. WARNING: This setting introduces a sig‐
13579 nificant risk of losing the work you've done in a rebase if the rebase
13580 aborts unexpectedly:
13581 [rebase]
13583 singletransaction = True
13584 By default, rebase writes to the working copy, but you can configure it
13586 to run in-memory for better performance. When the rebase is not moving
13587 the parent(s) of the working copy (AKA the "currently checked out
13588 changesets"), this may also allow it to run even if the working copy is
13589 dirty:
13590 [rebase]
13592 experimental.inmemory = True
13593 Return Values:
13595 Returns 0 on success, 1 if nothing to rebase or there are unresolved
13597 conflicts.
13598 Options:
13600 -s,--source <REV[+]>
13602 rebase the specified changesets and their descendants
13603 -b,--base <REV[+]>
13605 rebase everything from branching point of specified changeset
13606 -r,--rev <REV[+]>
13608 rebase these revisions
13609 -d,--dest <REV>
13611 rebase onto the specified changeset
13612 --collapse
13614 collapse the rebased changesets
13615 -m,--message <TEXT>
13617 use text as collapse commit message
13618 -e, --edit
13620 invoke editor on commit messages
13621 -l,--logfile <FILE>
13623 read collapse commit message from file
13624 -k, --keep
13626 keep original changesets
13627 --keepbranches
13629 keep original branch names
13630 -D, --detach
13632 (DEPRECATED)
13633 -i, --interactive
13635 (DEPRECATED)
13636 -t,--tool <VALUE>
13638 specify merge tool
13639 --stop stop interrupted rebase
13641 -c, --continue
13643 continue an interrupted rebase
13644 -a, --abort
13646 abort an interrupted rebase
13647 --auto-orphans <VALUE>
13649 automatically rebase orphan revisions in the specified revset
13650 (EXPERIMENTAL)
13651 -n, --dry-run
13653 do not perform actions, just print output
13654 -T,--template <TEMPLATE>
13656 display with template
13657 --confirm
13659 ask before applying actions
13660 [+] marked option can be specified multiple times
13662 record
13664 commands to interactively select changes for commit/qrefresh (DEPRE‐
13665 CATED)
13666 The feature provided by this extension has been moved into core Mercu‐
13668 rial as hg commit --interactive.
13669 Commands
13671 Change creation
13672 qrecord
13673 interactively record a new patch:
13674 hg qrecord [OPTION]... PATCH [FILE]...
13676 See hg help qnew & hg help record for more information and usage.
13678 record
13680 interactively select changes to commit:
13681 hg record [OPTION]... [FILE]...
13683 If a list of files is omitted, all changes reported by hg status will
13685 be candidates for recording.
13686 See hg help dates for a list of formats valid for -d/--date.
13688 If using the text interface (see hg help config), you will be prompted
13690 for whether to record changes to each modified file, and for files with
13691 multiple changes, for each change to use. For each query, the following
13692 responses are possible:
13693 y - record this change
13695 n - skip this change
13696 e - edit this change manually
13697 s - skip remaining changes to this file
13699 f - record remaining changes to this file
13700 d - done, skip remaining changes and files
13702 a - record all changes to all remaining files
13703 q - quit, recording no changes
13704 ? - display help
13706 This command is not available when committing a merge.
13708 Options:
13710 -A, --addremove
13712 mark new/missing files as added/removed before committing
13713 --close-branch
13715 mark a branch head as closed
13716 --amend
13718 amend the parent of the working directory
13719 -s, --secret
13721 use the secret phase for committing
13722 --draft
13724 use the draft phase for committing
13725 -e, --edit
13727 invoke editor on commit messages
13728 --force-close-branch
13730 forcibly close branch from a non-head changeset (ADVANCED)
13731 -I,--include <PATTERN[+]>
13733 include names matching the given patterns
13734 -X,--exclude <PATTERN[+]>
13736 exclude names matching the given patterns
13737 -m,--message <TEXT>
13739 use text as commit message
13740 -l,--logfile <FILE>
13742 read commit message from file
13743 -d,--date <DATE>
13745 record the specified date as commit date
13746 -u,--user <USER>
13748 record the specified user as committer
13749 -S, --subrepos
13751 recurse into subrepositories
13752 -w, --ignore-all-space
13754 ignore white space when comparing lines
13755 -b, --ignore-space-change
13757 ignore changes in the amount of white space
13758 -B, --ignore-blank-lines
13760 ignore changes whose lines are all blank
13761 -Z, --ignore-space-at-eol
13763 ignore changes in whitespace at EOL
13764 [+] marked option can be specified multiple times
13766 releasenotes
13768 generate release notes from commit messages (EXPERIMENTAL)
13769 It is common to maintain files detailing changes in a project between
13771 releases. Maintaining these files can be difficult and time consuming.
13772 The hg releasenotes command provided by this extension makes the
13773 process simpler by automating it.
13774 Commands
13776 Change navigation
13777 releasenotes
13778 parse release notes from commit messages into an output file:
13779 hg releasenotes [-r REV] [-c] FILE
13781 Given an output file and set of revisions, this command will parse com‐
13783 mit messages for release notes then add them to the output file.
13784 Release notes are defined in commit messages as ReStructuredText direc‐
13786 tives. These have the form:
13787 .. directive:: title
13789 content
13791 Each directive maps to an output section in a generated release notes
13793 file, which itself is ReStructuredText. For example, the .. feature::
13794 directive would map to a New Features section.
13795 Release note directives can be either short-form or long-form. In
13797 short- form, title is omitted and the release note is rendered as a
13798 bullet list. In long form, a sub-section with the title title is added
13799 to the section.
13800 The FILE argument controls the output file to write gathered release
13802 notes to. The format of the file is:
13803 Section 1
13805 =========
13806 ...
13808 Section 2
13810 =========
13811 ...
13813 Only sections with defined release notes are emitted.
13815 If a section only has short-form notes, it will consist of bullet list:
13817 Section
13819 =======
13820 * Release note 1
13822 * Release note 2
13823 If a section has long-form notes, sub-sections will be emitted:
13825 Section
13827 =======
13828 Note 1 Title
13830 ------------
13831 Description of the first long-form note.
13833 Note 2 Title
13835 ------------
13836 Description of the second long-form note.
13838 If the FILE argument points to an existing file, that file will be
13840 parsed for release notes having the format that would be generated by
13841 this command. The notes from the processed commit messages will be
13842 merged into this parsed set.
13843 During release notes merging:
13845 • Duplicate items are automatically ignored
13847 • Items that are different are automatically ignored if the similarity
13849 is greater than a threshold.
13850 This means that the release notes file can be updated independently
13852 from this command and changes should not be lost when running this com‐
13853 mand on that file. A particular use case for this is to tweak the word‐
13854 ing of a release note after it has been added to the release notes
13855 file.
13856 The -c/--check option checks the commit message for invalid admoni‐
13858 tions.
13859 The -l/--list option, presents the user with a list of existing avail‐
13861 able admonitions along with their title. This also includes the custom
13862 admonitions (if any).
13863 Options:
13865 -r,--rev <REV>
13867 revisions to process for release notes
13868 -c, --check
13870 checks for validity of admonitions (if any)
13871 -l, --list
13873 list the available admonitions with their title
13874 Uncategorized commands
13876 relink
13877 recreates hardlinks between repository clones
13878 Commands
13880 Repository maintenance
13881 relink
13882 recreate hardlinks between two repositories:
13883 hg relink [ORIGIN]
13885 When repositories are cloned locally, their data files will be
13887 hardlinked so that they only use the space of a single repository.
13888 Unfortunately, subsequent pulls into either repository will break
13890 hardlinks for any files touched by the new changesets, even if both
13891 repositories end up pulling the same changes.
13892 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
13894 falling back to a complete copy of the source repository.
13895 This command lets you recreate those hardlinks and reclaim that wasted
13897 space.
13898 This repository will be relinked to share space with ORIGIN, which must
13900 be on the same local disk. If ORIGIN is omitted, looks for "default-re‐
13901 link", then "default", in [paths].
13902 Do not attempt any read operations on this repository while the command
13904 is running. (Both repositories will be locked against writes.)
13905 remotefilelog
13907 remotefilelog causes Mercurial to lazilly fetch file contents (EXPERI‐
13908 MENTAL)
13909 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13911 BILITY GUARANTEES. This means that repositories created with this ex‐
13912 tension may only be usable with the exact version of this exten‐
13913 sion/Mercurial that was used. The extension attempts to enforce this in
13914 order to prevent repository corruption.
13915 remotefilelog works by fetching file contents lazily and storing them
13917 in a cache on the client rather than in revlogs. This allows enormous
13918 histories to be transferred only partially, making them easier to oper‐
13919 ate on.
13920 Configs:
13922 packs.maxchainlen specifies the maximum delta chain length in pack
13924 files
13925 packs.maxpacksize specifies the maximum pack file size
13927 packs.maxpackfilecount specifies the maximum number of packs in the
13929 shared cache (trees only for now)
13931 remotefilelog.backgroundprefetch runs prefetch in background when
13933 True
13934 remotefilelog.bgprefetchrevs specifies revisions to fetch on commit
13936 and
13937 update, and on other commands that use them. Different from
13939 pullprefetch.
13940 remotefilelog.gcrepack does garbage collection during repack when
13942 True
13943 remotefilelog.nodettl specifies maximum TTL of a node in seconds be‐
13945 fore
13946 it is garbage collected
13948 remotefilelog.repackonhggc runs repack on hg gc when True
13950 remotefilelog.prefetchdays specifies the maximum age of a commit in
13952 days after which it is no longer prefetched.
13954 remotefilelog.prefetchdelay specifies delay between background
13956 prefetches in seconds after operations that change the work‐
13958 ing copy parent
13959 remotefilelog.data.gencountlimit constraints the minimum number of
13961 data
13962 pack files required to be considered part of a generation. In
13964 particular, minimum number of packs files > gencountlimit.
13965 remotefilelog.data.generations list for specifying the lower bound
13967 of
13968 each generation of the data pack files. For example, list
13970 ['100MB','1MB'] or ['1MB', '100MB'] will lead to three gener‐
13971 ations: [0, 1MB), [ 1MB, 100MB) and [100MB, infinity).
13972 remotefilelog.data.maxrepackpacks the maximum number of pack files
13974 to
13975 include in an incremental data repack.
13977 remotefilelog.data.repackmaxpacksize the maximum size of a pack file
13979 for
13980 it to be considered for an incremental data repack.
13982 remotefilelog.data.repacksizelimit the maximum total size of pack
13984 files
13985 to include in an incremental data repack.
13987 remotefilelog.history.gencountlimit constraints the minimum number
13989 of
13990 history pack files required to be considered part of a gener‐
13992 ation. In particular, minimum number of packs files > gen‐
13993 countlimit.
13994 remotefilelog.history.generations list for specifying the lower
13996 bound of
13997 each generation of the history pack files. For example, list
13999 [ '100MB', '1MB'] or ['1MB', '100MB'] will lead to three gen‐
14000 erations: [ 0, 1MB), [1MB, 100MB) and [100MB, infinity).
14001 remotefilelog.history.maxrepackpacks the maximum number of pack
14003 files to
14004 include in an incremental history repack.
14006 remotefilelog.history.repackmaxpacksize the maximum size of a pack
14008 file
14009 for it to be considered for an incremental history repack.
14011 remotefilelog.history.repacksizelimit the maximum total size of pack
14013 files to include in an incremental history repack.
14015 remotefilelog.backgroundrepack automatically consolidate packs in
14017 the
14018 background
14020 remotefilelog.cachepath path to cache
14022 remotefilelog.cachegroup if set, make cache directory sgid to this
14024 group
14026 remotefilelog.cacheprocess binary to invoke for fetching file data
14028 remotefilelog.debug turn on remotefilelog-specific debug output
14030 remotefilelog.excludepattern pattern of files to exclude from pulls
14032 remotefilelog.includepattern pattern of files to include in pulls
14034 remotefilelog.fetchwarning: message to print when too many
14036 single-file fetches occur
14038 remotefilelog.getfilesstep number of files to request in a single
14040 RPC
14041 remotefilelog.getfilestype if set to 'threaded' use threads to fetch
14043 files, otherwise use optimistic fetching
14045 remotefilelog.pullprefetch revset for selecting files that should be
14047 eagerly downloaded rather than lazily
14049 remotefilelog.reponame name of the repo. If set, used to partition
14051 data from other repos in a shared store.
14053 remotefilelog.server if true, enable server-side functionality
14055 remotefilelog.servercachepath path for caching blobs on the server
14057 remotefilelog.serverexpiration number of days to keep cached server
14059 blobs
14061 remotefilelog.validatecache if set, check cache entries for corrup‐
14063 tion
14064 before returning blobs
14066 remotefilelog.validatecachelog if set, check cache entries for
14068 corruption before returning metadata
14070 Commands
14072 Repository maintenance
14073 prefetch
14074 prefetch file revisions from the server:
14075 hg prefetch [OPTIONS] [FILE...]
14077 Prefetchs file revisions for the specified revs and stores them in the
14079 local remotefilelog cache. If no rev is specified, the default rev is
14080 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
14081 File names or patterns can be used to limit which files are downloaded.
14082 Return 0 on success.
14084 Options:
14086 -r,--rev <REV[+]>
14088 prefetch the specified revisions
14089 --repack
14091 run repack after prefetch
14092 -b,--base <VALUE>
14094 rev that is assumed to already be local
14095 -I,--include <PATTERN[+]>
14097 include names matching the given patterns
14098 -X,--exclude <PATTERN[+]>
14100 exclude names matching the given patterns
14101 [+] marked option can be specified multiple times
14103 Uncategorized commands
14105 gc
14106 garbage collect the client and server filelog caches:
14107 hg gc [REPO...]
14109 garbage collect the client and server filelog caches
14111 repack
14113 hg repack [OPTIONS]
14114 Options:
14116 --background
14118 run in a background process
14119 --incremental
14121 do an incremental repack
14122 --packsonly
14124 only repack packs (skip loose objects)
14125 verifyremotefilelog
14127 hg verifyremotefilelogs <directory>
14128 Options:
14130 -d, --decompress
14132 decompress the filelogs first
14133 remotenames
14135 showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)
14136 By default both remotebookmarks and remotebranches are turned on. Con‐
14138 fig knob to control the individually are as follows.
14139 Config options to tweak the default behaviour:
14141 remotenames.bookmarks
14143 Boolean value to enable or disable showing of remotebookmarks
14144 (default: True)
14145 remotenames.branches
14147 Boolean value to enable or disable showing of remotebranches
14148 (default: True)
14149 remotenames.hoistedpeer
14151 Name of the peer whose remotebookmarks should be hoisted into
14152 the top-level namespace (default: 'default')
14153 schemes
14155 extend schemes with shortcuts to repository swarms
14156 This extension allows you to specify shortcuts for parent URLs with a
14158 lot of repositories to act like a scheme, for example:
14159 [schemes]
14161 py = http://code.python.org/hg/
14162 After that you can use it like:
14164 hg clone py://trunk/
14166 Additionally there is support for some more complex schemas, for exam‐
14168 ple used by Google Code:
14169 [schemes]
14171 gcode = http://{1}.googlecode.com/hg/
14172 The syntax is taken from Mercurial templates, and you have unlimited
14174 number of variables, starting with {1} and continuing with {2}, {3} and
14175 so on. This variables will receive parts of URL supplied, split by /.
14176 Anything not specified as {part} will be just appended to an URL.
14177 For convenience, the extension adds these schemes by default:
14179 [schemes]
14181 py = http://hg.python.org/
14182 bb = https://bitbucket.org/
14183 bb+ssh = ssh://hg@bitbucket.org/
14184 gcode = https://{1}.googlecode.com/hg/
14185 kiln = https://{1}.kilnhg.com/Repo/
14186 You can override a predefined scheme by defining a new scheme with the
14188 same name.
14189 Commands
14191 Uncategorized commands
14192 share
14193 share a common history between several working directories
14194 The share extension introduces a new command hg share to create a new
14196 working directory. This is similar to hg clone, but doesn't involve
14197 copying or linking the storage of the repository. This allows working
14198 on different branches or changes in parallel without the associated
14199 cost in terms of disk space.
14200 Note: destructive operations or extensions like hg rollback should be
14202 used with care as they can result in confusing problems.
14203 Automatic Pooled Storage for Clones
14205 When this extension is active, hg clone can be configured to automati‐
14206 cally share/pool storage across multiple clones. This mode effectively
14207 converts hg clone to hg clone + hg share. The benefit of using this
14208 mode is the automatic management of store paths and intelligent pooling
14209 of related repositories.
14210 The following share. config options influence this feature:
14212 share.pool
14214 Filesystem path where shared repository data will be stored.
14216 When defined, hg clone will automatically use shared repository
14217 storage instead of creating a store inside each clone.
14218 share.poolnaming
14220 How directory names in share.pool are constructed.
14222 "identity" means the name is derived from the first changeset in
14224 the repository. In this mode, different remotes share storage if
14225 their root/initial changeset is identical. In this mode, the lo‐
14226 cal shared repository is an aggregate of all encountered remote
14227 repositories.
14228 "remote" means the name is derived from the source repository's
14230 path or URL. In this mode, storage is only shared if the path or
14231 URL requested in the hg clone command matches exactly to a
14232 repository that was cloned before.
14233 The default naming mode is "identity".
14235 Sharing requirements and configs of source repository with shares:
14237 By default creating a shared repository only enables sharing a common
14239 history and does not share requirements and configs between them. This
14240 may lead to problems in some cases, for example when you upgrade the
14241 storage format from one repository but does not set related configs in
14242 the shares.
14243 Setting format.exp-share-safe = True enables sharing configs and re‐
14245 quirements. This only applies to shares which are done after enabling
14246 the config option.
14247 For enabling this in existing shares, enable the config option and re‐
14249 share.
14250 For resharing existing shares, make sure your working directory is
14252 clean and there are no untracked files, delete that share and create a
14253 new share.
14254 Commands
14256 Repository creation
14257 share
14258 create a new shared repository:
14259 hg share [-U] [-B] SOURCE [DEST]
14261 Initialize a new repository and working directory that shares its his‐
14263 tory (and optionally bookmarks) with another repository.
14264 Note using rollback or extensions that destroy/modify history (mq,
14266 rebase, etc.) can cause considerable confusion with shared
14267 clones. In particular, if two shared clones are both updated to
14268 the same changeset, and one of them destroys that changeset with
14269 rollback, the other clone will suddenly stop working: all opera‐
14270 tions will fail with "abort: working directory has unknown par‐
14271 ent". The only known workaround is to use debugsetparents on the
14272 broken clone to reset it to a changeset that still exists.
14273 Options:
14275 -U, --noupdate
14277 do not create a working directory
14278 -B, --bookmarks
14280 also share bookmarks
14281 --relative
14283 point to source using a relative path
14284 Repository maintenance
14286 unshare
14287 convert a shared repository to a normal one:
14288 hg unshare
14290 Copy the store data to the repo and remove the sharedpath data.
14292 show
14294 unified command to show various repository information (EXPERIMENTAL)
14295 This extension provides the hg show command, which provides a central
14297 command for displaying commonly-accessed repository data and views of
14298 that data.
14299 The following config options can influence operation.
14301 commands
14303 show.aliasprefix
14304 List of strings that will register aliases for views. e.g. s
14306 will effectively set config options alias.s<view> = show <view>
14307 for all views. i.e. hg swork would execute hg show work.
14308 Aliases that would conflict with existing registrations will not
14310 be performed.
14311 Commands
14313 Change navigation
14314 show
14315 show various repository information:
14316 hg show VIEW
14318 A requested view of repository data is displayed.
14320 If no view is requested, the list of available views is shown and the
14322 command aborts.
14323 Note There are no backwards compatibility guarantees for the output
14325 of this command. Output may change in any future Mercurial re‐
14326 lease.
14327 Consumers wanting stable command output should specify a tem‐
14329 plate via -T/--template.
14330 List of available views:
14332 bookmarks bookmarks and their associated changeset
14334 stack current line of work
14336 work changesets that aren't finished
14338 Options:
14340 -T,--template <TEMPLATE>
14342 display with template
14343 sparse
14345 allow sparse checkouts of the working directory (EXPERIMENTAL)
14346 (This extension is not yet protected by backwards compatibility guaran‐
14348 tees. Any aspect may break in future releases until this notice is re‐
14349 moved.)
14350 This extension allows the working directory to only consist of a subset
14352 of files for the revision. This allows specific files or directories to
14353 be explicitly included or excluded. Many repository operations have
14354 performance proportional to the number of files in the working direc‐
14355 tory. So only realizing a subset of files in the working directory can
14356 improve performance.
14357 Sparse Config Files
14359 The set of files that are part of a sparse checkout are defined by a
14360 sparse config file. The file defines 3 things: includes (files to in‐
14361 clude in the sparse checkout), excludes (files to exclude from the
14362 sparse checkout), and profiles (links to other config files).
14363 The file format is newline delimited. Empty lines and lines beginning
14365 with # are ignored.
14366 Lines beginning with %include `` denote another sparse config file to
14368 include. e.g. ``%include tests.sparse. The filename is relative to the
14369 repository root.
14370 The special lines [include] and [exclude] denote the section for in‐
14372 cludes and excludes that follow, respectively. It is illegal to have
14373 [include] after [exclude].
14374 Non-special lines resemble file patterns to be added to either includes
14376 or excludes. The syntax of these lines is documented by hg help pat‐
14377 terns. Patterns are interpreted as glob: by default and match against
14378 the root of the repository.
14379 Exclusion patterns take precedence over inclusion patterns. So even if
14381 a file is explicitly included, an [exclude] entry can remove it.
14382 For example, say you have a repository with 3 directories, frontend/,
14384 backend/, and tools/. frontend/ and backend/ correspond to different
14385 projects and it is uncommon for someone working on one to need the
14386 files for the other. But tools/ contains files shared between both
14387 projects. Your sparse config files may resemble:
14388 # frontend.sparse
14390 frontend/**
14391 tools/**
14392 # backend.sparse
14394 backend/**
14395 tools/**
14396 Say the backend grows in size. Or there's a directory with thousands of
14398 files you wish to exclude. You can modify the profile to exclude cer‐
14399 tain files:
14400 [include]
14402 backend/**
14403 tools/**
14404 [exclude]
14406 tools/tests/**
14407 Commands
14409 Uncategorized commands
14410 split
14411 command to split a changeset into smaller ones (EXPERIMENTAL)
14412 Commands
14414 Change manipulation
14415 split
14416 split a changeset into smaller ones:
14417 hg split [--no-rebase] [[-r] REV]
14419 Repeatedly prompt changes and commit message for new changesets until
14421 there is nothing left in the original changeset.
14422 If --rev was not given, split the working directory parent.
14424 By default, rebase connected non-obsoleted descendants onto the new
14426 changeset. Use --no-rebase to avoid the rebase.
14427 Options:
14429 -r,--rev <REV>
14431 revision to split
14432 --rebase
14434 rebase descendants after split (default: True)
14435 -d,--date <DATE>
14437 record the specified date as commit date
14438 -u,--user <USER>
14440 record the specified user as committer
14441 sqlitestore
14443 store repository data in SQLite (EXPERIMENTAL)
14444 The sqlitestore extension enables the storage of repository data in
14446 SQLite.
14447 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
14449 BILITY GUARANTEES. This means that repositories created with this ex‐
14450 tension may only be usable with the exact version of this exten‐
14451 sion/Mercurial that was used. The extension attempts to enforce this in
14452 order to prevent repository corruption.
14453 In addition, several features are not yet supported or have known bugs:
14455 • Only some data is stored in SQLite. Changeset, manifest, and other
14457 repository data is not yet stored in SQLite.
14458 • Transactions are not robust. If the process is aborted at the right
14460 time during transaction close/rollback, the repository could be in an
14461 inconsistent state. This problem will diminish once all repository
14462 data is tracked by SQLite.
14463 • Bundle repositories do not work (the ability to use e.g. hg -R <bun‐
14465 dle-file> log to automatically overlay a bundle on top of the exist‐
14466 ing repository).
14467 • Various other features don't work.
14469 This extension should work for basic clone/pull, update, and commit
14471 workflows. Some history rewriting operations may fail due to lack of
14472 support for bundle repositories.
14473 To use, activate the extension and set the storage.new-repo-backend
14475 config option to sqlite to enable new repositories to use SQLite for
14476 storage.
14477 strip
14479 strip changesets and their descendants from history (DEPRECATED)
14480 The functionality of this extension has been included in core Mercurial
14482 since version 5.7. Please use hg debugstrip ... instead.
14483 This extension allows you to strip changesets and all their descendants
14485 from the repository. See the command help for details.
14486 transplant
14488 command to transplant changesets from another branch
14489 This extension allows you to transplant changes to another parent revi‐
14491 sion, possibly in another repository. The transplant is done using
14492 'diff' patches.
14493 Transplanted patches are recorded in .hg/transplant/transplants, as a
14495 map from a changeset hash to its hash in the source repository.
14496 Commands
14498 Change manipulation
14499 transplant
14500 transplant changesets from another branch:
14501 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
14503 Selected changesets will be applied on top of the current working di‐
14505 rectory with the log of the original changeset. The changesets are
14506 copied and will thus appear twice in the history with different identi‐
14507 ties.
14508 Consider using the graft command if everything is inside the same
14510 repository - it will use merges and will usually give a better result.
14511 Use the rebase extension if the changesets are unpublished and you want
14512 to move them instead of copying them.
14513 If --log is specified, log messages will have a comment appended of the
14515 form:
14516 (transplanted from CHANGESETHASH)
14518 You can rewrite the changelog message with the --filter option. Its
14520 argument will be invoked with the current changelog message as $1 and
14521 the patch as $2.
14522 --source/-s specifies another repository to use for selecting change‐
14524 sets, just as if it temporarily had been pulled. If --branch/-b is
14525 specified, these revisions will be used as heads when deciding which
14526 changesets to transplant, just as if only these revisions had been
14527 pulled. If --all/-a is specified, all the revisions up to the heads
14528 specified with --branch will be transplanted.
14529 Example:
14531 • transplant all changes up to REV on top of your current revision:
14533 hg transplant --branch REV --all
14535 You can optionally mark selected transplanted changesets as merge
14537 changesets. You will not be prompted to transplant any ancestors of a
14538 merged transplant, and you can merge descendants of them normally in‐
14539 stead of transplanting them.
14540 Merge changesets may be transplanted directly by specifying the proper
14542 parent changeset by calling hg transplant --parent.
14543 If no merges or revisions are provided, hg transplant will start an in‐
14545 teractive changeset browser.
14546 If a changeset application fails, you can fix the merge by hand and
14548 then resume where you left off by calling hg transplant --continue/-c.
14549 Options:
14551 -s,--source <REPO>
14553 transplant changesets from REPO
14554 -b,--branch <REV[+]>
14556 use this source changeset as head
14557 -a, --all
14559 pull all changesets up to the --branch revisions
14560 -p,--prune <REV[+]>
14562 skip over REV
14563 -m,--merge <REV[+]>
14565 merge at REV
14566 --parent <REV>
14568 parent to choose when transplanting merge
14569 -e, --edit
14571 invoke editor on commit messages
14572 --log append transplant info to log message
14574 --stop stop interrupted transplant
14576 -c, --continue
14578 continue last transplant session after fixing conflicts
14579 --filter <CMD>
14581 filter changesets through command
14582 [+] marked option can be specified multiple times
14584 uncommit
14586 uncommit part or all of a local changeset (EXPERIMENTAL)
14587 This command undoes the effect of a local commit, returning the af‐
14589 fected files to their uncommitted state. This means that files modi‐
14590 fied, added or removed in the changeset will be left unchanged, and so
14591 will remain modified, added and removed in the working directory.
14592 Commands
14594 Change manipulation
14595 unamend
14596 undo the most recent amend operation on a current changeset:
14597 hg unamend
14599 This command will roll back to the previous version of a changeset,
14601 leaving working directory in state in which it was before running hg
14602 amend (e.g. files modified as part of an amend will be marked as modi‐
14603 fied hg status)
14604 uncommit
14606 uncommit part or all of a local changeset:
14607 hg uncommit [OPTION]... [FILE]...
14609 This command undoes the effect of a local commit, returning the af‐
14611 fected files to their uncommitted state. This means that files modified
14612 or deleted in the changeset will be left unchanged, and so will remain
14613 modified in the working directory.
14614 If no files are specified, the commit will be pruned, unless --keep is
14616 given.
14617 Options:
14619 --keep allow an empty commit after uncommitting
14621 --allow-dirty-working-copy
14623 allow uncommit with outstanding changes
14624 -n,--note <TEXT>
14626 store a note on uncommit
14627 -I,--include <PATTERN[+]>
14629 include names matching the given patterns
14630 -X,--exclude <PATTERN[+]>
14632 exclude names matching the given patterns
14633 -m,--message <TEXT>
14635 use text as commit message
14636 -l,--logfile <FILE>
14638 read commit message from file
14639 -d,--date <DATE>
14641 record the specified date as commit date
14642 -u,--user <USER>
14644 record the specified user as committer
14645 -D, --currentdate
14647 record the current date as commit date
14648 -U, --currentuser
14650 record the current user as committer
14651 [+] marked option can be specified multiple times
14653 win32mbcs
14655 allow the use of MBCS paths with problematic encodings
14656 Some MBCS encodings are not good for some path operations (i.e. split‐
14658 ting path, case conversion, etc.) with its encoded bytes. We call such
14659 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
14660 extension can be used to fix the issue with those encodings by wrapping
14661 some functions to convert to Unicode string before path operation.
14662 This extension is useful for:
14664 • Japanese Windows users using shift_jis encoding.
14666 • Chinese Windows users using big5 encoding.
14668 • All users who use a repository with one of problematic encodings on
14670 case-insensitive file system.
14671 This extension is not needed for:
14673 • Any user who use only ASCII chars in path.
14675 • Any user who do not use any of problematic encodings.
14677 Note that there are some limitations on using this extension:
14679 • You should use single encoding in one repository.
14681 • If the repository path ends with 0x5c, .hg/hgrc cannot be read.
14683 • win32mbcs is not compatible with fixutf8 extension.
14685 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
14687 can specify the encoding by config option:
14688 [win32mbcs]
14690 encoding = sjis
14691 It is useful for the users who want to commit with UTF-8 log message.
14693 win32text
14695 perform automatic newline conversion (DEPRECATED)
14696 Deprecation: The win32text extension requires each user to configure
14698 the extension again and again for each clone since the configuration
14699 is not copied when cloning.
14700 We have therefore made the eol as an alternative. The eol uses a
14702 version controlled file for its configuration and each clone will
14703 therefore use the right settings from the start.
14704 To perform automatic newline conversion, use:
14706 [extensions]
14708 win32text =
14709 [encode]
14710 ** = cleverencode:
14711 # or ** = macencode:
14712 [decode]
14714 ** = cleverdecode:
14715 # or ** = macdecode:
14716 If not doing conversion, to make sure you do not commit CRLF/CR by ac‐
14718 cident:
14719 [hooks]
14721 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
14722 # or pretxncommit.cr = python:hgext.win32text.forbidcr
14723 To do the same check on a server to prevent CRLF/CR from being pushed
14725 or pulled:
14726 [hooks]
14728 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
14729 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
14730 zeroconf
14732 discover and advertise repositories on the local network
14733 The zeroconf extension will advertise hg serve instances over DNS-SD so
14735 that they can be discovered using the hg paths command without knowing
14736 the server's IP address.
14737 To allow other people to discover your repository using run hg serve in
14739 your repository:
14740 $ cd test
14742 $ hg serve
14743 You can discover Zeroconf-enabled repositories by running hg paths:
14745 $ hg paths
14747 zc-test = http://example.com:8000/test
14748
14750 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
14751 This file contains defaults and configuration. Values in
14753 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
14754 tings made in the global /etc/mercurial/hgrc configuration. See
14755 hgrc(5) for details of the contents and format of these files.
14756 .hgignore
14758 This file contains regular expressions (one per line) that de‐
14760 scribe file names that should be ignored by hg. For details, see
14761 hgignore(5).
14762 .hgsub
14764 This file defines the locations of all subrepositories, and
14766 tells where the subrepository checkouts came from. For details,
14767 see hg help subrepos.
14768 .hgsubstate
14770 This file is where Mercurial stores all nested repository
14772 states. NB: This file should not be edited manually.
14773 .hgtags
14775 This file contains changeset hash values and text tag names (one
14777 of each separated by spaces) that correspond to tagged versions
14778 of the repository contents. The file content is encoded using
14779 UTF-8.
14780 .hg/last-message.txt
14782 This file is used by hg commit to store a backup of the commit
14784 message in case the commit fails.
14785 .hg/localtags
14787 This file can be used to define local tags which are not shared
14789 among repositories. The file format is the same as for .hgtags,
14790 but it is encoded using the local system encoding.
14791 Some commands (e.g. revert) produce backup files ending in .orig, if
14793 the .orig file already exists and is not tracked by Mercurial, it will
14794 be overwritten.
14795
14797 Probably lots, please post them to the mailing list (see Resources
14798 below) when you find them.
14799
14801 hgignore(5), hgrc(5)
14802
14804 Written by Olivia Mackall <olivia@selenic.com>
14805
14807 Main Web Site: https://mercurial-scm.org/
14808 Source code repository: https://www.mercurial-scm.org/repo/hg
14810 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
14812
14814 Copyright (C) 2005-2023 Olivia Mackall. Free use of this software is
14815 granted under the terms of the GNU General Public License version 2 or
14816 any later version.
14817
14819 Olivia Mackall <olivia@selenic.com>
14820 Organization: Mercurial
14822 HG(1)