Home

Awesome

tmuxist

Tmux configuration to use local and remote sessions nested. It is possible to disable the local prefix key by pressing F12 to use the prefix key for the remote session.

Disclaimer: This config -> gpakosz/.tmux is a great peace of work. All features contained in this repositories config are contained in the config made by gpakosz. Including fancy animations and many more features useful for local tmux sessions. If that's what you're looking for give that config a try. The main feature of this repositories config that sets the both apart is the remote session awareness.

The configuration and custom functions are mostly selfcontained. Nonetheless the config uses plugins to manage sessions. For more information see the plugins section.

Visuals

<img src="./shots/local_session.png" alt="img" align="right" width="400px"> <img src="./shots/remote_session.png" alt="img" align="right" width="400px">

The top image is a screenshot of tmux with only a local session open.

The lower image is a screenshot of tmux running a local session with a nested remote session.

On the right side of the lower status bar the remote keymap indicator can be seen. This tells you that the local prefix key is deactivated and if pressed is directly picked up by the remote session.

The colors are tweaked to resemble the gruvbox theme.

The different parts of the configuration are explained down below.

Nice to have you. I hope you can use any of this.

<br> <br> <br>

Features

OS Support

Enabled TMUX Features

Custom Features

Remote session awareness

That means that you can use the same config on your remote system and on your local system.

On the left side of status-right left from the sync indicator is an indicator that tells you whether the keymap is turnded on or off. The indicator looks like the following:

Plugins

Custom Keybindings

Default Mode

Copy Mode

Installation

You can simply use the install script to create some symlinks.

cd ~
git clone --recursive https://github.com/chrootzius/.tmuxist.git ~/.tmuxist
./.tmuxist/install.sh

Or you can use fancy gnu stow (which does pretty much the same)

cd ~
git clone --recursive https://github.com/chrootzius/.tmuxist.git ~/.tmuxist
cd .tmuxist/
stow tmux

Then start tmux :)

# General
tmux

# 256 color support
tmux -2

Nix

There is a flake.nix so you can install it using nix / home-manager or run it directly from the repo.

nix run github:oliverwiegers/tmuxist

Needed Packages

For the status bar components to work properly following packages need to be installed:

Configuration

Do not under any circumstances edit .tmux.conf.

To override any settings and functions or add anything to the configuration stick to .tmux.conf.local for changes to apply to local and remote sessions. Either to override existing settings from .tmux.conf or add anything new.

To override any settings and functions or add anything to the configuration that only applies to remote sessions stick to .tmux.conf.local.

Tmux Settings

To ignore changes you make to those files you can make git ignore these files until you revert that change. To do so do the following:

git update-index --skip-worktree tmux/.tmux.conf.local
git update-index --skip-worktree tmux/.tmux.conf.remote

For more information see this stackoverflow post.

Custom Functions

All functions that reside in .tmux.conf can be overwritten. This is especially useful if you use proprietary tools for example in house solutions for connection to remote hosts.

To override a function add a function with the function name added with _override to .tmux.conf.local. For example To override the _hostname function add the function _hostname_override.

In the default hostname / username functions used to display those in the status bar the ssh connections are taken into account. This does of course not work if the command used is not the usual ssh command. So you could override the hostname function like this:

_hostname_override() {
    tty=${1:-}
    hostname="$(ps -t "${tty}" -o user=WIDEOUTPUTFORLONGNAME -o pid= -o ppid= -o command= | awk '((/govm / || /gove /)) {print $6}')"
    if [ -n "${hostname}" ]; then
        printf '%s' "${hostname}"
    else
        tty_stats="$(_tty_stats "${tty}")"
        cmdline="${tty_stats#*:}"
        cmdline="${cmdline#*:}"
        if _is_ssh "${cmdline}";then
            ssh_stats="$(_ssh_stats "${cmdline}")"
            printf '%s' "${ssh_stats##*:}"
        else
            printf '%s' "$(uname -n)"
        fi
    fi
}

The above example takes ssh wrappers named govm and goct to enter VMs and containers into account.

Remote SSH Configuration

In .tmux.conf.remote the SSH_AUTH_SOCK tmux environment variable is set to $HOME/.ssh/ssh_auth_sock. This is needed so tmux uses the same ssh socket every time. Meaning if your ssh connection to the remote target is lost and you reconnect, your ssh agent uses still the right socket and is operational.

For this to work you need to add the following to your ~/.ssh/rc on the remote target.

if test "$SSH_AUTH_SOCK"; then
  ln -sf "$SSH_AUTH_SOCK" ~/.ssh/ssh_auth_sock
fi

Furthermore the ~/.ssh/rc is a shell script. For it to work the first line hast to be:

#!/bin/bash

As long as you do this your ssh connection can break all it wants and you can reconnect every time resulting in a working ssh agent on the remote target.

Testing

docker build -t tmux_test .
docker run -v "${PWD}/:/root" -it tmux_test

Development

In the development folder is a Makefile present. By using make dev the configuration tmux/.tmux.conf will be duplicated into the development folder and split up into two files - the tmux config and the bash code for the custom functions. This makes it possible to tweak the bash code in normal fashion.

git clone --recursive https://github.com/chrootzius/.tmuxist.git ~/.tmuxist
cd ~/.tmuxist/development
make dev