pre-commit

pre-commit 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.

import Pkg; Pkg.add("JuliaFormatter")

To use the hook, you can add the following to your .pre-commit-config.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:

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. 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.

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.

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:

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):

repos:
- repo: https://github.com/JuliaEditorSupport/JuliaFormatter.jl
  rev: TODO TODO
  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.