No magic. Git provides a mechanism for pre-commit hooks. Since it’s cumbersome to copy bash scripts and keep them updated in some hidden .git/ directory, people wrote frameworks to basically maintain these files. One of them is pre-commit.com. So you call git to commit, git calls its internal hooks, these hooks (bash scripts in the simplest case) are provided by the pre-commit framework. And where does pre-commit get all it’s nice hooks from? From us.
Internet connection is required during installation (precommit::install_precommit()) and project initialization (precommit::use_precommit()) as well as when hooks are updated (precommit::autoupdate()). Otherwise, no internet connection is required. Hooks will be placed into .git/ during calling the precommit::use_precommit() and afterwards you can precommit::autoupdate() to replace the hooks with their new version (that’s what I think happens).
Yes, all but the open_config() and open_wordlist() to open files in RStudio.
Yes, apart from the roxygenize hook (which uses an exported function from {precommit}). The hooks work even if you don’t have the R package installed because all you need to have for the hooks to work is the pre-commit executable. It will git clone the hooks from this repo into .git/hooks or similar. All exported functions of this package are just for the users convenience.
They must follow the installation instructions in the README, i.e. run
remotes::install_github("lorenzwalthert/precommit")
precommit::install_precommit()
precommit::use_precommit()The last call can be omitted by users who have automatically enabled pre-commit hooks.
To enforce all hooks pass, you can follow the advice on how to use pre-commit in a CI/CD setup.
This is not a problem, git will only run the hooks in a local repo after precommit::use_precommit() has been run successfully from within this local repo on your machine. You can also uninstall anytime with precommit::uninstall_precommit(). Anyone who does not want to use the hooks simply should not run precommit::use_precommit(). You can also temporarily disable hooks as described here.
How to contribute new hooks is explained in CONTRIBUTING.md.
Some of the hooks depend on R functions that run slowly, e.g. the style-files hook depends on styler, which is not very fast. Also, note that for each hook, R is started. Make sure your startup process is quick for non-interactive use, e.g. your .Rprofile and related files do not have a long execution time. E.g. wrap code in if (interactive()) if possible, so it won’t run when pre-commit hooks are ran. Find out more about the startup process with ?startup. We’d like to support the --vanilla option but it’s not easily possible we believe.
There is more. Check out the documentation of the pre-commit framework.