Tmux Super Fingers

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

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

Pressing space toggles "secondary" mode. In this mode, mark is copied to clipboard.

Install

Requires Python >= 3.9.

Using TPM:

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:

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

Development

Prerequisites: python3, pipenv, node, make

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

Run checks and tests:

make

Gotchas

The plugin relies on EDITOR variable being set. However, it has been observed that under some circumstances (I can't figure out what they are) tmux does not inherit environment when it starts and so the plugin code runs, EDITOR is missing and nothing works. Running tmux set-environment -g EDITOR $EDITOR later fixes it, but I can't figure out how to automate this.

One (untested) workaround could be to alias tmux like this:

alias tmux="tmux && tmux set-environment -g EDITOR $EDITOR"

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