##// END OF EJS Templates
help: unjumble the list of default config values for `internals.config`
Matt Harbison -
r40602:5b530d76 stable
parent child Browse files
Show More
@@ -1,108 +1,109 b''
1 All config options used within Mercurial should be registered.
1 All config options used within Mercurial should be registered.
2
2
3 Config Option in Core
3 Config Option in Core
4 =====================
4 =====================
5
5
6 Config options used by Mercurial core are registered in the
6 Config options used by Mercurial core are registered in the
7 ``mercurial.configitems`` module.
7 ``mercurial.configitems`` module.
8
8
9 Simple entry
9 Simple entry
10 ------------
10 ------------
11
11
12 A registration entry typically looks like::
12 A registration entry typically looks like::
13
13
14 coreconfigitem('section', 'option',
14 coreconfigitem('section', 'option',
15 default=MyDefaultValue,
15 default=MyDefaultValue,
16 )
16 )
17
17
18 Once registered, Mercurial will know that ``section.option`` is a legitimate
18 Once registered, Mercurial will know that ``section.option`` is a legitimate
19 config option and that ``MyDefaultValue`` should be used if no other values are
19 config option and that ``MyDefaultValue`` should be used if no other values are
20 defined in configuration files.
20 defined in configuration files.
21
21
22 Complex default value
22 Complex default value
23 ---------------------
23 ---------------------
24
24
25 If the default provided is a callable, it is called to retrieve the default
25 If the default provided is a callable, it is called to retrieve the default
26 value when accessing the config option. This is useful for default values that
26 value when accessing the config option. This is useful for default values that
27 are mutable like the empty list::
27 are mutable like the empty list::
28
28
29 coreconfigitem('pager', 'ignore',
29 coreconfigitem('pager', 'ignore',
30 default=list,
30 default=list,
31 )
31 )
32
32
33 In addition, there are cases where the default is not fixed, but computed from
33 In addition, there are cases where the default is not fixed, but computed from
34 other properties. In this case, use the ``dynamicdefault`` object as the value
34 other properties. In this case, use the ``dynamicdefault`` object as the value
35 for the ``default`` parameter. A default value is then explicitly required when
35 for the ``default`` parameter. A default value is then explicitly required when
36 reading the option::
36 reading the option::
37
37
38 # registration
38 # registration
39 coreconfigitem('web', 'name',
39 coreconfigitem('web', 'name',
40 default=dynamicdefault,
40 default=dynamicdefault,
41 )
41 )
42
42
43 # usage
43 # usage
44 ui.config('web', 'name', dirname)
44 ui.config('web', 'name', dirname)
45
45
46 Free form options
46 Free form options
47 -----------------
47 -----------------
48
48
49 Some config sections use free form options (e.g. ``paths``). You can register
49 Some config sections use free form options (e.g. ``paths``). You can register
50 them using the ``generic`` parameters::
50 them using the ``generic`` parameters::
51
51
52 coreconfigitem('paths', '.*',
52 coreconfigitem('paths', '.*',
53 default=None,
53 default=None,
54 generic=True,
54 generic=True,
55 )
55 )
56
56
57 When ``generic=True`` is set, the option name is matched as a regular expression
57 When ``generic=True`` is set, the option name is matched as a regular expression
58 (rooted to string start). It can be used to select specific sub parameters::
58 (rooted to string start). It can be used to select specific sub parameters::
59
59
60 coreconfigitem('merge-tools', br'.*\.args$',
60 coreconfigitem('merge-tools', br'.*\.args$',
61 default="$local $base $other",
61 default="$local $base $other",
62 generic=True,
62 generic=True,
63 priority=-1,
63 priority=-1,
64 )
64 )
65
65
66 The ``priority`` parameter controls the order used to match the generic pattern
66 The ``priority`` parameter controls the order used to match the generic pattern
67 (lower first).
67 (lower first).
68
68
69 Config Option in Extensions
69 Config Option in Extensions
70 ===========================
70 ===========================
71
71
72 General case
72 General case
73 ------------
73 ------------
74
74
75 Extensions should register config items through the ``registrar`` API (also used
75 Extensions should register config items through the ``registrar`` API (also used
76 for commands and others)::
76 for commands and others)::
77
77
78 configtable = {}
78 configtable = {}
79 configitem = registrar.configitem(configtable)
79 configitem = registrar.configitem(configtable)
80
80
81 configitem('blackbox', 'dirty',
81 configitem('blackbox', 'dirty',
82 default=False,
82 default=False,
83 )
83 )
84
84
85 The ``dynamicdefault`` object is then available as
85 The ``dynamicdefault`` object is then available as
86 ``configitem.dynamicdefault``.
86 ``configitem.dynamicdefault``.
87
87
88 Supporting older versions
88 Supporting older versions
89 -------------------------
89 -------------------------
90
90
91 The registrar was introduced in Mercurial 4.3, and the ``generic`` parameter was
91 The registrar was introduced in Mercurial 4.3, and the ``generic`` parameter was
92 introduced in 4.4. Starting with Mercurial 4.4, all core options were registered
92 introduced in 4.4. Starting with Mercurial 4.4, all core options were registered
93 and developer warnings are emitted when accessing unregistered option.
93 and developer warnings are emitted when accessing unregistered option.
94
94
95 Extensions supporting versions older than Mercurial 4.3 cannot rely on the
95 Extensions supporting versions older than Mercurial 4.3 cannot rely on the
96 default value being registered. The simplest way to register an option while
96 default value being registered. The simplest way to register an option while
97 still supporting an older version is to use ``dynamicdefault`` for options
97 still supporting an older version is to use ``dynamicdefault`` for options
98 requiring a default value. The existing code passing an explicit default can
98 requiring a default value. The existing code passing an explicit default can
99 then stay in use until compatibility with Mercurial 4.2 is dropped.
99 then stay in use until compatibility with Mercurial 4.2 is dropped.
100
100
101 As reminder, here are the default values for each config type:
101 As reminder, here are the default values for each config type:
102 - config: None
102
103 - configbool: False
103 - config: None
104 - configbytes: 0
104 - configbool: False
105 - configdate: None
105 - configbytes: 0
106 - configint: None
106 - configdate: None
107 - configlist: []
107 - configint: None
108 - configpath: None
108 - configlist: []
109 - configpath: None
General Comments 0
You need to be logged in to leave comments. Login now