moinsetup

Help

Config Registrar
""""""""""""""""

    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