vim: lightning fast navigation in a large software project

Love vim but need to work with a large software project that spans a dozen subdirectories and a bazillion source files? There are plenty of solutions, vim scripts or external tools, for this particular problem. Here is one that I've used for years: using the marvelous project script.

It comprises one .vim file (the script) and .txt file (the documentation), thus dead easy to install. After that, just launch vim using: vim +Project (replace vim with gvim if you favor the GUI version), the side pane will be visible. There is where the project tree will be displayed.

For a quick start, type \C and you will be prompted to answer 4 questions, as the example below (my answers are in bold)

Enter the Name of the Entry: KOffice
Enter the Absolute Directory to Load:/home/ariya/koffice/source
Enter the CD parameter:
Enter the File Filter: *.cpp *.h *.c

which, as you might guess, create an entry with the given name from all C/C++ headers and sources from the specified directory. Wait a few seconds (or minutes, depending on the project size) for the script to scan files in your disk, at last it will show the tree (as in the screenshot above) in the project window.

You can, of course, add as many entries as you want.

Note: for optimal usage, do not forget to put this on your .vimrc file:

:let g:proj_flags="imstvcg"

For details on the meaning, see the script documentation.

Navigating the project tree is easy, if you are familiar with the vim folding. In principle, use zo and zc to open and close the fold right where the cursor is located, or zO and zC to apply it recursively, i.e. for the whole entry.

How to open a file? Just place a cursor in a file name and press Enter. Since the project window is just a normal window, switching back and forth between the project window and main editing window is as easy as Ctrl+W w. Or you can use F12 to quickly show and hide the project pane. In addition, pressing Space toggle the wide and small version of project pane.

Some more tricks. Because the project window is just a normal vim window, use the blazing fast incremental search (along with n or N) to spot the file that you want. It even does allow you to jump between different matches quickly. Again, if the project window is too narrow, hit Space to make it wider and another Space will return the width back to normal. If you press Enter on a filename to open it, a wide project window is toggled to the usual width automagically. Master this technique and you will open any file you need in an instant.

Because I love tabbed editing, I also have this in my .vimrc:

:map <C-T> <Esc>:tabnew<CR>

so that Ctrl+T opens a new empty tab. Wherever I am, I can open KSpread's Cell.cpp (to have a quick look, hence in a new tab) as fast as hitting Ctrl+T, F12, /Cell.cpp, Enter. Try to beat that.

But that is not all. You might ask: what's the use of a big file list if I don't know which file I need to open? Right, because everyone (and his dog) just needs grep. Use \G (which will use vimgrep) and type in your search string. After a while, all the matches are listed in another small window. Choose one that you want and hit Enter, all the magic ensures that the corresponding file will be opened and the cursor is right located in the matched line.

For more features, e.g. rescan the files from disk, adjust the pane width, execute a command on a file, non-global project tree, etc., refer to the script documentation.

Untap the potential of this wonderful vim script and a 3000-files project is not a burden anymore!