How to Override the Go Version When Listing Guidelines with the CLI

Use the --go-version flag with the go-modern-guidelines list command to explicitly set the target Go version, bypassing automatic toolchain detection.

The JetBrains/go-modern-guidelines command-line tool determines the active Go version by inspecting your environment and the go version output. When you need to test guidelines against a specific release, preview upcoming features, or enforce version policies in automated pipelines, you can override the Go version using the --go-version flag defined in internal/cli/cli.go.

How the --go-version Flag Works

In internal/cli/cli.go at line 53, the CLI defines the --go-version parameter that accepts version strings in multiple formats. When provided, the tool bypasses its automatic detection logic and uses your specified value for all version-specific checks.

The flag integrates with the resolution logic in internal/goversion/goversion.go, where the supplied string is parsed and normalized. This resolved version then drives the filtering mechanism in internal/guidelines/guidelines.go, ensuring only guidelines applicable to your target version are displayed.

Supported Version Format Syntax

The --go-version flag accepts three distinct version string formats according to the source implementation:

• 1.24 – Major and minor version shorthand (e.g., 1.20, 1.21, 1.24)
• go1.24.3 – Full version string as produced by the go version command (e.g., go1.20.5, go1.21.0)
• devel – Development build of the Go toolchain for testing upcoming features before official release

Practical Usage Examples

To list guidelines using the default detected version:

go-modern-guidelines list

To override the Go version to a specific minor release:

go-modern-guidelines list --go-version 1.24

To specify an exact patch level for precise filtering:

go-modern-guidelines list --go-version go1.24.3

To test against the development build:

go-modern-guidelines list --go-version devel

CI/CD Pipeline Integration

In continuous integration pipelines, you can enforce a specific Go version using environment variables to ensure consistent guideline evaluation across different runner environments:

steps:
  - name: Validate guidelines against Go 1.20
    run: go-modern-guidelines list --go-version $GO_VERSION
    env:
      GO_VERSION: "1.20"

This approach guarantees that guideline checks remain deterministic regardless of the default Go installation on CI runners.

Source Code Implementation Details

The version override mechanism spans three key files in the JetBrains/go-modern-guidelines repository:

• internal/cli/cli.go – Defines the --go-version flag at line 53 and wires it into the command parser
• internal/goversion/goversion.go – Implements version string parsing, normalization, and comparison logic
• internal/guidelines/guidelines.go – Applies the resolved version to filter the guideline set according to version-specific availability rules

Summary

• The --go-version flag overrides automatic Go version detection when listing guidelines with the CLI
• Accepts semantic versions (1.24), full version strings (go1.24.3), or devel for development builds
• Defined in internal/cli/cli.go (line 53) and processed through internal/goversion/goversion.go
• Enables testing guideline compatibility against future Go releases without upgrading your local toolchain
• Essential for enforcing consistent version policies in CI/CD pipelines

Frequently Asked Questions

How does the tool determine the Go version without the override flag?

When --go-version is omitted, the CLI executes the local go version command and parses the output to detect the installed toolchain version. This automatic detection ensures guidelines match your current development environment by default, sourcing the version from your system's Go binary.

Can I use partial version numbers like "1" or "1.21"?

Yes, the parser in internal/goversion/goversion.go accepts minor version specifications such as 1.21. However, for patch-specific guideline filtering, provide the full version string format go1.21.0 to ensure precise matching against version-dependent rules that check for specific patch releases.

Does the override flag modify my system's Go installation?

No, the --go-version flag only affects how the guidelines tool evaluates version-specific rules. It does not change your system's Go toolchain, modify environment variables, or alter the active Go binary. The flag is purely informational for the CLI's internal filtering logic in internal/guidelines/guidelines.go.

Where is the flag parsing logic implemented?

The flag definition resides in internal/cli/cli.go at line 53, where the command-line interface constructs the list command and binds the --go-version parameter to the version resolution functions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}