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 |
- config |
|
105 | - configbytes: 0 | |
106 |
- config |
|
106 | - configdate: None | |
107 |
- config |
|
107 | - configint: None | |
108 |
- config |
|
108 | - configlist: [] | |
|
109 | - configpath: None |
General Comments 0
You need to be logged in to leave comments.
Login now