starship/starship

Format string DSL

The mini-language Starship uses for format, right_format, continuation_prompt, profiles, every module's format field, every module's style field, and parts of [custom.<name>]. Implemented in src/formatter/; the grammar lives in src/formatter/spec.pest.

Syntax cheatsheet

Construct	Meaning
`$name`	Insert the value of variable `name`.
`${name.with.dots}`	Same, but for variables containing dots (e.g. `${custom.foo}`, `${env_var.SHELL}`).
`[content](style)`	Apply `style` (a style string) to `content`. `content` itself is a format string.
`(content)`	Conditional group: render `content` only if at least one `$variable` inside it produced non-empty output.
`\\`, `\$`, `\[`, `\]`, `$`, `$`	Literal brackets, parens, dollar signs, and backslashes.

Everything else is literal text. Newlines are literal.

Example breakdown

[$symbol(\($region\) )]($style)

Reading left to right:

[ ... ]( ... ) — text group; the inside is content, after the ] is style.
$symbol — module's symbol.
($$region$ ) — conditional group. The $ and $ are literal parentheses around $region. If $region is empty, the whole group disappears (and the leading space too).
$style — variable referring to the module's style.

So this prints ☁️ (us-east-1) when a region is set and just ☁️ when it isn't.

What variables are available

It depends on the format string's context:

In a module's format, the available variables are the ones the module exposes (e.g., $version, $symbol, $style for toolchain modules; $branch, $remote_branch, $remote_name for git_branch; etc.). The module's source file is the source of truth.
In the top-level format / right_format / profile, the available variables are the names of every module in ALL_MODULES, plus $all (expand to remaining modules in PROMPT_ORDER), plus $custom and $env_var (expand to user-defined entries), plus ${custom.<name>} and ${env_var.<name>} for individual entries.
In a style string, the only meaningful variable today is $style (the module's style) — you can chain into it from a parent module via [$x]($style).

Conditional groups in practice

The conditional collapses if every variable inside expanded to nothing:

( on [$symbol $branch]($style)\($remote_name/$remote_branch\) )

If neither remote is set, on main() becomes on main. To collapse the parens too, wrap them in their own conditional:

( on [$symbol $branch]($style) (\($remote_name/$remote_branch\)) )

Now the parens vanish entirely when there's no remote.

Style strings

Inside ( ... ) after a [ ... ], you write a style string (not a format string). Style strings are space-separated tokens parsed by parse_style_string in src/config.rs. See Configuration for the full token list.

A common pattern: [$content]($style) — let the module's style config dictate the color. This is more flexible than hard-coding [$content](red bold) because the user can override style = "..." once and have it apply.

Escaping

Escape any character that would otherwise be syntactic:

\$ for a literal $.
\[, \], $, $ for literal brackets/parens.
\\ for a literal backslash.

Inside map-substituted values (e.g. $version from the toolchain modules), Starship automatically escapes these characters in the produced string. The exception is [custom.<name>] with unsafe_no_escape = true, which trusts the command's output verbatim — this lets you produce dynamic styling like [$output](bold) from the command itself, but means you must trust the command not to inject DSL that breaks rendering.

Format string parsing

Parsing is done by pest at runtime (the grammar is parsed once at startup). The full grammar is small:

expression = _{ SOI ~ value* ~ EOI }
value      = _{ text | variable | textgroup | conditional }
variable   = { "$" ~ (variable_name | variable_scope) }
text       = { (string | escape)+ }
textgroup  = { "[" ~ format ~ "]" ~ "(" ~ style ~ ")" }
conditional= { "(" ~ format ~ ")" }

A bad format string produces a StringFormatterError::Pest. The renderer logs it and falls back to >. Within a module, a parse error returns None for that module — see src/formatter/string_formatter.rs.