go-mod-helper

What this skill does

# 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
```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
```go
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
```bash
# Add dependency (automatically)
# Just import and run:
go get github.com/gin-gonic/gin

# Add specific version
go get github.com/gin-gonic/[email protected]

# 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/[email protected]
```

## 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
// 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
// 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
// go.mod
module github.com/username/project/v2

go 1.21

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

```go
// 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."[email protected]:".insteadOf "https://github.com/"

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

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

# Configure git to use SSH
git config --global url."[email protected]:".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
// go.mod
module github.com/myorg/project

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

require github.com/myorg/library v1.2.3
```

### Fork Replacement
```go
// 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 ./