mercurial/help/internals/config.txt

34947:ff2110eadbfa

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

        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
===========================

    )

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

34948:ff178743e59b

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

        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
===========================

    )

The ``dynamicdefault`` object is then available as
``configitem.dynamicdefault``.

Supporting older versions
-------------------------

The registry 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