Automate package and project setup tasks that are otherwise performed manually. This includes setting up unit testing, test coverage, continuous integration, Git, 'GitHub', licenses, 'Rcpp', 'RStudio' projects, and more.
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:
Or install the development version from GitHub with:
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_sitrep() to manually query the project and read more in the
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
✔ indicates something usethis has done for you.
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 -------------------------------------------------tmp <- file.path(tempdir(), "mypkg")create_package(tmp)#> ✔ Setting active project to '/private/var/folders/vr/gzrbtprx6ybg85y5pvwm1ct40000gn/T/RtmpGwzXO5/mypkg'#> ✔ Creating 'R/'#> ✔ Creating 'man/'#> ✔ Writing 'DESCRIPTION'#> ✔ Writing 'NAMESPACE'# Modify the description ----------------------------------------------use_mit_license("My Name")#> ✔ Setting License field in DESCRIPTION to 'MIT + file LICENSE'#> ✔ Writing 'LICENSE.md'#> ✔ Adding '^LICENSE\\.md$' to '.Rbuildignore'#> ✔ Writing 'LICENSE'use_package("MASS", "Suggests")#> ✔ Adding 'MASS' to Suggests field in DESCRIPTION#> ● Use `requireNamespace("MASS", quietly = TRUE)` to test if package is installed#> ● Then use `MASS::fun()` to refer to functions.use_dev_package("callr")#> ✔ Adding 'callr' to Imports field in DESCRIPTION#> ✔ Adding 'r-lib/callr' to Remotes field in DESCRIPTION# Set up various packages ---------------------------------------------use_roxygen_md()#> ✔ Setting Roxygen field in DESCRIPTION to 'list(markdown = TRUE)'#> ✔ Setting RoxygenNote field in DESCRIPTION to '6.1.0'#> ● Run `devtools::document()`use_rcpp()#> ✔ Adding 'Rcpp' to LinkingTo field in DESCRIPTION#> ✔ Adding 'Rcpp' to Imports field in DESCRIPTION#> ✔ Creating 'src/'#> ✔ Adding '*.o', '*.so', '*.dll' to 'src/.gitignore'#> ● Include the following roxygen tags somewhere in your package#> #' @useDynLib mypkg, .registration = TRUE#> #' @importFrom Rcpp sourceCpp#> NULL#> ● Run `devtools::document()`use_revdep()#> ✔ Creating 'revdep/'#> ✔ Adding '^revdep$' to '.Rbuildignore'#> ✔ Adding 'checks', 'library', 'checks.noindex', 'library.noindex', 'data.sqlite', '*.html' to 'revdep/.gitignore'#> ✔ Writing 'revdep/email.yml'#> ● Run checks with `revdepcheck::revdep_check(num_workers = 4)`# Set up other files -------------------------------------------------use_readme_md()#> ✔ Writing 'README.md'use_news_md()#> ✔ Writing 'NEWS.md'use_test("my-test")#> ✔ Adding 'testthat' to Suggests field in DESCRIPTION#> ✔ Creating 'tests/testthat/'#> ✔ Writing 'tests/testthat.R'#> ✔ Writing 'tests/testthat/test-my-test.R'x <- 1y <- 2use_data(x, y)#> ✔ Creating 'data/'#> ✔ Saving 'x', 'y' to 'data/x.rda', 'data/y.rda'# Use git ------------------------------------------------------------use_git()#> ✔ Initialising Git repo#> ✔ Adding '.Rhistory', '.RData', '.Rproj.user' 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.
All usethis file system operations now use the fs package (#177). This should not change how usethis functions, but users may notice these features of fs-mediated paths:
/is the path separator and there are never multiple or trailing
C:\Users\username(typical of Unix-oriented tools, like Git and ssh; also matches Python), as opposed to
C:\Users\username\Documents(R's default on Windows). Read more in
These changes make it easier for others to extend usethis, i.e. to create workflow packages specific to their organization, or to use usethis in other packages.
proj_path() is newly exported. Use it to build paths within the active project. Like
proj_set(), it is not aimed at end users, but rather for use in extension packages. End users should use rprojroot or its simpler companion, here, to programmatically detect a project and
build paths within it (#415, #425).
write_union() are newly exported helpers. They are mostly for internal use, but can also be useful in packages that extend or customize usethis (#344, #366, #389).
use_template() no longer errors when a user chooses not to overwrite an existing file and simply exits with confirmation that the file is unchanged (#348, #350, @boshek).
getOption("usethis.quiet") is consulted when printing user-facing messages. Set this option to
TRUE to suppress output, e.g., to use usethis functions quietly in another package. For example, use
withr::local_options(list(usethis.quiet = TRUE)) in the calling function (#416, #424).
proj_sitrep() reports current working directory, the active usethis project, and the active RStudio Project. Call this function if things seem weird and you're not sure what's wrong or how to fix it. Designed for interactive use and debugging, not for programmatic use (#426).
use_tibble() does minimum setup necessary for a package that returns or exports a tibble. For example, this guarantees a tibble will print as a tibble (#324 @martinjhnhadley).
use_logo() resizes and adds a logo to a package (#358, @jimhester).
use_spell_check() adds a whitelist of words and a unit test to spell check package documentation during
R CMD check (#285 @jeroen).
usethis has a new logo! (#429)
use_course() reports progress during download (#276, #380).
use_git() only makes an initial commit of all files if user gives explicit consent (#378).
repo argument is renamed to
repo_spec, since it takes input of the form "OWNER/REPO" (#376).
use_depsy_badge() is defunct. The Depsy project has officially concluded and is no longer being maintained (#354).
use_github() fails earlier, with a more informative message, in the absence of a GitHub personal access token (PAT). Also looks for the PAT more proactively in the usual environment variables (i.e., GITHUB_PAT, GITHUB_TOKEN) (#320, #340, @cderv).
The logic for setting DESCRIPTION fields in
use_description() got a Spring Cleaning. Fields directly specified by the user take precedence, then the named list in
getOption("usethis.description") is consulted, and finally defaults built into usethis.
use_description_defaults() is a new function that reveals fields found in options and built into usethis. Options specific to one DESCRIPTION field, e.g.
devtools.desc.license, are no longer supported. Instead, use a single named list for all fields, preferably stored in an option named
"devtools.desc" is still consulted for backwards compatibility). (#159, #233, #367)
New Imports: fs, glue, utils
No longer in Imports: backports, httr, rematch2, rmarkdown (moved to Suggests), styler (moved to Suggests)
usethis has a website: http://usethis.r-lib.org (#217). It includes an article with advice on system setup, for usethis and for R development more generally.
edit_*() functions now return the target path, invisibly (#255).
edit_git_ignore(scope = "user") prefers
~/.gitignore, but detects an existing
~/.gitignore_global, if it exists. If a new global gitignore file is created, it is created as
~/.gitignore and recorded in user's git config as the
create_from_github() gains several arguments and new functionality. The
protocol argument lets user convey whether remote URLs should be ssh or https. In the case of "fork and clone", the original repo is added as
upstream remote. It is now possible -- although rarely necessary -- to directly specify the GitHub PAT, credentials (in git2r form), and GitHub host (#214, #214, #253).
use_github_labels() can create or update the colour of arbitrary GitHub issue labels, defaulting to a set of labels and colours used by the tidyverse packages, which are now exposed via
tidy_labels(). That set now includes the labels "good first issue" and "help wanted" (#168, #249).
appveyor_info() no longer reverses the repo's URL and image link. Corrects the markdown produced by
use_appveyor_badge() (#240, @llrs).
use_cran_badge() uses an HTTPS URL for the CRAN badge image (#235, @jdblischak).
create_project() return a normalized path, even if target directory does not pre-exist (#227, #228).
use_git_config() can set user's Git name or email, globally or locally in a project/repo (#267).
browse_github_pat() goes to the webpage where a GitHub user can create a personal access token (PAT) for the GitHub API. If the user configures a PAT, they can use functions like
use_github() to easily create and connect GitHub repos to local projects. (#248, #257, @jeroen, via @jennybc).
use_version() increments the version of the active package, including an interactive chooser.
use_dev_version() is now a special case wrapper around this. (#188, #223, @EmilHvitfeldt).
use_tidy_github() creates a standard set of files that make a GitHub repository more navigable for users and contributors: an issue template, contributing guidelines, support documentation, and a code of conduct. All are now placed in a
.github/ subdirectory (#165, @batpigandme).
use_bioc_badge creates a Bioconductor badge that links to the build report (#271, @LiNk-NY).
use_binder_badge() creates a badge indicating the repository can be launched in an executable environment via Binder (#242, @uribo).
use_course() downloads a folder's worth of materials from a ZIP file, with deliberate choices around the default folder name and location. Developed for use at the start of a workshop. Helps participants obtain materials from, e.g., a DropBox folder or GitHub repo (#196).
use_blank_slate() provides a way to opt in to an RStudio workflow where the user's workspace is neither saved nor reloaded between R sessions. Automated for
scope = "project". Provides UI instructions for
scope = "user", for now (#139).
use_tidy_style() styles an entire project according to http://style.tidyverse.org (#72, #197 @lorenzwalthert).
GitHub conventions common to tidyverse packages are enacted by
use_tidy_support() (@batpigandme, #143, #166).
New projects that don't exhibit other obvious criteria for being a "project" will include a sentinel, empty file named
.here, so they can be recognized as a project.
Project launching and switching works on RStudio server (#115, #129).
use_template() is newly exported, so that other packages can provide
templating functions using this framework (@ijlyttle #120).
use_readme_md() work, in a similar fashion, for projects that are and are not a package (#131, #135).
use_readme_rmd() once again creates a pre-commit git hook, to help keep
README.md in sync (@PeteHaitch #41).
Substantial increase in unit test coverage.
browse_travis() open useful websites related to
the current project or a named package. (#96, #103).
create_from_github() creates a project from an existing GitHub
repository, forking if needed (#109).
use_cc0_license() applies a CC0 license, particularly appropriate for data
use_lifecycle_badge() creates a badge describing current stage in
project lifecycle (#48).
use_pkgdown() creates the basics needed for a
pkgdown website (#88).
use_r("foo") creates and edit
R/foo.R file. If you have a test file open,
use_r() will open the corresponding
.R file (#105).
use_tidy_versions() sets minimum version requirement for all dependencies.
use_dev_version() now correctly updates the
Version field in a package
description file. (@tjmahr, #104)
use_revdep() now also git-ignores the SQLite database (#107).
use_tidy_eval() has been tweaked to reflect current guidance (#106)
This is a new package that extracts out many functions that previously lived in devtools, as well as providing more building blocks so you can create your own helpers. As well as the many new helpers listed below, there are three main improvements to the package:
usethis is gradually evolving towards supporting more general R "projects", not just packages. This is still a work in progress, so please let me know if you use a function that you think should work with projects but doesn't. You can also try out the new
create_project() which creates a basic RStudio project.
The concept of the working directory and the "base path" have been refined. Rather than using an argument to specify the active project, all
use_ functions now use a global active project setting, as returned by
proj_get(). This is cached throughout a session, although it will be updated by
create_project(). You'll now get an clear error if you attempt to
use_something() outside of a project, and
create_something() will warn if you're trying to create inside an existing project.
The output from all usethis commands has been reviewed to be informative but not overwhelming. usethis takes advantage of colour (using crayon and RStudio 1.1) to help chunk the output and clearly differentiate what you need to do vs. what has been done for you.
use_apl2_license() if you want to use the Apache 2.0 license.
use_depsy_badge() allows including a Depsy badge (@gvegayon, #68).
use_dev_package() works like
use_package() but also adds the
repo to the
Remotes field (#32).
use_github_labels() will automatically set up a standard set of labels,
optionally removing the default labels (#1).
use_pipe() creates a template to use magrittr's
%>% in your package (#15).
use_tidy_ci() which sets up travis and codecov using the tidyverse
use_tidy_description() puts description fields in a standard order
and alphabetises dependencies.
use_tidy_eval() imports and re-exports the recommend set of tidy eval
helpers if your package uses tidy eval (#46).
use_usethis() opens your
.Rprofile and gives you the code to copy
and paste in.
A new class of functions make it easy to edit common config files:
use_coverage("codecov") now sets a default threshold of 1% to try and
reduce false positives (#8).
use_description() now sets
ByteCompile: true so you can benefit from
the byte compiler (#29)
The license functions (
use_gpl3_license()) save a copy of the standard license text in
LICENSE.md, which is then added to
.Rbuildignore. This allows you
to follow standard licensing best practices while adhering to CRANs
use_package_doc() uses more modern roxygen2 template requires that
use_test() will use the name of the currently open file in RStudio
if you don't supply an explicit name (#89).
use_readme_rmd() now puts images in
man/figures/ and no longer
.Rbuildgnore. This ensures that the rendered
also work on CRAN (#16, #19). The first chunk now uses
include = FALSE
and is named setup (#19).
use_revdep() creates structure for use with revdepcheck package, the
preferred way to run revdepchecks. (#33)
use_badge() for adding any badge to a README. Now only prints a
todo message if the badge does not already exist.
use_directory() is now exported (#27).
Functions which require code to be copied now automatically put the code on the clipboard if it is available (#52).
create_package() no longer creates a dependency on the current version of
use_build_ignore() now strips trailing
use_git() will restart RStudio if needed (and possible) (#42).
use_github() now has an organisation parameter so you can create repos
in organisations (#4).
use_test() now convert title to a slug that only
contains lowercase letters, numbers, and
use_vignette() now adds
*.R to your
.gitgnore so you
don't accidentally add in compiled vignette products (#35).