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.
- Provide usethis with info to use in all new R packages you create.
- Use the “sitrep” functions to get a health check or gather info when you’re going to ask for help.
- Sign up for a free GitHub.com account, if you plan to use GitHub.
- Install Git.
- Configure your Git
- 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.
- Prepare your system to build R packages from source.
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.
usethis::use_devtools() for prompts to do this:
- Open your
.Rprofilestartup file for editing.
- Show the necessary code snippet in the console and put it on your clipboard.
- Prompt you to paste, save, close, restart R. Done!
The suggested snippet looks like this:
More resources on
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” (the usethis default) or “ssh”. See the help for
usethis.description: named list of default DESCRIPTION fields for new packages made with
TRUE, prevents usethis from printing messages to the console.
usethis.destdir: a default directory to use in
TRUE, usethis overwrites an existing file without asking for user confirmation if the file is inside a Git repo. The rationale is that the normal Git workflow makes it easy to see and selectively accept/discard any proposed changes.
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 = "email@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", usethis.overwrite = TRUE )
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”.
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. Gert’s credential management also works best when official Git tooling is available.
Once Git is installed, introduce yourself to Git.
library(usethis) ## or library(devtools) use_git_config(user.name = "Jane Doe", user.email = "firstname.lastname@example.org") # check by running a git situation-report: # - your user.name and user.email should appear in global Git config git_sitrep()
usethis::use_git_config() helps you configure your
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.
The code chunk above is doing the equivalent of this:
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:
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. If you are an SSH person, set the
usethis.protocol option to “ssh” (as of v2.0.0, “https” is the usethis default).
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
create_from_github(..., fork = TRUE), and many other usethis functions that 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 the linked article).
Git/GitHub credential management is detailed in a separate article:
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
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.
If you work in RStudio, it will often assist you with setting up a dev environment upon first need.
devtools::has_devel() to get an initial sense of whether R package build tools are installed and available.
pkgbuild::check_build_tools() is another function to report on your system and, in an interactive RStudio session, should trigger an automatic installation of build tools.
It is also possible to install build tools yourself.
macOS: 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.