C<lei export-kw> propagates keywords (e.g. C<seen>, C<answered>,
C<flagged>, etc.) from lei/store to IMAP folders and/or Maildirs.
+It only works for messages lei knows about (e.g. was used as a
+C<lei q --output>, or imported via L<lei-import(1)>, or indexed
+via L<lei-index(1)>).
It does not delete, write, nor modify messages themselves;
it only sets metadata on Maildirs and IMAP folders.
=head1 DESCRIPTION
Forget synchronization information for C<LOCATION>, an IMAP or Maildir
-folder. Note that this won't delete any messages stored in Git,
-leaving C<lei-index(1)> users with dangling references.
+folder. Note that this won't delete any messages on the filesystem.
+Users using L<lei-index(1)> without L<lei-import(1)> will be left
+with dangling references in search results.
=head1 CONTACT
=head1 SYNOPSIS
-lei import [OPTIONS] LOCATION [LOCATION...]
+lei import [OPTIONS] LOCATION [LOCATION...] [+L:LABEL]
lei import [OPTIONS] (--stdin|-)
authentication use L<git-credential(1)> to
fill in the username and password.
-For a regular file, the location must have a C<E<lt>formatE<gt>:>
-prefix specifying one of the following formats: C<eml>, C<mboxrd>,
+For a regular file, the C<LOCATION> must have a C<E<lt>formatE<gt>:>
+prefix specifying one of the following formats: C<mboxrd>,
C<mboxcl2>, C<mboxcl>, or C<mboxo>.
=head1 OPTIONS
Default: fcntl,dotlock
+=item +L:LABEL
+
+Add the given C<LABEL> to all messages imported, where C<LABEL>
+is an arbitrary user-defined value consisting of lowercase and digits.
+See L<lei-tag(1)> for more info on labels.
+
+For example, specifying C<+L:inbox> applies the C<inbox> label
+to all messages being imported.
+
+May be specified multiple times to apply multiple labels.
+
+Default: none
+
+=item +kw:KEYWORD
+
+Apply C<KEYWORD> to all messages being imported in addition
+to any per-message keywords from the store (unless C<--no-kw>
+is specified). See L<lei-tag(1)> for more info on keywords.
+
+May be specified multiple times to apply multiple keywords.
+
+Default: none
+
=item --no-kw
Don't import message keywords (or "flags" in IMAP terminology).
=head1 COPYRIGHT
-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+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-add-external(1)>
+L<lei-index(1)>
have similar functionality to L<mairix(1)> by not duplicating
messages into C<lei/store>.
+Occasional invocations of C<lei-refresh-mail-sync --all=local>
+are recommended to keep indexed messages retrievable.
+
=head1 OPTIONS
=over
=head1 SEE ALSO
-L<lei-store-format(5)>, L<lei-import(1)>
+L<lei-refresh-mail-sync(1)>, L<lei-store-format(5)>, L<lei-import(1)>
=head1 DESCRIPTION
List all known message labels ("mailboxes" in JMAP terminology).
+This is handy for writing L<lei-import(1)> invocations.
=head1 OPTIONS
=head1 DESCRIPTION
List information about the IMAP or NNTP mail source at C<URL>.
+This command populates the cache used for Bash shell completion
+and is handy for writing L<lei-import(1)> invocations.
=head1 OPTIONS
=head1 COPYRIGHT
-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+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-import(1)>
=head1 DESCRIPTION
-List locations that lei is configured to watch.
+List locations that lei is configured to watch. This command is
+incomplete, mail-sync locations are implicitly watched.
=head1 CONTACT
Depending on the IMAP server software and configuration, IMAP
servers may use any (or combination) of the aforementioned
-formats or a non-standard database backend.
+formats or a non-standard database backend. Currently, lei
+uses L<Mail::IMAPClient> which has acceptable performance
+over low-latency links. Performance over high-latency links
+is currently poor.
=head1 eml
--- /dev/null
+=head1 NAME
+
+lei - an overview of lei mail synchronization
+
+=head1 DESCRIPTION
+
+L<lei(1)> provides several plumbing-level commands to synchronize
+mail and keywords (flags) between lei/store and existing IMAP
+and Maildir stores. Nothing documented in this manpage is required
+for day-to-day use against externals.
+
+Mail and keyword synchronization is currently a clunky process.
+Future work will be done to improve it and add IMAP IDLE support.
+
+=head1 TYPICAL WORKFLOW
+
+ # import mail from a user's IMAP inbox and give it the "inbox" label:
+ lei import +L:inbox imaps://user@example.com/INBOX
+
+ # dump "inbox" labeled files from the past week to a Maildir
+ lei q L:inbox rt:last.week.. -o /tmp/results
+
+ # open /tmp/results in your favorite mail agent. If inotify or kevent
+ # works, keyword changes (e.g. marking messages as `seen') are
+ # synchronized automatically.
+
+ # If the inotify queue overflows, or if lei-daemon crashes,
+ # "lei index" will tell lei about keyword changes:
+ lei index /tmp/results
+
+ # Optional: cleanup stale entries from mail_sync.sqlite3
+ lei refresh-mail-sync /tmp/results
+
+ # to export keyword changes back to IMAP
+ lei export-kw imaps://user@example.com/INBOX
+
+=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-import(1)>, L<lei-q(1)>, L<lei-index(1)>,
+L<lei-refresh-mail-sync(1)>, L<lei-export-kw(1)>
=head1 DESCRIPTION
-L<lei(1)> is a local email interface for public-inbox. This document
-provides some basic examples.
+L<lei(1)> is a local email interface for public-inbox and personal mail.
+This document provides some basic examples.
=head1 LEI STORE
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
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)>
=back
+=head1 LABELS
+
+Labels are user-defined values analogous to IMAP/JMAP mailbox
+names. They must only contain lowercase characters, digits, and
+a limited amount of punctuation (e.g. C<.>, C<->, C<@>).
+
+Messages may have multiple labels.
+
+=head1 KEYWORDS
+
+Keywords are "flags" in Maildir and IMAP terminology.
+Common keywords include: C<seen>, C<answered>, C<flagged>, and
+C<draft>, though C<forwarded>, C<phishing>, C<junk>, and C<notjunk>
+are also supported.
+
+When writing to various mboxes, the common keywords will be
+mapped to the C<Status> and C<X-Status> headers.
+
+Messages may have multiple keywords.
+
=head1 CONTACT
Feedback welcome via plain-text mail to 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-add-external(1)>
=item * L<lei-daemon-pid(1)>
-=item * lei-forget-mail-sync(1)
+=item * L<lei-forget-mail-sync(1)>
=item * L<lei-mail-diff(1)>
=head1 COPYRIGHT
-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>
License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
Documentation/lei-ls-watch.pod
Documentation/lei-mail-diff.pod
Documentation/lei-mail-formats.pod
+Documentation/lei-mail-sync-overview.pod
Documentation/lei-overview.pod
Documentation/lei-p2q.pod
Documentation/lei-q.pod
#!/usr/bin/perl -w
-# Copyright (C) 2013-2021 all contributors <meta@public-inbox.org>
+# Copyright (C) all contributors <meta@public-inbox.org>
# License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
use strict;
use ExtUtils::MakeMaker;
public-inbox-v2-format public-inbox-extindex-format
lei-mail-formats lei-store-format
) ];
-$v->{-m7} = [ qw(lei-overview lei-security
+$v->{-m7} = [ qw(lei-mail-sync-overview lei-overview lei-security
public-inbox-overview public-inbox-tuning
public-inbox-glossary) ];
$v->{-m8} = [ qw(public-inbox-daemon lei-daemon) ];