About Pre-Commit

pre-commit is a framework for managing pre-commit git hooks. Git hooks are custom scripts that run when you perform certain operations in a git repository.

As implied by the name, a pre-commit hook runs when you attempt to create a commit. It can inspect the changes that are about to be committed, to see if you have forgotten something, or to examine whatever you need to inspect in the code. A failure status from this hook aborts the commit. Moreover, the pre-commit framework can also be runs to run hooks at various other moments during a Git process, e.g. just before you push.

The pre-commit framework makes managing these hooks easier by storing them in a configuration file in the repository. This allows you to share the hook with colleagues working on the same repository.

The easiest way to install pre-commit is using pip:

pip install pre-commit

Refer to the pre-commit documentation for more install options and information about pre-commit.

Packamon hooks

Packamon currently offers two hooks:

To use only the Dockerfile hook, add a file .pre-commit-config.yaml to the root of your repository with the following content:

repos:
  - repo: https://scm.openanalytics.eu/git/packamon
    rev: master
    hooks:
      - id: update-dockerfile

To use both hooks:

repos:
  - repo: https://scm.openanalytics.eu/git/packamon
    rev: master
    hooks:
      - id: update-dockerfile
      - id: update-jenkinsfile

To install the hooks, run

pre-commit install

The Dockerfile hook will now run automatically whenever you create a commit that involves changes to a package DESCRIPTION or the template.Dockerfile.

To manually test-run the Dockerfile hook, you can use:

pre-commit run

Note: make sure your changes are added to the index (git add)

Alternatively, if you want run the Dockerfile hook at a different moment, for example because it takes quite long to run, you can add this hook to run just before a push. In order to do this, you can add stages to the .pre-commit-config.yaml:

repos:
  - repo: https://scm.openanalytics.eu/git/packamon
    rev: master
    hooks:
      - id: update-dockerfile
        stages: [pre-push]

By default, running pre-commit install will only install pre-commit hooks. You need to explicitly mention that you want to install pre-push hooks by running

pre-commit install --hook-type pre-commit --hook-type pre-push

or adding the line

default_install_hook_types: [pre-commit, pre-push, commit-msg]

to the .pre-commit-config.yaml.

To run the Jenkinsfile hook, you need to add --all-files:

pre-commit run --all-files

The Jenkinsfile hook does not run automatically because currently it can’t be meaningfully tied to any file in the repository. You should generally only generate it once and then make changes to it by hand; regenerating it should be a conscious, and therefore manual, decision. Future editions of packamon will feature some form of up-front customization of the Jenkinsfile through a configuration file which should make an automatic Jenkinsfile hook more useful.

References