mirror of
https://github.com/JanDeDobbeleer/oh-my-posh.git
synced 2024-12-29 04:49:39 -08:00
198 lines
9.7 KiB
Plaintext
198 lines
9.7 KiB
Plaintext
---
|
|
id: general
|
|
title: General
|
|
sidebar_label: General
|
|
---
|
|
|
|
import Tabs from "@theme/Tabs";
|
|
import TabItem from "@theme/TabItem";
|
|
|
|
Oh My Posh renders your prompt based on the definition of _blocks_ (like Lego) which contain one or more _segments_.
|
|
A really simple configuration could look like this. The default format is `json`, but we also support `toml` and `yaml`.
|
|
There's a [schema][schema] available which is kept up-to-date and helps with autocomplete and validation of the configuration.
|
|
|
|
:::info
|
|
There are a few [themes][themes] available which are basically predefined configs. You can use these as they are, or as a
|
|
starting point to create your own configuration.
|
|
:::
|
|
|
|
<Tabs
|
|
defaultValue="json"
|
|
groupId="sample"
|
|
values={[
|
|
{ label: 'json', value: 'json', },
|
|
{ label: 'yaml', value: 'yaml', },
|
|
{ label: 'toml', value: 'toml', },
|
|
]
|
|
}>
|
|
<TabItem value="json">
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
|
|
"final_space": true,
|
|
"version": 2,
|
|
"blocks": [
|
|
{
|
|
"type": "prompt",
|
|
"alignment": "left",
|
|
"segments": [
|
|
{
|
|
"type": "path",
|
|
"style": "powerline",
|
|
"powerline_symbol": "\uE0B0",
|
|
"foreground": "#ffffff",
|
|
"background": "#61AFEF",
|
|
"properties": {
|
|
"style": "folder"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="yaml">
|
|
|
|
```yaml
|
|
# yaml-language-server: $schema=https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
|
|
final_space: true
|
|
version: 2
|
|
blocks:
|
|
- type: prompt
|
|
alignment: left
|
|
segments:
|
|
- type: path
|
|
style: powerline
|
|
powerline_symbol: ""
|
|
foreground: "#ffffff"
|
|
background: "#61AFEF"
|
|
properties:
|
|
style: folder
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="toml">
|
|
|
|
```toml
|
|
"$schema" = "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json"
|
|
final_space = true
|
|
version = 2
|
|
|
|
[[blocks]]
|
|
type = "prompt"
|
|
alignment = "left"
|
|
|
|
[[blocks.segments]]
|
|
type = "path"
|
|
style = "powerline"
|
|
powerline_symbol = ""
|
|
foreground = "#ffffff"
|
|
background = "#61AFEF"
|
|
|
|
[blocks.segments.properties]
|
|
style = "folder"
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
With this configuration, a single powerline segment is rendered that shows the name of the folder you're currently in.
|
|
To set this configuration in combination with a Oh My Posh [executable][releases], use the `--config` flag to
|
|
set a path to a file containing the above code. The `--shell universal` flag is used to print the prompt without
|
|
escape characters to see the prompt as it would be shown inside a prompt function for your shell.
|
|
|
|
:::caution
|
|
The command below will not persist the configuration for your shell but print the prompt in your terminal.
|
|
If you want to use your own configuration permanently, adjust the prompt configuration to use your custom
|
|
theme.
|
|
:::
|
|
|
|
```bash
|
|
oh-my-posh print primary --config sample.json --shell uni
|
|
```
|
|
|
|
If all goes according to plan, you should see the prompt being printed out on the line below. In case you see a lot of
|
|
boxes with question marks, set up your terminal to use a [supported font][font] before continuing.
|
|
|
|
:::tip
|
|
The `--config` flag can accept either a local filepath or a remotely hosted config file.
|
|
|
|
For example, the following is a valid `--config` flag:
|
|
`--config 'https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/jandedobbeleer.omp.json'`
|
|
:::
|
|
|
|
## General Settings
|
|
|
|
| Name | Type | Default | Description |
|
|
| --------------------------- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `final_space` | `boolean` | | when true adds a space at the end of the prompt |
|
|
| `pwd` | `string` | | notify terminal of current working directory, values can be `osc99`, `osc7` or `osc51` depending on your terminal. Supports [templates][templates] |
|
|
| `terminal_background` | `string` | | [color][colors] - terminal background color, set to your terminal's background color when you notice black elements in Windows Terminal or the Visual Studio Code integrated terminal |
|
|
| `accent_color` | `string` | | [color][colors] - accent color, used as a fallback when the `accent` [color][accent] is not supported |
|
|
| `var` | `map[string]any` | | config variables to use in [templates][templates]. Can be any value |
|
|
| `shell_integration` | `boolean` | `false` | enable shell integration using FinalTerm's OSC sequences. Works in bash, cmd (Clink v1.14.25+), fish, powershell and zsh |
|
|
| `enable_cursor_positioning` | `boolean` | `false` | enable fetching the cursor position in bash and zsh to allow automatic hiding of leading newlines when at the top of the shell |
|
|
| `patch_pwsh_bleed` | `boolean` | `false` | patch a PowerShell bug where the background colors bleed into the next line at the end of the buffer (can be removed when [this][pwsh-bleed] is merged) |
|
|
| `disable_notice` | `boolean` | `false` | disables the notice that a new upgrade is available when `auto_upgrade` is disabled |
|
|
| `auto_upgrade` | `boolean` | `false` | enable [automatic upgrades][upgrade] for Oh My Posh (supports Windows, macOS and Linux) |
|
|
| `iterm_features` | `[]string` | `false` | enable iTerm2 specific features:<ul><li>`prompt_mark`: add the `iterm2_prompt_mark` [function][iterm2-si] for supported shells</li><li>`current_dir`: expose the current directory for iTerm2</li><li>`remote_host`: expose the current remote and user for iTerm2</li></ul> |
|
|
|
|
### JSON Schema Validation
|
|
|
|
As mentioned above, Oh My Posh themes can utilize JSON Schema to validate their contents. Themes should include a link to
|
|
the [external schema document][schema] which prescribes the appropriate structure and contents for various elements. If
|
|
your code editor is configured to use JSON Schema, it will compare your custom theme to the external document, and issue
|
|
warnings for discrepancies.
|
|
|
|
For example, given the following code:
|
|
|
|
```json
|
|
...
|
|
"segments": [
|
|
{
|
|
"type": "an_invalid_entry",
|
|
"template": "{{ if gt .Code 0 }}\uf134{{ end }}",
|
|
}
|
|
]
|
|
...
|
|
```
|
|
|
|
Warnings will be raised for type, since `an_invalid_entry` is not in the list of acceptable values, as well as
|
|
for the entire segment item (enclosed in `{}`), since it lacks the required `style` key. Take advantage of these
|
|
warnings, and ignore them at your peril.
|
|
|
|
### Accepted Formats
|
|
|
|
Oh My Posh supports three file formats for themes: `json`, `yaml`, and `toml`.
|
|
|
|
Various converters exist to convert between these, although they aren't perfect and will require manual
|
|
adjustment. Notably, the schema implementation for json is as follows:
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json"
|
|
}
|
|
```
|
|
|
|
While for yaml:
|
|
|
|
```yaml
|
|
# yaml-language-server: $schema=https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
|
|
```
|
|
|
|
Converters won't catch this change, so you will need to adjust manually.
|
|
|
|
[releases]: https://github.com/JanDeDobbeleer/oh-my-posh/releases/latest
|
|
[font]: /docs/installation/fonts
|
|
[schema]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/themes/schema.json
|
|
[themes]: https://github.com/JanDeDobbeleer/oh-my-posh/tree/main/themes
|
|
[colors]: /docs/configuration/colors
|
|
[accent]: /docs/configuration/colors#standard-colors
|
|
[templates]: /docs/configuration/templates#config-variables
|
|
[pwsh-bleed]: https://github.com/PowerShell/PowerShell/pull/19019
|
|
[iterm2-si]: https://iterm2.com/documentation-shell-integration.html
|
|
[upgrade]: /docs/installation/upgrade#automatic
|