Skip to content

Set up pre-commit

What is pre-commit?

pre-commit is a small software package that makes it easy to manage and run code quality checks prior to committing code.

As an OpenScPCA contributor, you will use pre-commit when you commit files while writing analysis code.

pre-commit checks code quality by defining a set of "hooks," called pre-commit hooks, that will automatically run every time you commit changes to a repository.

  • These pre-commit hooks check that the changes you are trying to commit pass the code quality standards we have set up.

  • If pre-commit finds that certain files do not pass these checks, you will need to update the files to ensure they pass before you can commit your changes.

  • You can learn more about this process in the documentation for working with Git.

How does OpenScPCA use pre-commit?

All OpenScPCA contributors should use pre-commit while making contributions with Git. Briefly, you will follow process:

We have set up some pre-commit hooks to manage basic code security and catch other common problems, such as the following:

  • Large data files that should not be committed to the repository
  • Merge conflicts that have not yet been resolved
  • Credential files and other sensitive information

Setting up pre-commit

During conda setup, you should have installed the pre-commit software into your base environment.

To turn on the pre-commit hooks for the OpenScPCA repository, you will need to run the command pre-commit install from a terminal window inside the repository. We recommend launching a terminal window in GitKraken to do this.

  1. Open a terminal window and navigate to the OpenScPCA repository.

    • Remember, if you open the terminal within GitKraken, you're automatically in the repository - no extra navigation steps needed!

  2. Type this command in the terminal prompt, and hit enter:

    pre-commit install

  3. The terminal should then return this output message showing that you successfully set up your pre-commit hooks:

    pre-commit installed at .git/hooks/pre-commit

All set! 🎉

Advanced considerations

Instructions in this section are optional.

While we use a limited set of required pre-commit hooks in this project, there are several other pre-commit hooks that you might find useful for your own development. This section describes how you can add additional pre-commit hooks.

Because all OpenScPCA contributors share the .pre-commit-config.yaml file, please do not modify it. Instead, you should make a copy of this file in the root directory of the repository named .pre-commit-local.yaml. We have configured Git to ignore this file in the repository's .gitignore file, so you can modify it as you wish without affecting other contributors.

To switch your local activation of pre-commit to use this file, you will need to re-activate pre-commit using the the following code:

# make and activate a local pre-commit configuration
cp .pre-commit-config.yaml .pre-commit-local.yaml
pre-commit install --config .pre-commit-local.yaml

You can then add your own pre-commit hooks by editing the .pre-commit-local.yaml file.

Suggested additional pre-commit hooks

Code formatting and linting

Code formatting and linting hooks can help you write error-free, consistent, and readable code. For more on the value of these tools, see this article about linters and formatters (although this article focuses on JavaScript, the same principles apply to other languages).

The OpenScPCA required pre-commit hooks do not include any code formatting or linting checks, but you may find it helpful to use these tools in your own copy of the repository.

Note that these tools will often directly modify your files if they find errors. In this case, the initial commit will fail, and you will then need to check and stage the changes that the tool made before retrying the commit.

Some formatters that we recommend are ruff-format for Python and the style-files hook from the pre-commit package for R.

You can add these hooks by adding the following code to your .pre-commit-local.yaml file in the repos: section:

  # ruff formatter for Python
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.3.3
    hooks:
      - id: ruff-format
  # code styling with the {styler} package for R
  - repo: https://github.com/lorenzwalthert/precommit
    rev: v0.4.0
    hooks:
      - id: style-files

Code linting tools are often more intrusive compared to code formatting tools. For example, they enforce not only general formatting but also particular style standards and "best" practices. This can make them more likely to find errors and inconsistencies, and therefore also more likely to require you to manually fix the errors it finds. They also might flag things that are not actually errors, but are simply not to the linter's taste.

If you would like to use a code linter, we recommend using ruff (which goes along with ruff-format shown above) for Python and the lintr package for R:

  # ruff linter for Python
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.3.3
    hooks:
      - id: ruff
  # code linting with the {lintr} package for R
  - repo: https://github.com/lorenzwalthert/precommit
    rev: v0.4.0
    hooks:
      - id: lintr

Spell checking

Spell checking is another useful class of tools that can be added as a pre-commit hook. Because biological and computational words are often not in default dictionaries, it is most helpful to use a spell checker that looks for common errors rather than one that checks every word against a dictionary.

One such tool is typos, which runs quickly to check both text and code for common mistakes. typos can be installed as a pre-commit hook with the following code added to the .pre-commit-local.yaml file:

  - repo: https://github.com/crate-ci/typos
    rev: v1.18.2
    hooks:
      - id: typos

Other pre-commit hooks

There are many other pre-commit hooks available.

You can find a fairly extensive list of them at the pre-commit "Supported hooks" page. Just note that the more hooks you add, the longer each commit to your repository will take!

Updating pre-commit hooks

If you ever need to update the versions of your pre-commit hooks, please use this command:

pre-commit autoupdate -c .pre-commit-local.yaml