*vim-multiple-cursors.txt* True Sublime Text multiple selection in Vim

                    ____  _       __                                            
   ____ ___  __  __/ / /_(_)___  / /__     _______  ________________  __________
  / __ `__ \/ / / / / __/ / __ \/ / _ \   / ___/ / / / ___/ ___/ __ \/ ___/ ___/
 / / / / / / /_/ / / /_/ / /_/ / /  __/  / /__/ /_/ / /  (__  ) /_/ / /  (__  ) 
/_/ /_/ /_/\__,_/_/\__/_/ .___/_/\___/   \___/\__,_/_/  /____/\____/_/  /____/  
                       /_/                                                      


                              Reference Manual~


==============================================================================

CONTENTS                                            *multiple-cursors-contents*
    1.Intro...................................|multiple-cursors-intro|
    2.Usage...................................|multiple-cursors-usage|
    3.Mappings................................|multiple-cursors-mappings|
    4.Global Options..........................|multiple-cursors-global-options|
    5.Issues..................................|multiple-cursors-issues|
    6.Contributing............................|multiple-cursors-contributing|
    7.License.................................|multiple-cursors-license|
    8.Credit..................................|multiple-cursors-credit|
    9.References..............................|multiple-cursors-references|

==============================================================================
1. Intro                                              *multiple-cursors-intro*

There [1] have [2] been [3] many [4] attempts [5] at bringing Sublime Text's
awesome multiple selection [6] 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.

==============================================================================
2. Usage                                              *multiple-cursors-usage*

Out of the box, all you need to know is a single key CTRL-N. Pressing the key
in Normal mode highlights the current word under the cursor in Visual mode and
places a virtual cursor at the end of it. Pressing it again finds the next
ocurrence and places another virtual cursor at the end of the visual
selection. If you select multiple lines in Visual mode, pressing the key puts
a virtual cursor at every line and leaves you in Normal mode.

After you've marked all your locations with CTRL-N, you can change the visual
selection with normal Vim motion commands in Visual mode. You could go to
Normal mode by pressing v and wield your motion commands there. Single key
command to switch to Insert mode such as `c` or `s` from Visual mode or `i`,
`a`, `I`, `A` in Normal mode should work without any issues.

At any time, you can press <Esc> to exit back to regular Vim.

Two additional keys are also mapped:

CTRL-P in Visual mode will remove the current virtual cursor and go back to
the previous virtual cursor location. This is useful if you are trigger happy
with Ctrl-n and accidentally went too far.

CTRL-X in Visual mode will remove the current virtual cursor and skip to the
next virtual cursor location. This is useful if you don't want the current
selection to be a candidate to operate on later.

You can also add multiple cursors using a regular expression. The command
*MultipleCursorsFind* accepts a range and a pattern, and it will create a
virtual cursor at the end of every match within the range. If no range is
passed in, then it defaults to the entire buffer.

NOTE: If at any time you have lingering cursors on screen, you can press
CTRL-N in Normal mode and it will remove all prior cursors before starting a
new one.

==============================================================================
3. Mappings                                        *multiple-cursors-mappings* 

*g:multi_cursor_use_default_mapping* (Default: 1)

Out of the box, only the single key CTRL-N is mapped in regular Vim's Normal
mode and Visual mode to provide the functionality mentioned above. CTRL-N,
CTRL-P, CTRL-X, and <ESC> are mapped in the special multicursor mode once
you've added at least one virtual cursor to the buffer. If you don't like the
plugin taking over your favorite key bindings, you can turn off the default
with >

    let g:multi_cursor_use_default_mapping=0
<

*g:multi_cursor_next_key* (Default: '<C-n>')
*g:multi_cursor_prev_key* (Default: '<C-p>')
*g:multi_cursor_skip_key* (Default: '<C-x>')
*g:multi_cursor_quit_key* (Default: '<Esc>')
You can map the 'next', 'previous', 'skip', and 'exit' keys like the
following: >

    " Default mapping
    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>'
<

*g:multi_cursor_start_key* (Default: 'g:multi_cursor_next_key')
By default, the same key is used to enter multicursor mode as to select the
next cursor location.  If you want to use a different key to start multicursor
mode than for selecting the next location, do like the following: >

    " Map start key separately from next key
    let g:multi_cursor_start_key='<F6>'
<

IMPORTANT: Please note that currently only single keystroes and special
keys can be mapped. This contraint is also the reason why multikey commands
such as `ciw` do not work and cause unexpected behavior in Normal mode. This
means that a mapping like `<Leader>n` will NOT work correctly. For a list of
special keys that are supported, see |key-notation|

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.

NOTE: Prior to version 1.3, the recommended way to map the keys is using the
expressoin quote syntax in Vim, using something like `"\<C-n>"` or `"\<Esc>"`
(see h: expr-quote). After 1.3, the recommended way is to use a raw string
like above. If your key mappings don't appear to work, give the new syntax a
try.

==============================================================================
4. Global Options                            *multiple-cursors-global-options* 

Currently there're two additional global settings one can tweak:

*g:multi_cursor_exit_from_visual_mode* (Defaut: 1)

If set to 0, then pressing |g:multi_cursor_quit_key| in Visual mode will not
quit and delete all existing cursors. This is useful if you want to press
Escape and go back to Normal mode, and still be able to operate on all the
cursors.

*g:multi_cursor_exit_from_insert_mode* (Default: 1)

If set to 0, then pressing |g:multi_cursor_quit_key| in Insert mode will not
quit and delete all existing cursors. This is useful if you want to press
Escape and go back to Normal mode, and still be able to operate on all the
cursors.

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
<

==============================================================================
5. Issues                                            *multiple-cursors-issues* 

- Multi key commands like ciw do not work at the moment
- All user input typed before Vim is able to fan out the last operation to all
  cursors is lost. This is a implementation decision to keep the input
  perfectly synced in all locations, at the cost of potentially losing user
  input.
- Performance in terminal vim degrades significantly with more cursors
- Select mode is not implemented

==============================================================================
6. Contributing                                *multiple-cursors-contributing* 

The project is hosted on Github. Patches, feature requests and suggestions are
always welcome!

Find the latest version of the plugin here:
    http://github.com/terryma/vim-multiple-cursors

==============================================================================
7. License                                          *multiple-cursors-license* 

The project is licensed under the MIT license [7]. Copyrigth 2013 Terry Ma

==============================================================================
8. Credit                                            *multiple-cursors-credit* 

The plugin is obviously inspired by Sublime Text's awesome multiple selection
[6] feature. Some inspiration was also taken from Emac's multiple cursors [8]
implementation. 

==============================================================================
9. References                                    *multiple-cursors-references* 

[1] https://github.com/paradigm/vim-multicursor
[2] https://github.com/felixr/vim-multiedit
[3] https://github.com/hlissner/vim-multiedit
[4] https://github.com/adinapoli/vim-markmultiple
[5] https://github.com/AndrewRadev/multichange.vim
[6] http://www.sublimetext.com/docs/2/multiple_selection_with_the_keyboard.html
[7] http://opensource.org/licenses/MIT
[8] https://github.com/magnars/multiple-cursors.el

 vim:tw=78:sw=4:ft=help:norl: