Pane Title in Tmux

Andrey Lushnikov picture Andrey Lushnikov · Mar 17, 2012 · Viewed 66.5k times · Source

On my local machine I've got 3 node.js instances running simultaneously. Each has it's own pane in a tmux window called "servers". The problem is that it's not that easy to figure out which node is running in which pane, 'cause their logs are similar.

What I need is a title for every pane. As I got, tmux itself doesn't have the feature: it has only titles for windows and not for panes. Launching a separate tmux session inside every pane for every node.js instance looks like an overkill.

So is there some small program that launches a command, wrapping its output with a specified status bar?

Thanks in advance

Answer

Chris Johnsen picture Chris Johnsen · Mar 18, 2012

tmux does support per-pane titles, but it does not provide a per-pane location to display these titles.

You can set a pane’s title with the escape sequence ESC ]2; … ESC \ (e.g. see the section called Names and Titles in the tmux manpage). You could do this from the shell like this:

printf '\033]2;%s\033\\' 'title goes here'

Each pane’s title defaults to the system’s hostname. By default the active pane’s title is displayed on the right side of the tmux status line (the default global value of the session variable status-right is "#22T" %H:%M %d-%b-%y, which shows 22 characters of the pane’s title, the time, and the date).

So, as long as you are satisfied with being able to see the active pane’s title (i.e. willing to switch panes to see the title of an inactive pane), you can get by with the default functionality. Just send the appropriate title-setting escape sequence before starting the main command for each pane.


If you absolutely need a dedicated line to display some per-pane information, then nested tmux sessions may not be as much (unnecessary) “overkill” as you might first think.

In the general case, to provide an inviolate status line on some given terminal, you will need a full terminal (re)emulator that sits between the original terminal and a new terminal (one with one fewer lines). Such (re)emulation is needed to translate control sequences sent to the inner terminal and translate them for the original terminal. For example, to maintain a status line at the bottom of the outer terminal, the command

Move to the last line.

sent to the inner terminal must be become

Move to the next to last line.

when translated for and sent to the outer terminal. Likewise, an LF sent to the inner terminal must become

If the cursor is on the next to last line, then scroll this line and all the lines above it up one line, to provide a clear next-to-last line (protecting the status line on the last line). Otherwise, send an LF.

in the outer terminal.

Programs like tmux and screen are just such terminal re-emulators. Sure, there is a lot of other functionality wrapped around the terminal emulator, but you would need a large chunk of terminal emulation code just to provide a reliable status line.


There is, however, a light-weight solution as long as

  1. your programs (Node.js instances) have limited terminal interactions with the panes in which they are running (i.e. no cursor positioning), and
  2. you do not resize the panes while your programs are running.

Like many terminal emulators, tmux supports a “set scrolling region” terminal control command in its panes. You could use this command to limit the scrolling region to the top (or bottom) N-1 lines of the terminal and write some sort of instance-identifying text into the non-scrolling line.

The restrictions (no cursor movement commands allowed, no resizing) are required because the program that is generating the output (e.g. a Node.js instance) has no idea that scrolling has been limited to a particular region. If the output-generating program happened to move the cursor outside of the scrolling region, then the output might become garbled. Likewise, the terminal emulator probably automatically resets the scrolling region when the terminal is resized (so the “non-scrolling line” will probably end up scrolling away).

I wrote a script that uses tput to generate the appropriate control sequences, write into the non-scrolling line, and run a program after moving the cursor into the scrolling region:

#!/bin/sh

# usage: no_scroll_line top|bottom 'non-scrolling line content' command to run with args
#
#     Set up a non-scrolling line at the top (or the bottom) of the
#     terminal, write the given text into it, then (in the scrolling
#     region) run the given command with its arguments. When the
#     command has finished, pause with a prompt and reset the
#     scrolling region.

get_size() {
    set -- $(stty size)
    LINES=$1
    COLUMNS=$2
}
set_nonscrolling_line() {
    get_size
    case "$1" in
        t|to|top)
            non_scroll_line=0
            first_scrolling_line=1
            scroll_region="1 $(($LINES - 1))"
            ;;
        b|bo|bot|bott|botto|bottom)
            first_scrolling_line=0
            scroll_region="0 $(($LINES - 2))"
            non_scroll_line="$(($LINES - 1))"
            ;;
        *)
            echo 'error: first argument must be "top" or "bottom"'
            exit 1
            ;;
    esac
    clear
    tput csr $scroll_region
    tput cup "$non_scroll_line" 0
    printf %s "$2"
    tput cup "$first_scrolling_line" 0
}
reset_scrolling() {
    get_size
    clear
    tput csr 0 $(($LINES - 1))
}

# Set up the scrolling region and write into the non-scrolling line
set_nonscrolling_line "$1" "$2"
shift 2

# Run something that writes into the scolling region
"$@"
ec=$?

# Reset the scrolling region
printf %s 'Press ENTER to reset scrolling (will clear screen)'
read a_line
reset_scrolling

exit "$ec"

You might use it like this:

tmux split-window '/path/to/no_scroll_line bottom "Node instance foo" node foo.js'
tmux split-window '/path/to/no_scroll_line bottom "Node instance bar" node bar.js'
tmux split-window '/path/to/no_scroll_line bottom "Node instance quux" node quux.js'

The script should also work outside of tmux as long as the terminal supports and publishes its csr and cup terminfo capabilities.