tmux: Enhance version checking for tmux

tmux configuration has become very fragmented between versions due to a
combination of new features and deprecation of older options. As such,
version checking for tmux became a requirement to allow maximum
functionality along with version-appropriate configuration. However,
wrapping nearly every line with `if-shell` is tedious and becomes
virtually unreadable.

This enhancement to tmux version-checking creates a logical
configuration file structure that reflects the development of tmux. As
additional configurations are added and tmux development continues, this
structure can be leveraged appropriately and extended as needed.

Rather than having multiple `if-shell` checks for the same version, each
version or version group with specific requirements can be checked only
once. This leads to simpler and fewer `if-shell` version checks. It also
reduces the ambiguity introduced by complex `if-shell` commands that
include an 'else' conditional.

A caveat to adding this enhancement is the additional requirement of the
end user to add a tmux variable definition (`POWERLINE_BINDINGS_DIR`) to
his/her `~/.tmux.conf` file. For existing tmux users leveraging
powerline, this may prove to be a slight one-time nuisance immediately
after upgrading. Without this definition, there is no way to determine
the location of the additional tmux powerline config files that have
been added with this enhancement. The docs have also been updated in
this commit to reflect this initial configuration requirement change.
Also added are some additional troubleshooting notes that point to
definition of this variable as a potential issue. Powerline will
continue to work without the definition of `POWERLINE_BINDINGS_DIR`, but
some of the functionality will be reduced and the appearance incomplete
(i.e. colors).

Ultimately, the caveat above is a small price to pay in exchange for a
framework that can be leveraged for proper version-appropriate
configuration of tmux going forward.

docs/source/installation/troubleshooting-common.rst

@@ -9,6 +9,8 @@ I'm using tmux and Powerline looks like crap, what's wrong?
 * If you're using iTerm2, make sure that you have enabled the setting 
   :guilabel:`Set locale variables automatically` in :menuselection:`Profiles 
   --> Terminal --> Environment`.
+* Check to ensure that ``POWERLINE_BINDINGS_DIR`` is properly defined in your
+  ``.tmux.conf`` file as indicated in the :ref:`tmux usage <tmux-statusline>`
 
 I’m using tmux/screen and Powerline is colorless
 ------------------------------------------------
@@ -18,6 +20,10 @@ I’m using tmux/screen and Powerline is colorless
 * Alternative: set :ref:`additional_escapes <config-common-additional_escapes>` 
   to ``"tmux"`` or ``"screen"``. Note that it is known to work perfectly in 
   screen, but in tmux it may produce ugly spaces.
+* For ``tmux``, check to ensure that ``POWERLINE_BINDINGS_DIR`` is properly
+  defined in your ``.tmux.conf`` file as indicated in the :ref:`tmux usage
+  <tmux-statusline>`
+
 
 After an update something stopped working
 -----------------------------------------

docs/source/overview.rst

@@ -164,13 +164,18 @@ is the absolute path to your Powerline installation directory:
    set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
    powerline-setup
 
+.. _tmux-statusline:
+
 Tmux statusline
 ---------------
 
-Add the following line to your :file:`tmux.conf`, where ``{repository_root}`` is 
-the absolute path to your Powerline installation directory::
+Add the following lines to your :file:`.tmux.conf`, where ``{repository_root}``
+is the absolute path to your Powerline installation directory (please note that
+the definition of the ``POWERLINE_BINDINGS_DIR`` variable is required for full
+powerline support)::
 
-   source '{repository_root}/powerline/bindings/tmux/powerline.conf'
+   POWERLINE_BINDINGS_DIR="{repository_root}/powerline/bindings"
+   source "$POWERLINE_BINDINGS_DIR/tmux/powerline.conf"
 
 IPython prompt
 --------------

powerline/bindings/tmux/powerline.conf

@@ -1,27 +1,37 @@
 if-shell 'test -z "$POWERLINE_COMMAND"' 'if-shell "which powerline-client" "set-environment -g POWERLINE_COMMAND powerline-client" "set-environment -g POWERLINE_COMMAND powerline"'
 run-shell "tmux set-environment -g TMUX_VERSION_MAJOR $(tmux -V | cut -d' ' -f2 | cut -d'.' -f1 | sed 's/[^0-9]*//g')"
 run-shell "tmux set-environment -g TMUX_VERSION_MINOR $(tmux -V | cut -d' ' -f2 | cut -d'.' -f2 | sed 's/[^0-9]*//g')"
+
+# Don't version-check for this core functionality -- anything too old to
+# support these options likely won't work well with powerline
 set -g status on
 set -g status-utf8 on
 set -g status-interval 2
-set -g status-fg colour231
-set -g status-bg colour234
 set -g status-left-length 20
-# Version check for 'client_prefix' format functionality
-if-shell '[ $TMUX_VERSION_MAJOR -gt 1 -o \( $TMUX_VERSION_MAJOR -eq 1 -a $TMUX_VERSION_MINOR -ge 8 \) ]' \
-  "set -g status-left '#{?client_prefix,#[fg=colour254]#[bg=colour31]#[bold],#[fg=colour16]#[bg=colour254]#[bold]} #S #{?client_prefix,#[fg=colour31]#[bg=colour234]#[nobold],#[fg=colour254]#[bg=colour234]#[nobold]}#(eval $POWERLINE_COMMAND tmux left)'" \
-  "set -g status-left '#[fg=colour16,bg=colour254,bold] #S #[fg=colour254,bg=colour234,nobold]#(eval $POWERLINE_COMMAND tmux left)'"
 set -g status-right '#(eval $POWERLINE_COMMAND tmux right -R pane_id=`tmux display -p "#D"`)'
 set -g status-right-length 150
 set -g window-status-format "#[fg=colour244,bg=colour234]#I #[fg=colour240] #[default]#W "
 set -g window-status-current-format "#[fg=colour234,bg=colour31]#[fg=colour117,bg=colour31] #I  #[fg=colour231,bold]#W #[fg=colour31,bg=colour234,nobold]"
