README ¶
Dep
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
dep
is safe for production use. That means two things:
- Any valid metadata file (
Gopkg.toml
andGopkg.lock
) will be readable and considered valid by any future version ofdep
. - Generally speaking, it has comparable or fewer bugs than other tools out there.
That said, keep in mind the following:
dep
is still changing rapidly. If you need stability (e.g. for CI), it's best to rely on a released version, not tip.- Some changes are pending to the CLI interface. Scripting on dep before they land is unwise.
dep
's exported API interface will continue to change in unpredictable, backwards-incompatible ways until we tag a v1.0.0 release.
Context
- The Saga of Go Dependency Management
- Official Google Docs
- Frequently Asked Questions
Setup
Get the tool via
$ go get -u github.com/golang/dep/cmd/dep
To start managing dependencies using dep, run the following from your project root directory:
$ dep init
This does the following:
- Look for existing dependency management files to convert
- Check if your dependencies use dep
- Identify your dependencies
- Back up your existing
vendor/
directory (if you have one) to_vendor-TIMESTAMP/
- Pick the highest compatible version for each dependency
- Generate
Gopkg.toml
("manifest") andGopkg.lock
files - Install the dependencies in
vendor/
Usage
There is one main subcommand you will use: dep ensure
. ensure
first makes
sure Gopkg.lock
is consistent with your import
s and Gopkg.toml
. If any
changes are detected, it then populates vendor/
with exactly what's described
in Gopkg.lock
.
dep ensure
is safe to run early and often. See the help text for more detailed
usage instructions.
$ dep help ensure
Installing dependencies
(if your vendor/
directory isn't checked in with your code)
$ dep ensure
If a dependency already exists in your vendor/
folder, dep will ensure it
matches the constraints from the manifest. If the dependency is missing from
vendor/
, the latest version allowed by your manifest will be installed.
Adding a dependency
-
import
the package in your*.go
source code file(s). -
Run the following command to update your
Gopkg.lock
and populatevendor/
with the new dependency.$ dep ensure
Changing dependencies
If you want to:
- Change the allowed
version
/branch
/revision
- Switch to using a fork
for one or more dependencies, do the following:
-
Modify your
Gopkg.toml
. -
Run
$ dep ensure
Checking the status of dependencies
Run dep status
to see the current status of all your dependencies.
$ dep status
PROJECT CONSTRAINT VERSION REVISION LATEST
github.com/Masterminds/semver branch 2.x branch 2.x 139cc09 c2e7f6c
github.com/Masterminds/vcs ^1.11.0 v1.11.1 3084677 3084677
github.com/armon/go-radix * branch master 4239b77 4239b77
On top of that, if you have added new imports to your project or modified the manifest file without running dep ensure
again, dep status
will tell you there is a mismatch between the lock file and the current status of the project.
$ dep status
Lock inputs-digest mismatch due to the following packages missing from the lock:
PROJECT MISSING PACKAGES
github.com/Masterminds/goutils [github.com/Masterminds/goutils]
This happens when a new import is added. Run `dep ensure` to install the missing packages.
As dep status
suggests, run dep ensure
to update your lockfile. Then run dep status
again, and the lock mismatch should go away.
Updating dependencies
(to the latest version allowed by the manifest)
$ dep ensure -update
Removing dependencies
-
Remove the
import
s and all usage from your code. -
Run
$ dep ensure
-
Remove from
Gopkg.toml
, if it was in there.
Testing changes to a dependency
Making changes in your vendor/
directory directly is not recommended, as dep
will overwrite any changes. Instead:
-
Delete the dependency from the
vendor/
directory.rm -rf vendor/<dependency>
-
Add that dependency to your
GOPATH
, if it isn't already.$ go get <dependency>
-
Modify the dependency in
$GOPATH/src/<dependency>
. -
Test, build, etc.
Don't run dep ensure
until you're done. dep ensure
will reinstall the
dependency into vendor/
based on your manifest, as if you were installing from
scratch.
This solution works for short-term use, but for something long-term, take a look at virtualgo.
To test out code that has been pushed as a new version, or to a branch or fork, see changing dependencies.
Semantic Versioning
dep ensure
a uses an external semver library to interpret the version constraints you specify in the manifest. The comparison operators are:
=
: equal!=
: not equal>
: greater than<
: less than>=
: greater than or equal to<=
: less than or equal to-
: literal range. Eg: 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5~
: minor range. Eg: ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0^
: major range. Eg: ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0[xX*]
: wildcard. Eg: 1.2.x is equivalent to >= 1.2.0, < 1.3.0
You might, for example, include a constraint in your manifest that specifies version = "=2.0.0"
to pin a dependency to version 2.0.0, or constrain to minor releases with: version = "2.*"
. Refer to the semver library documentation for more info.
Note: When you specify a version without an operator, dep
automatically uses the ^
operator by default. dep ensure
will interpret the given version as the min-boundry of a range, for example:
1.2.3
becomes the range>=1.2.3, <2.0.0
0.2.3
becomes the range>=0.2.3, <0.3.0
0.0.3
becomes the range>=0.0.3, <0.1.0
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 ¶
Overview ¶
Package dep is a prototype dependency management library.
Index ¶
- Constants
- func BackupVendor(vpath, suffix string) (string, error)
- type Analyzer
- type Ctx
- func (c *Ctx) AbsForImport(path string) (string, error)
- func (c *Ctx) DetectProjectGOPATH(p *Project) (string, error)
- func (c *Ctx) ImportForAbs(path string) (string, error)
- func (c *Ctx) LoadProject() (*Project, error)
- func (c *Ctx) SetPaths(wd string, GOPATHs ...string) error
- func (c *Ctx) SourceManager() (*gps.SourceMgr, error)
- type Lock
- type Manifest
- func (m *Manifest) DependencyConstraints() gps.ProjectConstraints
- func (m *Manifest) HasConstraintsOn(root gps.ProjectRoot) bool
- 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
- type Project
- type SafeWriter
- type SolveMeta
- type SortedLockedProjects
- type VendorBehavior
Constants ¶
const LockName = "Gopkg.lock"
LockName is the lock file name used by dep.
const ManifestName = "Gopkg.toml"
ManifestName is the manifest file name used by dep.
Variables ¶
This section is empty.
Functions ¶
func BackupVendor ¶
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.
Types ¶
type Analyzer ¶
type Analyzer struct{}
Analyzer implements gps.ProjectAnalyzer.
func (Analyzer) DeriveManifestAndLock ¶
func (a Analyzer) DeriveManifestAndLock(path string, n gps.ProjectRoot) (gps.Manifest, gps.Lock, error)
DeriveManifestAndLock reads and returns the manifest at path/ManifestName or nil if one is not found. The Lock is always nil for now.
func (Analyzer) HasDepMetadata ¶ added in v0.2.0
HasDepMetadata determines if a dep manifest exists at the specified path.
func (Analyzer) Info ¶
func (a Analyzer) Info() gps.ProjectAnalyzerInfo
Info returns Analyzer's name and version info.
type Ctx ¶
type Ctx struct { WorkingDir string // Where to execute. GOPATH string // Selected Go path, containing WorkingDir. GOPATHs []string // Other Go paths. Out, Err *log.Logger // Required loggers. Verbose bool // Enables more verbose logging. }
Ctx defines the supporting context of dep.
A properly initialized Ctx has a GOPATH containing the project root and non-nil Loggers.
ctx := &dep.Ctx{ WorkingDir: GOPATH + "/src/project/root", GOPATH: GOPATH, Out: log.New(os.Stdout, "", 0), Err: log.New(os.Stderr, "", 0), }
Ctx.DetectProjectGOPATH() helps with setting the containing GOPATH.
ctx.GOPATH, err := Ctx.DetectProjectGOPATH(project) if err != nil { // Could not determine which GOPATH to use for the project. }
func (*Ctx) AbsForImport ¶ added in v0.2.0
AbsForImport returns the absolute path for the project root including the $GOPATH. This will not work with stdlib packages and the package directory needs to exist.
func (*Ctx) DetectProjectGOPATH ¶ added in v0.2.0
DetectProjectGOPATH attempt to find the GOPATH containing the project.
If p.AbsRoot is not a symlink and is within a GOPATH, the GOPATH containing p.AbsRoot is returned. If p.AbsRoot is a symlink and is not within any known GOPATH, the GOPATH containing p.ResolvedAbsRoot is returned.
p.AbsRoot is assumed to be a symlink if it is not the same as p.ResolvedAbsRoot.
DetectProjectGOPATH will return an error in the following cases:
If p.AbsRoot is not a symlink and is not within any known GOPATH. If neither p.AbsRoot nor p.ResolvedAbsRoot are within a known GOPATH. If both p.AbsRoot and p.ResolvedAbsRoot are within the same GOPATH. If p.AbsRoot and p.ResolvedAbsRoot are each within a different GOPATH.
func (*Ctx) ImportForAbs ¶ added in v0.2.0
ImportForAbs returns the import path for an absolute project path by trimming the `$GOPATH/src/` prefix. Returns an error for paths equal to, or without this prefix.
func (*Ctx) LoadProject ¶
LoadProject starts from the current working directory and searches up the directory tree for a project root. 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.
type Lock ¶
type Lock struct { SolveMeta SolveMeta P []gps.LockedProject }
Lock holds lock file data and implements gps.Lock.
func LockFromSolution ¶
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) HasProjectWithRoot ¶ added in v0.3.0
func (l *Lock) HasProjectWithRoot(root gps.ProjectRoot) bool
HasProjectWithRoot checks if the lock contains a project with the provided ProjectRoot.
This check is O(n) in the number of projects.
func (*Lock) MarshalTOML ¶
MarshalTOML serializes this lock into TOML via an intermediate raw form.
func (*Lock) Projects ¶
func (l *Lock) Projects() []gps.LockedProject
Projects returns the list of LockedProjects contained in the lock data.
type Manifest ¶
type Manifest struct { Constraints gps.ProjectConstraints Ovr gps.ProjectConstraints Ignored []string Required []string }
Manifest holds manifest file data and implements gps.RootManifest.
func (*Manifest) DependencyConstraints ¶
func (m *Manifest) DependencyConstraints() gps.ProjectConstraints
DependencyConstraints returns a list of project-level constraints.
func (*Manifest) HasConstraintsOn ¶ added in v0.3.0
func (m *Manifest) HasConstraintsOn(root gps.ProjectRoot) bool
HasConstraintsOn checks if the manifest contains either constraints or overrides on the provided ProjectRoot.
func (*Manifest) IgnoredPackages ¶
IgnoredPackages returns a set of import paths to ignore.
func (*Manifest) MarshalTOML ¶
MarshalTOML serializes this manifest into TOML via an intermediate raw form.
func (*Manifest) Overrides ¶
func (m *Manifest) Overrides() gps.ProjectConstraints
Overrides returns a list of project-level override constraints.
func (*Manifest) RequiredPackages ¶
RequiredPackages returns a set of import paths to require.
type Project ¶
type Project struct { // AbsRoot is the absolute path to the root directory of the project. AbsRoot string // ResolvedAbsRoot is the resolved absolute path to the root directory of the project. // If AbsRoot is not a symlink, then ResolvedAbsRoot should equal AbsRoot. ResolvedAbsRoot string // ImportRoot is the import path of the project's root directory. ImportRoot gps.ProjectRoot Manifest *Manifest Lock *Lock // Optional }
A Project holds a Manifest and optional Lock for a project.
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 manifest, 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
PrintPreparedActions logs the actions a call to Write would perform.
func (*SafeWriter) Write ¶
func (sw *SafeWriter) Write(root string, sm gps.SourceManager, examples 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 }
SolveMeta holds solver meta data.
type SortedLockedProjects ¶
type SortedLockedProjects []gps.LockedProject
SortedLockedProjects implements sort.Interface.
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 )
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
dep
Command dep is a prototype dependency management tool.
|
Command dep is a prototype dependency management tool. |
hack
|
|
licenseok
Checks if all files have the license header, a lot of this is based off https://github.com/google/addlicense.
|
Checks if all files have the license header, a lot of this is based off https://github.com/google/addlicense. |
internal
|