retrodep

Documentation

Overview

Package retrodep 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 := retrodep.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 NewWorkingTree function makes a temporary local copy of the upstream repository.

wt, err := retrodep.NewWorkingTree(&proj.RepoRoot)

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

ref, rerr := retrodep.DescribeProject(proj, wt, 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
  • func (h FileHashes) Mismatches(s FileHashes, failFast bool) []string
• type GoSource
  • func FindGoSources(path string, excludeGlobs []string) ([]*GoSource, error)
  • func NewGoSource(path string, excludes []string) (*GoSource, error)
  • func (src GoSource) DescribeProject(project *RepoPath, wt WorkingTree, dir string, top *Reference) (*Reference, error)
  • func (src GoSource) DescribeVendoredProject(project *RepoPath, wt WorkingTree, top *Reference) (*Reference, error)
  • func (src GoSource) Diff(project *RepoPath, wt WorkingTree, out io.Writer, dir, ref string) (bool, 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
• 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 ErrorNoGo = errors.New("no Go source code to process")

ErrorNoGo indicates there is no Go source code to process.

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

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

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 map[string]FileHash

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.

func (FileHashes) Mismatches

func (h FileHashes) Mismatches(s FileHashes, failFast bool) []string

Mismatches returns a slice of filenames from h whose hashes mismatch those in s. If failFast is true at most one mismatch will be returned.

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 the import path for the top-level package
	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,
	wt WorkingTree,
	dir string,
	top *Reference,
) (*Reference, error)

DescribeProject attempts to identify the tag in the version control system which corresponds to the project, available in the working tree wt, based on comparison with files in dir. Vendored files and files whose names begin with "." are ignored. If top is not nil, it should be a Reference to the top-level package this project is vendored into.

func (GoSource) DescribeVendoredProject

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

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

func (GoSource) Diff

func (src GoSource) Diff(project *RepoPath, wt WorkingTree, out io.Writer, dir, ref string) (bool, error)

Diff writes (to out) the differences between the Go source code at dir and the repository at revision ref, ignoring files which are only present in the repository. It returns true if changes were found and false if not.

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)

RepoPathForImportPath takes an import path and returns a *RepoPath for it, based on possible replacements within the Go source configuration.

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.

type Reference

type Reference struct {
	// TopPkg is the name of the top-level package this package is
	// vendored into, or "" if Pkg is the top-level package.
	TopPkg string

	// TopVer is the Ver string (see below) for the TopPkg, if
	// defined.
	TopVer string

	// Pkg is the name of the package this Reference relates to.
	Pkg string

	// Repo is the URL for the repository holding the source code.
	Repo string

	// 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 Rev 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

	// Error encountered when finding repo path.
	Err error
}

RepoPath is a vcs.RepoRoot along with the sub-path within the repository, and the version.

type WorkingTree

type WorkingTree interface {
	io.Closer

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

	// Should be something that supports hashing files.
	Hasher

	// 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)

	// Diff writes output to out from 'diff -u' comparing the
	// path within the working tree with the localFile. It returns
	// true if changes were found and false if not.
	Diff(out io.Writer, path, localFile string) (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.