usethis

https://usethis.r-lib.org
Admin
usethis is a workflow package that automates repetitive tasks during R project setup and...
Tokens:95,059
Snippets:1,044
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example: Get help with GitHub token

Source: https://usethis.r-lib.org/reference/github-token.html

Demonstrates how to call the `gh_token_help()` function to get assistance with token setup. This example is non-runnable.

```r
if (FALSE) { # \dontrun{
gh_token_help()
}

```

--------------------------------

### Example: Use use_git()

Source: https://usethis.r-lib.org/reference/use_git.html

Demonstrates how to call the `use_git()` function to initialize a Git repository. This example is typically run interactively.

```r
if (FALSE) { # \dontrun{
use_git()
} # }
```

--------------------------------

### gh_token_help

Source: https://usethis.r-lib.org/reference/github-token.html

Guides you through token troubleshooting and setup.

```APIDOC
## gh_token_help

### Description
Guides you through token troubleshooting and setup.

### Usage
```R
gh_token_help(host = NULL)
```

### Arguments

* **host** (string, optional) - GitHub host to target, passed to the `.api_url` argument of `gh::gh()`. If unspecified, gh defaults to "https://api.github.com", although gh's default can be customised by setting the GITHUB_API_URL environment variable. For a hypothetical GitHub Enterprise instance, either "https://github.acme.com/api/v3" or "https://github.acme.com" is acceptable.

### Value
Nothing

### See also
`gh::gh_whoami()` for information on an existing token and `gitcreds::gitcreds_set()` and `gitcreds::gitcreds_get()` for a secure way to store and retrieve your PAT.

### Examples

```R
if (FALSE) { # \dontrun{
gh_token_help()
}
```
```

--------------------------------

### Example: Create a GitHub token

Source: https://usethis.r-lib.org/reference/github-token.html

Demonstrates how to call the `create_github_token()` function. This example is non-runnable and requires manual intervention in a browser.

```r
if (FALSE) { # \dontrun{
create_github_token()
}

```

--------------------------------

### Example usage of README creation functions

Source: https://usethis.r-lib.org/reference/use_readme_rmd.html

Demonstrates the basic usage of `use_readme_rmd()` and `use_readme_md()`. This example is non-executable and intended for illustration.

```r
if (FALSE) { # \dontrun{
use_readme_rmd()
use_readme_md()
} # }
```

--------------------------------

### Example: Create and open a learnr tutorial

Source: https://usethis.r-lib.org/reference/use_tutorial.html

This example demonstrates how to create a new tutorial named 'learn-to-do-stuff' with the title 'Learn to do stuff'. The tutorial file will be opened for editing if the `open` argument is TRUE (which is the default in interactive sessions).

```r
if (FALSE) { # \dontrun{
use_tutorial("learn-to-do-stuff", "Learn to do stuff")
} # }
```

--------------------------------

### Install usethis Development Version from GitHub

Source: https://usethis.r-lib.org/index.html

Install the development version of the usethis package from GitHub using the 'pak' package.

```R
# install.packages("pak")
pak::pak("r-lib/usethis")
```

--------------------------------

### Package Setup Tasks

Source: https://usethis.r-lib.org/reference/index.html

Functions for initial package setup, including licensing, namespace management, and configuration file editing.

```APIDOC
## use_data_table()

### Description
Prepare for importing data.table.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_description()
## use_description_defaults()

### Description
Create or modify a DESCRIPTION file.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_mit_license()
## use_gpl_license()
## use_agpl_license()
## use_lgpl_license()
## use_apache_license()
## use_cc0_license()
## use_ccby_license()
## use_proprietary_license()

### Description
License a package.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_namespace()

### Description
Use a basic `NAMESPACE`.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_coverage()
## use_covr_ignore()

### Description
Test coverage.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## edit_r_profile()
## edit_r_environ()
## edit_r_buildignore()
## edit_r_makevars()
## edit_rstudio_snippets()
## edit_rstudio_prefs()
## edit_git_config()
## edit_git_ignore()
## edit_pkgdown_config()

### Description
Open configuration files.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_build_ignore()

### Description
Add files to `.Rbuildignore`.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_cpp11()

### Description
Use C++ via the cpp11 package.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_make()

### Description
Create Makefile.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_pipe()

### Description
Use magrittr's pipe in your package.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_rcpp()
## use_rcpp_armadillo()
## use_rcpp_eigen()
## use_c()

### Description
Use C, C++, RcppArmadillo, or RcppEigen.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_tibble()

### Description
Prepare to return a tibble.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_tidy_github_actions()
## create_tidy_package()
## use_tidy_description()
## use_tidy_dependencies()
## use_tidy_contributing()
## use_tidy_support()
## use_tidy_issue_template()
## use_tidy_coc()
## use_tidy_github()
## use_tidy_logo()
## use_tidy_upkeep_issue()

### Description
Helpers for tidyverse development.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_logo()

### Description
Use a package logo.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_news_md()

### Description
Create a simple `NEWS.md`.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_package_doc()

### Description
Package-level documentation.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_roxygen_md()

### Description
Use roxygen2 with markdown.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_readme_rmd()
## use_readme_md()

### Description
Create README files.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_badge()
## use_cran_badge()
## use_bioc_badge()
## use_lifecycle_badge()
## use_binder_badge()
## use_r_universe_badge()
## use_posit_cloud_badge()

### Description
README badges.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_gitlab_ci()
## use_circleci()
## use_circleci_badge()

### Description
Continuous integration setup and badges.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_pkgdown()
## use_pkgdown_github_pages()

### Description
Use pkgdown.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_github_links()

### Description
Use GitHub links in URL and BugReports.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_lifecycle()

### Description
Use lifecycle badges.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_standalone()

### Description
Use a standalone file from another repo.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_testthat()

### Description
Sets up overall testing infrastructure.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_air()

### Description
Configure a project to use Air.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)
```

