gopher

Gopher User Guide

This comprehensive guide covers everything you need to know about using Gopher, the Go version manager.

Table of Contents

Installation

Prerequisites

Installation Methods

macOS (Homebrew):

brew install molmedoz/tap/gopher

Windows (Chocolatey):

choco install gopher

Linux (Snap):

snap install gopher

Method 2: From GitHub Releases

Windows:

# Download and install
$version = "1.0.0"
New-Item -ItemType Directory -Path "$env:USERPROFILE\bin" -Force
$url = "https://github.com/molmedoz/gopher/releases/download/v$version/gopher-windows-amd64.exe"
Invoke-WebRequest -Uri $url -OutFile "$env:USERPROFILE\bin\gopher.exe"

# Add to PATH
$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", "$env:USERPROFILE\bin;$userPath", "User")

# Restart PowerShell

macOS/Linux:

# Download for your platform
curl -LO https://github.com/molmedoz/gopher/releases/download/v1.0.0/gopher-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)
chmod +x gopher-*
sudo mv gopher-* /usr/local/bin/gopher

Method 3: Using Go Install

go install github.com/molmedoz/gopher/cmd/gopher@latest

Method 4: From Source

git clone https://github.com/molmedoz/gopher.git
cd gopher
make build
sudo make install

Verify Installation

gopher version

Expected output:

gopher v1.0.0

First-Time Setup

Windows:

gopher init

Then follow the on-screen instructions. See Windows Setup Guide for details.

macOS/Linux:

gopher init

What gopher init does:

Directories created automatically:

Quick Start

Workflow Overview

Here’s a visual overview of common Gopher workflows:

┌─────────────────────────────────────────────────────────────────────┐
│                     GOPHER WORKFLOW DIAGRAM                         │
└─────────────────────────────────────────────────────────────────────┘

First Time Setup:
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Install  │ -> │  Check   │ -> │ Install  │ -> │   Use    │
│  Gopher  │    │  System  │    │ Go Ver.  │    │ Go Ver.  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
   (once)      gopher system   gopher install  gopher use

Regular Usage:
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│   List   │ -> │ Install  │ -> │  Switch  │ -> │  Verify  │
│ Versions │    │  Version │    │  Version │    │  Active  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
gopher list   gopher install  gopher use     go version

Cleanup:
┌──────────┐    ┌──────────┐    ┌──────────┐
│   List   │ -> │   Find   │ -> │ Uninstall│
│ Installed│    │  Unused  │    │  Version │
└──────────┘    └──────────┘    └──────────┘
gopher list                    gopher uninstall

Version Switching Flow

Current State                Action                  New State
┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   System    │         │   gopher    │         │   go1.21.0  │
│  go1.20.0   │  --->   │ use 1.21.0  │  --->   │   [active]  │
│  [active]   │         └─────────────┘         └─────────────┘
└─────────────┘                                        │
      ↑                                                │
      │         ┌─────────────┐                        │
      └─────────│   gopher    │  <─────────────────────┘
                │ use system  │
                └─────────────┘

1. Check Your Current Setup

# See what Go versions you have
gopher list

# Check your current Go version
gopher current

# View system Go information
gopher system

2. Install a New Go Version

# Install Go 1.21.0
gopher install 1.21.0

# Verify installation
gopher list

3. Switch Between Versions

# Switch to a specific version
gopher use 1.21.0

# Switch back to system Go
gopher use system

# Verify the switch
go version

4. Clean Up Old Versions

# Remove a specific version you no longer need
gopher uninstall 1.20.7

# Clean download cache to free disk space
gopher clean

# Completely remove all Gopher data (requires confirmation)
gopher purge

Command Reference

gopher list

Lists all installed Go versions, including system versions. Interactive pagination is enabled by default.

gopher list

Interactive Mode (default):

Output:

