templates: clarify SHA1 arg in prepare-commit-msg

From: mataha <[email protected]>

'prepare-commit-msg' hook sample description doesn't mention the third argument (a commit object name) nor when is it actually passed to that hook by git-commit (if the source is a commit; see builtin/commit.c#L777, sequencer.c#L1219). Seeing that it's documented in githooks(5), there should be no reason not to include that in the sample hook as well.

---
Mention the third argument in 'prepare-commit-msg' hook sample

'prepare-commit-msg' hook sample doesn't mention what the third argument is for nor when is it actually passed; I feel like it should be, for the sake of convenience (this doesn't mean that a user shouldn't refer to a more detailed description in the manual, of course).

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1265%2Fmataha%2Fdoc%2Fprepare-commit-msg-args-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1265/mataha/doc/prepare-commit-msg-args-v1
Pull-Request: https://github.com/git/git/pull/1265

 templates/hooks--prepare-commit-msg.sample | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

index 318afe3fd86..bc06d0701a8 100755
@@ -3,9 +3,9 @@
 # An example hook script to prepare the commit log message.
 # Called by "git commit" with the name of the file that has the
 # commit message, followed by the description of the commit
-# message's source.  The hook's purpose is to edit the commit
-# message file.  If the hook fails with a non-zero status,
-# the commit is aborted.
+# message's source and the commit object name (if the source was
+# a commit).  The hook's purpose is to edit the commit message file.
+# If the hook fails with a non-zero status, the commit is aborted.
 #
 # To enable this hook, rename this file to "prepare-commit-msg".
 

base-commit: 277cf0bc36094f6dc4297d8c9cef79df045b735d

gitgitgadget

Welcome to the development community.

The name here must match the name you sign the patch off as, i.e. this line should read

From: Mateusz 'mataha' Kazimierczuk <[email protected]>

There should be a mention of the commit that added the hook, namely, 8089c85b (git-commit: add a prepare-commit-msg hook, 2008-02-05). The log message for this patch should also observe that this third argument, which is given only when the source is 'commit', was not mentioned in the sample hook added by the original commit.

Interestingly, its log message reads:

...
Its purpose is to modify the commit message in-place.

It takes one to three parameters. The first is the name of the file that the commit log message. The second is the source of the commit message, and can be: "message" (if a -m or -F option was given); "template" (if a -t option was given or the configuration option commit.template is set); "merge" (if the commit is a merge or a .git/MERGE_MSG file exists); "squash" (if a .git/SQUASH_MSG file exists); or "commit", followed by a commit SHA1 as the third parameter (if a -c, -C or --amend option was given).
...

So it wasn't a mistake that the sample did not mention it. I think the reason why the original, and today's version, does not mention it is because no sample code in the file actually uses it.

I am not yet convinced that it is a good idea to only add mention to the third one if we are not showing how it is used to this file, especially given that in the documentation we _do_ cover these arguments fully.

Thanks.