--------------------------------

### Install Development Dependencies

Source: https://usethis.r-lib.org/CONTRIBUTING.html

Installs all necessary development dependencies for the usethis package. This should be done after forking and cloning the repository.

```r
devtools::install_dev_deps()
```

--------------------------------

### Interactive yes/no question examples

Source: https://usethis.r-lib.org/reference/ui-questions.html

Demonstrates how to use ui_yeah() and ui_nope() to ask users questions. Includes examples with default and custom response options, and shuffling.

```R
if (FALSE) { # \dontrun{
ui_yeah("Do you like R?")
ui_nope("Have you tried turning it off and on again?", n_yes = 1, n_no = 1)
ui_yeah("Are you sure its plugged in?", yes = "Yes", no = "No", shuffle = FALSE)
} # }
```

--------------------------------

### Examples

Source: https://usethis.r-lib.org/reference/use_r.html

Illustrates how to use `use_r()` and `use_test()` for creating and navigating between R and test files.

```APIDOC
## Examples

```R
if (FALSE) { # \dontrun{
# create a new .R file below R/
use_r("coolstuff")

# if `R/coolstuff.R` is active in a supported IDE, you can now do:
use_test()

# if `tests/testthat/test-coolstuff.R` is active in a supported IDE, you can
# return to `R/coolstuff.R` with:
use_r()
} # }
```
```

--------------------------------

### Example Output of proj_sitrep()

Source: https://usethis.r-lib.org/reference/proj_sitrep.html

This example demonstrates the typical output of `proj_sitrep()`, showing the current working directory and indicating when no active usethis or RStudio project is detected. It also provides guidance on how to set or activate a project.

```r
proj_sitrep()
#> •  working_directory:
#>   "/home/runner/work/usethis/usethis/docs/reference"
#> • active_usethis_proj: <unset>
#> • active_rstudio_proj: <unset>
#> ℹ There is currently no active usethis project.
#> ℹ usethis attempts to activate a project upon first need.
#> ☐ Call `usethis::proj_get()` to initiate project discovery.
#> ☐ Call `proj_set("path/to/project")` or
#>   `proj_activate("path/to/project")` to provide an explicit path.
```

--------------------------------

### Example Badge Usage

Source: https://usethis.r-lib.org/reference/badges.html

Demonstrates how to use the `use_cran_badge()` and `use_lifecycle_badge()` functions. These examples are non-runnable and intended for documentation purposes.

```R
if (FALSE) { # \dontrun{
use_cran_badge()
use_lifecycle_badge("stable")
} # }
```

--------------------------------

### Setup C infrastructure

Source: https://usethis.r-lib.org/reference/use_rcpp.html

Use this function to add the necessary infrastructure for using C code. It creates a `src/` directory and may create an initial `.c` file.

```R
use_c(name = NULL)
```

--------------------------------

### Get help with GitHub token troubleshooting

Source: https://usethis.r-lib.org/reference/github-token.html

Guides users through troubleshooting and setting up their GitHub Personal Access Token.

```r
gh_token_help(host = NULL)
```

--------------------------------

### Install usethis from CRAN

Source: https://usethis.r-lib.org/index.html

Install the released version of the usethis package from CRAN.

```R
install.packages("usethis")
```

--------------------------------

### Example usage of usethis R and test file functions

Source: https://usethis.r-lib.org/reference/use_r.html

Demonstrates how to create new R and test files using `use_r()` and `use_test()`, and how to navigate between them when files are active in an IDE.

```r
if (FALSE) { # \dontrun{
# create a new .R file below R/
use_r("coolstuff")

# if `R/coolstuff.R` is active in a supported IDE, you can now do:
use_test()

# if `tests/testthat/test-coolstuff.R` is active in a supported IDE, you can
# return to `R/coolstuff.R` with:
use_r()
} # }
```

--------------------------------

### Example of usethis UI functions

Source: https://usethis.r-lib.org/reference/ui-legacy-functions.html

Demonstrates the usage of ui_done, ui_todo, and ui_code_block for providing feedback and code snippets. The ui_done function indicates a successful completion, ui_todo suggests a next step, and ui_code_block displays a multi-line code example.

```R
new_val <- "oxnard"
ui_done("{ui_field('name')} set to {ui_value(new_val)}")
#> ✔ name set to 'oxnard'
ui_todo("Redocument with {ui_code('devtools::document()')}")
#> • Redocument with `devtools::document()`

ui_code_block(c(
  "Line 1",
  "Line 2",
  "Line 3"
))
#>   Line 1
#>   Line 2
#>   Line 3
```

--------------------------------

### Continuous Integration Setup

Source: https://usethis.r-lib.org/reference/index.html

Use to set up continuous integration workflows for your package using GitHub Actions or other services.

```r
use_github_action()
use_gitlab_ci()
use_circleci()
use_circleci_badge()
use_jenkins()
```

