|
Size: 4697
Comment:
|
← Revision 5 as of 2022-05-11 18:18:59 ⇥
Size: 4360
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 21: | Line 21: |
| Vim assumes a standard file structure (see below) and searches for configuration files using a `runtimepath` option. | Configurations are loaded using the `runtimepath` variable. Each entry is a directory that will be searched for configuration files. A standard file structure (see below) is assumed. |
| Line 23: | Line 23: |
| First, local configuration is loaded from `~/.vim` (or `~/viminfo` for GVim). | The loading order goes... |
| Line 25: | Line 25: |
| Second, system configuration is loaded from `$VIMRUNTIME`. | 1. local configuration is loaded from `~/.vim` (or `~/viminfo` for GVim). |
| Line 27: | Line 27: |
| Third, '''after''' local configuration in `~/.vim/after` (or `~/vimfiles/after` for GVim). | 2. system configuration is loaded from `$VIMRUNTIME`. |
| Line 29: | Line 29: |
| To append a path to the default `runtimepath` option, edit the vimrc file. | 3. '''after''' local configuration is laoded from `~/.vim/after` (or `~/vimfiles/after` for GVim). To load an additional configuration directory, append the path to `runtimepath`. This should be done by editing the vimrc file. |
| Line 32: | Line 34: |
| execute 'set runtimepath+=' . expand('~/.marslo/.vim/bundle/vundle') | execute 'set runtimepath+=' . expand('path/to/organization/configuration') |
| Line 41: | Line 43: |
| Vim loads plugins and configurations based on a directory structure. This directory structure can be used in any path on the `runtimepath`. The `after` directory is meant for plugins/configurations that should ''override'' previously evaluated plugins/configurations. This is most commonly used to override system configuration with local configuration. |
Plugins and configurations are loaded based on a standard directory structure. |
| Line 47: | Line 47: |
| === autoload === | === After === |
| Line 49: | Line 49: |
| Libraries should be located in the `autoload` directory, This directory is searched for vimscript libraries; functions are loaded into memory but not evaluated. | The '''after''' directory is meant for files that should ''override'' previously evaluated files, which is achieved by loading ''after'' all others. |
| Line 51: | Line 51: |
| Given a function `foo` located in `autoload/mylib`, use: | === Autoload === Libraries should be placed in the '''autoload''' directory. Note that functions are loaded into memory but not evaluated. Given a function `foo` located in `autoload/mylib`, it can be called like: |
| Line 59: | Line 65: |
| === plugin === | === Plugin === |
| Line 61: | Line 67: |
| Generic plugins should be located in the `plugin` directory. This directory is searched ''recursively'' for vimscript plugins. | Plugins that are always loaded should be located in the '''plugin''' directory. |
| Line 65: | Line 71: |
| === filetype.vim, ftdetect, and scripts.vim === | === File Type Detection === |
| Line 67: | Line 73: |
| Many subsequent processes are determined by the `filetype` options. This is set through one of the following: | Many subsequent processes branch based on the `filetype` variable. This is set through one of the following: |
| Line 69: | Line 75: |
| The vimscript `filetype.vim` is executed first. Typically, this is used only for generic system configuration. | 1. the '''filetype.vim''' file is executed, setting generic system configuration |
| Line 71: | Line 77: |
| Secondly, the `ftdetect` directory is searched for a plugin matching the current buffer's file extension. (To clarify: `foo.bar` would load `ftdetect/bar.vim`.) These plugins should look like: | 2. the '''ftdetect''' directory is searched for a file matching the current buffer's file extension. (i.e. with `foo.bar` opened for editing, `ftdetect/bar.vim` would be loaded.) 3. the '''scripts.vim''' file is executed, setting generic local configuration Note that this is ''all'' skipped if the `filetype variable is set to `off`. ==== Ftdetect ==== '''ftdetect''' plugins should look like: |
| Line 77: | Line 94: |
| Lastly, `scripts.vim` is evaluated. Typically, generic local configurations will be done here. This file is ideal for generic filetype detection logic. This is ''all'' skipped if the command `:set filetype [...] off` was called. |
|
| Line 83: | Line 97: |
| === syntax === | ==== Syntax ==== |
| Line 85: | Line 99: |
| Configuration for syntax highlighting based on filetype should be located in the `syntax` directory. Given a set `filetype`, Vim searches for `syntax/<FILETYPE>.vim`. This is skipped if the command `:syntax off` was called. | Based on `filetype`, a syntax highlighting plugin may be loaded. With `foo.bar` opened for editing and `filetype` set to `bar`, configuration will be loaded from `syntax/bar.vim`. |
| Line 87: | Line 101: |
| This is skipped if the command `:set filetype [...] off` was called. | Note that this is skipped if the `filetype variable is set to `off` ''or'' if the command `:syntax off` was run. |
| Line 91: | Line 105: |
| === ftplugin.vim and ftplugin === | ==== Ftplugin ==== |
| Line 93: | Line 107: |
| The vimscript `ftplugin.vim` is executed first. Typically, this is used only for generic system configuration. | The '''ftplugin.vim''' file is executed. Typically this is used for generic system configuration. |
| Line 95: | Line 109: |
| Plugins that should be loaded/evaluated conditionally based on filetype should be located in the `ftplugin` directory. Given a set `filetype`, Vim searches for `ftplugin/<FILETYPE>.vim`. | Based on `filetype`, a language plugin may be loaded. With `foo.bar` opened for editing and `filetype` set to `bar`, configuration will be loaded from `ftplugin/bar.vim`. |
| Line 97: | Line 111: |
| This is ''all'' skipped if the command `:set filetype [...] off` was called. | Note that this is skipped if the `filetype variable is set to `off`. |
| Line 101: | Line 115: |
| === indent.vim and indent === | ==== Indent ==== |
| Line 103: | Line 117: |
| The vimscript `indent.vim` is executed first. Typically, this is used only for generic system configuration. | The '''indent.vim''' file is executed. Typically this is used for generic system configuration. |
| Line 105: | Line 119: |
| Configuration for indentation based on filetype should be located in the `indent` directory. Given a set `filetype`, Vim searches for `indent/<FILETYPE>.vim`. | Based on `filetype`, an indentation plugin may be loaded. With `foo.bar` opened for editing and `filetype` set to `bar`, configuration will be loaded from `indent/bar.vim`. |
| Line 107: | Line 121: |
| This is ''all'' skipped if the command `:set filetype [...] off` was called. | Note that this is skipped if the `filetype variable is set to `off`. |
| Line 111: | Line 125: |
| === compiler === | ==== Compiler ==== |
| Line 113: | Line 127: |
| Configuration for compilers based on filetype should be located in the `compiler` directory. Given a set `filetype`, Vim searches for `compiler/<FILETYPE>.vim`. | Based on `filetype`, a compiler plugin may be loaded. With `foo.bar` opened for editing and `filetype` set to `bar`, configuration will be loaded from `compiler/bar.vim`. |
| Line 115: | Line 129: |
| This is skipped if the command `:set filetype [...] off` was called. | Note that this is skipped if the `filetype variable is set to `off`. |
| Line 119: | Line 133: |
| === Colors === | |
| Line 120: | Line 135: |
| === colors === | Color scheme plugins should be placed in the '''colors''' directory. |
| Line 122: | Line 137: |
| Color scheme plugins mshould be located in the `colors` directory. When the `:colorscheme` command is called, this directory is searched for a plugin matching the name. (To clarify: `:colorscheme blue` would load `colors/blue.vim`.) | When the `:colorscheme NAME` command is executed, `colors/NAME.vim` is executed. |
| Line 130: | Line 145: |
| One of the most popular package management solutions for Vim is '''Pathogen'''. Pathogen is a short vimscript that searches an additional directory `bundle` for sub-directories. These sub-directories are added to the `runtimepath` option between local and system configuration. Each package then can be setup using the above directory structure and integrate into the Vim ecosystem immediately. | One of the most popular package management solutions for Vim is '''Pathogen'''. Pathogen is a short plugin that recursively searches an additional '''bundle''' directory. Discovered sub-directories are added to the `runtimepath` option between local and system configuration. |
Vim
Contents
vimrc
Initial configuration happens in the vimrc file, located at ~/.vimrc or ~/.vim/vimrc.
GVim looks in ~/_vimrc or ~/vimfiles/vimrc.
Runtime Path
Configurations are loaded using the runtimepath variable. Each entry is a directory that will be searched for configuration files. A standard file structure (see below) is assumed.
The loading order goes...
local configuration is loaded from ~/.vim (or ~/viminfo for GVim).
system configuration is loaded from $VIMRUNTIME.
after local configuration is laoded from ~/.vim/after (or ~/vimfiles/after for GVim).
To load an additional configuration directory, append the path to runtimepath. This should be done by editing the vimrc file.
execute 'set runtimepath+=' . expand('path/to/organization/configuration')
Directory Structure
Plugins and configurations are loaded based on a standard directory structure.
After
The after directory is meant for files that should override previously evaluated files, which is achieved by loading after all others.
Autoload
Libraries should be placed in the autoload directory.
Note that functions are loaded into memory but not evaluated. Given a function foo located in autoload/mylib, it can be called like:
call mylib#foo()
Plugin
Plugins that are always loaded should be located in the plugin directory.
File Type Detection
Many subsequent processes branch based on the filetype variable. This is set through one of the following:
the filetype.vim file is executed, setting generic system configuration
the ftdetect directory is searched for a file matching the current buffer's file extension. (i.e. with foo.bar opened for editing, ftdetect/bar.vim would be loaded.)
the scripts.vim file is executed, setting generic local configuration
Note that this is all skipped if the filetype variable is set to off`.
Ftdetect
ftdetect plugins should look like:
autocmd BufNewFile,BufRead *.bar setfiletype foobar
Syntax
Based on filetype, a syntax highlighting plugin may be loaded. With foo.bar opened for editing and filetype set to bar, configuration will be loaded from syntax/bar.vim.
Note that this is skipped if the filetype variable is set to off ''or'' if the command :syntax off` was run.
Ftplugin
The ftplugin.vim file is executed. Typically this is used for generic system configuration.
Based on filetype, a language plugin may be loaded. With foo.bar opened for editing and filetype set to bar, configuration will be loaded from ftplugin/bar.vim.
Note that this is skipped if the filetype variable is set to off`.
Indent
The indent.vim file is executed. Typically this is used for generic system configuration.
Based on filetype, an indentation plugin may be loaded. With foo.bar opened for editing and filetype set to bar, configuration will be loaded from indent/bar.vim.
Note that this is skipped if the filetype variable is set to off`.
Compiler
Based on filetype, a compiler plugin may be loaded. With foo.bar opened for editing and filetype set to bar, configuration will be loaded from compiler/bar.vim.
Note that this is skipped if the filetype variable is set to off`.
Colors
Color scheme plugins should be placed in the colors directory.
When the :colorscheme NAME command is executed, colors/NAME.vim is executed.
Pathogen
One of the most popular package management solutions for Vim is Pathogen. Pathogen is a short plugin that recursively searches an additional bundle directory. Discovered sub-directories are added to the runtimepath option between local and system configuration.
Neovim
Neovim follows the XDG standard, and checks for configuration in ${XDG_CONFIG_HOME}/nvim. The standard is also to use ${XDG_CONFIG_HOME}/init.vim instead of a vimrc file.