Installed Go versions (page 1 of 1, showing 2 of 2 total):

  go1.25.1 (darwin/arm64) - active (installed: 2025-08-27 08:49:40) [system]
  go1.21.0 (darwin/arm64) - inactive (installed: 2025-08-27 09:15:22)

Page 1 of 1
Commands:
  n, next, →     - Next page
  p, prev, ←     - Previous page
  <number>       - Go to specific page
  q, quit, exit  - Quit
  h, help        - Show this help

Enter command:

Options:

Note: Flags must be placed before the command name.

Examples:

# Interactive mode (default)
gopher list

# Disable interactive mode
gopher --no-interactive list

# JSON output
gopher --json list

# Change page size
gopher --page-size 5 list

# Go to specific page (non-interactive)
gopher --page 2 --no-interactive list

JSON Output:

gopher list --json

[
  {
    "version": "go1.25.1",
    "os": "darwin",
    "arch": "arm64",
    "installed_at": "2025-08-27T08:49:40-07:00",
    "is_active": true,
    "is_system": true,
    "path": "/opt/homebrew/opt/go/libexec/bin/go"
  }
]

gopher list-remote

Lists available Go versions for installation. Interactive pagination is enabled by default.

gopher list-remote

Interactive Mode (default):

Output:

Available Go versions (page 1 of 33, showing 10 of 328 total):

  go1.25.1 (stable) - 
  go1.25.0 (stable) - 
  go1.24.7 (stable) - 
  ...

Page 1 of 33
Commands:
  n, next, →     - Next page
  p, prev, ←     - Previous page
  <number>       - Go to specific page
  q, quit, exit  - Quit
  h, help        - Show this help

Enter command:

Options:

Note: Flags must be placed before the command name.

Examples:

# Interactive listing (default)
gopher list-remote

# Disable interactive mode
gopher --no-interactive list-remote

# Pagination
gopher --page-size 5 list-remote
gopher --page 2 --page-size 10 --no-interactive list-remote

# Filtering
gopher --filter "1.21" list-remote
gopher --filter "rc" list-remote
gopher --stable list-remote

# JSON output
gopher --json list-remote

gopher install <version>

Downloads and installs a specific Go version.

gopher install 1.21.0

Examples:

# Install latest stable
gopher install 1.21.0

# Install with go prefix
gopher install go1.21.0

# Install specific patch version
gopher install 1.21.1

What happens during installation:

  1. Validates version format
  2. Checks if already installed
  3. Downloads from official Go mirrors
  4. Verifies SHA256 checksums
  5. Extracts to gopher directory
  6. Creates version metadata
  7. Cleans up downloaded files

gopher uninstall <version>

Removes a Go version installed by gopher.

gopher uninstall 1.21.0

Note: Cannot uninstall system Go versions.

gopher use <version>

Switches to a specific Go version.

gopher use 1.21.0
gopher use system

Special versions:

What happens during switching:

  1. Validates version exists
  2. Creates symlink to version’s go binary
  3. Updates PATH (requires appropriate permissions)
  4. Sets up environment variables (GOROOT, GOPATH, etc.)
  5. Checks if GOPATH/bin is in PATH - warns with fix instructions if missing

Automatic PATH Check: After switching, Gopher automatically verifies that $GOPATH/bin is in your PATH. If not, you’ll see a warning with platform-specific fix instructions. This ensures that tools installed via go install are accessible from the command line.

gopher current

Shows the currently active Go version.

gopher current

Output:

Current Go version: go1.21.0 (darwin/arm64)

gopher system

Shows detailed information about system Go.

gopher system

Output:

System Go Information:
  System Go: go version go1.25.1 darwin/arm64
  Path: /opt/homebrew/opt/go/libexec/bin/go
  GOROOT: /opt/homebrew/opt/go/libexec
  GOPATH: /Users/molmedoz/go
  Installed: 2025-08-27 08:49:40
  System: true

gopher version

Shows gopher version information.

gopher version

gopher init

Runs the interactive setup wizard for platform-specific configuration.

gopher init

What it does:

  1. Detects your operating system and architecture
  2. Prompts for installation preferences
  3. Sets up shell integration
  4. Configures environment variables
  5. Creates initial configuration

Example output:

🚀 Welcome to Gopher Setup Wizard!

Detected system: darwin/arm64
Install directory: /Users/username/.gopher/versions
Download directory: /Users/username/.gopher/downloads

Setting up shell integration...
✓ Shell integration configured for zsh
✓ Configuration saved

gopher setup

Sets up shell integration for persistent Go version switching.

gopher setup

What it does:

  1. Detects your shell (bash, zsh, fish)
  2. Adds gopher integration to shell profile
  3. Enables automatic version switching
  4. Sets up environment variables

Supported shells:

gopher status

Shows persistence status and shell integration information.

gopher status

Output:

Gopher Status:
  Shell Integration: ✓ Enabled (zsh)
  Profile File: /Users/username/.zshrc
  Current Version: go1.21.0
  Active Version: go1.21.0
  System Go: Available

gopher debug

Shows debug information for troubleshooting.

gopher debug

Output:

Debug Information:
  Gopher Version: v1.0.0
  Go Version: go1.21.0
  OS: darwin
  Arch: arm64
  Install Dir: /Users/username/.gopher/versions
  Download Dir: /Users/username/.gopher/downloads
  Config File: /Users/username/.gopher/config.json
  Shell: zsh
  PATH: /Users/username/.gopher/versions/go1.21.0/bin:/usr/local/bin:...

Useful for:

gopher clean

Removes the download cache to free up disk space. This command deletes all downloaded Go archive files from ~/.gopher/downloads/ without affecting installed Go versions.

gopher clean

Example Output:

Cleaning download cache...
✓ Successfully cleaned download cache
  Freed: 125.3 MB

When to Use:

Note: Downloaded files are only needed during installation. Once a Go version is installed, the download archive is no longer required.

gopher purge

Completely removes all Gopher data including installed versions, download cache, configuration, state files, and symlinks. This operation requires explicit confirmation and cannot be undone.

gopher purge

Interactive Confirmation:

⚠️  WARNING: This will permanently delete ALL Gopher data:
  • All installed Go versions
  • Download cache
  • Configuration files
  • State files and aliases
  • Gopher-created symlinks

This operation CANNOT be undone!

Type 'yes' to confirm purge: yes

Purging all Gopher data...
✓ Successfully purged all Gopher data
  All Gopher files and directories have been removed.

To use Gopher again, run: gopher init

What Gets Removed:

When to Use:

Important: After purging, you’ll need to run gopher init to use Gopher again. Your system Go installation (if any) will remain unaffected.

System Go Management

Gopher automatically detects and manages your system-installed Go versions alongside Gopher-managed versions.

Supported System Installations

Gopher recognizes these system Go installations:

System Go Features

Working with System Go

# Check if system Go is available
gopher system

# Switch to system Go
gopher use system

# List all versions (including system)
gopher list

# Get system Go info in JSON
gopher system --json

Environment Management

Gopher provides comprehensive environment variable management to ensure proper Go development workflows. This section covers GOPATH and GOROOT management, environment configuration, and automatic script generation.

GOPATH Management Modes

Gopher supports three different GOPATH management strategies to suit different development needs:

1. Shared Mode (Default)

Best for: Most users, shared projects, simple setups

All Go versions share the same GOPATH directory, allowing packages to be shared across versions.

# Set shared mode (default)
gopher env set gopath_mode=shared

# Check current configuration
gopher env list

# Switch to a Go version
gopher use 1.21.0
# GOPATH=/home/user/go (shared across all versions)

Advantages:

Disadvantages:

2. Version-Specific Mode

Best for: Development work, testing, complete isolation

Each Go version has its own isolated GOPATH directory.

# Set version-specific mode
gopher env set gopath_mode=version-specific

