Llewellyn/starship
1
0
Fork 0
mirror of https://github.com/Llewellynvdm/starship.git synced 2024-11-04 20:37:56 +00:00
Code Issues Releases Activity
6bd4e724e9
starship/docs/config/README.md

2717 lines
119 KiB
Markdown
Raw Normal View History

docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
# Configuration
To get started configuring starship, create the following file: `~/.config/starship.toml`.
docs: Use Algolia DocSearch for docs
2020-02-07 17:36:23 +00:00
```sh
style(docs): remove `$` prefix from shell snippets (#1339)
2020-06-17 12:31:24 +00:00
mkdir -p ~/.config && touch ~/.config/starship.toml
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```
All configuration for starship is done in this [TOML](https://github.com/toml-lang/toml) file:
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```toml
feat: Add configuration for add_newline (#116) - Replace TableExt with a Config trait that extends toml::value::Table Add configuration for add_newline - add_newline is a root-level configuration value. When set to false, the initial newline before the prompt is removed.
2019-07-27 22:25:13 +00:00
# Don't print a new line at the start of the prompt
fix: re-add add_newline to root config (#1598)
2020-08-18 16:58:29 +00:00
add_newline = false
feat: Add configuration for add_newline (#116) - Replace TableExt with a Config trait that extends toml::value::Table Add configuration for add_newline - add_newline is a root-level configuration value. When set to false, the initial newline before the prompt is removed.
2019-07-27 22:25:13 +00:00
fix: Set default prompt character to ❯ (#177)
2019-08-18 15:34:45 +00:00
# Replace the "❯" symbol in the prompt with "➜"
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
[character] # The name of the module we are configuring is "character"
success_symbol = "[➜](bold green)" # The "success_symbol" segment is being set to "➜" with the color "bold green"
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
# Disable the package module, hiding it from the prompt completely
[package]
disabled = true
```
docs: Document the STARSHIP_CONFIG env variable (#807)
2020-01-04 19:20:07 +00:00
You can change default `starship.toml` file location with `STARSHIP_CONFIG` environment variable:
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
docs: Use Algolia DocSearch for docs
2020-02-07 17:36:23 +00:00
```sh
docs: Document the STARSHIP_CONFIG env variable (#807)
2020-01-04 19:20:07 +00:00
export STARSHIP_CONFIG=~/.starship
```
docs: Updated config with a tip for PowerShell user (#1216) Added a tip with information about how a PowerShell user can override default starship.toml file location path in his PowerShell profile.
2020-05-21 16:22:45 +00:00
Equivalently in PowerShell (Windows) would be adding this line to your `$PROFILE`:
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
docs: highlight powershell in vuepress (#2147)
2021-01-14 20:48:06 +00:00
```powershell
docs: Updated config with a tip for PowerShell user (#1216) Added a tip with information about how a PowerShell user can override default starship.toml file location path in his PowerShell profile.
2020-05-21 16:22:45 +00:00
$ENV:STARSHIP_CONFIG = "$HOME\.starship"
```
feat: add error messaging (#1576) This creates a custom logger for the log crate which logs everything to a file (/tmp/starship/session_$STARSHIP_SESSION_KEY.log) and it logs everything above Warn to stderr, but only if the log file does not contain the line that should be logged resulting in an error or warning to be only logged at the first starship invocation after opening the shell.
2020-09-28 20:38:50 +00:00
### Logging
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
export STARSHIP_CACHE=~/.starship/cache
```
Equivalently in PowerShell (Windows) would be adding this line to your `$PROFILE`:
docs: highlight powershell in vuepress (#2147)
2021-01-14 20:48:06 +00:00
```powershell
feat: add error messaging (#1576) This creates a custom logger for the log crate which logs everything to a file (/tmp/starship/session_$STARSHIP_SESSION_KEY.log) and it logs everything above Warn to stderr, but only if the log file does not contain the line that should be logged resulting in an error or warning to be only logged at the first starship invocation after opening the shell.
2020-09-28 20:38:50 +00:00
$ENV:STARSHIP_CACHE = "$HOME\AppData\Local\Temp"
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### 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.
docs: fix typo in config (#2008)
2020-12-18 17:24:48 +00:00
**Variable**: Smaller sub-components that contain information provided by the module. For example, the "version" variable in the "nodejs" module contains the current version of NodeJS.
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
By convention, most modules have a prefix of default terminal color (e.g. `via ` in "nodejs") and an empty space as a suffix.
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Format Strings
Format strings are the format that a module prints all its variables with.
Most modules have an entry called `format` that configures the display format of the module.
You can use texts, variables and text groups in a format string.
#### Variable
A variable contains a `$` symbol followed by the name of the variable.
The name of a variable only contains letters, numbers and `_`.
For example:
- `$version` is a format string with a variable named `version`.
- `$git_branch$git_commit` is a format string with two variables named `git_branch` and `git_commit`.
- `$git_branch $git_commit` has the two variables separated with a space.
#### Text Group
A text group is made up of two different parts.
The first part, which is enclosed in a `[]`, is a [format string](#format-strings).
You can add texts, variables, or even nested text groups in it.
In the second part, which is enclosed in a `()`, is a [style string](#style-strings). This can be used style the first part.
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
For example:
- `[on](red bold)` will print a string `on` with bold text colored red.
- `[⬢ $version](bold green)` will print a symbol `⬢ ` followed by the content of variable `version`, with bold text colored green.
- `[a [b](red) c](green)` will print `a b c` with `b` red, and `a` and `c` green.
#### Style Strings
feat: Add the ability to configure per-module color styles (#285) Add parsing logic, config support, docs, and integration with other modules for custom styling of each module.
2019-09-08 00:33:06 +00:00
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"` sets green text on a blue background
- `"bg:blue fg:bright-green"` sets bright green text on a blue background
- `"bold fg:27"` sets bold text with [ANSI color](https://i.stack.imgur.com/KTSQa.png) 27
- `"underline bg:#bf5700"` sets underlined text on a burnt orange background
feat: Add support for italic styles (#354) (#358)
2019-09-12 21:10:42 +00:00
- `"bold italic fg:purple"` sets bold italic purple text
feat: Add the ability to configure per-module color styles (#285) Add parsing logic, config support, docs, and integration with other modules for custom styling of each module.
2019-09-08 00:33:06 +00:00
- `""` explicitly disables all styling
feat: Add support for italic styles (#354) (#358)
2019-09-12 21:10:42 +00:00
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.
feat: Add the ability to configure per-module color styles (#285) Add parsing logic, config support, docs, and integration with other modules for custom styling of each module.
2019-09-08 00:33:06 +00:00
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
#### Conditional Format Strings
A conditional format string wrapped in `(` and `)` will not render if all variables inside are empty.
For example:
- `(@$region)` will show nothing if the variable `region` is `None`, otherwise `@` followed by the value of region.
- `(some text)` will always show nothing since there are no variables wrapped in the braces.
- When `$all` is a shortcut for `\[$a$b\] `, `($all)` will show nothing only if `$a` and `$b` are both `None`.
This works the same as `(\[$a$b\] )`.
#### Escapable characters
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 (`\`).
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
- \$
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
- \\
- [
- ]
- (
- )
Note that `toml` has [its own escape syntax](https://github.com/toml-lang/toml#user-content-string).
It is recommended to use a literal string (`''`) in your config.
If you want to use a basic string (`""`), pay attention to escape the backslash `\`.
For example, when you want to print a `$` symbol on a new line, the following configs for `format` are equivalent:
```toml
# with basic string
format = "\n\\$"
# with multiline basic string
format = """
\\$"""
# with literal string
format = '''
\$'''
```
feat: Add configuration for add_newline (#116) - Replace TableExt with a Config trait that extends toml::value::Table Add configuration for add_newline - add_newline is a root-level configuration value. When set to false, the initial newline before the prompt is removed.
2019-07-27 22:25:13 +00:00
## Prompt
This is the list of prompt-wide configuration options.
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| -------------- | ------------------------------ | ----------------------------------------------------- |
| `format` | [link](#default-prompt-format) | Configure the format of the prompt. |
| `scan_timeout` | `30` | Timeout for starship to scan files (in milliseconds). |
fix: re-add add_newline to root config (#1598)
2020-08-18 16:58:29 +00:00
| `add_newline` | `true` | Add a new line before the start of the prompt. |
feat: Add configuration for add_newline (#116) - Replace TableExt with a Config trait that extends toml::value::Table Add configuration for add_newline - add_newline is a root-level configuration value. When set to false, the initial newline before the prompt is removed.
2019-07-27 22:25:13 +00:00
### Example
```toml
# ~/.config/starship.toml
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
# Use custom format
format = """
[┌───────────────────>](bold green)
[│](bold green)$directory$rust$package
[└─>](bold green) """
feat: Add an option to limit the duration of starship directory scanning (#589)
2019-10-28 13:41:16 +00:00
# Wait 10 milliseconds for starship to check files under the current directory.
scan_timeout = 10
fix: re-add add_newline to root config (#1598)
2020-08-18 16:58:29 +00:00
# Disable the newline at the start of the prompt
add_newline = false
feat: Add configuration for add_newline (#116) - Replace TableExt with a Config trait that extends toml::value::Table Add configuration for add_newline - add_newline is a root-level configuration value. When set to false, the initial newline before the prompt is removed.
2019-07-27 22:25:13 +00:00
```
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Default Prompt Format
docs: Add undocumented config options (#262)
2019-08-29 17:09:36 +00:00
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
The default `format` is used to define the format of the prompt, if empty or no `format` is provided. The default is as shown:
docs: Add undocumented config options (#262)
2019-08-29 17:09:36 +00:00
docs: Reword the default prompt_order docs
2019-09-13 14:24:07 +00:00
```toml
fix: re-add add_newline to root config (#1598)
2020-08-18 16:58:29 +00:00
format = "$all"
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
# Which is equivalent to
format = """
$username\
$hostname\
feat(shlvl): Add shlvl module (#1385) * initial commit of support for shlvl * documentation for shlvl * use a symbol instead * test coverage for shlvl * actually disable when the config says to * fix docs * tweak defaults some * refactor from pr comments * redisable * return early to avoid indenting * make default suffix empty space * fixing tests after suffix change * updating docs for format * making shlvl compatible with formatting * adding variables table for shlvl * removing extra line * doc clarity
2020-08-05 16:30:01 +00:00
$shlvl\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$kubernetes\
$directory\
$git_branch\
$git_commit\
$git_state\
$git_status\
$hg_branch\
$docker_context\
$package\
feat(cmake): Add CMake module (#1456) * feat: CMake module * docs: Document symbol variable
2020-07-09 19:40:33 +00:00
$cmake\
feat(dart): add Dart module (#1392)
2020-07-29 15:38:23 +00:00
$dart\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$dotnet\
$elixir\
$elm\
$erlang\
$golang\
feat(helm): Add Helm module (#1463) Signed-off-by: Furkan <furkan.turkal@hotmail.com> Co-authored-by: Furkan <furkan.turkal@hotmail.com>
2020-07-17 07:51:25 +00:00
$helm\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$java\
$julia\
feat(kotlin): Add the kotlin module (#2026) Add a module to show the currently installed Kotlin version if a .kt/.kts file is found in the current folder
2020-12-26 14:26:50 +00:00
$kotlin\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$nim\
$nodejs\
$ocaml\
feat(perl): Added perl version module (#1382) Adds a module for perl support.
2020-08-04 16:22:44 +00:00
$perl\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$php\
$purescript\
$python\
$ruby\
$rust\
feat(swift): add Swift module (#1261)
2020-07-29 15:36:49 +00:00
$swift\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$terraform\
feat(vagrant): Add support for Vagrant (#1812) Signed-off-by: Dentrax <furkan.turkal@hotmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-30 11:05:16 +00:00
$vagrant\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$zig\
$nix_shell\
$conda\
$memory_usage\
$aws\
feat: Add gcloud module (#1493) * feat(gcloud): Add document of gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * feat(gcloud): Add gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * feat(gcloud): Add test for gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * Apply the comment https://github.com/starship/starship/pull/1493\#discussion_r456965413 Signed-off-by: dulltz <isrgnoe@gmail.com>
2020-08-03 21:30:20 +00:00
$gcloud\
feat(openstack): Add module for OpenStack (#1664) * first (crude) attempt to implement the openstack module * Attempt to follow OpenStack standards for clouds.yaml location * fmt * provide unittest * add documentation * fix fmt * fix clippy * fix clippy * fix fmt * fix small nitpicks * expand openstack explanation * load config file using find_map * fix fmt * add test for valid config, plus fix test for invalid config * fix fmt * re-add forgotten comment
2020-10-24 09:46:43 +00:00
$openstack\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$env_var\
$crystal\
$custom\
feat: Move cmd_duration after custom module (#1681)
2020-12-05 18:57:22 +00:00
$cmd_duration\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$line_break\
feat(lua): Add a Lua module (#1815) * feat: add lua module * docs: add lua module * fix: lua version test * feat: lua module can be detected if the current dir contains a "lua" dir * feat: enable to use luajit * fix: improve regex * fix based on https://github.com/starship/starship/pull/1815#discussion_r510932742 * fix based on https://github.com/starship/starship/pull/1815#discussion_r511362581 * fix based on https://github.com/starship/starship/pull/1815#discussion_r510941252
2020-10-27 18:05:20 +00:00
$lua\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$jobs\
$battery\
$time\
feat(status): add the status module (#1651) * add the exit code module this allows to display more precisely the last command exit code and to configure starship to not change the last charcter of the prompt even in case of failure. It is disabled by default, because it seems a bit redundant with the character module in its default configuration. * rename exit_code module to status * Enforce a default disabled=true In the outer places, we only check for the disabled flag in the config toml file, only when this is loaded into the real config struct, we see the default. And if the default is true, we have to abort at that place. For status and hg_branch that wasn't so. I also commented the rest * fix spaces in markdown table for status module * Add a tip that status module is disabled by default Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Remove unrelated changes for default disabled=true Co-authored-by: Gaëtan Lehmann <gaetan.lehmann@gmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-25 22:04:51 +00:00
$status\
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
$character"""
feat: Add configuration for reordering the prompt module and disabling default order (#171) Adds functionality for reordering the prompt module through the use of the prompt_order configuration option in starship.toml
2019-08-19 04:35:11 +00:00
```
feat: Add AWS module (#419) Adds a module for displaying the current AWS profile based on the AWS_PROFILE envar.
2019-09-26 02:55:47 +00:00
## AWS
feat: Show AWS region in `aws` module (#482)
2019-10-14 15:05:03 +00:00
The `aws` module shows the current AWS region and profile. This is based on
`AWS_REGION`, `AWS_DEFAULT_REGION`, and `AWS_PROFILE` env var with
`~/.aws/config` file.
feat: Add AWS module (#419) Adds a module for displaying the current AWS profile based on the AWS_PROFILE envar.
2019-09-26 02:55:47 +00:00
feat(aws): Use AWS_VAULT as the profile if set (#984) * Use AWS_VAULT as the profile if set [aws-vault](https://github.com/99designs/aws-vault) sets the `AWS_VAULT` env var instead of `AWS_PROFILE` when an aws-vault session is active. This PR adds support for reading the AWS profile value from the `AWS_VAULT` env var, giving priority to `AWS_VAULT` if both it and `AWS_PROFILE` are set. * Update docs for AWS_VAULT
2020-04-06 14:59:56 +00:00
When using [aws-vault](https://github.com/99designs/aws-vault) the profile
is read from the `AWS_VAULT` env var.
feat: Add AWS module (#419) Adds a module for displaying the current AWS profile based on the AWS_PROFILE envar.
2019-09-26 02:55:47 +00:00
### Options
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Default | Description |
| ---------------- | ---------------------------------------------- | --------------------------------------------------------------- |
| `format` | `'on [$symbol$profile(\($region\))]($style) '` | The format for the module. |
| `symbol` | `"☁️ "` | The symbol used before displaying the current AWS profile. |
| `region_aliases` | | Table of region aliases to display in addition to the AWS name. |
| `style` | `"bold yellow"` | The style for the module. |
| `disabled` | `false` | Disables the `AWS` module. |
feat: Add AWS module (#419) Adds a module for displaying the current AWS profile based on the AWS_PROFILE envar.
2019-09-26 02:55:47 +00:00
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | ---------------- | ------------------------------------ |
| region | `ap-northeast-1` | The current AWS region |
| profile | `astronauts` | The current AWS profile |
| 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
### Examples
#### Display everything
```toml
# ~/.config/starship.toml
[aws]
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
format = 'on [$symbol$profile(\($region\))]($style) '
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
style = "bold blue"
symbol = "🅰 "
[aws.region_aliases]
ap-southeast-2 = "au"
us-east-1 = "va"
```
#### Display region
feat: Add AWS module (#419) Adds a module for displaying the current AWS profile based on the AWS_PROFILE envar.
2019-09-26 02:55:47 +00:00
```toml
# ~/.config/starship.toml
[aws]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "on [$symbol$region]($style) "
feat: Add AWS module (#419) Adds a module for displaying the current AWS profile based on the AWS_PROFILE envar.
2019-09-26 02:55:47 +00:00
style = "bold blue"
symbol = "🅰 "
feat: Implement AWS region aliases (#646)
2019-12-20 17:30:47 +00:00
[aws.region_aliases]
ap-southeast-2 = "au"
us-east-1 = "va"
feat: Add AWS module (#419) Adds a module for displaying the current AWS profile based on the AWS_PROFILE envar.
2019-09-26 02:55:47 +00:00
```
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
#### Display profile
```toml
# ~/.config/starship.toml
[aws]
format = "on [$symbol$profile]($style) "
style = "bold blue"
symbol = "🅰 "
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## Battery
The `battery` module shows how charged the device's battery is and its current charging status.
The module is only visible when the device's battery is below 10%.
### Options
feat(battery): make module behaviour more obvious (#1950)
2021-01-01 11:16:55 +00:00
| Option | Default | Description |
| -------------------- | --------------------------------- | --------------------------------------------------- |
| `full_symbol` | `""` | The symbol shown when the battery is full. |
| `charging_symbol` | `""` | The symbol shown when the battery is charging. |
| `discharging_symbol` | `""` | The symbol shown when the battery is discharging. |
| `unknown_symbol` | `""` | The symbol shown when the battery state is unknown. |
| `empty_symbol` | `""` | The symbol shown when the battery state is empty. |
| `format` | `"[$symbol$percentage]($style) "` | The format for the module. |
| `display` | [link](#battery-display) | Display threshold and style for the module. |
| `disabled` | `false` | Disables the `battery` module. |
fix: Add display for unknown battery state (#316)
2019-09-20 16:52:54 +00:00
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Example
```toml
# ~/.config/starship.toml
[battery]
full_symbol = "🔋"
charging_symbol = "⚡️"
discharging_symbol = "💀"
```
feat: Implement threshold based styling for battery module (#318)
2019-09-12 18:06:59 +00:00
### 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. The default is as shown:
```toml
[[battery.display]]
threshold = 10
style = "bold red"
```
#### Options
The `display` option is an array of the following table.
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Description |
feat: add support for logical paths in directory (#366) Adds the ability for starship to display the logical path instead of the physical path.
2019-09-20 16:28:09 +00:00
| ----------- | ----------------------------------------------- |
feat: Implement threshold based styling for battery module (#318)
2019-09-12 18:06:59 +00:00
| `threshold` | The upper bound for the display option. |
| `style` | The style used if the display option is in use. |
#### Example
```toml
[[battery.display]] # "bold red" style when capacity is between 0% and 10%
threshold = 10
style = "bold red"
[[battery.display]] # "bold yellow" style when capacity is between 10% and 30%
threshold = 30
style = "bold yellow"
# when capacity is over 30%, the battery indicator will not be displayed
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## Character
The `character` module shows a character (usually an arrow) beside where the text
is entered in your terminal.
docs: Small doc touch-ups (#176)
2019-08-17 20:38:20 +00:00
The character will tell you whether the last command was successful or not. It
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
can do this in two ways:
- changing color (`red`/`green`)
- changing shape (`❯`/`✖`)
By default it only changes color. If you also want to change it's shape take a
look at [this example](#with-custom-error-shape).
feat(python): Configure when the module is shown (#2264) This makes it possible to configure when the python module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. This includes a breaking change since we are removing the `scan_for_pyfiles` configuration option in favour of setting the `detect_extensions` to an empty array.
2021-02-07 21:18:52 +00:00
feat: add support for elvish shell (#1725) * feat: add support for elvish shell * improve doc * elvish 0.15 is out * fix example init * update systax for 0.15 stable * udpate second init example too * remove warning from swift module * add warning to status module docs * prefix elvish version with v
2021-02-02 11:59:55 +00:00
::: warning
`error_symbol` is not supported on elvish shell.
:::
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------------- | ------------------- | -------------------------------------------------------------------------------- |
| `format` | `"$symbol "` | The format string used before the text input. |
| `success_symbol` | `"[❯](bold green)"` | The format string used before the text input if the previous command succeeded. |
| `error_symbol` | `"[❯](bold red)"` | The format string used before the text input if the previous command failed. |
| `vicmd_symbol` | `"[❮](bold green)"` | The format string used before the text input if the shell is in vim normal mode. |
| `disabled` | `false` | Disables the `character` module. |
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | ------- | --------------------------------------------------------------------- |
| symbol | | A mirror of either `success_symbol`, `error_symbol` or `vicmd_symbol` |
### Examples
#### With custom error shape
```toml
# ~/.config/starship.toml
[character]
success_symbol = "[➜](bold green) "
error_symbol = "[✗](bold red) "
```
#### Without custom error shape
```toml
# ~/.config/starship.toml
[character]
success_symbol = "[➜](bold green) "
error_symbol = "[➜](bold red) "
```
#### With custom vim shape
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```toml
# ~/.config/starship.toml
[character]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
vicmd_symbol = "[V](bold green) "
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```
feat(cmake): Add CMake module (#1456) * feat: CMake module * docs: Document symbol variable
2020-07-09 19:40:33 +00:00
## CMake
feat(cmake): Configure when the module is shown (#2280) This makes it possible to configure when the cmake module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module.
2021-02-13 10:38:47 +00:00
The `cmake` module shows the currently installed version of CMake. By default
the module will be activated if any of the following conditions are met:
feat(cmake): Add CMake module (#1456) * feat: CMake module * docs: Document symbol variable
2020-07-09 19:40:33 +00:00
- The current directory contains a `CMakeLists.txt` file
feat(cmake): Add CMakeCache.txt detection to CMake module (#1795) * Add CMakeCache.txt to cmake module * Remove trailing whitespace * Apply fixes by @andytom * Add CMakeCache.txt to docs * Revert documentation for languages other than en
2020-10-25 18:10:42 +00:00
- The current directory contains a `CMakeCache.txt` file
feat(cmake): Add CMake module (#1456) * feat: CMake module * docs: Document symbol variable
2020-07-09 19:40:33 +00:00
### Options
feat(cmake): Configure when the module is shown (#2280) This makes it possible to configure when the cmake module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module.
2021-02-13 10:38:47 +00:00
| Option | Default | Description |
| ------------------- | -------------------------------------- | -------------------------------------------- |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `symbol` | `"喝 "` | The symbol used before the version of cmake. |
| `detect_extensions` | `[]` | Which extensions should trigger this moudle |
| `detect_files` | `["CMakeLists.txt", "CMakeCache.txt"]` | Which filenames should trigger this module |
| `detect_folders` | `[]` | Which folders should trigger this module |
| `style` | `"bold blue"` | The style for the module. |
| `disabled` | `false` | Disables the `cmake` module. |
feat(cmake): Add CMake module (#1456) * feat: CMake module * docs: Document symbol variable
2020-07-09 19:40:33 +00:00
### Variables
| Variable | Example | Description |
| -------- | --------- | ------------------------------------ |
| version | `v3.17.3` | The version of cmake |
| 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
feat: implement timer module (#118) Implement a timer module that takes a commandline argument, the number of seconds the last job took to complete, and displays it if appropriate. Alters shell initialization files to compute this number using date +%s where needed. Adds a config section to configure minimum amount of time before timer is shown (default is 2s)
2019-08-08 17:25:30 +00:00
## Command Duration
The `cmd_duration` module shows how long the last command took to execute.
revert: Revert the command duration in ms feature (#380) (#425) Due to incompatibilities with the macOS date utility, we are temporarily reverting this feature. Refs: #c5e971a
2019-09-25 08:13:58 +00:00
The module will be shown only if the command took longer than two seconds, or
feat: implement timer module (#118) Implement a timer module that takes a commandline argument, the number of seconds the last job took to complete, and displays it if appropriate. Alters shell initialization files to compute this number using date +%s where needed. Adds a config section to configure minimum amount of time before timer is shown (default is 2s)
2019-08-08 17:25:30 +00:00
the `min_time` config value, if it exists.
docs: Small doc touch-ups (#176)
2019-08-17 20:38:20 +00:00
::: warning Do not hook the DEBUG trap in Bash
docs: Add extra newlines around custom containers
2019-09-28 11:20:18 +00:00
feat: implement `cmd_duration` for bash (#144)
2019-08-14 02:49:47 +00:00
If you are running Starship in `bash`, do not hook the `DEBUG` trap after running
`eval $(starship init $0)`, or this module **will** break.
docs: Add extra newlines around custom containers
2019-09-28 11:20:18 +00:00
feat: implement timer module (#118) Implement a timer module that takes a commandline argument, the number of seconds the last job took to complete, and displays it if appropriate. Alters shell initialization files to compute this number using date +%s where needed. Adds a config section to configure minimum amount of time before timer is shown (default is 2s)
2019-08-08 17:25:30 +00:00
:::
feat: implement `cmd_duration` for bash (#144)
2019-08-14 02:49:47 +00:00
Bash users who need preexec-like functionality can use
[rcaloras's bash_preexec framework](https://github.com/rcaloras/bash-preexec).
docs: Small doc touch-ups (#176)
2019-08-17 20:38:20 +00:00
Simply define the arrays `preexec_functions` and `precmd_functions` before
feat: implement `cmd_duration` for bash (#144)
2019-08-14 02:49:47 +00:00
running `eval $(starship init $0)`, and then proceed as normal.
feat: implement timer module (#118) Implement a timer module that takes a commandline argument, the number of seconds the last job took to complete, and displays it if appropriate. Alters shell initialization files to compute this number using date +%s where needed. Adds a config section to configure minimum amount of time before timer is shown (default is 2s)
2019-08-08 17:25:30 +00:00
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ------------------- | ----------------------------- | ---------------------------------------------------------- |
| `min_time` | `2_000` | Shortest duration to show time for (in milliseconds). |
| `show_milliseconds` | `false` | Show milliseconds in addition to seconds for the duration. |
| `format` | `"took [$duration]($style) "` | The format for the module. |
| `style` | `"bold yellow"` | The style for the module. |
| `disabled` | `false` | Disables the `cmd_duration` module. |
docs(cmd_duration): Document cmd_duration notifications (#1831) * docs: add options for cmd_duration notifications Added in #1019 * Update docs/config/README.md Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-11-04 17:53:51 +00:00
| `show_notifications`| `false` | Show desktop notifications when command completes. |
| `min_time_to_notify`| `45_000` | Shortest duration for notification (in milliseconds). |
::: tip
Showing desktop notifications requires starship to be built with `rust-notify` support. You check if your starship
supports notifications by running `STARSHIP_LOG=debug starship module cmd_duration -d 60000` when `show_notifications` is set to `true`.
:::
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | -------- | --------------------------------------- |
| duration | `16m40s` | The time it took to execute the command |
| style\* | | Mirrors the value of option `style` |
\*: This variable can only be used as a part of a style string
feat: implement timer module (#118) Implement a timer module that takes a commandline argument, the number of seconds the last job took to complete, and displays it if appropriate. Alters shell initialization files to compute this number using date +%s where needed. Adds a config section to configure minimum amount of time before timer is shown (default is 2s)
2019-08-08 17:25:30 +00:00
### Example
```toml
# ~/.config/starship.toml
[cmd_duration]
feat: cmd_duration module optionally reports milliseconds (#696)
2019-12-19 22:38:06 +00:00
min_time = 500
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "underwent [$duration](bold yellow)"
feat: implement timer module (#118) Implement a timer module that takes a commandline argument, the number of seconds the last job took to complete, and displays it if appropriate. Alters shell initialization files to compute this number using date +%s where needed. Adds a config section to configure minimum amount of time before timer is shown (default is 2s)
2019-08-08 17:25:30 +00:00
```
feat: Add conda module (#469)
2019-10-05 18:25:25 +00:00
## Conda
The `conda` module shows the current conda environment, if `$CONDA_DEFAULT_ENV` is set.
fix: Truncate long paths in conda environment names (#694) Environment names created via conda create -p [path] tend to be too long for comfort, so this truncates them.
2019-12-09 17:59:02 +00:00
::: tip
This does not suppress conda's own prompt modifier, you may want to run `conda config --set changeps1 False`.
:::
feat: Add conda module (#469)
2019-10-05 18:25:25 +00:00
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `truncation_length` | `1` | The number of directories the environment path should be truncated to, if the environment was created via `conda create -p [path]`. `0` means no truncation. Also see the [`directory`](#directory) module. |
| `symbol` | `"🅒 "` | The symbol used before the environment name. |
| `style` | `"bold green"` | The style for the module. |
docs(conda): Fix default format in Conda module's config doc (#1965) * docs: Fix default format string for Conda module #### Issues Addressed The default `format` string for the Conda module starts with "via", as seen [here](https://github.com/starship/starship/blob/2e763b5e7c41dd556c9515bdc36297bc177d7f46/src/configs/conda.rs#L19). However, this is not reflected in the config docs. Many similar modules include "via" in their default format string so I assume including it is the intended behavior, and that the doc should be updated. #### Summary of Changes Correct the default `format` string for the Conda module in the config docs. * Revert changes to i18n files Revert changes to i18n files, as these must be handled by Crowdin
2020-12-06 20:02:15 +00:00
| `format` | `"via [$symbol$environment]($style) "` | The format for the module. |
feat(conda): add ignore_base option (#1539) * Add ignore_base to conda module * Add ignore_base to conda module in English docs * `ignore_base` defaults to `true`
2020-07-30 16:57:15 +00:00
| `ignore_base` | `true` | Ignores `base` environment when activated. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `disabled` | `false` | Disables the `conda` module. |
### Variables
| Variable | Example | Description |
| ----------- | ------------ | ------------------------------------ |
| environment | `astronauts` | The current conda environment |
| 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
feat: Add conda module (#469)
2019-10-05 18:25:25 +00:00
### Example
```toml
# ~/.config/starship.toml
[conda]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "[$symbol$environment](dimmed green) "
feat: Add conda module (#469)
2019-10-05 18:25:25 +00:00
```
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
## Crystal
The `crystal` module shows the currently installed version of Crystal.
feat(crystal): Configure when the module is shown (#2310) * feat(crystal): Configure when the module is shown This makes it possible to configure when the crystal module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. * Update docs/config/README.md Co-authored-by: David Knaack <davidkna@users.noreply.github.com> Co-authored-by: David Knaack <davidkna@users.noreply.github.com>
2021-02-14 17:14:55 +00:00
By default the module will be shown if any of the following conditions are met:
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
- The current directory contains a `shard.yml` file
- The current directory contains a `.cr` file
### Options
feat(crystal): Configure when the module is shown (#2310) * feat(crystal): Configure when the module is shown This makes it possible to configure when the crystal module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. * Update docs/config/README.md Co-authored-by: David Knaack <davidkna@users.noreply.github.com> Co-authored-by: David Knaack <davidkna@users.noreply.github.com>
2021-02-14 17:14:55 +00:00
| Option | Default | Description |
| ------------------- | ------------------------------------ | --------------------------------------------------------- |
| `symbol` | `"🔮 "` | The symbol used before displaying the version of crystal. |
| `style` | `"bold red"` | The style for the module. |
| `detect_extensions` | `["cr"]` | Which extensions should trigger this module. |
| `detect_files` | `["shard.yml"]` | Which filenames should trigger this module. |
| `detect_folders` | `[]` | Which folders should trigger this module. |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `disabled` | `false` | Disables the `crystal` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | --------- | ------------------------------------ |
| version | `v0.32.1` | The version of `crystal` |
| 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
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
### Example
```toml
# ~/.config/starship.toml
[crystal]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "via [✨ $version](bold blue) "
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
```
feat(dart): add Dart module (#1392)
2020-07-29 15:38:23 +00:00
## Dart
The `dart` module shows the currently installed version of Dart.
feat(dart): Configure when the module is shown (#2312) * feat(dart): Configure when the module is shown This makes it possible to configure when the dart module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. * docs(dart): add missing detected files * removed invalid comment
2021-02-14 21:21:52 +00:00
By default the module will be shown if any of the following conditions are met:
feat(dart): add Dart module (#1392)
2020-07-29 15:38:23 +00:00
- The current directory contains a file with `.dart` extension
- The current directory contains a `.dart_tool` directory
feat(dart): Configure when the module is shown (#2312) * feat(dart): Configure when the module is shown This makes it possible to configure when the dart module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. * docs(dart): add missing detected files * removed invalid comment
2021-02-14 21:21:52 +00:00
- The current directory contains a `pubspec.yaml`, `pubspec.yml` or `pubspec.lock` file
feat(dart): add Dart module (#1392)
2020-07-29 15:38:23 +00:00
### Options
feat(dart): Configure when the module is shown (#2312) * feat(dart): Configure when the module is shown This makes it possible to configure when the dart module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. * docs(dart): add missing detected files * removed invalid comment
2021-02-14 21:21:52 +00:00
| Option | Default | Description |
| ------------------- | ------------------------------------------------- | ----------------------------------------------- |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `symbol` | `"🎯 "` | A format string representing the symbol of Dart |
| `detect_extensions` | `['dart']` | Which extensions should trigger this moudle. |
| `detect_files` | `["pubspec.yaml", "pubspec.yml", "pubspec.lock"]` | Which filenames should trigger this module. |
| `detect_folders` | `[".dart_tool"]` | Which folders should trigger this module. |
| `style` | `"bold blue"` | The style for the module. |
| `disabled` | `false` | Disables the `dart` module. |
feat(dart): add Dart module (#1392)
2020-07-29 15:38:23 +00:00
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `v2.8.4` | The version of `dart` |
| 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
### Example
```toml
# ~/.config/starship.toml
[dart]
format = "via [🔰 $version](bold red) "
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## 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.
feat: Add ability to use an alternate directory truncation style (#239) * Add ability to use an alternate directory truncation style
2019-08-27 01:52:45 +00:00
When using the fish style pwd option, instead of hiding the path that is
truncated, you will see a shortened name of each directory based on the number
you enable for the option.
For example, given `~/Dev/Nix/nixpkgs/pkgs` where `nixpkgs` is the repo root,
and the option set to `1`. You will now see `~/D/N/nixpkgs/pkgs`, whereas before
it would have been `nixpkgs/pkgs`.
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Options
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Default | Description |
docs(directory): fix $read_only variable names Fixes #1706
2020-09-30 22:38:57 +00:00
| ------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------- |
| `truncation_length` | `3` | The number of parent folders that the current directory should be truncated to. |
| `truncate_to_repo` | `true` | Whether or not to truncate to the root of the git repo that you're currently in. |
| `format` | `"[$path]($style)[$read_only]($read_only_style) "` | The format for the module. |
| `style` | `"bold cyan"` | The style for the module. |
| `disabled` | `false` | Disables the `directory` module. |
| `read_only` | `"🔒"` | The symbol indicating current directory is read only. |
| `read_only_style` | `"red"` | The style for the read only symbol. |
feat(directory): add ellipsis to truncated paths (#1563) Adds ellipsis in front of truncated paths: …/ Configurable through new config option: directory.truncation_symbol Fixes #1162, #1626
2020-10-03 16:25:21 +00:00
| `truncation_symbol` | `""` | The symbol to prefix to truncated paths. eg: "…/" |
feat(directory): Add home directory symbol (#2198) * feat(directory): Add home directory symbol * Replace HOME_SYMBOL constant as a config variable
2021-01-24 21:50:37 +00:00
| `home_symbol` | `"~"` | The symbol indicating home directory. |
feat: add support for logical paths in directory (#366) Adds the ability for starship to display the logical path instead of the physical path.
2019-09-20 16:28:09 +00:00
<details>
<summary>This module has a few advanced configuration options that control how the directory is displayed.</summary>
refactor(directory): Introduce `logical-path` argument which allows a shell to explicitly specify both a logical and physical filesystem path (#2104) * refactor(directory): Introduce `logical-path` argument which allows a shell to explicitly specify both a logical and physical filesystem path Fix `directory::module` to consume both path and logical-path (if provided). The "logical" path is preferred when rendering the "display path", while the "physical" path is used to resolve the "read only" flag. Repo- and home-directory contraction behavior is maintained, based on the logical path if it is set, or the physical path if it is not. The custom "get_current_dir" logic has been removed entirely, and the `directory` module now relies on `context.current_dir` / `context.logical_dir` entirely. Changes have been made to `init/starship.ps1` to work with this new flag: - Calculate and pass "physical" and "logical" paths explicitly (as other shells do not pass `--logical-path` that they fall back to rendering the physical path) - Moved the "powershell provider prefix" cleanup code to the PowerShell script - this code _should_ now support any kind of powershell path prefix. * fix(powershell): Fix an issue with trailing backslashes on file paths causing command line parsing issues. This is a bit of a footgun! The work-around chosen is to append a trailing space when a path string ends with a backslash, and then trim any extra whitespace away in the Context constructor. Other alternatives considered and rejected: 1. Always trim trailing backslashes as the filesystem generally doesn't need them. 2. Escape trailing backslashes with another backslash. This proved complex as PS only quotes string args when the string includes some whitespace, and other backslashes within the string apparently don't need to be escaped. * fix(powershell): Use Invoke-Native pattern for safely invoking native executables with strings which may contain characters which need to be escaped carefully. * fix(context): Remove superfluous argument trims These were in place to clean up extra whitespace sometimes injected by starship.ps1::prompt, and are no longer required with the new Invoke-Native helper in place. * refactor(directory): Clean up the semantics of `logical_dir` defaulting it to `current_dir` but overridable by the `--logical-dir` flag. - Restore `use_logical_path` config flag. - Always attempt to contract repo paths from the `current_dir`. * fix(directory) :Use logical_dir for contracting the home directory This keeps the two calls to contract_path in sync. * fix(directory): Remove test script * refactor(directory): Convert current_dir to canonical filesystem path when use_logical_path = false - This requires some clean-up to remove the extended-path prefix on Windows - The configured logical_dir is ignored entirely in this mode - we calculate a new logical_dir by cleaning up the physical_dir path for display. - Test coverage * fix(directory): Use AsRef style for passing Path arguments * fix(directory): Strip the windows extended-path prefix from the display string later in the render process * fix(docs): Update docs/config/README.md for use_logical_path * refactor(context): Populate `current_dir` from `--path` or `std::env::current_dir`, populate `logical_dir` from `--logical-path` or the `PWD` env var - `current_dir` is always canonicalized - On Windows, `current_dir` will have an extended-path prefix - `logical_dir` is now always set - `directory::module` now just selects between `current_dir` and `logical_dir` when picking which path to render - Test coverage * fix(directory): Fix path comparison operations in directory to ignore differences between path prefixes - Added PathExt extension trait which adds `normalised_equals`, `normalised_starts_with` and `without_prefix` * fix(path): Add test coverage for PathExt on *nix * fix(directory): Test coverage for `contract_repo_path`, `contract_path` with variations of verbatim and non-verbatim paths * fix(directory): Update path-slash to latest This fixes the issue with the trailing character of some Windows paths being truncated, e.g. `\\server\share` and `C:` * fix(powershell): Improve UTF8 output handling, argument encoding - Use `ProcessStartInfo` to launch native executable, replacing manual UTF8 output encoding handling - If we detect we're on PWSH6+ use the new `System.Diagnostics.ProcessStartInfo.ArgumentList` parameter, otherwise manually escape the argument string - Move `Get-Cwd` and `Invoke-Native` into the prompt function scope so that they don't leak into the user's shell scope * fix(path): Make PathExt methods no-ops on *nix * fix(path): Cargo fmt * fix(powershell): Remove typo ';'. Fix variable assignment lint.
2021-02-08 14:14:59 +00:00
| Advanced Option | Default | Description |
| --------------------------- | ------- | ------------------------------------------------------------------------- |
| `substitutions` | | A table of substitutions to be made to the path. |
| `fish_style_pwd_dir_length` | `0` | The number of characters to use when applying fish shell pwd path logic. |
| `use_logical_path` | `true` | If `true` render the logical path sourced from the shell via `PWD` or `--logical-path`. If `false` instead render the physical filesystem path with symlinks resolved. |
feat: add support for logical paths in directory (#366) Adds the ability for starship to display the logical path instead of the physical path.
2019-09-20 16:28:09 +00:00
feat(directory): Add directory substitutions (#1183) Adds an option to provide a table of strings to substitute in the directory string. Fixes #1065. Co-authored-by: Radu Butoi <butoi@google.com>
2020-05-31 17:32:35 +00:00
`substitutions` allows you to define arbitrary replacements for literal strings that occur in the path, for example long network
prefixes or development directories (i.e. Java). Note that this will disable the fish style PWD.
```toml
[directory.substitutions]
"/Volumes/network/path" = "/net"
"src/com/long/java/path" = "mypath"
```
docs: Update docs w/ details on fish-style truncation (#948)
2020-02-21 00:08:20 +00:00
`fish_style_pwd_dir_length` interacts with the standard truncation options in a way that can be surprising at first: if it's non-zero,
the components of the path that would normally be truncated are instead displayed with that many characters. For example, the path
`/built/this/city/on/rock/and/roll`, which would normally be displayed as as `rock/and/roll`, would be displayed as
`/b/t/c/o/rock/and/roll` with `fish_style_pwd_dir_length = 1`--the path components that would normally be removed are displayed with
a single character. For `fish_style_pwd_dir_length = 2`, it would be `/bu/th/ci/on/rock/and/roll`.
feat: add support for logical paths in directory (#366) Adds the ability for starship to display the logical path instead of the physical path.
2019-09-20 16:28:09 +00:00
</details>
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | --------------------- | ----------------------------------- |
| path | `"D:/Projects"` | The current directory path |
| style\* | `"black bold dimmed"` | Mirrors the value of option `style` |
\*: This variable can only be used as a part of a style string
feat: Allow directory truncation length to be configured (#120) This allows the directory truncation length to be configured. Previously, it was hard-coded to truncate to 3 parent directories.
2019-07-29 01:05:13 +00:00
### Example
```toml
# ~/.config/starship.toml
[directory]
truncation_length = 8
feat(directory): add ellipsis to truncated paths (#1563) Adds ellipsis in front of truncated paths: …/ Configurable through new config option: directory.truncation_symbol Fixes #1162, #1626
2020-10-03 16:25:21 +00:00
truncation_symbol = "…/"
feat: Allow directory truncation length to be configured (#120) This allows the directory truncation length to be configured. Previously, it was hard-coded to truncate to 3 parent directories.
2019-07-29 01:05:13 +00:00
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
feat: add docker context module (#996) * feat: add docker context module Adds a simple module that checks for a Docker config file and if present, reads the `currentContext` value out and displays on the prompt with a whale. * feat: add `only_with_compose_yml` option to docker_context When enabled, will only show the docker context name if there's a docker-compose.yml file in the current directory. * Update src/modules/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * Update src/modules/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * rename `only_with_compose_yml` configuration key to a more generic `only_with_files` * Update src/modules/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * re-order configuration table * Update docs/config/README.md Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * Update src/configs/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-04-05 19:42:55 +00:00
## Docker Context
The `docker_context` module shows the currently active
[Docker context](https://docs.docker.com/engine/context/working-with-contexts/) if it's not set to
`default`.
### Options
fix(docker_context): enable if either yml or yaml is found (#2053) * fix(docker_context): enable if either yml or yaml is found * Update docs
2021-01-11 16:38:58 +00:00
| Option | Default | Description |
| ----------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `format` | `"via [$symbol$context]($style) "` | The format for the module. |
| `symbol` | `"🐳 "` | The symbol used before displaying the Docker context. |
| `style` | `"blue bold"` | The style for the module. |
test(docker_context): Add basic tests to module (#2205) * test(docker_context): Add basic tests to module This adds some basic tests to the docker_context module. * PR suggestion
2021-01-26 21:46:17 +00:00
| `only_with_files` | `true` | Only show when there's a `docker-compose.yml`, `docker-compose.yaml`, or `Dockerfile` in the current directory. |
| `disabled` | `false` | Disables the `docker_context` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | -------------- | ------------------------------------ |
| context | `test_context` | The current docker context |
| 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
feat: add docker context module (#996) * feat: add docker context module Adds a simple module that checks for a Docker config file and if present, reads the `currentContext` value out and displays on the prompt with a whale. * feat: add `only_with_compose_yml` option to docker_context When enabled, will only show the docker context name if there's a docker-compose.yml file in the current directory. * Update src/modules/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * Update src/modules/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * rename `only_with_compose_yml` configuration key to a more generic `only_with_files` * Update src/modules/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * re-order configuration table * Update docs/config/README.md Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * Update src/configs/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-04-05 19:42:55 +00:00
### Example
```toml
# ~/.config/starship.toml
[docker_context]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "via [🐋 $context](blue bold)"
feat: add docker context module (#996) * feat: add docker context module Adds a simple module that checks for a Docker config file and if present, reads the `currentContext` value out and displays on the prompt with a whale. * feat: add `only_with_compose_yml` option to docker_context When enabled, will only show the docker context name if there's a docker-compose.yml file in the current directory. * Update src/modules/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * Update src/modules/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * rename `only_with_compose_yml` configuration key to a more generic `only_with_files` * Update src/modules/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * re-order configuration table * Update docs/config/README.md Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * Update src/configs/docker_context.rs Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-04-05 19:42:55 +00:00
```
feat: Add dotnet module (#416) Adds a .NET module, which preferentially parses local/git files to get the .NET version.
2019-10-02 06:56:49 +00:00
## Dotnet
The `dotnet` module shows the relevant version of the .NET Core SDK for the current directory. If
the SDK has been pinned in the current directory, the pinned version is shown. Otherwise the module
shows the latest installed version of the SDK.
feat(dotnet): adds additional files to detect .net projects (#1303) * adds additional files to detect .net projects * test .net output with a regex pattern
2020-06-21 08:22:20 +00:00
This module will only be shown in your prompt when one or more of the following files are present in the
current directory:
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
- `global.json`
- `project.json`
- `Directory.Build.props`
- `Directory.Build.targets`
- `Packages.props`
- `*.sln`
- `*.csproj`
- `*.fsproj`
- `*.xproj`
feat(dotnet): adds additional files to detect .net projects (#1303) * adds additional files to detect .net projects * test .net output with a regex pattern
2020-06-21 08:22:20 +00:00
You'll also need the .NET Core SDK installed in order to use it correctly.
feat: Add dotnet module (#416) Adds a .NET module, which preferentially parses local/git files to get the .NET version.
2019-10-02 06:56:49 +00:00
Internally, this module uses its own mechanism for version detection. Typically it is twice as fast
as running `dotnet --version`, but it may show an incorrect version if your .NET project has an
unusual directory layout. If accuracy is more important than speed, you can disable the mechanism by
setting `heuristic = false` in the module options.
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
The module will also show the Target Framework Moniker
(<https://docs.microsoft.com/en-us/dotnet/standard/frameworks#supported-target-framework-versions>)
when there is a csproj file in the current directory.
feat: Add dotnet module (#416) Adds a .NET module, which preferentially parses local/git files to get the .NET version.
2019-10-02 06:56:49 +00:00
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ----------- | ----------------------------------------- | -------------------------------------------------------- |
fix: Adjust default format strings (#2165) * fix(dotnet): update dotnet format string * fix(dotnet): update erlang format string * fix(dotnet): update golang format string * fix(dotnet): update helm format string * fix(dotnet): update julia format string * fix(dotnet): update nim format string * fix(dotnet): update ruby format string * fix(dotnet): update rust format string * test: update formatted strings in unit tests * Use suggested format strings Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Moritz Vetter <mv@3yourmind.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-20 17:46:26 +00:00
| `format` | `"[$symbol($version )(🎯 $tfm )]($style)"` | The format for the module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `symbol` | `"•NET "` | The symbol used before displaying the version of dotnet. |
| `heuristic` | `true` | Use faster version detection to keep starship snappy. |
| `style` | `"bold blue"` | The style for the module. |
| `disabled` | `false` | Disables the `dotnet` module. |
### Variables
| Variable | Example | Description |
| -------- | ---------------- | ------------------------------------------------------------------ |
| version | `v3.1.201` | The version of `dotnet` sdk |
| tfm | `netstandard2.0` | The Target Framework Moniker that the current project is targeting |
| 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
feat: Add dotnet module (#416) Adds a .NET module, which preferentially parses local/git files to get the .NET version.
2019-10-02 06:56:49 +00:00
### Example
```toml
# ~/.config/starship.toml
[dotnet]
symbol = "🥅 "
style = "green"
heuristic = false
```
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
## Elixir
The `elixir` module shows the currently installed version of Elixir and Erlang/OTP.
The module will be shown if any of the following conditions are met:
- The current directory contains a `mix.exs` file.
### Options
perf(elixir): evaluate version lazily (#2172)
2021-01-20 17:59:21 +00:00
| Option | Default | Description |
| ---------- | --------------------------------------------------------- | --------------------------------------------------------------- |
| `symbol` | `"💧 "` | The symbol used before displaying the version of Elixir/Erlang. |
| `style` | `"bold purple"` | The style for the module. |
| `format` | `'via [$symbol($version \(OTP $otp_version\) )]($style)'` | The format for the module elixir. |
| `disabled` | `false` | Disables the `elixir` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| ----------- | ------- | ------------------------------------ |
| version | `v1.10` | The version of `elixir` |
| otp_version | | The otp version of `elixir` |
| 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
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
### Example
```toml
# ~/.config/starship.toml
[elixir]
symbol = "🔮 "
```
feat: Add an Elm module (#879) Former-commit-id: d42137309da457a438b554601f0734db963a193e
2020-02-06 03:57:04 +00:00
## Elm
docs: Use Algolia DocSearch for docs
2020-02-07 17:36:23 +00:00
The `elm` module shows the currently installed version of Elm.
feat: Add an Elm module (#879) Former-commit-id: d42137309da457a438b554601f0734db963a193e
2020-02-06 03:57:04 +00:00
The module will be shown if any of the following conditions are met:
- The current directory contains a `elm.json` file
- The current directory contains a `elm-package.json` file
feat: Enable to display language version when `.<lang>-version` file exists. (#1028) * adjust https://github.com/sonnym/elmenv * adjust https://github.com/syndbg/goenv * adjust https://github.com/jenv/jenv * adjust https://github.com/nodenv/nodenv * adjust https://github.com/phpenv/phpenv * adjust https://github.com/rbenv/rbenv * add description * golang.rs is executed rustfmt * add testcases
2020-04-03 19:02:28 +00:00
- The current directory contains a `.elm-version` file
feat: Add an Elm module (#879) Former-commit-id: d42137309da457a438b554601f0734db963a193e
2020-02-06 03:57:04 +00:00
- The current directory contains a `elm-stuff` folder
- The current directory contains a `*.elm` files
### Options
perf(elm): Lazy eval elm (#2167) * perf(elm): evaluate version lazily * fix(elm): update format string * fix: use suggested format string Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-20 17:49:26 +00:00
| Option | Default | Description |
| ---------- | ------------------------------------ | ----------------------------------------------- |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `symbol` | `"🌳 "` | A format string representing the symbol of Elm. |
| `style` | `"cyan bold"` | The style for the module. |
| `disabled` | `false` | Disables the `elm` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
feat: Add an Elm module (#879) Former-commit-id: d42137309da457a438b554601f0734db963a193e
2020-02-06 03:57:04 +00:00
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Variable | Example | Description |
| -------- | --------- | ------------------------------------ |
| version | `v0.19.1` | The version of `elm` |
| 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
feat: Add an Elm module (#879) Former-commit-id: d42137309da457a438b554601f0734db963a193e
2020-02-06 03:57:04 +00:00
### Example
```toml
# ~/.config/starship.toml
[elm]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "via [ $version](cyan bold) "
feat: Add an Elm module (#879) Former-commit-id: d42137309da457a438b554601f0734db963a193e
2020-02-06 03:57:04 +00:00
```
docs: correct the configuration docs (#1195)
2020-05-13 22:19:21 +00:00
## Environment Variable
feat(erlang): Add Erlang module (#1129)
2020-04-27 10:09:42 +00:00
docs: correct the configuration docs (#1195)
2020-05-13 22:19:21 +00:00
The `env_var` module displays the current value of a selected environment variable.
The module will be shown only if any of the following conditions are met:
feat(erlang): Add Erlang module (#1129)
2020-04-27 10:09:42 +00:00
docs: correct the configuration docs (#1195)
2020-05-13 22:19:21 +00:00
- The `variable` configuration option matches an existing environment variable
- The `variable` configuration option is not defined, but the `default` configuration option is
feat(erlang): Add Erlang module (#1129)
2020-04-27 10:09:42 +00:00
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | ------------------------------ | ---------------------------------------------------------------------------- |
| `symbol` | | The symbol used before displaying the variable value. |
| `variable` | | The environment variable to be displayed. |
| `default` | | The default value to be displayed when the selected variable is not defined. |
| `format` | `"with [$env_value]($style) "` | The format for the module. |
| `disabled` | `false` | Disables the `env_var` module. |
### Variables
| Variable | Example | Description |
| --------- | ------------------------------------------- | ------------------------------------------ |
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| env_value | `Windows NT` (if _variable_ would be `$OS`) | The environment value of option `variable` |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| symbol | | Mirrors the value of option `symbol` |
| style\* | `black bold dimmed` | Mirrors the value of option `style` |
\*: This variable can only be used as a part of a style string
feat(erlang): Add Erlang module (#1129)
2020-04-27 10:09:42 +00:00
### Example
```toml
# ~/.config/starship.toml
docs: correct the configuration docs (#1195)
2020-05-13 22:19:21 +00:00
[env_var]
variable = "SHELL"
default = "unknown shell"
feat(erlang): Add Erlang module (#1129)
2020-04-27 10:09:42 +00:00
```
feat: Add Environment Variable module (#409)
2019-09-26 08:30:58 +00:00
docs: correct the configuration docs (#1195)
2020-05-13 22:19:21 +00:00
## Erlang
feat: Add Environment Variable module (#409)
2019-09-26 08:30:58 +00:00
docs: correct the configuration docs (#1195)
2020-05-13 22:19:21 +00:00
The `erlang` module shows the currently installed version of Erlang/OTP.
The module will be shown if any of the following conditions are met:
- The current directory contains a `rebar.config` file.
- The current directory contains a `erlang.mk` file.
feat: Add Environment Variable module (#409)
2019-09-26 08:30:58 +00:00
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | ---------------------------------- | -------------------------------------------------------- |
fix: replace emoji for cmake and erlang (#1787)
2020-10-13 22:01:35 +00:00
| `symbol` | `" "` | The symbol used before displaying the version of erlang. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `style` | `"bold red"` | The style for the module. |
fix: Adjust default format strings (#2165) * fix(dotnet): update dotnet format string * fix(dotnet): update erlang format string * fix(dotnet): update golang format string * fix(dotnet): update helm format string * fix(dotnet): update julia format string * fix(dotnet): update nim format string * fix(dotnet): update ruby format string * fix(dotnet): update rust format string * test: update formatted strings in unit tests * Use suggested format strings Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Moritz Vetter <mv@3yourmind.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-20 17:46:26 +00:00
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `disabled` | `false` | Disables the `erlang` module. |
### Variables
| Variable | Example | Description |
| -------- | --------- | ------------------------------------ |
| version | `v22.1.3` | The version of `erlang` |
| 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
feat: Add Environment Variable module (#409)
2019-09-26 08:30:58 +00:00
### Example
```toml
# ~/.config/starship.toml
docs: correct the configuration docs (#1195)
2020-05-13 22:19:21 +00:00
[erlang]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "via [e $version](bold red) "
feat: Add Environment Variable module (#409)
2019-09-26 08:30:58 +00:00
```
feat: Add gcloud module (#1493) * feat(gcloud): Add document of gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * feat(gcloud): Add gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * feat(gcloud): Add test for gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * Apply the comment https://github.com/starship/starship/pull/1493\#discussion_r456965413 Signed-off-by: dulltz <isrgnoe@gmail.com>
2020-08-03 21:30:20 +00:00
## 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.
### Options
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Default | Description |
| ---------------- | ---------------------------------------------- | --------------------------------------------------------------- |
| `format` | `'on [$symbol$account(\($region\))]($style) '` | The format for the module. |
| `symbol` | `"☁️ "` | The symbol used before displaying the current GCP profile. |
| `region_aliases` | | Table of region aliases to display in addition to the GCP name. |
| `style` | `"bold blue"` | The style for the module. |
| `disabled` | `false` | Disables the `gcloud` module. |
feat: Add gcloud module (#1493) * feat(gcloud): Add document of gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * feat(gcloud): Add gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * feat(gcloud): Add test for gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * Apply the comment https://github.com/starship/starship/pull/1493\#discussion_r456965413 Signed-off-by: dulltz <isrgnoe@gmail.com>
2020-08-03 21:30:20 +00:00
### Variables
| Variable | Example | Description |
| -------- | ----------------- | ------------------------------------------------------------------ |
| region | `us-central1` | The current GCP region |
| account | `foo@example.com` | The current GCP profile |
| project | | The current GCP project |
| active | `default` | The active config name written in `~/.config/gcloud/active_config` |
| 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
### Examples
#### Display account and project
```toml
# ~/.config/starship.toml
[gcloud]
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
format = 'on [$symbol$account(\($project\))]($style) '
feat: Add gcloud module (#1493) * feat(gcloud): Add document of gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * feat(gcloud): Add gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * feat(gcloud): Add test for gcloud module Signed-off-by: dulltz <isrgnoe@gmail.com> * Apply the comment https://github.com/starship/starship/pull/1493\#discussion_r456965413 Signed-off-by: dulltz <isrgnoe@gmail.com>
2020-08-03 21:30:20 +00:00
```
#### Display active config name only
```toml
# ~/.config/starship.toml
[gcloud]
format = "[$symbol$active]($style) "
style = "bold yellow"
```
#### Display account and aliased region
```toml
# ~/.config/starship.toml
[gcloud]
symbol = "️🇬️ "
[gcloud.region_aliases]
us-central1 = "uc1"
asia-northeast1 = "an1"
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## Git Branch
The `git_branch` module shows the active branch of the repo in your current directory.
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ------------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
feat(git_branch): add remote branch name if different than local branch (#1915) * feat(git_branch): add remote branch name if different than local branch * feat(git_branch): Implement a more customizable remote branch * feat(git_branch): Use more explicit API function name * feat(git_branch): Remove forgotten draft documentation * feat(git_branch): Set less verbose defaults * feat(git_branch): Handle case to always display remote * feat(git_branch): Fix error in rebase operation
2020-11-23 21:07:16 +00:00
| `always_show_remote`| `false` | Shows the remote tracking branch name, even if it is equal to the local branch name. |
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| `format` | `"on [$symbol$branch]($style) "` | The format for the module. Use `"$branch"` to refer to the current branch name. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `symbol` | `" "` | A format string representing the symbol of git branch. |
| `style` | `"bold purple"` | The style for the module. |
| `truncation_length` | `2^63 - 1` | Truncates a git branch to X graphemes. |
| `truncation_symbol` | `"…"` | The symbol used to indicate a branch name was truncated. You can use `""` for no symbol. |
feat(git_branch): show remote name (#1972) * feat(git_branch): Show remote name in addition to remote branch * feat(git_branch): Fix table indentation in config README * feat(git_branch): Use a different method to fetch remote information * feat(git_branch): Fix the Clippy issue regarding string constant
2020-12-08 10:12:53 +00:00
| `only_attached` | `false` | Only show the branch name when not in a detached HEAD state. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `disabled` | `false` | Disables the `git_branch` module. |
### Variables
feat(git_branch): show remote name (#1972) * feat(git_branch): Show remote name in addition to remote branch * feat(git_branch): Fix table indentation in config README * feat(git_branch): Use a different method to fetch remote information * feat(git_branch): Fix the Clippy issue regarding string constant
2020-12-08 10:12:53 +00:00
| Variable | Example | Description |
| ----------------| -------- | ---------------------------------------------------------------------------------------------------- |
| branch | `master` | The current branch name, falls back to `HEAD` if there's no current branch (e.g. git detached HEAD). |
| remote_name | `origin` | The remote name. |
| remote_branch | `master` | The name of the branch tracked on `remote_name`. |
| symbol | | Mirrors the value of option `symbol` |
| style\* | | Mirrors the value of option `style` |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
\*: This variable can only be used as a part of a style string
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Example
```toml
# ~/.config/starship.toml
[git_branch]
symbol = "🌱 "
refactor: Refactor git_branch module to use new module config (#535)
2019-10-15 11:48:53 +00:00
truncation_length = 4
feat: added truncation_length/symbol to git_branch (#268) Git branches can become very long (e.g. gitlab auto-generated branch names), thus it would be nice to be able to truncate them to keep your prompt lenght in line. This patch adds two new options to the git_branch module: * truncation_length: The amount of graphemes to of a gitbranch to truncate to * truncation_symbol: The symbol that should be used to indicate that a branch name was trunctated To be able to correctly work with UTF-8 graphemes, unicode-segmentation was added as a dependency.
2019-09-02 19:56:59 +00:00
truncation_symbol = ""
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```
feat: Add git_commit module (#673)
2019-12-06 16:57:42 +00:00
## Git Commit
feat(git_commit): add git tag to module (#950)
2020-10-23 15:49:19 +00:00
The `git_commit` module shows the current commit hash and also the tag (if any) of the repo in your current directory.
feat: Add git_commit module (#673)
2019-12-06 16:57:42 +00:00
### Options
feat(git_commit): add git tag to module (#950)
2020-10-23 15:49:19 +00:00
| Option | Default | Description |
| -------------------- | ---------------------------------------------- | ----------------------------------------------------- |
| `commit_hash_length` | `7` | The length of the displayed git commit hash. |
| `format` | `"[\\($hash\\)]($style) [\\($tag\\)]($style)"` | The format for the module. |
| `style` | `"bold green"` | The style for the module. |
| `only_detached` | `true` | Only show git commit hash when in detached HEAD state |
| `tag_disabled` | `true` | Disables showing tag info in `git_commit` module. |
| `tag_symbol` | `"🏷 "` | Tag symbol prefixing the info shown |
| `disabled` | `false` | Disables the `git_commit` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | --------- | ----------------------------------- |
| hash | `b703eb3` | The current git commit hash |
| style\* | | Mirrors the value of option `style` |
\*: This variable can only be used as a part of a style string
feat: Add git_commit module (#673)
2019-12-06 16:57:42 +00:00
### Example
```toml
# ~/.config/starship.toml
[git_commit]
commit_hash_length = 4
feat(git_commit): add git tag to module (#950)
2020-10-23 15:49:19 +00:00
tag_symbol = "🔖 "
feat: Add git_commit module (#673)
2019-12-06 16:57:42 +00:00
```
feat: Adds Git State module for showing "REBASING 2/3", etc. (#276) - Adds the git_state module. - Adds git_state to the default prompt order - Updates the documentation to describe the git_state module
2019-09-05 16:45:04 +00:00
## Git State
The `git_state` module will show in directories which are part of a git
repository, and where there is an operation in progress, such as: _REBASING_,
_BISECTING_, etc. If there is progress information (e.g., REBASING 3/10),
that information will be shown too.
### Options
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Default | Description |
| -------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `rebase` | `"REBASING"` | A format string displayed when a `rebase` is in progress. |
| `merge` | `"MERGING"` | A format string displayed when a `merge` is in progress. |
| `revert` | `"REVERTING"` | A format string displayed when a `revert` is in progress. |
| `cherry_pick` | `"CHERRY-PICKING"` | A format string displayed when a `cherry-pick` is in progress. |
| `bisect` | `"BISECTING"` | A format string displayed when a `bisect` is in progress. |
| `am` | `"AM"` | A format string displayed when an `apply-mailbox` (`git am`) is in progress. |
| `am_or_rebase` | `"AM/REBASE"` | A format string displayed when an ambiguous `apply-mailbox` or `rebase` is in progress. |
| `style` | `"bold yellow"` | The style for the module. |
| `format` | `'\([$state( $progress_current/$progress_total)]($style)\) '` | The format for the module. |
| `disabled` | `false` | Disables the `git_state` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| ---------------- | ---------- | ----------------------------------- |
| state | `REBASING` | The current state of the repo |
| progress_current | `1` | The current operation progress |
| progress_total | `2` | The total operation progress |
| style\* | | Mirrors the value of option `style` |
\*: This variable can only be used as a part of a style string
feat: Adds Git State module for showing "REBASING 2/3", etc. (#276) - Adds the git_state module. - Adds git_state to the default prompt order - Updates the documentation to describe the git_state module
2019-09-05 16:45:04 +00:00
### Example
```toml
# ~/.config/starship.toml
[git_state]
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
format = '[\($state( $progress_current of $progress_total)\)]($style) '
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
cherry_pick = "[🍒 PICKING](bold red)"
feat: Adds Git State module for showing "REBASING 2/3", etc. (#276) - Adds the git_state module. - Adds git_state to the default prompt order - Updates the documentation to describe the git_state module
2019-09-05 16:45:04 +00:00
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## Git Status
The `git_status` module shows symbols representing the state of the repo in your
current directory.
### Options
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Default | Description |
| ------------ | --------------------------------------------- | ----------------------------------- |
| `format` | `'([\[$all_status$ahead_behind\]]($style) )'` | The default format for `git_status` |
| `conflicted` | `"="` | This branch has merge conflicts. |
| `ahead` | `"⇡"` | The format of `ahead` |
| `behind` | `"⇣"` | The format of `behind` |
| `diverged` | `"⇕"` | The format of `diverged` |
| `untracked` | `"?"` | The format of `untracked` |
| `stashed` | `"$"` | The format of `stashed` |
| `modified` | `"!"` | The format of `modified` |
| `staged` | `"+"` | The format of `staged` |
| `renamed` | `"»"` | The format of `renamed` |
| `deleted` | `"✘"` | The format of `deleted` |
| `style` | `"bold red"` | The style for the module. |
| `disabled` | `false` | Disables the `git_status` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
The following variables can be used in `format`:
| Variable | Description |
| -------------- | --------------------------------------------------------------------------------------------- |
| `all_status` | Shortcut for`$conflicted$stashed$deleted$renamed$modified$staged$untracked` |
| `ahead_behind` | Displays `diverged` `ahead` or `behind` format string based on the current status of the repo |
| `conflicted` | Displays `conflicted` when this branch has merge conflicts. |
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| `untracked` | Displays `untracked` when there are untracked files in the working directory. |
| `stashed` | Displays `stashed` when a stash exists for the local repository. |
| `modified` | Displays `modified` when there are file modifications in the working directory. |
| `staged` | Displays `staged` when a new file has been added to the staging area. |
| `renamed` | Displays `renamed` when a renamed file has been added to the staging area. |
| `deleted` | Displays `deleted` when a file's deletion has been added to the staging area. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| style\* | Mirrors the value of option `style` |
\*: This variable can only be used as a part of a style string
The following variables can be used in `diverged`:
| Variable | Description |
| -------------- | ---------------------------------------------- |
| `ahead_count` | Number of commits ahead of the tracking branch |
| `behind_count` | Number of commits behind the tracking branch |
The following variables can be used in `conflicted`, `ahead`, `behind`, `untracked`, `stashed`, `modified`, `staged`, `renamed` and `deleted`:
| Variable | Description |
| -------- | ------------------------ |
| `count` | Show the number of files |
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Example
```toml
# ~/.config/starship.toml
[git_status]
conflicted = "🏳"
ahead = "🏎💨"
behind = "😰"
diverged = "😵"
untracked = "🤷‍"
stashed = "📦"
modified = "📝"
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
staged = '[++\($count\)](green)'
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
renamed = "👅"
deleted = "🗑"
```
docs(git_status): Update git_status module docs (#1667) * 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.
2020-09-26 17:15:52 +00:00
Show ahead/behind count of the branch being tracked
docs(directory): fix $read_only variable names Fixes #1706
2020-09-30 22:38:57 +00:00
docs(git_status): Update git_status module docs (#1667) * 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.
2020-09-26 17:15:52 +00:00
```toml
# ~/.config/starship.toml
[git_status]
ahead = "⇡${count}"
diverged = "⇕⇡${ahead_count}⇣${behind_count}"
behind = "⇣${count}"
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## Golang
The `golang` module shows the currently installed version of Golang.
The module will be shown if any of the following conditions are met:
- The current directory contains a `go.mod` file
- The current directory contains a `go.sum` file
- The current directory contains a `glide.yaml` file
- The current directory contains a `Gopkg.yml` file
- The current directory contains a `Gopkg.lock` file
feat: Enable to display language version when `.<lang>-version` file exists. (#1028) * adjust https://github.com/sonnym/elmenv * adjust https://github.com/syndbg/goenv * adjust https://github.com/jenv/jenv * adjust https://github.com/nodenv/nodenv * adjust https://github.com/phpenv/phpenv * adjust https://github.com/rbenv/rbenv * add description * golang.rs is executed rustfmt * add testcases
2020-04-03 19:02:28 +00:00
- The current directory contains a `.go-version` file
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
- The current directory contains a `Godeps` directory
- The current directory contains a file with the `.go` extension
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | ---------------------------------- | ---------------------------------------------- |
fix: Adjust default format strings (#2165) * fix(dotnet): update dotnet format string * fix(dotnet): update erlang format string * fix(dotnet): update golang format string * fix(dotnet): update helm format string * fix(dotnet): update julia format string * fix(dotnet): update nim format string * fix(dotnet): update ruby format string * fix(dotnet): update rust format string * test: update formatted strings in unit tests * Use suggested format strings Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Moritz Vetter <mv@3yourmind.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-20 17:46:26 +00:00
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `symbol` | `"🐹 "` | A format string representing the symbol of Go. |
| `style` | `"bold cyan"` | The style for the module. |
| `disabled` | `false` | Disables the `golang` module. |
### Variables
| Variable | Example | Description |
| -------- | --------- | ------------------------------------ |
| version | `v1.12.1` | The version of `go` |
| 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
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Example
```toml
# ~/.config/starship.toml
[golang]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "via [🏎💨 $version](bold cyan) "
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```
feat(helm): Add Helm module (#1463) Signed-off-by: Furkan <furkan.turkal@hotmail.com> Co-authored-by: Furkan <furkan.turkal@hotmail.com>
2020-07-17 07:51:25 +00:00
## Helm
The `helm` module shows the currently installed version of Helm.
The module will be shown if any of the following conditions are met:
- The current directory contains a `helmfile.yaml` file
- The current directory contains a `Chart.yaml` file
### Options
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| Option | Default | Description |
| ---------- | ---------------------------------- | ------------------------------------------------ |
fix: Adjust default format strings (#2165) * fix(dotnet): update dotnet format string * fix(dotnet): update erlang format string * fix(dotnet): update golang format string * fix(dotnet): update helm format string * fix(dotnet): update julia format string * fix(dotnet): update nim format string * fix(dotnet): update ruby format string * fix(dotnet): update rust format string * test: update formatted strings in unit tests * Use suggested format strings Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Moritz Vetter <mv@3yourmind.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-20 17:46:26 +00:00
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| `symbol` | `"⎈ "` | A format string representing the symbol of Helm. |
| `style` | `"bold white"` | The style for the module. |
| `disabled` | `false` | Disables the `helm` module. |
feat(helm): Add Helm module (#1463) Signed-off-by: Furkan <furkan.turkal@hotmail.com> Co-authored-by: Furkan <furkan.turkal@hotmail.com>
2020-07-17 07:51:25 +00:00
### Variables
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `v3.1.1` | The version of `helm` |
| symbol | | Mirrors the value of option `symbol` |
| style\* | | Mirrors the value of option `style` |
feat(helm): Add Helm module (#1463) Signed-off-by: Furkan <furkan.turkal@hotmail.com> Co-authored-by: Furkan <furkan.turkal@hotmail.com>
2020-07-17 07:51:25 +00:00
\*: This variable can only be used as a part of a style string
### Example
```toml
# ~/.config/starship.toml
[helm]
format = "via [⎈ $version](bold white) "
```
feat: Add the ability to configure per-module color styles (#285) Add parsing logic, config support, docs, and integration with other modules for custom styling of each module.
2019-09-08 00:33:06 +00:00
## Hostname
The `hostname` module shows the system hostname.
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `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 |
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| `format` | `"[$hostname]($style) in "` | The format for the module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `style` | `"bold dimmed green"` | The style for the module. |
| `disabled` | `false` | Disables the `hostname` module. |
### Variables
| Variable | Example | Description |
| -------- | ------- | ------------------------------------ |
| 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
feat: Add the ability to configure per-module color styles (#285) Add parsing logic, config support, docs, and integration with other modules for custom styling of each module.
2019-09-08 00:33:06 +00:00
### Example
```toml
# ~/.config/starship.toml
[hostname]
ssh_only = false
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "on [$hostname](bold red) "
feat: Add configuration for hostname truncation (#485)
2019-10-14 16:22:25 +00:00
trim_at = ".companyname.com"
feat: Add the ability to configure per-module color styles (#285) Add parsing logic, config support, docs, and integration with other modules for custom styling of each module.
2019-09-08 00:33:06 +00:00
disabled = false
```
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
## Java
The `java` module shows the currently installed version of Java.
The module will be shown if any of the following conditions are met:
feat(java): Show Java module for Clojure projects (#966)
2020-11-30 12:50:56 +00:00
- The current directory contains a `pom.xml`, `build.gradle.kts`, `build.sbt`, `.java-version`, `.deps.edn`, `project.clj`, or `build.boot` file
- The current directory contains a file with the `.java`, `.class`, `.gradle`, `.jar`, `.clj`, or `.cljc` extension
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
### Options
perf(java): Lazy eval java (#2168) * perf(java): evaluate version lazily * fix(java): update format string * fix: use suggested format string Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-20 17:51:30 +00:00
| Option | Default | Description |
| ---------- | ---------------------------------------- | ----------------------------------------------- |
| `format` | `"via [${symbol}(${version} )]($style)"` | The format for the module. |
| `symbol` | `"☕ "` | A format string representing the symbol of Java |
| `style` | `"red dimmed"` | The style for the module. |
| `disabled` | `false` | Disables the `java` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | ------- | ------------------------------------ |
| version | `v14` | The version of `java` |
| 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
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
### Example
```toml
# ~/.config/starship.toml
[java]
symbol = "🌟 "
```
feat: Implement the prompt module for jobs (#85)
2019-08-12 17:42:33 +00:00
## Jobs
The `jobs` module shows the current number of jobs running.
The module will be shown only if there are background jobs running.
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.
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ----------- | ----------------------------- | ------------------------------------------------ |
| `threshold` | `1` | Show number of jobs if exceeded. |
| `format` | `"[$symbol$number]($style) "` | The format for the module. |
| `symbol` | `"✦"` | A format string representing the number of jobs. |
| `style` | `"bold blue"` | The style for the module. |
| `disabled` | `false` | Disables the `jobs` module. |
### Variables
| Variable | Example | Description |
| -------- | ------- | ------------------------------------ |
| number | `1` | The number of jobs |
| 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
feat: Implement the prompt module for jobs (#85)
2019-08-12 17:42:33 +00:00
### Example
```toml
# ~/.config/starship.toml
[jobs]
docs: Add undocumented config options (#262)
2019-08-29 17:09:36 +00:00
symbol = "+ "
feat: Implement the prompt module for jobs (#85)
2019-08-12 17:42:33 +00:00
threshold = 4
```
feat: Add a julia module (#1030) * add a julia module * Update docs/config/README.md Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * fix based on https://github.com/starship/starship/pull/1030#pullrequestreview-381767326 Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-04-03 18:16:34 +00:00
## Julia
The `julia` module shows the currently installed version of Julia.
The module will be shown if any of the following conditions are met:
- The current directory contains a `Project.toml` file
- The current directory contains a `Manifest.toml` file
- The current directory contains a file with the `.jl` extension
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | ---------------------------------- | ------------------------------------------------- |
fix: Adjust default format strings (#2165) * fix(dotnet): update dotnet format string * fix(dotnet): update erlang format string * fix(dotnet): update golang format string * fix(dotnet): update helm format string * fix(dotnet): update julia format string * fix(dotnet): update nim format string * fix(dotnet): update ruby format string * fix(dotnet): update rust format string * test: update formatted strings in unit tests * Use suggested format strings Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Moritz Vetter <mv@3yourmind.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-20 17:46:26 +00:00
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `symbol` | `"ஃ "` | A format string representing the symbol of Julia. |
| `style` | `"bold purple"` | The style for the module. |
| `disabled` | `false` | Disables the `julia` module. |
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `v1.4.0` | The version of `julia` |
| 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
feat: Add a julia module (#1030) * add a julia module * Update docs/config/README.md Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * fix based on https://github.com/starship/starship/pull/1030#pullrequestreview-381767326 Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-04-03 18:16:34 +00:00
### Example
```toml
# ~/.config/starship.toml
[julia]
Fix julia icon based on https://julialang.org/community/standards/ (#1055) According by this standards > While "Julia" is a female name in many parts of the world, the programming language is not a person and does not have a gender.
2020-04-07 09:07:51 +00:00
symbol = "∴ "
feat: Add a julia module (#1030) * add a julia module * Update docs/config/README.md Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> * fix based on https://github.com/starship/starship/pull/1030#pullrequestreview-381767326 Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-04-03 18:16:34 +00:00
```
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
feat(kotlin): Add the kotlin module (#2026) Add a module to show the currently installed Kotlin version if a .kt/.kts file is found in the current folder
2020-12-26 14:26:50 +00:00
## Kotlin
The `kotlin` module shows the currently installed version of Kotlin.
The module will be shown if any of the following conditions are met:
- The current directory contains a `.kt` or a `.kts` file
### Options
perf(kotlin): Lazy eval kotlin (#2186) * perf(kotlin): evaluate version lazily * fix(kotlin): update format string; update tests Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-21 22:01:30 +00:00
| Option | Default | Description |
| --------------- | ------------------------------------ | ----------------------------------------------------------------------------- |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `symbol` | `"🅺 "` | A format string representing the symbol of Kotlin. |
| `style` | `"bold blue"` | The style for the module. |
| `kotlin_binary` | `"kotlin"` | Configures the kotlin binary that Starship executes when getting the version. |
| `disabled` | `false` | Disables the `kotlin` module. |
feat(kotlin): Add the kotlin module (#2026) Add a module to show the currently installed Kotlin version if a .kt/.kts file is found in the current folder
2020-12-26 14:26:50 +00:00
### Variables
| Variable | Example | Description |
| -------- | --------- | ------------------------------------ |
| version | `v1.4.21` | The version of `kotlin` |
| 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
### Example
```toml
# ~/.config/starship.toml
[kotlin]
symbol = "🅺 "
```
```toml
# ~/.config/starship.toml
[kotlin]
# Uses the Kotlin Compiler binary to get the installed version
kotlin_binary = "kotlinc"
```
feat: Add Kubernetes Module (#404) Adds a Kubernetes module, which works by parsing kubeconfig.
2019-10-01 18:58:24 +00:00
## Kubernetes
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
Displays the current Kubernetes context name and, if set, the namespace from the kubeconfig file.
The namespace needs to be set in the kubeconfig file, this can be done via
`kubectl config set-context starship-cluster --namespace astronaut`.
If the `$KUBECONFIG` env var is set the module will use that if not it will use the `~/.kube/config`.
feat: Add Kubernetes Module (#404) Adds a Kubernetes module, which works by parsing kubeconfig.
2019-10-01 18:58:24 +00:00
fix: Disable Kubernetes module by default (#488) Given the global nature of the Kubernetes module, the module has been disabled by default. The opportunity has also been taken to refactor the Kubernetes module to use the new config module.
2019-10-05 09:31:23 +00:00
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
:::
feat: Add Kubernetes Module (#404) Adds a Kubernetes module, which works by parsing kubeconfig.
2019-10-01 18:58:24 +00:00
### Options
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Default | Description |
| ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------- |
| `symbol` | `"☸ "` | A format string representing the symbol displayed before the Cluster. |
| `format` | `'[$symbol$context( \($namespace\))]($style) in '` | The format for the module. |
| `style` | `"cyan bold"` | The style for the module. |
| `context_aliases` | | Table of context aliases to display. |
| `disabled` | `true` | Disables the `kubernetes` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| --------- | -------------------- | ---------------------------------------- |
| context | `starship-cluster` | The current kubernetes context |
| namespace | `starship-namespace` | If set, the current kubernetes namespace |
| 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
feat: Add Kubernetes Module (#404) Adds a Kubernetes module, which works by parsing kubeconfig.
2019-10-01 18:58:24 +00:00
### Example
```toml
# ~/.config/starship.toml
[kubernetes]
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
format = 'on [⛵ $context \($namespace\)](dimmed green) '
fix: Disable Kubernetes module by default (#488) Given the global nature of the Kubernetes module, the module has been disabled by default. The opportunity has also been taken to refactor the Kubernetes module to use the new config module.
2019-10-05 09:31:23 +00:00
disabled = false
feat(kubernetes): context aliases (#1015) * Allow kubernetes module to use aliases for contexts * documentation for kubernetes context aliasing * Apply suggestions from code review: consistent ordering of options in documentation Co-Authored-By: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-04-03 18:18:44 +00:00
[kubernetes.context_aliases]
"dev.local.cluster.k8s" = "dev"
feat: Add Kubernetes Module (#404) Adds a Kubernetes module, which works by parsing kubeconfig.
2019-10-01 18:58:24 +00:00
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## Line Break
The `line_break` module separates the prompt into two lines.
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
| ---------- | ------- | ------------------------------------------------------------------ |
| `disabled` | `false` | Disables the `line_break` module, making the prompt a single line. |
### Example
```toml
# ~/.config/starship.toml
[line_break]
disabled = true
```
feat(lua): Add a Lua module (#1815) * feat: add lua module * docs: add lua module * fix: lua version test * feat: lua module can be detected if the current dir contains a "lua" dir * feat: enable to use luajit * fix: improve regex * fix based on https://github.com/starship/starship/pull/1815#discussion_r510932742 * fix based on https://github.com/starship/starship/pull/1815#discussion_r511362581 * fix based on https://github.com/starship/starship/pull/1815#discussion_r510941252
2020-10-27 18:05:20 +00:00
## Lua
The `lua` module shows the currently installed version of Lua.
The module will be shown if any of the following conditions are met:
- The current directory contains a `.lua-version` file
- The current directory contains a `lua` directory
- The current directory contains a file with the `.lua` extension
### Options
perf(lua): Lazy eval lua (#2185) * perf(lua): evaluate version lazily * fix(lua): update format string * test(lua): update tests Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-21 22:00:12 +00:00
| Option | Default | Description |
| ------------ | ------------------------------------ | ----------------------------------------------------------------------------- |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `symbol` | `"🌙 "` | A format string representing the symbol of Lua. |
| `style` | `"bold blue"` | The style for the module. |
| `lua_binary` | `"lua"` | Configures the lua binary that Starship executes when getting the version. |
| `disabled` | `false` | Disables the `lua` module. |
feat(lua): Add a Lua module (#1815) * feat: add lua module * docs: add lua module * fix: lua version test * feat: lua module can be detected if the current dir contains a "lua" dir * feat: enable to use luajit * fix: improve regex * fix based on https://github.com/starship/starship/pull/1815#discussion_r510932742 * fix based on https://github.com/starship/starship/pull/1815#discussion_r511362581 * fix based on https://github.com/starship/starship/pull/1815#discussion_r510941252
2020-10-27 18:05:20 +00:00
### Variables
| Variable | Example | Description |
| -------- | --------- | ------------------------------------ |
| version | `v5.4.0` | The version of `lua` |
| 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
### Example
```toml
# ~/.config/starship.toml
[lua]
format = "via [🌕 $version](bold blue) "
```
feat: add memory usage module (#403) Adds a module to display system memory and swap usage.
2019-09-29 05:55:49 +00:00
## Memory Usage
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.
fix: Disable memory_usage by default (#451)
2019-09-30 07:04:49 +00:00
::: tip
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
:::
feat: add memory usage module (#403) Adds a module to display system memory and swap usage.
2019-09-29 05:55:49 +00:00
### Options
docs(directory): fix $read_only variable names Fixes #1706
2020-09-30 22:38:57 +00:00
| Option | Default | Description |
| ----------- | ---------------------- | -------------------------------------------------------- |
| `threshold` | `75` | Hide the memory usage unless it exceeds this percentage. |
| `format` | `"via $symbol [${ram}( | ${swap})]($style) "` | The format for the module. |
| `symbol` | `"🐏"` | The symbol used before displaying the memory usage. |
| `style` | `"bold dimmed white"` | The style for the module. |
| `disabled` | `true` | Disables the `memory_usage` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| Variable | Example | Description |
| ------------ | ------------- | ------------------------------------------------------------------ |
| ram | `31GiB/65GiB` | The usage/total RAM of the current system memory. |
| ram_pct | `48%` | The percentage of the current system memory. |
| swap\*\* | `1GiB/4GiB` | The swap memory size of the current system swap memory file. |
| swap_pct\*\* | `77%` | The swap memory percentage of the current system swap memory file. |
| symbol | `🐏` | Mirrors the value of option `symbol` |
| style\* | | Mirrors the value of option `style` |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
\*: This variable can only be used as a part of a style string
\*\*: The SWAP file information is only displayed if detected on the current system
feat: add memory usage module (#403) Adds a module to display system memory and swap usage.
2019-09-29 05:55:49 +00:00
### Example
```toml
# ~/.config/starship.toml
[memory_usage]
docs(memory_usage): Update example to have `disabled = false` (#1027)
2020-03-23 16:53:04 +00:00
disabled = false
feat: add memory usage module (#403) Adds a module to display system memory and swap usage.
2019-09-29 05:55:49 +00:00
threshold = -1
docs: Fix `Memory Usage` option key (#586)
2019-10-25 00:58:10 +00:00
symbol = " "
feat: add memory usage module (#403) Adds a module to display system memory and swap usage.
2019-09-29 05:55:49 +00:00
style = "bold dimmed green"
```
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
## Mercurial Branch
feat: Add Crystal version module (#170)
2020-02-04 23:27:06 +00:00
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
The `hg_branch` module shows the active branch of the repo in your current directory.
feat: Add Crystal version module (#170)
2020-02-04 23:27:06 +00:00
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
| `symbol` | `" "` | The symbol used before the hg bookmark or branch name of the repo in your current directory. |
| `style` | `"bold purple"` | The style for the module. |
| `format` | `"on [$symbol$branch]($style) "` | The format for the module. |
| `truncation_length` | `2^63 - 1` | Truncates the hg branch name to X graphemes |
| `truncation_symbol` | `"…"` | The symbol used to indicate a branch name was truncated. |
| `disabled` | `true` | Disables the `hg_branch` module. |
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| branch | `master` | The active mercurial branch |
| 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
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
### Example
```toml
# ~/.config/starship.toml
[hg_branch]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "on [🌱 $branch](bold purple)"
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
truncation_length = 4
truncation_symbol = ""
```
feat(nim): Add Nim module (#1189) * Nim module and tests * Add nim to docs * parse_nim_version refactor, add nim desc * Add nim symbol to Nerd Font preset * Yellow with v prefix as default version * Nim version fmt fix * Update docs/config/README.md Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Update src/modules/nim.rs Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Nim module and tests * Add nim to docs * Yellow with v prefix as default version * Update docs/config/README.md Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Update src/modules/nim.rs Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Add nim to docs, proper version formatting. * Remove v from symbol, add to fmt string * cargo fmt Co-authored-by: Dario Vladovic <d.vladimyr@gmail.com>
2020-06-09 17:14:47 +00:00
## Nim
The `nim` module shows the currently installed version of Nim.
The module will be shown if any of the following conditions are met:
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
feat(nim): Add Nim module (#1189) * Nim module and tests * Add nim to docs * parse_nim_version refactor, add nim desc * Add nim symbol to Nerd Font preset * Yellow with v prefix as default version * Nim version fmt fix * Update docs/config/README.md Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Update src/modules/nim.rs Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Nim module and tests * Add nim to docs * Yellow with v prefix as default version * Update docs/config/README.md Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Update src/modules/nim.rs Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Add nim to docs, proper version formatting. * Remove v from symbol, add to fmt string * cargo fmt Co-authored-by: Dario Vladovic <d.vladimyr@gmail.com>
2020-06-09 17:14:47 +00:00
- The current directory contains a `nim.cfg` file
- The current directory contains a file with the `.nim` extension
- The current directory contains a file with the `.nims` extension
- The current directory contains a file with the `.nimble` extension
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | ---------------------------------- | ----------------------------------------------------- |
fix: Adjust default format strings (#2165) * fix(dotnet): update dotnet format string * fix(dotnet): update erlang format string * fix(dotnet): update golang format string * fix(dotnet): update helm format string * fix(dotnet): update julia format string * fix(dotnet): update nim format string * fix(dotnet): update ruby format string * fix(dotnet): update rust format string * test: update formatted strings in unit tests * Use suggested format strings Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Moritz Vetter <mv@3yourmind.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-20 17:46:26 +00:00
| `format` | `"via [$symbol($version )]($style)"` | The format for the module |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `symbol` | `"👑 "` | The symbol used before displaying the version of Nim. |
| `style` | `"bold yellow"` | The style for the module. |
| `disabled` | `false` | Disables the `nim` module. |
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `v1.2.0` | The version of `nimc` |
| 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
feat(nim): Add Nim module (#1189) * Nim module and tests * Add nim to docs * parse_nim_version refactor, add nim desc * Add nim symbol to Nerd Font preset * Yellow with v prefix as default version * Nim version fmt fix * Update docs/config/README.md Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Update src/modules/nim.rs Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Nim module and tests * Add nim to docs * Yellow with v prefix as default version * Update docs/config/README.md Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Update src/modules/nim.rs Co-authored-by: Dario Vladović <d.vladimyr@gmail.com> * Add nim to docs, proper version formatting. * Remove v from symbol, add to fmt string * cargo fmt Co-authored-by: Dario Vladovic <d.vladimyr@gmail.com>
2020-06-09 17:14:47 +00:00
### Example
```toml
# ~/.config/starship.toml
[nim]
style = "yellow"
symbol = "🎣 "
```
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
## Nix-shell
The `nix_shell` module shows the nix-shell environment.
The module will be shown when inside a nix-shell environment.
feat: Add Crystal version module (#170)
2020-02-04 23:27:06 +00:00
### Options
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Default | Description |
| ------------ | -------------------------------------------- | ----------------------------------------------------- |
| `format` | `'via [$symbol$state( \($name\))]($style) '` | The format for the module. |
| `symbol` | `"❄️ "` | A format string representing the symbol of nix-shell. |
| `style` | `"bold blue"` | The style for the module. |
| `impure_msg` | `"impure"` | A format string shown when the shell is impure. |
| `pure_msg` | `"pure"` | A format string shown when the shell is pure. |
| `disabled` | `false` | Disables the `nix_shell` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | ------- | ------------------------------------ |
| state | `pure` | The state of the nix-shell |
| name | `lorri` | The name of the nix-shell |
| 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
feat: Add Crystal version module (#170)
2020-02-04 23:27:06 +00:00
### Example
```toml
# ~/.config/starship.toml
docs: alphabetize modules in config docs (#981)
2020-03-16 01:07:08 +00:00
[nix_shell]
disabled = true
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
impure_msg = "[impure shell](bold red)"
pure_msg = "[pure shell](bold green)"
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
format = 'via [☃️ $state( \($name\))](bold blue) '
feat: Add Crystal version module (#170)
2020-02-04 23:27:06 +00:00
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## NodeJS
The `nodejs` module shows the currently installed version of NodeJS.
The module will be shown if any of the following conditions are met:
- The current directory contains a `package.json` file
feat: Enable to display language version when `.<lang>-version` file exists. (#1028) * adjust https://github.com/sonnym/elmenv * adjust https://github.com/syndbg/goenv * adjust https://github.com/jenv/jenv * adjust https://github.com/nodenv/nodenv * adjust https://github.com/phpenv/phpenv * adjust https://github.com/rbenv/rbenv * add description * golang.rs is executed rustfmt * add testcases
2020-04-03 19:02:28 +00:00
- The current directory contains a `.node-version` file
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
- The current directory contains a `node_modules` directory
feat(nodejs): support additional file patterns (#1311)
2020-06-21 08:33:58 +00:00
- The current directory contains a file with the `.js`, `.mjs` or `.cjs` extension
- The current directory contains a file with the `.ts` extension
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | ---------------------------------- | -------------------------------------------------- |
perf(nodejs): evaluate nodejs format string lazily (#2160) * fix(nodejs): update format string * test(nodejs): adjust tests to new format strings * fix(nodejs): use once_cell's Lazy to implement hassleless lazy execution * chore(nodejs): run rustfmt Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-20 18:03:48 +00:00
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `symbol` | `"⬢ "` | A format string representing the symbol of NodeJS. |
| `style` | `"bold green"` | The style for the module. |
| `disabled` | `false` | Disables the `nodejs` module. |
feat(nodejs): check node engines version in package.json (#1847) * check node engines version in package.json * fix code, following review.
2020-12-05 11:25:48 +00:00
| `not_capable_style` | `bold red` | The style for the module when an engines property in Packages.json does not match the NodeJS version. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | ---------- | ------------------------------------ |
| version | `v13.12.0` | The version of `node` |
| 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
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Example
```toml
# ~/.config/starship.toml
[nodejs]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "via [🤖 $version](bold green) "
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```
feat(ocaml): Add OCaml module (#1218) * Add OCaml module * Update README.md accordingly * Fix typo * Add Reason support Obtain OCaml version using `-vnum` flag. Extend conditions to match projects using jbuild, esy or merlin. * Update README.md Co-authored-by: Dario Vladovic <d.vladimyr@gmail.com>
2020-05-21 16:43:13 +00:00
## OCaml
The `ocaml` module shows the currently installed version of OCaml.
The module will be shown if any of the following conditions are met:
- The current directory contains a file with `.opam` extension or `_opam` directory
- The current directory contains a `esy.lock` directory
- The current directory contains a `dune` or `dune-project` file
- The current directory contains a `jbuild` or `jbuild-ignore` file
- The current directory contains a `.merlin` file
- The current directory contains a file with `.ml`, `.mli`, `.re` or `.rei` extension
### Options
perf(ocaml): evaluate version lazily; adjust format string; update test (#2188) Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-22 17:08:04 +00:00
| Option | Default | Description |
| ---------- | ------------------------------------ | ------------------------------------------------------- |
| `format` | `"via [$symbol($version )]($style)"` | The format string for the module. |
| `symbol` | `"🐫 "` | The symbol used before displaying the version of OCaml. |
| `style` | `"bold yellow"` | The style for the module. |
| `disabled` | `false` | Disables the `ocaml` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | --------- | ------------------------------------ |
| version | `v4.10.0` | The version of `ocaml` |
| 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
feat(ocaml): Add OCaml module (#1218) * Add OCaml module * Update README.md accordingly * Fix typo * Add Reason support Obtain OCaml version using `-vnum` flag. Extend conditions to match projects using jbuild, esy or merlin. * Update README.md Co-authored-by: Dario Vladovic <d.vladimyr@gmail.com>
2020-05-21 16:43:13 +00:00
### Example
```toml
# ~/.config/starship.toml
[ocaml]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "via [🐪 $version]($style) "
feat(ocaml): Add OCaml module (#1218) * Add OCaml module * Update README.md accordingly * Fix typo * Add Reason support Obtain OCaml version using `-vnum` flag. Extend conditions to match projects using jbuild, esy or merlin. * Update README.md Co-authored-by: Dario Vladovic <d.vladimyr@gmail.com>
2020-05-21 16:43:13 +00:00
```
feat(openstack): Add module for OpenStack (#1664) * first (crude) attempt to implement the openstack module * Attempt to follow OpenStack standards for clouds.yaml location * fmt * provide unittest * add documentation * fix fmt * fix clippy * fix clippy * fix fmt * fix small nitpicks * expand openstack explanation * load config file using find_map * fix fmt * add test for valid config, plus fix test for invalid config * fix fmt * re-add forgotten comment
2020-10-24 09:46:43 +00:00
## OpenStack
The `openstack` module shows the current OpenStack cloud and project. The module
only active when the `OS_CLOUD` env var is set, in which case it will read
`clouds.yaml` file from any of the [default locations](https://docs.openstack.org/python-openstackclient/latest/configuration/index.html#configuration-files).
to fetch the current project in use.
### Options
| Option | Default | Description |
| ---------------- | ------------------------------------------------ | --------------------------------------------------------------- |
| `format` | `"on [$symbol$cloud(\\($project\\))]($style) "` | The format for the module. |
| `symbol` | `"☁️ "` | The symbol used before displaying the current OpenStack cloud. |
| `style` | `"bold yellow"` | The style for the module. |
| `disabled` | `false` | Disables the `OpenStack` module. |
### Variables
| Variable | Example | Description |
| -------- | ---------- | ------------------------------------ |
| cloud | `corp` | The current OpenStack cloud |
| project | `dev` | The current OpenStack project |
| 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
### Example
```toml
# ~/.config/starship.toml
[openstack]
format = "on [$symbol$cloud(\\($project\\))]($style) "
style = "bold yellow"
symbol = "☁️ "
```
docs: Alphabetic sorting of config subsections (#1877)
2020-11-14 18:41:58 +00:00
## Package Version
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
- **poetry** – The `poetry` package version is extracted from the `pyproject.toml` present
in the current directory
- **composer** – The `composer` package version is extracted from the `composer.json` present
in the current directory
- **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
feat(package): Meson package support (#2001) * Add package version support for Meson meson.build. * Update docs with Meson package version support.
2020-12-19 13:17:34 +00:00
- **meson** - The `meson` package version is extracted from the `meson.build` present
docs: Alphabetic sorting of config subsections (#1877)
2020-11-14 18:41:58 +00:00
> ⚠️ The version being shown is that of the package whose source code is in your
> current directory, not your package manager.
### Options
| Option | Default | Description |
| ----------------- | ---------------------------------- | ---------------------------------------------------------- |
docs: update package default format to replace /via/is (#2067) https://github.com/starship/starship/blob/master/src/configs/package.rs#L17
2021-01-04 16:56:25 +00:00
| `format` | `"is [$symbol$version]($style) "` | The format for the module. |
docs: Alphabetic sorting of config subsections (#1877)
2020-11-14 18:41:58 +00:00
| `symbol` | `"📦 "` | The symbol used before displaying the version the package. |
| `style` | `"bold 208"` | The style for the module. |
| `display_private` | `false` | Enable displaying version for packages marked as private. |
| `disabled` | `false` | Disables the `package` module. |
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `v1.0.0` | The version of your package |
| 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
### Example
```toml
# ~/.config/starship.toml
[package]
format = "via [🎁 $version](208 bold) "
```
feat(perl): Added perl version module (#1382) Adds a module for perl support.
2020-08-04 16:22:44 +00:00
## 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`
### Options
perf(perl): Lazy eval perl (#2189) * perf(perl): evaluate version lazily * fix(perl): update format string; update tests * refact(perl): run rustfmt Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-22 17:07:03 +00:00
| Option | Default | Description |
| ---------- | ------------------------------------ | ----------------------------------------------------- |
| `format` | `"via [$symbol($version )]($style)"` | The format string for the module. |
| `symbol` | `"🐪 "` | The symbol used before displaying the version of Perl |
| `style` | `"bold 149"` | The style for the module. |
| `disabled` | `false` | Disables the `perl` module. |
feat(perl): Added perl version module (#1382) Adds a module for perl support.
2020-08-04 16:22:44 +00:00
### Variables
| Variable | Example | Description |
| -------- | --------- | ------------------------------------ |
| version | `v5.26.1` | The version of `perl` |
| symbol | | Mirrors the value of option `symbol` |
| style\* | | Mirrors the value of option `style` |
### Example
```toml
# ~/.config/starship.toml
[perl]
format = "via [🦪 $version]($style) "
```
feat: Add PHP version module (#244)
2019-12-05 18:04:27 +00:00
## PHP
The `php` module shows the currently installed version of PHP.
The module will be shown if any of the following conditions are met:
- The current directory contains a `composer.json` file
feat: Enable to display language version when `.<lang>-version` file exists. (#1028) * adjust https://github.com/sonnym/elmenv * adjust https://github.com/syndbg/goenv * adjust https://github.com/jenv/jenv * adjust https://github.com/nodenv/nodenv * adjust https://github.com/phpenv/phpenv * adjust https://github.com/rbenv/rbenv * add description * golang.rs is executed rustfmt * add testcases
2020-04-03 19:02:28 +00:00
- The current directory contains a `.php-version` file
feat: Add PHP version module (#244)
2019-12-05 18:04:27 +00:00
- The current directory contains a `.php` file
### Options
perf(php): Lazy eval php (#2190) * perf(php): evaluate version lazily * fix(php): update format string; update tests Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-22 17:03:18 +00:00
| Option | Default | Description |
| ---------- | ------------------------------------ | ----------------------------------------------------- |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `symbol` | `"🐘 "` | The symbol used before displaying the version of PHP. |
| `style` | `"147 bold"` | The style for the module. |
| `disabled` | `false` | Disables the `php` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `v7.3.8` | The version of `php` |
| 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
feat: Add PHP version module (#244)
2019-12-05 18:04:27 +00:00
### Example
```toml
# ~/.config/starship.toml
[php]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "via [🔹 $version](147 bold) "
feat: Add PHP version module (#244)
2019-12-05 18:04:27 +00:00
```
docs: Alphabetic sorting of config subsections (#1877)
2020-11-14 18:41:58 +00:00
## PureScript
The `purescript` module shows the currently installed version of PureScript version.
The module will be shown if any of the following conditions are met:
- The current directory contains a `spago.dhall` file
- The current directory contains a \*.purs files
### Options
Perf(purescript): Lazy eval purescript (#2191) * perf(purescript): evaluate version lazily * fix(purescript): update format string; update tests Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-22 17:01:54 +00:00
| Option | Default | Description |
| ---------- | ------------------------------------ | ------------------------------------------------------------ |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `symbol` | `"<=> "` | The symbol used before displaying the version of PureScript. |
| `style` | `"bold white"` | The style for the module. |
| `disabled` | `false` | Disables the `purescript` module. |
docs: Alphabetic sorting of config subsections (#1877)
2020-11-14 18:41:58 +00:00
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `0.13.5` | The version of `purescript` |
| 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
### Example
```toml
# ~/.config/starship.toml
[purescript]
format = "via [$symbol$version](bold white)"
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## Python
docs: correct the configuration docs (#1195)
2020-05-13 22:19:21 +00:00
The `python` module shows the currently installed version of Python and the
current Python virtual environment if one is activated.
feat: Implement configuration to display pyenv version name (#140) This behavior can be enabled via setting `use_pyenv` to true. The "pyenv" prefix before the version name can be configured using `pyenv_prefix`.
2019-08-13 01:12:55 +00:00
docs: correct the configuration docs (#1195)
2020-05-13 22:19:21 +00:00
If `pyenv_version_name` is set to `true`, it will display the pyenv version
name. Otherwise, it will display the version number from `python --version`.
feat: Implement configuration to display pyenv version name (#140) This behavior can be enabled via setting `use_pyenv` to true. The "pyenv" prefix before the version name can be configured using `pyenv_prefix`.
2019-08-13 01:12:55 +00:00
feat(python): Configure when the module is shown (#2264) This makes it possible to configure when the python module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. This includes a breaking change since we are removing the `scan_for_pyfiles` configuration option in favour of setting the `detect_extensions` to an empty array.
2021-02-07 21:18:52 +00:00
By default the module will be shown if any of the following conditions are met:
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
- The current directory contains a `.python-version` file
Add support for detecting Python from Pipenv files (#221) Added the ability to enable the Python module based on the existence of the a `Pipfile`.
2019-08-21 22:54:22 +00:00
- The current directory contains a `Pipfile` file
feat(python): Add scan_for_pyfiles option (#692) Also adds two new entries to the list of hardcoded files to check: setup.py and __init__.py.
2020-04-14 08:26:51 +00:00
- The current directory contains a `__init__.py` file
feat(python): Configure when the module is shown (#2264) This makes it possible to configure when the python module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. This includes a breaking change since we are removing the `scan_for_pyfiles` configuration option in favour of setting the `detect_extensions` to an empty array.
2021-02-07 21:18:52 +00:00
- The current directory contains a `pyproject.toml` file
- The current directory contains a `requirements.txt` file
- The current directory contains a `setup.py` file
- The current directory contains a `tox.ini` file
- The current directory contains a file with the `.py` extension.
feat: Enable the python module in virtual envs (#584) This will enable the python module when a virtual environment has been activated, this is detected via the `VIRTUAL_ENV` env var.
2019-11-02 11:10:21 +00:00
- A virtual environment is currently activated
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Options
feat(python): Configure when the module is shown (#2264) This makes it possible to configure when the python module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. This includes a breaking change since we are removing the `scan_for_pyfiles` configuration option in favour of setting the `detect_extensions` to an empty array.
2021-02-07 21:18:52 +00:00
| Option | Default | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `format` | `'via [${symbol}${pyenv_prefix}(${version} )(\($virtualenv\))]($style)'` | The format for the module. |
| `symbol` | `"🐍 "` | A format string representing the symbol of Python |
| `style` | `"yellow bold"` | The style for the module. |
| `pyenv_version_name` | `false` | Use pyenv to get Python version |
| `pyenv_prefix` | `pyenv ` | Prefix before pyenv version display, only used if pyenv is used |
| `python_binary` | `["python", "python3, "python2"]` | Configures the python binaries that Starship should executes when getting the version. |
| `detect_extensions` | `[".py"]` | Which extensions should trigger this moudle |
| `detect_files` | `[".python-version", "Pipfile", "__init__.py", "pyproject.toml", "requirements.txt", "setup.py", "tox.ini"]` | Which filenames should trigger this module |
| `detect_folders` | `[]` | Which folders should trigger this module |
| `disabled` | `false` | Disables the `python` module. |
feat(python): Smarter python binary usage (#1947) Update the python module to try multiple python binaries when determining the version. With the new logic if starship doesn't find `python` on the `PATH`, which is the default for some Linux Distros, it will fallback to `python3` and then `python2`.
2020-11-30 19:14:18 +00:00
::: 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.
:::
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
fix: restore the `pyenv_prefix` option to python (#1668) Have restored the `pyenv_prefix` option to the python module. This is added as a new variable that will only be shown if `pyenv` is being used to determine the version of python that is being used.
2020-09-21 15:48:26 +00:00
| Variable | Example | Description |
| ------------ | --------------- | ------------------------------------------ |
| 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 |
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
feat(python): Add option to change the python binary (#1297) * Add option to change the python binary We are going to start to have problems with the python binary as python2 is removed and replaced with python3. To make the transition easier I have added an option to the python module to allow the user to pick a particular binary, e.g `python3`, for the module to use when selecting the version of python. I have also refactored the python tests moving almost all of them into the module and removing the dependency on the version of python that is installed on the system. * Add advanced config section to python module docs Have added an advanced config section to the python module docs and moved the `python_binary` option into that section.
2020-06-14 09:27:10 +00:00
docs(python): Update the python_binary option (#1731) * docs(python): Update the python_binary option Have updated the documentation to make the `python_binary` option a bit more prominent, since this is becoming a more requested requirement now that more and more systems don't have a default `python` command. * Correct order of python options
2020-10-06 07:09:06 +00:00
### Example
feat(python): Add option to change the python binary (#1297) * Add option to change the python binary We are going to start to have problems with the python binary as python2 is removed and replaced with python3. To make the transition easier I have added an option to the python module to allow the user to pick a particular binary, e.g `python3`, for the module to use when selecting the version of python. I have also refactored the python tests moving almost all of them into the module and removing the dependency on the version of python that is installed on the system. * Add advanced config section to python module docs Have added an advanced config section to the python module docs and moved the `python_binary` option into that section.
2020-06-14 09:27:10 +00:00
```toml
# ~/.config/starship.toml
[python]
docs(python): Update the python_binary option (#1731) * docs(python): Update the python_binary option Have updated the documentation to make the `python_binary` option a bit more prominent, since this is becoming a more requested requirement now that more and more systems don't have a default `python` command. * Correct order of python options
2020-10-06 07:09:06 +00:00
symbol = "👾 "
pyenv_version_name = true
feat(python): Add option to change the python binary (#1297) * Add option to change the python binary We are going to start to have problems with the python binary as python2 is removed and replaced with python3. To make the transition easier I have added an option to the python module to allow the user to pick a particular binary, e.g `python3`, for the module to use when selecting the version of python. I have also refactored the python tests moving almost all of them into the module and removing the dependency on the version of python that is installed on the system. * Add advanced config section to python module docs Have added an advanced config section to the python module docs and moved the `python_binary` option into that section.
2020-06-14 09:27:10 +00:00
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```toml
# ~/.config/starship.toml
[python]
feat(python): Smarter python binary usage (#1947) Update the python module to try multiple python binaries when determining the version. With the new logic if starship doesn't find `python` on the `PATH`, which is the default for some Linux Distros, it will fallback to `python3` and then `python2`.
2020-11-30 19:14:18 +00:00
# Only use the `python3` binary to get the version.
docs(python): Update the python_binary option (#1731) * docs(python): Update the python_binary option Have updated the documentation to make the `python_binary` option a bit more prominent, since this is becoming a more requested requirement now that more and more systems don't have a default `python` command. * Correct order of python options
2020-10-06 07:09:06 +00:00
python_binary = "python3"
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```
feat(python): Configure when the module is shown (#2264) This makes it possible to configure when the python module is shown based on the contents of a directory. This should make it possible to be a lot more granular when configuring the module. This includes a breaking change since we are removing the `scan_for_pyfiles` configuration option in favour of setting the `detect_extensions` to an empty array.
2021-02-07 21:18:52 +00:00
```toml
# ~/.config/starship.toml
[python]
# Don't trigger for files with the py extension
detect_extensions = []
```
feat: Add the ability to configure per-module color styles (#285) Add parsing logic, config support, docs, and integration with other modules for custom styling of each module.
2019-09-08 00:33:06 +00:00
## Ruby
The `ruby` module shows the currently installed version of Ruby.
The module will be shown if any of the following conditions are met:
- The current directory contains a `Gemfile` file
feat: Enable to display language version when `.<lang>-version` file exists. (#1028) * adjust https://github.com/sonnym/elmenv * adjust https://github.com/syndbg/goenv * adjust https://github.com/jenv/jenv * adjust https://github.com/nodenv/nodenv * adjust https://github.com/phpenv/phpenv * adjust https://github.com/rbenv/rbenv * add description * golang.rs is executed rustfmt * add testcases
2020-04-03 19:02:28 +00:00
- The current directory contains a `.ruby-version` file
feat: Add the ability to configure per-module color styles (#285) Add parsing logic, config support, docs, and integration with other modules for custom styling of each module.
2019-09-08 00:33:06 +00:00
- The current directory contains a `.rb` file
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | ---------------------------------- | ------------------------------------------------ |
fix: Adjust default format strings (#2165) * fix(dotnet): update dotnet format string * fix(dotnet): update erlang format string * fix(dotnet): update golang format string * fix(dotnet): update helm format string * fix(dotnet): update julia format string * fix(dotnet): update nim format string * fix(dotnet): update ruby format string * fix(dotnet): update rust format string * test: update formatted strings in unit tests * Use suggested format strings Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Moritz Vetter <mv@3yourmind.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-20 17:46:26 +00:00
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `symbol` | `"💎 "` | A format string representing the symbol of Ruby. |
| `style` | `"bold red"` | The style for the module. |
| `disabled` | `false` | Disables the `ruby` module. |
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `v2.5.1` | The version of `ruby` |
| 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
feat: Add the ability to configure per-module color styles (#285) Add parsing logic, config support, docs, and integration with other modules for custom styling of each module.
2019-09-08 00:33:06 +00:00
docs: reorder misplaced Ruby option example (#317)
2019-09-08 14:57:52 +00:00
### Example
```toml
# ~/.config/starship.toml
[ruby]
symbol = "🔺 "
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## Rust
The `rust` module shows the currently installed version of Rust.
The module will be shown if any of the following conditions are met:
- The current directory contains a `Cargo.toml` file
- The current directory contains a file with the `.rs` extension
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | ---------------------------------- | ----------------------------------------------- |
fix: Adjust default format strings (#2165) * fix(dotnet): update dotnet format string * fix(dotnet): update erlang format string * fix(dotnet): update golang format string * fix(dotnet): update helm format string * fix(dotnet): update julia format string * fix(dotnet): update nim format string * fix(dotnet): update ruby format string * fix(dotnet): update rust format string * test: update formatted strings in unit tests * Use suggested format strings Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Moritz Vetter <mv@3yourmind.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-20 17:46:26 +00:00
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| `symbol` | `"🦀 "` | A format string representing the symbol of Rust |
| `style` | `"bold red"` | The style for the module. |
| `disabled` | `false` | Disables the `rust` module. |
### Variables
| Variable | Example | Description |
| -------- | ----------------- | ------------------------------------ |
| version | `v1.43.0-nightly` | The version of `rustc` |
| 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
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Example
```toml
# ~/.config/starship.toml
[rust]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "via [⚙️ $version](red bold)"
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```
feat(shlvl): Add shlvl module (#1385) * initial commit of support for shlvl * documentation for shlvl * use a symbol instead * test coverage for shlvl * actually disable when the config says to * fix docs * tweak defaults some * refactor from pr comments * redisable * return early to avoid indenting * make default suffix empty space * fixing tests after suffix change * updating docs for format * making shlvl compatible with formatting * adding variables table for shlvl * removing extra line * doc clarity
2020-08-05 16:30:01 +00:00
## 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.
### Options
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Default | Description |
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| ----------- | ---------------------------- | --------------------------------------- |
| `threshold` | `2` | Display threshold. |
| `format` | `"[$symbol$shlvl]($style) "` | The format for the module. |
| `symbol` | `"↕️ "` | The symbol used to represent the SHLVL. |
feat(shlvl): Add `repeat` option (#1995)
2020-12-14 20:40:21 +00:00
| `repeat` | `false` | Causes `symbol` to be repeated by the current SHLVL amount. |
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| `style` | `"bold yellow"` | The style for the module. |
| `disabled` | `true` | Disables the `shlvl` module. |
feat(shlvl): Add shlvl module (#1385) * initial commit of support for shlvl * documentation for shlvl * use a symbol instead * test coverage for shlvl * actually disable when the config says to * fix docs * tweak defaults some * refactor from pr comments * redisable * return early to avoid indenting * make default suffix empty space * fixing tests after suffix change * updating docs for format * making shlvl compatible with formatting * adding variables table for shlvl * removing extra line * doc clarity
2020-08-05 16:30:01 +00:00
### Variables
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| Variable | Example | Description |
| -------- | ------- | ------------------------------------ |
| shlvl | `3` | The current value of SHLVL |
| symbol | | Mirrors the value of option `symbol` |
| style\* | | Mirrors the value of option `style` |
feat(shlvl): Add shlvl module (#1385) * initial commit of support for shlvl * documentation for shlvl * use a symbol instead * test coverage for shlvl * actually disable when the config says to * fix docs * tweak defaults some * refactor from pr comments * redisable * return early to avoid indenting * make default suffix empty space * fixing tests after suffix change * updating docs for format * making shlvl compatible with formatting * adding variables table for shlvl * removing extra line * doc clarity
2020-08-05 16:30:01 +00:00
\*: This variable can only be used as a part of a style string
### Example
```toml
# ~/.config/starship.toml
[shlvl]
disabled = false
format = "$shlvl level(s) down"
threshold = 3
```
feat: add singularity module (#932)
2020-02-26 16:18:19 +00:00
## Singularity
The `singularity` module shows the current singularity image, if inside a container
and `$SINGULARITY_NAME` is set.
### Options
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------------------------ |
| `format` | `'[$symbol\[$env\]]($style) '` | The format for the module. |
| `symbol` | `""` | A format string displayed before the image name. |
| `style` | `"bold dimmed blue"` | The style for the module. |
| `disabled` | `false` | Disables the `singularity` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | ------------ | ------------------------------------ |
| env | `centos.img` | The current singularity image |
| 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
feat: add singularity module (#932)
2020-02-26 16:18:19 +00:00
### Example
```toml
# ~/.config/starship.toml
[singularity]
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
format = '[📦 \[$env\]]($style) '
feat: add singularity module (#932)
2020-02-26 16:18:19 +00:00
```
feat(status): add the status module (#1651) * add the exit code module this allows to display more precisely the last command exit code and to configure starship to not change the last charcter of the prompt even in case of failure. It is disabled by default, because it seems a bit redundant with the character module in its default configuration. * rename exit_code module to status * Enforce a default disabled=true In the outer places, we only check for the disabled flag in the config toml file, only when this is loaded into the real config struct, we see the default. And if the default is true, we have to abort at that place. For status and hg_branch that wasn't so. I also commented the rest * fix spaces in markdown table for status module * Add a tip that status module is disabled by default Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Remove unrelated changes for default disabled=true Co-authored-by: Gaëtan Lehmann <gaetan.lehmann@gmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-25 22:04:51 +00:00
## Status
The `status` module displays the exit code of the previous command.
The module will be shown only if the exit code is not `0`.
::: tip
docs(directory): fix $read_only variable names Fixes #1706
2020-09-30 22:38:57 +00:00
feat(status): add the status module (#1651) * add the exit code module this allows to display more precisely the last command exit code and to configure starship to not change the last charcter of the prompt even in case of failure. It is disabled by default, because it seems a bit redundant with the character module in its default configuration. * rename exit_code module to status * Enforce a default disabled=true In the outer places, we only check for the disabled flag in the config toml file, only when this is loaded into the real config struct, we see the default. And if the default is true, we have to abort at that place. For status and hg_branch that wasn't so. I also commented the rest * fix spaces in markdown table for status module * Add a tip that status module is disabled by default Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Remove unrelated changes for default disabled=true Co-authored-by: Gaëtan Lehmann <gaetan.lehmann@gmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-25 22:04:51 +00:00
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
docs: fix custom containers to work with Crowdin Fixes #2063
2021-01-07 22:35:12 +00:00
feat(status): add the status module (#1651) * add the exit code module this allows to display more precisely the last command exit code and to configure starship to not change the last charcter of the prompt even in case of failure. It is disabled by default, because it seems a bit redundant with the character module in its default configuration. * rename exit_code module to status * Enforce a default disabled=true In the outer places, we only check for the disabled flag in the config toml file, only when this is loaded into the real config struct, we see the default. And if the default is true, we have to abort at that place. For status and hg_branch that wasn't so. I also commented the rest * fix spaces in markdown table for status module * Add a tip that status module is disabled by default Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Remove unrelated changes for default disabled=true Co-authored-by: Gaëtan Lehmann <gaetan.lehmann@gmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-25 22:04:51 +00:00
:::
feat: add support for elvish shell (#1725) * feat: add support for elvish shell * improve doc * elvish 0.15 is out * fix example init * update systax for 0.15 stable * udpate second init example too * remove warning from swift module * add warning to status module docs * prefix elvish version with v
2021-02-02 11:59:55 +00:00
::: warning
This module is not supported on elvish shell.
:::
feat(status): add the status module (#1651) * add the exit code module this allows to display more precisely the last command exit code and to configure starship to not change the last charcter of the prompt even in case of failure. It is disabled by default, because it seems a bit redundant with the character module in its default configuration. * rename exit_code module to status * Enforce a default disabled=true In the outer places, we only check for the disabled flag in the config toml file, only when this is loaded into the real config struct, we see the default. And if the default is true, we have to abort at that place. For status and hg_branch that wasn't so. I also commented the rest * fix spaces in markdown table for status module * Add a tip that status module is disabled by default Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Remove unrelated changes for default disabled=true Co-authored-by: Gaëtan Lehmann <gaetan.lehmann@gmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-25 22:04:51 +00:00
### Options
feat(status): Convert known status code to their meaning (#1948) User is able to choose if their want to display the meaning of known status code in place of number.
2021-01-03 03:09:13 +00:00
| Option | Default | Description |
| ------------------------- | --------------------------- | ------------------------------------------------------ |
docs(status): fix the format string to match the default (#2211)
2021-01-26 21:42:41 +00:00
| `format` | `"[$symbol$status]($style) "` | The format of the module |
feat(status): Convert known status code to their meaning (#1948) User is able to choose if their want to display the meaning of known status code in place of number.
2021-01-03 03:09:13 +00:00
| `symbol` | `"✖"` | The symbol displayed on program error |
| `not_executable_symbol` | `"🚫"` | The symbol displayed when file isn't executable |
| `not_found_symbol` | `"🔍"` | The symbol displayed when the command can't be found |
| `sigint_symbol` | `"🧱"` | The symbol displayed on SIGINT (Ctrl + c) |
| `signal_symbol` | `"⚡"` | The symbol displayed on any signal |
| `style` | `"bold red"` | The style for the module. |
| `recognize_signal_code` | `true` | Enable signal mapping from exit code |
| `map_symbol` | `false` | Enable symbols mapping from exit code |
| `disabled` | `true` | Disables the `status` module. |
feat(status): add the status module (#1651) * add the exit code module this allows to display more precisely the last command exit code and to configure starship to not change the last charcter of the prompt even in case of failure. It is disabled by default, because it seems a bit redundant with the character module in its default configuration. * rename exit_code module to status * Enforce a default disabled=true In the outer places, we only check for the disabled flag in the config toml file, only when this is loaded into the real config struct, we see the default. And if the default is true, we have to abort at that place. For status and hg_branch that wasn't so. I also commented the rest * fix spaces in markdown table for status module * Add a tip that status module is disabled by default Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Remove unrelated changes for default disabled=true Co-authored-by: Gaëtan Lehmann <gaetan.lehmann@gmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-25 22:04:51 +00:00
### Variables
feat(status): Convert known status code to their meaning (#1948) User is able to choose if their want to display the meaning of known status code in place of number.
2021-01-03 03:09:13 +00:00
| Variable | Example | Description |
| ----------------------- | ------- | ----------------------------------------------------------------------- |
| status | `127` | The exit code of the last command |
| int | `127` | The exit code of the last command |
| common_meaning | `ERROR` | Meaning of the code if not a signal |
| signal_number | `9` | Signal number corresponding to the exit code, only if signalled |
| signal_name | `KILL` | Name of the signal corresponding to the exit code, only if signalled |
| maybe_int | `7` | Contains the exit code number when no meaning has been found |
| symbol | | Mirrors the value of option `symbol` |
| style\* | | Mirrors the value of option `style` |
feat(status): add the status module (#1651) * add the exit code module this allows to display more precisely the last command exit code and to configure starship to not change the last charcter of the prompt even in case of failure. It is disabled by default, because it seems a bit redundant with the character module in its default configuration. * rename exit_code module to status * Enforce a default disabled=true In the outer places, we only check for the disabled flag in the config toml file, only when this is loaded into the real config struct, we see the default. And if the default is true, we have to abort at that place. For status and hg_branch that wasn't so. I also commented the rest * fix spaces in markdown table for status module * Add a tip that status module is disabled by default Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Remove unrelated changes for default disabled=true Co-authored-by: Gaëtan Lehmann <gaetan.lehmann@gmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-25 22:04:51 +00:00
\*: This variable can only be used as a part of a style string
### Example
docs(directory): fix $read_only variable names Fixes #1706
2020-09-30 22:38:57 +00:00
feat(status): add the status module (#1651) * add the exit code module this allows to display more precisely the last command exit code and to configure starship to not change the last charcter of the prompt even in case of failure. It is disabled by default, because it seems a bit redundant with the character module in its default configuration. * rename exit_code module to status * Enforce a default disabled=true In the outer places, we only check for the disabled flag in the config toml file, only when this is loaded into the real config struct, we see the default. And if the default is true, we have to abort at that place. For status and hg_branch that wasn't so. I also commented the rest * fix spaces in markdown table for status module * Add a tip that status module is disabled by default Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Remove unrelated changes for default disabled=true Co-authored-by: Gaëtan Lehmann <gaetan.lehmann@gmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-25 22:04:51 +00:00
```toml
# ~/.config/starship.toml
[status]
style = "bg:blue"
feat(status): Convert known status code to their meaning (#1948) User is able to choose if their want to display the meaning of known status code in place of number.
2021-01-03 03:09:13 +00:00
symbol = "🔴"
docs(status): Remove status_ prefix from status module variables (#2260) * Remove status_ prefix from status module variables * Revert "Remove status_ prefix from status module variables" This reverts commit f4c6e9ced3040ef2939189afe7ff8bd08d6fae78. * docs: Remove status_ prefix from status module variables
2021-02-03 17:52:15 +00:00
format = '[\[$symbol $common_meaning$signal_name$maybe_int\]]($style) '
feat(status): Convert known status code to their meaning (#1948) User is able to choose if their want to display the meaning of known status code in place of number.
2021-01-03 03:09:13 +00:00
map_symbol = true
feat(status): add the status module (#1651) * add the exit code module this allows to display more precisely the last command exit code and to configure starship to not change the last charcter of the prompt even in case of failure. It is disabled by default, because it seems a bit redundant with the character module in its default configuration. * rename exit_code module to status * Enforce a default disabled=true In the outer places, we only check for the disabled flag in the config toml file, only when this is loaded into the real config struct, we see the default. And if the default is true, we have to abort at that place. For status and hg_branch that wasn't so. I also commented the rest * fix spaces in markdown table for status module * Add a tip that status module is disabled by default Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> * Remove unrelated changes for default disabled=true Co-authored-by: Gaëtan Lehmann <gaetan.lehmann@gmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-25 22:04:51 +00:00
disabled = false
```
docs: Alphabetic sorting of config subsections (#1877)
2020-11-14 18:41:58 +00:00
## Swift
The `swift` module shows the currently installed version of Swift.
The module will be shown if any of the following conditions are met:
- The current directory contains a `Package.swift` file
- The current directory contains a file with the `.swift` extension
### Options
perf: evaluate swift version lazily (#2159) * perf(swift): evaluate version lazily * fix(swift): update format string Co-authored-by: Moritz Vetter <mv@3yourmind.com>
2021-01-19 04:42:28 +00:00
| Option | Default | Description |
| ---------- | ------------------------------------ | ------------------------------------------------ |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `symbol` | `"🐦 "` | A format string representing the symbol of Swift |
| `style` | `"bold 202"` | The style for the module. |
| `disabled` | `false` | Disables the `swift` module. |
docs: Alphabetic sorting of config subsections (#1877)
2020-11-14 18:41:58 +00:00
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `v5.2.4` | The version of `swift` |
| 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
### Example
```toml
# ~/.config/starship.toml
[swift]
format = "via [🏎 $version](red bold)"
```
feat: Implement terraform module with workspace and version (#644)
2019-12-09 01:42:51 +00:00
## Terraform
The `terraform` module shows the currently selected terraform workspace and version.
docs(terraform): Make version perf issue obvious (#2107) This intends to make the performance issue with the terraform version more obvious.
2021-01-23 14:17:51 +00:00
::: 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.
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
If you still want to enable it, [follow the example shown below](#with-version).
docs(terraform): Make version perf issue obvious (#2107) This intends to make the performance issue with the terraform version more obvious.
2021-01-23 14:17:51 +00:00
:::
feat: Implement terraform module with workspace and version (#644)
2019-12-09 01:42:51 +00:00
The module will be shown if any of the following conditions are met:
- The current directory contains a `.terraform` folder
feat(terraform): Add hcl extension support to Terraform module (#1875) * Add hcl file extension to terraform module Signed-off-by: adhaamehab <adhaamehab.me@gmail.com> * Update docs Signed-off-by: adhaamehab <adhaamehab.me@gmail.com>
2020-11-14 17:33:21 +00:00
- Current directory contains a file with the `.tf` or `.hcl` extensions
feat: Implement terraform module with workspace and version (#644)
2019-12-09 01:42:51 +00:00
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ---------- | ------------------------------------ | ----------------------------------------------------- |
| `format` | `"via [$symbol$workspace]($style) "` | The format string for the module. |
| `symbol` | `"💠 "` | A format string shown before the terraform workspace. |
| `style` | `"bold 105"` | The style for the module. |
| `disabled` | `false` | Disables the `terraform` module. |
### Variables
| Variable | Example | Description |
| --------- | ---------- | ------------------------------------ |
| version | `v0.12.24` | The version of `terraform` |
| workspace | `default` | The current terraform workspace |
| 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
feat: Implement terraform module with workspace and version (#644)
2019-12-09 01:42:51 +00:00
### Example
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
#### With Version
feat: Implement terraform module with workspace and version (#644)
2019-12-09 01:42:51 +00:00
```toml
# ~/.config/starship.toml
[terraform]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
format = "[🏎💨 $version$workspace]($style) "
```
#### Without version
```toml
# ~/.config/starship.toml
[terraform]
format = "[🏎💨 $workspace]($style) "
feat: Implement terraform module with workspace and version (#644)
2019-12-09 01:42:51 +00:00
```
feat: Implement the prompt module for time (#138) Add a module which displays the current time in a format requested by the user. Disabled by default.
2019-09-10 17:54:40 +00:00
## Time
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
docs: Add extra newlines around custom containers
2019-09-28 11:20:18 +00:00
feat: Implement the prompt module for time (#138) Add a module which displays the current time in a format requested by the user. Disabled by default.
2019-09-10 17:54:40 +00:00
This module is disabled by default.
To enable it, set `disabled` to `false` in your configuration file.
docs: Add extra newlines around custom containers
2019-09-28 11:20:18 +00:00
feat: Implement the prompt module for time (#138) Add a module which displays the current time in a format requested by the user. Disabled by default.
2019-09-10 17:54:40 +00:00
:::
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
| ----------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `format` | `"at [$time]($style) "` | The format string for the module. |
| `use_12hr` | `false` | Enables 12 hour formatting |
| `time_format` | see below | The [chrono format string](https://docs.rs/chrono/0.4.7/chrono/format/strftime/index.html) used to format the time. |
| `style` | `"bold yellow"` | The style for the module time |
| `utc_time_offset` | `"local"` | Sets the UTC offset to use. Range from -24 &lt; x &lt; 24. Allows floats to accommodate 30/45 minute timezone offsets. |
| `disabled` | `true` | Disables the `time` module. |
| `time_range` | `"-"` | Sets the time range during which the module will be shown. Times must be specified in 24-hours format |
If `use_12hr` is `true`, then `time_format` defaults to `"%r"`. Otherwise, it defaults to `"%T"`.
Manually setting `time_format` will override the `use_12hr` setting.
feat: Implement the prompt module for time (#138) Add a module which displays the current time in a format requested by the user. Disabled by default.
2019-09-10 17:54:40 +00:00
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | ---------- | ----------------------------------- |
| time | `13:08:10` | The current time. |
| style\* | | Mirrors the value of option `style` |
\*: This variable can only be used as a part of a style string
feat: Implement the prompt module for time (#138) Add a module which displays the current time in a format requested by the user. Disabled by default.
2019-09-10 17:54:40 +00:00
### Example
```toml
# ~/.config/starship.toml
[time]
disabled = false
docs: Update defaults in config docs (#1759) Have updated some of the config docs to correct the git_status default that was incorrect. Have also taken the time to switch some of the format strings to use toml literal strings rather than normal strings to simplify the escape strings.
2020-10-12 04:10:39 +00:00
format = '🕙[\[ $time \]]($style) '
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
time_format = "%T"
docs(time): add missing quotations in options and examples (#967)
2020-02-28 18:01:47 +00:00
utc_time_offset = "-5"
feat(time): Show module with time range (#992) * Creation of range field in TimeConfig * time_range parsing * Hide time module if outside of time_range * Tidying of code, and properly handling more cases * is_inside_time_range function * Tests and fmt * Update docs * The configuration needs the 24-hours format * Fix clippy errors
2020-05-31 17:43:08 +00:00
time_range = "10:00:00-14:00:00"
feat: Implement the prompt module for time (#138) Add a module which displays the current time in a format requested by the user. Disabled by default.
2019-09-10 17:54:40 +00:00
```
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
## Username
The `username` module shows active user's username.
The module will be shown if any of the following conditions are met:
- The current user is root
- The current user isn't the same as the one that is logged in
- The user is currently connected as an SSH session
feat: Add option to always show the username module (#408)
2019-09-22 20:32:11 +00:00
- The variable `show_always` is set to true
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
feat(username): Try harder to guess if inside ssh (#1964) * feat: Try harder to guess if inside ssh * Add test for SSH_CLIENT * Update documentation on checking ssh connection * Update docs/config/README.md Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-12-06 21:15:20 +00:00
::: tip
docs: fix custom containers to work with Crowdin Fixes #2063
2021-01-07 22:35:12 +00:00
feat(username): Try harder to guess if inside ssh (#1964) * feat: Try harder to guess if inside ssh * Add test for SSH_CLIENT * Update documentation on checking ssh connection * Update docs/config/README.md Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-12-06 21:15:20 +00:00
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.
docs: fix custom containers to work with Crowdin Fixes #2063
2021-01-07 22:35:12 +00:00
feat(username): Try harder to guess if inside ssh (#1964) * feat: Try harder to guess if inside ssh * Add test for SSH_CLIENT * Update documentation on checking ssh connection * Update docs/config/README.md Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-12-06 21:15:20 +00:00
:::
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Options
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
| Option | Default | Description |
| ------------- | ----------------------- | ------------------------------------- |
| `style_root` | `"bold red"` | The style used when the user is root. |
| `style_user` | `"bold yellow"` | The style used for non-root users. |
| `format` | `"[$user]($style) in "` | The format for the module. |
| `show_always` | `false` | Always shows the `username` module. |
| `disabled` | `false` | Disables the `username` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | ------------ | ------------------------------------------------------------------------------------------- |
| `style` | `"red bold"` | Mirrors the value of option `style_root` when root is logged in and `style_user` otherwise. |
| `user` | `"matchai"` | The currently logged-in user ID. |
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
### Example
```toml
# ~/.config/starship.toml
[username]
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
style_user = "white bold"
style_root = "black bold"
format = "user: [$user]($style) "
disabled = false
show_always = true
docs: Add vuepress with initial docs (#99) Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
2019-07-19 20:18:52 +00:00
```
Add support for custom modules. (#916)
2020-04-11 16:37:24 +00:00
feat(vagrant): Add support for Vagrant (#1812) Signed-off-by: Dentrax <furkan.turkal@hotmail.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2021-01-30 11:05:16 +00:00
## Vagrant
The `vagrant` module shows the currently installed version of Vagrant.
The module will be shown if any of the following conditions are met:
- The current directory contains a `Vagrantfile` file
### Options
| Option | Default | Description |
| ---------- | ---------------------------------- | --------------------------------------------------- |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `symbol` | `"⍱ "` | A format string representing the symbol of Vagrant. |
| `style` | `"cyan bold"` | The style for the module. |
| `disabled` | `false` | Disables the `Vagrant` module. |
### Variables
| Variable | Example | Description |
| -------- | ---------------- | ------------------------------------ |
| version | `Vagrant 2.2.10` | The version of `Vagrant` |
| 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
### Example
```toml
# ~/.config/starship.toml
[vagrant]
format = "via [⍱ $version](bold white) "
```
feat: add Zig module (#1231)
2020-05-21 16:49:49 +00:00
## Zig
feat(zig): Configure when the module is shown (#2311) * feat(zig): Configure when the module is shown * remove outdated comment
2021-02-14 21:21:44 +00:00
By default the the `zig` module shows the currently installed version of Zig.
feat: add Zig module (#1231)
2020-05-21 16:49:49 +00:00
The module will be shown if any of the following conditions are met:
- The current directory contains a `.zig` file
### Options
feat(zig): Configure when the module is shown (#2311) * feat(zig): Configure when the module is shown * remove outdated comment
2021-02-14 21:21:44 +00:00
| Option | Default | Description |
| ------------------- | ------------------------------------ | ----------------------------------------------------- |
| `symbol` | `"↯ "` | The symbol used before displaying the version of Zig. |
| `style` | `"bold yellow"` | The style for the module. |
| `format` | `"via [$symbol($version )]($style)"` | The format for the module. |
| `disabled` | `false` | Disables the `zig` module. |
| `detect_extensions` | `["zig"]` | Which extensions should trigger this module. |
| `detect_files` | `[]` | Which filenames should trigger this module. |
| `detect_folders` | `[]` | Which folders should trigger this module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Example | Description |
| -------- | -------- | ------------------------------------ |
| version | `v0.6.0` | The version of `zig` |
| 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
feat: add Zig module (#1231)
2020-05-21 16:49:49 +00:00
### Example
```toml
# ~/.config/starship.toml
[zig]
symbol = "⚡️ "
```
Add support for custom modules. (#916)
2020-04-11 16:37:24 +00:00
## Custom commands
The `custom` modules show the output of some arbitrary commands.
These modules will be shown if any of the following conditions are met:
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
Add support for custom modules. (#916)
2020-04-11 16:37:24 +00:00
- The current directory contains a file whose name is in `files`
- The current directory contains a directory whose name is in `directories`
- The current directory contains a file whose extension is in `extensions`
- The `when` command returns 0
::: tip
Multiple custom modules can be defined by using a `.`.
:::
::: tip
fix: use suffixes for modules before directory (#1645) Previously, all modules would have prefixes, which lead to the first module having a dangling prefix. This change ensures that the first few modules would instead have suffixes so that we don't start or end with a prefix or suffix.
2020-09-08 16:09:21 +00:00
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 `${...}`).
docs: Improvements in docs for custom modules (#1615) * docs: Clarify that commands will be passed in on stdin * docs: Clearer instruction how to include individual custom modules * docs: Include link to #1252 in docs for custom modules That issue is used to share custom modules. * docs: Remove reference to prompt_order Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-01 17:07:12 +00:00
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!
Add support for custom modules. (#916)
2020-04-11 16:37:24 +00:00
:::
### Options
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
| Option | Default | Description |
perf(custom): evaluate command lazily (#2173)
2021-01-20 18:01:49 +00:00
| ------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `command` | | The command whose output should be printed. The command will be passed on stdin to the shell. |
| `when` | | A shell command used as a condition to show the module. The module will be shown if the command returns a `0` status code. |
| `shell` | | [See below](#custom-command-shell) |
| `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. |
| `symbol` | `""` | The symbol used before displaying the command output. |
| `style` | `"bold green"` | The style for the module. |
| `format` | `"[$symbol($output )]($style)"` | The format for the module. |
| `disabled` | `false` | Disables this `custom` module. |
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
### Variables
| Variable | Description |
| -------- | -------------------------------------- |
| output | The output of shell command in `shell` |
| 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
Add support for custom modules. (#916)
2020-04-11 16:37:24 +00:00
fix(custom): improve handling of Powershell prompts (#1237) To improve overall support of PowerShell in custom modules, the ability to pass arguments to the shell was also added. Additionally, the arguments `-NoProfile -Command -` will be automatically passed to PowerShell, unless other arguments are given by the user.
2020-05-27 07:38:05 +00:00
#### Custom command shell
`shell` accepts a non-empty list of strings, where:
feat: refactor modules to use format strings (#1374)
2020-07-07 22:45:32 +00:00
fix(custom): improve handling of Powershell prompts (#1237) To improve overall support of PowerShell in custom modules, the ability to pass arguments to the shell was also added. Additionally, the arguments `-NoProfile -Command -` will be automatically passed to PowerShell, unless other arguments are given by the user.
2020-05-27 07:38:05 +00:00
- The first string is the path to the shell to use to execute the command.
- Other following arguments are passed to the shell.
If unset, it will fallback to STARSHIP_SHELL and then to "sh" on Linux, and "cmd /C" on Windows.
docs: Improvements in docs for custom modules (#1615) * docs: Clarify that commands will be passed in on stdin * docs: Clearer instruction how to include individual custom modules * docs: Include link to #1252 in docs for custom modules That issue is used to share custom modules. * docs: Remove reference to prompt_order Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com> Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>
2020-09-01 17:07:12 +00:00
The `command` will be passed in on stdin.
fix(custom): improve handling of Powershell prompts (#1237) To improve overall support of PowerShell in custom modules, the ability to pass arguments to the shell was also added. Additionally, the arguments `-NoProfile -Command -` will be automatically passed to PowerShell, unless other arguments are given by the user.
2020-05-27 07:38:05 +00:00
If `shell` is not given or only contains one element and Starship detects PowerShell will be used,
feat(python): Add option to change the python binary (#1297) * Add option to change the python binary We are going to start to have problems with the python binary as python2 is removed and replaced with python3. To make the transition easier I have added an option to the python module to allow the user to pick a particular binary, e.g `python3`, for the module to use when selecting the version of python. I have also refactored the python tests moving almost all of them into the module and removing the dependency on the version of python that is installed on the system. * Add advanced config section to python module docs Have added an advanced config section to the python module docs and moved the `python_binary` option into that section.
2020-06-14 09:27:10 +00:00
the following arguments will automatically be added: `-NoProfile -Command -`.
fix(custom): improve handling of Powershell prompts (#1237) To improve overall support of PowerShell in custom modules, the ability to pass arguments to the shell was also added. Additionally, the arguments `-NoProfile -Command -` will be automatically passed to PowerShell, unless other arguments are given by the user.
2020-05-27 07:38:05 +00:00
This behavior can be avoided by explicitly passing arguments to the shell, e.g.
```toml
shell = ["pwsh", "-Command", "-"]
```
docs(custom): add warning about custom command potentially freezing terminal (#1242)
2020-05-28 15:37:54 +00:00
::: 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.
:::
Add support for custom modules. (#916)
2020-04-11 16:37:24 +00:00
### Example
```toml
# ~/.config/starship.toml
[custom.foo]
command = "echo foo" # shows output of command
files = ["foo"] # can specify filters
when = """ test "$HOME" == "$PWD" """
doc: small doc fixups
2020-09-19 18:50:52 +00:00
format = " transcending [$output]($style)"
docs(custom): add warning about custom command potentially freezing terminal (#1242)
2020-05-28 15:37:54 +00:00
[custom.time]
command = "time /T"
files = ["*.pst"]
shell = ["pwsh.exe", "-NoProfile", "-Command", "-"]
Add support for custom modules. (#916)
2020-04-11 16:37:24 +00:00
```
Copy Permalink