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/+/183630
Reviewed-by: Jay Conrod <jayconrod@google.com>
diff --git a/doc/go1.13.html b/doc/go1.13.html
index ec28e38..54dc765 100644
--- a/doc/go1.13.html
+++ b/doc/go1.13.html
@@ -167,11 +167,56 @@
<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 @@
</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>
+ 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>
+ 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 @@
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 -->
