└── README.md /README.md: -------------------------------------------------------------------------------- 1 | > **Deprecated**: Thanks for checking my project! The guide below was made for older versions of Vim. Today, you can try [nvim-starter](https://github.com/rstacruz/nvim-starter) or [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim) for Neovim. 2 | 3 |

4 |

5 |

6 | 7 |

Vim from scratch

8 | 9 |

10 | Rico's guide to setting up Vim for
everyday development 11 |

12 | 13 |
14 | 15 | This guide will walk you through setting up a practical config that will work on [Vim], [Neovim], [Macvim], and any other Vim implementation out there. 16 | 17 | #### Getting started 18 | 19 | - [Install Vim and Neovim](#install) 20 | - [Back up your existing config](#backup) 21 | - [Create ~/.vim](#vimpath) 22 | - [Create your .vimrc](#vimrc) 23 | - [Set up symlinks](#symlinks) 24 | 25 | #### Customizations 26 | 27 | - [Add vim-plug](#vim-plug) 28 | - [Set up plugins](#plugins) 29 | - [Set up additional options](#options) 30 | - [Set up key bindings](#keys) 31 | - [Set up the leader key](#leader) 32 | 33 | #### Interoperability 34 | 35 | - [With GUI Vim apps](#gui) 36 | - [Between Vim and Neovim](#vim-and-neovim) 37 | - [With Oni](#oni) 38 | 39 | #### Moving forward 40 | 41 | - [Commit your config](#more) 42 | - [Share your config](#more) 43 | - [Learn more about Vim](#more) 44 | - [Look at other configs](#more) 45 | 46 | ## Install Vim and Neovim 47 | 48 | > (Skip this step if you've already installed Vim.) 49 | 50 | There are many ways to acquire Vim. I suggest using [Neovim], a fork of Vim with extra features--but regular [Vim] would work just fine. 51 | 52 | - **Vim on Linux**
Most distributions come with `vim` and `neovim` packages. Some distributions have different versions available. When in doubt, pick the `vim-gnome` or `vim-gtk3` or `gvim` package. 53 | 54 | ```bash 55 | sudo pacman -S gvim # Arch Linux 56 | sudo apt install vim-gnome # Ubuntu 57 | ``` 58 | 59 | - **Neovim on Linux**
If your distro ships with python-neovim, add it in too. 60 | 61 | ```bash 62 | sudo pacman -S neovim python-neovim 63 | ``` 64 | 65 | - **Neovim on MacOS**
The `neovim` package is available in [Homebrew]. 66 | 67 | ```bash 68 | brew install neovim 69 | # (todo: add more notes on python integration etc) 70 | ``` 71 | 72 | - **Vim on MacOS**
I recommend using [Macvim] with installed via [Homebrew] with `--override-system-vim`. This gets you a more updated version of Vim than if you used the `vim` package. You'll also get a GUI app, which can be nice. 73 | 74 | ```bash 75 | brew install macvim --with-cscope --with-lua --override-system-vim --with-luajit --with-python3 76 | ``` 77 | 78 | ## Back up your existing Vim config 79 | 80 | > (Skip this step if you're setting up a fresh installation of Vim.) 81 | 82 | Want to try out this guide, but you already have Vim set up? You can rename them for now, and restore it later on. 83 | 84 | ```bash 85 | mv ~/.vimrc ~/.vimrc~ 86 | mv ~/.vim ~/.vim~ 87 | mv ~/.config/nvim ~/.config/nvim~ 88 | ``` 89 | 90 | ## Create your ~/.vim 91 | 92 | The first obvious step is to create your config folder. Vim expects this in `~/.vim`, and Neovim expects it in `~/.config/nvim`. Since our goal is to make a Vim config that'll work everywhere, I suggest keeping it in _~/.vim_ and symlinking it as needed. 93 | 94 | ```sh 95 | mkdir -p ~/.vim 96 | cd ~/.vim 97 | 98 | # Version it using Git 99 | git init 100 | git commit -m "Initial commit" --allow-empty 101 | ``` 102 | 103 | ## Create your init.vim (aka .vimrc) 104 | 105 | Vim looks for your config in `~/.vimrc`, and Neovim looks for it in `~/.config/nvim/init.vim`. Let's create the file as `~/.vim/init.vim`, which we will symlink to the proper locations later. 106 | 107 | ```bash 108 | cd ~/.vim 109 | touch init.vim 110 | ``` 111 | 112 | ## Set up symlinks 113 | 114 | My preferred method is to create a `Makefile` which will set up symlinks as necessary. In `~/.vim`, create a file called `Makefile` and add this in: 115 | 116 | ```bash 117 | # Makefile 118 | pwd := $(shell pwd -LP) 119 | 120 | link: 121 | @if [ ! . -ef ~/.vim ]; then ln -nfs "${pwd}" ~/.vim; fi 122 | @if [ ! . -ef ~/.config/nvim ]; then ln -nfs "${pwd}" ~/.config/nvim; fi 123 | @ln -nfs "${pwd}/init.vim" ~/.vimrc 124 | ``` 125 | 126 | After creating it, just run `make link`. This should finally make your config available in both `~/.config/nvim/init.vim` and `~/.vimrc`. 127 | 128 | ```bash 129 | # Before doing this, make sure you don't have ~/.vimrc (careful!) 130 | rm ~/.vimrc 131 | 132 | # Set up symlinks 133 | cd ~/.vim 134 | make link 135 | ``` 136 | 137 | ## Install vim-plug 138 | 139 | [**vim-plug**][vim-plug] is the plugin manager I can recommend the most. It's ridiculously fast, and supports a lot of great features. This command will download `plug.vim` into your Vim config path: 140 | 141 | ```bash 142 | curl -fLo ~/.vim/autoload/plug.vim --create-dirs \ 143 | https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim 144 | ``` 145 | 146 | Edit your config file by doing `vim ~/.vim/init.vim`. Add the following: 147 | 148 | ```vim 149 | set nocompatible 150 | let g:mapleader=" " 151 | 152 | call plug#begin('~/.vim/vendor') 153 | 154 | if !has('nvim') && !exists('g:gui_oni') | Plug 'tpope/vim-sensible' | endif 155 | Plug 'rstacruz/vim-opinion' 156 | 157 | call plug#end() 158 | ``` 159 | 160 | Save it, restart Vim, then call _PlugInstall_. 161 | 162 | ```vim 163 | " Save the file and exit vim 164 | :wq 165 | 166 | " Start vim again, then install the plugins 167 | :PlugInstall 168 | ``` 169 | 170 | > See: [vim-plug usage](https://github.com/junegunn/vim-plug#usage) _(github.com)_ 171 | 172 | ## Install plugins 173 | 174 | The config above will install 2 plugins. Both are optional, but I recommend them: 175 | 176 | - [**vim-sensible**](https://github.com/tpope/vim-sensible) enables some good "sensible" defaults, such as turning on syntax highlighting. This is superfluous in some vim forks like Neovim so I suggest to conditionally load it only when needed. 177 | 178 | ```vim 179 | if !has('nvim') && !exists('g:gui_oni') | Plug 'tpope/vim-sensible' | endif 180 | ``` 181 | 182 | - [**vim-opinion**](https://github.com/rstacruz/vim-opinion) enables some good "opinionated" defaults that I prefer (I'm the author of this plugin!). This has some settings that I think will do well for most setups, such as incremental search and so on. 183 | 184 | ```vim 185 | Plug 'rstacruz/vim-opinion' 186 | ``` 187 | 188 | ### More plugins 189 | 190 | Here are some more that I can recommend to almost every developer: 191 | 192 | - [**fzf**](https://github.com/junegunn/fzf) is a very fast file picker. I recommend this over alternatives like ctrlp.vim. 193 | 194 | ```vim 195 | Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all' } 196 | Plug 'junegunn/fzf.vim' 197 | ``` 198 | 199 | - [**ale**](https://github.com/w0rp/ale) verifies your files for syntax errors. 200 | 201 | ```vim 202 | Plug 'w0rp/ale' 203 | ``` 204 | 205 | - [**vim-sleuth**](https://github.com/tpope/vim-sleuth) auto-detects if files use space or tabs, and how many spaces each file should have. 206 | 207 | ```vim 208 | Plug 'tpope/vim-sleuth' 209 | ``` 210 | 211 | - [**vim-polyglot**](https://github.com/sheerun/vim-polyglot) adds automatic language support for every language that Vim can support through 3rd party plugins. 212 | 213 | ```vim 214 | Plug 'sheerun/vim-polyglot' 215 | ``` 216 | 217 | ## Set up additional options 218 | 219 | Our config so far has _vim-sensible_ and _vim-opinion_, which has some great defaults. You may want to add more settings. Instead of dumping them into `~/.vimrc`, I suggest adding them to your [after-directory] instead. This will keep your config file as clean as possible. 220 | 221 | ```bash 222 | mkdir -p ~/.vim/after/plugin 223 | vim ~/.vim/after/plugin/options.vim 224 | ``` 225 | 226 | Here are some stuff you can add. All of these are optional. 227 | 228 | ```vim 229 | " Enable 256-color by default in the terminal 230 | if !has('gui_running') | set t_Co=256 | endif 231 | 232 | " Hide line numbers by default 233 | set nonumber 234 | 235 | " Wildignore 236 | set wig+=vendor,log,logs 237 | ``` 238 | 239 | > See: [Keep your vimrc clean](http://vim.wikia.com/wiki/Keep_your_vimrc_file_clean) _(vim.wikia.com)_, [~/.vim/after](http://learnvimscriptthehardway.stevelosh.com/chapters/42.html#vimafter) \_(learnvimscriptthehardway.stevelosh.com)\_ 240 | 241 | [after-directory]: http://learnvimscriptthehardway.stevelosh.com/chapters/42.html#vimafter 242 | 243 | ## Set up additional key bindings 244 | 245 | I suggest keeping most (all?) of your key bindings in one file in your _after-directory_. I prefer to keep them in `~/.vim/after/plugin/key_bindings.vim`. This way, you can 246 | 247 | ```bash 248 | vim ~/.vim/after/plugin/key_bindings.vim 249 | ``` 250 | 251 | ```vim 252 | " ctrl-s to save 253 | nnoremap :w 254 | 255 | " ctrl-p to open a file via fzf 256 | if exists(':FZF') 257 | nnoremap :FZF! 258 | endif 259 | 260 | " SPC-f-e-d to edit your config file 261 | nnoremap fed :cd ~/.vim:e ~/.vim/init.vim 262 | " SPC-f-e-k to edit your kepmap file 263 | nnoremap fek :cd ~/.vim:e ~/.vim/after/plugin/key_bindings.vim 264 | " SPC-f-e-o to edit your options file 265 | nnoremap feo :cd ~/.vim:e ~/.vim/after/plugin/options.vim 266 | ``` 267 | 268 | The `leader` keymaps at the end can be triggered with the _Spacebar_ as the leader key. For instance, the first one is `SPACE` `f` `e` `d`. These are inspired by Spacemacs. 269 | 270 | ## Change your leader key 271 | 272 | The default `init.vim` above has a `g:mapleader` setting of spacebar. This is a great default that a lot of people use! I personally prefer the `,` key as a Dvorak user, but this is totally up to you. Common leader keys are ``, ``, ``, `-` and `,`. 273 | 274 | ```vim 275 | " In your ~/.vim/init.vim 276 | let g:mapleader="," 277 | ``` 278 | 279 | > See: [Leaders](http://learnvimscriptthehardway.stevelosh.com/chapters/06.html) _(learnvimscriptthehardway.stevelosh.com)_ 280 | 281 | ## Interoperability with GUI Vim apps 282 | 283 | There are many Vim GUI apps available today. Some popular ones include [Macvim], [VimR], vim-gtk and more are probably coming out everyday. 284 | 285 | There are some settings you might only want to use on GUI. You can use `if has('gui_running')` to conditionally only apply settings when running in a GUI. 286 | 287 | Like most settings, I suggest placing them in the after-directory, eg, `~/.vim/after/plugin/theme.vim`. Here's an example that sets fonts for GUIs: 288 | 289 | ```vim 290 | " ~/.vim/after/plugin/theme.vim 291 | 292 | if has('gui_running') 293 | " Settings for when running in a GUI 294 | set transparency=0 295 | set guifont=Iosevka\ Medium:h16 linespace=-1 296 | set guioptions+=gme " gray menu items, menu bar, gui tabs 297 | set antialias 298 | color ir_black+ 299 | else 300 | " Settings for when running in the console 301 | color base16 302 | endif 303 | ``` 304 | 305 | ## Interoperability between Vim and Neovim 306 | 307 | > TODO: talk about `has('nvim')`, config paths, etc 308 | 309 | ## Interoperability with Oni 310 | 311 | > TODO: talk about `exists('g:gui_oni')` 312 | 313 | ## More to come! 314 | 315 | This guide is a work in progress, more stuff soon! But at this point you should have a working Vim config. Commit it, and share it! 316 | 317 | Here are some more resources to look at: 318 | 319 | - [mhinz/vim-galore](https://github.com/mhinz/vim-galore#readme) has a lot of tips on learning Vim. 320 | 321 | - [devhints.io/vim](http://devhints.io/vim) is a quick reference on Vim. 322 | 323 | - [Learn vimscript the hard way](http://learnvimscriptthehardway.stevelosh.com/) is a free book on Vim scripting. 324 | 325 | - [vim-galore plugins](https://github.com/mhinz/vim-galore/blob/master/PLUGINS.md) is a curated list of common Vim plugins. 326 | 327 | > Icon from [Thenounproject.com](https://thenounproject.com/search/?q=code&i=995778) 328 | 329 | [homebrew]: https://brew.sh/ 330 | [macvim]: http://macvim-dev.github.io/macvim/ 331 | [neovim]: https://neovim.io/ 332 | [vim]: https://www.vim.org/ 333 | [vim-plug]: https://github.com/junegunn/vim-plug 334 | [vim-sensible]: https://github.com/tpope/vim-sensible 335 | [vim-opinion]: https://github.com/tpope/vim-sensible 336 | [vimr]: http://vimr.org/ 337 | --------------------------------------------------------------------------------