usethis is a workflow package: it automates repetitive tasks that arise during project setup and development, both for R packages and non-package projects.
Install the released version of usethis from CRAN:
install.packages("usethis")Or install the development version from GitHub with:
# install.packages("pak")
pak::pak("r-lib/usethis")Most use_*() functions operate on the active project: literally, a
directory on your computer. If youβve just used usethis to create a new
package or project, that will be the active project. Otherwise, usethis
verifies that current working directory is or is below a valid project
directory and that becomes the active project. Use proj_get() or
proj_sitrep() to manually query the project and read more in the
docs.
A few usethis functions have no strong connections to projects and will expect you to provide a path.
usethis is quite chatty, explaining what itβs doing and assigning you
tasks. β indicates something usethis has done for you. β indicates
that youβll need to do some work yourself.
Below is a quick look at how usethis can help to set up a package. But remember, many usethis functions are also applicable to analytical projects that are not packages.
library(usethis)
# Create a new package -------------------------------------------------
path <- file.path(tempdir(), "mypkg")
create_package(path)
#> β Creating '/tmp/RtmpMuqeSm/mypkg/'.
#> β Setting active project to "/private/tmp/RtmpMuqeSm/mypkg".
#> β Creating 'R/'.
#> β Writing 'DESCRIPTION'.
#> Package: mypkg
#> Title: What the Package Does (One Line, Title Case)
#> Version: 0.0.0.9000
#> Authors@R (parsed):
#> * First Last <[email protected]> [aut, cre] (YOUR-ORCID-ID)
#> Description: What the package does (one paragraph).
#> License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
#> license
#> Encoding: UTF-8
#> Roxygen: list(markdown = TRUE)
#> RoxygenNote: 7.3.1
#> β Writing 'NAMESPACE'.
#> β Setting active project to "<no active project>".
# only needed since this session isn't interactive
proj_activate(path)
#> β Setting active project to "/private/tmp/RtmpMuqeSm/mypkg".
#> β Changing working directory to '/tmp/RtmpMuqeSm/mypkg/'
# Modify the description ----------------------------------------------
use_mit_license("My Name")
#> β Adding "MIT + file LICENSE" to 'License'.
#> β Writing 'LICENSE'.
#> β Writing 'LICENSE.md'.
#> β Adding "^LICENSE\\.md$" to '.Rbuildignore'.
use_package("ggplot2", "Suggests")
#> β Adding ggplot2 to 'Suggests' field in DESCRIPTION.
#> β Use `requireNamespace("ggplot2", quietly = TRUE)` to test if ggplot2 is
#> installed.
#> β Then directly refer to functions with `ggplot2::fun()`.
# Set up other files -------------------------------------------------
use_readme_md()
#> β Writing 'README.md'.
#> β Update 'README.md' to include installation instructions.
use_news_md()
#> β Writing 'NEWS.md'.
use_test("my-test")
#> β Adding testthat to 'Suggests' field in DESCRIPTION.
#> β Adding "3" to 'Config/testthat/edition'.
#> β Creating 'tests/testthat/'.
#> β Writing 'tests/testthat.R'.
#> β Writing 'tests/testthat/test-my-test.R'.
#> β Edit 'tests/testthat/test-my-test.R'.
x <- 1
y <- 2
use_data(x, y)
#> β Adding R to 'Depends' field in DESCRIPTION.
#> β Creating 'data/'.
#> β Setting 'LazyData' to "true" in 'DESCRIPTION'.
#> β Saving "x" and "y" to "data/x.rda" and "data/y.rda".
#> β Document your data (see <https://r-pkgs.org/data.html>).
# Use git ------------------------------------------------------------
use_git()
#> β Initialising Git repo.
#> β Adding ".Rproj.user", ".Rhistory", ".Rdata", ".httr-oauth", ".DS_Store", and
#> ".quarto" to '.gitignore'.Please note that the usethis project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.