doc, cmd/go: adjust documentation for default GOPATH

Replaces CL 33356.

Fixes #17262.

Change-Id: Idfb2343e90771775e51a66c63760f458737a288c
Reviewed-on: https://go-review.googlesource.com/33730
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

7 files changed, 87 insertions, 98 deletions

diff --git a/doc/articles/go_command.html b/doc/articles/go_command.html
index 002c034367..0fd83cb53a 100644
--- a/doc/articles/go_command.html
+++ b/doc/articles/go_command.html
@@ -97,13 +97,14 @@ a tool like the go command to look at an unfamiliar import path and
 deduce where to obtain the source code.</p>
 
 <p>Second, the place to store sources in the local file system is derived
-in a known way from the import path.  Specifically, the first choice
-is <code>$GOPATH/src/&lt;import-path&gt;</code>.  If <code>$GOPATH</code> is
-unset, the go command will fall back to storing source code alongside the
-standard Go packages, in <code>$GOROOT/src/&lt;import-path&gt;</code>.
+in a known way from the import path, specifically
+<code>$GOPATH/src/&lt;import-path&gt;</code>.
+If unset, <code>$GOPATH</code> defaults to a subdirectory
+named <code>go</code> in the user's home directory.
 If <code>$GOPATH</code> is set to a list of paths, the go command tries
 <code>&lt;dir&gt;/src/&lt;import-path&gt;</code> for each of the directories in
-that list.</p>
+that list.
+</p>
 
 <p>Each of those trees contains, by convention, a top-level directory named
 "<code>bin</code>", for holding compiled executables, and a top-level directory
@@ -137,28 +138,13 @@ to the use of a specific tool chain.</p>
 
 <h2>Getting started with the go command</h2>
 
-<p>Finally, a quick tour of how to use the go command, to supplement
-the information in <a href="/doc/code.html">How to Write Go Code</a>,
-which you might want to read first.  Assuming you want
-to keep your source code separate from the Go distribution source
-tree, the first step is to set <code>$GOPATH</code>, the one piece of global
-configuration that the go command needs.  The <code>$GOPATH</code> can be a
-list of directories, but by far the most common usage should be to set it to a
-single directory.  In particular, you do not need a separate entry in
-<code>$GOPATH</code> for each of your projects.  One <code>$GOPATH</code> can
-support many projects.</p>
-
-<p>Here’s an example.  Let’s say we decide to keep our Go code in the directory
-<code>$HOME/mygo</code>.  We need to create that directory and set
-<code>$GOPATH</code> accordingly.</p>
+<p>Finally, a quick tour of how to use the go command.
+As mentioned above, the default <code>$GOPATH</code> on Unix is <code>$HOME/go</code>.
+We'll store our programs there.
+To use a different location, you can set <code>$GOPATH</code>;
+see <a href="/doc/code.html">How to Write Go Code</a> for details.
 
-<pre>
-$ mkdir $HOME/mygo
-$ export GOPATH=$HOME/mygo
-$
-</pre>
-
-<p>Into this directory, we now add some source code.  Suppose we want to use
+<p>We first add some source code.  Suppose we want to use
 the indexing library from the codesearch project along with a left-leaning
 red-black tree.  We can install both with the "<code>go get</code>"
 subcommand:</p>
@@ -169,8 +155,8 @@ $ go get github.com/petar/GoLLRB/llrb
 $
 </pre>
 
-<p>Both of these projects are now downloaded and installed into our
-<code>$GOPATH</code> directory. The one tree now contains the two directories
+<p>Both of these projects are now downloaded and installed into <code>$HOME/go</code>,
+which contains the two directories
 <code>src/github.com/google/codesearch/index/</code> and
 <code>src/github.com/petar/GoLLRB/llrb/</code>, along with the compiled
 packages (in <code>pkg/</code>) for those libraries and their dependencies.</p>
