Enable mouse scrolling with tmux 2.1 on Mac

Monday, Jan 18, 2016

tl;dr

I finally found the solution to automatically enable and disable scrolling on Mac after the tmux upgrade. Thanks again to ArchLinux Wiki.

Add those three lines to your .tmux.conf:

set -g mouse on
bind-key -T root WheelUpPane   if-shell -F -t = "#{alternate_on}" "send-keys -M" "select-pane -t =; copy-mode -e; send-keys -M"
bind-key -T root WheelDownPane if-shell -F -t = "#{alternate_on}" "send-keys -M" "select-pane -t =; send-keys -M"

Understand how it works

One thing I found missing on a lot of tech blogs is most of them have only the solution but not why it’s the case. I think we should change this so that everyone can make changes/improvements to meet their needs.

The main thing here is a bind-key command, so let’s check the manual first.

Official manual page on OpenBSD

To understand the command:

• set -g mouse on enables mouse event globally.
• bind-key gives you the ability to bind a key combination to do something.
• -T root allows you to bind a “plain” key combination instead of a pre-fixed one.
• WheelUpPane and WheelDownPane keep the event on the pane the mouse is scrolled on.
• if-shell -F -t = helps to create a if decision. -F expands the condition section "#{alternate_on}", and -t means run in the current (target) pane.
• alternate_on checks if pane is in alternate screen. According to the manual, “The alternate screen feature preserves the contents of the window when an interactive application starts and restores it on exit, so that any output visible before the application starts reappears unchanged after it exits. This is easy to understand if you ever use VIM, if you have this option on, then when you exit VIM you will still see all the text appeared in VIM instead of a cleaned-up terminal.
• "send-keys -M" just passes the mouse event on to the next step.
• "select-pane -t =; copy-mode -e; send-keys -M" is easier to understand. -t = means when scroll, the action should start on the current pane only. copy-mode -e “specifies that scrolling to the bottom of the history (to the visible screen) should exit copy mode”.