Python has become the world’s most popular programming language because of its elegant syntax. But this alone doesn’t ensure a clean, readable code.
The Python community had evolved to create standards to make codebases created by different programmers look like the same person had developed them. Later on, packages such as Black were created to auto-format the codebase. Yet the problem is only half solved. Git pre-commit hooks complete the rest.
What are pre-commit hooks?
Pre-commit hooks are helpful git scripts that run automatically before a git commit. If a pre-commit hook fails, the git push will be aborted, and depending on how you set it up, your CI software may also fail or not trigger.
Note, before setting up pre-commit hooks, ensure you have the following.
- You need to have git version >= v.0.99 (you can check this with git — version)
- You need to install Python (as it’s the language used for git hooks.)
Installing pre-commit hooks
You can install the pre-commit package easily with single pip command. But to attach it to your project, you need one more file.
.pre-commit-config.yaml file holds all the configurations your project requires. This is where you tell the pre-commit what actions it needs to perform before every commit and override its defaults if needed.
The following command will generate an example configuration file.
Here is an example configuration that sorts your requirements.txt file every time before you commit changes. Place this at the root of your project directory or edit the one you generated using the previous step.
We’ve installed the pre-commit package and configured how it should work. Now, we can enable pre-commit hooks to this repository using the following command.
Awesome! Let’s add the following requirements.txt file to your project and make a git commit. See pre-commit hooks in action.
Before committing, git will download instructions from the repository and use the requirement fixer module to clean the file. The resulting file will look like the one below.
Black with pre-commit hooks to automatically format your Python code.
Black is a popular package that helps Python developers maintain a clean codebase.
Most code editors have keyboard shortcuts that you can bind to Black to clean your code on the go. For example, VSCode on Linux uses Ctrl + Shift + I. Upon first using this shortcut, VScode prompts which code formatter to use. You can select black (or autopep8) to enable it.
But, if pressing the shortcut keys bothers you, you can put it on the pre-commit hooks. The below snippet does the trick.
Note that this has more settings than the previous ones. Here, in addition to using black, we are overriding its defaults. We used the args option to configure black to set a maximum line length of 120 characters.
Let’s see how Git hooks work with Black, for example, given in Black’s documentation. Create a Python file (the name doesn’t matter as long as it’s a .py file) with the following content.
The above file, after committing, will look like the following. This is more standard compared to the previous one. It’s easy to read, and code reviewers would love to see it this way.
Configure pre-commit hooks to look for local repositories
Sometimes, you want to run pre-commit hooks from your locally installed packages. Let’s try to use a locally installed isort package to sort your Python imports.
You can install
isort using the following command.
Now edit the
.pre-commit-config.yaml file and insert the below snippet.
To see this in action, create a Python file with multiple imports. Here’s a sample.
After committing, the same file will look like the one below.
Use Black, Isort, and Autoflake pre-commit hooks for a cleaner Python codebase.
Here’s the pre-commit hook template I always use in almost all of my projects. We already discussed two hooks in this list, Black and Isort. Autoflake is another useful hook that removes unused variables, whitespace, and imports.
Since this template uses local packages, make sure you have them installed. You can run the following command to install them all at once and set up pre-commit to your git repository.
Git pre-commit is revolutionary in many ways. They are primarily used in CI/CD pipelines to trigger activities. One of the other major use cases is to use them for automatic code formatting.
A well-formatted code is easy to read and digest for a different person as it follows standard guidelines shared among the community. Python has a standard called PEP8, and tools like Black, isort, and Autoflake help developers automate this standardization process.
Yet, it may be a hassle to remember this and use the tool every time manually. Pre-commit hooks quickly put it to its code review checklist and run it automatically before every commit.
This post discussed using pre-commit hooks from remote repositories and locally installed packages.
I hope you’d have enjoyed it.
Not a Medium member yet? Please use this link to become a member because I earn a commission for referring at no extra cost for you.