_content/doc: document module tools

For golang/go#48429

Change-Id: I81344da002afe92c8ec60ad5acef0b11e487934e
Reviewed-on: https://go-review.googlesource.com/c/website/+/632595
Reviewed-by: Sam Thanawalla <[email protected]>
Reviewed-by: Michael Matloob <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: ConradIrwin

_content/doc/modules/gomod-ref.md

@@ -345,6 +345,53 @@ For more about managing dependencies, see the following:
 * [Upgrading or downgrading a dependency](/doc/modules/managing-dependencies#upgrading)
 * [Synchronizing your code's dependencies](/doc/modules/managing-dependencies#synchronizing)
 
+## tool {#tool}
+
+Adds a package as a dependency of the current module, and makes it available to run with `go tool` when the current working directory is within this module.
+
+### Syntax {#tool-syntax}
+
+<pre>tool <var>package-path</var></pre>
+
+<dl>
+    <dt>package-path</dt>
+    <dd>The tool's package path, a concatenation of the module containing
+        the tool and the (possibly empty) path to the package implementing
+        the tool within the module.</dd>
+</dl>
+
+### Examples {#tool-examples}
+
+* Declaring a tool implemented in the current module:
+    ```
+    module example.com/mymodule
+
+    tool example.com/mymodule/cmd/mytool
+    ```
+* Declaring a tool implemented in a separate module:
+    ```
+    module example.com/mymodule
+
+    tool example.com/atool/cmd/atool
+
+    require example.com/atool v1.2.3
+    ```
+
+### Notes {#tool-notes}
+
+You can use `go tool` to run tools declared in your module by fully qualified package path
+or, if there is no ambiguity, by the last path segment. In the first example
+above you could run `go tool mytool` or `go tool example.com/mymodule/cmd/mytool`.
+
+In workspace mode, you can use `go tool` to run a tool declared in any workspace module.
+
+Tools are built using the same module graph as the module itself. A [`require`
+directive](#require) is needed to select the version of the module that
+implements the tool. Any [`replace` directives](#replace), or [`exclude`
+directives](#exclude) also apply to the tool and its dependencies.
+
+For more information see [Tool dependencies](/doc/modules/managing-dependencies#tools).
+
 ## replace {#replace}
 
 Replaces the content of a module at a specific version (or all versions) with

_content/doc/modules/managing-dependencies.md

@@ -477,6 +477,66 @@ $ go get example.com/theirmodule@none
 The `go get` command will also downgrade or remove other dependencies that
 depend on the removed module.
 
+## Tool dependencies {#tools}
+
+Tool dependencies let you manage developer tools that are written in Go and used
+when working on your module. For example, you might use
+[`stringer`](https://pkg.go.dev/golang.org/x/tools/cmd/stringer) with [`go
+generate`](/blog/generate), or a specific linter or formatter as part of
+preparing your change for submission.
+
+In Go 1.24 and above, you can add a tool dependency with:
+
+```
+$ go get -tool golang.org/x/tools/cmd/stringer
+```
+
+This will add a [`tool` directive](/ref/mod/#go-mod-file-tool) to your `go.mod` file, and ensure the
+necessary require directives are present. Once this directive is added you can
+run the tool by passing the last fragment of the package path to `go tool`:
+
+```
+$ go tool stringer
+```
+
+In the case that multiple tools share the last path fragment, or the path fragment
+matches one of the tools shipped with the Go distribution, you must pass the full
+package path instead:
+
+```
+$ go tool golang.org/x/tools/cmd/stringer
+```
+
+To see a list of all tools currently available, run `go tool` with no arguments:
+
+```
+$ go tool
+```
+
+You can manually add a `tool` directive to your `go.mod`, but you must ensure
+that there is a `require` directive for the module that defines the tool. The
+easiest way to add any missing `require` directives is to run:
+
+```
+$ go mod tidy
+```
+
+Requirements needed to satisfy tool dependencies behave like any other
+requirements in your [module graph](/ref/mod#glos-module-graph). They
+participate in [minimal version selection](/ref/mod#minimal-version-selection)
+and respect `require`, `replace` and `exclude` directives. Due to module
+pruning, when you depend on a module that itself has a tool dependency,
+requirements that exist to just to satisfy that tool dependency do not usually
+become requirements of your module.
+
+The `tool` [meta-pattern](/cmd/go#hdr-Package_lists_and_patterns) provides a way to perform operations on all tools simultaneously. For example you can upgrade all tools with `go get -u tool`, or install them all to $GOBIN with `go install tool`.
+
+In Go versions before 1.24, you can acheive something similar to a `tool`
+directive by adding a blank import to a go file within the module that is
+excluded from the build using [build
+constraints](/pkg/go/build/#hdr-Build_Constraints). If you do this, you can then
+use `go run` with the full package path to run the tool.
+
 ## Specifying a module proxy server {#proxy_server}
 
 When you use Go tools to work with modules, the tools by default download

_content/ref/mod.md

@@ -471,6 +471,7 @@ for details on EBNF syntax.
 GoMod = { Directive } .
 Directive = ModuleDirective |
             GoDirective |
+            ToolDirective |
             RequireDirective |
             ExcludeDirective |
             ReplaceDirective |
@@ -715,6 +716,35 @@ require (
 )
 ```
 
+### `tool` directive {#go-mod-file-tool}
+
+A `tool` directive adds a package as a dependency of the current module. It also
+makes it available to run with `go tool` when the current working directory is
+within this module, or within a workspace that contains this module.
+
+If the tool package is not in the current module, a `require`
+directive must be present that specifies the version of the tool to use.
+
+The `tool` meta-pattern resolves to the list of tools defined in the current module's
+`go.mod`, or in workspace mode to the union of all tools defined in all modules in the
+workspace.
+
+```
+ToolDirective = "tool" ( ToolSpec | "(" newline { ToolSpec } ")" newline ) .
+ToolSpec = ModulePath newline .
+```
+
+Example:
+
+```
+tool golang.org/x/tools/cmd/stringer
+
+tool (
+    example.com/module/cmd/a
+    example.com/module/cmd/b
+)
+```
+
 ### `exclude` directive {#go-mod-file-exclude}
 
 An `exclude` directive prevents a module version from being loaded by the `go`
@@ -2079,6 +2109,10 @@ The editing flags specify a sequence of editing operations.
   flag cannot add a rationale comment for the `retract` directive. Rationale
   comments are recommended and may be shown by `go list -m -u` and other
   commands.
+* The `-tool=path` and `-droptool=path` flags add and drop a `tool` directive
+  for the given paths. Note that this will not add necessary dependencies to
+  the build graph. Users should prefer `go get -tool path` to add a tool, or
+  `go get -tool path@none` to remove one.
 
 The editing flags may be repeated. The changes are applied in the order given.
 
@@ -2129,6 +2163,10 @@ type Retract struct {
     High      string
     Rationale string
 }
+
+type Tool struct {
+    Path      string
+}
 ```
 
 Note that this only describes the `go.mod` file itself, not other modules
@@ -2250,7 +2288,7 @@ The `-v` flag causes `go mod tidy` to print information about removed modules
 to standard error.
 
 `go mod tidy` works by loading all of the packages in the [main
-module](#glos-main-module) and all of the packages they import,
+module](#glos-main-module), all of its tools, and all of the packages they import,
 recursively. This includes packages imported by tests (including tests in other
 modules). `go mod tidy` acts as if all build tags are enabled, so it will
 consider platform-specific source files and files that require custom build