From 39d06d18fd836a0a474815508aa9fec86b7b336c Mon Sep 17 00:00:00 2001
From: Eric Wong <e@80x24.org>
Date: Fri, 24 Sep 2021 12:51:06 +0000
Subject: doc: lei blob+rediff+p2q: add notes about git directory

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(-)

(limited to 'Documentation')

diff --git a/Documentation/lei-blob.pod b/Documentation/lei-blob.pod
index 5b611d11..429d206e 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 44798ac3..1068ff0b 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 c7db6c1e..f34e946f 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
-- 
cgit v1.2.3-24-ge0c7