doc/go1.13: describe changes to 'go get'

Also fix up markup in the “Version validation” section to correct
indentation on Chrome.

Change-Id: Ib930d324567c086bbd0c67b105272bdfcca77b12
Reviewed-on: https://go-review.googlesource.com/c/go/+/183630Reviewed-by: Jay Conrod <jayconrod@google.com>

doc/go1.13.html

@@ -167,11 +167,56 @@ Do not send CLs removing the interior tags from such phrases.
 
 <h3 id="modules">Modules</h3>
 
-<p id="patch-suffix"><!-- CL 167747 -->
-  <a href="/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them"><code>go</code>
-  <code>get</code></a> in module mode now supports the version suffix
-  <code>@patch</code> to request the latest patch release.
-  TODO(bcmills): expand.
+<h4 id="go-get"><code>go</code> <code>get</code></h3>
+
+<p><!-- CL 174099 -->
+  In module-aware mode, the set of modules updated by
+  <a href="/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them"><code>go</code> <code>get</code> <code>-u</code></a>
+  is now smaller, and is more consistent with the set of packages updated by
+  <code>go</code> <code>get</code> <code>-u</code> in GOPATH mode.
+  <code>go</code> <code>get</code> <code>-u</code> continues to update the
+  modules and packages named on the command line, but additionally updates only
+  the modules containing the packages <em>imported by</em> the named packages,
+  rather than the transitive module requirements of the modules containing the
+  named packages.
+</p>
+
+<p>
+  Note in particular that <code>go</code> <code>get</code> <code>-u</code>
+  (without additional arguments) now updates only the transitive imports of the
+  package in the current directory. To instead update all of the packages
+  transitively imported by the main module (including test dependencies), use
+  <code>go</code> <code>get</code> <code>-u</code> <code>all</code>.
+</p>
+
+<p><!-- CL 177879 -->
+  As a result of the above changes to
+  <code>go</code> <code>get</code> <code>-u</code>, the
+  <code>go</code> <code>get</code> subcommand no longer supports
+  the <code>-m</code> flag, which caused <code>go</code> <code>get</code> to
+  stop before loading packages. The <code>-d</code> flag remains supported, and
+  continues to cause <code>go</code> <code>get</code> to stop after downloading
+  the source code needed to build dependencies of the named packages.
+</p>
+
+<p><!-- CL 167747 -->
+  In module-aware mode, the <code>go</code> <code>get</code> subcommand now
+  supports the version suffix <code>@patch</code>. The <code>@patch</code>
+  suffix indicates that the named module, or module containing the named
+  package, should be updated to the highest patch release with the same
+  major and minor versions as the version found in the build list.
+  If no such version is present in the build list, <code>@patch</code> is
+  equivalent to the existing <code>@latest</code> suffix.
+</p>
+
+<p><!-- CL 177677 -->
+  Additionally, the <code>go</code> <code>get</code> subcommand now supports
+  the <code>-t</code> flag in module-aware mode. As in GOPATH mode,
+  the <code>-t</code> flag instructs <code>go</code> <code>get</code> to include
+  the packages imported by <em>tests of<em> the packages named on the command
+  line. If the <code>-t</code> flag is set, the packages imported by tests will
+  be updated (if the <code>-u</code> flag is set), downloaded, and built (unless
+  the <code>-d</code> flag is set) along with the usual non-test packages.
 </p>
 
 <h4 id="version-validation">Version validation</h4><!-- CL 181881 -->
@@ -206,29 +251,31 @@ Do not send CLs removing the interior tags from such phrases.
 </p>
 
 <p>
-  If the main module directly requires a version that fails the above
-  validation, a corrected version can be obtained by redacting the version to
-  just the commit hash and re-running a <code>go</code> command such as <code>go
-  list -m all</code> or <code>go mod tidy</code>. For example,
-  <pre>require github.com/docker/docker v1.14.0-0.20190319215453-e7b5f7dbe98c</pre>
-      can be redacted to
-  <pre>require github.com/docker/docker e7b5f7dbe98c</pre>
-  which resolves to
-  <pre>require github.com/docker/docker v0.7.3-0.20190319215453-e7b5f7dbe98c</pre>
-</p>
+  If a <code>require</code> directive in the
+  <a href="/cmd/go/#hdr-The_main_module_and_the_build_list">main module</a> uses
+  an invalid pseudo-version, it can usually be corrected by redacting the
+  version to just the commit hash and re-running a <code>go</code> command, such
+  as <code>go</coqde> <code>list</code> <code>-m</code> <code>all</code>
+  or <code>go</code> <code>mod</code> <code>tidy</code>. For example,
+</p>
+<pre>require github.com/docker/docker v1.14.0-0.20190319215453-e7b5f7dbe98c</pre>
+<p>can be redacted to</p>
+<pre>require github.com/docker/docker e7b5f7dbe98c</pre>
+<p>which currently resolves to</p>
+<pre>require github.com/docker/docker v0.7.3-0.20190319215453-e7b5f7dbe98c</pre>
 
 <p>
-  If the main module has a transitive requirement on a version that fails
-  validation, the invalid version can still be replaced with a valid one through
-  the use of a <a href="/cmd/go/#hdr-The_go_mod_file"><code>replace</code>
-  directive</a> in the <code>go.mod</code> file of
-  the <a href="/cmd/go/#hdr-The_main_module_and_the_build_list">main module</a>.
-  If the replacement is a commit hash, it will be resolved to the appropriate
-  pseudo-version. For example,
-  <pre>replace github.com/docker/docker v1.14.0-0.20190319215453-e7b5f7dbe98c => github.com/docker/docker e7b5f7dbe98c</pre>
-  resolves to
-  <pre>replace github.com/docker/docker v1.14.0-0.20190319215453-e7b5f7dbe98c => github.com/docker/docker v0.7.3-0.20190319215453-e7b5f7dbe98c</pre>
-</p>
+  If one of the transitive dependencies of the main module requires an invalid
+  version or pseudo-version, the invalid version can be replaced with a valid
+  one using a
+  <a href="/cmd/go/#hdr-The_go_mod_file"><code>replace</code> directive</a> in
+  the <code>go.mod</code> file of the main module. If the replacement is a
+  commit hash, it will be resolved to the appropriate pseudo-version as above.
+  For example,
+</p>
+<pre>replace github.com/docker/docker v1.14.0-0.20190319215453-e7b5f7dbe98c => github.com/docker/docker e7b5f7dbe98c</pre>
+<p>currently resolves to</p>
+<pre>replace github.com/docker/docker v1.14.0-0.20190319215453-e7b5f7dbe98c => github.com/docker/docker v0.7.3-0.20190319215453-e7b5f7dbe98c</pre>
 
 <h3 id="go-command">Go command</h3>
 
@@ -251,6 +298,10 @@ Do not send CLs removing the interior tags from such phrases.
   files may be searched for directives but ignored during build.
 </p>
 
+<p><!-- CL 171137 -->
+  TODO
+</p>
+
 <h3 id="compiler">Compiler toolchain</h3>
 
 <p><!-- CL 170448 -->