Feature idea: Git hook for pre-checkout

Feature idea: Git hook for pre-checkout

[Mike Weltevrede]

Good morning,

I had an idea for a feature in Git. I am not sure if this is the
correct channel, but I could not find anything else. If not, could you
please let me know the best way to submit this?

Below, I will explain the idea and then the problem that this would solve.

<The idea>
I have a project that is using Git hooks. Besides pre-commit and
pre-push, I would like to use pre-checkout (rather than the already
available post-checkout). However, it seems like an active choice not
to have pre-checkout given the existing hooks, so I am curious as to
the reason behind this.

<The problem>
I want to do branch name validation when someone does git checkout -b.
If the branch name does not meet the requirements, the user should not
be allowed to checkout to it. As such, the post-checkout hook does not
fully meet my needs. It helps with doing the branch name validation,
but if it fails, the user is still on the feature branch. As such, if
they are ignorant about the error message, this does not stop them. I
am currently combining post-checkout and pre-push but would prefer
pre-checkout because this would prevent the user from doing work on
this feature branch and having to move their work.


I am looking forward to your thoughts. Thank you for your consideration.


Met vriendelijke groet / Kind regards,

Mike Weltevrede

Re: Feature idea: Git hook for pre-checkout

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 4151 bytes --]

On 2025-01-29 at 10:49:15, Mike Weltevrede wrote:
> Good morning,
> 
> I had an idea for a feature in Git. I am not sure if this is the
> correct channel, but I could not find anything else. If not, could you
> please let me know the best way to submit this?

This is the appropriate place to make feature requests.

> Below, I will explain the idea and then the problem that this would solve.
> 
> <The idea>
> I have a project that is using Git hooks. Besides pre-commit and
> pre-push, I would like to use pre-checkout (rather than the already
> available post-checkout). However, it seems like an active choice not
> to have pre-checkout given the existing hooks, so I am curious as to
> the reason behind this.
> 
> <The problem>
> I want to do branch name validation when someone does git checkout -b.
> If the branch name does not meet the requirements, the user should not
> be allowed to checkout to it. As such, the post-checkout hook does not
> fully meet my needs. It helps with doing the branch name validation,
> but if it fails, the user is still on the feature branch. As such, if
> they are ignorant about the error message, this does not stop them. I
> am currently combining post-checkout and pre-push but would prefer
> pre-checkout because this would prevent the user from doing work on
> this feature branch and having to move their work.

I don't think this is likely to be adopted.  We intentionally don't
place a lot of restrictions on local actions, since we assume that a
single user owns the repository and works on it, and they may make a
wide variety of local changes that are not pushed elsewhere.

In addition, this change wouldn't really be very effective, since there
are many ways to bypass it (such as `git branch -m` or `git
update-ref`).  All of those ways also make it very easy to rename a
branch as well, which one might well do for non-policy reasons (for
instance, if one made a typo) and thus these approaches are assumed to
be familiar to the reasonably capable user.  It's also possible to use
one name locally and push to another, such as with
`git push origin my-feature:refs/features/foo`.

It also sounds like you're trying to implement a policy decision on the
local system, which is the wrong place, as the Git FAQ outlines[0]:

  How do I use hooks to prevent users from making certain changes?

    The only safe place to make these changes is on the remote repository
    (i.e., the Git server), usually in the `pre-receive` hook or in a
    continuous integration (CI) system.  These are the locations in which
    policy can be enforced effectively.

    It's common to try to use `pre-commit` hooks (or, for commit messages,
    `commit-msg` hooks) to check these things, which is great if you're
    working as a solo developer and want the tooling to help you.
    However, using hooks on a developer machine is not effective as a
    policy control because a user can bypass these hooks with
    `--no-verify` without being noticed (among various other ways). Git
    assumes that the user is in control of their local repositories and
    doesn't try to prevent this or tattle on the user.

    In addition, some advanced users find `pre-commit` hooks to be an
    impediment to workflows that use temporary commits to stage work in
    progress or that create fixup commits, so it's better to push these
    kinds of checks to the server anyway.

While the FAQ mentions `pre-commit` hooks, all of this applies to other
hooks as well.  The difference between the `pre-commit` hook and your
proposed `pre-checkout` hook is that the former is generally useful for
users outside of a restricted policy environment (e.g., for local
development only), whereas the `pre-checkout` hook doesn't appear to be.

Of course, others may have different views, and it's possible that
Junio might accept a patch to add such a hook if someone sent one.  I'm
happy to defer to his judgement in this case.

[0] https://git-scm.com/docs/gitfaq#restrict-with-hooks
-- 
brian m. carlson (they/them or he/him)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]

Re: Feature idea: Git hook for pre-checkout

[Konstantin Khomoutov]

On Thu, Jan 30, 2025 at 02:18:06AM +0000, brian m. carlson wrote:

[...]
> It's also possible to use one name locally and push to another, such as with
> `git push origin my-feature:refs/features/foo`.

