diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index 70d655747c..c67e3f5a1c 100644 --- a/src/cmd/go/alldocs.go +++ b/src/cmd/go/alldocs.go @@ -40,6 +40,7 @@ // cache build and test caching // environment environment variables // filetype file types +// go.mod the go.mod file // gopath GOPATH environment variable // gopath-get legacy GOPATH go get // goproxy module proxy protocol @@ -622,24 +623,25 @@ // to -f '{{.ImportPath}}'. The struct being passed to the template is: // // type Package struct { -// Dir string // directory containing package sources -// ImportPath string // import path of package in dir -// ImportComment string // path in import comment on package statement -// Name string // package name -// Doc string // package documentation string -// Target string // install path -// Shlib string // the shared library that contains this package (only set when -linkshared) -// Goroot bool // is this package in the Go root? -// Standard bool // is this package part of the standard Go library? -// Stale bool // would 'go install' do anything for this package? -// StaleReason string // explanation for Stale==true -// Root string // Go root or Go path dir containing this package -// ConflictDir string // this directory shadows Dir in $GOPATH -// BinaryOnly bool // binary-only package: cannot be recompiled from sources -// ForTest string // package is only for use in named test -// DepOnly bool // package is only a dependency, not explicitly listed -// Export string // file containing export data (when using -export) -// Module *Module // info about package's containing module, if any (can be nil) +// Dir string // directory containing package sources +// ImportPath string // import path of package in dir +// ImportComment string // path in import comment on package statement +// Name string // package name +// Doc string // package documentation string +// Target string // install path +// Shlib string // the shared library that contains this package (only set when -linkshared) +// Goroot bool // is this package in the Go root? +// Standard bool // is this package part of the standard Go library? +// Stale bool // would 'go install' do anything for this package? +// StaleReason string // explanation for Stale==true +// Root string // Go root or Go path dir containing this package +// ConflictDir string // this directory shadows Dir in $GOPATH +// BinaryOnly bool // binary-only package: cannot be recompiled from sources +// ForTest string // package is only for use in named test +// Export string // file containing export data (when using -export) +// Module *Module // info about package's containing module, if any (can be nil) +// Match []string // command-line patterns matching this package +// DepOnly bool // package is only a dependency, not explicitly listed // // // Source files // GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) @@ -874,7 +876,6 @@ // // download download modules to local cache // edit edit go.mod from tools or scripts -// fix make go.mod semantically consistent // graph print module requirement graph // init initialize new module in current directory // tidy add missing and remove unused modules @@ -998,52 +999,6 @@ // by invoking 'go mod edit' with -require, -exclude, and so on. // // -// Make go.mod semantically consistent -// -// Usage: -// -// go mod fix -// -// Fix updates go.mod to use canonical version identifiers and -// to be semantically consistent. For example, consider this go.mod file: -// -// module M -// -// require ( -// A v1 -// B v1.0.0 -// C v1.0.0 -// D v1.2.3 -// E dev -// ) -// -// exclude D v1.2.3 -// -// First, fix rewrites non-canonical version identifiers to semver form, so -// A's v1 becomes v1.0.0 and E's dev becomes the pseudo-version for the latest -// commit on the dev branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1. -// -// Next, fix updates requirements to respect exclusions, so the requirement -// on the excluded D v1.2.3 is updated to use the next available version of D, -// perhaps D v1.2.4 or D v1.3.0. -// -// Finally, fix removes redundant or misleading requirements. -// For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0, then go.mod's -// requirement of B v1.0.0 is misleading (superseded by A's need for v1.2.0), -// and its requirement of C v1.0.0 is redundant (implied by A's need for the -// same version), so both will be removed. If module M contains packages -// that directly import packages from B or C, then the requirements will be -// kept but updated to the actual versions being used. -// -// Although fix runs the fix-up operation in isolation, the fix-up also -// runs automatically any time a go command uses the module graph, -// to update go.mod to reflect reality. Because the module graph defines -// the meaning of import statements, any commands that load packages -// also use and therefore fix the module graph. For example, -// go build, go get, go install, go list, go test, go mod graph, go mod tidy, -// and other commands all effectively imply go mod fix. -// -// // Print module requirement graph // // Usage: @@ -1620,6 +1575,73 @@ // command. // // +// The go.mod file +// +// A module version is defined by a tree of source files, with a go.mod +// file in its root. When the go command is run, it looks in the current +// directory and then successive parent directories to find the go.mod +// marking the root of the main (current) module. +// +// The go.mod file itself is line-oriented, with // comments but +// no /* */ comments. Each line holds a single directive, made up of a +// verb followed by arguments. For example: +// +// module my/thing +// require other/thing v1.0.2 +// require new/thing v2.3.4 +// exclude old/thing v1.2.3 +// replace bad/thing v1.4.5 => good/thing v1.4.5 +// +// The verbs are module, to define the module path; require, to require +// a particular module at a given version or later; exclude, to exclude +// a particular module version from use; and replace, to replace a module +// version with a different module version. Exclude and replace apply only +// in the main module's go.mod and are ignored in dependencies. +// See https://research.swtch.com/vgo-mvs for details. +// +// The leading verb can be factored out of adjacent lines to create a block, +// like in Go imports: +// +// require ( +// new/thing v2.3.4 +// old/thing v1.2.3 +// ) +// +// The go.mod file is designed both to be edited directly and to be +// easily updated by tools. The 'go mod edit' command can be used to +// parse and edit the go.mod file from programs and tools. +// See 'go help mod edit'. +// +// The go command automatically updates go.mod each time it uses the +// module graph, to make sure go.mod always accurately reflects reality +// and is properly formatted. +// +// The update rewrites non-canonical version identifiers to semver form, +// so A's v1 becomes v1.0.0 and E's dev becomes the pseudo-version for the +// latest commit on the dev branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1. +// +// The update modifies requirements to respect exclusions, so the +// requirement on the excluded D v1.2.3 is updated to use the next +// available version of D, perhaps D v1.2.4 or D v1.3.0. +// +// The update removes redundant or misleading requirements. +// For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0, +// then go.mod's requirement of B v1.0.0 is misleading (superseded by +// A's need for v1.2.0), and its requirement of C v1.0.0 is redundant +// (implied by A's need for the same version), so both will be removed. +// If module M contains packages that directly import packages from B or +// C, then the requirements will be kept but updated to the actual +// versions being used. +// +// Finally, the update reformats the go.mod in a canonical formatting, so +// that future mechanical changes will result in minimal diffs. +// +// Because the module graph defines the meaning of import statements, any +// commands that load packages also use and therefore update go.mod, +// including go build, go get, go install, go list, go test, go mod graph, +// go mod tidy, and go mod why. +// +// // GOPATH environment variable // // The Go path is used to resolve import statements. @@ -2095,7 +2117,7 @@ // The go.mod file can also specify replacements and excluded versions // that only apply when building the module directly; they are ignored // when the module is incorporated into a larger build. -// For more about the go.mod file, see https://research.swtch.com/vgo-module. +// For more about the go.mod file, see 'go help go.mod'. // // To start a new module, simply create a go.mod file in the root of the // module's directory tree, containing only a module statement. @@ -2350,8 +2372,6 @@ // about how source code in version control systems is mapped to // module file trees. // -// TODO: Add documentation to go command. -// // Module downloading and verification // // The go command maintains, in the main module's root directory alongside diff --git a/src/cmd/go/internal/modcmd/fix.go b/src/cmd/go/internal/modcmd/fix.go deleted file mode 100644 index bfb51456a6..0000000000 --- a/src/cmd/go/internal/modcmd/fix.go +++ /dev/null @@ -1,65 +0,0 @@ -// Copyright 2018 The Go Authors. All rights reserved. -// Use of this source code is governed by a BSD-style -// license that can be found in the LICENSE file. - -// go mod fix - -package modcmd - -import ( - "cmd/go/internal/base" - "cmd/go/internal/modload" -) - -var cmdFix = &base.Command{ - UsageLine: "go mod fix", - Short: "make go.mod semantically consistent", - Long: ` -Fix updates go.mod to use canonical version identifiers and -to be semantically consistent. For example, consider this go.mod file: - - module M - - require ( - A v1 - B v1.0.0 - C v1.0.0 - D v1.2.3 - E dev - ) - - exclude D v1.2.3 - -First, fix rewrites non-canonical version identifiers to semver form, so -A's v1 becomes v1.0.0 and E's dev becomes the pseudo-version for the latest -commit on the dev branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1. - -Next, fix updates requirements to respect exclusions, so the requirement -on the excluded D v1.2.3 is updated to use the next available version of D, -perhaps D v1.2.4 or D v1.3.0. - -Finally, fix removes redundant or misleading requirements. -For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0, then go.mod's -requirement of B v1.0.0 is misleading (superseded by A's need for v1.2.0), -and its requirement of C v1.0.0 is redundant (implied by A's need for the -same version), so both will be removed. If module M contains packages -that directly import packages from B or C, then the requirements will be -kept but updated to the actual versions being used. - -Although fix runs the fix-up operation in isolation, the fix-up also -runs automatically any time a go command uses the module graph, -to update go.mod to reflect reality. Because the module graph defines -the meaning of import statements, any commands that load packages -also use and therefore fix the module graph. For example, -go build, go get, go install, go list, go test, go mod graph, go mod tidy, -and other commands all effectively imply go mod fix. - `, - Run: runFix, -} - -func runFix(cmd *base.Command, args []string) { - if len(args) != 0 { - base.Fatalf("go mod fix: fix takes no arguments") - } - modload.LoadBuildList() // writes go.mod -} diff --git a/src/cmd/go/internal/modcmd/mod.go b/src/cmd/go/internal/modcmd/mod.go index c1d0c13a10..f150cc9728 100644 --- a/src/cmd/go/internal/modcmd/mod.go +++ b/src/cmd/go/internal/modcmd/mod.go @@ -21,7 +21,6 @@ See 'go help modules' for an overview of module functionality. Commands: []*base.Command{ cmdDownload, cmdEdit, - cmdFix, cmdGraph, cmdInit, cmdTidy, diff --git a/src/cmd/go/internal/modload/help.go b/src/cmd/go/internal/modload/help.go index 64c70b7d7b..9a12b24482 100644 --- a/src/cmd/go/internal/modload/help.go +++ b/src/cmd/go/internal/modload/help.go @@ -6,8 +6,7 @@ package modload import "cmd/go/internal/base" -// TODO(rsc): The links out to research.swtch.com here should all be -// replaced eventually with links to proper documentation. +// TODO(rsc): The "module code layout" section needs to be written. var HelpModules = &base.Command{ UsageLine: "modules", @@ -81,7 +80,7 @@ depends on specific versions of golang.org/x/text and gopkg.in/yaml.v2: The go.mod file can also specify replacements and excluded versions that only apply when building the module directly; they are ignored when the module is incorporated into a larger build. -For more about the go.mod file, see https://research.swtch.com/vgo-module. +For more about the go.mod file, see 'go help go.mod'. To start a new module, simply create a go.mod file in the root of the module's directory tree, containing only a module statement. @@ -336,8 +335,6 @@ For now, see https://research.swtch.com/vgo-module for information about how source code in version control systems is mapped to module file trees. -TODO: Add documentation to go command. - Module downloading and verification The go command maintains, in the main module's root directory alongside @@ -381,3 +378,73 @@ top-level vendor directory is used; vendor directories in other locations are still ignored. `, } + +var HelpGoMod = &base.Command{ + UsageLine: "go.mod", + Short: "the go.mod file", + Long: ` +A module version is defined by a tree of source files, with a go.mod +file in its root. When the go command is run, it looks in the current +directory and then successive parent directories to find the go.mod +marking the root of the main (current) module. + +The go.mod file itself is line-oriented, with // comments but +no /* */ comments. Each line holds a single directive, made up of a +verb followed by arguments. For example: + + module my/thing + require other/thing v1.0.2 + require new/thing v2.3.4 + exclude old/thing v1.2.3 + replace bad/thing v1.4.5 => good/thing v1.4.5 + +The verbs are module, to define the module path; require, to require +a particular module at a given version or later; exclude, to exclude +a particular module version from use; and replace, to replace a module +version with a different module version. Exclude and replace apply only +in the main module's go.mod and are ignored in dependencies. +See https://research.swtch.com/vgo-mvs for details. + +The leading verb can be factored out of adjacent lines to create a block, +like in Go imports: + + require ( + new/thing v2.3.4 + old/thing v1.2.3 + ) + +The go.mod file is designed both to be edited directly and to be +easily updated by tools. The 'go mod edit' command can be used to +parse and edit the go.mod file from programs and tools. +See 'go help mod edit'. + +The go command automatically updates go.mod each time it uses the +module graph, to make sure go.mod always accurately reflects reality +and is properly formatted. + +The update rewrites non-canonical version identifiers to semver form, +so A's v1 becomes v1.0.0 and E's dev becomes the pseudo-version for the +latest commit on the dev branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1. + +The update modifies requirements to respect exclusions, so the +requirement on the excluded D v1.2.3 is updated to use the next +available version of D, perhaps D v1.2.4 or D v1.3.0. + +The update removes redundant or misleading requirements. +For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0, +then go.mod's requirement of B v1.0.0 is misleading (superseded by +A's need for v1.2.0), and its requirement of C v1.0.0 is redundant +(implied by A's need for the same version), so both will be removed. +If module M contains packages that directly import packages from B or +C, then the requirements will be kept but updated to the actual +versions being used. + +Finally, the update reformats the go.mod in a canonical formatting, so +that future mechanical changes will result in minimal diffs. + +Because the module graph defines the meaning of import statements, any +commands that load packages also use and therefore update go.mod, +including go build, go get, go install, go list, go test, go mod graph, +go mod tidy, and go mod why. + `, +} diff --git a/src/cmd/go/main.go b/src/cmd/go/main.go index 59d367edaa..0639b4d2ca 100644 --- a/src/cmd/go/main.go +++ b/src/cmd/go/main.go @@ -64,6 +64,7 @@ func init() { help.HelpCache, help.HelpEnvironment, help.HelpFileType, + modload.HelpGoMod, help.HelpGopath, get.HelpGopathGet, modfetch.HelpGoproxy, diff --git a/src/cmd/go/testdata/script/mod_get_commit.txt b/src/cmd/go/testdata/script/mod_get_commit.txt index 2608397404..589a791fd4 100644 --- a/src/cmd/go/testdata/script/mod_get_commit.txt +++ b/src/cmd/go/testdata/script/mod_get_commit.txt @@ -45,8 +45,8 @@ grep 'rsc.io/quote v1.5.1' go.mod go mod edit -require rsc.io/quote@23179ee grep 'rsc.io/quote 23179ee' go.mod -# but go mod fix fixes them -go mod fix +# but other commands fix them +go mod graph grep 'rsc.io/quote v1.5.1' go.mod -- go.mod --