Documentation
¶
Overview ¶
Package extensions stores, verifies and runs the executables that `gt extension` installs. It performs no network requests.
Index ¶
- Constants
- Variables
- func ChecksumFor(checksums io.Reader, asset string) (string, error)
- func Environ(base []string, set map[string]string) []string
- func FileSHA256(path string) (string, error)
- func Interpreter(path string, lookPath func(string) (string, error)) (string, error)
- func Older(version, minimum string) bool
- func ParseRepositoryName(repo string) (prefix, name string, err error)
- func Run(c Command) (int, error)
- func SelectAsset(names []string, repo, name, goos, goarch string) int
- func ValidDigest(digest string) bool
- func ValidName(name string) bool
- type Command
- type Extension
- type Manifest
- type Metadata
- type Store
Constants ¶
const ( PrefixGT = "gt" PrefixGH = "gh" )
Prefixes of extension executables; gt- wins over gh- for the same name.
const ( // KindBinary is a precompiled release asset. KindBinary = "binary" // KindScript is an executable at the root of a cloned repository. KindScript = "script" // KindLocal is an executable in a local directory, run in place while it is developed. KindLocal = "local" )
Kinds of installed extensions.
const ( SourceGitea = "gitea" SourceGitHub = "github" )
Sources an extension is installed from.
const ( MaxAssetSize = 256 << 20 MaxChecksumsSize = 1 << 20 )
Limits of what an install downloads.
const ChecksumsAsset = "checksums.txt"
ChecksumsAsset is the release asset that lists the digests of the other assets.
const LockTimeout = 30 * time.Second
LockTimeout bounds the wait for another gt installing or removing an extension.
Variables ¶
var ErrNotInstalled = errors.New("extension is not installed")
ErrNotInstalled reports a name that no installed extension has.
var Secrets = []string{
"GITEA_TOKEN", "GITEA_INSTANCE_URL", "GITEA_INSTANCE_INSECURE", "GITEA_INSTANCE_SSH_HOST",
"GH_TOKEN", "GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN", "GH_HOST",
}
Secrets are never inherited by an extension; a granted one receives its own.
Functions ¶
func ChecksumFor ¶
ChecksumFor returns the digest that checksums, in sha256sum format, lists for asset.
func FileSHA256 ¶
FileSHA256 returns the hexadecimal SHA-256 of the file at path.
func Interpreter ¶
Interpreter returns the program that runs the script at path on this system: none where the system runs it itself, else sh from PATH or from Git for Windows.
func Older ¶
Older reports whether version is older than minimum. Versions are compared by their numeric MAJOR.MINOR.PATCH; a development build or an unparsable version is never older.
func ParseRepositoryName ¶
ParseRepositoryName splits a repository name such as gt-hello into its prefix and the extension name hello.
func Run ¶
Run runs c to completion and returns its exit code; a process ended by a signal exits with 128 plus the signal number, as a shell reports it. Interrupts from the terminal reach the extension directly through its process group, so gt waits instead of killing it, and relays termination signals sent to gt alone.
func SelectAsset ¶
SelectAsset returns the index of the asset of repo built for goos/goarch, or -1. It prefers one named REPO-OS-ARCH or NAME-OS-ARCH, with .exe on Windows, and else takes one whose name ends in OS-ARCH, as GitHub CLI extensions name them. On Apple silicon an amd64 build is taken when no arm64 one exists, as Rosetta runs it.
func ValidDigest ¶
ValidDigest reports whether digest is a lowercase hexadecimal SHA-256.
Types ¶
type Command ¶
type Command struct {
Path string
Args []string
Dir string
Env []string
// Interpreter runs Path when the system cannot execute it directly, such as sh for a script
// on Windows.
Interpreter string
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
}
Command is one run of an extension.
type Extension ¶
type Extension struct {
Manifest
// Dir holds the manifest and the executable, or for a script extension the clone.
Dir string
}
Extension is an installed extension.
type Manifest ¶
type Manifest struct {
Name string `yaml:"name" json:"name"`
Prefix string `yaml:"prefix" json:"prefix"`
Kind string `yaml:"kind" json:"kind"`
Source string `yaml:"source,omitempty" json:"source"`
// Host is the instance URL, or https://github.com.
Host string `yaml:"host,omitempty" json:"host"`
Owner string `yaml:"owner,omitempty" json:"owner"`
Repo string `yaml:"repo,omitempty" json:"repo"`
RepoID int64 `yaml:"repo_id,omitempty" json:"repo_id"`
Tag string `yaml:"tag,omitempty" json:"tag"`
Commit string `yaml:"commit,omitempty" json:"commit"`
// Asset is the release asset a binary extension was downloaded from.
Asset string `yaml:"asset,omitempty" json:"asset"`
SHA256 string `yaml:"sha256,omitempty" json:"sha256"`
// DigestSource names where the digest checked at install came from: server, checksums.txt or
// none, when only the digest recorded at install protects the executable.
DigestSource string `yaml:"digest_source,omitempty" json:"digest_source"`
Pinned bool `yaml:"pinned,omitempty" json:"pinned"`
Credentials bool `yaml:"credentials,omitempty" json:"credentials"`
CompatGH bool `yaml:"compat_gh,omitempty" json:"compat_gh"`
// Path is the executable of a local extension.
Path string `yaml:"path,omitempty" json:"path"`
Metadata Metadata `yaml:"metadata,omitempty" json:"metadata"`
}
Manifest records where an installed extension came from and what it was granted.
func (Manifest) Executable ¶
Executable is the file name of the extension's executable, such as gt-hello or gt-hello.exe.
func (Manifest) Repository ¶
Repository is the extension's repository as OWNER/REPO.
type Metadata ¶
type Metadata struct {
Description string `yaml:"description,omitempty" json:"description"`
MinVersion string `yaml:"min_gt_version,omitempty" json:"min_gt_version"`
Platforms []string `yaml:"platforms,omitempty" json:"platforms"`
Credentials bool `yaml:"credentials,omitempty" json:"credentials"`
// Completion is "cobra" for an executable that answers Cobra's __complete protocol.
Completion string `yaml:"completion,omitempty" json:"completion"`
// Aliases maps a top-level command word to the arguments it passes to the extension, so
// user-group: "user-group" makes gt user-group run gt NAME user-group.
Aliases map[string]string `yaml:"aliases,omitempty" json:"aliases"`
}
Metadata is what an extension declares about itself in gt-extension.yml. gt does not verify it.
func ParseMetadata ¶
ParseMetadata reads gt-extension.yml, rejecting unknown keys so a misspelled declaration is noticed.
type Store ¶
type Store struct{ Dir string }
Store keeps installed extensions in Dir, one directory per extension name.
func (Store) List ¶
List returns the installed extensions sorted by name. A broken manifest is reported, not skipped.
func (Store) Publish ¶
Publish installs the staged directory stage with manifest, replacing an installed extension of the same name only when replace is set.
Source Files
Directories