|
|
All config options used within Mercurial should be registered.
|
|
|
|
|
|
Config Option in Core
|
|
|
=====================
|
|
|
|
|
|
Config options used by Mercurial core are registered in the
|
|
|
``mercurial.configitems`` module.
|
|
|
|
|
|
Simple entry
|
|
|
------------
|
|
|
|
|
|
A registration entry typically looks like::
|
|
|
|
|
|
coreconfigitem('section', 'option',
|
|
|
default=MyDefaultValue,
|
|
|
)
|
|
|
|
|
|
Once registered, Mercurial will know that ``section.option`` is a legitimate
|
|
|
config option and that ``MyDefaultValue`` should be used if no other values are
|
|
|
defined in configuration files.
|
|
|
|
|
|
Complex default value
|
|
|
---------------------
|
|
|
|
|
|
If the default provided is a callable, it is called to retrieve the default
|
|
|
value when accessing the config option. This is useful for default values that
|
|
|
are mutable like the empty list::
|
|
|
|
|
|
coreconfigitem('pager', 'ignore',
|
|
|
default=list,
|
|
|
)
|
|
|
|
|
|
In addition, there are cases where the default is not fixed, but computed from
|
|
|
other properties. In this case, use the ``dynamicdefault`` object as the value
|
|
|
for the ``default`` parameter. A default value is then explicitly required when
|
|
|
reading the option::
|
|
|
|
|
|
# registration
|
|
|
coreconfigitem('web', 'name',
|
|
|
default=dynamicdefault,
|
|
|
)
|
|
|
|
|
|
# usage
|
|
|
ui.config('web', 'name', dirname)
|
|
|
|
|
|
Free form options
|
|
|
-----------------
|
|
|
|
|
|
Some config sections use free form options (e.g. ``paths``). You can register
|
|
|
them using the ``generic`` parameters::
|
|
|
|
|
|
coreconfigitem('paths', '.*',
|
|
|
default=None,
|
|
|
generic=True,
|
|
|
)
|
|
|
|
|
|
When ``generic=True`` is set, the option name is matched as a regular expression
|
|
|
(rooted to string start). It can be used to select specific sub parameters::
|
|
|
|
|
|
coreconfigitem('merge-tools', br'.*\.args$',
|
|
|
default="$local $base $other",
|
|
|
generic=True,
|
|
|
priority=-1,
|
|
|
)
|
|
|
|
|
|
The ``priority`` parameter controls the order used to match the generic pattern
|
|
|
(lower first).
|
|
|
|
|
|
Config Option in Extensions
|
|
|
===========================
|
|
|
|
|
|
General case
|
|
|
------------
|
|
|
|
|
|
Extensions should register config items through the ``registrar`` API (also used
|
|
|
for commands and others)::
|
|
|
|
|
|
configtable = {}
|
|
|
configitem = registrar.configitem(configtable)
|
|
|
|
|
|
configitem('blackbox', 'dirty',
|
|
|
default=False,
|
|
|
)
|
|
|
|
|
|
The ``dynamicdefault`` object is then available as
|
|
|
``configitem.dynamicdefault``.
|
|
|
|
|
|
Supporting older versions
|
|
|
-------------------------
|
|
|
|
|
|
The registrar was introduced in Mercurial 4.3, and the ``generic`` parameter was
|
|
|
introduced in 4.4. Starting with Mercurial 4.4, all core options were registered
|
|
|
and developer warnings are emitted when accessing unregistered option.
|
|
|
|
|
|
Extensions supporting versions older than Mercurial 4.3 cannot rely on the
|
|
|
default value being registered. The simplest way to register an option while
|
|
|
still supporting an older version is to use ``dynamicdefault`` for options
|
|
|
requiring a default value. The existing code passing an explicit default can
|
|
|
then stay in use until compatibility with Mercurial 4.2 is dropped.
|
|
|
|
|
|
As reminder, here are the default values for each config type:
|
|
|
- config: None
|
|
|
- configbool: False
|
|
|
- configbytes: 0
|
|
|
- configdate: None
|
|
|
- configint: None
|
|
|
- configlist: []
|
|
|
- configpath: None
|
|
|
|
