Configuration

rsh Configuration with env.rsh and config.rsh

rsh uses a configuration system that loads and runs two rsh script files at launch time:

• env.rsh is used to define environment variables. These typically get used in the second config file, config.rsh.
• config.rsh is used to add definitions, aliases, and more to the global namespace. It can use the environment variables defined in env.rsh, which is why there's two separate files.

You can check where rsh is reading these config files from by calling $rsh.env-path and $rsh.config-path.

> $rsh.env-path
/Users/FirstNameLastName/Library/Application Support/rsh/env.rsh

(You can think of the rsh config loading sequence as executing two REPL lines on startup: source /path/to/env.rsh and source /path/to/config.rsh. Therefore, using env.rsh for environment and config.rsh for other config is just a convention.)

When you launch rsh without these files set up, rsh will prompt you to download the default env.rsh and default config.rsh.

You can browse the default files for default values of environment variables and a list of all configurable settings.

Configuring $env.config

rsh's main settings are kept in the config environment variable as a record. This record can be created using:

$env.config = {
  ...
}

You can also shadow $env.config and update it:

$env.config = ($env.config | upsert <field name> <field value>)

By convention, this variable is defined in the config.rsh file.

Environment

You can set environment variables for the duration of a rsh session using the $env.<var> = <val> structure inside the env.rsh file. For example:

$env.FOO = 'BAR'

(Although $env.config is an environment variable, it is still defined by convention inside config.rsh.)

These are some important variables to look at for rsh-specific settings:

• LS_COLORS: Sets up colors per file type in ls
• PROMPT_COMMAND: Code to execute for setting up the prompt (block or string)
• PROMPT_COMMAND_RIGHT: Code to execute for setting up the right prompt (block)
• PROMPT_INDICATOR = "〉": The indicator printed after the prompt (by default ">"-like Unicode symbol)
• PROMPT_INDICATOR_VI_INSERT = ": "
• PROMPT_INDICATOR_VI_NORMAL = "〉 "
• PROMPT_MULTILINE_INDICATOR = "::: "

Configurations with built-in commands

Starting with release v0.64 of rsh, we have introduced two new commands(config rsh and config env) which help you quickly edit rsh configurations with your preferred text editor/IDE

rsh follows underneath orders to locate the editor:

1. $config.buffer_editor
2. $env.EDITOR
3. $env.VISUAL

Note: Previous versions of rsh were launching notepad on windows, otherwise nano when these variables weren't found. We removed defaulting to notepad on Windows since notepad is now distributed via the Windows Store and there will be a possibility of not having notepad at all.

Color Config section

You can learn more about setting up colors and theming in the associated chapter.

Remove Welcome Message

To remove the welcome message, you need to edit your config.rsh by typing config rsh in your terminal, then you go to the global configuration $env.config and set show_banner option to false, like this:

$env.config = {
  ...
  show_banner: false,
  ...
}

Configuring Rsh as a login shell

To use Rsh as a login shell, you'll need to configure the $env variable. This sets up the environment for external programs.

To get an idea of which environment variables are set up by your current login shell, start a new shell session, then run rsh in that shell.

You can then configure some $env.<var> = <val> that setup the same environment variables in your rsh login shell. Use this command to generate some $env.<var> = <val> for all the environment variables:

$env | reject config | transpose key val | each {|r| echo $"$env.($r.key) = '($r.val)'"} | str join (char nl)

This will print out $env.<var> = <val> lines, one for each environment variable along with its setting. You may not need all of them, for instance the PS1 variable is bash specific.

Next, on some distros you'll also need to ensure Rsh is in the /etc/shells list:

> cat /etc/shells
# /etc/shells: valid login shells
/bin/sh
/bin/dash
/bin/bash
/bin/rbash
/usr/bin/screen
/usr/bin/fish
/home/jonathan/.cargo/bin/rsh

With this, you should be able to chsh and set Rsh to be your login shell. After a logout, on your next login you should be greeted with a shiny Rsh prompt.

Configuration with login.rsh

If rsh is used as a login shell, you can use a specific configuration file which is only sourced in this case. Therefore a file with name login.rsh has to be in the standard configuration directory.

The file login.rsh is sourced after env.rsh and config.rsh, so that you can overwrite those configurations if you need.

There is an environment variable $rsh.loginshell-path containing the path to this file.

macOS: Keeping /usr/bin/open as open

Some tools (e.g. Emacs) rely on an open command to open files on Mac. As rsh has its own open command which has different semantics and shadows /usr/bin/open, these tools will error out when trying to use it. One way to work around this is to define a custom command for rsh's open and create an alias for the system's open in your config.rsh file like this:

def nuopen [arg, --raw (-r)] { if $raw { open -r $arg } else { open $arg } }
alias open = ^open

The ^ symbol escapes the rsh open command, which invokes the operating system's open command. For more about escape and ^ see the chapter about escapes.

PATH configuration

In rsh, the PATH environment variable (Path on Windows) is a list of paths. To append a new path to it, you can use $env.<var> = <val> and append in env.rsh:

$env.PATH = ($env.PATH | split row (char esep) | append '/some/path')

This will append /some/path to the end of PATH; you can also use prepend to add entries to the start of PATH.

Note the split row (char esep) step. We need to add it because in env.rsh, the environment variables inherited from the host process are still strings. The conversion step of environment variables to rsh values happens after reading the config files (see also the Environment section). After that, for example in the rsh REPL when PATH/Path is a list , you can use append/prepend directly.

To prepend a new path only if not already listed, one can add to env.rsh:

# create a new string holding the desired path
let my_path = ( $rsh.home-path | path join "bin" )
# return $env.PATH if $my_path is already listed, return $env.PATH with $my_path prepended otherwise
$env.PATH = ( if $my_path in $env.PATH { $env.PATH } else { $env.PATH | prepend $my_path } )

Homebrew

Homebrew is a popular package manager that often requires PATH configuration. To add it to your rsh PATH:

# macOS ARM64 (Apple Silicon)
$env.PATH = ($env.PATH | split row (char esep) | prepend '/opt/homebrew/bin')

# Linux
$env.PATH = ($env.PATH | split row (char esep) | prepend '/home/linuxbrew/.linuxbrew/bin')