Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/artemave/tmux_super_fingers
A Tmux plugin to open file links from the terminal in vim
https://github.com/artemave/tmux_super_fingers
tmux tmux-plugin vim
Last synced: 9 days ago
JSON representation
A Tmux plugin to open file links from the terminal in vim
- Host: GitHub
- URL: https://github.com/artemave/tmux_super_fingers
- Owner: artemave
- License: mit
- Created: 2021-05-16T21:12:44.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-02T08:17:37.000Z (2 months ago)
- Last Synced: 2024-10-13T07:07:14.305Z (23 days ago)
- Topics: tmux, tmux-plugin, vim
- Language: Python
- Homepage:
- Size: 212 KB
- Stars: 84
- Watchers: 4
- Forks: 16
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-tmux - tmux-super-fingers
README
# Tmux Super Fingers [](https://github.com/artemave/tmux_super_fingers/actions/workflows/python-app.yml)
A tmux "mode" that allows you to open file links in an `$EDITOR`, urls in the browser and more.
Demo
https://user-images.githubusercontent.com/23721/127735461-e716cca9-c6e4-46b9-97d1-05bc7f84e00c.mp4
## Description
Tmux [fingers](https://github.com/morantron/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](https://github.com/tmux-plugins/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](./tmux_super_fingers/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:
```python3
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](./tmux_super_fingers/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
- [x] generic, configurable/pluggable way to send highlited text to arbitrary action (not just `vim` and `xdg-open`)
- [ ] search marks
- [x] secondary action
- [x] configurable `@super-fingers-key`
- [x] create vim window if there are none in the session
- [x] extract untested code into tested packages
- [x] python stack traces (line numbers)
- [x] handle image files