How to add git hooks for your python projects using the pre-commit framework
By: Mathanraj Sharma
Tags: Hooks, Git, Github, Python, Workflow

What is Git Hooks?

As I mentioned at the top there are certain actions (tasks) we need to perform when an event happens in the development workflow, which is known as hooks.

Git hooks are scripts that run automatically every time a particular event occurs in a git repository.

For example, running black formatting and flake8 linting before each commit. Literally, we can add hooks at various stages of the git events.

pre-commit:- run certain hook before commit, if fails abort the commit

pre-merge-commit:- run certain hook before the merge, if fails abort the merge

pre-push:- run certain hook before pushing to the remote repo, if fails abort push

post-commit:- hook to be run immediately after a successful commit

post-checkout:- hook to be run immediately after checkout from one branch

post-merge:- hook to be run immediately after a successful merge

etc

When we do git init it adds the most commonly used git hooks into .git/hooks/ , we can write our own hooks using the most commonly used scripting languages. But today we going to see about a framework designed to ease this process.

What is pre-commit framework?

It is a framework for managing and maintaining multi-language git hooks. You may have a question, why do we need a framework for hooks.

As we create more libraries and projects we might find that sharing our pre-commit hooks across projects is painful. We have to copy and paste unwieldy bash scripts from project to project and had to manually change the hooks to work for different project structures. And also sometimes some good linters or other testing tools we need, might be not written in the same language we using for our project.

Pre-commit is a multi-language package manager for pre-commit hooks. We can simply specify the list of hooks we want and pre-commit manages the installation and execution of any hook written in any language without any root permission.

How to use the pre-commit framework with python projects?

Install pre-commit framework

pip install pre-commit or conda install -c conda-forge pre-commit

Add .pre-commit-config.yaml to your project’s root folder. In this example, I am going to show how to add black formatting and flake8 linting for each commit and push.

let us break down each component here,

default_stages:- a configuration-wide default for the stages property of hooks. This will only override individual hooks that do not set stages.

default_language_version:- default language version that should be used if language_version is not set for individual hooks.

repos:- list of repository mappings

repo:- the repository URL to git clone, the code for the hook will be taken from here.

rev:- which version of repo needs to be used (tag)

hooks:- A list of hook mappings, hook mapping lets the user select which hook needs to be used from the repo and allows customizations.

id: hook name from the repo.

args: command-line arguments need to be passed for that hook.

exclude:- regex for file/folder names to be excluded for that hook.

types:- file types to be considered for that hook.

There are many more components, to customize the hooks.

2. After adding the config file, run the below command to install hooks

pre-commit install --hook-type pre-commit hook-type pre-post

this will install the hooks that should be run before commits and push.

3. Modify any of the files in your project and try to commit them

Failed pre-commit (PC: Author)

here my hooks have failed due to some code reformatting and lint errors. Note, if any of the hooks failed then the commit will be aborted. Fix the issue and re-commit.

Successful pre-commit (PC: Author)

This will be the same if you have configured any pre-push hooks.

Successful pre-push (PC: Author)

You can find the complete source code here, https://github.com/Mathanraj-Sharma/python_boilerplate

In conclusion, git hooks is simply any script that we wish to trigger during the occurrence of a git event. It helps use to automate the repetitive workload to maintain the consistency of the code being written. It may not seem effective at the early stage, but as the projects grows and more contributors comes in we can feel the benefits of git hooks.

Happy Coding!!!