-# Version check for window-status-last-style and/or window-status-last-fg functionality
+
+# Legacy status-left definition to be overwritten for tmux Versions 1.8+
+set -g status-left '#[fg=colour16,bg=colour254,bold] #S #[fg=colour254,bg=colour234,nobold]#(eval $POWERLINE_COMMAND tmux left)'
+
+# Simplify tmux version checking by using multiple config files. Source these
+# config files based on the version in which tmux features were added and/or
+# deprecated. By splitting these configuration options into separate files,
+# less 'if-shell' commands are necessary and reading/editing of config files is
+# much easier.
+
+# tmux Version 1.9 adds foo-style options
 if-shell '[ $TMUX_VERSION_MAJOR -gt 1 -o \( $TMUX_VERSION_MAJOR -eq 1 -a $TMUX_VERSION_MINOR -ge 9 \) ]' \
-  "set -g window-status-last-style fg=colour31" \
-  'if-shell "[ $TMUX_VERSION_MAJOR -eq 1 -a $TMUX_VERSION_MINOR -ge 8 ]" "set -g window-status-last-fg colour31"'
-set-window-option -g window-status-fg colour249
-set-window-option -g window-status-activity-attr none
-set-window-option -g window-status-bell-attr none
-set-window-option -g window-status-activity-fg yellow
-set-window-option -g window-status-bell-fg red
+  "source "$POWERLINE_BINDINGS_DIR/tmux/powerline_tmux_1.9_plus.conf""
+# tmux Version 1.8 adds the 'client_prefix' format variable
+if-shell '[ $TMUX_VERSION_MAJOR -gt 1 -o \( $TMUX_VERSION_MAJOR -eq 1 -a $TMUX_VERSION_MINOR -ge 8 \) ]' \
+  "source "$POWERLINE_BINDINGS_DIR/tmux/powerline_tmux_1.8_plus.conf""
+# tmux Version 1.8 adds a legacy window-status-last-{attr,bg,fg} option
+if-shell '[ $TMUX_VERSION_MAJOR -eq 1 -a $TMUX_VERSION_MINOR -eq 8 ]' \
+  "source "$POWERLINE_BINDINGS_DIR/tmux/powerline_tmux_1.8.conf""
+# tmux Versions 1.8 and earlier use the legacy foo-{attr,bg,fg} options
+if-shell '[ $TMUX_VERSION_MAJOR -eq 1 -a $TMUX_VERSION_MINOR -le 8 ]' \
+  "source "$POWERLINE_BINDINGS_DIR/tmux/powerline_tmux_legacy_common.conf""
 # vim: ft=tmux

powerline/bindings/tmux/powerline_tmux_1.8.conf

@@ -0,0 +1,5 @@
+# powerline_tmux_1.8.conf
+# tmux Version 1.8 introduces window-status-last-{attr,bg,fg}, which is
+# deprecated for versions 1.9+, thus only applicable to version 1.8.
+set -g window-status-last-fg colour31
+# vim: ft=tmux

powerline/bindings/tmux/powerline_tmux_1.8_plus.conf

@@ -0,0 +1,5 @@
+# powerline_tmux_1.8_plus.conf
+# tmux Version 1.8 introduces the 'client_prefix' format variable, applicable
+# for versions 1.8+
+set -g status-left '#{?client_prefix,#[fg=colour254]#[bg=colour31]#[bold],#[fg=colour16]#[bg=colour254]#[bold]} #S #{?client_prefix,#[fg=colour31]#[bg=colour234]#[nobold],#[fg=colour254]#[bg=colour234]#[nobold]}#(eval $POWERLINE_COMMAND tmux left)'
+# vim: ft=tmux

powerline/bindings/tmux/powerline_tmux_1.9_plus.conf

@@ -0,0 +1,8 @@
+# powerline_tmux_1.9_plus.conf
+# Version 1.9 introduces the foo-style options, applicable to version 1.9+
+set -g status-style fg=colour231,bg=colour234
+set -g window-status-last-style fg=colour31
+set-window-option -g window-status-style fg=colour249
+set-window-option -g window-status-activity-style fg=yellow,none
+set-window-option -g window-status-bell-style fg=red,none
+# vim: ft=tmux

powerline/bindings/tmux/powerline_tmux_legacy_common.conf

@@ -0,0 +1,11 @@
+# powerline_tmux_legacy_common.conf
+# tmux Version 1.8 and earlier (legacy) common options. The foo-{attr,bg,fg}
+# options are deprecated starting with tmux Version 1.9.
+set -g status-fg colour231
+set -g status-bg colour234
+set-window-option -g window-status-fg colour249
+set-window-option -g window-status-activity-attr none
+set-window-option -g window-status-bell-attr none
+set-window-option -g window-status-activity-fg yellow
+set-window-option -g window-status-bell-fg red
+# vim: ft=tmux