Concise guide to golang/dep

Overview

This gist is based on the information available at golang/dep, only slightly more terse and annotated with a few notes and links primarily for my own personal benefit. It's public in case this information is helpful to anyone else as well.

I initially advocated Glide for my team and then, more recently, vndr. I've also taken the approach of exerting direct control over what goes into vendor/ in my Dockerfiles, and also work from isolated GOPATH environments on my system per project to ensure that dependencies are explicitly found under vendor/.

At the end of the day, vendoring (and committing vendor/) is about being in control of your dependencies and being able to achieve reproducible builds. While you can achieve this manually, things that are nice to have in a vendoring tool include:

automated ability to determine all of a project's dependencies
identify the latest version of a package that satisifies all dependencies in the dependency graph
ability to specify a range of acceptable versions of packages that satisfy the project's dependencies
ability to pin the range of acceptable versions to a set of explicit versions used for reproducible builds
ability to prune any unnecessary packages from the resulting vendor set

Because it looks like dep is the future for Go vendoring, it makes sense to embrace dep now even though it is still undergoing change until it is merged into the toolchain and reaches a v1 release. As noted in the roadmap, there is no "guarantee dep will be accepted"; yet, nevertheless, there appears to be a good deal of momentum behind dep at this point.

Get (or update) dep

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

Initialize your project

Run dep init to initialize your project.

dep will analyize your project, identify your dependencies, pick the highest compatible version for each dependency, generate a Gopkg.toml manifest and Gopkg.lock files (see here for background on the two file format), and install dependencies in vendor/.

$ dep init

Notes

If you are already using glide, godep, vndr, or govend, dep will convert the existing dependency management file. See this issue and this interface for implementing configuration importers.

If you have an existing vendor/ directory, it will be backed up to _vendor-TIMESTAMP/.

You can tell dep to resolve dependencies from GOPATH before resorting to network mode with dep init -gopath. See here for a bit more detail.

Usage

Installing dependencies

Run dep ensure to ensure vendor/ is in the correct state for your configuration.

$ dep ensure

dep's solver regenerates Gopkg.lock if it detects any change in your code imports and/or Gopkg.toml. If this is the case, then the new Gopkg.lock file is used to completely rewrite vendor/ (at some point vendor verification will allow the contents of vendor/ to also be checked for consistency with Gopkg.lock, updating only what is necessary to make the contents current).

Note

This process may be slow for large projects, especially the first time as dependencies are cloned or when it hasn't been run in a while and there are many changesets to fetch. dep manages a cache at $GOPATH/pkg/dep to mitigate fetch overhead. See here for further details.

There are a number of variations to this command. Run dep ensure -examples for details. One in particular to note that may be relevant when creating a Dockerfile is dep ensure -vendor-only.

Adding a dependency

Use dep ensure -add to update your configuration with a new dependency.

$ dep ensure -add github.com/foo/bar github.com/foo/baz...

dep will update your Gopkg.toml, Gopkg.lock, and vendor/ to the latest version unless version constraints are applied; for example:

$ dep ensure -add github.com/foo/[email protected] github.com/foo/baz@master

Checking status of dependencies

Use this to detect a mismatch between the configuration and state of your project

One way this can happen is when you import a package that is resolved when you build because it is found in your GOPATH, but it has not been added to your configuration (and therefore is not present in the generated Gopkg.lock file).

$ dep status

Use this information to update your configuration with dep ensure -add as appropriate.

Updating dependencies

dep will update your dependencies to the latest versions that satisify the constraints specified in Gopkg.toml.

Preferred

$ dep ensure -update github.com/foo/bar github.com/foo/baz...

Possible, but being specific is preferred

$ dep ensure -update

Note

The latest version means the latest version in a semver range or if depending on a branch, the tip of the branch.

Removing dependencies

Remove the relevant import package statements and usage in your code
Remove the relevant [[constraint]] rules from Gopkg.toml
Run dep ensure

Editing packages that are dependencies of your project

Your project may rely on dependencies that you wish to edit. These dependencies should not be updated directly under vendor/ since they can be overwritted by dep. Instead, volatile dependencies should be removed manually from under vendor/ and then placed in the appropriate location in your $GOPATH. When building, Go will first search your vendor/ directory, then it will search your $GOPATH.

If the package update has been pushed to its public repo, then simply run dep ensure -update as described in Changing Dependencies.

Gopkg.toml

While dep init will generate a Gopkg.toml file and dep ensure -add will add new dependencies to it, there are occasions where you will need to edit this file manually besides when removing a dependency. The format is straightforward and consists of the following elements:

required
ignored
metadata (under the root as well as under constraint and override declarations; ignored by dep)
constraint
override
version (a property of constraint and override declarations)