Why the go-modern-guidelines CLI Installs to ~/.cache/go-modern-guidelines and How Caching Works

The go-modern-guidelines CLI installs into ~/.cache/go-modern-guidelines to isolate the binary from your $GOPATH/bin, comply with XDG Base Directory standards, and enable safe removal, while the cached executable is reused on subsequent runs without recompilation.

The JetBrains/go-modern-guidelines repository delivers a command-line tool for enforcing Go best practices. Unlike standard Go binaries that populate $GOPATH/bin or $HOME/go/bin, this project deliberately redirects its installation target to the user's XDG cache directory via the GOBIN environment variable. This architectural decision ensures version isolation, simplifies cleanup, and aligns with JetBrains plugin conventions for transient, user-specific tooling.

Why the CLI Installs to ~/.cache/go-modern-guidelines

Isolation from Default Go Binary Paths

Placing the binary in ~/.cache/go-modern-guidelines keeps it separate from your global $GOPATH/bin directory. This prevents version clashes with other Go tools you may have installed and avoids polluting your default Go binary path. The dev-install script in scripts/dev-install.sh explicitly overrides the installation target:

# In scripts/dev-install.sh

export GOBIN="${HOME}/.cache/go-modern-guidelines"
go install ./...                # builds the binary into $GOBIN

Compliance with XDG Base Directory Standards

The $HOME/.cache directory follows the XDG Base Directory Specification, which designates it as the recommended location for transient, rebuildable artifacts. This location is per-user, writable without elevated privileges, and consistently available across Linux, macOS, and Windows (via WSL). By adhering to this standard, the go-modern-guidelines CLI respects platform conventions for cached data.

Simplified Cleanup and Version Management

Because the folder is explicitly designated for cached data, deleting ~/.cache/go-modern-guidelines completely removes the tool without affecting your Go source code, module cache, or other environment settings. This makes version switching trivial—simply delete the directory and rerun the installation script to obtain a fresh binary.

Alignment with JetBrains Tooling Conventions

The repository functions as a JetBrains "skill" or plugin component. JetBrains tooling expects cached executables under ~/.cache for fast reuse across IDE sessions. Installing the go-modern-guidelines binary to this location ensures seamless integration with JetBrains IDEs that invoke the CLI for real-time code analysis.

How the go-modern-guidelines Caching Mechanism Works

First Installation and Compilation

During initial setup, the dev-install script creates the ~/.cache/go-modern-guidelines directory if it does not exist, then executes go install. Go compiles the source code, writes the resulting go-modern-guidelines executable into the cache directory, and stores any module dependencies in the standard Go module cache ($GOPATH/pkg/mod or $GOMODCACHE).

Reusing Cached Executables

When you invoke the CLI after installation, the binary is already present in the cache directory, so no recompilation occurs. The installation script checks the existence (and optionally the modification timestamp) of the cached binary before deciding whether to trigger a rebuild. This design ensures sub-second startup times for repeated invocations.

Embedded Guidelines Data

The guidelines themselves are embedded at compile time using the //go:embed directive in internal/guidelines/guidelines.go. The source file embeds guidelines.json directly into the binary:

// In internal/guidelines/guidelines.go
//go:embed guidelines.json
var guidelinesData []byte

Because the data is compiled into the executable, the CLI requires no additional runtime downloads or separate cache management for guideline updates. The cached binary contains the complete, up-to-date rule set.

Updating the Cached Binary

To upgrade to a newer version, rerun the installation script or execute go install with a specific version tag. The script overwrites the existing executable in ~/.cache/go-modern-guidelines, treating the cache directory as the single source of truth for the CLI binary.

Installing and Updating the CLI

Install the tool using the provided script, which automatically handles the cache directory setup:

# Run the cache-aware install helper

bash scripts/dev-install.sh

Invoke the CLI directly or ensure the cache directory is in your $PATH:

# Direct invocation

~/.cache/go-modern-guidelines/go-modern-guidelines list

# Or if PATH includes the cache directory

go-modern-guidelines list

Update to the latest version by rerunning the install script:

# Overwrites the cached binary with the new version

bash scripts/dev-install.sh

Key Implementation Files

• scripts/dev-install.sh: Sets GOBIN="${HOME}/.cache/go-modern-guidelines" and executes go install ./... to compile the binary into the XDG cache location.
• internal/guidelines/guidelines.go: Implements //go:embed guidelines.json to bundle guideline data directly into the compiled executable, eliminating runtime network requests.
• internal/cli/cli.go: Implements the command-line interface logic executed by the cached binary.
• Cached binary location: ~/.cache/go-modern-guidelines/go-modern-guidelines serves as the persistent executable reused across sessions.

Summary

• The go-modern-guidelines CLI installs to ~/.cache/go-modern-guidelines via the GOBIN variable in scripts/dev-install.sh to isolate it from $GOPATH/bin.
• This location follows XDG Base Directory standards, requires no elevated permissions, and allows safe deletion without side effects.
• The binary embeds guidelines.json at compile time using //go:embed, so no runtime downloads are necessary.
• Subsequent invocations reuse the cached executable, while updates overwrite the binary in the same directory.
• The design integrates specifically with JetBrains tooling expectations for cached, user-specific executables.

Frequently Asked Questions

Why doesn't go-modern-guidelines use $GOPATH/bin like other Go tools?

The project prioritizes isolation and clean uninstallation. By using ~/.cache/go-modern-guidelines instead of $GOPATH/bin, the tool avoids conflicts with other installed versions and allows users to delete the entire directory without affecting their broader Go environment. This approach also aligns with JetBrains plugin architecture, which expects cached executables in the XDG cache location.

How do I update the cached binary when a new version is released?

Simply rerun the installation script (bash scripts/dev-install.sh) or execute go install github.com/JetBrains/go-modern-guidelines@latest with GOBIN set to "${HOME}/.cache/go-modern-guidelines". The new compilation overwrites the existing cached executable, preserving the same installation path while updating the underlying code and embedded guidelines.

Does the CLI download guidelines data at runtime or include it in the binary?

The CLI includes the guidelines data directly within the binary at compile time. The file internal/guidelines/guidelines.go uses the //go:embed guidelines.json directive to bundle the JSON data, meaning the cached executable is self-contained. No network requests or additional cache directories are required to access the rule definitions during execution.

Is it safe to delete the ~/.cache/go-modern-guidelines directory?

Yes. Deleting this directory removes only the compiled CLI binary and any related build artifacts stored there. Because the directory is strictly a cache location according to XDG standards, removal does not affect your Go module cache, source code, IDE configuration, or other system tools. You can safely delete it and reinstall the tool later using the standard installation script.

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