precommit (version 0.1.3)

use_precommit: Set up pre-commit

Description

Get started.

Usage

use_precommit(
  config_source = getOption("precommit.config_source"),
  force = FALSE,
  legacy_hooks = "forbid",
  open = rstudioapi::isAvailable(),
  install_hooks = TRUE,
  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 to replace an existing config file.

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 the .pre-commit-config.yaml after it's been placed in your repo. The default is TRUE when working in RStudio. Otherwise, we recommend manually inspecting the file.

install_hooks

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

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()
# }