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.
`dep` is a prototype dependency management tool for Go. It requires Go 1.8 or newer to compile.
10
+
`dep` is a prototype dependency management tool for Go. It requires Go 1.8 or newer to compile.**`dep` is safe for production use.**
11
11
12
12
`dep` is the official _experiment_, but not yet the official tool. Check out the [Roadmap](https://github.com/golang/dep/wiki/Roadmap) for more on what this means!
13
13
14
-
## Current status
14
+
For guides and reference materials about `dep`, see [the documentation](https://golang.github.io/dep).
15
15
16
-
`dep` is safe for production use. That means two things:
16
+
## Installation
17
17
18
-
* Any valid metadata file (`Gopkg.toml` and `Gopkg.lock`) will be readable and considered valid by any future version of `dep`.
19
-
* The CLI UI is mostly stable. `dep init` and `dep ensure` are mostly set; `dep status` is likely to change a fair bit, and `dep prune` is [going to be absorbed into `dep ensure`](https://github.com/golang/dep/issues/944).
18
+
It is strongly recommended that you use a released version. Release binaries are available on the [releases](https://github.com/golang/dep/releases) page.
20
19
21
-
That said, keep in mind the following:
22
-
23
-
*`dep init` on an existing project can be a rocky experience - we try to automatically convert from other tools' metadata files, and that process is often complex and murky. Once your project is converted and you're using `dep ensure`, its behavior is quite stable.
24
-
*`dep` still has nasty bugs, but in general these are comparable to or fewer than other tools out there.
25
-
*`dep` is [pretty slow right now](https://github.com/golang/dep/blob/master/docs/FAQ.md#why-is-dep-slow), especially on the first couple times you run it. Just know that there is a _lot_ of headroom for improvement, and work is actively underway.
26
-
*`dep` is still changing rapidly. If you need stability (e.g. for CI), it's best to rely on a released version, not tip.
27
-
*`dep`'s exported API interface will continue to change in unpredictable, backwards-incompatible ways until we tag a v1.0.0 release.
28
-
29
-
## Context
30
-
31
-
-[The Saga of Go Dependency Management](https://blog.gopheracademy.com/advent-2016/saga-go-dependency-management/)
Grab the latest binary from the [releases](https://github.com/golang/dep/releases) page.
42
-
43
-
On macOS you can install or upgrade to the latest released version with Homebrew:
20
+
On MacOS you can install or upgrade to the latest released version with Homebrew:
44
21
45
22
```sh
46
23
$ brew install dep
@@ -53,217 +30,12 @@ If you're interested in hacking on `dep`, you can install via `go get`:
53
30
go get -u github.com/golang/dep/cmd/dep
54
31
```
55
32
56
-
To start managing dependencies using dep, run the following from your project's root directory:
57
-
58
-
```sh
59
-
$ dep init
60
-
```
61
-
62
-
This does the following:
63
-
64
-
1. Look for [existing dependency management files](docs/FAQ.md#what-external-tools-are-supported) to convert
65
-
1. Check if your dependencies use dep
66
-
1. Identify your dependencies
67
-
1. Back up your existing `vendor/` directory (if you have one) to
68
-
`_vendor-TIMESTAMP/`
69
-
1. Pick the highest compatible version for each dependency
70
-
1. Generate [`Gopkg.toml`](docs/Gopkg.toml.md) ("manifest") and `Gopkg.lock` files
71
-
1. Install the dependencies in `vendor/`
72
-
73
-
## Usage
74
-
75
-
There is one main subcommand you will use: `dep ensure`. `ensure` first checks that `Gopkg.lock` is consistent with `Gopkg.toml` and the `import`s in your code. If any
76
-
changes are detected, `dep`'s solver works out a new `Gopkg.lock`. Then, `dep` checks if the contents of `vendor/` are what `Gopkg.lock` (the new one if applicable, else the existing one) says it should be, and rewrites `vendor/` as needed to bring it into line.
77
-
78
-
In essence, `dep ensure`[works in two phases to keep four buckets of state in sync](https://youtu.be/5LtMb090AZI?t=20m4s):
_Note: until we ship [vendor verification](https://github.com/golang/dep/issues/121), we can't efficiently perform the `Gopkg.lock` <-> `vendor/` comparison, so `dep ensure` unconditionally regenerates all of `vendor/` to be safe._
84
-
85
-
`dep ensure` is safe to run early and often. See the help text for more detailed
86
-
usage instructions.
87
-
88
-
```sh
89
-
$ dep help ensure
90
-
```
91
-
92
-
### Installing dependencies
93
-
94
-
(if your `vendor/` directory isn't [checked in with your code](docs/FAQ.md#should-i-commit-my-vendor-directory))
95
-
96
-
<!-- may change with https://github.com/golang/dep/pull/489 -->
97
-
98
-
```sh
99
-
$ dep ensure
100
-
```
101
-
102
-
If a dependency already exists in your `vendor/` folder, dep will ensure it
103
-
matches the constraints from the manifest. If the dependency is missing from
104
-
`vendor/`, the latest version allowed by your manifest will be installed.
105
-
106
-
### Adding a dependency
107
-
108
-
```sh
109
-
$ dep ensure -add github.com/foo/bar
110
-
```
111
-
112
-
This adds a version constraint to your `Gopkg.toml`, and updates `Gopkg.lock` and `vendor/`. Now, import and use the package in your code! ✨
113
-
114
-
`dep ensure -add` has some subtle behavior variations depending on the project or package named, and the state of your tree. See `dep ensure -examples` for more information.
115
-
116
-
### Changing dependencies
117
-
118
-
If you want to:
119
-
120
-
* Change the allowed `version`/`branch`/`revision`
121
-
* Switch to using a fork
122
-
123
-
for one or more dependencies, do the following:
124
-
125
-
1. Manually edit your `Gopkg.toml`.
126
-
1. Run
127
-
128
-
```sh
129
-
$ dep ensure
130
-
```
131
-
132
-
### Checking the status of dependencies
133
-
134
-
Run `dep status` to see the current status of all your dependencies.
On top of that, if you have added new imports to your project or modified `Gopkg.toml` without running `dep ensure` again, `dep status` will tell you there is a mismatch between `Gopkg.lock` and the current status of the project.
145
-
146
-
```sh
147
-
$ dep status
148
-
Lock inputs-digest mismatch due to the following packages missing from the lock:
Updating brings the version of a dependency in`Gopkg.lock` and `vendor/` to the latest version allowed by the constraints in`Gopkg.toml`.
181
-
182
-
You can update just a targeted subset of dependencies (recommended):
183
-
184
-
```sh
185
-
$ dep ensure -update github.com/some/project github.com/other/project
186
-
$ dep ensure -update github.com/another/project
187
-
```
188
-
189
-
Or you can update all your dependencies at once:
190
-
191
-
```sh
192
-
$ dep ensure -update
193
-
```
194
-
195
-
"Latest" means different things depending on the type of constraint in use. If you're depending on a `branch`, `dep` will update to the latest tip of that branch. If you're depending on a `version` using [a semver range](#semantic-versioning), it will update to the latest version in that range.
196
-
197
-
### Removing dependencies
198
-
199
-
1. Remove the `import`s and all usage from your code.
200
-
1. Remove `[[constraint]]` rules from `Gopkg.toml` (if any).
201
-
1. Run
202
-
203
-
```sh
204
-
$ dep ensure
205
-
```
206
-
207
-
### Testing changes to a dependency
208
-
209
-
Making changes in your `vendor/` directory directly is not recommended, as dep
210
-
will overwrite any changes. Instead:
211
-
212
-
1. Delete the dependency from the `vendor/` directory.
213
-
214
-
```sh
215
-
rm -rf vendor/<dependency>
216
-
```
217
-
218
-
1. Add that dependency to your `GOPATH`, if it isn't already.
219
-
220
-
```sh
221
-
$ go get <dependency>
222
-
```
223
-
224
-
1. Modify the dependency in `$GOPATH/src/<dependency>`.
225
-
1. Test, build, etc.
226
-
227
-
Don't run `dep ensure`until you're done. `dep ensure` will reinstall the
228
-
dependency into `vendor/` based on your manifest, as if you were installing from
229
-
scratch.
230
-
231
-
This solution works for short-term use, but for something long-term, take a look
232
-
at [virtualgo](https://github.com/GetStream/vg).
233
-
234
-
To test out code that has been pushed as a new version, or to a branch or fork,
235
-
see [changing dependencies](#changing-dependencies).
236
-
237
-
## Semantic Versioning
238
-
239
-
`dep ensure` uses an external [semver library](https://github.com/Masterminds/semver) to interpret the version constraints you specify in the manifest. The comparison operators are:
240
-
241
-
* `=`: equal
242
-
* `!=`: not equal
243
-
* `>`: greater than
244
-
* `<`: less than
245
-
* `>=`: greater than or equal to
246
-
* `<=`: less than or equal to
247
-
* `-`: literal range. Eg: 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5
248
-
* `~`: minor range. Eg: ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0
249
-
* `^`: major range. Eg: ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0
250
-
* `[xX*]`: wildcard. Eg: 1.2.x is equivalent to >= 1.2.0, < 1.3.0
251
-
252
-
You might, for example, include a constraint in your manifest that specifies `version = "=2.0.0"` to pin a dependency to version 2.0.0, or constrain to minor releases with: `version = "2.*"`. Refer to the [semver library](https://github.com/Masterminds/semver) documentation for more info.
253
-
254
-
**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:
255
-
256
-
* `1.2.3` becomes the range `>=1.2.3, <2.0.0`
257
-
* `0.2.3` becomes the range `>=0.2.3, <0.3.0`
258
-
* `0.0.3` becomes the range `>=0.0.3, <0.1.0`
259
-
260
33
## Feedback
261
34
262
35
Feedback is greatly appreciated.
263
36
At this stage, the maintainers are most interested in feedback centered on the user experience (UX) of the tool.
264
37
Do you have workflows that the tool supports well, or doesn't support at all?
265
38
Do any of the commands have surprising effects, output, or results?
266
-
Please check the existing issues and [FAQ](docs/FAQ.md) to see if your feedback has already been reported.
267
39
If not, please file an issue, describing what you did or wanted to do, what you expected to happen, and what actually happened.
Copy file name to clipboardExpand all lines: docs/FAQ.md
+5-7
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,8 @@
1
-
# FAQ
1
+
---
2
+
title: FAQ
3
+
---
2
4
3
-
_The first rule of FAQ is don't bikeshed the FAQ, leave that for
4
-
[Create structure for managing docs](https://github.com/golang/dep/issues/331)._
5
-
6
-
Please contribute to the FAQ! Found an explanation in an issue or pull request helpful?
7
-
Summarize the question and quote the reply, linking back to the original comment.
5
+
The FAQ predated the introduction of the rest of the documentation. If something in here conflicts with other guides or reference documents, it's probably here that it's wrong - please file a PR!
@@ -284,7 +282,7 @@ There's another major performance issue that's much harder - the process of pick
284
282
## How does `dep` handle symbolic links?
285
283
286
284
> because we're not crazy people who delight in inviting chaos into our lives, we need to work within one `GOPATH` at a time.
287
-
-[@sdboyer in #247](https://github.com/golang/dep/pull/247#issuecomment-284181879)
285
+
> -[@sdboyer in #247](https://github.com/golang/dep/pull/247#issuecomment-284181879)
288
286
289
287
Out of convenience, one might create a symlink to a directory within their `GOPATH/src`, e.g. `ln -s ~/go/src/github.com/user/awesome-project ~/Code/awesome-project`.
0 commit comments