required
lists a set of packages (not projects) that must be included in
Gopkg.lock. This list is merged with the set of packages imported by the current
project.
required = ["github.com/user/thing/cmd/thing"]
Use this for: linters, generators, and other development tools that
- Are needed by your project
- Aren't
import
ed by your project, directly or transitively - You don't want put in your
GOPATH
, and/or you want to lock the version
Please note that this only pulls in the sources of these dependencies. It does not install or compile them. So, if you need the tool to be installed you should still run the following (manually or from a Makefile
) after each dep ensure
:
cd vendor/pkg/to/install
go install .
This only works reliably if this is the only project to install these executables. This is not enough if you want to be able to run a different version of the same executable depending on the project you're working. In that case you have to use a different GOBIN
for each project, by doing something like this before running the above commands:
export GOBIN=$PWD/bin
export PATH=$GOBIN:$PATH
You might also try virtualgo, which installs dependencies in the required
list automatically in a project specific GOBIN
.
ignored
lists a set of packages (not projects) that are ignored when dep statically analyzes source code. Ignored packages can be in this project, or in a dependency.
ignored = ["github.com/user/project/badpkg"]
Use this for: preventing a package and any of that package's unique dependencies from being installed.
metadata
can exist at the root as well as under constraint
and override
declarations.
metadata
declarations are ignored by dep and are meant for usage by other independent systems.
A metadata
declaration at the root defines metadata about the project itself. While a metadata
declaration under a constraint
or an override
defines metadata about that constraint
or override
.
[metadata]
key1 = "value that convey data to other systems"
system1-data = "value that is used by a system"
system2-data = "value that is used by another system"
A constraint
provides rules for how a direct dependency may be incorporated into the
dependency graph.
They are respected by dep whether coming from the Gopkg.toml of the current project or a dependency.
[[constraint]]
# Required: the root import path of the project being constrained.
name = "github.com/user/project"
# Recommended: the version constraint to enforce for the project.
# Only one of "branch", "version" or "revision" can be specified.
version = "1.0.0"
branch = "master"
revision = "abc123"
# Optional: an alternate location (URL or import path) for the project's source.
source = "https://github.com/myfork/package.git"
# Optional: metadata about the constraint or override that could be used by other independent systems
[metadata]
key1 = "value that convey data to other systems"
system1-data = "value that is used by a system"
system2-data = "value that is used by another system"
Use this for: having a direct dependency use a specific branch, version range, revision, or alternate source (such as a fork).
An override
has the same structure as a constraint
declaration, but supersede all constraint
declarations from all projects. Only override
declarations from the current project's Gopkg.toml
are applied.
[[override]]
# Required: the root import path of the project being constrained.
name = "github.com/user/project"
# Optional: specifying a version constraint override will cause all other constraints on this project to be ignored; only the overridden constraint needs to be satisfied. Again, only one of "branch", "version" or "revision" can be specified.
version = "1.0.0"
branch = "master"
revision = "abc123"
# Optional: specifying an alternate source location as an override will enforce that the alternate location is used for that project, regardless of what source location any dependent projects specify.
source = "https://github.com/myfork/package.git"
# Optional: metadata about the constraint or override that could be used by other independent systems
[metadata]
key1 = "value that convey data to other systems"
system1-data = "value that is used by a system"
system2-data = "value that is used by another system"
Use this for: all the same things as a constraint
, but for
transitive dependencies.
See How do I constrain a transitive dependency's version?
for more details on how overrides differ from constraint
s. Overrides should
be used cautiously, sparingly, and temporarily.
version
is a property of constraint
s and override
s. It is used to specify
version constraint of a specific dependency.
Internally, dep uses Masterminds/semver to work with semver versioning.
~
and =
operators can be used with the versions. When a version is specified
without any operator, dep
automatically adds a caret operator, ^
. The caret
operator pins the left-most non-zero digit in the version. For example:
^1.2.3 means 1.2.3 <= X < 2.0.0
^0.2.3 means 0.2.3 <= X < 0.3.0
^0.0.3 means 0.0.3 <= X < 0.1.0
To pin a version of direct dependency in manifest, prefix the version with =
.
For example:
[[constraint]]
name = "github.com/pkg/errors"
version = "=0.8.0"
Why is dep ignoring a version constraint in the manifest?
Here's an example of a sample Gopkg.toml with most of the elements
required = ["github.com/user/thing/cmd/thing"]
ignored = ["github.com/user/project/pkgX", "bitbucket.org/user/project/pkgA/pkgY"]
[metadata]
codename = "foo"
[[constraint]]
name = "github.com/user/project"
version = "1.0.0"
[metadata]
property1 = "value1"
property2 = 10
[[constraint]]
name = "github.com/user/project2"
branch = "dev"
source = "github.com/myfork/project2"
[[override]]
name = "github.com/x/y"
version = "2.4.0"
[metadata]
propertyX = "valueX"