William Estep

My journey to retire and sail. Writing, reading, technology, programming, photography, coffee, equality, sailing, and the oxford comma.

How I Navigate My Notes in VIM

Category: Technology
Tags: writingvim

At the core of Getting Things Done is having a system you trust. My system revolves around a core of text files I can access from my laptop, desktop, and mobile devices.

I keep my notes and thoughts in text files, generally in markdown format, in a Notes folder in Dropbox.

On the Mac, I generally have a terminal window open (iTerm2) with my work projects file open in one tab and two or three other relevant files open in other Vim tabs/viewports.

Working With Multiple Files

Vim has several options for working with multiple files: Buffers, Viewports, and Tabs.

Buffers are files loaded into memory. Think of it as files in a stack. For example, you can have several files open, each in it's own buffer, and switch easily between them. Some simple commands to know for buffers:

  • :bn: Switch to next buffer.
  • :bp: Switch to previous buffer.
  • :ls: List current buffers.

Viewports are splits or windows on the screen. Viewports are views into buffers, but you can have multiple viewports open on the screen at the same time. Some important viewport commands are:

  • :help ctrl-w: Lists all of the windows commands because most begin with ctrl-w.
  • :sp filename: Opens a file in a new split.
  • ctrl-w w: Toggles between open windows.

Tabs are what you would expect, it's different tabbed panes in the same terminal window, and each tab can have it's own viewports/windows. Tabs are fun, and can be a great way to have multiple files open and easily switch between them while maximizing your screen realestate. Some good tab commands are:

  • :tabnew filename: Open a new tab with the file identified.
  • :tabn or gt: Go to the next tab.
  • :tabp or gT: Go to the previous tab.

Also, as a Vim user, it's really important to understand the help system and get used to navigating the help. The one command I need the most and forget the most is:

  • ctrl-]: This will advance to the help section under the cursor.

Naming Convention

Moving around all of my Notes is an important part of my workflow. One of the reasons I keep all of my notes in text files, and in one folder, is so I can easily search for and find what I'm looking for, even if it's in a file I haven't touched in a while.

My first method of finding files is by file names. I try to keep to a fairly consistent naming convention along these lines:

    [Prefix]x[Other Tags]x[Descriptive Title]

The prefix is a context, and here are some I use regularly:

  • wrkx: Work
  • bpx: Blog Post
  • wrtx: Writing File
  • tpx: Project Files. (I used to keep these in taskpaper format, but generally don't now. They are just markdown files now, but the tpx prefix still works for me.)
  • vex: Video Editing files
  • sbx: Sailboat and sailing related files. (See the ten year plan.)
  • refx: Reference files. For example, I have a refxvimxNotesAndCommands.md file that keeps my personal Vim FAQ's.

The other tags could be anything I think will help me differentiate the files if needed, for example, it may be file about a particular work project, so I might include that as another filename tag.

Notice all the tags are separated by x. I borrowed this naming idea from Merlin Mann. The separator is easy to set even on an iOS device.

Having the files stored in one central place, and easily accessible and synced across devices is the future. So handy!

On iOS I use Editorial to add/edit/work with my notes. On the mac, I generally use Vim in an iTerm terminal, and I will occasionally use nvAlt.

So down to the point of this post, how do I navigate my notes, and find what I'm looking for in Vim?

Browsing Files

For browsing, there are two main options, NerdTree and netrw. I started out using NerdTree, because it really feels like the 'project drawer' from familiar applications like textmate. But it didn't fit into my workflow very well. I couldn't get the feel of moving from one window to the next, and opening files where I need them. I probably didn't spend enough time getting used to NerdTree, and I should give it another try in the future, but for now, I use netrw with tpope's vinegar add on.

Netrw has a lot of features geared toward reading and writing on remote systems. While extremely handy, that's not something I deal with often, so I'm not going to cover it. Check out the netrw help for details.

To bring up a file listing for the current directory:

vim .

Or to open a listing in the current window:


And with the added magic of the vinegar plugin, open a listing in the current window by pressing -. The file list is focused on the current file, and pressing - again moves up a directory.

Note that the vinegar plugin removes the header lines from netrw. You can bring the header lines back with I (toggles on and off).

Browse around the file list with the normal navigation keys (h,j,k,l), pressing enter to dive into a file, or down a directory.

Search the list like any buffer by pressing / and typing a phrase to search.

Here's another command I frequently have to look up again, to clear the previous search highlighting:


Searching and Fuzzy Searching

Another very powerful plugin is ctrl-p. As you might expect, the plugin is activated by pressing ctrl-p. A small window opens at the bottom of the screen showing a file list. The power with ctrl-p is it's fuzzy search approach to finding files. Remember my naming convention? I can press ctrl-p and type wrkx and I'm almost immediately presented with a list of all the files in the current folder or child folders that match the pattern.

Using ctrl-p can be very fast and rewarding. It's a great plugin and worth getting to know in detail. A couple of key commands to know:

  • ctrl-x: Open the selected or highlighted file in a new split window.
  • ctrl-v: Open the selected or highlighted file in a new verticle split.
  • ctrl-t: Open the selected or highlighted file in a new tab.

Check out

:help ctrlp-commands

for a complete list of commands.

So let's assume I know I wrote something in a note file somewhere, but don't remember the name, or I've been hunting by name and I'm not finding what I'm looking for. Time to search through the files.

That means breaking out the powerful grep options in Vim. Vimgrep is my go to choice.

:vimgrep /pattern/ *

The above will search all the files in the current directory for the pattern.

The results appear in the status area in a quick-fix list. Moving forward and backwards in the quick-fix list is done by:

  • :cprev: Moves to the previous entry.
  • :cnext: Moves to the next entry.

Another important tpope plugin called unimpaired adds easier to use key mappings:

  • ]q: Moves to the next entry.
  • [q: Moves to the previous entry.

If I haven't found the file by this point, it probably doesn't exist. Or more likely, I broke one of my rules above and put the file somewhere other than my notes folder.

Let me know if you found this useful, or if you have text file tricks of your own.


Similar Posts

© William Estep