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

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



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


Whether or not to overwrite an existing ci config file (only relevant for ci = "gha").


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.


Whether or not to open .pre-commit-config.yaml after it's been placed in your repo as well as (if ci = "native"). The default is TRUE when working in RStudio.


Whether to install environments for all available hooks. If FALSE, environments are installed with first commit.


Specifies which continuous integration service to use. See vignette("ci", package = "precommit") for details. Defaults to getOption("", "native"), which is set to "native" on package loading (if unset). "native" sets up Alternatively, "gha" can be used to set up GitHub Actions. Set value to NULL if you don't want to use a continuous integration.


Whether or not to run autoupdate() as part of this function call.


The path to the root directory of your project.


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.

See also

Other helpers: open_config()


if (FALSE) {