--------------------------------

### Install GitHub Packages with remotes and pak

Source: https://usethis.r-lib.org/articles/articles/git-credentials.html

These commands demonstrate how to install R packages from GitHub using the 'remotes' and 'pak' packages. 'pak' is recommended as a replacement for 'remotes'.

```r
remotes::install_github("r-lib/usethis")

pak::pkg_install("r-lib/usethis")
```

--------------------------------

### Example of using use_pipe()

Source: https://usethis.r-lib.org/reference/use_pipe.html

Demonstrates the basic usage of the `use_pipe()` function. This example is typically run within an R package development environment.

```r
if (FALSE) { # \dontrun{
use_pipe()
} # }
```

--------------------------------

### Continuous Integration Setup

Source: https://usethis.r-lib.org/reference/index.html

Functions for setting up continuous integration workflows for R packages.

```APIDOC
## use_github_action()

### Description
Set up a GitHub Actions workflow.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_gitlab_ci()
## use_circleci()
## use_circleci_badge()

### Description
Continuous integration setup and badges.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_jenkins()

### Description
Create Jenkinsfile for Jenkins CI Pipelines.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)
```

--------------------------------

### Set up a custom GitHub Actions workflow from a URL

Source: https://usethis.r-lib.org/reference/use_github_action.html

This example demonstrates how to set up a GitHub Actions workflow by providing a direct URL to a YAML file on GitHub. This is useful for workflows not included in the default `r-lib/actions` repository.

```r
use_github_action(
  url = "https://github.com/posit-dev/setup-air/blob/main/examples/format-suggest.yaml"
)
```

--------------------------------

### Set up the pkgdown website build workflow

Source: https://usethis.r-lib.org/reference/use_github_action.html

Use this to automatically build and publish a pkgdown website for your package using GitHub Actions. It's recommended to use `use_pkgdown_github_pages()` for a more complete setup.

```r
use_github_action("pkgdown")
```

--------------------------------

### Set up Tidyverse Style Guide

Source: https://usethis.r-lib.org/reference/tidyverse.html

Styles source code according to the tidyverse style guide. This function will overwrite existing files, so use with caution.

```r
use_tidy_style()
```

--------------------------------

### Add GitHub Actions for Air formatting

Source: https://usethis.r-lib.org/reference/use_air.html

These examples show how to set up continuous integration workflows for running Air via GitHub Actions. Choose either `format-suggest` or `format-check`.

```r
use_github_action(url = "https://github.com/posit-dev/setup-air/blob/main/examples/format-suggest.yaml")
```

```r
use_github_action(url = "https://github.com/posit-dev/setup-air/blob/main/examples/format-check.yaml")
```

--------------------------------

### Setup RcppEigen infrastructure

Source: https://usethis.r-lib.org/reference/use_rcpp.html

Use this function to add the necessary infrastructure for using C++ code with RcppEigen. It creates `src/`, adds `RcppEigen` to `DESCRIPTION`, and creates `Makevars` and `Makevars.win` files.

```R
use_rcpp_eigen(name = NULL)
```

--------------------------------

### Example of using use_tibble()

Source: https://usethis.r-lib.org/reference/use_tibble.html

This is a non-runnable example demonstrating the usage of `use_tibble()`. It's typically used within a package development context.

```r
if (FALSE) { # \dontrun{
use_tibble()
} # }
```

--------------------------------

### Use a template to create NEWS.md

Source: https://usethis.r-lib.org/reference/use_template.html

This example demonstrates how to use `use_template()` to create a `NEWS.md` file. It passes package name and version as data for interpolation. Note that running this code will write `NEWS.md` to your working directory.

```r
if (FALSE) { # \dontrun{
  # Note: running this will write `NEWS.md` to your working directory
  use_template(
    template = "NEWS.md",
    data = list(Package = "acme", Version = "1.2.3"),
    package = "usethis"
  )
} # }
```

--------------------------------

### Setup pkgdown Travis CI

Source: https://usethis.r-lib.org/news/index.html

Call use_pkgdown_travis() to set up Travis CI for building pkgdown sites and automatically deploying them to GitHub Pages.

```R
use_pkgdown_travis()
```

--------------------------------

### Prepare an R package or project to use Air

Source: https://usethis.r-lib.org/reference/use_air.html

This example demonstrates how to prepare an R package or project to use Air by calling the `use_air()` function without any arguments, which defaults to setting up VS Code/Positron specific configurations.

```r
if (FALSE) { # \dontrun{
# Prepare an R package or project to use Air
use_air()
} # }
```

--------------------------------

### Create a New Quarto Project

Source: https://usethis.r-lib.org/news/index.html

This experimental function helps create a new Quarto project, integrating with `quarto::quarto_create_project()` and opening the project in your IDE. It exits early if the Quarto CLI is not installed.

```r
create_quarto_project()

```

--------------------------------

### Install Xcode Command Line Tools on macOS

Source: https://usethis.r-lib.org/articles/articles/usethis-setup.html

A convenient way to obtain the necessary tools for compiling R packages on macOS. This is a smaller installation than the full Xcode application.

```bash
xcode-select --install
```

--------------------------------

### Test Coverage Setup

Source: https://usethis.r-lib.org/reference/index.html

Use to set up test coverage reporting for your package.

```r
use_coverage()
use_covr_ignore("file.R")
```

