dep

This is a prototype dependency management tool for Go. It requires Go 1.8 or newer to compile.

The dep project is the official experiment, but not yet the official tool. Check out the Roadmap for more on what this means!

Current status

It is safe to use dep in production. That means two things:

  • Any valid metadata file (Gopkg.toml and Gopkg.lock) will be readable and considered valid by any future version of dep.
  • 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.

That said, keep in mind the following:

  • 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.
  • dep still has nasty bugs, but in general these are comparable to or fewer than other tools out there.
  • dep is pretty slow right now, 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.
  • 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.

Context

Semantic Versioning

dep ensure 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.0

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 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

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.

Contributing

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.