user/dev discussion of public-inbox itself
 help / color / mirror / code / Atom feed
blob f74a228ab21b5de1e10cb45ce0fc56f2d1502ced 3784 bytes (raw)
name: Documentation/lei-overview.pod 	 # note: path name is non-authoritative(*)

  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
 
=head1 NAME

lei - an overview of lei

=head1 DESCRIPTION

L<lei(1)> is a local email interface for public-inbox.  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

Import the messages from an mbox 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 mark - -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).

=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 mboxcl2:t.mbox --mua=mutt s:lei s:skeleton

Write mboxcl2-formatted results to t.mbox and enter mutt to view the
file by invoking C<mutt -f %f>.

=item $ lei q kw:flagged L:next

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

=item $ lei p2q HEAD | lei q --stdin -tt -o 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.

=back

=head1 PERFORMANCE NOTES

L<Inline::C> is recommended for performance.  To enable it, create
C<~/.cache/public-inbox/inline-c/>.

If Socket::MsgHdr is installed (libsocket-msghdr-perl in Debian), the
first invocation of lei starts a daemon, reducing the startup cost of
for future invocations (which is particularly important for Bash
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 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://hjrcffqmbrq6wope.onion/meta/>

=head1 COPYRIGHT

Copyright 2021 all contributors L<mailto:meta@public-inbox.org>

License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>

debug log:

solving f74a228a ...
found f74a228a in https://80x24.org/public-inbox.git

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this public inbox

	https://80x24.org/public-inbox.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).