--------------------------------

### Enter New PAT

Source: https://usethis.r-lib.org/articles/articles/git-credentials.html

Example of entering a new PAT when prompted by gitcreds::gitcreds_set(). Paste your generated PAT when asked.

```r
> gitcreds::gitcreds_set()

? Enter password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-> Adding new credentials...
-> Removing credentials from cache...
-> Done.
```

--------------------------------

### Example .Rprofile snippet for devtools/usethis

Source: https://usethis.r-lib.org/articles/articles/usethis-setup.html

This is an example snippet that can be added to your .Rprofile to automatically load the devtools package in interactive R sessions. Ensure you restart R after modifying your .Rprofile.

```r
if (interactive()) {
  suppressMessages(require(devtools))
}
```

--------------------------------

### pr_init()

Source: https://usethis.r-lib.org/reference/pull-requests.html

As a contributor, start work on a new PR by ensuring that your local repo is up-to-date, then creating and checking out a new branch. Nothing is pushed to or created on GitHub until you call `pr_push()`.

```APIDOC
## pr_init()

### Description
Initializes a new pull request branch for a contributor. Ensures the local repository is up-to-date and creates a new branch for the PR. Changes are not pushed to GitHub until `pr_push()` is called.

### Method
Not applicable (function call)

### Parameters
None
```

--------------------------------

### Setup Rcpp infrastructure

Source: https://usethis.r-lib.org/reference/use_rcpp.html

Use this function to add the necessary infrastructure for using C++ code with Rcpp. It creates a `src/` directory, adds `Rcpp` to `DESCRIPTION`, and may create an initial `.cpp` file.

```R
use_rcpp(name = NULL)
```

--------------------------------

### Set up pkgdown for GitHub Pages

Source: https://usethis.r-lib.org/reference/use_pkgdown.html

Use `use_pkgdown_github_pages()` to automate the setup for publishing your pkgdown site to GitHub Pages. This includes configuring GitHub Actions for automatic builds and deployments.

```R
use_pkgdown_github_pages()
```

--------------------------------

### Setup RcppArmadillo infrastructure

Source: https://usethis.r-lib.org/reference/use_rcpp.html

Use this function to add the necessary infrastructure for using C++ code with RcppArmadillo. It creates `src/`, adds `RcppArmadillo` to `DESCRIPTION`, and creates `Makevars` and `Makevars.win` files.

```R
use_rcpp_armadillo(name = NULL)
```

--------------------------------

### Convenience Wrapper for Tidyverse GitHub Setup

Source: https://usethis.r-lib.org/reference/tidyverse.html

A convenience function that calls `use_tidy_contributing()`, `use_tidy_issue_template()`, `use_tidy_support()`, and `use_tidy_coc()` to set up standard tidyverse conventions in a GitHub repository.

```r
use_tidy_github()
```

--------------------------------

### Setup GitLab CI, CircleCI, or CircleCI Badge

Source: https://usethis.r-lib.org/reference/use_gitlab_ci.html

Use these functions to add CI configuration files to your R package. `use_gitlab_ci()` adds a .gitlab-ci.yml file for GitLab CI. `use_circleci()` adds a .circleci/config.yml file for CircleCI, with options to open a browser for automatic builds and specify a Docker image. `use_circleci_badge()` only adds the Circle CI badge.

```r
use_gitlab_ci()

use_circleci(browse = rlang::is_interactive(), image = "rocker/verse:latest")

use_circleci_badge(repo_spec = NULL)
```

--------------------------------

### Unzip a downloaded archive

Source: https://usethis.r-lib.org/reference/use_course_details.html

Demonstrates how to use tidy_unzip to unpack a ZIP file after downloading it. This example is typically run within a conditional block to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
tidy_download("https://github.com/r-lib/rematch2/archive/main.zip")
tidy_unzip("rematch2-main.zip")
} # }
```

--------------------------------

### Configure usethis options in .Rprofile

Source: https://usethis.r-lib.org/articles/articles/usethis-setup.html

Set personal defaults for usethis by defining options in your .Rprofile file. This example configures default DESCRIPTION fields, a preferred project directory, and overwriting behavior for existing files within Git repositories.

```r
options(
  usethis.description = list(
    "Authors@R" = utils::person(
        "Jane", "Doe",
        email = "jane@example.com",
        role = c("aut", "cre"),
        comment = c(ORCID = "JANE'S-ORCID-ID")
    )
  ),
  usethis.destdir = "~/the/place/where/I/keep/my/R/projects",
  usethis.overwrite = TRUE
)
```

--------------------------------

### Create and Set Up a New R Package

Source: https://usethis.r-lib.org/index.html

Demonstrates creating a new R package, activating the project, setting a license, adding a suggested package, creating README and NEWS files, setting up tests, and saving data.

```R
library(usethis)

# Create a new package -------------------------------------------------
path <- file.path(tempdir(), "mypkg")
create_package(path)
#> ✔ Creating '/tmp/RtmpPZsquk/mypkg/'.
#> ✔ Setting active project to "/private/tmp/RtmpPZsquk/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]
#> 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.3.2
#> ✔ 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/RtmpPZsquk/mypkg".
#> ✔ Changing working directory to '/tmp/RtmpPZsquk/mypkg/'

