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 and personal mail.
   8 This document 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 =head1 SYNCHRONIZATION
  53
  54 lei currently has primitive mail synchronization abilities;
  55 see L<lei-mail-sync-overview(7)> for more details.
  56
  57 =head2 EXAMPLES
  58
  59 =over
  60
  61 =item $ lei add-external https://public-inbox.org/meta/
  62
  63 Add a remote external for public-inbox's inbox.
  64
  65 =item $ lei add-external --mirror https://public-inbox.org/meta/ path
  66
  67 Clone L<https://public-inbox.org/meta/> to C<path>, index it with
  68 L<public-inbox-index(1)>, and add it as a local external.
  69
  70 =back
  71
  72 =head1 SEARCHING
  73
  74 The L<lei-q(1)> command searches the local store and externals.  The
  75 search prefixes match those available via L<public-inbox-httpd(1)>.
  76
  77 =head2 EXAMPLES
  78
  79 =over
  80
  81 =item $ lei q s:lei s:skeleton
  82
  83 Search for messages whose subject includes "lei" and "skeleton".
  84
  85 =item $ lei q -t s:lei s:skeleton
  86
  87 Do the same, but also report unmatched messages that are in the same
  88 thread as a matched message.
  89
  90 =item $ lei q -t -o /tmp/mdir --mua=mutt s:lei s:skeleton
  91
  92 Write results to a Maildir at "mdir".  Mutt will be invoked
  93 to open mfolder (C<mutt -f %f>) while results are being fetched
  94 and written.
  95
  96 =item $ lei q kw:flagged L:next
  97
  98 Search for all flagged messages that also have a "next" label.
  99
 100 =item $ lei p2q HEAD | lei q -tt -o /tmp/mdir
 101
 102 Search for messages that have post-image git blob IDs that match those
 103 of the current repository's HEAD commit, writing them to the Maildir
 104 directory "mdir" and flagging the messages that were an exact match.
 105
 106 =item $ git show -s HEAD | lei lcat
 107
 108 Display a local message for the public-inbox link contained in a
 109 commit message.
 110
 111 =item $ lei q -f text m:MESSAGE-ID | lei rediff -U5
 112
 113 Feed a message containing a diff to L<lei-rediff(1)> to regenerate its
 114 diff with five context lines.  Unless C<--git-dir> is specified, this
 115 requires the current working directory to be within the associated
 116 code repository.
 117
 118 =back
 119
 120 =head1 PERFORMANCE NOTES
 121
 122 L<Inline::C> is required, lei runs as a background daemon to reduce
 123 startup costs and can provide real-time L<kqueue(2)>/L<inotify(7)>
 124 Maildir monitoring.  L<IO::KQueue> (p5-IO-KQueue on FreeBSD) and
 125 L<Linux::Inotify2> (liblinux-inotify2-perl and perl-Linux-Inotify2 in
 126 .deb and .rpm-based distros, respectively) are recommended.
 127
 128 L<Socket::MsgHdr> is optional (libsocket-msghdr-perl in Debian),
 129 and further improves startup performance.  Its effect is most felt
 130 when using shell completion.
 131
 132 =head1 BASH COMPLETION
 133
 134 Preliminary Bash completion for lei is provided in
 135 C<contrib/completion/>.  Contributions adding support for other
 136 shells, as well as improvements to the existing Bash completion, are
 137 welcome.
 138
 139 =head1 UPGRADING
 140
 141 Since lei runs as a daemon, L<lei-daemon-kill(1)> is required to kill
 142 the daemon so it can load new code.  It will be restarted with the
 143 next invocation of any lei command.
 144
 145 =head1 CAVEATS
 146
 147 IMAP and NNTP client performance is poor on high-latency connections.
 148 It will hopefully be fixed in 2022.
 149
 150 =head1 CONTACT
 151
 152 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 153
 154 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 155 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 156
 157 =head1 COPYRIGHT
 158
 159 Copyright all contributors L<mailto:meta@public-inbox.org>
 160
 161 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 162
 163 =head1 SEE ALSO
 164
 165 L<lei-mail-sync-overview(7)>