How the exclude directive works in the go.mod file?

Question

The new Go version 1.11 introduced the modules concept which is awesome.

In the documentation it says there are four directives that can be used in a go.mod file: module, require, exclude, replace.

It also explains that:

exclude and replace directives only operate on the current (“main”) module. exclude and replace directives in modules other than the main module are ignored when building the main module. The replace and exclude statements therefore allow the main module complete control over its own build, without also being subject to complete control by dependencies.

But I still don't understand how the exclude directive works.

Can someone explain to me how the exclude directive works and if possible give an example of when to use it?

Answer 1

Here's a semi-hypothetical hypothetical example:

go.mod

module github.com/example/project

require (
    github.com/SermoDigital/jose v0.0.0-20180104203859-803625baeddc
    github.com/google/uuid v1.1.0
)

exclude github.com/SermoDigital/jose v0.9.1

replace github.com/google/uuid v1.1.0 => git.coolaj86.com/coolaj86/uuid.go v1.1.1

exclude

In the case of the github.com/SermoDigital/jose package, it has a proper git tag for v0.9.1, but the current version is v1.1, which is NOT a proper git tag (missing the "patch" version).

By excluding the properly-versioned (but not working) code it causes go mod to fetch from master instead (which is not properly versioned, but has the working code).

replace

Likewise (and truly hypothetical), if I have a patch to github.com/google/uuid, I can create a fork and use replace to get my own version while I wait for the upstream version to accept my patch (or not).