Special modules

A handful of modules don't fit the "detect a project, show its version" mold. They are general-purpose primitives the user can wire into the prompt.

custom

Source: src/modules/custom.rs (~820 lines). Config: src/configs/custom.rs.

User-defined modules under [custom.<name>]. Each custom module specifies a detection rule and a command:

[custom.foo]
detect_extensions = ["md"]
command = "echo hello"
when = true
format = "[$output]($style) "

Detection options:

• detect_files, detect_extensions, detect_folders — same as built-in modules.
• when = true — always run.
• when = "cmd" — run a command; render only if exit status is 0. The command shell is configurable via shell (default: sh/cmd.exe).
• os = "linux" | "macos" | "windows" | "unix" — restrict to OS family.
• require_repo = true — only run inside a VCS repository.

Variables exposed to the format string:

• $output — stdout of command (with command_timeout enforced).
• $symbol and $style — same as everywhere.

Custom modules handle their own disabled check because they live in a TOML map ([custom.<name>]) rather than a top-level table. They are dispatched by print.rs via the special handling in handle_module for paths starting with custom.. See Custom modules for end-user docs.

env_var

Source: src/modules/env_var.rs. Config: src/configs/env_var.rs.

Either a single env var (using the top-level [env_var] table) or multiple env vars (using [env_var.<name>]):

[env_var]
variable = "USER"
default = "anonymous"
format = "[$env_value]($style) "

[env_var.SHELL]
format = "[$env_value]($style) "

The dispatcher in print::handle_module handles both forms. env_var.<name> is also accessible by name in custom format strings (e.g., format = "${env_var.SHELL}$character").

fill

Source: src/modules/fill.rs. Config: src/configs/fill.rs.

Pads the rest of the current line with a repeated string until the terminal width. Useful for two-column prompts where the right side should be flush with the right edge:

format = "$directory$fill$git_branch"
[fill]
symbol = "·"

The implementation lives mostly in src/segment.rs's FillSegment plus the rendering math in src/print.rs's ansi_line. fill segments are special: they are placed in the segment list, then the renderer divides remaining horizontal space between them at print time. The terminal width comes from terminal_size::terminal_size() (or --terminal-width=… from the init script).

line_break

Source: src/modules/line_break.rs. Config: src/configs/line_break.rs.

Emits a literal \n. By default, line_break appears between the modules above the second prompt line and the modules below it (look at PROMPT_ORDER to see exactly where). The right prompt strips newlines, so this is a no-op for Target::Right.

package

Source: src/modules/package.rs (~1.7K lines). Config: src/configs/package.rs.

Although named singular, package is a polyglot module that reads the version field from a wide range of package manifests and shows it as the project's "version". Supported formats include:

Manifest	Source
Cargo.toml	cargo package version
package.json	npm/yarn/pnpm package version (skipped for private: true unless overridden)
composer.json	PHP Composer
pyproject.toml	Poetry / PDM / Setuptools / Hatch (the tool.poetry, project, etc. sections)
setup.cfg / setup.py	Older Python projects
pubspec.yaml	Dart
gradle.properties, build.gradle.kts	Gradle (with optional Kotlin DSL parsing)
pom.xml	Maven (parsed via quick-xml)
mix.exs	Elixir
Project.toml	Julia
*.cabal	Haskell
meson.build	Meson
shard.yml	Crystal
*.cs (older <Version> tags), *.csproj, Directory.Build.props	.NET
Chart.yaml	Helm
helm/v3.yaml, helmfile.yaml	Helm extras
Cargo.toml (workspace inheritance)	Resolved via versions crate

There is a TODO at the top of module(context) listing a few formats not yet covered (Flit, PDM, Setuptools edge cases). The module uses versions::Version for normalization and VersionFormatter for display.

Why these modules live in special places

custom and env_var use dotted module names (custom.foo, env_var.SHELL) to allow many user-defined instances. The dispatcher in print::handle_module handles them specially:

} else if module.starts_with("custom.") || module.starts_with("env_var.") {
    modules.extend(modules::handle(module, context));
} else if matches!(module, "custom" | "env_var") {
    // Iterate over [<module>.*] in the user's config and dispatch each.
}

This is why the format string $custom expands to all configured custom modules, while ${custom.foo} renders just one.

Entry points for modification

• To add a new package-manifest format to package, write a get_<thing>_package_version function in src/modules/package.rs and register it in get_version.
• To extend custom's detection or output, edit src/modules/custom.rs. The exec_when and exec_command helpers handle process spawning and timeouts.
• To change the fill width math, edit ansi_line in src/print.rs.