Search code examples
gitgithooksgit-push

When exactly in the push process does a `pre-push` hook actually run?

The docs for Git hooks state that pre-push runs "after the remote refs have been updated". My naïve reading of this is the target ref (i.e. the branch, typically) on the remote will already have been updated to refer to the pushed commit by the time the hook executes - loosely, that the local repo's branch and the upstream one will "match". However, this cannot be the case:

  • The docs go on to say that the hook executes "before any objects have been transferred" - which would make it impossible for the local and upstream branches to match.
  • Documentation at the time the hook was introduced states, more directly, ""git push" will stop without doing anything if the new "pre-push" hook exists and exits with a failure.".
  • If pre-push operated how I'm interpreting it, it would be useless - a failure of the hook would not actually prevent or stop anything undesired.

What does it mean for a "remote ref to be updated", and how does that differ from "successfully completing a git push"? What is the technical series of steps in executing a git push, and where in them does a pre-push hook execute?

Solution

  • I think "remote ref" refers to the local reference representing the remote.

    In other words, it first changes refs/heads/yourremotehead in your local repository without changing anything in the remote repository, then running the hook and finally pushing/changing the remote repository/transferring the objects.

    This also matches the actual docs on hooks (your link refers to the book) which says:

    For instance, if the command git push origin master:foreign were run the hook would receive a line like the following:

    refs/heads/master 67890 refs/heads/foreign 12345

    And this is the ref that would be updated before the hook is run.

    When considering this, the contradicting statements you mentioned are no longer contradicting.

    You might also want to take a look at this issue of the book whhich is about the introduction of the term "remote references" which seems to be about exactly the same confusion.