### Example: Install pre-commit

Source: https://lorenzwalthert.github.io/precommit/reference/install_precommit.html

Demonstrates the usage of the `install_precommit()` function. This example is wrapped in a \dontrun{} block, indicating it should not be run automatically during package checks.

```r
if (FALSE) { # \dontrun{
install_precommit()
} # }
```

--------------------------------

### Example of calling use_precommit

Source: https://lorenzwalthert.github.io/precommit/reference/use_precommit.html

This is a basic example of how to call the use_precommit function without any arguments, which will use default settings. It is marked as a non-runnable example.

```r
if (FALSE) { # \dontrun{
use_precommit()
} # }
```

--------------------------------

### Install pre-commit Framework (Homebrew)

Source: https://lorenzwalthert.github.io/precommit/articles/precommit.html

Install the pre-commit framework using Homebrew. This is a convenient option for macOS users.

```bash
brew install pre-commit
```

--------------------------------

### Setup pre-commit for a Git repository

Source: https://lorenzwalthert.github.io/precommit/reference/use_precommit.html

Use this function to initialize pre-commit in a Git repository. It sets up a default configuration file, installs hooks, and optionally configures CI integration. It's called when you want to add pre-commit to a new or existing project.

```r
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()
)
```

--------------------------------

### Example of autoupdate usage

Source: https://lorenzwalthert.github.io/precommit/reference/autoupdate.html

Demonstrates how to call the `autoupdate` function. This example is wrapped in `if (FALSE)` to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
autoupdate()
} # }
```

--------------------------------

### Example: Open pre-commit configuration

Source: https://lorenzwalthert.github.io/precommit/reference/open_config.html

Demonstrates how to open the pre-commit configuration file. This code is for demonstration purposes and will not run by default.

```r
if (FALSE) { # \dontrun{
open_config()
} # }
```

--------------------------------

### Install and Use Pre-commit Hooks

Source: https://lorenzwalthert.github.io/precommit/articles/FAQ.html

Follow these steps to install the precommit package and integrate its hooks into your project. The last step can be omitted if automatic pre-commit hook enablement is configured.

```r
remotes::install_github("lorenzwalthert/precommit")
```

```r
precommit::install_precommit()
```

```r
precommit::use_precommit()
```

--------------------------------

### Example: Open pre-commit wordlist

Source: https://lorenzwalthert.github.io/precommit/reference/open_config.html

Demonstrates how to open the pre-commit wordlist file. This code is for demonstration purposes and will not run by default.

```r
if (FALSE) { # \dontrun{
open_wordlist()
} # }
```

--------------------------------

### Retrieve pre-commit Executable Version

Source: https://lorenzwalthert.github.io/precommit/reference/version_precommit.html

Call this function to get the version of the pre-commit executable. No setup or imports are required.

```R
version_precommit()
```

--------------------------------

### Example usage of path_precommit_exec

Source: https://lorenzwalthert.github.io/precommit/reference/path_precommit_exec.html

Demonstrates calling the `path_precommit_exec()` function. This example is wrapped in `if (FALSE)` to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
path_precommit_exec()
}
```

```r
if (FALSE) { # \dontrun{
path_pre_commit_exec()
}
```

--------------------------------

### Install pre-commit Framework (pip)

Source: https://lorenzwalthert.github.io/precommit/articles/precommit.html

Install the pre-commit framework using pip. This method is recommended for macOS, Linux, and Windows, and should be done outside of a conda or virtual environment.

```bash
pip3 install pre-commit --user
```

--------------------------------

### Example of initiating pre-commit config

Source: https://lorenzwalthert.github.io/precommit/reference/use_precommit_config.html

Demonstrates the basic usage of `use_precommit_config()` without any arguments, which will use default settings to create the configuration file.

```R
use_precommit_config()
```

--------------------------------

### pre-commit installation behavior

Source: https://lorenzwalthert.github.io/precommit/news/index.html

Changes in how pre-commit is installed and managed, including blocking behavior and duplicate installation warnings.

```APIDOC
## Pre-commit Installation Management

### Description
Updates to the installation and management of the pre-commit framework.

### Details
- A warning is issued if multiple pre-commit installations are found to prevent duplicates.
- `use_precommit(..., install_hooks = TRUE)` is no longer blocking by default. The behavior is controlled by the new option `precommit.block_install_hooks` (defaults to `FALSE`).
```

