Mouse scrolling in vim through tmux, how to configure

puttyscrollingtmuxvim

I'm using a combination of PuTTY, tmux and vim. If I just open an SSH connection with PuTTY and then open vim, mouse scrolling works as expected. But if I open tmux and then open vim inside tmux the scrolling only partially works, meaning I can scroll downwards as usual but I'm unable to scroll upwards. If I scroll upwards the buffer just jerks "up and down" and just stays in the same spot. "set -g mode-mouse on" doesn't seem to make a difference (I do reload the conf afterwards with "tmux source-file ~/.tmux.conf"), works the same way either way.

Edit: I also noticed that scrolling works like expected in tmux in terminal but not in vim. Only options related to mouse/terminal I have in vim is "set mouse=a" and "set t_Co=256".

Any ideas?

Best Answer

Summary

The issue clearly starts with PuTTY, but it doesn't necessarily stop there. There is a link to a potential fix for the PuTTY issue below, as well as an analysis of the issue as a whole.

Issue Description

Configuration

vim with mouse=a enabled for scrolling, selection, and cursor movement

tmux, with no tmux mouse functionality enabled, i.e. the following:

set -g mode-mouse off
set -g mouse-select-pane off
set -g mouse-resize-pane off
set -g mouse-select-window off

Use Case

A typical use case is to use vim inside of tmux. Avoiding negative interactions between tmux and vim is one of the primary reasons to disable tmux scrolling.

Behavior

Please note that the following only occurs when using PuTTY as the terminal emulator, and is not reproducible in gnome-terminal or any other tested Linux terminal emulator.

When attempting to 'scroll up' using the mouse in vim inside of a tmux session, the action simply fails. As OP describes, it is often possible to see the buffer jerking 'up and down' as if there is a counter-action taking place with each scroll attempt (more on this below).

This is basically the same as OP's description, but recapped just in case something isn't clear in my explanation or OP's question.

Potential Solution -- PuTTY

There appears to be an issue where PuTTY sends an extraneous ScrollDown event with every ScrollDown/ScrollUp event. This means that each attempt to scroll up gets cancelled out and nothing happens. Conversely, when scrolling down, each scroll event is doubled. The behavior is easy to validate by looking at the vim scrolling behavior first outside of tmux (where scrolling works properly), and second inside of tmux (where scrolling up does not work, and a single attempt to scroll down scrolls twice as much).

According to the following gmane thread, the issue described above is resolved with a patch from Putty-X (https://github.com/atsepkov/putty-X/commit/bbcedf5a85ca1ccaa27005e7f7ebeb4c8a783b88):

Link to gmane thread: http://comments.gmane.org/gmane.comp.terminal-emulators.tmux.user/5498.

NOTE: I haven't validated the above solution myself, so please review the gmane thread for additional information.

Additional Observations

Where it really gets interesting is that this is a new issue not reproducible using older versions of tmux/vim. Using the same version of PuTTY (0.63), the issue can be actively demonstrated on an Ubuntu 13.10 system, while an Ubuntu 12.04 system does not exhibit the issue.

At first, the issue seems to point to a system configuration delta (i.e. missing ncurses-term or similar), but no fix has been identified using this type of solution. Furthermore, the multiple reports of this same issue (including this thread) tend to support the existence of the issue.

Because of the co-dependent nature of the issue and versions of the related software, it seems the issue isn't limited to a single application. It may be that a newer version of tmux/vim 'fixed' something that created a regression. Or, it may be that a newer version of tmux/vim simply exposed the existing issue in PuTTY. Either way, it will require some additional investigation to fully iron out. Please find some pertinent version information below if this can help anyone in their investigation.

Version Information

Ubuntu 12.04 version info ('scrolling up' in vim inside of tmux works):

  • tmux: 1.6-1
  • vim: 7.3.429-2

Ubuntu 13.10 version info ('scrolling up' in vim inside of tmux is broken):

  • tmux: 1.8-4
  • vim: 7.4.000-1

Also of note -- the gmane poster reported not observing the issue on tmux 1.7 + vim 7.3. Poster's first observation of the issue was also with tmux 1.8 + vim 7.4.

Hopefully, at the very least, this answer provides anyone dedicated to (or stuck with) PuTTY an option for working around this issue. Beyond that, hopefully someone can make sense of the additional observations above and help bring the topic to a proper resolution.

Related Question