2016-05-01 19:50:41 +02:00
# tmux-fingers
2019-11-27 13:47:27 +01:00
[![Build Status ](https://travis-ci.com/Morantron/tmux-fingers.svg?branch=develop )](https://travis-ci.com/Morantron/tmux-fingers)
2016-07-14 22:48:01 +02:00
2016-05-01 19:50:41 +02:00
**tmux-fingers**: copy pasting with vimium/vimperator like hints.
2016-05-14 10:04:21 +02:00
![yay ](http://i.imgur.com/5bSrBew.gif )
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
2016-05-01 19:50:41 +02:00
It also works on copy mode, but requires *tmux 2.2* or newer to properly take
the scroll position into account.
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.
2018-02-15 09:33:19 +01:00
* < kbd > SPACE</ kbd > : toggle compact hints ( see [@fingers-compact-hints ](#fingers-compact-hints ) ).
* < kbd > CTRL</ kbd > + < kbd > c</ kbd > : exit ** [fingers]** mode
* < kbd > ESC</ kbd > : exit help or ** [fingers]** mode
* < kbd > ?</ kbd > : show help.
2016-10-17 21:44:28 +02:00
2016-05-02 23:00:28 +02:00
# Requirements
2018-12-30 19:12:40 +01:00
* tmux 2.1+ ( 2.8 recommended )
2017-04-02 17:55:39 +02:00
* bash 4+
* gawk
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'
```
2018-02-15 09:33:19 +01:00
Hit < kbd > prefix< / kbd > + < kbd > I< / kbd > to fetch and source the plugin. You should now be able to use
2016-05-01 19:50:41 +02:00
the plugin!
## Manual
Clone the repo:
```
2017-08-14 09:53:45 +02:00
# Use --recursive flag to also fetch submodules
➜ git clone --recursive 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:
```
2016-05-01 19:57:07 +02:00
➜ tmux source-file ~/.tmux.conf
2016-05-01 19:50:41 +02:00
```
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 )
* [@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 )
2017-05-02 17:41:30 +02:00
* [@fingers-compact-hints ](#fingers-compact-hints )
* [@fingers-hint-position ](#fingers-hint-position )
* [@fingers-hint-position-nocompact ](#fingers-hint-position-nocompact )
* [@fingers-hint-format ](#fingers-hint-format )
* [@fingers-hint-format-nocompact ](#fingers-hint-format-nocompact )
* [@fingers-highlight-format ](#fingers-highlight-format )
* [@fingers-highlight-format-nocompact ](#fingers-highlight-format-nocompact )
2020-01-06 11:19:33 +01:00
* [@fingers-selected-hint-format ](#fingers-selected-hint-format )
* [@fingers-selected-hint-format-nocompact ](#fingers-selected-hint-format-nocompact )
* [@fingers-selected-highlight-format ](#fingers-selected-highlight-format )
* [@fingers-selected-highlight-format-nocompact ](#fingers-selected-highlight-format-nocompact )
2018-12-30 19:12:40 +01:00
* deprecated: [@fingers-copy-command ](#fingers-copy-command )
* deprecated: [@fingers-copy-command-uppercase ](#fingers-copy-command-uppercase )
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`
2017-05-02 17:41:30 +02:00
Customize how to enter fingers mode. Always preceded by prefix: `prefix + @fingers-key`
For example:
2016-05-14 09:45:43 +02:00
2016-05-01 19:50:41 +02:00
```
set -g @fingers -key F
```
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:
```
set -g @fingers -pattern-0 'git rebase --(abort|continue)'
set -g @fingers -pattern-1 'yolo'
.
.
.
2016-05-01 19:54:20 +02:00
set -g @fingers -pattern-50 'whatever'
2016-05-01 19:50:41 +02:00
```
2016-08-19 08:00:19 +02:00
Patterns are case insensitive, and grep's extended syntax ( ERE ) should be used.
2016-05-01 19:50:41 +02:00
`man grep` for more info.
If the introduced regexp contains an error, an error will be shown when
invoking the plugin.
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
This option requires `tmux 2.8` or higher.
2018-12-02 21:07:47 +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 >
This option requires `tmux 2.8` or higher.
## @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 >
## @fingers-copy-command
_DEPRECATED: this option is deprecated, please use [@fingers-main-action ](#fingers-main-action ) instead_
## @fingers-copy-command-uppercase
_DEPRECATED: this option is deprecated, please use [@fingers-shift-action ](#fingers-shift-action ) instead_
2018-12-02 21:07:47 +01:00
2016-10-17 21:44:28 +02:00
## @fingers-compact-hints
`default: 1`
2017-05-02 15:46:28 +02:00
By default **tmux-fingers** will show hints in a compact format. For example:
2016-10-17 21:44:28 +02:00
< pre >
/path/to/foo/bar/lol
< i > with < bold > @fingers-compact-hints< / bold > set to < bold > 1< / bold > :< / i >
< strong > aw< / strong > ath/to/foo/bar/lol
< i > with < bold > @fingers-compact-hints< / bold > set to < bold > 0< / bold > :< / i >
/path/to/foo/bar/lol < strong > [aw]< / strong >
< / pre >
2020-01-05 12:36:36 +01:00
( _pressing *aw* would copy `/path/to/foo/bar/lol`_ )
2016-10-17 21:44:28 +02:00
2018-02-15 09:33:19 +01:00
While in ** [fingers]** mode you can press < kbd > SPACE</ kbd > to toggle compact mode on/off.
2016-10-17 21:44:28 +02:00
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
2018-02-15 09:33:19 +01:00
quickly toggle off compact mode by pressing < kbd > SPACE< / kbd > .
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"` .
## @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"`
2018-12-30 19:12:40 +01:00
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.
2017-05-02 17:41:30 +02:00
Check all supported features [here ](https://github.com/morantron/tmux-printer ).
## @fingers-hint-format-nocompact
`default: "#[fg=yellow,bold][%s]"`
Same as above, used when `@fingers-compact-hints` is set to `0` .
## @fingers-highlight-format
2020-01-05 12:36:36 +01:00
`default: "#[fg=yellow,nobold,dim]%s"`
2017-05-02 17:41:30 +02:00
Custom format for the highlighted match. See [@fingers-hint-format ](#fingers-hint-format ) for more details.
## @fingers-highlight-format-nocompact
2020-01-05 12:36:36 +01:00
`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]"`
2017-05-02 17:41:30 +02:00
Same as above, used when `@fingers-compact-hints` is set to `0` .
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`
2018-11-08 09:27:53 +01:00
# 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 ](./docs/health-check.md )
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 )