Auto-Update Check Mechanism and Version Comparison in Superfile: How It Works

Superfile compares a build-time injected version string against the latest GitHub release tag using semantic versioning logic whenever auto_check_update is enabled in the configuration.

Superfile, the terminal-based file manager by yorukot, includes a built-in auto-update check mechanism that queries GitHub Releases to notify users when newer versions are available. This system relies on compile-time version injection controlled by ldflags and a lightweight semantic version parser to avoid heavy external dependencies. The entire workflow is governed by a single boolean flag defined in the internal configuration types.

Build-Time Version Injection and Configuration

The update mechanism begins with version identification at compile time. In src/main.go, a version variable is injected during the build process using Go ldflags:

go build -ldflags "-X main.version=v1.2.3"

This hardcoded string becomes the canonical reference for the running binary. Whether the application uses this version to perform checks depends on the AutoCheckUpdate boolean field defined in src/internal/common/config_type.go at line 74. The src/internal/common/load_config.go file handles loading the user configuration, reading the auto_check_update value (which defaults to true) from the TOML config file to determine if a GitHub query should execute on startup.

GitHub API Integration and Semantic Comparison

When enabled, the update check logic reaches out to the GitHub Releases API to fetch the latest tag name (e.g., v1.3.0). According to the source implementation, the current and latest versions are parsed into their numeric components—major, minor, and patch—and compared using standard semantic versioning rules:

1. Major version takes precedence; a higher major version indicates a newer release
2. If majors are equal, minor version determines precedence
3. If both major and minor are equal, patch version is compared

If the remote version exceeds the local version, Superfile displays a concise notification with a link to the release page. If the current version is already the latest (or newer, such as when running a development build), the check silently passes without user notification.

Enabling and Disabling Auto-Updates

Users control this feature through the TOML configuration file:

Enable automatic checks (default):

# ~/.config/superfile/config.toml

auto_check_update = true

Disable automatic checks:

auto_check_update = false

Setting this to false prevents the application from querying GitHub during initialization, eliminating network overhead on startup.

Manual Update Checks

Beyond the automatic startup check, Superfile supports immediate manual verification via command-line flag:

superfile --check-update

This executes the same GitHub API query and semantic version comparison logic found in the automatic check workflow, providing instant feedback if an update is available.

Summary

• The auto_check_update field in src/internal/common/config_type.go controls whether Superfile checks for updates on startup
• Version strings are injected at build time via -ldflags "-X main.version=vX.Y.Z" in src/main.go
• The comparison logic parses GitHub release tags into semantic version components (major, minor, patch)
• Users can disable automatic checks in the TOML configuration or trigger manual checks using --check-update

Frequently Asked Questions

How do I disable automatic update checks in superfile?

Set auto_check_update = false in your configuration file (typically located at ~/.config/superfile/config.toml). This boolean flag is defined in src/internal/common/config_type.go and processed by src/internal/common/load_config.go during application initialization.

Where is the version number defined in superfile?

The version is injected at compile time rather than hardcoded in the source. The main.go file contains a version variable that receives its value via Go ldflags during the build process: -ldflags "-X main.version=vX.Y.Z". This allows the binary to report its version without requiring constant source code modifications.

How does superfile compare versions to determine if an update is available?

Superfile implements a lightweight semantic version parser that splits both the current build version and the latest GitHub release tag into major, minor, and patch integers. It performs a hierarchical comparison: first comparing major versions, then minor if majors are equal, then patch if minors are equal. If the GitHub version is greater in the first differing tier, Superfile concludes an update is available.

Can I trigger an update check manually from the command line?

Yes. Running superfile --check-update initiates an immediate version check against the GitHub Releases API. This command uses the same configuration settings and semantic version comparison logic as the automatic startup check, displaying a notification with a download link if a newer version exists.

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