README.md 8.8 KB
Newer Older
1
2
[![Build Status](https://asottile.visualstudio.com/asottile/_apis/build/status/pre-commit.pre-commit-hooks?branchName=master)](https://asottile.visualstudio.com/asottile/_build/latest?definitionId=17&branchName=master)
[![Azure DevOps coverage](https://img.shields.io/azure-devops/coverage/asottile/asottile/17/master.svg)](https://dev.azure.com/asottile/asottile/_build/latest?definitionId=17&branchName=master)
Anthony Sottile's avatar
Anthony Sottile 已提交
3
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pre-commit/pre-commit-hooks/master.svg)](https://results.pre-commit.ci/latest/github/pre-commit/pre-commit-hooks/master)
Anthony Sottile's avatar
Anthony Sottile 已提交
4

Anthony Sottile's avatar
Anthony Sottile 已提交
5
pre-commit-hooks
6
================
Anthony Sottile's avatar
Anthony Sottile 已提交
7
8
9

Some out-of-the-box hooks for pre-commit.

Anthony Sottile's avatar
Anthony Sottile 已提交
10
See also: https://github.com/pre-commit/pre-commit
Anthony Sottile's avatar
Anthony Sottile 已提交
11
12
13
14
15
16


### Using pre-commit-hooks with pre-commit

Add this to your `.pre-commit-config.yaml`

17
18
```yaml
-   repo: https://github.com/pre-commit/pre-commit-hooks
Anthony Sottile's avatar
v3.4.0    
Anthony Sottile 已提交
19
    rev: v3.4.0  # Use the ref you want to point at
20
21
22
23
    hooks:
    -   id: trailing-whitespace
    # -   id: ...
```
Anthony Sottile's avatar
Anthony Sottile 已提交
24
25
26

### Hooks available

27
28
29
#### `check-added-large-files`
Prevent giant files from being committed.
  - Specify what is "too large" with `args: ['--maxkb=123']` (default=500kB).
30
  - Limits checked files to those indicated as staged for addition by git.
31
32
  - If `git-lfs` is installed, lfs files will be skipped
    (requires `git-lfs>=2.2.1`)
33
34
  - `--enforce-all` - Check all listed files not just those staged for
    addition.
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

#### `check-ast`
Simply check whether files parse as valid python.

#### `check-builtin-literals`
Require literal syntax when initializing empty or zero Python builtin types.
  - Allows calling constructors with positional arguments (e.g., `list('abc')`).
  - Allows calling constructors from the `builtins` (`__builtin__`) namespace (`builtins.list()`).
  - Ignore this requirement for specific builtin types with `--ignore=type1,type2,…`.
  - Forbid `dict` keyword syntax with `--no-allow-dict-kwargs`.

#### `check-case-conflict`
Check for files with names that would conflict on a case-insensitive filesystem like MacOS HFS+ or Windows FAT.

#### `check-docstring-first`
Checks for a common error of placing code before the docstring.

#### `check-executables-have-shebangs`
Checks that non-binary executables have a proper shebang.

#### `check-json`
Attempts to load all json files to verify syntax.

#### `check-merge-conflict`
Check for files that contain merge conflict strings.

61
62
63
#### `check-shebang-scripts-are-executable`
Checks that scripts with shebangs are executable.

64
65
66
67
68
69
70
71
#### `check-symlinks`
Checks for symlinks which do not point to anything.

#### `check-toml`
Attempts to load all TOML files to verify syntax.

#### `check-vcs-permalinks`
Ensures that links to vcs websites are permalinks.
72
73
74
75
  - `--additional-github-domain DOMAIN` - Add check for specified domain.
    Can be repeated multiple times.  for example, if your company uses
    GitHub Enterprise you may use something like
    `--additional-github-domain github.example.com`
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

#### `check-xml`
Attempts to load all xml files to verify syntax.

#### `check-yaml`
Attempts to load all yaml files to verify syntax.
  - `--allow-multiple-documents` - allow yaml files which use the
    [multi-document syntax](http://www.yaml.org/spec/1.2/spec.html#YAML)
  - `--unsafe` - Instead of loading the files, simply parse them for syntax.
    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`.

#### `debug-statements`
Check for debugger imports and py37+ `breakpoint()` calls in python source.

93
94
95
96
97
98
#### `destroyed-symlinks`
Detects symlinks which are changed to regular files with a content of a path
which that symlink was pointing to.
This usually happens on Windows when a user clones a repository that has
symlinks but they do not have the permission to create symlinks.

99
100
101
102
103
104
105
106
107
108
109
110
#### `detect-aws-credentials`
Checks for the existence of AWS secrets that you have set up with the AWS CLI.
The following arguments are available:
- `--credentials-file CREDENTIALS_FILE` - additional AWS CLI style
  configuration file in a non-standard location to fetch configured
  credentials from. Can be repeated multiple times.
- `--allow-missing-credentials` - Allow hook to pass when no credentials are detected.

#### `detect-private-key`
Checks for the existence of private keys.

#### `double-quote-string-fixer`
Jacob Bundgaard's avatar
Jacob Bundgaard 已提交
111
This hook replaces double quoted strings with single quoted strings.
112
113
114
115

#### `end-of-file-fixer`
Makes sure files end in a newline and only a newline.

116
117
118
#### `fix-byte-order-marker`
removes UTF-8 byte order marker

119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
#### `fix-encoding-pragma`
Add `# -*- coding: utf-8 -*-` to the top of python files.
  - To remove the coding pragma pass `--remove` (useful in a python3-only codebase)

#### `file-contents-sorter`
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.

#### `forbid-new-submodules`
Prevent addition of new git submodules.

#### `mixed-line-ending`
Replaces or checks mixed line ending.
  - `--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.
          - This option isn't compatible with git setup check-in LF check-out CRLF as git smudge this later than the hook is invoked.
      - `no` - Checks if there is any mixed line ending without modifying any file.

#### `name-tests-test`
Assert that files in tests/ end in `_test.py`.
  - Use `args: ['--django']` to match `test*.py` instead.

#### `no-commit-to-branch`
Protect specific branches from direct checkins.
  - Use `args: [--branch, staging, --branch, master]` to set the branch.
146
    Both `master` and `main` are protected by default if no branch argument is set.
147
148
149
150
151
  - `-b` / `--branch` may be specified multiple times to protect multiple
    branches.
  - `-p` / `--pattern` can be used to protect branches that match a supplied regex
    (e.g. `--pattern, release/.*`). May be specified multiple times.

152
153
154
155
156
157
158
Note that `no-commit-to-branch` is configured by default to [`always_run`](https://pre-commit.com/#config-always_run).
As a result, it will ignore any setting of [`files`](https://pre-commit.com/#config-files),
[`exclude`](https://pre-commit.com/#config-exclude), [`types`](https://pre-commit.com/#config-types)
or [`exclude_types`](https://pre-commit.com/#config-exclude_types).
Set [`always_run: false`](https://pre-commit.com/#config-always_run) to allow this hook to be skipped according to these
file filters. Caveat: In this configuration, empty commits (`git commit --allow-empty`) would always be allowed by this hook.

159
160
161
162
163
#### `pretty-format-json`
Checks that all your JSON files are pretty.  "Pretty"
here means that keys are sorted and indented.  You can configure this with
the following commandline options:
  - `--autofix` - automatically format json files
164
  - `--indent ...` - Control the indentation (either a number for a number of spaces or a string of whitespace).  Defaults to 2 spaces.
165
166
167
168
169
170
171
172
173
174
175
176
  - `--no-ensure-ascii` preserve unicode characters instead of converting to escape sequences
  - `--no-sort-keys` - when autofixing, retain the original key ordering (instead of sorting the keys)
  - `--top-keys comma,separated,keys` - Keys to keep at the top of mappings.

#### `requirements-txt-fixer`
Sorts entries in requirements.txt and removes incorrect entry for `pkg-resources==0.0.0`

#### `sort-simple-yaml`
Sorts simple YAML files which consist only of top-level
keys, preserving comments and blocks.

Note that `sort-simple-yaml` by default matches no `files` as it enforces a
177
very specific format.  You must opt in to this by setting [`files`](https://pre-commit.com/#config-files), for example:
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192

```yaml
    -   id: sort-simple-yaml
        files: ^config/simple/
```


#### `trailing-whitespace`
Trims trailing whitespace.
  - 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=*`.
  - 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>"]`.
Anthony Sottile's avatar
Anthony Sottile 已提交
193

194
195
196
197
198
### Deprecated / replaced hooks

- `autopep8-wrapper`: instead use
  [mirrors-autopep8](https://github.com/pre-commit/mirrors-autopep8)
- `pyflakes`: instead use `flake8`
199
- `flake8`: instead use [upstream flake8](https://gitlab.com/pycqa/flake8)
200
- `check-byte-order-marker`: instead use fix-byte-order-marker
201

Anthony Sottile's avatar
Anthony Sottile 已提交
202
203
### As a standalone package

204
If you'd like to use these hooks, they're also available as a standalone package.
Anthony Sottile's avatar
Anthony Sottile 已提交
205
206

Simply `pip install pre-commit-hooks`