]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/lei-overview.pod
init: allow arbitrary key-values via -c KEY=VALUE
[public-inbox.git] / Documentation / lei-overview.pod
1 =head1 NAME
2
3 lei - an overview of lei
4
5 =head1 DESCRIPTION
6
7 L<lei(1)> is a local email interface for public-inbox.  This document
8 provides some basic examples.
9
10 =head1 LEI STORE
11
12 lei has writable local storage based on L<public-inbox-v2-format(5)>.
13 Commands will automatically initialize the store behind the scenes if
14 needed, but you can call L<lei-init(1)> directly if you want to use a
15 store location other than the default C<$XDG_DATA_HOME/lei/store>.
16
17 The L<lei-import(1)> command provides the primary interface for
18 importing messages into the local storage.  In addition, other
19 commands, such as L<lei-q(1)> and L<lei-blob(1)>, use the local store
20 to memoize messages from remotes.
21
22 =head2 EXAMPLES
23
24 =over
25
26 =item $ lei import mboxrd:t.mbox.gz
27
28 Import the messages from a gzipped mboxrd into the local storage.
29
30 =item $ lei blob 59ec517f9
31
32 Show message with the git blob OID of 59ec517f9.  If a message with
33 that OID isn't found, check if the current git repository has the
34 blob, trying to reconstruct it from a message if needed.
35
36 =item $ lei blob 59ec517f9 | lei tag - -F eml +kw:flagged +L:next
37
38 Set the "flagged" keyword and "next" label on the message with the
39 blob OID of 59ec517f9.
40
41 =back
42
43 =head1 EXTERNALS
44
45 In addition to the above store, lei can make read-only queries to
46 "externals": inboxes and external indices.  An external can be
47 registered by passing a URL or local path to L<lei-add-external(1)>.
48 For existing local paths, the external needs to be indexed with
49 L<public-inbox-index(1)> (in the case of a regular inbox) or
50 L<public-inbox-extindex(1)> (in the case of an external index).
51
52 =head2 EXAMPLES
53
54 =over
55
56 =item $ lei add-external https://public-inbox.org/meta/
57
58 Add a remote external for public-inbox's inbox.
59
60 =item $ lei add-external --mirror https://public-inbox.org/meta/ path
61
62 Clone L<https://public-inbox.org/meta/> to C<path>, index it with
63 L<public-inbox-index(1)>, and add it as a local external.
64
65 =back
66
67 =head1 SEARCHING
68
69 The L<lei-q(1)> command searches the local store and externals.  The
70 search prefixes match those available via L<public-inbox-httpd(1)>.
71
72 =head2 EXAMPLES
73
74 =over
75
76 =item $ lei q s:lei s:skeleton
77
78 Search for messages whose subject includes "lei" and "skeleton".
79
80 =item $ lei q -t s:lei s:skeleton
81
82 Do the same, but also report unmatched messages that are in the same
83 thread as a matched message.
84
85 =item $ lei q -t -o /tmp/mdir --mua=mutt s:lei s:skeleton
86
87 Write results to a Maildir at "mdir".  Mutt will be invoked
88 to open mfolder (C<mutt -f %f>) while results are being fetched
89 and written.
90
91 =item $ lei q kw:flagged L:next
92
93 Search for all flagged messages that also have a "next" label.
94
95 =item $ lei p2q HEAD | lei q --stdin -tt -o /tmp/mdir
96
97 Search for messages that have post-image git blob IDs that match those
98 of the current repository's HEAD commit, writing them to the Maildir
99 directory "mdir" and flagging the messages that were an exact match.
100
101 =item $ git show -s HEAD | lei lcat -
102
103 Display a local message for the public-inbox link contained in a
104 commit message.
105
106 =item $ lei q -f text m:MID | lei rediff -U5 -
107
108 Feed a message containing a diff to L<lei-rediff(1)> to regenerate its
109 diff with five context lines.  Unless C<--git-dir> is specified, this
110 requires the current working directory to be within the associated
111 code repository.
112
113 =back
114
115 =head1 PERFORMANCE NOTES
116
117 L<Inline::C> is recommended for performance.  To enable it, create
118 C<~/.cache/public-inbox/inline-c/>.
119
120 If Socket::MsgHdr is installed (libsocket-msghdr-perl in Debian), the
121 first invocation of lei starts a daemon, reducing the startup cost of
122 for future invocations (which is particularly important for Bash
123 completion).
124
125 =head1 BASH COMPLETION
126
127 Preliminary Bash completion for lei is provided in
128 C<contrib/completion/>.  Contributions adding support for other
129 shells, as well as improvements to the existing Bash completion, are
130 welcome.
131
132 =head1 CONTACT
133
134 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
135
136 The mail archives are hosted at L<https://public-inbox.org/meta/> and
137 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
138
139 =head1 COPYRIGHT
140
141 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
142
143 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>