dep

README

Dep

Linux: | Windows: |

Dep is a prototype dependency management tool. It requires Go 1.7 or newer to compile.

dep is NOT an official tool. Yet. Check out the Roadmap!

Current status

Alpha. Functionality is known to be broken, missing or incomplete. Command and file format changes are still planned. The repository is open to solicit feedback and contributions from the community. Please see below for feedback and contribution guidelines.

Context

• The Saga of Go Dependency Management
• Official Google Docs
  • Go Packaging Proposal Process
  • User Stories
  • Features
  • Design Space
• Frequently Asked Questions

Usage

Get the tool via

$ go get -u github.com/golang/dep/cmd/dep

Typical usage on a new repo might be

$ dep init
$ dep ensure -update

To update a dependency to a new version, you might run

$ dep ensure github.com/pkg/errors@^0.8.0

See the help text for much more detailed usage instructions.

Note that the manifest and lock file formats are not finalized, and will likely change before the tool is released. We make no compatibility guarantees for the time being. Please don't commit any code or files created with the tool.

Feedback

Feedback is greatly appreciated. At this stage, the maintainers are most interested in feedback centered on the user experience (UX) of the tool. Do you have workflows that the tool supports well, or doesn't support at all? Do any of the commands have surprising effects, output, or results? Please check the existing issues and FAQ to see if your feedback has already been reported. If not, please file an issue, describing what you did or wanted to do, what you expected to happen, and what actually happened.

Contributing

Contributions are greatly appreciated. The maintainers actively manage the issues list, and try to highlight issues suitable for newcomers. The project follows the typical GitHub pull request model. See CONTRIBUTING.md for more details. Before starting any work, please either comment on an existing issue, or file a new one.

Documentation

Index

• Constants
• func BackupVendor(vpath, suffix string) (string, error)
• func PruneProject(p *Project, sm gps.SourceManager, logger *log.Logger) error
• type Analyzer
  • func (a Analyzer) DeriveManifestAndLock(path string, n gps.ProjectRoot) (gps.Manifest, gps.Lock, error)
  • func (a Analyzer) Info() (string, int)
• type Ctx
  • func NewContext(wd string, env []string, loggers *Loggers) (*Ctx, error)
  • func (c *Ctx) LoadProject(path string) (*Project, error)
  • func (c *Ctx) SourceManager() (*gps.SourceMgr, error)
  • func (c *Ctx) SplitAbsoluteProjectRoot(path string) (string, error)
  • func (c *Ctx) VersionInWorkspace(root gps.ProjectRoot) (gps.Version, error)
• type Lock
  • func LockFromSolution(in gps.Solution) *Lock
  • func (l *Lock) InputHash() []byte
  • func (l *Lock) MarshalTOML() ([]byte, error)
  • func (l *Lock) Projects() []gps.LockedProject
• type Loggers
• type Manifest
  • func (m *Manifest) DependencyConstraints() gps.ProjectConstraints
  • func (m *Manifest) IgnoredPackages() map[string]bool
  • func (m *Manifest) MarshalTOML() ([]byte, error)
  • func (m *Manifest) Overrides() gps.ProjectConstraints
  • func (m *Manifest) RequiredPackages() map[string]bool
  • func (m *Manifest) TestDependencyConstraints() gps.ProjectConstraints
• type Project
  • func (p *Project) MakeParams() gps.SolveParameters
• type SafeWriter
  • func NewSafeWriter(manifest *Manifest, oldLock, newLock *Lock, vendor VendorBehavior) (*SafeWriter, error)
  • func (sw *SafeWriter) HasLock() bool
  • func (sw *SafeWriter) HasManifest() bool
  • func (sw *SafeWriter) PrintPreparedActions(output *log.Logger) error
  • func (sw *SafeWriter) Write(root string, sm gps.SourceManager, noExamples bool) error
• type SolveMeta
• type SortedLockedProjects
  • func (s SortedLockedProjects) Len() int
  • func (s SortedLockedProjects) Less(i, j int) bool
  • func (s SortedLockedProjects) Swap(i, j int)
• type VendorBehavior

Constants

const LockName = "Gopkg.lock"

const ManifestName = "Gopkg.toml"

Functions

func BackupVendor

func BackupVendor(vpath, suffix string) (string, error)

BackupVendor looks for existing vendor directory and if it's not empty, creates a backup of it to a new directory with the provided suffix.

func PruneProject

func PruneProject(p *Project, sm gps.SourceManager, logger *log.Logger) error

Types

type Analyzer

type Analyzer struct{}

func (Analyzer) DeriveManifestAndLock

func (a Analyzer) DeriveManifestAndLock(path string, n gps.ProjectRoot) (gps.Manifest, gps.Lock, error)

func (Analyzer) Info

func (a Analyzer) Info() (string, int)

type Ctx

type Ctx struct {
	GOPATH     string   // Selected Go path
	GOPATHS    []string // Other Go paths
	WorkingDir string
	*Loggers
}

Ctx defines the supporting context of the tool.

func NewContext

func NewContext(wd string, env []string, loggers *Loggers) (*Ctx, error)

NewContext creates a struct with the project's GOPATH. It assumes that of your "GOPATH"'s we want the one we are currently in.

func (*Ctx) LoadProject

func (c *Ctx) LoadProject(path string) (*Project, error)

LoadProject takes a path and searches up the directory tree for a project root. If an absolute path is given, the search begins in that directory. If a relative or empty path is given, the search start is computed from the current working directory. The search stops when a file with the name ManifestName (Gopkg.toml, by default) is located.

