=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)>
