-
-
Save nelstrom/1056049 to your computer and use it in GitHub Desktop.
plugin | |
naming convention: name_of_plugin.vim | |
these files are sourced for all file types | |
doc | |
naming convention: name_of_plugin.vim | |
these files document the functionality of a plugin | |
color | |
naming convention: name_of_colorscheme.vim | |
these files define a colorscheme for syntax highlighting | |
syntax | |
naming convention: filetype.vim | |
these files define the operators, keywords and constructs of a language | |
the syntax groups defined here are used by the colorscheme | |
(much like HTML elements, ids and classes provide hooks for CSS styling) | |
indent | |
naming convention: filetype.vim | |
these files define the `indentexpr` for a language | |
the `indentexpr` is used by the `=`, `o` and `O` commands | |
ftplugin | |
naming convention: filetype.vim | |
these files are sourced only for the specified filetype | |
suitable for defining functionality for one particular language | |
e.g. a command to build an HTML document from a markdown source | |
autoload | |
naming convention: ???.vim | |
Vim provides a mechanism to ensure that startup time isn't compromised | |
when large scripts are loaded. Functions, commands and mappings defined | |
in the autoload directory are defined with an empty implementation on | |
startup. It is only when these commands are invoked by the user that the | |
script is sourced in full, and each command is attached to its | |
implementation. | |
:help autoload-functions | |
:help 41.14 |
Yes, the folders really do matter.
You could just put everything into your vimrc, but then it would get huge. Eventually, you might decide to refactor it, moving common parts of functionality into a file in the .vim/plugins
directory. Then you could publish it, and other people would be able to install your plugin, use it, and perhaps submit patches to improve it.
But once you start sharing your plugins, you probably want to write documentation to help other people to use it properly. If you create a plain text file in the .vim/doc
directory, then it will automatically be added to Vim's built in help system. If you mark up your documentation with the appropriate symbols, then users will be able to run :help plugin_name
to open the relevant documentation file.
Suppose that you want to add some functionality that will only apply to a particular set of files. For example, a command that compiles markdown source files, generating an HTML document. You could create such a command in your vimrc (or a plugin file), and use an autocommand to only create the appropriate mapping for particular filetypes. This is fine for simple commands, but suppose that you have a whole suite of functions that work together on a particular filetype. The syntax for defining autocommands is ugly, and your code would quickly get unmaintainable. In this case, it would make more sense to break the functions out from a global plugin (or your vimrc file) and put them in a filetype plugin instead.
The same goes for syntax and indent files. You could (I suppose) implement these in the .vim/plugin
directory, and use autocommands to only apply your functions to a particular filetype. But it would be neater to simply use the appropriate folder, and have Vim look up the syntax and indent files for each filetype on demand.
What's the point of pathogen? It's difficult to describe if you aren't familiar with the traditional way of managing Vim's plugins. Suppose you want to install two plugins that look like this:
apples/
plugin/apples.vim
doc/apples.txt
oranges/
autoload/oranges.vim
plugin/oranges.vim
doc/oranges.txt
The traditional way of installing Vim plugins is to copy these files into your .vim
directory in the following places:
~/.vim/
autoload/
oranges.vim
doc/
apples.txt
oranges.txt
plugin/
apples.vim
oranges.vim
That looks neat enough. But as you install more plugins, it becomes harder to keep track of what goes where. If you decide you want to uninstall a plugin, you have to hunt down each of the individual files and delete them. Upgrading a plugin is an even bigger PITA. In this example, all of the files from each plugin are named consistently, so they obviously belong together. But some plugins don't follow consistent naming conventions.
With pathogen, all of the files for a plugin are kept in a directory together. If you wanted to load the same two plugins, you would just add them in their entirety to the .vim/bundle
directory, like this:
~/.vim/
bundle/
apples/
plugin/apples.vim
doc/apples.txt
oranges/
autoload/oranges.vim
plugin/oranges.vim
doc/oranges.txt
If you decide to uninstall a plugin, you can just nuke the entire directory. If you want to upgrade, just cd
to the root of the plugin, and run git pull
.
That's super helpful! Thanks!! I'd love to see this linked to on vimcasts!
That's super helpful! Thanks!! I'd love to see this linked to on vimcasts!
Glad it helped. You're right, it might be worth turning this into a blog post.
It might be useful to add the "after" directory, and a note about how it contains a clone of this structure but is loaded after other scripts. In fact I'm not too sure about this myself, so an update here would be good.
+1 for after directory.
some personal opnions :)
:help 41.15
to check autoload functionality- dir
color
should becolors
- add dir
ftdetect
compiler
Big thanks for this.
+1 for after directory.
just curious, does the same directory structure works with neovim?
I am thinking about totally ditching .vim/
direcectory and move everything to .config/nvim/
.
just curious, does the same directory structure works with neovim? I am thinking about totally ditching
.vim/
direcectory and move everything to.config/nvim/
.
Yeah, you can do that. Check :help vimfiles
to see all about it. :)
Thanks for this! Question: Do any of the folders really matter? E.g. could I just put EVERYTHING into the plugin folder and it would all just work? Also, what's the point of pathogen to manage plugins? why not just plugins in the plugin directory?