Stop committing wrongly formatted code and start using pre-commit checks.
Introduction
How many times have you seen a commit message like 'test' or 'modif' or 'reran notebook'?
Commit messages can be very useful and their format can help get the relevant information in a simple look. This is what conventional commits is trying to achieve: standardize the commit format to be able to navigate through commits easily and understand what code update they were associated to. But how could we make sure all commits followed this format?
File formatting can also be quite challenging when more than one person works on a GitHub repository. How could we make sure that all the files committed to a repository have the same format? Or that you do have the extra empty line at the end of your file that some system require to successfully run?
This is where standardization makes our life easier, especially when enforced before the commits: black formatting for python, getting rid of trailing whitespaces, etc.
Long story short, all the formatting issues that you might had to deal with or that created useless commits could be avoided by using pre-commit checks.
Without further due, let's see how we can implement these concepts to an actual GitHub repository (if you need more context on conventional commits feel free to skip to the appendix and come back here after).
All of the code for this tutorial can be found here
Get started with pre-commit checks
Step 1: Install pre-commit
To install pre-commit, simply run
brew install pre-commit
This will install pre-commit on your machine.
Step 2: Add pre-commit checks to your repo
To be able to add pre-commit checks that make sure your files and commit messages are correctly formatted, you simply need to add 2 files at the root of your repo:
- .pre-commit-config.yaml: defines the checks you want to run
- .commitlintrc.yaml: defines the npm package you use for pre commits.
# .commitlintrc.yaml
extends:
- "@open-turo/commitlint-config-conventional"
# .pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
rev: v8.0.0
hooks:
- id: commitlint
stages: [commit-msg]
additional_dependencies: ["@open-turo/commitlint-config-conventional"]
Once you added those files, you can try adding a commit, the pre commit checks defined will make sure that:
- yaml files are correctly formatted
- files have an extra empty line at the end (this is considered best practice as some systems fail when this condition is not met)
- get rid of trailing whitespaces
- make sure that the commits follow the conventional commits format.
To see if this worked, try to commit those files to your repo with some commit message like
git commit -m 'feat: enabled pre-commit checks'
Woohoo! You now know how to add pre commit checks to your own repository to make sure your file format are consistent and your commit messages too!
Apendix
Appendix 1: A word on Conventional Commits
With conventional commits, the commit message should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
For example (from commit conventional docs):
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
Appendix 2: adding a python code formatter to pre-commit checks
Additional content: if you want to add a python code formatter, like black, you can append to the end of .pre-commit-config.yaml
- repo: https://github.com/psf/black
rev: 21.12b0
hooks:
- id: black
About me
Hey! 👋 I'm Armand Sauzay (armandsauzay). You can find, follow or contact me on:
Top comments (0)