cmd/go: some documentation issues for new 1.24 'go tool' features

[thepudds]

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 (cmd/go: missing flags in help output for tool #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.

[ianlancetaylor]

CC @matloob @samthanawalla

[gabyhelp]

Related Issues

• cmd/go: `go get tool` upgrades tools instead of just downloading them #71289 (closed)
• cmd/go: document using -modfile to record tool versions without interfering with main module dependencies #33926 (closed)
• cmd/go: go mod does not provide access to all operations on modules #33561 (closed)
• cmd/go: flags to control changes to go.mod, go.sum #34506 (closed)
• cmd/go: mention `go get` in `go help mod` #44726 (closed)
• cmd/go: track tool dependencies in go.mod #48429 (closed)
• cmd/go: tools.go/+build tools dependencies in go.mod not updated with any go get -u variant #32345 (closed)

Related Code Changes

• cmd/go: clarify documentation for 'go get -u'
• cmd/go: add go get -g flag to install tools in global mode
• cmd/go: add -modfile and -modcacherw to go tool

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

[gopherbot]

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

[gopherbot]

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

[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

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

[dolmen]

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