@@ -184,6 +170,7 @@ the pattern "<code>./...</code>" means start in the current directory
 ("<code>...</code>"):</p>
 
 <pre>
+$ cd $HOME/go/src
 $ go list ./...
 github.com/google/codesearch/cmd/cgrep
 github.com/google/codesearch/cmd/cindex
@@ -215,7 +202,7 @@ $
 current directory:</p>
 
 <pre>
-$ cd $GOPATH/src/github.com/google/codesearch/regexp
+$ cd github.com/google/codesearch/regexp
 $ go list
 github.com/google/codesearch/regexp
 $ go test -v
@@ -244,9 +231,6 @@ pick such a long name, but that ability would require additional configuration
 and complexity in the tool. Typing an extra directory name or two is a small
 price to pay for the increased simplicity and power.</p>
 
-<p>As the example shows, it’s fine to work with packages from many different
-projects at once within a single <code>$GOPATH</code> root directory.</p>
-
 <h2>Limitations</h2>
 
 <p>As mentioned above, the go command is not a general-purpose build
diff --git a/doc/code.html b/doc/code.html
index b64bc1a142..9978b523b4 100644
--- a/doc/code.html
+++ b/doc/code.html
@@ -120,30 +120,43 @@ We will discuss the distinction <a href="#PackageNames">later</a>.
 
 <p>
 The <code>GOPATH</code> environment variable specifies the location of your
-workspace. It is likely the only environment variable you'll need to set
-when developing Go code.
+workspace. It defaults to a directory named <code>go</code> inside your home directory,
+so <code>$HOME/go</code> on Unix,
+<code>$home/go</code> on Plan 9,
+and <code>%USERPROFILE%\go</code> (usually <code>C:\Users\YourName\go</code>) on Windows.
+If you would like to work in a different location, you will need to set
+<code>GOPATH</code> to the path to that directory.
+(Another common setup is to set <code>GOPATH=$HOME</code>.)
+Note that <code>GOPATH</code> must <b>not</b> be the
+same path as your Go installation.
 </p>
 
 <p>
-To get started, create a workspace directory and set <code>GOPATH</code>
-accordingly. Your workspace can be located wherever you like, but we'll use
-<code>$HOME/work</code> in this document. Note that this must <b>not</b> be the
-same path as your Go installation.
-(Another common setup is to set <code>GOPATH=$HOME</code>.)
+The command <code>go</code> <code>env</code> <code>GOPATH</code>
+prints the effective current <code>GOPATH</code>;
+it prints the default location if the environment variable is unset.
+</p>
+
+<p>
+For convenience, add the workspace's <code>bin</code> subdirectory
+to your <code>PATH</code>:
 </p>
 
 <pre>
-$ <b>mkdir $HOME/work</b>
-$ <b>export GOPATH=$HOME/work</b>
+$ <b>export PATH=$PATH:$(go env GOPATH)/bin</b>
 </pre>
 
 <p>
-For convenience, add the workspace's <code>bin</code> subdirectory
-to your <code>PATH</code>:
+The scripts in the rest of this document use <code>$GOPATH</code>
+instead of <code>$(go env GOPATH)</code> for brevity.
+To make the scripts run as written
+if you have not set GOPATH,
+you can substitute $HOME/go in those commands
+or else run:
 </p>
 
 <pre>
-$ <b>export PATH=$PATH:$GOPATH/bin</b>
+$ <b>export GOPATH=$(go env GOPATH)</b>
 </pre>
 
 <p>
diff --git a/doc/go_faq.html b/doc/go_faq.html
index 884d98ba6e..3006b3d3d4 100644
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -1094,7 +1094,7 @@ it's easy to work around this. For GitHub, try one of these solutions:
 <ul>
 <li>Manually clone the repository in the expected package directory:
 <pre>
-$ cd $GOPATH/src/github.com/username
+$ cd src/github.com/username
 $ git clone git@github.com:username/package.git
 </pre>
 </li>
