Beginner’s Guide to Unite
Reader Sri Kadimisetty wrote in to ask for a guide to Unite (GitHub: Shougo / unite.vim, License: MOT) by Matsu Shougo. It has been compared to FuzzyFinder and ctrlp.vim, but it’s actually quite different, which is partly why people seem to find it confusing.
In this article I introduce Unite, with the goal of demystifying its main features.
What is Unite?
Unite is for quickly navigating between files in a project. It isn’t limited to files — other lists of things can be displayed and searched as well. This open-ended nature is probably what people find confusing about it.
Unite isn’t limited to searching files or buffers — it can comfortably handle both, and more. An API is provided so other Vim plugin authors can extend it to support other data sources.
Usage
Unite’s commands take the format :Unite source, where "source" is one of buffer, file, and file_rec.
buffer: Browse a list of the currently opened buffersfile: Browse the list of files in the current directoryfile_rec: Recursively list files under the current directory
Once a command has been issued, a new horizontally split window will open. For example, :Unite file will show a list of files in the current directory. The standard Vim Normal mode commands work — you can navigate the list using j and k, and search with /. If you press Enter over a file, Unite will open it. If the cursor is over a directory name, Unite will enter that directory and update the list.
Codes
If you enter Insert mode while in Unite’s window, the cursor will be moved to the top of the window where the > prompt is displayed. Typing will search the list -- this is where you can get behaviour similar to FuzzyFinder. Just like regular Vim, pressing <ESC> will leave Insert mode and go back to Normal mode.
Both Normal and Insert mode have mappings. For example, pressing a in Normal mode when the cursor is over a file will cause Unite to show a list of file manipulation commands. This list of commands is known as actions, and the list can be searched and invoked just like anything else in Unite.
Wildcards can be combined with actions. If I type :Unite file, then press * to mark all files, then type a to list actions, and finally select above, Unite will open all of the marked files in split windows.
Other Features
Unite also supports other file manipulation and navigation features. For example, :UniteBookmarkAdd will add a file to the bookmark list. Bookmarks can then be searched and manipulated with :Unite bookmark.
Unite doesn’t come with any mappings, but you can add some easily enough. The following will invoke :Unite file when <Leader>f is pressed:
nnoremap <Leader>f :Unite file<CR>If you just want Unite to behave like ctrlp.vim or FuzzyFinder, then you can do this by using this mapping instead:
nnoremap <Leader>f :Unite -start-insert file<CR>Unite accepts options. For example, -start-insert causes Unite to open with the prompt activated — subsequent typing will immediately cause Unite to search files.
If you’re not sure what <Leader> is, then see :help <Leader> in Vim. It basically allows shortcuts (mappings) to be namespaced, so to invoke these examples you should type \f.
Conclusion
Hopefully this article has demystified the main features of Unite for some of you. I feel like it’s a very interesting and idiomatic Vim plugin — it doesn’t try to simulate GUI IDEs but works in a way that’s consistent with Vim. I’m not sure if I like the way Normal and Insert mode analogues have been used, but it definitely feels natural after using it for a few days.
