Index your code with Devin
DeepWiki

fastfetch-cli/fastfetch

Menu

Output Formatting and Display Options

Relevant source files

This document describes the output formatting and display configuration system in fastfetch. It covers the structure, configuration, and runtime behavior of the output pipeline, focusing on the FFOptionsDisplay system and its related code. This includes color schemes, key/value formatting, percentage bars, temperature/size/frequency formatting, and output modes (text, JSON, pipe).

Scope:

  • How output appearance is controlled via config files, command-line options, and environment variables.
  • The structure and fields of FFOptionsDisplay.
  • How formatting options are parsed and applied at runtime.
  • The mapping between user-facing options and code entities.
  • The mechanisms for customizing colors, separators, bars, and numeric formatting.

Not covered here:

Purpose and Role in the System

The output formatting and display options system is responsible for controlling the visual and structural aspects of fastfetch's output. It acts as the bridge between the configuration state (FFconfig), the format engine, and the final output system. It enables users to customize how information is presented, including:

  • Color schemes for keys, values, separators, and bars.
  • Key alignment, padding, and icon usage.
  • Numeric formatting for percentages, sizes, temperatures, and frequencies.
  • Output mode selection (plain text, JSON, pipe).
  • Bar and percentage visualization.
  • Error and status display.

This system is implemented primarily through the FFOptionsDisplay struct and its associated parsing and application logic.

Sources:
src/options/display.h src/options/display.c doc/json_schema.json src/common/percent.h src/common/percent.c src/common/temps.h src/common/temps.c

System Overview and Code Mapping

Below is a diagram mapping the main display and formatting configuration system to its code entities.

Diagram: "Display Options System and Code Entities"

Sources:
src/options/display.h src/options/display.c doc/json_schema.json src/common/percent.c src/common/temps.c src/common/format.c

Configuration Entry Points

Display and formatting options can be set via:

The main code entry points for parsing these options are:

SourceFunction/HandlerFile
JSON configffOptionsParseDisplayJsonConfigsrc/options/display.c
Command-line optionsffOptionsParseDisplayCommandLinesrc/options/display.c
JSON schemadoc/json_schema.jsondoc/json_schema.json

Sources:
src/options/display.c10-521 src/options/display.c533-9999 doc/json_schema.json

FFOptionsDisplay Structure

The FFOptionsDisplay struct holds all display and formatting options. It is a field of the global FFconfig struct and is referenced throughout the output pipeline.

Table: Key Fields in FFOptionsDisplay

Field NamePurposeExample Option(s)
colorKeysColor for module keys--color-keys, display.color
colorTitleColor for the title line--color-title
colorOutputColor for module output values--color-output
colorSeparatorColor for key-value separator--color-separator
brightColorUse bright colors for keys/title/logo--bright-color
keyValueSeparatorString between key and value--separator
keyTypeKey display type (string, icon, both, none)--key-type
keyWidthWidth for key alignment--key-width
keyPaddingLeftLeft padding for keys--key-padding-left
pipeDisable all escape sequences (plain output)--pipe
showErrorsShow errors in output--show-errors
disableLinewrapDisable terminal line wrapping--disable-linewrap
hideCursorHide cursor during output--hide-cursor
percentTypePercentage output type (number, bar, both, etc.)--percent-type
percentNdigitsDigits after decimal for percentages--percent-ndigits
percentColorGreenColor for "green" state in percentages--percent-color-green
percentColorYellowColor for "yellow" state in percentages--percent-color-yellow
percentColorRedColor for "red" state in percentages--percent-color-red
barCharElapsedCharacter for filled part of bar--bar-char-elapsed
barCharTotalCharacter for unfilled part of bar--bar-char-total
barBorderLeftLeft border string for bar--bar-border-left
barBorderRightRight border string for bar--bar-border-right
barColorElapsedColor for filled part of bar--bar-color-elapsed
barColorTotalColor for unfilled part of bar--bar-color-total
barColorBorderColor for bar borders--bar-color-border
barWidthWidth of percentage bars--bar-width
sizeBinaryPrefixBinary prefix type for sizes (IEC, SI, JEDEC)--size-binary-prefix
sizeNdigitsDigits after decimal for sizes--size-ndigits
sizeMaxPrefixMaximum size prefix (e.g., GiB, TiB)--size-max-prefix
sizeSpaceBeforeUnitSpace before size unit--size-space-before-unit
tempUnitTemperature unit (C, F, K)--temp-unit
tempNdigitsDigits after decimal for temperature--temp-ndigits
tempColorGreen/Yellow/RedColors for temperature ranges--temp-color-green etc.
tempSpaceBeforeUnitSpace before temperature unit--temp-space-before-unit
freqNdigitsDigits after decimal for frequency--freq-ndigits
freqSpaceBeforeUnitSpace before frequency unit--freq-space-before-unit
fractionNdigitsDigits after decimal for fractions--fraction-ndigits
fractionTrailingZerosKeep trailing zeros in fractions--fraction-trailing-zeros
noBufferDisable stdout buffering--no-buffer
constantsList of user-defined constants for format stringsdisplay.constants

Sources:
src/options/display.h35-94 doc/json_schema.json

Configuration: JSON Schema and Command-Line Mapping

Display options are defined in the JSON schema (doc/json_schema.json) and mapped to both config file fields and command-line arguments.

