How Superfile's Auto-Update Check Mechanism Works

Superfile checks for new releases on startup by querying the GitHub API when the AutoCheckUpdate configuration flag is enabled, comparing the remote version tag against the local binary version, and silently skipping the check if it fails or if it's the first run.

Superfile is a modern terminal file manager that includes an optional auto-update check mechanism to keep users informed about new releases. This feature leverages the GitHub Releases API to detect version changes without interrupting the user experience, as implemented in the yorukot/superfile repository.

The Configuration Flag: AutoCheckUpdate

The auto-update check is controlled by the AutoCheckUpdate boolean field defined in the configuration struct.

In src/internal/common/config_type.go at line 74, this field is declared:

// src/internal/common/config_type.go
type Config struct {
    …
    AutoCheckUpdate bool `toml:"auto_check_update" comment:"\nAuto check for update"`
    …
}

Users can toggle this behavior by setting auto_check_update = true or false in their Superfile configuration file.

Startup Logic: Triggering the Check

Superfile evaluates this flag during initialization in src/cmd/main.go. At lines 235–239, the application checks whether the feature is enabled before invoking the update routine:

// src/cmd/main.go
// Check for the need of updates if AutoCheckUpdate is on, if its the first time
if common.Config.AutoCheckUpdate {
    checkForUpdates()
}

This logic ensures that the network request only occurs when the user has explicitly opted in via configuration and the application is not running for the first time.

How the Version Check Works

When the checkForUpdates() function is invoked, it performs a lightweight HTTP request to determine if the running binary is outdated.

Fetching the Latest Release

The function queries the GitHub Releases API endpoint:

https://api.github.com/repos/yorukot/superfile/releases/latest

It extracts the tag_name field from the JSON response (e.g., "v1.1.4") and compares it against the version.Version variable compiled into the current binary.

First-Run Protection

To avoid unnecessary network traffic during the initial setup, Superfile tracks whether this is the user's first execution. The check is bypassed on the very first run after installation, ensuring that new users aren't immediately prompted with update notifications before they've configured the tool.

Version Comparison

The mechanism performs a semantic version comparison between the remote tag and the local version.Version string. If the remote version represents a newer release, Superfile sets an internal flag indicating that an update is available, which the UI can query on the next render cycle.

Error Resilience

The update check is wrapped in non-blocking error handling. Network failures, rate-limit responses (HTTP 403/429), or malformed JSON responses are caught and silently ignored. This design guarantees that a failing update check never blocks the main file manager interface or degrades the terminal user experience.

Practical Code Examples

To verify the update mechanism programmatically or inspect its behavior, you can reference these patterns:

Manually triggering the check:

// Example: manually triggering the check (useful for debugging)
if err := common.CheckForUpdates(); err != nil {
    fmt.Fprintln(os.Stderr, "Update check failed:", err)
}

Checking the version constant:

package main

import (
    "fmt"
    "github.com/yorukot/superfile/src/internal/common/version"
)

func main() {
    fmt.Printf("Current binary version: %s\n", version.Version)
    // This string is compared against the GitHub API response
}

Detecting updates in the UI loop:

// Inside the UI rendering loop
if common.UpdateAvailable {
    fmt.Println("[!] A new Superfile version is available! Run `superfile self-update`")
}

Summary

• Configuration-driven: The feature is controlled by AutoCheckUpdate in src/internal/common/config_type.go (line 74).
• Startup evaluation: The check triggers in src/cmd/main.go (lines 235–239) only when enabled and not on the first run.
• GitHub API source: It fetches the latest release tag from https://api.github.com/repos/yorukot/superfile/releases/latest.
• Silent failures: Network or API errors do not interrupt the UI.
• First-run aware: The mechanism skips the check during the initial execution to avoid immediate prompts.

Frequently Asked Questions

How do I disable the auto-update check in superfile?

Set auto_check_update = false in your Superfile configuration file. This updates the AutoCheckUpdate boolean in src/internal/common/config_type.go, preventing the checkForUpdates() function from being invoked at startup in src/cmd/main.go.

What happens if the GitHub API is unreachable when superfile starts?

The update check is wrapped in error handling that silently catches network failures, timeouts, or HTTP errors. Superfile will start normally without displaying an error message, and the main file manager interface will load immediately.

How does superfile determine if a version is newer?

Superfile compares the tag_name from the GitHub API response (e.g., "v1.1.5") against the locally compiled version.Version string. If the remote tag represents a higher semantic version, the application marks an update as available for the UI to display.

Where does superfile store the first-run state?

Superfile tracks the first-run state within the user's configuration directory. This allows the application to skip the update check during the initial execution after installation, preventing unnecessary API calls before the user has configured the tool.

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