Shell Integration
Nash can follow what your shell does, if the shell tells it. With shell integration, your shell sends small escape sequences to Nash: the directory it is in, where each prompt and each command output starts and ends, and the command that it is about to run.
Nash needs no shell integration to work. Without it, Nash still runs your shell and still reads the working directory of a local shell from the shell process. With it, you get more reliable directories, command state in saved sessions, and more.
What the shell sends
| Sequence | What it tells Nash |
|---|---|
OSC 7 | The current working directory. |
OSC 133 | Where each prompt, input, and command output starts and ends (semantic zones), and when a command starts and finishes. |
OSC 1337 SetUserVar | Values that belong to the pane, called user vars. |
OSC means Operating System Command. These sequences are not specific to
Nash, and many terminals ignore the ones that they do not know.
The integration script sets these user vars:
| User var | Value |
|---|---|
NASH_PROG | The command line that the shell is about to run. The script clears it at the next prompt. |
NASH_USER | The output of id -un, the current user name. |
NASH_HOST | The host name, or the value of NASH_HOSTNAME if you set it. |
NASH_IN_TMUX | 1 if the shell runs inside tmux, 0 if not. |
Install it for zsh or bash
The script that Nash ships, nash.sh, works with zsh and bash. It does
nothing in a shell that is not interactive, and it does nothing when TERM is
dumb or linux. It needs the base64 program for the user vars.
The macOS app bundle contains the script at
Nash.app/Contents/Resources/nash.sh. Source it from your shell startup file,
~/.zshrc or ~/.bashrc. Change the path if Nash is not in /Applications:
if [ -r /Applications/Nash.app/Contents/Resources/nash.sh ]; then . /Applications/Nash.app/Contents/Resources/nash.sh fi
Open a new shell in Nash after you change the file.
For another shell, make the shell print the same sequences. For example, this tells Nash the directory:
printf '\033]7;file://%s%s\033\\' "$HOSTNAME" "$PWD"
Turn parts off
Set one of these variables, before the script runs, to turn a part of the integration off:
| Variable | What it turns off |
|---|---|
NASH_SHELL_SKIP_ALL=1 | The whole script. |
NASH_SHELL_SKIP_SEMANTIC_ZONES | The OSC 133 prompt and output zones. |
NASH_SHELL_SKIP_CWD | The OSC 7 working directory. |
NASH_SHELL_SKIP_USER_VARS | The user vars, including NASH_PROG. |
Set the last three to any non-empty value.
What Nash does with it
Working directory. A new tab or pane starts in the working directory of the
pane that you opened it from, if both use the same domain. Nash uses the
directory that the shell reported with OSC 7. If the shell did not report one,
Nash tries to read the directory from the shell process of a local pane. The
script reports the directory with nash set-working-directory, and falls back
to a plain printf if that command fails. The directory also shows in the smart
title of the tab (see Tabs), in
the tab search list, and in the title of a folded pane (see
Pane Folding).
Command state in saved sessions. When Nash saves a session, it records the
last command of each pane. It takes the command from NASH_PROG. Nash keeps the
last non-empty command, because the script clears NASH_PROG at the next
prompt. Nash also records whether that command is still running. It uses the
OSC 133 markers for this. Nash treats both values as best-effort
information, and a pane without shell integration has neither. See
Session Restore.
Semantic zones. Because the shell marks prompts and outputs, Nash can work
with them. For example, the ScrollToPrompt action scrolls to the previous or
the next prompt. Nash binds no key to it by default.
Your own scripts. A user var change raises a user-var-changed event in the
window of the pane. You can read all user vars of a pane with
pane:get_user_vars() in Lua. The script defines the shell function
__nash_set_user_var NAME VALUE, which you can call to set your own user vars.
Bundled tools on macOS
Since Nash 0.5.3, the macOS app adds its Contents/MacOS executable
directory to the PATH inherited by processes it starts. You can run nash and
the other bundled tools inside a pane without adding that directory to your
shell profile. The directory goes last, so a separately installed copy
earlier in your PATH still wins. This does not change the PATH of terminals
outside Nash or replace sourcing nash.sh for shell integration.
Use it with tmux
User vars pass through tmux only if you allow it. Add this line to your
tmux.conf:
set -g allow-passthrough on
Inside tmux, NASH_IN_TMUX is 1. The script wraps its user var sequences for
tmux.