cmd/go: add more go tool documentation and show tool aliases in go tool

This change adds pointers in the documentation for go tool to point to
go get -tool, and vice versa, and documents the rules for when aliases
can be used for tools and what those aliases are.

It also modifies go tool with no arguments so that it prints the alias
for any tools for which aliases can be provided, such as:
    $ go tool
    asm
    cgo
    [...]
    bar (foo.com/full/package/path/bar)

For #71663

Change-Id: Id008cffbb02863692a18d4e1c1458b5b6a6a6964
Reviewed-on: https://go-review.googlesource.com/c/go/+/761100
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Auto-Submit: Michael Matloob <matloob@golang.org>
Reviewed-by: Michael Matloob <matloob@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

4 files changed, 57 insertions, 2 deletions

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 85a82bc57d..1b74292327 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -748,6 +748,7 @@
 //
 // The -tool flag instructs go to add a matching tool line to go.mod for each
 // listed package. If -tool is used with @none, the line will be removed.
+// See 'go help tool' for more information.
 //
 // The -x flag prints commands as they are executed. This is useful for
 // debugging version control commands when a module is downloaded directly
@@ -1992,7 +1993,14 @@
 // Tool runs the go tool command identified by the arguments.
 //
 // Go ships with a number of builtin tools, and additional tools
-// may be defined in the go.mod of the current module.
+// may be defined in the go.mod of the current module. 'go get -tool'
+// can be used to define additional tools in the current module's
+// go.mod file. See 'go help get' for more information.
+//
+// The command can be specified using the full package path to the tool declared with
+// a tool directive. The default binary name of the tool, which is the last component of
+// the package path, excluding the major version suffix, can also be used if it is unique
+// among declared tools.
 //
 // With no arguments it prints the list of known tools.
 //
diff --git a/src/cmd/go/internal/modget/get.go b/src/cmd/go/internal/modget/get.go
index f29365b5b6..165d88a6b5 100644
--- a/src/cmd/go/internal/modget/get.go
+++ b/src/cmd/go/internal/modget/get.go
@@ -111,6 +111,7 @@ test dependencies as well.
 
 The -tool flag instructs go to add a matching tool line to go.mod for each
 listed package. If -tool is used with @none, the line will be removed.
+See 'go help tool' for more information.
 
 The -x flag prints commands as they are executed. This is useful for
 debugging version control commands when a module is downloaded directly
diff --git a/src/cmd/go/internal/tool/tool.go b/src/cmd/go/internal/tool/tool.go
index 57bcde6da4..b62e626a69 100644
--- a/src/cmd/go/internal/tool/tool.go
+++ b/src/cmd/go/internal/tool/tool.go
@@ -40,7 +40,14 @@ var CmdTool = &base.Command{
 Tool runs the go tool command identified by the arguments.
 
 Go ships with a number of builtin tools, and additional tools
-may be defined in the go.mod of the current module.
+may be defined in the go.mod of the current module. 'go get -tool'
+can be used to define additional tools in the current module's
+go.mod file. See 'go help get' for more information.
+
+The command can be specified using the full package path to the tool declared with
+a tool directive. The default binary name of the tool, which is the last component of
+the package path, excluding the major version suffix, can also be used if it is unique
+among declared tools.
 
 With no arguments it prints the list of known tools.
 
@@ -152,8 +159,11 @@ func listTools(loaderstate *modload.State, ctx context.Context) {
 		return
 	}
 
+	ambiguous := make(map[string]bool) // names that can't be used as aliases because they are ambiguous
 	sort.Strings(names)
 	for _, name := range names {
+		ambiguous[name] = true
+
 		// Unify presentation by going to lower case.
 		// If it's windows, don't show the .exe suffix.
 		name = strings.TrimSuffix(strings.ToLower(name), cfg.ToolExeSuffix())
@@ -169,7 +179,23 @@ func listTools(loaderstate *modload.State, ctx context.Context) {
 	loaderstate.InitWorkfile()
 	modload.LoadModFile(loaderstate, ctx)
 	modTools := slices.Sorted(maps.Keys(loaderstate.MainModules.Tools()))
+	seen := make(map[string]bool) // aliases we've seen already
+	for _, tool := range modTools {
+		alias := defaultExecName(tool)
+		switch {
+		case ambiguous[alias]:
+			continue
+		case seen[alias]:
+			ambiguous[alias] = true
+		default:
+			seen[alias] = true
+		}
+	}
 	for _, tool := range modTools {
+		if alias := defaultExecName(tool); !ambiguous[alias] {
+			fmt.Printf("%s (%s)\n", alias, tool)
+			continue
+		}
 		fmt.Println(tool)
 	}
 }
diff --git a/src/cmd/go/testdata/script/tool_exename.txt b/src/cmd/go/testdata/script/tool_exename.txt
index a8dba8409f..584ee70413 100644
--- a/src/cmd/go/testdata/script/tool_exename.txt
+++ b/src/cmd/go/testdata/script/tool_exename.txt
@@ -38,6 +38,16 @@ env GOCACHE=$WORK/cache2
 go run example.com/foo/v2
 stdout 'my name is: foo'$GOEXE
 
+# list aliases for tools
+go tool
+stdout '^bar \(example.com/foo/bar\)$'
+! stdout '^example.com/foo/bar$'
+stdout '^foo \(example.com/foo/v2\)$'
+! stdout '^example.com/foo/v2$'
+stdout '^example.com/foo/noalias$'
+! stdout '^noalias \(example.com/foo/noalias\)$'
+stdout '^example.com/foo/noalias/noalias$'
+! stdout '^noalias \(example.com/foo/noalias\)$'
 -- go.mod --
 module example.com/foo
 
@@ -45,6 +55,8 @@ go 1.24
 
 tool example.com/foo/bar
 tool example.com/foo/v2
+tool example.com/foo/noalias
+tool example.com/foo/noalias/noalias
 
 require example.com/foo/v2 v2.0.0
 
@@ -77,3 +89,11 @@ import (
 func main() {
 	fmt.Println("my name is:", filepath.Base(os.Args[0]))
 }
+
+-- noalias/noalias.go --
+package main
+
+func main() {}
+-- noalias/noalias/noalias.go --
+pagckage main
+func main() {}
\ No newline at end of file