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 with pr_init(), one of several functions that work pull requests.

create_from_github() works best when we can find a GitHub personal access token in the Git credential store (just like many other usethis functions). See gh_token_help() for more advice.

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

Arguments

repo_spec	A string identifying the GitHub repo in one of these forms: Plain OWNER/REPO spec Browser URL, such as "https://github.com/OWNER/REPO" HTTPS Git URL, such as "https://github.com/OWNER/REPO.git" SSH Git URL, such as "git@github.com:OWNER/REPO.git" In the case of a browser, HTTPS, or SSH URL, the host is extracted from the URL. 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 FALSE, we clone repo_spec. If TRUE, we fork repo_spec, clone that fork, and do additional set up favorable for future pull requests: The source repo, repo_spec, is configured as the upstream remote, using the indicated protocol. The local DEFAULT branch is set to track upstream/DEFAULT, where DEFAULT is typically master or main. It is also immediately pulled, to cover the case of a pre-existing, out-of-date fork. If fork = NA (the default), we check your permissions on repo_spec. If you can push, we set fork = FALSE, If you cannot, we set fork = TRUE.
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 (but note that the cloned repo may already be an RStudio Project, i.e. may already have a .Rproj file).
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	One of "https" or "ssh"
host	GitHub host to target, passed to the .api_url argument of gh::gh(). If unspecified, gh defaults to "https://api.github.com", although gh's default can be customised by setting the GITHUB_API_URL environment variable. For a hypothetical GitHub Enterprise instance, either "https://github.acme.com/api/v3" or "https://github.acme.com" is acceptable.
auth_token	: No longer consulted now that usethis uses the gert package for Git operations, instead of git2r; gert relies on the credentials package for auth. The API requests are now authorized with the token associated with the host, as retrieved by gh::gh_token().
credentials	: No longer consulted now that usethis uses the gert package for Git operations, instead of git2r; gert relies on the credentials package for auth. The API requests are now authorized with the token associated with the host, as retrieved by gh::gh_token().

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. See gh_token_help() for advice on getting and storing your token.

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. Therefore, once you've configured your PAT, your setup is complete!

But what if you prefer the SSH protocol? 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 v2.0.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")

# repo_spec can be a URL
create_from_github("https://github.com/r-lib/usethis")

# a URL repo_spec also specifies the host (e.g. GitHub Enterprise instance)
create_from_github("https://github.acme.com/OWNER/REPO")
}