Mercurial > hg
view mercurial/help/internals/config.txt @ 34932:fd78276948b4 stable
internal-doc: document the config register mechanism
This explains the various usage and feature of the config register introduced
in Mercurial 4.3 and 4.4.
author | Boris Feld <boris.feld@octobus.net> |
---|---|
date | Fri, 27 Oct 2017 18:19:07 +0200 |
parents | |
children | ff178743e59b |
line wrap: on
line source
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 value 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 value for the ``default`` parameters. A default value is then explicitly required when reading the option:: # registration coreconfigitem('web', 'name', default=dynamicdefault, ) # usage ui.config('web', 'name', dirnam) 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 control 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 version ------------------------ The register was introduced in Mercurial 4.3, 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 version older than Mercurial-4.3 cannot rely on the default value registered. The simplest way to register option while still supporting older version is to use ``dynamicdefault`` for option requiring a default value. The existing code passing an explicit default can then stay in use until compatibility to Mercurial 4.2 is dropped. As reminder here are the default value for each config types: - config: None - configbool: False - configbytes: 0 - configdate: None - configint: None - configlist: [] - configpath: None