Pre-commit : Protecting your future self

Neil Shephard

View these slides…

ns-rse.github.io/pre-commit/

You can scan this QR code and it will take you to these slides or you can visit the site they are hosted at by going to ns-rse.github.io/pre-commit/

Introduction

• Research Software Engineer at University of Sheffield
• Background : Statistical Genetics, Medical Statistics and Data Scientist for Telematics Company
• Blog Post (2022-10-10) : pre-commit : Protecting your future self

Good afternoon, my name is Neil Shephard and I’m a Research Software Engineer at the University of Sheffield.

I’d like to thank Gavin for inviting me to come and talk to you all about pre-commit, which is an amazing tool I discovered and blogged about, you can read the original article by scanning the QR code, but to give you a little time to do that I’ll just give a very brief overview of my background and experience as I’ve only worked as a Research Software Engineer for just over a year and matured into this role after a convoluted career pathway via Statistical Genetics, Medical Statistics during which I developed a keen interest in reproducible research and started using Git.

Prior to starting in my current role I spent a few years as a Data Scientist at a telematics company where I didn’t really do much data science but did learn Python, working collaboratively with Git and good practices for software development and engineering.

Structure

• (Very) brief Git version control.
• A digression into Linting and Testing.
• Git Hooks.
• pre-commit installation.
• pre-commit configuration.
• pre-commit usage.
• pre-commit in CI/CD.

In this talk I’ll give a very brief overview of using Git for version control before making a digression into linting and testing. We’ll then look at Git Hooks because they underpin the functionality of pre-commit and I’ll then go through installing and configuring pre-commit, hopefully give a demonstration that won’t fail and then show how pre-commit can be integrated into Continuous Integration and Delivery pipelines.

Git

xkcd (1597)

https://xkcd.com/1597/

Ok, Git is pretty popular but could I have a show of hands for how many people are familiar with and use Git on a daily basis please?

Pause

Great, looks like most of the audience are familiar with Git and hopefully are a little more proficient than the XKCD protagonists.

Git Workflow

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true,'showCommitLabel': true, 'rotateCommitLabel': true}} }%%
gitGraph
    commit
    commit
    branch bug1
    checkout main
    commit
    checkout bug1
    commit
    commit
    checkout main
    branch feature1
    checkout feature1
    commit
    commit
    checkout bug1
    commit
    checkout main
    merge bug1 tag: "v0.1.1"
    checkout feature1
    commit
    commit
    checkout main
    merge feature1 tag: "v0.1.2"
    commit

A typical workflow of a version controlled directory is shown here

• Make a branch from main to add a feature and here we have two features being developed.
• Edit some files on each branch
• Staging and commit changes as you go, then when ready you.
• Push the changes to the remote origin such as GitHub or GitLab
• Make a pull request to merge these changes into the main branch.
• If you’re lucky you won’t have any merge conflicts. and once approved
• Once approved and merged another commit is made marking the inclusion of the changes and a tag can optionally be applied.

This gives us an overview of the Git development cycle and how commits fit in. We’ll move now on to linting and testing.

Linting and Testing

A digression…

• Good practice to lint code & conform to Style Guides
• Good practice to have tests in place for code.

Linting - What is all the fluff about?

When writing code and it is good practice to lint your code to ensure it conforms to the languages style guides. These are useful because if code is written in a consistent style it makes it easier for multiple people, including your future self to read and understand.

Similarly it is sensible, and some would argue essential, to write tests to ensure that your functions, methods and classes work as expected. These tests are run regularly against your code base as it is developed to ensure that changes made to the code don’t break functionality.

Often these will be run as you write your code and as part of the Continuous Integration pipelines.

A simple Python function

sample.py

import numpy as np

from pathlib import Path

def find_files(file_path: Union[str, Path], file_ext: str) -> list:
    """Recursively find files of the stated type along the given file path."""
    # We have a really long comment on this line just for demonstration purposes so that we can generate a few errors that need linting
    try:
        return list(Path(file_path).rglob(f"*{file_ext}"))
    except:
        raise

In order to explain how pre-commit works I need an example so I’ve created this very simple Python function.

You don’t need to be too familiar with Python to understand and follow along but a quick explanation is that a few libraries are imported, then the function find_files is defined, it takes two arguments a file path and a file extension and it will recursively find all files ending with the given extension along that path, and if an exception is encountered it is raised.

A Simple Test

test_sample.py

