Go Mod Cheat Sheet

This article contains a collection of commands and troubleshooting manual for using Go Mod.

Previously, Go didn’t have built-in dependency package management. That’s why package management like Dep or Glide is very popular and use widely. However, starting at Go 1.11, Go provides a dependency package management that makes dependency version information explicit.

Dep

Previously, I also used Dep intensively for my Go development. But since last year, I have been using Go Mod as the new standard with Go v1.14. While working Go Mod, I somehow ended up wasting time opening a bunch of Stackoverflow or other people article just to do something. This article is a collection of commands and troubleshooting to use Go Mod with ease.

Turn On Go Mod in Go Environment

$ go env -w GO111MODULE=on

Initialize Project

$ go mod init

Adding a New Dependency

# for master branch
$ go get -v github.com/gin-gonic/gin
# for specific branch
$ go get -v github.com/gin-gonic/gin@development
# for specific commit hash
$ go get -v github.com/gin-gonic/gin@abcd1234
# for specific release
$ go get -v github.com/gin-gonic/gin@v1.0.0

Upgrading a Dependency

# all dependencies
$ go get -u ./...
# view dependencies with available update
$ go list -u -m -mod=mod all
# for master/main branch
$ go get -u -v github.com/gin-gonic/gin
# for specific branch
$ go get -u -v github.com/gin-gonic/gin@development
# for specific commit hash
$ go get -u -v github.com/gin-gonic/gin@abcd1234
# for specific release
$ go get -u -v github.com/gin-gonic/gin@v1.0.0

Pulling All Dependency

$ go mod vendor -v

Removing Unused/Hanging Dependency

Keep your dependency neat and tidy, by removing all unrequired dependencies from Go Mod by running:

$ go mod tidy

Removing a Used Dependency

Delete all the imports that refer to that dependency beforehand.
Then, execute:

$ go mod tidy

List All Vendor

If you need to list all the vendor, run:

$ go list -m -json -mod=mod all

Publishing Dependency

Unlike Dep where you can create a release tag with your own format, it is important that the release tag is in the semantic version format. A semantic version has the form vMAJOR.MINOR.PATCH.

Just like normal git operation, create a new release tag and push it:

$ git tag v1.0.0
$ git push --tags

Pulling a Private Repository

If you have a dependency that is a private repository like company repository. You need to update your GOPRIVATE environment variable. Don’t forget to replace the repository path with your own private repository path.

$ go env -w GOPRIVATE=github.com/your-company-name

Troubleshooting

Trace and correct faults in an operation.

Pulling Dependency Get Output: 410 Gone

Sample output error:

verifying github.com/your-company-name/sdk@v1.0.0/go.mod: github.com/your-company-name/sdk@v1.0.0/go.mod: reading https://sum.golang.org/lookup/github.com/your-company-name/sdk@v1.0.0: 410 Gone

This error means that the repository is either removed or a private one, and cannot be accessed by Go Mod.

Fix by adding your private repository to Go Environment.

$ go env -w GOPRIVATE=github.com/your-company-name

Pulling Dependency Get Output: No matching versions for query

Sample output error:

$ go get -v -u github.com/rizalgowandy/something/sdk@v1.0
Output:
go get github.com/rizalgowandy/something/sdk@v1.0: no matching versions for query "v1.0"

This error means that the release tag is non-existent or in an incorrect format. For the case above, it’s in an incorrect format. The tag should be in the semantic version format. So instead of a tag named v1.0, it should be v1.0.0.

Fix by creating a new release tag.

$ git tag v1.0.0
$ git push --tags 

Then try adding/updating the dependency again.

Sample success output:

$ go get -v -u github.com/rizalgowandy/something/sdk@v1.0.0
Output:
go: downloading github.com/tokopedia/something/sdk v1.0.0

Pulling Dependency Get Output: Ambiguous import

Sample output error:

$ go mod vendor -v
Output:
build github.com/rizalgowandy/something/sdk: 
cannot load github.com/hashicorp/consul/api: ambiguous import: found github.com/hashicorp/consul/api in multiple modules:                                                                                            
        github.com/hashicorp/consul v1.4.3 (/home/arwego/go/pkg/mod/github.com/hashicorp/consul@v1.4.3/api)
        github.com/hashicorp/consul/api v1.1.0 (/home/arwego/go/pkg/mod/github.com/hashicorp/consul/api@v1.1.0)

This error means that your packages or vendor have a conflicting dependency. Fix by pinning the dependency to a higher version tag, by adding this line to your go.mod file.

// place it at the bottom of your go.mod file
replace github.com/hashicorp/consul => github.com/hashicorp/consul v1.5.1