Downloaded size limits.
const (
MaxGoMod = 16 << 20 // maximum size of go.mod file
MaxLICENSE = 16 << 20 // maximum size of LICENSE file
MaxZipFile = 500 << 20 // maximum size of downloaded zip file
)
ErrNoCommits is an error equivalent to fs.ErrNotExist indicating that a given repository or module contains no commits.
var ErrNoCommits error = noCommitsError{}
func AllHex(rev string) bool
AllHex reports whether the revision rev is entirely lower-case hexadecimal digits.
func Run(ctx context.Context, dir string, cmdline ...any) ([]byte, error)
Run runs the command line in the given directory (an empty dir means the current directory). It returns the standard output and, for a non-zero exit, a *RunError indicating the command, exit status, and standard error. Standard error is unavailable for commands that exit successfully.
func RunWithStdin(ctx context.Context, dir string, stdin io.Reader, cmdline ...any) ([]byte, error)
func ShortenSHA1(rev string) string
ShortenSHA1 shortens a SHA1 hash (40 hex digits) to the canonical length used in pseudo-versions (12 hex digits).
func WorkDir(ctx context.Context, typ, name string) (dir, lockfile string, err error)
WorkDir returns the name of the cached work directory to use for the given repository type and name.
An Origin describes the provenance of a given repo method result. It can be passed to CheckReuse (usually in a different go command invocation) to see whether the result remains up-to-date.
type Origin struct {
VCS string `json:",omitempty"` // "git" etc
URL string `json:",omitempty"` // URL of repository
Subdir string `json:",omitempty"` // subdirectory in repo
Hash string `json:",omitempty"` // commit hash or ID
// If TagSum is non-empty, then the resolution of this module version
// depends on the set of tags present in the repo, specifically the tags
// of the form TagPrefix + a valid semver version.
// If the matching repo tags and their commit hashes still hash to TagSum,
// the Origin is still valid (at least as far as the tags are concerned).
// The exact checksum is up to the Repo implementation; see (*gitRepo).Tags.
TagPrefix string `json:",omitempty"`
TagSum string `json:",omitempty"`
// If Ref is non-empty, then the resolution of this module version
// depends on Ref resolving to the revision identified by Hash.
// If Ref still resolves to Hash, the Origin is still valid (at least as far as Ref is concerned).
// For Git, the Ref is a full ref like "refs/heads/main" or "refs/tags/v1.2.3",
// and the Hash is the Git object hash the ref maps to.
// Other VCS might choose differently, but the idea is that Ref is the name
// with a mutable meaning while Hash is a name with an immutable meaning.
Ref string `json:",omitempty"`
// If RepoSum is non-empty, then the resolution of this module version
// failed due to the repo being available but the version not being present.
// This depends on the entire state of the repo, which RepoSum summarizes.
// For Git, this is a hash of all the refs and their hashes.
RepoSum string `json:",omitempty"`
}
A Repo represents a code hosting source. Typical implementations include local version control repositories, remote version control servers, and code hosting sites.
A Repo must be safe for simultaneous use by multiple goroutines, and callers must not modify returned values, which may be cached and shared.
type Repo interface {
// CheckReuse checks whether the old origin information
// remains up to date. If so, whatever cached object it was
// taken from can be reused.
// The subdir gives subdirectory name where the module root is expected to be found,
// "" for the root or "sub/dir" for a subdirectory (no trailing slash).
CheckReuse(ctx context.Context, old *Origin, subdir string) error
// Tags lists all tags with the given prefix.
Tags(ctx context.Context, prefix string) (*Tags, error)
// Stat returns information about the revision rev.
// A revision can be any identifier known to the underlying service:
// commit hash, branch, tag, and so on.
Stat(ctx context.Context, rev string) (*RevInfo, error)
// Latest returns the latest revision on the default branch,
// whatever that means in the underlying implementation.
Latest(ctx context.Context) (*RevInfo, error)
// ReadFile reads the given file in the file tree corresponding to revision rev.
// It should refuse to read more than maxSize bytes.
//
// If the requested file does not exist it should return an error for which
// os.IsNotExist(err) returns true.
ReadFile(ctx context.Context, rev, file string, maxSize int64) (data []byte, err error)
// ReadZip downloads a zip file for the subdir subdirectory
// of the given revision to a new file in a given temporary directory.
// It should refuse to read more than maxSize bytes.
// It returns a ReadCloser for a streamed copy of the zip file.
// All files in the zip file are expected to be
// nested in a single top-level directory, whose name is not specified.
ReadZip(ctx context.Context, rev, subdir string, maxSize int64) (zip io.ReadCloser, err error)
// RecentTag returns the most recent tag on rev or one of its predecessors
// with the given prefix. allowed may be used to filter out unwanted versions.
RecentTag(ctx context.Context, rev, prefix string, allowed func(tag string) bool) (tag string, err error)
// DescendsFrom reports whether rev or any of its ancestors has the given tag.
//
// DescendsFrom must return true for any tag returned by RecentTag for the
// same revision.
DescendsFrom(ctx context.Context, rev, tag string) (bool, error)
}
func LocalGitRepo(ctx context.Context, remote string) (Repo, error)
LocalGitRepo is like Repo but accepts both Git remote references and paths to repositories on the local file system.
func NewRepo(ctx context.Context, vcs, remote string) (Repo, error)
A RevInfo describes a single revision in a source code repository.
type RevInfo struct {
Origin *Origin
Name string // complete ID in underlying repository
Short string // shortened ID, for use in pseudo-version
Version string // version used in lookup
Time time.Time // commit time
Tags []string // known tags for commit
}
type RunError struct {
Cmd string
Err error
Stderr []byte
HelpText string
}
func (e *RunError) Error() string
A Tag describes a single tag in a code repository.
type Tag struct {
Name string
Hash string // content hash identifying tag's content, if available
}
A Tags describes the available tags in a code repository.
type Tags struct {
Origin *Origin
List []Tag
}
UnknownRevisionError is an error equivalent to fs.ErrNotExist, but for a revision rather than a file.
type UnknownRevisionError struct {
Rev string
}
func (e *UnknownRevisionError) Error() string
func (UnknownRevisionError) Is(err error) bool
A VCSError indicates an error using a version control system. The implication of a VCSError is that we know definitively where to get the code, but we can't access it due to the error. The caller should report this error instead of continuing to probe other possible module paths.
TODO(golang.org/issue/31730): See if we can invert this. (Return a distinguished error for “repo not found” and treat everything else as terminal.)
type VCSError struct {
Err error
}
func (e *VCSError) Error() string
func (e *VCSError) Unwrap() error