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.
Copy file name to clipboardExpand all lines: docs/Gopkg.toml.md
+121-78
Original file line number
Diff line number
Diff line change
@@ -4,25 +4,32 @@ title: Gopkg.toml
4
4
5
5
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
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
-
*[`prune`](#prune) settings govern what files and directories can be deemed unnecessary, and thus automatically removed from `vendor/`.
7
+
*_Dependency rules:_[`constraints`](#constraint) and [`overrides`](#override) allow the user to specify which versions of dependencies are acceptable, and where they should be retrieved from.
8
+
*_Package graph rules:_[`required`](#required) and [`ignored`](#ignored) allow the user to manipulate the import graph by including or excluding import paths, respectively.
9
+
*[`metadata`](#metadata)are a user-defined maps of key-value pairs that dep will ignore. They provide a data sidecar for tools building on top of dep.
10
+
*[`prune`](#prune) settings determine what files and directories can be deemed unnecessary, and thus automatically removed from `vendor/`.
11
11
12
12
Note that because TOML does not adhere to a tree structure, the `required` and `ignored` fields must be declared before any `[[constraint]]` or `[[override]]`.
13
13
14
-
---
14
+
There is a full [example](#example)`Gopkg.toml` file at the bottom of this document. `dep init` will also, by default, generate a `Gopkg.toml` containing some example values, for guidance.
15
+
16
+
## Dependency rules: `[[constraint]]` and `[[override]]`
15
17
16
-
## `constraint`
18
+
Most of the rule declarations in a `Gopkg.toml` will be either `[[constraint]]` or `[[override]]` stanzas. Both of these types of stanzas allow exactly the same types of values, but dep interprets them differently. Each allows the following values:
17
19
18
-
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.
20
+
*`name` - the import path corresponding to the [source root](glossary.md#source-root) of a dependency (generally: where the VCS root is)
21
+
* At most one [version rule](#version-rules)
22
+
* An optional [`source` rule](#source)
23
+
*[`metadata`](#metadata) that is specific to the `name`'d project
24
+
25
+
A full example (invalid, actually, as it has more than one version rule, for illustrative purposes) of either one of these stanzas looks like this:
19
26
20
27
```toml
21
28
[[constraint]]
22
29
# Required: the root import path of the project being constrained.
23
30
name = "github.com/user/project"
24
31
# Recommended: the version constraint to enforce for the project.
25
-
#Only one of "branch", "version" or "revision" can be specified.
32
+
#Note that only one of "branch", "version" or "revision" can be specified.
26
33
version = "1.0.0"
27
34
branch = "master"
28
35
revision = "abc123"
@@ -37,33 +44,86 @@ A `constraint` provides rules for how a [direct dependency](FAQ.md#what-is-a-dir
37
44
system2-data = "value that is used by another system"
38
45
```
39
46
47
+
### `[[constraint]]`
48
+
49
+
A `[[constraint]]` stanza defines rules for how a [direct dependency](glossary.md#direct-dependency) must be incorporated into the dependency graph. Dep respects these declarations from the current project's `Gopkg.toml`, as well as the `Gopkg.toml` files found in any dependencies.
50
+
40
51
**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).
41
52
42
-
##`override`
53
+
### `[[override]]`
43
54
44
-
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.
55
+
An `[[override]]` stanza differs from a `[[constraint]]` in that it applies to all dependencies, [direct](glossary.md#direct-dependency) and [transitive](glossary.md#transitive-dependency), and supersedes all other `[[constraint]]` declarations for that project. However, only overrides from the current project's `Gopkg.toml` are incorporated.
45
56
46
-
```toml
47
-
[[override]]
48
-
# Required: the root import path of the project being constrained.
49
-
name = "github.com/user/project"
50
-
# 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.
51
-
version = "1.0.0"
52
-
branch = "master"
53
-
revision = "abc123"
54
-
# 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.
55
-
source = "https://github.com/myfork/package.git"
57
+
**Use this for:** Overrides are primarily intended as a way of eliminating disagreements between multiple irreconcilable `[[constraint]]` declarations on a single dependency. However, they will also be your primary recourse if you need to [constrain a transitive dependency's version?](FAQ.md#how-do-i-constrain-a-transitive-dependencys-version)
56
58
57
-
# Optional: metadata about the constraint or override that could be used by other independent systems
58
-
[metadata]
59
-
key1 = "value that convey data to other systems"
60
-
system1-data = "value that is used by a system"
61
-
system2-data = "value that is used by another system"
59
+
Overrides should be used cautiously and temporarily, when possible.
60
+
61
+
### `source`
62
+
63
+
A `source` rule can specify an alternate location from which the `name`'d project should be retrieved. It is primarily useful for temporarily specifying a fork for a repository.
64
+
65
+
`source` rules are generally brittle and should only be used when there is no other recourse. Using them to try to circumvent network reachability issues is typically an antipattern.
66
+
67
+
### Version rules
68
+
69
+
Version rules can be used in either `[[constraint]]` or `[[override]]` stanzas. There are three types of version rules - `version`, `branch`, and `revision`. At most one of the three types can be specified.
70
+
71
+
#### `version`
72
+
73
+
`version` is a property of `constraint`s and `override`s. It is used to specify version constraint of a specific dependency. It can be used to target an arbitrary VCS tag, or a semantic version, or a range of semantic versions.
74
+
75
+
Specifying semantic version ranges can be done using the following operators:
76
+
77
+
*`=`: equal
78
+
*`!=`: not equal
79
+
*`>`: greater than
80
+
*`<`: less than
81
+
*`>=`: greater than or equal to
82
+
*`<=`: less than or equal to
83
+
*`-`: literal range. Eg: 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5
84
+
*`~`: minor range. Eg: ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0
85
+
*`^`: major range. Eg: ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0
86
+
*`[xX*]`: wildcard. Eg: 1.2.x is equivalent to >= 1.2.0, < 1.3.0
87
+
88
+
You might, for example, include a rule that specifies `version = "=2.0.0"` to pin a dependency to version 2.0.0, or constrain to minor releases with: `version = "~2.1.0"`. Refer to the [semver library](https://github.com/Masterminds/semver) documentation for more info.
89
+
90
+
**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-boundary of a range, for example:
91
+
92
+
*`1.2.3` becomes the range `>=1.2.3, <2.0.0`
93
+
*`0.2.3` becomes the range `>=0.2.3, <0.3.0`
94
+
*`0.0.3` becomes the range `>=0.0.3, <0.1.0`
95
+
96
+
`~` 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:
97
+
```
98
+
^1.2.3 means 1.2.3 <= X < 2.0.0
99
+
^0.2.3 means 0.2.3 <= X < 0.3.0
100
+
^0.0.3 means 0.0.3 <= X < 0.1.0
101
+
```
102
+
103
+
To pin a version of direct dependency in manifest, prefix the version with `=`. For example:
104
+
```toml
105
+
[[constraint]]
106
+
name = "github.com/pkg/errors"
107
+
version = "=0.8.0"
62
108
```
63
109
64
-
**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._
110
+
#### `branch`
65
111
66
-
## `required`
112
+
Using a `branch` constraint will cause dep to use the named branch (e.g., `branch = "master"`) for a particular dependency. The revision at the tip of the branch will be recorded into `Gopkg.lock`, and almost always remain the same until a change is requested, via `dep ensure -update`.
113
+
114
+
In general, you should prefer semantic versions to branches, when a project has made them available.
115
+
116
+
#### `revision`
117
+
118
+
A `revision` is the underlying immutable identifier - like a git commit SHA1. While it is allowed to constrain to a `revision`, doing so is almost always an antipattern.
119
+
120
+
Usually, folks are inclined to pin to a revision because they feel it will somehow improve their project's reproducibility. That is not a good reason. `Gopkg.lock` provides reproducibility. Only use `revision` if you have a good reason to believe that _no_ other version of that dependency _could_ work.
121
+
122
+
## Package graph rules: `required` and `ignored`
123
+
124
+
As part of normal operation, dep analyzes import statements in Go code. These import statements connect packages together, ultimately forming a graph. The `required` and `ignored` rules manipulate that graph, in ways that are roughly dual to each other: `required` adds import paths to the graph, and `ignored` removes them.
125
+
126
+
### `required`
67
127
68
128
`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.
* Aren't `import`ed by your project, [directly or transitively](FAQ.md#what-is-a-direct-or-transitive-dependency)
77
-
* You don't want put in your `GOPATH`, and/or you want to lock the version
137
+
* You don't want to put them in your `GOPATH`, and/or you want to lock the version
78
138
79
139
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`:
80
140
@@ -92,18 +152,21 @@ export PATH=$GOBIN:$PATH
92
152
93
153
You might also try [virtualgo](https://github.com/GetStream/vg), which installs dependencies in the `required` list automatically in a project specific `GOBIN`.
94
154
95
-
## `ignored`
155
+
156
+
### `ignored`
96
157
`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.
158
+
97
159
```toml
98
160
ignored = ["github.com/user/project/badpkg"]
99
161
```
100
162
101
-
Use wildcard character (*) to define a package prefix to be ignored. Use this to ignore any package and their subpackages.
163
+
Use `*` to define a package prefix to be ignored. This will cause any lexical wildcard match to be ignored, including the literal string prior to the `*`.
164
+
102
165
```toml
103
166
ignored = ["github.com/user/project/badpkg*"]
104
167
```
105
168
106
-
**Use this for:** preventing a package and any of that package's unique dependencies from being installed.
169
+
**Use this for:** preventing a package, and any of that package's unique dependencies, from being incorporated in `Gopkg.lock`.
107
170
108
171
## `metadata`
109
172
`metadata` can exist at the root as well as under `constraint` and `override` declarations.
@@ -118,63 +181,35 @@ system1-data = "value that is used by a system"
118
181
system2-data = "value that is used by another system"
119
182
```
120
183
184
+
## `prune`
121
185
186
+
`prune` defines the global and per-project prune options for dependencies. The options determine which files are discarded when writing the `vendor/` tree.
122
187
123
-
## Version rules
124
-
125
-
Version rules can be used in either `[[constraint]]` or `[[override]]` stanzas. There are three types of version rules - `version`, `branch`, and `revision`. At most one of the three types can be specified.
188
+
The following are the current available options:
189
+
*`unused-packages` indicates that files from directories that do not appear in the package import graph should be pruned.
190
+
*`non-go` prunes files that are not used by Go.
191
+
*`go-tests` prunes Go test files.
126
192
127
-
### `version`
128
-
129
-
`version` is a property of `constraint`s and `override`s. It is used to specify version constraint of a specific dependency. It can be used to target an arbitrary VCS tag, or a semantic version, or a range of semantic versions.
130
-
131
-
Specifying semantic version ranges can be done using the following operators:
132
-
133
-
*`=`: equal
134
-
*`!=`: not equal
135
-
*`>`: greater than
136
-
*`<`: less than
137
-
*`>=`: greater than or equal to
138
-
*`<=`: less than or equal to
139
-
*`-`: literal range. Eg: 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5
140
-
*`~`: minor range. Eg: ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0
141
-
*`^`: major range. Eg: ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0
142
-
*`[xX*]`: wildcard. Eg: 1.2.x is equivalent to >= 1.2.0, < 1.3.0
193
+
Out of an abundance of caution, dep non-optionally preserves files that may have legal significance.
143
194
144
-
You might, for example, include a rule that specifies `version = "=2.0.0"` to pin a dependency to version 2.0.0, or constrain to minor releases with: `version = "~2.1.0"`. Refer to the [semver library](https://github.com/Masterminds/semver) documentation for more info.
145
-
146
-
**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-boundary of a range, for example:
147
-
148
-
*`1.2.3` becomes the range `>=1.2.3, <2.0.0`
149
-
*`0.2.3` becomes the range `>=0.2.3, <0.3.0`
150
-
*`0.0.3` becomes the range `>=0.0.3, <0.1.0`
151
-
152
-
`~` 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:
153
-
```
154
-
^1.2.3 means 1.2.3 <= X < 2.0.0
155
-
^0.2.3 means 0.2.3 <= X < 0.3.0
156
-
^0.0.3 means 0.0.3 <= X < 0.1.0
157
-
```
158
-
159
-
To pin a version of direct dependency in manifest, prefix the version with `=`. For example:
195
+
Pruning is disabled by default. It can be enabled by setting them to `true` at the root level.
160
196
```toml
161
-
[[constraint]]
162
-
name = "github.com/pkg/errors"
163
-
version = "=0.8.0"
197
+
[prune]
198
+
non-go = true
164
199
```
165
200
166
-
### `branch`
167
-
168
-
Using a `branch` constraint will cause dep to use the named branch (e.g., `branch = "master"`) for a particular dependency. The revision at the tip of the branch will be recorded into `Gopkg.lock`, and almost always remain the same until a change is requested, via `dep ensure -update`.
169
-
170
-
In general, you should prefer semantic versions to branches, when a project has made them available.
201
+
The same prune options can be defined per-project. An addtional `name` field is required and, as with should represent a project and not a package.
171
202
172
-
### `revision`
173
203
174
-
A `revision` is the underlying immutable identifier - like a git commit SHA1. While it is allowed to constrain to a `revision`, doing so is almost always an antipattern.
175
-
176
-
Usually, folks are inclined to pin to a revision because they feel it will somehow improve their project's reproducibility. That is not a good reason. `Gopkg.lock` provides reproducibility. Only use `revision` if you have a good reason to believe that _no_ other version of that dependency _could_ work.
Copy file name to clipboardExpand all lines: docs/glossary.md
+9-3
Original file line number
Diff line number
Diff line change
@@ -57,7 +57,11 @@ Deduction is the process of determining the subset of an import path that corres
57
57
58
58
### Direct Dependency
59
59
60
-
A project's direct dependencies are those that it imports from one or more of its packages, or includes in its [`required`](Gopkg.toml.md#required) list in `Gopkg.toml`. If each letter in `A -> B -> C -> D` represents a project, then only `B` is `A`'s direct dependency.
60
+
A project's direct dependencies are those that it _imports_ from one or more of its packages, or includes in its [`required`](Gopkg.toml.md#required) list in `Gopkg.toml`.
61
+
62
+
If each letter in `A -> B -> C -> D` represents a distinct project containing only a single package, and `->` indicates an import statement, then `B` is `A`'s direct dependency, whereas `C` and `D` are [transitive dependencies](#transitive-dependency) of `A`.
63
+
64
+
Dep only incorporates the `required` rules from the [current project's](#current-project)`Gopkg.toml`. Therefore, if `=>` represents `required` rather than a standard import, and `A -> B => C`, then `C` is a direct dependency of `B`_only_ when `B` is the current project. Because the `B`-to-`C` link does not exist when `A` is the current project, then `C` won't actually be in the graph at all.
61
65
62
66
### External Import
63
67
@@ -120,7 +124,7 @@ The remote entities that hold versioned code. Sources are specifically the entit
120
124
121
125
### Source Root
122
126
123
-
The portion of an import path that corresponds to the network location of a source. This is similar to [Project Root](#project-root), but refers strictly to the second definition, network-oriented.
127
+
The portion of an import path that corresponds to the network location of a source. This is similar to [Project Root](#project-root), but refers strictly to the second, network-oriented definition.
124
128
125
129
### Sync
126
130
@@ -130,4 +134,6 @@ This concept is explored in detail on [the ensure mechanics reference page](ensu
130
134
131
135
### Transitive Dependency
132
136
133
-
A project's transitive dependencies are those dependencies that it does not import itself, but are imported by one of its dependencies. If each letter in `A -> B -> C -> D` represents a project, then `C` and `D` are `A`'s transitive dependencies.
137
+
A project's transitive dependencies are those dependencies that it does not import itself, but are imported by one of its dependencies.
138
+
139
+
If each letter in `A -> B -> C -> D` represents a distinct project containing only a single package, and `->` indicates an import statement, then `C` and `D` are `A`'s transitive dependencies, whereas `B` is a [direct dependency](#transitive-dependency) of `A`.
0 commit comments