]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-convert.pod
doc: lei-{p2q,rediff}: note implicit --stdin
[public-inbox.git] / 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
29
30 =item --jobs=JOBS
31
32 Control the number of indexing jobs and Xapian shards of the v2
33 inbox.  By default, this is the detected CPU count but capped
34 at 4 due to various bottlenecks.  The number of Xapian shards
35 will be 1 less than the JOBS value, since there is a single
36 process which distributes work to the Xapian shards.
37
38 =item -L LEVEL, --index-level=LEVEL
39
40 =item -c, --compact
41
42 =item -v, --verbose
43
44 =item --no-fsync
45
46 =item --sequential-shard
47
48 =item --batch-size=BYTES
49
50 =item --max-size=BYTES
51
52 These options affect indexing.  They have no effect if
53 L</--no-index> is specified
54
55 See L<public-inbox-index(1)> for a description of these options.
56
57 =back
58
59 =head1 ENVIRONMENT
60
61 =over 8
62
63 =item PI_CONFIG
64
65 The default config file, normally "~/.public-inbox/config".
66 See L<public-inbox-config(5)>
67
68 =back
69
70 =head1 UPGRADING
71
72 Editing "~/.public-inbox/config" (or whatever C<PI_CONFIG> is
73 set to) will be required to start using the new directory.
74
75 =head1 BUGS
76
77 Writes from L<public-inbox-mda(1)> or L<git-fetch(1)> to the v1
78 inbox which occur after the start of the conversion will not
79 be picked up in the v2 inbox.
80
81 Users of L<public-inbox-watch(1)> do not have to worry about
82 this.  They only need to update the config file to point to the
83 v2 inbox, send C<SIGHUP> public-inbox-watch process to reload
84 the config file, and then C<SIGUSR1> to rescan existing
85 Maildirs.
86
87 =head1 CONTACT
88
89 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
90
91 The mail archives are hosted at L<https://public-inbox.org/meta/> and
92 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
93
94 =head1 COPYRIGHT
95
96 Copyright 2013-2021 all contributors L<mailto:meta@public-inbox.org>
97
98 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
99
100 =head1 SEE ALSO
101
102 L<public-inbox-init(1)>, L<public-inbox-index(1)>, L<public-inbox-config(5)>,
103 L<public-inbox-v1-format(5)>, L<public-inbox-v2-format(5)>