Skip to content

G
golang
Commit 4864decf authored by Russ Cox's avatar Russ Cox
Browse files
Options

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: 's avatarBrad Fitzpatrick <bradfitz@golang.org>
parent 16a72125
Hide whitespace changes
Inline Side-by-side
Showing with 163 additions and 141 deletions
src/cmd/go/alldocs.go
View file @ 4864decf
......@@ -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
......
src/cmd/go/internal/modcmd/fix.go deleted 100644 → 0
View file @ 16a72125
// 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
}
src/cmd/go/internal/modcmd/mod.go
View file @ 4864decf
......@@ -21,7 +21,6 @@ See 'go help modules' for an overview of module functionality.
Commands: []*base.Command{
cmdDownload,
cmdEdit,
cmdFix,
cmdGraph,
cmdInit,
cmdTidy,
......
src/cmd/go/internal/modload/help.go
View file @ 4864decf
......@@ -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.
`,
}
src/cmd/go/main.go
View file @ 4864decf
......@@ -64,6 +64,7 @@ func init() {
help.HelpCache,
help.HelpEnvironment,
help.HelpFileType,
modload.HelpGoMod,
help.HelpGopath,
get.HelpGopathGet,
modfetch.HelpGoproxy,
......
src/cmd/go/testdata/script/mod_get_commit.txt
View file @ 4864decf
......@@ -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 --
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment