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

Example

/* 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 github.com/myproject

Components

module path

Module paths are used both to locate, and uniquely identify packages.
Downloading packages is normally performed by a lookup in go index,
but the actual src is hosted using a server/service of your choosing.

URL suffix

Suffix indicating repository type

# Repos supporting multiple protocols will try each in order.
# ex: https://, git://, git+ssh://
#
#
# Bazaar      .bzr
# Fossil      .fossil
# Git         .git
# Mercurial   .hg
# Subversion  .svn

import "example.com/path/to/repo.git"
import "example.com/path/to/repo.git/sub/directory"

HTTP meta tag

HTTP meta tag

<!--
  Meta tags let you abstract the path of your src.
  You may use a import-prefix that has nothing to do with your URL.

  IMPORT-PREFIX: prefix of unique-identifier of package (not necessarily url) ex. "foo.com/x"
  VCS:           bzr, fossil, git, hg, svn
  REPO-ROOT:     URL to repo-root (no VCS extension!)
-->
<!--                            IMPORT-PREFIX  VCS   REPO-ROOT                 -->
<meta name="go-import" content="example.org    git   https://code.org/r/p/exproj">

Hosted services

Hosted Services

# github.com
import "github.com/user/your_project"
import "github.com/user/your_project/sub/directory"

# launchpad.net
import "launchpad.net/project"
import "launchpad.net/project/series"
import "launchpad.net/project/series/sub/directory"

# ...

Requirements

Add/remove requirements

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

Vendor/Patch requirements

// go.mod

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

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