What does <Plug> do in vim?

Question

I came across <Plug> in this command of easy-motion

nmap <Leader>w <Plug>(easymotion-overwin-w)

I tried to search for the definition of but no luck. What does it mean?

Does it have anything related with sourcing init.vim(I am using nvim)? I am asking because I found this mapping won't work initially, and I have to source $MYVIMRC manaually to make it work.

Answer 1

This is used by plugin authors to make complex mappings available to the user. In a plugin code you define a mapping with <plug>... which is not a real key sequence but which can be used as a right hand side expression in a mapping by your users.

As an example take this line of code from vim-subversive:

nnoremap <silent> <plug>(SubversiveSubstitute) :<c-u>call subversive#singleMotion#preSubstitute(v:register, 0, '')<cr>:set opfunc=subversive#singleMotion#substituteMotion<cr>g@

The right hand side calls the plugin functions and a bunch of other vim commands to change a text object without modifying the unnamed register. The author wanted to let the user decide which key should execute this action. Also they don't want to decide on a particular key sequence as it could have already been used by another plugin. In the doc they could have said to use:

nnoremap <silent> <your-favorite-key> :<c-u>call subversive#singleMotion#preSubstitute(v:register, 0, '')<cr>:set opfunc=subversive#singleMotion#substituteMotion<cr>g@

And that would have worked but the users would have to copy this long command in their vimrc, it's not convenient or easy to read.

So instead the users created the mapping with <plug>(SubversiveSubstitute) which means that you can use this expression as the right hand side of a mapping now. In their config users can simply add:

nmap gc <plug>(SubversiveSubstitute)

To remap gc to the long expression.

Note that here the user had to create a recursive mapping, otherwise <plug>(SubserviceSubstitute) is interpreted as a built-in list of command which will fail.

The help :h using-<Plug> does a great job at describing how this feature works.

Answer 2

<plug> mappings are meant as customization points. Not everyone will want to use the same shortcut/keybinding as the one chosen by the author of a plugin.

That's where <plug> mappings come in handy. The plugin author can provide a default keybinding (for a given feature of his/her plugin) and still permit end users of the plugin to use another keybinding (for personal taste or to avoid name collisions).

The line you've shown us is typical of what an end-user will put in his/her .vimrc to override the plugin default shortcut associated to <Plug>(easymotion-overwin-w) -- in a plugin this line would have been protected by at least a test on hasmapto('<Plug>(easymotion-overwin-w)').

The old vim tip on wikia(/fandom now) may explain it in better terms: Mapping keys in Vim - Tutorial (Part 3)

Now regarding why it doesn't work in our case. Well, 3 things:

1. first as you are using <leader> you'll need to set the leader key before the mapping is defined
2. the mapping needs to be defined -- if it's in your .vimrc or equivalent (init.vim), it should be automatical. Check :scriptname in doubt.
3. the plugin, the plug-mapping refers to, needs to be loaded