Unix Setup: neovim
Published: , Updated:
Introduction ¶
I'll explain my current setup of Neovim. I'm using this editor since some years as the only editor. I'm a full time developer, mostly working on PHP based websites using the open source CMS TYPO3. Therefore, my Neovim is tuned to ease work in that specific area. I've also worked with ReStructuredText (=rst), Python and TypeScript. Most parts should be reusable for other areas, some are very specific to TYPO3 but might give insights and ideas on how to improve workflows for other projects.
The post will explain my folder directory and setup, as well as plugins and foreign tools that are integrated into Neovim.
vi vs vim vs neovim ¶
I'm not going to much into detail here. I'm using neovim because when I switched it was a bit ahead regarding asynchronous processing. I would still recommend neovim if you plan to write your own plugins, as neovim allows you to easily write them using foreign languages like Python. If you are interested in writing custom plugins, check out https://github.com/neovim/neovim/wiki/Related-projects#api-clients.
I would not recommend to use vi but vim or neovim. Which one is up to you, but of course everyone should choose the right tool. So it doesn't matter to much whether you are using any kind of vim or use emacs, Sublime Text, Atom, Visual Studio Code or an IDE like NetBeans, Eclipse, etc.
I'm using neovim in terminal 100%. But there are other nice UIs for vim and neovim, if you are more into using a GUI. In case you prefer GUIs and neovim, check out https://github.com/neovim/neovim/wiki/Related-projects#gui.
Configuration ¶
I've structured my configuration into multiple files and folders. You can find out more about the structure at the older blog post "Folder specific settings in Vim" at section "Current structure of Vim configuration".
That might not be a good starting point. But once the configuration is growing, it might help to keep an overview.
Plugins ¶
Probably the most interesting part for most readers, but in the end I find those lists more or less useless. You can find plugins on GitHub and via https://vimawesome.com/. I find it unlikely that you find good plugins by reading other peoples blogs or configurations. You either need a plugin for a use case and search for it, or watch videos and find an interesting solution solved by plugins.
Still here it comes, reduced to the most important:
- ag.vim
https://vimawesome.com/plugin/ag-vim
Already deprecated integration for "ag" command line tool for searching files. Still it serves the general purpose. - ale
https://vimawesome.com/plugin/ale
One of the many available solutions for asynchronous linting integration. It comes with a wide range of pre configured tools. - coc.nvim
https://vimawesome.com/plugin/coc-nvim
Provide code completion. Needs nodejs. There are alternatives, but that one worked well for me. - ctrlp.vim
https://vimawesome.com/plugin/ctrlp
One of the fuzzy finders. It provides files and buffers as well as tags out of the box. - neotags
https://gitlab.com/DanielSiepmann/neotags/
My own small neovim plugin. There are a lot of plugins out there that should auto update tags files. But most of them try to be to clever and didn't work in setups I had at older companies.
Therefore I've developed this small one. - neoterm
https://vimawesome.com/plugin/neoterm
Integrates a terminal into neovim, which allows to send commands to the terminal. I use that for smaller demonstrations where I can execute commands from a readme. I also use this together with "vim-test". - nerdtree
https://vimawesome.com/plugin/nerdtree-red
One of the most populars file browsers for vim. - phpactor
https://phpactor.readthedocs.io/en/master/
Is a standalone CLI application written in PHP.
It comes with a VIM plugin and allows provides Refactoring and Language Server Protocol. - tagbar
https://preservim.github.io/tagbar/
Adds a small UI like "structure" or "outline" in other editors and IDEs. Uses ctags to generate the outline and therefore is very flexible. - undotree
https://github.com/mbbill/undotree
Vim already contains a history of changes. This plugin makes it visible and allows to jump to specific states. - vdebug
https://github.com/vim-vdebug/vdebug
DGBP debugger client for vim. Allows to debug PHP (via xdebug), Python and other languages.
Comes with all necessary features like Evaluation, Watching, Breakpoints, Step debugging, etc. - vim-snipmate
https://github.com/garbas/vim-snipmate
Integrates snippets into vim. - vim-test
https://github.com/vim-test/vim-test
Integrates test execution inside of vim. Plays nice with neoterm and other solutions.
Allows to execute all tests in a file or single tests.
Is pre configured for a lot of different languages and testing frameworks. Yet it can easily be adjusted for special project setups.
Disclaimer:
I'm not really updating my plugins until there is something missing or a bug. I keep the environment as it is, as long as it serves me well.
Colorscheme ¶
Not much to say, everyone has his own preferences. I'm using my own custom theme. That one uses the same color as my website, my terminal, my desktop environment, etc.
Vim already has some colorschemes. But one can also easily add further. Some are available here:
autocommands ¶
I'm making heavy use of autocommands in certain areas. They are explained here https://neovim.io/doc/user/autocmd.html and here https://learnvimscriptthehardway.stevelosh.com/chapters/12.html.
A concrete example is my daily work with TYPO3 (an open source content management system). Such systems have many different caches in use to speed up the system. Those caches need to be cleared during development. When all caches are moved to file system, that is easily done:
augroup typo3
autocmd!
" Clear some caches depending on files saved.
" Only works if cwd is document root
autocmd BufWritePost **/Configuration/Backend/Routes.php :silent !rm **/var/cache/code/cache_core/BackendRoutesFromPackages_*
augroup END
The same can be used to restart web server on configuration changes.
key mappings ¶
One of the great powers of vim are the key mappings. They are short and most of the time easy to remember. Thanks to different modes, there are very few mappings that require keys like CTRL, SHIFT or ALT.
Users can define their own mappings or adjust existing mappings. In order to not accidentally replace existing mappings, one can prefix mappings with so called leader
.
More information about leader is available at:
- https://learnvimscriptthehardway.stevelosh.com/chapters/06.html
- https://neovim.io/doc/user/map.html#%3CLeader%3E
The following is a short list of my own mappings, which I've set up to access some often used features of plugins:
let mapleader = ","
nnoremap H ^
nnoremap L $
" Toggle paste mode
nnoremap v :set paste!
" Stop highlighting of search results.
nnoremap nh :nohlsearch
nnoremap p :CtrlP
nnoremap l :CtrlPBuffer
nnoremap r :CtrlPBufTag
nnoremap k :NERDTreeToggle
nnoremap f :NERDTreeFind
nnoremap b :TagbarToggle
nnoremap u :UndotreeToggle
nnoremap a :PhpactorContextMenu
nnoremap au :PhpactorImportClass
nnoremap tn :TestNearest
nnoremap tl :TestLast
nnoremap tf :TestFile
nnoremap so :call SortParagraph()
nnoremap gtt :call OpenPHPUnitTestFilename()
Custom Functions ¶
I've added some small functions to my own vim which you might find useful.
" Copy the current relative file path to clipboard
function! CopyRelativeFilePath()
execute ':let @+ = expand("%")'
endfunction
" Copy the current full file path to clipboard
function! CopyFullFilePath()
execute ':let @+ = expand("%:p")'
endfunction
" Remove trailing whitespace
function! StripTrailingWhitespace()
execute ':%s/\s\+$//e'
endfunction
External tools (ctags) ¶
Neither vi, nor vim or neovim follows the "all in one" approach. Instead they follow the "do one thing well". They therefore don't include some important parts themselves, but support them by 3rd party tools.
One prominent example are "tags". All three support the tags file format for navigating code. This feature nowadays is known as "Goto Definition". An editor therefore needs to know where something is defined. The editors provide that feature out of the box, but don't provide the indexing. Instead tool like ctags are used.
ctags is definitely a must have, as long as no plugin and LSP (=Language Server Protocol) is integrated. This allows navigating via the editor itself. Also mentioned plugins like tagbar and ctrlp will use this tool. So even when using LSP, you still might wanna use ctags.
Video ¶
Video v30: Unix Setup: neovim
Size: 134.26 MB
YouTube: 9hdiv8YBhy4
I'll explain my current setup of neovim.