patchcontrib/hooks: avoid requiring root access in usage instructions

Comments in hooks/post-receive-email suggest:

 For example, on debian the hook is stored in
 /usr/share/git-core/contrib/hooks/post-receive-email:

  chmod a+x post-receive-email
  cd /path/to/your/repository.git
  ln -sf /usr/share/git-core/contrib/hooks/post-receive-email hooks/post-receive

Doing that means changing permissions on a file provided by a package, which is problematic in a number of ways: the permissions would be likely to change back in later upgrades, and changing them requires root access. Copying the script into each repo that uses it is not much better, since each copy would be maintained separately and not benefit from bugfixes in the master copy.

Better to ship the hook with executable permission and remove the chmod line so enabling the hook becomes a one-step process: just symlink it into place.

Likewise for the pre-auto-gc-battery hook.

Reported-by: Olivier Berger <olivier.berger@it-sudparis.eu>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
From <http://bugs.debian.org/687391>.

Thoughts? Jonathan

 contrib/hooks/post-receive-email  | 1 -
 contrib/hooks/pre-auto-gc-battery | 1 -
 2 files changed, 2 deletions(-)
 mode change 100644 => 100755 contrib/hooks/pre-auto-gc-battery

Jonathan Nieder <jrnieder@gmail.com> writes:

We already encourage casting-in-stone a particular version of the sample hook when a new repository is created by copying them from the template directory. This prevents from surprising users when an updated version of Git changes the behaviour of these samples. Even if you think bugs in older ones may be corrected in newer ones, silently updating the hook the user chose to use by inspecting one particular version is not something we would want to do lightly. A buggy devil you know is better than a devil that suddenly changes its behaviour depending on when your sysadmin updates the version of Git without your knowing.

I personally think the same applies to these contrib/ hooks, and I would think it is simpler and more consistent to correct the instruction in these files to tell users to copy them.

Adding +x bits to these files is a good idea but that is orthogonal to copying vs symlinking, I think.

Junio C Hamano wrote:

For context, the sample hooks you are talking about are the *.sample files from the templates/ directory. Except for post-update.sample, most are not very useful out of the box, and they are very much intended as examples to start people's thinking, as opposed to something one-size-fits-all.

By contrast, the post-receive-email script from contrib is a complete program with a well-defined behavior and configuration that have stayed consistent while the details of its implementation improved. It can be used by symlinking into place, but maybe a better set of instructions would say

	# This script takes no arguments and expects the same input format
	# as git's post-receive hook, so if this script is at
	# /usr/share/git-core/contrib/hooks/post-receive-email (as it is
	# on Debian and Fedora), you can do
	#
	#  cd /path/to/your/repository.git
	#  echo '#!/bin/sh' >hooks/post-receive
	#  echo 'exec /usr/share/git-core/contrib/hooks/post-receive-email' \
	#	>>hooks/post-receive
	#  chmod +x hooks/post-receive

That would make it more obvious what I can do next if my post-receive input should be passed both to post-receive-email and some other tool (perhaps in a pipeline using "tee").

Hmm? Jonathan