# Modify the description ----------------------------------------------
use_mit_license("My Name")
#> ✔ Adding "MIT + file LICENSE" to 'License'.
#> ✔ Writing 'LICENSE'.
#> ✔ Writing 'LICENSE.md'.
#> ✔ Adding "^LICENSE\.md$" to '.Rbuildignore'.

use_package("rmarkdown", "Suggests")
#> ✔ Adding rmarkdown to 'Suggests' field in DESCRIPTION.
#> ☐ Use `requireNamespace("rmarkdown", quietly = TRUE)` to test if rmarkdown is
#>   installed.
#> ☐ Then directly refer to functions with `rmarkdown::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.
#> ✔ Adding "3" to 'Config/testthat/edition'.
#> ✔ 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" and "y" to "data/x.rda" and "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", and
#>   ".quarto" to '.gitignore'.
```

--------------------------------

### RStudio Project Infrastructure Setup

Source: https://usethis.r-lib.org/reference/use_rstudio.html

Adds RStudio Project infrastructure to the current project. This includes creating an .Rproj file and adding RStudio-specific files to .gitignore and .Rbuildignore. It is recommended to use create_project() or create_package() for most use cases.

```r
use_rstudio(line_ending = c("posix", "windows"), reformat = TRUE)
```

--------------------------------

### Check R package build tools

Source: https://usethis.r-lib.org/articles/articles/usethis-setup.html

Run this function to get an initial assessment of whether R package build tools are installed and available on your system.

```r
devtools::has_devel()
```

--------------------------------

### Check Git Credential Status

Source: https://usethis.r-lib.org/articles/articles/git-credentials.html

Run this command to get a diagnostic report on your Git credential setup. It helps identify potential issues with PATs and environment variables.

```r
usethis::git_sitrep()
```

--------------------------------

### Get or Set Active Project

Source: https://usethis.r-lib.org/reference/index.html

Utility functions to get, set, or get the path of the currently active R project.

```r
proj_get()
proj_set("path/to/project")
proj_path()
with_project("path/to/project", { ... })
local_project("path/to/project")
```

--------------------------------

### use_tutorial

Source: https://usethis.r-lib.org/reference/use_tutorial.html

Creates a new tutorial below `inst/tutorials/`. Tutorials are interactive R Markdown documents built with the `learnr` package. `use_tutorial()` adds learnr to Suggests in DESCRIPTION, gitignores rendered tutorials, creates a new .Rmd tutorial from a template, and adds it to .Rbuildignore.

```APIDOC
## use_tutorial

### Description
Creates a new tutorial below `inst/tutorials/`. Tutorials are interactive R Markdown documents built with the `learnr` package. `use_tutorial()` does this setup:
  * Adds learnr to Suggests in `DESCRIPTION`.
  * Gitignores `inst/tutorials/*.html` so you don't accidentally track rendered tutorials.
  * Creates a new `.Rmd` tutorial from a template and, optionally, opens it for editing.
  * Adds new `.Rmd` to `.Rbuildignore`.

### Usage
```R
use_tutorial(name, title, open = rlang::is_interactive())
```

### Arguments 

* **name** - Base for file name to use for new `.Rmd` tutorial. Should consist only of numbers, letters, `_` and `-`. We recommend using lower case.
* **title** - The human-facing title of the tutorial.
* **open** - Open the newly created file for editing? Happens in RStudio, if applicable, or via `utils::file.edit()` otherwise.

### See also
The learnr package documentation.

### Examples
```R
if (FALSE) { # \dontrun{
use_tutorial("learn-to-do-stuff", "Learn to do stuff")
}
```
```

--------------------------------

### use_git()

Source: https://usethis.r-lib.org/reference/use_git.html

Initialises a Git repository and adds important files to .gitignore. If the user consents, it also makes an initial commit.

```APIDOC
## Initialise a git repository

### Description
`use_git()` initialises a Git repository and adds important files to `.gitignore`. If user consents, it also makes an initial commit.

### Usage
```R
use_git(message = "Initial commit")
```

### Arguments

* **message** (string) - Message to use for first commit.

### See also
Other git helpers: `use_git_config()`, `use_git_hook()`, `use_git_ignore()`

### Examples

```R
if (FALSE) { # \dontrun{
use_git()
}
```
```

--------------------------------

### Example of using use_rmarkdown_template

Source: https://usethis.r-lib.org/reference/use_rmarkdown_template.html

This is a non-runnable example demonstrating the basic usage of the `use_rmarkdown_template()` function. It shows how to call the function without any arguments to use default values.

```r
if (FALSE) { # \dontrun{
use_rmarkdown_template()
} # }
```

--------------------------------

### Check and install R package build tools

Source: https://usethis.r-lib.org/articles/articles/usethis-setup.html

This function reports on your system's build tools status. In an interactive RStudio session, it can trigger an automatic installation.

```r
pkgbuild::check_build_tools()
```

--------------------------------

### Create learnr Tutorial

Source: https://usethis.r-lib.org/reference/index.html

Use to create a learnr tutorial structure for your package.

```r
use_tutorial("intro-tutorial", "Introduction")
```

--------------------------------

### Create a learnr tutorial

Source: https://usethis.r-lib.org/reference/use_tutorial.html

Use this function to create a new tutorial structure. It adds learnr to your package's suggestions, ignores rendered HTML files in Git, and creates a new .Rmd file from a template.

```r
use_tutorial(name, title, open = rlang::is_interactive())
```

--------------------------------

### Create individual test files with usethis

Source: https://usethis.r-lib.org/reference/use_testthat.html

After setting up testthat infrastructure with `use_testthat()`, you can use `use_test()` to create individual test files. Provide a descriptive name for the test file, such as "something-management".

```R
use_test()

use_test("something-management")
```

--------------------------------

### Badge URL Example

Source: https://usethis.r-lib.org/articles/badge-accessibility.html

This is the URL format for a custom badge generated via shields.io.

```text
https://img.shields.io/badge/my__label-my__message-orange
```

--------------------------------

### Create Package-Level Documentation File

Source: https://usethis.r-lib.org/reference/use_package_doc.html

Use this function to add a dummy .R file for package-level documentation. The file is automatically opened for editing if the session is interactive.

```r
usethis::use_package_doc()
```

--------------------------------

### issue_reprex_needed

Source: https://usethis.r-lib.org/reference/issue-this.html

Labels an issue with 'reprex' and provides guidance to the author on what is needed for a reproducible example.

```APIDOC
## issue_reprex_needed

### Description
Labels the issue with the "reprex" label and gives the author some advice about what is needed.

### Arguments
* **number** (Issue number) - Required

### Example
```R
if (FALSE) { # \dontrun{
issue_reprex_needed(241)
}
```
```

--------------------------------

### Create Project from GitHub Repository

Source: https://usethis.r-lib.org/reference/create_from_github.html

Use `create_from_github()` to clone a GitHub repository and initialize a new project. The repository can be specified as an owner/repo pair or a full URL.

```r
if (FALSE) { # \dontrun{
create_from_github("r-lib/usethis")

# repo_spec can be a URL
create_from_github("https://github.com/r-lib/usethis")

# a URL repo_spec also specifies the host (e.g. GitHub Enterprise instance)
create_from_github("https://github.acme.com/OWNER/REPO")
} # } 

```

--------------------------------

### Download and unpack ZIP file with use_course

Source: https://usethis.r-lib.org/reference/zip-utils.html

Use `use_course()` to download a ZIP file from a URL or GitHub repository specification. It's designed for workshops, prompting the user to confirm the download destination and offering to clean up the ZIP file. The unpacked folder can be opened in the IDE or file manager.

```R
if (FALSE) { # \dontrun{
# download the source of usethis from GitHub, behind a bit.ly shortlink
use_course("bit.ly/usethis-shortlink-example")
use_course("http://bit.ly/usethis-shortlink-example")

# download the source of rematch2 package from CRAN
use_course("https://cran.r-project.org/bin/windows/contrib/4.5/rematch2_2.1.2.zip")

# download the source of rematch2 package from GitHub, 4 ways
use_course("r-lib/rematch2")
use_course("https://api.github.com/repos/r-lib/rematch2/zipball/HEAD")
use_course("https://api.github.com/repos/r-lib/rematch2/zipball/main")
use_course("https://github.com/r-lib/rematch2/archive/main.zip")
} # }

```

--------------------------------

### use_pkgdown_github_pages

Source: https://usethis.r-lib.org/reference/use_pkgdown.html

Implements the GitHub setup needed to automatically publish your pkgdown site to GitHub pages.

```APIDOC
## Function: use_pkgdown_github_pages

### Description
Implements the GitHub setup needed to automatically publish your pkgdown site to GitHub pages. This function first calls `use_pkgdown()`, then prepares to publish the pkgdown site from the `gh-pages` branch, configures a GitHub Action to automatically build and deploy the site, and updates relevant configuration files and the GitHub repository.

### Usage
```
use_pkgdown_github_pages()
```
```

--------------------------------

### use_course

Source: https://usethis.r-lib.org/reference/zip-utils.html

Designed for live workshops, this function downloads and unpacks a ZIP file, prompting the user to confirm the destination and cleanup actions. It attempts to open the unpacked folder in the user's IDE or file manager.

```APIDOC
## use_course(url, destdir = getOption("usethis.destdir"))

### Description
Designed with live workshops in mind. Includes intentional friction to highlight the download destination. Workflow:
* User executes, e.g., `use_course("bit.ly/xxx-yyy-zzz")`.
* User is asked to notice and confirm the location of the new folder. Specify `destdir` or configure the `"usethis.destdir"` option to prevent this.
* User is asked if they'd like to delete the ZIP file.
* If possible, the new folder is launched in a new session of the user's IDE. Otherwise, the folder is opened in the file manager, e.g. Finder on macOS or File Explorer on Windows.

### Arguments

* **url** (string) - Link to a ZIP file containing the materials. Shorter forms like GitHub repo specs ("OWNER/REPO") or shortlinks (bit.ly, pos.it, rstd.io) are accepted.
* **destdir** (string) - Destination for the new folder. Defaults to the location stored in the global option `usethis.destdir`, if defined, or to the user's Desktop or similarly conspicuous place otherwise.

### Value
Path to the new directory holding the unpacked ZIP file, invisibly.

