Go Module Management Skill

Go module system, dependency management, and project configuration assistance.

Instructions

You are a Go module and dependency expert. When invoked:

•
Module Management:
- •Initialize and configure Go modules
- •Manage go.mod and go.sum files
- •Handle module versioning and dependencies
- •Work with module replacements and exclusions
- •Configure module proxies and checksums
•
Dependency Management:
- •Add, update, and remove dependencies
- •Handle indirect dependencies
- •Resolve version conflicts
- •Use semantic import versioning
- •Manage private modules
•
Project Setup:
- •Initialize new Go projects
- •Configure project structure
- •Set up multi-module repositories
- •Configure build tags and constraints
- •Manage workspace mode
•
Troubleshooting:
- •Fix module resolution errors
- •Debug checksum mismatches
- •Resolve import path issues
- •Handle proxy and authentication problems
- •Clean corrupted module cache
•
Best Practices: Provide guidance on Go module patterns, versioning, and dependency management

Go Module Basics

Module Initialization

bash

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

# Initialize with custom path
go mod init example.com/myproject

# Create project structure
mkdir -p cmd/server internal/api pkg/utils
touch cmd/server/main.go

# Sample main.go
cat > cmd/server/main.go << 'EOF'
package main

import (
    "fmt"
    "github.com/username/project/internal/api"
)

func main() {
    fmt.Println("Hello, Go modules!")
    api.Start()
}
EOF

go.mod File Structure

module github.com/username/project

go 1.21

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/lib/pq v1.10.9
    golang.org/x/sync v0.5.0
)

require (
    // Indirect dependencies
    github.com/bytedance/sonic v1.10.2 // indirect
    github.com/chenzhuoyu/base64x v0.0.0-20230717121745-296ad89f973d // indirect
    github.com/gabriel-vasile/mimetype v1.4.3 // indirect
)

replace (
    // Replace with local version
    github.com/old/package => ../local/package

    // Replace with fork
    github.com/original/repo => github.com/fork/repo v1.2.3
)

exclude (
    // Exclude problematic versions
    github.com/bad/package v1.2.3
)

retract (
    // Retract published versions
    v1.5.0 // Contains bug
    [v1.6.0, v1.6.5] // Range of bad versions
)

go.sum File

code

github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YrpYKXt5YId3A/Tnip5kqbEAP+KLuI3SUcPTeU=

Usage Examples

code

@go-mod-helper
@go-mod-helper --init-project
@go-mod-helper --update-deps
@go-mod-helper --tidy
@go-mod-helper --troubleshoot
@go-mod-helper --private-modules

Common Commands

Dependency Management

bash

# Add dependency (automatically)
# Just import and run:
go get github.com/gin-gonic/gin

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

# Add latest version
go get github.com/gin-gonic/gin@latest

# Add specific commit
go get github.com/user/repo@commit-hash

# Add specific branch
go get github.com/user/repo@branch-name

# Update dependency
go get -u github.com/gin-gonic/gin

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

# Update to patch version only
go get -u=patch github.com/gin-gonic/gin

# Remove unused dependencies
go mod tidy

# Download dependencies
go mod download

# Verify dependencies
go mod verify

# View dependency graph
go mod graph

# Explain why dependency is needed
go mod why github.com/lib/pq

# List all modules
go list -m all

# List available versions
go list -m -versions github.com/gin-gonic/gin

Module Cache

bash

# View cache location
go env GOMODCACHE

# Clean module cache
go clean -modcache

# Download all dependencies to cache
go mod download

# Download specific module
go mod download github.com/gin-gonic/gin@v1.9.1

Project Setup Patterns

Standard Project Layout

code

myproject/
├── go.mod
├── go.sum
├── README.md
├── Makefile
├── .gitignore
├── cmd/
│   ├── server/
│   │   └── main.go
│   └── cli/
│       └── main.go
├── internal/
│   ├── api/
│   │   ├── handler.go
│   │   └── routes.go
│   ├── database/
│   │   └── db.go
│   └── config/
│       └── config.go
├── pkg/
│   ├── utils/
│   │   └── helper.go
│   └── models/
│       └── user.go
├── api/
│   └── openapi.yaml
├── docs/
│   └── design.md
├── scripts/
│   └── setup.sh
└── tests/
    ├── integration/
    └── e2e/

Multiple Binaries

// go.mod
module github.com/username/project

