2014-02-21 10:15:36 -05:00
Vim motion on speed!
2014-01-30 07:32:28 -05:00
=====
2014-03-21 11:10:25 -04:00
[![Build Status ](https://travis-ci.org/Lokaltog/vim-easymotion.svg?branch=master )](https://travis-ci.org/Lokaltog/vim-easymotion)
2013-06-03 18:54:49 -04:00
2014-01-30 19:50:15 -05:00
![Animated demonstration ](https://f.cloud.github.com/assets/3797062/2039359/a8e938d6-899f-11e3-8789-60025ea83656.gif )
2014-02-09 12:41:45 -05:00
About the authors
2014-01-30 07:32:28 -05:00
=====
2014-02-09 12:41:45 -05:00
2014-01-30 07:32:28 -05:00
- Kim Silkebækken (https://github.com/Lokaltog)
2014-02-09 12:41:45 -05:00
- haya14busa (https://github.com/haya14busa) (since version 2.0)
2013-06-03 18:54:49 -04:00
2014-02-14 00:58:26 -05:00
The EasyMotion project, revived!
2014-01-30 07:32:28 -05:00
======
2014-02-09 12:41:45 -05:00
2014-02-14 00:58:26 -05:00
Starting from version 2.0 [haya14busa ](https://github.com/haya14busa ) will be
taking over the project from [Lokaltog ](https://github.com/Lokaltog ). He's
improved the default motions, implemented many useful new features, and fixed
some bugs.
2013-06-03 18:54:49 -04:00
2014-02-09 12:41:45 -05:00
EasyMotion is now completely
2013-10-04 13:34:48 -04:00
2014-02-14 00:58:26 -05:00
- **Well-behaved**: It's consistent with the default motions of Vim and works
well in all modes. And it now supports repeating with the dot operator.
2014-03-23 17:57:51 -04:00
- **Configurable**: You can easily configure its behavior and map it to any key
- **Sofisticated**: Provide flawless, smooth and fast motions with minimal keystrokes
2011-03-28 06:54:03 -04:00
2014-02-14 00:58:26 -05:00
Even though some default behaviors were modified and many new features were
added, I carefully considered backward compatibility. So those of you updating
from older versions can do so without worry and start benefitting immediately
from all the new features!
2014-01-30 07:32:28 -05:00
Introduction
=====
2014-02-09 12:41:45 -05:00
2011-06-01 04:14:20 -04:00
EasyMotion provides a much simpler way to use some motions in vim. It
takes the `<number>` out of `<number>w` or `<number>f{char}` by
highlighting all possible choices and allowing you to press one key to
2011-03-28 06:54:03 -04:00
jump directly to the target.
2011-06-01 04:14:20 -04:00
When one of the available motions is triggered, all visible text
preceding or following the cursor is faded, and motion targets are
2011-03-28 06:54:03 -04:00
highlighted.
2014-02-14 00:58:26 -05:00
EasyMotion is triggered by the provided mappings. This readme only covers the
basics; please refer to
[`:help easymotion.txt` ](https://github.com/Lokaltog/vim-easymotion/blob/master/doc/easymotion.txt#L86 )
to see all of the available mappings.
2014-02-09 12:41:45 -05:00
2014-01-30 07:32:28 -05:00
Important notes
=====
2011-04-07 04:29:03 -04:00
2014-02-09 12:41:45 -05:00
### Default bindings
2013-10-04 07:35:22 -04:00
**The default leader has been changed to `<Leader><Leader>` to avoid
conflicts with other plugins you may have installed.** This can easily be
2011-11-07 08:39:51 -05:00
changed back to pre-1.3 behavior by rebinding the leader in your vimrc:
2011-04-07 04:29:03 -04:00
2014-01-30 07:32:28 -05:00
```vim
map < Leader > < Plug > (easymotion-prefix)
```
2014-02-14 00:58:26 -05:00
All motions will then be triggered with `<Leader>` by default, e.g.
2014-01-30 07:32:28 -05:00
`<Leader>s` , `<Leader>gE` .
2011-04-07 04:29:03 -04:00
2014-02-09 12:41:45 -05:00
### For users of the forked version
2014-02-14 00:58:26 -05:00
SelectLines and SelectPhrase are not actually *motions* , so I've moved them into
separate plugins.
2011-04-07 04:29:03 -04:00
2014-01-30 19:50:15 -05:00
- https://github.com/haya14busa/vim-easyoperator-line
- https://github.com/haya14busa/vim-easyoperator-phrase
2011-03-28 06:54:03 -04:00
2014-02-09 12:41:45 -05:00
Usage example for the base features
2014-01-30 07:32:28 -05:00
=====
2014-02-09 12:41:45 -05:00
< cursor > Lorem ipsum dolor sit amet.
2014-02-14 00:58:26 -05:00
Type `<Leader><Leader>w` (`< Plug > (easymotion-w)`) to trigger the word motion `w` .
When the motion is triggered, the text is updated (no braces are actually added,
the text is highlighted in red by default):
2011-03-28 06:54:03 -04:00
< cursor > Lorem {a}psum {b}olor {c}it {d}met.
Press `c` to jump to the beginning of the word "sit":
Lorem ipsum dolor < cursor > sit amet.
2011-06-01 04:14:20 -04:00
Similarly, if you're looking for an "o", you can use the `f` motion.
2011-11-07 08:39:51 -05:00
Type `<Leader><Leader>fo` , and all "o" characters are highlighted:
2011-03-31 02:23:06 -04:00
< cursor > L{a}rem ipsum d{b}l{c}r sit amet.
Press `b` to jump to the second "o":
Lorem ipsum d< cursor > olor sit amet.
2011-06-01 04:14:20 -04:00
Jeffrey Way of Nettuts+ has also [written
a tutorial](http://net.tutsplus.com/tutorials/other/vim-essential-plugin-easymotion/)
2014-01-30 19:50:15 -05:00
about EasyMotion.
2011-03-28 06:54:03 -04:00
2013-12-21 09:58:24 -05:00
2014-02-14 00:58:26 -05:00
New features in version 2.0
2014-02-09 12:41:45 -05:00
====
### Two key highlighting
2014-02-14 00:58:26 -05:00
When EasyMotion runs out of single characters to highlight movement targets, it
now shows you immediately the keys you have to press.
2013-12-21 09:58:24 -05:00
2014-02-14 00:58:26 -05:00
In previous versions you could not see the next character you would needed to
press until you entered the first one. This made movement over long distances
less fluid. Now you can see at a glance exactly which characters to select to
get to your destination.
2013-12-21 09:58:24 -05:00
2014-02-09 12:41:45 -05:00
### Bidirectional motions
2013-12-21 09:58:24 -05:00
2014-02-14 00:58:26 -05:00
All motions now come in a bidirectional variants (e.g. `<Plug>(easymotion-s)` ,
`<Plug>(easymotion-bd-w)` and so forth).
By default you can already jump forward or backward with `<Leader>s` . A useful
trick is to map `nmap s <Plug>(easymotion-s)` to use `s` instead and save one
keystroke!
2014-02-09 12:41:45 -05:00
### 2-character search motion
You can now also perform a 2-character search, similar to [vim-seek ](https://github.com/goldfeld/vim-seek )/[vim-sneak](https://github.com/justinmk/vim-sneak) with `<Plug>(easymotion-s2)` . For example you can highlight all words that start with `fu` .
2013-10-04 13:34:48 -04:00
2014-01-30 07:32:28 -05:00
![2-key-find-motion ](https://f.cloud.github.com/assets/3797062/2039612/7cafcec8-89a5-11e3-8f2c-5f26a6b83efd.gif )
2014-02-09 12:41:45 -05:00
2014-01-30 19:50:15 -05:00
```vim
2014-02-01 01:00:26 -05:00
" Gif config
2014-01-30 19:50:15 -05:00
nmap s < Plug > (easymotion-s2)
nmap t < Plug > (easymotion-t2)
```
2013-10-04 13:34:48 -04:00
2014-02-09 12:41:45 -05:00
### n-character search motion
2013-10-04 13:34:48 -04:00
2014-02-09 12:41:45 -05:00
You can also search for `n` characters, which basically can be used to replace the default search of Vim.
2014-03-03 09:08:46 -05:00
It supports incremental highlighting and you can use `<Tab>` and `<S-Tab>` to scroll down/up a page. If you press
2014-02-09 12:41:45 -05:00
`<CR>` you get the usual EasyMotion highlighting and can jump to any matching target destination with a
single keystroke.
What sounds complicated should become clear if you look at the following examples.
2013-10-04 13:34:48 -04:00
2014-01-30 07:32:28 -05:00
![n-key-motion-scroll ](https://f.cloud.github.com/assets/3797062/2039254/4fbf7276-899e-11e3-9bf3-1e446cabc097.gif )
2013-10-04 13:34:48 -04:00
2014-01-30 07:32:28 -05:00
![replace-search ](https://f.cloud.github.com/assets/3797062/2039751/64b72bd8-89a8-11e3-80ea-2a6b578040b2.gif )
2013-10-04 13:34:48 -04:00
2014-01-30 07:32:28 -05:00
```vim
2014-02-01 01:00:26 -05:00
" Gif config
2014-01-30 07:32:28 -05:00
map / < Plug > (easymotion-sn)
omap / < Plug > (easymotion-tn)
map n < Plug > (easymotion-next)
map N < Plug > (easymotion-prev)
```
2013-10-04 13:34:48 -04:00
2014-02-09 12:41:45 -05:00
### Within line motion
2014-02-14 00:58:26 -05:00
Every motion also has variants that are restricted to just the current line
(e.g. `<Plug>(easymotion-sl)` , `<Plug>(easymotion-bd-wl)` , etc...). This can be
helpful if you find the full search distracting or slows down vim.
2014-02-09 12:41:45 -05:00
### hjkl motions
2013-10-04 13:34:48 -04:00
2014-02-14 00:58:26 -05:00
EasyMotion can be configured to avoid repetitive use of the `h` `j` `k` and
`l` keys.
2014-02-09 12:41:45 -05:00
2014-02-14 00:58:26 -05:00
![hjkl-motion ](https://f.cloud.github.com/assets/3797062/2039413/d8b32ab2-89a0-11e3-894f-3e81db084cfd.gif )
2013-10-04 13:34:48 -04:00
2014-01-30 07:32:28 -05:00
```vim
2014-02-01 01:00:26 -05:00
" Gif config
2014-01-30 07:32:28 -05:00
map < Leader > h < Plug > (easymotion-lineforward)
map < Leader > j < Plug > (easymotion-j)
map < Leader > k < Plug > (easymotion-k)
map < Leader > l < Plug > (easymotion-linebackward)
2013-10-04 13:34:48 -04:00
2014-01-30 07:32:28 -05:00
let g:EasyMotion_startofline = 0 " keep cursor colum when JK motion
```
2013-12-21 09:58:24 -05:00
2014-02-09 12:41:45 -05:00
### Smartcase & Smartsign
2013-12-21 09:58:24 -05:00
2014-02-14 00:58:26 -05:00
This setting makes EasyMotion work similarly to Vim's `smartcase` option for
global searches.
2013-12-21 09:58:24 -05:00
2014-02-09 12:41:45 -05:00
```vim
let g:EasyMotion_smartcase = 1
```
2013-12-21 09:58:24 -05:00
2014-02-14 00:58:26 -05:00
With this option set, `v` will match both `v` and `V` , but `V` will match `V`
only. Default: 0.
2013-12-21 09:58:24 -05:00
2014-02-09 12:41:45 -05:00
```vim
let g:EasyMotion_use_smartsign_us = 1 " US layout
" or
let g:EasyMotion_use_smartsign_jp = 1 " JP layout
```
2013-12-21 09:58:24 -05:00
2014-02-14 00:58:26 -05:00
This applies the same concept, but for symbols and numerals. `1` will match `1`
and `!` ; `!` matches `!` only. Default: 0.
2013-12-21 09:58:24 -05:00
2014-02-09 12:41:45 -05:00
### Migemo feature (for Japanese user)
2013-12-21 09:58:24 -05:00
2014-01-30 07:32:28 -05:00
```vim
2014-02-09 12:41:45 -05:00
let g:EasyMotion_use_migemo = 1
2014-01-30 07:32:28 -05:00
```
2013-12-21 09:58:24 -05:00
2014-02-09 12:41:45 -05:00
2014-02-14 00:58:26 -05:00
Easymotion can match multibyte Japanese characters with alphabetical input.
2014-02-01 01:06:37 -05:00
For example, `<Leader><Leader>sa` can search 'あ'.
2014-01-30 07:32:28 -05:00
This feature doesn't require cmigemo because Easymotion includes regex
2014-02-14 00:58:26 -05:00
patterns generated by cmigemo. However installing `cmigemo` will make
2-character and n-character search motions to also support the migemo feature.
2014-02-09 12:41:45 -05:00
Default:0
2013-12-21 09:58:24 -05:00
2014-02-09 12:41:45 -05:00
### Repeat motions
2013-12-21 09:58:24 -05:00
2014-02-09 12:41:45 -05:00
#### Repeat the last motion
2013-12-21 09:58:24 -05:00
2014-02-09 12:41:45 -05:00
`<Plug>(easymotion-repeat)`
2014-01-30 19:50:15 -05:00
2014-02-09 12:41:45 -05:00
#### Repeat the last find motion
2014-01-30 19:50:15 -05:00
2014-02-09 12:41:45 -05:00
In a find motion (e.g. `<Plug>(easymotion-s)` ), type `<CR>` without
input characters to find the last motion again.
2014-01-30 19:50:15 -05:00
2014-02-09 12:41:45 -05:00
#### Jump to next/previous match (even on next/previous page)
2014-01-30 07:32:28 -05:00
2014-02-14 00:58:26 -05:00
* `<Plug>(easymotion-next)`
2014-02-09 12:41:45 -05:00
* `<Plug>(easymotion-prev)`
2014-01-30 07:32:28 -05:00
2014-02-09 12:41:45 -05:00
#### Support for dot repeat
2014-01-30 19:50:15 -05:00
2014-02-09 12:41:45 -05:00
This requires https://github.com/tpope/vim-repeat.
2014-01-30 19:50:15 -05:00
2014-02-14 00:58:26 -05:00
You can use EasyMotion with operators and press `.` to repeat!
It is well-behaved, and consistent with the default behavior of Vim.
2014-01-30 07:32:28 -05:00
![repeat-motion ](https://f.cloud.github.com/assets/3797062/2039538/0aef66aa-89a4-11e3-8242-c27a5208cfca.gif )
```vim
2014-02-01 01:00:26 -05:00
" Gif config
2014-01-30 07:32:28 -05:00
" Require tpope/vim-repeat to enable dot repeat support
" Jump to anywhere with only `s{char}{target}`
" `s<CR>` repeat last find motion.
nmap s < Plug > (easymotion-s)
" Bidirectional & within line 't' motion
omap t < Plug > (easymotion-bd-tl)
" Use uppercase target labels and type as a lower case
let g:EasyMotion_use_upper = 1
" type `l` and match `l` & `L`
let g:EasyMotion_smartcase = 1
" Smartsign (type `3` and match `3` & `#`)
let g:EasyMotion_use_smartsign_us = 1
```
2014-03-23 17:57:51 -04:00
Installation
------------
### Pathogen (https://github.com/tpope/vim-pathogen)
```
git clone https://github.com/Lokaltog/vim-easymotion ~/.vim/bundle/vim-easymotion
```
### Vundle (https://github.com/gmarik/vundle)
```
Bundle 'Lokaltog/vim-easymotion'
```
### NeoBundle (https://github.com/Shougo/neobundle.vim)
```
NeoBundle 'Lokaltog/vim-easymotion'
```
Minimal Configuration Tutorial
------------------------------
**I recommend to configure and map keys by yourself if you are true Vimmer.**
**Please do not be satisfied with just installing vim-easymotion, configuring it yourself boost your productibity more and more!**
Default `<Leader><Leader>` prefix isn't easy to press, and I leave them just for backwards compatibility.
You should at least change prefix key like this `map <Leader> <Plug>(easymotion-prefix)`
Minimal but useful vimrc example:
```
let g:EasyMotion_do_mapping = 0 " Disable default mappings
" Bi-directional find motion
" Jump to anywhere you want with minimal keystrokes, with just one key binding.
" `s{char}{label}`
nmap s < Plug > (easymotion-s)
" or
" `s{char}{char}{label}`
" Need one more keystroke, but on average, it may be more comfortable.
nmap s < Plug > (easymotion-s2)
" Turn on case sensitive feature
let g:EasyMotion_smartcase = 1
" JK motions: Line motions
map < Leader > j < Plug > (easymotion-j)
map < Leader > k < Plug > (easymotion-k)
```
Now, all you need to remember is `s` and JK motions bindings, and it's good enough to boost your cursor speed!
**`s`** is bidirectional find motion, you can move to anywhere with it.
**`< Leader > j`** & ** `<Leader>k` ** make it easy to move to the lines.
Of course you can use any key you want instead of `s` such as `<Space>` , `<Leader>s` , etc...
If you want to use more useful mappings, please see [:h easymotion.txt ](https://github.com/Lokaltog/vim-easymotion/blob/master/doc/easymotion.txt ) for more detail.