# Switch to different versions
gopher use 1.21.0
# GOPATH=/home/user/.gopher/versions/go1.21.0/gopath

gopher use 1.22.0
# GOPATH=/home/user/.gopher/versions/go1.22.0/gopath

Advantages:

Disadvantages:

3. Custom Mode

Best for: Specific project requirements, custom workspace setups

Use a custom GOPATH location specified by the user.

# Set custom mode
gopher env set gopath_mode=custom
gopher env set custom_gopath=/path/to/your/workspace

# Switch to a Go version
gopher use 1.21.0
# GOPATH=/path/to/your/workspace

Advantages:

Disadvantages:

Environment Configuration

Viewing Configuration

# List all configuration options
gopher env list

# Show environment variables for a specific version
gopher env show go1.21.0

# Show environment variables in JSON format
gopher env show go1.21.0 --json

Setting Configuration

# Set GOPATH mode
gopher env set gopath_mode=version-specific

# Set custom GOPATH (when mode is custom)
gopher env set custom_gopath=/path/to/workspace

# Configure Go proxy
gopher env set goproxy=https://proxy.golang.org,direct

# Configure checksum database
gopher env set gosumdb=sum.golang.org

# Enable/disable environment variable setting
gopher env set set_environment=true

Resetting Configuration

# Reset all configuration to defaults
gopher env reset

Automatic Environment Scripts

When switching Go versions, Gopher automatically generates environment activation scripts that set up all necessary environment variables.

Script Generation

# Switch to a Go version (generates script automatically)
gopher use 1.21.0

# Output:
# ✓ Environment variables configured for Go go1.21.0
#   To activate this environment, run:
#   source /home/user/.gopher/scripts/go-go1.21.0.env
#   Or add the following to your shell profile:
#   export GOROOT=/home/user/.gopher/versions/go1.21.0
#   export GOPATH=/home/user/go
#   export GOPROXY=https://proxy.golang.org,direct
#   export GOSUMDB=sum.golang.org
#   export PATH=/home/user/.gopher/versions/go1.21.0/bin:...

Script Location

Environment scripts are stored in ~/.gopher/scripts/:

~/.gopher/scripts/
├── go-go1.21.0.env
├── go-go1.22.0.env
└── go-system.env

Activating Environment

Method 1: Source the script

source ~/.gopher/scripts/go-go1.21.0.env

Method 2: Add to shell profile

# Add to ~/.bashrc, ~/.zshrc, etc.
echo 'source ~/.gopher/scripts/go-go1.21.0.env' >> ~/.bashrc

Method 3: Manual export

export GOROOT=/home/user/.gopher/versions/go1.21.0
export GOPATH=/home/user/go
export GOPROXY=https://proxy.golang.org,direct
export GOSUMDB=sum.golang.org
export PATH=/home/user/.gopher/versions/go1.21.0/bin:$PATH

Environment Variables

Gopher manages the following environment variables:

Variable Description Example
GOROOT Go installation directory /home/user/.gopher/versions/go1.21.0
GOPATH Go workspace directory /home/user/go (shared) or /home/user/.gopher/versions/go1.21.0/gopath (version-specific)
GOPROXY Go module proxy https://proxy.golang.org,direct
GOSUMDB Go checksum database sum.golang.org
PATH System PATH with Go binary /home/user/.gopher/versions/go1.21.0/bin:...

Workflow Examples

Example 1: Shared Development Setup

# Use shared GOPATH for common development
gopher env set gopath_mode=shared
gopher env set set_environment=true

# Install and switch to Go 1.21.0
gopher install 1.21.0
gopher use 1.21.0

# Activate environment
source ~/.gopher/scripts/go-go1.21.0.env

# Verify setup
go version
echo $GOPATH  # /home/user/go

Example 2: Isolated Testing Setup

# Use version-specific GOPATH for testing
gopher env set gopath_mode=version-specific
gopher env set set_environment=true

