-.- --. .-. --..

Magic of netrw in Vim 🎩💥

02 Jul 2017

One of the features of Vim I use less is it’s ability to edit files over network. This is possible thanks to the netrw plugin—it’s the file browser thingy that pops open when you accidentally end up opening a directory in Vim instead of a file.


Modern versions of Vim (unlike Vi for instance) will have this plugin auto-installed, and enabled by default. The main aim of this plugin is to make file browsing locally and over the network easy. The way this works is Vim displays a file browser and the contents piped into it by certain external commands depending on the protocol. For instance, it uses the ssh protocol via the scp command when accessing files over that protocol. You can in fact substitute other applications for the external command setting in vim for each of the protocol.

Editing Workflow

My most common usage of ssh these days at work is to edit nginx configuration files. There are two files that I need to check/edit, and the general workflow I follow is open the ssh connection, edit/view the files, exit the remote shell.

I also have an ssh config entry setup, so that I don’t have to provide the key, IP/hostname, port every time I type the ssh command. One more key point is that the nginx config files are located in a folder the same user’s directory tree, which I’m using to log in. These files get symlinked into the default nginx config file path (/etc/nginx/ directory by default on Linux machines).

Commands involved:

ssh nginx_config # (twice in two windows)
vim nginx/sites-enabled/filename1 nginx/upstream/filename2
# edit the file(s) if needed

Although this works fine for me, and is fast enough because of all the shell muscle memory going on, I think I can do better. Note that I have passphrase-less login setup for the ssh host, and this is key for using it with netrw. This the workflow with netrw:

vim scp://nginx_config/nginx/sites-enabled/filename1 scp://nginx_config/nginx/upstream/filename2

One thing to note is that scp doesn’t support sudo workflows, so we won’t be able to save a file in a directory that the ssh user doesn’t have access to.

If I were to directly edit the files in the default config path, under the root directory, assuming I have root access ssh config also setup, I can do something like:

vim scp://nginx_config_root//etc/nginx/sites-enabled/filename1 scp://nginx_config_root//etc/nginx/upstream/filename2

Note the double slashes right after the host config name. This is because the etc directory is situated under the root directory tree.

Some shells fetch the metadata of the folders if you hit Tab to autocomplete the file/folder name! (Although this might be a bit slow the first time).

Since we know the path to the files ahead of time, the file list argument above can be simplified to:

vim scp://nginx_config/nginx/{filename1,filename2}

One of the more aesthetic advantages of using netrw is you get syntax highlighting that you might have already setup on your local machine!

Browsing workflow

Sometimes you might want to browse the folder tree rather than start editing right away. Since netrw also bundles a directory tree browser, this becomes straight forward. Let’s say I want to check the folders under /etc/nginx, knowing that I don’t have edit access, I can do something like:

vim scp://nginx_config//etc/nginx/

Note:The trailing slash is important for vim to figure out that it’s a folder tree you’re seeking.

Some common commands you can issue in this file-browsing view are shown in the title panel above. For example:

"   Quick Help: <F1>:help  -:go up dir  D:delete  R:rename  s:sort-by  x:special

All the available key maps in this mode are listed in the documentation


As with every Vim plugin, the netrw plugin is highly configurable. Even if you just stick to the ssh/scp workflow I mentioned above, it’s a fraction of the functionality offered by the plugin.

The config I use in my vimrc is:

let g:netrw_liststyle=3

" Lifted off from http://blog.g14n.info/2013/07/my-vim-configuration.html
" when navigating a folder, hitting <v> opens a window at right side (default
" is left side)
" Thank you!
let g:netrw_altv = 1