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.
:h <Plug>
? How do I navigate to topics in Vim's documentation?