XYZHOU.com
Back to the archive

From the archive

Enable mouse scrolling with tmux 2.1 on Mac

Xinyun Zhou 2 min read Archived

tl;dr

I finally found the solution to automatically enable and disable scrolling on Mac after the tmux upgrade. Thanks again to Arch Linux 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 an explanation: most of them have only the solution but not why it works. 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 events 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 prefixed one.
  • WheelUpPane and WheelDownPane keep the event on the pane the mouse is scrolled on.
  • if-shell -F -t = helps to create an if decision. -F expands the condition section "#{alternate_on}", and -t means run in the current (target) pane.
  • alternate_on checks if the pane is in the 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 have ever used VIM. If you have this option on, then when you exit VIM you will still see all the text that 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 scrolling, 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”.