Git Hooks

Discussion

• What use cases can benefit from Git Hooks?

  

  Some Git commands and their associated hooks. Source: Bréhin 2017.

  The figure illustrates local add/commit followed by a push to the remote repository. Also shown are the relevant hooks. Each hook is given a specific name. Hooks are invoked by naming convention before or after specific events.

  The pre-commit hook is called when the commit procedure begins. This hook can format the code against the project's styling guide, run linting or execute unit tests. By checking for missing semicolons, trailing whitespace, and debug statements code reviews can focus on more important issues. Hooks prepare-commit-msg and commit-msg can be used to format/validate the commit message.

  After a successful commit, the hook post-commit could be used to send notifications. More commonly, when collaboration is via a remote repository, notifications are sent from the post-receive hook that's triggered after all references are updated. This hook can also deploy the latest changes to production. The update hook that runs once per branch can be used to enforce access control, that is, only authorized users can push to a branch.

• What are client-side and server-side hooks?

  

  A summary of hooks in Git v2.36.0. Source: Adapted from Git SCM 2022a.

  Client-side hooks run on developer machines whereas server-side hooks run on the server that hosts the repository. Committing, merging, rebasing, applying patches, and checkout are common Git operations that developers do on their development machines. Any of these commands can trigger their relevant client-side hooks. Server-side hooks are triggered by the git-receive-pack command, which is a result of developers pushing changes to the remote repository on a cloud-hosted Git server.

  Developers have full control of client-side hooks. Developers can choose to disable all client-side hooks if they wish. If a project's best practices need to be strictly enforced, server-side hooks are the way to do it.

  Some Git repository providers impose restrictions on the use of server-side hooks on their cloud-based servers. For example, GitHub's free tier doesn't allow developers to define server-side hooks though GitHub Enterprise Server supports them. However, there are alternatives to achieve server-side automation such as webhooks, GitHub Apps/Actions, GitLab CI/CD, GitLab push rules, etc.

• What are pre- and post- Git Hooks?

  Client-side and server-side hooks can be either pre- and post- hooks. The pre- hooks can be used to validate stuff before allowing the requested operation. For example, pre-commit hook executes at the start of a commit workflow. If the commit is deemed invalid for any reason, the hook can return a non-zero value. This terminates the commit operation. By returning zero, the hook states that the commit operation can continue, including the execution of other relevant hooks.

  The post- hooks execute after the requested operation is done. Such a hook's return value doesn't matter since the operation is already complete. For example, post-commit executes after a successful commit. These hooks are typically used to send emails or other notifications. They may also be used to trigger CI/CD pipelines. For example, post-receive could be used to deploy the updated code to production.

• What options help skip the execution of hooks?

  It's possible to skip some hooks if their associated commands are called with certain options. Hooks pre-commit, pre-merge-commit, prepare-commit-msg, and commit-msg can be skipped if commit and merge commands are invoked with --no-verify option.

  The hook post-checkout can be skipped if clone and worktree add commands are called with --no-checkout option. However, this hook is always called for checkout and switch commands.

• What essentials should a developer know to use Git Hooks?

  By default, hooks are stored in .git/hooks within the project's repository. Git populates this folder with sample scripts that developers can use as a starting point. However, the file suffix .sample must be removed and scripts must be made executable. Developers can rewrite the scripts in their preferred language. Accordingly, the shebang (#! first line in script) must be updated with the correct path to the language.

  If these sample scripts are deleted by mistake, we can retrieve them from Git templates folder. This may be /usr/local/git-core/templates/hooks (Linux) or C:\Program Files\Git\mingw64\share\git-core\templates\hooks (Windows). In fact, this copying from templates folder to the project's .git/ folder is what happens when we run git init.

  While hooks are triggered in response to specific events, we can also manually trigger the execution of a hook. The command for this is git hook run <hook-name> <hook-args>. For example, we could trigger one hook from another hook. This command is a low-level internal helper command.

  Beginners can start by reading the official documentation on Git Hooks and Chapter 14 of Loeliger's book on Git.

• What does it take to create and maintain reusable Git Hooks?

  It's a good practice to commit hooks as part of the repository so that all developers reuse and execute the same hooks. However, it's not permitted to store them within a .git/hooks folder within the repository. One approach is store them in another folder, say hooks, and then create a soft link from .git/hooks to hooks folder after cloning the repository. Another approach is to configure the path to the hooks with the command git config core.hooksPath <path>.

  To reuse across projects, hooks can be in a separate repository and cloned locally. Configure the hooks path globally to that folder: git config --global core.hooksPath <path>. This configuration variable has been available since Git version 2.9.0.

  There's also a framework named pre-commit to manage pre-commit hooks. This framework includes dozens of tested pre-commit hooks written in Python that developers can reuse in their own projects. These include syntax checking (check-json, check-yaml), fixing problems (fix-byte-order-marker, trailing-whitespace), protecting secrets (detect-private-key, detect-aws-credentials), enforcing policies (no-commit-to-branch, forbid-new-submodules), and more.

  The githooks.com lists many useful hooks and related tools that developers can use.

