Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions book/3rdpartyprompts.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,17 +33,17 @@ For MacOS users:

1. You can install oh-my-posh using `brew`, just following the [guide here](https://ohmyposh.dev/docs/installation/macos)
2. Download and install a [nerd font](https://github.com/ryanoasis/nerd-fonts).
3. Set the PROMPT_COMMAND in the file output by `$nu.config-path`, here is a code snippet:
3. Set the prompt in the file output by `$nu.config-path`, here is a code snippet:

```nu
let posh_dir = (brew --prefix oh-my-posh | str trim)
let posh_theme = $'($posh_dir)/share/oh-my-posh/themes/'
# Change the theme names to: zash/space/robbyrussell/powerline/powerlevel10k_lean/
# material/half-life/lambda Or double lines theme: amro/pure/spaceship, etc.
# For more [Themes demo](https://ohmyposh.dev/docs/themes)
$env.PROMPT_COMMAND = { || oh-my-posh print primary --config $'($posh_theme)/zash.omp.json' }
$env.config.prompt.left = { || oh-my-posh print primary --config $'($posh_theme)/zash.omp.json' }
# Optional
$env.PROMPT_INDICATOR = $"(ansi y)$> (ansi reset)"
$env.config.prompt.indicator = $"(ansi y)$> (ansi reset)"
```

## Starship
Expand Down Expand Up @@ -82,15 +82,15 @@ def create_left_prompt [] {
}

# Use nushell functions to define your right and left prompt
$env.PROMPT_COMMAND = { || create_left_prompt }
$env.PROMPT_COMMAND_RIGHT = ""
$env.config.prompt.left = { || create_left_prompt }
$env.config.prompt.right = ""

# The prompt indicators are environmental variables that represent
# The prompt indicators are strings that represent
# the state of the prompt
$env.PROMPT_INDICATOR = ""
$env.PROMPT_INDICATOR_VI_INSERT = ": "
$env.PROMPT_INDICATOR_VI_NORMAL = "〉"
$env.PROMPT_MULTILINE_INDICATOR = "::: "
$env.config.prompt.indicator = ""
$env.config.prompt.vi_insert = ": "
$env.config.prompt.vi_normal = "〉"
$env.config.prompt.multiline = "::: "
```

Now restart Nu.
Expand Down
45 changes: 26 additions & 19 deletions book/coloring_and_theming.md
Original file line number Diff line number Diff line change
Expand Up @@ -427,52 +427,59 @@ $env.config.color_config.shape_int = { fg: "#0000ff" attr: b}

## Prompt Configuration and Coloring

The Nushell prompt is configurable through these environment variables and config items:
The Nushell prompt is configurable through these keys of `$env.config.prompt`:

- `PROMPT_COMMAND`: Code to execute for setting up the prompt (block)
- `PROMPT_COMMAND_RIGHT`: Code to execute for setting up the _RIGHT_ prompt (block) (see oh-my.nu in nu_scripts)
- `PROMPT_INDICATOR` = "> ": The indicator printed after the prompt in Emacs mode
- `PROMPT_INDICATOR_VI_INSERT` = ": ": The indicator in Vi insert mode (and Helix insert mode)
- `PROMPT_INDICATOR_VI_NORMAL` = "> ": The indicator in Vi normal and visual mode (and Helix normal and select mode)
- `PROMPT_MULTILINE_INDICATOR` = "::: "
- `render_right_prompt_on_last_line`: Bool value to enable or disable the right prompt to be rendered on the last line of the prompt
- `left`: Code to execute for setting up the prompt (closure or string)
- `right`: Code to execute for setting up the _RIGHT_ prompt (closure or string) (see oh-my.nu in nu_scripts)
- `indicator` = "> ": The indicator printed after the prompt in Emacs mode
- `vi_insert` = "> ": The indicator in Vi insert mode (and Helix insert mode)
- `vi_normal` = ": ": The indicator in Vi normal mode (and Helix normal mode)
- `vi_visual` = "+ ": The indicator in Vi visual mode (and Helix select mode)
- `multiline` = "::: "
- `render_right_on_last_line`: Bool value to enable or disable the right prompt to be rendered on the last line of the prompt

Example: For a simple prompt one could do this. Note that `PROMPT_COMMAND` requires a `block` whereas the others require a `string`.
::: tip
Before Nushell 0.118 these were the `PROMPT_*` environment variables (`$env.PROMPT_COMMAND`, `$env.PROMPT_INDICATOR`, ...). Those are deprecated but still take precedence when set. See [Prompt Configuration](configuration.md#prompt-configuration).
:::

Example: For a simple prompt one could do this. Note that `left` and `right` accept a closure whereas the indicators require a `string`.

```nu
$env.PROMPT_COMMAND = { $"(date now | format date '%m/%d/%Y %I:%M:%S%.3f'): (pwd | path basename)" }
$env.config.prompt.left = { $"(date now | format date '%m/%d/%Y %I:%M:%S%.3f'): (pwd | path basename)" }
```

If you don't like the default `PROMPT_INDICATOR` you could change it like this.
If you don't like the default `indicator` you could change it like this.

```nu
$env.PROMPT_INDICATOR = "❯ "
$env.config.prompt.indicator = "❯ "
```

If you're using `starship`, you'll most likely want to show the right prompt on the last line of the prompt, just like zsh or fish. You could modify the `config.nu` file, just set `render_right_prompt_on_last_line` to true:
If you're using `starship`, you'll most likely want to show the right prompt on the last line of the prompt, just like zsh or fish. You could modify the `config.nu` file, just set `render_right_on_last_line` to true:

```nu
$env.config.render_right_prompt_on_last_line = true
$env.config.prompt.render_right_on_last_line = true
```

Coloring of the prompt is controlled by the `block` in `PROMPT_COMMAND` where you can write your own custom prompt. We've written a slightly fancy one that has git statuses located in the [nu_scripts repo](https://github.com/nushell/nu_scripts/blob/main/modules/prompt/oh-my.nu).
Coloring of the prompt is controlled by the closure in `$env.config.prompt.left` where you can write your own custom prompt. We've written a slightly fancy one that has git statuses located in the [nu_scripts repo](https://github.com/nushell/nu_scripts/blob/main/modules/prompt/oh-my.nu).

Text in a custom prompt that sets no color of its own is shown in the terminal's default foreground. The indicators are colored by the line editor; to style one yourself, include the escape codes in its value, e.g. `$"(ansi light_red)> "`.

### Transient Prompt

If you want a different prompt displayed for previously entered commands, you can use Nushell's transient prompt feature. This can be useful if your prompt has lots of information that is unnecessary to show for previous lines (e.g. time and Git status), since you can make it so that previous lines show with a shorter prompt.

Each of the `PROMPT_*` variables has a corresponding `TRANSIENT_PROMPT_*` variable to be used for changing that segment when displaying past prompts: `TRANSIENT_PROMPT_COMMAND`, `TRANSIENT_PROMPT_COMMAND_RIGHT`, `TRANSIENT_PROMPT_INDICATOR`, `TRANSIENT_PROMPT_INDICATOR_VI_INSERT`, `TRANSIENT_PROMPT_INDICATOR_VI_NORMAL`, `TRANSIENT_PROMPT_MULTILINE_INDICATOR`. By default, the `PROMPT_*` variables are used for displaying past prompts.
Each of the keys above has a counterpart under `$env.config.prompt.transient` to be used for changing that segment when displaying past prompts: `transient.left`, `transient.right`, `transient.indicator`, `transient.vi_insert`, `transient.vi_normal`, `transient.vi_visual`, `transient.multiline`. A key set to `null` keeps what the normal prompt showed. That is the default for all of them except `transient.right` and `transient.multiline`, which default to an empty string.

For example, if you want to make past prompts show up without a left prompt entirely and leave only the indicator, you can use:

```nu
$env.TRANSIENT_PROMPT_COMMAND = ""
$env.config.prompt.transient.left = ""
```

If you want to go back to the normal left prompt, you'll have to unset `TRANSIENT_PROMPT_COMMAND`:
If you want to go back to the normal left prompt, set the key back to `null`:

```nu
hide-env TRANSIENT_PROMPT_COMMAND
$env.config.prompt.transient.left = null
```

## `LS_COLORS` Colors for the [`ls`](/commands/docs/ls.md) Command
Expand Down
2 changes: 1 addition & 1 deletion book/coming_from_cmd.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ This table was last updated for Nu 0.116.0.
| `PATH <path>;%PATH%` | `$env.Path = ($env.Path \| prepend <path>)` | Edit the path variable |
| `PATH %PATH%;<path>` | `$env.Path = ($env.Path \| append <path>)` | Edit the path variable |
| `PAUSE` | `input "Press any key to continue . . ."` | Pause script execution |
| `PROMPT <template>` | `$env.PROMPT_COMMAND = { <command> }` | Change the terminal prompt |
| `PROMPT <template>` | `$env.config.prompt.left = { <command> }` | Change the terminal prompt |
| `PUSHD <path>`/`POPD` | `dirs add <path>`/`dirs drop` (after `use std/dirs`) | Change working directory temporarily |
| `REM` | `#` | Comments |
| `REN` or `RENAME` | `mv` | Rename files |
Expand Down
76 changes: 49 additions & 27 deletions book/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,62 +163,84 @@ Nushell provides a number of prompt configuration options. By default, Nushell i

- A prompt which includes the current directory, abbreviated using `~` if it is (or is under)
the home directory.
- A prompt indicator which appears immediately to the right of the prompt. This defaults to `> ` when in normal editing mode, or a `: ` when in Vi-insert mode. Note extra space after the character to provide separation of the command from the prompt.
- A prompt indicator which appears immediately to the right of the prompt. This defaults to `> ` in Emacs and Vi-insert mode, `: ` in Vi-normal mode and `+ ` in Vi-visual mode. Note extra space after the character to provide separation of the command from the prompt.
- A right-prompt with the date and time
- An indicator which is displayed when the current commandline extends over multiple lines - `::: ` by default

The environment variables which control these prompt components are:
These prompt components are configured under `$env.config.prompt`:

- `$env.PROMPT_COMMAND`: The prompt itself
- `$env.PROMPT_COMMAND_RIGHT`: A prompt which can appear on the right side of the terminal
- `$env.PROMPT_INDICATOR`: Emacs mode indicator
- `$env.PROMPT_INDICATOR_VI_NORMAL`: Vi-normal mode indicator
- `$env.PROMPT_INDICATOR_VI_INSERT`: Vi-insert mode indicator
- `$env.PROMPT_MULTILINE_INDICATOR`: The multi-line indicator
- `$env.config.prompt.left`: The prompt itself
- `$env.config.prompt.right`: A prompt which can appear on the right side of the terminal
- `$env.config.prompt.indicator`: Emacs mode indicator
- `$env.config.prompt.vi_insert`: Vi-insert mode indicator
- `$env.config.prompt.vi_normal`: Vi-normal mode indicator
- `$env.config.prompt.vi_visual`: Vi-visual mode indicator
- `$env.config.prompt.multiline`: The multi-line indicator
- `$env.config.prompt.render_right_on_last_line`: Whether the right prompt sits on the last line of a multi-line left prompt (`false` by default)

Each of these variables accepts either:
`left` and `right` accept either:

- A string, in which case the component will be statically displayed as that string.
- A closure (with no parameters), in which case the component will be dynamically displayed based on the closure's code.
- `null`, in which case the component will revert to its internal default value.
- `null`, in which case the line editor's built-in prompt is used.

The indicators are plain strings. Which one is shown depends on the current edit mode, so they cannot be computed inside the prompt closure.

The default `left` and `right` prompts are closures. You can read them with `view source $env.config.prompt.left`, build on them by keeping a reference, and get them back from [`config default`](/commands/docs/config_default.md):

```nu
# Wrap the default prompt
let default_left = $env.config.prompt.left
$env.config.prompt.left = {|| $"[(do $default_left)] " }

# Restore the default prompt
$env.config.prompt = (config default).prompt
```

::: tip
To disable the right-prompt, for instance, add the following to your startup config:

```nu
$env.PROMPT_COMMAND_RIGHT = ""
# or
$env.PROMPT_COMMAND_RIGHT = {||}
$env.config.prompt.right = ""
```

:::

::: warning Prompt environment variables
Before Nushell 0.118, the prompt was configured through environment variables: `$env.PROMPT_COMMAND`, `$env.PROMPT_COMMAND_RIGHT`, `$env.PROMPT_INDICATOR`, `$env.PROMPT_INDICATOR_VI_INSERT`, `$env.PROMPT_INDICATOR_VI_NORMAL`, `$env.PROMPT_MULTILINE_INDICATOR` and their `TRANSIENT_PROMPT_*` counterparts.

These are deprecated. A variable that you (or a tool such as Starship or oh-my-posh) set still takes precedence over the matching `$env.config.prompt` key, so existing configurations keep working.

Nushell no longer sets them at startup. Code that _reads_ one to find the current prompt, such as `let old = $env.PROMPT_COMMAND`, has to read `$env.config.prompt.left` instead.
:::

#### Transient Prompts

Nushell also supports transient prompts, which allow a different prompt to be shown _after_ a commandline has been executed. This can be useful in several situations:

- When using a multi-line prompt, the transient prompt can be a more condensed version.
- Removing the transient multiline indicator and right-prompt can simplify copying from the terminal.

As with the normal prompt commands above, each transient prompt can accept a (static) string, a (dynamic) closure, or a `null` to use the Nushell internal defaults.
Every key under `$env.config.prompt.transient` mirrors one of the keys above. Setting a key to `null` keeps whatever the normal prompt showed for that component, so only the components worth condensing need to be set.

The environment variables which control the transient prompt components are:
- `$env.config.prompt.transient.left`: The prompt itself after the commandline has been executed
- `$env.config.prompt.transient.right`: A prompt which can appear on the right side of the terminal
- `$env.config.prompt.transient.indicator`: Emacs mode indicator
- `$env.config.prompt.transient.vi_insert`: Vi-insert mode indicator
- `$env.config.prompt.transient.vi_normal`: Vi-normal mode indicator
- `$env.config.prompt.transient.vi_visual`: Vi-visual mode indicator
- `$env.config.prompt.transient.multiline`: The multi-line indicator

- `$env.TRANSIENT_PROMPT_COMMAND`: The prompt itself after the commandline has been executed
- `$env.TRANSIENT_PROMPT_COMMAND_RIGHT`: A prompt which can appear on the right side of the terminal
- `$env.TRANSIENT_PROMPT_INDICATOR`: Emacs mode indicator
- `$env.TRANSIENT_PROMPT_INDICATOR_VI_NORMAL`: Vi-normal mode indicator
- `$env.TRANSIENT_PROMPT_INDICATOR_VI_INSERT`: Vi-insert mode indicator
- `$env.TRANSIENT_PROMPT_MULTILINE_INDICATOR`: The multi-line indicator
As with the normal prompt, `left` and `right` accept a (static) string or a (dynamic) closure, and the indicators accept a string.

::: tip
Nushell sets `TRANSIENT_PROMPT_COMMAND_RIGHT` and `TRANSIENT_PROMPT_MULTILINE_INDICATOR` to an empty string (`""`) so that each disappears after the previous command is entered. This simplifies copying and pasting from the terminal.
`transient.right` and `transient.multiline` default to an empty string (`""`) so that each disappears after the previous command is entered. This simplifies copying and pasting from the terminal. The other keys default to `null`.

To disable this feature and always show those items, set:

```nu
$env.TRANSIENT_PROMPT_COMMAND_RIGHT = null
$env.TRANSIENT_PROMPT_MULTILINE_INDICATOR = null
$env.config.prompt.transient.right = null
$env.config.prompt.transient.multiline = null
```

:::
Expand All @@ -228,7 +250,7 @@ $env.TRANSIENT_PROMPT_MULTILINE_INDICATOR = null
A prompt closure that takes a long time to run, such as one that calls `git`, delays every prompt. Instead, the closure can start a [background job](./background_jobs.md) and return right away. When the job finishes, it calls [`commandline set-prompt`](/commands/docs/commandline_set-prompt.md) to fill in the missing part without disturbing the line being edited. For example, to show the current Git branch in the right prompt:

```nu
$env.PROMPT_COMMAND_RIGHT = {
$env.config.prompt.right = {
job spawn {
let branch = (git branch --show-current | complete | get stdout | str trim)
commandline set-prompt --right $"(ansi yellow)($branch)(ansi reset)"
Expand All @@ -238,9 +260,9 @@ $env.PROMPT_COMMAND_RIGHT = {
}
```

`commandline set-prompt` sets the left prompt by default. Use `--right`, `--indicator`, `--vi-insert`, `--vi-normal`, or `--multiline` to set the other prompt components. The new text lasts until the next prompt is drawn.
`commandline set-prompt` sets the left prompt by default. Use `--right`, `--indicator`, `--vi-insert`, `--vi-normal`, `--vi-visual`, or `--multiline` to set the other prompt components. The new text lasts until the next prompt is drawn.

A job started from a prompt closure, or from a `pre_prompt` or `env_change` [hook](./hooks.md), can finish before the prompt is drawn, for example when `git` answers quickly. Its `commandline set-prompt` still shows on that prompt. The same is true when a hook or prompt closure calls `commandline set-prompt` directly: the pushed text replaces what the prompt variable gives that segment.
A job started from a prompt closure, or from a `pre_prompt` or `env_change` [hook](./hooks.md), can finish before the prompt is drawn, for example when `git` answers quickly. Its `commandline set-prompt` still shows on that prompt. The same is true when a hook or prompt closure calls `commandline set-prompt` directly: the pushed text replaces what the prompt configuration gives that segment.

### ENV_CONVERSIONS

Expand Down
2 changes: 1 addition & 1 deletion book/environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ $env | table -e
# => ╰──────────────────────┴───────────────────────────────────────────────────────────────────────────╯
```

In Nushell, environment variables can be any value and have any type. You can see the type of an env variable with the describe command, for example: `$env.PROMPT_COMMAND | describe`.
In Nushell, environment variables can be any value and have any type. You can see the type of an env variable with the describe command, for example: `$env.PATH | describe`.

To send environment variables to external applications, the values will need to be converted to strings. See [Environment variable conversions](#environment-variable-conversions) on how this works.

Expand Down
2 changes: 1 addition & 1 deletion book/line_editor.md
Original file line number Diff line number Diff line change
Expand Up @@ -405,7 +405,7 @@ Changes:

<kbd>d</kbd>, <kbd>y</kbd> and <kbd>p</kbd> return to normal mode, and <kbd>c</kbd> switches to insert mode. These Helix keys are not available yet: <kbd>;</kbd>, <kbd>,</kbd>, <kbd>J</kbd>, <kbd>G</kbd>, <kbd>X</kbd>, <kbd>&gt;</kbd>, <kbd>&lt;</kbd>, the <kbd>/</kbd>, <kbd>n</kbd> and <kbd>N</kbd> search commands, match mode (<kbd>m</kbd>), and the multi-cursor commands.

Keybindings for Helix mode use the `helix_normal`, `helix_select` and `helix_insert` mode names. The prompt uses `PROMPT_INDICATOR_VI_INSERT` in Helix insert mode, and `PROMPT_INDICATOR_VI_NORMAL` in normal and select mode.
Keybindings for Helix mode use the `helix_normal`, `helix_select` and `helix_insert` mode names. The prompt uses `$env.config.prompt.vi_insert` in Helix insert mode, `$env.config.prompt.vi_normal` in normal mode and `$env.config.prompt.vi_visual` in select mode.

::: tip
The selection in Vi visual mode and Helix mode is styled with `$env.config.color_config.selection` (reverse video by default). `$env.config.color_config.selection_cursor` styles the character under the cursor inside a selection:
Expand Down
Loading