Tmux Super Fingers

A tmux "mode" that allows you to open file links in an $EDITOR, urls in the browser and more.

Demo

super_fingers_demo2.mp4

Description

Tmux fingers plugin introduced the "fingers" mode, where particularly looking chunks of text (e.g. file paths) are highlighted and assigned a character "mark". When user hits the mark key, the highlighted text gets copied to clipboard.

Super Fingers builds upon this idea. Notably:

• it opens files in a terminal $EDITOR* running elsewhere within the same tmux session**
• only files paths that actually exist are highlighted
• it opens files at line number
• text that isn't a file path, but maps onto one (e.g. UsersController#show in rails log or +++ b/app/models/user.rb in a diff) is also highlighted
• different types of marks are actioned differently: text files are sent to editor, urls and image files - to OS open.***
• works across all panes in a window
• can be invoked while scrolling up
• handles multiline marks (wrapping)

* currently this behavior only works for (n)vim - everything else is sent to OS open.
** if no running terminal $EDITOR is found in the session, plugin attempts to start one in a new window.
*** code is designed in such a way that it should be easy to add new types of marks/actions.

Secondary action

When in fingers mode, pressing space toggles "secondary" mode. In this mode, mark is copied to clipboard.

Install

Requires Python >= 3.9.

Using TPM:

set -ga update-environment EDITOR
set -g @plugin 'artemave/tmux_super_fingers'

Hit prefix + I to fetch and source the plugin.

Manual

Clone the repo:

git clone https://github.com/artemave/tmux_super_fingers.git ~/.tmux/plugins/tmux_super_fingers

Source it in your .tmux.conf:

set -ga update-environment EDITOR
run-shell ~/.tmux/plugins/tmux_super_fingers/tmux_super_fingers.tmux

Reload TMUX conf by running:

tmux source-file ~/.tmux.conf

Configuration

@super-fingers-key

Customize how to enter fingers mode. Always preceded by prefix: prefix + @super-fingers-key. Defaults to f.

set -g @super-fingers-key f

Custom actions

Requires writing some python code.

There are different types of mark targets (e.g. text file target, url target). Each target type has a primary and a secondary action. You can supply a python file that changes default actions for target types.

For example, the following code changes primary action to open files in vscode and secondary action to send them to vim:

import os
from .targets.file_target import FileTarget
from .actions.send_to_vim_in_tmux_pane_action import SendToVimInTmuxPaneAction
from .actions.action import Action
from .targets.target_payload import EditorOpenable


class SendToVsCodeAction(Action):
    def __init__(self, target_payload: EditorOpenable):
        self.target_payload = target_payload

    def perform(self):
        path = self.target_payload.file_path

        if self.target_payload.line_number:
            path += f':{self.target_payload.line_number}'

        os.system(f'code -g {path}')


FileTarget.primary_action = SendToVsCodeAction
FileTarget.secondary_action = SendToVimInTmuxPaneAction

You can also define new action types. See existing actions for details.

Now let's plug it in:

set -g @super-fingers-extend /path/to/the/above/code.py

Troubleshooting

Check /tmp/tmux_super_fingers_error.txt for errors:

tail -F /tmp/tmux_super_fingers_error.txt

Text files are not opened in vim/nvim but in a different editor

Please make sure your EDITOR env is set, and it's exclusively is set to vim or nvim (i.e. EDITOR=/my/custom/path/nvim will not work)

Development

Prerequisites: python3, pipenv, node, make

git clone https://github.com/artemave/tmux_super_fingers.git
cd tmux_super_fingers
pipenv install --dev
npm install

Run checks and tests:

make

TODO

• generic, configurable/pluggable way to send highlited text to arbitrary action (not just vim and xdg-open)
• search marks
• secondary action
• configurable @super-fingers-key
• create vim window if there are none in the session
• extract untested code into tested packages
• python stack traces (line numbers)
• handle image files