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

• Constants
• 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 VCSKind
• type VCSPackageStatus
• type VCSUrlInformation
  • func DiscoverVCSInformation(vcsUrl string) (VCSUrlInformation, error)

Constants

const (
	VCSKindUnknown VCSKind = "unknown" // an unknown kind of VCS
	VCSKindGit             = "git"     // Git

	VCSKindFakeGit = "__fake__git" // Fake git for testing only
)

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 VCSKind

type VCSKind string

VCSKind identifies the supported kinds of VCS.

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         VCSKind // 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.