Overrides and custom rows

Any built-in row can be given a name of your own, or text or a command's output in place of what the machine reports. You can also add rows of your own. Both are plain config.

modules = ["os", "kernel", "uptime", "custom", "shell"]

[overrides.os]
label = "Distro"                  # the name shown for the row

[overrides.kernel]
value = "my-own-kernel 1.0"       # shown instead of what the machine reports

[overrides.uptime]
label = "Up"
command = "uptime -p"             # the first line this prints is the value

[[custom]]                        # a row of your own, from text or a command
label = "Public IP"
command = "curl -s --max-time 1 ifconfig.me"

[[custom]]
label = "Editor"
value = "helix"

Overrides#

An override is a table named for a module: [overrides.os], [overrides.uptime] and so on. It has up to three keys:

Each is optional, but an override has to say at least one, and value and command are alternatives: give one, not both.

Renaming a row#

A rename is only the name. The row keeps its icon, its place and its live updates.

[overrides.cpu]
label = "Processor"

A rename shows wherever a style prints a name. A style that draws an icon in its place (iconic, and minimal with icons = true) shows no name to change, and tree prints fixed short names, so a rename is not visible there. The sections headings are fixed too.

Replacing a value#

A value or command is shown as a plain line in every style, so the usage bars and figures a style would draw for a memory or disk row are replaced by your text.

[overrides.memory]
value = "plenty"

Such a row is not refreshed by live: it is no longer the machine's reading, so a refresh must not write it back over your text.

A module the machine cannot read, such as battery on a desktop, still shows your text. You wrote the row, so it is yours to have wherever you run it.

Custom rows#

[[custom]] adds rows of your own. They appear where custom stands in modules, so modules = ["os", "custom", "kernel"] puts them between the two. Each has a label and either a value or a command:

[[custom]]
label = "Owner"
value = "Ada"

[[custom]]
label = "Branch"
command = "git -C ~/projects/site branch --show-current"

A row with an empty label is skipped, and custom must be in modules for the rows to show. Only the styles that list rows freely show them: classic, boxed, card and minimal. The fixed-block styles (tree, sections, chips, iconic) have no place for them.

The short form still works:

custom = [{ label = "Owner", value = "Ada" }]

Commands#

A command is run with sh -c, so pipes and && work.

• It runs with your privileges, like anything in your shell's startup files. animfetch only runs commands you wrote in your own config.
• Only the first non-empty line is used. Control characters are removed, so an escape sequence in the output cannot recolour or move the pane. Long lines are cut.
• The exit status is not asked about. A command that printed what you wanted and then complained is still the answer.
• They run once, at startup, all together, so the wait is the slowest command rather than the sum.
• A command that prints nothing, or takes longer than command_timeout seconds, leaves its row out. The default is 1.0, at most 10.

command_timeout = 2.0

Keep commands quick. Every one of them is on the path to your prompt appearing when animfetch --pin starts with your shell.

Mistakes#

A mistake is reported with its line number and the config is not used, like any other config error:

animfetch: ~/.config/animfetch/config.toml:7: it changes nothing: give a `label`, a `value` or a `command`

The things it catches: an unknown module name, a value together with a command, an empty [overrides.os] table, an empty label, and overriding colors or custom, which are not a named row.