CTags and Goto source definition in Sublime Text 3

adminIDE, sublime0 Comment
10 min. reading

One of the most important functionality of each high class IDE is “Goto source definition” mechanism, which let you click particular symbol (i.e. class or method name) in any source file of your project and be immediately redirected to file (and line) that contains its definition.

Sublime Text 3 is not supporting this functionality natively. But, we can add it quite easily, using CTags plugin.

Note, that “Goto source definition” is sometimes called “Code intelligence” and there is another plugin, that implements it in Sublime Text 3. Read more here. However note, that CTags is maintained by SublimeText team, which may suggest, that it is better solution for this editor.

Before we start, please note, that you shouldn’t rely on CTags installation and usage instructions too hard. As you’ll find below, it is either outdated (written for Sublime Text 2) or not correct. And many things are in fact different, that these docs claims.

You won’t get the whole cake!

If you’re expecting exactly the same functionality, like “huge” IDEs (Netbeans, phpStorm) offers, than you’ll be disappointed. These are full-blown (awful slow) IDEe, while Sublime Text 3 is lightning fast, but only a text editor.

Here are the biggest changes and missing things. In partcular, CTags:

  • will not work on core PHP functions and methods:
  • relies on tags files created by external program:
    • so neither plugin nor Sublime Text updates source “database” automatically;
    • you must do this manually, from time to time, as your work progresses
    • (this takes just a few seconds on fast computers),
  • does not have code completion of your local symbols:
    • in PHP, when you write $this-> it will not open a list of fields of class, which $this refers to)
    • this is possible only in alternative, “SublimeCodeIntel” plugin (see here for details)
  • allows you to jump over (to source definition and back) only on methods and class names:
    • you won’t have navigation between variables
    • (i.e. between place, where variable is used and its declaration).

As for last point there are some workarounds. I.e.:

  1. Alternatively, you can press Ctrl+; to open “Goto Anything” pane with # symbol entered.
    1. This allows you to search through words in current file.
    2. List will also include all symbols in current file
    3. They’ll be ordered by “popularity” (i.e. how often you did search for them in the past).
  2. You can also:
    1. Select particular variable or symbol
    2. Press Ctrl+F to put it into search query and then
    3. use F3 and Shift+F3 to quickly navigate between following and previous occurrences.
  3. You can use Alt+S shortcut to display all symbols in currently opened file.

Switch can be painful, especially for former Netbeans developers. But, if you’re ready for some concessions, you may end up with a very fast editor, offering nearly the same functionality and with many cool things in addition.

Installation

Below instructions are meant for Windows users. Adjust them to your system or programming environment:

  1. Install CTags plugin, either using Package Control or manual instructions.
  2. Get CTags binary (currently ctags58.zip) from Exuberant CTags site.
  3. Unzip ctags.exe from archive to any folder
    1. This folder of your choice must be listed on your PATH variable.
    2. Note, that CTags website claims that you can put it into Sublime Text installation folder (i.e. c:\Program Files\Sublime Text 3).
    3. I found this to be not true. I decided to put this executable to C:\Windows folder instead.
  4. Start Sublime Text 3, if it isn’t started yet.
  5. Press Ctrl+T followed by Ctrl+R to initially build tags files and wait for process completion.

You should consider ignoring generated tags files (see below).

Note, that you must select directory, under which tags files will be placed, from list offered by Sublime Text. You can’t enter that path manually (it will be ignored). If file / path / project, for which you want to build tags files isn’t listed, once you press Ctrl+T followed by Ctrl+R to open any file from that folder / project or adding new project to Sublime Text should fix this problem.

Building process creates two files: .tags and .tags_sorted_by_file.

For an average project (3 800 files, 700 folders, 62 MB in size) ctags program generates these two files with 167 MB in total size. Generation process took no more than just few seconds on four core i5-3470 with 8 GB of RAM and Windows 7 x64.

Usage

CTags website claims, that if you use plugin on folder / project, which doesn’t have tags files build yet, plugin will offer you to build such files. I found it to be not true. You must press Ctrl+T plus Ctrl+R to manually force tags files build process, if your project or folder misses these files.

