An introduction to pre-commit

We will take a look about the tool pre-commit, how to use it, and why you will like it!

November 8, 2022 November 12, 2022 4 minutes

What is pre-commit #

Pre-commit is a framework that allows you to manage Git hooks in a really easy way. It provides out-of-the-box a lot of useful hooks, such as trailing whitespace, check added large files or mixed line ending with the possibility to change the line ending with the wanted one, like this your code stay clean.

You will be able to set up the perfect pre-commit config file that will fit with your project and prevent a lot of unwanted cases or issues.

Let’s take a look at this awesome framework together!

Installation #

First of all, you need to have python installed on your machine if you’re using Windows, regarding macOS and Linux, using homebrew would be the best option.

Using pip:

pip install pre-commit

Using homebrew:

brew install pre-commit

And that’s it! Well done! OK, let’s configure it on your project.

Configuration #

You have two different ways to set up your pre-commit config file.

By hand #

Creating a file named .pre-commit-config.yaml at the root of your project, where the directory .git is located.

Inside you can add the following sample setup:

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
    -   id: check-yaml
    -   id: check-added-large-files

Lazy style #

And I know you are lazy, you are right to save some time to be able to do something else (🍺)… Anyway… Run the following command in your favorite terminal at the root of your project:

pre-commit sample-config > .pre-commit-config.yaml

That it! Your sample config is ready!

Open the file we just created and let’s take a look at the configuration.

How to configure hooks #

The configuration file is in YAML format, if you are not familiar with it, I invite you to watch some tutorials.

Pre-commit works using repositories, this is where the hooks are hosted. That’s why we declare a first level “repos”.

Repo #

You need to declare a repository. In the example, it is declared like this:

-   repo: https://github.com/pre-commit/pre-commit-hooks

It is basically the repository’s URL.

Revision tag #

The revision tag is really important, it allows you to flag your hooks in a desired version and be sure the hooks won’t be updated without any intervention from you.

Hooks #

This is where you start to do shopping 🛍️.

Hooks accept multiple parameters but the most common ones will be id and args.

ID refers to the hook itself in the repository, it’s like a name.
We will use “mixed-line-ending” for this tutorial as an example.
This hook is designed to prevent mixing different lines ending, such as Linux and Windows ones.
Maybe you are working in a team that used different OS, using this hook, you ensure your code will always keep the same line ending. Pretty cool, right? 😎
Args allows configuring the hook. In our case, we want to always have Linux’s line ending. To do that, your configuration will look like this:

- id: mixed-line-ending  
args: ["--fix=lf"]

And that’s it! If someone tries to commit a Windows or macOS line ending, the hook will convert it to Linux one. Such a relieve for a developer! 🙌

Install the hooks #

To install the hooks in your .git directory and make the magic happen, run the following command:

pre-commit install

And… that’s it! Pre-commit is set up and all the hooks you configured will be triggered every time you want to commit.

Tips: Maybe you just installed pre-commit on an existing repository and you want to check hooks against all your files. Run the following command to do it:

pre-commit run --all-files

You can do this every time you had a new hook to be sure your files are conform to the rules you want.

Where to find hooks? #

The pre-commit website is really well done and you can find all hooks listed here.

At the moment I’m writing these lines, there are 598 hooks listed!

Conclusion #

You discover a very useful tool that you will want to add in all of your projects, I’m sure of it. It is not only for fun but it helps to resolve issues before they can be committed.

You know how to compose your pre-commit config file and add hooks that will fit your needs.

Thank you for reading me. If you enjoyed this article and consider offering me a ☕, I will be very grateful, and it will help me write new articles.