README.md
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[](https://github.com/r-lib/usethis/actions)
9[](https://codecov.io/gh/r-lib/usethis?branch=master)
11[](https://CRAN.R-project.org/package=usethis)
13[](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
){kind=link}
){kind=link}
){kind=link}