[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pre-commit/action/master.svg)](https://results.pre-commit.ci/latest/github/pre-commit/action/master)
[![Build Status](https://github.com/pre-commit/action/workflows/deploy/badge.svg)](https://github.com/pre-commit/action/actions)

pre-commit/action
=================

a GitHub action to run [pre-commit](https://pre-commit.com)

### using this action

To use this action, make a file `.github/workflows/pre-commit.yml`.  Here's a
template to get started:

```yaml
name: pre-commit

on:
  pull_request:
  push:
    branches: [master]

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-python@v2
    - uses: pre-commit/action@v2.0.0
```

This does a few things:

- clones the code
- installs python
- sets up the `pre-commit` cache

### using this action with custom invocations

By default, this action runs all the hooks against all the files.  `extra_args`
lets users specify a single hook id and/or options to pass to `pre-commit run`.

Here's a sample step configuration that only runs the `flake8` hook against all
the files (use the template above except for the `pre-commit` action):

```yaml
    - uses: pre-commit/action@v2.0.0
      with:
        extra_args: flake8 --all-files
```

### only check files that have changed

`actions/checkout@v2` does a shallow clone by default which means pre-commit
doesn't have enough Git history to determine which files have changed in order
to only check them. So you need to expand the history yourself after the
checkout action has run.

This can be done effectively by getting a blobless clone with:
```yaml
    - uses: actions/checkout@v2
    - name: Expand Git history
      run: |
        # Tell Git we want a blobless clone,
        # which excludes file contents of historical commits making the cloning much faster.
        git config remote.origin.partialclonefilter blob:none

        # Then fetch the history of the repository, skip tags since we don't need them.
        git fetch --unshallow --no-tags
```

and you can then configure pre-commit to run with:
```yaml
    - uses: pre-commit/action@v2.0.0
      with:
        extra_args: --from-ref ${{ github.event.pull_request.base.sha }} --to-ref HEAD
```

### using this action in private repositories

this action also provides an additional behaviour when used in private
repositories.  when configured with a github token, the action will push back
fixes to the pull request branch.

using the template above, you'll make two replacements for individual actions:

first is the checkout step, which needs to use unlimited fetch depth for
pushing

```yaml
    - uses: actions/checkout@v2
      with:
        fetch-depth: 0
```

next is passing the token to the pre-commit action

```yaml
    - uses: pre-commit/action@v2.0.0
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
```

note that `secrets.GITHUB_TOKEN` is automatically provisioned and will not
require any special configuration.

while you could _technically_ configure this for a public repository (using a
personal access token), I can't think of a way to do this safely without
exposing a privileged token to pull requests -- if you have any ideas, please
leave an issue!