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 L<lei-init(1)> initializes writable local storage based on
  13 L<public-inbox-v2-format(5)>.
  14
  15 =head2 EXAMPLES
  16
  17 =over
  18
  19 =item $ lei import mboxrd:t.mbox
  20
  21 Import the messages from an mbox into the local storage.
  22
  23 =item $ lei blob 59ec517f9
  24
  25 Show message with the git blob OID of 59ec517f9.  If a message with
  26 that OID isn't found, check if the current git repository has the
  27 blob, trying to reconstruct it from a message if needed.
  28
  29 =item $ lei blob 59ec517f9 | lei mark - -F eml +kw:flagged +L:next
  30
  31 Set the "flagged" keyword and "next" label on the message with the
  32 blob OID of 59ec517f9.
  33
  34 =back
  35
  36 =head1 EXTERNALS
  37
  38 In addition to the above store, lei can make read-only queries to
  39 "externals": inboxes and external indices.  An external can be
  40 registered by passing a URL or local path to L<lei-add-external(1)>.
  41 For existing local paths, the external needs to be indexed with
  42 L<public-inbox-index(1)> (in the case of a regular inbox) or
  43 L<public-inbox-extindex(1)> (in the case of an external index).
  44
  45 =head2 EXAMPLES
  46
  47 =over
  48
  49 =item $ lei add-external https://public-inbox.org/meta/
  50
  51 Add a remote external for public-inbox's inbox.
  52
  53 =item $ lei add-external --mirror https://public-inbox.org/meta/ path
  54
  55 Clone L<https://public-inbox.org/meta/> to C<path>, index it with
  56 L<public-inbox-index(1)>, and add it as a local external.
  57
  58 =back
  59
  60 =head1 SEARCHING
  61
  62 The L<lei-q(1)> command searches the local store and externals.  The
  63 search prefixes match those available via L<public-inbox-httpd(1)>.
  64
  65 =head2 EXAMPLES
  66
  67 =over
  68
  69 =item $ lei q s:lei s:skeleton
  70
  71 Search for messages whose subject includes "lei" and "skeleton".
  72
  73 =item $ lei q -t s:lei s:skeleton
  74
  75 Do the same, but also report unmatched messages that are in the same
  76 thread as a matched message.
  77
  78 =item $ lei q -t -o mboxcl2:t.mbox --mua=mutt s:lei s:skeleton
  79
  80 Write mboxcl2-formatted results to t.mbox and enter mutt to view the
  81 file by invoking C<mutt -f %f>.
  82
  83 =item $ lei q kw:flagged L:next
  84
  85 Search for all flagged messages that also have a "next" label.
  86
  87 =item $ lei p2q HEAD | lei q --stdin -tt -o mdir
  88
  89 Search for messages that have post-image git blob IDs that match those
  90 of the current repository's HEAD commit, writing them to the Maildir
  91 directory "mdir" and flagging the messages that were an exact match.
  92
  93 =back
  94
  95 =head1 PERFORMANCE NOTES
  96
  97 L<Inline::C> is recommended for performance.  To enable it, create
  98 C<~/.cache/public-inbox/inline-c/>.
  99
 100 If Socket::MsgHdr is installed (libsocket-msghdr-perl in Debian), the
 101 first invocation of lei starts a daemon, reducing the startup cost of
 102 for future invocations (which is particularly important for Bash
 103 completion).
 104
 105 =head1 BASH COMPLETION
 106
 107 Preliminary Bash completion for lei is provided in
 108 C<contrib/completion/>.  Contributions adding support for other
 109 shells, as well as improvements to the existing Bash completion, are
 110 welcome.
 111
 112 =head1 CONTACT
 113
 114 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 115
 116 The mail archives are hosted at L<https://public-inbox.org/meta/>
 117 and L<http://hjrcffqmbrq6wope.onion/meta/>
 118
 119 =head1 COPYRIGHT
 120
 121 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
 122
 123 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>