Learn R Programming

⚠️There's a newer version (3.1.0) of this package.Take me there.

usethis

usethis is a workflow package: it automates repetitive tasks that arise during project setup and development, both for R packages and non-package projects.

Installation

Install the released version of usethis from CRAN:

install.packages("usethis")

Or install the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("r-lib/usethis")

Usage

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 -------------------------------------------------
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 <- 1
y <- 2
use_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.

Copy Link

Version

Install

install.packages('usethis')

Monthly Downloads

157,996

Version

1.4.0

License

GPL-3

Issues

Pull Requests

Stars

Forks

Maintainer

Hadley Wickham

Last Published

August 14th, 2018

Functions in usethis (1.4.0)

create_from_github

Create a project from a GitHub repo
browse_github_pat

Create a GitHub personal access token
use_course_details

Download and unpack a ZIP file
edit

Open configuration files
ci

Continuous integration setup and badges
create_package

Create a package or project
use_cran_comments

CRAN submission comments
proj_utils

Utility functions for the active project
use_pkgdown

Use pkgdown
edit_file

Open file for editing
use_github_labels

Manage GitHub issue labels
use_code_of_conduct

Add a code of conduct
use_github_links

Use GitHub links in URL and BugReports
tidyverse

Helpers for tidyverse development
use_package

Depend on another package
use_version

Increment package version
use_git_ignore

Tell git to ignore files
use_news_md

Create a simple NEWS.md
use_vignette

Create a vignette
use_course

Download course materials
use_r

Create or edit a .R file
badges

README badges
use_logo

Use a package logo
use_package_doc

Package-level documentation
use_github

Connect a local repo with GitHub
use_pipe

Use magrittr's pipe in your package
browse-this

Quickly browse to important package webpages
use_blank_slate

Don't save/load user workspace between sessions
use_namespace

Use a basic NAMESPACE
use_build_ignore

Add files to .Rbuildignore
use_directory

Use a directory
use_tidy_thanks

Identify contributors via GitHub activity
use_spell_check

Use spell check
use_template

Use a usethis-style template
licenses

License a package
proj_sitrep

Report working directory and usethis/RStudio project
use_testthat

Create tests
use_tibble

Prepare to return a tibble
use_git

Initialise a git repository
usethis-defunct

Defunct functions in usethis
use_usethis

Make usethis available in interactive sessions
use_data

Create package data
use_revdep

Reverse dependency checks
use_description

Create or modify a DESCRIPTION file
usethis-package

usethis: Automate Package and Project Setup
use_rmarkdown_template

Add an RMarkdown Template
use_git_config

Configure Git
use_git_hook

Add a git hook
use_rstudio

Add RStudio Project infrastructure
use_roxygen_md

Use roxygen with markdown
use_rcpp

Use Rcpp
write-this

Write into or over a file
use_readme_rmd

Create README files