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

SYNOPSIS
    ~/.public-inbox/config

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.

CONFIGURATION FILE
  EXAMPLE
            [publicinbox "test"]
                    mainrepo = /home/user/path/to/test.git
                    ; multiple addresses are supported
                    address = test@example.com
                    ; address = alternate@example.com
                    url = http://example.com/test
                    newsgroup = inbox.test

  VARIABLES
    publicinbox.<name>.address
            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
            purposes.

            Default: none, required

    publicinbox.<name>.mainrepo
            The absolute path to the directory which hosts the public-inbox.
            This must be specified once.

            Default: none, required

    publicinbox.<name>.url
            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

    publicinbox.<name>.newsgroup
            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 <mailto:meta@public-inbox.org> is:
            "inbox.comp.mail.public-inbox.meta"

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

            Default: none, optional

    publicinbox.<name>.watch
            A location for public-inbox-watch(1) to watch. Currently, only
            "maildir:" paths are supported:

                    [publicinbox "test"]
                            watch = maildir:/path/to/maildirs/.INBOX.test/

            Default: none; only for public-inbox-watch(1) users

    publicinbox.<name>.watchheader
                    [publicinbox "test"]
                            watchheader = List-Id:<test.example.com>

            Default: none; only for public-inbox-watch(1) users

    publicinbox.<name>.nntpmirror
            This may be the full NNTP URL of an independently-run mirror.
            For example, the https://public-inbox.org/meta/ inbox is
            mirrored by Gmane at
            "nntp://news.gmane.org/gmane.mail.public-inbox.general"

            Default: none

    publicinbox.<name>.httpbackendmax
            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)

    publicinbox.<name>.coderepo
            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

    publicinbox.<name>.replyto
            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 seperate 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

    publicinbox.css
            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.

    publicinboxmda.spamcheck
            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
            future.

            Default: spamc

    publicinboxwatch.spamcheck
            This may be set to "spamc" to enable 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
            future.

            Default: none

    publicinboxwatch.watchspam
            This may be set to "spamc" to enable 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
            future. This requires public-inbox-watch(1), but affects all
            configured public-inboxes in PI_CONFIG.

            Default: none

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

            Multiple values are allowed for servers with multiple addresses
            or mirrors.

            Default: none

    publicinbox.<name>.feedmax
            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

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

    coderepo.<nick>.cgitUrl
            The URL of the cgit instance associated with the coderepo.

            Default: none

    publicinbox.cgitrc
            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.

    publicinbox.cgitbin
            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

  NAMED LIMITER (PSGI)
    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
    limiter.

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

    publicinboxlimiter.<name>.max
            The maximum number of parallel processes for the given limiter.

    publicinboxlimiter.<name>.rlimitCore
    publicinboxlimiter.<name>.rlimitCPU
    publicinboxlimiter.<name>.rlimitData
            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
            OS).

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

   EXAMPLE WITH NAMED LIMITERS
            ; big inboxes which require lots of memory to clone:
            [publicinbox "big1"]
                    mainrepo = /path/to/big1
                    address = big1@example.com
                    httpbackendmax = big
            [publicinbox "big2"]
                    mainrepo = /path/to/big2
                    address = big2@example.com
                    httpbackendmax = big

            ; tiny inboxes which are easily cloned:
            [publicinbox "tiny1"]
                    mainrepo = /path/to/tiny1
                    address = tiny1@example.com
            [publicinbox "tiny2"]
                    mainrepo = /path/to/tiny2
                    address = tiny2@example.com

            [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.

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

CONTACT
    Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>

    The mail archives are hosted at <https://public-inbox.org/meta/> and
    <http://hjrcffqmbrq6wope.onion/meta/>

COPYRIGHT
    Copyright 2016-2018 all contributors <mailto:meta@public-inbox.org>

    License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>

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