Ctags and Taglist: Convert Vim Editor to Beautiful Source Code Browser for Any Programming Language

by SathiyaMoorthy on April 20, 2009

Code C Program using Vim Editor
Photo Courtesy: mint imperial

This article is part of the on-going Vi / Vim Tips and Tricks series. As a programmer or system administrator, you will be constantly browsing source codes and shell scripts.

Following are some typical activities that you may perform while browsing a source code file:

  1. Navigating to the function definition by specifying the function name.
  2. Navigating to the function definition from ‘function call’.
  3. Returning back again to function call from the definition.
  4. Viewing the prototype/signature of functions or variables.
  5. Viewing the number of functions in a file, etc.,


In this article, let us review how to perform the above activities efficiently in Vim editor using ctags and taglist plugin.

The techniques mentioned in this article using Vim editor can be used for any programming language.

I. Ctags Package Install and Configure

Step 1: Installing ctags Package

# apt-get install exuberant-ctags

(or)

# rpm -ivh ctags-5.5.4-1.i386.rpm
warning: ctags-5.5.4-1.i386.rpm: V3 DSA signature: NOKEY, key ID db42a60e
Preparing...          ########################################### [100%]
   1:ctags            ########################################### [100%]

Step 2: Generating ctags on your source code

Go to the directory where your source code is located. In the example below, I have stored all my C programming source code under ~/src directory.

# cd ~/src

# ctags *.c

The ctags command will create a filename tags the will contain all required information (tags) about the *.c program files. Following is partial output of the tags entries in the ctags file.

# cat tags
AddAcl  dumputils.c     /^AddAcl(PQExpBuffer aclbuf, const char *keyword)$/;"   f       file:
ArchiveEntry    pg_backup_archiver.c    /^ArchiveEntry(Archive *AHX,$/;"        f
AssignDumpId    common.c        /^AssignDumpId(DumpableObject *dobj)$/;"        f

II. 4 Powerful Ctags Usages inside Vim Editor

1. Navigate to function definition by specifying the function name using :ta

In the example below, :ta main will take you to the main function definition inside the mycprogram.c

# vim mycprogram.c
:ta main

By using this facility you can navigate to any function definition by specifying the function name.

2. Navigating to the function definition from ‘function call’ using Ctrl + ]

When the cursor is under the function call, then press CTRL + ] to go to the function definition. In the following example, when the cursor is in the function call ssh_xcalloc, pressing Ctrl + ] will take you to the ssh_xcalloc function definition.

# vim mycprogram.c
            av = ssh_xcalloc(argc, sizeof(char *));

Note: If the ctags couldn’t find that function, you’ll get the following message in the vim status bar at the bottom: E426 tag not found ssh_xcalloc

3. Returning back again to function call from the definition using Ctrl + t

Press CTRL + t which will take back to the function call again.

4. Navigating through a list of function names which has the similar names

In this example, :ta will go to the function definition whose name starts with get, and also builds a list to navigate with the relevant functions.

# vim mycprogram.c

:ta /^get

Following vim commands can be used to navigate through relevant functions

  • :ts – shows the list.
  • :tn – goes to the next tag in that list.
  • :tp - goes to the previous tag in that list.
  • :tf – goes to the function which is in the first of the list.
  • :tl – goes to the function which is in the last of the list.

III. Taglist Plugin: Vim Editor as Ultimate Source Code Browser

The above Ctags might have not given a source code browsing feeling, as it is driven by commands instead of visually browsing the code. So if you want to navigate through the source as like navigating in the file browser, you need to use vim taglist plugin which makes vim as a source code browser.

Author of the vim taglist plugin Yegappan Lakshmanan, says about it as

The “Tag List” plugin is a source code browser plugin for Vim and provides an overview of the structure of source code files and allows you to efficiently browse through source code files for different programming languages.

Step 1: Download the Vim Taglist plugin

Download it from from vim.org website as shown below.

$ cd /usr/src

$ wget -O taglist.zip http://www.vim.org/scripts/download_script.php?src_id=7701

Step 2: Install the TagList Vim Plugin

$ mkdir ~/.vim # if the directory does not exist already

$ cd ~/.vim

$ unzip /usr/src/taglist.zip
Archive:  /usr/src/taglist.zip
  inflating: plugin/taglist.vim
  inflating: doc/taglist.txt

Step 3: Enable the plugin in the ~/.vimrc

Add the following line to the ~/.vimrc to enable the plugin for Vim editor.

$ vim ~/.vimrc
filetype plugin on

Pre-Requisite: ctags should be installed to use taglist plugin. But it is not a must to generate the tag list manually by ctags command for using taglist plugin.

IV. 5 Powerful Features of Taglist Vim Plugin

1. Open the Tag List Window in Vim using :TlistOpen

# vim mycprogram.c
:TlistOpen

From the vim editor, execute :TlistOpen as shown above, which opens the tag list window with the tags of the current file as shown in the figure below.

