public-inbox.git  about / heads / tags
an "archives first" approach to mailing lists
blob 85c6c9e89172b25b77e35aa248f4f215cab0ca65 4541 bytes (raw)
$ git show HEAD:Documentation/public-inbox-init.pod	# shows this blob on the CLI

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
=head1 NAME

public-inbox-init - create or reinitialize a public-inbox

=head1 SYNOPSIS

B<public-inbox-init> [OPTIONS] NAME INBOX_DIR HTTP_URL ADDRESS [ADDRESS..]

=head1 DESCRIPTION

Creates an empty public-inbox or reinitializes an existing one.
It updates C<~/.public-inbox/config> by creating a
C<[publicinbox "NAME"]> section where
C<publicinbox.NAME.inboxdir> is C<INBOX_DIR>,
C<publicinbox.NAME.url> is C<HTTP_URL>, and
C<publicinbox.NAME.address> is C<ADDRESS>.  Multiple addresses
may be specified for inboxes with multiple addresses.

=head1 OPTIONS

=over

=item -V FORMAT_VERSION

=item --version FORMAT_VERSION

Specify C<2> here to use the scalable L<public-inbox-v2-format(5)>
if you have L<DBD::SQLite> installed.

The default is C<1> for the old L<public-inbox-v1-format(5)>,
but C<2> is strongly recommended for scalability if you have
L<DBD::SQLite>.

Default: C<1>

=item -L <basic|medium|full>

=item --indexlevel <basic|medium|full>

Controls the indexing level for L<public-inbox-index(1)>

See L<public-inbox-config(5)> for more information.

Default: C<full>

=item --ng NEWSGROUP

=item --newsgroup NEWSGROUP

The NNTP group name for use with L<public-inbox-nntpd(8)>.  This
may be any newsgroup name with hierarchies delimited by C<.>.
For example, the newsgroup for L<mailto:meta@public-inbox.org>
is: C<inbox.comp.mail.public-inbox.meta>

This may be set after-the-fact via C<publicinbox.$NAME.newsgroup>
in the configuration file.  See L<public-inbox-config(5)> for more
info.

Available in public-inbox 1.6.0+.

Default: none.

=item -c KEY=VALUE

Allow setting arbitrary configs as C<publicinbox.$NAME.$KEY>.
This is idempotent for the same C<VALUE>, but allows setting
multiple values for keys such as C<publicinbox.$NAME.url> and
C<publicinbox.$NAME.watch>.

=item --skip-artnum

This option allows archivists to publish incomplete archives
with only new mail while allowing NNTP article numbers
to be reserved for yet-to-be-archived old mail.

This is mainly intended for users of C<--skip-epoch> (documented below)
but may be of use to L<public-inbox-v1-format(5)> users.

There is no automatic way to use reserved NNTP article numbers
when old mail is found, yet.

Available in public-inbox 1.6.0+.

Default: unset, no NNTP article numbers are skipped

=item -S

=item --skip-epoch

For C<-V2> (L<public-inbox-v2-format(5)>) inboxes only, this option
allows archivists to publish incomplete archives with newer
mail while allowing "0.git" (or "1.git" and so on) epochs to be
added-after-the-fact (without affecting "git clone" followers).

Available since public-inbox 1.2.0.

Default: unset, no epochs are skipped

=item -j JOBS

=item --jobs=JOBS

Control the number of Xapian index shards in a
C<-V2> (L<public-inbox-v2-format(5)>) inbox.

It can be useful to use a single shard (C<-j1>) for inboxes on
high-latency storage (e.g. rotational HDD) unless the system has
enough RAM to cache 5-10x the size of the git repository.

Another approach for HDDs is to use the
L<public-inbox-index(1)/publicInbox.indexSequentialShard> option
and many shards, so each shard may fit into the kernel page
cache.  Unfortunately, excessive shards slows down read-only
query performance.

For fast storage, it is generally not useful to specify higher
values than the default due to the top-level producer process
being a bottleneck.

Default: the number of online CPUs, up to 4 (3 shard workers, 1 producer)

=item --skip-docdata

Do not store document data in Xapian, reducing Xapian storage
overhead by around 1.5%.

Warning: this option prevents rollbacks to public-inbox 1.5.0
and earlier.

Available in public-inbox 1.6.0+.

=back

=head1 ENVIRONMENT

=over 8

=item PI_CONFIG

Used to override the default C<~/.public-inbox/config> value.

=back

=head1 LIMITATIONS

Some of the options documented in L<public-inbox-config(5)>
require editing the config file.  Old versions lack the
C<--ng>/C<--newsgroup> parameter

See L<public-inbox-config(5)> for all the options which may be applied
to a given inbox.

=head1 CONTACT

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

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

=head1 COPYRIGHT

Copyright 2019-2021 all contributors L<mailto:meta@public-inbox.org>

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

=head1 SEE ALSO

L<git-init(1)>, L<git-config(1)>, L<public-inbox-v1-format(5)>,
L<public-inbox-v2-format(5)>

git clone https://public-inbox.org/public-inbox.git
git clone http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/public-inbox.git