It allows the user to disable a specific plugin.
:h use-cpo-save, and search for
It's possible that a user doesn't always want to load this plugin. Or the
system administrator has dropped it in the system-wide plugin directory, but a
user has his own plugin he wants to use. Then the user must have a chance to
disable loading this specific plugin. This will make it possible:
6 if exists("g:loaded_typecorr")
9 let g:loaded_typecorr = 1
This also avoids that when the script is loaded twice it would cause error
messages for redefining functions and cause trouble for autocommands that are
The name is recommended to start with "loaded_" and then the file name of the
plugin, literally. The "g:" is prepended just to avoid mistakes when using
the variable in a function (without "g:" it would be a variable local to the
Using "finish" stops Vim from reading the rest of the file, it's much quicker
than using if-endif around the whole file.
It's also useful if you want to use a custom version of a default plugin.
By placing your custom version in a directory of the runtime path which comes before the one of the default plugin, yours will be sourced first (and set
g:loaded_...); and when the default plugin will be sourced, the guard will prevent its interface from being installed and overwriting yours.
It can also be useful in a file under
autoload/someplugin.vim contains the function
You call the function, which causes
autoload/someplugin.vim to be sourced.
Now you call it a second time, but you make a typo:
The function won't be found and
E117 will be raised; but – without a guard –
autoload/someplugin.vim will have been sourced a second time. This can cause an issue if the script tracks some state via a global or script-local variable which is initialized outside a function then updated at runtime; the state will be reset which may lead to all sorts of unexpected behaviors.
To make sure not to clash with a
g:loaded_ variable, you can use the prefix
autoloaded_ instead of
vim-fugitive for an example) for files under
g:loaded_ variable allows you to inspect whether the plugin has been loaded.
As an example, I use this info to avoid configuring the plugin when it's temporarily disabled (e.g. with
vim-matchup and with
vim-sandwich), typically when debugging some issue.