ds: share long_step between NNTP and IMAP

[public-inbox.git] / Documentation / public-inbox-xcpdb.pod

diff --git a/Documentation/public-inbox-xcpdb.pod b/Documentation/public-inbox-xcpdb.pod
index 149c8f78c738fc60a18e1f9def1e295d745f65eb..e7c07ed38d4085c9c5b6bbdc7954f50aa8b2a68a 100644 (file)
--- a/Documentation/public-inbox-xcpdb.pod
+++ b/Documentation/public-inbox-xcpdb.pod
@@ -4,20 +4,34 @@ public-inbox-xcpdb - upgrade Xapian DB formats
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 

-       public-inbox-xcpdb [OPTIONS] INBOX_DIR
+public-inbox-xcpdb [OPTIONS] INBOX_DIR
+
+public-inbox-xcpdb [OPTIONS] --all

 
 =head1 DESCRIPTION
 
 public-inbox-xcpdb is similar to L<copydatabase(1)> for
 upgrading to the latest database format supported by Xapian
 (e.g. "glass" or "honey"), but is designed to tolerate and
 
 =head1 DESCRIPTION
 
 public-inbox-xcpdb is similar to L<copydatabase(1)> for
 upgrading to the latest database format supported by Xapian
 (e.g. "glass" or "honey"), but is designed to tolerate and

-recover from Xapian database modifications from
-L<public-inbox-watch(1)> or L<public-inbox-mda(1)>.
+accept parallel Xapian database modifications from
+L<public-inbox-watch(1)>, L<public-inbox-mda(1)>,
+L<public-inbox-learn(1)>, and L<public-inbox-index(1)>.
+
+This command is rarely used, as Xapian DB formats rarely
+change.

 
 =head1 OPTIONS
 
 =over
 
 
 =head1 OPTIONS
 
 =over
 

+=item --all
+
+Copy all inboxes configured in ~/.public-inbox/config.
+This is an alternative to specifying individual inboxes directories
+on the command-line.
+
+=item -c
+

 =item --compact
 
 In addition to performing the copy operation, run L<xapian-compact(1)>
 =item --compact
 
 In addition to performing the copy operation, run L<xapian-compact(1)>


@@ -30,7 +44,9 @@ preferable for gigantic inboxes where the coarse-grained lock
 currently required for L<public-inbox-compact(1)> can cause
 the compaction to take hours at-a-time.
 
 currently required for L<public-inbox-compact(1)> can cause
 the compaction to take hours at-a-time.
 

-=item --reshard=N / -R N
+=item -R N
+
+=item --reshard=N

 
 Reshard the Xapian database on a L<v2|public-inbox-v2-format(5)>
 inbox to C<N> shards .  Since L<xapian-compact(1)> is not suitable
 
 Reshard the Xapian database on a L<v2|public-inbox-v2-format(5)>
 inbox to C<N> shards .  Since L<xapian-compact(1)> is not suitable


@@ -40,11 +56,39 @@ existing Xapian database(s) to any positive value of C<N>.
 This is useful in case the Xapian DB was created with too few or
 too many shards given the capabilities of the current hardware.
 
 This is useful in case the Xapian DB was created with too few or
 too many shards given the capabilities of the current hardware.
 

-=item --blocksize / --no-full / --fuller
+=item --blocksize
+
+=item --no-full
+
+=item --fuller

 
 These options are passed directly to L<xapian-compact(1)> when
 used with C<--compact>.
 
 
 These options are passed directly to L<xapian-compact(1)> when
 used with C<--compact>.
 

+=item --no-fsync
+
+Disable L<fsync(2)> and L<fdatasync(2)>.
+See L<public-inbox-index(1)/--no-fsync> for caveats.
+
+Available in public-inbox 1.6.0+.
+
+=item --sequential-shard
+
+Copy each shard sequentially, ignoring C<--jobs>.  This also
+affects indexing done at the end of a run.
+
+=item --batch-size=BYTES
+
+=item --max-size=BYTES
+
+See L<public-inbox-index(1)> for a description of these options.
+
+These indexing options indexing at the end of a run.
+C<public-inbox-xcpdb> may run in parallel with with
+L<public-inbox-index(1)>, and C<public-inbox-xcpdb> needs to
+reindex changes made to the old Xapian DBs by
+L<public-inbox-index(1)> while it was running.
+

 =back
 
 =head1 ENVIRONMENT
 =back
 
 =head1 ENVIRONMENT


@@ -74,16 +118,26 @@ used by public-inbox, NOT users upgrading public-inbox itself.
 In particular, it DOES NOT upgrade the schema used by the
 PSGI search interface (see L<public-inbox-index(1)>).
 
 In particular, it DOES NOT upgrade the schema used by the
 PSGI search interface (see L<public-inbox-index(1)>).
 

+=head1 LIMITATIONS
+
+Do not use L<public-inbox-purge(1)> or L<public-inbox-edit(1)>
+while this is running; old (purged or edited data) may show up.
+
+Normal invocations L<public-inbox-index(1)> can safely run
+while this is running, too.  However, reindexing via the
+L<public-inbox-index(1)/--reindex> switch will be a waste of
+computing resources.
+

 =head1 CONTACT
 
 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 
 =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://hjrcffqmbrq6wope.onion/meta/>
+The mail archives are hosted at L<https://public-inbox.org/meta/> and
+L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>

 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright 2019-2020 all contributors L<mailto:meta@public-inbox.org>
+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>
 
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>