Go Modules

Go modules are the official dependency management solution for Go projects. They provide version control, reproducible builds, and simplified dependency management.

Understanding Go Modules

Go modules solve several key problems in dependency management:

Version locking
Reproducible builds
Semantic versioning
Dependency graph management
Backward compatibility

Creating a New Module

# Create a new directory
mkdir myproject
cd myproject

# Initialize a new module
go mod init github.com/username/myproject

The go.mod file is created:

module github.com/username/myproject

go 1.22

Managing Dependencies

Adding Dependencies

# Add a specific dependency
go get github.com/pkg/[email protected]

# Add latest version
go get github.com/gorilla/mux

# Add specific version
go get github.com/gorilla/[email protected]

Updating Dependencies

# Update all dependencies
go get -u ./...

# Update specific dependency
go get -u github.com/gorilla/mux

# Update patch versions only
go get -u=patch ./...

Removing Dependencies

# Remove unused dependencies
go mod tidy

# Remove specific dependency
go get github.com/username/package@none

Understanding go.mod

module github.com/username/myproject

go 1.22

require (
    github.com/pkg/errors v0.9.1
    github.com/gorilla/mux v1.8.1
)

// Exclude problematic versions
exclude github.com/pkg/errors v0.9.0

// Replace module with local copy
replace github.com/pkg/errors => ../errors

// Retract problematic versions
retract (
    v1.0.0 // Contains critical bug
    [v1.1.0, v1.1.2] // Security vulnerability
)

Version Selection

Go uses Semantic Import Versioning:

require (
    // Major version 0 or 1
    github.com/pkg/errors v0.9.1
    
    // Major version 2+
    github.com/author/package/v2 v2.1.0
)

Working with go.sum

The go.sum file ensures reproducible builds:

github.com/pkg/errors v0.9.1 h1:FEg8JWN3JQ1P2G6x
github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0

Verifying Dependencies

# Verify dependencies match go.sum
go mod verify

# Download dependencies
go mod download

# Vendor dependencies
go mod vendor

Module Queries

Listing Dependencies

# List direct dependencies
go list -m all

# List modules requiring a package
go list -m -u all

# Show module dependencies
go mod graph

Checking for Updates

# Check for available updates
go list -m -u all

# Show version details
go list -m -versions github.com/pkg/errors

Module Versioning

Version Tags

# Create a new version
git tag v1.0.0
git push origin v1.0.0

# Create a major version
git tag v2.0.0
git push origin v2.0.0

Major Version Changes

For v2 and beyond, update the module path:

// go.mod
module github.com/username/myproject/v2

go 1.22

// Import in other projects
import "github.com/username/myproject/v2"

Working with Private Modules

Authentication

# Set up Git authentication
export GOPRIVATE=github.com/mycompany/*

# Configure Git credentials
git config --global url."[email protected]:".insteadOf "https://github.com/"

Proxy Configuration

# Set GOPROXY
export GOPROXY=direct

# Set GOPRIVATE
export GOPRIVATE=*.internal.mycompany.com

Module Workspaces

Go 1.18+ supports multiple module workspaces:

myworkspace/
├── go.work
├── moduleA/
│   └── go.mod
└── moduleB/
    └── go.mod

# Initialize workspace
go work init ./moduleA ./moduleB

# Add module to workspace
go work use ./moduleC

# List workspace modules
go work edit -json

Best Practices

1. Version Tagging

# Use semantic versioning
v1.2.3       # Regular release
v1.2.3-beta  # Pre-release
v2.0.0       # Major version change

2. Module Organization

myproject/
├── go.mod
├── internal/     # Private packages
├── pkg/         # Public packages
└── cmd/         # Commands

3. Dependency Management

# Regular maintenance
go mod tidy
go mod verify
go mod download

# Before commits
go test ./...

Common Issues and Solutions

1. Version Conflicts

# Check dependency requirements
go mod why github.com/pkg/errors

# View module graph
go mod graph | grep github.com/pkg/errors

2. Incompatible Versions

// Use replace directive
replace github.com/pkg/errors v1.0.0 => github.com/pkg/errors v0.9.1

3. Authentication Issues

# Set up Git credentials
export GIT_TERMINAL_PROMPT=1
git config --global credential.helper store

Module Commands Reference

go mod init     # Initialize new module
go mod tidy     # Clean up dependencies
go mod vendor   # Copy dependencies
go mod verify   # Verify dependencies
go mod download # Download dependencies
go mod why      # Explain dependency
go mod graph    # Print dependency graph
go mod edit     # Edit go.mod

Publishing Modules

1. Preparing for Release

# Ensure tests pass
go test ./...

# Clean up dependencies
go mod tidy

# Verify everything works
go build ./...

2. Tagging Release

# Create version tag
git tag v1.0.0

# Push tag
git push origin v1.0.0

3. Documentation

// Add package documentation
// Package mypackage provides...
package mypackage

// Document exported items
// MyFunc does...
func MyFunc() {}

Next Steps

Explore Go tools for development
Learn about project structure
Study dependency management
Understand versioning