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 a few ex‐
538 ceptions. For C, line numbers are used for macro defini‐
539 tion tags. For Fortran, line numbers are used for common
540 blocks because their corresponding source lines are gen‐
541 erally identical, making pattern searches useless for
542 finding all matches.
543 This was the default format generated by the original
545 ctags and is, therefore, retained as the default for this
546 option.
547 combine
549 Concatenate the line number and pattern with a semicolon
550 in between.
551 -n Equivalent to --excmd=number.
553 -N Equivalent to --excmd=pattern.
555 --extras=[+|-][<flags>|*]
557 Specifies whether to include extra tag entries for certain kinds
558 of information. See also "Extras" subsection to know what are
559 extras.
560 The parameter <flags> is a set of one-letter flags (and/or
562 long-name flags), each representing one kind of extra tag entry
563 to include in the tag file. If flags is preceded by either the
564 '+' or '-' character, the effect of each flag is added to, or
565 removed from, those currently enabled; otherwise the flags re‐
566 place any current settings. All entries are included if '*' is
567 given.
568 This --extras= option is for controlling extras common in all
570 languages (or language-independent extras). Universal Ctags
571 also supports language-specific extras. (See "Language-specific
572 fields and extras" about the concept). Use --extras-<LANG>= op‐
573 tion for controlling them.
574 --extras-(<LANG>|all)=[+|-][<flags>|*]
576 Specifies whether to include extra tag entries for certain kinds
577 of information for language <LANG>. Universal Ctags introduces
578 language-specific extras. See "Language-specific fields and ex‐
579 tras" about the concept. This option is for controlling them.
580 Specifies all as <LANG> to apply the parameter <flags> to all
582 languages; all extras are enabled with specifying '*' as the pa‐
583 rameter flags. If specifying nothing as the parameter flags
584 (--extras-all=), all extras are disabled. These two combinations
585 are useful for testing.
586 Check the output of the --list-extras=<LANG> option for the ex‐
588 tras of specific language <LANG>.
589 --fields=[+|-][<flags>|*]
591 Specifies which language-independent fields are to be included
592 in the tag entries. Language-independent fields are extension
593 fields which are common in all languages. See "TAG FILE FORMAT"
594 section, and "Extension fields" subsection, for details of ex‐
595 tension fields.
596 The parameter <flags> is a set of one-letter or long-name flags,
598 each representing one type of extension field to include. Each
599 flag or group of flags may be preceded by either '+' to add it
600 to the default set, or '-' to exclude it. In the absence of any
601 preceding '+' or '-' sign, only those fields explicitly listed
602 in flags will be included in the output (i.e. overriding the de‐
603 fault set). All fields are included if '*' is given.
604 This option is ignored if the option --format=1 (legacy tag file
606 format) has been specified.
607 Use --fields-<LANG>= option for controlling language-specific
609 fields.
610 --fields-(<LANG>|all)=[+|-][<flags>|*]
612 Specifies which language-specific fields are to be included in
613 the tag entries. Universal Ctags supports language-specific
614 fields. (See "Language-specific fields and extras" about the
615 concept).
616 Specify all as <LANG> to apply the parameter <flags> to all lan‐
618 guages; all fields are enabled with specifying '*' as the param‐
619 eter flags. If specifying nothing as the parameter <flags> (i.e.
620 --fields-all=), all fields are disabled. These two combinations
621 are useful for testing.
622 See the description of --fields=[+|-][<flags>|*] about <flags>.
624 Use --fields= option for controlling language-independent
626 fields.
627 --kinds-(<LANG>|all)=[+|-](<kinds>|*)
629 Specifies a list of language-specific <kinds> of tags (or kinds)
630 to include in the output file for a particular language, where
631 <LANG> is case-insensitive and is one of the built-in language
632 names (see the --list-languages option for a complete list).
633 The parameter <kinds> is a group of one-letter or long-name
635 flags designating kinds of tags (particular to the language) to
636 either include or exclude from the output. The specific sets of
637 flags recognized for each language, their meanings and defaults
638 may be list using the --list-kinds-full option.
639 Each letter or group of letters may be preceded by either '+' to
641 add it to, or '-' to remove it from, the default set. In the ab‐
642 sence of any preceding '+' or '-' sign, only those kinds explic‐
643 itly listed in kinds will be included in the output (i.e. over‐
644 riding the default for the specified language).
645 Specify '*' as the parameter to include all kinds implemented in
647 <LANG> in the output. Furthermore if all is given as <LANG>,
648 specification of the parameter kinds affects all languages de‐
649 fined in ctags. Giving all makes sense only when '*' or 'F' is
650 given as the parameter kinds.
651 As an example for the C language, in order to add prototypes and
653 external variable declarations to the default set of tag kinds,
654 but exclude macros, use --kinds-c=+px-d; to include only tags
655 for functions, use --kinds-c=f.
656 Some kinds of C and C++ languages are synchronized; enabling (or
658 disabling) a kind in one language enables the kind having the
659 same one-letter and long-name in the other language. See also
660 the description of MASTER column of --list-kinds-full.
661 --pattern-length-limit=<N>
663 Truncate patterns of tag entries after <N> characters. Disable
664 by setting to 0 (default is 96).
665 An input source file with long lines and multiple tag matches
667 per line can generate an excessively large tags file with an un‐
668 constrained pattern length. For example, running ctags on a
669 minified JavaScript source file often exhibits this behavior.
670 The truncation avoids cutting in the middle of a UTF-8 code
672 point spanning multiple bytes to prevent writing invalid byte
673 sequences from valid input files. This handling allows for an
674 extra 3 bytes above the configured limit in the worse case of a
675 4 byte code point starting right before the limit. Please also
676 note that this handling is fairly naive and fast, and although
677 it is resistant against any input, it requires a valid input to
678 work properly; it is not guaranteed to work as the user expects
679 when dealing with partially invalid UTF-8 input. This also par‐
680 tially affect non-UTF-8 input, if the byte sequence at the trun‐
681 cation length looks like a multibyte UTF-8 sequence. This should
682 however be rare, and in the worse case will lead to including up
683 to an extra 3 bytes above the limit.
684 --pseudo-tags=[+|-](<pseudo-tag>|*)
686 Enable/disable emitting pseudo-tag named <pseudo-tag>. If '*'
687 is given, enable/disable emitting all pseudo-tags.
688 --put-field-prefix
690 Put UCTAGS as prefix for the name of fields newly introduced in
691 Universal Ctags.
692 Some fields are newly introduced in Universal Ctags and more
694 will be introduced in the future. Other tags generators may also
695 introduce their specific fields.
696 In such a situation, there is a concern about conflicting field
698 names; mixing tags files generated by multiple tags generators
699 including Universal Ctags is difficult. This option provides a
700 workaround for such station.
701 $ ctags --fields='{line}{end}' -o - hello.c
703 main hello.c /^main(int argc, char **argv)$/;" f line:3 end:6
704 $ ctags --put-field-prefix --fields='{line}{end}' -o - hello.c
705 main hello.c /^main(int argc, char **argv)$/;" f line:3 UCTAGSend:6
706 In the above example, the prefix is put to end field which is
708 newly introduced in Universal Ctags.
709 --roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*]
711 Specifies a list of kind-specific roles of tags to include in
712 the output file for a particular language. <kind> specifies the
713 kind where the <roles> are defined. <LANG> specifies the lan‐
714 guage where the kind is defined. Each role in <roles> must be
715 surrounded by braces (e.g. {system} for a role named "system").
716 Like --kinds-<LANG> option, '+' is for adding the role to the
718 list, and '-' is for removing from the list. '*' is for includ‐
719 ing all roles of the kind to the list. The option with no
720 argument makes the list empty.
721 Both a one-letter flag or a long name flag surrounded by braces
723 are acceptable for specifying a kind (e.g. --roles-C.h=+{sys‐
724 tem}{local} or --roles-C.{header}=+{system}{local}). '*' can be
725 used for <KIND> only for adding/removing all roles of all kinds
726 in a language to/from the list (e.g. --roles-C.*=* or
727 --roles-C.*=).
728 all can be used for <LANG> only for adding/removing all roles of
730 all kinds in all languages to/from the list (e.g.
731 --roles-all.*=* or --roles-all.*=).
732 --tag-relative=(yes|no|always|never)
734 Specifies how the file paths recorded in the tag file. The de‐
735 fault is yes when running in etags mode (see the -e option), no
736 otherwise.
737 yes indicates that the file paths recorded in the tag file
739 should be relative to the directory containing the tag
740 file unless the files supplied on the command line are
741 specified with absolute paths.
742 no indicates that the file paths recorded in the tag file
744 should be relative to the current directory unless the
745 files supplied on the command line are specified with ab‐
746 solute paths.
747 always indicates the recorded file paths should be relative even
749 if source file names are passed in with absolute paths.
750 never indicates the recorded file paths should be absolute even
752 if source file names are passed in with relative paths.
753 --use-slash-as-filename-separator[=(yes|no)]
755 Uses slash ('/') character as filename separators instead of
756 backslash ('\') character when printing input: field. The de‐
757 fault is yes for the default "u-ctags" output format, and no for
758 the other formats.
759 This option is available on MS Windows only.
761 -B Use backward searching patterns (e.g. ?pattern?). [Ignored in
763 etags mode]
764 -F Use forward searching patterns (e.g. /pattern/) (default). [Ig‐
766 nored in etags mode]
767 Option File Options
769 --options=<pathname>
770 Read additional options from file or directory.
771 ctags searches <pathname> in the optlib path list first. If
773 ctags cannot find a file or directory in the list, ctags reads a
774 file or directory at the specified <pathname>.
775 If a file is specified, it should contain one option per line.
777 If a directory is specified, files suffixed with .ctags under it
778 are read in alphabetical order.
779 As a special case, if --options=NONE is specified as the first
781 option on the command line, preloading is disabled; the option
782 will disable the automatic reading of any configuration options
783 from a file (see "FILES").
784 --options-maybe=<pathname>
786 Same as --options but doesn't cause an error if file (or direc‐
787 tory) specified with <pathname> doesn't exist.
788 --optlib-dir=[+]<directory>
790 Add an optlib <directory> to or reset the optlib path list. By
791 default, the optlib path list is empty.
792 optlib Options
794 See ctags-optlib(7) for details of each option.
795 --kinddef-<LANG>=<letter>,<name>,<description>
797 Define a kind for <LANG>. Don't be confused this with
798 --kinds-<LANG>.
799 --langdef=<name>
801 Defines a new user-defined language, <name>, to be parsed with
802 regular expressions.
803 --mline-regex-<LANG>=/<line_pattern>/<name_pat‐
805 tern>/<kind-spec>/[<flags>]
806 Define multi-line regular expression for locating tags in spe‐
807 cific language.
808 --regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]
810 Define single-line regular expression for locating tags in spe‐
811 cific language.
812 Language Specific Options
814 --if0[=(yes|no)]
815 Indicates a preference as to whether code within an "#if 0"
816 branch of a preprocessor conditional should be examined for
817 non-macro tags (macro tags are always included). Because the in‐
818 tent of this construct is to disable code, the default value of
819 this option is no (disabled).
820 Note that this indicates a preference only and does not guaran‐
822 tee skipping code within an "#if 0" branch, since the fall-back
823 algorithm used to generate tags when preprocessor conditionals
824 are too complex follows all branches of a conditional.
825 --line-directives[=(yes|no)]
827 Specifies whether #line directives should be recognized. These
828 are present in the output of a preprocessor and contain the line
829 number, and possibly the file name, of the original source
830 file(s) from which the preprocessor output file was generated.
831 This option is off by default.
832 When enabled, this option will cause ctags to generate tag en‐
834 tries marked with the file names and line numbers of their loca‐
835 tions original source file(s), instead of their actual locations
836 in the preprocessor output. The actual file names placed into
837 the tag file will have the same leading path components as the
838 preprocessor output file, since it is assumed that the original
839 source files are located relative to the preprocessor output
840 file (unless, of course, the #line directive specifies an abso‐
841 lute path).
842 Note: This option is generally only useful when used together
844 with the --excmd=number (-n) option. Also, you may have to use
845 either the --langmap or --language-force option if the extension
846 of the preprocessor output file is not known to ctags.
847 -D <macro>=<definition>
849 Defines a C preprocessor <macro>. This emulates the behavior of
850 the corresponding gcc option. All types of macros are supported,
851 including the ones with parameters and variable arguments.
852 Stringification, token pasting and recursive macro expansion are
853 also supported. This extends the function provided by -I op‐
854 tion.
855 -h (<list>|default)
857 Specifies a <list> of file extensions, separated by periods,
858 which are to be interpreted as include (or header) files. To in‐
859 dicate files having no extension, use a period not followed by a
860 non-period character (e.g. '.', ..x, .x.).
861 This option only affects how the scoping of particular kinds of
863 tags are interpreted (i.e. whether or not they are considered as
864 globally visible or visible only within the file in which they
865 are defined); it does not map the extension to any particular
866 language. Any tag which is located in a non-include file and
867 cannot be seen (e.g. linked to) from another file is considered
868 to have file-limited (e.g. static) scope. No kind of tag appear‐
869 ing in an include file will be considered to have file-limited
870 scope.
871 If the first character in the list is '+', then the extensions
873 in the list will be appended to the current list; otherwise, the
874 list will replace the current list. See, also, the fileScope/F
875 flag of --extras option.
876 The default list is .h.H.hh.hpp.hxx.h++.inc.def. To restore the
878 default list, specify "-h default".
879 Note that if an extension supplied to this option is not already
881 mapped to a particular language (see "Determining file lan‐
882 guage", above), you will also need to use either the
883 --map-<LANG>, --langmap or --language-force option.
884 -I <identifier-list>
886 Specifies a <identifier-list> of identifiers which are to be
887 specially handled while parsing C and C++ source files. This op‐
888 tion is specifically provided to handle special cases arising
889 through the use of preprocessor macros. When the identifiers
890 listed are simple identifiers, these identifiers will be ignored
891 during parsing of the source files.
892 If an identifier is suffixed with a '+' character (i.e. "-I
894 FOO+"), ctags will also ignore any parenthesis-enclosed argument
895 list which may immediately follow the identifier in the source
896 files. See the example of "-I MODULE_VERSION+" below.
897 If two identifiers are separated with the '=' character (i.e. -I
899 FOO=BAR), the first identifiers is replaced by the second iden‐
900 tifiers for parsing purposes. The list of identifiers may be
901 supplied directly on the command line or read in from a separate
902 file. See the example of "-I CLASS=class" below.
903 If the first character of <identifier-list> is '@', '.' or a
905 pathname separator ('/' or '\'), or the first two characters
906 specify a drive letter (e.g. C:), the parameter <identi‐
907 fier-list> will be interpreted as a filename from which to read
908 a list of identifiers, one per input line.
909 Otherwise, <identifier-list> is a list of identifiers (or iden‐
911 tifier pairs) to be specially handled, each delimited by either
912 a comma or by white space (in which case the list should be
913 quoted to keep the entire list as one command line argument).
914 Multiple -I options may be supplied. To clear the list of ignore
916 identifiers, supply a single dash ('-') for <identifier-list>.
917 This feature is useful when preprocessor macros are used in such
919 a way that they cause syntactic confusion due to their presence.
920 Indeed, this is the best way of working around a number of prob‐
921 lems caused by the presence of syntax-busting macros in source
922 files (see "CAVEATS"). Some examples will illustrate this
923 point.
924 int foo ARGDECL4(void *, ptr, long int, nbytes)
926 In the above example, the macro ARGDECL4 would be mistakenly in‐
928 terpreted to be the name of the function instead of the correct
929 name of foo. Specifying "-I ARGDECL4" results in the correct be‐
930 havior.
931 /* creates an RCS version string in module */
933 MODULE_VERSION("$Revision$")
934 In the above example the macro invocation looks too much like a
936 function definition because it is not followed by a semicolon
937 (indeed, it could even be followed by a global variable defini‐
938 tion that would look much like a K&R style function parameter
939 declaration). In fact, this seeming function definition could
940 possibly even cause the rest of the file to be skipped over
941 while trying to complete the definition. Specifying "-I MOD‐
942 ULE_VERSION+" would avoid such a problem.
943 CLASS Example {
945 // your content here
946 };
947 The example above uses CLASS as a preprocessor macro which ex‐
949 pands to something different for each platform. For instance
950 CLASS may be defined as class __declspec(dllexport) on Win32
951 platforms and simply class on UNIX. Normally, the absence of the
952 C++ keyword class would cause the source file to be incorrectly
953 parsed. Correct behavior can be restored by specifying "-I
954 CLASS=class".
955 --param-<LANG>:<name>=<argument>
957 Set a <LANG> specific parameter, a parameter specific to the
958 <LANG>.
959 Available parameters can be listed with --list-params.
961 Listing Options
963 --list-aliases[=(<language>|all)]
964 Lists the aliases for either the specified <language> or all
965 languages, and then exits. all is used as default value if the
966 option argument is omitted. The aliases are used when heuristi‐
967 cally testing a language parser for a source file.
968 --list-excludes
970 Lists the current exclusion patterns used to exclude files.
971 --list-extras[=(<language>|all)]
973 Lists the extras recognized for either the specified <language>
974 or all languages. See "Extras" subsection to know what are ex‐
975 tras. all is used as default value if the option argument is
976 omitted.
977 An extra can be enabled or disabled with --extras= for common
979 extras in all languages, or --extras-<LANG>= for the specified
980 language. These option takes one-letter flag or long-name flag
981 as a parameter for specifying an extra.
982 The meaning of columns in output are as follows:
984 LETTER One-letter flag. '-' means the extra does not have
986 one-letter flag.
987 NAME Long-name flag. The long-name is used in extras field.
989 ENABLED
991 Whether the extra is enabled or not. It takes yes or no.
992 LANGUAGE
994 The name of language if the extra is owned by a parser.
995 NONE means the extra is common in parsers.
996 DESCRIPTION
998 Human readable description for the extra.
999 --list-features
1001 Lists the compiled features.
1002 --list-fields[=(<language>|all)]
1004 Lists the fields recognized for either the specified <language>
1005 or all languages. See "Extension fields" subsection to know what
1006 are fields. all is used as default value if the option argument
1007 is omitted.
1008 The meaning of columns are as follows:
1010 LETTER One-letter flag. '-' means the field does not have
1012 one-letter flag.
1013 NAME Long-name of field.
1015 ENABLED
1017 Whether the field is enabled or not. It takes yes or no.
1018 LANGUAGE
1020 The name of language if the field is owned by a parser.
1021 NONE means that the field is a language-independent field
1022 which is common in all languages.
1023 JSTYPE JSON type used in printing the value of field when --out‐
1025 put-format=json is specified. See ctags-client-tools(7).
1026 FIXED Whether this field can be disabled or not in tags output.
1028 Some fields are printed always in tags output. They have
1030 yes as the value for this column.
1031 Unlike the tag output mode, JSON output mode allows dis‐
1033 abling any fields.
1034 OP How this field can be accessed from optscript code. This
1036 field is for Universal Ctags developers.
1037 DESCRIPTION
1039 Human readable description for the field.
1040 --list-kinds[=(<language>|all)]
1042 Subset of --list-kinds-full. This option is kept for back‐
1043 ward-compatibility with Exuberant Ctags.
1044 This option prints only LETTER, DESCRIPTION, and ENABLED fields
1046 of --list-kinds-full output. However, the presentation of EN‐
1047 ABLED column is different from that of --list-kinds-full option;
1048 [off] follows after description if the kind is disabled, and
1049 nothing follows if enabled. The most of all kinds are en‐
1050 abled by default.
1051 The critical weakness of this option is that this option does
1053 not print the name of kind. Universal Ctags introduces
1054 --list-kinds-full because it considers that names are important.
1055 This option does not work with --machinable nor
1057 --with-list-header.
1058 --list-kinds-full[=(<language>|all)]
1060 Lists the tag kinds recognized for either the specified <lan‐
1061 guage> or all languages, and then exits. See "Kinds" subsection
1062 to learn what kinds are. all is used as default value if the
1063 option argument is omitted.
1064 Each kind of tag recorded in the tag file is represented by a
1066 one-letter flag, or a long-name flag. They are also used to fil‐
1067 ter the tags placed into the output through use of the
1068 --kinds-<LANG> option.
1069 The meaning of columns are as follows:
1071 LANGUAGE
1073 The name of language having the kind.
1074 LETTER One-letter flag. This must be unique in a language.
1076 NAME The long-name flag of the kind. This can be used as the
1078 alternative to the one-letter flag described above. If
1079 enabling K field with --fields=+K, ctags uses long-names
1080 instead of one-letters in tags output. To enable/disable
1081 a kind with --kinds-<LANG> option, long-name surrounded
1082 by braces instead of one-letter. See "Letters and names"
1083 for details. This must be unique in a language.
1084 ENABLED
1086 Whether the kind is enabled or not. It takes yes or no.
1087 REFONLY
1089 Whether the kind is specialized for reference tagging or
1090 not. If the column is yes, the kind is for reference
1091 tagging, and it is never used for definition tagging. See
1092 also "TAG ENTRIES".
1093 NROLES The number of roles this kind has. See also "Roles".
1095 MASTER The master parser controlling enablement of the kind. A
1097 kind belongs to a language (owner) in Universal Ctags;
1098 enabling and disabling a kind in a language has no effect
1099 on a kind in another language even if both kinds has the
1100 same one-letter flag and/or the same long-name flag. In
1101 other words, the namespace of kinds are separated by lan‐
1102 guage.
1103 However, Exuberant Ctags does not separate the kinds of C
1105 and C++. Enabling/disabling kindX in C language en‐
1106 ables/disables a kind in C++ language having the same
1107 long-name flag with kindX. To emulate this behavior in
1108 Universal Ctags, a concept named master parser is intro‐
1109 duced. Enabling/disabling some kinds are synchronized un‐
1110 der the control of a master language.
1111 $ ctags --kinds-C=+'{local}' --list-kinds-full \
1113 | grep -E '^(#|C\+\+ .* local)'
1114 #LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION
1115 C++ l local yes no 0 C local variables
1116 $ ctags --kinds-C=-'{local}' --list-kinds-full \
1117 | grep -E '^(#|C\+\+ .* local)'
1118 #LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION
1119 C++ l local no no 0 C local variables
1120 You see ENABLED field of local kind of C++ language is
1122 changed Though local kind of C language is enabled/dis‐
1123 abled. If you swap the languages, you see the same re‐
1124 sult.
1125 DESCRIPTION
1127 Human readable description for the kind.
1128 --list-languages
1130 Lists the names of the languages understood by ctags, and then
1131 exits. These language names are case insensitive and may be used
1132 in many other options like --language-force, --languages,
1133 --kinds-<LANG>, --regex-<LANG>, and so on.
1134 Each language listed is disabled if followed by [disabled]. To
1136 use the parser for such a language, specify the language as an
1137 argument of --languages=+ option.
1138 --machinable and --with-list-header options are ignored if they
1140 are specified with this option.
1141 --list-map-extensions[=(<language>|all)]
1143 Lists the file extensions which associate a file name with a
1144 language for either the specified <language> or all languages,
1145 and then exits. all is used as default value if the option ar‐
1146 gument is omitted.
1147 --list-map-patterns[=(<language>|all)]
1149 Lists the file name patterns 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-maps[=(<language>|all)]
1155 Lists file name patterns and the file extensions which associate
1156 a file name with a language for either the specified <language>
1157 or all languages, and then exits. all is used as default value
1158 if the option argument is omitted.
1159 To list the file extensions or file name patterns individually,
1161 use --list-map-extensions or --list-map-patterns option. See
1162 the --langmap option, and "Determining file language", above.
1163 This option does not work with --machinable nor
1165 --with-list-header.
1166 --list-mline-regex-flags
1168 Output list of flags which can be used in a multiline regex
1169 parser definition. See ctags-optlib(7).
1170 --list-params[=(<language>|all)]
1172 Lists the parameters for either the specified <language> or all
1173 languages, and then exits. all is used as default value if the
1174 option argument is omitted.
1175 --list-pseudo-tags
1177 Output list of pseudo-tags.
1178 --list-regex-flags
1180 Lists the flags that can be used in --regex-<LANG> option. See
1181 ctags-optlib(7).
1182 --list-roles[=(<language>|all)[.(<kind-specs>|*)]]
1184 List the roles for either the specified <language> or all lan‐
1185 guages. all is used as default value if the option argument is
1186 omitted.
1187 If the parameter <kindspecs> is given after the parameter <lan‐
1189 guage> or all with concatenating with '.', list only roles de‐
1190 fined in the kinds. Both one-letter flags and long name flags
1191 surrounded by braces are acceptable as the parameter <kind‐
1192 specs>.
1193 The meaning of columns are as follows:
1195 LANGUAGE
1197 The name of language having the role.
1198 KIND(L/N)
1200 The one-letter flag and the long-name flag of kind having
1201 the role.
1202 NAME The long-name flag of the role.
1204 ENABLED
1206 Whether the kind is enabled or not. It takes yes or no.
1207 DESCRIPTION
1209 Human readable description for the role.
1210 --list-subparsers[=(<baselang>|all)]
1212 Lists the subparsers for a base language for either the speci‐
1213 fied <baselang> or all languages, and then exits. all is used
1214 as default value if the option argument is omitted.
1215 --machinable[=(yes|no)]
1217 Use tab character as separators for --list- option output. It
1218 may be suitable for scripting. See "List options" for considered
1219 use cases. Disabled by default.
1220 --with-list-header[=(yes|no)]
1222 Print headers describing columns in --list- option output. See
1223 also "List options".
1224 Miscellaneous Options
1226 --help Prints to standard output a detailed usage description, and then
1227 exits.
1228 -? Equivalent to --help.
1230 --help-full
1232 Prints to standard output a detailed usage description including
1233 experimental features, and then exits. Visit
1234 https://docs.ctags.io/ for information about the latest exciting
1235 experimental features.
1236 --license
1238 Prints a summary of the software license to standard output, and
1239 then exits.
1240 --print-language
1242 Just prints the language parsers for specified source files, and
1243 then exits.
1244 --quiet[=(yes|no)]
1246 Write fewer messages (default is no).
1247 --totals[=(yes|no|extra)]
1249 Prints statistics about the source files read and the tag file
1250 written during the current invocation of ctags. This option is
1251 no by default.
1252 The extra value prints parser specific statistics for parsers
1254 gathering such information.
1255 --verbose[=(yes|no)]
1257 Enable verbose mode. This prints out information on option pro‐
1258 cessing and a brief message describing what action is being
1259 taken for each file considered by ctags. Normally, ctags does
1260 not read command line arguments until after options are read
1261 from the configuration files (see "FILES", below). However, if
1262 this option is the first argument on the command line, it will
1263 take effect before any options are read from these sources. The
1264 default is no.
1265 -V Equivalent to --verbose.
1267 --version
1269 Prints a version identifier for ctags to standard output, and
1270 then exits. This is guaranteed to always contain the string
1271 "Universal Ctags".
1272 Obsoleted Options
1274 These options are kept for backward-compatibility with Exuberant Ctags.
1275 -w This option is silently ignored for backward-compatibility with
1277 the ctags of SVR4 Unix.
1278 --file-scope[=(yes|no)]
1280 This options is removed. Use --extras=[+|-]F or --ex‐
1281 tras=[+|-]{fileScope} instead.
1282 --extra=[+|-][<flags>|*]
1284 Equivalent to --extras=[+|-][<flags>|*], which was introduced to
1285 make the option naming convention align to the other options
1286 like --kinds-<LANG>= and --fields=.
1287 --<LANG>-kinds=[+|-](<kinds>|*)
1289 This option is obsolete. Use --kinds-<LANG>=... instead.
1290
1292 As ctags considers each source file name in turn, it tries to determine
1293 the language of the file by applying tests described in "Determining
1294 file language".
1295 If a language was identified, the file is opened and then the appropri‐
1297 ate language parser is called to operate on the currently open file.
1298 The parser parses through the file and adds an entry to the tag file
1299 for each language object it is written to handle. See "TAG FILE FOR‐
1300 MAT", below, for details on these entries.
1301 Notes for C/C++ Parser
1303 This implementation of ctags imposes no formatting requirements on C
1304 code as do legacy implementations. Older implementations of ctags
1305 tended to rely upon certain formatting assumptions in order to help it
1306 resolve coding dilemmas caused by preprocessor conditionals.
1307 In general, ctags tries to be smart about conditional preprocessor di‐
1309 rectives. If a preprocessor conditional is encountered within a state‐
1310 ment which defines a tag, ctags follows only the first branch of that
1311 conditional (except in the special case of #if 0, in which case it fol‐
1312 lows only the last branch). The reason for this is that failing to pur‐
1313 sue only one branch can result in ambiguous syntax, as in the following
1314 example:
1315 #ifdef TWO_ALTERNATIVES
1317 struct {
1318 #else
1319 union {
1320 #endif
1321 short a;
1322 long b;
1323 }
1324 Both branches cannot be followed, or braces become unbalanced and ctags
1326 would be unable to make sense of the syntax.
1327 If the application of this heuristic fails to properly parse a file,
1329 generally due to complicated and inconsistent pairing within the condi‐
1330 tionals, ctags will retry the file using a different heuristic which
1331 does not selectively follow conditional preprocessor branches, but in‐
1332 stead falls back to relying upon a closing brace ('}') in column 1 as
1333 indicating the end of a block once any brace imbalance results from
1334 following a #if conditional branch.
1335 ctags will also try to specially handle arguments lists enclosed in
1337 double sets of parentheses in order to accept the following conditional
1338 construct:
1339 extern void foo __ARGS((int one, char two));
1341 Any name immediately preceding the '((' will be automatically ignored
1343 and the previous name will be used.
1344 C++ operator definitions are specially handled. In order for consis‐
1346 tency with all types of operators (overloaded and conversion), the op‐
1347 erator name in the tag file will always be preceded by the string "op‐
1348 erator " (i.e. even if the actual operator definition was written as
1349 "operator<<").
1350 After creating or appending to the tag file, it is sorted by the tag
1352 name, removing identical tag lines.
1353 Determining file language
1355 File name mapping
1356 Unless the --language-force option is specified, the language of each
1357 source file is automatically selected based upon a mapping of file
1358 names to languages. The mappings in effect for each language may be
1359 displayed using the --list-maps option and may be changed using the
1360 --langmap or --map-<LANG> options.
1361 If the name of a file is not mapped to a language, ctags tries to
1363 heuristically guess the language for the file by inspecting its con‐
1364 tent.
1365 All files that have no file name mapping and no guessed parser are ig‐
1367 nored. This permits running ctags on all files in either a single di‐
1368 rectory (e.g. "ctags *"), or on all files in an entire source direc‐
1369 tory tree (e.g. "ctags -R"), since only those files whose names are
1370 mapped to languages will be scanned.
1371 An extension may be mapped to multiple parsers. For example, .h are
1373 mapped to C++, C and ObjectiveC. These mappings can cause issues. ctags
1374 tries to select the proper parser for the source file by applying
1375 heuristics to its content, however it is not perfect. In case of is‐
1376 sues one can use --language-force=<language>,
1377 --langmap=<map>[,<map>[...]], or the --map-<LANG>=[+|-]<exten‐
1378 sion>|<pattern> options. (Some of the heuristics are applied whether
1379 --guess-language-eagerly is given or not.)
1380 Heuristically guessing
1382 If ctags cannot select a parser from the mapping of file names, various
1383 heuristic tests are conducted to determine the language:
1384 template file name testing
1386 If the file name has an .in extension, ctags applies the mapping
1387 to the file name without the extension. For example, config.h is
1388 tested for a file named config.h.in.
1389 interpreter testing
1391 The first line of the file is checked to see if the file is a #!
1392 script for a recognized language. ctags looks for a parser hav‐
1393 ing the same name.
1394 If ctags finds no such parser, ctags looks for the name in alias
1396 lists. For example, consider if the first line is #!/bin/sh.
1397 Though ctags has a "shell" parser, it doesn't have a "sh"
1398 parser. However, sh is listed as an alias for shell, therefore
1399 ctags selects the "shell" parser for the file.
1400 An exception is env. If env is specified (for example
1402 "#!/usr/bin/env python"), ctags reads more lines to find real
1403 interpreter specification.
1404 To display the list of aliases, use --list-aliases option. To
1406 add an item to the list or to remove an item from the list, use
1407 the --alias-<LANG>=+<pattern> or --alias-<LANG>=-<pattern> op‐
1408 tion respectively.
1409 zsh autoload tag testing
1411 If the first line starts with #compdef or #autoload, ctags re‐
1412 gards the line as "zsh".
1413 emacs mode at the first line testing
1415 The Emacs editor has multiple editing modes specialized for pro‐
1416 gramming languages. Emacs can recognize a marker called modeline
1417 in a file and utilize the marker for the mode selection. This
1418 heuristic test does the same as what Emacs does.
1419 ctags treats MODE as a name of interpreter and applies the same
1421 rule of "interpreter" testing if the first line has one of the
1422 following patterns:
1423 -*- mode: MODE -*-
1425 or
1427 -*- MODE -*-
1429 emacs mode at the EOF testing
1431 Emacs editor recognizes another marker at the end of file as a
1432 mode specifier. This heuristic test does the same as what Emacs
1433 does.
1434 ctags treats MODE as a name of an interpreter and applies the
1436 same rule of "interpreter" heuristic testing, if the lines at
1437 the tail of the file have the following pattern:
1438 Local Variables:
1440 ...
1441 mode: MODE
1442 ...
1443 End:
1444 3000 characters are sought from the end of file to find the pat‐
1446 tern.
1447 vim modeline testing
1449 Like the modeline of the Emacs editor, Vim editor has the same
1450 concept. ctags treats TYPE as a name of interpreter and applies
1451 the same rule of "interpreter" heuristic testing if the last 5
1452 lines of the file have one of the following patterns:
1453 filetype=TYPE
1455 or
1457 ft=TYPE
1459 PHP marker testing
1461 If the first line is started with <?php, ctags regards the line
1462 as "php".
1463 Looking into the file contents is a more expensive operation than file
1465 name matching. So ctags runs the testings in limited conditions. "in‐
1466 terpreter" testing is enabled only when a file is an executable or the
1467 --guess-language-eagerly (-G in short) option is given. The other
1468 heuristic tests are enabled only when -G option is given.
1469 The --print-language option can be used just to print the results of
1471 parser selections for given files instead of generating a tags file.
1472 Examples:
1474 $ ctags --print-language config.h.in input.m input.unknown
1476 config.h.in: C++
1477 input.m: MatLab
1478 input.unknown: NONE
1479 NONE means that ctags does not select any parser for the file.
1481
1483 This section describes the tag file format briefly. See tags(5) and
1484 ctags-client-tools(7) for more details.
1485 When not running in etags mode, each entry in the tag file consists of
1487 a separate line, each looking like this, called regular tags, in the
1488 most general case:
1489 <tag_name><TAB><file_name><TAB><ex_cmd>;"<TAB><extension_fields>
1491 The fields and separators of these lines are specified as follows:
1493 1. <tag_name>: tag name
1495 2. <TAB>: single tab character
1497 3. <file_name>: name of the file in which the object associated with
1499 the tag is located
1500 4. <TAB>: single tab character
1502 5. <ex_cmd>: EX command used to locate the tag within the file; gen‐
1504 erally a search pattern (either /pattern/ or ?pattern?) or line
1505 number (see --excmd=<type> option).
1506 6. ;"<TAB><extension_fields>: a set of extension fields. See "‐
1508 Extension fields" for more details.
1509 Tag file format 2 (see --format) extends the EX command to in‐
1511 clude the extension fields embedded in an EX comment immediately
1512 appended to the EX command, which leaves it backward-compatible
1513 with original vi(1) implementations.
1514 A few special tags, called pseudo tags, are written into the tag file
1516 for internal purposes.
1517 !_TAG_FILE_FORMAT 2 /extended format; --format=1 will not append ;" to lines/
1519 !_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted, 2=foldcase/
1520 ...
1521 --pseudo-tags=[+|-](<pseudo-tag>|*) option enables or disables emitting
1523 pseudo-tags.
1524 See the output of "ctags --list-pseudo-tags" for the list of the kinds.
1526 See also tags(5) and ctags-client-tools(7) for more details of the
1527 pseudo tags.
1528 These tags are composed in such a way that they always sort to the top
1530 of the file. Therefore, the first two characters of these tags are used
1531 a magic number to detect a tag file for purposes of determining whether
1532 a valid tag file is being overwritten rather than a source file.
1533 Note that the name of each source file will be recorded in the tag file
1535 exactly as it appears on the command line. Therefore, if the path you
1536 specified on the command line was relative to the current directory,
1537 then it will be recorded in that same manner in the tag file. See, how‐
1538 ever, the --tag-relative=(yes|no|always|never) option for how this be‐
1539 havior can be modified.
1540
1542 A tag is an index for a language object. The concept of a tag and re‐
1543 lated items in Exuberant Ctags are refined and extended in Universal
1544 Ctags.
1545 A tag is categorized into definition tags or reference tags. In gen‐
1547 eral, Exuberant Ctags only tags definitions of language objects: places
1548 where newly named language objects are introduced. Universal Ctags, on
1549 the other hand, can also tag references of language objects: places
1550 where named language objects are used. However, support for generating
1551 reference tags is new and limited to specific areas of specific lan‐
1552 guages in the current version.
1553 Extension fields
1555 A tag can record various information, called extension fields.
1556 Extension fields are tab-separated key-value pairs appended to the end
1558 of the EX command as a comment, as described above. These key value
1559 pairs appear in the general form key:value.
1560 In addition, information on the scope of the tag definition may be
1562 available, with the key portion equal to some language-dependent con‐
1563 struct name and its value the name declared for that construct in the
1564 program. This scope entry indicates the scope in which the tag was
1565 found. For example, a tag generated for a C structure member would
1566 have a scope looking like struct:myStruct.
1567 --fields=[+|-][<flags>|*] and --fields-(<LANG>|all)=[+|-][<flags>|*]
1569 options specifies which available extension fields are to be included
1570 in the tag entries.
1571 See the output of "ctags --list-fields" for the list of extension
1573 fields. The essential fields are name, input, pattern, and line. The
1574 meaning of major fields is as follows (long-name flag/one-letter flag):
1575 access/a
1577 Indicates the visibility of this class member, where value is
1578 specific to the language.
1579 end/e Indicates the line number of the end lines of the language ob‐
1581 ject.
1582 extras/E
1584 Extra tag type information. See "Extras" for details.
1585 file/f Indicates that the tag has file-limited visibility. This key has
1587 no corresponding value. Enabled by default.
1588 implementation/m
1590 When present, this indicates a limited implementation (abstract
1591 vs. concrete) of a routine or class, where value is specific to
1592 the language (virtual or pure virtual for C++; abstract for
1593 Java).
1594 inherits/i
1596 When present, value is a comma-separated list of classes from
1597 which this class is derived (i.e. inherits from).
1598 input/F
1600 The name of source file where name is defined or referenced.
1601 k Kind of tag as one-letter. Enabled by default. This field has
1603 no long-name. See also kind/z flag.
1604 K Kind of tag as long-name. This field has no long-name. See
1606 also kind/z flag.
1607 kind/z Include the kind: key in kind field. See also k and K flags.
1609 language/l
1611 Language of source file containing tag
1612 line/n The line number where name is defined or referenced in input.
1614 name/N The name of language objects.
1616 pattern/P
1618 Can be used to search the name in input
1619 roles/r
1621 Roles assigned to the tag. See "Roles" for more details.
1622 s Scope of tag definition. Enabled by default. This field has no
1624 long-name. See also scope/Z flag.
1625 scope/Z
1627 Prepend the scope: key to scope (s) field. See also s flag.
1628 scopeKind/p
1630 Kind of scope as long-name
1631 signature/S
1633 When present, value is a language-dependent representation of
1634 the signature of a routine (e.g. prototype or parameter list). A
1635 routine signature in its complete form specifies the return type
1636 of a routine and its formal argument list. This extension field
1637 is presently supported only for C-based languages and does not
1638 include the return type.
1639 typeref/t
1641 Type and name of a variable, typedef, or return type of callable
1642 like function as typeref: field. Enabled by default.
1643 Kinds
1645 kind is a field which represents the kind of language object specified
1646 by a tag. Kinds used and defined are very different between parsers.
1647 For example, C language defines macro, function, variable, typedef,
1648 etc.
1649 --kinds-(<LANG>|all)=[+|-](<kinds>|*) option specifies a list of lan‐
1651 guage-specific kinds of tags (or kinds) to include in the output file
1652 for a particular language.
1653 See the output of "ctags --list-kinds-full" for the complete list of
1655 the kinds.
1656 Its value is either one of the corresponding one-letter flags or a
1658 long-name flag. It is permitted (and is, in fact, the default) for the
1659 key portion of this field to be omitted. The optional behaviors are
1660 controlled with the --fields option as follows.
1661 $ ctags -o - kinds.c
1663 foo kinds.c /^int foo() {$/;" f typeref:typename:int
1664 $ ctags --fields=+k -o - kinds.c
1665 foo kinds.c /^int foo() {$/;" f typeref:typename:int
1666 $ ctags --fields=+K -o - kinds.c
1667 foo kinds.c /^int foo() {$/;" function typeref:typename:int
1668 $ ctags --fields=+z -o - kinds.c
1669 foo kinds.c /^int foo() {$/;" kind:f typeref:typename:int
1670 $ ctags --fields=+zK -o - kinds.c
1671 foo kinds.c /^int foo() {$/;" kind:function typeref:typename:int
1672 Roles
1674 Role is a newly introduced concept in Universal Ctags. Role is a con‐
1675 cept associated with reference tags, and is not implemented widely yet.
1676 As described previously in "Kinds", the kind field represents the type
1678 of language object specified with a tag, such as a function vs. a vari‐
1679 able. Specific kinds are defined for reference tags, such as the C++
1680 kind header for header file, or Java kind package for package state‐
1681 ments. For such reference kinds, a roles field can be added to distin‐
1682 guish the role of the reference kind. In other words, the kind field
1683 identifies the what of the language object, whereas the roles field
1684 identifies the how of a referenced language object. Roles are only used
1685 with specific kinds.
1686 For a definition tag, this field takes def as a value.
1688 For example, Baz is tagged as a reference tag with kind package and
1690 with role imported with the following code.
1691 package Bar;
1693 import Baz;
1694 class Foo {
1696 // ...
1697 }
1698 $ ctags --fields=+KEr -uo - roles.java
1700 Bar roles.java /^package Bar;$/;" package roles:def
1701 Foo roles.java /^class Foo {$/;" class roles:def
1702 $ ctags --fields=+EKr --extras=+r -uo - roles.java
1703 Bar roles.java /^package Bar;$/;" package roles:def
1704 Baz roles.java /^import Baz;$/;" package roles:imported extras:reference
1705 Foo roles.java /^class Foo {$/;" class roles:def
1706 --roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*] option specifies a
1708 list of kind-specific roles of tags to include in the output file for a
1709 particular language.
1710 Inquire the output of "ctags --list-roles" for the list of roles.
1712 Extras
1714 Generally, ctags tags only language objects appearing in source files,
1715 as is. In other words, a value for a name: field should be found on the
1716 source file associated with the name:. An extra type tag (extra) is for
1717 tagging a language object with a processed name, or for tagging some‐
1718 thing not associated with a language object. A typical extra tag is
1719 qualified, which tags a language object with a class-qualified or
1720 scope-qualified name.
1721 --extras-(<LANG>|all)=[+|-][<flags>|*] option specifies whether to in‐
1723 clude extra tag entries for certain kinds of information.
1724 Inquire the output of ctags --list-extras for the list of extras. The
1726 meaning of major extras is as follows (long-name flag/one-letter flag):
1727 anonymous/none
1729 Include an entry for the language object that has no name like
1730 lambda function. This extra has no one-letter flag and is en‐
1731 abled by default.
1732 The extra tag is useful as a placeholder to fill scope fields
1734 for language objects defined in a language object with no name.
1735 struct {
1737 double x, y;
1738 } p = { .x = 0.0, .y = 0.0 };
1739 'x' and 'y' are the members of a structure. When filling the
1741 scope fields for them, ctags has trouble because the struct
1742 where 'x' and 'y' belong to has no name. For overcoming the
1743 trouble, ctags generates an anonymous extra tag for the struct
1744 and fills the scope fields with the name of the extra tag.
1745 $ ctags --fields=-f -uo - input.c
1747 __anon9f26d2460108 input.c /^struct {$/;" s
1748 x input.c /^ double x, y;$/;" m struct:__anon9f26d2460108
1749 y input.c /^ double x, y;$/;" m struct:__anon9f26d2460108
1750 p input.c /^} p = { .x = 0.0, .y = 0.0 };$/;" v typeref:struct:__anon9f26d2460108
1751 The above tag output has __anon9f26d2460108 as an anonymous ex‐
1753 tra tag. The typeref field of 'p' also receives the benefit of
1754 it.
1755 fileScope/F
1757 Indicates whether tags scoped only for a single file (i.e. tags
1758 which cannot be seen outside of the file in which they are de‐
1759 fined, such as language objects with static modifier of C lan‐
1760 guage) should be included in the output. See also the -h option.
1761 This extra tag is enabled by default. Add --extras=-F option not
1763 to output tags scoped only for a single-file. This is the re‐
1764 placement for --file-scope option of Exuberant Ctags.
1765 static int f() {
1767 return 0;
1768 }
1769 int g() {
1770 return 0;
1771 }
1772 $ ctags -uo - filescope.c
1774 f filescope.c /^static int f() {$/;" f typeref:typename:int file:
1775 g filescope.c /^int g() {$/;" f typeref:typename:int
1776 $ ctags --extras=-F -uo - filescope.c
1777 g filescope.c /^int g() {$/;" f typeref:typename:int
1778 inputFile/f
1780 Include an entry for the base file name of every source file
1781 (e.g. example.c), which addresses the first line of the file.
1782 This flag is the replacement for --file-tags hidden option of
1783 Exuberant Ctags.
1784 If the end: field is enabled, the end line number of the file
1786 can be attached to the tag. (However, ctags omits the end: field
1787 if no newline is in the file like an empty file.)
1788 By default, ctags doesn't create the inputFile/f extra tag for
1790 the source file when ctags doesn't find a parser for it. En‐
1791 abling Unknown parser with --languages=+Unknown forces ctags to
1792 create the extra tags for any source files.
1793 The etags mode enables the Unknown parser implicitly.
1795 pseudo/p
1797 Include pseudo-tags. Enabled by default unless the tag file is
1798 written to standard output. See ctags-client-tools(7) about the
1799 detail of pseudo-tags.
1800 qualified/q
1802 Include an extra class-qualified or namespace-qualified tag en‐
1803 try for each tag which is a member of a class or a namespace.
1804 This may allow easier location of a specific tags when multiple
1806 occurrences of a tag name occur in the tag file. Note, however,
1807 that this could potentially more than double the size of the tag
1808 file.
1809 The actual form of the qualified tag depends upon the language
1811 from which the tag was derived (using a form that is most natu‐
1812 ral for how qualified calls are specified in the language). For
1813 C++ and Perl, it is in the form class::member; for Eiffel and
1814 Java, it is in the form class.member.
1815 Note: Using backslash characters as separators forming qualified
1817 name in PHP. However, in tags output of Universal Ctags, a back‐
1818 slash character in a name is escaped with a backslash character.
1819 See tags(5) about the escaping.
1820 The following example demonstrates the qualified extra tag.
1822 class point {
1824 double x;
1825 };
1826 For the above source file, ctags tags point and x by default.
1828 If the qualified extra is enabled from the command line (--ex‐
1829 tras=+q), then point.x is also tagged even though the string
1830 "point.x" is not in the source code.
1831 $ ctags --fields=+K -uo - qualified.java
1833 point qualified.java /^class point {$/;" class
1834 x qualified.java /^ double x;$/;" field class:point
1835 $ ctags --fields=+K --extras=+q -uo - qualified.java
1836 point qualified.java /^class point {$/;" class
1837 x qualified.java /^ double x;$/;" field class:point
1838 point.x qualified.java /^ double x;$/;" field class:point
1839 reference/r
1841 Include reference tags. See "TAG ENTRIES" about reference tags.
1842 The following example demonstrates the reference extra tag.
1844 #include <stdio.h>
1846 #include "utils.h"
1847 #define X
1848 #undef X
1849 The roles:system or roles:local fields will be added depending
1851 on whether the include file name begins with '<' or not.
1852 "#define X" emits a definition tag. On the other hand "#undef X"
1854 emits a reference tag.
1855 $ ctags --fields=+EKr -uo - inc.c
1857 X inc.c /^#define X$/;" macro file: roles:def extras:fileScope
1858 $ ctags --fields=+EKr --extras=+r -uo - inc.c
1859 stdio.h inc.c /^#include <stdio.h>/;" header roles:system extras:reference
1860 utils.h inc.c /^#include "utils.h"/;" header roles:local extras:reference
1861 X inc.c /^#define X$/;" macro file: roles:def extras:fileScope
1862 X inc.c /^#undef X$/;" macro file: roles:undef extras:fileScope,reference
1863 Language-specific fields and extras
1865 Exuberant Ctags has the concept of fields and extras. They are common
1866 between parsers of different languages. Universal Ctags extends this
1867 concept by providing language-specific fields and extras.
1868
1870 vi(1) will, by default, expect a tag file by the name tags in the cur‐
1871 rent directory. Once the tag file is built, the following commands ex‐
1872 ercise the tag indexing feature:
1873 vi -t tag
1875 Start vi and position the cursor at the file and line where tag
1876 is defined.
1877 :ta tag
1879 Find a tag.
1880 Ctrl-] Find the tag under the cursor.
1882 Ctrl-T Return to previous location before jump to tag (not widely im‐
1884 plemented).
1885
1887 emacs(1) will, by default, expect a tag file by the name TAGS in the
1888 current directory. Once the tag file is built, the following commands
1889 exercise the tag indexing feature:
1890 M-x visit-tags-table <RET> FILE <RET>
1892 Select the tag file, FILE, to use.
1893 M-. [TAG] <RET>
1895 Find the first definition of TAG. The default tag is the identi‐
1896 fier under the cursor.
1897 M-* Pop back to where you previously invoked M-..
1899 C-u M-.
1901 Find the next definition for the last tag.
1902 For more commands, see the Tags topic in the Emacs info document.
1904
1906 NEdit version 5.1 and later can handle the new extended tag file format
1907 (see --format).
1908 • To make NEdit use the tag file, select "File->Load Tags File".
1910 • To jump to the definition for a tag, highlight the word, then press
1912 Ctrl-D.
1913 NEdit 5.1 can read multiple tag files from different directories. Set‐
1915 ting the X resource nedit.tagFile to the name of a tag file instructs
1916 NEdit to automatically load that tag file at startup time.
1917
1919 Because ctags is neither a preprocessor nor a compiler, use of pre‐
1920 processor macros can fool ctags into either missing tags or improperly
1921 generating inappropriate tags. Although ctags has been designed to han‐
1922 dle certain common cases, this is the single biggest cause of reported
1923 problems. In particular, the use of preprocessor constructs which alter
1924 the textual syntax of C can fool ctags. You can work around many such
1925 problems by using the -I option.
1926 Note that since ctags generates patterns for locating tags (see the
1928 --excmd option), it is entirely possible that the wrong line may be
1929 found by your editor if there exists another source line which is iden‐
1930 tical to the line containing the tag. The following example demon‐
1931 strates this condition:
1932 int variable;
1934 /* ... */
1936 void foo(variable)
1937 int variable;
1938 {
1939 /* ... */
1940 }
1941 Depending upon which editor you use and where in the code you happen to
1943 be, it is possible that the search pattern may locate the local parame‐
1944 ter declaration before it finds the actual global variable definition,
1945 since the lines (and therefore their search patterns) are identical.
1946 This can be avoided by use of the --excmd=n option.
1948
1950 ctags has more options than ls(1).
1951 ctags assumes the input file is written in the correct grammar. Other‐
1953 wise output of ctags is undefined. In other words it has garbage in,
1954 garbage out (GIGO) feature.
1955 When parsing a C++ member function definition (e.g. className::func‐
1957 tion), ctags cannot determine whether the scope specifier is a class
1958 name or a namespace specifier and always lists it as a class name in
1959 the scope portion of the extension fields. Also, if a C++ function is
1960 defined outside of the class declaration (the usual case), the access
1961 specification (i.e. public, protected, or private) and implementation
1962 information (e.g. virtual, pure virtual) contained in the function dec‐
1963 laration are not known when the tag is generated for the function defi‐
1964 nition. It will, however be available for prototypes (e.g.
1965 --kinds-c++=+p).
1966 No qualified tags are generated for language objects inherited into a
1968 class.
1969
1971 TMPDIR On Unix-like hosts where mkstemp(3) is available, the value of
1972 this variable specifies the directory in which to place tempo‐
1973 rary files. This can be useful if the size of a temporary file
1974 becomes too large to fit on the partition holding the default
1975 temporary directory defined at compilation time.
1976 ctags creates temporary files only if either (1) an emacs-style
1978 tag file is being generated, (2) the tag file is being sent to
1979 standard output, or (3) the program was compiled to use an in‐
1980 ternal sort algorithm to sort the tag files instead of the
1981 sort(1) utility of the operating system. If the sort(1) utility
1982 of the operating system is being used, it will generally observe
1983 this variable also.
1984 Note that if ctags is setuid, the value of TMPDIR will be ig‐
1986 nored.
1987
1989 tags The default tag file created by ctags.
1990 TAGS The default tag file created by etags.
1992 $XDG_CONFIG_HOME/ctags/*.ctags, or $HOME/.config/ctags/*.ctags if
1994 $XDG_CONFIG_HOME is not defined (on other than MS Windows)
1995 $HOME/.ctags.d/*.ctags
1997 $HOMEDRIVE$HOMEPATH/ctags.d/*.ctags (on MS Windows only)
1999 .ctags.d/*.ctags
2001 ctags.d/*.ctags
2003 If any of these configuration files exist, each will be expected to
2004 contain a set of default options which are read in the order listed
2005 when ctags starts, but before any command line options are read.
2006 This makes it possible to set up personal or project-level defaults.
2007 It is possible to compile ctags to read an additional configuration
2009 file before any of those shown above, which will be indicated if the
2010 output produced by the --version option lists the custom-conf fea‐
2011 ture.
2012 Options appearing on the command line will override options speci‐
2014 fied in these files. Only options will be read from these files.
2015 Note that the option files are read in line-oriented mode in which
2017 spaces are significant (since shell quoting is not possible) but
2018 spaces at the beginning of a line are ignored. Each line of the file
2019 is read as one command line parameter (as if it were quoted with
2020 single quotes). Therefore, use new lines to indicate separate com‐
2021 mand-line arguments.
2022 A line starting with '#' is treated as a comment.
2024 *.ctags files in a directory are loaded in alphabetical order.
2026
2028 See ctags-optlib(7) for defining (or extending) a parser in a configu‐
2029 ration file.
2030 See tags(5) for the format of tag files.
2032 See ctags-incompatibilities(7) about known incompatible changes with
2034 Exuberant Ctags.
2035 See ctags-client-tools(7) if you are interested in writing a tool for
2037 processing tags files.
2038 See ctags-lang-python(7) about python input specific notes.
2040 See readtags(1) about a client tool for binary searching a name in a
2042 sorted tags file.
2043 The official Universal Ctags web site at: https://ctags.io/
2045 Also ex(1), vi(1), elvis(1), or, better yet, vim(1), the official edi‐
2047 tor of ctags. For more information on vim(1), see the Vim web site at:
2048 https://www.vim.org/
2049
2051 Universal Ctags project https://ctags.io/
2052 Darren Hiebert <dhiebert@users.sourceforge.net>
2054 http://DarrenHiebert.com/
2055
2057 "Think ye at all times of rendering some service to every member of the
2058 human race."
2059 "All effort and exertion put forth by man from the fullness of his
2061 heart is worship, if it is prompted by the highest motives and the will
2062 to do service to humanity."
2063 -- From the Baha'i Writings
2065
2067 This version of ctags (Universal Ctags) derived from the repository,
2068 known as fishman-ctags, started by Reza Jelveh.
2069 The fishman-ctags was derived from Exuberant Ctags.
2071 Some parsers are taken from tagmanager of the Geany (‐
2073 https://www.geany.org/) project.
2074 Exuberant Ctags was originally derived from and inspired by the ctags
2076 program by Steve Kirkendall <kirkenda@cs.pdx.edu> that comes with the
2077 Elvis vi clone (though virtually none of the original code remains).
2078 Credit is also due Bram Moolenaar <Bram@vim.org>, the author of vim,
2080 who has devoted so much of his time and energy both to developing the
2081 editor as a service to others, and to helping the orphans of Uganda.
2082 The section entitled "HOW TO USE WITH GNU EMACS" was shamelessly stolen
2084 from the info page for GNU etags.
20855.9.0 CTAGS(1)