mirror of
https://github.com/Llewellynvdm/starship.git
synced 2024-11-11 07:40:57 +00:00
08cf33522a
Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com> Co-authored-by: Matan Kushner <hello@matchai.me>
337 lines
10 KiB
Markdown
337 lines
10 KiB
Markdown
# Configuration
|
||
|
||
::: tip
|
||
🔥 Configuration is currently being worked on.
|
||
Many new configuration options will be available in coming releases.
|
||
:::
|
||
|
||
To get started configuring starship, create the following file: `~/.config/starship.toml`.
|
||
|
||
```shell
|
||
$ touch ~/.config/starship.toml
|
||
```
|
||
|
||
All configuration for starship is done in this [TOML](https://github.com/toml-lang/toml) file:
|
||
|
||
```toml
|
||
# Replace the "➜" symbol in the prompt with "❯"
|
||
[character] # The name of the module we are confguring is "character"
|
||
symbol = "❯" # The "symbol" segment is being set to "❯"
|
||
|
||
# Disable the package module, hiding it from the prompt completely
|
||
[package]
|
||
disabled = true
|
||
```
|
||
|
||
### 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.
|
||
|
||
**Segment**: Smaller sub-components that compose a module. For example, the "symbol" segment in the "nodejs" module contains the character that is shown before the version number (⬢ by default).
|
||
|
||
Here is the representation of the node module. In the following example, "symbol" and "version"
|
||
are segments within it. Every module also has a prefix and suffix that are the default terminal color.
|
||
|
||
```
|
||
[prefix] [symbol] [version] [suffix]
|
||
"via " "⬢" "v10.4.1" ""
|
||
```
|
||
|
||
## 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
|
||
|
||
| Variable | 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. |
|
||
| `disabled` | `false` | Disables the `battery` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[battery]
|
||
full_symbol = "🔋"
|
||
charging_symbol = "⚡️"
|
||
discharging_symbol = "💀"
|
||
```
|
||
|
||
## Character
|
||
|
||
The `character` module shows a character (usually an arrow) beside where the text
|
||
is entered in your terminal.
|
||
|
||
The character will be green if the status of your
|
||
last command had a successful status code (zero), and will be red if the last
|
||
command had an unsuccessful status code (non-zero).
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | ---------------------------------------------------- |
|
||
| `symbol` | `"➜"` | The symbol used before the text input in the prompt. |
|
||
| `disabled` | `false` | Disables the `character` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[character]
|
||
symbol = "❯"
|
||
```
|
||
|
||
## 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.
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | -------------------------------- |
|
||
| `disabled` | `false` | Disables the `directory` module. |
|
||
|
||
## Git Branch
|
||
|
||
The `git_branch` module shows the active branch of the repo in your current directory.
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | ----------------------------------------------------------------------------- |
|
||
| `symbol` | `" "` | The symbol used before the branch name of the repo in your current directory. |
|
||
| `disabled` | `false` | Disables the `git_branch` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[git_branch]
|
||
symbol = "🌱 "
|
||
```
|
||
|
||
## Git Status
|
||
|
||
The `git_status` module shows symbols representing the state of the repo in your
|
||
current directory.
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ------------ | ------- | ------------------------------------------------------- |
|
||
| `conflicted` | `"="` | This branch has merge conflicts. |
|
||
| `ahead` | `"⇡"` | This branch is ahead of the branch being tracked. |
|
||
| `behind` | `"⇣"` | This branch is behind of the branch being tracked. |
|
||
| `diverged` | `"⇕"` | This branch has diverged from the branch being tracked. |
|
||
| `untracked` | `"?"` | There are untracked files in the working directory. |
|
||
| `stashed` | `"$"` | A stash exists for the local repository. |
|
||
| `modified` | `"!"` | There are file modifications in the working directory. |
|
||
| `added` | `"+"` | A new file has been added to the staging area. |
|
||
| `renamed` | `"»"` | A renamed file has been added to the staging area. |
|
||
| `deleted` | `"✘"` | A file's deletion has been added to the staging area. |
|
||
| `disabled` | `false` | Disables the `git_status` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[git_status]
|
||
conflicted = "🏳"
|
||
ahead = "🏎💨"
|
||
behind = "😰"
|
||
diverged = "😵"
|
||
untracked = "🤷"
|
||
stashed = "📦"
|
||
modified = "📝"
|
||
added = "➕"
|
||
renamed = "👅"
|
||
deleted = "🗑"
|
||
```
|
||
|
||
## 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
|
||
- The current directory contains a `Godeps` directory
|
||
- The current directory contains a file with the `.go` extension
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | -------------------------------------------------------- |
|
||
| `symbol` | `"🐹 "` | The symbol used before displaying the version of Golang. |
|
||
| `disabled` | `false` | Disables the `golang` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[golang]
|
||
symbol = "🏎💨 "
|
||
```
|
||
|
||
## Line Break
|
||
|
||
The `line_break` module separates the prompt into two lines.
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | ------------------------------------------------------------------ |
|
||
| `disabled` | `false` | Disables the `line_break` module, making the prompt a single line. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[line_break]
|
||
disabled = true
|
||
```
|
||
|
||
## 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
|
||
- The current directory contains a `node_modules` directory
|
||
- The current directory contains a file with the `.js` extension
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | -------------------------------------------------------- |
|
||
| `symbol` | `"⬢ "` | The symbol used before displaying the version of NodeJS. |
|
||
| `disabled` | `false` | Disables the `nodejs` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[nodejs]
|
||
symbol = "🤖 "
|
||
```
|
||
|
||
## 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` and
|
||
`cargo` 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
|
||
|
||
> ⚠️ The version being shown is that of the package whose source code is in your
|
||
> current directory, not your package manager.
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | ---------------------------------------------------------- |
|
||
| `symbol` | `"📦 "` | The symbol used before displaying the version the package. |
|
||
| `disabled` | `false` | Disables the `package` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[package]
|
||
symbol = "🎁 "
|
||
```
|
||
|
||
## Python
|
||
|
||
The `python` module shows the currently installed version of Python.
|
||
The module will be shown if any of the following conditions are met:
|
||
|
||
- The current directory contains a `.python-version` file
|
||
- The current directory contains a `requirements.txt` file
|
||
- The current directory contains a `pyproject.toml` file
|
||
- The current directory contains a file with the `.py` extension
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | -------------------------------------------------------- |
|
||
| `symbol` | `"🐍 "` | The symbol used before displaying the version of Python. |
|
||
| `disabled` | `false` | Disables the `python` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[python]
|
||
symbol = "👾 "
|
||
```
|
||
|
||
## 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
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | -------------------------------------------------------- |
|
||
| `symbol` | `"🦀 "` | The symbol used before displaying the version of Python. |
|
||
| `disabled` | `false` | Disables the `rust` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[rust]
|
||
symbol = "⚙️ "
|
||
```
|
||
|
||
## 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
|
||
|
||
### Options
|
||
|
||
| Variable | Default | Description |
|
||
| ---------- | ------- | ------------------------------- |
|
||
| `disabled` | `false` | Disables the `username` module. |
|
||
|
||
### Example
|
||
|
||
```toml
|
||
# ~/.config/starship.toml
|
||
|
||
[username]
|
||
disabled = true
|
||
```
|