-
Notifications
You must be signed in to change notification settings - Fork 488
Format String Guide
A format string is a text string that contains placeholders for values. These placeholders begin with a '{', contain the name or index of the value, and end with a '}'.
For example:
"Values: {1} ({2})" with values "First" and "My second val" produces "Values: First (My second val)"
Format strings can contain placeholders in any order and multiple occurrences of the same placeholder.
When setting a format string from the command line that contains spaces, surround it with double quotes:
fastfetch --title-format "Hello, {user-name}"
Value indices can be meaningful named tags instead of numbers:
"--title-format '{user-name-colored}{at-symbol-colored}{host-name-colored}'"
This is equivalent to using numerical indices. See module-specific help for supported tags:
fastfetch -h title-format
You can specify a truncation length using the syntax '{arg:trunc-length}':
"--title-format '{user-name:5}'" → truncates user name to 5 characters
If 'trunc-length' is negative, an ellipsis (…) will be appended when truncated.
Note: String length is counted in raw bytes; multi-byte Unicode characters and ANSI escape codes may not be counted as expected.
Use '<' or '>' instead of ':' to set left or right padding:
"{user-name<20}" → left-aligned with spaces: "<user-name> "
"{user-name>20}" → right-aligned with spaces: " <user-name>"
Use '{~startIndex,endIndex}' to slice a string:
"{~0,5}" → first five characters
"{~-5,}" → last five characters
"{~2,-2}" → from third character to second-to-last character
Negative indices count backward from the end of the string. If an index is omitted, 0 is used.
You can reference constants and environment variables:
"{$NUM}" → reference a constant defined in `display.constants`
"{$ENV_VAR}" → reference an environment variable
If a value index is missing (empty placeholder: "{}"), an internal counter automatically assigns the next sequential value:
"Values: {} ({})" → equivalent to "Values: {1} ({2})"
Note that this counter only increments for empty placeholders:
"{2} {} {}" → second value, then first value, then second value again
A double open curly brace ("{{") will be printed as a single open curly brace ('{') and not treated as a placeholder.
To conditionally print content only when a variable is set:
"{?2} Second value: {2}{?}" → prints only if value 2 is set
To conditionally print content only when a variable is NOT set:
"{/2}Value not available{/}" → prints only if value 2 is NOT set
Example combining both:
"{?2}{2}{?}{/2}Second value fallback{/}"
To terminate formatting at any point, use "{-}".
To apply color to text, start a placeholder with '#' followed by terminal color codes:
"{#4;35}Colored Text{#}" → pink and underlined text
The escape sequence "\033[" at the start and 'm' at the end are automatically added.
"{#}" is equivalent to "{#0}" and resets all formatting to normal.
Named formats are also supported:
"{#underline_magenta}Colored Text{#}"
See fastfetch -h color for details about supported color codes.
If a format string evaluates to an empty value, the entire line will be omitted from the output.
This can be used to disable specific outputs:
"--host-format ' '" → disables host output
Note that using an empty string (e.g., "--host-format ''") would be treated as not set, and the built-in format would be used instead.
Format strings can also be used to set fixed values—simply use a string without any placeholders:
"--custom-format Preferred"