1CTAGS(1)                        Universal Ctags                       CTAGS(1)
2
3
4

NAME

6       ctags - Generate tag files for source code
7

SYNOPSIS

9       ctags [<options>] [<source_file(s)>]
10       etags [<options>] [<source_file(s)>]
11
12

DESCRIPTION

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
22       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
26       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
32       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
38       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
43       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
48       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

COMMAND LINE INTERFACE

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
59       Note that spaces separating the single-letter options from their param‐
60       eters are optional.
61
62       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
69       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
72       <options> must precede  the  <source_file(s)>  following  the  standard
73       POSIX convention.
74
75       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
79   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
85       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
91          --kinds-C=+pLl
92          --kinds-C=+{prototype}{label}{local}
93          --kinds-C=+{prototype}L{local}
94
95       Note that braces may be meta  characters  in  your  shell.  Put  single
96       quotes in such case.
97
98       --list-...  options  shows  one-letter  flags  and associated long-name
99       flags.
100
101   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
107       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
113       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
117       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

OPTIONS

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
126       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
130   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
140              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
151              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
156              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
162              See also the description for --exclude-exception= option.
163
164       --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
169              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
173       --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
184       --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
190              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
196              This option is quite esoteric and is empty by default.
197
198       --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
203       --maxdepth=<N>
204              Limits the depth of directory recursion enabled with  the  --re‐
205              curse (-R) option.
206
207       --recurse[=(yes|no)]
208              Recurse  into  directories  encountered  in the list of supplied
209              files.
210
211              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
219              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
223       -R     Equivalent to --recurse.
224
225       -L <file>
226              Read from <file> a list of file names for which tags  should  be
227              generated.
228
229              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
235              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
241       --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
246       -a     Equivalent to --append.
247
248       -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
254              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
265              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
268       -o <tagfile>
269              Equivalent to "-f tagfile".
270
271   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
280       --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
287       -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
293       -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
301              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
307       --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
317       -u     Equivalent to --sort=no (i.e. "unsorted").
318
319       --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
325       --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
330       --input-encoding-<LANG>=<encoding>
331              Specifies  a  specific input <encoding> for <LANG>. It overrides
332              the global default value given with --input-encoding.
333
334       --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
339              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
343   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
352              In  addition, the special value auto indicates that the language
353              should be automatically  selected  (which  effectively  disables
354              this option).
355
356       --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
361              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
368              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
374              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
381              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
385              Note --languages= option works cumulative way; the option can be
386              specified with different arguments multiple times in  a  command
387              line.
388
389       --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
394              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
398              To restore the default language aliases, specify default.
399
400              Using all for <LANG> has meaning in following two cases:
401
402              --alias-all=
403                     This clears aliases setting of all languages.
404
405              --alias-all=default
406                     This  restores the default languages aliases for all lan‐
407                     guages.
408
409       --guess-language-eagerly
410              Looks into the file  contents  for  heuristically  guessing  the
411              proper language parser.  See "Determining file language".
412
413       -G     Equivalent to --guess-language-eagerly.
414
415       --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
424              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
435              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
439              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
452              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
459              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
464       --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
468              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
475              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
481              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
486   Tags File Contents Options
487       See "TAG ENTRIES" about fields, kinds, roles, and extras.
488
489       --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
493              The  valid  values for type (either the entire word or the first
494              letter is accepted) are:
495
496              number Use only line numbers in the tag file for locating  tags.
497                     This has four advantages:
498
499                     1. Significantly  reduces  the  size of the resulting tag
500                        file.
501
502                     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
507                     3. Eliminates  finding identical matching, but incorrect,
508                        source lines (see "BUGS").
509
510                     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
516                     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
526                     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
530              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
537              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
544                     This  was  the  default  format generated by the original
545                     ctags and is, therefore, retained as the default for this
546                     option.
547
548              combine
549                     Concatenate  the line number and pattern with a semicolon
550                     in between.
551
552       -n     Equivalent to --excmd=number.
553
554       -N     Equivalent to --excmd=pattern.
555
556       --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
561              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
569              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
575       --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
581              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
587              Check  the output of the --list-extras=<LANG> option for the ex‐
588              tras of specific language <LANG>.
589
590       --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
597              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
605              This option is ignored if the option --format=1 (legacy tag file
606              format) has been specified.
607
608              Use  --fields-<LANG>=  option  for controlling language-specific
609              fields.
610
611       --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
617              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
623              See the description of --fields=[+|-][<flags>|*] about <flags>.
624
625              Use   --fields=   option  for  controlling  language-independent
626              fields.
627
628       --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
634              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
640              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
646              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
652              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
657              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
662       --pattern-length-limit=<N>
663              Truncate  patterns  of tag entries after <N> characters. Disable
664              by setting to 0 (default is 96).
665
666              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
671              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
685       --pseudo-tags=[+|-](<pseudo-tag>|*)
686              Enable/disable  emitting  pseudo-tag named <pseudo-tag>.  If '*'
687              is given, enable/disable emitting all pseudo-tags.
688
689       --put-field-prefix
690              Put UCTAGS as prefix for the name of fields newly introduced  in
691              Universal Ctags.
692
693              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
697              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
702                 $ 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
707              In the above example, the prefix is put to end  field  which  is
708              newly introduced in Universal Ctags.
709
710       --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
717              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
722              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
729              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
733       --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
738              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
743              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
748              always indicates the recorded file paths should be relative even
749                     if source file names are passed in with absolute paths.
750
751              never  indicates the recorded file paths should be absolute even
752                     if source file names are passed in with relative paths.
753
754       --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
760              This option is available on MS Windows only.
761
762       -B     Use backward searching patterns (e.g.  ?pattern?).  [Ignored  in
763              etags mode]
764
765       -F     Use  forward searching patterns (e.g. /pattern/) (default). [Ig‐
766              nored in etags mode]
767
768   Option File Options
769       --options=<pathname>
770              Read additional options from file or directory.
771
772              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
776              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
780              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
785       --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
789       --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
793   optlib Options
794       See ctags-optlib(7) for details of each option.
795
796       --kinddef-<LANG>=<letter>,<name>,<description>
797              Define   a  kind  for  <LANG>.   Don't  be  confused  this  with
798              --kinds-<LANG>.
799
800       --langdef=<name>
801              Defines a new user-defined language, <name>, to be  parsed  with
802              regular expressions.
803
804       --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
809       --regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]
810              Define  single-line regular expression for locating tags in spe‐
811              cific language.
812
813   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
821              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
826       --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
833              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
843              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
848       -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
856       -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
862              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
872              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
877              The  default list is .h.H.hh.hpp.hxx.h++.inc.def. To restore the
878              default list, specify "-h default".
879
880              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
885       -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
893              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
898              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
904              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
910              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
915              Multiple -I options may be supplied. To clear the list of ignore
916              identifiers, supply a single dash ('-') for <identifier-list>.
917
918              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
925                 int foo ARGDECL4(void *, ptr, long int, nbytes)
926
927              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
932                 /* creates an RCS version string in module */
933                 MODULE_VERSION("$Revision$")
934
935              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
944                 CLASS Example {
945                         // your content here
946                 };
947
948              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
956       --param-<LANG>:<name>=<argument>
957              Set a <LANG> specific parameter, a  parameter  specific  to  the
958              <LANG>.
959
960              Available parameters can be listed with --list-params.
961
962   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
969       --list-excludes
970              Lists the current exclusion patterns used to exclude files.
971
972       --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
978              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
983              The meaning of columns in output are as follows:
984
985              LETTER One-letter flag.  '-'  means  the  extra  does  not  have
986                     one-letter flag.
987
988              NAME   Long-name flag. The long-name is used in extras field.
989
990              ENABLED
991                     Whether the extra is enabled or not. It takes yes or no.
992
993              LANGUAGE
994                     The  name  of language if the extra is owned by a parser.
995                     NONE means the extra is common in parsers.
996
997              DESCRIPTION
998                     Human readable description for the extra.
999
1000       --list-features
1001              Lists the compiled features.
1002
1003       --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
1009              The meaning of columns are as follows:
1010
1011              LETTER One-letter  flag.  '-'  means  the  field  does  not have
1012                     one-letter flag.
1013
1014              NAME   Long-name of field.
1015
1016              ENABLED
1017                     Whether the field is enabled or not. It takes yes or no.
1018
1019              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
1024              JSTYPE JSON type used in printing the value of field when --out‐
1025                     put-format=json is specified. See ctags-client-tools(7).
1026
1027              FIXED  Whether this field can be disabled or not in tags output.
1028
1029                     Some fields are printed always in tags output.  They have
1030                     yes as the value for this column.
1031
1032                     Unlike the tag output mode, JSON output mode allows  dis‐
1033                     abling any fields.
1034
1035              OP     How this field can be accessed from optscript code.  This
1036                     field is for Universal Ctags developers.
1037
1038              DESCRIPTION
1039                     Human readable description for the field.
1040
1041       --list-kinds[=(<language>|all)]
1042              Subset of --list-kinds-full.  This  option  is  kept  for  back‐
1043              ward-compatibility with Exuberant Ctags.
1044
1045              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
1052              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
1056              This   option   does   not   work    with    --machinable    nor
1057              --with-list-header.
1058
1059       --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
1065              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
1070              The meaning of columns are as follows:
1071
1072              LANGUAGE
1073                     The name of language having the kind.
1074
1075              LETTER One-letter flag. This must be unique in a language.
1076
1077              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
1085              ENABLED
1086                     Whether the kind is enabled or not. It takes yes or no.
1087
1088              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
1094              NROLES The number of roles this kind has. See also "Roles".
1095
1096              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
1104                     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
1112                        $ 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
1121                     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
1126              DESCRIPTION
1127                     Human readable description for the kind.
1128
1129       --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
1135              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
1139              --machinable and --with-list-header options are ignored if  they
1140              are specified with this option.
1141
1142       --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
1148       --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
1154       --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
1160              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
1164              This   option   does   not   work    with    --machinable    nor
1165              --with-list-header.
1166
1167       --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
1171       --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
1176       --list-pseudo-tags
1177              Output list of pseudo-tags.
1178
1179       --list-regex-flags
1180              Lists the flags that can be used in --regex-<LANG> option.   See
1181              ctags-optlib(7).
1182
1183       --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
1188              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
1194              The meaning of columns are as follows:
1195
1196              LANGUAGE
1197                     The name of language having the role.
1198
1199              KIND(L/N)
1200                     The one-letter flag and the long-name flag of kind having
1201                     the role.
1202
1203              NAME   The long-name flag of the role.
1204
1205              ENABLED
1206                     Whether the kind is enabled or not. It takes yes or no.
1207
1208              DESCRIPTION
1209                     Human readable description for the role.
1210
1211       --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
1216       --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
1221       --with-list-header[=(yes|no)]
1222              Print headers describing columns in --list- option output.   See
1223              also "List options".
1224
1225   Miscellaneous Options
1226       --help Prints to standard output a detailed usage description, and then
1227              exits.
1228
1229       -?     Equivalent to --help.
1230
1231       --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
1237       --license
1238              Prints a summary of the software license to standard output, and
1239              then exits.
1240
1241       --print-language
1242              Just prints the language parsers for specified source files, and
1243              then exits.
1244
1245       --quiet[=(yes|no)]
1246              Write fewer messages (default is no).
1247
1248       --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
1253              The  extra  value  prints parser specific statistics for parsers
1254              gathering such information.
1255
1256       --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
1266       -V     Equivalent to --verbose.
1267
1268       --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
1273   Obsoleted Options
1274       These options are kept for backward-compatibility with Exuberant Ctags.
1275
1276       -w     This  option is silently ignored for backward-compatibility with
1277              the ctags of SVR4 Unix.
1278
1279       --file-scope[=(yes|no)]
1280              This  options  is  removed.   Use   --extras=[+|-]F   or   --ex‐
1281              tras=[+|-]{fileScope} instead.
1282
1283       --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
1288       --<LANG>-kinds=[+|-](<kinds>|*)
1289              This option is obsolete. Use --kinds-<LANG>=... instead.
1290

OPERATIONAL DETAILS

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
1296       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
1302   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
1308       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
1316          #ifdef TWO_ALTERNATIVES
1317          struct {
1318          #else
1319          union {
1320          #endif
1321                  short a;
1322                  long b;
1323          }
1324
1325       Both branches cannot be followed, or braces become unbalanced and ctags
1326       would be unable to make sense of the syntax.
1327
1328       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
1336       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
1340          extern void foo __ARGS((int one, char two));
1341
1342       Any  name  immediately preceding the '((' will be automatically ignored
1343       and the previous name will be used.
1344
1345       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
1351       After creating or appending to the tag file, it is sorted  by  the  tag
1352       name, removing identical tag lines.
1353
1354   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
1362       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
1366       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
1372       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
1381   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
1385       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
1390       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
1395              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
1401              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
1405              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
1410       zsh autoload tag testing
1411              If the first line starts with #compdef or #autoload,  ctags  re‐
1412              gards the line as "zsh".
1413
1414       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
1420              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
1424                 -*- mode: MODE -*-
1425
1426              or
1427
1428                 -*- MODE -*-
1429
1430       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
1435              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
1439                 Local Variables:
1440                 ...
1441                 mode: MODE
1442                 ...
1443                 End:
1444
1445              3000 characters are sought from the end of file to find the pat‐
1446              tern.
1447
1448       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
1454                 filetype=TYPE
1455
1456              or
1457
1458                 ft=TYPE
1459
1460       PHP marker testing
1461              If the first line is started with <?php, ctags regards the  line
1462              as "php".
1463
1464       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
1470       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
1473       Examples:
1474
1475          $ ctags --print-language config.h.in input.m input.unknown
1476          config.h.in: C++
1477          input.m: MatLab
1478          input.unknown: NONE
1479
1480       NONE means that ctags does not select any parser for the file.
1481

TAG FILE FORMAT

1483       This section describes the tag file format briefly.   See  tags(5)  and
1484       ctags-client-tools(7) for more details.
1485
1486       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
1490          <tag_name><TAB><file_name><TAB><ex_cmd>;"<TAB><extension_fields>
1491
1492       The fields and separators of these lines are specified as follows:
1493
1494          1. <tag_name>: tag name
1495
1496          2. <TAB>: single tab character
1497
1498          3. <file_name>: name of the file in which the object associated with
1499             the tag is located
1500
1501          4. <TAB>: single tab character
1502
1503          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
1507          6. ;"<TAB><extension_fields>: a set  of  extension  fields.  See  "‐
1508             Extension fields" for more details.
1509
1510             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
1515       A few special tags, called pseudo tags, are written into the  tag  file
1516       for internal purposes.
1517
1518          !_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
1522       --pseudo-tags=[+|-](<pseudo-tag>|*) option enables or disables emitting
1523       pseudo-tags.
1524
1525       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
1529       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
1534       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

TAG ENTRIES

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
1546       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
1554   Extension fields
1555       A tag can record various information, called extension fields.
1556
1557       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
1561       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
1568       --fields=[+|-][<flags>|*]   and  --fields-(<LANG>|all)=[+|-][<flags>|*]
1569       options specifies which available extension fields are to  be  included
1570       in the tag entries.
1571
1572       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
1576       access/a
1577              Indicates  the  visibility  of this class member, where value is
1578              specific to the language.
1579
1580       end/e  Indicates the line number of the end lines of the  language  ob‐
1581              ject.
1582
1583       extras/E
1584              Extra tag type information. See "Extras" for details.
1585
1586       file/f Indicates that the tag has file-limited visibility. This key has
1587              no corresponding value. Enabled by default.
1588
1589       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
1595       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
1599       input/F
1600              The name of source file where name is defined or referenced.
1601
1602       k      Kind of tag as one-letter. Enabled by default.  This  field  has
1603              no long-name.  See also kind/z flag.
1604
1605       K      Kind  of  tag  as  long-name.  This field has no long-name.  See
1606              also kind/z flag.
1607
1608       kind/z Include the kind: key in kind field.  See also k and K flags.
1609
1610       language/l
1611              Language of source file containing tag
1612
1613       line/n The line number where name is defined or referenced in input.
1614
1615       name/N The name of language objects.
1616
1617       pattern/P
1618              Can be used to search the name in input
1619
1620       roles/r
1621              Roles assigned to the tag. See "Roles" for more details.
1622
1623       s      Scope of tag definition. Enabled by default.  This field has  no
1624              long-name.  See also scope/Z flag.
1625
1626       scope/Z
1627              Prepend the scope: key to scope (s) field.  See also s flag.
1628
1629       scopeKind/p
1630              Kind of scope as long-name
1631
1632       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
1640       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
1644   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
1650       --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
1654       See the output of "ctags --list-kinds-full" for the  complete  list  of
1655       the kinds.
1656
1657       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
1662          $ 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
1673   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
1677       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
1687       For a definition tag, this field takes def as a value.
1688
1689       For  example,  Baz  is  tagged as a reference tag with kind package and
1690       with role imported with the following code.
1691
1692          package Bar;
1693          import Baz;
1694
1695          class Foo {
1696                          // ...
1697          }
1698
1699          $ 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
1707       --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
1711       Inquire the output of "ctags --list-roles" for the list of roles.
1712
1713   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
1722       --extras-(<LANG>|all)=[+|-][<flags>|*] option specifies whether to  in‐
1723       clude extra tag entries for certain kinds of information.
1724
1725       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
1728       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
1733              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
1736                 struct {
1737                         double x, y;
1738                 } p = { .x = 0.0, .y = 0.0 };
1739
1740              '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
1746                 $ 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
1752              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
1756       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
1762              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
1766                 static int f() {
1767                         return 0;
1768                 }
1769                 int g() {
1770                         return 0;
1771                 }
1772
1773                 $ 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
1779       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
1785              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
1789              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
1794              The etags mode enables the Unknown parser implicitly.
1795
1796       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
1801       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
1805              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
1810              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
1816              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
1821              The following example demonstrates the qualified extra tag.
1822
1823                 class point {
1824                         double x;
1825                 };
1826
1827              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
1832                 $ 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
1840       reference/r
1841              Include reference tags. See "TAG ENTRIES" about reference tags.
1842
1843              The following example demonstrates the reference extra tag.
1844
1845                 #include <stdio.h>
1846                 #include "utils.h"
1847                 #define X
1848                 #undef X
1849
1850              The roles:system or roles:local fields will be  added  depending
1851              on whether the include file name begins with '<' or not.
1852
1853              "#define X" emits a definition tag. On the other hand "#undef X"
1854              emits a reference tag.
1855
1856                 $ 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
1864   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

HOW TO USE WITH VI

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
1874       vi -t tag
1875              Start vi and position the cursor at the file and line where  tag
1876              is defined.
1877
1878       :ta tag
1879              Find a tag.
1880
1881       Ctrl-] Find the tag under the cursor.
1882
1883       Ctrl-T Return  to  previous location before jump to tag (not widely im‐
1884              plemented).
1885

