This page covers how to set up a local installation. If you are contributing to a repo that has https://pre-commit.ci enabled and you don’t want to run the hooks locally, all you need to do is push, observe if the CI passes, and if not, pull the auto-fixes https://pre-commit.ci made and then fix the remainder manually and push again. We recommend running the hooks locally too to avoid tedious feedback loops from CI for everything but trivial commits.
You can install the package from CRAN:
install.packages("precommit")
To access pre-commit functionality from R, you also need to install the pre-commit framework on which the hooks from this repo build. The following command line methods are tested to work with this R package (and accessing them from outside R is easier and use is slightly faster):
$ pip3 install pre-commit --user
(macOS, Linux and
Windows) outside a conda or virtual
environment.
$ brew install pre-commit
(macOS).
Alternatively, you can handle the installation from R using miniconda:
install miniconda if you don’t have it already:
reticulate::install_miniconda()
. This needs reticulate
>= 1.14.
install the pre-commit framework with
precommit::install_precommit()
into the conda environment
r-precommit
. Do not install other packages into this
environment.
Then, in a fresh R session:
# once in every git repo either
# * after cloning a repo that already uses pre-commit or
# * if you want introduce pre-commit to this repo
::use_precommit() precommit
The last command initializes pre-commit in your repo and performs
some set-up tasks like creating the config file
.pre-commit-config.yaml
, where the hooks that will be run
on git commit
are specified. See
?precommit::use_precommit()
to see how you can use a custom
.pre-commit-config.yaml
instead of the default at
initialization. You can (obviously) change edit the file manually at any
time.
The next time you run git commit
, the hooks listed in
your .pre-commit-config.yaml
will get executed before the
commit. The helper function precommit::open_config()
let’s
you open and edit the .pre-commit-config.yaml
conveniently
from the RStudio console. When any file is changed due to running a hook
or the hook script errors, the commit will fail. You can inspect the
changes introduced by the hook and if satisfied, you can add the changes
made by the hook to the index with git add path/to/file
and
attempt to commit again. Some hooks change files, like the styler hook,
so all you need to do to make the hook pass is git add
the
changes introduced by the hook. Other hooks, like the parsable-R hook,
will need your action, e.g. add a missing closing brace to a call like
library(styler
, before they pass at the next attempt. If
all hooks pass, the commit is made. You can also temporarily
disable hooks. If you succeed, it should look like this:
See the hooks provided by this repo under
vignette("available-hooks")
. You can also add other hooks
from other repos, by extending the .pre-commit-config.yaml
file, e.g. like this:
- repo: https://github.com/pre-commit/precommit
rev: v1.2.3
hooks:
- id: check-added-large-files
To update the hook revisions, run
precommit::autoupdate()
.
Do not abort while hooks are running in RStudio git
tab. Non-staged changes are stashed to a temp directory and
when you abort in RStudio, these changes are not brought back to you
repo. Upvote this issue to
change this. We hope that in the future, the changes will be recovered
in RStudio too. Note that this is only an issue with RStudio. Stashes
are restored when you abort a git commit
with
INT
(e.g. Ctrl+C) on the command line. To restore stashes,
manually after hitting abort in the RStudio git tab, you can
git apply /path/to/patch_with_id
whereas you find the patch
under your pre-commit cache, which is usually under
$HOME/.cache/pre-commit/
.
If you used {precommit} before, upgrade these three components for maximal compatibility:
the R package {precommit} from CRAN with
install.packages("precommit")
.
the hook revisions in your .pre-commit-config.yaml
with precommit::autoupdate()
. Hook revision updates are
released in sync with R package updates (exception: Patch releases for
hooks don’t have a corresponding CRAN release).
the upstream pre-commit framework. Use the update utilities
provided by your installation method (i.e. pip3
or
brew
). If you chose conda, you can use
precommit::update_precommit()
. If you don’t remember the
installation method you chose, just choose any and then upgrade. We’ll
warn you if you have multiple executables installed and point you to
their location so you can get rid of all but one. You can check the
version of you executable with
precommit::version_precommit()
. Updates to the pre-commit
framework are not released in sync with the R or hook revision
updates.
uninstall_precommit("repo") # just for the repo you are in.
uninstall_precommit("user") # remove the pre-commit conda executable.