How to create version-aware tmux configuration using if-shell with Perl to handle different tmux versions.

The Problem

Different versions of tmux have different configuration options and syntax. When working across multiple systems with varying tmux versions, your configuration file might break or produce warnings.

The Solution

Use tmux’s if-shell command combined with Perl to create version-specific configurations:

if-shell "perl -e 'exit 0 if qx/tmux -V/ =~ /^tmux (\d+\.\d*).*$/ and $1 < 2.1 or exit 1'" \
"tmux set -g utf8"

How It Works

Breaking Down the Command

  1. if-shell: tmux command for conditional execution
  2. perl -e '...': Inline Perl script for version checking
  3. qx/tmux -V/: Executes tmux -V and captures output
  4. Regex matching: /^tmux (\d+\.\d*).*$/ extracts version number
  5. Version comparison: $1 < 2.1 checks if version is less than 2.1
  6. Exit codes: 0 for true condition, 1 for false

The Logic

  • If tmux version is less than 2.1, execute the command
  • In this example, UTF-8 settings are only applied to older versions
  • Newer tmux versions handle UTF-8 automatically

Usage Examples

For Different Version Ranges

# For tmux versions 2.1 and later
if-shell "perl -e 'exit 1 if qx/tmux -V/ =~ /^tmux (\d+\.\d*).*$/ and $1 < 2.1 or exit 0'" \
"set -g mouse on"

# For very old versions (pre-2.0)
if-shell "perl -e 'exit 0 if qx/tmux -V/ =~ /^tmux (\d+\.\d*).*$/ and $1 < 2.0 or exit 1'" \
"set -g mode-mouse on"

Alternative Version Checking

You can also use shell commands:

if-shell '[ $(echo "$(tmux -V | cut -d" " -f2) < 2.1" | bc) -eq 1 ]' \
'set -g utf8 on'

Benefits

  • Cross-compatibility: Same config works across different tmux versions
  • No warnings: Prevents deprecated option warnings
  • Maintainable: Easy to update when dropping support for old versions
  • Flexible: Can handle complex version logic

Common Version-Specific Options

# Mouse support (changed in 2.1)
if-shell "perl -e 'exit 0 if qx/tmux -V/ =~ /^tmux (\d+\.\d*).*$/ and $1 < 2.1 or exit 1'" \
"set -g mode-mouse on; set -g mouse-resize-pane on; set -g mouse-select-pane on; set -g mouse-select-window on" \
"set -g mouse on"

# UTF-8 settings (deprecated in 2.2)
if-shell "perl -e 'exit 0 if qx/tmux -V/ =~ /^tmux (\d+\.\d*).*$/ and $1 < 2.2 or exit 1'" \
"set -g utf8 on; set -g status-utf8 on"

This approach ensures your tmux configuration remains robust across different environments and tmux versions.