pre-commit.md

About pre-commit

pre-commit hooks are a subset of git hooks. git hooks are scripts that run automatically every time a particular event occurs in a git repository. A “pre-commit hook” runs before a commit takes place.

---

What problems pre-commit solve?

pre-commit hooks are very useful in identifying simple issues before submission to code review - mostly at the time of commit. These hooks are run on every commit to automatically point out issues in the code, such as code linting, trailing whitespace in the file, running test cases and type checking, etc Pointing out these issues before code review allows a code reviewer to focus more on the application logic & architecture rather than petty issues.

So you can fix these issues before committing the changes and sending them for code review.

---

pre-commit hooks used at PM

• Following are the pre-commit hooks used in PM, and a few projects may have additional hooks.

  • Basic pre-commit-hooks: Some out-of-the-box hooks for pre-commit.

    • trailing-whitespace
    • end-of-file-fixer
    • requirements-txt-fixer
    • detect-private-key
    • detect-aws-credentials
    • check-ast
    • check-merge-conflict
    • check-toml
    • check-yaml
    • check-added-large-files
    • no-commit-to-branch

  • autoflake: Removes unused imports and unused variables.

  • Black: PEP 8 compliant opinionated Python code formatter. It reformats entire files in place.

  • black_nbconvert: Black formatter for ipynb files or Jupyter notebooks.

  • docker-compose-check: Verifies that docker-compose files are valid.

  • flake8: Python code linter that wraps PyFlakes, pycodestyle and Ned Batchelder's McCabe script.

    • flake8-copyright: Additional dependency for flake8 that checks for copyright notices in all python files.

  • Interrogate: Checks code base for missing docstrings.

  • isort: Sort Python imports.

  • Mypy: mypy type checks for Python with additional dependencies.

  • pytest-check: Running pytest locally.

---

Installation & usage

1. Install pre-commit:

• Using pip :

  $ pip install pre-commit

• Using homebrew

  $ brew install pre-commit

• Using conda (via conda-forge):

2. Install pre-commit hooks:

• The pre-commit hook configurations are defined in .pre-commit-config.yaml file.

• To install the hooks, run:

  $ pre-commit install

3. Update hook version:

• To update hook version, periodically run:

  $ pre-commit autoupdate

4. Running pre-commit hooks on files:

• To run hooks on all the files, run:

  $ pre-commit run --all-files

• To run hooks on specifc file (single file), run:

  $ pre-commit run --files /path_of_the_file

• To skip pre-commit hook on commit, run:

  $ git commit -m "change_type: your message" --no-verify

• Skipping a hook:

  • To skip a specific hook (or set of hook) temporarily, use SKIP environment variable with hook id when doing a commit.

  • The SKIP environment variable is a comma separated list of hook ids. This allows you to skip a single hook instead of --no-verify ing the entire commit.

  • Syntax:

    $ SKIP=hook_id,hook_id_2 git commit -m "commit message"

  • Example:

    $ SKIP=flake8 git commit -m "doc: update readme"

• mypy hook needs the typing dependencies installed, which mirrors requirement-dev.txt, for example:

  - repo: https://github.com/pre-commit/mirrors-mypy
      rev: 'v0.910'
      hooks:
        - id: mypy
          # verbose: true
          # args: [--ignore-missing-imports]
          additional_dependencies:
            # - boto3-stubs[s3]>=1.18
            # - mypy-boto3-s3>=1.18
            # - types-orjson>=0.1.1
            - types-pytz>=2021.1.0
            # - types-requests>=2.25.0

• flake8 hook needs an additional dependency (flake8-copyright) that checks for copyright notices in all python files.

• Other hooks that need the dependencies should be configured in .pre-commit-config.yaml config file.

• Checkout pre-commit doc to know more about CLI options.