---
title: "Starship"
url: https://perrotta.dev/2025/12/starship/
last_updated: 2025-12-27
---


After years using the default prompt from
[`grml-zsh-config`](https://grml.org/zsh/) (with minor modifications), I adopted
[starship](https://starship.rs/):

> The minimal, blazing-fast, and infinitely customizable prompt for any shell!

My [`~/.config/starship.toml`](https://github.com/thiagowfx/.dotfiles/blob/master/starship/.config/starship.toml) is meant to resemble the zsh prompt I've been using,
with minor tweaks and improvements:

```toml
# Minimal starship config matching grml prompt
format = "$status$sudo$username$hostname$directory$git_branch$git_state$git_status$line_break$character"
right_format = "$cmd_duration$jobs"
add_newline = true

[status]
disabled = false
format = "[$status ]($style)"
style = "bold red"

[username]
show_always = true
format = "[$user](bold green)"

[hostname]
ssh_only = true
trim_at = "."
format = "@$hostname"

[directory]
truncation_length = 40
truncate_to_repo = true
format = " [$path](bold) "

[git_branch]
symbol = ""
format = "[$symbol$branch]() "

[git_state]
format = "|[$state]()"

[git_status]
format = "[$conflicted$deleted$renamed$modified$staged$untracked$ahead_behind](red) "

[cmd_duration]
min_time = 2000
format = "[$duration](yellow) "

[jobs]
format = "[$number](cyan) "

[sudo]
disabled = false
format = "[🔓](red) "

[character]
success_symbol = "[❯](green)"
error_symbol = "[❯](red)"
```

My prompt:

```
thiago.perrotta .dotfiles master
❯

```

Details you cannot easily tell from above:

- display the exit code if it is non-zero, and make the ❯ symbol red
- omit the hostname when not in SSH (no need to see `thiagoperrotta-MacBook-Pro` all the time)
- display the command duration when a command took too long (>2s) to complete
  (right side)
- display the number of background jobs if any (right side)
- display a couple of git markers (e.g. pending pull, pending push, pending changes)
- display an icon when `sudo` / `doas` is cached
- separate prompts with a blank line (breathe!)
- colors!
- truncate the full directory path when inside a VCS repo

My `.zshrc` looks like this:

```shell
# Use starship prompt if available, otherwise customize grml prompt.
if command -v starship &> /dev/null; then
    prompt off
    eval "$(starship init zsh)"
else
    # Customize grml prompt: two lines, user in bold green
    zstyle ':prompt:grml:left:items:user' pre '%B%F{green}'
    zstyle ':prompt:grml:left:setup' items rc change-root user at host path vcs newline percent
fi
```

...gracefully degrade when `starship` is not installed, using my original
grml-derived zsh prompt.

**Side effect**: now `bash` has a similar prompt to `zsh`!