Pre-Commit Guide ​

Open Library uses pre-commit hooks to enforce formatting and code quality standards. All contributors must have pre-commit installed locally — it catches issues before you push and saves everyone time and frustration.

Installing pre-commit ​

Install pre-commit using uv, a fast Python package manager that handles Python versions automatically — no manual Python setup needed:

# Install uv: https://docs.astral.sh/uv/getting-started/installation/
uv tool install pre-commit --with pre-commit-uv
pre-commit install

The --with pre-commit-uv flag adds a plugin that patches pre-commit to use uv for installing Python-based hooks, which is much faster than the default behavior.

To upgrade pre-commit later:

uv tool upgrade pre-commit

To remove pre-commit, run pre-commit uninstall.

How It Works ​

Once installed, pre-commit runs automatically before every git commit. If an issue is found, there are two possible outcomes:

1. The check initially fails and your staged changes are not committed, but pre-commit auto-fixes the problem. You'll see a new unstaged git change like this:

Add the auto-fixed change to staging and commit again. The check should now pass.

1. The check fails and your staged changes are not committed. You'll see an error message like this:

Fix the problem locally using the error message and/or guidance from the issue's lead, then re-commit.

To manually run pre-commit against all files (e.g., before pushing), run pre-commit run --all-files.

The GitHub CI Server ​

The CI server also runs pre-commit on every push. If you don't have pre-commit installed locally, your PR will fail checks and you'll need to fix issues after the fact — which means more waiting and more pushes. Install it locally to catch problems before they reach CI.

When a CI check fails, one of two things may happen:

1. The pre-commit bot pushes a new commit that auto-fixes the issue:

Pull in the bot's changes with git pull origin HEAD to avoid conflicts with future pushes.

1. The check simply fails and requires manual intervention:

Click "Details" to see what caused the failure, fix it locally, and push again. Reach out to the issue's lead if you're unsure how to proceed.

Generating POT Files ​

If your commit involves adding, removing or altering text that will be visible to the user and is properly internationalized, an update of the translation template file will be automatically bundled in with your changes via pre-commit.

What this means ​

• Your code will "fail" a test called Generate POT, give you the error message Files were modified by this hook, and add messages.pot changes to your git unstaged changes.
• All you need to do to "pass" the test is add the messages.pot file to staging and redo your commit; the Generate POT test should now pass, and your changes will be immediately available to translators once your branch is merged.

If you're not running pre-commit locally:

• The CI will push a new commit to your remote branch with the necessary messages.pot updates.
• Run git pull origin HEAD before making further changes to avoid conflicts.