2016-05-01 19:50:41 +02:00
2023-09-21 18:35:49 +02:00
![tmux-fingers ](./logo.svg )
2016-05-01 19:50:41 +02:00
2023-09-27 15:20:12 +02:00
![demo ](https://github.com/Morantron/tmux-fingers/assets/3304507/cafe8877-1c98-41b1-bb65-b72129fea701 )
2016-05-02 23:07:23 +02:00
2016-05-01 19:50:41 +02:00
# Usage
2018-02-15 09:33:19 +01:00
Press ( < kbd > prefix</ kbd > + < kbd > F</ kbd > ) to enter ** [fingers]** mode, it will highlight relevant stuff in the current
2016-05-01 19:50:41 +02:00
pane along with letter hints. By pressing those letters, the highlighted match
2020-01-05 12:36:36 +01:00
will be copied to the clipboard. Less keystrokes == profit!
2016-05-01 19:50:41 +02:00
2018-11-08 09:35:04 +01:00
Here is a list of the stuff highlighted by default.
2016-05-01 19:50:41 +02:00
* File paths
2020-03-06 08:45:02 +01:00
* SHAs
2016-05-01 19:54:20 +02:00
* numbers ( 4+ digits )
2018-11-08 09:35:04 +01:00
* hex numbers
* IP addresses
* kubernetes resources
2018-12-30 18:26:35 +01:00
* UUIDs
2023-09-20 10:11:23 +02:00
* git status/diff output
2016-05-01 19:50:41 +02:00
2016-10-17 21:44:28 +02:00
## Key shortcuts
2016-10-17 23:51:50 +02:00
While in ** [fingers]** mode, you can use the following shortcuts:
2016-10-17 21:44:28 +02:00
2020-01-05 12:36:36 +01:00
* < kbd > a</ kbd > -< kbd > z</ kbd > : copies selected match to the clipboard
* < kbd > CTRL</ kbd > + < kbd > a</ kbd > -< kbd > z</ kbd > : 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.
2020-01-05 12:44:09 +01:00
* < kbd > SHIFT</ kbd > + < kbd > a</ kbd > -< kbd > z</ kbd > : 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.
2020-01-05 12:36:36 +01:00
* < kbd > ALT</ kbd > + < kbd > a</ kbd > -< kbd > z</ kbd > : copies selected match to the clipboard and triggers [@fingers-alt-action ](#fingers-alt-action ). There is no default, configurable by the user.
* < kbd > TAB</ kbd > : 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.
2023-09-20 10:11:23 +02:00
* < kbd > q</ kbd > , < kbd > ESC</ kbd > or < kbd > CTRL</ kbd > + < kbd > c</ kbd > : exit ** [fingers]** mode
2016-10-17 21:44:28 +02:00
2016-05-02 23:00:28 +02:00
# Requirements
2020-05-02 11:45:56 +02:00
* tmux 3.0 or newer
2016-05-02 23:00:28 +02:00
2016-05-01 19:50:41 +02:00
# 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'
```
2020-05-02 11:45:56 +02:00
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.
2016-05-01 19:50:41 +02:00
## Manual
Clone the repo:
```
2020-05-02 11:45:56 +02:00
$ git clone https://github.com/Morantron/tmux-fingers ~/.tmux/plugins/tmux-fingers
2016-05-01 19:50:41 +02:00
```
Source it in your `.tmux.conf` :
```
2017-08-14 09:53:45 +02:00
run-shell ~/.tmux/plugins/tmux-fingers/tmux-fingers.tmux
2016-05-01 19:50:41 +02:00
```
Reload TMUX conf by running:
```
2020-05-02 11:45:56 +02:00
$ tmux source-file ~/.tmux.conf
2016-05-01 19:50:41 +02:00
```
2020-05-02 11:45:56 +02:00
The first time you run it you'll be presented with a wizard to complete the installation.
2016-05-01 19:57:07 +02:00
# Configuration
2016-05-01 19:50:41 +02:00
2017-05-02 17:41:30 +02:00
NOTE: for changes to take effect, you'll need to source again your `.tmux.conf` file.
* [@fingers-key ](#fingers-key )
2023-11-18 10:31:37 +01:00
* [@fingers-jump-key ](#fingers-jump-key )
2017-05-02 17:41:30 +02:00
* [@fingers-patterns-N ](#fingers-patterns-N )
2018-12-30 19:12:40 +01:00
* [@fingers-main-action ](#fingers-main-action )
* [@fingers-ctrl-action ](#fingers-ctrl-action )
* [@fingers-alt-action ](#fingers-alt-action )
* [@fingers-shift-action ](#fingers-shift-action )
2023-09-21 18:35:41 +02:00
* [@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 )
2017-05-02 17:41:30 +02:00
* [@fingers-hint-position ](#fingers-hint-position )
2023-09-21 18:35:41 +02:00
* [@fingers-keyboard-layout ](#fingers-keyboard-layout )
2023-10-26 18:55:41 +02:00
* [@fingers-show-copied-notification ](#fingers-show-copied-notification )
2016-05-01 19:50:41 +02:00
2016-05-14 09:45:43 +02:00
## @fingers-key
2016-10-17 21:44:28 +02:00
`default: F`
2023-11-10 15:48:55 +01:00
Customize how to enter fingers mode. Always preceded by prefix: `prefix + @fingers-key` .
2017-05-02 17:41:30 +02:00
For example:
2016-05-14 09:45:43 +02:00
2016-05-01 19:50:41 +02:00
```
set -g @fingers -key F
```
2023-11-10 15:48:55 +01:00
## @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.
2016-05-14 09:45:43 +02:00
## @fingers-patterns-N
2016-05-01 19:50:41 +02:00
You can also add additional patterns if you want more stuff to be highlighted:
```
2023-09-21 18:21:38 +02:00
# You can define custom patterns like this
2016-05-01 19:50:41 +02:00
set -g @fingers -pattern-0 'git rebase --(abort|continue)'
2023-09-21 18:21:38 +02:00
# 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
2016-05-01 19:50:41 +02:00
```
2023-09-21 18:21:38 +02:00
Patterns use [PCRE pattern syntax ](https://www.pcre.org/original/doc/html/pcrepattern.html ).
2016-05-01 19:50:41 +02:00
2023-09-21 18:21:38 +02:00
If the introduced regex contains an error, an error will be shown when invoking the plugin.
2016-05-01 19:50:41 +02:00
2018-12-30 19:12:40 +01:00
## @fingers-main-action
2018-02-15 09:33:19 +01:00
2018-12-30 19:12:40 +01:00
`default: :copy:`
2018-12-02 21:07:47 +01:00
2018-12-30 19:12:40 +01:00
By default **tmux-fingers** will copy matches in tmux and system clipboard.
2016-05-14 09:45:43 +02:00
If you still want to set your own custom command you can do so like this:
```
2018-12-30 19:12:40 +01:00
set -g @fingers -main-action '< your command here > '
2016-05-14 09:45:43 +02:00
```
2018-02-15 09:33:19 +01:00
This command will also receive the following:
2018-12-30 19:12:40 +01:00
* `MODIFIER` : environment variable set to `ctrl` , `alt` , or `shift` specififying which modifier was used when selecting the match.
2018-12-02 21:07:47 +01:00
* `HINT` : environment variable the selected letter hint itself ( ex: `q` , `as` , etc... ).
2018-02-15 09:33:19 +01:00
* `stdin` : copied text will be piped to `@fingers-copy-command` .
2018-12-30 19:12:40 +01:00
You can also use the following special values:
2018-02-15 09:33:19 +01:00
2018-12-30 19:12:40 +01:00
* `: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 ).
2018-02-15 09:33:19 +01:00
2018-12-30 19:12:40 +01:00
## @fingers-ctrl-action
2018-02-15 09:33:19 +01:00
2018-12-30 19:12:40 +01:00
`default: :open:`
2018-02-15 09:33:19 +01:00
2018-12-30 19:12:40 +01:00
Same as [@fingers-main-action ](#fingers-main-action ) but only called when match is selected by holding < kbd > ctrl</ kbd >
2018-02-15 09:33:19 +01:00
2018-12-30 19:12:40 +01:00
## @fingers-alt-action
Same as [@fingers-main-action ](#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 ](#fingers-main-action ) but only called when match is selected by holding < kbd > shift</ kbd >
2023-09-20 10:11:23 +02:00
## @fingers-hint-style
2018-12-30 19:12:40 +01:00
2023-09-21 18:21:38 +02:00
`default: "fg=green,bold`
2018-12-30 19:12:40 +01:00
2023-09-20 10:11:23 +02:00
With this option you can define the styles for the letter hints.
2018-12-30 19:12:40 +01:00
2023-09-20 10:11:23 +02:00
You can customize the styles using the same syntax used in `.tmux.conf` for styling the status bar.
2018-12-02 21:07:47 +01:00
2023-09-20 10:11:23 +02:00
More info in the `STYLES` section of `man tmux` .
2016-10-17 21:44:28 +02:00
2023-09-20 10:11:23 +02:00
Supported styles are: `bright` , `bold` , `dim` , `underscore` , `italics` .
2016-10-17 21:44:28 +02:00
2023-09-20 10:11:23 +02:00
## @fingers-highlight-style
2016-10-17 21:44:28 +02:00
2023-09-21 18:21:38 +02:00
`default: "fg=yellow"`
2016-10-17 21:44:28 +02:00
2023-09-20 10:11:23 +02:00
Custom styles for the highlighted match. See [@fingers-hint-format ](#fingers-hint-format ) for more details.
2016-10-17 21:44:28 +02:00
2023-09-21 18:21:38 +02:00
## @fingers-backdrop-style
`default: ""`
Custom styles for all the text that is not matched. See [@fingers-hint-format ](#fingers-hint-format ) for more details.
2023-09-20 10:11:23 +02:00
## @fingers-selected-hint-style
2016-10-17 21:44:28 +02:00
2023-09-21 18:21:38 +02:00
`default: "fg=blue,bold"`
2016-10-17 21:44:28 +02:00
2023-09-20 10:11:23 +02:00
Format for hints in selected matches in multimode.
2016-10-17 21:44:28 +02:00
2023-09-20 10:11:23 +02:00
## @fingers-selected-highlight-style
2016-10-17 21:44:28 +02:00
2023-09-21 18:21:38 +02:00
`default: "fg=blue"`
2016-10-17 21:44:28 +02:00
2023-09-20 10:11:23 +02:00
Format for selected matches in multimode.
2016-10-17 21:44:28 +02:00
2017-05-02 17:41:30 +02:00
## @fingers-hint-position
`default: "left"`
Control the position where the hint is rendered. Possible values are `"left"`
and `"right"` .
2019-01-17 16:38:11 +01:00
## @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`
2023-10-26 18:55:41 +02:00
## @fingers-show-copied-notification
`default: 0`
Show a message using `tmux display-message` notifying about the copied result.
2016-05-01 19:50:41 +02:00
# 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
2016-05-01 19:57:07 +02:00
[MIT ](https://github.com/Morantron/tmux-fingers/blob/master/LICENSE )