--------------------------------

### Get pre-commit executable path

Source: https://lorenzwalthert.github.io/precommit/articles/ci.html

Locate the pre-commit executable path when installed via R. This is useful if pre-commit is not on your system's PATH.

```r
precommit::path_pre_commit_exec()
#> "/usr/local/bin/pre-commit"
```

--------------------------------

### use_precommit

Source: https://lorenzwalthert.github.io/precommit/reference/use_precommit.html

Sets up pre-commit for your git repository. This function creates a `.pre-commit-config.yaml` file, updates it with the latest hook versions, and installs the necessary git hooks. It can also manage existing hooks, configure CI integration, and control the installation process.

```APIDOC
## Function: use_precommit

### Description
Sets up pre-commit for your git repo. This function creates a `.pre-commit-config.yaml` file, updates it with the latest hook versions, and installs the necessary git hooks. It can also manage existing hooks, configure CI integration, and control the installation process.

### Arguments

* `config_source` (character or NULL): Path or URL to a `.pre-commit-config.yaml`. If `NULL`, it attempts to find a default config based on whether the `root` is a package or project directory.
* `force` (logical): Whether to overwrite an existing CI config file (relevant for `ci = "gha"`). Defaults to `FALSE`.
* `legacy_hooks` (character): How to treat hooks already in the repo. Options are "forbid" (default), "allow", or "remove".
* `open` (logical): Whether to open `.pre-commit-config.yaml` after setup. Defaults to `TRUE` when in RStudio.
* `install_hooks` (logical): Whether to install environments for all available hooks. If `FALSE`, environments are installed with the first commit. Defaults to `TRUE`.
* `ci` (character or NA): Specifies the continuous integration service to use. Options include "native" (default), "gha", or `NA` to disable CI setup.
* `autoupdate` (logical): Whether to run `autoupdate()` as part of this function call. Defaults to the value of `install_hooks`.
* `root` (character): The path to the root directory of your project. Defaults to `here::here()`.

### Value

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

### When to call this function?

* To add pre-commit support to a git repo that lacks a `.pre-commit-config.yaml` file.
* To ensure git hooks are active in a cloned repository that already has a `.pre-commit-config.yaml` file.

### What does the function do?

* Sets up a template `.pre-commit-config.yaml`.
* Autoupdates the template to ensure the latest hook versions are used.
* Installs the pre-commit script and hook environments using `$ 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 by specifying its path or URL using the `config_source` argument. This file will be copied into your repository. This is different from the `--config` option in CLI commands, which links the file instead of copying it.

### Examples

```R
if (FALSE) { # \dontrun{
use_precommit()
}
}
```
```

--------------------------------

### Install pre-commit

Source: https://lorenzwalthert.github.io/precommit/reference/install_precommit.html

Installs pre-commit in the 'r-precommit' conda environment. Use this to make pre-commit available across different Git repositories. Refer to `update_precommit()` for updating.

```r
install_precommit(force = FALSE)
```

--------------------------------

### Install precommit R Package

Source: https://lorenzwalthert.github.io/precommit/articles/precommit.html

Install the precommit R package from CRAN. This is the first step to using pre-commit functionality within R.

```r
install.packages("precommit")
```

--------------------------------

### Setup Continuous Integration with pre-commit

Source: https://lorenzwalthert.github.io/precommit/reference/use_ci.html

Use this function to set up continuous integration for your project. It supports native pre-commit.ci and GitHub Actions. The default behavior opens pre-commit.ci in RStudio.

```r
use_ci(
  ci = getOption("precommit.ci", "native"),
  force = FALSE,
  open = rstudioapi::isAvailable(),
  root = here::here()
)
```

--------------------------------

### GPL Interactive Mode Notice

Source: https://lorenzwalthert.github.io/precommit/LICENSE.html

This notice should be displayed by programs when they start in interactive mode, informing users about warranty and redistribution conditions.

```text
precommit Copyright (C) 2019 Lorenz Watlhert
This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type 'show c' for details.
```

--------------------------------

### use_ci

Source: https://lorenzwalthert.github.io/precommit/reference/use_ci.html

Sets up continuous integration for your project. It can automatically configure services like pre-commit.ci or GitHub Actions, or prompt the user for manual setup.

```APIDOC
## Function: use_ci

