Go.mod

External

• https://go.dev/doc/modules/gomod-ref

Internal

• Go Modules

Overview

go.mod declares the module path, which is the import path prefix for all packages within the module. It also tracks the modules that provide dependencies to this module. go.mod is located in the root of the module, which is also the root of the source tree for the module. The most common way to create a go.mod is with go mod init <module-path>. The file can also be created manually with a text editor, and then edited with the same text editor, but Go documentation recommends to make changes to the file via go commands.

go.mod stays with the code, including in the source repository.

A typical go.mod file usually assumes that your project is hosted in GitHub, but this is not a requirement. The module path can be anything.

As go tools are used to manage dependencies, the tools update the go.mod file so that it maintains the current list of dependencies.

go.sum

https://golang.org/ref/mod#go-sum-files

When a dependency is added, go creates a go.sum file that contains checksums, in form of cryptographic hashes, of dependency modules. This is used to verify the integrity of the downloaded module files. This file should not edited manually.

go.mod Example

module example.com/hello

go 1.21.0

require rsc.io/quote v1.5.2

require (
	golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c // indirect
	rsc.io/sampler v1.3.0 // indirect
)

Initialize go.mod

In the module root directory, initialize the go.mod file.

go mod init <module-path>

go mod init example.com/generic

go.mod Editing Commands

Do not modify go.mod manually, always use go mod editing commands to ensure that requirements described by the file remain consistent.

edit

-require

go mod edit -require=...

Examples below.

-droprequire

go mod edit -droprequire=github.com/apache/yunikorn-scheduler-interface

-replace

go mod edit -replace=...

Examples below.

Go Version

module example.com/hello

go 1.22.4

Adding a Dependency to a Module

Dependencies are added with the go get command. The command updates go.mod by adding the require directive for dependencies. The require directive tracks the minimum version of a module that the module depends on. The command also updates the module source code and places in the module cache and authenticate each module it downloads. This ensures that it's unchanged from when the module was published.

go get [-u] github.com/apache/yunikorn-core@v1.4.0

For a post v1 module, postfix /vx to the module path:

go get github.com/labstack/echo/v4@v4.11.4

Note that you are adding the dependency in advance without actually referring it from the module source code, go get will add an "// indirect" comment for that specific dependency in go.mod.

If the exact latest version is unknown, use the following syntax to let go get determine it:

go get google.golang.org/protobuf/reflect/protoreflect

TODO: https://pkg.go.dev/cmd/go#hdr-Add_dependencies_to_current_module_and_install_them

Variations of go get

go get

Removing a Dependency from a Module

See go mod edit -droprequire above.

Update Module's Dependencies

Use go list to check if there are newer versions of dependencies. If there are available useful upgrades, use go get command again to add the particular newer version.

Synchronize Dependencies

TODO: https://go.dev/doc/modules/managing-dependencies#synchronizing

Using Unpublished Module Code

https://go.dev/doc/modules/managing-dependencies#unpublished

Normally, go get is used with published, versioned releases of a project's dependencies. However, there are situations that require experimentally modifying a dependency to use it with the current project. The Go documentation refers to this situation as "developing and testing against unpublished module code". There are two ways to access a modified dependency: in a local directory on the development machine and in a forked repository.

Using Local Module Code

A very common situation when experimenting with the source of a dependency is to clone the dependency repository locally, and modify the code. It is convenient, and possible, to express the go.mod dependency to point to the local directory. The go.mod syntax to express this situation is:

...
require example.com/somemodule v0.0.0-unpublished
replace example.com/somemodule v0.0.0-unpublished => ../somemodule

The configuration expresses the fact the dependency version we intend do use is not published anywhere (v0.0.0-unpublished), and the tool chain must reach out to the local directory ../somemodule to get it. The replace directive specifies the location. An absolute path can be used, but that might introduce problems if go.mod is shared within a team, and the path is not consistent across developers' machines.

Avoid modifying go.mod manually. Use the following command to generate the configuration:

go mod edit -require=example.com/somemodule@v0.0.0-unpublished
# Careful when using copy-and-paste, the first command uses "-require", the second "-replace"
go mod edit -replace=example.com/somemodule@v0.0.0-unpublished=../somemodule

Example:

go mod edit -require=github.com/apache/yunikorn-core@v0.0.0-unpublished
go mod edit -replace=github.com/apache/yunikorn-core@v0.0.0-unpublished=/Users/ovidiu/projects/yunikorn/github-ovidiuf-forks/yunikorn-core

Use go get to pull the source code in the module cache:

go get example.com/somemodule@v0.0.0-unpublished

Using an Arbitrary Fork Module Code

https://go.dev/doc/modules/managing-dependencies#external_fork

The same pattern as in Using Local Module Code applies, but this time the replace statement refers to an actual repository.

The go.mod should look like:

...
require github.com/apache/yunikorn-core v0.0.0-unpublished
replace github.com/apache/yunikorn-core v0.0.0-unpublished => example.com/myfork/yunikorn-core v1.2.3-fixed

The edit commands are:

go mod edit -require=github.com/apache/yunikorn-core@v0.0.0-unpublished
go mod edit -replace=github.com/apache/yunikorn-core@v0.0.0-unpublished=example.com/myfork/yunikorn-core@v1.2.3-fixed

Instead of a specific version, a commit hash or a branch name can be used instead, as show below in the Getting a Specific Commit section.

Getting a Specific Commit

https://go.dev/doc/modules/managing-dependencies#repo_identifier

To get a specific commit, use the commit hash or a branch name:

go get example.com/theirmodule@4cf76c2
go get example.com/theirmodule@of/some-branch

This command will modify go.mod as follows:

require example.com/theirmodule v0.0.0-20240109203350-28b9035e2013

If the dependency on a dot version is already declared in the go.mod:

require official.com/somemodule v1.0.0

and we want to (temporarily) replace it with the dependency defined by a specific commit or branch name in a different repository, use go mod edit -replace as follows:

go mod edit -replace=official.com/somemodule@v1.0.0=experimental.com/somemodule@4cf76c2
go mod edit -replace=official.com/somemodule@v1.0.0=experimental.com/somemodule@of/somebranch

This command will modify go.mod as follows:

replace official.com/somemodule v1.0.0 => experimental.com/somemodule v0.0.0-20240109203350-28b9035e2013

The version label eventually stored in the go.mod file has a timestamp "...-20240117154324-..." and a commit hash "...-4323f643fa79", that contains the first 12 most significant digits of the GitHub commit.