vcs

Documentation

Overview

vcs package defines helpers functions and interfaces for working with Version Control Systems such as git, including discovery of VCS information based on the Golang VCS discovery protocol.

The discovery protocol is documented loosely here: https://golang.org/cmd/go/#hdr-Remote_import_paths

Index

• func GetVCSCheckoutDirectory(vcsPath string, pkgCacheRootPath string, vcsDevelopmentDirectories ...string) (string, error)
• func IsVCSRootDirectory(localPath string) bool
• func ParseVCSPath(vcsPath string) (vcsPackagePath, error)
• type InspectInfo
  • func PerformVCSCheckoutAndInspect(vcsPath string, pkgCacheRootPath string, cacheOption VCSCacheOption, ...) (InspectInfo, string, error)
• type VCSCacheOption
• type VCSCheckoutResult
  • func PerformVCSCheckout(vcsPath string, pkgCacheRootPath string, cacheOption VCSCacheOption, ...) (VCSCheckoutResult, error)
• type VCSHandler
  • func DetectHandler(checkoutDir string) (VCSHandler, bool)
  • func GetHandlerByKind(kind string) (VCSHandler, bool)
• type VCSPackageStatus
• type VCSUrlInformation
  • func DiscoverVCSInformation(vcsUrl string) (VCSUrlInformation, error)

Functions

func GetVCSCheckoutDirectory

func GetVCSCheckoutDirectory(vcsPath string, pkgCacheRootPath string, vcsDevelopmentDirectories ...string) (string, error)

GetVCSCheckoutDirectory returns the path of the directory into which the given VCS path will checked out, if PerformVCSCheckout is called.

func IsVCSRootDirectory

func IsVCSRootDirectory(localPath string) bool

IsVCSRootDirectory returns true if the given local file system path is a VCS root directory. Note that this method will return false if the path does not exist locally.

func ParseVCSPath

func ParseVCSPath(vcsPath string) (vcsPackagePath, error)

ParseVCSPath parses a path/url to a VCS package into its components.

Types

type InspectInfo

type InspectInfo struct {
	Engine    string
	CommitSHA string
	GetTags   tagGetter
}

InspectInfo holds all the data returned from a call to PerformVCSCheckoutAndInspect.

func PerformVCSCheckoutAndInspect

func PerformVCSCheckoutAndInspect(vcsPath string, pkgCacheRootPath string, cacheOption VCSCacheOption, vcsDevelopmentDirectories ...string) (InspectInfo, string, error)

PerformVCSCheckoutAndInspect performs the checkout and updating of the given VCS path and returns the commit SHA of the package, as well as its tags.

pkgCacheRootPath holds the path of the root directory that forms the package cache.

vcsDevelopmentDirectories specifies optional directories to check for branchless and tagless copies of the repository first. If found, the copy will be used in lieu of a normal checkout.

type VCSCacheOption

type VCSCacheOption int

VCSCacheOption defines the caching options for VCS checkout.

const (
	// VCSFollowNormalCacheRules indicates that VCS checkouts will be pulled from cache unless a HEAD
	// reference.
	VCSFollowNormalCacheRules VCSCacheOption = iota

	// VCSAlwaysUseCache indicates that VCS checkouts will always use the cache if available.
	VCSAlwaysUseCache
)

type VCSCheckoutResult

type VCSCheckoutResult struct {
	PackageDirectory string
	Warning          string
	Status           VCSPackageStatus
}

VCSCheckoutResult is the result of a VCS checkout, if it succeeds.

func PerformVCSCheckout

func PerformVCSCheckout(vcsPath string, pkgCacheRootPath string, cacheOption VCSCacheOption, vcsDevelopmentDirectories ...string) (VCSCheckoutResult, error)

PerformVCSCheckout performs the checkout and updating of the given VCS path and returns the local system directory at which the package was checked out.

pkgCacheRootPath holds the path of the root directory that forms the package cache.

vcsDevelopmentDirectories specifies optional directories to check for branchless and tagless copies of the repository first. If found, the copy will be used in lieu of a normal checkout.

type VCSHandler

type VCSHandler interface {
	// Kind returns the kind of this handler.
	Kind() string

	// Detect detects whether this handler matches the given checkout directory.
	Detect(checkoutDir string) bool

	// Checkout performs a full checkout.
	Checkout(path vcsPackagePath, downloadPath string, checkoutDir string) error

	// HasLocalChanges detects whether the directory has uncommitted code changes.
	HasLocalChanges(checkoutDir string, ignoreEntries ...string) bool

	// Update performs a pull/update of a checked out directory.
	Update(checkoutDir string) error

	// Inspect inspects a checked out directory, returning its HEAD SHA.
	Inspect(checkoutDir string) (string, error)

	// ListTags lists all tags/version of a project in a checked out directory.
	ListTags(checkoutDir string) ([]string, error)

	// IsDetached returns whether the checked out directory is in a detached state.
	IsDetached(checkoutDir string) (bool, error)

	// GetPackagePath returns the VCS Package Path information for the checked out directory.
	GetPackagePath(checkoutDir string) (vcsPackagePath, error)

	// Tag tags the revision in the checked out directory with the given tag.
	Tag(checkoutDir string, tag string, message string) error
}

VCSHandler defines a handler for working with a VCS package.

func DetectHandler

func DetectHandler(checkoutDir string) (VCSHandler, bool)

DetectHandler attempts to detect which VCS handler is applicable to the given checkout directory.

func GetHandlerByKind

func GetHandlerByKind(kind string) (VCSHandler, bool)

GetHandlerByKind returns the VCS handler for the given VCS kind, if any.

type VCSPackageStatus

type VCSPackageStatus int

VCSPackageStatus is the status of the VCS package checked out.

const (
	// DetachedPackage indicates that the package is detatched from a branch and therefore
	// is static.
	DetachedPackage VCSPackageStatus = iota

	// BranchOrHEADPackage indicates that the package is a branch or head package, and will
	// therefore be updated on every call.
	BranchOrHEADPackage

	// LocallyModifiedPackage indicates that the package was modified on the local file system,
	// and therefore cannot be updated.
	LocallyModifiedPackage

	// DevelopmentPackage indicates that the package was found in the VCS development directory
	// and was therefore loaded from that location.
	DevelopmentPackage

	// CachedPackage indicates that the package was returned from cache without further operation.
	// Should only be returned if the always-use-cache options is specified (typically by tooling).
	CachedPackage
)

type VCSUrlInformation

type VCSUrlInformation struct {
	UrlPrefix    string // The prefix matching the source URL.
	Kind         string // The kind of VCS for the source URL.
	DownloadPath string // The VCS-specific download path.
}

VCSUrlInformation holds information about a VCS source URL.

func DiscoverVCSInformation

func DiscoverVCSInformation(vcsUrl string) (VCSUrlInformation, error)

DiscoverVCSInformation attempts to download the given URL, find the discovery <meta> tag, and return the VCSUrlInformation found.