1ctags(1) Universal Ctags ctags(1)
2
6 ctags - Generate tag files for source code
7
9 ctags [<options>] [<source_file(s)>]
10 etags [<options>] [<source_file(s)>]
11
14 The ctags and etags (see -e option) programs (hereinafter collectively
15 referred to as ctags, except where distinguished) generate an index (or
16 "tag") file for a variety of language objects found in source file(s).
17 This tag file allows these items to be quickly and easily located by a
18 text editor or other utilities (client tools). A tag signifies a lan‐
19 guage object for which an index entry is available (or, alternatively,
20 the index entry created for that object).
21 Alternatively, ctags can generate a cross reference file which lists,
23 in human readable form, information about the various language objects
24 found in a set of source files.
25 Tag index files are supported by numerous editors, which allow the user
27 to locate the object associated with a name appearing in a source file
28 and jump to the file and line which defines the name. See the manual of
29 your favorite editor about utilizing ctags command and the tag index
30 files in the editor.
31 ctags is capable of generating different kinds of tags for each of many
33 different languages. For a complete list of supported languages, the
34 names by which they are recognized, and the kinds of tags which are
35 generated for each, see the --list-languages and --list-kinds-full op‐
36 tions.
37 This man page describes Universal Ctags, an implementation of ctags de‐
39 rived from Exuberant Ctags. The major incompatible changes between Uni‐
40 versal Ctags and Exuberant Ctags are enumerated in ctags-incompatibili‐
41 ties(7).
42 One of the advantages of Exuberant Ctags is that it allows a user to
44 define a new parser from the command line. Extending this capability is
45 one of the major features of Universal Ctags. ctags-optlib(7) describes
46 how the capability is extended.
47 Newly introduced experimental features are not explained here. If you
49 are interested in such features and ctags internals, visit
50 https://docs.ctags.io/.
51
53 Despite the wealth of available options, defaults are set so that ctags
54 is most commonly executed without any options (e.g. "ctags *", or
55 "ctags -R"), which will create a tag file in the current directory for
56 all recognized source files. The options described below are provided
57 merely to allow custom tailoring to meet special needs.
58 Note that spaces separating the single-letter options from their param‐
60 eters are optional.
61 Note also that the boolean parameters to the long form options (those
63 beginning with -- and that take a [=(yes|no)] parameter) may be omit‐
64 ted, in which case =yes is implied. (e.g. --sort is equivalent to
65 --sort=yes). Note further that =1, =on, and =true are considered syn‐
66 onyms for =yes, and that =0, =off, and =false are considered synonyms
67 for =no.
68 Some options are either ignored or useful only when used while running
70 in etags mode (see -e option). Such options will be noted.
71 <options> must precede the <source_file(s)> following the standard
73 POSIX convention.
74 Options taking language names will accept those names in either upper
76 or lower case. See the --list-languages option for a complete list of
77 the built-in language names.
78 Letters and names
80 Some options take one-letter flags as parameters (e.g. --kinds-<LANG>
81 option). Specifying just letters help a user create a complicated com‐
82 mand line quickly. However, a command line including sequences of
83 one-letter flags becomes difficult to understand.
84 Universal Ctags accepts long-name flags in addition to such one-letter
86 flags. The long-name and one-letter flags can be mixed in an option pa‐
87 rameter by surrounding each long-name by braces. Thus, for an example,
88 the following three notations for --kinds-C option have the same mean‐
89 ing:
90 --kinds-C=+pLl
92 --kinds-C=+{prototype}{label}{local}
93 --kinds-C=+{prototype}L{local}
94 Note that braces may be meta characters in your shell. Put single
96 quotes in such case.
97 --list-... options shows one-letter flags and associated long-name
99 flags.
100 List options
102 Universal Ctags introduces many --list-... options that provide the in‐
103 ternal data of Universal Ctags (See "Listing Options"). Both users and
104 client tools may use the data. --with-list-header and --machinable op‐
105 tions adjust the output of the most of --list-... options.
106 The default setting (--with-list-header=yes and --machinable=no) is for
108 using interactively from a terminal. The header that explains the mean‐
109 ing of columns is simply added to the output, and each column is
110 aligned in all lines. The header line starts with a hash ('#') charac‐
111 ter.
112 For scripting in a client tool, --with-list-header=no and --machin‐
114 able=yes may be useful. The header is not added to the output, and each
115 column is separated by tab characters.
116 Note the order of columns will change in the future release. However,
118 labels in the header will not change. So by scanning the header, a
119 client tool can find the index for the target column.
120
122 ctags has more options than listed here. Options starting with an un‐
123 derscore character, such as --_echo=<msg>, are not listed here. They
124 are experimental or for debugging purpose.
125 Notation: <foo> is for a variable string foo, [ ... ] for optional, |
127 for selection, and ( ... ) for grouping. For example
128 --foo[=(yes|no)]'' means ``--foo, -foo=yes, or -foo=no.
129 Input/Output File Options
131 --exclude=<pattern>
132 Add <pattern> to a list of excluded files and directories. This
133 option may be specified as many times as desired. For each file
134 name considered by ctags, each pattern specified using this op‐
135 tion will be compared against both the complete path (e.g.
136 some/path/base.ext) and the base name (e.g. base.ext) of the
137 file, thus allowing patterns which match a given file name irre‐
138 spective of its path, or match only a specific path.
139 If appropriate support is available from the runtime library of
141 your C compiler, then pattern may contain the usual shell wild‐
142 cards (not regular expressions) common on Unix (be sure to quote
143 the option parameter to protect the wildcards from being ex‐
144 panded by the shell before being passed to ctags; also be aware
145 that wildcards can match the slash character, '/'). You can de‐
146 termine if shell wildcards are available on your platform by ex‐
147 amining the output of the --list-features option, which will in‐
148 clude wildcards in the compiled feature list; otherwise, pattern
149 is matched against file names using a simple textual comparison.
150 If <pattern> begins with the character '@', then the rest of the
152 string is interpreted as a file name from which to read exclu‐
153 sion patterns, one per line. If pattern is empty, the list of
154 excluded patterns is cleared.
155 Note that at program startup, the default exclude list contains
157 names of common hidden and system files, patterns for binary
158 files, and directories for which it is generally not desirable
159 to descend while processing the --recurse option. To see the
160 list of built-in exclude patterns, use --list-excludes.
161 See also the description for --exclude-exception= option.
163 --exclude-exception=<pattern>
165 Add <pattern> to a list of included files and directories. The
166 pattern affects the files and directories that are excluded by
167 the pattern specified with --exclude= option.
168 For an example, you want ctags to ignore all files under foo di‐
170 rectory except foo/main.c, use the following command line: --ex‐
171 clude=foo/* --exclude-exception=foo/main.c.
172 --filter[=(yes|no)]
174 Makes ctags behave as a filter, reading source file names from
175 standard input and printing their tags to standard output on a
176 file-by-file basis. If --sort is enabled, tags are sorted only
177 within the source file in which they are defined. File names are
178 read from standard input in line-oriented input mode (see note
179 for -L option) and only after file names listed on the command
180 line or from any file supplied using the -L option. When this
181 option is enabled, the options -f, -o, and --totals are ignored.
182 This option is quite esoteric and is disabled by default.
183 --filter-terminator=<string>
185 Specifies a <string> to print to standard output following the
186 tags for each file name parsed when the --filter option is en‐
187 abled. This may permit an application reading the output of
188 ctags to determine when the output for each file is finished.
189 Note that if the file name read is a directory and --recurse is
191 enabled, this string will be printed only once at the end of all
192 tags found for by descending the directory. This string will al‐
193 ways be separated from the last tag line for the file by its
194 terminating newline.
195 This option is quite esoteric and is empty by default.
197 --links[=(yes|no)]
199 Indicates whether symbolic links (if supported) should be fol‐
200 lowed. When disabled, symbolic links are ignored. This option
201 is on by default.
202 --maxdepth=<N>
204 Limits the depth of directory recursion enabled with the --re‐
205 curse (-R) option.
206 --recurse[=(yes|no)]
208 Recurse into directories encountered in the list of supplied
209 files.
210 If the list of supplied files is empty and no file list is spec‐
212 ified with the -L option, then the current directory (i.e. '.')
213 is assumed. Symbolic links are followed by default (See --links
214 option). If you don't like these behaviors, either explicitly
215 specify the files or pipe the output of find(1) into "ctags -L
216 -" instead. See, also, the --exclude and --maxdepth to limit re‐
217 cursion.
218 Note: This option is not supported on all platforms at present.
220 It is available if the output of the --help option includes this
221 option.
222 -R Equivalent to --recurse.
224 -L <file>
226 Read from <file> a list of file names for which tags should be
227 generated.
228 If file is specified as '-', then file names are read from stan‐
230 dard input. File names read using this option are processed fol‐
231 lowing file names appearing on the command line. Options are
232 also accepted in this input. If this option is specified more
233 than once, only the last will apply.
234 Note: file is read in line-oriented mode, where a new line is
236 the only delimiter and non-trailing white space is considered
237 significant, in order that file names containing spaces may be
238 supplied (however, trailing white space is stripped from lines);
239 this can affect how options are parsed if included in the input.
240 --append[=(yes|no)]
242 Indicates whether tags generated from the specified files should
243 be appended to those already present in the tag file or should
244 replace them. This option is no by default.
245 -a Equivalent to --append.
247 -f <tagfile>
249 Use the name specified by <tagfile> for the tag file (default is
250 "tags", or "TAGS" when running in etags mode). If <tagfile> is
251 specified as '-', then the tags are written to standard output
252 instead.
253 ctags will stubbornly refuse to take orders if tagfile exists
255 and its first line contains something other than a valid tags
256 line. This will save your neck if you mistakenly type "ctags -f
257 *.c", which would otherwise overwrite your first C file with the
258 tags generated by the rest! It will also refuse to accept a
259 multi-character file name which begins with a '-' (dash) charac‐
260 ter, since this most likely means that you left out the tag file
261 name and this option tried to grab the next option as the file
262 name. If you really want to name your output tag file -ugly,
263 specify it as "-f ./-ugly".
264 This option must appear before the first file name. If this op‐
266 tion is specified more than once, only the last will apply.
267 -o <tagfile>
269 Equivalent to "-f tagfile".
270 Output Format Options
272 --format=(1|2)
273 Change the format of the output tag file. Currently the only
274 valid values for level are 1 or 2. Level 1 specifies the origi‐
275 nal tag file format and level 2 specifies a new extended format
276 containing extension fields (but in a manner which retains back‐
277 ward-compatibility with original vi(1) implementations). The de‐
278 fault level is 2. [Ignored in etags mode]
279 --output-format=(u-ctags|e-ctags|etags|xref|json)
281 Specify the output format. The default is u-ctags. See tags(5)
282 for u-ctags and e-ctags. See -e for etags, and -x for xref.
283 json format is available only if the ctags executable is built
284 with libjansson. See ctags-client-tools(7) for more about json
285 format.
286 -e Same as --output-format=etags. Enable etags mode, which will
288 create a tag file for use with the Emacs editor. Alternatively,
289 if ctags is invoked by a name containing the string "etags" (ei‐
290 ther by renaming, or creating a link to, the executable), etags
291 mode will be enabled.
292 -x Same as --output-format=xref. Print a tabular, human-readable
294 cross reference (xref) file to standard output instead of gener‐
295 ating a tag file. The information contained in the output in‐
296 cludes: the tag name; the kind of tag; the line number, file
297 name, and source line (with extra white space condensed) of the
298 file which defines the tag. No tag file is written and all op‐
299 tions affecting tag file output will be ignored.
300 Example applications for this feature are generating a listing
302 of all functions located in a source file (e.g. "ctags -x
303 --kinds-c=f file"), or generating a list of all externally visi‐
304 ble global variables located in a source file (e.g. "ctags -x
305 --kinds-c=v --extras=-F file").
306 --sort=(yes|no|foldcase)
308 Indicates whether the tag file should be sorted on the tag name
309 (default is yes). Note that the original vi(1) required sorted
310 tags. The foldcase value specifies case insensitive (or
311 case-folded) sorting. Fast binary searches of tag files sorted
312 with case-folding will require special support from tools using
313 tag files, such as that found in the ctags readtags library, or
314 Vim version 6.2 or higher (using "set ignorecase"). [Ignored in
315 etags mode]
316 -u Equivalent to --sort=no (i.e. "unsorted").
318 --etags-include=<file>
320 Include a reference to <file> in the tag file. This option may
321 be specified as many times as desired. This supports Emacs' ca‐
322 pability to use a tag file which includes other tag files.
323 [Available only in etags mode]
324 --input-encoding=<encoding>
326 Specifies the <encoding> of the input files. If this option is
327 specified, Universal Ctags converts the input from this encoding
328 to the encoding specified by --output-encoding=encoding.
329 --input-encoding-<LANG>=<encoding>
331 Specifies a specific input <encoding> for <LANG>. It overrides
332 the global default value given with --input-encoding.
333 --output-encoding=<encoding>
335 Specifies the <encoding> of the tags file. Universal Ctags con‐
336 verts the encoding of input files from the encoding specified by
337 --input-encoding=<encoding> to this encoding.
338 In addition <encoding> is specified at the top the tags file as
340 the value for the TAG_FILE_ENCODING pseudo-tag. The default
341 value of <encoding> is UTF-8.
342 Language Selection and Mapping Options
344 --language-force=(<language>|auto)
345 By default, ctags automatically selects the language of a source
346 file, ignoring those files whose language cannot be determined
347 (see "Determining file language"). This option forces the speci‐
348 fied language (case-insensitive; either built-in or user-de‐
349 fined) to be used for every supplied file instead of automati‐
350 cally selecting the language based upon its extension.
351 In addition, the special value auto indicates that the language
353 should be automatically selected (which effectively disables
354 this option).
355 --languages=[+|-](<list>|all)
357 Specifies the languages for which tag generation is enabled,
358 with <list> containing a comma-separated list of language names
359 (case-insensitive; either built-in or user-defined).
360 If the first language of <list> is not preceded by either a '+'
362 or '-', the current list (the current settings of enabled/dis‐
363 abled languages managed in ctags internally) will be cleared be‐
364 fore adding or removing the languages in <list>. Until a '-' is
365 encountered, each language in the <list> will be added to the
366 current list.
367 As either the '+' or '-' is encountered in the <list>, the lan‐
369 guages following it are added or removed from the current list,
370 respectively. Thus, it becomes simple to replace the current
371 list with a new one, or to add or remove languages from the cur‐
372 rent list.
373 The actual list of files for which tags will be generated de‐
375 pends upon the language extension mapping in effect (see the
376 --langmap option). Note that the most of languages, including
377 user-defined languages, are enabled unless explicitly disabled
378 using this option. Language names included in list may be any
379 built-in language or one previously defined with --langdef.
380 The default is all, which is also accepted as a valid argument.
382 See the --list-languages option for a list of the all (built-in
383 and user-defined) language names.
384 Note --languages= option works cumulative way; the option can be
386 specified with different arguments multiple times in a command
387 line.
388 --alias-<LANG>=[+|-](<pattern>|default)
390 Adds ('+') or removes ('-') an alias <pattern> to a language
391 specified with <LANG>. ctags refers to the alias pattern in "‐
392 Determining file language" stage.
393 The parameter <pattern> is not a list. Use this option multiple
395 times in a command line to add or remove multiple alias pat‐
396 terns.
397 To restore the default language aliases, specify default.
399 Using all for <LANG> has meaning in following two cases:
401 --alias-all=
403 This clears aliases setting of all languages.
404 --alias-all=default
406 This restores the default languages aliases for all lan‐
407 guages.
408 --guess-language-eagerly
410 Looks into the file contents for heuristically guessing the
411 proper language parser. See "Determining file language".
412 -G Equivalent to --guess-language-eagerly.
414 --langmap=<map>[,<map>[...]]
416 Controls how file names are mapped to languages (see the
417 --list-maps option). Each comma-separated <map> consists of the
418 language name (either a built-in or user-defined language), a
419 colon, and a list of file extensions and/or file name patterns.
420 A file extension is specified by preceding the extension with a
421 period (e.g. .c). A file name pattern is specified by enclosing
422 the pattern in parentheses (e.g. ([Mm]akefile)).
423 If appropriate support is available from the runtime library of
425 your C compiler, then the file name pattern may contain the
426 usual shell wildcards common on Unix (be sure to quote the op‐
427 tion parameter to protect the wildcards from being expanded by
428 the shell before being passed to ctags). You can determine if
429 shell wildcards are available on your platform by examining the
430 output of the --list-features option, which will include wild‐
431 cards in the compiled feature list; otherwise, the file name
432 patterns are matched against file names using a simple textual
433 comparison.
434 When mapping a file extension with --langmap option, it will
436 first be unmapped from any other languages. (--map-<LANG> option
437 provides more fine-grained control.)
438 If the first character in a <map> is a plus sign ('+'), then the
440 extensions and file name patterns in that map will be appended
441 to the current map for that language; otherwise, the map will
442 replace the current map. For example, to specify that only
443 files with extensions of .c and .x are to be treated as C lan‐
444 guage files, use --langmap=c:.c.x; to also add files with exten‐
445 sions of .j as Java language files, specify
446 --langmap=c:.c.x,java:+.j. To map makefiles (e.g. files named
447 either Makefile, makefile, or having the extension .mak) to a
448 language called make, specify --langmap=make:([Mm]akefile).mak.
449 To map files having no extension, specify a period not followed
450 by a non-period character (e.g. '.', ..x, .x.).
451 To clear the mapping for a particular language (thus inhibiting
453 automatic generation of tags for that language), specify an
454 empty extension list (e.g. --langmap=fortran:). To restore the
455 default language mappings for a particular language, supply the
456 keyword default for the mapping. To specify restore the default
457 language mappings for all languages, specify --langmap=default.
458 Note that file name patterns are tested before file extensions
460 when inferring the language of a file. This order of Universal
461 Ctags is different from Exuberant Ctags. See ctags-incompatibil‐
462 ities(7) for the background of this incompatible change.
463 --map-<LANG>=[+|-]<extension>|<pattern>
465 This option provides the way to control mapping(s) of file names
466 to languages in a more fine-grained way than --langmap option.
467 In ctags, more than one language can map to a file name <pat‐
469 tern> or file <extension> (N:1 map). Alternatively, --langmap
470 option handle only 1:1 map, only one language mapping to one
471 file name <pattern> or file <extension>. A typical N:1 map is
472 seen in C++ and ObjectiveC language; both languages have a map
473 to .h as a file extension.
474 A file extension is specified by preceding the extension with a
476 period (e.g. .c). A file name pattern is specified by enclosing
477 the pattern in parentheses (e.g. ([Mm]akefile)). A prefixed
478 plus ('+') sign is for adding, and minus ('-') is for removing.
479 No prefix means replacing the map of <LANG>.
480 Unlike --langmap, <extension> (or <pattern>) is not a list.
482 --map-<LANG> takes one extension (or pattern). However, the op‐
483 tion can be specified with different arguments multiple times in
484 a command line.
485 Tags File Contents Options
487 See "TAG ENTRIES" about fields, kinds, roles, and extras.
488 --excmd=(number|pattern|mix|combine)
490 Determines the type of EX command used to locate tags in the
491 source file. [Ignored in etags mode]
492 The valid values for type (either the entire word or the first
494 letter is accepted) are:
495 number Use only line numbers in the tag file for locating tags.
497 This has four advantages:
498 1. Significantly reduces the size of the resulting tag
500 file.
501 2. Eliminates failures to find tags because the line
503 defining the tag has changed, causing the pattern
504 match to fail (note that some editors, such as vim,
505 are able to recover in many such instances).
506 3. Eliminates finding identical matching, but incorrect,
508 source lines (see "BUGS").
509 4. Retains separate entries in the tag file for lines
511 which are identical in content. In pattern mode, du‐
512 plicate entries are dropped because the search pat‐
513 terns they generate are identical, making the dupli‐
514 cate entries useless.
515 However, this option has one significant drawback:
517 changes to the source files can cause the line numbers
518 recorded in the tag file to no longer correspond to the
519 lines in the source file, causing jumps to some tags to
520 miss the target definition by one or more lines. Basi‐
521 cally, this option is best used when the source code to
522 which it is applied is not subject to change. Selecting
523 this option type causes the following options to be ig‐
524 nored: -B, -F.
525 number type is ignored in Xref and JSON output formats.
527 Use --_xformat="...%n" for Xref output format, or
528 --fields=+n-P for JSON output format.
529 pattern
531 Use only search patterns for all tags, rather than the
532 line numbers usually used for macro definitions. This has
533 the advantage of not referencing obsolete line numbers
534 when lines have been added or removed since the tag file
535 was generated.
536 mixed In this mode, patterns are generally used with an excep‐
538 tions. For Fortran, line numbers are used for common
539 blocks because their corresponding source lines are gen‐
540 erally identical, making pattern searches useless for
541 finding all matches.
542 Exuberant Ctags has one more exception; for C, line num‐
544 bers are used for macro definition tags. Universal Ctags
545 doesn't have this exception for C.
546 This was the default format generated by the original
548 ctags and is, therefore, retained as the default for this
549 option.
550 combine
552 Concatenate the line number and pattern with a semicolon
553 in between.
554 -n Equivalent to --excmd=number.
556 -N Equivalent to --excmd=pattern.
558 --extras=[+|-][<flags>|*]
560 Specifies whether to include extra tag entries for certain kinds
561 of information. See also "Extras" subsection to know what are
562 extras.
563 The parameter <flags> is a set of one-letter flags (and/or
565 long-name flags), each representing one kind of extra tag entry
566 to include in the tag file. If flags is preceded by either the
567 '+' or '-' character, the effect of each flag is added to, or
568 removed from, those currently enabled; otherwise the flags re‐
569 place any current settings. All entries are included if '*' is
570 given.
571 This --extras= option is for controlling extras common in all
573 languages (or language-independent extras). Universal Ctags
574 also supports language-specific extras. (See "Language-specific
575 fields and extras" about the concept). Use --extras-<LANG>= op‐
576 tion for controlling them.
577 --extras-(<LANG>|all)=[+|-][<flags>|*]
579 Specifies whether to include extra tag entries for certain kinds
580 of information for language <LANG>. Universal Ctags introduces
581 language-specific extras. See "Language-specific fields and ex‐
582 tras" about the concept. This option is for controlling them.
583 Specifies all as <LANG> to apply the parameter <flags> to all
585 languages; all extras are enabled with specifying '*' as the pa‐
586 rameter flags. If specifying nothing as the parameter flags
587 (--extras-all=), all extras are disabled. These two combinations
588 are useful for testing.
589 Check the output of the --list-extras=<LANG> option for the ex‐
591 tras of specific language <LANG>.
592 --fields=[+|-][<flags>|*]
594 Specifies which language-independent fields are to be included
595 in the tag entries. Language-independent fields are extension
596 fields which are common in all languages. See "TAG FILE FORMAT"
597 section, and "Extension fields" subsection, for details of ex‐
598 tension fields.
599 The parameter <flags> is a set of one-letter or long-name flags,
601 each representing one type of extension field to include. Each
602 flag or group of flags may be preceded by either '+' to add it
603 to the default set, or '-' to exclude it. In the absence of any
604 preceding '+' or '-' sign, only those fields explicitly listed
605 in flags will be included in the output (i.e. overriding the de‐
606 fault set). All fields are included if '*' is given.
607 This option is ignored if the option --format=1 (legacy tag file
609 format) has been specified.
610 Use --fields-<LANG>= option for controlling language-specific
612 fields.
613 --fields-(<LANG>|all)=[+|-][<flags>|*]
615 Specifies which language-specific fields are to be included in
616 the tag entries. Universal Ctags supports language-specific
617 fields. (See "Language-specific fields and extras" about the
618 concept).
619 Specify all as <LANG> to apply the parameter <flags> to all lan‐
621 guages; all fields are enabled with specifying '*' as the param‐
622 eter flags. If specifying nothing as the parameter <flags> (i.e.
623 --fields-all=), all fields are disabled. These two combinations
624 are useful for testing.
625 See the description of --fields=[+|-][<flags>|*] about <flags>.
627 Use --fields= option for controlling language-independent
629 fields.
630 --kinds-(<LANG>|all)=[+|-](<kinds>|*)
632 Specifies a list of language-specific <kinds> of tags (or kinds)
633 to include in the output file for a particular language, where
634 <LANG> is case-insensitive and is one of the built-in language
635 names (see the --list-languages option for a complete list).
636 The parameter <kinds> is a group of one-letter or long-name
638 flags designating kinds of tags (particular to the language) to
639 either include or exclude from the output. The specific sets of
640 flags recognized for each language, their meanings and defaults
641 may be list using the --list-kinds-full option.
642 Each letter or group of letters may be preceded by either '+' to
644 add it to, or '-' to remove it from, the default set. In the ab‐
645 sence of any preceding '+' or '-' sign, only those kinds explic‐
646 itly listed in kinds will be included in the output (i.e. over‐
647 riding the default for the specified language).
648 Specify '*' as the parameter to include all kinds implemented in
650 <LANG> in the output. Furthermore if all is given as <LANG>,
651 specification of the parameter kinds affects all languages de‐
652 fined in ctags. Giving all makes sense only when '*' or 'F' is
653 given as the parameter kinds.
654 As an example for the C language, in order to add prototypes and
656 external variable declarations to the default set of tag kinds,
657 but exclude macros, use --kinds-c=+px-d; to include only tags
658 for functions, use --kinds-c=f.
659 Some kinds of C and C++ languages are synchronized; enabling (or
661 disabling) a kind in one language enables the kind having the
662 same one-letter and long-name in the other language. See also
663 the description of MASTER column of --list-kinds-full.
664 --pattern-length-limit=<N>
666 Truncate patterns of tag entries after <N> characters. Disable
667 by setting to 0 (default is 96).
668 An input source file with long lines and multiple tag matches
670 per line can generate an excessively large tags file with an un‐
671 constrained pattern length. For example, running ctags on a
672 minified JavaScript source file often exhibits this behavior.
673 The truncation avoids cutting in the middle of a UTF-8 code
675 point spanning multiple bytes to prevent writing invalid byte
676 sequences from valid input files. This handling allows for an
677 extra 3 bytes above the configured limit in the worse case of a
678 4 byte code point starting right before the limit. Please also
679 note that this handling is fairly naive and fast, and although
680 it is resistant against any input, it requires a valid input to
681 work properly; it is not guaranteed to work as the user expects
682 when dealing with partially invalid UTF-8 input. This also par‐
683 tially affect non-UTF-8 input, if the byte sequence at the trun‐
684 cation length looks like a multibyte UTF-8 sequence. This should
685 however be rare, and in the worse case will lead to including up
686 to an extra 3 bytes above the limit.
687 --pseudo-tags=[+|-](<pseudo-tag>|*)
689 Enable/disable emitting pseudo-tag named <pseudo-tag>. If '*'
690 is given, enable/disable emitting all pseudo-tags.
691 --put-field-prefix
693 Put UCTAGS as prefix for the name of fields newly introduced in
694 Universal Ctags.
695 Some fields are newly introduced in Universal Ctags and more
697 will be introduced in the future. Other tags generators may also
698 introduce their specific fields.
699 In such a situation, there is a concern about conflicting field
701 names; mixing tags files generated by multiple tags generators
702 including Universal Ctags is difficult. This option provides a
703 workaround for such station.
704 $ ctags --fields='{line}{end}' -o - hello.c
706 main hello.c /^main(int argc, char **argv)$/;" f line:3 end:6
707 $ ctags --put-field-prefix --fields='{line}{end}' -o - hello.c
708 main hello.c /^main(int argc, char **argv)$/;" f line:3 UCTAGSend:6
709 In the above example, the prefix is put to end field which is
711 newly introduced in Universal Ctags.
712 --roles-(<LANG>|all).(<kind>|*)=[+|-][<roles>|*]
714 Specifies a list of kind-specific roles of tags to include in
715 the output file for a particular language. <kind> specifies the
716 kind where the <roles> are defined. <LANG> specifies the lan‐
717 guage where the kind is defined. Each role in <roles> must be
718 surrounded by braces (e.g. {system} for a role named "system").
719 Like --kinds-<LANG> option, '+' is for adding the role to the
721 list, and '-' is for removing from the list. '*' is for includ‐
722 ing all roles of the kind to the list. The option with no
723 argument makes the list empty.
724 Both a one-letter flag or a long name flag surrounded by braces
726 are acceptable for specifying a kind (e.g. --roles-C.h=+{sys‐
727 tem}{local} or --roles-C.{header}=+{system}{local}). '*' can be
728 used for <KIND> only for adding/removing all roles of all kinds
729 in a language to/from the list (e.g. --roles-C.*=* or
730 --roles-C.*=).
731 all can be used for <LANG> only for adding/removing all roles of
733 all kinds in all languages to/from the list (e.g.
734 --roles-all.*=* or --roles-all.*=).
735 --tag-relative=(yes|no|always|never)
737 Specifies how the file paths recorded in the tag file. The de‐
738 fault is yes when running in etags mode (see the -e option), no
739 otherwise.
740 yes indicates that the file paths recorded in the tag file
742 should be relative to the directory containing the tag
743 file unless the files supplied on the command line are
744 specified with absolute paths.
745 no indicates that the file paths recorded in the tag file
747 should be relative to the current directory unless the
748 files supplied on the command line are specified with ab‐
749 solute paths.
750 always indicates the recorded file paths should be relative even
752 if source file names are passed in with absolute paths.
753 never indicates the recorded file paths should be absolute even
755 if source file names are passed in with relative paths.
756 --use-slash-as-filename-separator[=(yes|no)]
758 Uses slash ('/') character as filename separators instead of
759 backslash ('\') character when printing input: field. The de‐
760 fault is yes for the default "u-ctags" output format, and no for
761 the other formats.
762 This option is available on MS Windows only.
764 -B Use backward searching patterns (e.g. ?pattern?). [Ignored in
766 etags mode]
767 -F Use forward searching patterns (e.g. /pattern/) (default). [Ig‐
769 nored in etags mode]
770 Option File Options
772 --options=<pathname>
773 Read additional options from file or directory.
774 ctags searches <pathname> in the optlib path list first. If
776 ctags cannot find a file or directory in the list, ctags reads a
777 file or directory at the specified <pathname>.
778 If a file is specified, it should contain one option per line.
780 If a directory is specified, files suffixed with .ctags under it
781 are read in alphabetical order.
782 As a special case, if --options=NONE is specified as the first
784 option on the command line, preloading is disabled; the option
785 will disable the automatic reading of any configuration options
786 from a file (see "FILES").
787 --options-maybe=<pathname>
789 Same as --options but doesn't cause an error if file (or direc‐
790 tory) specified with <pathname> doesn't exist.
791 --optlib-dir=[+]<directory>
793 Add an optlib <directory> to or reset the optlib path list. See
794 "Default optlib path list" about the default elements for optlib
795 path list.
796 optlib Options
798 See ctags-optlib(7) for details of each option.
799 --kinddef-<LANG>=<letter>,<name>,<description>
801 Define a kind for <LANG>. Don't be confused this with
802 --kinds-<LANG>.
803 --langdef=<name>
805 Defines a new user-defined language, <name>, to be parsed with
806 regular expressions.
807 --mline-regex-<LANG>=/<line_pattern>/<name_pat‐
809 tern>/<kind-spec>/[<flags>]
810 Define multi-line regular expression for locating tags in spe‐
811 cific language.
812 --regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]
814 Define single-line regular expression for locating tags in spe‐
815 cific language.
816 Language Specific Options
818 --if0[=(yes|no)]
819 Indicates a preference as to whether code within an "#if 0"
820 branch of a preprocessor conditional should be examined for
821 non-macro tags (macro tags are always included). Because the in‐
822 tent of this construct is to disable code, the default value of
823 this option is no (disabled).
824 Note that this indicates a preference only and does not guaran‐
826 tee skipping code within an "#if 0" branch, since the fall-back
827 algorithm used to generate tags when preprocessor conditionals
828 are too complex follows all branches of a conditional.
829 --line-directives[=(yes|no)]
831 Specifies whether #line directives should be recognized. These
832 are present in the output of a preprocessor and contain the line
833 number, and possibly the file name, of the original source
834 file(s) from which the preprocessor output file was generated.
835 This option is off by default.
836 When enabled, this option will cause ctags to generate tag en‐
838 tries marked with the file names and line numbers of their loca‐
839 tions original source file(s), instead of their actual locations
840 in the preprocessor output. The actual file names placed into
841 the tag file will have the same leading path components as the
842 preprocessor output file, since it is assumed that the original
843 source files are located relative to the preprocessor output
844 file (unless, of course, the #line directive specifies an abso‐
845 lute path).
846 Note: This option is generally only useful when used together
848 with the --excmd=number (-n) option. Also, you may have to use
849 either the --langmap or --language-force option if the extension
850 of the preprocessor output file is not known to ctags.
851 -D <macro>=<definition>
853 Defines a C preprocessor <macro>. This emulates the behavior of
854 the corresponding gcc option. All types of macros are supported,
855 including the ones with parameters and variable arguments.
856 Stringification, token pasting and recursive macro expansion are
857 also supported. This extends the function provided by -I op‐
858 tion.
859 -h (<list>|default)
861 Specifies a <list> of file extensions, separated by periods,
862 which are to be interpreted as include (or header) files. To in‐
863 dicate files having no extension, use a period not followed by a
864 non-period character (e.g. '.', ..x, .x.).
865 This option only affects how the scoping of particular kinds of
867 tags are interpreted (i.e. whether or not they are considered as
868 globally visible or visible only within the file in which they
869 are defined); it does not map the extension to any particular
870 language. Any tag which is located in a non-include file and
871 cannot be seen (e.g. linked to) from another file is considered
872 to have file-limited (e.g. static) scope. No kind of tag appear‐
873 ing in an include file will be considered to have file-limited
874 scope.
875 If the first character in the list is '+', then the extensions
877 in the list will be appended to the current list; otherwise, the
878 list will replace the current list. See, also, the fileScope/F
879 flag of --extras option.
880 The default list is .h.H.hh.hpp.hxx.h++.inc.def. To restore the
882 default list, specify "-h default".
883 Note that if an extension supplied to this option is not already
885 mapped to a particular language (see "Determining file lan‐
886 guage", above), you will also need to use either the
887 --map-<LANG>, --langmap or --language-force option.
888 -I <identifier-list>
890 Specifies a <identifier-list> of identifiers which are to be
891 specially handled while parsing C and C++ source files. This op‐
892 tion is specifically provided to handle special cases arising
893 through the use of preprocessor macros. When the identifiers
894 listed are simple identifiers, these identifiers will be ignored
895 during parsing of the source files.
896 If an identifier is suffixed with a '+' character (i.e. "-I
898 FOO+"), ctags will also ignore any parenthesis-enclosed argument
899 list which may immediately follow the identifier in the source
900 files. See the example of "-I MODULE_VERSION+" below.
901 If two identifiers are separated with the '=' character (i.e. -I
903 FOO=BAR), the first identifiers is replaced by the second iden‐
904 tifiers for parsing purposes. The list of identifiers may be
905 supplied directly on the command line or read in from a separate
906 file. See the example of "-I CLASS=class" below.
907 If the first character of <identifier-list> is '@', '.' or a
909 pathname separator ('/' or '\'), or the first two characters
910 specify a drive letter (e.g. C:), the parameter <identi‐
911 fier-list> will be interpreted as a filename from which to read
912 a list of identifiers, one per input line.
913 Otherwise, <identifier-list> is a list of identifiers (or iden‐
915 tifier pairs) to be specially handled, each delimited by either
916 a comma or by white space (in which case the list should be
917 quoted to keep the entire list as one command line argument).
918 Multiple -I options may be supplied. To clear the list of ignore
920 identifiers, supply a single dash ('-') for <identifier-list>.
921 This feature is useful when preprocessor macros are used in such
923 a way that they cause syntactic confusion due to their presence.
924 Indeed, this is the best way of working around a number of prob‐
925 lems caused by the presence of syntax-busting macros in source
926 files (see "CAVEATS"). Some examples will illustrate this
927 point.
928 int foo ARGDECL4(void *, ptr, long int, nbytes)
930 In the above example, the macro ARGDECL4 would be mistakenly in‐
932 terpreted to be the name of the function instead of the correct
933 name of foo. Specifying "-I ARGDECL4" results in the correct be‐
934 havior.
935 /* creates an RCS version string in module */
937 MODULE_VERSION("$Revision$")
938 In the above example the macro invocation looks too much like a
940 function definition because it is not followed by a semicolon
941 (indeed, it could even be followed by a global variable defini‐
942 tion that would look much like a K&R style function parameter
943 declaration). In fact, this seeming function definition could
944 possibly even cause the rest of the file to be skipped over
945 while trying to complete the definition. Specifying "-I MOD‐
946 ULE_VERSION+" would avoid such a problem.
947 CLASS Example {
949 // your content here
950 };
951 The example above uses CLASS as a preprocessor macro which ex‐
953 pands to something different for each platform. For instance
954 CLASS may be defined as class __declspec(dllexport) on Win32
955 platforms and simply class on UNIX. Normally, the absence of the
956 C++ keyword class would cause the source file to be incorrectly
957 parsed. Correct behavior can be restored by specifying "-I
958 CLASS=class".
959 --param-<LANG>.<name>=<argument>
961 Set a <LANG> specific parameter, a parameter specific to the
962 <LANG>.
963 Available parameters can be listed with --list-params.
965 Listing Options
967 --list-aliases[=(<language>|all)]
968 Lists the aliases for either the specified <language> or all
969 languages, and then exits. all is used as default value if the
970 option argument is omitted. The aliases are used when heuristi‐
971 cally testing a language parser for a source file.
972 --list-excludes
974 Lists the current exclusion patterns used to exclude files.
975 --list-extras[=(<language>|NONE|all)]
977 Lists the extras recognized for either the specified <language>
978 or all languages. If NONE is specified, it lists only extras
979 common in all languages. See "Extras" subsection to know what
980 are extras. all is used as default value if the option argument
981 is omitted.
982 An extra can be enabled or disabled with --extras= for common
984 extras in all languages, or --extras-<LANG>= for the specified
985 language. These option takes one-letter flag or long-name flag
986 as a parameter for specifying an extra.
987 The meaning of columns in output are as follows:
989 LETTER One-letter flag. '-' means the extra does not have
991 one-letter flag.
992 NAME Long-name flag. The long-name is used in extras field.
994 ENABLED
996 Whether the extra is enabled or not. It takes yes or no.
997 LANGUAGE
999 The name of language if the extra is owned by a parser.
1000 NONE means the extra is common in parsers.
1001 DESCRIPTION
1003 Human readable description for the extra.
1004 --list-features
1006 Lists the compiled features.
1007 --list-fields[=(<language>|NONE|all)]
1009 Lists the fields recognized for either the specified <language>
1010 or all languages. If NONE is specified, it lists only fields
1011 common in all languages. See "Extension fields" subsection to
1012 know what are fields. all is used as default value if the op‐
1013 tion argument is omitted.
1014 The meaning of columns are as follows:
1016 LETTER One-letter flag. '-' means the field does not have
1018 one-letter flag.
1019 NAME Long-name of field.
1021 ENABLED
1023 Whether the field is enabled or not. It takes yes or no.
1024 LANGUAGE
1026 The name of language if the field is owned by a parser.
1027 NONE means that the field is a language-independent field
1028 which is common in all languages.
1029 JSTYPE JSON type used in printing the value of field when --out‐
1031 put-format=json is specified. See ctags-client-tools(7).
1032 FIXED Whether this field can be disabled or not in tags output.
1034 Some fields are printed always in tags output. They have
1036 yes as the value for this column.
1037 Unlike the tag output mode, JSON output mode allows dis‐
1039 abling any fields.
1040 OP How this field can be accessed from optscript code. This
1042 field is for Universal Ctags developers.
1043 DESCRIPTION
1045 Human readable description for the field.
1046 --list-kinds[=(<language>|all)]
1048 Subset of --list-kinds-full. This option is kept for back‐
1049 ward-compatibility with Exuberant Ctags.
1050 This option prints only LETTER, DESCRIPTION, and ENABLED fields
1052 of --list-kinds-full output. However, the presentation of EN‐
1053 ABLED column is different from that of --list-kinds-full option;
1054 [off] follows after description if the kind is disabled, and
1055 nothing follows if enabled. The most of all kinds are en‐
1056 abled by default.
1057 The critical weakness of this option is that this option does
1059 not print the name of kind. Universal Ctags introduces
1060 --list-kinds-full because it considers that names are important.
1061 This option does not work with --machinable nor
1063 --with-list-header.
1064 --list-kinds-full[=(<language>|all)]
1066 Lists the tag kinds recognized for either the specified <lan‐
1067 guage> or all languages, and then exits. See "Kinds" subsection
1068 to learn what kinds are. all is used as default value if the
1069 option argument is omitted.
1070 Each kind of tag recorded in the tag file is represented by a
1072 one-letter flag, or a long-name flag. They are also used to fil‐
1073 ter the tags placed into the output through use of the
1074 --kinds-<LANG> option.
1075 The meaning of columns are as follows:
1077 LANGUAGE
1079 The name of language having the kind.
1080 LETTER One-letter flag. This must be unique in a language.
1082 NAME The long-name flag of the kind. This can be used as the
1084 alternative to the one-letter flag described above. If
1085 enabling K field with --fields=+K, ctags uses long-names
1086 instead of one-letters in tags output. To enable/disable
1087 a kind with --kinds-<LANG> option, long-name surrounded
1088 by braces instead of one-letter. See "Letters and names"
1089 for details. This must be unique in a language.
1090 ENABLED
1092 Whether the kind is enabled or not. It takes yes or no.
1093 REFONLY
1095 Whether the kind is specialized for reference tagging or
1096 not. If the column is yes, the kind is for reference
1097 tagging, and it is never used for definition tagging. See
1098 also "TAG ENTRIES".
1099 NROLES The number of roles this kind has. See also "Roles".
1101 MASTER The master parser controlling enablement of the kind. A
1103 kind belongs to a language (owner) in Universal Ctags;
1104 enabling and disabling a kind in a language has no effect
1105 on a kind in another language even if both kinds has the
1106 same one-letter flag and/or the same long-name flag. In
1107 other words, the namespace of kinds are separated by lan‐
1108 guage.
1109 However, Exuberant Ctags does not separate the kinds of C
1111 and C++. Enabling/disabling kindX in C language en‐
1112 ables/disables a kind in C++ language having the same
1113 long-name flag with kindX. To emulate this behavior in
1114 Universal Ctags, a concept named master parser is intro‐
1115 duced. Enabling/disabling some kinds are synchronized un‐
1116 der the control of a master language.
1117 $ ctags --kinds-C=+'{local}' --list-kinds-full \
1119 | grep -E '^(#|C\+\+ .* local)'
1120 #LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION
1121 C++ l local yes no 0 C local variables
1122 $ ctags --kinds-C=-'{local}' --list-kinds-full \
1123 | grep -E '^(#|C\+\+ .* local)'
1124 #LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION
1125 C++ l local no no 0 C local variables
1126 You see ENABLED field of local kind of C++ language is
1128 changed Though local kind of C language is enabled/dis‐
1129 abled. If you swap the languages, you see the same re‐
1130 sult.
1131 DESCRIPTION
1133 Human readable description for the kind.
1134 --list-languages
1136 Lists the names of the languages understood by ctags, and then
1137 exits. These language names are case insensitive and may be used
1138 in many other options like --language-force, --languages,
1139 --kinds-<LANG>, --regex-<LANG>, and so on.
1140 Each language listed is disabled if followed by [disabled]. To
1142 use the parser for such a language, specify the language as an
1143 argument of --languages=+ option.
1144 --machinable and --with-list-header options are ignored if they
1146 are specified with this option.
1147 --list-map-extensions[=(<language>|all)]
1149 Lists the file extensions which associate a file name with a
1150 language for either the specified <language> or all languages,
1151 and then exits. all is used as default value if the option ar‐
1152 gument is omitted.
1153 --list-map-patterns[=(<language>|all)]
1155 Lists the file name patterns which associate a file name with a
1156 language for either the specified <language> or all languages,
1157 and then exits. all is used as default value if the option ar‐
1158 gument is omitted.
1159 --list-maps[=(<language>|all)]
1161 Lists file name patterns and the file extensions which associate
1162 a file name with a language for either the specified <language>
1163 or all languages, and then exits. all is used as default value
1164 if the option argument is omitted.
1165 To list the file extensions or file name patterns individually,
1167 use --list-map-extensions or --list-map-patterns option. See
1168 the --langmap option, and "Determining file language", above.
1169 This option does not work with --machinable nor
1171 --with-list-header.
1172 --list-mline-regex-flags
1174 Output list of flags which can be used in a multiline regex
1175 parser definition. See ctags-optlib(7).
1176 --list-params[=(<language>|all)]
1178 Lists the parameters for either the specified <language> or all
1179 languages, and then exits. all is used as default value if the
1180 option argument is omitted.
1181 --list-pseudo-tags
1183 Output list of pseudo-tags.
1184 --list-regex-flags
1186 Lists the flags that can be used in --regex-<LANG> option. See
1187 ctags-optlib(7).
1188 --list-roles[=(<language>|all)[.(<kind-specs>|*)]]
1190 List the roles for either the specified <language> or all lan‐
1191 guages. all is used as default value if the option argument is
1192 omitted.
1193 If the parameter <kindspecs> is given after the parameter <lan‐
1195 guage> or all with concatenating with '.', list only roles de‐
1196 fined in the kinds. Both one-letter flags and long name flags
1197 surrounded by braces are acceptable as the parameter <kind‐
1198 specs>.
1199 The meaning of columns are as follows:
1201 LANGUAGE
1203 The name of language having the role.
1204 KIND(L/N)
1206 The one-letter flag and the long-name flag of kind having
1207 the role.
1208 NAME The long-name flag of the role.
1210 ENABLED
1212 Whether the kind is enabled or not. It takes yes or no.
1213 DESCRIPTION
1215 Human readable description for the role.
1216 --list-subparsers[=(<baselang>|all)]
1218 Lists the subparsers for a base language for either the speci‐
1219 fied <baselang> or all languages, and then exits. all is used
1220 as default value if the option argument is omitted.
1221 --machinable[=(yes|no)]
1223 Use tab character as separators for --list- option output. It
1224 may be suitable for scripting. See "List options" for considered
1225 use cases. Disabled by default.
1226 --with-list-header[=(yes|no)]
1228 Print headers describing columns in --list- option output. See
1229 also "List options".
1230 Miscellaneous Options
1232 --help Prints to standard output a detailed usage description, and then
1233 exits.
1234 -? Equivalent to --help.
1236 --help-full
1238 Prints to standard output a detailed usage description including
1239 experimental features, and then exits. Visit
1240 https://docs.ctags.io/ for information about the latest exciting
1241 experimental features.
1242 --license
1244 Prints a summary of the software license to standard output, and
1245 then exits.
1246 --print-language
1248 Just prints the language parsers for specified source files, and
1249 then exits.
1250 --quiet[=(yes|no)]
1252 Write fewer messages (default is no).
1253 --totals[=(yes|no|extra)]
1255 Prints statistics about the source files read and the tag file
1256 written during the current invocation of ctags. This option is
1257 no by default.
1258 The extra value prints parser specific statistics for parsers
1260 gathering such information.
1261 --verbose[=(yes|no)]
1263 Enable verbose mode. This prints out information on option pro‐
1264 cessing and a brief message describing what action is being
1265 taken for each file considered by ctags. Normally, ctags does
1266 not read command line arguments until after options are read
1267 from the configuration files (see "FILES", below). However, if
1268 this option is the first argument on the command line, it will
1269 take effect before any options are read from these sources. The
1270 default is no.
1271 -V Equivalent to --verbose.
1273 --version[=<language>|NONE]
1275 Prints a version identifier for ctags to standard output, and
1276 then exits. This is guaranteed to always contain the string
1277 "Universal Ctags". See also the description for TAG_PROGRAM_VER‐
1278 SION and TAG_OUTPUT_VERSION in ctags-client-tools(7).
1279 If NONE is given, prints the version identifier in a simplified
1281 way.
1282 If <language> is given, print the version identifier for the
1284 parser for <language>. See also the description for
1285 TAG_PARSER_VERSION in ctags-client-tools(7).
1286 Obsoleted Options
1288 These options are kept for backward-compatibility with Exuberant Ctags.
1289 -w This option is silently ignored for backward-compatibility with
1291 the ctags of SVR4 Unix.
1292 --file-scope[=(yes|no)]
1294 This options is removed. Use --extras=[+|-]F or --ex‐
1295 tras=[+|-]{fileScope} instead.
1296 --extra=[+|-][<flags>|*]
1298 Equivalent to --extras=[+|-][<flags>|*], which was introduced to
1299 make the option naming convention align to the other options
1300 like --kinds-<LANG>= and --fields=.
1301 --<LANG>-kinds=[+|-](<kinds>|*)
1303 This option is obsolete. Use --kinds-<LANG>=... instead.
1304
1306 As ctags considers each source file name in turn, it tries to determine
1307 the language of the file by applying tests described in "Determining
1308 file language".
1309 If a language was identified, the file is opened and then the appropri‐
1311 ate language parser is called to operate on the currently open file.
1312 The parser parses through the file and adds an entry to the tag file
1313 for each language object it is written to handle. See "TAG FILE FOR‐
1314 MAT", below, for details on these entries.
1315 Notes for C/C++ Parser
1317 This implementation of ctags imposes no formatting requirements on C
1318 code as do legacy implementations. Older implementations of ctags
1319 tended to rely upon certain formatting assumptions in order to help it
1320 resolve coding dilemmas caused by preprocessor conditionals.
1321 In general, ctags tries to be smart about conditional preprocessor di‐
1323 rectives. If a preprocessor conditional is encountered within a state‐
1324 ment which defines a tag, ctags follows only the first branch of that
1325 conditional (except in the special case of #if 0, in which case it fol‐
1326 lows only the last branch). The reason for this is that failing to pur‐
1327 sue only one branch can result in ambiguous syntax, as in the following
1328 example:
1329 #ifdef TWO_ALTERNATIVES
1331 struct {
1332 #else
1333 union {
1334 #endif
1335 short a;
1336 long b;
1337 }
1338 Both branches cannot be followed, or braces become unbalanced and ctags
1340 would be unable to make sense of the syntax.
1341 If the application of this heuristic fails to properly parse a file,
1343 generally due to complicated and inconsistent pairing within the condi‐
1344 tionals, ctags will retry the file using a different heuristic which
1345 does not selectively follow conditional preprocessor branches, but in‐
1346 stead falls back to relying upon a closing brace ('}') in column 1 as
1347 indicating the end of a block once any brace imbalance results from
1348 following a #if conditional branch.
1349 ctags will also try to specially handle arguments lists enclosed in
1351 double sets of parentheses in order to accept the following conditional
1352 construct:
1353 extern void foo __ARGS((int one, char two));
1355 Any name immediately preceding the '((' will be automatically ignored
1357 and the previous name will be used.
1358 C++ operator definitions are specially handled. In order for consis‐
1360 tency with all types of operators (overloaded and conversion), the op‐
1361 erator name in the tag file will always be preceded by the string "op‐
1362 erator " (i.e. even if the actual operator definition was written as
1363 "operator<<").
1364 After creating or appending to the tag file, it is sorted by the tag
1366 name, removing identical tag lines.
1367 Determining file language
1369 File name mapping
1370 Unless the --language-force option is specified, the language of each
1371 source file is automatically selected based upon a mapping of file
1372 names to languages. The mappings in effect for each language may be
1373 displayed using the --list-maps option and may be changed using the
1374 --langmap or --map-<LANG> options.
1375 If the name of a file is not mapped to a language, ctags tries to
1377 heuristically guess the language for the file by inspecting its con‐
1378 tent.
1379 All files that have no file name mapping and no guessed parser are ig‐
1381 nored. This permits running ctags on all files in either a single di‐
1382 rectory (e.g. "ctags *"), or on all files in an entire source direc‐
1383 tory tree (e.g. "ctags -R"), since only those files whose names are
1384 mapped to languages will be scanned.
1385 An extension may be mapped to multiple parsers. For example, .h are
1387 mapped to C++, C and ObjectiveC. These mappings can cause issues. ctags
1388 tries to select the proper parser for the source file by applying
1389 heuristics to its content, however it is not perfect. In case of is‐
1390 sues one can use --language-force=<language>,
1391 --langmap=<map>[,<map>[...]], or the --map-<LANG>=[+|-]<exten‐
1392 sion>|<pattern> options. (Some of the heuristics are applied whether
1393 --guess-language-eagerly is given or not.)
1394 Heuristically guessing
1396 If ctags cannot select a parser from the mapping of file names, various
1397 heuristic tests are conducted to determine the language:
1398 template file name testing
1400 If the file name has an .in extension, ctags applies the mapping
1401 to the file name without the extension. For example, config.h is
1402 tested for a file named config.h.in.
1403 interpreter testing
1405 The first line of the file is checked to see if the file is a #!
1406 script for a recognized language. ctags looks for a parser hav‐
1407 ing the same name.
1408 If ctags finds no such parser, ctags looks for the name in alias
1410 lists. For example, consider if the first line is #!/bin/sh.
1411 Though ctags has a "shell" parser, it doesn't have a "sh"
1412 parser. However, sh is listed as an alias for shell, therefore
1413 ctags selects the "shell" parser for the file.
1414 An exception is env. If env is specified (for example
1416 "#!/usr/bin/env python"), ctags reads more lines to find real
1417 interpreter specification.
1418 To display the list of aliases, use --list-aliases option. To
1420 add an item to the list or to remove an item from the list, use
1421 the --alias-<LANG>=+<pattern> or --alias-<LANG>=-<pattern> op‐
1422 tion respectively.
1423 zsh autoload tag testing
1425 If the first line starts with #compdef or #autoload, ctags re‐
1426 gards the line as "zsh".
1427 emacs mode at the first line testing
1429 The Emacs editor has multiple editing modes specialized for pro‐
1430 gramming languages. Emacs can recognize a marker called modeline
1431 in a file and utilize the marker for the mode selection. This
1432 heuristic test does the same as what Emacs does.
1433 ctags treats MODE as a name of interpreter and applies the same
1435 rule of "interpreter" testing if the first line has one of the
1436 following patterns:
1437 -*- mode: MODE -*-
1439 or
1441 -*- MODE -*-
1443 emacs mode at the EOF testing
1445 Emacs editor recognizes another marker at the end of file as a
1446 mode specifier. This heuristic test does the same as what Emacs
1447 does.
1448 ctags treats MODE as a name of an interpreter and applies the
1450 same rule of "interpreter" heuristic testing, if the lines at
1451 the tail of the file have the following pattern:
1452 Local Variables:
1454 ...
1455 mode: MODE
1456 ...
1457 End:
1458 3000 characters are sought from the end of file to find the pat‐
1460 tern.
1461 vim modeline testing
1463 Like the modeline of the Emacs editor, Vim editor has the same
1464 concept. ctags treats TYPE as a name of interpreter and applies
1465 the same rule of "interpreter" heuristic testing if the first or
1466 last 5 lines of the file have one of the following patterns:
1467 filetype=TYPE
1469 or
1471 ft=TYPE
1473 PHP marker testing
1475 If the first line is started with <?php, ctags regards the line
1476 as "php".
1477 Looking into the file contents is a more expensive operation than file
1479 name matching. So ctags runs the testings in limited conditions. "in‐
1480 terpreter" testing is enabled only when a file is an executable or the
1481 --guess-language-eagerly (-G in short) option is given. The other
1482 heuristic tests are enabled only when -G option is given.
1483 The --print-language option can be used just to print the results of
1485 parser selections for given files instead of generating a tags file.
1486 Examples:
1488 $ ctags --print-language config.h.in input.m input.unknown
1490 config.h.in: C++
1491 input.m: MatLab
1492 input.unknown: NONE
1493 NONE means that ctags does not select any parser for the file.
1495
1497 This section describes the tag file format briefly. See tags(5) and
1498 ctags-client-tools(7) for more details.
1499 When not running in etags mode, each entry in the tag file consists of
1501 a separate line, each looking like this, called regular tags, in the
1502 most general case:
1503 <tag_name><TAB><file_name><TAB><ex_cmd>;"<TAB><extension_fields>
1505 The fields and separators of these lines are specified as follows:
1507 1. <tag_name>: tag name
1509 2. <TAB>: single tab character
1511 3. <file_name>: name of the file in which the object associated with
1513 the tag is located
1514 4. <TAB>: single tab character
1516 5. <ex_cmd>: EX command used to locate the tag within the file; gen‐
1518 erally a search pattern (either /pattern/ or ?pattern?) or line
1519 number (see --excmd=<type> option).
1520 6. ;"<TAB><extension_fields>: a set of extension fields. See "‐
1522 Extension fields" for more details.
1523 Tag file format 2 (see --format) extends the EX command to in‐
1525 clude the extension fields embedded in an EX comment immediately
1526 appended to the EX command, which leaves it backward-compatible
1527 with original vi(1) implementations.
1528 A few special tags, called pseudo tags, are written into the tag file
1530 for internal purposes.
1531 !_TAG_FILE_FORMAT 2 /extended format; --format=1 will not append ;" to lines/
1533 !_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted, 2=foldcase/
1534 ...
1535 --pseudo-tags=[+|-](<pseudo-tag>|*) option enables or disables emitting
1537 pseudo-tags.
1538 See the output of "ctags --list-pseudo-tags" for the list of the kinds.
1540 See also tags(5) and ctags-client-tools(7) for more details of the
1541 pseudo tags.
1542 These tags are composed in such a way that they always sort to the top
1544 of the file. Therefore, the first two characters of these tags are used
1545 a magic number to detect a tag file for purposes of determining whether
1546 a valid tag file is being overwritten rather than a source file.
1547 Note that the name of each source file will be recorded in the tag file
1549 exactly as it appears on the command line. Therefore, if the path you
1550 specified on the command line was relative to the current directory,
1551 then it will be recorded in that same manner in the tag file. See, how‐
1552 ever, the --tag-relative=(yes|no|always|never) option for how this be‐
1553 havior can be modified.
1554
1556 A tag is an index for a language object. The concept of a tag and re‐
1557 lated items in Exuberant Ctags are refined and extended in Universal
1558 Ctags.
1559 A tag is categorized into definition tags or reference tags. In gen‐
1561 eral, Exuberant Ctags only tags definitions of language objects: places
1562 where newly named language objects are introduced. Universal Ctags, on
1563 the other hand, can also tag references of language objects: places
1564 where named language objects are used. However, support for generating
1565 reference tags is new and limited to specific areas of specific lan‐
1566 guages in the current version.
1567 Extension fields
1569 A tag can record various information, called extension fields.
1570 Extension fields are tab-separated key-value pairs appended to the end
1572 of the EX command as a comment, as described above. These key value
1573 pairs appear in the general form key:value.
1574 In addition, information on the scope of the tag definition may be
1576 available, with the key portion equal to some language-dependent con‐
1577 struct name and its value the name declared for that construct in the
1578 program. This scope entry indicates the scope in which the tag was
1579 found. For example, a tag generated for a C structure member would
1580 have a scope looking like struct:myStruct.
1581 --fields=[+|-][<flags>|*] and --fields-(<LANG>|all)=[+|-][<flags>|*]
1583 options specifies which available extension fields are to be included
1584 in the tag entries.
1585 See the output of "ctags --list-fields" for the list of extension
1587 fields. The essential fields are name, input, pattern, and line. The
1588 meaning of major fields is as follows (long-name flag/one-letter flag):
1589 access/a
1591 Indicates the visibility of this class member, where value is
1592 specific to the language.
1593 end/e Indicates the line number of the end lines of the language ob‐
1595 ject.
1596 extras/E
1598 Extra tag type information. See "Extras" for details.
1599 file/f Indicates that the tag has file-limited visibility. This key has
1601 no corresponding value. Enabled by default.
1602 implementation/m
1604 When present, this indicates a limited implementation (abstract
1605 vs. concrete) of a routine or class, where value is specific to
1606 the language (virtual or pure virtual for C++; abstract for
1607 Java).
1608 inherits/i
1610 When present, value is a comma-separated list of classes from
1611 which this class is derived (i.e. inherits from).
1612 input/F
1614 The name of source file where name is defined or referenced.
1615 k Kind of tag as one-letter. Enabled by default. This field has
1617 no long-name. See also kind/z flag.
1618 K Kind of tag as long-name. This field has no long-name. See
1620 also kind/z flag.
1621 kind/z Include the kind: key in kind field. See also k and K flags.
1623 language/l
1625 Language of source file containing tag
1626 line/n The line number where name is defined or referenced in input.
1628 name/N The name of language objects.
1630 nth/o The order in the parent scope. (i.e. 4th parameter in the func‐
1632 tion).
1633 pattern/P
1635 Can be used to search the name in input
1636 roles/r
1638 Roles assigned to the tag. See "Roles" for more details.
1639 s Scope of tag definition. Enabled by default. This field has no
1641 long-name. See also scope/Z flag.
1642 scope/Z
1644 Prepend the scope: key to scope (s) field. See also s flag.
1645 scopeKind/p
1647 Kind of scope as long-name
1648 signature/S
1650 When present, value is a language-dependent representation of
1651 the signature of a routine (e.g. prototype or parameter list). A
1652 routine signature in its complete form specifies the return type
1653 of a routine and its formal argument list. This extension field
1654 is presently supported only for C-based languages and does not
1655 include the return type.
1656 typeref/t
1658 Type and name of a variable, typedef, or return type of callable
1659 like function as typeref: field. Enabled by default.
1660 Kinds
1662 kind is a field which represents the kind of language object specified
1663 by a tag. Kinds used and defined are very different between parsers.
1664 For example, C language defines macro, function, variable, typedef,
1665 etc.
1666 --kinds-(<LANG>|all)=[+|-](<kinds>|*) option specifies a list of lan‐
1668 guage-specific kinds of tags (or kinds) to include in the output file
1669 for a particular language.
1670 See the output of "ctags --list-kinds-full" for the complete list of
1672 the kinds.
1673 Its value is either one of the corresponding one-letter flags or a
1675 long-name flag. It is permitted (and is, in fact, the default) for the
1676 key portion of this field to be omitted. The optional behaviors are
1677 controlled with the --fields option as follows.
1678 $ ctags -o - kinds.c
1680 foo kinds.c /^int foo() {$/;" f typeref:typename:int
1681 $ ctags --fields=+k -o - kinds.c
1682 foo kinds.c /^int foo() {$/;" f typeref:typename:int
1683 $ ctags --fields=+K -o - kinds.c
1684 foo kinds.c /^int foo() {$/;" function typeref:typename:int
1685 $ ctags --fields=+z -o - kinds.c
1686 foo kinds.c /^int foo() {$/;" kind:f typeref:typename:int
1687 $ ctags --fields=+zK -o - kinds.c
1688 foo kinds.c /^int foo() {$/;" kind:function typeref:typename:int
1689 Roles
1691 Role is a newly introduced concept in Universal Ctags. Role is a con‐
1692 cept associated with reference tags, and is not implemented widely yet.
1693 As described previously in "Kinds", the kind field represents the type
1695 of language object specified with a tag, such as a function vs. a vari‐
1696 able. Specific kinds are defined for reference tags, such as the C++
1697 kind header for header file, or Java kind package for package state‐
1698 ments. For such reference kinds, a roles field can be added to distin‐
1699 guish the role of the reference kind. In other words, the kind field
1700 identifies the what of the language object, whereas the roles field
1701 identifies the how of a referenced language object. Roles are only used
1702 with specific kinds.
1703 For a definition tag, this field takes def as a value.
1705 For example, Baz is tagged as a reference tag with kind package and
1707 with role imported with the following code.
1708 package Bar;
1710 import Baz;
1711 class Foo {
1713 // ...
1714 }
1715 $ ctags --fields=+KEr -uo - roles.java
1717 Bar roles.java /^package Bar;$/;" package roles:def
1718 Foo roles.java /^class Foo {$/;" class roles:def
1719 $ ctags --fields=+EKr --extras=+r -uo - roles.java
1720 Bar roles.java /^package Bar;$/;" package roles:def
1721 Baz roles.java /^import Baz;$/;" package roles:imported extras:reference
1722 Foo roles.java /^class Foo {$/;" class roles:def
1723 --roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*] option specifies a
1725 list of kind-specific roles of tags to include in the output file for a
1726 particular language.
1727 Inquire the output of "ctags --list-roles" for the list of roles.
1729 Extras
1731 Generally, ctags tags only language objects appearing in source files,
1732 as is. In other words, a value for a name: field should be found on the
1733 source file associated with the name:. An extra type tag (extra) is for
1734 tagging a language object with a processed name, or for tagging some‐
1735 thing not associated with a language object. A typical extra tag is
1736 qualified, which tags a language object with a class-qualified or
1737 scope-qualified name.
1738 --extras-(<LANG>|all)=[+|-][<flags>|*] option specifies whether to in‐
1740 clude extra tag entries for certain kinds of information.
1741 Inquire the output of ctags --list-extras for the list of extras. The
1743 meaning of major extras is as follows (long-name flag/one-letter flag):
1744 anonymous/none
1746 Include an entry for the language object that has no name like
1747 lambda function. This extra has no one-letter flag and is en‐
1748 abled by default.
1749 The extra tag is useful as a placeholder to fill scope fields
1751 for language objects defined in a language object with no name.
1752 struct {
1754 double x, y;
1755 } p = { .x = 0.0, .y = 0.0 };
1756 'x' and 'y' are the members of a structure. When filling the
1758 scope fields for them, ctags has trouble because the struct
1759 where 'x' and 'y' belong to has no name. For overcoming the
1760 trouble, ctags generates an anonymous extra tag for the struct
1761 and fills the scope fields with the name of the extra tag.
1762 $ ctags --fields=-f -uo - input.c
1764 __anon9f26d2460108 input.c /^struct {$/;" s
1765 x input.c /^ double x, y;$/;" m struct:__anon9f26d2460108
1766 y input.c /^ double x, y;$/;" m struct:__anon9f26d2460108
1767 p input.c /^} p = { .x = 0.0, .y = 0.0 };$/;" v typeref:struct:__anon9f26d2460108
1768 The above tag output has __anon9f26d2460108 as an anonymous ex‐
1770 tra tag. The typeref field of 'p' also receives the benefit of
1771 it.
1772 fileScope/F
1774 Indicates whether tags scoped only for a single file (i.e. tags
1775 which cannot be seen outside of the file in which they are de‐
1776 fined, such as language objects with static modifier of C lan‐
1777 guage) should be included in the output. See also the -h option.
1778 This extra tag is enabled by default. Add --extras=-F option not
1780 to output tags scoped only for a single-file. This is the re‐
1781 placement for --file-scope option of Exuberant Ctags.
1782 static int f() {
1784 return 0;
1785 }
1786 int g() {
1787 return 0;
1788 }
1789 $ ctags -uo - filescope.c
1791 f filescope.c /^static int f() {$/;" f typeref:typename:int file:
1792 g filescope.c /^int g() {$/;" f typeref:typename:int
1793 $ ctags --extras=-F -uo - filescope.c
1794 g filescope.c /^int g() {$/;" f typeref:typename:int
1795 inputFile/f
1797 Include an entry for the base file name of every source file
1798 (e.g. example.c), which addresses the first line of the file.
1799 This flag is the replacement for --file-tags hidden option of
1800 Exuberant Ctags.
1801 If the end: field is enabled, the end line number of the file
1803 can be attached to the tag. (However, ctags omits the end: field
1804 if no newline is in the file like an empty file.)
1805 By default, ctags doesn't create the inputFile/f extra tag for
1807 the source file when ctags doesn't find a parser for it. En‐
1808 abling Unknown parser with --languages=+Unknown forces ctags to
1809 create the extra tags for any source files.
1810 The etags mode enables the Unknown parser implicitly.
1812 pseudo/p
1814 Include pseudo-tags. Enabled by default unless the tag file is
1815 written to standard output. See ctags-client-tools(7) about the
1816 detail of pseudo-tags.
1817 qualified/q
1819 Include an extra class-qualified or namespace-qualified tag en‐
1820 try for each tag which is a member of a class or a namespace.
1821 This may allow easier location of a specific tags when multiple
1823 occurrences of a tag name occur in the tag file. Note, however,
1824 that this could potentially more than double the size of the tag
1825 file.
1826 The actual form of the qualified tag depends upon the language
1828 from which the tag was derived (using a form that is most natu‐
1829 ral for how qualified calls are specified in the language). For
1830 C++ and Perl, it is in the form class::member; for Eiffel and
1831 Java, it is in the form class.member.
1832 Note: Using backslash characters as separators forming qualified
1834 name in PHP. However, in tags output of Universal Ctags, a back‐
1835 slash character in a name is escaped with a backslash character.
1836 See tags(5) about the escaping.
1837 The following example demonstrates the qualified extra tag.
1839 class point {
1841 double x;
1842 };
1843 For the above source file, ctags tags point and x by default.
1845 If the qualified extra is enabled from the command line (--ex‐
1846 tras=+q), then point.x is also tagged even though the string
1847 "point.x" is not in the source code.
1848 $ ctags --fields=+K -uo - qualified.java
1850 point qualified.java /^class point {$/;" class
1851 x qualified.java /^ double x;$/;" field class:point
1852 $ ctags --fields=+K --extras=+q -uo - qualified.java
1853 point qualified.java /^class point {$/;" class
1854 x qualified.java /^ double x;$/;" field class:point
1855 point.x qualified.java /^ double x;$/;" field class:point
1856 reference/r
1858 Include reference tags. See "TAG ENTRIES" about reference tags.
1859 The following example demonstrates the reference extra tag.
1861 #include <stdio.h>
1863 #include "utils.h"
1864 #define X
1865 #undef X
1866 The roles:system or roles:local fields will be added depending
1868 on whether the include file name begins with '<' or not.
1869 "#define X" emits a definition tag. On the other hand "#undef X"
1871 emits a reference tag.
1872 $ ctags --fields=+EKr -uo - inc.c
1874 X inc.c /^#define X$/;" macro file: roles:def extras:fileScope
1875 $ ctags --fields=+EKr --extras=+r -uo - inc.c
1876 stdio.h inc.c /^#include <stdio.h>/;" header roles:system extras:reference
1877 utils.h inc.c /^#include "utils.h"/;" header roles:local extras:reference
1878 X inc.c /^#define X$/;" macro file: roles:def extras:fileScope
1879 X inc.c /^#undef X$/;" macro file: roles:undef extras:fileScope,reference
1880 Language-specific fields and extras
1882 Exuberant Ctags has the concept of fields and extras. They are common
1883 between parsers of different languages. Universal Ctags extends this
1884 concept by providing language-specific fields and extras.
1885
1887 vi(1) will, by default, expect a tag file by the name tags in the cur‐
1888 rent directory. Once the tag file is built, the following commands ex‐
1889 ercise the tag indexing feature:
1890 vi -t tag
1892 Start vi and position the cursor at the file and line where tag
1893 is defined.
1894 :ta tag
1896 Find a tag.
1897 Ctrl-] Find the tag under the cursor.
1899 Ctrl-T Return to previous location before jump to tag (not widely im‐
1901 plemented).
1902
1904 emacs(1) will, by default, expect a tag file by the name TAGS in the
1905 current directory. Once the tag file is built, the following commands
1906 exercise the tag indexing feature:
1907 M-x visit-tags-table <RET> FILE <RET>
1909 Select the tag file, FILE, to use.
1910 M-. [TAG] <RET>
1912 Find the first definition of TAG. The default tag is the identi‐
1913 fier under the cursor.
1914 M-* Pop back to where you previously invoked M-..
1916 C-u M-.
1918 Find the next definition for the last tag.
1919 For more commands, see the Tags topic in the Emacs info document.
1921
1923 NEdit version 5.1 and later can handle the new extended tag file format
1924 (see --format).
1925 • To make NEdit use the tag file, select "File->Load Tags File".
1927 • To jump to the definition for a tag, highlight the word, then press
1929 Ctrl-D.
1930 NEdit 5.1 can read multiple tag files from different directories. Set‐
1932 ting the X resource nedit.tagFile to the name of a tag file instructs
1933 NEdit to automatically load that tag file at startup time.
1934
1936 Because ctags is neither a preprocessor nor a compiler, use of pre‐
1937 processor macros can fool ctags into either missing tags or improperly
1938 generating inappropriate tags. Although ctags has been designed to han‐
1939 dle certain common cases, this is the single biggest cause of reported
1940 problems. In particular, the use of preprocessor constructs which alter
1941 the textual syntax of C can fool ctags. You can work around many such
1942 problems by using the -I option.
1943 Note that since ctags generates patterns for locating tags (see the
1945 --excmd option), it is entirely possible that the wrong line may be
1946 found by your editor if there exists another source line which is iden‐
1947 tical to the line containing the tag. The following example demon‐
1948 strates this condition:
1949 int variable;
1951 /* ... */
1953 void foo(variable)
1954 int variable;
1955 {
1956 /* ... */
1957 }
1958 Depending upon which editor you use and where in the code you happen to
1960 be, it is possible that the search pattern may locate the local parame‐
1961 ter declaration before it finds the actual global variable definition,
1962 since the lines (and therefore their search patterns) are identical.
1963 This can be avoided by use of the --excmd=n option.
1965
1967 See ctags-incompatibilities(7) about incompatibilities between Univer‐
1968 sal Ctags and Exuberant Ctags.
1969 This section describes major incompatibilities within versions of Uni‐
1971 versal Ctags.
1972 Unifying the kind Letter for unknown kinds
1974 Some parsers used different kind letters for unknown kinds.
1975 EmacsLisp used u. Go used u. Julian used x. Lisp used u. Lua
1976 used X. and Python used x. They were unified to Y in the during
1977 development of version 5.9.x.
1978
1980 ctags has more options than ls(1).
1981 ctags assumes the input file is written in the correct grammar. Other‐
1983 wise output of ctags is undefined. In other words it has garbage in,
1984 garbage out (GIGO) feature.
1985 When parsing a C++ member function definition (e.g. className::func‐
1987 tion), ctags cannot determine whether the scope specifier is a class
1988 name or a namespace specifier and always lists it as a class name in
1989 the scope portion of the extension fields. Also, if a C++ function is
1990 defined outside of the class declaration (the usual case), the access
1991 specification (i.e. public, protected, or private) and implementation
1992 information (e.g. virtual, pure virtual) contained in the function dec‐
1993 laration are not known when the tag is generated for the function defi‐
1994 nition. It will, however be available for prototypes (e.g.
1995 --kinds-c++=+p).
1996 No qualified tags are generated for language objects inherited into a
1998 class.
1999
2001 TMPDIR On Unix-like hosts where mkstemp(3) is available, the value of
2002 this variable specifies the directory in which to place tempo‐
2003 rary files. This can be useful if the size of a temporary file
2004 becomes too large to fit on the partition holding the default
2005 temporary directory defined at compilation time.
2006 ctags creates temporary files only if either (1) an emacs-style
2008 tag file is being generated, (2) the tag file is being sent to
2009 standard output, or (3) the program was compiled to use an in‐
2010 ternal sort algorithm to sort the tag files instead of the
2011 sort(1) utility of the operating system. If the sort(1) utility
2012 of the operating system is being used, it will generally observe
2013 this variable also.
2014 Note that if ctags is setuid, the value of TMPDIR will be ig‐
2016 nored.
2017
2019 Output files
2020 tags The default tag file created by ctags.
2021 TAGS The default tag file created by etags.
2023 Preloading option files
2025 $XDG_CONFIG_HOME/ctags/*.ctags, or $HOME/.config/ctags/*.ctags if
2026 $XDG_CONFIG_HOME is not defined (on other than MS Windows)
2027 $HOME/.ctags.d/*.ctags
2029 $HOMEDRIVE$HOMEPATH/ctags.d/*.ctags (on MS Windows only)
2031 .ctags.d/*.ctags
2033 ctags.d/*.ctags
2035 If any of these configuration files exist, each will be expected to
2036 contain a set of default options which are read in the order listed
2037 when ctags starts, but before any command line options are read.
2038 This makes it possible to set up personal or project-level defaults.
2039 It is possible to compile ctags to read an additional configuration
2041 file before any of those shown above, which will be indicated if the
2042 output produced by the --version option lists the custom-conf fea‐
2043 ture.
2044 Options appearing on the command line will override options speci‐
2046 fied in these files. Only options will be read from these files.
2047 Note that the option files are read in line-oriented mode in which
2049 spaces are significant (since shell quoting is not possible) but
2050 spaces at the beginning of a line are ignored. Each line of the file
2051 is read as one command line parameter (as if it were quoted with
2052 single quotes). Therefore, use new lines to indicate separate com‐
2053 mand-line arguments.
2054 A line starting with '#' is treated as a comment.
2056 *.ctags files in a directory are loaded in alphabetical order.
2058 Default optlib path list
2060 $XDG_CONFIG_HOME/ctags, or $HOME/.config/ctags if $XDG_CONFIG_HOME is
2061 not defined (on other than MS Windows)
2062 $HOME/.ctags.d
2064 $HOMEDRIVE$HOMEPATH/ctags.d (on MS Windows only)
2066 These directories are parts of the optlib path list by default. See
2067 "Option File Options" about the optlib path list.
2068 If you have a set of options that you want to enable conditionally,
2070 make a directory in the path in the optlib path list, and put the
2071 options to the files having .ctags as extensions under the direc‐
2072 tory. --options=<the-directory-name> is for enabling the options.
2073 For example, consider you have some options you want to enable only
2075 when tagging the Linux kernel source tree. In that case, make
2076 $HOME/.ctags.d/linux directory, put the options to
2077 $HOME/.ctags.d/linux/my.ctags. If you have many options, you can
2078 split them into multiple files like $HOME/.ctags.d/linux/de‐
2079 vice-driver.ctags and $HOME/.ctags.d/linux/network-stack.ctags. Ei‐
2080 ther way, you can enable the options in the .ctags file(s) under the
2081 directory by adding --options=linux to your ctags command line.
2082
2084 See ctags-optlib(7) for defining (or extending) a parser in a configu‐
2085 ration file.
2086 See tags(5) for the format of tag files.
2088 See ctags-incompatibilities(7) about known incompatible changes with
2090 Exuberant Ctags.
2091 See ctags-client-tools(7) if you are interested in writing a tool for
2093 processing tags files.
2094 See ctags-lang-python(7) about python input specific notes.
2096 See readtags(1) about a client tool for binary searching a name in a
2098 sorted tags file.
2099 The official Universal Ctags web site at: https://ctags.io/
2101 Also ex(1), vi(1), elvis(1), or, better yet, vim(1), the official edi‐
2103 tor of ctags. For more information on vim(1), see the Vim web site at:
2104 https://www.vim.org/
2105
2107 Universal Ctags project https://ctags.io/
2108 Darren Hiebert <dhiebert@users.sourceforge.net>
2110 http://DarrenHiebert.com/
2111
2113 "Think ye at all times of rendering some service to every member of the
2114 human race."
2115 "All effort and exertion put forth by man from the fullness of his
2117 heart is worship, if it is prompted by the highest motives and the will
2118 to do service to humanity."
2119 -- From the Baha'i Writings
2121
2123 This version of ctags (Universal Ctags) derived from the repository,
2124 known as fishman-ctags, started by Reza Jelveh.
2125 The fishman-ctags was derived from Exuberant Ctags.
2127 Some parsers are taken from tagmanager of the Geany (‐
2129 https://www.geany.org/) project.
2130 Exuberant Ctags was originally derived from and inspired by the ctags
2132 program by Steve Kirkendall <kirkenda@cs.pdx.edu> that comes with the
2133 Elvis vi clone (though virtually none of the original code remains).
2134 Credit is also due Bram Moolenaar <Bram@vim.org>, the author of vim,
2136 who has devoted so much of his time and energy both to developing the
2137 editor as a service to others, and to helping the orphans of Uganda.
2138 The section entitled "HOW TO USE WITH GNU EMACS" was shamelessly stolen
2140 from the info page for GNU etags.
21416.0.0 ctags(1)