2019-03-11 04:42:05 +08:00
[](https://asottile.visualstudio.com/asottile/_build/latest?definitionId=17& branchName=master)
[](https://dev.azure.com/asottile/asottile/_build/latest?definitionId=17& branchName=master)
2014-03-23 09:40:47 +08:00
2014-03-13 23:41:35 +08:00
pre-commit-hooks
2019-03-11 04:42:05 +08:00
================
2014-03-13 23:41:35 +08:00
Some out-of-the-box hooks for pre-commit.
2014-03-14 00:26:06 +08:00
See also: https://github.com/pre-commit/pre-commit
2014-06-18 21:47:14 +08:00
### Using pre-commit-hooks with pre-commit
Add this to your `.pre-commit-config.yaml`
2018-05-29 01:58:28 +08:00
- repo: https://github.com/pre-commit/pre-commit-hooks
2019-10-29 06:19:58 +08:00
rev: v2.4.0 # Use the ref you want to point at
2014-06-18 21:47:14 +08:00
hooks:
- id: trailing-whitespace
# - id: ...
### Hooks available
2020-02-03 21:10:31 +08:00
- < a name = "check-added-large-files" > `check-added-large-files`</ a > - Prevent giant files from being committed.
2015-05-10 16:00:54 +08:00
- Specify what is "too large" with `args: ['--maxkb=123']` (default=500kB).
2017-12-05 09:28:46 +08:00
- If `git-lfs` is installed, lfs files will be skipped
(requires `git-lfs>=2.2.1` )
2020-02-03 21:10:31 +08:00
- < a name = "check-ast" > `check-ast`</ a > - Simply check whether files parse as valid python.
- < a name = "check-builtin-literals" > `check-builtin-literals`</ a > - Require literal syntax when initializing empty or zero Python builtin types.
2017-11-26 08:17:47 +08:00
- Allows calling constructors with positional arguments (e.g., `list('abc')` ).
2017-12-01 02:27:16 +08:00
- Allows calling constructors from the `builtins` (`__builtin__`) namespace (`builtins.list()`).
2017-11-26 08:17:47 +08:00
- Ignore this requirement for specific builtin types with `--ignore=type1,type2,…` .
- Forbid `dict` keyword syntax with `--no-allow-dict-kwargs` .
2020-02-03 21:10:31 +08:00
- < a name = "check-byte-order-marker" > `check-byte-order-marker`</ a > - Forbid files which have a UTF-8 byte-order marker
- < a name = "check-case-conflict" > `check-case-conflict`</ a > - Check for files with names that would conflict on a
2015-05-10 16:00:54 +08:00
case-insensitive filesystem like MacOS HFS+ or Windows FAT.
2020-02-03 21:10:31 +08:00
- < a name = "check-docstring-first" > `check-docstring-first`</ a > - Checks for a common error of placing code before
2015-05-10 16:00:54 +08:00
the docstring.
2020-02-03 21:10:31 +08:00
- < a name = "check-executables-have-shebangs" > `check-executables-have-shebangs`</ a > - Checks that non-binary executables have a
2017-07-03 12:00:28 +08:00
proper shebang.
2020-02-03 21:10:31 +08:00
- < a name = "check-json" > `check-json`</ a > - Attempts to load all json files to verify syntax.
- < a name = "check-merge-conflict" > `check-merge-conflict`</ a > - Check for files that contain merge conflict strings.
- < a name = "check-symlinks" > `check-symlinks`</ a > - Checks for symlinks which do not point to anything.
- < a name = "check-toml" > `check-toml`</ a > - Attempts to load all TOML files to verify syntax.
- < a name = "check-vcs-permalinks" > `check-vcs-permalinks`</ a > - Ensures that links to vcs websites are permalinks.
- < a name = "check-xml" > `check-xml`</ a > - Attempts to load all xml files to verify syntax.
- < a name = "check-yaml" > `check-yaml`</ a > - Attempts to load all yaml files to verify syntax.
2017-10-13 06:47:20 +08:00
- `--allow-multiple-documents` - allow yaml files which use the
[multi-document syntax ](http://www.yaml.org/spec/1.2/spec.html#YAML )
2018-03-20 01:13:18 +08:00
- `--unsafe` - Instead of loading the files, simply parse them for syntax.
2018-03-20 00:28:18 +08:00
A syntax-only check enables extensions and unsafe constructs which would
otherwise be forbidden. Using this option removes all guarantees of
portability to other yaml implementations.
Implies `--allow-multiple-documents` .
2020-02-03 21:10:31 +08:00
- < a name = "debug-statements" > `debug-statements`</ a > - Check for debugger imports and py37+ `breakpoint()`
2018-05-15 00:16:37 +08:00
calls in python source.
2020-02-03 21:10:31 +08:00
- < a name = "detect-aws-credentials" > `detect-aws-credentials`</ a > - Checks for the existence of AWS secrets that you
Improve searching for configured AWS credentials
The previous approach for finding AWS credentials was pretty naive and
only covered contents of a single file (~/.aws/credentials by
default).
The AWS CLI documentation states various other ways to configure
credentials which weren't covered:
https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#credentials
Even that aren't all ways, a look into the code shows:
https://github.com/boto/botocore/blob/develop/botocore/credentials.py
This commit changes the behavior so the hook will behave in a way
that if the AWS CLI is able to obtain credentials from local files,
the hook will find them as well.
The changes in detail are:
- detect AWS session tokens and handle them like secret keys.
- always search credentials in the default AWS CLI file locations
( ~/.aws/config, ~/.aws/credentials, /etc/boto.cfg and ~/.boto)
- detect AWS credentials configured via environment variables in
AWS_SECRET_ACCESS_KEY, AWS_SECURITY_TOKEN and AWS_SESSION_TOKEN
- check additional configuration files configured via environment
variables (AWS_CREDENTIAL_FILE, AWS_SHARED_CREDENTIALS_FILE and
BOTO_CONFIG)
- print out the first four characters of each secret found in files to
be checked in, to make it easier to figure out, what the secrets
were, which were going to be checked in
- improve error handling for parsing ini-files
- improve tests
There is a major functional change introduced by this commit:
Locations the AWS CLI gets credentials from are always searched and
there is no way to disable them. --credentials-file is still there to
specify one or more additional files to search credentials in. It's
the purpose of this hook to find and check files for found
credentials, so it should work in any case. As this commit also
improves error handling for not-existing or malformed configuration
files, it should be no big deal.
Receiving credentials via the EC2 and ECS meta data services is not
covered intentionally, to not further increase the amount of changes
in this commit and as it's probably an edge case anyway to have this
hook running in such an environment.
2016-12-30 15:41:24 +08:00
have set up with the AWS CLI.
The following arguments are available:
2018-10-29 06:58:14 +08:00
- `--credentials-file CREDENTIALS_FILE` - additional AWS CLI style
2018-10-29 03:07:03 +08:00
configuration file in a non-standard location to fetch configured
credentials from. Can be repeated multiple times.
2018-10-29 03:05:42 +08:00
- `--allow-missing-credentials` - Allow hook to pass when no credentials are
detected.
2020-02-03 21:10:31 +08:00
- < a name = "detect-private-key" > `detect-private-key`</ a > - Checks for the existence of private keys.
- < a name = "double-quote-string-fixer" > `double-quote-string-fixer`</ a > - This hook replaces double quoted strings
2015-05-10 16:00:54 +08:00
with single quoted strings.
2020-02-03 21:10:31 +08:00
- < a name = "end-of-file-fixer" > `end-of-file-fixer`</ a > - Makes sure files end in a newline and only a newline.
- < a name = "fix-encoding-pragma" > `fix-encoding-pragma`</ a > - Add `# -*- coding: utf-8 -*-` to the top of python files.
2016-04-28 02:18:14 +08:00
- To remove the coding pragma pass `--remove` (useful in a python3-only codebase)
2020-02-03 21:10:31 +08:00
- < a name = "file-contents-sorter" > `file-contents-sorter`</ a > - Sort the lines in specified files (defaults to alphabetical). You must provide list of target files as input to it. Note that this hook WILL remove blank lines and does NOT respect any comments.
- < a name = "flake8" > `flake8`</ a > - Run flake8 on your python files.
- < a name = "forbid-new-submodules" > `forbid-new-submodules`</ a > - Prevent addition of new git submodules.
- < a name = "mixed-line-ending" > `mixed-line-ending`</ a > - Replaces or checks mixed line ending.
2017-06-14 03:38:14 +08:00
- `--fix={auto,crlf,lf,no}`
- `auto` - Replaces automatically the most frequent line ending. This is the default argument.
- `crlf` , `lf` - Forces to replace line ending by respectively CRLF and LF.
2020-01-15 05:44:59 +08:00
- This option isn't compatible with git setup check-in LF check-out CRLF as git smudge this later than the hook is invoked.
2017-06-14 03:38:14 +08:00
- `no` - Checks if there is any mixed line ending without modifying any file.
2020-02-03 21:10:31 +08:00
- < a name = "name-tests-test" > `name-tests-test`</ a > - Assert that files in tests/ end in `_test.py` .
2015-05-10 16:00:54 +08:00
- Use `args: ['--django']` to match `test*.py` instead.
2020-02-03 21:10:31 +08:00
- < a name = "no-commit-to-branch" > `no-commit-to-branch`</ a > - Protect specific branches from direct checkins.
2019-04-20 20:46:49 +08:00
- Use `args: [--branch, staging, --branch, master]` to set the branch.
2019-04-20 21:06:59 +08:00
`master` is the default if no branch argument is set.
2018-06-10 02:16:14 +08:00
- `-b` / `--branch` may be specified multiple times to protect multiple
branches.
2019-04-20 20:46:49 +08:00
- `-p` / `--pattern` can be used to protect branches that match a supplied regex
2019-04-20 20:52:59 +08:00
(e.g. `--pattern, release/.*` ). May be specified multiple times.
2020-02-03 21:10:31 +08:00
- < a name = "pretty-format-json" > `pretty-format-json`</ a > - Checks that all your JSON files are pretty. "Pretty"
2016-12-08 02:44:07 +08:00
here means that keys are sorted and indented. You can configure this with
the following commandline options:
2016-08-23 05:23:23 +08:00
- `--autofix` - automatically format json files
2016-12-08 02:44:07 +08:00
- `--indent ...` - Control the indentation (either a number for a number of spaces or a string of whitespace). Defaults to 4 spaces.
2019-10-29 10:14:32 +08:00
- `--no-ensure-ascii` preserve unicode characters instead of converting to escape sequences
2016-08-23 05:23:23 +08:00
- `--no-sort-keys` - when autofixing, retain the original key ordering (instead of sorting the keys)
2016-12-08 02:44:07 +08:00
- `--top-keys comma,separated,keys` - Keys to keep at the top of mappings.
2020-02-03 21:10:31 +08:00
- < a name = "requirements-txt-fixer" > `requirements-txt-fixer`</ a > - Sorts entries in requirements.txt and removes incorrect entry for `pkg-resources==0.0.0`
- < a name = "sort-simple-yaml" > `sort-simple-yaml`</ a > - Sorts simple YAML files which consist only of top-level
2019-10-07 23:33:23 +08:00
keys, preserving comments and blocks.
Note that `sort-simple-yaml` by default matches no `files` as it enforces a
very specific format. You must opt in to this by setting `files` , for
example:
```yaml
- id: sort-simple-yaml
files: ^config/simple/
```
2020-02-03 21:10:31 +08:00
- < a name = "trailing-whitespace" > `trailing-whitespace`</ a > - Trims trailing whitespace.
2018-10-13 09:10:02 +08:00
- To preserve Markdown [hard linebreaks ](https://github.github.com/gfm/#hard-line-break )
use `args: [--markdown-linebreak-ext=md]` (or other extensions used
by your markdownfiles). If for some reason you want to treat all files
as markdown, use `--markdown-linebreak-ext=*` .
2019-10-25 23:15:48 +08:00
- By default, this hook trims all whitespace from the ends of lines.
To specify a custom set of characters to trim instead, use `args: [--chars,"<chars to trim>"]` .
2014-06-18 21:47:14 +08:00
2018-10-12 08:19:35 +08:00
### Deprecated / replaced hooks
- `autopep8-wrapper` : instead use
[mirrors-autopep8 ](https://github.com/pre-commit/mirrors-autopep8 )
- `pyflakes` : instead use `flake8`
2014-06-18 21:47:14 +08:00
### As a standalone package
If you'd like to use these hooks, they're also available as a standalone
package.
Simply `pip install pre-commit-hooks`
