返回

Starship 配置——在终端上显示 Git 状态、Python 虚拟环境、命令运行时间等

Starship 是一款跨平台的 shell 主题管理器，其支持 Zsh、Nushell、PowerShell 等。使用 Starship 可以在终端上显示 Git 状态、Python 虚拟环境、命令运行时间等。本文介绍了如何配置 Starship。

安装

Starship

Starship 官网 上列出了不同安装方式。本文仅介绍其中两种。

Windows

用 Scoop 安装：

Terminal window
scoop install starship

Linux/macOS

用 Cargo 编译并安装：

Terminal window
cargo install starship --locked

此外还需要将 Cargo 编译的二进制文件添加到 PATH，在 ~/.bashrc（Bash）或 ~/.zshenv（Zsh）中添加：

~/.zshenv
export PATH = "$HOME/.cargo/bin:$PATH"

Nerd Font

Starship 的许多主题都需要 Nerd Font 中的符号。所以需要安装带有 Nerd Font 补丁的字体。

注意

安装字体后还需要在终端中使用字体。如果使用 Windows 终端，字体可于 设置 > 配置文件 > 外观 > 字体 中设置。

Windows

Scoop 的 nerd-fonts 源中包含了许多字体的 Nerd Font 版本。所以首先添加该源：

Terminal window
scoop bucket add nerd-fonts

之后选择一款心仪的字体，例如 JetBrains Mono，并安装：

Terminal window
scoop install jetbrainsmono-nf-mono

字体后缀

  • nf：Nerd Fonts 字体
  • mono：等宽字体

具体含义可参考 Nerd Fonts 的 README。

Ubuntu (Linux)

从 Nerd Fonts 官网 上下载心仪的字体，然后将其中字体文件解压到 ~/.local/share/fonts 即可 1。带 Mono 后缀的为等宽字体。

配置

Shell 配置

安装 Starship 后还需要配置 shell，官网 上介绍了不同 shell 的设置，本文仅介绍 Nushell 和 Zsh 的配置。

Nushell

Nushell 的情况下需要在 $nu.env-path 环境文件中添加以下内容来生成 Starship 初始化脚本：

env.nu
mkdir ~/.cache/starship
starship init nu | save -f ~/.cache/starship/init.nu

之后还需要在 $nu.config-path 配置文件中加载脚本：

config.nu
use ~/.cache/starship/init.nu

~/.cache/starship/init.nu 可以更改为任意路径。

Zsh

在 ~/.zshrc 中添加：

.zshrc
eval "$(starship init zsh)"

Starship 配置

默认情况下，Starship 的 配置文件 位于 ~/.config/starship.toml。如果不想从零开始配置，Starship 也提供了许多 预设主题。选好主题后运行以下命令即可使用：

Terminal window
starship preset 主题-名称 -o ~/.config/starship.toml

注意

此命令会覆盖当前配置文件！

因为组件太多会拖慢 Shell，所以笔者推荐使用简单的主题，例如 Bracketed Segments。

Bracketed Segments 主题，图片来自 Starship 文档
Bracketed Segments 主题，图片来自 Starship 文档

笔者的配置

部分符号为 Nerd Font 字体中的符号，所以可能在浏览器中显示不出来。

starship.toml
96 collapsed lines
"$schema" = "https://starship.rs/config-schema.json"


format = """
$username\
$hostname \
$directory \
$git_branch\
$git_status\
$java\
$python\
$conda\
$cmd_duration\


$line_break\
$character\
"""


add_newline = false


[cmd_duration]
    min_time = 2000
    style = "fg:white"
    format = "[ ⏱️ $duration]($style)"
    show_notifications = false
    min_time_to_notify = 60_000


[character]
    disabled = false
    format = "$symbol "
    error_symbol = "[✗](fg:red)"
    success_symbol = "[➜](fg:green)"


[username]
    show_always = true
    style_user = "bold white"
    style_root = "bold yellow"
    format = "[$user]($style)"


[hostname]
    disabled = false
    ssh_only = false
    ssh_symbol = "🌏 "
    style = "bold green"
    format = "[@$hostname]($style)"
    trim_at = ".companyname.com"


[directory]
    style = "cyan bold"
    format = "[$path]($style)[$read_only]($read_only_style)"
    truncation_length = 3


    [directory.substitutions]
        "Documents" = "󰈙"
        "Downloads" = ""
        "Music" = ""
        "Pictures" = ""


[git_branch]
    symbol = ""
    style = "bold purple"
    format = '\[[$symbol $branch]($style)\]'


[git_status]
    style = "red bold"
    format = '([\[$all_status$ahead_behind\]]($style))'
    conflicted = ""
    ahead = "⇡${count}"
    diverged = "⇕⇡${ahead_count}⇣${behind_count}"
    behind = "⇣${count}"
    up_to_date = "✓"
    untracked = "?"
    stashed = "󰏗"
    modified = ""
    staged = "+"
    renamed = "󰘎"
    deleted = "✘"


[fill]
    symbol = " "


[java]
    symbol = ""
    style = "red"
    version_format = "v$raw"
    format = '\[[$symbol ($version)]($style)\]'


[python]
    symbol = ""
    style = "yellow bold"
    version_format = "v$raw"
    format = '\[[$symbol $pyenv_prefix($version)( \($virtualenv\))]($style)\]'


[conda]
    style = "green bold"
    symbol = "🅒"
    format = '\[[$symbol $environment]($style)\]'

自定义

显然，读到这里的读者并不满足于预设主题，所以本段会更深入地介绍 Starship 的配置。

提示符格式

Starship 的提示符格式由 starship.toml 中的 format 字段决定，默认显示所有组件 2。例如以下配置对应的提示符为 用户名 主机名 路径名。

starship.toml
format = "$username $hostname $directory"

其中组件的格式为 $组件名称。此外，组件很多时可以使用多行字符串 """ 和 \ 来忽略换行：

starship.toml
format = """
$username \
$hostname \
$directory"""

注意

format 必须在所有组件之前定义，否则其会被当作组件的 format 字段 3。

starship.toml
format = ...


[组件1]
...


[组件2]
...

组件格式

Starship 的组件通常遵循以下格式：

starship.toml
[组件名称]
disable = false
format = "[你好]($style) $symbol"
symbol = "🌐"
style = "bold green"

字段含义：

  • disable：是否禁用组件，false 为启用
  • format：组件格式，类似前面的 format 字段
  • symbol：组件对应的符号，可在 format 中作为 $symbol 使用。如果想添加图标，可以使用 Emoji 或者在 Nerd Font 网站里查找符号。
  • style：内容样式，可在 format 中作为 [内容]($style) 使用。也可以直接使用 [内容](bold green)，具体可参考 文档。

部分组件的配置可能会有所不同，例如 username 中 style 被 style_user 和 style_root 取代。

Starship 组件推荐

必要

可选

  • username：用户名
  • hostname：主机名
  • cmd_duration：命令运行时间，可以在命令运行完后显示通知
  • 各种编程语言对应的组件，可显示版本、虚拟环境等。

其他组件可以从 Starship 的 文档 上找到。由于中文文档翻译不全，笔者建议参考 英文版。当然，也可以直接参与 Starship 文档的 翻译工作。

Footnotes

  1. How do I install fonts? https://askubuntu.com/a/3706 ↩

  2. 默认提示符格式，Starship，https://starship.rs/zh-CN/config/#%E9%BB%98%E8%AE%A4%E6%8F%90%E7%A4%BA%E7%AC%A6%E6%A0%BC%E5%BC%8F ↩

  3. TOML v1.0.0，https://toml.io/en/v1.0.0#table ↩