### Examples
```R
if (FALSE) { # \dontrun{
# download the source of usethis from GitHub, behind a bit.ly shortlink
use_course("bit.ly/usethis-shortlink-example")
use_course("http://bit.ly/usethis-shortlink-example")

# download the source of rematch2 package from CRAN
use_course("https://cran.r-project.org/bin/windows/contrib/4.5/rematch2_2.1.2.zip")

# download the source of rematch2 package from GitHub, 4 ways
use_course("r-lib/rematch2")
use_course("https://api.github.com/repos/r-lib/rematch2/zipball/HEAD")
use_course("https://api.github.com/repos/r-lib/rematch2/zipball/main")
use_course("https://github.com/r-lib/rematch2/archive/main.zip")
} # }
```
```

--------------------------------

### Create Tidyverse Standard Package

Source: https://usethis.r-lib.org/news/index.html

Use create_tidy_package() to initialize a new R package that follows Tidyverse development standards from the start.

```R
create_tidy_package()
```

--------------------------------

### Initialize Git Repository

Source: https://usethis.r-lib.org/reference/use_git.html

Initializes a Git repository and adds essential files to .gitignore. Optionally, it can create an initial commit if the user consents.

```r
use_git(message = "Initial commit")
```

--------------------------------

### Set up testthat

Source: https://usethis.r-lib.org/reference/index.html

Use to set up the testthat package infrastructure for your package's testing suite.

```r
use_testthat()
```

--------------------------------

### Get the active project

Source: https://usethis.r-lib.org/reference/proj_utils.html

Retrieves the active project. If no project is currently set, it attempts to identify one based on common project indicators.

```r
proj_get()
```

--------------------------------

### Aborting with Invalid Block Specification

Source: https://usethis.r-lib.org/articles/ui-cli-conversion.html

Example of using `ui_abort` to report an error when a block specification is invalid, providing guidance on the correct format.

```R
block_start = "# <<<")
block_end = "# >>>")
ui_abort(c(
  "Invalid block specification.",
  "Must start with {.code {block_start}} and end with {.code {block_end}}. "
))
```

--------------------------------

### Use use_description()

Source: https://usethis.r-lib.org/reference/use_description.html

Use the use_description() function to create a DESCRIPTION file. You can optionally provide a list of fields to add or override defaults.

```r
use_description()

use_description(fields = list(Language = "es"))
```

--------------------------------

### use_blank_slate

Source: https://usethis.r-lib.org/reference/use_blank_slate.html

Configures R to not save or load the user workspace between sessions. This promotes reproducibility by ensuring R starts with a clean environment each time.

```APIDOC
## FUNCTION use_blank_slate

### Description
Configures R to not save or load the user workspace between sessions. This promotes reproducibility by ensuring R starts with a clean environment each time.

### Usage
```R
use_blank_slate(scope = c("user", "project"))
```

### Arguments

* `scope` (character) - Specifies the scope of the configuration. Can be either "user" to apply globally for the current user, or "project" to apply only to the current project. Defaults to c("user", "project").
```

--------------------------------

### Call git_sitrep() with default arguments

Source: https://usethis.r-lib.org/reference/git_sitrep.html

Call `git_sitrep()` without arguments to get a comprehensive report of all Git and GitHub settings for both the user and the current project.

```r
git_sitrep()
```

--------------------------------

### use_github()

Source: https://usethis.r-lib.org/reference/use_github.html

Connects a local project to GitHub by creating a repository on GitHub, adding it as the 'origin' remote, and making an initial push. It also performs checks on the local repository's state before proceeding.

```APIDOC
## use_github()

### Description
Connects a local project to GitHub by creating a repository on GitHub, adding it as the 'origin' remote, and making an initial push. It also performs checks on the local repository's state before proceeding.

### Usage
```
use_github(
  organisation = NULL,
  private = FALSE,
  visibility = c("public", "private", "internal"),
  protocol = git_protocol(),
  host = NULL
)
```

### Arguments 

* **organisation** (string, optional) - If supplied, the repo will be created under this organisation, instead of the login associated with the GitHub token discovered for this `host`. The user's role and the token's scopes must be such that you have permission to create repositories in this `organisation`.
* **private** (boolean, optional) - If `TRUE`, creates a private repository.
* **visibility** (string, optional) - Only relevant for organisation-owned repos associated with certain GitHub Enterprise products. The special "internal" `visibility` grants read permission to all organisation members, i.e. it's intermediate between "private" and "public", within GHE. When specified, `visibility` takes precedence over `private = TRUE/FALSE`.
* **protocol** (string, optional) - One of "https" or "ssh".
* **host** (string, optional) - GitHub host to target, passed to the `.api_url` argument of `gh::gh()`. If unspecified, gh defaults to "https://api.github.com", although gh's default can be customised by setting the GITHUB_API_URL environment variable. For a hypothetical GitHub Enterprise instance, either "https://github.acme.com/api/v3" or "https://github.acme.com" is acceptable.

### Examples

```
if (FALSE) { # \dontrun{
pkgpath <- file.path(tempdir(), "testpkg")
create_package(pkgpath)

## now, working inside "testpkg", initialize git repository
use_git()

## create github repository and configure as git remote
use_github()
} # }
```
```

--------------------------------

### Generate a praise message

Source: https://usethis.r-lib.org/articles/articles/pr-functions.html

Demonstrates how to use the praise package to create a custom message, such as for a pull request. Requires the praise package to be installed and loaded.

```R
library(praise)

template <- "${EXCLAMATION} - your pull request is ${adjective}!"

praise(template)
#> [1] "YEE-HAW - your pull request is groovy!"
```

--------------------------------

### Renaming files in an existing package

Source: https://usethis.r-lib.org/reference/use_r.html

Provides guidance and code examples for aligning file names across `R/` and `tests/testthat/` directories in an existing package.

```APIDOC
## Renaming files in an existing package

