Documentation/public-inbox-config.pod

   1 =head1 NAME
   2
   3 public-inbox-config - public-inbox config file description
   4
   5 =head1 SYNOPSIS
   6
   7 ~/.public-inbox/config
   8
   9 =head1 DESCRIPTION
  10
  11 The public-inbox config file is parseable by L<git-config(1)>.
  12 This is a global configuration file for mapping/discovering
  13 all public-inboxes used by a particular user.
  14
  15 =head1 CONFIGURATION FILE
  16
  17 =head2 EXAMPLE
  18
  19         [publicinbox "test"]
  20                 mainrepo = /home/user/path/to/test.git
  21                 ; multiple addresses are supported
  22                 address = test@example.com
  23                 ; address = alternate@example.com
  24                 url = http://example.com/test
  25                 newsgroup = inbox.test
  26
  27 =head2 VARIABLES
  28
  29 =over 8
  30
  31 =item publicinbox.<name>.address
  32
  33 The email address of the public-inbox.  May be specified
  34 more than once for merging multiple mailing lists (or migrating
  35 to new addresses).  This must be specified at least once,
  36 the first value will be considered the primary address for
  37 informational purposes.
  38
  39 Default: none, required
  40
  41 =item publicinbox.<name>.mainrepo
  42
  43 The absolute path to the directory which hosts the
  44 public-inbox.  This must be specified once.
  45
  46 Default: none, required
  47
  48 =item publicinbox.<name>.url
  49
  50 The primary URL for hosting the HTTP/HTTPS archives.
  51 Additional HTTP/HTTPS URLs may be specified via
  52 C<$GIT_DIR/cloneurl> as documented in L<gitweb(1)>
  53
  54 Default: none, optional
  55
  56 =item publicinbox.<name>.newsgroup
  57
  58 The NNTP group name for use with L<public-inbox-nntpd(8)>.  This
  59 may be any newsgroup name with hierarchies delimited by '.'.
  60 For example, the newsgroup for L<mailto:meta@public-inbox.org>
  61 is: C<inbox.comp.mail.public-inbox.meta>
  62
  63 Omitting this for the given inbox will prevent the group from
  64 being read by L<public-inbox-nntpd(1)>
  65
  66 Default: none, optional
  67
  68 =item publicinbox.<name>.watch
  69
  70 A location for L<public-inbox-watch(1)> to watch.  Currently,
  71 only C<maildir:> paths are supported:
  72
  73         [publicinbox "test"]
  74                 watch = maildir:/path/to/maildirs/.INBOX.test/
  75
  76 Default: none; only for L<public-inbox-watch(1)> users
  77
  78 =item publicinbox.<name>.watchheader
  79
  80         [publicinbox "test"]
  81                 watchheader = List-Id:<test.example.com>
  82
  83 Default: none; only for L<public-inbox-watch(1)> users
  84
  85 =item publicinbox.<name>.nntpmirror
  86
  87 This may be the full NNTP URL of an independently-run mirror.
  88 For example, the https://public-inbox.org/meta/ inbox is
  89 mirrored by Gmane at
  90 C<nntp://news.gmane.org/gmane.mail.public-inbox.general>
  91
  92 Default: none
  93
  94 =item publicinbox.<name>.coderepo
  95
  96 The nickname of a "coderepo" section associated with the inbox.
  97 May be specified more than once for M:N mapping of code repos to
  98 inboxes.  If enabled, diff hunk headers in patch emails will
  99 link to the line numbers of blobs.
 100
 101 Default: none
 102
 103 =item publicinbox.css
 104
 105 The local path name of a CSS file for the PSGI web interface.
 106 May contain the attributes "media", "title" and "href" which match
 107 the associated attributes of the HTML <style> tag.
 108 "href" may be specified to point to the URL of an remote CSS file
 109 and the path may be "/dev/null" or any empty file.
 110 Multiple files may be specified and will be included in the
 111 order specified.
 112
 113 =item publicinboxmda.spamcheck
 114
 115 This may be set to C<none> to disable the use of SpamAssassin
 116 L<spamc(1)> for filtering spam before it is imported into git
 117 history.  Other spam filtering backends may be supported in
 118 the future.
 119
 120 Default: spamc
 121
 122 =item publicinboxwatch.spamcheck
 123
 124 This may be set to C<spamc> to enable the use of SpamAssassin
 125 L<spamc(1)> for filtering spam before it is imported into git
 126 history.  Other spam filtering backends may be supported in
 127 the future.
 128
 129 Default: none
 130
 131 =item publicinboxwatch.watchspam
 132
 133 This may be set to C<spamc> to enable the use of SpamAssassin
 134 L<spamc(1)> for filtering spam before it is imported into git
 135 history.  Other spam filtering backends may be supported in
 136 the future.  This requires L<public-inbox-watch(1)>, but affects
 137 all configured public-inboxes in PI_CONFIG.
 138
 139 Default: none
 140
 141 =item publicinbox.nntpserver
 142
 143 Set this to point to the address of the L<public-inbox-nntpd(1)>
 144 instance.  This is used to advertise the existence of the NNTP
 145 presnce in the L<PublicInbox::WWW> HTML interface.
 146
 147 Multiple values are allowed for servers with multiple
 148 addresses or mirrors.
 149
 150 Default: none
 151
 152 =item publicinbox.<name>.feedmax
 153
 154 The size of an Atom feed for the inbox.  If specified more than
 155 once, only the last value is used.  Invalid values (<= 0) will
 156 be treated as the default value.
 157
 158 Default: 25
 159
 160 =item coderepo.<name>.dir
 161
 162 The path to a git repository for "publicinbox.<name>.coderepo"
 163
 164 =item coderepo.<name>.cgitUrl
 165
 166 The URL of the cgit instance associated with the coderepo.
 167
 168 Default: none
 169
 170 =back
 171
 172 =head1 ENVIRONMENT
 173
 174 =over 8
 175
 176 =item PI_CONFIG
 177
 178 Used to override the default "~/.public-inbox/config" value.
 179
 180 =back
 181
 182 =head1 CONTACT
 183
 184 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 185
 186 The mail archives are hosted at L<https://public-inbox.org/meta/>
 187 and L<http://hjrcffqmbrq6wope.onion/meta/>
 188
 189 =head1 COPYRIGHT
 190
 191 Copyright 2016-2018 all contributors L<mailto:meta@public-inbox.org>
 192
 193 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 194
 195 =head1 SEE ALSO
 196
 197 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
 198 L<public-inbox-mda(1)>, L<public-inbox-watch(1)>