[PATCH] Documentation/git-patch-id: give working code example

Michael J Gruber· Aug 24, 2016, 12:56 UTC · lore

As it stands, the documentation gives the impression that

git diff-tree <treeish> | git patch-id

would be a working invocation of git patch-id, leaving the novice user in the dark.

Make it explicit that 'git diff-tree -p' would be the command to use.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 Documentation/git-patch-id.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Show changes to Documentation/git-patch-id.txt +1 −1

diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt
index cf71fba..67f8e28 100644
--- a/Documentation/git-patch-id.txt
+++ b/Documentation/git-patch-id.txt
@@ -21,7 +21,7 @@ have the same "patch ID" are almost guaranteed to be the same thing.
 
 IOW, you can use this thing to look for likely duplicate commits.
 
-When dealing with 'git diff-tree' output, it takes advantage of
+When dealing with 'git diff-tree -p' output, it takes advantage of
 the fact that the patch is prefixed with the object name of the
 commit, and outputs two 40-byte hexadecimal strings.  The first
 string is the patch ID, and the second string is the commit ID.

-- 
2.10.0.rc0.268.ge3ba28a

Junio C Hamano· Aug 24, 2016, 16:18 UTC · re: Michael J Gruber · lore

Re: [PATCH] Documentation/git-patch-id: give working code example

Michael J Gruber <git@drmicha.warpmail.net> writes:

Show 8 quoted lines

> As it stands, the documentation gives the impression that
>
> git diff-tree <treeish> | git patch-id
>
> would be a working invocation of git patch-id, leaving the novice user
> in the dark.
>
> Make it explicit that 'git diff-tree -p' would be the command to use.

I take the lack of <treeish> as a strong hint that it is not meant to be the full command line but merely there to make the command the description talks about stand out from others (i.e. "This description does not apply to 'diff-files' or 'diff-cache' output").

So I would think it is fine as-is.

Having said that, if we were to change something, I would rather replace the mention of "diff-tree" with something like "git show" or "git log -p", neither of which were even present in their current form back when this piece of text was written.

Show 19 quoted lines

>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
>  Documentation/git-patch-id.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt
> index cf71fba..67f8e28 100644
> --- a/Documentation/git-patch-id.txt
> +++ b/Documentation/git-patch-id.txt
> @@ -21,7 +21,7 @@ have the same "patch ID" are almost guaranteed to be the same thing.
>  
>  IOW, you can use this thing to look for likely duplicate commits.
>  
> -When dealing with 'git diff-tree' output, it takes advantage of
> +When dealing with 'git diff-tree -p' output, it takes advantage of
>  the fact that the patch is prefixed with the object name of the
>  commit, and outputs two 40-byte hexadecimal strings.  The first
>  string is the patch ID, and the second string is the commit ID.

patchDocumentation/git-patch-id: give working code example