diff options
Diffstat (limited to 'Documentation/lei-overview.pod')
-rw-r--r-- | Documentation/lei-overview.pod | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod new file mode 100644 index 00000000..e9a97d64 --- /dev/null +++ b/Documentation/lei-overview.pod @@ -0,0 +1,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)> |