use_precommit {precommit}

Get started with pre-commit

Description

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

Usage

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.

See Also

Other helpers: open_config()

Examples

## Not run: 
use_precommit()

## End(Not run)