cmd/go: remove go mod fix, add go help go.mod

"go mod fix" does work already done by nearly every other go command.
It was also confusing why we had both "go mod fix" and "go mod tidy".
Delete "go mod fix".

The main reason we kept "go mod fix" this long was for the discussion
of automatic go.mod updates in its documentation, which is now moved
into a new "go help go.mod".

Fixes #26831.

Change-Id: Ic95ca8918449ab79791d27998e02eb3377ac7972
Reviewed-on: https://go-review.googlesource.com/129682
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

6 files changed, 163 insertions, 141 deletions

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 --