You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Sep 9, 2020. It is now read-only.
The `Gopkg.toml` file is initially generated by `dep init`, and is primarily hand-edited. It contains several types of rule declarations that govern dep's behavior:
6
+
7
+
*[`constraints`](#constraint) and [`overrides`](#override) allow the user to specify which versions of dependencies are acceptable, and where they should be retrieved from.
8
+
*[`required`](#required) and [`ignored`](#ignored) allow the user to manipulate the import graph by including or excluding import paths, respectively.
9
+
*[`metadata`](#metadata) is a user-defined map of key-value pairs that dep will preserve and ignore.
10
+
11
+
Note that because of TOML does not adhere to a tree structure, the `required` and `ignored` fields must be declared before any `[[constraint]]` or `[[override]]`.
12
+
13
+
---
14
+
15
+
## `constraint`
16
+
17
+
A `constraint` provides rules for how a [direct dependency](FAQ.md#what-is-a-direct-or-transitive-dependency) may be incorporated into the dependency graph. dep respects these declarations from the current project's `Gopkg.toml`, as well as that of all dependencies.
18
+
19
+
```toml
20
+
[[constraint]]
21
+
# Required: the root import path of the project being constrained.
22
+
name = "github.com/user/project"
23
+
# Recommended: the version constraint to enforce for the project.
24
+
# Only one of "branch", "version" or "revision" can be specified.
25
+
version = "1.0.0"
26
+
branch = "master"
27
+
revision = "abc123"
28
+
29
+
# Optional: an alternate location (URL or import path) for the project's source.
# Optional: metadata about the constraint or override that could be used by other independent systems
33
+
[metadata]
34
+
key1 = "value that convey data to other systems"
35
+
system1-data = "value that is used by a system"
36
+
system2-data = "value that is used by another system"
37
+
```
38
+
39
+
**Use this for:** having a [direct dependency](FAQ.md#what-is-a-direct-or-transitive-dependency) use a specific branch, version range, revision, or alternate source (such as a fork).
40
+
41
+
## `override`
42
+
43
+
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.
44
+
45
+
```toml
46
+
[[override]]
47
+
# Required: the root import path of the project being constrained.
48
+
name = "github.com/user/project"
49
+
# 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.
50
+
version = "1.0.0"
51
+
branch = "master"
52
+
revision = "abc123"
53
+
# 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.
# Optional: metadata about the constraint or override that could be used by other independent systems
57
+
[metadata]
58
+
key1 = "value that convey data to other systems"
59
+
system1-data = "value that is used by a system"
60
+
system2-data = "value that is used by another system"
61
+
```
62
+
63
+
**Use this for:** all the same things as a [`constraint`](#constraint), but for [transitive dependencies](FAQ.md#what-is-a-direct-or-transitive-dependency). See [How do I constrain a transitive dependency's version?](FAQ.md#how-do-i-constrain-a-transitive-dependencys-version) for more details on how overrides differ from `constraint`s. _Overrides should be used cautiously, sparingly, and temporarily._
2
64
3
65
## `required`
4
-
`required` lists a set of packages (not projects) that must be included in
5
-
Gopkg.lock. This list is merged with the set of packages imported by the current
6
-
project.
66
+
67
+
`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.
**Use this for:** preventing a package and any of that package's unique
46
-
dependencies from being installed.
105
+
**Use this for:** preventing a package and any of that package's unique dependencies from being installed.
47
106
48
107
## `metadata`
49
108
`metadata` can exist at the root as well as under `constraint` and `override` declarations.
50
109
51
110
`metadata` declarations are ignored by dep and are meant for usage by other independent systems.
52
111
53
-
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`.
112
+
The root `metadata` declaration defines informatino about the project itself, while a `metadata` declaration under a `[[constraint]]` or an `[[override]]` defines metadata about that rule, for the `name`d project.
54
113
```toml
55
114
[metadata]
56
115
key1 = "value that convey data to other systems"
57
116
system1-data = "value that is used by a system"
58
117
system2-data = "value that is used by another system"
59
118
```
60
119
61
-
## `constraint`
62
-
A `constraint` provides rules for how a [direct dependency](FAQ.md#what-is-a-direct-or-transitive-dependency) may be incorporated into the
63
-
dependency graph.
64
-
They are respected by dep whether coming from the Gopkg.toml of the current project or a dependency.
65
-
```toml
66
-
[[constraint]]
67
-
# Required: the root import path of the project being constrained.
68
-
name = "github.com/user/project"
69
-
# Recommended: the version constraint to enforce for the project.
70
-
# Only one of "branch", "version" or "revision" can be specified.
71
-
version = "1.0.0"
72
-
branch = "master"
73
-
revision = "abc123"
74
120
75
-
# Optional: an alternate location (URL or import path) for the project's source.
# Optional: metadata about the constraint that could be used by other independent systems
79
-
[constraint.metadata]
80
-
key1 = "value that convey data to other systems"
81
-
system1-data = "value that is used by a system"
82
-
system2-data = "value that is used by another system"
83
-
```
84
-
85
-
**Use this for:** having a [direct dependency](FAQ.md#what-is-a-direct-or-transitive-dependency)
86
-
use a specific branch, version range, revision, or alternate source (such as a
87
-
fork).
88
-
89
-
## `override`
90
-
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.
91
-
92
-
```toml
93
-
[[override]]
94
-
# Required: the root import path of the project being constrained.
95
-
name = "github.com/user/project"
96
-
# 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.
97
-
version = "1.0.0"
98
-
branch = "master"
99
-
revision = "abc123"
100
-
# 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.
See [How do I constrain a transitive dependency's version?](FAQ.md#how-do-i-constrain-a-transitive-dependencys-version)
113
-
for more details on how overrides differ from `constraint`s. _Overrides should
114
-
be used cautiously, sparingly, and temporarily._
115
125
116
126
## `version`
117
127
118
-
`version` is a property of `constraint`s and `override`s. It is used to specify
119
-
version constraint of a specific dependency.
128
+
`version` is a property of `constraint`s and `override`s. It is used to specify version constraint of a specific dependency.
120
129
121
-
Internally, dep uses [Masterminds/semver](https://github.com/Masterminds/semver)
122
-
to work with semver versioning.
130
+
Internally, dep uses [Masterminds/semver](https://github.com/Masterminds/semver) to work with semver versioning.
123
131
124
-
`~` and `=` operators can be used with the versions. When a version is specified
125
-
without any operator, `dep` automatically adds a caret operator, `^`. The caret
126
-
operator pins the left-most non-zero digit in the version. For example:
132
+
`~` 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:
127
133
```
128
134
^1.2.3 means 1.2.3 <= X < 2.0.0
129
135
^0.2.3 means 0.2.3 <= X < 0.3.0
130
136
^0.0.3 means 0.0.3 <= X < 0.1.0
131
137
```
132
138
133
-
To pin a version of direct dependency in manifest, prefix the version with `=`.
134
-
For example:
139
+
To pin a version of direct dependency in manifest, prefix the version with `=`. For example:
135
140
```toml
136
141
[[constraint]]
137
142
name = "github.com/pkg/errors"
@@ -147,7 +152,10 @@ Here's an example of a sample Gopkg.toml with most of the elements
In keeping with Go's general design philosophy of minimizing knobs, dep has a sparse interface - there are only two commands you're likely to run regularly. For existing projects, `dep ensure` is the primary workhorse command, and the only thing you'll run that actually changes disk state. `dep status` is a read-only command that can help you understand the current state of your project.
6
+
7
+
Sparse interface notwithstanding, acclimating to `dep ensure` can take some practice. The verb here is "ensure", as we're asking dep to "make sure that my `Gopkg.lock` satisfies all the imports from my project and the rules in `Gopkg.toml`, and that `vendor/` contains exactly what `Gopkg.lock` says it should." In other words, dep is designed around the idea that it's fine to run `dep ensure` at most any time, and it will bring your project and its dependencies into a good state, while doing as little work as possible to achieve that guarantee (though [we're still optimizing "as little as possible"]()).
8
+
9
+
That's pretty vague, though. Let's make it clearer by exploring some concrete examples. We'll start by moving to the root of a hypothetical project, then running `dep ensure`:
10
+
11
+
```
12
+
$ cd $GOPATH/src/github.com/me/example
13
+
$ dep ensure
14
+
```
15
+
16
+
If `dep ensure` exits 0, then we're guaranteed (with [one fixable caveat]()), that our project is "in sync" - `vendor/` is populated with a depgraph that satisfies all imports and rules. So, let's assume `dep ensure` exited 0, and our project is now in sync. That means we're ready to develop normally: edit `.go` files, run `go test` and `go build`, etc. We don't need to think about dep again until one of the following happens:
17
+
18
+
- We want to add a new dependency
19
+
- We want to upgdate an existing dependency
20
+
- We've imported a package for the first time, or removed the last import of a package
21
+
- We've made a change to a rule in `Gopkg.toml`
22
+
23
+
There's a bit of [TIMTOWTDI](https://en.wiktionary.org/wiki/TMTOWTDI) here, as it's possible, and sometimes preferable, to handle each of these cases with a plain `dep ensure`, but dep also allows some additional parameters to make some of these cases a bit more ergonomic. We'll explore each in turn.
24
+
25
+
### Adding a new dependency
26
+
27
+
Let's say that we want to introduce a new dependency on `github.com/pkg/errors`. We can accomplish this with one command:
28
+
29
+
```
30
+
$ dep ensure -add github.com/pkg/errors
31
+
```
32
+
33
+
_Much like git, `dep status` and `dep ensure` can also be run from any subdirectory of your project root, which is determined by the presence of a `Gopkg.toml` file._
34
+
35
+
This should succeed, resulting in an updated `Gopkg.lock` and `vendor/` directory, as well as injecting a best-guess version constraint for `github.com/pkg/errors` into our `Gopkg.toml`. But, it will also report a warning:
36
+
37
+
```
38
+
"github.com/pkg/errors" is not imported by your project, and has been temporarily added to Gopkg.lock and vendor/.
39
+
If you run "dep ensure" again before actually importing it, it will disappear from Gopkg.lock and vendor/.
40
+
```
41
+
42
+
This reflects the nature of `dep ensure` - `github.com/pkg/errors` isn't in our project's imports, and as such, a subsequent `dep ensure` will classify it as unnecessary, and remove it. If we're ready to use the package, though, then this shouldn't be a problem - add an `import "github.com/pkg/errors"` to a `.go` file, and the project's now back in sync.
43
+
44
+
It's also possible to introduce the new dependency without relying on `-add`. If, as a first step, you add `import "github.com/pkg/errors"` to a `.go` file, then run a plain `dep ensure`, your project will be in almost the same state as with `-add`: `Gopkg.lock` and `vendor/` will include `github.com/pkg/errors`. The only difference is that `Gopkg.toml` will not have been updated with a guess at a version constraint.
45
+
46
+
In a sense, the plain `dep ensure` approach is more natural here, as using `-add` effectively dupes dep into violating its guarantee - `dep ensure` exits 0, but the extra dependency means our project is out of sync. However, the plain approach has a chicken-or-egg problem. Many Go developers use something like [`goimports`]() to read the contents of a `.go` file and infer what import statements to add. `goimports`, in turn, works by searching vendor and GOPATH for packages that match the identifiers in a file - which requires that those packages already be present locally.
47
+
48
+
**Both approaches can be useful in different situations. If you're genuinely experimenting with permanently adding a new dependency to your project, then `dep ensure -add` is probably best: you'll probably want that constraint **
49
+
50
+
### Updating dependencies
51
+
52
+
First, a quick definition: in dep's world, updating a dependency is the act of changing the value of the `revision` field in `Gopkg.lock` for that project (and, by extension, the version in the `vendor` directory). There are two basic ways of achieving this:
53
+
54
+
* Run `dep ensure -update <dependency/root/import/path>`; this will update the project to the latest version allowed by the version constraints in `Gopkg.toml`.
55
+
* Edit `Gopkg.toml`, changing the version constraint to one that does not allow the version currently in `Gopkg.lock`, then run `dep ensure`.
56
+
57
+
The CLI-driven approach is strongly preferred to hand-editing `Gopkg.toml`. Let's look at that first.
58
+
59
+
#### CLI-driven updates
60
+
61
+
`dep ensure -update` can be used to update multiple dependencies at once:
62
+
63
+
```
64
+
$ dep ensure -update github.com/foo/bar github.com/baz/quux
65
+
```
66
+
67
+
Or all dependencies (not recommended):
68
+
69
+
```
70
+
dep ensure -update
71
+
```
72
+
73
+
The CLI-driven approach is preferred because it is much more convenient, less expressive (read: safer), and better for the Go packaging ecosystem. However, it doesn't always work, as the semantics of `-update` are dependent on the constraint declared in `Gopkg.toml`:
74
+
75
+
* If `version` is specified with a semantic version range, then `dep ensure -update` will try to get the latest version in that range.
76
+
* If `branch` is specified, `dep ensure -update` will try to move to the latest tip of the named branch.
77
+
* If `version` is specified with a non-semantic version, or with a non-range (e.g., `version = "=v1.0.0"`), `dep ensure -update` will only make changes if the release moved (e.g., someone did a `git push --force`).
78
+
* If a `revision` is specified, `dep ensure -update` cannot make any changes.
79
+
* If no constraint is specified (typically not recommended), `dep ensure -update` will try versions in [the upgrade sort order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade).
80
+
81
+
There's a fair bit of nuance to the options here, which is explored in greater detail in [Zen of Constraints and Locks](). But only the first and second kinds of constraints are especially useful with `dep ensure -update`. And that's only partially under your control - if the dependency you're working with hasn't made any semver releases, then you can't use semver ranges.
82
+
83
+
#### Manual updates
84
+
85
+
If using semver ranges or branches isn't an option for a particular dependency, you'll have to rely instead on hand-editing `Gopkg.toml` with the exact version you want, then running `dep ensure`.
86
+
87
+
Given that the version constraints given in `Gopkg.toml` determine the behavior of `dep ensure -update`, hand-editing the constraints necessarily allows a superset of the changes to `Gopkg.lock` allowed by `dep ensure -update`. Really, these sorts of manual edits can be considered "updates" only in the loosest sense; they could just as easily be downgrades, or a change of the constraint type (e.g. from `version` to `branch`) that is not neatly classifiable as "up" or "down."
88
+
89
+
Note that these approaches are not mutually exclusive. If, for example, you initially constrain a project to `version = "^1.1.0"`, then later run `dep ensure -update` bringing it to `v1.2.0` in `Gopkg.lock` and start using new features introduced in `v1.2.0` in your code, then it's important to update the bottom of the constraint range: `version = "^1.2.0"`.
90
+
91
+
92
+
93
+
hand-edit `Gopkg.toml` update the range are also times when you'll need to
94
+
95
+
96
+
97
+
98
+
99
+
but it may not be possible to use. Whether it's possible is a combination of what releases the dependency has published, and what kind of constraint you've chosen to
100
+
101
+
102
+
103
+
The first approach is simultaneously more convenient and less expressive than the second,
Deduction is dep's algorithm for looking at an import path and determining the portion of the path that corresponds to the source root. The algorithm has a static component, by which a small set of known, popular hosts like GitHub and Bitbucket have their roots deduced:
The set of hosts supported by static deduction are the same as [those supported by `go get`]().
11
+
12
+
If the static logic cannot identify the root for a given import path, the algorithm continues to a dynamic component, where it makes an HTTP(S) request to the import path, and a server is expected to return a response that indicates the root import path. This, again, is equivalent to the behavior of `go get`.
0 commit comments