goenv

README

Go Version Management: goenv

goenv aims to be as simple as possible and follow the already established successful version management model of pyenv and rbenv.

🎉 Now 100% Go-based with dynamic version fetching! No more static version files or manual updates needed.

This project was originally cloned from pyenv, modified for Go, and has now been completely rewritten in Go for better performance and maintainability.

goenv does...

• Let you change the global Go version on a per-user basis.
• Provide support for per-project Go versions.
• Smart version discovery - automatically detects versions from .go-version or go.mod
• Go.mod toolchain support - respects Go 1.21+ toolchain directives with smart precedence
• Allow you to override the Go version with an environment variable.
• Search commands from multiple versions of Go at a time.
• Provide tab completion for bash, zsh, fish, and PowerShell.
• Automatically rehash after go install - tools available immediately (can be disabled with --no-rehash flag)
• Enhanced diagnostics (goenv doctor) with interactive fix mode and 18 issue types
• Quick status check (goenv status) for installation health overview
• Version usage analysis (goenv versions --used) - scan projects to see which versions are in use
• Version lifecycle tracking (goenv info) with EOL detection and upgrade recommendations
• Version comparison (goenv compare) for side-by-side analysis
• First-time setup wizard (goenv setup) for automatic shell and IDE configuration
• Interactive beginner guide (goenv get-started) for new users
• Command discovery (goenv explore) to find commands by intent or category
• Self-update capability (goenv update) for both git and binary installations
• Tool management (goenv tools) - comprehensive tool management across Go versions:
  • Install/uninstall tools across all versions with --all flag
  • Check tool consistency with goenv tools status
  • Find outdated tools with goenv tools outdated
  • Auto-install common tools with goenv tools default
  • Sync tools between versions with goenv tools sync
• Version aliases (goenv alias) - create convenient shorthand names for versions
• VS Code integration (goenv vscode) - sync Go settings with workspace-relative paths and security validation
• Shell prompt integration (goenv prompt) - display active Go version in your shell prompt with smart caching

goenv compared to others:

• https://github.com/crsmithdev/goenv depends on Go,
• https://github.com/moovweb/gvm is a different approach to the problem that's modeled after nvm. goenv is more simplified.

New in 2.x: This version is a complete rewrite in Go, offering:

• Dynamic version fetching - Always up-to-date without manual updates
• Offline support - Works without internet via intelligent caching
• Better performance - Native Go binary vs bash scripts
• Cross-platform - Single binary for all supported platforms
• Auto-rehash - Installed tools work immediately without manual intervention (configurable for CI/CD)

---

Hints

AWS CodeBuild

The following snippet can be inserted in your buildspec.yml (or buildspec definition) for AWS CodeBuild. It's recommended to do this during the pre_build phase.

Side Note: if you use the below steps, please unset your golang version in the buildspec and run the installer manually.

- (cd /root/.goenv && git pull)

---

🚀 Quick Start

Option 1: Binary Installation (Recommended - No Go Required!)

The fastest way to get started. Download a pre-built binary - no Go installation needed!

# Automatic install (Linux/macOS)
curl -sfL https://raw.githubusercontent.com/go-nv/goenv/master/install.sh | bash

# Or download manually from releases:
# https://github.com/go-nv/goenv/releases/latest

# Automatic install (Windows)
iwr -useb https://raw.githubusercontent.com/go-nv/goenv/master/install.ps1 | iex

Then add to your shell config:

# Bash (~/.bash_profile or ~/.bashrc)
export GOENV_ROOT="$HOME/.goenv"
export PATH="$GOENV_ROOT/bin:$PATH"
eval "$(goenv init -)"

Option 2: Package Manager (macOS)

Homebrew:

brew install goenv

Then add to your shell config (see Option 1 above for shell configuration).

Option 3: Git Clone (Requires Go to Build)

For contributors or those who want the latest development version:

# 1. Clone goenv
git clone https://github.com/go-nv/goenv.git ~/.goenv

# 2. Build (requires Go)
cd ~/.goenv && make build

# 3. Add to your shell config (~/.bashrc, ~/.zshrc, etc.)
export GOENV_ROOT="$HOME/.goenv"
export PATH="$GOENV_ROOT/bin:$PATH"
eval "$(goenv init -)"

# 4. Restart your shell
exec $SHELL

Next Steps (All Options)

# Enable tab completion (optional but recommended)
goenv completion --install

# Restart your shell
exec $SHELL

# Install and set a Go version (one command!)
goenv use 1.22.0 --global

# Or install first, then set
goenv install 1.22.0

# 💡 Shorthand: goenv 1.22.0 is an alias for goenv use 1.22.0
goenv 1.22.0  # Same as: goenv use 1.22.0

# Verify
go version

# Install tools (automatically isolated per version)
go install golang.org/x/tools/cmd/goimports@latest
goenv rehash  # Makes tools available as shims

💡 Tools installed with go install are isolated per Go version:

• Tools install to $HOME/go/{version}/bin/ (e.g., ~/go/1.22.0/bin/goimports)
• Running goenv rehash creates shims that automatically use the right version
• Switch Go versions → tools switch too (no conflicts between versions)
• See GOPATH Integration for complete details

See Installation Guide for platform-specific setup.

---

🎨 Shell Prompt Integration

Display your active Go version directly in your shell prompt for instant visual feedback:

# Quick setup with the interactive wizard
goenv prompt config

# Manual setup - add to your shell config:
# Bash/Zsh (~/.bashrc or ~/.zshrc)
export PS1='$(goenv prompt --prefix "(" --suffix ") ") '"$PS1"

# Fish (~/.config/fish/config.fish)
function fish_prompt
  set -l goenv_version (goenv prompt 2>/dev/null)
  test -n "$goenv_version"; and echo -n "($goenv_version) "
  # ... rest of your prompt
end

# PowerShell ($PROFILE)
function prompt {
  $goenvVersion = goenv prompt 2>$null
  if ($goenvVersion) {
    Write-Host "($goenvVersion) " -NoNewline -ForegroundColor Cyan
  }
  "PS $($PWD.Path)> "
}

Features:

• Smart caching - minimal performance impact (< 50ms)
• Customizable format - control prefix, suffix, and display format
• Project-aware - show only in Go projects with --go-project-only
• Hide system Go - use --no-system to hide when using system Go

Advanced options:

# Short version (1.23 instead of 1.23.2)
export PS1='$(goenv prompt --short) '"$PS1"

# Custom format with emoji
export PS1='$(goenv prompt --icon "🐹" --format "go:%s") '"$PS1"

# Show only in Go projects
export PS1='$(goenv prompt --go-project-only) '"$PS1"

# Environment variable configuration
export GOENV_PROMPT_PREFIX="["
export GOENV_PROMPT_SUFFIX="]"
export GOENV_PROMPT_FORMAT="go:%s"

See goenv prompt --help for all options.

---

🎯 Interactive Mode

goenv adapts to your workflow with three levels of interactivity:

Non-Interactive Mode (CI/Automation)

Perfect for scripts and CI/CD pipelines - auto-confirms all operations:

# Auto-confirm with --yes flag
goenv install 1.23.0 --yes
goenv uninstall 1.22.0 -y

# Or set globally
export GOENV_ASSUME_YES=1
goenv install 1.23.0

# Quiet mode (suppress output)
goenv install 1.23.0 --quiet

# Auto-detected in CI environments (GitHub Actions, GitLab CI, etc.)

Minimal Interactive Mode (Default)

Balances automation with safety - prompts only for critical operations:

# Default behavior
goenv uninstall 1.22.0
# Prompt: "Really uninstall Go 1.22.0? [y/N]"

goenv install 1.23.0
# Shows progress, offers retry on failure

Guided Interactive Mode (Learning)

Helpful prompts and suggestions for new users:

# Enable guided mode
goenv install --interactive
# Offers version selection, explains choices

goenv doctor --interactive  
# Offers to fix issues automatically

goenv use --interactive
# Guides through version selection

Global Flags

• --interactive - Enable guided mode with helpful prompts
• --yes / -y - Auto-confirm all prompts (non-interactive)
• --quiet / -q - Suppress progress output (only show errors)

Environment Variables

• GOENV_ASSUME_YES=1 - Auto-confirm globally (like --yes)
• CI=true - Automatically enables non-interactive mode

Examples by Use Case

Daily development:

goenv install 1.23.0    # Default: shows progress, confirms if needed
goenv use 1.23.0        # Installs if needed (with prompt)

Automation scripts:

#!/bin/bash
goenv install 1.23.0 --yes
goenv global 1.23.0 --yes

CI/CD pipelines:

# goenv auto-detects CI - no flags needed
- run: goenv install 1.23.0
- run: goenv global 1.23.0

Learning mode:

goenv install --interactive  # Guided experience
goenv explain               # Understand version resolution

📖 Full Guide: See Interactive Mode Guide for comprehensive documentation.

---

🪝 Hooks System

goenv includes a powerful hooks system that lets you automate actions at key points in the goenv lifecycle. Hooks are declarative, safe, and cross-platform.

Quick Example

# Generate configuration template
goenv hooks init

# Edit ~/.goenv/hooks.yaml
# Set enabled: true and acknowledged_risks: true

# Example: Log installations and send Slack notifications
hooks:
  post_install:
    - action: log_to_file
      params:
        path: ~/.goenv/install.log
        message: "Installed Go {version} at {timestamp}"

    - action: http_webhook
      params:
        url: https://hooks.slack.com/services/YOUR/WEBHOOK
        body: '{"text": "✅ Go {version} installed"}'

Available Actions

• log_to_file - Write audit logs and track installations
• http_webhook - Send notifications to Slack, Discord, or custom APIs
• notify_desktop - Display native desktop notifications
• check_disk_space - Verify sufficient space before operations
• set_env - Set environment variables dynamically

Hook Points

Execute actions at 8 different lifecycle points:

• pre_install / post_install - Before/after installing Go versions
• pre_uninstall / post_uninstall - Before/after removing Go versions
• pre_exec / post_exec - Before/after executing Go commands
• pre_rehash / post_rehash - Before/after regenerating shims

Commands

goenv hooks init       # Generate configuration template
goenv hooks list       # Show available actions and hook points
goenv hooks validate   # Check configuration for errors
goenv hooks test       # Dry-run hooks without executing

📖 Complete Hooks Documentation - Examples, use cases, and detailed guides

---

📖 Documentation

📚 Complete Documentation - Comprehensive guides and references

Quick Links

Getting Started

• Installation Guide - Get started with goenv ⭐ NEW: Windows FAQ
• Interactive Mode Guide - CI/CD, automation, and guided workflows ⭐ NEW
• Quick Reference - One-page cheat sheet ⭐ NEW
• FAQ - Frequently asked questions ⭐ NEW
• What's New in Docs - Recent documentation improvements ⭐ NEW
• How It Works - Understanding goenv's internals
• VS Code Integration - Setting up VS Code with goenv

Reference

• Command Reference - Complete CLI documentation ⭐ NEW: --force guidance, vscode setup
• Environment Variables - Configuration options
• Platform Support Matrix - OS and architecture compatibility ⭐ NEW
• Modern Commands Guide - use/current/list vs legacy commands ⭐ NEW
• JSON Output Guide - Automation and CI/CD integration ⭐ NEW

Advanced Topics

• CI/CD Integration - Best practices for pipelines ⭐ NEW: Offline mode, Windows examples
• Hooks System Quick Start - 5-minute hooks setup ⭐ NEW
• Hooks System (Full) - Complete hooks documentation ⭐ NEW: Security best practices
• Compliance Use Cases - SOC 2, ISO 27001, SBOM ⭐ NEW
• Smart Caching - Intelligent version caching ⭐ NEW: Network reliability
• What NOT to Sync - Sharing goenv across machines
• Cache Troubleshooting - Cache issues and migration ⭐ NEW
• System Go Coexistence - Using with system-installed Go ⭐ NEW

For Contributors

• Contributing - How to contribute (code & documentation)
• Documentation Review Checklist - Doc quality checklist ⭐ NEW
• Testing Roadmap - Test coverage gaps and priorities 🆕

Other

• Code of Conduct - Community guidelines
• Changelog - Version history