Create a project from a GitHub repo

Creates a new local Git repository from a repository on GitHub. It is highly recommended that you pre-configure or pass a GitHub personal access token (PAT), which is facilitated by browse_github_token(). In particular, a PAT is required in order for create_from_github() to do "fork and clone". It is also required by use_github(), which connects existing local projects to GitHub.

create_from_github(
  repo_spec,
  destdir = NULL,
  fork = NA,
  rstudio = NULL,
  open = interactive(),
  protocol = git_protocol(),
  credentials = NULL,
  auth_token = github_token(),
  host = NULL
)

Arguments

repo_spec	GitHub repo specification in this form: `owner/repo`. The `repo` part will be the name of the new local 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 "ssh" or "https", if specified. Defaults to the option `usethis.protocol` and, if unset, to an interactive choice or, in non-interactive sessions, "ssh". `NA` triggers the interactive menu.
credentials	A git2r credential object produced with `git2r::cred_env()`, `git2r::cred_ssh_key()`, `git2r::cred_token()`, or `git2r::cred_user_pass()`.
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".

Using SSH Keys on Windows

If you are a Windows user who connects to GitHub using SSH, as opposed to HTTPS, you may need to explicitly specify the paths to your keys and register this credential in the current R session. This helps if git2r, which usethis uses for Git operations, does not automatically find your keys or handle your passphrase.

In the snippet below, do whatever is necessary to make the paths correct, e.g., replace <USERNAME> with your Windows username. Omit the passphrase part if you don't have one. Replace <OWNER/REPO> with the appropriate GitHub specification. You get the idea.

creds &lt;- git2r::cred_ssh_key(
  publickey  = "C:/Users/&lt;USERNAME&gt;/.ssh/id_rsa.pub",
  privatekey = "C:/Users/&lt;USERNAME&gt;/.ssh/id_rsa",
  passphrase = character(0)
)
use_git_protocol("ssh")
use_git_credentials(credentials = creds)

create_from_github(
  repo_spec = "&lt;OWNER/REPO&gt;",
  ...
)

Examples

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

Arguments

Using SSH Keys on Windows

See also

Examples