|
Size: 4857
Comment:
|
Size: 4351
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
'''vi Improved''' ('''vim''') is a visual text editor. It is a family of programs with drop-in compatibility, including `neovim`. |
|
| Line 14: | Line 11: |
| Initial Vim configuration happens in the '''vimrc''' file, located at `~/.vimrc` or `~/.vim/vimrc` (or for Windows, `~/_vimrc` or `~/vimfiles/vimrc`). | Initial configuration happens in the '''vimrc''' file, located at `~/.vimrc` or `~/.vim/vimrc`. GVim looks in `~/_vimrc` or `~/vimfiles/vimrc`. |
| Line 22: | Line 21: |
| Vim searches for configuration files using a `runtimepath` option, based on a directory structure. First it looks for local configuration in `~/.vim` (or for Windows, `~/viminfo`). then it looks for system configurations in `$VIMRUNTIME`. Lastly is looks for `after` local configuration in `~/.vim/after` (or for Windows, `~/vimfiles/after`). | 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 24: | Line 23: |
| To append a path to the default `runtimepath` option, edit your `~/.vimrc` with syntax like the following: | The loading order goes... 1. local configuration is loaded from `~/.vim` (or `~/viminfo` for GVim). 2. system configuration is loaded from `$VIMRUNTIME`. 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 27: | Line 34: |
| execute 'set runtimepath+=' . expand('~/.marslo/.vim/bundle/vundle') | execute 'set runtimepath+=' . expand('path/to/organization/configuration') |
| Line 36: | 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 42: | Line 47: |
| === autoload === | === After === |
| Line 44: | 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 46: | 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 54: | Line 65: |
| === plugin === | === Plugin === |
| Line 56: | 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 60: | Line 71: |
| === filetype.vim, ftdetect, and scripts.vim === | === File Type Detection === |
| Line 62: | 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 64: | 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 66: | 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 72: | 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 78: | Line 97: |
| === syntax === | === Syntax === |
| Line 80: | 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 82: | 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 86: | Line 105: |
| === ftplugin.vim and ftplugin === | === Ftplugin === |
| Line 88: | 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 90: | 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 92: | 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 96: | Line 115: |
| === indent.vim and indent === | === Indent === |
| Line 98: | 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 100: | 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 102: | 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 106: | Line 125: |
| === compiler === | === Compiler === |
| Line 108: | 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 110: | 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 114: | Line 133: |
| === Colors === | |
| Line 115: | Line 135: |
| === colors === | Color scheme plugins should be placed in the '''colors''' directory. |
| Line 117: | 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 125: | 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.