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 -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 --dev
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

dannysu / tmux_super_fingers