diff --git a/doc/install-source.html b/doc/install-source.html
index 22cc1d5dec..4a25e37d22 100644
--- a/doc/install-source.html
+++ b/doc/install-source.html
@@ -430,7 +430,7 @@ to override the defaults.
 <ul>
 <li><code>$GOROOT</code>
 <p>
-The root of the Go tree, often <code>$HOME/go</code>.
+The root of the Go tree, often <code>$HOME/go1.X</code>.
 Its value is built into the tree when it is compiled, and
 defaults to the parent of the directory where <code>all.bash</code> was run.
 There is no need to set this unless you want to switch between multiple
@@ -632,7 +632,7 @@ something like this:
 </p>
 
 <pre>
-export GOROOT=$HOME/go
+export GOROOT=$HOME/go1.X
 export GOARCH=amd64
 export GOOS=linux
 </pre>
diff --git a/doc/install.html b/doc/install.html
index 1305c970e3..ebe66c0205 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -117,12 +117,12 @@ to point to the directory in which it was installed.
 </p>
 
 <p>
-For example, if you installed Go to your home directory you should add the
-following commands to <code>$HOME/.profile</code>:
+For example, if you installed Go to your home directory you should add
+commands like the following to <code>$HOME/.profile</code>:
 </p>
 
 <pre>
-export GOROOT=$HOME/go
+export GOROOT=$HOME/go1.X
 export PATH=$PATH:$GOROOT/bin
 </pre>
 
@@ -219,37 +219,16 @@ and building a simple program, as follows.
 </p>
 
 <p>
-Create a directory to contain your <a href="code.html#Workspaces">workspace</a>,
-<code class="testUnix">$HOME/work</code>
-<code class="testWindows" style="display: none">C:\work</code>
-for example, and set the <code>GOPATH</code> environment
-variable to point to that location.
+Create your <a href="code.html#Workspaces">workspace</a> directory,
+<code class="testUnix">$HOME/go</code><code class="testWindows">%USERPROFILE%\go</code>.
+(If you'd like to use a different directory,
+you will need to set the <code>GOPATH</code> environment variable;
+see <a href="code.html#Workspaces">How to Write Go Code</a> for details.)
 </p>
 
-<pre class="testUnix">
-$ <b>export GOPATH=$HOME/work</b>
-</pre>
-
-<pre class="testWindows" style="display: none">
-C:\&gt; <b>set GOPATH=C:\work</b>
-</pre>
-
 <p>
-<span class="testUnix">
-You should put the above command in your shell startup script
-(<code>$HOME/.profile</code> for example).
-</span>
-<span class="testWindows">
-On Windows, follow the <a href="#windows_env">instructions above</a> to set the
-<code>GOPATH</code> environment variable on your system.
-</span>
-</p>
-
-<p>
-Next, make the directories <code>src/github.com/user/hello</code> inside your
-workspace (if you use GitHub, substitute your user name for <code>user</code>),
-and inside the <code>hello</code> directory create a file named <code>hello.go</code>
-with the following contents:
+Next, make the directory <code>src/hello</code> inside your workspace,
+and in that directory create a file named <code>hello.go</code> that looks like:
 </p>
 
 <pre>
