How Superfile Embeds Default Configurations in Its Binary Using Go's embed Package

Superfile bundles its default themes, icons, and configuration files directly into the compiled executable using Go's embed package, exposing them through an embed.FS variable that is traversed at startup to populate global configuration structs.

The open-source terminal file manager yorukot/superfile ships with sensible defaults out of the box. To ensure these defaults are available without external file dependencies, the project embeds all default configuration assets directly into the binary. This allows the application to run immediately on any system while still permitting user customization through external config files.

Declaring the Embedded Filesystem in main/main.go

The embedding process starts in main/main.go with a //go:embed directive that instructs the Go compiler to package the entire src/superfile_config/ directory into the resulting binary.

//go:embed src/superfile_config/*
var content embed.FS

This content variable implements the embed.FS interface, providing a read-only virtual filesystem. The variable is passed into the application's core logic—typically via a Run(content) invocation—ensuring the embedded data is available throughout the application lifecycle without requiring physical files on disk.

Loading and Hydrating Configuration at Runtime

Once the binary starts, src/internal/common/load_config.go orchestrates the extraction and application of these defaults through the LoadAllDefaultConfig function.

Traversing the Virtual Filesystem with fs.WalkDir

Inside LoadAllDefaultConfig, Superfile uses fs.WalkDir to iterate recursively over every file within the embedded src/superfile_config path:

func LoadAllDefaultConfig(content embed.FS) error {
    return fs.WalkDir(content, "src/superfile_config", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if d.IsDir() {
            return nil
        }
        // Process individual files below...
        return nil
    })
}

Writing Themes and Parsing Structured Data

The loader distinguishes between binary assets (like themes) and structured configuration files. For theme files, it invokes WriteThemeFiles to extract the embedded bytes and write them to the user's local configuration directory. For JSON or YAML configuration files, the code reads the file content via content.ReadFile(path) and unmarshals the data directly into Go structs defined in src/internal/common/default_config.go and src/internal/common/config_type.go.

data, err := content.ReadFile(path)
if err != nil {
    return err
}

// Route based on file extension or path
switch filepath.Ext(path) {
case ".yaml", ".yml":
    // Unmarshal into theme or config structs
case ".json":
    // Parse icon definitions or fixed variables
}

Global Access and User Override Behavior

After initialization completes, the rest of the application references these values through global variables—such as cfg, iconConfig, and others—defined in src/internal/common/default_config.go. If a user creates custom configuration files in their $XDG_CONFIG_HOME/superfile/ directory (or the platform-specific equivalent), Superfile merges these user settings on top of the embedded defaults. This guarantees that every setting retains a sensible fallback value even if the user only customizes a subset of options.

Summary

• main/main.go uses a //go:embed src/superfile_config/* directive to pack the entire default configuration directory into the binary as an embed.FS.
• src/internal/common/load_config.go implements LoadAllDefaultConfig, which accepts the embed.FS and walks the virtual tree using fs.WalkDir.
• Theme extraction is handled by WriteThemeFiles, which writes embedded assets to the user's local config path.
• Structured defaults are unmarshaled from JSON/YAML into global Go structs defined in default_config.go and config_type.go.
• The architecture ensures zero-dependency portability while allowing user overrides via standard configuration directories.

Frequently Asked Questions

What Go version is required for embedding files?

Go 1.16 or later is required to use the embed package and //go:embed directives. Superfile leverages this feature to bundle its themes and default settings directly into the compiled executable.

Can I modify the embedded default configurations?

You cannot modify the files baked into the binary itself. However, you can override any default by placing a file with the same relative path in your user configuration directory ($XDG_CONFIG_HOME/superfile/). Superfile prioritizes user files over embedded defaults during the merge process.

Where are the source files that get embedded located?

The source files reside in the src/superfile_config/ directory at the repository root. This directory contains subdirectories for themes, icon definitions, and fixed variables, all of which are captured by the embed directive in main/main.go.

Does embedding configuration files increase the binary size?

Yes, the final binary includes the raw byte size of all embedded files. This increases the distributable size but eliminates external runtime dependencies, ensuring Superfile works immediately on fresh systems without requiring separate configuration file installation.

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