Diagram: "Display Option Mapping: Schema, Config, CLI, Struct"

Sources:
doc/json_schema.json src/options/display.c10-521 src/options/display.c533-9999

Color Customization

fastfetch supports extensive color customization for keys, values, separators, bars, and more. Colors can be set globally or per-module.

  • Color fields: colorKeys, colorTitle, colorOutput, colorSeparator, percentColorGreen, percentColorYellow, percentColorRed, barColorElapsed, barColorTotal, barColorBorder, tempColorGreen, tempColorYellow, tempColorRed
  • Color format: Named colors (e.g., "red", "light_blue"), ANSI codes, or hex codes (see Color Format Specification)
  • Pipe mode: When pipe is enabled, all color codes are suppressed for plain output.

Example:

Sources:
doc/json_schema.json src/options/display.c50-74 src/options/display.h38-41

Key and Value Formatting

  • Key display: Control whether keys are shown as strings, icons, both, or hidden (keyType).
  • Key width and padding: Align keys to a fixed width and add left padding (keyWidth, keyPaddingLeft).
  • Separator: Customize the string between key and value (keyValueSeparator).
  • Bright color: Enable or disable bright color for keys/title/logo (brightColor).

Example:

Sources:
doc/json_schema.json src/options/display.c437-471 src/options/display.h85-87

Percentage and Bar Formatting

fastfetch provides flexible options for displaying percentages and visual bars (e.g., for memory, disk, battery).

  • Type: Show as number, bar, both, colored, or monochrome (percentType)
  • Digits: Number of decimal digits (percentNdigits)
  • Width: Width of number and bar (percentWidth, barWidth)
  • Characters: Characters for filled/unfilled bar (barCharElapsed, barCharTotal)
  • Borders: Strings for bar borders (barBorderLeft, barBorderRight, etc.)
  • Colors: Colors for green/yellow/red states and bar parts
  • Thresholds: Define green/yellow/red cutoffs for coloring

Table: Percentage Type Flags

ValueMeaningDescription
1numShow percentage number
2barShow bar
3num + barShow both
6bar onlyBar only
9num-colorColored number
10bar-monochromeMonochrome bar

Example:

Sources:
doc/json_schema.json src/common/percent.h src/common/percent.c src/options/display.h77-83 src/options/display.c228-393

Numeric Formatting: Size, Temperature, Frequency, Fractions

fastfetch allows fine-grained control over how numeric values are formatted.

  • Size formatting:

    • Binary prefix type: IEC (KiB), SI (kB), JEDEC (KB) (sizeBinaryPrefix)
    • Max prefix: Limit to e.g., GiB, TiB (sizeMaxPrefix)
    • Digits: Number of decimals (sizeNdigits)
    • Space before unit (sizeSpaceBeforeUnit)

  • Temperature formatting:

    • Unit: Celsius, Fahrenheit, Kelvin (tempUnit)
    • Digits: Number of decimals (tempNdigits)
    • Color thresholds: Green/yellow/red (tempColorGreen, etc.)
    • Space before unit (tempSpaceBeforeUnit)

  • Frequency formatting:

    • Digits: Number of decimals (freqNdigits)
    • Space before unit (freqSpaceBeforeUnit)

  • Fraction formatting:

    • Digits: Number of decimals (fractionNdigits)
    • Trailing zeros: Always, never, or default (fractionTrailingZeros)

Example:

Sources:
doc/json_schema.json src/options/display.c99-162 src/options/display.c163-227 src/options/display.c481-515 src/options/display.h57-91

Output Modes

  • Text (default): Formatted, colored output for terminals.
  • Pipe: Plain output, disables all escape sequences and colors (pipe).
  • JSON: Machine-readable output (--format json or --json).

The output mode is auto-detected (e.g., disables colors if not writing to a TTY) or can be forced via options.

Sources:
src/data/help.json src/options/display.c41-42 src/options/display.h48

Error and Status Display

  • Show errors: Print errors inline with output (showErrors)
  • Stat: Show time usage for modules (stat)
  • Disable linewrap: Prevent terminal line wrapping (disableLinewrap)
  • Hide cursor: Hide cursor during output (hideCursor)

Sources:
src/options/display.c20-47 src/options/display.h47-56

Example: Customizing Output via Config

Sources:
doc/json_schema.json

How Formatting is Applied at Runtime

At runtime, the display options are referenced by the output and formatting functions. For example:

  • ffPercentAppendBar and ffPercentAppendNum use the percentage and bar options to render visual bars and numbers.
  • ffTempsAppendNum uses temperature formatting and color thresholds.
  • ffParseFormatString applies color, key, and value formatting as specified in FFOptionsDisplay.

Diagram: "Runtime Application of Display Options"

Sources:
src/common/percent.c src/common/temps.c src/common/format.c src/options/display.h

Summary

The output formatting and display options system in fastfetch provides a comprehensive and flexible mechanism for customizing the appearance and structure of output. It is implemented via the FFOptionsDisplay struct, which is populated from config files and command-line arguments, and is referenced throughout the output pipeline to control colors, formatting, and output modes.

For further details on the template/format string engine, see Format String System. For logo rendering, see Logo Rendering System.

Sources for this page:
src/options/display.h src/options/display.c doc/json_schema.json src/common/percent.h src/common/percent.c src/common/temps.h src/common/temps.c src/common/format.c src/data/help.json