backvendor

Documentation

Overview

Package backvendor provides a way to represent Go source code in a filesystem, and taken from a source code repository. It allows mapping vendored packages back to the original versions they came from.

A GoSource represents a filesystem tree containing Go source code. Create it using NewGoSource or FindGoSources. The Project and VendoredProjects methods return information about the top-level project and the vendored projects it has.

src := backvendor.NewGoSource(path, nil)
proj, perr := src.Project(importPath)
vendored, verr := src.VendoredProjects()

Both of these methods use RepoPath to describe the projects. If a glide configuration file is found, Version will be filled in for each vendored dependency.

The FindGoSources function looks for Go source code in the provided path. If it is not found there, the immediate subdirectories are searched. This function allows for repositories which are collections of independently-vendored projects.

The DescribeProject function takes a RepoPath and returns a Representation, indicating the upstream version of the project or vendored project, e.g.

ref, rerr := backvendor.DescribeProject(proj, src.Path)

It does this by comparing file hashes of the local files with those from commits in the upstream repository.

Index

• Variables
• func FindExcludes(path string, globs []string) ([]string, error)
• func PseudoVersion(d Describable, rev string) (string, error)
• type Describable
• type FileHash
• type FileHashes
  • func NewFileHashes(h Hasher, root string, excludes map[string]struct{}) (*FileHashes, error)
  • func (h *FileHashes) IsSubsetOf(s *FileHashes) bool
• type GoSource
  • func FindGoSources(path string, excludeGlobs []string) ([]*GoSource, error)
  • func NewGoSource(path string, excludes []string) (*GoSource, error)
  • func (src GoSource) DescribeProject(project *RepoPath, dir string) (*Reference, error)
  • func (src GoSource) DescribeVendoredProject(project *RepoPath) (*Reference, error)
  • func (src GoSource) Project(importPath string) (*RepoPath, error)
  • func (src GoSource) RepoPathForImportPath(importPath string) (*RepoPath, error)
  • func (src *GoSource) SetSubPath(root string) error
  • func (src GoSource) Vendor() string
  • func (src GoSource) VendoredProjects() (map[string]*RepoPath, error)
• type Hasher
  • func NewHasher(vcsCmd string) (Hasher, bool)
• type Reference
• type RepoPath
• type WorkingTree
  • func NewWorkingTree(project *vcs.RepoRoot) (WorkingTree, error)

Variables

var ErrorInvalidRef = errors.New("invalid ref")

ErrorInvalidRef indicates the ref is not a tag or a revision (perhaps it is a branch name instead).

var ErrorNeedImportPath = errors.New("unable to determine import path")

ErrorNeedImportPath indicates the import path for the project cannot be determined automatically and must be provided.

var ErrorNoFiles = errors.New("no files to hash")

ErrorNoFiles indicates there are no files to compare hashes of

var ErrorUnknownVCS = errors.New("unknown VCS")

ErrorUnknownVCS indicates the upstream version control system is not one of those for which support is implemented in backvendor.

var ErrorVersionNotFound = errors.New("version not found")

ErrorVersionNotFound indicates a vendored project does not match any semantic tag in the upstream revision control system.

Functions

func FindExcludes

func FindExcludes(path string, globs []string) ([]string, error)

FindExcludes returns a slice of paths which match the provided globs.

func PseudoVersion

func PseudoVersion(d Describable, rev string) (string, error)

PseudoVersion returns a semantic-like comparable version for a revision, based on tags reachable from that revision.

Types

type Describable

type Describable interface {
	// ReachableTag returns the most recent reachable tag,
	// preferring semver tags. It returns ErrorVersionNotFound if
	// no suitable tag is found.
	ReachableTag(rev string) (string, error)

	// TimeFromRevision returns the commit timestamp from the
	// revision rev.
	TimeFromRevision(rev string) (time.Time, error)
}

Describable is the interface which capture the methods required for creating a pseudo-version from a revision.

type FileHash

type FileHash string

FileHash records the hash of a file in the format preferred by the version control system that tracks it.

type FileHashes

type FileHashes struct {
	// contains filtered or unexported fields
}

FileHashes is a map of paths, relative to the top-level of the version control system, to their hashes.

func NewFileHashes

func NewFileHashes(h Hasher, root string, excludes map[string]struct{}) (*FileHashes, error)

NewFileHashes returns a new FileHashes from a filesystem tree at root, whose files belong to the version control system named in vcsCmd. Keys in the excludes map are filenames to ignore.

func (*FileHashes) IsSubsetOf

func (h *FileHashes) IsSubsetOf(s *FileHashes) bool

IsSubsetOf returns true if these file hashes are a subset of s.

