Commit a6ad626b authored by Bryan C. Mills's avatar Bryan C. Mills

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: default avatarJay Conrod <jayconrod@google.com>
parent fd629821
......@@ -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 -->
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment