Git

Git Hooks

You can checkout the .git/hooks directory in your git repo to see which hooks are available. This gives some sample options for hooks.

Pre-commit

In the .git/hooks/pre-commit file you can specify a script that will run when you try and commit something.

It is common to use the pre-commit framework to organise your pre-commits. In this way, the .git/hooks/pre-commit points to a pre-commit-config.yaml.

In this yaml file, you can use pre-defined pre-commits from different repos.

Example of pre-commit in other repos

  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
    - id: black

Some other hooks to consider could be: pylint, isort, mirrors-prettier …

The https://github.com/pre-commit/pre-commit-hooks repo also has a lot of options for pre-commits you can run. You can choose them based on the id tag.

You can also use pre-commits specified only in your repository:

Example using local repo hook

- repo: local
    hooks:
    - id: pytest-check
        name: pytest-check
        # you can specify your own script here
        # if the script returns 0, then the hook passes
        entry: ./run_tests_hook.sh
        language: system

Other Hooks

You can also run the other hook types using the pre-commit module.

Install hook configs

default_install_hook_types: [pre-commit, post-commit]

With this in the .pre-commit-config.yaml, when you run pre-commit install, it will install scripts for both pre-commit and post-commit in this case.

To make a hook run in a particular stage, set stages: [post-commit] to the stage or stages you want it to run in.

You can also specify a default for all hooks specified with default_stages: [commit].

Run a particular hook stage with pre-commit run --hook-stage post-commit

Hooks in another repo

It is possible to call hooks located in another repo.

First, in the repo you want the hook to be stored in, you will create a .pre-commit-hooks.yaml file:

Example .pre-commit-hooks.yaml file

- id: commit-message-checker
  name: commit-message-checker
  entry: hooks/commit-msg
  language: script
  always_run: true
  args: [.git/COMMIT_EDITMSG]

This particular example will call a script located at hooks/commit-msg. In this script you can insert the functionality you want your hook to run.

To use the hook from another repo, do something like this in you .pre-commit-config.yaml:

Using a hook from another repo

repos:
  - repo: <URL_to_repo>
    rev: v1.0.0
    hooks:
      # this should match the id in .pre-commit-hooks.yaml
      - id: commit-message-checker

Commit Messages

Different people like to have different formats for commit messaging.

One of the common ones is Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0/

Conventional commit requires a format as such:

Example commit format

<type>[optional scope]: <description>

Some types:

fix: patches a bug in the code base
feat: introduces a new feature to the code base
chore: updating dependancies
refactor: restructure of code, no functional change
style: code styling, e.g. black formatter changes
docs: updates to documentation e.g. READMEs
ci: changes to CI
test: adding/correcting tests

Example commit message

docs(git.rst): Added commit messages section