commit | 7a91b794bbfbf1f3b8b79823799316451127801b | [log] [tgz] |
---|---|---|
author | sam boyer <tech@samboyer.org> | Fri Aug 04 14:27:23 2017 |
committer | GitHub <noreply@github.com> | Fri Aug 04 14:27:23 2017 |
tree | 78217fe72724405f797f754cee9d1e91a67f5d48 | |
parent | c1aba4d8a9eb5d78ceca1812c477e81975a25b38 [diff] | |
parent | b8f7027092133c37c4503eb16a70660c3e571273 [diff] |
Merge pull request #489 from sdboyer/new-ensure Implement new spec for `dep ensure`
Dep is a prototype dependency management tool. It requires Go 1.7 or newer to compile.
dep
is NOT an official tool. Yet. Check out the Roadmap!
dep
is safe for production use. That means two things:
Gopkg.toml
and Gopkg.lock
) will be readable and considered valid by any future version of dep
.That said, keep in mind the following:
dep
is still changing rapidly. If you need stability (e.g. for CI), it's best to rely on a released version, not tip.dep
's exported API interface will continue to change in unpredictable, backwards-incompatible ways until we tag a v1.0.0 release.Get the tool via
$ go get -u github.com/golang/dep/cmd/dep
To start managing dependencies using dep, run the following from your project root directory:
$ dep init
This does the following:
vendor/
directory (if you have one) to _vendor-TIMESTAMP/
Gopkg.toml
(“manifest”) and Gopkg.lock
filesvendor/
There is one main subcommand you will use: dep ensure
. ensure
first makes sure Gopkg.lock
is consistent with your import
s and Gopkg.toml
. If any changes are detected, it then populates vendor/
with exactly what's described in Gopkg.lock
.
dep ensure
is safe to run early and often. See the help text for more detailed usage instructions.
$ dep help ensure
(if your vendor/
directory isn't checked in with your code)
$ dep ensure
If a dependency already exists in your vendor/
folder, dep will ensure it matches the constraints from the manifest. If the dependency is missing from vendor/
, the latest version allowed by your manifest will be installed.
import
the package in your *.go
source code file(s).
Run the following command to update your Gopkg.lock
and populate vendor/
with the new dependency.
$ dep ensure
If you want to:
version
/branch
/revision
for one or more dependencies, do the following:
Modify your Gopkg.toml
.
Run
$ dep ensure
Run dep status
to see the current status of all your dependencies.
$ dep status PROJECT CONSTRAINT VERSION REVISION LATEST github.com/Masterminds/semver branch 2.x branch 2.x 139cc09 c2e7f6c github.com/Masterminds/vcs ^1.11.0 v1.11.1 3084677 3084677 github.com/armon/go-radix * branch master 4239b77 4239b77
On top of that, if you have added new imports to your project or modified the manifest file without running dep ensure
again, dep status
will tell you there is a mismatch between the lock file and the current status of the project.
$ dep status Lock inputs-digest mismatch due to the following packages missing from the lock: PROJECT MISSING PACKAGES github.com/Masterminds/goutils [github.com/Masterminds/goutils] This happens when a new import is added. Run `dep ensure` to install the missing packages.
As dep status
suggests, run dep ensure
to update your lockfile. Then run dep status
again, and the lock mismatch should go away.
(to the latest version allowed by the manifest)
$ dep ensure -update
Remove the import
s and all usage from your code.
Run
$ dep ensure
Remove from Gopkg.toml
, if it was in there.
Making changes in your vendor/
directory directly is not recommended, as dep will overwrite any changes. Instead:
Delete the dependency from the vendor/
directory.
rm -rf vendor/<dependency>
Add that dependency to your GOPATH
, if it isn't already.
$ go get <dependency>
Modify the dependency in $GOPATH/src/<dependency>
.
Test, build, etc.
Don‘t run dep ensure
until you’re done. dep ensure
will reinstall the dependency into vendor/
based on your manifest, as if you were installing from scratch.
This solution works for short-term use, but for something long-term, take a look at virtualgo.
To test out code that has been pushed as a new version, or to a branch or fork, see changing dependencies.
dep ensure
a uses an external semver library to interpret the version constraints you specify in the manifest. The comparison operators are:
=
: equal!=
: not equal>
: greater than<
: less than>=
: greater than or equal to<=
: less than or equal to-
: literal range. Eg: 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5~
: minor range. Eg: ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0^
: major range. Eg: ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0[xX*]
: wildcard. Eg: 1.2.x is equivalent to >= 1.2.0, < 1.3.0You 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 documentation for more info.
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-boundry of a range, for example:
1.2.3
becomes the range >=1.2.3, <2.0.0
0.2.3
becomes the range >=0.2.3, <0.3.0
0.0.3
becomes the range >=0.0.3, <0.1.0
Feedback is greatly appreciated. At this stage, the maintainers are most interested in feedback centered on the user experience (UX) of the tool. Do you have workflows that the tool supports well, or doesn't support at all? Do any of the commands have surprising effects, output, or results? Please check the existing issues and FAQ to see if your feedback has already been reported. If not, please file an issue, describing what you did or wanted to do, what you expected to happen, and what actually happened.
Contributions are greatly appreciated. The maintainers actively manage the issues list, and try to highlight issues suitable for newcomers. The project follows the typical GitHub pull request model. See CONTRIBUTING.md for more details. Before starting any work, please either comment on an existing issue, or file a new one.