aboutsummaryrefslogtreecommitdiff
path: root/_content/doc/modules
diff options
context:
space:
mode:
Diffstat (limited to '_content/doc/modules')
-rw-r--r--_content/doc/modules/developing.md23
-rw-r--r--_content/doc/modules/gomod-ref.md154
-rw-r--r--_content/doc/modules/major-version.md8
-rw-r--r--_content/doc/modules/managing-dependencies.md114
-rw-r--r--_content/doc/modules/managing-source.md21
-rw-r--r--_content/doc/modules/publishing.md8
-rw-r--r--_content/doc/modules/release-workflow.md45
-rw-r--r--_content/doc/modules/version-numbers.md58
8 files changed, 210 insertions, 221 deletions
diff --git a/_content/doc/modules/developing.md b/_content/doc/modules/developing.md
index bcaabfe8..c1cbe4cd 100644
--- a/_content/doc/modules/developing.md
+++ b/_content/doc/modules/developing.md
@@ -25,7 +25,7 @@ To support developing, publishing, and using modules, you use:
[Versioning](#versioning).
* **Go tools** that make it easier for other developers to manage
dependencies, including getting your module's source, upgrading, and so on.
- See [Managing dependencies](managing-dependencies).
+ See [Managing dependencies](/doc/modules/managing-dependencies).
**See also**
@@ -33,10 +33,9 @@ To support developing, publishing, and using modules, you use:
isn't the topic for you. Instead, see [Managing
dependencies](managing-dependencies).
* For a tutorial that includes a few module development basics, see
- [Tutorial: Create a Go module](https://golang.org/doc/tutorial/create-module).
+ [Tutorial: Create a Go module](/doc/tutorial/create-module).
-<a id="workflow" ></a>
-## Workflow for developing and publishing modules
+## Workflow for developing and publishing modules {#workflow}
When you want to publish your modules for others, you adopt a few conventions to
make using those modules easier.
@@ -51,8 +50,7 @@ and versioning workflow](release-workflow).
1. Over time, revise the module with versions that use a version numbering
convention that signals each version's stability and backward compatibility.
-<a id="design" ></a>
-## Design and development
+## Design and development {#design}
Your module will be easier for developers to find and use if the functions and
packages in it form a coherent whole. When you're designing a module's public
@@ -70,8 +68,7 @@ functions in the module while the module is still in development. For more
information, see "Coding against an unpublished module" in [Module release and
versioning workflow](release-workflow#unpublished).
-<a id="decentralized" ></a>
-## Decentralized publishing
+## Decentralized publishing {#decentralized}
In Go, you publish your module by tagging its code in your repository to make it
available for other developers to use. You don't need to push your module to a
@@ -88,13 +85,12 @@ along with the module version number you use to tag the module for release, to
locate and download the module for its users.
For more about source and publishing conventions and best practices, see
-[Managing module source](managing-source).
+[Managing module source](/doc/modules/managing-source).
For step-by-step instructions on publishing a module, see [Publishing a
module](publishing).
-<a id="discovery" ></a>
-## Package discovery
+## Package discovery {#discovery}
After you've published your module and someone has fetched it with Go tools, it
will become visible on the Go package discovery site at
@@ -107,8 +103,7 @@ runs the `go get` command to download its source code to compile with.
For more about how developers find and use modules, see [Managing
dependencies](managing-dependencies).
-<a id="versioning" ></a>
-## Versioning
+## Versioning {#versioning}
As you revise and improve your module over time, you assign version numbers
(based on the semantic versioning model) designed to signal each version's
@@ -121,4 +116,4 @@ For more on developing major version updates, see [Developing a major version
update](major-version).
For more about how you use the semantic versioning model for Go modules, see
-[Module version numbering](version-numbers).
+[Module version numbering](/doc/modules/version-numbers).
diff --git a/_content/doc/modules/gomod-ref.md b/_content/doc/modules/gomod-ref.md
index bdbe853e..7a7c2b7d 100644
--- a/_content/doc/modules/gomod-ref.md
+++ b/_content/doc/modules/gomod-ref.md
@@ -8,9 +8,12 @@ properties, including its dependencies on other modules and on versions of Go.
These properties include:
-* The current module's **module path**. This serves as both its location and
- unique identifier, when combined with its version number. It is also the
- prefix of the package path for all packages in the module.
+* The current module's **module path**. This should be a location from which
+the module can be down loaded by Go tools, such as the module code's
+repository location. This serves as a unique identifier, when combined
+with the module's version number. It is also the prefix of the package path for
+all packages in the module. For more about how Go locates the module, see the
+<a href="/ref/mod#vcs-find">Go Modules Reference</a>.
* The minimum **version of Go** required by the current module.
* A list of minimum versions of other **modules required** by the current module.
* Instructions, optionally, to **replace** a required module with another
@@ -18,9 +21,8 @@ These properties include:
a required module.
Go generates a go.mod file when you run the [`go mod init`
-command](https://golang.org/cmd/go/#hdr-Initialize_new_module_in_current_directory).
-The following example creates a go.mod file, setting the module's module path to
-example.com/mymodule:
+command](/ref/mod#go-mod-init). The following example creates a go.mod file,
+setting the module's module path to example.com/mymodule:
```
$ go mod init example.com/mymodule
@@ -28,26 +30,22 @@ $ go mod init example.com/mymodule
Use `go` commands to manage dependencies. The commands ensure that the
requirements described in your go.mod file remain consistent and the content of
-your go.mod file is valid. These commands include the [`go
-get`](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)
-and [`go mod
-tidy`](https://golang.org/cmd/go/#hdr-Add_missing_and_remove_unused_modules) and
-[`go mod
-edit`](https://golang.org/cmd/go/#hdr-Edit_go_mod_from_tools_or_scripts)
+your go.mod file is valid. These commands include the [`go get`](/ref/mod#go-get)
+and [`go mod tidy`](/ref/mod#go-mod-tidy) and [`go mod edit`](/ref/mod#go-mod-edit)
commands.
-For reference on `go` commands, see [Command go](https://golang.org/cmd/go/).
+For reference on `go` commands, see [Command go](/cmd/go/).
You can get help from the command line by typing `go help` _command-name_, as
with `go help mod tidy`.
**See also**
* Go tools make changes to your go.mod file as you use them to manage
- dependencies. For more, see [Managing dependencies](managing-dependencies).
+ dependencies. For more, see [Managing dependencies](/doc/modules/managing-dependencies).
* For more details and constraints related to go.mod files, see the [Go modules
- reference](https://golang.org/ref/mod#go-mod-file).
+ reference](/ref/mod#go-mod-file).
-## Example
+## Example {#example}
A go.mod file includes directives shown in the following example. These are
described in this topic.
@@ -67,24 +65,28 @@ replace example.com/thatmodule => ../thatmodule
exclude example.com/thismodule v1.3.0
```
-<a id="module" ></a>
-## module
+## module {#module}
-Declares the module's module path, the module's unique identifier when combined
-with the module version.
+Declares the module's module path, which is the module's unique identifier
+(when combined with the module version number). This becomes the import prefix
+for all packages the module contains.
-### Syntax
+### Syntax {#module-syntax}
<pre>module <var>module-path</var></pre>
<dl>
<dt>module-path</dt>
- <dd>The module's module path, usually a concatenation of the module source's
- repository domain and the module name. For module versions v2 and later,
- this value must end with the major version number, such as <code>/v2</code>.</dd>
+ <dd>The module's module path, usually the repository location from which
+ the module can be downloaded by Go tools. For module versions v2 and
+ later, this value must end with the major version number, such as
+ <code>/v2</code>.</dd>
</dl>
-### Examples
+### Examples {#module-examples}
+
+The following examples substitute `example.com` for a repository domain from
+which the module could be downloaded.
* Module declaration for a v0 or v1 module:
```
@@ -95,18 +97,35 @@ with the module version.
module example.com/mymodule/v2
```
-### Notes
+### Notes {#module-notes}
+
+The module path should be a path from which Go tools can download the module
+source. In practice, this is typically the module source's repository domain
+and path to the module code within the repository. The <code>go</code> command
+relies on this form when downloading module versions to resolve dependencies
+on the module user's behalf.
+
+Even if you're not at first intending to make your module available for use
+from other code, using its repository path is a best practice that will help
+you avoid having to rename the module if you publish it later.
-The module path, together with the module's version number, is a unique
-identifier for the module. Go uses the `module` directive's value to locate the
-module source when building other modules that depend on it.
+If at first you don't know the module's eventual repository location, consider
+temporarily using a safe substitute, such as the name of a domain you own or
+`example.com`, along with a path following from the module's name or source
+directory.
-<a id="go" ></a>
-## go
+For example, if you're developing in a `stringtools` directory, your temporary
+module path might be `example.com/stringtools`, as in the following example:
+
+```
+go mod init example.com/stringtools
+```
+
+## go {#go}
Specifies the minimum Go version required by the module.
-### Syntax
+### Syntax {#go-syntax}
<pre>go <var>minimum-go-version</var></pre>
@@ -115,28 +134,27 @@ Specifies the minimum Go version required by the module.
<dd>The minimum version of Go required to compile packages in this module.</dd>
</dl>
-### Examples
+### Examples {#go-examples}
* Module must run on Go version 1.14 or later:
```
go 1.14
```
-### Notes
+### Notes {#go-notes}
The version number also controls some module-related features in the `go`
command. For example, if the vendor directory is present, that directory will be
used automatically if the version number is 1.14 or higher.
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
-<a id="require" ></a>
-## require
+## require {#require}
Declares a module as dependency required by the current module, specifying the
minimum version of the module required.
-### Syntax
+### Syntax {#require-syntax}
<pre>require <var>module-path</var> <var>module-version</var></pre>
@@ -151,7 +169,7 @@ minimum version of the module required.
v0.0.0-20200921210052-fa0125251cc4.</dd>
</dl>
-### Examples
+### Examples {#require-examples}
* Requiring a released version v1.2.3:
```
@@ -163,7 +181,7 @@ minimum version of the module required.
require example.com/othermodule v0.0.0-20200921210052-fa0125251cc4
```
-### Notes
+### Notes {#require-notes}
When you run a `go` command such as `go get`, Go inserts `require` directives
for each module containing imported packages. When a module isn't yet tagged in
@@ -173,24 +191,23 @@ command.
You can have Go require a module from a location other than its repository by
using the [`replace` directive](#replace).
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
For more about managing dependencies, see the following:
-* [Adding a dependency](managing-dependencies#adding_dependency)
-* [Getting a specific dependency version](managing-dependencies#getting_version)
-* [Discovering available updates](managing-dependencies#discovering_updates)
-* [Upgrading or downgrading a dependency](managing-dependencies#upgrading)
-* [Synchronizing your code's dependencies](managing-dependencies#synchronizing)
+* [Adding a dependency](/doc/modules/managing-dependencies#adding_dependency)
+* [Getting a specific dependency version](/doc/modules/managing-dependencies#getting_version)
+* [Discovering available updates](/doc/modules/managing-dependencies#discovering_updates)
+* [Upgrading or downgrading a dependency](/doc/modules/managing-dependencies#upgrading)
+* [Synchronizing your code's dependencies](/doc/modules/managing-dependencies#synchronizing)
-<a id="replace" ></a>
-## replace
+## replace {#replace}
Replaces the content of a module at a specific version (or all versions) with
another module version or with a local directory. Go tools will use the
replacement path when resolving the dependency.
-### Syntax
+### Syntax {#replace-syntax}
<pre>replace <var>module-path</var> <var>[module-version]</var> => <var>replacement-path</var> <var>[replacement-version]</var></pre>
@@ -212,7 +229,7 @@ replacement path when resolving the dependency.
be specified if <em>replacement-path</em> is a module path (not a local directory).</dd>
</dl>
-### Examples
+### Examples {#replace-examples}
* Replacing with a fork of the module repository
@@ -229,7 +246,7 @@ replacement path when resolving the dependency.
for packages in the module you're replacing.
For more on using a forked copy of module code, see [Requiring external module
- code from your own repository fork](managing-dependencies#external_fork).
+ code from your own repository fork](/doc/modules/managing-dependencies#external_fork).
* Replacing with a different version number
@@ -270,9 +287,9 @@ replacement path when resolving the dependency.
```
For more on using a local copy of module code, see [Requiring module code in a
- local directory](managing-dependencies#local_directory).
+ local directory](/doc/modules/managing-dependencies#local_directory).
-### Notes
+### Notes {#replace-notes}
Use the `replace` directive to temporarily substitute a module path value with
another value when you want Go to use the other path to find the module's
@@ -282,7 +299,7 @@ replacement path.
Use the `exclude` and `replace` directives to control build-time dependency
resolution when building the current module. These directives are ignored in
-modules that are dependencies of the current module.
+modules that depend on the current module.
The `replace` directive can be useful in situations such as the following:
@@ -294,31 +311,31 @@ The `replace` directive can be useful in situations such as the following:
For more on replacing a required module, including using Go tools to make the
change, see:
-* [Requiring external module code from your own repository fork](managing-dependencies#external_fork)
-* [Requiring module code in a local directory](managing-dependencies#local_directory)
+* [Requiring external module code from your own repository
+fork](/doc/modules/managing-dependencies#external_fork)
+* [Requiring module code in a local
+directory](/doc/modules/managing-dependencies#local_directory)
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version
+numbering](/doc/modules/version-numbers).
-<a id="exclude" ></a>
-## exclude
+## exclude {#exclude}
Specifies a module or module version to exclude from the current module's
dependency graph.
-### Syntax
+### Syntax {#exclude-syntax}
-<pre>exclude <var>module-path</var> <var>[module-version]</var></pre>
+<pre>exclude <var>module-path</var> <var>module-version</var></pre>
<dl>
<dt>module-path</dt>
<dd>The module path of the module to exclude.</dd>
<dt>module-version</dt>
- <dd>Optional. A specific version to exclude. If this version number is
- omitted, all versions of the module are replaced with the content on the
- right side of the arrow.</dd>
+ <dd>The specific version to exclude.</dd>
</dl>
-### Example
+### Example {#exclude-example}
* Exclude example.com/theirmodule version v1.3.0
@@ -326,7 +343,7 @@ dependency graph.
exclude example.com/theirmodule v1.3.0
```
-### Notes
+### Notes {#exclude-notes}
Use the `exclude` directive to exclude a specific version of a module that is
indirectly required but can't be loaded for some reason. For example, you might
@@ -336,12 +353,11 @@ Use the `exclude` and `replace` directives to control build-time dependency
resolution when building the current module (the main module you're building).
These directives are ignored in modules that depend on the current module.
-You can use the [`go mod
-edit`](https://golang.org/cmd/go/#hdr-Edit_go_mod_from_tools_or_scripts) command
+You can use the [`go mod edit`](/ref/mod#go-mod-edit) command
to exclude a module, as in the followng example.
```
go mod edit -exclude=example.com/theirmodule@v1.3.0
```
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
diff --git a/_content/doc/modules/major-version.md b/_content/doc/modules/major-version.md
index fe1555bf..9143634f 100644
--- a/_content/doc/modules/major-version.md
+++ b/_content/doc/modules/major-version.md
@@ -13,7 +13,7 @@ different meaning for a module's users. Those users rely on these differences to
understand the level of risk a release represents to their own code. In other
words, when preparing a release, be sure that its version number accurately
reflects the nature of the changes since the preceding release. For more on
-version numbers, see [Module version numbering](version-numbers).
+version numbers, see [Module version numbering](/doc/modules/version-numbers).
**See also**
@@ -22,7 +22,7 @@ version numbers, see [Module version numbering](version-numbers).
* For an end-to-end view, see [Module release and versioning
workflow](release-workflow).
-## Considerations for a major version update
+## Considerations for a major version update {#considerations}
You should only update to a new major version when it's absolutely necessary.
A major version update represents significant churn for both you and your
@@ -52,7 +52,7 @@ the following:
wherever code imports packages from the new module. Your module's users must
also update their import paths if they want to upgrade to the new major version.
-## Branching for a major release
+## Branching for a major release {#branching}
The most straightforward approach to handling source when preparing to develop a
new major version is to branch the repository at the latest version of the
@@ -85,4 +85,4 @@ the source for your new version:
* Old import statement: `import "example.com/mymodule/package1"`
* New import statement: `import "example.com/mymodule/v2/package1"`
-For publishing steps, see [Publishing a module](publishing).
+For publishing steps, see [Publishing a module](/doc/modules/publishing).
diff --git a/_content/doc/modules/managing-dependencies.md b/_content/doc/modules/managing-dependencies.md
index 671ec5ad..1385a6fe 100644
--- a/_content/doc/modules/managing-dependencies.md
+++ b/_content/doc/modules/managing-dependencies.md
@@ -16,24 +16,23 @@ useful.
**See also**
* If you're new to working with dependencies as modules, take a look at the
- [Getting started tutorial](https://golang.org/doc/tutorial/getting-started)
+ [Getting started tutorial](/doc/tutorial/getting-started)
for a brief introduction.
* Using the `go` command to manage dependencies helps ensure that your
requirements remain consistent and the content of your go.mod file is valid.
- For reference on the commands, see [Command go](https://golang.org/cmd/go/).
+ For reference on the commands, see [Command go](/cmd/go/).
You can also get help from the command line by typing `go help`
_command-name_, as with `go help mod tidy`.
* Go commands you use to make dependency changes edit your go.mod file. For
- more about the contents of the file, see [go.mod file reference](gomod-ref).
+ more about the contents of the file, see [go.mod file reference](/doc/modules/gomod-ref).
* Making your editor or IDE aware of Go modules can make the work of managing
them easier. For more on editors that support Go, see [Editor plugins and
- IDEs](https://golang.org/doc/editors.html).
+ IDEs](/doc/editors.html).
* This topic doesn't describe how to develop, publish, and version modules for
others to use. For more on that, see [Developing and publishing
modules](developing).
-<a id="workflow" ></a>
-## Workflow for using and managing dependencies
+## Workflow for using and managing dependencies {#workflow}
You can get and use useful packages with Go tools. On
[pkg.go.dev](https://pkg.go.dev), you can search for packages you might find
@@ -46,13 +45,12 @@ each, see the sections in this topic.
1. [Locate useful packages](#locating_packages) on [pkg.go.dev](https://pkg.go.dev).
1. [Import the packages](#locating_packages) you want in your code.
1. Add your code to a module for dependency tracking (if it isn't in a module
- already). See [Enabling dependencies tracking](#enable_tracking)
+ already). See [Enabling dependency tracking](#enable_tracking)
1. [Add external packages as dependencies](#adding_dependency) so you can manage
them.
1. [Upgrade or downgrade dependency versions](#upgrading) as needed over time.
-<a id="modules" ></a>
-## Managing dependencies as modules
+## Managing dependencies as modules {#modules}
In Go, you manage dependencies as modules that contain the packages you import.
This process is supported by:
@@ -61,7 +59,7 @@ This process is supported by:
Developers make their modules available for other developers to use from
their own repository and publish with a version number.
* A **package search engine** and documentation browser (pkg.go.dev) at which
- you can find modules. See [Package discovery](developing#discovery).
+ you can find modules. See [Locating and importing useful packages](#locating_packages).
* A module **version numbering convention** to help you understand a module's
stability and backward compatibility guarantees. See [Module version
numbering](version-numbers).
@@ -69,8 +67,7 @@ This process is supported by:
getting a module's source, upgrading, and so on. See sections of this topic
for more.
-<a id="locating_packages" ></a>
-## Locating and importing useful packages
+## Locating and importing useful packages {#locating_packages}
You can search [pkg.go.dev](https://pkg.go.dev) to find packages with functions
you might find useful.
@@ -88,15 +85,14 @@ After your code imports the package, enable dependency tracking and get the
package's code to compile with. For more, see [Enabling dependency tracking in
your code](#enable_tracking) and [Adding a dependency](#adding_dependency).
-<a id="enable_tracking" ></a>
-## Enabling dependency tracking in your code
+## Enabling dependency tracking in your code {#enable_tracking}
To track and manage the dependencies you add, you begin by putting your code in
its own module. This creates a go.mod file at the root of your source tree.
Dependencies you add will be listed in that file.
To add your code to its own module, use the [`go mod init`
-command](https://golang.org/cmd/go/#hdr-Initialize_new_module_in_current_directory).
+command](/ref/mod#go-mod-init).
For example, from the command line, change to your code's root directory, then
run the command as in the following example:
@@ -104,6 +100,13 @@ run the command as in the following example:
$ go mod init example.com/mymodule
```
+The `go mod init` command's argument is your module's module path. If possible,
+the module path should be the repository location of your source code. If at
+first you don't know the module's eventual repository location, consider
+temporarily using a safe substitute, such as the name of a domain you own or
+`example.com`, along with a path following from the module's name or source
+directory.
+
As you use Go tools to manage dependencies, the tools update the go.mod file so
that it maintains a current list of your dependencies.
@@ -114,21 +117,20 @@ project.
Include the go.mod and go.sum files in your repository with your code.
-See the [go.mod reference](gomod-ref) for more.
+See the [go.mod reference](/doc/modules/gomod-ref) for more.
-<a id="adding_dependency" ></a>
-## Adding a dependency
+## Adding a dependency {#adding_dependency}
Once you're importing packages from a published module, you can add that module
to manage as a dependency by using the [`go get`
-command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them).
+command](/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them).
The command does the following:
* If needed, it adds `require` directives to your go.mod file for modules
needed to build packages named on the command line. A `require` directive
tracks the minimum version of a module that your module depends on. See the
- [go.mod reference](gomod-ref) for more.
+ [go.mod reference](/doc/modules/gomod-ref) for more.
* If needed, it downloads module source code so you can compile packages that
depend on them. It can download modules from a module proxy like
proxy.golang.org or directly from version control repositories. The source
@@ -159,8 +161,7 @@ was published -- for example, the developer changed the contents of the commit
-- Go tools will present a security error. This authentication check protects
you from modules that might have been tampered with.
-<a id="getting_version" ></a>
-## Getting a specific dependency version
+## Getting a specific dependency version {#getting_version}
You can get a specific version of a dependency module by specifying its version
in the `go get` command. The command updates the `require` directive in your
@@ -174,7 +175,7 @@ You might want to do this if:
* You want to upgrade or downgrade a module you're already requiring.
Here are examples for using the [`go get`
-command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them):
+command](/ref/mod#go-get):
* To get a specific numbered version, append the module path with an @ sign
followed by the version you want:
@@ -190,15 +191,14 @@ command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_i
```
The following go.mod file `require` directive example (see the [go.mod
-reference](gomod-ref) for more) illustrates how to require a specific version
+reference]/doc/modules/gomod-ref) for more) illustrates how to require a specific version
number:
```
require example.com/theirmodule v1.3.4
```
-<a id="discovering_updates" ></a>
-## Discovering available updates
+## Discovering available updates {#discovering_updates}
You can check to see if there are newer versions of dependencies you're already
using in your current module. Use the `go list` command to display a list of
@@ -206,8 +206,7 @@ your module's dependencies, along with the latest version available for that
module. Once you've discovered available upgrades, you can try them out with your
code to decide whether or not to upgrade to new versions.
-For more about the `go list` command, see the [`go` command
-reference](https://golang.org/cmd/go/#hdr-List_packages_or_modules).
+For more about the `go list` command, see [`go list -m`](/ref/mod#go-list-m).
Here are a couple of examples.
@@ -224,8 +223,7 @@ Here are a couple of examples.
$ go list -m -u example.com/theirmodule
```
-<a id="upgrading" ></a>
-## Upgrading or downgrading a dependency
+## Upgrading or downgrading a dependency {#upgrading}
You can upgrade or downgrade a dependency module by using Go tools to discover
available versions, then add a different version as a dependency.
@@ -234,10 +232,9 @@ available versions, then add a different version as a dependency.
[Discovering available updates](#discovering_updates).
1. To add a particular version as a dependency, use the `go get` command as
- described in [Getting a specific module version](#getting_version).
+ described in [Getting a specific dependency version](#getting_version).
-<a id="synchronizing" ></a>
-## Synchronizing your code's dependencies
+## Synchronizing your code's dependencies {#synchronizing}
You can ensure that you're managing dependencies for all of your code's imported
packages while also removing dependencies for packages you're no longer
@@ -260,8 +257,7 @@ about removed modules.
$ go mod tidy
```
-<a id="unpublished" ></a>
-## Developing and testing against unpublished module code
+## Developing and testing against unpublished module code {#unpublished}
You can specify that your code should use dependency modules that may not be
published. The code for these modules might be in their respective repositories,
@@ -276,8 +272,7 @@ You might want to do this when:
* You're building a new module and haven't yet published it, so it's
unavailable on a repository where the `go get` command can reach it.
-<a id="local_directory" ></a>
-### Requiring module code in a local directory
+### Requiring module code in a local directory {#local_directory}
You can specify that the code for a required module is on the same local drive
as the code that requires it. You might find this useful when you are:
@@ -290,8 +285,8 @@ as the code that requires it. You might find this useful when you are:
To tell Go commands to use the local copy of the module's code, use the
`replace` directive in your go.mod file to replace the module path given in a
-`require` directive. See the [go.mod reference](gomod-ref) for more about
-directives.
+`require` directive. See the [go.mod reference](/doc/modules/gomod-ref) for
+more about directives.
In the following go.mod file example, the current module requires the external
module `example.com/theirmodule`, with a nonexistent version number
@@ -310,11 +305,9 @@ require example.com/theirmodule v0.0.0-unpublished
replace example.com/theirmodule v0.0.0-unpublished => ../theirmodule
```
-When setting up a `require`/`replace` pair, use the [`go mod
-edit`](https://golang.org/cmd/go/#hdr-Edit_go_mod_from_tools_or_scripts) and
-[`go
-get`](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)
-commands to ensure that requirements described by the file remain consistent:
+When setting up a `require`/`replace` pair, use the
+[`go mod edit`](/ref/mod#go-mod-edit) and [`go get`](/ref/mod#go-get) commands
+to ensure that requirements described by the file remain consistent:
```
$ go mod edit -replace=example.com/theirmodule@v0.0.0-unpublished=../theirmodule
@@ -324,10 +317,9 @@ $ go get -d example.com/theirmodule@v0.0.0-unpublished
**Note:** When you use the replace directive, Go tools don't authenticate
external modules as described in [Adding a dependency](#adding_dependency).
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
-<a id="external_fork" ></a>
-### Requiring external module code from your own repository fork
+### Requiring external module code from your own repository fork {#external_fork}
When you have forked an external module's repository (such as to fix an issue in
the module's code or to add a feature), you can have Go tools use your fork for
@@ -362,10 +354,9 @@ replace example.com/theirmodule v1.2.3 => example.com/myfork/theirmodule v1.2.3-
When setting up a `require`/`replace` pair, use Go tool commands to ensure that
requirements described by the file remain consistent. Use the [`go
-list`](https://golang.org/cmd/go/#hdr-List_packages_or_modules) command to get
-the version in use by the current module. Then use the [`go mod
-edit`](https://golang.org/cmd/go/#hdr-Edit_go_mod_from_tools_or_scripts) command
-to replace the required module with the fork:
+list`](/ref/mod#go-list-m) command to get the version in use by the current
+module. Then use the [`go mod edit`](/ref/mod#go-mod-edit) command to replace
+the required module with the fork:
```
$ go list -m example.com/theirmodule
@@ -376,10 +367,9 @@ $ go mod edit -replace=example.com/theirmodule@v1.2.3=example.com/myfork/theirmo
**Note:** When you use the `replace` directive, Go tools don't authenticate
external modules as described in [Adding a dependency](#adding_dependency).
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
-<a id="repo_identifier" ></a>
-## Getting a specific commit using a repository identifier
+## Getting a specific commit using a repository identifier {#repo_identifier}
You can use the `go get` command to add unpublished code for a module from a
specific commit in its repository.
@@ -404,25 +394,22 @@ whose source is in a git repository.
$ go get example.com/theirmodule@bugfixes
```
-<a id="removing_dependency" ></a>
-## Removing a dependency
+## Removing a dependency {#removing_dependency}
When your code no longer uses any packages in a module, you can stop tracking
the module as a dependency.
To stop tracking all unused modules, run the [`go mod tidy`
-command](https://golang.org/cmd/go/#hdr-Add_missing_and_remove_unused_modules).
-This command also may also add missing dependencies needed to build packages in
-your module.
+command](/ref/mod#go-mod-tidy). This command also may also add missing
+dependencies needed to build packages in your module.
```
$ go mod tidy
```
To remove a specific dependency, use the [`go get`
-command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them),
-specifying the module's module path and appending `@none`, as in the following
-example:
+command](/ref/mod#go-get), specifying the module's module path and appending
+`@none`, as in the following example:
```
$ go get example.com/theirmodule@none
@@ -431,8 +418,7 @@ $ go get example.com/theirmodule@none
The `go get` command will also downgrade or remove other dependencies that
depend on the removed module.
-<a id="proxy_server" ></a>
-## Specifying a module proxy server
+## Specifying a module proxy server {#proxy_server}
When you use Go tools to work with modules, the tools by default download
modules from proxy.golang.org (a public Google-run module mirror) or directly
diff --git a/_content/doc/modules/managing-source.md b/_content/doc/modules/managing-source.md
index ac14da33..cb41dceb 100644
--- a/_content/doc/modules/managing-source.md
+++ b/_content/doc/modules/managing-source.md
@@ -14,7 +14,7 @@ workflow](release-workflow).
Some of the conventions described here are required in modules, while others are
best practices. This content assumes you're familiar with the basic module use
-practices described in [Managing dependencies](managing-dependencies).
+practices described in [Managing dependencies](/doc/modules/managing-dependencies).
Go supports the following repositories for publishing modules: Git, Subversion,
Mercurial, Bazaar, and Fossil.
@@ -22,8 +22,7 @@ Mercurial, Bazaar, and Fossil.
For an overview of module development, see [Developing and publishing
modules](developing).
-<a id="tools" ></a>
-## How Go tools find your published module
+## How Go tools find your published module {#tools}
In Go's decentralized system for publishing modules and retrieving their code,
you can publish your module while leaving the code in your repository. Go tools
@@ -31,7 +30,7 @@ rely on naming rules that have repository paths and repository tags indicating a
module's name and version number. When your repository follows these
requirements, your module code is downloadable from your repository by Go tools
such as the [`go get`
-command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them).
+command](/ref/mod#go-get).
When a developer uses the `go get` command to get source code for packages their
code imports, the command does the following:
@@ -46,8 +45,7 @@ code imports, the command does the following:
release version.
1. Retrieves module source and downloads it to the developer's local module cache.
-<a id="repository" ></a>
-## Organizing code in the repository
+## Organizing code in the repository {#repository}
You can keep maintenance simple and improve developers' experience with your
module by following the conventions described here. Getting your module code
@@ -116,8 +114,7 @@ $ git commit -m "mycode: initial commit"
$ git push
```
-<a id="repository-scope" ></a>
-## Choosing repository scope
+## Choosing repository scope {#repository-scope}
You publish code in a module when the code should be versioned independently
from code in other modules.
@@ -128,8 +125,7 @@ minor and patch versions, branch into new major versions, and so on. However, if
your needs require it, you can instead maintain a collection of modules in a
single repository.
-<a id="one-module-source" ></a>
-### Sourcing one module per repository
+### Sourcing one module per repository {#one-module-source}
You can maintain a repository that has a single module's source in it. In this
model, you place your go.mod file at the repository root, with package
@@ -143,8 +139,7 @@ directory path.
alt="Diagram illustrating a single module's source in its repository"
style="width: 425px;" />
-<a id="multiple-module-source" ></a>
-### Sourcing multiple modules in a single repository
+### Sourcing multiple modules in a single repository {#multiple-module-source}
You can publish multiple modules from a single repository. For example, you
might have code in a single repository that constitutes multiple modules, but
@@ -155,7 +150,7 @@ Each subdirectory that is a module root directory must have its own go.mod file.
Sourcing module code in subdirectories changes the form of the version tag you
must use when publishing a module. You must prefix the version number part of
the tag with the name of the subdirectory that is the module root. For more
-about version numbers, see [Module version numbering](version-numbers).
+about version numbers, see [Module version numbering](/doc/modules/version-numbers).
For example, for module `example.com/mymodules/module1` below, you would have
the following for version v1.2.3:
diff --git a/_content/doc/modules/publishing.md b/_content/doc/modules/publishing.md
index db5ec4ff..f98f07c3 100644
--- a/_content/doc/modules/publishing.md
+++ b/_content/doc/modules/publishing.md
@@ -19,9 +19,9 @@ a new version.
* For an overview of module development, see [Developing and publishing
modules](developing)
* For a high-level module development workflow -- which includes publishing --
- see [Module release and versioning workflow](release-workflow).
+ see [Module release and versioning workflow](/doc/modules/release-workflow).
-## Publishing steps
+## Publishing steps {#steps}
Use the following steps to publish a module.
@@ -75,9 +75,9 @@ Use the following steps to publish a module.
```
Developers interested in your module import a package from it and run the
-[`go get` command](/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)
+[`go get` command](/ref/mod#go-get)
just as they would with any other module. They can run the
-[`go get` command](/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)
+[`go get` command](/ref/mod#go-get)
for latest versions or they can specify a particular version, as in the
following example:
diff --git a/_content/doc/modules/release-workflow.md b/_content/doc/modules/release-workflow.md
index 78f0cb62..097a57af 100644
--- a/_content/doc/modules/release-workflow.md
+++ b/_content/doc/modules/release-workflow.md
@@ -13,11 +13,11 @@ modules](developing).
**See also**
* If you're merely wanting to use external packages in your code, be sure to
- see [Managing dependencies](managing-dependencies).
+ see [Managing dependencies](/doc/modules/managing-dependencies).
* With each new version, you signal the changes to your module with its
- version number. For more, see [Module version numbering](version-numbers).
+ version number. For more, see [Module version numbering](/doc/modules/version-numbers).
-## Common workflow steps
+## Common workflow steps {#common-steps}
The following sequence illustrates release and versioning workflow steps for an
example new module. For more about each step, see the sections in this topic.
@@ -26,10 +26,10 @@ example new module. For more about each step, see the sections in this topic.
to use and for you to maintain.
If you're brand new to developing modules, check out [Tutorial: Create a Go
- module](https://golang.org/doc/tutorial/create-module).
+ module](/doc/tutorial/create-module).
In Go's decentralized module publishing system, how you organize your code
- matters. For more, see [Managing module source](managing-source).
+ matters. For more, see [Managing module source](/doc/modules/managing-source).
1. Set up to **write local client code** that calls functions in the
unpublished module.
@@ -82,8 +82,7 @@ example new module. For more about each step, see the sections in this topic.
disruptive upgrade for your module's users. It should be a last resort. For
more, see [Publishing breaking API changes](#breaking).
-<a id="unpublished" ></a>
-## Coding against an unpublished module
+## Coding against an unpublished module {#unpublished}
When you begin developing a module or a new version of a module, you won't yet
have published it. Before you publish a module, you won't be able to use Go
@@ -96,15 +95,14 @@ the `replace` directive in the client module's go.mod file. For more
information, see in [Requiring module code in a local
directory](managing-dependencies#local_directory).
-<a id="pre-release" ></a>
-## Publishing pre-release versions
+## Publishing pre-release versions {#pre-release}
You can publish pre-release versions to make a module available for others to
try it out and give you feedback. A pre-release version includes no guarantee of
stability.
Pre-release version numbers are appended with a pre-release identifier. For more
-on version numbers, see [Module version numbering](version-numbers).
+on version numbers, see [Module version numbering](/doc/modules/version-numbers).
Here are two examples:
@@ -128,8 +126,7 @@ You publish a pre-release by tagging the module code in your repository,
specifying the pre-release identifier in the tag. For more, see [Publishing a
module](publishing).
-<a id="first-unstable" ></a>
-## Publishing the first (unstable) version
+## Publishing the first (unstable) version {#first-unstable}
As when you publish a pre-release version, you can publish release versions that
don't guarantee stability or backward compatibility, but give your users an
@@ -156,8 +153,7 @@ You publish an unstable release by tagging the module code in your repository,
specifying a v0 version number in the tag. For more, see [Publishing a
module](publishing).
-<a id="first-stable" ></a>
-## Publishing the first stable version
+## Publishing the first stable version {#first-stable}
Your first stable release will have a v1.x.x version number. The first stable
release follows pre-release and v0 releases through which you got feedback,
@@ -182,7 +178,7 @@ does not signal stability or backward compatibility guarantees. As a result,
when you increment from v0 to v1, you needn't be mindful of breaking backward
compatibility because the v0 release was not considered stable.
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
Here's an example of a stable version number:
@@ -194,8 +190,7 @@ You publish a first stable release by tagging the module code in your
repository, specifying a v1 version number in the tag. For more, see [Publishing
a module](publishing).
-<a id="bug-fixes" ></a>
-## Publishing bug fixes
+## Publishing bug fixes {#bug-fixes}
You can publish a release in which the changes are limited to bug fixes. This is
known as a patch release.
@@ -210,7 +205,7 @@ upgrading to the patch of your module could wind up accidentally pulling in a
more invasive change to a transitive dependency that they use.
A patch release increments the patch part of the module's version number. For
-more see, [Module version numbering](version-numbers).
+more see, [Module version numbering](/doc/modules/version-numbers).
In the following example, v1.0.1 is a patch release.
@@ -222,8 +217,7 @@ You publish a patch release by tagging the module code in your repository,
incrementing the patch version number in the tag. For more, see [Publishing a
module](publishing).
-<a id="non-breaking" ></a>
-## Publishing non-breaking API changes
+## Publishing non-breaking API changes {#non-breaking}
You can make non-breaking changes to your module's public API and publish those
changes in a _minor_ version release.
@@ -235,7 +229,7 @@ this kind of release guarantees backward compatibility and stability for
existing code that calls the module's functions.
A minor release increments the minor part of the module's version number. For
-more, see [Module version numbering](version-numbers).
+more, see [Module version numbering](/doc/modules/version-numbers).
In the following example, v1.1.0 is a minor release.
@@ -247,8 +241,7 @@ You publish a minor release by tagging the module code in your repository,
incrementing the minor version number in the tag. For more, see [Publishing a
module](publishing).
-<a id="breaking" ></a>
-## Publishing breaking API changes
+## Publishing breaking API changes {#breaking}
You can publish a version that breaks backward compatibility by publishing a
_major_ version release.
@@ -259,7 +252,7 @@ using the module's previous versions.
Given the disruptive effect a major version upgrade can have on code relying on
the module, you should avoid a major version update if you can. For more about
-major version updates, see [Developing a major version update](major-version).
+major version updates, see [Developing a major version update](/doc/modules/major-version).
For strategies to avoid making breaking changes, see the blog post [Keeping your
modules compatible](https://blog.golang.org/module-compatibility).
@@ -272,7 +265,7 @@ steps.
One way to do this is to create a new branch in your repository that is
specifically for the new major version and its subsequent minor and patch
- versions. For more, see [Managing module source](managing-source).
+ versions. For more, see [Managing module source](/doc/modules/managing-source).
1. In the module's go.mod file, revise the module path to append the new major
version number, as in the following example:
@@ -298,4 +291,4 @@ steps.
incrementing the major version number in the tag -- such as from v1.5.2 to
v2.0.0.
- For more, see [Publishing a module](publishing).
+ For more, see [Publishing a module](/doc/modules/publishing).
diff --git a/_content/doc/modules/version-numbers.md b/_content/doc/modules/version-numbers.md
index ca1acddc..70ec30bf 100644
--- a/_content/doc/modules/version-numbers.md
+++ b/_content/doc/modules/version-numbers.md
@@ -10,18 +10,23 @@ changes since the preceding release.
When you're developing code that uses external modules, you can use the version
numbers to understand an external module's stability when you're considering an
-upgrade. When you're developing your own modules, your version numbers will
+upgrade. For more on managing versions, see
+[Managing dependencies](/doc/modules/managing-dependencies).
+
+When you're developing your own modules, your version numbers will
signal your modules' stability and backward compatibility to other developers.
+For more about versioning in the module development workflow, see
+[Module release and versioning workflow](/doc/modules/release-workflow).
This topic describes what module version numbers mean.
**See also**
* When you're using external packages in your code, you can manage those
- dependencies with Go tools. For more, see [Managing dependencies](managing-dependencies).
+ dependencies with Go tools. For more, see [Managing dependencies](/doc/modules/managing-dependencies).
* If you're developing modules for others to use, you apply a version number
when you publish the module, tagging the module in its repository. For more,
- see [Publishing a module](publishing).
+ see [Publishing a module](/doc/modules/publishing).
A released module is published with a version number in the semantic versioning
model, as in the following illustration:
@@ -81,8 +86,7 @@ module's stability and backward compatibility.
</tbody>
</table>
-<a id="in-development" ></a>
-## In development
+## In development {#in-development}
Signals that the module is still in development and **unstable**. This release
carries no backward compatibility or stability guarantees.
@@ -91,14 +95,17 @@ The version number can take one of the following forms:
**Pseudo-version number**
-> v0.0.0-20170915032832-14c0d48ead0c
+```
+v0.0.0-20170915032832-14c0d48ead0c
+```
**v0 number**
-> v0.x.x
+```
+v0.x.x
+```
-<a id="pseudo" ></a>
-### Pseudo-version number
+### Pseudo-version number {#pseudo}
When a module has not been tagged in its repository, Go tools will generate a
pseudo-version number for use in the go.mod file of code that calls functions in
@@ -114,11 +121,11 @@ semantic version tag yet.
A pseudo-version number has three parts separated by dashes, as shown in the
following form:
-#### Syntax
+#### Syntax {#pseudo-syntax}
_baseVersionPrefix_-_timestamp_-_revisionIdentifier_
-#### Parts
+#### Parts {#pseudo-parts}
* **baseVersionPrefix** (vX.0.0 or vX.Y.Z-0) is a value derived either from a
semantic version tag that precedes the revision or from vX.0.0 if there is no
@@ -130,8 +137,7 @@ _baseVersionPrefix_-_timestamp_-_revisionIdentifier_
* **revisionIdentifier** (abcdefabcdef) is a 12-character prefix of the commit
hash, or in Subversion, a zero-padded revision number.
-<a id="v0" ></a>
-### v0 number
+### v0 number {#v0}
A module published with a v0 number will have a formal semantic version number
with a major, minor, and patch part, as well as an optional pre-release
@@ -143,13 +149,12 @@ break backward compatibility for code using the v0 versions. For this reason, a
developer with code consuming functions in a v0 module is responsible for
adapting to incompatible changes until v1 is released.
-<a id="pre-release" ></a>
-## Pre-release version
+## Pre-release version {#pre-release}
Signals that this is a pre-release milestone, such as an alpha or beta. This
release carries no stability guarantees.
-#### Example
+#### Example {#pre-release-example}
```
vx.x.x-beta.2
@@ -158,13 +163,12 @@ vx.x.x-beta.2
A module's developer can use a pre-release identifier with any major.minor.patch
combination by appending a hyphen and the pre-release identifier.
-<a id="minor" ></a>
-## Minor version
+## Minor version {#minor}
Signals backward-compatible changes to the module’s public API. This release
guarantees backward compatibility and stability.
-#### Example
+#### Example {#minor-example}
```
vx.4.x
@@ -178,13 +182,12 @@ In other words, this version might include enhancements through new functions
that another developer might want to use. However, a developer using previous
minor versions needn’t change their code otherwise.
-<a id="patch" ></a>
-## Patch version
+## Patch version {#patch}
Signals changes that don't affect the module's public API or its dependencies.
This release guarantees backward compatibility and stability.
-#### Example
+#### Example {#patch-example}
```
vx.x.1
@@ -194,16 +197,17 @@ An update that increments this number is only for minor changes such as bug
fixes. Developers of consuming code can upgrade to this version safely without
needing to change their code.
-<a id="major" ></a>
-## Major version
+## Major version {#major}
Signals backward-incompatible changes in a module’s public API. This release
carries no guarantee that it will be backward compatible with preceding major
versions.
-#### Example
+#### Example {#major-example}
+```
v1.x.x
+```
A v1 or above version number signals that the module is stable for use (with
exceptions for its pre-release versions).
@@ -230,6 +234,6 @@ module example.com/mymodule/v2 v2.0.0
A major version update makes this a new module with a separate history from the
module's previous version. If you're developing modules to publish for others,
see "Publishing breaking API changes" in [Module release and versioning
-workflow](release-workflow).
+workflow](/doc/modules/release-workflow).
-For more on the module directive, see [go.mod reference](gomod-ref).
+For more on the module directive, see [go.mod reference](/doc/modules/gomod-ref).
generated by cgit v1.3 (git 2.53.0) at 2026-04-15 08:51:53 +0000