Gets the content of a file from GitHub, from any repo the user can read, and writes it into the active project. This function wraps an endpoint of the GitHub API which supports specifying a target reference (i.e. branch, tag, or commit) and which follows symlinks.

Usage

use_github_file(
repo_spec,
path = NULL,
save_as = NULL,
ref = NULL,
ignore = FALSE,
open = FALSE,
host = NULL
)

Arguments

repo_spec

A string identifying the GitHub repo or, alternatively, a GitHub file URL. Acceptable forms:

• Plain OWNER/REPO spec

• A blob URL, such as "https://github.com/OWNER/REPO/blob/REF/path/to/some/file"

• A raw URL, such as "https://raw.githubusercontent.com/OWNER/REPO/REF/path/to/some/file"

In the case of a URL, the path, ref, and host are extracted from it, in addition to the repo_spec.

path

Path of file to copy, relative to the GitHub repo it lives in. This is extracted from repo_spec when user provides a URL.

save_as

Path of file to create, relative to root of active project. Defaults to the last part of path, in the sense of basename(path) or fs::path_file(path).

ref

The name of a branch, tag, or commit. By default, the file at path will by copied from its current state in the repo's default branch. This is extracted from repo_spec when user provides a URL.

ignore

Should the newly created file be added to .Rbuildignore?

open

Open the newly created file for editing? Happens in RStudio, if applicable, or via utils::file.edit() otherwise.

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.

Value

A logical indicator of whether a file was written, invisibly.

Examples

if (FALSE) {
use_github_file(
"https://github.com/r-lib/actions/blob/v1/examples/check-standard.yaml"
)

use_github_file(
"r-lib/actions",
path = "examples/check-standard.yaml",
ref = "v1",
save_as = ".github/workflows/R-CMD-check.yaml"
)
}