Usethis now uses the gert package for Git operations (https://docs.ropensci.org/gert), 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 (https://docs.ropensci.org/credentials/).
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.
Usethis gains a more formal framework for characterizing a GitHub remote configuration. We look at:
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.
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.
GitHub Actions is the preferred platform for continuous integration, because that is what the tidyverse team currently uses and maintains. Functions related to Travis-CI and AppVeyor are soft-deprecated to raise awareness about this change and to make it clear that, if substantial maintenance becomes necessary, we may elect to retire the function (#1169).
use_cpp11() is a new function to set up an R package to use cpp11.
Patch release to align some path handling internals with an update coming in the fs package.
use_github_links() is a bit more clever about remotes (e.g.
upstream), which makes it easier to make a PR that adds GitHub links for a package you’ve forked.
.gitignores the destination directory and only adds the destination directory to the config file if it departs from the default (which is
We now recommend GitHub Actions instead of Travis-CI or AppVeyor, and strongly recommend upgrading your packages.
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).
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.
ui_silence() makes it easier to selectively silence some UI output.
When writing files, usethis now respects line endings. Default line endings are taken from the
.Rproj file (if available), otherwise the
DESCRIPTION, otherwise the first file found in
R/, then all else failing to your platform default (#767). It should do a better job of preserving UTF-8 files on windows (#969).
browse_github() now always goes to the canonical GitHub site:
https://github.com/user/repo. This is slightly worse than the current behaviour but makes the function more consistent across packages, and considerably simplifies the implementation.
browse_circle() opens the project dashboard on Circle CI.
create_download_url() is a new helper for making “ZIP file download” URLs suitable for use with
use_zip(), starting with the URLs that mere mortals can usually get their hands on in a browser (@fmichonneau, #406).
use_description_defaults() now shows the default fields combined with any options that you have set.
This is a patch release with various small features and bug fixes.
The templates used by
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).
use_tidy_ci() is updated for R 3.6, meaning that R 3.2 is the oldest version of R supported through proactive testing.
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
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 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_vaccinate() vaccinates your global (i.e. user-level) git ignore file. It adds standard entries for R users, such as
.Rdata. This decreases the chance that you commit and push files containing confidential information (#469).
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:
use_git_config() now invisibly returns the previous values of the settings.
use_github_labels() has been rewritten be more flexible. You can now supply a repo name, and
descriptions, and you can set colours/descriptions independently of creating labels. You can also
rename existing labels (#290).
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_view() constitute the new family of helpers. They are designed to be smart about the significance of remotes with the standard names of
upstream and to facilitate both internal and external pull requests.
usethis gains tooling to manage part of a file. This is currently used for managing badges in your README and roxygen import tags:
<-- badge:start --> <-- badge:end -->
## usethis namespace: start ## usethis namespace: end NULL
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.
proj_set() no longer have a
quiet argument. The user-facing message about setting a project is now under the same control as other messages, i.e.
getOption("usethis.quiet", default = FALSE) (#441).
A new set of
ui_*() functions makes it possible to give your own code the same user interface as usethis (#308). All use the glue and crayon and packages to power easy interpolation and formatting. There are four families of functions:
local_project() are new withr-style functions to temporarily set an active usethis project. They make usethis functions easier to use in an ad hoc fashion or from another package (#441).
These standards are (aspirationally) used by all tidyverse packages; you are welcome to use them if you find them helpful.
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.
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).
NEWS.md 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.
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.
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 http://hexb.in/sticker.html 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_tidy_versions() has source argument so that you can choose to use local or CRAN versions (#309).
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.
/is the path separator and there are never multiple or trailing
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
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.
proj_path() is newly exported. Use it to build paths within the active project. Like
proj_set(), it is not aimed at end users, but rather for use in extension packages. End users should use rprojroot or its simpler companion, here, to programmatically detect a project and build paths within it (#415, #425).
getOption("usethis.quiet", default = FALSE) is consulted when printing user-facing messages. Set this option to
TRUE to suppress output, e.g., to use usethis functions quietly in another package. For example, use
withr::local_options(list(usethis.quiet = TRUE)) in the calling function (#416, #424).
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).
usethis has a new logo! (#429)
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
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
"devtools.desc" is still consulted for backwards compatibility). (#159, #233, #367)
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
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).
browse_github_pat() goes to the webpage where a GitHub user can create a personal access token (PAT) for the GitHub API. If the user configures a PAT, they can use functions like
use_github() to easily create and connect GitHub repos to local projects. (#248, #257, @jeroen, via @jennybc).
use_tidy_github() creates a standard set of files that make a GitHub repository more navigable for users and contributors: an issue template, contributing guidelines, support documentation, and a code of conduct. All are now placed in a
.github/ subdirectory (#165, @batpigandme).
use_course() downloads a folder’s worth of materials from a ZIP file, with deliberate choices around the default folder name and location. Developed for use at the start of a workshop. Helps participants obtain materials from, e.g., a DropBox folder or GitHub repo (#196).
use_blank_slate() provides a way to opt in to an RStudio workflow where the user’s workspace is neither saved nor reloaded between R sessions. Automated for
scope = "project". Provides UI instructions for
scope = "user", for now (#139).
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.
Substantial increase in unit test coverage.
use_tidy_versions() sets minimum version requirement for all dependencies.
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:
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_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.
use_apl2_license() if you want to use the Apache 2.0 license.
use_tidy_description() puts description fields in a standard order and alphabetises dependencies.
use_usethis() opens your
.Rprofile and gives you the code to copy and paste in.
A new class of functions make it easy to edit common config files:
The license functions (
use_gpl3_license()) save a copy of the standard license text in
LICENSE.md, 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_readme_rmd() now puts images in
man/figures/ and no longer adds to
.Rbuildgnore. This ensures that the rendered
README.md will also work on CRAN (#16, #19). The first chunk now uses
include = FALSE and is named setup (#19).
Functions which require code to be copied now automatically put the code on the clipboard if it is available (#52).
create_package() no longer creates a dependency on the current version of