From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-3.2 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from out2.migadu.com (out2.migadu.com [IPv6:2001:41d0:2:aacc::]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id 6DC2A1F5AF for ; Mon, 29 Mar 2021 03:12:04 +0000 (UTC) X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kyleam.com; s=key1; t=1616987522; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=1C2ngJjEtIqQu1WmIaRnuKrQwdLAg//rQvyZGE0/zRc=; b=scC3XWyM5XmSnJt2osez0v18jKzpfZdZynhDNm1Jb197d4um8EMebNWmehIeLB2dGeGAVF fIeSeEsM7XvqjLh26+1DAeOVYRxs9cG+L5HTCtyt3Um366NR83tF5r7TmPpkaulVz7hoUd BgBGwKcQmlbJ4wFyCy7CJHupeVMBVvq10Szf5apLrYRrLi/+G7WUYXaHw//nurniK/woZl th3VDp2NvcskdUaFAshIUluwB+JJ5Xey3rAA5uSheGrhVbEkZaazrVb1vD8qAnX/iyqoNu BYQOoyqVOpyQY+iwDg95jmVt8D2r7ivl67F8T/PgwYH5Wk9yWwBMMHoX5dgd1g== From: Kyle Meyer To: meta@public-inbox.org Subject: [PATCH 6/8] doc lei: add manpages for new commands Date: Sun, 28 Mar 2021 23:11:15 -0400 Message-Id: <20210329031117.28516-7-kyle@kyleam.com> In-Reply-To: <20210329031117.28516-1-kyle@kyleam.com> References: <20210329031117.28516-1-kyle@kyleam.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Migadu-Flow: FLOW_OUT X-Migadu-Auth-User: kyle@kyleam.com List-Id: --- Documentation/lei-blob.pod | 109 +++++++++++++++++++++++++++++++++ Documentation/lei-ls-label.pod | 43 +++++++++++++ Documentation/lei-mark.pod | 58 ++++++++++++++++++ Documentation/lei-overview.pod | 21 +++++++ Documentation/lei-p2q.pod | 79 ++++++++++++++++++++++++ Documentation/lei.pod | 8 +++ Documentation/txt2pre | 4 ++ MANIFEST | 4 ++ Makefile.PL | 5 +- 9 files changed, 329 insertions(+), 2 deletions(-) create mode 100644 Documentation/lei-blob.pod create mode 100644 Documentation/lei-ls-label.pod create mode 100644 Documentation/lei-mark.pod create mode 100644 Documentation/lei-p2q.pod diff --git a/Documentation/lei-blob.pod b/Documentation/lei-blob.pod new file mode 100644 index 00000000..ecdd1e99 --- /dev/null +++ b/Documentation/lei-blob.pod @@ -0,0 +1,109 @@ +=head1 NAME + +lei-blob - display a git blob, reconstructing from mail if necessary + +=head1 SYNOPSIS + +lei blob [OPTIONS] OID + +=head1 DESCRIPTION + +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. + +=head1 OPTIONS + +=over + +=item --git-dir=DIR + +Specify an additional .git/ directory to scan. This option may be +given multiple times. + +=item --no-cwd + +Do not look in the git repository of the current working directory. + +=item --no-mail + +Do not look in mail storage for C. This is implied by +C<--oid-a>, C<--path-a>, and C<--path-b>. + +=item -A OID-A, --oid-a=OID-A + +=item -a PATH-A, --path-a=PATH-A + +=item -b PATH-B, --path-b=PATH-B + +Provide pre-image object ID, pre-image pathname, or post-image +pathname as a hint for reconstructing C. + +=for comment +TODO: The below options are shared with lei-q. Any good approaches to +not repeating the text? + +=item --[no-]remote + +Whether to include results requiring network access. When local +externals are configured, C<--remote> must be explicitly passed to +enable reporting of results from remote externals. + +=item --no-local + +Limit operations to those requiring network access. + +=item --no-external + +Don't include results from externals. + +=item -I LOCATION, --include=LOCATION + +Include specified external in search. This option may be given +multiple times. + +=item --exclude=LOCATION + +Exclude specified external from search. This option may be given +multiple times. + +=item --only=LOCATION + +Use only the specified external for search. This option may be given +multiple times, in which case the search uses only the specified set. + +=item --no-import-remote + +Disable the default behavior of memoizing remote messages into the +local store. + +=item -v, --verbose + +Provide more feedback on stderr. + +=item --torsocks=auto|no|yes, --no-torsocks + +Whether to wrap L and L commands with torsocks. + +Default: C + +=back + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L +and L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L diff --git a/Documentation/lei-ls-label.pod b/Documentation/lei-ls-label.pod new file mode 100644 index 00000000..0b4e8769 --- /dev/null +++ b/Documentation/lei-ls-label.pod @@ -0,0 +1,43 @@ +=head1 NAME + +lei-ls-label - list labels + +=head1 SYNOPSIS + +lei ls-label [OPTIONS] + +=head1 DESCRIPTION + +List all known message labels ("mailboxes" in JMAP terminology). + +=head1 OPTIONS + +=over + +=item -z, -0 + +Use C<\0> (NUL) instead of newline (CR) to delimit lines. + +=item -q, --quiet + +Suppress feedback messages. + +=back + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L +and L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L diff --git a/Documentation/lei-mark.pod b/Documentation/lei-mark.pod new file mode 100644 index 00000000..8ef1dce2 --- /dev/null +++ b/Documentation/lei-mark.pod @@ -0,0 +1,58 @@ +=head1 NAME + +lei-mark - set/unset metadata on messages + +=head1 SYNOPSIS + +lei mark [OPTIONS] FILE [FILE...] METADATA [METADATA...] + +lei mark [OPTIONS] (-|--stdin) METADATA [METADATA...] + +=head1 DESCRIPTION + +Set or unset volatile metadata on messages. In JMAP terms, "volatile +metadata" includes "mailboxes" (analogous to a folder or label) and a +restricted set of "keywords". This supported keywords are the +combination of system keywords (seen, answered, flagged, and draft), +which map to Maildir flags and mbox Status/X-Status headers, as well +as reserved keywords (forwarded, phishing, junk, and notjunk). + +To add a label or keyword, prefix it with "+L:" and "+kw:", +respectively. To remove a label or keyword, use "-L:" or "-kw:". For +example, "+kw:flagged" would set the "flagged" keyword for the +specified messages, and "-L:INBOX" would remove the "INBOX" label. + +=head1 OPTIONS + +=over + +=item -F MAIL_FORMAT, --in-format=MAIL_FORMAT + +Message input format: C, C, C, C, or +C. + +Default: C + +=item -q, --quiet + +Suppress feedback messages. + +=back + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L +and L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod index c3379caa..7c7337ab 100644 --- a/Documentation/lei-overview.pod +++ b/Documentation/lei-overview.pod @@ -20,6 +20,17 @@ L. 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 @@ -69,6 +80,16 @@ thread as a matched message. Write mboxcl2-formatted results to t.mbox and enter mutt to view the file by invoking C. +=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 diff --git a/Documentation/lei-p2q.pod b/Documentation/lei-p2q.pod new file mode 100644 index 00000000..cc342bd5 --- /dev/null +++ b/Documentation/lei-p2q.pod @@ -0,0 +1,79 @@ +=head1 NAME + +lei-p2q - use a patch to generate a lei-q query + +=head1 SYNOPSIS + +lei p2q [OPTIONS] (FILE|COMMIT) + +lei p2q [OPTIONS] (--stdin|-) + +=head1 DESCRIPTION + +Given a patch, create a query that can be fed on stdin to L. +This is useful for mapping the patch to associated messages of an +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 +L is used to generate the patch. + +=head1 OPTIONS + +=over + +=item -w PREFIX[,PREFIX], --want=PREFIX[,PREFIX] + +Search prefixes to use. C (post-image git blob ID) and C +(file names from the diff) are the most useful. Other available +values are C, C, C, C, and C. + +=for comment +TODO: Put a table of prefixes somewhere and reference that (at least +here and in lei-q)? + +Appending an integer to C or C indicates a minimum ID +length, and the generated query will be for that value up through the +default abbreviation length. For example, if the repository's +C is set to C and git calculates the default +abbreviation length as 7, C will expand a post-image blob ID +of e7b4b32 (seven characters) into C. + +This option may be given multiple times. + +Default: C + +=item --stdin + +Read patch from stdin. + +=item --debug + +Dump output that shows the information collected for every prefix. +This information can be useful for seeing how a patch is processed, +but the format should not be considered stable. + +=item -q, --quiet + +Suppress feedback messages. + +=back + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L +and L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L diff --git a/Documentation/lei.pod b/Documentation/lei.pod index 0b81b9f3..6c8cfc3d 100644 --- a/Documentation/lei.pod +++ b/Documentation/lei.pod @@ -46,6 +46,8 @@ Subcommands for initializing and managing local, writable storage: =item * L +=item * L + =back The following subcommands can be used to manage and inspect external @@ -66,6 +68,10 @@ store and configured externals are =over +=item * L + +=item * L + =item * L =back @@ -80,6 +86,8 @@ Other subcommands include =item * L +=item * L + =back =head1 FILES diff --git a/Documentation/txt2pre b/Documentation/txt2pre index 244dc50c..bfffdef1 100755 --- a/Documentation/txt2pre +++ b/Documentation/txt2pre @@ -12,6 +12,7 @@ use PublicInbox::Hval qw(ascii_html); my %xurls; for (qw[lei(1) lei-add-external(1) + lei-blob(1) lei-config(1) lei-daemon-kill(1) lei-daemon-pid(1) @@ -19,7 +20,10 @@ for (qw[lei(1) lei-import(1) lei-init(1) lei-ls-external(1) + lei-ls-label(1) + lei-mark(1) lei-overview(7) + lei-p2q(1) lei-q(1) public-inbox.cgi(1) public-inbox-compact(1) diff --git a/MANIFEST b/MANIFEST index 913ce55c..3d521a64 100644 --- a/MANIFEST +++ b/MANIFEST @@ -22,6 +22,7 @@ Documentation/flow.txt Documentation/hosted.txt Documentation/include.mk Documentation/lei-add-external.pod +Documentation/lei-blob.pod Documentation/lei-config.pod Documentation/lei-daemon-kill.pod Documentation/lei-daemon-pid.pod @@ -29,7 +30,10 @@ Documentation/lei-forget-external.pod Documentation/lei-import.pod Documentation/lei-init.pod Documentation/lei-ls-external.pod +Documentation/lei-ls-label.pod +Documentation/lei-mark.pod Documentation/lei-overview.pod +Documentation/lei-p2q.pod Documentation/lei-q.pod Documentation/lei.pod Documentation/marketing.txt diff --git a/Makefile.PL b/Makefile.PL index 8165e601..cdb67214 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -44,8 +44,9 @@ $v->{-m1} = [ map { } } @EXE_FILES, qw( - lei-add-external lei-config lei-daemon-kill lei-daemon-pid - lei-forget-external lei-import lei-init lei-ls-external lei-q)]; + lei-add-external lei-blob lei-config lei-daemon-kill lei-daemon-pid + lei-forget-external lei-import lei-init lei-ls-external lei-ls-label + lei-mark lei-p2q lei-q)]; $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format public-inbox-v2-format public-inbox-extindex-format) ]; $v->{-m7} = [ qw(lei-overview public-inbox-overview public-inbox-tuning -- 2.31.0