public-inbox-config - public-inbox config file description


    The public-inbox config file is parseable by git-config(1). This is a
    global configuration file for mapping/discovering all public-inboxes
    used by a particular user.

            [publicinbox "test"]
                    inboxdir = /home/user/path/to/test.git
                    ; multiple addresses are supported
                    address =
                    ; address =
                    url =
                    newsgroup = inbox.test

                    ; backwards compatibility with public-inbox pre-1.2.0,
                    ; "inboxdir" takes precedence over "mainrepo"
                    mainrepo = /home/user/path/to/test.git

            The email address of the public-inbox. May be specified more
            than once for merging multiple mailing lists (or migrating to
            new addresses). This must be specified at least once, the first
            value will be considered the primary address for informational

            Default: none, required

            The absolute path to the directory which hosts the public-inbox.
            This must be specified once.

            This was previously known as "mainrepo", which remains
            supported, but "inboxdir" takes precedence.

            Default: none, required

            The primary URL for hosting the HTTP/HTTPS archives. Additional
            HTTP/HTTPS URLs may be specified via "$GIT_DIR/cloneurl" as
            documented in gitweb(1)

            Default: none, optional

            The NNTP group name for use with public-inbox-nntpd(8). This may
            be any newsgroup name with hierarchies delimited by ".". For
            example, the newsgroup for <> is:

            Omitting this for the given inbox will prevent the group from
            being read by public-inbox-nntpd(1)

            Default: none, optional

            See public-inbox-watch(1)

            See public-inbox-watch(1)

            The rfc2919 <> header without
            angle brackets for public-inbox-mda(1) deliveries and

            For public-inbox-watch users, this is a shortcut for specifying

            For public-inbox-mda users, this may be used to avoid recipient
            matching via "ORIGINAL_RECIPIENT" environment variable.

            This may be specified multiple times for merging multiple
            mailing lists into a single public-inbox, only one "List-Id"
            header needs to match.

            Default: none

            This may be the full NNTP URL of an independently-run mirror.
            For example, the inbox is
            mirrored by Gmane at

            Default: none

            The indexing level for public-inbox-index(1)

            "basic" only requires DBD::SQLite(3pm) and provides all NNTP
            functionality along with thread-awareness in the WWW interface.

            "medium" requires Search::Xapian(3pm) to provide full-text term
            search functionality in the WWW UI.

            "full" also includes positional information used by Xapian to
            allow for searching for phrases using quoted text. (e.g.
            "looking for a complete sentence")

            Default: "full"

            See "publicInbox.indexSequentialShard" in public-inbox-index(1)

            If a digit, the maximum number of parallel git-http-backend(1)
            processes to allow for cloning this particular inbox.

            If an alphanumeric value starting with a lowercase alphabetic
            character is specified, the inbox will use a "NAMED LIMITER"
            which can be shared by multiple inboxes.

            Default: 32 (using a default limiter shared by all inboxes)

            The nickname of a "coderepo" section associated with the inbox.
            May be specified more than once for M:N mapping of code repos to
            inboxes. If enabled, diff hunk headers in patch emails will link
            to the line numbers of blobs.

            Default: none

            May be used to control how reply instructions in the PSGI
            interface are displayed.

            ":none=dead inbox" may be specified to denote an inactive list
            ("dead inbox" may be replaced with another phrase).

            A list of comma-delimited email addresses may be specified. This
            can be useful for dedicated inboxes for bot emails, but
            discussion happens on a separate mailing list/inbox.

            Mirrors of existing centralized mailing lists may use ":list"
            here to redirect mail only to the configured inbox address. The
            use of ":list" is discouraged for new mailing lists, as it leads
            to centralization.

            Default: :all

            The local path name of a CSS file for the PSGI web interface.
            May contain the attributes "media", "title" and "href" which
            match the associated attributes of the HTML <style> tag. "href"
            may be specified to point to the URL of an remote CSS file and
            the path may be "/dev/null" or any empty file. Multiple files
            may be specified and will be included in the order specified.

            This may be set to "none" to disable the use of SpamAssassin
            spamc(1) for filtering spam before it is imported into git
            history. Other spam filtering backends may be supported in the

            Default: spamc

            See public-inbox-watch(1)

            See public-inbox-watch(1)

            Set this to point to the hostname of the public-inbox-nntpd(1)
            instance. This is used to advertise the existence of the NNTP
            endpoint in the PublicInbox::WWW HTML interface.

            Multiple values are allowed for instances with multiple
            hostnames or mirrors.

            Default: none

            The size of an Atom feed for the inbox. If specified more than
            once, only the last value is used. Invalid values (<= 0) will be
            treated as the default value.

            Default: 25

            A comma-delimited list of listings to hide the inbox from.

            Valid values are currently "www" and "manifest".

            Default: none

            The path to a git repository for "publicinbox.<name>.coderepo"

            The URL of the cgit instance associated with the coderepo.

            Default: none

            A path to a cgitrc(5) file. "repo.url" directives in the cgitrc
            will be mapped to the nickname of a coderepo (without trailing
            slash), and "repo.path" directives map to "coderepo.<nick>.dir".
            Use of this directive allows admins of existing cgit
            installations to skip declaring coderepo sections and map
            inboxes directly to code repositories known to cgit.

            Macro expansion (e.g. $HTTP_HOST) is not yet supported.

            A path to the "cgit.cgi" executable. The PublicInbox::WWW
            interface can spawn cgit as a fallback if the publicinbox.cgitrc
            directive is configured.

            Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi

            A path to the data directory used by cgit for storing static
            files. Typically guessed based the location of "cgit.cgi" (from
            "publicinbox.cgitbin", but may be overridden.

            Default: basename of "publicinbox.cgitbin",
            /var/www/htdocs/cgit/ or /usr/share/cgit/

            See public-inbox-edit(1)

    publicinbox.indexMaxSize =item publicinbox.indexBatchSize =item
            See public-inbox-index(1)

            Enable a HTML listing style when the root path of the URL '/' is
            accessed. Valid values are:

            *       all - Show all inboxes

            *       404 - Return a 404 page. This is useful to allow
                    customization with Plack::App::Cascade(3pm)

            *       match=domain - Only show inboxes with URLs which belong
                    to the domain of the HTTP request

                    support showing cgit listing

            Default: 404

            Controls the generation of a grokmirror-compatible gzipped JSON
            file at the top-level of the PSGI interface. You generally do
            not need to change this from the default.

            Valid values are:

            *       match=domain - Only include inboxes with URLs which
                    belong to the domain of the HTTP request. This is
                    compatible with virtual hosting where several domains
                    come from the same host.

            *       all - All inboxes are present in "manifest.js.gz",
                    regardless of domain. Only use this if you're serving
                    HTTP requests in a domain-agnostic manner.

            *       404 - "manifest.js.gz" will only contain an empty JSON
                    array. This does NOT affect "$INBOX_URL/manifest.js.gz",
                    which will always contain all git repos used by the
                    inbox at $INBOX_URL

            Default: "match=domain"

    Named limiters are useful for preventing large inboxes from monopolizing
    (or overloading) the server. Since serving git clones (via
    git-http-backend(1) can be memory-intensive for large inboxes, it makes
    sense to put large inboxes on a named limiter with a low max value;
    while smaller inboxes can use the default limiter.

    "RLIMIT_*" keys may be set to enforce resource limits for a particular

    Default named-limiters are prefixed with "-". Currently, the "-cgit"
    named limiter is reserved for instances spawning cgit via

            The maximum number of parallel processes for the given limiter.

            The maximum core size, CPU time, or data size processes run with
            the given limiter will use. This may be comma-separated to
            distinguish soft and hard limits. The word "INFINITY" is
            accepted as the RLIM_INFINITY constant (if supported by your

            See setrlimit(2) for more info on the behavior of RLIMIT_CORE,
            RLIMIT_CPU, and RLIMIT_DATA for you operating system.

            ; big inboxes which require lots of memory to clone:
            [publicinbox "big1"]
                    inboxdir = /path/to/big1
                    address =
                    httpbackendmax = big
            [publicinbox "big2"]
                    inboxdir = /path/to/big2
                    address =
                    httpbackendmax = big

            ; tiny inboxes which are easily cloned:
            [publicinbox "tiny1"]
                    inboxdir = /path/to/tiny1
                    address =
            [publicinbox "tiny2"]
                    inboxdir = /path/to/tiny2
                    address =

            [publicinboxlimiter "big"]
                    max = 4

    In the above example, the "big1" and "big2" are limited to four parallel
    git-http-backend(1) processes between them.

    However, "tiny1" and "tiny2" will share the default limiter which means
    there can be 32 git-http-backend(1) processes between them.

            Used to override the default "~/.public-inbox/config" value.

    Feedback welcome via plain-text mail to <>

    The mail archives are hosted at <> and

    Copyright 2016-2021 all contributors <>

    License: AGPL-3.0+ <>

    git(1), git-config(1), public-inbox-daemon(8), public-inbox-mda(1),
    public-inbox-watch(1), grokmirror