### Description
Sets up continuous integration, or prompts the user to do it manually.

### Arguments

* `ci` (character or NA) - Specifies which continuous integration service to use. Defaults to `getOption("precommit.ci", "native")`. Use `"native"` for pre-commit.ci, `"gha"` for GitHub Actions, or `NA` to disable CI setup.
* `force` (logical) - Whether or not to overwrite an existing CI config file (only relevant for `ci = "gha"`).
* `open` (logical) - Whether or not to open the CI service configuration page. Defaults to `TRUE` when working in RStudio.
* `root` (character) - The path to the root directory of your project. Defaults to the current working directory.

### Example

```R
use_ci()
use_ci(ci = "gha", force = TRUE)
use_ci(ci = NA)
```
```

--------------------------------

### Install pre-commit

Source: https://lorenzwalthert.github.io/precommit/reference/install_precommit.html

Installs pre-commit in the conda environment 'r-precommit'. This makes pre-commit available for use across multiple git repositories. To update pre-commit, use the `update_precommit()` function.

```APIDOC
## install_precommit()

### Description
Installs pre-commit in the conda environment 'r-precommit'. It will be available to use across different git repositories. To update, refer to `update_precommit()`.

### Arguments

* `force` (logical) - Whether or not to force a re-installation.

### Value
The path to the pre-commit executable (invisibly).

### See also
Other executable managers: `uninstall_precommit()`, `update_precommit()`, `version_precommit()`

### Examples

```R
if (FALSE) { # \dontrun{
install_precommit()
}
}

```

--------------------------------

### Standard GPL Copyright Notice

Source: https://lorenzwalthert.github.io/precommit/LICENSE.html

Include this notice at the start of each source file to state the exclusion of warranty and specify licensing terms under the GNU GPL.

```text
<one line to give the program\'s name and a brief idea of what it does.>
Copyright (C) 2019 Lorenz Watlhert

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
```

--------------------------------

### Style Files with Custom Style Guide

Source: https://lorenzwalthert.github.io/precommit/articles/available-hooks.html

Customize the `style-files` hook to use a different style package and function by specifying `style_pkg` and `style_fun` arguments.

```yaml
id: style-files
args: [--style_pkg=pkg.with.style.guide, --style_fun=exported.style.function]
```

--------------------------------

### version_precommit() and update_precommit() functions

Source: https://lorenzwalthert.github.io/precommit/news/index.html

New functions to check the version of the installed pre-commit executable and to update it.

```APIDOC
## version_precommit() and update_precommit()

### Description
`version_precommit()` checks the installed pre-commit executable version, and `update_precommit()` updates it.

### Details
These functions help manage the pre-commit executable version within the project.
```

--------------------------------

### Get pre-commit executable path

Source: https://lorenzwalthert.github.io/precommit/reference/path_precommit_exec.html

Use `path_precommit_exec()` to get the path to the pre-commit executable. The `check_if_exists` argument defaults to TRUE, ensuring the returned path is valid.

```r
path_precommit_exec(check_if_exists = TRUE)
```

```r
path_pre_commit_exec(check_if_exists = TRUE)
```

--------------------------------

### Add External pre-commit Hook

Source: https://lorenzwalthert.github.io/precommit/articles/precommit.html

Example of how to extend the .pre-commit-config.yaml file to include hooks from other repositories, such as the check-added-large-files hook from the pre-commit repository.

```yaml
-   repo: https://github.com/pre-commit/precommit
    rev: v1.2.3
    hooks: 
    -   id: check-added-large-files
```

--------------------------------

### Install pre-commit Framework via reticulate

Source: https://lorenzwalthert.github.io/precommit/articles/precommit.html

Install the pre-commit framework into a dedicated conda environment using the reticulate package in R. Ensure reticulate is updated to version 1.14 or later.

```r
reticulate::install_miniconda()
precommit::install_precommit()
```

--------------------------------

### Style Files with styler (Tidyverse Style)

Source: https://lorenzwalthert.github.io/precommit/articles/available-hooks.html

Use the `style-files` hook to format R code according to the tidyverse style guide. Arguments can be passed to `styler::style_file()` using `--key=value` syntax.

```yaml
id: style-files
args: [--scope=spaces, --reindention=specify_reindention('#')]
```

--------------------------------

### Update Pre-commit

Source: https://lorenzwalthert.github.io/precommit/reference/update_precommit.html

This function updates the conda installation of the upstream framework pre-commit. It is only applicable if conda was used for installation. If problems occur, consider removing the `r-precommit` conda environment and reinstalling.

```APIDOC
## update_precommit()

### Description
Updates the conda installation of the upstream framework pre-commit. This does not update the R package `{precommit}` and only works if you choose conda as your installation method. If you have problems updating, we suggest deleting the conda environment `r-precommit` (if you are sure nothing but pre-commit depend on it) and do a fresh installation with `install_precommit()`.

### Value
The exit status of the conda update command (invisible).

### See also
Other executable managers: `install_precommit()`, `uninstall_precommit()`, `version_precommit()`
```

--------------------------------

### Update pre-commit executable

Source: https://lorenzwalthert.github.io/precommit/reference/update_precommit.html

Use this function to update the conda installation of the pre-commit framework. This does not update the R package `{precommit}`. If you encounter problems, consider removing and reinstalling the conda environment.

```r
update_precommit()
```

--------------------------------

### Configure pkgdown Hook

Source: https://lorenzwalthert.github.io/precommit/articles/available-hooks.html

This hook validates entries in your pkgdown configuration file (e.g., _pkgdown.yml) for references and articles. It skips time-consuming build steps and focuses solely on validation. Ensure all development dependencies and pkgdown are installed.

```yaml
id: pkgdown
```

--------------------------------

### Initiate a pre-commit config file

Source: https://lorenzwalthert.github.io/precommit/reference/use_precommit_config.html

This function initiates a `.pre-commit-config.yaml` file in your project root. You can specify a source for the configuration or let it default based on whether your root is a package or project directory. It also provides options to force overwriting an existing file, open the file after creation, and control verbosity.

```APIDOC
## Function: use_precommit_config

### Description
Initiates a `.pre-commit-config.yaml` file in your project root.

### Arguments

* **config_source** (Path or URL) - Path or URL to a `.pre-commit-config.yaml`. If `NULL`, it defaults based on the project type.
* **force** (boolean) - Whether to replace an existing config file. Defaults to `FALSE`.
* **open** (boolean) - Whether or not to open the `.pre-commit-config.yaml` after it's been placed in your repo. Defaults to `TRUE` when in RStudio.
* **verbose** (boolean) - Whether or not to communicate what's happening. Defaults to `FALSE`.
* **root** (Path) - The path to the root directory of your project. Defaults to `here::here()`.

### Value

Character vector of length one with the path to the config file used.

### Examples

```R
if (FALSE) { # \dontrun{
use_precommit_config()
}
}
```
```

--------------------------------

### Open pre-commit configuration file

Source: https://lorenzwalthert.github.io/precommit/reference/open_config.html

Opens the pre-commit configuration file. Specify the project root if it's not the current working directory.

```r
open_config(root = here::here())
```

--------------------------------

### Initiate pre-commit config

Source: https://lorenzwalthert.github.io/precommit/reference/use_precommit_config.html

Initializes a `.pre-commit-config.yaml` file in the project root. It can use a default configuration or one specified by `config_source`. The `force` argument controls overwriting existing files, and `open` determines if the file is opened after creation.

```R
use_precommit_config(
  config_source = getOption("precommit.config_source"),
  force = FALSE,
  open = rstudioapi::isAvailable(),
  verbose = FALSE,
  root = here::here()
)
```

--------------------------------

### Run pre-commit with full path

Source: https://lorenzwalthert.github.io/precommit/articles/ci.html

Execute pre-commit hooks using the full path to the executable, which is necessary if pre-commit is not in your system's PATH.

```bash
/usr/local/bin/pre-commit run --all-files
```

--------------------------------

### Run pre-commit hooks locally

Source: https://lorenzwalthert.github.io/precommit/articles/ci.html

Emulate a CI run by executing all pre-commit hooks on all files in the repository. This helps identify and fix issues before committing.

```bash
pre-commit run --all-files
```

--------------------------------

### Open pre-commit wordlist file

Source: https://lorenzwalthert.github.io/precommit/reference/open_config.html

Opens the WORDLIST file for the check-spelling hook. Specify the project root if it's not the current working directory.

```r
open_wordlist(root = here::here())
```

--------------------------------

### open_config

Source: https://lorenzwalthert.github.io/precommit/reference/open_config.html

Opens the pre-commit configuration file.

```APIDOC
## open_config

### Description
Opens the pre-commit config file.

### Arguments
* **root** (string) - The path to the root directory of your project.

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

### Examples
```R
if (FALSE) { # \dontrun{
open_config()
}
}
```
```

--------------------------------

### Update Pre-commit Framework with Conda

Source: https://lorenzwalthert.github.io/precommit/articles/precommit.html

Use this command if you installed the pre-commit framework using conda. Updates to the pre-commit framework are not released in sync with R or hook revision updates.

```r
precommit::update_precommit()
```

--------------------------------

### Configure precommit Hook Arguments

Source: https://lorenzwalthert.github.io/precommit/articles/available-hooks.html

Specify arguments for hooks using the `args` key in the `.pre-commit-config.yaml` file. Arguments are passed as a list of strings.

```yaml
repos:
-   repo: https://github.com/lorenzwalthert/precommit
    rev: v0.4.3
    hooks:
    -   id: lintr
        args: [--warn_only, --key=value]
```

--------------------------------

### Initialize pre-commit in a Git Repository

Source: https://lorenzwalthert.github.io/precommit/articles/precommit.html

Initialize pre-commit in a Git repository. This command sets up the necessary configuration file (.pre-commit-config.yaml) for running hooks on commit.

```r
# once in every git repo either
# * after cloning a repo that already uses pre-commit or
# * if you want introduce pre-commit to this repo
precommit::use_precommit()
```

--------------------------------

### use_ci() function

Source: https://lorenzwalthert.github.io/precommit/news/index.html

The `use_ci()` function is a new exported function to set up continuous integration for existing repositories.

```APIDOC
## use_ci()

### Description
Sets up continuous integration for existing repositories.

### Arguments
* `ci` (character or NULL) - Specifies the CI service. Defaults to `"native"` (pre-commit.ci). Other options include `"gha"` (GitHub Actions) or `NULL` (no CI).
```

--------------------------------

### Check Pre-commit Version

Source: https://lorenzwalthert.github.io/precommit/articles/precommit.html

Check the version of your pre-commit executable. This is useful for ensuring compatibility and managing updates.

```r
precommit::version_precommit()
```

--------------------------------

### Linter and Styler hook file support

Source: https://lorenzwalthert.github.io/precommit/news/index.html

The `lintr` and `styler` hooks now support additional file types.

```APIDOC
## lintr and styler hooks

### Description
Expanded file type support for `lintr` and `styler` hooks.

### Details
These hooks now also check `.Rmd`, `.Rnw`, and `.Rprofile` files.
```

--------------------------------

### Run a test function signature

Source: https://lorenzwalthert.github.io/precommit/reference/run_test.html

This is the function signature for `run_test`. Use this function to test pre-commit hooks by specifying hook name, file name, expected output, and other parameters.

```R
run_test(
  hook_name,
  file_name = hook_name,
  suffix = ".R",
  std_err = NULL,
  std_out = NULL,
  cmd_args = NULL,
  artifacts = NULL,
  file_transformer = function(files) files,
  env = character(),
  expect_success = is.null(std_err),
  read_only = FALSE
)
```

--------------------------------

### run_test Function

Source: https://lorenzwalthert.github.io/precommit/reference/run_test.html

Tests for the executables used as pre-commit hooks via `entrypoint` in `.pre-commit-config.yaml`. Sets the env variable `R_PRECOMMIT_HOOK_ENV` when running.

```APIDOC
## run_test

### Description
Tests for the executables used as pre-commit hooks via `entrypoint` in `.pre-commit-config.yaml`. Sets the env variable `R_PRECOMMIT_HOOK_ENV` when running.

### Signature
```R
run_test(
  hook_name,
  file_name = hook_name,
  suffix = ".R",
  std_err = NULL,
  std_out = NULL,
  cmd_args = NULL,
  artifacts = NULL,
  file_transformer = function(files) files,
  env = character(),
  expect_success = is.null(std_err),
  read_only = FALSE
)
```

### Arguments

* **hook_name** (character) - The name of the hook in `inst/hooks/exported/`, without file extension.
* **file_name** (character) - The file to test in `tests/in` (without extension). Can be a named vector of length one where the name is the target location relative to the temporary location and the value is the source of the file.
* **suffix** (character) - The suffix of `file_name`.
* **std_err** (character or NULL) - An expected error message. If no error is expected, this can be `NULL`. In that case, the `comparator` is applied.
* **std_out** (character or NULL) - The expected stdout message. If `NULL`, this check is omitted.
* **cmd_args** (character or NULL) - More arguments passed to the file. Pre-commit handles it as described here.
* **artifacts** (character or NULL) - Path with artifact files to copy to the temp directory root where the test is run. If you don't target the root, this can be a named vector of length one where the name is the target location relative to the temporary location and the value is the source of the file.
* **file_transformer** (function) - A function that takes the file names as input and is ran right before the hook script is invoked, returning the path to the files, potentially modified (if renamed). This can be useful if you need to make in-place modifications to the file, e.g. to test hooks that operate on `.Rprofile`. You can't have different names for different tests on that file because it must be called `.Rprofile` all the time. And R CMD check seems to remove hidden files, so we must also rename it. The transformation is also applied to a temp copy of the reference file before a comparison is made.
* **env** (character) - The environment variables to set with `base::system2()`.
* **expect_success** (logical) - Whether or not an exit code 0 is expected. This can be derived from `std_err`, but sometimes, non-empty stderr does not mean error, but just a message.
* **read_only** (logical) - If `TRUE`, then assert that no new files were created. Additionally, if `artifacts` are not `NULL`, then assert that hook did not modify the artifacts.

### Details
Two potential outcomes of a hooks are pass or fail. This is reflected on the level of the executable: Fail means the executable fails or the file is changed. Pass means the executable succeeds and the file is unchanged. We check if the executable passes as follows:
  * If we expect success (by setting `std_err` to `NULL`), we make sure nothing was written to sterr and the file content does not change.
  * If we expect failure, it can be due to changed file or due to failed executable. To check for failed executable, we set `std_err` to the message we expect. To check changed file content, we set `std_err` to `NA`.
```

--------------------------------

### Roxygenize Hook Dependencies

Source: https://lorenzwalthert.github.io/precommit/reference/snippet_generate.html

Paste this code into your `.pre-commit-config.yaml` file to add the necessary dependencies for the roxygenize hook.

```yaml
additional-deps-roxygenize: Code to paste into `.pre-commit-config.yaml` for the additional dependencies required by the roxygenize hook.
```

--------------------------------

### Uninstall pre-commit from a repository or system

Source: https://lorenzwalthert.github.io/precommit/reference/uninstall_precommit.html

Use this function to remove pre-commit. Specify 'repo' to remove it only from the current project, or 'user' to remove it globally. The 'ask' argument controls confirmation prompts.

```r
uninstall_precommit(scope = "repo", ask = "user", root = here::here())
```

```r
uninstall_precommit()
```

--------------------------------

### Use Tidy Description Hook Arguments

Source: https://lorenzwalthert.github.io/precommit/articles/available-hooks.html

Specifies the root directory for the use-tidy-description hook. Defaults to the current directory if not explicitly set.

```yaml
id: use-tidy-description
args: [--root=<R package root>]
```

--------------------------------

### Run pre-commit autoupdate

Source: https://lorenzwalthert.github.io/precommit/reference/autoupdate.html

Runs `pre-commit autoupdate` on the specified project root. The function returns the exit status of the command.

```r
autoupdate(root = here::here())
```

--------------------------------

### Configure lintr Hook

Source: https://lorenzwalthert.github.io/precommit/articles/available-hooks.html

Use this hook to run lintr::lint() on R files. Set 'verbose: true' to see lint errors as they appear. Other arguments are not supported; configure lintr via a .lintr file.

