UX feedback around ensure

[zmb3]

Greetings,

I'm just starting to give dep a whirl and have run into some behavior I can't explain.
I may be doing something wrong, or I may just not understand the tool, but I thought I'd share my initial experience. For reference, I have mostly used glide for dependency management up until now.

I started a project, ran dep init, and then added a single dependency with dep ensure. All worked as expected.

A few days later I came back and tried to add another dependency.

$ dep ensure github.com/someuser/somelib

The command completed without any output, and without modifying the lock file or adding anything to the vendor directory.

I tried again, running the same command with the -v flag to see if I could get some more information. I see some output about the original dependency, but nothing on the new dependency I'm trying to add. I ran the tool once more with the -n flag, and the lock file that it says it would generate is identical to the current one (again nothing on the new dependency).

My assumption is that dep ensure is supposed to go out and fetch a dependency for me, then update my lock file. Is this not the case?

I suspected maybe for some reason dep only looks at code that's already in $GOPATH, so I run go get github.com/someuser/someliband then try another dep ensure.

In this exercise, the library I'm attempting to pull in is github.com/mitchellh/pointerstructure.
Now that the library is in my $GOPATH I see some different behavior when running dep ensure:

(2)	? attempt github.com/mitchellh/pointerstructure with 1 pkgs; 1 versions to try
(2)	    try github.com/mitchellh/pointerstructure@master
(3)	✗   github.com/mitchellh/pointerstructure@master not allowed by constraint *:
(3)	    * from (root)

I don't fully understand dep's constraints yet, but my Gopkg.toml consists only of the commented out lines that were produced by dep init. I have not intentionally set any constraints, so I'm confused as to why I can't pull in the latest commit of some package like I could do with glide add.

[ibrasho]

Hi @zmb3 .

Thanks for sharing your feedback.

A few days later I came back and tried to add another dependency.
$ dep ensure github.com/someuser/somelib

dep ensure doesn't add dependencies. It merely ensures that the project state is consistent. You can either import the dependency in a *.go file or add it to the required field in Gopkg.toml. Refer to Why is it dep ensure instead of dep install?

Refer to When should I use constraint, override, required, or ignored in Gopkg.toml? to understand the effect of different fields in Gopkg.toml.

If you have time please read all the FAQs as they will answer a lot of questions you might have. And please let us know if you any additional feedback.

[zmb3]

Thanks for the claification @ibrasho.

I actually did see that particular question in the FAQ, but it came off to me as explaining why you settled on a particular naming convention as opposed to explaining why the tool doesn't add dependencies.

dep ensure doesn't add dependencies. It merely ensures that the project state is consistent.

I think what was confusing to me is that the help message states otherwise:

$ dep -h
dep is a tool for managing dependencies for Go projects

Usage: dep <command>

Commands:

  init    Initialize a new project with manifest and lock files
  status  Report the status of the project's dependencies
  ensure  Ensure a dependency is safely vendored in the project
  prune   Prune the vendor tree of unused packages

Examples:
  dep init                          set up a new project
  dep ensure                        install the project's dependencies
  dep ensure -update                update the locked versions of all dependencies
  dep ensure github.com/pkg/errors  add a dependency to the project

Perhaps the last section of the help message could be improved.

dep ensure github.com/pkg/errors add a dependency to the project

One additional piece of feedback - this workflow doesn't seem to play nice with goimports. If I know of a library I want to use but I don't currently have it in my GOPATH, I have to add an import to a *.go file and then run dep ensure. But if goimports is configured to run on save and I haven't actually used the dependency yet, the import will be removed and dep ensure won't see it.
I'll either have to context switch from adding my dependency to fiddling with editor settings to temporarily disable goimports, run go get first so I have a copy in my global GOPATH, or try to add a usage of the dependency before saving the file (without the help of things like autocomplete or go to definition, since I haven't yet acquired the source code of the dependency). Have other users run into this? Is there a better workflow for this use case?

[sdboyer]

hi @zmb3, thanks for the issue. as @ibrasho noted, we don't currently support this - however, for many of the reasons you cite here (and as previously raised in e.g. #303), we are planning to add some behaviors that'll be more along these lines. #489 will be the first draft at those, hopefully to be merged this week.

The CLI docs you note are definitely out of sync with the behavior of the tool. Unfortunately, they were written prior to deciding to move to the new model (#277) that #489 begins to implements. As happens, it's taken much longer than expected for us to catch up with the planned change...and we let the docs languish in the meantime.

[zmb3]

Thanks for the history Sam. I appreciate the work you all are doing. It's clear from reading these issues that this is a much harder problem to solve than it would appear on the surface.