Documentation/public-inbox-convert.pod

   1 =head1 NAME
   2
   3 public-inbox-convert - convert v1 inboxes to v2
   4
   5 =head1 SYNOPSIS
   6
   7         public-inbox-convert [OPTIONS] OLD_DIR NEW_DIR
   8
   9 =head1 DESCRIPTION
  10
  11 public-inbox-convert copies the contents of an old "v1" inbox
  12 into a new "v2" inbox.  It makes no changes to the old inbox
  13 and users are expected to update the "inboxdir" path in
  14 L<public-inbox-config(5)> to point to the path of NEW_DIR
  15 once they are satisfied with the conversion.
  16
  17 =head1 OPTIONS
  18
  19 =over
  20
  21 =item --no-index
  22
  23 Disables Xapian and overview DB indexing on the new inbox.
  24 By default, public-inbox-convert creates a new index in the
  25 v2 inbox and indexes all existing messages, a lengthy
  26 operation for large inboxes.
  27
  28 =item -j JOBS, --jobs=JOBS
  29
  30 Control the number of indexing jobs and Xapian shards of the v2
  31 inbox.  By default, this is the detected CPU count but capped
  32 at 4 due to various bottlenecks.  The number of Xapian shards
  33 will be 1 less than the JOBS value, since there is a single
  34 process which distributes work to the Xapian shards.
  35
  36 =item -L LEVEL, --index-level=LEVEL
  37
  38 =item -c, --compact
  39
  40 =item -v, --verbose
  41
  42 =item --no-fsync
  43
  44 =item --sequential-shard
  45
  46 =item --batch-size=BYTES
  47
  48 =item --max-size=BYTES
  49
  50 These options affect indexing.  They have no effect if
  51 L</--no-index> is specified
  52
  53 See L<public-inbox-index(1)> for a description of these options.
  54
  55 =back
  56
  57 =head1 ENVIRONMENT
  58
  59 =over 8
  60
  61 =item PI_CONFIG
  62
  63 The default config file, normally "~/.public-inbox/config".
  64 See L<public-inbox-config(5)>
  65
  66 =back
  67
  68 =head1 UPGRADING
  69
  70 Editing "~/.public-inbox/config" (or whatever C<PI_CONFIG> is
  71 set to) will be required to start using the new directory.
  72
  73 =head1 BUGS
  74
  75 Writes from L<public-inbox-mda(1)> or L<git-fetch(1)> to the v1
  76 inbox which occur after the start of the conversion will not
  77 be picked up in the v2 inbox.
  78
  79 Users of L<public-inbox-watch(1)> do not have to worry about
  80 this.  They only need to update the config file to point to the
  81 v2 inbox, send C<SIGHUP> public-inbox-watch process to reload
  82 the config file, and then C<SIGUSR1> to rescan existing
  83 Maildirs.
  84
  85 =head1 CONTACT
  86
  87 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
  88
  89 The mail archives are hosted at L<https://public-inbox.org/meta/>
  90 and L<http://hjrcffqmbrq6wope.onion/meta/>
  91
  92 =head1 COPYRIGHT
  93
  94 Copyright 2013-2020 all contributors L<mailto:meta@public-inbox.org>
  95
  96 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
  97
  98 =head1 SEE ALSO
  99
 100 L<public-inbox-init(1)>, L<public-inbox-index(1)>, L<public-inbox-config(5)>,
 101 L<public-inbox-v1-format(5)>, L<public-inbox-v2-format(5)>