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

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

[Ævar Arnfjörð Bjarmason]

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

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'
+
 DESCRIPTION
 -----------
 A "patch ID" is nothing but a SHA1 of the diff associated with a patch, with
-- 
1.7.2.3

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

[Junio C Hamano]

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

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

[Ævar Arnfjörð Bjarmason]

On Wed, Feb 16, 2011 at 20:35, Junio C Hamano <gitster@pobox.com> wrote:
> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

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

Yes, but see below.

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

This looks much better.

What I was aiming for was not to explain that:

    cat foo | thing
    thing < foo

Are the same thing, but that nothing in git-patch-id's previous
manpage suggested that it could take a stream of commits, from reading
it it looked like I would have to flush each individual patch to disk,
then feed them in one-by-one.

But your revised manpage explains that much better, you should commit
it.