Home

Awesome

tmux-fingers

demo

Usage

Press ( <kbd>prefix</kbd> + <kbd>F</kbd> ) 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.

Checkout list of built-in patterns.

Key shortcuts

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

Requirements

Installation

Using Tmux Plugin Manager

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

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

Hit <kbd>prefix</kbd> + <kbd>I</kbd> to fetch and source the plugin. The first time you run it you'll be presented with a wizard to complete the installation.

Manual

Clone the repo:

$ git clone 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

The first time you run it you'll be presented with a wizard to complete the installation.

Configuration

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

Recipes:

@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-jump-key

default: J

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

In jump mode, the cursor will be placed in the position of the match after the hint is selected.

@fingers-patterns-N

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

# You can define custom patterns like this
set -g @fingers-pattern-0 'git rebase --(abort|continue)'

# Increment the number and define more patterns
set -g @fingers-pattern-1 'some other pattern'

# You can use a named capture group like this (?<match>YOUR-REGEX-HERE)
# to only highlight and copy part of the match.
set -g @fingers-pattern-2 'capture (?<match>only this)'

# Watch out for backslashes! For example the regex \d{50} matches 50 digits.
set -g @fingers-pattern-3 '\d{50}'  # No need to escape if you use single quotes
set -g @fingers-pattern-4 "\\d{50}" # If you use double quotes, you'll need to escape backslashes for special characters to work
set -g @fingers-pattern-5 \\d{50} # Escaping also needed if you don't use any quotes

Patterns use PCRE pattern syntax.

If the introduced regex 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:

You can also use the following special values:

@fingers-ctrl-action

default: :open:

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

@fingers-alt-action

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

@fingers-shift-action

default: :paste:

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

@fingers-hint-style

default: "fg=green,bold

With this option you can define the styles for the letter hints.

You can customize the styles using the same syntax used in .tmux.conf for styling the status bar.

More info in the STYLES section of man tmux.

Supported styles are: bright, bold, dim, underscore, italics.

@fingers-highlight-style

default: "fg=yellow"

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

@fingers-backdrop-style

default: ""

Custom styles for all the text that is not matched. See @fingers-hint-format for more details.

@fingers-selected-hint-style

default: "fg=blue,bold"

Format for hints in selected matches in multimode.

@fingers-selected-highlight-style

default: "fg=blue"

Format for selected matches in multimode.

@fingers-hint-position

default: "left"

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

@fingers-keyboard-layout

default: "qwerty"

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

@fingers-show-copied-notification

default: 0

Show a message using tmux display-message notifying about the copied result.

@fingers-enabled-builtin-patterns

default: all

A list of comma separated pattern names. Built-in patterns are the following:

NameDescriptionExample
ipipv4 addresses192.168.0.1
uuiduuid identifierf1b43afb-773c-4da2-9ae5-fef1aa6945ce
shasha identifierc8b911e2c7e9a6cc57143eaa12cad57c1f0d69df
digitfour or more digits1337
urlurls (supported protocols: http/https/git/ssh/file)https://asdf.com
pathfile pathspath/to/file
hexhexidecimal numbers0x00FF
kuberneteskubernetes identiferdeployment.apps/zookeeper
git-statuswill match file paths in the output of git statusmodified: ./path/to/file
git-status-branchwill match branch name in the output of git statusYour branch is up to date withname-of-branch
diffwill match paths in diff output+++ a/path/to/file

Recipes

Start tmux-fingers without prefix

You can start tmux-fingers without having to press tmux prefix by adding bindings like this:

# tmux.conf

# Start tmux fingers by pressing Alt+F
bind -n M-f run -b "#{@fingers-cli} start #{pane_id}"

# Start tmux fingers in jump mode by pressing Alt+J
bind -n M-j run -b "#{@fingers-cli} start #{pane_id} --mode jump"

Using only specific patterns

You can start tmux-fingers with an specific set of built-in or custom patterns.

# match urls with prefix + u
bind -n u run -b "#{@fingers-cli} start #{pane_id} --patterns url"

# match hashes with prefix + h
bind -n h run -b "#{@fingers-cli} start #{pane_id} --patterns sha"

# match git stuff with prefix + g
bind -n g run -b "#{@fingers-cli} start #{pane_id} --patterns git-status,git-status-branch"

# match custom pattern with prefix + y
set -g @fingers-pattern-yolo "yolo.*"
bind -n y run -b "#{@fingers-cli} start #{pane_id} --patterns yolo"

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! :clap: :clap:

License

MIT