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

> Discover Superfile's auto-update check mechanism. Learn how it compares versions against GitHub releases using semantic logic when enabled.

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

---

**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`](https://github.com/yorukot/superfile/blob/main/src/main.go), a `version` variable is injected during the build process using Go ldflags:

```bash
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`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go) at line 74. The [`src/internal/common/load_config.go`](https://github.com/yorukot/superfile/blob/main/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):**

```toml

# ~/.config/superfile/config.toml

auto_check_update = true

```

**Disable automatic checks:**

```toml
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:

```bash
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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go) and processed by [`src/internal/common/load_config.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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.