When it appears
It renders inside a Git repository when Starship can resolve a branch or detached commit name.
Preview
Rendered from the starting configuration in a representative simulated environment.
starship — preview
on feat/live-preview
Starting configuration
[git_branch]
symbol = " "
truncation_length = 32
style = "bold purple"The configuration is compressed into the URL fragment and stays in your browser.
Key options
- formatstring
- The format for the module. Use '$branch' to refer to the current branch name.
- symbolstring
- A format string representing the symbol of git branch.
- stylestring
- The style for the module.
- truncation_lengthnumber
- Truncates a git branch to N graphemes.
- truncation_symbolstring
- The symbol used to indicate a branch name was truncated. You can use '' for no symbol.
- only_attachedboolean
- Only show the branch name when not in a detached HEAD state.
Format variables
- $symbol
- Mirrors the value of option symbol
- $branch
- The current branch name, falls back to HEAD if there's no current branch (e.g. git detached HEAD).
- $remote_name
- The remote name.
- $remote_branch
- The name of the branch tracked on remote_name.
Common adjustments
- Shorten long branch names with truncation_length and a visible truncation_symbol.
- Use only_attached when detached HEAD labels add more noise than value.
- Put remote variables in a conditional group so they disappear when no upstream exists.