from .sample import find_files

def test_find_files():
    """Test the find_files() function"""
    py_files = find_files(file_path="./", file_ext=".py")
    assert isinstance(py_files, list)
    assert "sample.py" in py_files

I’m a big fan of tests and so in addition to writing my function I’ve written a test to make sure my find_files function works as expected.

It imports the function and uses it to look in the current directory for files with the extension .py saving the results to py_files. The type of this is checked and it should be a list and then a check is made for the presence of the file sample.py in that list is made.

Linting and Testing Tools

• black PEP8 compliance.
• flake8 PEP8 compliance.
• pylint PEP8 compliance, code smells and refactoring suggestions.
• pytest

We’ve got some sample code but it might not meet the style guides.

Style guides set out a consistent way to write and structure code and there are guides for different languages and sometimes even different styles within a language.

For Python there is the PEP8 style guide and there are a number of tools that help with linting Python code to be compliant with PEP8 such as black which mostly applies formatting, flake8 and pylint which check formatting and also look for code smells where poor design patterns have been used and make refactoring suggestions.

Then there is the pytest framework for writing and running tests which I can highly recommend along with many of its extensions, although you could easily use the standard library unittest too if you wanted to make your life more difficult, really use pytest it saves you time and effort.

Linting and Testing manually…

black sample.py
flake8 sample.py
pylint sample.py
pytest test_sample.py

We have some code then our sample.py and our test_sample.py, but what does the process of linting them manually look like and how does our code measure up?

Linting manually

black

❱ black sample.py
All done! ✨ 🍰 ✨
1 file changed.

flake8

❱ flake8 sample.py
sample.py:1:1: D100 Missing docstring in public module
sample.py:1:1: F401 'numpy as np' imported but unused
sample.py:2:1: F401 'pandas as pd' imported but unused
sample.py:7:36: F821 undefined name 'Union'
sample.py:8:80: E501 line too long (87 > 79 characters)
sample.py:9:80: E501 line too long (135 > 79 characters)
sample.py:12:5: E722 do not use bare 'except'

pylint

❱ pylint sample.py
************* Module sample
sample.py:9:0: C0301: Line too long (135/120) (line-too-long)
sample.py:1:0: C0114: Missing module docstring (missing-module-docstring)
sample.py:7:35: E0602: Undefined variable 'Union' (undefined-variable)
sample.py:12:4: W0706: The except handler raises immediately (try-except-raise)
sample.py:4:0: C0411: standard import "from pathlib import Path" should be placed before "import numpy as np" (wrong-import-order)
sample.py:1:0: W0611: Unused numpy imported as np (unused-import)
sample.py:2:0: W0611: Unused pandas imported as pd (unused-import)

-------------------------------------
Your code has been rated at -10.00/10

pytest

❱ pylint test_sample.py
================= test session starts =================
platform linux -- Python 3.7.11, pytest-7.1.1, pluggy-1.0.0
rootdir: /home/neil/work/projects/pre-commit/assets/python
plugins: hydra-core-1.2.0, regtest-1.5.0, cov-3.0.0
collected 0 items / 1 error

======================= ERRORS ========================
___________ ERROR collecting test_sample.py ___________
test_sample.py:1: in <module>
    from .sample import find_files
sample.py:7: in <module>
    def find_and_load_files(file_path: Union[str, Path], file_type: str):
E   NameError: name 'Union' is not defined
================ short test summary info ===============
ERROR test_sample.py - NameError: name 'Union' is not defined
!!!!!!!! Interrupted: 1 error during collection !!!!!!!!
=================== 1 error in 0.49s ===================

Running each of these manually is four separate commands. This takes you time to switch to a terminal, make sure your virtual environment is activated and your in the same directory as your work, then run the commands.

black finds and corrects some errors.

flake8 complains about some problems with the style of the code as does pylint and we get a very poor score of -10.

pytest won’t even run because of errors so we can’t check our code.

You then correct any errors and repeat the cycle, albeit a little quicker and all of this before you can commit your changes to git….

…then you can commit and push

Git work cycles encourages regular saving of work, by staging and committing work into Git. Periodically you should Git push to your remote repository ensure your work is backed up just in case of fires or your hard drive failing.

But the process of repeatedly linting and testing your code quickly becomes tedious and you may even forget to do so before making commits. This means there is potential for errors to creep into the code base if these steps aren’t undertaken.

What can we do to mitigate this?

