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). To map an inbox to more than one repository (e.g., if the inbox receives patches for multiple projects, or if you use a few dedicated Git worktrees for different types of patches), set :coderepo to a list of locations.

When using the Debbugs instance at https://bugs.gnu.org to retrieve messages, an inbox can mapped to each message by setting :gnu-package for an inbox.

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.