## [`pre-commit`](@id pre-commit)

[`pre-commit`](https://pre-commit.com) is a tool for installing and managing pre-commit Git hooks, which makes Git automatically run specified commands before commits are made.
This is useful for ensuring that code matches a certain quality standard before it is committed: for example, you can use `pre-commit` to run `JuliaFormatter.jl` on your code before it is committed.

JuliaFormatter provides two pre-commit hooks for you to use.
One uses the old-style `julia -e ...` invocation; the other uses the `jlfmt` app, which must be installed separately.

### `julia-formatter` hook (uses `julia -e ...`)

This hook launches JuliaFormatter via your global Julia installation, which means that you must first install JuliaFormatter as a package.

```julia
import Pkg; Pkg.add("JuliaFormatter")
```

To use the hook, you can add the following to your `.pre-commit-config.yaml`:

```yaml
repos:
- repo: https://github.com/JuliaEditorSupport/JuliaFormatter.jl
  rev: 0935890389c9fbc45f4ee150064c0abe5340b6a9 # v2.4.0
  hooks:
  - id: "julia-formatter"
```

(If you have other pre-commit hooks, just add the `repo: ...` block to your pre-existing list of repos.)

To pass additional arguments to the Julia invocation (e.g. if JuliaFormatter is installed in a specific project), you can use the `args` field, like so:

```yaml
repos:
- repo: https://github.com/JuliaEditorSupport/JuliaFormatter.jl
  rev: 0935890389c9fbc45f4ee150064c0abe5340b6a9 # v2.4.0
  hooks:
  - id: "julia-formatter"
    args: ["--project=/path/to/myproj"]
```

**Note that `rev` controls the version of the _hook_ that is checked out; it does not control which version of JuliaFormatter is actually used to format your code.**
The version used to do the actual formatting is determined by the version of JuliaFormatter that is installed in your global Julia environment.
This means that if you want to format your code with JuliaFormatter v1, you must make sure that you install v1 in your global Julia environment.

The `rev` field above is a commit hash that points to [v2.4.0 of JuliaFormatter.jl](https://github.com/JuliaEditorSupport/JuliaFormatter.jl/releases/tag/v2.4.0).
As of the time of writing, this is the latest release of JuliaFormatter.jl.
However, it is extremely unlikely that this hook will change in future releases, so you do not need to worry about 'updating' it to a newer version.

!!! note
    You could also point to a branch or a release tag, but it is safer to point to a commit hash, since that is immutable and is not vulnerable to e.g. supply chain attacks.

### `jlfmt` hook (uses the `jlfmt` app)

To use the `jlfmt` hook you must first make sure that the `jlfmt` app is installed on your system.
Instructions for installing the `jlfmt` app are given in the [CLI documentation](@ref cli).

The version of `jlfmt` that you install here will be the version that is used to actually format your code.
The `jlfmt` app was only introduced in v2.2.0, so versions before that are inaccessible: if you want to format your code with JuliaFormatter v1, you will not be able to use this hook.

Once you have the `jlfmt` app installed, you can add the following to your `.pre-commit-config.yaml`:

```yaml
repos:
- repo: https://github.com/JuliaEditorSupport/JuliaFormatter.jl
  rev: 0935890389c9fbc45f4ee150064c0abe5340b6a9 # v2.4.0
  hooks:
  - id: "jlfmt"
```

The path to the `jlfmt` executable can be specified in the `args` field of the hook, like so (although you should not _need_ to do so—see below):

```yaml
repos:
- repo: https://github.com/JuliaEditorSupport/JuliaFormatter.jl
  rev: 0935890389c9fbc45f4ee150064c0abe5340b6a9 # v2.4.0
  hooks:
  - id: "jlfmt"
    args: ["--jlfmt-path=/path/to/jlfmt"]
```

However, even without this argument, the pre-commit hook will attempt to locate `jlfmt` for you.
It looks in the following places, in order:

1. Using the executable specified via the `--jlfmt-path` argument, if provided.
2. A `jlfmt` executable on your system `PATH`.
3. `{dir}/bin/jlfmt` for each directory `{dir}` in the `JULIA_DEPOT_PATH` environment variable.
4. `~/.julia/bin/jlfmt`, which is the default depot path if `JULIA_DEPOT_PATH` is not set.

Just like for the `julia-formatter` hook, the `rev` field controls the version of the _hook_ that is checked out, not the version of JuliaFormatter that is used to do the formatting: that is governed by the version of the `jlfmt` app that you installed.
The `rev` field used here points to JuliaFormatter v2.4.0, but this hook is unlikely to change in future releases, so you do not need to worry about updating it to a newer version.

!!! note
    You could also point `rev` to a branch or a release tag, but it is safer to point to a commit hash, since that is immutable and is not vulnerable to e.g. supply chain attacks.