Automate with pre-commit

• Uses Git Hooks to run checks automatically.
• Written in Python but hooks for most languages.
• Large number of supported hooks available to use.
• Supports : C, C++, R, Java, JavaScript, PHP, LISP, Markdown, Go, Bash, Ansible, Docker, Lua, Jupyter Notebooks and more.

This is where pre-commit comes in handy. It uses Git Hooks to run checks automatically.

It’s written in Python but beyond installing pre-commit you don’t need to know or use Python yourself to use pre-commit as there are a large number of existing pre-commit hooks that are available to be used off the shelf for a whole array of common and not so common languages.

So far I think the only thing that I use which I’ve not been able to find a hook for is checking formatting of Org-mode files.

What are Hooks?

• Actions that are run prior to or in response to a given action.

❱ ls -lha .git/hooks
drwxr-xr-x neil neil 4.0 KB Mon Oct 24 10:26:37 2022  .
drwxr-xr-x neil neil 4.0 KB Tue Jan  3 18:48:37 2023  ..
.rwxr-xr-x neil neil 478 B  Sun Aug 14 13:35:27 2022  applypatch-msg.sample
.rwxr-xr-x neil neil 896 B  Sun Aug 14 13:35:27 2022  commit-msg.sample
.rwxr-xr-x neil neil 4.6 KB Sun Aug 14 13:35:27 2022  fsmonitor-watchman.sample
.rwxr-xr-x neil neil 189 B  Sun Aug 14 13:35:27 2022  post-update.sample
.rwxr-xr-x neil neil 424 B  Sun Aug 14 13:35:27 2022  pre-applypatch.sample
.rwxr-xr-x neil neil 1.6 KB Sun Aug 14 13:35:27 2022  pre-commit.sample
.rwxr-xr-x neil neil 416 B  Sun Aug 14 13:35:27 2022  pre-merge-commit.sample
.rwxr-xr-x neil neil 1.3 KB Sun Aug 14 13:35:27 2022  pre-push.sample
.rwxr-xr-x neil neil 4.8 KB Sun Aug 14 13:35:27 2022  pre-rebase.sample
.rwxr-xr-x neil neil 544 B  Sun Aug 14 13:35:27 2022  pre-receive.sample
.rwxr-xr-x neil neil 1.5 KB Sun Aug 14 13:35:27 2022  prepare-commit-msg.sample
.rwxr-xr-x neil neil 2.7 KB Sun Aug 14 13:35:27 2022  push-to-checkout.sample
.rwxr-xr-x neil neil 3.6 KB Sun Aug 14 13:35:27 2022  update.sample

pre-commit is a hook, but what is a hook?

Well hooks are actions that are run prior to or in response to a given action that you’ve performed.

When you initialise a Git repository locally a number of sample hooks installed under the .git/hooks/ directory. If you’ve cloned a repository then these .git directory generally aren’t included so you won’t have these.

This is a directory listing and you can see there are a number of different stages at which hooks might apply, but as the name of this talk gives away, the key hook of interest here is the pre-commit hook.

Each of these files are Bash scripts and you could sit down and craft your own script to undertake all the tasks you wish to run prior to making commits.

But pre-commit saves you a bunch of time thanks to the hooks it makes available, all you need to do is configure it.

Installation of pre-commit

Python

❱ workon a_virtual_env  # Optional
❱ pip install pre-commit

Conda Environment

❱ conda activate conda_env
❱ conda install -c \
        conda-forge pre-commit

GNU/Linux

# Arch
❱ pacman -Syu python-pre-commit
# Gentoo
❱ emerge -av pre-commit
# Debian/Ubuntu
❱ sudo apt install pre-commit

OSX

❱ sudo port install pre-commit
❱ brew install pre-commit

I mentioned earlier that you didn’t really need to know or use Python which was mostly true but you do need to install pre-commit this can be done using pip the Python tool for installing Python packages from the Python Package Index and you can optionally do this within a virtual environment or Conda Environment if you use Conda to manage your virtual environments.

If you use GNU/Linux then many package managers have pre-commit available in the package repositories to install and some examples of how to install the relevant packages under Arch, Gentoo and Ubuntu are shown.

The OSX package managers macports and homebrew also includes pre-commit so you can install with either of those.

.pre-commit-config.yaml

