A "standalone" file implements a minimum set of functionality in such a way
that it can be copied into another package. use_standalone()
makes it easy
to get such a file into your own repo.
It always overwrites an existing standalone file of the same name, making it easy to update previously imported code.
use_standalone(repo_spec, file = NULL, ref = NULL, host = NULL)
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"
Name of standalone file. The standalone-
prefix and file
extension are optional. If omitted, will allow you to choose from the
standalone files offered by that repo.
The name of a branch, tag, or commit. By default, the file at
path
will be copied from its current state in the repo's default branch.
This is extracted from repo_spec
when user provides a URL.
GitHub host to target, passed to the .api_url
argument of
gh::gh()
. If repo_spec
is a URL, host
is extracted from that.
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.
A standalone file has YAML frontmatter that provides additional information, such as where the file originates from and when it was last updated. Here is an example:
---
repo: r-lib/rlang
file: standalone-types-check.R
last-updated: 2023-03-07
license: https://unlicense.org
dependencies: standalone-obj-type.R
imports: rlang (>= 1.1.0)
---
Two of these fields are consulted by use_standalone()
:
dependencies
: A file or a list of files in the same repo that
the standalone file depends on. These files are retrieved
automatically by use_standalone()
.
imports
: A package or list of packages that the standalone file
depends on. A minimal version may be specified in parentheses,
e.g. rlang (>= 1.0.0)
. These dependencies are passed to
use_package()
to ensure they are included in the Imports:
field of the DESCRIPTION
file.
Note that lists are specified with standard YAML syntax, using
square brackets, for example: imports: [rlang (>= 1.0.0), purrr]
.
if (FALSE) {
use_standalone("r-lib/rlang", file = "types-check")
use_standalone("r-lib/rlang", file = "types-check", ref = "standalone-dep")
}
Run the code above in your browser using DataLab