andrei/starship
1
0
Fork 0
mirror of https://github.com/starship/starship.git synced 2026-06-22 02:02:12 +07:00
Code Issues Packages Projects Releases 10 Wiki Activity

docs: use GitHub-flavored alerts (#6751)

Browse Source
This commit is contained in:
David Knaack
2025-06-14 20:32:16 +02:00
committed by GitHub
parent 0d5fec7707
commit 2c515c9488
4 changed files with 152 additions and 247 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/config/README.md
+143 -224
View File
@@ -221,12 +221,9 @@ This is the list of prompt-wide configuration options.
| `palettes` | `{}` | Collection of color palettes that assign [colors](../advanced-config/#style-strings) to user-defined names. Note that color palettes cannot reference their own color definitions. |
| `follow_symlinks` | `true` | Follows symlinks to check if they're directories; used in modules such as git. |
::: tip
If you have symlinks to networked filesystems, consider setting
`follow_symlinks` to `false`.
:::
> [!TIP]
> If you have symlinks to networked filesystems, consider setting
> `follow_symlinks` to `false`.
### Example
@@ -769,13 +766,10 @@ can do this in two ways:
By default it only changes color. If you also want to change its shape take a
look at [this example](#with-custom-error-shape).
::: warning
`vimcmd_symbol` is only supported in cmd, fish and zsh.
`vimcmd_replace_one_symbol`, `vimcmd_replace_symbol`, and `vimcmd_visual_symbol`
are only supported in fish due to [upstream issues with mode detection in zsh](https://github.com/starship/starship/issues/625#issuecomment-732454148).
:::
> [!WARNING]
> `vimcmd_symbol` is only supported in cmd, fish and zsh.
> `vimcmd_replace_one_symbol`, `vimcmd_replace_symbol`, and `vimcmd_visual_symbol`
> are only supported in fish due to [upstream issues with mode detection in zsh](https://github.com/starship/starship/issues/625#issuecomment-732454148).
### Options
@@ -895,12 +889,11 @@ The `cmd_duration` module shows how long the last command took to execute.
The module will be shown only if the command took longer than two seconds, or
the `min_time` config value, if it exists.
::: warning Do not hook the DEBUG trap in Bash
If you are running Starship in `bash`, do not hook the `DEBUG` trap after running
`eval $(starship init $0)`, or this module **will** break.
:::
> [!WARNING]
> Do not hook the DEBUG trap in Bash
>
> If you are running Starship in `bash`, do not hook the `DEBUG` trap after running
> `eval $(starship init $0)`, or this module **will** break.
Bash users who need preexec-like functionality can use
[rcaloras's bash_preexec framework](https://github.com/rcaloras/bash-preexec).
@@ -943,12 +936,9 @@ format = 'underwent [$duration](bold yellow)'
The `conda` module shows the current [Conda](https://docs.conda.io/en/latest/) environment, if `$CONDA_DEFAULT_ENV` is set.
::: tip
This does not suppress conda's own prompt modifier, you may want to run `conda config --set changeps1 False`.
If you use [pixi](https://pixi.sh), you can disable pixi's prompt modifier by running `pixi config set shell.change-ps1 false`.
:::
> [!TIP]
> This does not suppress conda's own prompt modifier, you may want to run `conda config --set changeps1 False`.
> If you use [pixi](https://pixi.sh), you can disable pixi's prompt modifier by running `pixi config set shell.change-ps1 false`.
### Options
@@ -1504,29 +1494,23 @@ The module will be shown only if any of the following conditions are met:
- The `variable` configuration option matches an existing environment variable
- The `variable` configuration option is not defined, but the `default` configuration option is
::: tip
> [!TIP]
> The order in which env_var modules are shown can be individually set by including
> `${env_var.foo}` in the top level `format` (as it includes a dot, you need to use `${...}`).
> By default, the `env_var` module will simply show all env_var modules in the order they were defined.
The order in which env_var modules are shown can be individually set by including
`${env_var.foo}` in the top level `format` (as it includes a dot, you need to use `${...}`).
By default, the `env_var` module will simply show all env_var modules in the order they were defined.
:::
::: tip
Multiple environmental variables can be displayed by using a `.`. (see example)
If the `variable` configuration option is not set, the module will display value of variable under the name of text after the `.` character.
Example: following configuration will display value of USER environment variable
```toml
# ~/.config/starship.toml
[env_var.USER]
default = 'unknown user'
```
:::
> [!TIP]
> Multiple environmental variables can be displayed by using a `.`. (see example)
> If the `variable` configuration option is not set, the module will display value of variable under the name of text after the `.` character.
>
> Example: following configuration will display value of USER environment variable
>
> ```toml
> # ~/.config/starship.toml
>
> [env_var.USER]
> default = 'unknown user'
> ```
### Options
@@ -1958,12 +1942,9 @@ cherry_pick = '[🍒 PICKING](bold red)'
The `git_metrics` module will show the number of added and deleted lines in
the current git repository.
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
:::
> [!TIP]
> This module is disabled by default.
> To enable it, set `disabled` to `false` in your configuration file.
### Options
@@ -2002,12 +1983,9 @@ format = '[+$added]($added_style)/[-$deleted]($deleted_style) '
The `git_status` module shows symbols representing the state of the repo in your
current directory.
::: tip
The Git Status module is very slow in Windows directories (for example under `/mnt/c/`) when in a WSL environment.
You can disable the module or use the `windows_starship` option to use a Windows-native Starship executable to compute `git_status` for those paths.
:::
> [!TIP]
> The Git Status module is very slow in Windows directories (for example under `/mnt/c/`) when in a WSL environment.
> You can disable the module or use the `windows_starship` option to use a Windows-native Starship executable to compute `git_status` for those paths.
### Options
@@ -2501,20 +2479,14 @@ The default functionality is:
- 1 job -> `symbol` is shown.
- 2 jobs or more -> `symbol` + `number` are shown.
::: warning
> [!WARNING]
> This module is not supported on tcsh.
This module is not supported on tcsh.
:::
::: warning
The `threshold` option is deprecated, but if you want to use it,
the module will show the number of jobs running if there is more than 1 job, or
more than the `threshold` config value, if it exists. If `threshold` is set to 0,
then the module will also show when there are 0 jobs running.
:::
> [!WARNING]
> The `threshold` option is deprecated, but if you want to use it,
> the module will show the number of jobs running if there is more than 1 job, or
> more than the `threshold` config value, if it exists. If `threshold` is set to 0,
> then the module will also show when there are 0 jobs running.
### Options
@@ -2649,26 +2621,20 @@ Similarly, the user and cluster can be set with `kubectl config set-context star
and `kubectl config set-context starship-context --cluster starship-cluster`.
If the `$KUBECONFIG` env var is set the module will use that if not it will use the `~/.kube/config`.
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
When the module is enabled it will always be active, unless any of
`detect_env_vars`, `detect_extensions`, `detect_files` or `detect_folders` have
been set in which case the module will only be active in directories that match
those conditions or one of the environmatal variable has been set.
:::
> [!TIP]
> This module is disabled by default.
> To enable it, set `disabled` to `false` in your configuration file.
>
> When the module is enabled it will always be active, unless any of
> `detect_env_vars`, `detect_extensions`, `detect_files` or `detect_folders` have
> been set in which case the module will only be active in directories that match
> those conditions or one of the environmatal variable has been set.
### Options
::: warning
The `context_aliases` and `user_aliases` options are deprecated. Use `contexts` and the corresponding `context_alias`
and `user_alias` options instead.
:::
> [!WARNING]
> The `context_aliases` and `user_aliases` options are deprecated. Use `contexts` and the corresponding `context_alias`
> and `user_alias` options instead.
| Option | Default | Description |
| ------------------- | -------------------------------------------------- | --------------------------------------------------------------------- |
@@ -2872,12 +2838,9 @@ The `memory_usage` module shows current system memory and swap usage.
By default the swap usage is displayed if the total system swap is non-zero.
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
:::
> [!TIP]
> This module is disabled by default.
> To enable it, set `disabled` to `false` in your configuration file.
### Options
@@ -3452,18 +3415,12 @@ symbol = '☁️ '
The `os` module shows the current operating system.
OS information is detected via the [os_info](https://lib.rs/crates/os_info) crate.
::: warning
> [!WARNING]
> The [os_info](https://lib.rs/crates/os_info) crate used by this module is known to be inaccurate on some systems.
The [os_info](https://lib.rs/crates/os_info) crate used by this module is known to be inaccurate on some systems.
:::
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
:::
> [!TIP]
> This module is disabled by default.
> To enable it, set `disabled` to `false` in your configuration file.
### Options
@@ -3726,11 +3683,8 @@ The `pijul_channel` module shows the active channel of the repo in your current
The `pixi` module shows the installed [pixi](https://pixi.sh) version as well as the activated environment, if `$PIXI_ENVIRONMENT_NAME` is set.
::: tip
This does not suppress pixi's own prompt modifier, you may want to run `pixi config set shell.change-ps1 false`.
:::
> [!TIP]
> This does not suppress pixi's own prompt modifier, you may want to run `pixi config set shell.change-ps1 false`.
### Options
@@ -3769,12 +3723,9 @@ format = '[$symbol$environment](yellow) '
The `pulumi` module shows the current username, selected [Pulumi Stack](https://www.pulumi.com/docs/intro/concepts/stack/), and version.
::: tip
By default the Pulumi version is not shown, since it takes an order of magnitude longer to load then most plugins (~70ms).
If you still want to enable it, [follow the example shown below](#with-pulumi-version).
:::
> [!TIP]
> By default the Pulumi version is not shown, since it takes an order of magnitude longer to load then most plugins (~70ms).
> If you still want to enable it, [follow the example shown below](#with-pulumi-version).
By default the module will be shown if any of the following conditions are met:
@@ -3903,23 +3854,20 @@ By default, the module will be shown if any of the following conditions are met:
| `detect_folders` | `[]` | Which folders should trigger this module |
| `disabled` | `false` | Disables the `python` module. |
::: tip
The `python_binary` variable accepts either a string or a list of strings.
Starship will try executing each binary until it gets a result. Note you can
only change the binary that Starship executes to get the version of Python not
the arguments that are used.
The default values and order for `python_binary` was chosen to first identify
the Python version in a virtualenv/conda environments (which currently still
add a `python`, no matter if it points to `python3` or `python2`). This has the
side effect that if you still have a system Python 2 installed, it may be
picked up before any Python 3 (at least on Linux Distros that always symlink
`/usr/bin/python` to Python 2). If you do not work with Python 2 anymore but
cannot remove the system Python 2, changing this to `'python3'` will hide any
Python version 2, see example below.
:::
> [!TIP]
> The `python_binary` variable accepts either a string or a list of strings.
> Starship will try executing each binary until it gets a result. Note you can
> only change the binary that Starship executes to get the version of Python not
> the arguments that are used.
>
> The default values and order for `python_binary` was chosen to first identify
> the Python version in a virtualenv/conda environments (which currently still
> add a `python`, no matter if it points to `python3` or `python2`). This has the
> side effect that if you still have a system Python 2 installed, it may be
> picked up before any Python 3 (at least on Linux Distros that always symlink
> `/usr/bin/python` to Python 2). If you do not work with Python 2 anymore but
> cannot remove the system Python 2, changing this to `'python3'` will hide any
> Python version 2, see example below.
### Variables
@@ -4243,12 +4191,9 @@ symbol = '🌟 '
The `shell` module shows an indicator for currently used shell.
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
:::
> [!TIP]
> This module is disabled by default.
> To enable it, set `disabled` to `false` in your configuration file.
### Options
@@ -4457,12 +4402,9 @@ The `status` module displays the exit code of the previous command.
If $success_symbol is empty (default), the module will be shown only if the exit code is not `0`.
The status code will cast to a signed 32-bit integer.
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
:::
> [!TIP]
> This module is disabled by default.
> To enable it, set `disabled` to `false` in your configuration file.
### Options
@@ -4522,12 +4464,9 @@ disabled = false
The `sudo` module displays if sudo credentials are currently cached.
The module will only be shown if credentials are cached.
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
:::
> [!TIP]
> This module is disabled by default.
> To enable it, set `disabled` to `false` in your configuration file.
### Options
@@ -4612,12 +4551,9 @@ format = 'via [🏎 $version](red bold)'
The `terraform` module shows the currently selected [Terraform workspace](https://www.terraform.io/docs/language/state/workspaces.html) and version.
::: tip
By default the Terraform version is not shown, since this is slow for current versions of Terraform when a lot of plugins are in use.
If you still want to enable it, [follow the example shown below](#with-terraform-version).
:::
> [!TIP]
> By default the Terraform version is not shown, since this is slow for current versions of Terraform when a lot of plugins are in use.
> If you still want to enable it, [follow the example shown below](#with-terraform-version).
By default the module will be shown if any of the following conditions are met:
@@ -4673,12 +4609,9 @@ format = '[🏎💨 $workspace]($style) '
The `time` module shows the current **local** time.
The `format` configuration value is used by the [`chrono`](https://crates.io/crates/chrono) crate to control how the time is displayed. Take a look [at the chrono strftime docs](https://docs.rs/chrono/0.4.7/chrono/format/strftime/index.html) to see what options are available.
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
:::
> [!TIP]
> This module is disabled by default.
> To enable it, set `disabled` to `false` in your configuration file.
### Options
@@ -4761,13 +4694,10 @@ The module will be shown if any of the following conditions are met:
- The variable `show_always` is set to true
- The array `detect_env_vars` contains at least the name of one environment variable, that is set
::: tip
SSH connection is detected by checking environment variables
`SSH_CONNECTION`, `SSH_CLIENT`, and `SSH_TTY`. If your SSH host does not set up
these variables, one workaround is to set one of them with a dummy value.
:::
> [!TIP]
> SSH connection is detected by checking environment variables
> `SSH_CONNECTION`, `SSH_CLIENT`, and `SSH_TTY`. If your SSH host does not set up
> these variables, one workaround is to set one of them with a dummy value.
### Options
@@ -4964,40 +4894,30 @@ These modules will be shown if any of the following conditions are met:
- The `when` command returns 0
- The current Operating System (std::env::consts::OS) matches with `os` field if defined.
::: tip
> [!TIP]
> Multiple custom modules can be defined by using a `.`.
Multiple custom modules can be defined by using a `.`.
> [!TIP]
> The order in which custom modules are shown can be individually set by including
> `${custom.foo}` in the top level `format` (as it includes a dot, you need to use `${...}`).
> By default, the `custom` module will simply show all custom modules in the order they were defined.
:::
> [!TIP]
> [Issue #1252](https://github.com/starship/starship/discussions/1252) contains examples of custom modules.
> If you have an interesting example not covered there, feel free to share it there!
::: tip
The order in which custom modules are shown can be individually set by including
`${custom.foo}` in the top level `format` (as it includes a dot, you need to use `${...}`).
By default, the `custom` module will simply show all custom modules in the order they were defined.
:::
::: tip
[Issue #1252](https://github.com/starship/starship/discussions/1252) contains examples of custom modules.
If you have an interesting example not covered there, feel free to share it there!
:::
::: warning If `unsafe_no_escape` is enabled or prior to starship v1.20 command output is printed unescaped to the prompt.
Whatever output the command generates is printed unmodified in the prompt. This means if the output
contains shell-specific interpretable sequences, they could be interpreted on display.
Depending on the shell, this can mean that e.g. strings enclosed by backticks are executed by the shell.
Such sequences are usually shell specific, e.g. you can write a command module that writes bash sequences,
e.g. `\h`, but this module will not work in a fish or zsh shell.
Format strings can also contain shell specific prompt sequences, e.g.
[Bash](https://www.gnu.org/software/bash/manual/html_node/Controlling-the-Prompt.html),
[Zsh](https://zsh.sourceforge.io/Doc/Release/Prompt-Expansion.html).
:::
> [!WARNING]
> If `unsafe_no_escape` is enabled or prior to starship v1.20 command output is printed unescaped to the prompt.
>
> Whatever output the command generates is printed unmodified in the prompt. This means if the output
> contains shell-specific interpretable sequences, they could be interpreted on display.
> Depending on the shell, this can mean that e.g. strings enclosed by backticks are executed by the shell.
> Such sequences are usually shell specific, e.g. you can write a command module that writes bash sequences,
> e.g. `\h`, but this module will not work in a fish or zsh shell.
>
> Format strings can also contain shell specific prompt sequences, e.g.
> [Bash](https://www.gnu.org/software/bash/manual/html_node/Controlling-the-Prompt.html),
> [Zsh](https://zsh.sourceforge.io/Doc/Release/Prompt-Expansion.html).
### Options
@@ -5053,28 +4973,27 @@ This behavior can be avoided by explicitly passing arguments to the shell, e.g.
shell = ['pwsh', '-Command', '-']
```
::: warning Make sure your custom shell configuration exits gracefully
If you set a custom command, make sure that the default Shell used by starship
will properly execute the command with a graceful exit (via the `shell`
option).
For example, PowerShell requires the `-Command` parameter to execute a one
liner. Omitting this parameter might throw starship into a recursive loop
where the shell might try to load a full profile environment with starship
itself again and hence re-execute the custom command, getting into a never
ending loop.
Parameters similar to `-NoProfile` in PowerShell are recommended for other
shells as well to avoid extra loading time of a custom profile on every
starship invocation.
Automatic detection of shells and proper parameters addition are currently
implemented, but it's possible that not all shells are covered.
[Please open an issue](https://github.com/starship/starship/issues/new/choose)
with shell details and starship configuration if you hit such scenario.
:::
> [!WARNING]
> Make sure your custom shell configuration exits gracefully
>
> If you set a custom command, make sure that the default Shell used by starship
> will properly execute the command with a graceful exit (via the `shell`
> option).
>
> For example, PowerShell requires the `-Command` parameter to execute a one
> liner. Omitting this parameter might throw starship into a recursive loop
> where the shell might try to load a full profile environment with starship
> itself again and hence re-execute the custom command, getting into a never
> ending loop.
>
> Parameters similar to `-NoProfile` in PowerShell are recommended for other
> shells as well to avoid extra loading time of a custom profile on every
> starship invocation.
>
> Automatic detection of shells and proper parameters addition are currently
> implemented, but it's possible that not all shells are covered.
> [Please open an issue](https://github.com/starship/starship/issues/new/choose)
> with shell details and starship configuration if you hit such scenario.
### Example