cmd/go: document relative imports

Fixes #3524.

R=golang-dev, iant, r
CC=golang-dev
https://golang.org/cl/14296043

src/cmd/go/doc.go

@@ -32,10 +32,10 @@ Use "go help [command]" for more information about a command.
 
 Additional help topics:
 
-    c           calling between Go and C/C++
+    c           calling between Go and C
     gopath      GOPATH environment variable
+    importpath  import path syntax
     packages    description of package lists
-    remote      remote import path syntax
     testflag    description of testing flags
     testfunc    description of testing functions
 
@@ -247,7 +247,7 @@ retrieves the most recent version of the package.
 For more about specifying packages, see 'go help packages'.
 
 For more about how 'go get' finds source code to
-download, see 'go help remote'.
+download, see 'go help importpath'.
 
 See also: go build, go install, go clean.
 
@@ -544,66 +544,40 @@ but new packages are always downloaded into the first directory
 in the list.
 
 
-Description of package lists
-
-Many commands apply to a set of packages:
-
-	go action [packages]
-
-Usually, [packages] is a list of import paths.
-
-An import path that is a rooted path or that begins with
-a . or .. element is interpreted as a file system path and
-denotes the package in that directory.
-
-Otherwise, the import path P denotes the package found in
-the directory DIR/src/P for some DIR listed in the GOPATH
-environment variable (see 'go help gopath').
-
-If no import paths are given, the action applies to the
-package in the current directory.
-
-There are three reserved names for paths that should not be used
-for packages to be built with the go tool:
-
-- "main" denotes the top-level package in a stand-alone executable.
-
-- "all" expands to all package directories found in all the GOPATH
-trees. For example, 'go list all' lists all the packages on the local
-system.
-
-- "std" is like all but expands to just the packages in the standard
-Go library.
-
-An import path is a pattern if it includes one or more "..." wildcards,
-each of which can match any string, including the empty string and
-strings containing slashes.  Such a pattern expands to all package
-directories found in the GOPATH trees with names matching the
-patterns.  As a special case, x/... matches x as well as x's subdirectories.
-For example, net/... expands to net and packages in its subdirectories.
-
-An import path can also name a package to be downloaded from
-a remote repository.  Run 'go help remote' for details.
-
-Every package in a program must have a unique import path.
-By convention, this is arranged by starting each path with a
-unique prefix that belongs to you.  For example, paths used
-internally at Google all begin with 'google', and paths
-denoting remote repositories begin with the path to the code,
-such as 'code.google.com/p/project'.
-
-As a special case, if the package list is a list of .go files from a
-single directory, the command is applied to a single synthesized
-package made up of exactly those files, ignoring any build constraints
-in those files and ignoring any other files in the directory.
-
-File names that begin with "." or "_" are ignored by the go tool.
-
-
-Remote import path syntax
+Import path syntax
 
 An import path (see 'go help packages') denotes a package
-stored in the local file system.  Certain import paths also
+stored in the local file system.  In general, an import path denotes
+either a standard package (such as "unicode/utf8") or a package
+found in one of the work spaces (see 'go help gopath').
+
+Relative import paths
+
+An import path beginning with ./ or ../ is called a relative path.
+The toolchain supports relative import paths as a shortcut in two ways.
+
+First, a relative path can be used as a shorthand on the command line.
+If you are working in the directory containing the code imported as
+"unicode" and want to run the tests for "unicode/utf8", you can type
+"go test ./utf8" instead of needing to specify the full path.
+Similarly, in the reverse situation, "go test .." will test "unicode" from
+the "unicode/utf8" directory. Relative patterns are also allowed, like
+"go test ./..." to test all subdirectories. See 'go help packages' for details
+on the pattern syntax.
+
+Second, if you are compiling a Go program not in a work space,
+you can use a relative path in an import statement in that program
+to refer to nearby code also not in a work space.
+This makes it easy to experiment with small multipackage programs
+outside of the usual work spaces, but such programs cannot be
+installed with "go install" (there is no work space in which to install them),
+so they are rebuilt from scratch each time they are built.
+To avoid ambiguity, Go programs cannot use relative import paths
+within a work space.
+
+Remote import paths
+
+Certain import paths also
 describe how to obtain the source code for the package using
 a revision control system.
 
@@ -714,6 +688,62 @@ package appropriate for the Go release being used.
 Run 'go help install' for more.
 
 
+Description of package lists
+
+Many commands apply to a set of packages:
+
+	go action [packages]
+
+Usually, [packages] is a list of import paths.
+
+An import path that is a rooted path or that begins with
+a . or .. element is interpreted as a file system path and
+denotes the package in that directory.
+
+Otherwise, the import path P denotes the package found in
+the directory DIR/src/P for some DIR listed in the GOPATH
+environment variable (see 'go help gopath').
+
+If no import paths are given, the action applies to the
+package in the current directory.
+
+There are three reserved names for paths that should not be used
+for packages to be built with the go tool:
+
+- "main" denotes the top-level package in a stand-alone executable.
+
+- "all" expands to all package directories found in all the GOPATH
+trees. For example, 'go list all' lists all the packages on the local
+system.
+
+- "std" is like all but expands to just the packages in the standard
+Go library.
+
+An import path is a pattern if it includes one or more "..." wildcards,
+each of which can match any string, including the empty string and
+strings containing slashes.  Such a pattern expands to all package
+directories found in the GOPATH trees with names matching the
+patterns.  As a special case, x/... matches x as well as x's subdirectories.
+For example, net/... expands to net and packages in its subdirectories.
+
+An import path can also name a package to be downloaded from
+a remote repository.  Run 'go help importpath' for details.
+
+Every package in a program must have a unique import path.
+By convention, this is arranged by starting each path with a
+unique prefix that belongs to you.  For example, paths used
+internally at Google all begin with 'google', and paths
+denoting remote repositories begin with the path to the code,
+such as 'code.google.com/p/project'.
+
+As a special case, if the package list is a list of .go files from a
+single directory, the command is applied to a single synthesized
+package made up of exactly those files, ignoring any build constraints
+in those files and ignoring any other files in the directory.
+
+File names that begin with "." or "_" are ignored by the go tool.
+
+
 Description of testing flags
 
 The 'go test' command takes both flags that apply to 'go test' itself

src/cmd/go/get.go

@@ -49,7 +49,7 @@ retrieves the most recent version of the package.
 For more about specifying packages, see 'go help packages'.
 
 For more about how 'go get' finds source code to
-download, see 'go help remote'.
+download, see 'go help importpath'.
 
 See also: go build, go install, go clean.
 	`,

src/cmd/go/help.go

@@ -6,7 +6,7 @@ package main
 
 var helpC = &Command{
 	UsageLine: "c",
-	Short:     "calling between Go and C/C++",
+	Short:     "calling between Go and C",
 	Long: `
 There are two different ways to call between Go and C/C++ code.
 
@@ -67,7 +67,7 @@ patterns.  As a special case, x/... matches x as well as x's subdirectories.
 For example, net/... expands to net and packages in its subdirectories.
 
 An import path can also name a package to be downloaded from
-a remote repository.  Run 'go help remote' for details.
+a remote repository.  Run 'go help importpath' for details.
 
 Every package in a program must have a unique import path.
 By convention, this is arranged by starting each path with a
@@ -85,13 +85,43 @@ File names that begin with "." or "_" are ignored by the go tool.
 	`,
 }
 
-var helpRemote = &Command{
-	UsageLine: "remote",
-	Short:     "remote import path syntax",
+var helpImportPath = &Command{
+	UsageLine: "importpath",
+	Short:     "import path syntax",
 	Long: `
 
 An import path (see 'go help packages') denotes a package
-stored in the local file system.  Certain import paths also
+stored in the local file system.  In general, an import path denotes
+either a standard package (such as "unicode/utf8") or a package
+found in one of the work spaces (see 'go help gopath').
+
+Relative import paths
+
+An import path beginning with ./ or ../ is called a relative path.
+The toolchain supports relative import paths as a shortcut in two ways.
+
+First, a relative path can be used as a shorthand on the command line.
+If you are working in the directory containing the code imported as
+"unicode" and want to run the tests for "unicode/utf8", you can type
+"go test ./utf8" instead of needing to specify the full path.
+Similarly, in the reverse situation, "go test .." will test "unicode" from
+the "unicode/utf8" directory. Relative patterns are also allowed, like
+"go test ./..." to test all subdirectories. See 'go help packages' for details
+on the pattern syntax.
+
+Second, if you are compiling a Go program not in a work space,
+you can use a relative path in an import statement in that program
+to refer to nearby code also not in a work space.
+This makes it easy to experiment with small multipackage programs
+outside of the usual work spaces, but such programs cannot be
+installed with "go install" (there is no work space in which to install them),
+so they are rebuilt from scratch each time they are built.
+To avoid ambiguity, Go programs cannot use relative import paths
+within a work space.
+
+Remote import paths
+
+Certain import paths also
 describe how to obtain the source code for the package using
 a revision control system.
 

src/cmd/go/main.go

@@ -90,8 +90,8 @@ var commands = []*Command{
 
 	helpC,
 	helpGopath,
+	helpImportPath,
 	helpPackages,
-	helpRemote,
 	helpTestflag,
 	helpTestfunc,
 }