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
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
dep initto 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
$ dep init
If you have an existing
vendor/ directory, it will be backed up to
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.
dep ensureto 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).
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
dep ensure -addto update your configuration with a new dependency.
$ dep ensure -add github.com/foo/bar github.com/foo/baz...
dep will update your
vendor/ to the latest version unless version constraints
are applied; for example:
$ dep ensure -add firstname.lastname@example.org 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
GOPATH, but it has not been added to your configuration (and therefore is not present in the
$ dep status
Use this information to update your configuration with
dep ensure -add as appropriate.
dep will update your dependencies to the latest versions that satisify the constraints specified in
$ dep ensure -update github.com/foo/bar github.com/foo/baz...
Possible, but being specific is preferred
$ dep ensure -update
The latest version means the latest version in a semver range or if depending on a branch, the tip of the branch.
- Remove the relevant
importpackage statements and usage in your code
- Remove the relevant
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
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
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:
metadata(under the root as well as under
overridedeclarations; ignored by dep)
version(a property of
There are important (and subtle) details involved, so it is best to read the spec directly.