Practical Tips for Neovim

Introduction

Learning how to use Neovim productively can be daunting or seemingly futile if you come from mouse-dependent GUIs. (That's most of us these days, if we're being honest.) It can be especially difficult if you want Neovim to replicate the same bells and whistles found in other contemporary word processors and code editors. For that you'll need to invest a lot of hours of research along with a lot of trial and error to set up the ✨💖perfect environment💖✨. Luckily, Neovim is a flexible text editor and you don't need to know all its commands to use it effectively. In this article I'll be sharing a few things I found useful when I started using Neovim.

Before we begin, it's worth mentioning a few things. The instructions in this post assume you're in a Debian-based environment and that you have some cursory knowledge of Linux and Neovim. If you're looking for a good Linux reference book, I highly recommend the Linux Pocket Guide by Daniel Barrett. And, if you haven't used Neovim's built-in tutorial, I recommend you try :Tutor before continuing. Lastly, you can always use the :help command on any of the features mentioned to pull up the Neovim docs from Neovim!

A Proper Installation

My first tip is that you understand how Neovim is installed on your computer and know what version you're running. This is essential if you plan on using plugins as they might not work on older versions. Certain features might also not be available and should you find an issue with Neovim, knowing how Neovim was installed and how to fix an install is great knowledge to have.

Neovim can be installed in a variety of ways, but from my experience, I think the latest stable appimage found on Neovim's Github release page is the best and easiest way to install Neovim. Part of why I like this approach is that appimages are easy to swap out and easy to manage. You might have to manually set this up, but at least it won't interact with your update habits; a sudo apt update && upgrade will not change your Neovim version which in turn won't break your plugins or settings.

If you've never used an appimage, here's a set of general instructions. Open a terminal in the folder where you've downloaded the appimage. Note, your shell's rc file is usually in $HOME and its name is based on what shell you're using. (BaSH:.bashrc, Zsh:.zshrc)

1. make sure the appimage is executable. (You can also right-click the appimage, go to properties and checkmark "Allow executing file as program".)

     chmod +x nvim.appimage
   

2. Move Neovim to $HOME/.local/bin; here I'm also renaming it to just 'neovim'

     mv nvim.appimage /$HOME/.local/bin/neovim
   

3. Add $HOME/.local/bin to your PATH in your shell's rc file.

     export PATH=$HOME/.local/bin:$PATH
   

4. Restart your terminal or source the shell settings file like so

     source ~/.bashrc
   

5. Now call Neovim from your terminal.

     neovim
   

Before we move on, it's worth also knowing where the default locations of your settings, data, and log files are. The config directory is ~/.config/nvim/. The data directory is ~/.local/share/nvim. Logs are in ~/.local/state/nvim.

Further Reading:

• Standard Paths

Using Motions effectively

Moving around in Neovim is probably the hardest hurdle for most new users to get accustomed to. It's tempting to want to reach out for the mouse or arrow keys. (Don't.) Movement in Neovim is built around the home row, it's meant to be paired with your touch-typing skills and this might feel strange at first when you come from a mouse-dependent GUI.

Motions

My best suggestion is to practice touch-typing. My second best suggestion is to experiment with all the motions Neovim has. Included below is a non-exhaustive list of motions you ought to at least know about. You need not use them all, but they might help you better understand how movement works in Neovim.

Object and Word motions are great when writing human-oriented languages, especially when writing long form content. Note, these motions can move you beyond the current line the cursor is on. (ex. Pressing w at the end of a line will move you to the next line down.) Also, keep in mind that you can pair these motions with operations such as d (delete) or y (yank) and prepend numbers to move in multiples.

Left-right motions are limited to the line you're on, they will never move you beyond the current line. Just like the object and word motions, the search motions on this list can have numbers prepended, such as 2fo to find the second instance of o on the line. ({char} is case-sensitive.)

Up-down motions move you linewise through a document. While this list is small, their use comes up often.

