usethis (development version) Unreleased

Adoption of gert and credentials

Usethis now uses the gert package for Git operations (, where previously we used git2r. The main motivation for this is to provide a smoother user experience by discovering and using the same credentials as command line Git (and, therefore, the same as RStudio). Under the hood, the hero is the credentials package ( use_git_credentials() and git_credentials() are now deprecated, since usethis no longer needs a way for a user to provide explicit credentials. The switch to gert + credentials should eliminate most credential-finding fiascos, but if you want to learn more, see the introductory vignette for the credentials package.

Gert also takes a different approach to wrapping libgit2, the underlying C library that does Git operations. The result is more consistent support for SSH and TLS, across all operating systems, without requiring special effort at install time. More users should enjoy Git remote operations that “just work”, for both SSH and HTTPS remotes. There should be fewer “unsupported protocol” errors.

GitHub remote configuration

Usethis gains a more formal framework for characterizing a GitHub remote configuration. We look at:

  • Which GitHub repositories origin and upstream point to
  • Whether you can push to them
  • How they relate to each other, e.g. fork-parent relationship

This is an internal matter, but users will notice that usethis is more clear about which configurations are supported by various functions and which are not. The most common configurations are reviewed in a section of Happy Git.

When working in a fork, there is sometimes a question whether to target the fork or the parent repository. For example, use_github_links() adds GitHub links to the URL and BugReports fields of DESCRIPTION. If someone calls use_github_links() when working in a fork, they probably want those links to refer to the parent repo, not to their fork, because the user is probably preparing a pull request. Usethis should now have better default behaviour in these situations and, in some cases, will present an interactive choice.

Default branch

There is increasing interest in making the name of a repo’s default branch configurable. In principle, this is already possible, but in reality many Git tools have master hard-wired in various places and usethis is no exception. We are laying the groundwork to respect a repository-specific default branch in a future release. It remains to be seen if some standard will emerge for where to record this info or if usethis needs to track it in a custom Git configuration field.

TODO: Summarize current level of prep or support of non-master default branch.

Other changes

use_cpp11() is a new function to set up an R package to use cpp11.

create_package(roxygen = FALSE) once again writes a valid NAMESPACE file (and also has no Roxygen* fields in DESCRIPTION) (#1120).

create_package(), create_project(), and proj_activate() work better with relative paths, outside of RStudio (#1122, #954).

usethis 1.6.1 2020-04-29

Patch release to align some path handling internals with an update coming in the fs package.

usethis 1.6.0 2020-04-09

GitHub actions

Package creation

  • create_package() gains a roxygen argument. If TRUE (the default), it adds a RoxygenNote field to the DESCRIPTION (which means the first run of devtools::check() will re-document the package, #963), and creates an empty NAMESPACE (which means you’ll always need an explicit @export if you want to export functions, #927). It also turns markdown processing on by default (#911).

  • use_rstudio() now sets the LineEndingConversion to Posix so that packages created using usethis always use LF line endings, regardless of who contributes to them (#1002).

  • In the usethis.description option, you can now set Authors@R = person() directly, without having to wrap in additional layer of quotes. If setting this in your .Rprofile, you’ll need to use utils::person() since the utils package isn’t loaded until after your profile is executed.

PR helpers

Other new features

Minor improvements and bug fixes

Dependency changes

New Imports: cli, rematch2, rlang.

gh minimum version is bumped to v.1.1.0, due to changed behaviour around requests that return nothing.

clisymbols is removed from Imports.

usethis 1.5.1 2019-07-04

This is a patch release with various small features and bug fixes.

Using the pipe %>% or the tidy eval toolkit in your package

  • The templates used by use_pipe() and use_tidy_eval() use a more robust form of cross-reference links, linking to files rather than topics. This should silence some warnings seen on Windows at install time (#730, #731 @jmgirard).

  • use_pipe() gains a logical export argument, so it can do the setup necessary to use the pipe operator when it is re-exported (export = TRUE, which is the default and preserves the previous behaviour) and when it is not (export = FALSE) (#783).

Git, GitHub, and pull requests

Build tools and continuous integration


  • use_zip() is a new variant of use_course() that downloads and unpacks a ZIP file, with less pedantic behaviour re: the destination directory. Both functions now also work for ZIP files with MIME type "application/x-zip-compressed" (#573).

  • use_version() can detect "(development version)" in a NEWS header and update it with an actual version (#768, @DavisVaughan).

Dependency changes

R 3.1 is no longer explicitly supported or tested. Our general practice is to support the current release (3.6, at time of writing), devel, and the 4 previous versions of R (3.5, 3.4, 3.3, 3.2).

fs minimum version is stated to be v1.3.0.

glue minimum version is stated to be v1.3.0.

usethis 1.5.0 2019-04-07

Git, GitHub (and GitLab)

usethis gains several functions to inspect and manipulate the Git situation for the current project = repository. We also provide more control and visibility into git2r’s workings, especially around credentials (usethis uses git2r for all Git operations).

  • git_sitrep() lets you know what’s up with your Git, git2r and GitHub config (#328).

  • git_vaccinate() vaccinates your global (i.e. user-level) git ignore file. It adds standard entries for R users, such as .Rhistory and .Rdata. This decreases the chance that you commit and push files containing confidential information (#469).

  • git_remotes() and use_git_remote() are new helpers to inspect or modify Git remote URLs for the repo associated with the active project (#649).

  • git_protocol() + use_git_protocol() and git_credentials() + use_git_credentials() are new helpers to summon or set Git transport protocol (SSH or HTTPS) or git2r credentials, respectively. These functions are primarily for internal use. Most users can rely on default behaviour. Use these helpers to intervene if git2r isn’t discovering the right credentials (#653). usethis honors the usethis.protocol option, which allows you to express a general preference for SSH vs. HTTPS.

Other improvements and bug fixes:

GitHub pull requests

We’ve added experimental functions to work with GitHub pull requests. They are aimed at both a maintainer (who may make, review, and modify pull requests) and a contributor (who may make or explore pull requests).

  • git_sitrep() includes a section at the end aimed at describing “pull request readiness”. Expect that to develop and expand.

  • pr_init(), pr_fetch(), pr_push(), pr_pull(), pr_finish(), and pr_view() constitute the new family of helpers. They are designed to be smart about the significance of remotes with the standard names of origin and upstream and to facilitate both internal and external pull requests.

Partial file management

usethis gains tooling to manage part of a file. This is currently used for managing badges in your README and roxygen import tags:

  • use_badge() and friends now automatically add badges if your README contains a specially formatted badge block (#497):

    <-- badge:start -->
    <-- badge:end -->
  • use_tibble() and use_rcpp() automatically add roxygen tags to to {package}-package.R if it contains a specially formatted namespace block (#517):

    ## usethis namespace: start
    ## usethis namespace: end

    Unfortunately this means that use_rcpp() no longer supports non-roxygen2 workflows, but I suspect the set of people who use usethis and Rcpp but not roxygen2 is very small.

Extending and wrapping usethis

Tidyverse standards

These standards are (aspirationally) used by all tidyverse packages; you are welcome to use them if you find them helpful.

  • Call use_tidy_labels() to update GitHub labels. Colours are less saturated, docs is now documentation, we use some emoji, and performance is no longer automatically added to all repos (#519). Repo specific issues should be given colour #eeeeee and have an emoji.

  • Call use_logo() to update the package logo to the latest specifications: man/figure/logo.png should be 240 x 278, and README should contain <img src="man/figures/logo.png" align="right" height="139" />. This gives a nicer display on retina displays. The logo is also linked to the pkgdown site if available (#536).

  • When creating a new package, use create_tidy_package() to start with a package following the tidyverse standards (#461).

  • for the development version should use “(development version)” rather than the specific version (#440).

  • pkgdown sites should now be built by travis and deployed automatically to GitHub pages. use_pkgdown_travis() will help you set that up.

  • When starting the release process, call use_release_issue() to create a release checklist issue (#338).

  • Prior to CRAN submission call use_tidy_release_test_env() to update the test environment section in cran-comments() (#496).

  • After acceptance, try use_github_release() to automatically create a release. It’s created as a draft so you have a chance to look over before publishing.

  • use_vignette() includes the a standard initialisation chunk with knitr::opts_chunk$set(comment = "#>", collapse = TRUE) which should be used for all Rmds.

New functions not already mentioned

Other minor bug fixes and improvements

  • write_union() appends the novel lines, but does not remove duplicates from existing lines (#583, @khailper).

  • use_rcpp("foo") now creates src/foo.cpp (#117).

  • use_data() gains a version argument and defaults to serialization format version 2 (#675).

  • use_data_raw() accepts a name for the to-be-prepared dataset and opens a templated R script (#646).

  • browse_github() now falls back to CRAN organisation (with a warning) if package doesn’t have its own GitHub repo (#186).

  • create_*() restore the active project if they error part way through, and use proj_activate() (#453, #511).

  • edit_r_profile() and edit_r_environ() now respect environment variables R_PROFILE_USER and R_ENVIRON_USER, respectively (#480).

  • use_description() once again prints the generated description (#287).

  • use_description_field() is no longer sensitive to whitespace, which allows use_vignette() to work even if the VignetteBuilder field is spread over multiple lines (#439).

  • use_logo() can override existing logo if user gives permission (#454). It also produces retina appropriate logos by default, and matches the aspect ratio to the specification (#499).

  • use_news_md() will optionally commit.

  • use_package() gains a min_version argument to specify a minimum version requirement (#498). Set to TRUE to use the currently installed version (#386). This is used by use_tidy_eval() in order to require version 0.1.2 or greater of rlang (#484).

  • use_pkgdown() is now configurable with site options (@jayhesselberth, #467), and no longer creates the docs/ directory (#495).

  • use_test() no longer forces the filename to be lowercase (#613, @stufield).

  • use_test() will not include a context() in the generated file if used with testthat 2.1.0 and above (the future release of testthat) (#325).

  • use_tidy_description() sets the Encoding field in DESCRIPTION (#502, @krlmlr).

  • use_tidy_eval() re-exports := (#595, @jonthegeek).

  • use_tidy_versions() has source argument so that you can choose to use local or CRAN versions (#309).

  • use_travis() gains an ext argument, defaulting to "org". Use ext = "com" for (@cderv, #500).

  • use_version() asks before committing.

  • use_vignette() now has a title argument which is used in YAML header (in the two places where it is needed). The vignettes also lose the default author and date fields (@rorynolan, #445), and the R Markdown starter material. They gain a standard setup chunk.

  • use_version("dev") now creates a standard “(development version)” heading in (#440).

  • use_vignette() now checks if the vignette name is valid (starts with letter and consists of letters, numbers, hyphen, and underscore) and throws an error if not (@akgold, #555).

  • restart_rstudio() now returns FALSE in RStudio if no project is open, fixing an issue that caused errors in helpers that suggest restarting RStudio (@gadenbuie, #571).

Dependency changes

  • withr moves from Suggests to Imports.

  • purrr and yaml are new in Imports.

usethis 1.4.0 2018-08-14

File system

All usethis file system operations now use the fs package (#177). This should not change how usethis functions, but users may notice these features of fs-mediated paths:

  • Paths are “tidy”, meaning / is the path separator and there are never multiple or trailing /.
  • Paths are UTF-8 encoded.
  • A Windows user’s home directory is interpreted as C:\Users\username (typical of Unix-oriented tools, like Git and ssh; also matches Python), as opposed to C:\Users\username\Documents (R’s default on Windows). Read more in fs::path_expand().

Extending or wrapping usethis

These changes make it easier for others to extend usethis, i.e. to create workflow packages specific to their organization, or to use usethis in other packages.

New functions

  • proj_sitrep() reports current working directory, the active usethis project, and the active RStudio Project. Call this function if things seem weird and you’re not sure what’s wrong or how to fix it. Designed for interactive use and debugging, not for programmatic use (#426).

  • use_tibble() does minimum setup necessary for a package that returns or exports a tibble. For example, this guarantees a tibble will print as a tibble (#324 @martinjhnhadley).

  • use_logo() resizes and adds a logo to a package (#358, @jimhester).

  • use_spell_check() adds a whitelist of words and a unit test to spell check package documentation during R CMD check (#285 @jeroen).

Other small changes and bug fixes

  • usethis has a new logo! (#429)

  • use_course() reports progress during download (#276, #380).

  • use_git() only makes an initial commit of all files if user gives explicit consent (#378).

  • create_from_github(): the repo argument is renamed to repo_spec, since it takes input of the form “OWNER/REPO” (#376).

  • use_depsy_badge() is defunct. The Depsy project has officially concluded and is no longer being maintained (#354).

  • use_github() fails earlier, with a more informative message, in the absence of a GitHub personal access token (PAT). Also looks for the PAT more proactively in the usual environment variables (i.e., GITHUB_PAT, GITHUB_TOKEN) (#320, #340, @cderv).

  • The logic for setting DESCRIPTION fields in create_package() and use_description() got a Spring Cleaning. Fields directly specified by the user take precedence, then the named list in getOption("usethis.description") is consulted, and finally defaults built into usethis. use_description_defaults() is a new function that reveals fields found in options and built into usethis. Options specific to one DESCRIPTION field, e.g. devtools.desc.license, are no longer supported. Instead, use a single named list for all fields, preferably stored in an option named "usethis.description" (however,"devtools.desc" is still consulted for backwards compatibility). (#159, #233, #367)

Dependency changes

New Imports: fs, glue, utils

No longer in Imports: backports, httr, rematch2, rmarkdown (moved to Suggests), styler (moved to Suggests)

usethis 1.3.0 2018-02-24

  • usethis has a website: (#217). It includes an article with advice on system setup, for usethis and for R development more generally.

  • edit_*() functions now return the target path, invisibly (#255).

  • edit_git_ignore(scope = "user") prefers ~/.gitignore, but detects an existing ~/.gitignore_global, if it exists. If a new global gitignore file is created, it is created as ~/.gitignore and recorded in user’s git config as the core.excludesfile (#255).

  • create_from_github() gains several arguments and new functionality. The protocol argument lets user convey whether remote URLs should be ssh or https. In the case of “fork and clone”, the original repo is added as upstream remote. It is now possible – although rarely necessary – to directly specify the GitHub PAT, credentials (in git2r form), and GitHub host (#214, #214, #253).

  • use_github_labels() can create or update the colour of arbitrary GitHub issue labels, defaulting to a set of labels and colours used by the tidyverse packages, which are now exposed via tidy_labels(). That set now includes the labels “good first issue” and “help wanted” (#168, #249).

  • appveyor_info() no longer reverses the repo’s URL and image link. Corrects the markdown produced by use_appveyor_badge() (#240, @llrs).

  • use_cran_badge() uses an HTTPS URL for the CRAN badge image (#235, @jdblischak).

  • create_package() and create_project() return a normalized path, even if target directory does not pre-exist (#227, #228).

New functions

usethis 1.2.0 2018-01-19

New functions

Other changes

  • New projects that don’t exhibit other obvious criteria for being a “project” will include a sentinel, empty file named .here, so they can be recognized as a project.

  • Project launching and switching works on RStudio server (#115, #129).

  • use_template() is newly exported, so that other packages can provide templating functions using this framework (@ijlyttle #120).

  • use_readme_rmd() and use_readme_md() work, in a similar fashion, for projects that are and are not a package (#131, #135).

  • use_readme_rmd() once again creates a pre-commit git hook, to help keep README.Rmd and in sync (@PeteHaitch #41).

  • Substantial increase in unit test coverage.

usethis 1.1.0 2017-11-17

New helpers

Bug fixes and improvements

usethis 1.0.0 2017-10-22

This is a new package that extracts out many functions that previously lived in devtools, as well as providing more building blocks so you can create your own helpers. As well as the many new helpers listed below, there are three main improvements to the package:

  • More support for general R projects, other than packages.
  • A notion of an “active” project that all commands operate on.
  • Refined output.

usethis is gradually evolving towards supporting more general R “projects”, not just packages. This is still a work in progress, so please let me know if you use a function that you think should work with projects but doesn’t. You can also try out the new create_project() which creates a basic RStudio project.

The concept of the working directory and the “base path” have been refined. Rather than using an argument to specify the active project, all use_ functions now use a global active project setting, as returned by proj_get(). This is cached throughout a session, although it will be updated by create_package() and create_project(). You’ll now get an clear error if you attempt to use_something() outside of a project, and create_something() will warn if you’re trying to create inside an existing project.

The output from all usethis commands has been reviewed to be informative but not overwhelming. usethis takes advantage of colour (using crayon and RStudio 1.1) to help chunk the output and clearly differentiate what you need to do vs. what has been done for you.

New functions

New edit functions

A new class of functions make it easy to edit common config files:

  • edit_r_profile_user() opens .Rprofile
  • edit_r_environ_user() opens .Renviron
  • edit_r_makevars_user() opens .R/Makevars
  • edit_git_config_user() opens .gitconfig
  • edit_git_ignore_user() opens .gitignore
  • edit_rstudio_snippets(type) opens ~/R/snippets/{type}.snippets


  • use_coverage("codecov") now sets a default threshold of 1% to try and reduce false positives (#8).

  • use_description() now sets ByteCompile: true so you can benefit from the byte compiler (#29)

  • The license functions (use_mit_license(), use_apl2_license(), and use_gpl3_license()) save a copy of the standard license text in, which is then added to .Rbuildignore. This allows you to follow standard licensing best practices while adhering to CRANs requirements (#10).

  • use_package_doc() uses more a modern roxygen2 template that requires less duplication.

  • use_test() will use the name of the currently open file in RStudio if you don’t supply an explicit name (#89).

  • use_readme_rmd() now puts images in man/figures/ and no longer adds to .Rbuildgnore. This ensures that the rendered will also work on CRAN (#16, #19). The first chunk now uses include = FALSE and is named setup (#19).

  • use_revdep() creates structure for use with revdepcheck package, the preferred way to run revdepchecks. (#33)

Building blocks

  • New use_badge() for adding any badge to a README. Now only prints a todo message if the badge does not already exist.

  • use_directory() is now exported (#27).

Bug fixes and minor improvements