1 2<!-- README.md is generated from README.Rmd. Please edit that file --> 3 4# usethis <img src="man/figures/logo.png" align="right" height="139" /> 5 6<!-- badges: start --> 7 8[![R-CMD-check](https://github.com/r-lib/usethis/workflows/R-CMD-check/badge.svg)](https://github.com/r-lib/usethis/actions) 9[![Codecov test 10coverage](https://codecov.io/gh/r-lib/usethis/branch/master/graph/badge.svg)](https://codecov.io/gh/r-lib/usethis?branch=master) 11[![CRAN 12status](https://www.r-pkg.org/badges/version/usethis)](https://CRAN.R-project.org/package=usethis) 13[![Lifecycle: 14stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable) 15<!-- badges: end --> 16 17usethis is a workflow package: it automates repetitive tasks that arise 18during project setup and development, both for R packages and 19non-package projects. 20 21## Installation 22 23Install the released version of usethis from CRAN: 24 25``` r 26install.packages("usethis") 27``` 28 29Or install the development version from GitHub with: 30 31``` r 32# install.packages("devtools") 33devtools::install_github("r-lib/usethis") 34``` 35 36## Usage 37 38Most `use_*()` functions operate on the *active project*: literally, a 39directory on your computer. If you’ve just used usethis to create a new 40package or project, that will be the active project. Otherwise, usethis 41verifies that current working directory is or is below a valid project 42directory and that becomes the active project. Use `proj_get()` or 43`proj_sitrep()` to manually query the project and [read more in the 44docs](https://usethis.r-lib.org/reference/proj_utils.html). 45 46A few usethis functions have no strong connections to projects and will 47expect you to provide a path. 48 49usethis is quite chatty, explaining what it’s doing and assigning you 50tasks. `✔` indicates something usethis has done for you. `●` indicates 51that you’ll need to do some work yourself. 52 53Below is a quick look at how usethis can help to set up a package. But 54remember, many usethis functions are also applicable to analytical 55projects that are not packages. 56 57``` r 58library(usethis) 59 60# Create a new package ------------------------------------------------- 61path <- file.path(tempdir(), "mypkg") 62create_package(path) 63#> ✓ Creating '/tmp/RtmpBtK0Bx/mypkg/' 64#> ✓ Setting active project to '/private/tmp/RtmpBtK0Bx/mypkg' 65#> ✓ Creating 'R/' 66#> ✓ Writing 'DESCRIPTION' 67#> Package: mypkg 68#> Title: What the Package Does (One Line, Title Case) 69#> Version: 0.0.0.9000 70#> Authors@R (parsed): 71#> * First Last <first.last@example.com> [aut, cre] (YOUR-ORCID-ID) 72#> Description: What the package does (one paragraph). 73#> License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a 74#> license 75#> Encoding: UTF-8 76#> LazyData: true 77#> Roxygen: list(markdown = TRUE) 78#> RoxygenNote: 7.1.1 79#> ✓ Writing 'NAMESPACE' 80#> ✓ Setting active project to '<no active project>' 81# only needed since this session isn't interactive 82proj_activate(path) 83#> ✓ Setting active project to '/private/tmp/RtmpBtK0Bx/mypkg' 84#> ✓ Changing working directory to '/tmp/RtmpBtK0Bx/mypkg/' 85 86# Modify the description ---------------------------------------------- 87use_mit_license("My Name") 88#> ✓ Setting License field in DESCRIPTION to 'MIT + file LICENSE' 89#> ✓ Writing 'LICENSE' 90#> ✓ Writing 'LICENSE.md' 91#> ✓ Adding '^LICENSE\\.md$' to '.Rbuildignore' 92 93use_package("MASS", "Suggests") 94#> ✓ Adding 'MASS' to Suggests field in DESCRIPTION 95#> ● Use `requireNamespace("MASS", quietly = TRUE)` to test if package is installed 96#> ● Then directly refer to functons like `MASS::fun()` (replacing `fun()`). 97 98# Set up other files ------------------------------------------------- 99use_readme_md() 100#> ✓ Writing 'README.md' 101 102use_news_md() 103#> ✓ Writing 'NEWS.md' 104 105use_test("my-test") 106#> ✓ Adding 'testthat' to Suggests field in DESCRIPTION 107#> ✓ Setting Config/testthat/edition field in DESCRIPTION to '3' 108#> ✓ Creating 'tests/testthat/' 109#> ✓ Writing 'tests/testthat.R' 110#> ✓ Writing 'tests/testthat/test-my-test.R' 111#> ● Edit 'tests/testthat/test-my-test.R' 112 113x <- 1 114y <- 2 115use_data(x, y) 116#> ✓ Adding 'R' to Depends field in DESCRIPTION 117#> ✓ Creating 'data/' 118#> ✓ Saving 'x', 'y' to 'data/x.rda', 'data/y.rda' 119#> ● Document your data (see 'https://r-pkgs.org/data.html') 120 121# Use git ------------------------------------------------------------ 122use_git() 123#> ✓ Initialising Git repo 124#> ✓ Adding '.Rproj.user', '.Rhistory', '.Rdata', '.httr-oauth', '.DS_Store' to '.gitignore' 125``` 126 127## Code of Conduct 128 129Please note that the usethis project is released with a [Contributor 130Code of Conduct](https://usethis.r-lib.org/CODE_OF_CONDUCT.html). By 131contributing to this project, you agree to abide by its terms. 132