Shell Integration

With shell integration, the command shell running within a terminal reports the username, hostname, current directory, and job information to termy-server via certain escape sequences. This enables a variety of useful features within qtermy and installing it is highly recommended.

termy-server implements the same shell integration escape sequences as the popular iTerm2 terminal emulator. The shell integration scripts provided by that project are compatible with TermySequence.

Installation

If you installed TermySequence via your distribution's package manager, check if shell integration is already installed (see Verification below). Otherwise, follow the instructions at iTerm2 shell integration to install shell integration for your shell. See Notes below for shell-specific notes and configuration options.

When using bash, make sure not to clobber the PROMPT_COMMAND environment variable after the shell integration script has been loaded. See Notes below.

termy-server defines the environment variable TERMYSEQUENCE within its terminals. Within login scripts, check for this variable before loading or sourcing the shell integration script. This will ensure that it doesn't get loaded by other terminal emulators which might not support the escape sequences. The shell integration scripts distributed with TermySequence do check for this variable.

Note

Thanks to the iTerm2 project for providing permission to distribute shell integration scripts with TermySequence.

Verification

To verify that shell integration is active, open the Terminal Information window using Terminal→View Terminal Information or by clicking the terminal size in the status bar. Check the "Shell Integration Version" property on the Terminal Properties tab as shown in the nearby figure. If it is blank, shell integration is not active.

Picture of Terminal Information window showing shell integration properties on the Terminal Properties tab.

Verifying shell integration in the Terminal Information window.

Notes

Shell-specific notes:

bash

The PROMPT_COMMAND environment variable is used to implement bash shell integration. When the shell integration script is sourced, any existing prompt command will be preserved and run as normal. This means that PROMPT_COMMAND should be set before the shell integration script is sourced, not afterward.

This presents a problem when using the /etc/profile.d/termy_shell_integration.sh distributed with TermySequence, because /etc/profile is sourced before user login scripts have a chance to run. To set a custom PROMPT_COMMAND in this scenario, create the file $HOME/.termy_bash_prompt and set the prompt command from there. The shell integration script sources this file before setting up shell integration. Refer to the top of the script for the implementation details.