Ainda que Starship seja um shell versátil, às vezes você precisará fazer algumas outras coisas além de editar o arquivo `starship.toml`. Esta página detalha algumas das configurações mais avançadas usadas em starship.
Ainda que Starship se`ja um shell versátil, às vezes você precisará fazer algumas outras coisas além de editar o arquivo <code>starship.toml`. Esta página detalha algumas das configurações mais avançadas usadas em starship.
Todas as configurações do starship são feitas neste arquivo [TOML](https://github.com/toml-lang/toml):
All configuration for starship is done in this [TOML](https://github.com/toml-lang/toml) file:
```toml
# Don't print a new line at the start of the prompt
@@ -27,21 +21,35 @@ success_symbol = "[➜](bold green)" # The "success_symbol" segment is being
disabled=true
```
Você pode alterar o caminho padrão do arquivo `starship.toml` com a variável de ambiente `STARSHIP_CONFIG`:
You can change default `starship.toml` file location with `STARSHIP_CONFIG` environment variable:
```sh
exportSTARSHIP_CONFIG=~/.starship
```
No PowerShell (Windows) você pode adicionar a seguinte linha no seu`$PROFILE`:
Equivalently in PowerShell (Windows) would be adding this line to your`$PROFILE`:
```ps1
$ENV:STARSHIP_CONFIG="$HOME\.starship"
```
### Terminologia
### Logging
**Módulo**: Um componente no prompt que fornece informações baseado no contexto do seu SO. Por exemplo, o módulo "nodejs" mostra a versão do NodeJS instalado no seu computador, se o diretório atual for um projeto NodeJS.
By default starship logs warnings and errors into a file named `~/.cache/starship/session_${STARSHIP_SESSION_KEY}.log`, where the session key is corresponding to a instance of your terminal. This, however can be changed using the `STARSHIP_CACHE` environment variable:
```sh
exportSTARSHIP_CACHE=~/.starship/cache
```
Equivalently in PowerShell (Windows) would be adding this line to your `$PROFILE`:
```ps1
$ENV:STARSHIP_CACHE="$HOME\AppData\Local\Temp"
```
### Terminology
**Module**: A component in the prompt giving information based on contextual information from your OS. For example, the "nodejs" module shows the version of NodeJS that is currently installed on your computer, if your current directory is a NodeJS project.
**Variable**: Smaller sub-components that contains information provided by the module. For example, the "version" variable in the "nodejs" module contains the current version of NodeJS.
@@ -77,7 +85,7 @@ For example:
#### Estilo dos textos
A maioria dos módulos do starship permite que você configure o estilo de exibição dos textos. Isso é feito através de um parâmetro (geralmente chamado`style`) que é uma string especificando a configuração. Aqui estão alguns exemplos de strings de estilo e o que elas fazem. Para detalhes sobre a sintaxe completa, consulte o [guia de configurações avançadas](/advanced-config/).
Most modules in starship allow you to configure their display styles. This is done with an entry (usually called`style`) which is a string specifying the configuration. Here are some examples of style strings along with what they do. For details on the full syntax, consult the [advanced config guide](/advanced-config/).
-`"fg:green bg:blue"` deixa o texto verde com o fundo azul
-`"bg:blue fg:bright-green"` deixa o texto verde brilhante com o fundo azul
@@ -86,7 +94,7 @@ A maioria dos módulos do starship permite que você configure o estilo de exibi
-`"bold italic fg:purple"` deixa o texto em negrito e itálico com a cor roxa
-`""` desabilita explicitamente todos os estilos
Note que a aparência do estilo será controlado pelo seu terminal. Por exemplo, alguns terminais deixarão as cores mais brilhantes ao invés de deixar o texto em negrito, ou alguns temas podem usar as mesmas cores para cores brilhantes e normais. Além disso, para textos em itálico, o terminal precisa ter suporte.
Note that what styling looks like will be controlled by your terminal emulator. For example, some terminal emulators will brighten the colors instead of bolding text, and some color themes use the same values for the normal and bright colors. Also, to get italic text, your terminal must support italics.
#### Conditional Format Strings
@@ -102,7 +110,7 @@ For example:
The following symbols have special usage in a format string. If you want to print the following symbols, you have to escape them with a backslash (`\`).
- $
-\$
- \\
- [
- ]
@@ -138,15 +146,13 @@ This is the list of prompt-wide configuration options.
| `format` | [link](#default-prompt-format) | Configure the format of the prompt. |
| `scan_timeout` | `30` | Timeout for starship to scan files (in milliseconds). |
| `add_newline` | `true` | Add a new line before the start of the prompt. |
### Exemplo
```toml
# ~/.config/starship.toml
# Disable the newline at the start of the prompt
format="$all"
# Use custom format
format="""
[┌───────────────────>](bold green)
@@ -155,20 +161,23 @@ format = """
# Wait 10 milliseconds for starship to check files under the current directory.
scan_timeout=10
# Disable the newline at the start of the prompt
add_newline=false
```
### Default Prompt Format
The default `format` is used to define the format of the prompt, if empty or no `format` is provided. Os valores padrão são os seguintes:
The default `format` is used to define the format of the prompt, if empty or no `format` is provided. The default is as shown:
```toml
format="\n$all"
format="$all"
# Which is equivalent to
format="""
$username\
$hostname\
$shlvl\
$kubernetes\
$directory\
$git_branch\
@@ -179,6 +188,7 @@ $hg_branch\
$docker_context\
$package\
$cmake\
$dart\
$dotnet\
$elixir\
$elm\
@@ -190,17 +200,20 @@ $julia\
$nim\
$nodejs\
$ocaml\
$perl\
$php\
$purescript\
$python\
$ruby\
$rust\
$swift\
$terraform\
$zig\
$nix_shell\
$conda\
$memory_usage\
$aws\
$gcloud\
$env_var\
$crystal\
$cmd_duration\
@@ -209,6 +222,7 @@ $line_break\
$jobs\
$battery\
$time\
$status\
$character"""
```
@@ -318,9 +332,9 @@ charging_symbol = "⚡️"
discharging_symbol="💀"
```
### Indicador de bateria
### Battery Display
The `display` configuration option is used to define when the battery indicator should be shown (threshold) and what it looks like (style). If no `display` is provided. Os valores padrão são os seguintes:
The `display` configuration option is used to define when the battery indicator should be shown (threshold) and what it looks like (style). If no `display` is provided. The default is as shown:
```toml
[[battery.display]]
@@ -439,7 +453,7 @@ The `cmake` module shows the currently installed version of CMake if:
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 Não utilize o DEBUG-trap no Bash
::: warning Do not hook the DEBUGtrap 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.
@@ -494,6 +508,7 @@ This does not suppress conda's own prompt modifier, you may want to run `conda c
| `symbol` | `"🅒 "` | The symbol used before the environment name. |
| `style` | `"bold green"` | O estilo do módulo. |
| `format` | `"[$symbol$environment]($style) "` | The format for the module. |
| symbol | | Mirrors the value of option `symbol` |
| style\* | | Mirrors the value of option `style` |
\*: This variable can only be used as a part of a style string
### Exemplo
```toml
# ~/.config/starship.toml
[dart]
format="via [🔰 $version](bold red) "
```
## Directory
The `directory` module shows the path to your current directory, truncated to three parent folders. Your directory will also be truncated to the root of the git repo that you're currently in.
@@ -790,7 +841,7 @@ The `env_var` module displays the current value of a selected environment variab
| env_value | `Windows NT` (if *variable* would be `$OS`) | The environment value of option `variable` |
| env_value | `Windows NT` (if _variable_ would be `$OS`) | The environment value of option `variable` |
| symbol | | Mirrors the value of option `symbol` |
| style\* | `black bold dimmed` | Mirrors the value of option `style` |
@@ -841,6 +892,66 @@ The `erlang` module shows the currently installed version of Erlang/OTP. The mod
format="via [e $version](bold red) "
```
## Gcloud
The `gcloud` module shows the current configuration for [`gcloud`](https://cloud.google.com/sdk/gcloud) CLI. This is based on the `~/.config/gcloud/active_config` file and the `~/.config/gcloud/configurations/config_{CONFIG NAME}` file and the `CLOUDSDK_CONFIG` env var.
| `ssh_only` | `true` | Only show hostname when connected to an SSH session. |
| `trim_at` | `"."` | String that the hostname is cut off at, after the first match. `"."` will stop after the first dot. `""` will disable any truncation |
| `format` | `"on [$hostname]($style) "` | The format for the module. |
| `format` | `"[$hostname]($style) in "` | The format for the module. |
| `style` | `"bold dimmed green"` | O estilo do módulo. |
| `disabled` | `false` | Disables the `hostname` module. |
@@ -1116,7 +1236,6 @@ The `hostname` module shows the system hostname.
The `package` module is shown when the current directory is the repository for a package, and shows its current version. The module currently supports `npm`, `cargo`, `poetry`, `composer`, `gradle`, `julia` and `mix` packages.
The `package` module is shown when the current directory is the repository for a package, and shows its current version. The module currently supports `npm`, `cargo`, `poetry`, `composer`, `gradle`, `julia`, `mix` and `helm` packages.
- **npm** – The `npm` package version is extracted from the `package.json` present in the current directory
- **cargo** – The `cargo` package version is extracted from the `Cargo.toml` present in the current directory
@@ -1513,6 +1632,8 @@ The `package` module is shown when the current directory is the repository for a
- **gradle** – The `gradle` package version is extracted from the `build.gradle` present
- **julia** - The package version is extracted from the `Project.toml` present
- **mix** - The `mix` package version is extracted from the `mix.exs` present
- **helm** - The `helm` chart version is extracted from the `Chart.yaml` present
- **maven** - The `maven` package version is extracted from the `pom.xml` present
> ⚠️ The version being shown is that of the package whose source code is in your current directory, not your package manager.
@@ -1584,6 +1705,42 @@ The `ocaml` module shows the currently installed version of OCaml. The module wi
format="via [🐪 $version]($style) "
```
## Perl
The `perl` module shows the currently installed version of Perl. The module will be shown if any of the following conditions are met:
- The current directory contains a `Makefile.PL` or `Build.PL` file
- The current directory contains a `cpanfile` or `cpanfile.snapshot` file
- The current directory contains a `META.json` file or `META.yml` file
- The current directory contains a `.perl-version` file
- The current directory contains a `.pl`, `.pm` or `.pod`
| version | `"v3.8.1"` | The version of `python` |
| symbol | `"🐍 "` | Mirrors the value of option `symbol` |
| style | `"yellow bold"` | Mirrors the value of option `style` |
| pyenv_prefix | `"pyenv"`| Mirrors the value of option `pyenv_prefix` |
| virtualenv | `"venv"` | The current `virtualenv` name |
<details>
<summary>This module has some advanced configuration options.</summary>
@@ -1684,7 +1843,6 @@ python_binary = "python3"
[python]
symbol="👾 "
pyenv_version_name=true
pyenv_prefix="foo "
```
## Ruby
@@ -1758,6 +1916,41 @@ The `rust` module shows the currently installed version of Rust. The module will
format="via [⚙️ $version](red bold)"
```
## SHLVL
The `shlvl` module shows the current SHLVL ("shell level") environment variable, if it is set to a number and meets or exceeds the specified threshold.
| status | `127` | The exit code of the last command |
| symbol | | Mirrors the value of option `symbol` |
| style\* | | Mirrors the value of option `style` |
\*: This variable can only be used as a part of a style string
### Exemplo
```toml
# ~/.config/starship.toml
[status]
style="bg:blue"
symbol="💣 "
format="[\\[$symbol$status\\]]($style) "
disabled=false
```
## Terraform
The `terraform` module shows the currently selected terraform workspace and version. By default the terraform version is not shown, since this is slow on 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-version). The module will be shown if any of the following conditions are met:
@@ -1894,13 +2164,13 @@ The `username` module shows active user's username. The module will be shown if
| `disabled` | `false` | Disables the `username` module. |
### Variables
@@ -1975,7 +2245,13 @@ Multiple custom modules can be defined by using a `.`.
::: tip
The order in which custom modules are shown can be individually set by setting `custom.foo` in `prompt_order`. By default, the `custom` module will simply show all custom modules in the order they were defined.
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!
:::
@@ -1983,10 +2259,10 @@ The order in which custom modules are shown can be individually set by setting `
| `descrição` | `"<custom module>"` | The description of the module that is shown when running `starship explain`. |
| `description` | `"<custom module>"` | The description of the module that is shown when running `starship explain`. |
| `files` | `[]` | The files that will be searched in the working directory for a match. |
| `directories` | `[]` | The directories that will be searched in the working directory for a match. |
| `extensions` | `[]` | The extensions that will be searched in the working directory for a match. |
@@ -2014,6 +2290,8 @@ The order in which custom modules are shown can be individually set by setting `
If unset, it will fallback to STARSHIP_SHELL and then to "sh" on Linux, and "cmd /C" on Windows.
The `command` will be passed in on stdin.
If `shell` is not given or only contains one element and Starship detects PowerShell will be used, the following arguments will automatically be added: `-NoProfile -Command -`. This behavior can be avoided by explicitly passing arguments to the shell, e.g.
```toml
@@ -2041,12 +2319,11 @@ Automatic detection of shells and proper parameters addition are currently imple
## Do `prompt_order` and `<module>.disabled` do the same thing?
## Do top level `format` and `<module>.disabled` do the same thing?
Yes, they can both be used to disable modules in the prompt. If all you plan to do is disable modules, `<module>.disabled` is the preferred way to do so for these reasons:
- Disabling modules is more explicit than omitting them from the prompt_order
- Disabling modules is more explicit than omitting them from the top level `format`
- Newly created modules will be added to the prompt as Starship is updated
## The docs say Starship is cross-shell, but it doesn't support X shell. Why?
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
#### Caractere
| Removed 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) "
```
#### Tempo de execução do comando
| Removed Property | Replacement |
| ---------------- | ----------- |
| `prefix` | `format` |
**Changes to the Default Configuration**
```diff
[cmd_duration]
-- prefix = "took "
++ format = "took [$duration]($style)"
```
#### Directory
| Removed Property | Replacement |
| ---------------- | ----------- |
| `prefix` | `format` |
**Changes to the Default Configuration**
```diff
[directory]
-- prefix = "in "
++ format = "[$path]($style)[$lock_symbol]($lock_style)"
```
#### Environment Variable
| Removed Property | Replacement |
| ---------------- | ----------- |
| `prefix` | `format` |
| `suffix` | `format` |
**Changes to the Default Configuration**
```diff
[env_var]
-- prefix = ""
-- suffix = ""
++ format = "with [$env_value]($style) "
```
#### Git Commit
| Removed Property | Replacement |
| ---------------- | ----------- |
| `prefix` | `format` |
| `suffix` | `format` |
**Changes to the Default Configuration**
```diff
[git_commit]
-- prefix = "("
-- suffix = ")"
++ format = "[\\($hash\\)]($style) "
```
#### Git Status
| Removed Property | Replacement |
| ----------------- | ----------- |
| `prefix` | `format` |
| `suffix` | `format` |
| `show_sync_count` | `format` |
**Changes to the Default Configuration**
```diff
[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:
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Matan Kushner