Editing Ctags

{{Short description|Programming tool for code comprehension}}
{{more citations needed|date=November 2011}}
{{Infobox software
| name                   = Ctags (BSD)
| logo                   = 
| screenshot             = 
| caption                = 
| latest release version =
| developer              = [[Ken Arnold]]
| operating system       = [[Unix]] and [[Unix-like]]
| platform               = [[Cross-platform]]
| genre                  = [[Programming tool]] <small>(Specifically: Code navigation tool)</small>
| license                = BSD
| website                = 
}}
'''Ctags''' is a [[programming tool]] that generates an [[index (publishing)|index]] file (or tag file) of names found in source and header files of various [[programming language]]s to aid [[Program comprehension|code comprehension]]. Depending on the language, [[function (computer science)|functions]], [[Variable (programming)|variables]], [[class (computer science)|class]] members, [[Macro (computer science)|macros]] and so on may be indexed. These tags allow definitions to be quickly and easily located by a [[text editor]], a code search engine, or other utility. Alternatively, there is also an output mode that generates a [[cross reference]] file, listing information about various names found in a set of language files in [[human-readable]] form.

The original '''Ctags''' was introduced in [[BSD Unix]] 2.0<ref>{{Cite web |url=https://www.tuhs.org/cgi-bin/utree.pl?file=2BSD/man/ctags.u |access-date=2024-10-21 |website=www.tuhs.org |title=2BSD/man/ctags.u}}</ref><ref>{{Cite web |url=https://www.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/ctags.sh |access-date=2024-10-21 |website=www.tuhs.org |title=2BSD/src/ctags.sh}}</ref> and was written by [[Ken Arnold]], with [[Fortran]] support by Jim Kleckner and [[Pascal (programming language)|Pascal]] support by [[Bill Joy]]. It is part of the initial release of Single Unix Specification and XPG4 of 1992.

==Editors that support ctags==
''Tag index files'' are supported by many [[source code editor]]s, including:
{{div col start}}
* [[Atom (text editor)|Atom]]
* [[BBEdit|BBEdit 8+]]
* [[CodeLite]] (via built-in ctagsd [[Language Server Protocol|language server]])<ref>{{Cite web |url=https://docs.codelite.org/plugins/lsp/ |title=Language Server Protocol |website=CodeLite Documentation |access-date=2022-06-12}}</ref>
* [[Cloud9 IDE]] (uses it internally but does not expose it)
* [[CygnusEd]]<ref>{{Cite web|url=http://aminet.net/package/dev/c/ctags|title = Aminet - dev/C/Ctags.lha}}</ref>
* [[Emacs]] and [[XEmacs]]
* [[EmEditor|EmEditor Professional]]
*[[Far Manager]] (via Ctags Source Navigator plugin)
* [[Geany]]
* [[Gedit]] (via [https://web.archive.org/web/20080117145432/http://www.micahcarrick.com/11-14-2007/gedit-symbol-browser-plugin.html gedit-symbol-browser-plugin])
* [[JED (text editor)|JED]]
* [[jEdit]] (via plugins CodeBrowser, Tags, ClassBrowser, CtagsSideKick, or Jump)
* [[Joe's Own Editor|JOE]]
* [[KDevelop]]
* [[Kate (text editor)|Kate]]
* [[mcedit]] (Midnight Commander builtin editor)
* [[NEdit]]
* [[Notepad++]] (via OpenCTags plug-in)
* QDevelop
* [[The SemWare Editor|TSE (via macro)]]
* [[TextMate]] (via CodeBrowser-PlugIn)
* [[UltraEdit]]
* [[TextPad]]
* [[VEDIT]]
* [[Vi (text editor)|vi]] (and derivatives such as [[Elvis (text editor)|Elvis]], [[Nvi]], [[Vim (text editor)|Vim]], [[Vile (text editor)|vile]], etc.)
* [[Visual Studio Code]]<ref>[https://donjayamanne.github.io/pythonVSCodeDocs/docs/workspaceSymbols/ Workspace Symbols], ''Python for Visual Studio Code Docs''</ref>
* [[Xedit (X11)]]
{{div col end}}

==Variants of ctags==
There are a few other implementations of the ''ctags'' program:

===Etags===
GNU [[Emacs]] comes with two ctags utilities, '''etags''' and ctags, which are compiled from the same source code.  Etags generates a tag table file for Emacs, while the ctags command is used to create a similar table in a format understood by [[Vi (text editor)|vi]].  They have different sets of command line options:
etags does not recognize and ignores options which only make sense for vi style tag files produced by the ctags command.<ref>{{man|1|etags.emacs|ManKier}}</ref>

===Exuberant Ctags===
'''Exuberant Ctags''', written and maintained by [[Darren Hiebert]] until 2009,<ref>{{cite web |title=Exuberant Ctags |url=http://ctags.sourceforge.net/ |website=ctags.sourceforge.net}}</ref> was initially distributed with [[Vim (text editor)|Vim]], but became a separate project upon the release of Vim 6. It includes support for Emacs and {{code|etags}} compatibility.<ref>{{cite web|url=http://vimdoc.sourceforge.net/htmldoc/version6.html#ctags-gone|title=Vim documentation: version6: ctags-gone|access-date=2007-04-28}}</ref><ref>{{man|1|etags.ctags|ManKier}}</ref>

Exuberant Ctags includes support for over 40 programming languages with the ability to add support for even more using [[regular expression]]s.

===Universal Ctags===
'''Universal Ctags''' is a fork of Exuberant Ctags, with the objective of continuing its development. A few parsers are rewritten to better support the languages.<ref>{{cite web|url=https://docs.ctags.io/|title=Universal Ctags Documentation|access-date=2018-08-02}}</ref>

===Language-specific===
'''{{vanchor|Hasktags}}''' creates ctags compatible tag files for [[Haskell (programming language)|Haskell]] source files.<ref>{{cite web|url=http://haskell.org/ghc/docs/latest/html/users_guide/utils.html#hasktags|title=GHC documentation: Other Haskell utility programs|access-date=2010-03-05}}</ref> It includes support for creating Emacs etags files.<ref>{{cite web|url=http://hackage.haskell.org/package/hasktags|title=hasktags: Produces ctags "tags" and etags "TAGS" files for Haskell programs|access-date=2010-03-05}}</ref>

'''{{vanchor|jsctags}}''' is a ctags-compatible code indexing solution for [[JavaScript]].<ref>{{cite web|url=https://github.com/pcwalton/jsctags|title=pcwalton github repository for jsctags|website=[[GitHub]] |access-date=2016-09-10|archive-url=https://web.archive.org/web/20100822181929/http://github.com/pcwalton/jsctags|archive-date=2010-08-22|url-status=dead}}</ref> It is specialized for JavaScript and uses the [[CommonJS]] packaging system. It outperforms ''Exuberant Ctags'' for JavaScript code, finding more tags than the latter.<ref>{{cite web|url=http://pcwalton.blogspot.com/2010/05/introducing-jsctags.html|title=Introducing jsctags|author=Patrick Walton|date=25 May 2010|access-date=2010-05-25}}</ref>

==Tags file formats==
There are multiple tag file formats. Some of them are described below.  In the following, {{mono|\<u>x##</u>}} represents the byte with hexadecimal representation {{mono|##}}. Every line ends with a [[line feed]] (LF, {{mono|\<u>n</u>}} = {{mono|\<u>x0A</u>}}).

===Ctags and descendants===
The original ''ctags'' and the Exuberant/Universal descendants have similar file formats:<ref name=exu-fmt>{{cite web|url=http://ctags.sourceforge.net/FORMAT|title=Proposal for extended Vi tags file format|access-date=2007-06-30}}</ref>

====Ctags====
This is the format used by ''vi'' and various clones.  The tags file is normally named "tags".

The tags file is a list of lines, each line in the format:

 {'''tagname'''}\<u>t</u>{'''tagfile'''}\<u>t</u>{'''tagaddress'''}

The fields are specified as follows:

* {{mono|{tagname}}} &ndash; Any identifier, not containing white space
* {{mono|\<u>t</u>}} &ndash; Exactly one [[Tab key|tab]] ({{mono|\<u>x0b</u>}}) character, although many versions of ''vi'' can handle any amount of white space.
* {{mono|{tagfile}}} &ndash; The name of the file where {{mono|{tagname}}} is defined, relative to the current directory
* {{mono|{tagaddress}}} &ndash; An [[ex (text editor)|ex]] mode command that will take the editor to the location of the tag. For POSIX implementations of ''vi'' this may only be a search or a line number, providing added security against arbitrary command execution.

The tags file is sorted on the {{mono|{tagname}}} field which allows for fast searching of the tags file.

====Extended Ctags====
This is the format used by [[Vim (text editor)|Vim]]'s Exuberant Ctags and Universal Ctags. These programs can generate an original ''ctags'' file format or an extended format that attempts to retain backward compatibility.

The extended tags file is a list of lines, each line in the format:

 {'''tagname'''}\<u>t</u>{'''tagfile'''}\<u>t</u>{'''tagaddress'''}[;"\<u>t</u>{'''tagfield'''...}]

The fields up to and including {{mono|{tagaddress}}} are the same as for [[#Ctags|ctags]] above.

Optional additional fields are indicated by square brackets ("[...]") and include:
*{{mono|;"}} &ndash; semicolon + double quote: Ends the {{mono|{tagaddress}}} in a way that looks like the start of a comment to ''vi'' or ''ex''.
*{{mono|{tagfield}}} &ndash; extension fields: tab separated "key:value" pairs for more information.

This format is compatible with non-POSIX ''vi'' as the additional data is interpreted as a comment. POSIX implementations of ''vi'' must be changed to support it, however.<ref name=exu-fmt/>

===Etags===
This is the format used by Emacs ''etags''. The tags file is normally named "TAGS".

The etags files consists of multiple sections&mdash;one section per input source file. Sections are plain-text with several non-printable ascii characters used for special purposes. These characters are represented as underlined hexadecimal codes below.

A section starts with a two line header (the first two bytes make up a [[Magic number (programming)|magic number]]):

 \<u>x0c</u>
 {'''src_file'''},{'''size_of_tag_definition_data_in_bytes'''}

The header is followed by tag definitions, one definition per line, with the format:

 {'''tag_definition_text'''}\<u>x7f</u>{'''tagname'''}\<u>x01</u>{'''line_number'''},{'''byte_offset'''}

{{mono|{tagname}<u>\x01</u>}} can be omitted if the name of the tag can be deduced from the text at the tag definition.

===Example===
Given a single line test.c source code:

 #define CCC(x)

The TAGS (etags) file would look like this:

 \<u>x0c</u>
 test.c,21
 #define CCC(\<u>x7f</u>CCC\<u>x01</u>1,0

The tags (ctags) file may look like:

<pre>
CCC(	test.c	1
</pre>

or more flexibly using a search:

<pre>
CCC(	test.c	/^#define CCC(/
</pre>

==See also==
* [[GNU GLOBAL]]

==References==
{{Reflist}}

==External links==
{{Wikibooks|Guide to Unix|Commands}}
*{{man|cu|ctags|SUS|create a tags file}}
* [https://ctags.io Universal Ctags homepage]
* [http://ctags.sourceforge.net Exuberant Ctags homepage]
* [http://polarhome.com/ctags/?lang=en Ctags on VMS]
* [http://cvs.savannah.gnu.org/viewvc/vtags/vtags/vtags.el?view=markup source code for  Emacs vtags.el module]

{{Unix commands}}

[[Category:Code comprehension tools]]
[[Category:Code navigation tools]]
[[Category:Free computer programming tools]]
[[Category:Unix programming tools]]
[[Category:Standard Unix programs]]
[[Category:Unix SUS2008 utilities]]
[[Category:Software using the BSD license]]

[[fr:Ctags]]