1HG(1) Mercurial Manual HG(1)
2
3
4
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
20 path indicates a path on the local machine
21
22 revision
23 indicates a changeset which can be specified as a changeset re‐
24 vision number, a tag, or a unique substring of the changeset
25 hash value
26
27 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
35 --cwd <DIR>
36 change working directory
37
38 -y, --noninteractive
39 do not prompt, automatically pick the first choice for all
40 prompts
41
42 -q, --quiet
43 suppress output
44
45 -v, --verbose
46 enable additional output
47
48 --color <TYPE>
49 when to colorize (boolean, always, auto, never, or debug)
50
51 --config <CONFIG[+]>
52 set/override config option (use 'section.name=value')
53
54 --debug
55 enable debugging output
56
57 --debugger
58 start debugger
59
60 --encoding <ENCODE>
61 set the charset encoding (default: UTF-8)
62
63 --encodingmode <MODE>
64 set the charset encoding mode (default: strict)
65
66 --traceback
67 always print a traceback on exception
68
69 --time time how long the command takes
70
71 --profile
72 print command execution profile
73
74 --version
75 output version information and exit
76
77 -h, --help
78 display help and exit
79
80 --hidden
81 consider hidden changesets
82
83 --pager <TYPE>
84 when to paginate (boolean, always, auto, or never) (default:
85 auto)
86
87 [+] marked option can be specified multiple times
88
90 Repository creation
91 clone
92 make a copy of an existing repository:
93
94 hg clone [OPTION]... SOURCE [DEST]
95
96 Create a copy of an existing repository in a new directory.
97
98 If no destination directory name is specified, it defaults to the base‐
99 name of the source.
100
101 The location of the source is added to the new repository's .hg/hgrc
102 file, as the default to be used for future pulls.
103
104 Only local paths and ssh:// URLs are supported as destinations. For
105 ssh:// destinations, no working directory or .hg/hgrc will be created
106 on the remote side.
107
108 If the source repository has a bookmark called '@' set, that revision
109 will be checked out in the new repository by default.
110
111 To check out a particular version, use -u/--update, or -U/--noupdate to
112 create a clone with no working directory.
113
114 To pull only a subset of changesets, specify one or more revisions
115 identifiers with -r/--rev or branches with -b/--branch. The resulting
116 clone will contain only the specified changesets and their ancestors.
117 These options (or 'clone src#rev dest') imply --pull, even for local
118 source repositories.
119
120 In normal clone mode, the remote normalizes repository data into a com‐
121 mon exchange format and the receiving end translates this data into its
122 local storage format. --stream activates a different clone mode that
123 essentially copies repository files from the remote with minimal data
124 processing. This significantly reduces the CPU cost of a clone both re‐
125 motely and locally. However, it often increases the transferred data
126 size by 30-40%. This can result in substantially faster clones where
127 I/O throughput is plentiful, especially for larger repositories. A
128 side-effect of --stream clones is that storage settings and require‐
129 ments on the remote are applied locally: a modern client may inherit
130 legacy or inefficient storage used by the remote or a legacy Mercurial
131 client may not be able to clone from a modern Mercurial remote.
132
133 Note Specifying a tag will include the tagged changeset but not the
134 changeset containing the tag.
135
136 For efficiency, hardlinks are used for cloning whenever the source and
137 destination are on the same filesystem (note this applies only to the
138 repository data, not to the working directory). Some filesystems, such
139 as AFS, implement hardlinking incorrectly, but do not report errors. In
140 these cases, use the --pull option to avoid hardlinking.
141
142 Mercurial will update the working directory to the first applicable re‐
143 vision from this list:
144
145 a. null if -U or the source repository has no changesets
146
147 b. if -u . and the source repository is local, the first parent of the
148 source repository's working directory
149
150 c. the changeset specified with -u (if a branch name, this means the
151 latest head of that branch)
152
153 d. the changeset specified with -r
154
155 e. the tipmost head specified with -b
156
157 f. the tipmost head specified with the url#branch source syntax
158
159 g. the revision marked with the '@' bookmark, if present
160
161 h. the tipmost head of the default branch
162
163 i. tip
164
165 When cloning from servers that support it, Mercurial may fetch pre-gen‐
166 erated data from a server-advertised URL or inline from the same
167 stream. When this is done, hooks operating on incoming changesets and
168 changegroups may fire more than once, once for each pre-generated bun‐
169 dle and as well as for any additional remaining data. In addition, if
170 an error occurs, the repository may be rolled back to a partial clone.
171 This behavior may change in future releases. See hg help -e cloneb‐
172 undles for more.
173
174 Examples:
175
176 • clone a remote repository to a new directory named hg/:
177
178 hg clone https://www.mercurial-scm.org/repo/hg/
179
180 • create a lightweight local clone:
181
182 hg clone project/ project-feature/
183
184 • clone from an absolute path on an ssh server (note double-slash):
185
186 hg clone ssh://user@server//home/projects/alpha/
187
188 • do a streaming clone while checking out a specified version:
189
190 hg clone --stream http://server/repo -u 1.5
191
192 • create a repository without changesets after a particular revision:
193
194 hg clone -r 04e544 experimental/ good/
195
196 • clone (and track) a particular named branch:
197
198 hg clone https://www.mercurial-scm.org/repo/hg/#stable
199
200 See hg help urls for details on specifying URLs.
201
202 Returns 0 on success.
203
204 Options:
205
206 -U, --noupdate
207 the clone will include an empty working directory (only a repos‐
208 itory)
209
210 -u,--updaterev <REV>
211 revision, tag, or branch to check out
212
213 -r,--rev <REV[+]>
214 do not clone everything, but include this changeset and its an‐
215 cestors
216
217 -b,--branch <BRANCH[+]>
218 do not clone everything, but include this branch's changesets
219 and their ancestors
220
221 --pull use pull protocol to copy metadata
222
223 --uncompressed
224 an alias to --stream (DEPRECATED)
225
226 --stream
227 clone with minimal data processing
228
229 -e,--ssh <CMD>
230 specify ssh command to use
231
232 --remotecmd <CMD>
233 specify hg command to run on the remote side
234
235 --insecure
236 do not verify server certificate (ignoring web.cacerts config)
237
238 [+] marked option can be specified multiple times
239
240 init
241 create a new repository in the given directory:
242
243 hg init [-e CMD] [--remotecmd CMD] [DEST]
244
245 Initialize a new repository in the given directory. If the given direc‐
246 tory does not exist, it will be created.
247
248 If no directory is given, the current directory is used.
249
250 It is possible to specify an ssh:// URL as the destination. See hg
251 help urls for more information.
252
253 Returns 0 on success.
254
255 Options:
256
257 -e,--ssh <CMD>
258 specify ssh command to use
259
260 --remotecmd <CMD>
261 specify hg command to run on the remote side
262
263 --insecure
264 do not verify server certificate (ignoring web.cacerts config)
265
266 Remote repository management
267 incoming
268 show new changesets found in source:
269
270 hg incoming [-p] [-n] [-M] [-f] [-r REV]... [--bundle FILENAME] [SOURCE]
271
272 Show new changesets found in the specified path/URL or the default pull
273 location. These are the changesets that would have been pulled by hg
274 pull at the time you issued this command.
275
276 See pull for valid source format details.
277
278 With -B/--bookmarks, the result of bookmark comparison between local
279 and remote repositories is displayed. With -v/--verbose, status is also
280 displayed for each bookmark like below:
281
282 BM1 01234567890a added
283 BM2 1234567890ab advanced
284 BM3 234567890abc diverged
285 BM4 34567890abcd changed
286
287 The action taken locally when pulling depends on the status of each
288 bookmark:
289
290 added
291
292 pull will create it
293
294 advanced
295
296 pull will update it
297
298 diverged
299
300 pull will create a divergent bookmark
301
302 changed
303
304 result depends on remote changesets
305
306 From the point of view of pulling behavior, bookmark existing only in
307 the remote repository are treated as added, even if it is in fact lo‐
308 cally deleted.
309
310 For remote repository, using --bundle avoids downloading the changesets
311 twice if the incoming is followed by a pull.
312
313 Examples:
314
315 • show incoming changes with patches and full description:
316
317 hg incoming -vp
318
319 • show incoming changes excluding merges, store a bundle:
320
321 hg in -vpM --bundle incoming.hg
322 hg pull incoming.hg
323
324 • briefly list changes inside a bundle:
325
326 hg in changes.hg -T "{desc|firstline}\n"
327
328 Returns 0 if there are incoming changes, 1 otherwise.
329
330 Options:
331
332 -f, --force
333 run even if remote repository is unrelated
334
335 -n, --newest-first
336 show newest record first
337
338 --bundle <FILE>
339 file to store the bundles into
340
341 -r,--rev <REV[+]>
342 a remote changeset intended to be added
343
344 -B, --bookmarks
345 compare bookmarks
346
347 -b,--branch <BRANCH[+]>
348 a specific branch you would like to pull
349
350 -p, --patch
351 show patch
352
353 -g, --git
354 use git extended diff format
355
356 -l,--limit <NUM>
357 limit number of changes displayed
358
359 -M, --no-merges
360 do not show merges
361
362 --stat output diffstat-style summary of changes
363
364 -G, --graph
365 show the revision DAG
366
367 --style <STYLE>
368 display using template map file (DEPRECATED)
369
370 -T,--template <TEMPLATE>
371 display with template
372
373 -e,--ssh <CMD>
374 specify ssh command to use
375
376 --remotecmd <CMD>
377 specify hg command to run on the remote side
378
379 --insecure
380 do not verify server certificate (ignoring web.cacerts config)
381
382 -S, --subrepos
383 recurse into subrepositories
384
385 [+] marked option can be specified multiple times
386
387 aliases: in
388
389 outgoing
390 show changesets not found in the destination:
391
392 hg outgoing [-M] [-p] [-n] [-f] [-r REV]... [DEST]...
393
394 Show changesets not found in the specified destination repository or
395 the default push location. These are the changesets that would be
396 pushed if a push was requested.
397
398 See pull for details of valid destination formats.
399
400 With -B/--bookmarks, the result of bookmark comparison between local
401 and remote repositories is displayed. With -v/--verbose, status is also
402 displayed for each bookmark like below:
403
404 BM1 01234567890a added
405 BM2 deleted
406 BM3 234567890abc advanced
407 BM4 34567890abcd diverged
408 BM5 4567890abcde changed
409
410 The action taken when pushing depends on the status of each bookmark:
411
412 added
413
414 push with -B will create it
415
416 deleted
417
418 push with -B will delete it
419
420 advanced
421
422 push will update it
423
424 diverged
425
426 push with -B will update it
427
428 changed
429
430 push with -B will update it
431
432 From the point of view of pushing behavior, bookmarks existing only in
433 the remote repository are treated as deleted, even if it is in fact
434 added remotely.
435
436 Returns 0 if there are outgoing changes, 1 otherwise.
437
438 Options:
439
440 -f, --force
441 run even when the destination is unrelated
442
443 -r,--rev <REV[+]>
444 a changeset intended to be included in the destination
445
446 -n, --newest-first
447 show newest record first
448
449 -B, --bookmarks
450 compare bookmarks
451
452 -b,--branch <BRANCH[+]>
453 a specific branch you would like to push
454
455 -p, --patch
456 show patch
457
458 -g, --git
459 use git extended diff format
460
461 -l,--limit <NUM>
462 limit number of changes displayed
463
464 -M, --no-merges
465 do not show merges
466
467 --stat output diffstat-style summary of changes
468
469 -G, --graph
470 show the revision DAG
471
472 --style <STYLE>
473 display using template map file (DEPRECATED)
474
475 -T,--template <TEMPLATE>
476 display with template
477
478 -e,--ssh <CMD>
479 specify ssh command to use
480
481 --remotecmd <CMD>
482 specify hg command to run on the remote side
483
484 --insecure
485 do not verify server certificate (ignoring web.cacerts config)
486
487 -S, --subrepos
488 recurse into subrepositories
489
490 [+] marked option can be specified multiple times
491
492 aliases: out
493
494 paths
495 show aliases for remote repositories:
496
497 hg paths [NAME]
498
499 Show definition of symbolic path name NAME. If no name is given, show
500 definition of all available names.
501
502 Option -q/--quiet suppresses all output when searching for NAME and
503 shows only the path names when listing all definitions.
504
505 Path names are defined in the [paths] section of your configuration
506 file and in /etc/mercurial/hgrc. If run inside a repository, .hg/hgrc
507 is used, too.
508
509 The path names default and default-push have a special meaning. When
510 performing a push or pull operation, they are used as fallbacks if no
511 location is specified on the command-line. When default-push is set,
512 it will be used for push and default will be used for pull; otherwise
513 default is used as the fallback for both. When cloning a repository,
514 the clone source is written as default in .hg/hgrc.
515
516 Note default and default-push apply to all inbound (e.g. hg incoming
517 ) and outbound (e.g. hg outgoing, hg email and hg bundle) opera‐
518 tions.
519
520 See hg help urls for more information.
521
522 Template:
523
524 The following keywords are supported. See also hg help templates.
525
526 name String. Symbolic name of the path alias.
527
528 pushurl
529 String. URL for push operations.
530
531 url String. URL or directory path for the other operations.
532
533 Returns 0 on success.
534
535 Options:
536
537 -T,--template <TEMPLATE>
538 display with template
539
540 pull
541 pull changes from the specified source:
542
543 hg pull [-u] [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [SOURCE]...
544
545 Pull changes from a remote repository to a local one.
546
547 This finds all changes from the repository at the specified path or URL
548 and adds them to a local repository (the current one unless -R is spec‐
549 ified). By default, this does not update the copy of the project in the
550 working directory.
551
552 When cloning from servers that support it, Mercurial may fetch pre-gen‐
553 erated data. When this is done, hooks operating on incoming changesets
554 and changegroups may fire more than once, once for each pre-generated
555 bundle and as well as for any additional remaining data. See hg help -e
556 clonebundles for more.
557
558 Use hg incoming if you want to see what would have been added by a pull
559 at the time you issued this command. If you then decide to add those
560 changes to the repository, you should use hg pull -r X where X is the
561 last changeset listed by hg incoming.
562
563 If SOURCE is omitted, the 'default' path will be used. See hg help
564 urls for more information.
565
566 If multiple sources are specified, they will be pulled sequentially as
567 if the command was run multiple time. If --update is specify and the
568 command will stop at the first failed --update.
569
570 Specifying bookmark as . is equivalent to specifying the active book‐
571 mark's name.
572
573 Returns 0 on success, 1 if an update had unresolved files.
574
575 Options:
576
577 -u, --update
578 update to new branch head if new descendants were pulled
579
580 -f, --force
581 run even when remote repository is unrelated
582
583 --confirm
584 confirm pull before applying changes
585
586 -r,--rev <REV[+]>
587 a remote changeset intended to be added
588
589 -B,--bookmark <BOOKMARK[+]>
590 bookmark to pull
591
592 -b,--branch <BRANCH[+]>
593 a specific branch you would like to pull
594
595 -e,--ssh <CMD>
596 specify ssh command to use
597
598 --remotecmd <CMD>
599 specify hg command to run on the remote side
600
601 --insecure
602 do not verify server certificate (ignoring web.cacerts config)
603
604 [+] marked option can be specified multiple times
605
606 push
607 push changes to the specified destination:
608
609 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]...
610
611 Push changesets from the local repository to the specified destination.
612
613 This operation is symmetrical to pull: it is identical to a pull in the
614 destination repository from the current one.
615
616 By default, push will not allow creation of new heads at the destina‐
617 tion, since multiple heads would make it unclear which head to use. In
618 this situation, it is recommended to pull and merge before pushing.
619
620 Use --new-branch if you want to allow push to create a new named branch
621 that is not present at the destination. This allows you to only create
622 a new branch without forcing other changes.
623
624 Note Extra care should be taken with the -f/--force option, which
625 will push all new heads on all branches, an action which will
626 almost always cause confusion for collaborators.
627
628 If -r/--rev is used, the specified revision and all its ancestors will
629 be pushed to the remote repository.
630
631 If -B/--bookmark is used, the specified bookmarked revision, its ances‐
632 tors, and the bookmark will be pushed to the remote repository. Speci‐
633 fying . is equivalent to specifying the active bookmark's name. Use the
634 --all-bookmarks option for pushing all current bookmarks.
635
636 Please see hg help urls for important details about ssh:// URLs. If
637 DESTINATION is omitted, a default path will be used.
638
639 When passed multiple destinations, push will process them one after the
640 other, but stop should an error occur.
641
642 The --pushvars option sends strings to the server that become environ‐
643 ment variables prepended with HG_USERVAR_. For example, --pushvars EN‐
644 ABLE_FEATURE=true, provides the server side hooks with HG_USERVAR_EN‐
645 ABLE_FEATURE=true as part of their environment.
646
647 pushvars can provide for user-overridable hooks as well as set debug
648 levels. One example is having a hook that blocks commits containing
649 conflict markers, but enables the user to override the hook if the file
650 is using conflict markers for testing purposes or the file format has
651 strings that look like conflict markers.
652
653 By default, servers will ignore --pushvars. To enable it add the fol‐
654 lowing to your configuration file:
655
656 [push]
657 pushvars.server = true
658
659 Returns 0 if push was successful, 1 if nothing to push.
660
661 Options:
662
663 -f, --force
664 force push
665
666 -r,--rev <REV[+]>
667 a changeset intended to be included in the destination
668
669 -B,--bookmark <BOOKMARK[+]>
670 bookmark to push
671
672 --all-bookmarks
673 push all bookmarks (EXPERIMENTAL)
674
675 -b,--branch <BRANCH[+]>
676 a specific branch you would like to push
677
678 --new-branch
679 allow pushing a new branch
680
681 --pushvars <VALUE[+]>
682 variables that can be sent to server (ADVANCED)
683
684 --publish
685 push the changeset as public (EXPERIMENTAL)
686
687 -e,--ssh <CMD>
688 specify ssh command to use
689
690 --remotecmd <CMD>
691 specify hg command to run on the remote side
692
693 --insecure
694 do not verify server certificate (ignoring web.cacerts config)
695
696 [+] marked option can be specified multiple times
697
698 serve
699 start stand-alone webserver:
700
701 hg serve [OPTION]...
702
703 Start a local HTTP repository browser and pull server. You can use this
704 for ad-hoc sharing and browsing of repositories. It is recommended to
705 use a real web server to serve a repository for longer periods of time.
706
707 Please note that the server does not implement access control. This
708 means that, by default, anybody can read from the server and nobody can
709 write to it by default. Set the web.allow-push option to * to allow ev‐
710 erybody to push to the server. You should use a real web server if you
711 need to authenticate users.
712
713 By default, the server logs accesses to stdout and errors to stderr.
714 Use the -A/--accesslog and -E/--errorlog options to log to files.
715
716 To have the server choose a free port number to listen on, specify a
717 port number of 0; in this case, the server will print the port number
718 it uses.
719
720 Returns 0 on success.
721
722 Options:
723
724 -A,--accesslog <FILE>
725 name of access log file to write to
726
727 -d, --daemon
728 run server in background
729
730 --daemon-postexec <VALUE[+]>
731 used internally by daemon mode
732
733 -E,--errorlog <FILE>
734 name of error log file to write to
735
736 -p,--port <PORT>
737 port to listen on (default: 8000)
738
739 -a,--address <ADDR>
740 address to listen on (default: all interfaces)
741
742 --prefix <PREFIX>
743 prefix path to serve from (default: server root)
744
745 -n,--name <NAME>
746 name to show in web pages (default: working directory)
747
748 --web-conf <FILE>
749 name of the hgweb config file (see 'hg help hgweb')
750
751 --webdir-conf <FILE>
752 name of the hgweb config file (DEPRECATED)
753
754 --pid-file <FILE>
755 name of file to write process ID to
756
757 --stdio
758 for remote clients (ADVANCED)
759
760 --cmdserver <MODE>
761 for remote clients (ADVANCED)
762
763 -t,--templates <TEMPLATE>
764 web templates to use
765
766 --style <STYLE>
767 template style to use
768
769 -6, --ipv6
770 use IPv6 in addition to IPv4
771
772 --certificate <FILE>
773 SSL certificate file
774
775 --print-url
776 start and print only the URL
777
778 -S, --subrepos
779 recurse into subrepositories
780
781 [+] marked option can be specified multiple times
782
783 Change creation
784 commit
785 commit the specified files or all outstanding changes:
786
787 hg commit [OPTION]... [FILE]...
788
789 Commit changes to the given files into the repository. Unlike a cen‐
790 tralized SCM, this operation is a local operation. See hg push for a
791 way to actively distribute your changes.
792
793 If a list of files is omitted, all changes reported by hg status will
794 be committed.
795
796 If you are committing the result of a merge, do not provide any file‐
797 names or -I/-X filters.
798
799 If no commit message is specified, Mercurial starts your configured ed‐
800 itor where you can enter a message. In case your commit fails, you will
801 find a backup of your message in .hg/last-message.txt.
802
803 The --close-branch flag can be used to mark the current branch head
804 closed. When all heads of a branch are closed, the branch will be con‐
805 sidered closed and no longer listed.
806
807 The --amend flag can be used to amend the parent of the working direc‐
808 tory with a new commit that contains the changes in the parent in addi‐
809 tion to those currently reported by hg status, if there are any. The
810 old commit is stored in a backup bundle in .hg/strip-backup (see hg
811 help bundle and hg help unbundle on how to restore it).
812
813 Message, user and date are taken from the amended commit unless speci‐
814 fied. When a message isn't specified on the command line, the editor
815 will open with the message of the amended commit.
816
817 It is not possible to amend public changesets (see hg help phases) or
818 changesets that have children.
819
820 See hg help dates for a list of formats valid for -d/--date.
821
822 Returns 0 on success, 1 if nothing changed.
823
824 Examples:
825
826 • commit all files ending in .py:
827
828 hg commit --include "set:**.py"
829
830 • commit all non-binary files:
831
832 hg commit --exclude "set:binary()"
833
834 • amend the current commit and set the date to now:
835
836 hg commit --amend --date now
837
838 Options:
839
840 -A, --addremove
841 mark new/missing files as added/removed before committing
842
843 --close-branch
844 mark a branch head as closed
845
846 --amend
847 amend the parent of the working directory
848
849 -s, --secret
850 use the secret phase for committing
851
852 -e, --edit
853 invoke editor on commit messages
854
855 --force-close-branch
856 forcibly close branch from a non-head changeset (ADVANCED)
857
858 -i, --interactive
859 use interactive mode
860
861 -I,--include <PATTERN[+]>
862 include names matching the given patterns
863
864 -X,--exclude <PATTERN[+]>
865 exclude names matching the given patterns
866
867 -m,--message <TEXT>
868 use text as commit message
869
870 -l,--logfile <FILE>
871 read commit message from file
872
873 -d,--date <DATE>
874 record the specified date as commit date
875
876 -u,--user <USER>
877 record the specified user as committer
878
879 -S, --subrepos
880 recurse into subrepositories
881
882 [+] marked option can be specified multiple times
883
884 aliases: ci
885
886 Change manipulation
887 abort
888 abort an unfinished operation (EXPERIMENTAL):
889
890 hg abort
891
892 Aborts a multistep operation like graft, histedit, rebase, merge, and
893 unshelve if they are in an unfinished state.
894
895 use --dry-run/-n to dry run the command.
896
897 Options:
898
899 -n, --dry-run
900 do not perform actions, just print output
901
902 backout
903 reverse effect of earlier changeset:
904
905 hg backout [OPTION]... [-r] REV
906
907 Prepare a new changeset with the effect of REV undone in the current
908 working directory. If no conflicts were encountered, it will be commit‐
909 ted immediately.
910
911 If REV is the parent of the working directory, then this new changeset
912 is committed automatically (unless --no-commit is specified).
913
914 Note hg backout cannot be used to fix either an unwanted or incorrect
915 merge.
916
917 Examples:
918
919 • Reverse the effect of the parent of the working directory. This
920 backout will be committed immediately:
921
922 hg backout -r .
923
924 • Reverse the effect of previous bad revision 23:
925
926 hg backout -r 23
927
928 • Reverse the effect of previous bad revision 23 and leave changes un‐
929 committed:
930
931 hg backout -r 23 --no-commit
932 hg commit -m "Backout revision 23"
933
934 By default, the pending changeset will have one parent, maintaining a
935 linear history. With --merge, the pending changeset will instead have
936 two parents: the old parent of the working directory and a new child of
937 REV that simply undoes REV.
938
939 Before version 1.7, the behavior without --merge was equivalent to
940 specifying --merge followed by hg update --clean . to cancel the merge
941 and leave the child of REV as a head to be merged separately.
942
943 See hg help dates for a list of formats valid for -d/--date.
944
945 See hg help revert for a way to restore files to the state of another
946 revision.
947
948 Returns 0 on success, 1 if nothing to backout or there are unresolved
949 files.
950
951 Options:
952
953 --merge
954 merge with old dirstate parent after backout
955
956 --commit
957 commit if no conflicts were encountered (DEPRECATED)
958
959 --no-commit
960 do not commit
961
962 --parent <REV>
963 parent to choose when backing out merge (DEPRECATED)
964
965 -r,--rev <REV>
966 revision to backout
967
968 -e, --edit
969 invoke editor on commit messages
970
971 -t,--tool <TOOL>
972 specify merge tool
973
974 -I,--include <PATTERN[+]>
975 include names matching the given patterns
976
977 -X,--exclude <PATTERN[+]>
978 exclude names matching the given patterns
979
980 -m,--message <TEXT>
981 use text as commit message
982
983 -l,--logfile <FILE>
984 read commit message from file
985
986 -d,--date <DATE>
987 record the specified date as commit date
988
989 -u,--user <USER>
990 record the specified user as committer
991
992 [+] marked option can be specified multiple times
993
994 continue
995 resumes an interrupted operation (EXPERIMENTAL):
996
997 hg continue
998
999 Finishes a multistep operation like graft, histedit, rebase, merge, and
1000 unshelve if they are in an interrupted state.
1001
1002 use --dry-run/-n to dry run the command.
1003
1004 Options:
1005
1006 -n, --dry-run
1007 do not perform actions, just print output
1008
1009 graft
1010 copy changes from other branches onto the current branch:
1011
1012 hg graft [OPTION]... [-r REV]... REV...
1013
1014 This command uses Mercurial's merge logic to copy individual changes
1015 from other branches without merging branches in the history graph. This
1016 is sometimes known as 'backporting' or 'cherry-picking'. By default,
1017 graft will copy user, date, and description from the source changesets.
1018
1019 Changesets that are ancestors of the current revision, that have al‐
1020 ready been grafted, or that are merges will be skipped.
1021
1022 If --log is specified, log messages will have a comment appended of the
1023 form:
1024
1025 (grafted from CHANGESETHASH)
1026
1027 If --force is specified, revisions will be grafted even if they are al‐
1028 ready ancestors of, or have been grafted to, the destination. This is
1029 useful when the revisions have since been backed out.
1030
1031 If a graft merge results in conflicts, the graft process is interrupted
1032 so that the current merge can be manually resolved. Once all conflicts
1033 are addressed, the graft process can be continued with the -c/--con‐
1034 tinue option.
1035
1036 The -c/--continue option reapplies all the earlier options.
1037
1038 The --base option exposes more of how graft internally uses merge with
1039 a custom base revision. --base can be used to specify another ancestor
1040 than the first and only parent.
1041
1042 The command:
1043
1044 hg graft -r 345 --base 234
1045
1046 is thus pretty much the same as:
1047
1048 hg diff --from 234 --to 345 | hg import
1049
1050 but using merge to resolve conflicts and track moved files.
1051
1052 The result of a merge can thus be backported as a single commit by
1053 specifying one of the merge parents as base, and thus effectively
1054 grafting the changes from the other side.
1055
1056 It is also possible to collapse multiple changesets and clean up his‐
1057 tory by specifying another ancestor as base, much like rebase --col‐
1058 lapse --keep.
1059
1060 The commit message can be tweaked after the fact using commit --amend .
1061
1062 For using non-ancestors as the base to backout changes, see the backout
1063 command and the hidden --parent option.
1064
1065 Examples:
1066
1067 • copy a single change to the stable branch and edit its description:
1068
1069 hg update stable
1070 hg graft --edit 9393
1071
1072 • graft a range of changesets with one exception, updating dates:
1073
1074 hg graft -D "2085::2093 and not 2091"
1075
1076 • continue a graft after resolving conflicts:
1077
1078 hg graft -c
1079
1080 • show the source of a grafted changeset:
1081
1082 hg log --debug -r .
1083
1084 • show revisions sorted by date:
1085
1086 hg log -r "sort(all(), date)"
1087
1088 • backport the result of a merge as a single commit:
1089
1090 hg graft -r 123 --base 123^
1091
1092 • land a feature branch as one changeset:
1093
1094 hg up -cr default
1095 hg graft -r featureX --base "ancestor('featureX', 'default')"
1096
1097 See hg help revisions for more about specifying revisions.
1098
1099 Returns 0 on successful completion, 1 if there are unresolved files.
1100
1101 Options:
1102
1103 -r,--rev <REV[+]>
1104 revisions to graft
1105
1106 --base <REV>
1107 base revision when doing the graft merge (ADVANCED)
1108
1109 -c, --continue
1110 resume interrupted graft
1111
1112 --stop stop interrupted graft
1113
1114 --abort
1115 abort interrupted graft
1116
1117 -e, --edit
1118 invoke editor on commit messages
1119
1120 --log append graft info to log message
1121
1122 --no-commit
1123 don't commit, just apply the changes in working directory
1124
1125 -f, --force
1126 force graft
1127
1128 -D, --currentdate
1129 record the current date as commit date
1130
1131 -U, --currentuser
1132 record the current user as committer
1133
1134 -d,--date <DATE>
1135 record the specified date as commit date
1136
1137 -u,--user <USER>
1138 record the specified user as committer
1139
1140 -t,--tool <TOOL>
1141 specify merge tool
1142
1143 -n, --dry-run
1144 do not perform actions, just print output
1145
1146 [+] marked option can be specified multiple times
1147
1148 merge
1149 merge another revision into working directory:
1150
1151 hg merge [-P] [[-r] REV]
1152
1153 The current working directory is updated with all changes made in the
1154 requested revision since the last common predecessor revision.
1155
1156 Files that changed between either parent are marked as changed for the
1157 next commit and a commit must be performed before any further updates
1158 to the repository are allowed. The next commit will have two parents.
1159
1160 --tool can be used to specify the merge tool used for file merges. It
1161 overrides the HGMERGE environment variable and your configuration
1162 files. See hg help merge-tools for options.
1163
1164 If no revision is specified, the working directory's parent is a head
1165 revision, and the current branch contains exactly one other head, the
1166 other head is merged with by default. Otherwise, an explicit revision
1167 with which to merge must be provided.
1168
1169 See hg help resolve for information on handling file conflicts.
1170
1171 To undo an uncommitted merge, use hg merge --abort which will check out
1172 a clean copy of the original merge parent, losing all changes.
1173
1174 Returns 0 on success, 1 if there are unresolved files.
1175
1176 Options:
1177
1178 -f, --force
1179 force a merge including outstanding changes (DEPRECATED)
1180
1181 -r,--rev <REV>
1182 revision to merge
1183
1184 -P, --preview
1185 review revisions to merge (no merge is performed)
1186
1187 --abort
1188 abort the ongoing merge
1189
1190 -t,--tool <TOOL>
1191 specify merge tool
1192
1193 Change organization
1194 bookmarks
1195 create a new bookmark or list existing bookmarks:
1196
1197 hg bookmarks [OPTIONS]... [NAME]...
1198
1199 Bookmarks are labels on changesets to help track lines of development.
1200 Bookmarks are unversioned and can be moved, renamed and deleted.
1201 Deleting or moving a bookmark has no effect on the associated change‐
1202 sets.
1203
1204 Creating or updating to a bookmark causes it to be marked as 'active'.
1205 The active bookmark is indicated with a '*'. When a commit is made,
1206 the active bookmark will advance to the new commit. A plain hg update
1207 will also advance an active bookmark, if possible. Updating away from
1208 a bookmark will cause it to be deactivated.
1209
1210 Bookmarks can be pushed and pulled between repositories (see hg help
1211 push and hg help pull). If a shared bookmark has diverged, a new 'di‐
1212 vergent bookmark' of the form 'name@path' will be created. Using hg
1213 merge will resolve the divergence.
1214
1215 Specifying bookmark as '.' to -m/-d/-l options is equivalent to speci‐
1216 fying the active bookmark's name.
1217
1218 A bookmark named '@' has the special property that hg clone will check
1219 it out by default if it exists.
1220
1221 Template:
1222
1223 The following keywords are supported in addition to the common template
1224 keywords and functions such as {bookmark}. See also hg help templates.
1225
1226 active Boolean. True if the bookmark is active.
1227
1228 Examples:
1229
1230 • create an active bookmark for a new line of development:
1231
1232 hg book new-feature
1233
1234 • create an inactive bookmark as a place marker:
1235
1236 hg book -i reviewed
1237
1238 • create an inactive bookmark on another changeset:
1239
1240 hg book -r .^ tested
1241
1242 • rename bookmark turkey to dinner:
1243
1244 hg book -m turkey dinner
1245
1246 • move the '@' bookmark from another branch:
1247
1248 hg book -f @
1249
1250 • print only the active bookmark name:
1251
1252 hg book -ql .
1253
1254 Options:
1255
1256 -f, --force
1257 force
1258
1259 -r,--rev <REV>
1260 revision for bookmark action
1261
1262 -d, --delete
1263 delete a given bookmark
1264
1265 -m,--rename <OLD>
1266 rename a given bookmark
1267
1268 -i, --inactive
1269 mark a bookmark inactive
1270
1271 -l, --list
1272 list existing bookmarks
1273
1274 -T,--template <TEMPLATE>
1275 display with template
1276
1277 aliases: bookmark
1278
1279 branch
1280 set or show the current branch name:
1281
1282 hg branch [-fC] [NAME]
1283
1284 Note Branch names are permanent and global. Use hg bookmark to create
1285 a light-weight bookmark instead. See hg help glossary for more
1286 information about named branches and bookmarks.
1287
1288 With no argument, show the current branch name. With one argument, set
1289 the working directory branch name (the branch will not exist in the
1290 repository until the next commit). Standard practice recommends that
1291 primary development take place on the 'default' branch.
1292
1293 Unless -f/--force is specified, branch will not let you set a branch
1294 name that already exists.
1295
1296 Use -C/--clean to reset the working directory branch to that of the
1297 parent of the working directory, negating a previous branch change.
1298
1299 Use the command hg update to switch to an existing branch. Use hg com‐
1300 mit --close-branch to mark this branch head as closed. When all heads
1301 of a branch are closed, the branch will be considered closed.
1302
1303 Returns 0 on success.
1304
1305 Options:
1306
1307 -f, --force
1308 set branch name even if it shadows an existing branch
1309
1310 -C, --clean
1311 reset branch name to parent branch name
1312
1313 -r,--rev <VALUE[+]>
1314 change branches of the given revs (EXPERIMENTAL)
1315
1316 [+] marked option can be specified multiple times
1317
1318 branches
1319 list repository named branches:
1320
1321 hg branches [-c]
1322
1323 List the repository's named branches, indicating which ones are inac‐
1324 tive. If -c/--closed is specified, also list branches which have been
1325 marked closed (see hg commit --close-branch).
1326
1327 Use the command hg update to switch to an existing branch.
1328
1329 Template:
1330
1331 The following keywords are supported in addition to the common template
1332 keywords and functions such as {branch}. See also hg help templates.
1333
1334 active Boolean. True if the branch is active.
1335
1336 closed Boolean. True if the branch is closed.
1337
1338 current
1339 Boolean. True if it is the current branch.
1340
1341 Returns 0.
1342
1343 Options:
1344
1345 -a, --active
1346 show only branches that have unmerged heads (DEPRECATED)
1347
1348 -c, --closed
1349 show normal and closed branches
1350
1351 -r,--rev <VALUE[+]>
1352 show branch name(s) of the given rev
1353
1354 -T,--template <TEMPLATE>
1355 display with template
1356
1357 [+] marked option can be specified multiple times
1358
1359 phase
1360 set or show the current phase name:
1361
1362 hg phase [-p|-d|-s] [-f] [-r] [REV...]
1363
1364 With no argument, show the phase name of the current revision(s).
1365
1366 With one of -p/--public, -d/--draft or -s/--secret, change the phase
1367 value of the specified revisions.
1368
1369 Unless -f/--force is specified, hg phase won't move changesets from a
1370 lower phase to a higher phase. Phases are ordered as follows:
1371
1372 public < draft < secret
1373
1374 Returns 0 on success, 1 if some phases could not be changed.
1375
1376 (For more information about the phases concept, see hg help phases.)
1377
1378 Options:
1379
1380 -p, --public
1381 set changeset phase to public
1382
1383 -d, --draft
1384 set changeset phase to draft
1385
1386 -s, --secret
1387 set changeset phase to secret
1388
1389 -f, --force
1390 allow to move boundary backward
1391
1392 -r,--rev <REV[+]>
1393 target revision
1394
1395 [+] marked option can be specified multiple times
1396
1397 tag
1398 add one or more tags for the current or given revision:
1399
1400 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
1401
1402 Name a particular revision using <name>.
1403
1404 Tags are used to name particular revisions of the repository and are
1405 very useful to compare different revisions, to go back to significant
1406 earlier versions or to mark branch points as releases, etc. Changing an
1407 existing tag is normally disallowed; use -f/--force to override.
1408
1409 If no revision is given, the parent of the working directory is used.
1410
1411 To facilitate version control, distribution, and merging of tags, they
1412 are stored as a file named ".hgtags" which is managed similarly to
1413 other project files and can be hand-edited if necessary. This also
1414 means that tagging creates a new commit. The file ".hg/localtags" is
1415 used for local tags (not shared among repositories).
1416
1417 Tag commits are usually made at the head of a branch. If the parent of
1418 the working directory is not a branch head, hg tag aborts; use
1419 -f/--force to force the tag commit to be based on a non-head changeset.
1420
1421 See hg help dates for a list of formats valid for -d/--date.
1422
1423 Since tag names have priority over branch names during revision lookup,
1424 using an existing branch name as a tag name is discouraged.
1425
1426 Returns 0 on success.
1427
1428 Options:
1429
1430 -f, --force
1431 force tag
1432
1433 -l, --local
1434 make the tag local
1435
1436 -r,--rev <REV>
1437 revision to tag
1438
1439 --remove
1440 remove a tag
1441
1442 -e, --edit
1443 invoke editor on commit messages
1444
1445 -m,--message <TEXT>
1446 use text as commit message
1447
1448 -d,--date <DATE>
1449 record the specified date as commit date
1450
1451 -u,--user <USER>
1452 record the specified user as committer
1453
1454 tags
1455 list repository tags:
1456
1457 hg tags
1458
1459 This lists both regular and local tags. When the -v/--verbose switch is
1460 used, a third column "local" is printed for local tags. When the
1461 -q/--quiet switch is used, only the tag name is printed.
1462
1463 Template:
1464
1465 The following keywords are supported in addition to the common template
1466 keywords and functions such as {tag}. See also hg help templates.
1467
1468 type String. local for local tags.
1469
1470 Returns 0 on success.
1471
1472 Options:
1473
1474 -T,--template <TEMPLATE>
1475 display with template
1476
1477 File content management
1478 annotate
1479 show changeset information by line for each file:
1480
1481 hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...
1482
1483 List changes in files, showing the revision id responsible for each
1484 line.
1485
1486 This command is useful for discovering when a change was made and by
1487 whom.
1488
1489 If you include --file, --user, or --date, the revision number is sup‐
1490 pressed unless you also include --number.
1491
1492 Without the -a/--text option, annotate will avoid processing files it
1493 detects as binary. With -a, annotate will annotate the file anyway, al‐
1494 though the results will probably be neither useful nor desirable.
1495
1496 Template:
1497
1498 The following keywords are supported in addition to the common template
1499 keywords and functions. See also hg help templates.
1500
1501 lines List of lines with annotation data.
1502
1503 path String. Repository-absolute path of the specified file.
1504
1505 And each entry of {lines} provides the following sub-keywords in addi‐
1506 tion to {date}, {node}, {rev}, {user}, etc.
1507
1508 line String. Line content.
1509
1510 lineno Integer. Line number at that revision.
1511
1512 path String. Repository-absolute path of the file at that revision.
1513
1514 See hg help templates.operators for the list expansion syntax.
1515
1516 Returns 0 on success.
1517
1518 Options:
1519
1520 -r,--rev <REV>
1521 annotate the specified revision
1522
1523 --follow
1524 follow copies/renames and list the filename (DEPRECATED)
1525
1526 --no-follow
1527 don't follow copies and renames
1528
1529 -a, --text
1530 treat all files as text
1531
1532 -u, --user
1533 list the author (long with -v)
1534
1535 -f, --file
1536 list the filename
1537
1538 -d, --date
1539 list the date (short with -q)
1540
1541 -n, --number
1542 list the revision number (default)
1543
1544 -c, --changeset
1545 list the changeset
1546
1547 -l, --line-number
1548 show line number at the first appearance
1549
1550 --skip <REV[+]>
1551 revset to not display (EXPERIMENTAL)
1552
1553 -w, --ignore-all-space
1554 ignore white space when comparing lines
1555
1556 -b, --ignore-space-change
1557 ignore changes in the amount of white space
1558
1559 -B, --ignore-blank-lines
1560 ignore changes whose lines are all blank
1561
1562 -Z, --ignore-space-at-eol
1563 ignore changes in whitespace at EOL
1564
1565 -I,--include <PATTERN[+]>
1566 include names matching the given patterns
1567
1568 -X,--exclude <PATTERN[+]>
1569 exclude names matching the given patterns
1570
1571 -T,--template <TEMPLATE>
1572 display with template
1573
1574 [+] marked option can be specified multiple times
1575
1576 aliases: blame
1577
1578 cat
1579 output the current or given revision of files:
1580
1581 hg cat [OPTION]... FILE...
1582
1583 Print the specified files as they were at the given revision. If no re‐
1584 vision is given, the parent of the working directory is used.
1585
1586 Output may be to a file, in which case the name of the file is given
1587 using a template string. See hg help templates. In addition to the com‐
1588 mon template keywords, the following formatting rules are supported:
1589
1590 %%
1591
1592 literal "%" character
1593
1594 %s
1595
1596 basename of file being printed
1597
1598 %d
1599
1600 dirname of file being printed, or '.' if in repository root
1601
1602 %p
1603
1604 root-relative path name of file being printed
1605
1606 %H
1607
1608 changeset hash (40 hexadecimal digits)
1609
1610 %R
1611
1612 changeset revision number
1613
1614 %h
1615
1616 short-form changeset hash (12 hexadecimal digits)
1617
1618 %r
1619
1620 zero-padded changeset revision number
1621
1622 %b
1623
1624 basename of the exporting repository
1625
1626 \
1627
1628 literal "" character
1629
1630 Template:
1631
1632 The following keywords are supported in addition to the common template
1633 keywords and functions. See also hg help templates.
1634
1635 data String. File content.
1636
1637 path String. Repository-absolute path of the file.
1638
1639 Returns 0 on success.
1640
1641 Options:
1642
1643 -o,--output <FORMAT>
1644 print output to file with formatted name
1645
1646 -r,--rev <REV>
1647 print the given revision
1648
1649 --decode
1650 apply any matching decode filter
1651
1652 -I,--include <PATTERN[+]>
1653 include names matching the given patterns
1654
1655 -X,--exclude <PATTERN[+]>
1656 exclude names matching the given patterns
1657
1658 -T,--template <TEMPLATE>
1659 display with template
1660
1661 [+] marked option can be specified multiple times
1662
1663 copy
1664 mark files as copied for the next commit:
1665
1666 hg copy [OPTION]... (SOURCE... DEST | --forget DEST...)
1667
1668 Mark dest as having copies of source files. If dest is a directory,
1669 copies are put in that directory. If dest is a file, the source must be
1670 a single file.
1671
1672 By default, this command copies the contents of files as they exist in
1673 the working directory. If invoked with -A/--after, the operation is
1674 recorded, but no copying is performed.
1675
1676 To undo marking a destination file as copied, use --forget. With that
1677 option, all given (positional) arguments are unmarked as copies. The
1678 destination file(s) will be left in place (still tracked). Note that hg
1679 copy --forget behaves the same way as hg rename --forget.
1680
1681 This command takes effect with the next commit by default.
1682
1683 Returns 0 on success, 1 if errors are encountered.
1684
1685 Options:
1686
1687 --forget
1688 unmark a destination file as copied
1689
1690 -A, --after
1691 record a copy that has already occurred
1692
1693 --at-rev <REV>
1694 (un)mark copies in the given revision (EXPERIMENTAL)
1695
1696 -f, --force
1697 forcibly copy over an existing managed file
1698
1699 -I,--include <PATTERN[+]>
1700 include names matching the given patterns
1701
1702 -X,--exclude <PATTERN[+]>
1703 exclude names matching the given patterns
1704
1705 -n, --dry-run
1706 do not perform actions, just print output
1707
1708 [+] marked option can be specified multiple times
1709
1710 aliases: cp
1711
1712 diff
1713 diff repository (or selected files):
1714
1715 hg diff [OPTION]... ([-c REV] | [--from REV1] [--to REV2]) [FILE]...
1716
1717 Show differences between revisions for the specified files.
1718
1719 Differences between files are shown using the unified diff format.
1720
1721 Note hg diff may generate unexpected results for merges, as it will
1722 default to comparing against the working directory's first par‐
1723 ent changeset if no revisions are specified. To diff against
1724 the conflict regions, you can use --config diff.merge=yes.
1725
1726 By default, the working directory files are compared to its first par‐
1727 ent. To see the differences from another revision, use --from. To see
1728 the difference to another revision, use --to. For example, hg diff
1729 --from .^ will show the differences from the working copy's grandparent
1730 to the working copy, hg diff --to . will show the diff from the working
1731 copy to its parent (i.e. the reverse of the default), and hg diff
1732 --from 1.0 --to 1.2 will show the diff between those two revisions.
1733
1734 Alternatively you can specify -c/--change with a revision to see the
1735 changes in that changeset relative to its first parent (i.e. hg diff -c
1736 42 is equivalent to hg diff --from 42^ --to 42)
1737
1738 Without the -a/--text option, diff will avoid generating diffs of files
1739 it detects as binary. With -a, diff will generate a diff anyway, proba‐
1740 bly with undesirable results.
1741
1742 Use the -g/--git option to generate diffs in the git extended diff for‐
1743 mat. For more information, read hg help diffs.
1744
1745 Examples:
1746
1747 • compare a file in the current working directory to its parent:
1748
1749 hg diff foo.c
1750
1751 • compare two historical versions of a directory, with rename info:
1752
1753 hg diff --git --from 1.0 --to 1.2 lib/
1754
1755 • get change stats relative to the last change on some date:
1756
1757 hg diff --stat --from "date('may 2')"
1758
1759 • diff all newly-added files that contain a keyword:
1760
1761 hg diff "set:added() and grep(GNU)"
1762
1763 • compare a revision and its parents:
1764
1765 hg diff -c 9353 # compare against first parent
1766 hg diff --from 9353^ --to 9353 # same using revset syntax
1767 hg diff --from 9353^2 --to 9353 # compare against the second parent
1768
1769 Returns 0 on success.
1770
1771 Options:
1772
1773 -r,--rev <REV[+]>
1774 revision (DEPRECATED)
1775
1776 --from <REV1>
1777 revision to diff from
1778
1779 --to <REV2>
1780 revision to diff to
1781
1782 -c,--change <REV>
1783 change made by revision
1784
1785 -a, --text
1786 treat all files as text
1787
1788 -g, --git
1789 use git extended diff format (DEFAULT: diff.git)
1790
1791 --binary
1792 generate binary diffs in git mode (default)
1793
1794 --nodates
1795 omit dates from diff headers
1796
1797 --noprefix
1798 omit a/ and b/ prefixes from filenames
1799
1800 -p, --show-function
1801 show which function each change is in (DEFAULT: diff.showfunc)
1802
1803 --reverse
1804 produce a diff that undoes the changes
1805
1806 -w, --ignore-all-space
1807 ignore white space when comparing lines
1808
1809 -b, --ignore-space-change
1810 ignore changes in the amount of white space
1811
1812 -B, --ignore-blank-lines
1813 ignore changes whose lines are all blank
1814
1815 -Z, --ignore-space-at-eol
1816 ignore changes in whitespace at EOL
1817
1818 -U,--unified <NUM>
1819 number of lines of context to show
1820
1821 --stat output diffstat-style summary of changes
1822
1823 --root <DIR>
1824 produce diffs relative to subdirectory
1825
1826 -I,--include <PATTERN[+]>
1827 include names matching the given patterns
1828
1829 -X,--exclude <PATTERN[+]>
1830 exclude names matching the given patterns
1831
1832 -S, --subrepos
1833 recurse into subrepositories
1834
1835 [+] marked option can be specified multiple times
1836
1837 grep
1838 search for a pattern in specified files:
1839
1840 hg grep [--diff] [OPTION]... PATTERN [FILE]...
1841
1842 Search the working directory or revision history for a regular expres‐
1843 sion in the specified files for the entire repository.
1844
1845 By default, grep searches the repository files in the working directory
1846 and prints the files where it finds a match. To specify historical re‐
1847 visions instead of the working directory, use the --rev flag.
1848
1849 To search instead historical revision differences that contains a
1850 change in match status ("-" for a match that becomes a non-match, or
1851 "+" for a non-match that becomes a match), use the --diff flag.
1852
1853 PATTERN can be any Python (roughly Perl-compatible) regular expression.
1854
1855 If no FILEs are specified and the --rev flag isn't supplied, all files
1856 in the working directory are searched. When using the --rev flag and
1857 specifying FILEs, use the --follow argument to also follow the speci‐
1858 fied FILEs across renames and copies.
1859
1860 Template:
1861
1862 The following keywords are supported in addition to the common template
1863 keywords and functions. See also hg help templates.
1864
1865 change String. Character denoting insertion + or removal -. Available
1866 if --diff is specified.
1867
1868 lineno Integer. Line number of the match.
1869
1870 path String. Repository-absolute path of the file.
1871
1872 texts List of text chunks.
1873
1874 And each entry of {texts} provides the following sub-keywords.
1875
1876 matched
1877 Boolean. True if the chunk matches the specified pattern.
1878
1879 text String. Chunk content.
1880
1881 See hg help templates.operators for the list expansion syntax.
1882
1883 Returns 0 if a match is found, 1 otherwise.
1884
1885 Options:
1886
1887 -0, --print0
1888 end fields with NUL
1889
1890 --all an alias to --diff (DEPRECATED)
1891
1892 --diff search revision differences for when the pattern was added or
1893 removed
1894
1895 -a, --text
1896 treat all files as text
1897
1898 -f, --follow
1899 follow changeset history, or file history across copies and re‐
1900 names
1901
1902 -i, --ignore-case
1903 ignore case when matching
1904
1905 -l, --files-with-matches
1906 print only filenames and revisions that match
1907
1908 -n, --line-number
1909 print matching line numbers
1910
1911 -r,--rev <REV[+]>
1912 search files changed within revision range
1913
1914 --all-files
1915 include all files in the changeset while grepping (DEPRECATED)
1916
1917 -u, --user
1918 list the author (long with -v)
1919
1920 -d, --date
1921 list the date (short with -q)
1922
1923 -T,--template <TEMPLATE>
1924 display with template
1925
1926 -I,--include <PATTERN[+]>
1927 include names matching the given patterns
1928
1929 -X,--exclude <PATTERN[+]>
1930 exclude names matching the given patterns
1931
1932 [+] marked option can be specified multiple times
1933
1934 Change navigation
1935 bisect
1936 subdivision search of changesets:
1937
1938 hg bisect [-gbsr] [-U] [-c CMD] [REV]
1939
1940 This command helps to find changesets which introduce problems. To use,
1941 mark the earliest changeset you know exhibits the problem as bad, then
1942 mark the latest changeset which is free from the problem as good. Bi‐
1943 sect will update your working directory to a revision for testing (un‐
1944 less the -U/--noupdate option is specified). Once you have performed
1945 tests, mark the working directory as good or bad, and bisect will ei‐
1946 ther update to another candidate changeset or announce that it has
1947 found the bad revision.
1948
1949 As a shortcut, you can also use the revision argument to mark a revi‐
1950 sion as good or bad without checking it out first.
1951
1952 If you supply a command, it will be used for automatic bisection. The
1953 environment variable HG_NODE will contain the ID of the changeset being
1954 tested. The exit status of the command will be used to mark revisions
1955 as good or bad: status 0 means good, 125 means to skip the revision,
1956 127 (command not found) will abort the bisection, and any other
1957 non-zero exit status means the revision is bad.
1958
1959 Some examples:
1960
1961 • start a bisection with known bad revision 34, and good revision 12:
1962
1963 hg bisect --bad 34
1964 hg bisect --good 12
1965
1966 • advance the current bisection by marking current revision as good or
1967 bad:
1968
1969 hg bisect --good
1970 hg bisect --bad
1971
1972 • mark the current revision, or a known revision, to be skipped (e.g.
1973 if that revision is not usable because of another issue):
1974
1975 hg bisect --skip
1976 hg bisect --skip 23
1977
1978 • skip all revisions that do not touch directories foo or bar:
1979
1980 hg bisect --skip "!( file('path:foo') & file('path:bar') )"
1981
1982 • forget the current bisection:
1983
1984 hg bisect --reset
1985
1986 • use 'make && make tests' to automatically find the first broken revi‐
1987 sion:
1988
1989 hg bisect --reset
1990 hg bisect --bad 34
1991 hg bisect --good 12
1992 hg bisect --command "make && make tests"
1993
1994 • see all changesets whose states are already known in the current bi‐
1995 section:
1996
1997 hg log -r "bisect(pruned)"
1998
1999 • see the changeset currently being bisected (especially useful if run‐
2000 ning with -U/--noupdate):
2001
2002 hg log -r "bisect(current)"
2003
2004 • see all changesets that took part in the current bisection:
2005
2006 hg log -r "bisect(range)"
2007
2008 • you can even get a nice graph:
2009
2010 hg log --graph -r "bisect(range)"
2011
2012 See hg help revisions.bisect for more about the bisect() predicate.
2013
2014 Returns 0 on success.
2015
2016 Options:
2017
2018 -r, --reset
2019 reset bisect state
2020
2021 -g, --good
2022 mark changeset good
2023
2024 -b, --bad
2025 mark changeset bad
2026
2027 -s, --skip
2028 skip testing changeset
2029
2030 -e, --extend
2031 extend the bisect range
2032
2033 -c,--command <CMD>
2034 use command to check changeset state
2035
2036 -U, --noupdate
2037 do not update to target
2038
2039 heads
2040 show branch heads:
2041
2042 hg heads [-ct] [-r STARTREV] [REV]...
2043
2044 With no arguments, show all open branch heads in the repository.
2045 Branch heads are changesets that have no descendants on the same
2046 branch. They are where development generally takes place and are the
2047 usual targets for update and merge operations.
2048
2049 If one or more REVs are given, only open branch heads on the branches
2050 associated with the specified changesets are shown. This means that you
2051 can use hg heads . to see the heads on the currently checked-out
2052 branch.
2053
2054 If -c/--closed is specified, also show branch heads marked closed (see
2055 hg commit --close-branch).
2056
2057 If STARTREV is specified, only those heads that are descendants of
2058 STARTREV will be displayed.
2059
2060 If -t/--topo is specified, named branch mechanics will be ignored and
2061 only topological heads (changesets with no children) will be shown.
2062
2063 Returns 0 if matching heads are found, 1 if not.
2064
2065 Options:
2066
2067 -r,--rev <STARTREV>
2068 show only heads which are descendants of STARTREV
2069
2070 -t, --topo
2071 show topological heads only
2072
2073 -a, --active
2074 show active branchheads only (DEPRECATED)
2075
2076 -c, --closed
2077 show normal and closed branch heads
2078
2079 --style <STYLE>
2080 display using template map file (DEPRECATED)
2081
2082 -T,--template <TEMPLATE>
2083 display with template
2084
2085 identify
2086 identify the working directory or specified revision:
2087
2088 hg identify [-nibtB] [-r REV] [SOURCE]
2089
2090 Print a summary identifying the repository state at REV using one or
2091 two parent hash identifiers, followed by a "+" if the working directory
2092 has uncommitted changes, the branch name (if not default), a list of
2093 tags, and a list of bookmarks.
2094
2095 When REV is not given, print a summary of the current state of the
2096 repository including the working directory. Specify -r. to get informa‐
2097 tion of the working directory parent without scanning uncommitted
2098 changes.
2099
2100 Specifying a path to a repository root or Mercurial bundle will cause
2101 lookup to operate on that repository/bundle.
2102
2103 Template:
2104
2105 The following keywords are supported in addition to the common template
2106 keywords and functions. See also hg help templates.
2107
2108 dirty String. Character + denoting if the working directory has uncom‐
2109 mitted changes.
2110
2111 id String. One or two nodes, optionally followed by +.
2112
2113 parents
2114 List of strings. Parent nodes of the changeset.
2115
2116 Examples:
2117
2118 • generate a build identifier for the working directory:
2119
2120 hg id --id > build-id.dat
2121
2122 • find the revision corresponding to a tag:
2123
2124 hg id -n -r 1.3
2125
2126 • check the most recent revision of a remote repository:
2127
2128 hg id -r tip https://www.mercurial-scm.org/repo/hg/
2129
2130 See hg log for generating more information about specific revisions,
2131 including full hash identifiers.
2132
2133 Returns 0 if successful.
2134
2135 Options:
2136
2137 -r,--rev <REV>
2138 identify the specified revision
2139
2140 -n, --num
2141 show local revision number
2142
2143 -i, --id
2144 show global revision id
2145
2146 -b, --branch
2147 show branch
2148
2149 -t, --tags
2150 show tags
2151
2152 -B, --bookmarks
2153 show bookmarks
2154
2155 -e,--ssh <CMD>
2156 specify ssh command to use
2157
2158 --remotecmd <CMD>
2159 specify hg command to run on the remote side
2160
2161 --insecure
2162 do not verify server certificate (ignoring web.cacerts config)
2163
2164 -T,--template <TEMPLATE>
2165 display with template
2166
2167 aliases: id
2168
2169 log
2170 show revision history of entire repository or files:
2171
2172 hg log [OPTION]... [FILE]
2173
2174 Print the revision history of the specified files or the entire
2175 project.
2176
2177 If no revision range is specified, the default is tip:0 unless --follow
2178 is set.
2179
2180 File history is shown without following rename or copy history of
2181 files. Use -f/--follow with a filename to follow history across renames
2182 and copies. --follow without a filename will only show ancestors of the
2183 starting revisions. The starting revisions can be specified by
2184 -r/--rev, which default to the working directory parent.
2185
2186 By default this command prints revision number and changeset id, tags,
2187 non-trivial parents, user, date and time, and a summary for each com‐
2188 mit. When the -v/--verbose switch is used, the list of changed files
2189 and full commit message are shown.
2190
2191 With --graph the revisions are shown as an ASCII art DAG with the most
2192 recent changeset at the top. 'o' is a changeset, '@' is a working di‐
2193 rectory parent, '%' is a changeset involved in an unresolved merge con‐
2194 flict, '_' closes a branch, 'x' is obsolete, '*' is unstable, and '+'
2195 represents a fork where the changeset from the lines below is a parent
2196 of the 'o' merge on the same line. Paths in the DAG are represented
2197 with '|', '/' and so forth. ':' in place of a '|' indicates one or more
2198 revisions in a path are omitted.
2199
2200 Use -L/--line-range FILE,M:N options to follow the history of lines
2201 from M to N in FILE. With -p/--patch only diff hunks affecting speci‐
2202 fied line range will be shown. This option requires --follow; it can be
2203 specified multiple times. Currently, this option is not compatible with
2204 --graph. This option is experimental.
2205
2206 Note hg log --patch may generate unexpected diff output for merge
2207 changesets, as it will only compare the merge changeset against
2208 its first parent. Also, only files different from BOTH parents
2209 will appear in files:.
2210
2211 Note For performance reasons, hg log FILE may omit duplicate changes
2212 made on branches and will not show removals or mode changes. To
2213 see all such changes, use the --removed switch.
2214
2215 Note The history resulting from -L/--line-range options depends on
2216 diff options; for instance if white-spaces are ignored, respec‐
2217 tive changes with only white-spaces in specified line range will
2218 not be listed.
2219
2220 Some examples:
2221
2222 • changesets with full descriptions and file lists:
2223
2224 hg log -v
2225
2226 • changesets ancestral to the working directory:
2227
2228 hg log -f
2229
2230 • last 10 commits on the current branch:
2231
2232 hg log -l 10 -b .
2233
2234 • changesets showing all modifications of a file, including removals:
2235
2236 hg log --removed file.c
2237
2238 • all changesets that touch a directory, with diffs, excluding merges:
2239
2240 hg log -Mp lib/
2241
2242 • all revision numbers that match a keyword:
2243
2244 hg log -k bug --template "{rev}\n"
2245
2246 • the full hash identifier of the working directory parent:
2247
2248 hg log -r . --template "{node}\n"
2249
2250 • list available log templates:
2251
2252 hg log -T list
2253
2254 • check if a given changeset is included in a tagged release:
2255
2256 hg log -r "a21ccf and ancestor(1.9)"
2257
2258 • find all changesets by some user in a date range:
2259
2260 hg log -k alice -d "may 2008 to jul 2008"
2261
2262 • summary of all changesets after the last tag:
2263
2264 hg log -r "last(tagged())::" --template "{desc|firstline}\n"
2265
2266 • changesets touching lines 13 to 23 for file.c:
2267
2268 hg log -L file.c,13:23
2269
2270 • changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2271 main.c with patch:
2272
2273 hg log -L file.c,13:23 -L main.c,2:6 -p
2274
2275 See hg help dates for a list of formats valid for -d/--date.
2276
2277 See hg help revisions for more about specifying and ordering revisions.
2278
2279 See hg help templates for more about pre-packaged styles and specifying
2280 custom templates. The default template used by the log command can be
2281 customized via the command-templates.log configuration setting.
2282
2283 Returns 0 on success.
2284
2285 Options:
2286
2287 -f, --follow
2288 follow changeset history, or file history across copies and re‐
2289 names
2290
2291 --follow-first
2292 only follow the first parent of merge changesets (DEPRECATED)
2293
2294 -d,--date <DATE>
2295 show revisions matching date spec
2296
2297 -C, --copies
2298 show copied files
2299
2300 -k,--keyword <TEXT[+]>
2301 do case-insensitive search for a given text
2302
2303 -r,--rev <REV[+]>
2304 revisions to select or follow from
2305
2306 -L,--line-range <FILE,RANGE[+]>
2307 follow line range of specified file (EXPERIMENTAL)
2308
2309 --removed
2310 include revisions where files were removed
2311
2312 -m, --only-merges
2313 show only merges (DEPRECATED) (use -r "merge()" instead)
2314
2315 -u,--user <USER[+]>
2316 revisions committed by user
2317
2318 --only-branch <BRANCH[+]>
2319 show only changesets within the given named branch (DEPRECATED)
2320
2321 -b,--branch <BRANCH[+]>
2322 show changesets within the given named branch
2323
2324 -B,--bookmark <BOOKMARK[+]>
2325 show changesets within the given bookmark
2326
2327 -P,--prune <REV[+]>
2328 do not display revision or any of its ancestors
2329
2330 -p, --patch
2331 show patch
2332
2333 -g, --git
2334 use git extended diff format
2335
2336 -l,--limit <NUM>
2337 limit number of changes displayed
2338
2339 -M, --no-merges
2340 do not show merges
2341
2342 --stat output diffstat-style summary of changes
2343
2344 -G, --graph
2345 show the revision DAG
2346
2347 --style <STYLE>
2348 display using template map file (DEPRECATED)
2349
2350 -T,--template <TEMPLATE>
2351 display with template
2352
2353 -I,--include <PATTERN[+]>
2354 include names matching the given patterns
2355
2356 -X,--exclude <PATTERN[+]>
2357 exclude names matching the given patterns
2358
2359 [+] marked option can be specified multiple times
2360
2361 aliases: history
2362
2363 parents
2364 show the parents of the working directory or revision (DEPRECATED):
2365
2366 hg parents [-r REV] [FILE]
2367
2368 Print the working directory's parent revisions. If a revision is given
2369 via -r/--rev, the parent of that revision will be printed. If a file
2370 argument is given, the revision in which the file was last changed (be‐
2371 fore the working directory revision or the argument to --rev if given)
2372 is printed.
2373
2374 This command is equivalent to:
2375
2376 hg log -r "p1()+p2()" or
2377 hg log -r "p1(REV)+p2(REV)" or
2378 hg log -r "max(::p1() and file(FILE))+max(::p2() and file(FILE))" or
2379 hg log -r "max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))"
2380
2381 See hg summary and hg help revsets for related information.
2382
2383 Returns 0 on success.
2384
2385 Options:
2386
2387 -r,--rev <REV>
2388 show parents of the specified revision
2389
2390 --style <STYLE>
2391 display using template map file (DEPRECATED)
2392
2393 -T,--template <TEMPLATE>
2394 display with template
2395
2396 tip
2397 show the tip revision (DEPRECATED):
2398
2399 hg tip [-p] [-g]
2400
2401 The tip revision (usually just called the tip) is the changeset most
2402 recently added to the repository (and therefore the most recently
2403 changed head).
2404
2405 If you have just made a commit, that commit will be the tip. If you
2406 have just pulled changes from another repository, the tip of that
2407 repository becomes the current tip. The "tip" tag is special and cannot
2408 be renamed or assigned to a different changeset.
2409
2410 This command is deprecated, please use hg heads instead.
2411
2412 Returns 0 on success.
2413
2414 Options:
2415
2416 -p, --patch
2417 show patch
2418
2419 -g, --git
2420 use git extended diff format
2421
2422 --style <STYLE>
2423 display using template map file (DEPRECATED)
2424
2425 -T,--template <TEMPLATE>
2426 display with template
2427
2428 Working directory management
2429 add
2430 add the specified files on the next commit:
2431
2432 hg add [OPTION]... [FILE]...
2433
2434 Schedule files to be version controlled and added to the repository.
2435
2436 The files will be added to the repository at the next commit. To undo
2437 an add before that, see hg forget.
2438
2439 If no names are given, add all files to the repository (except files
2440 matching .hgignore).
2441
2442 Examples:
2443
2444 • New (unknown) files are added automatically by hg add:
2445
2446 $ ls
2447 foo.c
2448 $ hg status
2449 ? foo.c
2450 $ hg add
2451 adding foo.c
2452 $ hg status
2453 A foo.c
2454
2455 • Specific files to be added can be specified:
2456
2457 $ ls
2458 bar.c foo.c
2459 $ hg status
2460 ? bar.c
2461 ? foo.c
2462 $ hg add bar.c
2463 $ hg status
2464 A bar.c
2465 ? foo.c
2466
2467 Returns 0 if all files are successfully added.
2468
2469 Options:
2470
2471 -I,--include <PATTERN[+]>
2472 include names matching the given patterns
2473
2474 -X,--exclude <PATTERN[+]>
2475 exclude names matching the given patterns
2476
2477 -S, --subrepos
2478 recurse into subrepositories
2479
2480 -n, --dry-run
2481 do not perform actions, just print output
2482
2483 [+] marked option can be specified multiple times
2484
2485 addremove
2486 add all new files, delete all missing files:
2487
2488 hg addremove [OPTION]... [FILE]...
2489
2490 Add all new files and remove all missing files from the repository.
2491
2492 Unless names are given, new files are ignored if they match any of the
2493 patterns in .hgignore. As with add, these changes take effect at the
2494 next commit.
2495
2496 Use the -s/--similarity option to detect renamed files. This option
2497 takes a percentage between 0 (disabled) and 100 (files must be identi‐
2498 cal) as its parameter. With a parameter greater than 0, this compares
2499 every removed file with every added file and records those similar
2500 enough as renames. Detecting renamed files this way can be expensive.
2501 After using this option, hg status -C can be used to check which files
2502 were identified as moved or renamed. If not specified, -s/--similarity
2503 defaults to 100 and only renames of identical files are detected.
2504
2505 Examples:
2506
2507 • A number of files (bar.c and foo.c) are new, while foobar.c has
2508 been removed (without using hg remove) from the repository:
2509
2510 $ ls
2511 bar.c foo.c
2512 $ hg status
2513 ! foobar.c
2514 ? bar.c
2515 ? foo.c
2516 $ hg addremove
2517 adding bar.c
2518 adding foo.c
2519 removing foobar.c
2520 $ hg status
2521 A bar.c
2522 A foo.c
2523 R foobar.c
2524
2525 • A file foobar.c was moved to foo.c without using hg rename. Af‐
2526 terwards, it was edited slightly:
2527
2528 $ ls
2529 foo.c
2530 $ hg status
2531 ! foobar.c
2532 ? foo.c
2533 $ hg addremove --similarity 90
2534 removing foobar.c
2535 adding foo.c
2536 recording removal of foobar.c as rename to foo.c (94% similar)
2537 $ hg status -C
2538 A foo.c
2539 foobar.c
2540 R foobar.c
2541
2542 Returns 0 if all files are successfully added.
2543
2544 Options:
2545
2546 -s,--similarity <SIMILARITY>
2547 guess renamed files by similarity (0<=s<=100)
2548
2549 -S, --subrepos
2550 recurse into subrepositories
2551
2552 -I,--include <PATTERN[+]>
2553 include names matching the given patterns
2554
2555 -X,--exclude <PATTERN[+]>
2556 exclude names matching the given patterns
2557
2558 -n, --dry-run
2559 do not perform actions, just print output
2560
2561 [+] marked option can be specified multiple times
2562
2563 files
2564 list tracked files:
2565
2566 hg files [OPTION]... [FILE]...
2567
2568 Print files under Mercurial control in the working directory or speci‐
2569 fied revision for given files (excluding removed files). Files can be
2570 specified as filenames or filesets.
2571
2572 If no files are given to match, this command prints the names of all
2573 files under Mercurial control.
2574
2575 Template:
2576
2577 The following keywords are supported in addition to the common template
2578 keywords and functions. See also hg help templates.
2579
2580 flags String. Character denoting file's symlink and executable bits.
2581
2582 path String. Repository-absolute path of the file.
2583
2584 size Integer. Size of the file in bytes.
2585
2586 Examples:
2587
2588 • list all files under the current directory:
2589
2590 hg files .
2591
2592 • shows sizes and flags for current revision:
2593
2594 hg files -vr .
2595
2596 • list all files named README:
2597
2598 hg files -I "**/README"
2599
2600 • list all binary files:
2601
2602 hg files "set:binary()"
2603
2604 • find files containing a regular expression:
2605
2606 hg files "set:grep('bob')"
2607
2608 • search tracked file contents with xargs and grep:
2609
2610 hg files -0 | xargs -0 grep foo
2611
2612 See hg help patterns and hg help filesets for more information on spec‐
2613 ifying file patterns.
2614
2615 Returns 0 if a match is found, 1 otherwise.
2616
2617 Options:
2618
2619 -r,--rev <REV>
2620 search the repository as it is in REV
2621
2622 -0, --print0
2623 end filenames with NUL, for use with xargs
2624
2625 -I,--include <PATTERN[+]>
2626 include names matching the given patterns
2627
2628 -X,--exclude <PATTERN[+]>
2629 exclude names matching the given patterns
2630
2631 -T,--template <TEMPLATE>
2632 display with template
2633
2634 -S, --subrepos
2635 recurse into subrepositories
2636
2637 [+] marked option can be specified multiple times
2638
2639 forget
2640 forget the specified files on the next commit:
2641
2642 hg forget [OPTION]... FILE...
2643
2644 Mark the specified files so they will no longer be tracked after the
2645 next commit.
2646
2647 This only removes files from the current branch, not from the entire
2648 project history, and it does not delete them from the working direc‐
2649 tory.
2650
2651 To delete the file from the working directory, see hg remove.
2652
2653 To undo a forget before the next commit, see hg add.
2654
2655 Examples:
2656
2657 • forget newly-added binary files:
2658
2659 hg forget "set:added() and binary()"
2660
2661 • forget files that would be excluded by .hgignore:
2662
2663 hg forget "set:hgignore()"
2664
2665 Returns 0 on success.
2666
2667 Options:
2668
2669 -i, --interactive
2670 use interactive mode
2671
2672 -I,--include <PATTERN[+]>
2673 include names matching the given patterns
2674
2675 -X,--exclude <PATTERN[+]>
2676 exclude names matching the given patterns
2677
2678 -n, --dry-run
2679 do not perform actions, just print output
2680
2681 [+] marked option can be specified multiple times
2682
2683 locate
2684 locate files matching specific patterns (DEPRECATED):
2685
2686 hg locate [OPTION]... [PATTERN]...
2687
2688 Print files under Mercurial control in the working directory whose
2689 names match the given patterns.
2690
2691 By default, this command searches all directories in the working direc‐
2692 tory. To search just the current directory and its subdirectories, use
2693 "--include .".
2694
2695 If no patterns are given to match, this command prints the names of all
2696 files under Mercurial control in the working directory.
2697
2698 If you want to feed the output of this command into the "xargs" com‐
2699 mand, use the -0 option to both this command and "xargs". This will
2700 avoid the problem of "xargs" treating single filenames that contain
2701 whitespace as multiple filenames.
2702
2703 See hg help files for a more versatile command.
2704
2705 Returns 0 if a match is found, 1 otherwise.
2706
2707 Options:
2708
2709 -r,--rev <REV>
2710 search the repository as it is in REV
2711
2712 -0, --print0
2713 end filenames with NUL, for use with xargs
2714
2715 -f, --fullpath
2716 print complete paths from the filesystem root
2717
2718 -I,--include <PATTERN[+]>
2719 include names matching the given patterns
2720
2721 -X,--exclude <PATTERN[+]>
2722 exclude names matching the given patterns
2723
2724 [+] marked option can be specified multiple times
2725
2726 purge
2727 removes files not tracked by Mercurial:
2728
2729 hg purge [OPTION]... [DIR]...
2730
2731 Delete files not known to Mercurial. This is useful to test local and
2732 uncommitted changes in an otherwise-clean source tree.
2733
2734 This means that purge will delete the following by default:
2735
2736 • Unknown files: files marked with "?" by hg status
2737
2738 • Empty directories: in fact Mercurial ignores directories unless they
2739 contain files under source control management
2740
2741 But it will leave untouched:
2742
2743 • Modified and unmodified tracked files
2744
2745 • Ignored files (unless -i or --all is specified)
2746
2747 • New files added to the repository (with hg add)
2748
2749 The --files and --dirs options can be used to direct purge to delete
2750 only files, only directories, or both. If neither option is given, both
2751 will be deleted.
2752
2753 If directories are given on the command line, only files in these di‐
2754 rectories are considered.
2755
2756 Be careful with purge, as you could irreversibly delete some files you
2757 forgot to add to the repository. If you only want to print the list of
2758 files that this program would delete, use the --print option.
2759
2760 Options:
2761
2762 -a, --abort-on-err
2763 abort if an error occurs
2764
2765 --all purge ignored files too
2766
2767 -i, --ignored
2768 purge only ignored files
2769
2770 --dirs purge empty directories
2771
2772 --files
2773 purge files
2774
2775 -p, --print
2776 print filenames instead of deleting them
2777
2778 -0, --print0
2779 end filenames with NUL, for use with xargs (implies -p/--print)
2780
2781 --confirm
2782 ask before permanently deleting files
2783
2784 -I,--include <PATTERN[+]>
2785 include names matching the given patterns
2786
2787 -X,--exclude <PATTERN[+]>
2788 exclude names matching the given patterns
2789
2790 [+] marked option can be specified multiple times
2791
2792 aliases: clean
2793
2794 remove
2795 remove the specified files on the next commit:
2796
2797 hg remove [OPTION]... FILE...
2798
2799 Schedule the indicated files for removal from the current branch.
2800
2801 This command schedules the files to be removed at the next commit. To
2802 undo a remove before that, see hg revert. To undo added files, see hg
2803 forget.
2804
2805 -A/--after can be used to remove only files that have already been
2806 deleted, -f/--force can be used to force deletion, and -Af can be used
2807 to remove files from the next revision without deleting them from the
2808 working directory.
2809
2810 The following table details the behavior of remove for different file
2811 states (columns) and option combinations (rows). The file states are
2812 Added [A], Clean [C], Modified [M] and Missing [!] (as reported by hg
2813 status). The actions are Warn, Remove (from branch) and Delete (from
2814 disk):
2815
2816 ┌──────────┬───┬────┬────┬───┐
2817 │opt/state │ A │ C │ M │ ! │
2818 ├──────────┼───┼────┼────┼───┤
2819 │none │ W │ RD │ W │ R │
2820 ├──────────┼───┼────┼────┼───┤
2821 │-f │ R │ RD │ RD │ R │
2822 ├──────────┼───┼────┼────┼───┤
2823 │-A │ W │ W │ W │ R │
2824 ├──────────┼───┼────┼────┼───┤
2825 │-Af │ R │ R │ R │ R │
2826 └──────────┴───┴────┴────┴───┘
2827
2828 Note hg remove never deletes files in Added [A] state from the work‐
2829 ing directory, not even if --force is specified.
2830
2831 Returns 0 on success, 1 if any warnings encountered.
2832
2833 Options:
2834
2835 -A, --after
2836 record delete for missing files
2837
2838 -f, --force
2839 forget added files, delete modified files
2840
2841 -S, --subrepos
2842 recurse into subrepositories
2843
2844 -I,--include <PATTERN[+]>
2845 include names matching the given patterns
2846
2847 -X,--exclude <PATTERN[+]>
2848 exclude names matching the given patterns
2849
2850 -n, --dry-run
2851 do not perform actions, just print output
2852
2853 [+] marked option can be specified multiple times
2854
2855 aliases: rm
2856
2857 rename
2858 rename files; equivalent of copy + remove:
2859
2860 hg rename [OPTION]... SOURCE... DEST
2861
2862 Mark dest as copies of sources; mark sources for deletion. If dest is a
2863 directory, copies are put in that directory. If dest is a file, there
2864 can only be one source.
2865
2866 By default, this command copies the contents of files as they exist in
2867 the working directory. If invoked with -A/--after, the operation is
2868 recorded, but no copying is performed.
2869
2870 To undo marking a destination file as renamed, use --forget. With that
2871 option, all given (positional) arguments are unmarked as renames. The
2872 destination file(s) will be left in place (still tracked). The source
2873 file(s) will not be restored. Note that hg rename --forget behaves the
2874 same way as hg copy --forget.
2875
2876 This command takes effect with the next commit by default.
2877
2878 Returns 0 on success, 1 if errors are encountered.
2879
2880 Options:
2881
2882 --forget
2883 unmark a destination file as renamed
2884
2885 -A, --after
2886 record a rename that has already occurred
2887
2888 --at-rev <REV>
2889 (un)mark renames in the given revision (EXPERIMENTAL)
2890
2891 -f, --force
2892 forcibly move over an existing managed file
2893
2894 -I,--include <PATTERN[+]>
2895 include names matching the given patterns
2896
2897 -X,--exclude <PATTERN[+]>
2898 exclude names matching the given patterns
2899
2900 -n, --dry-run
2901 do not perform actions, just print output
2902
2903 [+] marked option can be specified multiple times
2904
2905 aliases: move mv
2906
2907 resolve
2908 redo merges or set/view the merge status of files:
2909
2910 hg resolve [OPTION]... [FILE]...
2911
2912 Merges with unresolved conflicts are often the result of non-interac‐
2913 tive merging using the internal:merge configuration setting, or a com‐
2914 mand-line merge tool like diff3. The resolve command is used to manage
2915 the files involved in a merge, after hg merge has been run, and before
2916 hg commit is run (i.e. the working directory must have two parents).
2917 See hg help merge-tools for information on configuring merge tools.
2918
2919 The resolve command can be used in the following ways:
2920
2921 • hg resolve [--re-merge] [--tool TOOL] FILE...: attempt to re-merge
2922 the specified files, discarding any previous merge attempts. Re-merg‐
2923 ing is not performed for files already marked as resolved. Use
2924 --all/-a to select all unresolved files. --tool can be used to spec‐
2925 ify the merge tool used for the given files. It overrides the HGMERGE
2926 environment variable and your configuration files. Previous file
2927 contents are saved with a .orig suffix.
2928
2929 • hg resolve -m [FILE]: mark a file as having been resolved (e.g. after
2930 having manually fixed-up the files). The default is to mark all unre‐
2931 solved files.
2932
2933 • hg resolve -u [FILE]...: mark a file as unresolved. The default is to
2934 mark all resolved files.
2935
2936 • hg resolve -l: list files which had or still have conflicts. In the
2937 printed list, U = unresolved and R = resolved. You can use set:unre‐
2938 solved() or set:resolved() to filter the list. See hg help filesets
2939 for details.
2940
2941 Note Mercurial will not let you commit files with unresolved merge
2942 conflicts. You must use hg resolve -m ... before you can commit
2943 after a conflicting merge.
2944
2945 Template:
2946
2947 The following keywords are supported in addition to the common template
2948 keywords and functions. See also hg help templates.
2949
2950 mergestatus
2951 String. Character denoting merge conflicts, U or R.
2952
2953 path String. Repository-absolute path of the file.
2954
2955 Returns 0 on success, 1 if any files fail a resolve attempt.
2956
2957 Options:
2958
2959 -a, --all
2960 select all unresolved files
2961
2962 -l, --list
2963 list state of files needing merge
2964
2965 -m, --mark
2966 mark files as resolved
2967
2968 -u, --unmark
2969 mark files as unresolved
2970
2971 -n, --no-status
2972 hide status prefix
2973
2974 --re-merge
2975 re-merge files
2976
2977 -t,--tool <TOOL>
2978 specify merge tool
2979
2980 -I,--include <PATTERN[+]>
2981 include names matching the given patterns
2982
2983 -X,--exclude <PATTERN[+]>
2984 exclude names matching the given patterns
2985
2986 -T,--template <TEMPLATE>
2987 display with template
2988
2989 [+] marked option can be specified multiple times
2990
2991 revert
2992 restore files to their checkout state:
2993
2994 hg revert [OPTION]... [-r REV] [NAME]...
2995
2996 Note To check out earlier revisions, you should use hg update REV.
2997 To cancel an uncommitted merge (and lose your changes), use hg
2998 merge --abort.
2999
3000 With no revision specified, revert the specified files or directories
3001 to the contents they had in the parent of the working directory. This
3002 restores the contents of files to an unmodified state and unschedules
3003 adds, removes, copies, and renames. If the working directory has two
3004 parents, you must explicitly specify a revision.
3005
3006 Using the -r/--rev or -d/--date options, revert the given files or di‐
3007 rectories to their states as of a specific revision. Because revert
3008 does not change the working directory parents, this will cause these
3009 files to appear modified. This can be helpful to "back out" some or all
3010 of an earlier change. See hg backout for a related method.
3011
3012 Modified files are saved with a .orig suffix before reverting. To dis‐
3013 able these backups, use --no-backup. It is possible to store the backup
3014 files in a custom directory relative to the root of the repository by
3015 setting the ui.origbackuppath configuration option.
3016
3017 See hg help dates for a list of formats valid for -d/--date.
3018
3019 See hg help backout for a way to reverse the effect of an earlier
3020 changeset.
3021
3022 Returns 0 on success.
3023
3024 Options:
3025
3026 -a, --all
3027 revert all changes when no arguments given
3028
3029 -d,--date <DATE>
3030 tipmost revision matching date
3031
3032 -r,--rev <REV>
3033 revert to the specified revision
3034
3035 -C, --no-backup
3036 do not save backup copies of files
3037
3038 -i, --interactive
3039 interactively select the changes
3040
3041 -I,--include <PATTERN[+]>
3042 include names matching the given patterns
3043
3044 -X,--exclude <PATTERN[+]>
3045 exclude names matching the given patterns
3046
3047 -n, --dry-run
3048 do not perform actions, just print output
3049
3050 [+] marked option can be specified multiple times
3051
3052 root
3053 print the root (top) of the current working directory:
3054
3055 hg root
3056
3057 Print the root directory of the current repository.
3058
3059 Template:
3060
3061 The following keywords are supported in addition to the common template
3062 keywords and functions. See also hg help templates.
3063
3064 hgpath String. Path to the .hg directory.
3065
3066 storepath
3067 String. Path to the directory holding versioned data.
3068
3069 Returns 0 on success.
3070
3071 Options:
3072
3073 -T,--template <TEMPLATE>
3074 display with template
3075
3076 shelve
3077 save and set aside changes from the working directory:
3078
3079 hg shelve [OPTION]... [FILE]...
3080
3081 Shelving takes files that "hg status" reports as not clean, saves the
3082 modifications to a bundle (a shelved change), and reverts the files so
3083 that their state in the working directory becomes clean.
3084
3085 To restore these changes to the working directory, using "hg unshelve";
3086 this will work even if you switch to a different commit.
3087
3088 When no files are specified, "hg shelve" saves all not-clean files. If
3089 specific files or directories are named, only changes to those files
3090 are shelved.
3091
3092 In bare shelve (when no files are specified, without interactive, in‐
3093 clude and exclude option), shelving remembers information if the work‐
3094 ing directory was on newly created branch, in other words working di‐
3095 rectory was on different branch than its first parent. In this situa‐
3096 tion unshelving restores branch information to the working directory.
3097
3098 Each shelved change has a name that makes it easier to find later. The
3099 name of a shelved change defaults to being based on the active book‐
3100 mark, or if there is no active bookmark, the current named branch. To
3101 specify a different name, use --name.
3102
3103 To see a list of existing shelved changes, use the --list option. For
3104 each shelved change, this will print its name, age, and description;
3105 use --patch or --stat for more details.
3106
3107 To delete specific shelved changes, use --delete. To delete all shelved
3108 changes, use --cleanup.
3109
3110 Options:
3111
3112 -A, --addremove
3113 mark new/missing files as added/removed before shelving
3114
3115 -u, --unknown
3116 store unknown files in the shelve
3117
3118 --cleanup
3119 delete all shelved changes
3120
3121 --date <DATE>
3122 shelve with the specified commit date
3123
3124 -d, --delete
3125 delete the named shelved change(s)
3126
3127 -e, --edit
3128 invoke editor on commit messages
3129
3130 -k, --keep
3131 shelve, but keep changes in the working directory
3132
3133 -l, --list
3134 list current shelves
3135
3136 -m,--message <TEXT>
3137 use text as shelve message
3138
3139 -n,--name <NAME>
3140 use the given name for the shelved commit
3141
3142 -p, --patch
3143 output patches for changes (provide the names of the shelved
3144 changes as positional arguments)
3145
3146 -i, --interactive
3147 interactive mode
3148
3149 --stat output diffstat-style summary of changes (provide the names of
3150 the shelved changes as positional arguments)
3151
3152 -I,--include <PATTERN[+]>
3153 include names matching the given patterns
3154
3155 -X,--exclude <PATTERN[+]>
3156 exclude names matching the given patterns
3157
3158 [+] marked option can be specified multiple times
3159
3160 status
3161 show changed files in the working directory:
3162
3163 hg status [OPTION]... [FILE]...
3164
3165 Show status of files in the repository. If names are given, only files
3166 that match are shown. Files that are clean or ignored or the source of
3167 a copy/move operation, are not listed unless -c/--clean, -i/--ignored,
3168 -C/--copies or -A/--all are given. Unless options described with "show
3169 only ..." are given, the options -mardu are used.
3170
3171 Option -q/--quiet hides untracked (unknown and ignored) files unless
3172 explicitly requested with -u/--unknown or -i/--ignored.
3173
3174 Note hg status may appear to disagree with diff if permissions have
3175 changed or a merge has occurred. The standard diff format does
3176 not report permission changes and diff only reports changes rel‐
3177 ative to one merge parent.
3178
3179 If one revision is given, it is used as the base revision. If two re‐
3180 visions are given, the differences between them are shown. The --change
3181 option can also be used as a shortcut to list the changed files of a
3182 revision from its first parent.
3183
3184 The codes used to show the status of files are:
3185
3186 M = modified
3187 A = added
3188 R = removed
3189 C = clean
3190 ! = missing (deleted by non-hg command, but still tracked)
3191 ? = not tracked
3192 I = ignored
3193 = origin of the previous file (with --copies)
3194
3195 The -t/--terse option abbreviates the output by showing only the direc‐
3196 tory name if all the files in it share the same status. The option
3197 takes an argument indicating the statuses to abbreviate: 'm' for 'modi‐
3198 fied', 'a' for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for
3199 'unknown', 'i' for 'ignored' and 'c' for clean.
3200
3201 It abbreviates only those statuses which are passed. Note that clean
3202 and ignored files are not displayed with '--terse ic' unless the
3203 -c/--clean and -i/--ignored options are also used.
3204
3205 The -v/--verbose option shows information when the repository is in an
3206 unfinished merge, shelve, rebase state etc. You can have this behavior
3207 turned on by default by enabling the commands.status.verbose option.
3208
3209 You can skip displaying some of these states by setting commands.sta‐
3210 tus.skipstates to one or more of: 'bisect', 'graft', 'histedit',
3211 'merge', 'rebase', or 'unshelve'.
3212
3213 Template:
3214
3215 The following keywords are supported in addition to the common template
3216 keywords and functions. See also hg help templates.
3217
3218 path String. Repository-absolute path of the file.
3219
3220 source String. Repository-absolute path of the file originated from.
3221 Available if --copies is specified.
3222
3223 status String. Character denoting file's status.
3224
3225 Examples:
3226
3227 • show changes in the working directory relative to a changeset:
3228
3229 hg status --rev 9353
3230
3231 • show changes in the working directory relative to the current direc‐
3232 tory (see hg help patterns for more information):
3233
3234 hg status re:
3235
3236 • show all changes including copies in an existing changeset:
3237
3238 hg status --copies --change 9353
3239
3240 • get a NUL separated list of added files, suitable for xargs:
3241
3242 hg status -an0
3243
3244 • show more information about the repository status, abbreviating
3245 added, removed, modified, deleted, and untracked paths:
3246
3247 hg status -v -t mardu
3248
3249 Returns 0 on success.
3250
3251 Options:
3252
3253 -A, --all
3254 show status of all files
3255
3256 -m, --modified
3257 show only modified files
3258
3259 -a, --added
3260 show only added files
3261
3262 -r, --removed
3263 show only removed files
3264
3265 -d, --deleted
3266 show only missing files
3267
3268 -c, --clean
3269 show only files without changes
3270
3271 -u, --unknown
3272 show only unknown (not tracked) files
3273
3274 -i, --ignored
3275 show only ignored files
3276
3277 -n, --no-status
3278 hide status prefix
3279
3280 -t,--terse <VALUE>
3281 show the terse output (EXPERIMENTAL) (default: nothing)
3282
3283 -C, --copies
3284 show source of copied files (DEFAULT: ui.statuscopies)
3285
3286 -0, --print0
3287 end filenames with NUL, for use with xargs
3288
3289 --rev <REV[+]>
3290 show difference from revision
3291
3292 --change <REV>
3293 list the changed files of a revision
3294
3295 -I,--include <PATTERN[+]>
3296 include names matching the given patterns
3297
3298 -X,--exclude <PATTERN[+]>
3299 exclude names matching the given patterns
3300
3301 -S, --subrepos
3302 recurse into subrepositories
3303
3304 -T,--template <TEMPLATE>
3305 display with template
3306
3307 [+] marked option can be specified multiple times
3308
3309 aliases: st
3310
3311 summary
3312 summarize working directory state:
3313
3314 hg summary [--remote]
3315
3316 This generates a brief summary of the working directory state, includ‐
3317 ing parents, branch, commit status, phase and available updates.
3318
3319 With the --remote option, this will check the default paths for incom‐
3320 ing and outgoing changes. This can be time-consuming.
3321
3322 Returns 0 on success.
3323
3324 Options:
3325
3326 --remote
3327 check for push and pull
3328
3329 aliases: sum
3330
3331 unshelve
3332 restore a shelved change to the working directory:
3333
3334 hg unshelve [OPTION]... [[-n] SHELVED]
3335
3336 This command accepts an optional name of a shelved change to restore.
3337 If none is given, the most recent shelved change is used.
3338
3339 If a shelved change is applied successfully, the bundle that contains
3340 the shelved changes is moved to a backup location (.hg/shelve-backup).
3341
3342 Since you can restore a shelved change on top of an arbitrary commit,
3343 it is possible that unshelving will result in a conflict between your
3344 changes and the commits you are unshelving onto. If this occurs, you
3345 must resolve the conflict, then use --continue to complete the unshelve
3346 operation. (The bundle will not be moved until you successfully com‐
3347 plete the unshelve.)
3348
3349 (Alternatively, you can use --abort to abandon an unshelve that causes
3350 a conflict. This reverts the unshelved changes, and leaves the bundle
3351 in place.)
3352
3353 If bare shelved change (without interactive, include and exclude op‐
3354 tion) was done on newly created branch it would restore branch informa‐
3355 tion to the working directory.
3356
3357 After a successful unshelve, the shelved changes are stored in a backup
3358 directory. Only the N most recent backups are kept. N defaults to 10
3359 but can be overridden using the shelve.maxbackups configuration option.
3360
3361 Timestamp in seconds is used to decide order of backups. More than
3362 maxbackups backups are kept, if same timestamp prevents from deciding
3363 exact order of them, for safety.
3364
3365 Selected changes can be unshelved with --interactive flag. The working
3366 directory is updated with the selected changes, and only the unselected
3367 changes remain shelved. Note: The whole shelve is applied to working
3368 directory first before running interactively. So, this will bring up
3369 all the conflicts between working directory and the shelve, irrespec‐
3370 tive of which changes will be unshelved.
3371
3372 Options:
3373
3374 -a, --abort
3375 abort an incomplete unshelve operation
3376
3377 -c, --continue
3378 continue an incomplete unshelve operation
3379
3380 -i, --interactive
3381 use interactive mode (EXPERIMENTAL)
3382
3383 -k, --keep
3384 keep shelve after unshelving
3385
3386 -n,--name <NAME>
3387 restore shelved change with given name
3388
3389 -t,--tool <VALUE>
3390 specify merge tool
3391
3392 --date <DATE>
3393 set date for temporary commits (DEPRECATED)
3394
3395 update
3396 update working directory (or switch revisions):
3397
3398 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
3399
3400 Update the repository's working directory to the specified changeset.
3401 If no changeset is specified, update to the tip of the current named
3402 branch and move the active bookmark (see hg help bookmarks).
3403
3404 Update sets the working directory's parent revision to the specified
3405 changeset (see hg help parents).
3406
3407 If the changeset is not a descendant or ancestor of the working direc‐
3408 tory's parent and there are uncommitted changes, the update is aborted.
3409 With the -c/--check option, the working directory is checked for uncom‐
3410 mitted changes; if none are found, the working directory is updated to
3411 the specified changeset.
3412
3413 The -C/--clean, -c/--check, and -m/--merge options control what happens
3414 if the working directory contains uncommitted changes. At most of one
3415 of them can be specified.
3416
3417 1. If no option is specified, and if the requested changeset is an an‐
3418 cestor or descendant of the working directory's parent, the uncom‐
3419 mitted changes are merged into the requested changeset and the
3420 merged result is left uncommitted. If the requested changeset is not
3421 an ancestor or descendant (that is, it is on another branch), the
3422 update is aborted and the uncommitted changes are preserved.
3423
3424 2. With the -m/--merge option, the update is allowed even if the re‐
3425 quested changeset is not an ancestor or descendant of the working
3426 directory's parent.
3427
3428 3. With the -c/--check option, the update is aborted and the uncommit‐
3429 ted changes are preserved.
3430
3431 4. With the -C/--clean option, uncommitted changes are discarded and
3432 the working directory is updated to the requested changeset.
3433
3434 To cancel an uncommitted merge (and lose your changes), use hg merge
3435 --abort.
3436
3437 Use null as the changeset to remove the working directory (like hg
3438 clone -U).
3439
3440 If you want to revert just one file to an older revision, use hg revert
3441 [-r REV] NAME.
3442
3443 See hg help dates for a list of formats valid for -d/--date.
3444
3445 Returns 0 on success, 1 if there are unresolved files.
3446
3447 Options:
3448
3449 -C, --clean
3450 discard uncommitted changes (no backup)
3451
3452 -c, --check
3453 require clean working directory
3454
3455 -m, --merge
3456 merge uncommitted changes
3457
3458 -d,--date <DATE>
3459 tipmost revision matching date
3460
3461 -r,--rev <REV>
3462 revision
3463
3464 -t,--tool <TOOL>
3465 specify merge tool
3466
3467 aliases: up checkout co
3468
3469 Change import/export
3470 archive
3471 create an unversioned archive of a repository revision:
3472
3473 hg archive [OPTION]... DEST
3474
3475 By default, the revision used is the parent of the working directory;
3476 use -r/--rev to specify a different revision.
3477
3478 The archive type is automatically detected based on file extension (to
3479 override, use -t/--type).
3480
3481 Examples:
3482
3483 • create a zip file containing the 1.0 release:
3484
3485 hg archive -r 1.0 project-1.0.zip
3486
3487 • create a tarball excluding .hg files:
3488
3489 hg archive project.tar.gz -X ".hg*"
3490
3491 Valid types are:
3492
3493 files
3494
3495 a directory full of files (default)
3496
3497 tar
3498
3499 tar archive, uncompressed
3500
3501 tbz2
3502
3503 tar archive, compressed using bzip2
3504
3505 tgz
3506
3507 tar archive, compressed using gzip
3508
3509 txz
3510
3511 tar archive, compressed using lzma (only in Python 3)
3512
3513 uzip
3514
3515 zip archive, uncompressed
3516
3517 zip
3518
3519 zip archive, compressed using deflate
3520
3521 The exact name of the destination archive or directory is given using a
3522 format string; see hg help export for details.
3523
3524 Each member added to an archive file has a directory prefix prepended.
3525 Use -p/--prefix to specify a format string for the prefix. The default
3526 is the basename of the archive, with suffixes removed.
3527
3528 Returns 0 on success.
3529
3530 Options:
3531
3532 --no-decode
3533 do not pass files through decoders
3534
3535 -p,--prefix <PREFIX>
3536 directory prefix for files in archive
3537
3538 -r,--rev <REV>
3539 revision to distribute
3540
3541 -t,--type <TYPE>
3542 type of distribution to create
3543
3544 -S, --subrepos
3545 recurse into subrepositories
3546
3547 -I,--include <PATTERN[+]>
3548 include names matching the given patterns
3549
3550 -X,--exclude <PATTERN[+]>
3551 exclude names matching the given patterns
3552
3553 [+] marked option can be specified multiple times
3554
3555 bundle
3556 create a bundle file:
3557
3558 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]...
3559
3560 Generate a bundle file containing data to be transferred to another
3561 repository.
3562
3563 To create a bundle containing all changesets, use -a/--all (or --base
3564 null). Otherwise, hg assumes the destination will have all the nodes
3565 you specify with --base parameters. Otherwise, hg will assume the
3566 repository has all the nodes in destination, or default-push/default if
3567 no destination is specified, where destination is the repositories you
3568 provide through DEST option.
3569
3570 You can change bundle format with the -t/--type option. See hg help
3571 bundlespec for documentation on this format. By default, the most ap‐
3572 propriate format is used and compression defaults to bzip2.
3573
3574 The bundle file can then be transferred using conventional means and
3575 applied to another repository with the unbundle or pull command. This
3576 is useful when direct push and pull are not available or when exporting
3577 an entire repository is undesirable.
3578
3579 Applying bundles preserves all changeset contents including permis‐
3580 sions, copy/rename information, and revision history.
3581
3582 Returns 0 on success, 1 if no changes found.
3583
3584 Options:
3585
3586 --exact
3587 compute the base from the revision specified
3588
3589 -f, --force
3590 run even when the destination is unrelated
3591
3592 -r,--rev <REV[+]>
3593 a changeset intended to be added to the destination
3594
3595 -b,--branch <BRANCH[+]>
3596 a specific branch you would like to bundle
3597
3598 --base <REV[+]>
3599 a base changeset assumed to be available at the destination
3600
3601 -a, --all
3602 bundle all changesets in the repository
3603
3604 -t,--type <TYPE>
3605 bundle compression type to use (default: bzip2)
3606
3607 -e,--ssh <CMD>
3608 specify ssh command to use
3609
3610 --remotecmd <CMD>
3611 specify hg command to run on the remote side
3612
3613 --insecure
3614 do not verify server certificate (ignoring web.cacerts config)
3615
3616 [+] marked option can be specified multiple times
3617
3618 export
3619 dump the header and diffs for one or more changesets:
3620
3621 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
3622
3623 Print the changeset header and diffs for one or more revisions. If no
3624 revision is given, the parent of the working directory is used.
3625
3626 The information shown in the changeset header is: author, date, branch
3627 name (if non-default), changeset hash, parent(s) and commit comment.
3628
3629 Note hg export may generate unexpected diff output for merge change‐
3630 sets, as it will compare the merge changeset against its first
3631 parent only.
3632
3633 Output may be to a file, in which case the name of the file is given
3634 using a template string. See hg help templates. In addition to the com‐
3635 mon template keywords, the following formatting rules are supported:
3636
3637 %%
3638
3639 literal "%" character
3640
3641 %H
3642
3643 changeset hash (40 hexadecimal digits)
3644
3645 %N
3646
3647 number of patches being generated
3648
3649 %R
3650
3651 changeset revision number
3652
3653 %b
3654
3655 basename of the exporting repository
3656
3657 %h
3658
3659 short-form changeset hash (12 hexadecimal digits)
3660
3661 %m
3662
3663 first line of the commit message (only alphanumeric characters)
3664
3665 %n
3666
3667 zero-padded sequence number, starting at 1
3668
3669 %r
3670
3671 zero-padded changeset revision number
3672
3673 \
3674
3675 literal "" character
3676
3677 Without the -a/--text option, export will avoid generating diffs of
3678 files it detects as binary. With -a, export will generate a diff any‐
3679 way, probably with undesirable results.
3680
3681 With -B/--bookmark changesets reachable by the given bookmark are se‐
3682 lected.
3683
3684 Use the -g/--git option to generate diffs in the git extended diff for‐
3685 mat. See hg help diffs for more information.
3686
3687 With the --switch-parent option, the diff will be against the second
3688 parent. It can be useful to review a merge.
3689
3690 Template:
3691
3692 The following keywords are supported in addition to the common template
3693 keywords and functions. See also hg help templates.
3694
3695 diff String. Diff content.
3696
3697 parents
3698 List of strings. Parent nodes of the changeset.
3699
3700 Examples:
3701
3702 • use export and import to transplant a bugfix to the current branch:
3703
3704 hg export -r 9353 | hg import -
3705
3706 • export all the changesets between two revisions to a file with rename
3707 information:
3708
3709 hg export --git -r 123:150 > changes.txt
3710
3711 • split outgoing changes into a series of patches with descriptive
3712 names:
3713
3714 hg export -r "outgoing()" -o "%n-%m.patch"
3715
3716 Returns 0 on success.
3717
3718 Options:
3719
3720 -B,--bookmark <BOOKMARK>
3721 export changes only reachable by given bookmark
3722
3723 -o,--output <FORMAT>
3724 print output to file with formatted name
3725
3726 --switch-parent
3727 diff against the second parent
3728
3729 -r,--rev <REV[+]>
3730 revisions to export
3731
3732 -a, --text
3733 treat all files as text
3734
3735 -g, --git
3736 use git extended diff format (DEFAULT: diff.git)
3737
3738 --binary
3739 generate binary diffs in git mode (default)
3740
3741 --nodates
3742 omit dates from diff headers
3743
3744 -T,--template <TEMPLATE>
3745 display with template
3746
3747 [+] marked option can be specified multiple times
3748
3749 import
3750 import an ordered set of patches:
3751
3752 hg import [OPTION]... PATCH...
3753
3754 Import a list of patches and commit them individually (unless --no-com‐
3755 mit is specified).
3756
3757 To read a patch from standard input (stdin), use "-" as the patch name.
3758 If a URL is specified, the patch will be downloaded from there.
3759
3760 Import first applies changes to the working directory (unless --bypass
3761 is specified), import will abort if there are outstanding changes.
3762
3763 Use --bypass to apply and commit patches directly to the repository,
3764 without affecting the working directory. Without --exact, patches will
3765 be applied on top of the working directory parent revision.
3766
3767 You can import a patch straight from a mail message. Even patches as
3768 attachments work (to use the body part, it must have type text/plain or
3769 text/x-patch). From and Subject headers of email message are used as
3770 default committer and commit message. All text/plain body parts before
3771 first diff are added to the commit message.
3772
3773 If the imported patch was generated by hg export, user and description
3774 from patch override values from message headers and body. Values given
3775 on command line with -m/--message and -u/--user override these.
3776
3777 If --exact is specified, import will set the working directory to the
3778 parent of each patch before applying it, and will abort if the result‐
3779 ing changeset has a different ID than the one recorded in the patch.
3780 This will guard against various ways that portable patch formats and
3781 mail systems might fail to transfer Mercurial data or metadata. See hg
3782 bundle for lossless transmission.
3783
3784 Use --partial to ensure a changeset will be created from the patch even
3785 if some hunks fail to apply. Hunks that fail to apply will be written
3786 to a <target-file>.rej file. Conflicts can then be resolved by hand be‐
3787 fore hg commit --amend is run to update the created changeset. This
3788 flag exists to let people import patches that partially apply without
3789 losing the associated metadata (author, date, description, ...).
3790
3791 Note When no hunks apply cleanly, hg import --partial will create an
3792 empty changeset, importing only the patch metadata.
3793
3794 With -s/--similarity, hg will attempt to discover renames and copies in
3795 the patch in the same way as hg addremove.
3796
3797 It is possible to use external patch programs to perform the patch by
3798 setting the ui.patch configuration option. For the default internal
3799 tool, the fuzz can also be configured via patch.fuzz. See hg help con‐
3800 fig for more information about configuration files and how to use these
3801 options.
3802
3803 See hg help dates for a list of formats valid for -d/--date.
3804
3805 Examples:
3806
3807 • import a traditional patch from a website and detect renames:
3808
3809 hg import -s 80 http://example.com/bugfix.patch
3810
3811 • import a changeset from an hgweb server:
3812
3813 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
3814
3815 • import all the patches in an Unix-style mbox:
3816
3817 hg import incoming-patches.mbox
3818
3819 • import patches from stdin:
3820
3821 hg import -
3822
3823 • attempt to exactly restore an exported changeset (not always possi‐
3824 ble):
3825
3826 hg import --exact proposed-fix.patch
3827
3828 • use an external tool to apply a patch which is too fuzzy for the de‐
3829 fault internal tool.
3830
3831 hg import --config ui.patch="patch --merge" fuzzy.patch
3832
3833 • change the default fuzzing from 2 to a less strict 7
3834
3835 hg import --config ui.fuzz=7 fuzz.patch
3836
3837 Returns 0 on success, 1 on partial success (see --partial).
3838
3839 Options:
3840
3841 -p,--strip <NUM>
3842 directory strip option for patch. This has the same meaning as
3843 the corresponding patch option (default: 1)
3844
3845 -b,--base <PATH>
3846 base path (DEPRECATED)
3847
3848 --secret
3849 use the secret phase for committing
3850
3851 -e, --edit
3852 invoke editor on commit messages
3853
3854 -f, --force
3855 skip check for outstanding uncommitted changes (DEPRECATED)
3856
3857 --no-commit
3858 don't commit, just update the working directory
3859
3860 --bypass
3861 apply patch without touching the working directory
3862
3863 --partial
3864 commit even if some hunks fail
3865
3866 --exact
3867 abort if patch would apply lossily
3868
3869 --prefix <DIR>
3870 apply patch to subdirectory
3871
3872 --import-branch
3873 use any branch information in patch (implied by --exact)
3874
3875 -m,--message <TEXT>
3876 use text as commit message
3877
3878 -l,--logfile <FILE>
3879 read commit message from file
3880
3881 -d,--date <DATE>
3882 record the specified date as commit date
3883
3884 -u,--user <USER>
3885 record the specified user as committer
3886
3887 -s,--similarity <SIMILARITY>
3888 guess renamed files by similarity (0<=s<=100)
3889
3890 aliases: patch
3891
3892 unbundle
3893 apply one or more bundle files:
3894
3895 hg unbundle [-u] FILE...
3896
3897 Apply one or more bundle files generated by hg bundle.
3898
3899 Returns 0 on success, 1 if an update has unresolved files.
3900
3901 Options:
3902
3903 -u, --update
3904 update to new branch head if changesets were unbundled
3905
3906 Repository maintenance
3907 manifest
3908 output the current or given revision of the project manifest:
3909
3910 hg manifest [-r REV]
3911
3912 Print a list of version controlled files for the given revision. If no
3913 revision is given, the first parent of the working directory is used,
3914 or the null revision if no revision is checked out.
3915
3916 With -v, print file permissions, symlink and executable bits. With
3917 --debug, print file revision hashes.
3918
3919 If option --all is specified, the list of all files from all revisions
3920 is printed. This includes deleted and renamed files.
3921
3922 Returns 0 on success.
3923
3924 Options:
3925
3926 -r,--rev <REV>
3927 revision to display
3928
3929 --all list files from all revisions
3930
3931 -T,--template <TEMPLATE>
3932 display with template
3933
3934 recover
3935 roll back an interrupted transaction:
3936
3937 hg recover
3938
3939 Recover from an interrupted commit or pull.
3940
3941 This command tries to fix the repository status after an interrupted
3942 operation. It should only be necessary when Mercurial suggests it.
3943
3944 Returns 0 if successful, 1 if nothing to recover or verify fails.
3945
3946 Options:
3947
3948 --verify
3949 run hg verify after successful recover
3950
3951 rollback
3952 roll back the last transaction (DANGEROUS) (DEPRECATED):
3953
3954 hg rollback
3955
3956 Please use hg commit --amend instead of rollback to correct mistakes in
3957 the last commit.
3958
3959 This command should be used with care. There is only one level of roll‐
3960 back, and there is no way to undo a rollback. It will also restore the
3961 dirstate at the time of the last transaction, losing any dirstate
3962 changes since that time. This command does not alter the working direc‐
3963 tory.
3964
3965 Transactions are used to encapsulate the effects of all commands that
3966 create new changesets or propagate existing changesets into a reposi‐
3967 tory.
3968
3969 For example, the following commands are transactional, and their ef‐
3970 fects can be rolled back:
3971
3972 • commit
3973
3974 • import
3975
3976 • pull
3977
3978 • push (with this repository as the destination)
3979
3980 • unbundle
3981
3982 To avoid permanent data loss, rollback will refuse to rollback a commit
3983 transaction if it isn't checked out. Use --force to override this pro‐
3984 tection.
3985
3986 The rollback command can be entirely disabled by setting the ui.roll‐
3987 back configuration setting to false. If you're here because you want to
3988 use rollback and it's disabled, you can re-enable the command by set‐
3989 ting ui.rollback to true.
3990
3991 This command is not intended for use on public repositories. Once
3992 changes are visible for pull by other users, rolling a transaction back
3993 locally is ineffective (someone else may already have pulled the
3994 changes). Furthermore, a race is possible with readers of the reposi‐
3995 tory; for example an in-progress pull from the repository may fail if a
3996 rollback is performed.
3997
3998 Returns 0 on success, 1 if no rollback data is available.
3999
4000 Options:
4001
4002 -n, --dry-run
4003 do not perform actions, just print output
4004
4005 -f, --force
4006 ignore safety measures
4007
4008 verify
4009 verify the integrity of the repository:
4010
4011 hg verify
4012
4013 Verify the integrity of the current repository.
4014
4015 This will perform an extensive check of the repository's integrity,
4016 validating the hashes and checksums of each entry in the changelog,
4017 manifest, and tracked files, as well as the integrity of their
4018 crosslinks and indices.
4019
4020 Please see https://mercurial-scm.org/wiki/RepositoryCorruption for more
4021 information about recovery from corruption of the repository.
4022
4023 Returns 0 on success, 1 if errors are encountered.
4024
4025 Options:
4026
4027 --full perform more checks (EXPERIMENTAL)
4028
4029 Help
4030 config
4031 show combined config settings from all hgrc files:
4032
4033 hg config [-u] [NAME]...
4034
4035 With no arguments, print names and values of all config items.
4036
4037 With one argument of the form section.name, print just the value of
4038 that config item.
4039
4040 With multiple arguments, print names and values of all config items
4041 with matching section names or section.names.
4042
4043 With --edit, start an editor on the user-level config file. With
4044 --global, edit the system-wide config file. With --local, edit the
4045 repository-level config file.
4046
4047 With --source, the source (filename and line number) is printed for
4048 each config item.
4049
4050 See hg help config for more information about config files.
4051
4052 --non-shared flag is used to edit .hg/hgrc-not-shared config file.
4053 This file is not shared across shares when in share-safe mode.
4054
4055 Template:
4056
4057 The following keywords are supported. See also hg help templates.
4058
4059 name String. Config name.
4060
4061 source String. Filename and line number where the item is defined.
4062
4063 value String. Config value.
4064
4065 The --shared flag can be used to edit the config file of shared source
4066 repository. It only works when you have shared using the experimental
4067 share safe feature.
4068
4069 Returns 0 on success, 1 if NAME does not exist.
4070
4071 Options:
4072
4073 -u, --untrusted
4074 show untrusted configuration options
4075
4076 --exp-all-known
4077 show all known config option (EXPERIMENTAL)
4078
4079 -e, --edit
4080 edit user config
4081
4082 -l, --local
4083 edit repository config
4084
4085 --source
4086 show source of configuration value
4087
4088 --shared
4089 edit shared source repository config (EXPERIMENTAL)
4090
4091 --non-shared
4092 edit non shared config (EXPERIMENTAL)
4093
4094 -g, --global
4095 edit global config
4096
4097 -T,--template <TEMPLATE>
4098 display with template
4099
4100 aliases: showconfig debugconfig
4101
4102 help
4103 show help for a given topic or a help overview:
4104
4105 hg help [-eck] [-s PLATFORM] [TOPIC]
4106
4107 With no arguments, print a list of commands with short help messages.
4108
4109 Given a topic, extension, or command name, print help for that topic.
4110
4111 Returns 0 if successful.
4112
4113 Options:
4114
4115 -e, --extension
4116 show only help for extensions
4117
4118 -c, --command
4119 show only help for commands
4120
4121 -k, --keyword
4122 show topics matching keyword
4123
4124 -s,--system <PLATFORM[+]>
4125 show help for specific platform(s)
4126
4127 [+] marked option can be specified multiple times
4128
4129 version
4130 output version and copyright information:
4131
4132 hg version
4133
4134 Template:
4135
4136 The following keywords are supported. See also hg help templates.
4137
4138 extensions
4139 List of extensions.
4140
4141 ver String. Version number.
4142
4143 And each entry of {extensions} provides the following sub-keywords in
4144 addition to {ver}.
4145
4146 bundled
4147 Boolean. True if included in the release.
4148
4149 name String. Extension name.
4150
4151 Options:
4152
4153 -T,--template <TEMPLATE>
4154 display with template
4155
4156 Uncategorized commands
4158 Mercurial supports generating standalone "bundle" files that hold
4159 repository data. These "bundles" are typically saved locally and used
4160 later or exchanged between different repositories, possibly on differ‐
4161 ent machines. Example commands using bundles are hg bundle and hg un‐
4162 bundle.
4163
4164 Generation of bundle files is controlled by a "bundle specification"
4165 ("bundlespec") string. This string tells the bundle generation process
4166 how to create the bundle.
4167
4168 A "bundlespec" string is composed of the following elements:
4169
4170 type A string denoting the bundle format to use.
4171
4172 compression
4173 Denotes the compression engine to use compressing the raw bundle
4174 data.
4175
4176 parameters
4177 Arbitrary key-value parameters to further control bundle genera‐
4178 tion.
4179
4180 A "bundlespec" string has the following formats:
4181
4182 <type> The literal bundle format string is used.
4183
4184 <compression>-<type>
4185 The compression engine and format are delimited by a hyphen (-).
4186
4187 Optional parameters follow the <type>. Parameters are URI escaped
4188 key=value pairs. Each pair is delimited by a semicolon (;). The first
4189 parameter begins after a ; immediately following the <type> value.
4190
4191 Available Types
4192 The following bundle <type> strings are available:
4193
4194 v1 Produces a legacy "changegroup" version 1 bundle.
4195
4196 This format is compatible with nearly all Mercurial clients be‐
4197 cause it is the oldest. However, it has some limitations, which
4198 is why it is no longer the default for new repositories.
4199
4200 v1 bundles can be used with modern repositories using the "gen‐
4201 eraldelta" storage format. However, it may take longer to pro‐
4202 duce the bundle and the resulting bundle may be significantly
4203 larger than a v2 bundle.
4204
4205 v1 bundles can only use the gzip, bzip2, and none compression
4206 formats.
4207
4208 v2 Produces a version 2 bundle.
4209
4210 Version 2 bundles are an extensible format that can store addi‐
4211 tional repository data (such as bookmarks and phases informa‐
4212 tion) and they can store data more efficiently, resulting in
4213 smaller bundles.
4214
4215 Version 2 bundles can also use modern compression engines, such
4216 as zstd, making them faster to compress and often smaller.
4217
4218 Available Compression Engines
4219 The following bundle <compression> engines can be used:
4220
4221 bzip2
4222
4223 An algorithm that produces smaller bundles than gzip.
4224
4225 All Mercurial clients should support this format.
4226
4227 This engine will likely produce smaller bundles than gzip but
4228 will be significantly slower, both during compression and decom‐
4229 pression.
4230
4231 If available, the zstd engine can yield similar or better com‐
4232 pression at much higher speeds.
4233
4234 gzip
4235
4236 zlib compression using the DEFLATE algorithm.
4237
4238 All Mercurial clients should support this format. The compres‐
4239 sion algorithm strikes a reasonable balance between compression
4240 ratio and size.
4241
4242 none
4243
4244 No compression is performed.
4245
4246 Use this compression engine to explicitly disable compression.
4247
4248 Available Options
4249 The following options exist:
4250
4251 changegroup
4252 Include the changegroup data in the bundle (default to True).
4253
4254 cg.version
4255 Select the version of the changegroup to use. Available options
4256 are : 01, 02 or 03. By default it will be automatically selected
4257 according to the current repository format.
4258
4259 obsolescence
4260 Include obsolescence-markers relevant to the bundled changesets.
4261
4262 phases Include phase information relevant to the bundled changesets.
4263
4264 revbranchcache
4265 Include the "tags-fnodes" cache inside the bundle.
4266
4267 tagsfnodescache
4268 Include the "tags-fnodes" cache inside the bundle.
4269
4270 Examples
4271 v2
4272
4273 Produce a v2 bundle using default options, including compres‐
4274 sion.
4275
4276 none-v1
4277
4278 Produce a v1 bundle with no compression.
4279
4280 zstd-v2
4281
4282 Produce a v2 bundle with zstandard compression using default
4283 settings.
4284
4285 zstd-v1
4286
4287 This errors because zstd is not supported for v1 types.
4288
4290 Mercurial colorizes output from several commands.
4291
4292 For example, the diff command shows additions in green and deletions in
4293 red, while the status command shows modified files in magenta. Many
4294 other commands have analogous colors. It is possible to customize these
4295 colors.
4296
4297 To enable color (default) whenever possible use:
4298
4299 [ui]
4300 color = yes
4301
4302 To disable color use:
4303
4304 [ui]
4305 color = no
4306
4307 See hg help config.ui.color for details.
4308
4309 The default pager on Windows does not support color, so enabling the
4310 pager will effectively disable color. See hg help config.ui.paginate
4311 to disable the pager. Alternately, MSYS and Cygwin shells provide less
4312 as a pager, which can be configured to support ANSI color mode. Win‐
4313 dows 10 natively supports ANSI color mode.
4314
4315 Mode
4316 Mercurial can use various systems to display color. The supported modes
4317 are ansi, win32, and terminfo. See hg help config.color for details
4318 about how to control the mode.
4319
4320 Effects
4321 Other effects in addition to color, like bold and underlined text, are
4322 also available. By default, the terminfo database is used to find the
4323 terminal codes used to change color and effect. If terminfo is not
4324 available, then effects are rendered with the ECMA-48 SGR control func‐
4325 tion (aka ANSI escape codes).
4326
4327 The available effects in terminfo mode are 'blink', 'bold', 'dim', 'in‐
4328 verse', 'invisible', 'italic', 'standout', and 'underline'; in ECMA-48
4329 mode, the options are 'bold', 'inverse', 'italic', and 'underline'.
4330 How each is rendered depends on the terminal emulator. Some may not be
4331 available for a given terminal type, and will be silently ignored.
4332
4333 If the terminfo entry for your terminal is missing codes for an effect
4334 or has the wrong codes, you can add or override those codes in your
4335 configuration:
4336
4337 [color]
4338 terminfo.dim = \E[2m
4339
4340 where 'E' is substituted with an escape character.
4341
4342 Labels
4343 Text receives color effects depending on the labels that it has. Many
4344 default Mercurial commands emit labelled text. You can also define your
4345 own labels in templates using the label function, see hg help templates
4346 . A single portion of text may have more than one label. In that case,
4347 effects given to the last label will override any other effects. This
4348 includes the special "none" effect, which nullifies other effects.
4349
4350 Labels are normally invisible. In order to see these labels and their
4351 position in the text, use the global --color=debug option. The same an‐
4352 chor text may be associated to multiple labels, e.g.
4353
4354 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]
4355
4356 The following are the default effects for some default labels. Default
4357 effects may be overridden from your configuration file:
4358
4359 [color]
4360 status.modified = blue bold underline red_background
4361 status.added = green bold
4362 status.removed = red bold blue_background
4363 status.deleted = cyan bold underline
4364 status.unknown = magenta bold underline
4365 status.ignored = black bold
4366
4367 # 'none' turns off all effects
4368 status.clean = none
4369 status.copied = none
4370
4371 qseries.applied = blue bold underline
4372 qseries.unapplied = black bold
4373 qseries.missing = red bold
4374
4375 diff.diffline = bold
4376 diff.extended = cyan bold
4377 diff.file_a = red bold
4378 diff.file_b = green bold
4379 diff.hunk = magenta
4380 diff.deleted = red
4381 diff.inserted = green
4382 diff.changed = white
4383 diff.tab =
4384 diff.trailingwhitespace = bold red_background
4385
4386 # Blank so it inherits the style of the surrounding label
4387 changeset.public =
4388 changeset.draft =
4389 changeset.secret =
4390
4391 resolve.unresolved = red bold
4392 resolve.resolved = green bold
4393
4394 bookmarks.active = green
4395
4396 branches.active = none
4397 branches.closed = black bold
4398 branches.current = green
4399 branches.inactive = none
4400
4401 tags.normal = green
4402 tags.local = black bold
4403
4404 rebase.rebased = blue
4405 rebase.remaining = red bold
4406
4407 shelve.age = cyan
4408 shelve.newest = green bold
4409 shelve.name = blue bold
4410
4411 histedit.remaining = red bold
4412
4413 Custom colors
4414 Because there are only eight standard colors, Mercurial allows you to
4415 define color names for other color slots which might be available for
4416 your terminal type, assuming terminfo mode. For instance:
4417
4418 color.brightblue = 12
4419 color.pink = 207
4420 color.orange = 202
4421
4422 to set 'brightblue' to color slot 12 (useful for 16 color terminals
4423 that have brighter colors defined in the upper eight) and, 'pink' and
4424 'orange' to colors in 256-color xterm's default color cube. These de‐
4425 fined colors may then be used as any of the pre-defined eight, includ‐
4426 ing appending '_background' to set the background to that color.
4427
4429 Some commands allow the user to specify a date, e.g.:
4430
4431 • backout, commit, import, tag: Specify the commit date.
4432
4433 • log, revert, update: Select revision(s) by date.
4434
4435 Many date formats are valid. Here are some examples:
4436
4437 • Wed Dec 6 13:18:29 2006 (local timezone assumed)
4438
4439 • Dec 6 13:18 -0600 (year assumed, time offset provided)
4440
4441 • Dec 6 13:18 UTC (UTC and GMT are aliases for +0000)
4442
4443 • Dec 6 (midnight)
4444
4445 • 13:18 (today assumed)
4446
4447 • 3:39 (3:39AM assumed)
4448
4449 • 3:39pm (15:39)
4450
4451 • 2006-12-06 13:18:29 (ISO 8601 format)
4452
4453 • 2006-12-6 13:18
4454
4455 • 2006-12-6
4456
4457 • 12-6
4458
4459 • 12/6
4460
4461 • 12/6/6 (Dec 6 2006)
4462
4463 • today (midnight)
4464
4465 • yesterday (midnight)
4466
4467 • now - right now
4468
4469 Lastly, there is Mercurial's internal format:
4470
4471 • 1165411109 0 (Wed Dec 6 13:18:29 2006 UTC)
4472
4473 This is the internal representation format for dates. The first number
4474 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
4475 second is the offset of the local timezone, in seconds west of UTC
4476 (negative if the timezone is east of UTC).
4477
4478 The log command also accepts date ranges:
4479
4480 • <DATE - at or before a given date/time
4481
4482 • >DATE - on or after a given date/time
4483
4484 • DATE to DATE - a date range, inclusive
4485
4486 • -DAYS - within a given number of days from today
4487
4489 Mercurial evolves over time, some features, options, commands may be
4490 replaced by better and more secure alternatives. This topic will help
4491 you migrating your existing usage and/or configuration to newer fea‐
4492 tures.
4493
4494 Commands
4495 The following commands are still available but their use are not recom‐
4496 mended:
4497
4498 locate
4499
4500 This command has been replaced by hg files.
4501
4502 parents
4503
4504 This command can be replaced by hg summary or hg log with appropriate
4505 revsets. See hg help revsets for more information.
4506
4507 tip
4508
4509 The recommended alternative is hg heads.
4510
4511 Options
4512 web.allowpull
4513
4514 Renamed to allow-pull.
4515
4516 web.allow_push
4517
4518 Renamed to allow-push.
4519
4521 Mercurial's default format for showing changes between two versions of
4522 a file is compatible with the unified format of GNU diff, which can be
4523 used by GNU patch and many other standard tools.
4524
4525 While this standard format is often enough, it does not encode the fol‐
4526 lowing information:
4527
4528 • executable status and other permission bits
4529
4530 • copy or rename information
4531
4532 • changes in binary files
4533
4534 • creation or deletion of empty files
4535
4536 Mercurial also supports the extended diff format from the git VCS which
4537 addresses these limitations. The git diff format is not produced by de‐
4538 fault because a few widespread tools still do not understand this for‐
4539 mat.
4540
4541 This means that when generating diffs from a Mercurial repository (e.g.
4542 with hg export), you should be careful about things like file copies
4543 and renames or other things mentioned above, because when applying a
4544 standard diff to a different repository, this extra information is
4545 lost. Mercurial's internal operations (like push and pull) are not af‐
4546 fected by this, because they use an internal binary format for communi‐
4547 cating changes.
4548
4549 To make Mercurial produce the git extended diff format, use the --git
4550 option available for many commands, or set 'git = True' in the [diff]
4551 section of your configuration file. You do not need to set this option
4552 when importing diffs in this format or using them in the mq extension.
4553
4555 HG Path to the 'hg' executable, automatically passed when running
4556 hooks, extensions or external tools. If unset or empty, this is
4557 the hg executable's name if it's frozen, or an executable named
4558 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions
4559 on Windows) is searched.
4560
4561 HGEDITOR
4562 This is the name of the editor to run when committing. See EDI‐
4563 TOR.
4564
4565 (deprecated, see hg help config.ui.editor)
4566
4567 HGENCODING
4568 This overrides the default locale setting detected by Mercurial.
4569 This setting is used to convert data including usernames,
4570 changeset descriptions, tag names, and branches. This setting
4571 can be overridden with the --encoding command-line option.
4572
4573 HGENCODINGMODE
4574 This sets Mercurial's behavior for handling unknown characters
4575 while transcoding user input. The default is "strict", which
4576 causes Mercurial to abort if it can't map a character. Other
4577 settings include "replace", which replaces unknown characters,
4578 and "ignore", which drops them. This setting can be overridden
4579 with the --encodingmode command-line option.
4580
4581 HGENCODINGAMBIGUOUS
4582 This sets Mercurial's behavior for handling characters with "am‐
4583 biguous" widths like accented Latin characters with East Asian
4584 fonts. By default, Mercurial assumes ambiguous characters are
4585 narrow, set this variable to "wide" if such characters cause
4586 formatting problems.
4587
4588 HGMERGE
4589 An executable to use for resolving merge conflicts. The program
4590 will be executed with three arguments: local file, remote file,
4591 ancestor file.
4592
4593 (deprecated, see hg help config.ui.merge)
4594
4595 HGRCPATH
4596 A list of files or directories to search for configuration
4597 files. Item separator is ":" on Unix, ";" on Windows. If HGRC‐
4598 PATH is not set, platform default search path is used. If empty,
4599 only the .hg/hgrc from the current repository is read.
4600
4601 For each element in HGRCPATH:
4602
4603 • if it's a directory, all files ending with .rc are added
4604
4605 • otherwise, the file itself will be added
4606
4607 HGRCSKIPREPO
4608 When set, the .hg/hgrc from repositories are not read.
4609
4610 HGPLAIN
4611 When set, this disables any configuration settings that might
4612 change Mercurial's default output. This includes encoding, de‐
4613 faults, verbose mode, debug mode, quiet mode, tracebacks, and
4614 localization. This can be useful when scripting against Mercu‐
4615 rial in the face of existing user configuration.
4616
4617 In addition to the features disabled by HGPLAIN=, the following
4618 values can be specified to adjust behavior:
4619
4620 +strictflags
4621
4622 Restrict parsing of command line flags.
4623
4624 Equivalent options set via command line flags or environment
4625 variables are not overridden.
4626
4627 See hg help scripting for details.
4628
4629 HGPLAINEXCEPT
4630 This is a comma-separated list of features to preserve when HG‐
4631 PLAIN is enabled. Currently the following values are supported:
4632
4633 alias
4634
4635 Don't remove aliases.
4636
4637 color
4638
4639 Don't disable colored output.
4640
4641 i18n
4642
4643 Preserve internationalization.
4644
4645 revsetalias
4646
4647 Don't remove revset aliases.
4648
4649 templatealias
4650
4651 Don't remove template aliases.
4652
4653 progress
4654
4655 Don't hide progress output.
4656
4657 Setting HGPLAINEXCEPT to anything (even an empty string) will
4658 enable plain mode.
4659
4660 HGUSER This is the string used as the author of a commit. If not set,
4661 available values will be considered in this order:
4662
4663 • HGUSER (deprecated)
4664
4665 • configuration files from the HGRCPATH
4666
4667 • EMAIL
4668
4669 • interactive prompt
4670
4671 • LOGNAME (with @hostname appended)
4672
4673 (deprecated, see hg help config.ui.username)
4674
4675 EMAIL May be used as the author of a commit; see HGUSER.
4676
4677 LOGNAME
4678 May be used as the author of a commit; see HGUSER.
4679
4680 VISUAL This is the name of the editor to use when committing. See EDI‐
4681 TOR.
4682
4683 EDITOR Sometimes Mercurial needs to open a text file in an editor for a
4684 user to modify, for example when writing commit messages. The
4685 editor it uses is determined by looking at the environment vari‐
4686 ables HGEDITOR, VISUAL and EDITOR, in that order. The first
4687 non-empty one is chosen. If all of them are empty, the editor
4688 defaults to 'vi'.
4689
4690 PYTHONPATH
4691 This is used by Python to find imported modules and may need to
4692 be set appropriately if this Mercurial is not installed sys‐
4693 tem-wide.
4694
4696 Obsolescence markers make it possible to mark changesets that have been
4697 deleted or superseded in a new version of the changeset.
4698
4699 Unlike the previous way of handling such changes, by stripping the old
4700 changesets from the repository, obsolescence markers can be propagated
4701 between repositories. This allows for a safe and simple way of exchang‐
4702 ing mutable history and altering it after the fact. Changeset phases
4703 are respected, such that only draft and secret changesets can be al‐
4704 tered (see hg help phases for details).
4705
4706 Obsolescence is tracked using "obsolescence markers", a piece of meta‐
4707 data tracking which changesets have been made obsolete, potential suc‐
4708 cessors for a given changeset, the moment the changeset was marked as
4709 obsolete, and the user who performed the rewriting operation. The mark‐
4710 ers are stored separately from standard changeset data can be exchanged
4711 without any of the precursor changesets, preventing unnecessary ex‐
4712 change of obsolescence data.
4713
4714 The complete set of obsolescence markers describes a history of change‐
4715 set modifications that is orthogonal to the repository history of file
4716 modifications. This changeset history allows for detection and auto‐
4717 matic resolution of edge cases arising from multiple users rewriting
4718 the same part of history concurrently.
4719
4720 Current feature status
4721 This feature is still in development.
4722
4723 Instability
4724 Rewriting changesets might introduce instability.
4725
4726 There are two main kinds of instability: orphaning and diverging.
4727
4728 Orphans are changesets left behind when their ancestors are rewritten.
4729 Divergence has two variants:
4730
4731 • Content-divergence occurs when independent rewrites of the same
4732 changesets lead to different results.
4733
4734 • Phase-divergence occurs when the old (obsolete) version of a change‐
4735 set becomes public.
4736
4737 It is possible to prevent local creation of orphans by using the fol‐
4738 lowing config:
4739
4740 [experimental]
4741 evolution.createmarkers = true
4742 evolution.exchange = true
4743
4744 You can also enable that option explicitly:
4745
4746 [experimental]
4747 evolution.createmarkers = true
4748 evolution.exchange = true
4749 evolution.allowunstable = true
4750
4752 Mercurial has the ability to add new features through the use of exten‐
4753 sions. Extensions may add new commands, add options to existing com‐
4754 mands, change the default behavior of commands, or implement hooks.
4755
4756 To enable the "foo" extension, either shipped with Mercurial or in the
4757 Python search path, create an entry for it in your configuration file,
4758 like this:
4759
4760 [extensions]
4761 foo =
4762
4763 You may also specify the full path to an extension:
4764
4765 [extensions]
4766 myfeature = ~/.hgext/myfeature.py
4767
4768 See hg help config for more information on configuration files.
4769
4770 Extensions are not loaded by default for a variety of reasons: they can
4771 increase startup overhead; they may be meant for advanced usage only;
4772 they may provide potentially dangerous abilities (such as letting you
4773 destroy or modify history); they might not be ready for prime time; or
4774 they may alter some usual behaviors of stock Mercurial. It is thus up
4775 to the user to activate extensions as needed.
4776
4777 To explicitly disable an extension enabled in a configuration file of
4778 broader scope, prepend its path with !:
4779
4780 [extensions]
4781 # disabling extension bar residing in /path/to/extension/bar.py
4782 bar = !/path/to/extension/bar.py
4783 # ditto, but no path was supplied for extension baz
4784 baz = !
4785
4786 disabled extensions:
4787
4788 acl hooks for controlling repository access
4789
4790 blackbox
4791 log repository events to a blackbox for debugging
4792
4793 bugzilla
4794 hooks for integrating with the Bugzilla bug tracker
4795
4796 censor erase file content at a given revision
4797
4798 churn command to display statistics about repository history
4799
4800 clonebundles
4801 advertise pre-generated bundles to seed clones
4802
4803 closehead
4804 close arbitrary heads without checking them out first
4805
4806 convert
4807 import revisions from foreign VCS repositories into Mercurial
4808
4809 eol automatically manage newlines in repository files
4810
4811 extdiff
4812 command to allow external programs to compare revisions
4813
4814 factotum
4815 http authentication with factotum
4816
4817 fastexport
4818 export repositories as git fast-import stream
4819
4820 githelp
4821 try mapping git commands to Mercurial commands
4822
4823 gpg commands to sign and verify changesets
4824
4825 hgk browse the repository in a graphical way
4826
4827 highlight
4828 syntax highlighting for hgweb (requires Pygments)
4829
4830 histedit
4831 interactive history editing
4832
4833 keyword
4834 expand keywords in tracked files
4835
4836 largefiles
4837 track large binary files
4838
4839 mq manage a stack of patches
4840
4841 notify hooks for sending email push notifications
4842
4843 patchbomb
4844 command to send changesets as (a series of) patch emails
4845
4846 rebase command to move sets of revisions to a different ancestor
4847
4848 relink recreates hardlinks between repository clones
4849
4850 schemes
4851 extend schemes with shortcuts to repository swarms
4852
4853 share share a common history between several working directories
4854
4855 transplant
4856 command to transplant changesets from another branch
4857
4858 win32mbcs
4859 allow the use of MBCS paths with problematic encodings
4860
4861 zeroconf
4862 discover and advertise repositories on the local network
4863
4865 Mercurial supports a functional language for selecting a set of files.
4866
4867 Like other file patterns, this pattern type is indicated by a prefix,
4868 'set:'. The language supports a number of predicates which are joined
4869 by infix operators. Parenthesis can be used for grouping.
4870
4871 Identifiers such as filenames or patterns must be quoted with single or
4872 double quotes if they contain characters outside of
4873 [.*{}[]?/\_a-zA-Z0-9\x80-\xff] or if they match one of the predefined
4874 predicates. This generally applies to file patterns other than globs
4875 and arguments for predicates. Pattern prefixes such as path: may be
4876 specified without quoting.
4877
4878 Special characters can be used in quoted identifiers by escaping them,
4879 e.g., \n is interpreted as a newline. To prevent them from being inter‐
4880 preted, strings can be prefixed with r, e.g. r'...'.
4881
4882 See also hg help patterns.
4883
4884 Operators
4885 There is a single prefix operator:
4886
4887 not x
4888
4889 Files not in x. Short form is ! x.
4890
4891 These are the supported infix operators:
4892
4893 x and y
4894
4895 The intersection of files in x and y. Short form is x & y.
4896
4897 x or y
4898
4899 The union of files in x and y. There are two alternative short
4900 forms: x | y and x + y.
4901
4902 x - y
4903
4904 Files in x but not in y.
4905
4906 Predicates
4907 The following predicates are supported:
4908
4909 added()
4910
4911 File that is added according to hg status.
4912
4913 binary()
4914
4915 File that appears to be binary (contains NUL bytes).
4916
4917 clean()
4918
4919 File that is clean according to hg status.
4920
4921 copied()
4922
4923 File that is recorded as being copied.
4924
4925 deleted()
4926
4927 Alias for missing().
4928
4929 encoding(name)
4930
4931 File can be successfully decoded with the given character encod‐
4932 ing. May not be useful for encodings other than ASCII and UTF-8.
4933
4934 eol(style)
4935
4936 File contains newlines of the given style (dos, unix, mac). Bi‐
4937 nary files are excluded, files with mixed line endings match
4938 multiple styles.
4939
4940 exec()
4941
4942 File that is marked as executable.
4943
4944 grep(regex)
4945
4946 File contains the given regular expression.
4947
4948 hgignore()
4949
4950 File that matches the active .hgignore pattern.
4951
4952 ignored()
4953
4954 File that is ignored according to hg status.
4955
4956 missing()
4957
4958 File that is missing according to hg status.
4959
4960 modified()
4961
4962 File that is modified according to hg status.
4963
4964 portable()
4965
4966 File that has a portable name. (This doesn't include filenames
4967 with case collisions.)
4968
4969 removed()
4970
4971 File that is removed according to hg status.
4972
4973 resolved()
4974
4975 File that is marked resolved according to hg resolve -l.
4976
4977 revs(revs, pattern)
4978
4979 Evaluate set in the specified revisions. If the revset match
4980 multiple revs, this will return file matching pattern in any of
4981 the revision.
4982
4983 size(expression)
4984
4985 File size matches the given expression. Examples:
4986
4987 • size('1k') - files from 1024 to 2047 bytes
4988
4989 • size('< 20k') - files less than 20480 bytes
4990
4991 • size('>= .5MB') - files at least 524288 bytes
4992
4993 • size('4k - 1MB') - files from 4096 bytes to 1048576 bytes
4994
4995 status(base, rev, pattern)
4996
4997 Evaluate predicate using status change between base and rev. Ex‐
4998 amples:
4999
5000 • status(3, 7, added()) - matches files added from "3" to "7"
5001
5002 subrepo([pattern])
5003
5004 Subrepositories whose paths match the given pattern.
5005
5006 symlink()
5007
5008 File that is marked as a symlink.
5009
5010 tracked()
5011
5012 File that is under Mercurial control.
5013
5014 unknown()
5015
5016 File that is unknown according to hg status.
5017
5018 unresolved()
5019
5020 File that is marked unresolved according to hg resolve -l.
5021
5022 Examples
5023 Some sample queries:
5024
5025 • Show status of files that appear to be binary in the working direc‐
5026 tory:
5027
5028 hg status -A "set:binary()"
5029
5030 • Forget files that are in .hgignore but are already tracked:
5031
5032 hg forget "set:hgignore() and not ignored()"
5033
5034 • Find text files that contain a string:
5035
5036 hg files "set:grep(magic) and not binary()"
5037
5038 • Find C files in a non-standard encoding:
5039
5040 hg files "set:**.c and not encoding('UTF-8')"
5041
5042 • Revert copies of large binary files:
5043
5044 hg revert "set:copied() and binary() and size('>1M')"
5045
5046 • Revert files that were added to the working directory:
5047
5048 hg revert "set:revs('wdir()', added())"
5049
5050 • Remove files listed in foo.lst that contain the letter a or b:
5051
5052 hg remove "set: listfile:foo.lst and (**a* or **b*)"
5053
5055 Most Mercurial commands accept various flags.
5056
5057 Flag names
5058 Flags for each command are listed in hg help for that command. Addi‐
5059 tionally, some flags, such as --repository, are global and can be used
5060 with any command - those are seen in hg help -v, and can be specified
5061 before or after the command.
5062
5063 Every flag has at least a long name, such as --repository. Some flags
5064 may also have a short one-letter name, such as the equivalent -R. Using
5065 the short or long name is equivalent and has the same effect. The long
5066 name may be abbreviated to any unambiguous prefix. For example, hg com‐
5067 mit --amend can be abbreviated to hg commit --am.
5068
5069 Flags that have a short name can also be bundled together - for in‐
5070 stance, to specify both --edit (short -e) and --interactive (short -i),
5071 one could use:
5072
5073 hg commit -ei
5074
5075 If any of the bundled flags takes a value (i.e. is not a boolean), it
5076 must be last, followed by the value:
5077
5078 hg commit -im 'Message'
5079
5080 Flag types
5081 Mercurial command-line flags can be strings, numbers, booleans, or
5082 lists of strings.
5083
5084 Specifying flag values
5085 The following syntaxes are allowed, assuming a flag 'flagname' with
5086 short name 'f':
5087
5088 --flagname=foo
5089 --flagname foo
5090 -f foo
5091 -ffoo
5092
5093 This syntax applies to all non-boolean flags (strings, numbers or
5094 lists).
5095
5096 Specifying boolean flags
5097 Boolean flags do not take a value parameter. To specify a boolean, use
5098 the flag name to set it to true, or the same name prefixed with 'no-'
5099 to set it to false:
5100
5101 hg commit --interactive
5102 hg commit --no-interactive
5103
5104 Specifying list flags
5105 List flags take multiple values. To specify them, pass the flag multi‐
5106 ple times:
5107
5108 hg files --include mercurial --include tests
5109
5110 Setting flag defaults
5111 In order to set a default value for a flag in an hgrc file, it is rec‐
5112 ommended to use aliases:
5113
5114 [alias]
5115 commit = commit --interactive
5116
5117 For more information on hgrc files, see hg help config.
5118
5119 Overriding flags on the command line
5120 If the same non-list flag is specified multiple times on the command
5121 line, the latest specification is used:
5122
5123 hg commit -m "Ignored value" -m "Used value"
5124
5125 This includes the use of aliases - e.g., if one has:
5126
5127 [alias]
5128 committemp = commit -m "Ignored value"
5129
5130 then the following command will override that -m:
5131
5132 hg committemp -m "Used value"
5133
5134 Overriding flag defaults
5135 Every flag has a default value, and you may also set your own defaults
5136 in hgrc as described above. Except for list flags, defaults can be
5137 overridden on the command line simply by specifying the flag in that
5138 location.
5139
5140 Hidden flags
5141 Some flags are not shown in a command's help by default - specifically,
5142 those that are deemed to be experimental, deprecated or advanced. To
5143 show all flags, add the --verbose flag for the help command:
5144
5145 hg help --verbose commit
5146
5148 Ancestor
5149 Any changeset that can be reached by an unbroken chain of parent
5150 changesets from a given changeset. More precisely, the ancestors
5151 of a changeset can be defined by two properties: a parent of a
5152 changeset is an ancestor, and a parent of an ancestor is an an‐
5153 cestor. See also: 'Descendant'.
5154
5155 Bookmark
5156 Bookmarks are pointers to certain commits that move when commit‐
5157 ting. They are similar to tags in that it is possible to use
5158 bookmark names in all places where Mercurial expects a changeset
5159 ID, e.g., with hg update. Unlike tags, bookmarks move along when
5160 you make a commit.
5161
5162 Bookmarks can be renamed, copied and deleted. Bookmarks are lo‐
5163 cal, unless they are explicitly pushed or pulled between reposi‐
5164 tories. Pushing and pulling bookmarks allow you to collaborate
5165 with others on a branch without creating a named branch.
5166
5167 Branch (Noun) A child changeset that has been created from a parent
5168 that is not a head. These are known as topological branches, see
5169 'Branch, topological'. If a topological branch is named, it be‐
5170 comes a named branch. If a topological branch is not named, it
5171 becomes an anonymous branch. See 'Branch, anonymous' and
5172 'Branch, named'.
5173
5174 Branches may be created when changes are pulled from or pushed
5175 to a remote repository, since new heads may be created by these
5176 operations. Note that the term branch can also be used infor‐
5177 mally to describe a development process in which certain devel‐
5178 opment is done independently of other development. This is some‐
5179 times done explicitly with a named branch, but it can also be
5180 done locally, using bookmarks or clones and anonymous branches.
5181
5182 Example: "The experimental branch."
5183
5184 (Verb) The action of creating a child changeset which results in
5185 its parent having more than one child.
5186
5187 Example: "I'm going to branch at X."
5188
5189 Branch, anonymous
5190 Every time a new child changeset is created from a parent that
5191 is not a head and the name of the branch is not changed, a new
5192 anonymous branch is created.
5193
5194 Branch, closed
5195 A named branch whose branch heads have all been closed.
5196
5197 Branch, default
5198 The branch assigned to a changeset when no name has previously
5199 been assigned.
5200
5201 Branch head
5202 See 'Head, branch'.
5203
5204 Branch, inactive
5205 If a named branch has no topological heads, it is considered to
5206 be inactive. As an example, a feature branch becomes inactive
5207 when it is merged into the default branch. The hg branches com‐
5208 mand shows inactive branches by default, though they can be hid‐
5209 den with hg branches --active.
5210
5211 NOTE: this concept is deprecated because it is too implicit.
5212 Branches should now be explicitly closed using hg commit
5213 --close-branch when they are no longer needed.
5214
5215 Branch, named
5216 A collection of changesets which have the same branch name. By
5217 default, children of a changeset in a named branch belong to the
5218 same named branch. A child can be explicitly assigned to a dif‐
5219 ferent branch. See hg help branch, hg help branches and hg com‐
5220 mit --close-branch for more information on managing branches.
5221
5222 Named branches can be thought of as a kind of namespace, divid‐
5223 ing the collection of changesets that comprise the repository
5224 into a collection of disjoint subsets. A named branch is not
5225 necessarily a topological branch. If a new named branch is cre‐
5226 ated from the head of another named branch, or the default
5227 branch, but no further changesets are added to that previous
5228 branch, then that previous branch will be a branch in name only.
5229
5230 Branch tip
5231 See 'Tip, branch'.
5232
5233 Branch, topological
5234 Every time a new child changeset is created from a parent that
5235 is not a head, a new topological branch is created. If a topo‐
5236 logical branch is named, it becomes a named branch. If a topo‐
5237 logical branch is not named, it becomes an anonymous branch of
5238 the current, possibly default, branch.
5239
5240 Changelog
5241 A record of the changesets in the order in which they were added
5242 to the repository. This includes details such as changeset id,
5243 author, commit message, date, and list of changed files.
5244
5245 Changeset
5246 A snapshot of the state of the repository used to record a
5247 change.
5248
5249 Changeset, child
5250 The converse of parent changeset: if P is a parent of C, then C
5251 is a child of P. There is no limit to the number of children
5252 that a changeset may have.
5253
5254 Changeset id
5255 A SHA-1 hash that uniquely identifies a changeset. It may be
5256 represented as either a "long" 40 hexadecimal digit string, or a
5257 "short" 12 hexadecimal digit string.
5258
5259 Changeset, merge
5260 A changeset with two parents. This occurs when a merge is com‐
5261 mitted.
5262
5263 Changeset, parent
5264 A revision upon which a child changeset is based. Specifically,
5265 a parent changeset of a changeset C is a changeset whose node
5266 immediately precedes C in the DAG. Changesets have at most two
5267 parents.
5268
5269 Checkout
5270 (Noun) The working directory being updated to a specific revi‐
5271 sion. This use should probably be avoided where possible, as
5272 changeset is much more appropriate than checkout in this con‐
5273 text.
5274
5275 Example: "I'm using checkout X."
5276
5277 (Verb) Updating the working directory to a specific changeset.
5278 See hg help update.
5279
5280 Example: "I'm going to check out changeset X."
5281
5282 Child changeset
5283 See 'Changeset, child'.
5284
5285 Close changeset
5286 See 'Head, closed branch'.
5287
5288 Closed branch
5289 See 'Branch, closed'.
5290
5291 Clone (Noun) An entire or partial copy of a repository. The partial
5292 clone must be in the form of a revision and its ancestors.
5293
5294 Example: "Is your clone up to date?"
5295
5296 (Verb) The process of creating a clone, using hg clone.
5297
5298 Example: "I'm going to clone the repository."
5299
5300 Closed branch head
5301 See 'Head, closed branch'.
5302
5303 Commit (Noun) A synonym for changeset.
5304
5305 Example: "Is the bug fixed in your recent commit?"
5306
5307 (Verb) The act of recording changes to a repository. When files
5308 are committed in a working directory, Mercurial finds the dif‐
5309 ferences between the committed files and their parent changeset,
5310 creating a new changeset in the repository.
5311
5312 Example: "You should commit those changes now."
5313
5314 Cset A common abbreviation of the term changeset.
5315
5316 DAG The repository of changesets of a distributed version control
5317 system (DVCS) can be described as a directed acyclic graph
5318 (DAG), consisting of nodes and edges, where nodes correspond to
5319 changesets and edges imply a parent -> child relation. This
5320 graph can be visualized by graphical tools such as hg log
5321 --graph. In Mercurial, the DAG is limited by the requirement for
5322 children to have at most two parents.
5323
5324 Deprecated
5325 Feature removed from documentation, but not scheduled for re‐
5326 moval.
5327
5328 Default branch
5329 See 'Branch, default'.
5330
5331 Descendant
5332 Any changeset that can be reached by a chain of child changesets
5333 from a given changeset. More precisely, the descendants of a
5334 changeset can be defined by two properties: the child of a
5335 changeset is a descendant, and the child of a descendant is a
5336 descendant. See also: 'Ancestor'.
5337
5338 Diff (Noun) The difference between the contents and attributes of
5339 files in two changesets or a changeset and the current working
5340 directory. The difference is usually represented in a standard
5341 form called a "diff" or "patch". The "git diff" format is used
5342 when the changes include copies, renames, or changes to file at‐
5343 tributes, none of which can be represented/handled by classic
5344 "diff" and "patch".
5345
5346 Example: "Did you see my correction in the diff?"
5347
5348 (Verb) Diffing two changesets is the action of creating a diff
5349 or patch.
5350
5351 Example: "If you diff with changeset X, you will see what I
5352 mean."
5353
5354 Directory, working
5355 The working directory represents the state of the files tracked
5356 by Mercurial, that will be recorded in the next commit. The
5357 working directory initially corresponds to the snapshot at an
5358 existing changeset, known as the parent of the working direc‐
5359 tory. See 'Parent, working directory'. The state may be modified
5360 by changes to the files introduced manually or by a merge. The
5361 repository metadata exists in the .hg directory inside the work‐
5362 ing directory.
5363
5364 Draft Changesets in the draft phase have not been shared with publish‐
5365 ing repositories and may thus be safely changed by history-modi‐
5366 fying extensions. See hg help phases.
5367
5368 Experimental
5369 Feature that may change or be removed at a later date.
5370
5371 Graph See DAG and hg log --graph.
5372
5373 Head The term 'head' may be used to refer to both a branch head or a
5374 repository head, depending on the context. See 'Head, branch'
5375 and 'Head, repository' for specific definitions.
5376
5377 Heads are where development generally takes place and are the
5378 usual targets for update and merge operations.
5379
5380 Head, branch
5381 A changeset with no descendants on the same named branch.
5382
5383 Head, closed branch
5384 A changeset that marks a head as no longer interesting. The
5385 closed head is no longer listed by hg heads. A branch is consid‐
5386 ered closed when all its heads are closed and consequently is
5387 not listed by hg branches.
5388
5389 Closed heads can be re-opened by committing new changeset as the
5390 child of the changeset that marks a head as closed.
5391
5392 Head, repository
5393 A topological head which has not been closed.
5394
5395 Head, topological
5396 A changeset with no children in the repository.
5397
5398 History, immutable
5399 Once committed, changesets cannot be altered. Extensions which
5400 appear to change history actually create new changesets that re‐
5401 place existing ones, and then destroy the old changesets. Doing
5402 so in public repositories can result in old changesets being
5403 reintroduced to the repository.
5404
5405 History, rewriting
5406 The changesets in a repository are immutable. However, exten‐
5407 sions to Mercurial can be used to alter the repository, usually
5408 in such a way as to preserve changeset contents.
5409
5410 Immutable history
5411 See 'History, immutable'.
5412
5413 Merge changeset
5414 See 'Changeset, merge'.
5415
5416 Manifest
5417 Each changeset has a manifest, which is the list of files that
5418 are tracked by the changeset.
5419
5420 Merge Used to bring together divergent branches of work. When you up‐
5421 date to a changeset and then merge another changeset, you bring
5422 the history of the latter changeset into your working directory.
5423 Once conflicts are resolved (and marked), this merge may be com‐
5424 mitted as a merge changeset, bringing two branches together in
5425 the DAG.
5426
5427 Named branch
5428 See 'Branch, named'.
5429
5430 Null changeset
5431 The empty changeset. It is the parent state of newly-initialized
5432 repositories and repositories with no checked out revision. It
5433 is thus the parent of root changesets and the effective ancestor
5434 when merging unrelated changesets. Can be specified by the alias
5435 'null' or by the changeset ID '000000000000'.
5436
5437 Parent See 'Changeset, parent'.
5438
5439 Parent changeset
5440 See 'Changeset, parent'.
5441
5442 Parent, working directory
5443 The working directory parent reflects a virtual revision which
5444 is the child of the changeset (or two changesets with an uncom‐
5445 mitted merge) shown by hg parents. This is changed with hg up‐
5446 date. Other commands to see the working directory parent are hg
5447 summary and hg id. Can be specified by the alias ".".
5448
5449 Patch (Noun) The product of a diff operation.
5450
5451 Example: "I've sent you my patch."
5452
5453 (Verb) The process of using a patch file to transform one
5454 changeset into another.
5455
5456 Example: "You will need to patch that revision."
5457
5458 Phase A per-changeset state tracking how the changeset has been or
5459 should be shared. See hg help phases.
5460
5461 Public Changesets in the public phase have been shared with publishing
5462 repositories and are therefore considered immutable. See hg help
5463 phases.
5464
5465 Pull An operation in which changesets in a remote repository which
5466 are not in the local repository are brought into the local
5467 repository. Note that this operation without special arguments
5468 only updates the repository, it does not update the files in the
5469 working directory. See hg help pull.
5470
5471 Push An operation in which changesets in a local repository which are
5472 not in a remote repository are sent to the remote repository.
5473 Note that this operation only adds changesets which have been
5474 committed locally to the remote repository. Uncommitted changes
5475 are not sent. See hg help push.
5476
5477 Repository
5478 The metadata describing all recorded states of a collection of
5479 files. Each recorded state is represented by a changeset. A
5480 repository is usually (but not always) found in the .hg subdi‐
5481 rectory of a working directory. Any recorded state can be recre‐
5482 ated by "updating" a working directory to a specific changeset.
5483
5484 Repository head
5485 See 'Head, repository'.
5486
5487 Revision
5488 A state of the repository at some point in time. Earlier revi‐
5489 sions can be updated to by using hg update. See also 'Revision
5490 number'; See also 'Changeset'.
5491
5492 Revision number
5493 This integer uniquely identifies a changeset in a specific
5494 repository. It represents the order in which changesets were
5495 added to a repository, starting with revision number 0. Note
5496 that the revision number may be different in each clone of a
5497 repository. To identify changesets uniquely between different
5498 clones, see 'Changeset id'.
5499
5500 Revlog History storage mechanism used by Mercurial. It is a form of
5501 delta encoding, with occasional full revision of data followed
5502 by delta of each successive revision. It includes data and an
5503 index pointing to the data.
5504
5505 Rewriting history
5506 See 'History, rewriting'.
5507
5508 Root A changeset that has only the null changeset as its parent. Most
5509 repositories have only a single root changeset.
5510
5511 Secret Changesets in the secret phase may not be shared via push, pull,
5512 or clone. See hg help phases.
5513
5514 Tag An alternative name given to a changeset. Tags can be used in
5515 all places where Mercurial expects a changeset ID, e.g., with hg
5516 update. The creation of a tag is stored in the history and will
5517 thus automatically be shared with other using push and pull.
5518
5519 Tip The changeset with the highest revision number. It is the
5520 changeset most recently added in a repository.
5521
5522 Tip, branch
5523 The head of a given branch with the highest revision number.
5524 When a branch name is used as a revision identifier, it refers
5525 to the branch tip. See also 'Branch, head'. Note that because
5526 revision numbers may be different in different repository
5527 clones, the branch tip may be different in different cloned
5528 repositories.
5529
5530 Update (Noun) Another synonym of changeset.
5531
5532 Example: "I've pushed an update."
5533
5534 (Verb) This term is usually used to describe updating the state
5535 of the working directory to that of a specific changeset. See hg
5536 help update.
5537
5538 Example: "You should update."
5539
5540 Working directory
5541 See 'Directory, working'.
5542
5543 Working directory parent
5544 See 'Parent, working directory'.
5545
5547 Synopsis
5548 The Mercurial system uses a file called .hgignore in the root directory
5549 of a repository to control its behavior when it searches for files that
5550 it is not currently tracking.
5551
5552 Description
5553 The working directory of a Mercurial repository will often contain
5554 files that should not be tracked by Mercurial. These include backup
5555 files created by editors and build products created by compilers.
5556 These files can be ignored by listing them in a .hgignore file in the
5557 root of the working directory. The .hgignore file must be created manu‐
5558 ally. It is typically put under version control, so that the settings
5559 will propagate to other repositories with push and pull.
5560
5561 An untracked file is ignored if its path relative to the repository
5562 root directory, or any prefix path of that path, is matched against any
5563 pattern in .hgignore.
5564
5565 For example, say we have an untracked file, file.c, at a/b/file.c in‐
5566 side our repository. Mercurial will ignore file.c if any pattern in
5567 .hgignore matches a/b/file.c, a/b or a.
5568
5569 In addition, a Mercurial configuration file can reference a set of
5570 per-user or global ignore files. See the ignore configuration key on
5571 the [ui] section of hg help config for details of how to configure
5572 these files.
5573
5574 To control Mercurial's handling of files that it manages, many commands
5575 support the -I and -X options; see hg help <command> and hg help pat‐
5576 terns for details.
5577
5578 Files that are already tracked are not affected by .hgignore, even if
5579 they appear in .hgignore. An untracked file X can be explicitly added
5580 with hg add X, even if X would be excluded by a pattern in .hgignore.
5581
5582 Syntax
5583 An ignore file is a plain text file consisting of a list of patterns,
5584 with one pattern per line. Empty lines are skipped. The # character is
5585 treated as a comment character, and the \ character is treated as an
5586 escape character.
5587
5588 Mercurial supports several pattern syntaxes. The default syntax used is
5589 Python/Perl-style regular expressions.
5590
5591 To change the syntax used, use a line of the following form:
5592
5593 syntax: NAME
5594
5595 where NAME is one of the following:
5596
5597 regexp
5598
5599 Regular expression, Python/Perl syntax.
5600
5601 glob
5602
5603 Shell-style glob.
5604
5605 rootglob
5606
5607 A variant of glob that is rooted (see below).
5608
5609 The chosen syntax stays in effect when parsing all patterns that fol‐
5610 low, until another syntax is selected.
5611
5612 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
5613 the form *.c will match a file ending in .c in any directory, and a
5614 regexp pattern of the form \.c$ will do the same. To root a regexp pat‐
5615 tern, start it with ^. To get the same effect with glob-syntax, you
5616 have to use rootglob.
5617
5618 Subdirectories can have their own .hgignore settings by adding subin‐
5619 clude:path/to/subdir/.hgignore to the root .hgignore. See hg help pat‐
5620 terns for details on subinclude: and include:.
5621
5622 Note Patterns specified in other than .hgignore are always rooted.
5623 Please see hg help patterns for details.
5624
5625 Example
5626 Here is an example ignore file.
5627
5628 # use glob syntax.
5629 syntax: glob
5630
5631 *.elc
5632 *.pyc
5633 *~
5634
5635 # switch to regexp syntax.
5636 syntax: regexp
5637 ^\.pc/
5638
5639 Debugging
5640 Use the debugignore command to see if and why a file is ignored, or to
5641 see the combined ignore pattern. See hg help debugignore for details.
5642
5644 Mercurial's internal web server, hgweb, can serve either a single
5645 repository, or a tree of repositories. In the second case, repository
5646 paths and global options can be defined using a dedicated configuration
5647 file common to hg serve, hgweb.wsgi, hgweb.cgi and hgweb.fcgi.
5648
5649 This file uses the same syntax as other Mercurial configuration files
5650 but recognizes only the following sections:
5651
5652 • web
5653
5654 • paths
5655
5656 • collections
5657
5658 The web options are thoroughly described in hg help config.
5659
5660 The paths section maps URL paths to paths of repositories in the
5661 filesystem. hgweb will not expose the filesystem directly - only Mercu‐
5662 rial repositories can be published and only according to the configura‐
5663 tion.
5664
5665 The left hand side is the path in the URL. Note that hgweb reserves
5666 subpaths like rev or file, try using different names for nested reposi‐
5667 tories to avoid confusing effects.
5668
5669 The right hand side is the path in the filesystem. If the specified
5670 path ends with * or ** the filesystem will be searched recursively for
5671 repositories below that point. With * it will not recurse into the
5672 repositories it finds (except for .hg/patches). With ** it will also
5673 search inside repository working directories and possibly find sub‐
5674 repositories.
5675
5676 In this example:
5677
5678 [paths]
5679 /projects/a = /srv/tmprepos/a
5680 /projects/b = c:/repos/b
5681 / = /srv/repos/*
5682 /user/bob = /home/bob/repos/**
5683
5684 • The first two entries make two repositories in different directories
5685 appear under the same directory in the web interface
5686
5687 • The third entry will publish every Mercurial repository found in
5688 /srv/repos/, for instance the repository /srv/repos/quux/ will appear
5689 as http://server/quux/
5690
5691 • The fourth entry will publish both http://server/user/bob/quux/ and
5692 http://server/user/bob/quux/testsubrepo/
5693
5694 The collections section is deprecated and has been superseded by paths.
5695
5696 URLs and Common Arguments
5697 URLs under each repository have the form /{command}[/{arguments}] where
5698 {command} represents the name of a command or handler and {arguments}
5699 represents any number of additional URL parameters to that command.
5700
5701 The web server has a default style associated with it. Styles map to a
5702 collection of named templates. Each template is used to render a spe‐
5703 cific piece of data, such as a changeset or diff.
5704
5705 The style for the current request can be overridden two ways. First, if
5706 {command} contains a hyphen (-), the text before the hyphen defines the
5707 style. For example, /atom-log will render the log command handler with
5708 the atom style. The second way to set the style is with the style query
5709 string argument. For example, /log?style=atom. The hyphenated URL pa‐
5710 rameter is preferred.
5711
5712 Not all templates are available for all styles. Attempting to use a
5713 style that doesn't have all templates defined may result in an error
5714 rendering the page.
5715
5716 Many commands take a {revision} URL parameter. This defines the change‐
5717 set to operate on. This is commonly specified as the short, 12 digit
5718 hexadecimal abbreviation for the full 40 character unique revision
5719 identifier. However, any value described by hg help revisions typically
5720 works.
5721
5722 Commands and URLs
5723 The following web commands and their URLs are available:
5724
5725 /annotate/{revision}/{path}
5726 Show changeset information for each line in a file.
5727
5728 The ignorews, ignorewsamount, ignorewseol, and ignoreblanklines query
5729 string arguments have the same meaning as their [annotate] config
5730 equivalents. It uses the hgrc boolean parsing logic to interpret the
5731 value. e.g. 0 and false are false and 1 and true are true. If not de‐
5732 fined, the server default settings are used.
5733
5734 The fileannotate template is rendered.
5735
5736 /archive/{revision}.{format}[/{path}]
5737 Obtain an archive of repository content.
5738
5739 The content and type of the archive is defined by a URL path parameter.
5740 format is the file extension of the archive type to be generated. e.g.
5741 zip or tar.bz2. Not all archive types may be allowed by your server
5742 configuration.
5743
5744 The optional path URL parameter controls content to include in the ar‐
5745 chive. If omitted, every file in the specified revision is present in
5746 the archive. If included, only the specified file or contents of the
5747 specified directory will be included in the archive.
5748
5749 No template is used for this handler. Raw, binary content is generated.
5750
5751 /bookmarks
5752 Show information about bookmarks.
5753
5754 No arguments are accepted.
5755
5756 The bookmarks template is rendered.
5757
5758 /branches
5759 Show information about branches.
5760
5761 All known branches are contained in the output, even closed branches.
5762
5763 No arguments are accepted.
5764
5765 The branches template is rendered.
5766
5767 /changelog[/{revision}]
5768 Show information about multiple changesets.
5769
5770 If the optional revision URL argument is absent, information about all
5771 changesets starting at tip will be rendered. If the revision argument
5772 is present, changesets will be shown starting from the specified revi‐
5773 sion.
5774
5775 If revision is absent, the rev query string argument may be defined.
5776 This will perform a search for changesets.
5777
5778 The argument for rev can be a single revision, a revision set, or a
5779 literal keyword to search for in changeset data (equivalent to hg log
5780 -k).
5781
5782 The revcount query string argument defines the maximum numbers of
5783 changesets to render.
5784
5785 For non-searches, the changelog template will be rendered.
5786
5787 /changeset[/{revision}]
5788 Show information about a single changeset.
5789
5790 A URL path argument is the changeset identifier to show. See hg help
5791 revisions for possible values. If not defined, the tip changeset will
5792 be shown.
5793
5794 The changeset template is rendered. Contents of the changesettag,
5795 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5796 lated to diffs may all be used to produce the output.
5797
5798 /comparison/{revision}/{path}
5799 Show a comparison between the old and new versions of a file from
5800 changes made on a particular revision.
5801
5802 This is similar to the diff handler. However, this form features a
5803 split or side-by-side diff rather than a unified diff.
5804
5805 The context query string argument can be used to control the lines of
5806 context in the diff.
5807
5808 The filecomparison template is rendered.
5809
5810 /diff/{revision}/{path}
5811 Show how a file changed in a particular commit.
5812
5813 The filediff template is rendered.
5814
5815 This handler is registered under both the /diff and /filediff paths.
5816 /diff is used in modern code.
5817
5818 /file/{revision}[/{path}]
5819 Show information about a directory or file in the repository.
5820
5821 Info about the path given as a URL parameter will be rendered.
5822
5823 If path is a directory, information about the entries in that directory
5824 will be rendered. This form is equivalent to the manifest handler.
5825
5826 If path is a file, information about that file will be shown via the
5827 filerevision template.
5828
5829 If path is not defined, information about the root directory will be
5830 rendered.
5831
5832 /diff/{revision}/{path}
5833 Show how a file changed in a particular commit.
5834
5835 The filediff template is rendered.
5836
5837 This handler is registered under both the /diff and /filediff paths.
5838 /diff is used in modern code.
5839
5840 /filelog/{revision}/{path}
5841 Show information about the history of a file in the repository.
5842
5843 The revcount query string argument can be defined to control the maxi‐
5844 mum number of entries to show.
5845
5846 The filelog template will be rendered.
5847
5848 /graph[/{revision}]
5849 Show information about the graphical topology of the repository.
5850
5851 Information rendered by this handler can be used to create visual rep‐
5852 resentations of repository topology.
5853
5854 The revision URL parameter controls the starting changeset. If it's ab‐
5855 sent, the default is tip.
5856
5857 The revcount query string argument can define the number of changesets
5858 to show information for.
5859
5860 The graphtop query string argument can specify the starting changeset
5861 for producing jsdata variable that is used for rendering graph in Java‐
5862 Script. By default it has the same value as revision.
5863
5864 This handler will render the graph template.
5865
5866 /help[/{topic}]
5867 Render help documentation.
5868
5869 This web command is roughly equivalent to hg help. If a topic is de‐
5870 fined, that help topic will be rendered. If not, an index of available
5871 help topics will be rendered.
5872
5873 The help template will be rendered when requesting help for a topic.
5874 helptopics will be rendered for the index of help topics.
5875
5876 /log[/{revision}[/{path}]]
5877 Show repository or file history.
5878
5879 For URLs of the form /log/{revision}, a list of changesets starting at
5880 the specified changeset identifier is shown. If {revision} is not de‐
5881 fined, the default is tip. This form is equivalent to the changelog
5882 handler.
5883
5884 For URLs of the form /log/{revision}/{file}, the history for a specific
5885 file will be shown. This form is equivalent to the filelog handler.
5886
5887 /manifest[/{revision}[/{path}]]
5888 Show information about a directory.
5889
5890 If the URL path arguments are omitted, information about the root di‐
5891 rectory for the tip changeset will be shown.
5892
5893 Because this handler can only show information for directories, it is
5894 recommended to use the file handler instead, as it can handle both di‐
5895 rectories and files.
5896
5897 The manifest template will be rendered for this handler.
5898
5899 /changeset[/{revision}]
5900 Show information about a single changeset.
5901
5902 A URL path argument is the changeset identifier to show. See hg help
5903 revisions for possible values. If not defined, the tip changeset will
5904 be shown.
5905
5906 The changeset template is rendered. Contents of the changesettag,
5907 changesetbookmark, filenodelink, filenolink, and the many templates re‐
5908 lated to diffs may all be used to produce the output.
5909
5910 /shortlog
5911 Show basic information about a set of changesets.
5912
5913 This accepts the same parameters as the changelog handler. The only
5914 difference is the shortlog template will be rendered instead of the
5915 changelog template.
5916
5917 /summary
5918 Show a summary of repository state.
5919
5920 Information about the latest changesets, bookmarks, tags, and branches
5921 is captured by this handler.
5922
5923 The summary template is rendered.
5924
5925 /tags
5926 Show information about tags.
5927
5928 No arguments are accepted.
5929
5930 The tags template is rendered.
5931
5933 To access a subtopic, use "hg help internals.{subtopic-name}"
5934
5935 bid-merge
5936 Bid Merge Algorithm
5937
5938 bundle2
5939 Bundle2
5940
5941 bundles
5942 Bundles
5943
5944 cbor CBOR
5945
5946 censor Censor
5947
5948 changegroups
5949 Changegroups
5950
5951 config Config Registrar
5952
5953 dirstate-v2
5954 dirstate-v2 file format
5955
5956 extensions
5957 Extension API
5958
5959 mergestate
5960 Mergestate
5961
5962 requirements
5963 Repository Requirements
5964
5965 revlogs
5966 Revision Logs
5967
5968 wireprotocol
5969 Wire Protocol
5970
5971 wireprotocolrpc
5972 Wire Protocol RPC
5973
5974 wireprotocolv2
5975 Wire Protocol Version 2
5976
5978 To merge files Mercurial uses merge tools.
5979
5980 A merge tool combines two different versions of a file into a merged
5981 file. Merge tools are given the two files and the greatest common an‐
5982 cestor of the two file versions, so they can determine the changes made
5983 on both branches.
5984
5985 Merge tools are used both for hg resolve, hg merge, hg update, hg back‐
5986 out and in several extensions.
5987
5988 Usually, the merge tool tries to automatically reconcile the files by
5989 combining all non-overlapping changes that occurred separately in the
5990 two different evolutions of the same initial base file. Furthermore,
5991 some interactive merge programs make it easier to manually resolve con‐
5992 flicting merges, either in a graphical way, or by inserting some con‐
5993 flict markers. Mercurial does not include any interactive merge pro‐
5994 grams but relies on external tools for that.
5995
5996 Available merge tools
5997 External merge tools and their properties are configured in the
5998 merge-tools configuration section - see hgrc(5) - but they can often
5999 just be named by their executable.
6000
6001 A merge tool is generally usable if its executable can be found on the
6002 system and if it can handle the merge. The executable is found if it is
6003 an absolute or relative executable path or the name of an application
6004 in the executable search path. The tool is assumed to be able to handle
6005 the merge if it can handle symlinks if the file is a symlink, if it can
6006 handle binary files if the file is binary, and if a GUI is available if
6007 the tool requires a GUI.
6008
6009 There are some internal merge tools which can be used. The internal
6010 merge tools are:
6011
6012 :dump
6013
6014 Creates three versions of the files to merge, containing the
6015 contents of local, other and base. These files can then be used
6016 to perform a merge manually. If the file to be merged is named
6017 a.txt, these files will accordingly be named a.txt.local,
6018 a.txt.other and a.txt.base and they will be placed in the same
6019 directory as a.txt.
6020
6021 This implies premerge. Therefore, files aren't dumped, if pre‐
6022 merge runs successfully. Use :forcedump to forcibly write files
6023 out.
6024
6025 (actual capabilities: binary, symlink)
6026
6027 :fail
6028
6029 Rather than attempting to merge files that were modified on both
6030 branches, it marks them as unresolved. The resolve command must
6031 be used to resolve these conflicts.
6032
6033 (actual capabilities: binary, symlink)
6034
6035 :forcedump
6036
6037 Creates three versions of the files as same as :dump, but omits
6038 premerge.
6039
6040 (actual capabilities: binary, symlink)
6041
6042 :local
6043
6044 Uses the local p1() version of files as the merged version.
6045
6046 (actual capabilities: binary, symlink)
6047
6048 :merge
6049
6050 Uses the internal non-interactive simple merge algorithm for
6051 merging files. It will fail if there are any conflicts and leave
6052 markers in the partially merged file. Markers will have two sec‐
6053 tions, one for each side of merge.
6054
6055 :merge-local
6056
6057 Like :merge, but resolve all conflicts non-interactively in fa‐
6058 vor of the local p1() changes.
6059
6060 :merge-other
6061
6062 Like :merge, but resolve all conflicts non-interactively in fa‐
6063 vor of the other p2() changes.
6064
6065 :merge3
6066
6067 Uses the internal non-interactive simple merge algorithm for
6068 merging files. It will fail if there are any conflicts and leave
6069 markers in the partially merged file. Marker will have three
6070 sections, one from each side of the merge and one for the base
6071 content.
6072
6073 :mergediff
6074
6075 Uses the internal non-interactive simple merge algorithm for
6076 merging files. It will fail if there are any conflicts and leave
6077 markers in the partially merged file. The marker will have two
6078 sections, one with the content from one side of the merge, and
6079 one with a diff from the base content to the content on the
6080 other side. (experimental)
6081
6082 :other
6083
6084 Uses the other p2() version of files as the merged version.
6085
6086 (actual capabilities: binary, symlink)
6087
6088 :prompt
6089
6090 Asks the user which of the local p1() or the other p2() version
6091 to keep as the merged version.
6092
6093 (actual capabilities: binary, symlink)
6094
6095 :tagmerge
6096
6097 Uses the internal tag merge algorithm (experimental).
6098
6099 :union
6100
6101 Uses the internal non-interactive simple merge algorithm for
6102 merging files. It will use both left and right sides for con‐
6103 flict regions. No markers are inserted.
6104
6105 Internal tools are always available and do not require a GUI but will
6106 by default not handle symlinks or binary files. See next section for
6107 detail about "actual capabilities" described above.
6108
6109 Choosing a merge tool
6110 Mercurial uses these rules when deciding which merge tool to use:
6111
6112 1. If a tool has been specified with the --tool option to merge or re‐
6113 solve, it is used. If it is the name of a tool in the merge-tools
6114 configuration, its configuration is used. Otherwise the specified
6115 tool must be executable by the shell.
6116
6117 2. If the HGMERGE environment variable is present, its value is used
6118 and must be executable by the shell.
6119
6120 3. If the filename of the file to be merged matches any of the patterns
6121 in the merge-patterns configuration section, the first usable merge
6122 tool corresponding to a matching pattern is used.
6123
6124 4. If ui.merge is set it will be considered next. If the value is not
6125 the name of a configured tool, the specified value is used and must
6126 be executable by the shell. Otherwise the named tool is used if it
6127 is usable.
6128
6129 5. If any usable merge tools are present in the merge-tools configura‐
6130 tion section, the one with the highest priority is used.
6131
6132 6. If a program named hgmerge can be found on the system, it is used -
6133 but it will by default not be used for symlinks and binary files.
6134
6135 7. If the file to be merged is not binary and is not a symlink, then
6136 internal :merge is used.
6137
6138 8. Otherwise, :prompt is used.
6139
6140 For historical reason, Mercurial treats merge tools as below while ex‐
6141 amining rules above.
6142
6143 ┌───────────┬────────────────┬────────┬─────────┐
6144 │step │ specified via │ binary │ symlink │
6145 ├───────────┼────────────────┼────────┼─────────┤
6146 │ │ --tool │ o/o │ o/o │
6147 │ 1. │ │ │ │
6148 ├───────────┼────────────────┼────────┼─────────┤
6149 │ │ HGMERGE │ o/o │ o/o │
6150 │ 2. │ │ │ │
6151 ├───────────┼────────────────┼────────┼─────────┤
6152 │ │ merge-patterns │ o/o(*) │ x/?(*) │
6153 │ 3. │ │ │ │
6154 ├───────────┼────────────────┼────────┼─────────┤
6155 │ │ ui.merge │ x/?(*) │ x/?(*) │
6156 │ 4. │ │ │ │
6157 └───────────┴────────────────┴────────┴─────────┘
6158
6159 Each capability column indicates Mercurial behavior for internal/exter‐
6160 nal merge tools at examining each rule.
6161
6162 • "o": "assume that a tool has capability"
6163
6164 • "x": "assume that a tool does not have capability"
6165
6166 • "?": "check actual capability of a tool"
6167
6168 If merge.strict-capability-check configuration is true, Mercurial
6169 checks capabilities of merge tools strictly in (*) cases above (= each
6170 capability column becomes "?/?"). It is false by default for backward
6171 compatibility.
6172
6173 Note After selecting a merge program, Mercurial will by default at‐
6174 tempt to merge the files using a simple merge algorithm first.
6175 Only if it doesn't succeed because of conflicting changes will
6176 Mercurial actually execute the merge program. Whether to use the
6177 simple merge algorithm first can be controlled by the premerge
6178 setting of the merge tool. Premerge is enabled by default unless
6179 the file is binary or a symlink.
6180
6181 See the merge-tools and ui sections of hgrc(5) for details on the con‐
6182 figuration of merge tools.
6183
6185 Some Mercurial commands can produce a lot of output, and Mercurial will
6186 attempt to use a pager to make those commands more pleasant.
6187
6188 To set the pager that should be used, set the application variable:
6189
6190 [pager]
6191 pager = less -FRX
6192
6193 If no pager is set in the user or repository configuration, Mercurial
6194 uses the environment variable $PAGER. If $PAGER is not set, pager.pager
6195 from the default or system configuration is used. If none of these are
6196 set, a default pager will be used, typically less on Unix and more on
6197 Windows.
6198
6199 On Windows, more is not color aware, so using it effectively disables
6200 color. MSYS and Cygwin shells provide less as a pager, which can be
6201 configured to support ANSI color codes. See hg help con‐
6202 fig.color.pagermode to configure the color mode when invoking a pager.
6203
6204 You can disable the pager for certain commands by adding them to the
6205 pager.ignore list:
6206
6207 [pager]
6208 ignore = version, help, update
6209
6210 To ignore global commands like hg version or hg help, you have to spec‐
6211 ify them in your user configuration file.
6212
6213 To control whether the pager is used at all for an individual command,
6214 you can use --pager=<value>:
6215
6216 • use as needed: auto.
6217
6218 • require the pager: yes or on.
6219
6220 • suppress the pager: no or off (any unrecognized value will also
6221 work).
6222
6223 To globally turn off all attempts to use a pager, set:
6224
6225 [ui]
6226 paginate = never
6227
6228 which will prevent the pager from running.
6229
6231 Mercurial accepts several notations for identifying one or more files
6232 at a time.
6233
6234 By default, Mercurial treats filenames verbatim without pattern match‐
6235 ing, relative to the current working directory. Note that your system
6236 shell might perform pattern matching of its own before passing file‐
6237 names into Mercurial.
6238
6239 Alternate pattern notations must be specified explicitly.
6240
6241 Note Patterns specified in .hgignore are not rooted. Please see hg
6242 help hgignore for details.
6243
6244 To use a plain path name without any pattern matching, start it with
6245 path:. These path names must completely match starting at the current
6246 repository root, and when the path points to a directory, it is matched
6247 recursively. To match all files in a directory non-recursively (not in‐
6248 cluding any files in subdirectories), rootfilesin: can be used, speci‐
6249 fying an absolute path (relative to the repository root).
6250
6251 To use an extended glob, start a name with glob:. Globs are rooted at
6252 the current directory; a glob such as *.c will only match files in the
6253 current directory ending with .c. rootglob: can be used instead of
6254 glob: for a glob that is rooted at the root of the repository.
6255
6256 The supported glob syntax extensions are ** to match any string across
6257 path separators and {a,b} to mean "a or b".
6258
6259 To use a Perl/Python regular expression, start a name with re:. Regexp
6260 pattern matching is anchored at the root of the repository.
6261
6262 To read name patterns from a file, use listfile: or listfile0:. The
6263 latter expects null delimited patterns while the former expects line
6264 feeds. Each string read from the file is itself treated as a file pat‐
6265 tern.
6266
6267 To read a set of patterns from a file, use include: or subinclude:.
6268 include: will use all the patterns from the given file and treat them
6269 as if they had been passed in manually. subinclude: will only apply
6270 the patterns against files that are under the subinclude file's direc‐
6271 tory. See hg help hgignore for details on the format of these files.
6272
6273 All patterns, except for glob: specified in command line (not for -I or
6274 -X options), can match also against directories: files under matched
6275 directories are treated as matched. For -I and -X options, glob: will
6276 match directories recursively.
6277
6278 Plain examples:
6279
6280 path:foo/bar a name bar in a directory named foo in the root
6281 of the repository
6282 path:path:name a file or directory named "path:name"
6283 rootfilesin:foo/bar the files in a directory called foo/bar, but not any files
6284 in its subdirectories and not a file bar in directory foo
6285
6286 Glob examples:
6287
6288 glob:*.c any name ending in ".c" in the current directory
6289 *.c any name ending in ".c" in the current directory
6290 **.c any name ending in ".c" in any subdirectory of the
6291 current directory including itself.
6292 foo/* any file in directory foo
6293 foo/** any file in directory foo plus all its subdirectories,
6294 recursively
6295 foo/*.c any name ending in ".c" in the directory foo
6296 foo/**.c any name ending in ".c" in any subdirectory of foo
6297 including itself.
6298 rootglob:*.c any name ending in ".c" in the root of the repository
6299
6300 Regexp examples:
6301
6302 re:.*\.c$ any name ending in ".c", anywhere in the repository
6303
6304 File examples:
6305
6306 listfile:list.txt read list from list.txt with one file pattern per line
6307 listfile0:list.txt read list from list.txt with null byte delimiters
6308
6309 See also hg help filesets.
6310
6311 Include examples:
6312
6313 include:path/to/mypatternfile reads patterns to be applied to all paths
6314 subinclude:path/to/subignorefile reads patterns specifically for paths in the
6315 subdirectory
6316
6318 What are phases?
6319 Phases are a system for tracking which changesets have been or should
6320 be shared. This helps prevent common mistakes when modifying history
6321 (for instance, with the mq or rebase extensions).
6322
6323 Each changeset in a repository is in one of the following phases:
6324
6325 • public : changeset is visible on a public server
6326
6327 • draft : changeset is not yet published
6328
6329 • secret : changeset should not be pushed, pulled, or cloned
6330
6331 These phases are ordered (public < draft < secret) and no changeset can
6332 be in a lower phase than its ancestors. For instance, if a changeset is
6333 public, all its ancestors are also public. Lastly, changeset phases
6334 should only be changed towards the public phase.
6335
6336 How are phases managed?
6337 For the most part, phases should work transparently. By default, a
6338 changeset is created in the draft phase and is moved into the public
6339 phase when it is pushed to another repository.
6340
6341 Once changesets become public, extensions like mq and rebase will
6342 refuse to operate on them to prevent creating duplicate changesets.
6343 Phases can also be manually manipulated with the hg phase command if
6344 needed. See hg help -v phase for examples.
6345
6346 To make your commits secret by default, put this in your configuration
6347 file:
6348
6349 [phases]
6350 new-commit = secret
6351
6352 Phases and servers
6353 Normally, all servers are publishing by default. This means:
6354
6355 - all draft changesets that are pulled or cloned appear in phase
6356 public on the client
6357
6358 - all draft changesets that are pushed appear as public on both
6359 client and server
6360
6361 - secret changesets are neither pushed, pulled, or cloned
6362
6363 Note Pulling a draft changeset from a publishing server does not mark
6364 it as public on the server side due to the read-only nature of
6365 pull.
6366
6367 Sometimes it may be desirable to push and pull changesets in the draft
6368 phase to share unfinished work. This can be done by setting a reposi‐
6369 tory to disable publishing in its configuration file:
6370
6371 [phases]
6372 publish = False
6373
6374 See hg help config for more information on configuration files.
6375
6376 Note Servers running older versions of Mercurial are treated as pub‐
6377 lishing.
6378
6379 Note Changesets in secret phase are not exchanged with the server.
6380 This applies to their content: file names, file contents, and
6381 changeset metadata. For technical reasons, the identifier (e.g.
6382 d825e4025e39) of the secret changeset may be communicated to the
6383 server.
6384
6385 Examples
6386 • list changesets in draft or secret phase:
6387
6388 hg log -r "not public()"
6389
6390 • change all secret changesets to draft:
6391
6392 hg phase --draft "secret()"
6393
6394 • forcibly move the current changeset and descendants from public to
6395 draft:
6396
6397 hg phase --force --draft .
6398
6399 • show a list of changeset revisions and each corresponding phase:
6400
6401 hg log --template "{rev} {phase}\n"
6402
6403 • resynchronize draft changesets relative to a remote repository:
6404
6405 hg phase -fd "outgoing(URL)"
6406
6407 See hg help phase for more information on manually manipulating phases.
6408
6410 Mercurial supports several ways to specify revisions.
6411
6412 Specifying single revisions
6413 A plain integer is treated as a revision number. Negative integers are
6414 treated as sequential offsets from the tip, with -1 denoting the tip,
6415 -2 denoting the revision prior to the tip, and so forth.
6416
6417 A 40-digit hexadecimal string is treated as a unique revision identi‐
6418 fier. A hexadecimal string less than 40 characters long is treated as
6419 a unique revision identifier and is referred to as a short-form identi‐
6420 fier. A short-form identifier is only valid if it is the prefix of ex‐
6421 actly one full-length identifier.
6422
6423 Any other string is treated as a bookmark, tag, or branch name. A book‐
6424 mark is a movable pointer to a revision. A tag is a permanent name as‐
6425 sociated with a revision. A branch name denotes the tipmost open branch
6426 head of that branch - or if they are all closed, the tipmost closed
6427 head of the branch. Bookmark, tag, and branch names must not contain
6428 the ":" character.
6429
6430 The reserved name "tip" always identifies the most recent revision.
6431
6432 The reserved name "null" indicates the null revision. This is the revi‐
6433 sion of an empty repository, and the parent of revision 0.
6434
6435 The reserved name "." indicates the working directory parent. If no
6436 working directory is checked out, it is equivalent to null. If an un‐
6437 committed merge is in progress, "." is the revision of the first par‐
6438 ent.
6439
6440 Finally, commands that expect a single revision (like hg update) also
6441 accept revsets (see below for details). When given a revset, they use
6442 the last revision of the revset. A few commands accept two single revi‐
6443 sions (like hg diff). When given a revset, they use the first and the
6444 last revisions of the revset.
6445
6446 Specifying multiple revisions
6447 Mercurial supports a functional language for selecting a set of revi‐
6448 sions. Expressions in this language are called revsets.
6449
6450 The language supports a number of predicates which are joined by infix
6451 operators. Parenthesis can be used for grouping.
6452
6453 Identifiers such as branch names may need quoting with single or double
6454 quotes if they contain characters like - or if they match one of the
6455 predefined predicates.
6456
6457 Special characters can be used in quoted identifiers by escaping them,
6458 e.g., \n is interpreted as a newline. To prevent them from being inter‐
6459 preted, strings can be prefixed with r, e.g. r'...'.
6460
6461 Operators
6462 There is a single prefix operator:
6463
6464 not x
6465
6466 Changesets not in x. Short form is ! x.
6467
6468 These are the supported infix operators:
6469
6470 x::y
6471
6472 A DAG range, meaning all changesets that are descendants of x
6473 and ancestors of y, including x and y themselves. If the first
6474 endpoint is left out, this is equivalent to ancestors(y), if the
6475 second is left out it is equivalent to descendants(x).
6476
6477 An alternative syntax is x..y.
6478
6479 x:y
6480
6481 All changesets with revision numbers between x and y, both in‐
6482 clusive. Either endpoint can be left out, they default to 0 and
6483 tip.
6484
6485 x and y
6486
6487 The intersection of changesets in x and y. Short form is x & y.
6488
6489 x or y
6490
6491 The union of changesets in x and y. There are two alternative
6492 short forms: x | y and x + y.
6493
6494 x - y
6495
6496 Changesets in x but not in y.
6497
6498 x % y
6499
6500 Changesets that are ancestors of x but not ancestors of y (i.e.
6501 ::x - ::y). This is shorthand notation for only(x, y) (see be‐
6502 low). The second argument is optional and, if left out, is
6503 equivalent to only(x).
6504
6505 x^n
6506
6507 The nth parent of x, n == 0, 1, or 2. For n == 0, x; for n ==
6508 1, the first parent of each changeset in x; for n == 2, the sec‐
6509 ond parent of changeset in x.
6510
6511 x~n
6512
6513 The nth first ancestor of x; x~0 is x; x~3 is x^^^. For n < 0,
6514 the nth unambiguous descendent of x.
6515
6516 x ## y
6517
6518 Concatenate strings and identifiers into one string.
6519
6520 All other prefix, infix and postfix operators have lower prior‐
6521 ity than ##. For example, a1 ## a2~2 is equivalent to (a1 ##
6522 a2)~2.
6523
6524 For example:
6525
6526 [revsetalias]
6527 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
6528
6529 issue(1234) is equivalent to grep(r'\bissue[
6530 :]?1234\b|\bbug\(1234\)') in this case. This matches against all
6531 of "issue 1234", "issue:1234", "issue1234" and "bug(1234)".
6532
6533 There is a single postfix operator:
6534
6535 x^
6536
6537 Equivalent to x^1, the first parent of each changeset in x.
6538
6539 Patterns
6540 Where noted, predicates that perform string matching can accept a pat‐
6541 tern string. The pattern may be either a literal, or a regular expres‐
6542 sion. If the pattern starts with re:, the remainder of the pattern is
6543 treated as a regular expression. Otherwise, it is treated as a literal.
6544 To match a pattern that actually starts with re:, use the prefix lit‐
6545 eral:.
6546
6547 Matching is case-sensitive, unless otherwise noted. To perform a case-
6548 insensitive match on a case-sensitive predicate, use a regular expres‐
6549 sion, prefixed with (?i).
6550
6551 For example, tag(r're:(?i)release') matches "release" or "RELEASE" or
6552 "Release", etc.
6553
6554 Predicates
6555 The following predicates are supported:
6556
6557 adds(pattern)
6558
6559 Changesets that add a file matching pattern.
6560
6561 The pattern without explicit kind like glob: is expected to be
6562 relative to the current directory and match against a file or a
6563 directory.
6564
6565 all()
6566
6567 All changesets, the same as 0:tip.
6568
6569 ancestor(*changeset)
6570
6571 A greatest common ancestor of the changesets.
6572
6573 Accepts 0 or more changesets. Will return empty list when
6574 passed no args. Greatest common ancestor of a single changeset
6575 is that changeset.
6576
6577 ancestors(set[, depth])
6578
6579 Changesets that are ancestors of changesets in set, including
6580 the given changesets themselves.
6581
6582 If depth is specified, the result only includes changesets up to
6583 the specified generation.
6584
6585 author(string)
6586
6587 Alias for user(string).
6588
6589 bisect(string)
6590
6591 Changesets marked in the specified bisect status:
6592
6593 • good, bad, skip: csets explicitly marked as good/bad/skip
6594
6595 • goods, bads : csets topologically good/bad
6596
6597 • range : csets taking part in the bisection
6598
6599 • pruned : csets that are goods, bads or skipped
6600
6601 • untested : csets whose fate is yet unknown
6602
6603 • ignored : csets ignored due to DAG topology
6604
6605 • current : the cset currently being bisected
6606
6607 bookmark([name])
6608
6609 The named bookmark or all bookmarks.
6610
6611 Pattern matching is supported for name. See hg help revi‐
6612 sions.patterns.
6613
6614 branch(string or set)
6615
6616 All changesets belonging to the given branch or the branches of
6617 the given changesets.
6618
6619 Pattern matching is supported for string. See hg help revi‐
6620 sions.patterns.
6621
6622 branchpoint()
6623
6624 Changesets with more than one child.
6625
6626 bundle()
6627
6628 Changesets in the bundle.
6629
6630 Bundle must be specified by the -R option.
6631
6632 children(set)
6633
6634 Child changesets of changesets in set.
6635
6636 closed()
6637
6638 Changeset is closed.
6639
6640 commonancestors(set)
6641
6642 Changesets that are ancestors of every changeset in set.
6643
6644 conflictlocal()
6645
6646 The local side of the merge, if currently in an unresolved
6647 merge.
6648
6649 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6650 'hg graft'.
6651
6652 conflictother()
6653
6654 The other side of the merge, if currently in an unresolved
6655 merge.
6656
6657 "merge" here includes merge conflicts from e.g. 'hg rebase' or
6658 'hg graft'.
6659
6660 contains(pattern)
6661
6662 The revision's manifest contains a file matching pattern (but
6663 might not modify it). See hg help patterns for information about
6664 file patterns.
6665
6666 The pattern without explicit kind like glob: is expected to be
6667 relative to the current directory and match against a file ex‐
6668 actly for efficiency.
6669
6670 converted([id])
6671
6672 Changesets converted from the given identifier in the old repos‐
6673 itory if present, or all converted changesets if no identifier
6674 is specified.
6675
6676 date(interval)
6677
6678 Changesets within the interval, see hg help dates.
6679
6680 desc(string)
6681
6682 Search commit message for string. The match is case-insensitive.
6683
6684 Pattern matching is supported for string. See hg help revi‐
6685 sions.patterns.
6686
6687 descendants(set[, depth])
6688
6689 Changesets which are descendants of changesets in set, including
6690 the given changesets themselves.
6691
6692 If depth is specified, the result only includes changesets up to
6693 the specified generation.
6694
6695 destination([set])
6696
6697 Changesets that were created by a graft, transplant or rebase
6698 operation, with the given revisions specified as the source.
6699 Omitting the optional set is the same as passing all().
6700
6701 diffcontains(pattern)
6702
6703 Search revision differences for when the pattern was added or
6704 removed.
6705
6706 The pattern may be a substring literal or a regular expression.
6707 See hg help revisions.patterns.
6708
6709 draft()
6710
6711 Changeset in draft phase.
6712
6713 expectsize(set[, size])
6714
6715 Return the given revset if size matches the revset size. Abort
6716 if the revset doesn't expect given size. size can either be an
6717 integer range or an integer.
6718
6719 For example, expectsize(0:1, 3:5) will abort as revset size is 2
6720 and 2 is not between 3 and 5 inclusive.
6721
6722 extra(label, [value])
6723
6724 Changesets with the given label in the extra metadata, with the
6725 given optional value.
6726
6727 Pattern matching is supported for value. See hg help revi‐
6728 sions.patterns.
6729
6730 file(pattern)
6731
6732 Changesets affecting files matched by pattern.
6733
6734 For a faster but less accurate result, consider using filelog()
6735 instead.
6736
6737 This predicate uses glob: as the default kind of pattern.
6738
6739 filelog(pattern)
6740
6741 Changesets connected to the specified filelog.
6742
6743 For performance reasons, visits only revisions mentioned in the
6744 file-level filelog, rather than filtering through all changesets
6745 (much faster, but doesn't include deletes or duplicate changes).
6746 For a slower, more accurate result, use file().
6747
6748 The pattern without explicit kind like glob: is expected to be
6749 relative to the current directory and match against a file ex‐
6750 actly for efficiency.
6751
6752 first(set, [n])
6753
6754 An alias for limit().
6755
6756 follow([file[, startrev]])
6757
6758 An alias for ::. (ancestors of the working directory's first
6759 parent). If file pattern is specified, the histories of files
6760 matching given pattern in the revision given by startrev are
6761 followed, including copies.
6762
6763 followlines(file, fromline:toline[, startrev=., descend=False])
6764
6765 Changesets modifying file in line range ('fromline', 'toline').
6766
6767 Line range corresponds to 'file' content at 'startrev' and
6768 should hence be consistent with file size. If startrev is not
6769 specified, working directory's parent is used.
6770
6771 By default, ancestors of 'startrev' are returned. If 'descend'
6772 is True, descendants of 'startrev' are returned though renames
6773 are (currently) not followed in this direction.
6774
6775 grep(regex)
6776
6777 Like keyword(string) but accepts a regex. Use grep(r'...') to
6778 ensure special escape characters are handled correctly. Unlike
6779 keyword(string), the match is case-sensitive.
6780
6781 head()
6782
6783 Changeset is a named branch head.
6784
6785 heads(set)
6786
6787 Members of set with no children in set.
6788
6789 hidden()
6790
6791 Hidden changesets.
6792
6793 id(string)
6794
6795 Revision non-ambiguously specified by the given hex string pre‐
6796 fix.
6797
6798 keyword(string)
6799
6800 Search commit message, user name, and names of changed files for
6801 string. The match is case-insensitive.
6802
6803 For a regular expression or case sensitive search of these
6804 fields, use grep(regex).
6805
6806 last(set, [n])
6807
6808 Last n members of set, defaulting to 1.
6809
6810 limit(set[, n[, offset]])
6811
6812 First n members of set, defaulting to 1, starting from offset.
6813
6814 matching(revision [, field])
6815
6816 Changesets in which a given set of fields match the set of
6817 fields in the selected revision or set.
6818
6819 To match more than one field pass the list of fields to match
6820 separated by spaces (e.g. author description).
6821
6822 Valid fields are most regular revision fields and some special
6823 fields.
6824
6825 Regular revision fields are description, author, branch, date,
6826 files, phase, parents, substate, user and diff. Note that au‐
6827 thor and user are synonyms. diff refers to the contents of the
6828 revision. Two revisions matching their diff will also match
6829 their files.
6830
6831 Special fields are summary and metadata: summary matches the
6832 first line of the description. metadata is equivalent to match‐
6833 ing description user date (i.e. it matches the main metadata
6834 fields).
6835
6836 metadata is the default field which is used when no fields are
6837 specified. You can match more than one field at a time.
6838
6839 max(set)
6840
6841 Changeset with highest revision number in set.
6842
6843 merge()
6844
6845 Changeset is a merge changeset.
6846
6847 min(set)
6848
6849 Changeset with lowest revision number in set.
6850
6851 modifies(pattern)
6852
6853 Changesets modifying files matched by pattern.
6854
6855 The pattern without explicit kind like glob: is expected to be
6856 relative to the current directory and match against a file or a
6857 directory.
6858
6859 named(namespace)
6860
6861 The changesets in a given namespace.
6862
6863 Pattern matching is supported for namespace. See hg help revi‐
6864 sions.patterns.
6865
6866 nodefromfile(path)
6867
6868 Read a list of nodes from the file at path.
6869
6870 This applies id(LINE) to each line of the file.
6871
6872 This is useful when the amount of nodes you need to specify gets
6873 too large for the command line.
6874
6875 none()
6876
6877 No changesets.
6878
6879 only(set, [set])
6880
6881 Changesets that are ancestors of the first set that are not an‐
6882 cestors of any other head in the repo. If a second set is speci‐
6883 fied, the result is ancestors of the first set that are not an‐
6884 cestors of the second set (i.e. ::<set1> - ::<set2>).
6885
6886 origin([set])
6887
6888 Changesets that were specified as a source for the grafts,
6889 transplants or rebases that created the given revisions. Omit‐
6890 ting the optional set is the same as passing all(). If a
6891 changeset created by these operations is itself specified as a
6892 source for one of these operations, only the source changeset
6893 for the first operation is selected.
6894
6895 outgoing([path])
6896
6897 Changesets not found in the specified destination repository, or
6898 the default push location.
6899
6900 If the location resolve to multiple repositories, the union of
6901 all outgoing changeset will be used.
6902
6903 p1([set])
6904
6905 First parent of changesets in set, or the working directory.
6906
6907 p2([set])
6908
6909 Second parent of changesets in set, or the working directory.
6910
6911 parents([set])
6912
6913 The set of all parents for all changesets in set, or the working
6914 directory.
6915
6916 present(set)
6917
6918 An empty set, if any revision in set isn't found; otherwise, all
6919 revisions in set.
6920
6921 If any of specified revisions is not present in the local repos‐
6922 itory, the query is normally aborted. But this predicate allows
6923 the query to continue even in such cases.
6924
6925 public()
6926
6927 Changeset in public phase.
6928
6929 remote([id [,path]])
6930
6931 Local revision that corresponds to the given identifier in a re‐
6932 mote repository, if present. Here, the '.' identifier is a syn‐
6933 onym for the current local branch.
6934
6935 removes(pattern)
6936
6937 Changesets which remove files matching pattern.
6938
6939 The pattern without explicit kind like glob: is expected to be
6940 relative to the current directory and match against a file or a
6941 directory.
6942
6943 rev(number)
6944
6945 Revision with the given numeric identifier.
6946
6947 reverse(set)
6948
6949 Reverse order of set.
6950
6951 revset(set)
6952
6953 Strictly interpret the content as a revset.
6954
6955 The content of this special predicate will be strictly inter‐
6956 preted as a revset. For example, revset(id(0)) will be inter‐
6957 preted as "id(0)" without possible ambiguity with a "id(0)"
6958 bookmark or tag.
6959
6960 roots(set)
6961
6962 Changesets in set with no parent changeset in set.
6963
6964 secret()
6965
6966 Changeset in secret phase.
6967
6968 sort(set[, [-]key... [, ...]])
6969
6970 Sort set by keys. The default sort order is ascending, specify a
6971 key as -key to sort in descending order.
6972
6973 The keys can be:
6974
6975 • rev for the revision number,
6976
6977 • branch for the branch name,
6978
6979 • desc for the commit message (description),
6980
6981 • user for user name (author can be used as an alias),
6982
6983 • date for the commit date
6984
6985 • topo for a reverse topographical sort
6986
6987 • node the nodeid of the revision
6988
6989 • random randomly shuffle revisions
6990
6991 The topo sort order cannot be combined with other sort keys.
6992 This sort takes one optional argument, topo.firstbranch, which
6993 takes a revset that specifies what topographical branches to
6994 prioritize in the sort.
6995
6996 The random sort takes one optional random.seed argument to con‐
6997 trol the pseudo-randomness of the result.
6998
6999 subrepo([pattern])
7000
7001 Changesets that add, modify or remove the given subrepo. If no
7002 subrepo pattern is named, any subrepo changes are returned.
7003
7004 tag([name])
7005
7006 The specified tag by name, or all tagged revisions if no name is
7007 given.
7008
7009 Pattern matching is supported for name. See hg help revi‐
7010 sions.patterns.
7011
7012 user(string)
7013
7014 User name contains string. The match is case-insensitive.
7015
7016 Pattern matching is supported for string. See hg help revi‐
7017 sions.patterns.
7018
7019 Aliases
7020 New predicates (known as "aliases") can be defined, using any combina‐
7021 tion of existing predicates or other aliases. An alias definition looks
7022 like:
7023
7024 <alias> = <definition>
7025
7026 in the revsetalias section of a Mercurial configuration file. Arguments
7027 of the form a1, a2, etc. are substituted from the alias into the defi‐
7028 nition.
7029
7030 For example,
7031
7032 [revsetalias]
7033 h = heads()
7034 d(s) = sort(s, date)
7035 rs(s, k) = reverse(sort(s, k))
7036
7037 defines three aliases, h, d, and rs. rs(0:tip, author) is exactly
7038 equivalent to reverse(sort(0:tip, author)).
7039
7040 Equivalents
7041 Command line equivalents for hg log:
7042
7043 -f -> ::.
7044 -d x -> date(x)
7045 -k x -> keyword(x)
7046 -m -> merge()
7047 -u x -> user(x)
7048 -b x -> branch(x)
7049 -P x -> !::x
7050 -l x -> limit(expr, x)
7051
7052 Examples
7053 Some sample queries:
7054
7055 • Changesets on the default branch:
7056
7057 hg log -r "branch(default)"
7058
7059 • Changesets on the default branch since tag 1.5 (excluding merges):
7060
7061 hg log -r "branch(default) and 1.5:: and not merge()"
7062
7063 • Open branch heads:
7064
7065 hg log -r "head() and not closed()"
7066
7067 • Changesets between tags 1.3 and 1.5 mentioning "bug" that affect
7068 hgext/*:
7069
7070 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"
7071
7072 • Changesets committed in May 2008, sorted by user:
7073
7074 hg log -r "sort(date('May 2008'), user)"
7075
7076 • Changesets mentioning "bug" or "issue" that are not in a tagged re‐
7077 lease:
7078
7079 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"
7080
7081 • Update to the commit that bookmark @ is pointing to, without activat‐
7082 ing the bookmark (this works because the last revision of the revset
7083 is used):
7084
7085 hg update :@
7086
7087 • Show diff between tags 1.3 and 1.5 (this works because the first and
7088 the last revisions of the revset are used):
7089
7090 hg diff -r 1.3::1.5
7091
7093 Mercurial can be augmented with Rust extensions for speeding up certain
7094 operations.
7095
7096 Compatibility
7097 Though the Rust extensions are only tested by the project under Linux,
7098 users of MacOS, FreeBSD and other UNIX-likes have been using the Rust
7099 extensions. Your mileage may vary, but by all means do give us feedback
7100 or signal your interest for better support.
7101
7102 No Rust extensions are available for Windows at this time.
7103
7104 Features
7105 The following operations are sped up when using Rust:
7106
7107 • discovery of differences between repositories (pull/push)
7108
7109 • nodemap (see hg help config.format.use-persistent-nodemap)
7110
7111 • all commands using the dirstate (status, commit, diff, add, up‐
7112 date, etc.)
7113
7114 • dirstate-v2 (see hg help config.format.use-dirstate-v2)
7115
7116 • iteration over ancestors in a graph
7117
7118 More features are in the works, and improvements on the above listed
7119 are still in progress. For more experimental work see the "rhg" sec‐
7120 tion.
7121
7122 Checking for Rust
7123 You may already have the Rust extensions depending on how you install
7124 Mercurial:
7125
7126 $ hg debuginstall | grep -i rust
7127 checking Rust extensions (installed)
7128 checking module policy (rust+c-allow)
7129
7130 If those lines don't even exist, you're using an old version of hg
7131 which does not have any Rust extensions yet.
7132
7133 Installing
7134 You will need cargo to be in your $PATH. See the "MSRV" section for
7135 which version to use.
7136
7137 Using pip
7138 Users of pip can install the Rust extensions with the following com‐
7139 mand:
7140
7141 $ pip install mercurial --global-option --rust --no-use-pep517
7142
7143 --no-use-pep517 is here to tell pip to preserve backwards compatibility
7144 with the legacy setup.py system. Mercurial has not yet migrated its
7145 complex setup to the new system, so we still need this to add compiled
7146 extensions.
7147
7148 This might take a couple of minutes because you're compiling every‐
7149 thing.
7150
7151 See the "Checking for Rust" section to see if the install succeeded.
7152
7153 From your distribution
7154 Some distributions are shipping Mercurial with Rust extensions enabled
7155 and pre-compiled (meaning you won't have to install cargo), or allow
7156 you to specify an install flag. Check with your specific distribution
7157 for how to do that, or ask their team to add support for hg+Rust!
7158
7159 From source
7160 Please refer to the rust/README.rst file in the Mercurial repository
7161 for instructions on how to install from source.
7162
7163 MSRV
7164 The minimum supported Rust version is currently 1.48.0. The project's
7165 policy is to follow the version from Debian stable, to make the distri‐
7166 butions' job easier.
7167
7168 rhg
7169 There exists an experimental pure-Rust version of Mercurial called rhg
7170 with a fallback mechanism for unsupported invocations. It allows for
7171 much faster execution of certain commands while adding no discernable
7172 overhead for the rest.
7173
7174 The only way of trying it out is by building it from source. Please re‐
7175 fer to rust/README.rst in the Mercurial repository.
7176
7177 See hg help config.rhg for configuration options.
7178
7179 Contributing
7180 If you would like to help the Rust endeavor, please refer to
7181 rust/README.rst in the Mercurial repository.
7182
7184 It is common for machines (as opposed to humans) to consume Mercurial.
7185 This help topic describes some of the considerations for interfacing
7186 machines with Mercurial.
7187
7188 Choosing an Interface
7189 Machines have a choice of several methods to interface with Mercurial.
7190 These include:
7191
7192 • Executing the hg process
7193
7194 • Querying a HTTP server
7195
7196 • Calling out to a command server
7197
7198 Executing hg processes is very similar to how humans interact with Mer‐
7199 curial in the shell. It should already be familiar to you.
7200
7201 hg serve can be used to start a server. By default, this will start a
7202 "hgweb" HTTP server. This HTTP server has support for machine-readable
7203 output, such as JSON. For more, see hg help hgweb.
7204
7205 hg serve can also start a "command server." Clients can connect to this
7206 server and issue Mercurial commands over a special protocol. For more
7207 details on the command server, including links to client libraries, see
7208 https://www.mercurial-scm.org/wiki/CommandServer.
7209
7210 hg serve based interfaces (the hgweb and command servers) have the ad‐
7211 vantage over simple hg process invocations in that they are likely more
7212 efficient. This is because there is significant overhead to spawn new
7213 Python processes.
7214
7215 Tip If you need to invoke several hg processes in short order and/or
7216 performance is important to you, use of a server-based interface
7217 is highly recommended.
7218
7219 Environment Variables
7220 As documented in hg help environment, various environment variables in‐
7221 fluence the operation of Mercurial. The following are particularly rel‐
7222 evant for machines consuming Mercurial:
7223
7224 HGPLAIN
7225 If not set, Mercurial's output could be influenced by configura‐
7226 tion settings that impact its encoding, verbose mode, localiza‐
7227 tion, etc.
7228
7229 It is highly recommended for machines to set this variable when
7230 invoking hg processes.
7231
7232 HGENCODING
7233 If not set, the locale used by Mercurial will be detected from
7234 the environment. If the determined locale does not support dis‐
7235 play of certain characters, Mercurial may render these character
7236 sequences incorrectly (often by using "?" as a placeholder for
7237 invalid characters in the current locale).
7238
7239 Explicitly setting this environment variable is a good practice
7240 to guarantee consistent results. "utf-8" is a good choice on
7241 UNIX-like environments.
7242
7243 HGRCPATH
7244 If not set, Mercurial will inherit config options from config
7245 files using the process described in hg help config. This in‐
7246 cludes inheriting user or system-wide config files.
7247
7248 When utmost control over the Mercurial configuration is desired,
7249 the value of HGRCPATH can be set to an explicit file with known
7250 good configs. In rare cases, the value can be set to an empty
7251 file or the null device (often /dev/null) to bypass loading of
7252 any user or system config files. Note that these approaches can
7253 have unintended consequences, as the user and system config
7254 files often define things like the username and extensions that
7255 may be required to interface with a repository.
7256
7257 HGRCSKIPREPO
7258 When set, the .hg/hgrc from repositories are not read.
7259
7260 Note that not reading the repository's configuration can have
7261 unintended consequences, as the repository config files can de‐
7262 fine things like extensions that are required for access to the
7263 repository.
7264
7265 Command-line Flags
7266 Mercurial's default command-line parser is designed for humans, and is
7267 not robust against malicious input. For instance, you can start a de‐
7268 bugger by passing --debugger as an option value:
7269
7270 $ REV=--debugger sh -c 'hg log -r "$REV"'
7271
7272 This happens because several command-line flags need to be scanned
7273 without using a concrete command table, which may be modified while
7274 loading repository settings and extensions.
7275
7276 Since Mercurial 4.4.2, the parsing of such flags may be restricted by
7277 setting HGPLAIN=+strictflags. When this feature is enabled, all early
7278 options (e.g. -R/--repository, --cwd, --config) must be specified first
7279 amongst the other global options, and cannot be injected to an arbi‐
7280 trary location:
7281
7282 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV"
7283
7284 In earlier Mercurial versions where +strictflags isn't available, you
7285 can mitigate the issue by concatenating an option value with its flag:
7286
7287 $ hg log -r"$REV" --keyword="$KEYWORD"
7288
7289 Consuming Command Output
7290 It is common for machines to need to parse the output of Mercurial com‐
7291 mands for relevant data. This section describes the various techniques
7292 for doing so.
7293
7294 Parsing Raw Command Output
7295 Likely the simplest and most effective solution for consuming command
7296 output is to simply invoke hg commands as you would as a user and parse
7297 their output.
7298
7299 The output of many commands can easily be parsed with tools like grep,
7300 sed, and awk.
7301
7302 A potential downside with parsing command output is that the output of
7303 commands can change when Mercurial is upgraded. While Mercurial does
7304 generally strive for strong backwards compatibility, command output
7305 does occasionally change. Having tests for your automated interactions
7306 with hg commands is generally recommended, but is even more important
7307 when raw command output parsing is involved.
7308
7309 Using Templates to Control Output
7310 Many hg commands support templatized output via the -T/--template argu‐
7311 ment. For more, see hg help templates.
7312
7313 Templates are useful for explicitly controlling output so that you get
7314 exactly the data you want formatted how you want it. For example, log
7315 -T {node}\n can be used to print a newline delimited list of changeset
7316 nodes instead of a human-tailored output containing authors, dates, de‐
7317 scriptions, etc.
7318
7319 Tip If parsing raw command output is too complicated, consider using
7320 templates to make your life easier.
7321
7322 The -T/--template argument allows specifying pre-defined styles. Mer‐
7323 curial ships with the machine-readable styles cbor, json, and xml,
7324 which provide CBOR, JSON, and XML output, respectively. These are use‐
7325 ful for producing output that is machine readable as-is.
7326
7327 (Mercurial 5.0 is required for CBOR style.)
7328
7329 Important
7330 The json and xml styles are considered experimental. While they
7331 may be attractive to use for easily obtaining machine-readable
7332 output, their behavior may change in subsequent versions.
7333
7334 These styles may also exhibit unexpected results when dealing
7335 with certain encodings. Mercurial treats things like filenames
7336 as a series of bytes and normalizing certain byte sequences to
7337 JSON or XML with certain encoding settings can lead to sur‐
7338 prises.
7339
7340 Command Server Output
7341 If using the command server to interact with Mercurial, you are likely
7342 using an existing library/API that abstracts implementation details of
7343 the command server. If so, this interface layer may perform parsing for
7344 you, saving you the work of implementing it yourself.
7345
7346 Output Verbosity
7347 Commands often have varying output verbosity, even when machine read‐
7348 able styles are being used (e.g. -T json). Adding -v/--verbose and
7349 --debug to the command's arguments can increase the amount of data ex‐
7350 posed by Mercurial.
7351
7352 An alternate way to get the data you need is by explicitly specifying a
7353 template.
7354
7355 Other Topics
7356 revsets
7357 Revisions sets is a functional query language for selecting a
7358 set of revisions. Think of it as SQL for Mercurial repositories.
7359 Revsets are useful for querying repositories for specific data.
7360
7361 See hg help revsets for more.
7362
7363 share extension
7364 The share extension provides functionality for sharing reposi‐
7365 tory data across several working copies. It can even automati‐
7366 cally "pool" storage for logically related repositories when
7367 cloning.
7368
7369 Configuring the share extension can lead to significant resource
7370 utilization reduction, particularly around disk space and the
7371 network. This is especially true for continuous integration (CI)
7372 environments.
7373
7374 See hg help -e share for more.
7375
7377 Subrepositories let you nest external repositories or projects into a
7378 parent Mercurial repository, and make commands operate on them as a
7379 group.
7380
7381 Mercurial currently supports Mercurial, Git, and Subversion subreposi‐
7382 tories.
7383
7384 Subrepositories are made of three components:
7385
7386 1. Nested repository checkouts. They can appear anywhere in the parent
7387 working directory.
7388
7389 2. Nested repository references. They are defined in .hgsub, which
7390 should be placed in the root of working directory, and tell where
7391 the subrepository checkouts come from. Mercurial subrepositories are
7392 referenced like:
7393
7394 path/to/nested = https://example.com/nested/repo/path
7395
7396 Git and Subversion subrepos are also supported:
7397
7398 path/to/nested = [git]git://example.com/nested/repo/path
7399 path/to/nested = [svn]https://example.com/nested/trunk/path
7400
7401 where path/to/nested is the checkout location relatively to the par‐
7402 ent Mercurial root, and https://example.com/nested/repo/path is the
7403 source repository path. The source can also reference a filesystem
7404 path.
7405
7406 Note that .hgsub does not exist by default in Mercurial reposito‐
7407 ries, you have to create and add it to the parent repository before
7408 using subrepositories.
7409
7410 3. Nested repository states. They are defined in .hgsubstate, which is
7411 placed in the root of working directory, and capture whatever infor‐
7412 mation is required to restore the subrepositories to the state they
7413 were committed in a parent repository changeset. Mercurial automati‐
7414 cally record the nested repositories states when committing in the
7415 parent repository.
7416
7417 Note
7418 The .hgsubstate file should not be edited manually.
7419
7420 Adding a Subrepository
7421 If .hgsub does not exist, create it and add it to the parent reposi‐
7422 tory. Clone or checkout the external projects where you want it to live
7423 in the parent repository. Edit .hgsub and add the subrepository entry
7424 as described above. At this point, the subrepository is tracked and the
7425 next commit will record its state in .hgsubstate and bind it to the
7426 committed changeset.
7427
7428 Synchronizing a Subrepository
7429 Subrepos do not automatically track the latest changeset of their
7430 sources. Instead, they are updated to the changeset that corresponds
7431 with the changeset checked out in the top-level changeset. This is so
7432 developers always get a consistent set of compatible code and libraries
7433 when they update.
7434
7435 Thus, updating subrepos is a manual process. Simply check out target
7436 subrepo at the desired revision, test in the top-level repo, then com‐
7437 mit in the parent repository to record the new combination.
7438
7439 Deleting a Subrepository
7440 To remove a subrepository from the parent repository, delete its refer‐
7441 ence from .hgsub, then remove its files.
7442
7443 Interaction with Mercurial Commands
7444 add add does not recurse in subrepos unless -S/--subrepos is speci‐
7445 fied. However, if you specify the full path of a file in a sub‐
7446 repo, it will be added even without -S/--subrepos specified.
7447 Subversion subrepositories are currently silently ignored.
7448
7449 addremove
7450 addremove does not recurse into subrepos unless -S/--subrepos is
7451 specified. However, if you specify the full path of a directory
7452 in a subrepo, addremove will be performed on it even without
7453 -S/--subrepos being specified. Git and Subversion subreposito‐
7454 ries will print a warning and continue.
7455
7456 archive
7457 archive does not recurse in subrepositories unless -S/--subrepos
7458 is specified.
7459
7460 cat Git subrepositories only support exact file matches. Subversion
7461 subrepositories are currently ignored.
7462
7463 commit commit creates a consistent snapshot of the state of the entire
7464 project and its subrepositories. If any subrepositories have
7465 been modified, Mercurial will abort. Mercurial can be made to
7466 instead commit all modified subrepositories by specifying
7467 -S/--subrepos, or setting "ui.commitsubrepos=True" in a configu‐
7468 ration file (see hg help config). After there are no longer any
7469 modified subrepositories, it records their state and finally
7470 commits it in the parent repository. The --addremove option
7471 also honors the -S/--subrepos option. However, Git and Subver‐
7472 sion subrepositories will print a warning and abort.
7473
7474 diff diff does not recurse in subrepos unless -S/--subrepos is speci‐
7475 fied. However, if you specify the full path of a file or direc‐
7476 tory in a subrepo, it will be diffed even without -S/--subrepos
7477 being specified. Subversion subrepositories are currently
7478 silently ignored.
7479
7480 files files does not recurse into subrepos unless -S/--subrepos is
7481 specified. However, if you specify the full path of a file or
7482 directory in a subrepo, it will be displayed even without
7483 -S/--subrepos being specified. Git and Subversion subreposito‐
7484 ries are currently silently ignored.
7485
7486 forget forget currently only handles exact file matches in subrepos.
7487 Git and Subversion subrepositories are currently silently ig‐
7488 nored.
7489
7490 incoming
7491 incoming does not recurse in subrepos unless -S/--subrepos is
7492 specified. Git and Subversion subrepositories are currently
7493 silently ignored.
7494
7495 outgoing
7496 outgoing does not recurse in subrepos unless -S/--subrepos is
7497 specified. Git and Subversion subrepositories are currently
7498 silently ignored.
7499
7500 pull pull is not recursive since it is not clear what to pull prior
7501 to running hg update. Listing and retrieving all subrepositories
7502 changes referenced by the parent repository pulled changesets is
7503 expensive at best, impossible in the Subversion case.
7504
7505 push Mercurial will automatically push all subrepositories first when
7506 the parent repository is being pushed. This ensures new sub‐
7507 repository changes are available when referenced by top-level
7508 repositories. Push is a no-op for Subversion subrepositories.
7509
7510 serve serve does not recurse into subrepositories unless -S/--subrepos
7511 is specified. Git and Subversion subrepositories are currently
7512 silently ignored.
7513
7514 status status does not recurse into subrepositories unless -S/--subre‐
7515 pos is specified. Subrepository changes are displayed as regular
7516 Mercurial changes on the subrepository elements. Subversion sub‐
7517 repositories are currently silently ignored.
7518
7519 remove remove does not recurse into subrepositories unless -S/--subre‐
7520 pos is specified. However, if you specify a file or directory
7521 path in a subrepo, it will be removed even without -S/--subre‐
7522 pos. Git and Subversion subrepositories are currently silently
7523 ignored.
7524
7525 update update restores the subrepos in the state they were originally
7526 committed in target changeset. If the recorded changeset is not
7527 available in the current subrepository, Mercurial will pull it
7528 in first before updating. This means that updating can require
7529 network access when using subrepositories.
7530
7531 Remapping Subrepositories Sources
7532 A subrepository source location may change during a project life, in‐
7533 validating references stored in the parent repository history. To fix
7534 this, rewriting rules can be defined in parent repository hgrc file or
7535 in Mercurial configuration. See the [subpaths] section in hgrc(5) for
7536 more details.
7537
7539 Mercurial allows you to customize output of commands through templates.
7540 You can either pass in a template or select an existing template-style
7541 from the command line, via the --template option.
7542
7543 You can customize output for any "log-like" command: log, outgoing, in‐
7544 coming, tip, parents, and heads.
7545
7546 Some built-in styles are packaged with Mercurial. These can be listed
7547 with hg log --template list. Example usage:
7548
7549 $ hg log -r1.0::1.1 --template changelog
7550
7551 A template is a piece of text, with markup to invoke variable expan‐
7552 sion:
7553
7554 $ hg log -r1 --template "{node}\n"
7555 b56ce7b07c52de7d5fd79fb89701ea538af65746
7556
7557 Keywords
7558 Strings in curly braces are called keywords. The availability of key‐
7559 words depends on the exact context of the templater. These keywords are
7560 usually available for templating a log-like command:
7561
7562 _fast_rank
7563 the rank of a changeset if cached
7564
7565 The rank of a revision is the size of the sub-graph it defines
7566 as a head. Equivalently, the rank of a revision r is the size
7567 of the set ancestors(r), r included.
7568
7569 activebookmark
7570 String. The active bookmark, if it is associated with the
7571 changeset.
7572
7573 author Alias for {user}
7574
7575 bisect String. The changeset bisection status.
7576
7577 bookmarks
7578 List of strings. Any bookmarks associated with the changeset.
7579 Also sets 'active', the name of the active bookmark.
7580
7581 branch String. The name of the branch on which the changeset was com‐
7582 mitted.
7583
7584 changessincelatesttag
7585 Integer. All ancestors not in the latest tag.
7586
7587 children
7588 List of strings. The children of the changeset.
7589
7590 date Date information. The date when the changeset was committed.
7591
7592 desc String. The text of the changeset description.
7593
7594 diffstat
7595 String. Statistics of changes with the following format: "modi‐
7596 fied files: +added/-removed lines"
7597
7598 extras List of dicts with key, value entries of the 'extras' field of
7599 this changeset.
7600
7601 file_adds
7602 List of strings. Files added by this changeset.
7603
7604 file_copies
7605 List of strings. Files copied in this changeset with their
7606 sources.
7607
7608 file_copies_switch
7609 List of strings. Like "file_copies" but displayed only if the
7610 --copied switch is set.
7611
7612 file_dels
7613 List of strings. Files removed by this changeset.
7614
7615 file_mods
7616 List of strings. Files modified by this changeset.
7617
7618 files List of strings. All files modified, added, or removed by this
7619 changeset.
7620
7621 graphnode
7622 String. The character representing the changeset node in an
7623 ASCII revision graph.
7624
7625 graphwidth
7626 Integer. The width of the graph drawn by 'log --graph' or zero.
7627
7628 index Integer. The current iteration of the loop. (0 indexed)
7629
7630 latesttag
7631 List of strings. The global tags on the most recent globally
7632 tagged ancestor of this changeset. If no such tags exist, the
7633 list consists of the single string "null".
7634
7635 latesttagdistance
7636 Integer. Longest path to the latest tag.
7637
7638 namespaces
7639 Dict of lists. Names attached to this changeset per namespace.
7640
7641 negrev Integer. The repository-local changeset negative revision num‐
7642 ber, which counts in the opposite direction.
7643
7644 node String. The changeset identification hash, as a 40 hexadecimal
7645 digit string.
7646
7647 onelinesummary
7648 String. A one-line summary for the ctx (not including trailing
7649 newline). The default template be overridden in command-tem‐
7650 plates.oneline-summary.
7651
7652 p1 Changeset. The changeset's first parent. {p1.rev} for the revi‐
7653 sion number, and {p1.node} for the identification hash.
7654
7655 p2 Changeset. The changeset's second parent. {p2.rev} for the revi‐
7656 sion number, and {p2.node} for the identification hash.
7657
7658 parents
7659 List of strings. The parents of the changeset in "rev:node" for‐
7660 mat. If the changeset has only one "natural" parent (the prede‐
7661 cessor revision) nothing is shown.
7662
7663 peerurls
7664 A dictionary of repository locations defined in the [paths] sec‐
7665 tion of your configuration file.
7666
7667 phase String. The changeset phase name.
7668
7669 reporoot
7670 String. The root directory of the current repository.
7671
7672 rev Integer. The repository-local changeset revision number.
7673
7674 subrepos
7675 List of strings. Updated subrepositories in the changeset.
7676
7677 tags List of strings. Any tags associated with the changeset.
7678
7679 termwidth
7680 Integer. The width of the current terminal.
7681
7682 user String. The unmodified author of the changeset.
7683
7684 verbosity
7685 String. The current output verbosity in 'debug', 'quiet', 'ver‐
7686 bose', or ''.
7687
7688 The "date" keyword does not produce human-readable output. If you want
7689 to use a date in your output, you can use a filter to process it. Fil‐
7690 ters are functions which return a string based on the input variable.
7691 Be sure to use the stringify filter first when you're applying a
7692 string-input filter to a list-like input variable. You can also use a
7693 chain of filters to get the desired output:
7694
7695 $ hg tip --template "{date|isodate}\n"
7696 2008-08-21 18:22 +0000
7697
7698 Filters
7699 List of filters:
7700
7701 addbreaks
7702 Any text. Add an XHTML "<br />" tag before the end of every line
7703 except the last.
7704
7705 age Date. Returns a human-readable date/time difference between the
7706 given date/time and the current date/time.
7707
7708 basename
7709 Any text. Treats the text as a path, and returns the last compo‐
7710 nent of the path after splitting by the path separator. For ex‐
7711 ample, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "".
7712
7713 cbor Any object. Serializes the object to CBOR bytes.
7714
7715 commondir
7716 List of text. Treats each list item as file name with / as path
7717 separator and returns the longest common directory prefix shared
7718 by all list items. Returns the empty string if no common prefix
7719 exists.
7720
7721 The list items are not normalized, i.e. "foo/../bar" is handled
7722 as file "bar" in the directory "foo/..". Leading slashes are ig‐
7723 nored.
7724
7725 For example, ["foo/bar/baz", "foo/baz/bar"] becomes "foo" and
7726 ["foo/bar", "baz"] becomes "".
7727
7728 count List or text. Returns the length as an integer.
7729
7730 dirname
7731 Any text. Treats the text as a path, and strips the last compo‐
7732 nent of the path after splitting by the path separator.
7733
7734 domain Any text. Finds the first string that looks like an email ad‐
7735 dress, and extracts just the domain component. Example: User
7736 <user@example.com> becomes example.com.
7737
7738 email Any text. Extracts the first string that looks like an email ad‐
7739 dress. Example: User <user@example.com> becomes user@exam‐
7740 ple.com.
7741
7742 emailuser
7743 Any text. Returns the user portion of an email address.
7744
7745 escape Any text. Replaces the special XML/XHTML characters "&", "<" and
7746 ">" with XML entities, and filters out NUL characters.
7747
7748 fill68 Any text. Wraps the text to fit in 68 columns.
7749
7750 fill76 Any text. Wraps the text to fit in 76 columns.
7751
7752 firstline
7753 Any text. Returns the first line of text.
7754
7755 hex Any text. Convert a binary Mercurial node identifier into its
7756 long hexadecimal representation.
7757
7758 hgdate Date. Returns the date as a pair of numbers: "1157407993 25200"
7759 (Unix timestamp, timezone offset).
7760
7761 isodate
7762 Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
7763 +0200".
7764
7765 isodatesec
7766 Date. Returns the date in ISO 8601 format, including seconds:
7767 "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
7768
7769 json Any object. Serializes the object to a JSON formatted text.
7770
7771 lower Any text. Converts the text to lowercase.
7772
7773 nonempty
7774 Any text. Returns '(none)' if the string is empty.
7775
7776 obfuscate
7777 Any text. Returns the input text rendered as a sequence of XML
7778 entities.
7779
7780 person Any text. Returns the name before an email address, interpreting
7781 it as per RFC 5322.
7782
7783 reverse
7784 List. Reverses the order of list items.
7785
7786 revescape
7787 Any text. Escapes all "special" characters, except @. Forward
7788 slashes are escaped twice to prevent web servers from prema‐
7789 turely unescaping them. For example, "@foo bar/baz" becomes
7790 "@foo%20bar%252Fbaz".
7791
7792 rfc3339date
7793 Date. Returns a date using the Internet date format specified in
7794 RFC 3339: "2009-08-18T13:00:13+02:00".
7795
7796 rfc822date
7797 Date. Returns a date using the same format used in email head‐
7798 ers: "Tue, 18 Aug 2009 13:00:13 +0200".
7799
7800 short Changeset hash. Returns the short form of a changeset hash, i.e.
7801 a 12 hexadecimal digit string.
7802
7803 shortbisect
7804 Any text. Treats label as a bisection status, and returns a sin‐
7805 gle-character representing the status (G: good, B: bad, S:
7806 skipped, U: untested, I: ignored). Returns single space if text
7807 is not a valid bisection status.
7808
7809 shortdate
7810 Date. Returns a date like "2006-09-18".
7811
7812 slashpath
7813 Any text. Replaces the native path separator with slash.
7814
7815 splitlines
7816 Any text. Split text into a list of lines.
7817
7818 stringify
7819 Any type. Turns the value into text by converting values into
7820 text and concatenating them.
7821
7822 stripdir
7823 Treat the text as path and strip a directory level, if possible.
7824 For example, "foo" and "foo/bar" becomes "foo".
7825
7826 tabindent
7827 Any text. Returns the text, with every non-empty line except the
7828 first starting with a tab character.
7829
7830 upper Any text. Converts the text to uppercase.
7831
7832 urlescape
7833 Any text. Escapes all "special" characters. For example, "foo
7834 bar" becomes "foo%20bar".
7835
7836 user Any text. Returns a short representation of a user name or email
7837 address.
7838
7839 utf8 Any text. Converts from the local character encoding to UTF-8.
7840
7841 Note that a filter is nothing more than a function call, i.e.
7842 expr|filter is equivalent to filter(expr).
7843
7844 Functions
7845 In addition to filters, there are some basic built-in functions:
7846
7847 config(section, name[, default])
7848 Returns the requested hgrc config option as a string.
7849
7850 configbool(section, name[, default])
7851 Returns the requested hgrc config option as a boolean.
7852
7853 configint(section, name[, default])
7854 Returns the requested hgrc config option as an integer.
7855
7856 date(date[, fmt])
7857 Format a date. See hg help dates for formatting strings. The de‐
7858 fault is a Unix date format, including the timezone: "Mon Sep 04
7859 15:13:13 2006 0700".
7860
7861 dict([[key=]value...])
7862 Construct a dict from key-value pairs. A key may be omitted if a
7863 value expression can provide an unambiguous name.
7864
7865 diff([includepattern [, excludepattern]])
7866 Show a diff, optionally specifying files to include or exclude.
7867
7868 files(pattern)
7869 All files of the current changeset matching the pattern. See hg
7870 help patterns.
7871
7872 fill(text[, width[, initialident[, hangindent]]])
7873 Fill many paragraphs with optional indentation. See the "fill"
7874 filter.
7875
7876 filter(iterable[, expr])
7877 Remove empty elements from a list or a dict. If expr specified,
7878 it's applied to each element to test emptiness.
7879
7880 get(dict, key)
7881 Get an attribute/key from an object. Some keywords are complex
7882 types. This function allows you to obtain the value of an attri‐
7883 bute on these types.
7884
7885 if(expr, then[, else])
7886 Conditionally execute based on the result of an expression.
7887
7888 ifcontains(needle, haystack, then[, else])
7889 Conditionally execute based on whether the item "needle" is in
7890 "haystack".
7891
7892 ifeq(expr1, expr2, then[, else])
7893 Conditionally execute based on whether 2 items are equivalent.
7894
7895 indent(text, indentchars[, firstline])
7896 Indents all non-empty lines with the characters given in the in‐
7897 dentchars string. An optional third parameter will override the
7898 indent for the first line only if present.
7899
7900 join(list, sep)
7901 Join items in a list with a delimiter.
7902
7903 label(label, expr)
7904 Apply a label to generated content. Content with a label applied
7905 can result in additional post-processing, such as automatic col‐
7906 orization.
7907
7908 latesttag([pattern])
7909 The global tags matching the given pattern on the most recent
7910 globally tagged ancestor of this changeset. If no such tags ex‐
7911 ist, the "{tag}" template resolves to the string "null". See hg
7912 help revisions.patterns for the pattern syntax.
7913
7914 localdate(date[, tz])
7915 Converts a date to the specified timezone. The default is local
7916 date.
7917
7918 mailmap(author)
7919 Return the author, updated according to the value set in the
7920 .mailmap file
7921
7922 max(iterable)
7923 Return the max of an iterable
7924
7925 min(iterable)
7926 Return the min of an iterable
7927
7928 mod(a, b)
7929 Calculate a mod b such that a / b + a mod b == a
7930
7931 pad(text, width[, fillchar=' '[, left=False[, truncate=False]]])
7932 Pad text with a fill character.
7933
7934 relpath(path)
7935 Convert a repository-absolute path into a filesystem path rela‐
7936 tive to the current working directory.
7937
7938 revset(query[, formatargs...])
7939 Execute a revision set query. See hg help revset.
7940
7941 rstdoc(text, style)
7942 Format reStructuredText.
7943
7944 search(pattern, text)
7945 Look for the first text matching the regular expression pattern.
7946 Groups are accessible as {1}, {2}, ... in %-mapped template.
7947
7948 separate(sep, args...)
7949 Add a separator between non-empty arguments.
7950
7951 shortest(node, minlength=4)
7952 Obtain the shortest representation of a node.
7953
7954 startswith(pattern, text)
7955 Returns the value from the "text" argument if it begins with the
7956 content from the "pattern" argument.
7957
7958 strip(text[, chars])
7959 Strip characters from a string. By default, strips all leading
7960 and trailing whitespace.
7961
7962 sub(pattern, replacement, expression)
7963 Perform text substitution using regular expressions.
7964
7965 subsetparents(rev, revset)
7966 Look up parents of the rev in the sub graph given by the revset.
7967
7968 word(number, text[, separator])
7969 Return the nth word from a string.
7970
7971 Operators
7972 We provide a limited set of infix arithmetic operations on integers:
7973
7974 + for addition
7975 - for subtraction
7976 * for multiplication
7977 / for floor division (division rounded to integer nearest -infinity)
7978
7979 Division fulfills the law x = x / y + mod(x, y).
7980
7981 Also, for any expression that returns a list, there is a list operator:
7982
7983 expr % "{template}"
7984
7985 As seen in the above example, {template} is interpreted as a template.
7986 To prevent it from being interpreted, you can use an escape character
7987 \{ or a raw string prefix, r'...'.
7988
7989 The dot operator can be used as a shorthand for accessing a sub item:
7990
7991 • expr.member is roughly equivalent to expr % '{member}' if expr re‐
7992 turns a non-list/dict. The returned value is not stringified.
7993
7994 • dict.key is identical to get(dict, 'key').
7995
7996 Aliases
7997 New keywords and functions can be defined in the templatealias section
7998 of a Mercurial configuration file:
7999
8000 <alias> = <definition>
8001
8002 Arguments of the form a1, a2, etc. are substituted from the alias into
8003 the definition.
8004
8005 For example,
8006
8007 [templatealias]
8008 r = rev
8009 rn = "{r}:{node|short}"
8010 leftpad(s, w) = pad(s, w, ' ', True)
8011
8012 defines two symbol aliases, r and rn, and a function alias leftpad().
8013
8014 It's also possible to specify complete template strings, using the tem‐
8015 plates section. The syntax used is the general template string syntax.
8016
8017 For example,
8018
8019 [templates]
8020 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
8021
8022 defines a template, nodedate, which can be called like:
8023
8024 $ hg log -r . -Tnodedate
8025
8026 A template defined in templates section can also be referenced from an‐
8027 other template:
8028
8029 $ hg log -r . -T "{rev} {nodedate}"
8030
8031 but be aware that the keywords cannot be overridden by templates. For
8032 example, a template defined as templates.rev cannot be referenced as
8033 {rev}.
8034
8035 A template defined in templates section may have sub templates which
8036 are inserted before/after/between items:
8037
8038 [templates]
8039 myjson = ' {dict(rev, node|short)|json}'
8040 myjson:docheader = '\{\n'
8041 myjson:docfooter = '\n}\n'
8042 myjson:separator = ',\n'
8043
8044 Examples
8045 Some sample command line templates:
8046
8047 • Format lists, e.g. files:
8048
8049 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
8050
8051 • Join the list of files with a ", ":
8052
8053 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
8054
8055 • Join the list of files ending with ".py" with a ", ":
8056
8057 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
8058
8059 • Separate non-empty arguments by a " ":
8060
8061 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
8062
8063 • Modify each line of a commit description:
8064
8065 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
8066
8067 • Format date:
8068
8069 $ hg log -r 0 --template "{date(date, '%Y')}\n"
8070
8071 • Display date in UTC:
8072
8073 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
8074
8075 • Output the description set to a fill-width of 30:
8076
8077 $ hg log -r 0 --template "{fill(desc, 30)}"
8078
8079 • Use a conditional to test for the default branch:
8080
8081 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
8082 'on branch {branch}')}\n"
8083
8084 • Append a newline if not empty:
8085
8086 $ hg tip --template "{if(author, '{author}\n')}"
8087
8088 • Label the output for use with the color extension:
8089
8090 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
8091
8092 • Invert the firstline filter, i.e. everything but the first line:
8093
8094 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
8095
8096 • Display the contents of the 'extra' field, one per line:
8097
8098 $ hg log -r 0 --template "{join(extras, '\n')}\n"
8099
8100 • Mark the active bookmark with '*':
8101
8102 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
8103
8104 • Find the previous release candidate tag, the distance and changes
8105 since the tag:
8106
8107 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
8108
8109 • Mark the working copy parent with '@':
8110
8111 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
8112
8113 • Show details of parent revisions:
8114
8115 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
8116
8117 • Show only commit descriptions that start with "template":
8118
8119 $ hg log --template "{startswith('template', firstline(desc))}\n"
8120
8121 • Print the first word of each line of a commit message:
8122
8123 $ hg log --template "{word(0, desc)}\n"
8124
8126 Valid URLs are of the form:
8127
8128 local/filesystem/path[#revision]
8129 file://local/filesystem/path[#revision]
8130 http://[user[:pass]@]host[:port]/[path][#revision]
8131 https://[user[:pass]@]host[:port]/[path][#revision]
8132 ssh://[user@]host[:port]/[path][#revision]
8133 path://pathname
8134
8135 Paths in the local filesystem can either point to Mercurial reposito‐
8136 ries or to bundle files (as created by hg bundle or hg incoming --bun‐
8137 dle). See also hg help paths.
8138
8139 An optional identifier after # indicates a particular branch, tag, or
8140 changeset to use from the remote repository. See also hg help revisions
8141 .
8142
8143 Some features, such as pushing to http:// and https:// URLs are only
8144 possible if the feature is explicitly enabled on the remote Mercurial
8145 server.
8146
8147 Note that the security of HTTPS URLs depends on proper configuration of
8148 web.cacerts.
8149
8150 Some notes about using SSH with Mercurial:
8151
8152 • SSH requires an accessible shell account on the destination machine
8153 and a copy of hg in the remote path or specified with remotecmd.
8154
8155 • path is relative to the remote user's home directory by default. Use
8156 an extra slash at the start of a path to specify an absolute path:
8157
8158 ssh://example.com//tmp/repository
8159
8160 • Mercurial doesn't use its own compression via SSH; the right thing to
8161 do is to configure it in your ~/.ssh/config, e.g.:
8162
8163 Host *.mylocalnetwork.example.com
8164 Compression no
8165 Host *
8166 Compression yes
8167
8168 Alternatively specify "ssh -C" as your ssh command in your configura‐
8169 tion file or with the --ssh command line option.
8170
8171 These URLs can all be stored in your configuration file with path
8172 aliases under the [paths] section like so:
8173
8174 [paths]
8175 alias1 = URL1
8176 alias2 = URL2
8177 ...
8178
8179 You can then use the alias for any command that uses a URL (for example
8180 hg pull alias1 will be treated as hg pull URL1).
8181
8182 Two path aliases are special because they are used as defaults when you
8183 do not provide the URL to a command:
8184
8185 default:
8186 When you create a repository with hg clone, the clone command
8187 saves the location of the source repository as the new reposi‐
8188 tory's 'default' path. This is then used when you omit path from
8189 push- and pull-like commands (including incoming and outgoing).
8190
8191 default-push:
8192 The push command will look for a path named 'default-push', and
8193 prefer it over 'default' if both are defined.
8194
8195 These alias can also be use in the path:// scheme:
8196
8197 [paths]
8198 alias1 = URL1
8199 alias2 = path://alias1
8200 ...
8201
8202 check hg help config.paths for details about the behavior of such
8203 "sub-path".
8204
8206 This section contains help for extensions that are distributed together
8207 with Mercurial. Help for other extensions is available in the help sys‐
8208 tem.
8209
8210 absorb
8211 apply working directory changes to changesets (EXPERIMENTAL)
8212
8213 The absorb extension provides a command to use annotate information to
8214 amend modified chunks into the corresponding non-public changesets.
8215
8216 [absorb]
8217 # only check 50 recent non-public changesets at most
8218 max-stack-size = 50
8219 # whether to add noise to new commits to avoid obsolescence cycle
8220 add-noise = 1
8221 # make `amend --correlated` a shortcut to the main command
8222 amend-flag = correlated
8223
8224 [color]
8225 absorb.description = yellow
8226 absorb.node = blue bold
8227 absorb.path = bold
8228
8229 Commands
8230 Change creation
8231 absorb
8232 incorporate corrections into the stack of draft changesets:
8233
8234 hg absorb [OPTION] [FILE]...
8235
8236 absorb analyzes each change in your working directory and attempts to
8237 amend the changed lines into the changesets in your stack that first
8238 introduced those lines.
8239
8240 If absorb cannot find an unambiguous changeset to amend for a change,
8241 that change will be left in the working directory, untouched. They can
8242 be observed by hg status or hg diff afterwards. In other words, absorb
8243 does not write to the working directory.
8244
8245 Changesets outside the revset ::. and not public() and not merge() will
8246 not be changed.
8247
8248 Changesets that become empty after applying the changes will be
8249 deleted.
8250
8251 By default, absorb will show what it plans to do and prompt for confir‐
8252 mation. If you are confident that the changes will be absorbed to the
8253 correct place, run hg absorb -a to apply the changes immediately.
8254
8255 Returns 0 on success, 1 if all chunks were ignored and nothing amended.
8256
8257 Options:
8258
8259 -a, --apply-changes
8260 apply changes without prompting for confirmation
8261
8262 -p, --print-changes
8263 always print which changesets are modified by which changes
8264
8265 -i, --interactive
8266 interactively select which chunks to apply
8267
8268 -e, --edit-lines
8269 edit what lines belong to which changesets before commit (EXPER‐
8270 IMENTAL)
8271
8272 -n, --dry-run
8273 do not perform actions, just print output
8274
8275 --style <STYLE>
8276 display using template map file (DEPRECATED)
8277
8278 -T,--template <TEMPLATE>
8279 display with template
8280
8281 -I,--include <PATTERN[+]>
8282 include names matching the given patterns
8283
8284 -X,--exclude <PATTERN[+]>
8285 exclude names matching the given patterns
8286
8287 [+] marked option can be specified multiple times
8288
8289 acl
8290 hooks for controlling repository access
8291
8292 This hook makes it possible to allow or deny write access to given
8293 branches and paths of a repository when receiving incoming changesets
8294 via pretxnchangegroup and pretxncommit.
8295
8296 The authorization is matched based on the local user name on the system
8297 where the hook runs, and not the committer of the original changeset
8298 (since the latter is merely informative).
8299
8300 The acl hook is best used along with a restricted shell like hgsh, pre‐
8301 venting authenticating users from doing anything other than pushing or
8302 pulling. The hook is not safe to use if users have interactive shell
8303 access, as they can then disable the hook. Nor is it safe if remote
8304 users share an account, because then there is no way to distinguish
8305 them.
8306
8307 The order in which access checks are performed is:
8308
8309 1. Deny list for branches (section acl.deny.branches)
8310
8311 2. Allow list for branches (section acl.allow.branches)
8312
8313 3. Deny list for paths (section acl.deny)
8314
8315 4. Allow list for paths (section acl.allow)
8316
8317 The allow and deny sections take key-value pairs.
8318
8319 Branch-based Access Control
8320 Use the acl.deny.branches and acl.allow.branches sections to have
8321 branch-based access control. Keys in these sections can be either:
8322
8323 • a branch name, or
8324
8325 • an asterisk, to match any branch;
8326
8327 The corresponding values can be either:
8328
8329 • a comma-separated list containing users and groups, or
8330
8331 • an asterisk, to match anyone;
8332
8333 You can add the "!" prefix to a user or group name to invert the sense
8334 of the match.
8335
8336 Path-based Access Control
8337 Use the acl.deny and acl.allow sections to have path-based access con‐
8338 trol. Keys in these sections accept a subtree pattern (with a glob syn‐
8339 tax by default). The corresponding values follow the same syntax as the
8340 other sections above.
8341
8342 Bookmark-based Access Control
8343 Use the acl.deny.bookmarks and acl.allow.bookmarks sections to have
8344 bookmark-based access control. Keys in these sections can be either:
8345
8346 • a bookmark name, or
8347
8348 • an asterisk, to match any bookmark;
8349
8350 The corresponding values can be either:
8351
8352 • a comma-separated list containing users and groups, or
8353
8354 • an asterisk, to match anyone;
8355
8356 You can add the "!" prefix to a user or group name to invert the sense
8357 of the match.
8358
8359 Note: for interactions between clients and servers using Mercurial 3.6+
8360 a rejection will generally reject the entire push, for interactions in‐
8361 volving older clients, the commit transactions will already be ac‐
8362 cepted, and only the bookmark movement will be rejected.
8363
8364 Groups
8365 Group names must be prefixed with an @ symbol. Specifying a group name
8366 has the same effect as specifying all the users in that group.
8367
8368 You can define group members in the acl.groups section. If a group
8369 name is not defined there, and Mercurial is running under a Unix-like
8370 system, the list of users will be taken from the OS. Otherwise, an ex‐
8371 ception will be raised.
8372
8373 Example Configuration
8374 [hooks]
8375
8376 # Use this if you want to check access restrictions at commit time
8377 pretxncommit.acl = python:hgext.acl.hook
8378
8379 # Use this if you want to check access restrictions for pull, push,
8380 # bundle and serve.
8381 pretxnchangegroup.acl = python:hgext.acl.hook
8382
8383 [acl]
8384 # Allow or deny access for incoming changes only if their source is
8385 # listed here, let them pass otherwise. Source is "serve" for all
8386 # remote access (http or ssh), "push", "pull" or "bundle" when the
8387 # related commands are run locally.
8388 # Default: serve
8389 sources = serve
8390
8391 [acl.deny.branches]
8392
8393 # Everyone is denied to the frozen branch:
8394 frozen-branch = *
8395
8396 # A bad user is denied on all branches:
8397 * = bad-user
8398
8399 [acl.allow.branches]
8400
8401 # A few users are allowed on branch-a:
8402 branch-a = user-1, user-2, user-3
8403
8404 # Only one user is allowed on branch-b:
8405 branch-b = user-1
8406
8407 # The super user is allowed on any branch:
8408 * = super-user
8409
8410 # Everyone is allowed on branch-for-tests:
8411 branch-for-tests = *
8412
8413 [acl.deny]
8414 # This list is checked first. If a match is found, acl.allow is not
8415 # checked. All users are granted access if acl.deny is not present.
8416 # Format for both lists: glob pattern = user, ..., @group, ...
8417
8418 # To match everyone, use an asterisk for the user:
8419 # my/glob/pattern = *
8420
8421 # user6 will not have write access to any file:
8422 ** = user6
8423
8424 # Group "hg-denied" will not have write access to any file:
8425 ** = @hg-denied
8426
8427 # Nobody will be able to change "DONT-TOUCH-THIS.txt", despite
8428 # everyone being able to change all other files. See below.
8429 src/main/resources/DONT-TOUCH-THIS.txt = *
8430
8431 [acl.allow]
8432 # if acl.allow is not present, all users are allowed by default
8433 # empty acl.allow = no users allowed
8434
8435 # User "doc_writer" has write access to any file under the "docs"
8436 # folder:
8437 docs/** = doc_writer
8438
8439 # User "jack" and group "designers" have write access to any file
8440 # under the "images" folder:
8441 images/** = jack, @designers
8442
8443 # Everyone (except for "user6" and "@hg-denied" - see acl.deny above)
8444 # will have write access to any file under the "resources" folder
8445 # (except for 1 file. See acl.deny):
8446 src/main/resources/** = *
8447
8448 .hgtags = release_engineer
8449
8450 Examples using the ! prefix
8451 Suppose there's a branch that only a given user (or group) should be
8452 able to push to, and you don't want to restrict access to any other
8453 branch that may be created.
8454
8455 The "!" prefix allows you to prevent anyone except a given user or
8456 group to push changesets in a given branch or path.
8457
8458 In the examples below, we will: 1) Deny access to branch "ring" to any‐
8459 one but user "gollum" 2) Deny access to branch "lake" to anyone but
8460 members of the group "hobbit" 3) Deny access to a file to anyone but
8461 user "gollum"
8462
8463 [acl.allow.branches]
8464 # Empty
8465
8466 [acl.deny.branches]
8467
8468 # 1) only 'gollum' can commit to branch 'ring';
8469 # 'gollum' and anyone else can still commit to any other branch.
8470 ring = !gollum
8471
8472 # 2) only members of the group 'hobbit' can commit to branch 'lake';
8473 # 'hobbit' members and anyone else can still commit to any other branch.
8474 lake = !@hobbit
8475
8476 # You can also deny access based on file paths:
8477
8478 [acl.allow]
8479 # Empty
8480
8481 [acl.deny]
8482 # 3) only 'gollum' can change the file below;
8483 # 'gollum' and anyone else can still change any other file.
8484 /misty/mountains/cave/ring = !gollum
8485
8486 amend
8487 provide the amend command (EXPERIMENTAL)
8488
8489 This extension provides an amend command that is similar to commit
8490 --amend but does not prompt an editor.
8491
8492 Commands
8493 Change creation
8494 amend
8495 amend the working copy parent with all or specified outstanding
8496 changes:
8497
8498 hg amend [OPTION]... [FILE]...
8499
8500 Similar to hg commit --amend, but reuse the commit message without in‐
8501 voking editor, unless --edit was set.
8502
8503 See hg help commit for more details.
8504
8505 Options:
8506
8507 -A, --addremove
8508 mark new/missing files as added/removed before committing
8509
8510 -e, --edit
8511 invoke editor on commit messages
8512
8513 -i, --interactive
8514 use interactive mode
8515
8516 --close-branch
8517 mark a branch as closed, hiding it from the branch list
8518
8519 -s, --secret
8520 use the secret phase for committing
8521
8522 -n,--note <VALUE>
8523 store a note on the amend
8524
8525 -I,--include <PATTERN[+]>
8526 include names matching the given patterns
8527
8528 -X,--exclude <PATTERN[+]>
8529 exclude names matching the given patterns
8530
8531 -m,--message <TEXT>
8532 use text as commit message
8533
8534 -l,--logfile <FILE>
8535 read commit message from file
8536
8537 -d,--date <DATE>
8538 record the specified date as commit date
8539
8540 -u,--user <USER>
8541 record the specified user as committer
8542
8543 -D, --currentdate
8544 record the current date as commit date
8545
8546 -U, --currentuser
8547 record the current user as committer
8548
8549 [+] marked option can be specified multiple times
8550
8551 automv
8552 check for unrecorded moves at commit time (EXPERIMENTAL)
8553
8554 This extension checks at commit/amend time if any of the committed
8555 files comes from an unrecorded mv.
8556
8557 The threshold at which a file is considered a move can be set with the
8558 automv.similarity config option. This option takes a percentage between
8559 0 (disabled) and 100 (files must be identical), the default is 95.
8560
8561 beautifygraph
8562 beautify log -G output by using Unicode characters (EXPERIMENTAL)
8563
8564 A terminal with UTF-8 support and monospace narrow text are re‐
8565 quired.
8566
8567 blackbox
8568 log repository events to a blackbox for debugging
8569
8570 Logs event information to .hg/blackbox.log to help debug and diagnose
8571 problems. The events that get logged can be configured via the black‐
8572 box.track and blackbox.ignore config keys.
8573
8574 Examples:
8575
8576 [blackbox]
8577 track = *
8578 ignore = pythonhook
8579 # dirty is *EXPENSIVE* (slow);
8580 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
8581 dirty = True
8582 # record the source of log messages
8583 logsource = True
8584
8585 [blackbox]
8586 track = command, commandfinish, commandexception, exthook, pythonhook
8587
8588 [blackbox]
8589 track = incoming
8590
8591 [blackbox]
8592 # limit the size of a log file
8593 maxsize = 1.5 MB
8594 # rotate up to N log files when the current one gets too big
8595 maxfiles = 3
8596
8597 [blackbox]
8598 # Include microseconds in log entries with %f (see Python function
8599 # datetime.datetime.strftime)
8600 date-format = %Y-%m-%d @ %H:%M:%S.%f
8601
8602 Commands
8603 Repository maintenance
8604 blackbox
8605 view the recent repository events:
8606
8607 hg blackbox [OPTION]...
8608
8609 view the recent repository events
8610
8611 Options:
8612
8613 -l,--limit <VALUE>
8614 the number of events to show (default: 10)
8615
8616 bookflow
8617 implements bookmark-based branching (EXPERIMENTAL)
8618
8619 • Disables creation of new branches (config: enable_branches=False).
8620
8621 • Requires an active bookmark on commit (config: require_book‐
8622 mark=True).
8623
8624 • Doesn't move the active bookmark on update, only on commit.
8625
8626 • Requires '--rev' for moving an existing bookmark.
8627
8628 • Protects special bookmarks (config: protect=@).
8629
8630 flow related commands
8631
8632 hg book NAME
8633 create a new bookmark
8634
8635 hg book NAME -r REV
8636 move bookmark to revision (fast-forward)
8637
8638 hg up|co NAME
8639 switch to bookmark
8640
8641 hg push -B .
8642 push active bookmark
8643
8644 bugzilla
8645 hooks for integrating with the Bugzilla bug tracker
8646
8647 This hook extension adds comments on bugs in Bugzilla when changesets
8648 that refer to bugs by Bugzilla ID are seen. The comment is formatted
8649 using the Mercurial template mechanism.
8650
8651 The bug references can optionally include an update for Bugzilla of the
8652 hours spent working on the bug. Bugs can also be marked fixed.
8653
8654 Four basic modes of access to Bugzilla are provided:
8655
8656 1. Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.
8657
8658 2. Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or
8659 later.
8660
8661 3. Check data via the Bugzilla XMLRPC interface and submit bug change
8662 via email to Bugzilla email interface. Requires Bugzilla 3.4 or
8663 later.
8664
8665 4. Writing directly to the Bugzilla database. Only Bugzilla installa‐
8666 tions using MySQL are supported. Requires Python MySQLdb.
8667
8668 Writing directly to the database is susceptible to schema changes, and
8669 relies on a Bugzilla contrib script to send out bug change notification
8670 emails. This script runs as the user running Mercurial, must be run on
8671 the host with the Bugzilla install, and requires permission to read
8672 Bugzilla configuration details and the necessary MySQL user and pass‐
8673 word to have full access rights to the Bugzilla database. For these
8674 reasons this access mode is now considered deprecated, and will not be
8675 updated for new Bugzilla versions going forward. Only adding comments
8676 is supported in this access mode.
8677
8678 Access via XMLRPC needs a Bugzilla username and password to be speci‐
8679 fied in the configuration. Comments are added under that username.
8680 Since the configuration must be readable by all Mercurial users, it is
8681 recommended that the rights of that user are restricted in Bugzilla to
8682 the minimum necessary to add comments. Marking bugs fixed requires
8683 Bugzilla 4.0 and later.
8684
8685 Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email
8686 to the Bugzilla email interface to submit comments to bugs. The From:
8687 address in the email is set to the email address of the Mercurial user,
8688 so the comment appears to come from the Mercurial user. In the event
8689 that the Mercurial user email is not recognized by Bugzilla as a
8690 Bugzilla user, the email associated with the Bugzilla username used to
8691 log into Bugzilla is used instead as the source of the comment. Marking
8692 bugs fixed works on all supported Bugzilla versions.
8693
8694 Access via the REST-API needs either a Bugzilla username and password
8695 or an apikey specified in the configuration. Comments are made under
8696 the given username or the user associated with the apikey in Bugzilla.
8697
8698 Configuration items common to all access modes:
8699
8700 bugzilla.version
8701 The access type to use. Values recognized are:
8702
8703 restapi
8704
8705 Bugzilla REST-API, Bugzilla 5.0 and later.
8706
8707 xmlrpc
8708
8709 Bugzilla XMLRPC interface.
8710
8711 xmlrpc+email
8712
8713 Bugzilla XMLRPC and email interfaces.
8714
8715 3.0
8716
8717 MySQL access, Bugzilla 3.0 and later.
8718
8719 2.18
8720
8721 MySQL access, Bugzilla 2.18 and up to but not including
8722 3.0.
8723
8724 2.16
8725
8726 MySQL access, Bugzilla 2.16 and up to but not including
8727 2.18.
8728
8729 bugzilla.regexp
8730 Regular expression to match bug IDs for update in changeset com‐
8731 mit message. It must contain one "()" named group <ids> con‐
8732 taining the bug IDs separated by non-digit characters. It may
8733 also contain a named group <hours> with a floating-point number
8734 giving the hours worked on the bug. If no named groups are
8735 present, the first "()" group is assumed to contain the bug IDs,
8736 and work time is not updated. The default expression matches Bug
8737 1234, Bug no. 1234, Bug number 1234, Bugs 1234,5678, Bug 1234
8738 and 5678 and variations thereof, followed by an hours number
8739 prefixed by h or hours, e.g. hours 1.5. Matching is case insen‐
8740 sitive.
8741
8742 bugzilla.fixregexp
8743 Regular expression to match bug IDs for marking fixed in change‐
8744 set commit message. This must contain a "()" named group <ids>`
8745 containing the bug IDs separated by non-digit characters. It may
8746 also contain a named group ``<hours> with a floating-point num‐
8747 ber giving the hours worked on the bug. If no named groups are
8748 present, the first "()" group is assumed to contain the bug IDs,
8749 and work time is not updated. The default expression matches
8750 Fixes 1234, Fixes bug 1234, Fixes bugs 1234,5678, Fixes 1234 and
8751 5678 and variations thereof, followed by an hours number pre‐
8752 fixed by h or hours, e.g. hours 1.5. Matching is case insensi‐
8753 tive.
8754
8755 bugzilla.fixstatus
8756 The status to set a bug to when marking fixed. Default RESOLVED.
8757
8758 bugzilla.fixresolution
8759 The resolution to set a bug to when marking fixed. Default
8760 FIXED.
8761
8762 bugzilla.style
8763 The style file to use when formatting comments.
8764
8765 bugzilla.template
8766 Template to use when formatting comments. Overrides style if
8767 specified. In addition to the usual Mercurial keywords, the ex‐
8768 tension specifies:
8769
8770 {bug}
8771
8772 The Bugzilla bug ID.
8773
8774 {root}
8775
8776 The full pathname of the Mercurial repository.
8777
8778 {webroot}
8779
8780 Stripped pathname of the Mercurial repository.
8781
8782 {hgweb}
8783
8784 Base URL for browsing Mercurial repositories.
8785
8786 Default changeset {node|short} in repo {root} refers to bug
8787 {bug}.\ndetails:\n\t{desc|tabindent}
8788
8789 bugzilla.strip
8790 The number of path separator characters to strip from the front
8791 of the Mercurial repository path ({root} in templates) to pro‐
8792 duce {webroot}. For example, a repository with {root} /var/lo‐
8793 cal/my-project with a strip of 2 gives a value for {webroot} of
8794 my-project. Default 0.
8795
8796 web.baseurl
8797 Base URL for browsing Mercurial repositories. Referenced from
8798 templates as {hgweb}.
8799
8800 Configuration items common to XMLRPC+email and MySQL access modes:
8801
8802 bugzilla.usermap
8803 Path of file containing Mercurial committer email to Bugzilla
8804 user email mappings. If specified, the file should contain one
8805 mapping per line:
8806
8807 committer = Bugzilla user
8808
8809 See also the [usermap] section.
8810
8811 The [usermap] section is used to specify mappings of Mercurial commit‐
8812 ter email to Bugzilla user email. See also bugzilla.usermap. Contains
8813 entries of the form committer = Bugzilla user.
8814
8815 XMLRPC and REST-API access mode configuration:
8816
8817 bugzilla.bzurl
8818 The base URL for the Bugzilla installation. Default http://lo‐
8819 calhost/bugzilla.
8820
8821 bugzilla.user
8822 The username to use to log into Bugzilla via XMLRPC. Default
8823 bugs.
8824
8825 bugzilla.password
8826 The password for Bugzilla login.
8827
8828 REST-API access mode uses the options listed above as well as:
8829
8830 bugzilla.apikey
8831 An apikey generated on the Bugzilla instance for api access.
8832 Using an apikey removes the need to store the user and password
8833 options.
8834
8835 XMLRPC+email access mode uses the XMLRPC access mode configuration
8836 items, and also:
8837
8838 bugzilla.bzemail
8839 The Bugzilla email address.
8840
8841 In addition, the Mercurial email settings must be configured. See the
8842 documentation in hgrc(5), sections [email] and [smtp].
8843
8844 MySQL access mode configuration:
8845
8846 bugzilla.host
8847 Hostname of the MySQL server holding the Bugzilla database. De‐
8848 fault localhost.
8849
8850 bugzilla.db
8851 Name of the Bugzilla database in MySQL. Default bugs.
8852
8853 bugzilla.user
8854 Username to use to access MySQL server. Default bugs.
8855
8856 bugzilla.password
8857 Password to use to access MySQL server.
8858
8859 bugzilla.timeout
8860 Database connection timeout (seconds). Default 5.
8861
8862 bugzilla.bzuser
8863 Fallback Bugzilla user name to record comments with, if change‐
8864 set committer cannot be found as a Bugzilla user.
8865
8866 bugzilla.bzdir
8867 Bugzilla install directory. Used by default notify. Default
8868 /var/www/html/bugzilla.
8869
8870 bugzilla.notify
8871 The command to run to get Bugzilla to send bug change notifica‐
8872 tion emails. Substitutes from a map with 3 keys, bzdir, id (bug
8873 id) and user (committer bugzilla email). Default depends on ver‐
8874 sion; from 2.18 it is "cd %(bzdir)s && perl -T contrib/sendbug‐
8875 mail.pl %(id)s %(user)s".
8876
8877 Activating the extension:
8878
8879 [extensions]
8880 bugzilla =
8881
8882 [hooks]
8883 # run bugzilla hook on every change pulled or pushed in here
8884 incoming.bugzilla = python:hgext.bugzilla.hook
8885
8886 Example configurations:
8887
8888 XMLRPC example configuration. This uses the Bugzilla at
8889 http://my-project.org/bugzilla, logging in as user bug‐
8890 mail@my-project.org with password plugh. It is used with a collection
8891 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8892 at http://my-project.org/hg.
8893
8894 [bugzilla]
8895 bzurl=http://my-project.org/bugzilla
8896 user=bugmail@my-project.org
8897 password=plugh
8898 version=xmlrpc
8899 template=Changeset {node|short} in {root|basename}.
8900 {hgweb}/{webroot}/rev/{node|short}\n
8901 {desc}\n
8902 strip=5
8903
8904 [web]
8905 baseurl=http://my-project.org/hg
8906
8907 XMLRPC+email example configuration. This uses the Bugzilla at
8908 http://my-project.org/bugzilla, logging in as user bug‐
8909 mail@my-project.org with password plugh. It is used with a collection
8910 of Mercurial repositories in /var/local/hg/repos/, with a web interface
8911 at http://my-project.org/hg. Bug comments are sent to the Bugzilla
8912 email address bugzilla@my-project.org.
8913
8914 [bugzilla]
8915 bzurl=http://my-project.org/bugzilla
8916 user=bugmail@my-project.org
8917 password=plugh
8918 version=xmlrpc+email
8919 bzemail=bugzilla@my-project.org
8920 template=Changeset {node|short} in {root|basename}.
8921 {hgweb}/{webroot}/rev/{node|short}\n
8922 {desc}\n
8923 strip=5
8924
8925 [web]
8926 baseurl=http://my-project.org/hg
8927
8928 [usermap]
8929 user@emaildomain.com=user.name@bugzilladomain.com
8930
8931 MySQL example configuration. This has a local Bugzilla 3.2 installation
8932 in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla
8933 database name is bugs and MySQL is accessed with MySQL username bugs
8934 password XYZZY. It is used with a collection of Mercurial repositories
8935 in /var/local/hg/repos/, with a web interface at
8936 http://my-project.org/hg.
8937
8938 [bugzilla]
8939 host=localhost
8940 password=XYZZY
8941 version=3.0
8942 bzuser=unknown@domain.com
8943 bzdir=/opt/bugzilla-3.2
8944 template=Changeset {node|short} in {root|basename}.
8945 {hgweb}/{webroot}/rev/{node|short}\n
8946 {desc}\n
8947 strip=5
8948
8949 [web]
8950 baseurl=http://my-project.org/hg
8951
8952 [usermap]
8953 user@emaildomain.com=user.name@bugzilladomain.com
8954
8955 All the above add a comment to the Bugzilla bug record of the form:
8956
8957 Changeset 3b16791d6642 in repository-name.
8958 http://my-project.org/hg/repository-name/rev/3b16791d6642
8959
8960 Changeset commit comment. Bug 1234.
8961
8962 censor
8963 erase file content at a given revision
8964
8965 The censor command instructs Mercurial to erase all content of a file
8966 at a given revision without updating the changeset hash. This allows
8967 existing history to remain valid while preventing future clones/pulls
8968 from receiving the erased data.
8969
8970 Typical uses for censor are due to security or legal requirements, in‐
8971 cluding:
8972
8973 * Passwords, private keys, cryptographic material
8974 * Licensed data/code/libraries for which the license has expired
8975 * Personally Identifiable Information or other private data
8976
8977 Censored nodes can interrupt mercurial's typical operation whenever the
8978 excised data needs to be materialized. Some commands, like hg cat/hg
8979 revert, simply fail when asked to produce censored data. Others, like
8980 hg verify and hg update, must be capable of tolerating censored data to
8981 continue to function in a meaningful way. Such commands only tolerate
8982 censored file revisions if they are allowed by the "censor.policy=ig‐
8983 nore" config option.
8984
8985 A few informative commands such as hg grep will unconditionally ignore
8986 censored data and merely report that it was encountered.
8987
8988 Commands
8989 Repository maintenance
8990 censor
8991 hg censor -r REV [-t TEXT] [FILE]
8992
8993 Options:
8994
8995 -r,--rev <REV>
8996 censor file from specified revision
8997
8998 -t,--tombstone <TEXT>
8999 replacement tombstone data
9000
9001 children
9002 command to display child changesets (DEPRECATED)
9003
9004 This extension is deprecated. You should use hg log -r "children(REV)"
9005 instead.
9006
9007 Commands
9008 Change navigation
9009 children
9010 show the children of the given or working directory revision:
9011
9012 hg children [-r REV] [FILE]
9013
9014 Print the children of the working directory's revisions. If a revision
9015 is given via -r/--rev, the children of that revision will be printed.
9016 If a file argument is given, revision in which the file was last
9017 changed (after the working directory revision or the argument to --rev
9018 if given) is printed.
9019
9020 Please use hg log instead:
9021
9022 hg children => hg log -r "children(.)"
9023 hg children -r REV => hg log -r "children(REV)"
9024
9025 See hg help log and hg help revsets.children.
9026
9027 Options:
9028
9029 -r,--rev <REV>
9030 show children of the specified revision (default: .)
9031
9032 --style <STYLE>
9033 display using template map file (DEPRECATED)
9034
9035 -T,--template <TEMPLATE>
9036 display with template
9037
9038 churn
9039 command to display statistics about repository history
9040
9041 Commands
9042 Repository maintenance
9043 churn
9044 histogram of changes to the repository:
9045
9046 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
9047
9048 This command will display a histogram representing the number of
9049 changed lines or revisions, grouped according to the given template.
9050 The default template will group changes by author. The --dateformat
9051 option may be used to group the results by date instead.
9052
9053 Statistics are based on the number of changed lines, or alternatively
9054 the number of matching revisions if the --changesets option is speci‐
9055 fied.
9056
9057 Examples:
9058
9059 # display count of changed lines for every committer
9060 hg churn -T "{author|email}"
9061
9062 # display daily activity graph
9063 hg churn -f "%H" -s -c
9064
9065 # display activity of developers by month
9066 hg churn -f "%Y-%m" -s -c
9067
9068 # display count of lines changed in every year
9069 hg churn -f "%Y" -s
9070
9071 # display count of lines changed in a time range
9072 hg churn -d "2020-04 to 2020-09"
9073
9074 It is possible to map alternate email addresses to a main address by
9075 providing a file using the following format:
9076
9077 <alias email> = <actual email>
9078
9079 Such a file may be specified with the --aliases option, otherwise a
9080 .hgchurn file will be looked for in the working directory root.
9081 Aliases will be split from the rightmost "=".
9082
9083 Options:
9084
9085 -r,--rev <REV[+]>
9086 count rate for the specified revision or revset
9087
9088 -d,--date <DATE>
9089 count rate for revisions matching date spec
9090
9091 -t,--oldtemplate <TEMPLATE>
9092 template to group changesets (DEPRECATED)
9093
9094 -T,--template <TEMPLATE>
9095 template to group changesets (default: {author|email})
9096
9097 -f,--dateformat <FORMAT>
9098 strftime-compatible format for grouping by date
9099
9100 -c, --changesets
9101 count rate by number of changesets
9102
9103 -s, --sort
9104 sort by key (default: sort by count)
9105
9106 --diffstat
9107 display added/removed lines separately
9108
9109 --aliases <FILE>
9110 file with email aliases
9111
9112 -I,--include <PATTERN[+]>
9113 include names matching the given patterns
9114
9115 -X,--exclude <PATTERN[+]>
9116 exclude names matching the given patterns
9117
9118 [+] marked option can be specified multiple times
9119
9120 clonebundles
9121 advertise pre-generated bundles to seed clones
9122
9123 "clonebundles" is a server-side extension used to advertise the exis‐
9124 tence of pre-generated, externally hosted bundle files to clients that
9125 are cloning so that cloning can be faster, more reliable, and require
9126 less resources on the server. "pullbundles" is a related feature for
9127 sending pre-generated bundle files to clients as part of pull opera‐
9128 tions.
9129
9130 Cloning can be a CPU and I/O intensive operation on servers. Tradition‐
9131 ally, the server, in response to a client's request to clone, dynami‐
9132 cally generates a bundle containing the entire repository content and
9133 sends it to the client. There is no caching on the server and the
9134 server will have to redundantly generate the same outgoing bundle in
9135 response to each clone request. For servers with large repositories or
9136 with high clone volume, the load from clones can make scaling the
9137 server challenging and costly.
9138
9139 This extension provides server operators the ability to offload poten‐
9140 tially expensive clone load to an external service. Pre-generated bun‐
9141 dles also allow using more CPU intensive compression, reducing the ef‐
9142 fective bandwidth requirements.
9143
9144 Here's how clone bundles work:
9145
9146 1. A server operator establishes a mechanism for making bundle files
9147 available on a hosting service where Mercurial clients can fetch
9148 them.
9149
9150 2. A manifest file listing available bundle URLs and some optional
9151 metadata is added to the Mercurial repository on the server.
9152
9153 3. A client initiates a clone against a clone bundles aware server.
9154
9155 4. The client sees the server is advertising clone bundles and fetches
9156 the manifest listing available bundles.
9157
9158 5. The client filters and sorts the available bundles based on what it
9159 supports and prefers.
9160
9161 6. The client downloads and applies an available bundle from the
9162 server-specified URL.
9163
9164 7. The client reconnects to the original server and performs the equiv‐
9165 alent of hg pull to retrieve all repository data not in the bundle.
9166 (The repository could have been updated between when the bundle was
9167 created and when the client started the clone.) This may use "pull‐
9168 bundles".
9169
9170 Instead of the server generating full repository bundles for every
9171 clone request, it generates full bundles once and they are subsequently
9172 reused to bootstrap new clones. The server may still transfer data at
9173 clone time. However, this is only data that has been added/changed
9174 since the bundle was created. For large, established repositories, this
9175 can reduce server load for clones to less than 1% of original.
9176
9177 Here's how pullbundles work:
9178
9179 1. A manifest file listing available bundles and describing the revi‐
9180 sions is added to the Mercurial repository on the server.
9181
9182 2. A new-enough client informs the server that it supports partial
9183 pulls and initiates a pull.
9184
9185 3. If the server has pull bundles enabled and sees the client advertis‐
9186 ing partial pulls, it checks for a matching pull bundle in the mani‐
9187 fest. A bundle matches if the format is supported by the client,
9188 the client has the required revisions already and needs something
9189 from the bundle.
9190
9191 4. If there is at least one matching bundle, the server sends it to the
9192 client.
9193
9194 5. The client applies the bundle and notices that the server reply was
9195 incomplete. It initiates another pull.
9196
9197 To work, this extension requires the following of server operators:
9198
9199 • Generating bundle files of repository content (typically periodi‐
9200 cally, such as once per day).
9201
9202 • Clone bundles: A file server that clients have network access to and
9203 that Python knows how to talk to through its normal URL handling fa‐
9204 cility (typically an HTTP/HTTPS server).
9205
9206 • A process for keeping the bundles manifest in sync with available
9207 bundle files.
9208
9209 Strictly speaking, using a static file hosting server isn't required: a
9210 server operator could use a dynamic service for retrieving bundle data.
9211 However, static file hosting services are simple and scalable and
9212 should be sufficient for most needs.
9213
9214 Bundle files can be generated with the hg bundle command. Typically hg
9215 bundle --all is used to produce a bundle of the entire repository.
9216
9217 hg debugcreatestreamclonebundle can be used to produce a special
9218 streaming clonebundle. These are bundle files that are extremely effi‐
9219 cient to produce and consume (read: fast). However, they are larger
9220 than traditional bundle formats and require that clients support the
9221 exact set of repository data store formats in use by the repository
9222 that created them. Typically, a newer server can serve data that is
9223 compatible with older clients. However, streaming clone bundles don't
9224 have this guarantee. Server operators need to be aware that newer ver‐
9225 sions of Mercurial may produce streaming clone bundles incompatible
9226 with older Mercurial versions.
9227
9228 A server operator is responsible for creating a .hg/clonebundles.mani‐
9229 fest file containing the list of available bundle files suitable for
9230 seeding clones. If this file does not exist, the repository will not
9231 advertise the existence of clone bundles when clients connect. For pull
9232 bundles, .hg/pullbundles.manifest is used.
9233
9234 The manifest file contains a newline (n) delimited list of entries.
9235
9236 Each line in this file defines an available bundle. Lines have the for‐
9237 mat:
9238
9239 <URL> [<key>=<value>[ <key>=<value>]]
9240
9241 That is, a URL followed by an optional, space-delimited list of
9242 key=value pairs describing additional properties of this bundle. Both
9243 keys and values are URI encoded.
9244
9245 For pull bundles, the URL is a path under the .hg directory of the
9246 repository.
9247
9248 Keys in UPPERCASE are reserved for use by Mercurial and are defined be‐
9249 low. All non-uppercase keys can be used by site installations. An ex‐
9250 ample use for custom properties is to use the datacenter attribute to
9251 define which data center a file is hosted in. Clients could then prefer
9252 a server in the data center closest to them.
9253
9254 The following reserved keys are currently defined:
9255
9256 BUNDLESPEC
9257 A "bundle specification" string that describes the type of the
9258 bundle.
9259
9260 These are string values that are accepted by the "--type" argu‐
9261 ment of hg bundle.
9262
9263 The values are parsed in strict mode, which means they must be
9264 of the "<compression>-<type>" form. See mercurial.ex‐
9265 change.parsebundlespec() for more details.
9266
9267 hg debugbundle --spec can be used to print the bundle specifica‐
9268 tion string for a bundle file. The output of this command can be
9269 used verbatim for the value of BUNDLESPEC (it is already es‐
9270 caped).
9271
9272 Clients will automatically filter out specifications that are
9273 unknown or unsupported so they won't attempt to download some‐
9274 thing that likely won't apply.
9275
9276 The actual value doesn't impact client behavior beyond filter‐
9277 ing: clients will still sniff the bundle type from the header of
9278 downloaded files.
9279
9280 Use of this key is highly recommended, as it allows clients to
9281 easily skip unsupported bundles. If this key is not defined, an
9282 old client may attempt to apply a bundle that it is incapable of
9283 reading.
9284
9285 REQUIRESNI
9286 Whether Server Name Indication (SNI) is required to connect to
9287 the URL. SNI allows servers to use multiple certificates on the
9288 same IP. It is somewhat common in CDNs and other hosting
9289 providers. Older Python versions do not support SNI. Defining
9290 this attribute enables clients with older Python versions to
9291 filter this entry without experiencing an opaque SSL failure at
9292 connection time.
9293
9294 If this is defined, it is important to advertise a non-SNI fall‐
9295 back URL or clients running old Python releases may not be able
9296 to clone with the clonebundles facility.
9297
9298 Value should be "true".
9299
9300 REQUIREDRAM
9301 Value specifies expected memory requirements to decode the pay‐
9302 load. Values can have suffixes for common bytes sizes. e.g.
9303 "64MB".
9304
9305 This key is often used with zstd-compressed bundles using a high
9306 compression level / window size, which can require 100+ MB of
9307 memory to decode.
9308
9309 heads Used for pull bundles. This contains the ; separated changeset
9310 hashes of the heads of the bundle content.
9311
9312 bases Used for pull bundles. This contains the ; separated changeset
9313 hashes of the roots of the bundle content. This can be skipped
9314 if the bundle was created without --base.
9315
9316 Manifests can contain multiple entries. Assuming metadata is defined,
9317 clients will filter entries from the manifest that they don't support.
9318 The remaining entries are optionally sorted by client preferences
9319 (ui.clonebundleprefers config option). The client then attempts to
9320 fetch the bundle at the first URL in the remaining list.
9321
9322 Errors when downloading a bundle will fail the entire clone operation:
9323 clients do not automatically fall back to a traditional clone. The rea‐
9324 son for this is that if a server is using clone bundles, it is probably
9325 doing so because the feature is necessary to help it scale. In other
9326 words, there is an assumption that clone load will be offloaded to an‐
9327 other service and that the Mercurial server isn't responsible for serv‐
9328 ing this clone load. If that other service experiences issues and
9329 clients start mass falling back to the original Mercurial server, the
9330 added clone load could overwhelm the server due to unexpected load and
9331 effectively take it offline. Not having clients automatically fall back
9332 to cloning from the original server mitigates this scenario.
9333
9334 Because there is no automatic Mercurial server fallback on failure of
9335 the bundle hosting service, it is important for server operators to
9336 view the bundle hosting service as an extension of the Mercurial server
9337 in terms of availability and service level agreements: if the bundle
9338 hosting service goes down, so does the ability for clients to clone.
9339 Note: clients will see a message informing them how to bypass the clone
9340 bundles facility when a failure occurs. So server operators should pre‐
9341 pare for some people to follow these instructions when a failure oc‐
9342 curs, thus driving more load to the original Mercurial server when the
9343 bundle hosting service fails.
9344
9345 closehead
9346 close arbitrary heads without checking them out first
9347
9348 Commands
9349 Change manipulation
9350 close-head
9351 close the given head revisions:
9352
9353 hg close-head [OPTION]... [REV]...
9354
9355 This is equivalent to checking out each revision in a clean tree and
9356 running hg commit --close-branch, except that it doesn't change the
9357 working directory.
9358
9359 The commit message must be specified with -l or -m.
9360
9361 Options:
9362
9363 -m,--message <TEXT>
9364 use text as commit message
9365
9366 -l,--logfile <FILE>
9367 read commit message from file
9368
9369 -d,--date <DATE>
9370 record the specified date as commit date
9371
9372 -u,--user <USER>
9373 record the specified user as committer
9374
9375 -r,--rev <REV[+]>
9376 revision to check
9377
9378 [+] marked option can be specified multiple times
9379
9380 aliases: close-heads
9381
9382 commitextras
9383 adds a new flag extras to commit (ADVANCED)
9384
9385 convert
9386 import revisions from foreign VCS repositories into Mercurial
9387
9388 Commands
9389 Uncategorized commands
9390 convert
9391 convert a foreign SCM repository to a Mercurial one.:
9392
9393 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
9394
9395 Accepted source formats [identifiers]:
9396
9397 • Mercurial [hg]
9398
9399 • CVS [cvs]
9400
9401 • Darcs [darcs]
9402
9403 • git [git]
9404
9405 • Subversion [svn]
9406
9407 • Monotone [mtn]
9408
9409 • GNU Arch [gnuarch]
9410
9411 • Bazaar [bzr]
9412
9413 • Perforce [p4]
9414
9415 Accepted destination formats [identifiers]:
9416
9417 • Mercurial [hg]
9418
9419 • Subversion [svn] (history on branches is not preserved)
9420
9421 If no revision is given, all revisions will be converted. Otherwise,
9422 convert will only import up to the named revision (given in a format
9423 understood by the source).
9424
9425 If no destination directory name is specified, it defaults to the base‐
9426 name of the source with -hg appended. If the destination repository
9427 doesn't exist, it will be created.
9428
9429 By default, all sources except Mercurial will use --branchsort. Mercu‐
9430 rial uses --sourcesort to preserve original revision numbers order.
9431 Sort modes have the following effects:
9432
9433 --branchsort
9434 convert from parent to child revision when possible, which means
9435 branches are usually converted one after the other. It generates
9436 more compact repositories.
9437
9438 --datesort
9439 sort revisions by date. Converted repositories have good-looking
9440 changelogs but are often an order of magnitude larger than the
9441 same ones generated by --branchsort.
9442
9443 --sourcesort
9444 try to preserve source revisions order, only supported by Mercu‐
9445 rial sources.
9446
9447 --closesort
9448 try to move closed revisions as close as possible to parent
9449 branches, only supported by Mercurial sources.
9450
9451 If REVMAP isn't given, it will be put in a default location
9452 (<dest>/.hg/shamap by default). The REVMAP is a simple text file that
9453 maps each source commit ID to the destination ID for that revision,
9454 like so:
9455
9456 <source ID> <destination ID>
9457
9458 If the file doesn't exist, it's automatically created. It's updated on
9459 each commit copied, so hg convert can be interrupted and can be run re‐
9460 peatedly to copy new commits.
9461
9462 The authormap is a simple text file that maps each source commit author
9463 to a destination commit author. It is handy for source SCMs that use
9464 unix logins to identify authors (e.g.: CVS). One line per author map‐
9465 ping and the line format is:
9466
9467 source author = destination author
9468
9469 Empty lines and lines starting with a # are ignored.
9470
9471 The filemap is a file that allows filtering and remapping of files and
9472 directories. Each line can contain one of the following directives:
9473
9474 include path/to/file-or-dir
9475
9476 exclude path/to/file-or-dir
9477
9478 rename path/to/source path/to/destination
9479
9480 Comment lines start with #. A specified path matches if it equals the
9481 full relative name of a file or one of its parent directories. The in‐
9482 clude or exclude directive with the longest matching path applies, so
9483 line order does not matter.
9484
9485 The include directive causes a file, or all files under a directory, to
9486 be included in the destination repository. The default if there are no
9487 include statements is to include everything. If there are any include
9488 statements, nothing else is included. The exclude directive causes
9489 files or directories to be omitted. The rename directive renames a file
9490 or directory if it is converted. To rename from a subdirectory into the
9491 root of the repository, use . as the path to rename to.
9492
9493 --full will make sure the converted changesets contain exactly the
9494 right files with the right content. It will make a full conversion of
9495 all files, not just the ones that have changed. Files that already are
9496 correct will not be changed. This can be used to apply filemap changes
9497 when converting incrementally. This is currently only supported for
9498 Mercurial and Subversion.
9499
9500 The splicemap is a file that allows insertion of synthetic history,
9501 letting you specify the parents of a revision. This is useful if you
9502 want to e.g. give a Subversion merge two parents, or graft two discon‐
9503 nected series of history together. Each entry contains a key, followed
9504 by a space, followed by one or two comma-separated values:
9505
9506 key parent1, parent2
9507
9508 The key is the revision ID in the source revision control system whose
9509 parents should be modified (same format as a key in .hg/shamap). The
9510 values are the revision IDs (in either the source or destination revi‐
9511 sion control system) that should be used as the new parents for that
9512 node. For example, if you have merged "release-1.0" into "trunk", then
9513 you should specify the revision on "trunk" as the first parent and the
9514 one on the "release-1.0" branch as the second.
9515
9516 The branchmap is a file that allows you to rename a branch when it is
9517 being brought in from whatever external repository. When used in con‐
9518 junction with a splicemap, it allows for a powerful combination to help
9519 fix even the most badly mismanaged repositories and turn them into
9520 nicely structured Mercurial repositories. The branchmap contains lines
9521 of the form:
9522
9523 original_branch_name new_branch_name
9524
9525 where "original_branch_name" is the name of the branch in the source
9526 repository, and "new_branch_name" is the name of the branch is the des‐
9527 tination repository. No whitespace is allowed in the new branch name.
9528 This can be used to (for instance) move code in one repository from
9529 "default" to a named branch.
9530
9531 Mercurial Source
9532 The Mercurial source recognizes the following configuration options,
9533 which you can set on the command line with --config:
9534
9535 convert.hg.ignoreerrors
9536 ignore integrity errors when reading. Use it to fix Mercurial
9537 repositories with missing revlogs, by converting from and to
9538 Mercurial. Default is False.
9539
9540 convert.hg.saverev
9541 store original revision ID in changeset (forces target IDs to
9542 change). It takes a boolean argument and defaults to False.
9543
9544 convert.hg.startrev
9545 specify the initial Mercurial revision. The default is 0.
9546
9547 convert.hg.revs
9548 revset specifying the source revisions to convert.
9549
9550 Bazaar Source
9551 The following options can be used with --config:
9552
9553 convert.bzr.saverev
9554 whether to store the original Bazaar commit ID in the metadata
9555 of the destination commit. The default is True.
9556
9557 CVS Source
9558 CVS source will use a sandbox (i.e. a checked-out copy) from CVS to in‐
9559 dicate the starting point of what will be converted. Direct access to
9560 the repository files is not needed, unless of course the repository is
9561 :local:. The conversion uses the top level directory in the sandbox to
9562 find the CVS repository, and then uses CVS rlog commands to find files
9563 to convert. This means that unless a filemap is given, all files under
9564 the starting directory will be converted, and that any directory reor‐
9565 ganization in the CVS sandbox is ignored.
9566
9567 The following options can be used with --config:
9568
9569 convert.cvsps.cache
9570 Set to False to disable remote log caching, for testing and de‐
9571 bugging purposes. Default is True.
9572
9573 convert.cvsps.fuzz
9574 Specify the maximum time (in seconds) that is allowed between
9575 commits with identical user and log message in a single change‐
9576 set. When very large files were checked in as part of a change‐
9577 set then the default may not be long enough. The default is 60.
9578
9579 convert.cvsps.logencoding
9580 Specify encoding name to be used for transcoding CVS log mes‐
9581 sages. Multiple encoding names can be specified as a list (see
9582 hg help config.Syntax), but only the first acceptable encoding
9583 in the list is used per CVS log entries. This transcoding is ex‐
9584 ecuted before cvslog hook below.
9585
9586 convert.cvsps.mergeto
9587 Specify a regular expression to which commit log messages are
9588 matched. If a match occurs, then the conversion process will in‐
9589 sert a dummy revision merging the branch on which this log mes‐
9590 sage occurs to the branch indicated in the regex. Default is
9591 {{mergetobranch ([-\w]+)}}
9592
9593 convert.cvsps.mergefrom
9594 Specify a regular expression to which commit log messages are
9595 matched. If a match occurs, then the conversion process will add
9596 the most recent revision on the branch indicated in the regex as
9597 the second parent of the changeset. Default is {{mergefrombranch
9598 ([-\w]+)}}
9599
9600 convert.localtimezone
9601 use local time (as determined by the TZ environment variable)
9602 for changeset date/times. The default is False (use UTC).
9603
9604 hooks.cvslog
9605 Specify a Python function to be called at the end of gathering
9606 the CVS log. The function is passed a list with the log entries,
9607 and can modify the entries in-place, or add or delete them.
9608
9609 hooks.cvschangesets
9610 Specify a Python function to be called after the changesets are
9611 calculated from the CVS log. The function is passed a list with
9612 the changeset entries, and can modify the changesets in-place,
9613 or add or delete them.
9614
9615 An additional "debugcvsps" Mercurial command allows the builtin change‐
9616 set merging code to be run without doing a conversion. Its parameters
9617 and output are similar to that of cvsps 2.1. Please see the command
9618 help for more details.
9619
9620 Subversion Source
9621 Subversion source detects classical trunk/branches/tags layouts. By
9622 default, the supplied svn://repo/path/ source URL is converted as a
9623 single branch. If svn://repo/path/trunk exists it replaces the default
9624 branch. If svn://repo/path/branches exists, its subdirectories are
9625 listed as possible branches. If svn://repo/path/tags exists, it is
9626 looked for tags referencing converted branches. Default trunk, branches
9627 and tags values can be overridden with following options. Set them to
9628 paths relative to the source URL, or leave them blank to disable auto
9629 detection.
9630
9631 The following options can be set with --config:
9632
9633 convert.svn.branches
9634 specify the directory containing branches. The default is
9635 branches.
9636
9637 convert.svn.tags
9638 specify the directory containing tags. The default is tags.
9639
9640 convert.svn.trunk
9641 specify the name of the trunk branch. The default is trunk.
9642
9643 convert.localtimezone
9644 use local time (as determined by the TZ environment variable)
9645 for changeset date/times. The default is False (use UTC).
9646
9647 Source history can be retrieved starting at a specific revision, in‐
9648 stead of being integrally converted. Only single branch conversions are
9649 supported.
9650
9651 convert.svn.startrev
9652 specify start Subversion revision number. The default is 0.
9653
9654 Git Source
9655 The Git importer converts commits from all reachable branches (refs in
9656 refs/heads) and remotes (refs in refs/remotes) to Mercurial. Branches
9657 are converted to bookmarks with the same name, with the leading
9658 'refs/heads' stripped. Git submodules are converted to Git subrepos in
9659 Mercurial.
9660
9661 The following options can be set with --config:
9662
9663 convert.git.similarity
9664 specify how similar files modified in a commit must be to be im‐
9665 ported as renames or copies, as a percentage between 0 (dis‐
9666 abled) and 100 (files must be identical). For example, 90 means
9667 that a delete/add pair will be imported as a rename if more than
9668 90% of the file hasn't changed. The default is 50.
9669
9670 convert.git.findcopiesharder
9671 while detecting copies, look at all files in the working copy
9672 instead of just changed ones. This is very expensive for large
9673 projects, and is only effective when convert.git.similarity is
9674 greater than 0. The default is False.
9675
9676 convert.git.renamelimit
9677 perform rename and copy detection up to this many changed files
9678 in a commit. Increasing this will make rename and copy detection
9679 more accurate but will significantly slow down computation on
9680 large projects. The option is only relevant if convert.git.simi‐
9681 larity is greater than 0. The default is 400.
9682
9683 convert.git.committeractions
9684 list of actions to take when processing author and committer
9685 values.
9686
9687 Git commits have separate author (who wrote the commit) and com‐
9688 mitter (who applied the commit) fields. Not all destinations
9689 support separate author and committer fields (including Mercu‐
9690 rial). This config option controls what to do with these author
9691 and committer fields during conversion.
9692
9693 A value of messagedifferent will append a committer: ... line
9694 to the commit message if the Git committer is different from the
9695 author. The prefix of that line can be specified using the syn‐
9696 tax messagedifferent=<prefix>. e.g. messagedifferent=git-commit‐
9697 ter:. When a prefix is specified, a space will always be in‐
9698 serted between the prefix and the value.
9699
9700 messagealways behaves like messagedifferent except it will al‐
9701 ways result in a committer: ... line being appended to the com‐
9702 mit message. This value is mutually exclusive with messagedif‐
9703 ferent.
9704
9705 dropcommitter will remove references to the committer. Only ref‐
9706 erences to the author will remain. Actions that add references
9707 to the committer will have no effect when this is set.
9708
9709 replaceauthor will replace the value of the author field with
9710 the committer. Other actions that add references to the commit‐
9711 ter will still take effect when this is set.
9712
9713 The default is messagedifferent.
9714
9715 convert.git.extrakeys
9716 list of extra keys from commit metadata to copy to the destina‐
9717 tion. Some Git repositories store extra metadata in commits. By
9718 default, this non-default metadata will be lost during conver‐
9719 sion. Setting this config option can retain that metadata. Some
9720 built-in keys such as parent and branch are not allowed to be
9721 copied.
9722
9723 convert.git.remoteprefix
9724 remote refs are converted as bookmarks with convert.git.re‐
9725 moteprefix as a prefix followed by a /. The default is 'remote'.
9726
9727 convert.git.saverev
9728 whether to store the original Git commit ID in the metadata of
9729 the destination commit. The default is True.
9730
9731 convert.git.skipsubmodules
9732 does not convert root level .gitmodules files or files with
9733 160000 mode indicating a submodule. Default is False.
9734
9735 Perforce Source
9736 The Perforce (P4) importer can be given a p4 depot path or a client
9737 specification as source. It will convert all files in the source to a
9738 flat Mercurial repository, ignoring labels, branches and integrations.
9739 Note that when a depot path is given you then usually should specify a
9740 target directory, because otherwise the target may be named ...-hg.
9741
9742 The following options can be set with --config:
9743
9744 convert.p4.encoding
9745 specify the encoding to use when decoding standard output of the
9746 Perforce command line tool. The default is default system encod‐
9747 ing.
9748
9749 convert.p4.startrev
9750 specify initial Perforce revision (a Perforce changelist num‐
9751 ber).
9752
9753 Mercurial Destination
9754 The Mercurial destination will recognize Mercurial subrepositories in
9755 the destination directory, and update the .hgsubstate file automati‐
9756 cally if the destination subrepositories contain the
9757 <dest>/<sub>/.hg/shamap file. Converting a repository with subreposi‐
9758 tories requires converting a single repository at a time, from the bot‐
9759 tom up.
9760
9761 An example showing how to convert a repository with subrepositories:
9762
9763 # so convert knows the type when it sees a non empty destination
9764 $ hg init converted
9765
9766 $ hg convert orig/sub1 converted/sub1
9767 $ hg convert orig/sub2 converted/sub2
9768 $ hg convert orig converted
9769
9770 The following options are supported:
9771
9772 convert.hg.clonebranches
9773 dispatch source branches in separate clones. The default is
9774 False.
9775
9776 convert.hg.tagsbranch
9777 branch name for tag revisions, defaults to default.
9778
9779 convert.hg.usebranchnames
9780 preserve branch names. The default is True.
9781
9782 convert.hg.sourcename
9783 records the given string as a 'convert_source' extra value on
9784 each commit made in the target repository. The default is None.
9785
9786 convert.hg.preserve-hash
9787 only works with mercurial sources. Make convert prevent perfor‐
9788 mance improvement to the list of modified files in commits when
9789 such an improvement would cause the hash of a commit to change.
9790 The default is False.
9791
9792 All Destinations
9793 All destination types accept the following options:
9794
9795 convert.skiptags
9796 does not convert tags from the source repo to the target repo.
9797 The default is False.
9798
9799 Subversion Destination
9800 Original commit dates are not preserved by default.
9801
9802 convert.svn.dangerous-set-commit-dates
9803 preserve original commit dates, forcefully setting svn:date re‐
9804 vision properties. This option is DANGEROUS and may break some
9805 subversion functionality for the resulting repository (e.g. fil‐
9806 tering revisions with date ranges in svn log), as original com‐
9807 mit dates are not guaranteed to be monotonically increasing.
9808
9809 For commit dates setting to work destination repository must have
9810 pre-revprop-change hook configured to allow setting of svn:date revi‐
9811 sion properties. See Subversion documentation for more details.
9812
9813 Options:
9814
9815 --authors <FILE>
9816 username mapping filename (DEPRECATED) (use --authormap instead)
9817
9818 -s,--source-type <TYPE>
9819 source repository type
9820
9821 -d,--dest-type <TYPE>
9822 destination repository type
9823
9824 -r,--rev <REV[+]>
9825 import up to source revision REV
9826
9827 -A,--authormap <FILE>
9828 remap usernames using this file
9829
9830 --filemap <FILE>
9831 remap file names using contents of file
9832
9833 --full apply filemap changes by converting all files again
9834
9835 --splicemap <FILE>
9836 splice synthesized history into place
9837
9838 --branchmap <FILE>
9839 change branch names while converting
9840
9841 --branchsort
9842 try to sort changesets by branches
9843
9844 --datesort
9845 try to sort changesets by date
9846
9847 --sourcesort
9848 preserve source changesets order
9849
9850 --closesort
9851 try to reorder closed revisions
9852
9853 [+] marked option can be specified multiple times
9854
9855 eol
9856 automatically manage newlines in repository files
9857
9858 This extension allows you to manage the type of line endings (CRLF or
9859 LF) that are used in the repository and in the local working directory.
9860 That way you can get CRLF line endings on Windows and LF on Unix/Mac,
9861 thereby letting everybody use their OS native line endings.
9862
9863 The extension reads its configuration from a versioned .hgeol configu‐
9864 ration file found in the root of the working directory. The .hgeol file
9865 use the same syntax as all other Mercurial configuration files. It uses
9866 two sections, [patterns] and [repository].
9867
9868 The [patterns] section specifies how line endings should be converted
9869 between the working directory and the repository. The format is speci‐
9870 fied by a file pattern. The first match is used, so put more specific
9871 patterns first. The available line endings are LF, CRLF, and BIN.
9872
9873 Files with the declared format of CRLF or LF are always checked out and
9874 stored in the repository in that format and files declared to be binary
9875 (BIN) are left unchanged. Additionally, native is an alias for checking
9876 out in the platform's default line ending: LF on Unix (including Mac OS
9877 X) and CRLF on Windows. Note that BIN (do nothing to line endings) is
9878 Mercurial's default behavior; it is only needed if you need to override
9879 a later, more general pattern.
9880
9881 The optional [repository] section specifies the line endings to use for
9882 files stored in the repository. It has a single setting, native, which
9883 determines the storage line endings for files declared as native in the
9884 [patterns] section. It can be set to LF or CRLF. The default is LF. For
9885 example, this means that on Windows, files configured as native (CRLF
9886 by default) will be converted to LF when stored in the repository.
9887 Files declared as LF, CRLF, or BIN in the [patterns] section are always
9888 stored as-is in the repository.
9889
9890 Example versioned .hgeol file:
9891
9892 [patterns]
9893 **.py = native
9894 **.vcproj = CRLF
9895 **.txt = native
9896 Makefile = LF
9897 **.jpg = BIN
9898
9899 [repository]
9900 native = LF
9901
9902 Note The rules will first apply when files are touched in the working
9903 directory, e.g. by updating to null and back to tip to touch all
9904 files.
9905
9906 The extension uses an optional [eol] section read from both the normal
9907 Mercurial configuration files and the .hgeol file, with the latter
9908 overriding the former. You can use that section to control the overall
9909 behavior. There are three settings:
9910
9911 • eol.native (default os.linesep) can be set to LF or CRLF to override
9912 the default interpretation of native for checkout. This can be used
9913 with hg archive on Unix, say, to generate an archive where files have
9914 line endings for Windows.
9915
9916 • eol.only-consistent (default True) can be set to False to make the
9917 extension convert files with inconsistent EOLs. Inconsistent means
9918 that there is both CRLF and LF present in the file. Such files are
9919 normally not touched under the assumption that they have mixed EOLs
9920 on purpose.
9921
9922 • eol.fix-trailing-newline (default False) can be set to True to ensure
9923 that converted files end with a EOL character (either \n or \r\n as
9924 per the configured patterns).
9925
9926 The extension provides cleverencode: and cleverdecode: filters like the
9927 deprecated win32text extension does. This means that you can disable
9928 win32text and enable eol and your filters will still work. You only
9929 need to these filters until you have prepared a .hgeol file.
9930
9931 The win32text.forbid* hooks provided by the win32text extension have
9932 been unified into a single hook named eol.checkheadshook. The hook will
9933 lookup the expected line endings from the .hgeol file, which means you
9934 must migrate to a .hgeol file first before using the hook. eol.check‐
9935 headshook only checks heads, intermediate invalid revisions will be
9936 pushed. To forbid them completely, use the eol.checkallhook hook. These
9937 hooks are best used as pretxnchangegroup hooks.
9938
9939 See hg help patterns for more information about the glob patterns used.
9940
9941 extdiff
9942 command to allow external programs to compare revisions
9943
9944 The extdiff Mercurial extension allows you to use external programs to
9945 compare revisions, or revision with working directory. The external
9946 diff programs are called with a configurable set of options and two
9947 non-option arguments: paths to directories containing snapshots of
9948 files to compare.
9949
9950 If there is more than one file being compared and the "child" revision
9951 is the working directory, any modifications made in the external diff
9952 program will be copied back to the working directory from the temporary
9953 directory.
9954
9955 The extdiff extension also allows you to configure new diff commands,
9956 so you do not need to type hg extdiff -p kdiff3 always.
9957
9958 [extdiff]
9959 # add new command that runs GNU diff(1) in 'context diff' mode
9960 cdiff = gdiff -Nprc5
9961 ## or the old way:
9962 #cmd.cdiff = gdiff
9963 #opts.cdiff = -Nprc5
9964
9965 # add new command called meld, runs meld (no need to name twice). If
9966 # the meld executable is not available, the meld tool in [merge-tools]
9967 # will be used, if available
9968 meld =
9969
9970 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
9971 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
9972 # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
9973 # your .vimrc
9974 vimdiff = gvim -f "+next" \
9975 "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
9976
9977 Tool arguments can include variables that are expanded at runtime:
9978
9979 $parent1, $plabel1 - filename, descriptive label of first parent
9980 $child, $clabel - filename, descriptive label of child revision
9981 $parent2, $plabel2 - filename, descriptive label of second parent
9982 $root - repository root
9983 $parent is an alias for $parent1.
9984
9985 The extdiff extension will look in your [diff-tools] and [merge-tools]
9986 sections for diff tool arguments, when none are specified in [extdiff].
9987
9988 [extdiff]
9989 kdiff3 =
9990
9991 [diff-tools]
9992 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
9993
9994 If a program has a graphical interface, it might be interesting to tell
9995 Mercurial about it. It will prevent the program from being mistakenly
9996 used in a terminal-only environment (such as an SSH terminal session),
9997 and will make hg extdiff --per-file open multiple file diffs at once
9998 instead of one by one (if you still want to open file diffs one by one,
9999 you can use the --confirm option).
10000
10001 Declaring that a tool has a graphical interface can be done with the
10002 gui flag next to where diffargs are specified:
10003
10004 [diff-tools]
10005 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
10006 kdiff3.gui = true
10007
10008 You can use -I/-X and list of file or directory names like normal hg
10009 diff command. The extdiff extension makes snapshots of only needed
10010 files, so running the external diff program will actually be pretty
10011 fast (at least faster than having to compare the entire tree).
10012
10013 Commands
10014 File content management
10015 extdiff
10016 use external program to diff repository (or selected files):
10017
10018 hg extdiff [OPT]... [FILE]...
10019
10020 Show differences between revisions for the specified files, using an
10021 external program. The default program used is diff, with default op‐
10022 tions "-Npru".
10023
10024 To select a different program, use the -p/--program option. The program
10025 will be passed the names of two directories to compare, unless the
10026 --per-file option is specified (see below). To pass additional options
10027 to the program, use -o/--option. These will be passed before the names
10028 of the directories or files to compare.
10029
10030 The --from, --to, and --change options work the same way they do for hg
10031 diff.
10032
10033 The --per-file option runs the external program repeatedly on each file
10034 to diff, instead of once on two directories. By default, this happens
10035 one by one, where the next file diff is open in the external program
10036 only once the previous external program (for the previous file diff)
10037 has exited. If the external program has a graphical interface, it can
10038 open all the file diffs at once instead of one by one. See hg help -e
10039 extdiff for information about how to tell Mercurial that a given pro‐
10040 gram has a graphical interface.
10041
10042 The --confirm option will prompt the user before each invocation of the
10043 external program. It is ignored if --per-file isn't specified.
10044
10045 Options:
10046
10047 -p,--program <CMD>
10048 comparison program to run
10049
10050 -o,--option <OPT[+]>
10051 pass option to comparison program
10052
10053 -r,--rev <REV[+]>
10054 revision (DEPRECATED)
10055
10056 --from <REV1>
10057 revision to diff from
10058
10059 --to <REV2>
10060 revision to diff to
10061
10062 -c,--change <REV>
10063 change made by revision
10064
10065 --per-file
10066 compare each file instead of revision snapshots
10067
10068 --confirm
10069 prompt user before each external program invocation
10070
10071 --patch
10072 compare patches for two revisions
10073
10074 -I,--include <PATTERN[+]>
10075 include names matching the given patterns
10076
10077 -X,--exclude <PATTERN[+]>
10078 exclude names matching the given patterns
10079
10080 -S, --subrepos
10081 recurse into subrepositories
10082
10083 [+] marked option can be specified multiple times
10084
10085 factotum
10086 http authentication with factotum
10087
10088 This extension allows the factotum(4) facility on Plan 9 from Bell Labs
10089 platforms to provide authentication information for HTTP access. Con‐
10090 figuration entries specified in the auth section as well as authentica‐
10091 tion information provided in the repository URL are fully supported. If
10092 no prefix is specified, a value of "*" will be assumed.
10093
10094 By default, keys are specified as:
10095
10096 proto=pass service=hg prefix=<prefix> user=<username> !password=<password>
10097
10098 If the factotum extension is unable to read the required key, one will
10099 be requested interactively.
10100
10101 A configuration section is available to customize runtime behavior. By
10102 default, these entries are:
10103
10104 [factotum]
10105 executable = /bin/auth/factotum
10106 mountpoint = /mnt/factotum
10107 service = hg
10108
10109 The executable entry defines the full path to the factotum binary. The
10110 mountpoint entry defines the path to the factotum file service. Lastly,
10111 the service entry controls the service name used when reading keys.
10112
10113 fastannotate
10114 yet another annotate implementation that might be faster (EXPERIMENTAL)
10115
10116 The fastannotate extension provides a 'fastannotate' command that makes
10117 use of the linelog data structure as a cache layer and is expected to
10118 be faster than the vanilla 'annotate' if the cache is present.
10119
10120 In most cases, fastannotate requires a setup that mainbranch is some
10121 pointer that always moves forward, to be most efficient.
10122
10123 Using fastannotate together with linkrevcache would speed up building
10124 the annotate cache greatly. Run "debugbuildlinkrevcache" before "debug‐
10125 buildannotatecache".
10126
10127 [fastannotate]
10128 # specify the main branch head. the internal linelog will only contain
10129 # the linear (ignoring p2) "mainbranch". since linelog cannot move
10130 # backwards without a rebuild, this should be something that always moves
10131 # forward, usually it is "master" or "@".
10132 mainbranch = master
10133
10134 # fastannotate supports different modes to expose its feature.
10135 # a list of combination:
10136 # - fastannotate: expose the feature via the "fastannotate" command which
10137 # deals with everything in a most efficient way, and provides extra
10138 # features like --deleted etc.
10139 # - fctx: replace fctx.annotate implementation. note:
10140 # a. it is less efficient than the "fastannotate" command
10141 # b. it will make it practically impossible to access the old (disk
10142 # side-effect free) annotate implementation
10143 # c. it implies "hgweb".
10144 # - hgweb: replace hgweb's annotate implementation. conflict with "fctx".
10145 # (default: fastannotate)
10146 modes = fastannotate
10147
10148 # default format when no format flags are used (default: number)
10149 defaultformat = changeset, user, date
10150
10151 # serve the annotate cache via wire protocol (default: False)
10152 # tip: the .hg/fastannotate directory is portable - can be rsynced
10153 server = True
10154
10155 # build annotate cache on demand for every client request (default: True)
10156 # disabling it could make server response faster, useful when there is a
10157 # cronjob building the cache.
10158 serverbuildondemand = True
10159
10160 # update local annotate cache from remote on demand
10161 client = False
10162
10163 # path to use when connecting to the remote server (default: default)
10164 remotepath = default
10165
10166 # minimal length of the history of a file required to fetch linelog from
10167 # the server. (default: 10)
10168 clientfetchthreshold = 10
10169
10170 # for "fctx" mode, always follow renames regardless of command line option.
10171 # this is a BC with the original command but will reduced the space needed
10172 # for annotate cache, and is useful for client-server setup since the
10173 # server will only provide annotate cache with default options (i.e. with
10174 # follow). do not affect "fastannotate" mode. (default: True)
10175 forcefollow = True
10176
10177 # for "fctx" mode, always treat file as text files, to skip the "isbinary"
10178 # check. this is consistent with the "fastannotate" command and could help
10179 # to avoid a file fetch if remotefilelog is used. (default: True)
10180 forcetext = True
10181
10182 # use unfiltered repo for better performance.
10183 unfilteredrepo = True
10184
10185 # sacrifice correctness in some corner cases for performance. it does not
10186 # affect the correctness of the annotate cache being built. the option
10187 # is experimental and may disappear in the future (default: False)
10188 perfhack = True
10189
10190 Commands
10191 Uncategorized commands
10192 fastexport
10193 export repositories as git fast-import stream
10194
10195 Commands
10196 Change import/export
10197 fastexport
10198 export repository as git fast-import stream:
10199
10200 hg fastexport [OPTION]... [REV]...
10201
10202 This command lets you dump a repository as a human-readable text
10203 stream. It can be piped into corresponding import routines like "git
10204 fast-import". Incremental dumps can be created by using marks files.
10205
10206 Options:
10207
10208 -r,--rev <REV[+]>
10209 revisions to export
10210
10211 -i,--import-marks <FILE>
10212 old marks file to read
10213
10214 -e,--export-marks <FILE>
10215 new marks file to write
10216
10217 -A,--authormap <FILE>
10218 remap usernames using this file
10219
10220 [+] marked option can be specified multiple times
10221
10222 fetch
10223 pull, update and merge in one command (DEPRECATED)
10224
10225 Commands
10226 Remote repository management
10227 fetch
10228 pull changes from a remote repository, merge new changes if needed.:
10229
10230 hg fetch [SOURCE]
10231
10232 This finds all changes from the repository at the specified path or URL
10233 and adds them to the local repository.
10234
10235 If the pulled changes add a new branch head, the head is automatically
10236 merged, and the result of the merge is committed. Otherwise, the work‐
10237 ing directory is updated to include the new changes.
10238
10239 When a merge is needed, the working directory is first updated to the
10240 newly pulled changes. Local changes are then merged into the pulled
10241 changes. To switch the merge order, use --switch-parent.
10242
10243 See hg help dates for a list of formats valid for -d/--date.
10244
10245 Returns 0 on success.
10246
10247 Options:
10248
10249 -r,--rev <REV[+]>
10250 a specific revision you would like to pull
10251
10252 --edit invoke editor on commit messages
10253
10254 --force-editor
10255 edit commit message (DEPRECATED)
10256
10257 --switch-parent
10258 switch parents when merging
10259
10260 -m,--message <TEXT>
10261 use text as commit message
10262
10263 -l,--logfile <FILE>
10264 read commit message from file
10265
10266 -d,--date <DATE>
10267 record the specified date as commit date
10268
10269 -u,--user <USER>
10270 record the specified user as committer
10271
10272 -e,--ssh <CMD>
10273 specify ssh command to use
10274
10275 --remotecmd <CMD>
10276 specify hg command to run on the remote side
10277
10278 --insecure
10279 do not verify server certificate (ignoring web.cacerts config)
10280
10281 [+] marked option can be specified multiple times
10282
10283 fix
10284 rewrite file content in changesets or working copy (EXPERIMENTAL)
10285
10286 Provides a command that runs configured tools on the contents of modi‐
10287 fied files, writing back any fixes to the working copy or replacing
10288 changesets.
10289
10290 Here is an example configuration that causes hg fix to apply automatic
10291 formatting fixes to modified lines in C++ code:
10292
10293 [fix]
10294 clang-format:command=clang-format --assume-filename={rootpath}
10295 clang-format:linerange=--lines={first}:{last}
10296 clang-format:pattern=set:**.cpp or **.hpp
10297
10298 The :command suboption forms the first part of the shell command that
10299 will be used to fix a file. The content of the file is passed on stan‐
10300 dard input, and the fixed file content is expected on standard output.
10301 Any output on standard error will be displayed as a warning. If the
10302 exit status is not zero, the file will not be affected. A placeholder
10303 warning is displayed if there is a non-zero exit status but no standard
10304 error output. Some values may be substituted into the command:
10305
10306 {rootpath} The path of the file being fixed, relative to the repo root
10307 {basename} The name of the file being fixed, without the directory path
10308
10309 If the :linerange suboption is set, the tool will only be run if there
10310 are changed lines in a file. The value of this suboption is appended to
10311 the shell command once for every range of changed lines in the file.
10312 Some values may be substituted into the command:
10313
10314 {first} The 1-based line number of the first line in the modified range
10315 {last} The 1-based line number of the last line in the modified range
10316
10317 Deleted sections of a file will be ignored by :linerange, because there
10318 is no corresponding line range in the version being fixed.
10319
10320 By default, tools that set :linerange will only be executed if there is
10321 at least one changed line range. This is meant to prevent accidents
10322 like running a code formatter in such a way that it unexpectedly refor‐
10323 mats the whole file. If such a tool needs to operate on unchanged
10324 files, it should set the :skipclean suboption to false.
10325
10326 The :pattern suboption determines which files will be passed through
10327 each configured tool. See hg help patterns for possible values. How‐
10328 ever, all patterns are relative to the repo root, even if that text
10329 says they are relative to the current working directory. If there are
10330 file arguments to hg fix, the intersection of these patterns is used.
10331
10332 There is also a configurable limit for the maximum size of file that
10333 will be processed by hg fix:
10334
10335 [fix]
10336 maxfilesize = 2MB
10337
10338 Normally, execution of configured tools will continue after a failure
10339 (indicated by a non-zero exit status). It can also be configured to
10340 abort after the first such failure, so that no files will be affected
10341 if any tool fails. This abort will also cause hg fix to exit with a
10342 non-zero status:
10343
10344 [fix]
10345 failure = abort
10346
10347 When multiple tools are configured to affect a file, they execute in an
10348 order defined by the :priority suboption. The priority suboption has a
10349 default value of zero for each tool. Tools are executed in order of de‐
10350 scending priority. The execution order of tools with equal priority is
10351 unspecified. For example, you could use the 'sort' and 'head' utilities
10352 to keep only the 10 smallest numbers in a text file by ensuring that
10353 'sort' runs before 'head':
10354
10355 [fix]
10356 sort:command = sort -n
10357 head:command = head -n 10
10358 sort:pattern = numbers.txt
10359 head:pattern = numbers.txt
10360 sort:priority = 2
10361 head:priority = 1
10362
10363 To account for changes made by each tool, the line numbers used for in‐
10364 cremental formatting are recomputed before executing the next tool. So,
10365 each tool may see different values for the arguments added by the :lin‐
10366 erange suboption.
10367
10368 Each fixer tool is allowed to return some metadata in addition to the
10369 fixed file content. The metadata must be placed before the file content
10370 on stdout, separated from the file content by a zero byte. The metadata
10371 is parsed as a JSON value (so, it should be UTF-8 encoded and contain
10372 no zero bytes). A fixer tool is expected to produce this metadata en‐
10373 coding if and only if the :metadata suboption is true:
10374
10375 [fix]
10376 tool:command = tool --prepend-json-metadata
10377 tool:metadata = true
10378
10379 The metadata values are passed to hooks, which can be used to print
10380 summaries or perform other post-fixing work. The supported hooks are:
10381
10382 "postfixfile"
10383 Run once for each file in each revision where any fixer tools made changes
10384 to the file content. Provides "$HG_REV" and "$HG_PATH" to identify the file,
10385 and "$HG_METADATA" with a map of fixer names to metadata values from fixer
10386 tools that affected the file. Fixer tools that didn't affect the file have a
10387 value of None. Only fixer tools that executed are present in the metadata.
10388
10389 "postfix"
10390 Run once after all files and revisions have been handled. Provides
10391 "$HG_REPLACEMENTS" with information about what revisions were created and
10392 made obsolete. Provides a boolean "$HG_WDIRWRITTEN" to indicate whether any
10393 files in the working copy were updated. Provides a list "$HG_METADATA"
10394 mapping fixer tool names to lists of metadata values returned from
10395 executions that modified a file. This aggregates the same metadata
10396 previously passed to the "postfixfile" hook.
10397
10398 Fixer tools are run in the repository's root directory. This allows
10399 them to read configuration files from the working copy, or even write
10400 to the working copy. The working copy is not updated to match the re‐
10401 vision being fixed. In fact, several revisions may be fixed in paral‐
10402 lel. Writes to the working copy are not amended into the revision being
10403 fixed; fixer tools should always write fixed file content back to std‐
10404 out as documented above.
10405
10406 Commands
10407 File content management
10408 fix
10409 rewrite file content in changesets or working directory:
10410
10411 hg fix [OPTION]... [FILE]...
10412
10413 Runs any configured tools to fix the content of files. Only affects
10414 files with changes, unless file arguments are provided. Only affects
10415 changed lines of files, unless the --whole flag is used. Some tools may
10416 always affect the whole file regardless of --whole.
10417
10418 If --working-dir is used, files with uncommitted changes in the working
10419 copy will be fixed. Note that no backup are made.
10420
10421 If revisions are specified with --source, those revisions and their de‐
10422 scendants will be checked, and they may be replaced with new revisions
10423 that have fixed file content. By automatically including the descen‐
10424 dants, no merging, rebasing, or evolution will be required. If an an‐
10425 cestor of the working copy is included, then the working copy itself
10426 will also be fixed, and the working copy will be updated to the fixed
10427 parent.
10428
10429 When determining what lines of each file to fix at each revision, the
10430 whole set of revisions being fixed is considered, so that fixes to ear‐
10431 lier revisions are not forgotten in later ones. The --base flag can be
10432 used to override this default behavior, though it is not usually desir‐
10433 able to do so.
10434
10435 Options:
10436
10437 --all fix all non-public non-obsolete revisions
10438
10439 --base <REV[+]>
10440 revisions to diff against (overrides automatic selection, and
10441 applies to every revision being fixed)
10442
10443 -r,--rev <REV[+]>
10444 revisions to fix (ADVANCED)
10445
10446 -s,--source <REV[+]>
10447 fix the specified revisions and their descendants
10448
10449 -w, --working-dir
10450 fix the working directory
10451
10452 --whole
10453 always fix every line of a file
10454
10455 [+] marked option can be specified multiple times
10456
10457 fsmonitor
10458 Faster status operations with the Watchman file monitor (EXPERIMENTAL)
10459
10460 Integrates the file-watching program Watchman with Mercurial to produce
10461 faster status results.
10462
10463 On a particular Linux system, for a real-world repository with over
10464 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On
10465 the same system, with fsmonitor it takes about 0.3 seconds.
10466
10467 fsmonitor requires no configuration -- it will tell Watchman about your
10468 repository as necessary. You'll need to install Watchman from
10469 https://facebook.github.io/watchman/ and make sure it is in your PATH.
10470
10471 fsmonitor is incompatible with the largefiles and eol extensions, and
10472 will disable itself if any of those are active.
10473
10474 The following configuration options exist:
10475
10476 [fsmonitor]
10477 mode = {off, on, paranoid}
10478
10479 When mode = off, fsmonitor will disable itself (similar to not loading
10480 the extension at all). When mode = on, fsmonitor will be enabled (the
10481 default). When mode = paranoid, fsmonitor will query both Watchman and
10482 the filesystem, and ensure that the results are consistent.
10483
10484 [fsmonitor]
10485 timeout = (float)
10486
10487 A value, in seconds, that determines how long fsmonitor will wait for
10488 Watchman to return results. Defaults to 2.0.
10489
10490 [fsmonitor]
10491 blacklistusers = (list of userids)
10492
10493 A list of usernames for which fsmonitor will disable itself altogether.
10494
10495 [fsmonitor]
10496 walk_on_invalidate = (boolean)
10497
10498 Whether or not to walk the whole repo ourselves when our cached state
10499 has been invalidated, for example when Watchman has been restarted or
10500 .hgignore rules have been changed. Walking the repo in that case can
10501 result in competing for I/O with Watchman. For large repos it is recom‐
10502 mended to set this value to false. You may wish to set this to true if
10503 you have a very fast filesystem that can outpace the IPC overhead of
10504 getting the result data for the full repo from Watchman. Defaults to
10505 false.
10506
10507 [fsmonitor]
10508 warn_when_unused = (boolean)
10509
10510 Whether to print a warning during certain operations when fsmonitor
10511 would be beneficial to performance but isn't enabled.
10512
10513 [fsmonitor]
10514 warn_update_file_count = (integer)
10515 # or when mercurial is built with rust support
10516 warn_update_file_count_rust = (integer)
10517
10518 If warn_when_unused is set and fsmonitor isn't enabled, a warning will
10519 be printed during working directory updates if this many files will be
10520 created.
10521
10522 git
10523 grant Mercurial the ability to operate on Git repositories. (EXPERIMEN‐
10524 TAL)
10525
10526 This is currently super experimental. It probably will consume your
10527 firstborn a la Rumpelstiltskin, etc.
10528
10529 githelp
10530 try mapping git commands to Mercurial commands
10531
10532 Tries to map a given git command to a Mercurial command:
10533
10534 $ hg githelp -- git checkout master hg update master
10535
10536 If an unknown command or parameter combination is detected, an error is
10537 produced.
10538
10539 Commands
10540 Help
10541 githelp
10542 suggests the Mercurial equivalent of the given git command:
10543
10544 hg githelp
10545
10546 Usage: hg githelp -- <git command>
10547
10548 aliases: git
10549
10550 gpg
10551 commands to sign and verify changesets
10552
10553 Commands
10554 Signing changes (GPG)
10555 sigcheck
10556 verify all the signatures there may be for a particular revision:
10557
10558 hg sigcheck REV
10559
10560 verify all the signatures there may be for a particular revision
10561
10562 sign
10563 add a signature for the current or given revision:
10564
10565 hg sign [OPTION]... [REV]...
10566
10567 If no revision is given, the parent of the working directory is used,
10568 or tip if no revision is checked out.
10569
10570 The gpg.cmd config setting can be used to specify the command to run. A
10571 default key can be specified with gpg.key.
10572
10573 See hg help dates for a list of formats valid for -d/--date.
10574
10575 Options:
10576
10577 -l, --local
10578 make the signature local
10579
10580 -f, --force
10581 sign even if the sigfile is modified
10582
10583 --no-commit
10584 do not commit the sigfile after signing
10585
10586 -k,--key <ID>
10587 the key id to sign with
10588
10589 -m,--message <TEXT>
10590 use text as commit message
10591
10592 -e, --edit
10593 invoke editor on commit messages
10594
10595 -d,--date <DATE>
10596 record the specified date as commit date
10597
10598 -u,--user <USER>
10599 record the specified user as committer
10600
10601 sigs
10602 list signed changesets:
10603
10604 hg sigs
10605
10606 list signed changesets
10607
10608 graphlog
10609 command to view revision graphs from a shell (DEPRECATED)
10610
10611 The functionality of this extension has been include in core Mercurial
10612 since version 2.3. Please use hg log -G ... instead.
10613
10614 This extension adds a --graph option to the incoming, outgoing and log
10615 commands. When this options is given, an ASCII representation of the
10616 revision graph is also shown.
10617
10618 Commands
10619 Change navigation
10620 glog
10621 show revision history alongside an ASCII revision graph:
10622
10623 hg glog [OPTION]... [FILE]
10624
10625 Print a revision history alongside a revision graph drawn with ASCII
10626 characters.
10627
10628 Nodes printed as an @ character are parents of the working directory.
10629
10630 This is an alias to hg log -G.
10631
10632 Options:
10633
10634 -f, --follow
10635 follow changeset history, or file history across copies and re‐
10636 names
10637
10638 --follow-first
10639 only follow the first parent of merge changesets (DEPRECATED)
10640
10641 -d,--date <DATE>
10642 show revisions matching date spec
10643
10644 -C, --copies
10645 show copied files
10646
10647 -k,--keyword <TEXT[+]>
10648 do case-insensitive search for a given text
10649
10650 -r,--rev <REV[+]>
10651 show the specified revision or revset
10652
10653 --removed
10654 include revisions where files were removed
10655
10656 -m, --only-merges
10657 show only merges (DEPRECATED)
10658
10659 -u,--user <USER[+]>
10660 revisions committed by user
10661
10662 --only-branch <BRANCH[+]>
10663 show only changesets within the given named branch (DEPRECATED)
10664
10665 -b,--branch <BRANCH[+]>
10666 show changesets within the given named branch
10667
10668 -P,--prune <REV[+]>
10669 do not display revision or any of its ancestors
10670
10671 -p, --patch
10672 show patch
10673
10674 -g, --git
10675 use git extended diff format
10676
10677 -l,--limit <NUM>
10678 limit number of changes displayed
10679
10680 -M, --no-merges
10681 do not show merges
10682
10683 --stat output diffstat-style summary of changes
10684
10685 -G, --graph
10686 show the revision DAG
10687
10688 --style <STYLE>
10689 display using template map file (DEPRECATED)
10690
10691 -T,--template <TEMPLATE>
10692 display with template
10693
10694 -I,--include <PATTERN[+]>
10695 include names matching the given patterns
10696
10697 -X,--exclude <PATTERN[+]>
10698 exclude names matching the given patterns
10699
10700 [+] marked option can be specified multiple times
10701
10702 hgk
10703 browse the repository in a graphical way
10704
10705 The hgk extension allows browsing the history of a repository in a
10706 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
10707 distributed with Mercurial.)
10708
10709 hgk consists of two parts: a Tcl script that does the displaying and
10710 querying of information, and an extension to Mercurial named hgk.py,
10711 which provides hooks for hgk to get information. hgk can be found in
10712 the contrib directory, and the extension is shipped in the hgext repos‐
10713 itory, and needs to be enabled.
10714
10715 The hg view command will launch the hgk Tcl script. For this command to
10716 work, hgk must be in your search path. Alternately, you can specify the
10717 path to hgk in your configuration file:
10718
10719 [hgk]
10720 path = /location/of/hgk
10721
10722 hgk can make use of the extdiff extension to visualize revisions. As‐
10723 suming you had already configured extdiff vdiff command, just add:
10724
10725 [hgk]
10726 vdiff=vdiff
10727
10728 Revisions context menu will now display additional entries to fire vd‐
10729 iff on hovered and selected revisions.
10730
10731 Commands
10732 Change navigation
10733 view
10734 start interactive history viewer:
10735
10736 hg view [-l LIMIT] [REVRANGE]
10737
10738 start interactive history viewer
10739
10740 Options:
10741
10742 -l,--limit <NUM>
10743 limit number of changes displayed
10744
10745 Uncategorized commands
10746 highlight
10747 syntax highlighting for hgweb (requires Pygments)
10748
10749 It depends on the Pygments syntax highlighting library:
10750 http://pygments.org/
10751
10752 There are the following configuration options:
10753
10754 [web]
10755 pygments_style = <style> (default: colorful)
10756 highlightfiles = <fileset> (default: size('<5M'))
10757 highlightonlymatchfilename = <bool> (default False)
10758
10759 highlightonlymatchfilename will only highlight files if their type
10760 could be identified by their filename. When this is not enabled (the
10761 default), Pygments will try very hard to identify the file type from
10762 content and any match (even matches with a low confidence score) will
10763 be used.
10764
10765 histedit
10766 interactive history editing
10767
10768 With this extension installed, Mercurial gains one new command: histe‐
10769 dit. Usage is as follows, assuming the following history:
10770
10771 @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
10772 | Add delta
10773 |
10774 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
10775 | Add gamma
10776 |
10777 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
10778 | Add beta
10779 |
10780 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10781 Add alpha
10782
10783 If you were to run hg histedit c561b4e977df, you would see the follow‐
10784 ing file open in your editor:
10785
10786 pick c561b4e977df Add beta
10787 pick 030b686bedc4 Add gamma
10788 pick 7c2fd3b9020c Add delta
10789
10790 # Edit history between c561b4e977df and 7c2fd3b9020c
10791 #
10792 # Commits are listed from least to most recent
10793 #
10794 # Commands:
10795 # p, pick = use commit
10796 # e, edit = use commit, but allow edits before making new commit
10797 # f, fold = use commit, but combine it with the one above
10798 # r, roll = like fold, but discard this commit's description and date
10799 # d, drop = remove commit from history
10800 # m, mess = edit commit message without changing commit content
10801 # b, base = checkout changeset and apply further changesets from there
10802 #
10803
10804 In this file, lines beginning with # are ignored. You must specify a
10805 rule for each revision in your history. For example, if you had meant
10806 to add gamma before beta, and then wanted to add delta in the same re‐
10807 vision as beta, you would reorganize the file to look like this:
10808
10809 pick 030b686bedc4 Add gamma
10810 pick c561b4e977df Add beta
10811 fold 7c2fd3b9020c Add delta
10812
10813 # Edit history between c561b4e977df and 7c2fd3b9020c
10814 #
10815 # Commits are listed from least to most recent
10816 #
10817 # Commands:
10818 # p, pick = use commit
10819 # e, edit = use commit, but allow edits before making new commit
10820 # f, fold = use commit, but combine it with the one above
10821 # r, roll = like fold, but discard this commit's description and date
10822 # d, drop = remove commit from history
10823 # m, mess = edit commit message without changing commit content
10824 # b, base = checkout changeset and apply further changesets from there
10825 #
10826
10827 At which point you close the editor and histedit starts working. When
10828 you specify a fold operation, histedit will open an editor when it
10829 folds those revisions together, offering you a chance to clean up the
10830 commit message:
10831
10832 Add beta
10833 ***
10834 Add delta
10835
10836 Edit the commit message to your liking, then close the editor. The date
10837 used for the commit will be the later of the two commits' dates. For
10838 this example, let's assume that the commit message was changed to Add
10839 beta and delta. After histedit has run and had a chance to remove any
10840 old or temporary revisions it needed, the history looks like this:
10841
10842 @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
10843 | Add beta and delta.
10844 |
10845 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10846 | Add gamma
10847 |
10848 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10849 Add alpha
10850
10851 Note that histedit does not remove any revisions (even its own tempo‐
10852 rary ones) until after it has completed all the editing operations, so
10853 it will probably perform several strip operations when it's done. For
10854 the above example, it had to run strip twice. Strip can be slow depend‐
10855 ing on a variety of factors, so you might need to be a little patient.
10856 You can choose to keep the original revisions by passing the --keep
10857 flag.
10858
10859 The edit operation will drop you back to a command prompt, allowing you
10860 to edit files freely, or even use hg record to commit some changes as a
10861 separate commit. When you're done, any remaining uncommitted changes
10862 will be committed as well. When done, run hg histedit --continue to
10863 finish this step. If there are uncommitted changes, you'll be prompted
10864 for a new commit message, but the default commit message will be the
10865 original message for the edit ed revision, and the date of the original
10866 commit will be preserved.
10867
10868 The message operation will give you a chance to revise a commit message
10869 without changing the contents. It's a shortcut for doing edit immedi‐
10870 ately followed by hg histedit --continue`.
10871
10872 If histedit encounters a conflict when moving a revision (while han‐
10873 dling pick or fold), it'll stop in a similar manner to edit with the
10874 difference that it won't prompt you for a commit message when done. If
10875 you decide at this point that you don't like how much work it will be
10876 to rearrange history, or that you made a mistake, you can use hg histe‐
10877 dit --abort to abandon the new changes you have made and return to the
10878 state before you attempted to edit your history.
10879
10880 If we clone the histedit-ed example repository above and add four more
10881 changes, such that we have the following history:
10882
10883 @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
10884 | Add theta
10885 |
10886 o 5 140988835471 2009-04-27 18:04 -0500 stefan
10887 | Add eta
10888 |
10889 o 4 122930637314 2009-04-27 18:04 -0500 stefan
10890 | Add zeta
10891 |
10892 o 3 836302820282 2009-04-27 18:04 -0500 stefan
10893 | Add epsilon
10894 |
10895 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
10896 | Add beta and delta.
10897 |
10898 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
10899 | Add gamma
10900 |
10901 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
10902 Add alpha
10903
10904 If you run hg histedit --outgoing on the clone then it is the same as
10905 running hg histedit 836302820282. If you need plan to push to a reposi‐
10906 tory that Mercurial does not detect to be related to the source repo,
10907 you can add a --force option.
10908
10909 Config
10910 Histedit rule lines are truncated to 80 characters by default. You can
10911 customize this behavior by setting a different length in your configu‐
10912 ration file:
10913
10914 [histedit]
10915 linelen = 120 # truncate rule lines at 120 characters
10916
10917 The summary of a change can be customized as well:
10918
10919 [histedit]
10920 summary-template = '{rev} {bookmarks} {desc|firstline}'
10921
10922 The customized summary should be kept short enough that rule lines will
10923 fit in the configured line length. See above if that requires cus‐
10924 tomization.
10925
10926 hg histedit attempts to automatically choose an appropriate base revi‐
10927 sion to use. To change which base revision is used, define a revset in
10928 your configuration file:
10929
10930 [histedit]
10931 defaultrev = only(.) & draft()
10932
10933 By default each edited revision needs to be present in histedit com‐
10934 mands. To remove revision you need to use drop operation. You can con‐
10935 figure the drop to be implicit for missing commits by adding:
10936
10937 [histedit]
10938 dropmissing = True
10939
10940 By default, histedit will close the transaction after each action. For
10941 performance purposes, you can configure histedit to use a single trans‐
10942 action across the entire histedit. WARNING: This setting introduces a
10943 significant risk of losing the work you've done in a histedit if the
10944 histedit aborts unexpectedly:
10945
10946 [histedit]
10947 singletransaction = True
10948
10949 Commands
10950 Change manipulation
10951 histedit
10952 interactively edit changeset history:
10953
10954 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
10955
10956 This command lets you edit a linear series of changesets (up to and in‐
10957 cluding the working directory, which should be clean). You can:
10958
10959 • pick to [re]order a changeset
10960
10961 • drop to omit changeset
10962
10963 • mess to reword the changeset commit message
10964
10965 • fold to combine it with the preceding changeset (using the later
10966 date)
10967
10968 • roll like fold, but discarding this commit's description and date
10969
10970 • edit to edit this changeset (preserving date)
10971
10972 • base to checkout changeset and apply further changesets from there
10973
10974 There are a number of ways to select the root changeset:
10975
10976 • Specify ANCESTOR directly
10977
10978 • Use --outgoing -- it will be the first linear changeset not included
10979 in destination. (See hg help config.paths.default-push)
10980
10981 • Otherwise, the value from the "histedit.defaultrev" config option is
10982 used as a revset to select the base revision when ANCESTOR is not
10983 specified. The first revision returned by the revset is used. By de‐
10984 fault, this selects the editable history that is unique to the ances‐
10985 try of the working directory.
10986
10987 If you use --outgoing, this command will abort if there are ambiguous
10988 outgoing revisions. For example, if there are multiple branches con‐
10989 taining outgoing revisions.
10990
10991 Use "min(outgoing() and ::.)" or similar revset specification instead
10992 of --outgoing to specify edit target revision exactly in such ambiguous
10993 situation. See hg help revsets for detail about selecting revisions.
10994
10995 Examples:
10996
10997 • A number of changes have been made. Revision 3 is no longer
10998 needed.
10999
11000 Start history editing from revision 3:
11001
11002 hg histedit -r 3
11003
11004 An editor opens, containing the list of revisions, with specific
11005 actions specified:
11006
11007 pick 5339bf82f0ca 3 Zworgle the foobar
11008 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11009 pick 0a9639fcda9d 5 Morgify the cromulancy
11010
11011 Additional information about the possible actions to take appears
11012 below the list of revisions.
11013
11014 To remove revision 3 from the history, its action (at the begin‐
11015 ning of the relevant line) is changed to 'drop':
11016
11017 drop 5339bf82f0ca 3 Zworgle the foobar
11018 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11019 pick 0a9639fcda9d 5 Morgify the cromulancy
11020
11021 • A number of changes have been made. Revision 2 and 4 need to be
11022 swapped.
11023
11024 Start history editing from revision 2:
11025
11026 hg histedit -r 2
11027
11028 An editor opens, containing the list of revisions, with specific
11029 actions specified:
11030
11031 pick 252a1af424ad 2 Blorb a morgwazzle
11032 pick 5339bf82f0ca 3 Zworgle the foobar
11033 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11034
11035 To swap revision 2 and 4, its lines are swapped in the editor:
11036
11037 pick 8ef592ce7cc4 4 Bedazzle the zerlog
11038 pick 5339bf82f0ca 3 Zworgle the foobar
11039 pick 252a1af424ad 2 Blorb a morgwazzle
11040
11041 Returns 0 on success, 1 if user intervention is required (not only for
11042 intentional "edit" command, but also for resolving unexpected con‐
11043 flicts).
11044
11045 Options:
11046
11047 --commands <FILE>
11048 read history edits from the specified file
11049
11050 -c, --continue
11051 continue an edit already in progress
11052
11053 --edit-plan
11054 edit remaining actions list
11055
11056 -k, --keep
11057 don't strip old nodes after edit is complete
11058
11059 --abort
11060 abort an edit in progress
11061
11062 -o, --outgoing
11063 changesets not found in destination
11064
11065 -f, --force
11066 force outgoing even for unrelated repositories
11067
11068 -r,--rev <REV[+]>
11069 first revision to be edited
11070
11071 -T,--template <TEMPLATE>
11072 display with template
11073
11074 [+] marked option can be specified multiple times
11075
11076 hooklib
11077 collection of simple hooks for common tasks (EXPERIMENTAL)
11078
11079 This extension provides a number of simple hooks to handle issues com‐
11080 monly found in repositories with many contributors: - email notifica‐
11081 tion when changesets move from draft to public phase - email notifica‐
11082 tion when changesets are obsoleted - enforcement of draft phase for all
11083 incoming changesets - enforcement of a no-branch-merge policy - en‐
11084 forcement of a no-multiple-heads policy
11085
11086 The implementation of the hooks is subject to change, e.g. whether to
11087 implement them as individual hooks or merge them into the notify exten‐
11088 sion as option. The functionality itself is planned to be supported
11089 long-term.
11090
11091 infinitepush
11092 store some pushes in a remote blob store on the server (EXPERIMEN‐
11093 TAL)
11094
11095 IMPORTANT: if you use this extension, please contact
11096 mercurial-devel@mercurial-scm.org ASAP. This extension is believed to
11097 be unused and barring learning of users of this functionality, we will
11098 delete this code at the end of 2020.
11099
11100 [infinitepush] # Server-side and client-side option. Pattern of the
11101 infinitepush bookmark branchpattern = PATTERN
11102
11103 # Server or client server = False
11104
11105 # Server-side option. Possible values: 'disk' or 'sql'. Fails if not
11106 set indextype = disk
11107
11108 # Server-side option. Used only if indextype=sql. # Format:
11109 'IP:PORT:DB_NAME:USER:PASSWORD' sqlhost = IP:PORT:DB_NAME:USER:PASS‐
11110 WORD
11111
11112 # Server-side option. Used only if indextype=disk. # Filesystem
11113 path to the index store indexpath = PATH
11114
11115 # Server-side option. Possible values: 'disk' or 'external' # Fails
11116 if not set storetype = disk
11117
11118 # Server-side option. # Path to the binary that will save bundle to
11119 the bundlestore # Formatted cmd line will be passed to it (see
11120 put_args) put_binary = put
11121
11122 # Serser-side option. Used only if storetype=external. # Format
11123 cmd-line string for put binary. Placeholder: {filename} put_args =
11124 {filename}
11125
11126 # Server-side option. # Path to the binary that get bundle from the
11127 bundlestore. # Formatted cmd line will be passed to it (see
11128 get_args) get_binary = get
11129
11130 # Serser-side option. Used only if storetype=external. # Format
11131 cmd-line string for get binary. Placeholders: {filename} {handle}
11132 get_args = {filename} {handle}
11133
11134 # Server-side option logfile = FIlE
11135
11136 # Server-side option loglevel = DEBUG
11137
11138 # Server-side option. Used only if indextype=sql. # Sets mysql
11139 wait_timeout option. waittimeout = 300
11140
11141 # Server-side option. Used only if indextype=sql. # Sets mysql inn‐
11142 odb_lock_wait_timeout option. locktimeout = 120
11143
11144 # Server-side option. Used only if indextype=sql. # Name of the
11145 repository reponame = ''
11146
11147 # Client-side option. Used by --list-remote option. List of remote
11148 scratch # patterns to list if no patterns are specified. default‐
11149 remotepatterns = ['*']
11150
11151 # Instructs infinitepush to forward all received bundle2 parts to
11152 the # bundle for storage. Defaults to False. storeallparts = True
11153
11154 # routes each incoming push to the bundlestore. defaults to False
11155 pushtobundlestore = True
11156
11157 [remotenames] # Client-side option # This option should be set only
11158 if remotenames extension is enabled. # Whether remote bookmarks are
11159 tracked by remotenames extension. bookmarks = True
11160
11161 journal
11162 track previous positions of bookmarks (EXPERIMENTAL)
11163
11164 This extension adds a new command: hg journal, which shows you where
11165 bookmarks were previously located.
11166
11167 Commands
11168 Change organization
11169 journal
11170 show the previous position of bookmarks and the working copy:
11171
11172 hg journal [OPTION]... [BOOKMARKNAME]
11173
11174 The journal is used to see the previous commits that bookmarks and the
11175 working copy pointed to. By default the previous locations for the
11176 working copy. Passing a bookmark name will show all the previous posi‐
11177 tions of that bookmark. Use the --all switch to show previous locations
11178 for all bookmarks and the working copy; each line will then include the
11179 bookmark name, or '.' for the working copy, as well.
11180
11181 If name starts with re:, the remainder of the name is treated as a reg‐
11182 ular expression. To match a name that actually starts with re:, use the
11183 prefix literal:.
11184
11185 By default hg journal only shows the commit hash and the command that
11186 was running at that time. -v/--verbose will show the prior hash, the
11187 user, and the time at which it happened.
11188
11189 Use -c/--commits to output log information on each commit hash; at this
11190 point you can use the usual --patch, --git, --stat and --template
11191 switches to alter the log output for these.
11192
11193 hg journal -T json can be used to produce machine readable output.
11194
11195 Options:
11196
11197 --all show history for all names
11198
11199 -c, --commits
11200 show commit metadata
11201
11202 -p, --patch
11203 show patch
11204
11205 -g, --git
11206 use git extended diff format
11207
11208 -l,--limit <NUM>
11209 limit number of changes displayed
11210
11211 --stat output diffstat-style summary of changes
11212
11213 --style <STYLE>
11214 display using template map file (DEPRECATED)
11215
11216 -T,--template <TEMPLATE>
11217 display with template
11218
11219 keyword
11220 expand keywords in tracked files
11221
11222 This extension expands RCS/CVS-like or self-customized $Keywords$ in
11223 tracked text files selected by your configuration.
11224
11225 Keywords are only expanded in local repositories and not stored in the
11226 change history. The mechanism can be regarded as a convenience for the
11227 current user or for archive distribution.
11228
11229 Keywords expand to the changeset data pertaining to the latest change
11230 relative to the working directory parent of each file.
11231
11232 Configuration is done in the [keyword], [keywordset] and [keywordmaps]
11233 sections of hgrc files.
11234
11235 Example:
11236
11237 [keyword]
11238 # expand keywords in every python file except those matching "x*"
11239 **.py =
11240 x* = ignore
11241
11242 [keywordset]
11243 # prefer svn- over cvs-like default keywordmaps
11244 svn = True
11245
11246 Note The more specific you are in your filename patterns the less you
11247 lose speed in huge repositories.
11248
11249 For [keywordmaps] template mapping and expansion demonstration and con‐
11250 trol run hg kwdemo. See hg help templates for a list of available tem‐
11251 plates and filters.
11252
11253 Three additional date template filters are provided:
11254
11255 utcdate
11256
11257 "2006/09/18 15:13:13"
11258
11259 svnutcdate
11260
11261 "2006-09-18 15:13:13Z"
11262
11263 svnisodate
11264
11265 "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"
11266
11267 The default template mappings (view with hg kwdemo -d) can be replaced
11268 with customized keywords and templates. Again, run hg kwdemo to control
11269 the results of your configuration changes.
11270
11271 Before changing/disabling active keywords, you must run hg kwshrink to
11272 avoid storing expanded keywords in the change history.
11273
11274 To force expansion after enabling it, or a configuration change, run hg
11275 kwexpand.
11276
11277 Expansions spanning more than one line and incremental expansions, like
11278 CVS' $Log$, are not supported. A keyword template map "Log = {desc}"
11279 expands to the first line of the changeset description.
11280
11281 Commands
11282 Uncategorized commands
11283 kwdemo
11284 print [keywordmaps] configuration and an expansion example:
11285
11286 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
11287
11288 Show current, custom, or default keyword template maps and their expan‐
11289 sions.
11290
11291 Extend the current configuration by specifying maps as arguments and
11292 using -f/--rcfile to source an external hgrc file.
11293
11294 Use -d/--default to disable current configuration.
11295
11296 See hg help templates for information on templates and filters.
11297
11298 Options:
11299
11300 -d, --default
11301 show default keyword template maps
11302
11303 -f,--rcfile <FILE>
11304 read maps from rcfile
11305
11306 kwexpand
11307 expand keywords in the working directory:
11308
11309 hg kwexpand [OPTION]... [FILE]...
11310
11311 Run after (re)enabling keyword expansion.
11312
11313 kwexpand refuses to run if given files contain local changes.
11314
11315 Options:
11316
11317 -I,--include <PATTERN[+]>
11318 include names matching the given patterns
11319
11320 -X,--exclude <PATTERN[+]>
11321 exclude names matching the given patterns
11322
11323 [+] marked option can be specified multiple times
11324
11325 kwfiles
11326 show files configured for keyword expansion:
11327
11328 hg kwfiles [OPTION]... [FILE]...
11329
11330 List which files in the working directory are matched by the [keyword]
11331 configuration patterns.
11332
11333 Useful to prevent inadvertent keyword expansion and to speed up execu‐
11334 tion by including only files that are actual candidates for expansion.
11335
11336 See hg help keyword on how to construct patterns both for inclusion and
11337 exclusion of files.
11338
11339 With -A/--all and -v/--verbose the codes used to show the status of
11340 files are:
11341
11342 K = keyword expansion candidate
11343 k = keyword expansion candidate (not tracked)
11344 I = ignored
11345 i = ignored (not tracked)
11346
11347 Options:
11348
11349 -A, --all
11350 show keyword status flags of all files
11351
11352 -i, --ignore
11353 show files excluded from expansion
11354
11355 -u, --unknown
11356 only show unknown (not tracked) files
11357
11358 -I,--include <PATTERN[+]>
11359 include names matching the given patterns
11360
11361 -X,--exclude <PATTERN[+]>
11362 exclude names matching the given patterns
11363
11364 [+] marked option can be specified multiple times
11365
11366 kwshrink
11367 revert expanded keywords in the working directory:
11368
11369 hg kwshrink [OPTION]... [FILE]...
11370
11371 Must be run before changing/disabling active keywords.
11372
11373 kwshrink refuses to run if given files contain local changes.
11374
11375 Options:
11376
11377 -I,--include <PATTERN[+]>
11378 include names matching the given patterns
11379
11380 -X,--exclude <PATTERN[+]>
11381 exclude names matching the given patterns
11382
11383 [+] marked option can be specified multiple times
11384
11385 largefiles
11386 track large binary files
11387
11388 Large binary files tend to be not very compressible, not very diffable,
11389 and not at all mergeable. Such files are not handled efficiently by
11390 Mercurial's storage format (revlog), which is based on compressed bi‐
11391 nary deltas; storing large binary files as regular Mercurial files
11392 wastes bandwidth and disk space and increases Mercurial's memory usage.
11393 The largefiles extension addresses these problems by adding a central‐
11394 ized client-server layer on top of Mercurial: largefiles live in a cen‐
11395 tral store out on the network somewhere, and you only fetch the revi‐
11396 sions that you need when you need them.
11397
11398 largefiles works by maintaining a "standin file" in .hglf/ for each
11399 largefile. The standins are small (41 bytes: an SHA-1 hash plus new‐
11400 line) and are tracked by Mercurial. Largefile revisions are identified
11401 by the SHA-1 hash of their contents, which is written to the standin.
11402 largefiles uses that revision ID to get/put largefile revisions from/to
11403 the central store. This saves both disk space and bandwidth, since you
11404 don't need to retrieve all historical revisions of large files when you
11405 clone or pull.
11406
11407 To start a new repository or add new large binary files, just add
11408 --large to your hg add command. For example:
11409
11410 $ dd if=/dev/urandom of=randomdata count=2000
11411 $ hg add --large randomdata
11412 $ hg commit -m "add randomdata as a largefile"
11413
11414 When you push a changeset that adds/modifies largefiles to a remote
11415 repository, its largefile revisions will be uploaded along with it.
11416 Note that the remote Mercurial must also have the largefiles extension
11417 enabled for this to work.
11418
11419 When you pull a changeset that affects largefiles from a remote reposi‐
11420 tory, the largefiles for the changeset will by default not be pulled
11421 down. However, when you update to such a revision, any largefiles
11422 needed by that revision are downloaded and cached (if they have never
11423 been downloaded before). One way to pull largefiles when pulling is
11424 thus to use --update, which will update your working copy to the latest
11425 pulled revision (and thereby downloading any new largefiles).
11426
11427 If you want to pull largefiles you don't need for update yet, then you
11428 can use pull with the --lfrev option or the hg lfpull command.
11429
11430 If you know you are pulling from a non-default location and want to
11431 download all the largefiles that correspond to the new changesets at
11432 the same time, then you can pull with --lfrev "pulled()".
11433
11434 If you just want to ensure that you will have the largefiles needed to
11435 merge or rebase with new heads that you are pulling, then you can pull
11436 with --lfrev "head(pulled())" flag to pre-emptively download any large‐
11437 files that are new in the heads you are pulling.
11438
11439 Keep in mind that network access may now be required to update to
11440 changesets that you have not previously updated to. The nature of the
11441 largefiles extension means that updating is no longer guaranteed to be
11442 a local-only operation.
11443
11444 If you already have large files tracked by Mercurial without the large‐
11445 files extension, you will need to convert your repository in order to
11446 benefit from largefiles. This is done with the hg lfconvert command:
11447
11448 $ hg lfconvert --size 10 oldrepo newrepo
11449
11450 In repositories that already have largefiles in them, any new file over
11451 10MB will automatically be added as a largefile. To change this thresh‐
11452 old, set largefiles.minsize in your Mercurial config file to the mini‐
11453 mum size in megabytes to track as a largefile, or use the --lfsize op‐
11454 tion to the add command (also in megabytes):
11455
11456 [largefiles]
11457 minsize = 2
11458
11459 $ hg add --lfsize 2
11460
11461 The largefiles.patterns config option allows you to specify a list of
11462 filename patterns (see hg help patterns) that should always be tracked
11463 as largefiles:
11464
11465 [largefiles]
11466 patterns =
11467 *.jpg
11468 re:.*\.(png|bmp)$
11469 library.zip
11470 content/audio/*
11471
11472 Files that match one of these patterns will be added as largefiles re‐
11473 gardless of their size.
11474
11475 The largefiles.minsize and largefiles.patterns config options will be
11476 ignored for any repositories not already containing a largefile. To add
11477 the first largefile to a repository, you must explicitly do so with the
11478 --large flag passed to the hg add command.
11479
11480 Commands
11481 Uncategorized commands
11482 lfconvert
11483 convert a normal repository to a largefiles repository:
11484
11485 hg lfconvert SOURCE DEST [FILE ...]
11486
11487 Convert repository SOURCE to a new repository DEST, identical to SOURCE
11488 except that certain files will be converted as largefiles: specifi‐
11489 cally, any file that matches any PATTERN or whose size is above the
11490 minimum size threshold is converted as a largefile. The size used to
11491 determine whether or not to track a file as a largefile is the size of
11492 the first version of the file. The minimum size can be specified either
11493 with --size or in configuration as largefiles.size.
11494
11495 After running this command you will need to make sure that largefiles
11496 is enabled anywhere you intend to push the new repository.
11497
11498 Use --to-normal to convert largefiles back to normal files; after this,
11499 the DEST repository can be used without largefiles at all.
11500
11501 Options:
11502
11503 -s,--size <SIZE>
11504 minimum size (MB) for files to be converted as largefiles
11505
11506 --to-normal
11507 convert from a largefiles repo to a normal repo
11508
11509 lfpull
11510 pull largefiles for the specified revisions from the specified source:
11511
11512 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
11513
11514 Pull largefiles that are referenced from local changesets but missing
11515 locally, pulling from a remote repository to the local cache.
11516
11517 If SOURCE is omitted, the 'default' path will be used. See hg help
11518 urls for more information.
11519
11520 Some examples:
11521
11522 • pull largefiles for all branch heads:
11523
11524 hg lfpull -r "head() and not closed()"
11525
11526 • pull largefiles on the default branch:
11527
11528 hg lfpull -r "branch(default)"
11529
11530 Options:
11531
11532 -r,--rev <VALUE[+]>
11533 pull largefiles for these revisions
11534
11535 -e,--ssh <CMD>
11536 specify ssh command to use
11537
11538 --remotecmd <CMD>
11539 specify hg command to run on the remote side
11540
11541 --insecure
11542 do not verify server certificate (ignoring web.cacerts config)
11543
11544 [+] marked option can be specified multiple times
11545
11546 lfs
11547 lfs - large file support (EXPERIMENTAL)
11548
11549 This extension allows large files to be tracked outside of the normal
11550 repository storage and stored on a centralized server, similar to the
11551 largefiles extension. The git-lfs protocol is used when communicating
11552 with the server, so existing git infrastructure can be harnessed. Even
11553 though the files are stored outside of the repository, they are still
11554 integrity checked in the same manner as normal files.
11555
11556 The files stored outside of the repository are downloaded on demand,
11557 which reduces the time to clone, and possibly the local disk usage.
11558 This changes fundamental workflows in a DVCS, so careful thought should
11559 be given before deploying it. hg convert can be used to convert LFS
11560 repositories to normal repositories that no longer require this exten‐
11561 sion, and do so without changing the commit hashes. This allows the
11562 extension to be disabled if the centralized workflow becomes burden‐
11563 some. However, the pre and post convert clones will not be able to
11564 communicate with each other unless the extension is enabled on both.
11565
11566 To start a new repository, or to add LFS files to an existing one, just
11567 create an .hglfs file as described below in the root directory of the
11568 repository. Typically, this file should be put under version control,
11569 so that the settings will propagate to other repositories with push and
11570 pull. During any commit, Mercurial will consult this file to determine
11571 if an added or modified file should be stored externally. The type of
11572 storage depends on the characteristics of the file at each commit. A
11573 file that is near a size threshold may switch back and forth between
11574 LFS and normal storage, as needed.
11575
11576 Alternately, both normal repositories and largefile controlled reposi‐
11577 tories can be converted to LFS by using hg convert and the lfs.track
11578 config option described below. The .hglfs file should then be created
11579 and added, to control subsequent LFS selection. The hashes are also
11580 unchanged in this case. The LFS and non-LFS repositories can be dis‐
11581 tinguished because the LFS repository will abort any command if this
11582 extension is disabled.
11583
11584 Committed LFS files are held locally, until the repository is pushed.
11585 Prior to pushing the normal repository data, the LFS files that are
11586 tracked by the outgoing commits are automatically uploaded to the con‐
11587 figured central server. No LFS files are transferred on hg pull or hg
11588 clone. Instead, the files are downloaded on demand as they need to be
11589 read, if a cached copy cannot be found locally. Both committing and
11590 downloading an LFS file will link the file to a usercache, to speed up
11591 future access. See the usercache config setting described below.
11592
11593 The extension reads its configuration from a versioned .hglfs configu‐
11594 ration file found in the root of the working directory. The .hglfs file
11595 uses the same syntax as all other Mercurial configuration files. It
11596 uses a single section, [track].
11597
11598 The [track] section specifies which files are stored as LFS (or not).
11599 Each line is keyed by a file pattern, with a predicate value. The
11600 first file pattern match is used, so put more specific patterns first.
11601 The available predicates are all(), none(), and size(). See "hg help
11602 filesets.size" for the latter.
11603
11604 Example versioned .hglfs file:
11605
11606 [track]
11607 # No Makefile or python file, anywhere, will be LFS
11608 **Makefile = none()
11609 **.py = none()
11610
11611 **.zip = all()
11612 **.exe = size(">1MB")
11613
11614 # Catchall for everything not matched above
11615 ** = size(">10MB")
11616
11617 Configs:
11618
11619 [lfs]
11620 # Remote endpoint. Multiple protocols are supported:
11621 # - http(s)://user:pass@example.com/path
11622 # git-lfs endpoint
11623 # - file:///tmp/path
11624 # local filesystem, usually for testing
11625 # if unset, lfs will assume the remote repository also handles blob storage
11626 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
11627 # use this value.
11628 # (default: unset)
11629 url = https://example.com/repo.git/info/lfs
11630
11631 # Which files to track in LFS. Path tests are "**.extname" for file
11632 # extensions, and "path:under/some/directory" for path prefix. Both
11633 # are relative to the repository root.
11634 # File size can be tested with the "size()" fileset, and tests can be
11635 # joined with fileset operators. (See "hg help filesets.operators".)
11636 #
11637 # Some examples:
11638 # - all() # everything
11639 # - none() # nothing
11640 # - size(">20MB") # larger than 20MB
11641 # - !**.txt # anything not a *.txt file
11642 # - **.zip | **.tar.gz | **.7z # some types of compressed files
11643 # - path:bin # files under "bin" in the project root
11644 # - (**.php & size(">2MB")) | (**.js & size(">5MB")) | **.tar.gz
11645 # | (path:bin & !path:/bin/README) | size(">1GB")
11646 # (default: none())
11647 #
11648 # This is ignored if there is a tracked '.hglfs' file, and this setting
11649 # will eventually be deprecated and removed.
11650 track = size(">10M")
11651
11652 # how many times to retry before giving up on transferring an object
11653 retry = 5
11654
11655 # the local directory to store lfs files for sharing across local clones.
11656 # If not set, the cache is located in an OS specific cache location.
11657 usercache = /path/to/global/cache
11658
11659 Commands
11660 Uncategorized commands
11661 logtoprocess
11662 send ui.log() data to a subprocess (EXPERIMENTAL)
11663
11664 This extension lets you specify a shell command per ui.log() event,
11665 sending all remaining arguments to as environment variables to that
11666 command.
11667
11668 Positional arguments construct a log message, which is passed in the
11669 MSG1 environment variables. Each keyword argument is set as a OPT_UP‐
11670 PERCASE_KEY variable (so the key is uppercased, and prefixed with
11671 OPT_). The original event name is passed in the EVENT environment vari‐
11672 able, and the process ID of mercurial is given in HGPID.
11673
11674 So given a call ui.log('foo', 'bar %s ', 'baz', spam='eggs'), a script
11675 configured for the `foo event can expect an environment with MSG1=bar
11676 baz, and OPT_SPAM=eggs.
11677
11678 Scripts are configured in the [logtoprocess] section, each key an event
11679 name. For example:
11680
11681 [logtoprocess]
11682 commandexception = echo "$MSG1" > /var/log/mercurial_exceptions.log
11683
11684 would log the warning message and traceback of any failed command dis‐
11685 patch.
11686
11687 Scripts are run asynchronously as detached daemon processes; mercurial
11688 will not ensure that they exit cleanly.
11689
11690 mq
11691 manage a stack of patches
11692
11693 This extension lets you work with a stack of patches in a Mercurial
11694 repository. It manages two stacks of patches - all known patches, and
11695 applied patches (subset of known patches).
11696
11697 Known patches are represented as patch files in the .hg/patches direc‐
11698 tory. Applied patches are both patch files and changesets.
11699
11700 Common tasks (use hg help COMMAND for more details):
11701
11702 create new patch qnew
11703 import existing patch qimport
11704
11705 print patch series qseries
11706 print applied patches qapplied
11707
11708 add known patch to applied stack qpush
11709 remove patch from applied stack qpop
11710 refresh contents of top applied patch qrefresh
11711
11712 By default, mq will automatically use git patches when required to
11713 avoid losing file mode changes, copy records, binary files or empty
11714 files creations or deletions. This behavior can be configured with:
11715
11716 [mq]
11717 git = auto/keep/yes/no
11718
11719 If set to 'keep', mq will obey the [diff] section configuration while
11720 preserving existing git patches upon qrefresh. If set to 'yes' or 'no',
11721 mq will override the [diff] section and always generate git or regular
11722 patches, possibly losing data in the second case.
11723
11724 It may be desirable for mq changesets to be kept in the secret phase
11725 (see hg help phases), which can be enabled with the following setting:
11726
11727 [mq]
11728 secret = True
11729
11730 You will by default be managing a patch queue named "patches". You can
11731 create other, independent patch queues with the hg qqueue command.
11732
11733 If the working directory contains uncommitted files, qpush, qpop and
11734 qgoto abort immediately. If -f/--force is used, the changes are dis‐
11735 carded. Setting:
11736
11737 [mq]
11738 keepchanges = True
11739
11740 make them behave as if --keep-changes were passed, and non-conflicting
11741 local changes will be tolerated and preserved. If incompatible options
11742 such as -f/--force or --exact are passed, this setting is ignored.
11743
11744 This extension used to provide a strip command. This command now lives
11745 in the strip extension.
11746
11747 Commands
11748 Repository creation
11749 qclone
11750 clone main and patch repository at same time:
11751
11752 hg qclone [OPTION]... SOURCE [DEST]
11753
11754 If source is local, destination will have no patches applied. If source
11755 is remote, this command can not check if patches are applied in source,
11756 so cannot guarantee that patches are not applied in destination. If you
11757 clone remote repository, be sure before that it has no patches applied.
11758
11759 Source patch repository is looked for in <src>/.hg/patches by default.
11760 Use -p <url> to change.
11761
11762 The patch directory must be a nested Mercurial repository, as would be
11763 created by hg init --mq.
11764
11765 Return 0 on success.
11766
11767 Options:
11768
11769 --pull use pull protocol to copy metadata
11770
11771 -U, --noupdate
11772 do not update the new working directories
11773
11774 --uncompressed
11775 use uncompressed transfer (fast over LAN)
11776
11777 -p,--patches <REPO>
11778 location of source patch repository
11779
11780 -e,--ssh <CMD>
11781 specify ssh command to use
11782
11783 --remotecmd <CMD>
11784 specify hg command to run on the remote side
11785
11786 --insecure
11787 do not verify server certificate (ignoring web.cacerts config)
11788
11789 qinit
11790 init a new queue repository (DEPRECATED):
11791
11792 hg qinit [-c]
11793
11794 The queue repository is unversioned by default. If -c/--create-repo is
11795 specified, qinit will create a separate nested repository for patches
11796 (qinit -c may also be run later to convert an unversioned patch reposi‐
11797 tory into a versioned one). You can use qcommit to commit changes to
11798 this queue repository.
11799
11800 This command is deprecated. Without -c, it's implied by other relevant
11801 commands. With -c, use hg init --mq instead.
11802
11803 Options:
11804
11805 -c, --create-repo
11806 create queue repository
11807
11808 Change creation
11809 qcommit
11810 commit changes in the queue repository (DEPRECATED):
11811
11812 hg qcommit [OPTION]... [FILE]...
11813
11814 This command is deprecated; use hg commit --mq instead.
11815
11816 Options:
11817
11818 -A, --addremove
11819 mark new/missing files as added/removed before committing
11820
11821 --close-branch
11822 mark a branch head as closed
11823
11824 --amend
11825 amend the parent of the working directory
11826
11827 -s, --secret
11828 use the secret phase for committing
11829
11830 -e, --edit
11831 invoke editor on commit messages
11832
11833 --force-close-branch
11834 forcibly close branch from a non-head changeset (ADVANCED)
11835
11836 -i, --interactive
11837 use interactive mode
11838
11839 -I,--include <PATTERN[+]>
11840 include names matching the given patterns
11841
11842 -X,--exclude <PATTERN[+]>
11843 exclude names matching the given patterns
11844
11845 -m,--message <TEXT>
11846 use text as commit message
11847
11848 -l,--logfile <FILE>
11849 read commit message from file
11850
11851 -d,--date <DATE>
11852 record the specified date as commit date
11853
11854 -u,--user <USER>
11855 record the specified user as committer
11856
11857 -S, --subrepos
11858 recurse into subrepositories
11859
11860 [+] marked option can be specified multiple times
11861
11862 aliases: qci
11863
11864 qnew
11865 create a new patch:
11866
11867 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
11868
11869 qnew creates a new patch on top of the currently-applied patch (if
11870 any). The patch will be initialized with any outstanding changes in the
11871 working directory. You may also use -I/--include, -X/--exclude, and/or
11872 a list of files after the patch name to add only changes to matching
11873 files to the new patch, leaving the rest as uncommitted modifications.
11874
11875 -u/--user and -d/--date can be used to set the (given) user and date,
11876 respectively. -U/--currentuser and -D/--currentdate set user to current
11877 user and date to current date.
11878
11879 -e/--edit, -m/--message or -l/--logfile set the patch header as well as
11880 the commit message. If none is specified, the header is empty and the
11881 commit message is '[mq]: PATCH'.
11882
11883 Use the -g/--git option to keep the patch in the git extended diff for‐
11884 mat. Read the diffs help topic for more information on why this is im‐
11885 portant for preserving permission changes and copy/rename information.
11886
11887 Returns 0 on successful creation of a new patch.
11888
11889 Options:
11890
11891 -e, --edit
11892 invoke editor on commit messages
11893
11894 -f, --force
11895 import uncommitted changes (DEPRECATED)
11896
11897 -g, --git
11898 use git extended diff format
11899
11900 -U, --currentuser
11901 add "From: <current user>" to patch
11902
11903 -u,--user <USER>
11904 add "From: <USER>" to patch
11905
11906 -D, --currentdate
11907 add "Date: <current date>" to patch
11908
11909 -d,--date <DATE>
11910 add "Date: <DATE>" to patch
11911
11912 -I,--include <PATTERN[+]>
11913 include names matching the given patterns
11914
11915 -X,--exclude <PATTERN[+]>
11916 exclude names matching the given patterns
11917
11918 -m,--message <TEXT>
11919 use text as commit message
11920
11921 -l,--logfile <FILE>
11922 read commit message from file
11923
11924 [+] marked option can be specified multiple times
11925
11926 qrefresh
11927 update the current patch:
11928
11929 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
11930
11931 If any file patterns are provided, the refreshed patch will contain
11932 only the modifications that match those patterns; the remaining modifi‐
11933 cations will remain in the working directory.
11934
11935 If -s/--short is specified, files currently included in the patch will
11936 be refreshed just like matched files and remain in the patch.
11937
11938 If -e/--edit is specified, Mercurial will start your configured editor
11939 for you to enter a message. In case qrefresh fails, you will find a
11940 backup of your message in .hg/last-message.txt.
11941
11942 hg add/remove/copy/rename work as usual, though you might want to use
11943 git-style patches (-g/--git or [diff] git=1) to track copies and re‐
11944 names. See the diffs help topic for more information on the git diff
11945 format.
11946
11947 Returns 0 on success.
11948
11949 Options:
11950
11951 -e, --edit
11952 invoke editor on commit messages
11953
11954 -g, --git
11955 use git extended diff format
11956
11957 -s, --short
11958 refresh only files already in the patch and specified files
11959
11960 -U, --currentuser
11961 add/update author field in patch with current user
11962
11963 -u,--user <USER>
11964 add/update author field in patch with given user
11965
11966 -D, --currentdate
11967 add/update date field in patch with current date
11968
11969 -d,--date <DATE>
11970 add/update date field in patch with given date
11971
11972 -I,--include <PATTERN[+]>
11973 include names matching the given patterns
11974
11975 -X,--exclude <PATTERN[+]>
11976 exclude names matching the given patterns
11977
11978 -m,--message <TEXT>
11979 use text as commit message
11980
11981 -l,--logfile <FILE>
11982 read commit message from file
11983
11984 [+] marked option can be specified multiple times
11985
11986 Change manipulation
11987 qfold
11988 fold the named patches into the current patch:
11989
11990 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
11991
11992 Patches must not yet be applied. Each patch will be successively ap‐
11993 plied to the current patch in the order given. If all the patches apply
11994 successfully, the current patch will be refreshed with the new cumula‐
11995 tive patch, and the folded patches will be deleted. With -k/--keep, the
11996 folded patch files will not be removed afterwards.
11997
11998 The header for each folded patch will be concatenated with the current
11999 patch header, separated by a line of * * *.
12000
12001 Returns 0 on success.
12002
12003 Options:
12004
12005 -e, --edit
12006 invoke editor on commit messages
12007
12008 -k, --keep
12009 keep folded patch files
12010
12011 -m,--message <TEXT>
12012 use text as commit message
12013
12014 -l,--logfile <FILE>
12015 read commit message from file
12016
12017 Change organization
12018 qapplied
12019 print the patches already applied:
12020
12021 hg qapplied [-1] [-s] [PATCH]
12022
12023 Returns 0 on success.
12024
12025 Options:
12026
12027 -1, --last
12028 show only the preceding applied patch
12029
12030 -s, --summary
12031 print first line of patch header
12032
12033 qdelete
12034 remove patches from queue:
12035
12036 hg qdelete [-k] [PATCH]...
12037
12038 The patches must not be applied, and at least one patch is required.
12039 Exact patch identifiers must be given. With -k/--keep, the patch files
12040 are preserved in the patch directory.
12041
12042 To stop managing a patch and move it into permanent history, use the hg
12043 qfinish command.
12044
12045 Options:
12046
12047 -k, --keep
12048 keep patch file
12049
12050 -r,--rev <REV[+]>
12051 stop managing a revision (DEPRECATED)
12052
12053 [+] marked option can be specified multiple times
12054
12055 aliases: qremove qrm
12056
12057 qfinish
12058 move applied patches into repository history:
12059
12060 hg qfinish [-a] [REV]...
12061
12062 Finishes the specified revisions (corresponding to applied patches) by
12063 moving them out of mq control into regular repository history.
12064
12065 Accepts a revision range or the -a/--applied option. If --applied is
12066 specified, all applied mq revisions are removed from mq control. Other‐
12067 wise, the given revisions must be at the base of the stack of applied
12068 patches.
12069
12070 This can be especially useful if your changes have been applied to an
12071 upstream repository, or if you are about to push your changes to up‐
12072 stream.
12073
12074 Returns 0 on success.
12075
12076 Options:
12077
12078 -a, --applied
12079 finish all applied changesets
12080
12081 qgoto
12082 push or pop patches until named patch is at top of stack:
12083
12084 hg qgoto [OPTION]... PATCH
12085
12086 Returns 0 on success.
12087
12088 Options:
12089
12090 --keep-changes
12091 tolerate non-conflicting local changes
12092
12093 -f, --force
12094 overwrite any local changes
12095
12096 --no-backup
12097 do not save backup copies of files
12098
12099 qguard
12100 set or print guards for a patch:
12101
12102 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
12103
12104 Guards control whether a patch can be pushed. A patch with no guards is
12105 always pushed. A patch with a positive guard ("+foo") is pushed only if
12106 the hg qselect command has activated it. A patch with a negative guard
12107 ("-foo") is never pushed if the hg qselect command has activated it.
12108
12109 With no arguments, print the currently active guards. With arguments,
12110 set guards for the named patch.
12111
12112 Note Specifying negative guards now requires '--'.
12113
12114 To set guards on another patch:
12115
12116 hg qguard other.patch -- +2.6.17 -stable
12117
12118 Returns 0 on success.
12119
12120 Options:
12121
12122 -l, --list
12123 list all patches and guards
12124
12125 -n, --none
12126 drop all guards
12127
12128 qheader
12129 print the header of the topmost or specified patch:
12130
12131 hg qheader [PATCH]
12132
12133 Returns 0 on success.
12134
12135 qnext
12136 print the name of the next pushable patch:
12137
12138 hg qnext [-s]
12139
12140 Returns 0 on success.
12141
12142 Options:
12143
12144 -s, --summary
12145 print first line of patch header
12146
12147 qpop
12148 pop the current patch off the stack:
12149
12150 hg qpop [-a] [-f] [PATCH | INDEX]
12151
12152 Without argument, pops off the top of the patch stack. If given a patch
12153 name, keeps popping off patches until the named patch is at the top of
12154 the stack.
12155
12156 By default, abort if the working directory contains uncommitted
12157 changes. With --keep-changes, abort only if the uncommitted files over‐
12158 lap with patched files. With -f/--force, backup and discard changes
12159 made to such files.
12160
12161 Return 0 on success.
12162
12163 Options:
12164
12165 -a, --all
12166 pop all patches
12167
12168 -n,--name <NAME>
12169 queue name to pop (DEPRECATED)
12170
12171 --keep-changes
12172 tolerate non-conflicting local changes
12173
12174 -f, --force
12175 forget any local changes to patched files
12176
12177 --no-backup
12178 do not save backup copies of files
12179
12180 qprev
12181 print the name of the preceding applied patch:
12182
12183 hg qprev [-s]
12184
12185 Returns 0 on success.
12186
12187 Options:
12188
12189 -s, --summary
12190 print first line of patch header
12191
12192 qpush
12193 push the next patch onto the stack:
12194
12195 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
12196
12197 By default, abort if the working directory contains uncommitted
12198 changes. With --keep-changes, abort only if the uncommitted files over‐
12199 lap with patched files. With -f/--force, backup and patch over uncom‐
12200 mitted changes.
12201
12202 Return 0 on success.
12203
12204 Options:
12205
12206 --keep-changes
12207 tolerate non-conflicting local changes
12208
12209 -f, --force
12210 apply on top of local changes
12211
12212 -e, --exact
12213 apply the target patch to its recorded parent
12214
12215 -l, --list
12216 list patch name in commit text
12217
12218 -a, --all
12219 apply all patches
12220
12221 -m, --merge
12222 merge from another queue (DEPRECATED)
12223
12224 -n,--name <NAME>
12225 merge queue name (DEPRECATED)
12226
12227 --move reorder patch series and apply only the patch
12228
12229 --no-backup
12230 do not save backup copies of files
12231
12232 qqueue
12233 manage multiple patch queues:
12234
12235 hg qqueue [OPTION] [QUEUE]
12236
12237 Supports switching between different patch queues, as well as creating
12238 new patch queues and deleting existing ones.
12239
12240 Omitting a queue name or specifying -l/--list will show you the regis‐
12241 tered queues - by default the "normal" patches queue is registered. The
12242 currently active queue will be marked with "(active)". Specifying --ac‐
12243 tive will print only the name of the active queue.
12244
12245 To create a new queue, use -c/--create. The queue is automatically made
12246 active, except in the case where there are applied patches from the
12247 currently active queue in the repository. Then the queue will only be
12248 created and switching will fail.
12249
12250 To delete an existing queue, use --delete. You cannot delete the cur‐
12251 rently active queue.
12252
12253 Returns 0 on success.
12254
12255 Options:
12256
12257 -l, --list
12258 list all available queues
12259
12260 --active
12261 print name of active queue
12262
12263 -c, --create
12264 create new queue
12265
12266 --rename
12267 rename active queue
12268
12269 --delete
12270 delete reference to queue
12271
12272 --purge
12273 delete queue, and remove patch dir
12274
12275 qrename
12276 rename a patch:
12277
12278 hg qrename PATCH1 [PATCH2]
12279
12280 With one argument, renames the current patch to PATCH1. With two argu‐
12281 ments, renames PATCH1 to PATCH2.
12282
12283 Returns 0 on success.
12284
12285 aliases: qmv
12286
12287 qrestore
12288 restore the queue state saved by a revision (DEPRECATED):
12289
12290 hg qrestore [-d] [-u] REV
12291
12292 This command is deprecated, use hg rebase instead.
12293
12294 Options:
12295
12296 -d, --delete
12297 delete save entry
12298
12299 -u, --update
12300 update queue working directory
12301
12302 qsave
12303 save current queue state (DEPRECATED):
12304
12305 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
12306
12307 This command is deprecated, use hg rebase instead.
12308
12309 Options:
12310
12311 -c, --copy
12312 copy patch directory
12313
12314 -n,--name <NAME>
12315 copy directory name
12316
12317 -e, --empty
12318 clear queue status file
12319
12320 -f, --force
12321 force copy
12322
12323 -m,--message <TEXT>
12324 use text as commit message
12325
12326 -l,--logfile <FILE>
12327 read commit message from file
12328
12329 qselect
12330 set or print guarded patches to push:
12331
12332 hg qselect [OPTION]... [GUARD]...
12333
12334 Use the hg qguard command to set or print guards on patch, then use qs‐
12335 elect to tell mq which guards to use. A patch will be pushed if it has
12336 no guards or any positive guards match the currently selected guard,
12337 but will not be pushed if any negative guards match the current guard.
12338 For example:
12339
12340 qguard foo.patch -- -stable (negative guard)
12341 qguard bar.patch +stable (positive guard)
12342 qselect stable
12343
12344 This activates the "stable" guard. mq will skip foo.patch (because it
12345 has a negative match) but push bar.patch (because it has a positive
12346 match).
12347
12348 With no arguments, prints the currently active guards. With one argu‐
12349 ment, sets the active guard.
12350
12351 Use -n/--none to deactivate guards (no other arguments needed). When
12352 no guards are active, patches with positive guards are skipped and
12353 patches with negative guards are pushed.
12354
12355 qselect can change the guards on applied patches. It does not pop
12356 guarded patches by default. Use --pop to pop back to the last applied
12357 patch that is not guarded. Use --reapply (which implies --pop) to push
12358 back to the current patch afterwards, but skip guarded patches.
12359
12360 Use -s/--series to print a list of all guards in the series file (no
12361 other arguments needed). Use -v for more information.
12362
12363 Returns 0 on success.
12364
12365 Options:
12366
12367 -n, --none
12368 disable all guards
12369
12370 -s, --series
12371 list all guards in series file
12372
12373 --pop pop to before first guarded applied patch
12374
12375 --reapply
12376 pop, then reapply patches
12377
12378 qseries
12379 print the entire series file:
12380
12381 hg qseries [-ms]
12382
12383 Returns 0 on success.
12384
12385 Options:
12386
12387 -m, --missing
12388 print patches not in series
12389
12390 -s, --summary
12391 print first line of patch header
12392
12393 qtop
12394 print the name of the current patch:
12395
12396 hg qtop [-s]
12397
12398 Returns 0 on success.
12399
12400 Options:
12401
12402 -s, --summary
12403 print first line of patch header
12404
12405 qunapplied
12406 print the patches not yet applied:
12407
12408 hg qunapplied [-1] [-s] [PATCH]
12409
12410 Returns 0 on success.
12411
12412 Options:
12413
12414 -1, --first
12415 show only the first patch
12416
12417 -s, --summary
12418 print first line of patch header
12419
12420 File content management
12421 qdiff
12422 diff of the current patch and subsequent modifications:
12423
12424 hg qdiff [OPTION]... [FILE]...
12425
12426 Shows a diff which includes the current patch as well as any changes
12427 which have been made in the working directory since the last refresh
12428 (thus showing what the current patch would become after a qrefresh).
12429
12430 Use hg diff if you only want to see the changes made since the last
12431 qrefresh, or hg export qtip if you want to see changes made by the cur‐
12432 rent patch without including changes made since the qrefresh.
12433
12434 Returns 0 on success.
12435
12436 Options:
12437
12438 -a, --text
12439 treat all files as text
12440
12441 -g, --git
12442 use git extended diff format (DEFAULT: diff.git)
12443
12444 --binary
12445 generate binary diffs in git mode (default)
12446
12447 --nodates
12448 omit dates from diff headers
12449
12450 --noprefix
12451 omit a/ and b/ prefixes from filenames
12452
12453 -p, --show-function
12454 show which function each change is in (DEFAULT: diff.showfunc)
12455
12456 --reverse
12457 produce a diff that undoes the changes
12458
12459 -w, --ignore-all-space
12460 ignore white space when comparing lines
12461
12462 -b, --ignore-space-change
12463 ignore changes in the amount of white space
12464
12465 -B, --ignore-blank-lines
12466 ignore changes whose lines are all blank
12467
12468 -Z, --ignore-space-at-eol
12469 ignore changes in whitespace at EOL
12470
12471 -U,--unified <NUM>
12472 number of lines of context to show
12473
12474 --stat output diffstat-style summary of changes
12475
12476 --root <DIR>
12477 produce diffs relative to subdirectory
12478
12479 -I,--include <PATTERN[+]>
12480 include names matching the given patterns
12481
12482 -X,--exclude <PATTERN[+]>
12483 exclude names matching the given patterns
12484
12485 [+] marked option can be specified multiple times
12486
12487 Change import/export
12488 qimport
12489 import a patch or existing changeset:
12490
12491 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
12492
12493 The patch is inserted into the series after the last applied patch. If
12494 no patches have been applied, qimport prepends the patch to the series.
12495
12496 The patch will have the same name as its source file unless you give it
12497 a new one with -n/--name.
12498
12499 You can register an existing patch inside the patch directory with the
12500 -e/--existing flag.
12501
12502 With -f/--force, an existing patch of the same name will be overwrit‐
12503 ten.
12504
12505 An existing changeset may be placed under mq control with -r/--rev
12506 (e.g. qimport --rev . -n patch will place the current revision under mq
12507 control). With -g/--git, patches imported with --rev will use the git
12508 diff format. See the diffs help topic for information on why this is
12509 important for preserving rename/copy information and permission
12510 changes. Use hg qfinish to remove changesets from mq control.
12511
12512 To import a patch from standard input, pass - as the patch file. When
12513 importing from standard input, a patch name must be specified using the
12514 --name flag.
12515
12516 To import an existing patch while renaming it:
12517
12518 hg qimport -e existing-patch -n new-name
12519
12520 Returns 0 if import succeeded.
12521
12522 Options:
12523
12524 -e, --existing
12525 import file in patch directory
12526
12527 -n,--name <NAME>
12528 name of patch file
12529
12530 -f, --force
12531 overwrite existing files
12532
12533 -r,--rev <REV[+]>
12534 place existing revisions under mq control
12535
12536 -g, --git
12537 use git extended diff format
12538
12539 -P, --push
12540 qpush after importing
12541
12542 [+] marked option can be specified multiple times
12543
12544 narrow
12545 create clones which fetch history data for subset of files (EXPERIMEN‐
12546 TAL)
12547
12548 Commands
12549 Repository maintenance
12550 tracked
12551 show or change the current narrowspec:
12552
12553 hg tracked [OPTIONS]... [REMOTE]
12554
12555 With no argument, shows the current narrowspec entries, one per line.
12556 Each line will be prefixed with 'I' or 'X' for included or excluded
12557 patterns, respectively.
12558
12559 The narrowspec is comprised of expressions to match remote files and/or
12560 directories that should be pulled into your client. The narrowspec has
12561 include and exclude expressions, with excludes always trumping in‐
12562 cludes: that is, if a file matches an exclude expression, it will be
12563 excluded even if it also matches an include expression. Excluding
12564 files that were never included has no effect.
12565
12566 Each included or excluded entry is in the format described by 'hg help
12567 patterns'.
12568
12569 The options allow you to add or remove included and excluded expres‐
12570 sions.
12571
12572 If --clear is specified, then all previous includes and excludes are
12573 DROPPED and replaced by the new ones specified to --addinclude and
12574 --addexclude. If --clear is specified without any further options, the
12575 narrowspec will be empty and will not match any files.
12576
12577 If --auto-remove-includes is specified, then those includes that don't
12578 match any files modified by currently visible local commits (those not
12579 shared by the remote) will be added to the set of explicitly specified
12580 includes to remove.
12581
12582 --import-rules accepts a path to a file containing rules, allowing you
12583 to add --addinclude, --addexclude rules in bulk. Like the other include
12584 and exclude switches, the changes are applied immediately.
12585
12586 Options:
12587
12588 --addinclude <VALUE[+]>
12589 new paths to include
12590
12591 --removeinclude <VALUE[+]>
12592 old paths to no longer include
12593
12594 --auto-remove-includes
12595 automatically choose unused includes to remove
12596
12597 --addexclude <VALUE[+]>
12598 new paths to exclude
12599
12600 --import-rules <VALUE>
12601 import narrowspecs from a file
12602
12603 --removeexclude <VALUE[+]>
12604 old paths to no longer exclude
12605
12606 --clear
12607 whether to replace the existing narrowspec
12608
12609 --force-delete-local-changes
12610 forces deletion of local changes when narrowing
12611
12612 --backup
12613 back up local changes when narrowing (default: True)
12614
12615 --update-working-copy
12616 update working copy when the store has changed
12617
12618 -e,--ssh <CMD>
12619 specify ssh command to use
12620
12621 --remotecmd <CMD>
12622 specify hg command to run on the remote side
12623
12624 --insecure
12625 do not verify server certificate (ignoring web.cacerts config)
12626
12627 [+] marked option can be specified multiple times
12628
12629 notify
12630 hooks for sending email push notifications
12631
12632 This extension implements hooks to send email notifications when
12633 changesets are sent from or received by the local repository.
12634
12635 First, enable the extension as explained in hg help extensions, and
12636 register the hook you want to run. incoming and changegroup hooks are
12637 run when changesets are received, while outgoing hooks are for change‐
12638 sets sent to another repository:
12639
12640 [hooks]
12641 # one email for each incoming changeset
12642 incoming.notify = python:hgext.notify.hook
12643 # one email for all incoming changesets
12644 changegroup.notify = python:hgext.notify.hook
12645
12646 # one email for all outgoing changesets
12647 outgoing.notify = python:hgext.notify.hook
12648
12649 This registers the hooks. To enable notification, subscribers must be
12650 assigned to repositories. The [usersubs] section maps multiple reposi‐
12651 tories to a given recipient. The [reposubs] section maps multiple re‐
12652 cipients to a single repository:
12653
12654 [usersubs]
12655 # key is subscriber email, value is a comma-separated list of repo patterns
12656 user@host = pattern
12657
12658 [reposubs]
12659 # key is repo pattern, value is a comma-separated list of subscriber emails
12660 pattern = user@host
12661
12662 A pattern is a glob matching the absolute path to a repository, option‐
12663 ally combined with a revset expression. A revset expression, if
12664 present, is separated from the glob by a hash. Example:
12665
12666 [reposubs]
12667 */widgets#branch(release) = qa-team@example.com
12668
12669 This sends to qa-team@example.com whenever a changeset on the release
12670 branch triggers a notification in any repository ending in widgets.
12671
12672 In order to place them under direct user management, [usersubs] and
12673 [reposubs] sections may be placed in a separate hgrc file and incorpo‐
12674 rated by reference:
12675
12676 [notify]
12677 config = /path/to/subscriptionsfile
12678
12679 Notifications will not be sent until the notify.test value is set to
12680 False; see below.
12681
12682 Notifications content can be tweaked with the following configuration
12683 entries:
12684
12685 notify.test
12686 If True, print messages to stdout instead of sending them. De‐
12687 fault: True.
12688
12689 notify.sources
12690 Space-separated list of change sources. Notifications are acti‐
12691 vated only when a changeset's source is in this list. Sources
12692 may be:
12693
12694 serve
12695
12696 changesets received via http or ssh
12697
12698 pull
12699
12700 changesets received via hg pull
12701
12702 unbundle
12703
12704 changesets received via hg unbundle
12705
12706 push
12707
12708 changesets sent or received via hg push
12709
12710 bundle
12711
12712 changesets sent via hg unbundle
12713
12714 Default: serve.
12715
12716 notify.strip
12717 Number of leading slashes to strip from url paths. By default,
12718 notifications reference repositories with their absolute path.
12719 notify.strip lets you turn them into relative paths. For exam‐
12720 ple, notify.strip=3 will change /long/path/repository into
12721 repository. Default: 0.
12722
12723 notify.domain
12724 Default email domain for sender or recipients with no explicit
12725 domain. It is also used for the domain part of the Message-Id
12726 when using notify.messageidseed.
12727
12728 notify.messageidseed
12729 Create deterministic Message-Id headers for the mails based on
12730 the seed and the revision identifier of the first commit in the
12731 changeset.
12732
12733 notify.style
12734 Style file to use when formatting emails.
12735
12736 notify.template
12737 Template to use when formatting emails.
12738
12739 notify.incoming
12740 Template to use when run as an incoming hook, overriding no‐
12741 tify.template.
12742
12743 notify.outgoing
12744 Template to use when run as an outgoing hook, overriding no‐
12745 tify.template.
12746
12747 notify.changegroup
12748 Template to use when running as a changegroup hook, overriding
12749 notify.template.
12750
12751 notify.maxdiff
12752 Maximum number of diff lines to include in notification email.
12753 Set to 0 to disable the diff, or -1 to include all of it. De‐
12754 fault: 300.
12755
12756 notify.maxdiffstat
12757 Maximum number of diffstat lines to include in notification
12758 email. Set to -1 to include all of it. Default: -1.
12759
12760 notify.maxsubject
12761 Maximum number of characters in email's subject line. Default:
12762 67.
12763
12764 notify.diffstat
12765 Set to True to include a diffstat before diff content. Default:
12766 True.
12767
12768 notify.showfunc
12769 If set, override diff.showfunc for the diff content. Default:
12770 None.
12771
12772 notify.merge
12773 If True, send notifications for merge changesets. Default: True.
12774
12775 notify.mbox
12776 If set, append mails to this mbox file instead of sending. De‐
12777 fault: None.
12778
12779 notify.fromauthor
12780 If set, use the committer of the first changeset in a change‐
12781 group for the "From" field of the notification mail. If not set,
12782 take the user from the pushing repo. Default: False.
12783
12784 notify.reply-to-predecessor (EXPERIMENTAL)
12785 If set and the changeset has a predecessor in the repository,
12786 try to thread the notification mail with the predecessor. This
12787 adds the "In-Reply-To" header to the notification mail with a
12788 reference to the predecessor with the smallest revision number.
12789 Mail threads can still be torn, especially when changesets are
12790 folded.
12791
12792 This option must be used in combination with notify.messageid‐
12793 seed.
12794
12795 If set, the following entries will also be used to customize the noti‐
12796 fications:
12797
12798 email.from
12799 Email From address to use if none can be found in the generated
12800 email content.
12801
12802 web.baseurl
12803 Root repository URL to combine with repository paths when making
12804 references. See also notify.strip.
12805
12806 pager
12807 browse command output with an external pager (DEPRECATED)
12808
12809 Forcibly enable paging for individual commands that don't typically re‐
12810 quest pagination with the attend-<command> option. This setting takes
12811 precedence over ignore options and defaults:
12812
12813 [pager]
12814 attend-cat = false
12815
12816 patchbomb
12817 command to send changesets as (a series of) patch emails
12818
12819 The series is started off with a "[PATCH 0 of N]" introduction, which
12820 describes the series as a whole.
12821
12822 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12823 first line of the changeset description as the subject text. The mes‐
12824 sage contains two or three body parts:
12825
12826 • The changeset description.
12827
12828 • [Optional] The result of running diffstat on the patch.
12829
12830 • The patch itself, as generated by hg export.
12831
12832 Each message refers to the first in the series using the In-Reply-To
12833 and References headers, so they will show up as a sequence in threaded
12834 mail and news readers, and in mail archives.
12835
12836 To configure other defaults, add a section like this to your configura‐
12837 tion file:
12838
12839 [email]
12840 from = My Name <my@email>
12841 to = recipient1, recipient2, ...
12842 cc = cc1, cc2, ...
12843 bcc = bcc1, bcc2, ...
12844 reply-to = address1, address2, ...
12845
12846 Use [patchbomb] as configuration section name if you need to override
12847 global [email] address settings.
12848
12849 Then you can use the hg email command to mail a series of changesets as
12850 a patchbomb.
12851
12852 You can also either configure the method option in the email section to
12853 be a sendmail compatible mailer or fill out the [smtp] section so that
12854 the patchbomb extension can automatically send patchbombs directly from
12855 the commandline. See the [email] and [smtp] sections in hgrc(5) for de‐
12856 tails.
12857
12858 By default, hg email will prompt for a To or CC header if you do not
12859 supply one via configuration or the command line. You can override
12860 this to never prompt by configuring an empty value:
12861
12862 [email]
12863 cc =
12864
12865 You can control the default inclusion of an introduction message with
12866 the patchbomb.intro configuration option. The configuration is always
12867 overwritten by command line flags like --intro and --desc:
12868
12869 [patchbomb]
12870 intro=auto # include introduction message if more than 1 patch (default)
12871 intro=never # never include an introduction message
12872 intro=always # always include an introduction message
12873
12874 You can specify a template for flags to be added in subject prefixes.
12875 Flags specified by --flag option are exported as {flags} keyword:
12876
12877 [patchbomb]
12878 flagtemplate = "{separate(' ',
12879 ifeq(branch, 'default', '', branch|upper),
12880 flags)}"
12881
12882 You can set patchbomb to always ask for confirmation by setting patch‐
12883 bomb.confirm to true.
12884
12885 Commands
12886 Change import/export
12887 email
12888 send changesets by email:
12889
12890 hg email [OPTION]... [DEST]...
12891
12892 By default, diffs are sent in the format generated by hg export, one
12893 per message. The series starts with a "[PATCH 0 of N]" introduction,
12894 which describes the series as a whole.
12895
12896 Each patch email has a Subject line of "[PATCH M of N] ...", using the
12897 first line of the changeset description as the subject text. The mes‐
12898 sage contains two or three parts. First, the changeset description.
12899
12900 With the -d/--diffstat option, if the diffstat program is installed,
12901 the result of running diffstat on the patch is inserted.
12902
12903 Finally, the patch itself, as generated by hg export.
12904
12905 With the -d/--diffstat or --confirm options, you will be presented with
12906 a final summary of all messages and asked for confirmation before the
12907 messages are sent.
12908
12909 By default the patch is included as text in the email body for easy re‐
12910 viewing. Using the -a/--attach option will instead create an attachment
12911 for the patch. With -i/--inline an inline attachment will be created.
12912 You can include a patch both as text in the email body and as a regular
12913 or an inline attachment by combining the -a/--attach or -i/--inline
12914 with the --body option.
12915
12916 With -B/--bookmark changesets reachable by the given bookmark are se‐
12917 lected.
12918
12919 With -o/--outgoing, emails will be generated for patches not found in
12920 the destination repository (or only those which are ancestors of the
12921 specified revisions if any are provided)
12922
12923 With -b/--bundle, changesets are selected as for --outgoing, but a sin‐
12924 gle email containing a binary Mercurial bundle as an attachment will be
12925 sent. Use the patchbomb.bundletype config option to control the bundle
12926 type as with hg bundle --type.
12927
12928 With -m/--mbox, instead of previewing each patchbomb message in a pager
12929 or sending the messages directly, it will create a UNIX mailbox file
12930 with the patch emails. This mailbox file can be previewed with any mail
12931 user agent which supports UNIX mbox files.
12932
12933 With -n/--test, all steps will run, but mail will not be sent. You
12934 will be prompted for an email recipient address, a subject and an in‐
12935 troductory message describing the patches of your patchbomb. Then when
12936 all is done, patchbomb messages are displayed.
12937
12938 In case email sending fails, you will find a backup of your series in‐
12939 troductory message in .hg/last-email.txt.
12940
12941 The default behavior of this command can be customized through configu‐
12942 ration. (See hg help patchbomb for details)
12943
12944 Examples:
12945
12946 hg email -r 3000 # send patch 3000 only
12947 hg email -r 3000 -r 3001 # send patches 3000 and 3001
12948 hg email -r 3000:3005 # send patches 3000 through 3005
12949 hg email 3000 # send patch 3000 (deprecated)
12950
12951 hg email -o # send all patches not in default
12952 hg email -o DEST # send all patches not in DEST
12953 hg email -o -r 3000 # send all ancestors of 3000 not in default
12954 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
12955
12956 hg email -B feature # send all ancestors of feature bookmark
12957
12958 hg email -b # send bundle of all patches not in default
12959 hg email -b DEST # send bundle of all patches not in DEST
12960 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
12961 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
12962
12963 hg email -o -m mbox && # generate an mbox file...
12964 mutt -R -f mbox # ... and view it with mutt
12965 hg email -o -m mbox && # generate an mbox file ...
12966 formail -s sendmail \ # ... and use formail to send from the mbox
12967 -bm -t < mbox # ... using sendmail
12968
12969 Before using this command, you will need to enable email in your hgrc.
12970 See the [email] section in hgrc(5) for details.
12971
12972 Options:
12973
12974 -g, --git
12975 use git extended diff format
12976
12977 --plain
12978 omit hg patch header
12979
12980 -o, --outgoing
12981 send changes not found in the target repository
12982
12983 -b, --bundle
12984 send changes not in target as a binary bundle
12985
12986 -B,--bookmark <BOOKMARK>
12987 send changes only reachable by given bookmark
12988
12989 --bundlename <NAME>
12990 name of the bundle attachment file (default: bundle)
12991
12992 -r,--rev <REV[+]>
12993 a revision to send
12994
12995 --force
12996 run even when remote repository is unrelated (with -b/--bundle)
12997
12998 --base <REV[+]>
12999 a base changeset to specify instead of a destination (with
13000 -b/--bundle)
13001
13002 --intro
13003 send an introduction email for a single patch
13004
13005 --body send patches as inline message text (default)
13006
13007 -a, --attach
13008 send patches as attachments
13009
13010 -i, --inline
13011 send patches as inline attachments
13012
13013 --bcc <EMAIL[+]>
13014 email addresses of blind carbon copy recipients
13015
13016 -c,--cc <EMAIL[+]>
13017 email addresses of copy recipients
13018
13019 --confirm
13020 ask for confirmation before sending
13021
13022 -d, --diffstat
13023 add diffstat output to messages
13024
13025 --date <DATE>
13026 use the given date as the sending date
13027
13028 --desc <FILE>
13029 use the given file as the series description
13030
13031 -f,--from <EMAIL>
13032 email address of sender
13033
13034 -n, --test
13035 print messages that would be sent
13036
13037 -m,--mbox <FILE>
13038 write messages to mbox file instead of sending them
13039
13040 --reply-to <EMAIL[+]>
13041 email addresses replies should be sent to
13042
13043 -s,--subject <TEXT>
13044 subject of first message (intro or single patch)
13045
13046 --in-reply-to <MSGID>
13047 message identifier to reply to
13048
13049 --flag <FLAG[+]>
13050 flags to add in subject prefixes
13051
13052 -t,--to <EMAIL[+]>
13053 email addresses of recipients
13054
13055 -e,--ssh <CMD>
13056 specify ssh command to use
13057
13058 --remotecmd <CMD>
13059 specify hg command to run on the remote side
13060
13061 --insecure
13062 do not verify server certificate (ignoring web.cacerts config)
13063
13064 [+] marked option can be specified multiple times
13065
13066 phabricator
13067 simple Phabricator integration (EXPERIMENTAL)
13068
13069 This extension provides a phabsend command which sends a stack of
13070 changesets to Phabricator, and a phabread command which prints a stack
13071 of revisions in a format suitable for hg import, and a phabupdate com‐
13072 mand to update statuses in batch.
13073
13074 A "phabstatus" view for hg show is also provided; it displays status
13075 information of Phabricator differentials associated with unfinished
13076 changesets.
13077
13078 By default, Phabricator requires Test Plan which might prevent some
13079 changeset from being sent. The requirement could be disabled by chang‐
13080 ing differential.require-test-plan-field config server side.
13081
13082 Config:
13083
13084 [phabricator]
13085 # Phabricator URL
13086 url = https://phab.example.com/
13087
13088 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
13089 # callsign is "FOO".
13090 callsign = FOO
13091
13092 # curl command to use. If not set (default), use builtin HTTP library to
13093 # communicate. If set, use the specified curl command. This could be useful
13094 # if you need to specify advanced options that is not easily supported by
13095 # the internal library.
13096 curlcmd = curl --connect-timeout 2 --retry 3 --silent
13097
13098 # retry failed command N time (default 0). Useful when using the extension
13099 # over flakly connection.
13100 #
13101 # We wait `retry.interval` between each retry, in seconds.
13102 # (default 1 second).
13103 retry = 3
13104 retry.interval = 10
13105
13106 # the retry option can combine well with the http.timeout one.
13107 #
13108 # For example to give up on http request after 20 seconds:
13109 [http]
13110 timeout=20
13111
13112 [auth]
13113 example.schemes = https
13114 example.prefix = phab.example.com
13115
13116 # API token. Get it from https://$HOST/conduit/login/
13117 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
13118
13119 Commands
13120 Change import/export
13121 phabimport
13122 import patches from Phabricator for the specified Differential Revi‐
13123 sions:
13124
13125 hg phabimport DREVSPEC... [OPTIONS]
13126
13127 The patches are read and applied starting at the parent of the working
13128 directory.
13129
13130 See hg help phabread for how to specify DREVSPEC.
13131
13132 Options:
13133
13134 --stack
13135 import dependencies as well
13136
13137 --test-vcr <VALUE>
13138 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13139 script, otherwise will mock all http requests using the speci‐
13140 fied vcr file. (ADVANCED)
13141
13142 phabread
13143 print patches from Phabricator suitable for importing:
13144
13145 hg phabread DREVSPEC... [OPTIONS]
13146
13147 DREVSPEC could be a Differential Revision identity, like D123, or just
13148 the number 123. It could also have common operators like +, -, &, (, )
13149 for complex queries. Prefix : could be used to select a stack. If mul‐
13150 tiple DREVSPEC values are given, the result is the union of each indi‐
13151 vidually evaluated value. No attempt is currently made to reorder the
13152 values to run from parent to child.
13153
13154 abandoned, accepted, closed, needsreview, needsrevision could be used
13155 to filter patches by status. For performance reason, they only repre‐
13156 sent a subset of non-status selections and cannot be used alone.
13157
13158 For example, :D6+8-(2+D4) selects a stack up to D6, plus D8 and exclude
13159 D2 and D4. :D9 & needsreview selects "Needs Review" revisions in a
13160 stack up to D9.
13161
13162 If --stack is given, follow dependencies information and read all
13163 patches. It is equivalent to the : operator.
13164
13165 Options:
13166
13167 --stack
13168 read dependencies
13169
13170 --test-vcr <VALUE>
13171 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13172 script, otherwise will mock all http requests using the speci‐
13173 fied vcr file. (ADVANCED)
13174
13175 phabsend
13176 upload changesets to Phabricator:
13177
13178 hg phabsend REV [OPTIONS]
13179
13180 If there are multiple revisions specified, they will be send as a stack
13181 with a linear dependencies relationship using the order specified by
13182 the revset.
13183
13184 For the first time uploading changesets, local tags will be created to
13185 maintain the association. After the first time, phabsend will check ob‐
13186 sstore and tags information so it can figure out whether to update an
13187 existing Differential Revision, or create a new one.
13188
13189 If --amend is set, update commit messages so they have the Differential
13190 Revision URL, remove related tags. This is similar to what arcanist
13191 will do, and is more desired in author-push workflows. Otherwise, use
13192 local tags to record the Differential Revision association.
13193
13194 The --confirm option lets you confirm changesets before sending them.
13195 You can also add following to your configuration file to make it de‐
13196 fault behaviour:
13197
13198 [phabsend]
13199 confirm = true
13200
13201 By default, a separate review will be created for each commit that is
13202 selected, and will have the same parent/child relationship in Phabrica‐
13203 tor. If --fold is set, multiple commits are rolled up into a single
13204 review as if diffed from the parent of the first revision to the last.
13205 The commit messages are concatenated in the summary field on Phabrica‐
13206 tor.
13207
13208 phabsend will check obsstore and the above association to decide
13209 whether to update an existing Differential Revision, or create a new
13210 one.
13211
13212 Options:
13213
13214 -r,--rev <REV[+]>
13215 revisions to send
13216
13217 --amend
13218 update commit messages (default: True)
13219
13220 --reviewer <VALUE[+]>
13221 specify reviewers
13222
13223 --blocker <VALUE[+]>
13224 specify blocking reviewers
13225
13226 -m,--comment <VALUE>
13227 add a comment to Revisions with new/updated Diffs
13228
13229 --confirm
13230 ask for confirmation before sending
13231
13232 --fold combine the revisions into one review
13233
13234 --test-vcr <VALUE>
13235 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13236 script, otherwise will mock all http requests using the speci‐
13237 fied vcr file. (ADVANCED)
13238
13239 [+] marked option can be specified multiple times
13240
13241 phabupdate
13242 update Differential Revision in batch:
13243
13244 hg phabupdate [DREVSPEC...| -r REV...] [OPTIONS]
13245
13246 DREVSPEC selects revisions. See hg help phabread for its usage.
13247
13248 Options:
13249
13250 --accept
13251 accept revisions
13252
13253 --reject
13254 reject revisions
13255
13256 --request-review
13257 request review on revisions
13258
13259 --abandon
13260 abandon revisions
13261
13262 --reclaim
13263 reclaim revisions
13264
13265 --close
13266 close revisions
13267
13268 --reopen
13269 reopen revisions
13270
13271 --plan-changes
13272 plan changes for revisions
13273
13274 --resign
13275 resign as a reviewer from revisions
13276
13277 --commandeer
13278 commandeer revisions
13279
13280 -m,--comment <VALUE>
13281 comment on the last revision
13282
13283 -r,--rev <REV>
13284 local revision to update
13285
13286 --test-vcr <VALUE>
13287 Path to a vcr file. If nonexistent, will record a new vcr tran‐
13288 script, otherwise will mock all http requests using the speci‐
13289 fied vcr file. (ADVANCED)
13290
13291 Uncategorized commands
13292 purge
13293 command to delete untracked files from the working directory (DEPRE‐
13294 CATED)
13295
13296 The functionality of this extension has been included in core Mercurial
13297 since version 5.7. Please use hg purge ... instead. hg purge --confirm
13298 is now the default, unless the extension is enabled for backward com‐
13299 patibility.
13300
13301 rebase
13302 command to move sets of revisions to a different ancestor
13303
13304 This extension lets you rebase changesets in an existing Mercurial
13305 repository.
13306
13307 For more information: https://mercurial-scm.org/wiki/RebaseExtension
13308
13309 Commands
13310 Change manipulation
13311 rebase
13312 move changeset (and descendants) to a different branch:
13313
13314 hg rebase [[-s REV]... | [-b REV]... | [-r REV]...] [-d REV] [OPTION]...
13315
13316 Rebase uses repeated merging to graft changesets from one part of his‐
13317 tory (the source) onto another (the destination). This can be useful
13318 for linearizing local changes relative to a master development tree.
13319
13320 Published commits cannot be rebased (see hg help phases). To copy com‐
13321 mits, see hg help graft.
13322
13323 If you don't specify a destination changeset (-d/--dest), rebase will
13324 use the same logic as hg merge to pick a destination. if the current
13325 branch contains exactly one other head, the other head is merged with
13326 by default. Otherwise, an explicit revision with which to merge with
13327 must be provided. (destination changeset is not modified by rebasing,
13328 but new changesets are added as its descendants.)
13329
13330 Here are the ways to select changesets:
13331
13332 1. Explicitly select them using --rev.
13333
13334 2. Use --source to select a root changeset and include all of its
13335 descendants.
13336
13337 3. Use --base to select a changeset; rebase will find ancestors and
13338 their descendants which are not also ancestors of the destina‐
13339 tion.
13340
13341 4. If you do not specify any of --rev, --source, or --base, rebase
13342 will use --base . as above.
13343
13344 If --source or --rev is used, special names SRC and ALLSRC can be used
13345 in --dest. Destination would be calculated per source revision with SRC
13346 substituted by that single source revision and ALLSRC substituted by
13347 all source revisions.
13348
13349 Rebase will destroy original changesets unless you use --keep. It will
13350 also move your bookmarks (even if you do).
13351
13352 Some changesets may be dropped if they do not contribute changes (e.g.
13353 merges from the destination branch).
13354
13355 Unlike merge, rebase will do nothing if you are at the branch tip of a
13356 named branch with two heads. You will need to explicitly specify source
13357 and/or destination.
13358
13359 If you need to use a tool to automate merge/conflict decisions, you can
13360 specify one with --tool, see hg help merge-tools. As a caveat: the
13361 tool will not be used to mediate when a file was deleted, there is no
13362 hook presently available for this.
13363
13364 If a rebase is interrupted to manually resolve a conflict, it can be
13365 continued with --continue/-c, aborted with --abort/-a, or stopped with
13366 --stop.
13367
13368 Examples:
13369
13370 • move "local changes" (current commit back to branching point) to the
13371 current branch tip after a pull:
13372
13373 hg rebase
13374
13375 • move a single changeset to the stable branch:
13376
13377 hg rebase -r 5f493448 -d stable
13378
13379 • splice a commit and all its descendants onto another part of history:
13380
13381 hg rebase --source c0c3 --dest 4cf9
13382
13383 • rebase everything on a branch marked by a bookmark onto the default
13384 branch:
13385
13386 hg rebase --base myfeature --dest default
13387
13388 • collapse a sequence of changes into a single commit:
13389
13390 hg rebase --collapse -r 1520:1525 -d .
13391
13392 • move a named branch while preserving its name:
13393
13394 hg rebase -r "branch(featureX)" -d 1.3 --keepbranches
13395
13396 • stabilize orphaned changesets so history looks linear:
13397
13398 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) & ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) & ::SRC)^)-obsolete()))'
13399
13400 Configuration Options:
13401
13402 You can make rebase require a destination if you set the following con‐
13403 fig option:
13404
13405 [commands]
13406 rebase.requiredest = True
13407
13408 By default, rebase will close the transaction after each commit. For
13409 performance purposes, you can configure rebase to use a single transac‐
13410 tion across the entire rebase. WARNING: This setting introduces a sig‐
13411 nificant risk of losing the work you've done in a rebase if the rebase
13412 aborts unexpectedly:
13413
13414 [rebase]
13415 singletransaction = True
13416
13417 By default, rebase writes to the working copy, but you can configure it
13418 to run in-memory for better performance. When the rebase is not moving
13419 the parent(s) of the working copy (AKA the "currently checked out
13420 changesets"), this may also allow it to run even if the working copy is
13421 dirty:
13422
13423 [rebase]
13424 experimental.inmemory = True
13425
13426 Return Values:
13427
13428 Returns 0 on success, 1 if nothing to rebase or there are unresolved
13429 conflicts.
13430
13431 Options:
13432
13433 -s,--source <REV[+]>
13434 rebase the specified changesets and their descendants
13435
13436 -b,--base <REV[+]>
13437 rebase everything from branching point of specified changeset
13438
13439 -r,--rev <REV[+]>
13440 rebase these revisions
13441
13442 -d,--dest <REV>
13443 rebase onto the specified changeset
13444
13445 --collapse
13446 collapse the rebased changesets
13447
13448 -m,--message <TEXT>
13449 use text as collapse commit message
13450
13451 -e, --edit
13452 invoke editor on commit messages
13453
13454 -l,--logfile <FILE>
13455 read collapse commit message from file
13456
13457 -k, --keep
13458 keep original changesets
13459
13460 --keepbranches
13461 keep original branch names
13462
13463 -D, --detach
13464 (DEPRECATED)
13465
13466 -i, --interactive
13467 (DEPRECATED)
13468
13469 -t,--tool <VALUE>
13470 specify merge tool
13471
13472 --stop stop interrupted rebase
13473
13474 -c, --continue
13475 continue an interrupted rebase
13476
13477 -a, --abort
13478 abort an interrupted rebase
13479
13480 --auto-orphans <VALUE>
13481 automatically rebase orphan revisions in the specified revset
13482 (EXPERIMENTAL)
13483
13484 -n, --dry-run
13485 do not perform actions, just print output
13486
13487 -T,--template <TEMPLATE>
13488 display with template
13489
13490 --confirm
13491 ask before applying actions
13492
13493 [+] marked option can be specified multiple times
13494
13495 record
13496 commands to interactively select changes for commit/qrefresh (DEPRE‐
13497 CATED)
13498
13499 The feature provided by this extension has been moved into core Mercu‐
13500 rial as hg commit --interactive.
13501
13502 Commands
13503 Change creation
13504 qrecord
13505 interactively record a new patch:
13506
13507 hg qrecord [OPTION]... PATCH [FILE]...
13508
13509 See hg help qnew & hg help record for more information and usage.
13510
13511 record
13512 interactively select changes to commit:
13513
13514 hg record [OPTION]... [FILE]...
13515
13516 If a list of files is omitted, all changes reported by hg status will
13517 be candidates for recording.
13518
13519 See hg help dates for a list of formats valid for -d/--date.
13520
13521 If using the text interface (see hg help config), you will be prompted
13522 for whether to record changes to each modified file, and for files with
13523 multiple changes, for each change to use. For each query, the following
13524 responses are possible:
13525
13526 y - record this change
13527 n - skip this change
13528 e - edit this change manually
13529
13530 s - skip remaining changes to this file
13531 f - record remaining changes to this file
13532
13533 d - done, skip remaining changes and files
13534 a - record all changes to all remaining files
13535 q - quit, recording no changes
13536
13537 ? - display help
13538
13539 This command is not available when committing a merge.
13540
13541 Options:
13542
13543 -A, --addremove
13544 mark new/missing files as added/removed before committing
13545
13546 --close-branch
13547 mark a branch head as closed
13548
13549 --amend
13550 amend the parent of the working directory
13551
13552 -s, --secret
13553 use the secret phase for committing
13554
13555 -e, --edit
13556 invoke editor on commit messages
13557
13558 --force-close-branch
13559 forcibly close branch from a non-head changeset (ADVANCED)
13560
13561 -I,--include <PATTERN[+]>
13562 include names matching the given patterns
13563
13564 -X,--exclude <PATTERN[+]>
13565 exclude names matching the given patterns
13566
13567 -m,--message <TEXT>
13568 use text as commit message
13569
13570 -l,--logfile <FILE>
13571 read commit message from file
13572
13573 -d,--date <DATE>
13574 record the specified date as commit date
13575
13576 -u,--user <USER>
13577 record the specified user as committer
13578
13579 -S, --subrepos
13580 recurse into subrepositories
13581
13582 -w, --ignore-all-space
13583 ignore white space when comparing lines
13584
13585 -b, --ignore-space-change
13586 ignore changes in the amount of white space
13587
13588 -B, --ignore-blank-lines
13589 ignore changes whose lines are all blank
13590
13591 -Z, --ignore-space-at-eol
13592 ignore changes in whitespace at EOL
13593
13594 [+] marked option can be specified multiple times
13595
13596 releasenotes
13597 generate release notes from commit messages (EXPERIMENTAL)
13598
13599 It is common to maintain files detailing changes in a project between
13600 releases. Maintaining these files can be difficult and time consuming.
13601 The hg releasenotes command provided by this extension makes the
13602 process simpler by automating it.
13603
13604 Commands
13605 Change navigation
13606 releasenotes
13607 parse release notes from commit messages into an output file:
13608
13609 hg releasenotes [-r REV] [-c] FILE
13610
13611 Given an output file and set of revisions, this command will parse com‐
13612 mit messages for release notes then add them to the output file.
13613
13614 Release notes are defined in commit messages as ReStructuredText direc‐
13615 tives. These have the form:
13616
13617 .. directive:: title
13618
13619 content
13620
13621 Each directive maps to an output section in a generated release notes
13622 file, which itself is ReStructuredText. For example, the .. feature::
13623 directive would map to a New Features section.
13624
13625 Release note directives can be either short-form or long-form. In
13626 short- form, title is omitted and the release note is rendered as a
13627 bullet list. In long form, a sub-section with the title title is added
13628 to the section.
13629
13630 The FILE argument controls the output file to write gathered release
13631 notes to. The format of the file is:
13632
13633 Section 1
13634 =========
13635
13636 ...
13637
13638 Section 2
13639 =========
13640
13641 ...
13642
13643 Only sections with defined release notes are emitted.
13644
13645 If a section only has short-form notes, it will consist of bullet list:
13646
13647 Section
13648 =======
13649
13650 * Release note 1
13651 * Release note 2
13652
13653 If a section has long-form notes, sub-sections will be emitted:
13654
13655 Section
13656 =======
13657
13658 Note 1 Title
13659 ------------
13660
13661 Description of the first long-form note.
13662
13663 Note 2 Title
13664 ------------
13665
13666 Description of the second long-form note.
13667
13668 If the FILE argument points to an existing file, that file will be
13669 parsed for release notes having the format that would be generated by
13670 this command. The notes from the processed commit messages will be
13671 merged into this parsed set.
13672
13673 During release notes merging:
13674
13675 • Duplicate items are automatically ignored
13676
13677 • Items that are different are automatically ignored if the similarity
13678 is greater than a threshold.
13679
13680 This means that the release notes file can be updated independently
13681 from this command and changes should not be lost when running this com‐
13682 mand on that file. A particular use case for this is to tweak the word‐
13683 ing of a release note after it has been added to the release notes
13684 file.
13685
13686 The -c/--check option checks the commit message for invalid admoni‐
13687 tions.
13688
13689 The -l/--list option, presents the user with a list of existing avail‐
13690 able admonitions along with their title. This also includes the custom
13691 admonitions (if any).
13692
13693 Options:
13694
13695 -r,--rev <REV>
13696 revisions to process for release notes
13697
13698 -c, --check
13699 checks for validity of admonitions (if any)
13700
13701 -l, --list
13702 list the available admonitions with their title
13703
13704 Uncategorized commands
13705 relink
13706 recreates hardlinks between repository clones
13707
13708 Commands
13709 Repository maintenance
13710 relink
13711 recreate hardlinks between two repositories:
13712
13713 hg relink [ORIGIN]
13714
13715 When repositories are cloned locally, their data files will be
13716 hardlinked so that they only use the space of a single repository.
13717
13718 Unfortunately, subsequent pulls into either repository will break
13719 hardlinks for any files touched by the new changesets, even if both
13720 repositories end up pulling the same changes.
13721
13722 Similarly, passing --rev to "hg clone" will fail to use any hardlinks,
13723 falling back to a complete copy of the source repository.
13724
13725 This command lets you recreate those hardlinks and reclaim that wasted
13726 space.
13727
13728 This repository will be relinked to share space with ORIGIN, which must
13729 be on the same local disk. If ORIGIN is omitted, looks for "default-re‐
13730 link", then "default", in [paths].
13731
13732 Do not attempt any read operations on this repository while the command
13733 is running. (Both repositories will be locked against writes.)
13734
13735 remotefilelog
13736 remotefilelog causes Mercurial to lazilly fetch file contents (EXPERI‐
13737 MENTAL)
13738
13739 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
13740 BILITY GUARANTEES. This means that repositories created with this ex‐
13741 tension may only be usable with the exact version of this exten‐
13742 sion/Mercurial that was used. The extension attempts to enforce this in
13743 order to prevent repository corruption.
13744
13745 remotefilelog works by fetching file contents lazily and storing them
13746 in a cache on the client rather than in revlogs. This allows enormous
13747 histories to be transferred only partially, making them easier to oper‐
13748 ate on.
13749
13750 Configs:
13751
13752 packs.maxchainlen specifies the maximum delta chain length in pack
13753 files
13754
13755 packs.maxpacksize specifies the maximum pack file size
13756
13757 packs.maxpackfilecount specifies the maximum number of packs in the
13758
13759 shared cache (trees only for now)
13760
13761 remotefilelog.backgroundprefetch runs prefetch in background when
13762 True
13763
13764 remotefilelog.bgprefetchrevs specifies revisions to fetch on commit
13765 and
13766
13767 update, and on other commands that use them. Different from
13768 pullprefetch.
13769
13770 remotefilelog.gcrepack does garbage collection during repack when
13771 True
13772
13773 remotefilelog.nodettl specifies maximum TTL of a node in seconds be‐
13774 fore
13775
13776 it is garbage collected
13777
13778 remotefilelog.repackonhggc runs repack on hg gc when True
13779
13780 remotefilelog.prefetchdays specifies the maximum age of a commit in
13781
13782 days after which it is no longer prefetched.
13783
13784 remotefilelog.prefetchdelay specifies delay between background
13785
13786 prefetches in seconds after operations that change the work‐
13787 ing copy parent
13788
13789 remotefilelog.data.gencountlimit constraints the minimum number of
13790 data
13791
13792 pack files required to be considered part of a generation. In
13793 particular, minimum number of packs files > gencountlimit.
13794
13795 remotefilelog.data.generations list for specifying the lower bound
13796 of
13797
13798 each generation of the data pack files. For example, list
13799 ['100MB','1MB'] or ['1MB', '100MB'] will lead to three gener‐
13800 ations: [0, 1MB), [ 1MB, 100MB) and [100MB, infinity).
13801
13802 remotefilelog.data.maxrepackpacks the maximum number of pack files
13803 to
13804
13805 include in an incremental data repack.
13806
13807 remotefilelog.data.repackmaxpacksize the maximum size of a pack file
13808 for
13809
13810 it to be considered for an incremental data repack.
13811
13812 remotefilelog.data.repacksizelimit the maximum total size of pack
13813 files
13814
13815 to include in an incremental data repack.
13816
13817 remotefilelog.history.gencountlimit constraints the minimum number
13818 of
13819
13820 history pack files required to be considered part of a gener‐
13821 ation. In particular, minimum number of packs files > gen‐
13822 countlimit.
13823
13824 remotefilelog.history.generations list for specifying the lower
13825 bound of
13826
13827 each generation of the history pack files. For example, list
13828 [ '100MB', '1MB'] or ['1MB', '100MB'] will lead to three gen‐
13829 erations: [ 0, 1MB), [1MB, 100MB) and [100MB, infinity).
13830
13831 remotefilelog.history.maxrepackpacks the maximum number of pack
13832 files to
13833
13834 include in an incremental history repack.
13835
13836 remotefilelog.history.repackmaxpacksize the maximum size of a pack
13837 file
13838
13839 for it to be considered for an incremental history repack.
13840
13841 remotefilelog.history.repacksizelimit the maximum total size of pack
13842
13843 files to include in an incremental history repack.
13844
13845 remotefilelog.backgroundrepack automatically consolidate packs in
13846 the
13847
13848 background
13849
13850 remotefilelog.cachepath path to cache
13851
13852 remotefilelog.cachegroup if set, make cache directory sgid to this
13853
13854 group
13855
13856 remotefilelog.cacheprocess binary to invoke for fetching file data
13857
13858 remotefilelog.debug turn on remotefilelog-specific debug output
13859
13860 remotefilelog.excludepattern pattern of files to exclude from pulls
13861
13862 remotefilelog.includepattern pattern of files to include in pulls
13863
13864 remotefilelog.fetchwarning: message to print when too many
13865
13866 single-file fetches occur
13867
13868 remotefilelog.getfilesstep number of files to request in a single
13869 RPC
13870
13871 remotefilelog.getfilestype if set to 'threaded' use threads to fetch
13872
13873 files, otherwise use optimistic fetching
13874
13875 remotefilelog.pullprefetch revset for selecting files that should be
13876
13877 eagerly downloaded rather than lazily
13878
13879 remotefilelog.reponame name of the repo. If set, used to partition
13880
13881 data from other repos in a shared store.
13882
13883 remotefilelog.server if true, enable server-side functionality
13884
13885 remotefilelog.servercachepath path for caching blobs on the server
13886
13887 remotefilelog.serverexpiration number of days to keep cached server
13888
13889 blobs
13890
13891 remotefilelog.validatecache if set, check cache entries for corrup‐
13892 tion
13893
13894 before returning blobs
13895
13896 remotefilelog.validatecachelog if set, check cache entries for
13897
13898 corruption before returning metadata
13899
13900 Commands
13901 Repository maintenance
13902 prefetch
13903 prefetch file revisions from the server:
13904
13905 hg prefetch [OPTIONS] [FILE...]
13906
13907 Prefetchs file revisions for the specified revs and stores them in the
13908 local remotefilelog cache. If no rev is specified, the default rev is
13909 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
13910 File names or patterns can be used to limit which files are downloaded.
13911
13912 Return 0 on success.
13913
13914 Options:
13915
13916 -r,--rev <REV[+]>
13917 prefetch the specified revisions
13918
13919 --repack
13920 run repack after prefetch
13921
13922 -b,--base <VALUE>
13923 rev that is assumed to already be local
13924
13925 -I,--include <PATTERN[+]>
13926 include names matching the given patterns
13927
13928 -X,--exclude <PATTERN[+]>
13929 exclude names matching the given patterns
13930
13931 [+] marked option can be specified multiple times
13932
13933 Uncategorized commands
13934 gc
13935 garbage collect the client and server filelog caches:
13936
13937 hg gc [REPO...]
13938
13939 garbage collect the client and server filelog caches
13940
13941 repack
13942 hg repack [OPTIONS]
13943
13944 Options:
13945
13946 --background
13947 run in a background process
13948
13949 --incremental
13950 do an incremental repack
13951
13952 --packsonly
13953 only repack packs (skip loose objects)
13954
13955 verifyremotefilelog
13956 hg verifyremotefilelogs <directory>
13957
13958 Options:
13959
13960 -d, --decompress
13961 decompress the filelogs first
13962
13963 remotenames
13964 showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)
13965
13966 By default both remotebookmarks and remotebranches are turned on. Con‐
13967 fig knob to control the individually are as follows.
13968
13969 Config options to tweak the default behaviour:
13970
13971 remotenames.bookmarks
13972 Boolean value to enable or disable showing of remotebookmarks
13973 (default: True)
13974
13975 remotenames.branches
13976 Boolean value to enable or disable showing of remotebranches
13977 (default: True)
13978
13979 remotenames.hoistedpeer
13980 Name of the peer whose remotebookmarks should be hoisted into
13981 the top-level namespace (default: 'default')
13982
13983 schemes
13984 extend schemes with shortcuts to repository swarms
13985
13986 This extension allows you to specify shortcuts for parent URLs with a
13987 lot of repositories to act like a scheme, for example:
13988
13989 [schemes]
13990 py = http://code.python.org/hg/
13991
13992 After that you can use it like:
13993
13994 hg clone py://trunk/
13995
13996 Additionally there is support for some more complex schemas, for exam‐
13997 ple used by Google Code:
13998
13999 [schemes]
14000 gcode = http://{1}.googlecode.com/hg/
14001
14002 The syntax is taken from Mercurial templates, and you have unlimited
14003 number of variables, starting with {1} and continuing with {2}, {3} and
14004 so on. This variables will receive parts of URL supplied, split by /.
14005 Anything not specified as {part} will be just appended to an URL.
14006
14007 For convenience, the extension adds these schemes by default:
14008
14009 [schemes]
14010 py = http://hg.python.org/
14011 bb = https://bitbucket.org/
14012 bb+ssh = ssh://hg@bitbucket.org/
14013 gcode = https://{1}.googlecode.com/hg/
14014 kiln = https://{1}.kilnhg.com/Repo/
14015
14016 You can override a predefined scheme by defining a new scheme with the
14017 same name.
14018
14019 Commands
14020 Uncategorized commands
14021 share
14022 share a common history between several working directories
14023
14024 The share extension introduces a new command hg share to create a new
14025 working directory. This is similar to hg clone, but doesn't involve
14026 copying or linking the storage of the repository. This allows working
14027 on different branches or changes in parallel without the associated
14028 cost in terms of disk space.
14029
14030 Note: destructive operations or extensions like hg rollback should be
14031 used with care as they can result in confusing problems.
14032
14033 Automatic Pooled Storage for Clones
14034 When this extension is active, hg clone can be configured to automati‐
14035 cally share/pool storage across multiple clones. This mode effectively
14036 converts hg clone to hg clone + hg share. The benefit of using this
14037 mode is the automatic management of store paths and intelligent pooling
14038 of related repositories.
14039
14040 The following share. config options influence this feature:
14041
14042 share.pool
14043
14044 Filesystem path where shared repository data will be stored.
14045 When defined, hg clone will automatically use shared repository
14046 storage instead of creating a store inside each clone.
14047
14048 share.poolnaming
14049
14050 How directory names in share.pool are constructed.
14051
14052 "identity" means the name is derived from the first changeset in
14053 the repository. In this mode, different remotes share storage if
14054 their root/initial changeset is identical. In this mode, the lo‐
14055 cal shared repository is an aggregate of all encountered remote
14056 repositories.
14057
14058 "remote" means the name is derived from the source repository's
14059 path or URL. In this mode, storage is only shared if the path or
14060 URL requested in the hg clone command matches exactly to a
14061 repository that was cloned before.
14062
14063 The default naming mode is "identity".
14064
14065 Sharing requirements and configs of source repository with shares:
14066
14067 By default creating a shared repository only enables sharing a common
14068 history and does not share requirements and configs between them. This
14069 may lead to problems in some cases, for example when you upgrade the
14070 storage format from one repository but does not set related configs in
14071 the shares.
14072
14073 Setting format.exp-share-safe = True enables sharing configs and re‐
14074 quirements. This only applies to shares which are done after enabling
14075 the config option.
14076
14077 For enabling this in existing shares, enable the config option and re‐
14078 share.
14079
14080 For resharing existing shares, make sure your working directory is
14081 clean and there are no untracked files, delete that share and create a
14082 new share.
14083
14084 Commands
14085 Repository creation
14086 share
14087 create a new shared repository:
14088
14089 hg share [-U] [-B] SOURCE [DEST]
14090
14091 Initialize a new repository and working directory that shares its his‐
14092 tory (and optionally bookmarks) with another repository.
14093
14094 Note using rollback or extensions that destroy/modify history (mq,
14095 rebase, etc.) can cause considerable confusion with shared
14096 clones. In particular, if two shared clones are both updated to
14097 the same changeset, and one of them destroys that changeset with
14098 rollback, the other clone will suddenly stop working: all opera‐
14099 tions will fail with "abort: working directory has unknown par‐
14100 ent". The only known workaround is to use debugsetparents on the
14101 broken clone to reset it to a changeset that still exists.
14102
14103 Options:
14104
14105 -U, --noupdate
14106 do not create a working directory
14107
14108 -B, --bookmarks
14109 also share bookmarks
14110
14111 --relative
14112 point to source using a relative path
14113
14114 Repository maintenance
14115 unshare
14116 convert a shared repository to a normal one:
14117
14118 hg unshare
14119
14120 Copy the store data to the repo and remove the sharedpath data.
14121
14122 show
14123 unified command to show various repository information (EXPERIMENTAL)
14124
14125 This extension provides the hg show command, which provides a central
14126 command for displaying commonly-accessed repository data and views of
14127 that data.
14128
14129 The following config options can influence operation.
14130
14131 commands
14132 show.aliasprefix
14133
14134 List of strings that will register aliases for views. e.g. s
14135 will effectively set config options alias.s<view> = show <view>
14136 for all views. i.e. hg swork would execute hg show work.
14137
14138 Aliases that would conflict with existing registrations will not
14139 be performed.
14140
14141 Commands
14142 Change navigation
14143 show
14144 show various repository information:
14145
14146 hg show VIEW
14147
14148 A requested view of repository data is displayed.
14149
14150 If no view is requested, the list of available views is shown and the
14151 command aborts.
14152
14153 Note There are no backwards compatibility guarantees for the output
14154 of this command. Output may change in any future Mercurial re‐
14155 lease.
14156
14157 Consumers wanting stable command output should specify a tem‐
14158 plate via -T/--template.
14159
14160 List of available views:
14161
14162 bookmarks bookmarks and their associated changeset
14163
14164 stack current line of work
14165
14166 work changesets that aren't finished
14167
14168 Options:
14169
14170 -T,--template <TEMPLATE>
14171 display with template
14172
14173 sparse
14174 allow sparse checkouts of the working directory (EXPERIMENTAL)
14175
14176 (This extension is not yet protected by backwards compatibility guaran‐
14177 tees. Any aspect may break in future releases until this notice is re‐
14178 moved.)
14179
14180 This extension allows the working directory to only consist of a subset
14181 of files for the revision. This allows specific files or directories to
14182 be explicitly included or excluded. Many repository operations have
14183 performance proportional to the number of files in the working direc‐
14184 tory. So only realizing a subset of files in the working directory can
14185 improve performance.
14186
14187 Sparse Config Files
14188 The set of files that are part of a sparse checkout are defined by a
14189 sparse config file. The file defines 3 things: includes (files to in‐
14190 clude in the sparse checkout), excludes (files to exclude from the
14191 sparse checkout), and profiles (links to other config files).
14192
14193 The file format is newline delimited. Empty lines and lines beginning
14194 with # are ignored.
14195
14196 Lines beginning with %include `` denote another sparse config file to
14197 include. e.g. ``%include tests.sparse. The filename is relative to the
14198 repository root.
14199
14200 The special lines [include] and [exclude] denote the section for in‐
14201 cludes and excludes that follow, respectively. It is illegal to have
14202 [include] after [exclude].
14203
14204 Non-special lines resemble file patterns to be added to either includes
14205 or excludes. The syntax of these lines is documented by hg help pat‐
14206 terns. Patterns are interpreted as glob: by default and match against
14207 the root of the repository.
14208
14209 Exclusion patterns take precedence over inclusion patterns. So even if
14210 a file is explicitly included, an [exclude] entry can remove it.
14211
14212 For example, say you have a repository with 3 directories, frontend/,
14213 backend/, and tools/. frontend/ and backend/ correspond to different
14214 projects and it is uncommon for someone working on one to need the
14215 files for the other. But tools/ contains files shared between both
14216 projects. Your sparse config files may resemble:
14217
14218 # frontend.sparse
14219 frontend/**
14220 tools/**
14221
14222 # backend.sparse
14223 backend/**
14224 tools/**
14225
14226 Say the backend grows in size. Or there's a directory with thousands of
14227 files you wish to exclude. You can modify the profile to exclude cer‐
14228 tain files:
14229
14230 [include]
14231 backend/**
14232 tools/**
14233
14234 [exclude]
14235 tools/tests/**
14236
14237 Commands
14238 Uncategorized commands
14239 split
14240 command to split a changeset into smaller ones (EXPERIMENTAL)
14241
14242 Commands
14243 Change manipulation
14244 split
14245 split a changeset into smaller ones:
14246
14247 hg split [--no-rebase] [[-r] REV]
14248
14249 Repeatedly prompt changes and commit message for new changesets until
14250 there is nothing left in the original changeset.
14251
14252 If --rev was not given, split the working directory parent.
14253
14254 By default, rebase connected non-obsoleted descendants onto the new
14255 changeset. Use --no-rebase to avoid the rebase.
14256
14257 Options:
14258
14259 -r,--rev <REV>
14260 revision to split
14261
14262 --rebase
14263 rebase descendants after split (default: True)
14264
14265 -d,--date <DATE>
14266 record the specified date as commit date
14267
14268 -u,--user <USER>
14269 record the specified user as committer
14270
14271 sqlitestore
14272 store repository data in SQLite (EXPERIMENTAL)
14273
14274 The sqlitestore extension enables the storage of repository data in
14275 SQLite.
14276
14277 This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATI‐
14278 BILITY GUARANTEES. This means that repositories created with this ex‐
14279 tension may only be usable with the exact version of this exten‐
14280 sion/Mercurial that was used. The extension attempts to enforce this in
14281 order to prevent repository corruption.
14282
14283 In addition, several features are not yet supported or have known bugs:
14284
14285 • Only some data is stored in SQLite. Changeset, manifest, and other
14286 repository data is not yet stored in SQLite.
14287
14288 • Transactions are not robust. If the process is aborted at the right
14289 time during transaction close/rollback, the repository could be in an
14290 inconsistent state. This problem will diminish once all repository
14291 data is tracked by SQLite.
14292
14293 • Bundle repositories do not work (the ability to use e.g. hg -R <bun‐
14294 dle-file> log to automatically overlay a bundle on top of the exist‐
14295 ing repository).
14296
14297 • Various other features don't work.
14298
14299 This extension should work for basic clone/pull, update, and commit
14300 workflows. Some history rewriting operations may fail due to lack of
14301 support for bundle repositories.
14302
14303 To use, activate the extension and set the storage.new-repo-backend
14304 config option to sqlite to enable new repositories to use SQLite for
14305 storage.
14306
14307 strip
14308 strip changesets and their descendants from history (DEPRECATED)
14309
14310 The functionality of this extension has been included in core Mercurial
14311 since version 5.7. Please use hg debugstrip ... instead.
14312
14313 This extension allows you to strip changesets and all their descendants
14314 from the repository. See the command help for details.
14315
14316 transplant
14317 command to transplant changesets from another branch
14318
14319 This extension allows you to transplant changes to another parent revi‐
14320 sion, possibly in another repository. The transplant is done using
14321 'diff' patches.
14322
14323 Transplanted patches are recorded in .hg/transplant/transplants, as a
14324 map from a changeset hash to its hash in the source repository.
14325
14326 Commands
14327 Change manipulation
14328 transplant
14329 transplant changesets from another branch:
14330
14331 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
14332
14333 Selected changesets will be applied on top of the current working di‐
14334 rectory with the log of the original changeset. The changesets are
14335 copied and will thus appear twice in the history with different identi‐
14336 ties.
14337
14338 Consider using the graft command if everything is inside the same
14339 repository - it will use merges and will usually give a better result.
14340 Use the rebase extension if the changesets are unpublished and you want
14341 to move them instead of copying them.
14342
14343 If --log is specified, log messages will have a comment appended of the
14344 form:
14345
14346 (transplanted from CHANGESETHASH)
14347
14348 You can rewrite the changelog message with the --filter option. Its
14349 argument will be invoked with the current changelog message as $1 and
14350 the patch as $2.
14351
14352 --source/-s specifies another repository to use for selecting change‐
14353 sets, just as if it temporarily had been pulled. If --branch/-b is
14354 specified, these revisions will be used as heads when deciding which
14355 changesets to transplant, just as if only these revisions had been
14356 pulled. If --all/-a is specified, all the revisions up to the heads
14357 specified with --branch will be transplanted.
14358
14359 Example:
14360
14361 • transplant all changes up to REV on top of your current revision:
14362
14363 hg transplant --branch REV --all
14364
14365 You can optionally mark selected transplanted changesets as merge
14366 changesets. You will not be prompted to transplant any ancestors of a
14367 merged transplant, and you can merge descendants of them normally in‐
14368 stead of transplanting them.
14369
14370 Merge changesets may be transplanted directly by specifying the proper
14371 parent changeset by calling hg transplant --parent.
14372
14373 If no merges or revisions are provided, hg transplant will start an in‐
14374 teractive changeset browser.
14375
14376 If a changeset application fails, you can fix the merge by hand and
14377 then resume where you left off by calling hg transplant --continue/-c.
14378
14379 Options:
14380
14381 -s,--source <REPO>
14382 transplant changesets from REPO
14383
14384 -b,--branch <REV[+]>
14385 use this source changeset as head
14386
14387 -a, --all
14388 pull all changesets up to the --branch revisions
14389
14390 -p,--prune <REV[+]>
14391 skip over REV
14392
14393 -m,--merge <REV[+]>
14394 merge at REV
14395
14396 --parent <REV>
14397 parent to choose when transplanting merge
14398
14399 -e, --edit
14400 invoke editor on commit messages
14401
14402 --log append transplant info to log message
14403
14404 --stop stop interrupted transplant
14405
14406 -c, --continue
14407 continue last transplant session after fixing conflicts
14408
14409 --filter <CMD>
14410 filter changesets through command
14411
14412 [+] marked option can be specified multiple times
14413
14414 uncommit
14415 uncommit part or all of a local changeset (EXPERIMENTAL)
14416
14417 This command undoes the effect of a local commit, returning the af‐
14418 fected files to their uncommitted state. This means that files modi‐
14419 fied, added or removed in the changeset will be left unchanged, and so
14420 will remain modified, added and removed in the working directory.
14421
14422 Commands
14423 Change manipulation
14424 unamend
14425 undo the most recent amend operation on a current changeset:
14426
14427 hg unamend
14428
14429 This command will roll back to the previous version of a changeset,
14430 leaving working directory in state in which it was before running hg
14431 amend (e.g. files modified as part of an amend will be marked as modi‐
14432 fied hg status)
14433
14434 uncommit
14435 uncommit part or all of a local changeset:
14436
14437 hg uncommit [OPTION]... [FILE]...
14438
14439 This command undoes the effect of a local commit, returning the af‐
14440 fected files to their uncommitted state. This means that files modified
14441 or deleted in the changeset will be left unchanged, and so will remain
14442 modified in the working directory.
14443
14444 If no files are specified, the commit will be pruned, unless --keep is
14445 given.
14446
14447 Options:
14448
14449 --keep allow an empty commit after uncommitting
14450
14451 --allow-dirty-working-copy
14452 allow uncommit with outstanding changes
14453
14454 -n,--note <TEXT>
14455 store a note on uncommit
14456
14457 -I,--include <PATTERN[+]>
14458 include names matching the given patterns
14459
14460 -X,--exclude <PATTERN[+]>
14461 exclude names matching the given patterns
14462
14463 -m,--message <TEXT>
14464 use text as commit message
14465
14466 -l,--logfile <FILE>
14467 read commit message from file
14468
14469 -d,--date <DATE>
14470 record the specified date as commit date
14471
14472 -u,--user <USER>
14473 record the specified user as committer
14474
14475 -D, --currentdate
14476 record the current date as commit date
14477
14478 -U, --currentuser
14479 record the current user as committer
14480
14481 [+] marked option can be specified multiple times
14482
14483 win32mbcs
14484 allow the use of MBCS paths with problematic encodings
14485
14486 Some MBCS encodings are not good for some path operations (i.e. split‐
14487 ting path, case conversion, etc.) with its encoded bytes. We call such
14488 a encoding (i.e. shift_jis and big5) as "problematic encoding". This
14489 extension can be used to fix the issue with those encodings by wrapping
14490 some functions to convert to Unicode string before path operation.
14491
14492 This extension is useful for:
14493
14494 • Japanese Windows users using shift_jis encoding.
14495
14496 • Chinese Windows users using big5 encoding.
14497
14498 • All users who use a repository with one of problematic encodings on
14499 case-insensitive file system.
14500
14501 This extension is not needed for:
14502
14503 • Any user who use only ASCII chars in path.
14504
14505 • Any user who do not use any of problematic encodings.
14506
14507 Note that there are some limitations on using this extension:
14508
14509 • You should use single encoding in one repository.
14510
14511 • If the repository path ends with 0x5c, .hg/hgrc cannot be read.
14512
14513 • win32mbcs is not compatible with fixutf8 extension.
14514
14515 By default, win32mbcs uses encoding.encoding decided by Mercurial. You
14516 can specify the encoding by config option:
14517
14518 [win32mbcs]
14519 encoding = sjis
14520
14521 It is useful for the users who want to commit with UTF-8 log message.
14522
14523 win32text
14524 perform automatic newline conversion (DEPRECATED)
14525
14526 Deprecation: The win32text extension requires each user to configure
14527 the extension again and again for each clone since the configuration
14528 is not copied when cloning.
14529
14530 We have therefore made the eol as an alternative. The eol uses a
14531 version controlled file for its configuration and each clone will
14532 therefore use the right settings from the start.
14533
14534 To perform automatic newline conversion, use:
14535
14536 [extensions]
14537 win32text =
14538 [encode]
14539 ** = cleverencode:
14540 # or ** = macencode:
14541
14542 [decode]
14543 ** = cleverdecode:
14544 # or ** = macdecode:
14545
14546 If not doing conversion, to make sure you do not commit CRLF/CR by ac‐
14547 cident:
14548
14549 [hooks]
14550 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
14551 # or pretxncommit.cr = python:hgext.win32text.forbidcr
14552
14553 To do the same check on a server to prevent CRLF/CR from being pushed
14554 or pulled:
14555
14556 [hooks]
14557 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
14558 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
14559
14560 zeroconf
14561 discover and advertise repositories on the local network
14562
14563 The zeroconf extension will advertise hg serve instances over DNS-SD so
14564 that they can be discovered using the hg paths command without knowing
14565 the server's IP address.
14566
14567 To allow other people to discover your repository using run hg serve in
14568 your repository:
14569
14570 $ cd test
14571 $ hg serve
14572
14573 You can discover Zeroconf-enabled repositories by running hg paths:
14574
14575 $ hg paths
14576 zc-test = http://example.com:8000/test
14577
14579 /etc/mercurial/hgrc, $HOME/.hgrc, .hg/hgrc
14580
14581 This file contains defaults and configuration. Values in
14582 .hg/hgrc override those in $HOME/.hgrc, and these override set‐
14583 tings made in the global /etc/mercurial/hgrc configuration. See
14584 hgrc(5) for details of the contents and format of these files.
14585
14586 .hgignore
14587
14588 This file contains regular expressions (one per line) that de‐
14589 scribe file names that should be ignored by hg. For details, see
14590 hgignore(5).
14591
14592 .hgsub
14593
14594 This file defines the locations of all subrepositories, and
14595 tells where the subrepository checkouts came from. For details,
14596 see hg help subrepos.
14597
14598 .hgsubstate
14599
14600 This file is where Mercurial stores all nested repository
14601 states. NB: This file should not be edited manually.
14602
14603 .hgtags
14604
14605 This file contains changeset hash values and text tag names (one
14606 of each separated by spaces) that correspond to tagged versions
14607 of the repository contents. The file content is encoded using
14608 UTF-8.
14609
14610 .hg/last-message.txt
14611
14612 This file is used by hg commit to store a backup of the commit
14613 message in case the commit fails.
14614
14615 .hg/localtags
14616
14617 This file can be used to define local tags which are not shared
14618 among repositories. The file format is the same as for .hgtags,
14619 but it is encoded using the local system encoding.
14620
14621 Some commands (e.g. revert) produce backup files ending in .orig, if
14622 the .orig file already exists and is not tracked by Mercurial, it will
14623 be overwritten.
14624
14626 Probably lots, please post them to the mailing list (see Resources
14627 below) when you find them.
14628
14630 hgignore(5), hgrc(5)
14631
14633 Written by Olivia Mackall <olivia@selenic.com>
14634
14636 Main Web Site: https://mercurial-scm.org/
14637
14638 Source code repository: https://www.mercurial-scm.org/repo/hg
14639
14640 Mailing list: https://www.mercurial-scm.org/mailman/listinfo/mercurial/
14641
14643 Copyright (C) 2005-2023 Olivia Mackall. Free use of this software is
14644 granted under the terms of the GNU General Public License version 2 or
14645 any later version.
14646
14648 Olivia Mackall <olivia@selenic.com>
14649
14650 Organization: Mercurial
14651
14652
14653
14654
14655 HG(1)