submodules_configuration.md

Submodule Configuration

Every value xfetch renders is a submodule: a module key (e.g. cpu) that produces a value, an icon and an optional row key. Two config maps give you full control over how submodules look, without touching the probe logic:

• labels — rename or hide the row key shown per module.
• formats — replace a module's value with a template of {field} placeholders.

Both are optional and additive: an empty map (or absent key) keeps the default output byte-for-byte, so existing configs keep working unchanged. Formatting is applied once, when the render tree is built, so it works identically in every layout (classic and variants, compact, minimal, section, section-box, tree, custom-x) and in both daemons (animated-logo and live stats).

labels — Row Keys

The labels map renames the key shown for a module. An empty string hides the key entirely, leaving an icon-only row. Modules without an entry keep their module name.

Field	Type	Default	Description
labels	object	{}	Per-module key labels: "cpu": "procesador" renames the key; "gpu": "" hides it. Colors keep using the raw module key, so renaming never breaks the color mapping.

{
    "labels": {
        "cpu": "procesador",
        "gpu": "",
        "memory": "ram"
    }
}

formats — Value Templates

The formats map replaces a module's value with a template string. Placeholders {field} are substituted with the module's fields. Rules:

• Unknown placeholders render empty.
• {{ and }} escape literal braces.
• Modules without an entry use the default template {value} (the current output).

Module	Fields	Example
every module	{value} (current output), {key} (module name)	"os": "Sistema: {value}"
cpu	{brand} raw brand {model} cleaned brand ((R)/(TM), CPU @ ..., core-count suffixes removed) {cores} logical core count {freq} frequency (3.00 GHz)	"cpu": "{model} · {cores} núcleos · {freq}"
gpu	{name} device name {vendor} vendor (NVIDIA, AMD, Intel, Apple, ...) {model} best-effort model (vendor, product-line prefix and VRAM stripped) {vram} trailing VRAM (6GB), when present	"gpu": "{vendor} {model}"
memory, swap	{used}, {total} (with unit), {percent} (bare number)	"memory": "{used} / {total} ({percent}%)"
disk	memory fields plus {fs} (filesystem name, when shown)	"disk": "{used} en {fs}"
os	{distro}, {version}, {arch}, {wsl} (only with the WSL decoration)	"os": "{distro} {version} ({arch})"
packages	one field per package manager ({pacman}, {aur}, {dpkg}, ...), plus {count}/{manager} (first entry) and {managers} (joined names)	"packages": "pkg: {pacman} · aur: {aur}"
battery	{percent} (bare number), {state} (Charging, Discharging, ...)	"battery": "{percent}% [{state}]"
uptime	{days}, {hours}, {mins} (days derived from the hour count)	"uptime": "{days}d {hours}h {mins}m"
datetime	{date}, {time}	"datetime": "{date} | {time}"

{
    "formats": {
        "cpu": "{model} ({cores}) @ {freq}",
        "gpu": "{vendor} {model}",
        "memory": "{value}"
    }
}

Examples

Source values and what the templates turn them into:

Module	Raw value	Template	Result
cpu	Intel(R) Core(TM) i5-7400 CPU @ 3.00GHz (4) @ 3.00 GHz	{model}	Intel Core i5-7400
cpu	AMD Ryzen 7 5800X 8-Core Processor (8) @ 4.70 GHz	{model} ({cores}) @ {freq}	AMD Ryzen 7 5800X (8) @ 4.70 GHz
gpu	NVIDIA GeForce GTX 1060 6GB	{vendor} {model}	NVIDIA GTX 1060
gpu	GP106 [GeForce GTX 1060 6GB] (lspci)	{model}	GTX 1060

GPU Fields Per Platform

GPU field extraction lives where the probe output lives — each platform knows the shape of its own output:

Platform	Probe	Raw example	Extraction
Linux	lspci -mm	GP106 [GeForce GTX 1060 6GB]	{name} from the bracketed description, then the shared vendor/VRAM/model rules.
Windows	wmic / PowerShell CIM	NVIDIA GeForce GTX 1060 6GB	Plain device name; vendor word and VRAM split off.
macOS	system_profiler (Chipset Model)	Apple M2 Pro	Plain device name; vendor word and VRAM split off.

The shared rules (vendor detection, trailing VRAM, model cleaning) live in platform/shared/gpu.rs and are covered by unit tests.

Escaping and Empty Fields

{
    "formats": {
        // {{ and }} produce literal braces:
        "os": "{{ {value} }}",          // "{ Ubuntu 24.04 }"
        // unknown fields render empty:
        "hostname": "[{unknown}] {value}" // "[ ] myhost"
    }
}

Related

• CONFIGURATION.md — the rest of the config surface (modules, icons, colors, layout).
• LAYOUTS.md — the layouts these labels/formats apply to.