tmux-fingers

tmux-fingers: copy pasting with vimium/vimperator like hints.

Usage

Press ( prefix + F ) to enter [fingers] mode, it will highlight relevant stuff in the current pane along with letter hints. By pressing those letters, the highlighted match will be copied to the clipboard. Less keystrokes == profit!

Here is a list of the stuff highlighted by default.

• File paths
• SHAs
• numbers ( 4+ digits )
• hex numbers
• IP addresses
• kubernetes resources
• UUIDs

It also works on copy mode, but requires tmux 2.2 or newer to properly take the scroll position into account.

Key shortcuts

While in [fingers] mode, you can use the following shortcuts:

• a-z: copies selected match to the clipboard
• CTRL + a-z: copies selected match to the clipboard and triggers @fingers-ctrl-action. By default it triggers :open: action, which is useful for opening links in the browser for example.
• SHIFT + a-z: copies selected match to the clipboard and triggers @fingers-shift-action. By default it triggers :paste: action, which automatically pastes selected matches.
• ALT + a-z: copies selected match to the clipboard and triggers @fingers-alt-action. There is no default, configurable by the user.
• TAB: toggle multi mode. First press enters multi mode, which allows to select multiple matches. Second press will exit with the selected matches copied to the clipboard.
• SPACE: toggle compact hints ( see @fingers-compact-hints ).
• CTRL + c: exit [fingers] mode
• ESC: exit help or [fingers] mode
• ?: show help.

Requirements

• tmux 2.1+ ( 2.8 recommended )
• bash 4+
• gawk

Installation

Using Tmux Plugin Manager

Add the following to your list of TPM plugins in .tmux.conf:

set -g @plugin 'Morantron/tmux-fingers'

Hit prefix + I to fetch and source the plugin. You should now be able to use the plugin!

Manual

Clone the repo:

# Use --recursive flag to also fetch submodules
➜ git clone --recursive https://github.com/Morantron/tmux-fingers ~/.tmux/plugins/tmux-fingers

Source it in your .tmux.conf:

run-shell ~/.tmux/plugins/tmux-fingers/tmux-fingers.tmux

Reload TMUX conf by running:

➜ tmux source-file ~/.tmux.conf

Configuration

NOTE: for changes to take effect, you'll need to source again your .tmux.conf file.

• @fingers-key
• @fingers-patterns-N
• @fingers-main-action
• @fingers-ctrl-action
• @fingers-alt-action
• @fingers-shift-action
• @fingers-compact-hints
• @fingers-hint-position
• @fingers-hint-position-nocompact
• @fingers-hint-format
• @fingers-hint-format-nocompact
• @fingers-highlight-format
• @fingers-highlight-format-nocompact
• @fingers-selected-hint-format
• @fingers-selected-hint-format-nocompact
• @fingers-selected-highlight-format
• @fingers-selected-highlight-format-nocompact
• deprecated: @fingers-copy-command
• deprecated: @fingers-copy-command-uppercase

@fingers-key

default: F

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

For example:

set -g @fingers-key F

@fingers-patterns-N

You can also add additional patterns if you want more stuff to be highlighted:

set -g @fingers-pattern-0 'git rebase --(abort|continue)'
set -g @fingers-pattern-1 'yolo'
.
.
.
set -g @fingers-pattern-50 'whatever'

Patterns are case insensitive, and grep's extended syntax ( ERE ) should be used. Patterns matching the empty string are disallowed. man grep for more info.

If the introduced regexp contains an error, an error will be shown when invoking the plugin.

@fingers-main-action

default: :copy:

By default tmux-fingers will copy matches in tmux and system clipboard.

If you still want to set your own custom command you can do so like this:

set -g @fingers-main-action '<your command here>'

This command will also receive the following:

• MODIFIER: environment variable set to ctrl, alt, or shift specififying which modifier was used when selecting the match.
• HINT: environment variable the selected letter hint itself ( ex: q, as, etc... ).
• stdin: copied text will be piped to @fingers-copy-command.

You can also use the following special values:

