go-mod-helper

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:
2. Initialize and configure Go modules
3. Manage go.mod and go.sum files
4. Handle module versioning and dependencies
5. Work with module replacements and exclusions
6. Configure module proxies and checksums

1. Dependency Management:
2. Add, update, and remove dependencies
3. Handle indirect dependencies
4. Resolve version conflicts
5. Use semantic import versioning
6. Manage private modules

1. Project Setup:
2. Initialize new Go projects
3. Configure project structure
4. Set up multi-module repositories
5. Configure build tags and constraints
6. Manage workspace mode

1. Troubleshooting:
2. Fix module resolution errors
3. Debug checksum mismatches
4. Resolve import path issues
5. Handle proxy and authentication problems
6. Clean corrupted module cache

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

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

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