Re: Configuring a third-party git hook

[Junio C Hamano <gitster@pobox.com>]

Chris Angelico <rosuav@gmail.com> writes:

> On Fri, Mar 21, 2014 at 2:43 PM, Jeff King <peff@peff.net> wrote:
>> Thanks, the new text looks good to me. Please follow SubmittingPatches
>> (notably, you need to sign-off your work, and please send patches inline
>> rather than as attachments).
>
> Ah, didn't see that file.

It appears that we might need to be more explicit in that file,
though.

>
> From 6e1fc126ece37c6201d0c16b76c6c87781f7b02b Mon Sep 17 00:00:00 2001

Never paste the above line to your e-mail message.  It is only used
to separate individual messages/patches in the format-patch output.

> From: Chris Angelico <rosuav@gmail.com>
> Date: Fri, 21 Mar 2014 10:45:08 +1100
> Subject: [PATCH] Explain that third-party tools may create 'git config'
>  variables

You _may_ paste these in-body pseudo-header lines at the beginning of your
e-mail but (1) then these must be the first lines of your message,
not after doing random discussions at the beginning of the message
(you may separate that with scissors marker "-- >8 --", though),
and (2) do so only they are used to correct what appears in the real
header lines in your e-mail message.

 * "From: " is useful only when you are forwarding a patch written
   by somebody else; otherwise your authorship can be taken from the
   e-mail "From: " header.

 * "Date: " is the same way; "Date :" header in your e-mail is
   closer to the time wider world saw the change for the first time
   than when you made the commit, so it is usually not desired to
   see in-body pseudo-header.

 * "Subject: " is used a lot more often than the above two,
   especially when you send a patch to an on-going discussion thread
   as a "how about doing it this way?" patch and do not want to
   change the e-mail Subject: (which may break the discussion
   thread).

Also I'd title the commit with the area it touches, i.e. starting it
with "Explain blah" is suboptimal.

Will queue with a minor tweak, with retitling the change and
rephrasing the "ideally" part, which invites people to say "well it
may be so in the ideal world but the rule does not apply to me".

Thanks.

-- >8 --
From: Chris Angelico <rosuav@gmail.com>
Date: Fri, 21 Mar 2014 15:07:08 +1100
Subject: [PATCH] config.txt: third-party tools may and do use their own variables

Signed-off-by: Chris Angelico <rosuav@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/config.txt | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index ab26963..a1ea605 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -131,8 +131,13 @@ Variables
 
 Note that this list is non-comprehensive and not necessarily complete.
 For command-specific variables, you will find a more detailed description
-in the appropriate manual page. You will find a description of non-core
-porcelain configuration variables in the respective porcelain documentation.
+in the appropriate manual page.
+
+Other git-related tools may and do use their own variables.  When
+inventing new variables for use in your own tool, make sure their
+names do not conflict with what are used by Git itself and other
+popular tools, and describe them in your documentation.
+
 
 advice.*::
 	These variables control various optional help messages designed to
-- 
1.9.1-443-g8f4a3d9