comparison mercurial/help/internals/extensions.txt @ 40729:c93d046d4300

extensions: add "uipopulate" hook, called per instance, not per process

In short, this is the "reposetup" function for ui. It allows us to modify
ui attributes without extending ui.__class__. Before, the only way to do
that was to abuse the config dictionary, which is copied across ui instances.

See the next patch for usage example.

40728:2cd5f1fac788

Command table setup
-------------------

After ``extsetup``, the ``cmdtable`` is copied into the global command table
in Mercurial.

Repository setup
----------------

Extensions can implement an optional callback named ``reposetup``. It is

* Changes that need to be visible by other extensions: because initialization
  occurs in phases (all extensions run ``uisetup``, then all run ``extsetup``),
  a change made here will be visible by other extensions during ``extsetup``.
* Monkeypatches or function wraps (``extensions.wrapfunction``) of ``dispatch``
  module members
* Setup of ``pre-*`` and ``post-*`` hooks
* ``pushkey`` setup

extsetup
--------

* Changes depending on the status of other extensions. (``if extensions.find('mq')``)
* Add a global option to all commands
* Extend revsets

reposetup
---------

* All hooks but ``pre-*`` and ``post-*``
* Modify configuration variables
* Changes to ``repo.__class__``, ``repo.dirstate.__class__``

40729:c93d046d4300

Command table setup
-------------------

After ``extsetup``, the ``cmdtable`` is copied into the global command table
in Mercurial.

Ui instance setup
-----------------

The optional ``uipopulate`` is called for each ``ui`` instance after
configuration is loaded, where extensions can set up additional ui members,
update configuration by ``ui.setconfig()``, and extend the class dynamically.

Typically there are three ``ui`` instances involved in command execution:

``req.ui`` (or ``repo.baseui``)
    Only system and user configurations are loaded into it.
``lui``
    Local repository configuration is loaded as well. This will be used at
    early dispatching stage where a repository isn't available.
``repo.ui``
    The fully-loaded ``ui`` used after a repository is instantiated. This
    will be created from the ``req.ui`` per repository.

In command server and hgweb, this may be called more than once for the same
``ui`` instance.

(New in Mercurial 4.9)

Repository setup
----------------

Extensions can implement an optional callback named ``reposetup``. It is

* Changes that need to be visible by other extensions: because initialization
  occurs in phases (all extensions run ``uisetup``, then all run ``extsetup``),
  a change made here will be visible by other extensions during ``extsetup``.
* Monkeypatches or function wraps (``extensions.wrapfunction``) of ``dispatch``
  module members
* Set up ``pre-*`` and ``post-*`` hooks. (DEPRECATED. ``uipopulate`` is
  preferred on Mercurial 4.9 and later.)
* ``pushkey`` setup

extsetup
--------

* Changes depending on the status of other extensions. (``if extensions.find('mq')``)
* Add a global option to all commands
* Extend revsets

uipopulate
----------

* Modify ``ui`` instance attributes and configuration variables.
* Changes to ``ui.__class__`` per instance.
* Set up all hooks per scoped configuration.

reposetup
---------

* Set up all hooks but ``pre-*`` and ``post-*``. (DEPRECATED. ``uipopulate`` is
  preferred on Mercurial 4.9 and later.)
* Modify configuration variables
* Changes to ``repo.__class__``, ``repo.dirstate.__class__``