Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 1045b76

Browse files
struysstruys
committed
Update README.md
1 parent fe29f33 commit 1045b76

1 file changed

Lines changed: 258 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 258 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,269 @@
11
[![Build Status](https://travis-ci.org/pre-commit/pre-commit.svg?branch=master)](https://travis-ci.org/pre-commit/pre-commit)
22
[![Coverage Status](https://img.shields.io/coveralls/pre-commit/pre-commit.svg?branch=master)](https://coveralls.io/r/pre-commit/pre-commit)
33

4-
pre-commit
5-
==========
4+
## pre-commit
65

76
A framework for managing and maintaining multi-language pre-commit hooks.
87

9-
Some out-of-the-box hooks: https://github.com/pre-commit/pre-commit-hooks
8+
## Introduction
109

10+
At Yelp we rely heavily on pre-commit hooks to find and fix common
11+
issues before changes are submitted for code review. We run our hooks before
12+
every commit to automatically point out issues like missing semicolons,
13+
whitespace problems, and testing statements in code. Automatically fixing these
14+
issues before posting code reviews allows our code reviewer to pay attention to
15+
architecture of a change and not worry about trivial errors.
1116

12-
## What is a "pre-commit"
17+
As we created more libraries and projects we recognized that sharing our pre
18+
commit hooks across projects is painful. We copied and pasted bash scripts from
19+
project to project. We also had to manually change the hooks to work for
20+
different project structures.
1321

14-
A pre-commit is some code that runs before commiting code to do some spot-checking for some basic programming mistakes.
22+
We believe that you should always use the best industry standard linters. Some
23+
of the best linters are written in languages that you do not use in your
24+
project or have installed on your machine. For example scss-lint is a linter
25+
for SCSS written in ruby. If you're writing a project in node you should be able
26+
to use scss-lint as a pre-commit hook without adding a Gemfile to your project
27+
or understanding how to get scss-lint installed.
1528

16-
## Why make this project?
29+
We built pre-commit to solve our hook issues. pre-commit is a multi-language
30+
package manager for pre-commit hooks. You specify a list of hooks you want
31+
and pre-commit manages the installation and execution of any hook written in any
32+
language before every commit. pre-commit is specifically designed to not
33+
require root access; if one of your developers doesn't have node installed but
34+
modifies a javascript file, pre-commit automatically handles downloading and
35+
building node to run jshint without root.
1736

18-
We noticed that when creating a git repo it was not convenient to create pre-commit hooks. Often we resorted to copy/paste to include a set of useful hooks. https://github.com/causes/overcommit is an awesome project, but locked us into ruby and system packages -- which we wanted to avoid.
37+
## Installation
38+
39+
Before you can run hooks, you need to have the pre-commit package manager
40+
installed.
41+
42+
Using pip:
43+
44+
pip install pre-commit
45+
46+
Non Administrative Installation:
47+
48+
curl http://pre-commit.github.io/local-install.py | python
49+
50+
System Level Install:
51+
52+
sudo curl https://bootstrap.pypa.io/get-pip.py | python - pre-commit
53+
54+
In a Python Project, add the following to your requirements.txt (or requirements-dev.txt):
55+
56+
pre-commit
57+
58+
59+
## Adding pre-commit Plugins To Your Project
60+
61+
Once you have pre-commit installed, adding pre-commit plugins to your project is
62+
done with the `.pre-commit-config.yaml` configuration file.
63+
64+
Add a file called `.pre-commit-config.yaml` to the root of your project. The
65+
pre-commit config file describes:
66+
67+
- `repo`, `sha` - where to get plugins (git repos).
68+
- `id` - What plugins from the repo you want to use.
69+
- `language_version` - (optional) Override the default language version for the hook.
70+
See Advanced Features: "Overriding Language Version"
71+
- `files` - (optional) Override the default pattern for files to run on.
72+
- `exclude` - (optional) File exclude pattern.
73+
- `args` - (optional) additional parameters to pass to the hook.
74+
75+
For example:
76+
77+
- repo: [email protected]:pre-commit/pre-commit-hooks
78+
sha: 82344a4055f4e103afdc31e98a46de679fe55385
79+
hooks:
80+
- id: trailing-whitespace
81+
82+
This configuration says to download the pre-commit-hooks project and run it's
83+
trailing-whitespace hook.
84+
85+
86+
## Usage
87+
88+
run `pre-commit install` to install pre-commit into your git hooks. pre-commit
89+
will now run on every commit. Everytime you clone a project using pre-commit
90+
running install should always be the first thing you do.
91+
92+
If you want to manually run all pre-commit hooks on a repository, run
93+
`pre-commit run --all-files`. To run individual hooks use
94+
`pre-commit run <hook_id>`.
95+
96+
The first time pre-commit runs on a file it will automatically download, install,
97+
and run the hook. Note that running a hook for the first time may be slow.
98+
For example: If the machine does not have node installed, pre-commit will download
99+
and build a copy of node.
100+
101+
102+
## Creating New Hooks
103+
104+
pre-commit currently supports hooks written in JavaScript (node), Python, Ruby
105+
and system installed scripts. As long as your git repo is an installable package
106+
(gem, npm, pypi, etc) or exposes a executable, it can be used with pre-commit.
107+
Each git repo can support as many languages/hooks as you want.
108+
109+
An executable must satisfy the following things:
110+
111+
- Returncode of hook must be different between success / failures
112+
(Usually 0 for success, nonzero for failure)
113+
- It must take filenames
114+
115+
A git repo containing pre-commit plugins must contain a hooks.yaml file that
116+
tells pre-commit:
117+
118+
- `id` - The id of the hook - used in pre-commit-config.yaml
119+
- `name` - The name of the hook - shown during hook execution
120+
- `entry` - The entry point - The executable to run
121+
- `files` - The pattern of files to run on.
122+
- `language` - The language of the hook - tells pre-commit how to install the hook
123+
- `description` - (optional) The description of the hook
124+
- `language_version` - (optional) See advanced features "Overriding Language Version"
125+
- `expected_return_value` - (optional) Defaults to 0
126+
127+
For example:
128+
129+
- id: trailing-whitespace
130+
name: Trim Trailing Whitespace
131+
description: This hook trims trailing whitespace.
132+
entry: trailing-whitespace-fixer
133+
language: python
134+
files: \.(js|rb|md|py|sh|txt|yaml|yml)$
135+
136+
137+
## Popular Hooks
138+
139+
JSHint:
140+
141+
- repo: [email protected]:pre-commit/mirrors-jshint
142+
sha: 8e7fa9caad6f7b2aae8d2c7b64f457611416192b
143+
hooks:
144+
- id: jshint
145+
146+
SCSS-Lint:
147+
148+
- repo: [email protected]:pre-commit/mirrors-scss-lint
149+
sha: d7266131da322d6d76a18d6a3659f21025d9ea11
150+
hooks:
151+
- id: scss-lint
152+
153+
Ruby-Lint:
154+
155+
- repo: git://github.com/pre-commit/mirrors-ruby-lint
156+
sha: f4b537e0bf868fc6baefcb61288a12b35aac2157
157+
hooks:
158+
- id: ruby-lint
159+
160+
Whitespace Fixers:
161+
162+
- repo: git://github.com/pre-commit/pre-commit-hooks
163+
sha: a751eb58f91d8fa70e8b87c9c95777c5a743a932
164+
hooks:
165+
- id: trailing-whitespace
166+
- id: end-of-file-fixer
167+
168+
flake8:
169+
170+
- repo: git://github.com/pre-commit/pre-commit-hooks
171+
sha: a751eb58f91d8fa70e8b87c9c95777c5a743a932
172+
hooks:
173+
- id: flake8
174+
175+
pyflakes:
176+
177+
- repo: git://github.com/pre-commit/pre-commit-hooks
178+
sha: a751eb58f91d8fa70e8b87c9c95777c5a743a932
179+
hooks:
180+
- id: pyflakes
181+
182+
183+
## Advanced features
184+
185+
### Temporarily Disabling Hooks
186+
187+
Not all hooks are perfect so sometimes you may need to skip execution of
188+
one or more hooks. pre-commit solves this by querying a `SKIP` environment
189+
variable. The `SKIP` environment variable is a comma separated list of
190+
hook ids. This allows you to skip a single hook instead of `--no-verify`ing
191+
the entire commit
192+
193+
$ SKIP=flake8 git commit -m "foo"
194+
195+
### pre-commit During Commits
196+
197+
Running hooks on unstaged changes can lead to both false-positives and
198+
false-negatives during committing. pre-commit only runs on the staged
199+
contents of files by temporarily saving the contents of your files at
200+
commit time and stashing the unstaged changes while running hooks.
201+
202+
### pre-commit During Merges
203+
204+
The biggest gripe we've had in the past with pre-commit hooks was during
205+
merge conflict resolution. When working on very large projects a merge
206+
often results in hundreds of committed files. I shouldn't need to run
207+
hooks on all of these files that I didn't even touch! This often led
208+
to running commit with `--no-verify` and allowed introduction of real
209+
bugs that hooks could have caught through merge-conflict resolution.
210+
pre-commit solves this by only running hooks on files that conflict or
211+
were manually edited during conflict resolution.
212+
213+
214+
### Passing Arguments to Hooks
215+
216+
Sometimes hooks require arguments to run correctly. You can pass
217+
static arguments by specifying the `args` property in your
218+
`.pre-commit-config.yaml` as follows:
219+
220+
- repo: git://github.com/pre-commit/pre-commit-hooks
221+
sha: a751eb58f91d8fa70e8b87c9c95777c5a743a932
222+
hooks:
223+
- id: flake8
224+
args: [--max-line-length=131]
225+
226+
This will pass `--max-line-length=131` to `flake8`
227+
228+
229+
### Overriding Language Version
230+
231+
Sometimes you only want to run the hooks on a specific version of
232+
the language. For each language, they default to using the system
233+
installed language (So for example if I'm running `python2.6` and a
234+
hook specifies `python`, pre-commit will run the hook using `python2.6`).
235+
Sometimes you don't want the default system installed version so you can
236+
override this on a per-hook basis by setting the `language_version`.
237+
238+
239+
- repo: [email protected]:pre-commit/mirrors-scss-lint
240+
sha: d7266131da322d6d76a18d6a3659f21025d9ea11
241+
hooks:
242+
- id: scss-lint
243+
language_version: 1.9.3-p484
244+
245+
This tells pre-commit to use `1.9.3-p484` to run the `scss-lint` hook.
246+
247+
Valid values for specific languages are listed below:
248+
249+
- python: Whatever system installed python interpreters you have.
250+
The value of this argument is passed as the `-p` to `virtualenv`
251+
- node: See https://github.com/ekalinin/nodeenv#advanced
252+
- ruby: See https://github.com/sstephenson/ruby-build/tree/master/share/ruby-build
253+
254+
255+
## Contributing
256+
257+
We're looking to grow the project and get more contributors especially
258+
to support more languages/versions. We'd also like to get the hooks.yaml
259+
files added to popular linters without maintaining forks / mirrors.
260+
261+
Feel free to submit Bug Reports, Pull Requests, and Feature Requests.
262+
263+
When submitting a pull request, please enable travis-ci for your fork.
264+
265+
266+
## Contributors
267+
268+
- Anthony Sottile
269+
- Ken Struys

0 commit comments

Comments
 (0)