Maintaining code is quite a challenge over the long-term. Over the lifetime of a library, many people read and edit it. Each person has a different background in coding and also a different goal in mind. These variations can lead to inconsistencies throughout the code that makes it a bit harder for the next person to understand. In CircuitPython libraries, we use tools like Pylint and Black to ensure consistency in new code.

As we've added more automated checks, we've changed to a system called pre-commit to manage the checks overall. Once installed properly, you can run pre-commit locally, before committing new code into Git. It also runs remotely on GitHub when a pull request has been proposed. pre-commit is set up to remotely run on all existing libraries. It will automatically run remotely on a new library thanks to cookiecutter.

However, it won't run locally unless you install it into your local directory. We highly recommend doing this because it will both check and fix your code locally.

One-time initial install of pre-commit

If you've never used pre-commit on your computer before, you'll need to install it globally (there is a second "install" for each repository.) The easiest way to install it is with pip.

pip install pre-commit

See the instructions from the pre-commit project for installation for alternative ways of installing pre-commit.

Per-repository installation

For every new repository, you'll need to perform an pre-commit installation. This installs the specific versions of checks that the repository specifies. From within the repository do:

pre-commit install

After running this command, pre-commit will automatically run when you do git commit.

However, if you don't do this, you can still run pre-commit manually.

Running pre-commit

pre-commit will run each check every commit for all of the modified files and either pass or fail. Most checks that fail will also modify the source file to make it pass (like removing extra spaces). Once that happens, you'll see newly modified files in git status. git add them and then try the commit again.

Manually

You can run the pre-commit checks on every file whenever you like with:

pre-commit run --all-files

More Info

For more info on pre-commit see pre-commit.com.

This guide was first published on Aug 23, 2019. It was last updated on Aug 23, 2019.

This page (Check your code with pre-commit) was last updated on Oct 23, 2021.

Text editor powered by tinymce.