Root of a project under Git version control.

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.3.0
    hooks:
      - id: trailing-whitespace
        types: [file, text]
      - id: end-of-file-fixer
        types: [file, text]
      - id: check-docstring-first
      - id: check-case-conflict
      - id: check-yaml
  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black
        types: [python]
        additional_dependencies: ['click==8.0.4']
        args: ["--config pyproject.toml"]
  - repo: https://github.com/pycqa/flake8.git
    rev: 5.0.4
    hooks:
      - id: flake8
        args: ["--config setup.cfg"]
        additional_dependencies: [flake8-print]
        types: [python]
  - repo: local
    hooks:
      - id: pylint
        args: ["--rcfile=.pylintrc"]
        name: Pylint
        entry: python -m pylint
        language: system
        files: \.py$
  - repo: local
    hooks:
      - id: pytest
        name: pytest
        entry: pytest --cov
        language:system

Once you’ve installed pre-commit you need to configure it.

Configuration of pre-commit is via a YAML file called .pre-commit-config.yaml and this should reside in the root of a project that is under Git version control.

The top-level defines repos: and you then enable and configure each of the pre-commit hooks you wish to use under its own - repo section.

It then has configuration to use other people’s pre-commit hooks, in this example the black, flake8 and two local hooks that run pylint and pytest.

Lets take a look at how a pre-commit hook is configured.

Hook configuration - pre-commit

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.3.0  # Use the rev you want to point at
    hooks:
      - id: trailing-whitespace
        types: [file, text]
      - id: end-of-file-fixer
        types: [file, text]
      - id: check-docstring-first
      - id: check-case-conflict
      - id: check-yaml

This is the main pre-commit hooks repository configuration, it defines the repository from which a particular version of a virtual environment is downloaded and you specify a revision of this to use.

A series of hooks are then defined, each has an id and here the trailing-whitespace and end-of-file-fixer are enabled to run on files of type text. There are then checks for docstring-first, case-conflict and finally a check-yaml hook which makes sure any YAML files are correctly formatted.

Hook configuration - Black

  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black
        types: [python]
        additional_dependencies: ['click==8.0.4']
        args: ["--config pyproject.toml"]

Next we have a configuration section for the black formatter, its limited to python files via the types option and a required dependency click is pulled in.

Finally we as users can pass additional arguments to black via the args line and here we’re telling black to explicitly look for its configuration in the pyproject.toml file which is the current recommended way of configuring your Python package if you are using setuptools/

Hook Configuration - Local

  - repo: local
    hooks:
      -id: pytest
      name: pytest
      entry: pytest --cov
      language: system

Both the pylint and pytest hooks are configured differently, the repo here is local, which means that rather than downloading a virtual environment to run the hook its going to use your existing local environment. This is because the environments that are available online do not include the packages that need to be installed to lint and test your code and so instead pre-commit uses the system where it is being run, i.e. the virtual environment you have activated.

For Python projects there are other options, for example you could include a hook to run the static type checker mypy against your code base, there is an existing hook for this, or if you weren’t using pytest you could configure unittest and its extension nose you could configure a local hook to run tests using those.

pre-commit installation

❱ git add .pre-commit-config
❱ pre-commit --version
pre-commit 2.20.0
❱ pre-commit install
pre-commit installed at .git/hooks/pre-commit
❱ pre-commit install-hooks    # Optional

Now that pre-commit is installed on your system and a configuration file has been added to your repository you can install the pre-commit hook in the repository.

You add the configuration file to the repository, check that pre-commit is available using the --version flag and then install it. This writes a bash script to .git/hook/pre-commit that runs pre-commit whenever you make a git commit, whether that is at the command line or through your IDE.

Check existing Files

