mirror of
https://github.com/JanDeDobbeleer/oh-my-posh.git
synced 2024-09-20 13:37:31 -07:00
191 lines
13 KiB
Plaintext
191 lines
13 KiB
Plaintext
---
|
|
id: segment
|
|
title: Segment
|
|
sidebar_label: Segment
|
|
---
|
|
|
|
A segment is a part of the prompt with a certain context. There are different types available out-of-the-box, if you're
|
|
looking for what's included, feel free to skip this part and browse through the [segments][segments]. Keep reading to
|
|
understand how to configure a segment.
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
|
|
...
|
|
"blocks": [
|
|
{
|
|
...
|
|
"segments": [
|
|
{
|
|
"type": "path",
|
|
"style": "powerline",
|
|
"powerline_symbol": "\uE0B0",
|
|
"foreground": "#ffffff",
|
|
"background": "#61AFEF",
|
|
"template": " {{ .Path }}} ",
|
|
"properties": {
|
|
...
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
| Name | Type | Description |
|
|
| ---------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `type` | `string` | takes the `string` value referencing which segment logic it needs to run (see [segments][segments] for possible values) |
|
|
| `style` | `string` | see [Style][style] below. Possible values:<ul><li>`powerline`</li><li>`plain`</li><li>`diamond`</li><li>`accordion`</li><li>a go [text/template][go-text-template] [template][templates] resolving to the above values</li></ul> |
|
|
| `powerline_symbol` | `string` | character to use when `"style": "powerline"` |
|
|
| `invert_powerline` | `boolean` | if `true` swaps the foreground and background colors. Can be useful when the character you want does not exist in the perfectly mirrored variant for example - defaults to `false` |
|
|
| `leading_diamond` | `string` | character to use at the start of the segment. Will take the background color of the segment as its foreground color |
|
|
| `trailing_diamond` | `string` | character to use at the end of the segment. Will take the background color of the segment as its foreground color |
|
|
| `foreground` | `string` | [color][colors] |
|
|
| `foreground_templates` | `[]Template` | [color templates][color-templates] |
|
|
| `background` | `string` | [color][colors] |
|
|
| `background_templates` | `[]Template` | [color templates][color-templates] |
|
|
| `template` | `string` | a go [text/template][go-text-template] [template][templates] to render the prompt |
|
|
| `templates` | `[]Template` | in some cases having a single [template][templates] string is a bit cumbersome. Templates allows you to span the segment's [template][templates] string multiple lines where every [template][templates] is evaluated and depending on what you aim to achieve, there are two possible outcomes based on `templates_logic` |
|
|
| `templates_logic` | `string` | <ul><li>`first_match`: return the first non-whitespace string and skip everything else</li><li>`join`:evaluate all templates and join all non-whitespace strings (**default**)</li></ul> |
|
|
| `properties` | `[]Property` | see [Properties][properties] below |
|
|
| `interactive` | `boolean` | when is true, the segment text is not escaped to allow the use of interactive prompt escape sequences - defaults to `false` |
|
|
| `alias` | `string` | for use with [cross segment template properties][cstp] |
|
|
| `min_width` | `int` | if the terminal width is smaller than this value, the segment will be hidden. For your terminal width, see `oh-my-posh get width`. Defaults to `0` (disable) |
|
|
| `max_width` | `int` | if the terminal width exceeds this value, the segment will be hidden. For your terminal width, see `oh-my-posh get width`. Defaults to `0` (disable) |
|
|
|
|
## Style
|
|
|
|
Style defines how a prompt is rendered. Looking at the most prompt
|
|
themes out there, we identified 4 types. All of these require a different configuration and depending on the look
|
|
you want to achieve you might need to understand/use them all.
|
|
|
|
### Powerline
|
|
|
|
What started it all for us. Makes use of a single symbol (`powerline_symbol`) to separate the segments. It takes the
|
|
background color of the previous segment (or transparent if none) and the foreground of the current one (or transparent
|
|
if we're at the last segment). Expects segments to have a colored background, else there little use for this one.
|
|
|
|
### Plain
|
|
|
|
Simple. Colored text on a transparent background. Make sure to set `foreground` for maximum enjoyment.
|
|
|
|
### Diamond
|
|
|
|
While Powerline works great with a single symbol, sometimes you want a segment to have a different start and end symbol.
|
|
Just like a diamond: `< my segment text >`. The difference between this and plain is that the diamond symbols take the
|
|
segment background as their foreground color.
|
|
|
|
### Accordion
|
|
|
|
Same as Powerline except that it will display even when disabled, but without text. That way it seems
|
|
as if the segment is not expanded, just like an accordion.
|
|
|
|
## Properties
|
|
|
|
An array of Properties with a value. This is used inside of the segment logic to tweak what the output of the segment will be.
|
|
Segments have the ability to define their own Properties, but there are some shared ones being used by the engine which allow
|
|
you to customize the output even more.
|
|
|
|
### Shared properties
|
|
|
|
You can use these on any segment, the engine is responsible for adding them correctly.
|
|
|
|
| Name | Type |
|
|
| ----------------- | ---------- |
|
|
| `include_folders` | `[]string` |
|
|
| `exclude_folders` | `[]string` |
|
|
|
|
#### Include / Exclude Folders
|
|
|
|
Sometimes you might want to have a segment only rendered in certain folders. If `include_folders` is specified,
|
|
the segment will only be rendered when in one of those locations. If `exclude_folders` is specified, the segment
|
|
will not be rendered when in one of the excluded locations.
|
|
|
|
```json
|
|
"include_folders": [
|
|
"/Users/posh/Projects"
|
|
]
|
|
```
|
|
|
|
```json
|
|
"exclude_folders": [
|
|
"/Users/posh/Projects"
|
|
]
|
|
```
|
|
|
|
The strings specified in these properties are evaluated as [regular expressions][regex]. You
|
|
can use any valid regular expression construct, but the regular expression must match the entire directory
|
|
name. The following will match `/Users/posh/Projects/Foo` but not `/home/Users/posh/Projects/Foo`.
|
|
|
|
```json
|
|
"include_folders": [
|
|
"/Users/posh/Projects.*"
|
|
]
|
|
```
|
|
|
|
You can also combine these properties:
|
|
|
|
```json
|
|
"include_folders": [
|
|
"/Users/posh/Projects.*"
|
|
],
|
|
"exclude_folders": [
|
|
"/Users/posh/Projects/secret-project.*"
|
|
]
|
|
```
|
|
|
|
#### Notes
|
|
|
|
- Oh My Posh will accept both `/` and `\` as path separators for a folder and will match regardless of which
|
|
is used by the current operating system.
|
|
- Because the strings are evaluated as regular expressions, if you want to use a `\` in a Windows
|
|
directory name, you need to specify it as `\\\\`.
|
|
- The character `~` at the start of a specified folder will match the user's home directory.
|
|
- The comparison is case-insensitive on Windows and macOS, but case-sensitive on other operating systems.
|
|
|
|
This means that for user Bill, who has a user account `Bill` on Windows and `bill` on Linux, `~/Foo` might match
|
|
`C:\Users\Bill\Foo` or `C:\Users\Bill\foo` on Windows but only `/home/bill/Foo` on Linux.
|
|
|
|
## Hiding segments
|
|
|
|
### Conditionally
|
|
|
|
To hide a whole segment including the leading and trailing symbol based on a [template][templates], the template must
|
|
**evaluate to an empty string**. This can be achieved with conditional statements (`if`). The example below will render
|
|
a diamond segment, only if the environment variable `POSH_ENV` is not empty.
|
|
|
|
Only spaces are excluded, meaning you can still add line breaks and tabs if that is something you're after.
|
|
|
|
```json
|
|
{
|
|
"type": "text",
|
|
"style": "diamond",
|
|
"leading_diamond": " \ue0b6",
|
|
"trailing_diamond": "\ue0b4",
|
|
"foreground": "#ffffff",
|
|
"background": "#d53c14",
|
|
"template": "{{ if .Env.POSH_ENV }} \uf8c5 {{ .Env.POSH_ENV }} {{ end }}"
|
|
}
|
|
```
|
|
|
|
### On the fly
|
|
|
|
Sometimes run into a situation where you don't want to see a specific segment but the use-case does not justify
|
|
using a conditional template. In this case you can use the `oh-my-posh toggle <type>` command to toggle the
|
|
segment on or off. This works on a **per shell session basis**, meaning that if you toggle a segment off in one instance
|
|
of a shell, it will not disable in the others.
|
|
|
|
To list the currently toggled segments, use `oh-my-posh get toggles`.
|
|
|
|
[segments]: /docs/segments/angular
|
|
[properties]: #properties
|
|
[style]: #style
|
|
[colors]: /docs/configuration/colors
|
|
[go-text-template]: https://golang.org/pkg/text/template/
|
|
[sprig]: https://masterminds.github.io/sprig/
|
|
[regex]: https://www.regular-expressions.info/tutorial.html
|
|
[templates]: templates.mdx
|
|
[color-templates]: /docs/configuration/colors#color-templates
|
|
[cstp]: templates.mdx#cross-segment-template-properties
|