You will get the most out of usethis if you do some setup. These setup tasks do not need to be done all at once or even done at all. But usethis can offer the most support for package development and Git/GitHub workflows with some advance configuration. usethis can even help you with this!

Key steps that accelerate your R development workflow (details on how to do all this follow):

  • Make usethis available in interactive R sessions.
  • Sign up for a free GitHub.com account, if you plan to use GitHub.
  • Install Git.
  • Configure your Git user.name and user.email.
  • If you use RStudio, make sure RStudio can find your Git executable. If you use GitHub, make sure you can pull/push from your local computer to GitHub.com, in general and from RStudio.
  • Get a personal access token from GitHub.com and make it available in R sessions.
  • Provide usethis with info you’d like in the DESCRIPTION file of all new R packages you create.

As you participate more in the R development scene, you will need to be able to install packages from source that contain compiled code, e.g. C or C++. This will come up even if you do not write such packages (yet). We touch on this at the end.

Use usethis in interactive work

usethis::use_usethis() helps you make usethis available whenever you are working with R interactively. It opens .Rprofile for editing, shows the necessary code snippet in the console, and puts it on your clipboard. Paste, save, close, restart R. Done.

This is the snippet that needs to go in .Rprofile:

In the long-run, devtools should make all of usethis’s functions available and it should feel like they are part of devtools itself. But while the “devtools diaspora” is in process (written in first half of 2018), you may need to work with both usethis and devtools. If you attach both, we recommend attaching devtools, then usethis. In .Rprofile, that would look like so:

You can read more about .Rprofile in the official Startup documentation or in Kevin Ushey’s blog post RProfile Essentials.

Get a GitHub.com account

Sign up for a free account with GitHub.com. Happy Git provides more advice about picking your username and discusses ways to get private repositories.

Install Git

Please see Happy Git and GitHub for the useR for instructions on how to install Git. It is beyond the scope of this article.

usethis itself does not actually need the Git that you install, because it uses the git2r package which wraps libgit2. But, chances are, you want to do normal Git things, like diff and commit and push, and for that you must install Git.

Configure user.name and user.email

Once Git is installed, introduce yourself to Git.

library(usethis)
use_git_config(user.name = "Jane Doe", user.email = "jane@example.com")

## reveals config, even if not changing anything
use_git_config()

usethis::use_git_config() helps you configure your user.name and user.email. Substitute your name and your email address.

What user name should you give to Git? This does not have to be your GitHub username, although it can be. Another good option is your actual first name and last name. Your commits will be labelled with this name, so this should be informative to potential collaborators.

What email should you give to Git? This must be the email associated with your GitHub account.

Equivalent Git commands

The code chunk above is doing the equivalent of this:

Optional: configure Git’s editor

Another Git option that many people eventually configure is the editor. This will come up if you use Git from a shell. At some point, you will fail to give Git what it wants in terms of a commit message and it will kick you into an editor. This can be distressing, if it’s not your editor of choice and you don’t even know how to save and quit. You can enforce your will by executing this in a shell (not in R!):

Substitute your preferred editor for emacs here. A popular choice is nano. The default, if you don’t configure core.editor, is usually vim.

Connections: Git, GitHub, RStudio

As stated above, usethis doesn’t actually use the Git you install and has no absolute requirement that you use GitHub or use RStudio. But use of usethis is highly correlated with the desire to do all of these things, in a pleasant way.

If you plan to use GitHub, you need to make sure your local Git can pull from and push to GitHub.com. That is beyond the scope of this article, but see the Connect to GitHub section in Happy Git. You probably don’t want to enter your username and password all the time, so either cache credentials for HTTPS or set up SSH keys. This can make it much easier for you to use usethis::use_github() in the future.

If you want to use RStudio to work with Git (and therefore GitHub, see previous paragraph), you need to make sure RStudio can find your Git executable. This usually “just works”. The Connect RStudio to Git and GitHub section of Happy Git helps you confirm that all is well. If all is not well, there are also troubleshooting tips.

Get and store a GitHub personal access token

A GitHub personal access token (PAT) is required if you want to use usethis::use_github() and usethis::create_from_github(..., fork = TRUE). In both cases, usethis must create a new GitHub repository on your behalf. This is not a regular Git operation (like pulling and pushing to existing repos) and your usual method of providing credentials to GitHub does not work for this.

usethis::browse_github_pat() takes you to a pre-filled form to request a PAT. You can get to the same page in the browser by clicking on “Generate new token” from https://github.com/settings/tokens.

As the page says, you must store this token somewhere because you’ll never be able to see it again, once you leave that page or close the windows. If you somehow goof this up, just generate a new PAT and, so you don’t confuse yourself, delete the lost token.

browse_github_pat() provides advice on how to store your PAT, also repeated here. It is customary to save the PAT as an environment variable in your .Renviron, with the name GITHUB_PAT.

usethis::edit_r_environ() will open .Renviron for editing. Add a line like this, but substitute your PAT:

Make sure this file ends in a newline! Lack of a newline can lead to silent failure to load this environment variable, which can be tricky to debug.

Restart R and confirm your PAT is now available:

Now usethis (and a few other packages) can find this PAT automatically in order to deal with GitHub on your behalf.

Store default values for DESCRIPTION fields in all new packages

If you want to override the defaults for the DESCRIPTION file of packages that you create via usethis::create_package(), define those fields via usethis.* options in your .Rprofile.

The options are consulted for a named list called usethis.description and, if that does not exist, for backwards compatibility, devtools.desc is also consulted.

usethis::edit_r_profile() opens your .Rprofile for editing.

Here is an example of R code that sets the authors, license, and version in all future DESCRIPTION files created by usethis:

Save similar code in your .Rprofile and restart R for it to take effect.

Prepare your system to build packages from source

As you participate more in R development, you will inevitably want to run development versions of other people’s packages, i.e. not the version available from CRAN. A typical way to do this is to install a package from GitHub with devtools::install_github("OWNER/REPO").

But, unlike using install.packages() and CRAN, you will be downloading and installing a source package, not a binary package. This means your system needs to be set up for building R packages. And, before long, you will need to build an R package with compiled code in it.

A full description of setting up an R development environment is beyond the scope of this article, but we give some pointers and diagnostics to get you started.

Update R and all of your packages. And expect to keep doing so frequently.

Mac OS: A convenient way to get the tools needed for compilation is to install Xcode Command Line Tools. Note that this is much smaller than full Xcode. In a shell, enter xcode-select --install. For installing almost anything else, consider using Homebrew.

Windows: Install Rtools. This is not an R package! It is “a collection of resources for building packages for R under Microsoft Windows, or for building R itself”. Go to https://cran.r-project.org/bin/windows/Rtools/ and install as instructed.

There are functions that verify whether R package build tools are installed and available. The home and name of this function is in flux, as it is affected by the restructing of the devtools universe (written early 2018).