// 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
// 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)
//
// 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
// 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:
// 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.
// 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.
// 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
+++ /dev/null
-// 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
-}
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",
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.
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
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.
+ `,
+}