threads / patch / 55564

patchdoc: point to diff attribute in patch format docs

Subject: [PATCH] doc: point to diff attribute in patch format docs

## tl;dr

4 messages between Apr 26, 2021 and Apr 27, 2021. Diffs are folded; open one to read it.

replies: 3people: 2as markdown or json

Peter Oliver via GitGitGadget· Apr 26, 2021, 18:59 UTC · lore

From: Peter Oliver <git@mavit.org.uk>

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 <git@mavit.org.uk>
---
    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(-)

Show changes to Documentation/diff-generate-patch.txt +5 −1

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

base-commit: 48bf2fa8bad054d66bd79c6ba903c89c704201f7

-- 
gitgitgadget

Junio C Hamano· Apr 27, 2021, 07:40 UTC · re: Peter Oliver via GitGitGadget · lore

Re: [PATCH] doc: point to diff attribute in patch format docs

"Peter Oliver via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 16 quoted lines

> @@ -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· Apr 27, 2021, 10:37 UTC · re: Junio C Hamano · lore

Re: [PATCH] doc: point to diff attribute in patch format docs

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

Show 11 quoted lines

> "Peter Oliver via GitGitGadget" <gitgitgadget@gmail.com> 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.

-- 
Peter Oliver

Peter Oliver via GitGitGadget· Apr 27, 2021, 11:02 UTC · re: Peter Oliver via GitGitGadget · lore

[PATCH v2] doc: point to diff attribute in patch format docs

From: Peter Oliver <git@mavit.org.uk>

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 <git@mavit.org.uk>
---
    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.
    
    v2: Mention the specific relevant section of the gitattributes manual.
    Thanks to Junio C Hamano for the suggestion.

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

Range-diff vs v1:

 1:  6f87f3962b84 ! 1:  191d81ef61a5 doc: point to diff attribute in patch format docs
     @@ Documentation/diff-generate-patch.txt: separate lines indicate the old and the n
             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.
     ++    applies.  See "Defining a custom hunk-header" in
     ++    linkgit:gitattributes[5] for details of how to tailor to this to
     ++    specific languages.
      +
       
       Combined diff format

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

Show changes to Documentation/diff-generate-patch.txt +6 −1

diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 2db8eacc3ec7..c78063d4f74a 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,11 @@ 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 "Defining a custom hunk-header" in
+    linkgit:gitattributes[5] for details of how to tailor to this to
+    specific languages.
+
 
 Combined diff format
 --------------------

base-commit: 311531c9de557d25ac087c1637818bd2aad6eb3a

-- 
gitgitgadget