Re: [PATCH] git-patch-id.txt: show that you can pipe in git-log
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
Show 6 quoted lines
> Change the manual page for git-patch-id(1) to mention in the SYNOPSIS
> that you can pipe in the git-log(1) output.
>
> The manual page only mentioned that you could pipe in `< patch`, I had
> to grep the test suite to find that you could do things like `git log
> -p -1 | git patch-id`.
I tend to try to keep a command line example in the commit message from getting split by rewording.
The manual page only mentioned that you can redirect from a file
with `<patch`; I found by grepping the test suite that you can
feed the command from a pipe, e.g. `git log -p -1 | git patch-id`.It sounds silly to say "pipe in" and "<" in the same sentence, so I'd fix that while I am at it.
Show 15 quoted lines
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/git-patch-id.txt | 2 ++
> 1 files changed, 2 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt
> index 4dae139..fec2cf3 100644
> --- a/Documentation/git-patch-id.txt
> +++ b/Documentation/git-patch-id.txt
> @@ -9,6 +9,8 @@ SYNOPSIS
> --------
> 'git patch-id' < <patch>
>
> +'git log --pretty=format:%H -p | git patch-id'
> +
The notation "< <patch>" is used as a way to say "this command reads from its standard input and acts on it". Anybody who understands what the redirection is knows that a normal command would not mind getting fed from a pipe instead of a regular file (they _could_ tell the kind of file descriptors, and there indeed are commands that change their behaviour depending on the kind of file descriptor they are being fed from, but they are exceptions). So I don't think the new information should live here.
In a sense, I do not think the original is a material for SYNOPSIS section, either. The first paragraph of DESCRIPTION section is also bad as a manual page; it doesn't say _what the command does_.
> DESCRIPTION
> -----------
> A "patch ID" is nothing but a SHA1 of the diff associated with a patch, with
How about rewriting the whole thing, along these lines...
SYNOPSIS
--------
'git patch-id' DESCRIPTION
-----------
Reads a patch from the standard input, and outputs the unique ID
for it. When fed a series of patches that records which commit
they come from (e.g. output from 'git format-patch --stdout' or
'git log -p'), reads them and outputs the unique IDs for them, one
per line. A line in its output consists of two 40-byte hexadecimal values;
1. the unique ID for the change;
2. a SP; and
3. the commit object name for the change if known, or
40 "0" letters. A "patch ID" is nothing but a SHA-1 of ... (original text, but
needs to rewrite "When dealing with..." paragraph not to mention
diff-tree because that is not a user-facing command anymore).
EXAMPLES
-------- git patch-id <patch.txt::
... (describe what this does) ...
git log -3 -p | git patch-id::
... (describe what this does) ...
Ævar Arnfjörð Bjarmason