The Project contains the parsed manifest as well as a parsed lock file, if present. The import path is calculated as the remaining path segment below Ctx.GOPATH/src.

func (*Ctx) SourceManager

func (c *Ctx) SourceManager() (*gps.SourceMgr, error)

func (*Ctx) SplitAbsoluteProjectRoot

func (c *Ctx) SplitAbsoluteProjectRoot(path string) (string, error)

SplitAbsoluteProjectRoot takes an absolute path and compares it against declared GOPATH(s) to determine what portion of the input path should be treated as an import path - as a project root.

The second returned string indicates which GOPATH value was used.

func (*Ctx) VersionInWorkspace

func (c *Ctx) VersionInWorkspace(root gps.ProjectRoot) (gps.Version, error)

type Lock

type Lock struct {
	SolveMeta SolveMeta
	P         []gps.LockedProject
}

func LockFromSolution

func LockFromSolution(in gps.Solution) *Lock

LockFromSolution converts a gps.Solution to dep's representation of a lock.

Data is defensively copied wherever necessary to ensure the resulting *lock shares no memory with the original lock.

func (*Lock) InputHash

func (l *Lock) InputHash() []byte

func (*Lock) MarshalTOML

func (l *Lock) MarshalTOML() ([]byte, error)

func (*Lock) Projects

func (l *Lock) Projects() []gps.LockedProject

type Loggers

type Loggers struct {
	Out, Err *log.Logger
	// Whether verbose logging is enabled.
	Verbose bool
}

Loggers holds standard loggers and a verbosity flag.

type Manifest

type Manifest struct {
	Constraints gps.ProjectConstraints
	Ovr         gps.ProjectConstraints
	Ignored     []string
	Required    []string
}

func (*Manifest) DependencyConstraints

func (m *Manifest) DependencyConstraints() gps.ProjectConstraints

func (*Manifest) IgnoredPackages

func (m *Manifest) IgnoredPackages() map[string]bool

func (*Manifest) MarshalTOML

func (m *Manifest) MarshalTOML() ([]byte, error)

func (*Manifest) Overrides

func (m *Manifest) Overrides() gps.ProjectConstraints

func (*Manifest) RequiredPackages

func (m *Manifest) RequiredPackages() map[string]bool

func (*Manifest) TestDependencyConstraints

func (m *Manifest) TestDependencyConstraints() gps.ProjectConstraints

type Project

type Project struct {
	// AbsRoot is the absolute path to the root directory of the project.
	AbsRoot string
	// ImportRoot is the import path of the project's root directory.
	ImportRoot gps.ProjectRoot
	Manifest   *Manifest
	Lock       *Lock
}

func (*Project) MakeParams

func (p *Project) MakeParams() gps.SolveParameters

MakeParams is a simple helper to create a gps.SolveParameters without setting any nils incorrectly.

type SafeWriter

type SafeWriter struct {
	Manifest *Manifest
	// contains filtered or unexported fields
}

SafeWriter transactionalizes writes of manifest, lock, and vendor dir, both individually and in any combination, into a pseudo-atomic action with transactional rollback.

It is not impervious to errors (writing to disk is hard), but it should guard against non-arcane failure conditions.

func NewSafeWriter

func NewSafeWriter(manifest *Manifest, oldLock, newLock *Lock, vendor VendorBehavior) (*SafeWriter, error)

NewSafeWriter sets up a SafeWriter to write a set of config yaml, lock and vendor tree.

• If manifest is provided, it will be written to the standard manifest file name beneath root.
• If newLock is provided, it will be written to the standard lock file name beneath root.
• If vendor is VendorAlways, or is VendorOnChanged and the locks are different, the vendor directory will be written beneath root based on newLock.
• If oldLock is provided without newLock, error.
• If vendor is VendorAlways without a newLock, error.

func (*SafeWriter) HasLock

func (sw *SafeWriter) HasLock() bool

HasLock checks if a Lock is present in the SafeWriter

func (*SafeWriter) HasManifest

func (sw *SafeWriter) HasManifest() bool

HasManifest checks if a Manifest is present in the SafeWriter

func (*SafeWriter) PrintPreparedActions

func (sw *SafeWriter) PrintPreparedActions(output *log.Logger) error

func (*SafeWriter) Write

func (sw *SafeWriter) Write(root string, sm gps.SourceManager, noExamples bool) error

Write saves some combination of config yaml, lock, and a vendor tree. root is the absolute path of root dir in which to write. sm is only required if vendor is being written.

It first writes to a temp dir, then moves them in place if and only if all the write operations succeeded. It also does its best to roll back if any moves fail. This mostly guarantees that dep cannot exit with a partial write that would leave an undefined state on disk.

type SolveMeta

type SolveMeta struct {
	InputsDigest    []byte
	AnalyzerName    string
	AnalyzerVersion int
	SolverName      string
	SolverVersion   int
}

type SortedLockedProjects

type SortedLockedProjects []gps.LockedProject

func (SortedLockedProjects) Len

func (s SortedLockedProjects) Len() int

func (SortedLockedProjects) Less

func (s SortedLockedProjects) Less(i, j int) bool

func (SortedLockedProjects) Swap

func (s SortedLockedProjects) Swap(i, j int)

type VendorBehavior

type VendorBehavior int

VendorBehavior defines when the vendor directory should be written.

const (
	// VendorOnChanged indicates that the vendor directory should be written when the lock is new or changed.
	VendorOnChanged VendorBehavior = iota
	// VendorAlways forces the vendor directory to always be written.
	VendorAlways
	// VendorNever indicates the vendor directory should never be written.
	VendorNever
)