This section provides tips and a script to help identify and align file names across `R/` and `tests/testthat/` directories in an existing package.

### Script to identify file pairing opportunities

```R
library(fs)
library(tidyverse)

bind_rows(
  tibble(
    type = "R",
    path = dir_ls("R/", regexp = "\\.[Rr]$"),
    name = as.character(path_ext_remove(path_file(path))),
  ),
  tibble(
    type = "test",
    path = dir_ls("tests/testthat/", regexp = "/test[^/]+\\.[Rr]$"),
    name = as.character(path_ext_remove(str_remove(path_file(path), "^test[-_]"))),
  )
) |> 
  pivot_wider(names_from = type, values_from = path) |> 
  print(n = Inf)
```

The `rename_files()` function can also be helpful for this task.
```

--------------------------------

### R-universe Badge

Source: https://usethis.r-lib.org/reference/badges.html

Generates a badge indicating the package version available on R-universe. Assumes R-universe setup is complete. Optionally specify the repository owner/repo.

```R
use_r_universe_badge(repo_spec = NULL)
```

--------------------------------

### Use Basic NAMESPACE

Source: https://usethis.r-lib.org/reference/index.html

Use to create a basic NAMESPACE file for your package.

```r
use_namespace()
```

--------------------------------

### Inspect Shields.io Coveralls Badge

Source: https://usethis.r-lib.org/articles/badge-accessibility.html

Inspects a shields.io Coveralls badge URL to retrieve its title and aria-label attributes. This example shows badges with accessible information.

```R
inspect_badge("https://img.shields.io/coveralls/github/trinker/sentimentr?logo=coveralls")
#> $title
#> [1] "coverage: 19%"
#> 
#> $`aria-label`
#> [1] "coverage: 19%"
```

--------------------------------

### Inspect Shields.io Codecov Badge

Source: https://usethis.r-lib.org/articles/badge-accessibility.html

Inspects a shields.io Codecov badge URL to retrieve its title and aria-label attributes. This example shows badges with accessible information.

```R
inspect_badge("https://img.shields.io/codecov/c/github/r-lib/usethis?label=test%20coverage&logo=codecov")
#> $title
#> [1] "test coverage: 60%"
#> 
#> $`aria-label`
#> [1] "test coverage: 60%"
```

--------------------------------

### Connect Local Repo to GitHub

Source: https://usethis.r-lib.org/reference/use_github.html

Use this function to create a GitHub repository for your local project, add it as the 'origin' remote, and push the initial commit. Ensure your Git and GitHub credentials are set up correctly beforehand.

```r
if (FALSE) { # \dontrun{
pkgpath <- file.path(tempdir(), "testpkg")
create_package(pkgpath)

## now, working inside "testpkg", initialize git repository
use_git()

## create github repository and configure as git remote
use_github()
} # }
```

--------------------------------

### GitHub ZIP Download URLs

Source: https://usethis.r-lib.org/reference/use_course_details.html

Provides examples of direct download URLs for GitHub repositories as ZIP archives. These can be generated from the 'Clone or download' button or programmatically.

```R
https://github.com/r-lib/usethis/archive/main.zip
```

```R
https://github.com/github.com/r-lib/usethis/zipball/HEAD
```

```R
https://api.github.com/repos/r-lib/rematch2/zipball/REF
```

```R
https://api.github.com/repos/r-lib/rematch2/zipball/HEAD
```

```R
https://api.github.com/repos/r-lib/usethis/zipball/REF
```

--------------------------------

### Identify Contributors Using Browser URL

Source: https://usethis.r-lib.org/reference/use_tidy_thanks.html

This example shows how to specify the target repository using a full browser URL, which is useful for targeting hosts other than the default GitHub.com.

```r
if (FALSE) { # \dontrun{
use_tidy_thanks("https://github.com/r-lib/usethis")
} # }

```

--------------------------------

### use_data_raw()

Source: https://usethis.r-lib.org/reference/use_data.html

Sets up a script to generate package data. It creates a file in the `data-raw/` directory and optionally opens it for editing.

```APIDOC
## FUNCTION use_data_raw

### Description
Sets up a script to generate package data. It creates a file in the `data-raw/` directory and optionally opens it for editing.

### Usage
```R
use_data_raw(name = "DATASET", open = rlang::is_interactive())
```

### Arguments
* `name` (string): Name of the dataset to be prepared for inclusion in the package.
* `open` (boolean): Open the newly created file for editing? Happens in RStudio, if applicable, or via `utils::file.edit()` otherwise.

### Examples
```R
if (FALSE) { # \dontrun{
use_data_raw("daisy")
}
```
```

--------------------------------

### Setup magrittr pipe in an R package

Source: https://usethis.r-lib.org/reference/use_pipe.html

Use this function to add magrittr to your package's Imports, import the pipe operator, and optionally export it. This requires roxygen2.

```r
use_pipe(export = TRUE)
```

--------------------------------

### Generate GitHub Personal Access Token

Source: https://usethis.r-lib.org/articles/articles/git-credentials.html

Use this function to create a new personal access token (PAT) for GitHub. It guides you through a pre-filled form with recommended scopes.

```r
usethis::create_github_token()
```
Tokens:
Raw