go-mod-helper

name	go-mod-helper
description	Go module system, dependency management, and project configuration assistance.

Go Module Management Skill

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

Instructions

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

1. 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

2. Dependency Management:

   • Add, update, and remove dependencies
   • Handle indirect dependencies
   • Resolve version conflicts
   • Use semantic import versioning
   • Manage private modules

3. Project Setup:

   • Initialize new Go projects
   • Configure project structure
   • Set up multi-module repositories
   • Configure build tags and constraints
   • Manage workspace mode

4. Troubleshooting:

   • Fix module resolution errors
   • Debug checksum mismatches
   • Resolve import path issues
   • Handle proxy and authentication problems
   • Clean corrupted module cache

5. Best Practices: Provide guidance on Go module patterns, versioning, and dependency management

Go Module Basics

Module Initialization

# 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

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

@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

# 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

# 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

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
}

# 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

# 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

# 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."[e-mail]:".insteadOf "https://github.com/"

# Configure for specific organization
git config --global url."[e-mail]: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

# 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

# Generate SSH key if needed
ssh-keygen -t ed25519 -C "[e-mail]"

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

# Configure git to use SSH
git config --global url."[e-mail]:".insteadOf "https://github.com/"

GitLab CI/CD

# .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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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."[e-mail]:".insteadOf "https://github.com/"

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

Issue: Slow Downloads

# 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

# 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

# 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

# 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

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

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

# 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

.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

# 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

# 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

• All tests passing
• Documentation updated
• CHANGELOG.md updated
• go.mod and go.sum committed
• Version tagged
• LICENSE file present
• README.md with usage examples
• CI/CD pipeline green
• Breaking changes documented

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

# 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