]> git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/easymotion.txt
Add DS_Store to gitignore
[rbdr/dotfiles] / vim / doc / easymotion.txt
1 *easymotion.txt* Version 1.3. Last change: 2011 Nov 7
2
3
4 ______ __ ___ __ _
5 / ____/____ ________ __/ |/ /____ / /_(_)____ ____
6 / __/ / __ `/ ___/ / / / /|_/ // __ \/ __/ // __ \/ __ \
7 / /___ / /_/ (__ ) /_/ / / / // /_/ / /_/ // /_/ / / / /
8 /_____/ \__,_/____/\__, /_/ /_/ \____/\__/_/ \____/_/ /_/
9 /____/
10 - Vim motions on speed!
11
12
13 ==============================================================================
14 CONTENTS *easymotion-contents*
15
16 1. Introduction ....................... |easymotion-introduction|
17 2. Usage .............................. |easymotion-usage|
18 2.1 Default mappings ............... |easymotion-default-mappings|
19 3. Requirements ....................... |easymotion-requirements|
20 4. Configuration ...................... |easymotion-configuration|
21 4.1 EasyMotion_keys ................ |EasyMotion_keys|
22 4.2 EasyMotion_do_shade ............ |EasyMotion_do_shade|
23 4.3 EasyMotion_do_mapping .......... |EasyMotion_do_mapping|
24 4.4 EasyMotion_grouping ............ |EasyMotion_grouping|
25 4.5 Custom highlighting ............ |easymotion-custom-hl|
26 4.6 Custom mappings ................ |easymotion-custom-mappings|
27 4.6.1 Leader key ............... |easymotion-leader-key|
28 4.6.2 Custom keys .............. |easymotion-custom-keys|
29 5. License ............................ |easymotion-license|
30 6. Known bugs ......................... |easymotion-known-bugs|
31 7. Contributing ....................... |easymotion-contributing|
32 8. Credits ............................ |easymotion-credits|
33
34 ==============================================================================
35 1. Introduction *easymotion* *easymotion-introduction*
36
37 EasyMotion provides a much simpler way to use some motions in vim. It takes
38 the <number> out of <number>w or <number>f{char} by highlighting all possible
39 choices and allowing you to press one key to jump directly to the target.
40
41 When one of the available motions is triggered, all visible text preceding or
42 following the cursor is faded, and motion targets are highlighted.
43
44 ==============================================================================
45 2. Usage *easymotion-usage*
46
47 EasyMotion is triggered by one of the provided mappings (see
48 |easymotion-default-mappings| for details).
49
50 Example: >
51
52 <cursor>Lorem ipsum dolor sit amet.
53
54 Type <Leader><Leader>w to trigger the word motion |w|. See
55 |easymotion-leader-key| for details about the leader key. When the
56 motion is triggered, the text is updated (no braces are actually added,
57 the text is highlighted in red by default): >
58
59 <cursor>Lorem {a}psum {b}olor {c}it {d}met.
60
61 Press "c" to jump to the beginning of the word "sit": >
62
63 Lorem ipsum dolor <cursor>sit amet.
64
65 Similarly, if you're looking for an "o", you can use the |f| motion.
66 Type <Leader><Leader>fo, and all "o" characters are highlighted: >
67
68 <cursor>L{a}rem ipsum d{b}l{c}r sit amet.
69
70 Press "b" to jump to the second "o": >
71
72 Lorem ipsum d<cursor>olor sit amet.
73
74 And that's it!
75
76 ------------------------------------------------------------------------------
77 2.1 Default mappings *easymotion-default-mappings*
78
79 The default configuration defines the following mappings in normal,
80 visual and operator-pending mode:
81
82 Mapping | Details
83 ------------------|----------------------------------------------
84 <Leader>f{char} | Find {char} to the right. See |f|.
85 <Leader>F{char} | Find {char} to the left. See |F|.
86 <Leader>t{char} | Till before the {char} to the right. See |t|.
87 <Leader>T{char} | Till after the {char} to the left. See |T|.
88 <Leader>w | Beginning of word forward. See |w|.
89 <Leader>W | Beginning of WORD forward. See |W|.
90 <Leader>b | Beginning of word backward. See |b|.
91 <Leader>B | Beginning of WORD backward. See |B|.
92 <Leader>e | End of word forward. See |e|.
93 <Leader>E | End of WORD forward. See |E|.
94 <Leader>ge | End of word backward. See |ge|.
95 <Leader>gE | End of WORD backward. See |gE|.
96 <Leader>j | Line downward. See |j|.
97 <Leader>k | Line upward. See |k|.
98 <Leader>n | Jump to latest "/" or "?" forward. See |n|.
99 <Leader>N | Jump to latest "/" or "?" backward. See |N|.
100
101 See |easymotion-leader-key| and |mapleader| for details about the leader key.
102 See |easymotion-custom-mappings| for customizing the default mappings.
103
104 ==============================================================================
105 3. Requirements *easymotion-requirements*
106
107 EasyMotion has been developed and tested in vim 7.3, but it should run without
108 any problems in vim 7.2.
109
110 Vi-compatible mode must be disabled.
111
112 ==============================================================================
113 4. Configuration *easymotion-configuration*
114
115 EasyMotion will work fine without any configuration, but you can override the
116 default behavior by setting configuration variables globally in your |vimrc|
117 file.
118
119 Example (this will change the target keys and disable shading): >
120
121 let g:EasyMotion_keys = '1234567890'
122 let g:EasyMotion_do_shade = 0
123
124 ------------------------------------------------------------------------------
125 4.1 EasyMotion_keys *EasyMotion_keys*
126
127 Set the keys which will be used for motion targets. Add as many keys as you
128 want. There's a lower chance that the motion targets will be grouped if many
129 keys are available.
130
131 Default: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
132
133 ------------------------------------------------------------------------------
134 4.2 EasyMotion_do_shade *EasyMotion_do_shade*
135
136 The default behavior is to shade the text following the cursor (forward
137 motions) or preceding the cursor (backward motions) to make the motion targets
138 more visible. Set this option to 0 if you want to disable text shading.
139
140 Default: 1
141
142 ------------------------------------------------------------------------------
143 4.3 EasyMotion_do_mapping *EasyMotion_do_mapping*
144
145 Set this option to 0 if you want to disable the default mappings. See
146 |easymotion-default-mappings| for details about the default mappings.
147
148 Note: If you disable this option, you'll have to map the motions yourself. See
149 the plugin source code for mapping details. You usually shouldn't need to do
150 this, see |easymotion-custom-mappings| for customizing the default mappings.
151
152 Default: 1
153
154 ------------------------------------------------------------------------------
155 4.4 EasyMotion_grouping *EasyMotion_grouping*
156
157 When there are too many possible targets on the screen, the results have to be
158 grouped. This configuration option lets you change which grouping algorithm
159 you want to use. There are two grouping algorithms available:
160
161 * Single-key priority (value: 1)
162 -------------------
163
164 This algorithm prioritizes single-key jumps for the targets closest to
165 the cursor and only groups the last jump targets to maximize the amount
166 of single-key jumps.
167
168 This algorithm works recursively and will work with as few keys as two.
169
170 Example (with |EasyMotion_keys| = "abcdef"): >
171
172 x x x x x x x x x
173 <
174 The |w| motion is triggered: >
175
176 a b c d e f f f f
177 ^ ^ ^ ^ ^ Direct jump to target
178 ^ ^ ^ ^ Enter group "f"
179 <
180 * Original (value: 2)
181 --------
182
183 This is the original algorithm which always groups all targets if there
184 are too many possible motion targets.
185
186 Example (with |EasyMotion_keys| = "abcdef"): >
187
188 x x x x x x x x x
189 <
190 The |w| motion is triggered: >
191
192 a a a a a a b b b
193 ^ ^ ^ ^ ^ ^ Enter group "a"
194 ^ ^ ^ Enter group "b"
195
196 Default: 1
197
198 ------------------------------------------------------------------------------
199 4.5 Custom highlighting *easymotion-custom-hl*
200
201 The default EasyMotion configuration uses two highlighting groups that link
202 to groups with default values. The highlighting groups are:
203
204 * EasyMotionTarget
205
206 Highlights motion targets, the default value is bold red
207
208 * EasyMotionShade
209
210 Highlights shaded text, the default value is dark gray
211
212 There are two ways to override the default colors:
213
214 1) Set the highlighting in your color scheme
215
216 This will only affect a single color scheme. The default red/gray colors
217 will be used if you change the color scheme to one that doesn't assign
218 any EasyMotion colors.
219
220 Example: >
221
222 hi EasyMotionTarget ctermbg=none ctermfg=green
223 hi EasyMotionShade ctermbg=none ctermfg=blue
224 <
225 2) Set the highlighting in your vimrc
226
227 This is ideal if you want to link the colors to highlighting groups that
228 are available in almost every color scheme, e.g. |ErrorMsg| (usually
229 bright red) and Comment (usually faded). You can be sure that the
230 color scheme's colors will be used instead of the default red/gray
231 if you choose this option.
232
233 Example: >
234
235 hi link EasyMotionTarget ErrorMsg
236 hi link EasyMotionShade Comment
237 <
238 ------------------------------------------------------------------------------
239 4.6 Custom mappings *easymotion-custom-mappings*
240
241 EasyMotion allows you to customize all default mappings to avoid conflicts
242 with existing mappings. It is possible to change the default leader key
243 of all mappings to another key or sequence. It is also possible to fine
244 tune the plugin to your need by changing every single sequence.
245
246 4.6.1 Leader key *EasyMotion_leader_key* *easymotion-leader-key*
247
248 The default leader key can be changed with the configuration option
249 |EasyMotion_leader_key|.
250
251 Set this option to the key sequence to use as the prefix of the mappings
252 described in |easymotion-default-mappings|.
253
254 Note: The default leader key has been changed to '<Leader><Leader>' to
255 avoid conflicts with other plugins. You can revert to the original
256 leader by setting this option in your vimrc: >
257
258 let g:EasyMotion_leader_key = '<Leader>'
259 <
260 Default: '<Leader><Leader>'
261
262 4.6.2 Custom Keys *easymotion-custom-keys*
263
264 All custom mappings follow the same variable format: >
265
266 EasyMotion_mapping_{motion} = {mapping}
267 <
268 Example: >
269
270 let g:EasyMotion_mapping_f = '_f'
271 let g:EasyMotion_mapping_T = '<C-T>'
272 <
273 See |easymotion-default-mappings| for a table of motions that can be mapped
274 and their default values.
275
276 Note: The leader key defined by |EasyMotion_leader_key| is not prepended to
277 your customized mappings! You have to provide full key sequences when setting
278 these options.
279
280 ==============================================================================
281 5. License *easymotion-license*
282
283 Creative Commons Attribution-ShareAlike 3.0 Unported
284
285 http://creativecommons.org/licenses/by-sa/3.0/
286
287 ==============================================================================
288 6. Known bugs *easymotion-known-bugs*
289
290 None.
291
292 ==============================================================================
293 7. Contributing *easymotion-contributing*
294
295 If you experience any bugs or have feature requests, please open an issue on
296 GitHub. Fork the source repository on GitHub and send a pull request if you
297 have any code improvements.
298
299 Author: Kim Silkebækken <kim.silkebaekken+vim@gmail.com>
300 Source repository: https://github.com/Lokaltog/vim-easymotion
301
302 ==============================================================================
303 8. Credits *easymotion-credits*
304
305 - Ben Boeckel: ge and WORD motions
306 - Drew Neil: operator-pending mappings
307 - Rob O'Dwyer: customizable mappings without giving up all defaults
308 - Michel D'Hooge: customizable leader
309 - Maxime Bourget: search motion, improved JK motion behavior
310 - Kearn Holliday: fix jumplist issues
311 - Shougo Matsushita: fix CSApprox issue
312
313 EasyMotion is based on Bartlomiej Podolak's great PreciseJump script, which
314 can be downloaded here:
315
316 http://www.vim.org/scripts/script.php?script_id=3437
317
318 ==============================================================================
319 vim:tw=78:sw=4:ts=8:ft=help:norl: