2.1 Registering inboxes

A public-inbox archive, referred to as an inbox, is registered by adding an entry to piem-inboxes. Here’s an example entry for the Git project’s mailing list:

("git"
 :url "https://lore.kernel.org/git/"
 :address "git@vger.kernel.org"
 :listid "git.vger.kernel.org"
 :coderepo "~/src/git/")

The first element is a name for the inbox and will typically match the name at the end of the :url value. Specifying either :listid or :address is important so that a message in a buffer can be mapped to an inbox in piem-inboxes.

:coderepo points to the working tree of a local Git repository that contains code related to that archive (in the example above, a local clone of https://git.kernel.org/pub/scm/git/git.git/). This information is required to apply patches from an archive to a local code repository (see Applying patches).

If you mirror some inboxes locally (e.g., for fast local access or for use with lei), you don’t need to duplicate the information from your public-inbox configuration (public-inbox-config(5)). When the option piem-get-inboxes-from-config is non-nil, the function piem-merged-inboxes, which all code should use for accessing the registered inboxes, returns a combined set of inboxes derived from piem-inboxes and public-inbox’s configuration. Merging is done at the level of inbox properties (e.g., an inbox’s URL may be defined in piem-inboxes and the inbox’s address in public-inbox’s configuration). When a value is defined in both sources, the one in piem-inboxes takes precedence.

Properties described for piem-inboxes are constructed by mapping

[publicinbox $inbox]
$name = $value

to

  ($inbox :$name $value ...)

The one exception is :coderepo. In public-inbox’s configuration, the value of publicinbox.$inbox.coderepo points to another configuration option, coderepo.$value.dir, which in turn points to a repository’s git directory. The :coderepo of piem-inboxes, however, should be set to the working tree, so :coderepo is derived from the value of coderepo.$value.dir, stripping a trailing /.git if present.

Note that piem-merged-inboxes reads from the public-inbox configuration once, generates the merged set of inboxes, and then caches the result. If you change piem-inboxes outside the customize interface or change public-inbox’s configuration, you need to call the command piem-clear-merged-inboxes to clear the cache.