HOW TO USE WITH GNU EMACS

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
1891       M-x visit-tags-table <RET> FILE <RET>
1892              Select the tag file, FILE, to use.
1893
1894       M-. [TAG] <RET>
1895              Find the first definition of TAG. The default tag is the identi‐
1896              fier under the cursor.
1897
1898       M-*    Pop back to where you previously invoked M-..
1899
1900       C-u M-.
1901              Find the next definition for the last tag.
1902
1903       For more commands, see the Tags topic in the Emacs info document.
1904

HOW TO USE WITH NEDIT

1906       NEdit version 5.1 and later can handle the new extended tag file format
1907       (see --format).
1908
1909       • To make NEdit use the tag file, select "File->Load Tags File".
1910
1911       • To jump to the definition for a tag, highlight the word,  then  press
1912         Ctrl-D.
1913
1914       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

CAVEATS

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
1927       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
1933          int variable;
1934
1935          /* ... */
1936          void foo(variable)
1937          int variable;
1938          {
1939                  /* ... */
1940          }
1941
1942       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
1947       This can be avoided by use of the --excmd=n option.
1948

BUGS

1950       ctags has more options than ls(1).
1951
1952       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
1956       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
1967       No  qualified  tags are generated for language objects inherited into a
1968       class.
1969

ENVIRONMENT VARIABLES

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
1977              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
1985              Note that if ctags is setuid, the value of TMPDIR  will  be  ig‐
1986              nored.
1987

FILES

1989       tags   The default tag file created by ctags.
1990
1991       TAGS   The default tag file created by etags.
1992
1993       $XDG_CONFIG_HOME/ctags/*.ctags,   or   $HOME/.config/ctags/*.ctags   if
1994       $XDG_CONFIG_HOME is not defined (on other than MS Windows)
1995
1996       $HOME/.ctags.d/*.ctags
1997
1998       $HOMEDRIVE$HOMEPATH/ctags.d/*.ctags (on MS Windows only)
1999
2000       .ctags.d/*.ctags
2001
2002       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
2008          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
2013          Options appearing on the command line will override  options  speci‐
2014          fied in these files. Only options will be read from these files.
2015
2016          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
2023          A line starting with '#' is treated as a comment.
2024
2025          *.ctags files in a directory are loaded in alphabetical order.
2026

SEE ALSO

2028       See ctags-optlib(7) for defining (or extending) a parser in a  configu‐
2029       ration file.
2030
2031       See tags(5) for the format of tag files.
2032
2033       See  ctags-incompatibilities(7)  about  known incompatible changes with
2034       Exuberant Ctags.
2035
2036       See ctags-client-tools(7) if you are interested in writing a  tool  for
2037       processing tags files.
2038
2039       See ctags-lang-python(7) about python input specific notes.
2040
2041       See  readtags(1)  about  a client tool for binary searching a name in a
2042       sorted tags file.
2043
2044       The official Universal Ctags web site at: https://ctags.io/
2045
2046       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

AUTHOR

2051       Universal Ctags project https://ctags.io/
2052
2053       Darren             Hiebert             <dhiebert@users.sourceforge.net>
2054       http://DarrenHiebert.com/
2055

MOTIVATION

2057       "Think ye at all times of rendering some service to every member of the
2058       human race."
2059
2060       "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
2064       -- From the Baha'i Writings
2065

CREDITS

2067       This version of ctags (Universal Ctags) derived  from  the  repository,
2068       known as fishman-ctags, started by Reza Jelveh.
2069
2070       The fishman-ctags was derived from Exuberant Ctags.
2071
2072       Some   parsers   are   taken   from   tagmanager   of   the   Geany  (‐
2073       https://www.geany.org/) project.
2074
2075       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
2079       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
2083       The section entitled "HOW TO USE WITH GNU EMACS" was shamelessly stolen
2084       from the info page for GNU etags.
2085
2086
2087
2088
20895.9.0                                                                 CTAGS(1)
Impressum