• :paste: Copy the the match and paste it automatically.
• :copy: Uses built-in system clipboard integration to copy the match.
• :open: Uses built-in open file integration to open the file ( opens URLs in default browser, files in OS file navigator, etc ).

@fingers-ctrl-action

default: :open:

Same as @fingers-main-action but only called when match is selected by holding ctrl

This option requires tmux 2.8 or higher.

@fingers-alt-action

Same as @fingers-main-action but only called when match is selected by holding alt

This option requires tmux 2.8 or higher.

@fingers-shift-action

default: :paste:

Same as @fingers-main-action but only called when match is selected by holding shift

@fingers-copy-command

DEPRECATED: this option is deprecated, please use @fingers-main-action instead

@fingers-copy-command-uppercase

DEPRECATED: this option is deprecated, please use @fingers-shift-action instead

@fingers-compact-hints

default: 1

By default tmux-fingers will show hints in a compact format. For example:

/path/to/foo/bar/lol

with @fingers-compact-hints set to 1:

awath/to/foo/bar/lol

with @fingers-compact-hints set to 0:

/path/to/foo/bar/lol [aw]

( pressing aw would copy /path/to/foo/bar/lol )

While in [fingers] mode you can press SPACE to toggle compact mode on/off.

Compact mode is preferred because it preserves the length of lines and doesn't cause line wraps, making it easier to follow.

However for small hints this can be troublesome: a path as small as /a/b would have half of its original content concealed. If that's the case you can quickly toggle off compact mode by pressing SPACE.

@fingers-hint-position

default: "left"

Control the position where the hint is rendered. Possible values are "left" and "right".

@fingers-hint-position-nocompact

default: "right"

Same as above, used when @fingers-compact-hints is set to 0.

@fingers-hint-format

default: "#[fg=yellow,bold]%s"

You can customize the colors using the same syntax used in .tmux.conf for styling the status bar. You'll need to include the %s placeholder in your custom format, that's where the content will be rendered.

Check all supported features here.

@fingers-hint-format-nocompact

default: "#[fg=yellow,bold][%s]"

Same as above, used when @fingers-compact-hints is set to 0.

@fingers-highlight-format

default: "#[fg=yellow,nobold,dim]%s"

Custom format for the highlighted match. See @fingers-hint-format for more details.

@fingers-highlight-format-nocompact

default: "#[fg=yellow,nobold,dim]%s"

Same as above, used when @fingers-compact-hints is set to 0.

@fingers-selected-hint-format

default: "#[fg=green,green]%s"

Format for hints in selected matches in multimode.

@fingers-selected-hint-format-nocompact

default: "#[fg=green,bold][%s]"

Same as above, used when @fingers-compact-hints is set to 0.

@fingers-selected-highlight-format

default: "#[fg=green,nobold,dim]%s"

Format for selected matches in multimode.

@fingers-selected-hint-format-nocompact

default: "#[fg=green,nobold,dim][%s]"

Same as above, used when @fingers-compact-hints is set to 0.

@fingers-keyboard-layout

default: "qwerty"

Hints are generated taking optimal finger movement into account. You can choose between the following:

• qwerty: the default, use all letters
• qwerty-left-hand: only use letters easily reachable with left hand
• qwerty-right-hand: only use letters easily reachable with right hand
• qwerty-homerow: only use letters in the homerow
• qwertz
• qwertz-left-hand
• qwertz-right-hand
• qwertz-homerow
• azerty
• azerty-left-hand
• azerty-right-hand
• azerty-homerow
• colemak
• colemak-left-hand
• colemak-right-hand
• colemak-homerow
• dvorak
• dvorak-left-hand
• dvorak-right-hand
• dvorak-homerow

Troubleshooting

If you encounter any problems you can run the following command to automatically detect common problems:

$ /path/to/tmux-fingers/scripts/health-check.sh

More info in health-check.md

Acknowledgements and inspiration

This plugin is heavily inspired by tmux-copycat ( tmux-fingers predefined search are copycatted from tmux-copycat ).

Kudos to bruno- for paving the way to tmux plugins! 👏 👏

License

MIT