My Neovim Configuration and Cheatsheet

Since I don’t currently use neovim at work, it can be hard to consistently remember the custom mappings, plugins, etc and how it all works. This post will serve as a reference and explainer so I don’t get lost in the future.

In the past, I spent hours crafting my vim config, but I didn’t end up using it often enough for the custom mappings to stick, and I slowly forgot how everything worked and didn’t want to maintain the config. But after some time being frustrated with some of the limitations of vscode + vim, I decided to try again with a focus on simplicity, maintainability, and documentation.

So in the spirit of documenting my configuration and making it approachable, I have sections describing the concepts behind the configuration, important commands, and how to extend the configuration in the future.

This post will be updated in the future as the configuration inevitably changes.

Configuration #

First things first. I trashed my old init.vim for an init.lua, which I ripped directly from this youtube video by ThePrimeagen. I made some modifications and additions to fit my prefernces, which can be found in my neovim-config repo.

I also made notes in the configuration files where I felt like future me would need some clarification, so be sure to checkout the respository for more details.

Config File Organization #

All of the configs are stored in ~/.config/nvim with the structure outlined below.

├── after
│   └── plugin              <-- plugin configs
│       ├── colors.lua
│       ├── fugitive.lua
│       ├── harpoon.lua
│       ├── telescope.lua
│       ├── treesitter.lua
│       └── undotree.lua
├── init.lua                <-- config entry point
├── lua
│   └── micah               <-- custom vim config
│       ├── init.lua        <-- set general config
│       ├── packer.lua      <-- add plugins
│       ├── remap.lua       <-- add remaps
│       └── set.lua         <-- set vim options
└── plugin
    └── packer_compiled.lua <-- don't touch

Plugins #

The list below seems to keep growing as I expand my use cases, but here is what it is for now:

• Plugin Manager: Packer
• Fuzzy Finding: Telescope
• File Switching: Harpoon
• Syntax Highlighting: TreeSitter
• Undo/Versioning: Undotree
• LSP: LSP Zero
• Jupyter Integration: Magma.nvim

Using Packer #

Packer is the plugin manager, that allows all other plugins to easily be installed by referencing their github repo. Because of this, it requires a slightly different installation method, which can be found in the readme of my neovim-config repository.

Once installed, you add plugins by updating the ~/.config/nvim/lua/micah/packer.lua file with a new “use” statement, then running :so to source the packer.lua file and running the :PackerSync command, which tells packer to install (and update) all of the plugins listed in the configuration.

Navigating Files and Folders #

There are 3 main tools for file navigation: NetRW, Telescope, and Harpoon.

• NetRW is a file tree

• Telescope allows for fuzzy finding of files, git project files, and various froms of grep search. (Telescope can do a lot more too)

• Harpoon allows you to add files to a quick access list and switch quickly between them using a toggle menu or hot keys.

Using NetRW (File Tree) #

Full configuration reference: using-netrw-vim-builtin-file-explorer

There are a couple of options for using netrw, but for now I have settled on using :Lexplore, which presents a sidebar style file tree that can be toggled with <leader>pv. When selecting a file from netrw, the buffer is opened to the right side. If a buffer is already open to the right, it is replaced by the selected file. So far this is what works best with my workflow. The only problem at this point is that toggling the tree resets the view and collapses all files. There may be a way around this, but I haven’t spent the time to figure it out.

Using Harpoon #

Harpoon allows you to mark files and then quickly switch between them. Add files using <leader>a and see those files with the quick switch toggle Ctrl+e. While in the quick switch list, files can be reordered or removed using regular vim motions. You might ask why you would want to prioritize the quick switch list. The answer is that the the top 4 files can also be switched using the hotkeys Ctrl+ j(1),k(2), l(3), and ;(4). I have found harpoon to be a similar experience to tabs where you can quickly interact with a subset of active files and close them out when you are done.

Note: Harpoon also has a terminal feature, which I haven’t explored yet. Mabye one day I will.

Using Telescope (Fuzzy Search) #

Telescope provides all the fuzzy searching you could want. While there are many things to do with telescope, I have setup git project search, general file search, and two forms of grep in the current project context. The two grep options warrant a bit of explanation. The first type is live grep, which pulls up a telescope modal that refines your search as you type. The second type of grep takes a grep string prior to opening a telescope window, from there you can further refine your search from the inital results, but you are always in the scope of results returned by the inital grep string.

Note: Ripgrep is required for a lot of the functionality telescope provides

Mac:

 brew install ripgrep

Linux:

 sudo apt-get install ripgrep

Using LSP Zero #

LSP Zero is a project that bundles a lot of configuration and other dependencies that are needed to get LSPs and autocomplete working well in neovim. Once installed, it relies on mason.nvim to provide an easy way to mange LSP servers, formatters, and linters.

Configuration of LSP Zero happens in ~/.config/nvim/after/plugin/lsp.lua. Here you can specify which LSPs you want to always have installed, define keymappings, and configure the behavior of individual LSPs. Once feature that I use in my configuration in particular, is the on_attach hook, which defines and activates keymappings only when a language server is attached to the current session. This allows for neovim to do its best with commands like <leader>gd (go to definition) when a language server does not exist or is not running for any reason.

When running an LSP it provides diagnostic information about the code line by line. These diagnostics are indicated by an icon in the gutter as well as virtual text to the right of a line’s content. There are several ways to interact with these diagnostics.

Using Mason To Install LSPs #

Interact with Autocomplete Menus #

• Interact with an autocomplete list:
  • Next item -> Ctrl + n
  • Previous item -> Ctrl + p
  • Accept item -> Ctrl + y
• Dismiss the list with -> TODO:

Navigating buffers #

• Jump Cursor (in current view)

  • Top -> H
  • Middle -> M
  • Bottom -> L

• Jump by half pages (customized to place cursor in center of screen)

  • Up -> Ctrl + u
  • Down -> Ctrl + d

• Word jumps

  • w -> next word
  • e -> end of current word
  • b -> previous word

• Jump List: keeps track of previous cursor position

  • Previous cursor position -> Ctrl + o
    • Use this to jump back from a gd (go to definition) that takes you to a different file.
  • Next cursor position -> Ctrl + i

• Jump Between Windows

  • Ctrl + w, + hjkl

Using Git #

Vim Fugitive is used as the git interaction plugin. Here are the basics.

There is a lot more that vim-fugitive can do, but this gets the basics done for now. For a full reference see the vim-fugutive docs

• Use <leader>gs to open a git status buffer. You can stage changes with s or unstage changes with u. You can also visually select multiple lines to create a chunk that you can apply commands to.

• To view the diff of a file vs its latest change in git use :Gdiff.

• To commit code, use the :Git command follow by any normal git cli command.

  • :Git commit -m “my message”
  • :Git commit (pulls up temp buffer to create a commit message)

Visual Line Selction #

• While holding the shift key on a visual line selection, use j and k, to drag the lines up and down

Quick Reference #

Note that <leader> is the space key

This is a somewhat random list of commands that I find useful and want to remember. The remaining sections will be a bit more in depth and organized.