Go.mod file

The go.mod file contains metadata about your project,
and describes it's requirements (ex. go version, packages, etc)

Documentation

go.mod ref	https://go.dev/doc/modules/gomod-ref
go modules ref	https://go.dev/ref/mod
go checksum database docs	https://go.dev/ref/mod#checksum-database
go module index	https://index.golang.org/index
go remote import paths	https://pkg.go.dev/cmd/go#hdr-Remote_import_paths

Tutorials

DO: public go modules	https://www.digitalocean.com/community/tutorials/how-to-distribute-go-modules
DO: private, authenticated go modules	https://www.digitalocean.com/community/tutorials/how-to-use-a-private-go-module-in-your-own-project

Example

Minimal/throwaway

module foo
go 1.18

More complete

/* Unique identifier for project.
 * Distinguishes tools of the same name within `pkgs.go.dev`
 * Also directly or indirectly identifies the source-code's repo
 * (see module-path notes below)
 */
module example.com/x/yourproject

/* minimum supported go version */
go 1.18

/* project dependencies */
require (
    example.com/project-1 v1.1.1
    example.com/project-2 v2.2.2
)

/* replace content of module with a local directory */
replace example.com/project-2 => example.com/patched/project-2 v2.2.2-fixed

Creation

# run inside go project's directory, with the desired project 'module-path' (see below)
go mod init example.com/x/myproject

Components

Go Version

pacman -S go  # update your os's go version
go mod edit -go=1.19
go mod tidy

module path

See golang module path

Requirements

Adding/Removing

go get "rsc.io/quote"  # add requirement to 'go.mod'
go mod tidy            # auto-discover missing requirements, add to 'go.mod'

Vendor/Patch

// go.mod

require (
    example.com/project-2
    // ...
)

replace example.com/project-2 => example.com/patched/project-2 v2.2.2-fixed

Updating

go list -m -u all                 # list avail updates for all deps
go list -m -u example.com/module  # list avail updates for target dep

go get example.com/module@latest  # update to latest
go get example.com/module v1.1.1  # update/downgrade to target version