Get started with pre-commit

This function sets up pre-commit for your git repo.

use_precommit(
  config_source = getOption("precommit.config_source"),
  force = FALSE,
  legacy_hooks = "forbid",
  open = rstudioapi::isAvailable(),
  install_hooks = TRUE,
  ci = getOption("precommit.ci", "native"),
  autoupdate = install_hooks,
  root = here::here()
)

Arguments

config_source: Path or URL to a .pre-commit-config.yaml. This config file will be hard-copied into root. If NULL, we check if root is a package or project directory using rprojroot::find_package_root_file(), and resort to an appropriate default config. See section 'Copying an existing config file'.
force: Whether or not to overwrite an existing ci config file (only relevant for ci = "gha").
legacy_hooks: How to treat hooks already in the repo which are not managed by pre-commit. "forbid", the default, will cause use_precommit() to fail if there are such hooks. "allow" will run these along with pre-commit. "remove" will delete them.
open: Whether or not to open .pre-commit-config.yaml after it's been placed in your repo as well as pre-commit.ci (if ci = "native"). The default is TRUE when working in RStudio.
install_hooks: Whether to install environments for all available hooks. If FALSE, environments are installed with first commit.
ci: Specifies which continuous integration service to use. See vignette("ci", package = "precommit") for details. Defaults to getOption("precommit.ci", "native"), which is set to "native" on package loading (if unset). "native" sets up pre-commit.ci. Alternatively, "gha" can be used to set up GitHub Actions. Set value to NA if you don't want to use a continuous integration.
autoupdate: Whether or not to run autoupdate() as part of this function call.
root: The path to the root directory of your project.

Value

NULL (invisibly). The function is called for its side effects.

When to call this function?

You want to add pre-commit support to a git repo which does not have a .pre-commit-config.yaml. This involves adding a pre-commit config file and making sure git will call the hooks before the next commit.
You cloned a repo that has a .pre-commit-config.yaml already. You need to make sure git calls the hooks before the next commit.

What does the function do?

Sets up a template .pre-commit-config.yaml.
Autoupdates the template to make sure you get the latest versions of the hooks.
Installs the pre-commit script along with the hook environments with $ pre-commit install --install-hooks.
Opens the config file if RStudio is running.

Copying an existing config file

You can use an existing .pre-commit-config.yaml file when initializing pre-commit with use_precommit() using the argument config_source to copy an existing config file into your repo. This argument defaults to the R option precommit.config_source, so you may want to set this option in your .Rprofile for convenience. Note that this is not equivalent to the --config option in the CLI command pre-commit install and similar, which do not copy a config file into a project root (and allow to put it under version control), but rather link it in some more or less transparent way.

Examples