vim with the taglist plugin and exuberant ctags

First of all, let me introduce Ctags and the Taglist plugin:

Ctags generates an index (or tag) file of language objects found in source files that allows these items to be quickly and easily located by a text editor or other utility. A tag signifies a language object for which an index entry is available (or, alternatively, the index entry created for that object).

The "Tag List" plugin is a source code browser plugin for Vim. This plugin
allows you to efficiently browse through source code files for different
programming languages

Ctags must be installed in order for you to use the taglist plugin. Once you have installed ctags and the taglist plugin, some fantastic features in vim are
available to you. In short, the taglist plugin allows you to open a "side bar" inside of vim; this side bar is similar to the side bar in popular IDEs (e.g., eclipse, MS visual studio) and enables you to browse files and source code. For example, when a file is selected in the side bar, that file will be opened in the main window. Similarly, when a function or method is selected in the side bar, the main window will jump to that function or method. Ctags also enables you to jump from a symbol/function call/variable to its definition.

Here are the steps to get started :

1. Install vim and/or gvim if you don't have them installed already.

2. Install exuberant ctags, I was unable to install ctags version 5.7 on openSUSE 10.2, but ctags-5.6 installed fine. Exuberant ctags can be found at http://ctags.sourceforge.net.

3. Download the taglist plugin zip file for vim. Unzip the file and move the plugin/taglist.vim file to the vim plugin directory (e.g., /usr/share/vim/vim70/plugin). Move the doc/taglist.txt to the vim doc directory (e.g., /usr/share/vim/vim70/plugin).

4. Change to the vim doc directory directory, start Vim and run the ":helptags ." command to process the taglist help file. Without this step, you cannot jump to the taglist help topics.

5. Go to a directory in which you have code stored and create a tag file. This is accomplished by runnings 'ctags [-R] (the -R is an option to recurse into subdirectories). For example, assume I have a collection of python files in some directory and some subdirectories that make up a single project. I would use the following command to create my tag file: ctags -R *.py. If you're using a programming language like C/C++ that uses mutliple file extensions, read about the -h option in the ctags manual.

6. Open vim and type :TlistToggle to open the taglist window. A great shortcut for this is to map a funciton key adding 'nnoremap :TlistToggle to your .vimrc file. This would allow you to simply press F8 in vim to toggle the taglist window opened and closed.

7. Add files to the taglist window. This is done using the :TlistAddFiles or :TlistAddFilesRecursive commands in vim. In my example pyhon project, I would type ':TlistAddFilesRecursive ~/programs/myproject *.py' to populate my taglist window with all of the python files in my project. After your taglist window is populated it should look something like this:

By default the taglist window opens on the left side. In vim, the taglist window is just a vertical split. You can read more about managing split windows in the vim documentation, but one basic command is to use ctrl+ww to switch between splits. In the taglist window you can then use the enter key to open files in the main window; if you press the enter key while the cursor is on any definition (variable, function etc.) in the taglist window, the appropriate file will be opened in the main window and the cursor will jump to the definition in the file. The + and - keys expand and contract items in the taglist window respectively. For example, in the screenshot above the "function" items are all expanded. However, the "class" and "members" items directly below "image_this.py" are contracted. Other neat features include using the = key to expand all items and the * key to contract all items. In fact, "expanding" and "contracting" text is a standard vim feature known as folding, you can learn more about it in the vim documentation.

8. Obviously, configuring your taglist window every time you open vim would be quite painful. Once you have your taglist window configured for your project, use the ':TlistSessionSave command to save a session, and use the ':TlistSessionLoad command to load a session. Session files are saved in the current working directory.

9. If you haven't done it already, try some of the following tasks in gvim (graphical vim):

- use your mouse to expand the taglist window by clicking and dragging the vertical split line

- switch to the taglist window with a simple left click in the taglist window.

- try double clicking files, functions, classes, etc. in the taglist window to open them in the main window.

- try expanding and contracting items (folds) with left clicks

10. As a bonus, notice a nice little feature that ctags gives us. You can now use ctrl-] or g] when your cursor is on any symbol (variable, function call, etc.) to go to its definition. ctrl-] will do its best to take you where it thinks the definition is, while g] will give you a list of possible declarations. After having used ctrl+] or g] a few times in succession, use ctrl-t to start going back up the tag stack.

11. Use vim or gvim for your next coding project.

Personally, I also added 'let Tlist_Exit_OnlyWindow = 1' to my .vimrc file. This is useful because (as stated above) the taglist window is opened as a vertical split. This means when you close the main window the taglist window will stay open unless you add this option to your .vimrc file. In short, this option closes vim when the taglist window is the only window open.

Please add comments if you have any advice associated with ctags and/or the taglist plugin!