I would add that I, for one, have a habit of working on a detached HEAD and
then pushing the results with

  git push HEAD:refs/heads/whatever

and only creating a local branch when I think I'm going to abandon the current
work for too long (otherwise I just inspect the output of `git reflog HEAD`
to find the place where I left off and then check it out back).

I don't think it's a widely adopted approach to work with Git, so mentioning
it more for the purpose of widening the OP's view of the subject matter.

[...]

Re: Feature idea: Git hook for pre-checkout

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> On 2025-01-29 at 10:49:15, Mike Weltevrede wrote:
>> Good morning,
>> 
>> I had an idea for a feature in Git. I am not sure if this is the
>> correct channel, but I could not find anything else. If not, could you
>> please let me know the best way to submit this?
>
> This is the appropriate place to make feature requests.

Yes, indeed.

> I don't think this is likely to be adopted.  We intentionally don't
> place a lot of restrictions on local actions, ...
> In addition, this change wouldn't really be very effective, ...
> `git push origin my-feature:refs/features/foo`.
> It also sounds like you're trying to implement a policy decision on the
> local system, which is the wrong place, as the Git FAQ outlines[0]:

Thanks for raising all good points.

Even though I am negative on adding a hook that does not satisify
any of the "5 valid reasons" [*], this one squarely satisifies (1).
But I fully agree with you that it is ineffective as a policy
enforcement mechanism, and a local hook should not be used as such.

Having said that, giving reminders locally and early to help users
avoid making mistakes that will be pointed out at the remote at
reception time via their pre-receive hook, only when the user does
"git push", can still be a good friction reducer.

So I am not opposed to an idea to have a mechanism that reminds the
users of project-specific naming convention of branches and files
(think: cross platform projects that have participants from case
insensitive filesystems) when they create such a thing anew locally,
especially the project would have a rejection mechanism when their
participants try to push their changes that adds such a thing.

Here, however, again I agree with you that a pre-checkout hook will
not be an effective mechanism to give that reminder.  The mechanism
must sit at the ref API layer in order to vet all ways of creating
(or renaming) a ref in order for to be effectively restrict branch
names.  For pathnames, the mechanism must sit at the cache API layer
to tell add_to_index() what names are problematic.

Thanks.


[Reference]

*1* There may be slightly updated versions of this in the archive, but
https://lore.kernel.org/git/7vbq7ibxhh.fsf@gitster.siamese.dyndns.org/
is one of them.

Re: Feature idea: Git hook for pre-checkout

[Mike Weltevrede]

Hi all,

Thanks for your swift and elaborate response. I think that those are a
very clear explanation and it makes sense to me to take a look into
the alternatives you propose.


Kind regards,

Mike Weltevrede

On Thu, 30 Jan 2025 at 18:25, Junio C Hamano <gitster@pobox.com> wrote:
>
> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>
> > On 2025-01-29 at 10:49:15, Mike Weltevrede wrote:
> >> Good morning,
> >>
> >> I had an idea for a feature in Git. I am not sure if this is the
> >> correct channel, but I could not find anything else. If not, could you
> >> please let me know the best way to submit this?
> >
> > This is the appropriate place to make feature requests.
>
> Yes, indeed.
>
> > I don't think this is likely to be adopted.  We intentionally don't
> > place a lot of restrictions on local actions, ...
> > In addition, this change wouldn't really be very effective, ...
> > `git push origin my-feature:refs/features/foo`.
> > It also sounds like you're trying to implement a policy decision on the
> > local system, which is the wrong place, as the Git FAQ outlines[0]:
>
> Thanks for raising all good points.
>
> Even though I am negative on adding a hook that does not satisify
> any of the "5 valid reasons" [*], this one squarely satisifies (1).
> But I fully agree with you that it is ineffective as a policy
> enforcement mechanism, and a local hook should not be used as such.
>
> Having said that, giving reminders locally and early to help users
> avoid making mistakes that will be pointed out at the remote at
> reception time via their pre-receive hook, only when the user does
> "git push", can still be a good friction reducer.
>
> So I am not opposed to an idea to have a mechanism that reminds the
> users of project-specific naming convention of branches and files
> (think: cross platform projects that have participants from case
> insensitive filesystems) when they create such a thing anew locally,
> especially the project would have a rejection mechanism when their
> participants try to push their changes that adds such a thing.
>
> Here, however, again I agree with you that a pre-checkout hook will
> not be an effective mechanism to give that reminder.  The mechanism
> must sit at the ref API layer in order to vet all ways of creating
> (or renaming) a ref in order for to be effectively restrict branch
> names.  For pathnames, the mechanism must sit at the cache API layer
> to tell add_to_index() what names are problematic.
>
> Thanks.
>
>
> [Reference]
>
> *1* There may be slightly updated versions of this in the archive, but
> https://lore.kernel.org/git/7vbq7ibxhh.fsf@gitster.siamese.dyndns.org/
> is one of them.