Source file src/pkg/cmd/go/internal/modload/help.go
1
2
3
4
5 package modload
6
7 import "cmd/go/internal/base"
8
9
10
11 var HelpModules = &base.Command{
12 UsageLine: "modules",
13 Short: "modules, module versions, and more",
14 Long: `
15 A module is a collection of related Go packages.
16 Modules are the unit of source code interchange and versioning.
17 The go command has direct support for working with modules,
18 including recording and resolving dependencies on other modules.
19 Modules replace the old GOPATH-based approach to specifying
20 which source files are used in a given build.
21
22 Module support
23
24 Go 1.13 includes support for Go modules. Module-aware mode is active by default
25 whenever a go.mod file is found in, or in a parent of, the current directory.
26
27 The quickest way to take advantage of module support is to check out your
28 repository, create a go.mod file (described in the next section) there, and run
29 go commands from within that file tree.
30
31 For more fine-grained control, Go 1.13 continues to respect
32 a temporary environment variable, GO111MODULE, which can be set to one
33 of three string values: off, on, or auto (the default).
34 If GO111MODULE=on, then the go command requires the use of modules,
35 never consulting GOPATH. We refer to this as the command
36 being module-aware or running in "module-aware mode".
37 If GO111MODULE=off, then the go command never uses
38 module support. Instead it looks in vendor directories and GOPATH
39 to find dependencies; we now refer to this as "GOPATH mode."
40 If GO111MODULE=auto or is unset, then the go command enables or disables
41 module support based on the current directory.
42 Module support is enabled only when the current directory contains a
43 go.mod file or is below a directory containing a go.mod file.
44
45 In module-aware mode, GOPATH no longer defines the meaning of imports
46 during a build, but it still stores downloaded dependencies (in GOPATH/pkg/mod)
47 and installed commands (in GOPATH/bin, unless GOBIN is set).
48
49 Defining a module
50
51 A module is defined by a tree of Go source files with a go.mod file
52 in the tree's root directory. The directory containing the go.mod file
53 is called the module root. Typically the module root will also correspond
54 to a source code repository root (but in general it need not).
55 The module is the set of all Go packages in the module root and its
56 subdirectories, but excluding subtrees with their own go.mod files.
57
58 The "module path" is the import path prefix corresponding to the module root.
59 The go.mod file defines the module path and lists the specific versions
60 of other modules that should be used when resolving imports during a build,
61 by giving their module paths and versions.
62
63 For example, this go.mod declares that the directory containing it is the root
64 of the module with path example.com/m, and it also declares that the module
65 depends on specific versions of golang.org/x/text and gopkg.in/yaml.v2:
66
67 module example.com/m
68
69 require (
70 golang.org/x/text v0.3.0
71 gopkg.in/yaml.v2 v2.1.0
72 )
73
74 The go.mod file can also specify replacements and excluded versions
75 that only apply when building the module directly; they are ignored
76 when the module is incorporated into a larger build.
77 For more about the go.mod file, see 'go help go.mod'.
78
79 To start a new module, simply create a go.mod file in the root of the
80 module's directory tree, containing only a module statement.
81 The 'go mod init' command can be used to do this:
82
83 go mod init example.com/m
84
85 In a project already using an existing dependency management tool like
86 godep, glide, or dep, 'go mod init' will also add require statements
87 matching the existing configuration.
88
89 Once the go.mod file exists, no additional steps are required:
90 go commands like 'go build', 'go test', or even 'go list' will automatically
91 add new dependencies as needed to satisfy imports.
92
93 The main module and the build list
94
95 The "main module" is the module containing the directory where the go command
96 is run. The go command finds the module root by looking for a go.mod in the
97 current directory, or else the current directory's parent directory,
98 or else the parent's parent directory, and so on.
99
100 The main module's go.mod file defines the precise set of packages available
101 for use by the go command, through require, replace, and exclude statements.
102 Dependency modules, found by following require statements, also contribute
103 to the definition of that set of packages, but only through their go.mod
104 files' require statements: any replace and exclude statements in dependency
105 modules are ignored. The replace and exclude statements therefore allow the
106 main module complete control over its own build, without also being subject
107 to complete control by dependencies.
108
109 The set of modules providing packages to builds is called the "build list".
110 The build list initially contains only the main module. Then the go command
111 adds to the list the exact module versions required by modules already
112 on the list, recursively, until there is nothing left to add to the list.
113 If multiple versions of a particular module are added to the list,
114 then at the end only the latest version (according to semantic version
115 ordering) is kept for use in the build.
116
117 The 'go list' command provides information about the main module
118 and the build list. For example:
119
120 go list -m # print path of main module
121 go list -m -f={{.Dir}} # print root directory of main module
122 go list -m all # print build list
123
124 Maintaining module requirements
125
126 The go.mod file is meant to be readable and editable by both
127 programmers and tools. The go command itself automatically updates the go.mod file
128 to maintain a standard formatting and the accuracy of require statements.
129
130 Any go command that finds an unfamiliar import will look up the module
131 containing that import and add the latest version of that module
132 to go.mod automatically. In most cases, therefore, it suffices to
133 add an import to source code and run 'go build', 'go test', or even 'go list':
134 as part of analyzing the package, the go command will discover
135 and resolve the import and update the go.mod file.
136
137 Any go command can determine that a module requirement is
138 missing and must be added, even when considering only a single
139 package from the module. On the other hand, determining that a module requirement
140 is no longer necessary and can be deleted requires a full view of
141 all packages in the module, across all possible build configurations
142 (architectures, operating systems, build tags, and so on).
143 The 'go mod tidy' command builds that view and then
144 adds any missing module requirements and removes unnecessary ones.
145
146 As part of maintaining the require statements in go.mod, the go command
147 tracks which ones provide packages imported directly by the current module
148 and which ones provide packages only used indirectly by other module
149 dependencies. Requirements needed only for indirect uses are marked with a
150 "// indirect" comment in the go.mod file. Indirect requirements are
151 automatically removed from the go.mod file once they are implied by other
152 direct requirements. Indirect requirements only arise when using modules
153 that fail to state some of their own dependencies or when explicitly
154 upgrading a module's dependencies ahead of its own stated requirements.
155
156 Because of this automatic maintenance, the information in go.mod is an
157 up-to-date, readable description of the build.
158
159 The 'go get' command updates go.mod to change the module versions used in a
160 build. An upgrade of one module may imply upgrading others, and similarly a
161 downgrade of one module may imply downgrading others. The 'go get' command
162 makes these implied changes as well. If go.mod is edited directly, commands
163 like 'go build' or 'go list' will assume that an upgrade is intended and
164 automatically make any implied upgrades and update go.mod to reflect them.
165
166 The 'go mod' command provides other functionality for use in maintaining
167 and understanding modules and go.mod files. See 'go help mod'.
168
169 The -mod build flag provides additional control over updating and use of go.mod.
170
171 If invoked with -mod=readonly, the go command is disallowed from the implicit
172 automatic updating of go.mod described above. Instead, it fails when any changes
173 to go.mod are needed. This setting is most useful to check that go.mod does
174 not need updates, such as in a continuous integration and testing system.
175 The "go get" command remains permitted to update go.mod even with -mod=readonly,
176 and the "go mod" commands do not take the -mod flag (or any other build flags).
177
178 If invoked with -mod=vendor, the go command assumes that the vendor
179 directory holds the correct copies of dependencies and ignores
180 the dependency descriptions in go.mod.
181
182 Pseudo-versions
183
184 The go.mod file and the go command more generally use semantic versions as
185 the standard form for describing module versions, so that versions can be
186 compared to determine which should be considered earlier or later than another.
187 A module version like v1.2.3 is introduced by tagging a revision in the
188 underlying source repository. Untagged revisions can be referred to
189 using a "pseudo-version" like v0.0.0-yyyymmddhhmmss-abcdefabcdef,
190 where the time is the commit time in UTC and the final suffix is the prefix
191 of the commit hash. The time portion ensures that two pseudo-versions can
192 be compared to determine which happened later, the commit hash identifes
193 the underlying commit, and the prefix (v0.0.0- in this example) is derived from
194 the most recent tagged version in the commit graph before this commit.
195
196 There are three pseudo-version forms:
197
198 vX.0.0-yyyymmddhhmmss-abcdefabcdef is used when there is no earlier
199 versioned commit with an appropriate major version before the target commit.
200 (This was originally the only form, so some older go.mod files use this form
201 even for commits that do follow tags.)
202
203 vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef is used when the most
204 recent versioned commit before the target commit is vX.Y.Z-pre.
205
206 vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef is used when the most
207 recent versioned commit before the target commit is vX.Y.Z.
208
209 Pseudo-versions never need to be typed by hand: the go command will accept
210 the plain commit hash and translate it into a pseudo-version (or a tagged
211 version if available) automatically. This conversion is an example of a
212 module query.
213
214 Module queries
215
216 The go command accepts a "module query" in place of a module version
217 both on the command line and in the main module's go.mod file.
218 (After evaluating a query found in the main module's go.mod file,
219 the go command updates the file to replace the query with its result.)
220
221 A fully-specified semantic version, such as "v1.2.3",
222 evaluates to that specific version.
223
224 A semantic version prefix, such as "v1" or "v1.2",
225 evaluates to the latest available tagged version with that prefix.
226
227 A semantic version comparison, such as "<v1.2.3" or ">=v1.5.6",
228 evaluates to the available tagged version nearest to the comparison target
229 (the latest version for < and <=, the earliest version for > and >=).
230
231 The string "latest" matches the latest available tagged version,
232 or else the underlying source repository's latest untagged revision.
233
234 The string "upgrade" is like "latest", but if the module is
235 currently required at a later version than the version "latest"
236 would select (for example, a newer pre-release version), "upgrade"
237 will select the later version instead.
238
239 The string "patch" matches the latest available tagged version
240 of a module with the same major and minor version numbers as the
241 currently required version. If no version is currently required,
242 "patch" is equivalent to "latest".
243
244 A revision identifier for the underlying source repository, such as
245 a commit hash prefix, revision tag, or branch name, selects that
246 specific code revision. If the revision is also tagged with a
247 semantic version, the query evaluates to that semantic version.
248 Otherwise the query evaluates to a pseudo-version for the commit.
249 Note that branches and tags with names that are matched by other
250 query syntax cannot be selected this way. For example, the query
251 "v2" means the latest version starting with "v2", not the branch
252 named "v2".
253
254 All queries prefer release versions to pre-release versions.
255 For example, "<v1.2.3" will prefer to return "v1.2.2"
256 instead of "v1.2.3-pre1", even though "v1.2.3-pre1" is nearer
257 to the comparison target.
258
259 Module versions disallowed by exclude statements in the
260 main module's go.mod are considered unavailable and cannot
261 be returned by queries.
262
263 For example, these commands are all valid:
264
265 go get github.com/gorilla/mux@latest # same (@latest is default for 'go get')
266 go get github.com/gorilla/mux@v1.6.2 # records v1.6.2
267 go get github.com/gorilla/mux@e3702bed2 # records v1.6.2
268 go get github.com/gorilla/mux@c856192 # records v0.0.0-20180517173623-c85619274f5d
269 go get github.com/gorilla/mux@master # records current meaning of master
270
271 Module compatibility and semantic versioning
272
273 The go command requires that modules use semantic versions and expects that
274 the versions accurately describe compatibility: it assumes that v1.5.4 is a
275 backwards-compatible replacement for v1.5.3, v1.4.0, and even v1.0.0.
276 More generally the go command expects that packages follow the
277 "import compatibility rule", which says:
278
279 "If an old package and a new package have the same import path,
280 the new package must be backwards compatible with the old package."
281
282 Because the go command assumes the import compatibility rule,
283 a module definition can only set the minimum required version of one
284 of its dependencies: it cannot set a maximum or exclude selected versions.
285 Still, the import compatibility rule is not a guarantee: it may be that
286 v1.5.4 is buggy and not a backwards-compatible replacement for v1.5.3.
287 Because of this, the go command never updates from an older version
288 to a newer version of a module unasked.
289
290 In semantic versioning, changing the major version number indicates a lack
291 of backwards compatibility with earlier versions. To preserve import
292 compatibility, the go command requires that modules with major version v2
293 or later use a module path with that major version as the final element.
294 For example, version v2.0.0 of example.com/m must instead use module path
295 example.com/m/v2, and packages in that module would use that path as
296 their import path prefix, as in example.com/m/v2/sub/pkg. Including the
297 major version number in the module path and import paths in this way is
298 called "semantic import versioning". Pseudo-versions for modules with major
299 version v2 and later begin with that major version instead of v0, as in
300 v2.0.0-20180326061214-4fc5987536ef.
301
302 As a special case, module paths beginning with gopkg.in/ continue to use the
303 conventions established on that system: the major version is always present,
304 and it is preceded by a dot instead of a slash: gopkg.in/yaml.v1
305 and gopkg.in/yaml.v2, not gopkg.in/yaml and gopkg.in/yaml/v2.
306
307 The go command treats modules with different module paths as unrelated:
308 it makes no connection between example.com/m and example.com/m/v2.
309 Modules with different major versions can be used together in a build
310 and are kept separate by the fact that their packages use different
311 import paths.
312
313 In semantic versioning, major version v0 is for initial development,
314 indicating no expectations of stability or backwards compatibility.
315 Major version v0 does not appear in the module path, because those
316 versions are preparation for v1.0.0, and v1 does not appear in the
317 module path either.
318
319 Code written before the semantic import versioning convention
320 was introduced may use major versions v2 and later to describe
321 the same set of unversioned import paths as used in v0 and v1.
322 To accommodate such code, if a source code repository has a
323 v2.0.0 or later tag for a file tree with no go.mod, the version is
324 considered to be part of the v1 module's available versions
325 and is given an +incompatible suffix when converted to a module
326 version, as in v2.0.0+incompatible. The +incompatible tag is also
327 applied to pseudo-versions derived from such versions, as in
328 v2.0.1-0.yyyymmddhhmmss-abcdefabcdef+incompatible.
329
330 In general, having a dependency in the build list (as reported by 'go list -m all')
331 on a v0 version, pre-release version, pseudo-version, or +incompatible version
332 is an indication that problems are more likely when upgrading that
333 dependency, since there is no expectation of compatibility for those.
334
335 See https://research.swtch.com/vgo-import for more information about
336 semantic import versioning, and see https://semver.org/ for more about
337 semantic versioning.
338
339 Module code layout
340
341 For now, see https://research.swtch.com/vgo-module for information
342 about how source code in version control systems is mapped to
343 module file trees.
344
345 Module downloading and verification
346
347 The go command can fetch modules from a proxy or connect to source control
348 servers directly, according to the setting of the GOPROXY environment
349 variable (see 'go help env'). The default setting for GOPROXY is
350 "https://proxy.golang.org,direct", which means to try the
351 Go module mirror run by Google and fall back to a direct connection
352 if the proxy reports that it does not have the module (HTTP error 404 or 410).
353 See https://proxy.golang.org/privacy for the service's privacy policy.
354 If GOPROXY is set to the string "direct", downloads use a direct connection
355 to source control servers. Setting GOPROXY to "off" disallows downloading
356 modules from any source. Otherwise, GOPROXY is expected to be a comma-separated
357 list of the URLs of module proxies, in which case the go command will fetch
358 modules from those proxies. For each request, the go command tries each proxy
359 in sequence, only moving to the next if the current proxy returns a 404 or 410
360 HTTP response. The string "direct" may appear in the proxy list,
361 to cause a direct connection to be attempted at that point in the search.
362 Any proxies listed after "direct" are never consulted.
363
364 The GOPRIVATE and GONOPROXY environment variables allow bypassing
365 the proxy for selected modules. See 'go help module-private' for details.
366
367 No matter the source of the modules, the go command checks downloads against
368 known checksums, to detect unexpected changes in the content of any specific
369 module version from one day to the next. This check first consults the current
370 module's go.sum file but falls back to the Go checksum database, controlled by
371 the GOSUMDB and GONOSUMDB environment variables. See 'go help module-auth'
372 for details.
373
374 See 'go help goproxy' for details about the proxy protocol and also
375 the format of the cached downloaded packages.
376
377 Modules and vendoring
378
379 When using modules, the go command completely ignores vendor directories.
380
381 By default, the go command satisfies dependencies by downloading modules
382 from their sources and using those downloaded copies (after verification,
383 as described in the previous section). To allow interoperation with older
384 versions of Go, or to ensure that all files used for a build are stored
385 together in a single file tree, 'go mod vendor' creates a directory named
386 vendor in the root directory of the main module and stores there all the
387 packages from dependency modules that are needed to support builds and
388 tests of packages in the main module.
389
390 To build using the main module's top-level vendor directory to satisfy
391 dependencies (disabling use of the usual network sources and local
392 caches), use 'go build -mod=vendor'. Note that only the main module's
393 top-level vendor directory is used; vendor directories in other locations
394 are still ignored.
395 `,
396 }
397
398 var HelpGoMod = &base.Command{
399 UsageLine: "go.mod",
400 Short: "the go.mod file",
401 Long: `
402 A module version is defined by a tree of source files, with a go.mod
403 file in its root. When the go command is run, it looks in the current
404 directory and then successive parent directories to find the go.mod
405 marking the root of the main (current) module.
406
407 The go.mod file itself is line-oriented, with // comments but
408 no /* */ comments. Each line holds a single directive, made up of a
409 verb followed by arguments. For example:
410
411 module my/thing
412 go 1.12
413 require other/thing v1.0.2
414 require new/thing/v2 v2.3.4
415 exclude old/thing v1.2.3
416 replace bad/thing v1.4.5 => good/thing v1.4.5
417
418 The verbs are
419 module, to define the module path;
420 go, to set the expected language version;
421 require, to require a particular module at a given version or later;
422 exclude, to exclude a particular module version from use; and
423 replace, to replace a module version with a different module version.
424 Exclude and replace apply only in the main module's go.mod and are ignored
425 in dependencies. See https://research.swtch.com/vgo-mvs for details.
426
427 The leading verb can be factored out of adjacent lines to create a block,
428 like in Go imports:
429
430 require (
431 new/thing v2.3.4
432 old/thing v1.2.3
433 )
434
435 The go.mod file is designed both to be edited directly and to be
436 easily updated by tools. The 'go mod edit' command can be used to
437 parse and edit the go.mod file from programs and tools.
438 See 'go help mod edit'.
439
440 The go command automatically updates go.mod each time it uses the
441 module graph, to make sure go.mod always accurately reflects reality
442 and is properly formatted. For example, consider this go.mod file:
443
444 module M
445
446 require (
447 A v1
448 B v1.0.0
449 C v1.0.0
450 D v1.2.3
451 E dev
452 )
453
454 exclude D v1.2.3
455
456 The update rewrites non-canonical version identifiers to semver form,
457 so A's v1 becomes v1.0.0 and E's dev becomes the pseudo-version for the
458 latest commit on the dev branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1.
459
460 The update modifies requirements to respect exclusions, so the
461 requirement on the excluded D v1.2.3 is updated to use the next
462 available version of D, perhaps D v1.2.4 or D v1.3.0.
463
464 The update removes redundant or misleading requirements.
465 For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0,
466 then go.mod's requirement of B v1.0.0 is misleading (superseded by
467 A's need for v1.2.0), and its requirement of C v1.0.0 is redundant
468 (implied by A's need for the same version), so both will be removed.
469 If module M contains packages that directly import packages from B or
470 C, then the requirements will be kept but updated to the actual
471 versions being used.
472
473 Finally, the update reformats the go.mod in a canonical formatting, so
474 that future mechanical changes will result in minimal diffs.
475
476 Because the module graph defines the meaning of import statements, any
477 commands that load packages also use and therefore update go.mod,
478 including go build, go get, go install, go list, go test, go mod graph,
479 go mod tidy, and go mod why.
480
481 The expected language version, set by the go directive, determines
482 which language features are available when compiling the module.
483 Language features available in that version will be available for use.
484 Language features removed in earlier versions, or added in later versions,
485 will not be available. Note that the language version does not affect
486 build tags, which are determined by the Go release being used.
487 `,
488 }
489
View as plain text