The last thing I mention in this part is the search command. It's not a motion but it can be used as one. use / followed by the pattern you want to search. The command will jump you to the next instance if it finds one. Use n to jump to the next instance or N for the previous instance, the search wraps around the file. You can search in reverse with ?. By default this search is case-sensitive.

Marks

Marks are little bookmarks that you can quickly return to. There are two types of marks, local and global. Local marks only work within their buffer and can be used in conjunction with operations. Global marks work between buffers, but they cannot be used with operations unless the mark is in the current buffer.

To set a mark, use m in normal mode, followed by a letter (m{a-zA-Z}). The letter case is what determines whether the mark is local or global. Lowercase is for local, uppercase is for global. In order to return to a mark, use a backtick or single quote followed by the letter you assigned that mark ( `{a-zA-Z} or '{a-zA-Z}). To delete a mark, use the:delmarks command followed by the mark(s) you'd like to remove. For example, :delmarks A-Z deletes all global marks from A to Z.

There's a couple things to note when working with marks. The mark will save the cursor line and column position. If the column position is deleted, the mark will return you to the next closest column. If the line is deleted, the mark will no longer work, unless you redo or undo that line deletion. Since local marks are restricted to their buffer it's possible to assign the same local mark across multiple buffers.

Apart from alphabet marks there are numeric marks. 0-9 marks are unique in that they store a history of the last cursor (line and column) position along with its file association from previous Neovim sessions. Both global and numeric marks are updated to the shada file when exiting Neovim so they can be used when you next open Neovim. `0 is set to the last file and cursor position when exiting Neovim from a file buffer. For example, say I saved and quit from init.nvim at line 10 column 23. Opening Neovim and calling mark `0 will return me to line 10, column 23 of init.nvim; notice that I don't have to open the file first in order to return to this mark since it's global.

As for the previous 0 mark, it will be set to `1 and so on, though Neovim will omit duplicates if you happen to have a session that ends in the same place. Therefore closing Neovim on line 10, column 23 will not save again, but if I moved to column 20, it would save that new position.

One final thing to note, say you jumped somewhere by mistake, you can use `` to jump right back to where you were!

Further Readings:

• Motions
• Marks
• Search Command

Buffers, Netrw, and Windows

Using buffers, Netrw, and windows effectively go hand in hand when it comes to creating an efficient and cohesive work environment and it's likely the first point of interest when looking at Neovim in action. Being able to open multiple files concurrently to edit, navigate, and cross-reference helps immensely when working on any project, but it can be easy to get lost if you're only used to having one file open at a time.

To start, buffers are in-memory copies of opened files. Windows are viewports for those buffers. When you open a file, Neovim creates a buffer of the file and then displays it on a window. Opening Neovim without a file argument will create an empty buffer on a window with its start page information.

You can arrange your workspace however you like. The most common arrangement in a workspace I've seen is one window per buffer, though some restrict themselves to only one window and jump between their buffers via global marks and buffer commands. Still others manage their buffers and windows with tabs. No method is better or worse from my experience, but whatever method you choose, make sure you understand the ins and outs of how to navigate your workspace.

To see a list of buffers use the :buffers or :ls command. It will produce something like the table below without the column names.

The first column is the buffer number; You can jump between buffers by pairing this number with the :buffer command (example: :buffer 3). The second column contains a set of flags which provide details about the buffer. See the table below for flag meanings.

• | This buffer can't be modified, useful when you want to make sure the file really is uneditable. Use :set nomodifiable to turn it on and :set modifiable to turn it off.
• | This buffer has been modified.

The third column is the file's filepath. If the current buffer has no file association, it will print "[No Name]" until you save/write that buffer to a file. The last column is the last cursorline position for that file. That way you don't have to keep jumping back to your place in the file when you move back to that buffer.

Now since we're using windows to work with buffers we should also know some simple window management commands.

You'll notice that the window commands re-use the same directional syntax as that found in normal mode. Technically you could also use the arrow keys, but I would advise against that. Another thing to note is that the commands for adjusting the window width are non-contextual so they might feel counterintuitive when facing their opposing edges.

Neovim, just like Vim, has a built-in file explorer plugin called Netrw. We can open the file explorer by using the :Explore command. This command will open a file explorer buffer either on a new window or the current window. It will only split into a new window if the current buffer has been modified and the global boolean hidden is not set; by default, hidden is set. Otherwise, the command will swap out the current buffer on the window with the file explorer buffer. From this buffer there is a Quick help list that will help you navigate Netrw. As with normal mode, you can move around with hjkl, pressing enter will open the file/directory the cursor is on and there are additional commands to edit files or rename them.

I haven't used Netrw in a while, so my advice is limited but I will say that if you want to keep your current buffer and not mess around with the buffer list as much, you can use other explore commands like :Vexplore and Hexplore. These will open the Netrw on a new vertical or horizontal window respectively.

Finally, tabs can help you expand your workspace beyond the limitations of your monitor. Tabs hold sets of windows and you can alternate between them with tab commands. Their use case might seem strange when you consider how a buffer can be called to any window, but part of Neovim's versatility is offering many ways to organize your workspace.

Use :tabnew to create a new tab. Neovim will move to that new tab on an empty buffer and at the top, you should see a new line indicating the tabs opened, this is the tablist. The current tab will be highlighted differently from the others. If you have more than one window open on a given tab, that tab will indicate the quantity of windows open. a + flag on the tab indicates that a buffer open in that tab has been modified. The name on the tab indicates which buffer the tab is focused on. Use :tabs to see a list of the tabs you have open and what number they correspond to; their number is subject to change based on its position in the tab list. Tabs are numbered from 1 onward. You can prepend a number to :tabnew to indicate where on the tab list you want the new tab to open, for instance :0tabnew will create that new tab at the far left of the list, that new tab will now be tab 1.

There are a variety of ways to cycle between tabs. To move to the next tab to the right of the tab list, use :tabnext, gt, or CTRL-PageDown. For :tabnext and gt, you can prepend a number to move by multiples. (Ex. :4tabnext moves by 4 tabs to the right.) To move to the previous tab to the left of the tab list, use :tabprevious, gT, or CTRL-PageUp. As before, you can prepend a number to :tabprevious or gT to move in multiples.

A thing to note with these movements is that the tablist wraps around. Additionally, you can go directly to any tab by providing the tab number to :tabnext; ex. :tabnext 1 to go to the first tab.

To close a tab, you can quit out of all windows in that tab or use :tabclose. Buffers you had open on this tab will become hidden. Neovim will warn you to save any edits if you forget you made edits to the buffers you opened on that tab, but the best practice is to always check your buffers before quitting.

Further Reading:

• The buffer list
• Windows
• Netrw
• Tabs

Basic Settings

Now that Neovim is installed and you understand a bit more about movement, there's probably a few settings you'd like to change about how Neovim works by default. Generally speaking, settings should only be added or changed when you find a use for them in your workflow and you understand what you are changing. Changes suggested online, even in this post, without proper understanding of those changes will produce unfun experiences. Think of your settings as a work in progress that will evolve as you develop your own workflow; you don't need all of it figured out in one go.

Below is a list of my most basic settings when I started using Neovim. I still use them in my day to day. You can make these same edits by following the instructions.

1. go to your config file.

   cd ~/.config/nvim/init.vim
   

2. If the file or directory doesn't exist, create them.

   mkdir ~/.config/nvim
   

3. Copy the settings you want, then restart Neovim.

   set number " shows line number at the left side of the buffer
   set autoindent expandtab tabstop=4 shiftwidth=4
   set cursorline " highlights the current line the cursor is on in the buffer
   set showmatch " highlights the matching pair for [] {} ()
   set showmode " displays the mode you are in on the last line of the buffer
   set ignorecase " ignores case-sensitivity when searching with /
   set incsearch " displays incremental search results for / searches
   set linebreak " linebreaks between words instead of characters
   set clipboard+=unnamedplus " enables system clipboard
   

The settings above should all be pretty straightforward in what they do. tabstop=4 and shiftwidth=4 set tabs and shifts to be four spaces long, for example. autoindent automatically indents on a new line if you are working on an indent dependent file, such as a Python script.

Perhaps the strangest setting here is set clipboard+=unnamedplus. On Linux, Neovim's clipboard is not automatically synced to your system's clipboard. This means you can't yank a line from Neovim and paste it (ctrl + v) elsewhere. To enable this function, unnamedplus must be appended to the clipboard options. The += notation here tells Neovim to add unnamedplus onto the list of clipboard options it uses rather than overwriting them.

Further Readings:

• Neovim's Default Settings
• Clipboard Integration - Neovim Docs
• Set your settings - Neovim User Manual

Mapping your own hotkeys

Neovim has a lot of neat hotkeys, but some can be unintuitive, unergonomic, or not quite what you want. Luckily, Neovim lets you map custom hotkeys in the config file. Below is a set of mappings I use in my day to day.

" Maps split movements from <ctrl + w + hjkl> to <shift + hjkl>
nnoremap <S-h> <C-w>h
nnoremap <S-j> <C-w>j
nnoremap <S-k> <C-w>k
nnoremap <S-l> <C-w>l

" Maps switch to normal mode (in insert and terminal mode) from Esc to jj
inoremap jj <Esc>
tnoremap jj <C-\><C-n>

The notes are pretty self-explanatory. The first settings let you move between buffers in normal mode by holding shift and picking a direction. I also changed how to exit into normal mode from insert and terminal mode to jj; a common mapping you've likely already seen. You'll notice different commands were used between the settings. If you're new to mappings, the section below contains a small intro.

What are maps?

At its core, the *map is a root command that tells Neovim to do X when you press Y. But because hotkeys can change depending on what mode you're in, you'll have to be specific about what mode you'd like your map command to apply to.

From the chart above, a single letter is prefixed to map to indicate a specific mode. :map works in most common modes such as Normal, Visual, and Select, but :imap works exclusively in Insert mode. This clarifies to Neovim your mapping intentions, but modes are not the only prefix you ought to consider.

By default, *map commands are recursive. This enables you to extend map commands on top of each other.

nmap s ggVG
nmap yds sysd

In the settings above, pressing s will select all lines of a file and leave you in visual line mode, let's walk through it.

1. gg moves your cursorline to the top of the file.
2. V enters visual line mode, selecting the current line.
3. G moves your cursorline to the bottom of the file, thus selecting all lines in the process.

Notice that the command can start in one mode and end in another and that doing so changes what the following commands do! Always take into account when a custom hotkey switches modes. Pressing G in visual line mode moves the cursorline to the bottom, as it would in normal mode, the difference here is that visual line mode selects lines as you navigate between them.

Now that s selects all lines in a file, we can extend that command further. We know that in visual line mode, d deletes selected lines, y yanks them. Let's walk through the second command.

1. Neovim sees s is mapped to ggVG and performs that hotkey function.
2. y yanks the selected lines
3. Neovim sees s is mapped to ggVG and performs that hotkey function.
4. d deletes selected lines.

This is all well and good, but because these maps are recursive, we may unintentionally create map commands that are infinitely recursive. Consider the map settings below.

nmap s ggVG
nmap sd sysd

Let's walk through the loop.

1. s selects all lines.
2. y yanks selected lines.
3. sd is mapped to sysd.
4. s selects all lines.
5. y yanks selected lines.
6. sd is mapped to sysd...

In this example, Neovim will continuously find sd is mapped to sysd and perform that action indefinitely. Press ctrl + c to exit this loop.

Now, the obvious takeaway here is to not include the calling method for your custom hotkey inside that hotkey's instructions, but if you end up extending your hotkeys it can get complicated because one map command can call another.

nmap i o
nmap o i

Therefore, it's generally recommended you only use the non-recursive forms of the *map commands when creating custom hotkeys. In order to use them simply add "nore" after the mode prefix. Doing so will limit you from extending other hotkeys but it will save you from creating infinite recursions.

Further Reading:

• Learn Vimscript the Hard Way
• Map Overview - Neovim Docs

Other small things

Finally, here's a list of cool commands I didn't know where else to include.

Sorting

If you ever have a list of lines you'd like to sort, there is a neat built-in feature called :sort.

In visual line mode, select the lines you'd like sorted, then use :sort. (:'<,'> is shorthand for your current selection range and what you will likely see after pressing colon on your keyboard.)

1. Take a list of things

   - 1 Krenko, Mob Boss
   - 1 Goblin Bombardment
   - 1 Conspicuous Snoop
   - 1 Impact Tremors
   - 1 Skullclamp
   - 1 Rising of the Day
   - 30 Mountains
   

2. and sort them alphabetically!

   - 1 Conspicuous Snoop
   - 1 Goblin Bombardment
   - 1 Impact Tremors
   - 1 Krenko, Mob Boss
   - 1 Rising of the Day
   - 1 Skullclamp
   - 30 Mountains
   

Complex Repeats (AKA Macros)

Neovim always has 10 different ways of accomplishing your task, but there are cases where you'll find yourself stuck with a repetitive task. In these cases, complex repeats can alleviate you from the legwork you would otherwise have to sludge through.

1. Start a macro recording: go to normal mode, press q followed by any letter or number. (this is case-sensitive.) For my example I will use y.
2. record your actions. For my example I have recorded the same commands I did in the map section ggVGy; this will yank all lines in a file.
3. end your recording by pressing q again.
4. replay your recording with @. (ex. @y)

In my example, the macro will copy all lines in a file. I can go ahead and open a new buffer and paste them, and then reuse @y in a third buffer and aggregate all files into a single buffer.

You can also replay your recordings in multiples. For instance, 100@y will copy all lines in a file 100 times! Additionally, complex repeats can use the same map commands set from the setting files. Again, always take into account when a recording enters a new mode as you would a map command; you will need to exit back into normal mode and press q in order to end the recording.

This feature seems common to stumble upon but perhaps this is an anecdotal bias reinforced by stackexchange. In most cases you won't find yourself wanting to use this but it's worth knowing about on the off chance you do need it.

Substitution

You can find and replace words with the substitution command. The command is a bit unique in that the terms you plan on finding and replacing will be a part of the command, they will be divided with a forward slash as seen below.

:<area>s/{find}/{replace}/{flags}

<area>s is required. It can be % to indicate every line in the file or 1,20 to indicate lines 1 through 20; ex. :&s or :1,10s. You could also enter VISUAL mode, select an area, and type :s which will appear as :'<,'>s.

/{find}/ is the search term. To include an actual forward slash use \/. You can use regular expressions for your search. You can see the words found as you type.

/{replace} is the replace term. You can see the replacements that will happen as you type.

/{flags} are optional. By default the :s command only substitutes the first instance in a line without confirmation after the command is run, you can add flags like g to make the substitutions global, meaning they happen to all instances in the <area>, or c to confirm each replacement one by one.

Using all of this together, we could write out the command to find "here" and replace it with "there" for the first 100 lines of a buffer and have the command do it for every instance with a confirmation dialogue like so: :1,100s/here/there/gc.

Terminal

Use the :terminal command to open a terminal. Just like a file the terminal is contained in a buffer. by default it should drop you in the directory from where you opened Neovim. If you had any virtual environments opened when you opened Neovim, it should inherit them. Use i to enter terminal mode. Type in your command. Use CTRL-\ CTRL-n to exit terminal mode. Or if you added the cool new custom hotkey I mentioned in the mapping section, use jj! 😎

Further Reading:

• Sorting
• Complex Repeats
• Substitution
• Terminal

Conclusion

There's a whole lot more I'd like to include in this post, like my favorite themes and plugins. But I think that's a matter of preference and strictly outside the scope of what I wanted to accomplish with this post. Plugins can dramatically alter the look, function, and feel of Neovim, and I think that introducing fancy plugins without proper knowledge of the default systems Neovim presents can be limiting in some ways. Anyway I hope this post has helped you. Shoot me an email if you liked the post and read to the end. Thanks!