Warn users when system Go installation bypasses goenv shims

[Copilot]

Since PR #248, goenv places shims at the end of PATH by default. When a system Go exists (e.g. /usr/bin/go), it takes precedence over goenv's version management, silently breaking goenv.

Changes

Detection & Warning

• goenv init now detects system Go installations and warns when GOENV_PATH_ORDER is not front
• Warning displays on shell initialization with fix instructions:

  goenv: WARNING: System 'go' found at /usr/bin/go
  goenv: To fix this, add the following to your ~/.goenvrc:
  goenv:     export GOENV_PATH_ORDER=front
  

Test Infrastructure

• Added GOENV_DISABLE_PATH_WARNING env var to suppress warning in tests
• 4 new tests verify warning behavior across different configurations

Documentation

• Updated HOW_IT_WORKS.md to clarify PATH ordering behavior
• Documented GOENV_DISABLE_PATH_WARNING in ENVIRONMENT_VARIABLES.md

Implementation

Warning generation is conditional at init-script generation time (not runtime):

# In goenv-init
if [ "${GOENV_DISABLE_PATH_WARNING:-0}" != "1" ]; then
  cat <<'EOL'
if [ "${GOENV_PATH_ORDER:-}" != "front" ]; then
  system_go_path="$(command -v go 2>/dev/null || true)"
  if [ -n "$system_go_path" ]; then
    case "$system_go_path" in
      ${GOENV_ROOT}/*)
        ;;
      *)
        echo "goenv: WARNING: System 'go' found at $system_go_path" >&2
        # ... fix instructions
        ;;
    esac
  fi
fi
EOL
fi

Once user sets GOENV_PATH_ORDER=front, warning automatically disappears.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>go doesn't work if have /usr/bin/go</issue_title>
<issue_description>#247 moved the shims directory to the end of the PATH, so go doesn't work if have /usr/bin/go.

# the shims directory to the end of the PATH
which go
/usr/bin/go

# the shims directory to the start of the PATH
which go
~/.anyenv/envs/goenv/shims/go

</issue_description>

<agent_instructions>Figure out a way to make goenv to play nicely with a user-installed go (not managed by goenv). It should allow both Goenv and "system" to behave. Read all the comments on the issue and come up with a plan to fix this.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@ChronosMasterOfAllTime Maybe `goenv` should check if there is a "system" version and warn about the behavioral PATH collision? @ChronosMasterOfAllTime @ankitcharolia our version doesn't have a dependency on go or Python. It uses native shell which makes it more portable.

• Fixes go doesn't work if have /usr/bin/go #279

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.