Re: [PATCH] hook: introduce the report hook for git-receive-pack(1)

[Patrick Steinhardt <ps@pks.im>]

On Wed, Aug 19, 2026 at 03:13:50PM +0200, Karthik Nayak wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > On Tue, Aug 18, 2026 at 09:55:55AM +0200, Karthik Nayak wrote:
> >> When running 'git-receive-pack(1)', there is currently no way for the
> >> server to intercept and modify the status report before it is sent back
> >> to the client. This is useful for servers with custom logic that need
> >> to transform or gate the report based on the outcome of external logic
> >> post reference updates.
> >>
> >> Introduce a new 'report' hook which receives the pkt-line encoded
> >> status report on stdin and whose stdout replaces the report sent to the
> >> client. A non-zero exit status causes `receive-pack` to die and the
> >> client to treat the push as failed.
> >
> > I think it would have been useful to add context why none of the
> > preexisting hooks work for us:
> >
> >   - The pre-receive hook runs too early, as we haven't updated
> >     references at that point yet and we need to have the full view of
> >     all resulting updates (both objects and references).
> >
> >   - The update hook is too inefficient as it runs once per reference,
> >     and we cannot trivially determine the last update.
> >
> >   - The reference-transaction hook cannot be used by us because we care
> >     about the phase where it was committed already. And while the hook
> >     fires in that phase, it does not allow the caller to modify the
> >     result in any capacity.
> >
> >   - The post-receive and post-update hooks cannot be used as they run
> >     too late, at the point where we have already reported success to the
> >     client.
> >
> 
> Yeah, this is worthwhile mentioning, I already have made the commit
> message a lot more descriptive, so it does become bloated. I think it is
> justified though, since more information is always more useful than less.

Well. Until it isn't anymore :) Just look at the walls of text that AI
is prone to generate, where one is essentially drowning in information.
And it's the worst kind of information, too: plausibly looking but
inherently dubious.

Anyway, I digress. I think in this context it's good to have the context
indeed, and I trust your information more than the one generated by AI.

> >> diff --git a/Documentation/githooks.adoc b/Documentation/githooks.adoc
> >> index ed045940d1..7e6643ad89 100644
> >> --- a/Documentation/githooks.adoc
> >> +++ b/Documentation/githooks.adoc
> >> @@ -527,6 +527,29 @@ The exit status of the hook is ignored for any state except for the
> >> To reject individual ref updates, rewrite the corresponding
> >> +`ok` lines to `ng` lines in the output report (with an explanatory
> >> +error string) and exit zero; standard error can accompany this to
> >> +provide a human-readable explanation. A non-zero exit status causes
> >> +`receive-pack` to die.
> >
> > We should probably document that we expect the hook to never return
> > non-zero, even if it rejects reference updates, and that doing so
> > indicates a bug. This is mostly because git-receive-pack(1) shouldn't
> > ever just die on the client without giving it a proper status.
> >
> 
> Yeah, this is a part I was thinking about but wasn't sure if it should
> be added in because, we could also do an implementation where we simply
> ignore the exit code of the hook.

There could be cases where just making the whole operation explode is
the only remaining option. So I don't think it's necessarily bad to have
it as the nuclear option.

Patrick