• How do I configure my project environment to use Git Hooks?

  No special configuration is needed other than updating .git/hooks folder or configuring core.hooksPath variable. However, many developer tools attempt to simplify this further.

  In Maven, a plugin can setup the hooks path. In Gradle, we can have a dependent build script to do this setup. In Node.js, Husky project allows us to wire up all the hooks in the package.json file. In PHP, hooks can be set up in composer.json file via the post-install-cmd configuration.

  In different languages, frameworks are available to manage hooks: pre-commit (Python), Overcommit (Ruby), Lefthook (Ruby or Node.js).

• What are some criticisms of Git Hooks?

  Hooks change Git's default behaviour. If a hook does something unusual, it may confuse developers new to the project. Moreover, hooks can be buggy and make things counterproductive. For this reason, some recommend using Git aliases and invoking scripts directly rather than relying on hooks.

  Git doesn't provide any easy mechanism to share hooks among developers or from one repository to another. No doubt this is more secure but at the expense of convenience and reusability. Hooks problem with installation, maintainability, and reusability is to some extent solved by frameworks such as pre-commit.

  Hooks are powerful. Developers may be tempted to run unit tests before each commit. This can slow things quite a bit and discourage developers from committing often. This can lead to data loss.

  Server-side hooks are not universally enabled by cloud-hosted Git repository service providers.

Milestones

2005

Linus Torvalds creates Git as a replacement to BitKeeper that's a distributed version control system. Even in Git v1.0.0 (December), hooks are included as a feature.

Mar
2007

Hook post-receive is introduced to replace post-update. The latter is expected to be deprecated from v1.6.0. The hook post-receive is more useful since it has access to both old and new references; post-update knows only the new references.

Sep
2007

Git 1.5.4 is released. In this release, git merge command calls the post-merge hook following a successful merge.

Feb
2008

Git 1.6.0 is released. This release ships sample hook scripts with the suffix .sample since on some filesystems it's not sufficient to ship them as non-executables. In Windows, all scripts are executable by default. Developers can rename the scripts if they wish to enable the hooks.

Dec
2008

Git 1.6.1 is released. In this release, git rebase command when used without the --no-verify option calls the pre-rebase hook. This hook can be used to prevent the rebasing of a branch.

May
2009

Git 1.6.3 is released. In this release, git clone command when used without the --no-checkout option calls the post-checkout hook. This hook is normally called after an update to the worktree, such as with the git checkout command.

Dec
2014

A critical vulnerability is discovered pertaining to Git hooks. Usually it's not possible to create a top-level folder named .git in a repository. However, in case-sensitive filesystems it's possible to create a folder named .GIT, .Git, etc. In Windows, which is case-insensitive, such a folder overwrites the default .git folder. By including malicious hooks, a hacker could execute arbitrary code on the client's machine. This threat is greatest for developers using third party or untrusted repositories. This vulnerability is patched within a week.

Apr
2015

Git 2.4.0 is released. This release adds a new server-side hook named push-to-checkout. By default, pushes to checked out branch would fail. With this hook, we can customize the behaviour by merging with or overwriting server-side changes.

Apr
2016

GitHub Enterprise Server 2.6 is released. This includes the pre-receive server-side hook that can be used to enforce push policies and optimize workflows. However, GitHub has included server-side hooks since 2013, it's first hook tasked with warning users when a repository is renamed.

Jun
2016

Git 2.9.0 is released. The hooks directory can now be configured via the core.hooksPath configuration variable.

Nov
2019

Git 2.24.0 is released. This release adds a new hook named pre-merge-commit. This hook is called after a successful merge but before obtaining the commit message. It can be bypassed with --no-verify option to the merge command.

Feb
2022

GitHub improving performance of the pre-receive hook. Source: Nieto and Gummerer 2022.

On GitHub, it's noticed that pushes to repositories can take as long as 880ms on average. The implementation is in Ruby. A lot of time is spent loading Ruby dependencies. By rewriting the hook as a Go service, average processing time is brought down to 10ms. This improvement also becomes part of GitHub Enterprise Server 3.4.

References

