doc: point to diff attribute in patch format docs

Commit Message

Peter Oliver April 26, 2021, 6:59 p.m. UTC

From: Peter Oliver <[e-mail]>

From the documentation for generating patch text with diff-related
commands, refer to the documentation for the diff attribute.

This attribute influences the way that patches are generated, but this
was previously not mentioned in e.g., the git-diff manpage.

Signed-off-by: Peter Oliver <[e-mail]>
---
    doc: point to diff attribute in patch format docs
    
    From the documentation for generating patch text with diff-related
    commands, refer to the documentation for the diff attribute.
    
    This attribute influences the way that patches are generated, but this
    was previously not mentioned in e.g., the git-diff manpage.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-940%2Fmavit%2Fdiff-gitattributes-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-940/mavit/diff-gitattributes-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/940

 Documentation/diff-generate-patch.txt | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)


base-commit: 48bf2fa8bad054d66bd79c6ba903c89c704201f7

Comments

Junio C Hamano April 27, 2021, 7:40 a.m. UTC | #1

"Peter Oliver via GitGitGadget" <[e-mail]> writes:

> @@ -11,7 +11,7 @@ linkgit:git-diff-files[1]
>  with the `-p` option produces patch text.
>  You can customize the creation of patch text via the
>  `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables
> -(see linkgit:git[1]).
> +(see linkgit:git[1]), and the `diff` attribute (see linkgit:gitattributes[5]).
>  
>  What the -p option produces is slightly different from the traditional
>  diff format:
> @@ -74,6 +74,10 @@ separate lines indicate the old and the new mode.
>        rename from b
>        rename to a
>  
> +5.  Hunk headers mention the name of the function to which the hunk
> +    applies.  See linkgit:gitattributes[5] for details of how to tailor
> +    to this to specific languages.

Shouldn't this part be as helpful as the change you made to the
earlier part by mentioning that the user wants to look at a specific
part of the document, instead of reading the entire gitattributes(5)
manpage?  Perhaps "Defining a custom hunk header" section is what
they want to refer to.


>  Combined diff format
>  --------------------
>
> base-commit: 48bf2fa8bad054d66bd79c6ba903c89c704201f7

Peter Oliver April 27, 2021, 10:37 a.m. UTC | #2

On Tue, 27 Apr 2021, Junio C Hamano wrote:

> "Peter Oliver via GitGitGadget" <[e-mail]> writes:
>
>> +5.  Hunk headers mention the name of the function to which the hunk
>> +    applies.  See linkgit:gitattributes[5] for details of how to tailor
>> +    to this to specific languages.
>
> Shouldn't this part be as helpful as the change you made to the
> earlier part by mentioning that the user wants to look at a specific
> part of the document, instead of reading the entire gitattributes(5)
> manpage?  Perhaps "Defining a custom hunk header" section is what
> they want to refer to.

Thanks, good suggestion.

Patch

diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 2db8eacc3ec7..ec506155fc74 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -11,7 +11,7 @@  linkgit:git-diff-files[1]
 with the `-p` option produces patch text.
 You can customize the creation of patch text via the
 `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables
-(see linkgit:git[1]).
+(see linkgit:git[1]), and the `diff` attribute (see linkgit:gitattributes[5]).
 
 What the -p option produces is slightly different from the traditional
 diff format:
@@ -74,6 +74,10 @@  separate lines indicate the old and the new mode.
       rename from b
       rename to a
 
+5.  Hunk headers mention the name of the function to which the hunk
+    applies.  See linkgit:gitattributes[5] for details of how to tailor
+    to this to specific languages.
+
 
 Combined diff format
 --------------------