##// END OF EJS Templates
doc: point to the main share-safe doc in the "mismatch" config...
marmoute -
r47076:5249ac2b stable
parent child Browse files
Show More
@@ -1,3060 +1,3066 b''
1 1 The Mercurial system uses a set of configuration files to control
2 2 aspects of its behavior.
3 3
4 4 Troubleshooting
5 5 ===============
6 6
7 7 If you're having problems with your configuration,
8 8 :hg:`config --debug` can help you understand what is introducing
9 9 a setting into your environment.
10 10
11 11 See :hg:`help config.syntax` and :hg:`help config.files`
12 12 for information about how and where to override things.
13 13
14 14 Structure
15 15 =========
16 16
17 17 The configuration files use a simple ini-file format. A configuration
18 18 file consists of sections, led by a ``[section]`` header and followed
19 19 by ``name = value`` entries::
20 20
21 21 [ui]
22 22 username = Firstname Lastname <firstname.lastname@example.net>
23 23 verbose = True
24 24
25 25 The above entries will be referred to as ``ui.username`` and
26 26 ``ui.verbose``, respectively. See :hg:`help config.syntax`.
27 27
28 28 Files
29 29 =====
30 30
31 31 Mercurial reads configuration data from several files, if they exist.
32 32 These files do not exist by default and you will have to create the
33 33 appropriate configuration files yourself:
34 34
35 35 Local configuration is put into the per-repository ``<repo>/.hg/hgrc`` file.
36 36
37 37 Global configuration like the username setting is typically put into:
38 38
39 39 .. container:: windows
40 40
41 41 - ``%USERPROFILE%\mercurial.ini`` (on Windows)
42 42
43 43 .. container:: unix.plan9
44 44
45 45 - ``$HOME/.hgrc`` (on Unix, Plan9)
46 46
47 47 The names of these files depend on the system on which Mercurial is
48 48 installed. ``*.rc`` files from a single directory are read in
49 49 alphabetical order, later ones overriding earlier ones. Where multiple
50 50 paths are given below, settings from earlier paths override later
51 51 ones.
52 52
53 53 .. container:: verbose.unix
54 54
55 55 On Unix, the following files are consulted:
56 56
57 57 - ``<repo>/.hg/hgrc-not-shared`` (per-repository)
58 58 - ``<repo>/.hg/hgrc`` (per-repository)
59 59 - ``$HOME/.hgrc`` (per-user)
60 60 - ``${XDG_CONFIG_HOME:-$HOME/.config}/hg/hgrc`` (per-user)
61 61 - ``<install-root>/etc/mercurial/hgrc`` (per-installation)
62 62 - ``<install-root>/etc/mercurial/hgrc.d/*.rc`` (per-installation)
63 63 - ``/etc/mercurial/hgrc`` (per-system)
64 64 - ``/etc/mercurial/hgrc.d/*.rc`` (per-system)
65 65 - ``<internal>/*.rc`` (defaults)
66 66
67 67 .. container:: verbose.windows
68 68
69 69 On Windows, the following files are consulted:
70 70
71 71 - ``<repo>/.hg/hgrc-not-shared`` (per-repository)
72 72 - ``<repo>/.hg/hgrc`` (per-repository)
73 73 - ``%USERPROFILE%\.hgrc`` (per-user)
74 74 - ``%USERPROFILE%\Mercurial.ini`` (per-user)
75 75 - ``%HOME%\.hgrc`` (per-user)
76 76 - ``%HOME%\Mercurial.ini`` (per-user)
77 77 - ``HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial`` (per-system)
78 78 - ``<install-dir>\hgrc.d\*.rc`` (per-installation)
79 79 - ``<install-dir>\Mercurial.ini`` (per-installation)
80 80 - ``%PROGRAMDATA%\Mercurial\hgrc`` (per-system)
81 81 - ``%PROGRAMDATA%\Mercurial\Mercurial.ini`` (per-system)
82 82 - ``%PROGRAMDATA%\Mercurial\hgrc.d\*.rc`` (per-system)
83 83 - ``<internal>/*.rc`` (defaults)
84 84
85 85 .. note::
86 86
87 87 The registry key ``HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Mercurial``
88 88 is used when running 32-bit Python on 64-bit Windows.
89 89
90 90 .. container:: verbose.plan9
91 91
92 92 On Plan9, the following files are consulted:
93 93
94 94 - ``<repo>/.hg/hgrc-not-shared`` (per-repository)
95 95 - ``<repo>/.hg/hgrc`` (per-repository)
96 96 - ``$home/lib/hgrc`` (per-user)
97 97 - ``<install-root>/lib/mercurial/hgrc`` (per-installation)
98 98 - ``<install-root>/lib/mercurial/hgrc.d/*.rc`` (per-installation)
99 99 - ``/lib/mercurial/hgrc`` (per-system)
100 100 - ``/lib/mercurial/hgrc.d/*.rc`` (per-system)
101 101 - ``<internal>/*.rc`` (defaults)
102 102
103 103 Per-repository configuration options only apply in a
104 104 particular repository. This file is not version-controlled, and
105 105 will not get transferred during a "clone" operation. Options in
106 106 this file override options in all other configuration files.
107 107
108 108 .. container:: unix.plan9
109 109
110 110 On Plan 9 and Unix, most of this file will be ignored if it doesn't
111 111 belong to a trusted user or to a trusted group. See
112 112 :hg:`help config.trusted` for more details.
113 113
114 114 Per-user configuration file(s) are for the user running Mercurial. Options
115 115 in these files apply to all Mercurial commands executed by this user in any
116 116 directory. Options in these files override per-system and per-installation
117 117 options.
118 118
119 119 Per-installation configuration files are searched for in the
120 120 directory where Mercurial is installed. ``<install-root>`` is the
121 121 parent directory of the **hg** executable (or symlink) being run.
122 122
123 123 .. container:: unix.plan9
124 124
125 125 For example, if installed in ``/shared/tools/bin/hg``, Mercurial
126 126 will look in ``/shared/tools/etc/mercurial/hgrc``. Options in these
127 127 files apply to all Mercurial commands executed by any user in any
128 128 directory.
129 129
130 130 Per-installation configuration files are for the system on
131 131 which Mercurial is running. Options in these files apply to all
132 132 Mercurial commands executed by any user in any directory. Registry
133 133 keys contain PATH-like strings, every part of which must reference
134 134 a ``Mercurial.ini`` file or be a directory where ``*.rc`` files will
135 135 be read. Mercurial checks each of these locations in the specified
136 136 order until one or more configuration files are detected.
137 137
138 138 Per-system configuration files are for the system on which Mercurial
139 139 is running. Options in these files apply to all Mercurial commands
140 140 executed by any user in any directory. Options in these files
141 141 override per-installation options.
142 142
143 143 Mercurial comes with some default configuration. The default configuration
144 144 files are installed with Mercurial and will be overwritten on upgrades. Default
145 145 configuration files should never be edited by users or administrators but can
146 146 be overridden in other configuration files. So far the directory only contains
147 147 merge tool configuration but packagers can also put other default configuration
148 148 there.
149 149
150 150 On versions 5.7 and later, if share-safe functionality is enabled,
151 151 shares will read config file of share source too.
152 152 `<share-source/.hg/hgrc>` is read before reading `<repo/.hg/hgrc>`.
153 153
154 154 For configs which should not be shared, `<repo/.hg/hgrc-not-shared>`
155 155 should be used.
156 156
157 157 Syntax
158 158 ======
159 159
160 160 A configuration file consists of sections, led by a ``[section]`` header
161 161 and followed by ``name = value`` entries (sometimes called
162 162 ``configuration keys``)::
163 163
164 164 [spam]
165 165 eggs=ham
166 166 green=
167 167 eggs
168 168
169 169 Each line contains one entry. If the lines that follow are indented,
170 170 they are treated as continuations of that entry. Leading whitespace is
171 171 removed from values. Empty lines are skipped. Lines beginning with
172 172 ``#`` or ``;`` are ignored and may be used to provide comments.
173 173
174 174 Configuration keys can be set multiple times, in which case Mercurial
175 175 will use the value that was configured last. As an example::
176 176
177 177 [spam]
178 178 eggs=large
179 179 ham=serrano
180 180 eggs=small
181 181
182 182 This would set the configuration key named ``eggs`` to ``small``.
183 183
184 184 It is also possible to define a section multiple times. A section can
185 185 be redefined on the same and/or on different configuration files. For
186 186 example::
187 187
188 188 [foo]
189 189 eggs=large
190 190 ham=serrano
191 191 eggs=small
192 192
193 193 [bar]
194 194 eggs=ham
195 195 green=
196 196 eggs
197 197
198 198 [foo]
199 199 ham=prosciutto
200 200 eggs=medium
201 201 bread=toasted
202 202
203 203 This would set the ``eggs``, ``ham``, and ``bread`` configuration keys
204 204 of the ``foo`` section to ``medium``, ``prosciutto``, and ``toasted``,
205 205 respectively. As you can see there only thing that matters is the last
206 206 value that was set for each of the configuration keys.
207 207
208 208 If a configuration key is set multiple times in different
209 209 configuration files the final value will depend on the order in which
210 210 the different configuration files are read, with settings from earlier
211 211 paths overriding later ones as described on the ``Files`` section
212 212 above.
213 213
214 214 A line of the form ``%include file`` will include ``file`` into the
215 215 current configuration file. The inclusion is recursive, which means
216 216 that included files can include other files. Filenames are relative to
217 217 the configuration file in which the ``%include`` directive is found.
218 218 Environment variables and ``~user`` constructs are expanded in
219 219 ``file``. This lets you do something like::
220 220
221 221 %include ~/.hgrc.d/$HOST.rc
222 222
223 223 to include a different configuration file on each computer you use.
224 224
225 225 A line with ``%unset name`` will remove ``name`` from the current
226 226 section, if it has been set previously.
227 227
228 228 The values are either free-form text strings, lists of text strings,
229 229 or Boolean values. Boolean values can be set to true using any of "1",
230 230 "yes", "true", or "on" and to false using "0", "no", "false", or "off"
231 231 (all case insensitive).
232 232
233 233 List values are separated by whitespace or comma, except when values are
234 234 placed in double quotation marks::
235 235
236 236 allow_read = "John Doe, PhD", brian, betty
237 237
238 238 Quotation marks can be escaped by prefixing them with a backslash. Only
239 239 quotation marks at the beginning of a word is counted as a quotation
240 240 (e.g., ``foo"bar baz`` is the list of ``foo"bar`` and ``baz``).
241 241
242 242 Sections
243 243 ========
244 244
245 245 This section describes the different sections that may appear in a
246 246 Mercurial configuration file, the purpose of each section, its possible
247 247 keys, and their possible values.
248 248
249 249 ``alias``
250 250 ---------
251 251
252 252 Defines command aliases.
253 253
254 254 Aliases allow you to define your own commands in terms of other
255 255 commands (or aliases), optionally including arguments. Positional
256 256 arguments in the form of ``$1``, ``$2``, etc. in the alias definition
257 257 are expanded by Mercurial before execution. Positional arguments not
258 258 already used by ``$N`` in the definition are put at the end of the
259 259 command to be executed.
260 260
261 261 Alias definitions consist of lines of the form::
262 262
263 263 <alias> = <command> [<argument>]...
264 264
265 265 For example, this definition::
266 266
267 267 latest = log --limit 5
268 268
269 269 creates a new command ``latest`` that shows only the five most recent
270 270 changesets. You can define subsequent aliases using earlier ones::
271 271
272 272 stable5 = latest -b stable
273 273
274 274 .. note::
275 275
276 276 It is possible to create aliases with the same names as
277 277 existing commands, which will then override the original
278 278 definitions. This is almost always a bad idea!
279 279
280 280 An alias can start with an exclamation point (``!``) to make it a
281 281 shell alias. A shell alias is executed with the shell and will let you
282 282 run arbitrary commands. As an example, ::
283 283
284 284 echo = !echo $@
285 285
286 286 will let you do ``hg echo foo`` to have ``foo`` printed in your
287 287 terminal. A better example might be::
288 288
289 289 purge = !$HG status --no-status --unknown -0 re: | xargs -0 rm -f
290 290
291 291 which will make ``hg purge`` delete all unknown files in the
292 292 repository in the same manner as the purge extension.
293 293
294 294 Positional arguments like ``$1``, ``$2``, etc. in the alias definition
295 295 expand to the command arguments. Unmatched arguments are
296 296 removed. ``$0`` expands to the alias name and ``$@`` expands to all
297 297 arguments separated by a space. ``"$@"`` (with quotes) expands to all
298 298 arguments quoted individually and separated by a space. These expansions
299 299 happen before the command is passed to the shell.
300 300
301 301 Shell aliases are executed in an environment where ``$HG`` expands to
302 302 the path of the Mercurial that was used to execute the alias. This is
303 303 useful when you want to call further Mercurial commands in a shell
304 304 alias, as was done above for the purge alias. In addition,
305 305 ``$HG_ARGS`` expands to the arguments given to Mercurial. In the ``hg
306 306 echo foo`` call above, ``$HG_ARGS`` would expand to ``echo foo``.
307 307
308 308 .. note::
309 309
310 310 Some global configuration options such as ``-R`` are
311 311 processed before shell aliases and will thus not be passed to
312 312 aliases.
313 313
314 314
315 315 ``annotate``
316 316 ------------
317 317
318 318 Settings used when displaying file annotations. All values are
319 319 Booleans and default to False. See :hg:`help config.diff` for
320 320 related options for the diff command.
321 321
322 322 ``ignorews``
323 323 Ignore white space when comparing lines.
324 324
325 325 ``ignorewseol``
326 326 Ignore white space at the end of a line when comparing lines.
327 327
328 328 ``ignorewsamount``
329 329 Ignore changes in the amount of white space.
330 330
331 331 ``ignoreblanklines``
332 332 Ignore changes whose lines are all blank.
333 333
334 334
335 335 ``auth``
336 336 --------
337 337
338 338 Authentication credentials and other authentication-like configuration
339 339 for HTTP connections. This section allows you to store usernames and
340 340 passwords for use when logging *into* HTTP servers. See
341 341 :hg:`help config.web` if you want to configure *who* can login to
342 342 your HTTP server.
343 343
344 344 The following options apply to all hosts.
345 345
346 346 ``cookiefile``
347 347 Path to a file containing HTTP cookie lines. Cookies matching a
348 348 host will be sent automatically.
349 349
350 350 The file format uses the Mozilla cookies.txt format, which defines cookies
351 351 on their own lines. Each line contains 7 fields delimited by the tab
352 352 character (domain, is_domain_cookie, path, is_secure, expires, name,
353 353 value). For more info, do an Internet search for "Netscape cookies.txt
354 354 format."
355 355
356 356 Note: the cookies parser does not handle port numbers on domains. You
357 357 will need to remove ports from the domain for the cookie to be recognized.
358 358 This could result in a cookie being disclosed to an unwanted server.
359 359
360 360 The cookies file is read-only.
361 361
362 362 Other options in this section are grouped by name and have the following
363 363 format::
364 364
365 365 <name>.<argument> = <value>
366 366
367 367 where ``<name>`` is used to group arguments into authentication
368 368 entries. Example::
369 369
370 370 foo.prefix = hg.intevation.de/mercurial
371 371 foo.username = foo
372 372 foo.password = bar
373 373 foo.schemes = http https
374 374
375 375 bar.prefix = secure.example.org
376 376 bar.key = path/to/file.key
377 377 bar.cert = path/to/file.cert
378 378 bar.schemes = https
379 379
380 380 Supported arguments:
381 381
382 382 ``prefix``
383 383 Either ``*`` or a URI prefix with or without the scheme part.
384 384 The authentication entry with the longest matching prefix is used
385 385 (where ``*`` matches everything and counts as a match of length
386 386 1). If the prefix doesn't include a scheme, the match is performed
387 387 against the URI with its scheme stripped as well, and the schemes
388 388 argument, q.v., is then subsequently consulted.
389 389
390 390 ``username``
391 391 Optional. Username to authenticate with. If not given, and the
392 392 remote site requires basic or digest authentication, the user will
393 393 be prompted for it. Environment variables are expanded in the
394 394 username letting you do ``foo.username = $USER``. If the URI
395 395 includes a username, only ``[auth]`` entries with a matching
396 396 username or without a username will be considered.
397 397
398 398 ``password``
399 399 Optional. Password to authenticate with. If not given, and the
400 400 remote site requires basic or digest authentication, the user
401 401 will be prompted for it.
402 402
403 403 ``key``
404 404 Optional. PEM encoded client certificate key file. Environment
405 405 variables are expanded in the filename.
406 406
407 407 ``cert``
408 408 Optional. PEM encoded client certificate chain file. Environment
409 409 variables are expanded in the filename.
410 410
411 411 ``schemes``
412 412 Optional. Space separated list of URI schemes to use this
413 413 authentication entry with. Only used if the prefix doesn't include
414 414 a scheme. Supported schemes are http and https. They will match
415 415 static-http and static-https respectively, as well.
416 416 (default: https)
417 417
418 418 If no suitable authentication entry is found, the user is prompted
419 419 for credentials as usual if required by the remote.
420 420
421 421 ``cmdserver``
422 422 -------------
423 423
424 424 Controls command server settings. (ADVANCED)
425 425
426 426 ``message-encodings``
427 427 List of encodings for the ``m`` (message) channel. The first encoding
428 428 supported by the server will be selected and advertised in the hello
429 429 message. This is useful only when ``ui.message-output`` is set to
430 430 ``channel``. Supported encodings are ``cbor``.
431 431
432 432 ``shutdown-on-interrupt``
433 433 If set to false, the server's main loop will continue running after
434 434 SIGINT received. ``runcommand`` requests can still be interrupted by
435 435 SIGINT. Close the write end of the pipe to shut down the server
436 436 process gracefully.
437 437 (default: True)
438 438
439 439 ``color``
440 440 ---------
441 441
442 442 Configure the Mercurial color mode. For details about how to define your custom
443 443 effect and style see :hg:`help color`.
444 444
445 445 ``mode``
446 446 String: control the method used to output color. One of ``auto``, ``ansi``,
447 447 ``win32``, ``terminfo`` or ``debug``. In auto mode, Mercurial will
448 448 use ANSI mode by default (or win32 mode prior to Windows 10) if it detects a
449 449 terminal. Any invalid value will disable color.
450 450
451 451 ``pagermode``
452 452 String: optional override of ``color.mode`` used with pager.
453 453
454 454 On some systems, terminfo mode may cause problems when using
455 455 color with ``less -R`` as a pager program. less with the -R option
456 456 will only display ECMA-48 color codes, and terminfo mode may sometimes
457 457 emit codes that less doesn't understand. You can work around this by
458 458 either using ansi mode (or auto mode), or by using less -r (which will
459 459 pass through all terminal control codes, not just color control
460 460 codes).
461 461
462 462 On some systems (such as MSYS in Windows), the terminal may support
463 463 a different color mode than the pager program.
464 464
465 465 ``commands``
466 466 ------------
467 467
468 468 ``commit.post-status``
469 469 Show status of files in the working directory after successful commit.
470 470 (default: False)
471 471
472 472 ``merge.require-rev``
473 473 Require that the revision to merge the current commit with be specified on
474 474 the command line. If this is enabled and a revision is not specified, the
475 475 command aborts.
476 476 (default: False)
477 477
478 478 ``push.require-revs``
479 479 Require revisions to push be specified using one or more mechanisms such as
480 480 specifying them positionally on the command line, using ``-r``, ``-b``,
481 481 and/or ``-B`` on the command line, or using ``paths.<path>:pushrev`` in the
482 482 configuration. If this is enabled and revisions are not specified, the
483 483 command aborts.
484 484 (default: False)
485 485
486 486 ``resolve.confirm``
487 487 Confirm before performing action if no filename is passed.
488 488 (default: False)
489 489
490 490 ``resolve.explicit-re-merge``
491 491 Require uses of ``hg resolve`` to specify which action it should perform,
492 492 instead of re-merging files by default.
493 493 (default: False)
494 494
495 495 ``resolve.mark-check``
496 496 Determines what level of checking :hg:`resolve --mark` will perform before
497 497 marking files as resolved. Valid values are ``none`, ``warn``, and
498 498 ``abort``. ``warn`` will output a warning listing the file(s) that still
499 499 have conflict markers in them, but will still mark everything resolved.
500 500 ``abort`` will output the same warning but will not mark things as resolved.
501 501 If --all is passed and this is set to ``abort``, only a warning will be
502 502 shown (an error will not be raised).
503 503 (default: ``none``)
504 504
505 505 ``status.relative``
506 506 Make paths in :hg:`status` output relative to the current directory.
507 507 (default: False)
508 508
509 509 ``status.terse``
510 510 Default value for the --terse flag, which condenses status output.
511 511 (default: empty)
512 512
513 513 ``update.check``
514 514 Determines what level of checking :hg:`update` will perform before moving
515 515 to a destination revision. Valid values are ``abort``, ``none``,
516 516 ``linear``, and ``noconflict``. ``abort`` always fails if the working
517 517 directory has uncommitted changes. ``none`` performs no checking, and may
518 518 result in a merge with uncommitted changes. ``linear`` allows any update
519 519 as long as it follows a straight line in the revision history, and may
520 520 trigger a merge with uncommitted changes. ``noconflict`` will allow any
521 521 update which would not trigger a merge with uncommitted changes, if any
522 522 are present.
523 523 (default: ``linear``)
524 524
525 525 ``update.requiredest``
526 526 Require that the user pass a destination when running :hg:`update`.
527 527 For example, :hg:`update .::` will be allowed, but a plain :hg:`update`
528 528 will be disallowed.
529 529 (default: False)
530 530
531 531 ``committemplate``
532 532 ------------------
533 533
534 534 ``changeset``
535 535 String: configuration in this section is used as the template to
536 536 customize the text shown in the editor when committing.
537 537
538 538 In addition to pre-defined template keywords, commit log specific one
539 539 below can be used for customization:
540 540
541 541 ``extramsg``
542 542 String: Extra message (typically 'Leave message empty to abort
543 543 commit.'). This may be changed by some commands or extensions.
544 544
545 545 For example, the template configuration below shows as same text as
546 546 one shown by default::
547 547
548 548 [committemplate]
549 549 changeset = {desc}\n\n
550 550 HG: Enter commit message. Lines beginning with 'HG:' are removed.
551 551 HG: {extramsg}
552 552 HG: --
553 553 HG: user: {author}\n{ifeq(p2rev, "-1", "",
554 554 "HG: branch merge\n")
555 555 }HG: branch '{branch}'\n{if(activebookmark,
556 556 "HG: bookmark '{activebookmark}'\n") }{subrepos %
557 557 "HG: subrepo {subrepo}\n" }{file_adds %
558 558 "HG: added {file}\n" }{file_mods %
559 559 "HG: changed {file}\n" }{file_dels %
560 560 "HG: removed {file}\n" }{if(files, "",
561 561 "HG: no files changed\n")}
562 562
563 563 ``diff()``
564 564 String: show the diff (see :hg:`help templates` for detail)
565 565
566 566 Sometimes it is helpful to show the diff of the changeset in the editor without
567 567 having to prefix 'HG: ' to each line so that highlighting works correctly. For
568 568 this, Mercurial provides a special string which will ignore everything below
569 569 it::
570 570
571 571 HG: ------------------------ >8 ------------------------
572 572
573 573 For example, the template configuration below will show the diff below the
574 574 extra message::
575 575
576 576 [committemplate]
577 577 changeset = {desc}\n\n
578 578 HG: Enter commit message. Lines beginning with 'HG:' are removed.
579 579 HG: {extramsg}
580 580 HG: ------------------------ >8 ------------------------
581 581 HG: Do not touch the line above.
582 582 HG: Everything below will be removed.
583 583 {diff()}
584 584
585 585 .. note::
586 586
587 587 For some problematic encodings (see :hg:`help win32mbcs` for
588 588 detail), this customization should be configured carefully, to
589 589 avoid showing broken characters.
590 590
591 591 For example, if a multibyte character ending with backslash (0x5c) is
592 592 followed by the ASCII character 'n' in the customized template,
593 593 the sequence of backslash and 'n' is treated as line-feed unexpectedly
594 594 (and the multibyte character is broken, too).
595 595
596 596 Customized template is used for commands below (``--edit`` may be
597 597 required):
598 598
599 599 - :hg:`backout`
600 600 - :hg:`commit`
601 601 - :hg:`fetch` (for merge commit only)
602 602 - :hg:`graft`
603 603 - :hg:`histedit`
604 604 - :hg:`import`
605 605 - :hg:`qfold`, :hg:`qnew` and :hg:`qrefresh`
606 606 - :hg:`rebase`
607 607 - :hg:`shelve`
608 608 - :hg:`sign`
609 609 - :hg:`tag`
610 610 - :hg:`transplant`
611 611
612 612 Configuring items below instead of ``changeset`` allows showing
613 613 customized message only for specific actions, or showing different
614 614 messages for each action.
615 615
616 616 - ``changeset.backout`` for :hg:`backout`
617 617 - ``changeset.commit.amend.merge`` for :hg:`commit --amend` on merges
618 618 - ``changeset.commit.amend.normal`` for :hg:`commit --amend` on other
619 619 - ``changeset.commit.normal.merge`` for :hg:`commit` on merges
620 620 - ``changeset.commit.normal.normal`` for :hg:`commit` on other
621 621 - ``changeset.fetch`` for :hg:`fetch` (impling merge commit)
622 622 - ``changeset.gpg.sign`` for :hg:`sign`
623 623 - ``changeset.graft`` for :hg:`graft`
624 624 - ``changeset.histedit.edit`` for ``edit`` of :hg:`histedit`
625 625 - ``changeset.histedit.fold`` for ``fold`` of :hg:`histedit`
626 626 - ``changeset.histedit.mess`` for ``mess`` of :hg:`histedit`
627 627 - ``changeset.histedit.pick`` for ``pick`` of :hg:`histedit`
628 628 - ``changeset.import.bypass`` for :hg:`import --bypass`
629 629 - ``changeset.import.normal.merge`` for :hg:`import` on merges
630 630 - ``changeset.import.normal.normal`` for :hg:`import` on other
631 631 - ``changeset.mq.qnew`` for :hg:`qnew`
632 632 - ``changeset.mq.qfold`` for :hg:`qfold`
633 633 - ``changeset.mq.qrefresh`` for :hg:`qrefresh`
634 634 - ``changeset.rebase.collapse`` for :hg:`rebase --collapse`
635 635 - ``changeset.rebase.merge`` for :hg:`rebase` on merges
636 636 - ``changeset.rebase.normal`` for :hg:`rebase` on other
637 637 - ``changeset.shelve.shelve`` for :hg:`shelve`
638 638 - ``changeset.tag.add`` for :hg:`tag` without ``--remove``
639 639 - ``changeset.tag.remove`` for :hg:`tag --remove`
640 640 - ``changeset.transplant.merge`` for :hg:`transplant` on merges
641 641 - ``changeset.transplant.normal`` for :hg:`transplant` on other
642 642
643 643 These dot-separated lists of names are treated as hierarchical ones.
644 644 For example, ``changeset.tag.remove`` customizes the commit message
645 645 only for :hg:`tag --remove`, but ``changeset.tag`` customizes the
646 646 commit message for :hg:`tag` regardless of ``--remove`` option.
647 647
648 648 When the external editor is invoked for a commit, the corresponding
649 649 dot-separated list of names without the ``changeset.`` prefix
650 650 (e.g. ``commit.normal.normal``) is in the ``HGEDITFORM`` environment
651 651 variable.
652 652
653 653 In this section, items other than ``changeset`` can be referred from
654 654 others. For example, the configuration to list committed files up
655 655 below can be referred as ``{listupfiles}``::
656 656
657 657 [committemplate]
658 658 listupfiles = {file_adds %
659 659 "HG: added {file}\n" }{file_mods %
660 660 "HG: changed {file}\n" }{file_dels %
661 661 "HG: removed {file}\n" }{if(files, "",
662 662 "HG: no files changed\n")}
663 663
664 664 ``decode/encode``
665 665 -----------------
666 666
667 667 Filters for transforming files on checkout/checkin. This would
668 668 typically be used for newline processing or other
669 669 localization/canonicalization of files.
670 670
671 671 Filters consist of a filter pattern followed by a filter command.
672 672 Filter patterns are globs by default, rooted at the repository root.
673 673 For example, to match any file ending in ``.txt`` in the root
674 674 directory only, use the pattern ``*.txt``. To match any file ending
675 675 in ``.c`` anywhere in the repository, use the pattern ``**.c``.
676 676 For each file only the first matching filter applies.
677 677
678 678 The filter command can start with a specifier, either ``pipe:`` or
679 679 ``tempfile:``. If no specifier is given, ``pipe:`` is used by default.
680 680
681 681 A ``pipe:`` command must accept data on stdin and return the transformed
682 682 data on stdout.
683 683
684 684 Pipe example::
685 685
686 686 [encode]
687 687 # uncompress gzip files on checkin to improve delta compression
688 688 # note: not necessarily a good idea, just an example
689 689 *.gz = pipe: gunzip
690 690
691 691 [decode]
692 692 # recompress gzip files when writing them to the working dir (we
693 693 # can safely omit "pipe:", because it's the default)
694 694 *.gz = gzip
695 695
696 696 A ``tempfile:`` command is a template. The string ``INFILE`` is replaced
697 697 with the name of a temporary file that contains the data to be
698 698 filtered by the command. The string ``OUTFILE`` is replaced with the name
699 699 of an empty temporary file, where the filtered data must be written by
700 700 the command.
701 701
702 702 .. container:: windows
703 703
704 704 .. note::
705 705
706 706 The tempfile mechanism is recommended for Windows systems,
707 707 where the standard shell I/O redirection operators often have
708 708 strange effects and may corrupt the contents of your files.
709 709
710 710 This filter mechanism is used internally by the ``eol`` extension to
711 711 translate line ending characters between Windows (CRLF) and Unix (LF)
712 712 format. We suggest you use the ``eol`` extension for convenience.
713 713
714 714
715 715 ``defaults``
716 716 ------------
717 717
718 718 (defaults are deprecated. Don't use them. Use aliases instead.)
719 719
720 720 Use the ``[defaults]`` section to define command defaults, i.e. the
721 721 default options/arguments to pass to the specified commands.
722 722
723 723 The following example makes :hg:`log` run in verbose mode, and
724 724 :hg:`status` show only the modified files, by default::
725 725
726 726 [defaults]
727 727 log = -v
728 728 status = -m
729 729
730 730 The actual commands, instead of their aliases, must be used when
731 731 defining command defaults. The command defaults will also be applied
732 732 to the aliases of the commands defined.
733 733
734 734
735 735 ``diff``
736 736 --------
737 737
738 738 Settings used when displaying diffs. Everything except for ``unified``
739 739 is a Boolean and defaults to False. See :hg:`help config.annotate`
740 740 for related options for the annotate command.
741 741
742 742 ``git``
743 743 Use git extended diff format.
744 744
745 745 ``nobinary``
746 746 Omit git binary patches.
747 747
748 748 ``nodates``
749 749 Don't include dates in diff headers.
750 750
751 751 ``noprefix``
752 752 Omit 'a/' and 'b/' prefixes from filenames. Ignored in plain mode.
753 753
754 754 ``showfunc``
755 755 Show which function each change is in.
756 756
757 757 ``ignorews``
758 758 Ignore white space when comparing lines.
759 759
760 760 ``ignorewsamount``
761 761 Ignore changes in the amount of white space.
762 762
763 763 ``ignoreblanklines``
764 764 Ignore changes whose lines are all blank.
765 765
766 766 ``unified``
767 767 Number of lines of context to show.
768 768
769 769 ``word-diff``
770 770 Highlight changed words.
771 771
772 772 ``email``
773 773 ---------
774 774
775 775 Settings for extensions that send email messages.
776 776
777 777 ``from``
778 778 Optional. Email address to use in "From" header and SMTP envelope
779 779 of outgoing messages.
780 780
781 781 ``to``
782 782 Optional. Comma-separated list of recipients' email addresses.
783 783
784 784 ``cc``
785 785 Optional. Comma-separated list of carbon copy recipients'
786 786 email addresses.
787 787
788 788 ``bcc``
789 789 Optional. Comma-separated list of blind carbon copy recipients'
790 790 email addresses.
791 791
792 792 ``method``
793 793 Optional. Method to use to send email messages. If value is ``smtp``
794 794 (default), use SMTP (see the ``[smtp]`` section for configuration).
795 795 Otherwise, use as name of program to run that acts like sendmail
796 796 (takes ``-f`` option for sender, list of recipients on command line,
797 797 message on stdin). Normally, setting this to ``sendmail`` or
798 798 ``/usr/sbin/sendmail`` is enough to use sendmail to send messages.
799 799
800 800 ``charsets``
801 801 Optional. Comma-separated list of character sets considered
802 802 convenient for recipients. Addresses, headers, and parts not
803 803 containing patches of outgoing messages will be encoded in the
804 804 first character set to which conversion from local encoding
805 805 (``$HGENCODING``, ``ui.fallbackencoding``) succeeds. If correct
806 806 conversion fails, the text in question is sent as is.
807 807 (default: '')
808 808
809 809 Order of outgoing email character sets:
810 810
811 811 1. ``us-ascii``: always first, regardless of settings
812 812 2. ``email.charsets``: in order given by user
813 813 3. ``ui.fallbackencoding``: if not in email.charsets
814 814 4. ``$HGENCODING``: if not in email.charsets
815 815 5. ``utf-8``: always last, regardless of settings
816 816
817 817 Email example::
818 818
819 819 [email]
820 820 from = Joseph User <joe.user@example.com>
821 821 method = /usr/sbin/sendmail
822 822 # charsets for western Europeans
823 823 # us-ascii, utf-8 omitted, as they are tried first and last
824 824 charsets = iso-8859-1, iso-8859-15, windows-1252
825 825
826 826
827 827 ``extensions``
828 828 --------------
829 829
830 830 Mercurial has an extension mechanism for adding new features. To
831 831 enable an extension, create an entry for it in this section.
832 832
833 833 If you know that the extension is already in Python's search path,
834 834 you can give the name of the module, followed by ``=``, with nothing
835 835 after the ``=``.
836 836
837 837 Otherwise, give a name that you choose, followed by ``=``, followed by
838 838 the path to the ``.py`` file (including the file name extension) that
839 839 defines the extension.
840 840
841 841 To explicitly disable an extension that is enabled in an hgrc of
842 842 broader scope, prepend its path with ``!``, as in ``foo = !/ext/path``
843 843 or ``foo = !`` when path is not supplied.
844 844
845 845 Example for ``~/.hgrc``::
846 846
847 847 [extensions]
848 848 # (the churn extension will get loaded from Mercurial's path)
849 849 churn =
850 850 # (this extension will get loaded from the file specified)
851 851 myfeature = ~/.hgext/myfeature.py
852 852
853 853
854 854 ``format``
855 855 ----------
856 856
857 857 Configuration that controls the repository format. Newer format options are more
858 858 powerful, but incompatible with some older versions of Mercurial. Format options
859 859 are considered at repository initialization only. You need to make a new clone
860 860 for config changes to be taken into account.
861 861
862 862 For more details about repository format and version compatibility, see
863 863 https://www.mercurial-scm.org/wiki/MissingRequirement
864 864
865 865 ``usegeneraldelta``
866 866 Enable or disable the "generaldelta" repository format which improves
867 867 repository compression by allowing "revlog" to store deltas against
868 868 arbitrary revisions instead of the previously stored one. This provides
869 869 significant improvement for repositories with branches.
870 870
871 871 Repositories with this on-disk format require Mercurial version 1.9.
872 872
873 873 Enabled by default.
874 874
875 875 ``dotencode``
876 876 Enable or disable the "dotencode" repository format which enhances
877 877 the "fncache" repository format (which has to be enabled to use
878 878 dotencode) to avoid issues with filenames starting with "._" on
879 879 Mac OS X and spaces on Windows.
880 880
881 881 Repositories with this on-disk format require Mercurial version 1.7.
882 882
883 883 Enabled by default.
884 884
885 885 ``usefncache``
886 886 Enable or disable the "fncache" repository format which enhances
887 887 the "store" repository format (which has to be enabled to use
888 888 fncache) to allow longer filenames and avoids using Windows
889 889 reserved names, e.g. "nul".
890 890
891 891 Repositories with this on-disk format require Mercurial version 1.1.
892 892
893 893 Enabled by default.
894 894
895 895 ``use-persistent-nodemap``
896 896 Enable or disable the "persistent-nodemap" feature which improves
897 897 performance if the rust extensions are available.
898 898
899 899 The "persistence-nodemap" persist the "node -> rev" on disk removing the
900 900 need to dynamically build that mapping for each Mercurial invocation. This
901 901 significantly reduce the startup cost of various local and server-side
902 902 operation for larger repository.
903 903
904 904 The performance improving version of this feature is currently only
905 905 implemented in Rust, so people not using a version of Mercurial compiled
906 906 with the Rust part might actually suffer some slowdown. For this reason,
907 907 Such version will by default refuse to access such repositories. That
908 908 behavior can be controlled by configuration. Check
909 909 :hg:`help config.storage.revlog.persistent-nodemap.slowpath` for details.
910 910
911 911 Repository with this on-disk format require Mercurial version 5.4 or above.
912 912
913 913 Disabled by default.
914 914
915 915 ``use-share-safe``
916 916 Enforce "safe" behaviors for all "shares" that access this repository.
917 917
918 918 With this feature, "shares" using this repository as a source will:
919 919
920 920 * read the source repository's configuration (`<source>/.hg/hgrc`).
921 921 * read and use the source repository's "requirements"
922 922 (except the working copy specific one).
923 923
924 924 Without this feature, "shares" using this repository as a source will:
925 925
926 926 * keep tracking the repository "requirements" in the share only, ignoring
927 927 the source "requirements", possibly diverging from them.
928 928 * ignore source repository config. This can create problems, like silently
929 929 ignoring important hooks.
930 930
931 931 Beware that existing shares will not be upgraded/downgraded, and by
932 932 default, Mercurial will refuse to interact with them until the mismatch
933 933 is resolved. See :hg:`help config share.safe-mismatch.source-safe` and
934 934 :hg:`help config share.safe-mismatch.source-not-safe` for details.
935 935
936 936 Introduced in Mercurial 5.7.
937 937
938 938 Disabled by default.
939 939
940 940 ``usestore``
941 941 Enable or disable the "store" repository format which improves
942 942 compatibility with systems that fold case or otherwise mangle
943 943 filenames. Disabling this option will allow you to store longer filenames
944 944 in some situations at the expense of compatibility.
945 945
946 946 Repositories with this on-disk format require Mercurial version 0.9.4.
947 947
948 948 Enabled by default.
949 949
950 950 ``sparse-revlog``
951 951 Enable or disable the ``sparse-revlog`` delta strategy. This format improves
952 952 delta re-use inside revlog. For very branchy repositories, it results in a
953 953 smaller store. For repositories with many revisions, it also helps
954 954 performance (by using shortened delta chains.)
955 955
956 956 Repositories with this on-disk format require Mercurial version 4.7
957 957
958 958 Enabled by default.
959 959
960 960 ``revlog-compression``
961 961 Compression algorithm used by revlog. Supported values are `zlib` and
962 962 `zstd`. The `zlib` engine is the historical default of Mercurial. `zstd` is
963 963 a newer format that is usually a net win over `zlib`, operating faster at
964 964 better compression rates. Use `zstd` to reduce CPU usage. Multiple values
965 965 can be specified, the first available one will be used.
966 966
967 967 On some systems, the Mercurial installation may lack `zstd` support.
968 968
969 969 Default is `zlib`.
970 970
971 971 ``bookmarks-in-store``
972 972 Store bookmarks in .hg/store/. This means that bookmarks are shared when
973 973 using `hg share` regardless of the `-B` option.
974 974
975 975 Repositories with this on-disk format require Mercurial version 5.1.
976 976
977 977 Disabled by default.
978 978
979 979
980 980 ``graph``
981 981 ---------
982 982
983 983 Web graph view configuration. This section let you change graph
984 984 elements display properties by branches, for instance to make the
985 985 ``default`` branch stand out.
986 986
987 987 Each line has the following format::
988 988
989 989 <branch>.<argument> = <value>
990 990
991 991 where ``<branch>`` is the name of the branch being
992 992 customized. Example::
993 993
994 994 [graph]
995 995 # 2px width
996 996 default.width = 2
997 997 # red color
998 998 default.color = FF0000
999 999
1000 1000 Supported arguments:
1001 1001
1002 1002 ``width``
1003 1003 Set branch edges width in pixels.
1004 1004
1005 1005 ``color``
1006 1006 Set branch edges color in hexadecimal RGB notation.
1007 1007
1008 1008 ``hooks``
1009 1009 ---------
1010 1010
1011 1011 Commands or Python functions that get automatically executed by
1012 1012 various actions such as starting or finishing a commit. Multiple
1013 1013 hooks can be run for the same action by appending a suffix to the
1014 1014 action. Overriding a site-wide hook can be done by changing its
1015 1015 value or setting it to an empty string. Hooks can be prioritized
1016 1016 by adding a prefix of ``priority.`` to the hook name on a new line
1017 1017 and setting the priority. The default priority is 0.
1018 1018
1019 1019 Example ``.hg/hgrc``::
1020 1020
1021 1021 [hooks]
1022 1022 # update working directory after adding changesets
1023 1023 changegroup.update = hg update
1024 1024 # do not use the site-wide hook
1025 1025 incoming =
1026 1026 incoming.email = /my/email/hook
1027 1027 incoming.autobuild = /my/build/hook
1028 1028 # force autobuild hook to run before other incoming hooks
1029 1029 priority.incoming.autobuild = 1
1030 1030
1031 1031 Most hooks are run with environment variables set that give useful
1032 1032 additional information. For each hook below, the environment variables
1033 1033 it is passed are listed with names in the form ``$HG_foo``. The
1034 1034 ``$HG_HOOKTYPE`` and ``$HG_HOOKNAME`` variables are set for all hooks.
1035 1035 They contain the type of hook which triggered the run and the full name
1036 1036 of the hook in the config, respectively. In the example above, this will
1037 1037 be ``$HG_HOOKTYPE=incoming`` and ``$HG_HOOKNAME=incoming.email``.
1038 1038
1039 1039 .. container:: windows
1040 1040
1041 1041 Some basic Unix syntax can be enabled for portability, including ``$VAR``
1042 1042 and ``${VAR}`` style variables. A ``~`` followed by ``\`` or ``/`` will
1043 1043 be expanded to ``%USERPROFILE%`` to simulate a subset of tilde expansion
1044 1044 on Unix. To use a literal ``$`` or ``~``, it must be escaped with a back
1045 1045 slash or inside of a strong quote. Strong quotes will be replaced by
1046 1046 double quotes after processing.
1047 1047
1048 1048 This feature is enabled by adding a prefix of ``tonative.`` to the hook
1049 1049 name on a new line, and setting it to ``True``. For example::
1050 1050
1051 1051 [hooks]
1052 1052 incoming.autobuild = /my/build/hook
1053 1053 # enable translation to cmd.exe syntax for autobuild hook
1054 1054 tonative.incoming.autobuild = True
1055 1055
1056 1056 ``changegroup``
1057 1057 Run after a changegroup has been added via push, pull or unbundle. The ID of
1058 1058 the first new changeset is in ``$HG_NODE`` and last is in ``$HG_NODE_LAST``.
1059 1059 The URL from which changes came is in ``$HG_URL``.
1060 1060
1061 1061 ``commit``
1062 1062 Run after a changeset has been created in the local repository. The ID
1063 1063 of the newly created changeset is in ``$HG_NODE``. Parent changeset
1064 1064 IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
1065 1065
1066 1066 ``incoming``
1067 1067 Run after a changeset has been pulled, pushed, or unbundled into
1068 1068 the local repository. The ID of the newly arrived changeset is in
1069 1069 ``$HG_NODE``. The URL that was source of the changes is in ``$HG_URL``.
1070 1070
1071 1071 ``outgoing``
1072 1072 Run after sending changes from the local repository to another. The ID of
1073 1073 first changeset sent is in ``$HG_NODE``. The source of operation is in
1074 1074 ``$HG_SOURCE``. Also see :hg:`help config.hooks.preoutgoing`.
1075 1075
1076 1076 ``post-<command>``
1077 1077 Run after successful invocations of the associated command. The
1078 1078 contents of the command line are passed as ``$HG_ARGS`` and the result
1079 1079 code in ``$HG_RESULT``. Parsed command line arguments are passed as
1080 1080 ``$HG_PATS`` and ``$HG_OPTS``. These contain string representations of
1081 1081 the python data internally passed to <command>. ``$HG_OPTS`` is a
1082 1082 dictionary of options (with unspecified options set to their defaults).
1083 1083 ``$HG_PATS`` is a list of arguments. Hook failure is ignored.
1084 1084
1085 1085 ``fail-<command>``
1086 1086 Run after a failed invocation of an associated command. The contents
1087 1087 of the command line are passed as ``$HG_ARGS``. Parsed command line
1088 1088 arguments are passed as ``$HG_PATS`` and ``$HG_OPTS``. These contain
1089 1089 string representations of the python data internally passed to
1090 1090 <command>. ``$HG_OPTS`` is a dictionary of options (with unspecified
1091 1091 options set to their defaults). ``$HG_PATS`` is a list of arguments.
1092 1092 Hook failure is ignored.
1093 1093
1094 1094 ``pre-<command>``
1095 1095 Run before executing the associated command. The contents of the
1096 1096 command line are passed as ``$HG_ARGS``. Parsed command line arguments
1097 1097 are passed as ``$HG_PATS`` and ``$HG_OPTS``. These contain string
1098 1098 representations of the data internally passed to <command>. ``$HG_OPTS``
1099 1099 is a dictionary of options (with unspecified options set to their
1100 1100 defaults). ``$HG_PATS`` is a list of arguments. If the hook returns
1101 1101 failure, the command doesn't execute and Mercurial returns the failure
1102 1102 code.
1103 1103
1104 1104 ``prechangegroup``
1105 1105 Run before a changegroup is added via push, pull or unbundle. Exit
1106 1106 status 0 allows the changegroup to proceed. A non-zero status will
1107 1107 cause the push, pull or unbundle to fail. The URL from which changes
1108 1108 will come is in ``$HG_URL``.
1109 1109
1110 1110 ``precommit``
1111 1111 Run before starting a local commit. Exit status 0 allows the
1112 1112 commit to proceed. A non-zero status will cause the commit to fail.
1113 1113 Parent changeset IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
1114 1114
1115 1115 ``prelistkeys``
1116 1116 Run before listing pushkeys (like bookmarks) in the
1117 1117 repository. A non-zero status will cause failure. The key namespace is
1118 1118 in ``$HG_NAMESPACE``.
1119 1119
1120 1120 ``preoutgoing``
1121 1121 Run before collecting changes to send from the local repository to
1122 1122 another. A non-zero status will cause failure. This lets you prevent
1123 1123 pull over HTTP or SSH. It can also prevent propagating commits (via
1124 1124 local pull, push (outbound) or bundle commands), but not completely,
1125 1125 since you can just copy files instead. The source of operation is in
1126 1126 ``$HG_SOURCE``. If "serve", the operation is happening on behalf of a remote
1127 1127 SSH or HTTP repository. If "push", "pull" or "bundle", the operation
1128 1128 is happening on behalf of a repository on same system.
1129 1129
1130 1130 ``prepushkey``
1131 1131 Run before a pushkey (like a bookmark) is added to the
1132 1132 repository. A non-zero status will cause the key to be rejected. The
1133 1133 key namespace is in ``$HG_NAMESPACE``, the key is in ``$HG_KEY``,
1134 1134 the old value (if any) is in ``$HG_OLD``, and the new value is in
1135 1135 ``$HG_NEW``.
1136 1136
1137 1137 ``pretag``
1138 1138 Run before creating a tag. Exit status 0 allows the tag to be
1139 1139 created. A non-zero status will cause the tag to fail. The ID of the
1140 1140 changeset to tag is in ``$HG_NODE``. The name of tag is in ``$HG_TAG``. The
1141 1141 tag is local if ``$HG_LOCAL=1``, or in the repository if ``$HG_LOCAL=0``.
1142 1142
1143 1143 ``pretxnopen``
1144 1144 Run before any new repository transaction is open. The reason for the
1145 1145 transaction will be in ``$HG_TXNNAME``, and a unique identifier for the
1146 1146 transaction will be in ``HG_TXNID``. A non-zero status will prevent the
1147 1147 transaction from being opened.
1148 1148
1149 1149 ``pretxnclose``
1150 1150 Run right before the transaction is actually finalized. Any repository change
1151 1151 will be visible to the hook program. This lets you validate the transaction
1152 1152 content or change it. Exit status 0 allows the commit to proceed. A non-zero
1153 1153 status will cause the transaction to be rolled back. The reason for the
1154 1154 transaction opening will be in ``$HG_TXNNAME``, and a unique identifier for
1155 1155 the transaction will be in ``HG_TXNID``. The rest of the available data will
1156 1156 vary according the transaction type. New changesets will add ``$HG_NODE``
1157 1157 (the ID of the first added changeset), ``$HG_NODE_LAST`` (the ID of the last
1158 1158 added changeset), ``$HG_URL`` and ``$HG_SOURCE`` variables. Bookmark and
1159 1159 phase changes will set ``HG_BOOKMARK_MOVED`` and ``HG_PHASES_MOVED`` to ``1``
1160 1160 respectively, etc.
1161 1161
1162 1162 ``pretxnclose-bookmark``
1163 1163 Run right before a bookmark change is actually finalized. Any repository
1164 1164 change will be visible to the hook program. This lets you validate the
1165 1165 transaction content or change it. Exit status 0 allows the commit to
1166 1166 proceed. A non-zero status will cause the transaction to be rolled back.
1167 1167 The name of the bookmark will be available in ``$HG_BOOKMARK``, the new
1168 1168 bookmark location will be available in ``$HG_NODE`` while the previous
1169 1169 location will be available in ``$HG_OLDNODE``. In case of a bookmark
1170 1170 creation ``$HG_OLDNODE`` will be empty. In case of deletion ``$HG_NODE``
1171 1171 will be empty.
1172 1172 In addition, the reason for the transaction opening will be in
1173 1173 ``$HG_TXNNAME``, and a unique identifier for the transaction will be in
1174 1174 ``HG_TXNID``.
1175 1175
1176 1176 ``pretxnclose-phase``
1177 1177 Run right before a phase change is actually finalized. Any repository change
1178 1178 will be visible to the hook program. This lets you validate the transaction
1179 1179 content or change it. Exit status 0 allows the commit to proceed. A non-zero
1180 1180 status will cause the transaction to be rolled back. The hook is called
1181 1181 multiple times, once for each revision affected by a phase change.
1182 1182 The affected node is available in ``$HG_NODE``, the phase in ``$HG_PHASE``
1183 1183 while the previous ``$HG_OLDPHASE``. In case of new node, ``$HG_OLDPHASE``
1184 1184 will be empty. In addition, the reason for the transaction opening will be in
1185 1185 ``$HG_TXNNAME``, and a unique identifier for the transaction will be in
1186 1186 ``HG_TXNID``. The hook is also run for newly added revisions. In this case
1187 1187 the ``$HG_OLDPHASE`` entry will be empty.
1188 1188
1189 1189 ``txnclose``
1190 1190 Run after any repository transaction has been committed. At this
1191 1191 point, the transaction can no longer be rolled back. The hook will run
1192 1192 after the lock is released. See :hg:`help config.hooks.pretxnclose` for
1193 1193 details about available variables.
1194 1194
1195 1195 ``txnclose-bookmark``
1196 1196 Run after any bookmark change has been committed. At this point, the
1197 1197 transaction can no longer be rolled back. The hook will run after the lock
1198 1198 is released. See :hg:`help config.hooks.pretxnclose-bookmark` for details
1199 1199 about available variables.
1200 1200
1201 1201 ``txnclose-phase``
1202 1202 Run after any phase change has been committed. At this point, the
1203 1203 transaction can no longer be rolled back. The hook will run after the lock
1204 1204 is released. See :hg:`help config.hooks.pretxnclose-phase` for details about
1205 1205 available variables.
1206 1206
1207 1207 ``txnabort``
1208 1208 Run when a transaction is aborted. See :hg:`help config.hooks.pretxnclose`
1209 1209 for details about available variables.
1210 1210
1211 1211 ``pretxnchangegroup``
1212 1212 Run after a changegroup has been added via push, pull or unbundle, but before
1213 1213 the transaction has been committed. The changegroup is visible to the hook
1214 1214 program. This allows validation of incoming changes before accepting them.
1215 1215 The ID of the first new changeset is in ``$HG_NODE`` and last is in
1216 1216 ``$HG_NODE_LAST``. Exit status 0 allows the transaction to commit. A non-zero
1217 1217 status will cause the transaction to be rolled back, and the push, pull or
1218 1218 unbundle will fail. The URL that was the source of changes is in ``$HG_URL``.
1219 1219
1220 1220 ``pretxncommit``
1221 1221 Run after a changeset has been created, but before the transaction is
1222 1222 committed. The changeset is visible to the hook program. This allows
1223 1223 validation of the commit message and changes. Exit status 0 allows the
1224 1224 commit to proceed. A non-zero status will cause the transaction to
1225 1225 be rolled back. The ID of the new changeset is in ``$HG_NODE``. The parent
1226 1226 changeset IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
1227 1227
1228 1228 ``preupdate``
1229 1229 Run before updating the working directory. Exit status 0 allows
1230 1230 the update to proceed. A non-zero status will prevent the update.
1231 1231 The changeset ID of first new parent is in ``$HG_PARENT1``. If updating to a
1232 1232 merge, the ID of second new parent is in ``$HG_PARENT2``.
1233 1233
1234 1234 ``listkeys``
1235 1235 Run after listing pushkeys (like bookmarks) in the repository. The
1236 1236 key namespace is in ``$HG_NAMESPACE``. ``$HG_VALUES`` is a
1237 1237 dictionary containing the keys and values.
1238 1238
1239 1239 ``pushkey``
1240 1240 Run after a pushkey (like a bookmark) is added to the
1241 1241 repository. The key namespace is in ``$HG_NAMESPACE``, the key is in
1242 1242 ``$HG_KEY``, the old value (if any) is in ``$HG_OLD``, and the new
1243 1243 value is in ``$HG_NEW``.
1244 1244
1245 1245 ``tag``
1246 1246 Run after a tag is created. The ID of the tagged changeset is in ``$HG_NODE``.
1247 1247 The name of tag is in ``$HG_TAG``. The tag is local if ``$HG_LOCAL=1``, or in
1248 1248 the repository if ``$HG_LOCAL=0``.
1249 1249
1250 1250 ``update``
1251 1251 Run after updating the working directory. The changeset ID of first
1252 1252 new parent is in ``$HG_PARENT1``. If updating to a merge, the ID of second new
1253 1253 parent is in ``$HG_PARENT2``. If the update succeeded, ``$HG_ERROR=0``. If the
1254 1254 update failed (e.g. because conflicts were not resolved), ``$HG_ERROR=1``.
1255 1255
1256 1256 .. note::
1257 1257
1258 1258 It is generally better to use standard hooks rather than the
1259 1259 generic pre- and post- command hooks, as they are guaranteed to be
1260 1260 called in the appropriate contexts for influencing transactions.
1261 1261 Also, hooks like "commit" will be called in all contexts that
1262 1262 generate a commit (e.g. tag) and not just the commit command.
1263 1263
1264 1264 .. note::
1265 1265
1266 1266 Environment variables with empty values may not be passed to
1267 1267 hooks on platforms such as Windows. As an example, ``$HG_PARENT2``
1268 1268 will have an empty value under Unix-like platforms for non-merge
1269 1269 changesets, while it will not be available at all under Windows.
1270 1270
1271 1271 The syntax for Python hooks is as follows::
1272 1272
1273 1273 hookname = python:modulename.submodule.callable
1274 1274 hookname = python:/path/to/python/module.py:callable
1275 1275
1276 1276 Python hooks are run within the Mercurial process. Each hook is
1277 1277 called with at least three keyword arguments: a ui object (keyword
1278 1278 ``ui``), a repository object (keyword ``repo``), and a ``hooktype``
1279 1279 keyword that tells what kind of hook is used. Arguments listed as
1280 1280 environment variables above are passed as keyword arguments, with no
1281 1281 ``HG_`` prefix, and names in lower case.
1282 1282
1283 1283 If a Python hook returns a "true" value or raises an exception, this
1284 1284 is treated as a failure.
1285 1285
1286 1286
1287 1287 ``hostfingerprints``
1288 1288 --------------------
1289 1289
1290 1290 (Deprecated. Use ``[hostsecurity]``'s ``fingerprints`` options instead.)
1291 1291
1292 1292 Fingerprints of the certificates of known HTTPS servers.
1293 1293
1294 1294 A HTTPS connection to a server with a fingerprint configured here will
1295 1295 only succeed if the servers certificate matches the fingerprint.
1296 1296 This is very similar to how ssh known hosts works.
1297 1297
1298 1298 The fingerprint is the SHA-1 hash value of the DER encoded certificate.
1299 1299 Multiple values can be specified (separated by spaces or commas). This can
1300 1300 be used to define both old and new fingerprints while a host transitions
1301 1301 to a new certificate.
1302 1302
1303 1303 The CA chain and web.cacerts is not used for servers with a fingerprint.
1304 1304
1305 1305 For example::
1306 1306
1307 1307 [hostfingerprints]
1308 1308 hg.intevation.de = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1309 1309 hg.intevation.org = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1310 1310
1311 1311 ``hostsecurity``
1312 1312 ----------------
1313 1313
1314 1314 Used to specify global and per-host security settings for connecting to
1315 1315 other machines.
1316 1316
1317 1317 The following options control default behavior for all hosts.
1318 1318
1319 1319 ``ciphers``
1320 1320 Defines the cryptographic ciphers to use for connections.
1321 1321
1322 1322 Value must be a valid OpenSSL Cipher List Format as documented at
1323 1323 https://www.openssl.org/docs/manmaster/apps/ciphers.html#CIPHER-LIST-FORMAT.
1324 1324
1325 1325 This setting is for advanced users only. Setting to incorrect values
1326 1326 can significantly lower connection security or decrease performance.
1327 1327 You have been warned.
1328 1328
1329 1329 This option requires Python 2.7.
1330 1330
1331 1331 ``minimumprotocol``
1332 1332 Defines the minimum channel encryption protocol to use.
1333 1333
1334 1334 By default, the highest version of TLS supported by both client and server
1335 1335 is used.
1336 1336
1337 1337 Allowed values are: ``tls1.0``, ``tls1.1``, ``tls1.2``.
1338 1338
1339 1339 When running on an old Python version, only ``tls1.0`` is allowed since
1340 1340 old versions of Python only support up to TLS 1.0.
1341 1341
1342 1342 When running a Python that supports modern TLS versions, the default is
1343 1343 ``tls1.1``. ``tls1.0`` can still be used to allow TLS 1.0. However, this
1344 1344 weakens security and should only be used as a feature of last resort if
1345 1345 a server does not support TLS 1.1+.
1346 1346
1347 1347 Options in the ``[hostsecurity]`` section can have the form
1348 1348 ``hostname``:``setting``. This allows multiple settings to be defined on a
1349 1349 per-host basis.
1350 1350
1351 1351 The following per-host settings can be defined.
1352 1352
1353 1353 ``ciphers``
1354 1354 This behaves like ``ciphers`` as described above except it only applies
1355 1355 to the host on which it is defined.
1356 1356
1357 1357 ``fingerprints``
1358 1358 A list of hashes of the DER encoded peer/remote certificate. Values have
1359 1359 the form ``algorithm``:``fingerprint``. e.g.
1360 1360 ``sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2``.
1361 1361 In addition, colons (``:``) can appear in the fingerprint part.
1362 1362
1363 1363 The following algorithms/prefixes are supported: ``sha1``, ``sha256``,
1364 1364 ``sha512``.
1365 1365
1366 1366 Use of ``sha256`` or ``sha512`` is preferred.
1367 1367
1368 1368 If a fingerprint is specified, the CA chain is not validated for this
1369 1369 host and Mercurial will require the remote certificate to match one
1370 1370 of the fingerprints specified. This means if the server updates its
1371 1371 certificate, Mercurial will abort until a new fingerprint is defined.
1372 1372 This can provide stronger security than traditional CA-based validation
1373 1373 at the expense of convenience.
1374 1374
1375 1375 This option takes precedence over ``verifycertsfile``.
1376 1376
1377 1377 ``minimumprotocol``
1378 1378 This behaves like ``minimumprotocol`` as described above except it
1379 1379 only applies to the host on which it is defined.
1380 1380
1381 1381 ``verifycertsfile``
1382 1382 Path to file a containing a list of PEM encoded certificates used to
1383 1383 verify the server certificate. Environment variables and ``~user``
1384 1384 constructs are expanded in the filename.
1385 1385
1386 1386 The server certificate or the certificate's certificate authority (CA)
1387 1387 must match a certificate from this file or certificate verification
1388 1388 will fail and connections to the server will be refused.
1389 1389
1390 1390 If defined, only certificates provided by this file will be used:
1391 1391 ``web.cacerts`` and any system/default certificates will not be
1392 1392 used.
1393 1393
1394 1394 This option has no effect if the per-host ``fingerprints`` option
1395 1395 is set.
1396 1396
1397 1397 The format of the file is as follows::
1398 1398
1399 1399 -----BEGIN CERTIFICATE-----
1400 1400 ... (certificate in base64 PEM encoding) ...
1401 1401 -----END CERTIFICATE-----
1402 1402 -----BEGIN CERTIFICATE-----
1403 1403 ... (certificate in base64 PEM encoding) ...
1404 1404 -----END CERTIFICATE-----
1405 1405
1406 1406 For example::
1407 1407
1408 1408 [hostsecurity]
1409 1409 hg.example.com:fingerprints = sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
1410 1410 hg2.example.com:fingerprints = sha1:914f1aff87249c09b6859b88b1906d30756491ca, sha1:fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1411 1411 hg3.example.com:fingerprints = sha256:9a:b0:dc:e2:75:ad:8a:b7:84:58:e5:1f:07:32:f1:87:e6:bd:24:22:af:b7:ce:8e:9c:b4:10:cf:b9:f4:0e:d2
1412 1412 foo.example.com:verifycertsfile = /etc/ssl/trusted-ca-certs.pem
1413 1413
1414 1414 To change the default minimum protocol version to TLS 1.2 but to allow TLS 1.1
1415 1415 when connecting to ``hg.example.com``::
1416 1416
1417 1417 [hostsecurity]
1418 1418 minimumprotocol = tls1.2
1419 1419 hg.example.com:minimumprotocol = tls1.1
1420 1420
1421 1421 ``http_proxy``
1422 1422 --------------
1423 1423
1424 1424 Used to access web-based Mercurial repositories through a HTTP
1425 1425 proxy.
1426 1426
1427 1427 ``host``
1428 1428 Host name and (optional) port of the proxy server, for example
1429 1429 "myproxy:8000".
1430 1430
1431 1431 ``no``
1432 1432 Optional. Comma-separated list of host names that should bypass
1433 1433 the proxy.
1434 1434
1435 1435 ``passwd``
1436 1436 Optional. Password to authenticate with at the proxy server.
1437 1437
1438 1438 ``user``
1439 1439 Optional. User name to authenticate with at the proxy server.
1440 1440
1441 1441 ``always``
1442 1442 Optional. Always use the proxy, even for localhost and any entries
1443 1443 in ``http_proxy.no``. (default: False)
1444 1444
1445 1445 ``http``
1446 1446 ----------
1447 1447
1448 1448 Used to configure access to Mercurial repositories via HTTP.
1449 1449
1450 1450 ``timeout``
1451 1451 If set, blocking operations will timeout after that many seconds.
1452 1452 (default: None)
1453 1453
1454 1454 ``merge``
1455 1455 ---------
1456 1456
1457 1457 This section specifies behavior during merges and updates.
1458 1458
1459 1459 ``checkignored``
1460 1460 Controls behavior when an ignored file on disk has the same name as a tracked
1461 1461 file in the changeset being merged or updated to, and has different
1462 1462 contents. Options are ``abort``, ``warn`` and ``ignore``. With ``abort``,
1463 1463 abort on such files. With ``warn``, warn on such files and back them up as
1464 1464 ``.orig``. With ``ignore``, don't print a warning and back them up as
1465 1465 ``.orig``. (default: ``abort``)
1466 1466
1467 1467 ``checkunknown``
1468 1468 Controls behavior when an unknown file that isn't ignored has the same name
1469 1469 as a tracked file in the changeset being merged or updated to, and has
1470 1470 different contents. Similar to ``merge.checkignored``, except for files that
1471 1471 are not ignored. (default: ``abort``)
1472 1472
1473 1473 ``on-failure``
1474 1474 When set to ``continue`` (the default), the merge process attempts to
1475 1475 merge all unresolved files using the merge chosen tool, regardless of
1476 1476 whether previous file merge attempts during the process succeeded or not.
1477 1477 Setting this to ``prompt`` will prompt after any merge failure continue
1478 1478 or halt the merge process. Setting this to ``halt`` will automatically
1479 1479 halt the merge process on any merge tool failure. The merge process
1480 1480 can be restarted by using the ``resolve`` command. When a merge is
1481 1481 halted, the repository is left in a normal ``unresolved`` merge state.
1482 1482 (default: ``continue``)
1483 1483
1484 1484 ``strict-capability-check``
1485 1485 Whether capabilities of internal merge tools are checked strictly
1486 1486 or not, while examining rules to decide merge tool to be used.
1487 1487 (default: False)
1488 1488
1489 1489 ``merge-patterns``
1490 1490 ------------------
1491 1491
1492 1492 This section specifies merge tools to associate with particular file
1493 1493 patterns. Tools matched here will take precedence over the default
1494 1494 merge tool. Patterns are globs by default, rooted at the repository
1495 1495 root.
1496 1496
1497 1497 Example::
1498 1498
1499 1499 [merge-patterns]
1500 1500 **.c = kdiff3
1501 1501 **.jpg = myimgmerge
1502 1502
1503 1503 ``merge-tools``
1504 1504 ---------------
1505 1505
1506 1506 This section configures external merge tools to use for file-level
1507 1507 merges. This section has likely been preconfigured at install time.
1508 1508 Use :hg:`config merge-tools` to check the existing configuration.
1509 1509 Also see :hg:`help merge-tools` for more details.
1510 1510
1511 1511 Example ``~/.hgrc``::
1512 1512
1513 1513 [merge-tools]
1514 1514 # Override stock tool location
1515 1515 kdiff3.executable = ~/bin/kdiff3
1516 1516 # Specify command line
1517 1517 kdiff3.args = $base $local $other -o $output
1518 1518 # Give higher priority
1519 1519 kdiff3.priority = 1
1520 1520
1521 1521 # Changing the priority of preconfigured tool
1522 1522 meld.priority = 0
1523 1523
1524 1524 # Disable a preconfigured tool
1525 1525 vimdiff.disabled = yes
1526 1526
1527 1527 # Define new tool
1528 1528 myHtmlTool.args = -m $local $other $base $output
1529 1529 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
1530 1530 myHtmlTool.priority = 1
1531 1531
1532 1532 Supported arguments:
1533 1533
1534 1534 ``priority``
1535 1535 The priority in which to evaluate this tool.
1536 1536 (default: 0)
1537 1537
1538 1538 ``executable``
1539 1539 Either just the name of the executable or its pathname.
1540 1540
1541 1541 .. container:: windows
1542 1542
1543 1543 On Windows, the path can use environment variables with ${ProgramFiles}
1544 1544 syntax.
1545 1545
1546 1546 (default: the tool name)
1547 1547
1548 1548 ``args``
1549 1549 The arguments to pass to the tool executable. You can refer to the
1550 1550 files being merged as well as the output file through these
1551 1551 variables: ``$base``, ``$local``, ``$other``, ``$output``.
1552 1552
1553 1553 The meaning of ``$local`` and ``$other`` can vary depending on which action is
1554 1554 being performed. During an update or merge, ``$local`` represents the original
1555 1555 state of the file, while ``$other`` represents the commit you are updating to or
1556 1556 the commit you are merging with. During a rebase, ``$local`` represents the
1557 1557 destination of the rebase, and ``$other`` represents the commit being rebased.
1558 1558
1559 1559 Some operations define custom labels to assist with identifying the revisions,
1560 1560 accessible via ``$labellocal``, ``$labelother``, and ``$labelbase``. If custom
1561 1561 labels are not available, these will be ``local``, ``other``, and ``base``,
1562 1562 respectively.
1563 1563 (default: ``$local $base $other``)
1564 1564
1565 1565 ``premerge``
1566 1566 Attempt to run internal non-interactive 3-way merge tool before
1567 1567 launching external tool. Options are ``true``, ``false``, ``keep``,
1568 1568 ``keep-merge3``, or ``keep-mergediff`` (experimental). The ``keep`` option
1569 1569 will leave markers in the file if the premerge fails. The ``keep-merge3``
1570 1570 will do the same but include information about the base of the merge in the
1571 1571 marker (see internal :merge3 in :hg:`help merge-tools`). The
1572 1572 ``keep-mergediff`` option is similar but uses a different marker style
1573 1573 (see internal :merge3 in :hg:`help merge-tools`). (default: True)
1574 1574
1575 1575 ``binary``
1576 1576 This tool can merge binary files. (default: False, unless tool
1577 1577 was selected by file pattern match)
1578 1578
1579 1579 ``symlink``
1580 1580 This tool can merge symlinks. (default: False)
1581 1581
1582 1582 ``check``
1583 1583 A list of merge success-checking options:
1584 1584
1585 1585 ``changed``
1586 1586 Ask whether merge was successful when the merged file shows no changes.
1587 1587 ``conflicts``
1588 1588 Check whether there are conflicts even though the tool reported success.
1589 1589 ``prompt``
1590 1590 Always prompt for merge success, regardless of success reported by tool.
1591 1591
1592 1592 ``fixeol``
1593 1593 Attempt to fix up EOL changes caused by the merge tool.
1594 1594 (default: False)
1595 1595
1596 1596 ``gui``
1597 1597 This tool requires a graphical interface to run. (default: False)
1598 1598
1599 1599 ``mergemarkers``
1600 1600 Controls whether the labels passed via ``$labellocal``, ``$labelother``, and
1601 1601 ``$labelbase`` are ``detailed`` (respecting ``mergemarkertemplate``) or
1602 1602 ``basic``. If ``premerge`` is ``keep`` or ``keep-merge3``, the conflict
1603 1603 markers generated during premerge will be ``detailed`` if either this option or
1604 1604 the corresponding option in the ``[ui]`` section is ``detailed``.
1605 1605 (default: ``basic``)
1606 1606
1607 1607 ``mergemarkertemplate``
1608 1608 This setting can be used to override ``mergemarker`` from the
1609 1609 ``[command-templates]`` section on a per-tool basis; this applies to the
1610 1610 ``$label``-prefixed variables and to the conflict markers that are generated
1611 1611 if ``premerge`` is ``keep` or ``keep-merge3``. See the corresponding variable
1612 1612 in ``[ui]`` for more information.
1613 1613
1614 1614 .. container:: windows
1615 1615
1616 1616 ``regkey``
1617 1617 Windows registry key which describes install location of this
1618 1618 tool. Mercurial will search for this key first under
1619 1619 ``HKEY_CURRENT_USER`` and then under ``HKEY_LOCAL_MACHINE``.
1620 1620 (default: None)
1621 1621
1622 1622 ``regkeyalt``
1623 1623 An alternate Windows registry key to try if the first key is not
1624 1624 found. The alternate key uses the same ``regname`` and ``regappend``
1625 1625 semantics of the primary key. The most common use for this key
1626 1626 is to search for 32bit applications on 64bit operating systems.
1627 1627 (default: None)
1628 1628
1629 1629 ``regname``
1630 1630 Name of value to read from specified registry key.
1631 1631 (default: the unnamed (default) value)
1632 1632
1633 1633 ``regappend``
1634 1634 String to append to the value read from the registry, typically
1635 1635 the executable name of the tool.
1636 1636 (default: None)
1637 1637
1638 1638 ``pager``
1639 1639 ---------
1640 1640
1641 1641 Setting used to control when to paginate and with what external tool. See
1642 1642 :hg:`help pager` for details.
1643 1643
1644 1644 ``pager``
1645 1645 Define the external tool used as pager.
1646 1646
1647 1647 If no pager is set, Mercurial uses the environment variable $PAGER.
1648 1648 If neither pager.pager, nor $PAGER is set, a default pager will be
1649 1649 used, typically `less` on Unix and `more` on Windows. Example::
1650 1650
1651 1651 [pager]
1652 1652 pager = less -FRX
1653 1653
1654 1654 ``ignore``
1655 1655 List of commands to disable the pager for. Example::
1656 1656
1657 1657 [pager]
1658 1658 ignore = version, help, update
1659 1659
1660 1660 ``patch``
1661 1661 ---------
1662 1662
1663 1663 Settings used when applying patches, for instance through the 'import'
1664 1664 command or with Mercurial Queues extension.
1665 1665
1666 1666 ``eol``
1667 1667 When set to 'strict' patch content and patched files end of lines
1668 1668 are preserved. When set to ``lf`` or ``crlf``, both files end of
1669 1669 lines are ignored when patching and the result line endings are
1670 1670 normalized to either LF (Unix) or CRLF (Windows). When set to
1671 1671 ``auto``, end of lines are again ignored while patching but line
1672 1672 endings in patched files are normalized to their original setting
1673 1673 on a per-file basis. If target file does not exist or has no end
1674 1674 of line, patch line endings are preserved.
1675 1675 (default: strict)
1676 1676
1677 1677 ``fuzz``
1678 1678 The number of lines of 'fuzz' to allow when applying patches. This
1679 1679 controls how much context the patcher is allowed to ignore when
1680 1680 trying to apply a patch.
1681 1681 (default: 2)
1682 1682
1683 1683 ``paths``
1684 1684 ---------
1685 1685
1686 1686 Assigns symbolic names and behavior to repositories.
1687 1687
1688 1688 Options are symbolic names defining the URL or directory that is the
1689 1689 location of the repository. Example::
1690 1690
1691 1691 [paths]
1692 1692 my_server = https://example.com/my_repo
1693 1693 local_path = /home/me/repo
1694 1694
1695 1695 These symbolic names can be used from the command line. To pull
1696 1696 from ``my_server``: :hg:`pull my_server`. To push to ``local_path``:
1697 1697 :hg:`push local_path`.
1698 1698
1699 1699 Options containing colons (``:``) denote sub-options that can influence
1700 1700 behavior for that specific path. Example::
1701 1701
1702 1702 [paths]
1703 1703 my_server = https://example.com/my_path
1704 1704 my_server:pushurl = ssh://example.com/my_path
1705 1705
1706 1706 The following sub-options can be defined:
1707 1707
1708 1708 ``pushurl``
1709 1709 The URL to use for push operations. If not defined, the location
1710 1710 defined by the path's main entry is used.
1711 1711
1712 1712 ``pushrev``
1713 1713 A revset defining which revisions to push by default.
1714 1714
1715 1715 When :hg:`push` is executed without a ``-r`` argument, the revset
1716 1716 defined by this sub-option is evaluated to determine what to push.
1717 1717
1718 1718 For example, a value of ``.`` will push the working directory's
1719 1719 revision by default.
1720 1720
1721 1721 Revsets specifying bookmarks will not result in the bookmark being
1722 1722 pushed.
1723 1723
1724 1724 The following special named paths exist:
1725 1725
1726 1726 ``default``
1727 1727 The URL or directory to use when no source or remote is specified.
1728 1728
1729 1729 :hg:`clone` will automatically define this path to the location the
1730 1730 repository was cloned from.
1731 1731
1732 1732 ``default-push``
1733 1733 (deprecated) The URL or directory for the default :hg:`push` location.
1734 1734 ``default:pushurl`` should be used instead.
1735 1735
1736 1736 ``phases``
1737 1737 ----------
1738 1738
1739 1739 Specifies default handling of phases. See :hg:`help phases` for more
1740 1740 information about working with phases.
1741 1741
1742 1742 ``publish``
1743 1743 Controls draft phase behavior when working as a server. When true,
1744 1744 pushed changesets are set to public in both client and server and
1745 1745 pulled or cloned changesets are set to public in the client.
1746 1746 (default: True)
1747 1747
1748 1748 ``new-commit``
1749 1749 Phase of newly-created commits.
1750 1750 (default: draft)
1751 1751
1752 1752 ``checksubrepos``
1753 1753 Check the phase of the current revision of each subrepository. Allowed
1754 1754 values are "ignore", "follow" and "abort". For settings other than
1755 1755 "ignore", the phase of the current revision of each subrepository is
1756 1756 checked before committing the parent repository. If any of those phases is
1757 1757 greater than the phase of the parent repository (e.g. if a subrepo is in a
1758 1758 "secret" phase while the parent repo is in "draft" phase), the commit is
1759 1759 either aborted (if checksubrepos is set to "abort") or the higher phase is
1760 1760 used for the parent repository commit (if set to "follow").
1761 1761 (default: follow)
1762 1762
1763 1763
1764 1764 ``profiling``
1765 1765 -------------
1766 1766
1767 1767 Specifies profiling type, format, and file output. Two profilers are
1768 1768 supported: an instrumenting profiler (named ``ls``), and a sampling
1769 1769 profiler (named ``stat``).
1770 1770
1771 1771 In this section description, 'profiling data' stands for the raw data
1772 1772 collected during profiling, while 'profiling report' stands for a
1773 1773 statistical text report generated from the profiling data.
1774 1774
1775 1775 ``enabled``
1776 1776 Enable the profiler.
1777 1777 (default: false)
1778 1778
1779 1779 This is equivalent to passing ``--profile`` on the command line.
1780 1780
1781 1781 ``type``
1782 1782 The type of profiler to use.
1783 1783 (default: stat)
1784 1784
1785 1785 ``ls``
1786 1786 Use Python's built-in instrumenting profiler. This profiler
1787 1787 works on all platforms, but each line number it reports is the
1788 1788 first line of a function. This restriction makes it difficult to
1789 1789 identify the expensive parts of a non-trivial function.
1790 1790 ``stat``
1791 1791 Use a statistical profiler, statprof. This profiler is most
1792 1792 useful for profiling commands that run for longer than about 0.1
1793 1793 seconds.
1794 1794
1795 1795 ``format``
1796 1796 Profiling format. Specific to the ``ls`` instrumenting profiler.
1797 1797 (default: text)
1798 1798
1799 1799 ``text``
1800 1800 Generate a profiling report. When saving to a file, it should be
1801 1801 noted that only the report is saved, and the profiling data is
1802 1802 not kept.
1803 1803 ``kcachegrind``
1804 1804 Format profiling data for kcachegrind use: when saving to a
1805 1805 file, the generated file can directly be loaded into
1806 1806 kcachegrind.
1807 1807
1808 1808 ``statformat``
1809 1809 Profiling format for the ``stat`` profiler.
1810 1810 (default: hotpath)
1811 1811
1812 1812 ``hotpath``
1813 1813 Show a tree-based display containing the hot path of execution (where
1814 1814 most time was spent).
1815 1815 ``bymethod``
1816 1816 Show a table of methods ordered by how frequently they are active.
1817 1817 ``byline``
1818 1818 Show a table of lines in files ordered by how frequently they are active.
1819 1819 ``json``
1820 1820 Render profiling data as JSON.
1821 1821
1822 1822 ``frequency``
1823 1823 Sampling frequency. Specific to the ``stat`` sampling profiler.
1824 1824 (default: 1000)
1825 1825
1826 1826 ``output``
1827 1827 File path where profiling data or report should be saved. If the
1828 1828 file exists, it is replaced. (default: None, data is printed on
1829 1829 stderr)
1830 1830
1831 1831 ``sort``
1832 1832 Sort field. Specific to the ``ls`` instrumenting profiler.
1833 1833 One of ``callcount``, ``reccallcount``, ``totaltime`` and
1834 1834 ``inlinetime``.
1835 1835 (default: inlinetime)
1836 1836
1837 1837 ``time-track``
1838 1838 Control if the stat profiler track ``cpu`` or ``real`` time.
1839 1839 (default: ``cpu`` on Windows, otherwise ``real``)
1840 1840
1841 1841 ``limit``
1842 1842 Number of lines to show. Specific to the ``ls`` instrumenting profiler.
1843 1843 (default: 30)
1844 1844
1845 1845 ``nested``
1846 1846 Show at most this number of lines of drill-down info after each main entry.
1847 1847 This can help explain the difference between Total and Inline.
1848 1848 Specific to the ``ls`` instrumenting profiler.
1849 1849 (default: 0)
1850 1850
1851 1851 ``showmin``
1852 1852 Minimum fraction of samples an entry must have for it to be displayed.
1853 1853 Can be specified as a float between ``0.0`` and ``1.0`` or can have a
1854 1854 ``%`` afterwards to allow values up to ``100``. e.g. ``5%``.
1855 1855
1856 1856 Only used by the ``stat`` profiler.
1857 1857
1858 1858 For the ``hotpath`` format, default is ``0.05``.
1859 1859 For the ``chrome`` format, default is ``0.005``.
1860 1860
1861 1861 The option is unused on other formats.
1862 1862
1863 1863 ``showmax``
1864 1864 Maximum fraction of samples an entry can have before it is ignored in
1865 1865 display. Values format is the same as ``showmin``.
1866 1866
1867 1867 Only used by the ``stat`` profiler.
1868 1868
1869 1869 For the ``chrome`` format, default is ``0.999``.
1870 1870
1871 1871 The option is unused on other formats.
1872 1872
1873 1873 ``showtime``
1874 1874 Show time taken as absolute durations, in addition to percentages.
1875 1875 Only used by the ``hotpath`` format.
1876 1876 (default: true)
1877 1877
1878 1878 ``progress``
1879 1879 ------------
1880 1880
1881 1881 Mercurial commands can draw progress bars that are as informative as
1882 1882 possible. Some progress bars only offer indeterminate information, while others
1883 1883 have a definite end point.
1884 1884
1885 1885 ``debug``
1886 1886 Whether to print debug info when updating the progress bar. (default: False)
1887 1887
1888 1888 ``delay``
1889 1889 Number of seconds (float) before showing the progress bar. (default: 3)
1890 1890
1891 1891 ``changedelay``
1892 1892 Minimum delay before showing a new topic. When set to less than 3 * refresh,
1893 1893 that value will be used instead. (default: 1)
1894 1894
1895 1895 ``estimateinterval``
1896 1896 Maximum sampling interval in seconds for speed and estimated time
1897 1897 calculation. (default: 60)
1898 1898
1899 1899 ``refresh``
1900 1900 Time in seconds between refreshes of the progress bar. (default: 0.1)
1901 1901
1902 1902 ``format``
1903 1903 Format of the progress bar.
1904 1904
1905 1905 Valid entries for the format field are ``topic``, ``bar``, ``number``,
1906 1906 ``unit``, ``estimate``, ``speed``, and ``item``. ``item`` defaults to the
1907 1907 last 20 characters of the item, but this can be changed by adding either
1908 1908 ``-<num>`` which would take the last num characters, or ``+<num>`` for the
1909 1909 first num characters.
1910 1910
1911 1911 (default: topic bar number estimate)
1912 1912
1913 1913 ``width``
1914 1914 If set, the maximum width of the progress information (that is, min(width,
1915 1915 term width) will be used).
1916 1916
1917 1917 ``clear-complete``
1918 1918 Clear the progress bar after it's done. (default: True)
1919 1919
1920 1920 ``disable``
1921 1921 If true, don't show a progress bar.
1922 1922
1923 1923 ``assume-tty``
1924 1924 If true, ALWAYS show a progress bar, unless disable is given.
1925 1925
1926 1926 ``rebase``
1927 1927 ----------
1928 1928
1929 1929 ``evolution.allowdivergence``
1930 1930 Default to False, when True allow creating divergence when performing
1931 1931 rebase of obsolete changesets.
1932 1932
1933 1933 ``revsetalias``
1934 1934 ---------------
1935 1935
1936 1936 Alias definitions for revsets. See :hg:`help revsets` for details.
1937 1937
1938 1938 ``rewrite``
1939 1939 -----------
1940 1940
1941 1941 ``backup-bundle``
1942 1942 Whether to save stripped changesets to a bundle file. (default: True)
1943 1943
1944 1944 ``update-timestamp``
1945 1945 If true, updates the date and time of the changeset to current. It is only
1946 1946 applicable for `hg amend`, `hg commit --amend` and `hg uncommit` in the
1947 1947 current version.
1948 1948
1949 1949 ``empty-successor``
1950 1950
1951 1951 Control what happens with empty successors that are the result of rewrite
1952 1952 operations. If set to ``skip``, the successor is not created. If set to
1953 1953 ``keep``, the empty successor is created and kept.
1954 1954
1955 1955 Currently, only the rebase and absorb commands consider this configuration.
1956 1956 (EXPERIMENTAL)
1957 1957
1958 1958 ``share``
1959 1959 ---------
1960 1960
1961 1961 ``safe-mismatch.source-safe``
1962 1962
1963 1963 Controls what happens when the shared repository does not use the
1964 1964 share-safe mechanism but its source repository does.
1965 1965
1966 1966 Possible values are `abort` (default), `allow`, `upgrade-abort` and
1967 1967 `upgrade-abort`.
1968 1968
1969 1969 ``abort``
1970 1970 Disallows running any command and aborts
1971 1971 ``allow``
1972 1972 Respects the feature presence in the share source
1973 1973 ``upgrade-abort``
1974 1974 tries to upgrade the share to use share-safe; if it fails, aborts
1975 1975 ``upgrade-allow``
1976 1976 tries to upgrade the share; if it fails, continue by
1977 1977 respecting the share source setting
1978 1978
1979 Check :hg:`help config format.use-share-safe` for details about the
1980 share-safe feature.
1981
1979 1982 ``safe-mismatch.source-safe.warn``
1980 1983 Shows a warning on operations if the shared repository does not use
1981 1984 share-safe, but the source repository does.
1982 1985 (default: True)
1983 1986
1984 1987 ``safe-mismatch.source-not-safe``
1985 1988
1986 1989 Controls what happens when the shared repository uses the share-safe
1987 1990 mechanism but its source does not.
1988 1991
1989 1992 Possible values are `abort` (default), `allow`, `downgrade-abort` and
1990 1993 `downgrade-abort`.
1991 1994
1992 1995 ``abort``
1993 1996 Disallows running any command and aborts
1994 1997 ``allow``
1995 1998 Respects the feature presence in the share source
1996 1999 ``downgrade-abort``
1997 2000 tries to downgrade the share to not use share-safe; if it fails, aborts
1998 2001 ``downgrade-allow``
1999 2002 tries to downgrade the share to not use share-safe;
2000 2003 if it fails, continue by respecting the shared source setting
2001 2004
2005 Check :hg:`help config format.use-share-safe` for details about the
2006 share-safe feature.
2007
2002 2008 ``safe-mismatch.source-not-safe.warn``
2003 2009 Shows a warning on operations if the shared repository uses share-safe,
2004 2010 but the source repository does not.
2005 2011 (default: True)
2006 2012
2007 2013 ``storage``
2008 2014 -----------
2009 2015
2010 2016 Control the strategy Mercurial uses internally to store history. Options in this
2011 2017 category impact performance and repository size.
2012 2018
2013 2019 ``revlog.optimize-delta-parent-choice``
2014 2020 When storing a merge revision, both parents will be equally considered as
2015 2021 a possible delta base. This results in better delta selection and improved
2016 2022 revlog compression. This option is enabled by default.
2017 2023
2018 2024 Turning this option off can result in large increase of repository size for
2019 2025 repository with many merges.
2020 2026
2021 2027 ``revlog.persistent-nodemap.mmap``
2022 2028 Whether to use the Operating System "memory mapping" feature (when
2023 2029 possible) to access the persistent nodemap data. This improve performance
2024 2030 and reduce memory pressure.
2025 2031
2026 2032 Default to True.
2027 2033
2028 2034 For details on the "persistent-nodemap" feature, see:
2029 2035 :hg:`help config format.use-persistent-nodemap`.
2030 2036
2031 2037 ``revlog.persistent-nodemap.slow-path``
2032 2038 Control the behavior of Merucrial when using a repository with "persistent"
2033 2039 nodemap with an installation of Mercurial without a fast implementation for
2034 2040 the feature:
2035 2041
2036 2042 ``allow``: Silently use the slower implementation to access the repository.
2037 2043 ``warn``: Warn, but use the slower implementation to access the repository.
2038 2044 ``abort``: Prevent access to such repositories. (This is the default)
2039 2045
2040 2046 For details on the "persistent-nodemap" feature, see:
2041 2047 :hg:`help config format.use-persistent-nodemap`.
2042 2048
2043 2049 ``revlog.reuse-external-delta-parent``
2044 2050 Control the order in which delta parents are considered when adding new
2045 2051 revisions from an external source.
2046 2052 (typically: apply bundle from `hg pull` or `hg push`).
2047 2053
2048 2054 New revisions are usually provided as a delta against other revisions. By
2049 2055 default, Mercurial will try to reuse this delta first, therefore using the
2050 2056 same "delta parent" as the source. Directly using delta's from the source
2051 2057 reduces CPU usage and usually speeds up operation. However, in some case,
2052 2058 the source might have sub-optimal delta bases and forcing their reevaluation
2053 2059 is useful. For example, pushes from an old client could have sub-optimal
2054 2060 delta's parent that the server want to optimize. (lack of general delta, bad
2055 2061 parents, choice, lack of sparse-revlog, etc).
2056 2062
2057 2063 This option is enabled by default. Turning it off will ensure bad delta
2058 2064 parent choices from older client do not propagate to this repository, at
2059 2065 the cost of a small increase in CPU consumption.
2060 2066
2061 2067 Note: this option only control the order in which delta parents are
2062 2068 considered. Even when disabled, the existing delta from the source will be
2063 2069 reused if the same delta parent is selected.
2064 2070
2065 2071 ``revlog.reuse-external-delta``
2066 2072 Control the reuse of delta from external source.
2067 2073 (typically: apply bundle from `hg pull` or `hg push`).
2068 2074
2069 2075 New revisions are usually provided as a delta against another revision. By
2070 2076 default, Mercurial will not recompute the same delta again, trusting
2071 2077 externally provided deltas. There have been rare cases of small adjustment
2072 2078 to the diffing algorithm in the past. So in some rare case, recomputing
2073 2079 delta provided by ancient clients can provides better results. Disabling
2074 2080 this option means going through a full delta recomputation for all incoming
2075 2081 revisions. It means a large increase in CPU usage and will slow operations
2076 2082 down.
2077 2083
2078 2084 This option is enabled by default. When disabled, it also disables the
2079 2085 related ``storage.revlog.reuse-external-delta-parent`` option.
2080 2086
2081 2087 ``revlog.zlib.level``
2082 2088 Zlib compression level used when storing data into the repository. Accepted
2083 2089 Value range from 1 (lowest compression) to 9 (highest compression). Zlib
2084 2090 default value is 6.
2085 2091
2086 2092
2087 2093 ``revlog.zstd.level``
2088 2094 zstd compression level used when storing data into the repository. Accepted
2089 2095 Value range from 1 (lowest compression) to 22 (highest compression).
2090 2096 (default 3)
2091 2097
2092 2098 ``server``
2093 2099 ----------
2094 2100
2095 2101 Controls generic server settings.
2096 2102
2097 2103 ``bookmarks-pushkey-compat``
2098 2104 Trigger pushkey hook when being pushed bookmark updates. This config exist
2099 2105 for compatibility purpose (default to True)
2100 2106
2101 2107 If you use ``pushkey`` and ``pre-pushkey`` hooks to control bookmark
2102 2108 movement we recommend you migrate them to ``txnclose-bookmark`` and
2103 2109 ``pretxnclose-bookmark``.
2104 2110
2105 2111 ``compressionengines``
2106 2112 List of compression engines and their relative priority to advertise
2107 2113 to clients.
2108 2114
2109 2115 The order of compression engines determines their priority, the first
2110 2116 having the highest priority. If a compression engine is not listed
2111 2117 here, it won't be advertised to clients.
2112 2118
2113 2119 If not set (the default), built-in defaults are used. Run
2114 2120 :hg:`debuginstall` to list available compression engines and their
2115 2121 default wire protocol priority.
2116 2122
2117 2123 Older Mercurial clients only support zlib compression and this setting
2118 2124 has no effect for legacy clients.
2119 2125
2120 2126 ``uncompressed``
2121 2127 Whether to allow clients to clone a repository using the
2122 2128 uncompressed streaming protocol. This transfers about 40% more
2123 2129 data than a regular clone, but uses less memory and CPU on both
2124 2130 server and client. Over a LAN (100 Mbps or better) or a very fast
2125 2131 WAN, an uncompressed streaming clone is a lot faster (~10x) than a
2126 2132 regular clone. Over most WAN connections (anything slower than
2127 2133 about 6 Mbps), uncompressed streaming is slower, because of the
2128 2134 extra data transfer overhead. This mode will also temporarily hold
2129 2135 the write lock while determining what data to transfer.
2130 2136 (default: True)
2131 2137
2132 2138 ``uncompressedallowsecret``
2133 2139 Whether to allow stream clones when the repository contains secret
2134 2140 changesets. (default: False)
2135 2141
2136 2142 ``preferuncompressed``
2137 2143 When set, clients will try to use the uncompressed streaming
2138 2144 protocol. (default: False)
2139 2145
2140 2146 ``disablefullbundle``
2141 2147 When set, servers will refuse attempts to do pull-based clones.
2142 2148 If this option is set, ``preferuncompressed`` and/or clone bundles
2143 2149 are highly recommended. Partial clones will still be allowed.
2144 2150 (default: False)
2145 2151
2146 2152 ``streamunbundle``
2147 2153 When set, servers will apply data sent from the client directly,
2148 2154 otherwise it will be written to a temporary file first. This option
2149 2155 effectively prevents concurrent pushes.
2150 2156
2151 2157 ``pullbundle``
2152 2158 When set, the server will check pullbundle.manifest for bundles
2153 2159 covering the requested heads and common nodes. The first matching
2154 2160 entry will be streamed to the client.
2155 2161
2156 2162 For HTTP transport, the stream will still use zlib compression
2157 2163 for older clients.
2158 2164
2159 2165 ``concurrent-push-mode``
2160 2166 Level of allowed race condition between two pushing clients.
2161 2167
2162 2168 - 'strict': push is abort if another client touched the repository
2163 2169 while the push was preparing.
2164 2170 - 'check-related': push is only aborted if it affects head that got also
2165 2171 affected while the push was preparing. (default since 5.4)
2166 2172
2167 2173 'check-related' only takes effect for compatible clients (version
2168 2174 4.3 and later). Older clients will use 'strict'.
2169 2175
2170 2176 ``validate``
2171 2177 Whether to validate the completeness of pushed changesets by
2172 2178 checking that all new file revisions specified in manifests are
2173 2179 present. (default: False)
2174 2180
2175 2181 ``maxhttpheaderlen``
2176 2182 Instruct HTTP clients not to send request headers longer than this
2177 2183 many bytes. (default: 1024)
2178 2184
2179 2185 ``bundle1``
2180 2186 Whether to allow clients to push and pull using the legacy bundle1
2181 2187 exchange format. (default: True)
2182 2188
2183 2189 ``bundle1gd``
2184 2190 Like ``bundle1`` but only used if the repository is using the
2185 2191 *generaldelta* storage format. (default: True)
2186 2192
2187 2193 ``bundle1.push``
2188 2194 Whether to allow clients to push using the legacy bundle1 exchange
2189 2195 format. (default: True)
2190 2196
2191 2197 ``bundle1gd.push``
2192 2198 Like ``bundle1.push`` but only used if the repository is using the
2193 2199 *generaldelta* storage format. (default: True)
2194 2200
2195 2201 ``bundle1.pull``
2196 2202 Whether to allow clients to pull using the legacy bundle1 exchange
2197 2203 format. (default: True)
2198 2204
2199 2205 ``bundle1gd.pull``
2200 2206 Like ``bundle1.pull`` but only used if the repository is using the
2201 2207 *generaldelta* storage format. (default: True)
2202 2208
2203 2209 Large repositories using the *generaldelta* storage format should
2204 2210 consider setting this option because converting *generaldelta*
2205 2211 repositories to the exchange format required by the bundle1 data
2206 2212 format can consume a lot of CPU.
2207 2213
2208 2214 ``bundle2.stream``
2209 2215 Whether to allow clients to pull using the bundle2 streaming protocol.
2210 2216 (default: True)
2211 2217
2212 2218 ``zliblevel``
2213 2219 Integer between ``-1`` and ``9`` that controls the zlib compression level
2214 2220 for wire protocol commands that send zlib compressed output (notably the
2215 2221 commands that send repository history data).
2216 2222
2217 2223 The default (``-1``) uses the default zlib compression level, which is
2218 2224 likely equivalent to ``6``. ``0`` means no compression. ``9`` means
2219 2225 maximum compression.
2220 2226
2221 2227 Setting this option allows server operators to make trade-offs between
2222 2228 bandwidth and CPU used. Lowering the compression lowers CPU utilization
2223 2229 but sends more bytes to clients.
2224 2230
2225 2231 This option only impacts the HTTP server.
2226 2232
2227 2233 ``zstdlevel``
2228 2234 Integer between ``1`` and ``22`` that controls the zstd compression level
2229 2235 for wire protocol commands. ``1`` is the minimal amount of compression and
2230 2236 ``22`` is the highest amount of compression.
2231 2237
2232 2238 The default (``3``) should be significantly faster than zlib while likely
2233 2239 delivering better compression ratios.
2234 2240
2235 2241 This option only impacts the HTTP server.
2236 2242
2237 2243 See also ``server.zliblevel``.
2238 2244
2239 2245 ``view``
2240 2246 Repository filter used when exchanging revisions with the peer.
2241 2247
2242 2248 The default view (``served``) excludes secret and hidden changesets.
2243 2249 Another useful value is ``immutable`` (no draft, secret or hidden
2244 2250 changesets). (EXPERIMENTAL)
2245 2251
2246 2252 ``smtp``
2247 2253 --------
2248 2254
2249 2255 Configuration for extensions that need to send email messages.
2250 2256
2251 2257 ``host``
2252 2258 Host name of mail server, e.g. "mail.example.com".
2253 2259
2254 2260 ``port``
2255 2261 Optional. Port to connect to on mail server. (default: 465 if
2256 2262 ``tls`` is smtps; 25 otherwise)
2257 2263
2258 2264 ``tls``
2259 2265 Optional. Method to enable TLS when connecting to mail server: starttls,
2260 2266 smtps or none. (default: none)
2261 2267
2262 2268 ``username``
2263 2269 Optional. User name for authenticating with the SMTP server.
2264 2270 (default: None)
2265 2271
2266 2272 ``password``
2267 2273 Optional. Password for authenticating with the SMTP server. If not
2268 2274 specified, interactive sessions will prompt the user for a
2269 2275 password; non-interactive sessions will fail. (default: None)
2270 2276
2271 2277 ``local_hostname``
2272 2278 Optional. The hostname that the sender can use to identify
2273 2279 itself to the MTA.
2274 2280
2275 2281
2276 2282 ``subpaths``
2277 2283 ------------
2278 2284
2279 2285 Subrepository source URLs can go stale if a remote server changes name
2280 2286 or becomes temporarily unavailable. This section lets you define
2281 2287 rewrite rules of the form::
2282 2288
2283 2289 <pattern> = <replacement>
2284 2290
2285 2291 where ``pattern`` is a regular expression matching a subrepository
2286 2292 source URL and ``replacement`` is the replacement string used to
2287 2293 rewrite it. Groups can be matched in ``pattern`` and referenced in
2288 2294 ``replacements``. For instance::
2289 2295
2290 2296 http://server/(.*)-hg/ = http://hg.server/\1/
2291 2297
2292 2298 rewrites ``http://server/foo-hg/`` into ``http://hg.server/foo/``.
2293 2299
2294 2300 Relative subrepository paths are first made absolute, and the
2295 2301 rewrite rules are then applied on the full (absolute) path. If ``pattern``
2296 2302 doesn't match the full path, an attempt is made to apply it on the
2297 2303 relative path alone. The rules are applied in definition order.
2298 2304
2299 2305 ``subrepos``
2300 2306 ------------
2301 2307
2302 2308 This section contains options that control the behavior of the
2303 2309 subrepositories feature. See also :hg:`help subrepos`.
2304 2310
2305 2311 Security note: auditing in Mercurial is known to be insufficient to
2306 2312 prevent clone-time code execution with carefully constructed Git
2307 2313 subrepos. It is unknown if a similar detect is present in Subversion
2308 2314 subrepos. Both Git and Subversion subrepos are disabled by default
2309 2315 out of security concerns. These subrepo types can be enabled using
2310 2316 the respective options below.
2311 2317
2312 2318 ``allowed``
2313 2319 Whether subrepositories are allowed in the working directory.
2314 2320
2315 2321 When false, commands involving subrepositories (like :hg:`update`)
2316 2322 will fail for all subrepository types.
2317 2323 (default: true)
2318 2324
2319 2325 ``hg:allowed``
2320 2326 Whether Mercurial subrepositories are allowed in the working
2321 2327 directory. This option only has an effect if ``subrepos.allowed``
2322 2328 is true.
2323 2329 (default: true)
2324 2330
2325 2331 ``git:allowed``
2326 2332 Whether Git subrepositories are allowed in the working directory.
2327 2333 This option only has an effect if ``subrepos.allowed`` is true.
2328 2334
2329 2335 See the security note above before enabling Git subrepos.
2330 2336 (default: false)
2331 2337
2332 2338 ``svn:allowed``
2333 2339 Whether Subversion subrepositories are allowed in the working
2334 2340 directory. This option only has an effect if ``subrepos.allowed``
2335 2341 is true.
2336 2342
2337 2343 See the security note above before enabling Subversion subrepos.
2338 2344 (default: false)
2339 2345
2340 2346 ``templatealias``
2341 2347 -----------------
2342 2348
2343 2349 Alias definitions for templates. See :hg:`help templates` for details.
2344 2350
2345 2351 ``templates``
2346 2352 -------------
2347 2353
2348 2354 Use the ``[templates]`` section to define template strings.
2349 2355 See :hg:`help templates` for details.
2350 2356
2351 2357 ``trusted``
2352 2358 -----------
2353 2359
2354 2360 Mercurial will not use the settings in the
2355 2361 ``.hg/hgrc`` file from a repository if it doesn't belong to a trusted
2356 2362 user or to a trusted group, as various hgrc features allow arbitrary
2357 2363 commands to be run. This issue is often encountered when configuring
2358 2364 hooks or extensions for shared repositories or servers. However,
2359 2365 the web interface will use some safe settings from the ``[web]``
2360 2366 section.
2361 2367
2362 2368 This section specifies what users and groups are trusted. The
2363 2369 current user is always trusted. To trust everybody, list a user or a
2364 2370 group with name ``*``. These settings must be placed in an
2365 2371 *already-trusted file* to take effect, such as ``$HOME/.hgrc`` of the
2366 2372 user or service running Mercurial.
2367 2373
2368 2374 ``users``
2369 2375 Comma-separated list of trusted users.
2370 2376
2371 2377 ``groups``
2372 2378 Comma-separated list of trusted groups.
2373 2379
2374 2380
2375 2381 ``ui``
2376 2382 ------
2377 2383
2378 2384 User interface controls.
2379 2385
2380 2386 ``archivemeta``
2381 2387 Whether to include the .hg_archival.txt file containing meta data
2382 2388 (hashes for the repository base and for tip) in archives created
2383 2389 by the :hg:`archive` command or downloaded via hgweb.
2384 2390 (default: True)
2385 2391
2386 2392 ``askusername``
2387 2393 Whether to prompt for a username when committing. If True, and
2388 2394 neither ``$HGUSER`` nor ``$EMAIL`` has been specified, then the user will
2389 2395 be prompted to enter a username. If no username is entered, the
2390 2396 default ``USER@HOST`` is used instead.
2391 2397 (default: False)
2392 2398
2393 2399 ``clonebundles``
2394 2400 Whether the "clone bundles" feature is enabled.
2395 2401
2396 2402 When enabled, :hg:`clone` may download and apply a server-advertised
2397 2403 bundle file from a URL instead of using the normal exchange mechanism.
2398 2404
2399 2405 This can likely result in faster and more reliable clones.
2400 2406
2401 2407 (default: True)
2402 2408
2403 2409 ``clonebundlefallback``
2404 2410 Whether failure to apply an advertised "clone bundle" from a server
2405 2411 should result in fallback to a regular clone.
2406 2412
2407 2413 This is disabled by default because servers advertising "clone
2408 2414 bundles" often do so to reduce server load. If advertised bundles
2409 2415 start mass failing and clients automatically fall back to a regular
2410 2416 clone, this would add significant and unexpected load to the server
2411 2417 since the server is expecting clone operations to be offloaded to
2412 2418 pre-generated bundles. Failing fast (the default behavior) ensures
2413 2419 clients don't overwhelm the server when "clone bundle" application
2414 2420 fails.
2415 2421
2416 2422 (default: False)
2417 2423
2418 2424 ``clonebundleprefers``
2419 2425 Defines preferences for which "clone bundles" to use.
2420 2426
2421 2427 Servers advertising "clone bundles" may advertise multiple available
2422 2428 bundles. Each bundle may have different attributes, such as the bundle
2423 2429 type and compression format. This option is used to prefer a particular
2424 2430 bundle over another.
2425 2431
2426 2432 The following keys are defined by Mercurial:
2427 2433
2428 2434 BUNDLESPEC
2429 2435 A bundle type specifier. These are strings passed to :hg:`bundle -t`.
2430 2436 e.g. ``gzip-v2`` or ``bzip2-v1``.
2431 2437
2432 2438 COMPRESSION
2433 2439 The compression format of the bundle. e.g. ``gzip`` and ``bzip2``.
2434 2440
2435 2441 Server operators may define custom keys.
2436 2442
2437 2443 Example values: ``COMPRESSION=bzip2``,
2438 2444 ``BUNDLESPEC=gzip-v2, COMPRESSION=gzip``.
2439 2445
2440 2446 By default, the first bundle advertised by the server is used.
2441 2447
2442 2448 ``color``
2443 2449 When to colorize output. Possible value are Boolean ("yes" or "no"), or
2444 2450 "debug", or "always". (default: "yes"). "yes" will use color whenever it
2445 2451 seems possible. See :hg:`help color` for details.
2446 2452
2447 2453 ``commitsubrepos``
2448 2454 Whether to commit modified subrepositories when committing the
2449 2455 parent repository. If False and one subrepository has uncommitted
2450 2456 changes, abort the commit.
2451 2457 (default: False)
2452 2458
2453 2459 ``debug``
2454 2460 Print debugging information. (default: False)
2455 2461
2456 2462 ``editor``
2457 2463 The editor to use during a commit. (default: ``$EDITOR`` or ``vi``)
2458 2464
2459 2465 ``fallbackencoding``
2460 2466 Encoding to try if it's not possible to decode the changelog using
2461 2467 UTF-8. (default: ISO-8859-1)
2462 2468
2463 2469 ``graphnodetemplate``
2464 2470 (DEPRECATED) Use ``command-templates.graphnode`` instead.
2465 2471
2466 2472 ``ignore``
2467 2473 A file to read per-user ignore patterns from. This file should be
2468 2474 in the same format as a repository-wide .hgignore file. Filenames
2469 2475 are relative to the repository root. This option supports hook syntax,
2470 2476 so if you want to specify multiple ignore files, you can do so by
2471 2477 setting something like ``ignore.other = ~/.hgignore2``. For details
2472 2478 of the ignore file format, see the ``hgignore(5)`` man page.
2473 2479
2474 2480 ``interactive``
2475 2481 Allow to prompt the user. (default: True)
2476 2482
2477 2483 ``interface``
2478 2484 Select the default interface for interactive features (default: text).
2479 2485 Possible values are 'text' and 'curses'.
2480 2486
2481 2487 ``interface.chunkselector``
2482 2488 Select the interface for change recording (e.g. :hg:`commit -i`).
2483 2489 Possible values are 'text' and 'curses'.
2484 2490 This config overrides the interface specified by ui.interface.
2485 2491
2486 2492 ``large-file-limit``
2487 2493 Largest file size that gives no memory use warning.
2488 2494 Possible values are integers or 0 to disable the check.
2489 2495 (default: 10000000)
2490 2496
2491 2497 ``logtemplate``
2492 2498 (DEPRECATED) Use ``command-templates.log`` instead.
2493 2499
2494 2500 ``merge``
2495 2501 The conflict resolution program to use during a manual merge.
2496 2502 For more information on merge tools see :hg:`help merge-tools`.
2497 2503 For configuring merge tools see the ``[merge-tools]`` section.
2498 2504
2499 2505 ``mergemarkers``
2500 2506 Sets the merge conflict marker label styling. The ``detailed`` style
2501 2507 uses the ``command-templates.mergemarker`` setting to style the labels.
2502 2508 The ``basic`` style just uses 'local' and 'other' as the marker label.
2503 2509 One of ``basic`` or ``detailed``.
2504 2510 (default: ``basic``)
2505 2511
2506 2512 ``mergemarkertemplate``
2507 2513 (DEPRECATED) Use ``command-templates.mergemarker`` instead.
2508 2514
2509 2515 ``message-output``
2510 2516 Where to write status and error messages. (default: ``stdio``)
2511 2517
2512 2518 ``channel``
2513 2519 Use separate channel for structured output. (Command-server only)
2514 2520 ``stderr``
2515 2521 Everything to stderr.
2516 2522 ``stdio``
2517 2523 Status to stdout, and error to stderr.
2518 2524
2519 2525 ``origbackuppath``
2520 2526 The path to a directory used to store generated .orig files. If the path is
2521 2527 not a directory, one will be created. If set, files stored in this
2522 2528 directory have the same name as the original file and do not have a .orig
2523 2529 suffix.
2524 2530
2525 2531 ``paginate``
2526 2532 Control the pagination of command output (default: True). See :hg:`help pager`
2527 2533 for details.
2528 2534
2529 2535 ``patch``
2530 2536 An optional external tool that ``hg import`` and some extensions
2531 2537 will use for applying patches. By default Mercurial uses an
2532 2538 internal patch utility. The external tool must work as the common
2533 2539 Unix ``patch`` program. In particular, it must accept a ``-p``
2534 2540 argument to strip patch headers, a ``-d`` argument to specify the
2535 2541 current directory, a file name to patch, and a patch file to take
2536 2542 from stdin.
2537 2543
2538 2544 It is possible to specify a patch tool together with extra
2539 2545 arguments. For example, setting this option to ``patch --merge``
2540 2546 will use the ``patch`` program with its 2-way merge option.
2541 2547
2542 2548 ``portablefilenames``
2543 2549 Check for portable filenames. Can be ``warn``, ``ignore`` or ``abort``.
2544 2550 (default: ``warn``)
2545 2551
2546 2552 ``warn``
2547 2553 Print a warning message on POSIX platforms, if a file with a non-portable
2548 2554 filename is added (e.g. a file with a name that can't be created on
2549 2555 Windows because it contains reserved parts like ``AUX``, reserved
2550 2556 characters like ``:``, or would cause a case collision with an existing
2551 2557 file).
2552 2558
2553 2559 ``ignore``
2554 2560 Don't print a warning.
2555 2561
2556 2562 ``abort``
2557 2563 The command is aborted.
2558 2564
2559 2565 ``true``
2560 2566 Alias for ``warn``.
2561 2567
2562 2568 ``false``
2563 2569 Alias for ``ignore``.
2564 2570
2565 2571 .. container:: windows
2566 2572
2567 2573 On Windows, this configuration option is ignored and the command aborted.
2568 2574
2569 2575 ``pre-merge-tool-output-template``
2570 2576 (DEPRECATED) Use ``command-template.pre-merge-tool-output`` instead.
2571 2577
2572 2578 ``quiet``
2573 2579 Reduce the amount of output printed.
2574 2580 (default: False)
2575 2581
2576 2582 ``relative-paths``
2577 2583 Prefer relative paths in the UI.
2578 2584
2579 2585 ``remotecmd``
2580 2586 Remote command to use for clone/push/pull operations.
2581 2587 (default: ``hg``)
2582 2588
2583 2589 ``report_untrusted``
2584 2590 Warn if a ``.hg/hgrc`` file is ignored due to not being owned by a
2585 2591 trusted user or group.
2586 2592 (default: True)
2587 2593
2588 2594 ``slash``
2589 2595 (Deprecated. Use ``slashpath`` template filter instead.)
2590 2596
2591 2597 Display paths using a slash (``/``) as the path separator. This
2592 2598 only makes a difference on systems where the default path
2593 2599 separator is not the slash character (e.g. Windows uses the
2594 2600 backslash character (``\``)).
2595 2601 (default: False)
2596 2602
2597 2603 ``statuscopies``
2598 2604 Display copies in the status command.
2599 2605
2600 2606 ``ssh``
2601 2607 Command to use for SSH connections. (default: ``ssh``)
2602 2608
2603 2609 ``ssherrorhint``
2604 2610 A hint shown to the user in the case of SSH error (e.g.
2605 2611 ``Please see http://company/internalwiki/ssh.html``)
2606 2612
2607 2613 ``strict``
2608 2614 Require exact command names, instead of allowing unambiguous
2609 2615 abbreviations. (default: False)
2610 2616
2611 2617 ``style``
2612 2618 Name of style to use for command output.
2613 2619
2614 2620 ``supportcontact``
2615 2621 A URL where users should report a Mercurial traceback. Use this if you are a
2616 2622 large organisation with its own Mercurial deployment process and crash
2617 2623 reports should be addressed to your internal support.
2618 2624
2619 2625 ``textwidth``
2620 2626 Maximum width of help text. A longer line generated by ``hg help`` or
2621 2627 ``hg subcommand --help`` will be broken after white space to get this
2622 2628 width or the terminal width, whichever comes first.
2623 2629 A non-positive value will disable this and the terminal width will be
2624 2630 used. (default: 78)
2625 2631
2626 2632 ``timeout``
2627 2633 The timeout used when a lock is held (in seconds), a negative value
2628 2634 means no timeout. (default: 600)
2629 2635
2630 2636 ``timeout.warn``
2631 2637 Time (in seconds) before a warning is printed about held lock. A negative
2632 2638 value means no warning. (default: 0)
2633 2639
2634 2640 ``traceback``
2635 2641 Mercurial always prints a traceback when an unknown exception
2636 2642 occurs. Setting this to True will make Mercurial print a traceback
2637 2643 on all exceptions, even those recognized by Mercurial (such as
2638 2644 IOError or MemoryError). (default: False)
2639 2645
2640 2646 ``tweakdefaults``
2641 2647
2642 2648 By default Mercurial's behavior changes very little from release
2643 2649 to release, but over time the recommended config settings
2644 2650 shift. Enable this config to opt in to get automatic tweaks to
2645 2651 Mercurial's behavior over time. This config setting will have no
2646 2652 effect if ``HGPLAIN`` is set or ``HGPLAINEXCEPT`` is set and does
2647 2653 not include ``tweakdefaults``. (default: False)
2648 2654
2649 2655 It currently means::
2650 2656
2651 2657 .. tweakdefaultsmarker
2652 2658
2653 2659 ``username``
2654 2660 The committer of a changeset created when running "commit".
2655 2661 Typically a person's name and email address, e.g. ``Fred Widget
2656 2662 <fred@example.com>``. Environment variables in the
2657 2663 username are expanded.
2658 2664
2659 2665 (default: ``$EMAIL`` or ``username@hostname``. If the username in
2660 2666 hgrc is empty, e.g. if the system admin set ``username =`` in the
2661 2667 system hgrc, it has to be specified manually or in a different
2662 2668 hgrc file)
2663 2669
2664 2670 ``verbose``
2665 2671 Increase the amount of output printed. (default: False)
2666 2672
2667 2673
2668 2674 ``command-templates``
2669 2675 ---------------------
2670 2676
2671 2677 Templates used for customizing the output of commands.
2672 2678
2673 2679 ``graphnode``
2674 2680 The template used to print changeset nodes in an ASCII revision graph.
2675 2681 (default: ``{graphnode}``)
2676 2682
2677 2683 ``log``
2678 2684 Template string for commands that print changesets.
2679 2685
2680 2686 ``mergemarker``
2681 2687 The template used to print the commit description next to each conflict
2682 2688 marker during merge conflicts. See :hg:`help templates` for the template
2683 2689 format.
2684 2690
2685 2691 Defaults to showing the hash, tags, branches, bookmarks, author, and
2686 2692 the first line of the commit description.
2687 2693
2688 2694 If you use non-ASCII characters in names for tags, branches, bookmarks,
2689 2695 authors, and/or commit descriptions, you must pay attention to encodings of
2690 2696 managed files. At template expansion, non-ASCII characters use the encoding
2691 2697 specified by the ``--encoding`` global option, ``HGENCODING`` or other
2692 2698 environment variables that govern your locale. If the encoding of the merge
2693 2699 markers is different from the encoding of the merged files,
2694 2700 serious problems may occur.
2695 2701
2696 2702 Can be overridden per-merge-tool, see the ``[merge-tools]`` section.
2697 2703
2698 2704 ``oneline-summary``
2699 2705 A template used by `hg rebase` and other commands for showing a one-line
2700 2706 summary of a commit. If the template configured here is longer than one
2701 2707 line, then only the first line is used.
2702 2708
2703 2709 The template can be overridden per command by defining a template in
2704 2710 `oneline-summary.<command>`, where `<command>` can be e.g. "rebase".
2705 2711
2706 2712 ``pre-merge-tool-output``
2707 2713 A template that is printed before executing an external merge tool. This can
2708 2714 be used to print out additional context that might be useful to have during
2709 2715 the conflict resolution, such as the description of the various commits
2710 2716 involved or bookmarks/tags.
2711 2717
2712 2718 Additional information is available in the ``local`, ``base``, and ``other``
2713 2719 dicts. For example: ``{local.label}``, ``{base.name}``, or
2714 2720 ``{other.islink}``.
2715 2721
2716 2722
2717 2723 ``web``
2718 2724 -------
2719 2725
2720 2726 Web interface configuration. The settings in this section apply to
2721 2727 both the builtin webserver (started by :hg:`serve`) and the script you
2722 2728 run through a webserver (``hgweb.cgi`` and the derivatives for FastCGI
2723 2729 and WSGI).
2724 2730
2725 2731 The Mercurial webserver does no authentication (it does not prompt for
2726 2732 usernames and passwords to validate *who* users are), but it does do
2727 2733 authorization (it grants or denies access for *authenticated users*
2728 2734 based on settings in this section). You must either configure your
2729 2735 webserver to do authentication for you, or disable the authorization
2730 2736 checks.
2731 2737
2732 2738 For a quick setup in a trusted environment, e.g., a private LAN, where
2733 2739 you want it to accept pushes from anybody, you can use the following
2734 2740 command line::
2735 2741
2736 2742 $ hg --config web.allow-push=* --config web.push_ssl=False serve
2737 2743
2738 2744 Note that this will allow anybody to push anything to the server and
2739 2745 that this should not be used for public servers.
2740 2746
2741 2747 The full set of options is:
2742 2748
2743 2749 ``accesslog``
2744 2750 Where to output the access log. (default: stdout)
2745 2751
2746 2752 ``address``
2747 2753 Interface address to bind to. (default: all)
2748 2754
2749 2755 ``allow-archive``
2750 2756 List of archive format (bz2, gz, zip) allowed for downloading.
2751 2757 (default: empty)
2752 2758
2753 2759 ``allowbz2``
2754 2760 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
2755 2761 revisions.
2756 2762 (default: False)
2757 2763
2758 2764 ``allowgz``
2759 2765 (DEPRECATED) Whether to allow .tar.gz downloading of repository
2760 2766 revisions.
2761 2767 (default: False)
2762 2768
2763 2769 ``allow-pull``
2764 2770 Whether to allow pulling from the repository. (default: True)
2765 2771
2766 2772 ``allow-push``
2767 2773 Whether to allow pushing to the repository. If empty or not set,
2768 2774 pushing is not allowed. If the special value ``*``, any remote
2769 2775 user can push, including unauthenticated users. Otherwise, the
2770 2776 remote user must have been authenticated, and the authenticated
2771 2777 user name must be present in this list. The contents of the
2772 2778 allow-push list are examined after the deny_push list.
2773 2779
2774 2780 ``allow_read``
2775 2781 If the user has not already been denied repository access due to
2776 2782 the contents of deny_read, this list determines whether to grant
2777 2783 repository access to the user. If this list is not empty, and the
2778 2784 user is unauthenticated or not present in the list, then access is
2779 2785 denied for the user. If the list is empty or not set, then access
2780 2786 is permitted to all users by default. Setting allow_read to the
2781 2787 special value ``*`` is equivalent to it not being set (i.e. access
2782 2788 is permitted to all users). The contents of the allow_read list are
2783 2789 examined after the deny_read list.
2784 2790
2785 2791 ``allowzip``
2786 2792 (DEPRECATED) Whether to allow .zip downloading of repository
2787 2793 revisions. This feature creates temporary files.
2788 2794 (default: False)
2789 2795
2790 2796 ``archivesubrepos``
2791 2797 Whether to recurse into subrepositories when archiving.
2792 2798 (default: False)
2793 2799
2794 2800 ``baseurl``
2795 2801 Base URL to use when publishing URLs in other locations, so
2796 2802 third-party tools like email notification hooks can construct
2797 2803 URLs. Example: ``http://hgserver/repos/``.
2798 2804
2799 2805 ``cacerts``
2800 2806 Path to file containing a list of PEM encoded certificate
2801 2807 authority certificates. Environment variables and ``~user``
2802 2808 constructs are expanded in the filename. If specified on the
2803 2809 client, then it will verify the identity of remote HTTPS servers
2804 2810 with these certificates.
2805 2811
2806 2812 To disable SSL verification temporarily, specify ``--insecure`` from
2807 2813 command line.
2808 2814
2809 2815 You can use OpenSSL's CA certificate file if your platform has
2810 2816 one. On most Linux systems this will be
2811 2817 ``/etc/ssl/certs/ca-certificates.crt``. Otherwise you will have to
2812 2818 generate this file manually. The form must be as follows::
2813 2819
2814 2820 -----BEGIN CERTIFICATE-----
2815 2821 ... (certificate in base64 PEM encoding) ...
2816 2822 -----END CERTIFICATE-----
2817 2823 -----BEGIN CERTIFICATE-----
2818 2824 ... (certificate in base64 PEM encoding) ...
2819 2825 -----END CERTIFICATE-----
2820 2826
2821 2827 ``cache``
2822 2828 Whether to support caching in hgweb. (default: True)
2823 2829
2824 2830 ``certificate``
2825 2831 Certificate to use when running :hg:`serve`.
2826 2832
2827 2833 ``collapse``
2828 2834 With ``descend`` enabled, repositories in subdirectories are shown at
2829 2835 a single level alongside repositories in the current path. With
2830 2836 ``collapse`` also enabled, repositories residing at a deeper level than
2831 2837 the current path are grouped behind navigable directory entries that
2832 2838 lead to the locations of these repositories. In effect, this setting
2833 2839 collapses each collection of repositories found within a subdirectory
2834 2840 into a single entry for that subdirectory. (default: False)
2835 2841
2836 2842 ``comparisoncontext``
2837 2843 Number of lines of context to show in side-by-side file comparison. If
2838 2844 negative or the value ``full``, whole files are shown. (default: 5)
2839 2845
2840 2846 This setting can be overridden by a ``context`` request parameter to the
2841 2847 ``comparison`` command, taking the same values.
2842 2848
2843 2849 ``contact``
2844 2850 Name or email address of the person in charge of the repository.
2845 2851 (default: ui.username or ``$EMAIL`` or "unknown" if unset or empty)
2846 2852
2847 2853 ``csp``
2848 2854 Send a ``Content-Security-Policy`` HTTP header with this value.
2849 2855
2850 2856 The value may contain a special string ``%nonce%``, which will be replaced
2851 2857 by a randomly-generated one-time use value. If the value contains
2852 2858 ``%nonce%``, ``web.cache`` will be disabled, as caching undermines the
2853 2859 one-time property of the nonce. This nonce will also be inserted into
2854 2860 ``<script>`` elements containing inline JavaScript.
2855 2861
2856 2862 Note: lots of HTML content sent by the server is derived from repository
2857 2863 data. Please consider the potential for malicious repository data to
2858 2864 "inject" itself into generated HTML content as part of your security
2859 2865 threat model.
2860 2866
2861 2867 ``deny_push``
2862 2868 Whether to deny pushing to the repository. If empty or not set,
2863 2869 push is not denied. If the special value ``*``, all remote users are
2864 2870 denied push. Otherwise, unauthenticated users are all denied, and
2865 2871 any authenticated user name present in this list is also denied. The
2866 2872 contents of the deny_push list are examined before the allow-push list.
2867 2873
2868 2874 ``deny_read``
2869 2875 Whether to deny reading/viewing of the repository. If this list is
2870 2876 not empty, unauthenticated users are all denied, and any
2871 2877 authenticated user name present in this list is also denied access to
2872 2878 the repository. If set to the special value ``*``, all remote users
2873 2879 are denied access (rarely needed ;). If deny_read is empty or not set,
2874 2880 the determination of repository access depends on the presence and
2875 2881 content of the allow_read list (see description). If both
2876 2882 deny_read and allow_read are empty or not set, then access is
2877 2883 permitted to all users by default. If the repository is being
2878 2884 served via hgwebdir, denied users will not be able to see it in
2879 2885 the list of repositories. The contents of the deny_read list have
2880 2886 priority over (are examined before) the contents of the allow_read
2881 2887 list.
2882 2888
2883 2889 ``descend``
2884 2890 hgwebdir indexes will not descend into subdirectories. Only repositories
2885 2891 directly in the current path will be shown (other repositories are still
2886 2892 available from the index corresponding to their containing path).
2887 2893
2888 2894 ``description``
2889 2895 Textual description of the repository's purpose or contents.
2890 2896 (default: "unknown")
2891 2897
2892 2898 ``encoding``
2893 2899 Character encoding name. (default: the current locale charset)
2894 2900 Example: "UTF-8".
2895 2901
2896 2902 ``errorlog``
2897 2903 Where to output the error log. (default: stderr)
2898 2904
2899 2905 ``guessmime``
2900 2906 Control MIME types for raw download of file content.
2901 2907 Set to True to let hgweb guess the content type from the file
2902 2908 extension. This will serve HTML files as ``text/html`` and might
2903 2909 allow cross-site scripting attacks when serving untrusted
2904 2910 repositories. (default: False)
2905 2911
2906 2912 ``hidden``
2907 2913 Whether to hide the repository in the hgwebdir index.
2908 2914 (default: False)
2909 2915
2910 2916 ``ipv6``
2911 2917 Whether to use IPv6. (default: False)
2912 2918
2913 2919 ``labels``
2914 2920 List of string *labels* associated with the repository.
2915 2921
2916 2922 Labels are exposed as a template keyword and can be used to customize
2917 2923 output. e.g. the ``index`` template can group or filter repositories
2918 2924 by labels and the ``summary`` template can display additional content
2919 2925 if a specific label is present.
2920 2926
2921 2927 ``logoimg``
2922 2928 File name of the logo image that some templates display on each page.
2923 2929 The file name is relative to ``staticurl``. That is, the full path to
2924 2930 the logo image is "staticurl/logoimg".
2925 2931 If unset, ``hglogo.png`` will be used.
2926 2932
2927 2933 ``logourl``
2928 2934 Base URL to use for logos. If unset, ``https://mercurial-scm.org/``
2929 2935 will be used.
2930 2936
2931 2937 ``maxchanges``
2932 2938 Maximum number of changes to list on the changelog. (default: 10)
2933 2939
2934 2940 ``maxfiles``
2935 2941 Maximum number of files to list per changeset. (default: 10)
2936 2942
2937 2943 ``maxshortchanges``
2938 2944 Maximum number of changes to list on the shortlog, graph or filelog
2939 2945 pages. (default: 60)
2940 2946
2941 2947 ``name``
2942 2948 Repository name to use in the web interface.
2943 2949 (default: current working directory)
2944 2950
2945 2951 ``port``
2946 2952 Port to listen on. (default: 8000)
2947 2953
2948 2954 ``prefix``
2949 2955 Prefix path to serve from. (default: '' (server root))
2950 2956
2951 2957 ``push_ssl``
2952 2958 Whether to require that inbound pushes be transported over SSL to
2953 2959 prevent password sniffing. (default: True)
2954 2960
2955 2961 ``refreshinterval``
2956 2962 How frequently directory listings re-scan the filesystem for new
2957 2963 repositories, in seconds. This is relevant when wildcards are used
2958 2964 to define paths. Depending on how much filesystem traversal is
2959 2965 required, refreshing may negatively impact performance.
2960 2966
2961 2967 Values less than or equal to 0 always refresh.
2962 2968 (default: 20)
2963 2969
2964 2970 ``server-header``
2965 2971 Value for HTTP ``Server`` response header.
2966 2972
2967 2973 ``static``
2968 2974 Directory where static files are served from.
2969 2975
2970 2976 ``staticurl``
2971 2977 Base URL to use for static files. If unset, static files (e.g. the
2972 2978 hgicon.png favicon) will be served by the CGI script itself. Use
2973 2979 this setting to serve them directly with the HTTP server.
2974 2980 Example: ``http://hgserver/static/``.
2975 2981
2976 2982 ``stripes``
2977 2983 How many lines a "zebra stripe" should span in multi-line output.
2978 2984 Set to 0 to disable. (default: 1)
2979 2985
2980 2986 ``style``
2981 2987 Which template map style to use. The available options are the names of
2982 2988 subdirectories in the HTML templates path. (default: ``paper``)
2983 2989 Example: ``monoblue``.
2984 2990
2985 2991 ``templates``
2986 2992 Where to find the HTML templates. The default path to the HTML templates
2987 2993 can be obtained from ``hg debuginstall``.
2988 2994
2989 2995 ``websub``
2990 2996 ----------
2991 2997
2992 2998 Web substitution filter definition. You can use this section to
2993 2999 define a set of regular expression substitution patterns which
2994 3000 let you automatically modify the hgweb server output.
2995 3001
2996 3002 The default hgweb templates only apply these substitution patterns
2997 3003 on the revision description fields. You can apply them anywhere
2998 3004 you want when you create your own templates by adding calls to the
2999 3005 "websub" filter (usually after calling the "escape" filter).
3000 3006
3001 3007 This can be used, for example, to convert issue references to links
3002 3008 to your issue tracker, or to convert "markdown-like" syntax into
3003 3009 HTML (see the examples below).
3004 3010
3005 3011 Each entry in this section names a substitution filter.
3006 3012 The value of each entry defines the substitution expression itself.
3007 3013 The websub expressions follow the old interhg extension syntax,
3008 3014 which in turn imitates the Unix sed replacement syntax::
3009 3015
3010 3016 patternname = s/SEARCH_REGEX/REPLACE_EXPRESSION/[i]
3011 3017
3012 3018 You can use any separator other than "/". The final "i" is optional
3013 3019 and indicates that the search must be case insensitive.
3014 3020
3015 3021 Examples::
3016 3022
3017 3023 [websub]
3018 3024 issues = s|issue(\d+)|<a href="http://bts.example.org/issue\1">issue\1</a>|i
3019 3025 italic = s/\b_(\S+)_\b/<i>\1<\/i>/
3020 3026 bold = s/\*\b(\S+)\b\*/<b>\1<\/b>/
3021 3027
3022 3028 ``worker``
3023 3029 ----------
3024 3030
3025 3031 Parallel master/worker configuration. We currently perform working
3026 3032 directory updates in parallel on Unix-like systems, which greatly
3027 3033 helps performance.
3028 3034
3029 3035 ``enabled``
3030 3036 Whether to enable workers code to be used.
3031 3037 (default: true)
3032 3038
3033 3039 ``numcpus``
3034 3040 Number of CPUs to use for parallel operations. A zero or
3035 3041 negative value is treated as ``use the default``.
3036 3042 (default: 4 or the number of CPUs on the system, whichever is larger)
3037 3043
3038 3044 ``backgroundclose``
3039 3045 Whether to enable closing file handles on background threads during certain
3040 3046 operations. Some platforms aren't very efficient at closing file
3041 3047 handles that have been written or appended to. By performing file closing
3042 3048 on background threads, file write rate can increase substantially.
3043 3049 (default: true on Windows, false elsewhere)
3044 3050
3045 3051 ``backgroundcloseminfilecount``
3046 3052 Minimum number of files required to trigger background file closing.
3047 3053 Operations not writing this many files won't start background close
3048 3054 threads.
3049 3055 (default: 2048)
3050 3056
3051 3057 ``backgroundclosemaxqueue``
3052 3058 The maximum number of opened file handles waiting to be closed in the
3053 3059 background. This option only has an effect if ``backgroundclose`` is
3054 3060 enabled.
3055 3061 (default: 384)
3056 3062
3057 3063 ``backgroundclosethreadcount``
3058 3064 Number of threads to process background file closes. Only relevant if
3059 3065 ``backgroundclose`` is enabled.
3060 3066 (default: 4)
General Comments 0
You need to be logged in to leave comments. Login now