content/static/doc: add section on version queries
Updates golang/go#33637
Change-Id: I23559e47e28cc3a37e0fc1e5acea53906f812935
Reviewed-on: https://go-review.googlesource.com/c/website/+/219481
Run-TryBot: Jay Conrod <jayconrod@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Michael Matloob <matloob@golang.org>
diff --git a/content/static/doc/modules.md b/content/static/doc/modules.md
index 75a69c4..ff5de71 100644
--- a/content/static/doc/modules.md
+++ b/content/static/doc/modules.md
@@ -976,6 +976,60 @@
<a id="version-queries"></a>
### 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
+on the command line.
+
+Examples:
+
+```
+go get example.com/m@latest
+go mod download example.com/m@master
+go list -m -json example.com/m@e3702bed2
+```
+
+A version query may be one of the following:
+
+* A fully-specified semantic version, such as `v1.2.3`, which selects a
+ specific version. See [Versions](#versions) for syntax.
+* A semantic version prefix, such as `v1` or `v1.2`, which selects the highest
+ available version with that prefix.
+* A semantic version comparison, such as `<v1.2.3` or `>=v1.5.6`, which selects
+ the nearest available version to the comparison target (the lowest version
+ for `>` and `>=`, and the highest version for `<` and `<=`).
+* A revision identifier for the underlying source repository, such as a commit
+ hash prefix, revision tag, or branch name. If the revision is tagged with a
+ semantic version, this query selects that version. Otherwise, this query
+ selects a [pseudo-version](#glos-pseudo-version) for the underlying
+ commit. Note that branches and tags with names matched by other version
+ queries cannot be selected this way. For example, the query `v2` selects the
+ latest version starting with `v2`, not the branch named `v2`.
+* The string `latest`, which selects the highest available release version. If
+ there are no release versions, `latest` selects the highest pre-release
+ version. If there no tagged versions, `latest` selects a pseudo-version for
+ the commit at the tip of the repository's default branch.
+* The string `upgrade`, which is like `latest` except that if the module is
+ currently required at a higher version than the version `latest` would select
+ (for example, a pre-release), `upgrade` will select the current version.
+* The string `patch`, which selects the latest available version with the same
+ major and minor version numbers as the currently required version. If no
+ version is currently required, `patch` is equivalent to `latest`.
+
+Except for queries for specific named versions or revisions, all queries
+consider available versions reported by `go list -m -versions` (see [`go list
+-m`](#go-list-m)). This list contains only tagged versions, not pseudo-versions.
+Module versions disallowed by [exclude](#go.mod-exclude) directives in
+the main module's [`go.mod` file](#glos-go.mod-file) are not considered.
+
+[Release versions](#glos-release-version) are preferred over pre-release
+versions. For example, if versions `v1.2.2` and `v1.2.3-pre` are available, the
+`latest` query will select `v1.2.2`, even though `v1.2.3-pre` is higher. The
+`<v1.2.4` query would also select `v1.2.2`, even though `v1.2.3-pre` is closer
+to `v1.2.4`. If no release or pre-release version is available, the `latest`,
+`upgrade`, and `patch` queries will select a pseudo-version for the commit
+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
diff --git a/content/static/static.go b/content/static/static.go
index 719ee53..10f8e9e 100644
--- a/content/static/static.go
+++ b/content/static/static.go
@@ -109,5 +109,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.ModProtocol\x20{\x0a\x20\x20border-collapse:\x20collapse;\x0a\x20\x20margin:\x201.25rem;\x0a\x20\x20max-width:\x2050rem;\x0a}\x0a.ModProtocol\x20td,\x0a.ModProtocol\x20th\x20{\x0a\x20\x20border:\x201px\x20solid\x20#a9a9a9;\x0a\x20\x20padding:\x201rem;\x0a\x20\x20vertical-align:\x20top;\x0a}\x0a.ModProtocol\x20td\x20p\x20{\x0a\x20\x20margin:\x200\x200\x201rem\x200;\x0a}\x0a.ModProtocol\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\x20\x20\x20background:\x20#E0EBF5;\x0a\x20\x20\x20\x20border:\x200.0625rem\x20solid\x20#375EAB;\x0a\x20\x20\x20\x20border-radius:\x200.3125rem;\x0a\x20\x20\x20\x20color:\x20#222;\x0a\x20\x20\x20\x20display:\x20block;\x0a\x20\x20\x20\x20padding:\x200.625rem;\x0a\x20\x20\x20\x20text-align:\x20center;\x0a\x20\x20\x20\x20text-decoration:\x20none;\x0a}\x0aa#start\x20.big\x20{\x0a\x20\x20\x20\x20display:\x20block;\x0a\x20\x20\x20\x20font-size:\x201.25rem;\x0a\x20\x20\x20\x20font-weight:\x20bold;\x0a}\x0aa#start\x20.desc\x20{\x0a\x20\x20\x20\x20display:\x20block;\x0a\x20\x20\x20\x20font-size:\x200.875rem;\x0a\x20\x20\x20\x20font-weight:\x20normal;\x0a\x20\x20\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-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\x20height:\x205.125rem;\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/modules.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/modules\"\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>"golang.org/x/net"</code>\x20contains\x20a\x20package\x20in\x20the\x20directory\x20<code>"html"</code>.\x20That\x0apackage's\x20path\x20is\x20<code>"golang.org/x/net/html"</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\x20subdirectory\x0awithin\x20the\x20repository\x20(usually\x20empty),\x20and\x20a\x20major\x20version\x20suffix\x20(for\x20major\x0aversion\x202\x20or\x20higher).</p>\x0a<ul>\x0a<li>The\x20repository\x20root\x20path\x20is\x20part\x20of\x20a\x20URL\x20that\x20corresponds\x20to\x20a\x20version\x0acontrol\x20repository.\x20For\x20example,\x20<code>golang.org/x/net</code>.\x20See\x20<a\x20href=\"#custom-import-paths\">Custom\x20import\x0apaths</a>\x20for\x20details\x20on\x20how\x20paths\x20are\x20resolved\x20to\x0arepositories.</li>\x0a<li>If\x20the\x20module\x20is\x20in\x20a\x20subdirectory\x20of\x20the\x20version\x20control\x20repository,\x20the\x0asubdirectory\x20should\x20be\x20part\x20of\x20the\x20module\x20path\x20(but\x20not\x20the\x20repository\x20root\x0apath).\x20For\x20example,\x20the\x20module\x20<code>golang.org/x/tools/gopls</code>\x20is\x20in\x20the\x20<code>/gopls</code>\x0asubdirectory\x20of\x20the\x20repository\x20<code>golang.org/x/tools</code>.</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\">major\x20version\x20suffix</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=\"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=\"#communicating-with-vcs\">communicate\x20with\x20a\x20version\x20control\x20system</a>.\x20<code>off</code>\x0aindicates\x20that\x20no\x20communication\x20should\x20be\x20attempted.\x20The\x20<code>GOPRIVATE</code>\x20and\x0a<code>GONOPROXY</code>\x20<a\x20href=\"#environment-variables\">environment\x20variables</a>\x20can\x20also\x20be\x20used\x20to\x0acontrol\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=>\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>=></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>"</code>,\x20U+0022)\x20and\x0araw\x20strings\x20beginning\x20and\x20ending\x20with\x20grave\x20accents\x20(<code><</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>\\"</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>\\"</code>\x20is\x20replaced\x20by\x20<code>"</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"module"\x20(\x20ModulePath\x20|\x20"("\x20newline\x20ModulePath\x20newline\x20")"\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"go"\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"require"\x20(\x20RequireSpec\x20|\x20"("\x20newline\x20{\x20RequireSpec\x20}\x20")"\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"exclude"\x20(\x20ExcludeSpec\x20|\x20"("\x20newline\x20{\x20ExcludeSpec\x20}\x20")"\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>=></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"replace"\x20(\x20ReplaceSpec\x20|\x20"("\x20newline\x20{\x20ReplaceSpec\x20}\x20")"\x20newline\x20")"\x20)\x20.\x0aReplaceSpec\x20=\x20ModulePath\x20[\x20Version\x20]\x20"=>"\x20FilePath\x20newline\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20|\x20ModulePath\x20[\x20Version\x20]\x20"=>"\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=>\x20example.com/fork/net\x20v1.4.5\x0a\x0areplace\x20(\x0a\x20\x20\x20\x20golang.org/x/net\x20v1.2.3\x20=>\x20example.com/fork/net\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/net\x20=>\x20example.com/fork/net\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/net\x20v1.2.3\x20=>\x20./fork/net\x0a\x20\x20\x20\x20golang.org/x/net\x20=>\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><a\x20id=\"non-module-compat\"></a></p>\x0a<h2>Compatibility\x20with\x20non-module\x20repositories</h2>\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><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\x20package\x20in\x20the\x20main\x20module.\x0a$\x20go\x20get\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=>\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=>\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><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><a\x20id=\"go-mod-verify\"></a></p>\x0a<h3><code>go\x20mod\x20verify</code></h3>\x0a<p><a\x20id=\"go-clean-modcache\"></a></p>\x0a<h3><code>go\x20clean\x20-modcache</code></h3>\x0a<p><a\x20id=\"version-queries\"></a></p>\x0a<h3>Version\x20queries</h3>\x0a<p><a\x20id=\"commands-outside\"></a></p>\x0a<h3>Module\x20commands\x20outside\x20a\x20module</h3>\x0a<p><a\x20id=\"retrieving-modules\"></a></p>\x0a<h2>Retrieving\x20modules</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=\"ModProtocol\">\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-format\">Module\x20zip\x20format</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-file-format\"><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><a\x20id=\"communicating-with-vcs\"></a></p>\x0a<h3>Communicating\x20with\x20version\x20control\x20systems</h3>\x0a<p><a\x20id=\"custom-import-paths\"></a></p>\x0a<h3>Custom\x20import\x20paths</h3>\x0a<!--\x20TODO(jayconrod):\x20custom\x20import\x20paths,\x20details\x20of\x20direct\x20mode\x20-->\x0a<p><a\x20id=\"path-constraints\"></a></p>\x0a<h3>File\x20name\x20and\x20path\x20constraints</h3>\x0a<p><a\x20id=\"zip-format\"></a></p>\x0a<h3>Module\x20zip\x20format</h3>\x0a<p><a\x20id=\"private-modules\"></a></p>\x0a<h3>Private\x20modules</h3>\x0a<p><a\x20id=\"module-cache\"></a></p>\x0a<h3>Module\x20cache</h3>\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-file-format\"></a></p>\x0a<h3>go.sum\x20file\x20format</h3>\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=\"ModProtocol\">\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="sum.golang.org"\x0aGOSUMDB="sum.golang.org+<publickey>"\x0aGOSUMDB="sum.golang.org+<publickey>\x20https://sum.golang.org"\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><a\x20id=\"glossary\"></a></p>\x0a<h2>Glossary</h2>\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-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>"golang.org/x/net"</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-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>"golang.org/x/net/html"</code>\x20is\x20the\x20package\x20path\x20for\x20the\x20package\x20in\x20the\x0amodule\x20<code>"golang.org/x/net"</code>\x20in\x20the\x20<code>"html"</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-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/modules.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/modules\"\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>"golang.org/x/net"</code>\x20contains\x20a\x20package\x20in\x20the\x20directory\x20<code>"html"</code>.\x20That\x0apackage's\x20path\x20is\x20<code>"golang.org/x/net/html"</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\x20subdirectory\x0awithin\x20the\x20repository\x20(usually\x20empty),\x20and\x20a\x20major\x20version\x20suffix\x20(for\x20major\x0aversion\x202\x20or\x20higher).</p>\x0a<ul>\x0a<li>The\x20repository\x20root\x20path\x20is\x20part\x20of\x20a\x20URL\x20that\x20corresponds\x20to\x20a\x20version\x0acontrol\x20repository.\x20For\x20example,\x20<code>golang.org/x/net</code>.\x20See\x20<a\x20href=\"#custom-import-paths\">Custom\x20import\x0apaths</a>\x20for\x20details\x20on\x20how\x20paths\x20are\x20resolved\x20to\x0arepositories.</li>\x0a<li>If\x20the\x20module\x20is\x20in\x20a\x20subdirectory\x20of\x20the\x20version\x20control\x20repository,\x20the\x0asubdirectory\x20should\x20be\x20part\x20of\x20the\x20module\x20path\x20(but\x20not\x20the\x20repository\x20root\x0apath).\x20For\x20example,\x20the\x20module\x20<code>golang.org/x/tools/gopls</code>\x20is\x20in\x20the\x20<code>/gopls</code>\x0asubdirectory\x20of\x20the\x20repository\x20<code>golang.org/x/tools</code>.</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\">major\x20version\x20suffix</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=\"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=\"#communicating-with-vcs\">communicate\x20with\x20a\x20version\x20control\x20system</a>.\x20<code>off</code>\x0aindicates\x20that\x20no\x20communication\x20should\x20be\x20attempted.\x20The\x20<code>GOPRIVATE</code>\x20and\x0a<code>GONOPROXY</code>\x20<a\x20href=\"#environment-variables\">environment\x20variables</a>\x20can\x20also\x20be\x20used\x20to\x0acontrol\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=>\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>=></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>"</code>,\x20U+0022)\x20and\x0araw\x20strings\x20beginning\x20and\x20ending\x20with\x20grave\x20accents\x20(<code><</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>\\"</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>\\"</code>\x20is\x20replaced\x20by\x20<code>"</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"module"\x20(\x20ModulePath\x20|\x20"("\x20newline\x20ModulePath\x20newline\x20")"\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"go"\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"require"\x20(\x20RequireSpec\x20|\x20"("\x20newline\x20{\x20RequireSpec\x20}\x20")"\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"exclude"\x20(\x20ExcludeSpec\x20|\x20"("\x20newline\x20{\x20ExcludeSpec\x20}\x20")"\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>=></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"replace"\x20(\x20ReplaceSpec\x20|\x20"("\x20newline\x20{\x20ReplaceSpec\x20}\x20")"\x20newline\x20")"\x20)\x20.\x0aReplaceSpec\x20=\x20ModulePath\x20[\x20Version\x20]\x20"=>"\x20FilePath\x20newline\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20|\x20ModulePath\x20[\x20Version\x20]\x20"=>"\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=>\x20example.com/fork/net\x20v1.4.5\x0a\x0areplace\x20(\x0a\x20\x20\x20\x20golang.org/x/net\x20v1.2.3\x20=>\x20example.com/fork/net\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/net\x20=>\x20example.com/fork/net\x20v1.4.5\x0a\x20\x20\x20\x20golang.org/x/net\x20v1.2.3\x20=>\x20./fork/net\x0a\x20\x20\x20\x20golang.org/x/net\x20=>\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><a\x20id=\"non-module-compat\"></a></p>\x0a<h2>Compatibility\x20with\x20non-module\x20repositories</h2>\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><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\x20package\x20in\x20the\x20main\x20module.\x0a$\x20go\x20get\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=>\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=>\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><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><a\x20id=\"go-mod-verify\"></a></p>\x0a<h3><code>go\x20mod\x20verify</code></h3>\x0a<p><a\x20id=\"go-clean-modcache\"></a></p>\x0a<h3><code>go\x20clean\x20-modcache</code></h3>\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><v1.2.3</code>\x20or\x20<code>>=v1.5.6</code>,\x20which\x20selects\x0athe\x20nearest\x20available\x20version\x20to\x20the\x20comparison\x20target\x20(the\x20lowest\x20version\x0afor\x20<code>></code>\x20and\x20<code>>=</code>,\x20and\x20the\x20highest\x20version\x20for\x20<code><</code>\x20and\x20<code><=</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><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><a\x20id=\"retrieving-modules\"></a></p>\x0a<h2>Retrieving\x20modules</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=\"ModProtocol\">\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-format\">Module\x20zip\x20format</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-file-format\"><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><a\x20id=\"communicating-with-vcs\"></a></p>\x0a<h3>Communicating\x20with\x20version\x20control\x20systems</h3>\x0a<p><a\x20id=\"custom-import-paths\"></a></p>\x0a<h3>Custom\x20import\x20paths</h3>\x0a<!--\x20TODO(jayconrod):\x20custom\x20import\x20paths,\x20details\x20of\x20direct\x20mode\x20-->\x0a<p><a\x20id=\"path-constraints\"></a></p>\x0a<h3>File\x20name\x20and\x20path\x20constraints</h3>\x0a<p><a\x20id=\"zip-format\"></a></p>\x0a<h3>Module\x20zip\x20format</h3>\x0a<p><a\x20id=\"private-modules\"></a></p>\x0a<h3>Private\x20modules</h3>\x0a<p><a\x20id=\"module-cache\"></a></p>\x0a<h3>Module\x20cache</h3>\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-file-format\"></a></p>\x0a<h3>go.sum\x20file\x20format</h3>\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=\"ModProtocol\">\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="sum.golang.org"\x0aGOSUMDB="sum.golang.org+<publickey>"\x0aGOSUMDB="sum.golang.org+<publickey>\x20https://sum.golang.org"\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><a\x20id=\"glossary\"></a></p>\x0a<h2>Glossary</h2>\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-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>"golang.org/x/net"</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-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>"golang.org/x/net/html"</code>\x20is\x20the\x20package\x20path\x20for\x20the\x20package\x20in\x20the\x0amodule\x20<code>"golang.org/x/net"</code>\x20in\x20the\x20<code>"html"</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-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",
}
