public-inbox.git  about / heads / tags
an "archives first" approach to mailing lists
blob e9a97d64fb56d56be69c0265d0d8195151b3d17b 4980 bytes (raw)
$ git show HEAD:Documentation/lei-overview.pod	# shows this blob on the CLI

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
=head1 NAME

lei - an overview of lei

=head1 DESCRIPTION

L<lei(1)> is a local email interface for public-inbox and personal mail.
This document provides some basic examples.

=head1 LEI STORE

lei has writable local storage based on L<public-inbox-v2-format(5)>.
Commands will automatically initialize the store behind the scenes if
needed, but you can call L<lei-init(1)> directly if you want to use a
store location other than the default C<$XDG_DATA_HOME/lei/store>.

The L<lei-import(1)> command provides the primary interface for
importing messages into the local storage.  In addition, other
commands, such as L<lei-q(1)> and L<lei-blob(1)>, use the local store
to memoize messages from remotes.

=head2 EXAMPLES

=over

=item $ lei import mboxrd:t.mbox.gz

Import the messages from a gzipped mboxrd into the local storage.

=item $ lei blob 59ec517f9

Show message with the git blob OID of 59ec517f9.  If a message with
that OID isn't found, check if the current git repository has the
blob, trying to reconstruct it from a message if needed.

=item $ lei blob 59ec517f9 | lei tag -F eml +kw:flagged +L:next

Set the "flagged" keyword and "next" label on the message with the
blob OID of 59ec517f9.

=back

=head1 EXTERNALS

In addition to the above store, lei can make read-only queries to
"externals": inboxes and external indices.  An external can be
registered by passing a URL or local path to L<lei-add-external(1)>.
For existing local paths, the external needs to be indexed with
L<public-inbox-index(1)> (in the case of a regular inbox) or
L<public-inbox-extindex(1)> (in the case of an external index).

=head1 SYNCHRONIZATION

lei currently has primitive mail synchronization abilities;
see L<lei-mail-sync-overview(7)> for more details.

=head2 EXAMPLES

=over

=item $ lei add-external https://public-inbox.org/meta/

Add a remote external for public-inbox's inbox.

=item $ lei add-external --mirror https://public-inbox.org/meta/ path

Clone L<https://public-inbox.org/meta/> to C<path>, index it with
L<public-inbox-index(1)>, and add it as a local external.

=back

=head1 SEARCHING

The L<lei-q(1)> command searches the local store and externals.  The
search prefixes match those available via L<public-inbox-httpd(1)>.

=head2 EXAMPLES

=over

=item $ lei q s:lei s:skeleton

Search for messages whose subject includes "lei" and "skeleton".

=item $ lei q -t s:lei s:skeleton

Do the same, but also report unmatched messages that are in the same
thread as a matched message.

=item $ lei q -t -o /tmp/mdir --mua=mutt s:lei s:skeleton

Write results to a Maildir at "mdir".  Mutt will be invoked
to open mfolder (C<mutt -f %f>) while results are being fetched
and written.

=item $ lei q kw:flagged L:next

Search for all flagged messages that also have a "next" label.

=item $ lei p2q HEAD | lei q -tt -o /tmp/mdir

Search for messages that have post-image git blob IDs that match those
of the current repository's HEAD commit, writing them to the Maildir
directory "mdir" and flagging the messages that were an exact match.

=item $ git show -s HEAD | lei lcat

Display a local message for the public-inbox link contained in a
commit message.

=item $ lei q -f text m:MESSAGE-ID | lei rediff -U5

Feed a message containing a diff to L<lei-rediff(1)> to regenerate its
diff with five context lines.  Unless C<--git-dir> is specified, this
requires the current working directory to be within the associated
code repository.

=back

=head1 PERFORMANCE NOTES

L<Inline::C> is required on BSDs and can speed things up on Linux.

lei runs as a background daemon to reduce startup costs and can
provide real-time L<kqueue(2)>/L<inotify(7)> Maildir monitoring.
L<IO::KQueue> (p5-IO-KQueue on FreeBSD) and L<Linux::Inotify2>
(liblinux-inotify2-perl and perl-Linux-Inotify2 in .deb and .rpm-based
distros, respectively) are recommended.

L<Socket::MsgHdr> is optional (libsocket-msghdr-perl in Debian),
and further improves startup performance.  Its effect is most felt
when using shell completion.

=head1 BASH COMPLETION

Preliminary Bash completion for lei is provided in
C<contrib/completion/>.  Contributions adding support for other
shells, as well as improvements to the existing Bash completion, are
welcome.

=head1 UPGRADING

Since lei runs as a daemon, L<lei-daemon-kill(1)> is required to kill
the daemon so it can load new code.  It will be restarted with the
next invocation of any lei command.

=head1 CAVEATS

IMAP and NNTP client performance is poor on high-latency connections.
It will hopefully be fixed in 2022.

=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 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<lei-mail-sync-overview(7)>

git clone https://public-inbox.org/public-inbox.git
git clone http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/public-inbox.git