{"id":15377724,"url":"https://github.com/rstacruz/vim-from-scratch","last_synced_at":"2025-04-13T23:50:39.977Z","repository":{"id":66010385,"uuid":"153052525","full_name":"rstacruz/vim-from-scratch","owner":"rstacruz","description":"Rico's guide for setting up Vim","archived":false,"fork":false,"pushed_at":"2022-07-25T03:00:27.000Z","size":29,"stargazers_count":149,"open_issues_count":0,"forks_count":10,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-05T10:11:50.918Z","etag":null,"topics":["vim"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rstacruz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-15T04:18:40.000Z","updated_at":"2025-01-08T12:08:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"88c493ec-4c72-46b7-a3b9-c3960c10e5ca","html_url":"https://github.com/rstacruz/vim-from-scratch","commit_stats":{"total_commits":19,"total_committers":3,"mean_commits":6.333333333333333,"dds":"0.10526315789473684","last_synced_commit":"57bfebdc1e3c508e6e9dfe57d4673ef60c257517"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstacruz%2Fvim-from-scratch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstacruz%2Fvim-from-scratch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstacruz%2Fvim-from-scratch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstacruz%2Fvim-from-scratch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rstacruz","download_url":"https://codeload.github.com/rstacruz/vim-from-scratch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248799905,"owners_count":21163400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["vim"],"created_at":"2024-10-01T14:13:30.694Z","updated_at":"2025-04-13T23:50:39.945Z","avatar_url":"https://github.com/rstacruz.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **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.\n \n\u003cp align='center'\u003e\n\u003cbr\u003e\u003cimg src='https://user-images.githubusercontent.com/74385/46930533-c84de080-d078-11e8-8b8a-24945201be94.png' width='192'\u003e\u003cbr\u003e\n\u003c/p\u003e\n\n\u003ch1 align='center'\u003eVim from scratch\u003c/h1\u003e\n\n\u003cp align='center'\u003e\n\u003cem\u003eRico's guide to setting up Vim for\u003cbr\u003e everyday development\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\nThis guide will walk you through setting up a practical config that will work on [Vim], [Neovim], [Macvim], and any other Vim implementation out there.\n\n#### Getting started\n\n- [Install Vim and Neovim](#install)\n- [Back up your existing config](#backup)\n- [Create ~/.vim](#vimpath)\n- [Create your .vimrc](#vimrc)\n- [Set up symlinks](#symlinks)\n\n#### Customizations\n\n- [Add vim-plug](#vim-plug)\n- [Set up plugins](#plugins)\n- [Set up additional options](#options)\n- [Set up key bindings](#keys)\n- [Set up the leader key](#leader)\n\n#### Interoperability\n\n- [With GUI Vim apps](#gui)\n- [Between Vim and Neovim](#vim-and-neovim)\n- [With Oni](#oni)\n\n#### Moving forward\n\n- [Commit your config](#more)\n- [Share your config](#more)\n- [Learn more about Vim](#more)\n- [Look at other configs](#more)\n\n## Install Vim and Neovim \u003ca id='install'\u003e\u003c/a\u003e\n\n\u003e (Skip this step if you've already installed Vim.)\n\nThere are many ways to acquire Vim. I suggest using [Neovim], a fork of Vim with extra features--but regular [Vim] would work just fine.\n\n- **Vim on Linux** \u003cbr\u003e 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.\n\n  ```bash\n  sudo pacman -S gvim         # Arch Linux\n  sudo apt install vim-gnome  # Ubuntu\n  ```\n\n- **Neovim on Linux** \u003cbr\u003e If your distro ships with python-neovim, add it in too.\n\n  ```bash\n  sudo pacman -S neovim python-neovim\n  ```\n\n- **Neovim on MacOS** \u003cbr\u003e The `neovim` package is available in [Homebrew].\n\n  ```bash\n  brew install neovim\n  # (todo: add more notes on python integration etc)\n  ```\n\n- **Vim on MacOS** \u003cbr\u003e 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.\n\n  ```bash\n  brew install macvim --with-cscope --with-lua --override-system-vim --with-luajit --with-python3\n  ```\n\n## Back up your existing Vim config \u003ca id='backup'\u003e\u003c/a\u003e\n\n\u003e (Skip this step if you're setting up a fresh installation of Vim.)\n\nWant to try out this guide, but you already have Vim set up? You can rename them for now, and restore it later on.\n\n```bash\nmv ~/.vimrc ~/.vimrc~\nmv ~/.vim ~/.vim~\nmv ~/.config/nvim ~/.config/nvim~\n```\n\n## Create your ~/.vim \u003ca id='vimpath'\u003e\u003c/a\u003e\n\nThe 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.\n\n```sh\nmkdir -p ~/.vim\ncd ~/.vim\n\n# Version it using Git\ngit init\ngit commit -m \"Initial commit\" --allow-empty\n```\n\n## Create your init.vim (aka .vimrc) \u003ca id='vimrc'\u003e\u003c/a\u003e\n\nVim 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.\n\n```bash\ncd ~/.vim\ntouch init.vim\n```\n\n## Set up symlinks \u003ca id='symlinks'\u003e\u003c/a\u003e\n\nMy 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:\n\n```bash\n# Makefile\npwd := $(shell pwd -LP)\n\nlink:\n\t@if [ ! . -ef ~/.vim ]; then ln -nfs \"${pwd}\" ~/.vim; fi\n\t@if [ ! . -ef ~/.config/nvim ]; then ln -nfs \"${pwd}\" ~/.config/nvim; fi\n\t@ln -nfs \"${pwd}/init.vim\" ~/.vimrc\n```\n\nAfter creating it, just run `make link`. This should finally make your config available in both `~/.config/nvim/init.vim` and `~/.vimrc`.\n\n```bash\n# Before doing this, make sure you don't have ~/.vimrc (careful!)\nrm ~/.vimrc\n\n# Set up symlinks\ncd ~/.vim\nmake link\n```\n\n## Install vim-plug \u003ca id='vim-plug'\u003e\u003c/a\u003e\n\n[**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:\n\n```bash\ncurl -fLo ~/.vim/autoload/plug.vim --create-dirs \\\n  https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim\n```\n\nEdit your config file by doing `vim ~/.vim/init.vim`. Add the following:\n\n```vim\nset nocompatible\nlet g:mapleader=\" \"\n\ncall plug#begin('~/.vim/vendor')\n\nif !has('nvim') \u0026\u0026 !exists('g:gui_oni') | Plug 'tpope/vim-sensible' | endif\nPlug 'rstacruz/vim-opinion'\n\ncall plug#end()\n```\n\nSave it, restart Vim, then call _PlugInstall_.\n\n```vim\n\" Save the file and exit vim\n:wq\n\n\" Start vim again, then install the plugins\n:PlugInstall\n```\n\n\u003e See: [vim-plug usage](https://github.com/junegunn/vim-plug#usage) _(github.com)_\n\n## Install plugins \u003ca id='plugins'\u003e\u003c/a\u003e\n\nThe config above will install 2 plugins. Both are optional, but I recommend them:\n\n- [**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.\n\n  ```vim\n  if !has('nvim') \u0026\u0026 !exists('g:gui_oni') | Plug 'tpope/vim-sensible' | endif\n  ```\n\n- [**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.\n\n  ```vim\n  Plug 'rstacruz/vim-opinion'\n  ```\n\n### More plugins\n\nHere are some more that I can recommend to almost every developer:\n\n- [**fzf**](https://github.com/junegunn/fzf) is a very fast file picker. I recommend this over alternatives like ctrlp.vim.\n\n  ```vim\n  Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all' }\n  Plug 'junegunn/fzf.vim'\n  ```\n\n- [**ale**](https://github.com/w0rp/ale) verifies your files for syntax errors.\n\n  ```vim\n  Plug 'w0rp/ale'\n  ```\n\n- [**vim-sleuth**](https://github.com/tpope/vim-sleuth) auto-detects if files use space or tabs, and how many spaces each file should have.\n\n  ```vim\n  Plug 'tpope/vim-sleuth'\n  ```\n\n- [**vim-polyglot**](https://github.com/sheerun/vim-polyglot) adds automatic language support for every language that Vim can support through 3rd party plugins.\n\n  ```vim\n  Plug 'sheerun/vim-polyglot'\n  ```\n\n## Set up additional options \u003ca id='options'\u003e\u003c/a\u003e\n\nOur 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.\n\n```bash\nmkdir -p ~/.vim/after/plugin\nvim ~/.vim/after/plugin/options.vim\n```\n\nHere are some stuff you can add. All of these are optional.\n\n```vim\n\" Enable 256-color by default in the terminal\nif !has('gui_running') | set t_Co=256 | endif\n\n\" Hide line numbers by default\nset nonumber\n\n\" Wildignore\nset wig+=vendor,log,logs\n```\n\n\u003e 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)\\_\n\n[after-directory]: http://learnvimscriptthehardway.stevelosh.com/chapters/42.html#vimafter\n\n## Set up additional key bindings \u003ca id='keys'\u003e\u003c/a\u003e\n\nI 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\n\n```bash\nvim ~/.vim/after/plugin/key_bindings.vim\n```\n\n```vim\n\" ctrl-s to save\nnnoremap \u003cC-s\u003e :w\u003cCR\u003e\n\n\" ctrl-p to open a file via fzf\nif exists(':FZF')\n  nnoremap \u003cC-p\u003e :FZF!\u003ccr\u003e\nendif\n\n\" SPC-f-e-d to edit your config file\nnnoremap \u003cleader\u003efed :cd ~/.vim\u003cCR\u003e:e ~/.vim/init.vim\u003cCR\u003e\n\" SPC-f-e-k to edit your kepmap file\nnnoremap \u003cleader\u003efek :cd ~/.vim\u003cCR\u003e:e ~/.vim/after/plugin/key_bindings.vim\u003cCR\u003e\n\" SPC-f-e-o to edit your options file\nnnoremap \u003cleader\u003efeo :cd ~/.vim\u003cCR\u003e:e ~/.vim/after/plugin/options.vim\u003cCR\u003e\n```\n\nThe `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.\n\n## Change your leader key \u003ca id='leader'\u003e\u003c/a\u003e\n\nThe 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 `\u003cspace\u003e`, `\u003ccr\u003e`, `\u003cbs\u003e`, `-` and `,`.\n\n```vim\n\" In your ~/.vim/init.vim\nlet g:mapleader=\",\"\n```\n\n\u003e See: [Leaders](http://learnvimscriptthehardway.stevelosh.com/chapters/06.html) _(learnvimscriptthehardway.stevelosh.com)_\n\n## Interoperability with GUI Vim apps \u003ca id='gui'\u003e\u003c/a\u003e\n\nThere are many Vim GUI apps available today. Some popular ones include [Macvim], [VimR], vim-gtk and more are probably coming out everyday.\n\nThere 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.\n\nLike 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:\n\n```vim\n\" ~/.vim/after/plugin/theme.vim\n\nif has('gui_running')\n  \" Settings for when running in a GUI\n  set transparency=0\n  set guifont=Iosevka\\ Medium:h16 linespace=-1\n  set guioptions+=gme \" gray menu items, menu bar, gui tabs\n  set antialias\n  color ir_black+\nelse\n  \" Settings for when running in the console\n  color base16\nendif\n```\n\n## Interoperability between Vim and Neovim \u003ca id='vim-and-neovim'\u003e\u003c/a\u003e\n\n\u003e TODO: talk about `has('nvim')`, config paths, etc\n\n## Interoperability with Oni \u003ca id='oni'\u003e\u003c/a\u003e\n\n\u003e TODO: talk about `exists('g:gui_oni')`\n\n## More to come! \u003ca id='more'\u003e\u003c/a\u003e\n\nThis 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!\n\nHere are some more resources to look at:\n\n- [mhinz/vim-galore](https://github.com/mhinz/vim-galore#readme) has a lot of tips on learning Vim.\n\n- [devhints.io/vim](http://devhints.io/vim) is a quick reference on Vim.\n\n- [Learn vimscript the hard way](http://learnvimscriptthehardway.stevelosh.com/) is a free book on Vim scripting.\n\n- [vim-galore plugins](https://github.com/mhinz/vim-galore/blob/master/PLUGINS.md) is a curated list of common Vim plugins.\n\n\u003e Icon from [Thenounproject.com](https://thenounproject.com/search/?q=code\u0026i=995778)\n\n[homebrew]: https://brew.sh/\n[macvim]: http://macvim-dev.github.io/macvim/\n[neovim]: https://neovim.io/\n[vim]: https://www.vim.org/\n[vim-plug]: https://github.com/junegunn/vim-plug\n[vim-sensible]: https://github.com/tpope/vim-sensible\n[vim-opinion]: https://github.com/tpope/vim-sensible\n[vimr]: http://vimr.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstacruz%2Fvim-from-scratch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frstacruz%2Fvim-from-scratch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstacruz%2Fvim-from-scratch/lists"}