use_standalone: Use a standalone file from another repo

In r-lib/usethis: Automate Package and Project Setup

Use a standalone file from another repo

Description

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.

Usage

use_standalone(repo_spec, file = NULL, ref = NULL, host = NULL)

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 "[e-mail]:OWNER/REPO.git"
file	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.
ref	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.
host	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.

Supported fields

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]⁠.

Examples

## Not run: 
use_standalone("r-lib/rlang", file = "types-check")
use_standalone("r-lib/rlang", file = "types-check", ref = "standalone-dep")

## End(Not run)

r-lib/usethis documentation built on Nov. 28, 2024, 7:11 a.m.