To use CTags plugin in particular project:

  1. Start Sublime Text 3, if it isn’t started yet.
  2. Open any file, if it isn’t opened automatically.
  3. Locate any symbol (class name, method name etc.; unfortunately — it won’t work on variables names).
  4. Place a cursor on it (click) and press Ctrl+T twice to go to source definition on it.
  5. Alternatively, click any symbol, while holding Ctrl+Shift.
  6. Press Ctrl+T followed by Ctrl+B or Ctrl+Shift+right click to go back to previous editing position and file.

If symbol under cursor is found in more than one place, CTags will display a standard “Command Palette” and let you select, which file you’d like to open.

As you may recall, in many IDEs, simple Ctrl+click is used to jump to source definition. In Sublime Text 3 you must use default Ctrl+Shift+click, because Ctrl+click is reserved for placing multiple cursors in this editor. Alternatively, you can redefine default keyboard shortcut, if you don’t use this functionality.

You should learn, that you should create / update tags files (Ctrl+T followed by Ctrl+R) every time, you you create a new project, or switch to any. You can achieve the same, by right-clicking any folder in your sidebar and selecting CTags: Rebuild Tags position from context menu.

Ignore tags files

Sublime Text 3 will list tags files in file (project) tree and in search results. You probably would like to avoid that. To achieve this, you have to add file_exclude_patterns flag to your user settings file (Preferences > Settings — User).

This is another thing, about which CTags manual is wrong. You shouldn’t put just "file_exclude_patterns": [".tags", ".tags_sorted_by_file", ".gemtags"] into your user config file, because this flag (as probably other) isn’t merged with same flag in default configuration file.

So, instead, you should copy this flag, with all values, from default configuration file (Preferences > Settings — Default), paste it into your user config and add ".tags", ".tags_sorted_by_file", ".gemtags" values to the end of long list of already ignored file extensions (you may skip ".gemtags", if you’re not RoR developer and you’re not using gems).

If you’re working under any kind of version control, you may want to set tags files as ignored (for example, add them to .gitignore in case of Git).

More advanced usage

If code using any framework (Yii in my case), you probably would like CTags to be able to “jump” not only to your own symbols, but to framework’s one as well.

You can do this on two different ways:

  • by adding your entire framework to your sidebar / current project:
    • my tests shown, that you can do this only once, then remove it
    • and CTags will still use tags files in framework folder,
    • but I’m not sure, how reliable this solution is,
  • by overriding default plugin configuration.

Of course, you must first build tags for framework folder, either by runniny ctags.exe command manually or by opening any file from framework folder and pressing Ctrl+T followed by Ctrl+R.

If you decide to override base configuration of CTags, then:

  • extract a copy of CTags.sublime-settings file out of Installed Packages\CTags.sublime-package archive
  • and edit it.

Details about overriding base configuration of anything in Sublime Text 3 can be found in n official Sublime Text 3 documentation, section “Overriding Files From a Zipped Package”.

Now, edit CTags.sublime-settings file and modify extra_tag_paths:

"extra_tag_paths": [[["source.php", "windows"], "C:\XAMPP\websites\yii"]]

Remember about using double slashes and correct form of language/platform/path.

I found it impossible to exclude certain files from being used/indexed by CTags:

  • You can exclude entire directory only.
  • There’s a configuration flag opts, where you can pass extra settings for ctags.exe.
  • One of them is --exclude=some/path, but I found it to not work for a particular file.

I managed to workaround this problem, by:

  • simply removing obstacle file (yiilite.php in case of Yii 1.x framework),
  • building tags files (Ctrl+T and Ctrl+R)
  • and adding that file back.

Since framework source code doesn’t change that often, this is acceptable solution (at least for me).

Final words

CTags plugin for Sublime Text 3 along with ctags.exe program behind it, is a really powerful coding tool. A must have, in my opinion, for every professional developer.

When I started using it, I seemed to be a less powerful that functionalities build-in to large IDEs. But, with proper configuration (above) and when combined with speed and fuzzy logic comming from Sublime Text 3, I must admit, that I never run into more useful coding tool like that.

Leave a Reply