Introduction ¶ Git hook scripts are useful for identifying simple issues before submission to code review. We run our hooks on every commit to automatically point out issues in code such as missing semicolons, trailing whitespace, and debug statements. By pointing these issues out before code review, this allows a code reviewer to focus on the architecture of a change while not wasting time with trivial style nitpicks. As we created more libraries and projects we recognized that sharing our pre-commit hooks across projects is painful. We copied and pasted unwieldy bash scripts from project to project and had to manually change the hooks to work for different project structures. We believe that you should always use the best industry standard linters. Some of the best linters are written in languages that you do not use in your project or have installed on your machine. For example scss-lint is a linter for SCSS written in Ruby. If you’re writing a project in node you should be able to use scss-lint as a pre-commit hook without adding a Gemfile to your project or understanding how to get scss-lint installed. We built pre-commit to solve our hook issues. It is a multi-language package manager for pre-commit hooks. You specify a list of hooks you want and pre-commit manages the installation and execution of any hook written in any language before every commit. pre-commit is specifically designed to not require root access. If one of your developers doesn’t have node installed but modifies a JavaScript file, pre-commit automatically handles downloading and building node to run eslint without root.

Installation ¶ Before you can run hooks, you need to have the pre-commit package manager installed. Using pip: pip install pre-commit Non-administrative installation: to upgrade: run again, to uninstall: pass uninstall to python

to python does not work on platforms without symlink support (windows) curl https://pre-commit.com/install-local.py | python - In a python project, add the following to your requirements.txt (or requirements-dev.txt): pre-commit Using homebrew: brew install pre-commit Using conda (via conda-forge): conda install -c conda-forge pre-commit Quick start ¶ 1. Install pre-commit ¶ follow the install instructions above

pre-commit --version should show you what version you're using $ pre-commit --version pre-commit 2.7.1 2. Add a pre-commit configuration ¶ create a file named .pre-commit-config.yaml

you can generate a very basic configuration using pre-commit sample-config

the full set of options for the configuration are listed below

this example uses a formatter for python code, however pre-commit works for any programming language

works for any programming language other supported hooks are available repos : - repo : https://github.com/pre-commit/pre-commit-hooks rev : v2.3.0 hooks : - id : check-yaml - id : end-of-file-fixer - id : trailing-whitespace - repo : https://github.com/psf/black rev : 19.3b0 hooks : - id : black 3. Install the git hook scripts ¶ run pre-commit install to set up the git hook scripts $ pre-commit install pre-commit installed at .git/hooks/pre-commit now pre-commit will run automatically on git commit ! 4. (optional) Run against all the files ¶ it's usually a good idea to run the hooks against all of the files when adding new hooks (usually pre-commit will only run on the changed files during git hooks) $ pre-commit run --all-files [INFO] Initializing environment for https://github.com/pre-commit/pre-commit-hooks. [INFO] Initializing environment for https://github.com/psf/black. [INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks. [INFO] Once installed this environment will be reused. [INFO] This may take a few minutes... [INFO] Installing environment for https://github.com/psf/black. [INFO] Once installed this environment will be reused. [INFO] This may take a few minutes... Check Yaml............................................................... Passed Fix End of Files......................................................... Passed Trim Trailing Whitespace................................................. Failed - hook id: trailing-whitespace - exit code: 1 Files were modified by this hook. Additional output: Fixing sample.py black.................................................................... Passed oops! looks like I had some trailing whitespace

consider running that in CI too

Usage ¶ Run pre-commit install to install pre-commit into your git hooks. pre-commit will now run on every commit. Every time you clone a project using pre-commit running pre-commit install should always be the first thing you do. If you want to manually run all pre-commit hooks on a repository, run pre-commit run --all-files . To run individual hooks use pre-commit run <hook_id> . The first time pre-commit runs on a file it will automatically download, install, and run the hook. Note that running a hook for the first time may be slow. For example: If the machine does not have node installed, pre-commit will download and build a copy of node. $ pre-commit install pre-commit installed at /home/asottile/workspace/pytest/.git/hooks/pre-commit $ git commit -m "Add super awesome feature" black.................................................................... Passed blacken-docs.........................................(no files to check) Skipped Trim Trailing Whitespace................................................. Passed Fix End of Files......................................................... Passed Check Yaml...........................................(no files to check) Skipped Debug Statements (Python)................................................ Passed Flake8................................................................... Passed Reorder python imports................................................... Passed pyupgrade................................................................ Passed rst ``code`` is two backticks........................(no files to check) Skipped rst..................................................(no files to check) Skipped changelog filenames..................................(no files to check) Skipped [master 146c6c2c] Add super awesome feature 1 file changed, 1 insertion(+)