Function Browser Window inside Vim Editor
Fig: Vim – Source Code Tag/Function List Windows

2. Jump to the Function Definition inside a source code

By clicking on the function name in the left panel, you would be able to go to the definition of the function as shown in the Figure below.

Jump to a Function inside Vim Editor
Fig: Jump to a function definition quickly

Apart form jumping to the function names quickly, you can jump to classes, structures, variables, etc., by clicking on the corresponding values from the tag-browser in the left hand side.

3. Jump to the function definition which is in another source file

When you are going through a function in a source file and would want to go to the function definition which is in another file, you can do this in two different methods.

Method 1:

If you had the ctags generated for that file, when the cursor is in the function call pressing CTRL + ] will take you to the function definition. And automatically the tag list window will show the tags for that newly opened file.

Method 2:

Open another file also in the same vim session which will update the tag list window with the information about that file. Search for that function name in the tag list window, and by pressing <CR> on that function name in the tag list window you can go to the function definition.

4. Viewing the prototype/signature of functions or variables.

Press ‘space’ in the function name or in the variable name in the tag list window to show the prototype (function signature) of it in the VIM status bar as shown below. In the example below, click on selectDumpableTable function from the Tag-window and press space-bar, which displays the function signature for selectDumptableTable function in the bottom Vim Status bar.

Display Function Prototype inside Vim Editor
Fig: Display Function signature at the Vim Status Bar

5. Viewing the total number of functions or variables in a source code file

press ‘space’ in the tag type in the tag list window, which shows the count of it. In the example below, when the cursor is at ‘function’ press space, which will display the total number of functions in the current source code.

Display Total Number of functions for a source code inside Vim Editor
Fig: Display the total number of functions available in the source code

For effectively writing new source code files using Vim, please refer to our earlier articles:

Recommended Reading

Vim 101 Hacks, by Ramesh Natarajan. I’m a command-line junkie. So, naturally I’m a huge fan of Vi and Vim editors. Several years back, when I wrote lot of C code on Linux, I used to read all available Vim editor tips and tricks. Based on my Vim editor experience, I’ve written Vim 101 Hacks eBook that contains 101 practical examples on various advanced Vim features that will make you fast and productive in the Vim editor. Even if you’ve been using Vi and Vim Editors for several years and have not read this book, please do yourself a favor and read this book. You’ll be amazed with the capabilities of Vim editor.

Awesome Vim Editor Articles

Following are few awesome Vi / Vim editor tutorials that you might find helpful.

Note: Please subscribe to The Geek Stuff and don’t miss any future Vi and Vim editor tips and tricks.


Linux Sysadmin Course Linux provides several powerful administrative tools and utilities which will help you to manage your systems effectively. If you don’t know what these tools are and how to use them, you could be spending lot of time trying to perform even the basic administrative tasks. The focus of this course is to help you understand system administration tools, which will help you to become an effective Linux system administrator.
Get the Linux Sysadmin Course Now!

If you enjoyed this article, you might also like..

  1. 50 Linux Sysadmin Tutorials
  2. 50 Most Frequently Used Linux Commands (With Examples)
  3. Top 25 Best Linux Performance Monitoring and Debugging Tools
  4. Mommy, I found it! – 15 Practical Linux Find Command Examples
  5. Linux 101 Hacks 2nd Edition eBook Linux 101 Hacks Book

Bash 101 Hacks Book Sed and Awk 101 Hacks Book Nagios Core 3 Book Vim 101 Hacks Book

{ 21 comments… read them below or add one }

1 Nagalenoj April 20, 2009 at 11:17 pm

Nice article.

2 sasikala April 21, 2009 at 12:23 am

this could be one of the best article in your posting..
thanks.

3 Ramesh April 21, 2009 at 9:38 am

@Nagalenoj, @Sasikala,
 
Thanks for your comments. Like always, Sathiya has produced another great article on Vim/Vim Editor.
 
This is definitely a great way to get most out of Vim Editor for serious programmers and admins who are constantly working with source codes.
 

4 BalaC April 22, 2009 at 9:57 am