# Install multiple Go versions
gopher install 1.21.0
gopher install 1.22.0

# Test with Go 1.21.0
gopher use 1.21.0
source ~/.gopher/scripts/go-go1.21.0.env
go mod init test-project
go get github.com/gin-gonic/gin

# Test with Go 1.22.0 (isolated environment)
gopher use 1.22.0
source ~/.gopher/scripts/go-go1.22.0.env
go mod init test-project  # Fresh start, no shared packages

Example 3: Project-Specific Setup

# Use custom GOPATH for specific project
gopher env set gopath_mode=custom
gopher env set custom_gopath=/path/to/my-project
gopher env set set_environment=true

# Switch to Go version
gopher use 1.21.0

# Activate environment
source ~/.gopher/scripts/go-go1.21.0.env

# Verify custom GOPATH
echo $GOPATH  # /path/to/my-project

Troubleshooting Environment Issues

GOPATH/bin Not in PATH Warning

Problem: After switching versions, you see a warning that GOPATH/bin is not in your PATH

What this means:

Solution:

# Gopher automatically shows the fix when this warning appears
# For Unix/Linux/macOS:
export PATH="$GOPATH/bin:$PATH"

# Or add permanently to your shell profile (~/.bashrc, ~/.zshrc):
echo 'export PATH="$GOPATH/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For Windows (PowerShell):
$env:PATH = "$env:GOPATH\bin;$env:PATH"

# Or permanently via PowerShell:
[Environment]::SetEnvironmentVariable("PATH", "$env:GOPATH\bin;" + [Environment]::GetEnvironmentVariable("PATH", "User"), "User")

Note: Gopher automatically checks for this issue after every version switch and provides platform-specific instructions.

Environment Not Activated

Problem: Go commands not found after switching versions

Solution:

# Check if environment script exists
ls -la ~/.gopher/scripts/

# Activate environment manually
source ~/.gopher/scripts/go-go1.21.0.env

# Or recreate the environment
gopher use 1.21.0

Wrong GOPATH

Problem: GOPATH not set correctly

Solution:

# Check current configuration
gopher env list

# Check environment variables for version
gopher env show go1.21.0

# Reset configuration if needed
gopher env reset

Script Permission Issues

Problem: Cannot source environment script

Solution:

# Check script permissions
ls -la ~/.gopher/scripts/go-go1.21.0.env

# Fix permissions if needed
chmod +x ~/.gopher/scripts/go-go1.21.0.env

# Or use manual export
gopher env show go1.21.0
# Copy and paste the export commands

Configuration

Configuration File

Gopher stores its configuration in:

Default Configuration

{
  "install_dir": "~/.gopher/versions",
  "download_dir": "~/.gopher/downloads",
  "mirror_url": "https://go.dev/dl/",
  "auto_cleanup": true,
  "max_versions": 5
}

Configuration Options

Option Description Default
install_dir Directory for Go versions ~/.gopher/versions
download_dir Temporary download directory ~/.gopher/downloads
mirror_url Go download mirror URL https://go.dev/dl/
auto_cleanup Auto-remove old versions true
max_versions Maximum versions to keep 5

Custom Configuration

# Use custom configuration file
gopher --config /path/to/config.json list

# Environment variables
export GOPHER_CONFIG=/path/to/config.json
export GOPHER_INSTALL_DIR=/opt/go-versions
export GOPHER_DOWNLOAD_DIR=/tmp/gopher-downloads

Creating Custom Config

# Create config directory
mkdir -p ~/.gopher

# Create custom config
cat > ~/.gopher/config.json << EOF
{
  "install_dir": "/opt/go-versions",
  "download_dir": "/tmp/gopher-downloads",
  "mirror_url": "https://go.dev/dl/",
  "auto_cleanup": true,
  "max_versions": 10
}
EOF

Scripting and Automation

JSON Output

All commands support JSON output for scripting:

# Get current version in JSON
current_version=$(gopher current --json | jq -r '.version')
echo "Current Go version: $current_version"

# List versions as JSON
gopher list --json | jq '.[] | select(.is_active) | .version'

# Get system Go path
system_path=$(gopher system --json | jq -r '.path')
echo "System Go path: $system_path"

Shell Integration

Add to your shell profile (.bashrc, .zshrc, etc.):

# Auto-switch Go versions based on directory
function cd() {
    builtin cd "$@"
    if [[ -f .gopher-version ]]; then
        gopher use $(cat .gopher-version)
    fi
}

# Go version prompt
export PS1='$(gopher current --json | jq -r ".version") $ '

CI/CD Integration

# GitHub Actions example
- name: Setup Go with Gopher
  run: |
    go install github.com/molmedoz/gopher/cmd/gopher@latest
    gopher install 1.21.0
    gopher use 1.21.0
    echo "$(gopher current --json | jq -r '.path')" >> $GITHUB_PATH

Project-Specific Versions

Create .gopher-version files in your projects:

# In your project directory
echo "1.21.0" > .gopher-version

# Auto-switch script
#!/bin/bash
if [[ -f .gopher-version ]]; then
    version=$(cat .gopher-version)
    if gopher list --json | jq -e ".[] | select(.version == \"go$version\")" > /dev/null; then
        gopher use $version
    else
        echo "Installing Go $version..."
        gopher install $version
        gopher use $version
    fi
fi

Visual Indicators

Gopher provides clear visual indicators to help you identify the active Go version and distinguish between different types of versions.

Active Version Indicators

The list command shows clear visual indicators for the currently active version:

gopher list

Output with indicators:

  go1.24.7 (darwin/arm64) [system]
  go1.22.0 (darwin/arm64)
  go1.22.1 (darwin/arm64)
→ go1.23.0 (darwin/arm64) [active]

Indicator meanings:

Color Support

Gopher automatically detects terminal color support and provides:

Disabling Visual Indicators

If you prefer plain text output:

# Use JSON output for scripting
gopher --json list

# Or redirect to a file
gopher list > versions.txt

Verbosity Control

Gopher provides flexible verbosity control through command-line flags to help you get the right amount of information for your needs.

Log Levels

Gopher supports multiple log levels:

Using Verbosity Flags

Quiet Mode (ERROR level only)

# Minimal output - only errors
gopher --quiet list
gopher -q install 1.21.0

# Useful for scripting and automation
current_version=$(gopher -q current --json | jq -r '.version')

Verbose Mode (DEBUG level)

# Detailed output with debugging information
gopher --verbose install 1.21.0
gopher -v list

# Shows detailed progress and internal operations
gopher -v install 1.21.0
# Output:
# [DEBUG] Starting Go installation {version=go1.21.0 file=/tmp/go1.21.0.darwin-arm64.tar.gz}
# [INFO] Downloading file {file=go1.21.0.darwin-arm64.tar.gz}
# [DEBUG] Extracting files {count=1000}
# [INFO] Successfully installed Go version {version=go1.21.0}

Default Mode (INFO level)

# Standard output - general information
gopher list
gopher install 1.21.0

# Shows important information without excessive detail

Verbosity in Different Commands

Installation Commands

# Quiet installation (minimal output)
gopher -q install 1.21.0

# Verbose installation (detailed progress)
gopher -v install 1.21.0

# Default installation (standard progress)
gopher install 1.21.0

Listing Commands

# Quiet listing (just the list)
gopher -q list

# Verbose listing (with metadata)
gopher -v list

# Default listing (standard format)
gopher list

System Commands

# Quiet system info
gopher -q system

# Verbose system detection
gopher -v system

# Default system info
gopher system

Combining with Other Flags

Verbosity flags work with other command-line options:

# Verbose JSON output
gopher -v --json list

# Quiet installation with custom config
gopher -q --config /path/to/config.json install 1.21.0

# Verbose alias creation
gopher -v alias create stable 1.21.0

Use Cases

Development and Debugging

# Debug installation issues
gopher -v install 1.21.0

# Debug system detection
gopher -v system

# Debug alias operations
gopher -v alias create stable 1.21.0

Scripting and Automation

# Quiet mode for scripts
gopher -q current --json

# Error-only output for error handling
gopher -q install 1.21.0 || echo "Installation failed"

User-Friendly Output

# Standard output for interactive use
gopher list
gopher install 1.21.0

Troubleshooting

Troubleshooting Decision Tree

Use this decision tree to quickly identify and resolve common issues:

┌─────────────────────────────────────────────────────────────────┐
│                GOPHER TROUBLESHOOTING DECISION TREE             │
└─────────────────────────────────────────────────────────────────┘

START: What's the problem?
│
├─ [Gopher command not found]
│  │
│  ├─ Check if installed: which gopher
│  │  ├─ Not found → Reinstall (see Installation section)
│  │  └─ Found → Check PATH configuration
│  │             └─ Add to PATH: export PATH=$PATH:/path/to/gopher
│  │
│  └─ Still not working?
│     └─ Check shell config (~/.bashrc or ~/.zshrc)
│        └─ Reload: source ~/.bashrc
│
├─ [Version not switching / Wrong version active]
│  │
│  ├─ Verify switch: gopher current
│  │  └─ Check actual: go version
│  │
│  ├─ Not matching?
│  │  ├─ Check symlink: ls -la $(which go)
│  │  ├─ Reload shell: source ~/.bashrc
│  │  └─ Try switching again: gopher use <version>
│  │
│  └─ Still wrong?
│     └─ Check for multiple Go installations
│        └─ which -a go  # Shows all Go binaries in PATH
│
├─ [Installation failed / Download issues]
│  │
│  ├─ Check internet connection
│  │  └─ Test: curl -I https://go.dev/dl/
│  │
│  ├─ Try different mirror
│  │  └─ gopher env set mirror_url=https://golang.google.cn/dl/
│  │
│  ├─ Check disk space
│  │  └─ df -h ~/.gopher
│  │
│  └─ Enable verbose logging
│     └─ gopher --verbose install <version>
│
├─ [Permission denied errors]
│  │
│  ├─ Linux/macOS
│  │  ├─ Check permissions: ls -la ~/.gopher
│  │  ├─ Fix if needed: chmod -R u+w ~/.gopher
│  │  └─ May need sudo: sudo gopher use <version>
│  │
│  └─ Windows
│     ├─ Check Developer Mode: Settings → Privacy & Security
│     ├─ Enable Developer Mode (required for symlinks)
│     └─ Run as Administrator (if needed)
│
├─ [Go programs not finding packages]
│  │
│  ├─ Check GOPATH: echo $GOPATH
│  │  └─ Not set?
│  │     └─ gopher env show <version>
│  │        └─ Copy and run export commands
│  │
│  ├─ Check GOROOT: echo $GOROOT
│  │  └─ Should point to: ~/.gopher/versions/<version>
│  │
│  └─ Reset environment
│     └─ gopher env reset
│        └─ gopher use <version>
│
├─ [Installed Go tools/packages not working]
│  │
│  ├─ Check if GOPATH/bin is in PATH: echo $PATH | grep $GOPATH/bin
│  │  └─ Not found?
│  │     └─ Add to PATH (Gopher shows warning with instructions)
│  │        ├─ Unix: export PATH="$GOPATH/bin:$PATH"
│  │        └─ Windows: set PATH=%GOPATH%\bin;%PATH%
│  │
│  └─ Check GOPATH: echo $GOPATH
│     └─ Should match current version's GOPATH
│        └─ gopher env show <version>
│           └─ Verify PATH includes GOPATH/bin
│
├─ [Slow downloads]
│  │
│  ├─ Try different mirror
│  │  └─ China: gopher env set mirror_url=https://golang.google.cn/dl/
│  │
│  ├─ Check proxy settings
│  │  └─ echo $GOPROXY
│  │
│  └─ Use direct connection
│     └─ gopher env set goproxy=direct
│
└─ [Other issues]
   │
   ├─ Enable debug logging
   │  └─ gopher --verbose <command>
   │
   ├─ Check system status
   │  └─ gopher system
   │
   ├─ Verify installation
   │  └─ gopher list
   │     └─ gopher current
   │
   └─ Still stuck?
      ├─ Check FAQ: docs/FAQ.md
      ├─ Search Issues: github.com/molmedoz/gopher/issues
      └─ Create New Issue with debug output

