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 Returns 0 on success.
243 Options:
245 -r,--rev <REV>
247 annotate the specified revision
248 --follow
250 follow copies/renames and list the filename (DEPRECATED)
251 --no-follow
253 don't follow copies and renames
254 -a, --text
256 treat all files as text
257 -u, --user
259 list the author (long with -v)
260 -f, --file
262 list the filename
263 -d, --date
265 list the date (short with -q)
266 -n, --number
268 list the revision number (default)
269 -c, --changeset
271 list the changeset
272 -l, --line-number
274 show line number at the first appearance
275 --skip <REV[+]>
277 revision to not display (EXPERIMENTAL)
278 -w, --ignore-all-space
280 ignore white space when comparing lines
281 -b, --ignore-space-change
283 ignore changes in the amount of white space
284 -B, --ignore-blank-lines
286 ignore changes whose lines are all blank
287 -Z, --ignore-space-at-eol
289 ignore changes in whitespace at EOL
290 -I,--include <PATTERN[+]>
292 include names matching the given patterns
293 -X,--exclude <PATTERN[+]>
295 exclude names matching the given patterns
296 -T,--template <TEMPLATE>
298 display with template (EXPERIMENTAL)
299 [+] marked option can be specified multiple times
301 aliases: blame
303 archive
305 create an unversioned archive of a repository revision:
306 hg archive [OPTION]... DEST
308 By default, the revision used is the parent of the working directory;
310 use -r/--rev to specify a different revision.
311 The archive type is automatically detected based on file extension (to
313 override, use -t/--type).
314 Examples:
316 · create a zip file containing the 1.0 release:
318 hg archive -r 1.0 project-1.0.zip
320 · create a tarball excluding .hg files:
322 hg archive project.tar.gz -X ".hg*"
324 Valid types are:
326 files
328 a directory full of files (default)
330 tar
332 tar archive, uncompressed
334 tbz2
336 tar archive, compressed using bzip2
338 tgz
340 tar archive, compressed using gzip
342 uzip
344 zip archive, uncompressed
346 zip
348 zip archive, compressed using deflate
350 The exact name of the destination archive or directory is given using a
352 format string; see hg help export for details.
353 Each member added to an archive file has a directory prefix prepended.
355 Use -p/--prefix to specify a format string for the prefix. The default
356 is the basename of the archive, with suffixes removed.
357 Returns 0 on success.
359 Options:
361 --no-decode
363 do not pass files through decoders
364 -p,--prefix <PREFIX>
366 directory prefix for files in archive
367 -r,--rev <REV>
369 revision to distribute
370 -t,--type <TYPE>
372 type of distribution to create
373 -S, --subrepos
375 recurse into subrepositories
376 -I,--include <PATTERN[+]>
378 include names matching the given patterns
379 -X,--exclude <PATTERN[+]>
381 exclude names matching the given patterns
382 [+] marked option can be specified multiple times
384 backout
386 reverse effect of earlier changeset:
387 hg backout [OPTION]... [-r] REV
389 Prepare a new changeset with the effect of REV undone in the current
391 working directory. If no conflicts were encountered, it will be commit‐
392 ted immediately.
393 If REV is the parent of the working directory, then this new changeset
395 is committed automatically (unless --no-commit is specified).
396 Note hg backout cannot be used to fix either an unwanted or incorrect
398 merge.
399 Examples:
401 · Reverse the effect of the parent of the working directory. This
403 backout will be committed immediately:
404 hg backout -r .
406 · Reverse the effect of previous bad revision 23:
408 hg backout -r 23
410 · Reverse the effect of previous bad revision 23 and leave changes
412 uncommitted:
413 hg backout -r 23 --no-commit
415 hg commit -m "Backout revision 23"
416 By default, the pending changeset will have one parent, maintaining a
418 linear history. With --merge, the pending changeset will instead have
419 two parents: the old parent of the working directory and a new child of
420 REV that simply undoes REV.
421 Before version 1.7, the behavior without --merge was equivalent to
423 specifying --merge followed by hg update --clean . to cancel the merge
424 and leave the child of REV as a head to be merged separately.
425 See hg help dates for a list of formats valid for -d/--date.
427 See hg help revert for a way to restore files to the state of another
429 revision.
430 Returns 0 on success, 1 if nothing to backout or there are unresolved
432 files.
433 Options:
435 --merge
437 merge with old dirstate parent after backout
438 --commit
440 commit if no conflicts were encountered (DEPRECATED)
441 --no-commit
443 do not commit
444 --parent <REV>
446 parent to choose when backing out merge (DEPRECATED)
447 -r,--rev <REV>
449 revision to backout
450 -e, --edit
452 invoke editor on commit messages
453 -t,--tool <VALUE>
455 specify merge tool
456 -I,--include <PATTERN[+]>
458 include names matching the given patterns
459 -X,--exclude <PATTERN[+]>
461 exclude names matching the given patterns
462 -m,--message <TEXT>
464 use text as commit message
465 -l,--logfile <FILE>
467 read commit message from file
468 -d,--date <DATE>
470 record the specified date as commit date
471 -u,--user <USER>
473 record the specified user as committer
474 [+] marked option can be specified multiple times
476 bisect
478 subdivision search of changesets:
479 hg bisect [-gbsr] [-U] [-c CMD] [REV]
481 This command helps to find changesets which introduce problems. To use,
483 mark the earliest changeset you know exhibits the problem as bad, then
484 mark the latest changeset which is free from the problem as good.
485 Bisect will update your working directory to a revision for testing
486 (unless the -U/--noupdate option is specified). Once you have performed
487 tests, mark the working directory as good or bad, and bisect will
488 either update to another candidate changeset or announce that it has
489 found the bad revision.
490 As a shortcut, you can also use the revision argument to mark a revi‐
492 sion as good or bad without checking it out first.
493 If you supply a command, it will be used for automatic bisection. The
495 environment variable HG_NODE will contain the ID of the changeset being
496 tested. The exit status of the command will be used to mark revisions
497 as good or bad: status 0 means good, 125 means to skip the revision,
498 127 (command not found) will abort the bisection, and any other
499 non-zero exit status means the revision is bad.
500 Some examples:
502 · start a bisection with known bad revision 34, and good revision 12:
504 hg bisect --bad 34
506 hg bisect --good 12
507 · advance the current bisection by marking current revision as good or
509 bad:
510 hg bisect --good
512 hg bisect --bad
513 · mark the current revision, or a known revision, to be skipped (e.g.
515 if that revision is not usable because of another issue):
516 hg bisect --skip
518 hg bisect --skip 23
519 · skip all revisions that do not touch directories foo or bar:
521 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
523 · forget the current bisection:
525 hg bisect --reset
527 · use 'make && make tests' to automatically find the first broken revi‐
529 sion:
530 hg bisect --reset
532 hg bisect --bad 34
533 hg bisect --good 12
534 hg bisect --command "make && make tests"
535 · see all changesets whose states are already known in the current
537 bisection:
538 hg log -r "bisect(pruned)"
540 · see the changeset currently being bisected (especially useful if run‐
542 ning with -U/--noupdate):
543 hg log -r "bisect(current)"
545 · see all changesets that took part in the current bisection:
547 hg log -r "bisect(range)"
549 · you can even get a nice graph:
551 hg log --graph -r "bisect(range)"
553 See hg help revisions.bisect for more about the bisect() predicate.
555 Returns 0 on success.
557 Options:
559 -r, --reset
561 reset bisect state
562 -g, --good
564 mark changeset good
565 -b, --bad
567 mark changeset bad
568 -s, --skip
570 skip testing changeset
571 -e, --extend
573 extend the bisect range
574 -c,--command <CMD>
576 use command to check changeset state
577 -U, --noupdate
579 do not update to target
580 bookmarks
582 create a new bookmark or list existing bookmarks:
583 hg bookmarks [OPTIONS]... [NAME]...
585 Bookmarks are labels on changesets to help track lines of development.
587 Bookmarks are unversioned and can be moved, renamed and deleted.
588 Deleting or moving a bookmark has no effect on the associated change‐
589 sets.
590 Creating or updating to a bookmark causes it to be marked as 'active'.
592 The active bookmark is indicated with a '*'. When a commit is made,
593 the active bookmark will advance to the new commit. A plain hg update
594 will also advance an active bookmark, if possible. Updating away from
595 a bookmark will cause it to be deactivated.
596 Bookmarks can be pushed and pulled between repositories (see hg help
598 push and hg help pull). If a shared bookmark has diverged, a new
599 'divergent bookmark' of the form 'name@path' will be created. Using hg
600 merge will resolve the divergence.
601 Specifying bookmark as '.' to -m or -d options is equivalent to speci‐
603 fying the active bookmark's name.
604 A bookmark named '@' has the special property that hg clone will check
606 it out by default if it exists.
607 Examples:
609 · create an active bookmark for a new line of development:
611 hg book new-feature
613 · create an inactive bookmark as a place marker:
615 hg book -i reviewed
617 · create an inactive bookmark on another changeset:
619 hg book -r .^ tested
621 · rename bookmark turkey to dinner:
623 hg book -m turkey dinner
625 · move the '@' bookmark from another branch:
627 hg book -f @
629 Options:
631 -f, --force
633 force
634 -r,--rev <REV>
636 revision for bookmark action
637 -d, --delete
639 delete a given bookmark
640 -m,--rename <OLD>
642 rename a given bookmark
643 -i, --inactive
645 mark a bookmark inactive
646 -T,--template <TEMPLATE>
648 display with template (EXPERIMENTAL)
649 aliases: bookmark
651 branch
653 set or show the current branch name:
654 hg branch [-fC] [NAME]
656 Note Branch names are permanent and global. Use hg bookmark to create
658 a light-weight bookmark instead. See hg help glossary for more
659 information about named branches and bookmarks.
660 With no argument, show the current branch name. With one argument, set
662 the working directory branch name (the branch will not exist in the
663 repository until the next commit). Standard practice recommends that
664 primary development take place on the 'default' branch.
665 Unless -f/--force is specified, branch will not let you set a branch
667 name that already exists.
668 Use -C/--clean to reset the working directory branch to that of the
670 parent of the working directory, negating a previous branch change.
671 Use the command hg update to switch to an existing branch. Use hg com‐
673 mit --close-branch to mark this branch head as closed. When all heads
674 of a branch are closed, the branch will be considered closed.
675 Returns 0 on success.
677 Options:
679 -f, --force
681 set branch name even if it shadows an existing branch
682 -C, --clean
684 reset branch name to parent branch name
685 -r,--rev <VALUE[+]>
687 change branches of the given revs (EXPERIMENTAL)
688 [+] marked option can be specified multiple times
690 branches
692 list repository named branches:
693 hg branches [-c]
695 List the repository's named branches, indicating which ones are inac‐
697 tive. If -c/--closed is specified, also list branches which have been
698 marked closed (see hg commit --close-branch).
699 Use the command hg update to switch to an existing branch.
701 Returns 0.
703 Options:
705 -a, --active
707 show only branches that have unmerged heads (DEPRECATED)
708 -c, --closed
710 show normal and closed branches
711 -T,--template <TEMPLATE>
713 display with template (EXPERIMENTAL)
714 bundle
716 create a bundle file:
717 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]
719 Generate a bundle file containing data to be added to a repository.
721 To create a bundle containing all changesets, use -a/--all (or --base
723 null). Otherwise, hg assumes the destination will have all the nodes
724 you specify with --base parameters. Otherwise, hg will assume the
725 repository has all the nodes in destination, or default-push/default if
726 no destination is specified.
727 You can change bundle format with the -t/--type option. See hg help
729 bundlespec for documentation on this format. By default, the most
730 appropriate format is used and compression defaults to bzip2.
731 The bundle file can then be transferred using conventional means and
733 applied to another repository with the unbundle or pull command. This
734 is useful when direct push and pull are not available or when exporting
735 an entire repository is undesirable.
736 Applying bundles preserves all changeset contents including permis‐
738 sions, copy/rename information, and revision history.
739 Returns 0 on success, 1 if no changes found.
741 Options:
743 -f, --force
745 run even when the destination is unrelated
746 -r,--rev <REV[+]>
748 a changeset intended to be added to the destination
749 -b,--branch <BRANCH[+]>
751 a specific branch you would like to bundle
752 --base <REV[+]>
754 a base changeset assumed to be available at the destination
755 -a, --all
757 bundle all changesets in the repository
758 -t,--type <TYPE>
760 bundle compression type to use (default: bzip2)
761 -e,--ssh <CMD>
763 specify ssh command to use
764 --remotecmd <CMD>
766 specify hg command to run on the remote side
767 --insecure
769 do not verify server certificate (ignoring web.cacerts config)
770 [+] marked option can be specified multiple times
772 cat
774 output the current or given revision of files:
775 hg cat [OPTION]... FILE...
777 Print the specified files as they were at the given revision. If no
779 revision is given, the parent of the working directory is used.
780 Output may be to a file, in which case the name of the file is given
782 using a format string. The formatting rules as follows:
783 %%
785 literal "%" character
787 %s
789 basename of file being printed
791 %d
793 dirname of file being printed, or '.' if in repository root
795 %p
797 root-relative path name of file being printed
799 %H
801 changeset hash (40 hexadecimal digits)
803 %R
805 changeset revision number
807 %h
809 short-form changeset hash (12 hexadecimal digits)
811 %r
813 zero-padded changeset revision number
815 %b
817 basename of the exporting repository
819 Returns 0 on success.
821 Options:
823 -o,--output <FORMAT>
825 print output to file with formatted name
826 -r,--rev <REV>
828 print the given revision
829 --decode
831 apply any matching decode filter
832 -I,--include <PATTERN[+]>
834 include names matching the given patterns
835 -X,--exclude <PATTERN[+]>
837 exclude names matching the given patterns
838 -T,--template <TEMPLATE>
840 display with template (EXPERIMENTAL)
841 [+] marked option can be specified multiple times
843 clone
845 make a copy of an existing repository:
846 hg clone [OPTION]... SOURCE [DEST]
848 Create a copy of an existing repository in a new directory.
850 If no destination directory name is specified, it defaults to the base‐
852 name of the source.
853 The location of the source is added to the new repository's .hg/hgrc
855 file, as the default to be used for future pulls.
856 Only local paths and ssh:// URLs are supported as destinations. For
858 ssh:// destinations, no working directory or .hg/hgrc will be created
859 on the remote side.
860 If the source repository has a bookmark called '@' set, that revision
862 will be checked out in the new repository by default.
863 To check out a particular version, use -u/--update, or -U/--noupdate to
865 create a clone with no working directory.
866 To pull only a subset of changesets, specify one or more revisions
868 identifiers with -r/--rev or branches with -b/--branch. The resulting
869 clone will contain only the specified changesets and their ancestors.
870 These options (or 'clone src#rev dest') imply --pull, even for local
871 source repositories.
872 In normal clone mode, the remote normalizes repository data into a com‐
874 mon exchange format and the receiving end translates this data into its
875 local storage format. --stream activates a different clone mode that
876 essentially copies repository files from the remote with minimal data
877 processing. This significantly reduces the CPU cost of a clone both
878 remotely and locally. However, it often increases the transferred data
879 size by 30-40%. This can result in substantially faster clones where
880 I/O throughput is plentiful, especially for larger repositories. A
881 side-effect of --stream clones is that storage settings and require‐
882 ments on the remote are applied locally: a modern client may inherit
883 legacy or inefficient storage used by the remote or a legacy Mercurial
884 client may not be able to clone from a modern Mercurial remote.
885 Note Specifying a tag will include the tagged changeset but not the
887 changeset containing the tag.
888 For efficiency, hardlinks are used for cloning whenever the source and
890 destination are on the same filesystem (note this applies only to the
891 repository data, not to the working directory). Some filesystems, such
892 as AFS, implement hardlinking incorrectly, but do not report errors. In
893 these cases, use the --pull option to avoid hardlinking.
894 Mercurial will update the working directory to the first applicable
896 revision from this list:
897 a. null if -U or the source repository has no changesets
899 b. if -u . and the source repository is local, the first parent of the
901 source repository's working directory
902 c. the changeset specified with -u (if a branch name, this means the
904 latest head of that branch)
905 d. the changeset specified with -r
907 e. the tipmost head specified with -b
909 f. the tipmost head specified with the url#branch source syntax
911 g. the revision marked with the '@' bookmark, if present
913 h. the tipmost head of the default branch
915 i. tip
917 When cloning from servers that support it, Mercurial may fetch pre-gen‐
919 erated data from a server-advertised URL. When this is done, hooks
920 operating on incoming changesets and changegroups may fire twice, once
921 for the bundle fetched from the URL and another for any additional data
922 not fetched from this URL. In addition, if an error occurs, the reposi‐
923 tory may be rolled back to a partial clone. This behavior may change in
924 future releases. See hg help -e clonebundles for more.
925 Examples:
927 · clone a remote repository to a new directory named hg/:
929 hg clone https://www.mercurial-scm.org/repo/hg/
931 · create a lightweight local clone:
933 hg clone project/ project-feature/
935 · clone from an absolute path on an ssh server (note double-slash):
937 hg clone ssh://user@server//home/projects/alpha/
939 · do a streaming clone while checking out a specified version:
941 hg clone --stream http://server/repo -u 1.5
943 · create a repository without changesets after a particular revision:
945 hg clone -r 04e544 experimental/ good/
947 · clone (and track) a particular named branch:
949 hg clone https://www.mercurial-scm.org/repo/hg/#stable
951 See hg help urls for details on specifying URLs.
953 Returns 0 on success.
955 Options:
957 -U, --noupdate
959 the clone will include an empty working directory (only a repos‐
960 itory)
961 -u,--updaterev <REV>
963 revision, tag, or branch to check out
964 -r,--rev <REV[+]>
966 include the specified changeset
967 -b,--branch <BRANCH[+]>
969 clone only the specified branch
970 --pull use pull protocol to copy metadata
972 --uncompressed
974 an alias to --stream (DEPRECATED)
975 --stream
977 clone with minimal data processing
978 -e,--ssh <CMD>
980 specify ssh command to use
981 --remotecmd <CMD>
983 specify hg command to run on the remote side
984 --insecure
986 do not verify server certificate (ignoring web.cacerts config)
987 [+] marked option can be specified multiple times
989 commit
991 commit the specified files or all outstanding changes:
992 hg commit [OPTION]... [FILE]...
994 Commit changes to the given files into the repository. Unlike a cen‐
996 tralized SCM, this operation is a local operation. See hg push for a
997 way to actively distribute your changes.
998 If a list of files is omitted, all changes reported by hg status will
1000 be committed.
1001 If you are committing the result of a merge, do not provide any file‐
1003 names or -I/-X filters.
1004 If no commit message is specified, Mercurial starts your configured
1006 editor where you can enter a message. In case your commit fails, you
1007 will find a backup of your message in .hg/last-message.txt.
1008 The --close-branch flag can be used to mark the current branch head
1010 closed. When all heads of a branch are closed, the branch will be con‐
1011 sidered closed and no longer listed.
1012 The --amend flag can be used to amend the parent of the working direc‐
1014 tory with a new commit that contains the changes in the parent in addi‐
1015 tion to those currently reported by hg status, if there are any. The
1016 old commit is stored in a backup bundle in .hg/strip-backup (see hg
1017 help bundle and hg help unbundle on how to restore it).
1018 Message, user and date are taken from the amended commit unless speci‐
1020 fied. When a message isn't specified on the command line, the editor
1021 will open with the message of the amended commit.
1022 It is not possible to amend public changesets (see hg help phases) or
1024 changesets that have children.
1025 See hg help dates for a list of formats valid for -d/--date.
1027 Returns 0 on success, 1 if nothing changed.
1029 Examples:
1031 · commit all files ending in .py:
1033 hg commit --include "set:**.py"
1035 · commit all non-binary files:
1037 hg commit --exclude "set:binary()"
1039 · amend the current commit and set the date to now:
1041 hg commit --amend --date now
1043 Options:
1045 -A, --addremove
1047 mark new/missing files as added/removed before committing
1048 --close-branch
1050 mark a branch head as closed
1051 --amend
1053 amend the parent of the working directory
1054 -s, --secret
1056 use the secret phase for committing
1057 -e, --edit
1059 invoke editor on commit messages
1060 -i, --interactive
1062 use interactive mode
1063 -I,--include <PATTERN[+]>
1065 include names matching the given patterns
1066 -X,--exclude <PATTERN[+]>
1068 exclude names matching the given patterns
1069 -m,--message <TEXT>
1071 use text as commit message
1072 -l,--logfile <FILE>
1074 read commit message from file
1075 -d,--date <DATE>
1077 record the specified date as commit date
1078 -u,--user <USER>
1080 record the specified user as committer
1081 -S, --subrepos
1083 recurse into subrepositories
1084 [+] marked option can be specified multiple times
1086 aliases: ci
1088 config
1090 show combined config settings from all hgrc files:
1091 hg config [-u] [NAME]...
1093 With no arguments, print names and values of all config items.
1095 With one argument of the form section.name, print just the value of
1097 that config item.
1098 With multiple arguments, print names and values of all config items
1100 with matching section names.
1101 With --edit, start an editor on the user-level config file. With
1103 --global, edit the system-wide config file. With --local, edit the
1104 repository-level config file.
1105 With --debug, the source (filename and line number) is printed for each
1107 config item.
1108 See hg help config for more information about config files.
1110 Returns 0 on success, 1 if NAME does not exist.
1112 Options:
1114 -u, --untrusted
1116 show untrusted configuration options
1117 -e, --edit
1119 edit user config
1120 -l, --local
1122 edit repository config
1123 -g, --global
1125 edit global config
1126 -T,--template <TEMPLATE>
1128 display with template (EXPERIMENTAL)
1129 aliases: showconfig debugconfig
1131 copy
1133 mark files as copied for the next commit:
1134 hg copy [OPTION]... [SOURCE]... DEST
1136 Mark dest as having copies of source files. If dest is a directory,
1138 copies are put in that directory. If dest is a file, the source must be
1139 a single file.
1140 By default, this command copies the contents of files as they exist in
1142 the working directory. If invoked with -A/--after, the operation is
1143 recorded, but no copying is performed.
1144 This command takes effect with the next commit. To undo a copy before
1146 that, see hg revert.
1147 Returns 0 on success, 1 if errors are encountered.
1149 Options:
1151 -A, --after
1153 record a copy that has already occurred
1154 -f, --force
1156 forcibly copy over an existing managed file
1157 -I,--include <PATTERN[+]>
1159 include names matching the given patterns
1160 -X,--exclude <PATTERN[+]>
1162 exclude names matching the given patterns
1163 -n, --dry-run
1165 do not perform actions, just print output
1166 [+] marked option can be specified multiple times
1168 aliases: cp
1170 diff
1172 diff repository (or selected files):
1173 hg diff [OPTION]... ([-c REV] | [-r REV1 [-r REV2]]) [FILE]...
1175 Show differences between revisions for the specified files.
1177 Differences between files are shown using the unified diff format.
1179 Note hg diff may generate unexpected results for merges, as it will
1181 default to comparing against the working directory's first par‐
1182 ent changeset if no revisions are specified.
1183 When two revision arguments are given, then changes are shown between
1185 those revisions. If only one revision is specified then that revision
1186 is compared to the working directory, and, when no revisions are speci‐
1187 fied, the working directory files are compared to its first parent.
1188 Alternatively you can specify -c/--change with a revision to see the
1190 changes in that changeset relative to its first parent.
1191 Without the -a/--text option, diff will avoid generating diffs of files
1193 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1194 bly with undesirable results.
1195 Use the -g/--git option to generate diffs in the git extended diff for‐
1197 mat. For more information, read hg help diffs.
1198 Examples:
1200 · compare a file in the current working directory to its parent:
1202 hg diff foo.c
1204 · compare two historical versions of a directory, with rename info:
1206 hg diff --git -r 1.0:1.2 lib/
1208 · get change stats relative to the last change on some date:
1210 hg diff --stat -r "date('may 2')"
1212 · diff all newly-added files that contain a keyword:
1214 hg diff "set:added() and grep(GNU)"
1216 · compare a revision and its parents:
1218 hg diff -c 9353 # compare against first parent
1220 hg diff -r 9353^:9353 # same using revset syntax
1221 hg diff -r 9353^2:9353 # compare against the second parent
1222 Returns 0 on success.
1224 Options:
1226 -r,--rev <REV[+]>
1228 revision
1229 -c,--change <REV>
1231 change made by revision
1232 -a, --text
1234 treat all files as text
1235 -g, --git
1237 use git extended diff format
1238 --binary
1240 generate binary diffs in git mode (default)
1241 --nodates
1243 omit dates from diff headers
1244 --noprefix
1246 omit a/ and b/ prefixes from filenames
1247 -p, --show-function
1249 show which function each change is in
1250 --reverse
1252 produce a diff that undoes the changes
1253 -w, --ignore-all-space
1255 ignore white space when comparing lines
1256 -b, --ignore-space-change
1258 ignore changes in the amount of white space
1259 -B, --ignore-blank-lines
1261 ignore changes whose lines are all blank
1262 -Z, --ignore-space-at-eol
1264 ignore changes in whitespace at EOL
1265 -U,--unified <NUM>
1267 number of lines of context to show
1268 --stat output diffstat-style summary of changes
1270 --root <DIR>
1272 produce diffs relative to subdirectory
1273 -I,--include <PATTERN[+]>
1275 include names matching the given patterns
1276 -X,--exclude <PATTERN[+]>
1278 exclude names matching the given patterns
1279 -S, --subrepos
1281 recurse into subrepositories
1282 [+] marked option can be specified multiple times
1284 export
1286 dump the header and diffs for one or more changesets:
1287 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
1289 Print the changeset header and diffs for one or more revisions. If no
1291 revision is given, the parent of the working directory is used.
1292 The information shown in the changeset header is: author, date, branch
1294 name (if non-default), changeset hash, parent(s) and commit comment.
1295 Note hg export may generate unexpected diff output for merge change‐
1297 sets, as it will compare the merge changeset against its first
1298 parent only.
1299 Output may be to a file, in which case the name of the file is given
1301 using a format string. The formatting rules are as follows:
1302 %%
1304 literal "%" character
1306 %H
1308 changeset hash (40 hexadecimal digits)
1310 %N
1312 number of patches being generated
1314 %R
1316 changeset revision number
1318 %b
1320 basename of the exporting repository
1322 %h
1324 short-form changeset hash (12 hexadecimal digits)
1326 %m
1328 first line of the commit message (only alphanumeric characters)
1330 %n
1332 zero-padded sequence number, starting at 1
1334 %r
1336 zero-padded changeset revision number
1338 Without the -a/--text option, export will avoid generating diffs of
1340 files it detects as binary. With -a, export will generate a diff any‐
1341 way, probably with undesirable results.
1342 Use the -g/--git option to generate diffs in the git extended diff for‐
1344 mat. See hg help diffs for more information.
1345 With the --switch-parent option, the diff will be against the second
1347 parent. It can be useful to review a merge.
1348 Examples:
1350 · use export and import to transplant a bugfix to the current branch:
1352 hg export -r 9353 | hg import -
1354 · export all the changesets between two revisions to a file with rename
1356 information:
1357 hg export --git -r 123:150 > changes.txt
1359 · split outgoing changes into a series of patches with descriptive
1361 names:
1362 hg export -r "outgoing()" -o "%n-%m.patch"
1364 Returns 0 on success.
1366 Options:
1368 -o,--output <FORMAT>
1370 print output to file with formatted name
1371 --switch-parent
1373 diff against the second parent
1374 -r,--rev <REV[+]>
1376 revisions to export
1377 -a, --text
1379 treat all files as text
1380 -g, --git
1382 use git extended diff format
1383 --binary
1385 generate binary diffs in git mode (default)
1386 --nodates
1388 omit dates from diff headers
1389 [+] marked option can be specified multiple times
1391 files
1393 list tracked files:
1394 hg files [OPTION]... [FILE]...
1396 Print files under Mercurial control in the working directory or speci‐
1398 fied revision for given files (excluding removed files). Files can be
1399 specified as filenames or filesets.
1400 If no files are given to match, this command prints the names of all
1402 files under Mercurial control.
1403 Examples:
1405 · list all files under the current directory:
1407 hg files .
1409 · shows sizes and flags for current revision:
1411 hg files -vr .
1413 · list all files named README:
1415 hg files -I "**/README"
1417 · list all binary files:
1419 hg files "set:binary()"
1421 · find files containing a regular expression:
1423 hg files "set:grep('bob')"
1425 · search tracked file contents with xargs and grep:
1427 hg files -0 | xargs -0 grep foo
1429 See hg help patterns and hg help filesets for more information on spec‐
1431 ifying file patterns.
1432 Returns 0 if a match is found, 1 otherwise.
1434 Options:
1436 -r,--rev <REV>
1438 search the repository as it is in REV
1439 -0, --print0
1441 end filenames with NUL, for use with xargs
1442 -I,--include <PATTERN[+]>
1444 include names matching the given patterns
1445 -X,--exclude <PATTERN[+]>
1447 exclude names matching the given patterns
1448 -T,--template <TEMPLATE>
1450 display with template (EXPERIMENTAL)
1451 -S, --subrepos
1453 recurse into subrepositories
1454 [+] marked option can be specified multiple times
1456 forget
1458 forget the specified files on the next commit:
1459 hg forget [OPTION]... FILE...
1461 Mark the specified files so they will no longer be tracked after the
1463 next commit.
1464 This only removes files from the current branch, not from the entire
1466 project history, and it does not delete them from the working direc‐
1467 tory.
1468 To delete the file from the working directory, see hg remove.
1470 To undo a forget before the next commit, see hg add.
1472 Examples:
1474 · forget newly-added binary files:
1476 hg forget "set:added() and binary()"
1478 · forget files that would be excluded by .hgignore:
1480 hg forget "set:hgignore()"
1482 Returns 0 on success.
1484 Options:
1486 -I,--include <PATTERN[+]>
1488 include names matching the given patterns
1489 -X,--exclude <PATTERN[+]>
1491 exclude names matching the given patterns
1492 [+] marked option can be specified multiple times
1494 graft
1496 copy changes from other branches onto the current branch:
1497 hg graft [OPTION]... [-r REV]... REV...
1499 This command uses Mercurial's merge logic to copy individual changes
1501 from other branches without merging branches in the history graph. This
1502 is sometimes known as 'backporting' or 'cherry-picking'. By default,
1503 graft will copy user, date, and description from the source changesets.
1504 Changesets that are ancestors of the current revision, that have
1506 already been grafted, or that are merges will be skipped.
1507 If --log is specified, log messages will have a comment appended of the
1509 form:
1510 (grafted from CHANGESETHASH)
1512 If --force is specified, revisions will be grafted even if they are
1514 already ancestors of, or have been grafted to, the destination. This
1515 is useful when the revisions have since been backed out.
1516 If a graft merge results in conflicts, the graft process is interrupted
1518 so that the current merge can be manually resolved. Once all conflicts
1519 are addressed, the graft process can be continued with the -c/--con‐
1520 tinue option.
1521 Note The -c/--continue option does not reapply earlier options,
1523 except for --force.
1524 Examples:
1526 · copy a single change to the stable branch and edit its description:
1528 hg update stable
1530 hg graft --edit 9393
1531 · graft a range of changesets with one exception, updating dates:
1533 hg graft -D "2085::2093 and not 2091"
1535 · continue a graft after resolving conflicts:
1537 hg graft -c
1539 · show the source of a grafted changeset:
1541 hg log --debug -r .
1543 · show revisions sorted by date:
1545 hg log -r "sort(all(), date)"
1547 See hg help revisions for more about specifying revisions.
1549 Returns 0 on successful completion.
1551 Options:
1553 -r,--rev <REV[+]>
1555 revisions to graft
1556 -c, --continue
1558 resume interrupted graft
1559 -e, --edit
1561 invoke editor on commit messages
1562 --log append graft info to log message
1564 -f, --force
1566 force graft
1567 -D, --currentdate
1569 record the current date as commit date
1570 -U, --currentuser
1572 record the current user as committer
1573 -d,--date <DATE>
1575 record the specified date as commit date
1576 -u,--user <USER>
1578 record the specified user as committer
1579 -t,--tool <VALUE>
1581 specify merge tool
1582 -n, --dry-run
1584 do not perform actions, just print output
1585 [+] marked option can be specified multiple times
1587 grep
1589 search revision history for a pattern in specified files:
1590 hg grep [OPTION]... PATTERN [FILE]...
1592 Search revision history for a regular expression in the specified files
1594 or the entire project.
1595 By default, grep prints the most recent revision number for each file
1597 in which it finds a match. To get it to print every revision that con‐
1598 tains a change in match status ("-" for a match that becomes a
1599 non-match, or "+" for a non-match that becomes a match), use the --all
1600 flag.
1601 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1603 If no FILEs are specified (and -f/--follow isn't set), all files in the
1605 repository are searched, including those that don't exist in the cur‐
1606 rent branch or have been deleted in a prior changeset.
1607 Returns 0 if a match is found, 1 otherwise.
1609 Options:
1611 -0, --print0
1613 end fields with NUL
1614 --all print all revisions that match
1616 -a, --text
1618 treat all files as text
1619 -f, --follow
1621 follow changeset history, or file history across copies and
1622 renames
1623 -i, --ignore-case
1625 ignore case when matching
1626 -l, --files-with-matches
1628 print only filenames and revisions that match
1629 -n, --line-number
1631 print matching line numbers
1632 -r,--rev <REV[+]>
1634 only search files changed within revision range
1635 -u, --user
1637 list the author (long with -v)
1638 -d, --date
1640 list the date (short with -q)
1641 -T,--template <TEMPLATE>
1643 display with template (EXPERIMENTAL)
1644 -I,--include <PATTERN[+]>
1646 include names matching the given patterns
1647 -X,--exclude <PATTERN[+]>
1649 exclude names matching the given patterns
1650 [+] marked option can be specified multiple times
1652 heads
1654 show branch heads:
1655 hg heads [-ct] [-r STARTREV] [REV]...
1657 With no arguments, show all open branch heads in the repository.
1659 Branch heads are changesets that have no descendants on the same
1660 branch. They are where development generally takes place and are the
1661 usual targets for update and merge operations.
1662 If one or more REVs are given, only open branch heads on the branches
1664 associated with the specified changesets are shown. This means that you
1665 can use hg heads . to see the heads on the currently checked-out
1666 branch.
1667 If -c/--closed is specified, also show branch heads marked closed (see
1669 hg commit --close-branch).
1670 If STARTREV is specified, only those heads that are descendants of
1672 STARTREV will be displayed.
1673 If -t/--topo is specified, named branch mechanics will be ignored and
1675 only topological heads (changesets with no children) will be shown.
1676 Returns 0 if matching heads are found, 1 if not.
1678 Options:
1680 -r,--rev <STARTREV>
1682 show only heads which are descendants of STARTREV
1683 -t, --topo
1685 show topological heads only
1686 -a, --active
1688 show active branchheads only (DEPRECATED)
1689 -c, --closed
1691 show normal and closed branch heads
1692 --style <STYLE>
1694 display using template map file (DEPRECATED)
1695 -T,--template <TEMPLATE>
1697 display with template
1698 help
1700 show help for a given topic or a help overview:
1701 hg help [-ecks] [TOPIC]
1703 With no arguments, print a list of commands with short help messages.
1705 Given a topic, extension, or command name, print help for that topic.
1707 Returns 0 if successful.
1709 Options:
1711 -e, --extension
1713 show only help for extensions
1714 -c, --command
1716 show only help for commands
1717 -k, --keyword
1719 show topics matching keyword
1720 -s,--system <VALUE[+]>
1722 show help for specific platform(s)
1723 [+] marked option can be specified multiple times
1725 identify
1727 identify the working directory or specified revision:
1728 hg identify [-nibtB] [-r REV] [SOURCE]
1730 Print a summary identifying the repository state at REV using one or
1732 two parent hash identifiers, followed by a "+" if the working directory
1733 has uncommitted changes, the branch name (if not default), a list of
1734 tags, and a list of bookmarks.
1735 When REV is not given, print a summary of the current state of the
1737 repository including the working directory. Specify -r. to get informa‐
1738 tion of the working directory parent without scanning uncommitted
1739 changes.
1740 Specifying a path to a repository root or Mercurial bundle will cause
1742 lookup to operate on that repository/bundle.
1743 Examples:
1745 · generate a build identifier for the working directory:
1747 hg id --id > build-id.dat
1749 · find the revision corresponding to a tag:
1751 hg id -n -r 1.3
1753 · check the most recent revision of a remote repository:
1755 hg id -r tip https://www.mercurial-scm.org/repo/hg/
1757 See hg log for generating more information about specific revisions,
1759 including full hash identifiers.
1760 Returns 0 if successful.
1762 Options:
1764 -r,--rev <REV>
1766 identify the specified revision
1767 -n, --num
1769 show local revision number
1770 -i, --id
1772 show global revision id
1773 -b, --branch
1775 show branch
1776 -t, --tags
1778 show tags
1779 -B, --bookmarks
1781 show bookmarks
1782 -e,--ssh <CMD>
1784 specify ssh command to use
1785 --remotecmd <CMD>
1787 specify hg command to run on the remote side
1788 --insecure
1790 do not verify server certificate (ignoring web.cacerts config)
1791 -T,--template <TEMPLATE>
1793 display with template (EXPERIMENTAL)
1794 aliases: id
1796 import
1798 import an ordered set of patches:
1799 hg import [OPTION]... PATCH...
1801 Import a list of patches and commit them individually (unless --no-com‐
1803 mit is specified).
1804 To read a patch from standard input (stdin), use "-" as the patch name.
1806 If a URL is specified, the patch will be downloaded from there.
1807 Import first applies changes to the working directory (unless --bypass
1809 is specified), import will abort if there are outstanding changes.
1810 Use --bypass to apply and commit patches directly to the repository,
1812 without affecting the working directory. Without --exact, patches will
1813 be applied on top of the working directory parent revision.
1814 You can import a patch straight from a mail message. Even patches as
1816 attachments work (to use the body part, it must have type text/plain or
1817 text/x-patch). From and Subject headers of email message are used as
1818 default committer and commit message. All text/plain body parts before
1819 first diff are added to the commit message.
1820 If the imported patch was generated by hg export, user and description
1822 from patch override values from message headers and body. Values given
1823 on command line with -m/--message and -u/--user override these.
1824 If --exact is specified, import will set the working directory to the
1826 parent of each patch before applying it, and will abort if the result‐
1827 ing changeset has a different ID than the one recorded in the patch.
1828 This will guard against various ways that portable patch formats and
1829 mail systems might fail to transfer Mercurial data or metadata. See hg
1830 bundle for lossless transmission.
1831 Use --partial to ensure a changeset will be created from the patch even
1833 if some hunks fail to apply. Hunks that fail to apply will be written
1834 to a <target-file>.rej file. Conflicts can then be resolved by hand
1835 before hg commit --amend is run to update the created changeset. This
1836 flag exists to let people import patches that partially apply without
1837 losing the associated metadata (author, date, description, ...).
1838 Note When no hunks apply cleanly, hg import --partial will create an
1840 empty changeset, importing only the patch metadata.
1841 With -s/--similarity, hg will attempt to discover renames and copies in
1843 the patch in the same way as hg addremove.
1844 It is possible to use external patch programs to perform the patch by
1846 setting the ui.patch configuration option. For the default internal
1847 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
1848 fig for more information about configuration files and how to use these
1849 options.
1850 See hg help dates for a list of formats valid for -d/--date.
1852 Examples:
1854 · import a traditional patch from a website and detect renames:
1856 hg import -s 80 http://example.com/bugfix.patch
1858 · import a changeset from an hgweb server:
1860 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
1862 · import all the patches in an Unix-style mbox:
1864 hg import incoming-patches.mbox
1866 · import patches from stdin:
1868 hg import -
1870 · attempt to exactly restore an exported changeset (not always possi‐
1872 ble):
1873 hg import --exact proposed-fix.patch
1875 · use an external tool to apply a patch which is too fuzzy for the
1877 default internal tool.
1878 hg import --config ui.patch="patch --merge" fuzzy.patch
1880 · change the default fuzzing from 2 to a less strict 7
1882 hg import --config ui.fuzz=7 fuzz.patch
1884 Returns 0 on success, 1 on partial success (see --partial).
1886 Options:
1888 -p,--strip <NUM>
1890 directory strip option for patch. This has the same meaning as
1891 the corresponding patch option (default: 1)
1892 -b,--base <PATH>
1894 base path (DEPRECATED)
1895 -e, --edit
1897 invoke editor on commit messages
1898 -f, --force
1900 skip check for outstanding uncommitted changes (DEPRECATED)
1901 --no-commit
1903 don't commit, just update the working directory
1904 --bypass
1906 apply patch without touching the working directory
1907 --partial
1909 commit even if some hunks fail
1910 --exact
1912 abort if patch would apply lossily
1913 --prefix <DIR>
1915 apply patch to subdirectory
1916 --import-branch
1918 use any branch information in patch (implied by --exact)
1919 -m,--message <TEXT>
1921 use text as commit message
1922 -l,--logfile <FILE>
1924 read commit message from file
1925 -d,--date <DATE>
1927 record the specified date as commit date
1928 -u,--user <USER>
1930 record the specified user as committer
1931 -s,--similarity <SIMILARITY>
1933 guess renamed files by similarity (0<=s<=100)
1934 aliases: patch
1936 incoming
1938 show new changesets found in source:
1939 hg incoming [-p] [-n] [-M] [-f] [-r REV]... [--bundle FILENAME] [SOURCE]
1941 Show new changesets found in the specified path/URL or the default pull
1943 location. These are the changesets that would have been pulled by hg
1944 pull at the time you issued this command.
1945 See pull for valid source format details.
1947 With -B/--bookmarks, the result of bookmark comparison between local
1949 and remote repositories is displayed. With -v/--verbose, status is also
1950 displayed for each bookmark like below:
1951 BM1 01234567890a added
1953 BM2 1234567890ab advanced
1954 BM3 234567890abc diverged
1955 BM4 34567890abcd changed
1956 The action taken locally when pulling depends on the status of each
1958 bookmark:
1959 added
1961 pull will create it
1963 advanced
1965 pull will update it
1967 diverged
1969 pull will create a divergent bookmark
1971 changed
1973 result depends on remote changesets
1975 From the point of view of pulling behavior, bookmark existing only in
1977 the remote repository are treated as added, even if it is in fact
1978 locally deleted.
1979 For remote repository, using --bundle avoids downloading the changesets
1981 twice if the incoming is followed by a pull.
1982 Examples:
1984 · show incoming changes with patches and full description:
1986 hg incoming -vp
1988 · show incoming changes excluding merges, store a bundle:
1990 hg in -vpM --bundle incoming.hg
1992 hg pull incoming.hg
1993 · briefly list changes inside a bundle:
1995 hg in changes.hg -T "{desc|firstline}\n"
1997 Returns 0 if there are incoming changes, 1 otherwise.
1999 Options:
2001 -f, --force
2003 run even if remote repository is unrelated
2004 -n, --newest-first
2006 show newest record first
2007 --bundle <FILE>
2009 file to store the bundles into
2010 -r,--rev <REV[+]>
2012 a remote changeset intended to be added
2013 -B, --bookmarks
2015 compare bookmarks
2016 -b,--branch <BRANCH[+]>
2018 a specific branch you would like to pull
2019 -p, --patch
2021 show patch
2022 -g, --git
2024 use git extended diff format
2025 -l,--limit <NUM>
2027 limit number of changes displayed
2028 -M, --no-merges
2030 do not show merges
2031 --stat output diffstat-style summary of changes
2033 -G, --graph
2035 show the revision DAG
2036 --style <STYLE>
2038 display using template map file (DEPRECATED)
2039 -T,--template <TEMPLATE>
2041 display with template
2042 -e,--ssh <CMD>
2044 specify ssh command to use
2045 --remotecmd <CMD>
2047 specify hg command to run on the remote side
2048 --insecure
2050 do not verify server certificate (ignoring web.cacerts config)
2051 -S, --subrepos
2053 recurse into subrepositories
2054 [+] marked option can be specified multiple times
2056 aliases: in
2058 init
2060 create a new repository in the given directory:
2061 hg init [-e CMD] [--remotecmd CMD] [DEST]
2063 Initialize a new repository in the given directory. If the given direc‐
2065 tory does not exist, it will be created.
2066 If no directory is given, the current directory is used.
2068 It is possible to specify an ssh:// URL as the destination. See hg
2070 help urls for more information.
2071 Returns 0 on success.
2073 Options:
2075 -e,--ssh <CMD>
2077 specify ssh command to use
2078 --remotecmd <CMD>
2080 specify hg command to run on the remote side
2081 --insecure
2083 do not verify server certificate (ignoring web.cacerts config)
2084 locate
2086 locate files matching specific patterns (DEPRECATED):
2087 hg locate [OPTION]... [PATTERN]...
2089 Print files under Mercurial control in the working directory whose
2091 names match the given patterns.
2092 By default, this command searches all directories in the working direc‐
2094 tory. To search just the current directory and its subdirectories, use
2095 "--include .".
2096 If no patterns are given to match, this command prints the names of all
2098 files under Mercurial control in the working directory.
2099 If you want to feed the output of this command into the "xargs" com‐
2101 mand, use the -0 option to both this command and "xargs". This will
2102 avoid the problem of "xargs" treating single filenames that contain
2103 whitespace as multiple filenames.
2104 See hg help files for a more versatile command.
2106 Returns 0 if a match is found, 1 otherwise.
2108 Options:
2110 -r,--rev <REV>
2112 search the repository as it is in REV
2113 -0, --print0
2115 end filenames with NUL, for use with xargs
2116 -f, --fullpath
2118 print complete paths from the filesystem root
2119 -I,--include <PATTERN[+]>
2121 include names matching the given patterns
2122 -X,--exclude <PATTERN[+]>
2124 exclude names matching the given patterns
2125 [+] marked option can be specified multiple times
2127 log
2129 show revision history of entire repository or files:
2130 hg log [OPTION]... [FILE]
2132 Print the revision history of the specified files or the entire
2134 project.
2135 If no revision range is specified, the default is tip:0 unless --follow
2137 is set, in which case the working directory parent is used as the
2138 starting revision.
2139 File history is shown without following rename or copy history of
2141 files. Use -f/--follow with a filename to follow history across renames
2142 and copies. --follow without a filename will only show ancestors of the
2143 starting revision.
2144 By default this command prints revision number and changeset id, tags,
2146 non-trivial parents, user, date and time, and a summary for each com‐
2147 mit. When the -v/--verbose switch is used, the list of changed files
2148 and full commit message are shown.
2149 With --graph the revisions are shown as an ASCII art DAG with the most
2151 recent changeset at the top. 'o' is a changeset, '@' is a working
2152 directory parent, '_' closes a branch, 'x' is obsolete, '*' is unsta‐
2153 ble, and '+' represents a fork where the changeset from the lines below
2154 is a parent of the 'o' merge on the same line. Paths in the DAG are
2155 represented with '|', '/' and so forth. ':' in place of a '|' indicates
2156 one or more revisions in a path are omitted.
2157 Use -L/--line-range FILE,M:N options to follow the history of lines
2159 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2160 fied line range will be shown. This option requires --follow; it can be
2161 specified multiple times. Currently, this option is not compatible with
2162 --graph. This option is experimental.
2163 Note hg log --patch may generate unexpected diff output for merge
2165 changesets, as it will only compare the merge changeset against
2166 its first parent. Also, only files different from BOTH parents
2167 will appear in files:.
2168 Note For performance reasons, hg log FILE may omit duplicate changes
2170 made on branches and will not show removals or mode changes. To
2171 see all such changes, use the --removed switch.
2172 Note The history resulting from -L/--line-range options depends on
2174 diff options; for instance if white-spaces are ignored, respec‐
2175 tive changes with only white-spaces in specified line range will
2176 not be listed.
2177 Some examples:
2179 · changesets with full descriptions and file lists:
2181 hg log -v
2183 · changesets ancestral to the working directory:
2185 hg log -f
2187 · last 10 commits on the current branch:
2189 hg log -l 10 -b .
2191 · changesets showing all modifications of a file, including removals:
2193 hg log --removed file.c
2195 · all changesets that touch a directory, with diffs, excluding merges:
2197 hg log -Mp lib/
2199 · all revision numbers that match a keyword:
2201 hg log -k bug --template "{rev}\n"
2203 · the full hash identifier of the working directory parent:
2205 hg log -r . --template "{node}\n"
2207 · list available log templates:
2209 hg log -T list
2211 · check if a given changeset is included in a tagged release:
2213 hg log -r "a21ccf and ancestor(1.9)"
2215 · find all changesets by some user in a date range:
2217 hg log -k alice -d "may 2008 to jul 2008"
2219 · summary of all changesets after the last tag:
2221 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2223 · changesets touching lines 13 to 23 for file.c:
2225 hg log -L file.c,13:23
2227 · changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2229 main.c with patch:
2230 hg log -L file.c,13:23 -L main.c,2:6 -p
2232 See hg help dates for a list of formats valid for -d/--date.
2234 See hg help revisions for more about specifying and ordering revisions.
2236 See hg help templates for more about pre-packaged styles and specifying
2238 custom templates. The default template used by the log command can be
2239 customized via the ui.logtemplate configuration setting.
2240 Returns 0 on success.
2242 Options:
2244 -f, --follow
2246 follow changeset history, or file history across copies and
2247 renames
2248 --follow-first
2250 only follow the first parent of merge changesets (DEPRECATED)
2251 -d,--date <DATE>
2253 show revisions matching date spec
2254 -C, --copies
2256 show copied files
2257 -k,--keyword <TEXT[+]>
2259 do case-insensitive search for a given text
2260 -r,--rev <REV[+]>
2262 show the specified revision or revset
2263 -L,--line-range <FILE,RANGE[+]>
2265 follow line range of specified file (EXPERIMENTAL)
2266 --removed
2268 include revisions where files were removed
2269 -m, --only-merges
2271 show only merges (DEPRECATED)
2272 -u,--user <USER[+]>
2274 revisions committed by user
2275 --only-branch <BRANCH[+]>
2277 show only changesets within the given named branch (DEPRECATED)
2278 -b,--branch <BRANCH[+]>
2280 show changesets within the given named branch
2281 -P,--prune <REV[+]>
2283 do not display revision or any of its ancestors
2284 -p, --patch
2286 show patch
2287 -g, --git
2289 use git extended diff format
2290 -l,--limit <NUM>
2292 limit number of changes displayed
2293 -M, --no-merges
2295 do not show merges
2296 --stat output diffstat-style summary of changes
2298 -G, --graph
2300 show the revision DAG
2301 --style <STYLE>
2303 display using template map file (DEPRECATED)
2304 -T,--template <TEMPLATE>
2306 display with template
2307 -I,--include <PATTERN[+]>
2309 include names matching the given patterns
2310 -X,--exclude <PATTERN[+]>
2312 exclude names matching the given patterns
2313 [+] marked option can be specified multiple times
2315 aliases: history
2317 manifest
2319 output the current or given revision of the project manifest:
2320 hg manifest [-r REV]
2322 Print a list of version controlled files for the given revision. If no
2324 revision is given, the first parent of the working directory is used,
2325 or the null revision if no revision is checked out.
2326 With -v, print file permissions, symlink and executable bits. With
2328 --debug, print file revision hashes.
2329 If option --all is specified, the list of all files from all revisions
2331 is printed. This includes deleted and renamed files.
2332 Returns 0 on success.
2334 Options:
2336 -r,--rev <REV>
2338 revision to display
2339 --all list files from all revisions
2341 -T,--template <TEMPLATE>
2343 display with template (EXPERIMENTAL)
2344 merge
2346 merge another revision into working directory:
2347 hg merge [-P] [[-r] REV]
2349 The current working directory is updated with all changes made in the
2351 requested revision since the last common predecessor revision.
2352 Files that changed between either parent are marked as changed for the
2354 next commit and a commit must be performed before any further updates
2355 to the repository are allowed. The next commit will have two parents.
2356 --tool can be used to specify the merge tool used for file merges. It
2358 overrides the HGMERGE environment variable and your configuration
2359 files. See hg help merge-tools for options.
2360 If no revision is specified, the working directory's parent is a head
2362 revision, and the current branch contains exactly one other head, the
2363 other head is merged with by default. Otherwise, an explicit revision
2364 with which to merge with must be provided.
2365 See hg help resolve for information on handling file conflicts.
2367 To undo an uncommitted merge, use hg merge --abort which will check out
2369 a clean copy of the original merge parent, losing all changes.
2370 Returns 0 on success, 1 if there are unresolved files.
2372 Options:
2374 -f, --force
2376 force a merge including outstanding changes (DEPRECATED)
2377 -r,--rev <REV>
2379 revision to merge
2380 -P, --preview
2382 review revisions to merge (no merge is performed)
2383 --abort
2385 abort the ongoing merge
2386 -t,--tool <VALUE>
2388 specify merge tool
2389 outgoing
2391 show changesets not found in the destination:
2392 hg outgoing [-M] [-p] [-n] [-f] [-r REV]... [DEST]
2394 Show changesets not found in the specified destination repository or
2396 the default push location. These are the changesets that would be
2397 pushed if a push was requested.
2398 See pull for details of valid destination formats.
2400 With -B/--bookmarks, the result of bookmark comparison between local
2402 and remote repositories is displayed. With -v/--verbose, status is also
2403 displayed for each bookmark like below:
2404 BM1 01234567890a added
2406 BM2 deleted
2407 BM3 234567890abc advanced
2408 BM4 34567890abcd diverged
2409 BM5 4567890abcde changed
2410 The action taken when pushing depends on the status of each bookmark:
2412 added
2414 push with -B will create it
2416 deleted
2418 push with -B will delete it
2420 advanced
2422 push will update it
2424 diverged
2426 push with -B will update it
2428 changed
2430 push with -B will update it
2432 From the point of view of pushing behavior, bookmarks existing only in
2434 the remote repository are treated as deleted, even if it is in fact
2435 added remotely.
2436 Returns 0 if there are outgoing changes, 1 otherwise.
2438 Options:
2440 -f, --force
2442 run even when the destination is unrelated
2443 -r,--rev <REV[+]>
2445 a changeset intended to be included in the destination
2446 -n, --newest-first
2448 show newest record first
2449 -B, --bookmarks
2451 compare bookmarks
2452 -b,--branch <BRANCH[+]>
2454 a specific branch you would like to push
2455 -p, --patch
2457 show patch
2458 -g, --git
2460 use git extended diff format
2461 -l,--limit <NUM>
2463 limit number of changes displayed
2464 -M, --no-merges
2466 do not show merges
2467 --stat output diffstat-style summary of changes
2469 -G, --graph
2471 show the revision DAG
2472 --style <STYLE>
2474 display using template map file (DEPRECATED)
2475 -T,--template <TEMPLATE>
2477 display with template
2478 -e,--ssh <CMD>
2480 specify ssh command to use
2481 --remotecmd <CMD>
2483 specify hg command to run on the remote side
2484 --insecure
2486 do not verify server certificate (ignoring web.cacerts config)
2487 -S, --subrepos
2489 recurse into subrepositories
2490 [+] marked option can be specified multiple times
2492 aliases: out
2494 parents
2496 show the parents of the working directory or revision (DEPRECATED):
2497 hg parents [-r REV] [FILE]
2499 Print the working directory's parent revisions. If a revision is given
2501 via -r/--rev, the parent of that revision will be printed. If a file
2502 argument is given, the revision in which the file was last changed
2503 (before the working directory revision or the argument to --rev if
2504 given) is printed.
2505 This command is equivalent to:
2507 hg log -r "p1()+p2()" or
2509 hg log -r "p1(REV)+p2(REV)" or
2510 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2511 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2512 See hg summary and hg help revsets for related information.
2514 Returns 0 on success.
2516 Options:
2518 -r,--rev <REV>
2520 show parents of the specified revision
2521 --style <STYLE>
2523 display using template map file (DEPRECATED)
2524 -T,--template <TEMPLATE>
2526 display with template
2527 paths
2529 show aliases for remote repositories:
2530 hg paths [NAME]
2532 Show definition of symbolic path name NAME. If no name is given, show
2534 definition of all available names.
2535 Option -q/--quiet suppresses all output when searching for NAME and
2537 shows only the path names when listing all definitions.
2538 Path names are defined in the [paths] section of your configuration
2540 file and in /etc/mercurial/hgrc. If run inside a repository, .hg/hgrc
2541 is used, too.
2542 The path names default and default-push have a special meaning. When
2544 performing a push or pull operation, they are used as fallbacks if no
2545 location is specified on the command-line. When default-push is set,
2546 it will be used for push and default will be used for pull; otherwise
2547 default is used as the fallback for both. When cloning a repository,
2548 the clone source is written as default in .hg/hgrc.
2549 Note default and default-push apply to all inbound (e.g. hg incoming
2551 ) and outbound (e.g. hg outgoing, hg email and hg bundle) opera‐
2552 tions.
2553 See hg help urls for more information.
2555 Returns 0 on success.
2557 Options:
2559 -T,--template <TEMPLATE>
2561 display with template (EXPERIMENTAL)
2562 phase
2564 set or show the current phase name:
2565 hg phase [-p|-d|-s] [-f] [-r] [REV...]
2567 With no argument, show the phase name of the current revision(s).
2569 With one of -p/--public, -d/--draft or -s/--secret, change the phase
2571 value of the specified revisions.
2572 Unless -f/--force is specified, hg phase won't move changesets from a
2574 lower phase to a higher phase. Phases are ordered as follows:
2575 public < draft < secret
2577 Returns 0 on success, 1 if some phases could not be changed.
2579 (For more information about the phases concept, see hg help phases.)
2581 Options:
2583 -p, --public
2585 set changeset phase to public
2586 -d, --draft
2588 set changeset phase to draft
2589 -s, --secret
2591 set changeset phase to secret
2592 -f, --force
2594 allow to move boundary backward
2595 -r,--rev <REV[+]>
2597 target revision
2598 [+] marked option can be specified multiple times
2600 pull
2602 pull changes from the specified source:
2603 hg pull [-u] [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [SOURCE]
2605 Pull changes from a remote repository to a local one.
2607 This finds all changes from the repository at the specified path or URL
2609 and adds them to a local repository (the current one unless -R is spec‐
2610 ified). By default, this does not update the copy of the project in the
2611 working directory.
2612 Use hg incoming if you want to see what would have been added by a pull
2614 at the time you issued this command. If you then decide to add those
2615 changes to the repository, you should use hg pull -r X where X is the
2616 last changeset listed by hg incoming.
2617 If SOURCE is omitted, the 'default' path will be used. See hg help
2619 urls for more information.
2620 Specifying bookmark as . is equivalent to specifying the active book‐
2622 mark's name.
2623 Returns 0 on success, 1 if an update had unresolved files.
2625 Options:
2627 -u, --update
2629 update to new branch head if new descendants were pulled
2630 -f, --force
2632 run even when remote repository is unrelated
2633 -r,--rev <REV[+]>
2635 a remote changeset intended to be added
2636 -B,--bookmark <BOOKMARK[+]>
2638 bookmark to pull
2639 -b,--branch <BRANCH[+]>
2641 a specific branch you would like to pull
2642 -e,--ssh <CMD>
2644 specify ssh command to use
2645 --remotecmd <CMD>
2647 specify hg command to run on the remote side
2648 --insecure
2650 do not verify server certificate (ignoring web.cacerts config)
2651 [+] marked option can be specified multiple times
2653 push
2655 push changes to the specified destination:
2656 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]
2658 Push changesets from the local repository to the specified destination.
2660 This operation is symmetrical to pull: it is identical to a pull in the
2662 destination repository from the current one.
2663 By default, push will not allow creation of new heads at the destina‐
2665 tion, since multiple heads would make it unclear which head to use. In
2666 this situation, it is recommended to pull and merge before pushing.
2667 Use --new-branch if you want to allow push to create a new named branch
2669 that is not present at the destination. This allows you to only create
2670 a new branch without forcing other changes.
2671 Note Extra care should be taken with the -f/--force option, which
2673 will push all new heads on all branches, an action which will
2674 almost always cause confusion for collaborators.
2675 If -r/--rev is used, the specified revision and all its ancestors will
2677 be pushed to the remote repository.
2678 If -B/--bookmark is used, the specified bookmarked revision, its ances‐
2680 tors, and the bookmark will be pushed to the remote repository. Speci‐
2681 fying . is equivalent to specifying the active bookmark's name.
2682 Please see hg help urls for important details about ssh:// URLs. If
2684 DESTINATION is omitted, a default path will be used.
2685 The --pushvars option sends strings to the server that become environ‐
2687 ment variables prepended with HG_USERVAR_. For example, --pushvars
2688 ENABLE_FEATURE=true, provides the server side hooks with HG_USER‐
2689 VAR_ENABLE_FEATURE=true as part of their environment.
2690 pushvars can provide for user-overridable hooks as well as set debug
2692 levels. One example is having a hook that blocks commits containing
2693 conflict markers, but enables the user to override the hook if the file
2694 is using conflict markers for testing purposes or the file format has
2695 strings that look like conflict markers.
2696 By default, servers will ignore --pushvars. To enable it add the fol‐
2698 lowing to your configuration file:
2699 [push]
2701 pushvars.server = true
2702 Returns 0 if push was successful, 1 if nothing to push.
2704 Options:
2706 -f, --force
2708 force push
2709 -r,--rev <REV[+]>
2711 a changeset intended to be included in the destination
2712 -B,--bookmark <BOOKMARK[+]>
2714 bookmark to push
2715 -b,--branch <BRANCH[+]>
2717 a specific branch you would like to push
2718 --new-branch
2720 allow pushing a new branch
2721 --pushvars <VALUE[+]>
2723 variables that can be sent to server (ADVANCED)
2724 -e,--ssh <CMD>
2726 specify ssh command to use
2727 --remotecmd <CMD>
2729 specify hg command to run on the remote side
2730 --insecure
2732 do not verify server certificate (ignoring web.cacerts config)
2733 [+] marked option can be specified multiple times
2735 recover
2737 roll back an interrupted transaction:
2738 hg recover
2740 Recover from an interrupted commit or pull.
2742 This command tries to fix the repository status after an interrupted
2744 operation. It should only be necessary when Mercurial suggests it.
2745 Returns 0 if successful, 1 if nothing to recover or verify fails.
2747 remove
2749 remove the specified files on the next commit:
2750 hg remove [OPTION]... FILE...
2752 Schedule the indicated files for removal from the current branch.
2754 This command schedules the files to be removed at the next commit. To
2756 undo a remove before that, see hg revert. To undo added files, see hg
2757 forget.
2758 -A/--after can be used to remove only files that have already been
2760 deleted, -f/--force can be used to force deletion, and -Af can be used
2761 to remove files from the next revision without deleting them from the
2762 working directory.
2763 The following table details the behavior of remove for different file
2765 states (columns) and option combinations (rows). The file states are
2766 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2767 status). The actions are Warn, Remove (from branch) and Delete (from
2768 disk):
2769 ┌──────────┬───┬────┬────┬───┐
2771 │opt/state │ A │ C │ M │ ! │
2772 ├──────────┼───┼────┼────┼───┤
2773 │none │ W │ RD │ W │ R │
2774 ├──────────┼───┼────┼────┼───┤
2775 │-f │ R │ RD │ RD │ R │
2776 ├──────────┼───┼────┼────┼───┤
2777 │-A │ W │ W │ W │ R │
2778 ├──────────┼───┼────┼────┼───┤
2779 │-Af │ R │ R │ R │ R │
2780 └──────────┴───┴────┴────┴───┘
2781 Note hg remove never deletes files in Added [A] state from the work‐
2783 ing directory, not even if --force is specified.
2784 Returns 0 on success, 1 if any warnings encountered.
2786 Options:
2788 -A, --after
2790 record delete for missing files
2791 -f, --force
2793 forget added files, delete modified files
2794 -S, --subrepos
2796 recurse into subrepositories
2797 -I,--include <PATTERN[+]>
2799 include names matching the given patterns
2800 -X,--exclude <PATTERN[+]>
2802 exclude names matching the given patterns
2803 [+] marked option can be specified multiple times
2805 aliases: rm
2807 rename
2809 rename files; equivalent of copy + remove:
2810 hg rename [OPTION]... SOURCE... DEST
2812 Mark dest as copies of sources; mark sources for deletion. If dest is a
2814 directory, copies are put in that directory. If dest is a file, there
2815 can only be one source.
2816 By default, this command copies the contents of files as they exist in
2818 the working directory. If invoked with -A/--after, the operation is
2819 recorded, but no copying is performed.
2820 This command takes effect at the next commit. To undo a rename before
2822 that, see hg revert.
2823 Returns 0 on success, 1 if errors are encountered.
2825 Options:
2827 -A, --after
2829 record a rename that has already occurred
2830 -f, --force
2832 forcibly copy over an existing managed file
2833 -I,--include <PATTERN[+]>
2835 include names matching the given patterns
2836 -X,--exclude <PATTERN[+]>
2838 exclude names matching the given patterns
2839 -n, --dry-run
2841 do not perform actions, just print output
2842 [+] marked option can be specified multiple times
2844 aliases: move mv
2846 resolve
2848 redo merges or set/view the merge status of files:
2849 hg resolve [OPTION]... [FILE]...
2851 Merges with unresolved conflicts are often the result of non-interac‐
2853 tive merging using the internal:merge configuration setting, or a com‐
2854 mand-line merge tool like diff3. The resolve command is used to manage
2855 the files involved in a merge, after hg merge has been run, and before
2856 hg commit is run (i.e. the working directory must have two parents).
2857 See hg help merge-tools for information on configuring merge tools.
2858 The resolve command can be used in the following ways:
2860 · hg resolve [--tool TOOL] FILE...: attempt to re-merge the specified
2862 files, discarding any previous merge attempts. Re-merging is not per‐
2863 formed for files already marked as resolved. Use --all/-a to select
2864 all unresolved files. --tool can be used to specify the merge tool
2865 used for the given files. It overrides the HGMERGE environment vari‐
2866 able and your configuration files. Previous file contents are saved
2867 with a .orig suffix.
2868 · hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
2870 having manually fixed-up the files). The default is to mark all unre‐
2871 solved files.
2872 · hg resolve -u [FILE]...: mark a file as unresolved. The default is to
2874 mark all resolved files.
2875 · hg resolve -l: list files which had or still have conflicts. In the
2877 printed list, U = unresolved and R = resolved. You can use set:unre‐
2878 solved() or set:resolved() to filter the list. See hg help filesets
2879 for details.
2880 Note Mercurial will not let you commit files with unresolved merge
2882 conflicts. You must use hg resolve -m ... before you can commit
2883 after a conflicting merge.
2884 Returns 0 on success, 1 if any files fail a resolve attempt.
2886 Options:
2888 -a, --all
2890 select all unresolved files
2891 -l, --list
2893 list state of files needing merge
2894 -m, --mark
2896 mark files as resolved
2897 -u, --unmark
2899 mark files as unresolved
2900 -n, --no-status
2902 hide status prefix
2903 -t,--tool <VALUE>
2905 specify merge tool
2906 -I,--include <PATTERN[+]>
2908 include names matching the given patterns
2909 -X,--exclude <PATTERN[+]>
2911 exclude names matching the given patterns
2912 -T,--template <TEMPLATE>
2914 display with template (EXPERIMENTAL)
2915 [+] marked option can be specified multiple times
2917 revert
2919 restore files to their checkout state:
2920 hg revert [OPTION]... [-r REV] [NAME]...
2922 Note To check out earlier revisions, you should use hg update REV.
2924 To cancel an uncommitted merge (and lose your changes), use hg
2925 merge --abort.
2926 With no revision specified, revert the specified files or directories
2928 to the contents they had in the parent of the working directory. This
2929 restores the contents of files to an unmodified state and unschedules
2930 adds, removes, copies, and renames. If the working directory has two
2931 parents, you must explicitly specify a revision.
2932 Using the -r/--rev or -d/--date options, revert the given files or
2934 directories to their states as of a specific revision. Because revert
2935 does not change the working directory parents, this will cause these
2936 files to appear modified. This can be helpful to "back out" some or all
2937 of an earlier change. See hg backout for a related method.
2938 Modified files are saved with a .orig suffix before reverting. To dis‐
2940 able these backups, use --no-backup. It is possible to store the backup
2941 files in a custom directory relative to the root of the repository by
2942 setting the ui.origbackuppath configuration option.
2943 See hg help dates for a list of formats valid for -d/--date.
2945 See hg help backout for a way to reverse the effect of an earlier
2947 changeset.
2948 Returns 0 on success.
2950 Options:
2952 -a, --all
2954 revert all changes when no arguments given
2955 -d,--date <DATE>
2957 tipmost revision matching date
2958 -r,--rev <REV>
2960 revert to the specified revision
2961 -C, --no-backup
2963 do not save backup copies of files
2964 -i, --interactive
2966 interactively select the changes
2967 -I,--include <PATTERN[+]>
2969 include names matching the given patterns
2970 -X,--exclude <PATTERN[+]>
2972 exclude names matching the given patterns
2973 -n, --dry-run
2975 do not perform actions, just print output
2976 [+] marked option can be specified multiple times
2978 rollback
2980 roll back the last transaction (DANGEROUS) (DEPRECATED):
2981 hg rollback
2983 Please use hg commit --amend instead of rollback to correct mistakes in
2985 the last commit.
2986 This command should be used with care. There is only one level of roll‐
2988 back, and there is no way to undo a rollback. It will also restore the
2989 dirstate at the time of the last transaction, losing any dirstate
2990 changes since that time. This command does not alter the working direc‐
2991 tory.
2992 Transactions are used to encapsulate the effects of all commands that
2994 create new changesets or propagate existing changesets into a reposi‐
2995 tory.
2996 For example, the following commands are transactional, and their
2998 effects can be rolled back:
2999 · commit
3001 · import
3003 · pull
3005 · push (with this repository as the destination)
3007 · unbundle
3009 To avoid permanent data loss, rollback will refuse to rollback a commit
3011 transaction if it isn't checked out. Use --force to override this pro‐
3012 tection.
3013 The rollback command can be entirely disabled by setting the ui.roll‐
3015 back configuration setting to false. If you're here because you want to
3016 use rollback and it's disabled, you can re-enable the command by set‐
3017 ting ui.rollback to true.
3018 This command is not intended for use on public repositories. Once
3020 changes are visible for pull by other users, rolling a transaction back
3021 locally is ineffective (someone else may already have pulled the
3022 changes). Furthermore, a race is possible with readers of the reposi‐
3023 tory; for example an in-progress pull from the repository may fail if a
3024 rollback is performed.
3025 Returns 0 on success, 1 if no rollback data is available.
3027 Options:
3029 -n, --dry-run
3031 do not perform actions, just print output
3032 -f, --force
3034 ignore safety measures
3035 root
3037 print the root (top) of the current working directory:
3038 hg root
3040 Print the root directory of the current repository.
3042 Returns 0 on success.
3044 serve
3046 start stand-alone webserver:
3047 hg serve [OPTION]...
3049 Start a local HTTP repository browser and pull server. You can use this
3051 for ad-hoc sharing and browsing of repositories. It is recommended to
3052 use a real web server to serve a repository for longer periods of time.
3053 Please note that the server does not implement access control. This
3055 means that, by default, anybody can read from the server and nobody can
3056 write to it by default. Set the web.allow-push option to * to allow
3057 everybody to push to the server. You should use a real web server if
3058 you need to authenticate users.
3059 By default, the server logs accesses to stdout and errors to stderr.
3061 Use the -A/--accesslog and -E/--errorlog options to log to files.
3062 To have the server choose a free port number to listen on, specify a
3064 port number of 0; in this case, the server will print the port number
3065 it uses.
3066 Returns 0 on success.
3068 Options:
3070 -A,--accesslog <FILE>
3072 name of access log file to write to
3073 -d, --daemon
3075 run server in background
3076 --daemon-postexec <VALUE[+]>
3078 used internally by daemon mode
3079 -E,--errorlog <FILE>
3081 name of error log file to write to
3082 -p,--port <PORT>
3084 port to listen on (default: 8000)
3085 -a,--address <ADDR>
3087 address to listen on (default: all interfaces)
3088 --prefix <PREFIX>
3090 prefix path to serve from (default: server root)
3091 -n,--name <NAME>
3093 name to show in web pages (default: working directory)
3094 --web-conf <FILE>
3096 name of the hgweb config file (see 'hg help hgweb')
3097 --webdir-conf <FILE>
3099 name of the hgweb config file (DEPRECATED)
3100 --pid-file <FILE>
3102 name of file to write process ID to
3103 --stdio
3105 for remote clients (ADVANCED)
3106 --cmdserver <MODE>
3108 for remote clients (ADVANCED)
3109 -t,--templates <TEMPLATE>
3111 web templates to use
3112 --style <STYLE>
3114 template style to use
3115 -6, --ipv6
3117 use IPv6 in addition to IPv4
3118 --certificate <FILE>
3120 SSL certificate file
3121 -S, --subrepos
3123 recurse into subrepositories
3124 [+] marked option can be specified multiple times
3126 status
3128 show changed files in the working directory:
3129 hg status [OPTION]... [FILE]...
3131 Show status of files in the repository. If names are given, only files
3133 that match are shown. Files that are clean or ignored or the source of
3134 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3135 -C/--copies or -A/--all are given. Unless options described with "show
3136 only ..." are given, the options -mardu are used.
3137 Option -q/--quiet hides untracked (unknown and ignored) files unless
3139 explicitly requested with -u/--unknown or -i/--ignored.
3140 Note hg status may appear to disagree with diff if permissions have
3142 changed or a merge has occurred. The standard diff format does
3143 not report permission changes and diff only reports changes rel‐
3144 ative to one merge parent.
3145 If one revision is given, it is used as the base revision. If two
3147 revisions are given, the differences between them are shown. The
3148 --change option can also be used as a shortcut to list the changed
3149 files of a revision from its first parent.
3150 The codes used to show the status of files are:
3152 M = modified
3154 A = added
3155 R = removed
3156 C = clean
3157 ! = missing (deleted by non-hg command, but still tracked)
3158 ? = not tracked
3159 I = ignored
3160 = origin of the previous file (with --copies)
3161 The -t/--terse option abbreviates the output by showing only the direc‐
3163 tory name if all the files in it share the same status. The option
3164 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3165 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3166 'unknown', 'i' for 'ignored' and 'c' for clean.
3167 It abbreviates only those statuses which are passed. Note that clean
3169 and ignored files are not displayed with '--terse ic' unless the
3170 -c/--clean and -i/--ignored options are also used.
3171 The -v/--verbose option shows information when the repository is in an
3173 unfinished merge, shelve, rebase state etc. You can have this behavior
3174 turned on by default by enabling the commands.status.verbose option.
3175 You can skip displaying some of these states by setting commands.sta‐
3177 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3178 'merge', 'rebase', or 'unshelve'.
3179 Examples:
3181 · show changes in the working directory relative to a changeset:
3183 hg status --rev 9353
3185 · show changes in the working directory relative to the current direc‐
3187 tory (see hg help patterns for more information):
3188 hg status re:
3190 · show all changes including copies in an existing changeset:
3192 hg status --copies --change 9353
3194 · get a NUL separated list of added files, suitable for xargs:
3196 hg status -an0
3198 · show more information about the repository status, abbreviating
3200 added, removed, modified, deleted, and untracked paths:
3201 hg status -v -t mardu
3203 Returns 0 on success.
3205 Options:
3207 -A, --all
3209 show status of all files
3210 -m, --modified
3212 show only modified files
3213 -a, --added
3215 show only added files
3216 -r, --removed
3218 show only removed files
3219 -d, --deleted
3221 show only deleted (but tracked) files
3222 -c, --clean
3224 show only files without changes
3225 -u, --unknown
3227 show only unknown (not tracked) files
3228 -i, --ignored
3230 show only ignored files
3231 -n, --no-status
3233 hide status prefix
3234 -t,--terse <VALUE>
3236 show the terse output (EXPERIMENTAL)
3237 -C, --copies
3239 show source of copied files
3240 -0, --print0
3242 end filenames with NUL, for use with xargs
3243 --rev <REV[+]>
3245 show difference from revision
3246 --change <REV>
3248 list the changed files of a revision
3249 -I,--include <PATTERN[+]>
3251 include names matching the given patterns
3252 -X,--exclude <PATTERN[+]>
3254 exclude names matching the given patterns
3255 -S, --subrepos
3257 recurse into subrepositories
3258 -T,--template <TEMPLATE>
3260 display with template (EXPERIMENTAL)
3261 [+] marked option can be specified multiple times
3263 aliases: st
3265 summary
3267 summarize working directory state:
3268 hg summary [--remote]
3270 This generates a brief summary of the working directory state, includ‐
3272 ing parents, branch, commit status, phase and available updates.
3273 With the --remote option, this will check the default paths for incom‐
3275 ing and outgoing changes. This can be time-consuming.
3276 Returns 0 on success.
3278 Options:
3280 --remote
3282 check for push and pull
3283 aliases: sum
3285 tag
3287 add one or more tags for the current or given revision:
3288 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
3290 Name a particular revision using <name>.
3292 Tags are used to name particular revisions of the repository and are
3294 very useful to compare different revisions, to go back to significant
3295 earlier versions or to mark branch points as releases, etc. Changing an
3296 existing tag is normally disallowed; use -f/--force to override.
3297 If no revision is given, the parent of the working directory is used.
3299 To facilitate version control, distribution, and merging of tags, they
3301 are stored as a file named ".hgtags" which is managed similarly to
3302 other project files and can be hand-edited if necessary. This also
3303 means that tagging creates a new commit. The file ".hg/localtags" is
3304 used for local tags (not shared among repositories).
3305 Tag commits are usually made at the head of a branch. If the parent of
3307 the working directory is not a branch head, hg tag aborts; use
3308 -f/--force to force the tag commit to be based on a non-head changeset.
3309 See hg help dates for a list of formats valid for -d/--date.
3311 Since tag names have priority over branch names during revision lookup,
3313 using an existing branch name as a tag name is discouraged.
3314 Returns 0 on success.
3316 Options:
3318 -f, --force
3320 force tag
3321 -l, --local
3323 make the tag local
3324 -r,--rev <REV>
3326 revision to tag
3327 --remove
3329 remove a tag
3330 -e, --edit
3332 invoke editor on commit messages
3333 -m,--message <TEXT>
3335 use text as commit message
3336 -d,--date <DATE>
3338 record the specified date as commit date
3339 -u,--user <USER>
3341 record the specified user as committer
3342 tags
3344 list repository tags:
3345 hg tags
3347 This lists both regular and local tags. When the -v/--verbose switch is
3349 used, a third column "local" is printed for local tags. When the
3350 -q/--quiet switch is used, only the tag name is printed.
3351 Returns 0 on success.
3353 Options:
3355 -T,--template <TEMPLATE>
3357 display with template (EXPERIMENTAL)
3358 tip
3360 show the tip revision (DEPRECATED):
3361 hg tip [-p] [-g]
3363 The tip revision (usually just called the tip) is the changeset most
3365 recently added to the repository (and therefore the most recently
3366 changed head).
3367 If you have just made a commit, that commit will be the tip. If you
3369 have just pulled changes from another repository, the tip of that
3370 repository becomes the current tip. The "tip" tag is special and cannot
3371 be renamed or assigned to a different changeset.
3372 This command is deprecated, please use hg heads instead.
3374 Returns 0 on success.
3376 Options:
3378 -p, --patch
3380 show patch
3381 -g, --git
3383 use git extended diff format
3384 --style <STYLE>
3386 display using template map file (DEPRECATED)
3387 -T,--template <TEMPLATE>
3389 display with template
3390 unbundle
3392 apply one or more bundle files:
3393 hg unbundle [-u] FILE...
3395 Apply one or more bundle files generated by hg bundle.
3397 Returns 0 on success, 1 if an update has unresolved files.
3399 Options:
3401 -u, --update
3403 update to new branch head if changesets were unbundled
3404 update
3406 update working directory (or switch revisions):
3407 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3409 Update the repository's working directory to the specified changeset.
3411 If no changeset is specified, update to the tip of the current named
3412 branch and move the active bookmark (see hg help bookmarks).
3413 Update sets the working directory's parent revision to the specified
3415 changeset (see hg help parents).
3416 If the changeset is not a descendant or ancestor of the working direc‐
3418 tory's parent and there are uncommitted changes, the update is aborted.
3419 With the -c/--check option, the working directory is checked for uncom‐
3420 mitted changes; if none are found, the working directory is updated to
3421 the specified changeset.
3422 The -C/--clean, -c/--check, and -m/--merge options control what happens
3424 if the working directory contains uncommitted changes. At most of one
3425 of them can be specified.
3426 1. If no option is specified, and if the requested changeset is an
3428 ancestor or descendant of the working directory's parent, the uncom‐
3429 mitted changes are merged into the requested changeset and the
3430 merged result is left uncommitted. If the requested changeset is not
3431 an ancestor or descendant (that is, it is on another branch), the
3432 update is aborted and the uncommitted changes are preserved.
3433 2. With the -m/--merge option, the update is allowed even if the
3435 requested changeset is not an ancestor or descendant of the working
3436 directory's parent.
3437 3. With the -c/--check option, the update is aborted and the uncommit‐
3439 ted changes are preserved.
3440 4. With the -C/--clean option, uncommitted changes are discarded and
3442 the working directory is updated to the requested changeset.
3443 To cancel an uncommitted merge (and lose your changes), use hg merge
3445 --abort.
3446 Use null as the changeset to remove the working directory (like hg
3448 clone -U).
3449 If you want to revert just one file to an older revision, use hg revert
3451 [-r REV] NAME.
3452 See hg help dates for a list of formats valid for -d/--date.
3454 Returns 0 on success, 1 if there are unresolved files.
3456 Options:
3458 -C, --clean
3460 discard uncommitted changes (no backup)
3461 -c, --check
3463 require clean working directory
3464 -m, --merge
3466 merge uncommitted changes
3467 -d,--date <DATE>
3469 tipmost revision matching date
3470 -r,--rev <REV>
3472 revision
3473 -t,--tool <VALUE>
3475 specify merge tool
3476 aliases: up checkout co
3478 verify
3480 verify the integrity of the repository:
3481 hg verify
3483 Verify the integrity of the current repository.
3485 This will perform an extensive check of the repository's integrity,
3487 validating the hashes and checksums of each entry in the changelog,
3488 manifest, and tracked files, as well as the integrity of their
3489 crosslinks and indices.
3490 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
3492 information about recovery from corruption of the repository.
3493 Returns 0 on success, 1 if errors are encountered.
3495 version
3497 output version and copyright information:
3498 hg version
3500 output version and copyright information
3502 Options:
3504 -T,--template <TEMPLATE>
3506 display with template (EXPERIMENTAL)
3507
3509 Mercurial supports generating standalone "bundle" files that hold
3510 repository data. These "bundles" are typically saved locally and used
3511 later or exchanged between different repositories, possibly on differ‐
3512 ent machines. Example commands using bundles are hg bundle and hg
3513 unbundle.
3514 Generation of bundle files is controlled by a "bundle specification"
3516 ("bundlespec") string. This string tells the bundle generation process
3517 how to create the bundle.
3518 A "bundlespec" string is composed of the following elements:
3520 type A string denoting the bundle format to use.
3522 compression
3524 Denotes the compression engine to use compressing the raw bundle
3525 data.
3526 parameters
3528 Arbitrary key-value parameters to further control bundle genera‐
3529 tion.
3530 A "bundlespec" string has the following formats:
3532 <type> The literal bundle format string is used.
3534 <compression>-<type>
3536 The compression engine and format are delimited by a hyphen (-).
3537 Optional parameters follow the <type>. Parameters are URI escaped
3539 key=value pairs. Each pair is delimited by a semicolon (;). The first
3540 parameter begins after a ; immediately following the <type> value.
3541 Available Types
3543 The following bundle <type> strings are available:
3544 v1 Produces a legacy "changegroup" version 1 bundle.
3546 This format is compatible with nearly all Mercurial clients
3548 because it is the oldest. However, it has some limitations,
3549 which is why it is no longer the default for new repositories.
3550 v1 bundles can be used with modern repositories using the "gen‐
3552 eraldelta" storage format. However, it may take longer to pro‐
3553 duce the bundle and the resulting bundle may be significantly
3554 larger than a v2 bundle.
3555 v1 bundles can only use the gzip, bzip2, and none compression
3557 formats.
3558 v2 Produces a version 2 bundle.
3560 Version 2 bundles are an extensible format that can store addi‐
3562 tional repository data (such as bookmarks and phases informa‐
3563 tion) and they can store data more efficiently, resulting in
3564 smaller bundles.
3565 Version 2 bundles can also use modern compression engines, such
3567 as zstd, making them faster to compress and often smaller.
3568 Available Compression Engines
3570 The following bundle <compression> engines can be used:
3571 bzip2
3573 An algorithm that produces smaller bundles than gzip.
3575 All Mercurial clients should support this format.
3577 This engine will likely produce smaller bundles than gzip but
3579 will be significantly slower, both during compression and decom‐
3580 pression.
3581 If available, the zstd engine can yield similar or better com‐
3583 pression at much higher speeds.
3584 gzip
3586 zlib compression using the DEFLATE algorithm.
3588 All Mercurial clients should support this format. The compres‐
3590 sion algorithm strikes a reasonable balance between compression
3591 ratio and size.
3592 none
3594 No compression is performed.
3596 Use this compression engine to explicitly disable compression.
3598 Examples
3600 v2
3601 Produce a v2 bundle using default options, including compres‐
3603 sion.
3604 none-v1
3606 Produce a v1 bundle with no compression.
3608 zstd-v2
3610 Produce a v2 bundle with zstandard compression using default
3612 settings.
3613 zstd-v1
3615 This errors because zstd is not supported for v1 types.
3617
3619 Mercurial colorizes output from several commands.
3620 For example, the diff command shows additions in green and deletions in
3622 red, while the status command shows modified files in magenta. Many
3623 other commands have analogous colors. It is possible to customize these
3624 colors.
3625 To enable color (default) whenever possible use:
3627 [ui]
3629 color = yes
3630 To disable color use:
3632 [ui]
3634 color = no
3635 See hg help config.ui.color for details.
3637 The default pager on Windows does not support color, so enabling the
3639 pager will effectively disable color. See hg help config.ui.paginate
3640 to disable the pager. Alternately, MSYS and Cygwin shells provide less
3641 as a pager, which can be configured to support ANSI color mode. Win‐
3642 dows 10 natively supports ANSI color mode.
3643 Mode
3645 Mercurial can use various systems to display color. The supported modes
3646 are ansi, win32, and terminfo. See hg help config.color for details
3647 about how to control the mode.
3648 Effects
3650 Other effects in addition to color, like bold and underlined text, are
3651 also available. By default, the terminfo database is used to find the
3652 terminal codes used to change color and effect. If terminfo is not
3653 available, then effects are rendered with the ECMA-48 SGR control func‐
3654 tion (aka ANSI escape codes).
3655 The available effects in terminfo mode are 'blink', 'bold', 'dim',
3657 'inverse', 'invisible', 'italic', 'standout', and 'underline'; in
3658 ECMA-48 mode, the options are 'bold', 'inverse', 'italic', and 'under‐
3659 line'. How each is rendered depends on the terminal emulator. Some
3660 may not be available for a given terminal type, and will be silently
3661 ignored.
3662 If the terminfo entry for your terminal is missing codes for an effect
3664 or has the wrong codes, you can add or override those codes in your
3665 configuration:
3666 [color]
3668 terminfo.dim = \E[2m
3669 where 'E' is substituted with an escape character.
3671 Labels
3673 Text receives color effects depending on the labels that it has. Many
3674 default Mercurial commands emit labelled text. You can also define your
3675 own labels in templates using the label function, see hg help templates
3676 . A single portion of text may have more than one label. In that case,
3677 effects given to the last label will override any other effects. This
3678 includes the special "none" effect, which nullifies other effects.
3679 Labels are normally invisible. In order to see these labels and their
3681 position in the text, use the global --color=debug option. The same
3682 anchor text may be associated to multiple labels, e.g.
3683 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
3685 The following are the default effects for some default labels. Default
3687 effects may be overridden from your configuration file:
3688 [color]
3690 status.modified = blue bold underline red_background
3691 status.added = green bold
3692 status.removed = red bold blue_background
3693 status.deleted = cyan bold underline
3694 status.unknown = magenta bold underline
3695 status.ignored = black bold
3696 # 'none' turns off all effects
3698 status.clean = none
3699 status.copied = none
3700 qseries.applied = blue bold underline
3702 qseries.unapplied = black bold
3703 qseries.missing = red bold
3704 diff.diffline = bold
3706 diff.extended = cyan bold
3707 diff.file_a = red bold
3708 diff.file_b = green bold
3709 diff.hunk = magenta
3710 diff.deleted = red
3711 diff.inserted = green
3712 diff.changed = white
3713 diff.tab =
3714 diff.trailingwhitespace = bold red_background
3715 # Blank so it inherits the style of the surrounding label
3717 changeset.public =
3718 changeset.draft =
3719 changeset.secret =
3720 resolve.unresolved = red bold
3722 resolve.resolved = green bold
3723 bookmarks.active = green
3725 branches.active = none
3727 branches.closed = black bold
3728 branches.current = green
3729 branches.inactive = none
3730 tags.normal = green
3732 tags.local = black bold
3733 rebase.rebased = blue
3735 rebase.remaining = red bold
3736 shelve.age = cyan
3738 shelve.newest = green bold
3739 shelve.name = blue bold
3740 histedit.remaining = red bold
3742 Custom colors
3744 Because there are only eight standard colors, Mercurial allows you to
3745 define color names for other color slots which might be available for
3746 your terminal type, assuming terminfo mode. For instance:
3747 color.brightblue = 12
3749 color.pink = 207
3750 color.orange = 202
3751 to set 'brightblue' to color slot 12 (useful for 16 color terminals
3753 that have brighter colors defined in the upper eight) and, 'pink' and
3754 'orange' to colors in 256-color xterm's default color cube. These
3755 defined colors may then be used as any of the pre-defined eight,
3756 including appending '_background' to set the background to that color.
3757
3759 Some commands allow the user to specify a date, e.g.:
3760 · backout, commit, import, tag: Specify the commit date.
3762 · log, revert, update: Select revision(s) by date.
3764 Many date formats are valid. Here are some examples:
3766 · Wed Dec 6 13:18:29 2006 (local timezone assumed)
3768 · Dec 6 13:18 -0600 (year assumed, time offset provided)
3770 · Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
3772 · Dec 6 (midnight)
3774 · 13:18 (today assumed)
3776 · 3:39 (3:39AM assumed)
3778 · 3:39pm (15:39)
3780 · 2006-12-06 13:18:29 (ISO 8601 format)
3782 · 2006-12-6 13:18
3784 · 2006-12-6
3786 · 12-6
3788 · 12/6
3790 · 12/6/6 (Dec 6 2006)
3792 · today (midnight)
3794 · yesterday (midnight)
3796 · now - right now
3798 Lastly, there is Mercurial's internal format:
3800 · 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
3802 This is the internal representation format for dates. The first number
3804 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
3805 second is the offset of the local timezone, in seconds west of UTC
3806 (negative if the timezone is east of UTC).
3807 The log command also accepts date ranges:
3809 · <DATE - at or before a given date/time
3811 · >DATE - on or after a given date/time
3813 · DATE to DATE - a date range, inclusive
3815 · -DAYS - within a given number of days of today
3817
3819 Mercurial's default format for showing changes between two versions of
3820 a file is compatible with the unified format of GNU diff, which can be
3821 used by GNU patch and many other standard tools.
3822 While this standard format is often enough, it does not encode the fol‐
3824 lowing information:
3825 · executable status and other permission bits
3827 · copy or rename information
3829 · changes in binary files
3831 · creation or deletion of empty files
3833 Mercurial also supports the extended diff format from the git VCS which
3835 addresses these limitations. The git diff format is not produced by
3836 default because a few widespread tools still do not understand this
3837 format.
3838 This means that when generating diffs from a Mercurial repository (e.g.
3840 with hg export), you should be careful about things like file copies
3841 and renames or other things mentioned above, because when applying a
3842 standard diff to a different repository, this extra information is
3843 lost. Mercurial's internal operations (like push and pull) are not
3844 affected by this, because they use an internal binary format for commu‐
3845 nicating changes.
3846 To make Mercurial produce the git extended diff format, use the --git
3848 option available for many commands, or set 'git = True' in the [diff]
3849 section of your configuration file. You do not need to set this option
3850 when importing diffs in this format or using them in the mq extension.
3851
3853 HG Path to the 'hg' executable, automatically passed when running
3854 hooks, extensions or external tools. If unset or empty, this is
3855 the hg executable's name if it's frozen, or an executable named
3856 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
3857 on Windows) is searched.
3858 HGEDITOR
3860 This is the name of the editor to run when committing. See EDI‐
3861 TOR.
3862 (deprecated, see hg help config.ui.editor)
3864 HGENCODING
3866 This overrides the default locale setting detected by Mercurial.
3867 This setting is used to convert data including usernames,
3868 changeset descriptions, tag names, and branches. This setting
3869 can be overridden with the --encoding command-line option.
3870 HGENCODINGMODE
3872 This sets Mercurial's behavior for handling unknown characters
3873 while transcoding user input. The default is "strict", which
3874 causes Mercurial to abort if it can't map a character. Other
3875 settings include "replace", which replaces unknown characters,
3876 and "ignore", which drops them. This setting can be overridden
3877 with the --encodingmode command-line option.
3878 HGENCODINGAMBIGUOUS
3880 This sets Mercurial's behavior for handling characters with
3881 "ambiguous" widths like accented Latin characters with East
3882 Asian fonts. By default, Mercurial assumes ambiguous characters
3883 are narrow, set this variable to "wide" if such characters cause
3884 formatting problems.
3885 HGMERGE
3887 An executable to use for resolving merge conflicts. The program
3888 will be executed with three arguments: local file, remote file,
3889 ancestor file.
3890 (deprecated, see hg help config.ui.merge)
3892 HGRCPATH
3894 A list of files or directories to search for configuration
3895 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
3896 PATH is not set, platform default search path is used. If empty,
3897 only the .hg/hgrc from the current repository is read.
3898 For each element in HGRCPATH:
3900 · if it's a directory, all files ending with .rc are added
3902 · otherwise, the file itself will be added
3904 HGPLAIN
3906 When set, this disables any configuration settings that might
3907 change Mercurial's default output. This includes encoding,
3908 defaults, verbose mode, debug mode, quiet mode, tracebacks, and
3909 localization. This can be useful when scripting against Mercu‐
3910 rial in the face of existing user configuration.
3911 In addition to the features disabled by HGPLAIN=, the following
3913 values can be specified to adjust behavior:
3914 +strictflags
3916 Restrict parsing of command line flags.
3918 Equivalent options set via command line flags or environment
3920 variables are not overridden.
3921 See hg help scripting for details.
3923 HGPLAINEXCEPT
3925 This is a comma-separated list of features to preserve when
3926 HGPLAIN is enabled. Currently the following values are sup‐
3927 ported:
3928 alias
3930 Don't remove aliases.
3932 color
3934 Don't disable colored output.
3936 i18n
3938 Preserve internationalization.
3940 revsetalias
3942 Don't remove revset aliases.
3944 templatealias
3946 Don't remove template aliases.
3948 progress
3950 Don't hide progress output.
3952 Setting HGPLAINEXCEPT to anything (even an empty string) will
3954 enable plain mode.
3955 HGUSER This is the string used as the author of a commit. If not set,
3957 available values will be considered in this order:
3958 · HGUSER (deprecated)
3960 · configuration files from the HGRCPATH
3962 · EMAIL
3964 · interactive prompt
3966 · LOGNAME (with @hostname appended)
3968 (deprecated, see hg help config.ui.username)
3970 EMAIL May be used as the author of a commit; see HGUSER.
3972 LOGNAME
3974 May be used as the author of a commit; see HGUSER.
3975 VISUAL This is the name of the editor to use when committing. See EDI‐
3977 TOR.
3978 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
3980 user to modify, for example when writing commit messages. The
3981 editor it uses is determined by looking at the environment vari‐
3982 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
3983 non-empty one is chosen. If all of them are empty, the editor
3984 defaults to 'vi'.
3985 PYTHONPATH
3987 This is used by Python to find imported modules and may need to
3988 be set appropriately if this Mercurial is not installed sys‐
3989 tem-wide.
3990
3992 Mercurial has the ability to add new features through the use of exten‐
3993 sions. Extensions may add new commands, add options to existing com‐
3994 mands, change the default behavior of commands, or implement hooks.
3995 To enable the "foo" extension, either shipped with Mercurial or in the
3997 Python search path, create an entry for it in your configuration file,
3998 like this:
3999 [extensions]
4001 foo =
4002 You may also specify the full path to an extension:
4004 [extensions]
4006 myfeature = ~/.hgext/myfeature.py
4007 See hg help config for more information on configuration files.
4009 Extensions are not loaded by default for a variety of reasons: they can
4011 increase startup overhead; they may be meant for advanced usage only;
4012 they may provide potentially dangerous abilities (such as letting you
4013 destroy or modify history); they might not be ready for prime time; or
4014 they may alter some usual behaviors of stock Mercurial. It is thus up
4015 to the user to activate extensions as needed.
4016 To explicitly disable an extension enabled in a configuration file of
4018 broader scope, prepend its path with !:
4019 [extensions]
4021 # disabling extension bar residing in /path/to/extension/bar.py
4022 bar = !/path/to/extension/bar.py
4023 # ditto, but no path was supplied for extension baz
4024 baz = !
4025 disabled extensions:
4027 acl hooks for controlling repository access
4029 blackbox
4031 log repository events to a blackbox for debugging
4032 bugzilla
4034 hooks for integrating with the Bugzilla bug tracker
4035 censor erase file content at a given revision
4037 churn command to display statistics about repository history
4039 clonebundles
4041 advertise pre-generated bundles to seed clones
4042 convert
4044 import revisions from foreign VCS repositories into Mercurial
4045 eol automatically manage newlines in repository files
4047 extdiff
4049 command to allow external programs to compare revisions
4050 factotum
4052 http authentication with factotum
4053 githelp
4055 try mapping git commands to Mercurial commands
4056 gpg commands to sign and verify changesets
4058 hgk browse the repository in a graphical way
4060 highlight
4062 syntax highlighting for hgweb (requires Pygments)
4063 histedit
4065 interactive history editing
4066 keyword
4068 expand keywords in tracked files
4069 largefiles
4071 track large binary files
4072 mq manage a stack of patches
4074 notify hooks for sending email push notifications
4076 patchbomb
4078 command to send changesets as (a series of) patch emails
4079 purge command to delete untracked files from the working directory
4081 rebase command to move sets of revisions to a different ancestor
4083 relink recreates hardlinks between repository clones
4085 schemes
4087 extend schemes with shortcuts to repository swarms
4088 share share a common history between several working directories
4090 shelve save and restore changes to the working directory
4092 strip strip changesets and their descendants from history
4094 transplant
4096 command to transplant changesets from another branch
4097 win32mbcs
4099 allow the use of MBCS paths with problematic encodings
4100 zeroconf
4102 discover and advertise repositories on the local network
4103
4105 Mercurial supports a functional language for selecting a set of files.
4106 Like other file patterns, this pattern type is indicated by a prefix,
4108 'set:'. The language supports a number of predicates which are joined
4109 by infix operators. Parenthesis can be used for grouping.
4110 Identifiers such as filenames or patterns must be quoted with single or
4112 double quotes if they contain characters outside of
4113 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4114 predicates. This generally applies to file patterns other than globs
4115 and arguments for predicates. Pattern prefixes such as path: may be
4116 specified without quoting.
4117 Special characters can be used in quoted identifiers by escaping them,
4119 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4120 preted, strings can be prefixed with r, e.g. r'...'.
4121 See also hg help patterns.
4123 Operators
4125 There is a single prefix operator:
4126 not x
4128 Files not in x. Short form is ! x.
4130 These are the supported infix operators:
4132 x and y
4134 The intersection of files in x and y. Short form is x & y.
4136 x or y
4138 The union of files in x and y. There are two alternative short
4140 forms: x | y and x + y.
4141 x - y
4143 Files in x but not in y.
4145 Predicates
4147 The following predicates are supported:
4148 added()
4150 File that is added according to hg status.
4152 binary()
4154 File that appears to be binary (contains NUL bytes).
4156 clean()
4158 File that is clean according to hg status.
4160 copied()
4162 File that is recorded as being copied.
4164 deleted()
4166 Alias for missing().
4168 encoding(name)
4170 File can be successfully decoded with the given character encod‐
4172 ing. May not be useful for encodings other than ASCII and UTF-8.
4173 eol(style)
4175 File contains newlines of the given style (dos, unix, mac).
4177 Binary files are excluded, files with mixed line endings match
4178 multiple styles.
4179 exec()
4181 File that is marked as executable.
4183 grep(regex)
4185 File contains the given regular expression.
4187 hgignore()
4189 File that matches the active .hgignore pattern.
4191 ignored()
4193 File that is ignored according to hg status. These files will
4195 only be considered if this predicate is used.
4196 missing()
4198 File that is missing according to hg status.
4200 modified()
4202 File that is modified according to hg status.
4204 portable()
4206 File that has a portable name. (This doesn't include filenames
4208 with case collisions.)
4209 removed()
4211 File that is removed according to hg status.
4213 resolved()
4215 File that is marked resolved according to hg resolve -l.
4217 revs(revs, pattern)
4219 Evaluate set in the specified revisions. If the revset match
4221 multiple revs, this will return file matching pattern in any of
4222 the revision.
4223 size(expression)
4225 File size matches the given expression. Examples:
4227 · size('1k') - files from 1024 to 2047 bytes
4229 · size('< 20k') - files less than 20480 bytes
4231 · size('>= .5MB') - files at least 524288 bytes
4233 · size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
4235 status(base, rev, pattern)
4237 Evaluate predicate using status change between base and rev.
4239 Examples:
4240 · status(3, 7, added()) - matches files added from "3" to "7"
4242 subrepo([pattern])
4244 Subrepositories whose paths match the given pattern.
4246 symlink()
4248 File that is marked as a symlink.
4250 unknown()
4252 File that is unknown according to hg status. These files will
4254 only be considered if this predicate is used.
4255 unresolved()
4257 File that is marked unresolved according to hg resolve -l.
4259 Examples
4261 Some sample queries:
4262 · Show status of files that appear to be binary in the working direc‐
4264 tory:
4265 hg status -A "set:binary()"
4267 · Forget files that are in .hgignore but are already tracked:
4269 hg forget "set:hgignore() and not ignored()"
4271 · Find text files that contain a string:
4273 hg files "set:grep(magic) and not binary()"
4275 · Find C files in a non-standard encoding:
4277 hg files "set:**.c and not encoding('UTF-8')"
4279 · Revert copies of large binary files:
4281 hg revert "set:copied() and binary() and size('>1M')"
4283 · Revert files that were added to the working directory:
4285 hg revert "set:revs('wdir()', added())"
4287 · Remove files listed in foo.lst that contain the letter a or b:
4289 hg remove "set: listfile:foo.lst and (**a* or **b*)"
4291
4293 Most Mercurial commands accept various flags.
4294 Flag names
4296 Flags for each command are listed in hg help for that command. Addi‐
4297 tionally, some flags, such as --repository, are global and can be used
4298 with any command - those are seen in hg help -v, and can be specified
4299 before or after the command.
4300 Every flag has at least a long name, such as --repository. Some flags
4302 may also have a short one-letter name, such as the equivalent -R. Using
4303 the short or long name is equivalent and has the same effect.
4304 Flags that have a short name can also be bundled together - for
4306 instance, to specify both --edit (short -e) and --interactive (short
4307 -i), one could use:
4308 hg commit -ei
4310 If any of the bundled flags takes a value (i.e. is not a boolean), it
4312 must be last, followed by the value:
4313 hg commit -im 'Message'
4315 Flag types
4317 Mercurial command-line flags can be strings, numbers, booleans, or
4318 lists of strings.
4319 Specifying flag values
4321 The following syntaxes are allowed, assuming a flag 'flagname' with
4322 short name 'f':
4323 --flagname=foo
4325 --flagname foo
4326 -f foo
4327 -ffoo
4328 This syntax applies to all non-boolean flags (strings, numbers or
4330 lists).
4331 Specifying boolean flags
4333 Boolean flags do not take a value parameter. To specify a boolean, use
4334 the flag name to set it to true, or the same name prefixed with 'no-'
4335 to set it to false:
4336 hg commit --interactive
4338 hg commit --no-interactive
4339 Specifying list flags
4341 List flags take multiple values. To specify them, pass the flag multi‐
4342 ple times:
4343 hg files --include mercurial --include tests
4345 Setting flag defaults
4347 In order to set a default value for a flag in an hgrc file, it is rec‐
4348 ommended to use aliases:
4349 [alias]
4351 commit = commit --interactive
4352 For more information on hgrc files, see hg help config.
4354 Overriding flags on the command line
4356 If the same non-list flag is specified multiple times on the command
4357 line, the latest specification is used:
4358 hg commit -m "Ignored value" -m "Used value"
4360 This includes the use of aliases - e.g., if one has:
4362 [alias]
4364 committemp = commit -m "Ignored value"
4365 then the following command will override that -m:
4367 hg committemp -m "Used value"
4369 Overriding flag defaults
4371 Every flag has a default value, and you may also set your own defaults
4372 in hgrc as described above. Except for list flags, defaults can be
4373 overridden on the command line simply by specifying the flag in that
4374 location.
4375 Hidden flags
4377 Some flags are not shown in a command's help by default - specifically,
4378 those that are deemed to be experimental, deprecated or advanced. To
4379 show all flags, add the --verbose flag for the help command:
4380 hg help --verbose commit
4382
4384 Ancestor
4385 Any changeset that can be reached by an unbroken chain of parent
4386 changesets from a given changeset. More precisely, the ancestors
4387 of a changeset can be defined by two properties: a parent of a
4388 changeset is an ancestor, and a parent of an ancestor is an
4389 ancestor. See also: 'Descendant'.
4390 Bookmark
4392 Bookmarks are pointers to certain commits that move when commit‐
4393 ting. They are similar to tags in that it is possible to use
4394 bookmark names in all places where Mercurial expects a changeset
4395 ID, e.g., with hg update. Unlike tags, bookmarks move along when
4396 you make a commit.
4397 Bookmarks can be renamed, copied and deleted. Bookmarks are
4399 local, unless they are explicitly pushed or pulled between
4400 repositories. Pushing and pulling bookmarks allow you to col‐
4401 laborate with others on a branch without creating a named
4402 branch.
4403 Branch (Noun) A child changeset that has been created from a parent
4405 that is not a head. These are known as topological branches, see
4406 'Branch, topological'. If a topological branch is named, it
4407 becomes a named branch. If a topological branch is not named, it
4408 becomes an anonymous branch. See 'Branch, anonymous' and
4409 'Branch, named'.
4410 Branches may be created when changes are pulled from or pushed
4412 to a remote repository, since new heads may be created by these
4413 operations. Note that the term branch can also be used infor‐
4414 mally to describe a development process in which certain devel‐
4415 opment is done independently of other development. This is some‐
4416 times done explicitly with a named branch, but it can also be
4417 done locally, using bookmarks or clones and anonymous branches.
4418 Example: "The experimental branch."
4420 (Verb) The action of creating a child changeset which results in
4422 its parent having more than one child.
4423 Example: "I'm going to branch at X."
4425 Branch, anonymous
4427 Every time a new child changeset is created from a parent that
4428 is not a head and the name of the branch is not changed, a new
4429 anonymous branch is created.
4430 Branch, closed
4432 A named branch whose branch heads have all been closed.
4433 Branch, default
4435 The branch assigned to a changeset when no name has previously
4436 been assigned.
4437 Branch head
4439 See 'Head, branch'.
4440 Branch, inactive
4442 If a named branch has no topological heads, it is considered to
4443 be inactive. As an example, a feature branch becomes inactive
4444 when it is merged into the default branch. The hg branches com‐
4445 mand shows inactive branches by default, though they can be hid‐
4446 den with hg branches --active.
4447 NOTE: this concept is deprecated because it is too implicit.
4449 Branches should now be explicitly closed using hg commit
4450 --close-branch when they are no longer needed.
4451 Branch, named
4453 A collection of changesets which have the same branch name. By
4454 default, children of a changeset in a named branch belong to the
4455 same named branch. A child can be explicitly assigned to a dif‐
4456 ferent branch. See hg help branch, hg help branches and hg com‐
4457 mit --close-branch for more information on managing branches.
4458 Named branches can be thought of as a kind of namespace, divid‐
4460 ing the collection of changesets that comprise the repository
4461 into a collection of disjoint subsets. A named branch is not
4462 necessarily a topological branch. If a new named branch is cre‐
4463 ated from the head of another named branch, or the default
4464 branch, but no further changesets are added to that previous
4465 branch, then that previous branch will be a branch in name only.
4466 Branch tip
4468 See 'Tip, branch'.
4469 Branch, topological
4471 Every time a new child changeset is created from a parent that
4472 is not a head, a new topological branch is created. If a topo‐
4473 logical branch is named, it becomes a named branch. If a topo‐
4474 logical branch is not named, it becomes an anonymous branch of
4475 the current, possibly default, branch.
4476 Changelog
4478 A record of the changesets in the order in which they were added
4479 to the repository. This includes details such as changeset id,
4480 author, commit message, date, and list of changed files.
4481 Changeset
4483 A snapshot of the state of the repository used to record a
4484 change.
4485 Changeset, child
4487 The converse of parent changeset: if P is a parent of C, then C
4488 is a child of P. There is no limit to the number of children
4489 that a changeset may have.
4490 Changeset id
4492 A SHA-1 hash that uniquely identifies a changeset. It may be
4493 represented as either a "long" 40 hexadecimal digit string, or a
4494 "short" 12 hexadecimal digit string.
4495 Changeset, merge
4497 A changeset with two parents. This occurs when a merge is com‐
4498 mitted.
4499 Changeset, parent
4501 A revision upon which a child changeset is based. Specifically,
4502 a parent changeset of a changeset C is a changeset whose node
4503 immediately precedes C in the DAG. Changesets have at most two
4504 parents.
4505 Checkout
4507 (Noun) The working directory being updated to a specific revi‐
4508 sion. This use should probably be avoided where possible, as
4509 changeset is much more appropriate than checkout in this con‐
4510 text.
4511 Example: "I'm using checkout X."
4513 (Verb) Updating the working directory to a specific changeset.
4515 See hg help update.
4516 Example: "I'm going to check out changeset X."
4518 Child changeset
4520 See 'Changeset, child'.
4521 Close changeset
4523 See 'Head, closed branch'.
4524 Closed branch
4526 See 'Branch, closed'.
4527 Clone (Noun) An entire or partial copy of a repository. The partial
4529 clone must be in the form of a revision and its ancestors.
4530 Example: "Is your clone up to date?"
4532 (Verb) The process of creating a clone, using hg clone.
4534 Example: "I'm going to clone the repository."
4536 Closed branch head
4538 See 'Head, closed branch'.
4539 Commit (Noun) A synonym for changeset.
4541 Example: "Is the bug fixed in your recent commit?"
4543 (Verb) The act of recording changes to a repository. When files
4545 are committed in a working directory, Mercurial finds the dif‐
4546 ferences between the committed files and their parent changeset,
4547 creating a new changeset in the repository.
4548 Example: "You should commit those changes now."
4550 Cset A common abbreviation of the term changeset.
4552 DAG The repository of changesets of a distributed version control
4554 system (DVCS) can be described as a directed acyclic graph
4555 (DAG), consisting of nodes and edges, where nodes correspond to
4556 changesets and edges imply a parent -> child relation. This
4557 graph can be visualized by graphical tools such as hg log
4558 --graph. In Mercurial, the DAG is limited by the requirement for
4559 children to have at most two parents.
4560 Deprecated
4562 Feature removed from documentation, but not scheduled for
4563 removal.
4564 Default branch
4566 See 'Branch, default'.
4567 Descendant
4569 Any changeset that can be reached by a chain of child changesets
4570 from a given changeset. More precisely, the descendants of a
4571 changeset can be defined by two properties: the child of a
4572 changeset is a descendant, and the child of a descendant is a
4573 descendant. See also: 'Ancestor'.
4574 Diff (Noun) The difference between the contents and attributes of
4576 files in two changesets or a changeset and the current working
4577 directory. The difference is usually represented in a standard
4578 form called a "diff" or "patch". The "git diff" format is used
4579 when the changes include copies, renames, or changes to file
4580 attributes, none of which can be represented/handled by classic
4581 "diff" and "patch".
4582 Example: "Did you see my correction in the diff?"
4584 (Verb) Diffing two changesets is the action of creating a diff
4586 or patch.
4587 Example: "If you diff with changeset X, you will see what I
4589 mean."
4590 Directory, working
4592 The working directory represents the state of the files tracked
4593 by Mercurial, that will be recorded in the next commit. The
4594 working directory initially corresponds to the snapshot at an
4595 existing changeset, known as the parent of the working direc‐
4596 tory. See 'Parent, working directory'. The state may be modified
4597 by changes to the files introduced manually or by a merge. The
4598 repository metadata exists in the .hg directory inside the work‐
4599 ing directory.
4600 Draft Changesets in the draft phase have not been shared with publish‐
4602 ing repositories and may thus be safely changed by history-modi‐
4603 fying extensions. See hg help phases.
4604 Experimental
4606 Feature that may change or be removed at a later date.
4607 Graph See DAG and hg log --graph.
4609 Head The term 'head' may be used to refer to both a branch head or a
4611 repository head, depending on the context. See 'Head, branch'
4612 and 'Head, repository' for specific definitions.
4613 Heads are where development generally takes place and are the
4615 usual targets for update and merge operations.
4616 Head, branch
4618 A changeset with no descendants on the same named branch.
4619 Head, closed branch
4621 A changeset that marks a head as no longer interesting. The
4622 closed head is no longer listed by hg heads. A branch is consid‐
4623 ered closed when all its heads are closed and consequently is
4624 not listed by hg branches.
4625 Closed heads can be re-opened by committing new changeset as the
4627 child of the changeset that marks a head as closed.
4628 Head, repository
4630 A topological head which has not been closed.
4631 Head, topological
4633 A changeset with no children in the repository.
4634 History, immutable
4636 Once committed, changesets cannot be altered. Extensions which
4637 appear to change history actually create new changesets that
4638 replace existing ones, and then destroy the old changesets.
4639 Doing so in public repositories can result in old changesets
4640 being reintroduced to the repository.
4641 History, rewriting
4643 The changesets in a repository are immutable. However, exten‐
4644 sions to Mercurial can be used to alter the repository, usually
4645 in such a way as to preserve changeset contents.
4646 Immutable history
4648 See 'History, immutable'.
4649 Merge changeset
4651 See 'Changeset, merge'.
4652 Manifest
4654 Each changeset has a manifest, which is the list of files that
4655 are tracked by the changeset.
4656 Merge Used to bring together divergent branches of work. When you
4658 update to a changeset and then merge another changeset, you
4659 bring the history of the latter changeset into your working
4660 directory. Once conflicts are resolved (and marked), this merge
4661 may be committed as a merge changeset, bringing two branches
4662 together in the DAG.
4663 Named branch
4665 See 'Branch, named'.
4666 Null changeset
4668 The empty changeset. It is the parent state of newly-initialized
4669 repositories and repositories with no checked out revision. It
4670 is thus the parent of root changesets and the effective ancestor
4671 when merging unrelated changesets. Can be specified by the alias
4672 'null' or by the changeset ID '000000000000'.
4673 Parent See 'Changeset, parent'.
4675 Parent changeset
4677 See 'Changeset, parent'.
4678 Parent, working directory
4680 The working directory parent reflects a virtual revision which
4681 is the child of the changeset (or two changesets with an uncom‐
4682 mitted merge) shown by hg parents. This is changed with hg
4683 update. Other commands to see the working directory parent are
4684 hg summary and hg id. Can be specified by the alias ".".
4685 Patch (Noun) The product of a diff operation.
4687 Example: "I've sent you my patch."
4689 (Verb) The process of using a patch file to transform one
4691 changeset into another.
4692 Example: "You will need to patch that revision."
4694 Phase A per-changeset state tracking how the changeset has been or
4696 should be shared. See hg help phases.
4697 Public Changesets in the public phase have been shared with publishing
4699 repositories and are therefore considered immutable. See hg help
4700 phases.
4701 Pull An operation in which changesets in a remote repository which
4703 are not in the local repository are brought into the local
4704 repository. Note that this operation without special arguments
4705 only updates the repository, it does not update the files in the
4706 working directory. See hg help pull.
4707 Push An operation in which changesets in a local repository which are
4709 not in a remote repository are sent to the remote repository.
4710 Note that this operation only adds changesets which have been
4711 committed locally to the remote repository. Uncommitted changes
4712 are not sent. See hg help push.
4713 Repository
4715 The metadata describing all recorded states of a collection of
4716 files. Each recorded state is represented by a changeset. A
4717 repository is usually (but not always) found in the .hg subdi‐
4718 rectory of a working directory. Any recorded state can be recre‐
4719 ated by "updating" a working directory to a specific changeset.
4720 Repository head
4722 See 'Head, repository'.
4723 Revision
4725 A state of the repository at some point in time. Earlier revi‐
4726 sions can be updated to by using hg update. See also 'Revision
4727 number'; See also 'Changeset'.
4728 Revision number
4730 This integer uniquely identifies a changeset in a specific
4731 repository. It represents the order in which changesets were
4732 added to a repository, starting with revision number 0. Note
4733 that the revision number may be different in each clone of a
4734 repository. To identify changesets uniquely between different
4735 clones, see 'Changeset id'.
4736 Revlog History storage mechanism used by Mercurial. It is a form of
4738 delta encoding, with occasional full revision of data followed
4739 by delta of each successive revision. It includes data and an
4740 index pointing to the data.
4741 Rewriting history
4743 See 'History, rewriting'.
4744 Root A changeset that has only the null changeset as its parent. Most
4746 repositories have only a single root changeset.
4747 Secret Changesets in the secret phase may not be shared via push, pull,
4749 or clone. See hg help phases.
4750 Tag An alternative name given to a changeset. Tags can be used in
4752 all places where Mercurial expects a changeset ID, e.g., with hg
4753 update. The creation of a tag is stored in the history and will
4754 thus automatically be shared with other using push and pull.
4755 Tip The changeset with the highest revision number. It is the
4757 changeset most recently added in a repository.
4758 Tip, branch
4760 The head of a given branch with the highest revision number.
4761 When a branch name is used as a revision identifier, it refers
4762 to the branch tip. See also 'Branch, head'. Note that because
4763 revision numbers may be different in different repository
4764 clones, the branch tip may be different in different cloned
4765 repositories.
4766 Update (Noun) Another synonym of changeset.
4768 Example: "I've pushed an update."
4770 (Verb) This term is usually used to describe updating the state
4772 of the working directory to that of a specific changeset. See hg
4773 help update.
4774 Example: "You should update."
4776 Working directory
4778 See 'Directory, working'.
4779 Working directory parent
4781 See 'Parent, working directory'.
4782
4784 Synopsis
4785 The Mercurial system uses a file called .hgignore in the root directory
4786 of a repository to control its behavior when it searches for files that
4787 it is not currently tracking.
4788 Description
4790 The working directory of a Mercurial repository will often contain
4791 files that should not be tracked by Mercurial. These include backup
4792 files created by editors and build products created by compilers.
4793 These files can be ignored by listing them in a .hgignore file in the
4794 root of the working directory. The .hgignore file must be created manu‐
4795 ally. It is typically put under version control, so that the settings
4796 will propagate to other repositories with push and pull.
4797 An untracked file is ignored if its path relative to the repository
4799 root directory, or any prefix path of that path, is matched against any
4800 pattern in .hgignore.
4801 For example, say we have an untracked file, file.c, at a/b/file.c
4803 inside our repository. Mercurial will ignore file.c if any pattern in
4804 .hgignore matches a/b/file.c, a/b or a.
4805 In addition, a Mercurial configuration file can reference a set of
4807 per-user or global ignore files. See the ignore configuration key on
4808 the [ui] section of hg help config for details of how to configure
4809 these files.
4810 To control Mercurial's handling of files that it manages, many commands
4812 support the -I and -X options; see hg help <command> and hg help pat‐
4813 terns for details.
4814 Files that are already tracked are not affected by .hgignore, even if
4816 they appear in .hgignore. An untracked file X can be explicitly added
4817 with hg add X, even if X would be excluded by a pattern in .hgignore.
4818 Syntax
4820 An ignore file is a plain text file consisting of a list of patterns,
4821 with one pattern per line. Empty lines are skipped. The # character is
4822 treated as a comment character, and the \ character is treated as an
4823 escape character.
4824 Mercurial supports several pattern syntaxes. The default syntax used is
4826 Python/Perl-style regular expressions.
4827 To change the syntax used, use a line of the following form:
4829 syntax: NAME
4831 where NAME is one of the following:
4833 regexp
4835 Regular expression, Python/Perl syntax.
4837 glob
4839 Shell-style glob.
4841 The chosen syntax stays in effect when parsing all patterns that fol‐
4843 low, until another syntax is selected.
4844 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
4846 the form *.c will match a file ending in .c in any directory, and a
4847 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
4848 tern, start it with ^.
4849 Subdirectories can have their own .hgignore settings by adding subin‐
4851 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
4852 terns for details on subinclude: and include:.
4853 Note Patterns specified in other than .hgignore are always rooted.
4855 Please see hg help patterns for details.
4856 Example
4858 Here is an example ignore file.
4859 # use glob syntax.
4861 syntax: glob
4862 *.elc
4864 *.pyc
4865 *~
4866 # switch to regexp syntax.
4868 syntax: regexp
4869 ^\.pc/
4870
4872 Mercurial's internal web server, hgweb, can serve either a single
4873 repository, or a tree of repositories. In the second case, repository
4874 paths and global options can be defined using a dedicated configuration
4875 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
4876 This file uses the same syntax as other Mercurial configuration files
4878 but recognizes only the following sections:
4879 · web
4881 · paths
4883 · collections
4885 The web options are thoroughly described in hg help config.
4887 The paths section maps URL paths to paths of repositories in the
4889 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
4890 rial repositories can be published and only according to the configura‐
4891 tion.
4892 The left hand side is the path in the URL. Note that hgweb reserves
4894 subpaths like rev or file, try using different names for nested reposi‐
4895 tories to avoid confusing effects.
4896 The right hand side is the path in the filesystem. If the specified
4898 path ends with * or ** the filesystem will be searched recursively for
4899 repositories below that point. With * it will not recurse into the
4900 repositories it finds (except for .hg/patches). With ** it will also
4901 search inside repository working directories and possibly find sub‐
4902 repositories.
4903 In this example:
4905 [paths]
4907 /projects/a = /srv/tmprepos/a
4908 /projects/b = c:/repos/b
4909 / = /srv/repos/*
4910 /user/bob = /home/bob/repos/**
4911 · The first two entries make two repositories in different directories
4913 appear under the same directory in the web interface
4914 · The third entry will publish every Mercurial repository found in
4916 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
4917 as http://server/quux/
4918 · The fourth entry will publish both http://server/user/bob/quux/ and
4920 http://server/user/bob/quux/testsubrepo/
4921 The collections section is deprecated and has been superseded by paths.
4923 URLs and Common Arguments
4925 URLs under each repository have the form /{command}[/{arguments}] where
4926 {command} represents the name of a command or handler and {arguments}
4927 represents any number of additional URL parameters to that command.
4928 The web server has a default style associated with it. Styles map to a
4930 collection of named templates. Each template is used to render a spe‐
4931 cific piece of data, such as a changeset or diff.
4932 The style for the current request can be overwritten two ways. First,
4934 if {command} contains a hyphen (-), the text before the hyphen defines
4935 the style. For example, /atom-log will render the log command handler
4936 with the atom style. The second way to set the style is with the style
4937 query string argument. For example, /log?style=atom. The hyphenated URL
4938 parameter is preferred.
4939 Not all templates are available for all styles. Attempting to use a
4941 style that doesn't have all templates defined may result in an error
4942 rendering the page.
4943 Many commands take a {revision} URL parameter. This defines the change‐
4945 set to operate on. This is commonly specified as the short, 12 digit
4946 hexadecimal abbreviation for the full 40 character unique revision
4947 identifier. However, any value described by hg help revisions typically
4948 works.
4949 Commands and URLs
4951 The following web commands and their URLs are available:
4952 /annotate/{revision}/{path}
4954 Show changeset information for each line in a file.
4955 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
4957 string arguments have the same meaning as their [annotate] config
4958 equivalents. It uses the hgrc boolean parsing logic to interpret the
4959 value. e.g. 0 and false are false and 1 and true are true. If not
4960 defined, the server default settings are used.
4961 The fileannotate template is rendered.
4963 /archive/{revision}.{format}[/{path}]
4965 Obtain an archive of repository content.
4966 The content and type of the archive is defined by a URL path parameter.
4968 format is the file extension of the archive type to be generated. e.g.
4969 zip or tar.bz2. Not all archive types may be allowed by your server
4970 configuration.
4971 The optional path URL parameter controls content to include in the ar‐
4973 chive. If omitted, every file in the specified revision is present in
4974 the archive. If included, only the specified file or contents of the
4975 specified directory will be included in the archive.
4976 No template is used for this handler. Raw, binary content is generated.
4978 /bookmarks
4980 Show information about bookmarks.
4981 No arguments are accepted.
4983 The bookmarks template is rendered.
4985 /branches
4987 Show information about branches.
4988 All known branches are contained in the output, even closed branches.
4990 No arguments are accepted.
4992 The branches template is rendered.
4994 /changelog[/{revision}]
4996 Show information about multiple changesets.
4997 If the optional revision URL argument is absent, information about all
4999 changesets starting at tip will be rendered. If the revision argument
5000 is present, changesets will be shown starting from the specified revi‐
5001 sion.
5002 If revision is absent, the rev query string argument may be defined.
5004 This will perform a search for changesets.
5005 The argument for rev can be a single revision, a revision set, or a
5007 literal keyword to search for in changeset data (equivalent to hg log
5008 -k).
5009 The revcount query string argument defines the maximum numbers of
5011 changesets to render.
5012 For non-searches, the changelog template will be rendered.
5014 /changeset[/{revision}]
5016 Show information about a single changeset.
5017 A URL path argument is the changeset identifier to show. See hg help
5019 revisions for possible values. If not defined, the tip changeset will
5020 be shown.
5021 The changeset template is rendered. Contents of the changesettag,
5023 changesetbookmark, filenodelink, filenolink, and the many templates
5024 related to diffs may all be used to produce the output.
5025 /comparison/{revision}/{path}
5027 Show a comparison between the old and new versions of a file from
5028 changes made on a particular revision.
5029 This is similar to the diff handler. However, this form features a
5031 split or side-by-side diff rather than a unified diff.
5032 The context query string argument can be used to control the lines of
5034 context in the diff.
5035 The filecomparison template is rendered.
5037 /diff/{revision}/{path}
5039 Show how a file changed in a particular commit.
5040 The filediff template is rendered.
5042 This handler is registered under both the /diff and /filediff paths.
5044 /diff is used in modern code.
5045 /file/{revision}[/{path}]
5047 Show information about a directory or file in the repository.
5048 Info about the path given as a URL parameter will be rendered.
5050 If path is a directory, information about the entries in that directory
5052 will be rendered. This form is equivalent to the manifest handler.
5053 If path is a file, information about that file will be shown via the
5055 filerevision template.
5056 If path is not defined, information about the root directory will be
5058 rendered.
5059 /diff/{revision}/{path}
5061 Show how a file changed in a particular commit.
5062 The filediff template is rendered.
5064 This handler is registered under both the /diff and /filediff paths.
5066 /diff is used in modern code.
5067 /filelog/{revision}/{path}
5069 Show information about the history of a file in the repository.
5070 The revcount query string argument can be defined to control the maxi‐
5072 mum number of entries to show.
5073 The filelog template will be rendered.
5075 /graph[/{revision}]
5077 Show information about the graphical topology of the repository.
5078 Information rendered by this handler can be used to create visual rep‐
5080 resentations of repository topology.
5081 The revision URL parameter controls the starting changeset. If it's
5083 absent, the default is tip.
5084 The revcount query string argument can define the number of changesets
5086 to show information for.
5087 The graphtop query string argument can specify the starting changeset
5089 for producing jsdata variable that is used for rendering graph in
5090 JavaScript. By default it has the same value as revision.
5091 This handler will render the graph template.
5093 /help[/{topic}]
5095 Render help documentation.
5096 This web command is roughly equivalent to hg help. If a topic is
5098 defined, that help topic will be rendered. If not, an index of avail‐
5099 able help topics will be rendered.
5100 The help template will be rendered when requesting help for a topic.
5102 helptopics will be rendered for the index of help topics.
5103 /log[/{revision}[/{path}]]
5105 Show repository or file history.
5106 For URLs of the form /log/{revision}, a list of changesets starting at
5108 the specified changeset identifier is shown. If {revision} is not
5109 defined, the default is tip. This form is equivalent to the changelog
5110 handler.
5111 For URLs of the form /log/{revision}/{file}, the history for a specific
5113 file will be shown. This form is equivalent to the filelog handler.
5114 /manifest[/{revision}[/{path}]]
5116 Show information about a directory.
5117 If the URL path arguments are omitted, information about the root
5119 directory for the tip changeset will be shown.
5120 Because this handler can only show information for directories, it is
5122 recommended to use the file handler instead, as it can handle both
5123 directories and files.
5124 The manifest template will be rendered for this handler.
5126 /changeset[/{revision}]
5128 Show information about a single changeset.
5129 A URL path argument is the changeset identifier to show. See hg help
5131 revisions for possible values. If not defined, the tip changeset will
5132 be shown.
5133 The changeset template is rendered. Contents of the changesettag,
5135 changesetbookmark, filenodelink, filenolink, and the many templates
5136 related to diffs may all be used to produce the output.
5137 /shortlog
5139 Show basic information about a set of changesets.
5140 This accepts the same parameters as the changelog handler. The only
5142 difference is the shortlog template will be rendered instead of the
5143 changelog template.
5144 /summary
5146 Show a summary of repository state.
5147 Information about the latest changesets, bookmarks, tags, and branches
5149 is captured by this handler.
5150 The summary template is rendered.
5152 /tags
5154 Show information about tags.
5155 No arguments are accepted.
5157 The tags template is rendered.
5159
5161 To access a subtopic, use "hg help internals.{subtopic-name}"
5162 bundles
5164 Bundles
5165 censor Censor
5167 changegroups
5169 Changegroups
5170 config Config Registrar
5172 requirements
5174 Repository Requirements
5175 revlogs
5177 Revision Logs
5178 wireprotocol
5180 Wire Protocol
5181
5183 To merge files Mercurial uses merge tools.
5184 A merge tool combines two different versions of a file into a merged
5186 file. Merge tools are given the two files and the greatest common
5187 ancestor of the two file versions, so they can determine the changes
5188 made on both branches.
5189 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
5191 out and in several extensions.
5192 Usually, the merge tool tries to automatically reconcile the files by
5194 combining all non-overlapping changes that occurred separately in the
5195 two different evolutions of the same initial base file. Furthermore,
5196 some interactive merge programs make it easier to manually resolve con‐
5197 flicting merges, either in a graphical way, or by inserting some con‐
5198 flict markers. Mercurial does not include any interactive merge pro‐
5199 grams but relies on external tools for that.
5200 Available merge tools
5202 External merge tools and their properties are configured in the
5203 merge-tools configuration section - see hgrc(5) - but they can often
5204 just be named by their executable.
5205 A merge tool is generally usable if its executable can be found on the
5207 system and if it can handle the merge. The executable is found if it is
5208 an absolute or relative executable path or the name of an application
5209 in the executable search path. The tool is assumed to be able to handle
5210 the merge if it can handle symlinks if the file is a symlink, if it can
5211 handle binary files if the file is binary, and if a GUI is available if
5212 the tool requires a GUI.
5213 There are some internal merge tools which can be used. The internal
5215 merge tools are:
5216 :dump
5218 Creates three versions of the files to merge, containing the
5220 contents of local, other and base. These files can then be used
5221 to perform a merge manually. If the file to be merged is named
5222 a.txt, these files will accordingly be named a.txt.local,
5223 a.txt.other and a.txt.base and they will be placed in the same
5224 directory as a.txt.
5225 This implies premerge. Therefore, files aren't dumped, if pre‐
5227 merge runs successfully. Use :forcedump to forcibly write files
5228 out.
5229 :fail
5231 Rather than attempting to merge files that were modified on both
5233 branches, it marks them as unresolved. The resolve command must
5234 be used to resolve these conflicts.
5235 :forcedump
5237 Creates three versions of the files as same as :dump, but omits
5239 premerge.
5240 :local
5242 Uses the local p1() version of files as the merged version.
5244 :merge
5246 Uses the internal non-interactive simple merge algorithm for
5248 merging files. It will fail if there are any conflicts and leave
5249 markers in the partially merged file. Markers will have two sec‐
5250 tions, one for each side of merge.
5251 :merge-local
5253 Like :merge, but resolve all conflicts non-interactively in
5255 favor of the local p1() changes.
5256 :merge-other
5258 Like :merge, but resolve all conflicts non-interactively in
5260 favor of the other p2() changes.
5261 :merge3
5263 Uses the internal non-interactive simple merge algorithm for
5265 merging files. It will fail if there are any conflicts and leave
5266 markers in the partially merged file. Marker will have three
5267 sections, one from each side of the merge and one for the base
5268 content.
5269 :other
5271 Uses the other p2() version of files as the merged version.
5273 :prompt
5275 Asks the user which of the local p1() or the other p2() version
5277 to keep as the merged version.
5278 :tagmerge
5280 Uses the internal tag merge algorithm (experimental).
5282 :union
5284 Uses the internal non-interactive simple merge algorithm for
5286 merging files. It will use both left and right sides for con‐
5287 flict regions. No markers are inserted.
5288 Internal tools are always available and do not require a GUI but will
5290 by default not handle symlinks or binary files.
5291 Choosing a merge tool
5293 Mercurial uses these rules when deciding which merge tool to use:
5294 1. If a tool has been specified with the --tool option to merge or
5296 resolve, it is used. If it is the name of a tool in the merge-tools
5297 configuration, its configuration is used. Otherwise the specified
5298 tool must be executable by the shell.
5299 2. If the HGMERGE environment variable is present, its value is used
5301 and must be executable by the shell.
5302 3. If the filename of the file to be merged matches any of the patterns
5304 in the merge-patterns configuration section, the first usable merge
5305 tool corresponding to a matching pattern is used. Here, binary capa‐
5306 bilities of the merge tool are not considered.
5307 4. If ui.merge is set it will be considered next. If the value is not
5309 the name of a configured tool, the specified value is used and must
5310 be executable by the shell. Otherwise the named tool is used if it
5311 is usable.
5312 5. If any usable merge tools are present in the merge-tools configura‐
5314 tion section, the one with the highest priority is used.
5315 6. If a program named hgmerge can be found on the system, it is used -
5317 but it will by default not be used for symlinks and binary files.
5318 7. If the file to be merged is not binary and is not a symlink, then
5320 internal :merge is used.
5321 8. Otherwise, :prompt is used.
5323 Note After selecting a merge program, Mercurial will by default
5325 attempt to merge the files using a simple merge algorithm first.
5326 Only if it doesn't succeed because of conflicting changes will
5327 Mercurial actually execute the merge program. Whether to use the
5328 simple merge algorithm first can be controlled by the premerge
5329 setting of the merge tool. Premerge is enabled by default unless
5330 the file is binary or a symlink.
5331 See the merge-tools and ui sections of hgrc(5) for details on the con‐
5333 figuration of merge tools.
5334
5336 Some Mercurial commands can produce a lot of output, and Mercurial will
5337 attempt to use a pager to make those commands more pleasant.
5338 To set the pager that should be used, set the application variable:
5340 [pager]
5342 pager = less -FRX
5343 If no pager is set in the user or repository configuration, Mercurial
5345 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
5346 from the default or system configuration is used. If none of these are
5347 set, a default pager will be used, typically less on Unix and more on
5348 Windows.
5349 On Windows, more is not color aware, so using it effectively disables
5351 color. MSYS and Cygwin shells provide less as a pager, which can be
5352 configured to support ANSI color codes. See hg help con‐
5353 fig.color.pagermode to configure the color mode when invoking a pager.
5354 You can disable the pager for certain commands by adding them to the
5356 pager.ignore list:
5357 [pager]
5359 ignore = version, help, update
5360 To ignore global commands like hg version or hg help, you have to spec‐
5362 ify them in your user configuration file.
5363 To control whether the pager is used at all for an individual command,
5365 you can use --pager=<value>:
5366 · use as needed: auto.
5368 · require the pager: yes or on.
5370 · suppress the pager: no or off (any unrecognized value will also
5372 work).
5373 To globally turn off all attempts to use a pager, set:
5375 [ui]
5377 paginate = never
5378 which will prevent the pager from running.
5380
5382 Mercurial accepts several notations for identifying one or more files
5383 at a time.
5384 By default, Mercurial treats filenames as shell-style extended glob
5386 patterns.
5387 Alternate pattern notations must be specified explicitly.
5389 Note Patterns specified in .hgignore are not rooted. Please see hg
5391 help hgignore for details.
5392 To use a plain path name without any pattern matching, start it with
5394 path:. These path names must completely match starting at the current
5395 repository root, and when the path points to a directory, it is matched
5396 recursively. To match all files in a directory non-recursively (not
5397 including any files in subdirectories), rootfilesin: can be used, spec‐
5398 ifying an absolute path (relative to the repository root).
5399 To use an extended glob, start a name with glob:. Globs are rooted at
5401 the current directory; a glob such as *.c will only match files in the
5402 current directory ending with .c.
5403 The supported glob syntax extensions are ** to match any string across
5405 path separators and {a,b} to mean "a or b".
5406 To use a Perl/Python regular expression, start a name with re:. Regexp
5408 pattern matching is anchored at the root of the repository.
5409 To read name patterns from a file, use listfile: or listfile0:. The
5411 latter expects null delimited patterns while the former expects line
5412 feeds. Each string read from the file is itself treated as a file pat‐
5413 tern.
5414 To read a set of patterns from a file, use include: or subinclude:.
5416 include: will use all the patterns from the given file and treat them
5417 as if they had been passed in manually. subinclude: will only apply
5418 the patterns against files that are under the subinclude file's direc‐
5419 tory. See hg help hgignore for details on the format of these files.
5420 All patterns, except for glob: specified in command line (not for -I or
5422 -X options), can match also against directories: files under matched
5423 directories are treated as matched. For -I and -X options, glob: will
5424 match directories recursively.
5425 Plain examples:
5427 path:foo/bar a name bar in a directory named foo in the root
5429 of the repository
5430 path:path:name a file or directory named "path:name"
5431 rootfilesin:foo/bar the files in a directory called foo/bar, but not any files
5432 in its subdirectories and not a file bar in directory foo
5433 Glob examples:
5435 glob:*.c any name ending in ".c" in the current directory
5437 *.c any name ending in ".c" in the current directory
5438 **.c any name ending in ".c" in any subdirectory of the
5439 current directory including itself.
5440 foo/* any file in directory foo
5441 foo/** any file in directory foo plus all its subdirectories,
5442 recursively
5443 foo/*.c any name ending in ".c" in the directory foo
5444 foo/**.c any name ending in ".c" in any subdirectory of foo
5445 including itself.
5446 Regexp examples:
5448 re:.*\.c$ any name ending in ".c", anywhere in the repository
5450 File examples:
5452 listfile:list.txt read list from list.txt with one file pattern per line
5454 listfile0:list.txt read list from list.txt with null byte delimiters
5455 See also hg help filesets.
5457 Include examples:
5459 include:path/to/mypatternfile reads patterns to be applied to all paths
5461 subinclude:path/to/subignorefile reads patterns specifically for paths in the
5462 subdirectory
5463
5465 What are phases?
5466 Phases are a system for tracking which changesets have been or should
5467 be shared. This helps prevent common mistakes when modifying history
5468 (for instance, with the mq or rebase extensions).
5469 Each changeset in a repository is in one of the following phases:
5471 · public : changeset is visible on a public server
5473 · draft : changeset is not yet published
5475 · secret : changeset should not be pushed, pulled, or cloned
5477 These phases are ordered (public < draft < secret) and no changeset can
5479 be in a lower phase than its ancestors. For instance, if a changeset is
5480 public, all its ancestors are also public. Lastly, changeset phases
5481 should only be changed towards the public phase.
5482 How are phases managed?
5484 For the most part, phases should work transparently. By default, a
5485 changeset is created in the draft phase and is moved into the public
5486 phase when it is pushed to another repository.
5487 Once changesets become public, extensions like mq and rebase will
5489 refuse to operate on them to prevent creating duplicate changesets.
5490 Phases can also be manually manipulated with the hg phase command if
5491 needed. See hg help -v phase for examples.
5492 To make your commits secret by default, put this in your configuration
5494 file:
5495 [phases]
5497 new-commit = secret
5498 Phases and servers
5500 Normally, all servers are publishing by default. This means:
5501 - all draft changesets that are pulled or cloned appear in phase
5503 public on the client
5504 - all draft changesets that are pushed appear as public on both
5506 client and server
5507 - secret changesets are neither pushed, pulled, or cloned
5509 Note Pulling a draft changeset from a publishing server does not mark
5511 it as public on the server side due to the read-only nature of
5512 pull.
5513 Sometimes it may be desirable to push and pull changesets in the draft
5515 phase to share unfinished work. This can be done by setting a reposi‐
5516 tory to disable publishing in its configuration file:
5517 [phases]
5519 publish = False
5520 See hg help config for more information on configuration files.
5522 Note Servers running older versions of Mercurial are treated as pub‐
5524 lishing.
5525 Note Changesets in secret phase are not exchanged with the server.
5527 This applies to their content: file names, file contents, and
5528 changeset metadata. For technical reasons, the identifier (e.g.
5529 d825e4025e39) of the secret changeset may be communicated to the
5530 server.
5531 Examples
5533 · list changesets in draft or secret phase:
5534 hg log -r "not public()"
5536 · change all secret changesets to draft:
5538 hg phase --draft "secret()"
5540 · forcibly move the current changeset and descendants from public to
5542 draft:
5543 hg phase --force --draft .
5545 · show a list of changeset revisions and each corresponding phase:
5547 hg log --template "{rev} {phase}\n"
5549 · resynchronize draft changesets relative to a remote repository:
5551 hg phase -fd "outgoing(URL)"
5553 See hg help phase for more information on manually manipulating phases.
5555
5557 Mercurial supports several ways to specify revisions.
5558 Specifying single revisions
5560 A plain integer is treated as a revision number. Negative integers are
5561 treated as sequential offsets from the tip, with -1 denoting the tip,
5562 -2 denoting the revision prior to the tip, and so forth.
5563 A 40-digit hexadecimal string is treated as a unique revision identi‐
5565 fier. A hexadecimal string less than 40 characters long is treated as
5566 a unique revision identifier and is referred to as a short-form identi‐
5567 fier. A short-form identifier is only valid if it is the prefix of
5568 exactly one full-length identifier.
5569 Any other string is treated as a bookmark, tag, or branch name. A book‐
5571 mark is a movable pointer to a revision. A tag is a permanent name
5572 associated with a revision. A branch name denotes the tipmost open
5573 branch head of that branch - or if they are all closed, the tipmost
5574 closed head of the branch. Bookmark, tag, and branch names must not
5575 contain the ":" character.
5576 The reserved name "tip" always identifies the most recent revision.
5578 The reserved name "null" indicates the null revision. This is the revi‐
5580 sion of an empty repository, and the parent of revision 0.
5581 The reserved name "." indicates the working directory parent. If no
5583 working directory is checked out, it is equivalent to null. If an
5584 uncommitted merge is in progress, "." is the revision of the first par‐
5585 ent.
5586 Finally, commands that expect a single revision (like hg update) also
5588 accept revsets (see below for details). When given a revset, they use
5589 the last revision of the revset. A few commands accept two single revi‐
5590 sions (like hg diff). When given a revset, they use the first and the
5591 last revisions of the revset.
5592 Specifying multiple revisions
5594 Mercurial supports a functional language for selecting a set of revi‐
5595 sions. Expressions in this language are called revsets.
5596 The language supports a number of predicates which are joined by infix
5598 operators. Parenthesis can be used for grouping.
5599 Identifiers such as branch names may need quoting with single or double
5601 quotes if they contain characters like - or if they match one of the
5602 predefined predicates.
5603 Special characters can be used in quoted identifiers by escaping them,
5605 e.g., \n is interpreted as a newline. To prevent them from being inter‐
5606 preted, strings can be prefixed with r, e.g. r'...'.
5607 Operators
5609 There is a single prefix operator:
5610 not x
5612 Changesets not in x. Short form is ! x.
5614 These are the supported infix operators:
5616 x::y
5618 A DAG range, meaning all changesets that are descendants of x
5620 and ancestors of y, including x and y themselves. If the first
5621 endpoint is left out, this is equivalent to ancestors(y), if the
5622 second is left out it is equivalent to descendants(x).
5623 An alternative syntax is x..y.
5625 x:y
5627 All changesets with revision numbers between x and y, both
5629 inclusive. Either endpoint can be left out, they default to 0
5630 and tip.
5631 x and y
5633 The intersection of changesets in x and y. Short form is x & y.
5635 x or y
5637 The union of changesets in x and y. There are two alternative
5639 short forms: x | y and x + y.
5640 x - y
5642 Changesets in x but not in y.
5644 x % y
5646 Changesets that are ancestors of x but not ancestors of y (i.e.
5648 ::x - ::y). This is shorthand notation for only(x, y) (see
5649 below). The second argument is optional and, if left out, is
5650 equivalent to only(x).
5651 x^n
5653 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
5655 1, the first parent of each changeset in x; for n == 2, the sec‐
5656 ond parent of changeset in x.
5657 x~n
5659 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
5661 the nth unambiguous descendent of x.
5662 x ## y
5664 Concatenate strings and identifiers into one string.
5666 All other prefix, infix and postfix operators have lower prior‐
5668 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
5669 a2)~2.
5670 For example:
5672 [revsetalias]
5674 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
5675 issue(1234) is equivalent to grep(r'\bissue[
5677 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
5678 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
5679 There is a single postfix operator:
5681 x^
5683 Equivalent to x^1, the first parent of each changeset in x.
5685 Patterns
5687 Where noted, predicates that perform string matching can accept a pat‐
5688 tern string. The pattern may be either a literal, or a regular expres‐
5689 sion. If the pattern starts with re:, the remainder of the pattern is
5690 treated as a regular expression. Otherwise, it is treated as a literal.
5691 To match a pattern that actually starts with re:, use the prefix lit‐
5692 eral:.
5693 Matching is case-sensitive, unless otherwise noted. To perform a case-
5695 insensitive match on a case-sensitive predicate, use a regular expres‐
5696 sion, prefixed with (?i).
5697 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
5699 "Release", etc.
5700 Predicates
5702 The following predicates are supported:
5703 adds(pattern)
5705 Changesets that add a file matching pattern.
5707 The pattern without explicit kind like glob: is expected to be
5709 relative to the current directory and match against a file or a
5710 directory.
5711 all()
5713 All changesets, the same as 0:tip.
5715 ancestor(*changeset)
5717 A greatest common ancestor of the changesets.
5719 Accepts 0 or more changesets. Will return empty list when
5721 passed no args. Greatest common ancestor of a single changeset
5722 is that changeset.
5723 ancestors(set[, depth])
5725 Changesets that are ancestors of changesets in set, including
5727 the given changesets themselves.
5728 If depth is specified, the result only includes changesets up to
5730 the specified generation.
5731 author(string)
5733 Alias for user(string).
5735 bisect(string)
5737 Changesets marked in the specified bisect status:
5739 · good, bad, skip: csets explicitly marked as good/bad/skip
5741 · goods, bads : csets topologically good/bad
5743 · range : csets taking part in the bisection
5745 · pruned : csets that are goods, bads or skipped
5747 · untested : csets whose fate is yet unknown
5749 · ignored : csets ignored due to DAG topology
5751 · current : the cset currently being bisected
5753 bookmark([name])
5755 The named bookmark or all bookmarks.
5757 Pattern matching is supported for name. See hg help revi‐
5759 sions.patterns.
5760 branch(string or set)
5762 All changesets belonging to the given branch or the branches of
5764 the given changesets.
5765 Pattern matching is supported for string. See hg help revi‐
5767 sions.patterns.
5768 branchpoint()
5770 Changesets with more than one child.
5772 bundle()
5774 Changesets in the bundle.
5776 Bundle must be specified by the -R option.
5778 children(set)
5780 Child changesets of changesets in set.
5782 closed()
5784 Changeset is closed.
5786 contains(pattern)
5788 The revision's manifest contains a file matching pattern (but
5790 might not modify it). See hg help patterns for information about
5791 file patterns.
5792 The pattern without explicit kind like glob: is expected to be
5794 relative to the current directory and match against a file
5795 exactly for efficiency.
5796 converted([id])
5798 Changesets converted from the given identifier in the old repos‐
5800 itory if present, or all converted changesets if no identifier
5801 is specified.
5802 date(interval)
5804 Changesets within the interval, see hg help dates.
5806 desc(string)
5808 Search commit message for string. The match is case-insensitive.
5810 Pattern matching is supported for string. See hg help revi‐
5812 sions.patterns.
5813 descendants(set[, depth])
5815 Changesets which are descendants of changesets in set, including
5817 the given changesets themselves.
5818 If depth is specified, the result only includes changesets up to
5820 the specified generation.
5821 destination([set])
5823 Changesets that were created by a graft, transplant or rebase
5825 operation, with the given revisions specified as the source.
5826 Omitting the optional set is the same as passing all().
5827 draft()
5829 Changeset in draft phase.
5831 extinct()
5833 Obsolete changesets with obsolete descendants only.
5835 extra(label, [value])
5837 Changesets with the given label in the extra metadata, with the
5839 given optional value.
5840 Pattern matching is supported for value. See hg help revi‐
5842 sions.patterns.
5843 file(pattern)
5845 Changesets affecting files matched by pattern.
5847 For a faster but less accurate result, consider using filelog()
5849 instead.
5850 This predicate uses glob: as the default kind of pattern.
5852 filelog(pattern)
5854 Changesets connected to the specified filelog.
5856 For performance reasons, visits only revisions mentioned in the
5858 file-level filelog, rather than filtering through all changesets
5859 (much faster, but doesn't include deletes or duplicate changes).
5860 For a slower, more accurate result, use file().
5861 The pattern without explicit kind like glob: is expected to be
5863 relative to the current directory and match against a file
5864 exactly for efficiency.
5865 If some linkrev points to revisions filtered by the current
5867 repoview, we'll work around it to return a non-filtered value.
5868 first(set, [n])
5870 An alias for limit().
5872 follow([file[, startrev]])
5874 An alias for ::. (ancestors of the working directory's first
5876 parent). If file pattern is specified, the histories of files
5877 matching given pattern in the revision given by startrev are
5878 followed, including copies.
5879 followlines(file, fromline:toline[, startrev=., descend=False])
5881 Changesets modifying file in line range ('fromline', 'toline').
5883 Line range corresponds to 'file' content at 'startrev' and
5885 should hence be consistent with file size. If startrev is not
5886 specified, working directory's parent is used.
5887 By default, ancestors of 'startrev' are returned. If 'descend'
5889 is True, descendants of 'startrev' are returned though renames
5890 are (currently) not followed in this direction.
5891 grep(regex)
5893 Like keyword(string) but accepts a regex. Use grep(r'...') to
5895 ensure special escape characters are handled correctly. Unlike
5896 keyword(string), the match is case-sensitive.
5897 head()
5899 Changeset is a named branch head.
5901 heads(set)
5903 Members of set with no children in set.
5905 hidden()
5907 Hidden changesets.
5909 id(string)
5911 Revision non-ambiguously specified by the given hex string pre‐
5913 fix.
5914 keyword(string)
5916 Search commit message, user name, and names of changed files for
5918 string. The match is case-insensitive.
5919 For a regular expression or case sensitive search of these
5921 fields, use grep(regex).
5922 last(set, [n])
5924 Last n members of set, defaulting to 1.
5926 limit(set[, n[, offset]])
5928 First n members of set, defaulting to 1, starting from offset.
5930 matching(revision [, field])
5932 Changesets in which a given set of fields match the set of
5934 fields in the selected revision or set.
5935 To match more than one field pass the list of fields to match
5937 separated by spaces (e.g. author description).
5938 Valid fields are most regular revision fields and some special
5940 fields.
5941 Regular revision fields are description, author, branch, date,
5943 files, phase, parents, substate, user and diff. Note that
5944 author and user are synonyms. diff refers to the contents of the
5945 revision. Two revisions matching their diff will also match
5946 their files.
5947 Special fields are summary and metadata: summary matches the
5949 first line of the description. metadata is equivalent to match‐
5950 ing description user date (i.e. it matches the main metadata
5951 fields).
5952 metadata is the default field which is used when no fields are
5954 specified. You can match more than one field at a time.
5955 max(set)
5957 Changeset with highest revision number in set.
5959 merge()
5961 Changeset is a merge changeset.
5963 min(set)
5965 Changeset with lowest revision number in set.
5967 modifies(pattern)
5969 Changesets modifying files matched by pattern.
5971 The pattern without explicit kind like glob: is expected to be
5973 relative to the current directory and match against a file or a
5974 directory.
5975 named(namespace)
5977 The changesets in a given namespace.
5979 Pattern matching is supported for namespace. See hg help revi‐
5981 sions.patterns.
5982 obsolete()
5984 Mutable changeset with a newer version.
5986 only(set, [set])
5988 Changesets that are ancestors of the first set that are not
5990 ancestors of any other head in the repo. If a second set is
5991 specified, the result is ancestors of the first set that are not
5992 ancestors of the second set (i.e. ::<set1> - ::<set2>).
5993 origin([set])
5995 Changesets that were specified as a source for the grafts,
5997 transplants or rebases that created the given revisions. Omit‐
5998 ting the optional set is the same as passing all(). If a
5999 changeset created by these operations is itself specified as a
6000 source for one of these operations, only the source changeset
6001 for the first operation is selected.
6002 outgoing([path])
6004 Changesets not found in the specified destination repository, or
6006 the default push location.
6007 p1([set])
6009 First parent of changesets in set, or the working directory.
6011 p2([set])
6013 Second parent of changesets in set, or the working directory.
6015 parents([set])
6017 The set of all parents for all changesets in set, or the working
6019 directory.
6020 present(set)
6022 An empty set, if any revision in set isn't found; otherwise, all
6024 revisions in set.
6025 If any of specified revisions is not present in the local repos‐
6027 itory, the query is normally aborted. But this predicate allows
6028 the query to continue even in such cases.
6029 public()
6031 Changeset in public phase.
6033 remote([id [,path]])
6035 Local revision that corresponds to the given identifier in a
6037 remote repository, if present. Here, the '.' identifier is a
6038 synonym for the current local branch.
6039 removes(pattern)
6041 Changesets which remove files matching pattern.
6043 The pattern without explicit kind like glob: is expected to be
6045 relative to the current directory and match against a file or a
6046 directory.
6047 rev(number)
6049 Revision with the given numeric identifier.
6051 reverse(set)
6053 Reverse order of set.
6055 roots(set)
6057 Changesets in set with no parent changeset in set.
6059 secret()
6061 Changeset in secret phase.
6063 sort(set[, [-]key... [, ...]])
6065 Sort set by keys. The default sort order is ascending, specify a
6067 key as -key to sort in descending order.
6068 The keys can be:
6070 · rev for the revision number,
6072 · branch for the branch name,
6074 · desc for the commit message (description),
6076 · user for user name (author can be used as an alias),
6078 · date for the commit date
6080 · topo for a reverse topographical sort
6082 The topo sort order cannot be combined with other sort keys.
6084 This sort takes one optional argument, topo.firstbranch, which
6085 takes a revset that specifies what topographical branches to
6086 prioritize in the sort.
6087 subrepo([pattern])
6089 Changesets that add, modify or remove the given subrepo. If no
6091 subrepo pattern is named, any subrepo changes are returned.
6092 successors(set)
6094 All successors for set, including the given set themselves
6096 tag([name])
6098 The specified tag by name, or all tagged revisions if no name is
6100 given.
6101 Pattern matching is supported for name. See hg help revi‐
6103 sions.patterns.
6104 user(string)
6106 User name contains string. The match is case-insensitive.
6108 Pattern matching is supported for string. See hg help revi‐
6110 sions.patterns.
6111 Aliases
6113 New predicates (known as "aliases") can be defined, using any combina‐
6114 tion of existing predicates or other aliases. An alias definition looks
6115 like:
6116 <alias> = <definition>
6118 in the revsetalias section of a Mercurial configuration file. Arguments
6120 of the form a1, a2, etc. are substituted from the alias into the defi‐
6121 nition.
6122 For example,
6124 [revsetalias]
6126 h = heads()
6127 d(s) = sort(s, date)
6128 rs(s, k) = reverse(sort(s, k))
6129 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
6131 equivalent to reverse(sort(0:tip, author)).
6132 Equivalents
6134 Command line equivalents for hg log:
6135 -f -> ::.
6137 -d x -> date(x)
6138 -k x -> keyword(x)
6139 -m -> merge()
6140 -u x -> user(x)
6141 -b x -> branch(x)
6142 -P x -> !::x
6143 -l x -> limit(expr, x)
6144 Examples
6146 Some sample queries:
6147 · Changesets on the default branch:
6149 hg log -r "branch(default)"
6151 · Changesets on the default branch since tag 1.5 (excluding merges):
6153 hg log -r "branch(default) and 1.5:: and not merge()"
6155 · Open branch heads:
6157 hg log -r "head() and not closed()"
6159 · Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
6161 hgext/*:
6162 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
6164 · Changesets committed in May 2008, sorted by user:
6166 hg log -r "sort(date('May 2008'), user)"
6168 · Changesets mentioning "bug" or "issue" that are not in a tagged
6170 release:
6171 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
6173 · Update to the commit that bookmark @ is pointing to, without activat‐
6175 ing the bookmark (this works because the last revision of the revset
6176 is used):
6177 hg update :@
6179 · Show diff between tags 1.3 and 1.5 (this works because the first and
6181 the last revisions of the revset are used):
6182 hg diff -r 1.3::1.5
6184
6186 It is common for machines (as opposed to humans) to consume Mercurial.
6187 This help topic describes some of the considerations for interfacing
6188 machines with Mercurial.
6189 Choosing an Interface
6191 Machines have a choice of several methods to interface with Mercurial.
6192 These include:
6193 · Executing the hg process
6195 · Querying a HTTP server
6197 · Calling out to a command server
6199 Executing hg processes is very similar to how humans interact with Mer‐
6201 curial in the shell. It should already be familiar to you.
6202 hg serve can be used to start a server. By default, this will start a
6204 "hgweb" HTTP server. This HTTP server has support for machine-readable
6205 output, such as JSON. For more, see hg help hgweb.
6206 hg serve can also start a "command server." Clients can connect to this
6208 server and issue Mercurial commands over a special protocol. For more
6209 details on the command server, including links to client libraries, see
6210 https://www.mercurial-scm.org/wiki/CommandServer.
6211 hg serve based interfaces (the hgweb and command servers) have the
6213 advantage over simple hg process invocations in that they are likely
6214 more efficient. This is because there is significant overhead to spawn
6215 new Python processes.
6216 Tip If you need to invoke several hg processes in short order and/or
6218 performance is important to you, use of a server-based interface
6219 is highly recommended.
6220 Environment Variables
6222 As documented in hg help environment, various environment variables
6223 influence the operation of Mercurial. The following are particularly
6224 relevant for machines consuming Mercurial:
6225 HGPLAIN
6227 If not set, Mercurial's output could be influenced by configura‐
6228 tion settings that impact its encoding, verbose mode, localiza‐
6229 tion, etc.
6230 It is highly recommended for machines to set this variable when
6232 invoking hg processes.
6233 HGENCODING
6235 If not set, the locale used by Mercurial will be detected from
6236 the environment. If the determined locale does not support dis‐
6237 play of certain characters, Mercurial may render these character
6238 sequences incorrectly (often by using "?" as a placeholder for
6239 invalid characters in the current locale).
6240 Explicitly setting this environment variable is a good practice
6242 to guarantee consistent results. "utf-8" is a good choice on
6243 UNIX-like environments.
6244 HGRCPATH
6246 If not set, Mercurial will inherit config options from config
6247 files using the process described in hg help config. This
6248 includes inheriting user or system-wide config files.
6249 When utmost control over the Mercurial configuration is desired,
6251 the value of HGRCPATH can be set to an explicit file with known
6252 good configs. In rare cases, the value can be set to an empty
6253 file or the null device (often /dev/null) to bypass loading of
6254 any user or system config files. Note that these approaches can
6255 have unintended consequences, as the user and system config
6256 files often define things like the username and extensions that
6257 may be required to interface with a repository.
6258 Command-line Flags
6260 Mercurial's default command-line parser is designed for humans, and is
6261 not robust against malicious input. For instance, you can start a
6262 debugger by passing --debugger as an option value:
6263 $ REV=--debugger sh -c 'hg log -r "$REV"'
6265 This happens because several command-line flags need to be scanned
6267 without using a concrete command table, which may be modified while
6268 loading repository settings and extensions.
6269 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
6271 setting HGPLAIN=+strictflags. When this feature is enabled, all early
6272 options (e.g. -R/--repository, --cwd, --config) must be specified first
6273 amongst the other global options, and cannot be injected to an arbi‐
6274 trary location:
6275 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
6277 In earlier Mercurial versions where +strictflags isn't available, you
6279 can mitigate the issue by concatenating an option value with its flag:
6280 $ hg log -r"$REV" --keyword="$KEYWORD"
6282 Consuming Command Output
6284 It is common for machines to need to parse the output of Mercurial com‐
6285 mands for relevant data. This section describes the various techniques
6286 for doing so.
6287 Parsing Raw Command Output
6289 Likely the simplest and most effective solution for consuming command
6290 output is to simply invoke hg commands as you would as a user and parse
6291 their output.
6292 The output of many commands can easily be parsed with tools like grep,
6294 sed, and awk.
6295 A potential downside with parsing command output is that the output of
6297 commands can change when Mercurial is upgraded. While Mercurial does
6298 generally strive for strong backwards compatibility, command output
6299 does occasionally change. Having tests for your automated interactions
6300 with hg commands is generally recommended, but is even more important
6301 when raw command output parsing is involved.
6302 Using Templates to Control Output
6304 Many hg commands support templatized output via the -T/--template argu‐
6305 ment. For more, see hg help templates.
6306 Templates are useful for explicitly controlling output so that you get
6308 exactly the data you want formatted how you want it. For example, log
6309 -T {node}\n can be used to print a newline delimited list of changeset
6310 nodes instead of a human-tailored output containing authors, dates,
6311 descriptions, etc.
6312 Tip If parsing raw command output is too complicated, consider using
6314 templates to make your life easier.
6315 The -T/--template argument allows specifying pre-defined styles. Mer‐
6317 curial ships with the machine-readable styles json and xml, which pro‐
6318 vide JSON and XML output, respectively. These are useful for producing
6319 output that is machine readable as-is.
6320 Important
6322 The json and xml styles are considered experimental. While they
6323 may be attractive to use for easily obtaining machine-readable
6324 output, their behavior may change in subsequent versions.
6325 These styles may also exhibit unexpected results when dealing
6327 with certain encodings. Mercurial treats things like filenames
6328 as a series of bytes and normalizing certain byte sequences to
6329 JSON or XML with certain encoding settings can lead to sur‐
6330 prises.
6331 Command Server Output
6333 If using the command server to interact with Mercurial, you are likely
6334 using an existing library/API that abstracts implementation details of
6335 the command server. If so, this interface layer may perform parsing for
6336 you, saving you the work of implementing it yourself.
6337 Output Verbosity
6339 Commands often have varying output verbosity, even when machine read‐
6340 able styles are being used (e.g. -T json). Adding -v/--verbose and
6341 --debug to the command's arguments can increase the amount of data
6342 exposed by Mercurial.
6343 An alternate way to get the data you need is by explicitly specifying a
6345 template.
6346 Other Topics
6348 revsets
6349 Revisions sets is a functional query language for selecting a
6350 set of revisions. Think of it as SQL for Mercurial repositories.
6351 Revsets are useful for querying repositories for specific data.
6352 See hg help revsets for more.
6354 share extension
6356 The share extension provides functionality for sharing reposi‐
6357 tory data across several working copies. It can even automati‐
6358 cally "pool" storage for logically related repositories when
6359 cloning.
6360 Configuring the share extension can lead to significant resource
6362 utilization reduction, particularly around disk space and the
6363 network. This is especially true for continuous integration (CI)
6364 environments.
6365 See hg help -e share for more.
6367
6369 Subrepositories let you nest external repositories or projects into a
6370 parent Mercurial repository, and make commands operate on them as a
6371 group.
6372 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
6374 tories.
6375 Subrepositories are made of three components:
6377 1. Nested repository checkouts. They can appear anywhere in the parent
6379 working directory.
6380 2. Nested repository references. They are defined in .hgsub, which
6382 should be placed in the root of working directory, and tell where
6383 the subrepository checkouts come from. Mercurial subrepositories are
6384 referenced like:
6385 path/to/nested = https://example.com/nested/repo/path
6387 Git and Subversion subrepos are also supported:
6389 path/to/nested = [git]git://example.com/nested/repo/path
6391 path/to/nested = [svn]https://example.com/nested/trunk/path
6392 where path/to/nested is the checkout location relatively to the par‐
6394 ent Mercurial root, and https://example.com/nested/repo/path is the
6395 source repository path. The source can also reference a filesystem
6396 path.
6397 Note that .hgsub does not exist by default in Mercurial reposito‐
6399 ries, you have to create and add it to the parent repository before
6400 using subrepositories.
6401 3. Nested repository states. They are defined in .hgsubstate, which is
6403 placed in the root of working directory, and capture whatever infor‐
6404 mation is required to restore the subrepositories to the state they
6405 were committed in a parent repository changeset. Mercurial automati‐
6406 cally record the nested repositories states when committing in the
6407 parent repository.
6408 Note
6410 The .hgsubstate file should not be edited manually.
6411 Adding a Subrepository
6413 If .hgsub does not exist, create it and add it to the parent reposi‐
6414 tory. Clone or checkout the external projects where you want it to live
6415 in the parent repository. Edit .hgsub and add the subrepository entry
6416 as described above. At this point, the subrepository is tracked and the
6417 next commit will record its state in .hgsubstate and bind it to the
6418 committed changeset.
6419 Synchronizing a Subrepository
6421 Subrepos do not automatically track the latest changeset of their
6422 sources. Instead, they are updated to the changeset that corresponds
6423 with the changeset checked out in the top-level changeset. This is so
6424 developers always get a consistent set of compatible code and libraries
6425 when they update.
6426 Thus, updating subrepos is a manual process. Simply check out target
6428 subrepo at the desired revision, test in the top-level repo, then com‐
6429 mit in the parent repository to record the new combination.
6430 Deleting a Subrepository
6432 To remove a subrepository from the parent repository, delete its refer‐
6433 ence from .hgsub, then remove its files.
6434 Interaction with Mercurial Commands
6436 add add does not recurse in subrepos unless -S/--subrepos is speci‐
6437 fied. However, if you specify the full path of a file in a sub‐
6438 repo, it will be added even without -S/--subrepos specified.
6439 Subversion subrepositories are currently silently ignored.
6440 addremove
6442 addremove does not recurse into subrepos unless -S/--subrepos is
6443 specified. However, if you specify the full path of a directory
6444 in a subrepo, addremove will be performed on it even without
6445 -S/--subrepos being specified. Git and Subversion subreposito‐
6446 ries will print a warning and continue.
6447 archive
6449 archive does not recurse in subrepositories unless -S/--subrepos
6450 is specified.
6451 cat Git subrepositories only support exact file matches. Subversion
6453 subrepositories are currently ignored.
6454 commit commit creates a consistent snapshot of the state of the entire
6456 project and its subrepositories. If any subrepositories have
6457 been modified, Mercurial will abort. Mercurial can be made to
6458 instead commit all modified subrepositories by specifying
6459 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
6460 ration file (see hg help config). After there are no longer any
6461 modified subrepositories, it records their state and finally
6462 commits it in the parent repository. The --addremove option
6463 also honors the -S/--subrepos option. However, Git and Subver‐
6464 sion subrepositories will print a warning and abort.
6465 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
6467 fied. Changes are displayed as usual, on the subrepositories
6468 elements. Subversion subrepositories are currently silently
6469 ignored.
6470 files files does not recurse into subrepos unless -S/--subrepos is
6472 specified. However, if you specify the full path of a file or
6473 directory in a subrepo, it will be displayed even without
6474 -S/--subrepos being specified. Git and Subversion subreposito‐
6475 ries are currently silently ignored.
6476 forget forget currently only handles exact file matches in subrepos.
6478 Git and Subversion subrepositories are currently silently
6479 ignored.
6480 incoming
6482 incoming does not recurse in subrepos unless -S/--subrepos is
6483 specified. Git and Subversion subrepositories are currently
6484 silently ignored.
6485 outgoing
6487 outgoing does not recurse in subrepos unless -S/--subrepos is
6488 specified. Git and Subversion subrepositories are currently
6489 silently ignored.
6490 pull pull is not recursive since it is not clear what to pull prior
6492 to running hg update. Listing and retrieving all subrepositories
6493 changes referenced by the parent repository pulled changesets is
6494 expensive at best, impossible in the Subversion case.
6495 push Mercurial will automatically push all subrepositories first when
6497 the parent repository is being pushed. This ensures new sub‐
6498 repository changes are available when referenced by top-level
6499 repositories. Push is a no-op for Subversion subrepositories.
6500 serve serve does not recurse into subrepositories unless -S/--subrepos
6502 is specified. Git and Subversion subrepositories are currently
6503 silently ignored.
6504 status status does not recurse into subrepositories unless -S/--subre‐
6506 pos is specified. Subrepository changes are displayed as regular
6507 Mercurial changes on the subrepository elements. Subversion sub‐
6508 repositories are currently silently ignored.
6509 remove remove does not recurse into subrepositories unless -S/--subre‐
6511 pos is specified. However, if you specify a file or directory
6512 path in a subrepo, it will be removed even without -S/--subre‐
6513 pos. Git and Subversion subrepositories are currently silently
6514 ignored.
6515 update update restores the subrepos in the state they were originally
6517 committed in target changeset. If the recorded changeset is not
6518 available in the current subrepository, Mercurial will pull it
6519 in first before updating. This means that updating can require
6520 network access when using subrepositories.
6521 Remapping Subrepositories Sources
6523 A subrepository source location may change during a project life,
6524 invalidating references stored in the parent repository history. To fix
6525 this, rewriting rules can be defined in parent repository hgrc file or
6526 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
6527 more details.
6528
6530 Mercurial allows you to customize output of commands through templates.
6531 You can either pass in a template or select an existing template-style
6532 from the command line, via the --template option.
6533 You can customize output for any "log-like" command: log, outgoing,
6535 incoming, tip, parents, and heads.
6536 Some built-in styles are packaged with Mercurial. These can be listed
6538 with hg log --template list. Example usage:
6539 $ hg log -r1.0::1.1 --template changelog
6541 A template is a piece of text, with markup to invoke variable expan‐
6543 sion:
6544 $ hg log -r1 --template "{node}\n"
6546 b56ce7b07c52de7d5fd79fb89701ea538af65746
6547 Keywords
6549 Strings in curly braces are called keywords. The availability of key‐
6550 words depends on the exact context of the templater. These keywords are
6551 usually available for templating a log-like command:
6552 activebookmark
6554 String. The active bookmark, if it is associated with the
6555 changeset.
6556 author String. The unmodified author of the changeset.
6558 bisect String. The changeset bisection status.
6560 bookmarks
6562 List of strings. Any bookmarks associated with the changeset.
6563 Also sets 'active', the name of the active bookmark.
6564 branch String. The name of the branch on which the changeset was com‐
6566 mitted.
6567 changessincelatesttag
6569 Integer. All ancestors not in the latest tag.
6570 children
6572 List of strings. The children of the changeset.
6573 date Date information. The date when the changeset was committed.
6575 desc String. The text of the changeset description.
6577 diffstat
6579 String. Statistics of changes with the following format: "modi‐
6580 fied files: +added/-removed lines"
6581 extras List of dicts with key, value entries of the 'extras' field of
6583 this changeset.
6584 file_adds
6586 List of strings. Files added by this changeset.
6587 file_copies
6589 List of strings. Files copied in this changeset with their
6590 sources.
6591 file_copies_switch
6593 List of strings. Like "file_copies" but displayed only if the
6594 --copied switch is set.
6595 file_dels
6597 List of strings. Files removed by this changeset.
6598 file_mods
6600 List of strings. Files modified by this changeset.
6601 files List of strings. All files modified, added, or removed by this
6603 changeset.
6604 graphnode
6606 String. The character representing the changeset node in an
6607 ASCII revision graph.
6608 graphwidth
6610 Integer. The width of the graph drawn by 'log --graph' or zero.
6611 index Integer. The current iteration of the loop. (0 indexed)
6613 latesttag
6615 List of strings. The global tags on the most recent globally
6616 tagged ancestor of this changeset. If no such tags exist, the
6617 list consists of the single string "null".
6618 latesttagdistance
6620 Integer. Longest path to the latest tag.
6621 namespaces
6623 Dict of lists. Names attached to this changeset per namespace.
6624 node String. The changeset identification hash, as a 40 hexadecimal
6626 digit string.
6627 p1node String. The identification hash of the changeset's first parent,
6629 as a 40 digit hexadecimal string. If the changeset has no par‐
6630 ents, all digits are 0.
6631 p1rev Integer. The repository-local revision number of the changeset's
6633 first parent, or -1 if the changeset has no parents.
6634 p2node String. The identification hash of the changeset's second par‐
6636 ent, as a 40 digit hexadecimal string. If the changeset has no
6637 second parent, all digits are 0.
6638 p2rev Integer. The repository-local revision number of the changeset's
6640 second parent, or -1 if the changeset has no second parent.
6641 parents
6643 List of strings. The parents of the changeset in "rev:node" for‐
6644 mat. If the changeset has only one "natural" parent (the prede‐
6645 cessor revision) nothing is shown.
6646 peerurls
6648 A dictionary of repository locations defined in the [paths] sec‐
6649 tion of your configuration file.
6650 phase String. The changeset phase name.
6652 rev Integer. The repository-local changeset revision number.
6654 subrepos
6656 List of strings. Updated subrepositories in the changeset.
6657 tags List of strings. Any tags associated with the changeset.
6659 termwidth
6661 Integer. The width of the current terminal.
6662 verbosity
6664 String. The current output verbosity in 'debug', 'quiet', 'ver‐
6665 bose', or ''.
6666 The "date" keyword does not produce human-readable output. If you want
6668 to use a date in your output, you can use a filter to process it. Fil‐
6669 ters are functions which return a string based on the input variable.
6670 Be sure to use the stringify filter first when you're applying a
6671 string-input filter to a list-like input variable. You can also use a
6672 chain of filters to get the desired output:
6673 $ hg tip --template "{date|isodate}\n"
6675 2008-08-21 18:22 +0000
6676 Filters
6678 List of filters:
6679 addbreaks
6681 Any text. Add an XHTML "<br />" tag before the end of every line
6682 except the last.
6683 age Date. Returns a human-readable date/time difference between the
6685 given date/time and the current date/time.
6686 basename
6688 Any text. Treats the text as a path, and returns the last compo‐
6689 nent of the path after splitting by the path separator. For
6690 example, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
6691 count List or text. Returns the length as an integer.
6693 domain Any text. Finds the first string that looks like an email
6695 address, and extracts just the domain component. Example: User
6696 <user@example.com> becomes example.com.
6697 email Any text. Extracts the first string that looks like an email
6699 address. Example: User <user@example.com> becomes user@exam‐
6700 ple.com.
6701 emailuser
6703 Any text. Returns the user portion of an email address.
6704 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
6706 ">" with XML entities, and filters out NUL characters.
6707 fill68 Any text. Wraps the text to fit in 68 columns.
6709 fill76 Any text. Wraps the text to fit in 76 columns.
6711 firstline
6713 Any text. Returns the first line of text.
6714 hex Any text. Convert a binary Mercurial node identifier into its
6716 long hexadecimal representation.
6717 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
6719 (Unix timestamp, timezone offset).
6720 isodate
6722 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
6723 +0200".
6724 isodatesec
6726 Date. Returns the date in ISO 8601 format, including seconds:
6727 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
6728 lower Any text. Converts the text to lowercase.
6730 nonempty
6732 Any text. Returns '(none)' if the string is empty.
6733 obfuscate
6735 Any text. Returns the input text rendered as a sequence of XML
6736 entities.
6737 person Any text. Returns the name before an email address, interpreting
6739 it as per RFC 5322.
6740 revescape
6742 Any text. Escapes all "special" characters, except @. Forward
6743 slashes are escaped twice to prevent web servers from prema‐
6744 turely unescaping them. For example, "@foo bar/baz" becomes
6745 "@foo%20bar%252Fbaz".
6746 rfc3339date
6748 Date. Returns a date using the Internet date format specified in
6749 RFC 3339: "2009-08-18T13:00:13+02:00".
6750 rfc822date
6752 Date. Returns a date using the same format used in email head‐
6753 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
6754 short Changeset hash. Returns the short form of a changeset hash, i.e.
6756 a 12 hexadecimal digit string.
6757 shortbisect
6759 Any text. Treats text as a bisection status, and returns a sin‐
6760 gle-character representing the status (G: good, B: bad, S:
6761 skipped, U: untested, I: ignored). Returns single space if text
6762 is not a valid bisection status.
6763 shortdate
6765 Date. Returns a date like "2006-09-18".
6766 slashpath
6768 Any text. Replaces the native path separator with slash.
6769 splitlines
6771 Any text. Split text into a list of lines.
6772 stringify
6774 Any type. Turns the value into text by converting values into
6775 text and concatenating them.
6776 stripdir
6778 Treat the text as path and strip a directory level, if possible.
6779 For example, "foo" and "foo/bar" becomes "foo".
6780 tabindent
6782 Any text. Returns the text, with every non-empty line except the
6783 first starting with a tab character.
6784 upper Any text. Converts the text to uppercase.
6786 urlescape
6788 Any text. Escapes all "special" characters. For example, "foo
6789 bar" becomes "foo%20bar".
6790 user Any text. Returns a short representation of a user name or email
6792 address.
6793 utf8 Any text. Converts from the local character encoding to UTF-8.
6795 Note that a filter is nothing more than a function call, i.e.
6797 expr|filter is equivalent to filter(expr).
6798 Functions
6800 In addition to filters, there are some basic built-in functions:
6801 date(date[, fmt])
6803 Format a date. See hg help dates for formatting strings. The
6804 default is a Unix date format, including the timezone: "Mon Sep
6805 04 15:13:13 2006 0700".
6806 dict([[key=]value...])
6808 Construct a dict from key-value pairs. A key may be omitted if a
6809 value expression can provide an unambiguous name.
6810 diff([includepattern [, excludepattern]])
6812 Show a diff, optionally specifying files to include or exclude.
6813 files(pattern)
6815 All files of the current changeset matching the pattern. See hg
6816 help patterns.
6817 fill(text[, width[, initialident[, hangindent]]])
6819 Fill many paragraphs with optional indentation. See the "fill"
6820 filter.
6821 get(dict, key)
6823 Get an attribute/key from an object. Some keywords are complex
6824 types. This function allows you to obtain the value of an
6825 attribute on these types.
6826 if(expr, then[, else])
6828 Conditionally execute based on the result of an expression.
6829 ifcontains(needle, haystack, then[, else])
6831 Conditionally execute based on whether the item "needle" is in
6832 "haystack".
6833 ifeq(expr1, expr2, then[, else])
6835 Conditionally execute based on whether 2 items are equivalent.
6836 indent(text, indentchars[, firstline])
6838 Indents all non-empty lines with the characters given in the
6839 indentchars string. An optional third parameter will override
6840 the indent for the first line only if present.
6841 join(list, sep)
6843 Join items in a list with a delimiter.
6844 label(label, expr)
6846 Apply a label to generated content. Content with a label applied
6847 can result in additional post-processing, such as automatic col‐
6848 orization.
6849 latesttag([pattern])
6851 The global tags matching the given pattern on the most recent
6852 globally tagged ancestor of this changeset. If no such tags
6853 exist, the "{tag}" template resolves to the string "null".
6854 localdate(date[, tz])
6856 Converts a date to the specified timezone. The default is local
6857 date.
6858 max(iterable)
6860 Return the max of an iterable
6861 min(iterable)
6863 Return the min of an iterable
6864 mod(a, b)
6866 Calculate a mod b such that a / b + a mod b == a
6867 pad(text, width[, fillchar=' '[, left=False]])
6869 Pad text with a fill character.
6870 relpath(path)
6872 Convert a repository-absolute path into a filesystem path rela‐
6873 tive to the current working directory.
6874 revset(query[, formatargs...])
6876 Execute a revision set query. See hg help revset.
6877 rstdoc(text, style)
6879 Format reStructuredText.
6880 separate(sep, args)
6882 Add a separator between non-empty arguments.
6883 shortest(node, minlength=4)
6885 Obtain the shortest representation of a node.
6886 startswith(pattern, text)
6888 Returns the value from the "text" argument if it begins with the
6889 content from the "pattern" argument.
6890 strip(text[, chars])
6892 Strip characters from a string. By default, strips all leading
6893 and trailing whitespace.
6894 sub(pattern, replacement, expression)
6896 Perform text substitution using regular expressions.
6897 word(number, text[, separator])
6899 Return the nth word from a string.
6900 Operators
6902 We provide a limited set of infix arithmetic operations on integers:
6903 + for addition
6905 - for subtraction
6906 * for multiplication
6907 / for floor division (division rounded to integer nearest -infinity)
6908 Division fulfills the law x = x / y + mod(x, y).
6910 Also, for any expression that returns a list, there is a list operator:
6912 expr % "{template}"
6914 As seen in the above example, {template} is interpreted as a template.
6916 To prevent it from being interpreted, you can use an escape character
6917 \{ or a raw string prefix, r'...'.
6918 The dot operator can be used as a shorthand for accessing a sub item:
6920 · expr.member is roughly equivalent to expr % '{member}' if expr
6922 returns a non-list/dict. The returned value is not stringified.
6923 · dict.key is identical to get(dict, 'key').
6925 Aliases
6927 New keywords and functions can be defined in the templatealias section
6928 of a Mercurial configuration file:
6929 <alias> = <definition>
6931 Arguments of the form a1, a2, etc. are substituted from the alias into
6933 the definition.
6934 For example,
6936 [templatealias]
6938 r = rev
6939 rn = "{r}:{node|short}"
6940 leftpad(s, w) = pad(s, w, ' ', True)
6941 defines two symbol aliases, r and rn, and a function alias leftpad().
6943 It's also possible to specify complete template strings, using the tem‐
6945 plates section. The syntax used is the general template string syntax.
6946 For example,
6948 [templates]
6950 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
6951 defines a template, nodedate, which can be called like:
6953 $ hg log -r . -Tnodedate
6955 A template defined in templates section can also be referenced from
6957 another template:
6958 $ hg log -r . -T "{rev} {nodedate}"
6960 but be aware that the keywords cannot be overridden by templates. For
6962 example, a template defined as templates.rev cannot be referenced as
6963 {rev}.
6964 A template defined in templates section may have sub templates which
6966 are inserted before/after/between items:
6967 [templates]
6969 myjson = ' {dict(rev, node|short)|json}'
6970 myjson:docheader = '\{\n'
6971 myjson:docfooter = '\n}\n'
6972 myjson:separator = ',\n'
6973 Examples
6975 Some sample command line templates:
6976 · Format lists, e.g. files:
6978 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
6980 · Join the list of files with a ", ":
6982 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
6984 · Join the list of files ending with ".py" with a ", ":
6986 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
6988 · Separate non-empty arguments by a " ":
6990 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
6992 · Modify each line of a commit description:
6994 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
6996 · Format date:
6998 $ hg log -r 0 --template "{date(date, '%Y')}\n"
7000 · Display date in UTC:
7002 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
7004 · Output the description set to a fill-width of 30:
7006 $ hg log -r 0 --template "{fill(desc, 30)}"
7008 · Use a conditional to test for the default branch:
7010 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
7012 'on branch {branch}')}\n"
7013 · Append a newline if not empty:
7015 $ hg tip --template "{if(author, '{author}\n')}"
7017 · Label the output for use with the color extension:
7019 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
7021 · Invert the firstline filter, i.e. everything but the first line:
7023 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
7025 · Display the contents of the 'extra' field, one per line:
7027 $ hg log -r 0 --template "{join(extras, '\n')}\n"
7029 · Mark the active bookmark with '*':
7031 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
7033 · Find the previous release candidate tag, the distance and changes
7035 since the tag:
7036 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
7038 · Mark the working copy parent with '@':
7040 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
7042 · Show details of parent revisions:
7044 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
7046 · Show only commit descriptions that start with "template":
7048 $ hg log --template "{startswith('template', firstline(desc))}\n"
7050 · Print the first word of each line of a commit message:
7052 $ hg log --template "{word(0, desc)}\n"
7054
7056 Valid URLs are of the form:
7057 local/filesystem/path[#revision]
7059 file://local/filesystem/path[#revision]
7060 http://[user[:pass]@]host[:port]/[path][#revision]
7061 https://[user[:pass]@]host[:port]/[path][#revision]
7062 ssh://[user@]host[:port]/[path][#revision]
7063 Paths in the local filesystem can either point to Mercurial reposito‐
7065 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
7066 dle). See also hg help paths.
7067 An optional identifier after # indicates a particular branch, tag, or
7069 changeset to use from the remote repository. See also hg help revisions
7070 .
7071 Some features, such as pushing to http:// and https:// URLs are only
7073 possible if the feature is explicitly enabled on the remote Mercurial
7074 server.
7075 Note that the security of HTTPS URLs depends on proper configuration of
7077 web.cacerts.
7078 Some notes about using SSH with Mercurial:
7080 · SSH requires an accessible shell account on the destination machine
7082 and a copy of hg in the remote path or specified with remotecmd.
7083 · path is relative to the remote user's home directory by default. Use
7085 an extra slash at the start of a path to specify an absolute path:
7086 ssh://example.com//tmp/repository
7088 · Mercurial doesn't use its own compression via SSH; the right thing to
7090 do is to configure it in your ~/.ssh/config, e.g.:
7091 Host *.mylocalnetwork.example.com
7093 Compression no
7094 Host *
7095 Compression yes
7096 Alternatively specify "ssh -C" as your ssh command in your configura‐
7098 tion file or with the --ssh command line option.
7099 These URLs can all be stored in your configuration file with path
7101 aliases under the [paths] section like so:
7102 [paths]
7104 alias1 = URL1
7105 alias2 = URL2
7106 ...
7107 You can then use the alias for any command that uses a URL (for example
7109 hg pull alias1 will be treated as hg pull URL1).
7110 Two path aliases are special because they are used as defaults when you
7112 do not provide the URL to a command:
7113 default:
7115 When you create a repository with hg clone, the clone command
7116 saves the location of the source repository as the new reposi‐
7117 tory's 'default' path. This is then used when you omit path from
7118 push- and pull-like commands (including incoming and outgoing).
7119 default-push:
7121 The push command will look for a path named 'default-push', and
7122 prefer it over 'default' if both are defined.
7123
7125 This section contains help for extensions that are distributed together
7126 with Mercurial. Help for other extensions is available in the help sys‐
7127 tem.
7128 acl
7130 hooks for controlling repository access
7131 This hook makes it possible to allow or deny write access to given
7133 branches and paths of a repository when receiving incoming changesets
7134 via pretxnchangegroup and pretxncommit.
7135 The authorization is matched based on the local user name on the system
7137 where the hook runs, and not the committer of the original changeset
7138 (since the latter is merely informative).
7139 The acl hook is best used along with a restricted shell like hgsh, pre‐
7141 venting authenticating users from doing anything other than pushing or
7142 pulling. The hook is not safe to use if users have interactive shell
7143 access, as they can then disable the hook. Nor is it safe if remote
7144 users share an account, because then there is no way to distinguish
7145 them.
7146 The order in which access checks are performed is:
7148 1. Deny list for branches (section acl.deny.branches)
7150 2. Allow list for branches (section acl.allow.branches)
7152 3. Deny list for paths (section acl.deny)
7154 4. Allow list for paths (section acl.allow)
7156 The allow and deny sections take key-value pairs.
7158 Branch-based Access Control
7160 Use the acl.deny.branches and acl.allow.branches sections to have
7161 branch-based access control. Keys in these sections can be either:
7162 · a branch name, or
7164 · an asterisk, to match any branch;
7166 The corresponding values can be either:
7168 · a comma-separated list containing users and groups, or
7170 · an asterisk, to match anyone;
7172 You can add the "!" prefix to a user or group name to invert the sense
7174 of the match.
7175 Path-based Access Control
7177 Use the acl.deny and acl.allow sections to have path-based access con‐
7178 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
7179 tax by default). The corresponding values follow the same syntax as the
7180 other sections above.
7181 Groups
7183 Group names must be prefixed with an @ symbol. Specifying a group name
7184 has the same effect as specifying all the users in that group.
7185 You can define group members in the acl.groups section. If a group
7187 name is not defined there, and Mercurial is running under a Unix-like
7188 system, the list of users will be taken from the OS. Otherwise, an
7189 exception will be raised.
7190 Example Configuration
7192 [hooks]
7193 # Use this if you want to check access restrictions at commit time
7195 pretxncommit.acl = python:hgext.acl.hook
7196 # Use this if you want to check access restrictions for pull, push,
7198 # bundle and serve.
7199 pretxnchangegroup.acl = python:hgext.acl.hook
7200 [acl]
7202 # Allow or deny access for incoming changes only if their source is
7203 # listed here, let them pass otherwise. Source is "serve" for all
7204 # remote access (http or ssh), "push", "pull" or "bundle" when the
7205 # related commands are run locally.
7206 # Default: serve
7207 sources = serve
7208 [acl.deny.branches]
7210 # Everyone is denied to the frozen branch:
7212 frozen-branch = *
7213 # A bad user is denied on all branches:
7215 * = bad-user
7216 [acl.allow.branches]
7218 # A few users are allowed on branch-a:
7220 branch-a = user-1, user-2, user-3
7221 # Only one user is allowed on branch-b:
7223 branch-b = user-1
7224 # The super user is allowed on any branch:
7226 * = super-user
7227 # Everyone is allowed on branch-for-tests:
7229 branch-for-tests = *
7230 [acl.deny]
7232 # This list is checked first. If a match is found, acl.allow is not
7233 # checked. All users are granted access if acl.deny is not present.
7234 # Format for both lists: glob pattern = user, ..., @group, ...
7235 # To match everyone, use an asterisk for the user:
7237 # my/glob/pattern = *
7238 # user6 will not have write access to any file:
7240 ** = user6
7241 # Group "hg-denied" will not have write access to any file:
7243 ** = @hg-denied
7244 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
7246 # everyone being able to change all other files. See below.
7247 src/main/resources/DONT-TOUCH-THIS.txt = *
7248 [acl.allow]
7250 # if acl.allow is not present, all users are allowed by default
7251 # empty acl.allow = no users allowed
7252 # User "doc_writer" has write access to any file under the "docs"
7254 # folder:
7255 docs/** = doc_writer
7256 # User "jack" and group "designers" have write access to any file
7258 # under the "images" folder:
7259 images/** = jack, @designers
7260 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
7262 # will have write access to any file under the "resources" folder
7263 # (except for 1 file. See acl.deny):
7264 src/main/resources/** = *
7265 .hgtags = release_engineer
7267 Examples using the ! prefix
7269 Suppose there's a branch that only a given user (or group) should be
7270 able to push to, and you don't want to restrict access to any other
7271 branch that may be created.
7272 The "!" prefix allows you to prevent anyone except a given user or
7274 group to push changesets in a given branch or path.
7275 In the examples below, we will: 1) Deny access to branch "ring" to any‐
7277 one but user "gollum" 2) Deny access to branch "lake" to anyone but
7278 members of the group "hobbit" 3) Deny access to a file to anyone but
7279 user "gollum"
7280 [acl.allow.branches]
7282 # Empty
7283 [acl.deny.branches]
7285 # 1) only 'gollum' can commit to branch 'ring';
7287 # 'gollum' and anyone else can still commit to any other branch.
7288 ring = !gollum
7289 # 2) only members of the group 'hobbit' can commit to branch 'lake';
7291 # 'hobbit' members and anyone else can still commit to any other branch.
7292 lake = !@hobbit
7293 # You can also deny access based on file paths:
7295 [acl.allow]
7297 # Empty
7298 [acl.deny]
7300 # 3) only 'gollum' can change the file below;
7301 # 'gollum' and anyone else can still change any other file.
7302 /misty/mountains/cave/ring = !gollum
7303 amend
7305 provide the amend command (EXPERIMENTAL)
7306 This extension provides an amend command that is similar to commit
7308 --amend but does not prompt an editor.
7309 Commands
7311 amend
7312 amend the working copy parent with all or specified outstanding
7313 changes:
7314 hg amend [OPTION]... [FILE]...
7316 Similar to hg commit --amend, but reuse the commit message without
7318 invoking editor, unless --edit was set.
7319 See hg help commit for more details.
7321 Options:
7323 -A, --addremove
7325 mark new/missing files as added/removed before committing
7326 -e, --edit
7328 invoke editor on commit messages
7329 -i, --interactive
7331 use interactive mode
7332 -n,--note <VALUE>
7334 store a note on the amend
7335 -I,--include <PATTERN[+]>
7337 include names matching the given patterns
7338 -X,--exclude <PATTERN[+]>
7340 exclude names matching the given patterns
7341 -m,--message <TEXT>
7343 use text as commit message
7344 -l,--logfile <FILE>
7346 read commit message from file
7347 -d,--date <DATE>
7349 record the specified date as commit date
7350 -u,--user <USER>
7352 record the specified user as committer
7353 [+] marked option can be specified multiple times
7355 automv
7357 check for unrecorded moves at commit time (EXPERIMENTAL)
7358 This extension checks at commit/amend time if any of the committed
7360 files comes from an unrecorded mv.
7361 The threshold at which a file is considered a move can be set with the
7363 automv.similarity config option. This option takes a percentage between
7364 0 (disabled) and 100 (files must be identical), the default is 95.
7365 blackbox
7367 log repository events to a blackbox for debugging
7368 Logs event information to .hg/blackbox.log to help debug and diagnose
7370 problems. The events that get logged can be configured via the black‐
7371 box.track config key.
7372 Examples:
7374 [blackbox]
7376 track = *
7377 # dirty is *EXPENSIVE* (slow);
7378 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
7379 dirty = True
7380 # record the source of log messages
7381 logsource = True
7382 [blackbox]
7384 track = command, commandfinish, commandexception, exthook, pythonhook
7385 [blackbox]
7387 track = incoming
7388 [blackbox]
7390 # limit the size of a log file
7391 maxsize = 1.5 MB
7392 # rotate up to N log files when the current one gets too big
7393 maxfiles = 3
7394 Commands
7396 blackbox
7397 view the recent repository events:
7398 hg blackbox [OPTION]...
7400 view the recent repository events
7402 Options:
7404 -l,--limit <VALUE>
7406 the number of events to show (default: 10)
7407 bugzilla
7409 hooks for integrating with the Bugzilla bug tracker
7410 This hook extension adds comments on bugs in Bugzilla when changesets
7412 that refer to bugs by Bugzilla ID are seen. The comment is formatted
7413 using the Mercurial template mechanism.
7414 The bug references can optionally include an update for Bugzilla of the
7416 hours spent working on the bug. Bugs can also be marked fixed.
7417 Four basic modes of access to Bugzilla are provided:
7419 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
7421 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
7423 later.
7424 3. Check data via the Bugzilla XMLRPC interface and submit bug change
7426 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
7427 later.
7428 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
7430 tions using MySQL are supported. Requires Python MySQLdb.
7431 Writing directly to the database is susceptible to schema changes, and
7433 relies on a Bugzilla contrib script to send out bug change notification
7434 emails. This script runs as the user running Mercurial, must be run on
7435 the host with the Bugzilla install, and requires permission to read
7436 Bugzilla configuration details and the necessary MySQL user and pass‐
7437 word to have full access rights to the Bugzilla database. For these
7438 reasons this access mode is now considered deprecated, and will not be
7439 updated for new Bugzilla versions going forward. Only adding comments
7440 is supported in this access mode.
7441 Access via XMLRPC needs a Bugzilla username and password to be speci‐
7443 fied in the configuration. Comments are added under that username.
7444 Since the configuration must be readable by all Mercurial users, it is
7445 recommended that the rights of that user are restricted in Bugzilla to
7446 the minimum necessary to add comments. Marking bugs fixed requires
7447 Bugzilla 4.0 and later.
7448 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
7450 to the Bugzilla email interface to submit comments to bugs. The From:
7451 address in the email is set to the email address of the Mercurial user,
7452 so the comment appears to come from the Mercurial user. In the event
7453 that the Mercurial user email is not recognized by Bugzilla as a
7454 Bugzilla user, the email associated with the Bugzilla username used to
7455 log into Bugzilla is used instead as the source of the comment. Marking
7456 bugs fixed works on all supported Bugzilla versions.
7457 Access via the REST-API needs either a Bugzilla username and password
7459 or an apikey specified in the configuration. Comments are made under
7460 the given username or the user associated with the apikey in Bugzilla.
7461 Configuration items common to all access modes:
7463 bugzilla.version
7465 The access type to use. Values recognized are:
7466 restapi
7468 Bugzilla REST-API, Bugzilla 5.0 and later.
7470 xmlrpc
7472 Bugzilla XMLRPC interface.
7474 xmlrpc+email
7476 Bugzilla XMLRPC and email interfaces.
7478 3.0
7480 MySQL access, Bugzilla 3.0 and later.
7482 2.18
7484 MySQL access, Bugzilla 2.18 and up to but not including
7486 3.0.
7487 2.16
7489 MySQL access, Bugzilla 2.16 and up to but not including
7491 2.18.
7492 bugzilla.regexp
7494 Regular expression to match bug IDs for update in changeset com‐
7495 mit message. It must contain one "()" named group <ids> con‐
7496 taining the bug IDs separated by non-digit characters. It may
7497 also contain a named group <hours> with a floating-point number
7498 giving the hours worked on the bug. If no named groups are
7499 present, the first "()" group is assumed to contain the bug IDs,
7500 and work time is not updated. The default expression matches Bug
7501 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
7502 and 5678 and variations thereof, followed by an hours number
7503 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
7504 sitive.
7505 bugzilla.fixregexp
7507 Regular expression to match bug IDs for marking fixed in change‐
7508 set commit message. This must contain a "()" named group <ids>`
7509 containing the bug IDs separated by non-digit characters. It may
7510 also contain a named group ``<hours> with a floating-point num‐
7511 ber giving the hours worked on the bug. If no named groups are
7512 present, the first "()" group is assumed to contain the bug IDs,
7513 and work time is not updated. The default expression matches
7514 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
7515 5678 and variations thereof, followed by an hours number pre‐
7516 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
7517 tive.
7518 bugzilla.fixstatus
7520 The status to set a bug to when marking fixed. Default RESOLVED.
7521 bugzilla.fixresolution
7523 The resolution to set a bug to when marking fixed. Default
7524 FIXED.
7525 bugzilla.style
7527 The style file to use when formatting comments.
7528 bugzilla.template
7530 Template to use when formatting comments. Overrides style if
7531 specified. In addition to the usual Mercurial keywords, the
7532 extension specifies:
7533 {bug}
7535 The Bugzilla bug ID.
7537 {root}
7539 The full pathname of the Mercurial repository.
7541 {webroot}
7543 Stripped pathname of the Mercurial repository.
7545 {hgweb}
7547 Base URL for browsing Mercurial repositories.
7549 Default changeset {node|short} in repo {root} refers to bug
7551 {bug}.\ndetails:\n\t{desc|tabindent}
7552 bugzilla.strip
7554 The number of path separator characters to strip from the front
7555 of the Mercurial repository path ({root} in templates) to pro‐
7556 duce {webroot}. For example, a repository with {root}
7557 /var/local/my-project with a strip of 2 gives a value for {web‐
7558 root} of my-project. Default 0.
7559 web.baseurl
7561 Base URL for browsing Mercurial repositories. Referenced from
7562 templates as {hgweb}.
7563 Configuration items common to XMLRPC+email and MySQL access modes:
7565 bugzilla.usermap
7567 Path of file containing Mercurial committer email to Bugzilla
7568 user email mappings. If specified, the file should contain one
7569 mapping per line:
7570 committer = Bugzilla user
7572 See also the [usermap] section.
7574 The [usermap] section is used to specify mappings of Mercurial commit‐
7576 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
7577 entries of the form committer = Bugzilla user.
7578 XMLRPC and REST-API access mode configuration:
7580 bugzilla.bzurl
7582 The base URL for the Bugzilla installation. Default
7583 http://localhost/bugzilla.
7584 bugzilla.user
7586 The username to use to log into Bugzilla via XMLRPC. Default
7587 bugs.
7588 bugzilla.password
7590 The password for Bugzilla login.
7591 REST-API access mode uses the options listed above as well as:
7593 bugzilla.apikey
7595 An apikey generated on the Bugzilla instance for api access.
7596 Using an apikey removes the need to store the user and password
7597 options.
7598 XMLRPC+email access mode uses the XMLRPC access mode configuration
7600 items, and also:
7601 bugzilla.bzemail
7603 The Bugzilla email address.
7604 In addition, the Mercurial email settings must be configured. See the
7606 documentation in hgrc(5), sections [email] and [smtp].
7607 MySQL access mode configuration:
7609 bugzilla.host
7611 Hostname of the MySQL server holding the Bugzilla database.
7612 Default localhost.
7613 bugzilla.db
7615 Name of the Bugzilla database in MySQL. Default bugs.
7616 bugzilla.user
7618 Username to use to access MySQL server. Default bugs.
7619 bugzilla.password
7621 Password to use to access MySQL server.
7622 bugzilla.timeout
7624 Database connection timeout (seconds). Default 5.
7625 bugzilla.bzuser
7627 Fallback Bugzilla user name to record comments with, if change‐
7628 set committer cannot be found as a Bugzilla user.
7629 bugzilla.bzdir
7631 Bugzilla install directory. Used by default notify. Default
7632 /var/www/html/bugzilla.
7633 bugzilla.notify
7635 The command to run to get Bugzilla to send bug change notifica‐
7636 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
7637 id) and user (committer bugzilla email). Default depends on ver‐
7638 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
7639 mail.pl %(id)s %(user)s".
7640 Activating the extension:
7642 [extensions]
7644 bugzilla =
7645 [hooks]
7647 # run bugzilla hook on every change pulled or pushed in here
7648 incoming.bugzilla = python:hgext.bugzilla.hook
7649 Example configurations:
7651 XMLRPC example configuration. This uses the Bugzilla at
7653 http://my-project.org/bugzilla, logging in as user bug‐
7654 mail@my-project.org with password plugh. It is used with a collection
7655 of Mercurial repositories in /var/local/hg/repos/, with a web interface
7656 at http://my-project.org/hg.
7657 [bugzilla]
7659 bzurl=http://my-project.org/bugzilla
7660 user=bugmail@my-project.org
7661 password=plugh
7662 version=xmlrpc
7663 template=Changeset {node|short} in {root|basename}.
7664 {hgweb}/{webroot}/rev/{node|short}\n
7665 {desc}\n
7666 strip=5
7667 [web]
7669 baseurl=http://my-project.org/hg
7670 XMLRPC+email example configuration. This uses the Bugzilla at
7672 http://my-project.org/bugzilla, logging in as user bug‐
7673 mail@my-project.org with password plugh. It is used with a collection
7674 of Mercurial repositories in /var/local/hg/repos/, with a web interface
7675 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
7676 email address bugzilla@my-project.org.
7677 [bugzilla]
7679 bzurl=http://my-project.org/bugzilla
7680 user=bugmail@my-project.org
7681 password=plugh
7682 version=xmlrpc+email
7683 bzemail=bugzilla@my-project.org
7684 template=Changeset {node|short} in {root|basename}.
7685 {hgweb}/{webroot}/rev/{node|short}\n
7686 {desc}\n
7687 strip=5
7688 [web]
7690 baseurl=http://my-project.org/hg
7691 [usermap]
7693 user@emaildomain.com=user.name@bugzilladomain.com
7694 MySQL example configuration. This has a local Bugzilla 3.2 installation
7696 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
7697 database name is bugs and MySQL is accessed with MySQL username bugs
7698 password XYZZY. It is used with a collection of Mercurial repositories
7699 in /var/local/hg/repos/, with a web interface at
7700 http://my-project.org/hg.
7701 [bugzilla]
7703 host=localhost
7704 password=XYZZY
7705 version=3.0
7706 bzuser=unknown@domain.com
7707 bzdir=/opt/bugzilla-3.2
7708 template=Changeset {node|short} in {root|basename}.
7709 {hgweb}/{webroot}/rev/{node|short}\n
7710 {desc}\n
7711 strip=5
7712 [web]
7714 baseurl=http://my-project.org/hg
7715 [usermap]
7717 user@emaildomain.com=user.name@bugzilladomain.com
7718 All the above add a comment to the Bugzilla bug record of the form:
7720 Changeset 3b16791d6642 in repository-name.
7722 http://my-project.org/hg/repository-name/rev/3b16791d6642
7723 Changeset commit comment. Bug 1234.
7725 censor
7727 erase file content at a given revision
7728 The censor command instructs Mercurial to erase all content of a file
7730 at a given revision without updating the changeset hash. This allows
7731 existing history to remain valid while preventing future clones/pulls
7732 from receiving the erased data.
7733 Typical uses for censor are due to security or legal requirements,
7735 including:
7736 * Passwords, private keys, cryptographic material
7738 * Licensed data/code/libraries for which the license has expired
7739 * Personally Identifiable Information or other private data
7740 Censored nodes can interrupt mercurial's typical operation whenever the
7742 excised data needs to be materialized. Some commands, like hg cat/hg
7743 revert, simply fail when asked to produce censored data. Others, like
7744 hg verify and hg update, must be capable of tolerating censored data to
7745 continue to function in a meaningful way. Such commands only tolerate
7746 censored file revisions if they are allowed by the "censor.pol‐
7747 icy=ignore" config option.
7748 Commands
7750 censor
7751 hg censor -r REV [-t TEXT] [FILE]
7752 Options:
7754 -r,--rev <REV>
7756 censor file from specified revision
7757 -t,--tombstone <TEXT>
7759 replacement tombstone data
7760 children
7762 command to display child changesets (DEPRECATED)
7763 This extension is deprecated. You should use hg log -r "children(REV)"
7765 instead.
7766 Commands
7768 children
7769 show the children of the given or working directory revision:
7770 hg children [-r REV] [FILE]
7772 Print the children of the working directory's revisions. If a revision
7774 is given via -r/--rev, the children of that revision will be printed.
7775 If a file argument is given, revision in which the file was last
7776 changed (after the working directory revision or the argument to --rev
7777 if given) is printed.
7778 Please use hg log instead:
7780 hg children => hg log -r "children(.)"
7782 hg children -r REV => hg log -r "children(REV)"
7783 See hg help log and hg help revsets.children.
7785 Options:
7787 -r,--rev <REV>
7789 show children of the specified revision
7790 --style <STYLE>
7792 display using template map file (DEPRECATED)
7793 -T,--template <TEMPLATE>
7795 display with template
7796 churn
7798 command to display statistics about repository history
7799 Commands
7801 churn
7802 histogram of changes to the repository:
7803 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
7805 This command will display a histogram representing the number of
7807 changed lines or revisions, grouped according to the given template.
7808 The default template will group changes by author. The --dateformat
7809 option may be used to group the results by date instead.
7810 Statistics are based on the number of changed lines, or alternatively
7812 the number of matching revisions if the --changesets option is speci‐
7813 fied.
7814 Examples:
7816 # display count of changed lines for every committer
7818 hg churn -T "{author|email}"
7819 # display daily activity graph
7821 hg churn -f "%H" -s -c
7822 # display activity of developers by month
7824 hg churn -f "%Y-%m" -s -c
7825 # display count of lines changed in every year
7827 hg churn -f "%Y" -s
7828 It is possible to map alternate email addresses to a main address by
7830 providing a file using the following format:
7831 <alias email> = <actual email>
7833 Such a file may be specified with the --aliases option, otherwise a
7835 .hgchurn file will be looked for in the working directory root.
7836 Aliases will be split from the rightmost "=".
7837 Options:
7839 -r,--rev <REV[+]>
7841 count rate for the specified revision or revset
7842 -d,--date <DATE>
7844 count rate for revisions matching date spec
7845 -t,--oldtemplate <TEMPLATE>
7847 template to group changesets (DEPRECATED)
7848 -T,--template <TEMPLATE>
7850 template to group changesets (default: {author|email})
7851 -f,--dateformat <FORMAT>
7853 strftime-compatible format for grouping by date
7854 -c, --changesets
7856 count rate by number of changesets
7857 -s, --sort
7859 sort by key (default: sort by count)
7860 --diffstat
7862 display added/removed lines separately
7863 --aliases <FILE>
7865 file with email aliases
7866 -I,--include <PATTERN[+]>
7868 include names matching the given patterns
7869 -X,--exclude <PATTERN[+]>
7871 exclude names matching the given patterns
7872 [+] marked option can be specified multiple times
7874 clonebundles
7876 advertise pre-generated bundles to seed clones
7877 "clonebundles" is a server-side extension used to advertise the exis‐
7879 tence of pre-generated, externally hosted bundle files to clients that
7880 are cloning so that cloning can be faster, more reliable, and require
7881 less resources on the server.
7882 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
7884 ally, the server, in response to a client's request to clone, dynami‐
7885 cally generates a bundle containing the entire repository content and
7886 sends it to the client. There is no caching on the server and the
7887 server will have to redundantly generate the same outgoing bundle in
7888 response to each clone request. For servers with large repositories or
7889 with high clone volume, the load from clones can make scaling the
7890 server challenging and costly.
7891 This extension provides server operators the ability to offload poten‐
7893 tially expensive clone load to an external service. Here's how it
7894 works.
7895 1. A server operator establishes a mechanism for making bundle files
7897 available on a hosting service where Mercurial clients can fetch
7898 them.
7899 2. A manifest file listing available bundle URLs and some optional
7901 metadata is added to the Mercurial repository on the server.
7902 3. A client initiates a clone against a clone bundles aware server.
7904 4. The client sees the server is advertising clone bundles and fetches
7906 the manifest listing available bundles.
7907 5. The client filters and sorts the available bundles based on what it
7909 supports and prefers.
7910 6. The client downloads and applies an available bundle from the
7912 server-specified URL.
7913 7. The client reconnects to the original server and performs the equiv‐
7915 alent of hg pull to retrieve all repository data not in the bundle.
7916 (The repository could have been updated between when the bundle was
7917 created and when the client started the clone.)
7918 Instead of the server generating full repository bundles for every
7920 clone request, it generates full bundles once and they are subsequently
7921 reused to bootstrap new clones. The server may still transfer data at
7922 clone time. However, this is only data that has been added/changed
7923 since the bundle was created. For large, established repositories, this
7924 can reduce server load for clones to less than 1% of original.
7925 To work, this extension requires the following of server operators:
7927 · Generating bundle files of repository content (typically periodi‐
7929 cally, such as once per day).
7930 · A file server that clients have network access to and that Python
7932 knows how to talk to through its normal URL handling facility (typi‐
7933 cally an HTTP server).
7934 · A process for keeping the bundles manifest in sync with available
7936 bundle files.
7937 Strictly speaking, using a static file hosting server isn't required: a
7939 server operator could use a dynamic service for retrieving bundle data.
7940 However, static file hosting services are simple and scalable and
7941 should be sufficient for most needs.
7942 Bundle files can be generated with the hg bundle command. Typically hg
7944 bundle --all is used to produce a bundle of the entire repository.
7945 hg debugcreatestreamclonebundle can be used to produce a special
7947 streaming clone bundle. These are bundle files that are extremely effi‐
7948 cient to produce and consume (read: fast). However, they are larger
7949 than traditional bundle formats and require that clients support the
7950 exact set of repository data store formats in use by the repository
7951 that created them. Typically, a newer server can serve data that is
7952 compatible with older clients. However, streaming clone bundles don't
7953 have this guarantee. Server operators need to be aware that newer ver‐
7954 sions of Mercurial may produce streaming clone bundles incompatible
7955 with older Mercurial versions.
7956 A server operator is responsible for creating a .hg/clonebundles.mani‐
7958 fest file containing the list of available bundle files suitable for
7959 seeding clones. If this file does not exist, the repository will not
7960 advertise the existence of clone bundles when clients connect.
7961 The manifest file contains a newline (n) delimited list of entries.
7963 Each line in this file defines an available bundle. Lines have the for‐
7965 mat:
7966 <URL> [<key>=<value>[ <key>=<value>]]
7968 That is, a URL followed by an optional, space-delimited list of
7970 key=value pairs describing additional properties of this bundle. Both
7971 keys and values are URI encoded.
7972 Keys in UPPERCASE are reserved for use by Mercurial and are defined
7974 below. All non-uppercase keys can be used by site installations. An
7975 example use for custom properties is to use the datacenter attribute to
7976 define which data center a file is hosted in. Clients could then prefer
7977 a server in the data center closest to them.
7978 The following reserved keys are currently defined:
7980 BUNDLESPEC
7982 A "bundle specification" string that describes the type of the
7983 bundle.
7984 These are string values that are accepted by the "--type" argu‐
7986 ment of hg bundle.
7987 The values are parsed in strict mode, which means they must be
7989 of the "<compression>-<type>" form. See mercu‐
7990 rial.exchange.parsebundlespec() for more details.
7991 hg debugbundle --spec can be used to print the bundle specifica‐
7993 tion string for a bundle file. The output of this command can be
7994 used verbatim for the value of BUNDLESPEC (it is already
7995 escaped).
7996 Clients will automatically filter out specifications that are
7998 unknown or unsupported so they won't attempt to download some‐
7999 thing that likely won't apply.
8000 The actual value doesn't impact client behavior beyond filter‐
8002 ing: clients will still sniff the bundle type from the header of
8003 downloaded files.
8004 Use of this key is highly recommended, as it allows clients to
8006 easily skip unsupported bundles. If this key is not defined, an
8007 old client may attempt to apply a bundle that it is incapable of
8008 reading.
8009 REQUIRESNI
8011 Whether Server Name Indication (SNI) is required to connect to
8012 the URL. SNI allows servers to use multiple certificates on the
8013 same IP. It is somewhat common in CDNs and other hosting
8014 providers. Older Python versions do not support SNI. Defining
8015 this attribute enables clients with older Python versions to
8016 filter this entry without experiencing an opaque SSL failure at
8017 connection time.
8018 If this is defined, it is important to advertise a non-SNI fall‐
8020 back URL or clients running old Python releases may not be able
8021 to clone with the clonebundles facility.
8022 Value should be "true".
8024 Manifests can contain multiple entries. Assuming metadata is defined,
8026 clients will filter entries from the manifest that they don't support.
8027 The remaining entries are optionally sorted by client preferences
8028 (ui.clonebundleprefers config option). The client then attempts to
8029 fetch the bundle at the first URL in the remaining list.
8030 Errors when downloading a bundle will fail the entire clone operation:
8032 clients do not automatically fall back to a traditional clone. The rea‐
8033 son for this is that if a server is using clone bundles, it is probably
8034 doing so because the feature is necessary to help it scale. In other
8035 words, there is an assumption that clone load will be offloaded to
8036 another service and that the Mercurial server isn't responsible for
8037 serving this clone load. If that other service experiences issues and
8038 clients start mass falling back to the original Mercurial server, the
8039 added clone load could overwhelm the server due to unexpected load and
8040 effectively take it offline. Not having clients automatically fall back
8041 to cloning from the original server mitigates this scenario.
8042 Because there is no automatic Mercurial server fallback on failure of
8044 the bundle hosting service, it is important for server operators to
8045 view the bundle hosting service as an extension of the Mercurial server
8046 in terms of availability and service level agreements: if the bundle
8047 hosting service goes down, so does the ability for clients to clone.
8048 Note: clients will see a message informing them how to bypass the clone
8049 bundles facility when a failure occurs. So server operators should pre‐
8050 pare for some people to follow these instructions when a failure
8051 occurs, thus driving more load to the original Mercurial server when
8052 the bundle hosting service fails.
8053 commitextras
8055 adds a new flag extras to commit (ADVANCED)
8056 convert
8058 import revisions from foreign VCS repositories into Mercurial
8059 Commands
8061 convert
8062 convert a foreign SCM repository to a Mercurial one.:
8063 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
8065 Accepted source formats [identifiers]:
8067 · Mercurial [hg]
8069 · CVS [cvs]
8071 · Darcs [darcs]
8073 · git [git]
8075 · Subversion [svn]
8077 · Monotone [mtn]
8079 · GNU Arch [gnuarch]
8081 · Bazaar [bzr]
8083 · Perforce [p4]
8085 Accepted destination formats [identifiers]:
8087 · Mercurial [hg]
8089 · Subversion [svn] (history on branches is not preserved)
8091 If no revision is given, all revisions will be converted. Otherwise,
8093 convert will only import up to the named revision (given in a format
8094 understood by the source).
8095 If no destination directory name is specified, it defaults to the base‐
8097 name of the source with -hg appended. If the destination repository
8098 doesn't exist, it will be created.
8099 By default, all sources except Mercurial will use --branchsort. Mercu‐
8101 rial uses --sourcesort to preserve original revision numbers order.
8102 Sort modes have the following effects:
8103 --branchsort
8105 convert from parent to child revision when possible, which means
8106 branches are usually converted one after the other. It generates
8107 more compact repositories.
8108 --datesort
8110 sort revisions by date. Converted repositories have good-looking
8111 changelogs but are often an order of magnitude larger than the
8112 same ones generated by --branchsort.
8113 --sourcesort
8115 try to preserve source revisions order, only supported by Mercu‐
8116 rial sources.
8117 --closesort
8119 try to move closed revisions as close as possible to parent
8120 branches, only supported by Mercurial sources.
8121 If REVMAP isn't given, it will be put in a default location
8123 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
8124 maps each source commit ID to the destination ID for that revision,
8125 like so:
8126 <source ID> <destination ID>
8128 If the file doesn't exist, it's automatically created. It's updated on
8130 each commit copied, so hg convert can be interrupted and can be run
8131 repeatedly to copy new commits.
8132 The authormap is a simple text file that maps each source commit author
8134 to a destination commit author. It is handy for source SCMs that use
8135 unix logins to identify authors (e.g.: CVS). One line per author map‐
8136 ping and the line format is:
8137 source author = destination author
8139 Empty lines and lines starting with a # are ignored.
8141 The filemap is a file that allows filtering and remapping of files and
8143 directories. Each line can contain one of the following directives:
8144 include path/to/file-or-dir
8146 exclude path/to/file-or-dir
8148 rename path/to/source path/to/destination
8150 Comment lines start with #. A specified path matches if it equals the
8152 full relative name of a file or one of its parent directories. The
8153 include or exclude directive with the longest matching path applies, so
8154 line order does not matter.
8155 The include directive causes a file, or all files under a directory, to
8157 be included in the destination repository. The default if there are no
8158 include statements is to include everything. If there are any include
8159 statements, nothing else is included. The exclude directive causes
8160 files or directories to be omitted. The rename directive renames a file
8161 or directory if it is converted. To rename from a subdirectory into the
8162 root of the repository, use . as the path to rename to.
8163 --full will make sure the converted changesets contain exactly the
8165 right files with the right content. It will make a full conversion of
8166 all files, not just the ones that have changed. Files that already are
8167 correct will not be changed. This can be used to apply filemap changes
8168 when converting incrementally. This is currently only supported for
8169 Mercurial and Subversion.
8170 The splicemap is a file that allows insertion of synthetic history,
8172 letting you specify the parents of a revision. This is useful if you
8173 want to e.g. give a Subversion merge two parents, or graft two discon‐
8174 nected series of history together. Each entry contains a key, followed
8175 by a space, followed by one or two comma-separated values:
8176 key parent1, parent2
8178 The key is the revision ID in the source revision control system whose
8180 parents should be modified (same format as a key in .hg/shamap). The
8181 values are the revision IDs (in either the source or destination revi‐
8182 sion control system) that should be used as the new parents for that
8183 node. For example, if you have merged "release-1.0" into "trunk", then
8184 you should specify the revision on "trunk" as the first parent and the
8185 one on the "release-1.0" branch as the second.
8186 The branchmap is a file that allows you to rename a branch when it is
8188 being brought in from whatever external repository. When used in con‐
8189 junction with a splicemap, it allows for a powerful combination to help
8190 fix even the most badly mismanaged repositories and turn them into
8191 nicely structured Mercurial repositories. The branchmap contains lines
8192 of the form:
8193 original_branch_name new_branch_name
8195 where "original_branch_name" is the name of the branch in the source
8197 repository, and "new_branch_name" is the name of the branch is the des‐
8198 tination repository. No whitespace is allowed in the new branch name.
8199 This can be used to (for instance) move code in one repository from
8200 "default" to a named branch.
8201 Mercurial Source
8203 The Mercurial source recognizes the following configuration options,
8204 which you can set on the command line with --config:
8205 convert.hg.ignoreerrors
8207 ignore integrity errors when reading. Use it to fix Mercurial
8208 repositories with missing revlogs, by converting from and to
8209 Mercurial. Default is False.
8210 convert.hg.saverev
8212 store original revision ID in changeset (forces target IDs to
8213 change). It takes a boolean argument and defaults to False.
8214 convert.hg.startrev
8216 specify the initial Mercurial revision. The default is 0.
8217 convert.hg.revs
8219 revset specifying the source revisions to convert.
8220 CVS Source
8222 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to
8223 indicate the starting point of what will be converted. Direct access to
8224 the repository files is not needed, unless of course the repository is
8225 :local:. The conversion uses the top level directory in the sandbox to
8226 find the CVS repository, and then uses CVS rlog commands to find files
8227 to convert. This means that unless a filemap is given, all files under
8228 the starting directory will be converted, and that any directory reor‐
8229 ganization in the CVS sandbox is ignored.
8230 The following options can be used with --config:
8232 convert.cvsps.cache
8234 Set to False to disable remote log caching, for testing and
8235 debugging purposes. Default is True.
8236 convert.cvsps.fuzz
8238 Specify the maximum time (in seconds) that is allowed between
8239 commits with identical user and log message in a single change‐
8240 set. When very large files were checked in as part of a change‐
8241 set then the default may not be long enough. The default is 60.
8242 convert.cvsps.logencoding
8244 Specify encoding name to be used for transcoding CVS log mes‐
8245 sages. Multiple encoding names can be specified as a list (see
8246 hg help config.Syntax), but only the first acceptable encoding
8247 in the list is used per CVS log entries. This transcoding is
8248 executed before cvslog hook below.
8249 convert.cvsps.mergeto
8251 Specify a regular expression to which commit log messages are
8252 matched. If a match occurs, then the conversion process will
8253 insert a dummy revision merging the branch on which this log
8254 message occurs to the branch indicated in the regex. Default is
8255 {{mergetobranch ([-\w]+)}}
8256 convert.cvsps.mergefrom
8258 Specify a regular expression to which commit log messages are
8259 matched. If a match occurs, then the conversion process will add
8260 the most recent revision on the branch indicated in the regex as
8261 the second parent of the changeset. Default is {{mergefrombranch
8262 ([-\w]+)}}
8263 convert.localtimezone
8265 use local time (as determined by the TZ environment variable)
8266 for changeset date/times. The default is False (use UTC).
8267 hooks.cvslog
8269 Specify a Python function to be called at the end of gathering
8270 the CVS log. The function is passed a list with the log entries,
8271 and can modify the entries in-place, or add or delete them.
8272 hooks.cvschangesets
8274 Specify a Python function to be called after the changesets are
8275 calculated from the CVS log. The function is passed a list with
8276 the changeset entries, and can modify the changesets in-place,
8277 or add or delete them.
8278 An additional "debugcvsps" Mercurial command allows the builtin change‐
8280 set merging code to be run without doing a conversion. Its parameters
8281 and output are similar to that of cvsps 2.1. Please see the command
8282 help for more details.
8283 Subversion Source
8285 Subversion source detects classical trunk/branches/tags layouts. By
8286 default, the supplied svn://repo/path/ source URL is converted as a
8287 single branch. If svn://repo/path/trunk exists it replaces the default
8288 branch. If svn://repo/path/branches exists, its subdirectories are
8289 listed as possible branches. If svn://repo/path/tags exists, it is
8290 looked for tags referencing converted branches. Default trunk, branches
8291 and tags values can be overridden with following options. Set them to
8292 paths relative to the source URL, or leave them blank to disable auto
8293 detection.
8294 The following options can be set with --config:
8296 convert.svn.branches
8298 specify the directory containing branches. The default is
8299 branches.
8300 convert.svn.tags
8302 specify the directory containing tags. The default is tags.
8303 convert.svn.trunk
8305 specify the name of the trunk branch. The default is trunk.
8306 convert.localtimezone
8308 use local time (as determined by the TZ environment variable)
8309 for changeset date/times. The default is False (use UTC).
8310 Source history can be retrieved starting at a specific revision,
8312 instead of being integrally converted. Only single branch conversions
8313 are supported.
8314 convert.svn.startrev
8316 specify start Subversion revision number. The default is 0.
8317 Git Source
8319 The Git importer converts commits from all reachable branches (refs in
8320 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
8321 are converted to bookmarks with the same name, with the leading
8322 'refs/heads' stripped. Git submodules are converted to Git subrepos in
8323 Mercurial.
8324 The following options can be set with --config:
8326 convert.git.similarity
8328 specify how similar files modified in a commit must be to be
8329 imported as renames or copies, as a percentage between 0 (dis‐
8330 abled) and 100 (files must be identical). For example, 90 means
8331 that a delete/add pair will be imported as a rename if more than
8332 90% of the file hasn't changed. The default is 50.
8333 convert.git.findcopiesharder
8335 while detecting copies, look at all files in the working copy
8336 instead of just changed ones. This is very expensive for large
8337 projects, and is only effective when convert.git.similarity is
8338 greater than 0. The default is False.
8339 convert.git.renamelimit
8341 perform rename and copy detection up to this many changed files
8342 in a commit. Increasing this will make rename and copy detection
8343 more accurate but will significantly slow down computation on
8344 large projects. The option is only relevant if convert.git.simi‐
8345 larity is greater than 0. The default is 400.
8346 convert.git.committeractions
8348 list of actions to take when processing author and committer
8349 values.
8350 Git commits have separate author (who wrote the commit) and com‐
8352 mitter (who applied the commit) fields. Not all destinations
8353 support separate author and committer fields (including Mercu‐
8354 rial). This config option controls what to do with these author
8355 and committer fields during conversion.
8356 A value of messagedifferent will append a committer: ... line
8358 to the commit message if the Git committer is different from the
8359 author. The prefix of that line can be specified using the syn‐
8360 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
8361 ter:. When a prefix is specified, a space will always be
8362 inserted between the prefix and the value.
8363 messagealways behaves like messagedifferent except it will
8365 always result in a committer: ... line being appended to the
8366 commit message. This value is mutually exclusive with messaged‐
8367 ifferent.
8368 dropcommitter will remove references to the committer. Only ref‐
8370 erences to the author will remain. Actions that add references
8371 to the committer will have no effect when this is set.
8372 replaceauthor will replace the value of the author field with
8374 the committer. Other actions that add references to the commit‐
8375 ter will still take effect when this is set.
8376 The default is messagedifferent.
8378 convert.git.extrakeys
8380 list of extra keys from commit metadata to copy to the destina‐
8381 tion. Some Git repositories store extra metadata in commits. By
8382 default, this non-default metadata will be lost during conver‐
8383 sion. Setting this config option can retain that metadata. Some
8384 built-in keys such as parent and branch are not allowed to be
8385 copied.
8386 convert.git.remoteprefix
8388 remote refs are converted as bookmarks with con‐
8389 vert.git.remoteprefix as a prefix followed by a /. The default
8390 is 'remote'.
8391 convert.git.saverev
8393 whether to store the original Git commit ID in the metadata of
8394 the destination commit. The default is True.
8395 convert.git.skipsubmodules
8397 does not convert root level .gitmodules files or files with
8398 160000 mode indicating a submodule. Default is False.
8399 Perforce Source
8401 The Perforce (P4) importer can be given a p4 depot path or a client
8402 specification as source. It will convert all files in the source to a
8403 flat Mercurial repository, ignoring labels, branches and integrations.
8404 Note that when a depot path is given you then usually should specify a
8405 target directory, because otherwise the target may be named ...-hg.
8406 The following options can be set with --config:
8408 convert.p4.encoding
8410 specify the encoding to use when decoding standard output of the
8411 Perforce command line tool. The default is default system encod‐
8412 ing.
8413 convert.p4.startrev
8415 specify initial Perforce revision (a Perforce changelist num‐
8416 ber).
8417 Mercurial Destination
8419 The Mercurial destination will recognize Mercurial subrepositories in
8420 the destination directory, and update the .hgsubstate file automati‐
8421 cally if the destination subrepositories contain the
8422 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
8423 tories requires converting a single repository at a time, from the bot‐
8424 tom up.
8425 An example showing how to convert a repository with subrepositories:
8427 # so convert knows the type when it sees a non empty destination
8429 $ hg init converted
8430 $ hg convert orig/sub1 converted/sub1
8432 $ hg convert orig/sub2 converted/sub2
8433 $ hg convert orig converted
8434 The following options are supported:
8436 convert.hg.clonebranches
8438 dispatch source branches in separate clones. The default is
8439 False.
8440 convert.hg.tagsbranch
8442 branch name for tag revisions, defaults to default.
8443 convert.hg.usebranchnames
8445 preserve branch names. The default is True.
8446 convert.hg.sourcename
8448 records the given string as a 'convert_source' extra value on
8449 each commit made in the target repository. The default is None.
8450 All Destinations
8452 All destination types accept the following options:
8453 convert.skiptags
8455 does not convert tags from the source repo to the target repo.
8456 The default is False.
8457 Options:
8459 --authors <FILE>
8461 username mapping filename (DEPRECATED) (use --authormap instead)
8462 -s,--source-type <TYPE>
8464 source repository type
8465 -d,--dest-type <TYPE>
8467 destination repository type
8468 -r,--rev <REV[+]>
8470 import up to source revision REV
8471 -A,--authormap <FILE>
8473 remap usernames using this file
8474 --filemap <FILE>
8476 remap file names using contents of file
8477 --full apply filemap changes by converting all files again
8479 --splicemap <FILE>
8481 splice synthesized history into place
8482 --branchmap <FILE>
8484 change branch names while converting
8485 --branchsort
8487 try to sort changesets by branches
8488 --datesort
8490 try to sort changesets by date
8491 --sourcesort
8493 preserve source changesets order
8494 --closesort
8496 try to reorder closed revisions
8497 [+] marked option can be specified multiple times
8499 eol
8501 automatically manage newlines in repository files
8502 This extension allows you to manage the type of line endings (CRLF or
8504 LF) that are used in the repository and in the local working directory.
8505 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
8506 thereby letting everybody use their OS native line endings.
8507 The extension reads its configuration from a versioned .hgeol configu‐
8509 ration file found in the root of the working directory. The .hgeol file
8510 use the same syntax as all other Mercurial configuration files. It uses
8511 two sections, [patterns] and [repository].
8512 The [patterns] section specifies how line endings should be converted
8514 between the working directory and the repository. The format is speci‐
8515 fied by a file pattern. The first match is used, so put more specific
8516 patterns first. The available line endings are LF, CRLF, and BIN.
8517 Files with the declared format of CRLF or LF are always checked out and
8519 stored in the repository in that format and files declared to be binary
8520 (BIN) are left unchanged. Additionally, native is an alias for checking
8521 out in the platform's default line ending: LF on Unix (including Mac OS
8522 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
8523 Mercurial's default behavior; it is only needed if you need to override
8524 a later, more general pattern.
8525 The optional [repository] section specifies the line endings to use for
8527 files stored in the repository. It has a single setting, native, which
8528 determines the storage line endings for files declared as native in the
8529 [patterns] section. It can be set to LF or CRLF. The default is LF. For
8530 example, this means that on Windows, files configured as native (CRLF
8531 by default) will be converted to LF when stored in the repository.
8532 Files declared as LF, CRLF, or BIN in the [patterns] section are always
8533 stored as-is in the repository.
8534 Example versioned .hgeol file:
8536 [patterns]
8538 **.py = native
8539 **.vcproj = CRLF
8540 **.txt = native
8541 Makefile = LF
8542 **.jpg = BIN
8543 [repository]
8545 native = LF
8546 Note The rules will first apply when files are touched in the working
8548 directory, e.g. by updating to null and back to tip to touch all
8549 files.
8550 The extension uses an optional [eol] section read from both the normal
8552 Mercurial configuration files and the .hgeol file, with the latter
8553 overriding the former. You can use that section to control the overall
8554 behavior. There are three settings:
8555 · eol.native (default os.linesep) can be set to LF or CRLF to override
8557 the default interpretation of native for checkout. This can be used
8558 with hg archive on Unix, say, to generate an archive where files have
8559 line endings for Windows.
8560 · eol.only-consistent (default True) can be set to False to make the
8562 extension convert files with inconsistent EOLs. Inconsistent means
8563 that there is both CRLF and LF present in the file. Such files are
8564 normally not touched under the assumption that they have mixed EOLs
8565 on purpose.
8566 · eol.fix-trailing-newline (default False) can be set to True to ensure
8568 that converted files end with a EOL character (either \n or \r\n as
8569 per the configured patterns).
8570 The extension provides cleverencode: and cleverdecode: filters like the
8572 deprecated win32text extension does. This means that you can disable
8573 win32text and enable eol and your filters will still work. You only
8574 need to these filters until you have prepared a .hgeol file.
8575 The win32text.forbid* hooks provided by the win32text extension have
8577 been unified into a single hook named eol.checkheadshook. The hook will
8578 lookup the expected line endings from the .hgeol file, which means you
8579 must migrate to a .hgeol file first before using the hook. eol.check‐
8580 headshook only checks heads, intermediate invalid revisions will be
8581 pushed. To forbid them completely, use the eol.checkallhook hook. These
8582 hooks are best used as pretxnchangegroup hooks.
8583 See hg help patterns for more information about the glob patterns used.
8585 extdiff
8587 command to allow external programs to compare revisions
8588 The extdiff Mercurial extension allows you to use external programs to
8590 compare revisions, or revision with working directory. The external
8591 diff programs are called with a configurable set of options and two
8592 non-option arguments: paths to directories containing snapshots of
8593 files to compare.
8594 The extdiff extension also allows you to configure new diff commands,
8596 so you do not need to type hg extdiff -p kdiff3 always.
8597 [extdiff]
8599 # add new command that runs GNU diff(1) in 'context diff' mode
8600 cdiff = gdiff -Nprc5
8601 ## or the old way:
8602 #cmd.cdiff = gdiff
8603 #opts.cdiff = -Nprc5
8604 # add new command called meld, runs meld (no need to name twice). If
8606 # the meld executable is not available, the meld tool in [merge-tools]
8607 # will be used, if available
8608 meld =
8609 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
8611 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
8612 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
8613 # your .vimrc
8614 vimdiff = gvim -f "+next" \
8615 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
8616 Tool arguments can include variables that are expanded at runtime:
8618 $parent1, $plabel1 - filename, descriptive label of first parent
8620 $child, $clabel - filename, descriptive label of child revision
8621 $parent2, $plabel2 - filename, descriptive label of second parent
8622 $root - repository root
8623 $parent is an alias for $parent1.
8624 The extdiff extension will look in your [diff-tools] and [merge-tools]
8626 sections for diff tool arguments, when none are specified in [extdiff].
8627 [extdiff]
8629 kdiff3 =
8630 [diff-tools]
8632 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
8633 You can use -I/-X and list of file or directory names like normal hg
8635 diff command. The extdiff extension makes snapshots of only needed
8636 files, so running the external diff program will actually be pretty
8637 fast (at least faster than having to compare the entire tree).
8638 Commands
8640 extdiff
8641 use external program to diff repository (or selected files):
8642 hg extdiff [OPT]... [FILE]...
8644 Show differences between revisions for the specified files, using an
8646 external program. The default program used is diff, with default
8647 options "-Npru".
8648 To select a different program, use the -p/--program option. The program
8650 will be passed the names of two directories to compare. To pass addi‐
8651 tional options to the program, use -o/--option. These will be passed
8652 before the names of the directories to compare.
8653 When two revision arguments are given, then changes are shown between
8655 those revisions. If only one revision is specified then that revision
8656 is compared to the working directory, and, when no revisions are speci‐
8657 fied, the working directory files are compared to its parent.
8658 Options:
8660 -p,--program <CMD>
8662 comparison program to run
8663 -o,--option <OPT[+]>
8665 pass option to comparison program
8666 -r,--rev <REV[+]>
8668 revision
8669 -c,--change <REV>
8671 change made by revision
8672 --patch
8674 compare patches for two revisions
8675 -I,--include <PATTERN[+]>
8677 include names matching the given patterns
8678 -X,--exclude <PATTERN[+]>
8680 exclude names matching the given patterns
8681 -S, --subrepos
8683 recurse into subrepositories
8684 [+] marked option can be specified multiple times
8686 factotum
8688 http authentication with factotum
8689 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
8691 platforms to provide authentication information for HTTP access. Con‐
8692 figuration entries specified in the auth section as well as authentica‐
8693 tion information provided in the repository URL are fully supported. If
8694 no prefix is specified, a value of "*" will be assumed.
8695 By default, keys are specified as:
8697 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
8699 If the factotum extension is unable to read the required key, one will
8701 be requested interactively.
8702 A configuration section is available to customize runtime behavior. By
8704 default, these entries are:
8705 [factotum]
8707 executable = /bin/auth/factotum
8708 mountpoint = /mnt/factotum
8709 service = hg
8710 The executable entry defines the full path to the factotum binary. The
8712 mountpoint entry defines the path to the factotum file service. Lastly,
8713 the service entry controls the service name used when reading keys.
8714 fetch
8716 pull, update and merge in one command (DEPRECATED)
8717 Commands
8719 fetch
8720 pull changes from a remote repository, merge new changes if needed.:
8721 hg fetch [SOURCE]
8723 This finds all changes from the repository at the specified path or URL
8725 and adds them to the local repository.
8726 If the pulled changes add a new branch head, the head is automatically
8728 merged, and the result of the merge is committed. Otherwise, the work‐
8729 ing directory is updated to include the new changes.
8730 When a merge is needed, the working directory is first updated to the
8732 newly pulled changes. Local changes are then merged into the pulled
8733 changes. To switch the merge order, use --switch-parent.
8734 See hg help dates for a list of formats valid for -d/--date.
8736 Returns 0 on success.
8738 Options:
8740 -r,--rev <REV[+]>
8742 a specific revision you would like to pull
8743 --edit invoke editor on commit messages
8745 --force-editor
8747 edit commit message (DEPRECATED)
8748 --switch-parent
8750 switch parents when merging
8751 -m,--message <TEXT>
8753 use text as commit message
8754 -l,--logfile <FILE>
8756 read commit message from file
8757 -d,--date <DATE>
8759 record the specified date as commit date
8760 -u,--user <USER>
8762 record the specified user as committer
8763 -e,--ssh <CMD>
8765 specify ssh command to use
8766 --remotecmd <CMD>
8768 specify hg command to run on the remote side
8769 --insecure
8771 do not verify server certificate (ignoring web.cacerts config)
8772 [+] marked option can be specified multiple times
8774 fsmonitor
8776 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
8777 Integrates the file-watching program Watchman with Mercurial to produce
8779 faster status results.
8780 On a particular Linux system, for a real-world repository with over
8782 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
8783 the same system, with fsmonitor it takes about 0.3 seconds.
8784 fsmonitor requires no configuration -- it will tell Watchman about your
8786 repository as necessary. You'll need to install Watchman from
8787 https://facebook.github.io/watchman/ and make sure it is in your PATH.
8788 fsmonitor is incompatible with the largefiles and eol extensions, and
8790 will disable itself if any of those are active.
8791 The following configuration options exist:
8793 [fsmonitor]
8795 mode = {off, on, paranoid}
8796 When mode = off, fsmonitor will disable itself (similar to not loading
8798 the extension at all). When mode = on, fsmonitor will be enabled (the
8799 default). When mode = paranoid, fsmonitor will query both Watchman and
8800 the filesystem, and ensure that the results are consistent.
8801 [fsmonitor]
8803 timeout = (float)
8804 A value, in seconds, that determines how long fsmonitor will wait for
8806 Watchman to return results. Defaults to 2.0.
8807 [fsmonitor]
8809 blacklistusers = (list of userids)
8810 A list of usernames for which fsmonitor will disable itself altogether.
8812 [fsmonitor]
8814 walk_on_invalidate = (boolean)
8815 Whether or not to walk the whole repo ourselves when our cached state
8817 has been invalidated, for example when Watchman has been restarted or
8818 .hgignore rules have been changed. Walking the repo in that case can
8819 result in competing for I/O with Watchman. For large repos it is recom‐
8820 mended to set this value to false. You may wish to set this to true if
8821 you have a very fast filesystem that can outpace the IPC overhead of
8822 getting the result data for the full repo from Watchman. Defaults to
8823 false.
8824 [fsmonitor]
8826 warn_when_unused = (boolean)
8827 Whether to print a warning during certain operations when fsmonitor
8829 would be beneficial to performance but isn't enabled.
8830 [fsmonitor]
8832 warn_update_file_count = (integer)
8833 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
8835 be printed during working directory updates if this many files will be
8836 created.
8837 githelp
8839 try mapping git commands to Mercurial commands
8840 Tries to map a given git command to a Mercurial command:
8842 $ hg githelp -- git checkout master hg update master
8844 If an unknown command or parameter combination is detected, an error is
8846 produced.
8847 Commands
8849 githelp
8850 suggests the Mercurial equivalent of the given git command:
8851 hg githelp
8853 Usage: hg githelp -- <git command>
8855 aliases: git
8857 gpg
8859 commands to sign and verify changesets
8860 Commands
8862 sigcheck
8863 verify all the signatures there may be for a particular revision:
8864 hg sigcheck REV
8866 verify all the signatures there may be for a particular revision
8868 sign
8870 add a signature for the current or given revision:
8871 hg sign [OPTION]... [REV]...
8873 If no revision is given, the parent of the working directory is used,
8875 or tip if no revision is checked out.
8876 The gpg.cmd config setting can be used to specify the command to run. A
8878 default key can be specified with gpg.key.
8879 See hg help dates for a list of formats valid for -d/--date.
8881 Options:
8883 -l, --local
8885 make the signature local
8886 -f, --force
8888 sign even if the sigfile is modified
8889 --no-commit
8891 do not commit the sigfile after signing
8892 -k,--key <ID>
8894 the key id to sign with
8895 -m,--message <TEXT>
8897 use text as commit message
8898 -e, --edit
8900 invoke editor on commit messages
8901 -d,--date <DATE>
8903 record the specified date as commit date
8904 -u,--user <USER>
8906 record the specified user as committer
8907 sigs
8909 list signed changesets:
8910 hg sigs
8912 list signed changesets
8914 graphlog
8916 command to view revision graphs from a shell (DEPRECATED)
8917 The functionality of this extension has been include in core Mercurial
8919 since version 2.3. Please use hg log -G ... instead.
8920 This extension adds a --graph option to the incoming, outgoing and log
8922 commands. When this options is given, an ASCII representation of the
8923 revision graph is also shown.
8924 Commands
8926 glog
8927 show revision history alongside an ASCII revision graph:
8928 hg glog [OPTION]... [FILE]
8930 Print a revision history alongside a revision graph drawn with ASCII
8932 characters.
8933 Nodes printed as an @ character are parents of the working directory.
8935 This is an alias to hg log -G.
8937 Options:
8939 -f, --follow
8941 follow changeset history, or file history across copies and
8942 renames
8943 --follow-first
8945 only follow the first parent of merge changesets (DEPRECATED)
8946 -d,--date <DATE>
8948 show revisions matching date spec
8949 -C, --copies
8951 show copied files
8952 -k,--keyword <TEXT[+]>
8954 do case-insensitive search for a given text
8955 -r,--rev <REV[+]>
8957 show the specified revision or revset
8958 --removed
8960 include revisions where files were removed
8961 -m, --only-merges
8963 show only merges (DEPRECATED)
8964 -u,--user <USER[+]>
8966 revisions committed by user
8967 --only-branch <BRANCH[+]>
8969 show only changesets within the given named branch (DEPRECATED)
8970 -b,--branch <BRANCH[+]>
8972 show changesets within the given named branch
8973 -P,--prune <REV[+]>
8975 do not display revision or any of its ancestors
8976 -p, --patch
8978 show patch
8979 -g, --git
8981 use git extended diff format
8982 -l,--limit <NUM>
8984 limit number of changes displayed
8985 -M, --no-merges
8987 do not show merges
8988 --stat output diffstat-style summary of changes
8990 -G, --graph
8992 show the revision DAG
8993 --style <STYLE>
8995 display using template map file (DEPRECATED)
8996 -T,--template <TEMPLATE>
8998 display with template
8999 -I,--include <PATTERN[+]>
9001 include names matching the given patterns
9002 -X,--exclude <PATTERN[+]>
9004 exclude names matching the given patterns
9005 [+] marked option can be specified multiple times
9007 hgk
9009 browse the repository in a graphical way
9010 The hgk extension allows browsing the history of a repository in a
9012 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
9013 distributed with Mercurial.)
9014 hgk consists of two parts: a Tcl script that does the displaying and
9016 querying of information, and an extension to Mercurial named hgk.py,
9017 which provides hooks for hgk to get information. hgk can be found in
9018 the contrib directory, and the extension is shipped in the hgext repos‐
9019 itory, and needs to be enabled.
9020 The hg view command will launch the hgk Tcl script. For this command to
9022 work, hgk must be in your search path. Alternately, you can specify the
9023 path to hgk in your configuration file:
9024 [hgk]
9026 path = /location/of/hgk
9027 hgk can make use of the extdiff extension to visualize revisions.
9029 Assuming you had already configured extdiff vdiff command, just add:
9030 [hgk]
9032 vdiff=vdiff
9033 Revisions context menu will now display additional entries to fire
9035 vdiff on hovered and selected revisions.
9036 Commands
9038 view
9039 start interactive history viewer:
9040 hg view [-l LIMIT] [REVRANGE]
9042 start interactive history viewer
9044 Options:
9046 -l,--limit <NUM>
9048 limit number of changes displayed
9049 highlight
9051 syntax highlighting for hgweb (requires Pygments)
9052 It depends on the Pygments syntax highlighting library:
9054 http://pygments.org/
9055 There are the following configuration options:
9057 [web]
9059 pygments_style = <style> (default: colorful)
9060 highlightfiles = <fileset> (default: size('<5M'))
9061 highlightonlymatchfilename = <bool> (default False)
9062 highlightonlymatchfilename will only highlight files if their type
9064 could be identified by their filename. When this is not enabled (the
9065 default), Pygments will try very hard to identify the file type from
9066 content and any match (even matches with a low confidence score) will
9067 be used.
9068 histedit
9070 interactive history editing
9071 With this extension installed, Mercurial gains one new command: histe‐
9073 dit. Usage is as follows, assuming the following history:
9074 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
9076 | Add delta
9077 |
9078 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
9079 | Add gamma
9080 |
9081 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
9082 | Add beta
9083 |
9084 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
9085 Add alpha
9086 If you were to run hg histedit c561b4e977df, you would see the follow‐
9088 ing file open in your editor:
9089 pick c561b4e977df Add beta
9091 pick 030b686bedc4 Add gamma
9092 pick 7c2fd3b9020c Add delta
9093 # Edit history between c561b4e977df and 7c2fd3b9020c
9095 #
9096 # Commits are listed from least to most recent
9097 #
9098 # Commands:
9099 # p, pick = use commit
9100 # e, edit = use commit, but stop for amending
9101 # f, fold = use commit, but combine it with the one above
9102 # r, roll = like fold, but discard this commit's description and date
9103 # d, drop = remove commit from history
9104 # m, mess = edit commit message without changing commit content
9105 # b, base = checkout changeset and apply further changesets from there
9106 #
9107 In this file, lines beginning with # are ignored. You must specify a
9109 rule for each revision in your history. For example, if you had meant
9110 to add gamma before beta, and then wanted to add delta in the same
9111 revision as beta, you would reorganize the file to look like this:
9112 pick 030b686bedc4 Add gamma
9114 pick c561b4e977df Add beta
9115 fold 7c2fd3b9020c Add delta
9116 # Edit history between c561b4e977df and 7c2fd3b9020c
9118 #
9119 # Commits are listed from least to most recent
9120 #
9121 # Commands:
9122 # p, pick = use commit
9123 # e, edit = use commit, but stop for amending
9124 # f, fold = use commit, but combine it with the one above
9125 # r, roll = like fold, but discard this commit's description and date
9126 # d, drop = remove commit from history
9127 # m, mess = edit commit message without changing commit content
9128 # b, base = checkout changeset and apply further changesets from there
9129 #
9130 At which point you close the editor and histedit starts working. When
9132 you specify a fold operation, histedit will open an editor when it
9133 folds those revisions together, offering you a chance to clean up the
9134 commit message:
9135 Add beta
9137 ***
9138 Add delta
9139 Edit the commit message to your liking, then close the editor. The date
9141 used for the commit will be the later of the two commits' dates. For
9142 this example, let's assume that the commit message was changed to Add
9143 beta and delta. After histedit has run and had a chance to remove any
9144 old or temporary revisions it needed, the history looks like this:
9145 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
9147 | Add beta and delta.
9148 |
9149 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
9150 | Add gamma
9151 |
9152 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
9153 Add alpha
9154 Note that histedit does not remove any revisions (even its own tempo‐
9156 rary ones) until after it has completed all the editing operations, so
9157 it will probably perform several strip operations when it's done. For
9158 the above example, it had to run strip twice. Strip can be slow depend‐
9159 ing on a variety of factors, so you might need to be a little patient.
9160 You can choose to keep the original revisions by passing the --keep
9161 flag.
9162 The edit operation will drop you back to a command prompt, allowing you
9164 to edit files freely, or even use hg record to commit some changes as a
9165 separate commit. When you're done, any remaining uncommitted changes
9166 will be committed as well. When done, run hg histedit --continue to
9167 finish this step. If there are uncommitted changes, you'll be prompted
9168 for a new commit message, but the default commit message will be the
9169 original message for the edit ed revision, and the date of the original
9170 commit will be preserved.
9171 The message operation will give you a chance to revise a commit message
9173 without changing the contents. It's a shortcut for doing edit immedi‐
9174 ately followed by hg histedit --continue`.
9175 If histedit encounters a conflict when moving a revision (while han‐
9177 dling pick or fold), it'll stop in a similar manner to edit with the
9178 difference that it won't prompt you for a commit message when done. If
9179 you decide at this point that you don't like how much work it will be
9180 to rearrange history, or that you made a mistake, you can use hg histe‐
9181 dit --abort to abandon the new changes you have made and return to the
9182 state before you attempted to edit your history.
9183 If we clone the histedit-ed example repository above and add four more
9185 changes, such that we have the following history:
9186 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
9188 | Add theta
9189 |
9190 o 5 140988835471 2009-04-27 18:04 -0500 stefan
9191 | Add eta
9192 |
9193 o 4 122930637314 2009-04-27 18:04 -0500 stefan
9194 | Add zeta
9195 |
9196 o 3 836302820282 2009-04-27 18:04 -0500 stefan
9197 | Add epsilon
9198 |
9199 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
9200 | Add beta and delta.
9201 |
9202 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
9203 | Add gamma
9204 |
9205 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
9206 Add alpha
9207 If you run hg histedit --outgoing on the clone then it is the same as
9209 running hg histedit 836302820282. If you need plan to push to a reposi‐
9210 tory that Mercurial does not detect to be related to the source repo,
9211 you can add a --force option.
9212 Config
9214 Histedit rule lines are truncated to 80 characters by default. You can
9215 customize this behavior by setting a different length in your configu‐
9216 ration file:
9217 [histedit]
9219 linelen = 120 # truncate rule lines at 120 characters
9220 hg histedit attempts to automatically choose an appropriate base revi‐
9222 sion to use. To change which base revision is used, define a revset in
9223 your configuration file:
9224 [histedit]
9226 defaultrev = only(.) & draft()
9227 By default each edited revision needs to be present in histedit com‐
9229 mands. To remove revision you need to use drop operation. You can con‐
9230 figure the drop to be implicit for missing commits by adding:
9231 [histedit]
9233 dropmissing = True
9234 By default, histedit will close the transaction after each action. For
9236 performance purposes, you can configure histedit to use a single trans‐
9237 action across the entire histedit. WARNING: This setting introduces a
9238 significant risk of losing the work you've done in a histedit if the
9239 histedit aborts unexpectedly:
9240 [histedit]
9242 singletransaction = True
9243 Commands
9245 histedit
9246 interactively edit changeset history:
9247 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
9249 This command lets you edit a linear series of changesets (up to and
9251 including the working directory, which should be clean). You can:
9252 · pick to [re]order a changeset
9254 · drop to omit changeset
9256 · mess to reword the changeset commit message
9258 · fold to combine it with the preceding changeset (using the later
9260 date)
9261 · roll like fold, but discarding this commit's description and date
9263 · edit to edit this changeset (preserving date)
9265 · base to checkout changeset and apply further changesets from there
9267 There are a number of ways to select the root changeset:
9269 · Specify ANCESTOR directly
9271 · Use --outgoing -- it will be the first linear changeset not included
9273 in destination. (See hg help config.paths.default-push)
9274 · Otherwise, the value from the "histedit.defaultrev" config option is
9276 used as a revset to select the base revision when ANCESTOR is not
9277 specified. The first revision returned by the revset is used. By
9278 default, this selects the editable history that is unique to the
9279 ancestry of the working directory.
9280 If you use --outgoing, this command will abort if there are ambiguous
9282 outgoing revisions. For example, if there are multiple branches con‐
9283 taining outgoing revisions.
9284 Use "min(outgoing() and ::.)" or similar revset specification instead
9286 of --outgoing to specify edit target revision exactly in such ambiguous
9287 situation. See hg help revsets for detail about selecting revisions.
9288 Examples:
9290 · A number of changes have been made. Revision 3 is no longer
9292 needed.
9293 Start history editing from revision 3:
9295 hg histedit -r 3
9297 An editor opens, containing the list of revisions, with specific
9299 actions specified:
9300 pick 5339bf82f0ca 3 Zworgle the foobar
9302 pick 8ef592ce7cc4 4 Bedazzle the zerlog
9303 pick 0a9639fcda9d 5 Morgify the cromulancy
9304 Additional information about the possible actions to take appears
9306 below the list of revisions.
9307 To remove revision 3 from the history, its action (at the begin‐
9309 ning of the relevant line) is changed to 'drop':
9310 drop 5339bf82f0ca 3 Zworgle the foobar
9312 pick 8ef592ce7cc4 4 Bedazzle the zerlog
9313 pick 0a9639fcda9d 5 Morgify the cromulancy
9314 · A number of changes have been made. Revision 2 and 4 need to be
9316 swapped.
9317 Start history editing from revision 2:
9319 hg histedit -r 2
9321 An editor opens, containing the list of revisions, with specific
9323 actions specified:
9324 pick 252a1af424ad 2 Blorb a morgwazzle
9326 pick 5339bf82f0ca 3 Zworgle the foobar
9327 pick 8ef592ce7cc4 4 Bedazzle the zerlog
9328 To swap revision 2 and 4, its lines are swapped in the editor:
9330 pick 8ef592ce7cc4 4 Bedazzle the zerlog
9332 pick 5339bf82f0ca 3 Zworgle the foobar
9333 pick 252a1af424ad 2 Blorb a morgwazzle
9334 Returns 0 on success, 1 if user intervention is required (not only for
9336 intentional "edit" command, but also for resolving unexpected con‐
9337 flicts).
9338 Options:
9340 --commands <FILE>
9342 read history edits from the specified file
9343 -c, --continue
9345 continue an edit already in progress
9346 --edit-plan
9348 edit remaining actions list
9349 -k, --keep
9351 don't strip old nodes after edit is complete
9352 --abort
9354 abort an edit in progress
9355 -o, --outgoing
9357 changesets not found in destination
9358 -f, --force
9360 force outgoing even for unrelated repositories
9361 -r,--rev <REV[+]>
9363 first revision to be edited
9364 -T,--template <TEMPLATE>
9366 display with template (EXPERIMENTAL)
9367 [+] marked option can be specified multiple times
9369 journal
9371 track previous positions of bookmarks (EXPERIMENTAL)
9372 This extension adds a new command: hg journal, which shows you where
9374 bookmarks were previously located.
9375 Commands
9377 journal
9378 show the previous position of bookmarks and the working copy:
9379 hg journal [OPTION]... [BOOKMARKNAME]
9381 The journal is used to see the previous commits that bookmarks and the
9383 working copy pointed to. By default the previous locations for the
9384 working copy. Passing a bookmark name will show all the previous posi‐
9385 tions of that bookmark. Use the --all switch to show previous locations
9386 for all bookmarks and the working copy; each line will then include the
9387 bookmark name, or '.' for the working copy, as well.
9388 If name starts with re:, the remainder of the name is treated as a reg‐
9390 ular expression. To match a name that actually starts with re:, use the
9391 prefix literal:.
9392 By default hg journal only shows the commit hash and the command that
9394 was running at that time. -v/--verbose will show the prior hash, the
9395 user, and the time at which it happened.
9396 Use -c/--commits to output log information on each commit hash; at this
9398 point you can use the usual --patch, --git, --stat and --template
9399 switches to alter the log output for these.
9400 hg journal -T json can be used to produce machine readable output.
9402 Options:
9404 --all show history for all names
9406 -c, --commits
9408 show commit metadata
9409 -p, --patch
9411 show patch
9412 -g, --git
9414 use git extended diff format
9415 -l,--limit <NUM>
9417 limit number of changes displayed
9418 --stat output diffstat-style summary of changes
9420 --style <STYLE>
9422 display using template map file (DEPRECATED)
9423 -T,--template <TEMPLATE>
9425 display with template
9426 keyword
9428 expand keywords in tracked files
9429 This extension expands RCS/CVS-like or self-customized $Keywords$ in
9431 tracked text files selected by your configuration.
9432 Keywords are only expanded in local repositories and not stored in the
9434 change history. The mechanism can be regarded as a convenience for the
9435 current user or for archive distribution.
9436 Keywords expand to the changeset data pertaining to the latest change
9438 relative to the working directory parent of each file.
9439 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
9441 sections of hgrc files.
9442 Example:
9444 [keyword]
9446 # expand keywords in every python file except those matching "x*"
9447 **.py =
9448 x* = ignore
9449 [keywordset]
9451 # prefer svn- over cvs-like default keywordmaps
9452 svn = True
9453 Note The more specific you are in your filename patterns the less you
9455 lose speed in huge repositories.
9456 For [keywordmaps] template mapping and expansion demonstration and con‐
9458 trol run hg kwdemo. See hg help templates for a list of available tem‐
9459 plates and filters.
9460 Three additional date template filters are provided:
9462 utcdate
9464 "2006/09/18 15:13:13"
9466 svnutcdate
9468 "2006-09-18 15:13:13Z"
9470 svnisodate
9472 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
9474 The default template mappings (view with hg kwdemo -d) can be replaced
9476 with customized keywords and templates. Again, run hg kwdemo to control
9477 the results of your configuration changes.
9478 Before changing/disabling active keywords, you must run hg kwshrink to
9480 avoid storing expanded keywords in the change history.
9481 To force expansion after enabling it, or a configuration change, run hg
9483 kwexpand.
9484 Expansions spanning more than one line and incremental expansions, like
9486 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
9487 expands to the first line of the changeset description.
9488 Commands
9490 kwdemo
9491 print [keywordmaps] configuration and an expansion example:
9492 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
9494 Show current, custom, or default keyword template maps and their expan‐
9496 sions.
9497 Extend the current configuration by specifying maps as arguments and
9499 using -f/--rcfile to source an external hgrc file.
9500 Use -d/--default to disable current configuration.
9502 See hg help templates for information on templates and filters.
9504 Options:
9506 -d, --default
9508 show default keyword template maps
9509 -f,--rcfile <FILE>
9511 read maps from rcfile
9512 kwexpand
9514 expand keywords in the working directory:
9515 hg kwexpand [OPTION]... [FILE]...
9517 Run after (re)enabling keyword expansion.
9519 kwexpand refuses to run if given files contain local changes.
9521 Options:
9523 -I,--include <PATTERN[+]>
9525 include names matching the given patterns
9526 -X,--exclude <PATTERN[+]>
9528 exclude names matching the given patterns
9529 [+] marked option can be specified multiple times
9531 kwfiles
9533 show files configured for keyword expansion:
9534 hg kwfiles [OPTION]... [FILE]...
9536 List which files in the working directory are matched by the [keyword]
9538 configuration patterns.
9539 Useful to prevent inadvertent keyword expansion and to speed up execu‐
9541 tion by including only files that are actual candidates for expansion.
9542 See hg help keyword on how to construct patterns both for inclusion and
9544 exclusion of files.
9545 With -A/--all and -v/--verbose the codes used to show the status of
9547 files are:
9548 K = keyword expansion candidate
9550 k = keyword expansion candidate (not tracked)
9551 I = ignored
9552 i = ignored (not tracked)
9553 Options:
9555 -A, --all
9557 show keyword status flags of all files
9558 -i, --ignore
9560 show files excluded from expansion
9561 -u, --unknown
9563 only show unknown (not tracked) files
9564 -I,--include <PATTERN[+]>
9566 include names matching the given patterns
9567 -X,--exclude <PATTERN[+]>
9569 exclude names matching the given patterns
9570 [+] marked option can be specified multiple times
9572 kwshrink
9574 revert expanded keywords in the working directory:
9575 hg kwshrink [OPTION]... [FILE]...
9577 Must be run before changing/disabling active keywords.
9579 kwshrink refuses to run if given files contain local changes.
9581 Options:
9583 -I,--include <PATTERN[+]>
9585 include names matching the given patterns
9586 -X,--exclude <PATTERN[+]>
9588 exclude names matching the given patterns
9589 [+] marked option can be specified multiple times
9591 largefiles
9593 track large binary files
9594 Large binary files tend to be not very compressible, not very diffable,
9596 and not at all mergeable. Such files are not handled efficiently by
9597 Mercurial's storage format (revlog), which is based on compressed
9598 binary deltas; storing large binary files as regular Mercurial files
9599 wastes bandwidth and disk space and increases Mercurial's memory usage.
9600 The largefiles extension addresses these problems by adding a central‐
9601 ized client-server layer on top of Mercurial: largefiles live in a cen‐
9602 tral store out on the network somewhere, and you only fetch the revi‐
9603 sions that you need when you need them.
9604 largefiles works by maintaining a "standin file" in .hglf/ for each
9606 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
9607 line) and are tracked by Mercurial. Largefile revisions are identified
9608 by the SHA-1 hash of their contents, which is written to the standin.
9609 largefiles uses that revision ID to get/put largefile revisions from/to
9610 the central store. This saves both disk space and bandwidth, since you
9611 don't need to retrieve all historical revisions of large files when you
9612 clone or pull.
9613 To start a new repository or add new large binary files, just add
9615 --large to your hg add command. For example:
9616 $ dd if=/dev/urandom of=randomdata count=2000
9618 $ hg add --large randomdata
9619 $ hg commit -m "add randomdata as a largefile"
9620 When you push a changeset that adds/modifies largefiles to a remote
9622 repository, its largefile revisions will be uploaded along with it.
9623 Note that the remote Mercurial must also have the largefiles extension
9624 enabled for this to work.
9625 When you pull a changeset that affects largefiles from a remote reposi‐
9627 tory, the largefiles for the changeset will by default not be pulled
9628 down. However, when you update to such a revision, any largefiles
9629 needed by that revision are downloaded and cached (if they have never
9630 been downloaded before). One way to pull largefiles when pulling is
9631 thus to use --update, which will update your working copy to the latest
9632 pulled revision (and thereby downloading any new largefiles).
9633 If you want to pull largefiles you don't need for update yet, then you
9635 can use pull with the --lfrev option or the hg lfpull command.
9636 If you know you are pulling from a non-default location and want to
9638 download all the largefiles that correspond to the new changesets at
9639 the same time, then you can pull with --lfrev "pulled()".
9640 If you just want to ensure that you will have the largefiles needed to
9642 merge or rebase with new heads that you are pulling, then you can pull
9643 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
9644 files that are new in the heads you are pulling.
9645 Keep in mind that network access may now be required to update to
9647 changesets that you have not previously updated to. The nature of the
9648 largefiles extension means that updating is no longer guaranteed to be
9649 a local-only operation.
9650 If you already have large files tracked by Mercurial without the large‐
9652 files extension, you will need to convert your repository in order to
9653 benefit from largefiles. This is done with the hg lfconvert command:
9654 $ hg lfconvert --size 10 oldrepo newrepo
9656 In repositories that already have largefiles in them, any new file over
9658 10MB will automatically be added as a largefile. To change this thresh‐
9659 old, set largefiles.minsize in your Mercurial config file to the mini‐
9660 mum size in megabytes to track as a largefile, or use the --lfsize
9661 option to the add command (also in megabytes):
9662 [largefiles]
9664 minsize = 2
9665 $ hg add --lfsize 2
9667 The largefiles.patterns config option allows you to specify a list of
9669 filename patterns (see hg help patterns) that should always be tracked
9670 as largefiles:
9671 [largefiles]
9673 patterns =
9674 *.jpg
9675 re:.*\.(png|bmp)$
9676 library.zip
9677 content/audio/*
9678 Files that match one of these patterns will be added as largefiles
9680 regardless of their size.
9681 The largefiles.minsize and largefiles.patterns config options will be
9683 ignored for any repositories not already containing a largefile. To add
9684 the first largefile to a repository, you must explicitly do so with the
9685 --large flag passed to the hg add command.
9686 Commands
9688 lfconvert
9689 convert a normal repository to a largefiles repository:
9690 hg lfconvert SOURCE DEST [FILE ...]
9692 Convert repository SOURCE to a new repository DEST, identical to SOURCE
9694 except that certain files will be converted as largefiles: specifi‐
9695 cally, any file that matches any PATTERN or whose size is above the
9696 minimum size threshold is converted as a largefile. The size used to
9697 determine whether or not to track a file as a largefile is the size of
9698 the first version of the file. The minimum size can be specified either
9699 with --size or in configuration as largefiles.size.
9700 After running this command you will need to make sure that largefiles
9702 is enabled anywhere you intend to push the new repository.
9703 Use --to-normal to convert largefiles back to normal files; after this,
9705 the DEST repository can be used without largefiles at all.
9706 Options:
9708 -s,--size <SIZE>
9710 minimum size (MB) for files to be converted as largefiles
9711 --to-normal
9713 convert from a largefiles repo to a normal repo
9714 lfpull
9716 pull largefiles for the specified revisions from the specified source:
9717 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
9719 Pull largefiles that are referenced from local changesets but missing
9721 locally, pulling from a remote repository to the local cache.
9722 If SOURCE is omitted, the 'default' path will be used. See hg help
9724 urls for more information.
9725 Some examples:
9727 · pull largefiles for all branch heads:
9729 hg lfpull -r "head() and not closed()"
9731 · pull largefiles on the default branch:
9733 hg lfpull -r "branch(default)"
9735 Options:
9737 -r,--rev <VALUE[+]>
9739 pull largefiles for these revisions
9740 -e,--ssh <CMD>
9742 specify ssh command to use
9743 --remotecmd <CMD>
9745 specify hg command to run on the remote side
9746 --insecure
9748 do not verify server certificate (ignoring web.cacerts config)
9749 [+] marked option can be specified multiple times
9751 lfs
9753 lfs - large file support (EXPERIMENTAL)
9754 This extension allows large files to be tracked outside of the normal
9756 repository storage and stored on a centralized server, similar to the
9757 largefiles extension. The git-lfs protocol is used when communicating
9758 with the server, so existing git infrastructure can be harnessed. Even
9759 though the files are stored outside of the repository, they are still
9760 integrity checked in the same manner as normal files.
9761 The files stored outside of the repository are downloaded on demand,
9763 which reduces the time to clone, and possibly the local disk usage.
9764 This changes fundamental workflows in a DVCS, so careful thought should
9765 be given before deploying it. hg convert can be used to convert LFS
9766 repositories to normal repositories that no longer require this exten‐
9767 sion, and do so without changing the commit hashes. This allows the
9768 extension to be disabled if the centralized workflow becomes burden‐
9769 some. However, the pre and post convert clones will not be able to
9770 communicate with each other unless the extension is enabled on both.
9771 To start a new repository, or to add LFS files to an existing one, just
9773 create an .hglfs file as described below in the root directory of the
9774 repository. Typically, this file should be put under version control,
9775 so that the settings will propagate to other repositories with push and
9776 pull. During any commit, Mercurial will consult this file to determine
9777 if an added or modified file should be stored externally. The type of
9778 storage depends on the characteristics of the file at each commit. A
9779 file that is near a size threshold may switch back and forth between
9780 LFS and normal storage, as needed.
9781 Alternately, both normal repositories and largefile controlled reposi‐
9783 tories can be converted to LFS by using hg convert and the lfs.track
9784 config option described below. The .hglfs file should then be created
9785 and added, to control subsequent LFS selection. The hashes are also
9786 unchanged in this case. The LFS and non-LFS repositories can be dis‐
9787 tinguished because the LFS repository will abort any command if this
9788 extension is disabled.
9789 Committed LFS files are held locally, until the repository is pushed.
9791 Prior to pushing the normal repository data, the LFS files that are
9792 tracked by the outgoing commits are automatically uploaded to the con‐
9793 figured central server. No LFS files are transferred on hg pull or hg
9794 clone. Instead, the files are downloaded on demand as they need to be
9795 read, if a cached copy cannot be found locally. Both committing and
9796 downloading an LFS file will link the file to a usercache, to speed up
9797 future access. See the usercache config setting described below.
9798 The extension reads its configuration from a versioned ``.hglfs``
9801 configuration file found in the root of the working directory. The
9802 ``.hglfs`` file uses the same syntax as all other Mercurial
9803 configuration files. It uses a single section, ``[track]``.
9804 The ``[track]`` section specifies which files are stored as LFS (or
9806 not). Each line is keyed by a file pattern, with a predicate value.
9807 The first file pattern match is used, so put more specific patterns
9808 first. The available predicates are ``all()``, ``none()``, and
9809 ``size()``. See "hg help filesets.size" for the latter.
9810 Example versioned ``.hglfs`` file::
9812 [track]
9814 # No Makefile or python file, anywhere, will be LFS
9815 **Makefile = none()
9816 **.py = none()
9817 **.zip = all()
9819 **.exe = size(">1MB")
9820 # Catchall for everything not matched above
9822 ** = size(">10MB")
9823 Configs:
9825 [lfs]
9827 # Remote endpoint. Multiple protocols are supported:
9828 # - http(s)://user:pass@example.com/path
9829 # git-lfs endpoint
9830 # - file:///tmp/path
9831 # local filesystem, usually for testing
9832 # if unset, lfs will prompt setting this when it must use this value.
9833 # (default: unset)
9834 url = https://example.com/repo.git/info/lfs
9835 # Which files to track in LFS. Path tests are "**.extname" for file
9837 # extensions, and "path:under/some/directory" for path prefix. Both
9838 # are relative to the repository root.
9839 # File size can be tested with the "size()" fileset, and tests can be
9840 # joined with fileset operators. (See "hg help filesets.operators".)
9841 #
9842 # Some examples:
9843 # - all() # everything
9844 # - none() # nothing
9845 # - size(">20MB") # larger than 20MB
9846 # - !**.txt # anything not a *.txt file
9847 # - **.zip | **.tar.gz | **.7z # some types of compressed files
9848 # - path:bin # files under "bin" in the project root
9849 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
9850 # | (path:bin & !path:/bin/README) | size(">1GB")
9851 # (default: none())
9852 #
9853 # This is ignored if there is a tracked '.hglfs' file, and this setting
9854 # will eventually be deprecated and removed.
9855 track = size(">10M")
9856 # how many times to retry before giving up on transferring an object
9858 retry = 5
9859 # the local directory to store lfs files for sharing across local clones.
9861 # If not set, the cache is located in an OS specific cache location.
9862 usercache = /path/to/global/cache
9863 Commands
9865 logtoprocess
9866 send ui.log() data to a subprocess (EXPERIMENTAL)
9867 This extension lets you specify a shell command per ui.log() event,
9869 sending all remaining arguments to as environment variables to that
9870 command.
9871 Each positional argument to the method results in a MSG[N] key in the
9873 environment, starting at 1 (so MSG1, MSG2, etc.). Each keyword argument
9874 is set as a OPT_UPPERCASE_KEY variable (so the key is uppercased, and
9875 prefixed with OPT_). The original event name is passed in the EVENT
9876 environment variable, and the process ID of mercurial is given in
9877 HGPID.
9878 So given a call ui.log('foo', 'bar', 'baz', spam='eggs'), a script con‐
9880 figured for the `foo event can expect an environment with MSG1=bar,
9881 MSG2=baz, and OPT_SPAM=eggs.
9882 Scripts are configured in the [logtoprocess] section, each key an event
9884 name. For example:
9885 [logtoprocess]
9887 commandexception = echo "$MSG2$MSG3" > /var/log/mercurial_exceptions.log
9888 would log the warning message and traceback of any failed command dis‐
9890 patch.
9891 Scripts are run asynchronously as detached daemon processes; mercurial
9893 will not ensure that they exit cleanly.
9894 mq
9896 manage a stack of patches
9897 This extension lets you work with a stack of patches in a Mercurial
9899 repository. It manages two stacks of patches - all known patches, and
9900 applied patches (subset of known patches).
9901 Known patches are represented as patch files in the .hg/patches direc‐
9903 tory. Applied patches are both patch files and changesets.
9904 Common tasks (use hg help COMMAND for more details):
9906 create new patch qnew
9908 import existing patch qimport
9909 print patch series qseries
9911 print applied patches qapplied
9912 add known patch to applied stack qpush
9914 remove patch from applied stack qpop
9915 refresh contents of top applied patch qrefresh
9916 By default, mq will automatically use git patches when required to
9918 avoid losing file mode changes, copy records, binary files or empty
9919 files creations or deletions. This behavior can be configured with:
9920 [mq]
9922 git = auto/keep/yes/no
9923 If set to 'keep', mq will obey the [diff] section configuration while
9925 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
9926 mq will override the [diff] section and always generate git or regular
9927 patches, possibly losing data in the second case.
9928 It may be desirable for mq changesets to be kept in the secret phase
9930 (see hg help phases), which can be enabled with the following setting:
9931 [mq]
9933 secret = True
9934 You will by default be managing a patch queue named "patches". You can
9936 create other, independent patch queues with the hg qqueue command.
9937 If the working directory contains uncommitted files, qpush, qpop and
9939 qgoto abort immediately. If -f/--force is used, the changes are dis‐
9940 carded. Setting:
9941 [mq]
9943 keepchanges = True
9944 make them behave as if --keep-changes were passed, and non-conflicting
9946 local changes will be tolerated and preserved. If incompatible options
9947 such as -f/--force or --exact are passed, this setting is ignored.
9948 This extension used to provide a strip command. This command now lives
9950 in the strip extension.
9951 Commands
9953 qapplied
9954 print the patches already applied:
9955 hg qapplied [-1] [-s] [PATCH]
9957 Returns 0 on success.
9959 Options:
9961 -1, --last
9963 show only the preceding applied patch
9964 -s, --summary
9966 print first line of patch header
9967 qclone
9969 clone main and patch repository at same time:
9970 hg qclone [OPTION]... SOURCE [DEST]
9972 If source is local, destination will have no patches applied. If source
9974 is remote, this command can not check if patches are applied in source,
9975 so cannot guarantee that patches are not applied in destination. If you
9976 clone remote repository, be sure before that it has no patches applied.
9977 Source patch repository is looked for in <src>/.hg/patches by default.
9979 Use -p <url> to change.
9980 The patch directory must be a nested Mercurial repository, as would be
9982 created by hg init --mq.
9983 Return 0 on success.
9985 Options:
9987 --pull use pull protocol to copy metadata
9989 -U, --noupdate
9991 do not update the new working directories
9992 --uncompressed
9994 use uncompressed transfer (fast over LAN)
9995 -p,--patches <REPO>
9997 location of source patch repository
9998 -e,--ssh <CMD>
10000 specify ssh command to use
10001 --remotecmd <CMD>
10003 specify hg command to run on the remote side
10004 --insecure
10006 do not verify server certificate (ignoring web.cacerts config)
10007 qcommit
10009 commit changes in the queue repository (DEPRECATED):
10010 hg qcommit [OPTION]... [FILE]...
10012 This command is deprecated; use hg commit --mq instead.
10014 Options:
10016 -A, --addremove
10018 mark new/missing files as added/removed before committing
10019 --close-branch
10021 mark a branch head as closed
10022 --amend
10024 amend the parent of the working directory
10025 -s, --secret
10027 use the secret phase for committing
10028 -e, --edit
10030 invoke editor on commit messages
10031 -i, --interactive
10033 use interactive mode
10034 -I,--include <PATTERN[+]>
10036 include names matching the given patterns
10037 -X,--exclude <PATTERN[+]>
10039 exclude names matching the given patterns
10040 -m,--message <TEXT>
10042 use text as commit message
10043 -l,--logfile <FILE>
10045 read commit message from file
10046 -d,--date <DATE>
10048 record the specified date as commit date
10049 -u,--user <USER>
10051 record the specified user as committer
10052 -S, --subrepos
10054 recurse into subrepositories
10055 [+] marked option can be specified multiple times
10057 aliases: qci
10059 qdelete
10061 remove patches from queue:
10062 hg qdelete [-k] [PATCH]...
10064 The patches must not be applied, and at least one patch is required.
10066 Exact patch identifiers must be given. With -k/--keep, the patch files
10067 are preserved in the patch directory.
10068 To stop managing a patch and move it into permanent history, use the hg
10070 qfinish command.
10071 Options:
10073 -k, --keep
10075 keep patch file
10076 -r,--rev <REV[+]>
10078 stop managing a revision (DEPRECATED)
10079 [+] marked option can be specified multiple times
10081 aliases: qremove qrm
10083 qdiff
10085 diff of the current patch and subsequent modifications:
10086 hg qdiff [OPTION]... [FILE]...
10088 Shows a diff which includes the current patch as well as any changes
10090 which have been made in the working directory since the last refresh
10091 (thus showing what the current patch would become after a qrefresh).
10092 Use hg diff if you only want to see the changes made since the last
10094 qrefresh, or hg export qtip if you want to see changes made by the cur‐
10095 rent patch without including changes made since the qrefresh.
10096 Returns 0 on success.
10098 Options:
10100 -a, --text
10102 treat all files as text
10103 -g, --git
10105 use git extended diff format
10106 --binary
10108 generate binary diffs in git mode (default)
10109 --nodates
10111 omit dates from diff headers
10112 --noprefix
10114 omit a/ and b/ prefixes from filenames
10115 -p, --show-function
10117 show which function each change is in
10118 --reverse
10120 produce a diff that undoes the changes
10121 -w, --ignore-all-space
10123 ignore white space when comparing lines
10124 -b, --ignore-space-change
10126 ignore changes in the amount of white space
10127 -B, --ignore-blank-lines
10129 ignore changes whose lines are all blank
10130 -Z, --ignore-space-at-eol
10132 ignore changes in whitespace at EOL
10133 -U,--unified <NUM>
10135 number of lines of context to show
10136 --stat output diffstat-style summary of changes
10138 --root <DIR>
10140 produce diffs relative to subdirectory
10141 -I,--include <PATTERN[+]>
10143 include names matching the given patterns
10144 -X,--exclude <PATTERN[+]>
10146 exclude names matching the given patterns
10147 [+] marked option can be specified multiple times
10149 qfinish
10151 move applied patches into repository history:
10152 hg qfinish [-a] [REV]...
10154 Finishes the specified revisions (corresponding to applied patches) by
10156 moving them out of mq control into regular repository history.
10157 Accepts a revision range or the -a/--applied option. If --applied is
10159 specified, all applied mq revisions are removed from mq control. Other‐
10160 wise, the given revisions must be at the base of the stack of applied
10161 patches.
10162 This can be especially useful if your changes have been applied to an
10164 upstream repository, or if you are about to push your changes to
10165 upstream.
10166 Returns 0 on success.
10168 Options:
10170 -a, --applied
10172 finish all applied changesets
10173 qfold
10175 fold the named patches into the current patch:
10176 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
10178 Patches must not yet be applied. Each patch will be successively
10180 applied to the current patch in the order given. If all the patches
10181 apply successfully, the current patch will be refreshed with the new
10182 cumulative patch, and the folded patches will be deleted. With
10183 -k/--keep, the folded patch files will not be removed afterwards.
10184 The header for each folded patch will be concatenated with the current
10186 patch header, separated by a line of * * *.
10187 Returns 0 on success.
10189 Options:
10191 -e, --edit
10193 invoke editor on commit messages
10194 -k, --keep
10196 keep folded patch files
10197 -m,--message <TEXT>
10199 use text as commit message
10200 -l,--logfile <FILE>
10202 read commit message from file
10203 qgoto
10205 push or pop patches until named patch is at top of stack:
10206 hg qgoto [OPTION]... PATCH
10208 Returns 0 on success.
10210 Options:
10212 --keep-changes
10214 tolerate non-conflicting local changes
10215 -f, --force
10217 overwrite any local changes
10218 --no-backup
10220 do not save backup copies of files
10221 qguard
10223 set or print guards for a patch:
10224 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
10226 Guards control whether a patch can be pushed. A patch with no guards is
10228 always pushed. A patch with a positive guard ("+foo") is pushed only if
10229 the hg qselect command has activated it. A patch with a negative guard
10230 ("-foo") is never pushed if the hg qselect command has activated it.
10231 With no arguments, print the currently active guards. With arguments,
10233 set guards for the named patch.
10234 Note Specifying negative guards now requires '--'.
10236 To set guards on another patch:
10238 hg qguard other.patch -- +2.6.17 -stable
10240 Returns 0 on success.
10242 Options:
10244 -l, --list
10246 list all patches and guards
10247 -n, --none
10249 drop all guards
10250 qheader
10252 print the header of the topmost or specified patch:
10253 hg qheader [PATCH]
10255 Returns 0 on success.
10257 qimport
10259 import a patch or existing changeset:
10260 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
10262 The patch is inserted into the series after the last applied patch. If
10264 no patches have been applied, qimport prepends the patch to the series.
10265 The patch will have the same name as its source file unless you give it
10267 a new one with -n/--name.
10268 You can register an existing patch inside the patch directory with the
10270 -e/--existing flag.
10271 With -f/--force, an existing patch of the same name will be overwrit‐
10273 ten.
10274 An existing changeset may be placed under mq control with -r/--rev
10276 (e.g. qimport --rev . -n patch will place the current revision under mq
10277 control). With -g/--git, patches imported with --rev will use the git
10278 diff format. See the diffs help topic for information on why this is
10279 important for preserving rename/copy information and permission
10280 changes. Use hg qfinish to remove changesets from mq control.
10281 To import a patch from standard input, pass - as the patch file. When
10283 importing from standard input, a patch name must be specified using the
10284 --name flag.
10285 To import an existing patch while renaming it:
10287 hg qimport -e existing-patch -n new-name
10289 Returns 0 if import succeeded.
10291 Options:
10293 -e, --existing
10295 import file in patch directory
10296 -n,--name <NAME>
10298 name of patch file
10299 -f, --force
10301 overwrite existing files
10302 -r,--rev <REV[+]>
10304 place existing revisions under mq control
10305 -g, --git
10307 use git extended diff format
10308 -P, --push
10310 qpush after importing
10311 [+] marked option can be specified multiple times
10313 qinit
10315 init a new queue repository (DEPRECATED):
10316 hg qinit [-c]
10318 The queue repository is unversioned by default. If -c/--create-repo is
10320 specified, qinit will create a separate nested repository for patches
10321 (qinit -c may also be run later to convert an unversioned patch reposi‐
10322 tory into a versioned one). You can use qcommit to commit changes to
10323 this queue repository.
10324 This command is deprecated. Without -c, it's implied by other relevant
10326 commands. With -c, use hg init --mq instead.
10327 Options:
10329 -c, --create-repo
10331 create queue repository
10332 qnew
10334 create a new patch:
10335 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
10337 qnew creates a new patch on top of the currently-applied patch (if
10339 any). The patch will be initialized with any outstanding changes in the
10340 working directory. You may also use -I/--include, -X/--exclude, and/or
10341 a list of files after the patch name to add only changes to matching
10342 files to the new patch, leaving the rest as uncommitted modifications.
10343 -u/--user and -d/--date can be used to set the (given) user and date,
10345 respectively. -U/--currentuser and -D/--currentdate set user to current
10346 user and date to current date.
10347 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
10349 the commit message. If none is specified, the header is empty and the
10350 commit message is '[mq]: PATCH'.
10351 Use the -g/--git option to keep the patch in the git extended diff for‐
10353 mat. Read the diffs help topic for more information on why this is
10354 important for preserving permission changes and copy/rename informa‐
10355 tion.
10356 Returns 0 on successful creation of a new patch.
10358 Options:
10360 -e, --edit
10362 invoke editor on commit messages
10363 -f, --force
10365 import uncommitted changes (DEPRECATED)
10366 -g, --git
10368 use git extended diff format
10369 -U, --currentuser
10371 add "From: <current user>" to patch
10372 -u,--user <USER>
10374 add "From: <USER>" to patch
10375 -D, --currentdate
10377 add "Date: <current date>" to patch
10378 -d,--date <DATE>
10380 add "Date: <DATE>" to patch
10381 -I,--include <PATTERN[+]>
10383 include names matching the given patterns
10384 -X,--exclude <PATTERN[+]>
10386 exclude names matching the given patterns
10387 -m,--message <TEXT>
10389 use text as commit message
10390 -l,--logfile <FILE>
10392 read commit message from file
10393 [+] marked option can be specified multiple times
10395 qnext
10397 print the name of the next pushable patch:
10398 hg qnext [-s]
10400 Returns 0 on success.
10402 Options:
10404 -s, --summary
10406 print first line of patch header
10407 qpop
10409 pop the current patch off the stack:
10410 hg qpop [-a] [-f] [PATCH | INDEX]
10412 Without argument, pops off the top of the patch stack. If given a patch
10414 name, keeps popping off patches until the named patch is at the top of
10415 the stack.
10416 By default, abort if the working directory contains uncommitted
10418 changes. With --keep-changes, abort only if the uncommitted files over‐
10419 lap with patched files. With -f/--force, backup and discard changes
10420 made to such files.
10421 Return 0 on success.
10423 Options:
10425 -a, --all
10427 pop all patches
10428 -n,--name <NAME>
10430 queue name to pop (DEPRECATED)
10431 --keep-changes
10433 tolerate non-conflicting local changes
10434 -f, --force
10436 forget any local changes to patched files
10437 --no-backup
10439 do not save backup copies of files
10440 qprev
10442 print the name of the preceding applied patch:
10443 hg qprev [-s]
10445 Returns 0 on success.
10447 Options:
10449 -s, --summary
10451 print first line of patch header
10452 qpush
10454 push the next patch onto the stack:
10455 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
10457 By default, abort if the working directory contains uncommitted
10459 changes. With --keep-changes, abort only if the uncommitted files over‐
10460 lap with patched files. With -f/--force, backup and patch over uncom‐
10461 mitted changes.
10462 Return 0 on success.
10464 Options:
10466 --keep-changes
10468 tolerate non-conflicting local changes
10469 -f, --force
10471 apply on top of local changes
10472 -e, --exact
10474 apply the target patch to its recorded parent
10475 -l, --list
10477 list patch name in commit text
10478 -a, --all
10480 apply all patches
10481 -m, --merge
10483 merge from another queue (DEPRECATED)
10484 -n,--name <NAME>
10486 merge queue name (DEPRECATED)
10487 --move reorder patch series and apply only the patch
10489 --no-backup
10491 do not save backup copies of files
10492 qqueue
10494 manage multiple patch queues:
10495 hg qqueue [OPTION] [QUEUE]
10497 Supports switching between different patch queues, as well as creating
10499 new patch queues and deleting existing ones.
10500 Omitting a queue name or specifying -l/--list will show you the regis‐
10502 tered queues - by default the "normal" patches queue is registered. The
10503 currently active queue will be marked with "(active)". Specifying
10504 --active will print only the name of the active queue.
10505 To create a new queue, use -c/--create. The queue is automatically made
10507 active, except in the case where there are applied patches from the
10508 currently active queue in the repository. Then the queue will only be
10509 created and switching will fail.
10510 To delete an existing queue, use --delete. You cannot delete the cur‐
10512 rently active queue.
10513 Returns 0 on success.
10515 Options:
10517 -l, --list
10519 list all available queues
10520 --active
10522 print name of active queue
10523 -c, --create
10525 create new queue
10526 --rename
10528 rename active queue
10529 --delete
10531 delete reference to queue
10532 --purge
10534 delete queue, and remove patch dir
10535 qrefresh
10537 update the current patch:
10538 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
10540 If any file patterns are provided, the refreshed patch will contain
10542 only the modifications that match those patterns; the remaining modifi‐
10543 cations will remain in the working directory.
10544 If -s/--short is specified, files currently included in the patch will
10546 be refreshed just like matched files and remain in the patch.
10547 If -e/--edit is specified, Mercurial will start your configured editor
10549 for you to enter a message. In case qrefresh fails, you will find a
10550 backup of your message in .hg/last-message.txt.
10551 hg add/remove/copy/rename work as usual, though you might want to use
10553 git-style patches (-g/--git or [diff] git=1) to track copies and
10554 renames. See the diffs help topic for more information on the git diff
10555 format.
10556 Returns 0 on success.
10558 Options:
10560 -e, --edit
10562 invoke editor on commit messages
10563 -g, --git
10565 use git extended diff format
10566 -s, --short
10568 refresh only files already in the patch and specified files
10569 -U, --currentuser
10571 add/update author field in patch with current user
10572 -u,--user <USER>
10574 add/update author field in patch with given user
10575 -D, --currentdate
10577 add/update date field in patch with current date
10578 -d,--date <DATE>
10580 add/update date field in patch with given date
10581 -I,--include <PATTERN[+]>
10583 include names matching the given patterns
10584 -X,--exclude <PATTERN[+]>
10586 exclude names matching the given patterns
10587 -m,--message <TEXT>
10589 use text as commit message
10590 -l,--logfile <FILE>
10592 read commit message from file
10593 [+] marked option can be specified multiple times
10595 qrename
10597 rename a patch:
10598 hg qrename PATCH1 [PATCH2]
10600 With one argument, renames the current patch to PATCH1. With two argu‐
10602 ments, renames PATCH1 to PATCH2.
10603 Returns 0 on success.
10605 aliases: qmv
10607 qrestore
10609 restore the queue state saved by a revision (DEPRECATED):
10610 hg qrestore [-d] [-u] REV
10612 This command is deprecated, use hg rebase instead.
10614 Options:
10616 -d, --delete
10618 delete save entry
10619 -u, --update
10621 update queue working directory
10622 qsave
10624 save current queue state (DEPRECATED):
10625 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
10627 This command is deprecated, use hg rebase instead.
10629 Options:
10631 -c, --copy
10633 copy patch directory
10634 -n,--name <NAME>
10636 copy directory name
10637 -e, --empty
10639 clear queue status file
10640 -f, --force
10642 force copy
10643 -m,--message <TEXT>
10645 use text as commit message
10646 -l,--logfile <FILE>
10648 read commit message from file
10649 qselect
10651 set or print guarded patches to push:
10652 hg qselect [OPTION]... [GUARD]...
10654 Use the hg qguard command to set or print guards on patch, then use
10656 qselect to tell mq which guards to use. A patch will be pushed if it
10657 has no guards or any positive guards match the currently selected
10658 guard, but will not be pushed if any negative guards match the current
10659 guard. For example:
10660 qguard foo.patch -- -stable (negative guard)
10662 qguard bar.patch +stable (positive guard)
10663 qselect stable
10664 This activates the "stable" guard. mq will skip foo.patch (because it
10666 has a negative match) but push bar.patch (because it has a positive
10667 match).
10668 With no arguments, prints the currently active guards. With one argu‐
10670 ment, sets the active guard.
10671 Use -n/--none to deactivate guards (no other arguments needed). When
10673 no guards are active, patches with positive guards are skipped and
10674 patches with negative guards are pushed.
10675 qselect can change the guards on applied patches. It does not pop
10677 guarded patches by default. Use --pop to pop back to the last applied
10678 patch that is not guarded. Use --reapply (which implies --pop) to push
10679 back to the current patch afterwards, but skip guarded patches.
10680 Use -s/--series to print a list of all guards in the series file (no
10682 other arguments needed). Use -v for more information.
10683 Returns 0 on success.
10685 Options:
10687 -n, --none
10689 disable all guards
10690 -s, --series
10692 list all guards in series file
10693 --pop pop to before first guarded applied patch
10695 --reapply
10697 pop, then reapply patches
10698 qseries
10700 print the entire series file:
10701 hg qseries [-ms]
10703 Returns 0 on success.
10705 Options:
10707 -m, --missing
10709 print patches not in series
10710 -s, --summary
10712 print first line of patch header
10713 qtop
10715 print the name of the current patch:
10716 hg qtop [-s]
10718 Returns 0 on success.
10720 Options:
10722 -s, --summary
10724 print first line of patch header
10725 qunapplied
10727 print the patches not yet applied:
10728 hg qunapplied [-1] [-s] [PATCH]
10730 Returns 0 on success.
10732 Options:
10734 -1, --first
10736 show only the first patch
10737 -s, --summary
10739 print first line of patch header
10740 notify
10742 hooks for sending email push notifications
10743 This extension implements hooks to send email notifications when
10745 changesets are sent from or received by the local repository.
10746 First, enable the extension as explained in hg help extensions, and
10748 register the hook you want to run. incoming and changegroup hooks are
10749 run when changesets are received, while outgoing hooks are for change‐
10750 sets sent to another repository:
10751 [hooks]
10753 # one email for each incoming changeset
10754 incoming.notify = python:hgext.notify.hook
10755 # one email for all incoming changesets
10756 changegroup.notify = python:hgext.notify.hook
10757 # one email for all outgoing changesets
10759 outgoing.notify = python:hgext.notify.hook
10760 This registers the hooks. To enable notification, subscribers must be
10762 assigned to repositories. The [usersubs] section maps multiple reposi‐
10763 tories to a given recipient. The [reposubs] section maps multiple
10764 recipients to a single repository:
10765 [usersubs]
10767 # key is subscriber email, value is a comma-separated list of repo patterns
10768 user@host = pattern
10769 [reposubs]
10771 # key is repo pattern, value is a comma-separated list of subscriber emails
10772 pattern = user@host
10773 A pattern is a glob matching the absolute path to a repository, option‐
10775 ally combined with a revset expression. A revset expression, if
10776 present, is separated from the glob by a hash. Example:
10777 [reposubs]
10779 */widgets#branch(release) = qa-team@example.com
10780 This sends to qa-team@example.com whenever a changeset on the release
10782 branch triggers a notification in any repository ending in widgets.
10783 In order to place them under direct user management, [usersubs] and
10785 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
10786 rated by reference:
10787 [notify]
10789 config = /path/to/subscriptionsfile
10790 Notifications will not be sent until the notify.test value is set to
10792 False; see below.
10793 Notifications content can be tweaked with the following configuration
10795 entries:
10796 notify.test
10798 If True, print messages to stdout instead of sending them.
10799 Default: True.
10800 notify.sources
10802 Space-separated list of change sources. Notifications are acti‐
10803 vated only when a changeset's source is in this list. Sources
10804 may be:
10805 serve
10807 changesets received via http or ssh
10809 pull
10811 changesets received via hg pull
10813 unbundle
10815 changesets received via hg unbundle
10817 push
10819 changesets sent or received via hg push
10821 bundle
10823 changesets sent via hg unbundle
10825 Default: serve.
10827 notify.strip
10829 Number of leading slashes to strip from url paths. By default,
10830 notifications reference repositories with their absolute path.
10831 notify.strip lets you turn them into relative paths. For exam‐
10832 ple, notify.strip=3 will change /long/path/repository into
10833 repository. Default: 0.
10834 notify.domain
10836 Default email domain for sender or recipients with no explicit
10837 domain.
10838 notify.style
10840 Style file to use when formatting emails.
10841 notify.template
10843 Template to use when formatting emails.
10844 notify.incoming
10846 Template to use when run as an incoming hook, overriding
10847 notify.template.
10848 notify.outgoing
10850 Template to use when run as an outgoing hook, overriding
10851 notify.template.
10852 notify.changegroup
10854 Template to use when running as a changegroup hook, overriding
10855 notify.template.
10856 notify.maxdiff
10858 Maximum number of diff lines to include in notification email.
10859 Set to 0 to disable the diff, or -1 to include all of it.
10860 Default: 300.
10861 notify.maxsubject
10863 Maximum number of characters in email's subject line. Default:
10864 67.
10865 notify.diffstat
10867 Set to True to include a diffstat before diff content. Default:
10868 True.
10869 notify.merge
10871 If True, send notifications for merge changesets. Default: True.
10872 notify.mbox
10874 If set, append mails to this mbox file instead of sending.
10875 Default: None.
10876 notify.fromauthor
10878 If set, use the committer of the first changeset in a change‐
10879 group for the "From" field of the notification mail. If not set,
10880 take the user from the pushing repo. Default: False.
10881 If set, the following entries will also be used to customize the noti‐
10883 fications:
10884 email.from
10886 Email From address to use if none can be found in the generated
10887 email content.
10888 web.baseurl
10890 Root repository URL to combine with repository paths when making
10891 references. See also notify.strip.
10892 pager
10894 browse command output with an external pager (DEPRECATED)
10895 Forcibly enable paging for individual commands that don't typically
10897 request pagination with the attend-<command> option. This setting takes
10898 precedence over ignore options and defaults:
10899 [pager]
10901 attend-cat = false
10902 patchbomb
10904 command to send changesets as (a series of) patch emails
10905 The series is started off with a "[PATCH 0 of N]" introduction, which
10907 describes the series as a whole.
10908 Each patch email has a Subject line of "[PATCH M of N] ...", using the
10910 first line of the changeset description as the subject text. The mes‐
10911 sage contains two or three body parts:
10912 · The changeset description.
10914 · [Optional] The result of running diffstat on the patch.
10916 · The patch itself, as generated by hg export.
10918 Each message refers to the first in the series using the In-Reply-To
10920 and References headers, so they will show up as a sequence in threaded
10921 mail and news readers, and in mail archives.
10922 To configure other defaults, add a section like this to your configura‐
10924 tion file:
10925 [email]
10927 from = My Name <my@email>
10928 to = recipient1, recipient2, ...
10929 cc = cc1, cc2, ...
10930 bcc = bcc1, bcc2, ...
10931 reply-to = address1, address2, ...
10932 Use [patchbomb] as configuration section name if you need to override
10934 global [email] address settings.
10935 Then you can use the hg email command to mail a series of changesets as
10937 a patchbomb.
10938 You can also either configure the method option in the email section to
10940 be a sendmail compatible mailer or fill out the [smtp] section so that
10941 the patchbomb extension can automatically send patchbombs directly from
10942 the commandline. See the [email] and [smtp] sections in hgrc(5) for
10943 details.
10944 By default, hg email will prompt for a To or CC header if you do not
10946 supply one via configuration or the command line. You can override
10947 this to never prompt by configuring an empty value:
10948 [email]
10950 cc =
10951 You can control the default inclusion of an introduction message with
10953 the patchbomb.intro configuration option. The configuration is always
10954 overwritten by command line flags like --intro and --desc:
10955 [patchbomb]
10957 intro=auto # include introduction message if more than 1 patch (default)
10958 intro=never # never include an introduction message
10959 intro=always # always include an introduction message
10960 You can specify a template for flags to be added in subject prefixes.
10962 Flags specified by --flag option are exported as {flags} keyword:
10963 [patchbomb]
10965 flagtemplate = "{separate(' ',
10966 ifeq(branch, 'default', '', branch|upper),
10967 flags)}"
10968 You can set patchbomb to always ask for confirmation by setting patch‐
10970 bomb.confirm to true.
10971 Commands
10973 email
10974 send changesets by email:
10975 hg email [OPTION]... [DEST]...
10977 By default, diffs are sent in the format generated by hg export, one
10979 per message. The series starts with a "[PATCH 0 of N]" introduction,
10980 which describes the series as a whole.
10981 Each patch email has a Subject line of "[PATCH M of N] ...", using the
10983 first line of the changeset description as the subject text. The mes‐
10984 sage contains two or three parts. First, the changeset description.
10985 With the -d/--diffstat option, if the diffstat program is installed,
10987 the result of running diffstat on the patch is inserted.
10988 Finally, the patch itself, as generated by hg export.
10990 With the -d/--diffstat or --confirm options, you will be presented with
10992 a final summary of all messages and asked for confirmation before the
10993 messages are sent.
10994 By default the patch is included as text in the email body for easy
10996 reviewing. Using the -a/--attach option will instead create an attach‐
10997 ment for the patch. With -i/--inline an inline attachment will be cre‐
10998 ated. You can include a patch both as text in the email body and as a
10999 regular or an inline attachment by combining the -a/--attach or
11000 -i/--inline with the --body option.
11001 With -B/--bookmark changesets reachable by the given bookmark are
11003 selected.
11004 With -o/--outgoing, emails will be generated for patches not found in
11006 the destination repository (or only those which are ancestors of the
11007 specified revisions if any are provided)
11008 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
11010 gle email containing a binary Mercurial bundle as an attachment will be
11011 sent. Use the patchbomb.bundletype config option to control the bundle
11012 type as with hg bundle --type.
11013 With -m/--mbox, instead of previewing each patchbomb message in a pager
11015 or sending the messages directly, it will create a UNIX mailbox file
11016 with the patch emails. This mailbox file can be previewed with any mail
11017 user agent which supports UNIX mbox files.
11018 With -n/--test, all steps will run, but mail will not be sent. You
11020 will be prompted for an email recipient address, a subject and an
11021 introductory message describing the patches of your patchbomb. Then
11022 when all is done, patchbomb messages are displayed.
11023 In case email sending fails, you will find a backup of your series
11025 introductory message in .hg/last-email.txt.
11026 The default behavior of this command can be customized through configu‐
11028 ration. (See hg help patchbomb for details)
11029 Examples:
11031 hg email -r 3000 # send patch 3000 only
11033 hg email -r 3000 -r 3001 # send patches 3000 and 3001
11034 hg email -r 3000:3005 # send patches 3000 through 3005
11035 hg email 3000 # send patch 3000 (deprecated)
11036 hg email -o # send all patches not in default
11038 hg email -o DEST # send all patches not in DEST
11039 hg email -o -r 3000 # send all ancestors of 3000 not in default
11040 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
11041 hg email -B feature # send all ancestors of feature bookmark
11043 hg email -b # send bundle of all patches not in default
11045 hg email -b DEST # send bundle of all patches not in DEST
11046 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
11047 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
11048 hg email -o -m mbox && # generate an mbox file...
11050 mutt -R -f mbox # ... and view it with mutt
11051 hg email -o -m mbox && # generate an mbox file ...
11052 formail -s sendmail \ # ... and use formail to send from the mbox
11053 -bm -t < mbox # ... using sendmail
11054 Before using this command, you will need to enable email in your hgrc.
11056 See the [email] section in hgrc(5) for details.
11057 Options:
11059 -g, --git
11061 use git extended diff format
11062 --plain
11064 omit hg patch header
11065 -o, --outgoing
11067 send changes not found in the target repository
11068 -b, --bundle
11070 send changes not in target as a binary bundle
11071 -B,--bookmark <VALUE>
11073 send changes only reachable by given bookmark
11074 --bundlename <NAME>
11076 name of the bundle attachment file (default: bundle)
11077 -r,--rev <REV[+]>
11079 a revision to send
11080 --force
11082 run even when remote repository is unrelated (with -b/--bundle)
11083 --base <REV[+]>
11085 a base changeset to specify instead of a destination (with
11086 -b/--bundle)
11087 --intro
11089 send an introduction email for a single patch
11090 --body send patches as inline message text (default)
11092 -a, --attach
11094 send patches as attachments
11095 -i, --inline
11097 send patches as inline attachments
11098 --bcc <VALUE[+]>
11100 email addresses of blind carbon copy recipients
11101 -c,--cc <VALUE[+]>
11103 email addresses of copy recipients
11104 --confirm
11106 ask for confirmation before sending
11107 -d, --diffstat
11109 add diffstat output to messages
11110 --date <VALUE>
11112 use the given date as the sending date
11113 --desc <VALUE>
11115 use the given file as the series description
11116 -f,--from <VALUE>
11118 email address of sender
11119 -n, --test
11121 print messages that would be sent
11122 -m,--mbox <VALUE>
11124 write messages to mbox file instead of sending them
11125 --reply-to <VALUE[+]>
11127 email addresses replies should be sent to
11128 -s,--subject <VALUE>
11130 subject of first message (intro or single patch)
11131 --in-reply-to <VALUE>
11133 message identifier to reply to
11134 --flag <VALUE[+]>
11136 flags to add in subject prefixes
11137 -t,--to <VALUE[+]>
11139 email addresses of recipients
11140 -e,--ssh <CMD>
11142 specify ssh command to use
11143 --remotecmd <CMD>
11145 specify hg command to run on the remote side
11146 --insecure
11148 do not verify server certificate (ignoring web.cacerts config)
11149 [+] marked option can be specified multiple times
11151 purge
11153 command to delete untracked files from the working directory
11154 Commands
11156 purge
11157 removes files not tracked by Mercurial:
11158 hg purge [OPTION]... [DIR]...
11160 Delete files not known to Mercurial. This is useful to test local and
11162 uncommitted changes in an otherwise-clean source tree.
11163 This means that purge will delete the following by default:
11165 · Unknown files: files marked with "?" by hg status
11167 · Empty directories: in fact Mercurial ignores directories unless they
11169 contain files under source control management
11170 But it will leave untouched:
11172 · Modified and unmodified tracked files
11174 · Ignored files (unless --all is specified)
11176 · New files added to the repository (with hg add)
11178 The --files and --dirs options can be used to direct purge to delete
11180 only files, only directories, or both. If neither option is given, both
11181 will be deleted.
11182 If directories are given on the command line, only files in these
11184 directories are considered.
11185 Be careful with purge, as you could irreversibly delete some files you
11187 forgot to add to the repository. If you only want to print the list of
11188 files that this program would delete, use the --print option.
11189 Options:
11191 -a, --abort-on-err
11193 abort if an error occurs
11194 --all purge ignored files too
11196 --dirs purge empty directories
11198 --files
11200 purge files
11201 -p, --print
11203 print filenames instead of deleting them
11204 -0, --print0
11206 end filenames with NUL, for use with xargs (implies -p/--print)
11207 -I,--include <PATTERN[+]>
11209 include names matching the given patterns
11210 -X,--exclude <PATTERN[+]>
11212 exclude names matching the given patterns
11213 [+] marked option can be specified multiple times
11215 aliases: clean
11217 rebase
11219 command to move sets of revisions to a different ancestor
11220 This extension lets you rebase changesets in an existing Mercurial
11222 repository.
11223 For more information: https://mercurial-scm.org/wiki/RebaseExtension
11225 Commands
11227 rebase
11228 move changeset (and descendants) to a different branch:
11229 hg rebase [-s REV | -b REV] [-d REV] [OPTION]
11231 Rebase uses repeated merging to graft changesets from one part of his‐
11233 tory (the source) onto another (the destination). This can be useful
11234 for linearizing local changes relative to a master development tree.
11235 Published commits cannot be rebased (see hg help phases). To copy com‐
11237 mits, see hg help graft.
11238 If you don't specify a destination changeset (-d/--dest), rebase will
11240 use the same logic as hg merge to pick a destination. if the current
11241 branch contains exactly one other head, the other head is merged with
11242 by default. Otherwise, an explicit revision with which to merge with
11243 must be provided. (destination changeset is not modified by rebasing,
11244 but new changesets are added as its descendants.)
11245 Here are the ways to select changesets:
11247 1. Explicitly select them using --rev.
11249 2. Use --source to select a root changeset and include all of its
11251 descendants.
11252 3. Use --base to select a changeset; rebase will find ancestors and
11254 their descendants which are not also ancestors of the destina‐
11255 tion.
11256 4. If you do not specify any of --rev, source, or --base, rebase
11258 will use --base . as above.
11259 If --source or --rev is used, special names SRC and ALLSRC can be used
11261 in --dest. Destination would be calculated per source revision with SRC
11262 substituted by that single source revision and ALLSRC substituted by
11263 all source revisions.
11264 Rebase will destroy original changesets unless you use --keep. It will
11266 also move your bookmarks (even if you do).
11267 Some changesets may be dropped if they do not contribute changes (e.g.
11269 merges from the destination branch).
11270 Unlike merge, rebase will do nothing if you are at the branch tip of a
11272 named branch with two heads. You will need to explicitly specify source
11273 and/or destination.
11274 If you need to use a tool to automate merge/conflict decisions, you can
11276 specify one with --tool, see hg help merge-tools. As a caveat: the
11277 tool will not be used to mediate when a file was deleted, there is no
11278 hook presently available for this.
11279 If a rebase is interrupted to manually resolve a conflict, it can be
11281 continued with --continue/-c or aborted with --abort/-a.
11282 Examples:
11284 · move "local changes" (current commit back to branching point) to the
11286 current branch tip after a pull:
11287 hg rebase
11289 · move a single changeset to the stable branch:
11291 hg rebase -r 5f493448 -d stable
11293 · splice a commit and all its descendants onto another part of history:
11295 hg rebase --source c0c3 --dest 4cf9
11297 · rebase everything on a branch marked by a bookmark onto the default
11299 branch:
11300 hg rebase --base myfeature --dest default
11302 · collapse a sequence of changes into a single commit:
11304 hg rebase --collapse -r 1520:1525 -d .
11306 · move a named branch while preserving its name:
11308 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
11310 · stabilize orphaned changesets so history looks linear:
11312 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
11314 Configuration Options:
11316 You can make rebase require a destination if you set the following con‐
11318 fig option:
11319 [commands]
11321 rebase.requiredest = True
11322 By default, rebase will close the transaction after each commit. For
11324 performance purposes, you can configure rebase to use a single transac‐
11325 tion across the entire rebase. WARNING: This setting introduces a sig‐
11326 nificant risk of losing the work you've done in a rebase if the rebase
11327 aborts unexpectedly:
11328 [rebase]
11330 singletransaction = True
11331 By default, rebase writes to the working copy, but you can configure it
11333 to run in-memory for for better performance, and to allow it to run if
11334 the working copy is dirty:
11335 [rebase]
11337 experimental.inmemory = True
11338 Return Values:
11340 Returns 0 on success, 1 if nothing to rebase or there are unresolved
11342 conflicts.
11343 Options:
11345 -s,--source <REV>
11347 rebase the specified changeset and descendants
11348 -b,--base <REV>
11350 rebase everything from branching point of specified changeset
11351 -r,--rev <REV[+]>
11353 rebase these revisions
11354 -d,--dest <REV>
11356 rebase onto the specified changeset
11357 --collapse
11359 collapse the rebased changesets
11360 -m,--message <TEXT>
11362 use text as collapse commit message
11363 -e, --edit
11365 invoke editor on commit messages
11366 -l,--logfile <FILE>
11368 read collapse commit message from file
11369 -k, --keep
11371 keep original changesets
11372 --keepbranches
11374 keep original branch names
11375 -D, --detach
11377 (DEPRECATED)
11378 -i, --interactive
11380 (DEPRECATED)
11381 -t,--tool <VALUE>
11383 specify merge tool
11384 -c, --continue
11386 continue an interrupted rebase
11387 -a, --abort
11389 abort an interrupted rebase
11390 -T,--template <TEMPLATE>
11392 display with template (EXPERIMENTAL)
11393 [+] marked option can be specified multiple times
11395 record
11397 commands to interactively select changes for commit/qrefresh (DEPRE‐
11398 CATED)
11399 The feature provided by this extension has been moved into core Mercu‐
11401 rial as hg commit --interactive.
11402 Commands
11404 qrecord
11405 interactively record a new patch:
11406 hg qrecord [OPTION]... PATCH [FILE]...
11408 See hg help qnew & hg help record for more information and usage.
11410 record
11412 interactively select changes to commit:
11413 hg record [OPTION]... [FILE]...
11415 If a list of files is omitted, all changes reported by hg status will
11417 be candidates for recording.
11418 See hg help dates for a list of formats valid for -d/--date.
11420 If using the text interface (see hg help config), you will be prompted
11422 for whether to record changes to each modified file, and for files with
11423 multiple changes, for each change to use. For each query, the following
11424 responses are possible:
11425 y - record this change
11427 n - skip this change
11428 e - edit this change manually
11429 s - skip remaining changes to this file
11431 f - record remaining changes to this file
11432 d - done, skip remaining changes and files
11434 a - record all changes to all remaining files
11435 q - quit, recording no changes
11436 ? - display help
11438 This command is not available when committing a merge.
11440 Options:
11442 -A, --addremove
11444 mark new/missing files as added/removed before committing
11445 --close-branch
11447 mark a branch head as closed
11448 --amend
11450 amend the parent of the working directory
11451 -s, --secret
11453 use the secret phase for committing
11454 -e, --edit
11456 invoke editor on commit messages
11457 -I,--include <PATTERN[+]>
11459 include names matching the given patterns
11460 -X,--exclude <PATTERN[+]>
11462 exclude names matching the given patterns
11463 -m,--message <TEXT>
11465 use text as commit message
11466 -l,--logfile <FILE>
11468 read commit message from file
11469 -d,--date <DATE>
11471 record the specified date as commit date
11472 -u,--user <USER>
11474 record the specified user as committer
11475 -S, --subrepos
11477 recurse into subrepositories
11478 -w, --ignore-all-space
11480 ignore white space when comparing lines
11481 -b, --ignore-space-change
11483 ignore changes in the amount of white space
11484 -B, --ignore-blank-lines
11486 ignore changes whose lines are all blank
11487 -Z, --ignore-space-at-eol
11489 ignore changes in whitespace at EOL
11490 [+] marked option can be specified multiple times
11492 releasenotes
11494 generate release notes from commit messages (EXPERIMENTAL)
11495 It is common to maintain files detailing changes in a project between
11497 releases. Maintaining these files can be difficult and time consuming.
11498 The hg releasenotes command provided by this extension makes the
11499 process simpler by automating it.
11500 Commands
11502 releasenotes
11503 parse release notes from commit messages into an output file:
11504 hg releasenotes [-r REV] [-c] FILE
11506 Given an output file and set of revisions, this command will parse com‐
11508 mit messages for release notes then add them to the output file.
11509 Release notes are defined in commit messages as ReStructuredText direc‐
11511 tives. These have the form:
11512 .. directive:: title
11514 content
11516 Each directive maps to an output section in a generated release notes
11518 file, which itself is ReStructuredText. For example, the .. feature::
11519 directive would map to a New Features section.
11520 Release note directives can be either short-form or long-form. In
11522 short- form, title is omitted and the release note is rendered as a
11523 bullet list. In long form, a sub-section with the title title is added
11524 to the section.
11525 The FILE argument controls the output file to write gathered release
11527 notes to. The format of the file is:
11528 Section 1
11530 =========
11531 ...
11533 Section 2
11535 =========
11536 ...
11538 Only sections with defined release notes are emitted.
11540 If a section only has short-form notes, it will consist of bullet list:
11542 Section
11544 =======
11545 * Release note 1
11547 * Release note 2
11548 If a section has long-form notes, sub-sections will be emitted:
11550 Section
11552 =======
11553 Note 1 Title
11555 ------------
11556 Description of the first long-form note.
11558 Note 2 Title
11560 ------------
11561 Description of the second long-form note.
11563 If the FILE argument points to an existing file, that file will be
11565 parsed for release notes having the format that would be generated by
11566 this command. The notes from the processed commit messages will be
11567 merged into this parsed set.
11568 During release notes merging:
11570 · Duplicate items are automatically ignored
11572 · Items that are different are automatically ignored if the similarity
11574 is greater than a threshold.
11575 This means that the release notes file can be updated independently
11577 from this command and changes should not be lost when running this com‐
11578 mand on that file. A particular use case for this is to tweak the word‐
11579 ing of a release note after it has been added to the release notes
11580 file.
11581 The -c/--check option checks the commit message for invalid admoni‐
11583 tions.
11584 The -l/--list option, presents the user with a list of existing avail‐
11586 able admonitions along with their title. This also includes the custom
11587 admonitions (if any).
11588 Options:
11590 -r,--rev <REV>
11592 revisions to process for release notes
11593 -c, --check
11595 checks for validity of admonitions (if any)
11596 -l, --list
11598 list the available admonitions with their title
11599 relink
11601 recreates hardlinks between repository clones
11602 Commands
11604 relink
11605 recreate hardlinks between two repositories:
11606 hg relink [ORIGIN]
11608 When repositories are cloned locally, their data files will be
11610 hardlinked so that they only use the space of a single repository.
11611 Unfortunately, subsequent pulls into either repository will break
11613 hardlinks for any files touched by the new changesets, even if both
11614 repositories end up pulling the same changes.
11615 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
11617 falling back to a complete copy of the source repository.
11618 This command lets you recreate those hardlinks and reclaim that wasted
11620 space.
11621 This repository will be relinked to share space with ORIGIN, which must
11623 be on the same local disk. If ORIGIN is omitted, looks for
11624 "default-relink", then "default", in [paths].
11625 Do not attempt any read operations on this repository while the command
11627 is running. (Both repositories will be locked against writes.)
11628 schemes
11630 extend schemes with shortcuts to repository swarms
11631 This extension allows you to specify shortcuts for parent URLs with a
11633 lot of repositories to act like a scheme, for example:
11634 [schemes]
11636 py = http://code.python.org/hg/
11637 After that you can use it like:
11639 hg clone py://trunk/
11641 Additionally there is support for some more complex schemas, for exam‐
11643 ple used by Google Code:
11644 [schemes]
11646 gcode = http://{1}.googlecode.com/hg/
11647 The syntax is taken from Mercurial templates, and you have unlimited
11649 number of variables, starting with {1} and continuing with {2}, {3} and
11650 so on. This variables will receive parts of URL supplied, split by /.
11651 Anything not specified as {part} will be just appended to an URL.
11652 For convenience, the extension adds these schemes by default:
11654 [schemes]
11656 py = http://hg.python.org/
11657 bb = https://bitbucket.org/
11658 bb+ssh = ssh://hg@bitbucket.org/
11659 gcode = https://{1}.googlecode.com/hg/
11660 kiln = https://{1}.kilnhg.com/Repo/
11661 You can override a predefined scheme by defining a new scheme with the
11663 same name.
11664 Commands
11666 share
11667 share a common history between several working directories
11668 Automatic Pooled Storage for Clones
11670 When this extension is active, hg clone can be configured to automati‐
11671 cally share/pool storage across multiple clones. This mode effectively
11672 converts hg clone to hg clone + hg share. The benefit of using this
11673 mode is the automatic management of store paths and intelligent pooling
11674 of related repositories.
11675 The following share. config options influence this feature:
11677 share.pool
11679 Filesystem path where shared repository data will be stored.
11681 When defined, hg clone will automatically use shared repository
11682 storage instead of creating a store inside each clone.
11683 share.poolnaming
11685 How directory names in share.pool are constructed.
11687 "identity" means the name is derived from the first changeset in
11689 the repository. In this mode, different remotes share storage if
11690 their root/initial changeset is identical. In this mode, the
11691 local shared repository is an aggregate of all encountered
11692 remote repositories.
11693 "remote" means the name is derived from the source repository's
11695 path or URL. In this mode, storage is only shared if the path or
11696 URL requested in the hg clone command matches exactly to a
11697 repository that was cloned before.
11698 The default naming mode is "identity".
11700 Commands
11702 share
11703 create a new shared repository:
11704 hg share [-U] [-B] SOURCE [DEST]
11706 Initialize a new repository and working directory that shares its his‐
11708 tory (and optionally bookmarks) with another repository.
11709 Note using rollback or extensions that destroy/modify history (mq,
11711 rebase, etc.) can cause considerable confusion with shared
11712 clones. In particular, if two shared clones are both updated to
11713 the same changeset, and one of them destroys that changeset with
11714 rollback, the other clone will suddenly stop working: all opera‐
11715 tions will fail with "abort: working directory has unknown par‐
11716 ent". The only known workaround is to use debugsetparents on the
11717 broken clone to reset it to a changeset that still exists.
11718 Options:
11720 -U, --noupdate
11722 do not create a working directory
11723 -B, --bookmarks
11725 also share bookmarks
11726 --relative
11728 point to source using a relative path (EXPERIMENTAL)
11729 unshare
11731 convert a shared repository to a normal one:
11732 hg unshare
11734 Copy the store data to the repo and remove the sharedpath data.
11736 shelve
11738 save and restore changes to the working directory
11739 The "hg shelve" command saves changes made to the working directory and
11741 reverts those changes, resetting the working directory to a clean
11742 state.
11743 Later on, the "hg unshelve" command restores the changes saved by "hg
11745 shelve". Changes can be restored even after updating to a different
11746 parent, in which case Mercurial's merge machinery will resolve any con‐
11747 flicts if necessary.
11748 You can have more than one shelved change outstanding at a time; each
11750 shelved change has a distinct name. For details, see the help for "hg
11751 shelve".
11752 Commands
11754 shelve
11755 save and set aside changes from the working directory:
11756 hg shelve [OPTION]... [FILE]...
11758 Shelving takes files that "hg status" reports as not clean, saves the
11760 modifications to a bundle (a shelved change), and reverts the files so
11761 that their state in the working directory becomes clean.
11762 To restore these changes to the working directory, using "hg unshelve";
11764 this will work even if you switch to a different commit.
11765 When no files are specified, "hg shelve" saves all not-clean files. If
11767 specific files or directories are named, only changes to those files
11768 are shelved.
11769 In bare shelve (when no files are specified, without interactive,
11771 include and exclude option), shelving remembers information if the
11772 working directory was on newly created branch, in other words working
11773 directory was on different branch than its first parent. In this situa‐
11774 tion unshelving restores branch information to the working directory.
11775 Each shelved change has a name that makes it easier to find later. The
11777 name of a shelved change defaults to being based on the active book‐
11778 mark, or if there is no active bookmark, the current named branch. To
11779 specify a different name, use --name.
11780 To see a list of existing shelved changes, use the --list option. For
11782 each shelved change, this will print its name, age, and description;
11783 use --patch or --stat for more details.
11784 To delete specific shelved changes, use --delete. To delete all shelved
11786 changes, use --cleanup.
11787 Options:
11789 -A, --addremove
11791 mark new/missing files as added/removed before shelving
11792 -u, --unknown
11794 store unknown files in the shelve
11795 --cleanup
11797 delete all shelved changes
11798 --date <DATE>
11800 shelve with the specified commit date
11801 -d, --delete
11803 delete the named shelved change(s)
11804 -e, --edit
11806 invoke editor on commit messages
11807 -l, --list
11809 list current shelves
11810 -m,--message <TEXT>
11812 use text as shelve message
11813 -n,--name <NAME>
11815 use the given name for the shelved commit
11816 -p, --patch
11818 show patch
11819 -i, --interactive
11821 interactive mode, only works while creating a shelve
11822 --stat output diffstat-style summary of changes
11824 -I,--include <PATTERN[+]>
11826 include names matching the given patterns
11827 -X,--exclude <PATTERN[+]>
11829 exclude names matching the given patterns
11830 [+] marked option can be specified multiple times
11832 unshelve
11834 restore a shelved change to the working directory:
11835 hg unshelve [[-n] SHELVED]
11837 This command accepts an optional name of a shelved change to restore.
11839 If none is given, the most recent shelved change is used.
11840 If a shelved change is applied successfully, the bundle that contains
11842 the shelved changes is moved to a backup location (.hg/shelve-backup).
11843 Since you can restore a shelved change on top of an arbitrary commit,
11845 it is possible that unshelving will result in a conflict between your
11846 changes and the commits you are unshelving onto. If this occurs, you
11847 must resolve the conflict, then use --continue to complete the unshelve
11848 operation. (The bundle will not be moved until you successfully com‐
11849 plete the unshelve.)
11850 (Alternatively, you can use --abort to abandon an unshelve that causes
11852 a conflict. This reverts the unshelved changes, and leaves the bundle
11853 in place.)
11854 If bare shelved change(when no files are specified, without interac‐
11856 tive, include and exclude option) was done on newly created branch it
11857 would restore branch information to the working directory.
11858 After a successful unshelve, the shelved changes are stored in a backup
11860 directory. Only the N most recent backups are kept. N defaults to 10
11861 but can be overridden using the shelve.maxbackups configuration option.
11862 Timestamp in seconds is used to decide order of backups. More than
11864 maxbackups backups are kept, if same timestamp prevents from deciding
11865 exact order of them, for safety.
11866 Options:
11868 -a, --abort
11870 abort an incomplete unshelve operation
11871 -c, --continue
11873 continue an incomplete unshelve operation
11874 -k, --keep
11876 keep shelve after unshelving
11877 -n,--name <NAME>
11879 restore shelved change with given name
11880 -t,--tool <VALUE>
11882 specify merge tool
11883 --date <DATE>
11885 set date for temporary commits (DEPRECATED)
11886 show
11888 unified command to show various repository information (EXPERIMENTAL)
11889 This extension provides the hg show command, which provides a central
11891 command for displaying commonly-accessed repository data and views of
11892 that data.
11893 The following config options can influence operation.
11895 commands
11897 show.aliasprefix
11898 List of strings that will register aliases for views. e.g. s
11900 will effectively set config options alias.s<view> = show <view>
11901 for all views. i.e. hg swork would execute hg show work.
11902 Aliases that would conflict with existing registrations will not
11904 be performed.
11905 Commands
11907 show
11908 show various repository information:
11909 hg show VIEW
11911 A requested view of repository data is displayed.
11913 If no view is requested, the list of available views is shown and the
11915 command aborts.
11916 Note There are no backwards compatibility guarantees for the output
11918 of this command. Output may change in any future Mercurial
11919 release.
11920 Consumers wanting stable command output should specify a tem‐
11922 plate via -T/--template.
11923 List of available views:
11925 bookmarks bookmarks and their associated changeset
11927 stack current line of work
11929 work changesets that aren't finished
11931 Options:
11933 -T,--template <TEMPLATE>
11935 display with template
11936 sparse
11938 allow sparse checkouts of the working directory (EXPERIMENTAL)
11939 (This extension is not yet protected by backwards compatibility guaran‐
11941 tees. Any aspect may break in future releases until this notice is
11942 removed.)
11943 This extension allows the working directory to only consist of a subset
11945 of files for the revision. This allows specific files or directories to
11946 be explicitly included or excluded. Many repository operations have
11947 performance proportional to the number of files in the working direc‐
11948 tory. So only realizing a subset of files in the working directory can
11949 improve performance.
11950 Sparse Config Files
11952 The set of files that are part of a sparse checkout are defined by a
11953 sparse config file. The file defines 3 things: includes (files to
11954 include in the sparse checkout), excludes (files to exclude from the
11955 sparse checkout), and profiles (links to other config files).
11956 The file format is newline delimited. Empty lines and lines beginning
11958 with # are ignored.
11959 Lines beginning with %include `` denote another sparse config file to
11961 include. e.g. ``%include tests.sparse. The filename is relative to the
11962 repository root.
11963 The special lines [include] and [exclude] denote the section for
11965 includes and excludes that follow, respectively. It is illegal to have
11966 [include] after [exclude].
11967 Non-special lines resemble file patterns to be added to either includes
11969 or excludes. The syntax of these lines is documented by hg help pat‐
11970 terns. Patterns are interpreted as glob: by default and match against
11971 the root of the repository.
11972 Exclusion patterns take precedence over inclusion patterns. So even if
11974 a file is explicitly included, an [exclude] entry can remove it.
11975 For example, say you have a repository with 3 directories, frontend/,
11977 backend/, and tools/. frontend/ and backend/ correspond to different
11978 projects and it is uncommon for someone working on one to need the
11979 files for the other. But tools/ contains files shared between both
11980 projects. Your sparse config files may resemble:
11981 # frontend.sparse
11983 frontend/**
11984 tools/**
11985 # backend.sparse
11987 backend/**
11988 tools/**
11989 Say the backend grows in size. Or there's a directory with thousands of
11991 files you wish to exclude. You can modify the profile to exclude cer‐
11992 tain files:
11993 [include]
11995 backend/**
11996 tools/**
11997 [exclude]
11999 tools/tests/**
12000 Commands
12002 split
12003 command to split a changeset into smaller ones (EXPERIMENTAL)
12004 Commands
12006 split
12007 split a changeset into smaller ones:
12008 hg split [--no-rebase] [[-r] REV]
12010 Repeatedly prompt changes and commit message for new changesets until
12012 there is nothing left in the original changeset.
12013 If --rev was not given, split the working directory parent.
12015 By default, rebase connected non-obsoleted descendants onto the new
12017 changeset. Use --no-rebase to avoid the rebase.
12018 Options:
12020 -r,--rev <REV>
12022 revision to split
12023 --rebase
12025 rebase descendants after split (default: True)
12026 -d,--date <DATE>
12028 record the specified date as commit date
12029 -u,--user <USER>
12031 record the specified user as committer
12032 strip
12034 strip changesets and their descendants from history
12035 This extension allows you to strip changesets and all their descendants
12037 from the repository. See the command help for details.
12038 Commands
12040 strip
12041 strip changesets and all their descendants from the repository:
12042 hg strip [-k] [-f] [-B bookmark] [-r] REV...
12044 The strip command removes the specified changesets and all their
12046 descendants. If the working directory has uncommitted changes, the
12047 operation is aborted unless the --force flag is supplied, in which case
12048 changes will be discarded.
12049 If a parent of the working directory is stripped, then the working
12051 directory will automatically be updated to the most recent available
12052 ancestor of the stripped parent after the operation completes.
12053 Any stripped changesets are stored in .hg/strip-backup as a bundle (see
12055 hg help bundle and hg help unbundle). They can be restored by running
12056 hg unbundle .hg/strip-backup/BUNDLE, where BUNDLE is the bundle file
12057 created by the strip. Note that the local revision numbers will in gen‐
12058 eral be different after the restore.
12059 Use the --no-backup option to discard the backup bundle once the opera‐
12061 tion completes.
12062 Strip is not a history-rewriting operation and can be used on change‐
12064 sets in the public phase. But if the stripped changesets have been
12065 pushed to a remote repository you will likely pull them again.
12066 Return 0 on success.
12068 Options:
12070 -r,--rev <REV[+]>
12072 strip specified revision (optional, can specify revisions with‐
12073 out this option)
12074 -f, --force
12076 force removal of changesets, discard uncommitted changes (no
12077 backup)
12078 --no-backup
12080 no backups
12081 --nobackup
12083 no backups (DEPRECATED)
12084 -n ignored (DEPRECATED)
12086 -k, --keep
12088 do not modify working directory during strip
12089 -B,--bookmark <VALUE[+]>
12091 remove revs only reachable from given bookmark
12092 [+] marked option can be specified multiple times
12094 transplant
12096 command to transplant changesets from another branch
12097 This extension allows you to transplant changes to another parent revi‐
12099 sion, possibly in another repository. The transplant is done using
12100 'diff' patches.
12101 Transplanted patches are recorded in .hg/transplant/transplants, as a
12103 map from a changeset hash to its hash in the source repository.
12104 Commands
12106 transplant
12107 transplant changesets from another branch:
12108 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
12110 Selected changesets will be applied on top of the current working
12112 directory with the log of the original changeset. The changesets are
12113 copied and will thus appear twice in the history with different identi‐
12114 ties.
12115 Consider using the graft command if everything is inside the same
12117 repository - it will use merges and will usually give a better result.
12118 Use the rebase extension if the changesets are unpublished and you want
12119 to move them instead of copying them.
12120 If --log is specified, log messages will have a comment appended of the
12122 form:
12123 (transplanted from CHANGESETHASH)
12125 You can rewrite the changelog message with the --filter option. Its
12127 argument will be invoked with the current changelog message as $1 and
12128 the patch as $2.
12129 --source/-s specifies another repository to use for selecting change‐
12131 sets, just as if it temporarily had been pulled. If --branch/-b is
12132 specified, these revisions will be used as heads when deciding which
12133 changesets to transplant, just as if only these revisions had been
12134 pulled. If --all/-a is specified, all the revisions up to the heads
12135 specified with --branch will be transplanted.
12136 Example:
12138 · transplant all changes up to REV on top of your current revision:
12140 hg transplant --branch REV --all
12142 You can optionally mark selected transplanted changesets as merge
12144 changesets. You will not be prompted to transplant any ancestors of a
12145 merged transplant, and you can merge descendants of them normally
12146 instead of transplanting them.
12147 Merge changesets may be transplanted directly by specifying the proper
12149 parent changeset by calling hg transplant --parent.
12150 If no merges or revisions are provided, hg transplant will start an
12152 interactive changeset browser.
12153 If a changeset application fails, you can fix the merge by hand and
12155 then resume where you left off by calling hg transplant --continue/-c.
12156 Options:
12158 -s,--source <REPO>
12160 transplant changesets from REPO
12161 -b,--branch <REV[+]>
12163 use this source changeset as head
12164 -a, --all
12166 pull all changesets up to the --branch revisions
12167 -p,--prune <REV[+]>
12169 skip over REV
12170 -m,--merge <REV[+]>
12172 merge at REV
12173 --parent <REV>
12175 parent to choose when transplanting merge
12176 -e, --edit
12178 invoke editor on commit messages
12179 --log append transplant info to log message
12181 -c, --continue
12183 continue last transplant session after fixing conflicts
12184 --filter <CMD>
12186 filter changesets through command
12187 [+] marked option can be specified multiple times
12189 uncommit
12191 uncommit part or all of a local changeset (EXPERIMENTAL)
12192 This command undoes the effect of a local commit, returning the
12194 affected files to their uncommitted state. This means that files modi‐
12195 fied, added or removed in the changeset will be left unchanged, and so
12196 will remain modified, added and removed in the working directory.
12197 Commands
12199 unamend
12200 undo the most recent amend operation on a current changeset:
12201 hg unamend
12203 This command will roll back to the previous version of a changeset,
12205 leaving working directory in state in which it was before running hg
12206 amend (e.g. files modified as part of an amend will be marked as modi‐
12207 fied hg status)
12208 uncommit
12210 uncommit part or all of a local changeset:
12211 hg uncommit [OPTION]... [FILE]...
12213 This command undoes the effect of a local commit, returning the
12215 affected files to their uncommitted state. This means that files modi‐
12216 fied or deleted in the changeset will be left unchanged, and so will
12217 remain modified in the working directory.
12218 Options:
12220 --keep allow an empty commit after uncommiting
12222 -I,--include <PATTERN[+]>
12224 include names matching the given patterns
12225 -X,--exclude <PATTERN[+]>
12227 exclude names matching the given patterns
12228 [+] marked option can be specified multiple times
12230 win32mbcs
12232 allow the use of MBCS paths with problematic encodings
12233 Some MBCS encodings are not good for some path operations (i.e. split‐
12235 ting path, case conversion, etc.) with its encoded bytes. We call such
12236 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
12237 extension can be used to fix the issue with those encodings by wrapping
12238 some functions to convert to Unicode string before path operation.
12239 This extension is useful for:
12241 · Japanese Windows users using shift_jis encoding.
12243 · Chinese Windows users using big5 encoding.
12245 · All users who use a repository with one of problematic encodings on
12247 case-insensitive file system.
12248 This extension is not needed for:
12250 · Any user who use only ASCII chars in path.
12252 · Any user who do not use any of problematic encodings.
12254 Note that there are some limitations on using this extension:
12256 · You should use single encoding in one repository.
12258 · If the repository path ends with 0x5c, .hg/hgrc cannot be read.
12260 · win32mbcs is not compatible with fixutf8 extension.
12262 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
12264 can specify the encoding by config option:
12265 [win32mbcs]
12267 encoding = sjis
12268 It is useful for the users who want to commit with UTF-8 log message.
12270 win32text
12272 perform automatic newline conversion (DEPRECATED)
12273 Deprecation: The win32text extension requires each user to configure
12275 the extension again and again for each clone since the configuration
12276 is not copied when cloning.
12277 We have therefore made the eol as an alternative. The eol uses a
12279 version controlled file for its configuration and each clone will
12280 therefore use the right settings from the start.
12281 To perform automatic newline conversion, use:
12283 [extensions]
12285 win32text =
12286 [encode]
12287 ** = cleverencode:
12288 # or ** = macencode:
12289 [decode]
12291 ** = cleverdecode:
12292 # or ** = macdecode:
12293 If not doing conversion, to make sure you do not commit CRLF/CR by
12295 accident:
12296 [hooks]
12298 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
12299 # or pretxncommit.cr = python:hgext.win32text.forbidcr
12300 To do the same check on a server to prevent CRLF/CR from being pushed
12302 or pulled:
12303 [hooks]
12305 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
12306 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
12307 zeroconf
12309 discover and advertise repositories on the local network
12310 Zeroconf-enabled repositories will be announced in a network without
12312 the need to configure a server or a service. They can be discovered
12313 without knowing their actual IP address.
12314 To allow other people to discover your repository using run hg serve in
12316 your repository:
12317 $ cd test
12319 $ hg serve
12320 You can discover Zeroconf-enabled repositories by running hg paths:
12322 $ hg paths
12324 zc-test = http://example.com:8000/test
12325
12327 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
12328 This file contains defaults and configuration. Values in
12330 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
12331 tings made in the global /etc/mercurial/hgrc configuration. See
12332 hgrc(5) for details of the contents and format of these files.
12333 .hgignore
12335 This file contains regular expressions (one per line) that
12337 describe file names that should be ignored by hg. For details,
12338 see hgignore(5).
12339 .hgsub
12341 This file defines the locations of all subrepositories, and
12343 tells where the subrepository checkouts came from. For details,
12344 see hg help subrepos.
12345 .hgsubstate
12347 This file is where Mercurial stores all nested repository
12349 states. NB: This file should not be edited manually.
12350 .hgtags
12352 This file contains changeset hash values and text tag names (one
12354 of each separated by spaces) that correspond to tagged versions
12355 of the repository contents. The file content is encoded using
12356 UTF-8.
12357 .hg/last-message.txt
12359 This file is used by hg commit to store a backup of the commit
12361 message in case the commit fails.
12362 .hg/localtags
12364 This file can be used to define local tags which are not shared
12366 among repositories. The file format is the same as for .hgtags,
12367 but it is encoded using the local system encoding.
12368 Some commands (e.g. revert) produce backup files ending in .orig, if
12370 the .orig file already exists and is not tracked by Mercurial, it will
12371 be overwritten.
12372
12374 Probably lots, please post them to the mailing list (see Resources
12375 below) when you find them.
12376
12378 hgignore(5), hgrc(5)
12379
12381 Written by Matt Mackall <mpm@selenic.com>
12382
12384 Main Web Site: https://mercurial-scm.org/
12385 Source code repository: https://www.mercurial-scm.org/repo/hg
12387 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
12389
12391 Copyright (C) 2005-2018 Matt Mackall. Free use of this software is
12392 granted under the terms of the GNU General Public License version 2 or
12393 any later version.
12394
12396 Matt Mackall <mpm@selenic.com>
12397 Organization: Mercurial
12399 HG(1)