create_from_github: Create a project from a GitHub repo

Description Usage Arguments Git/GitHub Authentication See Also Examples

View source: R/create.R

Description

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 your GitHub credentials are discoverable. See below for more about authentication.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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

Deprecated lifecycle: 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

Deprecated lifecycle: 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().

Git/GitHub Authentication

Many usethis functions, including those documented here, potentially interact with GitHub in two different ways:

Therefore two types of auth can happen and your credentials must be discoverable. Which credentials do we mean?

Git/GitHub credential management is covered in a dedicated article: Managing Git(Hub) Credentials

See Also

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
## Not run: 
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")

## End(Not run)

usethis documentation built on Feb. 10, 2021, 5:08 p.m.