1HG(1) Mercurial Manual HG(1)
2
6 hg - Mercurial source code management system
7
9 hg command [option]... [argument]...
10
12 The hg command provides a command line interface to the Mercurial sys‐
13 tem.
14
16 files...
17 indicates one or more filename or relative path filenames; see
18 File Name Patterns for information on pattern matching
19 path indicates a path on the local machine
21 revision
23 indicates a changeset which can be specified as a changeset
24 revision number, a tag, or a unique substring of the changeset
25 hash value
26 repository path
28 either the pathname of a local repository or the URI of a remote
29 repository.
30
32 -R,--repository <REPO>
33 repository root directory or name of overlay bundle file
34 --cwd <DIR>
36 change working directory
37 -y, --noninteractive
39 do not prompt, automatically pick the first choice for all
40 prompts
41 -q, --quiet
43 suppress output
44 -v, --verbose
46 enable additional output
47 --color <TYPE>
49 when to colorize (boolean, always, auto, never, or debug)
50 --config <CONFIG[+]>
52 set/override config option (use 'section.name=value')
53 --debug
55 enable debugging output
56 --debugger
58 start debugger
59 --encoding <ENCODE>
61 set the charset encoding (default: UTF-8)
62 --encodingmode <MODE>
64 set the charset encoding mode (default: strict)
65 --traceback
67 always print a traceback on exception
68 --time time how long the command takes
70 --profile
72 print command execution profile
73 --version
75 output version information and exit
76 -h, --help
78 display help and exit
79 --hidden
81 consider hidden changesets
82 --pager <TYPE>
84 when to paginate (boolean, always, auto, or never) (default:
85 auto)
86 [+] marked option can be specified multiple times
88
90 add
91 add the specified files on the next commit:
92 hg add [OPTION]... [FILE]...
94 Schedule files to be version controlled and added to the repository.
96 The files will be added to the repository at the next commit. To undo
98 an add before that, see hg forget.
99 If no names are given, add all files to the repository (except files
101 matching .hgignore).
102 Examples:
104 · New (unknown) files are added automatically by hg add:
106 $ ls
108 foo.c
109 $ hg status
110 ? foo.c
111 $ hg add
112 adding foo.c
113 $ hg status
114 A foo.c
115 · Specific files to be added can be specified:
117 $ ls
119 bar.c foo.c
120 $ hg status
121 ? bar.c
122 ? foo.c
123 $ hg add bar.c
124 $ hg status
125 A bar.c
126 ? foo.c
127 Returns 0 if all files are successfully added.
129 Options:
131 -I,--include <PATTERN[+]>
133 include names matching the given patterns
134 -X,--exclude <PATTERN[+]>
136 exclude names matching the given patterns
137 -S, --subrepos
139 recurse into subrepositories
140 -n, --dry-run
142 do not perform actions, just print output
143 [+] marked option can be specified multiple times
145 addremove
147 add all new files, delete all missing files:
148 hg addremove [OPTION]... [FILE]...
150 Add all new files and remove all missing files from the repository.
152 Unless names are given, new files are ignored if they match any of the
154 patterns in .hgignore. As with add, these changes take effect at the
155 next commit.
156 Use the -s/--similarity option to detect renamed files. This option
158 takes a percentage between 0 (disabled) and 100 (files must be identi‐
159 cal) as its parameter. With a parameter greater than 0, this compares
160 every removed file with every added file and records those similar
161 enough as renames. Detecting renamed files this way can be expensive.
162 After using this option, hg status -C can be used to check which files
163 were identified as moved or renamed. If not specified, -s/--similarity
164 defaults to 100 and only renames of identical files are detected.
165 Examples:
167 · A number of files (bar.c and foo.c) are new, while foobar.c has
169 been removed (without using hg remove) from the repository:
170 $ ls
172 bar.c foo.c
173 $ hg status
174 ! foobar.c
175 ? bar.c
176 ? foo.c
177 $ hg addremove
178 adding bar.c
179 adding foo.c
180 removing foobar.c
181 $ hg status
182 A bar.c
183 A foo.c
184 R foobar.c
185 · A file foobar.c was moved to foo.c without using hg rename.
187 Afterwards, it was edited slightly:
188 $ ls
190 foo.c
191 $ hg status
192 ! foobar.c
193 ? foo.c
194 $ hg addremove --similarity 90
195 removing foobar.c
196 adding foo.c
197 recording removal of foobar.c as rename to foo.c (94% similar)
198 $ hg status -C
199 A foo.c
200 foobar.c
201 R foobar.c
202 Returns 0 if all files are successfully added.
204 Options:
206 -s,--similarity <SIMILARITY>
208 guess renamed files by similarity (0<=s<=100)
209 -S, --subrepos
211 recurse into subrepositories
212 -I,--include <PATTERN[+]>
214 include names matching the given patterns
215 -X,--exclude <PATTERN[+]>
217 exclude names matching the given patterns
218 -n, --dry-run
220 do not perform actions, just print output
221 [+] marked option can be specified multiple times
223 annotate
225 show changeset information by line for each file:
226 hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...
228 List changes in files, showing the revision id responsible for each
230 line.
231 This command is useful for discovering when a change was made and by
233 whom.
234 If you include --file, --user, or --date, the revision number is sup‐
236 pressed unless you also include --number.
237 Without the -a/--text option, annotate will avoid processing files it
239 detects as binary. With -a, annotate will annotate the file anyway,
240 although the results will probably be neither useful nor desirable.
241 Template:
243 The following keywords are supported in addition to the common template
245 keywords and functions. See also hg help templates.
246 lines List of lines with annotation data.
248 path String. Repository-absolute path of the specified file.
250 And each entry of {lines} provides the following sub-keywords in addi‐
252 tion to {date}, {node}, {rev}, {user}, etc.
253 line String. Line content.
255 lineno Integer. Line number at that revision.
257 path String. Repository-absolute path of the file at that revision.
259 See hg help templates.operators for the list expansion syntax.
261 Returns 0 on success.
263 Options:
265 -r,--rev <REV>
267 annotate the specified revision
268 --follow
270 follow copies/renames and list the filename (DEPRECATED)
271 --no-follow
273 don't follow copies and renames
274 -a, --text
276 treat all files as text
277 -u, --user
279 list the author (long with -v)
280 -f, --file
282 list the filename
283 -d, --date
285 list the date (short with -q)
286 -n, --number
288 list the revision number (default)
289 -c, --changeset
291 list the changeset
292 -l, --line-number
294 show line number at the first appearance
295 --skip <REV[+]>
297 revision to not display (EXPERIMENTAL)
298 -w, --ignore-all-space
300 ignore white space when comparing lines
301 -b, --ignore-space-change
303 ignore changes in the amount of white space
304 -B, --ignore-blank-lines
306 ignore changes whose lines are all blank
307 -Z, --ignore-space-at-eol
309 ignore changes in whitespace at EOL
310 -I,--include <PATTERN[+]>
312 include names matching the given patterns
313 -X,--exclude <PATTERN[+]>
315 exclude names matching the given patterns
316 -T,--template <TEMPLATE>
318 display with template
319 [+] marked option can be specified multiple times
321 aliases: blame
323 archive
325 create an unversioned archive of a repository revision:
326 hg archive [OPTION]... DEST
328 By default, the revision used is the parent of the working directory;
330 use -r/--rev to specify a different revision.
331 The archive type is automatically detected based on file extension (to
333 override, use -t/--type).
334 Examples:
336 · create a zip file containing the 1.0 release:
338 hg archive -r 1.0 project-1.0.zip
340 · create a tarball excluding .hg files:
342 hg archive project.tar.gz -X ".hg*"
344 Valid types are:
346 files
348 a directory full of files (default)
350 tar
352 tar archive, uncompressed
354 tbz2
356 tar archive, compressed using bzip2
358 tgz
360 tar archive, compressed using gzip
362 uzip
364 zip archive, uncompressed
366 zip
368 zip archive, compressed using deflate
370 The exact name of the destination archive or directory is given using a
372 format string; see hg help export for details.
373 Each member added to an archive file has a directory prefix prepended.
375 Use -p/--prefix to specify a format string for the prefix. The default
376 is the basename of the archive, with suffixes removed.
377 Returns 0 on success.
379 Options:
381 --no-decode
383 do not pass files through decoders
384 -p,--prefix <PREFIX>
386 directory prefix for files in archive
387 -r,--rev <REV>
389 revision to distribute
390 -t,--type <TYPE>
392 type of distribution to create
393 -S, --subrepos
395 recurse into subrepositories
396 -I,--include <PATTERN[+]>
398 include names matching the given patterns
399 -X,--exclude <PATTERN[+]>
401 exclude names matching the given patterns
402 [+] marked option can be specified multiple times
404 backout
406 reverse effect of earlier changeset:
407 hg backout [OPTION]... [-r] REV
409 Prepare a new changeset with the effect of REV undone in the current
411 working directory. If no conflicts were encountered, it will be commit‐
412 ted immediately.
413 If REV is the parent of the working directory, then this new changeset
415 is committed automatically (unless --no-commit is specified).
416 Note hg backout cannot be used to fix either an unwanted or incorrect
418 merge.
419 Examples:
421 · Reverse the effect of the parent of the working directory. This
423 backout will be committed immediately:
424 hg backout -r .
426 · Reverse the effect of previous bad revision 23:
428 hg backout -r 23
430 · Reverse the effect of previous bad revision 23 and leave changes
432 uncommitted:
433 hg backout -r 23 --no-commit
435 hg commit -m "Backout revision 23"
436 By default, the pending changeset will have one parent, maintaining a
438 linear history. With --merge, the pending changeset will instead have
439 two parents: the old parent of the working directory and a new child of
440 REV that simply undoes REV.
441 Before version 1.7, the behavior without --merge was equivalent to
443 specifying --merge followed by hg update --clean . to cancel the merge
444 and leave the child of REV as a head to be merged separately.
445 See hg help dates for a list of formats valid for -d/--date.
447 See hg help revert for a way to restore files to the state of another
449 revision.
450 Returns 0 on success, 1 if nothing to backout or there are unresolved
452 files.
453 Options:
455 --merge
457 merge with old dirstate parent after backout
458 --commit
460 commit if no conflicts were encountered (DEPRECATED)
461 --no-commit
463 do not commit
464 --parent <REV>
466 parent to choose when backing out merge (DEPRECATED)
467 -r,--rev <REV>
469 revision to backout
470 -e, --edit
472 invoke editor on commit messages
473 -t,--tool <TOOL>
475 specify merge tool
476 -I,--include <PATTERN[+]>
478 include names matching the given patterns
479 -X,--exclude <PATTERN[+]>
481 exclude names matching the given patterns
482 -m,--message <TEXT>
484 use text as commit message
485 -l,--logfile <FILE>
487 read commit message from file
488 -d,--date <DATE>
490 record the specified date as commit date
491 -u,--user <USER>
493 record the specified user as committer
494 [+] marked option can be specified multiple times
496 bisect
498 subdivision search of changesets:
499 hg bisect [-gbsr] [-U] [-c CMD] [REV]
501 This command helps to find changesets which introduce problems. To use,
503 mark the earliest changeset you know exhibits the problem as bad, then
504 mark the latest changeset which is free from the problem as good.
505 Bisect will update your working directory to a revision for testing
506 (unless the -U/--noupdate option is specified). Once you have performed
507 tests, mark the working directory as good or bad, and bisect will
508 either update to another candidate changeset or announce that it has
509 found the bad revision.
510 As a shortcut, you can also use the revision argument to mark a revi‐
512 sion as good or bad without checking it out first.
513 If you supply a command, it will be used for automatic bisection. The
515 environment variable HG_NODE will contain the ID of the changeset being
516 tested. The exit status of the command will be used to mark revisions
517 as good or bad: status 0 means good, 125 means to skip the revision,
518 127 (command not found) will abort the bisection, and any other
519 non-zero exit status means the revision is bad.
520 Some examples:
522 · start a bisection with known bad revision 34, and good revision 12:
524 hg bisect --bad 34
526 hg bisect --good 12
527 · advance the current bisection by marking current revision as good or
529 bad:
530 hg bisect --good
532 hg bisect --bad
533 · mark the current revision, or a known revision, to be skipped (e.g.
535 if that revision is not usable because of another issue):
536 hg bisect --skip
538 hg bisect --skip 23
539 · skip all revisions that do not touch directories foo or bar:
541 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
543 · forget the current bisection:
545 hg bisect --reset
547 · use 'make && make tests' to automatically find the first broken revi‐
549 sion:
550 hg bisect --reset
552 hg bisect --bad 34
553 hg bisect --good 12
554 hg bisect --command "make && make tests"
555 · see all changesets whose states are already known in the current
557 bisection:
558 hg log -r "bisect(pruned)"
560 · see the changeset currently being bisected (especially useful if run‐
562 ning with -U/--noupdate):
563 hg log -r "bisect(current)"
565 · see all changesets that took part in the current bisection:
567 hg log -r "bisect(range)"
569 · you can even get a nice graph:
571 hg log --graph -r "bisect(range)"
573 See hg help revisions.bisect for more about the bisect() predicate.
575 Returns 0 on success.
577 Options:
579 -r, --reset
581 reset bisect state
582 -g, --good
584 mark changeset good
585 -b, --bad
587 mark changeset bad
588 -s, --skip
590 skip testing changeset
591 -e, --extend
593 extend the bisect range
594 -c,--command <CMD>
596 use command to check changeset state
597 -U, --noupdate
599 do not update to target
600 bookmarks
602 create a new bookmark or list existing bookmarks:
603 hg bookmarks [OPTIONS]... [NAME]...
605 Bookmarks are labels on changesets to help track lines of development.
607 Bookmarks are unversioned and can be moved, renamed and deleted.
608 Deleting or moving a bookmark has no effect on the associated change‐
609 sets.
610 Creating or updating to a bookmark causes it to be marked as 'active'.
612 The active bookmark is indicated with a '*'. When a commit is made,
613 the active bookmark will advance to the new commit. A plain hg update
614 will also advance an active bookmark, if possible. Updating away from
615 a bookmark will cause it to be deactivated.
616 Bookmarks can be pushed and pulled between repositories (see hg help
618 push and hg help pull). If a shared bookmark has diverged, a new
619 'divergent bookmark' of the form 'name@path' will be created. Using hg
620 merge will resolve the divergence.
621 Specifying bookmark as '.' to -m/-d/-l options is equivalent to speci‐
623 fying the active bookmark's name.
624 A bookmark named '@' has the special property that hg clone will check
626 it out by default if it exists.
627 Template:
629 The following keywords are supported in addition to the common template
631 keywords and functions such as {bookmark}. See also hg help templates.
632 active Boolean. True if the bookmark is active.
634 Examples:
636 · create an active bookmark for a new line of development:
638 hg book new-feature
640 · create an inactive bookmark as a place marker:
642 hg book -i reviewed
644 · create an inactive bookmark on another changeset:
646 hg book -r .^ tested
648 · rename bookmark turkey to dinner:
650 hg book -m turkey dinner
652 · move the '@' bookmark from another branch:
654 hg book -f @
656 · print only the active bookmark name:
658 hg book -ql .
660 Options:
662 -f, --force
664 force
665 -r,--rev <REV>
667 revision for bookmark action
668 -d, --delete
670 delete a given bookmark
671 -m,--rename <OLD>
673 rename a given bookmark
674 -i, --inactive
676 mark a bookmark inactive
677 -l, --list
679 list existing bookmarks
680 -T,--template <TEMPLATE>
682 display with template
683 aliases: bookmark
685 branch
687 set or show the current branch name:
688 hg branch [-fC] [NAME]
690 Note Branch names are permanent and global. Use hg bookmark to create
692 a light-weight bookmark instead. See hg help glossary for more
693 information about named branches and bookmarks.
694 With no argument, show the current branch name. With one argument, set
696 the working directory branch name (the branch will not exist in the
697 repository until the next commit). Standard practice recommends that
698 primary development take place on the 'default' branch.
699 Unless -f/--force is specified, branch will not let you set a branch
701 name that already exists.
702 Use -C/--clean to reset the working directory branch to that of the
704 parent of the working directory, negating a previous branch change.
705 Use the command hg update to switch to an existing branch. Use hg com‐
707 mit --close-branch to mark this branch head as closed. When all heads
708 of a branch are closed, the branch will be considered closed.
709 Returns 0 on success.
711 Options:
713 -f, --force
715 set branch name even if it shadows an existing branch
716 -C, --clean
718 reset branch name to parent branch name
719 -r,--rev <VALUE[+]>
721 change branches of the given revs (EXPERIMENTAL)
722 [+] marked option can be specified multiple times
724 branches
726 list repository named branches:
727 hg branches [-c]
729 List the repository's named branches, indicating which ones are inac‐
731 tive. If -c/--closed is specified, also list branches which have been
732 marked closed (see hg commit --close-branch).
733 Use the command hg update to switch to an existing branch.
735 Template:
737 The following keywords are supported in addition to the common template
739 keywords and functions such as {branch}. See also hg help templates.
740 active Boolean. True if the branch is active.
742 closed Boolean. True if the branch is closed.
744 current
746 Boolean. True if it is the current branch.
747 Returns 0.
749 Options:
751 -a, --active
753 show only branches that have unmerged heads (DEPRECATED)
754 -c, --closed
756 show normal and closed branches
757 -r,--rev <VALUE[+]>
759 show branch name(s) of the given rev
760 -T,--template <TEMPLATE>
762 display with template
763 [+] marked option can be specified multiple times
765 bundle
767 create a bundle file:
768 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]
770 Generate a bundle file containing data to be transferred to another
772 repository.
773 To create a bundle containing all changesets, use -a/--all (or --base
775 null). Otherwise, hg assumes the destination will have all the nodes
776 you specify with --base parameters. Otherwise, hg will assume the
777 repository has all the nodes in destination, or default-push/default if
778 no destination is specified, where destination is the repository you
779 provide through DEST option.
780 You can change bundle format with the -t/--type option. See hg help
782 bundlespec for documentation on this format. By default, the most
783 appropriate format is used and compression defaults to bzip2.
784 The bundle file can then be transferred using conventional means and
786 applied to another repository with the unbundle or pull command. This
787 is useful when direct push and pull are not available or when exporting
788 an entire repository is undesirable.
789 Applying bundles preserves all changeset contents including permis‐
791 sions, copy/rename information, and revision history.
792 Returns 0 on success, 1 if no changes found.
794 Options:
796 -f, --force
798 run even when the destination is unrelated
799 -r,--rev <REV[+]>
801 a changeset intended to be added to the destination
802 -b,--branch <BRANCH[+]>
804 a specific branch you would like to bundle
805 --base <REV[+]>
807 a base changeset assumed to be available at the destination
808 -a, --all
810 bundle all changesets in the repository
811 -t,--type <TYPE>
813 bundle compression type to use (default: bzip2)
814 -e,--ssh <CMD>
816 specify ssh command to use
817 --remotecmd <CMD>
819 specify hg command to run on the remote side
820 --insecure
822 do not verify server certificate (ignoring web.cacerts config)
823 [+] marked option can be specified multiple times
825 cat
827 output the current or given revision of files:
828 hg cat [OPTION]... FILE...
830 Print the specified files as they were at the given revision. If no
832 revision is given, the parent of the working directory is used.
833 Output may be to a file, in which case the name of the file is given
835 using a template string. See hg help templates. In addition to the com‐
836 mon template keywords, the following formatting rules are supported:
837 %%
839 literal "%" character
841 %s
843 basename of file being printed
845 %d
847 dirname of file being printed, or '.' if in repository root
849 %p
851 root-relative path name of file being printed
853 %H
855 changeset hash (40 hexadecimal digits)
857 %R
859 changeset revision number
861 %h
863 short-form changeset hash (12 hexadecimal digits)
865 %r
867 zero-padded changeset revision number
869 %b
871 basename of the exporting repository
873 \
875 literal "" character
877 Template:
879 The following keywords are supported in addition to the common template
881 keywords and functions. See also hg help templates.
882 data String. File content.
884 path String. Repository-absolute path of the file.
886 Returns 0 on success.
888 Options:
890 -o,--output <FORMAT>
892 print output to file with formatted name
893 -r,--rev <REV>
895 print the given revision
896 --decode
898 apply any matching decode filter
899 -I,--include <PATTERN[+]>
901 include names matching the given patterns
902 -X,--exclude <PATTERN[+]>
904 exclude names matching the given patterns
905 -T,--template <TEMPLATE>
907 display with template
908 [+] marked option can be specified multiple times
910 clone
912 make a copy of an existing repository:
913 hg clone [OPTION]... SOURCE [DEST]
915 Create a copy of an existing repository in a new directory.
917 If no destination directory name is specified, it defaults to the base‐
919 name of the source.
920 The location of the source is added to the new repository's .hg/hgrc
922 file, as the default to be used for future pulls.
923 Only local paths and ssh:// URLs are supported as destinations. For
925 ssh:// destinations, no working directory or .hg/hgrc will be created
926 on the remote side.
927 If the source repository has a bookmark called '@' set, that revision
929 will be checked out in the new repository by default.
930 To check out a particular version, use -u/--update, or -U/--noupdate to
932 create a clone with no working directory.
933 To pull only a subset of changesets, specify one or more revisions
935 identifiers with -r/--rev or branches with -b/--branch. The resulting
936 clone will contain only the specified changesets and their ancestors.
937 These options (or 'clone src#rev dest') imply --pull, even for local
938 source repositories.
939 In normal clone mode, the remote normalizes repository data into a com‐
941 mon exchange format and the receiving end translates this data into its
942 local storage format. --stream activates a different clone mode that
943 essentially copies repository files from the remote with minimal data
944 processing. This significantly reduces the CPU cost of a clone both
945 remotely and locally. However, it often increases the transferred data
946 size by 30-40%. This can result in substantially faster clones where
947 I/O throughput is plentiful, especially for larger repositories. A
948 side-effect of --stream clones is that storage settings and require‐
949 ments on the remote are applied locally: a modern client may inherit
950 legacy or inefficient storage used by the remote or a legacy Mercurial
951 client may not be able to clone from a modern Mercurial remote.
952 Note Specifying a tag will include the tagged changeset but not the
954 changeset containing the tag.
955 For efficiency, hardlinks are used for cloning whenever the source and
957 destination are on the same filesystem (note this applies only to the
958 repository data, not to the working directory). Some filesystems, such
959 as AFS, implement hardlinking incorrectly, but do not report errors. In
960 these cases, use the --pull option to avoid hardlinking.
961 Mercurial will update the working directory to the first applicable
963 revision from this list:
964 a. null if -U or the source repository has no changesets
966 b. if -u . and the source repository is local, the first parent of the
968 source repository's working directory
969 c. the changeset specified with -u (if a branch name, this means the
971 latest head of that branch)
972 d. the changeset specified with -r
974 e. the tipmost head specified with -b
976 f. the tipmost head specified with the url#branch source syntax
978 g. the revision marked with the '@' bookmark, if present
980 h. the tipmost head of the default branch
982 i. tip
984 When cloning from servers that support it, Mercurial may fetch pre-gen‐
986 erated data from a server-advertised URL or inline from the same
987 stream. When this is done, hooks operating on incoming changesets and
988 changegroups may fire more than once, once for each pre-generated bun‐
989 dle and as well as for any additional remaining data. In addition, if
990 an error occurs, the repository may be rolled back to a partial clone.
991 This behavior may change in future releases. See hg help -e cloneb‐
992 undles for more.
993 Examples:
995 · clone a remote repository to a new directory named hg/:
997 hg clone https://www.mercurial-scm.org/repo/hg/
999 · create a lightweight local clone:
1001 hg clone project/ project-feature/
1003 · clone from an absolute path on an ssh server (note double-slash):
1005 hg clone ssh://user@server//home/projects/alpha/
1007 · do a streaming clone while checking out a specified version:
1009 hg clone --stream http://server/repo -u 1.5
1011 · create a repository without changesets after a particular revision:
1013 hg clone -r 04e544 experimental/ good/
1015 · clone (and track) a particular named branch:
1017 hg clone https://www.mercurial-scm.org/repo/hg/#stable
1019 See hg help urls for details on specifying URLs.
1021 Returns 0 on success.
1023 Options:
1025 -U, --noupdate
1027 the clone will include an empty working directory (only a repos‐
1028 itory)
1029 -u,--updaterev <REV>
1031 revision, tag, or branch to check out
1032 -r,--rev <REV[+]>
1034 do not clone everything, but include this changeset and its
1035 ancestors
1036 -b,--branch <BRANCH[+]>
1038 do not clone everything, but include this branch's changesets
1039 and their ancestors
1040 --pull use pull protocol to copy metadata
1042 --uncompressed
1044 an alias to --stream (DEPRECATED)
1045 --stream
1047 clone with minimal data processing
1048 -e,--ssh <CMD>
1050 specify ssh command to use
1051 --remotecmd <CMD>
1053 specify hg command to run on the remote side
1054 --insecure
1056 do not verify server certificate (ignoring web.cacerts config)
1057 [+] marked option can be specified multiple times
1059 commit
1061 commit the specified files or all outstanding changes:
1062 hg commit [OPTION]... [FILE]...
1064 Commit changes to the given files into the repository. Unlike a cen‐
1066 tralized SCM, this operation is a local operation. See hg push for a
1067 way to actively distribute your changes.
1068 If a list of files is omitted, all changes reported by hg status will
1070 be committed.
1071 If you are committing the result of a merge, do not provide any file‐
1073 names or -I/-X filters.
1074 If no commit message is specified, Mercurial starts your configured
1076 editor where you can enter a message. In case your commit fails, you
1077 will find a backup of your message in .hg/last-message.txt.
1078 The --close-branch flag can be used to mark the current branch head
1080 closed. When all heads of a branch are closed, the branch will be con‐
1081 sidered closed and no longer listed.
1082 The --amend flag can be used to amend the parent of the working direc‐
1084 tory with a new commit that contains the changes in the parent in addi‐
1085 tion to those currently reported by hg status, if there are any. The
1086 old commit is stored in a backup bundle in .hg/strip-backup (see hg
1087 help bundle and hg help unbundle on how to restore it).
1088 Message, user and date are taken from the amended commit unless speci‐
1090 fied. When a message isn't specified on the command line, the editor
1091 will open with the message of the amended commit.
1092 It is not possible to amend public changesets (see hg help phases) or
1094 changesets that have children.
1095 See hg help dates for a list of formats valid for -d/--date.
1097 Returns 0 on success, 1 if nothing changed.
1099 Examples:
1101 · commit all files ending in .py:
1103 hg commit --include "set:**.py"
1105 · commit all non-binary files:
1107 hg commit --exclude "set:binary()"
1109 · amend the current commit and set the date to now:
1111 hg commit --amend --date now
1113 Options:
1115 -A, --addremove
1117 mark new/missing files as added/removed before committing
1118 --close-branch
1120 mark a branch head as closed
1121 --amend
1123 amend the parent of the working directory
1124 -s, --secret
1126 use the secret phase for committing
1127 -e, --edit
1129 invoke editor on commit messages
1130 -i, --interactive
1132 use interactive mode
1133 -I,--include <PATTERN[+]>
1135 include names matching the given patterns
1136 -X,--exclude <PATTERN[+]>
1138 exclude names matching the given patterns
1139 -m,--message <TEXT>
1141 use text as commit message
1142 -l,--logfile <FILE>
1144 read commit message from file
1145 -d,--date <DATE>
1147 record the specified date as commit date
1148 -u,--user <USER>
1150 record the specified user as committer
1151 -S, --subrepos
1153 recurse into subrepositories
1154 [+] marked option can be specified multiple times
1156 aliases: ci
1158 config
1160 show combined config settings from all hgrc files:
1161 hg config [-u] [NAME]...
1163 With no arguments, print names and values of all config items.
1165 With one argument of the form section.name, print just the value of
1167 that config item.
1168 With multiple arguments, print names and values of all config items
1170 with matching section names or section.names.
1171 With --edit, start an editor on the user-level config file. With
1173 --global, edit the system-wide config file. With --local, edit the
1174 repository-level config file.
1175 With --debug, the source (filename and line number) is printed for each
1177 config item.
1178 See hg help config for more information about config files.
1180 Template:
1182 The following keywords are supported. See also hg help templates.
1184 name String. Config name.
1186 source String. Filename and line number where the item is defined.
1188 value String. Config value.
1190 Returns 0 on success, 1 if NAME does not exist.
1192 Options:
1194 -u, --untrusted
1196 show untrusted configuration options
1197 -e, --edit
1199 edit user config
1200 -l, --local
1202 edit repository config
1203 -g, --global
1205 edit global config
1206 -T,--template <TEMPLATE>
1208 display with template
1209 aliases: showconfig debugconfig
1211 copy
1213 mark files as copied for the next commit:
1214 hg copy [OPTION]... [SOURCE]... DEST
1216 Mark dest as having copies of source files. If dest is a directory,
1218 copies are put in that directory. If dest is a file, the source must be
1219 a single file.
1220 By default, this command copies the contents of files as they exist in
1222 the working directory. If invoked with -A/--after, the operation is
1223 recorded, but no copying is performed.
1224 This command takes effect with the next commit. To undo a copy before
1226 that, see hg revert.
1227 Returns 0 on success, 1 if errors are encountered.
1229 Options:
1231 -A, --after
1233 record a copy that has already occurred
1234 -f, --force
1236 forcibly copy over an existing managed file
1237 -I,--include <PATTERN[+]>
1239 include names matching the given patterns
1240 -X,--exclude <PATTERN[+]>
1242 exclude names matching the given patterns
1243 -n, --dry-run
1245 do not perform actions, just print output
1246 [+] marked option can be specified multiple times
1248 aliases: cp
1250 diff
1252 diff repository (or selected files):
1253 hg diff [OPTION]... ([-c REV] | [-r REV1 [-r REV2]]) [FILE]...
1255 Show differences between revisions for the specified files.
1257 Differences between files are shown using the unified diff format.
1259 Note hg diff may generate unexpected results for merges, as it will
1261 default to comparing against the working directory's first par‐
1262 ent changeset if no revisions are specified.
1263 When two revision arguments are given, then changes are shown between
1265 those revisions. If only one revision is specified then that revision
1266 is compared to the working directory, and, when no revisions are speci‐
1267 fied, the working directory files are compared to its first parent.
1268 Alternatively you can specify -c/--change with a revision to see the
1270 changes in that changeset relative to its first parent.
1271 Without the -a/--text option, diff will avoid generating diffs of files
1273 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1274 bly with undesirable results.
1275 Use the -g/--git option to generate diffs in the git extended diff for‐
1277 mat. For more information, read hg help diffs.
1278 Examples:
1280 · compare a file in the current working directory to its parent:
1282 hg diff foo.c
1284 · compare two historical versions of a directory, with rename info:
1286 hg diff --git -r 1.0:1.2 lib/
1288 · get change stats relative to the last change on some date:
1290 hg diff --stat -r "date('may 2')"
1292 · diff all newly-added files that contain a keyword:
1294 hg diff "set:added() and grep(GNU)"
1296 · compare a revision and its parents:
1298 hg diff -c 9353 # compare against first parent
1300 hg diff -r 9353^:9353 # same using revset syntax
1301 hg diff -r 9353^2:9353 # compare against the second parent
1302 Returns 0 on success.
1304 Options:
1306 -r,--rev <REV[+]>
1308 revision
1309 -c,--change <REV>
1311 change made by revision
1312 -a, --text
1314 treat all files as text
1315 -g, --git
1317 use git extended diff format
1318 --binary
1320 generate binary diffs in git mode (default)
1321 --nodates
1323 omit dates from diff headers
1324 --noprefix
1326 omit a/ and b/ prefixes from filenames
1327 -p, --show-function
1329 show which function each change is in
1330 --reverse
1332 produce a diff that undoes the changes
1333 -w, --ignore-all-space
1335 ignore white space when comparing lines
1336 -b, --ignore-space-change
1338 ignore changes in the amount of white space
1339 -B, --ignore-blank-lines
1341 ignore changes whose lines are all blank
1342 -Z, --ignore-space-at-eol
1344 ignore changes in whitespace at EOL
1345 -U,--unified <NUM>
1347 number of lines of context to show
1348 --stat output diffstat-style summary of changes
1350 --root <DIR>
1352 produce diffs relative to subdirectory
1353 -I,--include <PATTERN[+]>
1355 include names matching the given patterns
1356 -X,--exclude <PATTERN[+]>
1358 exclude names matching the given patterns
1359 -S, --subrepos
1361 recurse into subrepositories
1362 [+] marked option can be specified multiple times
1364 export
1366 dump the header and diffs for one or more changesets:
1367 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
1369 Print the changeset header and diffs for one or more revisions. If no
1371 revision is given, the parent of the working directory is used.
1372 The information shown in the changeset header is: author, date, branch
1374 name (if non-default), changeset hash, parent(s) and commit comment.
1375 Note hg export may generate unexpected diff output for merge change‐
1377 sets, as it will compare the merge changeset against its first
1378 parent only.
1379 Output may be to a file, in which case the name of the file is given
1381 using a template string. See hg help templates. In addition to the com‐
1382 mon template keywords, the following formatting rules are supported:
1383 %%
1385 literal "%" character
1387 %H
1389 changeset hash (40 hexadecimal digits)
1391 %N
1393 number of patches being generated
1395 %R
1397 changeset revision number
1399 %b
1401 basename of the exporting repository
1403 %h
1405 short-form changeset hash (12 hexadecimal digits)
1407 %m
1409 first line of the commit message (only alphanumeric characters)
1411 %n
1413 zero-padded sequence number, starting at 1
1415 %r
1417 zero-padded changeset revision number
1419 \
1421 literal "" character
1423 Without the -a/--text option, export will avoid generating diffs of
1425 files it detects as binary. With -a, export will generate a diff any‐
1426 way, probably with undesirable results.
1427 With -B/--bookmark changesets reachable by the given bookmark are
1429 selected.
1430 Use the -g/--git option to generate diffs in the git extended diff for‐
1432 mat. See hg help diffs for more information.
1433 With the --switch-parent option, the diff will be against the second
1435 parent. It can be useful to review a merge.
1436 Template:
1438 The following keywords are supported in addition to the common template
1440 keywords and functions. See also hg help templates.
1441 diff String. Diff content.
1443 parents
1445 List of strings. Parent nodes of the changeset.
1446 Examples:
1448 · use export and import to transplant a bugfix to the current branch:
1450 hg export -r 9353 | hg import -
1452 · export all the changesets between two revisions to a file with rename
1454 information:
1455 hg export --git -r 123:150 > changes.txt
1457 · split outgoing changes into a series of patches with descriptive
1459 names:
1460 hg export -r "outgoing()" -o "%n-%m.patch"
1462 Returns 0 on success.
1464 Options:
1466 -B,--bookmark <BOOKMARK>
1468 export changes only reachable by given bookmark
1469 -o,--output <FORMAT>
1471 print output to file with formatted name
1472 --switch-parent
1474 diff against the second parent
1475 -r,--rev <REV[+]>
1477 revisions to export
1478 -a, --text
1480 treat all files as text
1481 -g, --git
1483 use git extended diff format
1484 --binary
1486 generate binary diffs in git mode (default)
1487 --nodates
1489 omit dates from diff headers
1490 -T,--template <TEMPLATE>
1492 display with template
1493 [+] marked option can be specified multiple times
1495 files
1497 list tracked files:
1498 hg files [OPTION]... [FILE]...
1500 Print files under Mercurial control in the working directory or speci‐
1502 fied revision for given files (excluding removed files). Files can be
1503 specified as filenames or filesets.
1504 If no files are given to match, this command prints the names of all
1506 files under Mercurial control.
1507 Template:
1509 The following keywords are supported in addition to the common template
1511 keywords and functions. See also hg help templates.
1512 flags String. Character denoting file's symlink and executable bits.
1514 path String. Repository-absolute path of the file.
1516 size Integer. Size of the file in bytes.
1518 Examples:
1520 · list all files under the current directory:
1522 hg files .
1524 · shows sizes and flags for current revision:
1526 hg files -vr .
1528 · list all files named README:
1530 hg files -I "**/README"
1532 · list all binary files:
1534 hg files "set:binary()"
1536 · find files containing a regular expression:
1538 hg files "set:grep('bob')"
1540 · search tracked file contents with xargs and grep:
1542 hg files -0 | xargs -0 grep foo
1544 See hg help patterns and hg help filesets for more information on spec‐
1546 ifying file patterns.
1547 Returns 0 if a match is found, 1 otherwise.
1549 Options:
1551 -r,--rev <REV>
1553 search the repository as it is in REV
1554 -0, --print0
1556 end filenames with NUL, for use with xargs
1557 -I,--include <PATTERN[+]>
1559 include names matching the given patterns
1560 -X,--exclude <PATTERN[+]>
1562 exclude names matching the given patterns
1563 -T,--template <TEMPLATE>
1565 display with template
1566 -S, --subrepos
1568 recurse into subrepositories
1569 [+] marked option can be specified multiple times
1571 forget
1573 forget the specified files on the next commit:
1574 hg forget [OPTION]... FILE...
1576 Mark the specified files so they will no longer be tracked after the
1578 next commit.
1579 This only removes files from the current branch, not from the entire
1581 project history, and it does not delete them from the working direc‐
1582 tory.
1583 To delete the file from the working directory, see hg remove.
1585 To undo a forget before the next commit, see hg add.
1587 Examples:
1589 · forget newly-added binary files:
1591 hg forget "set:added() and binary()"
1593 · forget files that would be excluded by .hgignore:
1595 hg forget "set:hgignore()"
1597 Returns 0 on success.
1599 Options:
1601 -i, --interactive
1603 use interactive mode
1604 -I,--include <PATTERN[+]>
1606 include names matching the given patterns
1607 -X,--exclude <PATTERN[+]>
1609 exclude names matching the given patterns
1610 -n, --dry-run
1612 do not perform actions, just print output
1613 [+] marked option can be specified multiple times
1615 graft
1617 copy changes from other branches onto the current branch:
1618 hg graft [OPTION]... [-r REV]... REV...
1620 This command uses Mercurial's merge logic to copy individual changes
1622 from other branches without merging branches in the history graph. This
1623 is sometimes known as 'backporting' or 'cherry-picking'. By default,
1624 graft will copy user, date, and description from the source changesets.
1625 Changesets that are ancestors of the current revision, that have
1627 already been grafted, or that are merges will be skipped.
1628 If --log is specified, log messages will have a comment appended of the
1630 form:
1631 (grafted from CHANGESETHASH)
1633 If --force is specified, revisions will be grafted even if they are
1635 already ancestors of, or have been grafted to, the destination. This
1636 is useful when the revisions have since been backed out.
1637 If a graft merge results in conflicts, the graft process is interrupted
1639 so that the current merge can be manually resolved. Once all conflicts
1640 are addressed, the graft process can be continued with the -c/--con‐
1641 tinue option.
1642 The -c/--continue option reapplies all the earlier options.
1644 The --base option exposes more of how graft internally uses merge with
1646 a custom base revision. --base can be used to specify another ancestor
1647 than the first and only parent.
1648 The command:
1650 hg graft -r 345 --base 234
1652 is thus pretty much the same as:
1654 hg diff -r 234 -r 345 | hg import
1656 but using merge to resolve conflicts and track moved files.
1658 The result of a merge can thus be backported as a single commit by
1660 specifying one of the merge parents as base, and thus effectively
1661 grafting the changes from the other side.
1662 It is also possible to collapse multiple changesets and clean up his‐
1664 tory by specifying another ancestor as base, much like rebase --col‐
1665 lapse --keep.
1666 The commit message can be tweaked after the fact using commit --amend .
1668 For using non-ancestors as the base to backout changes, see the backout
1670 command and the hidden --parent option.
1671 Examples:
1673 · copy a single change to the stable branch and edit its description:
1675 hg update stable
1677 hg graft --edit 9393
1678 · graft a range of changesets with one exception, updating dates:
1680 hg graft -D "2085::2093 and not 2091"
1682 · continue a graft after resolving conflicts:
1684 hg graft -c
1686 · show the source of a grafted changeset:
1688 hg log --debug -r .
1690 · show revisions sorted by date:
1692 hg log -r "sort(all(), date)"
1694 · backport the result of a merge as a single commit:
1696 hg graft -r 123 --base 123^
1698 · land a feature branch as one changeset:
1700 hg up -cr default
1702 hg graft -r featureX --base "ancestor('featureX', 'default')"
1703 See hg help revisions for more about specifying revisions.
1705 Returns 0 on successful completion.
1707 Options:
1709 -r,--rev <REV[+]>
1711 revisions to graft
1712 --base <REV>
1714 base revision when doing the graft merge (ADVANCED)
1715 -c, --continue
1717 resume interrupted graft
1718 --stop stop interrupted graft
1720 --abort
1722 abort interrupted graft
1723 -e, --edit
1725 invoke editor on commit messages
1726 --log append graft info to log message
1728 --no-commit
1730 don't commit, just apply the changes in working directory
1731 -f, --force
1733 force graft
1734 -D, --currentdate
1736 record the current date as commit date
1737 -U, --currentuser
1739 record the current user as committer
1740 -d,--date <DATE>
1742 record the specified date as commit date
1743 -u,--user <USER>
1745 record the specified user as committer
1746 -t,--tool <TOOL>
1748 specify merge tool
1749 -n, --dry-run
1751 do not perform actions, just print output
1752 [+] marked option can be specified multiple times
1754 grep
1756 search revision history for a pattern in specified files:
1757 hg grep [OPTION]... PATTERN [FILE]...
1759 Search revision history for a regular expression in the specified files
1761 or the entire project.
1762 By default, grep prints the most recent revision number for each file
1764 in which it finds a match. To get it to print every revision that con‐
1765 tains a change in match status ("-" for a match that becomes a
1766 non-match, or "+" for a non-match that becomes a match), use the --diff
1767 flag.
1768 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1770 If no FILEs are specified (and -f/--follow isn't set), all files in the
1772 repository are searched, including those that don't exist in the cur‐
1773 rent branch or have been deleted in a prior changeset.
1774 Template:
1776 The following keywords are supported in addition to the common template
1778 keywords and functions. See also hg help templates.
1779 change String. Character denoting insertion + or removal -. Available
1781 if --diff is specified.
1782 lineno Integer. Line number of the match.
1784 path String. Repository-absolute path of the file.
1786 texts List of text chunks.
1788 And each entry of {texts} provides the following sub-keywords.
1790 matched
1792 Boolean. True if the chunk matches the specified pattern.
1793 text String. Chunk content.
1795 See hg help templates.operators for the list expansion syntax.
1797 Returns 0 if a match is found, 1 otherwise.
1799 Options:
1801 -0, --print0
1803 end fields with NUL
1804 --all print all revisions that match (DEPRECATED)
1806 --diff print all revisions when the term was introduced or removed
1808 -a, --text
1810 treat all files as text
1811 -f, --follow
1813 follow changeset history, or file history across copies and
1814 renames
1815 -i, --ignore-case
1817 ignore case when matching
1818 -l, --files-with-matches
1820 print only filenames and revisions that match
1821 -n, --line-number
1823 print matching line numbers
1824 -r,--rev <REV[+]>
1826 only search files changed within revision range
1827 --all-files
1829 include all files in the changeset while grepping (EXPERIMENTAL)
1830 -u, --user
1832 list the author (long with -v)
1833 -d, --date
1835 list the date (short with -q)
1836 -T,--template <TEMPLATE>
1838 display with template
1839 -I,--include <PATTERN[+]>
1841 include names matching the given patterns
1842 -X,--exclude <PATTERN[+]>
1844 exclude names matching the given patterns
1845 [+] marked option can be specified multiple times
1847 heads
1849 show branch heads:
1850 hg heads [-ct] [-r STARTREV] [REV]...
1852 With no arguments, show all open branch heads in the repository.
1854 Branch heads are changesets that have no descendants on the same
1855 branch. They are where development generally takes place and are the
1856 usual targets for update and merge operations.
1857 If one or more REVs are given, only open branch heads on the branches
1859 associated with the specified changesets are shown. This means that you
1860 can use hg heads . to see the heads on the currently checked-out
1861 branch.
1862 If -c/--closed is specified, also show branch heads marked closed (see
1864 hg commit --close-branch).
1865 If STARTREV is specified, only those heads that are descendants of
1867 STARTREV will be displayed.
1868 If -t/--topo is specified, named branch mechanics will be ignored and
1870 only topological heads (changesets with no children) will be shown.
1871 Returns 0 if matching heads are found, 1 if not.
1873 Options:
1875 -r,--rev <STARTREV>
1877 show only heads which are descendants of STARTREV
1878 -t, --topo
1880 show topological heads only
1881 -a, --active
1883 show active branchheads only (DEPRECATED)
1884 -c, --closed
1886 show normal and closed branch heads
1887 --style <STYLE>
1889 display using template map file (DEPRECATED)
1890 -T,--template <TEMPLATE>
1892 display with template
1893 help
1895 show help for a given topic or a help overview:
1896 hg help [-eck] [-s PLATFORM] [TOPIC]
1898 With no arguments, print a list of commands with short help messages.
1900 Given a topic, extension, or command name, print help for that topic.
1902 Returns 0 if successful.
1904 Options:
1906 -e, --extension
1908 show only help for extensions
1909 -c, --command
1911 show only help for commands
1912 -k, --keyword
1914 show topics matching keyword
1915 -s,--system <PLATFORM[+]>
1917 show help for specific platform(s)
1918 [+] marked option can be specified multiple times
1920 identify
1922 identify the working directory or specified revision:
1923 hg identify [-nibtB] [-r REV] [SOURCE]
1925 Print a summary identifying the repository state at REV using one or
1927 two parent hash identifiers, followed by a "+" if the working directory
1928 has uncommitted changes, the branch name (if not default), a list of
1929 tags, and a list of bookmarks.
1930 When REV is not given, print a summary of the current state of the
1932 repository including the working directory. Specify -r. to get informa‐
1933 tion of the working directory parent without scanning uncommitted
1934 changes.
1935 Specifying a path to a repository root or Mercurial bundle will cause
1937 lookup to operate on that repository/bundle.
1938 Template:
1940 The following keywords are supported in addition to the common template
1942 keywords and functions. See also hg help templates.
1943 dirty String. Character + denoting if the working directory has uncom‐
1945 mitted changes.
1946 id String. One or two nodes, optionally followed by +.
1948 parents
1950 List of strings. Parent nodes of the changeset.
1951 Examples:
1953 · generate a build identifier for the working directory:
1955 hg id --id > build-id.dat
1957 · find the revision corresponding to a tag:
1959 hg id -n -r 1.3
1961 · check the most recent revision of a remote repository:
1963 hg id -r tip https://www.mercurial-scm.org/repo/hg/
1965 See hg log for generating more information about specific revisions,
1967 including full hash identifiers.
1968 Returns 0 if successful.
1970 Options:
1972 -r,--rev <REV>
1974 identify the specified revision
1975 -n, --num
1977 show local revision number
1978 -i, --id
1980 show global revision id
1981 -b, --branch
1983 show branch
1984 -t, --tags
1986 show tags
1987 -B, --bookmarks
1989 show bookmarks
1990 -e,--ssh <CMD>
1992 specify ssh command to use
1993 --remotecmd <CMD>
1995 specify hg command to run on the remote side
1996 --insecure
1998 do not verify server certificate (ignoring web.cacerts config)
1999 -T,--template <TEMPLATE>
2001 display with template
2002 aliases: id
2004 import
2006 import an ordered set of patches:
2007 hg import [OPTION]... PATCH...
2009 Import a list of patches and commit them individually (unless --no-com‐
2011 mit is specified).
2012 To read a patch from standard input (stdin), use "-" as the patch name.
2014 If a URL is specified, the patch will be downloaded from there.
2015 Import first applies changes to the working directory (unless --bypass
2017 is specified), import will abort if there are outstanding changes.
2018 Use --bypass to apply and commit patches directly to the repository,
2020 without affecting the working directory. Without --exact, patches will
2021 be applied on top of the working directory parent revision.
2022 You can import a patch straight from a mail message. Even patches as
2024 attachments work (to use the body part, it must have type text/plain or
2025 text/x-patch). From and Subject headers of email message are used as
2026 default committer and commit message. All text/plain body parts before
2027 first diff are added to the commit message.
2028 If the imported patch was generated by hg export, user and description
2030 from patch override values from message headers and body. Values given
2031 on command line with -m/--message and -u/--user override these.
2032 If --exact is specified, import will set the working directory to the
2034 parent of each patch before applying it, and will abort if the result‐
2035 ing changeset has a different ID than the one recorded in the patch.
2036 This will guard against various ways that portable patch formats and
2037 mail systems might fail to transfer Mercurial data or metadata. See hg
2038 bundle for lossless transmission.
2039 Use --partial to ensure a changeset will be created from the patch even
2041 if some hunks fail to apply. Hunks that fail to apply will be written
2042 to a <target-file>.rej file. Conflicts can then be resolved by hand
2043 before hg commit --amend is run to update the created changeset. This
2044 flag exists to let people import patches that partially apply without
2045 losing the associated metadata (author, date, description, ...).
2046 Note When no hunks apply cleanly, hg import --partial will create an
2048 empty changeset, importing only the patch metadata.
2049 With -s/--similarity, hg will attempt to discover renames and copies in
2051 the patch in the same way as hg addremove.
2052 It is possible to use external patch programs to perform the patch by
2054 setting the ui.patch configuration option. For the default internal
2055 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
2056 fig for more information about configuration files and how to use these
2057 options.
2058 See hg help dates for a list of formats valid for -d/--date.
2060 Examples:
2062 · import a traditional patch from a website and detect renames:
2064 hg import -s 80 http://example.com/bugfix.patch
2066 · import a changeset from an hgweb server:
2068 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
2070 · import all the patches in an Unix-style mbox:
2072 hg import incoming-patches.mbox
2074 · import patches from stdin:
2076 hg import -
2078 · attempt to exactly restore an exported changeset (not always possi‐
2080 ble):
2081 hg import --exact proposed-fix.patch
2083 · use an external tool to apply a patch which is too fuzzy for the
2085 default internal tool.
2086 hg import --config ui.patch="patch --merge" fuzzy.patch
2088 · change the default fuzzing from 2 to a less strict 7
2090 hg import --config ui.fuzz=7 fuzz.patch
2092 Returns 0 on success, 1 on partial success (see --partial).
2094 Options:
2096 -p,--strip <NUM>
2098 directory strip option for patch. This has the same meaning as
2099 the corresponding patch option (default: 1)
2100 -b,--base <PATH>
2102 base path (DEPRECATED)
2103 -e, --edit
2105 invoke editor on commit messages
2106 -f, --force
2108 skip check for outstanding uncommitted changes (DEPRECATED)
2109 --no-commit
2111 don't commit, just update the working directory
2112 --bypass
2114 apply patch without touching the working directory
2115 --partial
2117 commit even if some hunks fail
2118 --exact
2120 abort if patch would apply lossily
2121 --prefix <DIR>
2123 apply patch to subdirectory
2124 --import-branch
2126 use any branch information in patch (implied by --exact)
2127 -m,--message <TEXT>
2129 use text as commit message
2130 -l,--logfile <FILE>
2132 read commit message from file
2133 -d,--date <DATE>
2135 record the specified date as commit date
2136 -u,--user <USER>
2138 record the specified user as committer
2139 -s,--similarity <SIMILARITY>
2141 guess renamed files by similarity (0<=s<=100)
2142 aliases: patch
2144 incoming
2146 show new changesets found in source:
2147 hg incoming [-p] [-n] [-M] [-f] [-r REV]... [--bundle FILENAME] [SOURCE]
2149 Show new changesets found in the specified path/URL or the default pull
2151 location. These are the changesets that would have been pulled by hg
2152 pull at the time you issued this command.
2153 See pull for valid source format details.
2155 With -B/--bookmarks, the result of bookmark comparison between local
2157 and remote repositories is displayed. With -v/--verbose, status is also
2158 displayed for each bookmark like below:
2159 BM1 01234567890a added
2161 BM2 1234567890ab advanced
2162 BM3 234567890abc diverged
2163 BM4 34567890abcd changed
2164 The action taken locally when pulling depends on the status of each
2166 bookmark:
2167 added
2169 pull will create it
2171 advanced
2173 pull will update it
2175 diverged
2177 pull will create a divergent bookmark
2179 changed
2181 result depends on remote changesets
2183 From the point of view of pulling behavior, bookmark existing only in
2185 the remote repository are treated as added, even if it is in fact
2186 locally deleted.
2187 For remote repository, using --bundle avoids downloading the changesets
2189 twice if the incoming is followed by a pull.
2190 Examples:
2192 · show incoming changes with patches and full description:
2194 hg incoming -vp
2196 · show incoming changes excluding merges, store a bundle:
2198 hg in -vpM --bundle incoming.hg
2200 hg pull incoming.hg
2201 · briefly list changes inside a bundle:
2203 hg in changes.hg -T "{desc|firstline}\n"
2205 Returns 0 if there are incoming changes, 1 otherwise.
2207 Options:
2209 -f, --force
2211 run even if remote repository is unrelated
2212 -n, --newest-first
2214 show newest record first
2215 --bundle <FILE>
2217 file to store the bundles into
2218 -r,--rev <REV[+]>
2220 a remote changeset intended to be added
2221 -B, --bookmarks
2223 compare bookmarks
2224 -b,--branch <BRANCH[+]>
2226 a specific branch you would like to pull
2227 -p, --patch
2229 show patch
2230 -g, --git
2232 use git extended diff format
2233 -l,--limit <NUM>
2235 limit number of changes displayed
2236 -M, --no-merges
2238 do not show merges
2239 --stat output diffstat-style summary of changes
2241 -G, --graph
2243 show the revision DAG
2244 --style <STYLE>
2246 display using template map file (DEPRECATED)
2247 -T,--template <TEMPLATE>
2249 display with template
2250 -e,--ssh <CMD>
2252 specify ssh command to use
2253 --remotecmd <CMD>
2255 specify hg command to run on the remote side
2256 --insecure
2258 do not verify server certificate (ignoring web.cacerts config)
2259 -S, --subrepos
2261 recurse into subrepositories
2262 [+] marked option can be specified multiple times
2264 aliases: in
2266 init
2268 create a new repository in the given directory:
2269 hg init [-e CMD] [--remotecmd CMD] [DEST]
2271 Initialize a new repository in the given directory. If the given direc‐
2273 tory does not exist, it will be created.
2274 If no directory is given, the current directory is used.
2276 It is possible to specify an ssh:// URL as the destination. See hg
2278 help urls for more information.
2279 Returns 0 on success.
2281 Options:
2283 -e,--ssh <CMD>
2285 specify ssh command to use
2286 --remotecmd <CMD>
2288 specify hg command to run on the remote side
2289 --insecure
2291 do not verify server certificate (ignoring web.cacerts config)
2292 locate
2294 locate files matching specific patterns (DEPRECATED):
2295 hg locate [OPTION]... [PATTERN]...
2297 Print files under Mercurial control in the working directory whose
2299 names match the given patterns.
2300 By default, this command searches all directories in the working direc‐
2302 tory. To search just the current directory and its subdirectories, use
2303 "--include .".
2304 If no patterns are given to match, this command prints the names of all
2306 files under Mercurial control in the working directory.
2307 If you want to feed the output of this command into the "xargs" com‐
2309 mand, use the -0 option to both this command and "xargs". This will
2310 avoid the problem of "xargs" treating single filenames that contain
2311 whitespace as multiple filenames.
2312 See hg help files for a more versatile command.
2314 Returns 0 if a match is found, 1 otherwise.
2316 Options:
2318 -r,--rev <REV>
2320 search the repository as it is in REV
2321 -0, --print0
2323 end filenames with NUL, for use with xargs
2324 -f, --fullpath
2326 print complete paths from the filesystem root
2327 -I,--include <PATTERN[+]>
2329 include names matching the given patterns
2330 -X,--exclude <PATTERN[+]>
2332 exclude names matching the given patterns
2333 [+] marked option can be specified multiple times
2335 log
2337 show revision history of entire repository or files:
2338 hg log [OPTION]... [FILE]
2340 Print the revision history of the specified files or the entire
2342 project.
2343 If no revision range is specified, the default is tip:0 unless --follow
2345 is set, in which case the working directory parent is used as the
2346 starting revision.
2347 File history is shown without following rename or copy history of
2349 files. Use -f/--follow with a filename to follow history across renames
2350 and copies. --follow without a filename will only show ancestors of the
2351 starting revision.
2352 By default this command prints revision number and changeset id, tags,
2354 non-trivial parents, user, date and time, and a summary for each com‐
2355 mit. When the -v/--verbose switch is used, the list of changed files
2356 and full commit message are shown.
2357 With --graph the revisions are shown as an ASCII art DAG with the most
2359 recent changeset at the top. 'o' is a changeset, '@' is a working
2360 directory parent, '_' closes a branch, 'x' is obsolete, '*' is unsta‐
2361 ble, and '+' represents a fork where the changeset from the lines below
2362 is a parent of the 'o' merge on the same line. Paths in the DAG are
2363 represented with '|', '/' and so forth. ':' in place of a '|' indicates
2364 one or more revisions in a path are omitted.
2365 Use -L/--line-range FILE,M:N options to follow the history of lines
2367 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2368 fied line range will be shown. This option requires --follow; it can be
2369 specified multiple times. Currently, this option is not compatible with
2370 --graph. This option is experimental.
2371 Note hg log --patch may generate unexpected diff output for merge
2373 changesets, as it will only compare the merge changeset against
2374 its first parent. Also, only files different from BOTH parents
2375 will appear in files:.
2376 Note For performance reasons, hg log FILE may omit duplicate changes
2378 made on branches and will not show removals or mode changes. To
2379 see all such changes, use the --removed switch.
2380 Note The history resulting from -L/--line-range options depends on
2382 diff options; for instance if white-spaces are ignored, respec‐
2383 tive changes with only white-spaces in specified line range will
2384 not be listed.
2385 Some examples:
2387 · changesets with full descriptions and file lists:
2389 hg log -v
2391 · changesets ancestral to the working directory:
2393 hg log -f
2395 · last 10 commits on the current branch:
2397 hg log -l 10 -b .
2399 · changesets showing all modifications of a file, including removals:
2401 hg log --removed file.c
2403 · all changesets that touch a directory, with diffs, excluding merges:
2405 hg log -Mp lib/
2407 · all revision numbers that match a keyword:
2409 hg log -k bug --template "{rev}\n"
2411 · the full hash identifier of the working directory parent:
2413 hg log -r . --template "{node}\n"
2415 · list available log templates:
2417 hg log -T list
2419 · check if a given changeset is included in a tagged release:
2421 hg log -r "a21ccf and ancestor(1.9)"
2423 · find all changesets by some user in a date range:
2425 hg log -k alice -d "may 2008 to jul 2008"
2427 · summary of all changesets after the last tag:
2429 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2431 · changesets touching lines 13 to 23 for file.c:
2433 hg log -L file.c,13:23
2435 · changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2437 main.c with patch:
2438 hg log -L file.c,13:23 -L main.c,2:6 -p
2440 See hg help dates for a list of formats valid for -d/--date.
2442 See hg help revisions for more about specifying and ordering revisions.
2444 See hg help templates for more about pre-packaged styles and specifying
2446 custom templates. The default template used by the log command can be
2447 customized via the ui.logtemplate configuration setting.
2448 Returns 0 on success.
2450 Options:
2452 -f, --follow
2454 follow changeset history, or file history across copies and
2455 renames
2456 --follow-first
2458 only follow the first parent of merge changesets (DEPRECATED)
2459 -d,--date <DATE>
2461 show revisions matching date spec
2462 -C, --copies
2464 show copied files
2465 -k,--keyword <TEXT[+]>
2467 do case-insensitive search for a given text
2468 -r,--rev <REV[+]>
2470 show the specified revision or revset
2471 -L,--line-range <FILE,RANGE[+]>
2473 follow line range of specified file (EXPERIMENTAL)
2474 --removed
2476 include revisions where files were removed
2477 -m, --only-merges
2479 show only merges (DEPRECATED)
2480 -u,--user <USER[+]>
2482 revisions committed by user
2483 --only-branch <BRANCH[+]>
2485 show only changesets within the given named branch (DEPRECATED)
2486 -b,--branch <BRANCH[+]>
2488 show changesets within the given named branch
2489 -P,--prune <REV[+]>
2491 do not display revision or any of its ancestors
2492 -p, --patch
2494 show patch
2495 -g, --git
2497 use git extended diff format
2498 -l,--limit <NUM>
2500 limit number of changes displayed
2501 -M, --no-merges
2503 do not show merges
2504 --stat output diffstat-style summary of changes
2506 -G, --graph
2508 show the revision DAG
2509 --style <STYLE>
2511 display using template map file (DEPRECATED)
2512 -T,--template <TEMPLATE>
2514 display with template
2515 -I,--include <PATTERN[+]>
2517 include names matching the given patterns
2518 -X,--exclude <PATTERN[+]>
2520 exclude names matching the given patterns
2521 [+] marked option can be specified multiple times
2523 aliases: history
2525 manifest
2527 output the current or given revision of the project manifest:
2528 hg manifest [-r REV]
2530 Print a list of version controlled files for the given revision. If no
2532 revision is given, the first parent of the working directory is used,
2533 or the null revision if no revision is checked out.
2534 With -v, print file permissions, symlink and executable bits. With
2536 --debug, print file revision hashes.
2537 If option --all is specified, the list of all files from all revisions
2539 is printed. This includes deleted and renamed files.
2540 Returns 0 on success.
2542 Options:
2544 -r,--rev <REV>
2546 revision to display
2547 --all list files from all revisions
2549 -T,--template <TEMPLATE>
2551 display with template
2552 merge
2554 merge another revision into working directory:
2555 hg merge [-P] [[-r] REV]
2557 The current working directory is updated with all changes made in the
2559 requested revision since the last common predecessor revision.
2560 Files that changed between either parent are marked as changed for the
2562 next commit and a commit must be performed before any further updates
2563 to the repository are allowed. The next commit will have two parents.
2564 --tool can be used to specify the merge tool used for file merges. It
2566 overrides the HGMERGE environment variable and your configuration
2567 files. See hg help merge-tools for options.
2568 If no revision is specified, the working directory's parent is a head
2570 revision, and the current branch contains exactly one other head, the
2571 other head is merged with by default. Otherwise, an explicit revision
2572 with which to merge with must be provided.
2573 See hg help resolve for information on handling file conflicts.
2575 To undo an uncommitted merge, use hg merge --abort which will check out
2577 a clean copy of the original merge parent, losing all changes.
2578 Returns 0 on success, 1 if there are unresolved files.
2580 Options:
2582 -f, --force
2584 force a merge including outstanding changes (DEPRECATED)
2585 -r,--rev <REV>
2587 revision to merge
2588 -P, --preview
2590 review revisions to merge (no merge is performed)
2591 --abort
2593 abort the ongoing merge
2594 -t,--tool <TOOL>
2596 specify merge tool
2597 outgoing
2599 show changesets not found in the destination:
2600 hg outgoing [-M] [-p] [-n] [-f] [-r REV]... [DEST]
2602 Show changesets not found in the specified destination repository or
2604 the default push location. These are the changesets that would be
2605 pushed if a push was requested.
2606 See pull for details of valid destination formats.
2608 With -B/--bookmarks, the result of bookmark comparison between local
2610 and remote repositories is displayed. With -v/--verbose, status is also
2611 displayed for each bookmark like below:
2612 BM1 01234567890a added
2614 BM2 deleted
2615 BM3 234567890abc advanced
2616 BM4 34567890abcd diverged
2617 BM5 4567890abcde changed
2618 The action taken when pushing depends on the status of each bookmark:
2620 added
2622 push with -B will create it
2624 deleted
2626 push with -B will delete it
2628 advanced
2630 push will update it
2632 diverged
2634 push with -B will update it
2636 changed
2638 push with -B will update it
2640 From the point of view of pushing behavior, bookmarks existing only in
2642 the remote repository are treated as deleted, even if it is in fact
2643 added remotely.
2644 Returns 0 if there are outgoing changes, 1 otherwise.
2646 Options:
2648 -f, --force
2650 run even when the destination is unrelated
2651 -r,--rev <REV[+]>
2653 a changeset intended to be included in the destination
2654 -n, --newest-first
2656 show newest record first
2657 -B, --bookmarks
2659 compare bookmarks
2660 -b,--branch <BRANCH[+]>
2662 a specific branch you would like to push
2663 -p, --patch
2665 show patch
2666 -g, --git
2668 use git extended diff format
2669 -l,--limit <NUM>
2671 limit number of changes displayed
2672 -M, --no-merges
2674 do not show merges
2675 --stat output diffstat-style summary of changes
2677 -G, --graph
2679 show the revision DAG
2680 --style <STYLE>
2682 display using template map file (DEPRECATED)
2683 -T,--template <TEMPLATE>
2685 display with template
2686 -e,--ssh <CMD>
2688 specify ssh command to use
2689 --remotecmd <CMD>
2691 specify hg command to run on the remote side
2692 --insecure
2694 do not verify server certificate (ignoring web.cacerts config)
2695 -S, --subrepos
2697 recurse into subrepositories
2698 [+] marked option can be specified multiple times
2700 aliases: out
2702 parents
2704 show the parents of the working directory or revision (DEPRECATED):
2705 hg parents [-r REV] [FILE]
2707 Print the working directory's parent revisions. If a revision is given
2709 via -r/--rev, the parent of that revision will be printed. If a file
2710 argument is given, the revision in which the file was last changed
2711 (before the working directory revision or the argument to --rev if
2712 given) is printed.
2713 This command is equivalent to:
2715 hg log -r "p1()+p2()" or
2717 hg log -r "p1(REV)+p2(REV)" or
2718 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2719 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2720 See hg summary and hg help revsets for related information.
2722 Returns 0 on success.
2724 Options:
2726 -r,--rev <REV>
2728 show parents of the specified revision
2729 --style <STYLE>
2731 display using template map file (DEPRECATED)
2732 -T,--template <TEMPLATE>
2734 display with template
2735 paths
2737 show aliases for remote repositories:
2738 hg paths [NAME]
2740 Show definition of symbolic path name NAME. If no name is given, show
2742 definition of all available names.
2743 Option -q/--quiet suppresses all output when searching for NAME and
2745 shows only the path names when listing all definitions.
2746 Path names are defined in the [paths] section of your configuration
2748 file and in /etc/mercurial/hgrc. If run inside a repository, .hg/hgrc
2749 is used, too.
2750 The path names default and default-push have a special meaning. When
2752 performing a push or pull operation, they are used as fallbacks if no
2753 location is specified on the command-line. When default-push is set,
2754 it will be used for push and default will be used for pull; otherwise
2755 default is used as the fallback for both. When cloning a repository,
2756 the clone source is written as default in .hg/hgrc.
2757 Note default and default-push apply to all inbound (e.g. hg incoming
2759 ) and outbound (e.g. hg outgoing, hg email and hg bundle) opera‐
2760 tions.
2761 See hg help urls for more information.
2763 Template:
2765 The following keywords are supported. See also hg help templates.
2767 name String. Symbolic name of the path alias.
2769 pushurl
2771 String. URL for push operations.
2772 url String. URL or directory path for the other operations.
2774 Returns 0 on success.
2776 Options:
2778 -T,--template <TEMPLATE>
2780 display with template
2781 phase
2783 set or show the current phase name:
2784 hg phase [-p|-d|-s] [-f] [-r] [REV...]
2786 With no argument, show the phase name of the current revision(s).
2788 With one of -p/--public, -d/--draft or -s/--secret, change the phase
2790 value of the specified revisions.
2791 Unless -f/--force is specified, hg phase won't move changesets from a
2793 lower phase to a higher phase. Phases are ordered as follows:
2794 public < draft < secret
2796 Returns 0 on success, 1 if some phases could not be changed.
2798 (For more information about the phases concept, see hg help phases.)
2800 Options:
2802 -p, --public
2804 set changeset phase to public
2805 -d, --draft
2807 set changeset phase to draft
2808 -s, --secret
2810 set changeset phase to secret
2811 -f, --force
2813 allow to move boundary backward
2814 -r,--rev <REV[+]>
2816 target revision
2817 [+] marked option can be specified multiple times
2819 pull
2821 pull changes from the specified source:
2822 hg pull [-u] [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [SOURCE]
2824 Pull changes from a remote repository to a local one.
2826 This finds all changes from the repository at the specified path or URL
2828 and adds them to a local repository (the current one unless -R is spec‐
2829 ified). By default, this does not update the copy of the project in the
2830 working directory.
2831 When cloning from servers that support it, Mercurial may fetch pre-gen‐
2833 erated data. When this is done, hooks operating on incoming changesets
2834 and changegroups may fire more than once, once for each pre-generated
2835 bundle and as well as for any additional remaining data. See hg help -e
2836 clonebundles for more.
2837 Use hg incoming if you want to see what would have been added by a pull
2839 at the time you issued this command. If you then decide to add those
2840 changes to the repository, you should use hg pull -r X where X is the
2841 last changeset listed by hg incoming.
2842 If SOURCE is omitted, the 'default' path will be used. See hg help
2844 urls for more information.
2845 Specifying bookmark as . is equivalent to specifying the active book‐
2847 mark's name.
2848 Returns 0 on success, 1 if an update had unresolved files.
2850 Options:
2852 -u, --update
2854 update to new branch head if new descendants were pulled
2855 -f, --force
2857 run even when remote repository is unrelated
2858 -r,--rev <REV[+]>
2860 a remote changeset intended to be added
2861 -B,--bookmark <BOOKMARK[+]>
2863 bookmark to pull
2864 -b,--branch <BRANCH[+]>
2866 a specific branch you would like to pull
2867 -e,--ssh <CMD>
2869 specify ssh command to use
2870 --remotecmd <CMD>
2872 specify hg command to run on the remote side
2873 --insecure
2875 do not verify server certificate (ignoring web.cacerts config)
2876 [+] marked option can be specified multiple times
2878 push
2880 push changes to the specified destination:
2881 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]
2883 Push changesets from the local repository to the specified destination.
2885 This operation is symmetrical to pull: it is identical to a pull in the
2887 destination repository from the current one.
2888 By default, push will not allow creation of new heads at the destina‐
2890 tion, since multiple heads would make it unclear which head to use. In
2891 this situation, it is recommended to pull and merge before pushing.
2892 Use --new-branch if you want to allow push to create a new named branch
2894 that is not present at the destination. This allows you to only create
2895 a new branch without forcing other changes.
2896 Note Extra care should be taken with the -f/--force option, which
2898 will push all new heads on all branches, an action which will
2899 almost always cause confusion for collaborators.
2900 If -r/--rev is used, the specified revision and all its ancestors will
2902 be pushed to the remote repository.
2903 If -B/--bookmark is used, the specified bookmarked revision, its ances‐
2905 tors, and the bookmark will be pushed to the remote repository. Speci‐
2906 fying . is equivalent to specifying the active bookmark's name.
2907 Please see hg help urls for important details about ssh:// URLs. If
2909 DESTINATION is omitted, a default path will be used.
2910 The --pushvars option sends strings to the server that become environ‐
2912 ment variables prepended with HG_USERVAR_. For example, --pushvars
2913 ENABLE_FEATURE=true, provides the server side hooks with HG_USER‐
2914 VAR_ENABLE_FEATURE=true as part of their environment.
2915 pushvars can provide for user-overridable hooks as well as set debug
2917 levels. One example is having a hook that blocks commits containing
2918 conflict markers, but enables the user to override the hook if the file
2919 is using conflict markers for testing purposes or the file format has
2920 strings that look like conflict markers.
2921 By default, servers will ignore --pushvars. To enable it add the fol‐
2923 lowing to your configuration file:
2924 [push]
2926 pushvars.server = true
2927 Returns 0 if push was successful, 1 if nothing to push.
2929 Options:
2931 -f, --force
2933 force push
2934 -r,--rev <REV[+]>
2936 a changeset intended to be included in the destination
2937 -B,--bookmark <BOOKMARK[+]>
2939 bookmark to push
2940 -b,--branch <BRANCH[+]>
2942 a specific branch you would like to push
2943 --new-branch
2945 allow pushing a new branch
2946 --pushvars <VALUE[+]>
2948 variables that can be sent to server (ADVANCED)
2949 --publish
2951 push the changeset as public (EXPERIMENTAL)
2952 -e,--ssh <CMD>
2954 specify ssh command to use
2955 --remotecmd <CMD>
2957 specify hg command to run on the remote side
2958 --insecure
2960 do not verify server certificate (ignoring web.cacerts config)
2961 [+] marked option can be specified multiple times
2963 recover
2965 roll back an interrupted transaction:
2966 hg recover
2968 Recover from an interrupted commit or pull.
2970 This command tries to fix the repository status after an interrupted
2972 operation. It should only be necessary when Mercurial suggests it.
2973 Returns 0 if successful, 1 if nothing to recover or verify fails.
2975 remove
2977 remove the specified files on the next commit:
2978 hg remove [OPTION]... FILE...
2980 Schedule the indicated files for removal from the current branch.
2982 This command schedules the files to be removed at the next commit. To
2984 undo a remove before that, see hg revert. To undo added files, see hg
2985 forget.
2986 -A/--after can be used to remove only files that have already been
2988 deleted, -f/--force can be used to force deletion, and -Af can be used
2989 to remove files from the next revision without deleting them from the
2990 working directory.
2991 The following table details the behavior of remove for different file
2993 states (columns) and option combinations (rows). The file states are
2994 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2995 status). The actions are Warn, Remove (from branch) and Delete (from
2996 disk):
2997 ┌──────────┬───┬────┬────┬───┐
2999 │opt/state │ A │ C │ M │ ! │
3000 ├──────────┼───┼────┼────┼───┤
3001 │none │ W │ RD │ W │ R │
3002 ├──────────┼───┼────┼────┼───┤
3003 │-f │ R │ RD │ RD │ R │
3004 ├──────────┼───┼────┼────┼───┤
3005 │-A │ W │ W │ W │ R │
3006 ├──────────┼───┼────┼────┼───┤
3007 │-Af │ R │ R │ R │ R │
3008 └──────────┴───┴────┴────┴───┘
3009 Note hg remove never deletes files in Added [A] state from the work‐
3011 ing directory, not even if --force is specified.
3012 Returns 0 on success, 1 if any warnings encountered.
3014 Options:
3016 -A, --after
3018 record delete for missing files
3019 -f, --force
3021 forget added files, delete modified files
3022 -S, --subrepos
3024 recurse into subrepositories
3025 -I,--include <PATTERN[+]>
3027 include names matching the given patterns
3028 -X,--exclude <PATTERN[+]>
3030 exclude names matching the given patterns
3031 -n, --dry-run
3033 do not perform actions, just print output
3034 [+] marked option can be specified multiple times
3036 aliases: rm
3038 rename
3040 rename files; equivalent of copy + remove:
3041 hg rename [OPTION]... SOURCE... DEST
3043 Mark dest as copies of sources; mark sources for deletion. If dest is a
3045 directory, copies are put in that directory. If dest is a file, there
3046 can only be one source.
3047 By default, this command copies the contents of files as they exist in
3049 the working directory. If invoked with -A/--after, the operation is
3050 recorded, but no copying is performed.
3051 This command takes effect at the next commit. To undo a rename before
3053 that, see hg revert.
3054 Returns 0 on success, 1 if errors are encountered.
3056 Options:
3058 -A, --after
3060 record a rename that has already occurred
3061 -f, --force
3063 forcibly copy over an existing managed file
3064 -I,--include <PATTERN[+]>
3066 include names matching the given patterns
3067 -X,--exclude <PATTERN[+]>
3069 exclude names matching the given patterns
3070 -n, --dry-run
3072 do not perform actions, just print output
3073 [+] marked option can be specified multiple times
3075 aliases: move mv
3077 resolve
3079 redo merges or set/view the merge status of files:
3080 hg resolve [OPTION]... [FILE]...
3082 Merges with unresolved conflicts are often the result of non-interac‐
3084 tive merging using the internal:merge configuration setting, or a com‐
3085 mand-line merge tool like diff3. The resolve command is used to manage
3086 the files involved in a merge, after hg merge has been run, and before
3087 hg commit is run (i.e. the working directory must have two parents).
3088 See hg help merge-tools for information on configuring merge tools.
3089 The resolve command can be used in the following ways:
3091 · hg resolve [--re-merge] [--tool TOOL] FILE...: attempt to re-merge
3093 the specified files, discarding any previous merge attempts. Re-merg‐
3094 ing is not performed for files already marked as resolved. Use
3095 --all/-a to select all unresolved files. --tool can be used to spec‐
3096 ify the merge tool used for the given files. It overrides the HGMERGE
3097 environment variable and your configuration files. Previous file
3098 contents are saved with a .orig suffix.
3099 · hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
3101 having manually fixed-up the files). The default is to mark all unre‐
3102 solved files.
3103 · hg resolve -u [FILE]...: mark a file as unresolved. The default is to
3105 mark all resolved files.
3106 · hg resolve -l: list files which had or still have conflicts. In the
3108 printed list, U = unresolved and R = resolved. You can use set:unre‐
3109 solved() or set:resolved() to filter the list. See hg help filesets
3110 for details.
3111 Note Mercurial will not let you commit files with unresolved merge
3113 conflicts. You must use hg resolve -m ... before you can commit
3114 after a conflicting merge.
3115 Template:
3117 The following keywords are supported in addition to the common template
3119 keywords and functions. See also hg help templates.
3120 mergestatus
3122 String. Character denoting merge conflicts, U or R.
3123 path String. Repository-absolute path of the file.
3125 Returns 0 on success, 1 if any files fail a resolve attempt.
3127 Options:
3129 -a, --all
3131 select all unresolved files
3132 -l, --list
3134 list state of files needing merge
3135 -m, --mark
3137 mark files as resolved
3138 -u, --unmark
3140 mark files as unresolved
3141 -n, --no-status
3143 hide status prefix
3144 --re-merge
3146 re-merge files
3147 -t,--tool <TOOL>
3149 specify merge tool
3150 -I,--include <PATTERN[+]>
3152 include names matching the given patterns
3153 -X,--exclude <PATTERN[+]>
3155 exclude names matching the given patterns
3156 -T,--template <TEMPLATE>
3158 display with template
3159 [+] marked option can be specified multiple times
3161 revert
3163 restore files to their checkout state:
3164 hg revert [OPTION]... [-r REV] [NAME]...
3166 Note To check out earlier revisions, you should use hg update REV.
3168 To cancel an uncommitted merge (and lose your changes), use hg
3169 merge --abort.
3170 With no revision specified, revert the specified files or directories
3172 to the contents they had in the parent of the working directory. This
3173 restores the contents of files to an unmodified state and unschedules
3174 adds, removes, copies, and renames. If the working directory has two
3175 parents, you must explicitly specify a revision.
3176 Using the -r/--rev or -d/--date options, revert the given files or
3178 directories to their states as of a specific revision. Because revert
3179 does not change the working directory parents, this will cause these
3180 files to appear modified. This can be helpful to "back out" some or all
3181 of an earlier change. See hg backout for a related method.
3182 Modified files are saved with a .orig suffix before reverting. To dis‐
3184 able these backups, use --no-backup. It is possible to store the backup
3185 files in a custom directory relative to the root of the repository by
3186 setting the ui.origbackuppath configuration option.
3187 See hg help dates for a list of formats valid for -d/--date.
3189 See hg help backout for a way to reverse the effect of an earlier
3191 changeset.
3192 Returns 0 on success.
3194 Options:
3196 -a, --all
3198 revert all changes when no arguments given
3199 -d,--date <DATE>
3201 tipmost revision matching date
3202 -r,--rev <REV>
3204 revert to the specified revision
3205 -C, --no-backup
3207 do not save backup copies of files
3208 -i, --interactive
3210 interactively select the changes
3211 -I,--include <PATTERN[+]>
3213 include names matching the given patterns
3214 -X,--exclude <PATTERN[+]>
3216 exclude names matching the given patterns
3217 -n, --dry-run
3219 do not perform actions, just print output
3220 [+] marked option can be specified multiple times
3222 rollback
3224 roll back the last transaction (DANGEROUS) (DEPRECATED):
3225 hg rollback
3227 Please use hg commit --amend instead of rollback to correct mistakes in
3229 the last commit.
3230 This command should be used with care. There is only one level of roll‐
3232 back, and there is no way to undo a rollback. It will also restore the
3233 dirstate at the time of the last transaction, losing any dirstate
3234 changes since that time. This command does not alter the working direc‐
3235 tory.
3236 Transactions are used to encapsulate the effects of all commands that
3238 create new changesets or propagate existing changesets into a reposi‐
3239 tory.
3240 For example, the following commands are transactional, and their
3242 effects can be rolled back:
3243 · commit
3245 · import
3247 · pull
3249 · push (with this repository as the destination)
3251 · unbundle
3253 To avoid permanent data loss, rollback will refuse to rollback a commit
3255 transaction if it isn't checked out. Use --force to override this pro‐
3256 tection.
3257 The rollback command can be entirely disabled by setting the ui.roll‐
3259 back configuration setting to false. If you're here because you want to
3260 use rollback and it's disabled, you can re-enable the command by set‐
3261 ting ui.rollback to true.
3262 This command is not intended for use on public repositories. Once
3264 changes are visible for pull by other users, rolling a transaction back
3265 locally is ineffective (someone else may already have pulled the
3266 changes). Furthermore, a race is possible with readers of the reposi‐
3267 tory; for example an in-progress pull from the repository may fail if a
3268 rollback is performed.
3269 Returns 0 on success, 1 if no rollback data is available.
3271 Options:
3273 -n, --dry-run
3275 do not perform actions, just print output
3276 -f, --force
3278 ignore safety measures
3279 root
3281 print the root (top) of the current working directory:
3282 hg root
3284 Print the root directory of the current repository.
3286 Returns 0 on success.
3288 serve
3290 start stand-alone webserver:
3291 hg serve [OPTION]...
3293 Start a local HTTP repository browser and pull server. You can use this
3295 for ad-hoc sharing and browsing of repositories. It is recommended to
3296 use a real web server to serve a repository for longer periods of time.
3297 Please note that the server does not implement access control. This
3299 means that, by default, anybody can read from the server and nobody can
3300 write to it by default. Set the web.allow-push option to * to allow
3301 everybody to push to the server. You should use a real web server if
3302 you need to authenticate users.
3303 By default, the server logs accesses to stdout and errors to stderr.
3305 Use the -A/--accesslog and -E/--errorlog options to log to files.
3306 To have the server choose a free port number to listen on, specify a
3308 port number of 0; in this case, the server will print the port number
3309 it uses.
3310 Returns 0 on success.
3312 Options:
3314 -A,--accesslog <FILE>
3316 name of access log file to write to
3317 -d, --daemon
3319 run server in background
3320 --daemon-postexec <VALUE[+]>
3322 used internally by daemon mode
3323 -E,--errorlog <FILE>
3325 name of error log file to write to
3326 -p,--port <PORT>
3328 port to listen on (default: 8000)
3329 -a,--address <ADDR>
3331 address to listen on (default: all interfaces)
3332 --prefix <PREFIX>
3334 prefix path to serve from (default: server root)
3335 -n,--name <NAME>
3337 name to show in web pages (default: working directory)
3338 --web-conf <FILE>
3340 name of the hgweb config file (see 'hg help hgweb')
3341 --webdir-conf <FILE>
3343 name of the hgweb config file (DEPRECATED)
3344 --pid-file <FILE>
3346 name of file to write process ID to
3347 --stdio
3349 for remote clients (ADVANCED)
3350 --cmdserver <MODE>
3352 for remote clients (ADVANCED)
3353 -t,--templates <TEMPLATE>
3355 web templates to use
3356 --style <STYLE>
3358 template style to use
3359 -6, --ipv6
3361 use IPv6 in addition to IPv4
3362 --certificate <FILE>
3364 SSL certificate file
3365 --print-url
3367 start and print only the URL
3368 -S, --subrepos
3370 recurse into subrepositories
3371 [+] marked option can be specified multiple times
3373 status
3375 show changed files in the working directory:
3376 hg status [OPTION]... [FILE]...
3378 Show status of files in the repository. If names are given, only files
3380 that match are shown. Files that are clean or ignored or the source of
3381 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3382 -C/--copies or -A/--all are given. Unless options described with "show
3383 only ..." are given, the options -mardu are used.
3384 Option -q/--quiet hides untracked (unknown and ignored) files unless
3386 explicitly requested with -u/--unknown or -i/--ignored.
3387 Note hg status may appear to disagree with diff if permissions have
3389 changed or a merge has occurred. The standard diff format does
3390 not report permission changes and diff only reports changes rel‐
3391 ative to one merge parent.
3392 If one revision is given, it is used as the base revision. If two
3394 revisions are given, the differences between them are shown. The
3395 --change option can also be used as a shortcut to list the changed
3396 files of a revision from its first parent.
3397 The codes used to show the status of files are:
3399 M = modified
3401 A = added
3402 R = removed
3403 C = clean
3404 ! = missing (deleted by non-hg command, but still tracked)
3405 ? = not tracked
3406 I = ignored
3407 = origin of the previous file (with --copies)
3408 The -t/--terse option abbreviates the output by showing only the direc‐
3410 tory name if all the files in it share the same status. The option
3411 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3412 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3413 'unknown', 'i' for 'ignored' and 'c' for clean.
3414 It abbreviates only those statuses which are passed. Note that clean
3416 and ignored files are not displayed with '--terse ic' unless the
3417 -c/--clean and -i/--ignored options are also used.
3418 The -v/--verbose option shows information when the repository is in an
3420 unfinished merge, shelve, rebase state etc. You can have this behavior
3421 turned on by default by enabling the commands.status.verbose option.
3422 You can skip displaying some of these states by setting commands.sta‐
3424 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3425 'merge', 'rebase', or 'unshelve'.
3426 Template:
3428 The following keywords are supported in addition to the common template
3430 keywords and functions. See also hg help templates.
3431 path String. Repository-absolute path of the file.
3433 source String. Repository-absolute path of the file originated from.
3435 Available if --copies is specified.
3436 status String. Character denoting file's status.
3438 Examples:
3440 · show changes in the working directory relative to a changeset:
3442 hg status --rev 9353
3444 · show changes in the working directory relative to the current direc‐
3446 tory (see hg help patterns for more information):
3447 hg status re:
3449 · show all changes including copies in an existing changeset:
3451 hg status --copies --change 9353
3453 · get a NUL separated list of added files, suitable for xargs:
3455 hg status -an0
3457 · show more information about the repository status, abbreviating
3459 added, removed, modified, deleted, and untracked paths:
3460 hg status -v -t mardu
3462 Returns 0 on success.
3464 Options:
3466 -A, --all
3468 show status of all files
3469 -m, --modified
3471 show only modified files
3472 -a, --added
3474 show only added files
3475 -r, --removed
3477 show only removed files
3478 -d, --deleted
3480 show only deleted (but tracked) files
3481 -c, --clean
3483 show only files without changes
3484 -u, --unknown
3486 show only unknown (not tracked) files
3487 -i, --ignored
3489 show only ignored files
3490 -n, --no-status
3492 hide status prefix
3493 -t,--terse <VALUE>
3495 show the terse output (EXPERIMENTAL) (default: nothing)
3496 -C, --copies
3498 show source of copied files
3499 -0, --print0
3501 end filenames with NUL, for use with xargs
3502 --rev <REV[+]>
3504 show difference from revision
3505 --change <REV>
3507 list the changed files of a revision
3508 -I,--include <PATTERN[+]>
3510 include names matching the given patterns
3511 -X,--exclude <PATTERN[+]>
3513 exclude names matching the given patterns
3514 -S, --subrepos
3516 recurse into subrepositories
3517 -T,--template <TEMPLATE>
3519 display with template
3520 [+] marked option can be specified multiple times
3522 aliases: st
3524 summary
3526 summarize working directory state:
3527 hg summary [--remote]
3529 This generates a brief summary of the working directory state, includ‐
3531 ing parents, branch, commit status, phase and available updates.
3532 With the --remote option, this will check the default paths for incom‐
3534 ing and outgoing changes. This can be time-consuming.
3535 Returns 0 on success.
3537 Options:
3539 --remote
3541 check for push and pull
3542 aliases: sum
3544 tag
3546 add one or more tags for the current or given revision:
3547 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
3549 Name a particular revision using <name>.
3551 Tags are used to name particular revisions of the repository and are
3553 very useful to compare different revisions, to go back to significant
3554 earlier versions or to mark branch points as releases, etc. Changing an
3555 existing tag is normally disallowed; use -f/--force to override.
3556 If no revision is given, the parent of the working directory is used.
3558 To facilitate version control, distribution, and merging of tags, they
3560 are stored as a file named ".hgtags" which is managed similarly to
3561 other project files and can be hand-edited if necessary. This also
3562 means that tagging creates a new commit. The file ".hg/localtags" is
3563 used for local tags (not shared among repositories).
3564 Tag commits are usually made at the head of a branch. If the parent of
3566 the working directory is not a branch head, hg tag aborts; use
3567 -f/--force to force the tag commit to be based on a non-head changeset.
3568 See hg help dates for a list of formats valid for -d/--date.
3570 Since tag names have priority over branch names during revision lookup,
3572 using an existing branch name as a tag name is discouraged.
3573 Returns 0 on success.
3575 Options:
3577 -f, --force
3579 force tag
3580 -l, --local
3582 make the tag local
3583 -r,--rev <REV>
3585 revision to tag
3586 --remove
3588 remove a tag
3589 -e, --edit
3591 invoke editor on commit messages
3592 -m,--message <TEXT>
3594 use text as commit message
3595 -d,--date <DATE>
3597 record the specified date as commit date
3598 -u,--user <USER>
3600 record the specified user as committer
3601 tags
3603 list repository tags:
3604 hg tags
3606 This lists both regular and local tags. When the -v/--verbose switch is
3608 used, a third column "local" is printed for local tags. When the
3609 -q/--quiet switch is used, only the tag name is printed.
3610 Template:
3612 The following keywords are supported in addition to the common template
3614 keywords and functions such as {tag}. See also hg help templates.
3615 type String. local for local tags.
3617 Returns 0 on success.
3619 Options:
3621 -T,--template <TEMPLATE>
3623 display with template
3624 tip
3626 show the tip revision (DEPRECATED):
3627 hg tip [-p] [-g]
3629 The tip revision (usually just called the tip) is the changeset most
3631 recently added to the repository (and therefore the most recently
3632 changed head).
3633 If you have just made a commit, that commit will be the tip. If you
3635 have just pulled changes from another repository, the tip of that
3636 repository becomes the current tip. The "tip" tag is special and cannot
3637 be renamed or assigned to a different changeset.
3638 This command is deprecated, please use hg heads instead.
3640 Returns 0 on success.
3642 Options:
3644 -p, --patch
3646 show patch
3647 -g, --git
3649 use git extended diff format
3650 --style <STYLE>
3652 display using template map file (DEPRECATED)
3653 -T,--template <TEMPLATE>
3655 display with template
3656 unbundle
3658 apply one or more bundle files:
3659 hg unbundle [-u] FILE...
3661 Apply one or more bundle files generated by hg bundle.
3663 Returns 0 on success, 1 if an update has unresolved files.
3665 Options:
3667 -u, --update
3669 update to new branch head if changesets were unbundled
3670 update
3672 update working directory (or switch revisions):
3673 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3675 Update the repository's working directory to the specified changeset.
3677 If no changeset is specified, update to the tip of the current named
3678 branch and move the active bookmark (see hg help bookmarks).
3679 Update sets the working directory's parent revision to the specified
3681 changeset (see hg help parents).
3682 If the changeset is not a descendant or ancestor of the working direc‐
3684 tory's parent and there are uncommitted changes, the update is aborted.
3685 With the -c/--check option, the working directory is checked for uncom‐
3686 mitted changes; if none are found, the working directory is updated to
3687 the specified changeset.
3688 The -C/--clean, -c/--check, and -m/--merge options control what happens
3690 if the working directory contains uncommitted changes. At most of one
3691 of them can be specified.
3692 1. If no option is specified, and if the requested changeset is an
3694 ancestor or descendant of the working directory's parent, the uncom‐
3695 mitted changes are merged into the requested changeset and the
3696 merged result is left uncommitted. If the requested changeset is not
3697 an ancestor or descendant (that is, it is on another branch), the
3698 update is aborted and the uncommitted changes are preserved.
3699 2. With the -m/--merge option, the update is allowed even if the
3701 requested changeset is not an ancestor or descendant of the working
3702 directory's parent.
3703 3. With the -c/--check option, the update is aborted and the uncommit‐
3705 ted changes are preserved.
3706 4. With the -C/--clean option, uncommitted changes are discarded and
3708 the working directory is updated to the requested changeset.
3709 To cancel an uncommitted merge (and lose your changes), use hg merge
3711 --abort.
3712 Use null as the changeset to remove the working directory (like hg
3714 clone -U).
3715 If you want to revert just one file to an older revision, use hg revert
3717 [-r REV] NAME.
3718 See hg help dates for a list of formats valid for -d/--date.
3720 Returns 0 on success, 1 if there are unresolved files.
3722 Options:
3724 -C, --clean
3726 discard uncommitted changes (no backup)
3727 -c, --check
3729 require clean working directory
3730 -m, --merge
3732 merge uncommitted changes
3733 -d,--date <DATE>
3735 tipmost revision matching date
3736 -r,--rev <REV>
3738 revision
3739 -t,--tool <TOOL>
3741 specify merge tool
3742 aliases: up checkout co
3744 verify
3746 verify the integrity of the repository:
3747 hg verify
3749 Verify the integrity of the current repository.
3751 This will perform an extensive check of the repository's integrity,
3753 validating the hashes and checksums of each entry in the changelog,
3754 manifest, and tracked files, as well as the integrity of their
3755 crosslinks and indices.
3756 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
3758 information about recovery from corruption of the repository.
3759 Returns 0 on success, 1 if errors are encountered.
3761 version
3763 output version and copyright information:
3764 hg version
3766 Template:
3768 The following keywords are supported. See also hg help templates.
3770 extensions
3772 List of extensions.
3773 ver String. Version number.
3775 And each entry of {extensions} provides the following sub-keywords in
3777 addition to {ver}.
3778 bundled
3780 Boolean. True if included in the release.
3781 name String. Extension name.
3783 Options:
3785 -T,--template <TEMPLATE>
3787 display with template
3788
3790 Mercurial supports generating standalone "bundle" files that hold
3791 repository data. These "bundles" are typically saved locally and used
3792 later or exchanged between different repositories, possibly on differ‐
3793 ent machines. Example commands using bundles are hg bundle and hg
3794 unbundle.
3795 Generation of bundle files is controlled by a "bundle specification"
3797 ("bundlespec") string. This string tells the bundle generation process
3798 how to create the bundle.
3799 A "bundlespec" string is composed of the following elements:
3801 type A string denoting the bundle format to use.
3803 compression
3805 Denotes the compression engine to use compressing the raw bundle
3806 data.
3807 parameters
3809 Arbitrary key-value parameters to further control bundle genera‐
3810 tion.
3811 A "bundlespec" string has the following formats:
3813 <type> The literal bundle format string is used.
3815 <compression>-<type>
3817 The compression engine and format are delimited by a hyphen (-).
3818 Optional parameters follow the <type>. Parameters are URI escaped
3820 key=value pairs. Each pair is delimited by a semicolon (;). The first
3821 parameter begins after a ; immediately following the <type> value.
3822 Available Types
3824 The following bundle <type> strings are available:
3825 v1 Produces a legacy "changegroup" version 1 bundle.
3827 This format is compatible with nearly all Mercurial clients
3829 because it is the oldest. However, it has some limitations,
3830 which is why it is no longer the default for new repositories.
3831 v1 bundles can be used with modern repositories using the "gen‐
3833 eraldelta" storage format. However, it may take longer to pro‐
3834 duce the bundle and the resulting bundle may be significantly
3835 larger than a v2 bundle.
3836 v1 bundles can only use the gzip, bzip2, and none compression
3838 formats.
3839 v2 Produces a version 2 bundle.
3841 Version 2 bundles are an extensible format that can store addi‐
3843 tional repository data (such as bookmarks and phases informa‐
3844 tion) and they can store data more efficiently, resulting in
3845 smaller bundles.
3846 Version 2 bundles can also use modern compression engines, such
3848 as zstd, making them faster to compress and often smaller.
3849 Available Compression Engines
3851 The following bundle <compression> engines can be used:
3852 bzip2
3854 An algorithm that produces smaller bundles than gzip.
3856 All Mercurial clients should support this format.
3858 This engine will likely produce smaller bundles than gzip but
3860 will be significantly slower, both during compression and decom‐
3861 pression.
3862 If available, the zstd engine can yield similar or better com‐
3864 pression at much higher speeds.
3865 gzip
3867 zlib compression using the DEFLATE algorithm.
3869 All Mercurial clients should support this format. The compres‐
3871 sion algorithm strikes a reasonable balance between compression
3872 ratio and size.
3873 none
3875 No compression is performed.
3877 Use this compression engine to explicitly disable compression.
3879 Examples
3881 v2
3882 Produce a v2 bundle using default options, including compres‐
3884 sion.
3885 none-v1
3887 Produce a v1 bundle with no compression.
3889 zstd-v2
3891 Produce a v2 bundle with zstandard compression using default
3893 settings.
3894 zstd-v1
3896 This errors because zstd is not supported for v1 types.
3898
3900 Mercurial colorizes output from several commands.
3901 For example, the diff command shows additions in green and deletions in
3903 red, while the status command shows modified files in magenta. Many
3904 other commands have analogous colors. It is possible to customize these
3905 colors.
3906 To enable color (default) whenever possible use:
3908 [ui]
3910 color = yes
3911 To disable color use:
3913 [ui]
3915 color = no
3916 See hg help config.ui.color for details.
3918 The default pager on Windows does not support color, so enabling the
3920 pager will effectively disable color. See hg help config.ui.paginate
3921 to disable the pager. Alternately, MSYS and Cygwin shells provide less
3922 as a pager, which can be configured to support ANSI color mode. Win‐
3923 dows 10 natively supports ANSI color mode.
3924 Mode
3926 Mercurial can use various systems to display color. The supported modes
3927 are ansi, win32, and terminfo. See hg help config.color for details
3928 about how to control the mode.
3929 Effects
3931 Other effects in addition to color, like bold and underlined text, are
3932 also available. By default, the terminfo database is used to find the
3933 terminal codes used to change color and effect. If terminfo is not
3934 available, then effects are rendered with the ECMA-48 SGR control func‐
3935 tion (aka ANSI escape codes).
3936 The available effects in terminfo mode are 'blink', 'bold', 'dim',
3938 'inverse', 'invisible', 'italic', 'standout', and 'underline'; in
3939 ECMA-48 mode, the options are 'bold', 'inverse', 'italic', and 'under‐
3940 line'. How each is rendered depends on the terminal emulator. Some
3941 may not be available for a given terminal type, and will be silently
3942 ignored.
3943 If the terminfo entry for your terminal is missing codes for an effect
3945 or has the wrong codes, you can add or override those codes in your
3946 configuration:
3947 [color]
3949 terminfo.dim = \E[2m
3950 where 'E' is substituted with an escape character.
3952 Labels
3954 Text receives color effects depending on the labels that it has. Many
3955 default Mercurial commands emit labelled text. You can also define your
3956 own labels in templates using the label function, see hg help templates
3957 . A single portion of text may have more than one label. In that case,
3958 effects given to the last label will override any other effects. This
3959 includes the special "none" effect, which nullifies other effects.
3960 Labels are normally invisible. In order to see these labels and their
3962 position in the text, use the global --color=debug option. The same
3963 anchor text may be associated to multiple labels, e.g.
3964 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
3966 The following are the default effects for some default labels. Default
3968 effects may be overridden from your configuration file:
3969 [color]
3971 status.modified = blue bold underline red_background
3972 status.added = green bold
3973 status.removed = red bold blue_background
3974 status.deleted = cyan bold underline
3975 status.unknown = magenta bold underline
3976 status.ignored = black bold
3977 # 'none' turns off all effects
3979 status.clean = none
3980 status.copied = none
3981 qseries.applied = blue bold underline
3983 qseries.unapplied = black bold
3984 qseries.missing = red bold
3985 diff.diffline = bold
3987 diff.extended = cyan bold
3988 diff.file_a = red bold
3989 diff.file_b = green bold
3990 diff.hunk = magenta
3991 diff.deleted = red
3992 diff.inserted = green
3993 diff.changed = white
3994 diff.tab =
3995 diff.trailingwhitespace = bold red_background
3996 # Blank so it inherits the style of the surrounding label
3998 changeset.public =
3999 changeset.draft =
4000 changeset.secret =
4001 resolve.unresolved = red bold
4003 resolve.resolved = green bold
4004 bookmarks.active = green
4006 branches.active = none
4008 branches.closed = black bold
4009 branches.current = green
4010 branches.inactive = none
4011 tags.normal = green
4013 tags.local = black bold
4014 rebase.rebased = blue
4016 rebase.remaining = red bold
4017 shelve.age = cyan
4019 shelve.newest = green bold
4020 shelve.name = blue bold
4021 histedit.remaining = red bold
4023 Custom colors
4025 Because there are only eight standard colors, Mercurial allows you to
4026 define color names for other color slots which might be available for
4027 your terminal type, assuming terminfo mode. For instance:
4028 color.brightblue = 12
4030 color.pink = 207
4031 color.orange = 202
4032 to set 'brightblue' to color slot 12 (useful for 16 color terminals
4034 that have brighter colors defined in the upper eight) and, 'pink' and
4035 'orange' to colors in 256-color xterm's default color cube. These
4036 defined colors may then be used as any of the pre-defined eight,
4037 including appending '_background' to set the background to that color.
4038
4040 Some commands allow the user to specify a date, e.g.:
4041 · backout, commit, import, tag: Specify the commit date.
4043 · log, revert, update: Select revision(s) by date.
4045 Many date formats are valid. Here are some examples:
4047 · Wed Dec 6 13:18:29 2006 (local timezone assumed)
4049 · Dec 6 13:18 -0600 (year assumed, time offset provided)
4051 · Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
4053 · Dec 6 (midnight)
4055 · 13:18 (today assumed)
4057 · 3:39 (3:39AM assumed)
4059 · 3:39pm (15:39)
4061 · 2006-12-06 13:18:29 (ISO 8601 format)
4063 · 2006-12-6 13:18
4065 · 2006-12-6
4067 · 12-6
4069 · 12/6
4071 · 12/6/6 (Dec 6 2006)
4073 · today (midnight)
4075 · yesterday (midnight)
4077 · now - right now
4079 Lastly, there is Mercurial's internal format:
4081 · 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
4083 This is the internal representation format for dates. The first number
4085 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
4086 second is the offset of the local timezone, in seconds west of UTC
4087 (negative if the timezone is east of UTC).
4088 The log command also accepts date ranges:
4090 · <DATE - at or before a given date/time
4092 · >DATE - on or after a given date/time
4094 · DATE to DATE - a date range, inclusive
4096 · -DAYS - within a given number of days of today
4098
4100 Mercurial evolves over time, some features, options, commands may be
4101 replaced by better and more secure alternatives. This topic will help
4102 you migrating your existing usage and/or configuration to newer fea‐
4103 tures.
4104 Commands
4106 The following commands are still available but their use are not recom‐
4107 mended:
4108 locate
4110 This command has been replaced by hg files.
4112 parents
4114 This command can be replaced by hg summary or hg log with appropriate
4116 revsets. See hg help revsets for more information.
4117 tip
4119 The recommended alternative is hg heads.
4121 Options
4123 web.allowpull
4124 Renamed to allow-pull.
4126 web.allow_push
4128 Renamed to allow-push.
4130
4132 Mercurial's default format for showing changes between two versions of
4133 a file is compatible with the unified format of GNU diff, which can be
4134 used by GNU patch and many other standard tools.
4135 While this standard format is often enough, it does not encode the fol‐
4137 lowing information:
4138 · executable status and other permission bits
4140 · copy or rename information
4142 · changes in binary files
4144 · creation or deletion of empty files
4146 Mercurial also supports the extended diff format from the git VCS which
4148 addresses these limitations. The git diff format is not produced by
4149 default because a few widespread tools still do not understand this
4150 format.
4151 This means that when generating diffs from a Mercurial repository (e.g.
4153 with hg export), you should be careful about things like file copies
4154 and renames or other things mentioned above, because when applying a
4155 standard diff to a different repository, this extra information is
4156 lost. Mercurial's internal operations (like push and pull) are not
4157 affected by this, because they use an internal binary format for commu‐
4158 nicating changes.
4159 To make Mercurial produce the git extended diff format, use the --git
4161 option available for many commands, or set 'git = True' in the [diff]
4162 section of your configuration file. You do not need to set this option
4163 when importing diffs in this format or using them in the mq extension.
4164
4166 HG Path to the 'hg' executable, automatically passed when running
4167 hooks, extensions or external tools. If unset or empty, this is
4168 the hg executable's name if it's frozen, or an executable named
4169 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
4170 on Windows) is searched.
4171 HGEDITOR
4173 This is the name of the editor to run when committing. See EDI‐
4174 TOR.
4175 (deprecated, see hg help config.ui.editor)
4177 HGENCODING
4179 This overrides the default locale setting detected by Mercurial.
4180 This setting is used to convert data including usernames,
4181 changeset descriptions, tag names, and branches. This setting
4182 can be overridden with the --encoding command-line option.
4183 HGENCODINGMODE
4185 This sets Mercurial's behavior for handling unknown characters
4186 while transcoding user input. The default is "strict", which
4187 causes Mercurial to abort if it can't map a character. Other
4188 settings include "replace", which replaces unknown characters,
4189 and "ignore", which drops them. This setting can be overridden
4190 with the --encodingmode command-line option.
4191 HGENCODINGAMBIGUOUS
4193 This sets Mercurial's behavior for handling characters with
4194 "ambiguous" widths like accented Latin characters with East
4195 Asian fonts. By default, Mercurial assumes ambiguous characters
4196 are narrow, set this variable to "wide" if such characters cause
4197 formatting problems.
4198 HGMERGE
4200 An executable to use for resolving merge conflicts. The program
4201 will be executed with three arguments: local file, remote file,
4202 ancestor file.
4203 (deprecated, see hg help config.ui.merge)
4205 HGRCPATH
4207 A list of files or directories to search for configuration
4208 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
4209 PATH is not set, platform default search path is used. If empty,
4210 only the .hg/hgrc from the current repository is read.
4211 For each element in HGRCPATH:
4213 · if it's a directory, all files ending with .rc are added
4215 · otherwise, the file itself will be added
4217 HGPLAIN
4219 When set, this disables any configuration settings that might
4220 change Mercurial's default output. This includes encoding,
4221 defaults, verbose mode, debug mode, quiet mode, tracebacks, and
4222 localization. This can be useful when scripting against Mercu‐
4223 rial in the face of existing user configuration.
4224 In addition to the features disabled by HGPLAIN=, the following
4226 values can be specified to adjust behavior:
4227 +strictflags
4229 Restrict parsing of command line flags.
4231 Equivalent options set via command line flags or environment
4233 variables are not overridden.
4234 See hg help scripting for details.
4236 HGPLAINEXCEPT
4238 This is a comma-separated list of features to preserve when
4239 HGPLAIN is enabled. Currently the following values are sup‐
4240 ported:
4241 alias
4243 Don't remove aliases.
4245 color
4247 Don't disable colored output.
4249 i18n
4251 Preserve internationalization.
4253 revsetalias
4255 Don't remove revset aliases.
4257 templatealias
4259 Don't remove template aliases.
4261 progress
4263 Don't hide progress output.
4265 Setting HGPLAINEXCEPT to anything (even an empty string) will
4267 enable plain mode.
4268 HGUSER This is the string used as the author of a commit. If not set,
4270 available values will be considered in this order:
4271 · HGUSER (deprecated)
4273 · configuration files from the HGRCPATH
4275 · EMAIL
4277 · interactive prompt
4279 · LOGNAME (with @hostname appended)
4281 (deprecated, see hg help config.ui.username)
4283 EMAIL May be used as the author of a commit; see HGUSER.
4285 LOGNAME
4287 May be used as the author of a commit; see HGUSER.
4288 VISUAL This is the name of the editor to use when committing. See EDI‐
4290 TOR.
4291 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
4293 user to modify, for example when writing commit messages. The
4294 editor it uses is determined by looking at the environment vari‐
4295 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
4296 non-empty one is chosen. If all of them are empty, the editor
4297 defaults to 'vi'.
4298 PYTHONPATH
4300 This is used by Python to find imported modules and may need to
4301 be set appropriately if this Mercurial is not installed sys‐
4302 tem-wide.
4303
4305 Mercurial has the ability to add new features through the use of exten‐
4306 sions. Extensions may add new commands, add options to existing com‐
4307 mands, change the default behavior of commands, or implement hooks.
4308 To enable the "foo" extension, either shipped with Mercurial or in the
4310 Python search path, create an entry for it in your configuration file,
4311 like this:
4312 [extensions]
4314 foo =
4315 You may also specify the full path to an extension:
4317 [extensions]
4319 myfeature = ~/.hgext/myfeature.py
4320 See hg help config for more information on configuration files.
4322 Extensions are not loaded by default for a variety of reasons: they can
4324 increase startup overhead; they may be meant for advanced usage only;
4325 they may provide potentially dangerous abilities (such as letting you
4326 destroy or modify history); they might not be ready for prime time; or
4327 they may alter some usual behaviors of stock Mercurial. It is thus up
4328 to the user to activate extensions as needed.
4329 To explicitly disable an extension enabled in a configuration file of
4331 broader scope, prepend its path with !:
4332 [extensions]
4334 # disabling extension bar residing in /path/to/extension/bar.py
4335 bar = !/path/to/extension/bar.py
4336 # ditto, but no path was supplied for extension baz
4337 baz = !
4338 disabled extensions:
4340 acl hooks for controlling repository access
4342 blackbox
4344 log repository events to a blackbox for debugging
4345 bugzilla
4347 hooks for integrating with the Bugzilla bug tracker
4348 censor erase file content at a given revision
4350 churn command to display statistics about repository history
4352 clonebundles
4354 advertise pre-generated bundles to seed clones
4355 closehead
4357 close arbitrary heads without checking them out first
4358 convert
4360 import revisions from foreign VCS repositories into Mercurial
4361 eol automatically manage newlines in repository files
4363 extdiff
4365 command to allow external programs to compare revisions
4366 factotum
4368 http authentication with factotum
4369 githelp
4371 try mapping git commands to Mercurial commands
4372 gpg commands to sign and verify changesets
4374 hgk browse the repository in a graphical way
4376 highlight
4378 syntax highlighting for hgweb (requires Pygments)
4379 histedit
4381 interactive history editing
4382 keyword
4384 expand keywords in tracked files
4385 largefiles
4387 track large binary files
4388 mq manage a stack of patches
4390 notify hooks for sending email push notifications
4392 patchbomb
4394 command to send changesets as (a series of) patch emails
4395 purge command to delete untracked files from the working directory
4397 rebase command to move sets of revisions to a different ancestor
4399 relink recreates hardlinks between repository clones
4401 schemes
4403 extend schemes with shortcuts to repository swarms
4404 share share a common history between several working directories
4406 shelve save and restore changes to the working directory
4408 strip strip changesets and their descendants from history
4410 transplant
4412 command to transplant changesets from another branch
4413 win32mbcs
4415 allow the use of MBCS paths with problematic encodings
4416 zeroconf
4418 discover and advertise repositories on the local network
4419
4421 Mercurial supports a functional language for selecting a set of files.
4422 Like other file patterns, this pattern type is indicated by a prefix,
4424 'set:'. The language supports a number of predicates which are joined
4425 by infix operators. Parenthesis can be used for grouping.
4426 Identifiers such as filenames or patterns must be quoted with single or
4428 double quotes if they contain characters outside of
4429 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4430 predicates. This generally applies to file patterns other than globs
4431 and arguments for predicates. Pattern prefixes such as path: may be
4432 specified without quoting.
4433 Special characters can be used in quoted identifiers by escaping them,
4435 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4436 preted, strings can be prefixed with r, e.g. r'...'.
4437 See also hg help patterns.
4439 Operators
4441 There is a single prefix operator:
4442 not x
4444 Files not in x. Short form is ! x.
4446 These are the supported infix operators:
4448 x and y
4450 The intersection of files in x and y. Short form is x & y.
4452 x or y
4454 The union of files in x and y. There are two alternative short
4456 forms: x | y and x + y.
4457 x - y
4459 Files in x but not in y.
4461 Predicates
4463 The following predicates are supported:
4464 added()
4466 File that is added according to hg status.
4468 binary()
4470 File that appears to be binary (contains NUL bytes).
4472 clean()
4474 File that is clean according to hg status.
4476 copied()
4478 File that is recorded as being copied.
4480 deleted()
4482 Alias for missing().
4484 encoding(name)
4486 File can be successfully decoded with the given character encod‐
4488 ing. May not be useful for encodings other than ASCII and UTF-8.
4489 eol(style)
4491 File contains newlines of the given style (dos, unix, mac).
4493 Binary files are excluded, files with mixed line endings match
4494 multiple styles.
4495 exec()
4497 File that is marked as executable.
4499 grep(regex)
4501 File contains the given regular expression.
4503 hgignore()
4505 File that matches the active .hgignore pattern.
4507 ignored()
4509 File that is ignored according to hg status.
4511 missing()
4513 File that is missing according to hg status.
4515 modified()
4517 File that is modified according to hg status.
4519 portable()
4521 File that has a portable name. (This doesn't include filenames
4523 with case collisions.)
4524 removed()
4526 File that is removed according to hg status.
4528 resolved()
4530 File that is marked resolved according to hg resolve -l.
4532 revs(revs, pattern)
4534 Evaluate set in the specified revisions. If the revset match
4536 multiple revs, this will return file matching pattern in any of
4537 the revision.
4538 size(expression)
4540 File size matches the given expression. Examples:
4542 · size('1k') - files from 1024 to 2047 bytes
4544 · size('< 20k') - files less than 20480 bytes
4546 · size('>= .5MB') - files at least 524288 bytes
4548 · size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
4550 status(base, rev, pattern)
4552 Evaluate predicate using status change between base and rev.
4554 Examples:
4555 · status(3, 7, added()) - matches files added from "3" to "7"
4557 subrepo([pattern])
4559 Subrepositories whose paths match the given pattern.
4561 symlink()
4563 File that is marked as a symlink.
4565 tracked()
4567 File that is under Mercurial control.
4569 unknown()
4571 File that is unknown according to hg status.
4573 unresolved()
4575 File that is marked unresolved according to hg resolve -l.
4577 Examples
4579 Some sample queries:
4580 · Show status of files that appear to be binary in the working direc‐
4582 tory:
4583 hg status -A "set:binary()"
4585 · Forget files that are in .hgignore but are already tracked:
4587 hg forget "set:hgignore() and not ignored()"
4589 · Find text files that contain a string:
4591 hg files "set:grep(magic) and not binary()"
4593 · Find C files in a non-standard encoding:
4595 hg files "set:**.c and not encoding('UTF-8')"
4597 · Revert copies of large binary files:
4599 hg revert "set:copied() and binary() and size('>1M')"
4601 · Revert files that were added to the working directory:
4603 hg revert "set:revs('wdir()', added())"
4605 · Remove files listed in foo.lst that contain the letter a or b:
4607 hg remove "set: listfile:foo.lst and (**a* or **b*)"
4609
4611 Most Mercurial commands accept various flags.
4612 Flag names
4614 Flags for each command are listed in hg help for that command. Addi‐
4615 tionally, some flags, such as --repository, are global and can be used
4616 with any command - those are seen in hg help -v, and can be specified
4617 before or after the command.
4618 Every flag has at least a long name, such as --repository. Some flags
4620 may also have a short one-letter name, such as the equivalent -R. Using
4621 the short or long name is equivalent and has the same effect.
4622 Flags that have a short name can also be bundled together - for
4624 instance, to specify both --edit (short -e) and --interactive (short
4625 -i), one could use:
4626 hg commit -ei
4628 If any of the bundled flags takes a value (i.e. is not a boolean), it
4630 must be last, followed by the value:
4631 hg commit -im 'Message'
4633 Flag types
4635 Mercurial command-line flags can be strings, numbers, booleans, or
4636 lists of strings.
4637 Specifying flag values
4639 The following syntaxes are allowed, assuming a flag 'flagname' with
4640 short name 'f':
4641 --flagname=foo
4643 --flagname foo
4644 -f foo
4645 -ffoo
4646 This syntax applies to all non-boolean flags (strings, numbers or
4648 lists).
4649 Specifying boolean flags
4651 Boolean flags do not take a value parameter. To specify a boolean, use
4652 the flag name to set it to true, or the same name prefixed with 'no-'
4653 to set it to false:
4654 hg commit --interactive
4656 hg commit --no-interactive
4657 Specifying list flags
4659 List flags take multiple values. To specify them, pass the flag multi‐
4660 ple times:
4661 hg files --include mercurial --include tests
4663 Setting flag defaults
4665 In order to set a default value for a flag in an hgrc file, it is rec‐
4666 ommended to use aliases:
4667 [alias]
4669 commit = commit --interactive
4670 For more information on hgrc files, see hg help config.
4672 Overriding flags on the command line
4674 If the same non-list flag is specified multiple times on the command
4675 line, the latest specification is used:
4676 hg commit -m "Ignored value" -m "Used value"
4678 This includes the use of aliases - e.g., if one has:
4680 [alias]
4682 committemp = commit -m "Ignored value"
4683 then the following command will override that -m:
4685 hg committemp -m "Used value"
4687 Overriding flag defaults
4689 Every flag has a default value, and you may also set your own defaults
4690 in hgrc as described above. Except for list flags, defaults can be
4691 overridden on the command line simply by specifying the flag in that
4692 location.
4693 Hidden flags
4695 Some flags are not shown in a command's help by default - specifically,
4696 those that are deemed to be experimental, deprecated or advanced. To
4697 show all flags, add the --verbose flag for the help command:
4698 hg help --verbose commit
4700
4702 Ancestor
4703 Any changeset that can be reached by an unbroken chain of parent
4704 changesets from a given changeset. More precisely, the ancestors
4705 of a changeset can be defined by two properties: a parent of a
4706 changeset is an ancestor, and a parent of an ancestor is an
4707 ancestor. See also: 'Descendant'.
4708 Bookmark
4710 Bookmarks are pointers to certain commits that move when commit‐
4711 ting. They are similar to tags in that it is possible to use
4712 bookmark names in all places where Mercurial expects a changeset
4713 ID, e.g., with hg update. Unlike tags, bookmarks move along when
4714 you make a commit.
4715 Bookmarks can be renamed, copied and deleted. Bookmarks are
4717 local, unless they are explicitly pushed or pulled between
4718 repositories. Pushing and pulling bookmarks allow you to col‐
4719 laborate with others on a branch without creating a named
4720 branch.
4721 Branch (Noun) A child changeset that has been created from a parent
4723 that is not a head. These are known as topological branches, see
4724 'Branch, topological'. If a topological branch is named, it
4725 becomes a named branch. If a topological branch is not named, it
4726 becomes an anonymous branch. See 'Branch, anonymous' and
4727 'Branch, named'.
4728 Branches may be created when changes are pulled from or pushed
4730 to a remote repository, since new heads may be created by these
4731 operations. Note that the term branch can also be used infor‐
4732 mally to describe a development process in which certain devel‐
4733 opment is done independently of other development. This is some‐
4734 times done explicitly with a named branch, but it can also be
4735 done locally, using bookmarks or clones and anonymous branches.
4736 Example: "The experimental branch."
4738 (Verb) The action of creating a child changeset which results in
4740 its parent having more than one child.
4741 Example: "I'm going to branch at X."
4743 Branch, anonymous
4745 Every time a new child changeset is created from a parent that
4746 is not a head and the name of the branch is not changed, a new
4747 anonymous branch is created.
4748 Branch, closed
4750 A named branch whose branch heads have all been closed.
4751 Branch, default
4753 The branch assigned to a changeset when no name has previously
4754 been assigned.
4755 Branch head
4757 See 'Head, branch'.
4758 Branch, inactive
4760 If a named branch has no topological heads, it is considered to
4761 be inactive. As an example, a feature branch becomes inactive
4762 when it is merged into the default branch. The hg branches com‐
4763 mand shows inactive branches by default, though they can be hid‐
4764 den with hg branches --active.
4765 NOTE: this concept is deprecated because it is too implicit.
4767 Branches should now be explicitly closed using hg commit
4768 --close-branch when they are no longer needed.
4769 Branch, named
4771 A collection of changesets which have the same branch name. By
4772 default, children of a changeset in a named branch belong to the
4773 same named branch. A child can be explicitly assigned to a dif‐
4774 ferent branch. See hg help branch, hg help branches and hg com‐
4775 mit --close-branch for more information on managing branches.
4776 Named branches can be thought of as a kind of namespace, divid‐
4778 ing the collection of changesets that comprise the repository
4779 into a collection of disjoint subsets. A named branch is not
4780 necessarily a topological branch. If a new named branch is cre‐
4781 ated from the head of another named branch, or the default
4782 branch, but no further changesets are added to that previous
4783 branch, then that previous branch will be a branch in name only.
4784 Branch tip
4786 See 'Tip, branch'.
4787 Branch, topological
4789 Every time a new child changeset is created from a parent that
4790 is not a head, a new topological branch is created. If a topo‐
4791 logical branch is named, it becomes a named branch. If a topo‐
4792 logical branch is not named, it becomes an anonymous branch of
4793 the current, possibly default, branch.
4794 Changelog
4796 A record of the changesets in the order in which they were added
4797 to the repository. This includes details such as changeset id,
4798 author, commit message, date, and list of changed files.
4799 Changeset
4801 A snapshot of the state of the repository used to record a
4802 change.
4803 Changeset, child
4805 The converse of parent changeset: if P is a parent of C, then C
4806 is a child of P. There is no limit to the number of children
4807 that a changeset may have.
4808 Changeset id
4810 A SHA-1 hash that uniquely identifies a changeset. It may be
4811 represented as either a "long" 40 hexadecimal digit string, or a
4812 "short" 12 hexadecimal digit string.
4813 Changeset, merge
4815 A changeset with two parents. This occurs when a merge is com‐
4816 mitted.
4817 Changeset, parent
4819 A revision upon which a child changeset is based. Specifically,
4820 a parent changeset of a changeset C is a changeset whose node
4821 immediately precedes C in the DAG. Changesets have at most two
4822 parents.
4823 Checkout
4825 (Noun) The working directory being updated to a specific revi‐
4826 sion. This use should probably be avoided where possible, as
4827 changeset is much more appropriate than checkout in this con‐
4828 text.
4829 Example: "I'm using checkout X."
4831 (Verb) Updating the working directory to a specific changeset.
4833 See hg help update.
4834 Example: "I'm going to check out changeset X."
4836 Child changeset
4838 See 'Changeset, child'.
4839 Close changeset
4841 See 'Head, closed branch'.
4842 Closed branch
4844 See 'Branch, closed'.
4845 Clone (Noun) An entire or partial copy of a repository. The partial
4847 clone must be in the form of a revision and its ancestors.
4848 Example: "Is your clone up to date?"
4850 (Verb) The process of creating a clone, using hg clone.
4852 Example: "I'm going to clone the repository."
4854 Closed branch head
4856 See 'Head, closed branch'.
4857 Commit (Noun) A synonym for changeset.
4859 Example: "Is the bug fixed in your recent commit?"
4861 (Verb) The act of recording changes to a repository. When files
4863 are committed in a working directory, Mercurial finds the dif‐
4864 ferences between the committed files and their parent changeset,
4865 creating a new changeset in the repository.
4866 Example: "You should commit those changes now."
4868 Cset A common abbreviation of the term changeset.
4870 DAG The repository of changesets of a distributed version control
4872 system (DVCS) can be described as a directed acyclic graph
4873 (DAG), consisting of nodes and edges, where nodes correspond to
4874 changesets and edges imply a parent -> child relation. This
4875 graph can be visualized by graphical tools such as hg log
4876 --graph. In Mercurial, the DAG is limited by the requirement for
4877 children to have at most two parents.
4878 Deprecated
4880 Feature removed from documentation, but not scheduled for
4881 removal.
4882 Default branch
4884 See 'Branch, default'.
4885 Descendant
4887 Any changeset that can be reached by a chain of child changesets
4888 from a given changeset. More precisely, the descendants of a
4889 changeset can be defined by two properties: the child of a
4890 changeset is a descendant, and the child of a descendant is a
4891 descendant. See also: 'Ancestor'.
4892 Diff (Noun) The difference between the contents and attributes of
4894 files in two changesets or a changeset and the current working
4895 directory. The difference is usually represented in a standard
4896 form called a "diff" or "patch". The "git diff" format is used
4897 when the changes include copies, renames, or changes to file
4898 attributes, none of which can be represented/handled by classic
4899 "diff" and "patch".
4900 Example: "Did you see my correction in the diff?"
4902 (Verb) Diffing two changesets is the action of creating a diff
4904 or patch.
4905 Example: "If you diff with changeset X, you will see what I
4907 mean."
4908 Directory, working
4910 The working directory represents the state of the files tracked
4911 by Mercurial, that will be recorded in the next commit. The
4912 working directory initially corresponds to the snapshot at an
4913 existing changeset, known as the parent of the working direc‐
4914 tory. See 'Parent, working directory'. The state may be modified
4915 by changes to the files introduced manually or by a merge. The
4916 repository metadata exists in the .hg directory inside the work‐
4917 ing directory.
4918 Draft Changesets in the draft phase have not been shared with publish‐
4920 ing repositories and may thus be safely changed by history-modi‐
4921 fying extensions. See hg help phases.
4922 Experimental
4924 Feature that may change or be removed at a later date.
4925 Graph See DAG and hg log --graph.
4927 Head The term 'head' may be used to refer to both a branch head or a
4929 repository head, depending on the context. See 'Head, branch'
4930 and 'Head, repository' for specific definitions.
4931 Heads are where development generally takes place and are the
4933 usual targets for update and merge operations.
4934 Head, branch
4936 A changeset with no descendants on the same named branch.
4937 Head, closed branch
4939 A changeset that marks a head as no longer interesting. The
4940 closed head is no longer listed by hg heads. A branch is consid‐
4941 ered closed when all its heads are closed and consequently is
4942 not listed by hg branches.
4943 Closed heads can be re-opened by committing new changeset as the
4945 child of the changeset that marks a head as closed.
4946 Head, repository
4948 A topological head which has not been closed.
4949 Head, topological
4951 A changeset with no children in the repository.
4952 History, immutable
4954 Once committed, changesets cannot be altered. Extensions which
4955 appear to change history actually create new changesets that
4956 replace existing ones, and then destroy the old changesets.
4957 Doing so in public repositories can result in old changesets
4958 being reintroduced to the repository.
4959 History, rewriting
4961 The changesets in a repository are immutable. However, exten‐
4962 sions to Mercurial can be used to alter the repository, usually
4963 in such a way as to preserve changeset contents.
4964 Immutable history
4966 See 'History, immutable'.
4967 Merge changeset
4969 See 'Changeset, merge'.
4970 Manifest
4972 Each changeset has a manifest, which is the list of files that
4973 are tracked by the changeset.
4974 Merge Used to bring together divergent branches of work. When you
4976 update to a changeset and then merge another changeset, you
4977 bring the history of the latter changeset into your working
4978 directory. Once conflicts are resolved (and marked), this merge
4979 may be committed as a merge changeset, bringing two branches
4980 together in the DAG.
4981 Named branch
4983 See 'Branch, named'.
4984 Null changeset
4986 The empty changeset. It is the parent state of newly-initialized
4987 repositories and repositories with no checked out revision. It
4988 is thus the parent of root changesets and the effective ancestor
4989 when merging unrelated changesets. Can be specified by the alias
4990 'null' or by the changeset ID '000000000000'.
4991 Parent See 'Changeset, parent'.
4993 Parent changeset
4995 See 'Changeset, parent'.
4996 Parent, working directory
4998 The working directory parent reflects a virtual revision which
4999 is the child of the changeset (or two changesets with an uncom‐
5000 mitted merge) shown by hg parents. This is changed with hg
5001 update. Other commands to see the working directory parent are
5002 hg summary and hg id. Can be specified by the alias ".".
5003 Patch (Noun) The product of a diff operation.
5005 Example: "I've sent you my patch."
5007 (Verb) The process of using a patch file to transform one
5009 changeset into another.
5010 Example: "You will need to patch that revision."
5012 Phase A per-changeset state tracking how the changeset has been or
5014 should be shared. See hg help phases.
5015 Public Changesets in the public phase have been shared with publishing
5017 repositories and are therefore considered immutable. See hg help
5018 phases.
5019 Pull An operation in which changesets in a remote repository which
5021 are not in the local repository are brought into the local
5022 repository. Note that this operation without special arguments
5023 only updates the repository, it does not update the files in the
5024 working directory. See hg help pull.
5025 Push An operation in which changesets in a local repository which are
5027 not in a remote repository are sent to the remote repository.
5028 Note that this operation only adds changesets which have been
5029 committed locally to the remote repository. Uncommitted changes
5030 are not sent. See hg help push.
5031 Repository
5033 The metadata describing all recorded states of a collection of
5034 files. Each recorded state is represented by a changeset. A
5035 repository is usually (but not always) found in the .hg subdi‐
5036 rectory of a working directory. Any recorded state can be recre‐
5037 ated by "updating" a working directory to a specific changeset.
5038 Repository head
5040 See 'Head, repository'.
5041 Revision
5043 A state of the repository at some point in time. Earlier revi‐
5044 sions can be updated to by using hg update. See also 'Revision
5045 number'; See also 'Changeset'.
5046 Revision number
5048 This integer uniquely identifies a changeset in a specific
5049 repository. It represents the order in which changesets were
5050 added to a repository, starting with revision number 0. Note
5051 that the revision number may be different in each clone of a
5052 repository. To identify changesets uniquely between different
5053 clones, see 'Changeset id'.
5054 Revlog History storage mechanism used by Mercurial. It is a form of
5056 delta encoding, with occasional full revision of data followed
5057 by delta of each successive revision. It includes data and an
5058 index pointing to the data.
5059 Rewriting history
5061 See 'History, rewriting'.
5062 Root A changeset that has only the null changeset as its parent. Most
5064 repositories have only a single root changeset.
5065 Secret Changesets in the secret phase may not be shared via push, pull,
5067 or clone. See hg help phases.
5068 Tag An alternative name given to a changeset. Tags can be used in
5070 all places where Mercurial expects a changeset ID, e.g., with hg
5071 update. The creation of a tag is stored in the history and will
5072 thus automatically be shared with other using push and pull.
5073 Tip The changeset with the highest revision number. It is the
5075 changeset most recently added in a repository.
5076 Tip, branch
5078 The head of a given branch with the highest revision number.
5079 When a branch name is used as a revision identifier, it refers
5080 to the branch tip. See also 'Branch, head'. Note that because
5081 revision numbers may be different in different repository
5082 clones, the branch tip may be different in different cloned
5083 repositories.
5084 Update (Noun) Another synonym of changeset.
5086 Example: "I've pushed an update."
5088 (Verb) This term is usually used to describe updating the state
5090 of the working directory to that of a specific changeset. See hg
5091 help update.
5092 Example: "You should update."
5094 Working directory
5096 See 'Directory, working'.
5097 Working directory parent
5099 See 'Parent, working directory'.
5100
5102 Synopsis
5103 The Mercurial system uses a file called .hgignore in the root directory
5104 of a repository to control its behavior when it searches for files that
5105 it is not currently tracking.
5106 Description
5108 The working directory of a Mercurial repository will often contain
5109 files that should not be tracked by Mercurial. These include backup
5110 files created by editors and build products created by compilers.
5111 These files can be ignored by listing them in a .hgignore file in the
5112 root of the working directory. The .hgignore file must be created manu‐
5113 ally. It is typically put under version control, so that the settings
5114 will propagate to other repositories with push and pull.
5115 An untracked file is ignored if its path relative to the repository
5117 root directory, or any prefix path of that path, is matched against any
5118 pattern in .hgignore.
5119 For example, say we have an untracked file, file.c, at a/b/file.c
5121 inside our repository. Mercurial will ignore file.c if any pattern in
5122 .hgignore matches a/b/file.c, a/b or a.
5123 In addition, a Mercurial configuration file can reference a set of
5125 per-user or global ignore files. See the ignore configuration key on
5126 the [ui] section of hg help config for details of how to configure
5127 these files.
5128 To control Mercurial's handling of files that it manages, many commands
5130 support the -I and -X options; see hg help <command> and hg help pat‐
5131 terns for details.
5132 Files that are already tracked are not affected by .hgignore, even if
5134 they appear in .hgignore. An untracked file X can be explicitly added
5135 with hg add X, even if X would be excluded by a pattern in .hgignore.
5136 Syntax
5138 An ignore file is a plain text file consisting of a list of patterns,
5139 with one pattern per line. Empty lines are skipped. The # character is
5140 treated as a comment character, and the \ character is treated as an
5141 escape character.
5142 Mercurial supports several pattern syntaxes. The default syntax used is
5144 Python/Perl-style regular expressions.
5145 To change the syntax used, use a line of the following form:
5147 syntax: NAME
5149 where NAME is one of the following:
5151 regexp
5153 Regular expression, Python/Perl syntax.
5155 glob
5157 Shell-style glob.
5159 rootglob
5161 A variant of glob that is rooted (see below).
5163 The chosen syntax stays in effect when parsing all patterns that fol‐
5165 low, until another syntax is selected.
5166 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
5168 the form *.c will match a file ending in .c in any directory, and a
5169 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
5170 tern, start it with ^. To get the same effect with glob-syntax, you
5171 have to use rootglob.
5172 Subdirectories can have their own .hgignore settings by adding subin‐
5174 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
5175 terns for details on subinclude: and include:.
5176 Note Patterns specified in other than .hgignore are always rooted.
5178 Please see hg help patterns for details.
5179 Example
5181 Here is an example ignore file.
5182 # use glob syntax.
5184 syntax: glob
5185 *.elc
5187 *.pyc
5188 *~
5189 # switch to regexp syntax.
5191 syntax: regexp
5192 ^\.pc/
5193
5195 Mercurial's internal web server, hgweb, can serve either a single
5196 repository, or a tree of repositories. In the second case, repository
5197 paths and global options can be defined using a dedicated configuration
5198 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
5199 This file uses the same syntax as other Mercurial configuration files
5201 but recognizes only the following sections:
5202 · web
5204 · paths
5206 · collections
5208 The web options are thoroughly described in hg help config.
5210 The paths section maps URL paths to paths of repositories in the
5212 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
5213 rial repositories can be published and only according to the configura‐
5214 tion.
5215 The left hand side is the path in the URL. Note that hgweb reserves
5217 subpaths like rev or file, try using different names for nested reposi‐
5218 tories to avoid confusing effects.
5219 The right hand side is the path in the filesystem. If the specified
5221 path ends with * or ** the filesystem will be searched recursively for
5222 repositories below that point. With * it will not recurse into the
5223 repositories it finds (except for .hg/patches). With ** it will also
5224 search inside repository working directories and possibly find sub‐
5225 repositories.
5226 In this example:
5228 [paths]
5230 /projects/a = /srv/tmprepos/a
5231 /projects/b = c:/repos/b
5232 / = /srv/repos/*
5233 /user/bob = /home/bob/repos/**
5234 · The first two entries make two repositories in different directories
5236 appear under the same directory in the web interface
5237 · The third entry will publish every Mercurial repository found in
5239 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
5240 as http://server/quux/
5241 · The fourth entry will publish both http://server/user/bob/quux/ and
5243 http://server/user/bob/quux/testsubrepo/
5244 The collections section is deprecated and has been superseded by paths.
5246 URLs and Common Arguments
5248 URLs under each repository have the form /{command}[/{arguments}] where
5249 {command} represents the name of a command or handler and {arguments}
5250 represents any number of additional URL parameters to that command.
5251 The web server has a default style associated with it. Styles map to a
5253 collection of named templates. Each template is used to render a spe‐
5254 cific piece of data, such as a changeset or diff.
5255 The style for the current request can be overwritten two ways. First,
5257 if {command} contains a hyphen (-), the text before the hyphen defines
5258 the style. For example, /atom-log will render the log command handler
5259 with the atom style. The second way to set the style is with the style
5260 query string argument. For example, /log?style=atom. The hyphenated URL
5261 parameter is preferred.
5262 Not all templates are available for all styles. Attempting to use a
5264 style that doesn't have all templates defined may result in an error
5265 rendering the page.
5266 Many commands take a {revision} URL parameter. This defines the change‐
5268 set to operate on. This is commonly specified as the short, 12 digit
5269 hexadecimal abbreviation for the full 40 character unique revision
5270 identifier. However, any value described by hg help revisions typically
5271 works.
5272 Commands and URLs
5274 The following web commands and their URLs are available:
5275 /annotate/{revision}/{path}
5277 Show changeset information for each line in a file.
5278 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
5280 string arguments have the same meaning as their [annotate] config
5281 equivalents. It uses the hgrc boolean parsing logic to interpret the
5282 value. e.g. 0 and false are false and 1 and true are true. If not
5283 defined, the server default settings are used.
5284 The fileannotate template is rendered.
5286 /archive/{revision}.{format}[/{path}]
5288 Obtain an archive of repository content.
5289 The content and type of the archive is defined by a URL path parameter.
5291 format is the file extension of the archive type to be generated. e.g.
5292 zip or tar.bz2. Not all archive types may be allowed by your server
5293 configuration.
5294 The optional path URL parameter controls content to include in the ar‐
5296 chive. If omitted, every file in the specified revision is present in
5297 the archive. If included, only the specified file or contents of the
5298 specified directory will be included in the archive.
5299 No template is used for this handler. Raw, binary content is generated.
5301 /bookmarks
5303 Show information about bookmarks.
5304 No arguments are accepted.
5306 The bookmarks template is rendered.
5308 /branches
5310 Show information about branches.
5311 All known branches are contained in the output, even closed branches.
5313 No arguments are accepted.
5315 The branches template is rendered.
5317 /changelog[/{revision}]
5319 Show information about multiple changesets.
5320 If the optional revision URL argument is absent, information about all
5322 changesets starting at tip will be rendered. If the revision argument
5323 is present, changesets will be shown starting from the specified revi‐
5324 sion.
5325 If revision is absent, the rev query string argument may be defined.
5327 This will perform a search for changesets.
5328 The argument for rev can be a single revision, a revision set, or a
5330 literal keyword to search for in changeset data (equivalent to hg log
5331 -k).
5332 The revcount query string argument defines the maximum numbers of
5334 changesets to render.
5335 For non-searches, the changelog template will be rendered.
5337 /changeset[/{revision}]
5339 Show information about a single changeset.
5340 A URL path argument is the changeset identifier to show. See hg help
5342 revisions for possible values. If not defined, the tip changeset will
5343 be shown.
5344 The changeset template is rendered. Contents of the changesettag,
5346 changesetbookmark, filenodelink, filenolink, and the many templates
5347 related to diffs may all be used to produce the output.
5348 /comparison/{revision}/{path}
5350 Show a comparison between the old and new versions of a file from
5351 changes made on a particular revision.
5352 This is similar to the diff handler. However, this form features a
5354 split or side-by-side diff rather than a unified diff.
5355 The context query string argument can be used to control the lines of
5357 context in the diff.
5358 The filecomparison template is rendered.
5360 /diff/{revision}/{path}
5362 Show how a file changed in a particular commit.
5363 The filediff template is rendered.
5365 This handler is registered under both the /diff and /filediff paths.
5367 /diff is used in modern code.
5368 /file/{revision}[/{path}]
5370 Show information about a directory or file in the repository.
5371 Info about the path given as a URL parameter will be rendered.
5373 If path is a directory, information about the entries in that directory
5375 will be rendered. This form is equivalent to the manifest handler.
5376 If path is a file, information about that file will be shown via the
5378 filerevision template.
5379 If path is not defined, information about the root directory will be
5381 rendered.
5382 /diff/{revision}/{path}
5384 Show how a file changed in a particular commit.
5385 The filediff template is rendered.
5387 This handler is registered under both the /diff and /filediff paths.
5389 /diff is used in modern code.
5390 /filelog/{revision}/{path}
5392 Show information about the history of a file in the repository.
5393 The revcount query string argument can be defined to control the maxi‐
5395 mum number of entries to show.
5396 The filelog template will be rendered.
5398 /graph[/{revision}]
5400 Show information about the graphical topology of the repository.
5401 Information rendered by this handler can be used to create visual rep‐
5403 resentations of repository topology.
5404 The revision URL parameter controls the starting changeset. If it's
5406 absent, the default is tip.
5407 The revcount query string argument can define the number of changesets
5409 to show information for.
5410 The graphtop query string argument can specify the starting changeset
5412 for producing jsdata variable that is used for rendering graph in
5413 JavaScript. By default it has the same value as revision.
5414 This handler will render the graph template.
5416 /help[/{topic}]
5418 Render help documentation.
5419 This web command is roughly equivalent to hg help. If a topic is
5421 defined, that help topic will be rendered. If not, an index of avail‐
5422 able help topics will be rendered.
5423 The help template will be rendered when requesting help for a topic.
5425 helptopics will be rendered for the index of help topics.
5426 /log[/{revision}[/{path}]]
5428 Show repository or file history.
5429 For URLs of the form /log/{revision}, a list of changesets starting at
5431 the specified changeset identifier is shown. If {revision} is not
5432 defined, the default is tip. This form is equivalent to the changelog
5433 handler.
5434 For URLs of the form /log/{revision}/{file}, the history for a specific
5436 file will be shown. This form is equivalent to the filelog handler.
5437 /manifest[/{revision}[/{path}]]
5439 Show information about a directory.
5440 If the URL path arguments are omitted, information about the root
5442 directory for the tip changeset will be shown.
5443 Because this handler can only show information for directories, it is
5445 recommended to use the file handler instead, as it can handle both
5446 directories and files.
5447 The manifest template will be rendered for this handler.
5449 /changeset[/{revision}]
5451 Show information about a single changeset.
5452 A URL path argument is the changeset identifier to show. See hg help
5454 revisions for possible values. If not defined, the tip changeset will
5455 be shown.
5456 The changeset template is rendered. Contents of the changesettag,
5458 changesetbookmark, filenodelink, filenolink, and the many templates
5459 related to diffs may all be used to produce the output.
5460 /shortlog
5462 Show basic information about a set of changesets.
5463 This accepts the same parameters as the changelog handler. The only
5465 difference is the shortlog template will be rendered instead of the
5466 changelog template.
5467 /summary
5469 Show a summary of repository state.
5470 Information about the latest changesets, bookmarks, tags, and branches
5472 is captured by this handler.
5473 The summary template is rendered.
5475 /tags
5477 Show information about tags.
5478 No arguments are accepted.
5480 The tags template is rendered.
5482
5484 To access a subtopic, use "hg help internals.{subtopic-name}"
5485 bundle2
5487 Bundle2
5488 bundles
5490 Bundles
5491 cbor CBOR
5493 censor Censor
5495 changegroups
5497 Changegroups
5498 config Config Registrar
5500 extensions
5502 Extension API
5503 requirements
5505 Repository Requirements
5506 revlogs
5508 Revision Logs
5509 wireprotocol
5511 Wire Protocol
5512 wireprotocolrpc
5514 Wire Protocol RPC
5515 wireprotocolv2
5517 Wire Protocol Version 2
5518
5520 To merge files Mercurial uses merge tools.
5521 A merge tool combines two different versions of a file into a merged
5523 file. Merge tools are given the two files and the greatest common
5524 ancestor of the two file versions, so they can determine the changes
5525 made on both branches.
5526 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
5528 out and in several extensions.
5529 Usually, the merge tool tries to automatically reconcile the files by
5531 combining all non-overlapping changes that occurred separately in the
5532 two different evolutions of the same initial base file. Furthermore,
5533 some interactive merge programs make it easier to manually resolve con‐
5534 flicting merges, either in a graphical way, or by inserting some con‐
5535 flict markers. Mercurial does not include any interactive merge pro‐
5536 grams but relies on external tools for that.
5537 Available merge tools
5539 External merge tools and their properties are configured in the
5540 merge-tools configuration section - see hgrc(5) - but they can often
5541 just be named by their executable.
5542 A merge tool is generally usable if its executable can be found on the
5544 system and if it can handle the merge. The executable is found if it is
5545 an absolute or relative executable path or the name of an application
5546 in the executable search path. The tool is assumed to be able to handle
5547 the merge if it can handle symlinks if the file is a symlink, if it can
5548 handle binary files if the file is binary, and if a GUI is available if
5549 the tool requires a GUI.
5550 There are some internal merge tools which can be used. The internal
5552 merge tools are:
5553 :dump
5555 Creates three versions of the files to merge, containing the
5557 contents of local, other and base. These files can then be used
5558 to perform a merge manually. If the file to be merged is named
5559 a.txt, these files will accordingly be named a.txt.local,
5560 a.txt.other and a.txt.base and they will be placed in the same
5561 directory as a.txt.
5562 This implies premerge. Therefore, files aren't dumped, if pre‐
5564 merge runs successfully. Use :forcedump to forcibly write files
5565 out.
5566 (actual capabilities: binary, symlink)
5568 :fail
5570 Rather than attempting to merge files that were modified on both
5572 branches, it marks them as unresolved. The resolve command must
5573 be used to resolve these conflicts.
5574 (actual capabilities: binary, symlink)
5576 :forcedump
5578 Creates three versions of the files as same as :dump, but omits
5580 premerge.
5581 (actual capabilities: binary, symlink)
5583 :local
5585 Uses the local p1() version of files as the merged version.
5587 (actual capabilities: binary, symlink)
5589 :merge
5591 Uses the internal non-interactive simple merge algorithm for
5593 merging files. It will fail if there are any conflicts and leave
5594 markers in the partially merged file. Markers will have two sec‐
5595 tions, one for each side of merge.
5596 :merge-local
5598 Like :merge, but resolve all conflicts non-interactively in
5600 favor of the local p1() changes.
5601 :merge-other
5603 Like :merge, but resolve all conflicts non-interactively in
5605 favor of the other p2() changes.
5606 :merge3
5608 Uses the internal non-interactive simple merge algorithm for
5610 merging files. It will fail if there are any conflicts and leave
5611 markers in the partially merged file. Marker will have three
5612 sections, one from each side of the merge and one for the base
5613 content.
5614 :other
5616 Uses the other p2() version of files as the merged version.
5618 (actual capabilities: binary, symlink)
5620 :prompt
5622 Asks the user which of the local p1() or the other p2() version
5624 to keep as the merged version.
5625 (actual capabilities: binary, symlink)
5627 :tagmerge
5629 Uses the internal tag merge algorithm (experimental).
5631 :union
5633 Uses the internal non-interactive simple merge algorithm for
5635 merging files. It will use both left and right sides for con‐
5636 flict regions. No markers are inserted.
5637 Internal tools are always available and do not require a GUI but will
5639 by default not handle symlinks or binary files. See next section for
5640 detail about "actual capabilities" described above.
5641 Choosing a merge tool
5643 Mercurial uses these rules when deciding which merge tool to use:
5644 1. If a tool has been specified with the --tool option to merge or
5646 resolve, it is used. If it is the name of a tool in the merge-tools
5647 configuration, its configuration is used. Otherwise the specified
5648 tool must be executable by the shell.
5649 2. If the HGMERGE environment variable is present, its value is used
5651 and must be executable by the shell.
5652 3. If the filename of the file to be merged matches any of the patterns
5654 in the merge-patterns configuration section, the first usable merge
5655 tool corresponding to a matching pattern is used.
5656 4. If ui.merge is set it will be considered next. If the value is not
5658 the name of a configured tool, the specified value is used and must
5659 be executable by the shell. Otherwise the named tool is used if it
5660 is usable.
5661 5. If any usable merge tools are present in the merge-tools configura‐
5663 tion section, the one with the highest priority is used.
5664 6. If a program named hgmerge can be found on the system, it is used -
5666 but it will by default not be used for symlinks and binary files.
5667 7. If the file to be merged is not binary and is not a symlink, then
5669 internal :merge is used.
5670 8. Otherwise, :prompt is used.
5672 For historical reason, Mercurial treats merge tools as below while
5674 examining rules above.
5675 ┌───────────┬────────────────┬────────┬─────────┐
5677 │step │ specified via │ binary │ symlink │
5678 ├───────────┼────────────────┼────────┼─────────┤
5679 │ │ --tool │ o/o │ o/o │
5680 │ 1. │ │ │ │
5681 ├───────────┼────────────────┼────────┼─────────┤
5682 │ │ HGMERGE │ o/o │ o/o │
5683 │ 2. │ │ │ │
5684 ├───────────┼────────────────┼────────┼─────────┤
5685 │ │ merge-patterns │ o/o(*) │ x/?(*) │
5686 │ 3. │ │ │ │
5687 ├───────────┼────────────────┼────────┼─────────┤
5688 │ │ ui.merge │ x/?(*) │ x/?(*) │
5689 │ 4. │ │ │ │
5690 └───────────┴────────────────┴────────┴─────────┘
5691 Each capability column indicates Mercurial behavior for internal/exter‐
5693 nal merge tools at examining each rule.
5694 · "o": "assume that a tool has capability"
5696 · "x": "assume that a tool does not have capability"
5698 · "?": "check actual capability of a tool"
5700 If merge.strict-capability-check configuration is true, Mercurial
5702 checks capabilities of merge tools strictly in (*) cases above (= each
5703 capability column becomes "?/?"). It is false by default for backward
5704 compatibility.
5705 Note After selecting a merge program, Mercurial will by default
5707 attempt to merge the files using a simple merge algorithm first.
5708 Only if it doesn't succeed because of conflicting changes will
5709 Mercurial actually execute the merge program. Whether to use the
5710 simple merge algorithm first can be controlled by the premerge
5711 setting of the merge tool. Premerge is enabled by default unless
5712 the file is binary or a symlink.
5713 See the merge-tools and ui sections of hgrc(5) for details on the con‐
5715 figuration of merge tools.
5716
5718 Some Mercurial commands can produce a lot of output, and Mercurial will
5719 attempt to use a pager to make those commands more pleasant.
5720 To set the pager that should be used, set the application variable:
5722 [pager]
5724 pager = less -FRX
5725 If no pager is set in the user or repository configuration, Mercurial
5727 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
5728 from the default or system configuration is used. If none of these are
5729 set, a default pager will be used, typically less on Unix and more on
5730 Windows.
5731 On Windows, more is not color aware, so using it effectively disables
5733 color. MSYS and Cygwin shells provide less as a pager, which can be
5734 configured to support ANSI color codes. See hg help con‐
5735 fig.color.pagermode to configure the color mode when invoking a pager.
5736 You can disable the pager for certain commands by adding them to the
5738 pager.ignore list:
5739 [pager]
5741 ignore = version, help, update
5742 To ignore global commands like hg version or hg help, you have to spec‐
5744 ify them in your user configuration file.
5745 To control whether the pager is used at all for an individual command,
5747 you can use --pager=<value>:
5748 · use as needed: auto.
5750 · require the pager: yes or on.
5752 · suppress the pager: no or off (any unrecognized value will also
5754 work).
5755 To globally turn off all attempts to use a pager, set:
5757 [ui]
5759 paginate = never
5760 which will prevent the pager from running.
5762
5764 Mercurial accepts several notations for identifying one or more files
5765 at a time.
5766 By default, Mercurial treats filenames as shell-style extended glob
5768 patterns.
5769 Alternate pattern notations must be specified explicitly.
5771 Note Patterns specified in .hgignore are not rooted. Please see hg
5773 help hgignore for details.
5774 To use a plain path name without any pattern matching, start it with
5776 path:. These path names must completely match starting at the current
5777 repository root, and when the path points to a directory, it is matched
5778 recursively. To match all files in a directory non-recursively (not
5779 including any files in subdirectories), rootfilesin: can be used, spec‐
5780 ifying an absolute path (relative to the repository root).
5781 To use an extended glob, start a name with glob:. Globs are rooted at
5783 the current directory; a glob such as *.c will only match files in the
5784 current directory ending with .c. rootglob: can be used instead of
5785 glob: for a glob that is rooted at the root of the repository.
5786 The supported glob syntax extensions are ** to match any string across
5788 path separators and {a,b} to mean "a or b".
5789 To use a Perl/Python regular expression, start a name with re:. Regexp
5791 pattern matching is anchored at the root of the repository.
5792 To read name patterns from a file, use listfile: or listfile0:. The
5794 latter expects null delimited patterns while the former expects line
5795 feeds. Each string read from the file is itself treated as a file pat‐
5796 tern.
5797 To read a set of patterns from a file, use include: or subinclude:.
5799 include: will use all the patterns from the given file and treat them
5800 as if they had been passed in manually. subinclude: will only apply
5801 the patterns against files that are under the subinclude file's direc‐
5802 tory. See hg help hgignore for details on the format of these files.
5803 All patterns, except for glob: specified in command line (not for -I or
5805 -X options), can match also against directories: files under matched
5806 directories are treated as matched. For -I and -X options, glob: will
5807 match directories recursively.
5808 Plain examples:
5810 path:foo/bar a name bar in a directory named foo in the root
5812 of the repository
5813 path:path:name a file or directory named "path:name"
5814 rootfilesin:foo/bar the files in a directory called foo/bar, but not any files
5815 in its subdirectories and not a file bar in directory foo
5816 Glob examples:
5818 glob:*.c any name ending in ".c" in the current directory
5820 *.c any name ending in ".c" in the current directory
5821 **.c any name ending in ".c" in any subdirectory of the
5822 current directory including itself.
5823 foo/* any file in directory foo
5824 foo/** any file in directory foo plus all its subdirectories,
5825 recursively
5826 foo/*.c any name ending in ".c" in the directory foo
5827 foo/**.c any name ending in ".c" in any subdirectory of foo
5828 including itself.
5829 rootglob:*.c any name ending in ".c" in the root of the repository
5830 Regexp examples:
5832 re:.*\.c$ any name ending in ".c", anywhere in the repository
5834 File examples:
5836 listfile:list.txt read list from list.txt with one file pattern per line
5838 listfile0:list.txt read list from list.txt with null byte delimiters
5839 See also hg help filesets.
5841 Include examples:
5843 include:path/to/mypatternfile reads patterns to be applied to all paths
5845 subinclude:path/to/subignorefile reads patterns specifically for paths in the
5846 subdirectory
5847
5849 What are phases?
5850 Phases are a system for tracking which changesets have been or should
5851 be shared. This helps prevent common mistakes when modifying history
5852 (for instance, with the mq or rebase extensions).
5853 Each changeset in a repository is in one of the following phases:
5855 · public : changeset is visible on a public server
5857 · draft : changeset is not yet published
5859 · secret : changeset should not be pushed, pulled, or cloned
5861 These phases are ordered (public < draft < secret) and no changeset can
5863 be in a lower phase than its ancestors. For instance, if a changeset is
5864 public, all its ancestors are also public. Lastly, changeset phases
5865 should only be changed towards the public phase.
5866 How are phases managed?
5868 For the most part, phases should work transparently. By default, a
5869 changeset is created in the draft phase and is moved into the public
5870 phase when it is pushed to another repository.
5871 Once changesets become public, extensions like mq and rebase will
5873 refuse to operate on them to prevent creating duplicate changesets.
5874 Phases can also be manually manipulated with the hg phase command if
5875 needed. See hg help -v phase for examples.
5876 To make your commits secret by default, put this in your configuration
5878 file:
5879 [phases]
5881 new-commit = secret
5882 Phases and servers
5884 Normally, all servers are publishing by default. This means:
5885 - all draft changesets that are pulled or cloned appear in phase
5887 public on the client
5888 - all draft changesets that are pushed appear as public on both
5890 client and server
5891 - secret changesets are neither pushed, pulled, or cloned
5893 Note Pulling a draft changeset from a publishing server does not mark
5895 it as public on the server side due to the read-only nature of
5896 pull.
5897 Sometimes it may be desirable to push and pull changesets in the draft
5899 phase to share unfinished work. This can be done by setting a reposi‐
5900 tory to disable publishing in its configuration file:
5901 [phases]
5903 publish = False
5904 See hg help config for more information on configuration files.
5906 Note Servers running older versions of Mercurial are treated as pub‐
5908 lishing.
5909 Note Changesets in secret phase are not exchanged with the server.
5911 This applies to their content: file names, file contents, and
5912 changeset metadata. For technical reasons, the identifier (e.g.
5913 d825e4025e39) of the secret changeset may be communicated to the
5914 server.
5915 Examples
5917 · list changesets in draft or secret phase:
5918 hg log -r "not public()"
5920 · change all secret changesets to draft:
5922 hg phase --draft "secret()"
5924 · forcibly move the current changeset and descendants from public to
5926 draft:
5927 hg phase --force --draft .
5929 · show a list of changeset revisions and each corresponding phase:
5931 hg log --template "{rev} {phase}\n"
5933 · resynchronize draft changesets relative to a remote repository:
5935 hg phase -fd "outgoing(URL)"
5937 See hg help phase for more information on manually manipulating phases.
5939
5941 Mercurial supports several ways to specify revisions.
5942 Specifying single revisions
5944 A plain integer is treated as a revision number. Negative integers are
5945 treated as sequential offsets from the tip, with -1 denoting the tip,
5946 -2 denoting the revision prior to the tip, and so forth.
5947 A 40-digit hexadecimal string is treated as a unique revision identi‐
5949 fier. A hexadecimal string less than 40 characters long is treated as
5950 a unique revision identifier and is referred to as a short-form identi‐
5951 fier. A short-form identifier is only valid if it is the prefix of
5952 exactly one full-length identifier.
5953 Any other string is treated as a bookmark, tag, or branch name. A book‐
5955 mark is a movable pointer to a revision. A tag is a permanent name
5956 associated with a revision. A branch name denotes the tipmost open
5957 branch head of that branch - or if they are all closed, the tipmost
5958 closed head of the branch. Bookmark, tag, and branch names must not
5959 contain the ":" character.
5960 The reserved name "tip" always identifies the most recent revision.
5962 The reserved name "null" indicates the null revision. This is the revi‐
5964 sion of an empty repository, and the parent of revision 0.
5965 The reserved name "." indicates the working directory parent. If no
5967 working directory is checked out, it is equivalent to null. If an
5968 uncommitted merge is in progress, "." is the revision of the first par‐
5969 ent.
5970 Finally, commands that expect a single revision (like hg update) also
5972 accept revsets (see below for details). When given a revset, they use
5973 the last revision of the revset. A few commands accept two single revi‐
5974 sions (like hg diff). When given a revset, they use the first and the
5975 last revisions of the revset.
5976 Specifying multiple revisions
5978 Mercurial supports a functional language for selecting a set of revi‐
5979 sions. Expressions in this language are called revsets.
5980 The language supports a number of predicates which are joined by infix
5982 operators. Parenthesis can be used for grouping.
5983 Identifiers such as branch names may need quoting with single or double
5985 quotes if they contain characters like - or if they match one of the
5986 predefined predicates.
5987 Special characters can be used in quoted identifiers by escaping them,
5989 e.g., \n is interpreted as a newline. To prevent them from being inter‐
5990 preted, strings can be prefixed with r, e.g. r'...'.
5991 Operators
5993 There is a single prefix operator:
5994 not x
5996 Changesets not in x. Short form is ! x.
5998 These are the supported infix operators:
6000 x::y
6002 A DAG range, meaning all changesets that are descendants of x
6004 and ancestors of y, including x and y themselves. If the first
6005 endpoint is left out, this is equivalent to ancestors(y), if the
6006 second is left out it is equivalent to descendants(x).
6007 An alternative syntax is x..y.
6009 x:y
6011 All changesets with revision numbers between x and y, both
6013 inclusive. Either endpoint can be left out, they default to 0
6014 and tip.
6015 x and y
6017 The intersection of changesets in x and y. Short form is x & y.
6019 x or y
6021 The union of changesets in x and y. There are two alternative
6023 short forms: x | y and x + y.
6024 x - y
6026 Changesets in x but not in y.
6028 x % y
6030 Changesets that are ancestors of x but not ancestors of y (i.e.
6032 ::x - ::y). This is shorthand notation for only(x, y) (see
6033 below). The second argument is optional and, if left out, is
6034 equivalent to only(x).
6035 x^n
6037 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
6039 1, the first parent of each changeset in x; for n == 2, the sec‐
6040 ond parent of changeset in x.
6041 x~n
6043 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
6045 the nth unambiguous descendent of x.
6046 x ## y
6048 Concatenate strings and identifiers into one string.
6050 All other prefix, infix and postfix operators have lower prior‐
6052 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
6053 a2)~2.
6054 For example:
6056 [revsetalias]
6058 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
6059 issue(1234) is equivalent to grep(r'\bissue[
6061 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
6062 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
6063 There is a single postfix operator:
6065 x^
6067 Equivalent to x^1, the first parent of each changeset in x.
6069 Patterns
6071 Where noted, predicates that perform string matching can accept a pat‐
6072 tern string. The pattern may be either a literal, or a regular expres‐
6073 sion. If the pattern starts with re:, the remainder of the pattern is
6074 treated as a regular expression. Otherwise, it is treated as a literal.
6075 To match a pattern that actually starts with re:, use the prefix lit‐
6076 eral:.
6077 Matching is case-sensitive, unless otherwise noted. To perform a case-
6079 insensitive match on a case-sensitive predicate, use a regular expres‐
6080 sion, prefixed with (?i).
6081 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
6083 "Release", etc.
6084 Predicates
6086 The following predicates are supported:
6087 adds(pattern)
6089 Changesets that add a file matching pattern.
6091 The pattern without explicit kind like glob: is expected to be
6093 relative to the current directory and match against a file or a
6094 directory.
6095 all()
6097 All changesets, the same as 0:tip.
6099 ancestor(*changeset)
6101 A greatest common ancestor of the changesets.
6103 Accepts 0 or more changesets. Will return empty list when
6105 passed no args. Greatest common ancestor of a single changeset
6106 is that changeset.
6107 ancestors(set[, depth])
6109 Changesets that are ancestors of changesets in set, including
6111 the given changesets themselves.
6112 If depth is specified, the result only includes changesets up to
6114 the specified generation.
6115 author(string)
6117 Alias for user(string).
6119 bisect(string)
6121 Changesets marked in the specified bisect status:
6123 · good, bad, skip: csets explicitly marked as good/bad/skip
6125 · goods, bads : csets topologically good/bad
6127 · range : csets taking part in the bisection
6129 · pruned : csets that are goods, bads or skipped
6131 · untested : csets whose fate is yet unknown
6133 · ignored : csets ignored due to DAG topology
6135 · current : the cset currently being bisected
6137 bookmark([name])
6139 The named bookmark or all bookmarks.
6141 Pattern matching is supported for name. See hg help revi‐
6143 sions.patterns.
6144 branch(string or set)
6146 All changesets belonging to the given branch or the branches of
6148 the given changesets.
6149 Pattern matching is supported for string. See hg help revi‐
6151 sions.patterns.
6152 branchpoint()
6154 Changesets with more than one child.
6156 bundle()
6158 Changesets in the bundle.
6160 Bundle must be specified by the -R option.
6162 children(set)
6164 Child changesets of changesets in set.
6166 closed()
6168 Changeset is closed.
6170 commonancestors(set)
6172 Changesets that are ancestors of every changeset in set.
6174 contains(pattern)
6176 The revision's manifest contains a file matching pattern (but
6178 might not modify it). See hg help patterns for information about
6179 file patterns.
6180 The pattern without explicit kind like glob: is expected to be
6182 relative to the current directory and match against a file
6183 exactly for efficiency.
6184 converted([id])
6186 Changesets converted from the given identifier in the old repos‐
6188 itory if present, or all converted changesets if no identifier
6189 is specified.
6190 date(interval)
6192 Changesets within the interval, see hg help dates.
6194 desc(string)
6196 Search commit message for string. The match is case-insensitive.
6198 Pattern matching is supported for string. See hg help revi‐
6200 sions.patterns.
6201 descendants(set[, depth])
6203 Changesets which are descendants of changesets in set, including
6205 the given changesets themselves.
6206 If depth is specified, the result only includes changesets up to
6208 the specified generation.
6209 destination([set])
6211 Changesets that were created by a graft, transplant or rebase
6213 operation, with the given revisions specified as the source.
6214 Omitting the optional set is the same as passing all().
6215 draft()
6217 Changeset in draft phase.
6219 extinct()
6221 Obsolete changesets with obsolete descendants only.
6223 extra(label, [value])
6225 Changesets with the given label in the extra metadata, with the
6227 given optional value.
6228 Pattern matching is supported for value. See hg help revi‐
6230 sions.patterns.
6231 file(pattern)
6233 Changesets affecting files matched by pattern.
6235 For a faster but less accurate result, consider using filelog()
6237 instead.
6238 This predicate uses glob: as the default kind of pattern.
6240 filelog(pattern)
6242 Changesets connected to the specified filelog.
6244 For performance reasons, visits only revisions mentioned in the
6246 file-level filelog, rather than filtering through all changesets
6247 (much faster, but doesn't include deletes or duplicate changes).
6248 For a slower, more accurate result, use file().
6249 The pattern without explicit kind like glob: is expected to be
6251 relative to the current directory and match against a file
6252 exactly for efficiency.
6253 If some linkrev points to revisions filtered by the current
6255 repoview, we'll work around it to return a non-filtered value.
6256 first(set, [n])
6258 An alias for limit().
6260 follow([file[, startrev]])
6262 An alias for ::. (ancestors of the working directory's first
6264 parent). If file pattern is specified, the histories of files
6265 matching given pattern in the revision given by startrev are
6266 followed, including copies.
6267 followlines(file, fromline:toline[, startrev=., descend=False])
6269 Changesets modifying file in line range ('fromline', 'toline').
6271 Line range corresponds to 'file' content at 'startrev' and
6273 should hence be consistent with file size. If startrev is not
6274 specified, working directory's parent is used.
6275 By default, ancestors of 'startrev' are returned. If 'descend'
6277 is True, descendants of 'startrev' are returned though renames
6278 are (currently) not followed in this direction.
6279 grep(regex)
6281 Like keyword(string) but accepts a regex. Use grep(r'...') to
6283 ensure special escape characters are handled correctly. Unlike
6284 keyword(string), the match is case-sensitive.
6285 head()
6287 Changeset is a named branch head.
6289 heads(set)
6291 Members of set with no children in set.
6293 hidden()
6295 Hidden changesets.
6297 id(string)
6299 Revision non-ambiguously specified by the given hex string pre‐
6301 fix.
6302 keyword(string)
6304 Search commit message, user name, and names of changed files for
6306 string. The match is case-insensitive.
6307 For a regular expression or case sensitive search of these
6309 fields, use grep(regex).
6310 last(set, [n])
6312 Last n members of set, defaulting to 1.
6314 limit(set[, n[, offset]])
6316 First n members of set, defaulting to 1, starting from offset.
6318 matching(revision [, field])
6320 Changesets in which a given set of fields match the set of
6322 fields in the selected revision or set.
6323 To match more than one field pass the list of fields to match
6325 separated by spaces (e.g. author description).
6326 Valid fields are most regular revision fields and some special
6328 fields.
6329 Regular revision fields are description, author, branch, date,
6331 files, phase, parents, substate, user and diff. Note that
6332 author and user are synonyms. diff refers to the contents of the
6333 revision. Two revisions matching their diff will also match
6334 their files.
6335 Special fields are summary and metadata: summary matches the
6337 first line of the description. metadata is equivalent to match‐
6338 ing description user date (i.e. it matches the main metadata
6339 fields).
6340 metadata is the default field which is used when no fields are
6342 specified. You can match more than one field at a time.
6343 max(set)
6345 Changeset with highest revision number in set.
6347 merge()
6349 Changeset is a merge changeset.
6351 min(set)
6353 Changeset with lowest revision number in set.
6355 modifies(pattern)
6357 Changesets modifying files matched by pattern.
6359 The pattern without explicit kind like glob: is expected to be
6361 relative to the current directory and match against a file or a
6362 directory.
6363 named(namespace)
6365 The changesets in a given namespace.
6367 Pattern matching is supported for namespace. See hg help revi‐
6369 sions.patterns.
6370 none()
6372 No changesets.
6374 obsolete()
6376 Mutable changeset with a newer version.
6378 only(set, [set])
6380 Changesets that are ancestors of the first set that are not
6382 ancestors of any other head in the repo. If a second set is
6383 specified, the result is ancestors of the first set that are not
6384 ancestors of the second set (i.e. ::<set1> - ::<set2>).
6385 origin([set])
6387 Changesets that were specified as a source for the grafts,
6389 transplants or rebases that created the given revisions. Omit‐
6390 ting the optional set is the same as passing all(). If a
6391 changeset created by these operations is itself specified as a
6392 source for one of these operations, only the source changeset
6393 for the first operation is selected.
6394 outgoing([path])
6396 Changesets not found in the specified destination repository, or
6398 the default push location.
6399 p1([set])
6401 First parent of changesets in set, or the working directory.
6403 p2([set])
6405 Second parent of changesets in set, or the working directory.
6407 parents([set])
6409 The set of all parents for all changesets in set, or the working
6411 directory.
6412 present(set)
6414 An empty set, if any revision in set isn't found; otherwise, all
6416 revisions in set.
6417 If any of specified revisions is not present in the local repos‐
6419 itory, the query is normally aborted. But this predicate allows
6420 the query to continue even in such cases.
6421 public()
6423 Changeset in public phase.
6425 remote([id [,path]])
6427 Local revision that corresponds to the given identifier in a
6429 remote repository, if present. Here, the '.' identifier is a
6430 synonym for the current local branch.
6431 removes(pattern)
6433 Changesets which remove files matching pattern.
6435 The pattern without explicit kind like glob: is expected to be
6437 relative to the current directory and match against a file or a
6438 directory.
6439 rev(number)
6441 Revision with the given numeric identifier.
6443 reverse(set)
6445 Reverse order of set.
6447 revset(set)
6449 Strictly interpret the content as a revset.
6451 The content of this special predicate will be strictly inter‐
6453 preted as a revset. For example, revset(id(0)) will be inter‐
6454 preted as "id(0)" without possible ambiguity with a "id(0)"
6455 bookmark or tag.
6456 roots(set)
6458 Changesets in set with no parent changeset in set.
6460 secret()
6462 Changeset in secret phase.
6464 sort(set[, [-]key... [, ...]])
6466 Sort set by keys. The default sort order is ascending, specify a
6468 key as -key to sort in descending order.
6469 The keys can be:
6471 · rev for the revision number,
6473 · branch for the branch name,
6475 · desc for the commit message (description),
6477 · user for user name (author can be used as an alias),
6479 · date for the commit date
6481 · topo for a reverse topographical sort
6483 The topo sort order cannot be combined with other sort keys.
6485 This sort takes one optional argument, topo.firstbranch, which
6486 takes a revset that specifies what topographical branches to
6487 prioritize in the sort.
6488 subrepo([pattern])
6490 Changesets that add, modify or remove the given subrepo. If no
6492 subrepo pattern is named, any subrepo changes are returned.
6493 successors(set)
6495 All successors for set, including the given set themselves
6497 tag([name])
6499 The specified tag by name, or all tagged revisions if no name is
6501 given.
6502 Pattern matching is supported for name. See hg help revi‐
6504 sions.patterns.
6505 user(string)
6507 User name contains string. The match is case-insensitive.
6509 Pattern matching is supported for string. See hg help revi‐
6511 sions.patterns.
6512 Aliases
6514 New predicates (known as "aliases") can be defined, using any combina‐
6515 tion of existing predicates or other aliases. An alias definition looks
6516 like:
6517 <alias> = <definition>
6519 in the revsetalias section of a Mercurial configuration file. Arguments
6521 of the form a1, a2, etc. are substituted from the alias into the defi‐
6522 nition.
6523 For example,
6525 [revsetalias]
6527 h = heads()
6528 d(s) = sort(s, date)
6529 rs(s, k) = reverse(sort(s, k))
6530 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
6532 equivalent to reverse(sort(0:tip, author)).
6533 Equivalents
6535 Command line equivalents for hg log:
6536 -f -> ::.
6538 -d x -> date(x)
6539 -k x -> keyword(x)
6540 -m -> merge()
6541 -u x -> user(x)
6542 -b x -> branch(x)
6543 -P x -> !::x
6544 -l x -> limit(expr, x)
6545 Examples
6547 Some sample queries:
6548 · Changesets on the default branch:
6550 hg log -r "branch(default)"
6552 · Changesets on the default branch since tag 1.5 (excluding merges):
6554 hg log -r "branch(default) and 1.5:: and not merge()"
6556 · Open branch heads:
6558 hg log -r "head() and not closed()"
6560 · Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
6562 hgext/*:
6563 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
6565 · Changesets committed in May 2008, sorted by user:
6567 hg log -r "sort(date('May 2008'), user)"
6569 · Changesets mentioning "bug" or "issue" that are not in a tagged
6571 release:
6572 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
6574 · Update to the commit that bookmark @ is pointing to, without activat‐
6576 ing the bookmark (this works because the last revision of the revset
6577 is used):
6578 hg update :@
6580 · Show diff between tags 1.3 and 1.5 (this works because the first and
6582 the last revisions of the revset are used):
6583 hg diff -r 1.3::1.5
6585
6587 It is common for machines (as opposed to humans) to consume Mercurial.
6588 This help topic describes some of the considerations for interfacing
6589 machines with Mercurial.
6590 Choosing an Interface
6592 Machines have a choice of several methods to interface with Mercurial.
6593 These include:
6594 · Executing the hg process
6596 · Querying a HTTP server
6598 · Calling out to a command server
6600 Executing hg processes is very similar to how humans interact with Mer‐
6602 curial in the shell. It should already be familiar to you.
6603 hg serve can be used to start a server. By default, this will start a
6605 "hgweb" HTTP server. This HTTP server has support for machine-readable
6606 output, such as JSON. For more, see hg help hgweb.
6607 hg serve can also start a "command server." Clients can connect to this
6609 server and issue Mercurial commands over a special protocol. For more
6610 details on the command server, including links to client libraries, see
6611 https://www.mercurial-scm.org/wiki/CommandServer.
6612 hg serve based interfaces (the hgweb and command servers) have the
6614 advantage over simple hg process invocations in that they are likely
6615 more efficient. This is because there is significant overhead to spawn
6616 new Python processes.
6617 Tip If you need to invoke several hg processes in short order and/or
6619 performance is important to you, use of a server-based interface
6620 is highly recommended.
6621 Environment Variables
6623 As documented in hg help environment, various environment variables
6624 influence the operation of Mercurial. The following are particularly
6625 relevant for machines consuming Mercurial:
6626 HGPLAIN
6628 If not set, Mercurial's output could be influenced by configura‐
6629 tion settings that impact its encoding, verbose mode, localiza‐
6630 tion, etc.
6631 It is highly recommended for machines to set this variable when
6633 invoking hg processes.
6634 HGENCODING
6636 If not set, the locale used by Mercurial will be detected from
6637 the environment. If the determined locale does not support dis‐
6638 play of certain characters, Mercurial may render these character
6639 sequences incorrectly (often by using "?" as a placeholder for
6640 invalid characters in the current locale).
6641 Explicitly setting this environment variable is a good practice
6643 to guarantee consistent results. "utf-8" is a good choice on
6644 UNIX-like environments.
6645 HGRCPATH
6647 If not set, Mercurial will inherit config options from config
6648 files using the process described in hg help config. This
6649 includes inheriting user or system-wide config files.
6650 When utmost control over the Mercurial configuration is desired,
6652 the value of HGRCPATH can be set to an explicit file with known
6653 good configs. In rare cases, the value can be set to an empty
6654 file or the null device (often /dev/null) to bypass loading of
6655 any user or system config files. Note that these approaches can
6656 have unintended consequences, as the user and system config
6657 files often define things like the username and extensions that
6658 may be required to interface with a repository.
6659 Command-line Flags
6661 Mercurial's default command-line parser is designed for humans, and is
6662 not robust against malicious input. For instance, you can start a
6663 debugger by passing --debugger as an option value:
6664 $ REV=--debugger sh -c 'hg log -r "$REV"'
6666 This happens because several command-line flags need to be scanned
6668 without using a concrete command table, which may be modified while
6669 loading repository settings and extensions.
6670 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
6672 setting HGPLAIN=+strictflags. When this feature is enabled, all early
6673 options (e.g. -R/--repository, --cwd, --config) must be specified first
6674 amongst the other global options, and cannot be injected to an arbi‐
6675 trary location:
6676 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
6678 In earlier Mercurial versions where +strictflags isn't available, you
6680 can mitigate the issue by concatenating an option value with its flag:
6681 $ hg log -r"$REV" --keyword="$KEYWORD"
6683 Consuming Command Output
6685 It is common for machines to need to parse the output of Mercurial com‐
6686 mands for relevant data. This section describes the various techniques
6687 for doing so.
6688 Parsing Raw Command Output
6690 Likely the simplest and most effective solution for consuming command
6691 output is to simply invoke hg commands as you would as a user and parse
6692 their output.
6693 The output of many commands can easily be parsed with tools like grep,
6695 sed, and awk.
6696 A potential downside with parsing command output is that the output of
6698 commands can change when Mercurial is upgraded. While Mercurial does
6699 generally strive for strong backwards compatibility, command output
6700 does occasionally change. Having tests for your automated interactions
6701 with hg commands is generally recommended, but is even more important
6702 when raw command output parsing is involved.
6703 Using Templates to Control Output
6705 Many hg commands support templatized output via the -T/--template argu‐
6706 ment. For more, see hg help templates.
6707 Templates are useful for explicitly controlling output so that you get
6709 exactly the data you want formatted how you want it. For example, log
6710 -T {node}\n can be used to print a newline delimited list of changeset
6711 nodes instead of a human-tailored output containing authors, dates,
6712 descriptions, etc.
6713 Tip If parsing raw command output is too complicated, consider using
6715 templates to make your life easier.
6716 The -T/--template argument allows specifying pre-defined styles. Mer‐
6718 curial ships with the machine-readable styles json and xml, which pro‐
6719 vide JSON and XML output, respectively. These are useful for producing
6720 output that is machine readable as-is.
6721 Important
6723 The json and xml styles are considered experimental. While they
6724 may be attractive to use for easily obtaining machine-readable
6725 output, their behavior may change in subsequent versions.
6726 These styles may also exhibit unexpected results when dealing
6728 with certain encodings. Mercurial treats things like filenames
6729 as a series of bytes and normalizing certain byte sequences to
6730 JSON or XML with certain encoding settings can lead to sur‐
6731 prises.
6732 Command Server Output
6734 If using the command server to interact with Mercurial, you are likely
6735 using an existing library/API that abstracts implementation details of
6736 the command server. If so, this interface layer may perform parsing for
6737 you, saving you the work of implementing it yourself.
6738 Output Verbosity
6740 Commands often have varying output verbosity, even when machine read‐
6741 able styles are being used (e.g. -T json). Adding -v/--verbose and
6742 --debug to the command's arguments can increase the amount of data
6743 exposed by Mercurial.
6744 An alternate way to get the data you need is by explicitly specifying a
6746 template.
6747 Other Topics
6749 revsets
6750 Revisions sets is a functional query language for selecting a
6751 set of revisions. Think of it as SQL for Mercurial repositories.
6752 Revsets are useful for querying repositories for specific data.
6753 See hg help revsets for more.
6755 share extension
6757 The share extension provides functionality for sharing reposi‐
6758 tory data across several working copies. It can even automati‐
6759 cally "pool" storage for logically related repositories when
6760 cloning.
6761 Configuring the share extension can lead to significant resource
6763 utilization reduction, particularly around disk space and the
6764 network. This is especially true for continuous integration (CI)
6765 environments.
6766 See hg help -e share for more.
6768
6770 Subrepositories let you nest external repositories or projects into a
6771 parent Mercurial repository, and make commands operate on them as a
6772 group.
6773 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
6775 tories.
6776 Subrepositories are made of three components:
6778 1. Nested repository checkouts. They can appear anywhere in the parent
6780 working directory.
6781 2. Nested repository references. They are defined in .hgsub, which
6783 should be placed in the root of working directory, and tell where
6784 the subrepository checkouts come from. Mercurial subrepositories are
6785 referenced like:
6786 path/to/nested = https://example.com/nested/repo/path
6788 Git and Subversion subrepos are also supported:
6790 path/to/nested = [git]git://example.com/nested/repo/path
6792 path/to/nested = [svn]https://example.com/nested/trunk/path
6793 where path/to/nested is the checkout location relatively to the par‐
6795 ent Mercurial root, and https://example.com/nested/repo/path is the
6796 source repository path. The source can also reference a filesystem
6797 path.
6798 Note that .hgsub does not exist by default in Mercurial reposito‐
6800 ries, you have to create and add it to the parent repository before
6801 using subrepositories.
6802 3. Nested repository states. They are defined in .hgsubstate, which is
6804 placed in the root of working directory, and capture whatever infor‐
6805 mation is required to restore the subrepositories to the state they
6806 were committed in a parent repository changeset. Mercurial automati‐
6807 cally record the nested repositories states when committing in the
6808 parent repository.
6809 Note
6811 The .hgsubstate file should not be edited manually.
6812 Adding a Subrepository
6814 If .hgsub does not exist, create it and add it to the parent reposi‐
6815 tory. Clone or checkout the external projects where you want it to live
6816 in the parent repository. Edit .hgsub and add the subrepository entry
6817 as described above. At this point, the subrepository is tracked and the
6818 next commit will record its state in .hgsubstate and bind it to the
6819 committed changeset.
6820 Synchronizing a Subrepository
6822 Subrepos do not automatically track the latest changeset of their
6823 sources. Instead, they are updated to the changeset that corresponds
6824 with the changeset checked out in the top-level changeset. This is so
6825 developers always get a consistent set of compatible code and libraries
6826 when they update.
6827 Thus, updating subrepos is a manual process. Simply check out target
6829 subrepo at the desired revision, test in the top-level repo, then com‐
6830 mit in the parent repository to record the new combination.
6831 Deleting a Subrepository
6833 To remove a subrepository from the parent repository, delete its refer‐
6834 ence from .hgsub, then remove its files.
6835 Interaction with Mercurial Commands
6837 add add does not recurse in subrepos unless -S/--subrepos is speci‐
6838 fied. However, if you specify the full path of a file in a sub‐
6839 repo, it will be added even without -S/--subrepos specified.
6840 Subversion subrepositories are currently silently ignored.
6841 addremove
6843 addremove does not recurse into subrepos unless -S/--subrepos is
6844 specified. However, if you specify the full path of a directory
6845 in a subrepo, addremove will be performed on it even without
6846 -S/--subrepos being specified. Git and Subversion subreposito‐
6847 ries will print a warning and continue.
6848 archive
6850 archive does not recurse in subrepositories unless -S/--subrepos
6851 is specified.
6852 cat Git subrepositories only support exact file matches. Subversion
6854 subrepositories are currently ignored.
6855 commit commit creates a consistent snapshot of the state of the entire
6857 project and its subrepositories. If any subrepositories have
6858 been modified, Mercurial will abort. Mercurial can be made to
6859 instead commit all modified subrepositories by specifying
6860 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
6861 ration file (see hg help config). After there are no longer any
6862 modified subrepositories, it records their state and finally
6863 commits it in the parent repository. The --addremove option
6864 also honors the -S/--subrepos option. However, Git and Subver‐
6865 sion subrepositories will print a warning and abort.
6866 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
6868 fied. Changes are displayed as usual, on the subrepositories
6869 elements. Subversion subrepositories are currently silently
6870 ignored.
6871 files files does not recurse into subrepos unless -S/--subrepos is
6873 specified. However, if you specify the full path of a file or
6874 directory in a subrepo, it will be displayed even without
6875 -S/--subrepos being specified. Git and Subversion subreposito‐
6876 ries are currently silently ignored.
6877 forget forget currently only handles exact file matches in subrepos.
6879 Git and Subversion subrepositories are currently silently
6880 ignored.
6881 incoming
6883 incoming does not recurse in subrepos unless -S/--subrepos is
6884 specified. Git and Subversion subrepositories are currently
6885 silently ignored.
6886 outgoing
6888 outgoing does not recurse in subrepos unless -S/--subrepos is
6889 specified. Git and Subversion subrepositories are currently
6890 silently ignored.
6891 pull pull is not recursive since it is not clear what to pull prior
6893 to running hg update. Listing and retrieving all subrepositories
6894 changes referenced by the parent repository pulled changesets is
6895 expensive at best, impossible in the Subversion case.
6896 push Mercurial will automatically push all subrepositories first when
6898 the parent repository is being pushed. This ensures new sub‐
6899 repository changes are available when referenced by top-level
6900 repositories. Push is a no-op for Subversion subrepositories.
6901 serve serve does not recurse into subrepositories unless -S/--subrepos
6903 is specified. Git and Subversion subrepositories are currently
6904 silently ignored.
6905 status status does not recurse into subrepositories unless -S/--subre‐
6907 pos is specified. Subrepository changes are displayed as regular
6908 Mercurial changes on the subrepository elements. Subversion sub‐
6909 repositories are currently silently ignored.
6910 remove remove does not recurse into subrepositories unless -S/--subre‐
6912 pos is specified. However, if you specify a file or directory
6913 path in a subrepo, it will be removed even without -S/--subre‐
6914 pos. Git and Subversion subrepositories are currently silently
6915 ignored.
6916 update update restores the subrepos in the state they were originally
6918 committed in target changeset. If the recorded changeset is not
6919 available in the current subrepository, Mercurial will pull it
6920 in first before updating. This means that updating can require
6921 network access when using subrepositories.
6922 Remapping Subrepositories Sources
6924 A subrepository source location may change during a project life,
6925 invalidating references stored in the parent repository history. To fix
6926 this, rewriting rules can be defined in parent repository hgrc file or
6927 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
6928 more details.
6929
6931 Mercurial allows you to customize output of commands through templates.
6932 You can either pass in a template or select an existing template-style
6933 from the command line, via the --template option.
6934 You can customize output for any "log-like" command: log, outgoing,
6936 incoming, tip, parents, and heads.
6937 Some built-in styles are packaged with Mercurial. These can be listed
6939 with hg log --template list. Example usage:
6940 $ hg log -r1.0::1.1 --template changelog
6942 A template is a piece of text, with markup to invoke variable expan‐
6944 sion:
6945 $ hg log -r1 --template "{node}\n"
6947 b56ce7b07c52de7d5fd79fb89701ea538af65746
6948 Keywords
6950 Strings in curly braces are called keywords. The availability of key‐
6951 words depends on the exact context of the templater. These keywords are
6952 usually available for templating a log-like command:
6953 activebookmark
6955 String. The active bookmark, if it is associated with the
6956 changeset.
6957 author Alias for {user}
6959 bisect String. The changeset bisection status.
6961 bookmarks
6963 List of strings. Any bookmarks associated with the changeset.
6964 Also sets 'active', the name of the active bookmark.
6965 branch String. The name of the branch on which the changeset was com‐
6967 mitted.
6968 changessincelatesttag
6970 Integer. All ancestors not in the latest tag.
6971 children
6973 List of strings. The children of the changeset.
6974 date Date information. The date when the changeset was committed.
6976 desc String. The text of the changeset description.
6978 diffstat
6980 String. Statistics of changes with the following format: "modi‐
6981 fied files: +added/-removed lines"
6982 extras List of dicts with key, value entries of the 'extras' field of
6984 this changeset.
6985 file_adds
6987 List of strings. Files added by this changeset.
6988 file_copies
6990 List of strings. Files copied in this changeset with their
6991 sources.
6992 file_copies_switch
6994 List of strings. Like "file_copies" but displayed only if the
6995 --copied switch is set.
6996 file_dels
6998 List of strings. Files removed by this changeset.
6999 file_mods
7001 List of strings. Files modified by this changeset.
7002 files List of strings. All files modified, added, or removed by this
7004 changeset.
7005 graphnode
7007 String. The character representing the changeset node in an
7008 ASCII revision graph.
7009 graphwidth
7011 Integer. The width of the graph drawn by 'log --graph' or zero.
7012 index Integer. The current iteration of the loop. (0 indexed)
7014 latesttag
7016 List of strings. The global tags on the most recent globally
7017 tagged ancestor of this changeset. If no such tags exist, the
7018 list consists of the single string "null".
7019 latesttagdistance
7021 Integer. Longest path to the latest tag.
7022 namespaces
7024 Dict of lists. Names attached to this changeset per namespace.
7025 node String. The changeset identification hash, as a 40 hexadecimal
7027 digit string.
7028 p1 Changeset. The changeset's first parent. {p1.rev} for the revi‐
7030 sion number, and {p1.node} for the identification hash.
7031 p2 Changeset. The changeset's second parent. {p2.rev} for the revi‐
7033 sion number, and {p2.node} for the identification hash.
7034 parents
7036 List of strings. The parents of the changeset in "rev:node" for‐
7037 mat. If the changeset has only one "natural" parent (the prede‐
7038 cessor revision) nothing is shown.
7039 peerurls
7041 A dictionary of repository locations defined in the [paths] sec‐
7042 tion of your configuration file.
7043 phase String. The changeset phase name.
7045 reporoot
7047 String. The root directory of the current repository.
7048 rev Integer. The repository-local changeset revision number.
7050 subrepos
7052 List of strings. Updated subrepositories in the changeset.
7053 tags List of strings. Any tags associated with the changeset.
7055 termwidth
7057 Integer. The width of the current terminal.
7058 user String. The unmodified author of the changeset.
7060 verbosity
7062 String. The current output verbosity in 'debug', 'quiet', 'ver‐
7063 bose', or ''.
7064 The "date" keyword does not produce human-readable output. If you want
7066 to use a date in your output, you can use a filter to process it. Fil‐
7067 ters are functions which return a string based on the input variable.
7068 Be sure to use the stringify filter first when you're applying a
7069 string-input filter to a list-like input variable. You can also use a
7070 chain of filters to get the desired output:
7071 $ hg tip --template "{date|isodate}\n"
7073 2008-08-21 18:22 +0000
7074 Filters
7076 List of filters:
7077 addbreaks
7079 Any text. Add an XHTML "<br />" tag before the end of every line
7080 except the last.
7081 age Date. Returns a human-readable date/time difference between the
7083 given date/time and the current date/time.
7084 basename
7086 Any text. Treats the text as a path, and returns the last compo‐
7087 nent of the path after splitting by the path separator. For
7088 example, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
7089 commondir
7091 List of text. Treats each list item as file name with / as path
7092 separator and returns the longest common directory prefix shared
7093 by all list items. Returns the empty string if no common prefix
7094 exists.
7095 The list items are not normalized, i.e. "foo/../bar" is handled
7097 as file "bar" in the directory "foo/..". Leading slashes are
7098 ignored.
7099 For example, ["foo/bar/baz", "foo/baz/bar"] becomes "foo" and
7101 ["foo/bar", "baz"] becomes "".
7102 count List or text. Returns the length as an integer.
7104 dirname
7106 Any text. Treats the text as a path, and strips the last compo‐
7107 nent of the path after splitting by the path separator.
7108 domain Any text. Finds the first string that looks like an email
7110 address, and extracts just the domain component. Example: User
7111 <user@example.com> becomes example.com.
7112 email Any text. Extracts the first string that looks like an email
7114 address. Example: User <user@example.com> becomes user@exam‐
7115 ple.com.
7116 emailuser
7118 Any text. Returns the user portion of an email address.
7119 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
7121 ">" with XML entities, and filters out NUL characters.
7122 fill68 Any text. Wraps the text to fit in 68 columns.
7124 fill76 Any text. Wraps the text to fit in 76 columns.
7126 firstline
7128 Any text. Returns the first line of text.
7129 hex Any text. Convert a binary Mercurial node identifier into its
7131 long hexadecimal representation.
7132 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
7134 (Unix timestamp, timezone offset).
7135 isodate
7137 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
7138 +0200".
7139 isodatesec
7141 Date. Returns the date in ISO 8601 format, including seconds:
7142 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
7143 json Any object. Serializes the object to a JSON formatted text.
7145 lower Any text. Converts the text to lowercase.
7147 nonempty
7149 Any text. Returns '(none)' if the string is empty.
7150 obfuscate
7152 Any text. Returns the input text rendered as a sequence of XML
7153 entities.
7154 person Any text. Returns the name before an email address, interpreting
7156 it as per RFC 5322.
7157 revescape
7159 Any text. Escapes all "special" characters, except @. Forward
7160 slashes are escaped twice to prevent web servers from prema‐
7161 turely unescaping them. For example, "@foo bar/baz" becomes
7162 "@foo%20bar%252Fbaz".
7163 rfc3339date
7165 Date. Returns a date using the Internet date format specified in
7166 RFC 3339: "2009-08-18T13:00:13+02:00".
7167 rfc822date
7169 Date. Returns a date using the same format used in email head‐
7170 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
7171 short Changeset hash. Returns the short form of a changeset hash, i.e.
7173 a 12 hexadecimal digit string.
7174 shortbisect
7176 Any text. Treats label as a bisection status, and returns a sin‐
7177 gle-character representing the status (G: good, B: bad, S:
7178 skipped, U: untested, I: ignored). Returns single space if text
7179 is not a valid bisection status.
7180 shortdate
7182 Date. Returns a date like "2006-09-18".
7183 slashpath
7185 Any text. Replaces the native path separator with slash.
7186 splitlines
7188 Any text. Split text into a list of lines.
7189 stringify
7191 Any type. Turns the value into text by converting values into
7192 text and concatenating them.
7193 stripdir
7195 Treat the text as path and strip a directory level, if possible.
7196 For example, "foo" and "foo/bar" becomes "foo".
7197 tabindent
7199 Any text. Returns the text, with every non-empty line except the
7200 first starting with a tab character.
7201 upper Any text. Converts the text to uppercase.
7203 urlescape
7205 Any text. Escapes all "special" characters. For example, "foo
7206 bar" becomes "foo%20bar".
7207 user Any text. Returns a short representation of a user name or email
7209 address.
7210 utf8 Any text. Converts from the local character encoding to UTF-8.
7212 Note that a filter is nothing more than a function call, i.e.
7214 expr|filter is equivalent to filter(expr).
7215 Functions
7217 In addition to filters, there are some basic built-in functions:
7218 date(date[, fmt])
7220 Format a date. See hg help dates for formatting strings. The
7221 default is a Unix date format, including the timezone: "Mon Sep
7222 04 15:13:13 2006 0700".
7223 dict([[key=]value...])
7225 Construct a dict from key-value pairs. A key may be omitted if a
7226 value expression can provide an unambiguous name.
7227 diff([includepattern [, excludepattern]])
7229 Show a diff, optionally specifying files to include or exclude.
7230 files(pattern)
7232 All files of the current changeset matching the pattern. See hg
7233 help patterns.
7234 fill(text[, width[, initialident[, hangindent]]])
7236 Fill many paragraphs with optional indentation. See the "fill"
7237 filter.
7238 filter(iterable[, expr])
7240 Remove empty elements from a list or a dict. If expr specified,
7241 it's applied to each element to test emptiness.
7242 get(dict, key)
7244 Get an attribute/key from an object. Some keywords are complex
7245 types. This function allows you to obtain the value of an
7246 attribute on these types.
7247 if(expr, then[, else])
7249 Conditionally execute based on the result of an expression.
7250 ifcontains(needle, haystack, then[, else])
7252 Conditionally execute based on whether the item "needle" is in
7253 "haystack".
7254 ifeq(expr1, expr2, then[, else])
7256 Conditionally execute based on whether 2 items are equivalent.
7257 indent(text, indentchars[, firstline])
7259 Indents all non-empty lines with the characters given in the
7260 indentchars string. An optional third parameter will override
7261 the indent for the first line only if present.
7262 join(list, sep)
7264 Join items in a list with a delimiter.
7265 label(label, expr)
7267 Apply a label to generated content. Content with a label applied
7268 can result in additional post-processing, such as automatic col‐
7269 orization.
7270 latesttag([pattern])
7272 The global tags matching the given pattern on the most recent
7273 globally tagged ancestor of this changeset. If no such tags
7274 exist, the "{tag}" template resolves to the string "null". See
7275 hg help revisions.patterns for the pattern syntax.
7276 localdate(date[, tz])
7278 Converts a date to the specified timezone. The default is local
7279 date.
7280 mailmap(author)
7282 Return the author, updated according to the value set in the
7283 .mailmap file
7284 max(iterable)
7286 Return the max of an iterable
7287 min(iterable)
7289 Return the min of an iterable
7290 mod(a, b)
7292 Calculate a mod b such that a / b + a mod b == a
7293 pad(text, width[, fillchar=' '[, left=False[, truncate=False]]])
7295 Pad text with a fill character.
7296 relpath(path)
7298 Convert a repository-absolute path into a filesystem path rela‐
7299 tive to the current working directory.
7300 revset(query[, formatargs...])
7302 Execute a revision set query. See hg help revset.
7303 rstdoc(text, style)
7305 Format reStructuredText.
7306 search(pattern, text)
7308 Look for the first text matching the regular expression pattern.
7309 Groups are accessible as {1}, {2}, ... in %-mapped template.
7310 separate(sep, args...)
7312 Add a separator between non-empty arguments.
7313 shortest(node, minlength=4)
7315 Obtain the shortest representation of a node.
7316 startswith(pattern, text)
7318 Returns the value from the "text" argument if it begins with the
7319 content from the "pattern" argument.
7320 strip(text[, chars])
7322 Strip characters from a string. By default, strips all leading
7323 and trailing whitespace.
7324 sub(pattern, replacement, expression)
7326 Perform text substitution using regular expressions.
7327 word(number, text[, separator])
7329 Return the nth word from a string.
7330 Operators
7332 We provide a limited set of infix arithmetic operations on integers:
7333 + for addition
7335 - for subtraction
7336 * for multiplication
7337 / for floor division (division rounded to integer nearest -infinity)
7338 Division fulfills the law x = x / y + mod(x, y).
7340 Also, for any expression that returns a list, there is a list operator:
7342 expr % "{template}"
7344 As seen in the above example, {template} is interpreted as a template.
7346 To prevent it from being interpreted, you can use an escape character
7347 \{ or a raw string prefix, r'...'.
7348 The dot operator can be used as a shorthand for accessing a sub item:
7350 · expr.member is roughly equivalent to expr % '{member}' if expr
7352 returns a non-list/dict. The returned value is not stringified.
7353 · dict.key is identical to get(dict, 'key').
7355 Aliases
7357 New keywords and functions can be defined in the templatealias section
7358 of a Mercurial configuration file:
7359 <alias> = <definition>
7361 Arguments of the form a1, a2, etc. are substituted from the alias into
7363 the definition.
7364 For example,
7366 [templatealias]
7368 r = rev
7369 rn = "{r}:{node|short}"
7370 leftpad(s, w) = pad(s, w, ' ', True)
7371 defines two symbol aliases, r and rn, and a function alias leftpad().
7373 It's also possible to specify complete template strings, using the tem‐
7375 plates section. The syntax used is the general template string syntax.
7376 For example,
7378 [templates]
7380 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
7381 defines a template, nodedate, which can be called like:
7383 $ hg log -r . -Tnodedate
7385 A template defined in templates section can also be referenced from
7387 another template:
7388 $ hg log -r . -T "{rev} {nodedate}"
7390 but be aware that the keywords cannot be overridden by templates. For
7392 example, a template defined as templates.rev cannot be referenced as
7393 {rev}.
7394 A template defined in templates section may have sub templates which
7396 are inserted before/after/between items:
7397 [templates]
7399 myjson = ' {dict(rev, node|short)|json}'
7400 myjson:docheader = '\{\n'
7401 myjson:docfooter = '\n}\n'
7402 myjson:separator = ',\n'
7403 Examples
7405 Some sample command line templates:
7406 · Format lists, e.g. files:
7408 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
7410 · Join the list of files with a ", ":
7412 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
7414 · Join the list of files ending with ".py" with a ", ":
7416 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
7418 · Separate non-empty arguments by a " ":
7420 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
7422 · Modify each line of a commit description:
7424 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
7426 · Format date:
7428 $ hg log -r 0 --template "{date(date, '%Y')}\n"
7430 · Display date in UTC:
7432 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
7434 · Output the description set to a fill-width of 30:
7436 $ hg log -r 0 --template "{fill(desc, 30)}"
7438 · Use a conditional to test for the default branch:
7440 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
7442 'on branch {branch}')}\n"
7443 · Append a newline if not empty:
7445 $ hg tip --template "{if(author, '{author}\n')}"
7447 · Label the output for use with the color extension:
7449 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
7451 · Invert the firstline filter, i.e. everything but the first line:
7453 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
7455 · Display the contents of the 'extra' field, one per line:
7457 $ hg log -r 0 --template "{join(extras, '\n')}\n"
7459 · Mark the active bookmark with '*':
7461 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
7463 · Find the previous release candidate tag, the distance and changes
7465 since the tag:
7466 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
7468 · Mark the working copy parent with '@':
7470 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
7472 · Show details of parent revisions:
7474 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
7476 · Show only commit descriptions that start with "template":
7478 $ hg log --template "{startswith('template', firstline(desc))}\n"
7480 · Print the first word of each line of a commit message:
7482 $ hg log --template "{word(0, desc)}\n"
7484
7486 Valid URLs are of the form:
7487 local/filesystem/path[#revision]
7489 file://local/filesystem/path[#revision]
7490 http://[user[:pass]@]host[:port]/[path][#revision]
7491 https://[user[:pass]@]host[:port]/[path][#revision]
7492 ssh://[user@]host[:port]/[path][#revision]
7493 Paths in the local filesystem can either point to Mercurial reposito‐
7495 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
7496 dle). See also hg help paths.
7497 An optional identifier after # indicates a particular branch, tag, or
7499 changeset to use from the remote repository. See also hg help revisions
7500 .
7501 Some features, such as pushing to http:// and https:// URLs are only
7503 possible if the feature is explicitly enabled on the remote Mercurial
7504 server.
7505 Note that the security of HTTPS URLs depends on proper configuration of
7507 web.cacerts.
7508 Some notes about using SSH with Mercurial:
7510 · SSH requires an accessible shell account on the destination machine
7512 and a copy of hg in the remote path or specified with remotecmd.
7513 · path is relative to the remote user's home directory by default. Use
7515 an extra slash at the start of a path to specify an absolute path:
7516 ssh://example.com//tmp/repository
7518 · Mercurial doesn't use its own compression via SSH; the right thing to
7520 do is to configure it in your ~/.ssh/config, e.g.:
7521 Host *.mylocalnetwork.example.com
7523 Compression no
7524 Host *
7525 Compression yes
7526 Alternatively specify "ssh -C" as your ssh command in your configura‐
7528 tion file or with the --ssh command line option.
7529 These URLs can all be stored in your configuration file with path
7531 aliases under the [paths] section like so:
7532 [paths]
7534 alias1 = URL1
7535 alias2 = URL2
7536 ...
7537 You can then use the alias for any command that uses a URL (for example
7539 hg pull alias1 will be treated as hg pull URL1).
7540 Two path aliases are special because they are used as defaults when you
7542 do not provide the URL to a command:
7543 default:
7545 When you create a repository with hg clone, the clone command
7546 saves the location of the source repository as the new reposi‐
7547 tory's 'default' path. This is then used when you omit path from
7548 push- and pull-like commands (including incoming and outgoing).
7549 default-push:
7551 The push command will look for a path named 'default-push', and
7552 prefer it over 'default' if both are defined.
7553
7555 This section contains help for extensions that are distributed together
7556 with Mercurial. Help for other extensions is available in the help sys‐
7557 tem.
7558 absorb
7560 apply working directory changes to changesets (EXPERIMENTAL)
7561 The absorb extension provides a command to use annotate information to
7563 amend modified chunks into the corresponding non-public changesets.
7564 [absorb]
7566 # only check 50 recent non-public changesets at most
7567 max-stack-size = 50
7568 # whether to add noise to new commits to avoid obsolescence cycle
7569 add-noise = 1
7570 # make `amend --correlated` a shortcut to the main command
7571 amend-flag = correlated
7572 [color]
7574 absorb.description = yellow
7575 absorb.node = blue bold
7576 absorb.path = bold
7577 Commands
7579 absorb
7580 incorporate corrections into the stack of draft changesets:
7581 hg absorb [OPTION] [FILE]...
7583 absorb analyzes each change in your working directory and attempts to
7585 amend the changed lines into the changesets in your stack that first
7586 introduced those lines.
7587 If absorb cannot find an unambiguous changeset to amend for a change,
7589 that change will be left in the working directory, untouched. They can
7590 be observed by hg status or hg diff afterwards. In other words, absorb
7591 does not write to the working directory.
7592 Changesets outside the revset ::. and not public() and not merge() will
7594 not be changed.
7595 Changesets that become empty after applying the changes will be
7597 deleted.
7598 By default, absorb will show what it plans to do and prompt for confir‐
7600 mation. If you are confident that the changes will be absorbed to the
7601 correct place, run hg absorb -a to apply the changes immediately.
7602 Returns 0 on success, 1 if all chunks were ignored and nothing amended.
7604 Options:
7606 -a, --apply-changes
7608 apply changes without prompting for confirmation
7609 -p, --print-changes
7611 always print which changesets are modified by which changes
7612 -i, --interactive
7614 interactively select which chunks to apply (EXPERIMENTAL)
7615 -e, --edit-lines
7617 edit what lines belong to which changesets before commit (EXPER‐
7618 IMENTAL)
7619 -n, --dry-run
7621 do not perform actions, just print output
7622 --style <STYLE>
7624 display using template map file (DEPRECATED)
7625 -T,--template <TEMPLATE>
7627 display with template
7628 -I,--include <PATTERN[+]>
7630 include names matching the given patterns
7631 -X,--exclude <PATTERN[+]>
7633 exclude names matching the given patterns
7634 [+] marked option can be specified multiple times
7636 acl
7638 hooks for controlling repository access
7639 This hook makes it possible to allow or deny write access to given
7641 branches and paths of a repository when receiving incoming changesets
7642 via pretxnchangegroup and pretxncommit.
7643 The authorization is matched based on the local user name on the system
7645 where the hook runs, and not the committer of the original changeset
7646 (since the latter is merely informative).
7647 The acl hook is best used along with a restricted shell like hgsh, pre‐
7649 venting authenticating users from doing anything other than pushing or
7650 pulling. The hook is not safe to use if users have interactive shell
7651 access, as they can then disable the hook. Nor is it safe if remote
7652 users share an account, because then there is no way to distinguish
7653 them.
7654 The order in which access checks are performed is:
7656 1. Deny list for branches (section acl.deny.branches)
7658 2. Allow list for branches (section acl.allow.branches)
7660 3. Deny list for paths (section acl.deny)
7662 4. Allow list for paths (section acl.allow)
7664 The allow and deny sections take key-value pairs.
7666 Branch-based Access Control
7668 Use the acl.deny.branches and acl.allow.branches sections to have
7669 branch-based access control. Keys in these sections can be either:
7670 · a branch name, or
7672 · an asterisk, to match any branch;
7674 The corresponding values can be either:
7676 · a comma-separated list containing users and groups, or
7678 · an asterisk, to match anyone;
7680 You can add the "!" prefix to a user or group name to invert the sense
7682 of the match.
7683 Path-based Access Control
7685 Use the acl.deny and acl.allow sections to have path-based access con‐
7686 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
7687 tax by default). The corresponding values follow the same syntax as the
7688 other sections above.
7689 Bookmark-based Access Control
7691 Use the acl.deny.bookmarks and acl.allow.bookmarks sections to have
7692 bookmark-based access control. Keys in these sections can be either:
7693 · a bookmark name, or
7695 · an asterisk, to match any bookmark;
7697 The corresponding values can be either:
7699 · a comma-separated list containing users and groups, or
7701 · an asterisk, to match anyone;
7703 You can add the "!" prefix to a user or group name to invert the sense
7705 of the match.
7706 Note: for interactions between clients and servers using Mercurial 3.6+
7708 a rejection will generally reject the entire push, for interactions
7709 involving older clients, the commit transactions will already be
7710 accepted, and only the bookmark movement will be rejected.
7711 Groups
7713 Group names must be prefixed with an @ symbol. Specifying a group name
7714 has the same effect as specifying all the users in that group.
7715 You can define group members in the acl.groups section. If a group
7717 name is not defined there, and Mercurial is running under a Unix-like
7718 system, the list of users will be taken from the OS. Otherwise, an
7719 exception will be raised.
7720 Example Configuration
7722 [hooks]
7723 # Use this if you want to check access restrictions at commit time
7725 pretxncommit.acl = python:hgext.acl.hook
7726 # Use this if you want to check access restrictions for pull, push,
7728 # bundle and serve.
7729 pretxnchangegroup.acl = python:hgext.acl.hook
7730 [acl]
7732 # Allow or deny access for incoming changes only if their source is
7733 # listed here, let them pass otherwise. Source is "serve" for all
7734 # remote access (http or ssh), "push", "pull" or "bundle" when the
7735 # related commands are run locally.
7736 # Default: serve
7737 sources = serve
7738 [acl.deny.branches]
7740 # Everyone is denied to the frozen branch:
7742 frozen-branch = *
7743 # A bad user is denied on all branches:
7745 * = bad-user
7746 [acl.allow.branches]
7748 # A few users are allowed on branch-a:
7750 branch-a = user-1, user-2, user-3
7751 # Only one user is allowed on branch-b:
7753 branch-b = user-1
7754 # The super user is allowed on any branch:
7756 * = super-user
7757 # Everyone is allowed on branch-for-tests:
7759 branch-for-tests = *
7760 [acl.deny]
7762 # This list is checked first. If a match is found, acl.allow is not
7763 # checked. All users are granted access if acl.deny is not present.
7764 # Format for both lists: glob pattern = user, ..., @group, ...
7765 # To match everyone, use an asterisk for the user:
7767 # my/glob/pattern = *
7768 # user6 will not have write access to any file:
7770 ** = user6
7771 # Group "hg-denied" will not have write access to any file:
7773 ** = @hg-denied
7774 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
7776 # everyone being able to change all other files. See below.
7777 src/main/resources/DONT-TOUCH-THIS.txt = *
7778 [acl.allow]
7780 # if acl.allow is not present, all users are allowed by default
7781 # empty acl.allow = no users allowed
7782 # User "doc_writer" has write access to any file under the "docs"
7784 # folder:
7785 docs/** = doc_writer
7786 # User "jack" and group "designers" have write access to any file
7788 # under the "images" folder:
7789 images/** = jack, @designers
7790 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
7792 # will have write access to any file under the "resources" folder
7793 # (except for 1 file. See acl.deny):
7794 src/main/resources/** = *
7795 .hgtags = release_engineer
7797 Examples using the ! prefix
7799 Suppose there's a branch that only a given user (or group) should be
7800 able to push to, and you don't want to restrict access to any other
7801 branch that may be created.
7802 The "!" prefix allows you to prevent anyone except a given user or
7804 group to push changesets in a given branch or path.
7805 In the examples below, we will: 1) Deny access to branch "ring" to any‐
7807 one but user "gollum" 2) Deny access to branch "lake" to anyone but
7808 members of the group "hobbit" 3) Deny access to a file to anyone but
7809 user "gollum"
7810 [acl.allow.branches]
7812 # Empty
7813 [acl.deny.branches]
7815 # 1) only 'gollum' can commit to branch 'ring';
7817 # 'gollum' and anyone else can still commit to any other branch.
7818 ring = !gollum
7819 # 2) only members of the group 'hobbit' can commit to branch 'lake';
7821 # 'hobbit' members and anyone else can still commit to any other branch.
7822 lake = !@hobbit
7823 # You can also deny access based on file paths:
7825 [acl.allow]
7827 # Empty
7828 [acl.deny]
7830 # 3) only 'gollum' can change the file below;
7831 # 'gollum' and anyone else can still change any other file.
7832 /misty/mountains/cave/ring = !gollum
7833 amend
7835 provide the amend command (EXPERIMENTAL)
7836 This extension provides an amend command that is similar to commit
7838 --amend but does not prompt an editor.
7839 Commands
7841 amend
7842 amend the working copy parent with all or specified outstanding
7843 changes:
7844 hg amend [OPTION]... [FILE]...
7846 Similar to hg commit --amend, but reuse the commit message without
7848 invoking editor, unless --edit was set.
7849 See hg help commit for more details.
7851 Options:
7853 -A, --addremove
7855 mark new/missing files as added/removed before committing
7856 -e, --edit
7858 invoke editor on commit messages
7859 -i, --interactive
7861 use interactive mode
7862 -n,--note <VALUE>
7864 store a note on the amend
7865 -D, --currentdate
7867 record the current date as commit date
7868 -I,--include <PATTERN[+]>
7870 include names matching the given patterns
7871 -X,--exclude <PATTERN[+]>
7873 exclude names matching the given patterns
7874 -m,--message <TEXT>
7876 use text as commit message
7877 -l,--logfile <FILE>
7879 read commit message from file
7880 -d,--date <DATE>
7882 record the specified date as commit date
7883 -u,--user <USER>
7885 record the specified user as committer
7886 [+] marked option can be specified multiple times
7888 automv
7890 check for unrecorded moves at commit time (EXPERIMENTAL)
7891 This extension checks at commit/amend time if any of the committed
7893 files comes from an unrecorded mv.
7894 The threshold at which a file is considered a move can be set with the
7896 automv.similarity config option. This option takes a percentage between
7897 0 (disabled) and 100 (files must be identical), the default is 95.
7898 beautifygraph
7900 beautify log -G output by using Unicode characters (EXPERIMENTAL)
7901 A terminal with UTF-8 support and monospace narrow text are
7903 required.
7904 blackbox
7906 log repository events to a blackbox for debugging
7907 Logs event information to .hg/blackbox.log to help debug and diagnose
7909 problems. The events that get logged can be configured via the black‐
7910 box.track config key.
7911 Examples:
7913 [blackbox]
7915 track = *
7916 # dirty is *EXPENSIVE* (slow);
7917 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
7918 dirty = True
7919 # record the source of log messages
7920 logsource = True
7921 [blackbox]
7923 track = command, commandfinish, commandexception, exthook, pythonhook
7924 [blackbox]
7926 track = incoming
7927 [blackbox]
7929 # limit the size of a log file
7930 maxsize = 1.5 MB
7931 # rotate up to N log files when the current one gets too big
7932 maxfiles = 3
7933 [blackbox]
7935 # Include nanoseconds in log entries with %f (see Python function
7936 # datetime.datetime.strftime)
7937 date-format = '%Y-%m-%d @ %H:%M:%S.%f'
7938 Commands
7940 blackbox
7941 view the recent repository events:
7942 hg blackbox [OPTION]...
7944 view the recent repository events
7946 Options:
7948 -l,--limit <VALUE>
7950 the number of events to show (default: 10)
7951 bookflow
7953 implements bookmark-based branching (EXPERIMENTAL)
7954 · Disables creation of new branches (config: enable_branches=False).
7956 · Requires an active bookmark on commit (config: require_book‐
7958 mark=True).
7959 · Doesn't move the active bookmark on update, only on commit.
7961 · Requires '--rev' for moving an existing bookmark.
7963 · Protects special bookmarks (config: protect=@).
7965 flow related commands
7967 hg book NAME
7969 create a new bookmark
7970 hg book NAME -r REV
7972 move bookmark to revision (fast-forward)
7973 hg up|co NAME
7975 switch to bookmark
7976 hg push -B .
7978 push active bookmark
7979 bugzilla
7981 hooks for integrating with the Bugzilla bug tracker
7982 This hook extension adds comments on bugs in Bugzilla when changesets
7984 that refer to bugs by Bugzilla ID are seen. The comment is formatted
7985 using the Mercurial template mechanism.
7986 The bug references can optionally include an update for Bugzilla of the
7988 hours spent working on the bug. Bugs can also be marked fixed.
7989 Four basic modes of access to Bugzilla are provided:
7991 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
7993 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
7995 later.
7996 3. Check data via the Bugzilla XMLRPC interface and submit bug change
7998 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
7999 later.
8000 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
8002 tions using MySQL are supported. Requires Python MySQLdb.
8003 Writing directly to the database is susceptible to schema changes, and
8005 relies on a Bugzilla contrib script to send out bug change notification
8006 emails. This script runs as the user running Mercurial, must be run on
8007 the host with the Bugzilla install, and requires permission to read
8008 Bugzilla configuration details and the necessary MySQL user and pass‐
8009 word to have full access rights to the Bugzilla database. For these
8010 reasons this access mode is now considered deprecated, and will not be
8011 updated for new Bugzilla versions going forward. Only adding comments
8012 is supported in this access mode.
8013 Access via XMLRPC needs a Bugzilla username and password to be speci‐
8015 fied in the configuration. Comments are added under that username.
8016 Since the configuration must be readable by all Mercurial users, it is
8017 recommended that the rights of that user are restricted in Bugzilla to
8018 the minimum necessary to add comments. Marking bugs fixed requires
8019 Bugzilla 4.0 and later.
8020 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
8022 to the Bugzilla email interface to submit comments to bugs. The From:
8023 address in the email is set to the email address of the Mercurial user,
8024 so the comment appears to come from the Mercurial user. In the event
8025 that the Mercurial user email is not recognized by Bugzilla as a
8026 Bugzilla user, the email associated with the Bugzilla username used to
8027 log into Bugzilla is used instead as the source of the comment. Marking
8028 bugs fixed works on all supported Bugzilla versions.
8029 Access via the REST-API needs either a Bugzilla username and password
8031 or an apikey specified in the configuration. Comments are made under
8032 the given username or the user associated with the apikey in Bugzilla.
8033 Configuration items common to all access modes:
8035 bugzilla.version
8037 The access type to use. Values recognized are:
8038 restapi
8040 Bugzilla REST-API, Bugzilla 5.0 and later.
8042 xmlrpc
8044 Bugzilla XMLRPC interface.
8046 xmlrpc+email
8048 Bugzilla XMLRPC and email interfaces.
8050 3.0
8052 MySQL access, Bugzilla 3.0 and later.
8054 2.18
8056 MySQL access, Bugzilla 2.18 and up to but not including
8058 3.0.
8059 2.16
8061 MySQL access, Bugzilla 2.16 and up to but not including
8063 2.18.
8064 bugzilla.regexp
8066 Regular expression to match bug IDs for update in changeset com‐
8067 mit message. It must contain one "()" named group <ids> con‐
8068 taining the bug IDs separated by non-digit characters. It may
8069 also contain a named group <hours> with a floating-point number
8070 giving the hours worked on the bug. If no named groups are
8071 present, the first "()" group is assumed to contain the bug IDs,
8072 and work time is not updated. The default expression matches Bug
8073 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
8074 and 5678 and variations thereof, followed by an hours number
8075 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
8076 sitive.
8077 bugzilla.fixregexp
8079 Regular expression to match bug IDs for marking fixed in change‐
8080 set commit message. This must contain a "()" named group <ids>`
8081 containing the bug IDs separated by non-digit characters. It may
8082 also contain a named group ``<hours> with a floating-point num‐
8083 ber giving the hours worked on the bug. If no named groups are
8084 present, the first "()" group is assumed to contain the bug IDs,
8085 and work time is not updated. The default expression matches
8086 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
8087 5678 and variations thereof, followed by an hours number pre‐
8088 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
8089 tive.
8090 bugzilla.fixstatus
8092 The status to set a bug to when marking fixed. Default RESOLVED.
8093 bugzilla.fixresolution
8095 The resolution to set a bug to when marking fixed. Default
8096 FIXED.
8097 bugzilla.style
8099 The style file to use when formatting comments.
8100 bugzilla.template
8102 Template to use when formatting comments. Overrides style if
8103 specified. In addition to the usual Mercurial keywords, the
8104 extension specifies:
8105 {bug}
8107 The Bugzilla bug ID.
8109 {root}
8111 The full pathname of the Mercurial repository.
8113 {webroot}
8115 Stripped pathname of the Mercurial repository.
8117 {hgweb}
8119 Base URL for browsing Mercurial repositories.
8121 Default changeset {node|short} in repo {root} refers to bug
8123 {bug}.\ndetails:\n\t{desc|tabindent}
8124 bugzilla.strip
8126 The number of path separator characters to strip from the front
8127 of the Mercurial repository path ({root} in templates) to pro‐
8128 duce {webroot}. For example, a repository with {root}
8129 /var/local/my-project with a strip of 2 gives a value for {web‐
8130 root} of my-project. Default 0.
8131 web.baseurl
8133 Base URL for browsing Mercurial repositories. Referenced from
8134 templates as {hgweb}.
8135 Configuration items common to XMLRPC+email and MySQL access modes:
8137 bugzilla.usermap
8139 Path of file containing Mercurial committer email to Bugzilla
8140 user email mappings. If specified, the file should contain one
8141 mapping per line:
8142 committer = Bugzilla user
8144 See also the [usermap] section.
8146 The [usermap] section is used to specify mappings of Mercurial commit‐
8148 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
8149 entries of the form committer = Bugzilla user.
8150 XMLRPC and REST-API access mode configuration:
8152 bugzilla.bzurl
8154 The base URL for the Bugzilla installation. Default
8155 http://localhost/bugzilla.
8156 bugzilla.user
8158 The username to use to log into Bugzilla via XMLRPC. Default
8159 bugs.
8160 bugzilla.password
8162 The password for Bugzilla login.
8163 REST-API access mode uses the options listed above as well as:
8165 bugzilla.apikey
8167 An apikey generated on the Bugzilla instance for api access.
8168 Using an apikey removes the need to store the user and password
8169 options.
8170 XMLRPC+email access mode uses the XMLRPC access mode configuration
8172 items, and also:
8173 bugzilla.bzemail
8175 The Bugzilla email address.
8176 In addition, the Mercurial email settings must be configured. See the
8178 documentation in hgrc(5), sections [email] and [smtp].
8179 MySQL access mode configuration:
8181 bugzilla.host
8183 Hostname of the MySQL server holding the Bugzilla database.
8184 Default localhost.
8185 bugzilla.db
8187 Name of the Bugzilla database in MySQL. Default bugs.
8188 bugzilla.user
8190 Username to use to access MySQL server. Default bugs.
8191 bugzilla.password
8193 Password to use to access MySQL server.
8194 bugzilla.timeout
8196 Database connection timeout (seconds). Default 5.
8197 bugzilla.bzuser
8199 Fallback Bugzilla user name to record comments with, if change‐
8200 set committer cannot be found as a Bugzilla user.
8201 bugzilla.bzdir
8203 Bugzilla install directory. Used by default notify. Default
8204 /var/www/html/bugzilla.
8205 bugzilla.notify
8207 The command to run to get Bugzilla to send bug change notifica‐
8208 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
8209 id) and user (committer bugzilla email). Default depends on ver‐
8210 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
8211 mail.pl %(id)s %(user)s".
8212 Activating the extension:
8214 [extensions]
8216 bugzilla =
8217 [hooks]
8219 # run bugzilla hook on every change pulled or pushed in here
8220 incoming.bugzilla = python:hgext.bugzilla.hook
8221 Example configurations:
8223 XMLRPC example configuration. This uses the Bugzilla at
8225 http://my-project.org/bugzilla, logging in as user bug‐
8226 mail@my-project.org with password plugh. It is used with a collection
8227 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8228 at http://my-project.org/hg.
8229 [bugzilla]
8231 bzurl=http://my-project.org/bugzilla
8232 user=bugmail@my-project.org
8233 password=plugh
8234 version=xmlrpc
8235 template=Changeset {node|short} in {root|basename}.
8236 {hgweb}/{webroot}/rev/{node|short}\n
8237 {desc}\n
8238 strip=5
8239 [web]
8241 baseurl=http://my-project.org/hg
8242 XMLRPC+email example configuration. This uses the Bugzilla at
8244 http://my-project.org/bugzilla, logging in as user bug‐
8245 mail@my-project.org with password plugh. It is used with a collection
8246 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8247 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
8248 email address bugzilla@my-project.org.
8249 [bugzilla]
8251 bzurl=http://my-project.org/bugzilla
8252 user=bugmail@my-project.org
8253 password=plugh
8254 version=xmlrpc+email
8255 bzemail=bugzilla@my-project.org
8256 template=Changeset {node|short} in {root|basename}.
8257 {hgweb}/{webroot}/rev/{node|short}\n
8258 {desc}\n
8259 strip=5
8260 [web]
8262 baseurl=http://my-project.org/hg
8263 [usermap]
8265 user@emaildomain.com=user.name@bugzilladomain.com
8266 MySQL example configuration. This has a local Bugzilla 3.2 installation
8268 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
8269 database name is bugs and MySQL is accessed with MySQL username bugs
8270 password XYZZY. It is used with a collection of Mercurial repositories
8271 in /var/local/hg/repos/, with a web interface at
8272 http://my-project.org/hg.
8273 [bugzilla]
8275 host=localhost
8276 password=XYZZY
8277 version=3.0
8278 bzuser=unknown@domain.com
8279 bzdir=/opt/bugzilla-3.2
8280 template=Changeset {node|short} in {root|basename}.
8281 {hgweb}/{webroot}/rev/{node|short}\n
8282 {desc}\n
8283 strip=5
8284 [web]
8286 baseurl=http://my-project.org/hg
8287 [usermap]
8289 user@emaildomain.com=user.name@bugzilladomain.com
8290 All the above add a comment to the Bugzilla bug record of the form:
8292 Changeset 3b16791d6642 in repository-name.
8294 http://my-project.org/hg/repository-name/rev/3b16791d6642
8295 Changeset commit comment. Bug 1234.
8297 censor
8299 erase file content at a given revision
8300 The censor command instructs Mercurial to erase all content of a file
8302 at a given revision without updating the changeset hash. This allows
8303 existing history to remain valid while preventing future clones/pulls
8304 from receiving the erased data.
8305 Typical uses for censor are due to security or legal requirements,
8307 including:
8308 * Passwords, private keys, cryptographic material
8310 * Licensed data/code/libraries for which the license has expired
8311 * Personally Identifiable Information or other private data
8312 Censored nodes can interrupt mercurial's typical operation whenever the
8314 excised data needs to be materialized. Some commands, like hg cat/hg
8315 revert, simply fail when asked to produce censored data. Others, like
8316 hg verify and hg update, must be capable of tolerating censored data to
8317 continue to function in a meaningful way. Such commands only tolerate
8318 censored file revisions if they are allowed by the "censor.pol‐
8319 icy=ignore" config option.
8320 Commands
8322 censor
8323 hg censor -r REV [-t TEXT] [FILE]
8324 Options:
8326 -r,--rev <REV>
8328 censor file from specified revision
8329 -t,--tombstone <TEXT>
8331 replacement tombstone data
8332 children
8334 command to display child changesets (DEPRECATED)
8335 This extension is deprecated. You should use hg log -r "children(REV)"
8337 instead.
8338 Commands
8340 children
8341 show the children of the given or working directory revision:
8342 hg children [-r REV] [FILE]
8344 Print the children of the working directory's revisions. If a revision
8346 is given via -r/--rev, the children of that revision will be printed.
8347 If a file argument is given, revision in which the file was last
8348 changed (after the working directory revision or the argument to --rev
8349 if given) is printed.
8350 Please use hg log instead:
8352 hg children => hg log -r "children(.)"
8354 hg children -r REV => hg log -r "children(REV)"
8355 See hg help log and hg help revsets.children.
8357 Options:
8359 -r,--rev <REV>
8361 show children of the specified revision (default: .)
8362 --style <STYLE>
8364 display using template map file (DEPRECATED)
8365 -T,--template <TEMPLATE>
8367 display with template
8368 churn
8370 command to display statistics about repository history
8371 Commands
8373 churn
8374 histogram of changes to the repository:
8375 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
8377 This command will display a histogram representing the number of
8379 changed lines or revisions, grouped according to the given template.
8380 The default template will group changes by author. The --dateformat
8381 option may be used to group the results by date instead.
8382 Statistics are based on the number of changed lines, or alternatively
8384 the number of matching revisions if the --changesets option is speci‐
8385 fied.
8386 Examples:
8388 # display count of changed lines for every committer
8390 hg churn -T "{author|email}"
8391 # display daily activity graph
8393 hg churn -f "%H" -s -c
8394 # display activity of developers by month
8396 hg churn -f "%Y-%m" -s -c
8397 # display count of lines changed in every year
8399 hg churn -f "%Y" -s
8400 It is possible to map alternate email addresses to a main address by
8402 providing a file using the following format:
8403 <alias email> = <actual email>
8405 Such a file may be specified with the --aliases option, otherwise a
8407 .hgchurn file will be looked for in the working directory root.
8408 Aliases will be split from the rightmost "=".
8409 Options:
8411 -r,--rev <REV[+]>
8413 count rate for the specified revision or revset
8414 -d,--date <DATE>
8416 count rate for revisions matching date spec
8417 -t,--oldtemplate <TEMPLATE>
8419 template to group changesets (DEPRECATED)
8420 -T,--template <TEMPLATE>
8422 template to group changesets (default: {author|email})
8423 -f,--dateformat <FORMAT>
8425 strftime-compatible format for grouping by date
8426 -c, --changesets
8428 count rate by number of changesets
8429 -s, --sort
8431 sort by key (default: sort by count)
8432 --diffstat
8434 display added/removed lines separately
8435 --aliases <FILE>
8437 file with email aliases
8438 -I,--include <PATTERN[+]>
8440 include names matching the given patterns
8441 -X,--exclude <PATTERN[+]>
8443 exclude names matching the given patterns
8444 [+] marked option can be specified multiple times
8446 clonebundles
8448 advertise pre-generated bundles to seed clones
8449 "clonebundles" is a server-side extension used to advertise the exis‐
8451 tence of pre-generated, externally hosted bundle files to clients that
8452 are cloning so that cloning can be faster, more reliable, and require
8453 less resources on the server. "pullbundles" is a related feature for
8454 sending pre-generated bundle files to clients as part of pull opera‐
8455 tions.
8456 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
8458 ally, the server, in response to a client's request to clone, dynami‐
8459 cally generates a bundle containing the entire repository content and
8460 sends it to the client. There is no caching on the server and the
8461 server will have to redundantly generate the same outgoing bundle in
8462 response to each clone request. For servers with large repositories or
8463 with high clone volume, the load from clones can make scaling the
8464 server challenging and costly.
8465 This extension provides server operators the ability to offload poten‐
8467 tially expensive clone load to an external service. Pre-generated bun‐
8468 dles also allow using more CPU intensive compression, reducing the
8469 effective bandwidth requirements.
8470 Here's how clone bundles work:
8472 1. A server operator establishes a mechanism for making bundle files
8474 available on a hosting service where Mercurial clients can fetch
8475 them.
8476 2. A manifest file listing available bundle URLs and some optional
8478 metadata is added to the Mercurial repository on the server.
8479 3. A client initiates a clone against a clone bundles aware server.
8481 4. The client sees the server is advertising clone bundles and fetches
8483 the manifest listing available bundles.
8484 5. The client filters and sorts the available bundles based on what it
8486 supports and prefers.
8487 6. The client downloads and applies an available bundle from the
8489 server-specified URL.
8490 7. The client reconnects to the original server and performs the equiv‐
8492 alent of hg pull to retrieve all repository data not in the bundle.
8493 (The repository could have been updated between when the bundle was
8494 created and when the client started the clone.) This may use "pull‐
8495 bundles".
8496 Instead of the server generating full repository bundles for every
8498 clone request, it generates full bundles once and they are subsequently
8499 reused to bootstrap new clones. The server may still transfer data at
8500 clone time. However, this is only data that has been added/changed
8501 since the bundle was created. For large, established repositories, this
8502 can reduce server load for clones to less than 1% of original.
8503 Here's how pullbundles work:
8505 1. A manifest file listing available bundles and describing the revi‐
8507 sions is added to the Mercurial repository on the server.
8508 2. A new-enough client informs the server that it supports partial
8510 pulls and initiates a pull.
8511 3. If the server has pull bundles enabled and sees the client advertis‐
8513 ing partial pulls, it checks for a matching pull bundle in the mani‐
8514 fest. A bundle matches if the format is supported by the client,
8515 the client has the required revisions already and needs something
8516 from the bundle.
8517 4. If there is at least one matching bundle, the server sends it to the
8519 client.
8520 5. The client applies the bundle and notices that the server reply was
8522 incomplete. It initiates another pull.
8523 To work, this extension requires the following of server operators:
8525 · Generating bundle files of repository content (typically periodi‐
8527 cally, such as once per day).
8528 · Clone bundles: A file server that clients have network access to and
8530 that Python knows how to talk to through its normal URL handling
8531 facility (typically an HTTP/HTTPS server).
8532 · A process for keeping the bundles manifest in sync with available
8534 bundle files.
8535 Strictly speaking, using a static file hosting server isn't required: a
8537 server operator could use a dynamic service for retrieving bundle data.
8538 However, static file hosting services are simple and scalable and
8539 should be sufficient for most needs.
8540 Bundle files can be generated with the hg bundle command. Typically hg
8542 bundle --all is used to produce a bundle of the entire repository.
8543 hg debugcreatestreamclonebundle can be used to produce a special
8545 streaming clonebundle. These are bundle files that are extremely effi‐
8546 cient to produce and consume (read: fast). However, they are larger
8547 than traditional bundle formats and require that clients support the
8548 exact set of repository data store formats in use by the repository
8549 that created them. Typically, a newer server can serve data that is
8550 compatible with older clients. However, streaming clone bundles don't
8551 have this guarantee. Server operators need to be aware that newer ver‐
8552 sions of Mercurial may produce streaming clone bundles incompatible
8553 with older Mercurial versions.
8554 A server operator is responsible for creating a .hg/clonebundles.mani‐
8556 fest file containing the list of available bundle files suitable for
8557 seeding clones. If this file does not exist, the repository will not
8558 advertise the existence of clone bundles when clients connect. For pull
8559 bundles, .hg/pullbundles.manifest is used.
8560 The manifest file contains a newline (n) delimited list of entries.
8562 Each line in this file defines an available bundle. Lines have the for‐
8564 mat:
8565 <URL> [<key>=<value>[ <key>=<value>]]
8567 That is, a URL followed by an optional, space-delimited list of
8569 key=value pairs describing additional properties of this bundle. Both
8570 keys and values are URI encoded.
8571 For pull bundles, the URL is a path under the .hg directory of the
8573 repository.
8574 Keys in UPPERCASE are reserved for use by Mercurial and are defined
8576 below. All non-uppercase keys can be used by site installations. An
8577 example use for custom properties is to use the datacenter attribute to
8578 define which data center a file is hosted in. Clients could then prefer
8579 a server in the data center closest to them.
8580 The following reserved keys are currently defined:
8582 BUNDLESPEC
8584 A "bundle specification" string that describes the type of the
8585 bundle.
8586 These are string values that are accepted by the "--type" argu‐
8588 ment of hg bundle.
8589 The values are parsed in strict mode, which means they must be
8591 of the "<compression>-<type>" form. See mercu‐
8592 rial.exchange.parsebundlespec() for more details.
8593 hg debugbundle --spec can be used to print the bundle specifica‐
8595 tion string for a bundle file. The output of this command can be
8596 used verbatim for the value of BUNDLESPEC (it is already
8597 escaped).
8598 Clients will automatically filter out specifications that are
8600 unknown or unsupported so they won't attempt to download some‐
8601 thing that likely won't apply.
8602 The actual value doesn't impact client behavior beyond filter‐
8604 ing: clients will still sniff the bundle type from the header of
8605 downloaded files.
8606 Use of this key is highly recommended, as it allows clients to
8608 easily skip unsupported bundles. If this key is not defined, an
8609 old client may attempt to apply a bundle that it is incapable of
8610 reading.
8611 REQUIRESNI
8613 Whether Server Name Indication (SNI) is required to connect to
8614 the URL. SNI allows servers to use multiple certificates on the
8615 same IP. It is somewhat common in CDNs and other hosting
8616 providers. Older Python versions do not support SNI. Defining
8617 this attribute enables clients with older Python versions to
8618 filter this entry without experiencing an opaque SSL failure at
8619 connection time.
8620 If this is defined, it is important to advertise a non-SNI fall‐
8622 back URL or clients running old Python releases may not be able
8623 to clone with the clonebundles facility.
8624 Value should be "true".
8626 heads Used for pull bundles. This contains the ; separated changeset
8628 hashes of the heads of the bundle content.
8629 bases Used for pull bundles. This contains the ; separated changeset
8631 hashes of the roots of the bundle content. This can be skipped
8632 if the bundle was created without --base.
8633 Manifests can contain multiple entries. Assuming metadata is defined,
8635 clients will filter entries from the manifest that they don't support.
8636 The remaining entries are optionally sorted by client preferences
8637 (ui.clonebundleprefers config option). The client then attempts to
8638 fetch the bundle at the first URL in the remaining list.
8639 Errors when downloading a bundle will fail the entire clone operation:
8641 clients do not automatically fall back to a traditional clone. The rea‐
8642 son for this is that if a server is using clone bundles, it is probably
8643 doing so because the feature is necessary to help it scale. In other
8644 words, there is an assumption that clone load will be offloaded to
8645 another service and that the Mercurial server isn't responsible for
8646 serving this clone load. If that other service experiences issues and
8647 clients start mass falling back to the original Mercurial server, the
8648 added clone load could overwhelm the server due to unexpected load and
8649 effectively take it offline. Not having clients automatically fall back
8650 to cloning from the original server mitigates this scenario.
8651 Because there is no automatic Mercurial server fallback on failure of
8653 the bundle hosting service, it is important for server operators to
8654 view the bundle hosting service as an extension of the Mercurial server
8655 in terms of availability and service level agreements: if the bundle
8656 hosting service goes down, so does the ability for clients to clone.
8657 Note: clients will see a message informing them how to bypass the clone
8658 bundles facility when a failure occurs. So server operators should pre‐
8659 pare for some people to follow these instructions when a failure
8660 occurs, thus driving more load to the original Mercurial server when
8661 the bundle hosting service fails.
8662 closehead
8664 close arbitrary heads without checking them out first
8665 Commands
8667 close-head
8668 close the given head revisions:
8669 hg close-head [OPTION]... [REV]...
8671 This is equivalent to checking out each revision in a clean tree and
8673 running hg commit --close-branch, except that it doesn't change the
8674 working directory.
8675 The commit message must be specified with -l or -m.
8677 Options:
8679 -m,--message <TEXT>
8681 use text as commit message
8682 -l,--logfile <FILE>
8684 read commit message from file
8685 -d,--date <DATE>
8687 record the specified date as commit date
8688 -u,--user <USER>
8690 record the specified user as committer
8691 -r,--rev <REV[+]>
8693 revision to check
8694 [+] marked option can be specified multiple times
8696 aliases: close-heads
8698 commitextras
8700 adds a new flag extras to commit (ADVANCED)
8701 convert
8703 import revisions from foreign VCS repositories into Mercurial
8704 Commands
8706 convert
8707 convert a foreign SCM repository to a Mercurial one.:
8708 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
8710 Accepted source formats [identifiers]:
8712 · Mercurial [hg]
8714 · CVS [cvs]
8716 · Darcs [darcs]
8718 · git [git]
8720 · Subversion [svn]
8722 · Monotone [mtn]
8724 · GNU Arch [gnuarch]
8726 · Bazaar [bzr]
8728 · Perforce [p4]
8730 Accepted destination formats [identifiers]:
8732 · Mercurial [hg]
8734 · Subversion [svn] (history on branches is not preserved)
8736 If no revision is given, all revisions will be converted. Otherwise,
8738 convert will only import up to the named revision (given in a format
8739 understood by the source).
8740 If no destination directory name is specified, it defaults to the base‐
8742 name of the source with -hg appended. If the destination repository
8743 doesn't exist, it will be created.
8744 By default, all sources except Mercurial will use --branchsort. Mercu‐
8746 rial uses --sourcesort to preserve original revision numbers order.
8747 Sort modes have the following effects:
8748 --branchsort
8750 convert from parent to child revision when possible, which means
8751 branches are usually converted one after the other. It generates
8752 more compact repositories.
8753 --datesort
8755 sort revisions by date. Converted repositories have good-looking
8756 changelogs but are often an order of magnitude larger than the
8757 same ones generated by --branchsort.
8758 --sourcesort
8760 try to preserve source revisions order, only supported by Mercu‐
8761 rial sources.
8762 --closesort
8764 try to move closed revisions as close as possible to parent
8765 branches, only supported by Mercurial sources.
8766 If REVMAP isn't given, it will be put in a default location
8768 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
8769 maps each source commit ID to the destination ID for that revision,
8770 like so:
8771 <source ID> <destination ID>
8773 If the file doesn't exist, it's automatically created. It's updated on
8775 each commit copied, so hg convert can be interrupted and can be run
8776 repeatedly to copy new commits.
8777 The authormap is a simple text file that maps each source commit author
8779 to a destination commit author. It is handy for source SCMs that use
8780 unix logins to identify authors (e.g.: CVS). One line per author map‐
8781 ping and the line format is:
8782 source author = destination author
8784 Empty lines and lines starting with a # are ignored.
8786 The filemap is a file that allows filtering and remapping of files and
8788 directories. Each line can contain one of the following directives:
8789 include path/to/file-or-dir
8791 exclude path/to/file-or-dir
8793 rename path/to/source path/to/destination
8795 Comment lines start with #. A specified path matches if it equals the
8797 full relative name of a file or one of its parent directories. The
8798 include or exclude directive with the longest matching path applies, so
8799 line order does not matter.
8800 The include directive causes a file, or all files under a directory, to
8802 be included in the destination repository. The default if there are no
8803 include statements is to include everything. If there are any include
8804 statements, nothing else is included. The exclude directive causes
8805 files or directories to be omitted. The rename directive renames a file
8806 or directory if it is converted. To rename from a subdirectory into the
8807 root of the repository, use . as the path to rename to.
8808 --full will make sure the converted changesets contain exactly the
8810 right files with the right content. It will make a full conversion of
8811 all files, not just the ones that have changed. Files that already are
8812 correct will not be changed. This can be used to apply filemap changes
8813 when converting incrementally. This is currently only supported for
8814 Mercurial and Subversion.
8815 The splicemap is a file that allows insertion of synthetic history,
8817 letting you specify the parents of a revision. This is useful if you
8818 want to e.g. give a Subversion merge two parents, or graft two discon‐
8819 nected series of history together. Each entry contains a key, followed
8820 by a space, followed by one or two comma-separated values:
8821 key parent1, parent2
8823 The key is the revision ID in the source revision control system whose
8825 parents should be modified (same format as a key in .hg/shamap). The
8826 values are the revision IDs (in either the source or destination revi‐
8827 sion control system) that should be used as the new parents for that
8828 node. For example, if you have merged "release-1.0" into "trunk", then
8829 you should specify the revision on "trunk" as the first parent and the
8830 one on the "release-1.0" branch as the second.
8831 The branchmap is a file that allows you to rename a branch when it is
8833 being brought in from whatever external repository. When used in con‐
8834 junction with a splicemap, it allows for a powerful combination to help
8835 fix even the most badly mismanaged repositories and turn them into
8836 nicely structured Mercurial repositories. The branchmap contains lines
8837 of the form:
8838 original_branch_name new_branch_name
8840 where "original_branch_name" is the name of the branch in the source
8842 repository, and "new_branch_name" is the name of the branch is the des‐
8843 tination repository. No whitespace is allowed in the new branch name.
8844 This can be used to (for instance) move code in one repository from
8845 "default" to a named branch.
8846 Mercurial Source
8848 The Mercurial source recognizes the following configuration options,
8849 which you can set on the command line with --config:
8850 convert.hg.ignoreerrors
8852 ignore integrity errors when reading. Use it to fix Mercurial
8853 repositories with missing revlogs, by converting from and to
8854 Mercurial. Default is False.
8855 convert.hg.saverev
8857 store original revision ID in changeset (forces target IDs to
8858 change). It takes a boolean argument and defaults to False.
8859 convert.hg.startrev
8861 specify the initial Mercurial revision. The default is 0.
8862 convert.hg.revs
8864 revset specifying the source revisions to convert.
8865 Bazaar Source
8867 The following options can be used with --config:
8868 convert.bzr.saverev
8870 whether to store the original Bazaar commit ID in the metadata
8871 of the destination commit. The default is True.
8872 CVS Source
8874 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to
8875 indicate the starting point of what will be converted. Direct access to
8876 the repository files is not needed, unless of course the repository is
8877 :local:. The conversion uses the top level directory in the sandbox to
8878 find the CVS repository, and then uses CVS rlog commands to find files
8879 to convert. This means that unless a filemap is given, all files under
8880 the starting directory will be converted, and that any directory reor‐
8881 ganization in the CVS sandbox is ignored.
8882 The following options can be used with --config:
8884 convert.cvsps.cache
8886 Set to False to disable remote log caching, for testing and
8887 debugging purposes. Default is True.
8888 convert.cvsps.fuzz
8890 Specify the maximum time (in seconds) that is allowed between
8891 commits with identical user and log message in a single change‐
8892 set. When very large files were checked in as part of a change‐
8893 set then the default may not be long enough. The default is 60.
8894 convert.cvsps.logencoding
8896 Specify encoding name to be used for transcoding CVS log mes‐
8897 sages. Multiple encoding names can be specified as a list (see
8898 hg help config.Syntax), but only the first acceptable encoding
8899 in the list is used per CVS log entries. This transcoding is
8900 executed before cvslog hook below.
8901 convert.cvsps.mergeto
8903 Specify a regular expression to which commit log messages are
8904 matched. If a match occurs, then the conversion process will
8905 insert a dummy revision merging the branch on which this log
8906 message occurs to the branch indicated in the regex. Default is
8907 {{mergetobranch ([-\w]+)}}
8908 convert.cvsps.mergefrom
8910 Specify a regular expression to which commit log messages are
8911 matched. If a match occurs, then the conversion process will add
8912 the most recent revision on the branch indicated in the regex as
8913 the second parent of the changeset. Default is {{mergefrombranch
8914 ([-\w]+)}}
8915 convert.localtimezone
8917 use local time (as determined by the TZ environment variable)
8918 for changeset date/times. The default is False (use UTC).
8919 hooks.cvslog
8921 Specify a Python function to be called at the end of gathering
8922 the CVS log. The function is passed a list with the log entries,
8923 and can modify the entries in-place, or add or delete them.
8924 hooks.cvschangesets
8926 Specify a Python function to be called after the changesets are
8927 calculated from the CVS log. The function is passed a list with
8928 the changeset entries, and can modify the changesets in-place,
8929 or add or delete them.
8930 An additional "debugcvsps" Mercurial command allows the builtin change‐
8932 set merging code to be run without doing a conversion. Its parameters
8933 and output are similar to that of cvsps 2.1. Please see the command
8934 help for more details.
8935 Subversion Source
8937 Subversion source detects classical trunk/branches/tags layouts. By
8938 default, the supplied svn://repo/path/ source URL is converted as a
8939 single branch. If svn://repo/path/trunk exists it replaces the default
8940 branch. If svn://repo/path/branches exists, its subdirectories are
8941 listed as possible branches. If svn://repo/path/tags exists, it is
8942 looked for tags referencing converted branches. Default trunk, branches
8943 and tags values can be overridden with following options. Set them to
8944 paths relative to the source URL, or leave them blank to disable auto
8945 detection.
8946 The following options can be set with --config:
8948 convert.svn.branches
8950 specify the directory containing branches. The default is
8951 branches.
8952 convert.svn.tags
8954 specify the directory containing tags. The default is tags.
8955 convert.svn.trunk
8957 specify the name of the trunk branch. The default is trunk.
8958 convert.localtimezone
8960 use local time (as determined by the TZ environment variable)
8961 for changeset date/times. The default is False (use UTC).
8962 Source history can be retrieved starting at a specific revision,
8964 instead of being integrally converted. Only single branch conversions
8965 are supported.
8966 convert.svn.startrev
8968 specify start Subversion revision number. The default is 0.
8969 Git Source
8971 The Git importer converts commits from all reachable branches (refs in
8972 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
8973 are converted to bookmarks with the same name, with the leading
8974 'refs/heads' stripped. Git submodules are converted to Git subrepos in
8975 Mercurial.
8976 The following options can be set with --config:
8978 convert.git.similarity
8980 specify how similar files modified in a commit must be to be
8981 imported as renames or copies, as a percentage between 0 (dis‐
8982 abled) and 100 (files must be identical). For example, 90 means
8983 that a delete/add pair will be imported as a rename if more than
8984 90% of the file hasn't changed. The default is 50.
8985 convert.git.findcopiesharder
8987 while detecting copies, look at all files in the working copy
8988 instead of just changed ones. This is very expensive for large
8989 projects, and is only effective when convert.git.similarity is
8990 greater than 0. The default is False.
8991 convert.git.renamelimit
8993 perform rename and copy detection up to this many changed files
8994 in a commit. Increasing this will make rename and copy detection
8995 more accurate but will significantly slow down computation on
8996 large projects. The option is only relevant if convert.git.simi‐
8997 larity is greater than 0. The default is 400.
8998 convert.git.committeractions
9000 list of actions to take when processing author and committer
9001 values.
9002 Git commits have separate author (who wrote the commit) and com‐
9004 mitter (who applied the commit) fields. Not all destinations
9005 support separate author and committer fields (including Mercu‐
9006 rial). This config option controls what to do with these author
9007 and committer fields during conversion.
9008 A value of messagedifferent will append a committer: ... line
9010 to the commit message if the Git committer is different from the
9011 author. The prefix of that line can be specified using the syn‐
9012 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
9013 ter:. When a prefix is specified, a space will always be
9014 inserted between the prefix and the value.
9015 messagealways behaves like messagedifferent except it will
9017 always result in a committer: ... line being appended to the
9018 commit message. This value is mutually exclusive with messaged‐
9019 ifferent.
9020 dropcommitter will remove references to the committer. Only ref‐
9022 erences to the author will remain. Actions that add references
9023 to the committer will have no effect when this is set.
9024 replaceauthor will replace the value of the author field with
9026 the committer. Other actions that add references to the commit‐
9027 ter will still take effect when this is set.
9028 The default is messagedifferent.
9030 convert.git.extrakeys
9032 list of extra keys from commit metadata to copy to the destina‐
9033 tion. Some Git repositories store extra metadata in commits. By
9034 default, this non-default metadata will be lost during conver‐
9035 sion. Setting this config option can retain that metadata. Some
9036 built-in keys such as parent and branch are not allowed to be
9037 copied.
9038 convert.git.remoteprefix
9040 remote refs are converted as bookmarks with con‐
9041 vert.git.remoteprefix as a prefix followed by a /. The default
9042 is 'remote'.
9043 convert.git.saverev
9045 whether to store the original Git commit ID in the metadata of
9046 the destination commit. The default is True.
9047 convert.git.skipsubmodules
9049 does not convert root level .gitmodules files or files with
9050 160000 mode indicating a submodule. Default is False.
9051 Perforce Source
9053 The Perforce (P4) importer can be given a p4 depot path or a client
9054 specification as source. It will convert all files in the source to a
9055 flat Mercurial repository, ignoring labels, branches and integrations.
9056 Note that when a depot path is given you then usually should specify a
9057 target directory, because otherwise the target may be named ...-hg.
9058 The following options can be set with --config:
9060 convert.p4.encoding
9062 specify the encoding to use when decoding standard output of the
9063 Perforce command line tool. The default is default system encod‐
9064 ing.
9065 convert.p4.startrev
9067 specify initial Perforce revision (a Perforce changelist num‐
9068 ber).
9069 Mercurial Destination
9071 The Mercurial destination will recognize Mercurial subrepositories in
9072 the destination directory, and update the .hgsubstate file automati‐
9073 cally if the destination subrepositories contain the
9074 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
9075 tories requires converting a single repository at a time, from the bot‐
9076 tom up.
9077 An example showing how to convert a repository with subrepositories:
9079 # so convert knows the type when it sees a non empty destination
9081 $ hg init converted
9082 $ hg convert orig/sub1 converted/sub1
9084 $ hg convert orig/sub2 converted/sub2
9085 $ hg convert orig converted
9086 The following options are supported:
9088 convert.hg.clonebranches
9090 dispatch source branches in separate clones. The default is
9091 False.
9092 convert.hg.tagsbranch
9094 branch name for tag revisions, defaults to default.
9095 convert.hg.usebranchnames
9097 preserve branch names. The default is True.
9098 convert.hg.sourcename
9100 records the given string as a 'convert_source' extra value on
9101 each commit made in the target repository. The default is None.
9102 All Destinations
9104 All destination types accept the following options:
9105 convert.skiptags
9107 does not convert tags from the source repo to the target repo.
9108 The default is False.
9109 Options:
9111 --authors <FILE>
9113 username mapping filename (DEPRECATED) (use --authormap instead)
9114 -s,--source-type <TYPE>
9116 source repository type
9117 -d,--dest-type <TYPE>
9119 destination repository type
9120 -r,--rev <REV[+]>
9122 import up to source revision REV
9123 -A,--authormap <FILE>
9125 remap usernames using this file
9126 --filemap <FILE>
9128 remap file names using contents of file
9129 --full apply filemap changes by converting all files again
9131 --splicemap <FILE>
9133 splice synthesized history into place
9134 --branchmap <FILE>
9136 change branch names while converting
9137 --branchsort
9139 try to sort changesets by branches
9140 --datesort
9142 try to sort changesets by date
9143 --sourcesort
9145 preserve source changesets order
9146 --closesort
9148 try to reorder closed revisions
9149 [+] marked option can be specified multiple times
9151 eol
9153 automatically manage newlines in repository files
9154 This extension allows you to manage the type of line endings (CRLF or
9156 LF) that are used in the repository and in the local working directory.
9157 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
9158 thereby letting everybody use their OS native line endings.
9159 The extension reads its configuration from a versioned .hgeol configu‐
9161 ration file found in the root of the working directory. The .hgeol file
9162 use the same syntax as all other Mercurial configuration files. It uses
9163 two sections, [patterns] and [repository].
9164 The [patterns] section specifies how line endings should be converted
9166 between the working directory and the repository. The format is speci‐
9167 fied by a file pattern. The first match is used, so put more specific
9168 patterns first. The available line endings are LF, CRLF, and BIN.
9169 Files with the declared format of CRLF or LF are always checked out and
9171 stored in the repository in that format and files declared to be binary
9172 (BIN) are left unchanged. Additionally, native is an alias for checking
9173 out in the platform's default line ending: LF on Unix (including Mac OS
9174 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
9175 Mercurial's default behavior; it is only needed if you need to override
9176 a later, more general pattern.
9177 The optional [repository] section specifies the line endings to use for
9179 files stored in the repository. It has a single setting, native, which
9180 determines the storage line endings for files declared as native in the
9181 [patterns] section. It can be set to LF or CRLF. The default is LF. For
9182 example, this means that on Windows, files configured as native (CRLF
9183 by default) will be converted to LF when stored in the repository.
9184 Files declared as LF, CRLF, or BIN in the [patterns] section are always
9185 stored as-is in the repository.
9186 Example versioned .hgeol file:
9188 [patterns]
9190 **.py = native
9191 **.vcproj = CRLF
9192 **.txt = native
9193 Makefile = LF
9194 **.jpg = BIN
9195 [repository]
9197 native = LF
9198 Note The rules will first apply when files are touched in the working
9200 directory, e.g. by updating to null and back to tip to touch all
9201 files.
9202 The extension uses an optional [eol] section read from both the normal
9204 Mercurial configuration files and the .hgeol file, with the latter
9205 overriding the former. You can use that section to control the overall
9206 behavior. There are three settings:
9207 · eol.native (default os.linesep) can be set to LF or CRLF to override
9209 the default interpretation of native for checkout. This can be used
9210 with hg archive on Unix, say, to generate an archive where files have
9211 line endings for Windows.
9212 · eol.only-consistent (default True) can be set to False to make the
9214 extension convert files with inconsistent EOLs. Inconsistent means
9215 that there is both CRLF and LF present in the file. Such files are
9216 normally not touched under the assumption that they have mixed EOLs
9217 on purpose.
9218 · eol.fix-trailing-newline (default False) can be set to True to ensure
9220 that converted files end with a EOL character (either \n or \r\n as
9221 per the configured patterns).
9222 The extension provides cleverencode: and cleverdecode: filters like the
9224 deprecated win32text extension does. This means that you can disable
9225 win32text and enable eol and your filters will still work. You only
9226 need to these filters until you have prepared a .hgeol file.
9227 The win32text.forbid* hooks provided by the win32text extension have
9229 been unified into a single hook named eol.checkheadshook. The hook will
9230 lookup the expected line endings from the .hgeol file, which means you
9231 must migrate to a .hgeol file first before using the hook. eol.check‐
9232 headshook only checks heads, intermediate invalid revisions will be
9233 pushed. To forbid them completely, use the eol.checkallhook hook. These
9234 hooks are best used as pretxnchangegroup hooks.
9235 See hg help patterns for more information about the glob patterns used.
9237 extdiff
9239 command to allow external programs to compare revisions
9240 The extdiff Mercurial extension allows you to use external programs to
9242 compare revisions, or revision with working directory. The external
9243 diff programs are called with a configurable set of options and two
9244 non-option arguments: paths to directories containing snapshots of
9245 files to compare.
9246 If there is more than one file being compared and the "child" revision
9248 is the working directory, any modifications made in the external diff
9249 program will be copied back to the working directory from the temporary
9250 directory.
9251 The extdiff extension also allows you to configure new diff commands,
9253 so you do not need to type hg extdiff -p kdiff3 always.
9254 [extdiff]
9256 # add new command that runs GNU diff(1) in 'context diff' mode
9257 cdiff = gdiff -Nprc5
9258 ## or the old way:
9259 #cmd.cdiff = gdiff
9260 #opts.cdiff = -Nprc5
9261 # add new command called meld, runs meld (no need to name twice). If
9263 # the meld executable is not available, the meld tool in [merge-tools]
9264 # will be used, if available
9265 meld =
9266 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
9268 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
9269 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
9270 # your .vimrc
9271 vimdiff = gvim -f "+next" \
9272 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
9273 Tool arguments can include variables that are expanded at runtime:
9275 $parent1, $plabel1 - filename, descriptive label of first parent
9277 $child, $clabel - filename, descriptive label of child revision
9278 $parent2, $plabel2 - filename, descriptive label of second parent
9279 $root - repository root
9280 $parent is an alias for $parent1.
9281 The extdiff extension will look in your [diff-tools] and [merge-tools]
9283 sections for diff tool arguments, when none are specified in [extdiff].
9284 [extdiff]
9286 kdiff3 =
9287 [diff-tools]
9289 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9290 You can use -I/-X and list of file or directory names like normal hg
9292 diff command. The extdiff extension makes snapshots of only needed
9293 files, so running the external diff program will actually be pretty
9294 fast (at least faster than having to compare the entire tree).
9295 Commands
9297 extdiff
9298 use external program to diff repository (or selected files):
9299 hg extdiff [OPT]... [FILE]...
9301 Show differences between revisions for the specified files, using an
9303 external program. The default program used is diff, with default
9304 options "-Npru".
9305 To select a different program, use the -p/--program option. The program
9307 will be passed the names of two directories to compare. To pass addi‐
9308 tional options to the program, use -o/--option. These will be passed
9309 before the names of the directories to compare.
9310 When two revision arguments are given, then changes are shown between
9312 those revisions. If only one revision is specified then that revision
9313 is compared to the working directory, and, when no revisions are speci‐
9314 fied, the working directory files are compared to its parent.
9315 Options:
9317 -p,--program <CMD>
9319 comparison program to run
9320 -o,--option <OPT[+]>
9322 pass option to comparison program
9323 -r,--rev <REV[+]>
9325 revision
9326 -c,--change <REV>
9328 change made by revision
9329 --patch
9331 compare patches for two revisions
9332 -I,--include <PATTERN[+]>
9334 include names matching the given patterns
9335 -X,--exclude <PATTERN[+]>
9337 exclude names matching the given patterns
9338 -S, --subrepos
9340 recurse into subrepositories
9341 [+] marked option can be specified multiple times
9343 factotum
9345 http authentication with factotum
9346 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
9348 platforms to provide authentication information for HTTP access. Con‐
9349 figuration entries specified in the auth section as well as authentica‐
9350 tion information provided in the repository URL are fully supported. If
9351 no prefix is specified, a value of "*" will be assumed.
9352 By default, keys are specified as:
9354 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
9356 If the factotum extension is unable to read the required key, one will
9358 be requested interactively.
9359 A configuration section is available to customize runtime behavior. By
9361 default, these entries are:
9362 [factotum]
9364 executable = /bin/auth/factotum
9365 mountpoint = /mnt/factotum
9366 service = hg
9367 The executable entry defines the full path to the factotum binary. The
9369 mountpoint entry defines the path to the factotum file service. Lastly,
9370 the service entry controls the service name used when reading keys.
9371 fastannotate
9373 yet another annotate implementation that might be faster (EXPERIMENTAL)
9374 The fastannotate extension provides a 'fastannotate' command that makes
9376 use of the linelog data structure as a cache layer and is expected to
9377 be faster than the vanilla 'annotate' if the cache is present.
9378 In most cases, fastannotate requires a setup that mainbranch is some
9380 pointer that always moves forward, to be most efficient.
9381 Using fastannotate together with linkrevcache would speed up building
9383 the annotate cache greatly. Run "debugbuildlinkrevcache" before "debug‐
9384 buildannotatecache".
9385 [fastannotate]
9387 # specify the main branch head. the internal linelog will only contain
9388 # the linear (ignoring p2) "mainbranch". since linelog cannot move
9389 # backwards without a rebuild, this should be something that always moves
9390 # forward, usually it is "master" or "@".
9391 mainbranch = master
9392 # fastannotate supports different modes to expose its feature.
9394 # a list of combination:
9395 # - fastannotate: expose the feature via the "fastannotate" command which
9396 # deals with everything in a most efficient way, and provides extra
9397 # features like --deleted etc.
9398 # - fctx: replace fctx.annotate implementation. note:
9399 # a. it is less efficient than the "fastannotate" command
9400 # b. it will make it practically impossible to access the old (disk
9401 # side-effect free) annotate implementation
9402 # c. it implies "hgweb".
9403 # - hgweb: replace hgweb's annotate implementation. conflict with "fctx".
9404 # (default: fastannotate)
9405 modes = fastannotate
9406 # default format when no format flags are used (default: number)
9408 defaultformat = changeset, user, date
9409 # serve the annotate cache via wire protocol (default: False)
9411 # tip: the .hg/fastannotate directory is portable - can be rsynced
9412 server = True
9413 # build annotate cache on demand for every client request (default: True)
9415 # disabling it could make server response faster, useful when there is a
9416 # cronjob building the cache.
9417 serverbuildondemand = True
9418 # update local annotate cache from remote on demand
9420 client = False
9421 # path to use when connecting to the remote server (default: default)
9423 remotepath = default
9424 # minimal length of the history of a file required to fetch linelog from
9426 # the server. (default: 10)
9427 clientfetchthreshold = 10
9428 # use flock instead of the file existence lock
9430 # flock may not work well on some network filesystems, but they avoid
9431 # creating and deleting files frequently, which is faster when updating
9432 # the annotate cache in batch. if you have issues with this option, set it
9433 # to False. (default: True if flock is supported, False otherwise)
9434 useflock = True
9435 # for "fctx" mode, always follow renames regardless of command line option.
9437 # this is a BC with the original command but will reduced the space needed
9438 # for annotate cache, and is useful for client-server setup since the
9439 # server will only provide annotate cache with default options (i.e. with
9440 # follow). do not affect "fastannotate" mode. (default: True)
9441 forcefollow = True
9442 # for "fctx" mode, always treat file as text files, to skip the "isbinary"
9444 # check. this is consistent with the "fastannotate" command and could help
9445 # to avoid a file fetch if remotefilelog is used. (default: True)
9446 forcetext = True
9447 # use unfiltered repo for better performance.
9449 unfilteredrepo = True
9450 # sacrifice correctness in some corner cases for performance. it does not
9452 # affect the correctness of the annotate cache being built. the option
9453 # is experimental and may disappear in the future (default: False)
9454 perfhack = True
9455 Commands
9457 fetch
9458 pull, update and merge in one command (DEPRECATED)
9459 Commands
9461 fetch
9462 pull changes from a remote repository, merge new changes if needed.:
9463 hg fetch [SOURCE]
9465 This finds all changes from the repository at the specified path or URL
9467 and adds them to the local repository.
9468 If the pulled changes add a new branch head, the head is automatically
9470 merged, and the result of the merge is committed. Otherwise, the work‐
9471 ing directory is updated to include the new changes.
9472 When a merge is needed, the working directory is first updated to the
9474 newly pulled changes. Local changes are then merged into the pulled
9475 changes. To switch the merge order, use --switch-parent.
9476 See hg help dates for a list of formats valid for -d/--date.
9478 Returns 0 on success.
9480 Options:
9482 -r,--rev <REV[+]>
9484 a specific revision you would like to pull
9485 --edit invoke editor on commit messages
9487 --force-editor
9489 edit commit message (DEPRECATED)
9490 --switch-parent
9492 switch parents when merging
9493 -m,--message <TEXT>
9495 use text as commit message
9496 -l,--logfile <FILE>
9498 read commit message from file
9499 -d,--date <DATE>
9501 record the specified date as commit date
9502 -u,--user <USER>
9504 record the specified user as committer
9505 -e,--ssh <CMD>
9507 specify ssh command to use
9508 --remotecmd <CMD>
9510 specify hg command to run on the remote side
9511 --insecure
9513 do not verify server certificate (ignoring web.cacerts config)
9514 [+] marked option can be specified multiple times
9516 fix
9518 rewrite file content in changesets or working copy (EXPERIMENTAL)
9519 Provides a command that runs configured tools on the contents of modi‐
9521 fied files, writing back any fixes to the working copy or replacing
9522 changesets.
9523 Here is an example configuration that causes hg fix to apply automatic
9525 formatting fixes to modified lines in C++ code:
9526 [fix]
9528 clang-format:command=clang-format --assume-filename={rootpath}
9529 clang-format:linerange=--lines={first}:{last}
9530 clang-format:pattern=set:**.cpp or **.hpp
9531 The :command suboption forms the first part of the shell command that
9533 will be used to fix a file. The content of the file is passed on stan‐
9534 dard input, and the fixed file content is expected on standard output.
9535 Any output on standard error will be displayed as a warning. If the
9536 exit status is not zero, the file will not be affected. A placeholder
9537 warning is displayed if there is a non-zero exit status but no standard
9538 error output. Some values may be substituted into the command:
9539 {rootpath} The path of the file being fixed, relative to the repo root
9541 {basename} The name of the file being fixed, without the directory path
9542 If the :linerange suboption is set, the tool will only be run if there
9544 are changed lines in a file. The value of this suboption is appended to
9545 the shell command once for every range of changed lines in the file.
9546 Some values may be substituted into the command:
9547 {first} The 1-based line number of the first line in the modified range
9549 {last} The 1-based line number of the last line in the modified range
9550 The :pattern suboption determines which files will be passed through
9552 each configured tool. See hg help patterns for possible values. If
9553 there are file arguments to hg fix, the intersection of these patterns
9554 is used.
9555 There is also a configurable limit for the maximum size of file that
9557 will be processed by hg fix:
9558 [fix]
9560 maxfilesize = 2MB
9561 Normally, execution of configured tools will continue after a failure
9563 (indicated by a non-zero exit status). It can also be configured to
9564 abort after the first such failure, so that no files will be affected
9565 if any tool fails. This abort will also cause hg fix to exit with a
9566 non-zero status:
9567 [fix]
9569 failure = abort
9570 When multiple tools are configured to affect a file, they execute in an
9572 order defined by the :priority suboption. The priority suboption has a
9573 default value of zero for each tool. Tools are executed in order of
9574 descending priority. The execution order of tools with equal priority
9575 is unspecified. For example, you could use the 'sort' and 'head' utili‐
9576 ties to keep only the 10 smallest numbers in a text file by ensuring
9577 that 'sort' runs before 'head':
9578 [fix]
9580 sort:command = sort -n
9581 head:command = head -n 10
9582 sort:pattern = numbers.txt
9583 head:pattern = numbers.txt
9584 sort:priority = 2
9585 head:priority = 1
9586 To account for changes made by each tool, the line numbers used for
9588 incremental formatting are recomputed before executing the next tool.
9589 So, each tool may see different values for the arguments added by the
9590 :linerange suboption.
9591 Commands
9593 fix
9594 rewrite file content in changesets or working directory:
9595 hg fix [OPTION]... [FILE]...
9597 Runs any configured tools to fix the content of files. Only affects
9599 files with changes, unless file arguments are provided. Only affects
9600 changed lines of files, unless the --whole flag is used. Some tools may
9601 always affect the whole file regardless of --whole.
9602 If revisions are specified with --rev, those revisions will be checked,
9604 and they may be replaced with new revisions that have fixed file con‐
9605 tent. It is desirable to specify all descendants of each specified
9606 revision, so that the fixes propagate to the descendants. If all
9607 descendants are fixed at the same time, no merging, rebasing, or evolu‐
9608 tion will be required.
9609 If --working-dir is used, files with uncommitted changes in the working
9611 copy will be fixed. If the checked-out revision is also fixed, the
9612 working directory will update to the replacement revision.
9613 When determining what lines of each file to fix at each revision, the
9615 whole set of revisions being fixed is considered, so that fixes to ear‐
9616 lier revisions are not forgotten in later ones. The --base flag can be
9617 used to override this default behavior, though it is not usually desir‐
9618 able to do so.
9619 Options:
9621 --all fix all non-public non-obsolete revisions
9623 --base <REV[+]>
9625 revisions to diff against (overrides automatic selection, and
9626 applies to every revision being fixed)
9627 -r,--rev <REV[+]>
9629 revisions to fix
9630 -w, --working-dir
9632 fix the working directory
9633 --whole
9635 always fix every line of a file
9636 [+] marked option can be specified multiple times
9638 fsmonitor
9640 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
9641 Integrates the file-watching program Watchman with Mercurial to produce
9643 faster status results.
9644 On a particular Linux system, for a real-world repository with over
9646 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
9647 the same system, with fsmonitor it takes about 0.3 seconds.
9648 fsmonitor requires no configuration -- it will tell Watchman about your
9650 repository as necessary. You'll need to install Watchman from
9651 https://facebook.github.io/watchman/ and make sure it is in your PATH.
9652 fsmonitor is incompatible with the largefiles and eol extensions, and
9654 will disable itself if any of those are active.
9655 The following configuration options exist:
9657 [fsmonitor]
9659 mode = {off, on, paranoid}
9660 When mode = off, fsmonitor will disable itself (similar to not loading
9662 the extension at all). When mode = on, fsmonitor will be enabled (the
9663 default). When mode = paranoid, fsmonitor will query both Watchman and
9664 the filesystem, and ensure that the results are consistent.
9665 [fsmonitor]
9667 timeout = (float)
9668 A value, in seconds, that determines how long fsmonitor will wait for
9670 Watchman to return results. Defaults to 2.0.
9671 [fsmonitor]
9673 blacklistusers = (list of userids)
9674 A list of usernames for which fsmonitor will disable itself altogether.
9676 [fsmonitor]
9678 walk_on_invalidate = (boolean)
9679 Whether or not to walk the whole repo ourselves when our cached state
9681 has been invalidated, for example when Watchman has been restarted or
9682 .hgignore rules have been changed. Walking the repo in that case can
9683 result in competing for I/O with Watchman. For large repos it is recom‐
9684 mended to set this value to false. You may wish to set this to true if
9685 you have a very fast filesystem that can outpace the IPC overhead of
9686 getting the result data for the full repo from Watchman. Defaults to
9687 false.
9688 [fsmonitor]
9690 warn_when_unused = (boolean)
9691 Whether to print a warning during certain operations when fsmonitor
9693 would be beneficial to performance but isn't enabled.
9694 [fsmonitor]
9696 warn_update_file_count = (integer)
9697 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
9699 be printed during working directory updates if this many files will be
9700 created.
9701 githelp
9703 try mapping git commands to Mercurial commands
9704 Tries to map a given git command to a Mercurial command:
9706 $ hg githelp -- git checkout master hg update master
9708 If an unknown command or parameter combination is detected, an error is
9710 produced.
9711 Commands
9713 githelp
9714 suggests the Mercurial equivalent of the given git command:
9715 hg githelp
9717 Usage: hg githelp -- <git command>
9719 aliases: git
9721 gpg
9723 commands to sign and verify changesets
9724 Commands
9726 sigcheck
9727 verify all the signatures there may be for a particular revision:
9728 hg sigcheck REV
9730 verify all the signatures there may be for a particular revision
9732 sign
9734 add a signature for the current or given revision:
9735 hg sign [OPTION]... [REV]...
9737 If no revision is given, the parent of the working directory is used,
9739 or tip if no revision is checked out.
9740 The gpg.cmd config setting can be used to specify the command to run. A
9742 default key can be specified with gpg.key.
9743 See hg help dates for a list of formats valid for -d/--date.
9745 Options:
9747 -l, --local
9749 make the signature local
9750 -f, --force
9752 sign even if the sigfile is modified
9753 --no-commit
9755 do not commit the sigfile after signing
9756 -k,--key <ID>
9758 the key id to sign with
9759 -m,--message <TEXT>
9761 use text as commit message
9762 -e, --edit
9764 invoke editor on commit messages
9765 -d,--date <DATE>
9767 record the specified date as commit date
9768 -u,--user <USER>
9770 record the specified user as committer
9771 sigs
9773 list signed changesets:
9774 hg sigs
9776 list signed changesets
9778 graphlog
9780 command to view revision graphs from a shell (DEPRECATED)
9781 The functionality of this extension has been include in core Mercurial
9783 since version 2.3. Please use hg log -G ... instead.
9784 This extension adds a --graph option to the incoming, outgoing and log
9786 commands. When this options is given, an ASCII representation of the
9787 revision graph is also shown.
9788 Commands
9790 glog
9791 show revision history alongside an ASCII revision graph:
9792 hg glog [OPTION]... [FILE]
9794 Print a revision history alongside a revision graph drawn with ASCII
9796 characters.
9797 Nodes printed as an @ character are parents of the working directory.
9799 This is an alias to hg log -G.
9801 Options:
9803 -f, --follow
9805 follow changeset history, or file history across copies and
9806 renames
9807 --follow-first
9809 only follow the first parent of merge changesets (DEPRECATED)
9810 -d,--date <DATE>
9812 show revisions matching date spec
9813 -C, --copies
9815 show copied files
9816 -k,--keyword <TEXT[+]>
9818 do case-insensitive search for a given text
9819 -r,--rev <REV[+]>
9821 show the specified revision or revset
9822 --removed
9824 include revisions where files were removed
9825 -m, --only-merges
9827 show only merges (DEPRECATED)
9828 -u,--user <USER[+]>
9830 revisions committed by user
9831 --only-branch <BRANCH[+]>
9833 show only changesets within the given named branch (DEPRECATED)
9834 -b,--branch <BRANCH[+]>
9836 show changesets within the given named branch
9837 -P,--prune <REV[+]>
9839 do not display revision or any of its ancestors
9840 -p, --patch
9842 show patch
9843 -g, --git
9845 use git extended diff format
9846 -l,--limit <NUM>
9848 limit number of changes displayed
9849 -M, --no-merges
9851 do not show merges
9852 --stat output diffstat-style summary of changes
9854 -G, --graph
9856 show the revision DAG
9857 --style <STYLE>
9859 display using template map file (DEPRECATED)
9860 -T,--template <TEMPLATE>
9862 display with template
9863 -I,--include <PATTERN[+]>
9865 include names matching the given patterns
9866 -X,--exclude <PATTERN[+]>
9868 exclude names matching the given patterns
9869 [+] marked option can be specified multiple times
9871 hgk
9873 browse the repository in a graphical way
9874 The hgk extension allows browsing the history of a repository in a
9876 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
9877 distributed with Mercurial.)
9878 hgk consists of two parts: a Tcl script that does the displaying and
9880 querying of information, and an extension to Mercurial named hgk.py,
9881 which provides hooks for hgk to get information. hgk can be found in
9882 the contrib directory, and the extension is shipped in the hgext repos‐
9883 itory, and needs to be enabled.
9884 The hg view command will launch the hgk Tcl script. For this command to
9886 work, hgk must be in your search path. Alternately, you can specify the
9887 path to hgk in your configuration file:
9888 [hgk]
9890 path = /location/of/hgk
9891 hgk can make use of the extdiff extension to visualize revisions.
9893 Assuming you had already configured extdiff vdiff command, just add:
9894 [hgk]
9896 vdiff=vdiff
9897 Revisions context menu will now display additional entries to fire
9899 vdiff on hovered and selected revisions.
9900 Commands
9902 view
9903 start interactive history viewer:
9904 hg view [-l LIMIT] [REVRANGE]
9906 start interactive history viewer
9908 Options:
9910 -l,--limit <NUM>
9912 limit number of changes displayed
9913 highlight
9915 syntax highlighting for hgweb (requires Pygments)
9916 It depends on the Pygments syntax highlighting library:
9918 http://pygments.org/
9919 There are the following configuration options:
9921 [web]
9923 pygments_style = <style> (default: colorful)
9924 highlightfiles = <fileset> (default: size('<5M'))
9925 highlightonlymatchfilename = <bool> (default False)
9926 highlightonlymatchfilename will only highlight files if their type
9928 could be identified by their filename. When this is not enabled (the
9929 default), Pygments will try very hard to identify the file type from
9930 content and any match (even matches with a low confidence score) will
9931 be used.
9932 histedit
9934 interactive history editing
9935 With this extension installed, Mercurial gains one new command: histe‐
9937 dit. Usage is as follows, assuming the following history:
9938 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
9940 | Add delta
9941 |
9942 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
9943 | Add gamma
9944 |
9945 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
9946 | Add beta
9947 |
9948 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
9949 Add alpha
9950 If you were to run hg histedit c561b4e977df, you would see the follow‐
9952 ing file open in your editor:
9953 pick c561b4e977df Add beta
9955 pick 030b686bedc4 Add gamma
9956 pick 7c2fd3b9020c Add delta
9957 # Edit history between c561b4e977df and 7c2fd3b9020c
9959 #
9960 # Commits are listed from least to most recent
9961 #
9962 # Commands:
9963 # p, pick = use commit
9964 # e, edit = use commit, but stop for amending
9965 # f, fold = use commit, but combine it with the one above
9966 # r, roll = like fold, but discard this commit's description and date
9967 # d, drop = remove commit from history
9968 # m, mess = edit commit message without changing commit content
9969 # b, base = checkout changeset and apply further changesets from there
9970 #
9971 In this file, lines beginning with # are ignored. You must specify a
9973 rule for each revision in your history. For example, if you had meant
9974 to add gamma before beta, and then wanted to add delta in the same
9975 revision as beta, you would reorganize the file to look like this:
9976 pick 030b686bedc4 Add gamma
9978 pick c561b4e977df Add beta
9979 fold 7c2fd3b9020c Add delta
9980 # Edit history between c561b4e977df and 7c2fd3b9020c
9982 #
9983 # Commits are listed from least to most recent
9984 #
9985 # Commands:
9986 # p, pick = use commit
9987 # e, edit = use commit, but stop for amending
9988 # f, fold = use commit, but combine it with the one above
9989 # r, roll = like fold, but discard this commit's description and date
9990 # d, drop = remove commit from history
9991 # m, mess = edit commit message without changing commit content
9992 # b, base = checkout changeset and apply further changesets from there
9993 #
9994 At which point you close the editor and histedit starts working. When
9996 you specify a fold operation, histedit will open an editor when it
9997 folds those revisions together, offering you a chance to clean up the
9998 commit message:
9999 Add beta
10001 ***
10002 Add delta
10003 Edit the commit message to your liking, then close the editor. The date
10005 used for the commit will be the later of the two commits' dates. For
10006 this example, let's assume that the commit message was changed to Add
10007 beta and delta. After histedit has run and had a chance to remove any
10008 old or temporary revisions it needed, the history looks like this:
10009 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
10011 | Add beta and delta.
10012 |
10013 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10014 | Add gamma
10015 |
10016 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10017 Add alpha
10018 Note that histedit does not remove any revisions (even its own tempo‐
10020 rary ones) until after it has completed all the editing operations, so
10021 it will probably perform several strip operations when it's done. For
10022 the above example, it had to run strip twice. Strip can be slow depend‐
10023 ing on a variety of factors, so you might need to be a little patient.
10024 You can choose to keep the original revisions by passing the --keep
10025 flag.
10026 The edit operation will drop you back to a command prompt, allowing you
10028 to edit files freely, or even use hg record to commit some changes as a
10029 separate commit. When you're done, any remaining uncommitted changes
10030 will be committed as well. When done, run hg histedit --continue to
10031 finish this step. If there are uncommitted changes, you'll be prompted
10032 for a new commit message, but the default commit message will be the
10033 original message for the edit ed revision, and the date of the original
10034 commit will be preserved.
10035 The message operation will give you a chance to revise a commit message
10037 without changing the contents. It's a shortcut for doing edit immedi‐
10038 ately followed by hg histedit --continue`.
10039 If histedit encounters a conflict when moving a revision (while han‐
10041 dling pick or fold), it'll stop in a similar manner to edit with the
10042 difference that it won't prompt you for a commit message when done. If
10043 you decide at this point that you don't like how much work it will be
10044 to rearrange history, or that you made a mistake, you can use hg histe‐
10045 dit --abort to abandon the new changes you have made and return to the
10046 state before you attempted to edit your history.
10047 If we clone the histedit-ed example repository above and add four more
10049 changes, such that we have the following history:
10050 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
10052 | Add theta
10053 |
10054 o 5 140988835471 2009-04-27 18:04 -0500 stefan
10055 | Add eta
10056 |
10057 o 4 122930637314 2009-04-27 18:04 -0500 stefan
10058 | Add zeta
10059 |
10060 o 3 836302820282 2009-04-27 18:04 -0500 stefan
10061 | Add epsilon
10062 |
10063 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
10064 | Add beta and delta.
10065 |
10066 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10067 | Add gamma
10068 |
10069 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10070 Add alpha
10071 If you run hg histedit --outgoing on the clone then it is the same as
10073 running hg histedit 836302820282. If you need plan to push to a reposi‐
10074 tory that Mercurial does not detect to be related to the source repo,
10075 you can add a --force option.
10076 Config
10078 Histedit rule lines are truncated to 80 characters by default. You can
10079 customize this behavior by setting a different length in your configu‐
10080 ration file:
10081 [histedit]
10083 linelen = 120 # truncate rule lines at 120 characters
10084 hg histedit attempts to automatically choose an appropriate base revi‐
10086 sion to use. To change which base revision is used, define a revset in
10087 your configuration file:
10088 [histedit]
10090 defaultrev = only(.) & draft()
10091 By default each edited revision needs to be present in histedit com‐
10093 mands. To remove revision you need to use drop operation. You can con‐
10094 figure the drop to be implicit for missing commits by adding:
10095 [histedit]
10097 dropmissing = True
10098 By default, histedit will close the transaction after each action. For
10100 performance purposes, you can configure histedit to use a single trans‐
10101 action across the entire histedit. WARNING: This setting introduces a
10102 significant risk of losing the work you've done in a histedit if the
10103 histedit aborts unexpectedly:
10104 [histedit]
10106 singletransaction = True
10107 Commands
10109 histedit
10110 interactively edit changeset history:
10111 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
10113 This command lets you edit a linear series of changesets (up to and
10115 including the working directory, which should be clean). You can:
10116 · pick to [re]order a changeset
10118 · drop to omit changeset
10120 · mess to reword the changeset commit message
10122 · fold to combine it with the preceding changeset (using the later
10124 date)
10125 · roll like fold, but discarding this commit's description and date
10127 · edit to edit this changeset (preserving date)
10129 · base to checkout changeset and apply further changesets from there
10131 There are a number of ways to select the root changeset:
10133 · Specify ANCESTOR directly
10135 · Use --outgoing -- it will be the first linear changeset not included
10137 in destination. (See hg help config.paths.default-push)
10138 · Otherwise, the value from the "histedit.defaultrev" config option is
10140 used as a revset to select the base revision when ANCESTOR is not
10141 specified. The first revision returned by the revset is used. By
10142 default, this selects the editable history that is unique to the
10143 ancestry of the working directory.
10144 If you use --outgoing, this command will abort if there are ambiguous
10146 outgoing revisions. For example, if there are multiple branches con‐
10147 taining outgoing revisions.
10148 Use "min(outgoing() and ::.)" or similar revset specification instead
10150 of --outgoing to specify edit target revision exactly in such ambiguous
10151 situation. See hg help revsets for detail about selecting revisions.
10152 Examples:
10154 · A number of changes have been made. Revision 3 is no longer
10156 needed.
10157 Start history editing from revision 3:
10159 hg histedit -r 3
10161 An editor opens, containing the list of revisions, with specific
10163 actions specified:
10164 pick 5339bf82f0ca 3 Zworgle the foobar
10166 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10167 pick 0a9639fcda9d 5 Morgify the cromulancy
10168 Additional information about the possible actions to take appears
10170 below the list of revisions.
10171 To remove revision 3 from the history, its action (at the begin‐
10173 ning of the relevant line) is changed to 'drop':
10174 drop 5339bf82f0ca 3 Zworgle the foobar
10176 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10177 pick 0a9639fcda9d 5 Morgify the cromulancy
10178 · A number of changes have been made. Revision 2 and 4 need to be
10180 swapped.
10181 Start history editing from revision 2:
10183 hg histedit -r 2
10185 An editor opens, containing the list of revisions, with specific
10187 actions specified:
10188 pick 252a1af424ad 2 Blorb a morgwazzle
10190 pick 5339bf82f0ca 3 Zworgle the foobar
10191 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10192 To swap revision 2 and 4, its lines are swapped in the editor:
10194 pick 8ef592ce7cc4 4 Bedazzle the zerlog
10196 pick 5339bf82f0ca 3 Zworgle the foobar
10197 pick 252a1af424ad 2 Blorb a morgwazzle
10198 Returns 0 on success, 1 if user intervention is required (not only for
10200 intentional "edit" command, but also for resolving unexpected con‐
10201 flicts).
10202 Options:
10204 --commands <FILE>
10206 read history edits from the specified file
10207 -c, --continue
10209 continue an edit already in progress
10210 --edit-plan
10212 edit remaining actions list
10213 -k, --keep
10215 don't strip old nodes after edit is complete
10216 --abort
10218 abort an edit in progress
10219 -o, --outgoing
10221 changesets not found in destination
10222 -f, --force
10224 force outgoing even for unrelated repositories
10225 -r,--rev <REV[+]>
10227 first revision to be edited
10228 -T,--template <TEMPLATE>
10230 display with template
10231 [+] marked option can be specified multiple times
10233 infinitepush
10235 store some pushes in a remote blob store on the server (EXPERIMEN‐
10236 TAL)
10237 [infinitepush] # Server-side and client-side option. Pattern of
10239 the infinitepush bookmark branchpattern = PATTERN
10240 # Server or client server = False
10242 # Server-side option. Possible values: 'disk' or 'sql'. Fails if
10244 not set indextype = disk
10245 # Server-side option. Used only if indextype=sql. # Format:
10247 'IP:PORT:DB_NAME:USER:PASSWORD' sqlhost =
10248 IP:PORT:DB_NAME:USER:PASSWORD
10249 # Server-side option. Used only if indextype=disk. # Filesystem
10251 path to the index store indexpath = PATH
10252 # Server-side option. Possible values: 'disk' or 'external' #
10254 Fails if not set storetype = disk
10255 # Server-side option. # Path to the binary that will save bun‐
10257 dle to the bundlestore # Formatted cmd line will be passed to it
10258 (see put_args) put_binary = put
10259 # Serser-side option. Used only if storetype=external. # Format
10261 cmd-line string for put binary. Placeholder: {filename} put_args
10262 = {filename}
10263 # Server-side option. # Path to the binary that get bundle from
10265 the bundlestore. # Formatted cmd line will be passed to it (see
10266 get_args) get_binary = get
10267 # Serser-side option. Used only if storetype=external. # Format
10269 cmd-line string for get binary. Placeholders: {filename} {han‐
10270 dle} get_args = {filename} {handle}
10271 # Server-side option logfile = FIlE
10273 # Server-side option loglevel = DEBUG
10275 # Server-side option. Used only if indextype=sql. # Sets mysql
10277 wait_timeout option. waittimeout = 300
10278 # Server-side option. Used only if indextype=sql. # Sets mysql
10280 innodb_lock_wait_timeout option. locktimeout = 120
10281 # Server-side option. Used only if indextype=sql. # Name of the
10283 repository reponame = ''
10284 # Client-side option. Used by --list-remote option. List of
10286 remote scratch # patterns to list if no patterns are specified.
10287 defaultremotepatterns = ['*']
10288 # Instructs infinitepush to forward all received bundle2 parts
10290 to the # bundle for storage. Defaults to False. storeallparts =
10291 True
10292 # routes each incoming push to the bundlestore. defaults to
10294 False pushtobundlestore = True
10295 [remotenames] # Client-side option # This option should be set
10297 only if remotenames extension is enabled. # Whether remote
10298 bookmarks are tracked by remotenames extension. bookmarks =
10299 True
10300 journal
10302 track previous positions of bookmarks (EXPERIMENTAL)
10303 This extension adds a new command: hg journal, which shows you where
10305 bookmarks were previously located.
10306 Commands
10308 journal
10309 show the previous position of bookmarks and the working copy:
10310 hg journal [OPTION]... [BOOKMARKNAME]
10312 The journal is used to see the previous commits that bookmarks and the
10314 working copy pointed to. By default the previous locations for the
10315 working copy. Passing a bookmark name will show all the previous posi‐
10316 tions of that bookmark. Use the --all switch to show previous locations
10317 for all bookmarks and the working copy; each line will then include the
10318 bookmark name, or '.' for the working copy, as well.
10319 If name starts with re:, the remainder of the name is treated as a reg‐
10321 ular expression. To match a name that actually starts with re:, use the
10322 prefix literal:.
10323 By default hg journal only shows the commit hash and the command that
10325 was running at that time. -v/--verbose will show the prior hash, the
10326 user, and the time at which it happened.
10327 Use -c/--commits to output log information on each commit hash; at this
10329 point you can use the usual --patch, --git, --stat and --template
10330 switches to alter the log output for these.
10331 hg journal -T json can be used to produce machine readable output.
10333 Options:
10335 --all show history for all names
10337 -c, --commits
10339 show commit metadata
10340 -p, --patch
10342 show patch
10343 -g, --git
10345 use git extended diff format
10346 -l,--limit <NUM>
10348 limit number of changes displayed
10349 --stat output diffstat-style summary of changes
10351 --style <STYLE>
10353 display using template map file (DEPRECATED)
10354 -T,--template <TEMPLATE>
10356 display with template
10357 keyword
10359 expand keywords in tracked files
10360 This extension expands RCS/CVS-like or self-customized $Keywords$ in
10362 tracked text files selected by your configuration.
10363 Keywords are only expanded in local repositories and not stored in the
10365 change history. The mechanism can be regarded as a convenience for the
10366 current user or for archive distribution.
10367 Keywords expand to the changeset data pertaining to the latest change
10369 relative to the working directory parent of each file.
10370 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
10372 sections of hgrc files.
10373 Example:
10375 [keyword]
10377 # expand keywords in every python file except those matching "x*"
10378 **.py =
10379 x* = ignore
10380 [keywordset]
10382 # prefer svn- over cvs-like default keywordmaps
10383 svn = True
10384 Note The more specific you are in your filename patterns the less you
10386 lose speed in huge repositories.
10387 For [keywordmaps] template mapping and expansion demonstration and con‐
10389 trol run hg kwdemo. See hg help templates for a list of available tem‐
10390 plates and filters.
10391 Three additional date template filters are provided:
10393 utcdate
10395 "2006/09/18 15:13:13"
10397 svnutcdate
10399 "2006-09-18 15:13:13Z"
10401 svnisodate
10403 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
10405 The default template mappings (view with hg kwdemo -d) can be replaced
10407 with customized keywords and templates. Again, run hg kwdemo to control
10408 the results of your configuration changes.
10409 Before changing/disabling active keywords, you must run hg kwshrink to
10411 avoid storing expanded keywords in the change history.
10412 To force expansion after enabling it, or a configuration change, run hg
10414 kwexpand.
10415 Expansions spanning more than one line and incremental expansions, like
10417 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
10418 expands to the first line of the changeset description.
10419 Commands
10421 kwdemo
10422 print [keywordmaps] configuration and an expansion example:
10423 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
10425 Show current, custom, or default keyword template maps and their expan‐
10427 sions.
10428 Extend the current configuration by specifying maps as arguments and
10430 using -f/--rcfile to source an external hgrc file.
10431 Use -d/--default to disable current configuration.
10433 See hg help templates for information on templates and filters.
10435 Options:
10437 -d, --default
10439 show default keyword template maps
10440 -f,--rcfile <FILE>
10442 read maps from rcfile
10443 kwexpand
10445 expand keywords in the working directory:
10446 hg kwexpand [OPTION]... [FILE]...
10448 Run after (re)enabling keyword expansion.
10450 kwexpand refuses to run if given files contain local changes.
10452 Options:
10454 -I,--include <PATTERN[+]>
10456 include names matching the given patterns
10457 -X,--exclude <PATTERN[+]>
10459 exclude names matching the given patterns
10460 [+] marked option can be specified multiple times
10462 kwfiles
10464 show files configured for keyword expansion:
10465 hg kwfiles [OPTION]... [FILE]...
10467 List which files in the working directory are matched by the [keyword]
10469 configuration patterns.
10470 Useful to prevent inadvertent keyword expansion and to speed up execu‐
10472 tion by including only files that are actual candidates for expansion.
10473 See hg help keyword on how to construct patterns both for inclusion and
10475 exclusion of files.
10476 With -A/--all and -v/--verbose the codes used to show the status of
10478 files are:
10479 K = keyword expansion candidate
10481 k = keyword expansion candidate (not tracked)
10482 I = ignored
10483 i = ignored (not tracked)
10484 Options:
10486 -A, --all
10488 show keyword status flags of all files
10489 -i, --ignore
10491 show files excluded from expansion
10492 -u, --unknown
10494 only show unknown (not tracked) files
10495 -I,--include <PATTERN[+]>
10497 include names matching the given patterns
10498 -X,--exclude <PATTERN[+]>
10500 exclude names matching the given patterns
10501 [+] marked option can be specified multiple times
10503 kwshrink
10505 revert expanded keywords in the working directory:
10506 hg kwshrink [OPTION]... [FILE]...
10508 Must be run before changing/disabling active keywords.
10510 kwshrink refuses to run if given files contain local changes.
10512 Options:
10514 -I,--include <PATTERN[+]>
10516 include names matching the given patterns
10517 -X,--exclude <PATTERN[+]>
10519 exclude names matching the given patterns
10520 [+] marked option can be specified multiple times
10522 largefiles
10524 track large binary files
10525 Large binary files tend to be not very compressible, not very diffable,
10527 and not at all mergeable. Such files are not handled efficiently by
10528 Mercurial's storage format (revlog), which is based on compressed
10529 binary deltas; storing large binary files as regular Mercurial files
10530 wastes bandwidth and disk space and increases Mercurial's memory usage.
10531 The largefiles extension addresses these problems by adding a central‐
10532 ized client-server layer on top of Mercurial: largefiles live in a cen‐
10533 tral store out on the network somewhere, and you only fetch the revi‐
10534 sions that you need when you need them.
10535 largefiles works by maintaining a "standin file" in .hglf/ for each
10537 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
10538 line) and are tracked by Mercurial. Largefile revisions are identified
10539 by the SHA-1 hash of their contents, which is written to the standin.
10540 largefiles uses that revision ID to get/put largefile revisions from/to
10541 the central store. This saves both disk space and bandwidth, since you
10542 don't need to retrieve all historical revisions of large files when you
10543 clone or pull.
10544 To start a new repository or add new large binary files, just add
10546 --large to your hg add command. For example:
10547 $ dd if=/dev/urandom of=randomdata count=2000
10549 $ hg add --large randomdata
10550 $ hg commit -m "add randomdata as a largefile"
10551 When you push a changeset that adds/modifies largefiles to a remote
10553 repository, its largefile revisions will be uploaded along with it.
10554 Note that the remote Mercurial must also have the largefiles extension
10555 enabled for this to work.
10556 When you pull a changeset that affects largefiles from a remote reposi‐
10558 tory, the largefiles for the changeset will by default not be pulled
10559 down. However, when you update to such a revision, any largefiles
10560 needed by that revision are downloaded and cached (if they have never
10561 been downloaded before). One way to pull largefiles when pulling is
10562 thus to use --update, which will update your working copy to the latest
10563 pulled revision (and thereby downloading any new largefiles).
10564 If you want to pull largefiles you don't need for update yet, then you
10566 can use pull with the --lfrev option or the hg lfpull command.
10567 If you know you are pulling from a non-default location and want to
10569 download all the largefiles that correspond to the new changesets at
10570 the same time, then you can pull with --lfrev "pulled()".
10571 If you just want to ensure that you will have the largefiles needed to
10573 merge or rebase with new heads that you are pulling, then you can pull
10574 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
10575 files that are new in the heads you are pulling.
10576 Keep in mind that network access may now be required to update to
10578 changesets that you have not previously updated to. The nature of the
10579 largefiles extension means that updating is no longer guaranteed to be
10580 a local-only operation.
10581 If you already have large files tracked by Mercurial without the large‐
10583 files extension, you will need to convert your repository in order to
10584 benefit from largefiles. This is done with the hg lfconvert command:
10585 $ hg lfconvert --size 10 oldrepo newrepo
10587 In repositories that already have largefiles in them, any new file over
10589 10MB will automatically be added as a largefile. To change this thresh‐
10590 old, set largefiles.minsize in your Mercurial config file to the mini‐
10591 mum size in megabytes to track as a largefile, or use the --lfsize
10592 option to the add command (also in megabytes):
10593 [largefiles]
10595 minsize = 2
10596 $ hg add --lfsize 2
10598 The largefiles.patterns config option allows you to specify a list of
10600 filename patterns (see hg help patterns) that should always be tracked
10601 as largefiles:
10602 [largefiles]
10604 patterns =
10605 *.jpg
10606 re:.*\.(png|bmp)$
10607 library.zip
10608 content/audio/*
10609 Files that match one of these patterns will be added as largefiles
10611 regardless of their size.
10612 The largefiles.minsize and largefiles.patterns config options will be
10614 ignored for any repositories not already containing a largefile. To add
10615 the first largefile to a repository, you must explicitly do so with the
10616 --large flag passed to the hg add command.
10617 Commands
10619 lfconvert
10620 convert a normal repository to a largefiles repository:
10621 hg lfconvert SOURCE DEST [FILE ...]
10623 Convert repository SOURCE to a new repository DEST, identical to SOURCE
10625 except that certain files will be converted as largefiles: specifi‐
10626 cally, any file that matches any PATTERN or whose size is above the
10627 minimum size threshold is converted as a largefile. The size used to
10628 determine whether or not to track a file as a largefile is the size of
10629 the first version of the file. The minimum size can be specified either
10630 with --size or in configuration as largefiles.size.
10631 After running this command you will need to make sure that largefiles
10633 is enabled anywhere you intend to push the new repository.
10634 Use --to-normal to convert largefiles back to normal files; after this,
10636 the DEST repository can be used without largefiles at all.
10637 Options:
10639 -s,--size <SIZE>
10641 minimum size (MB) for files to be converted as largefiles
10642 --to-normal
10644 convert from a largefiles repo to a normal repo
10645 lfpull
10647 pull largefiles for the specified revisions from the specified source:
10648 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
10650 Pull largefiles that are referenced from local changesets but missing
10652 locally, pulling from a remote repository to the local cache.
10653 If SOURCE is omitted, the 'default' path will be used. See hg help
10655 urls for more information.
10656 Some examples:
10658 · pull largefiles for all branch heads:
10660 hg lfpull -r "head() and not closed()"
10662 · pull largefiles on the default branch:
10664 hg lfpull -r "branch(default)"
10666 Options:
10668 -r,--rev <VALUE[+]>
10670 pull largefiles for these revisions
10671 -e,--ssh <CMD>
10673 specify ssh command to use
10674 --remotecmd <CMD>
10676 specify hg command to run on the remote side
10677 --insecure
10679 do not verify server certificate (ignoring web.cacerts config)
10680 [+] marked option can be specified multiple times
10682 lfs
10684 lfs - large file support (EXPERIMENTAL)
10685 This extension allows large files to be tracked outside of the normal
10687 repository storage and stored on a centralized server, similar to the
10688 largefiles extension. The git-lfs protocol is used when communicating
10689 with the server, so existing git infrastructure can be harnessed. Even
10690 though the files are stored outside of the repository, they are still
10691 integrity checked in the same manner as normal files.
10692 The files stored outside of the repository are downloaded on demand,
10694 which reduces the time to clone, and possibly the local disk usage.
10695 This changes fundamental workflows in a DVCS, so careful thought should
10696 be given before deploying it. hg convert can be used to convert LFS
10697 repositories to normal repositories that no longer require this exten‐
10698 sion, and do so without changing the commit hashes. This allows the
10699 extension to be disabled if the centralized workflow becomes burden‐
10700 some. However, the pre and post convert clones will not be able to
10701 communicate with each other unless the extension is enabled on both.
10702 To start a new repository, or to add LFS files to an existing one, just
10704 create an .hglfs file as described below in the root directory of the
10705 repository. Typically, this file should be put under version control,
10706 so that the settings will propagate to other repositories with push and
10707 pull. During any commit, Mercurial will consult this file to determine
10708 if an added or modified file should be stored externally. The type of
10709 storage depends on the characteristics of the file at each commit. A
10710 file that is near a size threshold may switch back and forth between
10711 LFS and normal storage, as needed.
10712 Alternately, both normal repositories and largefile controlled reposi‐
10714 tories can be converted to LFS by using hg convert and the lfs.track
10715 config option described below. The .hglfs file should then be created
10716 and added, to control subsequent LFS selection. The hashes are also
10717 unchanged in this case. The LFS and non-LFS repositories can be dis‐
10718 tinguished because the LFS repository will abort any command if this
10719 extension is disabled.
10720 Committed LFS files are held locally, until the repository is pushed.
10722 Prior to pushing the normal repository data, the LFS files that are
10723 tracked by the outgoing commits are automatically uploaded to the con‐
10724 figured central server. No LFS files are transferred on hg pull or hg
10725 clone. Instead, the files are downloaded on demand as they need to be
10726 read, if a cached copy cannot be found locally. Both committing and
10727 downloading an LFS file will link the file to a usercache, to speed up
10728 future access. See the usercache config setting described below.
10729 The extension reads its configuration from a versioned ``.hglfs``
10732 configuration file found in the root of the working directory. The
10733 ``.hglfs`` file uses the same syntax as all other Mercurial
10734 configuration files. It uses a single section, ``[track]``.
10735 The ``[track]`` section specifies which files are stored as LFS (or
10737 not). Each line is keyed by a file pattern, with a predicate value.
10738 The first file pattern match is used, so put more specific patterns
10739 first. The available predicates are ``all()``, ``none()``, and
10740 ``size()``. See "hg help filesets.size" for the latter.
10741 Example versioned ``.hglfs`` file::
10743 [track]
10745 # No Makefile or python file, anywhere, will be LFS
10746 **Makefile = none()
10747 **.py = none()
10748 **.zip = all()
10750 **.exe = size(">1MB")
10751 # Catchall for everything not matched above
10753 ** = size(">10MB")
10754 Configs:
10756 [lfs]
10758 # Remote endpoint. Multiple protocols are supported:
10759 # - http(s)://user:pass@example.com/path
10760 # git-lfs endpoint
10761 # - file:///tmp/path
10762 # local filesystem, usually for testing
10763 # if unset, lfs will assume the remote repository also handles blob storage
10764 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
10765 # use this value.
10766 # (default: unset)
10767 url = https://example.com/repo.git/info/lfs
10768 # Which files to track in LFS. Path tests are "**.extname" for file
10770 # extensions, and "path:under/some/directory" for path prefix. Both
10771 # are relative to the repository root.
10772 # File size can be tested with the "size()" fileset, and tests can be
10773 # joined with fileset operators. (See "hg help filesets.operators".)
10774 #
10775 # Some examples:
10776 # - all() # everything
10777 # - none() # nothing
10778 # - size(">20MB") # larger than 20MB
10779 # - !**.txt # anything not a *.txt file
10780 # - **.zip | **.tar.gz | **.7z # some types of compressed files
10781 # - path:bin # files under "bin" in the project root
10782 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
10783 # | (path:bin & !path:/bin/README) | size(">1GB")
10784 # (default: none())
10785 #
10786 # This is ignored if there is a tracked '.hglfs' file, and this setting
10787 # will eventually be deprecated and removed.
10788 track = size(">10M")
10789 # how many times to retry before giving up on transferring an object
10791 retry = 5
10792 # the local directory to store lfs files for sharing across local clones.
10794 # If not set, the cache is located in an OS specific cache location.
10795 usercache = /path/to/global/cache
10796 Commands
10798 logtoprocess
10799 send ui.log() data to a subprocess (EXPERIMENTAL)
10800 This extension lets you specify a shell command per ui.log() event,
10802 sending all remaining arguments to as environment variables to that
10803 command.
10804 Positional arguments construct a log message, which is passed in the
10806 MSG1 environment variables. Each keyword argument is set as a
10807 OPT_UPPERCASE_KEY variable (so the key is uppercased, and prefixed with
10808 OPT_). The original event name is passed in the EVENT environment vari‐
10809 able, and the process ID of mercurial is given in HGPID.
10810 So given a call ui.log('foo', 'bar %s ', 'baz', spam='eggs'), a script
10812 configured for the `foo event can expect an environment with MSG1=bar
10813 baz, and OPT_SPAM=eggs.
10814 Scripts are configured in the [logtoprocess] section, each key an event
10816 name. For example:
10817 [logtoprocess]
10819 commandexception = echo "$MSG1" > /var/log/mercurial_exceptions.log
10820 would log the warning message and traceback of any failed command dis‐
10822 patch.
10823 Scripts are run asynchronously as detached daemon processes; mercurial
10825 will not ensure that they exit cleanly.
10826 mq
10828 manage a stack of patches
10829 This extension lets you work with a stack of patches in a Mercurial
10831 repository. It manages two stacks of patches - all known patches, and
10832 applied patches (subset of known patches).
10833 Known patches are represented as patch files in the .hg/patches direc‐
10835 tory. Applied patches are both patch files and changesets.
10836 Common tasks (use hg help COMMAND for more details):
10838 create new patch qnew
10840 import existing patch qimport
10841 print patch series qseries
10843 print applied patches qapplied
10844 add known patch to applied stack qpush
10846 remove patch from applied stack qpop
10847 refresh contents of top applied patch qrefresh
10848 By default, mq will automatically use git patches when required to
10850 avoid losing file mode changes, copy records, binary files or empty
10851 files creations or deletions. This behavior can be configured with:
10852 [mq]
10854 git = auto/keep/yes/no
10855 If set to 'keep', mq will obey the [diff] section configuration while
10857 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
10858 mq will override the [diff] section and always generate git or regular
10859 patches, possibly losing data in the second case.
10860 It may be desirable for mq changesets to be kept in the secret phase
10862 (see hg help phases), which can be enabled with the following setting:
10863 [mq]
10865 secret = True
10866 You will by default be managing a patch queue named "patches". You can
10868 create other, independent patch queues with the hg qqueue command.
10869 If the working directory contains uncommitted files, qpush, qpop and
10871 qgoto abort immediately. If -f/--force is used, the changes are dis‐
10872 carded. Setting:
10873 [mq]
10875 keepchanges = True
10876 make them behave as if --keep-changes were passed, and non-conflicting
10878 local changes will be tolerated and preserved. If incompatible options
10879 such as -f/--force or --exact are passed, this setting is ignored.
10880 This extension used to provide a strip command. This command now lives
10882 in the strip extension.
10883 Commands
10885 qapplied
10886 print the patches already applied:
10887 hg qapplied [-1] [-s] [PATCH]
10889 Returns 0 on success.
10891 Options:
10893 -1, --last
10895 show only the preceding applied patch
10896 -s, --summary
10898 print first line of patch header
10899 qclone
10901 clone main and patch repository at same time:
10902 hg qclone [OPTION]... SOURCE [DEST]
10904 If source is local, destination will have no patches applied. If source
10906 is remote, this command can not check if patches are applied in source,
10907 so cannot guarantee that patches are not applied in destination. If you
10908 clone remote repository, be sure before that it has no patches applied.
10909 Source patch repository is looked for in <src>/.hg/patches by default.
10911 Use -p <url> to change.
10912 The patch directory must be a nested Mercurial repository, as would be
10914 created by hg init --mq.
10915 Return 0 on success.
10917 Options:
10919 --pull use pull protocol to copy metadata
10921 -U, --noupdate
10923 do not update the new working directories
10924 --uncompressed
10926 use uncompressed transfer (fast over LAN)
10927 -p,--patches <REPO>
10929 location of source patch repository
10930 -e,--ssh <CMD>
10932 specify ssh command to use
10933 --remotecmd <CMD>
10935 specify hg command to run on the remote side
10936 --insecure
10938 do not verify server certificate (ignoring web.cacerts config)
10939 qcommit
10941 commit changes in the queue repository (DEPRECATED):
10942 hg qcommit [OPTION]... [FILE]...
10944 This command is deprecated; use hg commit --mq instead.
10946 Options:
10948 -A, --addremove
10950 mark new/missing files as added/removed before committing
10951 --close-branch
10953 mark a branch head as closed
10954 --amend
10956 amend the parent of the working directory
10957 -s, --secret
10959 use the secret phase for committing
10960 -e, --edit
10962 invoke editor on commit messages
10963 -i, --interactive
10965 use interactive mode
10966 -I,--include <PATTERN[+]>
10968 include names matching the given patterns
10969 -X,--exclude <PATTERN[+]>
10971 exclude names matching the given patterns
10972 -m,--message <TEXT>
10974 use text as commit message
10975 -l,--logfile <FILE>
10977 read commit message from file
10978 -d,--date <DATE>
10980 record the specified date as commit date
10981 -u,--user <USER>
10983 record the specified user as committer
10984 -S, --subrepos
10986 recurse into subrepositories
10987 [+] marked option can be specified multiple times
10989 aliases: qci
10991 qdelete
10993 remove patches from queue:
10994 hg qdelete [-k] [PATCH]...
10996 The patches must not be applied, and at least one patch is required.
10998 Exact patch identifiers must be given. With -k/--keep, the patch files
10999 are preserved in the patch directory.
11000 To stop managing a patch and move it into permanent history, use the hg
11002 qfinish command.
11003 Options:
11005 -k, --keep
11007 keep patch file
11008 -r,--rev <REV[+]>
11010 stop managing a revision (DEPRECATED)
11011 [+] marked option can be specified multiple times
11013 aliases: qremove qrm
11015 qdiff
11017 diff of the current patch and subsequent modifications:
11018 hg qdiff [OPTION]... [FILE]...
11020 Shows a diff which includes the current patch as well as any changes
11022 which have been made in the working directory since the last refresh
11023 (thus showing what the current patch would become after a qrefresh).
11024 Use hg diff if you only want to see the changes made since the last
11026 qrefresh, or hg export qtip if you want to see changes made by the cur‐
11027 rent patch without including changes made since the qrefresh.
11028 Returns 0 on success.
11030 Options:
11032 -a, --text
11034 treat all files as text
11035 -g, --git
11037 use git extended diff format
11038 --binary
11040 generate binary diffs in git mode (default)
11041 --nodates
11043 omit dates from diff headers
11044 --noprefix
11046 omit a/ and b/ prefixes from filenames
11047 -p, --show-function
11049 show which function each change is in
11050 --reverse
11052 produce a diff that undoes the changes
11053 -w, --ignore-all-space
11055 ignore white space when comparing lines
11056 -b, --ignore-space-change
11058 ignore changes in the amount of white space
11059 -B, --ignore-blank-lines
11061 ignore changes whose lines are all blank
11062 -Z, --ignore-space-at-eol
11064 ignore changes in whitespace at EOL
11065 -U,--unified <NUM>
11067 number of lines of context to show
11068 --stat output diffstat-style summary of changes
11070 --root <DIR>
11072 produce diffs relative to subdirectory
11073 -I,--include <PATTERN[+]>
11075 include names matching the given patterns
11076 -X,--exclude <PATTERN[+]>
11078 exclude names matching the given patterns
11079 [+] marked option can be specified multiple times
11081 qfinish
11083 move applied patches into repository history:
11084 hg qfinish [-a] [REV]...
11086 Finishes the specified revisions (corresponding to applied patches) by
11088 moving them out of mq control into regular repository history.
11089 Accepts a revision range or the -a/--applied option. If --applied is
11091 specified, all applied mq revisions are removed from mq control. Other‐
11092 wise, the given revisions must be at the base of the stack of applied
11093 patches.
11094 This can be especially useful if your changes have been applied to an
11096 upstream repository, or if you are about to push your changes to
11097 upstream.
11098 Returns 0 on success.
11100 Options:
11102 -a, --applied
11104 finish all applied changesets
11105 qfold
11107 fold the named patches into the current patch:
11108 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
11110 Patches must not yet be applied. Each patch will be successively
11112 applied to the current patch in the order given. If all the patches
11113 apply successfully, the current patch will be refreshed with the new
11114 cumulative patch, and the folded patches will be deleted. With
11115 -k/--keep, the folded patch files will not be removed afterwards.
11116 The header for each folded patch will be concatenated with the current
11118 patch header, separated by a line of * * *.
11119 Returns 0 on success.
11121 Options:
11123 -e, --edit
11125 invoke editor on commit messages
11126 -k, --keep
11128 keep folded patch files
11129 -m,--message <TEXT>
11131 use text as commit message
11132 -l,--logfile <FILE>
11134 read commit message from file
11135 qgoto
11137 push or pop patches until named patch is at top of stack:
11138 hg qgoto [OPTION]... PATCH
11140 Returns 0 on success.
11142 Options:
11144 --keep-changes
11146 tolerate non-conflicting local changes
11147 -f, --force
11149 overwrite any local changes
11150 --no-backup
11152 do not save backup copies of files
11153 qguard
11155 set or print guards for a patch:
11156 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
11158 Guards control whether a patch can be pushed. A patch with no guards is
11160 always pushed. A patch with a positive guard ("+foo") is pushed only if
11161 the hg qselect command has activated it. A patch with a negative guard
11162 ("-foo") is never pushed if the hg qselect command has activated it.
11163 With no arguments, print the currently active guards. With arguments,
11165 set guards for the named patch.
11166 Note Specifying negative guards now requires '--'.
11168 To set guards on another patch:
11170 hg qguard other.patch -- +2.6.17 -stable
11172 Returns 0 on success.
11174 Options:
11176 -l, --list
11178 list all patches and guards
11179 -n, --none
11181 drop all guards
11182 qheader
11184 print the header of the topmost or specified patch:
11185 hg qheader [PATCH]
11187 Returns 0 on success.
11189 qimport
11191 import a patch or existing changeset:
11192 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
11194 The patch is inserted into the series after the last applied patch. If
11196 no patches have been applied, qimport prepends the patch to the series.
11197 The patch will have the same name as its source file unless you give it
11199 a new one with -n/--name.
11200 You can register an existing patch inside the patch directory with the
11202 -e/--existing flag.
11203 With -f/--force, an existing patch of the same name will be overwrit‐
11205 ten.
11206 An existing changeset may be placed under mq control with -r/--rev
11208 (e.g. qimport --rev . -n patch will place the current revision under mq
11209 control). With -g/--git, patches imported with --rev will use the git
11210 diff format. See the diffs help topic for information on why this is
11211 important for preserving rename/copy information and permission
11212 changes. Use hg qfinish to remove changesets from mq control.
11213 To import a patch from standard input, pass - as the patch file. When
11215 importing from standard input, a patch name must be specified using the
11216 --name flag.
11217 To import an existing patch while renaming it:
11219 hg qimport -e existing-patch -n new-name
11221 Returns 0 if import succeeded.
11223 Options:
11225 -e, --existing
11227 import file in patch directory
11228 -n,--name <NAME>
11230 name of patch file
11231 -f, --force
11233 overwrite existing files
11234 -r,--rev <REV[+]>
11236 place existing revisions under mq control
11237 -g, --git
11239 use git extended diff format
11240 -P, --push
11242 qpush after importing
11243 [+] marked option can be specified multiple times
11245 qinit
11247 init a new queue repository (DEPRECATED):
11248 hg qinit [-c]
11250 The queue repository is unversioned by default. If -c/--create-repo is
11252 specified, qinit will create a separate nested repository for patches
11253 (qinit -c may also be run later to convert an unversioned patch reposi‐
11254 tory into a versioned one). You can use qcommit to commit changes to
11255 this queue repository.
11256 This command is deprecated. Without -c, it's implied by other relevant
11258 commands. With -c, use hg init --mq instead.
11259 Options:
11261 -c, --create-repo
11263 create queue repository
11264 qnew
11266 create a new patch:
11267 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
11269 qnew creates a new patch on top of the currently-applied patch (if
11271 any). The patch will be initialized with any outstanding changes in the
11272 working directory. You may also use -I/--include, -X/--exclude, and/or
11273 a list of files after the patch name to add only changes to matching
11274 files to the new patch, leaving the rest as uncommitted modifications.
11275 -u/--user and -d/--date can be used to set the (given) user and date,
11277 respectively. -U/--currentuser and -D/--currentdate set user to current
11278 user and date to current date.
11279 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
11281 the commit message. If none is specified, the header is empty and the
11282 commit message is '[mq]: PATCH'.
11283 Use the -g/--git option to keep the patch in the git extended diff for‐
11285 mat. Read the diffs help topic for more information on why this is
11286 important for preserving permission changes and copy/rename informa‐
11287 tion.
11288 Returns 0 on successful creation of a new patch.
11290 Options:
11292 -e, --edit
11294 invoke editor on commit messages
11295 -f, --force
11297 import uncommitted changes (DEPRECATED)
11298 -g, --git
11300 use git extended diff format
11301 -U, --currentuser
11303 add "From: <current user>" to patch
11304 -u,--user <USER>
11306 add "From: <USER>" to patch
11307 -D, --currentdate
11309 add "Date: <current date>" to patch
11310 -d,--date <DATE>
11312 add "Date: <DATE>" to patch
11313 -I,--include <PATTERN[+]>
11315 include names matching the given patterns
11316 -X,--exclude <PATTERN[+]>
11318 exclude names matching the given patterns
11319 -m,--message <TEXT>
11321 use text as commit message
11322 -l,--logfile <FILE>
11324 read commit message from file
11325 [+] marked option can be specified multiple times
11327 qnext
11329 print the name of the next pushable patch:
11330 hg qnext [-s]
11332 Returns 0 on success.
11334 Options:
11336 -s, --summary
11338 print first line of patch header
11339 qpop
11341 pop the current patch off the stack:
11342 hg qpop [-a] [-f] [PATCH | INDEX]
11344 Without argument, pops off the top of the patch stack. If given a patch
11346 name, keeps popping off patches until the named patch is at the top of
11347 the stack.
11348 By default, abort if the working directory contains uncommitted
11350 changes. With --keep-changes, abort only if the uncommitted files over‐
11351 lap with patched files. With -f/--force, backup and discard changes
11352 made to such files.
11353 Return 0 on success.
11355 Options:
11357 -a, --all
11359 pop all patches
11360 -n,--name <NAME>
11362 queue name to pop (DEPRECATED)
11363 --keep-changes
11365 tolerate non-conflicting local changes
11366 -f, --force
11368 forget any local changes to patched files
11369 --no-backup
11371 do not save backup copies of files
11372 qprev
11374 print the name of the preceding applied patch:
11375 hg qprev [-s]
11377 Returns 0 on success.
11379 Options:
11381 -s, --summary
11383 print first line of patch header
11384 qpush
11386 push the next patch onto the stack:
11387 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
11389 By default, abort if the working directory contains uncommitted
11391 changes. With --keep-changes, abort only if the uncommitted files over‐
11392 lap with patched files. With -f/--force, backup and patch over uncom‐
11393 mitted changes.
11394 Return 0 on success.
11396 Options:
11398 --keep-changes
11400 tolerate non-conflicting local changes
11401 -f, --force
11403 apply on top of local changes
11404 -e, --exact
11406 apply the target patch to its recorded parent
11407 -l, --list
11409 list patch name in commit text
11410 -a, --all
11412 apply all patches
11413 -m, --merge
11415 merge from another queue (DEPRECATED)
11416 -n,--name <NAME>
11418 merge queue name (DEPRECATED)
11419 --move reorder patch series and apply only the patch
11421 --no-backup
11423 do not save backup copies of files
11424 qqueue
11426 manage multiple patch queues:
11427 hg qqueue [OPTION] [QUEUE]
11429 Supports switching between different patch queues, as well as creating
11431 new patch queues and deleting existing ones.
11432 Omitting a queue name or specifying -l/--list will show you the regis‐
11434 tered queues - by default the "normal" patches queue is registered. The
11435 currently active queue will be marked with "(active)". Specifying
11436 --active will print only the name of the active queue.
11437 To create a new queue, use -c/--create. The queue is automatically made
11439 active, except in the case where there are applied patches from the
11440 currently active queue in the repository. Then the queue will only be
11441 created and switching will fail.
11442 To delete an existing queue, use --delete. You cannot delete the cur‐
11444 rently active queue.
11445 Returns 0 on success.
11447 Options:
11449 -l, --list
11451 list all available queues
11452 --active
11454 print name of active queue
11455 -c, --create
11457 create new queue
11458 --rename
11460 rename active queue
11461 --delete
11463 delete reference to queue
11464 --purge
11466 delete queue, and remove patch dir
11467 qrefresh
11469 update the current patch:
11470 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
11472 If any file patterns are provided, the refreshed patch will contain
11474 only the modifications that match those patterns; the remaining modifi‐
11475 cations will remain in the working directory.
11476 If -s/--short is specified, files currently included in the patch will
11478 be refreshed just like matched files and remain in the patch.
11479 If -e/--edit is specified, Mercurial will start your configured editor
11481 for you to enter a message. In case qrefresh fails, you will find a
11482 backup of your message in .hg/last-message.txt.
11483 hg add/remove/copy/rename work as usual, though you might want to use
11485 git-style patches (-g/--git or [diff] git=1) to track copies and
11486 renames. See the diffs help topic for more information on the git diff
11487 format.
11488 Returns 0 on success.
11490 Options:
11492 -e, --edit
11494 invoke editor on commit messages
11495 -g, --git
11497 use git extended diff format
11498 -s, --short
11500 refresh only files already in the patch and specified files
11501 -U, --currentuser
11503 add/update author field in patch with current user
11504 -u,--user <USER>
11506 add/update author field in patch with given user
11507 -D, --currentdate
11509 add/update date field in patch with current date
11510 -d,--date <DATE>
11512 add/update date field in patch with given date
11513 -I,--include <PATTERN[+]>
11515 include names matching the given patterns
11516 -X,--exclude <PATTERN[+]>
11518 exclude names matching the given patterns
11519 -m,--message <TEXT>
11521 use text as commit message
11522 -l,--logfile <FILE>
11524 read commit message from file
11525 [+] marked option can be specified multiple times
11527 qrename
11529 rename a patch:
11530 hg qrename PATCH1 [PATCH2]
11532 With one argument, renames the current patch to PATCH1. With two argu‐
11534 ments, renames PATCH1 to PATCH2.
11535 Returns 0 on success.
11537 aliases: qmv
11539 qrestore
11541 restore the queue state saved by a revision (DEPRECATED):
11542 hg qrestore [-d] [-u] REV
11544 This command is deprecated, use hg rebase instead.
11546 Options:
11548 -d, --delete
11550 delete save entry
11551 -u, --update
11553 update queue working directory
11554 qsave
11556 save current queue state (DEPRECATED):
11557 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
11559 This command is deprecated, use hg rebase instead.
11561 Options:
11563 -c, --copy
11565 copy patch directory
11566 -n,--name <NAME>
11568 copy directory name
11569 -e, --empty
11571 clear queue status file
11572 -f, --force
11574 force copy
11575 -m,--message <TEXT>
11577 use text as commit message
11578 -l,--logfile <FILE>
11580 read commit message from file
11581 qselect
11583 set or print guarded patches to push:
11584 hg qselect [OPTION]... [GUARD]...
11586 Use the hg qguard command to set or print guards on patch, then use
11588 qselect to tell mq which guards to use. A patch will be pushed if it
11589 has no guards or any positive guards match the currently selected
11590 guard, but will not be pushed if any negative guards match the current
11591 guard. For example:
11592 qguard foo.patch -- -stable (negative guard)
11594 qguard bar.patch +stable (positive guard)
11595 qselect stable
11596 This activates the "stable" guard. mq will skip foo.patch (because it
11598 has a negative match) but push bar.patch (because it has a positive
11599 match).
11600 With no arguments, prints the currently active guards. With one argu‐
11602 ment, sets the active guard.
11603 Use -n/--none to deactivate guards (no other arguments needed). When
11605 no guards are active, patches with positive guards are skipped and
11606 patches with negative guards are pushed.
11607 qselect can change the guards on applied patches. It does not pop
11609 guarded patches by default. Use --pop to pop back to the last applied
11610 patch that is not guarded. Use --reapply (which implies --pop) to push
11611 back to the current patch afterwards, but skip guarded patches.
11612 Use -s/--series to print a list of all guards in the series file (no
11614 other arguments needed). Use -v for more information.
11615 Returns 0 on success.
11617 Options:
11619 -n, --none
11621 disable all guards
11622 -s, --series
11624 list all guards in series file
11625 --pop pop to before first guarded applied patch
11627 --reapply
11629 pop, then reapply patches
11630 qseries
11632 print the entire series file:
11633 hg qseries [-ms]
11635 Returns 0 on success.
11637 Options:
11639 -m, --missing
11641 print patches not in series
11642 -s, --summary
11644 print first line of patch header
11645 qtop
11647 print the name of the current patch:
11648 hg qtop [-s]
11650 Returns 0 on success.
11652 Options:
11654 -s, --summary
11656 print first line of patch header
11657 qunapplied
11659 print the patches not yet applied:
11660 hg qunapplied [-1] [-s] [PATCH]
11662 Returns 0 on success.
11664 Options:
11666 -1, --first
11668 show only the first patch
11669 -s, --summary
11671 print first line of patch header
11672 narrow
11674 create clones which fetch history data for subset of files (EXPERIMEN‐
11675 TAL)
11676 Commands
11678 tracked
11679 show or change the current narrowspec:
11680 hg tracked [OPTIONS]... [REMOTE]
11682 With no argument, shows the current narrowspec entries, one per line.
11684 Each line will be prefixed with 'I' or 'X' for included or excluded
11685 patterns, respectively.
11686 The narrowspec is comprised of expressions to match remote files and/or
11688 directories that should be pulled into your client. The narrowspec has
11689 include and exclude expressions, with excludes always trumping
11690 includes: that is, if a file matches an exclude expression, it will be
11691 excluded even if it also matches an include expression. Excluding
11692 files that were never included has no effect.
11693 Each included or excluded entry is in the format described by 'hg help
11695 patterns'.
11696 The options allow you to add or remove included and excluded expres‐
11698 sions.
11699 If --clear is specified, then all previous includes and excludes are
11701 DROPPED and replaced by the new ones specified to --addinclude and
11702 --addexclude. If --clear is specified without any further options, the
11703 narrowspec will be empty and will not match any files.
11704 Options:
11706 --addinclude <VALUE[+]>
11708 new paths to include
11709 --removeinclude <VALUE[+]>
11711 old paths to no longer include
11712 --addexclude <VALUE[+]>
11714 new paths to exclude
11715 --import-rules <VALUE>
11717 import narrowspecs from a file
11718 --removeexclude <VALUE[+]>
11720 old paths to no longer exclude
11721 --clear
11723 whether to replace the existing narrowspec
11724 --force-delete-local-changes
11726 forces deletion of local changes when narrowing
11727 --update-working-copy
11729 update working copy when the store has changed
11730 -e,--ssh <CMD>
11732 specify ssh command to use
11733 --remotecmd <CMD>
11735 specify hg command to run on the remote side
11736 --insecure
11738 do not verify server certificate (ignoring web.cacerts config)
11739 [+] marked option can be specified multiple times
11741 notify
11743 hooks for sending email push notifications
11744 This extension implements hooks to send email notifications when
11746 changesets are sent from or received by the local repository.
11747 First, enable the extension as explained in hg help extensions, and
11749 register the hook you want to run. incoming and changegroup hooks are
11750 run when changesets are received, while outgoing hooks are for change‐
11751 sets sent to another repository:
11752 [hooks]
11754 # one email for each incoming changeset
11755 incoming.notify = python:hgext.notify.hook
11756 # one email for all incoming changesets
11757 changegroup.notify = python:hgext.notify.hook
11758 # one email for all outgoing changesets
11760 outgoing.notify = python:hgext.notify.hook
11761 This registers the hooks. To enable notification, subscribers must be
11763 assigned to repositories. The [usersubs] section maps multiple reposi‐
11764 tories to a given recipient. The [reposubs] section maps multiple
11765 recipients to a single repository:
11766 [usersubs]
11768 # key is subscriber email, value is a comma-separated list of repo patterns
11769 user@host = pattern
11770 [reposubs]
11772 # key is repo pattern, value is a comma-separated list of subscriber emails
11773 pattern = user@host
11774 A pattern is a glob matching the absolute path to a repository, option‐
11776 ally combined with a revset expression. A revset expression, if
11777 present, is separated from the glob by a hash. Example:
11778 [reposubs]
11780 */widgets#branch(release) = qa-team@example.com
11781 This sends to qa-team@example.com whenever a changeset on the release
11783 branch triggers a notification in any repository ending in widgets.
11784 In order to place them under direct user management, [usersubs] and
11786 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
11787 rated by reference:
11788 [notify]
11790 config = /path/to/subscriptionsfile
11791 Notifications will not be sent until the notify.test value is set to
11793 False; see below.
11794 Notifications content can be tweaked with the following configuration
11796 entries:
11797 notify.test
11799 If True, print messages to stdout instead of sending them.
11800 Default: True.
11801 notify.sources
11803 Space-separated list of change sources. Notifications are acti‐
11804 vated only when a changeset's source is in this list. Sources
11805 may be:
11806 serve
11808 changesets received via http or ssh
11810 pull
11812 changesets received via hg pull
11814 unbundle
11816 changesets received via hg unbundle
11818 push
11820 changesets sent or received via hg push
11822 bundle
11824 changesets sent via hg unbundle
11826 Default: serve.
11828 notify.strip
11830 Number of leading slashes to strip from url paths. By default,
11831 notifications reference repositories with their absolute path.
11832 notify.strip lets you turn them into relative paths. For exam‐
11833 ple, notify.strip=3 will change /long/path/repository into
11834 repository. Default: 0.
11835 notify.domain
11837 Default email domain for sender or recipients with no explicit
11838 domain.
11839 notify.style
11841 Style file to use when formatting emails.
11842 notify.template
11844 Template to use when formatting emails.
11845 notify.incoming
11847 Template to use when run as an incoming hook, overriding
11848 notify.template.
11849 notify.outgoing
11851 Template to use when run as an outgoing hook, overriding
11852 notify.template.
11853 notify.changegroup
11855 Template to use when running as a changegroup hook, overriding
11856 notify.template.
11857 notify.maxdiff
11859 Maximum number of diff lines to include in notification email.
11860 Set to 0 to disable the diff, or -1 to include all of it.
11861 Default: 300.
11862 notify.maxdiffstat
11864 Maximum number of diffstat lines to include in notification
11865 email. Set to -1 to include all of it. Default: -1.
11866 notify.maxsubject
11868 Maximum number of characters in email's subject line. Default:
11869 67.
11870 notify.diffstat
11872 Set to True to include a diffstat before diff content. Default:
11873 True.
11874 notify.showfunc
11876 If set, override diff.showfunc for the diff content. Default:
11877 None.
11878 notify.merge
11880 If True, send notifications for merge changesets. Default: True.
11881 notify.mbox
11883 If set, append mails to this mbox file instead of sending.
11884 Default: None.
11885 notify.fromauthor
11887 If set, use the committer of the first changeset in a change‐
11888 group for the "From" field of the notification mail. If not set,
11889 take the user from the pushing repo. Default: False.
11890 If set, the following entries will also be used to customize the noti‐
11892 fications:
11893 email.from
11895 Email From address to use if none can be found in the generated
11896 email content.
11897 web.baseurl
11899 Root repository URL to combine with repository paths when making
11900 references. See also notify.strip.
11901 pager
11903 browse command output with an external pager (DEPRECATED)
11904 Forcibly enable paging for individual commands that don't typically
11906 request pagination with the attend-<command> option. This setting takes
11907 precedence over ignore options and defaults:
11908 [pager]
11910 attend-cat = false
11911 patchbomb
11913 command to send changesets as (a series of) patch emails
11914 The series is started off with a "[PATCH 0 of N]" introduction, which
11916 describes the series as a whole.
11917 Each patch email has a Subject line of "[PATCH M of N] ...", using the
11919 first line of the changeset description as the subject text. The mes‐
11920 sage contains two or three body parts:
11921 · The changeset description.
11923 · [Optional] The result of running diffstat on the patch.
11925 · The patch itself, as generated by hg export.
11927 Each message refers to the first in the series using the In-Reply-To
11929 and References headers, so they will show up as a sequence in threaded
11930 mail and news readers, and in mail archives.
11931 To configure other defaults, add a section like this to your configura‐
11933 tion file:
11934 [email]
11936 from = My Name <my@email>
11937 to = recipient1, recipient2, ...
11938 cc = cc1, cc2, ...
11939 bcc = bcc1, bcc2, ...
11940 reply-to = address1, address2, ...
11941 Use [patchbomb] as configuration section name if you need to override
11943 global [email] address settings.
11944 Then you can use the hg email command to mail a series of changesets as
11946 a patchbomb.
11947 You can also either configure the method option in the email section to
11949 be a sendmail compatible mailer or fill out the [smtp] section so that
11950 the patchbomb extension can automatically send patchbombs directly from
11951 the commandline. See the [email] and [smtp] sections in hgrc(5) for
11952 details.
11953 By default, hg email will prompt for a To or CC header if you do not
11955 supply one via configuration or the command line. You can override
11956 this to never prompt by configuring an empty value:
11957 [email]
11959 cc =
11960 You can control the default inclusion of an introduction message with
11962 the patchbomb.intro configuration option. The configuration is always
11963 overwritten by command line flags like --intro and --desc:
11964 [patchbomb]
11966 intro=auto # include introduction message if more than 1 patch (default)
11967 intro=never # never include an introduction message
11968 intro=always # always include an introduction message
11969 You can specify a template for flags to be added in subject prefixes.
11971 Flags specified by --flag option are exported as {flags} keyword:
11972 [patchbomb]
11974 flagtemplate = "{separate(' ',
11975 ifeq(branch, 'default', '', branch|upper),
11976 flags)}"
11977 You can set patchbomb to always ask for confirmation by setting patch‐
11979 bomb.confirm to true.
11980 Commands
11982 email
11983 send changesets by email:
11984 hg email [OPTION]... [DEST]...
11986 By default, diffs are sent in the format generated by hg export, one
11988 per message. The series starts with a "[PATCH 0 of N]" introduction,
11989 which describes the series as a whole.
11990 Each patch email has a Subject line of "[PATCH M of N] ...", using the
11992 first line of the changeset description as the subject text. The mes‐
11993 sage contains two or three parts. First, the changeset description.
11994 With the -d/--diffstat option, if the diffstat program is installed,
11996 the result of running diffstat on the patch is inserted.
11997 Finally, the patch itself, as generated by hg export.
11999 With the -d/--diffstat or --confirm options, you will be presented with
12001 a final summary of all messages and asked for confirmation before the
12002 messages are sent.
12003 By default the patch is included as text in the email body for easy
12005 reviewing. Using the -a/--attach option will instead create an attach‐
12006 ment for the patch. With -i/--inline an inline attachment will be cre‐
12007 ated. You can include a patch both as text in the email body and as a
12008 regular or an inline attachment by combining the -a/--attach or
12009 -i/--inline with the --body option.
12010 With -B/--bookmark changesets reachable by the given bookmark are
12012 selected.
12013 With -o/--outgoing, emails will be generated for patches not found in
12015 the destination repository (or only those which are ancestors of the
12016 specified revisions if any are provided)
12017 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
12019 gle email containing a binary Mercurial bundle as an attachment will be
12020 sent. Use the patchbomb.bundletype config option to control the bundle
12021 type as with hg bundle --type.
12022 With -m/--mbox, instead of previewing each patchbomb message in a pager
12024 or sending the messages directly, it will create a UNIX mailbox file
12025 with the patch emails. This mailbox file can be previewed with any mail
12026 user agent which supports UNIX mbox files.
12027 With -n/--test, all steps will run, but mail will not be sent. You
12029 will be prompted for an email recipient address, a subject and an
12030 introductory message describing the patches of your patchbomb. Then
12031 when all is done, patchbomb messages are displayed.
12032 In case email sending fails, you will find a backup of your series
12034 introductory message in .hg/last-email.txt.
12035 The default behavior of this command can be customized through configu‐
12037 ration. (See hg help patchbomb for details)
12038 Examples:
12040 hg email -r 3000 # send patch 3000 only
12042 hg email -r 3000 -r 3001 # send patches 3000 and 3001
12043 hg email -r 3000:3005 # send patches 3000 through 3005
12044 hg email 3000 # send patch 3000 (deprecated)
12045 hg email -o # send all patches not in default
12047 hg email -o DEST # send all patches not in DEST
12048 hg email -o -r 3000 # send all ancestors of 3000 not in default
12049 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
12050 hg email -B feature # send all ancestors of feature bookmark
12052 hg email -b # send bundle of all patches not in default
12054 hg email -b DEST # send bundle of all patches not in DEST
12055 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
12056 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
12057 hg email -o -m mbox && # generate an mbox file...
12059 mutt -R -f mbox # ... and view it with mutt
12060 hg email -o -m mbox && # generate an mbox file ...
12061 formail -s sendmail \ # ... and use formail to send from the mbox
12062 -bm -t < mbox # ... using sendmail
12063 Before using this command, you will need to enable email in your hgrc.
12065 See the [email] section in hgrc(5) for details.
12066 Options:
12068 -g, --git
12070 use git extended diff format
12071 --plain
12073 omit hg patch header
12074 -o, --outgoing
12076 send changes not found in the target repository
12077 -b, --bundle
12079 send changes not in target as a binary bundle
12080 -B,--bookmark <BOOKMARK>
12082 send changes only reachable by given bookmark
12083 --bundlename <NAME>
12085 name of the bundle attachment file (default: bundle)
12086 -r,--rev <REV[+]>
12088 a revision to send
12089 --force
12091 run even when remote repository is unrelated (with -b/--bundle)
12092 --base <REV[+]>
12094 a base changeset to specify instead of a destination (with
12095 -b/--bundle)
12096 --intro
12098 send an introduction email for a single patch
12099 --body send patches as inline message text (default)
12101 -a, --attach
12103 send patches as attachments
12104 -i, --inline
12106 send patches as inline attachments
12107 --bcc <EMAIL[+]>
12109 email addresses of blind carbon copy recipients
12110 -c,--cc <EMAIL[+]>
12112 email addresses of copy recipients
12113 --confirm
12115 ask for confirmation before sending
12116 -d, --diffstat
12118 add diffstat output to messages
12119 --date <DATE>
12121 use the given date as the sending date
12122 --desc <FILE>
12124 use the given file as the series description
12125 -f,--from <EMAIL>
12127 email address of sender
12128 -n, --test
12130 print messages that would be sent
12131 -m,--mbox <FILE>
12133 write messages to mbox file instead of sending them
12134 --reply-to <EMAIL[+]>
12136 email addresses replies should be sent to
12137 -s,--subject <TEXT>
12139 subject of first message (intro or single patch)
12140 --in-reply-to <MSGID>
12142 message identifier to reply to
12143 --flag <FLAG[+]>
12145 flags to add in subject prefixes
12146 -t,--to <EMAIL[+]>
12148 email addresses of recipients
12149 -e,--ssh <CMD>
12151 specify ssh command to use
12152 --remotecmd <CMD>
12154 specify hg command to run on the remote side
12155 --insecure
12157 do not verify server certificate (ignoring web.cacerts config)
12158 [+] marked option can be specified multiple times
12160 phabricator
12162 simple Phabricator integration (EXPERIMENTAL)
12163 This extension provides a phabsend command which sends a stack of
12165 changesets to Phabricator, and a phabread command which prints a stack
12166 of revisions in a format suitable for hg import, and a phabupdate com‐
12167 mand to update statuses in batch.
12168 By default, Phabricator requires Test Plan which might prevent some
12170 changeset from being sent. The requirement could be disabled by chang‐
12171 ing differential.require-test-plan-field config server side.
12172 Config:
12174 [phabricator]
12176 # Phabricator URL
12177 url = https://phab.example.com/
12178 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
12180 # callsign is "FOO".
12181 callsign = FOO
12182 # curl command to use. If not set (default), use builtin HTTP library to
12184 # communicate. If set, use the specified curl command. This could be useful
12185 # if you need to specify advanced options that is not easily supported by
12186 # the internal library.
12187 curlcmd = curl --connect-timeout 2 --retry 3 --silent
12188 [auth]
12190 example.schemes = https
12191 example.prefix = phab.example.com
12192 # API token. Get it from https://$HOST/conduit/login/
12194 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
12195 Commands
12197 phabread
12198 print patches from Phabricator suitable for importing:
12199 hg phabread DREVSPEC [OPTIONS]
12201 DREVSPEC could be a Differential Revision identity, like D123, or just
12203 the number 123. It could also have common operators like +, -, &, (, )
12204 for complex queries. Prefix : could be used to select a stack.
12205 abandoned, accepted, closed, needsreview, needsrevision could be used
12207 to filter patches by status. For performance reason, they only repre‐
12208 sent a subset of non-status selections and cannot be used alone.
12209 For example, :D6+8-(2+D4) selects a stack up to D6, plus D8 and exclude
12211 D2 and D4. :D9 & needsreview selects "Needs Review" revisions in a
12212 stack up to D9.
12213 If --stack is given, follow dependencies information and read all
12215 patches. It is equivalent to the : operator.
12216 Options:
12218 --stack
12220 read dependencies
12221 --test-vcr <VALUE>
12223 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12224 script, otherwise will mock all http requests using the speci‐
12225 fied vcr file. (ADVANCED)
12226 phabsend
12228 upload changesets to Phabricator:
12229 hg phabsend REV [OPTIONS]
12231 If there are multiple revisions specified, they will be send as a stack
12233 with a linear dependencies relationship using the order specified by
12234 the revset.
12235 For the first time uploading changesets, local tags will be created to
12237 maintain the association. After the first time, phabsend will check
12238 obsstore and tags information so it can figure out whether to update an
12239 existing Differential Revision, or create a new one.
12240 If --amend is set, update commit messages so they have the Differential
12242 Revision URL, remove related tags. This is similar to what arcanist
12243 will do, and is more desired in author-push workflows. Otherwise, use
12244 local tags to record the Differential Revision association.
12245 The --confirm option lets you confirm changesets before sending them.
12247 You can also add following to your configuration file to make it
12248 default behaviour:
12249 [phabsend]
12251 confirm = true
12252 phabsend will check obsstore and the above association to decide
12254 whether to update an existing Differential Revision, or create a new
12255 one.
12256 Options:
12258 -r,--rev <REV[+]>
12260 revisions to send
12261 --amend
12263 update commit messages (default: True)
12264 --reviewer <VALUE[+]>
12266 specify reviewers
12267 --confirm
12269 ask for confirmation before sending
12270 --test-vcr <VALUE>
12272 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12273 script, otherwise will mock all http requests using the speci‐
12274 fied vcr file. (ADVANCED)
12275 [+] marked option can be specified multiple times
12277 phabupdate
12279 update Differential Revision in batch:
12280 hg phabupdate DREVSPEC [OPTIONS]
12282 DREVSPEC selects revisions. See hg help phabread for its usage.
12284 Options:
12286 --accept
12288 accept revisions
12289 --reject
12291 reject revisions
12292 --abandon
12294 abandon revisions
12295 --reclaim
12297 reclaim revisions
12298 -m,--comment <VALUE>
12300 comment on the last revision
12301 --test-vcr <VALUE>
12303 Path to a vcr file. If nonexistent, will record a new vcr tran‐
12304 script, otherwise will mock all http requests using the speci‐
12305 fied vcr file. (ADVANCED)
12306 purge
12308 command to delete untracked files from the working directory
12309 Commands
12311 purge
12312 removes files not tracked by Mercurial:
12313 hg purge [OPTION]... [DIR]...
12315 Delete files not known to Mercurial. This is useful to test local and
12317 uncommitted changes in an otherwise-clean source tree.
12318 This means that purge will delete the following by default:
12320 · Unknown files: files marked with "?" by hg status
12322 · Empty directories: in fact Mercurial ignores directories unless they
12324 contain files under source control management
12325 But it will leave untouched:
12327 · Modified and unmodified tracked files
12329 · Ignored files (unless --all is specified)
12331 · New files added to the repository (with hg add)
12333 The --files and --dirs options can be used to direct purge to delete
12335 only files, only directories, or both. If neither option is given, both
12336 will be deleted.
12337 If directories are given on the command line, only files in these
12339 directories are considered.
12340 Be careful with purge, as you could irreversibly delete some files you
12342 forgot to add to the repository. If you only want to print the list of
12343 files that this program would delete, use the --print option.
12344 Options:
12346 -a, --abort-on-err
12348 abort if an error occurs
12349 --all purge ignored files too
12351 --dirs purge empty directories
12353 --files
12355 purge files
12356 -p, --print
12358 print filenames instead of deleting them
12359 -0, --print0
12361 end filenames with NUL, for use with xargs (implies -p/--print)
12362 -I,--include <PATTERN[+]>
12364 include names matching the given patterns
12365 -X,--exclude <PATTERN[+]>
12367 exclude names matching the given patterns
12368 [+] marked option can be specified multiple times
12370 aliases: clean
12372 rebase
12374 command to move sets of revisions to a different ancestor
12375 This extension lets you rebase changesets in an existing Mercurial
12377 repository.
12378 For more information: https://mercurial-scm.org/wiki/RebaseExtension
12380 Commands
12382 rebase
12383 move changeset (and descendants) to a different branch:
12384 hg rebase [-s REV | -b REV] [-d REV] [OPTION]
12386 Rebase uses repeated merging to graft changesets from one part of his‐
12388 tory (the source) onto another (the destination). This can be useful
12389 for linearizing local changes relative to a master development tree.
12390 Published commits cannot be rebased (see hg help phases). To copy com‐
12392 mits, see hg help graft.
12393 If you don't specify a destination changeset (-d/--dest), rebase will
12395 use the same logic as hg merge to pick a destination. if the current
12396 branch contains exactly one other head, the other head is merged with
12397 by default. Otherwise, an explicit revision with which to merge with
12398 must be provided. (destination changeset is not modified by rebasing,
12399 but new changesets are added as its descendants.)
12400 Here are the ways to select changesets:
12402 1. Explicitly select them using --rev.
12404 2. Use --source to select a root changeset and include all of its
12406 descendants.
12407 3. Use --base to select a changeset; rebase will find ancestors and
12409 their descendants which are not also ancestors of the destina‐
12410 tion.
12411 4. If you do not specify any of --rev, source, or --base, rebase
12413 will use --base . as above.
12414 If --source or --rev is used, special names SRC and ALLSRC can be used
12416 in --dest. Destination would be calculated per source revision with SRC
12417 substituted by that single source revision and ALLSRC substituted by
12418 all source revisions.
12419 Rebase will destroy original changesets unless you use --keep. It will
12421 also move your bookmarks (even if you do).
12422 Some changesets may be dropped if they do not contribute changes (e.g.
12424 merges from the destination branch).
12425 Unlike merge, rebase will do nothing if you are at the branch tip of a
12427 named branch with two heads. You will need to explicitly specify source
12428 and/or destination.
12429 If you need to use a tool to automate merge/conflict decisions, you can
12431 specify one with --tool, see hg help merge-tools. As a caveat: the
12432 tool will not be used to mediate when a file was deleted, there is no
12433 hook presently available for this.
12434 If a rebase is interrupted to manually resolve a conflict, it can be
12436 continued with --continue/-c, aborted with --abort/-a, or stopped with
12437 --stop.
12438 Examples:
12440 · move "local changes" (current commit back to branching point) to the
12442 current branch tip after a pull:
12443 hg rebase
12445 · move a single changeset to the stable branch:
12447 hg rebase -r 5f493448 -d stable
12449 · splice a commit and all its descendants onto another part of history:
12451 hg rebase --source c0c3 --dest 4cf9
12453 · rebase everything on a branch marked by a bookmark onto the default
12455 branch:
12456 hg rebase --base myfeature --dest default
12458 · collapse a sequence of changes into a single commit:
12460 hg rebase --collapse -r 1520:1525 -d .
12462 · move a named branch while preserving its name:
12464 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
12466 · stabilize orphaned changesets so history looks linear:
12468 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
12470 Configuration Options:
12472 You can make rebase require a destination if you set the following con‐
12474 fig option:
12475 [commands]
12477 rebase.requiredest = True
12478 By default, rebase will close the transaction after each commit. For
12480 performance purposes, you can configure rebase to use a single transac‐
12481 tion across the entire rebase. WARNING: This setting introduces a sig‐
12482 nificant risk of losing the work you've done in a rebase if the rebase
12483 aborts unexpectedly:
12484 [rebase]
12486 singletransaction = True
12487 By default, rebase writes to the working copy, but you can configure it
12489 to run in-memory for for better performance, and to allow it to run if
12490 the working copy is dirty:
12491 [rebase]
12493 experimental.inmemory = True
12494 Return Values:
12496 Returns 0 on success, 1 if nothing to rebase or there are unresolved
12498 conflicts.
12499 Options:
12501 -s,--source <REV>
12503 rebase the specified changeset and descendants
12504 -b,--base <REV>
12506 rebase everything from branching point of specified changeset
12507 -r,--rev <REV[+]>
12509 rebase these revisions
12510 -d,--dest <REV>
12512 rebase onto the specified changeset
12513 --collapse
12515 collapse the rebased changesets
12516 -m,--message <TEXT>
12518 use text as collapse commit message
12519 -e, --edit
12521 invoke editor on commit messages
12522 -l,--logfile <FILE>
12524 read collapse commit message from file
12525 -k, --keep
12527 keep original changesets
12528 --keepbranches
12530 keep original branch names
12531 -D, --detach
12533 (DEPRECATED)
12534 -i, --interactive
12536 (DEPRECATED)
12537 -t,--tool <VALUE>
12539 specify merge tool
12540 --stop stop interrupted rebase
12542 -c, --continue
12544 continue an interrupted rebase
12545 -a, --abort
12547 abort an interrupted rebase
12548 --auto-orphans <VALUE>
12550 automatically rebase orphan revisions in the specified revset
12551 (EXPERIMENTAL)
12552 -n, --dry-run
12554 do not perform actions, just print output
12555 -T,--template <TEMPLATE>
12557 display with template
12558 --confirm
12560 ask before applying actions
12561 [+] marked option can be specified multiple times
12563 record
12565 commands to interactively select changes for commit/qrefresh (DEPRE‐
12566 CATED)
12567 The feature provided by this extension has been moved into core Mercu‐
12569 rial as hg commit --interactive.
12570 Commands
12572 qrecord
12573 interactively record a new patch:
12574 hg qrecord [OPTION]... PATCH [FILE]...
12576 See hg help qnew & hg help record for more information and usage.
12578 record
12580 interactively select changes to commit:
12581 hg record [OPTION]... [FILE]...
12583 If a list of files is omitted, all changes reported by hg status will
12585 be candidates for recording.
12586 See hg help dates for a list of formats valid for -d/--date.
12588 If using the text interface (see hg help config), you will be prompted
12590 for whether to record changes to each modified file, and for files with
12591 multiple changes, for each change to use. For each query, the following
12592 responses are possible:
12593 y - record this change
12595 n - skip this change
12596 e - edit this change manually
12597 s - skip remaining changes to this file
12599 f - record remaining changes to this file
12600 d - done, skip remaining changes and files
12602 a - record all changes to all remaining files
12603 q - quit, recording no changes
12604 ? - display help
12606 This command is not available when committing a merge.
12608 Options:
12610 -A, --addremove
12612 mark new/missing files as added/removed before committing
12613 --close-branch
12615 mark a branch head as closed
12616 --amend
12618 amend the parent of the working directory
12619 -s, --secret
12621 use the secret phase for committing
12622 -e, --edit
12624 invoke editor on commit messages
12625 -I,--include <PATTERN[+]>
12627 include names matching the given patterns
12628 -X,--exclude <PATTERN[+]>
12630 exclude names matching the given patterns
12631 -m,--message <TEXT>
12633 use text as commit message
12634 -l,--logfile <FILE>
12636 read commit message from file
12637 -d,--date <DATE>
12639 record the specified date as commit date
12640 -u,--user <USER>
12642 record the specified user as committer
12643 -S, --subrepos
12645 recurse into subrepositories
12646 -w, --ignore-all-space
12648 ignore white space when comparing lines
12649 -b, --ignore-space-change
12651 ignore changes in the amount of white space
12652 -B, --ignore-blank-lines
12654 ignore changes whose lines are all blank
12655 -Z, --ignore-space-at-eol
12657 ignore changes in whitespace at EOL
12658 [+] marked option can be specified multiple times
12660 releasenotes
12662 generate release notes from commit messages (EXPERIMENTAL)
12663 It is common to maintain files detailing changes in a project between
12665 releases. Maintaining these files can be difficult and time consuming.
12666 The hg releasenotes command provided by this extension makes the
12667 process simpler by automating it.
12668 Commands
12670 releasenotes
12671 parse release notes from commit messages into an output file:
12672 hg releasenotes [-r REV] [-c] FILE
12674 Given an output file and set of revisions, this command will parse com‐
12676 mit messages for release notes then add them to the output file.
12677 Release notes are defined in commit messages as ReStructuredText direc‐
12679 tives. These have the form:
12680 .. directive:: title
12682 content
12684 Each directive maps to an output section in a generated release notes
12686 file, which itself is ReStructuredText. For example, the .. feature::
12687 directive would map to a New Features section.
12688 Release note directives can be either short-form or long-form. In
12690 short- form, title is omitted and the release note is rendered as a
12691 bullet list. In long form, a sub-section with the title title is added
12692 to the section.
12693 The FILE argument controls the output file to write gathered release
12695 notes to. The format of the file is:
12696 Section 1
12698 =========
12699 ...
12701 Section 2
12703 =========
12704 ...
12706 Only sections with defined release notes are emitted.
12708 If a section only has short-form notes, it will consist of bullet list:
12710 Section
12712 =======
12713 * Release note 1
12715 * Release note 2
12716 If a section has long-form notes, sub-sections will be emitted:
12718 Section
12720 =======
12721 Note 1 Title
12723 ------------
12724 Description of the first long-form note.
12726 Note 2 Title
12728 ------------
12729 Description of the second long-form note.
12731 If the FILE argument points to an existing file, that file will be
12733 parsed for release notes having the format that would be generated by
12734 this command. The notes from the processed commit messages will be
12735 merged into this parsed set.
12736 During release notes merging:
12738 · Duplicate items are automatically ignored
12740 · Items that are different are automatically ignored if the similarity
12742 is greater than a threshold.
12743 This means that the release notes file can be updated independently
12745 from this command and changes should not be lost when running this com‐
12746 mand on that file. A particular use case for this is to tweak the word‐
12747 ing of a release note after it has been added to the release notes
12748 file.
12749 The -c/--check option checks the commit message for invalid admoni‐
12751 tions.
12752 The -l/--list option, presents the user with a list of existing avail‐
12754 able admonitions along with their title. This also includes the custom
12755 admonitions (if any).
12756 Options:
12758 -r,--rev <REV>
12760 revisions to process for release notes
12761 -c, --check
12763 checks for validity of admonitions (if any)
12764 -l, --list
12766 list the available admonitions with their title
12767 relink
12769 recreates hardlinks between repository clones
12770 Commands
12772 relink
12773 recreate hardlinks between two repositories:
12774 hg relink [ORIGIN]
12776 When repositories are cloned locally, their data files will be
12778 hardlinked so that they only use the space of a single repository.
12779 Unfortunately, subsequent pulls into either repository will break
12781 hardlinks for any files touched by the new changesets, even if both
12782 repositories end up pulling the same changes.
12783 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
12785 falling back to a complete copy of the source repository.
12786 This command lets you recreate those hardlinks and reclaim that wasted
12788 space.
12789 This repository will be relinked to share space with ORIGIN, which must
12791 be on the same local disk. If ORIGIN is omitted, looks for
12792 "default-relink", then "default", in [paths].
12793 Do not attempt any read operations on this repository while the command
12795 is running. (Both repositories will be locked against writes.)
12796 remotefilelog
12798 remotefilelog causes Mercurial to lazilly fetch file contents (EXPERI‐
12799 MENTAL)
12800 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
12802 BILITY GUARANTEES. This means that repositories created with this
12803 extension may only be usable with the exact version of this exten‐
12804 sion/Mercurial that was used. The extension attempts to enforce this in
12805 order to prevent repository corruption.
12806 remotefilelog works by fetching file contents lazily and storing them
12808 in a cache on the client rather than in revlogs. This allows enormous
12809 histories to be transferred only partially, making them easier to oper‐
12810 ate on.
12811 Configs:
12813 packs.maxchainlen specifies the maximum delta chain length in pack
12815 files
12816 packs.maxpacksize specifies the maximum pack file size
12818 packs.maxpackfilecount specifies the maximum number of packs in the
12820 shared cache (trees only for now)
12822 remotefilelog.backgroundprefetch runs prefetch in background when
12824 True
12825 remotefilelog.bgprefetchrevs specifies revisions to fetch on commit
12827 and
12828 update, and on other commands that use them. Different from
12830 pullprefetch.
12831 remotefilelog.gcrepack does garbage collection during repack when
12833 True
12834 remotefilelog.nodettl specifies maximum TTL of a node in seconds
12836 before
12837 it is garbage collected
12839 remotefilelog.repackonhggc runs repack on hg gc when True
12841 remotefilelog.prefetchdays specifies the maximum age of a commit in
12843 days after which it is no longer prefetched.
12845 remotefilelog.prefetchdelay specifies delay between background
12847 prefetches in seconds after operations that change the work‐
12849 ing copy parent
12850 remotefilelog.data.gencountlimit constraints the minimum number of
12852 data
12853 pack files required to be considered part of a generation. In
12855 particular, minimum number of packs files > gencountlimit.
12856 remotefilelog.data.generations list for specifying the lower bound
12858 of
12859 each generation of the data pack files. For example, list
12861 ['100MB','1MB'] or ['1MB', '100MB'] will lead to three gener‐
12862 ations: [0, 1MB), [ 1MB, 100MB) and [100MB, infinity).
12863 remotefilelog.data.maxrepackpacks the maximum number of pack files
12865 to
12866 include in an incremental data repack.
12868 remotefilelog.data.repackmaxpacksize the maximum size of a pack file
12870 for
12871 it to be considered for an incremental data repack.
12873 remotefilelog.data.repacksizelimit the maximum total size of pack
12875 files
12876 to include in an incremental data repack.
12878 remotefilelog.history.gencountlimit constraints the minimum number
12880 of
12881 history pack files required to be considered part of a gener‐
12883 ation. In particular, minimum number of packs files > gen‐
12884 countlimit.
12885 remotefilelog.history.generations list for specifying the lower
12887 bound of
12888 each generation of the history pack files. For example, list
12890 [ '100MB', '1MB'] or ['1MB', '100MB'] will lead to three gen‐
12891 erations: [ 0, 1MB), [1MB, 100MB) and [100MB, infinity).
12892 remotefilelog.history.maxrepackpacks the maximum number of pack
12894 files to
12895 include in an incremental history repack.
12897 remotefilelog.history.repackmaxpacksize the maximum size of a pack
12899 file
12900 for it to be considered for an incremental history repack.
12902 remotefilelog.history.repacksizelimit the maximum total size of pack
12904 files to include in an incremental history repack.
12906 remotefilelog.backgroundrepack automatically consolidate packs in
12908 the
12909 background
12911 remotefilelog.cachepath path to cache
12913 remotefilelog.cachegroup if set, make cache directory sgid to this
12915 group
12917 remotefilelog.cacheprocess binary to invoke for fetching file data
12919 remotefilelog.debug turn on remotefilelog-specific debug output
12921 remotefilelog.excludepattern pattern of files to exclude from pulls
12923 remotefilelog.includepattern pattern of files to include in pulls
12925 remotefilelog.fetchwarning: message to print when too many
12927 single-file fetches occur
12929 remotefilelog.getfilesstep number of files to request in a single
12931 RPC
12932 remotefilelog.getfilestype if set to 'threaded' use threads to fetch
12934 files, otherwise use optimistic fetching
12936 remotefilelog.pullprefetch revset for selecting files that should be
12938 eagerly downloaded rather than lazily
12940 remotefilelog.reponame name of the repo. If set, used to partition
12942 data from other repos in a shared store.
12944 remotefilelog.server if true, enable server-side functionality
12946 remotefilelog.servercachepath path for caching blobs on the server
12948 remotefilelog.serverexpiration number of days to keep cached server
12950 blobs
12952 remotefilelog.validatecache if set, check cache entries for corrup‐
12954 tion
12955 before returning blobs
12957 remotefilelog.validatecachelog if set, check cache entries for
12959 corruption before returning metadata
12961 Commands
12963 gc
12964 garbage collect the client and server filelog caches:
12965 hg gc [REPO...]
12967 garbage collect the client and server filelog caches
12969 prefetch
12971 prefetch file revisions from the server:
12972 hg prefetch [OPTIONS] [FILE...]
12974 Prefetchs file revisions for the specified revs and stores them in the
12976 local remotefilelog cache. If no rev is specified, the default rev is
12977 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
12978 File names or patterns can be used to limit which files are downloaded.
12979 Return 0 on success.
12981 Options:
12983 -r,--rev <REV[+]>
12985 prefetch the specified revisions
12986 --repack
12988 run repack after prefetch
12989 -b,--base <VALUE>
12991 rev that is assumed to already be local
12992 -I,--include <PATTERN[+]>
12994 include names matching the given patterns
12995 -X,--exclude <PATTERN[+]>
12997 exclude names matching the given patterns
12998 [+] marked option can be specified multiple times
13000 repack
13002 hg repack [OPTIONS]
13003 Options:
13005 --background
13007 run in a background process
13008 --incremental
13010 do an incremental repack
13011 --packsonly
13013 only repack packs (skip loose objects)
13014 verifyremotefilelog
13016 hg verifyremotefilelogs <directory>
13017 Options:
13019 -d, --decompress
13021 decompress the filelogs first
13022 remotenames
13024 showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)
13025 By default both remotebookmarks and remotebranches are turned on. Con‐
13027 fig knob to control the individually are as follows.
13028 Config options to tweak the default behaviour:
13030 remotenames.bookmarks
13032 Boolean value to enable or disable showing of remotebookmarks
13033 (default: True)
13034 remotenames.branches
13036 Boolean value to enable or disable showing of remotebranches
13037 (default: True)
13038 remotenames.hoistedpeer
13040 Name of the peer whose remotebookmarks should be hoisted into
13041 the top-level namespace (default: 'default')
13042 schemes
13044 extend schemes with shortcuts to repository swarms
13045 This extension allows you to specify shortcuts for parent URLs with a
13047 lot of repositories to act like a scheme, for example:
13048 [schemes]
13050 py = http://code.python.org/hg/
13051 After that you can use it like:
13053 hg clone py://trunk/
13055 Additionally there is support for some more complex schemas, for exam‐
13057 ple used by Google Code:
13058 [schemes]
13060 gcode = http://{1}.googlecode.com/hg/
13061 The syntax is taken from Mercurial templates, and you have unlimited
13063 number of variables, starting with {1} and continuing with {2}, {3} and
13064 so on. This variables will receive parts of URL supplied, split by /.
13065 Anything not specified as {part} will be just appended to an URL.
13066 For convenience, the extension adds these schemes by default:
13068 [schemes]
13070 py = http://hg.python.org/
13071 bb = https://bitbucket.org/
13072 bb+ssh = ssh://hg@bitbucket.org/
13073 gcode = https://{1}.googlecode.com/hg/
13074 kiln = https://{1}.kilnhg.com/Repo/
13075 You can override a predefined scheme by defining a new scheme with the
13077 same name.
13078 Commands
13080 share
13081 share a common history between several working directories
13082 Automatic Pooled Storage for Clones
13084 When this extension is active, hg clone can be configured to automati‐
13085 cally share/pool storage across multiple clones. This mode effectively
13086 converts hg clone to hg clone + hg share. The benefit of using this
13087 mode is the automatic management of store paths and intelligent pooling
13088 of related repositories.
13089 The following share. config options influence this feature:
13091 share.pool
13093 Filesystem path where shared repository data will be stored.
13095 When defined, hg clone will automatically use shared repository
13096 storage instead of creating a store inside each clone.
13097 share.poolnaming
13099 How directory names in share.pool are constructed.
13101 "identity" means the name is derived from the first changeset in
13103 the repository. In this mode, different remotes share storage if
13104 their root/initial changeset is identical. In this mode, the
13105 local shared repository is an aggregate of all encountered
13106 remote repositories.
13107 "remote" means the name is derived from the source repository's
13109 path or URL. In this mode, storage is only shared if the path or
13110 URL requested in the hg clone command matches exactly to a
13111 repository that was cloned before.
13112 The default naming mode is "identity".
13114 Commands
13116 share
13117 create a new shared repository:
13118 hg share [-U] [-B] SOURCE [DEST]
13120 Initialize a new repository and working directory that shares its his‐
13122 tory (and optionally bookmarks) with another repository.
13123 Note using rollback or extensions that destroy/modify history (mq,
13125 rebase, etc.) can cause considerable confusion with shared
13126 clones. In particular, if two shared clones are both updated to
13127 the same changeset, and one of them destroys that changeset with
13128 rollback, the other clone will suddenly stop working: all opera‐
13129 tions will fail with "abort: working directory has unknown par‐
13130 ent". The only known workaround is to use debugsetparents on the
13131 broken clone to reset it to a changeset that still exists.
13132 Options:
13134 -U, --noupdate
13136 do not create a working directory
13137 -B, --bookmarks
13139 also share bookmarks
13140 --relative
13142 point to source using a relative path (EXPERIMENTAL)
13143 unshare
13145 convert a shared repository to a normal one:
13146 hg unshare
13148 Copy the store data to the repo and remove the sharedpath data.
13150 shelve
13152 save and restore changes to the working directory
13153 The "hg shelve" command saves changes made to the working directory and
13155 reverts those changes, resetting the working directory to a clean
13156 state.
13157 Later on, the "hg unshelve" command restores the changes saved by "hg
13159 shelve". Changes can be restored even after updating to a different
13160 parent, in which case Mercurial's merge machinery will resolve any con‐
13161 flicts if necessary.
13162 You can have more than one shelved change outstanding at a time; each
13164 shelved change has a distinct name. For details, see the help for "hg
13165 shelve".
13166 Commands
13168 shelve
13169 save and set aside changes from the working directory:
13170 hg shelve [OPTION]... [FILE]...
13172 Shelving takes files that "hg status" reports as not clean, saves the
13174 modifications to a bundle (a shelved change), and reverts the files so
13175 that their state in the working directory becomes clean.
13176 To restore these changes to the working directory, using "hg unshelve";
13178 this will work even if you switch to a different commit.
13179 When no files are specified, "hg shelve" saves all not-clean files. If
13181 specific files or directories are named, only changes to those files
13182 are shelved.
13183 In bare shelve (when no files are specified, without interactive,
13185 include and exclude option), shelving remembers information if the
13186 working directory was on newly created branch, in other words working
13187 directory was on different branch than its first parent. In this situa‐
13188 tion unshelving restores branch information to the working directory.
13189 Each shelved change has a name that makes it easier to find later. The
13191 name of a shelved change defaults to being based on the active book‐
13192 mark, or if there is no active bookmark, the current named branch. To
13193 specify a different name, use --name.
13194 To see a list of existing shelved changes, use the --list option. For
13196 each shelved change, this will print its name, age, and description;
13197 use --patch or --stat for more details.
13198 To delete specific shelved changes, use --delete. To delete all shelved
13200 changes, use --cleanup.
13201 Options:
13203 -A, --addremove
13205 mark new/missing files as added/removed before shelving
13206 -u, --unknown
13208 store unknown files in the shelve
13209 --cleanup
13211 delete all shelved changes
13212 --date <DATE>
13214 shelve with the specified commit date
13215 -d, --delete
13217 delete the named shelved change(s)
13218 -e, --edit
13220 invoke editor on commit messages
13221 -l, --list
13223 list current shelves
13224 -m,--message <TEXT>
13226 use text as shelve message
13227 -n,--name <NAME>
13229 use the given name for the shelved commit
13230 -p, --patch
13232 output patches for changes (provide the names of the shelved
13233 changes as positional arguments)
13234 -i, --interactive
13236 interactive mode, only works while creating a shelve
13237 --stat output diffstat-style summary of changes (provide the names of
13239 the shelved changes as positional arguments)
13240 -I,--include <PATTERN[+]>
13242 include names matching the given patterns
13243 -X,--exclude <PATTERN[+]>
13245 exclude names matching the given patterns
13246 [+] marked option can be specified multiple times
13248 unshelve
13250 restore a shelved change to the working directory:
13251 hg unshelve [[-n] SHELVED]
13253 This command accepts an optional name of a shelved change to restore.
13255 If none is given, the most recent shelved change is used.
13256 If a shelved change is applied successfully, the bundle that contains
13258 the shelved changes is moved to a backup location (.hg/shelve-backup).
13259 Since you can restore a shelved change on top of an arbitrary commit,
13261 it is possible that unshelving will result in a conflict between your
13262 changes and the commits you are unshelving onto. If this occurs, you
13263 must resolve the conflict, then use --continue to complete the unshelve
13264 operation. (The bundle will not be moved until you successfully com‐
13265 plete the unshelve.)
13266 (Alternatively, you can use --abort to abandon an unshelve that causes
13268 a conflict. This reverts the unshelved changes, and leaves the bundle
13269 in place.)
13270 If bare shelved change(when no files are specified, without interac‐
13272 tive, include and exclude option) was done on newly created branch it
13273 would restore branch information to the working directory.
13274 After a successful unshelve, the shelved changes are stored in a backup
13276 directory. Only the N most recent backups are kept. N defaults to 10
13277 but can be overridden using the shelve.maxbackups configuration option.
13278 Timestamp in seconds is used to decide order of backups. More than
13280 maxbackups backups are kept, if same timestamp prevents from deciding
13281 exact order of them, for safety.
13282 Options:
13284 -a, --abort
13286 abort an incomplete unshelve operation
13287 -c, --continue
13289 continue an incomplete unshelve operation
13290 -k, --keep
13292 keep shelve after unshelving
13293 -n,--name <NAME>
13295 restore shelved change with given name
13296 -t,--tool <VALUE>
13298 specify merge tool
13299 --date <DATE>
13301 set date for temporary commits (DEPRECATED)
13302 show
13304 unified command to show various repository information (EXPERIMENTAL)
13305 This extension provides the hg show command, which provides a central
13307 command for displaying commonly-accessed repository data and views of
13308 that data.
13309 The following config options can influence operation.
13311 commands
13313 show.aliasprefix
13314 List of strings that will register aliases for views. e.g. s
13316 will effectively set config options alias.s<view> = show <view>
13317 for all views. i.e. hg swork would execute hg show work.
13318 Aliases that would conflict with existing registrations will not
13320 be performed.
13321 Commands
13323 show
13324 show various repository information:
13325 hg show VIEW
13327 A requested view of repository data is displayed.
13329 If no view is requested, the list of available views is shown and the
13331 command aborts.
13332 Note There are no backwards compatibility guarantees for the output
13334 of this command. Output may change in any future Mercurial
13335 release.
13336 Consumers wanting stable command output should specify a tem‐
13338 plate via -T/--template.
13339 List of available views:
13341 bookmarks bookmarks and their associated changeset
13343 stack current line of work
13345 work changesets that aren't finished
13347 Options:
13349 -T,--template <TEMPLATE>
13351 display with template
13352 sparse
13354 allow sparse checkouts of the working directory (EXPERIMENTAL)
13355 (This extension is not yet protected by backwards compatibility guaran‐
13357 tees. Any aspect may break in future releases until this notice is
13358 removed.)
13359 This extension allows the working directory to only consist of a subset
13361 of files for the revision. This allows specific files or directories to
13362 be explicitly included or excluded. Many repository operations have
13363 performance proportional to the number of files in the working direc‐
13364 tory. So only realizing a subset of files in the working directory can
13365 improve performance.
13366 Sparse Config Files
13368 The set of files that are part of a sparse checkout are defined by a
13369 sparse config file. The file defines 3 things: includes (files to
13370 include in the sparse checkout), excludes (files to exclude from the
13371 sparse checkout), and profiles (links to other config files).
13372 The file format is newline delimited. Empty lines and lines beginning
13374 with # are ignored.
13375 Lines beginning with %include `` denote another sparse config file to
13377 include. e.g. ``%include tests.sparse. The filename is relative to the
13378 repository root.
13379 The special lines [include] and [exclude] denote the section for
13381 includes and excludes that follow, respectively. It is illegal to have
13382 [include] after [exclude].
13383 Non-special lines resemble file patterns to be added to either includes
13385 or excludes. The syntax of these lines is documented by hg help pat‐
13386 terns. Patterns are interpreted as glob: by default and match against
13387 the root of the repository.
13388 Exclusion patterns take precedence over inclusion patterns. So even if
13390 a file is explicitly included, an [exclude] entry can remove it.
13391 For example, say you have a repository with 3 directories, frontend/,
13393 backend/, and tools/. frontend/ and backend/ correspond to different
13394 projects and it is uncommon for someone working on one to need the
13395 files for the other. But tools/ contains files shared between both
13396 projects. Your sparse config files may resemble:
13397 # frontend.sparse
13399 frontend/**
13400 tools/**
13401 # backend.sparse
13403 backend/**
13404 tools/**
13405 Say the backend grows in size. Or there's a directory with thousands of
13407 files you wish to exclude. You can modify the profile to exclude cer‐
13408 tain files:
13409 [include]
13411 backend/**
13412 tools/**
13413 [exclude]
13415 tools/tests/**
13416 Commands
13418 split
13419 command to split a changeset into smaller ones (EXPERIMENTAL)
13420 Commands
13422 split
13423 split a changeset into smaller ones:
13424 hg split [--no-rebase] [[-r] REV]
13426 Repeatedly prompt changes and commit message for new changesets until
13428 there is nothing left in the original changeset.
13429 If --rev was not given, split the working directory parent.
13431 By default, rebase connected non-obsoleted descendants onto the new
13433 changeset. Use --no-rebase to avoid the rebase.
13434 Options:
13436 -r,--rev <REV>
13438 revision to split
13439 --rebase
13441 rebase descendants after split (default: True)
13442 -d,--date <DATE>
13444 record the specified date as commit date
13445 -u,--user <USER>
13447 record the specified user as committer
13448 sqlitestore
13450 store repository data in SQLite (EXPERIMENTAL)
13451 The sqlitestore extension enables the storage of repository data in
13453 SQLite.
13454 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13456 BILITY GUARANTEES. This means that repositories created with this
13457 extension may only be usable with the exact version of this exten‐
13458 sion/Mercurial that was used. The extension attempts to enforce this in
13459 order to prevent repository corruption.
13460 In addition, several features are not yet supported or have known bugs:
13462 · Only some data is stored in SQLite. Changeset, manifest, and other
13464 repository data is not yet stored in SQLite.
13465 · Transactions are not robust. If the process is aborted at the right
13467 time during transaction close/rollback, the repository could be in an
13468 inconsistent state. This problem will diminish once all repository
13469 data is tracked by SQLite.
13470 · Bundle repositories do not work (the ability to use e.g. hg -R <bun‐
13472 dle-file> log to automatically overlay a bundle on top of the exist‐
13473 ing repository).
13474 · Various other features don't work.
13476 This extension should work for basic clone/pull, update, and commit
13478 workflows. Some history rewriting operations may fail due to lack of
13479 support for bundle repositories.
13480 To use, activate the extension and set the storage.new-repo-backend
13482 config option to sqlite to enable new repositories to use SQLite for
13483 storage.
13484 strip
13486 strip changesets and their descendants from history
13487 This extension allows you to strip changesets and all their descendants
13489 from the repository. See the command help for details.
13490 Commands
13492 strip
13493 strip changesets and all their descendants from the repository:
13494 hg strip [-k] [-f] [-B bookmark] [-r] REV...
13496 The strip command removes the specified changesets and all their
13498 descendants. If the working directory has uncommitted changes, the
13499 operation is aborted unless the --force flag is supplied, in which case
13500 changes will be discarded.
13501 If a parent of the working directory is stripped, then the working
13503 directory will automatically be updated to the most recent available
13504 ancestor of the stripped parent after the operation completes.
13505 Any stripped changesets are stored in .hg/strip-backup as a bundle (see
13507 hg help bundle and hg help unbundle). They can be restored by running
13508 hg unbundle .hg/strip-backup/BUNDLE, where BUNDLE is the bundle file
13509 created by the strip. Note that the local revision numbers will in gen‐
13510 eral be different after the restore.
13511 Use the --no-backup option to discard the backup bundle once the opera‐
13513 tion completes.
13514 Strip is not a history-rewriting operation and can be used on change‐
13516 sets in the public phase. But if the stripped changesets have been
13517 pushed to a remote repository you will likely pull them again.
13518 Return 0 on success.
13520 Options:
13522 -r,--rev <REV[+]>
13524 strip specified revision (optional, can specify revisions with‐
13525 out this option)
13526 -f, --force
13528 force removal of changesets, discard uncommitted changes (no
13529 backup)
13530 --no-backup
13532 do not save backup bundle
13533 --nobackup
13535 do not save backup bundle (DEPRECATED)
13536 -n ignored (DEPRECATED)
13538 -k, --keep
13540 do not modify working directory during strip
13541 -B,--bookmark <BOOKMARK[+]>
13543 remove revs only reachable from given bookmark
13544 [+] marked option can be specified multiple times
13546 transplant
13548 command to transplant changesets from another branch
13549 This extension allows you to transplant changes to another parent revi‐
13551 sion, possibly in another repository. The transplant is done using
13552 'diff' patches.
13553 Transplanted patches are recorded in .hg/transplant/transplants, as a
13555 map from a changeset hash to its hash in the source repository.
13556 Commands
13558 transplant
13559 transplant changesets from another branch:
13560 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
13562 Selected changesets will be applied on top of the current working
13564 directory with the log of the original changeset. The changesets are
13565 copied and will thus appear twice in the history with different identi‐
13566 ties.
13567 Consider using the graft command if everything is inside the same
13569 repository - it will use merges and will usually give a better result.
13570 Use the rebase extension if the changesets are unpublished and you want
13571 to move them instead of copying them.
13572 If --log is specified, log messages will have a comment appended of the
13574 form:
13575 (transplanted from CHANGESETHASH)
13577 You can rewrite the changelog message with the --filter option. Its
13579 argument will be invoked with the current changelog message as $1 and
13580 the patch as $2.
13581 --source/-s specifies another repository to use for selecting change‐
13583 sets, just as if it temporarily had been pulled. If --branch/-b is
13584 specified, these revisions will be used as heads when deciding which
13585 changesets to transplant, just as if only these revisions had been
13586 pulled. If --all/-a is specified, all the revisions up to the heads
13587 specified with --branch will be transplanted.
13588 Example:
13590 · transplant all changes up to REV on top of your current revision:
13592 hg transplant --branch REV --all
13594 You can optionally mark selected transplanted changesets as merge
13596 changesets. You will not be prompted to transplant any ancestors of a
13597 merged transplant, and you can merge descendants of them normally
13598 instead of transplanting them.
13599 Merge changesets may be transplanted directly by specifying the proper
13601 parent changeset by calling hg transplant --parent.
13602 If no merges or revisions are provided, hg transplant will start an
13604 interactive changeset browser.
13605 If a changeset application fails, you can fix the merge by hand and
13607 then resume where you left off by calling hg transplant --continue/-c.
13608 Options:
13610 -s,--source <REPO>
13612 transplant changesets from REPO
13613 -b,--branch <REV[+]>
13615 use this source changeset as head
13616 -a, --all
13618 pull all changesets up to the --branch revisions
13619 -p,--prune <REV[+]>
13621 skip over REV
13622 -m,--merge <REV[+]>
13624 merge at REV
13625 --parent <REV>
13627 parent to choose when transplanting merge
13628 -e, --edit
13630 invoke editor on commit messages
13631 --log append transplant info to log message
13633 -c, --continue
13635 continue last transplant session after fixing conflicts
13636 --filter <CMD>
13638 filter changesets through command
13639 [+] marked option can be specified multiple times
13641 uncommit
13643 uncommit part or all of a local changeset (EXPERIMENTAL)
13644 This command undoes the effect of a local commit, returning the
13646 affected files to their uncommitted state. This means that files modi‐
13647 fied, added or removed in the changeset will be left unchanged, and so
13648 will remain modified, added and removed in the working directory.
13649 Commands
13651 unamend
13652 undo the most recent amend operation on a current changeset:
13653 hg unamend
13655 This command will roll back to the previous version of a changeset,
13657 leaving working directory in state in which it was before running hg
13658 amend (e.g. files modified as part of an amend will be marked as modi‐
13659 fied hg status)
13660 uncommit
13662 uncommit part or all of a local changeset:
13663 hg uncommit [OPTION]... [FILE]...
13665 This command undoes the effect of a local commit, returning the
13667 affected files to their uncommitted state. This means that files modi‐
13668 fied or deleted in the changeset will be left unchanged, and so will
13669 remain modified in the working directory.
13670 If no files are specified, the commit will be pruned, unless --keep is
13672 given.
13673 Options:
13675 --keep allow an empty commit after uncommiting
13677 -I,--include <PATTERN[+]>
13679 include names matching the given patterns
13680 -X,--exclude <PATTERN[+]>
13682 exclude names matching the given patterns
13683 [+] marked option can be specified multiple times
13685 win32mbcs
13687 allow the use of MBCS paths with problematic encodings
13688 Some MBCS encodings are not good for some path operations (i.e. split‐
13690 ting path, case conversion, etc.) with its encoded bytes. We call such
13691 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
13692 extension can be used to fix the issue with those encodings by wrapping
13693 some functions to convert to Unicode string before path operation.
13694 This extension is useful for:
13696 · Japanese Windows users using shift_jis encoding.
13698 · Chinese Windows users using big5 encoding.
13700 · All users who use a repository with one of problematic encodings on
13702 case-insensitive file system.
13703 This extension is not needed for:
13705 · Any user who use only ASCII chars in path.
13707 · Any user who do not use any of problematic encodings.
13709 Note that there are some limitations on using this extension:
13711 · You should use single encoding in one repository.
13713 · If the repository path ends with 0x5c, .hg/hgrc cannot be read.
13715 · win32mbcs is not compatible with fixutf8 extension.
13717 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
13719 can specify the encoding by config option:
13720 [win32mbcs]
13722 encoding = sjis
13723 It is useful for the users who want to commit with UTF-8 log message.
13725 win32text
13727 perform automatic newline conversion (DEPRECATED)
13728 Deprecation: The win32text extension requires each user to configure
13730 the extension again and again for each clone since the configuration
13731 is not copied when cloning.
13732 We have therefore made the eol as an alternative. The eol uses a
13734 version controlled file for its configuration and each clone will
13735 therefore use the right settings from the start.
13736 To perform automatic newline conversion, use:
13738 [extensions]
13740 win32text =
13741 [encode]
13742 ** = cleverencode:
13743 # or ** = macencode:
13744 [decode]
13746 ** = cleverdecode:
13747 # or ** = macdecode:
13748 If not doing conversion, to make sure you do not commit CRLF/CR by
13750 accident:
13751 [hooks]
13753 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
13754 # or pretxncommit.cr = python:hgext.win32text.forbidcr
13755 To do the same check on a server to prevent CRLF/CR from being pushed
13757 or pulled:
13758 [hooks]
13760 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
13761 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
13762 zeroconf
13764 discover and advertise repositories on the local network
13765 Zeroconf-enabled repositories will be announced in a network without
13767 the need to configure a server or a service. They can be discovered
13768 without knowing their actual IP address.
13769 To allow other people to discover your repository using run hg serve in
13771 your repository:
13772 $ cd test
13774 $ hg serve
13775 You can discover Zeroconf-enabled repositories by running hg paths:
13777 $ hg paths
13779 zc-test = http://example.com:8000/test
13780
13782 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
13783 This file contains defaults and configuration. Values in
13785 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
13786 tings made in the global /etc/mercurial/hgrc configuration. See
13787 hgrc(5) for details of the contents and format of these files.
13788 .hgignore
13790 This file contains regular expressions (one per line) that
13792 describe file names that should be ignored by hg. For details,
13793 see hgignore(5).
13794 .hgsub
13796 This file defines the locations of all subrepositories, and
13798 tells where the subrepository checkouts came from. For details,
13799 see hg help subrepos.
13800 .hgsubstate
13802 This file is where Mercurial stores all nested repository
13804 states. NB: This file should not be edited manually.
13805 .hgtags
13807 This file contains changeset hash values and text tag names (one
13809 of each separated by spaces) that correspond to tagged versions
13810 of the repository contents. The file content is encoded using
13811 UTF-8.
13812 .hg/last-message.txt
13814 This file is used by hg commit to store a backup of the commit
13816 message in case the commit fails.
13817 .hg/localtags
13819 This file can be used to define local tags which are not shared
13821 among repositories. The file format is the same as for .hgtags,
13822 but it is encoded using the local system encoding.
13823 Some commands (e.g. revert) produce backup files ending in .orig, if
13825 the .orig file already exists and is not tracked by Mercurial, it will
13826 be overwritten.
13827
13829 Probably lots, please post them to the mailing list (see Resources
13830 below) when you find them.
13831
13833 hgignore(5), hgrc(5)
13834
13836 Written by Matt Mackall <mpm@selenic.com>
13837
13839 Main Web Site: https://mercurial-scm.org/
13840 Source code repository: https://www.mercurial-scm.org/repo/hg
13842 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
13844
13846 Copyright (C) 2005-2019 Matt Mackall. Free use of this software is
13847 granted under the terms of the GNU General Public License version 2 or
13848 any later version.
13849
13851 Matt Mackall <mpm@selenic.com>
13852 Organization: Mercurial
13854 HG(1)