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):
user.name and user.email.The usethis package was carved out of the devtools package as part of its “conscious uncoupling” in the v2.0.0 release. But note that devtools makes all of usethis’s functions available and they should feel like they are part of devtools itself. In addition, devtools offers some functions of its own and exposes selected functionality from a few other packages. You might enjoy making devtools (and therefore usethis) available in all your interactive R work.
Call usethis::use_devtools() for prompts to do this:
library(devtools) ## or library(usethis) use_devtools()
This will:
.Rprofile startup file for editing.The suggested snippet looks like this:
if (interactive()) { suppressMessages(require(devtools)) }
More resources on .Rprofile:
Certain options are consulted by usethis and allow you to set personal defaults:
usethis.full_name: consulted for making, e.g., supplemental license files.usethis.protocol: specifies your preferred transport protocol for Git. Either “https” or “ssh”. See the help for git_protocol() for more.usethis.description: named list of default DESCRIPTION fields for new packages made with usethis::create_package().usethis.quiet: if TRUE, prevents usethis from printing messages to the console.usethis.destdir: a default directory to use in create_from_github() and use_course().Define any of these options in your .Rprofile, which can be opened for editing via usethis::edit_r_profile(). Here is example code:
options( usethis.full_name = "Jane Doe", usethis.protocol = "ssh", usethis.description = list( "Authors@R" = utils::person( "Jane", "Doe", email = "jane@example.com", role = c("aut", "cre"), comment = c(ORCID = "JANE'S-ORCID-ID") ), Version = "0.0.0.9000" ), usethis.destdir = "~/the/place/where/I/keep/my/R/projects" )
Save similar code in your .Rprofile and restart R for it to take effect.
These functions gather information that help you or others troubleshoot things:
proj_sitrep(): prints info about the active usethis project, working directory, and the active RStudio Project. Points out when things are peculiar and how to fix.git_sitrep(): prints info about your current Git, gert, and GitHub setup.“Sitrep” is short for “situation report”.
Sign up for a free account with GitHub.com. Happy Git and GitHub for the useR provides more advice about picking your username.
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 gert package which wraps libgit2. But, chances are, you want to do normal Git things, like diff and commit and push, from RStudio or in the shell and for that you must install Git.
user.name and user.email
Once Git is installed, introduce yourself to Git.
library(usethis) ## or library(devtools) use_git_config(user.name = "Jane Doe", user.email = "jane@example.com") ## check by running a git situation-report: ## - your user.name and user.email should appear under "User" git_sitrep()
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.
usethis::git_sitrep() generates a git situation-report. It can help you confirm things will work as expected; it can also help you diagnose problems.
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 R:
library(usethis) use_git_config(core.editor = "nano")
To do the same thing with command line Git, execute this in a shell:
Substitute your preferred editor for emacs here. A popular choice is nano. The default, if you don’t configure core.editor, is usually vim.
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. Then set the usethis.protocol option to match, i.e. to either “https” or “ssh”. This setup makes functions like usethis::use_github() much easier to use.
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.
A GitHub personal access token (PAT) is required if you want to use usethis::use_github(), usethis::create_from_github(..., fork = TRUE), and many other usethis functions that need to create something on GitHub, such as a repo, an issue, or a pull request. Unlike pulling and pushing, these are not regular Git operations and your usual GitHub credentials do not necessarily work for this (although they can, if you play your cards right; see below).
A PAT is separate from your GitHub password, in the username / password sense (but in some cases you can use a PAT as a password; see below). You must create a PAT explicitly.
usethis::create_github_token() 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 window. If you somehow goof this up, just generate a new PAT and, so you don’t confuse yourself, delete the lost token.
In the moment, I usually copy the PAT to the clipboard for the next step. (I also store this PAT in my general password manager, for redundancy.) But the most useful place to store this PAT is in your Git credential store.
The credentials package is the first R package to interact with the Git credential store from R. It is used for credential handling by the gert package, which is how usethis does its Git work, and this is a big motivation for using gert. The rOpenSci tech note A better way to manage your GitHub personal access tokens lays out the basic approach.
credentials::set_github_pat() triggers a prompt where you can provide a PAT for github.com. The credentials package then validates it and registers it with your operating system’s Git credential store. This is something you do once. Or, rather, once per machine, per PAT. From that point on, credentials and, therefore, gert and, therefore, usethis should be able to automatically retrieve and use this PAT.
If you use the HTTPS protocol for Git work (as opposed to SSH), this PAT is the only credential you need to configure. It is sufficient for Git work done by usethis/gert/credentials and for GitHub API work done by usethis/gh/gitcreds (see next section).
At the time of writing, credentials::set_github_pat() is hard-wired to work with github.com, although this is likely to change.
One goal of usethis v2.0.0 is to provide support for GitHub Enterprise, i.e. instances of GitHub that are not github.com. Many companies and universities use GitHub Enterprise to have their own internal GitHub. Therefore, all PAT handling in usethis has been generalized to work with any GitHub host, defaulting to github.com.
usethis accomplishes all of its GitHub API work through the gh package and gh + usethis rely on the gitcreds package to lookup the PAT for any given GitHub host.
Why another package?!? gitcreds is inspired by the credentials package, but offers better support for GitHub deployments that aren’t github.com and for programmatic use from R. (These two packages (credentials and gitcreds) are likely to merge back into one at some point.)
Here’s how to check if you’ve already stored a token that usethis/gh/gitcreds can find:
gitcreds::gitcreds_get() # default is https://github.com # or for another GitHub deployment gitcreds::gitcreds_get("https://github.acme.com")
A github.com PAT stored by credentials::set_github_pat() should be re-discovered. But if you’re using GitHub Enterprise, you almost certainly won’t have a PAT stored yet.
If you find that you need to store you PAT, do this:
gitcreds::gitcreds_set() # default is https://github.com # or for another GitHub deployment gitcreds::gitcreds_set("https://github.acme.com")
Once stored properly, both credentials/gert and gitcreds/gh should be using the same PAT. Furthermore, both packages cache the PAT in an environment variable for the duration of the R session, which further facilitates PAT reuse over multiple calls, from multiple packages.
.Renviron
In the past, the most common way to make a github.com PAT available in R was to define it as an environment variable in the .Renviron startup file. This still works (since credentials/gert and gitcreds/gh check first for an environment variable), but it is less secure than the approaches described above. It is safer to keep your PAT in the Git credential store and to avoid storing it in plain text, in a regular file.
If you still want to use the less secure .Renviron method, usethis::edit_r_environ() opens that file 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 startup files, which can be tricky to debug.
Restart R for this to take effect.
These functions should reveal a configured PAT:
The PAT situation is also part of what’s reported in git_sitrep():
Now usethis (and several other packages) can find this PAT automatically in order to deal with GitHub on your behalf.
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).
pkgbuild::check_build_tools() is the most current function. It can be installed via install.packages("pkgbuild").devtools::has_devel() was a function in devtools, at least up to v1.13.5, so you might still see references to that. All functionality related to package building now lives in pkgbuild. But once you have installed pkgbuild, you should just use the function pkgbuild::check_build_tools() instead.