How Fastfetch Format Strings Work: Complete Guide to Custom Output

Fastfetch format strings are parsed at runtime by ffParseFormatString in src/common/impl/format.c, which interpolates module data, evaluates conditionals, applies ANSI colors, and handles truncation to produce fully customizable terminal output.

Fastfetch uses a sophisticated format string system to give users pixel-perfect control over system information display. This deep dive examines how the fastfetch-cli/fastfetch repository implements dynamic output generation through runtime string parsing and interpolation, based on the current dev branch implementation.

The Format String Processing Pipeline

The fastfetch format string engine operates through a multi-stage pipeline that transforms template strings into rendered output. Each stage is implemented in specific source files with clear separation of concerns.

Module Data Exposure via FFformatarg

Every module populates a FFformatarg[] array with the values it can provide, such as {pretty-name}, {arch}, or {size}. This array construction happens inside each module's source file using the FF_PRINT_FORMAT_CHECKED macro.

For example, the OS module in src/modules/os/os.c defines which arguments are available for the format string to reference.

Parser Entry Points: ffPrintFormat and ffParseFormatString

When rendering output, the system calls ffPrintFormat from src/common/impl/printing.c. This function creates an FFstrbuf buffer and forwards the module's outputFormat along with the argument list to the core parser:

ffParseFormatString(&buffer, &moduleArgs->outputFormat, numArgs, arguments);

Source: printing.c L84–L88

The ffParseFormatString function in src/common/impl/format.c walks the format string character by character, copying literals and extracting placeholders when encountering opening braces.

Source: format.c L22–L38

Placeholder Parsing and Special Prefixes

When the parser encounters a { character, it analyzes the content based on special prefix characters. The implementation in src/common/impl/format.c (lines 46–84) handles these cases through a switch-style dispatcher:

• ? — If conditional: {?var} … {?} prints the interior only if var is set and non-zero
• / — Not-if conditional: {/var} … {/} prints only when var is not set or zero
• # — Color change: {#red} injects ANSI color codes (skipped when output is piped)
• $ — Environment variable or constant: {$HOME} or {${1}}
• : , < , > , ~ — Truncation and padding: {name:10} (max 10 chars), {name<10} (right-pad to 10), {name>10} (left-pad to 10), {name~5} (first 5 chars + ellipsis)

Argument Resolution and Value Rendering

The getArgumentIndex function translates placeholder names (like {size}) or numeric shortcuts (like {1}) into indices into the FFformatarg array.

Source: format.c L73–L98

Once the matching argument is identified, ffFormatAppendFormatArg formats the value according to its type (int, uint, string, bool, list, etc.) and appends it to the output buffer.

Source: format.c L9–L42

Finally, ffPrintFormat writes the completed buffer to stdout and appends a reset escape sequence unless the output is being piped.

Source: printing.c L92–L95

Format String Syntax Reference

The fastfetch format string system supports comprehensive text manipulation through specific placeholder syntax:

Feature	Syntax	Description
Simple field	{field}	Replaced by the value of field from the module's argument list
If conditional	{?field} … {?}	Prints inner content only if field is set and non-zero
Not-if conditional	{/field} … {/}	Prints inner content only if field is not set or zero
Color codes	{#color}	Sets ANSI color (e.g., {#red}, {#bright_blue}). Ignored with --pipe
Environment variables	{$VAR}	Inserts value of $VAR. Unset variables render as-is
Constants	{${n}}	Uses the n-th constant from the global constants array (set via --set-constants)
Truncation	{field:10}	Truncates to maximum 10 characters
Right padding	{field<10}	Left-pads with spaces to width 10
Left padding	{field>10}	Right-pads with spaces to width 10
Ellipsis truncation	{field~5}	Keeps first 5 characters and appends "…" if longer
Substring	{field:5,12}	Keeps characters 5–16 (zero-based index)
Escape braces	{{	Renders a literal { without starting a placeholder

Practical Command-Line Examples

Basic Module Formatting

Display the OS pretty name followed by the architecture:

fastfetch --format "OS: {pretty-name} ({arch})"

Conditional Display

Print temperature only when the module reports a valid value:

fastfetch --format "{?temperature}{temperature}°C{?}"

Colorized Output

Set field-specific colors using ANSI codes:

fastfetch --format "{#green}{name}{#reset}: {#yellow}{version}{#reset}"

Truncation and Padding

Limit name to 15 characters and right-pad size to 10 characters:

fastfetch --format "{name:15} {size>10}"

Environment Variables

Insert shell environment values directly:

fastfetch --format "Home: {$HOME}"

Custom Key Formatting

Format the key itself (the label before the value) using --set-key:

fastfetch --set-key "{icon} {module-name}"

Core Source Files and Architecture

Understanding the format string engine requires familiarity with these key files in the fastfetch-cli/fastfetch repository:

• src/common/format.h — Defines FFformatarg structure and the FF_PARSE_FORMAT_STRING_CHECKED helper macro
• src/common/impl/format.c — Core parser implementing placeholder expansion, conditionals, colors, truncation, and environment variable resolution
• src/common/printing.h — Declares ffPrintFormat and the FF_PRINT_FORMAT_CHECKED macro used by modules
• src/common/impl/printing.c — Glue layer that builds output buffers, invokes the parser, and handles final line output
• src/fastfetch.c — CLI handling that parses --format and --set-key options
• src/modules/*/*.c (e.g., src/modules/os/os.c) — Individual modules defining default format strings and populating FFformatarg arrays

These components form the complete format-string engine powering Fastfetch's customizable output.

Summary

• Fastfetch format strings are processed at runtime by ffParseFormatString in src/common/impl/format.c, not at compile time
• Modules expose data through FFformatarg arrays filled via the FF_PRINT_FORMAT_CHECKED macro in each module's source file
• Conditionals use {?var} for "if set" and {/var} for "if not set" logic to control output flow
• Colors via {#color} inject ANSI codes automatically disabled when piping output
• Truncation and padding support maximum widths (:), right-padding (<), left-padding (>), and ellipsis truncation (~)
• Environment variables and constants are accessible through the {$} syntax

Frequently Asked Questions

What file handles the main format string parsing in Fastfetch?

The core parsing logic resides in src/common/impl/format.c, specifically within the ffParseFormatString function. This file handles placeholder extraction, conditional evaluation, color injection, and string truncation. The function walks the input string character-by-character and dispatches to specialized handlers based on the prefix character found inside braces.

How do I conditionally display a value in a fastfetch format string?

Use the if-conditional syntax {?variable}content{?}. This prints "content" only if the variable is set and non-zero. For the inverse logic (print only if unset or zero), use the not-if conditional {/variable}content{/}. These conditionals are implemented in src/common/impl/format.c lines 46–84 and support nesting for complex output logic.

Can I use environment variables in fastfetch format strings?

Yes, using the {$VAR} syntax. For example, {$HOME} inserts the value of the $HOME environment variable. If the variable does not exist in the environment, the placeholder is rendered as literal text. You can also reference constants set via --set-constants using {${n}} where n is the constant index.

How do I escape curly braces in fastfetch output?

Use double braces {{ to render a single literal { character. This prevents the parser from treating the character as the start of a placeholder. There is no specific escape sequence for closing braces } as the parser only recognizes opening braces as special tokens.

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