Create a project from a GitHub repo

Creates a new local project and Git repository from a repo on GitHub, by either cloning or fork-and-cloning. In the fork-and-clone case, create_from_github() also does additional remote and branch setup, leaving you in the perfect position to make a pull request, possibly with the pull request functions.

It is highly recommended that you pre-configure a GitHub personal access token (PAT), which is facilitated by create_github_token(). In particular, if you can't push to the source repo, you usually want to fork-and-clone (vs. clone) and we cannot do that unless we have a PAT.

create_from_github(
  repo_spec,
  destdir = NULL,
  fork = NA,
  rstudio = NULL,
  open = rlang::is_interactive(),
  protocol = git_protocol(),
  auth_token = github_token(),
  host = NULL,
  credentials = deprecated()
)

Arguments

repo_spec	GitHub repo specification in this form: owner/repo. The repo part will be the name of the new local folder, which is also a project and Git repo.
destdir	The new folder is stored here. If NULL, defaults to user's Desktop or some other conspicuous place. You can also set a default location using the option usethis.destdir, e.g. options(usethis.destdir = "a/good/dir"), perhaps saved to your .Rprofile with edit_r_profile()
fork	If TRUE, we create and clone a fork. If FALSE, we clone repo_spec itself. Will be set to FALSE if no auth_token (a.k.a. PAT) is provided or preconfigured. Otherwise, defaults to FALSE if you can push to repo_spec and TRUE if you cannot. In the case of a fork, the original target repo is added to the local repo as the upstream remote, using the preferred protocol. The master branch is set to track upstream/master and is immediately pulled, which matters in the case of a pre-existing, out-of-date fork.
rstudio	Initiate an RStudio Project? Defaults to TRUE if in an RStudio session and project has no pre-existing .Rproj file. Defaults to FALSE otherwise.
open	If TRUE, activates the new project: If RStudio desktop, the package is opened in a new session. If on RStudio server, the current RStudio project is activated. Otherwise, the working directory and active project is changed.
protocol	Optional. Should be "https" or "ssh", if specified. Defaults to the option usethis.protocol and, if unset, to an interactive choice or, in non-interactive sessions, "https". NA triggers the interactive menu.
auth_token	GitHub personal access token (PAT).
host	GitHub API host to use. Override with the endpoint-root for your GitHub enterprise instance, for example, "https://github.hostname.com/api/v3".
credentials	: No longer consulted now that usethis uses the gert package for Git operations, instead of git2r. Note that gert relies on the credentials package for auth.

Authentication

This function potentially interacts with GitHub in two different ways:

• via the GitHub REST API

• as a conventional Git remote

Therefore two types of auth happen.

To create a new repo on GitHub, we must call the GitHub REST API, i.e. this isn't one of the standard remote Git operations. Therefore you must make a GitHub personal access token (PAT) available. There are two ways to do this, in order of preference:

• Configure your token as the GITHUB_PAT env var. Then it can be used by many packages and functions, without any effort on your part. If you don't have a token yet or you haven't configured it as an env var, see create_github_token().

• Provide the token directly via the auth_token argument.

When we clone or pull from GitHub or push to it, depending on the protocol (HTTPS vs. SSH) and the privacy of the repo, we may also need regular Git credentials, just like we'd need with command line Git.

We highly recommend using the HTTPS protocol, unless you have a specific preference for SSH. If you are an "HTTPS person", your GitHub PAT (see above) can also be used to authorize standard Git remote operations. Once you've configured your PAT, your setup is complete! See use_git_protocol() for how to tell usethis about your preference for HTTPS (or SSH) by setting an option.

But what about SSH? usethis uses the gert package for Git operations and gert, in turn, relies on the credentials package for auth:

• https://docs.ropensci.org/gert

• https://docs.ropensci.org/credentials/

In usethis v1.7.0, we switched from git2r to gert + credentials. The main motivation is to provide a smoother user experience by discovering and using the same credentials as command line Git (and, therefore, the same as RStudio). The credentials package should automatically discover your SSH keys. This works so well that we have removed all credential-handling workarounds from usethis. If you have credential problems, focus your troubleshooting on getting the credentials package to find your SSH keys. Its introductory vignette is a good place to start.

See also

• use_github() to go the opposite direction, i.e. create a GitHub repo from your local repo

• git_protocol() for background on protocol (HTTPS vs SSH)

• use_course() to download a snapshot of all files in a GitHub repo, without the need for any local or remote Git operations

Examples

if (FALSE) {
create_from_github("r-lib/usethis")
}