Home

Awesome

Vim's easy-motion for tmux

Demo

tmux-easy-motion demo

Introduction

This plugin brings Vim's easy-motion navigation plugin to tmux. There are already some other plugins with similar functionality:

However, none of the already-existing plugins implement other movements than seeking. Therefore, I started my own implementation which adds much more easy-motion movements. All standard vi motions (b, B, w, W, e, E, ge, gE, j, k, f, F, t, T) and these vim-easy-motion movements are supported:

By default, only the standard vim motions, J, K and c are bound to the keyboard. If you would like to use a bidirectional motions, you need to configure a key binding for it. See the key-bindings section of this README for more details.

Special thanks to the authors of the tmux-fingers project. Reading their source code helped a lot to understand how an easy-motion plugin can be implemented for tmux.

Requirements

This plugin needs at least tmux 3.1 and Python 2.7 or 3.3+. You can check your installed tmux version with

tmux -V

and your installed Python version with

python --version

If you are using a quite recent Linux distribution or macOS, an appropriate Python version should already be installed.

Installation

Using tpm

  1. Add set -g @plugin 'IngoMeyer441/tmux-easy-motion' to your .tmux.conf.

  2. Configure a prefix key for easy-motion movements, the default is Space:

    set -g @easy-motion-prefix "Space"

    By default, the Space key changes layouts in tmux (non-copy mode) or sets the beginning of a selection (copy mode). Therefore, you should configure other keys for these actions if you would like to use Space as easy-motion prefix key, for example:

    bind-key v next-layout
bind-key -T copy-mode-vi v send-keys -X begin-selection

    You can also configure another key binding for copy mode by setting @easy-motion-copy-mode-prefix.

Manual

  1. Clone this repository and add

    run-shell <clone-location>/easy_motion.tmux

    to .tmux.conf.

  2. Configure prefix keys like explained above.

Usage

Press the tmux prefix key followed by the configured easy-motion prefix key (by default Ctrl-b Space) to enter the easy-motion mode. Enter a vi motion command and possible jump targets will be highlighted by red and yellow letters. Press one of the highlighted letters to enter tmux copy-mode and jump to the corresponding position directly.

This plugin also works in tmux copy-mode. In copy-mode you don't need to press the tmux prefix key.

Grouping

If more jump targets exist than configured target keys, targets will be grouped and a second key press is needed to determine the jump target (see the demo for an example). Groups always contain a preview of the next key which is needed to reach the target position. The grouping works exactly like the grouping mechanism in Vim's easy-motion plugin.

The grouping algorithm works recursively, so grouping is repeated if necessary. However, that case should only occur if a small set of target keys was configured.

Configuration

Key bindings

You can set a prefix key for tmux-easy-motion with the @easy-motion-prefix option. It will be bound on the prefix and the copy-mode-vi key table. If you don't want to use the same prefix key for both modes, you can set another key binding for copy mode with the @easy-motion-copy-mode-prefix option or you can disable the key bindings by setting @easy-motion-prefix-enabled and/or @easy-motion-copy-mode-prefix-enabled to false (or no, off, disabled, deactivated, 0).

By default, tmux-easy-motion creates default key bindings for all standard vim motions, J, K and c. If you would like to remove, change or add a single key bindings, change the corresponding option (see the list below). Alternatively, you can set @easy-motion-default-key-bindings to false (or off, disabled, no, deactivated, 0) and configure all easy-motion key binding options yourself.

Available key binding options:

If you only want to use a single easy-motion movement, you can configure it as the default motion which is activated directly after pressing the easy-motion prefix key and save one key press (@easy-motion-default-motion).

Example:

set -g @easy-motion-default-motion "bd-w"

This setting will cause the highlight of all word beginnings (bidirectional) after pressing the configured easy-motion prefix key.

Target keys

The target keys can be configured with the @easy-motion-target-keys option. The default is taken from the Vim default configuration value ("asdghklqwertyuiopzxcvbnmfj;")

You can configure as many keys as you want (minimum two keys).

Example:

set -g @easy-motion-target-keys "asdfghjkl;"

Colors

The color of dimmed and highlighted text can be configured by setting four style options. These are the default settings (taken from the easy-motion Vim plugin):

set -g @easy-motion-dim-style "fg=colour242"
set -g @easy-motion-highlight-style "fg=colour196,bold"
set -g @easy-motion-highlight-2-first-style "fg=brightyellow,bold"
set -g @easy-motion-highlight-2-second-style "fg=yellow,bold"

Possible style values are described in the tmux man page.

These settings were used in the demo:

set -g @easy-motion-dim-style "fg=colour242"
set -g @easy-motion-highlight-style "fg=colour196,bold"
set -g @easy-motion-highlight-2-first-style "fg=#ffb400,bold"
set -g @easy-motion-highlight-2-second-style "fg=#b98300,bold"

Verbose mode

By setting

set -g @easy-motion-verbose "true"

tmux-easy-motion operates in verbose mode which displays messages when easy-motion is activated and a motion was selected.

Auto selection

By setting

set -g @easy-motion-auto-begin-selection "true"

you can enable the automatic start of selection

Other plugins

If you like this plugin and use zsh, please also try my easy-motion port for zsh: zsh-easy-motion.