```yaml
id: lintr
args: [--warn_only]
verbose: true
```

--------------------------------

### Configure styler Ignore Markers

Source: https://lorenzwalthert.github.io/precommit/articles/available-hooks.html

Use `ignore-start` and `ignore-stop` arguments to define custom markers for ignoring code blocks during styling with `styler`, useful for restoring older behavior.

```yaml
id: style-files
args: [--ignore-start="^# styler: on$", --ignore-stop="^# styler: off$"]
```

--------------------------------

### Derive pre-commit executable path

Source: https://lorenzwalthert.github.io/precommit/reference/path_derive_precommit_exec.html

Call this function to find the path to the pre-commit executable. Returns an empty string if the executable cannot be found.

```r
path_derive_precommit_exec()
```

--------------------------------

### Derive pre-commit executable path

Source: https://lorenzwalthert.github.io/precommit/reference/path_derive_precommit_exec_path.html

Tries to derive the `pre-commit` executable from the `$PATH`. Returns `""` if no executable is found.

```APIDOC
## path_derive_precommit_exec_path()

### Description
Tries to derive the `pre-commit` executable from the `$PATH`. Returns `""` if no executable is found.

### Method
```
path_derive_precommit_exec_path()
```
```

--------------------------------

### roxygenize hook changes

Source: https://lorenzwalthert.github.io/precommit/news/index.html

The `roxygenize` hook now requires explicit listing of package dependencies.

```APIDOC
## roxygenize hook

### Description
Changes related to the `roxygenize` hook.

### Details
Since hooks run in a virtual environment and the `roxygenize` hook runs `pkgload::load_all()`, all package dependencies must be listed in the `additional_dependencies` field in `.pre-commit-config.yaml`. The system will prompt to add missing dependencies. `precommit::snippet_generate("additional-deps-roxygenize")` can generate the necessary code.
```

--------------------------------

### path_precommit_exec

Source: https://lorenzwalthert.github.io/precommit/reference/path_precommit_exec.html

`path_precommit_exec()` reads the R option `precommit.executable` to find the pre-commit executable. The `check_if_exists` argument determines if the path should be verified to exist.

```APIDOC
## path_precommit_exec

### Description
Reads the R option `precommit.executable` to locate the pre-commit executable.

### Arguments
* **check_if_exists** (boolean) - Whether or not to make sure the returned path also exists.

### Value
A character vector of length one with the path to the pre-commit executable.

### Examples
```R
if (FALSE) { # \dontrun{
path_precommit_exec()
}
```
```

--------------------------------

### Roxygenize Hook Arguments

Source: https://lorenzwalthert.github.io/precommit/articles/available-hooks.html

Specifies the root directory for the roxygenize hook. Defaults to the current directory if not explicitly set.

```yaml
id: roxygenize
args: [--root=<R package root>]
```

--------------------------------

### style-files hook arguments

Source: https://lorenzwalthert.github.io/precommit/news/index.html

The `style-files` hook has been updated to include new arguments and support more of the `style_file()` API.

```APIDOC
## style-files hook

### Description
Enhancements to the `style-files` hook.

### Arguments
* `--cache-root` - Passed to `options(styler.cache_root = ...)`.
* Supports full `style_file()` API arguments like `--scope=spaces` via `args:` in `.pre-commit-config.yaml`.

### Details
Both `style-files` and `roxygenize` hooks now warn if no permanent R.cache cache is set up. This warning can be silenced with the hook argument `--no-warn-cache`.
```

--------------------------------

### use_precommit() function

Source: https://lorenzwalthert.github.io/precommit/news/index.html

The `use_precommit()` function is used to set up pre-commit hooks in an R project. It now includes a `ci` argument to configure continuous integration.

```APIDOC
## use_precommit()

### Description
Sets up pre-commit hooks for an R project.

### Arguments
* `ci` (character or NULL) - Sets up continuous integration. Allowed values are: 
    - `"native"` (default): for pre-commit.ci
    - `"gha"`: for GitHub Actions
    - `NULL`: for no CI

### Details
The default behavior for `ci` can be governed by the R option `precommit.ci`.
```

--------------------------------

### open_wordlist

Source: https://lorenzwalthert.github.io/precommit/reference/open_config.html

Opens the WORDLIST file for the check-spelling hook.

```APIDOC
## open_wordlist

### Description
Opens the the WORDLIST file for the check-spelling hook in inst/WORDLIST.

### Arguments
* **root** (string) - The path to the root directory of your project.

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

### Examples
```R
if (FALSE) { # \dontrun{
open_wordlist()
}
}
```
```

--------------------------------

### autoupdate

Source: https://lorenzwalthert.github.io/precommit/reference/autoupdate.html

Runs `pre-commit autoupdate` to update your project's hooks.

```APIDOC
## autoupdate

### Description
Runs `pre-commit autoupdate` to update your project's hooks.

### Method
`autoupdate(root = here::here())`

### Parameters
#### Path Parameters
* **root** (string) - Optional - The path to the root directory of your project.

### Value
The exit status from `pre-commit autoupdate` (invisibly).

### Examples
```R
if (FALSE) { # \dontrun{
autoupdate()
}
}
```
```

--------------------------------

### Retrieve pre-commit executable version

Source: https://lorenzwalthert.github.io/precommit/reference/version_precommit.html

This function retrieves the version of the pre-commit executable that is currently being used.

```APIDOC
## version_precommit()

### Description
Retrieves the version of the pre-commit executable used.

### Usage
```R
version_precommit()
```

### See Also
Other executable managers: `install_precommit()`, `uninstall_precommit()`, `update_precommit()`
```

--------------------------------

### Roxygenize Hook with Additional Dependencies

Source: https://lorenzwalthert.github.io/precommit/articles/available-hooks.html

Configures the roxygenize hook to include additional dependencies, such as r-lib/pkgapi, for roclets specified in DESCRIPTION.

```yaml
id: roxygenize
additional_dependencies:
- r-lib/pkgapi
```

--------------------------------

### snippet_generate

Source: https://lorenzwalthert.github.io/precommit/reference/snippet_generate.html

Generates and optionally opens a `.pre-commit-config.yaml` file with specified snippets. Currently supports 'additional-deps-roxygenize'.

```APIDOC
## snippet_generate

### Description
Utility function to generate code snippets for pre-commit configuration.

### Arguments

* `snippet` (string) - Name of the snippet to generate. Currently supported: `additional-deps-roxygenize`.
* `open` (boolean) - Whether or not to open the `.pre-commit-config.yaml`. Defaults to `TRUE` when working in RStudio.
* `root` (string) - The path to the root directory of your project. Defaults to `here::here()`.

### Details
Currently supported snippets:

* `additional-deps-roxygenize`: Code to paste into `.pre-commit-config.yaml` for the additional dependencies required by the roxygenize hook.
```

--------------------------------

### Uninstall Pre-commit Hooks

Source: https://lorenzwalthert.github.io/precommit/articles/precommit.html

Commands to uninstall pre-commit hooks. Use the first for the current repository and the second to remove the conda executable.

```r
uninstall_precommit("repo") # just for the repo you are in.
uninstall_precommit("user") # remove the pre-commit conda executable.
```

--------------------------------

### Generate Snippet Function

Source: https://lorenzwalthert.github.io/precommit/reference/snippet_generate.html

Use this function to generate code snippets for your pre-commit configuration. It supports specific snippet names like 'additional-deps-roxygenize'. The default behavior opens the configuration file in RStudio if available.

```R
snippet_generate(
  snippet = "",
  open = rstudioapi::isAvailable(),
  root = here::here()
)
```

--------------------------------

### Uninstall Pre-commit Hooks

Source: https://lorenzwalthert.github.io/precommit/articles/FAQ.html

Use this command to remove pre-commit hooks from your local repository if you no longer wish to use them.

```r
precommit::uninstall_precommit()
```

--------------------------------

### parsable-R hook update

Source: https://lorenzwalthert.github.io/precommit/news/index.html

The `parsable-R` hook can now parse `.Rmd` files in addition to `.R` files.

```APIDOC
## parsable-R hook

### Description
Extended parsing capabilities for the `parsable-R` hook.

### Details
This hook can now parse `.Rmd` files, broadening its utility beyond just `.R` files.
```