diff --git a/content/static/doc/mod.md b/content/static/doc/mod.md
index 3e35e3c..6e492dc 100644
--- a/content/static/doc/mod.md
+++ b/content/static/doc/mod.md
@@ -3,16 +3,12 @@
   "Subtitle": "Version of Feb 5, 2019",
   "Path": "/ref/mod"
 }-->
-<!-- TODO(jayconrod): change anchors to header id attributes either during
-markdown rendering or as HTML postprocessing step. -->
 <!-- TODO(jayconrod): use <dfn> tags where meaningful.
 Currently, *term* is used instead, which renders to <em>term</em>. -->
 
-<a id="introduction"></a>
-## Introduction
+## Introduction {#introduction}
 
-<a id="modules-overview"></a>
-## Modules, packages, and versions
+## Modules, packages, and versions {#modules-overview}
 
 A [*module*](#glos-module) is a collection of packages that are released,
 versioned, and distributed together. A module is identified by a [*module
@@ -30,8 +26,7 @@
 `"golang.org/x/net"` contains a package in the directory `"html"`. That
 package's path is `"golang.org/x/net/html"`.
 
-<a id="module-path"></a>
-### Module paths
+### Module paths {#module-path}
 
 A [*module path*](#glos-module-path) is the canonical name for a module,
 declared with the [`module` directive](#go.mod-module) in the module's
@@ -70,8 +65,7 @@
 several [lexical restrictions](#go.mod-ident) on characters allowed in
 module paths.
 
-<a id="versions"></a>
-### Versions
+### Versions {#versions}
 
 A [*version*](#glos-version) identifies an immutable snapshot of a module, which
 may be either a [release](#glos-release-version) or a
@@ -129,8 +123,7 @@
 required outside the main module, and the `go` command will report an error if a
 non-canonical version like `master` appears in a `go.mod` file.
 
-<a id="pseudo-versions"></a>
-### Pseudo-versions
+### Pseudo-versions {#pseudo-versions}
 
 A <dfn>pseudo-version</dfn> is a specially formatted
 [pre-release](#glos-pre-release-version) [version](#glos-version) that encodes
@@ -202,8 +195,7 @@
 go list -m -json example.com/mod@abcd1234
 ```
 
-<a id="major-version-suffixes"></a>
-### Major version suffixes
+### Major version suffixes {#major-version-suffixes}
 
 Starting with major version 2, module paths must have a [*major version
 suffix*](#glos-major-version-suffix) like `/v2` that matches the major
@@ -252,8 +244,7 @@
 example, `v2.0.0+incompatible`). See [Compatibility with non-module
 repositories](#non-module-compat) for more information.
 
-<a id="resolve-pkg-mod"></a>
-### Resolving a package to a module
+### Resolving a package to a module {#resolve-pkg-mod}
 
 When the `go` command loads a package using a [package
 path](#glos-package-path), it needs to determine which module provides the
@@ -320,8 +311,7 @@
 package is not imported by a package in the main module, the new requirement
 will have an `// indirect` comment.
 
-<a id="go.mod-files"></a>
-## `go.mod` files
+## `go.mod` files {#go.mod-files}
 
 A module is defined by a UTF-8 encoded text file named `go.mod` in its root
 directory. The `go.mod` file is line-oriented. Each line holds a single
@@ -357,8 +347,7 @@
 [`golang.org/x/mod/modfile`](https://pkg.go.dev/golang.org/x/mod/modfile?tab=doc)
 package can be used by Go programs to make the same changes programmatically.
 
-<a id="go.mod-lexical"></a>
-### Lexical elements
+### Lexical elements {#go.mod-lexical}
 
 When a `go.mod` file is parsed, its content is broken into a sequence of tokens.
 There are several kinds of tokens: whitespace, comments, punctuation,
@@ -395,8 +384,7 @@
 
 Identifiers and strings are interchangeable in the `go.mod` grammar.
 
-<a id="go.mod-ident"></a>
-### Module paths and versions
+### Module paths and versions {#go.mod-ident}
 
 Most identifiers and strings in a `go.mod` file are either module paths or
 versions.
@@ -445,8 +433,7 @@
 `replace`, and `exclude` directives), the final path element must be consistent
 with the version. See [Major version suffixes](#major-version-suffixes).
 
-<a id="go.mod-grammar"></a>
-### Grammar
+### Grammar {#go.mod-grammar}
 
 `go.mod` syntax is specified below using Extended Backus-Naur Form (EBNF).
 See the [Notation section in the Go Language Specificiation](/ref/spec#Notation)
@@ -471,8 +458,7 @@
 Version = ident | string .    /* see restrictions above */
 ```
 
-<a id="go.mod-module"></a>
-### `module` directive
+### `module` directive {#go.mod-module}
 
 A `module` directive defines the main module's [path](#glos-module-path). A
 `go.mod` file must contain exactly one `module` directive.
@@ -487,8 +473,7 @@
 module golang.org/x/net
 ```
 
-<a id="go.mod-go"></a>
-### `go` directive
+### `go` directive {#go.mod-go}
 
 A `go` directive sets the expected language version for the module. The
 version must be a valid Go release version: a positive integer followed by a dot
@@ -518,8 +503,7 @@
 go 1.14
 ```
 
-<a id="go.mod-require"></a>
-### `require` directive
+### `require` directive {#go.mod-require}
 
 A `require` directive declares a minimum required version of a given module
 dependency. For each required module version, the `go` command loads the
@@ -555,8 +539,7 @@
 )
 ```
 
-<a id="go.mod-exclude"></a>
-### `exclude` directive
+### `exclude` directive {#go.mod-exclude}
 
 An `exclude` directive prevents a module version from being loaded by the `go`
 command. If an excluded version is referenced by a `require` directive in a
@@ -589,8 +572,7 @@
 )
 ```
 
-<a id="go.mod-replace"></a>
-### `replace` directive
+### `replace` directive {#go.mod-replace}
 
 A `replace` directive replaces the contents of a specific version of a module,
 or all versions of a module, with contents found elsewhere. The replacement
@@ -638,8 +620,7 @@
 )
 ```
 
-<a id="go.mod-updates"></a>
-### Automatic updates
+### Automatic updates {#go.mod-updates}
 
 The `go` command automatically updates `go.mod` when it uses the module graph if
 some information is missing or `go.mod` doesn't accurately reflect reality.  For
@@ -693,8 +674,7 @@
 list, `go build` will report an error instead of looking up the module and
 updating requirements in `go.mod`.
 
-<a id="minimal-version-selection"></a>
-## Minimal version selection (MVS)
+## Minimal version selection (MVS) {#minimal-version-selection}
 
 Go uses an algorithm called <dfn>Minimal version selection (MVS)</dfn> to select
 a set of module versions to use when building packages. MVS is described in
@@ -734,8 +714,7 @@
 versions of B and D are available but MVS does not select them, since nothing
 requires them.
 
-<a id="mvs-replace"></a>
-### Replacement
+### Replacement {#mvs-replace}
 
 The content of a module (including its `go.mod` file) may be replaced using a
 [`replace` directive](#go.mod-replace) in the the main module's `go.mod` file.
@@ -751,8 +730,7 @@
 
 ![Module version graph with a replacement](/doc/mvs/replace.svg "MVS replacment")
 
-<a id="mvs-exclude"></a>
-### Exclusion
+### Exclusion {#mvs-exclude}
 
 A module may also be excluded at specific versions using an [`exclude`
 directive](#go.mod-exclude) in the main module's `go.mod` file.
@@ -766,8 +744,7 @@
 
 ![Module version graph with an exclusion](/doc/mvs/exclude.svg "MVS exclude")
 
-<a id="mvs-upgrade"></a>
-### Upgrades
+### Upgrades {#mvs-upgrade}
 
 The [`go get`](#go-get) command may be used to upgrade a set of modules. To
 perform an upgrade, the `go` command changes the module graph before running MVS
@@ -787,8 +764,7 @@
 on C 1.4 and D 1.3 with `// indirect` comments, since those versions would not
 be selected otherwise.
 
-<a id="mvs-downgrade"></a>
-### Downgrade
+### Downgrade {#mvs-downgrade}
 
 The [`go get`](#go-get) command may also be used to downgrade a set of
 modules. To perform a downgrade, the `go` command changes the module graph by
@@ -810,8 +786,7 @@
 suffix after an argument. This works similarly to a downgrade. All versions
 of the named module are removed from the module graph.
 
-<a id="non-module-compat"></a>
-## Compatibility with non-module repositories
+## Compatibility with non-module repositories {#non-module-compat}
 
 To ensure a smooth transition from `GOPATH` to modules, the `go` command can
 download and build packages in module-aware mode from repositories that have not
@@ -835,8 +810,7 @@
 from the rest of the module content. The proxy is expected to serve a synthetic
 `go.mod` file if the original module didn't have one.
 
-<a id="incompatible-versions"></a>
-### `+incompatible` versions
+### `+incompatible` versions {#incompatible-versions}
 
 A module released at major version 2 or higher must have a matching [major
 version suffix](#major-version-suffixes) on its module path. For example, if a
@@ -888,8 +862,7 @@
 <!-- TODO(jayconrod): Is it appropriate
 to link to the blog here? Ideally, we would have a more detailed guide. -->
 
-<a id="minimal-module-compatibility"></a>
-### Minimal module compatibility
+### Minimal module compatibility {#minimal-module-compatibility}
 
 A module released at major version 2 or higher is required to have a [major
 version suffix](#glos-major-version-suffix) on its [module
@@ -944,8 +917,7 @@
 packages that have been migrated to modules when built in `GOPATH` mode even
 when a major version subdirectory was not used.
 
-<a id="mod-commands"></a>
-## Module-aware commands
+## Module-aware commands {#mod-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
@@ -973,11 +945,9 @@
 [Module cache](#module-cache)) and installed commands (in `GOPATH/bin`, unless
 `GOBIN` is set).
 
-<a id="build-commands"></a>
-### Build commands
+### Build commands {#build-commands}
 
-<a id="vendoring"></a>
-### Vendoring
+### Vendoring {#vendoring}
 
 When using modules, the `go` command typically satisfies dependencies by
 downloading modules from their sources into the module cache, then loading
@@ -1021,8 +991,7 @@
 command ignores vendor directories in locations other than the main module's
 root directory.
 
-<a id="go-get"></a>
-### `go get`
+### `go get` {#go-get}
 
 Usage:
 
@@ -1140,8 +1109,7 @@
   variable](#environment-variables) provides more fine-grained control and
   should be used instead.
 
-<a id="go-list-m"></a>
-### `go list -m`
+### `go list -m` {#go-list-m}
 
 Usage:
 
@@ -1229,8 +1197,7 @@
 an error occurs, the result will be a `Module` struct with a non-nil `Error`
 field.
 
-<a id="go-mod-download"></a>
-### `go mod download`
+### `go mod download` {#go-mod-download}
 
 Usage:
 
@@ -1280,8 +1247,7 @@
 The `-x` flag causes `download` to print the commands `download` executes
 to standard error.
 
-<a id="go-mod-edit"></a>
-### `go mod edit`
+### `go mod edit` {#go-mod-edit}
 
 Usage:
 
@@ -1398,8 +1364,7 @@
 [`golang.org/x/mod/modfile`](https://pkg.go.dev/golang.org/x/mod/modfile?tab=doc)
 to parse, edit, and format `go.mod` files.
 
-<a id="go-mod-init"></a>
-### `go mod init`
+### `go mod init` {#go-mod-init}
 
 Usage:
 
@@ -1446,8 +1411,7 @@
 list](#glos-build-list), and [`go mod tidy`](#go-mod-tidy) to add missing
 requirements and to drop unused requirements.
 
-<a id="go-mod-tidy"></a>
-### `go mod tidy`
+### `go mod tidy` {#go-mod-tidy}
 
 Usage:
 
@@ -1492,8 +1456,7 @@
 required at a higher version than is implied by the module graph; this usually
 happens after running a command like `go get -u ./...`.
 
-<a id="go-mod-vendor"></a>
-### `go mod vendor`
+### `go mod vendor` {#go-mod-vendor}
 
 Usage:
 
@@ -1531,8 +1494,7 @@
 The `-v` flag causes `go mod vendor` to print the names of vendored modules
 and packages to standard error.
 
-<a id="go-mod-verify"></a>
-### `go mod verify`
+### `go mod verify` {#go-mod-verify}
 
 Usage:
 
@@ -1571,8 +1533,7 @@
 selection](#minimal-version-selection). It will use `go.sum` to verify those
 files, and it may add `go.sum` entries for missing hashes.
 
-<a id="go-version-m"></a>
-### `go version -m`
+### `go version -m` {#go-version-m}
 
 Usage:
 
@@ -1639,8 +1600,7 @@
   version, and sum are listed, as with `mod` and `dep`. A replaced module has
   no sum.
 
-<a id="go-clean-modcache"></a>
-### `go clean -modcache`
+### `go clean -modcache` {#go-clean-modcache}
 
 Usage:
 
@@ -1677,8 +1637,7 @@
 may be used to check that files in the cache match hashes in the main module's
 `go.sum` file.
 
-<a id="version-queries"></a>
-### Version queries
+### Version queries {#version-queries}
 
 Several commands allow you to specify a version of a module using a *version
 query*, which appears after an `@` character following a module or package path
@@ -1734,8 +1693,7 @@
 at the tip of the repository's default branch. Other queries will report
 an error.
 
-<a id="commands-outside"></a>
-### Module commands outside a module
+### Module commands outside a module {#commands-outside}
 
 Module-aware Go commands normally run in the context of a [main
 module](#glos-main-module) defined by a `go.mod` file in the working directory
@@ -1817,11 +1775,9 @@
   </tbody>
 </table>
 
-<a id="module-proxy"></a>
-## Module proxies
+## Module proxies {#module-proxy}
 
-<a id="goproxy-protocol"></a>
-### `GOPROXY` protocol
+### `GOPROXY` protocol {#goproxy-protocol}
 
 A [*module proxy*](#glos-module-proxy) is an HTTP server that can respond to
 `GET` requests for paths specified below. The requests have no query parameters,
@@ -1974,8 +1930,7 @@
 `https://example.com/proxy` would let users access cached module versions by
 setting `GOPROXY` to `https://example.com/proxy`.
 
-<a id="communicating-with-proxies"></a>
-### Communicating with proxies
+### Communicating with proxies {#communicating-with-proxies}
 
 The `go` command may download module source code and metadata from a [module
 proxy](#glos-module-proxy). The `GOPROXY` [environment
@@ -2090,8 +2045,7 @@
 information. Note that version lists and version metadata returned for `.info`
 requests are not authenticated and may change over time.
 
-<a id="vcs"></a>
-## Version control systems
+## Version control systems {#vcs}
 
 The `go` command may download module source code and metadata directly from a
 version control repository. Downloading a module from a
@@ -2108,8 +2062,7 @@
 to `direct`. See [Environment variables](#environment-variables) for more
 information.
 
-<a id="vcs-find"></a>
-### Finding a repository for a module path
+### Finding a repository for a module path {#vcs-find}
 
 When the `go` command downloads a module in `direct` mode, it starts by locating
 the repository that contains the module. The `go` command sends an
@@ -2176,8 +2129,7 @@
 commits without downloading ancestor commits, but doing so is sometimes
 necessary.
 
-<a id="vcs-version"></a>
-### Mapping versions to commits
+### Mapping versions to commits {#vcs-version}
 
 The `go` command may check out a module within a repository at a specific
 [canonical version](#glos-canonical-version) like `v1.2.3`, `v2.4.0-beta`, or
@@ -2216,8 +2168,7 @@
 downloading it. Even after a tag is deleted, its content may remain
 available on [module proxies](#glos-module-proxy).
 
-<a id="vcs-pseudo"></a>
-### Mapping pseudo-versions to commits
+### Mapping pseudo-versions to commits {#vcs-pseudo}
 
 The `go` command may check out a module within a repository at a specific
 revision, encoded as a [pseudo-version](#glos-pseudo-version) like
@@ -2237,8 +2188,7 @@
 
 See [Pseudo-versions](#pseudo-versions) for more information.
 
-<a id="vcs-branch"></a>
-### Mapping branches and commits to versions
+### Mapping branches and commits to versions {#vcs-branch}
 
 A module may be checked out at a specific branch, tag, or revision using a
 [version query](#version-queries).
@@ -2264,8 +2214,7 @@
 ancestors with valid semantic version tags, the highest ancestor version will be
 used as the pseudo-version base. See [Pseudo-versions](#pseudo-versions).
 
-<a id="vcs-dir"></a>
-### Module directories within a repository
+### Module directories within a repository {#vcs-dir}
 
 Once a module's repository has been checked out at a specific revision, the `go`
 command must locate the directory that contains the module's `go.mod` file
@@ -2314,8 +2263,7 @@
 module cache the same way they would be if the `.zip` file were downloaded from
 a proxy.
 
-<a id="zip-files"></a>
-## Module zip files
+## Module zip files {#zip-files}
 
 Module versions are distributed as `.zip` files. There is rarely any need to
 interact directly with these files, since the `go` command creates, downloads,
@@ -2336,8 +2284,7 @@
 package may be used to create, extract, or check contents of zip files
 programmatically.
 
-<a id="zip-path-size-constraints"></a>
-### File path and size constraints
+### File path and size constraints {#zip-path-size-constraints}
 
 There are a number of restrictions on the content of module zip files. These
 constraints ensure that zip files can be extracted safely and consistently on
@@ -2382,8 +2329,7 @@
 * A file or directory name up to the first dot must not be a reserved file name
   on Windows, regardless of case (`CON`, `com1`, `NuL`, and so on).
 
-<a id="private-modules"></a>
-## Private modules
+## Private modules {#private-modules}
 
 Go modules are frequently developed and distributed on version control servers
 and module proxies that aren't available on the public internet. The `go`
@@ -2417,8 +2363,7 @@
 The rest of this section describes common patterns for providing access to
 private module proxies and version control repositories.
 
-<a id="private-module-proxy-all"></a>
-### Private proxy serving all modules
+### Private proxy serving all modules {#private-module-proxy-all}
 
 A central private proxy server that serves all modules (public and private)
 provides the most control for administrators and requires the least
@@ -2451,8 +2396,7 @@
 download`](#go-mod-download) (with suitable configuration) to retrieve missing
 modules.
 
-<a id="private-module-proxy-private"></a>
-### Private proxy serving private modules
+### Private proxy serving private modules {#private-module-proxy-private}
 
 A private proxy server may serve private modules without also serving publicly
 available modules. The `go` command can be configured to fall back to
@@ -2482,8 +2426,7 @@
 with 403 (Forbidden) for a module with an unsuitable license or with known
 security vulnerabilities.
 
-<a id="private-module-proxy-direct"></a>
-### Direct access to private modules
+### Direct access to private modules {#private-module-proxy-direct}
 
 The `go` command may be configured to bypass public proxies and download private
 modules directly from version control servers. This is useful when running a
@@ -2521,8 +2464,7 @@
 prompts. By default, when invoking Git, the `go` command disables interactive
 prompts by setting `GIT_TERMINAL_PROMPT=0`, but it respects explicit settings.
 
-<a id="private-module-proxy-auth"></a>
-### Passing credentials to private proxies
+### Passing credentials to private proxies {#private-module-proxy-auth}
 
 The `go` command supports HTTP [basic
 authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) when
@@ -2559,8 +2501,7 @@
 Use caution when taking this approach: environment variables may be appear
 in shell history and in logs.
 
-<a id="module-cache"></a>
-## Module cache
+## Module cache {#module-cache}
 
 The <dfn>module cache</dfn> is the directory where the `go` command stores
 downloaded module files. The module cache is distinct from the build cache,
@@ -2695,8 +2636,7 @@
   </tbody>
 </table>
 
-<a id="authenticating"></a>
-## Authenticating modules
+## Authenticating modules {#authenticating}
 
 <!-- TODO: continue this section -->
 When deciding whether to trust the source code for a module version just
@@ -2705,8 +2645,7 @@
 does not contain an entry for that module version, then it may consult the
 checksum database.
 
-<a id="go.sum-files"></a>
-### go.sum files
+### go.sum files {#go.sum-files}
 
 A module may have a text file named `go.sum` in its root directory, alongside
 its `go.mod` file. The `go.sum` file contains cryptographic hashes of the
@@ -2758,8 +2697,7 @@
 (for example, after an upgrade). [`go mod tidy`](#go-mod-tidy) will add missing
 hashes and will remove unnecessary hashes from `go.sum`.
 
-<a id="checksum-database"></a>
-### Checksum database
+### Checksum database {#checksum-database}
 
 The checksum database is a global source of `go.sum` lines. The `go` command can
 use this in many situations to detect misbehavior by proxies or origin servers.
@@ -2912,11 +2850,9 @@
 [set these variables](/pkg/cmd/go/#hdr-Print_Go_environment_information)
 for future `go` command invocations.
 
-<a id="privacy"></a>
-## Privacy
+## Privacy {#privacy}
 
-<a id="environment-variables"></a>
-## Environment variables
+## Environment variables {#environment-variables}
 
 Module behavior in the `go` command may be configured using the environment
 variables listed below. This list only includes module-related environment
@@ -3145,8 +3081,7 @@
   </tbody>
 </table>
 
-<a id="glossary"></a>
-## Glossary
+## Glossary {#glossary}
 
 <a id="glos-build-constraint"></a>
 **build constraint:** A condition that determines whether a Go source file is
diff --git a/content/static/static.go b/content/static/static.go
index 88d2b1b..58572a9 100644
--- a/content/static/static.go
+++ b/content/static/static.go
@@ -121,5 +121,5 @@
 
 	"style.css": "body\x20{\x0a\x20\x20margin:\x200;\x0a\x20\x20font-family:\x20Roboto,\x20Arial,\x20sans-serif;\x0a\x20\x20background-color:\x20#fff;\x0a\x20\x20line-height:\x201.3;\x0a\x20\x20text-align:\x20center;\x0a\x20\x20color:\x20#3e4042;\x0a}\x0atextarea\x20{\x0a\x20\x20/*\x20Inherit\x20text\x20color\x20from\x20body\x20avoiding\x20illegible\x20text\x20in\x20the\x20case\x20where\x20the\x0a\x20\x20\x20*\x20user\x20has\x20inverted\x20the\x20browsers\x20custom\x20text\x20and\x20background\x20colors.\x20*/\x0a\x20\x20color:\x20inherit;\x0a}\x0apre,\x0acode\x20{\x0a\x20\x20font-family:\x20Menlo,\x20monospace;\x0a\x20\x20font-size:\x200.875rem;\x0a}\x0apre\x20{\x0a\x20\x20line-height:\x201.4;\x0a\x20\x20overflow-x:\x20auto;\x0a}\x0apre\x20.comment\x20{\x0a\x20\x20color:\x20#006600;\x0a}\x0apre\x20.highlight,\x0apre\x20.highlight-comment,\x0apre\x20.selection-highlight,\x0apre\x20.selection-highlight-comment\x20{\x0a\x20\x20background:\x20#ffff00;\x0a}\x0apre\x20.selection,\x0apre\x20.selection-comment\x20{\x0a\x20\x20background:\x20#ff9632;\x0a}\x0apre\x20.ln\x20{\x0a\x20\x20color:\x20#999;\x0a\x20\x20background:\x20#efefef;\x0a}\x0a.ln\x20{\x0a\x20\x20user-select:\x20none;\x0a\x0a\x20\x20/*\x20Ensure\x208\x20characters\x20in\x20the\x20document\x20-\x20which\x20due\x20to\x20floating\x0a\x20\x20\x20*\x20point\x20rendering\x20issues,\x20might\x20have\x20a\x20width\x20of\x20less\x20than\x201\x20each\x20-\x20are\x208\x0a\x20\x20\x20*\x20characters\x20wide,\x20so\x20a\x20tab\x20in\x20the\x209th\x20position\x20indents\x20properly.\x20See\x0a\x20\x20\x20*\x20https://github.com/webcompat/web-bugs/issues/17530#issuecomment-402675091\x0a\x20\x20\x20*\x20for\x20more\x20information.\x20*/\x0a\x20\x20display:\x20inline-block;\x0a\x20\x20width:\x208ch;\x0a}\x0a\x0a.search-nav\x20{\x0a\x20\x20margin-left:\x201.25rem;\x0a\x20\x20font-size:\x200.875rem;\x0a\x20\x20column-gap:\x201.25rem;\x0a\x20\x20column-fill:\x20auto;\x0a\x20\x20column-width:\x2014rem;\x0a}\x0a\x0a.search-nav\x20.indent\x20{\x0a\x20\x20margin-left:\x201.25rem;\x0a}\x0a\x0aa,\x0a.exampleHeading\x20.text,\x0a.expandAll\x20{\x0a\x20\x20color:\x20#007d9c;\x0a\x20\x20text-decoration:\x20none;\x0a}\x0aa:hover,\x0a.exampleHeading\x20.text:hover,\x0a.expandAll:hover\x20{\x0a\x20\x20text-decoration:\x20underline;\x0a}\x0a.article\x20a\x20{\x0a\x20\x20text-decoration:\x20underline;\x0a}\x0a.article\x20.title\x20a\x20{\x0a\x20\x20text-decoration:\x20none;\x0a}\x0a\x0a.permalink\x20{\x0a\x20\x20display:\x20none;\x0a}\x0a:hover\x20>\x20.permalink\x20{\x0a\x20\x20display:\x20inline;\x0a}\x0a\x0ap,\x0ali\x20{\x0a\x20\x20max-width:\x2050rem;\x0a\x20\x20word-wrap:\x20break-word;\x0a}\x0ap,\x0apre,\x0aul,\x0aol\x20{\x0a\x20\x20margin:\x201.25rem;\x0a}\x0apre\x20{\x0a\x20\x20background:\x20#efefef;\x0a\x20\x20padding:\x200.625rem;\x0a\x20\x20border-radius:\x200.3125rem;\x0a}\x0a\x0ah1,\x0ah2,\x0ah3,\x0ah4\x20{\x0a\x20\x20margin:\x201.25rem\x200\x201.25rem;\x0a\x20\x20padding:\x200;\x0a\x20\x20color:\x20#202224;\x0a\x20\x20font-family:\x20'Work\x20Sans',\x20sans-serif;\x0a\x20\x20font-weight:\x20600;\x0a}\x0ah1\x20{\x0a\x20\x20font-size:\x201.75rem;\x0a\x20\x20line-height:\x201;\x0a}\x0ah1\x20.text-muted\x20{\x0a\x20\x20color:\x20#777;\x0a}\x0ah2\x20{\x0a\x20\x20font-size:\x201.25rem;\x0a\x20\x20background:\x20#e0ebf5;\x0a\x20\x20padding:\x200.5rem;\x0a\x20\x20line-height:\x201.25;\x0a\x20\x20font-weight:\x20normal;\x0a\x20\x20overflow-wrap:\x20break-word;\x0a}\x0ah2\x20a\x20{\x0a\x20\x20font-weight:\x20bold;\x0a}\x0ah3\x20{\x0a\x20\x20font-size:\x201.25rem;\x0a\x20\x20line-height:\x201.25;\x0a\x20\x20overflow-wrap:\x20break-word;\x0a}\x0ah3,\x0ah4\x20{\x0a\x20\x20margin:\x201.25rem\x200.3125rem;\x0a}\x0ah4\x20{\x0a\x20\x20font-size:\x201rem;\x0a}\x0a\x0ah2\x20>\x20span,\x0ah3\x20>\x20span\x20{\x0a\x20\x20float:\x20right;\x0a\x20\x20margin:\x200\x2025px\x200\x200;\x0a\x20\x20font-weight:\x20normal;\x0a\x20\x20color:\x20#5279c7;\x0a}\x0a\x0adl\x20{\x0a\x20\x20margin:\x201.25rem;\x0a}\x0add\x20{\x0a\x20\x20margin:\x200\x200\x200\x201.25rem;\x0a}\x0adl,\x0add\x20{\x0a\x20\x20font-size:\x200.875rem;\x0a}\x0adiv#nav\x20table\x20td\x20{\x0a\x20\x20vertical-align:\x20top;\x0a}\x0a\x0a.ModTable\x20{\x0a\x20\x20border-collapse:\x20collapse;\x0a\x20\x20margin:\x201.25rem;\x0a\x20\x20max-width:\x2050rem;\x0a}\x0a.ModTable\x20code\x20{\x0a\x20\x20white-space:\x20nowrap;\x0a}\x0a.ModTable\x20td,\x0a.ModTable\x20th\x20{\x0a\x20\x20border:\x201px\x20solid\x20#a9a9a9;\x0a\x20\x20padding:\x201rem;\x0a\x20\x20vertical-align:\x20top;\x0a}\x0a.ModTable\x20td\x20p\x20{\x0a\x20\x20margin:\x200\x200\x201rem\x200;\x0a}\x0a.ModTable\x20td\x20p:last-child\x20{\x0a\x20\x20margin-bottom:\x200;\x0a}\x0a\x0a#pkg-index\x20h3\x20{\x0a\x20\x20font-size:\x201rem;\x0a}\x0a.pkg-dir\x20{\x0a\x20\x20padding:\x200\x200.625rem;\x0a}\x0a.pkg-dir\x20table\x20{\x0a\x20\x20border-collapse:\x20collapse;\x0a\x20\x20border-spacing:\x200;\x0a}\x0a.pkg-name\x20{\x0a\x20\x20padding-right:\x200.625rem;\x0a}\x0a.alert\x20{\x0a\x20\x20color:\x20#aa0000;\x0a}\x0a\x0a#pkg-examples\x20h3\x20{\x0a\x20\x20float:\x20left;\x0a}\x0a\x0a#pkg-examples\x20dl\x20{\x0a\x20\x20clear:\x20both;\x0a}\x0a\x0a.expandAll\x20{\x0a\x20\x20cursor:\x20pointer;\x0a\x20\x20float:\x20left;\x0a\x20\x20margin:\x201.25rem\x200;\x0a}\x0a\x0a.Site\x20{\x0a\x20\x20display:\x20flex;\x0a\x20\x20flex-direction:\x20column;\x0a\x20\x20min-height:\x20100vh;\x0a}\x0a.Site-content\x20{\x0a\x20\x20flex:\x201;\x0a}\x0a#page\x20{\x0a\x20\x20width:\x20100%;\x0a}\x0a#page\x20>\x20.container,\x0a.Header-nav\x20{\x0a\x20\x20text-align:\x20left;\x0a\x20\x20margin-left:\x20auto;\x0a\x20\x20margin-right:\x20auto;\x0a\x20\x20padding:\x200\x201.25rem;\x0a}\x0a#page\x20>\x20.container,\x0a.Header-nav,\x0a.Footer\x20{\x0a\x20\x20max-width:\x2059.38rem;\x0a}\x0a#page.wide\x20>\x20.container,\x0a.Header-nav--wide,\x0a.Footer--wide\x20{\x0a\x20\x20max-width:\x20none;\x0a}\x0a\x0adiv#playground\x20.buttons\x20a\x20{\x0a\x20\x20background:\x20#375eab;\x0a\x20\x20border:\x200.0625rem\x20solid\x20#757575;\x0a\x20\x20color:\x20white;\x0a}\x0a\x0a/*\x20Style\x20download\x20button\x20on\x20doc/install\x20page\x20*/\x0aa#start\x20{\x0a\x20\x20background:\x20#e0ebf5;\x0a\x20\x20border:\x200.0625rem\x20solid\x20#375eab;\x0a\x20\x20border-radius:\x200.3125rem;\x0a\x20\x20color:\x20#222;\x0a\x20\x20display:\x20block;\x0a\x20\x20padding:\x200.625rem;\x0a\x20\x20text-align:\x20center;\x0a\x20\x20text-decoration:\x20none;\x0a}\x0aa#start\x20.big\x20{\x0a\x20\x20display:\x20block;\x0a\x20\x20font-size:\x201.25rem;\x0a\x20\x20font-weight:\x20bold;\x0a}\x0aa#start\x20.desc\x20{\x0a\x20\x20display:\x20block;\x0a\x20\x20font-size:\x200.875rem;\x0a\x20\x20font-weight:\x20normal;\x0a\x20\x20margin-top:\x200.3125rem;\x0a}\x0a\x0a.download\x20{\x0a\x20\x20width:\x209.375rem;\x0a}\x0a\x0a::-webkit-input-placeholder\x20{\x0a\x20\x20color:\x20#7f7f7f;\x0a\x20\x20opacity:\x201;\x0a}\x0a::placeholder\x20{\x0a\x20\x20color:\x20#7f7f7f;\x0a\x20\x20opacity:\x201;\x0a}\x0a\x0a.Header\x20{\x0a\x20\x20align-items:\x20center;\x0a\x20\x20box-sizing:\x20border-box;\x0a\x20\x20display:\x20flex;\x0a\x20\x20font-size:\x200.875rem;\x0a\x20\x20justify-content:\x20space-between;\x0a\x20\x20padding:\x201.375rem\x200;\x0a}\x0a.Header.is-active\x20{\x0a\x20\x20background-color:\x20#f7f9fa;\x0a}\x0a.Header-banner\x20{\x0a\x20\x20display:\x20none;\x0a}\x0a.Header-logo\x20{\x0a\x20\x20height:\x202rem;\x0a\x20\x20width:\x205.125rem;\x0a}\x0a.Header-nav\x20{\x0a\x20\x20align-items:\x20center;\x0a\x20\x20display:\x20flex;\x0a\x20\x20flex-wrap:\x20wrap;\x0a\x20\x20justify-content:\x20space-between;\x0a\x20\x20width:\x20100%;\x0a}\x0a.Header-menuButton\x20{\x0a\x20\x20background-color:\x20transparent;\x0a\x20\x20border:\x20none;\x0a\x20\x20box-sizing:\x20content-box;\x0a\x20\x20cursor:\x20pointer;\x0a\x20\x20display:\x20inline-block;\x0a\x20\x20height:\x201.313rem;\x0a\x20\x20padding:\x200.375rem;\x0a\x20\x20position:\x20relative;\x0a\x20\x20vertical-align:\x20middle;\x0a\x20\x20width:\x201.313rem;\x0a}\x0a.Header-menuButtonInner\x20{\x0a\x20\x20position:\x20relative;\x0a}\x0a.Header-menuButton::after,\x0a.Header-menuButtonInner,\x0a.Header-menuButtonInner::before,\x0a.Header-menuButtonInner::after\x20{\x0a\x20\x20background-color:\x20#3e4042;\x0a\x20\x20height:\x200.1875rem;\x0a\x20\x20transition:\x20all\x20100ms\x20ease-in;\x0a}\x0a.Header-menuButton::after\x20{\x0a\x20\x20opacity:\x200;\x0a\x20\x20top:\x200.9375rem;\x0a}\x0a.Header-menuButton::after,\x0a.Header-menuButtonInner::before,\x0a.Header-menuButtonInner::after\x20{\x0a\x20\x20content:\x20'';\x0a\x20\x20display:\x20block;\x0a\x20\x20position:\x20absolute;\x0a\x20\x20width:\x201.313rem;\x0a}\x0a.Header-menuButtonInner::before\x20{\x0a\x20\x20top:\x20-0.375rem;\x0a}\x0a.Header-menuButtonInner::after\x20{\x0a\x20\x20bottom:\x20-0.375rem;\x0a}\x0a.Header.is-active\x20.Header-menuButton::after\x20{\x0a\x20\x20opacity:\x201;\x0a\x20\x20transform:\x20rotate(-45deg);\x0a}\x0a.Header.is-active\x20.Header-menuButton\x20.Header-menuButtonInner\x20{\x0a\x20\x20transform:\x20rotate(45deg);\x0a}\x0a.Header.is-active\x20.Header-menuButton\x20.Header-menuButtonInner::before,\x0a.Header.is-active\x20.Header-menuButton\x20.Header-menuButtonInner::after\x20{\x0a\x20\x20background-color:\x20transparent;\x0a}\x0a.Header-menu\x20{\x0a\x20\x20align-items:\x20center;\x0a\x20\x20display:\x20none;\x0a\x20\x20flex-direction:\x20column;\x0a\x20\x20list-style:\x20none;\x0a\x20\x20margin:\x200;\x0a\x20\x20padding:\x200;\x0a\x20\x20width:\x20100%;\x0a}\x0a.Header.is-active\x20.Header-menu\x20{\x0a\x20\x20display:\x20flex;\x0a}\x0a.Header-menuItem:first-of-type\x20{\x0a\x20\x20/*\x20Offset\x20the\x20padding\x20of\x20the\x20inner\x20link,\x20maintaining\x20its\x20click\x20target\x20size,\x0a\x20\x20\x20\x20\x20while\x20still\x20placing\x20the\x20item\x20as\x20if\x20it\x20had\x20no\x20top\x20margin\x20or\x20padding.\x20*/\x0a\x20\x20margin-top:\x20-0.5rem;\x0a}\x0a.Header-menuItem\x20{\x0a\x20\x20display:\x20inline-flex;\x0a}\x0a.Header-menuItem,\x0a.Header-menuItem\x20a:link,\x0a.Header-menuItem\x20a:visited,\x0a.Header-menuItem--search,\x0a.HeaderSearch\x20{\x0a\x20\x20width:\x20100%;\x0a}\x0a.Header-menuItem,\x0a.Header-menuItem\x20a:link,\x0a.Header-menuItem\x20a:visited\x20{\x0a\x20\x20color:\x20#3e4042;\x0a\x20\x20text-align:\x20center;\x0a}\x0a.Header-menuItem\x20a:link,\x0a.Header-menuItem\x20a:visited\x20{\x0a\x20\x20padding:\x200.5rem\x200;\x0a}\x0a.Header-menuItem--search\x20{\x0a\x20\x20margin-top:\x200.5rem;\x0a}\x0a.HeaderSearch,\x0a.HeaderSearch-label\x20{\x0a\x20\x20display:\x20inline-block;\x0a\x20\x20position:\x20relative;\x0a}\x0a.HeaderSearch\x20{\x0a\x20\x20border:\x200.0625rem\x20solid\x20#979797;\x0a\x20\x20border-radius:\x200.1875rem;\x0a\x20\x20display:\x20inline-flex;\x0a\x20\x20overflow:\x20hidden;\x0a\x20\x20position:\x20relative;\x0a}\x0a.HeaderSearch-input\x20{\x0a\x20\x20-webkit-appearance:\x20none;\x0a\x20\x20border:\x20none;\x0a\x20\x20border-radius:\x200;\x0a\x20\x20box-sizing:\x20border-box;\x0a\x20\x20display:\x20block;\x0a\x20\x20flex:\x201;\x0a\x20\x20font:\x20inherit;\x0a\x20\x20font-size:\x2016px;\x20/*\x20Prevents\x20automatic\x20zoom\x20on\x20mobile\x20devices\x20*/\x0a\x20\x20margin:\x200;\x0a\x20\x20padding:\x200.5rem;\x0a}\x0a.HeaderSearch-input::-webkit-search-decoration\x20{\x0a\x20\x20-webkit-appearance:\x20none;\x0a}\x0a.HeaderSearch-input::-moz-ui-invalid\x20{\x0a\x20\x20box-shadow:\x20unset;\x0a}\x0a.HeaderSearch-submit\x20{\x0a\x20\x20background-color:\x20#fff;\x0a\x20\x20border:\x20none;\x0a\x20\x20box-sizing:\x20border-box;\x0a\x20\x20cursor:\x20pointer;\x0a\x20\x20margin:\x200;\x0a\x20\x20padding:\x200.125rem\x200.5rem\x200\x200.55rem;\x0a\x20\x20transition:\x20background-color\x20200ms;\x0a}\x0a.HeaderSearch:focus-within\x20.HeaderSearch-submit\x20{\x0a\x20\x20background-color:\x20#e5f6fb;\x0a}\x0a.HeaderSearch-icon\x20{\x0a\x20\x20fill:\x20#757575;\x0a\x20\x20transition:\x20fill\x20200ms;\x0a}\x0a.HeaderSearch:focus-within\x20.HeaderSearch-icon\x20{\x0a\x20\x20fill:\x20#007d9c;\x0a}\x0a@media\x20only\x20screen\x20and\x20(min-width:\x2056rem)\x20{\x0a\x20\x20.Header\x20{\x0a\x20\x20\x20\x20display:\x20block;\x0a\x20\x20\x20\x20padding:\x200;\x0a\x20\x20}\x0a\x20\x20.Header-banner\x20{\x0a\x20\x20\x20\x20background-color:\x20#000;\x0a\x20\x20\x20\x20color:\x20#fff;\x0a\x20\x20\x20\x20display:\x20block;\x0a\x20\x20\x20\x20padding:\x201rem;\x0a\x20\x20}\x0a\x20\x20.Header-banner\x20a:link,\x0a\x20\x20.Header-banner\x20a:visited\x20{\x0a\x20\x20\x20\x20color:\x20#fff;\x0a\x20\x20\x20\x20text-decoration:\x20underline;\x0a\x20\x20}\x0a\x20\x20.Header-nav\x20{\x0a\x20\x20\x20\x20width:\x20auto;\x0a\x20\x20}\x0a\x20\x20.Header.is-active\x20{\x0a\x20\x20\x20\x20background-color:\x20#fff;\x0a\x20\x20}\x0a\x20\x20.Header.is-active\x20.Header-menu\x20{\x0a\x20\x20\x20\x20display:\x20block;\x0a\x20\x20}\x0a\x20\x20.Header-menuButton\x20{\x0a\x20\x20\x20\x20display:\x20none;\x0a\x20\x20}\x0a\x20\x20.Header-menu\x20{\x0a\x20\x20\x20\x20display:\x20flex;\x0a\x20\x20\x20\x20flex-direction:\x20row;\x0a\x20\x20\x20\x20width:\x20auto;\x0a\x20\x20}\x0a\x20\x20.Header-menuItem:first-of-type\x20{\x0a\x20\x20\x20\x20margin-top:\x200;\x0a\x20\x20}\x0a\x20\x20.Header-menuItem,\x0a\x20\x20.Header-menuItem\x20a:link,\x0a\x20\x20.Header-menuItem\x20a:visited\x20{\x0a\x20\x20\x20\x20width:\x20auto;\x0a\x20\x20}\x0a\x20\x20.Header-menuItem\x20a:link,\x0a\x20\x20.Header-menuItem\x20a:visited\x20{\x0a\x20\x20\x20\x20padding:\x202rem\x201.5rem;\x0a\x20\x20}\x0a\x20\x20.Header-menuItem\x20a:hover,\x0a\x20\x20.Header-menuItem\x20a:focus\x20{\x0a\x20\x20\x20\x20text-decoration:\x20underline;\x0a\x20\x20}\x0a\x20\x20.Header-menuItem--search,\x0a\x20\x20.HeaderSearch\x20{\x0a\x20\x20\x20\x20width:\x208.75rem;\x0a\x20\x20}\x0a\x20\x20.Header-menuItem--search\x20{\x0a\x20\x20\x20\x20margin-left:\x201.5rem;\x0a\x20\x20\x20\x20margin-top:\x200;\x0a\x20\x20}\x0a\x20\x20.HeaderSearch-input\x20{\x0a\x20\x20\x20\x20min-width:\x205.625rem;\x0a\x20\x20}\x0a\x20\x20.HeaderSearch-submit\x20{\x0a\x20\x20\x20\x20padding:\x200.125rem\x200.5rem\x200;\x0a\x20\x20}\x0a}\x0a@media\x20only\x20screen\x20and\x20(min-width:\x2057.5rem)\x20{\x0a\x20\x20.Header\x20{\x0a\x20\x20\x20\x20font-size:\x201rem;\x0a\x20\x20}\x0a}\x0a\x0a.Button,\x0a.Button:link,\x0a.Button:visited\x20{\x0a\x20\x20align-items:\x20center;\x0a\x20\x20background-color:\x20#f7f9fa;\x0a\x20\x20border:\x20none;\x0a\x20\x20border-radius:\x200.1875rem;\x0a\x20\x20box-shadow:\x200\x202px\x205px\x20rgba(0,\x200,\x200,\x200.2);\x0a\x20\x20box-sizing:\x20border-box;\x0a\x20\x20color:\x20#007d9c;\x0a\x20\x20cursor:\x20pointer;\x0a\x20\x20display:\x20inline-flex;\x0a\x20\x20font:\x20bold\x200.875rem\x20Roboto,\x20sans-serif;\x0a\x20\x20height:\x202.375rem;\x0a\x20\x20padding:\x200\x200.625rem;\x0a\x20\x20justify-content:\x20center;\x0a\x20\x20min-width:\x204.063rem;\x0a\x20\x20text-decoration:\x20none;\x0a}\x0a.Button:active\x20{\x0a\x20\x20box-shadow:\x200\x201px\x203px\x20rgba(0,\x200,\x200,\x200.2);\x0a}\x0a.Button--primary,\x0a.Button--primary:link,\x0a.Button--primary:visited\x20{\x0a\x20\x20border:\x200.0625rem\x20solid\x20#00add8;\x0a}\x0a.Button--big,\x0a.Button--big:link,\x0a.Button--big:visited\x20{\x0a\x20\x20background-color:\x20#7fd5ea;\x0a\x20\x20border-radius:\x200.3125rem;\x0a\x20\x20color:\x20#202224;\x0a\x20\x20font-size:\x201.5rem;\x0a\x20\x20height:\x204rem;\x0a\x20\x20justify-content:\x20center;\x0a}\x0a\x0a.HomeContainer\x20{\x0a\x20\x20align-items:\x20top;\x0a\x20\x20display:\x20flex;\x0a\x20\x20flex-wrap:\x20wrap;\x0a\x20\x20justify-content:\x20space-between;\x0a}\x0a.HomeContainer\x20*\x20{\x0a\x20\x20box-sizing:\x20border-box;\x0a}\x0a\x0a.HomeSection\x20{\x0a\x20\x20flex:\x200\x200\x20100%;\x0a\x20\x20margin-bottom:\x202.5rem;\x0a\x20\x20padding:\x200\x201rem;\x0a}\x0a.HomeSection-header\x20{\x0a\x20\x20background:\x20none;\x0a\x20\x20color:\x20#202224;\x0a\x20\x20margin:\x200\x200\x200.625rem\x200;\x0a\x20\x20padding:\x200;\x0a\x20\x20font-weight:\x20bold;\x0a}\x0a\x0a.Hero-header\x20{\x0a\x20\x20font:\x201.5rem\x20Roboto,\x20sans-serif;\x0a\x20\x20line-height:\x20inherit;\x0a\x20\x20margin:\x200\x200\x201.875rem;\x0a}\x0a.Hero-gopher\x20{\x0a\x20\x20background:\x20url('/lib/godoc/images/home-gopher.png')\x20no-repeat;\x0a\x20\x20background-position:\x20center\x20top;\x0a\x20\x20display:\x20block;\x0a\x20\x20height:\x209.688rem;\x0a\x20\x20max-height:\x20200px;\x20/*\x20Setting\x20in\x20px\x20to\x20prevent\x20the\x20gopher\x20from\x20blowing\x20up\x20in\x20very\x20high\x20default\x20font-sizes\x20*/\x0a}\x0a.HeroDownloadButton,\x0a.Hero-description\x20{\x0a\x20\x20text-align:\x20center;\x0a}\x0a.HeroDownloadButton,\x0a.HeroDownloadButton:link,\x0a.HeroDownloadButton:visited\x20{\x0a\x20\x20display:\x20flex;\x0a\x20\x20margin-bottom:\x200.5rem;\x0a}\x0a.HeroDownloadButton-image\x20{\x0a\x20\x20height:\x202rem;\x0a\x20\x20margin-right:\x202rem;\x0a\x20\x20width:\x202rem;\x0a}\x0a.Hero-description\x20{\x0a\x20\x20color:\x20#616161;\x0a\x20\x20font-size:\x200.875rem;\x0a\x20\x20margin:\x200;\x0a}\x0a@media\x20only\x20screen\x20and\x20(min-width:\x2057.1875rem)\x20{\x0a\x20\x20.HomeSection\x20{\x0a\x20\x20\x20\x20flex:\x200\x200\x2026.875rem;\x0a\x20\x20\x20\x20padding:\x200;\x0a\x20\x20}\x0a\x20\x20.Hero,\x0a\x20\x20.Playground\x20{\x0a\x20\x20\x20\x20margin-top:\x201rem;\x0a\x20\x20}\x0a}\x0a\x0a.Playground-headerContainer\x20{\x0a\x20\x20align-items:\x20baseline;\x0a\x20\x20display:\x20flex;\x0a\x20\x20justify-content:\x20space-between;\x0a}\x0a.Playground-popout\x20{\x0a\x20\x20background:\x20url('/lib/godoc/images/play-link.svg')\x20no-repeat;\x0a\x20\x20background-position:\x20right\x20center;\x0a\x20\x20cursor:\x20pointer;\x0a\x20\x20display:\x20block;\x0a\x20\x20font-size:\x201rem;\x0a\x20\x20padding:\x200\x201.688rem;\x0a}\x0a.Playground-input,\x0a.Playground-output\x20{\x0a\x20\x20padding:\x200;\x0a\x20\x20margin:\x200;\x0a\x20\x20font-family:\x20Menlo,\x20monospace;\x0a\x20\x20font-size:\x200.875rem;\x0a}\x0a.Playground-inputContainer\x20{\x0a\x20\x20border-top-left-radius:\x200.3125rem;\x0a\x20\x20border-top-right-radius:\x200.3125rem;\x0a\x20\x20overflow:\x20hidden;\x0a\x20\x20height:\x2011rem;\x0a}\x0a.Playground-input\x20{\x0a\x20\x20width:\x20100%;\x0a\x20\x20height:\x20100%;\x0a\x20\x20border:\x20none;\x0a\x20\x20outline:\x20none;\x0a\x20\x20resize:\x20none;\x0a\x20\x20padding:\x200.625rem;\x0a}\x0a.Playground-outputContainer\x20{\x0a\x20\x20border-bottom-right-radius:\x200.3125rem;\x0a\x20\x20border-bottom-left-radius:\x200.3125rem;\x0a\x20\x20border-top:\x20none\x20!important;\x0a\x20\x20padding:\x200.625rem;\x0a\x20\x20height:\x205rem;\x0a\x20\x20margin-bottom:\x201rem;\x0a\x20\x20overflow:\x20auto;\x0a}\x0a.Playground-output\x20{\x0a\x20\x20padding:\x200;\x0a\x20\x20border-radius:\x200;\x0a}\x0a.Playground-inputContainer,\x0a.Playground-input,\x0a.Playground-outputContainer,\x0a.Playground-output\x20{\x0a\x20\x20background:\x20#f7f9fa;\x0a\x20\x20color:\x20#202224;\x0a}\x0a.Playground-inputContainer,\x0a.Playground-outputContainer\x20{\x0a\x20\x20border:\x200.0625rem\x20solid\x20#c0c2c3;\x0a}\x0a.Playground-controls\x20{\x0a\x20\x20display:\x20flex;\x0a\x20\x20flex-wrap:\x20wrap;\x0a}\x0a.Playground-buttons\x20{\x0a\x20\x20display:\x20flex;\x0a\x20\x20flex:\x201;\x0a\x20\x20flex-wrap:\x20nowrap;\x0a\x20\x20justify-content:\x20space-between;\x0a}\x0a.Playground-selectExample\x20{\x0a\x20\x20background-color:\x20white;\x0a\x20\x20border-radius:\x203px;\x0a\x20\x20border:\x200.0625rem\x20solid\x20#979797;\x0a\x20\x20color:\x20inherit;\x0a\x20\x20font-family:\x20inherit;\x0a\x20\x20font-size:\x2016px;\x20/*\x20Prevents\x20automatic\x20zoom\x20on\x20mobile\x20devices\x20*/\x0a\x20\x20height:\x202.375rem;\x0a\x20\x20margin:\x200\x200\x200.5rem\x200;\x0a\x20\x20width:\x20100%;\x0a}\x0a.Playground-secondaryButtons\x20{\x0a\x20\x20white-space:\x20nowrap;\x0a}\x0a.Playground-secondaryButtons\x20.Button:not(:first-child)\x20{\x0a\x20\x20margin-left:\x200.4375rem;\x0a}\x0a@media\x20only\x20screen\x20and\x20(min-width:\x2027.8125rem)\x20{\x0a\x20\x20.Playground-outputContainer\x20{\x0a\x20\x20\x20\x20margin-bottom:\x201.688rem;\x0a\x20\x20}\x0a\x20\x20.Playground-controls\x20{\x0a\x20\x20\x20\x20flex-wrap:\x20nowrap;\x0a\x20\x20}\x0a\x20\x20.Playground-selectExample\x20{\x0a\x20\x20\x20\x20margin:\x200\x200.4375rem\x200\x200;\x0a\x20\x20\x20\x20width:\x20auto;\x0a\x20\x20}\x0a}\x0a\x0a.Blog-title\x20{\x0a\x20\x20display:\x20block;\x0a\x20\x20font-size:\x201.25rem;\x0a\x20\x20font-weight:\x20normal;\x0a\x20\x20margin:\x200;\x0a}\x0a.Blog-title,\x0a.Blog-extract,\x0a.Blog-when\x20{\x0a\x20\x20margin-bottom:\x200.625rem;\x0a}\x0a.Blog-when\x20{\x0a\x20\x20color:\x20#666;\x0a\x20\x20font-size:\x200.875rem;\x0a}\x0a.Blog-footer\x20{\x0a\x20\x20text-align:\x20right;\x0a}\x0a\x0a@supports\x20(--c:\x200)\x20{\x0a\x20\x20[style*='--aspect-ratio-padding:']\x20{\x0a\x20\x20\x20\x20position:\x20relative;\x0a\x20\x20\x20\x20overflow:\x20hidden;\x0a\x20\x20\x20\x20padding-top:\x20var(--aspect-ratio-padding);\x0a\x20\x20}\x0a\x20\x20[style*='--aspect-ratio-padding:']\x20>\x20*\x20{\x0a\x20\x20\x20\x20position:\x20absolute;\x0a\x20\x20\x20\x20top:\x200;\x0a\x20\x20\x20\x20left:\x200;\x0a\x20\x20\x20\x20width:\x20100%;\x0a\x20\x20\x20\x20height:\x20100%;\x0a\x20\x20}\x0a}\x0a\x0a.Footer\x20{\x0a\x20\x20margin:\x202rem\x20auto\x200;\x0a\x20\x20padding:\x201rem\x201.25rem;\x0a\x20\x20position:\x20relative;\x0a\x20\x20text-align:\x20right;\x0a}\x0a.Footer-gopher\x20{\x0a\x20\x20bottom:\x200;\x0a\x20\x20left:\x201.25rem;\x0a\x20\x20position:\x20absolute;\x0a\x20\x20width:\x205rem;\x0a}\x0a.Footer-links\x20{\x0a\x20\x20flex:\x201;\x0a\x20\x20list-style:\x20none;\x0a\x20\x20margin:\x200;\x0a\x20\x20padding:\x200;\x0a}\x0a.Footer-link\x20{\x0a\x20\x20font-size:\x200.875rem;\x0a\x20\x20white-space:\x20nowrap;\x0a}\x0a.Footer-link\x20+\x20.Footer-link\x20{\x0a\x20\x20margin-top:\x200.5rem;\x0a}\x0a.Footer-supportedBy\x20{\x0a\x20\x20color:\x20#6e7072;\x0a\x20\x20display:\x20inline-block;\x0a\x20\x20font:\x200.875rem\x20'Product\x20Sans',\x20'Roboto',\x20'sans-serif';\x0a\x20\x20margin-top:\x201rem;\x0a}\x0a.Footer-supportedBy:hover\x20{\x0a\x20\x20text-decoration:\x20none;\x0a}\x0a@media\x20only\x20screen\x20and\x20(min-width:\x2050rem)\x20{\x0a\x20\x20.Footer\x20{\x0a\x20\x20\x20\x20align-items:\x20center;\x0a\x20\x20\x20\x20display:\x20flex;\x0a\x20\x20\x20\x20margin:\x205rem\x20auto\x200;\x0a\x20\x20}\x0a\x20\x20.Footer-links\x20{\x0a\x20\x20\x20\x20padding-left:\x206.25rem;\x0a\x20\x20\x20\x20text-align:\x20left;\x0a\x20\x20}\x0a\x20\x20.Footer-link\x20{\x0a\x20\x20\x20\x20display:\x20inline;\x0a\x20\x20}\x0a\x20\x20.Footer-link\x20+\x20.Footer-link\x20{\x0a\x20\x20\x20\x20border-left:\x200.0625rem\x20solid\x20#3e4042;\x0a\x20\x20\x20\x20margin-left:\x200.75rem;\x0a\x20\x20\x20\x20padding-left:\x200.75rem;\x0a\x20\x20}\x0a\x20\x20.Footer-supportedBy\x20{\x0a\x20\x20\x20\x20margin-top:\x200;\x0a\x20\x20}\x0a}\x0a\x0a.toggleButton\x20{\x0a\x20\x20cursor:\x20pointer;\x0a}\x0a.toggle\x20>\x20.collapsed\x20{\x0a\x20\x20display:\x20block;\x0a}\x0a.toggle\x20>\x20.expanded\x20{\x0a\x20\x20display:\x20none;\x0a}\x0a.toggleVisible\x20>\x20.collapsed\x20{\x0a\x20\x20display:\x20none;\x0a}\x0a.toggleVisible\x20>\x20.expanded\x20{\x0a\x20\x20display:\x20block;\x0a}\x0a\x0atable.codetable\x20{\x0a\x20\x20margin-left:\x20auto;\x0a\x20\x20margin-right:\x20auto;\x0a\x20\x20border-style:\x20none;\x0a}\x0atable.codetable\x20td\x20{\x0a\x20\x20padding-right:\x200.625rem;\x0a}\x0ahr\x20{\x0a\x20\x20border-style:\x20none;\x0a\x20\x20border-top:\x200.0625rem\x20solid\x20black;\x0a}\x0a\x0aimg.gopher\x20{\x0a\x20\x20float:\x20right;\x0a\x20\x20margin-left:\x200.625rem;\x0a\x20\x20margin-bottom:\x200.625rem;\x0a\x20\x20z-index:\x20-1;\x0a}\x0ah2\x20{\x0a\x20\x20clear:\x20right;\x0a}\x0a\x0adiv.play\x20{\x0a\x20\x20padding:\x200\x201.25rem\x202.5rem\x201.25rem;\x0a}\x0adiv.play\x20pre,\x0adiv.play\x20textarea,\x0adiv.play\x20.lines\x20{\x0a\x20\x20padding:\x200;\x0a\x20\x20margin:\x200;\x0a\x20\x20font-family:\x20Menlo,\x20monospace;\x0a\x20\x20font-size:\x200.875rem;\x0a}\x0adiv.play\x20.input\x20{\x0a\x20\x20padding:\x200.625rem;\x0a\x20\x20margin-top:\x200.625rem;\x0a\x0a\x20\x20border-top-left-radius:\x200.3125rem;\x0a\x20\x20border-top-right-radius:\x200.3125rem;\x0a\x0a\x20\x20overflow:\x20hidden;\x0a}\x0adiv.play\x20.input\x20textarea\x20{\x0a\x20\x20width:\x20100%;\x0a\x20\x20height:\x20100%;\x0a\x20\x20border:\x20none;\x0a\x20\x20outline:\x20none;\x0a\x20\x20resize:\x20none;\x0a\x0a\x20\x20overflow:\x20hidden;\x0a}\x0adiv#playground\x20.input\x20textarea\x20{\x0a\x20\x20overflow:\x20auto;\x0a\x20\x20resize:\x20auto;\x0a}\x0adiv.play\x20.output\x20{\x0a\x20\x20border-top:\x20none\x20!important;\x0a\x0a\x20\x20padding:\x200.625rem;\x0a\x20\x20max-height:\x2012.5rem;\x0a\x20\x20overflow:\x20auto;\x0a\x0a\x20\x20border-bottom-right-radius:\x200.3125rem;\x0a\x20\x20border-bottom-left-radius:\x200.3125rem;\x0a}\x0adiv.play\x20.output\x20pre\x20{\x0a\x20\x20padding:\x200;\x0a\x20\x20border-radius:\x200;\x0a}\x0adiv.play\x20.input,\x0adiv.play\x20.input\x20textarea,\x0adiv.play\x20.output,\x0adiv.play\x20.output\x20pre\x20{\x0a\x20\x20background:\x20#f7f9fa;\x0a\x20\x20color:\x20#202224;\x0a}\x0adiv.play\x20.input,\x0adiv.play\x20.output\x20{\x0a\x20\x20border:\x200.0625rem\x20solid\x20#c0c2c3;\x0a}\x0adiv.play\x20.buttons\x20{\x0a\x20\x20float:\x20right;\x0a\x20\x20padding:\x200.625rem\x200;\x0a\x20\x20text-align:\x20right;\x0a}\x0adiv.play\x20.buttons\x20.Button\x20{\x0a\x20\x20margin-left:\x200.3125rem;\x0a}\x0a.output\x20.stderr\x20{\x0a\x20\x20color:\x20#933;\x0a}\x0a.output\x20.system\x20{\x0a\x20\x20color:\x20#999;\x0a}\x0a\x0a/*\x20drop-down\x20playground\x20*/\x0adiv#playground\x20{\x0a\x20\x20/*\x20start\x20hidden;\x20revealed\x20by\x20javascript\x20*/\x0a\x20\x20display:\x20none;\x0a}\x0adiv#playground\x20{\x0a\x20\x20position:\x20absolute;\x0a\x20\x20top:\x203.938rem;\x0a\x20\x20right:\x201.25rem;\x0a\x20\x20padding:\x200\x200.625rem\x200.625rem\x200.625rem;\x0a\x20\x20z-index:\x201;\x0a\x20\x20text-align:\x20left;\x0a\x20\x20background:\x20#e0ebf5;\x0a\x0a\x20\x20border:\x200.0625rem\x20solid\x20#b0bbc5;\x0a\x20\x20border-top:\x20none;\x0a\x0a\x20\x20border-bottom-left-radius:\x200.3125rem;\x0a\x20\x20border-bottom-right-radius:\x200.3125rem;\x0a}\x0adiv#playground\x20.code\x20{\x0a\x20\x20width:\x2032.5rem;\x0a\x20\x20height:\x2012.5rem;\x0a}\x0adiv#playground\x20.output\x20{\x0a\x20\x20height:\x206.25rem;\x0a}\x0a\x0a/*\x20Inline\x20runnable\x20snippets\x20(play.js/initPlayground)\x20*/\x0a#content\x20.code\x20pre,\x0a#content\x20.playground\x20pre,\x0a#content\x20.output\x20pre\x20{\x0a\x20\x20margin:\x200;\x0a\x20\x20padding:\x200;\x0a\x20\x20background:\x20none;\x0a\x20\x20border:\x20none;\x0a\x20\x20outline:\x200\x20solid\x20transparent;\x0a\x20\x20overflow:\x20auto;\x0a}\x0a#content\x20.playground\x20.number,\x0a#content\x20.code\x20.number\x20{\x0a\x20\x20color:\x20#999;\x0a}\x0a#content\x20.code,\x0a#content\x20.playground,\x0a#content\x20.output\x20{\x0a\x20\x20width:\x20auto;\x0a\x20\x20margin:\x201.25rem;\x0a\x20\x20padding:\x200.625rem;\x0a\x20\x20border-radius:\x200.3125rem;\x0a}\x0a#content\x20.code,\x0a#content\x20.playground\x20{\x0a\x20\x20background:\x20#e9e9e9;\x0a}\x0a#content\x20.output\x20{\x0a\x20\x20background:\x20#202020;\x0a}\x0a#content\x20.output\x20.stdout,\x0a#content\x20.output\x20pre\x20{\x0a\x20\x20color:\x20#e6e6e6;\x0a}\x0a#content\x20.output\x20.stderr,\x0a#content\x20.output\x20.error\x20{\x0a\x20\x20color:\x20rgb(244,\x2074,\x2063);\x0a}\x0a#content\x20.output\x20.system,\x0a#content\x20.output\x20.exit\x20{\x0a\x20\x20color:\x20rgb(255,\x20209,\x2077);\x0a}\x0a#content\x20.buttons\x20{\x0a\x20\x20position:\x20relative;\x0a\x20\x20float:\x20right;\x0a\x20\x20top:\x20-3.125rem;\x0a\x20\x20right:\x201.875rem;\x0a}\x0a#content\x20.output\x20.buttons\x20{\x0a\x20\x20top:\x20-3.75rem;\x0a\x20\x20right:\x200;\x0a\x20\x20height:\x200;\x0a}\x0a#content\x20.buttons\x20.kill\x20{\x0a\x20\x20display:\x20none;\x0a\x20\x20visibility:\x20hidden;\x0a}\x0aa.error\x20{\x0a\x20\x20font-weight:\x20bold;\x0a\x20\x20color:\x20white;\x0a\x20\x20background-color:\x20darkred;\x0a\x20\x20border-bottom-left-radius:\x200.25rem;\x0a\x20\x20border-bottom-right-radius:\x200.25rem;\x0a\x20\x20border-top-left-radius:\x200.25rem;\x0a\x20\x20border-top-right-radius:\x200.25rem;\x0a\x20\x20padding:\x200.125rem\x200.25rem\x200.125rem\x200.25rem;\x20/*\x20TRBL\x20*/\x0a}\x0a\x0a.downloading\x20{\x0a\x20\x20background:\x20#f9f9be;\x0a\x20\x20padding:\x200.625rem;\x0a\x20\x20text-align:\x20center;\x0a\x20\x20border-radius:\x200.3125rem;\x0a}\x0a\x0a@media\x20(max-width:\x2043.75em)\x20{\x0a\x20\x20body\x20{\x0a\x20\x20\x20\x20font-size:\x200.9375rem;\x0a\x20\x20}\x0a\x0a\x20\x20div#playground\x20{\x0a\x20\x20\x20\x20left:\x200;\x0a\x20\x20\x20\x20right:\x200;\x0a\x20\x20}\x0a\x0a\x20\x20pre,\x0a\x20\x20code\x20{\x0a\x20\x20\x20\x20font-size:\x200.866rem;\x0a\x20\x20}\x0a\x0a\x20\x20#page\x20>\x20.container,\x0a\x20\x20.Header-nav\x20{\x0a\x20\x20\x20\x20padding:\x200\x200.625rem;\x0a\x20\x20}\x0a\x0a\x20\x20p,\x0a\x20\x20pre,\x0a\x20\x20ul,\x0a\x20\x20ol\x20{\x0a\x20\x20\x20\x20margin:\x200.625rem;\x0a\x20\x20}\x0a\x0a\x20\x20.pkg-synopsis\x20{\x0a\x20\x20\x20\x20display:\x20none;\x0a\x20\x20}\x0a\x0a\x20\x20img.gopher\x20{\x0a\x20\x20\x20\x20display:\x20none;\x0a\x20\x20}\x0a}\x0a\x0a@media\x20print\x20{\x0a\x20\x20pre\x20{\x0a\x20\x20\x20\x20background:\x20#fff;\x0a\x20\x20\x20\x20border:\x200.0625rem\x20solid\x20#bbb;\x0a\x20\x20\x20\x20white-space:\x20pre-wrap;\x0a\x20\x20\x20\x20page-break-inside:\x20avoid;\x0a\x20\x20}\x0a}\x0a",
 
-	"doc/mod.html": "<!--{\x0a\x20\x20\"Title\":\x20\"Go\x20Modules\x20Reference\",\x0a\x20\x20\"Subtitle\":\x20\"Version\x20of\x20Feb\x205,\x202019\",\x0a\x20\x20\"Path\":\x20\"/ref/mod\"\x0a}-->\x0a<!--\x20TODO(jayconrod):\x20change\x20anchors\x20to\x20header\x20id\x20attributes\x20either\x20during\x0amarkdown\x20rendering\x20or\x20as\x20HTML\x20postprocessing\x20step.\x20-->\x0a<!--\x20TODO(jayconrod):\x20use\x20<dfn>\x20tags\x20where\x20meaningful.\x0aCurrently,\x20*term*\x20is\x20used\x20instead,\x20which\x20renders\x20to\x20<em>term</em>.\x20-->\x0a<p><a\x20id=\"introduction\"></a></p>\x0a<h2>Introduction</h2>\x0a<p><a\x20id=\"modules-overview\"></a></p>\x0a<h2>Modules,\x20packages,\x20and\x20versions</h2>\x0a<p>A\x20<a\x20href=\"#glos-module\"><em>module</em></a>\x20is\x20a\x20collection\x20of\x20packages\x20that\x20are\x20released,\x0aversioned,\x20and\x20distributed\x20together.\x20A\x20module\x20is\x20identified\x20by\x20a\x20<a\x20href=\"#glos-module-path\"><em>module\x0apath</em></a>,\x20which\x20is\x20declared\x20in\x20a\x20<a\x20href=\"#go.mod-files\"><code>go.mod</code>\x0afile</a>,\x20together\x20with\x20information\x20about\x20the\x20module's\x0adependencies.\x20The\x20<a\x20href=\"#glos-module-root-directory\"><em>module\x20root\x20directory</em></a>\x20is\x20the\x0adirectory\x20that\x20contains\x20the\x20<code>go.mod</code>\x20file.\x20The\x20<a\x20href=\"#glos-main-module\"><em>main\x0amodule</em></a>\x20is\x20the\x20module\x20containing\x20the\x20directory\x20where\x20the\x0a<code>go</code>\x20command\x20is\x20invoked.</p>\x0a<p>Each\x20<a\x20href=\"#glos-package\"><em>package</em></a>\x20within\x20a\x20module\x20is\x20a\x20collection\x20of\x20source\x20files\x0ain\x20the\x20same\x20directory\x20that\x20are\x20compiled\x20together.\x20A\x20<a\x20href=\"#glos-package-path\"><em>package\x0apath</em></a>\x20is\x20the\x20module\x20path\x20joined\x20with\x20the\x20subdirectory\x0acontaining\x20the\x20package\x20(relative\x20to\x20the\x20module\x20root).\x20For\x20example,\x20the\x20module\x0a<code>&quot;golang.org/x/net&quot;</code>\x20contains\x20a\x20package\x20in\x20the\x20directory\x20<code>&quot;html&quot;</code>.\x20That\x0apackage's\x20path\x20is\x20<code>&quot;golang.org/x/net/html&quot;</code>.</p>\x0a<p><a\x20id=\"module-path\"></a></p>\x0a<h3>Module\x20paths</h3>\x0a<p>A\x20<a\x20href=\"#glos-module-path\"><em>module\x20path</em></a>\x20is\x20the\x20canonical\x20name\x20for\x20a\x20module,\x0adeclared\x20with\x20the\x20<a\x20href=\"#go.mod-module\"><code>module</code>\x20directive</a>\x20in\x20the\x20module's\x0a<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20file</a>.\x20A\x20module's\x20path\x20is\x20the\x20prefix\x20for\x20package\x0apaths\x20within\x20the\x20module.</p>\x0a<p>A\x20module\x20path\x20should\x20describe\x20both\x20what\x20the\x20module\x20does\x20and\x20where\x20to\x20find\x20it.\x0aTypically,\x20a\x20module\x20path\x20consists\x20of\x20a\x20repository\x20root\x20path,\x20a\x20directory\x20within\x0athe\x20repository\x20(usually\x20empty),\x20and\x20a\x20major\x20version\x20suffix\x20(only\x20for\x20major\x0aversion\x202\x20or\x20higher).</p>\x0a<ul>\x0a<li>The\x20<dfn>repository\x20root\x20path</dfn>\x20is\x20the\x20portion\x20of\x20the\x20module\x20path\x20that\x0acorresponds\x20to\x20the\x20root\x20directory\x20of\x20the\x20version\x20control\x20repository\x20where\x20the\x0amodule\x20is\x20developed.\x20Most\x20modules\x20are\x20defined\x20in\x20their\x20repository's\x20root\x0adirectory,\x20so\x20this\x20is\x20usually\x20the\x20entire\x20path.\x20For\x20example,\x0a<code>golang.org/x/net</code>\x20is\x20the\x20repository\x20root\x20path\x20for\x20the\x20module\x20of\x20the\x20same\x0aname.\x20See\x20<a\x20href=\"#vcs-find\">Finding\x20a\x20repository\x20for\x20a\x20module\x20path</a>\x20for\x20information\x0aon\x20how\x20the\x20<code>go</code>\x20command\x20locates\x20a\x20repository\x20using\x20HTTP\x20requests\x20derived\x0afrom\x20a\x20module\x20path.</li>\x0a<li>If\x20the\x20module\x20is\x20not\x20defined\x20in\x20the\x20repository's\x20root\x20directory,\x20the\x0a<dfn>module\x20subdirectory</dfn>\x20is\x20the\x20part\x20of\x20the\x20module\x20path\x20that\x20names\x20the\x0adirectory,\x20not\x20including\x20the\x20major\x20version\x20suffix.\x20This\x20also\x20serves\x20as\x20a\x0aprefix\x20for\x20semantic\x20version\x20tags.\x20For\x20example,\x20the\x20module\x0a<code>golang.org/x/tools/gopls</code>\x20is\x20in\x20the\x20<code>gopls</code>\x20subdirectory\x20of\x20the\x20repository\x0awith\x20root\x20path\x20<code>golang.org/x/tools</code>,\x20so\x20it\x20has\x20the\x20module\x20subdirectory\x0a<code>gopls</code>.\x20See\x20<a\x20href=\"#vcs-version\">Mapping\x20versions\x20to\x20commits</a>\x20and\x20<a\x20href=\"#vcs-dir\">Module\x0adirectories\x20within\x20a\x20repository</a>.</li>\x0a<li>If\x20the\x20module\x20is\x20released\x20at\x20major\x20version\x202\x20or\x20higher,\x20the\x20module\x20path\x20must\x0aend\x20with\x20a\x20<a\x20href=\"#major-version-suffixes\"><em>major\x20version\x20suffix</em></a>\x20like\x0a<code>/v2</code>.\x20This\x20may\x20or\x20may\x20not\x20be\x20part\x20of\x20the\x20subdirectory\x20name.\x20For\x20example,\x20the\x0amodule\x20with\x20path\x20<code>golang.org/x/repo/sub/v2</code>\x20could\x20be\x20in\x20the\x20<code>/sub</code>\x20or\x0a<code>/sub/v2</code>\x20subdirectory\x20of\x20the\x20repository\x20<code>golang.org/x/repo</code>.</li>\x0a</ul>\x0a<p>If\x20a\x20module\x20might\x20be\x20depended\x20on\x20by\x20other\x20modules,\x20these\x20rules\x20must\x20be\x20followed\x0aso\x20that\x20the\x20<code>go</code>\x20command\x20can\x20find\x20and\x20download\x20the\x20module.\x20There\x20are\x20also\x0aseveral\x20<a\x20href=\"#go.mod-ident\">lexical\x20restrictions</a>\x20on\x20characters\x20allowed\x20in\x0amodule\x20paths.</p>\x0a<p><a\x20id=\"versions\"></a></p>\x0a<h3>Versions</h3>\x0a<p>A\x20<a\x20href=\"#glos-version\"><em>version</em></a>\x20identifies\x20an\x20immutable\x20snapshot\x20of\x20a\x20module,\x20which\x0amay\x20be\x20either\x20a\x20<a\x20href=\"#glos-release-version\">release</a>\x20or\x20a\x0a<a\x20href=\"#glos-pre-release-version\">pre-release</a>.\x20Each\x20version\x20starts\x20with\x20the\x20letter\x0a<code>v</code>,\x20followed\x20by\x20a\x20semantic\x20version.\x20See\x20<a\x20href=\"https://semver.org/spec/v2.0.0.html\">Semantic\x20Versioning\x0a2.0.0</a>\x20for\x20details\x20on\x20how\x20versions\x20are\x0aformatted,\x20interpreted,\x20and\x20compared.</p>\x0a<p>To\x20summarize,\x20a\x20semantic\x20version\x20consists\x20of\x20three\x20non-negative\x20integers\x20(the\x0amajor,\x20minor,\x20and\x20patch\x20versions,\x20from\x20left\x20to\x20right)\x20separated\x20by\x20dots.\x20The\x0apatch\x20version\x20may\x20be\x20followed\x20by\x20an\x20optional\x20pre-release\x20string\x20starting\x20with\x20a\x0ahyphen.\x20The\x20pre-release\x20string\x20or\x20patch\x20version\x20may\x20be\x20followed\x20by\x20a\x20build\x0ametadata\x20string\x20starting\x20with\x20a\x20plus.\x20For\x20example,\x20<code>v0.0.0</code>,\x20<code>v1.12.134</code>,\x0a<code>v8.0.5-pre</code>,\x20and\x20<code>v2.0.9+meta</code>\x20are\x20valid\x20versions.</p>\x0a<p>Each\x20part\x20of\x20a\x20version\x20indicates\x20whether\x20the\x20version\x20is\x20stable\x20and\x20whether\x20it\x20is\x0acompatible\x20with\x20previous\x20versions.</p>\x0a<ul>\x0a<li>The\x20<a\x20href=\"#glos-major-version\">major\x20version</a>\x20must\x20be\x20incremented\x20and\x20the\x20minor\x0aand\x20patch\x20versions\x20must\x20be\x20set\x20to\x20zero\x20after\x20a\x20backwards\x20incompatible\x20change\x0ais\x20made\x20to\x20the\x20module's\x20public\x20interface\x20or\x20documented\x20functionality,\x20for\x0aexample,\x20after\x20a\x20package\x20is\x20removed.</li>\x0a<li>The\x20<a\x20href=\"#glos-minor-version\">minor\x20version</a>\x20must\x20be\x20incremented\x20and\x20the\x20patch\x0aversion\x20set\x20to\x20zero\x20after\x20a\x20backwards\x20compatible\x20change,\x20for\x20example,\x20after\x20a\x0anew\x20function\x20is\x20added.</li>\x0a<li>The\x20<a\x20href=\"#glos-patch-version\">patch\x20version</a>\x20must\x20be\x20incremented\x20after\x20a\x20change\x0athat\x20does\x20not\x20affect\x20the\x20module's\x20public\x20interface,\x20such\x20as\x20a\x20bug\x20fix\x20or\x0aoptimization.</li>\x0a<li>The\x20pre-release\x20suffix\x20indicates\x20a\x20version\x20is\x20a\x0a<a\x20href=\"#glos-pre-release-version\">pre-release</a>.\x20Pre-release\x20versions\x20sort\x20before\x0athe\x20corresponding\x20release\x20versions.\x20For\x20example,\x20<code>v1.2.3-pre</code>\x20comes\x20before\x0a<code>v1.2.3</code>.</li>\x0a<li>The\x20build\x20metadata\x20suffix\x20is\x20ignored\x20for\x20the\x20purpose\x20of\x20comparing\x20versions.\x0aTags\x20with\x20build\x20metadata\x20are\x20ignored\x20in\x20version\x20control\x20repositories,\x20but\x0abuild\x20metadata\x20is\x20preserved\x20in\x20versions\x20specified\x20in\x20<code>go.mod</code>\x20files.\x20The\x0asuffix\x20<code>+incompatible</code>\x20denotes\x20a\x20version\x20released\x20before\x20migrating\x20to\x20modules\x0aversion\x20major\x20version\x202\x20or\x20later\x20(see\x20<a\x20href=\"#non-module-compat\">Compatibility\x20with\x20non-module\x0arepositories</a>.</li>\x0a</ul>\x0a<p>A\x20version\x20is\x20considered\x20unstable\x20if\x20its\x20major\x20version\x20is\x200\x20or\x20it\x20has\x20a\x0apre-release\x20suffix.\x20Unstable\x20versions\x20are\x20not\x20subject\x20to\x20compatibility\x0arequirements.\x20For\x20example,\x20<code>v0.2.0</code>\x20may\x20not\x20be\x20compatible\x20with\x20<code>v0.1.0</code>,\x20and\x0a<code>v1.5.0-beta</code>\x20may\x20not\x20be\x20compatible\x20with\x20<code>v1.5.0</code>.</p>\x0a<p>Go\x20may\x20access\x20modules\x20in\x20version\x20control\x20systems\x20using\x20tags,\x20branches,\x20or\x0arevisions\x20that\x20don't\x20follow\x20these\x20conventions.\x20However,\x20within\x20the\x20main\x20module,\x0athe\x20<code>go</code>\x20command\x20will\x20automatically\x20convert\x20revision\x20names\x20that\x20don't\x20follow\x0athis\x20standard\x20into\x20canonical\x20versions.\x20The\x20<code>go</code>\x20command\x20will\x20also\x20remove\x20build\x0ametadata\x20suffixes\x20(except\x20for\x20<code>+incompatible</code>)\x20as\x20part\x20of\x20this\x20process.\x20This\x20may\x0aresult\x20in\x20a\x20<a\x20href=\"#glos-pseudo-version\"><em>pseudo-version</em></a>,\x20a\x20pre-release\x20version\x20that\x0aencodes\x20a\x20revision\x20identifier\x20(such\x20as\x20a\x20Git\x20commit\x20hash)\x20and\x20a\x20timestamp\x20from\x20a\x0aversion\x20control\x20system.\x20For\x20example,\x20the\x20command\x20<code>go\x20get\x20-d\x20golang.org/x/net@daa7c041</code>\x20will\x20convert\x20the\x20commit\x20hash\x20<code>daa7c041</code>\x20into\x20the\x0apseudo-version\x20<code>v0.0.0-20191109021931-daa7c04131f5</code>.\x20Canonical\x20versions\x20are\x0arequired\x20outside\x20the\x20main\x20module,\x20and\x20the\x20<code>go</code>\x20command\x20will\x20report\x20an\x20error\x20if\x20a\x0anon-canonical\x20version\x20like\x20<code>master</code>\x20appears\x20in\x20a\x20<code>go.mod</code>\x20file.</p>\x0a<p><a\x20id=\"pseudo-versions\"></a></p>\x0a<h3>Pseudo-versions</h3>\x0a<p>A\x20<dfn>pseudo-version</dfn>\x20is\x20a\x20specially\x20formatted\x0a<a\x20href=\"#glos-pre-release-version\">pre-release</a>\x20<a\x20href=\"#glos-version\">version</a>\x20that\x20encodes\x0ainformation\x20about\x20a\x20specific\x20revision\x20in\x20a\x20version\x20control\x20repository.\x20For\x0aexample,\x20<code>v0.0.0-20191109021931-daa7c04131f5</code>\x20is\x20a\x20pseudo-version.</p>\x0a<p>Pseudo-versions\x20may\x20refer\x20to\x20revisions\x20for\x20which\x20no\x20<a\x20href=\"#glos-semantic-version-tag\">semantic\x20version\x0atags</a>\x20are\x20available.\x20They\x20may\x20be\x20used\x20to\x20test\x0acommits\x20before\x20creating\x20version\x20tags,\x20for\x20example,\x20on\x20a\x20development\x20branch.</p>\x0a<p>Each\x20pseudo-version\x20has\x20three\x20parts:</p>\x0a<ul>\x0a<li>A\x20base\x20version\x20prefix\x20(<code>vX.0.0</code>\x20or\x20<code>vX.Y.Z-0</code>),\x20which\x20is\x20either\x20derived\x20from\x20a\x0asemantic\x20version\x20tag\x20that\x20precedes\x20the\x20revision\x20or\x20<code>vX.0.0</code>\x20if\x20there\x20is\x20no\x0asuch\x20tag.</li>\x0a<li>A\x20timestamp\x20(<code>yymmddhhmmss</code>),\x20which\x20is\x20the\x20UTC\x20time\x20the\x20revision\x20was\x20created.\x0aIn\x20Git,\x20this\x20is\x20the\x20commit\x20time,\x20not\x20the\x20author\x20time.</li>\x0a<li>A\x20revision\x20identifier\x20(<code>abcdefabcdef</code>),\x20which\x20is\x20a\x2012-character\x20prefix\x20of\x20the\x0acommit\x20hash,\x20or\x20in\x20Subversion,\x20a\x20zero-padded\x20revision\x20number.</li>\x0a</ul>\x0a<p>Each\x20pseudo-version\x20may\x20be\x20in\x20one\x20of\x20three\x20forms,\x20depending\x20on\x20the\x20base\x20version.\x0aThese\x20forms\x20ensure\x20that\x20a\x20pseudo-version\x20compares\x20higher\x20than\x20its\x20base\x20version,\x0abut\x20lower\x20than\x20the\x20next\x20tagged\x20version.</p>\x0a<ul>\x0a<li><code>vX.0.0-yyyymmddhhmmss-abcdefabcdef</code>\x20is\x20used\x20when\x20there\x20is\x20no\x20known\x20base\x0aversion.\x20As\x20with\x20all\x20versions,\x20the\x20major\x20version\x20<code>X</code>\x20must\x20match\x20the\x20module's\x0a<a\x20href=\"#glos-major-version-suffix\">major\x20version\x20suffix</a>.</li>\x0a<li><code>vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef</code>\x20is\x20used\x20when\x20the\x20base\x20version\x20is\x0aa\x20pre-release\x20version\x20like\x20<code>vX.Y.Z-pre</code>.</li>\x0a<li><code>vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef</code>\x20is\x20used\x20when\x20the\x20base\x20version\x20is\x0aa\x20release\x20version\x20like\x20<code>vX.Y.Z</code>.\x20For\x20example,\x20if\x20the\x20base\x20version\x20is\x0a<code>v1.2.3</code>,\x20a\x20pseudo-version\x20might\x20be\x20<code>v1.2.4-0.20191109021931-daa7c04131f5</code>.</li>\x0a</ul>\x0a<p>More\x20than\x20one\x20pseudo-version\x20may\x20refer\x20to\x20the\x20same\x20commit\x20by\x20using\x20different\x0abase\x20versions.\x20This\x20happens\x20naturally\x20when\x20a\x20lower\x20version\x20is\x20tagged\x20after\x20a\x0apseudo-version\x20is\x20written.</p>\x0a<p>These\x20forms\x20give\x20pseudo-versions\x20two\x20useful\x20properties:</p>\x0a<ul>\x0a<li>Pseudo-versions\x20with\x20known\x20base\x20versions\x20sort\x20higher\x20than\x20those\x20versions\x20but\x0alower\x20than\x20other\x20pre-release\x20for\x20later\x20versions.</li>\x0a<li>Pseudo-versions\x20with\x20the\x20same\x20base\x20version\x20prefix\x20sort\x20chronologically.</li>\x0a</ul>\x0a<p>The\x20<code>go</code>\x20command\x20performs\x20several\x20checks\x20to\x20ensure\x20that\x20module\x20authors\x20have\x0acontrol\x20over\x20how\x20pseudo-versions\x20are\x20compared\x20with\x20other\x20versions\x20and\x20that\x0apseudo-versions\x20refer\x20to\x20revisions\x20that\x20are\x20actually\x20part\x20of\x20a\x20module's\x0acommit\x20history.</p>\x0a<ul>\x0a<li>If\x20a\x20base\x20version\x20is\x20specified,\x20there\x20must\x20be\x20a\x20corresponding\x20semantic\x20version\x0atag\x20that\x20is\x20an\x20ancestor\x20of\x20the\x20revision\x20described\x20by\x20the\x20pseudo-version.\x20This\x0aprevents\x20developers\x20from\x20bypassing\x20<a\x20href=\"#glos-minimal-version-selection\">minimal\x20version\x0aselection</a>\x20using\x20a\x20pseudo-version\x20that\x0acompares\x20higher\x20than\x20all\x20tagged\x20versions\x20like\x0a<code>v1.999.999-99999999999999-daa7c04131f5</code>.</li>\x0a<li>The\x20timestamp\x20must\x20match\x20the\x20revision's\x20timestamp.\x20This\x20prevents\x20attackers\x0afrom\x20flooding\x20<a\x20href=\"#glos-module-proxy\">module\x20proxies</a>\x20with\x20an\x20unbounded\x20number\x0aof\x20otherwise\x20identical\x20pseudo-versions.\x20This\x20also\x20prevents\x20module\x20consumers\x0afrom\x20changing\x20the\x20relative\x20ordering\x20of\x20versions.</li>\x0a<li>The\x20revision\x20must\x20be\x20an\x20ancestor\x20of\x20one\x20of\x20the\x20module\x20repository's\x20branches\x20or\x0atags.\x20This\x20prevents\x20attackers\x20from\x20referring\x20to\x20unapproved\x20changes\x20or\x20pull\x0arequests.</li>\x0a</ul>\x0a<p>Pseudo-versions\x20never\x20need\x20to\x20be\x20typed\x20by\x20hand.\x20Many\x20commands\x20accept\x0aa\x20commit\x20hash\x20or\x20a\x20branch\x20name\x20and\x20will\x20translate\x20it\x20into\x20a\x20pseudo-version\x0a(or\x20tagged\x20version\x20if\x20available)\x20automatically.\x20For\x20example:</p>\x0a<pre><code>go\x20get\x20-d\x20example.com/mod@master\x0ago\x20list\x20-m\x20-json\x20example.com/mod@abcd1234\x0a</code></pre>\x0a<p><a\x20id=\"major-version-suffixes\"></a></p>\x0a<h3>Major\x20version\x20suffixes</h3>\x0a<p>Starting\x20with\x20major\x20version\x202,\x20module\x20paths\x20must\x20have\x20a\x20<a\x20href=\"#glos-major-version-suffix\"><em>major\x20version\x0asuffix</em></a>\x20like\x20<code>/v2</code>\x20that\x20matches\x20the\x20major\x0aversion.\x20For\x20example,\x20if\x20a\x20module\x20has\x20the\x20path\x20<code>example.com/mod</code>\x20at\x20<code>v1.0.0</code>,\x20it\x0amust\x20have\x20the\x20path\x20<code>example.com/mod/v2</code>\x20at\x20version\x20<code>v2.0.0</code>.</p>\x0a<p>Major\x20version\x20suffixes\x20implement\x20the\x20<a\x20href=\"https://research.swtch.com/vgo-import\"><em>import\x20compatibility\x0arule</em></a>:</p>\x0a<blockquote>\x0a<p>If\x20an\x20old\x20package\x20and\x20a\x20new\x20package\x20have\x20the\x20same\x20import\x20path,\x0athe\x20new\x20package\x20must\x20be\x20backwards\x20compatible\x20with\x20the\x20old\x20package.</p>\x0a</blockquote>\x0a<p>By\x20definition,\x20packages\x20in\x20a\x20new\x20major\x20version\x20of\x20a\x20module\x20are\x20not\x20backwards\x0acompatible\x20with\x20the\x20corresponding\x20packages\x20in\x20the\x20previous\x20major\x20version.\x0aConsequently,\x20starting\x20with\x20<code>v2</code>,\x20packages\x20need\x20new\x20import\x20paths.\x20This\x20is\x0aaccomplished\x20by\x20adding\x20a\x20major\x20version\x20suffix\x20to\x20the\x20module\x20path.\x20Since\x20the\x0amodule\x20path\x20is\x20a\x20prefix\x20of\x20the\x20import\x20path\x20for\x20each\x20package\x20within\x20the\x20module,\x0aadding\x20the\x20major\x20version\x20suffix\x20to\x20the\x20module\x20path\x20provides\x20a\x20distinct\x20import\x0apath\x20for\x20each\x20incompatible\x20version.</p>\x0a<p>Major\x20version\x20suffixes\x20are\x20not\x20allowed\x20at\x20major\x20versions\x20<code>v0</code>\x20or\x20<code>v1</code>.\x20There\x20is\x0ano\x20need\x20to\x20change\x20the\x20module\x20path\x20between\x20<code>v0</code>\x20and\x20<code>v1</code>\x20because\x20<code>v0</code>\x20versions\x0aare\x20unstable\x20and\x20have\x20no\x20compatibility\x20guarantee.\x20Additionally,\x20for\x20most\x0amodules,\x20<code>v1</code>\x20is\x20backwards\x20compatible\x20with\x20the\x20last\x20<code>v0</code>\x20version;\x20a\x20<code>v1</code>\x20version\x0aacts\x20as\x20a\x20commitment\x20to\x20compatibility,\x20rather\x20than\x20an\x20indication\x20of\x0aincompatible\x20changes\x20compared\x20with\x20<code>v0</code>.</p>\x0a<p>As\x20a\x20special\x20case,\x20modules\x20paths\x20starting\x20with\x20<code>gopkg.in/</code>\x20must\x20always\x20have\x20a\x0amajor\x20version\x20suffix,\x20even\x20at\x20<code>v0</code>\x20and\x20<code>v1</code>.\x20The\x20suffix\x20must\x20start\x20with\x20a\x20dot\x0arather\x20than\x20a\x20slash\x20(for\x20example,\x20<code>gopkg.in/yaml.v2</code>).</p>\x0a<p>Major\x20version\x20suffixes\x20let\x20multiple\x20major\x20versions\x20of\x20a\x20module\x20coexist\x20in\x20the\x0asame\x20build.\x20This\x20may\x20be\x20necessary\x20due\x20to\x20a\x20<a\x20href=\"https://research.swtch.com/vgo-import#dependency_story\">diamond\x20dependency\x0aproblem</a>.\x20Ordinarily,\x20if\x0aa\x20module\x20is\x20required\x20at\x20two\x20different\x20versions\x20by\x20transitive\x20dependencies,\x20the\x0ahigher\x20version\x20will\x20be\x20used.\x20However,\x20if\x20the\x20two\x20versions\x20are\x20incompatible,\x0aneither\x20version\x20will\x20satisfy\x20all\x20clients.\x20Since\x20incompatible\x20versions\x20must\x20have\x0adifferent\x20major\x20version\x20numbers,\x20they\x20must\x20also\x20have\x20different\x20module\x20paths\x20due\x0ato\x20major\x20version\x20suffixes.\x20This\x20resolves\x20the\x20conflict:\x20modules\x20with\x20distinct\x0asuffixes\x20are\x20treated\x20as\x20separate\x20modules,\x20and\x20their\x20packages\xe2\x80\x94even\x20packages\x20in\x0asame\x20subdirectory\x20relative\x20to\x20their\x20module\x20roots\xe2\x80\x94are\x20distinct.</p>\x0a<p>Many\x20Go\x20projects\x20released\x20versions\x20at\x20<code>v2</code>\x20or\x20higher\x20without\x20using\x20a\x20major\x0aversion\x20suffix\x20before\x20migrating\x20to\x20modules\x20(perhaps\x20before\x20modules\x20were\x20even\x0aintroduced).\x20These\x20versions\x20are\x20annotated\x20with\x20a\x20<code>+incompatible</code>\x20build\x20tag\x20(for\x0aexample,\x20<code>v2.0.0+incompatible</code>).\x20See\x20<a\x20href=\"#non-module-compat\">Compatibility\x20with\x20non-module\x0arepositories</a>\x20for\x20more\x20information.</p>\x0a<p><a\x20id=\"resolve-pkg-mod\"></a></p>\x0a<h3>Resolving\x20a\x20package\x20to\x20a\x20module</h3>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20loads\x20a\x20package\x20using\x20a\x20<a\x20href=\"#glos-package-path\">package\x0apath</a>,\x20it\x20needs\x20to\x20determine\x20which\x20module\x20provides\x20the\x0apackage.</p>\x0a<p>The\x20<code>go</code>\x20command\x20starts\x20by\x20searching\x20the\x20<a\x20href=\"#glos-build-list\">build\x20list</a>\x20for\x0amodules\x20with\x20paths\x20that\x20are\x20prefixes\x20of\x20the\x20package\x20path.\x20For\x20example,\x20if\x20the\x0apackage\x20<code>example.com/a/b</code>\x20is\x20imported,\x20and\x20the\x20module\x20<code>example.com/a</code>\x20is\x20in\x20the\x0abuild\x20list,\x20the\x20<code>go</code>\x20command\x20will\x20check\x20whether\x20<code>example.com/a</code>\x20contains\x20the\x0apackage,\x20in\x20the\x20directory\x20<code>b</code>.\x20At\x20least\x20one\x20file\x20with\x20the\x20<code>.go</code>\x20extension\x20must\x0abe\x20present\x20in\x20a\x20directory\x20for\x20it\x20to\x20be\x20considered\x20a\x20package.\x20<a\x20href=\"/pkg/go/build/#hdr-Build_Constraints\">Build\x0aconstraints</a>\x20are\x20not\x20applied\x20for\x20this\x0apurpose.\x20If\x20exactly\x20one\x20module\x20in\x20the\x20build\x20list\x20provides\x20the\x20package,\x20that\x0amodule\x20is\x20used.\x20If\x20two\x20or\x20more\x20modules\x20provide\x20the\x20package,\x20an\x20error\x20is\x0areported.\x20If\x20no\x20modules\x20provide\x20the\x20package,\x20the\x20<code>go</code>\x20command\x20will\x20attempt\x20to\x0afind\x20a\x20new\x20module\x20(unless\x20the\x20flags\x20<code>-mod=readonly</code>\x20or\x20<code>-mod=vendor</code>\x20are\x20used,\x0ain\x20which\x20case,\x20an\x20error\x20is\x20reported).</p>\x0a<!--\x20NOTE(golang.org/issue/27899):\x20the\x20go\x20command\x20reports\x20an\x20error\x20when\x20two\x0aor\x20more\x20modules\x20provide\x20a\x20package\x20with\x20the\x20same\x20path\x20as\x20above.\x20In\x20the\x20future,\x0awe\x20may\x20try\x20to\x20upgrade\x20one\x20(or\x20all)\x20of\x20the\x20colliding\x20modules.\x0a-->\x0a<p>When\x20the\x20<code>go</code>\x20command\x20looks\x20up\x20a\x20new\x20module\x20for\x20a\x20package\x20path,\x20it\x20checks\x20the\x0a<code>GOPROXY</code>\x20environment\x20variable,\x20which\x20is\x20a\x20comma-separated\x20list\x20of\x20proxy\x20URLs\x20or\x0athe\x20keywords\x20<code>direct</code>\x20or\x20<code>off</code>.\x20A\x20proxy\x20URL\x20indicates\x20the\x20<code>go</code>\x20command\x20should\x0acontact\x20a\x20<a\x20href=\"#glos-module-proxy\">module\x20proxy</a>\x20using\x20the\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x0aprotocol</a>.\x20<code>direct</code>\x20indicates\x20that\x20the\x20<code>go</code>\x20command\x20should\x0a<a\x20href=\"#vcs\">communicate\x20with\x20a\x20version\x20control\x20system</a>.\x20<code>off</code>\x20indicates\x20that\x20no\x0acommunication\x20should\x20be\x20attempted.\x20The\x20<code>GOPRIVATE</code>\x20and\x20<code>GONOPROXY</code>\x20<a\x20href=\"#environment-variables\">environment\x0avariables</a>\x20can\x20also\x20be\x20used\x20to\x20control\x20this\x20behavior.</p>\x0a<p>For\x20each\x20entry\x20in\x20the\x20<code>GOPROXY</code>\x20list,\x20the\x20<code>go</code>\x20command\x20requests\x20the\x20latest\x0aversion\x20of\x20each\x20module\x20path\x20that\x20might\x20provide\x20the\x20package\x20(that\x20is,\x20each\x20prefix\x0aof\x20the\x20package\x20path).\x20For\x20each\x20successfully\x20requested\x20module\x20path,\x20the\x20<code>go</code>\x0acommand\x20will\x20download\x20the\x20module\x20at\x20the\x20latest\x20version\x20and\x20check\x20whether\x20the\x0amodule\x20contains\x20the\x20requested\x20package.\x20If\x20one\x20or\x20more\x20modules\x20contain\x20the\x0arequested\x20package,\x20the\x20module\x20with\x20the\x20longest\x20path\x20is\x20used.\x20If\x20one\x20or\x20more\x0amodules\x20are\x20found\x20but\x20none\x20contain\x20the\x20requested\x20package,\x20an\x20error\x20is\x0areported.\x20If\x20no\x20modules\x20are\x20found,\x20the\x20<code>go</code>\x20command\x20tries\x20the\x20next\x20entry\x20in\x20the\x0a<code>GOPROXY</code>\x20list.\x20If\x20no\x20entries\x20are\x20left,\x20an\x20error\x20is\x20reported.</p>\x0a<p>For\x20example,\x20suppose\x20the\x20<code>go</code>\x20command\x20is\x20looking\x20for\x20a\x20module\x20that\x20provides\x20the\x0apackage\x20<code>golang.org/x/net/html</code>,\x20and\x20<code>GOPROXY</code>\x20is\x20set\x20to\x0a<code>https://corp.example.com,https://proxy.golang.org</code>.\x20The\x20<code>go</code>\x20command\x20may\x20make\x0athe\x20following\x20requests:</p>\x0a<ul>\x0a<li>To\x20<code>https://corp.example.com/</code>\x20(in\x20parallel):\x0a<ul>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x/net/html</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x/net</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org</code></li>\x0a</ul>\x0a</li>\x0a<li>To\x20<code>https://proxy.golang.org/</code>,\x20if\x20all\x20requests\x20to\x20<code>https://corp.example.com/</code>\x0ahave\x20failed\x20with\x20404\x20or\x20410:\x0a<ul>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x/net/html</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x/net</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org</code></li>\x0a</ul>\x0a</li>\x0a</ul>\x0a<p>After\x20a\x20suitable\x20module\x20has\x20been\x20found,\x20the\x20<code>go</code>\x20command\x20will\x20add\x20a\x20new\x0a<a\x20href=\"#go.mod-require\">requirement</a>\x20with\x20the\x20new\x20module's\x20path\x20and\x20version\x20to\x20the\x0amain\x20module's\x20<code>go.mod</code>\x20file.\x20This\x20ensures\x20that\x20when\x20the\x20same\x20package\x20is\x20loaded\x0ain\x20the\x20future,\x20the\x20same\x20module\x20will\x20be\x20used\x20at\x20the\x20same\x20version.\x20If\x20the\x20resolved\x0apackage\x20is\x20not\x20imported\x20by\x20a\x20package\x20in\x20the\x20main\x20module,\x20the\x20new\x20requirement\x0awill\x20have\x20an\x20<code>//\x20indirect</code>\x20comment.</p>\x0a<p><a\x20id=\"go.mod-files\"></a></p>\x0a<h2><code>go.mod</code>\x20files</h2>\x0a<p>A\x20module\x20is\x20defined\x20by\x20a\x20UTF-8\x20encoded\x20text\x20file\x20named\x20<code>go.mod</code>\x20in\x20its\x20root\x0adirectory.\x20The\x20<code>go.mod</code>\x20file\x20is\x20line-oriented.\x20Each\x20line\x20holds\x20a\x20single\x0adirective,\x20made\x20up\x20of\x20a\x20keyword\x20followed\x20by\x20arguments.\x20For\x20example:</p>\x0a<pre><code>module\x20example.com/my/thing\x0a\x0ago\x201.12\x0a\x0arequire\x20example.com/other/thing\x20v1.0.2\x0arequire\x20example.com/new/thing/v2\x20v2.3.4\x0aexclude\x20example.com/old/thing\x20v1.2.3\x0areplace\x20example.com/bad/thing\x20v1.4.5\x20=&gt;\x20example.com/good/thing\x20v1.4.5\x0a</code></pre>\x0a<p>The\x20leading\x20keyword\x20can\x20be\x20factored\x20out\x20of\x20adjacent\x20lines\x20to\x20create\x20a\x20block,\x0alike\x20in\x20Go\x20imports.</p>\x0a<pre><code>require\x20(\x0a\x20\x20\x20\x20example.com/new/thing/v2\x20v2.3.4\x0a\x20\x20\x20\x20example.com/old/thing\x20v1.2.3\x0a)\x0a</code></pre>\x0a<p>The\x20<code>go.mod</code>\x20file\x20is\x20designed\x20to\x20be\x20human\x20readable\x20and\x20machine\x20writable.\x20The\x0a<code>go</code>\x20command\x20provides\x20several\x20subcommands\x20that\x20change\x20<code>go.mod</code>\x20files.\x20For\x0aexample,\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20can\x20upgrade\x20or\x20downgrade\x20specific\x20dependencies.\x0aCommands\x20that\x20load\x20the\x20module\x20graph\x20will\x20<a\x20href=\"#go.mod-updates\">automatically\x20update</a>\x0a<code>go.mod</code>\x20when\x20needed.\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20edit</code></a>\x20can\x20perform\x20low-level\x20edits.\x0aThe\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/modfile?tab=doc\"><code>golang.org/x/mod/modfile</code></a>\x0apackage\x20can\x20be\x20used\x20by\x20Go\x20programs\x20to\x20make\x20the\x20same\x20changes\x20programmatically.</p>\x0a<p><a\x20id=\"go.mod-lexical\"></a></p>\x0a<h3>Lexical\x20elements</h3>\x0a<p>When\x20a\x20<code>go.mod</code>\x20file\x20is\x20parsed,\x20its\x20content\x20is\x20broken\x20into\x20a\x20sequence\x20of\x20tokens.\x0aThere\x20are\x20several\x20kinds\x20of\x20tokens:\x20whitespace,\x20comments,\x20punctuation,\x0akeywords,\x20identifiers,\x20and\x20strings.</p>\x0a<p><em>White\x20space</em>\x20consists\x20of\x20spaces\x20(U+0020),\x20tabs\x20(U+0009),\x20carriage\x20returns\x0a(U+000D),\x20and\x20newlines\x20(U+000A).\x20White\x20space\x20characters\x20other\x20than\x20newlines\x20have\x0ano\x20effect\x20except\x20to\x20separate\x20tokens\x20that\x20would\x20otherwise\x20be\x20combined.\x20Newlines\x0aare\x20significant\x20tokens.</p>\x0a<p><em>Comments</em>\x20start\x20with\x20<code>//</code>\x20and\x20run\x20to\x20the\x20end\x20of\x20a\x20line.\x20<code>/*\x20*/</code>\x20comments\x20are\x0anot\x20allowed.</p>\x0a<p><em>Punctuation</em>\x20tokens\x20include\x20<code>(</code>,\x20<code>)</code>,\x20and\x20<code>=&gt;</code>.</p>\x0a<p><em>Keywords</em>\x20distinguish\x20different\x20kinds\x20of\x20directives\x20in\x20a\x20<code>go.mod</code>\x20file.\x20Allowed\x0akeywords\x20are\x20<code>module</code>,\x20<code>go</code>,\x20<code>require</code>,\x20<code>replace</code>,\x20and\x20<code>exclude</code>.</p>\x0a<p><em>Identifiers</em>\x20are\x20sequences\x20of\x20non-whitespace\x20characters,\x20such\x20as\x20module\x20paths\x0aor\x20semantic\x20versions.</p>\x0a<p><em>Strings</em>\x20are\x20quoted\x20sequences\x20of\x20characters.\x20There\x20are\x20two\x20kinds\x20of\x20strings:\x0ainterpreted\x20strings\x20beginning\x20and\x20ending\x20with\x20quotation\x20marks\x20(<code>&quot;</code>,\x20U+0022)\x20and\x0araw\x20strings\x20beginning\x20and\x20ending\x20with\x20grave\x20accents\x20(<code>&lt;</code>,\x0aU+0060).\x20Interpreted\x20strings\x20may\x20contain\x20escape\x20sequences\x20consisting\x20of\x20a\x0abackslash\x20(<code>\\</code>,\x20U+005C)\x20followed\x20by\x20another\x20character.\x20An\x20escaped\x20quotation\x0amark\x20(<code>\\&quot;</code>)\x20does\x20not\x20terminate\x20an\x20interpreted\x20string.\x20The\x20unquoted\x20value\x0aof\x20an\x20interpreted\x20string\x20is\x20the\x20sequence\x20of\x20characters\x20between\x20quotation\x0amarks\x20with\x20each\x20escape\x20sequence\x20replaced\x20by\x20the\x20character\x20following\x20the\x0abackslash\x20(for\x20example,\x20<code>\\&quot;</code>\x20is\x20replaced\x20by\x20<code>&quot;</code>,\x20<code>\\n</code>\x20is\x20replaced\x20by\x20<code>n</code>).\x0aIn\x20contrast,\x20the\x20unquoted\x20value\x20of\x20a\x20raw\x20string\x20is\x20simply\x20the\x20sequence\x20of\x0acharacters\x20between\x20grave\x20accents;\x20backslashes\x20have\x20no\x20special\x20meaning\x20within\x0araw\x20strings.</p>\x0a<p>Identifiers\x20and\x20strings\x20are\x20interchangeable\x20in\x20the\x20<code>go.mod</code>\x20grammar.</p>\x0a<p><a\x20id=\"go.mod-ident\"></a></p>\x0a<h3>Module\x20paths\x20and\x20versions</h3>\x0a<p>Most\x20identifiers\x20and\x20strings\x20in\x20a\x20<code>go.mod</code>\x20file\x20are\x20either\x20module\x20paths\x20or\x0aversions.</p>\x0a<p>A\x20module\x20path\x20must\x20satisfy\x20the\x20following\x20requirements:</p>\x0a<ul>\x0a<li>The\x20path\x20must\x20consist\x20of\x20one\x20or\x20more\x20path\x20elements\x20separated\x20by\x20slashes\x0a(<code>/</code>,\x20U+002F).\x20It\x20must\x20not\x20begin\x20or\x20end\x20with\x20a\x20slash.</li>\x0a<li>Each\x20path\x20element\x20is\x20a\x20non-empty\x20string\x20made\x20of\x20up\x20ASCII\x20letters,\x20ASCII\x0adigits,\x20and\x20limited\x20ASCII\x20punctuation\x20(<code>+</code>,\x20<code>-</code>,\x20<code>.</code>,\x20<code>_</code>,\x20and\x20<code>~</code>).</li>\x0a<li>A\x20path\x20element\x20may\x20not\x20begin\x20or\x20end\x20with\x20a\x20dot\x20(<code>.</code>,\x20U+002E).</li>\x0a<li>The\x20element\x20prefix\x20up\x20to\x20the\x20first\x20dot\x20must\x20not\x20be\x20a\x20reserved\x20file\x20name\x20on\x0aWindows,\x20regardless\x20of\x20case\x20(<code>CON</code>,\x20<code>com1</code>,\x20<code>NuL</code>,\x20and\x20so\x20on).</li>\x0a</ul>\x0a<p>If\x20the\x20module\x20path\x20appears\x20in\x20a\x20<code>require</code>\x20directive\x20and\x20is\x20not\x20replaced,\x20or\x0aif\x20the\x20module\x20paths\x20appears\x20on\x20the\x20right\x20side\x20of\x20a\x20<code>replace</code>\x20directive,\x0athe\x20<code>go</code>\x20command\x20may\x20need\x20to\x20download\x20modules\x20with\x20that\x20path,\x20and\x20some\x0aadditional\x20requirements\x20must\x20be\x20satisfied.</p>\x0a<ul>\x0a<li>The\x20leading\x20path\x20element\x20(up\x20to\x20the\x20first\x20slash,\x20if\x20any),\x20by\x20convention\x20a\x0adomain\x20name,\x20must\x20contain\x20only\x20lower-case\x20ASCII\x20letters,\x20ASCII\x20digits,\x20dots\x0a(<code>.</code>,\x20U+002E),\x20and\x20dashes\x20(<code>-</code>,\x20U+002D);\x20it\x20must\x20contain\x20at\x20least\x20one\x20dot\x20and\x0acannot\x20start\x20with\x20a\x20dash.</li>\x0a<li>For\x20a\x20final\x20path\x20element\x20of\x20the\x20form\x20<code>/vN</code>\x20where\x20<code>N</code>\x20looks\x20numeric\x20(ASCII\x0adigits\x20and\x20dots),\x20<code>N</code>\x20must\x20not\x20begin\x20with\x20a\x20leading\x20zero,\x20must\x20not\x20be\x20<code>/v1</code>,\x0aand\x20must\x20not\x20contain\x20any\x20dots.\x0a<ul>\x0a<li>For\x20paths\x20beginning\x20with\x20<code>gopkg.in/</code>,\x20this\x20requirement\x20is\x20replaced\x20by\x20a\x0arequirement\x20that\x20the\x20path\x20follow\x20the\x20<a\x20href=\"https://gopkg.in\">gopkg.in</a>\x20service's\x0aconventions.</li>\x0a</ul>\x0a</li>\x0a</ul>\x0a<p>Versions\x20in\x20<code>go.mod</code>\x20files\x20may\x20be\x20<a\x20href=\"#glos-canonical-version\">canonical</a>\x20or\x0anon-canonical.</p>\x0a<p>A\x20canonical\x20version\x20starts\x20with\x20the\x20letter\x20<code>v</code>,\x20followed\x20by\x20a\x20semantic\x20version\x0afollowing\x20the\x20<a\x20href=\"https://semver.org/spec/v2.0.0.html\">Semantic\x20Versioning\x202.0.0</a>\x0aspecification.\x20See\x20<a\x20href=\"#versions\">Versions</a>\x20for\x20more\x20information.</p>\x0a<p>Most\x20other\x20identifiers\x20and\x20strings\x20may\x20be\x20used\x20as\x20non-canonical\x20versions,\x20though\x0athere\x20are\x20some\x20restrictions\x20to\x20avoid\x20problems\x20with\x20file\x20systems,\x20repositories,\x0aand\x20<a\x20href=\"#glos-module-proxy\">module\x20proxies</a>.\x20Non-canonical\x20versions\x20are\x20only\x0aallowed\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file.\x20The\x20<code>go</code>\x20command\x20will\x20attempt\x20to\x0areplace\x20each\x20non-canonical\x20version\x20with\x20an\x20equivalent\x20canonical\x20version\x20when\x20it\x0aautomatically\x20<a\x20href=\"#go.mod-updates\">updates</a>\x20the\x20<code>go.mod</code>\x20file.</p>\x0a<p>In\x20places\x20where\x20a\x20module\x20path\x20is\x20associated\x20with\x20a\x20verison\x20(as\x20in\x20<code>require</code>,\x0a<code>replace</code>,\x20and\x20<code>exclude</code>\x20directives),\x20the\x20final\x20path\x20element\x20must\x20be\x20consistent\x0awith\x20the\x20version.\x20See\x20<a\x20href=\"#major-version-suffixes\">Major\x20version\x20suffixes</a>.</p>\x0a<p><a\x20id=\"go.mod-grammar\"></a></p>\x0a<h3>Grammar</h3>\x0a<p><code>go.mod</code>\x20syntax\x20is\x20specified\x20below\x20using\x20Extended\x20Backus-Naur\x20Form\x20(EBNF).\x0aSee\x20the\x20<a\x20href=\"/ref/spec#Notation\">Notation\x20section\x20in\x20the\x20Go\x20Language\x20Specificiation</a>\x0afor\x20details\x20on\x20EBNF\x20syntax.</p>\x0a<pre><code>GoMod\x20=\x20{\x20Directive\x20}\x20.\x0aDirective\x20=\x20ModuleDirective\x20|\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20GoDirective\x20|\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20RequireDirective\x20|\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20ExcludeDirective\x20|\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20ReplaceDirective\x20.\x0a</code></pre>\x0a<p>Newlines,\x20identifiers,\x20and\x20strings\x20are\x20denoted\x20with\x20<code>newline</code>,\x20<code>ident</code>,\x20and\x0a<code>string</code>,\x20respectively.</p>\x0a<p>Module\x20paths\x20and\x20versions\x20are\x20denoted\x20with\x20<code>ModulePath</code>\x20and\x20<code>Version</code>.</p>\x0a<pre><code>ModulePath\x20=\x20ident\x20|\x20string\x20.\x20/*\x20see\x20restrictions\x20above\x20*/\x0aVersion\x20=\x20ident\x20|\x20string\x20.\x20\x20\x20\x20/*\x20see\x20restrictions\x20above\x20*/\x0a</code></pre>\x0a<p><a\x20id=\"go.mod-module\"></a></p>\x0a<h3><code>module</code>\x20directive</h3>\x0a<p>A\x20<code>module</code>\x20directive\x20defines\x20the\x20main\x20module's\x20<a\x20href=\"#glos-module-path\">path</a>.\x20A\x0a<code>go.mod</code>\x20file\x20must\x20contain\x20exactly\x20one\x20<code>module</code>\x20directive.</p>\x0a<pre><code>ModuleDirective\x20=\x20&quot;module&quot;\x20(\x20ModulePath\x20|\x20&quot;(&quot;\x20newline\x20ModulePath\x20newline\x20&quot;)&quot;\x20newline\x20.\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>module\x20golang.org/x/net\x0a</code></pre>\x0a<p><a\x20id=\"go.mod-go\"></a></p>\x0a<h3><code>go</code>\x20directive</h3>\x0a<p>A\x20<code>go</code>\x20directive\x20sets\x20the\x20expected\x20language\x20version\x20for\x20the\x20module.\x20The\x0aversion\x20must\x20be\x20a\x20valid\x20Go\x20release\x20version:\x20a\x20positive\x20integer\x20followed\x20by\x20a\x20dot\x0aand\x20a\x20non-negative\x20integer\x20(for\x20example,\x20<code>1.9</code>,\x20<code>1.14</code>).</p>\x0a<p>The\x20language\x20version\x20determines\x20which\x20language\x20features\x20are\x20available\x20when\x0acompiling\x20packages\x20in\x20the\x20module.\x20Language\x20features\x20present\x20in\x20that\x20version\x0awill\x20be\x20available\x20for\x20use.\x20Language\x20features\x20removed\x20in\x20earlier\x20versions,\x0aor\x20added\x20in\x20later\x20versions,\x20will\x20not\x20be\x20available.\x20The\x20language\x20version\x20does\x20not\x0aaffect\x20build\x20tags,\x20which\x20are\x20determined\x20by\x20the\x20Go\x20release\x20being\x20used.</p>\x0a<p>The\x20language\x20version\x20is\x20also\x20used\x20to\x20enable\x20features\x20in\x20the\x20<code>go</code>\x20command.\x20For\x0aexample,\x20automatic\x20<a\x20href=\"#vendoring\">vendoring</a>\x20may\x20be\x20enabled\x20with\x20a\x20<code>go</code>\x20version\x20of\x0a<code>1.14</code>\x20or\x20higher.</p>\x0a<p>A\x20<code>go.mod</code>\x20file\x20may\x20contain\x20at\x20most\x20one\x20<code>go</code>\x20directive.\x20Most\x20commands\x20will\x20add\x20a\x0a<code>go</code>\x20directive\x20with\x20the\x20current\x20Go\x20version\x20if\x20one\x20is\x20not\x20present.</p>\x0a<pre><code>GoDirective\x20=\x20&quot;go&quot;\x20GoVersion\x20newline\x20.\x0aGoVersion\x20=\x20string\x20|\x20ident\x20.\x20\x20/*\x20valid\x20release\x20version;\x20see\x20above\x20*/\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>go\x201.14\x0a</code></pre>\x0a<p><a\x20id=\"go.mod-require\"></a></p>\x0a<h3><code>require</code>\x20directive</h3>\x0a<p>A\x20<code>require</code>\x20directive\x20declares\x20a\x20minimum\x20required\x20version\x20of\x20a\x20given\x20module\x0adependency.\x20For\x20each\x20required\x20module\x20version,\x20the\x20<code>go</code>\x20command\x20loads\x20the\x0a<code>go.mod</code>\x20file\x20for\x20that\x20version\x20and\x20incorporates\x20the\x20requirements\x20from\x20that\x0afile.\x20Once\x20all\x20requirements\x20have\x20been\x20loaded,\x20the\x20<code>go</code>\x20command\x20resolves\x20them\x0ausing\x20<a\x20href=\"#minimal-version-selection\">minimal\x20version\x20selection\x20(MVS)</a>\x20to\x20produce\x0athe\x20<a\x20href=\"#glos-build-list\">build\x20list</a>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20automatically\x20adds\x20<code>//\x20indirect</code>\x20comments\x20for\x20some\x0arequirements.\x20An\x20<code>//\x20indirect</code>\x20comment\x20indicates\x20that\x20no\x20package\x20from\x20the\x0arequired\x20module\x20is\x20directly\x20imported\x20by\x20any\x20package\x20in\x20the\x20main\x20module.\x0aThe\x20<code>go</code>\x20command\x20adds\x20an\x20indirect\x20requirement\x20when\x20the\x20selected\x20version\x20of\x20a\x0amodule\x20is\x20higher\x20than\x20what\x20is\x20already\x20implied\x20(transitively)\x20by\x20the\x20main\x0amodule's\x20other\x20dependencies.\x20That\x20may\x20occur\x20because\x20of\x20an\x20explicit\x20upgrade\x0a(<code>go\x20get\x20-u</code>),\x20removal\x20of\x20some\x20other\x20dependency\x20that\x20previously\x20imposed\x20the\x0arequirement\x20(<code>go\x20mod\x20tidy</code>),\x20or\x20a\x20dependency\x20that\x20imports\x20a\x20package\x20without\x0aa\x20corresponding\x20requirement\x20in\x20its\x20own\x20<code>go.mod</code>\x20file\x20(such\x20as\x20a\x20dependency\x0athat\x20lacks\x20a\x20<code>go.mod</code>\x20file\x20altogether).</p>\x0a<pre><code>RequireDirective\x20=\x20&quot;require&quot;\x20(\x20RequireSpec\x20|\x20&quot;(&quot;\x20newline\x20{\x20RequireSpec\x20}\x20&quot;)&quot;\x20newline\x20)\x20.\x0aRequireSpec\x20=\x20ModulePath\x20Version\x20newline\x20.\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>require\x20golang.org/x/net\x20v1.2.3\x0a\x0arequire\x20(\x0a\x20\x20\x20\x20golang.org/x/crypto\x20v1.4.5\x20//\x20indirect\x0a\x20\x20\x20\x20golang.org/x/text\x20v1.6.7\x0a)\x0a</code></pre>\x0a<p><a\x20id=\"go.mod-exclude\"></a></p>\x0a<h3><code>exclude</code>\x20directive</h3>\x0a<p>An\x20<code>exclude</code>\x20directive\x20prevents\x20a\x20module\x20version\x20from\x20being\x20loaded\x20by\x20the\x20<code>go</code>\x0acommand.\x20If\x20an\x20excluded\x20version\x20is\x20referenced\x20by\x20a\x20<code>require</code>\x20directive\x20in\x20a\x0a<code>go.mod</code>\x20file,\x20the\x20<code>go</code>\x20command\x20will\x20list\x20available\x20versions\x20for\x20the\x20module\x20(as\x0ashown\x20with\x20<code>go\x20list\x20-m\x20-versions</code>)\x20and\x20will\x20load\x20the\x20next\x20higher\x20non-excluded\x0aversion\x20instead.\x20Both\x20release\x20and\x20pre-release\x20versions\x20are\x20considered\x20for\x20this\x0apurpose,\x20but\x20pseudo-versions\x20are\x20not.\x20If\x20there\x20are\x20no\x20higher\x20versions,\x0athe\x20<code>go</code>\x20command\x20will\x20report\x20an\x20error.\x20Note\x20that\x20this\x20<a\x20href=\"https://golang.org/issue/36465\">may\x0achange</a>\x20in\x20Go\x201.15.</p>\x0a<!--\x20TODO(golang.org/issue/36465):\x20update\x20after\x20change\x20-->\x0a<p><code>exclude</code>\x20directives\x20only\x20apply\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file\x20and\x20are\x0aignored\x20in\x20other\x20modules.\x20See\x20<a\x20href=\"#minimal-version-selection\">Minimal\x20version\x0aselection</a>\x20for\x20details.</p>\x0a<pre><code>ExcludeDirective\x20=\x20&quot;exclude&quot;\x20(\x20ExcludeSpec\x20|\x20&quot;(&quot;\x20newline\x20{\x20ExcludeSpec\x20}\x20&quot;)&quot;\x20)\x20.\x0aExcludeSpec\x20=\x20ModulePath\x20Version\x20newline\x20.\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>exclude\x20golang.org/x/net\x20v1.2.3\x0a\x0aexclude\x20(\x0a\x20\x20\x20\x20golang.org/x/crypto\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/text\x20v1.6.7\x0a)\x0a</code></pre>\x0a<p><a\x20id=\"go.mod-replace\"></a></p>\x0a<h3><code>replace</code>\x20directive</h3>\x0a<p>A\x20<code>replace</code>\x20directive\x20replaces\x20the\x20contents\x20of\x20a\x20specific\x20version\x20of\x20a\x20module,\x0aor\x20all\x20versions\x20of\x20a\x20module,\x20with\x20contents\x20found\x20elsewhere.\x20The\x20replacement\x0amay\x20be\x20specified\x20with\x20either\x20another\x20module\x20path\x20and\x20version,\x20or\x20a\x0aplatform-specific\x20file\x20path.</p>\x0a<p>If\x20a\x20version\x20is\x20present\x20on\x20the\x20left\x20side\x20of\x20the\x20arrow\x20(<code>=&gt;</code>),\x20only\x20that\x20specific\x0aversion\x20of\x20the\x20module\x20is\x20replaced;\x20other\x20versions\x20will\x20be\x20accessed\x20normally.\x0aIf\x20the\x20left\x20version\x20is\x20omitted,\x20all\x20versions\x20of\x20the\x20module\x20are\x20replaced.</p>\x0a<p>If\x20the\x20path\x20on\x20the\x20right\x20side\x20of\x20the\x20arrow\x20is\x20an\x20absolute\x20or\x20relative\x20path\x0a(beginning\x20with\x20<code>./</code>\x20or\x20<code>../</code>),\x20it\x20is\x20interpreted\x20as\x20the\x20local\x20file\x20path\x20to\x20the\x0areplacement\x20module\x20root\x20directory,\x20which\x20must\x20contain\x20a\x20<code>go.mod</code>\x20file.\x20The\x0areplacement\x20version\x20must\x20be\x20omitted\x20in\x20this\x20case.</p>\x0a<p>If\x20the\x20path\x20on\x20the\x20right\x20side\x20is\x20not\x20a\x20local\x20path,\x20it\x20must\x20be\x20a\x20valid\x20module\x0apath.\x20In\x20this\x20case,\x20a\x20version\x20is\x20required.\x20The\x20same\x20module\x20version\x20must\x20not\x0aalso\x20appear\x20in\x20the\x20build\x20list.</p>\x0a<p>Regardless\x20of\x20whether\x20a\x20replacement\x20is\x20specified\x20with\x20a\x20local\x20path\x20or\x20module\x0apath,\x20if\x20the\x20replacement\x20module\x20has\x20a\x20<code>go.mod</code>\x20file,\x20its\x20<code>module</code>\x20directive\x0amust\x20match\x20the\x20module\x20path\x20it\x20replaces.</p>\x0a<p><code>replace</code>\x20directives\x20only\x20apply\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file\x0aand\x20are\x20ignored\x20in\x20other\x20modules.\x20See\x20<a\x20href=\"#minimal-version-selection\">Minimal\x20version\x0aselection</a>\x20for\x20details.</p>\x0a<pre><code>ReplaceDirective\x20=\x20&quot;replace&quot;\x20(\x20ReplaceSpec\x20|\x20&quot;(&quot;\x20newline\x20{\x20ReplaceSpec\x20}\x20&quot;)&quot;\x20newline\x20&quot;)&quot;\x20)\x20.\x0aReplaceSpec\x20=\x20ModulePath\x20[\x20Version\x20]\x20&quot;=&gt;&quot;\x20FilePath\x20newline\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20|\x20ModulePath\x20[\x20Version\x20]\x20&quot;=&gt;&quot;\x20ModulePath\x20Version\x20newline\x20.\x0aFilePath\x20=\x20/*\x20platform-specific\x20relative\x20or\x20absolute\x20file\x20path\x20*/\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>replace\x20golang.org/x/net\x20v1.2.3\x20=&gt;\x20example.com/fork/net\x20v1.4.5\x0a\x0areplace\x20(\x0a\x20\x20\x20\x20golang.org/x/net\x20v1.2.3\x20=&gt;\x20example.com/fork/net\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/net\x20=&gt;\x20example.com/fork/net\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/net\x20v1.2.3\x20=&gt;\x20./fork/net\x0a\x20\x20\x20\x20golang.org/x/net\x20=&gt;\x20./fork/net\x0a)\x0a</code></pre>\x0a<p><a\x20id=\"go.mod-updates\"></a></p>\x0a<h3>Automatic\x20updates</h3>\x0a<p>The\x20<code>go</code>\x20command\x20automatically\x20updates\x20<code>go.mod</code>\x20when\x20it\x20uses\x20the\x20module\x20graph\x20if\x0asome\x20information\x20is\x20missing\x20or\x20<code>go.mod</code>\x20doesn't\x20accurately\x20reflect\x20reality.\x20\x20For\x0aexample,\x20consider\x20this\x20<code>go.mod</code>\x20file:</p>\x0a<pre><code>module\x20example.com/M\x0a\x0arequire\x20(\x0a\x20\x20\x20\x20example.com/A\x20v1\x0a\x20\x20\x20\x20example.com/B\x20v1.0.0\x0a\x20\x20\x20\x20example.com/C\x20v1.0.0\x0a\x20\x20\x20\x20example.com/D\x20v1.2.3\x0a\x20\x20\x20\x20example.com/E\x20dev\x0a)\x0a\x0aexclude\x20example.com/D\x20v1.2.3\x0a</code></pre>\x0a<p>The\x20update\x20rewrites\x20non-canonical\x20version\x20identifiers\x20to\x0a<a\x20href=\"#glos-canonical-version\">canonical</a>\x20semver\x20form,\x20so\x20<code>example.com/A</code>'s\x20<code>v1</code>\x0abecomes\x20<code>v1.0.0</code>,\x20and\x20<code>example.com/E</code>'s\x20<code>dev</code>\x20becomes\x20the\x20pseudo-version\x20for\x20the\x0alatest\x20commit\x20on\x20the\x20<code>dev</code>\x20branch,\x20perhaps\x20<code>v0.0.0-20180523231146-b3f5c0f6e5f1</code>.</p>\x0a<p>The\x20update\x20modifies\x20requirements\x20to\x20respect\x20exclusions,\x20so\x20the\x20requirement\x20on\x0athe\x20excluded\x20<code>example.com/D\x20v1.2.3</code>\x20is\x20updated\x20to\x20use\x20the\x20next\x20available\x20version\x0aof\x20<code>example.com/D</code>,\x20perhaps\x20<code>v1.2.4</code>\x20or\x20<code>v1.3.0</code>.</p>\x0a<p>The\x20update\x20removes\x20redundant\x20or\x20misleading\x20requirements.\x20For\x20example,\x20if\x0a<code>example.com/A\x20v1.0.0</code>\x20itself\x20requires\x20<code>example.com/B\x20v1.2.0</code>\x20and\x20<code>example.com/C\x20v1.0.0</code>,\x20then\x20<code>go.mod</code>'s\x20requirement\x20of\x20<code>example.com/B\x20v1.0.0</code>\x20is\x20misleading\x0a(superseded\x20by\x20<code>example.com/A</code>'s\x20need\x20for\x20<code>v1.2.0</code>),\x20and\x20its\x20requirement\x20of\x0a<code>example.com/C\x20v1.0.0</code>\x20is\x20redundant\x20(implied\x20by\x20<code>example.com/A</code>'s\x20need\x20for\x20the\x0asame\x20version),\x20so\x20both\x20will\x20be\x20removed.\x20If\x20the\x20main\x20module\x20contains\x20packages\x0athat\x20directly\x20import\x20packages\x20from\x20<code>example.com/B</code>\x20or\x20<code>example.com/C</code>,\x20then\x20the\x0arequirements\x20will\x20be\x20kept\x20but\x20updated\x20to\x20the\x20actual\x20versions\x20being\x20used.</p>\x0a<p>Finally,\x20the\x20update\x20reformats\x20the\x20<code>go.mod</code>\x20in\x20a\x20canonical\x20formatting,\x20so\x0athat\x20future\x20mechanical\x20changes\x20will\x20result\x20in\x20minimal\x20diffs.\x20The\x20<code>go</code>\x20command\x0awill\x20not\x20update\x20<code>go.mod</code>\x20if\x20only\x20formatting\x20changes\x20are\x20needed.</p>\x0a<p>Because\x20the\x20module\x20graph\x20defines\x20the\x20meaning\x20of\x20import\x20statements,\x20any\x20commands\x0athat\x20load\x20packages\x20also\x20use\x20and\x20therefore\x20update\x20<code>go.mod</code>,\x20including\x20<code>go\x20build</code>,\x0a<code>go\x20get</code>,\x20<code>go\x20install</code>,\x20<code>go\x20list</code>,\x20<code>go\x20test</code>,\x20<code>go\x20mod\x20graph</code>,\x20<code>go\x20mod\x20tidy</code>,\x20and\x0a<code>go\x20mod\x20why</code>.</p>\x0a<p>The\x20<code>-mod=readonly</code>\x20flag\x20prevents\x20commands\x20from\x20automatically\x20updating\x0a<code>go.mod</code>.\x20However,\x20if\x20a\x20command\x20needs\x20to\x20perform\x20an\x20action\x20that\x20would\x0aupdate\x20to\x20<code>go.mod</code>,\x20it\x20will\x20report\x20an\x20error.\x20For\x20example,\x20if\x0a<code>go\x20build</code>\x20is\x20asked\x20to\x20build\x20a\x20package\x20not\x20provided\x20by\x20any\x20module\x20in\x20the\x20build\x0alist,\x20<code>go\x20build</code>\x20will\x20report\x20an\x20error\x20instead\x20of\x20looking\x20up\x20the\x20module\x20and\x0aupdating\x20requirements\x20in\x20<code>go.mod</code>.</p>\x0a<p><a\x20id=\"minimal-version-selection\"></a></p>\x0a<h2>Minimal\x20version\x20selection\x20(MVS)</h2>\x0a<p>Go\x20uses\x20an\x20algorithm\x20called\x20<dfn>Minimal\x20version\x20selection\x20(MVS)</dfn>\x20to\x20select\x0aa\x20set\x20of\x20module\x20versions\x20to\x20use\x20when\x20building\x20packages.\x20MVS\x20is\x20described\x20in\x0adetail\x20in\x20<a\x20href=\"https://research.swtch.com/vgo-mvs\">Minimal\x20Version\x20Selection</a>\x20by\x0aRuss\x20Cox.</p>\x0a<p>Conceptually,\x20MVS\x20operates\x20on\x20a\x20directed\x20graph\x20of\x20modules,\x20specified\x20with\x0a<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20files</a>.\x20Each\x20vertex\x20in\x20the\x20graph\x20represents\x20a\x0amodule\x20version.\x20Each\x20edge\x20represents\x20a\x20minimum\x20required\x20version\x20of\x20a\x20dependency,\x0aspecified\x20using\x20a\x20<a\x20href=\"#go.mod-require\"><code>require</code></a>\x0adirective.\x20<a\x20href=\"#go.mod-replace\"><code>replace</code></a>\x20and\x20<a\x20href=\"#go.mod-exclude\"><code>exclude</code></a>\x0adirectives\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file\x20modify\x20the\x20graph.</p>\x0a<p>MVS\x20produces\x20the\x20<a\x20href=\"#glos-build-list\">build\x20list</a>\x20as\x20output,\x20the\x20list\x20of\x20module\x0aversions\x20used\x20for\x20a\x20build.</p>\x0a<p>MVS\x20starts\x20at\x20the\x20main\x20module\x20(a\x20special\x20vertex\x20in\x20the\x20graph\x20that\x20has\x20no\x0aversion)\x20and\x20traverses\x20the\x20graph,\x20tracking\x20the\x20highest\x20required\x20version\x20of\x20each\x0amodule.\x20At\x20the\x20end\x20of\x20the\x20traversal,\x20the\x20highest\x20required\x20versions\x20comprise\x20the\x0abuild\x20list:\x20they\x20are\x20the\x20minimum\x20versions\x20that\x20satisfy\x20all\x20requirements.</p>\x0a<p>The\x20build\x20list\x20may\x20be\x20inspected\x20with\x20the\x20command\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m\x20all</code></a>.\x20Unlike\x20other\x20dependency\x20management\x20systems,\x20the\x20build\x20list\x20is\x0anot\x20saved\x20in\x20a\x20&quot;lock&quot;\x20file.\x20MVS\x20is\x20deterministic,\x20and\x20the\x20build\x20list\x20doesn't\x0achange\x20when\x20new\x20versions\x20of\x20dependencies\x20are\x20released,\x20so\x20MVS\x20is\x20used\x20to\x20compute\x0ait\x20at\x20the\x20beginning\x20of\x20every\x20module-aware\x20command.</p>\x0a<p>Consider\x20the\x20example\x20in\x20the\x20diagram\x20below.\x20The\x20main\x20module\x20requires\x20module\x20A\x0aat\x20version\x201.2\x20or\x20higher\x20and\x20module\x20B\x20at\x20version\x201.2\x20or\x20higher.\x20A\x201.2\x20and\x20B\x201.2\x0arequire\x20C\x201.3\x20and\x20C\x201.4,\x20respectively.\x20C\x201.3\x20and\x20C\x201.4\x20both\x20require\x20D\x201.2.</p>\x0a<p><img\x20src=\"/doc/mvs/buildlist.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20visited\x20versions\x20highlighted\"\x20title=\"MVS\x20build\x20list\x20graph\"></p>\x0a<p>MVS\x20visits\x20and\x20loads\x20the\x20<code>go.mod</code>\x20file\x20for\x20each\x20of\x20the\x20module\x20versions\x0ahighlighted\x20in\x20blue.\x20At\x20the\x20end\x20of\x20the\x20graph\x20traversal,\x20MVS\x20returns\x20a\x20build\x20list\x0acontaining\x20the\x20bolded\x20versions:\x20A\x201.2,\x20B\x201.2,\x20C\x201.4,\x20and\x20D\x201.2.\x20Note\x20that\x20higher\x0aversions\x20of\x20B\x20and\x20D\x20are\x20available\x20but\x20MVS\x20does\x20not\x20select\x20them,\x20since\x20nothing\x0arequires\x20them.</p>\x0a<p><a\x20id=\"mvs-replace\"></a></p>\x0a<h3>Replacement</h3>\x0a<p>The\x20content\x20of\x20a\x20module\x20(including\x20its\x20<code>go.mod</code>\x20file)\x20may\x20be\x20replaced\x20using\x20a\x0a<a\x20href=\"#go.mod-replace\"><code>replace</code>\x20directive</a>\x20in\x20the\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file.\x0aA\x20<code>replace</code>\x20directive\x20may\x20apply\x20to\x20a\x20specific\x20version\x20of\x20a\x20module\x20or\x20to\x20all\x0aversions\x20of\x20a\x20module.</p>\x0a<p>Replacements\x20change\x20the\x20module\x20graph,\x20since\x20a\x20replacement\x20module\x20may\x20have\x0adifferent\x20dependencies\x20than\x20replaced\x20versions.</p>\x0a<p>Consider\x20the\x20example\x20below,\x20where\x20C\x201.4\x20has\x20been\x20replaced\x20with\x20R.\x20R\x20depends\x20on\x20D\x0a1.3\x20instead\x20of\x20D\x201.2,\x20so\x20MVS\x20returns\x20a\x20build\x20list\x20containing\x20A\x201.2,\x20B\x201.2,\x20C\x201.4\x0a(replaced\x20with\x20R),\x20and\x20D\x201.3.</p>\x0a<p><img\x20src=\"/doc/mvs/replace.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20a\x20replacement\"\x20title=\"MVS\x20replacment\"></p>\x0a<p><a\x20id=\"mvs-exclude\"></a></p>\x0a<h3>Exclusion</h3>\x0a<p>A\x20module\x20may\x20also\x20be\x20excluded\x20at\x20specific\x20versions\x20using\x20an\x20<a\x20href=\"#go.mod-exclude\"><code>exclude</code>\x0adirective</a>\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file.</p>\x0a<p>Exclusions\x20also\x20change\x20the\x20module\x20graph.\x20When\x20a\x20version\x20is\x20excluded,\x20it\x20is\x0aremoved\x20from\x20the\x20module\x20graph,\x20and\x20requirements\x20on\x20it\x20are\x20redirected\x20to\x20the\x0anext\x20higher\x20version.</p>\x0a<p>Consider\x20the\x20example\x20below.\x20C\x201.3\x20has\x20been\x20excluded.\x20MVS\x20will\x20act\x20as\x20if\x20A\x201.2\x0arequired\x20C\x201.4\x20(the\x20next\x20higher\x20version)\x20instead\x20of\x20C\x201.3.</p>\x0a<p><img\x20src=\"/doc/mvs/exclude.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20an\x20exclusion\"\x20title=\"MVS\x20exclude\"></p>\x0a<p><a\x20id=\"mvs-upgrade\"></a></p>\x0a<h3>Upgrades</h3>\x0a<p>The\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20command\x20may\x20be\x20used\x20to\x20upgrade\x20a\x20set\x20of\x20modules.\x20To\x0aperform\x20an\x20upgrade,\x20the\x20<code>go</code>\x20command\x20changes\x20the\x20module\x20graph\x20before\x20running\x20MVS\x0aby\x20adding\x20edges\x20from\x20visited\x20versions\x20to\x20upgraded\x20versions.</p>\x0a<p>Consider\x20the\x20example\x20below.\x20Module\x20B\x20may\x20be\x20upgraded\x20from\x201.2\x20to\x201.3,\x20C\x20may\x20be\x0aupgraded\x20from\x201.3\x20to\x201.4,\x20and\x20D\x20may\x20be\x20upgraded\x20from\x201.2\x20to\x201.3.</p>\x0a<p><img\x20src=\"/doc/mvs/upgrade.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20upgrades\"\x20title=\"MVS\x20upgrade\"></p>\x0a<p>Upgrades\x20(and\x20downgrades)\x20may\x20add\x20or\x20remove\x20indirect\x20dependencies.\x20In\x20this\x20case,\x0aE\x201.1\x20and\x20F\x201.1\x20appear\x20in\x20the\x20build\x20list\x20after\x20the\x20upgrade,\x20since\x20E\x201.1\x20is\x0arequired\x20by\x20B\x201.3.</p>\x0a<p>To\x20preserve\x20upgrades,\x20the\x20<code>go</code>\x20command\x20updates\x20the\x20requirements\x20in\x20<code>go.mod</code>.\x20\x20It\x0awill\x20change\x20the\x20requirement\x20on\x20B\x20to\x20version\x201.3.\x20It\x20will\x20also\x20add\x20requirements\x0aon\x20C\x201.4\x20and\x20D\x201.3\x20with\x20<code>//\x20indirect</code>\x20comments,\x20since\x20those\x20versions\x20would\x20not\x0abe\x20selected\x20otherwise.</p>\x0a<p><a\x20id=\"mvs-downgrade\"></a></p>\x0a<h3>Downgrade</h3>\x0a<p>The\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20command\x20may\x20also\x20be\x20used\x20to\x20downgrade\x20a\x20set\x20of\x0amodules.\x20To\x20perform\x20a\x20downgrade,\x20the\x20<code>go</code>\x20command\x20changes\x20the\x20module\x20graph\x20by\x0aremoving\x20versions\x20above\x20the\x20downgraded\x20versions.\x20It\x20also\x20removes\x20versions\x20of\x0aother\x20modules\x20that\x20depend\x20on\x20removed\x20versions,\x20since\x20they\x20may\x20not\x20be\x20compatible\x0awith\x20the\x20downgraded\x20versions\x20of\x20their\x20dependencies.\x20If\x20the\x20main\x20module\x20requires\x0aa\x20module\x20version\x20removed\x20by\x20downgrading,\x20the\x20requirement\x20is\x20changed\x20to\x20a\x0aprevious\x20version\x20that\x20has\x20not\x20been\x20removed.\x20If\x20no\x20previous\x20version\x20is\x20available,\x0athe\x20requirement\x20is\x20dropped.</p>\x0a<p>Consider\x20the\x20example\x20below.\x20Suppose\x20that\x20a\x20problem\x20was\x20found\x20with\x20C\x201.4,\x20so\x20we\x0adowngrade\x20to\x20C\x201.3.\x20C\x201.4\x20is\x20removed\x20from\x20the\x20module\x20graph.\x20B\x201.2\x20is\x20also\x0aremoved,\x20since\x20it\x20requires\x20C\x201.4\x20or\x20higher.\x20The\x20main\x20module's\x20requirement\x20on\x20B\x0ais\x20changed\x20to\x201.1.</p>\x0a<p><img\x20src=\"/doc/mvs/downgrade.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20downgrade\"\x20title=\"MVS\x20downgrade\"></p>\x0a<p><a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20can\x20also\x20remove\x20dependencies\x20entirely,\x20using\x20an\x20<code>@none</code>\x0asuffix\x20after\x20an\x20argument.\x20This\x20works\x20similarly\x20to\x20a\x20downgrade.\x20All\x20versions\x0aof\x20the\x20named\x20module\x20are\x20removed\x20from\x20the\x20module\x20graph.</p>\x0a<p><a\x20id=\"non-module-compat\"></a></p>\x0a<h2>Compatibility\x20with\x20non-module\x20repositories</h2>\x0a<p>To\x20ensure\x20a\x20smooth\x20transition\x20from\x20<code>GOPATH</code>\x20to\x20modules,\x20the\x20<code>go</code>\x20command\x20can\x0adownload\x20and\x20build\x20packages\x20in\x20module-aware\x20mode\x20from\x20repositories\x20that\x20have\x20not\x0amigrated\x20to\x20modules\x20by\x20adding\x20a\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20file</a>.</p>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20downloads\x20a\x20module\x20at\x20a\x20given\x20version\x20<a\x20href=\"#vcs\">directly</a>\x0afrom\x20a\x20repository,\x20it\x20looks\x20up\x20a\x20repository\x20URL\x20for\x20the\x20module\x20path,\x20maps\x20the\x0aversion\x20to\x20a\x20revision\x20within\x20the\x20repository,\x20then\x20extracts\x20an\x20archive\x20of\x20the\x0arepository\x20at\x20that\x20revision.\x20If\x20the\x20<a\x20href=\"#glos-module-path\">module's\x20path</a>\x20is\x20equal\x0ato\x20the\x20<a\x20href=\"#glos-repository-root-path\">repository\x20root\x20path</a>,\x20and\x20the\x20repository\x0aroot\x20directory\x20does\x20not\x20contain\x20a\x20<code>go.mod</code>\x20file,\x20the\x20<code>go</code>\x20command\x20synthesizes\x20a\x0a<code>go.mod</code>\x20file\x20in\x20the\x20module\x20cache\x20that\x20contains\x20a\x20<a\x20href=\"#go.mod-module\"><code>module</code>\x0adirective</a>\x20and\x20nothing\x20else.\x20Since\x20synthetic\x20<code>go.mod</code>\x20files\x20do\x0anot\x20contain\x20<a\x20href=\"#go.mod-require\"><code>require</code>\x20directives</a>\x20for\x20their\x20dependencies,\x0aother\x20modules\x20that\x20depend\x20on\x20them\x20may\x20need\x20additional\x20<code>require</code>\x20directives\x20(with\x0a<code>//\x20indirect</code>\x20comments)\x20to\x20ensure\x20each\x20dependency\x20is\x20fetched\x20at\x20the\x20same\x20version\x0aon\x20every\x20build.</p>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20downloads\x20a\x20module\x20from\x20a\x0a<a\x20href=\"#communicating-with-proxies\">proxy</a>,\x20it\x20downloads\x20the\x20<code>go.mod</code>\x20file\x20separately\x0afrom\x20the\x20rest\x20of\x20the\x20module\x20content.\x20The\x20proxy\x20is\x20expected\x20to\x20serve\x20a\x20synthetic\x0a<code>go.mod</code>\x20file\x20if\x20the\x20original\x20module\x20didn't\x20have\x20one.</p>\x0a<p><a\x20id=\"incompatible-versions\"></a></p>\x0a<h3><code>+incompatible</code>\x20versions</h3>\x0a<p>A\x20module\x20released\x20at\x20major\x20version\x202\x20or\x20higher\x20must\x20have\x20a\x20matching\x20<a\x20href=\"#major-version-suffixes\">major\x0aversion\x20suffix</a>\x20on\x20its\x20module\x20path.\x20For\x20example,\x20if\x20a\x0amodule\x20is\x20released\x20at\x20<code>v2.0.0</code>,\x20its\x20path\x20must\x20have\x20a\x20<code>/v2</code>\x20suffix.\x20This\x20allows\x0athe\x20<code>go</code>\x20command\x20to\x20treat\x20multiple\x20major\x20versions\x20of\x20a\x20project\x20as\x20distinct\x0amodules,\x20even\x20if\x20they're\x20developed\x20in\x20the\x20same\x20repository.</p>\x0a<p>The\x20major\x20version\x20suffix\x20requirement\x20was\x20introduced\x20when\x20module\x20support\x20was\x0aadded\x20to\x20the\x20<code>go</code>\x20command,\x20and\x20many\x20repositories\x20had\x20already\x20tagged\x20releases\x0awith\x20major\x20version\x20<code>2</code>\x20or\x20higher\x20before\x20that.\x20To\x20maintain\x20compatibility\x20with\x0athese\x20repositories,\x20the\x20<code>go</code>\x20command\x20adds\x20an\x20<code>+incompatible</code>\x20suffix\x20to\x20versions\x0awith\x20major\x20version\x202\x20or\x20higher\x20without\x20a\x20<code>go.mod</code>\x20file.\x20<code>+incompatible</code>\x0aindicates\x20that\x20a\x20version\x20is\x20part\x20of\x20the\x20same\x20module\x20as\x20versions\x20with\x20lower\x20major\x0aversion\x20numbers;\x20consequently,\x20the\x20<code>go</code>\x20command\x20may\x20automatically\x20upgrade\x20to\x0ahigher\x20<code>+incompatible</code>\x20versions\x20even\x20though\x20it\x20may\x20break\x20the\x20build.</p>\x0a<p>Consider\x20the\x20example\x20requirement\x20below:</p>\x0a<pre><code>require\x20example.com/m\x20v4.1.2+incompatible\x0a</code></pre>\x0a<p>The\x20version\x20<code>v4.1.2+incompatible</code>\x20refers\x20to\x20the\x20<a\x20href=\"#glos-semantic-version-tag\">semantic\x20version\x0atag</a>\x20<code>v4.1.2</code>\x20in\x20the\x20repository\x20that\x20provides\x20the\x0amodule\x20<code>example.com/m</code>.\x20The\x20module\x20must\x20be\x20in\x20the\x20repository\x20root\x20directory\x0a(that\x20is,\x20the\x20<a\x20href=\"#glos-module-path\">repository\x20root\x20path</a>\x20must\x20also\x20be\x0a<code>example.com/m</code>),\x20and\x20a\x20<code>go.mod</code>\x20file\x20must\x20not\x20be\x20present.\x20The\x20module\x20may\x20have\x0aversions\x20with\x20lower\x20major\x20version\x20numbers\x20like\x20<code>v1.5.2</code>,\x20and\x20the\x20<code>go</code>\x20command\x0amay\x20upgrade\x20automatically\x20to\x20<code>v4.1.2+incompatible</code>\x20from\x20those\x20versions\x20(see\x0a<a\x20href=\"#minimal-version-selection\">minimal\x20version\x20selection\x20(MVS)</a>\x20for\x20information\x0aon\x20how\x20upgrades\x20work).</p>\x0a<p>A\x20repository\x20that\x20migrates\x20to\x20modules\x20after\x20version\x20<code>v2.0.0</code>\x20is\x20tagged\x20should\x0ausually\x20release\x20a\x20new\x20major\x20version.\x20In\x20the\x20example\x20above,\x20the\x20author\x20should\x0acreate\x20a\x20module\x20with\x20the\x20path\x20<code>example.com/m/v5</code>\x20and\x20should\x20release\x20version\x0a<code>v5.0.0</code>.\x20The\x20author\x20should\x20also\x20update\x20imports\x20of\x20packages\x20in\x20the\x20module\x20to\x20use\x0athe\x20prefix\x20<code>example.com/m/v5</code>\x20instead\x20of\x20<code>example.com/m</code>.\x20See\x20<a\x20href=\"https://blog.golang.org/v2-go-modules\">Go\x20Modules:\x20v2\x0aand\x20Beyond</a>\x20for\x20a\x20more\x20detailed\x20example.</p>\x0a<p>Note\x20that\x20the\x20<code>+incompatible</code>\x20suffix\x20should\x20not\x20appear\x20on\x20a\x20tag\x20in\x20a\x20repository;\x0aa\x20tag\x20like\x20<code>v4.1.2+incompatible</code>\x20will\x20be\x20ignored.\x20The\x20suffix\x20only\x20appears\x20in\x0aversions\x20used\x20by\x20the\x20<code>go</code>\x20command.\x20See\x20<a\x20href=\"#vcs-version\">Mapping\x20versions\x20to\x0acommits</a>\x20for\x20details\x20on\x20the\x20distinction\x20between\x20versions\x20and\x20tags.</p>\x0a<p>Note\x20also\x20that\x20the\x20<code>+incompatible</code>\x20suffix\x20may\x20appear\x20on\x0a<a\x20href=\"#glos-pseudo-version\">pseudo-versions</a>.\x20For\x20example,\x0a<code>v2.0.1-20200722182040-012345abcdef+incompatible</code>\x20may\x20be\x20a\x20valid\x20pseudo-version.</p>\x0a<!--\x20TODO(jayconrod):\x20Is\x20it\x20appropriate\x0ato\x20link\x20to\x20the\x20blog\x20here?\x20Ideally,\x20we\x20would\x20have\x20a\x20more\x20detailed\x20guide.\x20-->\x0a<p><a\x20id=\"minimal-module-compatibility\"></a></p>\x0a<h3>Minimal\x20module\x20compatibility</h3>\x0a<p>A\x20module\x20released\x20at\x20major\x20version\x202\x20or\x20higher\x20is\x20required\x20to\x20have\x20a\x20<a\x20href=\"#glos-major-version-suffix\">major\x0aversion\x20suffix</a>\x20on\x20its\x20<a\x20href=\"#glos-module-path\">module\x0apath</a>.\x20The\x20module\x20may\x20or\x20may\x20not\x20be\x20developed\x20in\x20a\x20<a\x20href=\"#glos-major-version-subdirectory\">major\x0aversion\x20subdirectory</a>\x20within\x20its\x20repository.\x0aThis\x20has\x20implications\x20for\x20packages\x20that\x20import\x20packages\x20within\x20the\x20module\x20when\x0abuilding\x20<code>GOPATH</code>\x20mode.</p>\x0a<p>Normally\x20in\x20<code>GOPATH</code>\x20mode,\x20a\x20package\x20is\x20stored\x20in\x20a\x20directory\x20matching\x20its\x0a<a\x20href=\"#glos-repository-root-path\">repository's\x20root\x20path</a>\x20joined\x20with\x20its\x20diretory\x0awithin\x20the\x20repository.\x20For\x20example,\x20a\x20package\x20in\x20the\x20repository\x20with\x20root\x20path\x0a<code>example.com/repo</code>\x20in\x20the\x20subdirectory\x20<code>sub</code>\x20would\x20be\x20stored\x20in\x0a<code>$GOPATH/src/example.com/repo/sub</code>\x20and\x20would\x20be\x20imported\x20as\x0a<code>example.com/repo/sub</code>.</p>\x0a<p>For\x20a\x20module\x20with\x20a\x20major\x20version\x20suffix,\x20one\x20might\x20expect\x20to\x20find\x20the\x20package\x0a<code>example.com/repo/v2/sub</code>\x20in\x20the\x20directory\x0a<code>$GOPATH/src/example.com/repo/v2/sub</code>.\x20This\x20would\x20require\x20the\x20module\x20to\x20be\x0adeveloped\x20in\x20the\x20<code>v2</code>\x20subdirectory\x20of\x20its\x20repository.\x20The\x20<code>go</code>\x20command\x20supports\x0athis\x20but\x20does\x20not\x20require\x20it\x20(see\x20<a\x20href=\"#vcs-version\">Mapping\x20versions\x20to\x20commits</a>).</p>\x0a<p>If\x20a\x20module\x20is\x20<em>not</em>\x20developed\x20in\x20a\x20major\x20version\x20subdirectory,\x20then\x20its\x0adirectory\x20in\x20<code>GOPATH</code>\x20will\x20not\x20contain\x20the\x20major\x20version\x20suffix,\x20and\x20its\x0apackages\x20may\x20be\x20imported\x20without\x20the\x20major\x20version\x20suffix.\x20In\x20the\x20example\x20above,\x0athe\x20package\x20would\x20be\x20found\x20in\x20the\x20directory\x20<code>$GOPATH/src/example.com/repo/sub</code>\x0aand\x20would\x20be\x20imported\x20as\x20<code>example.com/repo/sub</code>.</p>\x0a<p>This\x20creates\x20a\x20problem\x20for\x20packages\x20intended\x20to\x20be\x20built\x20in\x20both\x20module\x20mode\x0aand\x20<code>GOPATH</code>\x20mode:\x20module\x20mode\x20requires\x20a\x20suffix,\x20while\x20<code>GOPATH</code>\x20mode\x20does\x20not.</p>\x0a<p>To\x20fix\x20this,\x20<dfn>minimal\x20module\x20compatibility</dfn>\x20was\x20added\x20in\x20Go\x201.11\x20and\x0awas\x20backported\x20to\x20Go\x201.9.7\x20and\x201.10.3.\x20When\x20an\x20import\x20path\x20is\x20resolved\x20to\x20a\x0adirectory\x20in\x20<code>GOPATH</code>\x20mode:</p>\x0a<ul>\x0a<li>When\x20resolving\x20an\x20import\x20of\x20the\x20form\x20<code>$modpath/$vn/$dir</code>\x20where:\x0a<ul>\x0a<li><code>$modpath</code>\x20is\x20a\x20valid\x20module\x20path,</li>\x0a<li><code>$vn</code>\x20is\x20a\x20major\x20version\x20suffix,</li>\x0a<li><code>$dir</code>\x20is\x20a\x20possibly\x20empty\x20subdirectory,</li>\x0a</ul>\x0a</li>\x0a<li>If\x20all\x20of\x20the\x20following\x20are\x20true:\x0a<ul>\x0a<li>The\x20package\x20<code>$modpath/$vn/$dir</code>\x20is\x20not\x20present\x20in\x20any\x20relevant\x20<code>vendor</code>\x0adirectory.</li>\x0a<li>A\x20<code>go.mod</code>\x20file\x20is\x20present\x20in\x20the\x20same\x20directory\x20as\x20the\x20importing\x20file\x0aor\x20in\x20any\x20parent\x20directory\x20up\x20to\x20the\x20<code>$GOPATH/src</code>\x20root,</li>\x0a<li>No\x20<code>$GOPATH[i]/src/$modpath/$vn/$suffix</code>\x20directory\x20exists\x20(for\x20any\x20root\x0a<code>$GOPATH[i]</code>),</li>\x0a<li>The\x20file\x20<code>$GOPATH[d]/src/$modpath/go.mod</code>\x20exists\x20(for\x20some\x20root\x0a<code>$GOPATH[d]</code>)\x20and\x20declares\x20the\x20module\x20path\x20as\x20<code>$modpath/$vn</code>,</li>\x0a</ul>\x0a</li>\x0a<li>Then\x20the\x20import\x20of\x20<code>$modpath/$vn/$dir</code>\x20is\x20resolved\x20to\x20the\x20directory\x0a<code>$GOPATH[d]/src/$modpath/$dir</code>.</li>\x0a</ul>\x0a<p>This\x20rules\x20allow\x20packages\x20that\x20have\x20been\x20migrated\x20to\x20modules\x20to\x20import\x20other\x0apackages\x20that\x20have\x20been\x20migrated\x20to\x20modules\x20when\x20built\x20in\x20<code>GOPATH</code>\x20mode\x20even\x0awhen\x20a\x20major\x20version\x20subdirectory\x20was\x20not\x20used.</p>\x0a<p><a\x20id=\"mod-commands\"></a></p>\x0a<h2>Module-aware\x20commands</h2>\x0a<p>Most\x20<code>go</code>\x20commands\x20may\x20run\x20in\x20<em>Module-aware\x20mode</em>\x20or\x20<em><code>GOPATH</code>\x20mode</em>.\x20In\x0amodule-aware\x20mode,\x20the\x20<code>go</code>\x20command\x20uses\x20<code>go.mod</code>\x20files\x20to\x20find\x20versioned\x0adependencies,\x20and\x20it\x20typically\x20loads\x20packages\x20out\x20of\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>,\x20downloading\x20modules\x20if\x20they\x20are\x20missing.\x20In\x20<code>GOPATH</code>\x0amode,\x20the\x20<code>go</code>\x20command\x20ignores\x20modules;\x20it\x20looks\x20in\x20<code>vendor</code>\x20directories\x20and\x20in\x0a<code>GOPATH</code>\x20to\x20find\x20dependencies.</p>\x0a<p>Module-aware\x20mode\x20is\x20active\x20by\x20default\x20whenever\x20a\x20<code>go.mod</code>\x20file\x20is\x20found\x20in\x20the\x0acurrent\x20directory\x20or\x20in\x20any\x20parent\x20directory.\x20For\x20more\x20fine-grained\x20control,\x20the\x0a<code>GO111MODULE</code>\x20environment\x20variable\x20may\x20be\x20set\x20to\x20one\x20of\x20three\x20values:\x20<code>on</code>,\x0a<code>off</code>,\x20or\x20<code>auto</code>.</p>\x0a<ul>\x0a<li>If\x20<code>GO111MODULE=off</code>,\x20the\x20<code>go</code>\x20command\x20ignores\x20<code>go.mod</code>\x20files\x20and\x20runs\x20in\x0a<code>GOPATH</code>\x20mode.</li>\x0a<li>If\x20<code>GO111MODULE=on</code>,\x20the\x20<code>go</code>\x20command\x20runs\x20in\x20module-aware\x20mode,\x20even\x20when\x0ano\x20<code>go.mod</code>\x20file\x20is\x20present.\x20Not\x20all\x20commands\x20work\x20without\x20a\x20<code>go.mod</code>\x20file:\x0asee\x20<a\x20href=\"#commands-outside\">Module\x20commands\x20outside\x20a\x20module</a>.</li>\x0a<li>If\x20<code>GO111MODULE=auto</code>\x20or\x20is\x20unset,\x20the\x20<code>go</code>\x20command\x20runs\x20in\x20module-aware\x0amode\x20if\x20a\x20<code>go.mod</code>\x20file\x20is\x20present\x20in\x20the\x20current\x20directory\x20or\x20any\x20parent\x0adirectory\x20(the\x20default\x20behavior).</li>\x0a</ul>\x0a<p>In\x20module-aware\x20mode,\x20<code>GOPATH</code>\x20no\x20longer\x20defines\x20the\x20meaning\x20of\x20imports\x20during\x20a\x0abuild,\x20but\x20it\x20still\x20stores\x20downloaded\x20dependencies\x20(in\x20<code>GOPATH/pkg/mod</code>;\x20see\x0a<a\x20href=\"#module-cache\">Module\x20cache</a>)\x20and\x20installed\x20commands\x20(in\x20<code>GOPATH/bin</code>,\x20unless\x0a<code>GOBIN</code>\x20is\x20set).</p>\x0a<p><a\x20id=\"build-commands\"></a></p>\x0a<h3>Build\x20commands</h3>\x0a<p><a\x20id=\"vendoring\"></a></p>\x0a<h3>Vendoring</h3>\x0a<p>When\x20using\x20modules,\x20the\x20<code>go</code>\x20command\x20typically\x20satisfies\x20dependencies\x20by\x0adownloading\x20modules\x20from\x20their\x20sources\x20into\x20the\x20module\x20cache,\x20then\x20loading\x0apackages\x20from\x20those\x20downloaded\x20copies.\x20<em>Vendoring</em>\x20may\x20be\x20used\x20to\x20allow\x0ainteroperation\x20with\x20older\x20versions\x20of\x20Go,\x20or\x20to\x20ensure\x20that\x20all\x20files\x20used\x20for\x20a\x0abuild\x20are\x20stored\x20in\x20a\x20single\x20file\x20tree.</p>\x0a<p>The\x20<code>go\x20mod\x20vendor</code>\x20command\x20constructs\x20a\x20directory\x20named\x20<code>vendor</code>\x20in\x20the\x20<a\x20href=\"#glos-main-module\">main\x0amodule's</a>\x20root\x20directory\x20containing\x20copies\x20of\x20all\x20packages\x0aneeded\x20to\x20build\x20and\x20test\x20packages\x20in\x20the\x20main\x20module.\x20Packages\x20that\x20are\x20only\x0aimported\x20by\x20tests\x20of\x20packages\x20outside\x20the\x20main\x20module\x20are\x20not\x20included.\x20As\x20with\x0a<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20and\x20other\x20module\x20commands,\x20<a\x20href=\"#glos-build-constraint\">build\x0aconstraints</a>\x20except\x20for\x20<code>ignore</code>\x20are\x20not\x20considered\x20when\x0aconstructing\x20the\x20<code>vendor</code>\x20directory.</p>\x0a<p><code>go\x20mod\x20vendor</code>\x20also\x20creates\x20the\x20file\x20<code>vendor/modules.txt</code>\x20that\x20contains\x20a\x20list\x0aof\x20vendored\x20packages\x20and\x20the\x20module\x20versions\x20they\x20were\x20copied\x20from.\x20When\x0avendoring\x20is\x20enabled,\x20this\x20manifest\x20is\x20used\x20as\x20a\x20source\x20of\x20module\x20version\x0ainformation,\x20as\x20reported\x20by\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>\x20and\x20<a\x20href=\"#go-version-m\"><code>go\x20version\x20-m</code></a>.\x20When\x20the\x20<code>go</code>\x20command\x20reads\x20<code>vendor/modules.txt</code>,\x20it\x20checks\x0athat\x20the\x20module\x20versions\x20are\x20consistent\x20with\x20<code>go.mod</code>.\x20If\x20<code>go.mod</code>\x20has\x20changed\x0asince\x20<code>vendor/modules.txt</code>\x20was\x20generated,\x20the\x20<code>go</code>\x20command\x20will\x20report\x20an\x20error.\x0a<code>go\x20mod\x20vendor</code>\x20should\x20be\x20run\x20again\x20to\x20update\x20the\x20<code>vendor</code>\x20directory.</p>\x0a<p>If\x20the\x20<code>vendor</code>\x20directory\x20is\x20present\x20in\x20the\x20main\x20module's\x20root\x20directory,\x20it\x0awill\x20be\x20used\x20automatically\x20if\x20the\x20<a\x20href=\"#go.mod-go\"><code>go</code>\x20version</a>\x20in\x20the\x20main\x0amodule's\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20file</a>\x20is\x20<code>1.14</code>\x20or\x20higher.\x20To\x20explicitly\x0aenable\x20vendoring,\x20invoke\x20the\x20<code>go</code>\x20command\x20with\x20the\x20flag\x20<code>-mod=vendor</code>.\x20To\x0adisable\x20vendoring,\x20use\x20the\x20flag\x20<code>-mod=mod</code>.</p>\x0a<p>When\x20vendoring\x20is\x20enabled,\x20<a\x20href=\"#build-commands\">build\x20commands</a>\x20like\x20<code>go\x20build</code>\x20and\x0a<code>go\x20test</code>\x20load\x20packages\x20from\x20the\x20<code>vendor</code>\x20directory\x20instead\x20of\x20accessing\x20the\x0anetwork\x20or\x20the\x20local\x20module\x20cache.\x20The\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>\x20command\x20only\x0aprints\x20information\x20about\x20modules\x20listed\x20in\x20<code>go.mod</code>.\x20<code>go\x20mod</code>\x20commands\x20such\x20as\x0a<a\x20href=\"#go-mod-download\"><code>go\x20mod\x20download</code></a>\x20and\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20do\x20not\x0awork\x20differently\x20when\x20vendoring\x20is\x20enabled\x20and\x20will\x20still\x20download\x20modules\x20and\x0aaccess\x20the\x20module\x20cache.\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20also\x20does\x20not\x20work\x20differently\x20when\x0avendoring\x20is\x20enabled.</p>\x0a<p>Unlike\x20<a\x20href=\"https://golang.org/s/go15vendor\">vendoring\x20in\x20<code>GOPATH</code></a>,\x20the\x20<code>go</code>\x0acommand\x20ignores\x20vendor\x20directories\x20in\x20locations\x20other\x20than\x20the\x20main\x20module's\x0aroot\x20directory.</p>\x0a<p><a\x20id=\"go-get\"></a></p>\x0a<h3><code>go\x20get</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20get\x20[-d]\x20[-t]\x20[-u]\x20[build\x20flags]\x20[packages]\x0a</code></pre>\x0a<p>Examples:</p>\x0a<pre><code>#\x20Install\x20the\x20latest\x20version\x20of\x20a\x20tool.\x0a$\x20go\x20get\x20golang.org/x/tools/cmd/goimports\x0a\x0a#\x20Upgrade\x20a\x20specific\x20module.\x0a$\x20go\x20get\x20-d\x20golang.org/x/net\x0a\x0a#\x20Upgrade\x20modules\x20that\x20provide\x20packages\x20imported\x20by\x20packages\x20in\x20the\x20main\x20module.\x0a$\x20go\x20get\x20-d\x20-u\x20./...\x0a\x0a#\x20Upgrade\x20or\x20downgrade\x20to\x20a\x20specific\x20version\x20of\x20a\x20module.\x0a$\x20go\x20get\x20-d\x20golang.org/x/text@v0.3.2\x0a\x0a#\x20Update\x20to\x20the\x20commit\x20on\x20the\x20module's\x20master\x20branch.\x0a$\x20go\x20get\x20-d\x20golang.org/x/text@master\x0a\x0a#\x20Remove\x20a\x20dependency\x20on\x20a\x20module\x20and\x20downgrade\x20modules\x20that\x20require\x20it\x0a#\x20to\x20versions\x20that\x20don't\x20require\x20it.\x0a$\x20go\x20get\x20-d\x20golang.org/x/text@none\x0a</code></pre>\x0a<p>The\x20<code>go\x20get</code>\x20command\x20updates\x20module\x20dependencies\x20in\x20the\x20<a\x20href=\"#go.mod-files\"><code>go.mod</code>\x0afile</a>\x20for\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module</a>,\x20then\x20builds\x20and\x0ainstalls\x20packages\x20listed\x20on\x20the\x20command\x20line.</p>\x0a<p>The\x20first\x20step\x20is\x20to\x20determine\x20which\x20modules\x20to\x20update.\x20<code>go\x20get</code>\x20accepts\x20a\x20list\x0aof\x20packages,\x20package\x20patterns,\x20and\x20module\x20paths\x20as\x20arguments.\x20If\x20a\x20package\x0aargument\x20is\x20specified,\x20<code>go\x20get</code>\x20updates\x20the\x20module\x20that\x20provides\x20the\x20package.\x0aIf\x20a\x20package\x20pattern\x20is\x20specified\x20(for\x20example,\x20<code>all</code>\x20or\x20a\x20path\x20with\x20a\x20<code>...</code>\x0awildcard),\x20<code>go\x20get</code>\x20expands\x20the\x20pattern\x20to\x20a\x20set\x20of\x20packages,\x20then\x20updates\x20the\x0amodules\x20that\x20provide\x20the\x20packages.\x20If\x20an\x20argument\x20names\x20a\x20module\x20but\x20not\x20a\x0apackage\x20(for\x20example,\x20the\x20module\x20<code>golang.org/x/net</code>\x20has\x20no\x20package\x20in\x20its\x20root\x0adirectory),\x20<code>go\x20get</code>\x20will\x20update\x20the\x20module\x20but\x20will\x20not\x20build\x20a\x20package.\x20If\x20no\x0aarguments\x20are\x20specified,\x20<code>go\x20get</code>\x20acts\x20as\x20if\x20<code>.</code>\x20were\x20specified\x20(the\x20package\x20in\x0athe\x20current\x20directory);\x20this\x20may\x20be\x20used\x20together\x20with\x20the\x20<code>-u</code>\x20flag\x20to\x20update\x0amodules\x20that\x20provide\x20imported\x20packages.</p>\x0a<p>Each\x20argument\x20may\x20include\x20a\x20<dfn>version\x20query\x20suffix</dfn>\x20indicating\x20the\x0adesired\x20version,\x20as\x20in\x20<code>go\x20get\x20golang.org/x/text@v0.3.0</code>.\x20A\x20version\x20query\x0asuffix\x20consists\x20of\x20an\x20<code>@</code>\x20symbol\x20followed\x20by\x20a\x20<a\x20href=\"#version-queries\">version\x20query</a>,\x0awhich\x20may\x20indicate\x20a\x20specific\x20version\x20(<code>v0.3.0</code>),\x20a\x20version\x20prefix\x20(<code>v0.3</code>),\x0aa\x20branch\x20or\x20tag\x20name\x20(<code>master</code>),\x20a\x20revision\x20(<code>1234abcd</code>),\x20or\x20one\x20of\x20the\x20special\x0aqueries\x20<code>latest</code>,\x20<code>upgrade</code>,\x20<code>patch</code>,\x20or\x20<code>none</code>.\x20If\x20no\x20version\x20is\x20given,\x0a<code>go\x20get</code>\x20uses\x20the\x20<code>@upgrade</code>\x20query.</p>\x0a<p>Once\x20<code>go\x20get</code>\x20has\x20resolved\x20its\x20arguments\x20to\x20specific\x20modules\x20and\x20versions,\x20<code>go\x20get</code>\x20will\x20add,\x20change,\x20or\x20remove\x20<a\x20href=\"#go.mod-require\"><code>require</code>\x20directives</a>\x20in\x20the\x0amain\x20module's\x20<code>go.mod</code>\x20file\x20to\x20ensure\x20the\x20modules\x20remain\x20at\x20the\x20desired\x0aversions\x20in\x20the\x20future.\x20Note\x20that\x20required\x20versions\x20in\x20<code>go.mod</code>\x20files\x20are\x0a<em>minimum\x20versions</em>\x20and\x20may\x20be\x20increased\x20automatically\x20as\x20new\x20dependencies\x20are\x0aadded.\x20See\x20<a\x20href=\"#minimal-version-selection\">Minimal\x20version\x20selection\x20(MVS)</a>\x20for\x0adetails\x20on\x20how\x20versions\x20are\x20selected\x20and\x20conflicts\x20are\x20resolved\x20by\x20module-aware\x0acommands.</p>\x0a<!--\x20TODO(jayconrod):\x20add\x20diagrams\x20for\x20the\x20examples\x20below.\x0aWe\x20need\x20a\x20consistent\x20strategy\x20for\x20visualizing\x20module\x20graphs\x20here,\x20in\x20the\x20MVS\x0asection,\x20and\x20perhaps\x20in\x20other\x20documentation\x20(blog\x20posts,\x20etc.).\x0a-->\x0a<p>Other\x20modules\x20may\x20be\x20upgraded\x20when\x20a\x20module\x20named\x20on\x20the\x20command\x20line\x20is\x20added,\x0aupgraded,\x20or\x20downgraded\x20if\x20the\x20new\x20version\x20of\x20the\x20named\x20module\x20requires\x20other\x0amodules\x20at\x20higher\x20versions.\x20For\x20example,\x20suppose\x20module\x20<code>example.com/a</code>\x20is\x0aupgraded\x20to\x20version\x20<code>v1.5.0</code>,\x20and\x20that\x20version\x20requires\x20module\x20<code>example.com/b</code>\x0aat\x20version\x20<code>v1.2.0</code>.\x20If\x20module\x20<code>example.com/b</code>\x20is\x20currently\x20required\x20at\x20version\x0a<code>v1.1.0</code>,\x20<code>go\x20get\x20example.com/a@v1.5.0</code>\x20will\x20also\x20upgrade\x20<code>example.com/b</code>\x20to\x0a<code>v1.2.0</code>.</p>\x0a<p>Other\x20modules\x20may\x20be\x20downgraded\x20when\x20a\x20module\x20named\x20on\x20the\x20command\x20line\x20is\x0adowngraded\x20or\x20removed.\x20To\x20continue\x20the\x20above\x20example,\x20suppose\x20module\x0a<code>example.com/b</code>\x20is\x20downgraded\x20to\x20<code>v1.1.0</code>.\x20Module\x20<code>example.com/a</code>\x20would\x20also\x20be\x0adowngraded\x20to\x20a\x20version\x20that\x20requires\x20<code>example.com/b</code>\x20at\x20version\x20<code>v1.1.0</code>\x20or\x0alower.</p>\x0a<p>A\x20module\x20requirement\x20may\x20be\x20removed\x20using\x20the\x20version\x20suffix\x20<code>@none</code>.\x20This\x20is\x20a\x0aspecial\x20kind\x20of\x20downgrade.\x20Modules\x20that\x20depend\x20on\x20the\x20removed\x20module\x20will\x20be\x0adowngraded\x20or\x20removed\x20as\x20needed.\x20A\x20module\x20requirement\x20may\x20be\x20removed\x20even\x20if\x20one\x0aor\x20more\x20of\x20its\x20packages\x20are\x20imported\x20by\x20packages\x20in\x20the\x20main\x20module.\x20In\x20this\x0acase,\x20the\x20next\x20build\x20command\x20may\x20add\x20a\x20new\x20module\x20requirement.</p>\x0a<p>If\x20a\x20module\x20is\x20needed\x20at\x20two\x20different\x20versions\x20(specified\x20explicitly\x20in\x20command\x0aline\x20arguments\x20or\x20to\x20satisfy\x20upgrades\x20and\x20downgrades),\x20<code>go\x20get</code>\x20will\x20report\x20an\x0aerror.</p>\x0a<p>After\x20<code>go\x20get</code>\x20updates\x20the\x20<code>go.mod</code>\x20file,\x20it\x20builds\x20the\x20packages\x20named\x0aon\x20the\x20command\x20line.\x20Executables\x20will\x20be\x20installed\x20in\x20the\x20directory\x20named\x20by\x0athe\x20<code>GOBIN</code>\x20environment\x20variable,\x20which\x20defaults\x20to\x20<code>$GOPATH/bin</code>\x20or\x0a<code>$HOME/go/bin</code>\x20if\x20the\x20<code>GOPATH</code>\x20environment\x20variable\x20is\x20not\x20set.</p>\x0a<p><code>go\x20get</code>\x20supports\x20the\x20following\x20flags:</p>\x0a<ul>\x0a<li>The\x20<code>-d</code>\x20flag\x20tells\x20<code>go\x20get</code>\x20not\x20to\x20build\x20or\x20install\x20packages.\x20When\x20<code>-d</code>\x20is\x0aused,\x20<code>go\x20get</code>\x20will\x20only\x20manage\x20dependencies\x20in\x20<code>go.mod</code>.</li>\x0a<li>The\x20<code>-u</code>\x20flag\x20tells\x20<code>go\x20get</code>\x20to\x20upgrade\x20modules\x20providing\x20packages\x0aimported\x20directly\x20or\x20indirectly\x20by\x20packages\x20named\x20on\x20the\x20command\x20line.\x0aEach\x20module\x20selected\x20by\x20<code>-u</code>\x20will\x20be\x20upgraded\x20to\x20its\x20latest\x20version\x20unless\x0ait\x20is\x20already\x20required\x20at\x20a\x20higher\x20version\x20(a\x20pre-release).</li>\x0a<li>The\x20<code>-u=patch</code>\x20flag\x20(not\x20<code>-u\x20patch</code>)\x20also\x20tells\x20<code>go\x20get</code>\x20to\x20upgrade\x0adependencies,\x20but\x20<code>go\x20get</code>\x20will\x20upgrade\x20each\x20dependency\x20to\x20the\x20latest\x20patch\x0aversion\x20(similar\x20to\x20the\x20<code>@patch</code>\x20version\x20query).</li>\x0a<li>The\x20<code>-t</code>\x20flag\x20tells\x20<code>go\x20get</code>\x20to\x20consider\x20modules\x20needed\x20to\x20build\x20tests\x0aof\x20packages\x20named\x20on\x20the\x20command\x20line.\x20When\x20<code>-t</code>\x20and\x20<code>-u</code>\x20are\x20used\x20together,\x0a<code>go\x20get</code>\x20will\x20update\x20test\x20dependencies\x20as\x20well.</li>\x0a<li>The\x20<code>-insecure</code>\x20flag\x20should\x20no\x20longer\x20be\x20used.\x20It\x20permits\x20<code>go\x20get</code>\x20to\x20resolve\x0acustom\x20import\x20paths\x20and\x20fetch\x20from\x20repositories\x20and\x20module\x20proxies\x20using\x0ainsecure\x20schemes\x20such\x20as\x20HTTP.\x20The\x20<code>GOINSECURE</code>\x20<a\x20href=\"#environment-variables\">environment\x0avariable</a>\x20provides\x20more\x20fine-grained\x20control\x20and\x0ashould\x20be\x20used\x20instead.</li>\x0a</ul>\x0a<p><a\x20id=\"go-list-m\"></a></p>\x0a<h3><code>go\x20list\x20-m</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20list\x20-m\x20[-u]\x20[-versions]\x20[list\x20flags]\x20[modules]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>$\x20go\x20list\x20-m\x20all\x0a$\x20go\x20list\x20-m\x20-versions\x20example.com/m\x0a$\x20go\x20list\x20-m\x20-json\x20example.com/m@latest\x0a</code></pre>\x0a<p>The\x20<code>-m</code>\x20flag\x20causes\x20<code>go\x20list</code>\x20to\x20list\x20modules\x20instead\x20of\x20packages.\x20In\x20this\x0amode,\x20the\x20arguments\x20to\x20<code>go\x20list</code>\x20may\x20be\x20modules,\x20module\x20patterns\x20(containing\x20the\x0a<code>...</code>\x20wildcard),\x20<a\x20href=\"#version-queries\">version\x20queries</a>,\x20or\x20the\x20special\x20pattern\x0a<code>all</code>,\x20which\x20matches\x20all\x20modules\x20in\x20the\x20<a\x20href=\"#glos-build-list\">build\x20list</a>.\x20If\x20no\x0aarguments\x20are\x20specified,\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module</a>\x20is\x20listed.</p>\x0a<p>When\x20listing\x20modules,\x20the\x20<code>-f</code>\x20flag\x20still\x20specifies\x20a\x20format\x20template\x20applied\x0ato\x20a\x20Go\x20struct,\x20but\x20now\x20a\x20<code>Module</code>\x20struct:</p>\x0a<pre><code>type\x20Module\x20struct\x20{\x0a\x20\x20\x20\x20Path\x20\x20\x20\x20\x20\x20string\x20\x20\x20\x20\x20\x20\x20//\x20module\x20path\x0a\x20\x20\x20\x20Version\x20\x20\x20string\x20\x20\x20\x20\x20\x20\x20//\x20module\x20version\x0a\x20\x20\x20\x20Versions\x20\x20[]string\x20\x20\x20\x20\x20//\x20available\x20module\x20versions\x20(with\x20-versions)\x0a\x20\x20\x20\x20Replace\x20\x20\x20*Module\x20\x20\x20\x20\x20\x20//\x20replaced\x20by\x20this\x20module\x0a\x20\x20\x20\x20Time\x20\x20\x20\x20\x20\x20*time.Time\x20\x20\x20//\x20time\x20version\x20was\x20created\x0a\x20\x20\x20\x20Update\x20\x20\x20\x20*Module\x20\x20\x20\x20\x20\x20//\x20available\x20update,\x20if\x20any\x20(with\x20-u)\x0a\x20\x20\x20\x20Main\x20\x20\x20\x20\x20\x20bool\x20\x20\x20\x20\x20\x20\x20\x20\x20//\x20is\x20this\x20the\x20main\x20module?\x0a\x20\x20\x20\x20Indirect\x20\x20bool\x20\x20\x20\x20\x20\x20\x20\x20\x20//\x20is\x20this\x20module\x20only\x20an\x20indirect\x20dependency\x20of\x20main\x20module?\x0a\x20\x20\x20\x20Dir\x20\x20\x20\x20\x20\x20\x20string\x20\x20\x20\x20\x20\x20\x20//\x20directory\x20holding\x20files\x20for\x20this\x20module,\x20if\x20any\x0a\x20\x20\x20\x20GoMod\x20\x20\x20\x20\x20string\x20\x20\x20\x20\x20\x20\x20//\x20path\x20to\x20go.mod\x20file\x20for\x20this\x20module,\x20if\x20any\x0a\x20\x20\x20\x20GoVersion\x20string\x20\x20\x20\x20\x20\x20\x20//\x20go\x20version\x20used\x20in\x20module\x0a\x20\x20\x20\x20Error\x20\x20\x20\x20\x20*ModuleError\x20//\x20error\x20loading\x20module\x0a}\x0a\x0atype\x20ModuleError\x20struct\x20{\x0a\x20\x20\x20\x20Err\x20string\x20//\x20the\x20error\x20itself\x0a}\x0a</code></pre>\x0a<p>The\x20default\x20output\x20is\x20to\x20print\x20the\x20module\x20path\x20and\x20then\x20information\x20about\x20the\x0aversion\x20and\x20replacement\x20if\x20any.\x20For\x20example,\x20<code>go\x20list\x20-m\x20all</code>\x20might\x20print:</p>\x0a<pre><code>example.com/main/module\x0agolang.org/x/text\x20v0.3.0\x20=&gt;\x20/tmp/text\x0arsc.io/pdf\x20v0.1.1\x0a</code></pre>\x0a<p>The\x20<code>Module</code>\x20struct\x20has\x20a\x20<code>String</code>\x20method\x20that\x20formats\x20this\x20line\x20of\x20output,\x20so\x0athat\x20the\x20default\x20format\x20is\x20equivalent\x20to\x20<code>-f\x20'{{.String}}'</code>.</p>\x0a<p>Note\x20that\x20when\x20a\x20module\x20has\x20been\x20replaced,\x20its\x20<code>Replace</code>\x20field\x20describes\x20the\x0areplacement\x20module\x20module,\x20and\x20its\x20<code>Dir</code>\x20field\x20is\x20set\x20to\x20the\x20replacement\x0amodule's\x20source\x20code,\x20if\x20present.\x20(That\x20is,\x20if\x20<code>Replace</code>\x20is\x20non-nil,\x20then\x20<code>Dir</code>\x0ais\x20set\x20to\x20<code>Replace.Dir</code>,\x20with\x20no\x20access\x20to\x20the\x20replaced\x20source\x20code.)</p>\x0a<p>The\x20<code>-u</code>\x20flag\x20adds\x20information\x20about\x20available\x20upgrades.\x20When\x20the\x20latest\x20version\x0aof\x20a\x20given\x20module\x20is\x20newer\x20than\x20the\x20current\x20one,\x20<code>list\x20-u</code>\x20sets\x20the\x20module's\x0a<code>Update</code>\x20field\x20to\x20information\x20about\x20the\x20newer\x20module.\x20The\x20module's\x20<code>String</code>\x0amethod\x20indicates\x20an\x20available\x20upgrade\x20by\x20formatting\x20the\x20newer\x20version\x20in\x0abrackets\x20after\x20the\x20current\x20version.\x20For\x20example,\x20<code>go\x20list\x20-m\x20-u\x20all</code>\x20might\x0aprint:</p>\x0a<pre><code>example.com/main/module\x0agolang.org/x/text\x20v0.3.0\x20[v0.4.0]\x20=&gt;\x20/tmp/text\x0arsc.io/pdf\x20v0.1.1\x20[v0.1.2]\x0a</code></pre>\x0a<p>(For\x20tools,\x20<code>go\x20list\x20-m\x20-u\x20-json\x20all</code>\x20may\x20be\x20more\x20convenient\x20to\x20parse.)</p>\x0a<p>The\x20<code>-versions</code>\x20flag\x20causes\x20<code>list</code>\x20to\x20set\x20the\x20module's\x20<code>Versions</code>\x20field\x20to\x20a\x0alist\x20of\x20all\x20known\x20versions\x20of\x20that\x20module,\x20ordered\x20according\x20to\x20semantic\x0aversioning,\x20lowest\x20to\x20highest.\x20The\x20flag\x20also\x20changes\x20the\x20default\x20output\x20format\x0ato\x20display\x20the\x20module\x20path\x20followed\x20by\x20the\x20space-separated\x20version\x20list.</p>\x0a<p>The\x20template\x20function\x20<code>module</code>\x20takes\x20a\x20single\x20string\x20argument\x20that\x20must\x20be\x20a\x0amodule\x20path\x20or\x20query\x20and\x20returns\x20the\x20specified\x20module\x20as\x20a\x20<code>Module</code>\x20struct.\x20If\x0aan\x20error\x20occurs,\x20the\x20result\x20will\x20be\x20a\x20<code>Module</code>\x20struct\x20with\x20a\x20non-nil\x20<code>Error</code>\x0afield.</p>\x0a<p><a\x20id=\"go-mod-download\"></a></p>\x0a<h3><code>go\x20mod\x20download</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20download\x20[-json]\x20[-x]\x20[modules]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>$\x20go\x20mod\x20download\x0a$\x20go\x20mod\x20download\x20golang.org/x/mod@v0.2.0\x0a</code></pre>\x0a<p>The\x20<code>go\x20mod\x20download</code>\x20command\x20downloads\x20the\x20named\x20modules\x20into\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>.\x20Arguments\x20can\x20be\x20module\x20paths\x20or\x20module\x0apatterns\x20selecting\x20dependencies\x20of\x20the\x20main\x20module\x20or\x20<a\x20href=\"#version-queries\">version\x0aqueries</a>\x20of\x20the\x20form\x20<code>path@version</code>.\x20With\x20no\x20arguments,\x0a<code>download</code>\x20applies\x20to\x20all\x20dependencies\x20of\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module</a>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20will\x20automatically\x20download\x20modules\x20as\x20needed\x20during\x20ordinary\x0aexecution.\x20The\x20<code>go\x20mod\x20download</code>\x20command\x20is\x20useful\x20mainly\x20for\x20pre-filling\x20the\x0amodule\x20cache\x20or\x20for\x20loading\x20data\x20to\x20be\x20served\x20by\x20a\x20<a\x20href=\"#glos-module-proxy\">module\x0aproxy</a>.</p>\x0a<p>By\x20default,\x20<code>download</code>\x20writes\x20nothing\x20to\x20standard\x20output.\x20It\x20prints\x20progress\x0amessages\x20and\x20errors\x20to\x20standard\x20error.</p>\x0a<p>The\x20<code>-json</code>\x20flag\x20causes\x20<code>download</code>\x20to\x20print\x20a\x20sequence\x20of\x20JSON\x20objects\x20to\x0astandard\x20output,\x20describing\x20each\x20downloaded\x20module\x20(or\x20failure),\x20corresponding\x0ato\x20this\x20Go\x20struct:</p>\x0a<pre><code>type\x20Module\x20struct\x20{\x0a\x20\x20\x20\x20Path\x20\x20\x20\x20\x20string\x20//\x20module\x20path\x0a\x20\x20\x20\x20Version\x20\x20string\x20//\x20module\x20version\x0a\x20\x20\x20\x20Error\x20\x20\x20\x20string\x20//\x20error\x20loading\x20module\x0a\x20\x20\x20\x20Info\x20\x20\x20\x20\x20string\x20//\x20absolute\x20path\x20to\x20cached\x20.info\x20file\x0a\x20\x20\x20\x20GoMod\x20\x20\x20\x20string\x20//\x20absolute\x20path\x20to\x20cached\x20.mod\x20file\x0a\x20\x20\x20\x20Zip\x20\x20\x20\x20\x20\x20string\x20//\x20absolute\x20path\x20to\x20cached\x20.zip\x20file\x0a\x20\x20\x20\x20Dir\x20\x20\x20\x20\x20\x20string\x20//\x20absolute\x20path\x20to\x20cached\x20source\x20root\x20directory\x0a\x20\x20\x20\x20Sum\x20\x20\x20\x20\x20\x20string\x20//\x20checksum\x20for\x20path,\x20version\x20(as\x20in\x20go.sum)\x0a\x20\x20\x20\x20GoModSum\x20string\x20//\x20checksum\x20for\x20go.mod\x20(as\x20in\x20go.sum)\x0a}\x0a</code></pre>\x0a<p>The\x20<code>-x</code>\x20flag\x20causes\x20<code>download</code>\x20to\x20print\x20the\x20commands\x20<code>download</code>\x20executes\x0ato\x20standard\x20error.</p>\x0a<p><a\x20id=\"go-mod-edit\"></a></p>\x0a<h3><code>go\x20mod\x20edit</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20edit\x20[editing\x20flags]\x20[-fmt|-print|-json]\x20[go.mod]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>#\x20Add\x20a\x20replace\x20directive.\x0a$\x20go\x20mod\x20edit\x20-replace\x20example.com/a@v1.0.0=./a\x0a\x0a#\x20Remove\x20a\x20replace\x20directive.\x0a$\x20go\x20mod\x20edit\x20-dropreplace\x20example.com/a@v1.0.0\x0a\x0a#\x20Set\x20the\x20go\x20version,\x20add\x20a\x20requirement,\x20and\x20print\x20the\x20file\x0a#\x20instead\x20of\x20writing\x20it\x20to\x20disk.\x0a$\x20go\x20mod\x20edit\x20-go=1.14\x20-require=example.com/m@v1.0.0\x20-print\x0a\x0a#\x20Format\x20the\x20go.mod\x20file.\x0a$\x20go\x20mod\x20edit\x20-fmt\x0a\x0a#\x20Format\x20and\x20print\x20a\x20different\x20.mod\x20file.\x0a$\x20go\x20mod\x20edit\x20-print\x20tools.mod\x0a\x0a#\x20Print\x20a\x20JSON\x20representation\x20of\x20the\x20go.mod\x20file.\x0a$\x20go\x20mod\x20edit\x20-json\x0a</code></pre>\x0a<p>The\x20<code>go\x20mod\x20edit</code>\x20command\x20provides\x20a\x20command-line\x20interface\x20for\x20editing\x20and\x0aformatting\x20<code>go.mod</code>\x20files,\x20for\x20use\x20primarily\x20by\x20tools\x20and\x20scripts.\x20<code>go\x20mod\x20edit</code>\x0areads\x20only\x20one\x20<code>go.mod</code>\x20file;\x20it\x20does\x20not\x20look\x20up\x20information\x20about\x20other\x0amodules.\x20By\x20default,\x20<code>go\x20mod\x20edit</code>\x20reads\x20and\x20writes\x20the\x20<code>go.mod</code>\x20file\x20of\x20the\x0amain\x20module,\x20but\x20a\x20different\x20target\x20file\x20can\x20be\x20specified\x20after\x20the\x20editing\x0aflags.</p>\x0a<p>The\x20editing\x20flags\x20specify\x20a\x20sequence\x20of\x20editing\x20operations.</p>\x0a<ul>\x0a<li>The\x20<code>-module</code>\x20flag\x20changes\x20the\x20module's\x20path\x20(the\x20<code>go.mod</code>\x20file's\x20module\x0aline).</li>\x0a<li>The\x20<code>-go=version</code>\x20flag\x20sets\x20the\x20expected\x20Go\x20language\x20version.</li>\x0a<li>The\x20<code>-require=path@version</code>\x20and\x20<code>-droprequire=path</code>\x20flags\x20add\x20and\x20drop\x20a\x0arequirement\x20on\x20the\x20given\x20module\x20path\x20and\x20version.\x20Note\x20that\x20<code>-require</code>\x0aoverrides\x20any\x20existing\x20requirements\x20on\x20<code>path</code>.\x20These\x20flags\x20are\x20mainly\x20for\x0atools\x20that\x20understand\x20the\x20module\x20graph.\x20Users\x20should\x20prefer\x20<code>go\x20get\x20path@version</code>\x20or\x20<code>go\x20get\x20path@none</code>,\x20which\x20make\x20other\x20<code>go.mod</code>\x20adjustments\x20as\x0aneeded\x20to\x20satisfy\x20constraints\x20imposed\x20by\x20other\x20modules.\x20See\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>.</li>\x0a<li>The\x20<code>-exclude=path@version</code>\x20and\x20<code>-dropexclude=path@version</code>\x20flags\x20add\x20and\x20drop\x0aan\x20exclusion\x20for\x20the\x20given\x20module\x20path\x20and\x20version.\x20Note\x20that\x0a<code>-exclude=path@version</code>\x20is\x20a\x20no-op\x20if\x20that\x20exclusion\x20already\x20exists.</li>\x0a<li>The\x20<code>-replace=old[@v]=new[@v]</code>\x20flag\x20adds\x20a\x20replacement\x20of\x20the\x20given\x20module\x0apath\x20and\x20version\x20pair.\x20If\x20the\x20<code>@v</code>\x20in\x20<code>old@v</code>\x20is\x20omitted,\x20a\x20replacement\x0awithout\x20a\x20version\x20on\x20the\x20left\x20side\x20is\x20added,\x20which\x20applies\x20to\x20all\x20versions\x20of\x0athe\x20old\x20module\x20path.\x20If\x20the\x20<code>@v</code>\x20in\x20<code>new@v</code>\x20is\x20omitted,\x20the\x20new\x20path\x20should\x20be\x0aa\x20local\x20module\x20root\x20directory,\x20not\x20a\x20module\x20path.\x20Note\x20that\x20<code>-replace</code>\x0aoverrides\x20any\x20redundant\x20replacements\x20for\x20<code>old[@v]</code>,\x20so\x20omitting\x20<code>@v</code>\x20will\x20drop\x0areplacements\x20for\x20specific\x20versions.</li>\x0a<li>The\x20<code>-dropreplace=old[@v]</code>\x20flag\x20drops\x20a\x20replacement\x20of\x20the\x20given\x20module\x20path\x0aand\x20version\x20pair.\x20If\x20the\x20<code>@v</code>\x20is\x20provided,\x20a\x20replacement\x20with\x20the\x20given\x0aversion\x20is\x20dropped.\x20An\x20existing\x20replacement\x20without\x20a\x20version\x20on\x20the\x20left\x20side\x0amay\x20still\x20replace\x20the\x20module.\x20If\x20the\x20<code>@v</code>\x20is\x20omitted,\x20a\x20replacement\x20without\x20a\x0aversion\x20is\x20dropped.</li>\x0a</ul>\x0a<p>The\x20editing\x20flags\x20may\x20be\x20repeated.\x20The\x20changes\x20are\x20applied\x20in\x20the\x20order\x20given.</p>\x0a<p><code>go\x20mod\x20edit</code>\x20has\x20additional\x20flags\x20that\x20control\x20its\x20output.</p>\x0a<ul>\x0a<li>The\x20<code>-fmt</code>\x20flag\x20reformats\x20the\x20<code>go.mod</code>\x20file\x20without\x20making\x20other\x20changes.\x0aThis\x20reformatting\x20is\x20also\x20implied\x20by\x20any\x20other\x20modifications\x20that\x20use\x20or\x0arewrite\x20the\x20<code>go.mod</code>\x20file.\x20The\x20only\x20time\x20this\x20flag\x20is\x20needed\x20is\x20if\x20no\x0aother\x20flags\x20are\x20specified,\x20as\x20in\x20<code>go\x20mod\x20edit\x20-fmt</code>.</li>\x0a<li>The\x20<code>-print</code>\x20flag\x20prints\x20the\x20final\x20<code>go.mod</code>\x20in\x20its\x20text\x20format\x20instead\x20of\x0awriting\x20it\x20back\x20to\x20disk.</li>\x0a<li>The\x20<code>-json</code>\x20flag\x20prints\x20the\x20final\x20<code>go.mod</code>\x20in\x20JSON\x20format\x20instead\x20of\x20writing\x0ait\x20back\x20to\x20disk\x20in\x20text\x20format.\x20The\x20JSON\x20output\x20corresponds\x20to\x20these\x20Go\x20types:</li>\x0a</ul>\x0a<pre><code>type\x20Module\x20struct\x20{\x0a\x20\x20\x20\x20\x20\x20\x20\x20Path\x20string\x0a\x20\x20\x20\x20\x20\x20\x20\x20Version\x20string\x0a}\x0a\x0atype\x20GoMod\x20struct\x20{\x0a\x20\x20\x20\x20\x20\x20\x20\x20Module\x20\x20Module\x0a\x20\x20\x20\x20\x20\x20\x20\x20Go\x20\x20\x20\x20\x20\x20string\x0a\x20\x20\x20\x20\x20\x20\x20\x20Require\x20[]Require\x0a\x20\x20\x20\x20\x20\x20\x20\x20Exclude\x20[]Module\x0a\x20\x20\x20\x20\x20\x20\x20\x20Replace\x20[]Replace\x0a}\x0a\x0atype\x20Require\x20struct\x20{\x0a\x20\x20\x20\x20\x20\x20\x20\x20Path\x20string\x0a\x20\x20\x20\x20\x20\x20\x20\x20Version\x20string\x0a\x20\x20\x20\x20\x20\x20\x20\x20Indirect\x20bool\x0a}\x0a\x0atype\x20Replace\x20struct\x20{\x0a\x20\x20\x20\x20\x20\x20\x20\x20Old\x20Module\x0a\x20\x20\x20\x20\x20\x20\x20\x20New\x20Module\x0a}\x0a</code></pre>\x0a<p>Note\x20that\x20this\x20only\x20describes\x20the\x20<code>go.mod</code>\x20file\x20itself,\x20not\x20other\x20modules\x0areferred\x20to\x20indirectly.\x20For\x20the\x20full\x20set\x20of\x20modules\x20available\x20to\x20a\x20build,\x0ause\x20<code>go\x20list\x20-m\x20-json\x20all</code>.\x20See\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>.</p>\x0a<p>For\x20example,\x20a\x20tool\x20can\x20obtain\x20the\x20<code>go.mod</code>\x20file\x20as\x20a\x20data\x20structure\x20by\x0aparsing\x20the\x20output\x20of\x20<code>go\x20mod\x20edit\x20-json</code>\x20and\x20can\x20then\x20make\x20changes\x20by\x20invoking\x0a<code>go\x20mod\x20edit</code>\x20with\x20<code>-require</code>,\x20<code>-exclude</code>,\x20and\x20so\x20on.</p>\x0a<p>Tools\x20may\x20also\x20use\x20the\x20package\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/modfile?tab=doc\"><code>golang.org/x/mod/modfile</code></a>\x0ato\x20parse,\x20edit,\x20and\x20format\x20<code>go.mod</code>\x20files.</p>\x0a<p><a\x20id=\"go-mod-init\"></a></p>\x0a<h3><code>go\x20mod\x20init</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20init\x20[module-path]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>go\x20mod\x20init\x0ago\x20mod\x20init\x20example.com/m\x0a</code></pre>\x0a<p>The\x20<code>go\x20mod\x20init</code>\x20command\x20initializes\x20and\x20writes\x20a\x20new\x20<code>go.mod</code>\x20file\x20in\x20the\x0acurrent\x20directory,\x20in\x20effect\x20creating\x20a\x20new\x20module\x20rooted\x20at\x20the\x20current\x0adirectory.\x20The\x20<code>go.mod</code>\x20file\x20must\x20not\x20already\x20exist.</p>\x0a<p><code>init</code>\x20accepts\x20one\x20optional\x20argument,\x20the\x20<a\x20href=\"#glos-module-path\">module\x20path</a>\x20for\x0athe\x20new\x20module.\x20See\x20<a\x20href=\"#module-path\">Module\x20paths</a>\x20for\x20instructions\x20on\x20choosing\x0aa\x20module\x20path.\x20If\x20the\x20module\x20path\x20argument\x20is\x20omitted,\x20<code>init</code>\x20will\x20attempt\x0ato\x20infer\x20the\x20module\x20path\x20using\x20import\x20comments\x20in\x20<code>.go</code>\x20files,\x20vendoring\x20tool\x0aconfiguration\x20files,\x20and\x20the\x20current\x20directory\x20(if\x20in\x20<code>GOPATH</code>).</p>\x0a<p>If\x20a\x20configuration\x20file\x20for\x20a\x20vendoring\x20tool\x20is\x20present,\x20<code>init</code>\x20will\x20attempt\x20to\x0aimport\x20module\x20requirements\x20from\x20it.\x20<code>init</code>\x20supports\x20the\x20following\x20configuration\x0afiles.</p>\x0a<ul>\x0a<li><code>GLOCKFILE</code>\x20(Glock)</li>\x0a<li><code>Godeps/Godeps.json</code>\x20(Godeps)</li>\x0a<li><code>Gopkg.lock</code>\x20(dep)</li>\x0a<li><code>dependencies.tsv</code>\x20(godeps)</li>\x0a<li><code>glide.lock</code>\x20(glide)</li>\x0a<li><code>vendor.conf</code>\x20(trash)</li>\x0a<li><code>vendor.yml</code>\x20(govend)</li>\x0a<li><code>vendor/manifest</code>\x20(gvt)</li>\x0a<li><code>vendor/vendor.json</code>\x20(govendor)</li>\x0a</ul>\x0a<p>Vendoring\x20tool\x20configuration\x20files\x20can't\x20always\x20be\x20translated\x20with\x20perfect\x0afidelity.\x20For\x20example,\x20if\x20multiple\x20packages\x20within\x20the\x20same\x20repository\x20are\x0aimported\x20at\x20different\x20versions,\x20and\x20the\x20repository\x20only\x20contains\x20one\x20module,\x20the\x0aimported\x20<code>go.mod</code>\x20can\x20only\x20require\x20the\x20module\x20at\x20one\x20version.\x20You\x20may\x20wish\x20to\x0arun\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m\x20all</code></a>\x20to\x20check\x20all\x20versions\x20in\x20the\x20<a\x20href=\"#glos-build-list\">build\x0alist</a>,\x20and\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20to\x20add\x20missing\x0arequirements\x20and\x20to\x20drop\x20unused\x20requirements.</p>\x0a<p><a\x20id=\"go-mod-tidy\"></a></p>\x0a<h3><code>go\x20mod\x20tidy</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20tidy\x20[-v]\x0a</code></pre>\x0a<p><code>go\x20mod\x20tidy</code>\x20ensures\x20that\x20the\x20<code>go.mod</code>\x20file\x20matches\x20the\x20source\x20code\x20in\x20the\x0amodule.\x20It\x20adds\x20any\x20missing\x20module\x20requirements\x20necessary\x20to\x20build\x20the\x20current\x0amodule's\x20packages\x20and\x20dependencies,\x20and\x20it\x20removes\x20requirements\x20on\x20modules\x20that\x0adon't\x20provide\x20any\x20relevant\x20packages.\x20It\x20also\x20adds\x20any\x20missing\x20entries\x20to\x0a<code>go.sum</code>\x20and\x20removes\x20unnecessary\x20entries.</p>\x0a<p>The\x20<code>-v</code>\x20flag\x20causes\x20<code>go\x20mod\x20tidy</code>\x20to\x20print\x20information\x20about\x20removed\x20modules\x0ato\x20standard\x20error.</p>\x0a<p><code>go\x20mod\x20tidy</code>\x20works\x20by\x20loading\x20all\x20of\x20the\x20packages\x20in\x20the\x20<a\x20href=\"#glos-main-module\">main\x0amodule</a>\x20and\x20all\x20of\x20the\x20packages\x20they\x20import,\x0arecursively.\x20This\x20includes\x20packages\x20imported\x20by\x20tests\x20(including\x20tests\x20in\x20other\x0amodules).\x20<code>go\x20mod\x20tidy</code>\x20acts\x20as\x20if\x20all\x20build\x20tags\x20are\x20enabled,\x20so\x20it\x20will\x0aconsider\x20platform-specific\x20source\x20files\x20and\x20files\x20that\x20require\x20custom\x20build\x0atags,\x20even\x20if\x20those\x20source\x20files\x20wouldn't\x20normally\x20be\x20built.\x20There\x20is\x20one\x0aexception:\x20the\x20<code>ignore</code>\x20build\x20tag\x20is\x20not\x20enabled,\x20so\x20a\x20file\x20with\x20the\x20build\x0aconstraint\x20<code>//\x20+build\x20ignore</code>\x20will\x20not\x20be\x20considered.\x20Note\x20that\x20<code>go\x20mod\x20tidy</code>\x0awill\x20not\x20consider\x20packages\x20in\x20the\x20main\x20module\x20in\x20directories\x20named\x20<code>testdata</code>\x20or\x0awith\x20names\x20that\x20start\x20with\x20<code>.</code>\x20or\x20<code>_</code>\x20unless\x20those\x20packages\x20are\x20explicitly\x0aimported\x20by\x20other\x20packages.</p>\x0a<p>Once\x20<code>go\x20mod\x20tidy</code>\x20has\x20loaded\x20this\x20set\x20of\x20packages,\x20it\x20ensures\x20that\x20each\x20module\x0athat\x20provides\x20one\x20or\x20more\x20packages\x20either\x20has\x20a\x20<code>require</code>\x20directive\x20in\x20the\x20main\x0amodule's\x20<code>go.mod</code>\x20file\x20or\x20is\x20required\x20by\x20another\x20required\x20module.\x20\x20<code>go\x20mod\x20tidy</code>\x0awill\x20add\x20a\x20requirement\x20on\x20the\x20latest\x20version\x20on\x20each\x20missing\x20module\x20(see\x0a<a\x20href=\"#version-queries\">Version\x20queries</a>\x20for\x20the\x20definition\x20of\x20the\x20<code>latest</code>\x0aversion).\x20<code>go\x20mod\x20tidy</code>\x20will\x20remove\x20<code>require</code>\x20directives\x20for\x20modules\x20that\x20don't\x0aprovide\x20any\x20packages\x20in\x20the\x20set\x20described\x20above.</p>\x0a<p><code>go\x20mod\x20tidy</code>\x20may\x20also\x20add\x20or\x20remove\x20<code>//\x20indirect</code>\x20comments\x20on\x20<code>require</code>\x0adirectives.\x20An\x20<code>//\x20indirect</code>\x20comment\x20denotes\x20a\x20module\x20that\x20does\x20not\x20provide\x0apackages\x20imported\x20by\x20packages\x20in\x20the\x20main\x20module.\x20These\x20requirements\x20will\x20be\x0apresent\x20if\x20the\x20module\x20that\x20imports\x20packages\x20in\x20the\x20indirect\x20dependency\x20has\x0ano\x20<code>go.mod</code>\x20file.\x20They\x20may\x20also\x20be\x20present\x20if\x20the\x20indirect\x20dependency\x20is\x0arequired\x20at\x20a\x20higher\x20version\x20than\x20is\x20implied\x20by\x20the\x20module\x20graph;\x20this\x20usually\x0ahappens\x20after\x20running\x20a\x20command\x20like\x20<code>go\x20get\x20-u\x20./...</code>.</p>\x0a<p><a\x20id=\"go-mod-vendor\"></a></p>\x0a<h3><code>go\x20mod\x20vendor</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20vendor\x20[-v]\x0a</code></pre>\x0a<p>The\x20<code>go\x20mod\x20vendor</code>\x20command\x20constructs\x20a\x20directory\x20named\x20<code>vendor</code>\x20in\x20the\x20<a\x20href=\"#glos-main-module\">main\x0amodule's</a>\x20root\x20directory\x20that\x20contains\x20copies\x20of\x20all\x20packages\x0aneeded\x20to\x20support\x20builds\x20and\x20tests\x20of\x20packages\x20in\x20the\x20main\x20module.\x20Packages\x0athat\x20are\x20only\x20imported\x20by\x20tests\x20of\x20packages\x20outside\x20the\x20main\x20module\x20are\x20not\x0aincluded.\x20As\x20with\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20and\x20other\x20module\x20commands,\x0a<a\x20href=\"#glos-build-constraint\">build\x20constraints</a>\x20except\x20for\x20<code>ignore</code>\x20are\x20not\x0aconsidered\x20when\x20constructing\x20the\x20<code>vendor</code>\x20directory.</p>\x0a<p>When\x20vendoring\x20is\x20enabled,\x20the\x20<code>go</code>\x20command\x20will\x20load\x20packages\x20from\x20the\x20<code>vendor</code>\x0adirectory\x20instead\x20of\x20downloading\x20modules\x20from\x20their\x20sources\x20into\x20the\x20module\x0acache\x20and\x20using\x20packages\x20those\x20downloaded\x20copies.\x20See\x20<a\x20href=\"#vendoring\">Vendoring</a>\x0afor\x20more\x20information.</p>\x0a<p><code>go\x20mod\x20vendor</code>\x20also\x20creates\x20the\x20file\x20<code>vendor/modules.txt</code>\x20that\x20contains\x20a\x20list\x0aof\x20vendored\x20packages\x20and\x20the\x20module\x20versions\x20they\x20were\x20copied\x20from.\x20When\x0avendoring\x20is\x20enabled,\x20this\x20manifest\x20is\x20used\x20as\x20a\x20source\x20of\x20module\x20version\x0ainformation,\x20as\x20reported\x20by\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>\x20and\x20<a\x20href=\"#go-version-m\"><code>go\x20version\x20-m</code></a>.\x20When\x20the\x20<code>go</code>\x20command\x20reads\x20<code>vendor/modules.txt</code>,\x20it\x20checks\x0athat\x20the\x20module\x20versions\x20are\x20consistent\x20with\x20<code>go.mod</code>.\x20If\x20<code>go.mod</code>\x20changed\x20since\x0a<code>vendor/modules.txt</code>\x20was\x20generated,\x20<code>go\x20mod\x20vendor</code>\x20should\x20be\x20run\x20again.</p>\x0a<p>Note\x20that\x20<code>go\x20mod\x20vendor</code>\x20removes\x20the\x20<code>vendor</code>\x20directory\x20if\x20it\x20exists\x20before\x0are-constructing\x20it.\x20Local\x20changes\x20should\x20not\x20be\x20made\x20to\x20vendored\x20packages.\x0aThe\x20<code>go</code>\x20command\x20does\x20not\x20check\x20that\x20packages\x20in\x20the\x20<code>vendor</code>\x20directory\x20have\x0anot\x20been\x20modified,\x20but\x20one\x20can\x20verify\x20the\x20integrity\x20of\x20the\x20<code>vendor</code>\x20directory\x0aby\x20running\x20<code>go\x20mod\x20vendor</code>\x20and\x20checking\x20that\x20no\x20changes\x20were\x20made.</p>\x0a<p>The\x20<code>-v</code>\x20flag\x20causes\x20<code>go\x20mod\x20vendor</code>\x20to\x20print\x20the\x20names\x20of\x20vendored\x20modules\x0aand\x20packages\x20to\x20standard\x20error.</p>\x0a<p><a\x20id=\"go-mod-verify\"></a></p>\x0a<h3><code>go\x20mod\x20verify</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20verify\x0a</code></pre>\x0a<p><code>go\x20mod\x20verify</code>\x20checks\x20that\x20dependencies\x20of\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module</a>\x0astored\x20in\x20the\x20<a\x20href=\"#glos-module-cache\">module\x20cache</a>\x20have\x20not\x20been\x20modified\x20since\x0athey\x20were\x20downloaded.\x20To\x20perform\x20this\x20check,\x20<code>go\x20mod\x20verify</code>\x20hashes\x20each\x0adownloaded\x20module\x20<a\x20href=\"#zip-files\"><code>.zip</code>\x20file</a>\x20and\x20extracted\x20directory,\x20then\x0acompares\x20those\x20hashes\x20with\x20a\x20hash\x20recorded\x20when\x20the\x20module\x20was\x20first\x0adownloaded.\x20<code>go\x20mod\x20verify</code>\x20checks\x20each\x20module\x20in\x20the\x20<a\x20href=\"#glos-build-list\">build\x0alist</a>\x20(which\x20may\x20be\x20printed\x20with\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m\x20all</code></a>).</p>\x0a<p>If\x20all\x20the\x20modules\x20are\x20unmodified,\x20<code>go\x20mod\x20verify</code>\x20prints\x20&quot;all\x20modules\x0averified&quot;.\x20Otherwise,\x20it\x20reports\x20which\x20modules\x20have\x20been\x20changed\x20and\x20exits\x20with\x0aa\x20non-zero\x20status.</p>\x0a<p>Note\x20that\x20all\x20module-aware\x20commands\x20verify\x20that\x20hashes\x20in\x20the\x20main\x20module's\x0a<code>go.sum</code>\x20file\x20match\x20hashes\x20recorded\x20for\x20modules\x20downloaded\x20into\x20the\x20module\x0acache.\x20If\x20a\x20hash\x20is\x20missing\x20from\x20<code>go.sum</code>\x20(for\x20example,\x20because\x20the\x20module\x20is\x0abeing\x20used\x20for\x20the\x20first\x20time),\x20the\x20<code>go</code>\x20command\x20verifies\x20its\x20hash\x20using\x20the\x0a<a\x20href=\"#checksum-database\">checksum\x20database</a>\x20(unless\x20the\x20module\x20path\x20is\x20matched\x20by\x0a<code>GOPRIVATE</code>\x20or\x20<code>GONOSUMDB</code>).\x20See\x20<a\x20href=\"#authenticating\">Authenticating\x20modules</a>\x20for\x0adetails.</p>\x0a<p>In\x20contrast,\x20<code>go\x20mod\x20verify</code>\x20checks\x20that\x20module\x20<code>.zip</code>\x20files\x20and\x20their\x20extracted\x0adirectories\x20have\x20hashes\x20that\x20match\x20hashes\x20recorded\x20in\x20the\x20module\x20cache\x20when\x20they\x0awere\x20first\x20downloaded.\x20This\x20is\x20useful\x20for\x20detecting\x20changes\x20to\x20files\x20in\x20the\x0amodule\x20cache\x20<em>after</em>\x20a\x20module\x20has\x20been\x20downloaded\x20and\x20verified.\x20<code>go\x20mod\x20verify</code>\x0adoes\x20not\x20download\x20content\x20for\x20modules\x20not\x20in\x20the\x20cache,\x20and\x20it\x20does\x20not\x20use\x0a<code>go.sum</code>\x20files\x20to\x20verify\x20module\x20content.\x20However,\x20<code>go\x20mod\x20verify</code>\x20may\x20download\x0a<code>go.mod</code>\x20files\x20in\x20order\x20to\x20perform\x20<a\x20href=\"#minimal-version-selection\">minimal\x20version\x0aselection</a>.\x20It\x20will\x20use\x20<code>go.sum</code>\x20to\x20verify\x20those\x0afiles,\x20and\x20it\x20may\x20add\x20<code>go.sum</code>\x20entries\x20for\x20missing\x20hashes.</p>\x0a<p><a\x20id=\"go-version-m\"></a></p>\x0a<h3><code>go\x20version\x20-m</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20version\x20[-m]\x20[-v]\x20[file\x20...]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>#\x20Print\x20Go\x20version\x20used\x20to\x20build\x20go.\x0a$\x20go\x20version\x0a\x0a#\x20Print\x20Go\x20version\x20used\x20to\x20build\x20a\x20specific\x20executable.\x0a$\x20go\x20version\x20~/go/bin/gopls\x0a\x0a#\x20Print\x20Go\x20version\x20and\x20module\x20versions\x20used\x20to\x20build\x20a\x20specific\x20executable.\x0a$\x20go\x20version\x20-m\x20~/go/bin/gopls\x0a\x0a#\x20Print\x20Go\x20version\x20and\x20module\x20versions\x20used\x20to\x20build\x20executables\x20in\x20a\x20directory.\x0a$\x20go\x20version\x20-m\x20~/go/bin/\x0a</code></pre>\x0a<p><code>go\x20version</code>\x20reports\x20the\x20Go\x20version\x20used\x20to\x20build\x20each\x20executable\x20file\x20named\x0aon\x20the\x20command\x20line.</p>\x0a<p>If\x20no\x20files\x20are\x20named\x20on\x20the\x20command\x20line,\x20<code>go\x20version</code>\x20prints\x20its\x20own\x20version\x0ainformation.</p>\x0a<p>If\x20a\x20directory\x20is\x20named,\x20<code>go\x20version</code>\x20walks\x20that\x20directory,\x20recursively,\x20looking\x0afor\x20recognized\x20Go\x20binaries\x20and\x20reporting\x20their\x20versions.\x20By\x20default,\x20<code>go\x20version</code>\x20does\x20not\x20report\x20unrecognized\x20files\x20found\x20during\x20a\x20directory\x20scan.\x20The\x0a<code>-v</code>\x20flag\x20causes\x20it\x20to\x20report\x20unrecognized\x20files.</p>\x0a<p>The\x20<code>-m</code>\x20flag\x20causes\x20<code>go\x20version</code>\x20to\x20print\x20each\x20executable's\x20embedded\x20module\x0aversion\x20information,\x20when\x20available.\x20For\x20each\x20executable,\x20<code>go\x20version\x20-m</code>\x20prints\x0aa\x20table\x20with\x20tab-separated\x20columns\x20like\x20the\x20one\x20below.</p>\x0a<pre><code>$\x20go\x20version\x20-m\x20~/go/bin/goimports\x0a/home/jrgopher/go/bin/goimports:\x20go1.14.3\x0a\x20\x20\x20\x20\x20\x20\x20\x20path\x20\x20\x20\x20golang.org/x/tools/cmd/goimports\x0a\x20\x20\x20\x20\x20\x20\x20\x20mod\x20\x20\x20\x20\x20golang.org/x/tools\x20\x20\x20\x20\x20\x20v0.0.0-20200518203908-8018eb2c26ba\x20\x20\x20\x20\x20\x20h1:0Lcy64USfQQL6GAJma8BdHCgeofcchQj+Z7j0SXYAzU=\x0a\x20\x20\x20\x20\x20\x20\x20\x20dep\x20\x20\x20\x20\x20golang.org/x/mod\x20\x20\x20\x20\x20\x20\x20\x20v0.2.0\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20h1:KU7oHjnv3XNWfa5COkzUifxZmxp1TyI7ImMXqFxLwvQ=\x0a\x20\x20\x20\x20\x20\x20\x20\x20dep\x20\x20\x20\x20\x20golang.org/x/xerrors\x20\x20\x20\x20v0.0.0-20191204190536-9bdfabe68543\x20\x20\x20\x20\x20\x20h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=\x0a</code></pre>\x0a<p>The\x20format\x20of\x20the\x20table\x20may\x20change\x20in\x20the\x20future.\x20The\x20same\x20information\x20may\x20be\x0aobtained\x20from\x0a<a\x20href=\"https://pkg.go.dev/runtime/debug?tab=doc#ReadBuildInfo\"><code>runtime/debug.ReadBuildInfo</code></a>.</p>\x0a<p>The\x20meaning\x20of\x20each\x20row\x20in\x20the\x20table\x20is\x20determined\x20by\x20the\x20word\x20in\x20the\x20first\x0acolumn.</p>\x0a<ul>\x0a<li><strong><code>path</code></strong>:\x20the\x20path\x20of\x20the\x20<code>main</code>\x20package\x20used\x20to\x20build\x20the\x20executable.</li>\x0a<li><strong><code>mod</code></strong>:\x20the\x20module\x20containing\x20the\x20<code>main</code>\x20package.\x20The\x20columns\x20are\x20the\x0amodule\x20path,\x20version,\x20and\x20sum,\x20respectively.\x20The\x20<a\x20href=\"#glos-main-module\">main\x0amodule</a>\x20has\x20the\x20version\x20<code>(devel)</code>\x20and\x20no\x20sum.</li>\x0a<li><strong><code>dep</code></strong>:\x20a\x20module\x20that\x20provided\x20one\x20or\x20more\x20packages\x20linked\x20into\x20the\x0aexecutable.\x20Same\x20format\x20as\x20<code>mod</code>.</li>\x0a<li><strong><code>=&gt;</code></strong>:\x20a\x20<a\x20href=\"#go.mod-replace\">replacement</a>\x20for\x20the\x20module\x20on\x20the\x20previous\x0aline.\x20If\x20the\x20replacement\x20is\x20a\x20local\x20directory,\x20only\x20the\x20directory\x20path\x20is\x0alisted\x20(no\x20version\x20or\x20sum).\x20If\x20the\x20replacement\x20is\x20a\x20module\x20version,\x20the\x20path,\x0aversion,\x20and\x20sum\x20are\x20listed,\x20as\x20with\x20<code>mod</code>\x20and\x20<code>dep</code>.\x20A\x20replaced\x20module\x20has\x0ano\x20sum.</li>\x0a</ul>\x0a<p><a\x20id=\"go-clean-modcache\"></a></p>\x0a<h3><code>go\x20clean\x20-modcache</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20clean\x20[-modcache]\x0a</code></pre>\x0a<p>The\x20<code>-modcache</code>\x20flag\x20causes\x20<a\x20href=\"/cmd/go/#hdr-Remove_object_files_and_cached_files\"><code>go\x20clean</code></a>\x20to\x20remove\x20the\x20entire\x0a<a\x20href=\"#glos-module-cache\">module\x20cache</a>,\x20including\x20unpacked\x20source\x20code\x20of\x20versioned\x0adependencies.</p>\x0a<p>This\x20is\x20usually\x20the\x20best\x20way\x20to\x20remove\x20the\x20module\x20cache.\x20By\x20default,\x20most\x20files\x0aand\x20directories\x20in\x20the\x20module\x20cache\x20are\x20read-only\x20to\x20prevent\x20tests\x20and\x20editors\x0afrom\x20unintentionally\x20changing\x20files\x20after\x20they've\x20been\x0a<a\x20href=\"#authenticating\">authenticated</a>.\x20Unfortunately,\x20this\x20causes\x20commands\x20like\x0a<code>rm\x20-r</code>\x20to\x20fail,\x20since\x20files\x20can't\x20be\x20removed\x20without\x20first\x20making\x20their\x20parent\x0adirectories\x20writable.</p>\x0a<p>The\x20<code>-modcacherw</code>\x20flag\x20(accepted\x20by\x20<a\x20href=\"https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies\"><code>go\x20build</code></a>\x20and\x0aother\x20module-aware\x20commands)\x20causes\x20new\x20directories\x20in\x20the\x20module\x20cache\x20to\x0abe\x20writable.\x20To\x20pass\x20<code>-modcacherw</code>\x20to\x20all\x20module-aware\x20commands,\x20add\x20it\x20to\x20the\x0a<code>GOFLAGS</code>\x20variable.\x20<code>GOFLAGS</code>\x20may\x20be\x20set\x20in\x20the\x20environment\x20or\x20with\x20<a\x20href=\"https://golang.org/cmd/go/#hdr-Print_Go_environment_information\"><code>go\x20env\x20-w</code></a>.\x20For\x0aexample,\x20the\x20command\x20below\x20sets\x20it\x20permanently:</p>\x0a<pre><code>go\x20env\x20-w\x20GOFLAGS=-modcacherw\x0a</code></pre>\x0a<p><code>-modcacherw</code>\x20should\x20be\x20used\x20with\x20caution;\x20developers\x20should\x20be\x20careful\x20not\x0ato\x20make\x20changes\x20to\x20files\x20in\x20the\x20module\x20cache.\x20<a\x20href=\"#go-mod-verify\"><code>go\x20mod\x20verify</code></a>\x0amay\x20be\x20used\x20to\x20check\x20that\x20files\x20in\x20the\x20cache\x20match\x20hashes\x20in\x20the\x20main\x20module's\x0a<code>go.sum</code>\x20file.</p>\x0a<p><a\x20id=\"version-queries\"></a></p>\x0a<h3>Version\x20queries</h3>\x0a<p>Several\x20commands\x20allow\x20you\x20to\x20specify\x20a\x20version\x20of\x20a\x20module\x20using\x20a\x20<em>version\x0aquery</em>,\x20which\x20appears\x20after\x20an\x20<code>@</code>\x20character\x20following\x20a\x20module\x20or\x20package\x20path\x0aon\x20the\x20command\x20line.</p>\x0a<p>Examples:</p>\x0a<pre><code>go\x20get\x20example.com/m@latest\x0ago\x20mod\x20download\x20example.com/m@master\x0ago\x20list\x20-m\x20-json\x20example.com/m@e3702bed2\x0a</code></pre>\x0a<p>A\x20version\x20query\x20may\x20be\x20one\x20of\x20the\x20following:</p>\x0a<ul>\x0a<li>A\x20fully-specified\x20semantic\x20version,\x20such\x20as\x20<code>v1.2.3</code>,\x20which\x20selects\x20a\x0aspecific\x20version.\x20See\x20<a\x20href=\"#versions\">Versions</a>\x20for\x20syntax.</li>\x0a<li>A\x20semantic\x20version\x20prefix,\x20such\x20as\x20<code>v1</code>\x20or\x20<code>v1.2</code>,\x20which\x20selects\x20the\x20highest\x0aavailable\x20version\x20with\x20that\x20prefix.</li>\x0a<li>A\x20semantic\x20version\x20comparison,\x20such\x20as\x20<code>&lt;v1.2.3</code>\x20or\x20<code>&gt;=v1.5.6</code>,\x20which\x20selects\x0athe\x20nearest\x20available\x20version\x20to\x20the\x20comparison\x20target\x20(the\x20lowest\x20version\x0afor\x20<code>&gt;</code>\x20and\x20<code>&gt;=</code>,\x20and\x20the\x20highest\x20version\x20for\x20<code>&lt;</code>\x20and\x20<code>&lt;=</code>).</li>\x0a<li>A\x20revision\x20identifier\x20for\x20the\x20underlying\x20source\x20repository,\x20such\x20as\x20a\x20commit\x0ahash\x20prefix,\x20revision\x20tag,\x20or\x20branch\x20name.\x20If\x20the\x20revision\x20is\x20tagged\x20with\x20a\x0asemantic\x20version,\x20this\x20query\x20selects\x20that\x20version.\x20Otherwise,\x20this\x20query\x0aselects\x20a\x20<a\x20href=\"#glos-pseudo-version\">pseudo-version</a>\x20for\x20the\x20underlying\x0acommit.\x20Note\x20that\x20branches\x20and\x20tags\x20with\x20names\x20matched\x20by\x20other\x20version\x0aqueries\x20cannot\x20be\x20selected\x20this\x20way.\x20For\x20example,\x20the\x20query\x20<code>v2</code>\x20selects\x20the\x0alatest\x20version\x20starting\x20with\x20<code>v2</code>,\x20not\x20the\x20branch\x20named\x20<code>v2</code>.</li>\x0a<li>The\x20string\x20<code>latest</code>,\x20which\x20selects\x20the\x20highest\x20available\x20release\x20version.\x20If\x0athere\x20are\x20no\x20release\x20versions,\x20<code>latest</code>\x20selects\x20the\x20highest\x20pre-release\x0aversion.\x20\x20If\x20there\x20no\x20tagged\x20versions,\x20<code>latest</code>\x20selects\x20a\x20pseudo-version\x20for\x0athe\x20commit\x20at\x20the\x20tip\x20of\x20the\x20repository's\x20default\x20branch.</li>\x0a<li>The\x20string\x20<code>upgrade</code>,\x20which\x20is\x20like\x20<code>latest</code>\x20except\x20that\x20if\x20the\x20module\x20is\x0acurrently\x20required\x20at\x20a\x20higher\x20version\x20than\x20the\x20version\x20<code>latest</code>\x20would\x20select\x0a(for\x20example,\x20a\x20pre-release),\x20<code>upgrade</code>\x20will\x20select\x20the\x20current\x20version.</li>\x0a<li>The\x20string\x20<code>patch</code>,\x20which\x20selects\x20the\x20latest\x20available\x20version\x20with\x20the\x20same\x0amajor\x20and\x20minor\x20version\x20numbers\x20as\x20the\x20currently\x20required\x20version.\x20If\x20no\x0aversion\x20is\x20currently\x20required,\x20<code>patch</code>\x20is\x20equivalent\x20to\x20<code>latest</code>.</li>\x0a</ul>\x0a<p>Except\x20for\x20queries\x20for\x20specific\x20named\x20versions\x20or\x20revisions,\x20all\x20queries\x0aconsider\x20available\x20versions\x20reported\x20by\x20<code>go\x20list\x20-m\x20-versions</code>\x20(see\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>).\x20This\x20list\x20contains\x20only\x20tagged\x20versions,\x20not\x20pseudo-versions.\x0aModule\x20versions\x20disallowed\x20by\x20<a\x20href=\"#go.mod-exclude\">exclude</a>\x20directives\x20in\x0athe\x20main\x20module's\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20file</a>\x20are\x20not\x20considered.</p>\x0a<p><a\x20href=\"#glos-release-version\">Release\x20versions</a>\x20are\x20preferred\x20over\x20pre-release\x0aversions.\x20For\x20example,\x20if\x20versions\x20<code>v1.2.2</code>\x20and\x20<code>v1.2.3-pre</code>\x20are\x20available,\x20the\x0a<code>latest</code>\x20query\x20will\x20select\x20<code>v1.2.2</code>,\x20even\x20though\x20<code>v1.2.3-pre</code>\x20is\x20higher.\x20The\x0a<code>&lt;v1.2.4</code>\x20query\x20would\x20also\x20select\x20<code>v1.2.2</code>,\x20even\x20though\x20<code>v1.2.3-pre</code>\x20is\x20closer\x0ato\x20<code>v1.2.4</code>.\x20If\x20no\x20release\x20or\x20pre-release\x20version\x20is\x20available,\x20the\x20<code>latest</code>,\x0a<code>upgrade</code>,\x20and\x20<code>patch</code>\x20queries\x20will\x20select\x20a\x20pseudo-version\x20for\x20the\x20commit\x0aat\x20the\x20tip\x20of\x20the\x20repository's\x20default\x20branch.\x20Other\x20queries\x20will\x20report\x0aan\x20error.</p>\x0a<p><a\x20id=\"commands-outside\"></a></p>\x0a<h3>Module\x20commands\x20outside\x20a\x20module</h3>\x0a<p>Module-aware\x20Go\x20commands\x20normally\x20run\x20in\x20the\x20context\x20of\x20a\x20<a\x20href=\"#glos-main-module\">main\x0amodule</a>\x20defined\x20by\x20a\x20<code>go.mod</code>\x20file\x20in\x20the\x20working\x20directory\x0aor\x20a\x20parent\x20directory.\x20Some\x20commands\x20may\x20be\x20run\x20in\x20module-aware\x20mode\x20without\x20a\x0a<code>go.mod</code>\x20file\x20by\x20setting\x20the\x20<code>GO111MODULE</code>\x20environment\x20variable\x20to\x20<code>on</code>.\x0aMost\x20commands\x20work\x20differently\x20when\x20no\x20<code>go.mod</code>\x20file\x20is\x20present.</p>\x0a<p>See\x20<a\x20href=\"#mod-commands\">Module-aware\x20commands</a>\x20for\x20information\x20on\x20enabling\x20and\x0adisabling\x20module-aware\x20mode.</p>\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Command</th>\x0a\x20\x20\x20\x20\x20\x20<th>Behavior</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20build</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20doc</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20fix</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20fmt</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20generate</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20install</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20list</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20run</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20test</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20vet</code>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Only\x20packages\x20in\x20the\x20standard\x20library\x20and\x20packages\x20specified\x20as\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>.go</code>\x20files\x20on\x20the\x20command\x20line\x20can\x20be\x20loaded,\x20imported,\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20built.\x20Packages\x20from\x20other\x20modules\x20cannot\x20be\x20built,\x20since\x20there\x20is\x20no\x0a\x20\x20\x20\x20\x20\x20\x20\x20place\x20to\x20record\x20module\x20requirements\x20and\x20ensure\x20deterministic\x20builds.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>go\x20get</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Packages\x20and\x20executables\x20may\x20be\x20built\x20and\x20installed\x20as\x20usual.\x20Note\x20that\x0a\x20\x20\x20\x20\x20\x20\x20\x20there\x20is\x20no\x20main\x20module\x20when\x20<code>go\x20get</code>\x20is\x20run\x20without\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go.mod</code>\x20file,\x20so\x20<code>replace</code>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>exclude</code>\x20directives\x20are\x20not\x20applied.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>go\x20list\x20-m</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Explicit\x20<a\x20href=\"#version-queries\">version\x20queries</a>\x20are\x20required\x0a\x20\x20\x20\x20\x20\x20\x20\x20for\x20most\x20arguments,\x20except\x20when\x20the\x20<code>-versions</code>\x20flag\x20is\x20used.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>go\x20mod\x20download</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Explicit\x20<a\x20href=\"#version-queries\">version\x20queries</a>\x20are\x20required\x0a\x20\x20\x20\x20\x20\x20\x20\x20for\x20most\x20arguments.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>go\x20mod\x20edit</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>An\x20explicit\x20file\x20argument\x20is\x20required.</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20graph</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20tidy</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20vendor</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20verify</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20why</code>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20These\x20commands\x20require\x20a\x20<code>go.mod</code>\x20file\x20and\x20will\x20report\x0a\x20\x20\x20\x20\x20\x20\x20\x20an\x20error\x20if\x20one\x20is\x20not\x20present.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<p><a\x20id=\"module-proxy\"></a></p>\x0a<h2>Module\x20proxies</h2>\x0a<p><a\x20id=\"goproxy-protocol\"></a></p>\x0a<h3><code>GOPROXY</code>\x20protocol</h3>\x0a<p>A\x20<a\x20href=\"#glos-module-proxy\"><em>module\x20proxy</em></a>\x20is\x20an\x20HTTP\x20server\x20that\x20can\x20respond\x20to\x0a<code>GET</code>\x20requests\x20for\x20paths\x20specified\x20below.\x20The\x20requests\x20have\x20no\x20query\x20parameters,\x0aand\x20no\x20specific\x20headers\x20are\x20required,\x20so\x20even\x20a\x20site\x20serving\x20from\x20a\x20fixed\x20file\x0asystem\x20(including\x20a\x20<code>file://</code>\x20URL)\x20can\x20be\x20a\x20module\x20proxy.</p>\x0a<p>Successful\x20HTTP\x20responses\x20must\x20have\x20the\x20status\x20code\x20200\x20(OK).\x20Redirects\x20(3xx)\x0aare\x20followed.\x20Responses\x20with\x20status\x20codes\x204xx\x20and\x205xx\x20are\x20treated\x20as\x20errors.\x0aThe\x20error\x20codes\x20404\x20(Not\x20Found)\x20and\x20410\x20(Gone)\x20indicate\x20that\x20the\x0arequested\x20module\x20or\x20version\x20is\x20not\x20available\x20on\x20the\x20proxy,\x20but\x20it\x20may\x20be\x20found\x0aelsewhere.\x20Error\x20responses\x20should\x20have\x20content\x20type\x20<code>text/plain</code>\x20with\x0a<code>charset</code>\x20either\x20<code>utf-8</code>\x20or\x20<code>us-ascii</code>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20be\x20configured\x20to\x20contact\x20proxies\x20or\x20source\x20control\x20servers\x0ausing\x20the\x20<code>GOPROXY</code>\x20environment\x20variable,\x20which\x20is\x20a\x20comma-separated\x20list\x20of\x0aURLs\x20or\x20the\x20keywords\x20<code>direct</code>\x20or\x20<code>off</code>\x20(see\x20<a\x20href=\"#environment-variables\">Environment\x0avariables</a>\x20for\x20details).\x20When\x20the\x20<code>go</code>\x20command\x20receives\x0aa\x20404\x20or\x20410\x20response\x20from\x20a\x20proxy,\x20it\x20falls\x20back\x20to\x20later\x20proxies\x20in\x20the\x0alist.\x20The\x20<code>go</code>\x20command\x20does\x20not\x20fall\x20back\x20to\x20later\x20proxies\x20in\x20response\x20to\x20other\x0a4xx\x20and\x205xx\x20errors.\x20This\x20allows\x20a\x20proxy\x20to\x20act\x20as\x20a\x20gatekeeper,\x20for\x20example,\x20by\x0aresponding\x20with\x20error\x20403\x20(Forbidden)\x20for\x20modules\x20not\x20on\x20an\x20approved\x20list.</p>\x0a<!--\x20TODO(katiehockman):\x20why\x20only\x20fall\x20back\x20for\x20410/404?\x20Either\x20add\x20the\x20details\x0ahere,\x20or\x20write\x20a\x20blog\x20post\x20about\x20how\x20to\x20build\x20multiple\x20types\x20of\x20proxies.\x20e.g.\x0aa\x20\"privacy\x20preserving\x20one\"\x20and\x20an\x20\"authorization\x20one\"\x20-->\x0a<p>The\x20table\x20below\x20specifies\x20queries\x20that\x20a\x20module\x20proxy\x20must\x20respond\x20to.\x20For\x20each\x0apath,\x20<code>$base</code>\x20is\x20the\x20path\x20portion\x20of\x20a\x20proxy\x20URL,<code>$module</code>\x20is\x20a\x20module\x20path,\x20and\x0a<code>$version</code>\x20is\x20a\x20version.\x20For\x20example,\x20if\x20the\x20proxy\x20URL\x20is\x0a<code>https://example.com/mod</code>,\x20and\x20the\x20client\x20is\x20requesting\x20the\x20<code>go.mod</code>\x20file\x20for\x0athe\x20module\x20<code>golang.org/x/text</code>\x20at\x20version\x20<code>v0.3.2</code>,\x20the\x20client\x20would\x20send\x20a\x0a<code>GET</code>\x20request\x20for\x20<code>https://example.com/mod/golang.org/x/text/@v/v0.3.2.mod</code>.</p>\x0a<p>To\x20avoid\x20ambiguity\x20when\x20serving\x20from\x20case-insensitive\x20file\x20systems,\x0athe\x20<code>$module</code>\x20and\x20<code>$version</code>\x20elements\x20are\x20case-encoded\x20by\x20replacing\x20every\x0auppercase\x20letter\x20with\x20an\x20exclamation\x20mark\x20followed\x20by\x20the\x20corresponding\x0alower-case\x20letter.\x20This\x20allows\x20modules\x20<code>example.com/M</code>\x20and\x20<code>example.com/m</code>\x20to\x0aboth\x20be\x20stored\x20on\x20disk,\x20since\x20the\x20former\x20is\x20encoded\x20as\x20<code>example.com/!m</code>.</p>\x0a<!--\x20TODO(jayconrod):\x20This\x20table\x20has\x20multi-line\x20cells,\x20and\x20GitHub\x20Flavored\x0aMarkdown\x20doesn't\x20have\x20syntax\x20for\x20that,\x20so\x20we\x20use\x20raw\x20HTML.\x20Gitiles\x20doesn't\x0ainclude\x20this\x20table\x20in\x20the\x20rendered\x20HTML.\x20Once\x20x/website\x20has\x20a\x20Markdown\x20renderer,\x0aensure\x20this\x20table\x20is\x20readable.\x20If\x20the\x20cells\x20are\x20too\x20large,\x20and\x20it's\x20difficult\x0ato\x20scan,\x20use\x20paragraphs\x20or\x20sections\x20below.\x0a-->\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Path</th>\x0a\x20\x20\x20\x20\x20\x20<th>Description</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@v/list</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20a\x20list\x20of\x20known\x20versions\x20of\x20the\x20given\x20module\x20in\x20plain\x20text,\x20one\x0a\x20\x20\x20\x20\x20\x20\x20\x20per\x20line.\x20This\x20list\x20should\x20not\x20include\x20pseudo-versions.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@v/$version.info</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20JSON-formatted\x20metadata\x20about\x20a\x20specific\x20version\x20of\x20a\x20module.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20response\x20must\x20be\x20a\x20JSON\x20object\x20that\x20corresponds\x20to\x20the\x20Go\x20data\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20structure\x20below:\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<pre>\x0atype\x20Info\x20struct\x20{\x0a\x20\x20\x20\x20Version\x20string\x20\x20\x20\x20//\x20version\x20string\x0a\x20\x20\x20\x20Time\x20\x20\x20\x20time.Time\x20//\x20commit\x20time\x0a}\x0a</pre>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20<code>Version</code>\x20field\x20is\x20required\x20and\x20must\x20contain\x20a\x20valid,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#glos-canonical-version\">canonical\x20version</a>\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#versions\">Versions</a>).\x20The\x20<code>$version</code>\x20in\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20request\x20path\x20does\x20not\x20need\x20to\x20be\x20the\x20same\x20version\x20or\x20even\x20a\x20valid\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20version;\x20this\x20endpoint\x20may\x20be\x20used\x20to\x20find\x20versions\x20for\x20branch\x20names\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20or\x20revision\x20identifiers.\x20However,\x20if\x20<code>$version</code>\x20is\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20canonical\x20version\x20with\x20a\x20major\x20version\x20compatible\x20with\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>$module</code>,\x20the\x20<code>Version</code>\x20field\x20in\x20a\x20successful\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20response\x20must\x20be\x20the\x20same.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20<code>Time</code>\x20field\x20is\x20optional.\x20If\x20present,\x20it\x20must\x20be\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20string\x20in\x20RFC\x203339\x20format.\x20It\x20indicates\x20the\x20time\x20when\x20the\x20version\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20was\x20created.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20More\x20fields\x20may\x20be\x20added\x20in\x20the\x20future,\x20so\x20other\x20names\x20are\x20reserved.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@v/$version.mod</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20the\x20<code>go.mod</code>\x20file\x20for\x20a\x20specific\x20version\x20of\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20module.\x20If\x20the\x20module\x20does\x20not\x20have\x20a\x20<code>go.mod</code>\x20file\x20at\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20requested\x20version,\x20a\x20file\x20containing\x20only\x20a\x20<code>module</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20statement\x20with\x20the\x20requested\x20module\x20path\x20must\x20be\x20returned.\x20Otherwise,\x0a\x20\x20\x20\x20\x20\x20\x20\x20the\x20original,\x20unmodified\x20<code>go.mod</code>\x20file\x20must\x20be\x20returned.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@v/$version.zip</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20a\x20zip\x20file\x20containing\x20the\x20contents\x20of\x20a\x20specific\x20version\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20a\x20module.\x20See\x20<a\x20href=\"#zip-files\">Module\x20zip\x20files</a>\x20for\x20details\x0a\x20\x20\x20\x20\x20\x20\x20\x20on\x20how\x20this\x20zip\x20file\x20must\x20be\x20formatted.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@latest</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20JSON-formatted\x20metadata\x20about\x20the\x20latest\x20known\x20version\x20of\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20module\x20in\x20the\x20same\x20format\x20as\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>$base/$module/@v/$version.info</code>.\x20The\x20latest\x20version\x20should\x0a\x20\x20\x20\x20\x20\x20\x20\x20be\x20the\x20version\x20of\x20the\x20module\x20that\x20the\x20<code>go</code>\x20command\x20should\x20use\x0a\x20\x20\x20\x20\x20\x20\x20\x20if\x20<code>$base/$module/@v/list</code>\x20is\x20empty\x20or\x20no\x20listed\x20version\x20is\x0a\x20\x20\x20\x20\x20\x20\x20\x20suitable.\x20This\x20endpoint\x20is\x20optional,\x20and\x20module\x20proxies\x20are\x20not\x20required\x0a\x20\x20\x20\x20\x20\x20\x20\x20to\x20implement\x20it.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<p>When\x20resolving\x20the\x20latest\x20version\x20of\x20a\x20module,\x20the\x20<code>go</code>\x20command\x20will\x20request\x0a<code>$base/$module/@v/list</code>,\x20then,\x20if\x20no\x20suitable\x20versions\x20are\x20found,\x0a<code>$base/$module/@latest</code>.\x20The\x20<code>go</code>\x20command\x20prefers,\x20in\x20order:\x20the\x20semantically\x0ahighest\x20release\x20version,\x20the\x20semantically\x20highest\x20pre-release\x20version,\x20and\x20the\x0achronologically\x20most\x20recent\x20pseudo-version.\x20In\x20Go\x201.12\x20and\x20earlier,\x20the\x20<code>go</code>\x0acommand\x20considered\x20pseudo-versions\x20in\x20<code>$base/$module/@v/list</code>\x20to\x20be\x20pre-release\x0aversions,\x20but\x20this\x20is\x20no\x20longer\x20true\x20since\x20Go\x201.13.</p>\x0a<p>A\x20module\x20proxy\x20must\x20always\x20serve\x20the\x20same\x20content\x20for\x20successful\x0aresponses\x20for\x20<code>$base/$module/$version.mod</code>\x20and\x20<code>$base/$module/$version.zip</code>\x0aqueries.\x20This\x20content\x20is\x20<a\x20href=\"#authenticating\">cryptographically\x20authenticated</a>\x0ausing\x20<a\x20href=\"#go.sum-files\"><code>go.sum</code>\x20files</a>\x20and,\x20by\x20default,\x20the\x0a<a\x20href=\"#checksum-database\">checksum\x20database</a>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20caches\x20most\x20content\x20it\x20downloads\x20from\x20module\x20proxies\x20in\x20its\x0amodule\x20cache\x20in\x20<code>$GOPATH/pkg/mod/cache/download</code>.\x20Even\x20when\x20downloading\x20directly\x0afrom\x20version\x20control\x20systems,\x20the\x20<code>go</code>\x20command\x20synthesizes\x20explicit\x20<code>info</code>,\x0a<code>mod</code>,\x20and\x20<code>zip</code>\x20files\x20and\x20stores\x20them\x20in\x20this\x20directory,\x20the\x20same\x20as\x20if\x20it\x20had\x0adownloaded\x20them\x20directly\x20from\x20a\x20proxy.\x20The\x20cache\x20layout\x20is\x20the\x20same\x20as\x20the\x20proxy\x0aURL\x20space,\x20so\x20serving\x20<code>$GOPATH/pkg/mod/cache/download</code>\x20at\x20(or\x20copying\x20it\x20to)\x0a<code>https://example.com/proxy</code>\x20would\x20let\x20users\x20access\x20cached\x20module\x20versions\x20by\x0asetting\x20<code>GOPROXY</code>\x20to\x20<code>https://example.com/proxy</code>.</p>\x0a<p><a\x20id=\"communicating-with-proxies\"></a></p>\x0a<h3>Communicating\x20with\x20proxies</h3>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20download\x20module\x20source\x20code\x20and\x20metadata\x20from\x20a\x20<a\x20href=\"#glos-module-proxy\">module\x0aproxy</a>.\x20The\x20<code>GOPROXY</code>\x20<a\x20href=\"#environment-variables\">environment\x0avariable</a>\x20may\x20be\x20used\x20to\x20configure\x20which\x20proxies\x20the\x0a<code>go</code>\x20command\x20may\x20connect\x20to\x20and\x20whether\x20it\x20may\x20communicate\x20directly\x20with\x0a<a\x20href=\"#vcs\">version\x20control\x20systems</a>.\x20Downloaded\x20module\x20data\x20is\x20saved\x20in\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>.\x20The\x20<code>go</code>\x20command\x20will\x20only\x20contact\x20a\x20proxy\x20when\x20it\x0aneeds\x20information\x20not\x20already\x20in\x20the\x20cache.</p>\x0a<p>The\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>\x20section\x20describes\x20requests\x20that\x0amay\x20be\x20sent\x20to\x20a\x20<code>GOPROXY</code>\x20server.\x20However,\x20it's\x20also\x20helpful\x20to\x20understand\x0awhen\x20the\x20<code>go</code>\x20command\x20makes\x20these\x20requests.\x20For\x20example,\x20<code>go\x20build</code>\x20follows\x0athe\x20procedure\x20below:</p>\x0a<ul>\x0a<li>Compute\x20the\x20<a\x20href=\"#glos-build-list\">build\x20list</a>\x20by\x20reading\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x0afiles</a>\x20and\x20performing\x20<a\x20href=\"#glos-minimal-version-selection\">minimal\x20version\x20selection\x0a(MVS)</a>.</li>\x0a<li>Read\x20the\x20packages\x20named\x20on\x20the\x20command\x20line\x20and\x20the\x20packages\x20they\x20import.</li>\x0a<li>If\x20a\x20package\x20is\x20not\x20provided\x20by\x20any\x20module\x20in\x20the\x20build\x20list,\x20find\x20a\x20module\x0athat\x20provides\x20it.\x20Add\x20a\x20module\x20requirement\x20on\x20its\x20latest\x20version\x20to\x20<code>go.mod</code>,\x0aand\x20start\x20over.</li>\x0a<li>Build\x20packages\x20after\x20everything\x20is\x20loaded.</li>\x0a</ul>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20computes\x20the\x20build\x20list,\x20it\x20loads\x20the\x20<code>go.mod</code>\x20file\x20for\x0aeach\x20module\x20in\x20the\x20<a\x20href=\"#glos-module-graph\">module\x20graph</a>.\x20If\x20a\x20<code>go.mod</code>\x20file\x20is\x20not\x0ain\x20the\x20cache,\x20the\x20<code>go</code>\x20command\x20will\x20download\x20it\x20from\x20the\x20proxy\x20using\x20a\x0a<code>$module/@v/$version.mod</code>\x20request\x20(where\x20<code>$module</code>\x20is\x20the\x20module\x20path\x20and\x0a<code>$version</code>\x20is\x20the\x20version).\x20These\x20requests\x20can\x20be\x20tested\x20with\x20a\x20tool\x20like\x0a<code>curl</code>.\x20For\x20example,\x20the\x20command\x20below\x20downloads\x20the\x20<code>go.mod</code>\x20file\x20for\x0a<code>golang.org/x/mod</code>\x20at\x20version\x20<code>v0.2.0</code>:</p>\x0a<pre><code>$\x20curl\x20https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.mod\x0amodule\x20golang.org/x/mod\x0a\x0ago\x201.12\x0a\x0arequire\x20(\x0a\x09golang.org/x/crypto\x20v0.0.0-20191011191535-87dc89f01550\x0a\x09golang.org/x/tools\x20v0.0.0-20191119224855-298f0cb1881e\x0a\x09golang.org/x/xerrors\x20v0.0.0-20191011141410-1b5146add898\x0a)\x0a</code></pre>\x0a<p>In\x20order\x20to\x20load\x20a\x20package,\x20the\x20<code>go</code>\x20command\x20needs\x20the\x20source\x20code\x20for\x20the\x0amodule\x20that\x20provides\x20it.\x20Module\x20source\x20code\x20is\x20distributed\x20in\x20<code>.zip</code>\x20files\x20which\x0aare\x20extracted\x20into\x20the\x20module\x20cache.\x20If\x20a\x20module\x20<code>.zip</code>\x20is\x20not\x20in\x20the\x20cache,\x0athe\x20<code>go</code>\x20command\x20will\x20download\x20it\x20using\x20a\x20<code>$module/@v/$version.zip</code>\x20request.</p>\x0a<pre><code>$\x20curl\x20-O\x20https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.zip\x0a$\x20unzip\x20-l\x20v0.2.0.zip\x20|\x20head\x0aArchive:\x20\x20v0.2.0.zip\x0a\x20\x20Length\x20\x20\x20\x20\x20\x20Date\x20\x20\x20\x20Time\x20\x20\x20\x20Name\x0a---------\x20\x20----------\x20-----\x20\x20\x20----\x0a\x20\x20\x20\x20\x201479\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/LICENSE\x0a\x20\x20\x20\x20\x201303\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/PATENTS\x0a\x20\x20\x20\x20\x20\x20559\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/README\x0a\x20\x20\x20\x20\x20\x20\x2021\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/codereview.cfg\x0a\x20\x20\x20\x20\x20\x20214\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/go.mod\x0a\x20\x20\x20\x20\x201476\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/go.sum\x0a\x20\x20\x20\x20\x205224\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/gosumcheck/main.go\x0a</code></pre>\x0a<p>Note\x20that\x20<code>.mod</code>\x20and\x20<code>.zip</code>\x20requests\x20are\x20separate,\x20even\x20though\x20<code>go.mod</code>\x20files\x0aare\x20usually\x20contained\x20within\x20<code>.zip</code>\x20files.\x20The\x20<code>go</code>\x20command\x20may\x20need\x20to\x20download\x0a<code>go.mod</code>\x20files\x20for\x20many\x20different\x20modules,\x20and\x20<code>.mod</code>\x20files\x20are\x20much\x20smaller\x0athan\x20<code>.zip</code>\x20files.\x20Additionally,\x20if\x20a\x20Go\x20project\x20does\x20not\x20have\x20a\x20<code>go.mod</code>\x20file,\x0athe\x20proxy\x20will\x20serve\x20a\x20synthetic\x20<code>go.mod</code>\x20file\x20that\x20only\x20contains\x20a\x20<a\x20href=\"#go.mod-module\"><code>module</code>\x0adirective</a>.\x20Synthetic\x20<code>go.mod</code>\x20files\x20are\x20generated\x20by\x20the\x20<code>go</code>\x0acommand\x20when\x20downloading\x20from\x20a\x20<a\x20href=\"#vcs\">version\x20control\x0asystem</a>.</p>\x0a<p>If\x20the\x20<code>go</code>\x20command\x20needs\x20to\x20load\x20a\x20package\x20not\x20provided\x20by\x20any\x20module\x20in\x20the\x0abuild\x20list,\x20it\x20will\x20attempt\x20to\x20find\x20a\x20new\x20module\x20that\x20provides\x20it.\x20The\x20section\x0a<a\x20href=\"#resolve-pkg-mod\">Resolving\x20a\x20package\x20to\x20a\x20module</a>\x20describes\x20this\x20process.\x20In\x0asummary,\x20the\x20<code>go</code>\x20command\x20requests\x20information\x20about\x20the\x20latest\x20version\x20of\x20each\x0amodule\x20path\x20that\x20could\x20possibly\x20contain\x20the\x20package.\x20For\x20example,\x20for\x20the\x0apackage\x20<code>golang.org/x/net/html</code>,\x20the\x20<code>go</code>\x20command\x20would\x20try\x20to\x20find\x20the\x20latest\x0aversions\x20of\x20the\x20modules\x20<code>golang.org/x/net/html</code>,\x20<code>golang.org/x/net</code>,\x0a<code>golang.org/x/</code>,\x20and\x20<code>golang.org</code>.\x20Only\x20<code>golang.org/x/net</code>\x20actually\x20exists\x20and\x0aprovides\x20that\x20package,\x20so\x20the\x20<code>go</code>\x20command\x20uses\x20the\x20latest\x20version\x20of\x20that\x0amodule.\x20If\x20more\x20than\x20one\x20module\x20provides\x20the\x20package,\x20the\x20<code>go</code>\x20command\x20will\x20use\x0athe\x20module\x20with\x20the\x20longest\x20path.</p>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20requests\x20the\x20latest\x20version\x20of\x20a\x20module,\x20it\x20first\x20sends\x20a\x0arequest\x20for\x20<code>$module/@v/list</code>.\x20If\x20the\x20list\x20is\x20empty\x20or\x20none\x20of\x20the\x20returned\x0aversions\x20can\x20be\x20used,\x20it\x20sends\x20a\x20request\x20for\x20<code>$module/@latest</code>.\x20Once\x20a\x20version\x0ais\x20chosen,\x20the\x20<code>go</code>\x20command\x20sends\x20a\x20<code>$module/@v/$version.info</code>\x20request\x20for\x0ametadata.\x20It\x20may\x20then\x20send\x20<code>$module/@v/$version.mod</code>\x20and\x0a<code>$module/@v/$version.zip</code>\x20requests\x20to\x20load\x20the\x20<code>go.mod</code>\x20file\x20and\x20source\x20code.</p>\x0a<pre><code>$\x20curl\x20https://proxy.golang.org/golang.org/x/mod/@v/list\x0av0.1.0\x0av0.2.0\x0a\x0a$\x20curl\x20https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.info\x0a{&quot;Version&quot;:&quot;v0.2.0&quot;,&quot;Time&quot;:&quot;2020-01-02T17:33:45Z&quot;}\x0a</code></pre>\x0a<p>After\x20downloading\x20a\x20<code>.mod</code>\x20or\x20<code>.zip</code>\x20file,\x20the\x20<code>go</code>\x20command\x20computes\x20a\x0acryptographic\x20hash\x20and\x20checks\x20that\x20it\x20matches\x20a\x20hash\x20in\x20the\x20main\x20module's\x0a<code>go.sum</code>\x20file.\x20If\x20the\x20hash\x20is\x20not\x20present\x20in\x20<code>go.sum</code>,\x20by\x20default,\x20the\x20<code>go</code>\x0acommand\x20retrieves\x20it\x20from\x20the\x20<a\x20href=\"#checksum-database\">checksum\x20database</a>.\x20If\x20the\x0acomputed\x20hash\x20does\x20not\x20match,\x20the\x20<code>go</code>\x20command\x20reports\x20a\x20security\x20error\x20and\x20does\x0anot\x20install\x20the\x20file\x20in\x20the\x20module\x20cache.\x20The\x20<code>GOPRIVATE</code>\x20and\x20<code>GONOSUMDB</code>\x0a<a\x20href=\"#environment-variables\">environment\x20variables</a>\x20may\x20be\x20used\x20to\x20disable\x20requests\x0ato\x20the\x20checksum\x20database\x20for\x20specific\x20modules.\x20The\x20<code>GOSUMDB</code>\x20environment\x0avariable\x20may\x20also\x20be\x20set\x20to\x20<code>off</code>\x20to\x20disable\x20requests\x20to\x20the\x20checksum\x20database\x0aentirely.\x20See\x20<a\x20href=\"#authenticating\">Authenticating\x20modules</a>\x20for\x20more\x0ainformation.\x20Note\x20that\x20version\x20lists\x20and\x20version\x20metadata\x20returned\x20for\x20<code>.info</code>\x0arequests\x20are\x20not\x20authenticated\x20and\x20may\x20change\x20over\x20time.</p>\x0a<p><a\x20id=\"vcs\"></a></p>\x0a<h2>Version\x20control\x20systems</h2>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20download\x20module\x20source\x20code\x20and\x20metadata\x20directly\x20from\x20a\x0aversion\x20control\x20repository.\x20Downloading\x20a\x20module\x20from\x20a\x0a<a\x20href=\"#communicating-with-proxies\">proxy</a>\x20is\x20usually\x20faster,\x20but\x20connecting\x20directly\x0ato\x20a\x20repository\x20is\x20necessary\x20if\x20a\x20proxy\x20is\x20not\x20available\x20or\x20if\x20a\x20module's\x0arepository\x20is\x20not\x20accessible\x20to\x20a\x20proxy\x20(frequently\x20true\x20for\x20private\x0arepositories).\x20Git,\x20Subversion,\x20Mercurial,\x20Bazaar,\x20and\x20Fossil\x20are\x20supported.\x20A\x0aversion\x20control\x20tool\x20must\x20be\x20installed\x20in\x20a\x20directory\x20in\x20<code>PATH</code>\x20in\x20order\x20for\x20the\x0a<code>go</code>\x20command\x20to\x20use\x20it.</p>\x0a<p>To\x20download\x20specific\x20modules\x20from\x20source\x20repositories\x20instead\x20of\x20a\x20proxy,\x20set\x0athe\x20<code>GOPRIVATE</code>\x20or\x20<code>GONOPROXY</code>\x20environment\x20variables.\x20To\x20configure\x20the\x20<code>go</code>\x0acommand\x20to\x20download\x20all\x20modules\x20directly\x20from\x20source\x20repositories,\x20set\x20<code>GOPROXY</code>\x0ato\x20<code>direct</code>.\x20See\x20<a\x20href=\"#environment-variables\">Environment\x20variables</a>\x20for\x20more\x0ainformation.</p>\x0a<p><a\x20id=\"vcs-find\"></a></p>\x0a<h3>Finding\x20a\x20repository\x20for\x20a\x20module\x20path</h3>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20downloads\x20a\x20module\x20in\x20<code>direct</code>\x20mode,\x20it\x20starts\x20by\x20locating\x0athe\x20repository\x20that\x20contains\x20the\x20module.\x20The\x20<code>go</code>\x20command\x20sends\x20an\x0aHTTP\x20<code>GET</code>\x20request\x20to\x20a\x20URL\x20derived\x20from\x20the\x20module\x20path\x20with\x20a\x0a<code>?go-get=1</code>\x20query\x20string.\x20For\x20example,\x20for\x20the\x20module\x20<code>golang.org/x/mod</code>,\x0athe\x20<code>go</code>\x20command\x20may\x20send\x20the\x20following\x20requests:</p>\x0a<pre><code>https://golang.org/x/mod?go-get=1\x20(preferred)\x0ahttp://golang.org/x/mod?go-get=1\x20\x20(fallback,\x20only\x20with\x20GOINSECURE)\x0a</code></pre>\x0a<p>The\x20<code>go</code>\x20command\x20will\x20follow\x20redirects\x20but\x20otherwise\x20ignores\x20response\x20status\x0acodes,\x20so\x20the\x20server\x20may\x20respond\x20with\x20a\x20404\x20or\x20any\x20other\x20error\x20status.\x20The\x0a<code>GOINSECURE</code>\x20environment\x20variable\x20may\x20be\x20set\x20to\x20allow\x20fallback\x20and\x20redirects\x20to\x0aunencrypted\x20HTTP\x20for\x20specific\x20modules.</p>\x0a<p>The\x20server\x20must\x20respond\x20with\x20an\x20HTML\x20document\x20containing\x20a\x20<code>&lt;meta&gt;</code>\x20tag\x20in\x20the\x0adocument's\x20<code>&lt;head&gt;</code>.\x20The\x20<code>&lt;meta&gt;</code>\x20tag\x20should\x20appear\x20early\x20in\x20the\x20document\x20to\x0aavoid\x20confusing\x20the\x20<code>go</code>\x20command's\x20restricted\x20parser.\x20In\x20particular,\x20it\x20should\x0aappear\x20before\x20any\x20raw\x20JavaScript\x20or\x20CSS.\x20The\x20<code>&lt;meta&gt;</code>\x20tag\x20must\x20have\x20the\x20form:</p>\x0a<pre><code>&lt;meta\x20name=&quot;go-import&quot;\x20content=&quot;root-path\x20vcs\x20repo-url&quot;&gt;\x0a</code></pre>\x0a<p><code>root-path</code>\x20is\x20the\x20repository\x20root\x20path,\x20the\x20portion\x20of\x20the\x20module\x20path\x20that\x0acorresponds\x20to\x20the\x20repository's\x20root\x20directory.\x20It\x20must\x20be\x20a\x20prefix\x20or\x20an\x20exact\x0amatch\x20of\x20the\x20requested\x20module\x20path.\x20If\x20it's\x20not\x20an\x20exact\x20match,\x20another\x20request\x0ais\x20made\x20for\x20the\x20prefix\x20to\x20verify\x20the\x20<code>&lt;meta&gt;</code>\x20tags\x20match.</p>\x0a<p><code>vcs</code>\x20is\x20the\x20version\x20control\x20system.\x20It\x20must\x20be\x20one\x20of\x20<code>bzr</code>,\x20<code>fossil</code>,\x20<code>git</code>,\x0a<code>hg</code>,\x20<code>svn</code>,\x20<code>mod</code>.\x20The\x20<code>mod</code>\x20scheme\x20instructs\x20the\x20<code>go</code>\x20command\x20to\x20download\x20the\x0amodule\x20from\x20the\x20given\x20URL\x20using\x20the\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x0aprotocol</a>.\x20This\x20allows\x20developers\x20to\x20distribute\x20modules\x0awithout\x20exposing\x20source\x20repositories.</p>\x0a<p><code>repo-url</code>\x20is\x20the\x20repository's\x20URL.\x20If\x20the\x20URL\x20does\x20not\x20include\x20a\x20scheme,\x20the\x0a<code>go</code>\x20command\x20will\x20try\x20each\x20protocol\x20supported\x20by\x20the\x20version\x20control\x20system.\x0aFor\x20example,\x20with\x20Git,\x20the\x20<code>go</code>\x20command\x20will\x20try\x20<code>https://</code>\x20then\x20<code>git+ssh://</code>.\x0aInsecure\x20protocols\x20may\x20only\x20be\x20used\x20if\x20the\x20module\x20path\x20is\x20matched\x20by\x20the\x0a<code>GOINSECURE</code>\x20environment\x20variable.</p>\x0a<p>As\x20an\x20example,\x20consider\x20<code>golang.org/x/mod</code>\x20again.\x20The\x20<code>go</code>\x20command\x20sends\x0aa\x20request\x20to\x20<code>https://golang.org/x/mod?go-get=1</code>.\x20The\x20server\x20responds\x0awith\x20an\x20HTML\x20document\x20containing\x20the\x20tag:</p>\x0a<pre><code>&lt;meta\x20name=&quot;go-import&quot;\x20content=&quot;golang.org/x/mod\x20git\x20https://go.googlesource.com/mod&quot;&gt;\x0a</code></pre>\x0a<p>From\x20this\x20response,\x20the\x20<code>go</code>\x20command\x20will\x20use\x20the\x20Git\x20repository\x20at\x0athe\x20remote\x20URL\x20<code>https://go.googlesource.com/mod</code>.</p>\x0a<p>GitHub\x20and\x20other\x20popular\x20hosting\x20services\x20respond\x20to\x20<code>?go-get=1</code>\x20queries\x20for\x0aall\x20repositories,\x20so\x20usually\x20no\x20server\x20configuration\x20is\x20necessary\x20for\x20modules\x0ahosted\x20at\x20those\x20sites.</p>\x0a<p>After\x20the\x20repository\x20URL\x20is\x20found,\x20the\x20<code>go</code>\x20command\x20will\x20clone\x20the\x20repository\x0ainto\x20the\x20module\x20cache.\x20In\x20general,\x20the\x20<code>go</code>\x20command\x20tries\x20to\x20avoid\x20fetching\x0aunneeded\x20data\x20from\x20a\x20repository.\x20However,\x20the\x20actual\x20commands\x20used\x20vary\x20by\x0aversion\x20control\x20system\x20and\x20may\x20change\x20over\x20time.\x20For\x20Git,\x20the\x20<code>go</code>\x20command\x20can\x0alist\x20most\x20available\x20versions\x20without\x20downloading\x20commits.\x20It\x20will\x20usually\x20fetch\x0acommits\x20without\x20downloading\x20ancestor\x20commits,\x20but\x20doing\x20so\x20is\x20sometimes\x0anecessary.</p>\x0a<p><a\x20id=\"vcs-version\"></a></p>\x0a<h3>Mapping\x20versions\x20to\x20commits</h3>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20check\x20out\x20a\x20module\x20within\x20a\x20repository\x20at\x20a\x20specific\x0a<a\x20href=\"#glos-canonical-version\">canonical\x20version</a>\x20like\x20<code>v1.2.3</code>,\x20<code>v2.4.0-beta</code>,\x20or\x0a<code>v3.0.0+incompatible</code>.\x20Each\x20module\x20version\x20should\x20have\x20a\x20<dfn>semantic\x20version\x0atag</dfn>\x20within\x20the\x20repository\x20that\x20indicates\x20which\x20revision\x20should\x20be\x20checked\x0aout\x20for\x20a\x20given\x20version.</p>\x0a<p>If\x20a\x20module\x20is\x20defined\x20in\x20the\x20repository\x20root\x20directory\x20or\x20in\x20a\x20major\x20version\x0asubdirectory\x20of\x20the\x20root\x20directory,\x20then\x20each\x20version\x20tag\x20name\x20is\x20equal\x20to\x20the\x0acorresponding\x20version.\x20For\x20example,\x20the\x20module\x20<code>golang.org/x/text</code>\x20is\x20defined\x20in\x0athe\x20root\x20directory\x20of\x20its\x20repository,\x20so\x20the\x20version\x20<code>v0.3.2</code>\x20has\x20the\x20tag\x0a<code>v0.3.2</code>\x20in\x20that\x20repository.\x20This\x20is\x20true\x20for\x20most\x20modules.</p>\x0a<p>If\x20a\x20module\x20is\x20defined\x20in\x20a\x20subdirectory\x20within\x20the\x20repository,\x20that\x20is,\x20the\x0a<a\x20href=\"#glos-module-subdirectory\">module\x20subdirectory</a>\x20portion\x20of\x20the\x20module\x20path\x20is\x0anot\x20empty,\x20then\x20each\x20tag\x20name\x20must\x20be\x20prefixed\x20with\x20the\x20module\x20subdirectory,\x0afollowed\x20by\x20a\x20slash.\x20For\x20example,\x20the\x20module\x20<code>golang.org/x/tools/gopls</code>\x20is\x0adefined\x20in\x20the\x20<code>gopls</code>\x20subdirectory\x20of\x20the\x20repository\x20with\x20root\x20path\x0a<code>golang.org/x/tools</code>.\x20The\x20version\x20<code>v0.4.0</code>\x20of\x20that\x20module\x20must\x20have\x20the\x20tag\x0anamed\x20<code>gopls/v0.4.0</code>\x20in\x20that\x20repository.</p>\x0a<p>The\x20major\x20version\x20number\x20of\x20a\x20semantic\x20version\x20tag\x20must\x20be\x20consistent\x20with\x20the\x0amodule\x20path's\x20major\x20version\x20suffix\x20(if\x20any).\x20For\x20example,\x20the\x20tag\x20<code>v1.0.0</code>\x20could\x0abelong\x20to\x20the\x20module\x20<code>example.com/mod</code>\x20but\x20not\x20<code>example.com/mod/v2</code>,\x20which\x20would\x0ahave\x20tags\x20like\x20<code>v2.0.0</code>.</p>\x0a<p>A\x20tag\x20with\x20major\x20version\x20<code>v2</code>\x20or\x20higher\x20may\x20belong\x20to\x20a\x20module\x20without\x20a\x20major\x0aversion\x20suffix\x20if\x20no\x20<code>go.mod</code>\x20file\x20is\x20present,\x20and\x20the\x20module\x20is\x20in\x20the\x0arepository\x20root\x20directory.\x20This\x20kind\x20of\x20version\x20is\x20denoted\x20with\x20the\x20suffix\x0a<code>+incompatible</code>.\x20The\x20version\x20tag\x20itself\x20must\x20not\x20have\x20the\x20suffix.\x20See\x0a<a\x20href=\"#non-module-compat\">Compatibility\x20with\x20non-module\x20repositories</a>.</p>\x0a<p>Once\x20a\x20tag\x20is\x20created,\x20it\x20should\x20not\x20be\x20deleted\x20or\x20changed\x20to\x20a\x20different\x0arevision.\x20Versions\x20are\x20<a\x20href=\"#authenticating\">authenticated</a>\x20to\x20ensure\x20safe,\x0arepeatable\x20builds.\x20If\x20a\x20tag\x20is\x20modified,\x20clients\x20may\x20see\x20a\x20security\x20error\x20when\x0adownloading\x20it.\x20Even\x20after\x20a\x20tag\x20is\x20deleted,\x20its\x20content\x20may\x20remain\x0aavailable\x20on\x20<a\x20href=\"#glos-module-proxy\">module\x20proxies</a>.</p>\x0a<p><a\x20id=\"vcs-pseudo\"></a></p>\x0a<h3>Mapping\x20pseudo-versions\x20to\x20commits</h3>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20check\x20out\x20a\x20module\x20within\x20a\x20repository\x20at\x20a\x20specific\x0arevision,\x20encoded\x20as\x20a\x20<a\x20href=\"#glos-pseudo-version\">pseudo-version</a>\x20like\x0a<code>v1.3.2-0.20191109021931-daa7c04131f5</code>.</p>\x0a<p>The\x20last\x2012\x20characters\x20of\x20the\x20pseudo-version\x20(<code>daa7c04131f5</code>\x20in\x20the\x20example\x0aabove)\x20indicate\x20a\x20revision\x20in\x20the\x20repository\x20to\x20check\x20out.\x20The\x20meaning\x20of\x20this\x0adepends\x20on\x20the\x20version\x20control\x20system.\x20For\x20Git\x20and\x20Mercurial,\x20this\x20is\x20a\x20prefix\x0aof\x20a\x20commit\x20hash.\x20For\x20Subversion,\x20this\x20is\x20a\x20zero-padded\x20revision\x20number.</p>\x0a<p>Before\x20checking\x20out\x20a\x20commit,\x20the\x20<code>go</code>\x20command\x20verifies\x20that\x20the\x20timestamp\x0a(<code>20191109021931</code>\x20above)\x20matches\x20the\x20commit\x20date.\x20It\x20also\x20verifies\x20that\x20the\x20base\x0aversion\x20(<code>v1.3.1</code>,\x20the\x20version\x20before\x20<code>v1.3.2</code>\x20in\x20the\x20example\x20above)\x20corresponds\x0ato\x20a\x20semantic\x20version\x20tag\x20that\x20is\x20an\x20ancestor\x20of\x20the\x20commit.\x20These\x20checks\x20ensure\x0athat\x20module\x20authors\x20have\x20full\x20control\x20over\x20how\x20pseudo-versions\x20compare\x20with\x0aother\x20released\x20versions.</p>\x0a<p>See\x20<a\x20href=\"#pseudo-versions\">Pseudo-versions</a>\x20for\x20more\x20information.</p>\x0a<p><a\x20id=\"vcs-branch\"></a></p>\x0a<h3>Mapping\x20branches\x20and\x20commits\x20to\x20versions</h3>\x0a<p>A\x20module\x20may\x20be\x20checked\x20out\x20at\x20a\x20specific\x20branch,\x20tag,\x20or\x20revision\x20using\x20a\x0a<a\x20href=\"#version-queries\">version\x20query</a>.</p>\x0a<pre><code>go\x20get\x20example.com/mod@master\x0a</code></pre>\x0a<p>The\x20<code>go</code>\x20command\x20converts\x20these\x20names\x20into\x20<a\x20href=\"#glos-canonical-version\">canonical\x0aversions</a>\x20that\x20can\x20be\x20used\x20with\x20<a\x20href=\"#minimal-version-selection\">minimal\x20version\x0aselection\x20(MVS)</a>.\x20MVS\x20depends\x20on\x20the\x20ability\x20to\x0aorder\x20versions\x20unambiguously.\x20Branch\x20names\x20and\x20revisions\x20can't\x20be\x20compared\x0areliably\x20over\x20time,\x20since\x20they\x20depend\x20on\x20repository\x20structure\x20which\x20may\x20change.</p>\x0a<p>If\x20a\x20revision\x20is\x20tagged\x20with\x20one\x20or\x20more\x20semantic\x20version\x20tags\x20like\x20<code>v1.2.3</code>,\x0athe\x20tag\x20for\x20the\x20highest\x20valid\x20version\x20will\x20be\x20used.\x20The\x20<code>go</code>\x20command\x20only\x0aconsiders\x20semantic\x20version\x20tags\x20that\x20could\x20belong\x20to\x20the\x20target\x20module;\x20for\x0aexample,\x20the\x20tag\x20<code>v1.5.2</code>\x20would\x20not\x20be\x20considered\x20for\x20<code>example.com/mod/v2</code>\x20since\x0athe\x20major\x20version\x20doesn't\x20match\x20the\x20module\x20path's\x20suffix.</p>\x0a<p>If\x20a\x20revision\x20is\x20not\x20tagged\x20with\x20a\x20valid\x20semantic\x20version\x20tag,\x20the\x20<code>go</code>\x20command\x0awill\x20generate\x20a\x20<a\x20href=\"#glos-pseudo-version\">pseudo-version</a>.\x20If\x20the\x20revision\x20has\x0aancestors\x20with\x20valid\x20semantic\x20version\x20tags,\x20the\x20highest\x20ancestor\x20version\x20will\x20be\x0aused\x20as\x20the\x20pseudo-version\x20base.\x20See\x20<a\x20href=\"#pseudo-versions\">Pseudo-versions</a>.</p>\x0a<p><a\x20id=\"vcs-dir\"></a></p>\x0a<h3>Module\x20directories\x20within\x20a\x20repository</h3>\x0a<p>Once\x20a\x20module's\x20repository\x20has\x20been\x20checked\x20out\x20at\x20a\x20specific\x20revision,\x20the\x20<code>go</code>\x0acommand\x20must\x20locate\x20the\x20directory\x20that\x20contains\x20the\x20module's\x20<code>go.mod</code>\x20file\x0a(the\x20module's\x20root\x20directory).</p>\x0a<p>Recall\x20that\x20a\x20<a\x20href=\"#module-path\">module\x20path</a>\x20consists\x20of\x20three\x20parts:\x20a\x0arepository\x20root\x20path\x20(corresponding\x20to\x20the\x20repository\x20root\x20directory),\x0aa\x20module\x20subdirectory,\x20and\x20a\x20major\x20version\x20suffix\x20(only\x20for\x20modules\x20released\x20at\x0a<code>v2</code>\x20or\x20higher).</p>\x0a<p>For\x20most\x20modules,\x20the\x20module\x20path\x20is\x20equal\x20to\x20the\x20repository\x20root\x20path,\x20so\x0athe\x20module's\x20root\x20directory\x20is\x20the\x20repository's\x20root\x20directory.</p>\x0a<p>Modules\x20are\x20sometimes\x20defined\x20in\x20repository\x20subdirectories.\x20This\x20is\x20typically\x0adone\x20for\x20large\x20repositories\x20with\x20multiple\x20components\x20that\x20need\x20to\x20be\x20released\x0aand\x20versioned\x20indepently.\x20Such\x20a\x20module\x20is\x20expected\x20to\x20be\x20found\x20in\x20a\x0asubdirectory\x20that\x20matches\x20the\x20part\x20of\x20the\x20module's\x20path\x20after\x20the\x20repository\x0aroot\x20path.\x20\x20For\x20example,\x20suppose\x20the\x20module\x20<code>example.com/monorepo/foo/bar</code>\x20is\x20in\x0athe\x20repository\x20with\x20root\x20path\x20<code>example.com/monorepo</code>.\x20Its\x20<code>go.mod</code>\x20file\x20must\x20be\x0ain\x20the\x20<code>foo/bar</code>\x20subdirectory.</p>\x0a<p>If\x20a\x20module\x20is\x20released\x20at\x20major\x20version\x20<code>v2</code>\x20or\x20higher,\x20its\x20path\x20must\x20have\x20a\x0a<a\x20href=\"#major-version-suffixes\">major\x20version\x20suffix</a>.\x20A\x20module\x20with\x20a\x20major\x20version\x0asuffix\x20may\x20be\x20defined\x20in\x20one\x20of\x20two\x20subdirectories:\x20one\x20with\x20the\x20suffix,\x0aand\x20one\x20without.\x20For\x20example,\x20suppose\x20a\x20new\x20version\x20of\x20the\x20module\x20above\x20is\x0areleased\x20with\x20the\x20path\x20<code>example.com/monorepo/foo/bar/v2</code>.\x20Its\x20<code>go.mod</code>\x20file\x0amay\x20be\x20in\x20either\x20<code>foo/bar</code>\x20or\x20<code>foo/bar/v2</code>.</p>\x0a<p>Subdirectories\x20with\x20a\x20major\x20version\x20suffix\x20are\x20<dfn>major\x20version\x0asubdirectories</dfn>.\x20They\x20may\x20be\x20used\x20to\x20develop\x20multiple\x20major\x20versions\x20of\x20a\x0amodule\x20on\x20a\x20single\x20branch.\x20This\x20may\x20be\x20unnecessary\x20when\x20development\x20of\x20multiple\x0amajor\x20versions\x20proceeds\x20on\x20separate\x20branches.\x20However,\x20major\x20version\x0asubdirectories\x20have\x20an\x20important\x20property:\x20in\x20<code>GOPATH</code>\x20mode,\x20package\x20import\x0apaths\x20exactly\x20match\x20directories\x20under\x20<code>GOPATH/src</code>.\x20The\x20<code>go</code>\x20command\x20provides\x0aminimal\x20module\x20compatibility\x20in\x20<code>GOPATH</code>\x20mode\x20(see\x20<a\x20href=\"#non-module-compat\">Compatibility\x20with\x0anon-module\x20repositories</a>),\x20so\x20major\x20version\x0asubdirectories\x20aren't\x20always\x20necessary\x20for\x20compatibility\x20with\x20projects\x20built\x20in\x0a<code>GOPATH</code>\x20mode.\x20Older\x20tools\x20that\x20don't\x20support\x20minimal\x20module\x20compatibility\x0amay\x20have\x20problems\x20though.</p>\x0a<p>Once\x20the\x20<code>go</code>\x20command\x20has\x20found\x20the\x20module\x20root\x20directory,\x20it\x20creates\x20a\x20<code>.zip</code>\x0afile\x20of\x20the\x20contents\x20of\x20the\x20directory,\x20then\x20extracts\x20the\x20<code>.zip</code>\x20file\x20into\x20the\x0amodule\x20cache.\x20See\x20<a\x20href=\"#zip-path-size-constraints\">File\x20path\x20and\x20size\x20constraints</a>)\x0afor\x20details\x20on\x20what\x20files\x20may\x20be\x20included\x20in\x20the\x20<code>.zip</code>\x20file.\x20The\x20contents\x20of\x0athe\x20<code>.zip</code>\x20file\x20are\x20<a\x20href=\"#authenticating\">authenticated</a>\x20before\x20extraction\x20into\x20the\x0amodule\x20cache\x20the\x20same\x20way\x20they\x20would\x20be\x20if\x20the\x20<code>.zip</code>\x20file\x20were\x20downloaded\x20from\x0aa\x20proxy.</p>\x0a<p><a\x20id=\"zip-files\"></a></p>\x0a<h2>Module\x20zip\x20files</h2>\x0a<p>Module\x20versions\x20are\x20distributed\x20as\x20<code>.zip</code>\x20files.\x20There\x20is\x20rarely\x20any\x20need\x20to\x0ainteract\x20directly\x20with\x20these\x20files,\x20since\x20the\x20<code>go</code>\x20command\x20creates,\x20downloads,\x0aand\x20extracts\x20them\x20automatically\x20from\x20<a\x20href=\"#glos-module-proxy\">module\x20proxies</a>\x20and\x0aversion\x20control\x20repositories.\x20However,\x20it's\x20still\x20useful\x20to\x20know\x20about\x20these\x0afiles\x20to\x20understand\x20cross-platform\x20compatibility\x20constraints\x20or\x20when\x0aimplementing\x20a\x20module\x20proxy.</p>\x0a<p>The\x20<a\x20href=\"#go-mod-download\"><code>go\x20mod\x20download</code></a>\x20command\x20downloads\x20zip\x20files\x0afor\x20one\x20or\x20more\x20modules,\x20then\x20extracts\x20those\x20files\x20into\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>.\x20Depending\x20on\x20<code>GOPROXY</code>\x20and\x20other\x20<a\x20href=\"#environment-variables\">environment\x0avariables</a>,\x20the\x20<code>go</code>\x20command\x20may\x20either\x20download\x0azip\x20files\x20from\x20a\x20proxy\x20or\x20clone\x20source\x20control\x20repositories\x20and\x20create\x0azip\x20files\x20from\x20them.\x20The\x20<code>-json</code>\x20flag\x20may\x20be\x20used\x20to\x20find\x20the\x20location\x20of\x0adownload\x20zip\x20files\x20and\x20their\x20extracted\x20contents\x20in\x20the\x20module\x20cache.</p>\x0a<p>The\x20<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/zip?tab=doc\"><code>golang.org/x/mod/zip</code></a>\x0apackage\x20may\x20be\x20used\x20to\x20create,\x20extract,\x20or\x20check\x20contents\x20of\x20zip\x20files\x0aprogrammatically.</p>\x0a<p><a\x20id=\"zip-path-size-constraints\"></a></p>\x0a<h3>File\x20path\x20and\x20size\x20constraints</h3>\x0a<p>There\x20are\x20a\x20number\x20of\x20restrictions\x20on\x20the\x20content\x20of\x20module\x20zip\x20files.\x20These\x0aconstraints\x20ensure\x20that\x20zip\x20files\x20can\x20be\x20extracted\x20safely\x20and\x20consistently\x20on\x0aa\x20wide\x20range\x20of\x20platforms.</p>\x0a<ul>\x0a<li>A\x20module\x20zip\x20file\x20may\x20be\x20at\x20most\x20500\x20MiB\x20in\x20size.\x20The\x20total\x20uncompressed\x20size\x0aof\x20its\x20files\x20is\x20also\x20limited\x20to\x20500\x20MiB.\x20<code>go.mod</code>\x20files\x20are\x20limited\x20to\x2016\x20MiB.\x0a<code>LICENSE</code>\x20files\x20are\x20also\x20limited\x20to\x2016\x20MiB.\x20These\x20limits\x20exist\x20to\x20mitigate\x0adenial\x20of\x20service\x20attacks\x20on\x20users,\x20proxies,\x20and\x20other\x20parts\x20of\x20the\x20module\x0aecosystem.\x20Repositories\x20that\x20contain\x20more\x20than\x20500\x20MiB\x20of\x20files\x20in\x20a\x20module\x0adirectory\x20tree\x20should\x20tag\x20module\x20versions\x20at\x20commits\x20that\x20only\x20include\x20files\x0aneeded\x20to\x20build\x20the\x20module's\x20packages;\x20videos,\x20models,\x20and\x20other\x20large\x20assets\x0aare\x20usually\x20not\x20needed\x20for\x20builds.</li>\x0a<li>Each\x20file\x20within\x20a\x20module\x20zip\x20file\x20must\x20begin\x20with\x20the\x20prefix\x0a<code>$module@$version/</code>\x20where\x20<code>$module</code>\x20is\x20the\x20module\x20path\x20and\x20<code>$version</code>\x20is\x20the\x0aversion,\x20for\x20example,\x20<code>golang.org/x/mod@v0.3.0/</code>.\x20The\x20module\x20path\x20must\x20be\x0avalid,\x20the\x20version\x20must\x20be\x20valid\x20and\x20canonical,\x20and\x20the\x20version\x20must\x20match\x20the\x0amodule\x20path's\x20major\x20version\x20suffix.\x20See\x20<a\x20href=\"#go.mod-ident\">Module\x20paths\x20and\x0aversions</a>\x20for\x20specific\x20definitions\x20and\x20restrictions.</li>\x0a<li>File\x20modes,\x20timestamps,\x20and\x20other\x20metadata\x20are\x20ignored.</li>\x0a<li>Empty\x20directories\x20(entries\x20with\x20paths\x20ending\x20with\x20a\x20slash)\x20may\x20be\x20included\x0ain\x20module\x20zip\x20files\x20but\x20are\x20not\x20extracted.\x20The\x20<code>go</code>\x20command\x20does\x20not\x20include\x0aempty\x20directories\x20in\x20zip\x20files\x20it\x20creates.</li>\x0a<li>Symbolic\x20links\x20and\x20other\x20irregular\x20files\x20are\x20ignored\x20when\x20creating\x20zip\x20files,\x0asince\x20they\x20aren't\x20portable\x20across\x20operating\x20systems\x20and\x20file\x20systems,\x20and\x0athere's\x20no\x20portable\x20way\x20to\x20represent\x20them\x20in\x20the\x20zip\x20file\x20format.</li>\x0a<li>No\x20two\x20files\x20within\x20a\x20zip\x20file\x20may\x20have\x20paths\x20equal\x20under\x20Unicode\x20case-folding\x0a(see\x20<a\x20href=\"https://pkg.go.dev/strings?tab=doc#EqualFold\"><code>strings.EqualFold</code></a>).\x0aThis\x20ensures\x20that\x20zip\x20files\x20can\x20be\x20extracted\x20on\x20case-insensitive\x20file\x20systems\x0awithout\x20collisions.</li>\x0a<li>A\x20<code>go.mod</code>\x20file\x20may\x20or\x20may\x20not\x20appear\x20in\x20the\x20top-level\x20directory\x0a(<code>$module@$version/go.mod</code>).\x20If\x20present,\x20it\x20must\x20have\x20the\x20name\x20<code>go.mod</code>\x20(all\x0alowercase).\x20Files\x20named\x20<code>go.mod</code>\x20are\x20not\x20allowed\x20in\x20any\x20other\x20directory.</li>\x0a<li>File\x20and\x20directory\x20names\x20within\x20a\x20module\x20may\x20consist\x20of\x20Unicode\x20letters,\x20ASCII\x0adigits,\x20the\x20ASCII\x20space\x20character\x20(U+0020),\x20and\x20the\x20ASCII\x20punctuation\x0acharacters\x20<code>!#$%&amp;()+,-.=@[]^_{}~</code>.\x20Note\x20that\x20package\x20paths\x20may\x20not\x20contain\x20all\x0athese\x20all\x20these\x20characters.\x20See\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/module?tab=doc#CheckFilePath\"><code>module.CheckFilePath</code></a>\x0aand\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/module?tab=doc#CheckImportPath\"><code>module.CheckImportPath</code></a>\x0afor\x20the\x20differences.</li>\x0a<li>A\x20file\x20or\x20directory\x20name\x20up\x20to\x20the\x20first\x20dot\x20must\x20not\x20be\x20a\x20reserved\x20file\x20name\x0aon\x20Windows,\x20regardless\x20of\x20case\x20(<code>CON</code>,\x20<code>com1</code>,\x20<code>NuL</code>,\x20and\x20so\x20on).</li>\x0a</ul>\x0a<p><a\x20id=\"private-modules\"></a></p>\x0a<h2>Private\x20modules</h2>\x0a<p>Go\x20modules\x20are\x20frequently\x20developed\x20and\x20distributed\x20on\x20version\x20control\x20servers\x0aand\x20module\x20proxies\x20that\x20aren't\x20available\x20on\x20the\x20public\x20internet.\x20The\x20<code>go</code>\x0acommand\x20can\x20download\x20and\x20build\x20modules\x20from\x20private\x20sources,\x20though\x20it\x20usually\x0arequires\x20some\x20configuration.</p>\x0a<p>The\x20environment\x20variables\x20below\x20may\x20be\x20used\x20to\x20configure\x20access\x20to\x20private\x0amodules.\x20See\x20<a\x20href=\"#environment-variables\">Environment\x20variables</a>\x20for\x20details.\x20See\x0aalso\x20<a\x20href=\"#privacy\">Privacy</a>\x20for\x20information\x20on\x20controlling\x20information\x20sent\x20to\x0apublic\x20servers.</p>\x0a<ul>\x0a<li><code>GOPROXY</code>\x20\xe2\x80\x94\x20list\x20of\x20module\x20proxy\x20URLs.\x20The\x20<code>go</code>\x20command\x20will\x20attempt\x20to\x0adownload\x20modules\x20from\x20each\x20server\x20in\x20sequence.\x20The\x20keyword\x20<code>direct</code>\x20instructs\x0athe\x20<code>go</code>\x20command\x20to\x20download\x20modules\x20from\x20version\x20control\x20repositories\x0awhere\x20they're\x20developed\x20instead\x20of\x20using\x20a\x20proxy.</li>\x0a<li><code>GOPRIVATE</code>\x20\xe2\x80\x94\x20list\x20of\x20glob\x20patterns\x20of\x20module\x20path\x20prefixes\x20that\x20should\x20be\x0aconsidered\x20private.\x20Acts\x20as\x20a\x20default\x20value\x20for\x20<code>GONOPROXY</code>\x20and\x20<code>GONOSUMDB</code>.</li>\x0a<li><code>GONOPROXY</code>\x20\xe2\x80\x94\x20list\x20of\x20glob\x20patterns\x20of\x20module\x20path\x20prefixes\x20that\x20should\x20not\x20be\x0adownloaded\x20from\x20a\x20proxy.\x20The\x20<code>go</code>\x20command\x20will\x20download\x20matching\x20modules\x20from\x0aversion\x20control\x20repositories\x20where\x20they're\x20developed,\x20regardless\x20of\x20<code>GOPROXY</code>.</li>\x0a<li><code>GONOSUMDB</code>\x20\xe2\x80\x94\x20list\x20of\x20glob\x20patterns\x20of\x20module\x20path\x20prefixes\x20that\x20should\x20not\x20be\x0achecked\x20using\x20the\x20public\x20checksum\x20database,\x0a<a\x20href=\"https://sum.golang.org\">sum.golang.org</a>.</li>\x0a<li><code>GOINSECURE</code>\x20\xe2\x80\x94\x20list\x20of\x20glob\x20patterns\x20of\x20module\x20path\x20prefixes\x20that\x20may\x20be\x0aretrieved\x20over\x20HTTP\x20and\x20other\x20insecure\x20protocols.</li>\x0a</ul>\x0a<p>These\x20variables\x20may\x20be\x20set\x20in\x20the\x20development\x20environment\x20(for\x20example,\x20in\x20a\x0a<code>.profile</code>\x20file),\x20or\x20they\x20may\x20be\x20set\x20permanently\x20with\x20<a\x20href=\"https://golang.org/cmd/go/#hdr-Print_Go_environment_information\"><code>go\x20env\x20-w</code></a>.</p>\x0a<p>The\x20rest\x20of\x20this\x20section\x20describes\x20common\x20patterns\x20for\x20providing\x20access\x20to\x0aprivate\x20module\x20proxies\x20and\x20version\x20control\x20repositories.</p>\x0a<p><a\x20id=\"private-module-proxy-all\"></a></p>\x0a<h3>Private\x20proxy\x20serving\x20all\x20modules</h3>\x0a<p>A\x20central\x20private\x20proxy\x20server\x20that\x20serves\x20all\x20modules\x20(public\x20and\x20private)\x0aprovides\x20the\x20most\x20control\x20for\x20administrators\x20and\x20requires\x20the\x20least\x0aconfiguration\x20for\x20individual\x20developers.</p>\x0a<p>To\x20configure\x20the\x20<code>go</code>\x20command\x20to\x20use\x20such\x20a\x20server,\x20set\x20the\x20following\x0aenvironment\x20variables,\x20replacing\x20<code>https://proxy.corp.example.com</code>\x20with\x20your\x0aproxy\x20URL\x20and\x20<code>corp.example.com</code>\x20with\x20your\x20module\x20prefix:</p>\x0a<pre><code>GOPROXY=https://proxy.corp.example.com\x0aGONOSUMDB=corp.example.com\x0a</code></pre>\x0a<p>The\x20<code>GOPROXY</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20to\x20only\x20download\x20modules\x20from\x0a<code>https://proxy.corp.example.com</code>;\x20the\x20<code>go</code>\x20command\x20will\x20not\x20connect\x20to\x20other\x0aproxies\x20or\x20version\x20control\x20repositories.</p>\x0a<p>The\x20<code>GONOSUMDB</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20not\x20to\x20use\x20the\x20public\x0achecksum\x20database\x20to\x20authenticate\x20modules\x20with\x20paths\x20starting\x20with\x0a<code>corp.example.com</code>.</p>\x0a<p>A\x20proxy\x20running\x20in\x20this\x20configuration\x20will\x20likely\x20need\x20read\x20access\x20to\x0aprivate\x20version\x20control\x20servers.\x20It\x20will\x20also\x20need\x20access\x20to\x20the\x20public\x20internet\x0ato\x20download\x20new\x20versions\x20of\x20public\x20modules.</p>\x0a<p>There\x20are\x20several\x20existing\x20implementations\x20of\x20<code>GOPROXY</code>\x20servers\x20that\x20may\x20be\x20used\x0athis\x20way.\x20A\x20minimal\x20implementation\x20would\x20serve\x20files\x20from\x20a\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>\x20directory\x20and\x20would\x20use\x20<a\x20href=\"#go-mod-download\"><code>go\x20mod\x20download</code></a>\x20(with\x20suitable\x20configuration)\x20to\x20retrieve\x20missing\x0amodules.</p>\x0a<p><a\x20id=\"private-module-proxy-private\"></a></p>\x0a<h3>Private\x20proxy\x20serving\x20private\x20modules</h3>\x0a<p>A\x20private\x20proxy\x20server\x20may\x20serve\x20private\x20modules\x20without\x20also\x20serving\x20publicly\x0aavailable\x20modules.\x20The\x20<code>go</code>\x20command\x20can\x20be\x20configured\x20to\x20fall\x20back\x20to\x0apublic\x20sources\x20for\x20modules\x20that\x20aren't\x20available\x20on\x20the\x20private\x20server.</p>\x0a<p>To\x20configure\x20the\x20<code>go</code>\x20command\x20to\x20work\x20this\x20way,\x20set\x20the\x20following\x20environment\x0avariables,\x20replacing\x20<code>https://proxy.corp.example.com</code>\x20with\x20the\x20proxy\x20URL\x20and\x0a<code>corp.example.com</code>\x20with\x20the\x20module\x20prefix:</p>\x0a<pre><code>GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct\x0aGONOSUMDB=corp.example.com\x0a</code></pre>\x0a<p>The\x20<code>GOPROXY</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20to\x20try\x20to\x20download\x20modules\x20from\x0a<code>https://proxy.corp.example.com</code>\x20first.\x20If\x20that\x20server\x20responds\x20with\x20404\x20(Not\x0aFound)\x20or\x20410\x20(Gone),\x20the\x20<code>go</code>\x20command\x20will\x20fall\x20back\x20to\x0a<code>https://proxy.golang.org</code>,\x20then\x20to\x20direct\x20connections\x20to\x20repositories.</p>\x0a<p>The\x20<code>GONOSUMDB</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20not\x20to\x20use\x20the\x20public\x20checksum\x0adatabase\x20to\x20authenticate\x20modules\x20whose\x20paths\x20start\x20with\x20<code>corp.example.com</code>.</p>\x0a<p>Note\x20that\x20a\x20proxy\x20used\x20in\x20this\x20configuration\x20may\x20still\x20control\x20access\x20to\x20public\x0amodules,\x20even\x20though\x20it\x20doesn't\x20serve\x20them.\x20If\x20the\x20proxy\x20responds\x20to\x20a\x20request\x0awith\x20an\x20error\x20status\x20other\x20than\x20404\x20or\x20410,\x20the\x20<code>go</code>\x20command\x20will\x20not\x20fall\x20back\x0ato\x20later\x20entries\x20in\x20the\x20<code>GOPROXY</code>\x20list.\x20For\x20example,\x20the\x20proxy\x20could\x20respond\x0awith\x20403\x20(Forbidden)\x20for\x20a\x20module\x20with\x20an\x20unsuitable\x20license\x20or\x20with\x20known\x0asecurity\x20vulnerabilities.</p>\x0a<p><a\x20id=\"private-module-proxy-direct\"></a></p>\x0a<h3>Direct\x20access\x20to\x20private\x20modules</h3>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20be\x20configured\x20to\x20bypass\x20public\x20proxies\x20and\x20download\x20private\x0amodules\x20directly\x20from\x20version\x20control\x20servers.\x20This\x20is\x20useful\x20when\x20running\x20a\x0aprivate\x20proxy\x20server\x20is\x20not\x20feasible.</p>\x0a<p>To\x20configure\x20the\x20<code>go</code>\x20command\x20to\x20work\x20this\x20way,\x20set\x20<code>GOPRIVATE</code>,\x20replacing\x0a<code>corp.example.com</code>\x20the\x20private\x20module\x20prefix:</p>\x0a<pre><code>GOPRIVATE=corp.example.com\x0a</code></pre>\x0a<p>The\x20<code>GOPROXY</code>\x20variable\x20does\x20not\x20need\x20to\x20be\x20changed\x20in\x20this\x20situation.\x20It\x0adefaults\x20to\x20<code>https://proxy.golang.org,direct</code>,\x20which\x20instructs\x20the\x20<code>go</code>\x20command\x0ato\x20attempt\x20to\x20download\x20modules\x20from\x20<code>https://proxy.golang.org</code>\x20first,\x20then\x20fall\x0aback\x20to\x20a\x20direct\x20connection\x20if\x20that\x20proxy\x20responds\x20with\x20404\x20(Not\x20Found)\x20or\x20410\x0a(Gone).</p>\x0a<p>The\x20<code>GOPRIVATE</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20not\x20to\x20connect\x20to\x20a\x20proxy\x20or\x0ato\x20the\x20checksum\x20database\x20for\x20modules\x20starting\x20with\x20<code>corp.example.com</code>.</p>\x0a<p>An\x20internal\x20HTTP\x20server\x20may\x20still\x20be\x20needed\x20to\x20<a\x20href=\"#vcs-find\">resolve\x20module\x20paths\x20to\x0arepository\x20URLs</a>.\x20For\x20example,\x20when\x20the\x20<code>go</code>\x20command\x20downloads\x20the\x0amodule\x20<code>corp.example.com/mod</code>,\x20it\x20will\x20send\x20a\x20GET\x20request\x20to\x0a<code>https://corp.example.com/mod?go-get=1</code>,\x20and\x20it\x20will\x20look\x20for\x20the\x20repository\x20URL\x0ain\x20the\x20response.\x20To\x20avoid\x20this\x20requirement,\x20ensure\x20that\x20each\x20private\x20module\x20path\x0ahas\x20a\x20VCS\x20suffix\x20(like\x20<code>.git</code>)\x20marking\x20the\x20repository\x20root\x20prefix.\x20For\x20example,\x0awhen\x20the\x20<code>go</code>\x20command\x20downloads\x20the\x20module\x20<code>corp.example.com/repo.git/mod</code>,\x20it\x0awill\x20clone\x20the\x20Git\x20repository\x20at\x20<code>https://corp.example.com/repo.git</code>\x20or\x0a<code>ssh://corp.example.com/repo.git</code>\x20without\x20needing\x20to\x20make\x20additional\x20requests.</p>\x0a<p>Developers\x20will\x20need\x20read\x20access\x20to\x20repositories\x20containing\x20private\x20modules.\x0aThis\x20may\x20be\x20configured\x20in\x20global\x20VCS\x20configuration\x20files\x20like\x20<code>.gitconfig</code>.\x0aIt's\x20best\x20if\x20VCS\x20tools\x20are\x20configured\x20not\x20to\x20need\x20interactive\x20authentication\x0aprompts.\x20By\x20default,\x20when\x20invoking\x20Git,\x20the\x20<code>go</code>\x20command\x20disables\x20interactive\x0aprompts\x20by\x20setting\x20<code>GIT_TERMINAL_PROMPT=0</code>,\x20but\x20it\x20respects\x20explicit\x20settings.</p>\x0a<p><a\x20id=\"private-module-proxy-auth\"></a></p>\x0a<h3>Passing\x20credentials\x20to\x20private\x20proxies</h3>\x0a<p>The\x20<code>go</code>\x20command\x20supports\x20HTTP\x20<a\x20href=\"https://en.wikipedia.org/wiki/Basic_access_authentication\">basic\x0aauthentication</a>\x20when\x0acommunicating\x20with\x20proxy\x20servers.</p>\x0a<p>Credentials\x20may\x20be\x20specified\x20in\x20a\x20<a\x20href=\"https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html\"><code>.netrc</code>\x0afile</a>.\x0aFor\x20example,\x20a\x20<code>.netrc</code>\x20file\x20containing\x20the\x20lines\x20below\x20would\x20configure\x20the\x20<code>go</code>\x0acommand\x20to\x20connect\x20to\x20the\x20machine\x20<code>proxy.corp.example.com</code>\x20with\x20the\x20given\x0ausername\x20and\x20password.</p>\x0a<pre><code>machine\x20proxy.corp.example.com\x0alogin\x20jrgopher\x0apassword\x20hunter2\x0a</code></pre>\x0a<p>The\x20location\x20of\x20the\x20file\x20may\x20be\x20set\x20with\x20the\x20<code>NETRC</code>\x20environment\x20variable.\x20If\x0a<code>NETRC</code>\x20is\x20not\x20set,\x20the\x20<code>go</code>\x20command\x20will\x20read\x20<code>$HOME/.netrc</code>\x20on\x20UNIX-like\x0aplatforms\x20or\x20<code>%USERPROFILE%\\_netrc</code>\x20on\x20Windows.</p>\x0a<p>Fields\x20in\x20<code>.netrc</code>\x20are\x20separated\x20with\x20spaces,\x20tabs,\x20and\x20newlines.\x20Unfortunately,\x0athese\x20characters\x20cannot\x20be\x20used\x20in\x20usernames\x20or\x20passwords.\x20Note\x20also\x20that\x20the\x0amachine\x20name\x20cannot\x20be\x20a\x20full\x20URL,\x20so\x20it's\x20not\x20possible\x20to\x20specify\x20different\x0ausernames\x20and\x20passwords\x20for\x20different\x20paths\x20on\x20the\x20same\x20machine.</p>\x0a<p>Alternatively,\x20credentials\x20may\x20be\x20specified\x20directly\x20in\x20<code>GOPROXY</code>\x20URLs.\x20For\x0aexample:</p>\x0a<pre><code>GOPROXY=https://jrgopher:hunter2@proxy.corp.example.com\x0a</code></pre>\x0a<p>Use\x20caution\x20when\x20taking\x20this\x20approach:\x20environment\x20variables\x20may\x20be\x20appear\x0ain\x20shell\x20history\x20and\x20in\x20logs.</p>\x0a<p><a\x20id=\"module-cache\"></a></p>\x0a<h2>Module\x20cache</h2>\x0a<p>The\x20<dfn>module\x20cache</dfn>\x20is\x20the\x20directory\x20where\x20the\x20<code>go</code>\x20command\x20stores\x0adownloaded\x20module\x20files.\x20The\x20module\x20cache\x20is\x20distinct\x20from\x20the\x20build\x20cache,\x0awhich\x20contains\x20compiled\x20packages\x20and\x20other\x20build\x20artifacts.</p>\x0a<p>The\x20default\x20location\x20of\x20the\x20module\x20cache\x20is\x20<code>$GOPATH/pkg/mod</code>.\x20To\x20use\x20a\x0adifferent\x20location,\x20set\x20the\x20<code>GOMODCACHE</code>\x20<a\x20href=\"#environment-variables\">environment\x0avariable</a>.</p>\x0a<p>The\x20module\x20cache\x20has\x20no\x20maximum\x20size,\x20and\x20the\x20<code>go</code>\x20command\x20does\x20not\x20remove\x20its\x0acontents\x20automatically.</p>\x0a<p>The\x20cache\x20may\x20be\x20shared\x20by\x20multiple\x20Go\x20projects\x20developed\x20on\x20the\x20same\x20machine.\x0aThe\x20<code>go</code>\x20command\x20will\x20use\x20the\x20same\x20cache\x20regardless\x20of\x20the\x20location\x20of\x20the\x0amain\x20module.\x20Multiple\x20instances\x20of\x20the\x20<code>go</code>\x20command\x20may\x20safely\x20access\x20the\x0asame\x20module\x20cache\x20at\x20the\x20same\x20time.</p>\x0a<p>The\x20<code>go</code>\x20command\x20creates\x20module\x20source\x20files\x20and\x20directories\x20in\x20the\x20cache\x20with\x0aread-only\x20permissions\x20to\x20prevent\x20accidental\x20changes\x20to\x20modules\x20after\x20they're\x0adownloaded.\x20This\x20has\x20the\x20unfortunate\x20side-effect\x20of\x20making\x20the\x20cache\x20difficult\x0ato\x20delete\x20with\x20commands\x20like\x20<code>rm\x20-rf</code>.\x20The\x20cache\x20may\x20instead\x20be\x20deleted\x20with\x0a<a\x20href=\"#go-clean-modcache\"><code>go\x20clean\x20-modcache</code></a>.\x20Alternatively,\x20when\x20the\x0a<code>-modcacherw</code>\x20flag\x20is\x20used,\x20the\x20<code>go</code>\x20command\x20will\x20create\x20new\x20directories\x20with\x0aread-write\x20permissions.\x20This\x20increases\x20the\x20risk\x20of\x20editors,\x20tests,\x20and\x20other\x0aprograms\x20modifying\x20files\x20in\x20the\x20module\x20cache.\x20The\x20<a\x20href=\"#go-mod-verify\"><code>go\x20mod\x20verify</code></a>\x20command\x20may\x20be\x20used\x20to\x20detect\x20modifications\x20to\x0adependencies\x20of\x20the\x20main\x20module.\x20It\x20scans\x20the\x20extracted\x20contents\x20of\x20each\x0amodule\x20dependency\x20and\x20confirms\x20they\x20match\x20the\x20expected\x20hash\x20in\x20<code>go.sum</code>.</p>\x0a<p>The\x20table\x20below\x20explains\x20the\x20purpose\x20of\x20most\x20files\x20in\x20the\x20module\x20cache.\x20Some\x0atransient\x20files\x20(lock\x20files,\x20temporary\x20directories)\x20are\x20omitted.\x20For\x20each\x20path,\x0a<code>$module</code>\x20is\x20a\x20module\x20path,\x20and\x20<code>$version</code>\x20is\x20a\x20version.\x20Paths\x20ending\x20with\x0aslashes\x20(<code>/</code>)\x20are\x20directories.\x20Capital\x20letters\x20in\x20module\x20paths\x20and\x20versions\x20are\x0aescaped\x20using\x20exclamation\x20points\x20(<code>Azure</code>\x20is\x20escaped\x20as\x20<code>!azure</code>)\x20to\x20avoid\x0aconflicts\x20on\x20case-insensitive\x20file\x20systems.</p>\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Path</th>\x0a\x20\x20\x20\x20\x20\x20<th>Description</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$module@$version/</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Directory\x20containing\x20extracted\x20contents\x20of\x20a\x20module\x20<code>.zip</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20file.\x20This\x20serves\x20as\x20a\x20module\x20root\x20directory\x20for\x20a\x20downloaded\x20module.\x20It\x0a\x20\x20\x20\x20\x20\x20\x20\x20won't\x20contain\x20contain\x20a\x20<code>go.mod</code>\x20file\x20if\x20the\x20original\x20module\x0a\x20\x20\x20\x20\x20\x20\x20\x20didn't\x20have\x20one.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Directory\x20containing\x20files\x20downloaded\x20from\x20module\x20proxies\x20and\x20files\x0a\x20\x20\x20\x20\x20\x20\x20\x20derived\x20from\x20<a\x20href=\"#vcs\">version\x20control\x20systems</a>.\x20The\x20layout\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20this\x20directory\x20follows\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>,\x20so\x0a\x20\x20\x20\x20\x20\x20\x20\x20this\x20directory\x20may\x20be\x20used\x20as\x20a\x20proxy\x20when\x20served\x20by\x20an\x20HTTP\x20file\x0a\x20\x20\x20\x20\x20\x20\x20\x20server\x20or\x20when\x20referenced\x20with\x20a\x20<code>file://</code>\x20URL.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/list</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20List\x20of\x20known\x20versions\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>).\x20This\x0a\x20\x20\x20\x20\x20\x20\x20\x20may\x20change\x20over\x20time,\x20so\x20the\x20<code>go</code>\x20command\x20usually\x20fetches\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20new\x20copy\x20instead\x20of\x20re-using\x20this\x20file.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/$version.info</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20JSON\x20metadata\x20about\x20the\x20version.\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>).\x20This\x0a\x20\x20\x20\x20\x20\x20\x20\x20may\x20change\x20over\x20time,\x20so\x20the\x20<code>go</code>\x20command\x20usually\x20fetches\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20new\x20copy\x20instead\x20of\x20re-using\x20this\x20file.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/$version.mod</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20The\x20<code>go.mod</code>\x20file\x20for\x20this\x20version\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>).\x20If\x0a\x20\x20\x20\x20\x20\x20\x20\x20the\x20original\x20module\x20did\x20not\x20have\x20a\x20<code>go.mod</code>\x20file,\x20this\x20is\x0a\x20\x20\x20\x20\x20\x20\x20\x20a\x20synthesized\x20file\x20with\x20no\x20requirements.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/$version.zip</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20The\x20zipped\x20contents\x20of\x20the\x20module\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#zip-files\">Module\x20zip\x20files</a>).\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/$version.ziphash</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20A\x20cryptographic\x20hash\x20of\x20the\x20files\x20in\x20the\x20<code>.zip</code>\x20file.\x0a\x20\x20\x20\x20\x20\x20\x20\x20Note\x20that\x20the\x20<code>.zip</code>\x20file\x20itself\x20is\x20not\x20hashed,\x20so\x20file\x0a\x20\x20\x20\x20\x20\x20\x20\x20order,\x20compression,\x20alignment,\x20and\x20metadata\x20don't\x20affect\x20the\x20hash.\x0a\x20\x20\x20\x20\x20\x20\x20\x20When\x20using\x20a\x20module,\x20the\x20<code>go</code>\x20command\x20verifies\x20this\x20hash\x0a\x20\x20\x20\x20\x20\x20\x20\x20matches\x20the\x20corresponding\x20line\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#go.sum-files\"><code>go.sum</code></a>.\x20The\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#go-mod-verify\"><code>go\x20mod\x20verify</code></a>\x20command\x20checks\x0a\x20\x20\x20\x20\x20\x20\x20\x20that\x20the\x20hashes\x20of\x20module\x20<code>.zip</code>\x20files\x20and\x20extracted\x0a\x20\x20\x20\x20\x20\x20\x20\x20directories\x20match\x20these\x20files.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/sumdb/</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Directory\x20containing\x20files\x20downloaded\x20from\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#checksum-database\">checksum\x20database</a>\x20(typically\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>sum.golang.org</code>).\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/vcs/</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Contains\x20cloned\x20version\x20control\x20repositories\x20for\x20modules\x20fetched\x0a\x20\x20\x20\x20\x20\x20\x20\x20directly\x20from\x20their\x20sources.\x20Directory\x20names\x20are\x20hex-encoded\x20hashes\x0a\x20\x20\x20\x20\x20\x20\x20\x20derived\x20from\x20the\x20repository\x20type\x20and\x20URL.\x20Repositories\x20are\x20optimized\x0a\x20\x20\x20\x20\x20\x20\x20\x20for\x20size\x20on\x20disk.\x20For\x20example,\x20cloned\x20Git\x20repositories\x20are\x20bare\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20shallow\x20when\x20possible.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<p><a\x20id=\"authenticating\"></a></p>\x0a<h2>Authenticating\x20modules</h2>\x0a<!--\x20TODO:\x20continue\x20this\x20section\x20-->\x0a<p>When\x20deciding\x20whether\x20to\x20trust\x20the\x20source\x20code\x20for\x20a\x20module\x20version\x20just\x0afetched\x20from\x20a\x20proxy\x20or\x20origin\x20server,\x20the\x20<code>go</code>\x20command\x20first\x20consults\x20the\x0a<code>go.sum</code>\x20lines\x20in\x20the\x20<code>go.sum</code>\x20file\x20of\x20the\x20current\x20module.\x20If\x20the\x20<code>go.sum</code>\x20file\x0adoes\x20not\x20contain\x20an\x20entry\x20for\x20that\x20module\x20version,\x20then\x20it\x20may\x20consult\x20the\x0achecksum\x20database.</p>\x0a<p><a\x20id=\"go.sum-files\"></a></p>\x0a<h3>go.sum\x20files</h3>\x0a<p>A\x20module\x20may\x20have\x20a\x20text\x20file\x20named\x20<code>go.sum</code>\x20in\x20its\x20root\x20directory,\x20alongside\x0aits\x20<code>go.mod</code>\x20file.\x20The\x20<code>go.sum</code>\x20file\x20contains\x20cryptographic\x20hashes\x20of\x20the\x0amodule's\x20direct\x20and\x20indirect\x20dependencies.\x20<code>go.sum</code>\x20may\x20be\x20empty\x20or\x20absent\x0aif\x20the\x20module\x20has\x20no\x20dependencies\x20or\x20if\x20all\x20dependencies\x20are\x20replaced\x20with\x0alocal\x20directories\x20using\x20<a\x20href=\"#go.mod-replace\"><code>replace</code>\x20directives</a>.</p>\x0a<p>Each\x20line\x20in\x20<code>go.sum</code>\x20has\x20three\x20fields\x20separated\x20by\x20spaces:\x20a\x20module\x20path,\x0aa\x20version\x20(possibly\x20ending\x20with\x20<code>/go.mod</code>),\x20and\x20a\x20hash.</p>\x0a<ul>\x0a<li>The\x20module\x20path\x20is\x20the\x20name\x20of\x20the\x20module\x20the\x20hash\x20belongs\x20to.</li>\x0a<li>The\x20version\x20is\x20the\x20version\x20of\x20the\x20module\x20the\x20hash\x20belongs\x20to.\x20If\x20the\x20version\x0aends\x20with\x20<code>/go.mod</code>,\x20the\x20hash\x20is\x20for\x20the\x20module's\x20<code>go.mod</code>\x20file\x20only;\x0aotherwise,\x20the\x20hash\x20is\x20for\x20the\x20files\x20within\x20the\x20module's\x20<code>.zip</code>\x20file.</li>\x0a<li>The\x20hash\x20column\x20consists\x20of\x20an\x20algorithm\x20name\x20(like\x20<code>h1</code>)\x20and\x20a\x20base64-encoded\x0acryptographic\x20hash,\x20separated\x20by\x20a\x20colon\x20(<code>:</code>).\x20Currently,\x20SHA-256\x20(<code>h1</code>)\x20is\x0athe\x20only\x20supported\x20hash\x20algorithm.\x20If\x20a\x20vulnerability\x20in\x20SHA-256\x20is\x20discovered\x0ain\x20the\x20future,\x20support\x20will\x20be\x20added\x20for\x20another\x20algorithm\x20(named\x20<code>h2</code>\x20and\x0aso\x20on).</li>\x0a</ul>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20downloads\x20a\x20module\x20<code>.mod</code>\x20or\x20<code>.zip</code>\x20file\x20into\x20the\x20<a\x20href=\"#module-cache\">module\x0acache</a>,\x20it\x20computes\x20a\x20hash\x20and\x20checks\x20that\x20the\x20hash\x20matches\x20the\x0acorresponding\x20hash\x20in\x20the\x20main\x20module's\x20<code>go.sum</code>\x20file.\x20For\x20<code>.mod</code>\x20files,\x20the\x0afile\x20contents\x20are\x20hashed.\x20For\x20<code>.zip</code>\x20files,\x20the\x20files\x20within\x20the\x20archive\x20are\x0ahashed.\x20The\x20hash\x20is\x20not\x20affected\x20by\x20file\x20ordering,\x20compression,\x20alignment,\x20or\x0ametadata.\x20See\x20<a\x20href=\"#zip-files\">Module\x20zip\x20files</a>\x20for\x20information\x20on\x20which\x20files\x20are\x0aincluded.\x20See\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/sumdb/dirhash?tab=doc\"><code>golang.org/x/mod/sumdb/dirhash</code></a>\x0afor\x20hash\x20implementation\x20details.</p>\x0a<p>If\x20the\x20computed\x20hash\x20does\x20not\x20match\x20the\x20corresponding\x20hash\x20in\x20<code>go.sum</code>,\x20the\x20<code>go</code>\x0acommand\x20reports\x20a\x20security\x20error.\x20If\x20the\x20hash\x20is\x20not\x20present\x20in\x20<code>go.sum</code>,\x20the\x0a<code>go</code>\x20command\x20looks\x20up\x20the\x20correct\x20hash\x20in\x20the\x20<a\x20href=\"#checksum-database\">checksum\x0adatabase</a>\x20(unless\x20the\x20module\x20matches\x20<code>GONOSUMDB</code>\x20or\x0a<code>GOSUMDB</code>\x20is\x20set\x20to\x20<code>off</code>;\x20see\x20<a\x20href=\"#environment-variables\">Environment\x0avariables</a>).\x20If\x20no\x20mismatch\x20is\x20detected,\x20the\x20<code>go</code>\x0acommand\x20adds\x20the\x20hash\x20to\x20<code>go.sum</code>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20does\x20not\x20automatically\x20verify\x20modules\x20already\x20in\x20the\x20cache.\x20By\x0adefault,\x20files\x20and\x20directories\x20in\x20the\x20module\x20cache\x20have\x20read-only\x20permissions\x20to\x0aprevent\x20accidental\x20changes.\x20The\x20<a\x20href=\"#go-mod-verify\"><code>go\x20mod\x20verify</code></a>\x20command\x20may\x20be\x0aused\x20to\x20check\x20that\x20<code>.zip</code>\x20files\x20and\x20extracted\x20directories\x20in\x20the\x20module\x20cache\x0amatch\x20hashes\x20recorded\x20when\x20they\x20were\x20downloaded.</p>\x0a<p>The\x20<code>go.sum</code>\x20file\x20may\x20contain\x20hashes\x20for\x20multiple\x20versions\x20of\x20a\x20module.\x20The\x20<code>go</code>\x0acommand\x20may\x20need\x20to\x20load\x20<code>go.mod</code>\x20files\x20from\x20multiple\x20versions\x20of\x20a\x20dependency\x0ain\x20order\x20to\x20perform\x20<a\x20href=\"#minimal-version-selection\">minimal\x20version\x20selection</a>.\x0a<code>go.sum</code>\x20may\x20also\x20contain\x20hashes\x20for\x20module\x20versions\x20that\x20aren't\x20needed\x20anymore\x0a(for\x20example,\x20after\x20an\x20upgrade).\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20will\x20add\x20missing\x0ahashes\x20and\x20will\x20remove\x20unnecessary\x20hashes\x20from\x20<code>go.sum</code>.</p>\x0a<p><a\x20id=\"checksum-database\"></a></p>\x0a<h3>Checksum\x20database</h3>\x0a<p>The\x20checksum\x20database\x20is\x20a\x20global\x20source\x20of\x20<code>go.sum</code>\x20lines.\x20The\x20<code>go</code>\x20command\x20can\x0ause\x20this\x20in\x20many\x20situations\x20to\x20detect\x20misbehavior\x20by\x20proxies\x20or\x20origin\x20servers.</p>\x0a<p>The\x20checksum\x20database\x20allows\x20for\x20global\x20consistency\x20and\x20reliability\x20for\x20all\x0apublicly\x20available\x20module\x20versions.\x20It\x20makes\x20untrusted\x20proxies\x20possible\x20since\x0athey\x20can't\x20serve\x20the\x20wrong\x20code\x20without\x20it\x20going\x20unnoticed.\x20It\x20also\x20ensures\x0athat\x20the\x20bits\x20associated\x20with\x20a\x20specific\x20version\x20do\x20not\x20change\x20from\x20one\x20day\x20to\x0athe\x20next,\x20even\x20if\x20the\x20module's\x20author\x20subsequently\x20alters\x20the\x20tags\x20in\x20their\x0arepository.</p>\x0a<p>The\x20checksum\x20database\x20is\x20served\x20by\x20<a\x20href=\"https://sum.golang.org\">sum.golang.org</a>,\x0awhich\x20is\x20run\x20by\x20Google.\x20It\x20is\x20a\x20<a\x20href=\"https://research.swtch.com/tlog\">Transparent\x0aLog</a>\x20(or\x20\xe2\x80\x9cMerkle\x20Tree\xe2\x80\x9d)\x20of\x20<code>go.sum</code>\x20line\x0ahashes,\x20which\x20is\x20backed\x20by\x20<a\x20href=\"https://github.com/google/trillian\">Trillian</a>.\x20The\x0amain\x20advantage\x20of\x20a\x20Merkle\x20tree\x20is\x20that\x20independent\x20auditors\x20can\x20verify\x20that\x20it\x0ahasn't\x20been\x20tampered\x20with,\x20so\x20it\x20is\x20more\x20trustworthy\x20than\x20a\x20simple\x20database.</p>\x0a<p>The\x20<code>go</code>\x20command\x20interacts\x20with\x20the\x20checksum\x20database\x20using\x20the\x20protocol\x0aoriginally\x20outlined\x20in\x20<a\x20href=\"https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#checksum-database\">Proposal:\x20Secure\x20the\x20Public\x20Go\x20Module\x0aEcosystem</a>.</p>\x0a<p>The\x20table\x20below\x20specifies\x20queries\x20that\x20the\x20checksum\x20database\x20must\x20respond\x20to.\x0aFor\x20each\x20path,\x20<code>$base</code>\x20is\x20the\x20path\x20portion\x20of\x20the\x20checksum\x20database\x20URL,\x0a<code>$module</code>\x20is\x20a\x20module\x20path,\x20and\x20<code>$version</code>\x20is\x20a\x20version.\x20For\x20example,\x20if\x20the\x0achecksum\x20database\x20URL\x20is\x20<code>https://sum.golang.org</code>,\x20and\x20the\x20client\x20is\x20requesting\x0athe\x20record\x20for\x20the\x20module\x20<code>golang.org/x/text</code>\x20at\x20version\x20<code>v0.3.2</code>,\x20the\x20client\x0awould\x20send\x20a\x20<code>GET</code>\x20request\x20for\x0a<code>https://sum.golang.org/lookup/golang.org/x/text@v0.3.2</code>.</p>\x0a<p>To\x20avoid\x20ambiguity\x20when\x20serving\x20from\x20case-insensitive\x20file\x20systems,\x0athe\x20<code>$module</code>\x20and\x20<code>$version</code>\x20elements\x20are\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/module#EscapePath\">case-encoded</a>\x0aby\x20replacing\x20every\x20uppercase\x20letter\x20with\x20an\x20exclamation\x20mark\x20followed\x20by\x20the\x0acorresponding\x20lower-case\x20letter.\x20This\x20allows\x20modules\x20<code>example.com/M</code>\x20and\x0a<code>example.com/m</code>\x20to\x20both\x20be\x20stored\x20on\x20disk,\x20since\x20the\x20former\x20is\x20encoded\x20as\x0a<code>example.com/!m</code>.</p>\x0a<p>Parts\x20of\x20the\x20path\x20surrounded\x20by\x20square\x20brakets,\x20like\x20<code>[.p/$W]</code>\x20denote\x20optional\x0avalues.</p>\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Path</th>\x0a\x20\x20\x20\x20\x20\x20<th>Description</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/latest</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20a\x20signed,\x20encoded\x20tree\x20description\x20for\x20the\x20latest\x20log.\x20This\x0a\x20\x20\x20\x20\x20\x20\x20\x20signed\x20description\x20is\x20in\x20the\x20form\x20of\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/sumdb/note\">note</a>,\x0a\x20\x20\x20\x20\x20\x20\x20\x20which\x20is\x20text\x20that\x20has\x20been\x20signed\x20by\x20one\x20or\x20more\x20server\x20keys\x20and\x20can\x0a\x20\x20\x20\x20\x20\x20\x20\x20be\x20verified\x20using\x20the\x20server's\x20public\x20key.\x20The\x20tree\x20description\x0a\x20\x20\x20\x20\x20\x20\x20\x20provides\x20the\x20size\x20of\x20the\x20tree\x20and\x20the\x20hash\x20of\x20the\x20tree\x20head\x20at\x20that\x0a\x20\x20\x20\x20\x20\x20\x20\x20size.\x20This\x20encoding\x20is\x20described\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code><a\x20href=\"https://pkg.go.dev/golang.org/x/mod/sumdb/tlog#FormatTree\">\x0a\x20\x20\x20\x20\x20\x20\x20\x20golang.org/x/mod/sumdb/tlog#FormatTree</a></code>.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/lookup/$module@$version</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20the\x20log\x20record\x20number\x20for\x20the\x20entry\x20about\x20<code>$module</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20at\x20<code>$version</code>,\x20followed\x20by\x20the\x20data\x20for\x20the\x20record\x20(that\x20is,\x0a\x20\x20\x20\x20\x20\x20\x20\x20the\x20<code>go.sum</code>\x20lines\x20for\x20<code>$module</code>\x20at\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>$version</code>)\x20and\x20a\x20signed,\x20encoded\x20tree\x20description\x20that\x0a\x20\x20\x20\x20\x20\x20\x20\x20contains\x20the\x20record.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/tile/$H/$L/$K[.p/$W]</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20a\x20[log\x20tile](https://research.swtch.com/tlog#serving_tiles),\x0a\x20\x20\x20\x20\x20\x20\x20\x20which\x20is\x20a\x20set\x20of\x20hashes\x20that\x20make\x20up\x20a\x20section\x20of\x20the\x20log.\x20Each\x20tile\x0a\x20\x20\x20\x20\x20\x20\x20\x20is\x20defined\x20in\x20a\x20two-dimensional\x20coordinate\x20at\x20tile\x20level\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>$L</code>,\x20<code>$K</code>th\x20from\x20the\x20left,\x20with\x20a\x20tile\x20height\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>$H</code>.\x20The\x20optional\x20<code>.p/$W</code>\x20suffix\x20indicates\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20partial\x20log\x20tile\x20with\x20only\x20<code>$W</code>\x20hashes.\x20Clients\x20must\x20fall\x0a\x20\x20\x20\x20\x20\x20\x20\x20back\x20to\x20fetching\x20the\x20full\x20tile\x20if\x20a\x20partial\x20tile\x20is\x20not\x20found.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/tile/$H/data/$K[.p/$W]</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20the\x20record\x20data\x20for\x20the\x20leaf\x20hashes\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>/tile/$H/0/$K[.p/$W]</code>\x20(with\x20a\x20literal\x20<code>data</code>\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20element).\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<p>If\x20the\x20<code>go</code>\x20command\x20consults\x20the\x20checksum\x20database,\x20then\x20the\x20first\x0astep\x20is\x20to\x20retrieve\x20the\x20record\x20data\x20through\x20the\x20<code>/lookup</code>\x20endpoint.\x20If\x20the\x0amodule\x20version\x20is\x20not\x20yet\x20recorded\x20in\x20the\x20log,\x20the\x20checksum\x20database\x20will\x20try\x0ato\x20fetch\x20it\x20from\x20the\x20origin\x20server\x20before\x20replying.\x20This\x20<code>/lookup</code>\x20data\x0aprovides\x20the\x20sum\x20for\x20this\x20module\x20version\x20as\x20well\x20as\x20its\x20position\x20in\x20the\x20log,\x0awhich\x20informs\x20the\x20client\x20of\x20which\x20tiles\x20should\x20be\x20fetched\x20to\x20perform\x20proofs.\x0aThe\x20<code>go</code>\x20command\x20performs\x20\xe2\x80\x9cinclusion\xe2\x80\x9d\x20proofs\x20(that\x20a\x20specific\x20record\x20exists\x20in\x0athe\x20log)\x20and\x20\xe2\x80\x9cconsistency\xe2\x80\x9d\x20proofs\x20(that\x20the\x20tree\x20hasn\xe2\x80\x99t\x20been\x20tampered\x20with)\x0abefore\x20adding\x20new\x20<code>go.sum</code>\x20lines\x20to\x20the\x20main\x20module\xe2\x80\x99s\x20<code>go.sum</code>\x20file.\x20It's\x0aimportant\x20that\x20the\x20data\x20from\x20<code>/lookup</code>\x20should\x20never\x20be\x20used\x20without\x20first\x0aauthenticating\x20it\x20against\x20the\x20signed\x20tree\x20hash\x20and\x20authenticating\x20the\x20signed\x0atree\x20hash\x20against\x20the\x20client's\x20timeline\x20of\x20signed\x20tree\x20hashes.</p>\x0a<p>Signed\x20tree\x20hashes\x20and\x20new\x20tiles\x20served\x20by\x20the\x20checksum\x20database\x20are\x20stored\x0ain\x20the\x20module\x20cache,\x20so\x20the\x20<code>go</code>\x20command\x20only\x20needs\x20to\x20fetch\x20tiles\x20that\x20are\x0amissing.</p>\x0a<p>The\x20<code>go</code>\x20command\x20doesn't\x20need\x20to\x20directly\x20connect\x20to\x20the\x20checksum\x20database.\x20It\x0acan\x20request\x20module\x20sums\x20via\x20a\x20module\x20proxy\x20that\x0a<a\x20href=\"https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#proxying-a-checksum-database\">mirrors\x20the\x20checksum\x20database</a>\x0aand\x20supports\x20the\x20protocol\x20above.\x20This\x20can\x20be\x20particularly\x20helpful\x20for\x20private,\x0acorporate\x20proxies\x20which\x20block\x20requests\x20outside\x20the\x20organization.</p>\x0a<p>The\x20<code>GOSUMDB</code>\x20environment\x20variable\x20identifies\x20the\x20name\x20of\x20checksum\x20database\x20to\x20use\x0aand\x20optionally\x20its\x20public\x20key\x20and\x20URL,\x20as\x20in:</p>\x0a<pre><code>GOSUMDB=&quot;sum.golang.org&quot;\x0aGOSUMDB=&quot;sum.golang.org+&lt;publickey&gt;&quot;\x0aGOSUMDB=&quot;sum.golang.org+&lt;publickey&gt;\x20https://sum.golang.org&quot;\x0a</code></pre>\x0a<p>The\x20<code>go</code>\x20command\x20knows\x20the\x20public\x20key\x20of\x20<code>sum.golang.org</code>,\x20and\x20also\x20that\x20the\x0aname\x20<code>sum.golang.google.cn</code>\x20(available\x20inside\x20mainland\x20China)\x20connects\x20to\x20the\x0a<code>sum.golang.org</code>\x20checksum\x20database;\x20use\x20of\x20any\x20other\x20database\x20requires\x20giving\x0athe\x20public\x20key\x20explicitly.\x20The\x20URL\x20defaults\x20to\x20<code>https://</code>\x20followed\x20by\x20the\x0adatabase\x20name.</p>\x0a<p><code>GOSUMDB</code>\x20defaults\x20to\x20<code>sum.golang.org</code>,\x20the\x20Go\x20checksum\x20database\x20run\x20by\x20Google.\x0aSee\x20https://sum.golang.org/privacy\x20for\x20the\x20service's\x20privacy\x20policy.</p>\x0a<p>If\x20<code>GOSUMDB</code>\x20is\x20set\x20to\x20<code>off</code>,\x20or\x20if\x20<code>go\x20get</code>\x20is\x20invoked\x20with\x20the\x20<code>-insecure</code>\x0aflag,\x20the\x20checksum\x20database\x20is\x20not\x20consulted,\x20and\x20all\x20unrecognized\x20modules\x20are\x0aaccepted,\x20at\x20the\x20cost\x20of\x20giving\x20up\x20the\x20security\x20guarantee\x20of\x20verified\x0arepeatable\x20downloads\x20for\x20all\x20modules.\x20A\x20better\x20way\x20to\x20bypass\x20the\x20checksum\x0adatabase\x20for\x20specific\x20modules\x20is\x20to\x20use\x20the\x20<code>GOPRIVATE</code>\x20or\x20<code>GONOSUMDB</code>\x0aenvironment\x20variables.\x20See\x20<a\x20href=\"#private-modules\">Private\x20Modules</a>\x20for\x20details.</p>\x0a<p>The\x20<code>go\x20env\x20-w</code>\x20command\x20can\x20be\x20used\x20to\x0a<a\x20href=\"/pkg/cmd/go/#hdr-Print_Go_environment_information\">set\x20these\x20variables</a>\x0afor\x20future\x20<code>go</code>\x20command\x20invocations.</p>\x0a<p><a\x20id=\"privacy\"></a></p>\x0a<h2>Privacy</h2>\x0a<p><a\x20id=\"environment-variables\"></a></p>\x0a<h2>Environment\x20variables</h2>\x0a<p>Module\x20behavior\x20in\x20the\x20<code>go</code>\x20command\x20may\x20be\x20configured\x20using\x20the\x20environment\x0avariables\x20listed\x20below.\x20This\x20list\x20only\x20includes\x20module-related\x20environment\x0avariables.\x20See\x20<a\x20href=\"https://golang.org/cmd/go/#hdr-Environment_variables\"><code>go\x20help\x20environment</code></a>\x20for\x20a\x20list\x0aof\x20all\x20environment\x20variables\x20recognized\x20by\x20the\x20<code>go</code>\x20command.</p>\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Variable</th>\x0a\x20\x20\x20\x20\x20\x20<th>Description</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GO111MODULE</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Controls\x20whether\x20the\x20<code>go</code>\x20command\x20runs\x20in\x20module-aware\x20mode\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20or\x20<code>GOPATH</code>\x20mode.\x20Three\x20values\x20are\x20recognized:\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<ul>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>off</code>:\x20the\x20<code>go</code>\x20command\x20ignores\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>go.mod</code>\x20files\x20and\x20runs\x20in\x20<code>GOPATH</code>\x20mode.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>on</code>:\x20the\x20<code>go</code>\x20command\x20runs\x20in\x20module-aware\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20mode,\x20even\x20when\x20no\x20<code>go.mod</code>\x20file\x20is\x20present.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>auto</code>\x20(or\x20unset):\x20the\x20<code>go</code>\x20command\x20runs\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20module-aware\x20mode\x20if\x20a\x20<code>go.mod</code>\x20file\x20is\x20present\x20in\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20current\x20directory\x20or\x20any\x20parent\x20directory\x20(the\x20default\x20behavior).\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20</ul>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20See\x20<a\x20href=\"mod-commands\">Module-aware\x20commands</a>\x20for\x20more\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20information.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOMODCACHE</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20directory\x20where\x20the\x20<code>go</code>\x20command\x20will\x20store\x20downloaded\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20modules\x20and\x20related\x20files.\x20See\x20<a\x20href=\"#module-cache\">Module\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20cache</a>\x20for\x20details\x20on\x20the\x20structure\x20of\x20this\x20directory.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GOMODCACHE</code>\x20is\x20not\x20set,\x20it\x20defaults\x20to\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>$GOPATH/pkg/mod</code>.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOINSECURE</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20glob\x20patterns\x20(in\x20the\x20syntax\x20of\x20Go's\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"/pkg/path/#Match\"><code>path.Match</code></a>)\x20of\x20module\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20prefixes\x20that\x20may\x20always\x20be\x20fetched\x20in\x20an\x20insecure\x20manner.\x20Only\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20applies\x20to\x20dependencies\x20that\x20are\x20being\x20fetched\x20directly.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Unlike\x20the\x20<code>-insecure</code>\x20flag\x20on\x20<code>go\x20get</code>,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOINSECURE</code>\x20does\x20not\x20disable\x20module\x20checksum\x20database\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20validation.\x20<code>GOPRIVATE</code>\x20or\x20<code>GONOSUMDB</code>\x20may\x20be\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20used\x20to\x20achieve\x20that.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GONOPROXY</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20glob\x20patterns\x20(in\x20the\x20syntax\x20of\x20Go's\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"/pkg/path/#Match\"><code>path.Match</code></a>)\x20of\x20module\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20prefixes\x20that\x20should\x20always\x20be\x20fetched\x20directly\x20from\x20version\x20control\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20repositories,\x20not\x20from\x20module\x20proxies.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GONOPROXY</code>\x20is\x20not\x20set,\x20it\x20defaults\x20to\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPRIVATE</code>.\x20See\x20<a\x20href=\"#privacy\">Privacy</a>.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GONOSUMDB</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20glob\x20patterns\x20(in\x20the\x20syntax\x20of\x20Go's\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"/pkg/path/#Match\"><code>path.Match</code></a>)\x20of\x20module\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20prefixes\x20for\x20which\x20the\x20<code>go</code>\x20should\x20not\x20verify\x20checksums\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20using\x20the\x20checksum\x20database.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GONOSUMDB</code>\x20is\x20not\x20set,\x20it\x20defaults\x20to\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPRIVATE</code>.\x20See\x20<a\x20href=\"#privacy\">Privacy</a>.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOPATH</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20In\x20<code>GOPATH</code>\x20mode,\x20the\x20<code>GOPATH</code>\x20variable\x20is\x20a\x20list\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20of\x20directories\x20that\x20may\x20contain\x20Go\x20code.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20In\x20module-aware\x20mode,\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20cache</a>\x20is\x20stored\x20in\x20the\x20<code>pkg/mod</code>\x20subdirectory\x20of\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20first\x20<code>GOPATH</code>\x20directory.\x20Module\x20source\x20code\x20outside\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20cache\x20may\x20be\x20stored\x20in\x20any\x20directory.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GOPATH</code>\x20is\x20not\x20set,\x20it\x20defaults\x20to\x20the\x20<code>go</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20subdirectory\x20of\x20the\x20user's\x20home\x20directory.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOPRIVATE</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20glob\x20patterns\x20(in\x20the\x20syntax\x20of\x20Go's\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"/pkg/path/#Match\"><code>path.Match</code></a>)\x20of\x20module\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20prefixes\x20that\x20should\x20be\x20considered\x20private.\x20<code>GOPRIVATE</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20is\x20a\x20default\x20value\x20for\x20<code>GONOPROXY</code>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>GONOSUMDB</code>.\x20<code>GOPRIVATE</code>\x20itself\x20has\x20no\x20other\x0a\x20\x20\x20\x20\x20\x20\x20\x20meaning.\x20See\x20<a\x20href=\"#privacy\">Privacy</a>.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOPROXY</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20module\x20proxy\x20URLs.\x20When\x20the\x20<code>go</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20command\x20looks\x20up\x20information\x20about\x20a\x20module,\x20it\x20will\x20contact\x20each\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20proxy\x20in\x20the\x20list,\x20in\x20sequence.\x20A\x20proxy\x20may\x20respond\x20with\x20a\x20404\x20(Not\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Found)\x20or\x20410\x20(Gone)\x20status\x20to\x20indicate\x20the\x20module\x20is\x20not\x20available\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20and\x20the\x20<code>go</code>\x20command\x20should\x20contact\x20the\x20next\x20proxy\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20the\x20list.\x20Any\x20other\x20error\x20will\x20cause\x20the\x20<code>go</code>\x20command\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20to\x20stop\x20without\x20contacting\x20other\x20proxies\x20in\x20the\x20list.\x20This\x20allows\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20a\x20proxy\x20to\x20act\x20as\x20a\x20gatekeeper,\x20for\x20example,\x20by\x20responding\x20with\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20403\x20(Forbidden)\x20for\x20modules\x20not\x20on\x20an\x20approved\x20list.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPROXY</code>\x20URLs\x20may\x20have\x20the\x20schemes\x20<code>https</code>,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>http</code>,\x20or\x20<code>file</code>.\x20If\x20no\x20scheme\x20is\x20specified,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>https</code>\x20is\x20assumed.\x20A\x20module\x20cache\x20may\x20be\x20used\x20direclty\x20as\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20a\x20file\x20proxy:\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<pre>GOPROXY=file://$(go\x20env\x20GOPATH)/pkg/mod/cache/download</pre>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>Two\x20keywords\x20may\x20be\x20used\x20in\x20place\x20of\x20proxy\x20URLs:</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<ul>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>off</code>:\x20disallows\x20downloading\x20modules\x20from\x20any\x20source.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>direct</code>:\x20download\x20directly\x20from\x20version\x20control\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20repositories.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20</ul>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPROXY</code>\x20defaults\x20to\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>https://proxy.golang.org,direct</code>.\x20Under\x20that\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20configuration,\x20the\x20<code>go</code>\x20command\x20will\x20first\x20contact\x20the\x20Go\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20module\x20mirror\x20run\x20by\x20Google,\x20then\x20fall\x20back\x20to\x20a\x20direct\x20connection\x20if\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20the\x20mirror\x20does\x20not\x20have\x20the\x20module.\x20See\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"https://proxy.golang.org/privacy\">https://proxy.golang.org/privacy</a>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20for\x20the\x20mirror's\x20privacy\x20policy.\x20The\x20<code>GOPRIVATE</code>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GONOPROXY</code>\x20environment\x20variables\x20may\x20be\x20set\x20to\x20prevent\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20specific\x20modules\x20from\x20being\x20downloaded\x20using\x20proxies.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20See\x20<a\x20href=\"#module-proxy\">Module\x20proxies</a>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#resolve-pkg-mod\">Resolving\x20a\x20package\x20to\x20a\x20module</a>\x20for\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20more\x20information.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOSUMDB</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Identifies\x20the\x20name\x20of\x20the\x20checksum\x20database\x20to\x20use\x20and\x20optionally\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20its\x20public\x20key\x20and\x20URL.\x20For\x20example:\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<pre>\x0aGOSUMDB=\"sum.golang.org\"\x0aGOSUMDB=\"sum.golang.org+&lt;publickey&gt;\"\x0aGOSUMDB=\"sum.golang.org+&lt;publickey&gt;\x20https://sum.golang.org\x0a</pre>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20<code>go</code>\x20command\x20knows\x20the\x20public\x20key\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>sum.golang.org</code>\x20and\x20also\x20that\x20the\x20name\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>sum.golang.google.cn</code>\x20(available\x20inside\x20mainland\x20China)\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20connects\x20to\x20the\x20<code>sum.golang.org</code>\x20database;\x20use\x20of\x20any\x20other\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20database\x20requires\x20giving\x20the\x20public\x20key\x20explicitly.\x20The\x20URL\x20defaults\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20to\x20<code>https://</code>\x20followed\x20by\x20the\x20database\x20name.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOSUMDB</code>\x20defaults\x20to\x20<code>sum.golang.org</code>,\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Go\x20checksum\x20database\x20run\x20by\x20Google.\x20See\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"https://sum.golang.org/privacy\">https://sum.golang.org/privacy</a>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20for\x20the\x20service's\x20privacy\x20policy.\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GOSUMDB</code>\x20is\x20set\x20to\x20<code>off</code>\x20or\x20if\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20get</code>\x20is\x20invoked\x20with\x20the\x20<code>-insecure</code>\x20flag,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20the\x20checksum\x20database\x20is\x20not\x20consulted,\x20and\x20all\x20unrecognized\x20modules\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20are\x20accepted,\x20at\x20the\x20cost\x20of\x20giving\x20up\x20the\x20security\x20guarantee\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20verified\x20repeatable\x20downloads\x20for\x20all\x20modules.\x20A\x20better\x20way\x20to\x20bypass\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20the\x20checksum\x20database\x20for\x20specific\x20modules\x20is\x20to\x20use\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPRIVATE</code>\x20or\x20<code>GONOSUMDB</code>\x20environment\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20variables.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20See\x20<a\x20href=\"#authenticating\">Authenticating\x20modules</a>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#privacy\">Privacy</a>\x20for\x20more\x20information.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<p><a\x20id=\"glossary\"></a></p>\x0a<h2>Glossary</h2>\x0a<p><a\x20id=\"glos-build-constraint\"></a>\x0a<strong>build\x20constraint:</strong>\x20A\x20condition\x20that\x20determines\x20whether\x20a\x20Go\x20source\x20file\x20is\x0aused\x20when\x20compiling\x20a\x20package.\x20Build\x20constraints\x20may\x20be\x20expressed\x20with\x20file\x20name\x0asuffixes\x20(for\x20example,\x20<code>foo_linux_amd64.go</code>)\x20or\x20with\x20build\x20constraint\x20comments\x0a(for\x20example,\x20<code>//\x20+build\x20linux,amd64</code>).\x20See\x20<a\x20href=\"https://golang.org/pkg/go/build/#hdr-Build_Constraints\">Build\x0aConstraints</a>.</p>\x0a<p><a\x20id=\"glos-build-list\"></a>\x0a<strong>build\x20list:</strong>\x20The\x20list\x20of\x20module\x20versions\x20that\x20will\x20be\x20used\x20for\x20a\x20build\x0acommand\x20such\x20as\x20<code>go\x20build</code>,\x20<code>go\x20list</code>,\x20or\x20<code>go\x20test</code>.\x20The\x20build\x20list\x20is\x0adetermined\x20from\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module's</a>\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x0afile</a>\x20and\x20<code>go.mod</code>\x20files\x20in\x20transitively\x20required\x20modules\x0ausing\x20<a\x20href=\"#glos-minimal-version-selection\">minimal\x20version\x20selection</a>.\x20The\x20build\x0alist\x20contains\x20versions\x20for\x20all\x20modules\x20in\x20the\x20<a\x20href=\"#glos-module-graph\">module\x0agraph</a>,\x20not\x20just\x20those\x20relevant\x20to\x20a\x20specific\x20command.</p>\x0a<p><a\x20id=\"glos-canonical-version\"></a>\x0a<strong>canonical\x20version:</strong>\x20A\x20correctly\x20formatted\x20<a\x20href=\"#glos-version\">version</a>\x20without\x0aa\x20build\x20metadata\x20suffix\x20other\x20than\x20<code>+incompatible</code>.\x20For\x20example,\x20<code>v1.2.3</code>\x0ais\x20a\x20canonical\x20version,\x20but\x20<code>v1.2.3+meta</code>\x20is\x20not.</p>\x0a<p><a\x20id=\"glos-go.mod-file\"></a>\x0a<strong><code>go.mod</code>\x20file:</strong>\x20The\x20file\x20that\x20defines\x20a\x20module's\x20path,\x20requirements,\x20and\x0aother\x20metadata.\x20Appears\x20in\x20the\x20<a\x20href=\"#glos-module-root-directory\">module's\x20root\x0adirectory</a>.\x20See\x20the\x20section\x20on\x20<a\x20href=\"#go.mod-files\"><code>go.mod</code>\x0afiles</a>.</p>\x0a<p><a\x20id=\"glos-import-path\"></a>\x0a<strong>import\x20path:</strong>\x20A\x20string\x20used\x20to\x20import\x20a\x20package\x20in\x20a\x20Go\x20source\x20file.\x0aSynonymous\x20with\x20<a\x20href=\"#glos-package-path\">package\x20path</a>.</p>\x0a<p><a\x20id=\"glos-main-module\"></a>\x0a<strong>main\x20module:</strong>\x20The\x20module\x20in\x20which\x20the\x20<code>go</code>\x20command\x20is\x20invoked.</p>\x0a<p><a\x20id=\"glos-major-version\"></a>\x0a<strong>major\x20version:</strong>\x20The\x20first\x20number\x20in\x20a\x20semantic\x20version\x20(<code>1</code>\x20in\x20<code>v1.2.3</code>).\x20In\x0aa\x20release\x20with\x20incompatible\x20changes,\x20the\x20major\x20version\x20must\x20be\x20incremented,\x20and\x0athe\x20minor\x20and\x20patch\x20versions\x20must\x20be\x20set\x20to\x200.\x20Semantic\x20versions\x20with\x20major\x0aversion\x200\x20are\x20considered\x20unstable.</p>\x0a<p><a\x20id=\"glos-major-version-subdirectory\"></a>\x0a<strong>major\x20version\x20subdirectory:</strong>\x20A\x20subdirectory\x20within\x20a\x20version\x20control\x0arepository\x20matching\x20a\x20module's\x20<a\x20href=\"#glos-major-version-suffix\">major\x20version\x0asuffix</a>\x20where\x20a\x20module\x20may\x20be\x20defined.\x20For\x20example,\x0athe\x20module\x20<code>example.com/mod/v2</code>\x20in\x20the\x20repository\x20with\x20<a\x20href=\"#glos-repository-root-path\">root\x0apath</a>\x20<code>example.com/mod</code>\x20may\x20be\x20defined\x20in\x20the\x0arepository\x20root\x20directory\x20or\x20the\x20major\x20version\x20subdirectory\x20<code>v2</code>.\x20See\x20<a\x20href=\"#vcs-dir\">Module\x0adirectories\x20within\x20a\x20repository</a>.</p>\x0a<p><a\x20id=\"glos-major-version-suffix\"></a>\x0a<strong>major\x20version\x20suffix:</strong>\x20A\x20module\x20path\x20suffix\x20that\x20matches\x20the\x20major\x20version\x0anumber.\x20For\x20example,\x20<code>/v2</code>\x20in\x20<code>example.com/mod/v2</code>.\x20Major\x20version\x20suffixes\x20are\x0arequired\x20at\x20<code>v2.0.0</code>\x20and\x20later\x20and\x20are\x20not\x20allowed\x20at\x20earlier\x20versions.\x20See\x0athe\x20section\x20on\x20<a\x20href=\"#major-version-suffixes\">Major\x20version\x20suffixes</a>.</p>\x0a<p><a\x20id=\"glos-minimal-version-selection\"></a>\x0a<strong>minimal\x20version\x20selection\x20(MVS):</strong>\x20The\x20algorithm\x20used\x20to\x20determine\x20the\x0aversions\x20of\x20all\x20modules\x20that\x20will\x20be\x20used\x20in\x20a\x20build.\x20See\x20the\x20section\x20on\x0a<a\x20href=\"#minimal-version-selection\">Minimal\x20version\x20selection</a>\x20for\x20details.</p>\x0a<p><a\x20id=\"glos-minor-version\"></a>\x0a<strong>minor\x20version:</strong>\x20The\x20second\x20number\x20in\x20a\x20semantic\x20version\x20(<code>2</code>\x20in\x20<code>v1.2.3</code>).\x20In\x0aa\x20release\x20with\x20new,\x20backwards\x20compatible\x20functionality,\x20the\x20minor\x20version\x20must\x0abe\x20incremented,\x20and\x20the\x20patch\x20version\x20must\x20be\x20set\x20to\x200.</p>\x0a<p><a\x20id=\"glos-module\"></a>\x0a<strong>module:</strong>\x20A\x20collection\x20of\x20packages\x20that\x20are\x20released,\x20versioned,\x20and\x0adistributed\x20together.</p>\x0a<p><a\x20id=\"glos-module-cache\"></a>\x0a<strong>module\x20cache:</strong>\x20A\x20local\x20directory\x20storing\x20downloaded\x20modules,\x20located\x20in\x0a<code>GOPATH/pkg/mod</code>.\x20See\x20<a\x20href=\"#module-cache\">Module\x20cache</a>.</p>\x0a<p><a\x20id=\"glos-module-graph\"></a>\x0a<strong>module\x20graph:</strong>\x20The\x20directed\x20graph\x20of\x20module\x20requirements,\x20rooted\x20at\x20the\x20<a\x20href=\"#glos-main-module\">main\x0amodule</a>.\x20Each\x20vertex\x20in\x20the\x20graph\x20is\x20a\x20module;\x20each\x20edge\x20is\x20a\x0aversion\x20from\x20a\x20<code>require</code>\x20statement\x20in\x20a\x20<code>go.mod</code>\x20file\x20(subject\x20to\x20<code>replace</code>\x20and\x0a<code>exclude</code>\x20statements\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file.</p>\x0a<p><a\x20id=\"glos-module-path\"></a>\x0a<strong>module\x20path:</strong>\x20A\x20path\x20that\x20identifies\x20a\x20module\x20and\x20acts\x20as\x20a\x20prefix\x20for\x0apackage\x20import\x20paths\x20within\x20the\x20module.\x20For\x20example,\x20<code>&quot;golang.org/x/net&quot;</code>.</p>\x0a<p><a\x20id=\"glos-module-proxy\"></a>\x0a<strong>module\x20proxy:</strong>\x20A\x20web\x20server\x20that\x20implements\x20the\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x0aprotocol</a>.\x20The\x20<code>go</code>\x20command\x20downloads\x20version\x20information,\x0a<code>go.mod</code>\x20files,\x20and\x20module\x20zip\x20files\x20from\x20module\x20proxies.</p>\x0a<p><a\x20id=\"glos-module-root-directory\"></a>\x0a<strong>module\x20root\x20directory:</strong>\x20The\x20directory\x20that\x20contains\x20the\x20<code>go.mod</code>\x20file\x20that\x0adefines\x20a\x20module.</p>\x0a<p><a\x20id=\"glos-module-subdirectory\"></a>\x0a<strong>module\x20subdirectory:</strong>\x20The\x20portion\x20of\x20a\x20<a\x20href=\"#glos-module-path\">module\x20path</a>\x20after\x0athe\x20<a\x20href=\"#glos-repository-root-path\">repository\x20root\x20path</a>\x20that\x20indicates\x20the\x0asubdirectory\x20where\x20the\x20module\x20is\x20defined.\x20When\x20non-empty,\x20the\x20module\x0asubdirectory\x20is\x20also\x20a\x20prefix\x20for\x20<a\x20href=\"#glos-semantic-version-tag\">semantic\x20version\x0atags</a>.\x20The\x20module\x20subdirectory\x20does\x20not\x20include\x20the\x0a<a\x20href=\"#glos-major-version-suffix\">major\x20version\x20suffix</a>,\x20if\x20there\x20is\x20one,\x20even\x20if\x20the\x0amodule\x20is\x20in\x20a\x20<a\x20href=\"#glos-major-version-subdirectory\">major\x20version\x20subdirectory</a>.\x0aSee\x20<a\x20href=\"#module-path\">Module\x20paths</a>.</p>\x0a<p><a\x20id=\"glos-package\"></a>\x0a<strong>package:</strong>\x20A\x20collection\x20of\x20source\x20files\x20in\x20the\x20same\x20directory\x20that\x20are\x0acompiled\x20together.\x20See\x20the\x20<a\x20href=\"/ref/spec#Packages\">Packages\x20section</a>\x20in\x20the\x20Go\x0aLanguage\x20Specification.</p>\x0a<p><a\x20id=\"glos-package-path\"></a>\x0a<strong>package\x20path:</strong>\x20The\x20path\x20that\x20uniquely\x20identifies\x20a\x20package.\x20A\x20package\x20path\x20is\x0aa\x20<a\x20href=\"#glos-module-path\">module\x20path</a>\x20joined\x20with\x20a\x20subdirectory\x20within\x20the\x20module.\x0aFor\x20example\x20<code>&quot;golang.org/x/net/html&quot;</code>\x20is\x20the\x20package\x20path\x20for\x20the\x20package\x20in\x20the\x0amodule\x20<code>&quot;golang.org/x/net&quot;</code>\x20in\x20the\x20<code>&quot;html&quot;</code>\x20subdirectory.\x20Synonym\x20of\x0a<a\x20href=\"#glos-import-path\">import\x20path</a>.</p>\x0a<p><a\x20id=\"glos-patch-version\"></a>\x0a<strong>patch\x20version:</strong>\x20The\x20third\x20number\x20in\x20a\x20semantic\x20version\x20(<code>3</code>\x20in\x20<code>v1.2.3</code>).\x20In\x0aa\x20release\x20with\x20no\x20changes\x20to\x20the\x20module's\x20public\x20interface,\x20the\x20patch\x20version\x0amust\x20be\x20incremented.</p>\x0a<p><a\x20id=\"glos-pre-release-version\"></a>\x0a<strong>pre-release\x20version:</strong>\x20A\x20version\x20with\x20a\x20dash\x20followed\x20by\x20a\x20series\x20of\x0adot-separated\x20identifiers\x20immediately\x20following\x20the\x20patch\x20version,\x20for\x20example,\x0a<code>v1.2.3-beta4</code>.\x20Pre-release\x20versions\x20are\x20considered\x20unstable\x20and\x20are\x20not\x0aassumed\x20to\x20be\x20compatible\x20with\x20other\x20versions.\x20A\x20pre-release\x20version\x20sorts\x20before\x0athe\x20corresponding\x20release\x20version:\x20<code>v1.2.3-pre</code>\x20comes\x20before\x20<code>v1.2.3</code>.\x20See\x20also\x0a<a\x20href=\"#glos-release-version\">release\x20version</a>.</p>\x0a<p><a\x20id=\"glos-pseudo-version\"></a>\x0a<strong>pseudo-version:</strong>\x20A\x20version\x20that\x20encodes\x20a\x20revision\x20identifier\x20(such\x20as\x20a\x20Git\x0acommit\x20hash)\x20and\x20a\x20timestamp\x20from\x20a\x20version\x20control\x20system.\x20For\x20example,\x0a<code>v0.0.0-20191109021931-daa7c04131f5</code>.\x20Used\x20for\x20<a\x20href=\"#non-module-compat\">compatibility\x20with\x20non-module\x0arepositories</a>\x20and\x20in\x20other\x20situations\x20when\x20a\x20tagged\x0aversion\x20is\x20not\x20available.</p>\x0a<p><a\x20id=\"glos-release-version\"></a>\x0a<strong>release\x20version:</strong>\x20A\x20version\x20without\x20a\x20pre-release\x20suffix.\x20For\x20example,\x0a<code>v1.2.3</code>,\x20not\x20<code>v1.2.3-pre</code>.\x20See\x20also\x20<a\x20href=\"#glos-pre-release-version\">pre-release\x0aversion</a>.</p>\x0a<p><a\x20id=\"glos-repository-root-path\"></a>\x0a<strong>repository\x20root\x20path:</strong>\x20The\x20portion\x20of\x20a\x20<a\x20href=\"#glos-module-path\">module\x20path</a>\x20that\x0acorresponds\x20to\x20a\x20version\x20control\x20repository's\x20root\x20directory.\x20See\x20<a\x20href=\"#module-path\">Module\x0apaths</a>.</p>\x0a<p><a\x20id=\"glos-semantic-version-tag\"></a>\x0a<strong>semantic\x20version\x20tag:</strong>\x20A\x20tag\x20in\x20a\x20version\x20control\x20repository\x20that\x20maps\x20a\x0a<a\x20href=\"#glos-version\">version</a>\x20to\x20a\x20specific\x20revision.\x20See\x20<a\x20href=\"#vcs-version\">Mapping\x20versions\x20to\x0acommits</a>.</p>\x0a<p><a\x20id=\"glos-version\"></a>\x0a<strong>version:</strong>\x20An\x20identifier\x20for\x20an\x20immutable\x20snapshot\x20of\x20a\x20module,\x20written\x20as\x20the\x0aletter\x20<code>v</code>\x20followed\x20by\x20a\x20semantic\x20version.\x20See\x20the\x20section\x20on\x0a<a\x20href=\"#versions\">Versions</a>.</p>\x0a",
+	"doc/mod.html": "<!--{\x0a\x20\x20\"Title\":\x20\"Go\x20Modules\x20Reference\",\x0a\x20\x20\"Subtitle\":\x20\"Version\x20of\x20Feb\x205,\x202019\",\x0a\x20\x20\"Path\":\x20\"/ref/mod\"\x0a}-->\x0a<!--\x20TODO(jayconrod):\x20use\x20<dfn>\x20tags\x20where\x20meaningful.\x0aCurrently,\x20*term*\x20is\x20used\x20instead,\x20which\x20renders\x20to\x20<em>term</em>.\x20-->\x0a<h2\x20id=\"introduction\">Introduction</h2>\x0a<h2\x20id=\"modules-overview\">Modules,\x20packages,\x20and\x20versions</h2>\x0a<p>A\x20<a\x20href=\"#glos-module\"><em>module</em></a>\x20is\x20a\x20collection\x20of\x20packages\x20that\x20are\x20released,\x0aversioned,\x20and\x20distributed\x20together.\x20A\x20module\x20is\x20identified\x20by\x20a\x20<a\x20href=\"#glos-module-path\"><em>module\x0apath</em></a>,\x20which\x20is\x20declared\x20in\x20a\x20<a\x20href=\"#go.mod-files\"><code>go.mod</code>\x0afile</a>,\x20together\x20with\x20information\x20about\x20the\x20module's\x0adependencies.\x20The\x20<a\x20href=\"#glos-module-root-directory\"><em>module\x20root\x20directory</em></a>\x20is\x20the\x0adirectory\x20that\x20contains\x20the\x20<code>go.mod</code>\x20file.\x20The\x20<a\x20href=\"#glos-main-module\"><em>main\x0amodule</em></a>\x20is\x20the\x20module\x20containing\x20the\x20directory\x20where\x20the\x0a<code>go</code>\x20command\x20is\x20invoked.</p>\x0a<p>Each\x20<a\x20href=\"#glos-package\"><em>package</em></a>\x20within\x20a\x20module\x20is\x20a\x20collection\x20of\x20source\x20files\x0ain\x20the\x20same\x20directory\x20that\x20are\x20compiled\x20together.\x20A\x20<a\x20href=\"#glos-package-path\"><em>package\x0apath</em></a>\x20is\x20the\x20module\x20path\x20joined\x20with\x20the\x20subdirectory\x0acontaining\x20the\x20package\x20(relative\x20to\x20the\x20module\x20root).\x20For\x20example,\x20the\x20module\x0a<code>&quot;golang.org/x/net&quot;</code>\x20contains\x20a\x20package\x20in\x20the\x20directory\x20<code>&quot;html&quot;</code>.\x20That\x0apackage's\x20path\x20is\x20<code>&quot;golang.org/x/net/html&quot;</code>.</p>\x0a<h3\x20id=\"module-path\">Module\x20paths</h3>\x0a<p>A\x20<a\x20href=\"#glos-module-path\"><em>module\x20path</em></a>\x20is\x20the\x20canonical\x20name\x20for\x20a\x20module,\x0adeclared\x20with\x20the\x20<a\x20href=\"#go.mod-module\"><code>module</code>\x20directive</a>\x20in\x20the\x20module's\x0a<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20file</a>.\x20A\x20module's\x20path\x20is\x20the\x20prefix\x20for\x20package\x0apaths\x20within\x20the\x20module.</p>\x0a<p>A\x20module\x20path\x20should\x20describe\x20both\x20what\x20the\x20module\x20does\x20and\x20where\x20to\x20find\x20it.\x0aTypically,\x20a\x20module\x20path\x20consists\x20of\x20a\x20repository\x20root\x20path,\x20a\x20directory\x20within\x0athe\x20repository\x20(usually\x20empty),\x20and\x20a\x20major\x20version\x20suffix\x20(only\x20for\x20major\x0aversion\x202\x20or\x20higher).</p>\x0a<ul>\x0a<li>The\x20<dfn>repository\x20root\x20path</dfn>\x20is\x20the\x20portion\x20of\x20the\x20module\x20path\x20that\x0acorresponds\x20to\x20the\x20root\x20directory\x20of\x20the\x20version\x20control\x20repository\x20where\x20the\x0amodule\x20is\x20developed.\x20Most\x20modules\x20are\x20defined\x20in\x20their\x20repository's\x20root\x0adirectory,\x20so\x20this\x20is\x20usually\x20the\x20entire\x20path.\x20For\x20example,\x0a<code>golang.org/x/net</code>\x20is\x20the\x20repository\x20root\x20path\x20for\x20the\x20module\x20of\x20the\x20same\x0aname.\x20See\x20<a\x20href=\"#vcs-find\">Finding\x20a\x20repository\x20for\x20a\x20module\x20path</a>\x20for\x20information\x0aon\x20how\x20the\x20<code>go</code>\x20command\x20locates\x20a\x20repository\x20using\x20HTTP\x20requests\x20derived\x0afrom\x20a\x20module\x20path.</li>\x0a<li>If\x20the\x20module\x20is\x20not\x20defined\x20in\x20the\x20repository's\x20root\x20directory,\x20the\x0a<dfn>module\x20subdirectory</dfn>\x20is\x20the\x20part\x20of\x20the\x20module\x20path\x20that\x20names\x20the\x0adirectory,\x20not\x20including\x20the\x20major\x20version\x20suffix.\x20This\x20also\x20serves\x20as\x20a\x0aprefix\x20for\x20semantic\x20version\x20tags.\x20For\x20example,\x20the\x20module\x0a<code>golang.org/x/tools/gopls</code>\x20is\x20in\x20the\x20<code>gopls</code>\x20subdirectory\x20of\x20the\x20repository\x0awith\x20root\x20path\x20<code>golang.org/x/tools</code>,\x20so\x20it\x20has\x20the\x20module\x20subdirectory\x0a<code>gopls</code>.\x20See\x20<a\x20href=\"#vcs-version\">Mapping\x20versions\x20to\x20commits</a>\x20and\x20<a\x20href=\"#vcs-dir\">Module\x0adirectories\x20within\x20a\x20repository</a>.</li>\x0a<li>If\x20the\x20module\x20is\x20released\x20at\x20major\x20version\x202\x20or\x20higher,\x20the\x20module\x20path\x20must\x0aend\x20with\x20a\x20<a\x20href=\"#major-version-suffixes\"><em>major\x20version\x20suffix</em></a>\x20like\x0a<code>/v2</code>.\x20This\x20may\x20or\x20may\x20not\x20be\x20part\x20of\x20the\x20subdirectory\x20name.\x20For\x20example,\x20the\x0amodule\x20with\x20path\x20<code>golang.org/x/repo/sub/v2</code>\x20could\x20be\x20in\x20the\x20<code>/sub</code>\x20or\x0a<code>/sub/v2</code>\x20subdirectory\x20of\x20the\x20repository\x20<code>golang.org/x/repo</code>.</li>\x0a</ul>\x0a<p>If\x20a\x20module\x20might\x20be\x20depended\x20on\x20by\x20other\x20modules,\x20these\x20rules\x20must\x20be\x20followed\x0aso\x20that\x20the\x20<code>go</code>\x20command\x20can\x20find\x20and\x20download\x20the\x20module.\x20There\x20are\x20also\x0aseveral\x20<a\x20href=\"#go.mod-ident\">lexical\x20restrictions</a>\x20on\x20characters\x20allowed\x20in\x0amodule\x20paths.</p>\x0a<h3\x20id=\"versions\">Versions</h3>\x0a<p>A\x20<a\x20href=\"#glos-version\"><em>version</em></a>\x20identifies\x20an\x20immutable\x20snapshot\x20of\x20a\x20module,\x20which\x0amay\x20be\x20either\x20a\x20<a\x20href=\"#glos-release-version\">release</a>\x20or\x20a\x0a<a\x20href=\"#glos-pre-release-version\">pre-release</a>.\x20Each\x20version\x20starts\x20with\x20the\x20letter\x0a<code>v</code>,\x20followed\x20by\x20a\x20semantic\x20version.\x20See\x20<a\x20href=\"https://semver.org/spec/v2.0.0.html\">Semantic\x20Versioning\x0a2.0.0</a>\x20for\x20details\x20on\x20how\x20versions\x20are\x0aformatted,\x20interpreted,\x20and\x20compared.</p>\x0a<p>To\x20summarize,\x20a\x20semantic\x20version\x20consists\x20of\x20three\x20non-negative\x20integers\x20(the\x0amajor,\x20minor,\x20and\x20patch\x20versions,\x20from\x20left\x20to\x20right)\x20separated\x20by\x20dots.\x20The\x0apatch\x20version\x20may\x20be\x20followed\x20by\x20an\x20optional\x20pre-release\x20string\x20starting\x20with\x20a\x0ahyphen.\x20The\x20pre-release\x20string\x20or\x20patch\x20version\x20may\x20be\x20followed\x20by\x20a\x20build\x0ametadata\x20string\x20starting\x20with\x20a\x20plus.\x20For\x20example,\x20<code>v0.0.0</code>,\x20<code>v1.12.134</code>,\x0a<code>v8.0.5-pre</code>,\x20and\x20<code>v2.0.9+meta</code>\x20are\x20valid\x20versions.</p>\x0a<p>Each\x20part\x20of\x20a\x20version\x20indicates\x20whether\x20the\x20version\x20is\x20stable\x20and\x20whether\x20it\x20is\x0acompatible\x20with\x20previous\x20versions.</p>\x0a<ul>\x0a<li>The\x20<a\x20href=\"#glos-major-version\">major\x20version</a>\x20must\x20be\x20incremented\x20and\x20the\x20minor\x0aand\x20patch\x20versions\x20must\x20be\x20set\x20to\x20zero\x20after\x20a\x20backwards\x20incompatible\x20change\x0ais\x20made\x20to\x20the\x20module's\x20public\x20interface\x20or\x20documented\x20functionality,\x20for\x0aexample,\x20after\x20a\x20package\x20is\x20removed.</li>\x0a<li>The\x20<a\x20href=\"#glos-minor-version\">minor\x20version</a>\x20must\x20be\x20incremented\x20and\x20the\x20patch\x0aversion\x20set\x20to\x20zero\x20after\x20a\x20backwards\x20compatible\x20change,\x20for\x20example,\x20after\x20a\x0anew\x20function\x20is\x20added.</li>\x0a<li>The\x20<a\x20href=\"#glos-patch-version\">patch\x20version</a>\x20must\x20be\x20incremented\x20after\x20a\x20change\x0athat\x20does\x20not\x20affect\x20the\x20module's\x20public\x20interface,\x20such\x20as\x20a\x20bug\x20fix\x20or\x0aoptimization.</li>\x0a<li>The\x20pre-release\x20suffix\x20indicates\x20a\x20version\x20is\x20a\x0a<a\x20href=\"#glos-pre-release-version\">pre-release</a>.\x20Pre-release\x20versions\x20sort\x20before\x0athe\x20corresponding\x20release\x20versions.\x20For\x20example,\x20<code>v1.2.3-pre</code>\x20comes\x20before\x0a<code>v1.2.3</code>.</li>\x0a<li>The\x20build\x20metadata\x20suffix\x20is\x20ignored\x20for\x20the\x20purpose\x20of\x20comparing\x20versions.\x0aTags\x20with\x20build\x20metadata\x20are\x20ignored\x20in\x20version\x20control\x20repositories,\x20but\x0abuild\x20metadata\x20is\x20preserved\x20in\x20versions\x20specified\x20in\x20<code>go.mod</code>\x20files.\x20The\x0asuffix\x20<code>+incompatible</code>\x20denotes\x20a\x20version\x20released\x20before\x20migrating\x20to\x20modules\x0aversion\x20major\x20version\x202\x20or\x20later\x20(see\x20<a\x20href=\"#non-module-compat\">Compatibility\x20with\x20non-module\x0arepositories</a>.</li>\x0a</ul>\x0a<p>A\x20version\x20is\x20considered\x20unstable\x20if\x20its\x20major\x20version\x20is\x200\x20or\x20it\x20has\x20a\x0apre-release\x20suffix.\x20Unstable\x20versions\x20are\x20not\x20subject\x20to\x20compatibility\x0arequirements.\x20For\x20example,\x20<code>v0.2.0</code>\x20may\x20not\x20be\x20compatible\x20with\x20<code>v0.1.0</code>,\x20and\x0a<code>v1.5.0-beta</code>\x20may\x20not\x20be\x20compatible\x20with\x20<code>v1.5.0</code>.</p>\x0a<p>Go\x20may\x20access\x20modules\x20in\x20version\x20control\x20systems\x20using\x20tags,\x20branches,\x20or\x0arevisions\x20that\x20don't\x20follow\x20these\x20conventions.\x20However,\x20within\x20the\x20main\x20module,\x0athe\x20<code>go</code>\x20command\x20will\x20automatically\x20convert\x20revision\x20names\x20that\x20don't\x20follow\x0athis\x20standard\x20into\x20canonical\x20versions.\x20The\x20<code>go</code>\x20command\x20will\x20also\x20remove\x20build\x0ametadata\x20suffixes\x20(except\x20for\x20<code>+incompatible</code>)\x20as\x20part\x20of\x20this\x20process.\x20This\x20may\x0aresult\x20in\x20a\x20<a\x20href=\"#glos-pseudo-version\"><em>pseudo-version</em></a>,\x20a\x20pre-release\x20version\x20that\x0aencodes\x20a\x20revision\x20identifier\x20(such\x20as\x20a\x20Git\x20commit\x20hash)\x20and\x20a\x20timestamp\x20from\x20a\x0aversion\x20control\x20system.\x20For\x20example,\x20the\x20command\x20<code>go\x20get\x20-d\x20golang.org/x/net@daa7c041</code>\x20will\x20convert\x20the\x20commit\x20hash\x20<code>daa7c041</code>\x20into\x20the\x0apseudo-version\x20<code>v0.0.0-20191109021931-daa7c04131f5</code>.\x20Canonical\x20versions\x20are\x0arequired\x20outside\x20the\x20main\x20module,\x20and\x20the\x20<code>go</code>\x20command\x20will\x20report\x20an\x20error\x20if\x20a\x0anon-canonical\x20version\x20like\x20<code>master</code>\x20appears\x20in\x20a\x20<code>go.mod</code>\x20file.</p>\x0a<h3\x20id=\"pseudo-versions\">Pseudo-versions</h3>\x0a<p>A\x20<dfn>pseudo-version</dfn>\x20is\x20a\x20specially\x20formatted\x0a<a\x20href=\"#glos-pre-release-version\">pre-release</a>\x20<a\x20href=\"#glos-version\">version</a>\x20that\x20encodes\x0ainformation\x20about\x20a\x20specific\x20revision\x20in\x20a\x20version\x20control\x20repository.\x20For\x0aexample,\x20<code>v0.0.0-20191109021931-daa7c04131f5</code>\x20is\x20a\x20pseudo-version.</p>\x0a<p>Pseudo-versions\x20may\x20refer\x20to\x20revisions\x20for\x20which\x20no\x20<a\x20href=\"#glos-semantic-version-tag\">semantic\x20version\x0atags</a>\x20are\x20available.\x20They\x20may\x20be\x20used\x20to\x20test\x0acommits\x20before\x20creating\x20version\x20tags,\x20for\x20example,\x20on\x20a\x20development\x20branch.</p>\x0a<p>Each\x20pseudo-version\x20has\x20three\x20parts:</p>\x0a<ul>\x0a<li>A\x20base\x20version\x20prefix\x20(<code>vX.0.0</code>\x20or\x20<code>vX.Y.Z-0</code>),\x20which\x20is\x20either\x20derived\x20from\x20a\x0asemantic\x20version\x20tag\x20that\x20precedes\x20the\x20revision\x20or\x20<code>vX.0.0</code>\x20if\x20there\x20is\x20no\x0asuch\x20tag.</li>\x0a<li>A\x20timestamp\x20(<code>yymmddhhmmss</code>),\x20which\x20is\x20the\x20UTC\x20time\x20the\x20revision\x20was\x20created.\x0aIn\x20Git,\x20this\x20is\x20the\x20commit\x20time,\x20not\x20the\x20author\x20time.</li>\x0a<li>A\x20revision\x20identifier\x20(<code>abcdefabcdef</code>),\x20which\x20is\x20a\x2012-character\x20prefix\x20of\x20the\x0acommit\x20hash,\x20or\x20in\x20Subversion,\x20a\x20zero-padded\x20revision\x20number.</li>\x0a</ul>\x0a<p>Each\x20pseudo-version\x20may\x20be\x20in\x20one\x20of\x20three\x20forms,\x20depending\x20on\x20the\x20base\x20version.\x0aThese\x20forms\x20ensure\x20that\x20a\x20pseudo-version\x20compares\x20higher\x20than\x20its\x20base\x20version,\x0abut\x20lower\x20than\x20the\x20next\x20tagged\x20version.</p>\x0a<ul>\x0a<li><code>vX.0.0-yyyymmddhhmmss-abcdefabcdef</code>\x20is\x20used\x20when\x20there\x20is\x20no\x20known\x20base\x0aversion.\x20As\x20with\x20all\x20versions,\x20the\x20major\x20version\x20<code>X</code>\x20must\x20match\x20the\x20module's\x0a<a\x20href=\"#glos-major-version-suffix\">major\x20version\x20suffix</a>.</li>\x0a<li><code>vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef</code>\x20is\x20used\x20when\x20the\x20base\x20version\x20is\x0aa\x20pre-release\x20version\x20like\x20<code>vX.Y.Z-pre</code>.</li>\x0a<li><code>vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef</code>\x20is\x20used\x20when\x20the\x20base\x20version\x20is\x0aa\x20release\x20version\x20like\x20<code>vX.Y.Z</code>.\x20For\x20example,\x20if\x20the\x20base\x20version\x20is\x0a<code>v1.2.3</code>,\x20a\x20pseudo-version\x20might\x20be\x20<code>v1.2.4-0.20191109021931-daa7c04131f5</code>.</li>\x0a</ul>\x0a<p>More\x20than\x20one\x20pseudo-version\x20may\x20refer\x20to\x20the\x20same\x20commit\x20by\x20using\x20different\x0abase\x20versions.\x20This\x20happens\x20naturally\x20when\x20a\x20lower\x20version\x20is\x20tagged\x20after\x20a\x0apseudo-version\x20is\x20written.</p>\x0a<p>These\x20forms\x20give\x20pseudo-versions\x20two\x20useful\x20properties:</p>\x0a<ul>\x0a<li>Pseudo-versions\x20with\x20known\x20base\x20versions\x20sort\x20higher\x20than\x20those\x20versions\x20but\x0alower\x20than\x20other\x20pre-release\x20for\x20later\x20versions.</li>\x0a<li>Pseudo-versions\x20with\x20the\x20same\x20base\x20version\x20prefix\x20sort\x20chronologically.</li>\x0a</ul>\x0a<p>The\x20<code>go</code>\x20command\x20performs\x20several\x20checks\x20to\x20ensure\x20that\x20module\x20authors\x20have\x0acontrol\x20over\x20how\x20pseudo-versions\x20are\x20compared\x20with\x20other\x20versions\x20and\x20that\x0apseudo-versions\x20refer\x20to\x20revisions\x20that\x20are\x20actually\x20part\x20of\x20a\x20module's\x0acommit\x20history.</p>\x0a<ul>\x0a<li>If\x20a\x20base\x20version\x20is\x20specified,\x20there\x20must\x20be\x20a\x20corresponding\x20semantic\x20version\x0atag\x20that\x20is\x20an\x20ancestor\x20of\x20the\x20revision\x20described\x20by\x20the\x20pseudo-version.\x20This\x0aprevents\x20developers\x20from\x20bypassing\x20<a\x20href=\"#glos-minimal-version-selection\">minimal\x20version\x0aselection</a>\x20using\x20a\x20pseudo-version\x20that\x0acompares\x20higher\x20than\x20all\x20tagged\x20versions\x20like\x0a<code>v1.999.999-99999999999999-daa7c04131f5</code>.</li>\x0a<li>The\x20timestamp\x20must\x20match\x20the\x20revision's\x20timestamp.\x20This\x20prevents\x20attackers\x0afrom\x20flooding\x20<a\x20href=\"#glos-module-proxy\">module\x20proxies</a>\x20with\x20an\x20unbounded\x20number\x0aof\x20otherwise\x20identical\x20pseudo-versions.\x20This\x20also\x20prevents\x20module\x20consumers\x0afrom\x20changing\x20the\x20relative\x20ordering\x20of\x20versions.</li>\x0a<li>The\x20revision\x20must\x20be\x20an\x20ancestor\x20of\x20one\x20of\x20the\x20module\x20repository's\x20branches\x20or\x0atags.\x20This\x20prevents\x20attackers\x20from\x20referring\x20to\x20unapproved\x20changes\x20or\x20pull\x0arequests.</li>\x0a</ul>\x0a<p>Pseudo-versions\x20never\x20need\x20to\x20be\x20typed\x20by\x20hand.\x20Many\x20commands\x20accept\x0aa\x20commit\x20hash\x20or\x20a\x20branch\x20name\x20and\x20will\x20translate\x20it\x20into\x20a\x20pseudo-version\x0a(or\x20tagged\x20version\x20if\x20available)\x20automatically.\x20For\x20example:</p>\x0a<pre><code>go\x20get\x20-d\x20example.com/mod@master\x0ago\x20list\x20-m\x20-json\x20example.com/mod@abcd1234\x0a</code></pre>\x0a<h3\x20id=\"major-version-suffixes\">Major\x20version\x20suffixes</h3>\x0a<p>Starting\x20with\x20major\x20version\x202,\x20module\x20paths\x20must\x20have\x20a\x20<a\x20href=\"#glos-major-version-suffix\"><em>major\x20version\x0asuffix</em></a>\x20like\x20<code>/v2</code>\x20that\x20matches\x20the\x20major\x0aversion.\x20For\x20example,\x20if\x20a\x20module\x20has\x20the\x20path\x20<code>example.com/mod</code>\x20at\x20<code>v1.0.0</code>,\x20it\x0amust\x20have\x20the\x20path\x20<code>example.com/mod/v2</code>\x20at\x20version\x20<code>v2.0.0</code>.</p>\x0a<p>Major\x20version\x20suffixes\x20implement\x20the\x20<a\x20href=\"https://research.swtch.com/vgo-import\"><em>import\x20compatibility\x0arule</em></a>:</p>\x0a<blockquote>\x0a<p>If\x20an\x20old\x20package\x20and\x20a\x20new\x20package\x20have\x20the\x20same\x20import\x20path,\x0athe\x20new\x20package\x20must\x20be\x20backwards\x20compatible\x20with\x20the\x20old\x20package.</p>\x0a</blockquote>\x0a<p>By\x20definition,\x20packages\x20in\x20a\x20new\x20major\x20version\x20of\x20a\x20module\x20are\x20not\x20backwards\x0acompatible\x20with\x20the\x20corresponding\x20packages\x20in\x20the\x20previous\x20major\x20version.\x0aConsequently,\x20starting\x20with\x20<code>v2</code>,\x20packages\x20need\x20new\x20import\x20paths.\x20This\x20is\x0aaccomplished\x20by\x20adding\x20a\x20major\x20version\x20suffix\x20to\x20the\x20module\x20path.\x20Since\x20the\x0amodule\x20path\x20is\x20a\x20prefix\x20of\x20the\x20import\x20path\x20for\x20each\x20package\x20within\x20the\x20module,\x0aadding\x20the\x20major\x20version\x20suffix\x20to\x20the\x20module\x20path\x20provides\x20a\x20distinct\x20import\x0apath\x20for\x20each\x20incompatible\x20version.</p>\x0a<p>Major\x20version\x20suffixes\x20are\x20not\x20allowed\x20at\x20major\x20versions\x20<code>v0</code>\x20or\x20<code>v1</code>.\x20There\x20is\x0ano\x20need\x20to\x20change\x20the\x20module\x20path\x20between\x20<code>v0</code>\x20and\x20<code>v1</code>\x20because\x20<code>v0</code>\x20versions\x0aare\x20unstable\x20and\x20have\x20no\x20compatibility\x20guarantee.\x20Additionally,\x20for\x20most\x0amodules,\x20<code>v1</code>\x20is\x20backwards\x20compatible\x20with\x20the\x20last\x20<code>v0</code>\x20version;\x20a\x20<code>v1</code>\x20version\x0aacts\x20as\x20a\x20commitment\x20to\x20compatibility,\x20rather\x20than\x20an\x20indication\x20of\x0aincompatible\x20changes\x20compared\x20with\x20<code>v0</code>.</p>\x0a<p>As\x20a\x20special\x20case,\x20modules\x20paths\x20starting\x20with\x20<code>gopkg.in/</code>\x20must\x20always\x20have\x20a\x0amajor\x20version\x20suffix,\x20even\x20at\x20<code>v0</code>\x20and\x20<code>v1</code>.\x20The\x20suffix\x20must\x20start\x20with\x20a\x20dot\x0arather\x20than\x20a\x20slash\x20(for\x20example,\x20<code>gopkg.in/yaml.v2</code>).</p>\x0a<p>Major\x20version\x20suffixes\x20let\x20multiple\x20major\x20versions\x20of\x20a\x20module\x20coexist\x20in\x20the\x0asame\x20build.\x20This\x20may\x20be\x20necessary\x20due\x20to\x20a\x20<a\x20href=\"https://research.swtch.com/vgo-import#dependency_story\">diamond\x20dependency\x0aproblem</a>.\x20Ordinarily,\x20if\x0aa\x20module\x20is\x20required\x20at\x20two\x20different\x20versions\x20by\x20transitive\x20dependencies,\x20the\x0ahigher\x20version\x20will\x20be\x20used.\x20However,\x20if\x20the\x20two\x20versions\x20are\x20incompatible,\x0aneither\x20version\x20will\x20satisfy\x20all\x20clients.\x20Since\x20incompatible\x20versions\x20must\x20have\x0adifferent\x20major\x20version\x20numbers,\x20they\x20must\x20also\x20have\x20different\x20module\x20paths\x20due\x0ato\x20major\x20version\x20suffixes.\x20This\x20resolves\x20the\x20conflict:\x20modules\x20with\x20distinct\x0asuffixes\x20are\x20treated\x20as\x20separate\x20modules,\x20and\x20their\x20packages\xe2\x80\x94even\x20packages\x20in\x0asame\x20subdirectory\x20relative\x20to\x20their\x20module\x20roots\xe2\x80\x94are\x20distinct.</p>\x0a<p>Many\x20Go\x20projects\x20released\x20versions\x20at\x20<code>v2</code>\x20or\x20higher\x20without\x20using\x20a\x20major\x0aversion\x20suffix\x20before\x20migrating\x20to\x20modules\x20(perhaps\x20before\x20modules\x20were\x20even\x0aintroduced).\x20These\x20versions\x20are\x20annotated\x20with\x20a\x20<code>+incompatible</code>\x20build\x20tag\x20(for\x0aexample,\x20<code>v2.0.0+incompatible</code>).\x20See\x20<a\x20href=\"#non-module-compat\">Compatibility\x20with\x20non-module\x0arepositories</a>\x20for\x20more\x20information.</p>\x0a<h3\x20id=\"resolve-pkg-mod\">Resolving\x20a\x20package\x20to\x20a\x20module</h3>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20loads\x20a\x20package\x20using\x20a\x20<a\x20href=\"#glos-package-path\">package\x0apath</a>,\x20it\x20needs\x20to\x20determine\x20which\x20module\x20provides\x20the\x0apackage.</p>\x0a<p>The\x20<code>go</code>\x20command\x20starts\x20by\x20searching\x20the\x20<a\x20href=\"#glos-build-list\">build\x20list</a>\x20for\x0amodules\x20with\x20paths\x20that\x20are\x20prefixes\x20of\x20the\x20package\x20path.\x20For\x20example,\x20if\x20the\x0apackage\x20<code>example.com/a/b</code>\x20is\x20imported,\x20and\x20the\x20module\x20<code>example.com/a</code>\x20is\x20in\x20the\x0abuild\x20list,\x20the\x20<code>go</code>\x20command\x20will\x20check\x20whether\x20<code>example.com/a</code>\x20contains\x20the\x0apackage,\x20in\x20the\x20directory\x20<code>b</code>.\x20At\x20least\x20one\x20file\x20with\x20the\x20<code>.go</code>\x20extension\x20must\x0abe\x20present\x20in\x20a\x20directory\x20for\x20it\x20to\x20be\x20considered\x20a\x20package.\x20<a\x20href=\"/pkg/go/build/#hdr-Build_Constraints\">Build\x0aconstraints</a>\x20are\x20not\x20applied\x20for\x20this\x0apurpose.\x20If\x20exactly\x20one\x20module\x20in\x20the\x20build\x20list\x20provides\x20the\x20package,\x20that\x0amodule\x20is\x20used.\x20If\x20two\x20or\x20more\x20modules\x20provide\x20the\x20package,\x20an\x20error\x20is\x0areported.\x20If\x20no\x20modules\x20provide\x20the\x20package,\x20the\x20<code>go</code>\x20command\x20will\x20attempt\x20to\x0afind\x20a\x20new\x20module\x20(unless\x20the\x20flags\x20<code>-mod=readonly</code>\x20or\x20<code>-mod=vendor</code>\x20are\x20used,\x0ain\x20which\x20case,\x20an\x20error\x20is\x20reported).</p>\x0a<!--\x20NOTE(golang.org/issue/27899):\x20the\x20go\x20command\x20reports\x20an\x20error\x20when\x20two\x0aor\x20more\x20modules\x20provide\x20a\x20package\x20with\x20the\x20same\x20path\x20as\x20above.\x20In\x20the\x20future,\x0awe\x20may\x20try\x20to\x20upgrade\x20one\x20(or\x20all)\x20of\x20the\x20colliding\x20modules.\x0a-->\x0a<p>When\x20the\x20<code>go</code>\x20command\x20looks\x20up\x20a\x20new\x20module\x20for\x20a\x20package\x20path,\x20it\x20checks\x20the\x0a<code>GOPROXY</code>\x20environment\x20variable,\x20which\x20is\x20a\x20comma-separated\x20list\x20of\x20proxy\x20URLs\x20or\x0athe\x20keywords\x20<code>direct</code>\x20or\x20<code>off</code>.\x20A\x20proxy\x20URL\x20indicates\x20the\x20<code>go</code>\x20command\x20should\x0acontact\x20a\x20<a\x20href=\"#glos-module-proxy\">module\x20proxy</a>\x20using\x20the\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x0aprotocol</a>.\x20<code>direct</code>\x20indicates\x20that\x20the\x20<code>go</code>\x20command\x20should\x0a<a\x20href=\"#vcs\">communicate\x20with\x20a\x20version\x20control\x20system</a>.\x20<code>off</code>\x20indicates\x20that\x20no\x0acommunication\x20should\x20be\x20attempted.\x20The\x20<code>GOPRIVATE</code>\x20and\x20<code>GONOPROXY</code>\x20<a\x20href=\"#environment-variables\">environment\x0avariables</a>\x20can\x20also\x20be\x20used\x20to\x20control\x20this\x20behavior.</p>\x0a<p>For\x20each\x20entry\x20in\x20the\x20<code>GOPROXY</code>\x20list,\x20the\x20<code>go</code>\x20command\x20requests\x20the\x20latest\x0aversion\x20of\x20each\x20module\x20path\x20that\x20might\x20provide\x20the\x20package\x20(that\x20is,\x20each\x20prefix\x0aof\x20the\x20package\x20path).\x20For\x20each\x20successfully\x20requested\x20module\x20path,\x20the\x20<code>go</code>\x0acommand\x20will\x20download\x20the\x20module\x20at\x20the\x20latest\x20version\x20and\x20check\x20whether\x20the\x0amodule\x20contains\x20the\x20requested\x20package.\x20If\x20one\x20or\x20more\x20modules\x20contain\x20the\x0arequested\x20package,\x20the\x20module\x20with\x20the\x20longest\x20path\x20is\x20used.\x20If\x20one\x20or\x20more\x0amodules\x20are\x20found\x20but\x20none\x20contain\x20the\x20requested\x20package,\x20an\x20error\x20is\x0areported.\x20If\x20no\x20modules\x20are\x20found,\x20the\x20<code>go</code>\x20command\x20tries\x20the\x20next\x20entry\x20in\x20the\x0a<code>GOPROXY</code>\x20list.\x20If\x20no\x20entries\x20are\x20left,\x20an\x20error\x20is\x20reported.</p>\x0a<p>For\x20example,\x20suppose\x20the\x20<code>go</code>\x20command\x20is\x20looking\x20for\x20a\x20module\x20that\x20provides\x20the\x0apackage\x20<code>golang.org/x/net/html</code>,\x20and\x20<code>GOPROXY</code>\x20is\x20set\x20to\x0a<code>https://corp.example.com,https://proxy.golang.org</code>.\x20The\x20<code>go</code>\x20command\x20may\x20make\x0athe\x20following\x20requests:</p>\x0a<ul>\x0a<li>To\x20<code>https://corp.example.com/</code>\x20(in\x20parallel):\x0a<ul>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x/net/html</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x/net</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org</code></li>\x0a</ul>\x0a</li>\x0a<li>To\x20<code>https://proxy.golang.org/</code>,\x20if\x20all\x20requests\x20to\x20<code>https://corp.example.com/</code>\x0ahave\x20failed\x20with\x20404\x20or\x20410:\x0a<ul>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x/net/html</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x/net</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org/x</code></li>\x0a<li>Request\x20for\x20latest\x20version\x20of\x20<code>golang.org</code></li>\x0a</ul>\x0a</li>\x0a</ul>\x0a<p>After\x20a\x20suitable\x20module\x20has\x20been\x20found,\x20the\x20<code>go</code>\x20command\x20will\x20add\x20a\x20new\x0a<a\x20href=\"#go.mod-require\">requirement</a>\x20with\x20the\x20new\x20module's\x20path\x20and\x20version\x20to\x20the\x0amain\x20module's\x20<code>go.mod</code>\x20file.\x20This\x20ensures\x20that\x20when\x20the\x20same\x20package\x20is\x20loaded\x0ain\x20the\x20future,\x20the\x20same\x20module\x20will\x20be\x20used\x20at\x20the\x20same\x20version.\x20If\x20the\x20resolved\x0apackage\x20is\x20not\x20imported\x20by\x20a\x20package\x20in\x20the\x20main\x20module,\x20the\x20new\x20requirement\x0awill\x20have\x20an\x20<code>//\x20indirect</code>\x20comment.</p>\x0a<h2\x20id=\"go\"\x20class=\"mod-files\"><code>go.mod</code>\x20files</h2>\x0a<p>A\x20module\x20is\x20defined\x20by\x20a\x20UTF-8\x20encoded\x20text\x20file\x20named\x20<code>go.mod</code>\x20in\x20its\x20root\x0adirectory.\x20The\x20<code>go.mod</code>\x20file\x20is\x20line-oriented.\x20Each\x20line\x20holds\x20a\x20single\x0adirective,\x20made\x20up\x20of\x20a\x20keyword\x20followed\x20by\x20arguments.\x20For\x20example:</p>\x0a<pre><code>module\x20example.com/my/thing\x0a\x0ago\x201.12\x0a\x0arequire\x20example.com/other/thing\x20v1.0.2\x0arequire\x20example.com/new/thing/v2\x20v2.3.4\x0aexclude\x20example.com/old/thing\x20v1.2.3\x0areplace\x20example.com/bad/thing\x20v1.4.5\x20=&gt;\x20example.com/good/thing\x20v1.4.5\x0a</code></pre>\x0a<p>The\x20leading\x20keyword\x20can\x20be\x20factored\x20out\x20of\x20adjacent\x20lines\x20to\x20create\x20a\x20block,\x0alike\x20in\x20Go\x20imports.</p>\x0a<pre><code>require\x20(\x0a\x20\x20\x20\x20example.com/new/thing/v2\x20v2.3.4\x0a\x20\x20\x20\x20example.com/old/thing\x20v1.2.3\x0a)\x0a</code></pre>\x0a<p>The\x20<code>go.mod</code>\x20file\x20is\x20designed\x20to\x20be\x20human\x20readable\x20and\x20machine\x20writable.\x20The\x0a<code>go</code>\x20command\x20provides\x20several\x20subcommands\x20that\x20change\x20<code>go.mod</code>\x20files.\x20For\x0aexample,\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20can\x20upgrade\x20or\x20downgrade\x20specific\x20dependencies.\x0aCommands\x20that\x20load\x20the\x20module\x20graph\x20will\x20<a\x20href=\"#go.mod-updates\">automatically\x20update</a>\x0a<code>go.mod</code>\x20when\x20needed.\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20edit</code></a>\x20can\x20perform\x20low-level\x20edits.\x0aThe\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/modfile?tab=doc\"><code>golang.org/x/mod/modfile</code></a>\x0apackage\x20can\x20be\x20used\x20by\x20Go\x20programs\x20to\x20make\x20the\x20same\x20changes\x20programmatically.</p>\x0a<h3\x20id=\"go\"\x20class=\"mod-lexical\">Lexical\x20elements</h3>\x0a<p>When\x20a\x20<code>go.mod</code>\x20file\x20is\x20parsed,\x20its\x20content\x20is\x20broken\x20into\x20a\x20sequence\x20of\x20tokens.\x0aThere\x20are\x20several\x20kinds\x20of\x20tokens:\x20whitespace,\x20comments,\x20punctuation,\x0akeywords,\x20identifiers,\x20and\x20strings.</p>\x0a<p><em>White\x20space</em>\x20consists\x20of\x20spaces\x20(U+0020),\x20tabs\x20(U+0009),\x20carriage\x20returns\x0a(U+000D),\x20and\x20newlines\x20(U+000A).\x20White\x20space\x20characters\x20other\x20than\x20newlines\x20have\x0ano\x20effect\x20except\x20to\x20separate\x20tokens\x20that\x20would\x20otherwise\x20be\x20combined.\x20Newlines\x0aare\x20significant\x20tokens.</p>\x0a<p><em>Comments</em>\x20start\x20with\x20<code>//</code>\x20and\x20run\x20to\x20the\x20end\x20of\x20a\x20line.\x20<code>/*\x20*/</code>\x20comments\x20are\x0anot\x20allowed.</p>\x0a<p><em>Punctuation</em>\x20tokens\x20include\x20<code>(</code>,\x20<code>)</code>,\x20and\x20<code>=&gt;</code>.</p>\x0a<p><em>Keywords</em>\x20distinguish\x20different\x20kinds\x20of\x20directives\x20in\x20a\x20<code>go.mod</code>\x20file.\x20Allowed\x0akeywords\x20are\x20<code>module</code>,\x20<code>go</code>,\x20<code>require</code>,\x20<code>replace</code>,\x20and\x20<code>exclude</code>.</p>\x0a<p><em>Identifiers</em>\x20are\x20sequences\x20of\x20non-whitespace\x20characters,\x20such\x20as\x20module\x20paths\x0aor\x20semantic\x20versions.</p>\x0a<p><em>Strings</em>\x20are\x20quoted\x20sequences\x20of\x20characters.\x20There\x20are\x20two\x20kinds\x20of\x20strings:\x0ainterpreted\x20strings\x20beginning\x20and\x20ending\x20with\x20quotation\x20marks\x20(<code>&quot;</code>,\x20U+0022)\x20and\x0araw\x20strings\x20beginning\x20and\x20ending\x20with\x20grave\x20accents\x20(<code>&lt;</code>,\x0aU+0060).\x20Interpreted\x20strings\x20may\x20contain\x20escape\x20sequences\x20consisting\x20of\x20a\x0abackslash\x20(<code>\\</code>,\x20U+005C)\x20followed\x20by\x20another\x20character.\x20An\x20escaped\x20quotation\x0amark\x20(<code>\\&quot;</code>)\x20does\x20not\x20terminate\x20an\x20interpreted\x20string.\x20The\x20unquoted\x20value\x0aof\x20an\x20interpreted\x20string\x20is\x20the\x20sequence\x20of\x20characters\x20between\x20quotation\x0amarks\x20with\x20each\x20escape\x20sequence\x20replaced\x20by\x20the\x20character\x20following\x20the\x0abackslash\x20(for\x20example,\x20<code>\\&quot;</code>\x20is\x20replaced\x20by\x20<code>&quot;</code>,\x20<code>\\n</code>\x20is\x20replaced\x20by\x20<code>n</code>).\x0aIn\x20contrast,\x20the\x20unquoted\x20value\x20of\x20a\x20raw\x20string\x20is\x20simply\x20the\x20sequence\x20of\x0acharacters\x20between\x20grave\x20accents;\x20backslashes\x20have\x20no\x20special\x20meaning\x20within\x0araw\x20strings.</p>\x0a<p>Identifiers\x20and\x20strings\x20are\x20interchangeable\x20in\x20the\x20<code>go.mod</code>\x20grammar.</p>\x0a<h3\x20id=\"go\"\x20class=\"mod-ident\">Module\x20paths\x20and\x20versions</h3>\x0a<p>Most\x20identifiers\x20and\x20strings\x20in\x20a\x20<code>go.mod</code>\x20file\x20are\x20either\x20module\x20paths\x20or\x0aversions.</p>\x0a<p>A\x20module\x20path\x20must\x20satisfy\x20the\x20following\x20requirements:</p>\x0a<ul>\x0a<li>The\x20path\x20must\x20consist\x20of\x20one\x20or\x20more\x20path\x20elements\x20separated\x20by\x20slashes\x0a(<code>/</code>,\x20U+002F).\x20It\x20must\x20not\x20begin\x20or\x20end\x20with\x20a\x20slash.</li>\x0a<li>Each\x20path\x20element\x20is\x20a\x20non-empty\x20string\x20made\x20of\x20up\x20ASCII\x20letters,\x20ASCII\x0adigits,\x20and\x20limited\x20ASCII\x20punctuation\x20(<code>+</code>,\x20<code>-</code>,\x20<code>.</code>,\x20<code>_</code>,\x20and\x20<code>~</code>).</li>\x0a<li>A\x20path\x20element\x20may\x20not\x20begin\x20or\x20end\x20with\x20a\x20dot\x20(<code>.</code>,\x20U+002E).</li>\x0a<li>The\x20element\x20prefix\x20up\x20to\x20the\x20first\x20dot\x20must\x20not\x20be\x20a\x20reserved\x20file\x20name\x20on\x0aWindows,\x20regardless\x20of\x20case\x20(<code>CON</code>,\x20<code>com1</code>,\x20<code>NuL</code>,\x20and\x20so\x20on).</li>\x0a</ul>\x0a<p>If\x20the\x20module\x20path\x20appears\x20in\x20a\x20<code>require</code>\x20directive\x20and\x20is\x20not\x20replaced,\x20or\x0aif\x20the\x20module\x20paths\x20appears\x20on\x20the\x20right\x20side\x20of\x20a\x20<code>replace</code>\x20directive,\x0athe\x20<code>go</code>\x20command\x20may\x20need\x20to\x20download\x20modules\x20with\x20that\x20path,\x20and\x20some\x0aadditional\x20requirements\x20must\x20be\x20satisfied.</p>\x0a<ul>\x0a<li>The\x20leading\x20path\x20element\x20(up\x20to\x20the\x20first\x20slash,\x20if\x20any),\x20by\x20convention\x20a\x0adomain\x20name,\x20must\x20contain\x20only\x20lower-case\x20ASCII\x20letters,\x20ASCII\x20digits,\x20dots\x0a(<code>.</code>,\x20U+002E),\x20and\x20dashes\x20(<code>-</code>,\x20U+002D);\x20it\x20must\x20contain\x20at\x20least\x20one\x20dot\x20and\x0acannot\x20start\x20with\x20a\x20dash.</li>\x0a<li>For\x20a\x20final\x20path\x20element\x20of\x20the\x20form\x20<code>/vN</code>\x20where\x20<code>N</code>\x20looks\x20numeric\x20(ASCII\x0adigits\x20and\x20dots),\x20<code>N</code>\x20must\x20not\x20begin\x20with\x20a\x20leading\x20zero,\x20must\x20not\x20be\x20<code>/v1</code>,\x0aand\x20must\x20not\x20contain\x20any\x20dots.\x0a<ul>\x0a<li>For\x20paths\x20beginning\x20with\x20<code>gopkg.in/</code>,\x20this\x20requirement\x20is\x20replaced\x20by\x20a\x0arequirement\x20that\x20the\x20path\x20follow\x20the\x20<a\x20href=\"https://gopkg.in\">gopkg.in</a>\x20service's\x0aconventions.</li>\x0a</ul>\x0a</li>\x0a</ul>\x0a<p>Versions\x20in\x20<code>go.mod</code>\x20files\x20may\x20be\x20<a\x20href=\"#glos-canonical-version\">canonical</a>\x20or\x0anon-canonical.</p>\x0a<p>A\x20canonical\x20version\x20starts\x20with\x20the\x20letter\x20<code>v</code>,\x20followed\x20by\x20a\x20semantic\x20version\x0afollowing\x20the\x20<a\x20href=\"https://semver.org/spec/v2.0.0.html\">Semantic\x20Versioning\x202.0.0</a>\x0aspecification.\x20See\x20<a\x20href=\"#versions\">Versions</a>\x20for\x20more\x20information.</p>\x0a<p>Most\x20other\x20identifiers\x20and\x20strings\x20may\x20be\x20used\x20as\x20non-canonical\x20versions,\x20though\x0athere\x20are\x20some\x20restrictions\x20to\x20avoid\x20problems\x20with\x20file\x20systems,\x20repositories,\x0aand\x20<a\x20href=\"#glos-module-proxy\">module\x20proxies</a>.\x20Non-canonical\x20versions\x20are\x20only\x0aallowed\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file.\x20The\x20<code>go</code>\x20command\x20will\x20attempt\x20to\x0areplace\x20each\x20non-canonical\x20version\x20with\x20an\x20equivalent\x20canonical\x20version\x20when\x20it\x0aautomatically\x20<a\x20href=\"#go.mod-updates\">updates</a>\x20the\x20<code>go.mod</code>\x20file.</p>\x0a<p>In\x20places\x20where\x20a\x20module\x20path\x20is\x20associated\x20with\x20a\x20verison\x20(as\x20in\x20<code>require</code>,\x0a<code>replace</code>,\x20and\x20<code>exclude</code>\x20directives),\x20the\x20final\x20path\x20element\x20must\x20be\x20consistent\x0awith\x20the\x20version.\x20See\x20<a\x20href=\"#major-version-suffixes\">Major\x20version\x20suffixes</a>.</p>\x0a<h3\x20id=\"go\"\x20class=\"mod-grammar\">Grammar</h3>\x0a<p><code>go.mod</code>\x20syntax\x20is\x20specified\x20below\x20using\x20Extended\x20Backus-Naur\x20Form\x20(EBNF).\x0aSee\x20the\x20<a\x20href=\"/ref/spec#Notation\">Notation\x20section\x20in\x20the\x20Go\x20Language\x20Specificiation</a>\x0afor\x20details\x20on\x20EBNF\x20syntax.</p>\x0a<pre><code>GoMod\x20=\x20{\x20Directive\x20}\x20.\x0aDirective\x20=\x20ModuleDirective\x20|\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20GoDirective\x20|\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20RequireDirective\x20|\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20ExcludeDirective\x20|\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20ReplaceDirective\x20.\x0a</code></pre>\x0a<p>Newlines,\x20identifiers,\x20and\x20strings\x20are\x20denoted\x20with\x20<code>newline</code>,\x20<code>ident</code>,\x20and\x0a<code>string</code>,\x20respectively.</p>\x0a<p>Module\x20paths\x20and\x20versions\x20are\x20denoted\x20with\x20<code>ModulePath</code>\x20and\x20<code>Version</code>.</p>\x0a<pre><code>ModulePath\x20=\x20ident\x20|\x20string\x20.\x20/*\x20see\x20restrictions\x20above\x20*/\x0aVersion\x20=\x20ident\x20|\x20string\x20.\x20\x20\x20\x20/*\x20see\x20restrictions\x20above\x20*/\x0a</code></pre>\x0a<h3\x20id=\"go\"\x20class=\"mod-module\"><code>module</code>\x20directive</h3>\x0a<p>A\x20<code>module</code>\x20directive\x20defines\x20the\x20main\x20module's\x20<a\x20href=\"#glos-module-path\">path</a>.\x20A\x0a<code>go.mod</code>\x20file\x20must\x20contain\x20exactly\x20one\x20<code>module</code>\x20directive.</p>\x0a<pre><code>ModuleDirective\x20=\x20&quot;module&quot;\x20(\x20ModulePath\x20|\x20&quot;(&quot;\x20newline\x20ModulePath\x20newline\x20&quot;)&quot;\x20newline\x20.\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>module\x20golang.org/x/net\x0a</code></pre>\x0a<h3\x20id=\"go\"\x20class=\"mod-go\"><code>go</code>\x20directive</h3>\x0a<p>A\x20<code>go</code>\x20directive\x20sets\x20the\x20expected\x20language\x20version\x20for\x20the\x20module.\x20The\x0aversion\x20must\x20be\x20a\x20valid\x20Go\x20release\x20version:\x20a\x20positive\x20integer\x20followed\x20by\x20a\x20dot\x0aand\x20a\x20non-negative\x20integer\x20(for\x20example,\x20<code>1.9</code>,\x20<code>1.14</code>).</p>\x0a<p>The\x20language\x20version\x20determines\x20which\x20language\x20features\x20are\x20available\x20when\x0acompiling\x20packages\x20in\x20the\x20module.\x20Language\x20features\x20present\x20in\x20that\x20version\x0awill\x20be\x20available\x20for\x20use.\x20Language\x20features\x20removed\x20in\x20earlier\x20versions,\x0aor\x20added\x20in\x20later\x20versions,\x20will\x20not\x20be\x20available.\x20The\x20language\x20version\x20does\x20not\x0aaffect\x20build\x20tags,\x20which\x20are\x20determined\x20by\x20the\x20Go\x20release\x20being\x20used.</p>\x0a<p>The\x20language\x20version\x20is\x20also\x20used\x20to\x20enable\x20features\x20in\x20the\x20<code>go</code>\x20command.\x20For\x0aexample,\x20automatic\x20<a\x20href=\"#vendoring\">vendoring</a>\x20may\x20be\x20enabled\x20with\x20a\x20<code>go</code>\x20version\x20of\x0a<code>1.14</code>\x20or\x20higher.</p>\x0a<p>A\x20<code>go.mod</code>\x20file\x20may\x20contain\x20at\x20most\x20one\x20<code>go</code>\x20directive.\x20Most\x20commands\x20will\x20add\x20a\x0a<code>go</code>\x20directive\x20with\x20the\x20current\x20Go\x20version\x20if\x20one\x20is\x20not\x20present.</p>\x0a<pre><code>GoDirective\x20=\x20&quot;go&quot;\x20GoVersion\x20newline\x20.\x0aGoVersion\x20=\x20string\x20|\x20ident\x20.\x20\x20/*\x20valid\x20release\x20version;\x20see\x20above\x20*/\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>go\x201.14\x0a</code></pre>\x0a<h3\x20id=\"go\"\x20class=\"mod-require\"><code>require</code>\x20directive</h3>\x0a<p>A\x20<code>require</code>\x20directive\x20declares\x20a\x20minimum\x20required\x20version\x20of\x20a\x20given\x20module\x0adependency.\x20For\x20each\x20required\x20module\x20version,\x20the\x20<code>go</code>\x20command\x20loads\x20the\x0a<code>go.mod</code>\x20file\x20for\x20that\x20version\x20and\x20incorporates\x20the\x20requirements\x20from\x20that\x0afile.\x20Once\x20all\x20requirements\x20have\x20been\x20loaded,\x20the\x20<code>go</code>\x20command\x20resolves\x20them\x0ausing\x20<a\x20href=\"#minimal-version-selection\">minimal\x20version\x20selection\x20(MVS)</a>\x20to\x20produce\x0athe\x20<a\x20href=\"#glos-build-list\">build\x20list</a>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20automatically\x20adds\x20<code>//\x20indirect</code>\x20comments\x20for\x20some\x0arequirements.\x20An\x20<code>//\x20indirect</code>\x20comment\x20indicates\x20that\x20no\x20package\x20from\x20the\x0arequired\x20module\x20is\x20directly\x20imported\x20by\x20any\x20package\x20in\x20the\x20main\x20module.\x0aThe\x20<code>go</code>\x20command\x20adds\x20an\x20indirect\x20requirement\x20when\x20the\x20selected\x20version\x20of\x20a\x0amodule\x20is\x20higher\x20than\x20what\x20is\x20already\x20implied\x20(transitively)\x20by\x20the\x20main\x0amodule's\x20other\x20dependencies.\x20That\x20may\x20occur\x20because\x20of\x20an\x20explicit\x20upgrade\x0a(<code>go\x20get\x20-u</code>),\x20removal\x20of\x20some\x20other\x20dependency\x20that\x20previously\x20imposed\x20the\x0arequirement\x20(<code>go\x20mod\x20tidy</code>),\x20or\x20a\x20dependency\x20that\x20imports\x20a\x20package\x20without\x0aa\x20corresponding\x20requirement\x20in\x20its\x20own\x20<code>go.mod</code>\x20file\x20(such\x20as\x20a\x20dependency\x0athat\x20lacks\x20a\x20<code>go.mod</code>\x20file\x20altogether).</p>\x0a<pre><code>RequireDirective\x20=\x20&quot;require&quot;\x20(\x20RequireSpec\x20|\x20&quot;(&quot;\x20newline\x20{\x20RequireSpec\x20}\x20&quot;)&quot;\x20newline\x20)\x20.\x0aRequireSpec\x20=\x20ModulePath\x20Version\x20newline\x20.\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>require\x20golang.org/x/net\x20v1.2.3\x0a\x0arequire\x20(\x0a\x20\x20\x20\x20golang.org/x/crypto\x20v1.4.5\x20//\x20indirect\x0a\x20\x20\x20\x20golang.org/x/text\x20v1.6.7\x0a)\x0a</code></pre>\x0a<h3\x20id=\"go\"\x20class=\"mod-exclude\"><code>exclude</code>\x20directive</h3>\x0a<p>An\x20<code>exclude</code>\x20directive\x20prevents\x20a\x20module\x20version\x20from\x20being\x20loaded\x20by\x20the\x20<code>go</code>\x0acommand.\x20If\x20an\x20excluded\x20version\x20is\x20referenced\x20by\x20a\x20<code>require</code>\x20directive\x20in\x20a\x0a<code>go.mod</code>\x20file,\x20the\x20<code>go</code>\x20command\x20will\x20list\x20available\x20versions\x20for\x20the\x20module\x20(as\x0ashown\x20with\x20<code>go\x20list\x20-m\x20-versions</code>)\x20and\x20will\x20load\x20the\x20next\x20higher\x20non-excluded\x0aversion\x20instead.\x20Both\x20release\x20and\x20pre-release\x20versions\x20are\x20considered\x20for\x20this\x0apurpose,\x20but\x20pseudo-versions\x20are\x20not.\x20If\x20there\x20are\x20no\x20higher\x20versions,\x0athe\x20<code>go</code>\x20command\x20will\x20report\x20an\x20error.\x20Note\x20that\x20this\x20<a\x20href=\"https://golang.org/issue/36465\">may\x0achange</a>\x20in\x20Go\x201.15.</p>\x0a<!--\x20TODO(golang.org/issue/36465):\x20update\x20after\x20change\x20-->\x0a<p><code>exclude</code>\x20directives\x20only\x20apply\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file\x20and\x20are\x0aignored\x20in\x20other\x20modules.\x20See\x20<a\x20href=\"#minimal-version-selection\">Minimal\x20version\x0aselection</a>\x20for\x20details.</p>\x0a<pre><code>ExcludeDirective\x20=\x20&quot;exclude&quot;\x20(\x20ExcludeSpec\x20|\x20&quot;(&quot;\x20newline\x20{\x20ExcludeSpec\x20}\x20&quot;)&quot;\x20)\x20.\x0aExcludeSpec\x20=\x20ModulePath\x20Version\x20newline\x20.\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>exclude\x20golang.org/x/net\x20v1.2.3\x0a\x0aexclude\x20(\x0a\x20\x20\x20\x20golang.org/x/crypto\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/text\x20v1.6.7\x0a)\x0a</code></pre>\x0a<h3\x20id=\"go\"\x20class=\"mod-replace\"><code>replace</code>\x20directive</h3>\x0a<p>A\x20<code>replace</code>\x20directive\x20replaces\x20the\x20contents\x20of\x20a\x20specific\x20version\x20of\x20a\x20module,\x0aor\x20all\x20versions\x20of\x20a\x20module,\x20with\x20contents\x20found\x20elsewhere.\x20The\x20replacement\x0amay\x20be\x20specified\x20with\x20either\x20another\x20module\x20path\x20and\x20version,\x20or\x20a\x0aplatform-specific\x20file\x20path.</p>\x0a<p>If\x20a\x20version\x20is\x20present\x20on\x20the\x20left\x20side\x20of\x20the\x20arrow\x20(<code>=&gt;</code>),\x20only\x20that\x20specific\x0aversion\x20of\x20the\x20module\x20is\x20replaced;\x20other\x20versions\x20will\x20be\x20accessed\x20normally.\x0aIf\x20the\x20left\x20version\x20is\x20omitted,\x20all\x20versions\x20of\x20the\x20module\x20are\x20replaced.</p>\x0a<p>If\x20the\x20path\x20on\x20the\x20right\x20side\x20of\x20the\x20arrow\x20is\x20an\x20absolute\x20or\x20relative\x20path\x0a(beginning\x20with\x20<code>./</code>\x20or\x20<code>../</code>),\x20it\x20is\x20interpreted\x20as\x20the\x20local\x20file\x20path\x20to\x20the\x0areplacement\x20module\x20root\x20directory,\x20which\x20must\x20contain\x20a\x20<code>go.mod</code>\x20file.\x20The\x0areplacement\x20version\x20must\x20be\x20omitted\x20in\x20this\x20case.</p>\x0a<p>If\x20the\x20path\x20on\x20the\x20right\x20side\x20is\x20not\x20a\x20local\x20path,\x20it\x20must\x20be\x20a\x20valid\x20module\x0apath.\x20In\x20this\x20case,\x20a\x20version\x20is\x20required.\x20The\x20same\x20module\x20version\x20must\x20not\x0aalso\x20appear\x20in\x20the\x20build\x20list.</p>\x0a<p>Regardless\x20of\x20whether\x20a\x20replacement\x20is\x20specified\x20with\x20a\x20local\x20path\x20or\x20module\x0apath,\x20if\x20the\x20replacement\x20module\x20has\x20a\x20<code>go.mod</code>\x20file,\x20its\x20<code>module</code>\x20directive\x0amust\x20match\x20the\x20module\x20path\x20it\x20replaces.</p>\x0a<p><code>replace</code>\x20directives\x20only\x20apply\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file\x0aand\x20are\x20ignored\x20in\x20other\x20modules.\x20See\x20<a\x20href=\"#minimal-version-selection\">Minimal\x20version\x0aselection</a>\x20for\x20details.</p>\x0a<pre><code>ReplaceDirective\x20=\x20&quot;replace&quot;\x20(\x20ReplaceSpec\x20|\x20&quot;(&quot;\x20newline\x20{\x20ReplaceSpec\x20}\x20&quot;)&quot;\x20newline\x20&quot;)&quot;\x20)\x20.\x0aReplaceSpec\x20=\x20ModulePath\x20[\x20Version\x20]\x20&quot;=&gt;&quot;\x20FilePath\x20newline\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20|\x20ModulePath\x20[\x20Version\x20]\x20&quot;=&gt;&quot;\x20ModulePath\x20Version\x20newline\x20.\x0aFilePath\x20=\x20/*\x20platform-specific\x20relative\x20or\x20absolute\x20file\x20path\x20*/\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>replace\x20golang.org/x/net\x20v1.2.3\x20=&gt;\x20example.com/fork/net\x20v1.4.5\x0a\x0areplace\x20(\x0a\x20\x20\x20\x20golang.org/x/net\x20v1.2.3\x20=&gt;\x20example.com/fork/net\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/net\x20=&gt;\x20example.com/fork/net\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/net\x20v1.2.3\x20=&gt;\x20./fork/net\x0a\x20\x20\x20\x20golang.org/x/net\x20=&gt;\x20./fork/net\x0a)\x0a</code></pre>\x0a<h3\x20id=\"go\"\x20class=\"mod-updates\">Automatic\x20updates</h3>\x0a<p>The\x20<code>go</code>\x20command\x20automatically\x20updates\x20<code>go.mod</code>\x20when\x20it\x20uses\x20the\x20module\x20graph\x20if\x0asome\x20information\x20is\x20missing\x20or\x20<code>go.mod</code>\x20doesn't\x20accurately\x20reflect\x20reality.\x20\x20For\x0aexample,\x20consider\x20this\x20<code>go.mod</code>\x20file:</p>\x0a<pre><code>module\x20example.com/M\x0a\x0arequire\x20(\x0a\x20\x20\x20\x20example.com/A\x20v1\x0a\x20\x20\x20\x20example.com/B\x20v1.0.0\x0a\x20\x20\x20\x20example.com/C\x20v1.0.0\x0a\x20\x20\x20\x20example.com/D\x20v1.2.3\x0a\x20\x20\x20\x20example.com/E\x20dev\x0a)\x0a\x0aexclude\x20example.com/D\x20v1.2.3\x0a</code></pre>\x0a<p>The\x20update\x20rewrites\x20non-canonical\x20version\x20identifiers\x20to\x0a<a\x20href=\"#glos-canonical-version\">canonical</a>\x20semver\x20form,\x20so\x20<code>example.com/A</code>'s\x20<code>v1</code>\x0abecomes\x20<code>v1.0.0</code>,\x20and\x20<code>example.com/E</code>'s\x20<code>dev</code>\x20becomes\x20the\x20pseudo-version\x20for\x20the\x0alatest\x20commit\x20on\x20the\x20<code>dev</code>\x20branch,\x20perhaps\x20<code>v0.0.0-20180523231146-b3f5c0f6e5f1</code>.</p>\x0a<p>The\x20update\x20modifies\x20requirements\x20to\x20respect\x20exclusions,\x20so\x20the\x20requirement\x20on\x0athe\x20excluded\x20<code>example.com/D\x20v1.2.3</code>\x20is\x20updated\x20to\x20use\x20the\x20next\x20available\x20version\x0aof\x20<code>example.com/D</code>,\x20perhaps\x20<code>v1.2.4</code>\x20or\x20<code>v1.3.0</code>.</p>\x0a<p>The\x20update\x20removes\x20redundant\x20or\x20misleading\x20requirements.\x20For\x20example,\x20if\x0a<code>example.com/A\x20v1.0.0</code>\x20itself\x20requires\x20<code>example.com/B\x20v1.2.0</code>\x20and\x20<code>example.com/C\x20v1.0.0</code>,\x20then\x20<code>go.mod</code>'s\x20requirement\x20of\x20<code>example.com/B\x20v1.0.0</code>\x20is\x20misleading\x0a(superseded\x20by\x20<code>example.com/A</code>'s\x20need\x20for\x20<code>v1.2.0</code>),\x20and\x20its\x20requirement\x20of\x0a<code>example.com/C\x20v1.0.0</code>\x20is\x20redundant\x20(implied\x20by\x20<code>example.com/A</code>'s\x20need\x20for\x20the\x0asame\x20version),\x20so\x20both\x20will\x20be\x20removed.\x20If\x20the\x20main\x20module\x20contains\x20packages\x0athat\x20directly\x20import\x20packages\x20from\x20<code>example.com/B</code>\x20or\x20<code>example.com/C</code>,\x20then\x20the\x0arequirements\x20will\x20be\x20kept\x20but\x20updated\x20to\x20the\x20actual\x20versions\x20being\x20used.</p>\x0a<p>Finally,\x20the\x20update\x20reformats\x20the\x20<code>go.mod</code>\x20in\x20a\x20canonical\x20formatting,\x20so\x0athat\x20future\x20mechanical\x20changes\x20will\x20result\x20in\x20minimal\x20diffs.\x20The\x20<code>go</code>\x20command\x0awill\x20not\x20update\x20<code>go.mod</code>\x20if\x20only\x20formatting\x20changes\x20are\x20needed.</p>\x0a<p>Because\x20the\x20module\x20graph\x20defines\x20the\x20meaning\x20of\x20import\x20statements,\x20any\x20commands\x0athat\x20load\x20packages\x20also\x20use\x20and\x20therefore\x20update\x20<code>go.mod</code>,\x20including\x20<code>go\x20build</code>,\x0a<code>go\x20get</code>,\x20<code>go\x20install</code>,\x20<code>go\x20list</code>,\x20<code>go\x20test</code>,\x20<code>go\x20mod\x20graph</code>,\x20<code>go\x20mod\x20tidy</code>,\x20and\x0a<code>go\x20mod\x20why</code>.</p>\x0a<p>The\x20<code>-mod=readonly</code>\x20flag\x20prevents\x20commands\x20from\x20automatically\x20updating\x0a<code>go.mod</code>.\x20However,\x20if\x20a\x20command\x20needs\x20to\x20perform\x20an\x20action\x20that\x20would\x0aupdate\x20to\x20<code>go.mod</code>,\x20it\x20will\x20report\x20an\x20error.\x20For\x20example,\x20if\x0a<code>go\x20build</code>\x20is\x20asked\x20to\x20build\x20a\x20package\x20not\x20provided\x20by\x20any\x20module\x20in\x20the\x20build\x0alist,\x20<code>go\x20build</code>\x20will\x20report\x20an\x20error\x20instead\x20of\x20looking\x20up\x20the\x20module\x20and\x0aupdating\x20requirements\x20in\x20<code>go.mod</code>.</p>\x0a<h2\x20id=\"minimal-version-selection\">Minimal\x20version\x20selection\x20(MVS)</h2>\x0a<p>Go\x20uses\x20an\x20algorithm\x20called\x20<dfn>Minimal\x20version\x20selection\x20(MVS)</dfn>\x20to\x20select\x0aa\x20set\x20of\x20module\x20versions\x20to\x20use\x20when\x20building\x20packages.\x20MVS\x20is\x20described\x20in\x0adetail\x20in\x20<a\x20href=\"https://research.swtch.com/vgo-mvs\">Minimal\x20Version\x20Selection</a>\x20by\x0aRuss\x20Cox.</p>\x0a<p>Conceptually,\x20MVS\x20operates\x20on\x20a\x20directed\x20graph\x20of\x20modules,\x20specified\x20with\x0a<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20files</a>.\x20Each\x20vertex\x20in\x20the\x20graph\x20represents\x20a\x0amodule\x20version.\x20Each\x20edge\x20represents\x20a\x20minimum\x20required\x20version\x20of\x20a\x20dependency,\x0aspecified\x20using\x20a\x20<a\x20href=\"#go.mod-require\"><code>require</code></a>\x0adirective.\x20<a\x20href=\"#go.mod-replace\"><code>replace</code></a>\x20and\x20<a\x20href=\"#go.mod-exclude\"><code>exclude</code></a>\x0adirectives\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file\x20modify\x20the\x20graph.</p>\x0a<p>MVS\x20produces\x20the\x20<a\x20href=\"#glos-build-list\">build\x20list</a>\x20as\x20output,\x20the\x20list\x20of\x20module\x0aversions\x20used\x20for\x20a\x20build.</p>\x0a<p>MVS\x20starts\x20at\x20the\x20main\x20module\x20(a\x20special\x20vertex\x20in\x20the\x20graph\x20that\x20has\x20no\x0aversion)\x20and\x20traverses\x20the\x20graph,\x20tracking\x20the\x20highest\x20required\x20version\x20of\x20each\x0amodule.\x20At\x20the\x20end\x20of\x20the\x20traversal,\x20the\x20highest\x20required\x20versions\x20comprise\x20the\x0abuild\x20list:\x20they\x20are\x20the\x20minimum\x20versions\x20that\x20satisfy\x20all\x20requirements.</p>\x0a<p>The\x20build\x20list\x20may\x20be\x20inspected\x20with\x20the\x20command\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m\x20all</code></a>.\x20Unlike\x20other\x20dependency\x20management\x20systems,\x20the\x20build\x20list\x20is\x0anot\x20saved\x20in\x20a\x20&quot;lock&quot;\x20file.\x20MVS\x20is\x20deterministic,\x20and\x20the\x20build\x20list\x20doesn't\x0achange\x20when\x20new\x20versions\x20of\x20dependencies\x20are\x20released,\x20so\x20MVS\x20is\x20used\x20to\x20compute\x0ait\x20at\x20the\x20beginning\x20of\x20every\x20module-aware\x20command.</p>\x0a<p>Consider\x20the\x20example\x20in\x20the\x20diagram\x20below.\x20The\x20main\x20module\x20requires\x20module\x20A\x0aat\x20version\x201.2\x20or\x20higher\x20and\x20module\x20B\x20at\x20version\x201.2\x20or\x20higher.\x20A\x201.2\x20and\x20B\x201.2\x0arequire\x20C\x201.3\x20and\x20C\x201.4,\x20respectively.\x20C\x201.3\x20and\x20C\x201.4\x20both\x20require\x20D\x201.2.</p>\x0a<p><img\x20src=\"/doc/mvs/buildlist.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20visited\x20versions\x20highlighted\"\x20title=\"MVS\x20build\x20list\x20graph\"></p>\x0a<p>MVS\x20visits\x20and\x20loads\x20the\x20<code>go.mod</code>\x20file\x20for\x20each\x20of\x20the\x20module\x20versions\x0ahighlighted\x20in\x20blue.\x20At\x20the\x20end\x20of\x20the\x20graph\x20traversal,\x20MVS\x20returns\x20a\x20build\x20list\x0acontaining\x20the\x20bolded\x20versions:\x20A\x201.2,\x20B\x201.2,\x20C\x201.4,\x20and\x20D\x201.2.\x20Note\x20that\x20higher\x0aversions\x20of\x20B\x20and\x20D\x20are\x20available\x20but\x20MVS\x20does\x20not\x20select\x20them,\x20since\x20nothing\x0arequires\x20them.</p>\x0a<h3\x20id=\"mvs-replace\">Replacement</h3>\x0a<p>The\x20content\x20of\x20a\x20module\x20(including\x20its\x20<code>go.mod</code>\x20file)\x20may\x20be\x20replaced\x20using\x20a\x0a<a\x20href=\"#go.mod-replace\"><code>replace</code>\x20directive</a>\x20in\x20the\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file.\x0aA\x20<code>replace</code>\x20directive\x20may\x20apply\x20to\x20a\x20specific\x20version\x20of\x20a\x20module\x20or\x20to\x20all\x0aversions\x20of\x20a\x20module.</p>\x0a<p>Replacements\x20change\x20the\x20module\x20graph,\x20since\x20a\x20replacement\x20module\x20may\x20have\x0adifferent\x20dependencies\x20than\x20replaced\x20versions.</p>\x0a<p>Consider\x20the\x20example\x20below,\x20where\x20C\x201.4\x20has\x20been\x20replaced\x20with\x20R.\x20R\x20depends\x20on\x20D\x0a1.3\x20instead\x20of\x20D\x201.2,\x20so\x20MVS\x20returns\x20a\x20build\x20list\x20containing\x20A\x201.2,\x20B\x201.2,\x20C\x201.4\x0a(replaced\x20with\x20R),\x20and\x20D\x201.3.</p>\x0a<p><img\x20src=\"/doc/mvs/replace.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20a\x20replacement\"\x20title=\"MVS\x20replacment\"></p>\x0a<h3\x20id=\"mvs-exclude\">Exclusion</h3>\x0a<p>A\x20module\x20may\x20also\x20be\x20excluded\x20at\x20specific\x20versions\x20using\x20an\x20<a\x20href=\"#go.mod-exclude\"><code>exclude</code>\x0adirective</a>\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file.</p>\x0a<p>Exclusions\x20also\x20change\x20the\x20module\x20graph.\x20When\x20a\x20version\x20is\x20excluded,\x20it\x20is\x0aremoved\x20from\x20the\x20module\x20graph,\x20and\x20requirements\x20on\x20it\x20are\x20redirected\x20to\x20the\x0anext\x20higher\x20version.</p>\x0a<p>Consider\x20the\x20example\x20below.\x20C\x201.3\x20has\x20been\x20excluded.\x20MVS\x20will\x20act\x20as\x20if\x20A\x201.2\x0arequired\x20C\x201.4\x20(the\x20next\x20higher\x20version)\x20instead\x20of\x20C\x201.3.</p>\x0a<p><img\x20src=\"/doc/mvs/exclude.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20an\x20exclusion\"\x20title=\"MVS\x20exclude\"></p>\x0a<h3\x20id=\"mvs-upgrade\">Upgrades</h3>\x0a<p>The\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20command\x20may\x20be\x20used\x20to\x20upgrade\x20a\x20set\x20of\x20modules.\x20To\x0aperform\x20an\x20upgrade,\x20the\x20<code>go</code>\x20command\x20changes\x20the\x20module\x20graph\x20before\x20running\x20MVS\x0aby\x20adding\x20edges\x20from\x20visited\x20versions\x20to\x20upgraded\x20versions.</p>\x0a<p>Consider\x20the\x20example\x20below.\x20Module\x20B\x20may\x20be\x20upgraded\x20from\x201.2\x20to\x201.3,\x20C\x20may\x20be\x0aupgraded\x20from\x201.3\x20to\x201.4,\x20and\x20D\x20may\x20be\x20upgraded\x20from\x201.2\x20to\x201.3.</p>\x0a<p><img\x20src=\"/doc/mvs/upgrade.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20upgrades\"\x20title=\"MVS\x20upgrade\"></p>\x0a<p>Upgrades\x20(and\x20downgrades)\x20may\x20add\x20or\x20remove\x20indirect\x20dependencies.\x20In\x20this\x20case,\x0aE\x201.1\x20and\x20F\x201.1\x20appear\x20in\x20the\x20build\x20list\x20after\x20the\x20upgrade,\x20since\x20E\x201.1\x20is\x0arequired\x20by\x20B\x201.3.</p>\x0a<p>To\x20preserve\x20upgrades,\x20the\x20<code>go</code>\x20command\x20updates\x20the\x20requirements\x20in\x20<code>go.mod</code>.\x20\x20It\x0awill\x20change\x20the\x20requirement\x20on\x20B\x20to\x20version\x201.3.\x20It\x20will\x20also\x20add\x20requirements\x0aon\x20C\x201.4\x20and\x20D\x201.3\x20with\x20<code>//\x20indirect</code>\x20comments,\x20since\x20those\x20versions\x20would\x20not\x0abe\x20selected\x20otherwise.</p>\x0a<h3\x20id=\"mvs-downgrade\">Downgrade</h3>\x0a<p>The\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20command\x20may\x20also\x20be\x20used\x20to\x20downgrade\x20a\x20set\x20of\x0amodules.\x20To\x20perform\x20a\x20downgrade,\x20the\x20<code>go</code>\x20command\x20changes\x20the\x20module\x20graph\x20by\x0aremoving\x20versions\x20above\x20the\x20downgraded\x20versions.\x20It\x20also\x20removes\x20versions\x20of\x0aother\x20modules\x20that\x20depend\x20on\x20removed\x20versions,\x20since\x20they\x20may\x20not\x20be\x20compatible\x0awith\x20the\x20downgraded\x20versions\x20of\x20their\x20dependencies.\x20If\x20the\x20main\x20module\x20requires\x0aa\x20module\x20version\x20removed\x20by\x20downgrading,\x20the\x20requirement\x20is\x20changed\x20to\x20a\x0aprevious\x20version\x20that\x20has\x20not\x20been\x20removed.\x20If\x20no\x20previous\x20version\x20is\x20available,\x0athe\x20requirement\x20is\x20dropped.</p>\x0a<p>Consider\x20the\x20example\x20below.\x20Suppose\x20that\x20a\x20problem\x20was\x20found\x20with\x20C\x201.4,\x20so\x20we\x0adowngrade\x20to\x20C\x201.3.\x20C\x201.4\x20is\x20removed\x20from\x20the\x20module\x20graph.\x20B\x201.2\x20is\x20also\x0aremoved,\x20since\x20it\x20requires\x20C\x201.4\x20or\x20higher.\x20The\x20main\x20module's\x20requirement\x20on\x20B\x0ais\x20changed\x20to\x201.1.</p>\x0a<p><img\x20src=\"/doc/mvs/downgrade.svg\"\x20alt=\"Module\x20version\x20graph\x20with\x20downgrade\"\x20title=\"MVS\x20downgrade\"></p>\x0a<p><a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20can\x20also\x20remove\x20dependencies\x20entirely,\x20using\x20an\x20<code>@none</code>\x0asuffix\x20after\x20an\x20argument.\x20This\x20works\x20similarly\x20to\x20a\x20downgrade.\x20All\x20versions\x0aof\x20the\x20named\x20module\x20are\x20removed\x20from\x20the\x20module\x20graph.</p>\x0a<h2\x20id=\"non-module-compat\">Compatibility\x20with\x20non-module\x20repositories</h2>\x0a<p>To\x20ensure\x20a\x20smooth\x20transition\x20from\x20<code>GOPATH</code>\x20to\x20modules,\x20the\x20<code>go</code>\x20command\x20can\x0adownload\x20and\x20build\x20packages\x20in\x20module-aware\x20mode\x20from\x20repositories\x20that\x20have\x20not\x0amigrated\x20to\x20modules\x20by\x20adding\x20a\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20file</a>.</p>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20downloads\x20a\x20module\x20at\x20a\x20given\x20version\x20<a\x20href=\"#vcs\">directly</a>\x0afrom\x20a\x20repository,\x20it\x20looks\x20up\x20a\x20repository\x20URL\x20for\x20the\x20module\x20path,\x20maps\x20the\x0aversion\x20to\x20a\x20revision\x20within\x20the\x20repository,\x20then\x20extracts\x20an\x20archive\x20of\x20the\x0arepository\x20at\x20that\x20revision.\x20If\x20the\x20<a\x20href=\"#glos-module-path\">module's\x20path</a>\x20is\x20equal\x0ato\x20the\x20<a\x20href=\"#glos-repository-root-path\">repository\x20root\x20path</a>,\x20and\x20the\x20repository\x0aroot\x20directory\x20does\x20not\x20contain\x20a\x20<code>go.mod</code>\x20file,\x20the\x20<code>go</code>\x20command\x20synthesizes\x20a\x0a<code>go.mod</code>\x20file\x20in\x20the\x20module\x20cache\x20that\x20contains\x20a\x20<a\x20href=\"#go.mod-module\"><code>module</code>\x0adirective</a>\x20and\x20nothing\x20else.\x20Since\x20synthetic\x20<code>go.mod</code>\x20files\x20do\x0anot\x20contain\x20<a\x20href=\"#go.mod-require\"><code>require</code>\x20directives</a>\x20for\x20their\x20dependencies,\x0aother\x20modules\x20that\x20depend\x20on\x20them\x20may\x20need\x20additional\x20<code>require</code>\x20directives\x20(with\x0a<code>//\x20indirect</code>\x20comments)\x20to\x20ensure\x20each\x20dependency\x20is\x20fetched\x20at\x20the\x20same\x20version\x0aon\x20every\x20build.</p>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20downloads\x20a\x20module\x20from\x20a\x0a<a\x20href=\"#communicating-with-proxies\">proxy</a>,\x20it\x20downloads\x20the\x20<code>go.mod</code>\x20file\x20separately\x0afrom\x20the\x20rest\x20of\x20the\x20module\x20content.\x20The\x20proxy\x20is\x20expected\x20to\x20serve\x20a\x20synthetic\x0a<code>go.mod</code>\x20file\x20if\x20the\x20original\x20module\x20didn't\x20have\x20one.</p>\x0a<h3\x20id=\"incompatible-versions\"><code>+incompatible</code>\x20versions</h3>\x0a<p>A\x20module\x20released\x20at\x20major\x20version\x202\x20or\x20higher\x20must\x20have\x20a\x20matching\x20<a\x20href=\"#major-version-suffixes\">major\x0aversion\x20suffix</a>\x20on\x20its\x20module\x20path.\x20For\x20example,\x20if\x20a\x0amodule\x20is\x20released\x20at\x20<code>v2.0.0</code>,\x20its\x20path\x20must\x20have\x20a\x20<code>/v2</code>\x20suffix.\x20This\x20allows\x0athe\x20<code>go</code>\x20command\x20to\x20treat\x20multiple\x20major\x20versions\x20of\x20a\x20project\x20as\x20distinct\x0amodules,\x20even\x20if\x20they're\x20developed\x20in\x20the\x20same\x20repository.</p>\x0a<p>The\x20major\x20version\x20suffix\x20requirement\x20was\x20introduced\x20when\x20module\x20support\x20was\x0aadded\x20to\x20the\x20<code>go</code>\x20command,\x20and\x20many\x20repositories\x20had\x20already\x20tagged\x20releases\x0awith\x20major\x20version\x20<code>2</code>\x20or\x20higher\x20before\x20that.\x20To\x20maintain\x20compatibility\x20with\x0athese\x20repositories,\x20the\x20<code>go</code>\x20command\x20adds\x20an\x20<code>+incompatible</code>\x20suffix\x20to\x20versions\x0awith\x20major\x20version\x202\x20or\x20higher\x20without\x20a\x20<code>go.mod</code>\x20file.\x20<code>+incompatible</code>\x0aindicates\x20that\x20a\x20version\x20is\x20part\x20of\x20the\x20same\x20module\x20as\x20versions\x20with\x20lower\x20major\x0aversion\x20numbers;\x20consequently,\x20the\x20<code>go</code>\x20command\x20may\x20automatically\x20upgrade\x20to\x0ahigher\x20<code>+incompatible</code>\x20versions\x20even\x20though\x20it\x20may\x20break\x20the\x20build.</p>\x0a<p>Consider\x20the\x20example\x20requirement\x20below:</p>\x0a<pre><code>require\x20example.com/m\x20v4.1.2+incompatible\x0a</code></pre>\x0a<p>The\x20version\x20<code>v4.1.2+incompatible</code>\x20refers\x20to\x20the\x20<a\x20href=\"#glos-semantic-version-tag\">semantic\x20version\x0atag</a>\x20<code>v4.1.2</code>\x20in\x20the\x20repository\x20that\x20provides\x20the\x0amodule\x20<code>example.com/m</code>.\x20The\x20module\x20must\x20be\x20in\x20the\x20repository\x20root\x20directory\x0a(that\x20is,\x20the\x20<a\x20href=\"#glos-module-path\">repository\x20root\x20path</a>\x20must\x20also\x20be\x0a<code>example.com/m</code>),\x20and\x20a\x20<code>go.mod</code>\x20file\x20must\x20not\x20be\x20present.\x20The\x20module\x20may\x20have\x0aversions\x20with\x20lower\x20major\x20version\x20numbers\x20like\x20<code>v1.5.2</code>,\x20and\x20the\x20<code>go</code>\x20command\x0amay\x20upgrade\x20automatically\x20to\x20<code>v4.1.2+incompatible</code>\x20from\x20those\x20versions\x20(see\x0a<a\x20href=\"#minimal-version-selection\">minimal\x20version\x20selection\x20(MVS)</a>\x20for\x20information\x0aon\x20how\x20upgrades\x20work).</p>\x0a<p>A\x20repository\x20that\x20migrates\x20to\x20modules\x20after\x20version\x20<code>v2.0.0</code>\x20is\x20tagged\x20should\x0ausually\x20release\x20a\x20new\x20major\x20version.\x20In\x20the\x20example\x20above,\x20the\x20author\x20should\x0acreate\x20a\x20module\x20with\x20the\x20path\x20<code>example.com/m/v5</code>\x20and\x20should\x20release\x20version\x0a<code>v5.0.0</code>.\x20The\x20author\x20should\x20also\x20update\x20imports\x20of\x20packages\x20in\x20the\x20module\x20to\x20use\x0athe\x20prefix\x20<code>example.com/m/v5</code>\x20instead\x20of\x20<code>example.com/m</code>.\x20See\x20<a\x20href=\"https://blog.golang.org/v2-go-modules\">Go\x20Modules:\x20v2\x0aand\x20Beyond</a>\x20for\x20a\x20more\x20detailed\x20example.</p>\x0a<p>Note\x20that\x20the\x20<code>+incompatible</code>\x20suffix\x20should\x20not\x20appear\x20on\x20a\x20tag\x20in\x20a\x20repository;\x0aa\x20tag\x20like\x20<code>v4.1.2+incompatible</code>\x20will\x20be\x20ignored.\x20The\x20suffix\x20only\x20appears\x20in\x0aversions\x20used\x20by\x20the\x20<code>go</code>\x20command.\x20See\x20<a\x20href=\"#vcs-version\">Mapping\x20versions\x20to\x0acommits</a>\x20for\x20details\x20on\x20the\x20distinction\x20between\x20versions\x20and\x20tags.</p>\x0a<p>Note\x20also\x20that\x20the\x20<code>+incompatible</code>\x20suffix\x20may\x20appear\x20on\x0a<a\x20href=\"#glos-pseudo-version\">pseudo-versions</a>.\x20For\x20example,\x0a<code>v2.0.1-20200722182040-012345abcdef+incompatible</code>\x20may\x20be\x20a\x20valid\x20pseudo-version.</p>\x0a<!--\x20TODO(jayconrod):\x20Is\x20it\x20appropriate\x0ato\x20link\x20to\x20the\x20blog\x20here?\x20Ideally,\x20we\x20would\x20have\x20a\x20more\x20detailed\x20guide.\x20-->\x0a<h3\x20id=\"minimal-module-compatibility\">Minimal\x20module\x20compatibility</h3>\x0a<p>A\x20module\x20released\x20at\x20major\x20version\x202\x20or\x20higher\x20is\x20required\x20to\x20have\x20a\x20<a\x20href=\"#glos-major-version-suffix\">major\x0aversion\x20suffix</a>\x20on\x20its\x20<a\x20href=\"#glos-module-path\">module\x0apath</a>.\x20The\x20module\x20may\x20or\x20may\x20not\x20be\x20developed\x20in\x20a\x20<a\x20href=\"#glos-major-version-subdirectory\">major\x0aversion\x20subdirectory</a>\x20within\x20its\x20repository.\x0aThis\x20has\x20implications\x20for\x20packages\x20that\x20import\x20packages\x20within\x20the\x20module\x20when\x0abuilding\x20<code>GOPATH</code>\x20mode.</p>\x0a<p>Normally\x20in\x20<code>GOPATH</code>\x20mode,\x20a\x20package\x20is\x20stored\x20in\x20a\x20directory\x20matching\x20its\x0a<a\x20href=\"#glos-repository-root-path\">repository's\x20root\x20path</a>\x20joined\x20with\x20its\x20diretory\x0awithin\x20the\x20repository.\x20For\x20example,\x20a\x20package\x20in\x20the\x20repository\x20with\x20root\x20path\x0a<code>example.com/repo</code>\x20in\x20the\x20subdirectory\x20<code>sub</code>\x20would\x20be\x20stored\x20in\x0a<code>$GOPATH/src/example.com/repo/sub</code>\x20and\x20would\x20be\x20imported\x20as\x0a<code>example.com/repo/sub</code>.</p>\x0a<p>For\x20a\x20module\x20with\x20a\x20major\x20version\x20suffix,\x20one\x20might\x20expect\x20to\x20find\x20the\x20package\x0a<code>example.com/repo/v2/sub</code>\x20in\x20the\x20directory\x0a<code>$GOPATH/src/example.com/repo/v2/sub</code>.\x20This\x20would\x20require\x20the\x20module\x20to\x20be\x0adeveloped\x20in\x20the\x20<code>v2</code>\x20subdirectory\x20of\x20its\x20repository.\x20The\x20<code>go</code>\x20command\x20supports\x0athis\x20but\x20does\x20not\x20require\x20it\x20(see\x20<a\x20href=\"#vcs-version\">Mapping\x20versions\x20to\x20commits</a>).</p>\x0a<p>If\x20a\x20module\x20is\x20<em>not</em>\x20developed\x20in\x20a\x20major\x20version\x20subdirectory,\x20then\x20its\x0adirectory\x20in\x20<code>GOPATH</code>\x20will\x20not\x20contain\x20the\x20major\x20version\x20suffix,\x20and\x20its\x0apackages\x20may\x20be\x20imported\x20without\x20the\x20major\x20version\x20suffix.\x20In\x20the\x20example\x20above,\x0athe\x20package\x20would\x20be\x20found\x20in\x20the\x20directory\x20<code>$GOPATH/src/example.com/repo/sub</code>\x0aand\x20would\x20be\x20imported\x20as\x20<code>example.com/repo/sub</code>.</p>\x0a<p>This\x20creates\x20a\x20problem\x20for\x20packages\x20intended\x20to\x20be\x20built\x20in\x20both\x20module\x20mode\x0aand\x20<code>GOPATH</code>\x20mode:\x20module\x20mode\x20requires\x20a\x20suffix,\x20while\x20<code>GOPATH</code>\x20mode\x20does\x20not.</p>\x0a<p>To\x20fix\x20this,\x20<dfn>minimal\x20module\x20compatibility</dfn>\x20was\x20added\x20in\x20Go\x201.11\x20and\x0awas\x20backported\x20to\x20Go\x201.9.7\x20and\x201.10.3.\x20When\x20an\x20import\x20path\x20is\x20resolved\x20to\x20a\x0adirectory\x20in\x20<code>GOPATH</code>\x20mode:</p>\x0a<ul>\x0a<li>When\x20resolving\x20an\x20import\x20of\x20the\x20form\x20<code>$modpath/$vn/$dir</code>\x20where:\x0a<ul>\x0a<li><code>$modpath</code>\x20is\x20a\x20valid\x20module\x20path,</li>\x0a<li><code>$vn</code>\x20is\x20a\x20major\x20version\x20suffix,</li>\x0a<li><code>$dir</code>\x20is\x20a\x20possibly\x20empty\x20subdirectory,</li>\x0a</ul>\x0a</li>\x0a<li>If\x20all\x20of\x20the\x20following\x20are\x20true:\x0a<ul>\x0a<li>The\x20package\x20<code>$modpath/$vn/$dir</code>\x20is\x20not\x20present\x20in\x20any\x20relevant\x20<code>vendor</code>\x0adirectory.</li>\x0a<li>A\x20<code>go.mod</code>\x20file\x20is\x20present\x20in\x20the\x20same\x20directory\x20as\x20the\x20importing\x20file\x0aor\x20in\x20any\x20parent\x20directory\x20up\x20to\x20the\x20<code>$GOPATH/src</code>\x20root,</li>\x0a<li>No\x20<code>$GOPATH[i]/src/$modpath/$vn/$suffix</code>\x20directory\x20exists\x20(for\x20any\x20root\x0a<code>$GOPATH[i]</code>),</li>\x0a<li>The\x20file\x20<code>$GOPATH[d]/src/$modpath/go.mod</code>\x20exists\x20(for\x20some\x20root\x0a<code>$GOPATH[d]</code>)\x20and\x20declares\x20the\x20module\x20path\x20as\x20<code>$modpath/$vn</code>,</li>\x0a</ul>\x0a</li>\x0a<li>Then\x20the\x20import\x20of\x20<code>$modpath/$vn/$dir</code>\x20is\x20resolved\x20to\x20the\x20directory\x0a<code>$GOPATH[d]/src/$modpath/$dir</code>.</li>\x0a</ul>\x0a<p>This\x20rules\x20allow\x20packages\x20that\x20have\x20been\x20migrated\x20to\x20modules\x20to\x20import\x20other\x0apackages\x20that\x20have\x20been\x20migrated\x20to\x20modules\x20when\x20built\x20in\x20<code>GOPATH</code>\x20mode\x20even\x0awhen\x20a\x20major\x20version\x20subdirectory\x20was\x20not\x20used.</p>\x0a<h2\x20id=\"mod-commands\">Module-aware\x20commands</h2>\x0a<p>Most\x20<code>go</code>\x20commands\x20may\x20run\x20in\x20<em>Module-aware\x20mode</em>\x20or\x20<em><code>GOPATH</code>\x20mode</em>.\x20In\x0amodule-aware\x20mode,\x20the\x20<code>go</code>\x20command\x20uses\x20<code>go.mod</code>\x20files\x20to\x20find\x20versioned\x0adependencies,\x20and\x20it\x20typically\x20loads\x20packages\x20out\x20of\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>,\x20downloading\x20modules\x20if\x20they\x20are\x20missing.\x20In\x20<code>GOPATH</code>\x0amode,\x20the\x20<code>go</code>\x20command\x20ignores\x20modules;\x20it\x20looks\x20in\x20<code>vendor</code>\x20directories\x20and\x20in\x0a<code>GOPATH</code>\x20to\x20find\x20dependencies.</p>\x0a<p>Module-aware\x20mode\x20is\x20active\x20by\x20default\x20whenever\x20a\x20<code>go.mod</code>\x20file\x20is\x20found\x20in\x20the\x0acurrent\x20directory\x20or\x20in\x20any\x20parent\x20directory.\x20For\x20more\x20fine-grained\x20control,\x20the\x0a<code>GO111MODULE</code>\x20environment\x20variable\x20may\x20be\x20set\x20to\x20one\x20of\x20three\x20values:\x20<code>on</code>,\x0a<code>off</code>,\x20or\x20<code>auto</code>.</p>\x0a<ul>\x0a<li>If\x20<code>GO111MODULE=off</code>,\x20the\x20<code>go</code>\x20command\x20ignores\x20<code>go.mod</code>\x20files\x20and\x20runs\x20in\x0a<code>GOPATH</code>\x20mode.</li>\x0a<li>If\x20<code>GO111MODULE=on</code>,\x20the\x20<code>go</code>\x20command\x20runs\x20in\x20module-aware\x20mode,\x20even\x20when\x0ano\x20<code>go.mod</code>\x20file\x20is\x20present.\x20Not\x20all\x20commands\x20work\x20without\x20a\x20<code>go.mod</code>\x20file:\x0asee\x20<a\x20href=\"#commands-outside\">Module\x20commands\x20outside\x20a\x20module</a>.</li>\x0a<li>If\x20<code>GO111MODULE=auto</code>\x20or\x20is\x20unset,\x20the\x20<code>go</code>\x20command\x20runs\x20in\x20module-aware\x0amode\x20if\x20a\x20<code>go.mod</code>\x20file\x20is\x20present\x20in\x20the\x20current\x20directory\x20or\x20any\x20parent\x0adirectory\x20(the\x20default\x20behavior).</li>\x0a</ul>\x0a<p>In\x20module-aware\x20mode,\x20<code>GOPATH</code>\x20no\x20longer\x20defines\x20the\x20meaning\x20of\x20imports\x20during\x20a\x0abuild,\x20but\x20it\x20still\x20stores\x20downloaded\x20dependencies\x20(in\x20<code>GOPATH/pkg/mod</code>;\x20see\x0a<a\x20href=\"#module-cache\">Module\x20cache</a>)\x20and\x20installed\x20commands\x20(in\x20<code>GOPATH/bin</code>,\x20unless\x0a<code>GOBIN</code>\x20is\x20set).</p>\x0a<h3\x20id=\"build-commands\">Build\x20commands</h3>\x0a<h3\x20id=\"vendoring\">Vendoring</h3>\x0a<p>When\x20using\x20modules,\x20the\x20<code>go</code>\x20command\x20typically\x20satisfies\x20dependencies\x20by\x0adownloading\x20modules\x20from\x20their\x20sources\x20into\x20the\x20module\x20cache,\x20then\x20loading\x0apackages\x20from\x20those\x20downloaded\x20copies.\x20<em>Vendoring</em>\x20may\x20be\x20used\x20to\x20allow\x0ainteroperation\x20with\x20older\x20versions\x20of\x20Go,\x20or\x20to\x20ensure\x20that\x20all\x20files\x20used\x20for\x20a\x0abuild\x20are\x20stored\x20in\x20a\x20single\x20file\x20tree.</p>\x0a<p>The\x20<code>go\x20mod\x20vendor</code>\x20command\x20constructs\x20a\x20directory\x20named\x20<code>vendor</code>\x20in\x20the\x20<a\x20href=\"#glos-main-module\">main\x0amodule's</a>\x20root\x20directory\x20containing\x20copies\x20of\x20all\x20packages\x0aneeded\x20to\x20build\x20and\x20test\x20packages\x20in\x20the\x20main\x20module.\x20Packages\x20that\x20are\x20only\x0aimported\x20by\x20tests\x20of\x20packages\x20outside\x20the\x20main\x20module\x20are\x20not\x20included.\x20As\x20with\x0a<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20and\x20other\x20module\x20commands,\x20<a\x20href=\"#glos-build-constraint\">build\x0aconstraints</a>\x20except\x20for\x20<code>ignore</code>\x20are\x20not\x20considered\x20when\x0aconstructing\x20the\x20<code>vendor</code>\x20directory.</p>\x0a<p><code>go\x20mod\x20vendor</code>\x20also\x20creates\x20the\x20file\x20<code>vendor/modules.txt</code>\x20that\x20contains\x20a\x20list\x0aof\x20vendored\x20packages\x20and\x20the\x20module\x20versions\x20they\x20were\x20copied\x20from.\x20When\x0avendoring\x20is\x20enabled,\x20this\x20manifest\x20is\x20used\x20as\x20a\x20source\x20of\x20module\x20version\x0ainformation,\x20as\x20reported\x20by\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>\x20and\x20<a\x20href=\"#go-version-m\"><code>go\x20version\x20-m</code></a>.\x20When\x20the\x20<code>go</code>\x20command\x20reads\x20<code>vendor/modules.txt</code>,\x20it\x20checks\x0athat\x20the\x20module\x20versions\x20are\x20consistent\x20with\x20<code>go.mod</code>.\x20If\x20<code>go.mod</code>\x20has\x20changed\x0asince\x20<code>vendor/modules.txt</code>\x20was\x20generated,\x20the\x20<code>go</code>\x20command\x20will\x20report\x20an\x20error.\x0a<code>go\x20mod\x20vendor</code>\x20should\x20be\x20run\x20again\x20to\x20update\x20the\x20<code>vendor</code>\x20directory.</p>\x0a<p>If\x20the\x20<code>vendor</code>\x20directory\x20is\x20present\x20in\x20the\x20main\x20module's\x20root\x20directory,\x20it\x0awill\x20be\x20used\x20automatically\x20if\x20the\x20<a\x20href=\"#go.mod-go\"><code>go</code>\x20version</a>\x20in\x20the\x20main\x0amodule's\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20file</a>\x20is\x20<code>1.14</code>\x20or\x20higher.\x20To\x20explicitly\x0aenable\x20vendoring,\x20invoke\x20the\x20<code>go</code>\x20command\x20with\x20the\x20flag\x20<code>-mod=vendor</code>.\x20To\x0adisable\x20vendoring,\x20use\x20the\x20flag\x20<code>-mod=mod</code>.</p>\x0a<p>When\x20vendoring\x20is\x20enabled,\x20<a\x20href=\"#build-commands\">build\x20commands</a>\x20like\x20<code>go\x20build</code>\x20and\x0a<code>go\x20test</code>\x20load\x20packages\x20from\x20the\x20<code>vendor</code>\x20directory\x20instead\x20of\x20accessing\x20the\x0anetwork\x20or\x20the\x20local\x20module\x20cache.\x20The\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>\x20command\x20only\x0aprints\x20information\x20about\x20modules\x20listed\x20in\x20<code>go.mod</code>.\x20<code>go\x20mod</code>\x20commands\x20such\x20as\x0a<a\x20href=\"#go-mod-download\"><code>go\x20mod\x20download</code></a>\x20and\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20do\x20not\x0awork\x20differently\x20when\x20vendoring\x20is\x20enabled\x20and\x20will\x20still\x20download\x20modules\x20and\x0aaccess\x20the\x20module\x20cache.\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>\x20also\x20does\x20not\x20work\x20differently\x20when\x0avendoring\x20is\x20enabled.</p>\x0a<p>Unlike\x20<a\x20href=\"https://golang.org/s/go15vendor\">vendoring\x20in\x20<code>GOPATH</code></a>,\x20the\x20<code>go</code>\x0acommand\x20ignores\x20vendor\x20directories\x20in\x20locations\x20other\x20than\x20the\x20main\x20module's\x0aroot\x20directory.</p>\x0a<h3\x20id=\"go-get\"><code>go\x20get</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20get\x20[-d]\x20[-t]\x20[-u]\x20[build\x20flags]\x20[packages]\x0a</code></pre>\x0a<p>Examples:</p>\x0a<pre><code>#\x20Install\x20the\x20latest\x20version\x20of\x20a\x20tool.\x0a$\x20go\x20get\x20golang.org/x/tools/cmd/goimports\x0a\x0a#\x20Upgrade\x20a\x20specific\x20module.\x0a$\x20go\x20get\x20-d\x20golang.org/x/net\x0a\x0a#\x20Upgrade\x20modules\x20that\x20provide\x20packages\x20imported\x20by\x20packages\x20in\x20the\x20main\x20module.\x0a$\x20go\x20get\x20-d\x20-u\x20./...\x0a\x0a#\x20Upgrade\x20or\x20downgrade\x20to\x20a\x20specific\x20version\x20of\x20a\x20module.\x0a$\x20go\x20get\x20-d\x20golang.org/x/text@v0.3.2\x0a\x0a#\x20Update\x20to\x20the\x20commit\x20on\x20the\x20module's\x20master\x20branch.\x0a$\x20go\x20get\x20-d\x20golang.org/x/text@master\x0a\x0a#\x20Remove\x20a\x20dependency\x20on\x20a\x20module\x20and\x20downgrade\x20modules\x20that\x20require\x20it\x0a#\x20to\x20versions\x20that\x20don't\x20require\x20it.\x0a$\x20go\x20get\x20-d\x20golang.org/x/text@none\x0a</code></pre>\x0a<p>The\x20<code>go\x20get</code>\x20command\x20updates\x20module\x20dependencies\x20in\x20the\x20<a\x20href=\"#go.mod-files\"><code>go.mod</code>\x0afile</a>\x20for\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module</a>,\x20then\x20builds\x20and\x0ainstalls\x20packages\x20listed\x20on\x20the\x20command\x20line.</p>\x0a<p>The\x20first\x20step\x20is\x20to\x20determine\x20which\x20modules\x20to\x20update.\x20<code>go\x20get</code>\x20accepts\x20a\x20list\x0aof\x20packages,\x20package\x20patterns,\x20and\x20module\x20paths\x20as\x20arguments.\x20If\x20a\x20package\x0aargument\x20is\x20specified,\x20<code>go\x20get</code>\x20updates\x20the\x20module\x20that\x20provides\x20the\x20package.\x0aIf\x20a\x20package\x20pattern\x20is\x20specified\x20(for\x20example,\x20<code>all</code>\x20or\x20a\x20path\x20with\x20a\x20<code>...</code>\x0awildcard),\x20<code>go\x20get</code>\x20expands\x20the\x20pattern\x20to\x20a\x20set\x20of\x20packages,\x20then\x20updates\x20the\x0amodules\x20that\x20provide\x20the\x20packages.\x20If\x20an\x20argument\x20names\x20a\x20module\x20but\x20not\x20a\x0apackage\x20(for\x20example,\x20the\x20module\x20<code>golang.org/x/net</code>\x20has\x20no\x20package\x20in\x20its\x20root\x0adirectory),\x20<code>go\x20get</code>\x20will\x20update\x20the\x20module\x20but\x20will\x20not\x20build\x20a\x20package.\x20If\x20no\x0aarguments\x20are\x20specified,\x20<code>go\x20get</code>\x20acts\x20as\x20if\x20<code>.</code>\x20were\x20specified\x20(the\x20package\x20in\x0athe\x20current\x20directory);\x20this\x20may\x20be\x20used\x20together\x20with\x20the\x20<code>-u</code>\x20flag\x20to\x20update\x0amodules\x20that\x20provide\x20imported\x20packages.</p>\x0a<p>Each\x20argument\x20may\x20include\x20a\x20<dfn>version\x20query\x20suffix</dfn>\x20indicating\x20the\x0adesired\x20version,\x20as\x20in\x20<code>go\x20get\x20golang.org/x/text@v0.3.0</code>.\x20A\x20version\x20query\x0asuffix\x20consists\x20of\x20an\x20<code>@</code>\x20symbol\x20followed\x20by\x20a\x20<a\x20href=\"#version-queries\">version\x20query</a>,\x0awhich\x20may\x20indicate\x20a\x20specific\x20version\x20(<code>v0.3.0</code>),\x20a\x20version\x20prefix\x20(<code>v0.3</code>),\x0aa\x20branch\x20or\x20tag\x20name\x20(<code>master</code>),\x20a\x20revision\x20(<code>1234abcd</code>),\x20or\x20one\x20of\x20the\x20special\x0aqueries\x20<code>latest</code>,\x20<code>upgrade</code>,\x20<code>patch</code>,\x20or\x20<code>none</code>.\x20If\x20no\x20version\x20is\x20given,\x0a<code>go\x20get</code>\x20uses\x20the\x20<code>@upgrade</code>\x20query.</p>\x0a<p>Once\x20<code>go\x20get</code>\x20has\x20resolved\x20its\x20arguments\x20to\x20specific\x20modules\x20and\x20versions,\x20<code>go\x20get</code>\x20will\x20add,\x20change,\x20or\x20remove\x20<a\x20href=\"#go.mod-require\"><code>require</code>\x20directives</a>\x20in\x20the\x0amain\x20module's\x20<code>go.mod</code>\x20file\x20to\x20ensure\x20the\x20modules\x20remain\x20at\x20the\x20desired\x0aversions\x20in\x20the\x20future.\x20Note\x20that\x20required\x20versions\x20in\x20<code>go.mod</code>\x20files\x20are\x0a<em>minimum\x20versions</em>\x20and\x20may\x20be\x20increased\x20automatically\x20as\x20new\x20dependencies\x20are\x0aadded.\x20See\x20<a\x20href=\"#minimal-version-selection\">Minimal\x20version\x20selection\x20(MVS)</a>\x20for\x0adetails\x20on\x20how\x20versions\x20are\x20selected\x20and\x20conflicts\x20are\x20resolved\x20by\x20module-aware\x0acommands.</p>\x0a<!--\x20TODO(jayconrod):\x20add\x20diagrams\x20for\x20the\x20examples\x20below.\x0aWe\x20need\x20a\x20consistent\x20strategy\x20for\x20visualizing\x20module\x20graphs\x20here,\x20in\x20the\x20MVS\x0asection,\x20and\x20perhaps\x20in\x20other\x20documentation\x20(blog\x20posts,\x20etc.).\x0a-->\x0a<p>Other\x20modules\x20may\x20be\x20upgraded\x20when\x20a\x20module\x20named\x20on\x20the\x20command\x20line\x20is\x20added,\x0aupgraded,\x20or\x20downgraded\x20if\x20the\x20new\x20version\x20of\x20the\x20named\x20module\x20requires\x20other\x0amodules\x20at\x20higher\x20versions.\x20For\x20example,\x20suppose\x20module\x20<code>example.com/a</code>\x20is\x0aupgraded\x20to\x20version\x20<code>v1.5.0</code>,\x20and\x20that\x20version\x20requires\x20module\x20<code>example.com/b</code>\x0aat\x20version\x20<code>v1.2.0</code>.\x20If\x20module\x20<code>example.com/b</code>\x20is\x20currently\x20required\x20at\x20version\x0a<code>v1.1.0</code>,\x20<code>go\x20get\x20example.com/a@v1.5.0</code>\x20will\x20also\x20upgrade\x20<code>example.com/b</code>\x20to\x0a<code>v1.2.0</code>.</p>\x0a<p>Other\x20modules\x20may\x20be\x20downgraded\x20when\x20a\x20module\x20named\x20on\x20the\x20command\x20line\x20is\x0adowngraded\x20or\x20removed.\x20To\x20continue\x20the\x20above\x20example,\x20suppose\x20module\x0a<code>example.com/b</code>\x20is\x20downgraded\x20to\x20<code>v1.1.0</code>.\x20Module\x20<code>example.com/a</code>\x20would\x20also\x20be\x0adowngraded\x20to\x20a\x20version\x20that\x20requires\x20<code>example.com/b</code>\x20at\x20version\x20<code>v1.1.0</code>\x20or\x0alower.</p>\x0a<p>A\x20module\x20requirement\x20may\x20be\x20removed\x20using\x20the\x20version\x20suffix\x20<code>@none</code>.\x20This\x20is\x20a\x0aspecial\x20kind\x20of\x20downgrade.\x20Modules\x20that\x20depend\x20on\x20the\x20removed\x20module\x20will\x20be\x0adowngraded\x20or\x20removed\x20as\x20needed.\x20A\x20module\x20requirement\x20may\x20be\x20removed\x20even\x20if\x20one\x0aor\x20more\x20of\x20its\x20packages\x20are\x20imported\x20by\x20packages\x20in\x20the\x20main\x20module.\x20In\x20this\x0acase,\x20the\x20next\x20build\x20command\x20may\x20add\x20a\x20new\x20module\x20requirement.</p>\x0a<p>If\x20a\x20module\x20is\x20needed\x20at\x20two\x20different\x20versions\x20(specified\x20explicitly\x20in\x20command\x0aline\x20arguments\x20or\x20to\x20satisfy\x20upgrades\x20and\x20downgrades),\x20<code>go\x20get</code>\x20will\x20report\x20an\x0aerror.</p>\x0a<p>After\x20<code>go\x20get</code>\x20updates\x20the\x20<code>go.mod</code>\x20file,\x20it\x20builds\x20the\x20packages\x20named\x0aon\x20the\x20command\x20line.\x20Executables\x20will\x20be\x20installed\x20in\x20the\x20directory\x20named\x20by\x0athe\x20<code>GOBIN</code>\x20environment\x20variable,\x20which\x20defaults\x20to\x20<code>$GOPATH/bin</code>\x20or\x0a<code>$HOME/go/bin</code>\x20if\x20the\x20<code>GOPATH</code>\x20environment\x20variable\x20is\x20not\x20set.</p>\x0a<p><code>go\x20get</code>\x20supports\x20the\x20following\x20flags:</p>\x0a<ul>\x0a<li>The\x20<code>-d</code>\x20flag\x20tells\x20<code>go\x20get</code>\x20not\x20to\x20build\x20or\x20install\x20packages.\x20When\x20<code>-d</code>\x20is\x0aused,\x20<code>go\x20get</code>\x20will\x20only\x20manage\x20dependencies\x20in\x20<code>go.mod</code>.</li>\x0a<li>The\x20<code>-u</code>\x20flag\x20tells\x20<code>go\x20get</code>\x20to\x20upgrade\x20modules\x20providing\x20packages\x0aimported\x20directly\x20or\x20indirectly\x20by\x20packages\x20named\x20on\x20the\x20command\x20line.\x0aEach\x20module\x20selected\x20by\x20<code>-u</code>\x20will\x20be\x20upgraded\x20to\x20its\x20latest\x20version\x20unless\x0ait\x20is\x20already\x20required\x20at\x20a\x20higher\x20version\x20(a\x20pre-release).</li>\x0a<li>The\x20<code>-u=patch</code>\x20flag\x20(not\x20<code>-u\x20patch</code>)\x20also\x20tells\x20<code>go\x20get</code>\x20to\x20upgrade\x0adependencies,\x20but\x20<code>go\x20get</code>\x20will\x20upgrade\x20each\x20dependency\x20to\x20the\x20latest\x20patch\x0aversion\x20(similar\x20to\x20the\x20<code>@patch</code>\x20version\x20query).</li>\x0a<li>The\x20<code>-t</code>\x20flag\x20tells\x20<code>go\x20get</code>\x20to\x20consider\x20modules\x20needed\x20to\x20build\x20tests\x0aof\x20packages\x20named\x20on\x20the\x20command\x20line.\x20When\x20<code>-t</code>\x20and\x20<code>-u</code>\x20are\x20used\x20together,\x0a<code>go\x20get</code>\x20will\x20update\x20test\x20dependencies\x20as\x20well.</li>\x0a<li>The\x20<code>-insecure</code>\x20flag\x20should\x20no\x20longer\x20be\x20used.\x20It\x20permits\x20<code>go\x20get</code>\x20to\x20resolve\x0acustom\x20import\x20paths\x20and\x20fetch\x20from\x20repositories\x20and\x20module\x20proxies\x20using\x0ainsecure\x20schemes\x20such\x20as\x20HTTP.\x20The\x20<code>GOINSECURE</code>\x20<a\x20href=\"#environment-variables\">environment\x0avariable</a>\x20provides\x20more\x20fine-grained\x20control\x20and\x0ashould\x20be\x20used\x20instead.</li>\x0a</ul>\x0a<h3\x20id=\"go-list-m\"><code>go\x20list\x20-m</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20list\x20-m\x20[-u]\x20[-versions]\x20[list\x20flags]\x20[modules]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>$\x20go\x20list\x20-m\x20all\x0a$\x20go\x20list\x20-m\x20-versions\x20example.com/m\x0a$\x20go\x20list\x20-m\x20-json\x20example.com/m@latest\x0a</code></pre>\x0a<p>The\x20<code>-m</code>\x20flag\x20causes\x20<code>go\x20list</code>\x20to\x20list\x20modules\x20instead\x20of\x20packages.\x20In\x20this\x0amode,\x20the\x20arguments\x20to\x20<code>go\x20list</code>\x20may\x20be\x20modules,\x20module\x20patterns\x20(containing\x20the\x0a<code>...</code>\x20wildcard),\x20<a\x20href=\"#version-queries\">version\x20queries</a>,\x20or\x20the\x20special\x20pattern\x0a<code>all</code>,\x20which\x20matches\x20all\x20modules\x20in\x20the\x20<a\x20href=\"#glos-build-list\">build\x20list</a>.\x20If\x20no\x0aarguments\x20are\x20specified,\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module</a>\x20is\x20listed.</p>\x0a<p>When\x20listing\x20modules,\x20the\x20<code>-f</code>\x20flag\x20still\x20specifies\x20a\x20format\x20template\x20applied\x0ato\x20a\x20Go\x20struct,\x20but\x20now\x20a\x20<code>Module</code>\x20struct:</p>\x0a<pre><code>type\x20Module\x20struct\x20{\x0a\x20\x20\x20\x20Path\x20\x20\x20\x20\x20\x20string\x20\x20\x20\x20\x20\x20\x20//\x20module\x20path\x0a\x20\x20\x20\x20Version\x20\x20\x20string\x20\x20\x20\x20\x20\x20\x20//\x20module\x20version\x0a\x20\x20\x20\x20Versions\x20\x20[]string\x20\x20\x20\x20\x20//\x20available\x20module\x20versions\x20(with\x20-versions)\x0a\x20\x20\x20\x20Replace\x20\x20\x20*Module\x20\x20\x20\x20\x20\x20//\x20replaced\x20by\x20this\x20module\x0a\x20\x20\x20\x20Time\x20\x20\x20\x20\x20\x20*time.Time\x20\x20\x20//\x20time\x20version\x20was\x20created\x0a\x20\x20\x20\x20Update\x20\x20\x20\x20*Module\x20\x20\x20\x20\x20\x20//\x20available\x20update,\x20if\x20any\x20(with\x20-u)\x0a\x20\x20\x20\x20Main\x20\x20\x20\x20\x20\x20bool\x20\x20\x20\x20\x20\x20\x20\x20\x20//\x20is\x20this\x20the\x20main\x20module?\x0a\x20\x20\x20\x20Indirect\x20\x20bool\x20\x20\x20\x20\x20\x20\x20\x20\x20//\x20is\x20this\x20module\x20only\x20an\x20indirect\x20dependency\x20of\x20main\x20module?\x0a\x20\x20\x20\x20Dir\x20\x20\x20\x20\x20\x20\x20string\x20\x20\x20\x20\x20\x20\x20//\x20directory\x20holding\x20files\x20for\x20this\x20module,\x20if\x20any\x0a\x20\x20\x20\x20GoMod\x20\x20\x20\x20\x20string\x20\x20\x20\x20\x20\x20\x20//\x20path\x20to\x20go.mod\x20file\x20for\x20this\x20module,\x20if\x20any\x0a\x20\x20\x20\x20GoVersion\x20string\x20\x20\x20\x20\x20\x20\x20//\x20go\x20version\x20used\x20in\x20module\x0a\x20\x20\x20\x20Error\x20\x20\x20\x20\x20*ModuleError\x20//\x20error\x20loading\x20module\x0a}\x0a\x0atype\x20ModuleError\x20struct\x20{\x0a\x20\x20\x20\x20Err\x20string\x20//\x20the\x20error\x20itself\x0a}\x0a</code></pre>\x0a<p>The\x20default\x20output\x20is\x20to\x20print\x20the\x20module\x20path\x20and\x20then\x20information\x20about\x20the\x0aversion\x20and\x20replacement\x20if\x20any.\x20For\x20example,\x20<code>go\x20list\x20-m\x20all</code>\x20might\x20print:</p>\x0a<pre><code>example.com/main/module\x0agolang.org/x/text\x20v0.3.0\x20=&gt;\x20/tmp/text\x0arsc.io/pdf\x20v0.1.1\x0a</code></pre>\x0a<p>The\x20<code>Module</code>\x20struct\x20has\x20a\x20<code>String</code>\x20method\x20that\x20formats\x20this\x20line\x20of\x20output,\x20so\x0athat\x20the\x20default\x20format\x20is\x20equivalent\x20to\x20<code>-f\x20'{{.String}}'</code>.</p>\x0a<p>Note\x20that\x20when\x20a\x20module\x20has\x20been\x20replaced,\x20its\x20<code>Replace</code>\x20field\x20describes\x20the\x0areplacement\x20module\x20module,\x20and\x20its\x20<code>Dir</code>\x20field\x20is\x20set\x20to\x20the\x20replacement\x0amodule's\x20source\x20code,\x20if\x20present.\x20(That\x20is,\x20if\x20<code>Replace</code>\x20is\x20non-nil,\x20then\x20<code>Dir</code>\x0ais\x20set\x20to\x20<code>Replace.Dir</code>,\x20with\x20no\x20access\x20to\x20the\x20replaced\x20source\x20code.)</p>\x0a<p>The\x20<code>-u</code>\x20flag\x20adds\x20information\x20about\x20available\x20upgrades.\x20When\x20the\x20latest\x20version\x0aof\x20a\x20given\x20module\x20is\x20newer\x20than\x20the\x20current\x20one,\x20<code>list\x20-u</code>\x20sets\x20the\x20module's\x0a<code>Update</code>\x20field\x20to\x20information\x20about\x20the\x20newer\x20module.\x20The\x20module's\x20<code>String</code>\x0amethod\x20indicates\x20an\x20available\x20upgrade\x20by\x20formatting\x20the\x20newer\x20version\x20in\x0abrackets\x20after\x20the\x20current\x20version.\x20For\x20example,\x20<code>go\x20list\x20-m\x20-u\x20all</code>\x20might\x0aprint:</p>\x0a<pre><code>example.com/main/module\x0agolang.org/x/text\x20v0.3.0\x20[v0.4.0]\x20=&gt;\x20/tmp/text\x0arsc.io/pdf\x20v0.1.1\x20[v0.1.2]\x0a</code></pre>\x0a<p>(For\x20tools,\x20<code>go\x20list\x20-m\x20-u\x20-json\x20all</code>\x20may\x20be\x20more\x20convenient\x20to\x20parse.)</p>\x0a<p>The\x20<code>-versions</code>\x20flag\x20causes\x20<code>list</code>\x20to\x20set\x20the\x20module's\x20<code>Versions</code>\x20field\x20to\x20a\x0alist\x20of\x20all\x20known\x20versions\x20of\x20that\x20module,\x20ordered\x20according\x20to\x20semantic\x0aversioning,\x20lowest\x20to\x20highest.\x20The\x20flag\x20also\x20changes\x20the\x20default\x20output\x20format\x0ato\x20display\x20the\x20module\x20path\x20followed\x20by\x20the\x20space-separated\x20version\x20list.</p>\x0a<p>The\x20template\x20function\x20<code>module</code>\x20takes\x20a\x20single\x20string\x20argument\x20that\x20must\x20be\x20a\x0amodule\x20path\x20or\x20query\x20and\x20returns\x20the\x20specified\x20module\x20as\x20a\x20<code>Module</code>\x20struct.\x20If\x0aan\x20error\x20occurs,\x20the\x20result\x20will\x20be\x20a\x20<code>Module</code>\x20struct\x20with\x20a\x20non-nil\x20<code>Error</code>\x0afield.</p>\x0a<h3\x20id=\"go-mod-download\"><code>go\x20mod\x20download</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20download\x20[-json]\x20[-x]\x20[modules]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>$\x20go\x20mod\x20download\x0a$\x20go\x20mod\x20download\x20golang.org/x/mod@v0.2.0\x0a</code></pre>\x0a<p>The\x20<code>go\x20mod\x20download</code>\x20command\x20downloads\x20the\x20named\x20modules\x20into\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>.\x20Arguments\x20can\x20be\x20module\x20paths\x20or\x20module\x0apatterns\x20selecting\x20dependencies\x20of\x20the\x20main\x20module\x20or\x20<a\x20href=\"#version-queries\">version\x0aqueries</a>\x20of\x20the\x20form\x20<code>path@version</code>.\x20With\x20no\x20arguments,\x0a<code>download</code>\x20applies\x20to\x20all\x20dependencies\x20of\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module</a>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20will\x20automatically\x20download\x20modules\x20as\x20needed\x20during\x20ordinary\x0aexecution.\x20The\x20<code>go\x20mod\x20download</code>\x20command\x20is\x20useful\x20mainly\x20for\x20pre-filling\x20the\x0amodule\x20cache\x20or\x20for\x20loading\x20data\x20to\x20be\x20served\x20by\x20a\x20<a\x20href=\"#glos-module-proxy\">module\x0aproxy</a>.</p>\x0a<p>By\x20default,\x20<code>download</code>\x20writes\x20nothing\x20to\x20standard\x20output.\x20It\x20prints\x20progress\x0amessages\x20and\x20errors\x20to\x20standard\x20error.</p>\x0a<p>The\x20<code>-json</code>\x20flag\x20causes\x20<code>download</code>\x20to\x20print\x20a\x20sequence\x20of\x20JSON\x20objects\x20to\x0astandard\x20output,\x20describing\x20each\x20downloaded\x20module\x20(or\x20failure),\x20corresponding\x0ato\x20this\x20Go\x20struct:</p>\x0a<pre><code>type\x20Module\x20struct\x20{\x0a\x20\x20\x20\x20Path\x20\x20\x20\x20\x20string\x20//\x20module\x20path\x0a\x20\x20\x20\x20Version\x20\x20string\x20//\x20module\x20version\x0a\x20\x20\x20\x20Error\x20\x20\x20\x20string\x20//\x20error\x20loading\x20module\x0a\x20\x20\x20\x20Info\x20\x20\x20\x20\x20string\x20//\x20absolute\x20path\x20to\x20cached\x20.info\x20file\x0a\x20\x20\x20\x20GoMod\x20\x20\x20\x20string\x20//\x20absolute\x20path\x20to\x20cached\x20.mod\x20file\x0a\x20\x20\x20\x20Zip\x20\x20\x20\x20\x20\x20string\x20//\x20absolute\x20path\x20to\x20cached\x20.zip\x20file\x0a\x20\x20\x20\x20Dir\x20\x20\x20\x20\x20\x20string\x20//\x20absolute\x20path\x20to\x20cached\x20source\x20root\x20directory\x0a\x20\x20\x20\x20Sum\x20\x20\x20\x20\x20\x20string\x20//\x20checksum\x20for\x20path,\x20version\x20(as\x20in\x20go.sum)\x0a\x20\x20\x20\x20GoModSum\x20string\x20//\x20checksum\x20for\x20go.mod\x20(as\x20in\x20go.sum)\x0a}\x0a</code></pre>\x0a<p>The\x20<code>-x</code>\x20flag\x20causes\x20<code>download</code>\x20to\x20print\x20the\x20commands\x20<code>download</code>\x20executes\x0ato\x20standard\x20error.</p>\x0a<h3\x20id=\"go-mod-edit\"><code>go\x20mod\x20edit</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20edit\x20[editing\x20flags]\x20[-fmt|-print|-json]\x20[go.mod]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>#\x20Add\x20a\x20replace\x20directive.\x0a$\x20go\x20mod\x20edit\x20-replace\x20example.com/a@v1.0.0=./a\x0a\x0a#\x20Remove\x20a\x20replace\x20directive.\x0a$\x20go\x20mod\x20edit\x20-dropreplace\x20example.com/a@v1.0.0\x0a\x0a#\x20Set\x20the\x20go\x20version,\x20add\x20a\x20requirement,\x20and\x20print\x20the\x20file\x0a#\x20instead\x20of\x20writing\x20it\x20to\x20disk.\x0a$\x20go\x20mod\x20edit\x20-go=1.14\x20-require=example.com/m@v1.0.0\x20-print\x0a\x0a#\x20Format\x20the\x20go.mod\x20file.\x0a$\x20go\x20mod\x20edit\x20-fmt\x0a\x0a#\x20Format\x20and\x20print\x20a\x20different\x20.mod\x20file.\x0a$\x20go\x20mod\x20edit\x20-print\x20tools.mod\x0a\x0a#\x20Print\x20a\x20JSON\x20representation\x20of\x20the\x20go.mod\x20file.\x0a$\x20go\x20mod\x20edit\x20-json\x0a</code></pre>\x0a<p>The\x20<code>go\x20mod\x20edit</code>\x20command\x20provides\x20a\x20command-line\x20interface\x20for\x20editing\x20and\x0aformatting\x20<code>go.mod</code>\x20files,\x20for\x20use\x20primarily\x20by\x20tools\x20and\x20scripts.\x20<code>go\x20mod\x20edit</code>\x0areads\x20only\x20one\x20<code>go.mod</code>\x20file;\x20it\x20does\x20not\x20look\x20up\x20information\x20about\x20other\x0amodules.\x20By\x20default,\x20<code>go\x20mod\x20edit</code>\x20reads\x20and\x20writes\x20the\x20<code>go.mod</code>\x20file\x20of\x20the\x0amain\x20module,\x20but\x20a\x20different\x20target\x20file\x20can\x20be\x20specified\x20after\x20the\x20editing\x0aflags.</p>\x0a<p>The\x20editing\x20flags\x20specify\x20a\x20sequence\x20of\x20editing\x20operations.</p>\x0a<ul>\x0a<li>The\x20<code>-module</code>\x20flag\x20changes\x20the\x20module's\x20path\x20(the\x20<code>go.mod</code>\x20file's\x20module\x0aline).</li>\x0a<li>The\x20<code>-go=version</code>\x20flag\x20sets\x20the\x20expected\x20Go\x20language\x20version.</li>\x0a<li>The\x20<code>-require=path@version</code>\x20and\x20<code>-droprequire=path</code>\x20flags\x20add\x20and\x20drop\x20a\x0arequirement\x20on\x20the\x20given\x20module\x20path\x20and\x20version.\x20Note\x20that\x20<code>-require</code>\x0aoverrides\x20any\x20existing\x20requirements\x20on\x20<code>path</code>.\x20These\x20flags\x20are\x20mainly\x20for\x0atools\x20that\x20understand\x20the\x20module\x20graph.\x20Users\x20should\x20prefer\x20<code>go\x20get\x20path@version</code>\x20or\x20<code>go\x20get\x20path@none</code>,\x20which\x20make\x20other\x20<code>go.mod</code>\x20adjustments\x20as\x0aneeded\x20to\x20satisfy\x20constraints\x20imposed\x20by\x20other\x20modules.\x20See\x20<a\x20href=\"#go-get\"><code>go\x20get</code></a>.</li>\x0a<li>The\x20<code>-exclude=path@version</code>\x20and\x20<code>-dropexclude=path@version</code>\x20flags\x20add\x20and\x20drop\x0aan\x20exclusion\x20for\x20the\x20given\x20module\x20path\x20and\x20version.\x20Note\x20that\x0a<code>-exclude=path@version</code>\x20is\x20a\x20no-op\x20if\x20that\x20exclusion\x20already\x20exists.</li>\x0a<li>The\x20<code>-replace=old[@v]=new[@v]</code>\x20flag\x20adds\x20a\x20replacement\x20of\x20the\x20given\x20module\x0apath\x20and\x20version\x20pair.\x20If\x20the\x20<code>@v</code>\x20in\x20<code>old@v</code>\x20is\x20omitted,\x20a\x20replacement\x0awithout\x20a\x20version\x20on\x20the\x20left\x20side\x20is\x20added,\x20which\x20applies\x20to\x20all\x20versions\x20of\x0athe\x20old\x20module\x20path.\x20If\x20the\x20<code>@v</code>\x20in\x20<code>new@v</code>\x20is\x20omitted,\x20the\x20new\x20path\x20should\x20be\x0aa\x20local\x20module\x20root\x20directory,\x20not\x20a\x20module\x20path.\x20Note\x20that\x20<code>-replace</code>\x0aoverrides\x20any\x20redundant\x20replacements\x20for\x20<code>old[@v]</code>,\x20so\x20omitting\x20<code>@v</code>\x20will\x20drop\x0areplacements\x20for\x20specific\x20versions.</li>\x0a<li>The\x20<code>-dropreplace=old[@v]</code>\x20flag\x20drops\x20a\x20replacement\x20of\x20the\x20given\x20module\x20path\x0aand\x20version\x20pair.\x20If\x20the\x20<code>@v</code>\x20is\x20provided,\x20a\x20replacement\x20with\x20the\x20given\x0aversion\x20is\x20dropped.\x20An\x20existing\x20replacement\x20without\x20a\x20version\x20on\x20the\x20left\x20side\x0amay\x20still\x20replace\x20the\x20module.\x20If\x20the\x20<code>@v</code>\x20is\x20omitted,\x20a\x20replacement\x20without\x20a\x0aversion\x20is\x20dropped.</li>\x0a</ul>\x0a<p>The\x20editing\x20flags\x20may\x20be\x20repeated.\x20The\x20changes\x20are\x20applied\x20in\x20the\x20order\x20given.</p>\x0a<p><code>go\x20mod\x20edit</code>\x20has\x20additional\x20flags\x20that\x20control\x20its\x20output.</p>\x0a<ul>\x0a<li>The\x20<code>-fmt</code>\x20flag\x20reformats\x20the\x20<code>go.mod</code>\x20file\x20without\x20making\x20other\x20changes.\x0aThis\x20reformatting\x20is\x20also\x20implied\x20by\x20any\x20other\x20modifications\x20that\x20use\x20or\x0arewrite\x20the\x20<code>go.mod</code>\x20file.\x20The\x20only\x20time\x20this\x20flag\x20is\x20needed\x20is\x20if\x20no\x0aother\x20flags\x20are\x20specified,\x20as\x20in\x20<code>go\x20mod\x20edit\x20-fmt</code>.</li>\x0a<li>The\x20<code>-print</code>\x20flag\x20prints\x20the\x20final\x20<code>go.mod</code>\x20in\x20its\x20text\x20format\x20instead\x20of\x0awriting\x20it\x20back\x20to\x20disk.</li>\x0a<li>The\x20<code>-json</code>\x20flag\x20prints\x20the\x20final\x20<code>go.mod</code>\x20in\x20JSON\x20format\x20instead\x20of\x20writing\x0ait\x20back\x20to\x20disk\x20in\x20text\x20format.\x20The\x20JSON\x20output\x20corresponds\x20to\x20these\x20Go\x20types:</li>\x0a</ul>\x0a<pre><code>type\x20Module\x20struct\x20{\x0a\x20\x20\x20\x20\x20\x20\x20\x20Path\x20string\x0a\x20\x20\x20\x20\x20\x20\x20\x20Version\x20string\x0a}\x0a\x0atype\x20GoMod\x20struct\x20{\x0a\x20\x20\x20\x20\x20\x20\x20\x20Module\x20\x20Module\x0a\x20\x20\x20\x20\x20\x20\x20\x20Go\x20\x20\x20\x20\x20\x20string\x0a\x20\x20\x20\x20\x20\x20\x20\x20Require\x20[]Require\x0a\x20\x20\x20\x20\x20\x20\x20\x20Exclude\x20[]Module\x0a\x20\x20\x20\x20\x20\x20\x20\x20Replace\x20[]Replace\x0a}\x0a\x0atype\x20Require\x20struct\x20{\x0a\x20\x20\x20\x20\x20\x20\x20\x20Path\x20string\x0a\x20\x20\x20\x20\x20\x20\x20\x20Version\x20string\x0a\x20\x20\x20\x20\x20\x20\x20\x20Indirect\x20bool\x0a}\x0a\x0atype\x20Replace\x20struct\x20{\x0a\x20\x20\x20\x20\x20\x20\x20\x20Old\x20Module\x0a\x20\x20\x20\x20\x20\x20\x20\x20New\x20Module\x0a}\x0a</code></pre>\x0a<p>Note\x20that\x20this\x20only\x20describes\x20the\x20<code>go.mod</code>\x20file\x20itself,\x20not\x20other\x20modules\x0areferred\x20to\x20indirectly.\x20For\x20the\x20full\x20set\x20of\x20modules\x20available\x20to\x20a\x20build,\x0ause\x20<code>go\x20list\x20-m\x20-json\x20all</code>.\x20See\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>.</p>\x0a<p>For\x20example,\x20a\x20tool\x20can\x20obtain\x20the\x20<code>go.mod</code>\x20file\x20as\x20a\x20data\x20structure\x20by\x0aparsing\x20the\x20output\x20of\x20<code>go\x20mod\x20edit\x20-json</code>\x20and\x20can\x20then\x20make\x20changes\x20by\x20invoking\x0a<code>go\x20mod\x20edit</code>\x20with\x20<code>-require</code>,\x20<code>-exclude</code>,\x20and\x20so\x20on.</p>\x0a<p>Tools\x20may\x20also\x20use\x20the\x20package\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/modfile?tab=doc\"><code>golang.org/x/mod/modfile</code></a>\x0ato\x20parse,\x20edit,\x20and\x20format\x20<code>go.mod</code>\x20files.</p>\x0a<h3\x20id=\"go-mod-init\"><code>go\x20mod\x20init</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20init\x20[module-path]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>go\x20mod\x20init\x0ago\x20mod\x20init\x20example.com/m\x0a</code></pre>\x0a<p>The\x20<code>go\x20mod\x20init</code>\x20command\x20initializes\x20and\x20writes\x20a\x20new\x20<code>go.mod</code>\x20file\x20in\x20the\x0acurrent\x20directory,\x20in\x20effect\x20creating\x20a\x20new\x20module\x20rooted\x20at\x20the\x20current\x0adirectory.\x20The\x20<code>go.mod</code>\x20file\x20must\x20not\x20already\x20exist.</p>\x0a<p><code>init</code>\x20accepts\x20one\x20optional\x20argument,\x20the\x20<a\x20href=\"#glos-module-path\">module\x20path</a>\x20for\x0athe\x20new\x20module.\x20See\x20<a\x20href=\"#module-path\">Module\x20paths</a>\x20for\x20instructions\x20on\x20choosing\x0aa\x20module\x20path.\x20If\x20the\x20module\x20path\x20argument\x20is\x20omitted,\x20<code>init</code>\x20will\x20attempt\x0ato\x20infer\x20the\x20module\x20path\x20using\x20import\x20comments\x20in\x20<code>.go</code>\x20files,\x20vendoring\x20tool\x0aconfiguration\x20files,\x20and\x20the\x20current\x20directory\x20(if\x20in\x20<code>GOPATH</code>).</p>\x0a<p>If\x20a\x20configuration\x20file\x20for\x20a\x20vendoring\x20tool\x20is\x20present,\x20<code>init</code>\x20will\x20attempt\x20to\x0aimport\x20module\x20requirements\x20from\x20it.\x20<code>init</code>\x20supports\x20the\x20following\x20configuration\x0afiles.</p>\x0a<ul>\x0a<li><code>GLOCKFILE</code>\x20(Glock)</li>\x0a<li><code>Godeps/Godeps.json</code>\x20(Godeps)</li>\x0a<li><code>Gopkg.lock</code>\x20(dep)</li>\x0a<li><code>dependencies.tsv</code>\x20(godeps)</li>\x0a<li><code>glide.lock</code>\x20(glide)</li>\x0a<li><code>vendor.conf</code>\x20(trash)</li>\x0a<li><code>vendor.yml</code>\x20(govend)</li>\x0a<li><code>vendor/manifest</code>\x20(gvt)</li>\x0a<li><code>vendor/vendor.json</code>\x20(govendor)</li>\x0a</ul>\x0a<p>Vendoring\x20tool\x20configuration\x20files\x20can't\x20always\x20be\x20translated\x20with\x20perfect\x0afidelity.\x20For\x20example,\x20if\x20multiple\x20packages\x20within\x20the\x20same\x20repository\x20are\x0aimported\x20at\x20different\x20versions,\x20and\x20the\x20repository\x20only\x20contains\x20one\x20module,\x20the\x0aimported\x20<code>go.mod</code>\x20can\x20only\x20require\x20the\x20module\x20at\x20one\x20version.\x20You\x20may\x20wish\x20to\x0arun\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m\x20all</code></a>\x20to\x20check\x20all\x20versions\x20in\x20the\x20<a\x20href=\"#glos-build-list\">build\x0alist</a>,\x20and\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20to\x20add\x20missing\x0arequirements\x20and\x20to\x20drop\x20unused\x20requirements.</p>\x0a<h3\x20id=\"go-mod-tidy\"><code>go\x20mod\x20tidy</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20tidy\x20[-v]\x0a</code></pre>\x0a<p><code>go\x20mod\x20tidy</code>\x20ensures\x20that\x20the\x20<code>go.mod</code>\x20file\x20matches\x20the\x20source\x20code\x20in\x20the\x0amodule.\x20It\x20adds\x20any\x20missing\x20module\x20requirements\x20necessary\x20to\x20build\x20the\x20current\x0amodule's\x20packages\x20and\x20dependencies,\x20and\x20it\x20removes\x20requirements\x20on\x20modules\x20that\x0adon't\x20provide\x20any\x20relevant\x20packages.\x20It\x20also\x20adds\x20any\x20missing\x20entries\x20to\x0a<code>go.sum</code>\x20and\x20removes\x20unnecessary\x20entries.</p>\x0a<p>The\x20<code>-v</code>\x20flag\x20causes\x20<code>go\x20mod\x20tidy</code>\x20to\x20print\x20information\x20about\x20removed\x20modules\x0ato\x20standard\x20error.</p>\x0a<p><code>go\x20mod\x20tidy</code>\x20works\x20by\x20loading\x20all\x20of\x20the\x20packages\x20in\x20the\x20<a\x20href=\"#glos-main-module\">main\x0amodule</a>\x20and\x20all\x20of\x20the\x20packages\x20they\x20import,\x0arecursively.\x20This\x20includes\x20packages\x20imported\x20by\x20tests\x20(including\x20tests\x20in\x20other\x0amodules).\x20<code>go\x20mod\x20tidy</code>\x20acts\x20as\x20if\x20all\x20build\x20tags\x20are\x20enabled,\x20so\x20it\x20will\x0aconsider\x20platform-specific\x20source\x20files\x20and\x20files\x20that\x20require\x20custom\x20build\x0atags,\x20even\x20if\x20those\x20source\x20files\x20wouldn't\x20normally\x20be\x20built.\x20There\x20is\x20one\x0aexception:\x20the\x20<code>ignore</code>\x20build\x20tag\x20is\x20not\x20enabled,\x20so\x20a\x20file\x20with\x20the\x20build\x0aconstraint\x20<code>//\x20+build\x20ignore</code>\x20will\x20not\x20be\x20considered.\x20Note\x20that\x20<code>go\x20mod\x20tidy</code>\x0awill\x20not\x20consider\x20packages\x20in\x20the\x20main\x20module\x20in\x20directories\x20named\x20<code>testdata</code>\x20or\x0awith\x20names\x20that\x20start\x20with\x20<code>.</code>\x20or\x20<code>_</code>\x20unless\x20those\x20packages\x20are\x20explicitly\x0aimported\x20by\x20other\x20packages.</p>\x0a<p>Once\x20<code>go\x20mod\x20tidy</code>\x20has\x20loaded\x20this\x20set\x20of\x20packages,\x20it\x20ensures\x20that\x20each\x20module\x0athat\x20provides\x20one\x20or\x20more\x20packages\x20either\x20has\x20a\x20<code>require</code>\x20directive\x20in\x20the\x20main\x0amodule's\x20<code>go.mod</code>\x20file\x20or\x20is\x20required\x20by\x20another\x20required\x20module.\x20\x20<code>go\x20mod\x20tidy</code>\x0awill\x20add\x20a\x20requirement\x20on\x20the\x20latest\x20version\x20on\x20each\x20missing\x20module\x20(see\x0a<a\x20href=\"#version-queries\">Version\x20queries</a>\x20for\x20the\x20definition\x20of\x20the\x20<code>latest</code>\x0aversion).\x20<code>go\x20mod\x20tidy</code>\x20will\x20remove\x20<code>require</code>\x20directives\x20for\x20modules\x20that\x20don't\x0aprovide\x20any\x20packages\x20in\x20the\x20set\x20described\x20above.</p>\x0a<p><code>go\x20mod\x20tidy</code>\x20may\x20also\x20add\x20or\x20remove\x20<code>//\x20indirect</code>\x20comments\x20on\x20<code>require</code>\x0adirectives.\x20An\x20<code>//\x20indirect</code>\x20comment\x20denotes\x20a\x20module\x20that\x20does\x20not\x20provide\x0apackages\x20imported\x20by\x20packages\x20in\x20the\x20main\x20module.\x20These\x20requirements\x20will\x20be\x0apresent\x20if\x20the\x20module\x20that\x20imports\x20packages\x20in\x20the\x20indirect\x20dependency\x20has\x0ano\x20<code>go.mod</code>\x20file.\x20They\x20may\x20also\x20be\x20present\x20if\x20the\x20indirect\x20dependency\x20is\x0arequired\x20at\x20a\x20higher\x20version\x20than\x20is\x20implied\x20by\x20the\x20module\x20graph;\x20this\x20usually\x0ahappens\x20after\x20running\x20a\x20command\x20like\x20<code>go\x20get\x20-u\x20./...</code>.</p>\x0a<h3\x20id=\"go-mod-vendor\"><code>go\x20mod\x20vendor</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20vendor\x20[-v]\x0a</code></pre>\x0a<p>The\x20<code>go\x20mod\x20vendor</code>\x20command\x20constructs\x20a\x20directory\x20named\x20<code>vendor</code>\x20in\x20the\x20<a\x20href=\"#glos-main-module\">main\x0amodule's</a>\x20root\x20directory\x20that\x20contains\x20copies\x20of\x20all\x20packages\x0aneeded\x20to\x20support\x20builds\x20and\x20tests\x20of\x20packages\x20in\x20the\x20main\x20module.\x20Packages\x0athat\x20are\x20only\x20imported\x20by\x20tests\x20of\x20packages\x20outside\x20the\x20main\x20module\x20are\x20not\x0aincluded.\x20As\x20with\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20and\x20other\x20module\x20commands,\x0a<a\x20href=\"#glos-build-constraint\">build\x20constraints</a>\x20except\x20for\x20<code>ignore</code>\x20are\x20not\x0aconsidered\x20when\x20constructing\x20the\x20<code>vendor</code>\x20directory.</p>\x0a<p>When\x20vendoring\x20is\x20enabled,\x20the\x20<code>go</code>\x20command\x20will\x20load\x20packages\x20from\x20the\x20<code>vendor</code>\x0adirectory\x20instead\x20of\x20downloading\x20modules\x20from\x20their\x20sources\x20into\x20the\x20module\x0acache\x20and\x20using\x20packages\x20those\x20downloaded\x20copies.\x20See\x20<a\x20href=\"#vendoring\">Vendoring</a>\x0afor\x20more\x20information.</p>\x0a<p><code>go\x20mod\x20vendor</code>\x20also\x20creates\x20the\x20file\x20<code>vendor/modules.txt</code>\x20that\x20contains\x20a\x20list\x0aof\x20vendored\x20packages\x20and\x20the\x20module\x20versions\x20they\x20were\x20copied\x20from.\x20When\x0avendoring\x20is\x20enabled,\x20this\x20manifest\x20is\x20used\x20as\x20a\x20source\x20of\x20module\x20version\x0ainformation,\x20as\x20reported\x20by\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>\x20and\x20<a\x20href=\"#go-version-m\"><code>go\x20version\x20-m</code></a>.\x20When\x20the\x20<code>go</code>\x20command\x20reads\x20<code>vendor/modules.txt</code>,\x20it\x20checks\x0athat\x20the\x20module\x20versions\x20are\x20consistent\x20with\x20<code>go.mod</code>.\x20If\x20<code>go.mod</code>\x20changed\x20since\x0a<code>vendor/modules.txt</code>\x20was\x20generated,\x20<code>go\x20mod\x20vendor</code>\x20should\x20be\x20run\x20again.</p>\x0a<p>Note\x20that\x20<code>go\x20mod\x20vendor</code>\x20removes\x20the\x20<code>vendor</code>\x20directory\x20if\x20it\x20exists\x20before\x0are-constructing\x20it.\x20Local\x20changes\x20should\x20not\x20be\x20made\x20to\x20vendored\x20packages.\x0aThe\x20<code>go</code>\x20command\x20does\x20not\x20check\x20that\x20packages\x20in\x20the\x20<code>vendor</code>\x20directory\x20have\x0anot\x20been\x20modified,\x20but\x20one\x20can\x20verify\x20the\x20integrity\x20of\x20the\x20<code>vendor</code>\x20directory\x0aby\x20running\x20<code>go\x20mod\x20vendor</code>\x20and\x20checking\x20that\x20no\x20changes\x20were\x20made.</p>\x0a<p>The\x20<code>-v</code>\x20flag\x20causes\x20<code>go\x20mod\x20vendor</code>\x20to\x20print\x20the\x20names\x20of\x20vendored\x20modules\x0aand\x20packages\x20to\x20standard\x20error.</p>\x0a<h3\x20id=\"go-mod-verify\"><code>go\x20mod\x20verify</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20mod\x20verify\x0a</code></pre>\x0a<p><code>go\x20mod\x20verify</code>\x20checks\x20that\x20dependencies\x20of\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module</a>\x0astored\x20in\x20the\x20<a\x20href=\"#glos-module-cache\">module\x20cache</a>\x20have\x20not\x20been\x20modified\x20since\x0athey\x20were\x20downloaded.\x20To\x20perform\x20this\x20check,\x20<code>go\x20mod\x20verify</code>\x20hashes\x20each\x0adownloaded\x20module\x20<a\x20href=\"#zip-files\"><code>.zip</code>\x20file</a>\x20and\x20extracted\x20directory,\x20then\x0acompares\x20those\x20hashes\x20with\x20a\x20hash\x20recorded\x20when\x20the\x20module\x20was\x20first\x0adownloaded.\x20<code>go\x20mod\x20verify</code>\x20checks\x20each\x20module\x20in\x20the\x20<a\x20href=\"#glos-build-list\">build\x0alist</a>\x20(which\x20may\x20be\x20printed\x20with\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m\x20all</code></a>).</p>\x0a<p>If\x20all\x20the\x20modules\x20are\x20unmodified,\x20<code>go\x20mod\x20verify</code>\x20prints\x20&quot;all\x20modules\x0averified&quot;.\x20Otherwise,\x20it\x20reports\x20which\x20modules\x20have\x20been\x20changed\x20and\x20exits\x20with\x0aa\x20non-zero\x20status.</p>\x0a<p>Note\x20that\x20all\x20module-aware\x20commands\x20verify\x20that\x20hashes\x20in\x20the\x20main\x20module's\x0a<code>go.sum</code>\x20file\x20match\x20hashes\x20recorded\x20for\x20modules\x20downloaded\x20into\x20the\x20module\x0acache.\x20If\x20a\x20hash\x20is\x20missing\x20from\x20<code>go.sum</code>\x20(for\x20example,\x20because\x20the\x20module\x20is\x0abeing\x20used\x20for\x20the\x20first\x20time),\x20the\x20<code>go</code>\x20command\x20verifies\x20its\x20hash\x20using\x20the\x0a<a\x20href=\"#checksum-database\">checksum\x20database</a>\x20(unless\x20the\x20module\x20path\x20is\x20matched\x20by\x0a<code>GOPRIVATE</code>\x20or\x20<code>GONOSUMDB</code>).\x20See\x20<a\x20href=\"#authenticating\">Authenticating\x20modules</a>\x20for\x0adetails.</p>\x0a<p>In\x20contrast,\x20<code>go\x20mod\x20verify</code>\x20checks\x20that\x20module\x20<code>.zip</code>\x20files\x20and\x20their\x20extracted\x0adirectories\x20have\x20hashes\x20that\x20match\x20hashes\x20recorded\x20in\x20the\x20module\x20cache\x20when\x20they\x0awere\x20first\x20downloaded.\x20This\x20is\x20useful\x20for\x20detecting\x20changes\x20to\x20files\x20in\x20the\x0amodule\x20cache\x20<em>after</em>\x20a\x20module\x20has\x20been\x20downloaded\x20and\x20verified.\x20<code>go\x20mod\x20verify</code>\x0adoes\x20not\x20download\x20content\x20for\x20modules\x20not\x20in\x20the\x20cache,\x20and\x20it\x20does\x20not\x20use\x0a<code>go.sum</code>\x20files\x20to\x20verify\x20module\x20content.\x20However,\x20<code>go\x20mod\x20verify</code>\x20may\x20download\x0a<code>go.mod</code>\x20files\x20in\x20order\x20to\x20perform\x20<a\x20href=\"#minimal-version-selection\">minimal\x20version\x0aselection</a>.\x20It\x20will\x20use\x20<code>go.sum</code>\x20to\x20verify\x20those\x0afiles,\x20and\x20it\x20may\x20add\x20<code>go.sum</code>\x20entries\x20for\x20missing\x20hashes.</p>\x0a<h3\x20id=\"go-version-m\"><code>go\x20version\x20-m</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20version\x20[-m]\x20[-v]\x20[file\x20...]\x0a</code></pre>\x0a<p>Example:</p>\x0a<pre><code>#\x20Print\x20Go\x20version\x20used\x20to\x20build\x20go.\x0a$\x20go\x20version\x0a\x0a#\x20Print\x20Go\x20version\x20used\x20to\x20build\x20a\x20specific\x20executable.\x0a$\x20go\x20version\x20~/go/bin/gopls\x0a\x0a#\x20Print\x20Go\x20version\x20and\x20module\x20versions\x20used\x20to\x20build\x20a\x20specific\x20executable.\x0a$\x20go\x20version\x20-m\x20~/go/bin/gopls\x0a\x0a#\x20Print\x20Go\x20version\x20and\x20module\x20versions\x20used\x20to\x20build\x20executables\x20in\x20a\x20directory.\x0a$\x20go\x20version\x20-m\x20~/go/bin/\x0a</code></pre>\x0a<p><code>go\x20version</code>\x20reports\x20the\x20Go\x20version\x20used\x20to\x20build\x20each\x20executable\x20file\x20named\x0aon\x20the\x20command\x20line.</p>\x0a<p>If\x20no\x20files\x20are\x20named\x20on\x20the\x20command\x20line,\x20<code>go\x20version</code>\x20prints\x20its\x20own\x20version\x0ainformation.</p>\x0a<p>If\x20a\x20directory\x20is\x20named,\x20<code>go\x20version</code>\x20walks\x20that\x20directory,\x20recursively,\x20looking\x0afor\x20recognized\x20Go\x20binaries\x20and\x20reporting\x20their\x20versions.\x20By\x20default,\x20<code>go\x20version</code>\x20does\x20not\x20report\x20unrecognized\x20files\x20found\x20during\x20a\x20directory\x20scan.\x20The\x0a<code>-v</code>\x20flag\x20causes\x20it\x20to\x20report\x20unrecognized\x20files.</p>\x0a<p>The\x20<code>-m</code>\x20flag\x20causes\x20<code>go\x20version</code>\x20to\x20print\x20each\x20executable's\x20embedded\x20module\x0aversion\x20information,\x20when\x20available.\x20For\x20each\x20executable,\x20<code>go\x20version\x20-m</code>\x20prints\x0aa\x20table\x20with\x20tab-separated\x20columns\x20like\x20the\x20one\x20below.</p>\x0a<pre><code>$\x20go\x20version\x20-m\x20~/go/bin/goimports\x0a/home/jrgopher/go/bin/goimports:\x20go1.14.3\x0a\x20\x20\x20\x20\x20\x20\x20\x20path\x20\x20\x20\x20golang.org/x/tools/cmd/goimports\x0a\x20\x20\x20\x20\x20\x20\x20\x20mod\x20\x20\x20\x20\x20golang.org/x/tools\x20\x20\x20\x20\x20\x20v0.0.0-20200518203908-8018eb2c26ba\x20\x20\x20\x20\x20\x20h1:0Lcy64USfQQL6GAJma8BdHCgeofcchQj+Z7j0SXYAzU=\x0a\x20\x20\x20\x20\x20\x20\x20\x20dep\x20\x20\x20\x20\x20golang.org/x/mod\x20\x20\x20\x20\x20\x20\x20\x20v0.2.0\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20h1:KU7oHjnv3XNWfa5COkzUifxZmxp1TyI7ImMXqFxLwvQ=\x0a\x20\x20\x20\x20\x20\x20\x20\x20dep\x20\x20\x20\x20\x20golang.org/x/xerrors\x20\x20\x20\x20v0.0.0-20191204190536-9bdfabe68543\x20\x20\x20\x20\x20\x20h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=\x0a</code></pre>\x0a<p>The\x20format\x20of\x20the\x20table\x20may\x20change\x20in\x20the\x20future.\x20The\x20same\x20information\x20may\x20be\x0aobtained\x20from\x0a<a\x20href=\"https://pkg.go.dev/runtime/debug?tab=doc#ReadBuildInfo\"><code>runtime/debug.ReadBuildInfo</code></a>.</p>\x0a<p>The\x20meaning\x20of\x20each\x20row\x20in\x20the\x20table\x20is\x20determined\x20by\x20the\x20word\x20in\x20the\x20first\x0acolumn.</p>\x0a<ul>\x0a<li><strong><code>path</code></strong>:\x20the\x20path\x20of\x20the\x20<code>main</code>\x20package\x20used\x20to\x20build\x20the\x20executable.</li>\x0a<li><strong><code>mod</code></strong>:\x20the\x20module\x20containing\x20the\x20<code>main</code>\x20package.\x20The\x20columns\x20are\x20the\x0amodule\x20path,\x20version,\x20and\x20sum,\x20respectively.\x20The\x20<a\x20href=\"#glos-main-module\">main\x0amodule</a>\x20has\x20the\x20version\x20<code>(devel)</code>\x20and\x20no\x20sum.</li>\x0a<li><strong><code>dep</code></strong>:\x20a\x20module\x20that\x20provided\x20one\x20or\x20more\x20packages\x20linked\x20into\x20the\x0aexecutable.\x20Same\x20format\x20as\x20<code>mod</code>.</li>\x0a<li><strong><code>=&gt;</code></strong>:\x20a\x20<a\x20href=\"#go.mod-replace\">replacement</a>\x20for\x20the\x20module\x20on\x20the\x20previous\x0aline.\x20If\x20the\x20replacement\x20is\x20a\x20local\x20directory,\x20only\x20the\x20directory\x20path\x20is\x0alisted\x20(no\x20version\x20or\x20sum).\x20If\x20the\x20replacement\x20is\x20a\x20module\x20version,\x20the\x20path,\x0aversion,\x20and\x20sum\x20are\x20listed,\x20as\x20with\x20<code>mod</code>\x20and\x20<code>dep</code>.\x20A\x20replaced\x20module\x20has\x0ano\x20sum.</li>\x0a</ul>\x0a<h3\x20id=\"go-clean-modcache\"><code>go\x20clean\x20-modcache</code></h3>\x0a<p>Usage:</p>\x0a<pre><code>go\x20clean\x20[-modcache]\x0a</code></pre>\x0a<p>The\x20<code>-modcache</code>\x20flag\x20causes\x20<a\x20href=\"/cmd/go/#hdr-Remove_object_files_and_cached_files\"><code>go\x20clean</code></a>\x20to\x20remove\x20the\x20entire\x0a<a\x20href=\"#glos-module-cache\">module\x20cache</a>,\x20including\x20unpacked\x20source\x20code\x20of\x20versioned\x0adependencies.</p>\x0a<p>This\x20is\x20usually\x20the\x20best\x20way\x20to\x20remove\x20the\x20module\x20cache.\x20By\x20default,\x20most\x20files\x0aand\x20directories\x20in\x20the\x20module\x20cache\x20are\x20read-only\x20to\x20prevent\x20tests\x20and\x20editors\x0afrom\x20unintentionally\x20changing\x20files\x20after\x20they've\x20been\x0a<a\x20href=\"#authenticating\">authenticated</a>.\x20Unfortunately,\x20this\x20causes\x20commands\x20like\x0a<code>rm\x20-r</code>\x20to\x20fail,\x20since\x20files\x20can't\x20be\x20removed\x20without\x20first\x20making\x20their\x20parent\x0adirectories\x20writable.</p>\x0a<p>The\x20<code>-modcacherw</code>\x20flag\x20(accepted\x20by\x20<a\x20href=\"https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies\"><code>go\x20build</code></a>\x20and\x0aother\x20module-aware\x20commands)\x20causes\x20new\x20directories\x20in\x20the\x20module\x20cache\x20to\x0abe\x20writable.\x20To\x20pass\x20<code>-modcacherw</code>\x20to\x20all\x20module-aware\x20commands,\x20add\x20it\x20to\x20the\x0a<code>GOFLAGS</code>\x20variable.\x20<code>GOFLAGS</code>\x20may\x20be\x20set\x20in\x20the\x20environment\x20or\x20with\x20<a\x20href=\"https://golang.org/cmd/go/#hdr-Print_Go_environment_information\"><code>go\x20env\x20-w</code></a>.\x20For\x0aexample,\x20the\x20command\x20below\x20sets\x20it\x20permanently:</p>\x0a<pre><code>go\x20env\x20-w\x20GOFLAGS=-modcacherw\x0a</code></pre>\x0a<p><code>-modcacherw</code>\x20should\x20be\x20used\x20with\x20caution;\x20developers\x20should\x20be\x20careful\x20not\x0ato\x20make\x20changes\x20to\x20files\x20in\x20the\x20module\x20cache.\x20<a\x20href=\"#go-mod-verify\"><code>go\x20mod\x20verify</code></a>\x0amay\x20be\x20used\x20to\x20check\x20that\x20files\x20in\x20the\x20cache\x20match\x20hashes\x20in\x20the\x20main\x20module's\x0a<code>go.sum</code>\x20file.</p>\x0a<h3\x20id=\"version-queries\">Version\x20queries</h3>\x0a<p>Several\x20commands\x20allow\x20you\x20to\x20specify\x20a\x20version\x20of\x20a\x20module\x20using\x20a\x20<em>version\x0aquery</em>,\x20which\x20appears\x20after\x20an\x20<code>@</code>\x20character\x20following\x20a\x20module\x20or\x20package\x20path\x0aon\x20the\x20command\x20line.</p>\x0a<p>Examples:</p>\x0a<pre><code>go\x20get\x20example.com/m@latest\x0ago\x20mod\x20download\x20example.com/m@master\x0ago\x20list\x20-m\x20-json\x20example.com/m@e3702bed2\x0a</code></pre>\x0a<p>A\x20version\x20query\x20may\x20be\x20one\x20of\x20the\x20following:</p>\x0a<ul>\x0a<li>A\x20fully-specified\x20semantic\x20version,\x20such\x20as\x20<code>v1.2.3</code>,\x20which\x20selects\x20a\x0aspecific\x20version.\x20See\x20<a\x20href=\"#versions\">Versions</a>\x20for\x20syntax.</li>\x0a<li>A\x20semantic\x20version\x20prefix,\x20such\x20as\x20<code>v1</code>\x20or\x20<code>v1.2</code>,\x20which\x20selects\x20the\x20highest\x0aavailable\x20version\x20with\x20that\x20prefix.</li>\x0a<li>A\x20semantic\x20version\x20comparison,\x20such\x20as\x20<code>&lt;v1.2.3</code>\x20or\x20<code>&gt;=v1.5.6</code>,\x20which\x20selects\x0athe\x20nearest\x20available\x20version\x20to\x20the\x20comparison\x20target\x20(the\x20lowest\x20version\x0afor\x20<code>&gt;</code>\x20and\x20<code>&gt;=</code>,\x20and\x20the\x20highest\x20version\x20for\x20<code>&lt;</code>\x20and\x20<code>&lt;=</code>).</li>\x0a<li>A\x20revision\x20identifier\x20for\x20the\x20underlying\x20source\x20repository,\x20such\x20as\x20a\x20commit\x0ahash\x20prefix,\x20revision\x20tag,\x20or\x20branch\x20name.\x20If\x20the\x20revision\x20is\x20tagged\x20with\x20a\x0asemantic\x20version,\x20this\x20query\x20selects\x20that\x20version.\x20Otherwise,\x20this\x20query\x0aselects\x20a\x20<a\x20href=\"#glos-pseudo-version\">pseudo-version</a>\x20for\x20the\x20underlying\x0acommit.\x20Note\x20that\x20branches\x20and\x20tags\x20with\x20names\x20matched\x20by\x20other\x20version\x0aqueries\x20cannot\x20be\x20selected\x20this\x20way.\x20For\x20example,\x20the\x20query\x20<code>v2</code>\x20selects\x20the\x0alatest\x20version\x20starting\x20with\x20<code>v2</code>,\x20not\x20the\x20branch\x20named\x20<code>v2</code>.</li>\x0a<li>The\x20string\x20<code>latest</code>,\x20which\x20selects\x20the\x20highest\x20available\x20release\x20version.\x20If\x0athere\x20are\x20no\x20release\x20versions,\x20<code>latest</code>\x20selects\x20the\x20highest\x20pre-release\x0aversion.\x20\x20If\x20there\x20no\x20tagged\x20versions,\x20<code>latest</code>\x20selects\x20a\x20pseudo-version\x20for\x0athe\x20commit\x20at\x20the\x20tip\x20of\x20the\x20repository's\x20default\x20branch.</li>\x0a<li>The\x20string\x20<code>upgrade</code>,\x20which\x20is\x20like\x20<code>latest</code>\x20except\x20that\x20if\x20the\x20module\x20is\x0acurrently\x20required\x20at\x20a\x20higher\x20version\x20than\x20the\x20version\x20<code>latest</code>\x20would\x20select\x0a(for\x20example,\x20a\x20pre-release),\x20<code>upgrade</code>\x20will\x20select\x20the\x20current\x20version.</li>\x0a<li>The\x20string\x20<code>patch</code>,\x20which\x20selects\x20the\x20latest\x20available\x20version\x20with\x20the\x20same\x0amajor\x20and\x20minor\x20version\x20numbers\x20as\x20the\x20currently\x20required\x20version.\x20If\x20no\x0aversion\x20is\x20currently\x20required,\x20<code>patch</code>\x20is\x20equivalent\x20to\x20<code>latest</code>.</li>\x0a</ul>\x0a<p>Except\x20for\x20queries\x20for\x20specific\x20named\x20versions\x20or\x20revisions,\x20all\x20queries\x0aconsider\x20available\x20versions\x20reported\x20by\x20<code>go\x20list\x20-m\x20-versions</code>\x20(see\x20<a\x20href=\"#go-list-m\"><code>go\x20list\x20-m</code></a>).\x20This\x20list\x20contains\x20only\x20tagged\x20versions,\x20not\x20pseudo-versions.\x0aModule\x20versions\x20disallowed\x20by\x20<a\x20href=\"#go.mod-exclude\">exclude</a>\x20directives\x20in\x0athe\x20main\x20module's\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x20file</a>\x20are\x20not\x20considered.</p>\x0a<p><a\x20href=\"#glos-release-version\">Release\x20versions</a>\x20are\x20preferred\x20over\x20pre-release\x0aversions.\x20For\x20example,\x20if\x20versions\x20<code>v1.2.2</code>\x20and\x20<code>v1.2.3-pre</code>\x20are\x20available,\x20the\x0a<code>latest</code>\x20query\x20will\x20select\x20<code>v1.2.2</code>,\x20even\x20though\x20<code>v1.2.3-pre</code>\x20is\x20higher.\x20The\x0a<code>&lt;v1.2.4</code>\x20query\x20would\x20also\x20select\x20<code>v1.2.2</code>,\x20even\x20though\x20<code>v1.2.3-pre</code>\x20is\x20closer\x0ato\x20<code>v1.2.4</code>.\x20If\x20no\x20release\x20or\x20pre-release\x20version\x20is\x20available,\x20the\x20<code>latest</code>,\x0a<code>upgrade</code>,\x20and\x20<code>patch</code>\x20queries\x20will\x20select\x20a\x20pseudo-version\x20for\x20the\x20commit\x0aat\x20the\x20tip\x20of\x20the\x20repository's\x20default\x20branch.\x20Other\x20queries\x20will\x20report\x0aan\x20error.</p>\x0a<h3\x20id=\"commands-outside\">Module\x20commands\x20outside\x20a\x20module</h3>\x0a<p>Module-aware\x20Go\x20commands\x20normally\x20run\x20in\x20the\x20context\x20of\x20a\x20<a\x20href=\"#glos-main-module\">main\x0amodule</a>\x20defined\x20by\x20a\x20<code>go.mod</code>\x20file\x20in\x20the\x20working\x20directory\x0aor\x20a\x20parent\x20directory.\x20Some\x20commands\x20may\x20be\x20run\x20in\x20module-aware\x20mode\x20without\x20a\x0a<code>go.mod</code>\x20file\x20by\x20setting\x20the\x20<code>GO111MODULE</code>\x20environment\x20variable\x20to\x20<code>on</code>.\x0aMost\x20commands\x20work\x20differently\x20when\x20no\x20<code>go.mod</code>\x20file\x20is\x20present.</p>\x0a<p>See\x20<a\x20href=\"#mod-commands\">Module-aware\x20commands</a>\x20for\x20information\x20on\x20enabling\x20and\x0adisabling\x20module-aware\x20mode.</p>\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Command</th>\x0a\x20\x20\x20\x20\x20\x20<th>Behavior</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20build</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20doc</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20fix</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20fmt</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20generate</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20install</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20list</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20run</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20test</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20vet</code>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Only\x20packages\x20in\x20the\x20standard\x20library\x20and\x20packages\x20specified\x20as\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>.go</code>\x20files\x20on\x20the\x20command\x20line\x20can\x20be\x20loaded,\x20imported,\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20built.\x20Packages\x20from\x20other\x20modules\x20cannot\x20be\x20built,\x20since\x20there\x20is\x20no\x0a\x20\x20\x20\x20\x20\x20\x20\x20place\x20to\x20record\x20module\x20requirements\x20and\x20ensure\x20deterministic\x20builds.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>go\x20get</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Packages\x20and\x20executables\x20may\x20be\x20built\x20and\x20installed\x20as\x20usual.\x20Note\x20that\x0a\x20\x20\x20\x20\x20\x20\x20\x20there\x20is\x20no\x20main\x20module\x20when\x20<code>go\x20get</code>\x20is\x20run\x20without\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go.mod</code>\x20file,\x20so\x20<code>replace</code>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>exclude</code>\x20directives\x20are\x20not\x20applied.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>go\x20list\x20-m</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Explicit\x20<a\x20href=\"#version-queries\">version\x20queries</a>\x20are\x20required\x0a\x20\x20\x20\x20\x20\x20\x20\x20for\x20most\x20arguments,\x20except\x20when\x20the\x20<code>-versions</code>\x20flag\x20is\x20used.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>go\x20mod\x20download</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Explicit\x20<a\x20href=\"#version-queries\">version\x20queries</a>\x20are\x20required\x0a\x20\x20\x20\x20\x20\x20\x20\x20for\x20most\x20arguments.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>go\x20mod\x20edit</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>An\x20explicit\x20file\x20argument\x20is\x20required.</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20graph</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20tidy</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20vendor</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20verify</code><br>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20mod\x20why</code>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20These\x20commands\x20require\x20a\x20<code>go.mod</code>\x20file\x20and\x20will\x20report\x0a\x20\x20\x20\x20\x20\x20\x20\x20an\x20error\x20if\x20one\x20is\x20not\x20present.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<h2\x20id=\"module-proxy\">Module\x20proxies</h2>\x0a<h3\x20id=\"goproxy-protocol\"><code>GOPROXY</code>\x20protocol</h3>\x0a<p>A\x20<a\x20href=\"#glos-module-proxy\"><em>module\x20proxy</em></a>\x20is\x20an\x20HTTP\x20server\x20that\x20can\x20respond\x20to\x0a<code>GET</code>\x20requests\x20for\x20paths\x20specified\x20below.\x20The\x20requests\x20have\x20no\x20query\x20parameters,\x0aand\x20no\x20specific\x20headers\x20are\x20required,\x20so\x20even\x20a\x20site\x20serving\x20from\x20a\x20fixed\x20file\x0asystem\x20(including\x20a\x20<code>file://</code>\x20URL)\x20can\x20be\x20a\x20module\x20proxy.</p>\x0a<p>Successful\x20HTTP\x20responses\x20must\x20have\x20the\x20status\x20code\x20200\x20(OK).\x20Redirects\x20(3xx)\x0aare\x20followed.\x20Responses\x20with\x20status\x20codes\x204xx\x20and\x205xx\x20are\x20treated\x20as\x20errors.\x0aThe\x20error\x20codes\x20404\x20(Not\x20Found)\x20and\x20410\x20(Gone)\x20indicate\x20that\x20the\x0arequested\x20module\x20or\x20version\x20is\x20not\x20available\x20on\x20the\x20proxy,\x20but\x20it\x20may\x20be\x20found\x0aelsewhere.\x20Error\x20responses\x20should\x20have\x20content\x20type\x20<code>text/plain</code>\x20with\x0a<code>charset</code>\x20either\x20<code>utf-8</code>\x20or\x20<code>us-ascii</code>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20be\x20configured\x20to\x20contact\x20proxies\x20or\x20source\x20control\x20servers\x0ausing\x20the\x20<code>GOPROXY</code>\x20environment\x20variable,\x20which\x20is\x20a\x20comma-separated\x20list\x20of\x0aURLs\x20or\x20the\x20keywords\x20<code>direct</code>\x20or\x20<code>off</code>\x20(see\x20<a\x20href=\"#environment-variables\">Environment\x0avariables</a>\x20for\x20details).\x20When\x20the\x20<code>go</code>\x20command\x20receives\x0aa\x20404\x20or\x20410\x20response\x20from\x20a\x20proxy,\x20it\x20falls\x20back\x20to\x20later\x20proxies\x20in\x20the\x0alist.\x20The\x20<code>go</code>\x20command\x20does\x20not\x20fall\x20back\x20to\x20later\x20proxies\x20in\x20response\x20to\x20other\x0a4xx\x20and\x205xx\x20errors.\x20This\x20allows\x20a\x20proxy\x20to\x20act\x20as\x20a\x20gatekeeper,\x20for\x20example,\x20by\x0aresponding\x20with\x20error\x20403\x20(Forbidden)\x20for\x20modules\x20not\x20on\x20an\x20approved\x20list.</p>\x0a<!--\x20TODO(katiehockman):\x20why\x20only\x20fall\x20back\x20for\x20410/404?\x20Either\x20add\x20the\x20details\x0ahere,\x20or\x20write\x20a\x20blog\x20post\x20about\x20how\x20to\x20build\x20multiple\x20types\x20of\x20proxies.\x20e.g.\x0aa\x20\"privacy\x20preserving\x20one\"\x20and\x20an\x20\"authorization\x20one\"\x20-->\x0a<p>The\x20table\x20below\x20specifies\x20queries\x20that\x20a\x20module\x20proxy\x20must\x20respond\x20to.\x20For\x20each\x0apath,\x20<code>$base</code>\x20is\x20the\x20path\x20portion\x20of\x20a\x20proxy\x20URL,<code>$module</code>\x20is\x20a\x20module\x20path,\x20and\x0a<code>$version</code>\x20is\x20a\x20version.\x20For\x20example,\x20if\x20the\x20proxy\x20URL\x20is\x0a<code>https://example.com/mod</code>,\x20and\x20the\x20client\x20is\x20requesting\x20the\x20<code>go.mod</code>\x20file\x20for\x0athe\x20module\x20<code>golang.org/x/text</code>\x20at\x20version\x20<code>v0.3.2</code>,\x20the\x20client\x20would\x20send\x20a\x0a<code>GET</code>\x20request\x20for\x20<code>https://example.com/mod/golang.org/x/text/@v/v0.3.2.mod</code>.</p>\x0a<p>To\x20avoid\x20ambiguity\x20when\x20serving\x20from\x20case-insensitive\x20file\x20systems,\x0athe\x20<code>$module</code>\x20and\x20<code>$version</code>\x20elements\x20are\x20case-encoded\x20by\x20replacing\x20every\x0auppercase\x20letter\x20with\x20an\x20exclamation\x20mark\x20followed\x20by\x20the\x20corresponding\x0alower-case\x20letter.\x20This\x20allows\x20modules\x20<code>example.com/M</code>\x20and\x20<code>example.com/m</code>\x20to\x0aboth\x20be\x20stored\x20on\x20disk,\x20since\x20the\x20former\x20is\x20encoded\x20as\x20<code>example.com/!m</code>.</p>\x0a<!--\x20TODO(jayconrod):\x20This\x20table\x20has\x20multi-line\x20cells,\x20and\x20GitHub\x20Flavored\x0aMarkdown\x20doesn't\x20have\x20syntax\x20for\x20that,\x20so\x20we\x20use\x20raw\x20HTML.\x20Gitiles\x20doesn't\x0ainclude\x20this\x20table\x20in\x20the\x20rendered\x20HTML.\x20Once\x20x/website\x20has\x20a\x20Markdown\x20renderer,\x0aensure\x20this\x20table\x20is\x20readable.\x20If\x20the\x20cells\x20are\x20too\x20large,\x20and\x20it's\x20difficult\x0ato\x20scan,\x20use\x20paragraphs\x20or\x20sections\x20below.\x0a-->\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Path</th>\x0a\x20\x20\x20\x20\x20\x20<th>Description</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@v/list</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20a\x20list\x20of\x20known\x20versions\x20of\x20the\x20given\x20module\x20in\x20plain\x20text,\x20one\x0a\x20\x20\x20\x20\x20\x20\x20\x20per\x20line.\x20This\x20list\x20should\x20not\x20include\x20pseudo-versions.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@v/$version.info</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20JSON-formatted\x20metadata\x20about\x20a\x20specific\x20version\x20of\x20a\x20module.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20response\x20must\x20be\x20a\x20JSON\x20object\x20that\x20corresponds\x20to\x20the\x20Go\x20data\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20structure\x20below:\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<pre>\x0atype\x20Info\x20struct\x20{\x0a\x20\x20\x20\x20Version\x20string\x20\x20\x20\x20//\x20version\x20string\x0a\x20\x20\x20\x20Time\x20\x20\x20\x20time.Time\x20//\x20commit\x20time\x0a}\x0a</pre>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20<code>Version</code>\x20field\x20is\x20required\x20and\x20must\x20contain\x20a\x20valid,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#glos-canonical-version\">canonical\x20version</a>\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#versions\">Versions</a>).\x20The\x20<code>$version</code>\x20in\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20request\x20path\x20does\x20not\x20need\x20to\x20be\x20the\x20same\x20version\x20or\x20even\x20a\x20valid\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20version;\x20this\x20endpoint\x20may\x20be\x20used\x20to\x20find\x20versions\x20for\x20branch\x20names\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20or\x20revision\x20identifiers.\x20However,\x20if\x20<code>$version</code>\x20is\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20canonical\x20version\x20with\x20a\x20major\x20version\x20compatible\x20with\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>$module</code>,\x20the\x20<code>Version</code>\x20field\x20in\x20a\x20successful\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20response\x20must\x20be\x20the\x20same.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20<code>Time</code>\x20field\x20is\x20optional.\x20If\x20present,\x20it\x20must\x20be\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20string\x20in\x20RFC\x203339\x20format.\x20It\x20indicates\x20the\x20time\x20when\x20the\x20version\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20was\x20created.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20More\x20fields\x20may\x20be\x20added\x20in\x20the\x20future,\x20so\x20other\x20names\x20are\x20reserved.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@v/$version.mod</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20the\x20<code>go.mod</code>\x20file\x20for\x20a\x20specific\x20version\x20of\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20module.\x20If\x20the\x20module\x20does\x20not\x20have\x20a\x20<code>go.mod</code>\x20file\x20at\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20requested\x20version,\x20a\x20file\x20containing\x20only\x20a\x20<code>module</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20statement\x20with\x20the\x20requested\x20module\x20path\x20must\x20be\x20returned.\x20Otherwise,\x0a\x20\x20\x20\x20\x20\x20\x20\x20the\x20original,\x20unmodified\x20<code>go.mod</code>\x20file\x20must\x20be\x20returned.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@v/$version.zip</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20a\x20zip\x20file\x20containing\x20the\x20contents\x20of\x20a\x20specific\x20version\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20a\x20module.\x20See\x20<a\x20href=\"#zip-files\">Module\x20zip\x20files</a>\x20for\x20details\x0a\x20\x20\x20\x20\x20\x20\x20\x20on\x20how\x20this\x20zip\x20file\x20must\x20be\x20formatted.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/$module/@latest</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20JSON-formatted\x20metadata\x20about\x20the\x20latest\x20known\x20version\x20of\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20module\x20in\x20the\x20same\x20format\x20as\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>$base/$module/@v/$version.info</code>.\x20The\x20latest\x20version\x20should\x0a\x20\x20\x20\x20\x20\x20\x20\x20be\x20the\x20version\x20of\x20the\x20module\x20that\x20the\x20<code>go</code>\x20command\x20should\x20use\x0a\x20\x20\x20\x20\x20\x20\x20\x20if\x20<code>$base/$module/@v/list</code>\x20is\x20empty\x20or\x20no\x20listed\x20version\x20is\x0a\x20\x20\x20\x20\x20\x20\x20\x20suitable.\x20This\x20endpoint\x20is\x20optional,\x20and\x20module\x20proxies\x20are\x20not\x20required\x0a\x20\x20\x20\x20\x20\x20\x20\x20to\x20implement\x20it.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<p>When\x20resolving\x20the\x20latest\x20version\x20of\x20a\x20module,\x20the\x20<code>go</code>\x20command\x20will\x20request\x0a<code>$base/$module/@v/list</code>,\x20then,\x20if\x20no\x20suitable\x20versions\x20are\x20found,\x0a<code>$base/$module/@latest</code>.\x20The\x20<code>go</code>\x20command\x20prefers,\x20in\x20order:\x20the\x20semantically\x0ahighest\x20release\x20version,\x20the\x20semantically\x20highest\x20pre-release\x20version,\x20and\x20the\x0achronologically\x20most\x20recent\x20pseudo-version.\x20In\x20Go\x201.12\x20and\x20earlier,\x20the\x20<code>go</code>\x0acommand\x20considered\x20pseudo-versions\x20in\x20<code>$base/$module/@v/list</code>\x20to\x20be\x20pre-release\x0aversions,\x20but\x20this\x20is\x20no\x20longer\x20true\x20since\x20Go\x201.13.</p>\x0a<p>A\x20module\x20proxy\x20must\x20always\x20serve\x20the\x20same\x20content\x20for\x20successful\x0aresponses\x20for\x20<code>$base/$module/$version.mod</code>\x20and\x20<code>$base/$module/$version.zip</code>\x0aqueries.\x20This\x20content\x20is\x20<a\x20href=\"#authenticating\">cryptographically\x20authenticated</a>\x0ausing\x20<a\x20href=\"#go.sum-files\"><code>go.sum</code>\x20files</a>\x20and,\x20by\x20default,\x20the\x0a<a\x20href=\"#checksum-database\">checksum\x20database</a>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20caches\x20most\x20content\x20it\x20downloads\x20from\x20module\x20proxies\x20in\x20its\x0amodule\x20cache\x20in\x20<code>$GOPATH/pkg/mod/cache/download</code>.\x20Even\x20when\x20downloading\x20directly\x0afrom\x20version\x20control\x20systems,\x20the\x20<code>go</code>\x20command\x20synthesizes\x20explicit\x20<code>info</code>,\x0a<code>mod</code>,\x20and\x20<code>zip</code>\x20files\x20and\x20stores\x20them\x20in\x20this\x20directory,\x20the\x20same\x20as\x20if\x20it\x20had\x0adownloaded\x20them\x20directly\x20from\x20a\x20proxy.\x20The\x20cache\x20layout\x20is\x20the\x20same\x20as\x20the\x20proxy\x0aURL\x20space,\x20so\x20serving\x20<code>$GOPATH/pkg/mod/cache/download</code>\x20at\x20(or\x20copying\x20it\x20to)\x0a<code>https://example.com/proxy</code>\x20would\x20let\x20users\x20access\x20cached\x20module\x20versions\x20by\x0asetting\x20<code>GOPROXY</code>\x20to\x20<code>https://example.com/proxy</code>.</p>\x0a<h3\x20id=\"communicating-with-proxies\">Communicating\x20with\x20proxies</h3>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20download\x20module\x20source\x20code\x20and\x20metadata\x20from\x20a\x20<a\x20href=\"#glos-module-proxy\">module\x0aproxy</a>.\x20The\x20<code>GOPROXY</code>\x20<a\x20href=\"#environment-variables\">environment\x0avariable</a>\x20may\x20be\x20used\x20to\x20configure\x20which\x20proxies\x20the\x0a<code>go</code>\x20command\x20may\x20connect\x20to\x20and\x20whether\x20it\x20may\x20communicate\x20directly\x20with\x0a<a\x20href=\"#vcs\">version\x20control\x20systems</a>.\x20Downloaded\x20module\x20data\x20is\x20saved\x20in\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>.\x20The\x20<code>go</code>\x20command\x20will\x20only\x20contact\x20a\x20proxy\x20when\x20it\x0aneeds\x20information\x20not\x20already\x20in\x20the\x20cache.</p>\x0a<p>The\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>\x20section\x20describes\x20requests\x20that\x0amay\x20be\x20sent\x20to\x20a\x20<code>GOPROXY</code>\x20server.\x20However,\x20it's\x20also\x20helpful\x20to\x20understand\x0awhen\x20the\x20<code>go</code>\x20command\x20makes\x20these\x20requests.\x20For\x20example,\x20<code>go\x20build</code>\x20follows\x0athe\x20procedure\x20below:</p>\x0a<ul>\x0a<li>Compute\x20the\x20<a\x20href=\"#glos-build-list\">build\x20list</a>\x20by\x20reading\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x0afiles</a>\x20and\x20performing\x20<a\x20href=\"#glos-minimal-version-selection\">minimal\x20version\x20selection\x0a(MVS)</a>.</li>\x0a<li>Read\x20the\x20packages\x20named\x20on\x20the\x20command\x20line\x20and\x20the\x20packages\x20they\x20import.</li>\x0a<li>If\x20a\x20package\x20is\x20not\x20provided\x20by\x20any\x20module\x20in\x20the\x20build\x20list,\x20find\x20a\x20module\x0athat\x20provides\x20it.\x20Add\x20a\x20module\x20requirement\x20on\x20its\x20latest\x20version\x20to\x20<code>go.mod</code>,\x0aand\x20start\x20over.</li>\x0a<li>Build\x20packages\x20after\x20everything\x20is\x20loaded.</li>\x0a</ul>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20computes\x20the\x20build\x20list,\x20it\x20loads\x20the\x20<code>go.mod</code>\x20file\x20for\x0aeach\x20module\x20in\x20the\x20<a\x20href=\"#glos-module-graph\">module\x20graph</a>.\x20If\x20a\x20<code>go.mod</code>\x20file\x20is\x20not\x0ain\x20the\x20cache,\x20the\x20<code>go</code>\x20command\x20will\x20download\x20it\x20from\x20the\x20proxy\x20using\x20a\x0a<code>$module/@v/$version.mod</code>\x20request\x20(where\x20<code>$module</code>\x20is\x20the\x20module\x20path\x20and\x0a<code>$version</code>\x20is\x20the\x20version).\x20These\x20requests\x20can\x20be\x20tested\x20with\x20a\x20tool\x20like\x0a<code>curl</code>.\x20For\x20example,\x20the\x20command\x20below\x20downloads\x20the\x20<code>go.mod</code>\x20file\x20for\x0a<code>golang.org/x/mod</code>\x20at\x20version\x20<code>v0.2.0</code>:</p>\x0a<pre><code>$\x20curl\x20https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.mod\x0amodule\x20golang.org/x/mod\x0a\x0ago\x201.12\x0a\x0arequire\x20(\x0a\x09golang.org/x/crypto\x20v0.0.0-20191011191535-87dc89f01550\x0a\x09golang.org/x/tools\x20v0.0.0-20191119224855-298f0cb1881e\x0a\x09golang.org/x/xerrors\x20v0.0.0-20191011141410-1b5146add898\x0a)\x0a</code></pre>\x0a<p>In\x20order\x20to\x20load\x20a\x20package,\x20the\x20<code>go</code>\x20command\x20needs\x20the\x20source\x20code\x20for\x20the\x0amodule\x20that\x20provides\x20it.\x20Module\x20source\x20code\x20is\x20distributed\x20in\x20<code>.zip</code>\x20files\x20which\x0aare\x20extracted\x20into\x20the\x20module\x20cache.\x20If\x20a\x20module\x20<code>.zip</code>\x20is\x20not\x20in\x20the\x20cache,\x0athe\x20<code>go</code>\x20command\x20will\x20download\x20it\x20using\x20a\x20<code>$module/@v/$version.zip</code>\x20request.</p>\x0a<pre><code>$\x20curl\x20-O\x20https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.zip\x0a$\x20unzip\x20-l\x20v0.2.0.zip\x20|\x20head\x0aArchive:\x20\x20v0.2.0.zip\x0a\x20\x20Length\x20\x20\x20\x20\x20\x20Date\x20\x20\x20\x20Time\x20\x20\x20\x20Name\x0a---------\x20\x20----------\x20-----\x20\x20\x20----\x0a\x20\x20\x20\x20\x201479\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/LICENSE\x0a\x20\x20\x20\x20\x201303\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/PATENTS\x0a\x20\x20\x20\x20\x20\x20559\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/README\x0a\x20\x20\x20\x20\x20\x20\x2021\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/codereview.cfg\x0a\x20\x20\x20\x20\x20\x20214\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/go.mod\x0a\x20\x20\x20\x20\x201476\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/go.sum\x0a\x20\x20\x20\x20\x205224\x20\x2000-00-1980\x2000:00\x20\x20\x20golang.org/x/mod@v0.2.0/gosumcheck/main.go\x0a</code></pre>\x0a<p>Note\x20that\x20<code>.mod</code>\x20and\x20<code>.zip</code>\x20requests\x20are\x20separate,\x20even\x20though\x20<code>go.mod</code>\x20files\x0aare\x20usually\x20contained\x20within\x20<code>.zip</code>\x20files.\x20The\x20<code>go</code>\x20command\x20may\x20need\x20to\x20download\x0a<code>go.mod</code>\x20files\x20for\x20many\x20different\x20modules,\x20and\x20<code>.mod</code>\x20files\x20are\x20much\x20smaller\x0athan\x20<code>.zip</code>\x20files.\x20Additionally,\x20if\x20a\x20Go\x20project\x20does\x20not\x20have\x20a\x20<code>go.mod</code>\x20file,\x0athe\x20proxy\x20will\x20serve\x20a\x20synthetic\x20<code>go.mod</code>\x20file\x20that\x20only\x20contains\x20a\x20<a\x20href=\"#go.mod-module\"><code>module</code>\x0adirective</a>.\x20Synthetic\x20<code>go.mod</code>\x20files\x20are\x20generated\x20by\x20the\x20<code>go</code>\x0acommand\x20when\x20downloading\x20from\x20a\x20<a\x20href=\"#vcs\">version\x20control\x0asystem</a>.</p>\x0a<p>If\x20the\x20<code>go</code>\x20command\x20needs\x20to\x20load\x20a\x20package\x20not\x20provided\x20by\x20any\x20module\x20in\x20the\x0abuild\x20list,\x20it\x20will\x20attempt\x20to\x20find\x20a\x20new\x20module\x20that\x20provides\x20it.\x20The\x20section\x0a<a\x20href=\"#resolve-pkg-mod\">Resolving\x20a\x20package\x20to\x20a\x20module</a>\x20describes\x20this\x20process.\x20In\x0asummary,\x20the\x20<code>go</code>\x20command\x20requests\x20information\x20about\x20the\x20latest\x20version\x20of\x20each\x0amodule\x20path\x20that\x20could\x20possibly\x20contain\x20the\x20package.\x20For\x20example,\x20for\x20the\x0apackage\x20<code>golang.org/x/net/html</code>,\x20the\x20<code>go</code>\x20command\x20would\x20try\x20to\x20find\x20the\x20latest\x0aversions\x20of\x20the\x20modules\x20<code>golang.org/x/net/html</code>,\x20<code>golang.org/x/net</code>,\x0a<code>golang.org/x/</code>,\x20and\x20<code>golang.org</code>.\x20Only\x20<code>golang.org/x/net</code>\x20actually\x20exists\x20and\x0aprovides\x20that\x20package,\x20so\x20the\x20<code>go</code>\x20command\x20uses\x20the\x20latest\x20version\x20of\x20that\x0amodule.\x20If\x20more\x20than\x20one\x20module\x20provides\x20the\x20package,\x20the\x20<code>go</code>\x20command\x20will\x20use\x0athe\x20module\x20with\x20the\x20longest\x20path.</p>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20requests\x20the\x20latest\x20version\x20of\x20a\x20module,\x20it\x20first\x20sends\x20a\x0arequest\x20for\x20<code>$module/@v/list</code>.\x20If\x20the\x20list\x20is\x20empty\x20or\x20none\x20of\x20the\x20returned\x0aversions\x20can\x20be\x20used,\x20it\x20sends\x20a\x20request\x20for\x20<code>$module/@latest</code>.\x20Once\x20a\x20version\x0ais\x20chosen,\x20the\x20<code>go</code>\x20command\x20sends\x20a\x20<code>$module/@v/$version.info</code>\x20request\x20for\x0ametadata.\x20It\x20may\x20then\x20send\x20<code>$module/@v/$version.mod</code>\x20and\x0a<code>$module/@v/$version.zip</code>\x20requests\x20to\x20load\x20the\x20<code>go.mod</code>\x20file\x20and\x20source\x20code.</p>\x0a<pre><code>$\x20curl\x20https://proxy.golang.org/golang.org/x/mod/@v/list\x0av0.1.0\x0av0.2.0\x0a\x0a$\x20curl\x20https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.info\x0a{&quot;Version&quot;:&quot;v0.2.0&quot;,&quot;Time&quot;:&quot;2020-01-02T17:33:45Z&quot;}\x0a</code></pre>\x0a<p>After\x20downloading\x20a\x20<code>.mod</code>\x20or\x20<code>.zip</code>\x20file,\x20the\x20<code>go</code>\x20command\x20computes\x20a\x0acryptographic\x20hash\x20and\x20checks\x20that\x20it\x20matches\x20a\x20hash\x20in\x20the\x20main\x20module's\x0a<code>go.sum</code>\x20file.\x20If\x20the\x20hash\x20is\x20not\x20present\x20in\x20<code>go.sum</code>,\x20by\x20default,\x20the\x20<code>go</code>\x0acommand\x20retrieves\x20it\x20from\x20the\x20<a\x20href=\"#checksum-database\">checksum\x20database</a>.\x20If\x20the\x0acomputed\x20hash\x20does\x20not\x20match,\x20the\x20<code>go</code>\x20command\x20reports\x20a\x20security\x20error\x20and\x20does\x0anot\x20install\x20the\x20file\x20in\x20the\x20module\x20cache.\x20The\x20<code>GOPRIVATE</code>\x20and\x20<code>GONOSUMDB</code>\x0a<a\x20href=\"#environment-variables\">environment\x20variables</a>\x20may\x20be\x20used\x20to\x20disable\x20requests\x0ato\x20the\x20checksum\x20database\x20for\x20specific\x20modules.\x20The\x20<code>GOSUMDB</code>\x20environment\x0avariable\x20may\x20also\x20be\x20set\x20to\x20<code>off</code>\x20to\x20disable\x20requests\x20to\x20the\x20checksum\x20database\x0aentirely.\x20See\x20<a\x20href=\"#authenticating\">Authenticating\x20modules</a>\x20for\x20more\x0ainformation.\x20Note\x20that\x20version\x20lists\x20and\x20version\x20metadata\x20returned\x20for\x20<code>.info</code>\x0arequests\x20are\x20not\x20authenticated\x20and\x20may\x20change\x20over\x20time.</p>\x0a<h2\x20id=\"vcs\">Version\x20control\x20systems</h2>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20download\x20module\x20source\x20code\x20and\x20metadata\x20directly\x20from\x20a\x0aversion\x20control\x20repository.\x20Downloading\x20a\x20module\x20from\x20a\x0a<a\x20href=\"#communicating-with-proxies\">proxy</a>\x20is\x20usually\x20faster,\x20but\x20connecting\x20directly\x0ato\x20a\x20repository\x20is\x20necessary\x20if\x20a\x20proxy\x20is\x20not\x20available\x20or\x20if\x20a\x20module's\x0arepository\x20is\x20not\x20accessible\x20to\x20a\x20proxy\x20(frequently\x20true\x20for\x20private\x0arepositories).\x20Git,\x20Subversion,\x20Mercurial,\x20Bazaar,\x20and\x20Fossil\x20are\x20supported.\x20A\x0aversion\x20control\x20tool\x20must\x20be\x20installed\x20in\x20a\x20directory\x20in\x20<code>PATH</code>\x20in\x20order\x20for\x20the\x0a<code>go</code>\x20command\x20to\x20use\x20it.</p>\x0a<p>To\x20download\x20specific\x20modules\x20from\x20source\x20repositories\x20instead\x20of\x20a\x20proxy,\x20set\x0athe\x20<code>GOPRIVATE</code>\x20or\x20<code>GONOPROXY</code>\x20environment\x20variables.\x20To\x20configure\x20the\x20<code>go</code>\x0acommand\x20to\x20download\x20all\x20modules\x20directly\x20from\x20source\x20repositories,\x20set\x20<code>GOPROXY</code>\x0ato\x20<code>direct</code>.\x20See\x20<a\x20href=\"#environment-variables\">Environment\x20variables</a>\x20for\x20more\x0ainformation.</p>\x0a<h3\x20id=\"vcs-find\">Finding\x20a\x20repository\x20for\x20a\x20module\x20path</h3>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20downloads\x20a\x20module\x20in\x20<code>direct</code>\x20mode,\x20it\x20starts\x20by\x20locating\x0athe\x20repository\x20that\x20contains\x20the\x20module.\x20The\x20<code>go</code>\x20command\x20sends\x20an\x0aHTTP\x20<code>GET</code>\x20request\x20to\x20a\x20URL\x20derived\x20from\x20the\x20module\x20path\x20with\x20a\x0a<code>?go-get=1</code>\x20query\x20string.\x20For\x20example,\x20for\x20the\x20module\x20<code>golang.org/x/mod</code>,\x0athe\x20<code>go</code>\x20command\x20may\x20send\x20the\x20following\x20requests:</p>\x0a<pre><code>https://golang.org/x/mod?go-get=1\x20(preferred)\x0ahttp://golang.org/x/mod?go-get=1\x20\x20(fallback,\x20only\x20with\x20GOINSECURE)\x0a</code></pre>\x0a<p>The\x20<code>go</code>\x20command\x20will\x20follow\x20redirects\x20but\x20otherwise\x20ignores\x20response\x20status\x0acodes,\x20so\x20the\x20server\x20may\x20respond\x20with\x20a\x20404\x20or\x20any\x20other\x20error\x20status.\x20The\x0a<code>GOINSECURE</code>\x20environment\x20variable\x20may\x20be\x20set\x20to\x20allow\x20fallback\x20and\x20redirects\x20to\x0aunencrypted\x20HTTP\x20for\x20specific\x20modules.</p>\x0a<p>The\x20server\x20must\x20respond\x20with\x20an\x20HTML\x20document\x20containing\x20a\x20<code>&lt;meta&gt;</code>\x20tag\x20in\x20the\x0adocument's\x20<code>&lt;head&gt;</code>.\x20The\x20<code>&lt;meta&gt;</code>\x20tag\x20should\x20appear\x20early\x20in\x20the\x20document\x20to\x0aavoid\x20confusing\x20the\x20<code>go</code>\x20command's\x20restricted\x20parser.\x20In\x20particular,\x20it\x20should\x0aappear\x20before\x20any\x20raw\x20JavaScript\x20or\x20CSS.\x20The\x20<code>&lt;meta&gt;</code>\x20tag\x20must\x20have\x20the\x20form:</p>\x0a<pre><code>&lt;meta\x20name=&quot;go-import&quot;\x20content=&quot;root-path\x20vcs\x20repo-url&quot;&gt;\x0a</code></pre>\x0a<p><code>root-path</code>\x20is\x20the\x20repository\x20root\x20path,\x20the\x20portion\x20of\x20the\x20module\x20path\x20that\x0acorresponds\x20to\x20the\x20repository's\x20root\x20directory.\x20It\x20must\x20be\x20a\x20prefix\x20or\x20an\x20exact\x0amatch\x20of\x20the\x20requested\x20module\x20path.\x20If\x20it's\x20not\x20an\x20exact\x20match,\x20another\x20request\x0ais\x20made\x20for\x20the\x20prefix\x20to\x20verify\x20the\x20<code>&lt;meta&gt;</code>\x20tags\x20match.</p>\x0a<p><code>vcs</code>\x20is\x20the\x20version\x20control\x20system.\x20It\x20must\x20be\x20one\x20of\x20<code>bzr</code>,\x20<code>fossil</code>,\x20<code>git</code>,\x0a<code>hg</code>,\x20<code>svn</code>,\x20<code>mod</code>.\x20The\x20<code>mod</code>\x20scheme\x20instructs\x20the\x20<code>go</code>\x20command\x20to\x20download\x20the\x0amodule\x20from\x20the\x20given\x20URL\x20using\x20the\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x0aprotocol</a>.\x20This\x20allows\x20developers\x20to\x20distribute\x20modules\x0awithout\x20exposing\x20source\x20repositories.</p>\x0a<p><code>repo-url</code>\x20is\x20the\x20repository's\x20URL.\x20If\x20the\x20URL\x20does\x20not\x20include\x20a\x20scheme,\x20the\x0a<code>go</code>\x20command\x20will\x20try\x20each\x20protocol\x20supported\x20by\x20the\x20version\x20control\x20system.\x0aFor\x20example,\x20with\x20Git,\x20the\x20<code>go</code>\x20command\x20will\x20try\x20<code>https://</code>\x20then\x20<code>git+ssh://</code>.\x0aInsecure\x20protocols\x20may\x20only\x20be\x20used\x20if\x20the\x20module\x20path\x20is\x20matched\x20by\x20the\x0a<code>GOINSECURE</code>\x20environment\x20variable.</p>\x0a<p>As\x20an\x20example,\x20consider\x20<code>golang.org/x/mod</code>\x20again.\x20The\x20<code>go</code>\x20command\x20sends\x0aa\x20request\x20to\x20<code>https://golang.org/x/mod?go-get=1</code>.\x20The\x20server\x20responds\x0awith\x20an\x20HTML\x20document\x20containing\x20the\x20tag:</p>\x0a<pre><code>&lt;meta\x20name=&quot;go-import&quot;\x20content=&quot;golang.org/x/mod\x20git\x20https://go.googlesource.com/mod&quot;&gt;\x0a</code></pre>\x0a<p>From\x20this\x20response,\x20the\x20<code>go</code>\x20command\x20will\x20use\x20the\x20Git\x20repository\x20at\x0athe\x20remote\x20URL\x20<code>https://go.googlesource.com/mod</code>.</p>\x0a<p>GitHub\x20and\x20other\x20popular\x20hosting\x20services\x20respond\x20to\x20<code>?go-get=1</code>\x20queries\x20for\x0aall\x20repositories,\x20so\x20usually\x20no\x20server\x20configuration\x20is\x20necessary\x20for\x20modules\x0ahosted\x20at\x20those\x20sites.</p>\x0a<p>After\x20the\x20repository\x20URL\x20is\x20found,\x20the\x20<code>go</code>\x20command\x20will\x20clone\x20the\x20repository\x0ainto\x20the\x20module\x20cache.\x20In\x20general,\x20the\x20<code>go</code>\x20command\x20tries\x20to\x20avoid\x20fetching\x0aunneeded\x20data\x20from\x20a\x20repository.\x20However,\x20the\x20actual\x20commands\x20used\x20vary\x20by\x0aversion\x20control\x20system\x20and\x20may\x20change\x20over\x20time.\x20For\x20Git,\x20the\x20<code>go</code>\x20command\x20can\x0alist\x20most\x20available\x20versions\x20without\x20downloading\x20commits.\x20It\x20will\x20usually\x20fetch\x0acommits\x20without\x20downloading\x20ancestor\x20commits,\x20but\x20doing\x20so\x20is\x20sometimes\x0anecessary.</p>\x0a<h3\x20id=\"vcs-version\">Mapping\x20versions\x20to\x20commits</h3>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20check\x20out\x20a\x20module\x20within\x20a\x20repository\x20at\x20a\x20specific\x0a<a\x20href=\"#glos-canonical-version\">canonical\x20version</a>\x20like\x20<code>v1.2.3</code>,\x20<code>v2.4.0-beta</code>,\x20or\x0a<code>v3.0.0+incompatible</code>.\x20Each\x20module\x20version\x20should\x20have\x20a\x20<dfn>semantic\x20version\x0atag</dfn>\x20within\x20the\x20repository\x20that\x20indicates\x20which\x20revision\x20should\x20be\x20checked\x0aout\x20for\x20a\x20given\x20version.</p>\x0a<p>If\x20a\x20module\x20is\x20defined\x20in\x20the\x20repository\x20root\x20directory\x20or\x20in\x20a\x20major\x20version\x0asubdirectory\x20of\x20the\x20root\x20directory,\x20then\x20each\x20version\x20tag\x20name\x20is\x20equal\x20to\x20the\x0acorresponding\x20version.\x20For\x20example,\x20the\x20module\x20<code>golang.org/x/text</code>\x20is\x20defined\x20in\x0athe\x20root\x20directory\x20of\x20its\x20repository,\x20so\x20the\x20version\x20<code>v0.3.2</code>\x20has\x20the\x20tag\x0a<code>v0.3.2</code>\x20in\x20that\x20repository.\x20This\x20is\x20true\x20for\x20most\x20modules.</p>\x0a<p>If\x20a\x20module\x20is\x20defined\x20in\x20a\x20subdirectory\x20within\x20the\x20repository,\x20that\x20is,\x20the\x0a<a\x20href=\"#glos-module-subdirectory\">module\x20subdirectory</a>\x20portion\x20of\x20the\x20module\x20path\x20is\x0anot\x20empty,\x20then\x20each\x20tag\x20name\x20must\x20be\x20prefixed\x20with\x20the\x20module\x20subdirectory,\x0afollowed\x20by\x20a\x20slash.\x20For\x20example,\x20the\x20module\x20<code>golang.org/x/tools/gopls</code>\x20is\x0adefined\x20in\x20the\x20<code>gopls</code>\x20subdirectory\x20of\x20the\x20repository\x20with\x20root\x20path\x0a<code>golang.org/x/tools</code>.\x20The\x20version\x20<code>v0.4.0</code>\x20of\x20that\x20module\x20must\x20have\x20the\x20tag\x0anamed\x20<code>gopls/v0.4.0</code>\x20in\x20that\x20repository.</p>\x0a<p>The\x20major\x20version\x20number\x20of\x20a\x20semantic\x20version\x20tag\x20must\x20be\x20consistent\x20with\x20the\x0amodule\x20path's\x20major\x20version\x20suffix\x20(if\x20any).\x20For\x20example,\x20the\x20tag\x20<code>v1.0.0</code>\x20could\x0abelong\x20to\x20the\x20module\x20<code>example.com/mod</code>\x20but\x20not\x20<code>example.com/mod/v2</code>,\x20which\x20would\x0ahave\x20tags\x20like\x20<code>v2.0.0</code>.</p>\x0a<p>A\x20tag\x20with\x20major\x20version\x20<code>v2</code>\x20or\x20higher\x20may\x20belong\x20to\x20a\x20module\x20without\x20a\x20major\x0aversion\x20suffix\x20if\x20no\x20<code>go.mod</code>\x20file\x20is\x20present,\x20and\x20the\x20module\x20is\x20in\x20the\x0arepository\x20root\x20directory.\x20This\x20kind\x20of\x20version\x20is\x20denoted\x20with\x20the\x20suffix\x0a<code>+incompatible</code>.\x20The\x20version\x20tag\x20itself\x20must\x20not\x20have\x20the\x20suffix.\x20See\x0a<a\x20href=\"#non-module-compat\">Compatibility\x20with\x20non-module\x20repositories</a>.</p>\x0a<p>Once\x20a\x20tag\x20is\x20created,\x20it\x20should\x20not\x20be\x20deleted\x20or\x20changed\x20to\x20a\x20different\x0arevision.\x20Versions\x20are\x20<a\x20href=\"#authenticating\">authenticated</a>\x20to\x20ensure\x20safe,\x0arepeatable\x20builds.\x20If\x20a\x20tag\x20is\x20modified,\x20clients\x20may\x20see\x20a\x20security\x20error\x20when\x0adownloading\x20it.\x20Even\x20after\x20a\x20tag\x20is\x20deleted,\x20its\x20content\x20may\x20remain\x0aavailable\x20on\x20<a\x20href=\"#glos-module-proxy\">module\x20proxies</a>.</p>\x0a<h3\x20id=\"vcs-pseudo\">Mapping\x20pseudo-versions\x20to\x20commits</h3>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20check\x20out\x20a\x20module\x20within\x20a\x20repository\x20at\x20a\x20specific\x0arevision,\x20encoded\x20as\x20a\x20<a\x20href=\"#glos-pseudo-version\">pseudo-version</a>\x20like\x0a<code>v1.3.2-0.20191109021931-daa7c04131f5</code>.</p>\x0a<p>The\x20last\x2012\x20characters\x20of\x20the\x20pseudo-version\x20(<code>daa7c04131f5</code>\x20in\x20the\x20example\x0aabove)\x20indicate\x20a\x20revision\x20in\x20the\x20repository\x20to\x20check\x20out.\x20The\x20meaning\x20of\x20this\x0adepends\x20on\x20the\x20version\x20control\x20system.\x20For\x20Git\x20and\x20Mercurial,\x20this\x20is\x20a\x20prefix\x0aof\x20a\x20commit\x20hash.\x20For\x20Subversion,\x20this\x20is\x20a\x20zero-padded\x20revision\x20number.</p>\x0a<p>Before\x20checking\x20out\x20a\x20commit,\x20the\x20<code>go</code>\x20command\x20verifies\x20that\x20the\x20timestamp\x0a(<code>20191109021931</code>\x20above)\x20matches\x20the\x20commit\x20date.\x20It\x20also\x20verifies\x20that\x20the\x20base\x0aversion\x20(<code>v1.3.1</code>,\x20the\x20version\x20before\x20<code>v1.3.2</code>\x20in\x20the\x20example\x20above)\x20corresponds\x0ato\x20a\x20semantic\x20version\x20tag\x20that\x20is\x20an\x20ancestor\x20of\x20the\x20commit.\x20These\x20checks\x20ensure\x0athat\x20module\x20authors\x20have\x20full\x20control\x20over\x20how\x20pseudo-versions\x20compare\x20with\x0aother\x20released\x20versions.</p>\x0a<p>See\x20<a\x20href=\"#pseudo-versions\">Pseudo-versions</a>\x20for\x20more\x20information.</p>\x0a<h3\x20id=\"vcs-branch\">Mapping\x20branches\x20and\x20commits\x20to\x20versions</h3>\x0a<p>A\x20module\x20may\x20be\x20checked\x20out\x20at\x20a\x20specific\x20branch,\x20tag,\x20or\x20revision\x20using\x20a\x0a<a\x20href=\"#version-queries\">version\x20query</a>.</p>\x0a<pre><code>go\x20get\x20example.com/mod@master\x0a</code></pre>\x0a<p>The\x20<code>go</code>\x20command\x20converts\x20these\x20names\x20into\x20<a\x20href=\"#glos-canonical-version\">canonical\x0aversions</a>\x20that\x20can\x20be\x20used\x20with\x20<a\x20href=\"#minimal-version-selection\">minimal\x20version\x0aselection\x20(MVS)</a>.\x20MVS\x20depends\x20on\x20the\x20ability\x20to\x0aorder\x20versions\x20unambiguously.\x20Branch\x20names\x20and\x20revisions\x20can't\x20be\x20compared\x0areliably\x20over\x20time,\x20since\x20they\x20depend\x20on\x20repository\x20structure\x20which\x20may\x20change.</p>\x0a<p>If\x20a\x20revision\x20is\x20tagged\x20with\x20one\x20or\x20more\x20semantic\x20version\x20tags\x20like\x20<code>v1.2.3</code>,\x0athe\x20tag\x20for\x20the\x20highest\x20valid\x20version\x20will\x20be\x20used.\x20The\x20<code>go</code>\x20command\x20only\x0aconsiders\x20semantic\x20version\x20tags\x20that\x20could\x20belong\x20to\x20the\x20target\x20module;\x20for\x0aexample,\x20the\x20tag\x20<code>v1.5.2</code>\x20would\x20not\x20be\x20considered\x20for\x20<code>example.com/mod/v2</code>\x20since\x0athe\x20major\x20version\x20doesn't\x20match\x20the\x20module\x20path's\x20suffix.</p>\x0a<p>If\x20a\x20revision\x20is\x20not\x20tagged\x20with\x20a\x20valid\x20semantic\x20version\x20tag,\x20the\x20<code>go</code>\x20command\x0awill\x20generate\x20a\x20<a\x20href=\"#glos-pseudo-version\">pseudo-version</a>.\x20If\x20the\x20revision\x20has\x0aancestors\x20with\x20valid\x20semantic\x20version\x20tags,\x20the\x20highest\x20ancestor\x20version\x20will\x20be\x0aused\x20as\x20the\x20pseudo-version\x20base.\x20See\x20<a\x20href=\"#pseudo-versions\">Pseudo-versions</a>.</p>\x0a<h3\x20id=\"vcs-dir\">Module\x20directories\x20within\x20a\x20repository</h3>\x0a<p>Once\x20a\x20module's\x20repository\x20has\x20been\x20checked\x20out\x20at\x20a\x20specific\x20revision,\x20the\x20<code>go</code>\x0acommand\x20must\x20locate\x20the\x20directory\x20that\x20contains\x20the\x20module's\x20<code>go.mod</code>\x20file\x0a(the\x20module's\x20root\x20directory).</p>\x0a<p>Recall\x20that\x20a\x20<a\x20href=\"#module-path\">module\x20path</a>\x20consists\x20of\x20three\x20parts:\x20a\x0arepository\x20root\x20path\x20(corresponding\x20to\x20the\x20repository\x20root\x20directory),\x0aa\x20module\x20subdirectory,\x20and\x20a\x20major\x20version\x20suffix\x20(only\x20for\x20modules\x20released\x20at\x0a<code>v2</code>\x20or\x20higher).</p>\x0a<p>For\x20most\x20modules,\x20the\x20module\x20path\x20is\x20equal\x20to\x20the\x20repository\x20root\x20path,\x20so\x0athe\x20module's\x20root\x20directory\x20is\x20the\x20repository's\x20root\x20directory.</p>\x0a<p>Modules\x20are\x20sometimes\x20defined\x20in\x20repository\x20subdirectories.\x20This\x20is\x20typically\x0adone\x20for\x20large\x20repositories\x20with\x20multiple\x20components\x20that\x20need\x20to\x20be\x20released\x0aand\x20versioned\x20indepently.\x20Such\x20a\x20module\x20is\x20expected\x20to\x20be\x20found\x20in\x20a\x0asubdirectory\x20that\x20matches\x20the\x20part\x20of\x20the\x20module's\x20path\x20after\x20the\x20repository\x0aroot\x20path.\x20\x20For\x20example,\x20suppose\x20the\x20module\x20<code>example.com/monorepo/foo/bar</code>\x20is\x20in\x0athe\x20repository\x20with\x20root\x20path\x20<code>example.com/monorepo</code>.\x20Its\x20<code>go.mod</code>\x20file\x20must\x20be\x0ain\x20the\x20<code>foo/bar</code>\x20subdirectory.</p>\x0a<p>If\x20a\x20module\x20is\x20released\x20at\x20major\x20version\x20<code>v2</code>\x20or\x20higher,\x20its\x20path\x20must\x20have\x20a\x0a<a\x20href=\"#major-version-suffixes\">major\x20version\x20suffix</a>.\x20A\x20module\x20with\x20a\x20major\x20version\x0asuffix\x20may\x20be\x20defined\x20in\x20one\x20of\x20two\x20subdirectories:\x20one\x20with\x20the\x20suffix,\x0aand\x20one\x20without.\x20For\x20example,\x20suppose\x20a\x20new\x20version\x20of\x20the\x20module\x20above\x20is\x0areleased\x20with\x20the\x20path\x20<code>example.com/monorepo/foo/bar/v2</code>.\x20Its\x20<code>go.mod</code>\x20file\x0amay\x20be\x20in\x20either\x20<code>foo/bar</code>\x20or\x20<code>foo/bar/v2</code>.</p>\x0a<p>Subdirectories\x20with\x20a\x20major\x20version\x20suffix\x20are\x20<dfn>major\x20version\x0asubdirectories</dfn>.\x20They\x20may\x20be\x20used\x20to\x20develop\x20multiple\x20major\x20versions\x20of\x20a\x0amodule\x20on\x20a\x20single\x20branch.\x20This\x20may\x20be\x20unnecessary\x20when\x20development\x20of\x20multiple\x0amajor\x20versions\x20proceeds\x20on\x20separate\x20branches.\x20However,\x20major\x20version\x0asubdirectories\x20have\x20an\x20important\x20property:\x20in\x20<code>GOPATH</code>\x20mode,\x20package\x20import\x0apaths\x20exactly\x20match\x20directories\x20under\x20<code>GOPATH/src</code>.\x20The\x20<code>go</code>\x20command\x20provides\x0aminimal\x20module\x20compatibility\x20in\x20<code>GOPATH</code>\x20mode\x20(see\x20<a\x20href=\"#non-module-compat\">Compatibility\x20with\x0anon-module\x20repositories</a>),\x20so\x20major\x20version\x0asubdirectories\x20aren't\x20always\x20necessary\x20for\x20compatibility\x20with\x20projects\x20built\x20in\x0a<code>GOPATH</code>\x20mode.\x20Older\x20tools\x20that\x20don't\x20support\x20minimal\x20module\x20compatibility\x0amay\x20have\x20problems\x20though.</p>\x0a<p>Once\x20the\x20<code>go</code>\x20command\x20has\x20found\x20the\x20module\x20root\x20directory,\x20it\x20creates\x20a\x20<code>.zip</code>\x0afile\x20of\x20the\x20contents\x20of\x20the\x20directory,\x20then\x20extracts\x20the\x20<code>.zip</code>\x20file\x20into\x20the\x0amodule\x20cache.\x20See\x20<a\x20href=\"#zip-path-size-constraints\">File\x20path\x20and\x20size\x20constraints</a>)\x0afor\x20details\x20on\x20what\x20files\x20may\x20be\x20included\x20in\x20the\x20<code>.zip</code>\x20file.\x20The\x20contents\x20of\x0athe\x20<code>.zip</code>\x20file\x20are\x20<a\x20href=\"#authenticating\">authenticated</a>\x20before\x20extraction\x20into\x20the\x0amodule\x20cache\x20the\x20same\x20way\x20they\x20would\x20be\x20if\x20the\x20<code>.zip</code>\x20file\x20were\x20downloaded\x20from\x0aa\x20proxy.</p>\x0a<h2\x20id=\"zip-files\">Module\x20zip\x20files</h2>\x0a<p>Module\x20versions\x20are\x20distributed\x20as\x20<code>.zip</code>\x20files.\x20There\x20is\x20rarely\x20any\x20need\x20to\x0ainteract\x20directly\x20with\x20these\x20files,\x20since\x20the\x20<code>go</code>\x20command\x20creates,\x20downloads,\x0aand\x20extracts\x20them\x20automatically\x20from\x20<a\x20href=\"#glos-module-proxy\">module\x20proxies</a>\x20and\x0aversion\x20control\x20repositories.\x20However,\x20it's\x20still\x20useful\x20to\x20know\x20about\x20these\x0afiles\x20to\x20understand\x20cross-platform\x20compatibility\x20constraints\x20or\x20when\x0aimplementing\x20a\x20module\x20proxy.</p>\x0a<p>The\x20<a\x20href=\"#go-mod-download\"><code>go\x20mod\x20download</code></a>\x20command\x20downloads\x20zip\x20files\x0afor\x20one\x20or\x20more\x20modules,\x20then\x20extracts\x20those\x20files\x20into\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>.\x20Depending\x20on\x20<code>GOPROXY</code>\x20and\x20other\x20<a\x20href=\"#environment-variables\">environment\x0avariables</a>,\x20the\x20<code>go</code>\x20command\x20may\x20either\x20download\x0azip\x20files\x20from\x20a\x20proxy\x20or\x20clone\x20source\x20control\x20repositories\x20and\x20create\x0azip\x20files\x20from\x20them.\x20The\x20<code>-json</code>\x20flag\x20may\x20be\x20used\x20to\x20find\x20the\x20location\x20of\x0adownload\x20zip\x20files\x20and\x20their\x20extracted\x20contents\x20in\x20the\x20module\x20cache.</p>\x0a<p>The\x20<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/zip?tab=doc\"><code>golang.org/x/mod/zip</code></a>\x0apackage\x20may\x20be\x20used\x20to\x20create,\x20extract,\x20or\x20check\x20contents\x20of\x20zip\x20files\x0aprogrammatically.</p>\x0a<h3\x20id=\"zip-path-size-constraints\">File\x20path\x20and\x20size\x20constraints</h3>\x0a<p>There\x20are\x20a\x20number\x20of\x20restrictions\x20on\x20the\x20content\x20of\x20module\x20zip\x20files.\x20These\x0aconstraints\x20ensure\x20that\x20zip\x20files\x20can\x20be\x20extracted\x20safely\x20and\x20consistently\x20on\x0aa\x20wide\x20range\x20of\x20platforms.</p>\x0a<ul>\x0a<li>A\x20module\x20zip\x20file\x20may\x20be\x20at\x20most\x20500\x20MiB\x20in\x20size.\x20The\x20total\x20uncompressed\x20size\x0aof\x20its\x20files\x20is\x20also\x20limited\x20to\x20500\x20MiB.\x20<code>go.mod</code>\x20files\x20are\x20limited\x20to\x2016\x20MiB.\x0a<code>LICENSE</code>\x20files\x20are\x20also\x20limited\x20to\x2016\x20MiB.\x20These\x20limits\x20exist\x20to\x20mitigate\x0adenial\x20of\x20service\x20attacks\x20on\x20users,\x20proxies,\x20and\x20other\x20parts\x20of\x20the\x20module\x0aecosystem.\x20Repositories\x20that\x20contain\x20more\x20than\x20500\x20MiB\x20of\x20files\x20in\x20a\x20module\x0adirectory\x20tree\x20should\x20tag\x20module\x20versions\x20at\x20commits\x20that\x20only\x20include\x20files\x0aneeded\x20to\x20build\x20the\x20module's\x20packages;\x20videos,\x20models,\x20and\x20other\x20large\x20assets\x0aare\x20usually\x20not\x20needed\x20for\x20builds.</li>\x0a<li>Each\x20file\x20within\x20a\x20module\x20zip\x20file\x20must\x20begin\x20with\x20the\x20prefix\x0a<code>$module@$version/</code>\x20where\x20<code>$module</code>\x20is\x20the\x20module\x20path\x20and\x20<code>$version</code>\x20is\x20the\x0aversion,\x20for\x20example,\x20<code>golang.org/x/mod@v0.3.0/</code>.\x20The\x20module\x20path\x20must\x20be\x0avalid,\x20the\x20version\x20must\x20be\x20valid\x20and\x20canonical,\x20and\x20the\x20version\x20must\x20match\x20the\x0amodule\x20path's\x20major\x20version\x20suffix.\x20See\x20<a\x20href=\"#go.mod-ident\">Module\x20paths\x20and\x0aversions</a>\x20for\x20specific\x20definitions\x20and\x20restrictions.</li>\x0a<li>File\x20modes,\x20timestamps,\x20and\x20other\x20metadata\x20are\x20ignored.</li>\x0a<li>Empty\x20directories\x20(entries\x20with\x20paths\x20ending\x20with\x20a\x20slash)\x20may\x20be\x20included\x0ain\x20module\x20zip\x20files\x20but\x20are\x20not\x20extracted.\x20The\x20<code>go</code>\x20command\x20does\x20not\x20include\x0aempty\x20directories\x20in\x20zip\x20files\x20it\x20creates.</li>\x0a<li>Symbolic\x20links\x20and\x20other\x20irregular\x20files\x20are\x20ignored\x20when\x20creating\x20zip\x20files,\x0asince\x20they\x20aren't\x20portable\x20across\x20operating\x20systems\x20and\x20file\x20systems,\x20and\x0athere's\x20no\x20portable\x20way\x20to\x20represent\x20them\x20in\x20the\x20zip\x20file\x20format.</li>\x0a<li>No\x20two\x20files\x20within\x20a\x20zip\x20file\x20may\x20have\x20paths\x20equal\x20under\x20Unicode\x20case-folding\x0a(see\x20<a\x20href=\"https://pkg.go.dev/strings?tab=doc#EqualFold\"><code>strings.EqualFold</code></a>).\x0aThis\x20ensures\x20that\x20zip\x20files\x20can\x20be\x20extracted\x20on\x20case-insensitive\x20file\x20systems\x0awithout\x20collisions.</li>\x0a<li>A\x20<code>go.mod</code>\x20file\x20may\x20or\x20may\x20not\x20appear\x20in\x20the\x20top-level\x20directory\x0a(<code>$module@$version/go.mod</code>).\x20If\x20present,\x20it\x20must\x20have\x20the\x20name\x20<code>go.mod</code>\x20(all\x0alowercase).\x20Files\x20named\x20<code>go.mod</code>\x20are\x20not\x20allowed\x20in\x20any\x20other\x20directory.</li>\x0a<li>File\x20and\x20directory\x20names\x20within\x20a\x20module\x20may\x20consist\x20of\x20Unicode\x20letters,\x20ASCII\x0adigits,\x20the\x20ASCII\x20space\x20character\x20(U+0020),\x20and\x20the\x20ASCII\x20punctuation\x0acharacters\x20<code>!#$%&amp;()+,-.=@[]^_{}~</code>.\x20Note\x20that\x20package\x20paths\x20may\x20not\x20contain\x20all\x0athese\x20all\x20these\x20characters.\x20See\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/module?tab=doc#CheckFilePath\"><code>module.CheckFilePath</code></a>\x0aand\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/module?tab=doc#CheckImportPath\"><code>module.CheckImportPath</code></a>\x0afor\x20the\x20differences.</li>\x0a<li>A\x20file\x20or\x20directory\x20name\x20up\x20to\x20the\x20first\x20dot\x20must\x20not\x20be\x20a\x20reserved\x20file\x20name\x0aon\x20Windows,\x20regardless\x20of\x20case\x20(<code>CON</code>,\x20<code>com1</code>,\x20<code>NuL</code>,\x20and\x20so\x20on).</li>\x0a</ul>\x0a<h2\x20id=\"private-modules\">Private\x20modules</h2>\x0a<p>Go\x20modules\x20are\x20frequently\x20developed\x20and\x20distributed\x20on\x20version\x20control\x20servers\x0aand\x20module\x20proxies\x20that\x20aren't\x20available\x20on\x20the\x20public\x20internet.\x20The\x20<code>go</code>\x0acommand\x20can\x20download\x20and\x20build\x20modules\x20from\x20private\x20sources,\x20though\x20it\x20usually\x0arequires\x20some\x20configuration.</p>\x0a<p>The\x20environment\x20variables\x20below\x20may\x20be\x20used\x20to\x20configure\x20access\x20to\x20private\x0amodules.\x20See\x20<a\x20href=\"#environment-variables\">Environment\x20variables</a>\x20for\x20details.\x20See\x0aalso\x20<a\x20href=\"#privacy\">Privacy</a>\x20for\x20information\x20on\x20controlling\x20information\x20sent\x20to\x0apublic\x20servers.</p>\x0a<ul>\x0a<li><code>GOPROXY</code>\x20\xe2\x80\x94\x20list\x20of\x20module\x20proxy\x20URLs.\x20The\x20<code>go</code>\x20command\x20will\x20attempt\x20to\x0adownload\x20modules\x20from\x20each\x20server\x20in\x20sequence.\x20The\x20keyword\x20<code>direct</code>\x20instructs\x0athe\x20<code>go</code>\x20command\x20to\x20download\x20modules\x20from\x20version\x20control\x20repositories\x0awhere\x20they're\x20developed\x20instead\x20of\x20using\x20a\x20proxy.</li>\x0a<li><code>GOPRIVATE</code>\x20\xe2\x80\x94\x20list\x20of\x20glob\x20patterns\x20of\x20module\x20path\x20prefixes\x20that\x20should\x20be\x0aconsidered\x20private.\x20Acts\x20as\x20a\x20default\x20value\x20for\x20<code>GONOPROXY</code>\x20and\x20<code>GONOSUMDB</code>.</li>\x0a<li><code>GONOPROXY</code>\x20\xe2\x80\x94\x20list\x20of\x20glob\x20patterns\x20of\x20module\x20path\x20prefixes\x20that\x20should\x20not\x20be\x0adownloaded\x20from\x20a\x20proxy.\x20The\x20<code>go</code>\x20command\x20will\x20download\x20matching\x20modules\x20from\x0aversion\x20control\x20repositories\x20where\x20they're\x20developed,\x20regardless\x20of\x20<code>GOPROXY</code>.</li>\x0a<li><code>GONOSUMDB</code>\x20\xe2\x80\x94\x20list\x20of\x20glob\x20patterns\x20of\x20module\x20path\x20prefixes\x20that\x20should\x20not\x20be\x0achecked\x20using\x20the\x20public\x20checksum\x20database,\x0a<a\x20href=\"https://sum.golang.org\">sum.golang.org</a>.</li>\x0a<li><code>GOINSECURE</code>\x20\xe2\x80\x94\x20list\x20of\x20glob\x20patterns\x20of\x20module\x20path\x20prefixes\x20that\x20may\x20be\x0aretrieved\x20over\x20HTTP\x20and\x20other\x20insecure\x20protocols.</li>\x0a</ul>\x0a<p>These\x20variables\x20may\x20be\x20set\x20in\x20the\x20development\x20environment\x20(for\x20example,\x20in\x20a\x0a<code>.profile</code>\x20file),\x20or\x20they\x20may\x20be\x20set\x20permanently\x20with\x20<a\x20href=\"https://golang.org/cmd/go/#hdr-Print_Go_environment_information\"><code>go\x20env\x20-w</code></a>.</p>\x0a<p>The\x20rest\x20of\x20this\x20section\x20describes\x20common\x20patterns\x20for\x20providing\x20access\x20to\x0aprivate\x20module\x20proxies\x20and\x20version\x20control\x20repositories.</p>\x0a<h3\x20id=\"private-module-proxy-all\">Private\x20proxy\x20serving\x20all\x20modules</h3>\x0a<p>A\x20central\x20private\x20proxy\x20server\x20that\x20serves\x20all\x20modules\x20(public\x20and\x20private)\x0aprovides\x20the\x20most\x20control\x20for\x20administrators\x20and\x20requires\x20the\x20least\x0aconfiguration\x20for\x20individual\x20developers.</p>\x0a<p>To\x20configure\x20the\x20<code>go</code>\x20command\x20to\x20use\x20such\x20a\x20server,\x20set\x20the\x20following\x0aenvironment\x20variables,\x20replacing\x20<code>https://proxy.corp.example.com</code>\x20with\x20your\x0aproxy\x20URL\x20and\x20<code>corp.example.com</code>\x20with\x20your\x20module\x20prefix:</p>\x0a<pre><code>GOPROXY=https://proxy.corp.example.com\x0aGONOSUMDB=corp.example.com\x0a</code></pre>\x0a<p>The\x20<code>GOPROXY</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20to\x20only\x20download\x20modules\x20from\x0a<code>https://proxy.corp.example.com</code>;\x20the\x20<code>go</code>\x20command\x20will\x20not\x20connect\x20to\x20other\x0aproxies\x20or\x20version\x20control\x20repositories.</p>\x0a<p>The\x20<code>GONOSUMDB</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20not\x20to\x20use\x20the\x20public\x0achecksum\x20database\x20to\x20authenticate\x20modules\x20with\x20paths\x20starting\x20with\x0a<code>corp.example.com</code>.</p>\x0a<p>A\x20proxy\x20running\x20in\x20this\x20configuration\x20will\x20likely\x20need\x20read\x20access\x20to\x0aprivate\x20version\x20control\x20servers.\x20It\x20will\x20also\x20need\x20access\x20to\x20the\x20public\x20internet\x0ato\x20download\x20new\x20versions\x20of\x20public\x20modules.</p>\x0a<p>There\x20are\x20several\x20existing\x20implementations\x20of\x20<code>GOPROXY</code>\x20servers\x20that\x20may\x20be\x20used\x0athis\x20way.\x20A\x20minimal\x20implementation\x20would\x20serve\x20files\x20from\x20a\x20<a\x20href=\"#glos-module-cache\">module\x0acache</a>\x20directory\x20and\x20would\x20use\x20<a\x20href=\"#go-mod-download\"><code>go\x20mod\x20download</code></a>\x20(with\x20suitable\x20configuration)\x20to\x20retrieve\x20missing\x0amodules.</p>\x0a<h3\x20id=\"private-module-proxy-private\">Private\x20proxy\x20serving\x20private\x20modules</h3>\x0a<p>A\x20private\x20proxy\x20server\x20may\x20serve\x20private\x20modules\x20without\x20also\x20serving\x20publicly\x0aavailable\x20modules.\x20The\x20<code>go</code>\x20command\x20can\x20be\x20configured\x20to\x20fall\x20back\x20to\x0apublic\x20sources\x20for\x20modules\x20that\x20aren't\x20available\x20on\x20the\x20private\x20server.</p>\x0a<p>To\x20configure\x20the\x20<code>go</code>\x20command\x20to\x20work\x20this\x20way,\x20set\x20the\x20following\x20environment\x0avariables,\x20replacing\x20<code>https://proxy.corp.example.com</code>\x20with\x20the\x20proxy\x20URL\x20and\x0a<code>corp.example.com</code>\x20with\x20the\x20module\x20prefix:</p>\x0a<pre><code>GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct\x0aGONOSUMDB=corp.example.com\x0a</code></pre>\x0a<p>The\x20<code>GOPROXY</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20to\x20try\x20to\x20download\x20modules\x20from\x0a<code>https://proxy.corp.example.com</code>\x20first.\x20If\x20that\x20server\x20responds\x20with\x20404\x20(Not\x0aFound)\x20or\x20410\x20(Gone),\x20the\x20<code>go</code>\x20command\x20will\x20fall\x20back\x20to\x0a<code>https://proxy.golang.org</code>,\x20then\x20to\x20direct\x20connections\x20to\x20repositories.</p>\x0a<p>The\x20<code>GONOSUMDB</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20not\x20to\x20use\x20the\x20public\x20checksum\x0adatabase\x20to\x20authenticate\x20modules\x20whose\x20paths\x20start\x20with\x20<code>corp.example.com</code>.</p>\x0a<p>Note\x20that\x20a\x20proxy\x20used\x20in\x20this\x20configuration\x20may\x20still\x20control\x20access\x20to\x20public\x0amodules,\x20even\x20though\x20it\x20doesn't\x20serve\x20them.\x20If\x20the\x20proxy\x20responds\x20to\x20a\x20request\x0awith\x20an\x20error\x20status\x20other\x20than\x20404\x20or\x20410,\x20the\x20<code>go</code>\x20command\x20will\x20not\x20fall\x20back\x0ato\x20later\x20entries\x20in\x20the\x20<code>GOPROXY</code>\x20list.\x20For\x20example,\x20the\x20proxy\x20could\x20respond\x0awith\x20403\x20(Forbidden)\x20for\x20a\x20module\x20with\x20an\x20unsuitable\x20license\x20or\x20with\x20known\x0asecurity\x20vulnerabilities.</p>\x0a<h3\x20id=\"private-module-proxy-direct\">Direct\x20access\x20to\x20private\x20modules</h3>\x0a<p>The\x20<code>go</code>\x20command\x20may\x20be\x20configured\x20to\x20bypass\x20public\x20proxies\x20and\x20download\x20private\x0amodules\x20directly\x20from\x20version\x20control\x20servers.\x20This\x20is\x20useful\x20when\x20running\x20a\x0aprivate\x20proxy\x20server\x20is\x20not\x20feasible.</p>\x0a<p>To\x20configure\x20the\x20<code>go</code>\x20command\x20to\x20work\x20this\x20way,\x20set\x20<code>GOPRIVATE</code>,\x20replacing\x0a<code>corp.example.com</code>\x20the\x20private\x20module\x20prefix:</p>\x0a<pre><code>GOPRIVATE=corp.example.com\x0a</code></pre>\x0a<p>The\x20<code>GOPROXY</code>\x20variable\x20does\x20not\x20need\x20to\x20be\x20changed\x20in\x20this\x20situation.\x20It\x0adefaults\x20to\x20<code>https://proxy.golang.org,direct</code>,\x20which\x20instructs\x20the\x20<code>go</code>\x20command\x0ato\x20attempt\x20to\x20download\x20modules\x20from\x20<code>https://proxy.golang.org</code>\x20first,\x20then\x20fall\x0aback\x20to\x20a\x20direct\x20connection\x20if\x20that\x20proxy\x20responds\x20with\x20404\x20(Not\x20Found)\x20or\x20410\x0a(Gone).</p>\x0a<p>The\x20<code>GOPRIVATE</code>\x20setting\x20instructs\x20the\x20<code>go</code>\x20command\x20not\x20to\x20connect\x20to\x20a\x20proxy\x20or\x0ato\x20the\x20checksum\x20database\x20for\x20modules\x20starting\x20with\x20<code>corp.example.com</code>.</p>\x0a<p>An\x20internal\x20HTTP\x20server\x20may\x20still\x20be\x20needed\x20to\x20<a\x20href=\"#vcs-find\">resolve\x20module\x20paths\x20to\x0arepository\x20URLs</a>.\x20For\x20example,\x20when\x20the\x20<code>go</code>\x20command\x20downloads\x20the\x0amodule\x20<code>corp.example.com/mod</code>,\x20it\x20will\x20send\x20a\x20GET\x20request\x20to\x0a<code>https://corp.example.com/mod?go-get=1</code>,\x20and\x20it\x20will\x20look\x20for\x20the\x20repository\x20URL\x0ain\x20the\x20response.\x20To\x20avoid\x20this\x20requirement,\x20ensure\x20that\x20each\x20private\x20module\x20path\x0ahas\x20a\x20VCS\x20suffix\x20(like\x20<code>.git</code>)\x20marking\x20the\x20repository\x20root\x20prefix.\x20For\x20example,\x0awhen\x20the\x20<code>go</code>\x20command\x20downloads\x20the\x20module\x20<code>corp.example.com/repo.git/mod</code>,\x20it\x0awill\x20clone\x20the\x20Git\x20repository\x20at\x20<code>https://corp.example.com/repo.git</code>\x20or\x0a<code>ssh://corp.example.com/repo.git</code>\x20without\x20needing\x20to\x20make\x20additional\x20requests.</p>\x0a<p>Developers\x20will\x20need\x20read\x20access\x20to\x20repositories\x20containing\x20private\x20modules.\x0aThis\x20may\x20be\x20configured\x20in\x20global\x20VCS\x20configuration\x20files\x20like\x20<code>.gitconfig</code>.\x0aIt's\x20best\x20if\x20VCS\x20tools\x20are\x20configured\x20not\x20to\x20need\x20interactive\x20authentication\x0aprompts.\x20By\x20default,\x20when\x20invoking\x20Git,\x20the\x20<code>go</code>\x20command\x20disables\x20interactive\x0aprompts\x20by\x20setting\x20<code>GIT_TERMINAL_PROMPT=0</code>,\x20but\x20it\x20respects\x20explicit\x20settings.</p>\x0a<h3\x20id=\"private-module-proxy-auth\">Passing\x20credentials\x20to\x20private\x20proxies</h3>\x0a<p>The\x20<code>go</code>\x20command\x20supports\x20HTTP\x20<a\x20href=\"https://en.wikipedia.org/wiki/Basic_access_authentication\">basic\x0aauthentication</a>\x20when\x0acommunicating\x20with\x20proxy\x20servers.</p>\x0a<p>Credentials\x20may\x20be\x20specified\x20in\x20a\x20<a\x20href=\"https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html\"><code>.netrc</code>\x0afile</a>.\x0aFor\x20example,\x20a\x20<code>.netrc</code>\x20file\x20containing\x20the\x20lines\x20below\x20would\x20configure\x20the\x20<code>go</code>\x0acommand\x20to\x20connect\x20to\x20the\x20machine\x20<code>proxy.corp.example.com</code>\x20with\x20the\x20given\x0ausername\x20and\x20password.</p>\x0a<pre><code>machine\x20proxy.corp.example.com\x0alogin\x20jrgopher\x0apassword\x20hunter2\x0a</code></pre>\x0a<p>The\x20location\x20of\x20the\x20file\x20may\x20be\x20set\x20with\x20the\x20<code>NETRC</code>\x20environment\x20variable.\x20If\x0a<code>NETRC</code>\x20is\x20not\x20set,\x20the\x20<code>go</code>\x20command\x20will\x20read\x20<code>$HOME/.netrc</code>\x20on\x20UNIX-like\x0aplatforms\x20or\x20<code>%USERPROFILE%\\_netrc</code>\x20on\x20Windows.</p>\x0a<p>Fields\x20in\x20<code>.netrc</code>\x20are\x20separated\x20with\x20spaces,\x20tabs,\x20and\x20newlines.\x20Unfortunately,\x0athese\x20characters\x20cannot\x20be\x20used\x20in\x20usernames\x20or\x20passwords.\x20Note\x20also\x20that\x20the\x0amachine\x20name\x20cannot\x20be\x20a\x20full\x20URL,\x20so\x20it's\x20not\x20possible\x20to\x20specify\x20different\x0ausernames\x20and\x20passwords\x20for\x20different\x20paths\x20on\x20the\x20same\x20machine.</p>\x0a<p>Alternatively,\x20credentials\x20may\x20be\x20specified\x20directly\x20in\x20<code>GOPROXY</code>\x20URLs.\x20For\x0aexample:</p>\x0a<pre><code>GOPROXY=https://jrgopher:hunter2@proxy.corp.example.com\x0a</code></pre>\x0a<p>Use\x20caution\x20when\x20taking\x20this\x20approach:\x20environment\x20variables\x20may\x20be\x20appear\x0ain\x20shell\x20history\x20and\x20in\x20logs.</p>\x0a<h2\x20id=\"module-cache\">Module\x20cache</h2>\x0a<p>The\x20<dfn>module\x20cache</dfn>\x20is\x20the\x20directory\x20where\x20the\x20<code>go</code>\x20command\x20stores\x0adownloaded\x20module\x20files.\x20The\x20module\x20cache\x20is\x20distinct\x20from\x20the\x20build\x20cache,\x0awhich\x20contains\x20compiled\x20packages\x20and\x20other\x20build\x20artifacts.</p>\x0a<p>The\x20default\x20location\x20of\x20the\x20module\x20cache\x20is\x20<code>$GOPATH/pkg/mod</code>.\x20To\x20use\x20a\x0adifferent\x20location,\x20set\x20the\x20<code>GOMODCACHE</code>\x20<a\x20href=\"#environment-variables\">environment\x0avariable</a>.</p>\x0a<p>The\x20module\x20cache\x20has\x20no\x20maximum\x20size,\x20and\x20the\x20<code>go</code>\x20command\x20does\x20not\x20remove\x20its\x0acontents\x20automatically.</p>\x0a<p>The\x20cache\x20may\x20be\x20shared\x20by\x20multiple\x20Go\x20projects\x20developed\x20on\x20the\x20same\x20machine.\x0aThe\x20<code>go</code>\x20command\x20will\x20use\x20the\x20same\x20cache\x20regardless\x20of\x20the\x20location\x20of\x20the\x0amain\x20module.\x20Multiple\x20instances\x20of\x20the\x20<code>go</code>\x20command\x20may\x20safely\x20access\x20the\x0asame\x20module\x20cache\x20at\x20the\x20same\x20time.</p>\x0a<p>The\x20<code>go</code>\x20command\x20creates\x20module\x20source\x20files\x20and\x20directories\x20in\x20the\x20cache\x20with\x0aread-only\x20permissions\x20to\x20prevent\x20accidental\x20changes\x20to\x20modules\x20after\x20they're\x0adownloaded.\x20This\x20has\x20the\x20unfortunate\x20side-effect\x20of\x20making\x20the\x20cache\x20difficult\x0ato\x20delete\x20with\x20commands\x20like\x20<code>rm\x20-rf</code>.\x20The\x20cache\x20may\x20instead\x20be\x20deleted\x20with\x0a<a\x20href=\"#go-clean-modcache\"><code>go\x20clean\x20-modcache</code></a>.\x20Alternatively,\x20when\x20the\x0a<code>-modcacherw</code>\x20flag\x20is\x20used,\x20the\x20<code>go</code>\x20command\x20will\x20create\x20new\x20directories\x20with\x0aread-write\x20permissions.\x20This\x20increases\x20the\x20risk\x20of\x20editors,\x20tests,\x20and\x20other\x0aprograms\x20modifying\x20files\x20in\x20the\x20module\x20cache.\x20The\x20<a\x20href=\"#go-mod-verify\"><code>go\x20mod\x20verify</code></a>\x20command\x20may\x20be\x20used\x20to\x20detect\x20modifications\x20to\x0adependencies\x20of\x20the\x20main\x20module.\x20It\x20scans\x20the\x20extracted\x20contents\x20of\x20each\x0amodule\x20dependency\x20and\x20confirms\x20they\x20match\x20the\x20expected\x20hash\x20in\x20<code>go.sum</code>.</p>\x0a<p>The\x20table\x20below\x20explains\x20the\x20purpose\x20of\x20most\x20files\x20in\x20the\x20module\x20cache.\x20Some\x0atransient\x20files\x20(lock\x20files,\x20temporary\x20directories)\x20are\x20omitted.\x20For\x20each\x20path,\x0a<code>$module</code>\x20is\x20a\x20module\x20path,\x20and\x20<code>$version</code>\x20is\x20a\x20version.\x20Paths\x20ending\x20with\x0aslashes\x20(<code>/</code>)\x20are\x20directories.\x20Capital\x20letters\x20in\x20module\x20paths\x20and\x20versions\x20are\x0aescaped\x20using\x20exclamation\x20points\x20(<code>Azure</code>\x20is\x20escaped\x20as\x20<code>!azure</code>)\x20to\x20avoid\x0aconflicts\x20on\x20case-insensitive\x20file\x20systems.</p>\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Path</th>\x0a\x20\x20\x20\x20\x20\x20<th>Description</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$module@$version/</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Directory\x20containing\x20extracted\x20contents\x20of\x20a\x20module\x20<code>.zip</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20file.\x20This\x20serves\x20as\x20a\x20module\x20root\x20directory\x20for\x20a\x20downloaded\x20module.\x20It\x0a\x20\x20\x20\x20\x20\x20\x20\x20won't\x20contain\x20contain\x20a\x20<code>go.mod</code>\x20file\x20if\x20the\x20original\x20module\x0a\x20\x20\x20\x20\x20\x20\x20\x20didn't\x20have\x20one.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Directory\x20containing\x20files\x20downloaded\x20from\x20module\x20proxies\x20and\x20files\x0a\x20\x20\x20\x20\x20\x20\x20\x20derived\x20from\x20<a\x20href=\"#vcs\">version\x20control\x20systems</a>.\x20The\x20layout\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20this\x20directory\x20follows\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>,\x20so\x0a\x20\x20\x20\x20\x20\x20\x20\x20this\x20directory\x20may\x20be\x20used\x20as\x20a\x20proxy\x20when\x20served\x20by\x20an\x20HTTP\x20file\x0a\x20\x20\x20\x20\x20\x20\x20\x20server\x20or\x20when\x20referenced\x20with\x20a\x20<code>file://</code>\x20URL.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/list</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20List\x20of\x20known\x20versions\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>).\x20This\x0a\x20\x20\x20\x20\x20\x20\x20\x20may\x20change\x20over\x20time,\x20so\x20the\x20<code>go</code>\x20command\x20usually\x20fetches\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20new\x20copy\x20instead\x20of\x20re-using\x20this\x20file.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/$version.info</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20JSON\x20metadata\x20about\x20the\x20version.\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>).\x20This\x0a\x20\x20\x20\x20\x20\x20\x20\x20may\x20change\x20over\x20time,\x20so\x20the\x20<code>go</code>\x20command\x20usually\x20fetches\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20new\x20copy\x20instead\x20of\x20re-using\x20this\x20file.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/$version.mod</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20The\x20<code>go.mod</code>\x20file\x20for\x20this\x20version\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>).\x20If\x0a\x20\x20\x20\x20\x20\x20\x20\x20the\x20original\x20module\x20did\x20not\x20have\x20a\x20<code>go.mod</code>\x20file,\x20this\x20is\x0a\x20\x20\x20\x20\x20\x20\x20\x20a\x20synthesized\x20file\x20with\x20no\x20requirements.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/$version.zip</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20The\x20zipped\x20contents\x20of\x20the\x20module\x20(see\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x20protocol</a>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#zip-files\">Module\x20zip\x20files</a>).\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/$module/@v/$version.ziphash</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20A\x20cryptographic\x20hash\x20of\x20the\x20files\x20in\x20the\x20<code>.zip</code>\x20file.\x0a\x20\x20\x20\x20\x20\x20\x20\x20Note\x20that\x20the\x20<code>.zip</code>\x20file\x20itself\x20is\x20not\x20hashed,\x20so\x20file\x0a\x20\x20\x20\x20\x20\x20\x20\x20order,\x20compression,\x20alignment,\x20and\x20metadata\x20don't\x20affect\x20the\x20hash.\x0a\x20\x20\x20\x20\x20\x20\x20\x20When\x20using\x20a\x20module,\x20the\x20<code>go</code>\x20command\x20verifies\x20this\x20hash\x0a\x20\x20\x20\x20\x20\x20\x20\x20matches\x20the\x20corresponding\x20line\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#go.sum-files\"><code>go.sum</code></a>.\x20The\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#go-mod-verify\"><code>go\x20mod\x20verify</code></a>\x20command\x20checks\x0a\x20\x20\x20\x20\x20\x20\x20\x20that\x20the\x20hashes\x20of\x20module\x20<code>.zip</code>\x20files\x20and\x20extracted\x0a\x20\x20\x20\x20\x20\x20\x20\x20directories\x20match\x20these\x20files.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/download/sumdb/</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Directory\x20containing\x20files\x20downloaded\x20from\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#checksum-database\">checksum\x20database</a>\x20(typically\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>sum.golang.org</code>).\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>cache/vcs/</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Contains\x20cloned\x20version\x20control\x20repositories\x20for\x20modules\x20fetched\x0a\x20\x20\x20\x20\x20\x20\x20\x20directly\x20from\x20their\x20sources.\x20Directory\x20names\x20are\x20hex-encoded\x20hashes\x0a\x20\x20\x20\x20\x20\x20\x20\x20derived\x20from\x20the\x20repository\x20type\x20and\x20URL.\x20Repositories\x20are\x20optimized\x0a\x20\x20\x20\x20\x20\x20\x20\x20for\x20size\x20on\x20disk.\x20For\x20example,\x20cloned\x20Git\x20repositories\x20are\x20bare\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20shallow\x20when\x20possible.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<h2\x20id=\"authenticating\">Authenticating\x20modules</h2>\x0a<!--\x20TODO:\x20continue\x20this\x20section\x20-->\x0a<p>When\x20deciding\x20whether\x20to\x20trust\x20the\x20source\x20code\x20for\x20a\x20module\x20version\x20just\x0afetched\x20from\x20a\x20proxy\x20or\x20origin\x20server,\x20the\x20<code>go</code>\x20command\x20first\x20consults\x20the\x0a<code>go.sum</code>\x20lines\x20in\x20the\x20<code>go.sum</code>\x20file\x20of\x20the\x20current\x20module.\x20If\x20the\x20<code>go.sum</code>\x20file\x0adoes\x20not\x20contain\x20an\x20entry\x20for\x20that\x20module\x20version,\x20then\x20it\x20may\x20consult\x20the\x0achecksum\x20database.</p>\x0a<h3\x20id=\"go\"\x20class=\"sum-files\">go.sum\x20files</h3>\x0a<p>A\x20module\x20may\x20have\x20a\x20text\x20file\x20named\x20<code>go.sum</code>\x20in\x20its\x20root\x20directory,\x20alongside\x0aits\x20<code>go.mod</code>\x20file.\x20The\x20<code>go.sum</code>\x20file\x20contains\x20cryptographic\x20hashes\x20of\x20the\x0amodule's\x20direct\x20and\x20indirect\x20dependencies.\x20<code>go.sum</code>\x20may\x20be\x20empty\x20or\x20absent\x0aif\x20the\x20module\x20has\x20no\x20dependencies\x20or\x20if\x20all\x20dependencies\x20are\x20replaced\x20with\x0alocal\x20directories\x20using\x20<a\x20href=\"#go.mod-replace\"><code>replace</code>\x20directives</a>.</p>\x0a<p>Each\x20line\x20in\x20<code>go.sum</code>\x20has\x20three\x20fields\x20separated\x20by\x20spaces:\x20a\x20module\x20path,\x0aa\x20version\x20(possibly\x20ending\x20with\x20<code>/go.mod</code>),\x20and\x20a\x20hash.</p>\x0a<ul>\x0a<li>The\x20module\x20path\x20is\x20the\x20name\x20of\x20the\x20module\x20the\x20hash\x20belongs\x20to.</li>\x0a<li>The\x20version\x20is\x20the\x20version\x20of\x20the\x20module\x20the\x20hash\x20belongs\x20to.\x20If\x20the\x20version\x0aends\x20with\x20<code>/go.mod</code>,\x20the\x20hash\x20is\x20for\x20the\x20module's\x20<code>go.mod</code>\x20file\x20only;\x0aotherwise,\x20the\x20hash\x20is\x20for\x20the\x20files\x20within\x20the\x20module's\x20<code>.zip</code>\x20file.</li>\x0a<li>The\x20hash\x20column\x20consists\x20of\x20an\x20algorithm\x20name\x20(like\x20<code>h1</code>)\x20and\x20a\x20base64-encoded\x0acryptographic\x20hash,\x20separated\x20by\x20a\x20colon\x20(<code>:</code>).\x20Currently,\x20SHA-256\x20(<code>h1</code>)\x20is\x0athe\x20only\x20supported\x20hash\x20algorithm.\x20If\x20a\x20vulnerability\x20in\x20SHA-256\x20is\x20discovered\x0ain\x20the\x20future,\x20support\x20will\x20be\x20added\x20for\x20another\x20algorithm\x20(named\x20<code>h2</code>\x20and\x0aso\x20on).</li>\x0a</ul>\x0a<p>When\x20the\x20<code>go</code>\x20command\x20downloads\x20a\x20module\x20<code>.mod</code>\x20or\x20<code>.zip</code>\x20file\x20into\x20the\x20<a\x20href=\"#module-cache\">module\x0acache</a>,\x20it\x20computes\x20a\x20hash\x20and\x20checks\x20that\x20the\x20hash\x20matches\x20the\x0acorresponding\x20hash\x20in\x20the\x20main\x20module's\x20<code>go.sum</code>\x20file.\x20For\x20<code>.mod</code>\x20files,\x20the\x0afile\x20contents\x20are\x20hashed.\x20For\x20<code>.zip</code>\x20files,\x20the\x20files\x20within\x20the\x20archive\x20are\x0ahashed.\x20The\x20hash\x20is\x20not\x20affected\x20by\x20file\x20ordering,\x20compression,\x20alignment,\x20or\x0ametadata.\x20See\x20<a\x20href=\"#zip-files\">Module\x20zip\x20files</a>\x20for\x20information\x20on\x20which\x20files\x20are\x0aincluded.\x20See\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/sumdb/dirhash?tab=doc\"><code>golang.org/x/mod/sumdb/dirhash</code></a>\x0afor\x20hash\x20implementation\x20details.</p>\x0a<p>If\x20the\x20computed\x20hash\x20does\x20not\x20match\x20the\x20corresponding\x20hash\x20in\x20<code>go.sum</code>,\x20the\x20<code>go</code>\x0acommand\x20reports\x20a\x20security\x20error.\x20If\x20the\x20hash\x20is\x20not\x20present\x20in\x20<code>go.sum</code>,\x20the\x0a<code>go</code>\x20command\x20looks\x20up\x20the\x20correct\x20hash\x20in\x20the\x20<a\x20href=\"#checksum-database\">checksum\x0adatabase</a>\x20(unless\x20the\x20module\x20matches\x20<code>GONOSUMDB</code>\x20or\x0a<code>GOSUMDB</code>\x20is\x20set\x20to\x20<code>off</code>;\x20see\x20<a\x20href=\"#environment-variables\">Environment\x0avariables</a>).\x20If\x20no\x20mismatch\x20is\x20detected,\x20the\x20<code>go</code>\x0acommand\x20adds\x20the\x20hash\x20to\x20<code>go.sum</code>.</p>\x0a<p>The\x20<code>go</code>\x20command\x20does\x20not\x20automatically\x20verify\x20modules\x20already\x20in\x20the\x20cache.\x20By\x0adefault,\x20files\x20and\x20directories\x20in\x20the\x20module\x20cache\x20have\x20read-only\x20permissions\x20to\x0aprevent\x20accidental\x20changes.\x20The\x20<a\x20href=\"#go-mod-verify\"><code>go\x20mod\x20verify</code></a>\x20command\x20may\x20be\x0aused\x20to\x20check\x20that\x20<code>.zip</code>\x20files\x20and\x20extracted\x20directories\x20in\x20the\x20module\x20cache\x0amatch\x20hashes\x20recorded\x20when\x20they\x20were\x20downloaded.</p>\x0a<p>The\x20<code>go.sum</code>\x20file\x20may\x20contain\x20hashes\x20for\x20multiple\x20versions\x20of\x20a\x20module.\x20The\x20<code>go</code>\x0acommand\x20may\x20need\x20to\x20load\x20<code>go.mod</code>\x20files\x20from\x20multiple\x20versions\x20of\x20a\x20dependency\x0ain\x20order\x20to\x20perform\x20<a\x20href=\"#minimal-version-selection\">minimal\x20version\x20selection</a>.\x0a<code>go.sum</code>\x20may\x20also\x20contain\x20hashes\x20for\x20module\x20versions\x20that\x20aren't\x20needed\x20anymore\x0a(for\x20example,\x20after\x20an\x20upgrade).\x20<a\x20href=\"#go-mod-tidy\"><code>go\x20mod\x20tidy</code></a>\x20will\x20add\x20missing\x0ahashes\x20and\x20will\x20remove\x20unnecessary\x20hashes\x20from\x20<code>go.sum</code>.</p>\x0a<h3\x20id=\"checksum-database\">Checksum\x20database</h3>\x0a<p>The\x20checksum\x20database\x20is\x20a\x20global\x20source\x20of\x20<code>go.sum</code>\x20lines.\x20The\x20<code>go</code>\x20command\x20can\x0ause\x20this\x20in\x20many\x20situations\x20to\x20detect\x20misbehavior\x20by\x20proxies\x20or\x20origin\x20servers.</p>\x0a<p>The\x20checksum\x20database\x20allows\x20for\x20global\x20consistency\x20and\x20reliability\x20for\x20all\x0apublicly\x20available\x20module\x20versions.\x20It\x20makes\x20untrusted\x20proxies\x20possible\x20since\x0athey\x20can't\x20serve\x20the\x20wrong\x20code\x20without\x20it\x20going\x20unnoticed.\x20It\x20also\x20ensures\x0athat\x20the\x20bits\x20associated\x20with\x20a\x20specific\x20version\x20do\x20not\x20change\x20from\x20one\x20day\x20to\x0athe\x20next,\x20even\x20if\x20the\x20module's\x20author\x20subsequently\x20alters\x20the\x20tags\x20in\x20their\x0arepository.</p>\x0a<p>The\x20checksum\x20database\x20is\x20served\x20by\x20<a\x20href=\"https://sum.golang.org\">sum.golang.org</a>,\x0awhich\x20is\x20run\x20by\x20Google.\x20It\x20is\x20a\x20<a\x20href=\"https://research.swtch.com/tlog\">Transparent\x0aLog</a>\x20(or\x20\xe2\x80\x9cMerkle\x20Tree\xe2\x80\x9d)\x20of\x20<code>go.sum</code>\x20line\x0ahashes,\x20which\x20is\x20backed\x20by\x20<a\x20href=\"https://github.com/google/trillian\">Trillian</a>.\x20The\x0amain\x20advantage\x20of\x20a\x20Merkle\x20tree\x20is\x20that\x20independent\x20auditors\x20can\x20verify\x20that\x20it\x0ahasn't\x20been\x20tampered\x20with,\x20so\x20it\x20is\x20more\x20trustworthy\x20than\x20a\x20simple\x20database.</p>\x0a<p>The\x20<code>go</code>\x20command\x20interacts\x20with\x20the\x20checksum\x20database\x20using\x20the\x20protocol\x0aoriginally\x20outlined\x20in\x20<a\x20href=\"https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#checksum-database\">Proposal:\x20Secure\x20the\x20Public\x20Go\x20Module\x0aEcosystem</a>.</p>\x0a<p>The\x20table\x20below\x20specifies\x20queries\x20that\x20the\x20checksum\x20database\x20must\x20respond\x20to.\x0aFor\x20each\x20path,\x20<code>$base</code>\x20is\x20the\x20path\x20portion\x20of\x20the\x20checksum\x20database\x20URL,\x0a<code>$module</code>\x20is\x20a\x20module\x20path,\x20and\x20<code>$version</code>\x20is\x20a\x20version.\x20For\x20example,\x20if\x20the\x0achecksum\x20database\x20URL\x20is\x20<code>https://sum.golang.org</code>,\x20and\x20the\x20client\x20is\x20requesting\x0athe\x20record\x20for\x20the\x20module\x20<code>golang.org/x/text</code>\x20at\x20version\x20<code>v0.3.2</code>,\x20the\x20client\x0awould\x20send\x20a\x20<code>GET</code>\x20request\x20for\x0a<code>https://sum.golang.org/lookup/golang.org/x/text@v0.3.2</code>.</p>\x0a<p>To\x20avoid\x20ambiguity\x20when\x20serving\x20from\x20case-insensitive\x20file\x20systems,\x0athe\x20<code>$module</code>\x20and\x20<code>$version</code>\x20elements\x20are\x0a<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/module#EscapePath\">case-encoded</a>\x0aby\x20replacing\x20every\x20uppercase\x20letter\x20with\x20an\x20exclamation\x20mark\x20followed\x20by\x20the\x0acorresponding\x20lower-case\x20letter.\x20This\x20allows\x20modules\x20<code>example.com/M</code>\x20and\x0a<code>example.com/m</code>\x20to\x20both\x20be\x20stored\x20on\x20disk,\x20since\x20the\x20former\x20is\x20encoded\x20as\x0a<code>example.com/!m</code>.</p>\x0a<p>Parts\x20of\x20the\x20path\x20surrounded\x20by\x20square\x20brakets,\x20like\x20<code>[.p/$W]</code>\x20denote\x20optional\x0avalues.</p>\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Path</th>\x0a\x20\x20\x20\x20\x20\x20<th>Description</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/latest</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20a\x20signed,\x20encoded\x20tree\x20description\x20for\x20the\x20latest\x20log.\x20This\x0a\x20\x20\x20\x20\x20\x20\x20\x20signed\x20description\x20is\x20in\x20the\x20form\x20of\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"https://pkg.go.dev/golang.org/x/mod/sumdb/note\">note</a>,\x0a\x20\x20\x20\x20\x20\x20\x20\x20which\x20is\x20text\x20that\x20has\x20been\x20signed\x20by\x20one\x20or\x20more\x20server\x20keys\x20and\x20can\x0a\x20\x20\x20\x20\x20\x20\x20\x20be\x20verified\x20using\x20the\x20server's\x20public\x20key.\x20The\x20tree\x20description\x0a\x20\x20\x20\x20\x20\x20\x20\x20provides\x20the\x20size\x20of\x20the\x20tree\x20and\x20the\x20hash\x20of\x20the\x20tree\x20head\x20at\x20that\x0a\x20\x20\x20\x20\x20\x20\x20\x20size.\x20This\x20encoding\x20is\x20described\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code><a\x20href=\"https://pkg.go.dev/golang.org/x/mod/sumdb/tlog#FormatTree\">\x0a\x20\x20\x20\x20\x20\x20\x20\x20golang.org/x/mod/sumdb/tlog#FormatTree</a></code>.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/lookup/$module@$version</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20the\x20log\x20record\x20number\x20for\x20the\x20entry\x20about\x20<code>$module</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20at\x20<code>$version</code>,\x20followed\x20by\x20the\x20data\x20for\x20the\x20record\x20(that\x20is,\x0a\x20\x20\x20\x20\x20\x20\x20\x20the\x20<code>go.sum</code>\x20lines\x20for\x20<code>$module</code>\x20at\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>$version</code>)\x20and\x20a\x20signed,\x20encoded\x20tree\x20description\x20that\x0a\x20\x20\x20\x20\x20\x20\x20\x20contains\x20the\x20record.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/tile/$H/$L/$K[.p/$W]</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20a\x20[log\x20tile](https://research.swtch.com/tlog#serving_tiles),\x0a\x20\x20\x20\x20\x20\x20\x20\x20which\x20is\x20a\x20set\x20of\x20hashes\x20that\x20make\x20up\x20a\x20section\x20of\x20the\x20log.\x20Each\x20tile\x0a\x20\x20\x20\x20\x20\x20\x20\x20is\x20defined\x20in\x20a\x20two-dimensional\x20coordinate\x20at\x20tile\x20level\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>$L</code>,\x20<code>$K</code>th\x20from\x20the\x20left,\x20with\x20a\x20tile\x20height\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>$H</code>.\x20The\x20optional\x20<code>.p/$W</code>\x20suffix\x20indicates\x20a\x0a\x20\x20\x20\x20\x20\x20\x20\x20partial\x20log\x20tile\x20with\x20only\x20<code>$W</code>\x20hashes.\x20Clients\x20must\x20fall\x0a\x20\x20\x20\x20\x20\x20\x20\x20back\x20to\x20fetching\x20the\x20full\x20tile\x20if\x20a\x20partial\x20tile\x20is\x20not\x20found.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>$base/tile/$H/data/$K[.p/$W]</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Returns\x20the\x20record\x20data\x20for\x20the\x20leaf\x20hashes\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>/tile/$H/0/$K[.p/$W]</code>\x20(with\x20a\x20literal\x20<code>data</code>\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20element).\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<p>If\x20the\x20<code>go</code>\x20command\x20consults\x20the\x20checksum\x20database,\x20then\x20the\x20first\x0astep\x20is\x20to\x20retrieve\x20the\x20record\x20data\x20through\x20the\x20<code>/lookup</code>\x20endpoint.\x20If\x20the\x0amodule\x20version\x20is\x20not\x20yet\x20recorded\x20in\x20the\x20log,\x20the\x20checksum\x20database\x20will\x20try\x0ato\x20fetch\x20it\x20from\x20the\x20origin\x20server\x20before\x20replying.\x20This\x20<code>/lookup</code>\x20data\x0aprovides\x20the\x20sum\x20for\x20this\x20module\x20version\x20as\x20well\x20as\x20its\x20position\x20in\x20the\x20log,\x0awhich\x20informs\x20the\x20client\x20of\x20which\x20tiles\x20should\x20be\x20fetched\x20to\x20perform\x20proofs.\x0aThe\x20<code>go</code>\x20command\x20performs\x20\xe2\x80\x9cinclusion\xe2\x80\x9d\x20proofs\x20(that\x20a\x20specific\x20record\x20exists\x20in\x0athe\x20log)\x20and\x20\xe2\x80\x9cconsistency\xe2\x80\x9d\x20proofs\x20(that\x20the\x20tree\x20hasn\xe2\x80\x99t\x20been\x20tampered\x20with)\x0abefore\x20adding\x20new\x20<code>go.sum</code>\x20lines\x20to\x20the\x20main\x20module\xe2\x80\x99s\x20<code>go.sum</code>\x20file.\x20It's\x0aimportant\x20that\x20the\x20data\x20from\x20<code>/lookup</code>\x20should\x20never\x20be\x20used\x20without\x20first\x0aauthenticating\x20it\x20against\x20the\x20signed\x20tree\x20hash\x20and\x20authenticating\x20the\x20signed\x0atree\x20hash\x20against\x20the\x20client's\x20timeline\x20of\x20signed\x20tree\x20hashes.</p>\x0a<p>Signed\x20tree\x20hashes\x20and\x20new\x20tiles\x20served\x20by\x20the\x20checksum\x20database\x20are\x20stored\x0ain\x20the\x20module\x20cache,\x20so\x20the\x20<code>go</code>\x20command\x20only\x20needs\x20to\x20fetch\x20tiles\x20that\x20are\x0amissing.</p>\x0a<p>The\x20<code>go</code>\x20command\x20doesn't\x20need\x20to\x20directly\x20connect\x20to\x20the\x20checksum\x20database.\x20It\x0acan\x20request\x20module\x20sums\x20via\x20a\x20module\x20proxy\x20that\x0a<a\x20href=\"https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#proxying-a-checksum-database\">mirrors\x20the\x20checksum\x20database</a>\x0aand\x20supports\x20the\x20protocol\x20above.\x20This\x20can\x20be\x20particularly\x20helpful\x20for\x20private,\x0acorporate\x20proxies\x20which\x20block\x20requests\x20outside\x20the\x20organization.</p>\x0a<p>The\x20<code>GOSUMDB</code>\x20environment\x20variable\x20identifies\x20the\x20name\x20of\x20checksum\x20database\x20to\x20use\x0aand\x20optionally\x20its\x20public\x20key\x20and\x20URL,\x20as\x20in:</p>\x0a<pre><code>GOSUMDB=&quot;sum.golang.org&quot;\x0aGOSUMDB=&quot;sum.golang.org+&lt;publickey&gt;&quot;\x0aGOSUMDB=&quot;sum.golang.org+&lt;publickey&gt;\x20https://sum.golang.org&quot;\x0a</code></pre>\x0a<p>The\x20<code>go</code>\x20command\x20knows\x20the\x20public\x20key\x20of\x20<code>sum.golang.org</code>,\x20and\x20also\x20that\x20the\x0aname\x20<code>sum.golang.google.cn</code>\x20(available\x20inside\x20mainland\x20China)\x20connects\x20to\x20the\x0a<code>sum.golang.org</code>\x20checksum\x20database;\x20use\x20of\x20any\x20other\x20database\x20requires\x20giving\x0athe\x20public\x20key\x20explicitly.\x20The\x20URL\x20defaults\x20to\x20<code>https://</code>\x20followed\x20by\x20the\x0adatabase\x20name.</p>\x0a<p><code>GOSUMDB</code>\x20defaults\x20to\x20<code>sum.golang.org</code>,\x20the\x20Go\x20checksum\x20database\x20run\x20by\x20Google.\x0aSee\x20https://sum.golang.org/privacy\x20for\x20the\x20service's\x20privacy\x20policy.</p>\x0a<p>If\x20<code>GOSUMDB</code>\x20is\x20set\x20to\x20<code>off</code>,\x20or\x20if\x20<code>go\x20get</code>\x20is\x20invoked\x20with\x20the\x20<code>-insecure</code>\x0aflag,\x20the\x20checksum\x20database\x20is\x20not\x20consulted,\x20and\x20all\x20unrecognized\x20modules\x20are\x0aaccepted,\x20at\x20the\x20cost\x20of\x20giving\x20up\x20the\x20security\x20guarantee\x20of\x20verified\x0arepeatable\x20downloads\x20for\x20all\x20modules.\x20A\x20better\x20way\x20to\x20bypass\x20the\x20checksum\x0adatabase\x20for\x20specific\x20modules\x20is\x20to\x20use\x20the\x20<code>GOPRIVATE</code>\x20or\x20<code>GONOSUMDB</code>\x0aenvironment\x20variables.\x20See\x20<a\x20href=\"#private-modules\">Private\x20Modules</a>\x20for\x20details.</p>\x0a<p>The\x20<code>go\x20env\x20-w</code>\x20command\x20can\x20be\x20used\x20to\x0a<a\x20href=\"/pkg/cmd/go/#hdr-Print_Go_environment_information\">set\x20these\x20variables</a>\x0afor\x20future\x20<code>go</code>\x20command\x20invocations.</p>\x0a<h2\x20id=\"privacy\">Privacy</h2>\x0a<h2\x20id=\"environment-variables\">Environment\x20variables</h2>\x0a<p>Module\x20behavior\x20in\x20the\x20<code>go</code>\x20command\x20may\x20be\x20configured\x20using\x20the\x20environment\x0avariables\x20listed\x20below.\x20This\x20list\x20only\x20includes\x20module-related\x20environment\x0avariables.\x20See\x20<a\x20href=\"https://golang.org/cmd/go/#hdr-Environment_variables\"><code>go\x20help\x20environment</code></a>\x20for\x20a\x20list\x0aof\x20all\x20environment\x20variables\x20recognized\x20by\x20the\x20<code>go</code>\x20command.</p>\x0a<table\x20class=\"ModTable\">\x0a\x20\x20<thead>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<th>Variable</th>\x0a\x20\x20\x20\x20\x20\x20<th>Description</th>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</thead>\x0a\x20\x20<tbody>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GO111MODULE</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Controls\x20whether\x20the\x20<code>go</code>\x20command\x20runs\x20in\x20module-aware\x20mode\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20or\x20<code>GOPATH</code>\x20mode.\x20Three\x20values\x20are\x20recognized:\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<ul>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>off</code>:\x20the\x20<code>go</code>\x20command\x20ignores\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>go.mod</code>\x20files\x20and\x20runs\x20in\x20<code>GOPATH</code>\x20mode.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>on</code>:\x20the\x20<code>go</code>\x20command\x20runs\x20in\x20module-aware\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20mode,\x20even\x20when\x20no\x20<code>go.mod</code>\x20file\x20is\x20present.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>auto</code>\x20(or\x20unset):\x20the\x20<code>go</code>\x20command\x20runs\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20module-aware\x20mode\x20if\x20a\x20<code>go.mod</code>\x20file\x20is\x20present\x20in\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20current\x20directory\x20or\x20any\x20parent\x20directory\x20(the\x20default\x20behavior).\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20</ul>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20See\x20<a\x20href=\"mod-commands\">Module-aware\x20commands</a>\x20for\x20more\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20information.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOMODCACHE</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20directory\x20where\x20the\x20<code>go</code>\x20command\x20will\x20store\x20downloaded\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20modules\x20and\x20related\x20files.\x20See\x20<a\x20href=\"#module-cache\">Module\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20cache</a>\x20for\x20details\x20on\x20the\x20structure\x20of\x20this\x20directory.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GOMODCACHE</code>\x20is\x20not\x20set,\x20it\x20defaults\x20to\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>$GOPATH/pkg/mod</code>.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOINSECURE</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20glob\x20patterns\x20(in\x20the\x20syntax\x20of\x20Go's\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"/pkg/path/#Match\"><code>path.Match</code></a>)\x20of\x20module\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20prefixes\x20that\x20may\x20always\x20be\x20fetched\x20in\x20an\x20insecure\x20manner.\x20Only\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20applies\x20to\x20dependencies\x20that\x20are\x20being\x20fetched\x20directly.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Unlike\x20the\x20<code>-insecure</code>\x20flag\x20on\x20<code>go\x20get</code>,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOINSECURE</code>\x20does\x20not\x20disable\x20module\x20checksum\x20database\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20validation.\x20<code>GOPRIVATE</code>\x20or\x20<code>GONOSUMDB</code>\x20may\x20be\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20used\x20to\x20achieve\x20that.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GONOPROXY</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20glob\x20patterns\x20(in\x20the\x20syntax\x20of\x20Go's\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"/pkg/path/#Match\"><code>path.Match</code></a>)\x20of\x20module\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20prefixes\x20that\x20should\x20always\x20be\x20fetched\x20directly\x20from\x20version\x20control\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20repositories,\x20not\x20from\x20module\x20proxies.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GONOPROXY</code>\x20is\x20not\x20set,\x20it\x20defaults\x20to\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPRIVATE</code>.\x20See\x20<a\x20href=\"#privacy\">Privacy</a>.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GONOSUMDB</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20glob\x20patterns\x20(in\x20the\x20syntax\x20of\x20Go's\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"/pkg/path/#Match\"><code>path.Match</code></a>)\x20of\x20module\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20prefixes\x20for\x20which\x20the\x20<code>go</code>\x20should\x20not\x20verify\x20checksums\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20using\x20the\x20checksum\x20database.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GONOSUMDB</code>\x20is\x20not\x20set,\x20it\x20defaults\x20to\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPRIVATE</code>.\x20See\x20<a\x20href=\"#privacy\">Privacy</a>.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOPATH</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20In\x20<code>GOPATH</code>\x20mode,\x20the\x20<code>GOPATH</code>\x20variable\x20is\x20a\x20list\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20of\x20directories\x20that\x20may\x20contain\x20Go\x20code.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20In\x20module-aware\x20mode,\x20the\x20<a\x20href=\"#glos-module-cache\">module\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20cache</a>\x20is\x20stored\x20in\x20the\x20<code>pkg/mod</code>\x20subdirectory\x20of\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20first\x20<code>GOPATH</code>\x20directory.\x20Module\x20source\x20code\x20outside\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20cache\x20may\x20be\x20stored\x20in\x20any\x20directory.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GOPATH</code>\x20is\x20not\x20set,\x20it\x20defaults\x20to\x20the\x20<code>go</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20subdirectory\x20of\x20the\x20user's\x20home\x20directory.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOPRIVATE</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20glob\x20patterns\x20(in\x20the\x20syntax\x20of\x20Go's\x0a\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"/pkg/path/#Match\"><code>path.Match</code></a>)\x20of\x20module\x20path\x0a\x20\x20\x20\x20\x20\x20\x20\x20prefixes\x20that\x20should\x20be\x20considered\x20private.\x20<code>GOPRIVATE</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20is\x20a\x20default\x20value\x20for\x20<code>GONOPROXY</code>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20<code>GONOSUMDB</code>.\x20<code>GOPRIVATE</code>\x20itself\x20has\x20no\x20other\x0a\x20\x20\x20\x20\x20\x20\x20\x20meaning.\x20See\x20<a\x20href=\"#privacy\">Privacy</a>.\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOPROXY</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Comma-separated\x20list\x20of\x20module\x20proxy\x20URLs.\x20When\x20the\x20<code>go</code>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20command\x20looks\x20up\x20information\x20about\x20a\x20module,\x20it\x20will\x20contact\x20each\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20proxy\x20in\x20the\x20list,\x20in\x20sequence.\x20A\x20proxy\x20may\x20respond\x20with\x20a\x20404\x20(Not\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Found)\x20or\x20410\x20(Gone)\x20status\x20to\x20indicate\x20the\x20module\x20is\x20not\x20available\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20and\x20the\x20<code>go</code>\x20command\x20should\x20contact\x20the\x20next\x20proxy\x20in\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20the\x20list.\x20Any\x20other\x20error\x20will\x20cause\x20the\x20<code>go</code>\x20command\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20to\x20stop\x20without\x20contacting\x20other\x20proxies\x20in\x20the\x20list.\x20This\x20allows\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20a\x20proxy\x20to\x20act\x20as\x20a\x20gatekeeper,\x20for\x20example,\x20by\x20responding\x20with\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20403\x20(Forbidden)\x20for\x20modules\x20not\x20on\x20an\x20approved\x20list.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPROXY</code>\x20URLs\x20may\x20have\x20the\x20schemes\x20<code>https</code>,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>http</code>,\x20or\x20<code>file</code>.\x20If\x20no\x20scheme\x20is\x20specified,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>https</code>\x20is\x20assumed.\x20A\x20module\x20cache\x20may\x20be\x20used\x20direclty\x20as\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20a\x20file\x20proxy:\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<pre>GOPROXY=file://$(go\x20env\x20GOPATH)/pkg/mod/cache/download</pre>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>Two\x20keywords\x20may\x20be\x20used\x20in\x20place\x20of\x20proxy\x20URLs:</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<ul>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>off</code>:\x20disallows\x20downloading\x20modules\x20from\x20any\x20source.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>direct</code>:\x20download\x20directly\x20from\x20version\x20control\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20repositories.\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20</li>\x0a\x20\x20\x20\x20\x20\x20\x20\x20</ul>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPROXY</code>\x20defaults\x20to\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>https://proxy.golang.org,direct</code>.\x20Under\x20that\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20configuration,\x20the\x20<code>go</code>\x20command\x20will\x20first\x20contact\x20the\x20Go\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20module\x20mirror\x20run\x20by\x20Google,\x20then\x20fall\x20back\x20to\x20a\x20direct\x20connection\x20if\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20the\x20mirror\x20does\x20not\x20have\x20the\x20module.\x20See\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"https://proxy.golang.org/privacy\">https://proxy.golang.org/privacy</a>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20for\x20the\x20mirror's\x20privacy\x20policy.\x20The\x20<code>GOPRIVATE</code>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GONOPROXY</code>\x20environment\x20variables\x20may\x20be\x20set\x20to\x20prevent\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20specific\x20modules\x20from\x20being\x20downloaded\x20using\x20proxies.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20See\x20<a\x20href=\"#module-proxy\">Module\x20proxies</a>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#resolve-pkg-mod\">Resolving\x20a\x20package\x20to\x20a\x20module</a>\x20for\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20more\x20information.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20\x20\x20<tr>\x0a\x20\x20\x20\x20\x20\x20<td><code>GOSUMDB</code></td>\x0a\x20\x20\x20\x20\x20\x20<td>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Identifies\x20the\x20name\x20of\x20the\x20checksum\x20database\x20to\x20use\x20and\x20optionally\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20its\x20public\x20key\x20and\x20URL.\x20For\x20example:\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<pre>\x0aGOSUMDB=\"sum.golang.org\"\x0aGOSUMDB=\"sum.golang.org+&lt;publickey&gt;\"\x0aGOSUMDB=\"sum.golang.org+&lt;publickey&gt;\x20https://sum.golang.org\x0a</pre>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20The\x20<code>go</code>\x20command\x20knows\x20the\x20public\x20key\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>sum.golang.org</code>\x20and\x20also\x20that\x20the\x20name\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>sum.golang.google.cn</code>\x20(available\x20inside\x20mainland\x20China)\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20connects\x20to\x20the\x20<code>sum.golang.org</code>\x20database;\x20use\x20of\x20any\x20other\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20database\x20requires\x20giving\x20the\x20public\x20key\x20explicitly.\x20The\x20URL\x20defaults\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20to\x20<code>https://</code>\x20followed\x20by\x20the\x20database\x20name.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOSUMDB</code>\x20defaults\x20to\x20<code>sum.golang.org</code>,\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20Go\x20checksum\x20database\x20run\x20by\x20Google.\x20See\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"https://sum.golang.org/privacy\">https://sum.golang.org/privacy</a>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20for\x20the\x20service's\x20privacy\x20policy.\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20If\x20<code>GOSUMDB</code>\x20is\x20set\x20to\x20<code>off</code>\x20or\x20if\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>go\x20get</code>\x20is\x20invoked\x20with\x20the\x20<code>-insecure</code>\x20flag,\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20the\x20checksum\x20database\x20is\x20not\x20consulted,\x20and\x20all\x20unrecognized\x20modules\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20are\x20accepted,\x20at\x20the\x20cost\x20of\x20giving\x20up\x20the\x20security\x20guarantee\x20of\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20verified\x20repeatable\x20downloads\x20for\x20all\x20modules.\x20A\x20better\x20way\x20to\x20bypass\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20the\x20checksum\x20database\x20for\x20specific\x20modules\x20is\x20to\x20use\x20the\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<code>GOPRIVATE</code>\x20or\x20<code>GONOSUMDB</code>\x20environment\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20variables.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20<p>\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20See\x20<a\x20href=\"#authenticating\">Authenticating\x20modules</a>\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20<a\x20href=\"#privacy\">Privacy</a>\x20for\x20more\x20information.\x0a\x20\x20\x20\x20\x20\x20\x20\x20</p>\x0a\x20\x20\x20\x20\x20\x20</td>\x0a\x20\x20\x20\x20</tr>\x0a\x20\x20</tbody>\x0a</table>\x0a<h2\x20id=\"glossary\">Glossary</h2>\x0a<p><a\x20id=\"glos-build-constraint\"></a>\x0a<strong>build\x20constraint:</strong>\x20A\x20condition\x20that\x20determines\x20whether\x20a\x20Go\x20source\x20file\x20is\x0aused\x20when\x20compiling\x20a\x20package.\x20Build\x20constraints\x20may\x20be\x20expressed\x20with\x20file\x20name\x0asuffixes\x20(for\x20example,\x20<code>foo_linux_amd64.go</code>)\x20or\x20with\x20build\x20constraint\x20comments\x0a(for\x20example,\x20<code>//\x20+build\x20linux,amd64</code>).\x20See\x20<a\x20href=\"https://golang.org/pkg/go/build/#hdr-Build_Constraints\">Build\x0aConstraints</a>.</p>\x0a<p><a\x20id=\"glos-build-list\"></a>\x0a<strong>build\x20list:</strong>\x20The\x20list\x20of\x20module\x20versions\x20that\x20will\x20be\x20used\x20for\x20a\x20build\x0acommand\x20such\x20as\x20<code>go\x20build</code>,\x20<code>go\x20list</code>,\x20or\x20<code>go\x20test</code>.\x20The\x20build\x20list\x20is\x0adetermined\x20from\x20the\x20<a\x20href=\"#glos-main-module\">main\x20module's</a>\x20<a\x20href=\"#glos-go.mod-file\"><code>go.mod</code>\x0afile</a>\x20and\x20<code>go.mod</code>\x20files\x20in\x20transitively\x20required\x20modules\x0ausing\x20<a\x20href=\"#glos-minimal-version-selection\">minimal\x20version\x20selection</a>.\x20The\x20build\x0alist\x20contains\x20versions\x20for\x20all\x20modules\x20in\x20the\x20<a\x20href=\"#glos-module-graph\">module\x0agraph</a>,\x20not\x20just\x20those\x20relevant\x20to\x20a\x20specific\x20command.</p>\x0a<p><a\x20id=\"glos-canonical-version\"></a>\x0a<strong>canonical\x20version:</strong>\x20A\x20correctly\x20formatted\x20<a\x20href=\"#glos-version\">version</a>\x20without\x0aa\x20build\x20metadata\x20suffix\x20other\x20than\x20<code>+incompatible</code>.\x20For\x20example,\x20<code>v1.2.3</code>\x0ais\x20a\x20canonical\x20version,\x20but\x20<code>v1.2.3+meta</code>\x20is\x20not.</p>\x0a<p><a\x20id=\"glos-go.mod-file\"></a>\x0a<strong><code>go.mod</code>\x20file:</strong>\x20The\x20file\x20that\x20defines\x20a\x20module's\x20path,\x20requirements,\x20and\x0aother\x20metadata.\x20Appears\x20in\x20the\x20<a\x20href=\"#glos-module-root-directory\">module's\x20root\x0adirectory</a>.\x20See\x20the\x20section\x20on\x20<a\x20href=\"#go.mod-files\"><code>go.mod</code>\x0afiles</a>.</p>\x0a<p><a\x20id=\"glos-import-path\"></a>\x0a<strong>import\x20path:</strong>\x20A\x20string\x20used\x20to\x20import\x20a\x20package\x20in\x20a\x20Go\x20source\x20file.\x0aSynonymous\x20with\x20<a\x20href=\"#glos-package-path\">package\x20path</a>.</p>\x0a<p><a\x20id=\"glos-main-module\"></a>\x0a<strong>main\x20module:</strong>\x20The\x20module\x20in\x20which\x20the\x20<code>go</code>\x20command\x20is\x20invoked.</p>\x0a<p><a\x20id=\"glos-major-version\"></a>\x0a<strong>major\x20version:</strong>\x20The\x20first\x20number\x20in\x20a\x20semantic\x20version\x20(<code>1</code>\x20in\x20<code>v1.2.3</code>).\x20In\x0aa\x20release\x20with\x20incompatible\x20changes,\x20the\x20major\x20version\x20must\x20be\x20incremented,\x20and\x0athe\x20minor\x20and\x20patch\x20versions\x20must\x20be\x20set\x20to\x200.\x20Semantic\x20versions\x20with\x20major\x0aversion\x200\x20are\x20considered\x20unstable.</p>\x0a<p><a\x20id=\"glos-major-version-subdirectory\"></a>\x0a<strong>major\x20version\x20subdirectory:</strong>\x20A\x20subdirectory\x20within\x20a\x20version\x20control\x0arepository\x20matching\x20a\x20module's\x20<a\x20href=\"#glos-major-version-suffix\">major\x20version\x0asuffix</a>\x20where\x20a\x20module\x20may\x20be\x20defined.\x20For\x20example,\x0athe\x20module\x20<code>example.com/mod/v2</code>\x20in\x20the\x20repository\x20with\x20<a\x20href=\"#glos-repository-root-path\">root\x0apath</a>\x20<code>example.com/mod</code>\x20may\x20be\x20defined\x20in\x20the\x0arepository\x20root\x20directory\x20or\x20the\x20major\x20version\x20subdirectory\x20<code>v2</code>.\x20See\x20<a\x20href=\"#vcs-dir\">Module\x0adirectories\x20within\x20a\x20repository</a>.</p>\x0a<p><a\x20id=\"glos-major-version-suffix\"></a>\x0a<strong>major\x20version\x20suffix:</strong>\x20A\x20module\x20path\x20suffix\x20that\x20matches\x20the\x20major\x20version\x0anumber.\x20For\x20example,\x20<code>/v2</code>\x20in\x20<code>example.com/mod/v2</code>.\x20Major\x20version\x20suffixes\x20are\x0arequired\x20at\x20<code>v2.0.0</code>\x20and\x20later\x20and\x20are\x20not\x20allowed\x20at\x20earlier\x20versions.\x20See\x0athe\x20section\x20on\x20<a\x20href=\"#major-version-suffixes\">Major\x20version\x20suffixes</a>.</p>\x0a<p><a\x20id=\"glos-minimal-version-selection\"></a>\x0a<strong>minimal\x20version\x20selection\x20(MVS):</strong>\x20The\x20algorithm\x20used\x20to\x20determine\x20the\x0aversions\x20of\x20all\x20modules\x20that\x20will\x20be\x20used\x20in\x20a\x20build.\x20See\x20the\x20section\x20on\x0a<a\x20href=\"#minimal-version-selection\">Minimal\x20version\x20selection</a>\x20for\x20details.</p>\x0a<p><a\x20id=\"glos-minor-version\"></a>\x0a<strong>minor\x20version:</strong>\x20The\x20second\x20number\x20in\x20a\x20semantic\x20version\x20(<code>2</code>\x20in\x20<code>v1.2.3</code>).\x20In\x0aa\x20release\x20with\x20new,\x20backwards\x20compatible\x20functionality,\x20the\x20minor\x20version\x20must\x0abe\x20incremented,\x20and\x20the\x20patch\x20version\x20must\x20be\x20set\x20to\x200.</p>\x0a<p><a\x20id=\"glos-module\"></a>\x0a<strong>module:</strong>\x20A\x20collection\x20of\x20packages\x20that\x20are\x20released,\x20versioned,\x20and\x0adistributed\x20together.</p>\x0a<p><a\x20id=\"glos-module-cache\"></a>\x0a<strong>module\x20cache:</strong>\x20A\x20local\x20directory\x20storing\x20downloaded\x20modules,\x20located\x20in\x0a<code>GOPATH/pkg/mod</code>.\x20See\x20<a\x20href=\"#module-cache\">Module\x20cache</a>.</p>\x0a<p><a\x20id=\"glos-module-graph\"></a>\x0a<strong>module\x20graph:</strong>\x20The\x20directed\x20graph\x20of\x20module\x20requirements,\x20rooted\x20at\x20the\x20<a\x20href=\"#glos-main-module\">main\x0amodule</a>.\x20Each\x20vertex\x20in\x20the\x20graph\x20is\x20a\x20module;\x20each\x20edge\x20is\x20a\x0aversion\x20from\x20a\x20<code>require</code>\x20statement\x20in\x20a\x20<code>go.mod</code>\x20file\x20(subject\x20to\x20<code>replace</code>\x20and\x0a<code>exclude</code>\x20statements\x20in\x20the\x20main\x20module's\x20<code>go.mod</code>\x20file.</p>\x0a<p><a\x20id=\"glos-module-path\"></a>\x0a<strong>module\x20path:</strong>\x20A\x20path\x20that\x20identifies\x20a\x20module\x20and\x20acts\x20as\x20a\x20prefix\x20for\x0apackage\x20import\x20paths\x20within\x20the\x20module.\x20For\x20example,\x20<code>&quot;golang.org/x/net&quot;</code>.</p>\x0a<p><a\x20id=\"glos-module-proxy\"></a>\x0a<strong>module\x20proxy:</strong>\x20A\x20web\x20server\x20that\x20implements\x20the\x20<a\x20href=\"#goproxy-protocol\"><code>GOPROXY</code>\x0aprotocol</a>.\x20The\x20<code>go</code>\x20command\x20downloads\x20version\x20information,\x0a<code>go.mod</code>\x20files,\x20and\x20module\x20zip\x20files\x20from\x20module\x20proxies.</p>\x0a<p><a\x20id=\"glos-module-root-directory\"></a>\x0a<strong>module\x20root\x20directory:</strong>\x20The\x20directory\x20that\x20contains\x20the\x20<code>go.mod</code>\x20file\x20that\x0adefines\x20a\x20module.</p>\x0a<p><a\x20id=\"glos-module-subdirectory\"></a>\x0a<strong>module\x20subdirectory:</strong>\x20The\x20portion\x20of\x20a\x20<a\x20href=\"#glos-module-path\">module\x20path</a>\x20after\x0athe\x20<a\x20href=\"#glos-repository-root-path\">repository\x20root\x20path</a>\x20that\x20indicates\x20the\x0asubdirectory\x20where\x20the\x20module\x20is\x20defined.\x20When\x20non-empty,\x20the\x20module\x0asubdirectory\x20is\x20also\x20a\x20prefix\x20for\x20<a\x20href=\"#glos-semantic-version-tag\">semantic\x20version\x0atags</a>.\x20The\x20module\x20subdirectory\x20does\x20not\x20include\x20the\x0a<a\x20href=\"#glos-major-version-suffix\">major\x20version\x20suffix</a>,\x20if\x20there\x20is\x20one,\x20even\x20if\x20the\x0amodule\x20is\x20in\x20a\x20<a\x20href=\"#glos-major-version-subdirectory\">major\x20version\x20subdirectory</a>.\x0aSee\x20<a\x20href=\"#module-path\">Module\x20paths</a>.</p>\x0a<p><a\x20id=\"glos-package\"></a>\x0a<strong>package:</strong>\x20A\x20collection\x20of\x20source\x20files\x20in\x20the\x20same\x20directory\x20that\x20are\x0acompiled\x20together.\x20See\x20the\x20<a\x20href=\"/ref/spec#Packages\">Packages\x20section</a>\x20in\x20the\x20Go\x0aLanguage\x20Specification.</p>\x0a<p><a\x20id=\"glos-package-path\"></a>\x0a<strong>package\x20path:</strong>\x20The\x20path\x20that\x20uniquely\x20identifies\x20a\x20package.\x20A\x20package\x20path\x20is\x0aa\x20<a\x20href=\"#glos-module-path\">module\x20path</a>\x20joined\x20with\x20a\x20subdirectory\x20within\x20the\x20module.\x0aFor\x20example\x20<code>&quot;golang.org/x/net/html&quot;</code>\x20is\x20the\x20package\x20path\x20for\x20the\x20package\x20in\x20the\x0amodule\x20<code>&quot;golang.org/x/net&quot;</code>\x20in\x20the\x20<code>&quot;html&quot;</code>\x20subdirectory.\x20Synonym\x20of\x0a<a\x20href=\"#glos-import-path\">import\x20path</a>.</p>\x0a<p><a\x20id=\"glos-patch-version\"></a>\x0a<strong>patch\x20version:</strong>\x20The\x20third\x20number\x20in\x20a\x20semantic\x20version\x20(<code>3</code>\x20in\x20<code>v1.2.3</code>).\x20In\x0aa\x20release\x20with\x20no\x20changes\x20to\x20the\x20module's\x20public\x20interface,\x20the\x20patch\x20version\x0amust\x20be\x20incremented.</p>\x0a<p><a\x20id=\"glos-pre-release-version\"></a>\x0a<strong>pre-release\x20version:</strong>\x20A\x20version\x20with\x20a\x20dash\x20followed\x20by\x20a\x20series\x20of\x0adot-separated\x20identifiers\x20immediately\x20following\x20the\x20patch\x20version,\x20for\x20example,\x0a<code>v1.2.3-beta4</code>.\x20Pre-release\x20versions\x20are\x20considered\x20unstable\x20and\x20are\x20not\x0aassumed\x20to\x20be\x20compatible\x20with\x20other\x20versions.\x20A\x20pre-release\x20version\x20sorts\x20before\x0athe\x20corresponding\x20release\x20version:\x20<code>v1.2.3-pre</code>\x20comes\x20before\x20<code>v1.2.3</code>.\x20See\x20also\x0a<a\x20href=\"#glos-release-version\">release\x20version</a>.</p>\x0a<p><a\x20id=\"glos-pseudo-version\"></a>\x0a<strong>pseudo-version:</strong>\x20A\x20version\x20that\x20encodes\x20a\x20revision\x20identifier\x20(such\x20as\x20a\x20Git\x0acommit\x20hash)\x20and\x20a\x20timestamp\x20from\x20a\x20version\x20control\x20system.\x20For\x20example,\x0a<code>v0.0.0-20191109021931-daa7c04131f5</code>.\x20Used\x20for\x20<a\x20href=\"#non-module-compat\">compatibility\x20with\x20non-module\x0arepositories</a>\x20and\x20in\x20other\x20situations\x20when\x20a\x20tagged\x0aversion\x20is\x20not\x20available.</p>\x0a<p><a\x20id=\"glos-release-version\"></a>\x0a<strong>release\x20version:</strong>\x20A\x20version\x20without\x20a\x20pre-release\x20suffix.\x20For\x20example,\x0a<code>v1.2.3</code>,\x20not\x20<code>v1.2.3-pre</code>.\x20See\x20also\x20<a\x20href=\"#glos-pre-release-version\">pre-release\x0aversion</a>.</p>\x0a<p><a\x20id=\"glos-repository-root-path\"></a>\x0a<strong>repository\x20root\x20path:</strong>\x20The\x20portion\x20of\x20a\x20<a\x20href=\"#glos-module-path\">module\x20path</a>\x20that\x0acorresponds\x20to\x20a\x20version\x20control\x20repository's\x20root\x20directory.\x20See\x20<a\x20href=\"#module-path\">Module\x0apaths</a>.</p>\x0a<p><a\x20id=\"glos-semantic-version-tag\"></a>\x0a<strong>semantic\x20version\x20tag:</strong>\x20A\x20tag\x20in\x20a\x20version\x20control\x20repository\x20that\x20maps\x20a\x0a<a\x20href=\"#glos-version\">version</a>\x20to\x20a\x20specific\x20revision.\x20See\x20<a\x20href=\"#vcs-version\">Mapping\x20versions\x20to\x0acommits</a>.</p>\x0a<p><a\x20id=\"glos-version\"></a>\x0a<strong>version:</strong>\x20An\x20identifier\x20for\x20an\x20immutable\x20snapshot\x20of\x20a\x20module,\x20written\x20as\x20the\x0aletter\x20<code>v</code>\x20followed\x20by\x20a\x20semantic\x20version.\x20See\x20the\x20section\x20on\x0a<a\x20href=\"#versions\">Versions</a>.</p>\x0a",
 }
diff --git a/internal/markdown/markdown.go b/internal/markdown/markdown.go
index e40a58d..a729b9f 100644
--- a/internal/markdown/markdown.go
+++ b/internal/markdown/markdown.go
@@ -13,6 +13,7 @@
 	"bytes"
 
 	"github.com/yuin/goldmark"
+	"github.com/yuin/goldmark/parser"
 	"github.com/yuin/goldmark/renderer/html"
 )
 
@@ -24,8 +25,11 @@
 // untrusted content is not performed: the caller is responsible for ensuring
 // that only trusted content is provided.
 func Render(src []byte) ([]byte, error) {
+	// parser.WithHeadingAttribute allows custom ids on headings.
 	// html.WithUnsafe allows use of raw HTML, which we need for tables.
-	md := goldmark.New(goldmark.WithRendererOptions(html.WithUnsafe()))
+	md := goldmark.New(
+		goldmark.WithParserOptions(parser.WithHeadingAttribute()),
+		goldmark.WithRendererOptions(html.WithUnsafe()))
 	var buf bytes.Buffer
 	if err := md.Convert(src, &buf); err != nil {
 		return nil, err