diff --git a/DESCRIPTION b/DESCRIPTION index 60a75fdfa..bf5e78dbb 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -32,6 +32,7 @@ Suggests: styler (>= 1.2), testthat, tic, + versions, yaml VignetteBuilder: knitr diff --git a/tests/testthat.R b/tests/testthat.R index 8b445d1f2..92a0e12c6 100644 --- a/tests/testthat.R +++ b/tests/testthat.R @@ -1,4 +1,10 @@ library(testthat) library(precommit) +versions <- versions::available.versions("desc") + + +if (max(as.package_version(versions$desc$version)) > "1.2") { + rlang::abort("newer version of desc on CRAN. Adapt the warning and maybe add minimal version requirement?") +} test_check("precommit") diff --git a/vignettes/available-hooks.Rmd b/vignettes/available-hooks.Rmd index 7d9c0a069..af2fc1642 100644 --- a/vignettes/available-hooks.Rmd +++ b/vignettes/available-hooks.Rmd @@ -1,5 +1,5 @@ --- -title: "Available hooks" +title: "Available Hooks" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{available-hooks} @@ -7,43 +7,176 @@ vignette: > %\VignetteEncoding{UTF-8} --- -This repo contains a collection of git pre-commit hooks to use with -[pre-commit.com](https://pre-commit.com). Currently, this repo hosts: +Below is a comprehensive list with all hooks from {precommit} as well well as +their arguments or flags, if they take any. Other repos also host hooks, many +are listed [here](https://pre-commit.com/hooks.html). -* `style-files`: A hook to style files with [styler](https://styler.r-lib.org). - Only commit code corresponding to the tidyverse style guide. To customize, see - `vignette("available-hooks")`. +# File modification -* `readme-rmd-rendered`: Make sure `README.Rmd` hasn't been edited more recently - than `README.md`, i.e. remind you to render the `.Rmd` to `.md` before - committing. +Some hooks will fail without changing the files you want to commit, like the +`lintr` hook - and you need to make manual changes for the hook to pass on the +next attempt. Other hooks like the `styler` hook write to files, and if that +changes the file, the hook will fail, but this means you won't need to modify +the file manually, just stage the changes and try to commit again. Below, we +indicate for every hook if it modifies files or not. -* `parsable-R`: Checks if your `.R` files are "valid" R code. +# Arguments -* `no-browser-statement`: Guarantees you that you don't accidentally commit code - with a `browser()` statement in it. +Arguments are specified as described in the [pre-commit.com +documentation](https://pre-commit.com/#passing-arguments-to-hooks), e.g. we can +set the argument `style_pkg` to `styler` and `style_fun` to `tidyverse_style` +for the hook `style-files` like this: -* `spell-check`: Checks spelling with `spelling::spell_check_files()`. Excluded - are R and python scripts as well as .gitignore. To customize, see the vignette - *Hook arguments*. +```{r, echo = FALSE, output = "asis", comment = "", message = FALSE} +library(magrittr) +config <- yaml::read_yaml(system.file("pre-commit-config.yaml", package = "precommit", mustWork = TRUE)) +rev <- purrr::imap(config$repos, function(x, y) { + if (x$repo == "https://github.com/lorenzwalthert/precommit") { + return(x$rev) + } +}) %>% + purrr::compact() %>% + unlist() +cat(glue::glue(" +repos: +- repo: https://github.com/lorenzwalthert/precommit + rev: {rev} + hooks: + - id: style-files + args: [--style_pkg=styler, --style_fun=tidyverse_style] +")) +``` -* `roxygenize`: A hook to run `roxygen2::roxygenize()`. Makes sure you commit - your `.Rd` changes with the source changes. +# Hooks -* `deps-in-desc`: Checks if packages used with the `pkgname::fun()` syntax are - listed in your DESCRIPTION file. +## `style-files` -* `use-tidy-description`: A hook to run `usethis::use_tidy_description()` to - ensure dependencies are ordered alphabetically and fields are in standard - order. +A hook to style files with [styler](https://styler.r-lib.org). Only commit code +corresponding to the tidyverse style guide. Set argument `style_pkg` and +`style_fun` if you want to use another style guide than the tidyverse style +guide. -* `lintr`: A hook to run `lintr::lint()` to check that R files are lint free. +``` + id: style-files + args: [--style_pkg=, --style_fun=] +``` -* `codemeta-description-updated`: Make sure `DESCRIPTION` hasn't been edited - more recently than `codemeta.json`, i.e. remind you to run - `codemetar::write_codemeta()` in order to keep `codemeta.json` in sync with - `DESCRIPTION`. +This hook modifies files. -Other repos also host hooks, many are listed -[here](https://pre-commit.com/hooks.html). +## `readme-rmd-rendered` + +Make sure `README.Rmd` hasn't been edited more recently than `README.md`, i.e. +remind you to render the `.Rmd` to `.md` before committing. + +This hook does not modify files. + +## `parsable-R` + +Checks if your `.R` files are "valid" R code by checking if running `parse()` on +it returns an error. + +This hook does not modify files. + +## `no-browser-statement` + +Guarantees you that you don't accidentally commit code with a `browser()` +statement in it. + +This hook does not modify files. + +## `spell-check` + +Checks spelling with `spelling::spell_check_files()`. Excluded are R and python +scripts as well as `.gitignore` and similar. To be precise, files matching the +following regex are excluded by default (as of `r paste0("v", +desc::desc_get_version())`): + +```{r, echo = FALSE, comment = ""} +extract_spell_check_regex <- function() { + yaml::read_yaml(here::here(".pre-commit-hooks.yaml")) %>% + purrr::keep(~ .x$id == "spell-check") %>% + magrittr::extract2(1) %>% + magrittr::extract2("exclude") +} + +cat(extract_spell_check_regex()) +``` + +Argument `ignore_files` takes a regular expression matched with `base::grep()` +to ignore further files from the hook. Argument `lang` is passed to +`spelling::spell_check_files()`. + +``` +id: spell-check +args: [--ignore_files=, --lang=] +``` + +This hook does not modify files. It will add all words not found in the +dictionary to `inst/WORDLIST`, assuming they were spelled correctly but were not +in the dictionary. An example might be "RStudio". The hook error message will +contain all words written to `inst/WORDLIST`, so if there were really some +typos, make sure to fix them and remove them from `inst/WORDLIST`. If there were +not typos, or you fixed all, stage `inst/WORDLIST` and this time, the commit +should pass. + +## `roxygenize` + +A hook to run `roxygen2::roxygenize()`. Makes sure you commit your `.Rd` changes +with the source changes. + +This hook modifies files. + +## `deps-in-desc` + +Checks if packages used with the `pkgname::fun()` syntax are listed in your +DESCRIPTION file. Flag `allow_private_imports` lets the user specify that +private imports into the package namespace are tolerable, e.g. `somepkg:::x()`. +Flag not set by default, i.e. the hook will fail if such a call is found. + +``` +id: deps-in-desc args: [--allow_private_imports] +``` + +This hook does not modify the file `DESCRIPTION` because the user should decide +for each package if it should go to `Imports:` or `Suggests:`, which can be done +easily with `usethis::use_package()`. For those who use +`usethis::use_package()`: As long as the CRAN version of the dependency {desc} +is `v1.2.0`, we recommend you to install the GitHub version because otherwise, +the new dependencies won't be added in alphabetical order and after adding a +dependency, `use-tidy-description` will fail in most cases +(#85)[https://github.com/r-lib/desc/pull/85]. + +## `use-tidy-description` + +A hook to run `usethis::use_tidy_description()` to ensure dependencies are +ordered alphabetically and fields are in standard order. + +This hook does modify the file `DESCRIPTION`. + +## `lintr` + +A hook to run `lintr::lint()` to check that R files are lint free. Argument +`warning_only` changes the behavior of the pre-commit to be non-blocking. You +should set this with the field `verbose: true`. + +``` +id: lintr +args: [--warn_only] +verbose: true +``` + +When configured this way, lintr prints lint errors as they appear. Other +arguments are not supported. Instead, `lintr` config should be specified in a +`.lintr` config file in Debian Control Field Format as specified in the +[`.lintr` documentation](https://github.com/jimhester/lintr#project-configuration). + +This hook does not modify any file. + +## `codemeta-description-updated` + +Make sure `DESCRIPTION` hasn't been edited more recently than `codemeta.json`, +i.e. remind you to run `codemetar::write_codemeta()` in order to keep +`codemeta.json` in sync with `DESCRIPTION`. + +This hook does not modify any file. diff --git a/vignettes/hook-arguments.Rmd b/vignettes/hook-arguments.Rmd deleted file mode 100644 index 8f7b2d4ab..000000000 --- a/vignettes/hook-arguments.Rmd +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "Hook arguments" -output: rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{hook-arguments} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -Arguments are specified as described in the [pre-commit.com -documentation](https://pre-commit.com/#passing-arguments-to-hooks), e.g. the -arguments for the `style-files` hook can be set like this: - -```{r, echo = FALSE, output = "asis", comment = ""} -library(magrittr) -config <- yaml::read_yaml(system.file("pre-commit-config.yaml", package = "precommit", mustWork = TRUE)) -rev <- purrr::imap(config$repos, function(x, y) { - if (x$repo == "https://github.com/lorenzwalthert/precommit") { - return(x$rev) - } -}) %>% - purrr::compact() %>% - unlist() -cat(glue::glue(" -repos: -- repo: https://github.com/lorenzwalthert/precommit - rev: {rev} - hooks: - - id: style-files - args: [--style_pkg=styler, --style_fun=tidyverse_style] -")) -``` - -The following hooks take arguments: - -* `style-files`: Argument `style_pkg` and `style_fun` if you want to use another - style guide than the default. Defaults: `styler` for `style_pkg` and - `tidyverse_style` for `style_fun`. - ``` - id: style-files - args: [--style_pkg=styler, --style_fun=tidyverse_style] - ``` -* `spell-check`: Argument `ignore_files` takes a regular expression matched with - `base::grep()` to ignore further files from the hook. Argument `lang` is - passed to `spelling::spell_check_files()`. - ``` - id: spell-check - args: [--ignore_files=, --lang=] - ``` - -* `lintr`: Argument `warning_only` changes the behavior of the pre-commit to - be non-blocking. You should set this with the field `verbose: true`. - - ``` - id: lintr - args: [--warn_only] - verbose: true - ``` - When configured this way, lintr prints lint errors as they appear. Other - arguments are not supported. Instead, `lintr` config should be specified in a - `.lintr` config file in Debian Control Field Format as specified in the - [`.lintr` - documentation](https://github.com/jimhester/lintr#project-configuration). - -* `deps-in-desc`: Flag `allow_private_imports` lets the user specify that - private imports into the package namespace are tolerable, e.g. - `somepkg:::x()`. Flag not set by default, i.e. the hook will fail if - such a call is found. - ``` - id: deps-in-desc - args: [--allow_private_imports] - ``` diff --git a/vignettes/manual-installation.Rmd b/vignettes/manual-installation.Rmd index 011df85a4..244a9e561 100644 --- a/vignettes/manual-installation.Rmd +++ b/vignettes/manual-installation.Rmd @@ -87,7 +87,7 @@ cat(string) The `repo` key points to the place where the source code of the hooks are stored, not the repo you want to apply them to. -Some hooks also take arguments, see `vignette("hook-arguments")`. +Some hooks also take arguments, see `vignette("available-hooks")`. If you want to see the file `.pre-commit-config.yaml` in RStudio, you have to enable "Show Hidden Files" in the *Files* Pane of RStudio under *More*.