cmd/go: document internal and vendor
Fixes #11606.
Change-Id: I70d38c22812c17119b998aad9c1c68e7cf74e98a
Reviewed-on: https://go-review.googlesource.com/12524
Reviewed-by: Rob Pike <r@golang.org>
diff --git a/doc/go1.5.html b/doc/go1.5.html
index b8acdac..9dc289e 100644
--- a/doc/go1.5.html
+++ b/doc/go1.5.html
@@ -455,8 +455,8 @@
<p>
Another change in how packages are handled is the experimental
addition of support for "vendoring".
-TODO: This is undocumented in the go command itself.
-TODO: Preliminary design in https://golang.org/s/go15vendor should be updated.
+For details, see the documentation for the <a href="/cmd/go/#hdr-Vendor_Directories"><code>go</code> command</a>
+and the <a href="https://golang.org/s/go15vendor">design document</a>.
</p>
<p>
diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 060385c..a769f6c 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -135,8 +135,8 @@
For more about specifying packages, see 'go help packages'.
For more about where packages and binaries are installed,
-run 'go help gopath'. For more about calling between Go and C/C++,
-run 'go help c'.
+run 'go help gopath'.
+For more about calling between Go and C/C++, run 'go help c'.
See also: go install, go get, go clean.
@@ -472,6 +472,10 @@
searches for a branch or tag named "go1". If no such version exists it
retrieves the most recent version of the package.
+If the vendoring experiment is enabled (see 'go help gopath'),
+then when go get checks out or updates a Git repository,
+it also updates any git submodules referenced by the repository.
+
For more about specifying packages, see 'go help packages'.
For more about how 'go get' finds source code to
@@ -838,10 +842,10 @@
Each directory listed in GOPATH must have a prescribed structure:
-The src/ directory holds source code. The path below 'src'
+The src directory holds source code. The path below src
determines the import path or executable name.
-The pkg/ directory holds installed package objects.
+The pkg directory holds installed package objects.
As in the Go tree, each target operating system and
architecture pair has its own subdirectory of pkg
(pkg/GOOS_GOARCH).
@@ -850,11 +854,11 @@
source in DIR/src/foo/bar can be imported as "foo/bar" and
has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
-The bin/ directory holds compiled commands.
+The bin directory holds compiled commands.
Each command is named for its source directory, but only
the final element, not the entire path. That is, the
command with source in DIR/src/foo/quux is installed into
-DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped
+DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
so that you can add DIR/bin to your PATH to get at the
installed commands. If the GOBIN environment variable is
set, commands are installed to the directory it names instead
@@ -884,6 +888,91 @@
See https://golang.org/doc/code.html for an example.
+Internal Directories
+
+Code in or below a directory named "internal" is importable only
+by code in the directory tree rooted at the parent of "internal".
+Here's an extended version of the directory layout above:
+
+ /home/user/gocode/
+ src/
+ crash/
+ bang/ (go code in package bang)
+ b.go
+ foo/ (go code in package foo)
+ f.go
+ bar/ (go code in package bar)
+ x.go
+ internal/
+ baz/ (go code in package baz)
+ z.go
+ quux/ (go code in package main)
+ y.go
+
+
+The code in z.go is imported as "foo/internal/baz", but that
+import statement can only appear in source files in the subtree
+rooted at foo. The source files foo/f.go, foo/bar/x.go, and
+foo/quux/y.go can all import "foo/internal/baz", but the source file
+crash/bang/b.go cannot.
+
+See https://golang.org/s/go14internal for details.
+
+Vendor Directories
+
+Go 1.5 includes experimental support for using local copies
+of external dependencies to satisfy imports of those dependencies,
+often referred to as vendoring. Setting the environment variable
+GO15VENDOREXPERIMENT=1 enables that experimental support.
+
+When the vendor experiment is enabled,
+code below a directory named "vendor" is importable only
+by code in the directory tree rooted at the parent of "vendor",
+and only using an import path that omits the prefix up to and
+including the vendor element.
+
+Here's the example from the previous section,
+but with the "internal" directory renamed to "vendor"
+and a new foo/vendor/crash/bang directory added:
+
+ /home/user/gocode/
+ src/
+ crash/
+ bang/ (go code in package bang)
+ b.go
+ foo/ (go code in package foo)
+ f.go
+ bar/ (go code in package bar)
+ x.go
+ vendor/
+ crash/
+ bang/ (go code in package bang)
+ b.go
+ baz/ (go code in package baz)
+ z.go
+ quux/ (go code in package main)
+ y.go
+
+The same visibility rules apply as for internal, but the code
+in z.go is imported as "baz", not as "foo/vendor/baz".
+
+Code in vendor directories deeper in the source tree shadows
+code in higher directories. Within the subtree rooted at foo, an import
+of "crash/bang" resolves to "foo/vendor/crash/bang", not the
+top-level "crash/bang".
+
+Code in vendor directories is not subject to import path
+checking (see 'go help importpath').
+
+When the vendor experiment is enabled, 'go get' checks out
+submodules when checking out or updating a git repository
+(see 'go help get').
+
+The vendoring semantics are an experiment, and they may change
+in future releases. Once settled, they will be on by default.
+
+See https://golang.org/s/go15vendor for details.
+
Import path syntax
@@ -1054,6 +1143,11 @@
let package authors make sure the custom import path is used and not a
direct path to the underlying code hosting site.
+If the vendoring experiment is enabled (see 'go help gopath'),
+then import path checking is disabled for code found within vendor trees.
+This makes it possible to copy code into alternate locations in vendor trees
+without needing to update import comments.
+
See https://golang.org/s/go14customimport for details.
diff --git a/src/cmd/go/build.go b/src/cmd/go/build.go
index 2d2f10d..9134e39 100644
--- a/src/cmd/go/build.go
+++ b/src/cmd/go/build.go
@@ -115,8 +115,8 @@
For more about specifying packages, see 'go help packages'.
For more about where packages and binaries are installed,
-run 'go help gopath'. For more about calling between Go and C/C++,
-run 'go help c'.
+run 'go help gopath'.
+For more about calling between Go and C/C++, run 'go help c'.
See also: go install, go get, go clean.
`,
diff --git a/src/cmd/go/get.go b/src/cmd/go/get.go
index f331c29..78088b3 100644
--- a/src/cmd/go/get.go
+++ b/src/cmd/go/get.go
@@ -51,6 +51,10 @@
searches for a branch or tag named "go1". If no such version exists it
retrieves the most recent version of the package.
+If the vendoring experiment is enabled (see 'go help gopath'),
+then when go get checks out or updates a Git repository,
+it also updates any git submodules referenced by the repository.
+
For more about specifying packages, see 'go help packages'.
For more about how 'go get' finds source code to
diff --git a/src/cmd/go/help.go b/src/cmd/go/help.go
index 45d8ae5..2f463f7 100644
--- a/src/cmd/go/help.go
+++ b/src/cmd/go/help.go
@@ -261,6 +261,11 @@
let package authors make sure the custom import path is used and not a
direct path to the underlying code hosting site.
+If the vendoring experiment is enabled (see 'go help gopath'),
+then import path checking is disabled for code found within vendor trees.
+This makes it possible to copy code into alternate locations in vendor trees
+without needing to update import comments.
+
See https://golang.org/s/go14customimport for details.
`,
}
@@ -282,10 +287,10 @@
Each directory listed in GOPATH must have a prescribed structure:
-The src/ directory holds source code. The path below 'src'
+The src directory holds source code. The path below src
determines the import path or executable name.
-The pkg/ directory holds installed package objects.
+The pkg directory holds installed package objects.
As in the Go tree, each target operating system and
architecture pair has its own subdirectory of pkg
(pkg/GOOS_GOARCH).
@@ -294,11 +299,11 @@
source in DIR/src/foo/bar can be imported as "foo/bar" and
has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
-The bin/ directory holds compiled commands.
+The bin directory holds compiled commands.
Each command is named for its source directory, but only
the final element, not the entire path. That is, the
command with source in DIR/src/foo/quux is installed into
-DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped
+DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
so that you can add DIR/bin to your PATH to get at the
installed commands. If the GOBIN environment variable is
set, commands are installed to the directory it names instead
@@ -327,6 +332,91 @@
in the list.
See https://golang.org/doc/code.html for an example.
+
+Internal Directories
+
+Code in or below a directory named "internal" is importable only
+by code in the directory tree rooted at the parent of "internal".
+Here's an extended version of the directory layout above:
+
+ /home/user/gocode/
+ src/
+ crash/
+ bang/ (go code in package bang)
+ b.go
+ foo/ (go code in package foo)
+ f.go
+ bar/ (go code in package bar)
+ x.go
+ internal/
+ baz/ (go code in package baz)
+ z.go
+ quux/ (go code in package main)
+ y.go
+
+
+The code in z.go is imported as "foo/internal/baz", but that
+import statement can only appear in source files in the subtree
+rooted at foo. The source files foo/f.go, foo/bar/x.go, and
+foo/quux/y.go can all import "foo/internal/baz", but the source file
+crash/bang/b.go cannot.
+
+See https://golang.org/s/go14internal for details.
+
+Vendor Directories
+
+Go 1.5 includes experimental support for using local copies
+of external dependencies to satisfy imports of those dependencies,
+often referred to as vendoring. Setting the environment variable
+GO15VENDOREXPERIMENT=1 enables that experimental support.
+
+When the vendor experiment is enabled,
+code below a directory named "vendor" is importable only
+by code in the directory tree rooted at the parent of "vendor",
+and only using an import path that omits the prefix up to and
+including the vendor element.
+
+Here's the example from the previous section,
+but with the "internal" directory renamed to "vendor"
+and a new foo/vendor/crash/bang directory added:
+
+ /home/user/gocode/
+ src/
+ crash/
+ bang/ (go code in package bang)
+ b.go
+ foo/ (go code in package foo)
+ f.go
+ bar/ (go code in package bar)
+ x.go
+ vendor/
+ crash/
+ bang/ (go code in package bang)
+ b.go
+ baz/ (go code in package baz)
+ z.go
+ quux/ (go code in package main)
+ y.go
+
+The same visibility rules apply as for internal, but the code
+in z.go is imported as "baz", not as "foo/vendor/baz".
+
+Code in vendor directories deeper in the source tree shadows
+code in higher directories. Within the subtree rooted at foo, an import
+of "crash/bang" resolves to "foo/vendor/crash/bang", not the
+top-level "crash/bang".
+
+Code in vendor directories is not subject to import path
+checking (see 'go help importpath').
+
+When the vendor experiment is enabled, 'go get' checks out
+submodules when checking out or updating a git repository
+(see 'go help get').
+
+The vendoring semantics are an experiment, and they may change
+in future releases. Once settled, they will be on by default.
+
+See https://golang.org/s/go15vendor for details.
`,
}