1. AK DevCraft. 2021. "Git pre-hook: Setup pre-commit hook for Gradle project example." Dev.to, September 17. Updated 2021-12-17. Accessed 2022-05-06.
2. Atlassian. 2022. "Git Hooks." Tutorial, Atlassian. Accessed 2022-05-06.
3. Brown, Zack. 2018. "A Git Origin Story." Linux Journal, July 27. Accessed 2022-05-06.
4. Bréhin, Maxime. 2017. "Addicted to Hooks." Blog, Delicious Insights, April 14. Updated 2022-05-05. Accessed 2022-05-06.
5. Florence, Ryan. 2010. "Deploying Websites With a Tiny Git Hook." July 27. Accessed 2022-05-06.
6. Git. 2005. "History for git/run-command.c." v1.0.0, Git, on GitHub, December 8. Accessed 2022-05-06.
7. Git. 2010a. "GIT v1.5.4 Release Notes." Git, on GitHub, September 7. Accessed 2022-05-06.
8. Git. 2010b. "GIT v1.6.0 Release Notes." Git, on GitHub, September 7. Accessed 2022-05-06.
9. Git. 2012. "GIT v1.6.1 Release Notes." Git, on GitHub, October 16. Accessed 2022-05-06.
10. Git. 2019a. "GIT v1.6.3 Release Notes." Git, on GitHub, December 3. Accessed 2022-05-06.
11. Git. 2019b. "Git 2.24 Release Notes." Git, on GitHub, October 31. Accessed 2022-05-06.
12. Git. 2019c. "Git 2.9 Release Notes." Git, on GitHub, December 3. Accessed 2022-05-06.
13. Git. 2022. "Tags." Git, on GitHub. Accessed 2022-05-06.
14. Git SCM. 2022a. "githooks - Hooks used by Git." Documentation, Git SCM, v2.36.0, April 18. Accessed 2022-05-06.
15. Git SCM. 2022b. "gitrepository-layout - Git Repository Layout." Documentation, Git SCM, v2.36.0, April 18. Accessed 2022-05-06.
16. Git SCM. 2022c. "git - the stupid content tracker." Documentation, Git SCM, v2.36.0, April 18. Accessed 2022-05-06.
17. Git SCM. 2022d. "git-hook - Run git hooks." Documentation, Git SCM, v2.36.0, April 18. Accessed 2022-05-06.
18. Git SCM. 2022e. "git-init - Create an empty Git repository or reinitialize an existing one." Documentation, Git SCM, v2.36.0, April 18. Accessed 2022-05-06.
19. GitHub. 2017. "Release notes for the 2.6 series." GitHub Enterprise 2.6.20, April 18. Accessed 2022-05-06.
20. GitHub. 2022. "GitHub Enterprise Server releases." Documentation, Enterprise Server 3.4, GitHub. Accessed 2022-05-06.
21. GitLab. 2022. "Server hooks." Documentation, GitLab, February 14. Accessed 2022-05-06.
22. Haggerty, Michael. 2015. "Git 2.4 — atomic pushes, push to deploy, and more." Blog, GitHub, April 30. Accessed 2022-05-06.
23. Hettiarachchi, Charith. 2020. "Git pre-commits hooks and Continous Integration / Continous Deployment." On Medium, February 22. Accessed 2022-05-06.
24. Leimonis, Konstantinos. 2019. "How To Ease Your Team’s Development Workflow With Git Hooks." Smashing Magazine, December 2. Accessed 2022-05-06.
25. Loeliger, Jon. 2009. "Version Control with Git." First Edition, O'Reilly. Accessed 2022-05-06.
26. Mphego, Mpho. 2019. "Why You Need To Stop Using Git-Hooks." Blog, October 3. Accessed 2022-05-06.
27. Nieto, Carlos Martín and Thomas Gummerer. 2022. "Improving Git push times through faster server side hooks." Blog, GitHub, April 21. Accessed 2022-05-06.
28. Pettersen, Tim. 2014. "Securing your Git server against CVE-2014-9390." Blog, Atlassian, December 20. Accessed 2022-05-06.
29. Straub, Ben, and Scott Chacon. 2014a. "8.3 Customizing Git - Git Hooks." Second Edition, Apress. Accessed 2022-05-06.
30. Straub, Ben, and Scott Chacon. 2014b. "8.4 Customizing Git - An Example Git-Enforced Policy." Second Edition, Apress. Accessed 2022-05-06.
31. de Rivas, Fernando Moya. 2022. "Enforce Your Team’s Code-style With Git Hooks." Better Programming, on Medium, March 9. Accessed 2022-05-06.
32. pre-commit. 2022a. "Homepage." pre-commit. Accessed 2022-05-06.
33. pre-commit. 2022b. "pre-commit-hooks." pre-commit, on GitHub, May 3. Accessed 2022-05-06.
34. shabunc. 2010. "Putting Git hooks into a repository." StackOverflow, August 11. Updated 2021-12-29. Accessed 2022-05-06.

Further Reading

1. Git SCM. 2022a. "githooks - Hooks used by Git." Documentation, Git SCM, v2.36.0, April 18. Accessed 2022-05-06.
2. Atlassian. 2022. "Git Hooks." Tutorial, Atlassian. Accessed 2022-05-06.
3. Tran, Tony and Justin Ellingwood. 2014. "How To Use Git Hooks To Automate Development and Deployment Tasks." Tutorial, Digital Ocean, August 12. Updated 2022-03-10. Accessed 2022-05-06.
4. Leimonis, Konstantinos. 2019. "How To Ease Your Team’s Development Workflow With Git Hooks." Smashing Magazine, December 2. Accessed 2022-05-06.
5. Prajapati, Ameet. 2020. "Understanding Git Hooks." Codeburst, on Medium, May 16. Accessed 2022-05-06.

Article Stats

Author-wise Stats for Article Edits

Author

No. of Edits

No. of Chats

DevCoins

arvindpdmn

6

0

1537

DevCoins due to articles, chats, their likes and article hits are included.

Cite As