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

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 CopyDir(src string, dest string) error
• func CopyFile(src string, dest string) error
• func IsDir(name string) (bool, error)
• func IsNonEmptyDir(name string) (bool, error)
• func IsRegular(name string) (bool, error)
• func PruneProject(p *Project, sm gps.SourceManager) 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() (*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 LockFromInterface(in gps.Lock) *Lock
  • func (l *Lock) InputHash() []byte
  • func (l *Lock) MarshalTOML() ([]byte, error)
  • func (l *Lock) Projects() []gps.LockedProject
• type Manifest
  • func (m *Manifest) DependencyConstraints() gps.ProjectConstraints
  • func (m *Manifest) IgnoredPackages() map[string]bool
  • func (m *Manifest) IsEmpty() 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 (sw *SafeWriter) Prepare(manifest *Manifest, oldLock, newLock *Lock, vendor VendorBehavior) error
  • func (sw *SafeWriter) PrintPreparedActions() error
  • func (sw *SafeWriter) Write(root string, sm gps.SourceManager) error
• type SafeWriterPayload
  • func (payload *SafeWriterPayload) HasLock() bool
  • func (payload *SafeWriterPayload) HasManifest() bool
  • func (payload *SafeWriterPayload) HasVendor() bool
• 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 CopyDir

func CopyDir(src string, dest string) error

CopyDir takes in a directory and copies its contents to the destination. It preserves the file mode on files as well.

func CopyFile

func CopyFile(src string, dest string) error

CopyFile copies a file from one place to another with the permission bits preserved as well.

func IsDir

func IsDir(name string) (bool, error)

func IsNonEmptyDir

func IsNonEmptyDir(name string) (bool, error)

func IsRegular

func IsRegular(name string) (bool, error)

func PruneProject

func PruneProject(p *Project, sm gps.SourceManager) 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
}

Ctx defines the supporting context of the tool.

func NewContext

func NewContext() (*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 {
	Memo []byte
	P    []gps.LockedProject
}

func LockFromInterface

func LockFromInterface(in gps.Lock) *Lock

LockFromInterface converts an arbitrary gps.Lock to dep's representation of a lock. If the input is already dep's *lock, the input is returned directly.

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

As gps.Solution is a superset of gps.Lock, this can also be used to convert solutions to dep's lock format.

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 Manifest

type Manifest struct {
	Dependencies 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) IsEmpty

func (m *Manifest) IsEmpty() bool

IsEmpty - Checks if payload is empty

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 {
	Payload *SafeWriterPayload
}

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 (*SafeWriter) Prepare

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

Prepare 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) PrintPreparedActions

func (sw *SafeWriter) PrintPreparedActions() error

func (*SafeWriter) Write

func (sw *SafeWriter) Write(root string, sm gps.SourceManager) 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 SafeWriterPayload

type SafeWriterPayload struct {
	Manifest    *Manifest
	Lock        *Lock
	LockDiff    *gps.LockDiff
	WriteVendor bool
}

SafeWriterPayload represents the actions SafeWriter will execute when SafeWriter.Write is called.

func (*SafeWriterPayload) HasLock

func (payload *SafeWriterPayload) HasLock() bool

func (*SafeWriterPayload) HasManifest

func (payload *SafeWriterPayload) HasManifest() bool

func (*SafeWriterPayload) HasVendor

func (payload *SafeWriterPayload) HasVendor() bool

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
)