Skip to content

r-lib/usethis

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
R
 
 
 
 
man
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

usethis

R-CMD-check Codecov test coverage CRAN status Lifecycle: stable

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 -------------------------------------------------
path <- file.path(tempdir(), "mypkg")
create_package(path)
#> βœ” Creating '/tmp/Rtmp4VMzwK/mypkg/'
#> βœ” Setting active project to '/private/tmp/Rtmp4VMzwK/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 <first.last@example.com> [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.2.0
#> βœ” 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/Rtmp4VMzwK/mypkg'
#> βœ” Changing working directory to '/tmp/Rtmp4VMzwK/mypkg/'

# Modify the description ----------------------------------------------
use_mit_license("My Name")
#> βœ” Setting License field in DESCRIPTION to 'MIT + file 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 package 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
#> βœ” Setting Config/testthat/edition field in DESCRIPTION to '3'
#> βœ” 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', 'y' to 'data/x.rda', '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' to '.gitignore'

Code of Conduct

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.