Ãvar ArnfjÃrà Bjarmason <avarab@xxxxxxxxx> 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@xxxxxxxxx>
> ---
> 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) ...
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html