Rush reads interactive configuration from Rush scripts.
Interactive startup sources configuration in the order below. Defaults embedded in the rush binary load first, so every later file can override them. Missing files are skipped silently.
embedded default configuration (ships inside the rush binary) $ENV $sysconfdir/rush/profile.rush (login shells only) $XDG_CONFIG_HOME/rush/profile.rush (login shells only) $sysconfdir/rush/config.rush $XDG_CONFIG_HOME/rush/config.rush
Before reading $ENV, Rush applies shell parameter expansion to its value, so paths such as $HOME/.rushrc and ${ENV_DIR}/startup.rush are resolved before the file is sourced. Rush does not apply field splitting or pathname expansion to the resulting startup pathname.
User paths fall back to $HOME/.config/rush/ when $XDG_CONFIG_HOME is unset. $sysconfdir is fixed at build time: it defaults to etc inside the install prefix, and packagers set it to /etc with zig build -Dsysconfdir=/etc.
POSIX leaves a non-absolute expanded $ENV pathname unspecified; Rush currently accepts it relative to the current working directory. Rush is not intended to be installed setuid/setgid and does not add a differing-real/effective-ID suppression layer around $ENV. Point $ENV at a trusted file and avoid group- or world-writable startup files or containing directories.
The embedded defaults define the default prompt, colorized ls, grep, and diff functions (color flags are probed once per session and only colorize terminals), and ll and la abbreviations for ls -lh and ls -lAh. Redefine, unset -f, or abbr --erase any of them in a later file to opt out.
Use abbr for fish-style interactive text expansion in the line editor.
abbr gs 'git status' abbr ga 'git add' abbr gc 'git commit' abbr --list abbr --erase gs
Abbreviations expand only while editing an interactive command line. When the command word exactly matches an abbreviation, accepting the word or line with space, Enter, or Tab rewrites the buffer to the expanded command so you can inspect or edit it before execution. Tab expands first, then runs completion for the expanded command.
abbr is different from alias. An abbreviation is editor text expansion and does not change script execution. An alias is shell command aliasing and is expanded by the shell when scripts run. Normal alias definitions do not expand in the editor.
Place abbr commands in your Rush configuration file to persist them across interactive sessions.
Interactive editor colors are configured with lowercase shell variables. Values are comma-separated style options, so normal shell expansion works before Rush stores the variable.
rush_style() {
if test "$rush_color_scheme" = light; then
accent=blue
muted=black
flash='fg=white,bg=black'
else
accent=cyan
muted=bright-black
flash='fg=black,bg=white'
fi
directory_color=$(color dim "${rush_color_blue-#0000ff}" 20)
rush_style_completion_directory="fg=$directory_color"
rush_style_completion_selected="fg=$accent,bold"
rush_style_completion_description="fg=$muted,dim"
rush_style_completion_flash="$flash"
rush_style_history_match='fg=yellow,bold'
rush_style_autosuggestion='dim'
rush_style_diagnostic_error='ul=curly,ul_color=red'
}
If rush_style is defined, Rush calls it once during interactive startup and again when the terminal reports a color-scheme or palette change. Before each color-scheme call, Rush sets the Rush-owned rush_color_scheme variable to dark, light, or unknown. When the terminal reports colors, Rush sets rush_color_foreground, rush_color_background, and rush_color_black, rush_color_red, rush_color_green, rush_color_yellow, rush_color_blue, rush_color_magenta, rush_color_cyan, and rush_color_white to #rrggbb values. These RGB variables are only defined after the terminal reports them, so configs can provide their own fallbacks with normal shell expansion. Normal commands do not call rush_style; Rush reads the current rush_style_* variables before each prompt, so assignments made by commands take effect on the next prompt.
Supported options are fg=<color>, bg=<color>, ul=<style>, ul_color=<color>, bold, dim, italic, reverse, and strike. Underline styles are none, single, double, curly, dotted, and dashed.
Colors use the same names as prompt colors: default, black, red, green, yellow, blue, magenta, cyan, white, their bright- variants, index:N or N for 256-color palette entries, and #rrggbb truecolor values.
The color builtin can derive truecolor values for dynamic styles. color dim COLOR PERCENT blends a #rrggbb color toward black by PERCENT; color blend COLOR COLOR PERCENT blends the first color toward the second by PERCENT. Invalid color input exits with status 2, writes a diagnostic to stderr, and writes nothing to stdout; if that produces an invalid rush_style_* value, Rush falls back to the default style for that role.
Available style variables are rush_style_completion_selected, rush_style_completion_directory, rush_style_completion_option, rush_style_completion_variable, rush_style_completion_function, rush_style_completion_file, rush_style_completion_description, rush_style_completion_flash, rush_style_history_match, rush_style_autosuggestion, and rush_style_diagnostic_error. Invalid style values are ignored and the default for that role is used.
Rush ships a default prompt: the current directory in blue, the Git branch in yellow with a • marker when the worktree is dirty and ↑/↓ commit counts against the upstream, and a $ that turns red when the previous command failed.
Define rush_prompt in your configuration to replace it.
rush_prompt() { prompt segment --fg blue "$(prompt_pwd)" prompt text ' $ ' }
The prompt command is only available while Rush is rendering the prompt.
prompt text TEXT... prompt segment [OPTIONS] TEXT... prompt newline
prompt text appends plain text. prompt segment appends styled text. prompt newline starts a new prompt line.
--fg COLOR --bg COLOR --bold --dim --italic --underline --blink --reverse --strikethrough
Colors may be named colors, 256-color indexes, or RGB hex values.
blue
bright-blue
index:236
'#7aa2f7'
prompt_pwd [-d N] [-D N] # current directory, with $HOME shortened to ~ prompt_duration # previous command duration
prompt_pwd optionally shortens path components like fish. -d/--dir-length keeps the first N characters of each component (0, the default, disables shortening; a leading dot is preserved). -D/--full-length-dirs keeps the last N components at full length (default 1).
prompt_pwd # ~/repos/rush prompt_pwd -d 1 # ~/r/rush prompt_pwd -d 1 -D 2 # ~/repos/rush
Prompts should stay fast. Use the async prompt helpers for clocks, Git status, and other data that may change while the editor is waiting for input. Background work requests a safe redraw with prompt repaint; Rush rerenders the prompt and input line through the line editor.
prompt repaint prompt refresh --interval MS prompt_time FORMAT prompt_async KEY --ttl MS -- COMMAND... event prompt FUNCTION event preexec FUNCTION event postexec FUNCTION event variable FUNCTION interval NAME --interval MS FUNCTION
prompt repaint is the low-level redraw primitive for hooks and hidden refresh jobs. It schedules a prompt redraw when Rush is editing a command line and does not write prompt or input bytes directly.
prompt refresh --interval MS asks Rush to rerender the prompt periodically while the editor is idle. Timers are suspended while a foreground command is running.
prompt_time FORMAT formats the current time using zeit. Both strftime formats and Go-style layouts are supported.
rush_prompt() { prompt segment --fg yellow "$(prompt_time %H:%M:%S)" prompt refresh --interval 1000 prompt text ' $ ' }
prompt_async returns cached stdout immediately. When the cache is missing or stale, Rush starts COMMAND as a hidden refresh and returns the old cached value, or nothing if no value has been cached yet. When the hidden command exits, Rush automatically requests a safe prompt redraw; the next render sees the fresh cached stdout. You do not need to call prompt repaint after prompt_async. Cache entries are keyed by the current directory plus the explicit key. Duplicate refreshes for the same key are coalesced. Stderr is suppressed by default, and hidden refreshes preserve the interactive last status.
rush_prompt() { prompt segment --fg bright-blue "$(prompt_pwd)" git_branch="$(prompt_async git-branch --ttl 5000 -- git branch --show-current)" if test "$git_branch" != ""; then prompt text ' ' prompt segment --fg green "$git_branch" fi prompt text ' $ ' }
Save $? before running other commands in a prompt if you want to display the previous command status.
rush_prompt() { status="$?" if test "$status" != 0; then prompt segment --fg red "status $status" prompt text ' ' fi prompt segment --fg bright-blue "$(prompt_pwd)" prompt text ' $ ' }
event registers lower-level hooks for advanced prompt setups. Prompt hooks run before each prompt render. Preexec and postexec hooks run around foreground commands. Variable hooks run after variable changes and receive the variable name. Named intervals run while the editor is idle and receive the interval name.
on_prompt() { # Update cheap prompt variables before rendering. } on_variable() { if test "$1" = PWD; then prompt repaint fi } on_clock() { CLOCK="$(date +%H:%M:%S)" prompt repaint } event prompt on_prompt event variable on_variable interval clock --interval 1000 on_clock
Prefer prompt_async, timers, and hooks over slow synchronous command substitutions in rush_prompt. They keep prompt rendering responsive and route redraws through prompt repaint instead of writing to the terminal from background contexts.
If rush_prompt is not defined, Rush uses PS1. Rush initializes PS1 to $ and PS2 to > for interactive shells. The default prompt is a rush_prompt function, so unset it to use a plain PS1 prompt.
unset -f rush_prompt PS1='rush$ ' PS2='> '
File: $HOME/.config/rush/config.rush
rush_prompt() { prompt segment --fg bright-blue "$(prompt_pwd)" if test "$(prompt_duration)" != ""; then prompt text ' ' prompt segment --dim "$(prompt_duration)" fi prompt text ' $ ' }
Configuration is early. Expect changes.