Re: [PATCH] git-patch-id.txt: show that you can pipe in git-log

[Junio C Hamano <gitster@pobox.com>]

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> 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.

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