3

I see the following common pattern in the beginning of vim plugins (where NAME is a placeholder for some plugin identifier):

if exists("g:loaded_NAME")
  finish
endif

let g:loaded_NAME = 1

For example: https://github.com/tpope/vim-eunuch/blob/75efe06ccc63b7cd50b193b99cce83e3ad3e60cb/plugin/eunuch.vim#L5-L8

Presumably this type of guard is intended to prevent the script from executing multiple times. I am curious why such a guard is necessary. In what scenarios would a plugin load multiple times?

6

It allows the user to disable a specific plugin. See :h use-cpo-save, and search for NOT LOADING:

NOT LOADING

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")
7   finish
8 endif
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 added twice.

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 function).

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/. Suppose autoload/someplugin.vim contains the function someplugin#func(). You call the function, which causes autoload/someplugin.vim to be sourced. Now you call it a second time, but you make a typo:

:call someplugin#funx()
                    ^
                    ✘

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 loaded_ (see vim-fugitive for an example) for files under autoload/.


Setting the 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.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.