Quick Diagnostic Commands

Run these commands to gather diagnostic information:

# Check Gopher installation
which gopher
gopher version

# Check current Go setup
which go
go version
gopher current
gopher system

# Check environment
echo $PATH
echo $GOROOT
echo $GOPATH
gopher env list

# List all installed versions
gopher list

# Check for multiple Go installations
which -a go   # Linux/macOS
where go      # Windows

Common Issues

Permission Denied When Switching Versions

Problem:

Error: failed to create symlink: permission denied

Solution:

# On macOS/Linux, you may need sudo for system-wide symlinks
sudo gopher use 1.21.0

# Or use a local installation directory
export GOPHER_INSTALL_DIR=~/.local/go-versions
gopher use 1.21.0

Go Not Found After Switching

Problem:

go: command not found

Solution:

# Check if symlink was created
ls -la /usr/local/bin/go

# Recreate symlink
gopher use 1.21.0

# Check PATH
echo $PATH

System Go Not Detected

Problem: System Go not showing in gopher list

Solution:

# Check if Go is in PATH
which go

# Check system detection
gopher system

# Verify Go installation
go version

Download Failures

Problem:

Error: failed to download version

Solution:

# Check internet connection
ping go.dev

# Try different mirror
gopher --config <(echo '{"mirror_url": "https://golang.org/dl/"}') install 1.21.0

# Check disk space
df -h

Debug Mode

Enable verbose output for debugging:

# Set debug environment variable
export GOPHER_DEBUG=1

# Run commands with debug output
gopher list
gopher install 1.21.0

Log Files

Gopher logs to:

Reset Gopher

If gopher gets into a bad state:

# Remove gopher directory
rm -rf ~/.gopher

# Reinstall
go install github.com/molmedoz/gopher/cmd/gopher@latest

# Reconfigure
gopher list

Advanced Usage

Custom Go Mirrors

# Use different mirror
gopher --config <(echo '{"mirror_url": "https://golang.org/dl/"}') install 1.21.0

# Corporate mirror
gopher --config <(echo '{"mirror_url": "https://internal-mirror.company.com/go/"}') install 1.21.0

Multiple Gopher Instances

# Different configs for different projects
gopher --config ~/.gopher/project1.json use 1.21.0
gopher --config ~/.gopher/project2.json use 1.20.7

Integration with Other Tools

VS Code

Add to VS Code settings:

{
  "go.goroot": "~/.gopher/versions/go1.21.0",
  "go.toolsEnvVars": {
    "GOROOT": "~/.gopher/versions/go1.21.0"
  }
}

Docker

# Use gopher in Docker
FROM golang:1.21-alpine AS gopher
RUN go install github.com/molmedoz/gopher/cmd/gopher@latest

FROM alpine:latest
COPY --from=gopher /go/bin/gopher /usr/local/bin/gopher
RUN gopher install 1.21.0

Performance Tips

  1. Use SSD storage for better performance
  2. Enable auto-cleanup to save disk space
  3. Use local mirrors for faster downloads
  4. Set appropriate max_versions based on your needs

Security Considerations

See Also

Platform-Specific Guides

Additional Resources

Getting Help

Contributing

See CONTRIBUTING.md for information on contributing to Gopher.

This site is open source. Improve this page.