# How Superfile's Auto-Update Check Mechanism Works

> Discover how Superfile's auto-update check mechanism works. Learn how it queries the GitHub API on startup to ensure you have the latest version, enhancing your experience.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: internals
- Published: 2026-07-26

---

**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`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go) at line 74, this field is declared:

```go
// 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`](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go). At lines 235–239, the application checks whether the feature is enabled before invoking the update routine:

```go
// 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:**

```go
// 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:**

```go
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:**

```go
// 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`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go) (line 74).
- **Startup evaluation**: The check triggers in [`src/cmd/main.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go), preventing the `checkForUpdates()` function from being invoked at startup in [`src/cmd/main.go`](https://github.com/yorukot/superfile/blob/main/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.