go-modules

Master Go module system and dependency management.

Overview

Complete guide for Go modules including versioning, private modules, vendoring, and dependency updates.

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | action | string | yes | - | Action: "init", "tidy", "vendor", "update" | | private | bool | no | false | Handle private modules |

Core Topics

Module Initialization

# Initialize new module
go mod init github.com/myorg/myapp

# Download dependencies
go mod download

# Cleanup unused dependencies
go mod tidy

# Verify dependencies
go mod verify

go.mod Structure

module github.com/myorg/myapp

go 1.22

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/jmoiron/sqlx v1.3.5
    go.uber.org/zap v1.26.0
)

require (
    // indirect dependencies auto-managed
    github.com/lib/pq v1.10.9 // indirect
)

Private Modules

# Configure private module pattern
go env -w GOPRIVATE=github.com/myorg/*

# Use SSH for private repos
git config --global url."git@github.com:".insteadOf "https://github.com/"

# Or use access token
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"

Vendoring

# Create vendor directory
go mod vendor

# Build with vendor
go build -mod=vendor ./...

# Verify vendor is in sync
go mod verify

Dependency Updates

# List available updates
go list -m -u all

# Update specific dependency
go get github.com/gin-gonic/gin@latest

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

# Update to specific version
go get github.com/gin-gonic/gin@v1.9.1

# Downgrade
go get github.com/gin-gonic/gin@v1.8.0

Replace Directives

// go.mod

// Local development
replace github.com/myorg/shared => ../shared

// Fork with fixes
replace github.com/original/pkg => github.com/myorg/pkg-fork v1.2.3

// Exclude vulnerable version
exclude github.com/vulnerable/pkg v1.0.0

Workspace (Go 1.18+)

// go.work
go 1.22

use (
    ./api
    ./shared
    ./worker
)

# Initialize workspace
go work init ./api ./shared

# Add module to workspace
go work use ./worker

# Sync workspace
go work sync

Troubleshooting

Failure Modes

| Symptom | Cause | Fix | |---------|-------|-----| | Module not found | Private repo | Set GOPRIVATE | | Checksum mismatch | Proxy cache | GOPROXY=direct | | Version conflict | Diamond dependency | Use go mod graph |

Debug Commands

go mod graph                    # Show dependency graph
go mod why github.com/pkg/errors # Why is this needed?
go list -m -versions github.com/gin-gonic/gin # Available versions

Usage

Skill("go-modules")