type GoSource

type GoSource struct {
	// Path is the filepath to the top-level package
	Path string

	// SubPath is the top-level filepath relative to the root of
	// the repository, or "" if they are the same.
	SubPath string

	// Package is any import path in this project
	Package string
	// contains filtered or unexported fields
}

GoSource represents a filesystem tree containing Go source code.

func FindGoSources

func FindGoSources(path string, excludeGlobs []string) ([]*GoSource, error)

FindGoSources looks for top-level projects at path. If path is itself a top-level project, the returned slice contains a single *GoSource for that project; otherwise immediate sub-directories are tested. Files matching globs in excludeGlobs will not be considered when matching against upstream repositories.

func NewGoSource

func NewGoSource(path string, excludes []string) (*GoSource, error)

NewGoSource returns a *GoSource for the given path path. The paths in excludes will not be considered when matching against the upstream repository.

func (GoSource) DescribeProject

func (src GoSource) DescribeProject(project *RepoPath, dir string) (*Reference, error)

DescribeProject attempts to identify the tag in the version control system which corresponds to the project, based on comparison with files in dir. Vendored files and files whose names begin with "." are ignored.

func (GoSource) DescribeVendoredProject

func (src GoSource) DescribeVendoredProject(project *RepoPath) (*Reference, error)

DescribeVendoredProject attempts to identify the tag in the version control system which corresponds to the vendored copy of the project.

func (GoSource) Project

func (src GoSource) Project(importPath string) (*RepoPath, error)

Project returns information about the project's repository, as well as the project's path within the repository, given its import path. If importPath is "" it is deduced from import comments, if available.

func (GoSource) RepoPathForImportPath

func (src GoSource) RepoPathForImportPath(importPath string) (*RepoPath, error)

func (*GoSource) SetSubPath

func (src *GoSource) SetSubPath(root string) error

SetSubPath updates the GoSource.SubPath string to be relative to the given root.

func (GoSource) Vendor

func (src GoSource) Vendor() string

Vendor returns the path to the vendored source code.

func (GoSource) VendoredProjects

func (src GoSource) VendoredProjects() (map[string]*RepoPath, error)

VendoredProjects return a map of project import names to information about those projects, including which version control system they use.

type Hasher

type Hasher interface {
	// Hash returns the file hash for the filename absPath, hashed
	// as though it were in the repository as filename
	// relativePath.
	Hash(relativePath, absPath string) (FileHash, error)
}

Hasher is the interface that wraps the Hash method.

func NewHasher

func NewHasher(vcsCmd string) (Hasher, bool)

type Reference

type Reference struct {
	// Tag is the semver tag within the upstream repository which
	// corresponds exactly to the vendored copy of the project. If
	// no tag corresponds Tag is "".
	Tag string

	// Rev is the upstream revision from which the vendored
	// copy was taken. If this is not known Reference is "".
	Rev string

	// Ver is the semantic version or pseudo-version for the
	// commit named in Reference. This is Tag if Tag is not "".
	Ver string
}

Reference describes the origin of a vendored project.

type RepoPath

type RepoPath struct {
	vcs.RepoRoot

	// SubPath is the top-level filepath relative to the root of
	// the repository, or "" if they are the same.
	SubPath string

	Version string
}

type WorkingTree

type WorkingTree interface {
	io.Closer

	// Should be something that supports creating pseudo-versions.
	Describable

	// TagSync syncs the repo to the named tag.
	TagSync(tag string) error

	// VersionTags returns the semantic version tags.
	VersionTags() ([]string, error)

	// Revisions returns all revisions, newest to oldest.
	Revisions() ([]string, error)

	// FileHashesFromRef returns the file hashes for the tag or
	// revision ref. The returned FileHashes will be relative to
	// the subPath, which is itself relative to the repository
	// root.
	FileHashesFromRef(ref, subPath string) (*FileHashes, error)

	// RevSync syncs the repo to the named revision.
	RevSync(rev string) error

	// RevisionFromTag returns the revision ID from the tag.
	RevisionFromTag(tag string) (string, error)

	// StripImportComment removes import comments from package
	// declarations in the same way godep does, writing the result
	// (if changed) to w. It returns a boolean indicating whether
	// an import comment was removed.
	//
	// The file content may be written to w even if no change was made.
	StripImportComment(path string, w io.Writer) (bool, error)
}

A WorkingTree is a local checkout of Go source code, and methods to interact with the version control system it came from.

func NewWorkingTree

func NewWorkingTree(project *vcs.RepoRoot) (WorkingTree, error)

NewWorkingTree creates a local checkout of the version control system for a Go project.