Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
dev
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

tmux-fingers

Build Status

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

yay

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

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. 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 :trollface: from tmux-copycat ).

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

License

MIT

You can’t perform that action at this time.