selfupdate

Documentation

Overview

Package selfupdate provides a generic, zero-dependency self-update mechanism for Go binaries distributed via GitHub Releases.

It handles fetching the latest release, downloading the platform-specific asset, verifying its SHA256 checksum, extracting the binary, and atomically replacing the running executable.

Example usage:

u := &selfupdate.Updater{
    Repo:  "owner/repo",
    Token: os.Getenv("GITHUB_TOKEN"),
    AssetNamer: func(v, goos, goarch string) string {
        return "mytool-" + v + "-" + goos + "-" + goarch
    },
}

rel, err := u.CheckLatest(ctx)
if err != nil { ... }

exePath, _ := os.Executable()
if err := u.Install(ctx, rel, exePath); err != nil { ... }

Index

• func IsInPath(dir string) bool
• func PathWarningMessage(dir string) string
• type AssetNamer
• type HTTPDoer
• type Release
• type Updater
  • func (u *Updater) CheckLatest(ctx context.Context) (*Release, error)
  • func (u *Updater) FetchRelease(ctx context.Context, version string) (*Release, error)
  • func (u *Updater) Install(ctx context.Context, rel *Release, exePath string) error

Functions

func IsInPath

func IsInPath(dir string) bool

IsInPath reports whether dir is in the colon-separated PATH.

func PathWarningMessage

func PathWarningMessage(dir string) string

PathWarningMessage returns instructions for adding dir to PATH on Unix. Returns an empty string if dir is already in PATH.

Types

type AssetNamer

type AssetNamer func(version, goos, goarch string) string

AssetNamer maps (version, goos, goarch) to an asset base filename without extension. version is the release version without the leading "v" prefix (e.g. "0.5.0"). The package appends ".tar.gz" (non-Windows) or ".zip" (Windows) automatically.

Example for a GoReleaser project named "mytool":

func(v, goos, goarch string) string { return "mytool-" + v + "-" + goos + "-" + goarch }

type HTTPDoer

type HTTPDoer interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPDoer is the interface satisfied by *http.Client. Inject a custom implementation for testing or proxy configuration.

type Release

type Release struct {
	// Version is the full release tag, e.g. "v0.5.0".
	Version string
	// AssetName is the resolved asset filename, e.g. "rog-0.5.0-linux-amd64.tar.gz".
	AssetName string
	// DownloadURL is the direct URL to download the asset.
	DownloadURL string
	// ChecksumURL is the URL for the checksums.txt file for this release.
	ChecksumURL string
}

Release describes a GitHub release resolved for the current platform.

type Updater

type Updater struct {
	// Repo is the GitHub repository in "owner/repo" format (required).
	Repo string
	// BinaryName is the base name of the binary to extract from the archive (required).
	// Do not include the ".exe" suffix — it is added automatically on Windows.
	// Example: "rog"
	BinaryName string
	// Token is an optional GitHub API token to avoid rate limits.
	Token string
	// Client is an optional HTTP client. If nil, http.DefaultClient is used.
	// Set a custom client to configure proxy, timeouts, or TLS settings.
	Client HTTPDoer
	// AssetNamer determines the asset base filename for the current platform (required).
	AssetNamer AssetNamer
}

Updater performs self-update operations against a GitHub repository.

Zero-value is not usable; at minimum Repo, BinaryName, and AssetNamer must be set.

func (*Updater) CheckLatest

func (u *Updater) CheckLatest(ctx context.Context) (*Release, error)

CheckLatest fetches the latest release from GitHub without downloading it. Returns the release metadata resolved for the current OS and architecture.

func (*Updater) FetchRelease

func (u *Updater) FetchRelease(ctx context.Context, version string) (*Release, error)

FetchRelease fetches a specific version's release from GitHub without downloading it. version may include or omit the leading "v" (both "v0.5.0" and "0.5.0" are accepted).

func (*Updater) Install

func (u *Updater) Install(ctx context.Context, rel *Release, exePath string) error

Install downloads, verifies, and atomically replaces exePath with the binary from the given release. It returns an error if any step fails.

On Unix, the replacement is performed with os.Rename (atomic on same filesystem). On Windows, the running executable is first renamed to exePath+".old", then the new binary is moved into place. The .old file is removed best-effort.