Re: post-checkout hook aborts rebase

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

Chris Torek <chris.torek@gmail.com> writes:

> This might be intended as a feature, but if so, the documentation
> needs a tweak: the githooks docs say in part
>
>     This hook cannot affect the outcome of git checkout.
>
> If "outcome" includes exit status -- to me, it does -- either the docs
> are wrong or the code is wrong.

I suspected that this was a case of adding the hook that just runs
without affecting the exit code and then somebody later changed the
behaviour (either deliberately or by mistake) and forgot to update
the documentation.  But it seems that ever since the hook support
was introduced at 1abbe475 (post-checkout hook, tests, and docs,
2007-09-26), the command was made to exit with the same status from
the hook.

So I agree that depending on reader's view on "the outcome", this is
documented incorrectly (if the exit code is part of "the outcome")
or just fine (otherwise).  Apparently, the author of the patch and
the reviewers back then thought the latter.

I still suspect that the checkout run, merely as an implementation
detail of rebase (or any other git subcommand), should not trigger
any hook, but before any such code change, at least let's update the
documentation to clarify what we mean by "the outcome".

Hopefully something like the below may be a good starting point?

 Documentation/githooks.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 31b601e4bc..cf95d6d02b 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -193,7 +193,9 @@ worktree.  The hook is given three parameters: the ref of the previous HEAD,
 the ref of the new HEAD (which may or may not have changed), and a flag
 indicating whether the checkout was a branch checkout (changing branches,
 flag=1) or a file checkout (retrieving a file from the index, flag=0).
-This hook cannot affect the outcome of `git switch` or `git checkout`.
+This hook cannot affect the outcome of `git switch` or `git checkout`,
+other than that the hook's exit status becomes the exit status of
+these two commands.
 
 It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is
 used. The first parameter given to the hook is the null-ref, the second the