11 KiB
vim-multiple-cursors
Contents
- About
- Installation
- Quick Start
- Mapping
- Settings
- Interactions with other plugins
- Highlight
- FAQ
- Contributing
- Credit
About
There have been many attempts at bringing Sublime Text's awesome multiple selection feature into Vim, but none so far have been in my opinion a faithful port that is simplistic to use, yet powerful and intuitive enough for an existing Vim user. vim-multiple-cursors is yet another attempt at that.
It's great for quick refactoring
Vim command sequence: fp<C-n><C-n><C-n>cname
Add a cursor to each line of your visual selection
Vim command sequence: vip<C-n>i"<Right><Right><Right>",<Esc>vipgJ$r]Idays = [
Match characters from visual selection
Vim command sequence: df[$r,0f,v<C-n>…<C-n>c<CR><Up><Del><Right><Right><Right><Del>
Use the command to match regexp
To see what keystrokes are used for the above examples, see the wiki page.
Installation
Install using Pathogen, Vundle, Neobundle, vim-plug, or your favorite Vim package manager.
Requires vim 7.4 or newer for full functionality.
vim-plug instructions
- Paste this block into the top of
~/.vimrc.
call plug#begin()
Plug 'terryma/vim-multiple-cursors'
call plug#end()
- Start vim and execute
:PlugInstall.
Quick Start
normal mode / visual mode
- start:
<C-n>start multicursor and add a virtual cursor + selection on the match- next:
<C-n>add a new virtual cursor + selection on the next match - skip:
<C-x>skip the next match - prev:
<C-p>remove current virtual cursor + selection and go back on previous match
- next:
- select all:
<A-n>start multicursor and directly select all matches
You can now change the virtual cursors + selection with visual mode commands.
For instance: c, s, I, A work without any issues.
You could also go to normal mode by pressing v and use normal commands there.
At any time, you can press <Esc> to exit back to regular Vim.
NOTE: start with g<C-n> to match without boundaries (behaves like g* instead of *)
visual mode when multiple lines are selected
- start:
<C-n>add virtual cursors on each line
You can now change the virtual cursors with normal mode commands.
For instance: ciw.
command
The command MultipleCursorsFind accepts a range and a pattern (regexp), it creates a visual cursor at the end of each match.
If no range is passed in, then it defaults to the entire buffer.
Mapping
If you don't like the plugin taking over your key bindings, you can turn it off and reassign them the way you want:
let g:multi_cursor_use_default_mapping=0
" Default mapping
let g:multi_cursor_start_word_key = '<C-n>'
let g:multi_cursor_select_all_word_key = '<A-n>'
let g:multi_cursor_start_key = 'g<C-n>'
let g:multi_cursor_select_all_key = 'g<A-n>'
let g:multi_cursor_next_key = '<C-n>'
let g:multi_cursor_prev_key = '<C-p>'
let g:multi_cursor_skip_key = '<C-x>'
let g:multi_cursor_quit_key = '<Esc>'
NOTE: Please make sure to always map something to g:multi_cursor_quit_key, otherwise you'll have a tough time quitting from multicursor mode.
Settings
Currently there are four additional global settings one can tweak:
g:multi_cursor_support_imap (Default: 1)
If set to 0, insert mappings won't be supported in Insert mode anymore.
g:multi_cursor_exit_from_visual_mode (Default: 0)
If set to 1, then pressing g:multi_cursor_quit_key in Visual mode will quit and
delete all existing cursors, just skipping normal mode with multiple cursors.
g:multi_cursor_exit_from_insert_mode (Default: 0)
If set to 1, then pressing g:multi_cursor_quit_key in Insert mode will quit and
delete all existing cursors, just skipping normal mode with multiple cursors.
g:multi_cursor_normal_maps (Default: see below)
{'@': 1, 'F': 1, 'T': 1, '[': 1, '\': 1, ']': 1, '!': 1, '"': 1, 'c': 1, 'd': 1, 'f': 1, 'g': 1, 'm': 1, 'q': 1, 'r': 1, 't': 1, 'y': 1, 'z': 1, '<': 1, '=': 1, '>': 1}
Any key in this map (values are ignored) will cause multi-cursor Normal mode
to pause for map completion just like normal vim. Otherwise keys mapped in
normal mode will "fail to replay" when multiple cursors are active.
For example: {'d':1} makes normal-mode command dw work in multi-cursor mode.
The default list contents should work for anybody, unless they have remapped a key from an operator-pending command to a non-operator-pending command or vice versa.
These keys must be manually listed because vim doesn't provide a way to
automatically see which keys start mappings, and trying to run motion commands
such as j as if they were operator-pending commands can break things.
g:multi_cursor_visual_maps (Default: see below)
{'T': 1, 'a': 1, 't': 1, 'F': 1, 'f': 1, 'i': 1}
Same principle as g:multi_cursor_normal_maps
Interactions with other plugins
Multiple_cursors_before/Multiple_cursors_after (Default: nothing)
Other plugins may be incompatible in insert mode. That is why we provide hooks to disable those plug-ins when vim-multiple-cursors is active:
For example, if you are using Neocomplete, add this to your vimrc to prevent conflict:
function! Multiple_cursors_before()
if exists(':NeoCompleteLock')==2
exe 'NeoCompleteLock'
endif
endfunction
function! Multiple_cursors_after()
if exists(':NeoCompleteUnlock')==2
exe 'NeoCompleteUnlock'
endif
endfunction
Plugins themselves can register User autocommands on MultipleCursorsPre and
MultipleCursorsPost for automatic integration.
Highlight
The plugin uses the highlight group multiple_cursors_cursor and multiple_cursors_visual to highlight the virtual cursors and their visual selections respectively. You can customize them by putting something similar like the following in your vimrc:
" Default highlighting (see help :highlight and help :highlight-link)
highlight multiple_cursors_cursor term=reverse cterm=reverse gui=reverse
highlight link multiple_cursors_visual Visual
FAQ
Q Pressing i after selecting words with C-n makes the plugin hang, why?
A When selecting words with C-n, the plugin behaves like in visual mode. Once you pressed i, you can still press I to insert text.
Q ALT+n doesn't seem to work in VIM but works in gVIM, why?
A This is a well known terminal/Vim issue, different terminal have different ways to send Alt+key.
Try adding this in your .vimrc and make sure to replace the string:
if !has('gui_running')
map "in Insert mode, type Ctrl+v Alt+n here" <A-n>
endif
Or remap the following:
g:multi_cursor_start_key
g:multi_cursor_select_all_key
Q CTRL+n doesn't seem to work in gVIM?
A Try setting set selection=inclusive in your ~/.gvimrc
A Alternatively, you can just temporarily disable exclusive selection whenever the plugin is active:
augroup MultipleCursorsSelectionFix
autocmd User MultipleCursorsPre if &selection ==# 'exclusive' | let g:multi_cursor_save_selection = &selection | set selection=inclusive | endif
autocmd User MultipleCursorsPost if exists('g:multi_cursor_save_selection') | let &selection = g:multi_cursor_save_selection | unlet g:multi_cursor_save_selection | endif
augroup END
Q deoplete insert giberrish, how to fix this?
A use the Multiple_cursors functions, add this in your vimrc:
func! Multiple_cursors_before()
if deoplete#is_enabled()
call deoplete#disable()
let g:deoplete_is_enable_before_multi_cursors = 1
else
let g:deoplete_is_enable_before_multi_cursors = 0
endif
endfunc
func! Multiple_cursors_after()
if g:deoplete_is_enable_before_multi_cursors
call deoplete#enable()
endif
endfunc
Q is it also working on Mac?
A On Mac OS, MacVim is known to work.
Q How can I select n keywords with several keystrokes? 200<C-n> does not work.
A You can use :MultipleCursorsFind keyword. I have this binding in my vimrc:
nnoremap <silent> <M-j> :MultipleCursorsFind <C-R>/<CR>
vnoremap <silent> <M-j> :MultipleCursorsFind <C-R>/<CR>
This allows one to search for the keyword using * and turn search results into cursors with Alt-j.
Contributing
Patches and suggestions are always welcome! A list of open feature requests can be found here.
Issue Creation
Contributor's time is precious and limited. Please ensure it meets the requirements outlined in CONTRIBUTING.md.
Pull Requests
Running the test suite requires ruby and rake as well as vim of course. Before submitting PR, please ensure the checks are passing:
cd vim-multiple-cursors/spec/
bundle exec rake
Contributors
This is a community supported project. Here is the list of all the Contributors
Credit
Obviously inspired by Sublime Text's multiple selection feature, also encouraged by Emac's multiple cursors implementation by Magnar Sveen