Mercurial > public > mercurial-scm > hg-stable

annotate mercurial/help/internals/config.txt @ 40450:41f0529b5112 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commandserver: get around ETIMEDOUT raised by selectors2 selector.select() should exits with an empty event list on timed out, but selectors2 raises OSError if timeout expires while recovering from EINTR. Spotted while debugging new chg feature.
author Yuya Nishihara <yuya@tcha.org>
date Mon, 03 Dec 2018 21:45:15 +0900
parents 5b530d767e67
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
1 All config options used within Mercurial should be registered.
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
2
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
3 Config Option in Core
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
4 =====================
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
5
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
6 Config options used by Mercurial core are registered in the
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
7 ``mercurial.configitems`` module.
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
8
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
9 Simple entry
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
10 ------------
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
11
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
12 A registration entry typically looks like::
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
13
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
14 coreconfigitem('section', 'option',
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
15 default=MyDefaultValue,
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
16 )
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
17
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
18 Once registered, Mercurial will know that ``section.option`` is a legitimate
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
19 config option and that ``MyDefaultValue`` should be used if no other values are
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
20 defined in configuration files.
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
21
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
22 Complex default value
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
23 ---------------------
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
24
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
25 If the default provided is a callable, it is called to retrieve the default
34948
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
26 value when accessing the config option. This is useful for default values that
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
27 are mutable like the empty list::
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
28
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
29 coreconfigitem('pager', 'ignore',
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
30 default=list,
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
31 )
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
32
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
33 In addition, there are cases where the default is not fixed, but computed from
34948
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
34 other properties. In this case, use the ``dynamicdefault`` object as the value
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
35 for the ``default`` parameter. A default value is then explicitly required when
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
36 reading the option::
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
37
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
38 # registration
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
39 coreconfigitem('web', 'name',
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
40 default=dynamicdefault,
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
41 )
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
42
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
43 # usage
34948
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
44 ui.config('web', 'name', dirname)
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
45
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
46 Free form options
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
47 -----------------
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
48
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
49 Some config sections use free form options (e.g. ``paths``). You can register
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
50 them using the ``generic`` parameters::
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
51
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
52 coreconfigitem('paths', '.*',
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
53 default=None,
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
54 generic=True,
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
55 )
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
56
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
57 When ``generic=True`` is set, the option name is matched as a regular expression
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
58 (rooted to string start). It can be used to select specific sub parameters::
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
59
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
60 coreconfigitem('merge-tools', br'.*\.args$',
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
61 default="$local $base $other",
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
62 generic=True,
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
63 priority=-1,
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
64 )
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
65
34948
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
66 The ``priority`` parameter controls the order used to match the generic pattern
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
67 (lower first).
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
68
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
69 Config Option in Extensions
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
70 ===========================
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
71
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
72 General case
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
73 ------------
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
74
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
75 Extensions should register config items through the ``registrar`` API (also used
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
76 for commands and others)::
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
77
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
78 configtable = {}
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
79 configitem = registrar.configitem(configtable)
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
80
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
81 configitem('blackbox', 'dirty',
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
82 default=False,
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
83 )
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
84
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
85 The ``dynamicdefault`` object is then available as
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
86 ``configitem.dynamicdefault``.
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
87
34948
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
88 Supporting older versions
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
89 -------------------------
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
90
34951
fb7f58daca48 internals: copy-edit "register" -> "registrar" in configitem docs
Kevin Bullock <kbullock+mercurial@ringworld.org>
parents: 34948
diff changeset
91 The registrar was introduced in Mercurial 4.3, and the ``generic`` parameter was
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
92 introduced in 4.4. Starting with Mercurial 4.4, all core options were registered
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
93 and developer warnings are emitted when accessing unregistered option.
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
94
34948
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
95 Extensions supporting versions older than Mercurial 4.3 cannot rely on the
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
96 default value being registered. The simplest way to register an option while
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
97 still supporting an older version is to use ``dynamicdefault`` for options
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
98 requiring a default value. The existing code passing an explicit default can
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
99 then stay in use until compatibility with Mercurial 4.2 is dropped.
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
100
34948
ff178743e59b help: minor copy editing for grammar
Matt Harbison <matt_harbison@yahoo.com>
parents: 34932
diff changeset
101 As reminder, here are the default values for each config type:
40433
5b530d767e67 help: unjumble the list of default config values for `internals.config`
Matt Harbison <matt_harbison@yahoo.com>
parents: 34951
diff changeset
102
5b530d767e67 help: unjumble the list of default config values for `internals.config`
Matt Harbison <matt_harbison@yahoo.com>
parents: 34951
diff changeset
103 - config: None
5b530d767e67 help: unjumble the list of default config values for `internals.config`
Matt Harbison <matt_harbison@yahoo.com>
parents: 34951
diff changeset
104 - configbool: False
5b530d767e67 help: unjumble the list of default config values for `internals.config`
Matt Harbison <matt_harbison@yahoo.com>
parents: 34951
diff changeset
105 - configbytes: 0
5b530d767e67 help: unjumble the list of default config values for `internals.config`
Matt Harbison <matt_harbison@yahoo.com>
parents: 34951
diff changeset
106 - configdate: None
5b530d767e67 help: unjumble the list of default config values for `internals.config`
Matt Harbison <matt_harbison@yahoo.com>
parents: 34951
diff changeset
107 - configint: None
5b530d767e67 help: unjumble the list of default config values for `internals.config`
Matt Harbison <matt_harbison@yahoo.com>
parents: 34951
diff changeset
108 - configlist: []
5b530d767e67 help: unjumble the list of default config values for `internals.config`
Matt Harbison <matt_harbison@yahoo.com>
parents: 34951
diff changeset
109 - configpath: None