From c20dddcdc17872f956391b1eda6cac9364cea4dc Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Wed, 19 Apr 2017 11:52:48 -0500 Subject: [PATCH 1/7] Add a FAQ --- CONTRIBUTING.md | 2 + FAQ.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 3 +- 3 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 FAQ.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06df1a4901..6194bad69f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,6 +8,8 @@ Keep an eye on the [Roadmap](https://github.com/golang/dep/wiki/Roadmap) for a s ## Filing issues +Please check the existing issues and [FAQ](FAQ.md) to see if your feedback has already been reported. + When [filing an issue](https://github.com/golang/dep/issues/new), make sure to answer these five questions: 1. What version of Go are you using (`go version`)? diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000000..b22075bd3f --- /dev/null +++ b/FAQ.md @@ -0,0 +1,112 @@ +# FAQ + +_The first rule of FAQ is don't bikeshed the FAQ, leave that for +[Create structure for managing docs](https://github.com/golang/dep/issues/331)._ + +Please contribute to the FAQ! Found an explanation in an issue or pull request helpful? +Summarize the question and quote the reply, linking back to the original comment. + +* [What is a direct or transitive dependency?](#what-is-a-direct-or-transitive-dependency) +* [Why is it `dep ensure` instead of `dep install`?](#why-is-it-dep-ensure-instead-of-dep-install) +* [Does `dep` replace `go get`?](#does-dep-replace-go-get) +* [Why did `dep ensure -update` not update package X?](#why-did-dep-ensure--update-not-update-package-x) +* [Why is `dep` ignoring the version specified in the manifest?](#why-is-dep-ignoring-the-version-specified-in-the-manifest) +* [`dep` deleted my files in the vendor directory!](#dep-deleted-my-files-in-the-vendor-directory) +* [Can I put the manifest and lock in the vendor directory?](#can-i-put-the-manifest-and-lock-in-the-vendor-directory) +* [Unable to update checked out version: fatal: reference is not a tree](#unable-to-update-checked-out-version-fatal-reference-is-not-a-tree) + +## What is a direct or transitive dependency? +* Direct dependencies are dependencies that are imported by your project. +* Transitive dependencies are the dependencies of your dependencies. Necessary to compile but are not directly used by your code. + +## Why is it `dep ensure` instead of `dep install`? + +> Yeah, we went round and round on names. [A lot](https://gist.github.com/jessfraz/315db91b272441f510e81e449f675a8b). +> +> 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." +> +> 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). +-[@sdboyer in #371](https://github.com/golang/dep/issues/371#issuecomment-293246832) + +## Does `dep` replace `go get`? + +> I would say that dep doesn't replace go get, but they both can do similar things. Here's how I use them: +> +> `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. +> +> `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. +-[@carolynvs in #376](https://github.com/golang/dep/issues/376#issuecomment-293964655) + +> The long term vision is a sane, overall-consistent go tool. My general take is that `go get` +> is for people consuming Go code, and dep-family commands are for people developing it. +-[@sdboyer in #376](https://github.com/golang/dep/issues/376#issuecomment-294045873) + +## Why did `dep ensure -update` not update package X? + + +* Is package X a direct dependency? [#385](https://github.com/golang/dep/issues/385) + + Constraints given in a project's manifest are only applied if the + dependent project is actually imported. Transitive dependencies (dependencies + of your imports) are only updated when the revision in the lockfile no + longer meets the constraints of your direct dependencies. + + > If you absolutely need to specify the constraint of a transitive dep from your own project, you have two options: + > + > Specify the constraint on github.com/gorilla/context via an override. Overrides apply globally, but are a power only given to the root project, so if anything else imports your project, the override won't be used. + > Mark github.com/gorilla/context as a required package in the manifest. This will cause it to be treated as a direct dependency, and your constraint will come into effect. + > + > However, before taking either of those steps, I'd say it's worth asking if you actually need to use master of github.com/gorilla/context. I imagine it's imported by github.com/gorilla/mux - and if that package is OK with using the tagged release instead of master (which is the preferred mode of operation anyway), then maybe that should be good enough for you? If you really needed something out of github.com/gorilla/context, then you'd probably be importing it directly and doing something with it + -[@sdboyer in #385](https://github.com/golang/dep/issues/385#issuecomment-294361087) + +* Is package X included in the `ignored` list in your manifest? + + Remove it from `ignored` and try again. + +## Why is `dep` ignoring the version specified in the manifest? +Only direct dependencies can be managed with a `depenencies` entry +in the manifest. Use an `overrides` entry for transitive dependencies. + +> Constraints: +> +> 1. Can be declared by any project's manifest, yours or a dependency +> 2. Apply only to direct dependencies of the project declaring the constraint +> 3. Must not conflict with the constraints declared in any other project's manifest +> +> Overrides: +> +> 1. Are only utilized from the current/your project's manifest +> 2. Apply globally, to direct and transitive dependencies +> 3. Supercede constraints declared in all manifests, yours or a dependency's +> +> Overrides are also discussed with some visuals in [the gps docs](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#overrides). +-[@sdboyer in #328](https://github.com/golang/dep/issues/328#issuecomment-286631961) + +## `dep` deleted my files in the vendor directory! +First, sorry! 😞 We hope you were able to recover your files... + +> dep assumes complete control of vendor/, and may indeed blow things away if it feels like it. +-[@peterbourgon in #206](https://github.com/golang/dep/issues/206#issuecomment-277139419) + +## Can I put the manifest and lock in the vendor directory? +No. + +> Placing these files inside vendor/ would concretely bind us to vendor/ in the long term. +> We prefer to treat the use of vendor/ as an implementation detail. +-[@sdboyer on go package management list](https://groups.google.com/d/msg/go-package-management/et1qFUjrkP4/LQFCHP4WBQAJ) + +## Unable to update checked out version: fatal: reference is not a tree + +``` +solve error: No versions of github.com/groob/plist met constraints: + empty_data: Unable to update checked out version: fatal: reference is not a tree: 94c3023a0ab2ab1ae7ca10cf1b1416d00c0b77a0 + + master: Could not introduce github.com/groob/plist@master, as it is not allowed by constraint empty_data from project github.com/groob/autopkgd.No versions of github.com/groob/plist met constraints: + empty_data: Unable to update checked out version: fatal: reference is not a tree: 94c3023a0ab2ab1ae7ca10cf1b1416d00c0b77a0 + + master: Could not introduce github.com/groob/plist@master, as it is not allowed by constraint empty_data from project github.com/groob/autopkgd. +``` +-[@groob in #216](https://github.com/golang/dep/issues/216#issue-204717822) + +This can occur when a package in your GOPATH has unpushed commits. Either push the commit(s), +or checkout a commit that is present on the remote. \ No newline at end of file diff --git a/README.md b/README.md index fc54df8265..0a7b88f58b 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ Please see below for feedback and contribution guidelines. - [User Stories](https://docs.google.com/document/d/1wT8e8wBHMrSRHY4UF_60GCgyWGqvYye4THvaDARPySs/edit) - [Features](https://docs.google.com/document/d/1JNP6DgSK-c6KqveIhQk-n_HAw3hsZkL-okoleM43NgA/edit) - [Design Space](https://docs.google.com/document/d/1TpQlQYovCoX9FkpgsoxzdvZplghudHAiQOame30A-v8/edit) +- [Frequently Asked Questions](FAQ.md) ## Usage @@ -55,7 +56,7 @@ 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 to see if your feedback has already been reported. +Please check the existing issues and [FAQ](FAQ.md) 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 From 1d443310c2dd617550578bdefac0f5ecf0328803 Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Fri, 21 Apr 2017 09:05:13 -0500 Subject: [PATCH 2/7] FAQ: Should I commit my vendor directory? --- FAQ.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/FAQ.md b/FAQ.md index b22075bd3f..89b32a529f 100644 --- a/FAQ.md +++ b/FAQ.md @@ -7,6 +7,7 @@ Please contribute to the FAQ! Found an explanation in an issue or pull request h Summarize the question and quote the reply, linking back to the original comment. * [What is a direct or transitive dependency?](#what-is-a-direct-or-transitive-dependency) +* [Should I commit my vendor directory?](#should-i-commit-my-vendor-directory) * [Why is it `dep ensure` instead of `dep install`?](#why-is-it-dep-ensure-instead-of-dep-install) * [Does `dep` replace `go get`?](#does-dep-replace-go-get) * [Why did `dep ensure -update` not update package X?](#why-did-dep-ensure--update-not-update-package-x) @@ -17,15 +18,24 @@ Summarize the question and quote the reply, linking back to the original comment ## What is a direct or transitive dependency? * Direct dependencies are dependencies that are imported by your project. -* Transitive dependencies are the dependencies of your dependencies. Necessary to compile but are not directly used by your code. +* Transitive dependencies are the dependencies of your dependencies. Necessary + to compile but are not directly used by your code. + +## Should I commit my vendor directory? + +Committing the vendor directory is totally up to you. There is no general advice that applies in all cases. + +**Pros**: it's the only way to get truly reproducible builds, as it guards against upstream renames and deletes; and you don't need an extra `dep ensure` step on fresh clones to build your repo. + +**Cons**: your repo will be bigger, potentially a lot bigger; and PR diffs are more annoying. ## Why is it `dep ensure` instead of `dep install`? > Yeah, we went round and round on names. [A lot](https://gist.github.com/jessfraz/315db91b272441f510e81e449f675a8b). > -> 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." +> 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." > -> 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). +> 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). -[@sdboyer in #371](https://github.com/golang/dep/issues/371#issuecomment-293246832) ## Does `dep` replace `go get`? From c41dfceb7d310fbf67fd6899795572547a0ac6d6 Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Fri, 21 Apr 2017 09:32:28 -0500 Subject: [PATCH 3/7] Fix typo --- FAQ.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FAQ.md b/FAQ.md index 89b32a529f..f264a52a2c 100644 --- a/FAQ.md +++ b/FAQ.md @@ -74,7 +74,7 @@ Committing the vendor directory is totally up to you. There is no general advice Remove it from `ignored` and try again. ## Why is `dep` ignoring the version specified in the manifest? -Only direct dependencies can be managed with a `depenencies` entry +Only direct dependencies can be managed with a `dependencies` entry in the manifest. Use an `overrides` entry for transitive dependencies. > Constraints: From 227404c5617f8b638e657df45dc8d6249c0cc9f7 Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Fri, 21 Apr 2017 09:33:45 -0500 Subject: [PATCH 4/7] =?UTF-8?q?Update=20answer=20for=20=E2=80=9Crevision?= =?UTF-8?q?=20is=20not=20a=20tree=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The behavior has changed, and now instead of a failing, dep picks a new commit. --- FAQ.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/FAQ.md b/FAQ.md index f264a52a2c..965851da22 100644 --- a/FAQ.md +++ b/FAQ.md @@ -14,7 +14,7 @@ Summarize the question and quote the reply, linking back to the original comment * [Why is `dep` ignoring the version specified in the manifest?](#why-is-dep-ignoring-the-version-specified-in-the-manifest) * [`dep` deleted my files in the vendor directory!](#dep-deleted-my-files-in-the-vendor-directory) * [Can I put the manifest and lock in the vendor directory?](#can-i-put-the-manifest-and-lock-in-the-vendor-directory) -* [Unable to update checked out version: fatal: reference is not a tree](#unable-to-update-checked-out-version-fatal-reference-is-not-a-tree) +* [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) ## What is a direct or transitive dependency? * Direct dependencies are dependencies that are imported by your project. @@ -105,18 +105,22 @@ No. > We prefer to treat the use of vendor/ as an implementation detail. -[@sdboyer on go package management list](https://groups.google.com/d/msg/go-package-management/et1qFUjrkP4/LQFCHP4WBQAJ) -## Unable to update checked out version: fatal: reference is not a tree +## Why did dep use a different revision for package X instead of the revision in the lock file? +Sometimes the revision specified in the lock file is no longer valid. There are a few +ways this can occur: -``` -solve error: No versions of github.com/groob/plist met constraints: - empty_data: Unable to update checked out version: fatal: reference is not a tree: 94c3023a0ab2ab1ae7ca10cf1b1416d00c0b77a0 +* When you generated the lock file, you had an unpushed commit in your local copy of package X's repository in your GOPATH. +* 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. - master: Could not introduce github.com/groob/plist@master, as it is not allowed by constraint empty_data from project github.com/groob/autopkgd.No versions of github.com/groob/plist met constraints: - empty_data: Unable to update checked out version: fatal: reference is not a tree: 94c3023a0ab2ab1ae7ca10cf1b1416d00c0b77a0 +To troubleshoot, you can revert dep's changes to your lock, and then run `dep ensure -v -n`. +This retries the command in dry-run mode with verbose logs enabled. Check the output +for a warning like the one below, indicating that a commit in the lock is no longer valid. - master: Could not introduce github.com/groob/plist@master, as it is not allowed by constraint empty_data from project github.com/groob/autopkgd. ``` --[@groob in #216](https://github.com/golang/dep/issues/216#issue-204717822) +Unable to update checked out version: fatal: reference is not a tree: 4dfc6a8a7e15229398c0a018b6d7a078cccae9c8 +``` -This can occur when a package in your GOPATH has unpushed commits. Either push the commit(s), -or checkout a commit that is present on the remote. \ No newline at end of file +> 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. +> +> Under most circumstances, if those arguments don't change, then the lock remains fine and correct. You've hit one 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. +-[@sdboyer in #405](https://github.com/golang/dep/issues/405#issuecomment-295998489) \ No newline at end of file From db0acd400af53ccd5a8babbca5bf1c16f38e3140 Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Fri, 21 Apr 2017 09:34:13 -0500 Subject: [PATCH 5/7] =?UTF-8?q?Correct=20answer=20for=20why=20deploy=20did?= =?UTF-8?q?n=E2=80=99t=20update=20a=20dependency=20as=20expected?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- FAQ.md | 30 ++++++++++++------------------ 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/FAQ.md b/FAQ.md index 965851da22..4b082d972c 100644 --- a/FAQ.md +++ b/FAQ.md @@ -52,26 +52,20 @@ Committing the vendor directory is totally up to you. There is no general advice -[@sdboyer in #376](https://github.com/golang/dep/issues/376#issuecomment-294045873) ## Why did `dep ensure -update` not update package X? +Is package X a direct dependency? [#385](https://github.com/golang/dep/issues/385) +Constraints given in a project's manifest are only applied if the +dependent project is actually imported. Transitive dependencies (dependencies +of your imports) are only updated when the revision in the lockfile no +longer meets the constraints of your direct dependencies. -* Is package X a direct dependency? [#385](https://github.com/golang/dep/issues/385) - - Constraints given in a project's manifest are only applied if the - dependent project is actually imported. Transitive dependencies (dependencies - of your imports) are only updated when the revision in the lockfile no - longer meets the constraints of your direct dependencies. - - > If you absolutely need to specify the constraint of a transitive dep from your own project, you have two options: - > - > Specify the constraint on github.com/gorilla/context via an override. Overrides apply globally, but are a power only given to the root project, so if anything else imports your project, the override won't be used. - > Mark github.com/gorilla/context as a required package in the manifest. This will cause it to be treated as a direct dependency, and your constraint will come into effect. - > - > However, before taking either of those steps, I'd say it's worth asking if you actually need to use master of github.com/gorilla/context. I imagine it's imported by github.com/gorilla/mux - and if that package is OK with using the tagged release instead of master (which is the preferred mode of operation anyway), then maybe that should be good enough for you? If you really needed something out of github.com/gorilla/context, then you'd probably be importing it directly and doing something with it - -[@sdboyer in #385](https://github.com/golang/dep/issues/385#issuecomment-294361087) - -* Is package X included in the `ignored` list in your manifest? - - Remove it from `ignored` and try again. +> If you absolutely need to specify the constraint of a transitive dep from your own project, you have two options: +> +> Specify the constraint on github.com/gorilla/context via an override. Overrides apply globally, but are a power only given to the root project, so if anything else imports your project, the override won't be used. +> Mark github.com/gorilla/context as a required package in the manifest. This will cause it to be treated as a direct dependency, and your constraint will come into effect. +> +> However, before taking either of those steps, I'd say it's worth asking if you actually need to use master of github.com/gorilla/context. I imagine it's imported by github.com/gorilla/mux - and if that package is OK with using the tagged release instead of master (which is the preferred mode of operation anyway), then maybe that should be good enough for you? If you really needed something out of github.com/gorilla/context, then you'd probably be importing it directly and doing something with it +-[@sdboyer in #385](https://github.com/golang/dep/issues/385#issuecomment-294361087) ## Why is `dep` ignoring the version specified in the manifest? Only direct dependencies can be managed with a `dependencies` entry From 15de9b07207d7013372f03d1e49426cc4830dab4 Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Fri, 21 Apr 2017 11:19:00 -0500 Subject: [PATCH 6/7] Add caveats to dep vs. go get answer --- FAQ.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/FAQ.md b/FAQ.md index 4b082d972c..a4903d7ac5 100644 --- a/FAQ.md +++ b/FAQ.md @@ -39,7 +39,11 @@ Committing the vendor directory is totally up to you. There is no general advice -[@sdboyer in #371](https://github.com/golang/dep/issues/371#issuecomment-293246832) ## Does `dep` replace `go get`? +No, `dep` is an experiment and is still in its infancy. Depending on how this +experiment goes, it may be considered for inclusion in the go project in some form +or another in the future but that is not guaranteed. +Here are some suggestions for when you could use `dep` or `go get`: > I would say that dep doesn't replace go get, but they both can do similar things. Here's how I use them: > > `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. From 3617095fcbf7f859a4febb76d56e95a7b5014ba5 Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Fri, 21 Apr 2017 14:24:37 -0500 Subject: [PATCH 7/7] Attempt to better explain why -update doesn't work for transitive deps --- FAQ.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/FAQ.md b/FAQ.md index a4903d7ac5..0b6dc778e4 100644 --- a/FAQ.md +++ b/FAQ.md @@ -10,8 +10,8 @@ Summarize the question and quote the reply, linking back to the original comment * [Should I commit my vendor directory?](#should-i-commit-my-vendor-directory) * [Why is it `dep ensure` instead of `dep install`?](#why-is-it-dep-ensure-instead-of-dep-install) * [Does `dep` replace `go get`?](#does-dep-replace-go-get) -* [Why did `dep ensure -update` not update package X?](#why-did-dep-ensure--update-not-update-package-x) * [Why is `dep` ignoring the version specified in the manifest?](#why-is-dep-ignoring-the-version-specified-in-the-manifest) +* [Why did `dep ensure -update` not update package X?](#why-did-dep-ensure--update-not-update-package-x) * [`dep` deleted my files in the vendor directory!](#dep-deleted-my-files-in-the-vendor-directory) * [Can I put the manifest and lock in the vendor directory?](#can-i-put-the-manifest-and-lock-in-the-vendor-directory) * [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) @@ -55,41 +55,41 @@ Here are some suggestions for when you could use `dep` or `go get`: > is for people consuming Go code, and dep-family commands are for people developing it. -[@sdboyer in #376](https://github.com/golang/dep/issues/376#issuecomment-294045873) -## Why did `dep ensure -update` not update package X? -Is package X a direct dependency? [#385](https://github.com/golang/dep/issues/385) - -Constraints given in a project's manifest are only applied if the -dependent project is actually imported. Transitive dependencies (dependencies -of your imports) are only updated when the revision in the lockfile no -longer meets the constraints of your direct dependencies. - -> If you absolutely need to specify the constraint of a transitive dep from your own project, you have two options: -> -> Specify the constraint on github.com/gorilla/context via an override. Overrides apply globally, but are a power only given to the root project, so if anything else imports your project, the override won't be used. -> Mark github.com/gorilla/context as a required package in the manifest. This will cause it to be treated as a direct dependency, and your constraint will come into effect. -> -> However, before taking either of those steps, I'd say it's worth asking if you actually need to use master of github.com/gorilla/context. I imagine it's imported by github.com/gorilla/mux - and if that package is OK with using the tagged release instead of master (which is the preferred mode of operation anyway), then maybe that should be good enough for you? If you really needed something out of github.com/gorilla/context, then you'd probably be importing it directly and doing something with it --[@sdboyer in #385](https://github.com/golang/dep/issues/385#issuecomment-294361087) - ## Why is `dep` ignoring the version specified in the manifest? Only direct dependencies can be managed with a `dependencies` entry in the manifest. Use an `overrides` entry for transitive dependencies. -> Constraints: +> Dependencies: > > 1. Can be declared by any project's manifest, yours or a dependency > 2. Apply only to direct dependencies of the project declaring the constraint -> 3. Must not conflict with the constraints declared in any other project's manifest +> 3. Must not conflict with the `dependencies` declared in any other project's manifest > > Overrides: > > 1. Are only utilized from the current/your project's manifest > 2. Apply globally, to direct and transitive dependencies -> 3. Supercede constraints declared in all manifests, yours or a dependency's +> 3. Supersede constraints declared in all manifests, yours or a dependency's > > Overrides are also discussed with some visuals in [the gps docs](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#overrides). -[@sdboyer in #328](https://github.com/golang/dep/issues/328#issuecomment-286631961) + +## Why did `dep ensure -update` not update package X? +This is a symptom of the same problem in [Why is `dep` ignoring the version specified in the manifest?](#why-is-dep-ignoring-the-version-specified-in-the-manifest) and can occur after you had previously added a `dependencies` entry to your manifest for a [transitive dependency](#what-is-a-direct-or-transitive-dependency) and run `dep ensure`. Later when you attempt to update, project X is not updated as expected. + +If you accidentally use a `dependencies` entry for a transitive dependency, **it is silently ignored**. We have [#302](https://github.com/golang/dep/issues/302) open to detect and print a warning when this occurs. + +Only direct dependencies can be constrained with a `dependencies` entry, anything else should use a `required` or `overrides` entry. + +> If you absolutely need to specify the constraint of a transitive dep from your own project, you have two options: +> +> 1. Specify the constraint on `github.com/gorilla/context` via an override. Overrides apply globally, but are a power only given to the root project, so if anything else imports your project, the override won't be used. +> 2. Mark `github.com/gorilla/context` as a required package in the manifest. This will cause it to be treated as a direct dependency, and your constraint will come into effect. +> +> However, before taking either of those steps, I'd say it's worth asking if you actually need to use `master` of `github.com/gorilla/context`. I imagine it's imported by `github.com/gorilla/mux` - and if that package is OK with using the tagged release instead of `master` (which is the preferred mode of operation anyway), then maybe that should be good enough for you? If you really needed something out of `github.com/gorilla/context`, then you'd probably be importing it directly and doing something with it +-[@sdboyer in #385](https://github.com/golang/dep/issues/385#issuecomment-294361087) + ## `dep` deleted my files in the vendor directory! First, sorry! 😞 We hope you were able to recover your files...