1. "Managing module dependencies": a. The text seems to imply -u is needed to upgrade tools, but the -u is not actually needed and often is undesirable. (This was also a problem in the release notes as well; I previously sent https://go.dev/cl/638296 to address in the release notes).

  2. Modules reference: a. go get section is missing -tool flag. b. go install section doesn't mention go install tool. (It also somewhat implies it wouldn't work because it says 'go install' can't take meta-pattern, which we should also probably tweak). c. Most new-ish capabilities have a "Since Go 1.x" or a similar phrase, but the tools description does not (e.g., in https://go.dev/ref/mod#go-mod-file-tool). d. No 'go tool' section. (Maybe this is OK for now given the documentation elsewhere, but could include a short section with a link for details).

  3. cmd/go documentation go tool section: a. Does not mention needing to use full package path for go tool in some cases. b. No mention of go tool without args to list available tools. c. No -modfile mentioned (https://github.com/golang/go/issues/71502). d. These overlap with the help text shown at the command line in cmd/go.

  4. 1.24 release notes: a. Ideally the release notes would mention the -modfile flag. (For example, see #71502, #48429 (comment), or various other recent & older comments on #48429, #33926 and elsewhere).

Opening this issue for discussion. I plan to send some CLs. It seems Go 1.24 official release is very close, so maybe some or all of these are adjustments for later.

For these new capabilities, I think the "Managing Dependencies" doc is currently the most comprehensive and also the easiest to digest, so probably reasonable to link to there from some of the other doc.

There are some other more minor issues, but I wanted to at least try to address some of these. Finally, one additional caveat is this writeup is based on some older notes I had taken, and I need to double-check some of it again.

Comment From: ianlancetaylor

CC @matloob @samthanawalla

Comment From: gabyhelp

Related Issues

Related Code Changes

(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)

Comment From: gopherbot

Change https://go.dev/cl/648577 mentions this issue: cmd/go: document -modfile and other flags for 'go tool'

Comment From: gopherbot

Change https://go.dev/cl/648578 mentions this issue: _content/doc/modules/managing-dependencies: remove unneeded '-u' flag and mention '-modfile'

Comment From: samthanawalla

We also need to add some documentation to the website for other Go Command features.

  • GOAUTH variable to https://go.dev/ref/mod#module-proxy
  • GODEBUG=toolchaintrace to https://go.dev/doc/godebug
  • https://go.dev/ref/mod#go-version-m the main module will no longer have (devel) in the presence of local VCS info

Comment From: hu3bi

Somehow related:

The vscode go extension might also need to be upgraded to accommodate for tools.

After clicking upgrade direct dependencies vscode pulls in a bunch of not needed dependencies, which are removed once you run go mod tidy. This might be confusing, especially for new go developers. Image

Comment From: dolmen

@hu3bi Report here: https://github.com/golang/vscode-go

Comment From: hu3bi

@dolmen Thank you and sorry. Should have known better. https://github.com/golang/vscode-go/issues/3706