❱ pre-commit run --all-files
[INFO] Initializing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Initializing environment for https://github.com/psf/black.
[INFO] Initializing environment for https://github.com/pycqa/flake8.git.
[INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
[INFO] Installing environment for https://github.com/psf/black.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
[INFO] Installing environment for https://github.com/pycqa/flake8.git
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
Check Yaml.....................................................Passed
Fix End of Files...............................................Passed
Check for case conflicts.......................................Passed
Check docstring is first.......................................Failed
Trim Trailing Whitespace.......................................Failed
- hook id: trailing-whitespace
- exit code: 1

Files were modified by this hook. Additional output:

Fixing sample.py

black..........................................................Failed
reformatted sample.py

All done! ✨ 🍰 ✨
1 file reformatted.
flake8.........................................................Failed
- hook id: flake8
- exit code: 1

sample.py:1:1: D100 Missing docstring in public module
sample.py:1:1: F401 'numpy as np' imported but unused
sample.py:2:1: F401 'pandas as pd' imported but unused
sample.py:7:36: F821 undefined name 'Union'
sample.py:8:80: E501 line too long (87 > 79 characters)
sample.py:9:80: E501 line too long (135 > 79 characters)
sample.py:12:5: E722 do not use bare 'except'

pylint.........................................................Failed
- hook id: pylint
- exit code: 1

************* Module python.sample
sample.py:9:0: C0301: Line too long (135/120) (line-too-long)
sample.py:1:0: C0114: Missing module docstring (missing-module-docstring)
sample.py:7:35: E0602: Undefined variable 'Union' (undefined-variable)
sample.py:12:4: W0706: The except handler raises immediately (try-except-raise)
sample.py:4:0: C0411: standard import "from pathlib import Path" should be placed before "import numpy as np" (wrong-import-order)
sample.py:1:0: W0611: Unused numpy imported as np (unused-import)
sample.py:2:0: W0611: Unused pandas imported as pd (unused-import)

-------------------------------------
Your code has been rated at -10.00/10

pytest.........................................................Failed
================= test session starts =================
platform linux -- Python 3.7.11, pytest-7.1.1, pluggy-1.0.0
rootdir: /home/neil/work/projects/pre-commit/assets/python
plugins: hydra-core-1.2.0, regtest-1.5.0, cov-3.0.0
collected 0 items / 1 error

======================= ERRORS ========================
___________ ERROR collecting test_sample.py ___________
test_sample.py:1: in <module>
    from .sample import find_files
sample.py:7: in <module>
    def find_and_load_files(file_path: Union[str, Path], file_type: str):
E   NameError: name 'Union' is not defined
================ short test summary info ===============
ERROR test_sample.py - NameError: name 'Union' is not defined
!!!!!!!! Interrupted: 1 error during collection !!!!!!!!
=================== 1 error in 0.49s ===================

git --ignore-rev Who’s to Blame?

Normally pre-commit only runs against the files that have been changed in a given commit and so after installing it is often a good idea to run it against all files.

The first time you run pre-commit it downloads Python virtual environments for each of the configured hooks so it can take a little while to run, but these are reused in future runs so once setup the process will be a lot quicker on subsequent runs of pre-commit.

Here we see it failed the “Trim trailing-whitespace” check and the file was modified.

And as with the manual linting and tests we see the files were modified by black, failed flake8 and pylint and because of these errors also failed pytest.

Its worth flagging up though that running black against a large code base could actually cause problems as it will reformat files in place using its opinionated style. You would then have to commit those changes and the blame would be associated with code that you only formatted rather than wrote. There are ways around this using Git’s --ignore-rev flag and I’ve written another blog post on that.

Correcting Errors

Original sample.py

import numpy as np

from pathlib import Path

def find_files(file_path: Union[str, Path], file_ext: str) -> List:
    """Recursively find files of the stated type along the given file path."""
    # Short comment
    try:
        return list(Path(file_path).rglob(f"*{file_ext}"))
    except:
        raise

pylint errors

************* Module python.sample
sample.py:9:0: C0301: Line too long (135/120) (line-too-long)
sample.py:1:0: C0114: Missing module docstring (missing-module-docstring)
sample.py:7:35: E0602: Undefined variable 'Union' (undefined-variable)
sample.py:12:4: W0706: The except handler raises immediately (try-except-raise)
sample.py:4:0: C0411: standard import "from pathlib import Path" should be placed before "import numpy as np" (wrong-import-order)
sample.py:1:0: W0611: Unused numpy imported as np (unused-import)

-------------------------------------
Your code has been rated at -10.00/10

Linted

"""Find files of a given type """
from pathlib import Path
from typing import Union


def find_files(file_path: Union[str, Path], file_type: str) -> list:
    """Recursively find files of the stated type along the given file path."""
    return list(Path(file_path).rglob(f"*{file_type}"))

Lets fix the linting errors. You can see the original code at the top and the linted code below where we’ve addressed the problems thatflake8 and pylint were reporting by removing unused libraries, importing the missing Union class, changing the returned to be a basic Python list rather than a class from the typing library.

We’ve removed the long comment line and the plain try: ... except: instead just returning the list, because we don’t need to add anything more to the error that is raised.

Add and commit changes

git add sample.py
git commit -m "Linting sample.py."
Check Yaml.....................................................Passed
Fix End of Files...............................................Passed
Check for case conflicts.......................................Passed
Check docstring is first.......................................Passed
Trim Trailing Whitespace.......................................Passed
black..........................................................Passed
flake8.........................................................Passed
pylint.........................................................Passed
pytest.........................................................Passed
[INFO] Restored changes from /home/neil/.cache/pre-commit/patch1674045267-394193.
[main 05b1568] Linting sample.py
 1 file changed, 2 insertions(+), 2 deletions(-)

Now we git add the files and git commit them and because we have pre-commit configured and installed we don’t need to run the linting or tests manually as pre-commit runs the various hooks we’ve configured it to but only against the files we are committing, in this case sample.py. There is no downloading of the environments as there was with the first manual run and as we’ve corrected the linting errors the tests pass and the commit is made.

The [INFO] line here is saying changes have been restored is because pre-commit makes a git stash and only runs the linting on the files that are included in the commit then restores that stash afterwards.

This is much quicker and efficient than having to run black, flake8, pylint and pytest against the changed files manually, there is no cognitive overhead involved in thinking about what files to run against as there may be in larger changes. You might consider running linting and tests against the whole code base but this could be problematic if there are unlinted files and if its a large code base with lots of tests it might take a long time to run. With pre-commit the linting and tests run only against the files included in the commit and so are faster.

This all streamlines the process and frees up developer time.

But one point of friction is that its contingent on people using the tools locally, what if you have a contributor who hasn’t set themselves up with pre-commit as described and they make a pull request to have their bug fix or feature included. Is there a way to apply these checks against their pull request before it is committed to the master or main branch?

Continuous Integration/Delivery (CI/CD)

• Runs hooks on GitHub/GitLab/etc. in response to specific tasks/actions.
• GitHub Actions (see also Actions Marketplace)
• GitLab Pipelines
• Jenkins

Fortunately there is because many projects use Continuous Integration.

This involves running various checks such as linting, testing on Pull Requests before merging changes into main and master. Continuous delivery extends this and builds packages for release and tests that these work so they are ready to deploy.

GitHub has Actions for performing these tasks, whilst GitLab has what it calls Pipelines

Another popular CI framework is Jenkins.

For the remainder of this talk I’m going to focus on GitHub Actions.

GitHub Actions

• Actions are hooks that run under certain conditions e.g. push to main branch or tag beginning with v.
• Useful for CI/CD.
• Defined in .github/workflows/*.yaml
• Write your own .github/workflows/pre-commit.yaml or…

• …use pre-commit.ci

GitHub Actions are hooks in that they are processes that run when certain conditions are met for example a push to the main branch, or a commit has a tag applied.

As mentioned they are useful for running Continuous Integration and Delivery and in a Git repository they are defined in YAML files that live in the .github/workflows/ directory.

You could write your own Action and save it in say pre-commit.yaml in this directory but there is an even easier service to use in the form of pre-commit.ci which is a CI extension to pre-commit.

pre-commit.ci

• Supports GitHub but more to come in the future.
• Zero configuration, just need .pre-commit-config.yaml.
• Corrects & commits some formatting issues automatically without need for developer to reformat.
• Only runs on Pull Request commits (not on individual branches)
• Automatically updates .pre-commit-config.yaml for you (e.g. new rev).
• Free for open source repositories (paid for version for private/organisation repositories).

Pre-commit.ci is a continuous integration service for the pre-commit framework.

Currently it only supports GitHub but apparently support is in development for other platforms such as GitLab and so forth.

Its really easy to use, you don’t have to provide any specific configuration (although you can if you want to and I’ll get to that shortly).

If the configured pre-commit hooks make simple formatting changes to your files pre-commit.ci will automatically fix the pull request.

Only runs on Pull Request commits, so if you’re pushing your work to your branch you don’t need to worry it won’t be churning through every push.

It will also automatically keep your .pre-commit-config.yaml up-to-date when new revisions of configured hooks become available.

Its free for open source repositories, there are paid for options for private and organisation repositories.

It really is worth using this over writing your own not just for the reasons described but it is also considerably faster because it caches the various environments that are used. If you wrote your own GitHub Action for this then on execution each runner would have to download all the hooks anew, setup and install any local environment and then run pre-commit. There is no such overhead with pre-commit.ci so if you can I would recommend using it.

Configuration (.pre-commit-config.yaml)

ci:
  autofix_prs: true
  autofix_commit_msg: '[pre-commit.ci] Fixing issues with pre-commit'
  autoupdate_schedule: weekly
  autoupdate_commit_msg: '[pre-commit.ci] pre-commit automatically updated.'
  skip: [pylint, pytest] # Optionally list ids of hooks to skip on CI

Its not required but you can if you want configure pre-commit.ci with a ci: section in your .pre-commit-config.yaml, this example shows some explicit options to automatically fix pull requests and the message to add when doing so.

The update schedule is set to run weekly and as an example the pylint and pytest hooks are set to be skipped because if you remember these are configured to run in the local environments because of the dependency needs.

pre-commit.ci Setup

• Sign-in with GitHub at https://pre-commit.ci
• Grant permission to your account.

To use pre-commit.ci just sign in with your GitHub credentials.

You can then follow the link to manage which repositories pre-commit.ci has access to on GitHub.

Manage Repos for pre-commit.ci

GitLab pre-commit

You can provide pre-commit.ci access to all of your repositories or fine grained control to only specific repositories and I would advocate going with the fine-grained control so you know what is happening where and when.

That is all you need to do. Now when you push to master or main or make pull requests pre-commit.ci will run.

If you’re using GitLab there is a thread on StackOverflow linked here that shows how to setup and configure things.

Pre-commit GitHub Action

When you make a Pull Request on your repository the GitHub Actions run and you can see at the bottom here that the pre-commit.ci job is listed. If we click on details…

Pre-commit Pass

Pass

You get an overview for each repository you have enabled pre-commit.ci for showing the success and failures of historical runs and as you see here you can add a badge to your repository to indicate success.

Pre-commit Pass

Pass

We are taken to the job and can see exactly which checks were carried out and in this example we see they all pass and because we disabled pylint from running under CI it shows as Skipped as were a few other steps but all the other checks passed. Sometimes jobs fail though…

Pre-commit Fail

Fail

Here you can see the pre-commit found trailing white spaces across a number of files and it went ahead and fixed them for us and automatically pushed them back to the branch for inclusion in the pull request and we can click through and look at that.

Summary

• ✔️ pre-commit is useful for automating repetitive tasks.
• ✔️ Helps keep git history clean (no more “linting code” commit messages).
• ✔️ Improves code quality by ensuring style guides are adhered to.
• ✔️ Automates running test suites and ensures they pass.
• ✔️ Integrates with CI/CD on GitHub and others.
• ✔️ Frees up developer time.

In this talk I’ve hopefully demonstrated how using pre-commit can help automate running repetitive tasks.

By using it you help keep your git history clean, it improves the code quality by ensuring style guides are adhered to, automates running test suites and ensures they pass , integrates into CI/CD pipelines and all of this helps free up developer time by pushing the detection of errors as far “left” or early into the development cycle as possible.

This is important because it is developer time that is often the most expensive component of a project and you don’t want people sitting around waiting for tests to fail on CI/CD pipelines when they could have been caught earlier in the development cycle….i.e. pre-commit.

Alternatives

• Megalinter.io - comparable, lots of languages, lots of tools.
• Codacy - only works with GitHub repos, not locally.
• No doubt many others I’m not aware of!

Bonus - Linting with IDE

Popular IDEs have tools to run linting automatically on file save…

• Emacs : blacken / Flycheck / Pylint & Flymake
• VSCode : Python
• PyCharm : black / Mypy / flake8
• RStudio : lintr

Many popular Integrated Development Environments support linting of code on the fly or on saving files, Emacs has blacken and flycheck modes, the later of which will run flake8.

VSCode has a Python module for linting.

PyCharm has plugins for black, mypy and flake8

RStudio has support for the lintr package (as does Emacs).

Using these tools is sensible as it can highlight quickly and early on problems with your code. Applying black automatically also takes out some mental overhead in thinking about whether you are using the correct formatting whilst writing code allowing you to focus on the problem you are trying to solve.

View these slides…

By Mara Averick

ns-rse.github.io/pre-commit/

Here’s the QR code again in case you missed it, these slides have lots of links in to the resources and tools I’ve talked about so please do take the time to check them out.

Also they’re written in RevealJS so if you view them hit ‘s’ and you can see the speaker notes I wrote and probably failed abysmally to follow today!