go 1.21

// cmd/server/main.go
package main

func main() {
    // Server implementation
}

// cmd/cli/main.go
package main

func main() {
    // CLI implementation
}

bash

# Build specific binary
go build -o bin/server ./cmd/server
go build -o bin/cli ./cmd/cli

# Build all
go build ./cmd/...

# Install to GOPATH/bin
go install ./cmd/server
go install ./cmd/cli

Library Project

// go.mod
module github.com/username/mylib

go 1.21

// mylib.go (root package)
package mylib

// Public API

// internal/impl.go
package internal

// Private implementation

Semantic Import Versioning

Major Versions (v2+)

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

go 1.21

require (
    github.com/other/lib/v3 v3.1.0
)

// Import in code
import (
    "github.com/username/project/v2/pkg/utils"
    oldversion "github.com/username/project"  // v1
)

Version Strategy

bash

# v0.x.x - Initial development
v0.1.0  # Initial release
v0.2.0  # Add features
v0.3.0  # More changes

# v1.x.x - Stable API
v1.0.0  # First stable release
v1.1.0  # Add features (backward compatible)
v1.1.1  # Bug fixes

# v2.x.x - Breaking changes
v2.0.0  # Breaking API changes
# Must update module path to /v2

# Tagging releases
git tag v1.0.0
git push origin v1.0.0

Private Modules

Configure Private Repositories

bash

# Set GOPRIVATE environment variable
go env -w GOPRIVATE="github.com/yourorg/*,gitlab.com/yourcompany/*"

# Or set in shell
export GOPRIVATE="github.com/yourorg/*"

# Configure Git to use SSH instead of HTTPS
git config --global url."git@github.com:".insteadOf "https://github.com/"

# Configure for specific organization
git config --global url."git@github.com:yourorg/".insteadOf "https://github.com/yourorg/"

# Disable proxy for private modules
go env -w GONOPROXY="github.com/yourorg/*"

# Disable checksum verification for private
go env -w GONOSUMDB="github.com/yourorg/*"

Authentication Methods

GitHub Personal Access Token

bash

# Create ~/.netrc for HTTPS auth
cat > ~/.netrc << EOF
machine github.com
login YOUR_GITHUB_USERNAME
password YOUR_GITHUB_TOKEN
EOF

chmod 600 ~/.netrc

SSH Keys

bash

# Generate SSH key if needed
ssh-keygen -t ed25519 -C "your_email@example.com"

# Add to ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Configure git to use SSH
git config --global url."git@github.com:".insteadOf "https://github.com/"

GitLab CI/CD

bash

# .gitlab-ci.yml
before_script:
  - git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/".insteadOf "https://gitlab.com/"
  - go env -w GOPRIVATE="gitlab.com/yourgroup/*"

Module Replacement

Local Development

// go.mod
module github.com/myorg/project

replace github.com/myorg/library => ../library

require github.com/myorg/library v1.2.3

Fork Replacement

// Replace with fork
replace github.com/original/repo => github.com/yourfork/repo v1.2.3

// Replace with specific version
replace github.com/pkg/errors => github.com/pkg/errors v0.9.1

Temporary Fixes

bash

# Edit vendor copy
go mod vendor
# Edit vendor/github.com/package/file.go

# Tell Go to use vendor
go build -mod=vendor

Workspace Mode (Go 1.18+)

Multi-Module Development

bash

# Create workspace
go work init

# Add modules to workspace
go work use ./project1
go work use ./project2
go work use ./shared-lib

# go.work file created
cat go.work

// go.work
go 1.21

use (
    ./project1
    ./project2
    ./shared-lib
)

replace github.com/myorg/shared => ./shared-lib

bash

# Work commands
go work sync     # Sync workspace modules
go work edit     # Edit go.work
go work use -r . # Add all modules recursively

# Workspace ignored by default in .gitignore
echo "go.work" >> .gitignore

Vendoring

Enable Vendoring

bash

# Create vendor directory
go mod vendor

# Build with vendor
go build -mod=vendor

# Set vendor mode as default
go env -w GOFLAGS=-mod=vendor

# Update vendor
go mod vendor

# Verify vendor
go mod verify

Vendor Configuration

bash

# Build always uses vendor
go build -mod=vendor

# Build ignores vendor
go build -mod=mod

# Build with readonly mode (CI)
go build -mod=readonly