I think you can also include cscope ( http://cscope.sourceforge.net ) another great vim plugin which i have been using while working in a project which has about 6000 files.

cscope allows searching code for:

# all references to a symbol
# global definitions
# functions called by a function
# functions calling a function
# text string
# regular expression pattern
# a file
# files including a file

5 Ramesh Natarajan April 23, 2009 at 12:17 am

@BalaC,
 
Thanks a lot. CScope looks excellent. It is also good to point out that Cscope support is built into the Vim if it is compiled with the –enable-cscope. You can check whether CScope is enabled in your vim by entering :version from vim editor.
 
For those who are interested in Cscope, please check-out Cscope Vim Tutorial

6 BalaC April 24, 2009 at 5:33 am

I have also had the following lines embedded in my vimrc file, which makes working with CScope much simpler

if has(“cscope”) && filereadable(“/usr/bin/cscope”)
set csprg=/usr/bin/cscope
set csto=0
set cst
set nocsverb
” add any database in current directory
if filereadable(“cscope.out”)
cs add cscope.out
” else add database pointed to by environment
elseif $CSCOPE_DB != “”
cs add $CSCOPE_DB
endif
set csverb
” Using ‘CTRL-\’ then a search type makes the vim window
” “shell-out”, with search results displayed on the bottom

nmap s :cs find s =expand(“”)
nmap g :cs find g =expand(“”)
nmap c :cs find c =expand(“”)
nmap t :cs find t =expand(“”)
nmap e :cs find e =expand(“”)
nmap f :cs find f =expand(“”)
nmap i :cs find i ^=expand(“”)$
nmap d :cs find d =expand(“”)

” Using ‘CTRL-spacebar’ then a search type makes the vim window
” split horizontally, with search result displayed in
” the new window.

nmap s :scs find s =expand(“”)
nmap g :scs find g =expand(“”)
nmap c :scs find c =expand(“”)
nmap t :scs find t =expand(“”)
nmap e :scs find e =expand(“”)
nmap f :scs find f =expand(“”)
nmap i :scs find i ^=expand(“”)$
nmap d :scs find d =expand(“”)

” Hitting CTRL-space *twice* before the search type does a vertical
” split instead of a horizontal one

nmap s :vert scs find s =expand(“”)
nmap g :vert scs find g =expand(“”)
nmap c :vert scs find c =expand(“”)
nmap t :vert scs find t =expand(“”)
nmap e :vert scs find e =expand(“”)
nmap i :vert scs find i ^=expand(“”)$
nmap d :vert scs find d =expand(“”)

endif

7 Border April 24, 2009 at 5:47 am

ctags + cscope is powerful.

8 tarun August 5, 2009 at 4:08 am

very useful.. searched for ctags at so many places .. but found this one the simplest ans easiest to understand… thanks

9 rakesh uv September 19, 2009 at 12:38 am

when i use ctrl+], i get an error tag not found, tag file not found , i have one tag file made by ctag in my project root, how could possible tell vi that its there, is there any variable i need to set

ruv

10 SathiyaMoorthy September 26, 2009 at 11:26 am

@rakesh uv

:set tags+=$PROJECTROOT/tags

After the above, vim will be able to identify that tag file.

11 Justin November 11, 2009 at 3:07 am

Hi, I just want to know how to jump back into the taglist after I “Jump to the Function Definition inside a source code”?

Maybe I need to view the next function, then it’s better that i can jump back and select again.

12 rakeshuv November 11, 2009 at 7:56 am

try ctrl+0, its a genric key used basically to come back, if the key is not mapped to some other function

13 Justin November 11, 2009 at 9:01 pm

Thanks rakeshuv,

ctrl+o generally take me back to the function where I used to be last time.

Here, I want to jump between left taglist window and right function window. How to jump back to the taglist window after I clicking the enter and jumping to the right corresponding function???

14 wangweihua December 14, 2009 at 8:33 pm

try ctrl+w and press h, it will jump back to the taglist window

15 vaibhav April 13, 2010 at 10:18 am

does it work with tcl or itcl ?
are there any other extensions for tcl?

16 Tarek November 18, 2010 at 8:21 am

Hi and thanks for this post, i got a question : how can i switch between window tag list and my programs?

Thanks.

17 Paresh January 24, 2012 at 12:47 pm

Thanks for this very useful article.

Is it possible to save the current vim session along with the taglist. I have tried mksession command.

If there is taglist for multiple files in the taglist side pane and if i try to restore the saved session, then taglist side pane will not come up with all taglists for all the files.

18 Abhinav Gaur April 23, 2012 at 3:33 am

Hello,

I am trying to use the ctags utility for CUDA files. The ctags doesnt carry support for CUDA files at present. Do you have any suggestions/tweaks to achieve the same?

Abhinav

19 Adriano May 18, 2012 at 2:01 pm

Thank you for this useful article.

I use to work with Vim to program Python and C/C++ project. when you use Vim, you will not use another one ;)

20 bankster August 14, 2012 at 2:55 pm

1) This is the content of my .ctags file in my home directory. I found it somewhere on the internet. Using this you can generate a tags-file for vim. The following was based on this.

–langdef=Splus
–langmap=Splus:.s.S.R.r.q
–regex-Splus=/^[ \t]+”?([.A-Za-z][.A-Za-z0-9_]*)”?[\t]*<-[\t]*function/\1/
–regex-Splus=/^"?([.A-Za-z][.A-Za-z0-9_]*)"?[ \t]*<-/\1/

2) Read this to understand How to Add Support for a New Language to Exuberant Ctags …

21 wayne November 21, 2012 at 3:19 pm

Great article. Very clear and concise. Thanks.

Leave a Comment

Previous post:

Next post: