https://github.com/Morantron/tmux-fingers

copy pasting in terminal with vimium/vimperator like hints.
https://github.com/Morantron/tmux-fingers

hint keyboard-shortcuts productivity tmux tmux-plugins vimium vimperator

Last synced: 3 months ago
JSON representation

copy pasting in terminal with vimium/vimperator like hints.

• Host: GitHub
• URL: https://github.com/Morantron/tmux-fingers
• Owner: Morantron
• License: mit
• Created: 2016-05-01T17:55:44.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2024-07-29T06:03:31.000Z (3 months ago)
• Last Synced: 2024-07-29T07:28:38.578Z (3 months ago)
• Topics: hint, keyboard-shortcuts, productivity, tmux, tmux-plugins, vimium, vimperator
• Language: Crystal
• Size: 2.07 MB
• Stars: 960
• Watchers: 14
• Forks: 45
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-tmux - tmux-fingers

README

        

![tmux-fingers](./logo.svg)

![demo](https://github.com/Morantron/tmux-fingers/assets/3304507/cafe8877-1c98-41b1-bb65-b72129fea701)

# 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

* git status/diff output

Checkout [list of built-in patterns](#fingers-enabled-builtin-patterns).

## 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](#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](#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](#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.

* q, ESC or CTRL + c: exit **[fingers]** mode

# Requirements

* tmux 3.0 or newer

# Installation

## Using [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm)

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

* [@fingers-key](#fingers-key)

* [@fingers-jump-key](#fingers-jump-key)

* [@fingers-patterns-N](#fingers-patterns-N)

* [@fingers-main-action](#fingers-main-action)

* [@fingers-ctrl-action](#fingers-ctrl-action)

* [@fingers-alt-action](#fingers-alt-action)

* [@fingers-shift-action](#fingers-shift-action)

* [@fingers-hint-style](#fingers-hint-style)

* [@fingers-highlight-style](#fingers-highlight-style)

* [@fingers-backdrop-style](#fingers-backdrop-style)

* [@fingers-selected-hint-style](#fingers-selected-hint-style)

* [@fingers-selected-highlight-style](#fingers-selected-highlight-style)

* [@fingers-hint-position](#fingers-hint-position)

* [@fingers-keyboard-layout](#fingers-keyboard-layout)

* [@fingers-show-copied-notification](#fingers-show-copied-notification)

* [@fingers-enabled-builtin-patterns](#fingers-enabled-builtin-patterns)

Recipes:

* [Start tmux-fingers without prefix](#start-tmux-fingers-without-prefix)

* [Using only specific patterns](#using-only-specific-patterns)

## @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 (?YOUR-REGEX-HERE)

# to only highlight and copy part of the match.

set -g @fingers-pattern-2 'capture (?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](https://www.pcre.org/original/doc/html/pcrepattern.html).

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

```

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](#fingers-main-action) but only called when match is selected by holding ctrl

## @fingers-alt-action

Same as [@fingers-main-action](#fingers-main-action) but only called when match is selected by holding alt

## @fingers-shift-action

`default: :paste:`

Same as [@fingers-main-action](#fingers-main-action) but only called when match is selected by holding shift

## @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](#fingers-hint-format) for more details.

## @fingers-backdrop-style

`default: ""`

Custom styles for all the text that is not matched. See [@fingers-hint-format](#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:

  * `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`

## @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:

| Name              | Description                                               | Example                                        |

| ----------------- | --------------------------------------------------------- | ---------------------------------------------- |

| ip                | ipv4 addresses                                            | `192.168.0.1`                                  |

| uuid              | uuid identifier                                           | `f1b43afb-773c-4da2-9ae5-fef1aa6945ce`         |

| sha               | sha identifier                                            | `c8b911e2c7e9a6cc57143eaa12cad57c1f0d69df`     |

| digit             | four or more digits                                       | `1337`                                         |

| url               | urls (supported protocols: http/https/git/ssh/file)       | `https://asdf.com`                             |

| path              | file paths                                                | `path/to/file`                                 |

| hex               | hexidecimal numbers                                       | `0x00FF`                                       |

| kubernetes        | kubernetes identifer                                      | `deployment.apps/zookeeper`                    |

| git-status        | will match file paths in the output of git status         | `modified: ./path/to/file`                     |

| git-status-branch | will match branch name in the output of git status        | `Your branch is up to date withname-of-branch` |

| diff              | will 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](https://github.com/tmux-plugins/tmux-copycat) ( **tmux-fingers**

predefined search are *copycatted* :trollface: from

[tmux-copycat](https://github.com/tmux-plugins/tmux-copycat) ).

Kudos to [bruno-](https://github.com/bruno-) for paving the way to tmux

plugins! :clap: :clap:

# License

[MIT](https://github.com/Morantron/tmux-fingers/blob/master/LICENSE)