skuroda/CTags

== CTags ==

This [[http://sublimetext.com|Sublime Text 2]] Package provides support for working with tags generated by [[http://ctags.sourceforge.net/|Exuberant CTags]]

The ctags command is searched for on PATH. It works by doing a binary search of
an mmap()'d .tags file so it will work efficiently with very large ( 50MB+ etc
) tags files if needed.

=== OS X ===

If anyone is having trouble getting the CTags -R flag to work on OSX, you are probably using the stock CTags installation.

To get a proper copy of ctags, use one of the following options:

Using [[http://mxcl.github.com/homebrew/|Homebrew]]:
{{{brew install ctags}}}
Using [[http://www.macports.org/|MacPorts]]:
{{{port install ctags}}}

Make sure that Sublime Text is using the right version of CTags:

If 'which ctags' doesn't point at ctags in '/usr/local/bin', make sure you add '/usr/local/bin' to your PATH ahead of the folder that 'which ctags' reported.
** Add or modify the 'export PATH=...' (e.g. in ~/.profile) to make the change permanent

=== Linux ===

To get a proper copy of ctags, use one of the following options:

In a terminal session:
{{{sudo apt-get install ctags}}}

=== Windows ===

Download the [[http://prdownloads.sourceforge.net/ctags/ctags58.zip|binary ctags.exe]] from [[http://ctags.sourceforge.net/|Exuberant Ctags site]].

Extract ctags.exe from the download zip to "C:\Program Files\Sublime Text 2" or any folder that within your PATH so CTags support for Sublime Text 2 can run it.

=== Dependencies ===

No dependencies!

=== Installation ===

If you are a git user, the best way to install the package and keep up to date
is to clone the repo directly into your /Packages directory in the Sublime Text
2 application settings area.

==== Using Git ====

Go to your Sublime Text 2 Packages directory and clone the repository using the command below:

{{{
$ git clone https://github.com/SublimeText/CTags CTags
}}}

==== Download Manually ====

Download the files using the .zip download option
Unzip the files (and rename the folder to CTags if needed)
Copy the folder to your Sublime Text 2 Packages directory

=== About ===

See this [[http://www.sublimetext.com/forum/viewtopic.php?f=5&t=144|forum thread]] for a bit of background.

=== Usage ===

This uses .tags files created in ctags -R -f .tags recursive mode.

The commands will try and find a tags file in the same directory as
the current view, walking up directories until it finds one. If it
can't find one it will offer to build some ( in the directory of the
current view ) (TODO: doesn't ask as missing api from S1)

If a symbol can't be found in a tags file it will search in
alternative locations.

If you create a file tags_search_paths in the same folder as your
tags file, listing alternative locations (full absolute paths, one
per line) it will search those files also.

{{{
D:\myProject\tags
}}}

If you are a rubyist, you can build the whole Ruby Gems ctags file for your application seperately via a build_gemtags.rb script:

{{{
require 'bundler'
paths = Bundler.load.specs.map(&:full_gem_path)
system("ctags -R -f .gemtags #{paths.join(' ')}")
}}}

=== Other Settings ===

There's a CTags.sublime-settings file:

{{{
{
"debug" : false,
"ctags_command" : "ctags -R -f .tags",
"filters" : {
"source.python": {"type":"^i$"}
},
"definition_filters": {
"source.php": {"type":"^v$"}
},
"definition_current_first": false,
"show_context_menus": false,
"extra_tag_paths" : [ [["source.python", "windows"], "C:\Python27\Lib\tags"]],
"extra_tag_files" : [".gemtags"]
}
}}}

filters will allow you to set scope specific filters against a field of the
tag. In the excerpt above, imports tags like "from a import b" are filtered.

{{{
'(?P[^\t]+)\t'
'(?P[^\t]+)\t'
'(?P<ex_command>.?);"\t'
'(?P[^\t\r\n]+)'
'(?:\t(?P.))?'
}}}

extra_tag_paths is a list of extra places to look for keyed by (selector, platform)

extra_tag_files is a list of extra files relative to the original .tags file

Note the platform (windows in the example above) is tested against
sublime.platform() so any values that function returns are valid.

The rest of the options are fairly self explanatory.

=== Support ===

If there are any problems or you have a suggestion [[https://github.com/SublimeText/CTags/issues/new|open an issue]] and we will receive an email notification.

Thanks :)

=== Commands Listing ===

Contributors