git.r.bdr.sh - rbdr/dotfiles/blob - 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: