.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "LEI-OVERVIEW 7"
.TH LEI-OVERVIEW 7 "1993-10-02" "public-inbox.git" "public-inbox user manual"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
lei \- an overview of lei
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBlei\fR\|(1) is a local email interface for public-inbox and personal mail.
This document provides some basic examples.
.SH "LEI STORE"
.IX Header "LEI STORE"
lei has writable local storage based on \fBpublic\-inbox\-v2\-format\fR\|(5).
Commands will automatically initialize the store behind the scenes if
needed, but you can call \fBlei\-init\fR\|(1) directly if you want to use a
store location other than the default \f(CW\*(C`$XDG_DATA_HOME/lei/store\*(C'\fR.
.PP
The \fBlei\-import\fR\|(1) command provides the primary interface for
importing messages into the local storage.  In addition, other
commands, such as \fBlei\-q\fR\|(1) and \fBlei\-blob\fR\|(1), use the local store
to memoize messages from remotes.
.SS "\s-1EXAMPLES\s0"
.IX Subsection "EXAMPLES"
.IP "$ lei import mboxrd:t.mbox.gz" 4
.IX Item "$ lei import mboxrd:t.mbox.gz"
Import the messages from a gzipped mboxrd into the local storage.
.IP "$ lei blob 59ec517f9" 4
.IX Item "$ lei blob 59ec517f9"
Show message with the git blob \s-1OID\s0 of 59ec517f9.  If a message with
that \s-1OID\s0 isn't found, check if the current git repository has the
blob, trying to reconstruct it from a message if needed.
.IP "$ lei blob 59ec517f9 | lei tag \-F eml +kw:flagged +L:next" 4
.IX Item "$ lei blob 59ec517f9 | lei tag -F eml +kw:flagged +L:next"
Set the \*(L"flagged\*(R" keyword and \*(L"next\*(R" label on the message with the
blob \s-1OID\s0 of 59ec517f9.
.SH "EXTERNALS"
.IX Header "EXTERNALS"
In addition to the above store, lei can make read-only queries to
\&\*(L"externals\*(R": inboxes and external indices.  An external can be
registered by passing a \s-1URL\s0 or local path to \fBlei\-add\-external\fR\|(1).
For existing local paths, the external needs to be indexed with
\&\fBpublic\-inbox\-index\fR\|(1) (in the case of a regular inbox) or
\&\fBpublic\-inbox\-extindex\fR\|(1) (in the case of an external index).
.SH "SYNCHRONIZATION"
.IX Header "SYNCHRONIZATION"
lei currently has primitive mail synchronization abilities;
see \fBlei\-mail\-sync\-overview\fR\|(7) for more details.
.SS "\s-1EXAMPLES\s0"
.IX Subsection "EXAMPLES"
.IP "$ lei add-external https://public\-inbox.org/meta/" 4
.IX Item "$ lei add-external https://public-inbox.org/meta/"
Add a remote external for public-inbox's inbox.
.IP "$ lei add-external \-\-mirror https://public\-inbox.org/meta/ path" 4
.IX Item "$ lei add-external --mirror https://public-inbox.org/meta/ path"
Clone <https://public\-inbox.org/meta/> to \f(CW\*(C`path\*(C'\fR, index it with
\&\fBpublic\-inbox\-index\fR\|(1), and add it as a local external.
.SH "SEARCHING"
.IX Header "SEARCHING"
The \fBlei\-q\fR\|(1) command searches the local store and externals.  The
search prefixes match those available via \fBpublic\-inbox\-httpd\fR\|(1).
.SS "\s-1EXAMPLES\s0"
.IX Subsection "EXAMPLES"
.IP "$ lei q s:lei s:skeleton" 4
.IX Item "$ lei q s:lei s:skeleton"
Search for messages whose subject includes \*(L"lei\*(R" and \*(L"skeleton\*(R".
.IP "$ lei q \-t s:lei s:skeleton" 4
.IX 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.
.IP "$ lei q \-t \-o /tmp/mdir \-\-mua=mutt s:lei s:skeleton" 4
.IX Item "$ lei q -t -o /tmp/mdir --mua=mutt s:lei s:skeleton"
Write results to a Maildir at \*(L"mdir\*(R".  Mutt will be invoked
to open mfolder (\f(CW\*(C`mutt \-f %f\*(C'\fR) while results are being fetched
and written.
.IP "$ lei q kw:flagged L:next" 4
.IX Item "$ lei q kw:flagged L:next"
Search for all flagged messages that also have a \*(L"next\*(R" label.
.IP "$ lei p2q \s-1HEAD\s0 | lei q \-tt \-o /tmp/mdir" 4
.IX 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 \s-1HEAD\s0 commit, writing them to the Maildir
directory \*(L"mdir\*(R" and flagging the messages that were an exact match.
.IP "$ git show \-s \s-1HEAD\s0 | lei lcat" 4
.IX Item "$ git show -s HEAD | lei lcat"
Display a local message for the public-inbox link contained in a
commit message.
.IP "$ lei q \-f text m:MESSAGE\-ID | lei rediff \-U5" 4
.IX Item "$ lei q -f text m:MESSAGE-ID | lei rediff -U5"
Feed a message containing a diff to \fBlei\-rediff\fR\|(1) to regenerate its
diff with five context lines.  Unless \f(CW\*(C`\-\-git\-dir\*(C'\fR is specified, this
requires the current working directory to be within the associated
code repository.
.SH "PERFORMANCE NOTES"
.IX Header "PERFORMANCE NOTES"
Inline::C is required, lei runs as a background daemon to reduce
startup costs and can provide real-time \fBkqueue\fR\|(2)/\fBinotify\fR\|(7)
Maildir monitoring.  IO::KQueue (p5\-IO\-KQueue on FreeBSD) and
Linux::Inotify2 (liblinux\-inotify2\-perl and perl\-Linux\-Inotify2 in
\&.deb and .rpm\-based distros, respectively) are recommended.
.PP
Socket::MsgHdr is optional (libsocket-msghdr-perl in Debian),
and further improves startup performance.  Its effect is most felt
when using shell completion.
.SH "BASH COMPLETION"
.IX Header "BASH COMPLETION"
Preliminary Bash completion for lei is provided in
\&\f(CW\*(C`contrib/completion/\*(C'\fR.  Contributions adding support for other
shells, as well as improvements to the existing Bash completion, are
welcome.
.SH "UPGRADING"
.IX Header "UPGRADING"
Since lei runs as a daemon, \fBlei\-daemon\-kill\fR\|(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.
.SH "CAVEATS"
.IX Header "CAVEATS"
\&\s-1IMAP\s0 and \s-1NNTP\s0 client performance is poor on high-latency connections.
It will hopefully be fixed in 2022.
.SH "CONTACT"
.IX Header "CONTACT"
Feedback welcome via plain-text mail to <mailto:meta@public\-inbox.org>
.PP
The mail archives are hosted at <https://public\-inbox.org/meta/> and
<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright all contributors <mailto:meta@public\-inbox.org>
.PP
License: \s-1AGPL\-3.0+\s0 <https://www.gnu.org/licenses/agpl\-3.0.txt>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlei\-mail\-sync\-overview\fR\|(7)