github.com/golang/dep@v0.5.4/docs/FAQ.md (about) 1 --- 2 title: FAQ 3 --- 4 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! 6 7 ## Concepts 8 9 * [Does `dep` replace `go get`?](#does-dep-replace-go-get) 10 * [Why is it `dep ensure` instead of `dep install`?](#why-is-it-dep-ensure-instead-of-dep-install) 11 * [What is a direct or transitive dependency?](#what-is-a-direct-or-transitive-dependency) 12 13 ## Configuration 14 15 * [What is the difference between Gopkg.toml (the "manifest") and Gopkg.lock (the "lock")?](#what-is-the-difference-between-gopkgtoml-the-manifest-and-gopkglock-the-lock) 16 * [How do I constrain a transitive dependency's version?](#how-do-i-constrain-a-transitive-dependency-s-version) 17 * [How do I change the version of a dependency?](#how-do-i-change-the-version-of-a-dependency) 18 * [Can I put the manifest and lock in the vendor directory?](#can-i-put-the-manifest-and-lock-in-the-vendor-directory) 19 * [How do I get `dep` to authenticate to a `git` repo?](#how-do-i-get-dep-to-authenticate-to-a-git-repo) 20 * [How do I get `dep` to consume private `git` repos using a GitHub Token?](#how-do-i-get-dep-to-consume-private-git-repos-using-a-github-token) 21 22 ## Behavior 23 24 * [How does `dep` decide what version of a dependency to use?](#how-does-dep-decide-what-version-of-a-dependency-to-use) 25 * [What is the default `dep ensure -update` behavior for dependencies that are imported but not included as a `[[Constraint]]` in `Gopkg.toml`?](#what-is-the-default-dep-ensure--update-behavior-for-dependencies-that-are-imported-but-not-included-as-a-constraint-in-gopkgtoml) 26 * [What external tools are supported?](#what-external-tools-are-supported) 27 * [Why is `dep` ignoring a version constraint in the manifest?](#why-is-dep-ignoring-a-version-constraint-in-the-manifest) 28 * [Why did `dep` use a different revision for package X instead of the revision in the lock file?](#why-did-dep-use-a-different-revision-for-package-x-instead-of-the-revision-in-the-lock-file) 29 * [Why is `dep` slow?](#why-is-dep-slow) 30 * [How does `dep` handle symbolic links?](#how-does-dep-handle-symbolic-links) 31 * [Does `dep` support relative imports?](#does-dep-support-relative-imports) 32 * [How do I make `dep` resolve dependencies from my `GOPATH`?](#how-do-i-make-dep-resolve-dependencies-from-my-gopath) 33 * [Will `dep` let me use git submodules to store dependencies in `vendor`?](#will-dep-let-me-use-git-submodules-to-store-dependencies-in-vendor) 34 * [How does `dep` work without changing my packages imports?](#how-does-dep-work-without-changing-my-packages-imports) 35 36 ## Best Practices 37 38 * [Should I commit my vendor directory?](#should-i-commit-my-vendor-directory) 39 * [How do I roll releases that `dep` will be able to use?](#how-do-i-roll-releases-that-dep-will-be-able-to-use) 40 * [What semver version should I use?](#what-semver-version-should-i-use) 41 * [Is it OK to make backwards-incompatible changes now?](#is-it-ok-to-make-backwards-incompatible-changes-now) 42 * [My dependers don't use `dep` yet. What should I do?](#my-dependers-don-t-use-dep-yet-what-should-i-do) 43 * [How do I configure a dependency that doesn't tag its release](#how-do-i-configure-a-dependency-that-doesn-t-tag-its-releases) 44 * [How do I use `dep` with Docker?](#how-do-i-use-dep-with-docker) 45 * [How do I use `dep` in CI?](#how-do-i-use-dep-in-ci) 46 47 ## Concepts 48 49 ### Does `dep` replace `go get`? 50 51 No. `dep` and `go get` serve mostly different purposes. 52 53 Here are some suggestions for when you could use `dep` or `go get`: 54 55 > I would say that dep doesn't replace go get, but they both can do similar things. Here's how I use them: 56 > 57 > `go get`: I want to download the source code for a go project so that I can work on it myself, or to install a tool. This clones the repo under GOPATH for all to use. 58 > 59 > `dep ensure`: I have imported a new dependency in my code and want to download the dependency so I can start using it. My workflow is "add the import to the code, and then run dep ensure so that the manifest/lock/vendor are updated". This clones the repo under my project's vendor directory, and remembers the revision used so that everyone who works on my project is guaranteed to be using the same version of dependencies. 60 > 61 > [@carolynvs in #376](https://github.com/golang/dep/issues/376#issuecomment-293964655) 62 63 > The long term vision is a sane, overall-consistent go tool. My general take is that `go get` 64 > is for people consuming Go code, and dep-family commands are for people developing it. 65 > 66 > [@sdboyer in #376](https://github.com/golang/dep/issues/376#issuecomment-294045873) 67 68 ### Why is it `dep ensure` instead of `dep install`? 69 70 > Yeah, we went round and round on names. [A lot](https://gist.github.com/jessfraz/315db91b272441f510e81e449f675a8b). 71 > 72 > The idea of "ensure" is roughly, "ensure that all my local states - code tree, manifest, lock, and vendor - are in sync with each other." When arguments are passed, it becomes "ensure this argument is satisfied, along with synchronization between all my local states." 73 > 74 > We opted for this approach because we came to the conclusion that allowing the tool to perform partial work/exit in intermediate states ended up creating a tool that had more commands, had far more possible valid exit and input states, and was generally full of footguns. In this approach, the user has most of the same ultimate control, but exercises it differently (by modifying the code/manifest and re-running dep ensure). 75 > 76 > [@sdboyer in #371](https://github.com/golang/dep/issues/371#issuecomment-293246832) 77 78 ### What is a direct or transitive dependency? 79 80 * Direct dependencies are dependencies that are imported directly by your project: they appear in at least one import statement from your project. 81 * Transitive dependencies are the dependencies of your dependencies. Necessary to compile but are not directly used by your code. 82 83 ## Configuration 84 85 ### What is the difference between `Gopkg.toml` (the "manifest") and `Gopkg.lock` (the "lock")? 86 87 > The manifest describes user intent, and the lock describes computed outputs. There's flexibility in manifests that isn't present in locks..., as the "branch": "master" constraint will match whatever revision master HAPPENS to be at right now, whereas the lock is nailed down to a specific revision. 88 > 89 > This flexibility is important because it allows us to provide easy commands (e.g. `dep ensure -update`) that can manage an update process for you, within the constraints you specify, AND because it allows your project, when imported by someone else, to collaboratively specify the constraints for your own dependencies. 90 > 91 > [@sdboyer in #281](https://github.com/golang/dep/issues/281#issuecomment-284118314) 92 93 ## <a id="how-do-i-constrain-a-transitive-dependency-s-version"></a>How do I constrain a transitive dependency's version? 94 95 First, if you're wondering about this because you're trying to keep the version 96 of the transitive dependency from changing, then you're working against `dep`'s 97 design. The lock file, `Gopkg.lock`, will keep the selected version of the 98 transitive dependency stable, unless you explicitly request an upgrade or it's 99 impossible to find a solution without changing that version. 100 101 If that isn't your use case and you still need to constrain a transitive 102 dependency, you have a couple of options: 103 104 1. Make the transitive dependency a direct one, either with a dummy import or an entry in the `required` list in `Gopkg.toml`. 105 2. Use an override. 106 107 Overrides are a sledgehammer, and should only be used as a last resort. While 108 constraints and overrides are declared in the same way in `Gopkg.toml`, they 109 behave differently: 110 111 * Constraints: 112 1. Can be declared by any project's manifest, yours or a dependency 113 2. Apply only to direct dependencies of the project declaring the constraint 114 3. Must not conflict with the `constraint` entries declared in any other project's manifest 115 * Overrides: 116 1. Are only utilized from the current/your project's manifest 117 2. Apply globally, to direct and transitive dependencies 118 3. Supersede constraints declared in all manifests, yours or a dependency's 119 120 Overrides are also discussed with some visuals in [the gps docs](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#overrides). 121 122 ## How do I change the version of a dependency 123 124 If you want to: 125 126 * Change the allowed `version`/`branch`/`revision` 127 * Switch to using a fork 128 129 for one or more dependencies, do the following: 130 131 1. Manually edit your `Gopkg.toml`. 132 1. Run 133 134 ```sh 135 $ dep ensure 136 ``` 137 138 ## Can I put the manifest and lock in the vendor directory? 139 140 No. 141 142 > Placing these files inside `vendor/` would concretely bind us to `vendor/` in the long term. 143 > We prefer to treat the `vendor/` as an implementation detail. 144 > 145 > [@sdboyer on go package management list](https://groups.google.com/d/msg/go-package-management/et1qFUjrkP4/LQFCHP4WBQAJ) 146 147 ## How do I get dep to authenticate to a git repo? 148 149 `dep` currently uses the `git` command under the hood, so configuring the credentials 150 for each repository you wish to authenticate to will allow `dep` to use an 151 authenticated repository. 152 153 First, configure `git` to use the credentials option for the specific repository. 154 155 For example, if you use GitLab, and you wish to access `https://gitlab.example.com/example/package.git`, 156 then you would want to use the following configuration: 157 158 ``` 159 $ git config --global credential.https://gitlab.example.com.example yourusername 160 ``` 161 162 In the example the hostname `gitlab.example.com.example` string seems incorrect, but 163 it's actually the hostname plus the name of the repo you are accessing which is `username`. 164 The trailing 'yourusername' is the username you would use for the actual authentication. 165 166 You also need to configure `git` with the authentication provider you wish to use. You can get 167 a list of providers, with the command: 168 169 ``` 170 $ git help -a | grep credential- 171 credential-cache remote-fd 172 credential-cache--daemon remote-ftp 173 credential-osxkeychain remote-ftps 174 credential-store remote-http 175 ``` 176 177 You would then choose an appropriate provider. For example, to use the osxkeychain, you 178 would use the following: 179 180 ``` 181 git config --global credential.helper osxkeychain 182 ``` 183 184 If you need to do this for a CI system, then you may want to use the "store" provider. 185 Please see the documentation on how to configure that: https://git-scm.com/docs/git-credential-store 186 187 After configuring `git`, you may need to use `git` manually once to have it store the 188 credentials. Once you've checked out the repo manually, it will then use the stored 189 credentials. This at least appears to be the behavior for the osxkeychain provider. 190 191 ### How do I get dep to consume private git repos using a GitHub Token? 192 193 Another alternative to make `dep` work with private repos is to use a [Personal GitHub 194 Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) 195 and configure it inside the [`.netrc` file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html) 196 as the following example: 197 198 ``` 199 machine github.com 200 login [YOUR_GITHUB_USERNAME] 201 password [YOUR_GITHUB_TOKEN] 202 ``` 203 204 Once you have set that up, dep will automatically use that Token to authenticate to the repositories. 205 206 ## How do I get dep to authenticate via SSH to a git repo? 207 208 You can rewrite the repo url and use the git+ssh shema with follow example: 209 210 ``` 211 git config --global url."git@github.yourEnterprise.com:".insteadOf "https://github.yourEnterprise.com/" 212 213 ``` 214 215 216 ## Behavior 217 218 ### How does `dep` decide what version of a dependency to use? 219 220 The full algorithm is complex, but the most important thing to understand is 221 that `dep` tries versions in a [certain 222 order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade), 223 checking to see a version is acceptable according to specified constraints. 224 225 * All semver versions come first, and sort mostly according to the semver 2.0 226 spec, with one exception: 227 * Semver versions with a prerelease are sorted after _all_ non-prerelease 228 semver. Within this subset they are sorted first by their numerical 229 component, then lexicographically by their prerelease version. 230 * The default branch(es) are next; the semantics of what "default branch" means 231 are specific to the underlying source type, but this is generally what you'd 232 get from a `go get`. 233 * All other branches come next, sorted lexicographically. 234 * All non-semver versions (tags) are next, sorted lexicographically. 235 * Revisions, if any, are last, sorted lexicographically. Revisions do not 236 typically appear in version lists, so the only invariant we maintain is 237 determinism - deeper semantics, like chronology or topology, do not matter. 238 239 So, given a slice of the following versions: 240 241 * Branch: `master` `devel` 242 * Semver tags: `v1.0.0` `v1.1.0` `v1.1.0-alpha1` 243 * Non-semver tags: `footag` 244 * Revision: `f6e74e8d` 245 246 Sorting for upgrade will result in the following slice: 247 248 `[v1.1.0 v1.0.0 v1.1.0-alpha1 master devel footag f6e74e8d]` 249 250 There are a number of factors that can eliminate a version from consideration, 251 the simplest of which is that it doesn't match a constraint. But if you're 252 trying to figure out why `dep` is doing what it does, understanding that its 253 basic action is to attempt versions in this order should help you to reason 254 about what's going on. 255 256 ## What is the default `dep ensure -update` behavior for dependencies that are imported but not included as a `[[Constraint]]` in `Gopkg.toml`? 257 `dep` updates the dependency to the latest semver tag. If there are no semver tags, `dep` uses the tip of master. 258 259 ## What external tools are supported? 260 261 During `dep init` configuration from other dependency managers is detected 262 and imported, unless `-skip-tools` is specified. 263 264 The following tools are supported: `glide`, `godep`, `vndr`, `govend`, `gb`, `gvt`, `govendor` and `glock`. 265 266 See [#186](https://github.com/golang/dep/issues/186#issuecomment-306363441) for 267 how to add support for another tool. 268 269 ## Why is `dep` ignoring a version constraint in the manifest? 270 271 Only your project's directly imported dependencies are affected by a `constraint` entry 272 in the manifest. Transitive dependencies are unaffected. See [How do I constrain a transitive dependency's version](#how-do-i-constrain-a-transitive-dependency-s-version)? 273 274 ## Why did `dep` use a different revision for package X instead of the revision in the lock file? 275 276 Sometimes the revision specified in the lock file is no longer valid. There are a few 277 ways this can occur: 278 279 * When you generated the lock file, you had an unpushed commit in your local copy of package X's repository in your `GOPATH`. (This case will be going away soon) 280 * After generating the lock file, new commits were force pushed to package X's repository, causing the commit revision in your lock file to no longer exist. 281 282 To troubleshoot, you can revert dep's changes to your lock, and then run `dep ensure -v -n`. 283 This retries the command in dry-run mode with verbose logs enabled. Check the output 284 for a warning like the one below, indicating that a commit in the lock is no longer valid. 285 286 ``` 287 Unable to update checked out version: fatal: reference is not a tree: 4dfc6a8a7e15229398c0a018b6d7a078cccae9c8 288 ``` 289 290 > The lock file represents a set of precise, typically immutable versions for the entire transitive closure of dependencies for a project. But "the project" can be, and is, decomposed into just a bunch of arguments to an algorithm. When those inputs change, the lock may need to change as well. 291 > 292 > Under most circumstances, if those arguments don't change, then the lock remains fine and correct. You've hit one of the few cases where that guarantee doesn't apply. The fact that you ran dep ensure and it DID a solve is a product of some arguments changing; that solving failed because this particular commit had become stale is a separate problem. 293 > 294 > [@sdboyer in #405](https://github.com/golang/dep/issues/405#issuecomment-295998489) 295 296 ## Why is `dep` slow? 297 298 There are two things that really slow `dep` down. One is unavoidable; for the other, we have a plan. 299 300 The unavoidable part is the initial clone. `dep` relies on a cache of local 301 repositories (stored under `$GOPATH/pkg/dep`), which is populated on demand. 302 Unfortunately, the first `dep` run, especially for a large project, may take a 303 while, as all dependencies are cloned into the cache. 304 305 Fortunately, this is just an _initial_ clone - pay it once, and you're done. 306 The problem repeats itself a bit when you're running `dep` for the first time 307 in a while and there's new changesets to fetch, but even then, these costs are 308 only paid once per changeset. 309 310 The other part is the work of retrieving information about dependencies. There are three parts to this: 311 312 1. Getting an up-to-date list of versions from the upstream source 313 2. Reading the `Gopkg.toml` for a particular version out of the local cache 314 3. Parsing the tree of packages for import statements at a particular version 315 316 The first requires one or more network calls; the second two usually mean 317 something like a `git checkout`, and the third is a filesystem walk, plus 318 loading and parsing `.go` files. All of these are expensive operations. 319 320 Fortunately, we can cache the second and third. And that cache can be permanent 321 when keyed on an immutable identifier for the version - like a git commit SHA1 322 hash. The first is a bit trickier, but there are reasonable staleness tradeoffs 323 we can consider to avoid the network entirely. There's an issue to [implement 324 persistent caching](https://github.com/golang/dep/issues/431) that's the 325 gateway to all of these improvements. 326 327 There's another major performance issue that's much harder - the process of picking versions itself is an NP-complete problem in `dep`'s current design. This is a much trickier problem 😜 328 329 ## How does `dep` handle symbolic links? 330 331 > because we're not crazy people who delight in inviting chaos into our lives, we need to work within one `GOPATH` at a time. -[@sdboyer in #247](https://github.com/golang/dep/pull/247#issuecomment-284181879) 332 333 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`. 334 335 When `dep` is invoked with a project root that is a symlink, it will be resolved according to the following rules: 336 337 * If the symlink is outside `GOPATH` and links to a directory within a `GOPATH`, or vice versa, then `dep` will choose whichever path is within `GOPATH`. 338 * If the symlink is within a `GOPATH` and the resolved path is within a _different_ `GOPATH`, then an error is thrown. 339 * If both the symlink and the resolved path are in the same `GOPATH`, then an error is thrown. 340 * If neither the symlink nor the resolved path are in a `GOPATH`, then an error is thrown. 341 342 This is the only symbolic link support that `dep` really intends to provide. In keeping with the general practices of the `go` tool, `dep` tends to either ignore symlinks (when walking) or copy the symlink itself, depending on the filesystem operation being performed. 343 344 ## Does `dep` support relative imports? 345 346 No. 347 348 > dep simply doesn't allow relative imports. this is one of the few places where we restrict a case that the toolchain itself allows. we disallow them only because: 349 > 350 > * the toolchain already frowns heavily on them<br> 351 > * it's worse for our case, as we start venturing into [dot dot hell](http://doc.cat-v.org/plan_9/4th_edition/papers/lexnames) territory when trying to prove that the import does not escape the tree of the project 352 > 353 > [@sdboyer in #899](https://github.com/golang/dep/issues/899#issuecomment-317904001) 354 355 For a refresher on Go's recommended workspace organization, see the ["How To Write Go Code"](https://golang.org/doc/code.html) article in the Go docs. Organizing your code this way gives you a unique import path for every package. 356 357 ## How do I make `dep` resolve dependencies from my `GOPATH`? 358 359 `dep init` provides an option to scan the `GOPATH` for dependencies by doing 360 `dep init -gopath`, which falls back to network mode when the packages are not 361 found in `GOPATH`. `dep ensure` doesn't work with projects in `GOPATH`. 362 363 ## Will `dep` let me use git submodules to store dependencies in `vendor`? 364 365 No, with just one tiny exception: `dep` preserves `/vendor/.git`, if it exists. This was added at [cockroachdb](https://github.com/cockroachdb/cockroach)'s request, who rely on it to keep `vendor` from bloating their primary repository. 366 367 The reasons why git submodules will not be a part of dep are best expressed as a pro/con list: 368 369 **Pros** 370 371 * git submodules provide a well-structured way of nesting repositories within repositories. 372 373 **Cons** 374 375 * The nesting that git submodules perform is no more powerful or expressive than what dep already does, but dep does it both more generally (for bzr and hg) and more domain-specifically (e.g. elimination of nested vendor directories). 376 * Incorporating git submodules in any way would new fork new paths in the logic to handle the submodule cases, meaning nontrivial complexity increases. 377 * dep does not currently know or care if the project it operates on is under version control. Relying on submodules would entail that dep start paying attention to that. That it would only be conditionally does not make it better - again, more forking paths in the logic, more complexity. 378 * Incorporating submodules in a way that is at all visible to the user (and why else would you do it?) makes dep's workflows both more complicated and less predictable: _sometimes_ submodule-related actions are expected; _sometimes_ submodule-derived workflows are sufficient. 379 * Nesting one repository within another implies that changes could, potentially, be made directly in that subrepository. This is directly contrary to dep's foundational principle that `vendor` is dead code, and directly modifying anything in there is an error. 380 381 ## How does `dep` work without changing my packages imports? 382 383 `dep` doesn't require imports (or the `$GOPATH`) to be updated because [go has native support for a vendor directory since version 1.5](https://golang.org/cmd/go/#hdr-Vendor_Directories). You do not need to update import paths to be relative. For instance, `import github.com/user/awesome-project` will be found in the project's `/vendor/github.com/user/awesome-project` before looking to `$GOPATH/src/github.com/user/awesome-project`. 384 385 ## Best Practices 386 387 ### Should I commit my vendor directory? 388 389 It's up to you: 390 391 **Pros** 392 393 * It's the only way to get truly reproducible builds, as it guards against upstream renames, 394 deletes and commit history overwrites. 395 * You don't need an extra `dep ensure` step to sync `vendor/` with `Gopkg.lock` after most operations, 396 such as `go get`, cloning, getting latest, merging, etc. 397 398 **Cons** 399 400 * Your repo will be bigger, potentially a lot bigger, 401 though [`prune`](Gopkg.toml.md#prune) can help minimize this problem. 402 * PR diffs will include changes for files under `vendor/` when `Gopkg.lock` is modified, 403 however files in `vendor/` are [hidden by default](https://github.com/github/linguist/blob/v5.2.0/lib/linguist/generated.rb#L328) on GitHub. 404 405 ## How do I roll releases that `dep` will be able to use? 406 407 In short: make sure you've committed your `Gopkg.toml` and `Gopkg.lock`, then 408 just create a tag in your version control system and push it to the canonical 409 location. `dep` is designed to work automatically with this sort of metadata 410 from `git`, `bzr`, and `hg`. 411 412 It's strongly preferred that you use [semver](http://semver.org)-compliant tag 413 names. We hope to develop documentation soon that describes this more precisely, 414 but in the meantime, the [npm](https://docs.npmjs.com/misc/semver) docs match 415 our patterns pretty well. 416 417 ## What semver version should I use? 418 419 This can be a nuanced question, and the community is going to have to work out 420 some accepted standards for how semver should be applied to Go projects. At the 421 highest level, though, these are the rules: 422 423 * Below `v1.0.0`, anything goes. Use these releases to figure out what you want 424 your API to be. 425 * Above `v1.0.0`, the general Go best practices continue to apply - don't make 426 backwards-incompatible changes - exported identifiers can be added to, but 427 not changed or removed. 428 * If you must make a backwards-incompatible change, then bump the major version. 429 430 It's important to note that having a `v1.0.0` does not preclude you from having 431 alpha/beta/etc releases. The semver spec allows for [prerelease 432 versions](http://semver.org/#spec-item-9), and `dep` is careful to _not_ allow 433 such versions unless `Gopkg.toml` contains a range constraint that explicitly 434 includes prereleases: if there exists a version `v1.0.1-alpha4`, then the 435 constraint `>=1.0.0` will not match it, but `>=1.0.1-alpha1` will. 436 437 Some work has been done towards [a tool 438 to](https://github.com/bradleyfalzon/apicompat) that will analyze and compare 439 your code with the last release, and suggest the next version you should use. 440 441 ## Is it OK to make backwards-incompatible changes now? 442 443 Yes. But. 444 445 `dep` will make it possible for the Go ecosystem to handle 446 backwards-incompatible changes more gracefully. However, `dep` is not some 447 magical panacea. Version and dependency management is hard, and dependency hell 448 is real. The longstanding community wisdom about avoiding breaking changes 449 remains important. Any `v1.0.0` release should be accompanied by a plan for how 450 to avoid future breaking API changes. 451 452 One good strategy may be to add to your API instead of changing it, deprecating 453 old versions as you progress. Then, when the time is right, you can roll a new 454 major version and clean out a bunch of deprecated symbols all at once. 455 456 Note that providing an incremental migration path across breaking changes (i.e., 457 shims) is tricky, and something we [don't have a good answer for 458 yet](https://groups.google.com/forum/#!topic/go-package-management/fp2uBMf6kq4). 459 460 ## <a id="my-dependers-don-t-use-dep-yet-what-should-i-do"></a>My dependers don't use `dep` yet. What should I do? 461 462 For the most part, you needn't do anything differently. 463 464 The only possible issue is if your project is ever consumed as a library. If 465 so, then you may want to be wary about committing your `vendor/` directory, as 466 it can [cause 467 problems](https://groups.google.com/d/msg/golang-nuts/AnMr9NL6dtc/UnyUUKcMCAAJ). 468 If your dependers are using `dep`, this is not a concern, as `dep` takes care of 469 stripping out nested `vendor` directories. 470 471 ## <a id="how-do-i-configure-a-dependency-that-doesn-t-tag-its-releases"></a>How do I configure a dependency that doesn't tag its releases? 472 473 Add a constraint to `Gopkg.toml` that specifies `branch: "master"` (or whichever branch you need) in the `[[constraint]]` for that dependency. `dep ensure` will determine the current revision of your dependency's master branch, and place it in `Gopkg.lock` for you. See also: [What is the difference between Gopkg.toml and Gopkg.lock?](#what-is-the-difference-between-gopkgtoml-the-manifest-and-gopkglock-the-lock) 474 475 ## How do I use `dep` with Docker? 476 477 `dep ensure -vendor-only` creates the vendor folder from a valid `Gopkg.toml` and `Gopkg.lock` without checking for Go code. 478 This is especially useful for builds inside docker utilizing cache layers. 479 480 Sample Dockerfile: 481 482 ```Dockerfile 483 FROM golang:1.9 AS builder 484 485 RUN curl -fsSL -o /usr/local/bin/dep https://github.com/golang/dep/releases/download/vX.X.X/dep-linux-amd64 && chmod +x /usr/local/bin/dep 486 487 RUN mkdir -p /go/src/github.com/*** 488 WORKDIR /go/src/github.com/*** 489 490 COPY Gopkg.toml Gopkg.lock ./ 491 # copies the Gopkg.toml and Gopkg.lock to WORKDIR 492 493 RUN dep ensure -vendor-only 494 # install the dependencies without checking for go code 495 496 ... 497 ``` 498 499 ## How do I use `dep` in CI? 500 501 Since `dep` is expected to change until `v1.0.0` is released, it is recommended to rely on a released version. 502 You can find the latest binary from the [releases](https://github.com/golang/dep/releases) page. 503 504 Sample configuration for Travis CI: 505 506 ```yml 507 # ... 508 509 env: 510 - DEP_VERSION="X.X.X" 511 512 before_install: 513 # Download the binary to bin folder in $GOPATH 514 - curl -L -s https://github.com/golang/dep/releases/download/v${DEP_VERSION}/dep-linux-amd64 -o $GOPATH/bin/dep 515 # Make the binary executable 516 - chmod +x $GOPATH/bin/dep 517 518 install: 519 - dep ensure 520 ``` 521 522 Caching can also be enabled but there are a couple of caveats you should be aware of: 523 524 > Until recently, we have had intermittent cache corruption that would have been super annoying if it was breaking Travis build too. 525 > 526 > Also according to https://docs.travis-ci.com/user/caching/#Things-not-to-cache, they don't recommend it for larger caches. 527 > 528 > https://docs.travis-ci.com/user/caching/#How-does-the-caching-work%3F 529 > 530 > > Note that this makes our cache not network-local, it's still bound to network bandwidth and DNS resolutions for S3. 531 > > That impacts what you can and should store in the cache. If you store archives larger than a few hundred megabytes in the cache, it's unlikely that you'll see a big speed improvement. 532 > 533 > [@carolynvs in #1293](https://github.com/golang/dep/pull/1293#issuecomment-342969292) 534 535 If you are sure you want to enable caching on Travis, it can be done by adding `$GOPATH/pkg/dep`, the default location for `dep` cache, to the cached directories: 536 537 ```yml 538 # ... 539 540 cache: 541 directories: 542 - $GOPATH/pkg/dep 543 ```