1
0
Fork 0
mirror of synced 2024-11-16 14:05:34 -05:00
ultimate-vim/sources_non_forked/vim-multiple-cursors/README.md

232 lines
9.7 KiB
Markdown
Raw Normal View History

2016-02-20 08:13:10 -05:00
# vim-multiple-cursors
[![Build Status](https://travis-ci.org/terryma/vim-multiple-cursors.svg)](https://travis-ci.org/terryma/vim-multiple-cursors)
[![Issue Stats](http://issuestats.com/github/terryma/vim-multiple-cursors/badge/pr?style=flat)](http://issuestats.com/github/terryma/vim-multiple-cursors)
[![Issue Stats](http://issuestats.com/github/terryma/vim-multiple-cursors/badge/issue?style=flat)](http://issuestats.com/github/terryma/vim-multiple-cursors)
2018-06-14 06:31:12 -04:00
2015-07-13 06:22:46 -04:00
## Contents
- [About](#about)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Mapping](#mapping)
- [Settings](#settings)
- [Interactions with other plugins](#interactions-with-other-plugins)
- [Highlight](#highlight)
2018-06-14 06:31:12 -04:00
- [FAQ](#faq)
2015-07-13 06:22:46 -04:00
- [Contributing](#contributing)
2016-01-05 13:18:45 -05:00
- [Credit](#credit)
2015-07-13 06:22:46 -04:00
## About
[There](https://github.com/paradigm/vim-multicursor) [have](https://github.com/felixr/vim-multiedit) [been](https://github.com/hlissner/vim-multiedit) [many](https://github.com/adinapoli/vim-markmultiple) [attempts](https://github.com/AndrewRadev/multichange.vim) at bringing Sublime Text's awesome [multiple selection][sublime-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
![Example1](assets/example1.gif?raw=true)
2018-06-14 06:31:12 -04:00
Vim command sequence: `fp<C-n><C-n><C-n>cname`
2015-12-08 08:20:04 -05:00
### Add a cursor to each line of your visual selection
![Example2](assets/example2.gif?raw=true)
2018-06-14 06:31:12 -04:00
Vim command sequence: `vip<C-n>i"<Right><Right><Right>",<Esc>vipgJ$r]Idays = [`
2015-12-08 08:20:04 -05:00
2018-06-14 06:31:12 -04:00
### Match characters from visual selection
![Example3](assets/example3.gif?raw=true)
2018-06-14 06:31:12 -04:00
Vim command sequence: `df[$r,0f,v<C-n>…<C-n>c<CR><Up><Del><Right><Right><Right><Del>`
2015-12-08 08:20:04 -05:00
2018-06-14 06:31:12 -04:00
### Use the command to match regexp
2013-04-26 12:17:22 -04:00
![Example4](assets/example4.gif?raw=true)
2016-02-20 08:13:10 -05:00
To see what keystrokes are used for the above examples, see [the wiki page](https://github.com/terryma/vim-multiple-cursors/wiki/Keystrokes-for-example-gifs).
2013-04-26 12:17:22 -04:00
## Installation
2018-07-19 08:52:53 -04:00
Install using [Pathogen], [Vundle], [Neobundle], [vim-plug], or your favorite Vim package manager.
2018-06-14 06:31:12 -04:00
2018-07-19 08:52:53 -04:00
Requires vim 7.4 or newer for full functionality.
### vim-plug instructions
1. Paste this block into the top of `~/.vimrc`.
```vim script
call plug#begin()
Plug 'terryma/vim-multiple-cursors'
call plug#end()
```
2. Start vim and execute `:PlugInstall`.
## Quick Start
2018-06-14 06:31:12 -04:00
### 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
* select all: `<A-n>` start muticursor and directly select all matches
2018-06-14 06:31:12 -04:00
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.
2018-06-14 06:31:12 -04:00
**NOTE**: start with `g<C-n>` to match without boundaries (behaves like `g*` instead of `*`)
2018-06-14 06:31:12 -04:00
### 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.
2013-04-26 12:17:22 -04:00
## Mapping
2018-06-14 06:31:12 -04:00
If you don't like the plugin taking over your key bindings, you can turn it off and reassign them the way you want:
2015-07-13 06:22:46 -04:00
```viml
let g:multi_cursor_use_default_mapping=0
" Default mapping
2018-06-14 06:31:12 -04:00
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>'
2015-01-18 07:58:28 -05:00
```
2013-04-26 12:17:22 -04:00
**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.
2015-07-13 06:22:46 -04:00
## Settings
2015-02-24 05:45:22 -05:00
Currently there are four additional global settings one can tweak:
2015-02-24 05:45:22 -05:00
### ```g:multi_cursor_exit_from_visual_mode``` (Default: 1)
2018-06-14 06:31:12 -04:00
If set to 0, then pressing `g:multi_cursor_quit_key` in _Visual_ mode will not quit and delete all existing cursors.
Useful if you want to go back to Normal mode, and still be able to operate on all the cursors.
### ```g:multi_cursor_exit_from_insert_mode``` (Default: 1)
2018-06-14 06:31:12 -04:00
If set to 0, then pressing `g:multi_cursor_quit_key` in _Insert_ mode will not quit and delete all existing cursors.
Useful if you want to go back to Normal mode, and still be able to operate on all the cursors.
2015-07-13 06:22:46 -04:00
### ```g:multi_cursor_normal_maps``` (Default: see below)
2018-06-14 06:31:12 -04:00
`{'@': 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}`
2015-07-13 06:22:46 -04:00
2015-01-18 07:58:28 -05:00
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
2018-06-14 06:31:12 -04:00
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.
2016-01-05 13:18:45 -05:00
2015-07-13 06:22:46 -04:00
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.
2015-01-18 07:58:28 -05:00
2018-06-14 06:31:12 -04:00
### ```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`
2015-01-18 07:58:28 -05:00
### Interactions with other plugins
### ```Multiple_cursors_before/Multiple_cursors_after``` (Default: `nothing`)
2018-06-14 06:31:12 -04:00
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:
2015-01-18 07:58:28 -05:00
For example, if you are using [Neocomplete](https://github.com/Shougo/neocomplete.vim),
add this to your vimrc to prevent conflict:
2015-07-13 06:22:46 -04:00
```viml
2015-01-18 07:58:28 -05:00
function! Multiple_cursors_before()
if exists(':NeoCompleteLock')==2
exe 'NeoCompleteLock'
endif
endfunction
function! Multiple_cursors_after()
if exists(':NeoCompleteUnlock')==2
exe 'NeoCompleteUnlock'
endif
endfunction
```
2017-05-02 08:42:08 -04:00
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:
2015-07-13 06:22:46 -04:00
```viml
" 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
```
2015-07-13 06:22:46 -04:00
## FAQ
2018-06-14 06:31:12 -04:00
#### **Q** <kbd>ALT</kbd>+<kbd>n</kbd> doesn't seem to work in VIM but works in gVIM, why?
**A** This is a well known terminal/Vim [issue](http://vim.wikia.com/wiki/Get_Alt_key_to_work_in_terminal), different terminal have different ways to send ```Alt+key```.
Try adding this in your `.vimrc` and **make sure to replace the string**:
```vim
if !has('gui_running')
map "in Insert mode, type Ctrl+v Alt+n here" <A-n>
endif
```
Or remap the following:
```vim
g:multi_cursor_start_key
g:multi_cursor_select_all_key
```
2015-07-13 06:22:46 -04:00
2018-06-14 06:31:12 -04:00
#### **Q** <kbd>CTRL</kbd>+<kbd>n</kbd> doesn't seem to work in gVIM?
2015-07-13 06:22:46 -04:00
**A** Try setting `set selection=inclusive` in your `~/.gvimrc`
2018-06-14 06:31:12 -04:00
#### **Q** is it also working on Mac?
**A** On Mac OS, [MacVim](https://code.google.com/p/macvim/) is known to work.
2016-06-11 09:56:50 -04:00
2018-06-14 06:31:12 -04:00
#### **Q** How can I select `n` keywords with several keystrokes? `200<C-n>` does not work.
2016-06-11 09:56:50 -04:00
**A** You can use :MultipleCursorsFind keyword. I have this binding in my vimrc:
```VimL
nnoremap <silent> <M-j> :MultipleCursorsFind <C-R>/<CR>
vnoremap <silent> <M-j> :MultipleCursorsFind <C-R>/<CR>
```
2018-06-14 06:31:12 -04:00
This allows one to search for the keyword using `*` and turn search results into cursors with `Alt-j`.
2016-06-11 09:56:50 -04:00
2013-04-26 12:17:22 -04:00
2018-06-14 06:31:12 -04:00
## Contributing
Patches and suggestions are always welcome! A list of open feature requests can be found [here](https://github.com/terryma/vim-multiple-cursors/labels/pull%20request%20welcome).
2016-02-20 08:13:10 -05:00
2018-06-14 06:31:12 -04:00
### Issue Creation
Contributor's time is precious and limited. Please ensure it meets the requirements outlined in [CONTRIBUTING.md](CONTRIBUTING.md).
2018-06-14 06:31:12 -04:00
### 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:
```bash
cd vim-multiple-cursors/spec/
bundle exec rake
```
2018-06-14 06:31:12 -04:00
### Contributors
This is a community supported project. Here is the list of all the [Contributors](https://github.com/terryma/vim-multiple-cursors/graphs/contributors)
2015-02-24 05:45:22 -05:00
## Credit
2015-02-24 05:45:22 -05:00
Obviously inspired by Sublime Text's [multiple selection][sublime-multiple-selection] feature, also encouraged by Emac's [multiple cursors][emacs-multiple-cursors] implementation by Magnar Sveen
[vim-multiple-cursors]:http://github.com/terryma/vim-multiple-cursors
[sublime-multiple-selection]:http://www.sublimetext.com/docs/2/multiple_selection_with_the_keyboard.html
[Pathogen]:http://github.com/tpope/vim-pathogen
[Vundle]:http://github.com/gmarik/vundle
[Neobundle]:http://github.com/Shougo/neobundle.vim
2018-07-19 08:52:53 -04:00
[vim-plug]:https://github.com/junegunn/vim-plug
[emacs-multiple-cursors]:https://github.com/magnars/multiple-cursors.el