@@ -263,30 +242,33 @@ func main() {
 </pre>
 
 <p>
-Then compile it with the <code>go</code> tool:
+Then build it with the <code>go</code> tool:
 </p>
 
 <pre class="testUnix">
-$ <b>go install github.com/user/hello</b>
+$ <b>cd $HOME/go/src/hello
+$ <b>go build</b>
 </pre>
 
 <pre class="testWindows" style="display: none">
-C:\&gt; <b>go install github.com/user/hello</b>
+C:\&gt; <b>cd %USERPROFILE%\go\src\hello<b>
+C:\Users\Gopher\go\src\hello&gt; <b>go build</b>
 </pre>
 
 <p>
-The command above will put an executable command named <code>hello</code> 
-(or <code>hello.exe</code>) inside the <code>bin</code> directory of your workspace.
-Execute the command to see the greeting:
+The command above will build an executable named
+<code class="testUnix">hello</code><code class="testWindows">hello.exe</code>
+in the directory alongside your source code.
+Execute it to see the greeting:
 </p>
 
 <pre class="testUnix">
-$ <b>$GOPATH/bin/hello</b>
+$ <b>./hello</b>
 hello, world
 </pre>
 
 <pre class="testWindows" style="display: none">
-C:\&gt; <b>%GOPATH%\bin\hello</b>
+C:\Users\Gopher\go\src\hello&gt; <b>hello</b>
 hello, world
 </pre>
 
@@ -295,6 +277,12 @@ If you see the "hello, world" message then your Go installation is working.
 </p>
 
 <p>
+You can run <code>go</code> <code>install</code> to install the binary into
+your workspace's <code>bin</code> directory
+or <code>go</code> <code>clean</code> to remove it.
+</p>
+
+<p>
 Before rushing off to write Go code please read the
 <a href="/doc/code.html">How to Write Go Code</a> document,
 which describes some essential concepts about using the Go tools.
diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 3c909fed26..0272e185ab 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -929,8 +929,10 @@
 // On Windows, the value is a semicolon-separated string.
 // On Plan 9, the value is a list.
 //
-// GOPATH must be set to get, build and install packages outside the
-// standard Go tree.
+// If the environment variable is unset, GOPATH defaults
+// to a subdirectory named "go" in the user's home directory
+// ($HOME/go on Unix, %USERPROFILE%\go on Windows).
+// Run "go env GOPATH" to see the current GOPATH.
 //
 // Each directory listed in GOPATH must have a prescribed structure:
 //
@@ -958,9 +960,9 @@
 //
 // Here's an example directory layout:
 //
-//     GOPATH=/home/user/gocode
+//     GOPATH=/home/user/go
 //
-//     /home/user/gocode/
+//     /home/user/go/
 //         src/
 //             foo/
 //                 bar/               (go code in package bar)
@@ -986,7 +988,7 @@
 // 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/
+//     /home/user/go/
 //         src/
 //             crash/
 //                 bang/              (go code in package bang)
@@ -1024,7 +1026,7 @@
 // but with the "internal" directory renamed to "vendor"
 // and a new foo/vendor/crash/bang directory added:
 //
-//     /home/user/gocode/
+//     /home/user/go/
 //         src/
 //             crash/
 //                 bang/              (go code in package bang)
diff --git a/src/cmd/go/help.go b/src/cmd/go/help.go
index f90cfcc7e9..183b27e7e6 100644
--- a/src/cmd/go/help.go
+++ b/src/cmd/go/help.go
@@ -289,8 +289,10 @@ On Unix, the value is a colon-separated string.
 On Windows, the value is a semicolon-separated string.
 On Plan 9, the value is a list.
 
-GOPATH must be set to get, build and install packages outside the
-standard Go tree.
+If the environment variable is unset, GOPATH defaults
+to a subdirectory named "go" in the user's home directory
+($HOME/go on Unix, %USERPROFILE%\go on Windows).
+Run "go env GOPATH" to see the current GOPATH.
 
 Each directory listed in GOPATH must have a prescribed structure:
 
@@ -318,9 +320,9 @@ of DIR/bin. GOBIN must be an absolute path.
 
 Here's an example directory layout:
 
-    GOPATH=/home/user/gocode
+    GOPATH=/home/user/go
 
-    /home/user/gocode/
+    /home/user/go/
         src/
             foo/
                 bar/               (go code in package bar)
@@ -346,7 +348,7 @@ 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/
+    /home/user/go/
         src/
             crash/
                 bang/              (go code in package bang)
@@ -384,7 +386,7 @@ 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/
+    /home/user/go/
         src/
             crash/
                 bang/              (go code in package bang)