* [PATCH 1/4] doc: lei blob+rediff+p2q: add notes about git directory
2021-09-24 12:51 [PATCH 0/4] doc: lei: some manpage updaets Eric Wong
@ 2021-09-24 12:51 ` Eric Wong
2021-09-24 12:51 ` [PATCH 2/4] doc: lei-overview: implicit stdin, correct Inline::C notes Eric Wong
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2021-09-24 12:51 UTC (permalink / raw)
To: meta
Try to clarify these commands are intended to be useful for
git-using (usually software) projects (and not the bare git
repos we use internally).
We'll also document some commonly useful git-diff switches
in the lei-rediff man page to highlight the usefulness
of the command.
---
Documentation/lei-blob.pod | 6 ++++--
Documentation/lei-p2q.pod | 2 +-
Documentation/lei-rediff.pod | 23 +++++++++++++++++++++--
3 files changed, 26 insertions(+), 5 deletions(-)
diff --git a/Documentation/lei-blob.pod b/Documentation/lei-blob.pod
index 5b611d11ba1f..429d206e358e 100644
--- a/Documentation/lei-blob.pod
+++ b/Documentation/lei-blob.pod
@@ -10,8 +10,8 @@ lei blob [OPTIONS] OID
Display a git blob. The blob may correspond to a message from the
local store, an existing blob in the current repository, or a
-not-yet-created blob in the current repository that can be
-reconstructed from a message.
+not-yet-created blob in the current git project repository (if any)
+that can be reconstructed from a message.
=head1 OPTIONS
@@ -22,6 +22,8 @@ reconstructed from a message.
Specify an additional .git/ directory to scan. This option may be
given multiple times.
+Default: the output of C<git rev-parse --git-dir>
+
=item --no-cwd
Do not look in the git repository of the current working directory.
diff --git a/Documentation/lei-p2q.pod b/Documentation/lei-p2q.pod
index 44798ac3d2a0..1068ff0beb27 100644
--- a/Documentation/lei-p2q.pod
+++ b/Documentation/lei-p2q.pod
@@ -16,7 +16,7 @@ inbox.
The patch can be provided on stdin or as a file. Alternatively, when
an argument is given that does not point to an existing file, it is
-taken as a reference to a commit in the current repository, and
+taken as a reference to a commit in the current git repository, and
L<git-format-patch(1)> is used to generate the patch.
=head1 OPTIONS
diff --git a/Documentation/lei-rediff.pod b/Documentation/lei-rediff.pod
index c7db6c1e20b6..f34e946ffe52 100644
--- a/Documentation/lei-rediff.pod
+++ b/Documentation/lei-rediff.pod
@@ -15,10 +15,15 @@ the specified L<git-diff(1)> options. This is useful if you want to
change the display of the original patch (e.g., increasing context,
coloring moved lines differently, or using an external diff viewer).
+It relies on the contents of the .git directory of your current
+project working tree. In other words, it works anywhere
+L<git-am(1)> works. Otherwise, C<--git-dir=> may be specified
+any number of times to add repositories to build blob data from.
+
=head1 OPTIONS
-In addition to many L<git-diff(1)>, the following options are
-supported.
+In addition to many L<git-diff(1)> options (e.g. C<-W>, C<-w>,
+C<-U $LINES>) the following options are supported:
=over
@@ -27,15 +32,29 @@ supported.
Read message from stdin. This is implicit if no arguments are given
and stdin is a pipe or regular file.
+For users of text editors and pagers capable of piping its
+buffer to arbitrary commands, it is useful to pipe a patch email
+to C<lei rediff> before piping it to L<git-am(1)>. The output
+of C<lei rediff> is compatible with C<git am> if its input was a
+patch email.
+
=item --git-dir=DIR
Specify an additional .git/ directory to scan. This option may be
given multiple times.
+Default: the output of C<git rev-parse --git-dir>
+
=item --no-cwd
Do not look in the git repository of the current working directory.
+=item -q
+
+=item --quiet
+
+Suppress progress output.
+
=item -v
=item --verbose
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 2/4] doc: lei-overview: implicit stdin, correct Inline::C notes
2021-09-24 12:51 [PATCH 0/4] doc: lei: some manpage updaets Eric Wong
2021-09-24 12:51 ` [PATCH 1/4] doc: lei blob+rediff+p2q: add notes about git directory Eric Wong
@ 2021-09-24 12:51 ` Eric Wong
2021-09-24 12:51 ` [PATCH 3/4] doc: lei-index: remove --stdin, reword -F Eric Wong
2021-09-24 12:51 ` [PATCH 4/4] doc: lei: manpages for export-kw and refresh-mail-sync Eric Wong
3 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2021-09-24 12:51 UTC (permalink / raw)
To: meta
Implicit stdin based on standard input being a pipe or regular
file is here to stay, so save users the trouble of typing '-'
or '--stdin'.
Inline::C is required as of commit 1d6e1f9a6a66 (lei: require
Socket::MsgHdr or Inline::C, drop oneshot, 2021-05-26); but
Socket::MsgHdr still gives a noticeable improvement in bash
completion speed.
Also, spell-out "MESSAGE-ID" since "MID" is actually not a
common abbreviation ("MSGID" is used by RFC 3977 and several
other RFCs, I recall).
---
Documentation/lei-overview.pod | 22 ++++++++++++----------
1 file changed, 12 insertions(+), 10 deletions(-)
diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod
index e80cb094cecc..40a7b0aadd04 100644
--- a/Documentation/lei-overview.pod
+++ b/Documentation/lei-overview.pod
@@ -33,7 +33,7 @@ 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 tag - -F eml +kw:flagged +L:next
+=item $ lei blob 59ec517f9 | lei tag -F eml +kw:flagged +L:next
Set the "flagged" keyword and "next" label on the message with the
blob OID of 59ec517f9.
@@ -92,18 +92,18 @@ and written.
Search for all flagged messages that also have a "next" label.
-=item $ lei p2q HEAD | lei q --stdin -tt -o /tmp/mdir
+=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 HEAD commit, writing them to the Maildir
directory "mdir" and flagging the messages that were an exact match.
-=item $ git show -s HEAD | lei lcat -
+=item $ git show -s HEAD | lei lcat
Display a local message for the public-inbox link contained in a
commit message.
-=item $ lei q -f text m:MID | lei rediff -U5 -
+=item $ lei q -f text m:MESSAGE-ID | lei rediff -U5
Feed a message containing a diff to L<lei-rediff(1)> to regenerate its
diff with five context lines. Unless C<--git-dir> is specified, this
@@ -114,13 +114,15 @@ code repository.
=head1 PERFORMANCE NOTES
-L<Inline::C> is recommended for performance. To enable it, create
-C<~/.cache/public-inbox/inline-c/>.
+L<Inline::C> is required, lei runs as a background daemon to reduce
+startup costs and can provide real-time L<kqueue(2)>/L<inotify(7)>
+Maildir monitoring. L<IO::KQueue> (p5-IO-KQueue on FreeBSD) and
+L<Linux::Inotify2> (liblinux-inotify2-perl and perl-Linux-Inotify2 in
+.deb and .rpm-based distros, respectively) are recommended.
-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).
+L<Socket::MsgHdr> is optional (libsocket-msghdr-perl in Debian),
+and further improves startup performance. Its effect is most felt
+when using shell completion.
=head1 BASH COMPLETION
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 3/4] doc: lei-index: remove --stdin, reword -F
2021-09-24 12:51 [PATCH 0/4] doc: lei: some manpage updaets Eric Wong
2021-09-24 12:51 ` [PATCH 1/4] doc: lei blob+rediff+p2q: add notes about git directory Eric Wong
2021-09-24 12:51 ` [PATCH 2/4] doc: lei-overview: implicit stdin, correct Inline::C notes Eric Wong
@ 2021-09-24 12:51 ` Eric Wong
2021-09-24 12:51 ` [PATCH 4/4] doc: lei: manpages for export-kw and refresh-mail-sync Eric Wong
3 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2021-09-24 12:51 UTC (permalink / raw)
To: meta
lei-index really only works for Maildir, at the moment.
---
Documentation/lei-index.pod | 18 +++++-------------
1 file changed, 5 insertions(+), 13 deletions(-)
diff --git a/Documentation/lei-index.pod b/Documentation/lei-index.pod
index bd125bcceb63..9e72026351a1 100644
--- a/Documentation/lei-index.pod
+++ b/Documentation/lei-index.pod
@@ -6,8 +6,6 @@ lei-index - index messages without importing them into lei/store
lei index [OPTIONS] FOLDER
-lei index [OPTIONS] --stdin
-
=head1 DESCRIPTION
Similar to L<lei-import(1)>, but does not store a copy of
@@ -26,22 +24,16 @@ messages into C<lei/store>.
=over
-=item -
-
-=item --stdin
-
-Read input from standard input. This is the default if standard
-input is a pipe or regular file and there are no arguments on
-the command-line.
-
=item -F MAIL_FORMAT
=item --in-format=MAIL_FORMAT
-Message input format: C<eml>, C<maildir>, C<imap>, C<imaps>, C<nntp>,
-C<nntps>, C<mboxrd>, C<mboxcl2>, C<mboxcl>, or C<mboxo>.
+There is currently no need for this option. It will support C<mh>,
+eventually. For now, the default (and only supported) format is
+C<maildir>. When IMAP and NNTP support are fleshed out, those
+formats will be inferred from their URLs.
-Default: C<eml> when reading from stdin
+Default: C<maildir>
=item -q
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH 4/4] doc: lei: manpages for export-kw and refresh-mail-sync
2021-09-24 12:51 [PATCH 0/4] doc: lei: some manpage updaets Eric Wong
` (2 preceding siblings ...)
2021-09-24 12:51 ` [PATCH 3/4] doc: lei-index: remove --stdin, reword -F Eric Wong
@ 2021-09-24 12:51 ` Eric Wong
3 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2021-09-24 12:51 UTC (permalink / raw)
To: meta
Something is better than nothing.
---
Documentation/lei-export-kw.pod | 52 ++++++++++++++++++++++
Documentation/lei-refresh-mail-sync.pod | 57 +++++++++++++++++++++++++
MANIFEST | 2 +
Makefile.PL | 5 ++-
4 files changed, 115 insertions(+), 1 deletion(-)
create mode 100644 Documentation/lei-export-kw.pod
create mode 100644 Documentation/lei-refresh-mail-sync.pod
diff --git a/Documentation/lei-export-kw.pod b/Documentation/lei-export-kw.pod
new file mode 100644
index 000000000000..cf482ca0d307
--- /dev/null
+++ b/Documentation/lei-export-kw.pod
@@ -0,0 +1,52 @@
+=head1 NAME
+
+lei-export-kw - export keywords (flags) to Maildir and IMAP folders
+
+=head1 SYNOPSIS
+
+lei export-kw --all=[<remote|local>]
+
+lei export-kw MFOLDER [MFOLDER...]
+
+=head1 DESCRIPTION
+
+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 does not delete, write, nor modify messages themselves;
+it only sets metadata on Maildirs and IMAP folders.
+
+=head1 OPTIONS
+
+=over
+
+=item --all
+
+Export to all local Maildirs and remote IMAP folders
+
+=item --all=local
+
+Export all local Maildirs
+
+=item --all=remote
+
+Export all remote IMAP folders
+
+=back
+
+=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-refresh-mail-sync(1)>, L<lei-tag(1)>
diff --git a/Documentation/lei-refresh-mail-sync.pod b/Documentation/lei-refresh-mail-sync.pod
new file mode 100644
index 000000000000..aefd516fad93
--- /dev/null
+++ b/Documentation/lei-refresh-mail-sync.pod
@@ -0,0 +1,57 @@
+=head1 NAME
+
+lei-refresh-mail-sync - refresh sync info with Maildir, IMAP
+
+=head1 SYNOPSIS
+
+lei refresh-mail-sync --all[=<remote|local>]
+
+lei refresh-mail-sync MFOLDER [MFOLDER...]
+
+=head1 DESCRIPTION
+
+C<lei refresh-mail-sync> is intended to to keep old messages
+indexed with L<lei-index(1)> retrievable if Maildir flags change
+a filename. It will prune invalid entries for messages which no
+longer exist in a Maildir.
+
+It is also useful for ensuring L<lei-export-kw(1)> can propagate
+keyword (flag) changes to Maildirs and IMAP folders.
+
+It only needs read-only access to Maildirs and IMAP folders
+and will not attempt to write to them at all.
+
+=head1 OPTIONS
+
+=over
+
+=item --all
+
+Refresh all local Maildirs and remote IMAP folders
+
+=item --all=local
+
+Refresh all local Maildirs
+
+=item --all=remote
+
+Refresh all remote IMAP folders
+
+=back
+
+=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-index(1)>, L<lei-export-kw(1)>
diff --git a/MANIFEST b/MANIFEST
index 8c2e964b3dce..3595195a6996 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -28,6 +28,7 @@ Documentation/lei-convert.pod
Documentation/lei-daemon-kill.pod
Documentation/lei-daemon-pid.pod
Documentation/lei-edit-search.pod
+Documentation/lei-export-kw.pod
Documentation/lei-forget-external.pod
Documentation/lei-forget-search.pod
Documentation/lei-import.pod
@@ -43,6 +44,7 @@ Documentation/lei-overview.pod
Documentation/lei-p2q.pod
Documentation/lei-q.pod
Documentation/lei-rediff.pod
+Documentation/lei-refresh-mail-sync.pod
Documentation/lei-rm.pod
Documentation/lei-security.pod
Documentation/lei-store-format.pod
diff --git a/Makefile.PL b/Makefile.PL
index f56445ae422d..00a558d12472 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -46,9 +46,12 @@ $v->{-m1} = [ map {
} @EXE_FILES,
qw(
lei-add-external lei-blob lei-config lei-convert lei-edit-search
+ lei-export-kw
lei-daemon-kill lei-daemon-pid lei-forget-external lei-forget-search
lei-import lei-index lei-init lei-lcat lei-ls-external lei-ls-label
- lei-ls-mail-sync lei-ls-search lei-p2q lei-q lei-rediff lei-rm lei-tag
+ lei-ls-mail-sync lei-ls-search lei-p2q lei-q lei-rediff
+ lei-refresh-mail-sync
+ lei-rm lei-tag
lei-up)];
$v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format
public-inbox-v2-format public-inbox-extindex-format
^ permalink raw reply related [flat|nested] 5+ messages in thread