Ultimate solution to enable seamless mouse scroll in tmux.
When no process running, it will scroll over the pane content. Otherwise, depending on process name, it will pass ↑ / ↓ or Page Up / Page Down keys or pass-through mouse scroll events as is.
- Works in scenarios like
$ git log,$ find | less, etc. - Works in other applications like
fzf,mc,man,ranger,vim, etc. - Works with nested environments like
chroot. - Starts copy-mode automatically when no process running.
Does not work in panes with open remote connection, since there is no way to
relay back to tmux which processes are running in remote shell.
See @mighty-scroll-fallback-mode.
- Mouse mode enabled (
set -g mouse on). - C compiler (Linux only. Optional, but highly recommended).
Installation with Tmux Plugin Manager (recommended)
Add the plugin to the list of TPM plugins in .tmux.conf:
set -g @plugin 'noscript/tmux-mighty-scroll'
Hit prefix + I to fetch the plugin and source it.
Clone the repo:
$ git clone https://github.com/noscript/tmux-mighty-scroll ~/clone/path
Add this line to the bottom of .tmux.conf:
run '~/clone/path/mighty-scroll.tmux'
Reload tmux environment:
$ tmux source ~/.tmux.conf
| Option | Default value | Supported values | Description |
|---|---|---|---|
@mighty-scroll-interval |
2 |
Number | How many lines to scroll in by-line and history modes. |
@mighty-scroll-select-pane |
on |
on, off |
If enabled, the pane being scrolled becomes automatically selected. |
@mighty-scroll-by-line |
'man less pager fzf' |
List | Space separated list of processes that will be scrolled by line. |
@mighty-scroll-by-page |
'irssi vi' |
List | Space separated list of processes that will be scrolled by page. |
@mighty-scroll-pass-through |
'vim nvim' |
List | Space separated list of processes that will receive mouse scroll events as is. |
@mighty-scroll-fallback-mode |
'history' |
'history', 'by-line', 'by-page', 'pass-through' |
Scroll mode when in alternate screen but the process didn't match the lists from above. |
@mighty-scroll-show-indicator |
off |
on, off |
If enabled, shows the position indicator in the top right with the current position and the number of lines in the history. |
Scrolling modes:
history- enter copy mode and scroll over the pane content by line.by-line- scroll by line, the running process will receive ↑ / ↓ keys.by-page- scroll by page, the running process will receive Page Up / Page Down keys.pass-though- the running process will receive mouse scroll events as is.
Example configuration:
set -g mouse on
set -g @mighty-scroll-interval 3
set -g @mighty-scroll-by-line 'man fzf'
set -g @mighty-scroll-select-pane off
On Linux, make sure to have a C compiler (gcc, clang) available (check with
$ cc -v), otherwise a Shell implementation of the process checker will be
used, which is about 400% slower!
On macOS there is only a Shell implementation of the process checker at the moment.