7b09c86b0f
* docs: Update git_status module docs Have updated the configuration docs for the `git_status` to remove a non-existing option and to add an example for how to achieve the same effect as with the new format strings. * Add git_status changes to migration guide Have added the change to the sync count to the migration guide. I also corrected a few typos in the configuration. |
||
---|---|---|
.. | ||
README.md |
Migrating to v0.45.0
Starship v0.45.0 is a release containing breaking changes, in preparation for the big v1.0.0. We have made some major changes around how configuration is done on the prompt, to allow for a greater degree of customization.
This guide is intended to walk you through the breaking changes.
prompt_order
has been replaced by a root-level format
Previously to v0.45.0, prompt_order
would accept an array of module names
in the order which they should be rendered by Starship.
Starship v0.45.0 will instead be accepting a format
value, allowing for customization of the prompt outside of the modules themselves.
Example pre-v0.45.0 configuration
prompt_order = [
"username",
"hostname",
"directory",
"git_branch",
"git_commit",
"git_state",
"git_status",
"cmd_duration",
"custom",
"line_break",
"jobs",
"battery",
"time",
"character",
]
Example v0.45.0 configuration
format = """\
$username\
$hostname\
$directory\
$git_branch\
$git_commit\
$git_state\
$git_status\
$cmd_duration\
$custom\
$line_break\
$jobs\
$battery\
$time\
$character\
"""
Module prefix
and suffix
will be replaced by format
Previously to v0.45.0, some modules would accept prefix
and/or suffix
in order to stylize the way that modules are rendered.
Starship v0.45.0 will instead be accepting a format
value, allowing for further
customization of how modules are rendered. Instead of defining a prefix and suffix
for the context-based variables, the variables can now be substituted from within
a format string, which represents the module's output.
Example pre-v0.45.0 configuration
[cmd_duration]
prefix = "took "
Example v0.45.0 configuration
[cmd_duration]
# $duration – The command duration (e.g. "15s")
# $style – The default style of the module (e.g. "bold yellow")
format = "took [$duration]($style)"
Affected Modules
Character
Deprecated Property | Replacement |
---|---|
symbol |
success_symbol |
use_symbol_for_status |
error_symbol |
style_success |
success_symbol |
style_failure |
error_symbol |
Changes to the Default Configuration
[character]
-- symbol = "❯"
-- error_symbol = "✖"
-- use_symbol_for_status = true
-- vicmd_symbol = "❮"
++ success_symbol = "[❯](bold green) "
++ error_symbol = "[❯](bold red) "
++ vicmd_symbol = "[❮](bold green)"
Previously, the use_symbol_for_status
property was used to configure the prompt to show the error_symbol
when the last command resulted in a non-zero status code.
With the release of v0.45.0, we now always use error_symbol
after non-zero status codes, unifying use_symbol_for_status
and error_symbol
properties.
To configure the prompt to use the older use_symbol_for_status = true
configuration, add the following to your config file:
[character]
error_symbol = "[✖](bold red) "
Command Duration
Deprecated Property | Replacement |
---|---|
prefix |
format |
Changes to the Default Configuration
[cmd_duration]
-- prefix = "took "
++ format = "took [$duration]($style)"
Directory
Deprecated Property | Replacement |
---|---|
prefix |
format |
Changes to the Default Configuration
[directory]
-- prefix = "in "
++ format = "[$path]($style)[$lock_symbol]($lock_style)"
Environment Variable
Deprecated Property | Replacement |
---|---|
prefix |
format |
suffix |
format |
Changes to the Default Configuration
[env_var]
-- prefix = ""
-- suffix = ""
++ format = "with [$env_value]($style) "
Git Commit
Deprecated Property | Replacement |
---|---|
prefix |
format |
suffix |
format |
Changes to the Default Configuration
[git_commit]
-- prefix = "("
-- suffix = ")"
++ format = "[\\($hash\\)]($style) "
Git Status
Deprecated Property | Replacement |
---|---|
prefix |
format |
suffix |
format |
show_sync_count |
format |
Changes to the Default Configuration
[git_status]
-- prefix = "["
-- suffix = "]"
-- show_sync_count = false
++ format = "([$all_status$ahead_behind] )"
Previously, the show_sync_count
property was used to configure the prompt to
show the number of commits the branch was ahead or behind the remote branch.
With the release of v0.45.0, this has been replaced with the
To configure the prompt to use the older show_sync_count = true
configuration, set the following to your config file:
[git_status]
ahead = "⇡${count}"
diverged = "⇕⇡${ahead_count}⇣${behind_count}"
behind = "⇣${count}"
Hostname
Deprecated Property | Replacement |
---|---|
prefix |
format |
suffix |
format |
Changes to the Default Configuration
[hostname]
-- prefix = ""
-- suffix = ""
++ format = "[$hostname]($style) in "
Singularity
Deprecated Property | Replacement |
---|---|
label |
format |
prefix |
format |
suffix |
format |
Changes to the Default Configuration
[singularity]
-- prefix = ""
-- suffix = ""
++ format = "[$symbol\\[$env\\]]($style) "
Time
Deprecated Property | Replacement |
---|---|
format |
time_format |
Changes to the Default Configuration
[time]
-- format = "🕙[ %T ]"
++ time_format = "%T"
++ format = "at 🕙[$time]($style)
Custom Commands
Deprecated Property | Replacement |
---|---|
prefix |
format |
suffix |
format |
Changes to the Default Configuration
[custom.example]
-- prefix = ""
-- suffix = ""
++ format = "[$symbol$output]($style) "