diff options
author | Jay Conrod <jayconrod@google.com> | 2020-01-10 15:52:05 -0500 |
---|---|---|
committer | Jay Conrod <jayconrod@google.com> | 2020-02-07 18:06:58 +0000 |
commit | ff091b5fa0c08a1f91aa6bd6e2bc080a3eba2720 (patch) | |
tree | 4c9dbaa88bb444879b460991f83d9755906c082f | |
parent | c7c525a79d224382ff59e238dbf1d129f26e9e2f (diff) | |
download | go-ff091b5fa0c08a1f91aa6bd6e2bc080a3eba2720.tar.gz go-ff091b5fa0c08a1f91aa6bd6e2bc080a3eba2720.zip |
doc: fill in 'Module-aware commands' section in module documentation
Updates #33637
Change-Id: I6332fcdbd4c35a11cd84504f28ee594f1831ccaa
Reviewed-on: https://go-review.googlesource.com/c/go/+/214378
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Tyler Bui-Palsulich <tbp@google.com>
-rw-r--r-- | doc/modules.md | 59 |
1 files changed, 49 insertions, 10 deletions
diff --git a/doc/modules.md b/doc/modules.md index 9a0dfc7c1b..52ceb87ca8 100644 --- a/doc/modules.md +++ b/doc/modules.md @@ -619,13 +619,33 @@ updating requirements in `go.mod`. ## Compatibility with non-module repositories <a id="mod-commands"></a> -## Module-aware build commands - -<a id="enabling"></a> -### Enabling modules - -<a id="initializing"></a> -### Initializing modules +## Module-aware commands + +Most `go` commands may run in *Module-aware mode* or *`GOPATH` mode*. In +module-aware mode, the `go` command uses `go.mod` files to find versioned +dependencies, and it typically loads packages out of the [module +cache](#glos-module-cache), downloading modules if they are missing. In `GOPATH` +mode, the `go` command ignores modules; it looks in `vendor` directories and in +`GOPATH` to find dependencies. + +Module-aware mode is active by default whenever a `go.mod` file is found in the +current directory or in any parent directory. For more fine-grained control, the +`GO111MODULE` environment variable may be set to one of three values: `on`, +`off`, or `auto`. + +* If `GO111MODULE=off`, the `go` command ignores `go.mod` files and runs in + `GOPATH` mode. +* If `GO111MODULE=on`, the `go` command runs in module-aware mode, even when + no `go.mod` file is present. Not all commands work without a `go.mod` file: + see [Module commands outside a module](#commands-outside). +* If `GO111MODULE=auto` or is unset, the `go` command runs in module-aware + mode if a `go.mod` file is present in the current directory or any parent + directory (the default behavior). + +In module-aware mode, `GOPATH` no longer defines the meaning of imports during a +build, but it still stores downloaded dependencies (in `GOPATH/pkg/mod`; see +[Module cache](#module-cache)) and installed commands (in `GOPATH/bin`, unless +`GOBIN` is set). <a id="build-commands"></a> ### Build commands @@ -636,18 +656,30 @@ updating requirements in `go.mod`. <a id="go-get"></a> ### `go get` +<a id="go-list-m"></a> +### `go list -m` + <a id="go-mod-download"></a> ### `go mod download` -<a id="go-mod-verify"></a> -### `go mod verify` - <a id="go-mod-edit"></a> ### `go mod edit` +<a id="go-mod-init"></a> +### `go mod init` + +<a id="go-mod-tidy"></a> +### `go mod tidy` + +<a id="go-mod-verify"></a> +### `go mod verify` + <a id="go-clean-modcache"></a> ### `go clean -modcache` +<a id="module-queries"></a> +### Module queries + <a id="commands-outside"></a> ### Module commands outside a module @@ -828,6 +860,9 @@ setting `GOPROXY` to `https://example.com/proxy`. <a id="private-modules"></a> ### Private modules +<a id="module-cache"></a> +### Module cache + <a id="authenticating"></a> ## Authenticating modules @@ -1057,6 +1092,10 @@ be incremented, and the patch version must be set to 0. **module:** A collection of packages that are released, versioned, and distributed together. +<a id="glos-module-cache"></a> +**module cache:** A local directory storing downloaded modules, located in +`GOPATH/pkg/mod`. See [Module cache](#module-cache). + <a id="glos-module-graph"></a> **module graph:** The directed graph of module requirements, rooted at the [main module](#glos-main-module). Each vertex in the graph is a module; each edge is a |