gta

README

gta

Overview

gta is an application which finds Go packages that have deviated from their upstream source in git. A typical situation is when a project is using a monorepo. At build or continuous integration time, you won't have to build every single package since you will know which packages (and dependencies) have changed.

Installation

go install github.com/digitalocean/gta/cmd/gta

After installation, you will have a gta binary in $GOPATH/bin/

Usage

List packages that should be tested since they have deviated from master.

gta -include "$(go list -f '{{ .Module.Path }}')/"

List packages that have deviated from the most recent merge commit.

gta -include "$(go list -f '{{ .Module.Path }}')/"

What gta does

gta builds a list of "dirty" (changed) packages from master, using git. This is useful for determining which tests to run in larger monorepo style repositories.

gta works by implementing a various set of interfaces, namely the Differ and Packager interfaces.

Note: When using this tool, it is common to hit the maximum number of open file descriptors limit set by your OS. On macOS, this may be a measly 256. Consider raising that maximum to something reasonable with:

sudo ulimit -n 4096

License

This application is distributed under the Apache 2 license found in LICENSE

Documentation

Overview

Copyright 2016 The gta AUTHORS. All rights reserved.

Use of this source code is governed by the Apache 2 license that can be found in the LICENSE file.

Package gta provides a set of utilites to build a set of dirty packages and their dependents that can be used to target code changes.

Copyright 2016 The gta AUTHORS. All rights reserved.

Use of this source code is governed by the Apache 2 license that can be found in the LICENSE file.

Copyright 2016 The gta AUTHORS. All rights reserved.

Use of this source code is governed by the Apache 2 license that can be found in the LICENSE file.

Copyright 2016 The gta AUTHORS. All rights reserved.

Use of this source code is governed by the Apache 2 license that can be found in the LICENSE file.

Copyright 2016 The gta AUTHORS. All rights reserved.

Use of this source code is governed by the Apache 2 license that can be found in the LICENSE file.

Index

• Variables
• type Differ
  • func NewFileDiffer(files []string) Differ
  • func NewGitDiffer(opts ...GitDifferOption) Differ
• type Directory
• type GTA
  • func New(opts ...Option) (*GTA, error)
  • func (g *GTA) ChangedPackages() (*Packages, error)
• type GitDifferOption
  • func SetBaseBranch(baseBranch string) GitDifferOption
  • func SetUseMergeCommit(useMergeCommit bool) GitDifferOption
• type Graph
  • func (g *Graph) Traverse(node string, mark map[string]bool)
• type Option
  • func SetDiffer(d Differ) Option
  • func SetPackager(p Packager) Option
  • func SetPrefixes(prefixes ...string) Option
  • func SetTags(tags ...string) Option
• type Package
• type Packager
  • func NewPackager(patterns, tags []string) Packager
• type Packages
  • func (p *Packages) MarshalJSON() ([]byte, error)
  • func (p *Packages) UnmarshalJSON(b []byte) error

Variables

var (
	// ErrNoDiffer is returned when there is no differ set on the GTA.
	ErrNoDiffer = errors.New("there is no differ set")
	// ErrNoPackager is returned when there is no packager set on the GTA.
	ErrNoPackager = errors.New("there is no packager set")
)

Types

type Differ

type Differ interface {
	// Diff returns a set of absolute pathed directories that have files that
	// have been modified.
	Diff() (map[string]Directory, error)

	// DiffFiles returns a map whose keys are absolute files paths. A map value
	// is true when the file exists.
	DiffFiles() (map[string]bool, error)
}

A Differ implements provides methods that return values to understand the directories and files that have changed. and the dirs they in which occur.

func NewFileDiffer

func NewFileDiffer(files []string) Differ

NewFileDiffer returns a Differ that operates on a list of absolute paths of changed files.

func NewGitDiffer

func NewGitDiffer(opts ...GitDifferOption) Differ

NewGitDiffer returns a Differ that determines differences using git.

type Directory

type Directory struct {
	Exists bool
	Files  []string
}

A Directory describes changes to a directory and its contents.

type GTA

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

A GTA provides a method of building dirty packages, and their dependent packages.

func New

func New(opts ...Option) (*GTA, error)

New returns a new GTA with various options passed to New. Options will be applied in order so that later options can override earlier options.

func (*GTA) ChangedPackages

func (g *GTA) ChangedPackages() (*Packages, error)

ChangedPackages uses the differ and packager to build a map of changed root packages to their dependent packages where dependent is defined as "changed" as well due to their dependency to the changed packages. It returns the dependency graph, the changes differ detected and a set of all unique packages (including the changes).

As an example: package "foo" is imported by packages "bar" and "qux". If "foo" has changed, it has two dependent packages, "bar" and "qux". The result would be then:

Dependencies = {"foo": ["bar", "qux"]}
Changes      = ["foo"]
AllChanges   = ["foo", "bar", "qux]

Note that two different changed package might have the same dependent package. Below you see that both "foo" and "foo2" has changed. Each have "bar" because "bar" imports both "foo" and "foo2", i.e:

Dependencies = {"foo": ["bar", "qux"], "foo2" : ["afa", "bar", "qux"]}
Changes      = ["foo", "foo2"]
AllChanges   = ["foo", "foo2", "afa", "bar", "qux]

type GitDifferOption

type GitDifferOption func(*git)

GitDifferOption is an option function used to modify a git differ

func SetBaseBranch

func SetBaseBranch(baseBranch string) GitDifferOption

SetBaseBranch sets the baseBranch field on a git differ

func SetUseMergeCommit

func SetUseMergeCommit(useMergeCommit bool) GitDifferOption

SetUseMergeCommit sets the useMergeCommit field on a git differ

type Graph

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

Graph is an adjacency list representation of a graph using maps.

func (*Graph) Traverse

func (g *Graph) Traverse(node string, mark map[string]bool)

Traverse is a simple recursive depth first traversal of a directed cyclic graph.

type Option

type Option func(*GTA) error

Option is an option function used to modify a GTA.

func SetDiffer

func SetDiffer(d Differ) Option

SetDiffer sets a differ on a GTA.

func SetPackager

func SetPackager(p Packager) Option

SetPackager sets a packager on a GTA.

func SetPrefixes

func SetPrefixes(prefixes ...string) Option

SetPrefixes sets a list of prefix to be included

func SetTags

func SetTags(tags ...string) Option

SetTags sets a list of build tags to consider.

type Package

type Package struct {
	ImportPath string

	// Dir the absolute path of the directory containing the package.
	// bug(bc): this is currently unreliable and in GOPATH mode only identifies
	// the src directory for the GOPATH that hosts the package.  Currently, the
	// only guarantee is that Dir will not be empty when the package exists.
	Dir string
}

type Packager

type Packager interface {
	// Get a go package from directory. Should return a *build.NoGoError value
	// when there are no Go files in the directory.
	PackageFromDir(string) (*Package, error)
	// Get a go package from an empty directory.
	PackageFromEmptyDir(string) (*Package, error)
	// Get a go package from import path. Should return a *build.NoGoError value
	// when there are no Go files in the directory.
	PackageFromImport(string) (*Package, error)
	// DependentGraph returns the DependentGraph for the current
	// Golang workspace as defined by their import paths.
	DependentGraph() (*Graph, error)
	// EmbeddedBy returns the package import paths of packages that embed a file.
	EmbeddedBy(string) []string
}

Packager interface defines a set of means to access golang build Package information.

func NewPackager

func NewPackager(patterns, tags []string) Packager

type Packages

type Packages struct {
	// Dependencies contains a map of changed packages to their dependencies
	Dependencies map[string][]Package

	// Changes represents the changed files
	Changes []Package

	// AllChanges represents all packages that are dirty including the initial
	// changed packages.
	AllChanges []Package
}

Packages contains various detailed information about the structure of packages GTA has detected.

func (*Packages) MarshalJSON

func (p *Packages) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*Packages) UnmarshalJSON

func (p *Packages) UnmarshalJSON(b []byte) error

UnmarshalJSON used by gtartifacts when providing a changed package list see `useChangedPackagesFrom()`