*vm-troubleshooting.txt*    Version 0.3.0    Last change: June 13 2019

Known issues                                            |vm-bugs|
Plugins compatibility                                   |vm-compatibility|



TROUBLESHOOTING                                           *vm-troubleshooting*
===============================================================================

First stop for troubleshooting is |vm-faq|.





KNOWN ISSUES                                                         *vm-bugs*
==============================================================================

VM relies mostly on autocommands, especially in insert mode. Plugins and
autocommands defined by the user could cause issues, if they do something
intrusive while VM is updating text. Snippets plugins won't work for this
reason, but |abbreviations| work. For example this won't work either:
>
  au InsertLeave * silent! update
<                                                             *b:visual_multi*
In this case you may want to check that VM is not active, before performing an
action, you could write it as:
>
  au InsertLeave * if !exists('b:visual_multi') | silent! update | endif
<
                         {https://github.com/mg979/vim-visual-multi/issues/91}

------------------------------------------------------------------------------
                                                           *vm-autocompletion*

Some autocompletion plugins can cause trouble if the active cursor is not the
first cursor in the line. In this case this can help:
>
  let g:VM_use_first_cursor_in_line = 1


------------------------------------------------------------------------------

In |vm-single-region| mode, some insert mode mappings (<C-w>, <C-u>, <CR>) are
disabled because they don't behave well. <BS> and <Del> are not disabled, but
they cause issues when deleting other cursors, so be careful. They are not
disabled because it shouldn't happen in normal use cases for this feature, that
should be used when you want to use cursors as 'fields' to edit sequentially.





PLUGINS COMPATIBILITY                                       *vm-compatibility*
==============================================================================

As mentioned above, snippets plugins cannot work with VM. Other plugins can
have incompatibilities, especially if they apply buffer mappings. In this
case, VM will not replace the conflicting keys, but this can result in missing
VM functionalities or even render VM unusable. If you notice some mappings
don't work in VM, run |:VMDebug| to see if a plugin is the cause.

However, VM will always overwrite insert mode mappings. If this happens, you
can also read it in the |:VMDebug| output. In this case, it's not VM that
breaks, it's the conflicting plugin.

Some plugins have built-in compatibility:

  - jiangmiao/auto-pairs
  - AndrewRadev/tagalong.vim
  - dyng/ctrlsf.vim
  - Shougo/deoplete.nvim
  - ncmw/ncm2

If you want to run some code before/after VM starts/exits, see
|vm-faq-functions|.

If you make a plugin and want to test if VM is active, perform a check on the
|b:visual_multi| variable.

If a plugin needs to be deactivated inside VM, you could also use the
|g:VM_plugins_compatibilty| dictionary, with this structure:
>
  let g:VM_plugins_compatibilty = {
            \'plugin_name': {
            \   'test': { -> exists('plugin_is_enabled') },
            \   'enable': ':PluginEnableCommand',
            \   'disable': ':PluginDisableCommand'},
            \}
<
If you would like a plugin to have built-in compatibility, open an issue about
it on the VM GitHub repo and/or make a pull request.




 vim: ft=help et sw=2 ts=2 sts=2 tw=78
