42

I understand it's the place to put things that should have the final say and not be overridden by another source, but I'm unclear on how to decide when to put something in, say, ~/.vim/after/ftplugin/ rather than ~/.vim/ftplugin/.

Do people generally use ~/.vim/ftplugin/ and only move stuff into ~/.vim/after/ftplugin/ if they observe unwanted behavior, or do they just put it all in the after-directory right away?

ivan
  • 1,450
  • 1
  • 11
  • 16

3 Answers3

52

Generally, if you want to add your own plugin, or replace a standard plugin with your own, it would go into ~/.vim/plugin or ~/.vim/ftplugin. If instead you want to keep the functionality of an existing plugin but add to it, or change just a few settings made by it, then your plugin would go into ~/.vim/after/plugin or ~/.vim/after/ftplugin.

garyjohn
  • 6,309
  • 20
  • 21
  • For some reason I always assumed Vim searched the runtimepath and sourced each file that matched the search criteria, rather than just sourcing the first match it found. It kind of sounds like stuff in the after-directory gets that kind of "in-addition-to" treatment, but maybe everything else gets treated more like the Unix PATH variable, where the first match wins? – ivan Jun 27 '17 at 02:07
  • 7
    Vim does source each file that matches the search criteria, but properly-written plugins have a test near their top of the form, if exists("g:loaded_<plugin name>") finish endif let g:loaded_<plugin name> = 1. The plugin that's loaded first "wins" and subsequent plugins of the same name exit early through the finish command. That's how a plugin in your ~/.vim/plugin directory, for example, can prevent a plugin in $VIMRUNTIME/plugin from loading completely. That test is not included in after plugin files. – garyjohn Jun 27 '17 at 05:22
  • Ok, I think I get it now. Since all matching files will be sourced, use a finish guard-clause when you want to load only the first match, and use the after-directory (without a finish guard-clause) when you need to override a setting that's affected by one of the other sources. – ivan Jun 27 '17 at 12:12
  • @garyjohn Forgive me for resurrecting a several-year-old chat, but I don't seem get it. What if I put my override in ~/.vim/ftplugin, but without a guard-clause? What's the point in ~/.vim/after/ftplugin then? – intelfx Jun 03 '23 at 13:01
  • @intelfx: If your plugin adds to or changes some option set by the existing plugin, yours has to go into ~/.vim/after/ftplugin so that it has the last say. If the options set by your plugin are not affected by the existing plugin, you could put yours into either directory. – garyjohn Jun 04 '23 at 14:57
3

if vanilla vim recognizes a certain filetype and you want to modify the shipped behavior then your own settings go into ~/.vim/after/ftplugin/

Naumann
  • 2,759
  • 1
  • 11
  • 16
0

garyjohn's anwser is very helpful, and I just add a little advise here on the basic of his great one.

If anyone is trying to add a ftplugin file xx.vim in ~/.vim/after/ftplugin/, then must don't include the original part from the system built-in xx.vim, e.g. from /usr/share/vim/vim82/ftplugin. Because the system one include:

if exists("b:did_ftplugin")
  finish
endif

also because vim should read the system ftplugin then read your after/ftplugin, hence this if exists("b:did_ftplugin") will be true and any below confi will be passed.

I know most people will not have this error. Just add in here in case any people as dumb as me and take long to figure out why my ftplugin not sourced :>

qili fang
  • 1
  • It's still a good idea to add the same kind of guard but with a different variable like b:did_ftplugin_custom to avoid running your custom ftplugin in case the filetype is reset. – statox Jun 18 '21 at 18:25
  • 1
    @statox isn't that only true if you don't update b:undo_ftplugin? If you set it relentlessly like I do, I don't see why that would be an issue – D. Ben Knoble Jun 18 '21 at 19:04