Configuration

Configuration File

You can customize albafetch through a configuration file. There are multiple locations for this file and once one is found, it will be the only one parsed. The files are searched for in the following order:

• $XDG_CONFIG_HOME/albafetch.conf
• $XDG_CONFIG_HOME/albafetch/albafetch.conf
• $HOME/.config/albafetch.conf
• $HOME/.config/albafetch/albafetch.conf
• /etc/xdg/albafetch.conf

A custom file can also be given using the --config argument.

Syntax

The config should contain entry = "value", pairs (using quotation marks is mandatory). During parsing, albafetch will look for the first string matching the entry (which you can find in the default config), then locate the next quotation mark, check whether there is another quotation mark following it and if so take the value between the two.

There are three different types of data that will be parsed:

• Strings: No more than N bytes between the quotation marks will be read, but every single one of those bytes will be used. These variables will be marked in the example config with a ; str [N] following the option.
• Integers: An integer smaller or equal to N will be parsed using the C standard atoi() function (use man 3 atoi for specific information). The provided value will always be treaded as unsigned (using something like -1 will therefore be treated as 2³²-1, 4294967295) These variables will be marked in the example config with a ; int [N] following the option.
• Booleans: The program will recognize anything different from "false" as "true". These variables will be marked in the example config with a ; bool following the option.

All of this means that AB"CboldDEF"whatever lol"wo"w will be parsed the exact same way as bold = "true", or bold"", but I would not recommend this as it makes everything less readable. I might also stop supporting this at any moment, so the specified syntax is the only one that's guaranteed to work. I might also make the parser stricter in the future and configs written this way might stop working entirely.

Also, any ~ that you may want to use will not get expanded to /home/username and will instead be parsed as it is. If you want to reference your home directory inside of this config file (e.g. to specify the path to a custom ascii art) you will have to do so manually.

A specific option that's worth spending some extra time talking about is ascii_art. This option expects the path to a file that contains a custom logo. Its syntax is really straight-forward: You can specify up to 40 lines you want to use as logo (which can not be longer than 256 bytes long, including the closing null character. Note that Unicode characters will be bigger than 1B), and eventually a color on the first line. Anything that's not recognized as a color ("colors" are defined as black, red, green, yellow, blue, purple, cyan, gray or white) Will be considered the first line of the logo.

This is what a logo file could look like:

blue
first_line 
second_line
third_line 
fourth_line

This file should not end with an empty line, and every logo line should be equally long (you can achieve this simply by adding spaces at the end of the shorter lines), or albafetch will have alignment problems. There is no way to add comments in this file, everything will be used as it is written (except some escape sequences, more about this further down).

You can find an example logo file in this repository, more specifically example_logo.txt.

The config can also contain an ordered array of the modules that you want albafetch to print. The array has a vastly different syntax in the config, as shown here:

modules = {
    "module1",
    "module2",
    "module3",
}

You can found a list of the accepted modules inside of the default config. Any other value will be considered as plain text (and will be printed as-is, with no label nor dash).

To parse this section, albafetch first locates a string matching modules in the config file, takes the part between the following curly braces, and reads the text between the following pairs of quotation marks. As for normal options, this allows some weird formats, like modules{"module1""module2""module3"}, but I also invite anyone to consider the parsing of similar strings undefined behavior.

Anything that doesn't match what the parser is looking for will be ignored, but the usage of explicit comments is encouraged: whatever stands between a ; or an # and the end of the line will not be read as part of the config. You can, however, still freely use # and ; in your config, as they will not be considered when enclosed in a string (between a pair of "). There is currently no way to use multi-line comments.

When albafetch parses a file (config or custom ascii art), it will also automatically unescape some escape sequences, like the following table shows:

File content	How it will be parsed
"\e"	'\033' (ANSI escape)
"\033"	'\033' (ANSI escape)
"\n"	'\n' (new line)
"\X"	'X' (everything else)

Since it might be useful, here are some of the most useful ANSI escape sequences (you can find a more complete list here)

Function	Escape
Reset	\e[0m
Bold	\e[1m
Black	\e[30m
Red	\e[31m
Green	\e[32m
Yellow	\e[33m
Blue	\e[34m
Purple	\e[35m
Cyan	\e[36m
White	\e[97m

Please note that these colors will be displayed as defined in the configuration of your terminal. You can check how a certain string will look using something like echo -e "\e[1mHello, \e[31mWorld\e[0m". These escape sequences may be placed at any point inside of your config or custom ascii art and they should get parsed correctly (as long as you stay inside of the size limits defined for each field). You can even use multiple inside a single line.