docs: add a migration guide for the format string changes (#1624)
* Start writing migration guide * Add prefix/suffix migration to guide * Update docs/migrating-to-0.45.0/README.md Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Update docs/migrating-to-0.45.0/README.md Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Add missing quote * Detail the modules affected by the change * Document character and time migration Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
This commit is contained in:
Matan Kushner
GitHub
parent
a245d54cdb
commit
17687be1cb
|
|
@ -0,0 +1,255 @@
|
|||
# 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**
|
||||
|
||||
```toml
|
||||
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**
|
||||
|
||||
```toml
|
||||
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**
|
||||
|
||||
```toml
|
||||
[cmd_duration]
|
||||
prefix = "took "
|
||||
```
|
||||
|
||||
**Example v0.45.0 configuration**
|
||||
|
||||
```toml
|
||||
[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**
|
||||
|
||||
```diff
|
||||
[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:
|
||||
|
||||
```toml
|
||||
[character]
|
||||
error_symbol = "[✖](bold red) "
|
||||
```
|
||||
|
||||
#### Command Duration
|
||||
|
||||
| Deprecated Property | Replacement |
|
||||
| ------------------- | ----------- |
|
||||
| `prefix` | `format` |
|
||||
|
||||
**Changes to the Default Configuration**
|
||||
|
||||
```diff
|
||||
[cmd_duration]
|
||||
-- prefix = "took "
|
||||
++ format = "took [$duration]($style)"
|
||||
```
|
||||
|
||||
#### Directory
|
||||
|
||||
| Deprecated Property | Replacement |
|
||||
| ------------------- | ----------- |
|
||||
| `prefix` | `format` |
|
||||
|
||||
**Changes to the Default Configuration**
|
||||
|
||||
```diff
|
||||
[cmd_duration]
|
||||
-- prefix = "in "
|
||||
++ format = "[$path]($style)[$lock_symbol]($lock_style)"
|
||||
```
|
||||
|
||||
#### Environment Variable
|
||||
|
||||
| Deprecated Property | Replacement |
|
||||
| ------------------- | ----------- |
|
||||
| `prefix` | `format` |
|
||||
| `suffix` | `format` |
|
||||
|
||||
**Changes to the Default Configuration**
|
||||
|
||||
```diff
|
||||
[cmd_duration]
|
||||
-- prefix = ""
|
||||
-- suffix = ""
|
||||
++ format = "with [$env_value]($style) "
|
||||
```
|
||||
|
||||
#### Git Commit
|
||||
|
||||
| Deprecated Property | Replacement |
|
||||
| ------------------- | ----------- |
|
||||
| `prefix` | `format` |
|
||||
| `suffix` | `format` |
|
||||
|
||||
**Changes to the Default Configuration**
|
||||
|
||||
```diff
|
||||
[cmd_duration]
|
||||
-- prefix = "("
|
||||
-- suffix = ")"
|
||||
++ format = "[\\($hash\\)]($style) "
|
||||
```
|
||||
|
||||
#### Git Status
|
||||
|
||||
| Deprecated Property | Replacement |
|
||||
| ------------------- | ----------- |
|
||||
| `prefix` | `format` |
|
||||
| `suffix` | `format` |
|
||||
|
||||
**Changes to the Default Configuration**
|
||||
|
||||
```diff
|
||||
[cmd_duration]
|
||||
-- prefix = "["
|
||||
-- suffix = "]"
|
||||
++ format = "([$all_status$ahead_behind] )"
|
||||
```
|
||||
|
||||
#### Hostname
|
||||
|
||||
| Deprecated Property | Replacement |
|
||||
| ------------------- | ----------- |
|
||||
| `prefix` | `format` |
|
||||
| `suffix` | `format` |
|
||||
|
||||
**Changes to the Default Configuration**
|
||||
|
||||
```diff
|
||||
[cmd_duration]
|
||||
-- prefix = ""
|
||||
-- suffix = ""
|
||||
++ format = "[$hostname]($style) in "
|
||||
```
|
||||
|
||||
#### Singularity
|
||||
|
||||
| Deprecated Property | Replacement |
|
||||
| ------------------- | ----------- |
|
||||
| `label` | `format` |
|
||||
| `prefix` | `format` |
|
||||
| `suffix` | `format` |
|
||||
|
||||
**Changes to the Default Configuration**
|
||||
|
||||
```diff
|
||||
[cmd_duration]
|
||||
-- prefix = ""
|
||||
-- suffix = ""
|
||||
++ format = "[$symbol\\[$env\\]]($style) "
|
||||
```
|
||||
|
||||
#### Time
|
||||
|
||||
| Deprecated Property | Replacement |
|
||||
| ------------------- | ------------- |
|
||||
| `format` | `time_format` |
|
||||
|
||||
**Changes to the Default Configuration**
|
||||
|
||||
```diff
|
||||
[time]
|
||||
-- format = "🕙[ %T ]"
|
||||
++ time_format = "%T"
|
||||
++ format = "at 🕙[$time]($style)
|
||||
```
|
||||
|
||||
#### Custom Commands
|
||||
|
||||
| Deprecated Property | Replacement |
|
||||
| ------------------- | ----------- |
|
||||
| `prefix` | `format` |
|
||||
| `suffix` | `format` |
|
||||
|
||||
**Changes to the Default Configuration**
|
||||
|
||||
```diff
|
||||
[cmd_duration]
|
||||
-- prefix = ""
|
||||
-- suffix = ""
|
||||
++ format = "[$symbol$output]($style) "
|
||||
```
|
||||
Loading…
Reference in New Issue