Common Issues & Solutions

Issue: Checksum Mismatch

bash

# Error: verifying module: checksum mismatch

# Solution 1: Update go.sum
go clean -modcache
go mod download
go mod tidy

# Solution 2: Verify authenticity
go mod verify

# Solution 3: Force re-download
go get -u github.com/package/name
go mod tidy

# Solution 4: Check GOSUMDB
go env GOSUMDB  # Should be "sum.golang.org"

Issue: Module Not Found

bash

# Error: cannot find module providing package

# Check if module exists
go list -m github.com/package/name

# Update dependencies
go get github.com/package/name
go mod download

# Clear cache and retry
go clean -modcache
go mod download

# Check import path
go list -m -json github.com/package/name

Issue: Version Conflicts

bash

# Check dependency graph
go mod graph | grep package-name

# See why package is required
go mod why github.com/package/name

# Force specific version
go get github.com/package/name@v1.2.3

# Exclude problematic version
# Add to go.mod:
exclude github.com/bad/package v1.2.3

Issue: Private Repository Access

bash

# Configure GOPRIVATE
go env -w GOPRIVATE="github.com/yourorg/*"

# Configure git credentials
git config --global credential.helper store

# Use SSH instead of HTTPS
git config --global url."git@github.com:".insteadOf "https://github.com/"

# Verify settings
go env | grep GOPRIVATE
git config --get-regexp url

Issue: Slow Downloads

bash

# Use module proxy
go env -w GOPROXY="https://proxy.golang.org,direct"

# Use alternative proxy (China)
go env -w GOPROXY="https://goproxy.cn,direct"

# Disable proxy for specific domains
go env -w GOPRIVATE="github.com/myorg/*"

# Direct download (no proxy)
go env -w GOPROXY="direct"

# Check current settings
go env | grep PROXY

Issue: Corrupted Module Cache

bash

# Clean entire cache
go clean -modcache

# Re-download dependencies
go mod download

# Verify integrity
go mod verify

# Check cache location
go env GOMODCACHE

Advanced Patterns

Build Constraints

// +build linux darwin

package utils

// Only compiled on Linux and macOS

// build tag: go1.18
// +build go1.18

// Requires Go 1.18+

// Modern syntax (Go 1.17+)
//go:build linux && amd64

package platform

// Compiled only for Linux AMD64

Conditional Dependencies

// go.mod
require (
    github.com/common/lib v1.0.0
)

// For testing only
require (
    github.com/stretchr/testify v1.8.4
)

Module Documentation

// Package mypackage provides utilities for...
//
// Basic usage:
//
//     import "github.com/user/mypackage"
//
//     result := mypackage.DoSomething()
//
package mypackage

bash

# View documentation
go doc github.com/user/mypackage
go doc github.com/user/mypackage.FunctionName

# Run doc server
godoc -http=:6060

Testing and CI/CD

Testing with Modules

bash

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Generate coverage profile
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Test with race detector
go test -race ./...

# Test specific package
go test github.com/user/project/pkg/utils

CI/CD Configuration

GitHub Actions

yaml

name: Go

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Set up Go
      uses: actions/setup-go@v4
      with:
        go-version: '1.21'
        cache: true

    - name: Download dependencies
      run: go mod download

    - name: Verify dependencies
      run: go mod verify

    - name: Run go vet
      run: go vet ./...

    - name: Run tests
      run: go test -v -race -coverprofile=coverage.out ./...

    - name: Upload coverage
      uses: codecov/codecov-action@v3
      with:
        files: ./coverage.out

    - name: Build
      run: go build -v ./...

GitLab CI

yaml

image: golang:1.21

stages:
  - test
  - build

before_script:
  - go mod download

test:
  stage: test
  script:
    - go mod verify
    - go vet ./...
    - go test -v -race -coverprofile=coverage.out ./...
  coverage: '/total:.*?(\d+\.\d+)%/'

build:
  stage: build
  script:
    - go build -v ./...
  artifacts:
    paths:
      - bin/

Build and Release

Build Configuration

bash

# Basic build
go build -o bin/myapp ./cmd/myapp

# Build with version info
VERSION=$(git describe --tags --always)
BUILD_TIME=$(date -u '+%Y-%m-%d_%H:%M:%S')
go build -ldflags "-X main.Version=${VERSION} -X main.BuildTime=${BUILD_TIME}" -o bin/myapp

# Build for different platforms
GOOS=linux GOARCH=amd64 go build -o bin/myapp-linux-amd64
GOOS=darwin GOARCH=amd64 go build -o bin/myapp-darwin-amd64
GOOS=windows GOARCH=amd64 go build -o bin/myapp-windows-amd64.exe

# Build with optimizations
go build -ldflags="-s -w" -o bin/myapp  # Strip debug info

# Static binary (no CGO)
CGO_ENABLED=0 go build -o bin/myapp

Makefile Example

makefile

.PHONY: build test clean install

VERSION ?= $(shell git describe --tags --always --dirty)
BUILD_TIME ?= $(shell date -u '+%Y-%m-%d_%H:%M:%S')
LDFLAGS := -ldflags "-X main.Version=$(VERSION) -X main.BuildTime=$(BUILD_TIME)"

build:
	go build $(LDFLAGS) -o bin/myapp ./cmd/myapp

test:
	go test -v -race -coverprofile=coverage.out ./...

coverage:
	go tool cover -html=coverage.out

lint:
	golangci-lint run

tidy:
	go mod tidy
	go mod verify

clean:
	rm -rf bin/
	go clean -cache -modcache

install: build
	cp bin/myapp $(GOPATH)/bin/

release:
	GOOS=linux GOARCH=amd64 go build $(LDFLAGS) -o bin/myapp-linux-amd64
	GOOS=darwin GOARCH=amd64 go build $(LDFLAGS) -o bin/myapp-darwin-amd64
	GOOS=windows GOARCH=amd64 go build $(LDFLAGS) -o bin/myapp-windows-amd64.exe

Module Publishing

Prepare for Release

bash

# Ensure tests pass
go test ./...

# Tidy dependencies
go mod tidy

# Verify module
go mod verify

# Run linter
golangci-lint run

# Update version in documentation
# Update CHANGELOG.md

Semantic Versioning

bash

# Tag release
git tag v1.0.0
git push origin v1.0.0

# For v2+ major versions
# Update go.mod module path
module github.com/user/project/v2

# Tag with /v2
git tag v2.0.0
git push origin v2.0.0

# Pre-release versions
git tag v1.0.0-beta.1
git tag v1.0.0-rc.1

Publishing Checklist

Best Practices Summary

Module Management

•Use semantic versioning (v1.2.3)
•Tag releases properly
•Keep go.mod and go.sum in version control
•Run go mod tidy regularly
•Use go mod verify before releases
•Document breaking changes

Dependency Management

•Minimize dependencies
•Use require for direct dependencies
•Let Go manage indirect dependencies
•Update dependencies regularly
•Test after updates
•Use go.sum for verification

Project Structure

•Follow standard project layout
•Use internal/ for private packages
•Use pkg/ for public libraries
•Keep cmd/ for binaries
•Organize by feature, not by type

Versioning

•Start with v0.x.x for development
•Use v1.0.0 for first stable release
•v2+ requires /v2 in module path
•Use pre-release tags (beta, rc)
•Never delete published versions

Security

•Run go mod verify regularly
•Use checksums (go.sum)
•Audit dependencies
•Keep dependencies updated
•Use GOSUMDB for verification

Performance

•Use module cache
•Enable module proxy
•Vendor for Docker builds
•Use go mod download in CI

Quick Reference Commands

bash

# Module initialization
go mod init <module-path>

# Dependency management
go get <package>              # Add/update dependency
go get -u <package>           # Update to latest
go mod tidy                   # Remove unused dependencies
go mod download               # Download dependencies
go mod verify                 # Verify dependencies

# Information
go list -m all                # List all modules
go mod graph                  # Dependency graph
go mod why <package>          # Why is package needed
go list -m -versions <package> # List available versions

# Maintenance
go clean -modcache            # Clean module cache
go mod vendor                 # Create vendor directory
go get -u ./...               # Update all dependencies

# Building
go build ./...                # Build all packages
go test ./...                 # Test all packages
go install ./...              # Install all binaries

Notes

•Always commit go.mod and go.sum files
•Use semantic versioning for releases
•Tag releases with git tags
•Use module proxy for faster downloads
•Configure GOPRIVATE for private modules
•Use workspaces for multi-module development
•Vendor dependencies for Docker builds
•Keep module path stable (avoid renames)
•Document breaking changes clearly
•Use go mod tidy before committing