.. _ctags(1):

==============================================================

@CTAGS_NAME_EXECUTABLE@

==============================================================

--------------------------------------------------------------

Generate tag files for source code

--------------------------------------------------------------

:Version: @VERSION@

:Manual group: Universal Ctags

:Manual section: 1

SYNOPSIS

--------

| **@CTAGS_NAME_EXECUTABLE@** [<options>] [<source_file(s)>]

| **@ETAGS_NAME_EXECUTABLE@** [<options>] [<source_file(s)>]

DESCRIPTION

-----------

The *@CTAGS_NAME_EXECUTABLE@* and *@ETAGS_NAME_EXECUTABLE@* (see ``-e`` option) programs

(hereinafter collectively referred to as @CTAGS_NAME_EXECUTABLE@,

except where distinguished) generate an index (or "tag") file for a

variety of *language objects* found in *source file(s)*. This tag file allows

these items to be quickly and easily located by a text editor or other

utilities (*client tools*). A *tag* signifies a language object for which an index entry is

available (or, alternatively, the index entry created for that object).

Alternatively, @CTAGS_NAME_EXECUTABLE@ can generate a cross reference

file which lists, in human readable form, information about the various

language objects found in a set of source files.

Tag index files are supported by numerous editors, which allow the user to

locate the object associated with a name appearing in a source file and

jump to the file and line which defines the name. See the manual of your

favorite editor about utilizing @CTAGS_NAME_EXECUTABLE@ command and

the tag index files in the editor.

@CTAGS_NAME_EXECUTABLE@ is capable of generating different *kinds* of tags

for each of many different *languages*. For a complete list of supported

languages, the names by which they are recognized, and the kinds of tags

which are generated for each, see the ``--list-languages`` and ``--list-kinds-full``

options.

This man page describes *Universal Ctags*, an implementation of ctags

derived from *Exuberant Ctags*. The major incompatible changes between

Universal Ctags and Exuberant Ctags are enumerated in

ctags-incompatibilities(7).

One of the advantages of Exuberant Ctags is that it allows a user to

define a new parser from the command line. Extending this capability is one

of the major features of Universal Ctags. ctags-optlib(7)

describes how the capability is extended.

Newly introduced experimental features are not explained here. If you

are interested in such features and @CTAGS_NAME_EXECUTABLE@ internals,

visit https://docs.ctags.io/.

COMMAND LINE INTERFACE

----------------------

Despite the wealth of available options, defaults are set so that

@CTAGS_NAME_EXECUTABLE@ is most commonly executed without any options (e.g.

"``@CTAGS_NAME_EXECUTABLE@ *``", or "``@CTAGS_NAME_EXECUTABLE@ -R``"), which will

create a tag file in the current directory for all recognized source

files. The options described below are provided merely to allow custom

tailoring to meet special needs.

Note that spaces separating the single-letter options from their parameters

are optional.

Note also that the boolean parameters to the long form options (those

beginning with ``--`` and that take a ``[=(yes|no)]`` parameter) may be omitted,

in which case ``=yes`` is implied. (e.g. ``--sort`` is equivalent to ``--sort=yes``).

Note further that ``=1``, ``=on``, and ``=true`` are considered synonyms for ``=yes``,

and that ``=0``, ``=off``, and ``=false`` are considered synonyms for ``=no``.

Some options are either ignored or useful only when used while running in

etags mode (see ``-e`` option). Such options will be noted.

*<options>* must precede the *<source_file(s)>* following the standard POSIX

convention.

Options taking language names will accept those names in either upper or

lower case. See the ``--list-languages`` option for a complete list of the

built-in language names.

Letters and names

~~~~~~~~~~~~~~~~~

Some options take one-letter flags as parameters (e.g. ``--kinds-<LANG>`` option).

Specifying just letters help a user create a complicated command line

quickly. However, a command line including sequences of one-letter flags

becomes difficult to understand.

Universal Ctags accepts long-name flags in

addition to such one-letter flags. The long-name and one-letter flags can be mixed in an

option parameter by surrounding each long-name by braces. Thus, for an

example, the following three notations for ``--kinds-C`` option have

the same meaning::

--kinds-C=+pLl

--kinds-C=+{prototype}{label}{local}

--kinds-C=+{prototype}L{local}

Note that braces may be meta characters in your shell. Put

single quotes in such case.

``--list-...`` options shows one-letter flags and associated long-name flags.

List options

~~~~~~~~~~~~

Universal Ctags introduces many ``--list-...`` options that provide

the internal data of Universal Ctags (See "`Listing Options`_"). Both users and client tools may

use the data. ``--with-list-header`` and ``--machinable`` options

adjust the output of the most of ``--list-...`` options.

The default setting (``--with-list-header=yes`` and ``--machinable=no``)

is for using interactively from a terminal. The header that explains

the meaning of columns is simply added to the output, and each column is

aligned in all lines. The header line starts with a hash ('``#``') character.

For scripting in a client tool, ``--with-list-header=no`` and

``--machinable=yes`` may be useful. The header is not added to the

output, and each column is separated by tab characters.

Note the order of columns will change in the future release.

However, labels in the header will not change. So by scanning

the header, a client tool can find the index for the target

column.

.. options that should be explained and revised here

``--list-features`` (done)

``--machinable`` (done)

``--with-list-header`` (done)

OPTIONS

------------

@CTAGS_NAME_EXECUTABLE@ has more options than listed here.

Options starting with an underscore character, such as ``--_echo=<msg>``,

are not listed here. They are experimental or for debugging purpose.

Notation: ``<foo>`` is for a variable string ``foo``, ``[ ... ]`` for optional,

``|`` for selection, and ``( ... )`` for grouping. For example

``--foo[=(yes|no)]'' means ``--foo``, ``-foo=yes``, or ``-foo=no``.

.. _option_input_output_file:

Input/Output File Options

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``--exclude=<pattern>``

Add *<pattern>* to a list of excluded files and directories. This option may

be specified as many times as desired. For each file name considered

by @CTAGS_NAME_EXECUTABLE@, each pattern specified using this option

will be compared against both the complete path (e.g.

``some/path/base.ext``) and the base name (e.g. ``base.ext``) of the file, thus

allowing patterns which match a given file name irrespective of its

path, or match only a specific path.

If appropriate support is available

from the runtime library of your C compiler, then pattern may

contain the usual shell wildcards (not regular expressions) common on

Unix (be sure to quote the option parameter to protect the wildcards from

being expanded by the shell before being passed to @CTAGS_NAME_EXECUTABLE@;

also be aware that wildcards can match the slash character, '``/``').

You can determine if shell wildcards are available on your platform by

examining the output of the ``--list-features`` option, which will include

``wildcards`` in the compiled feature list; otherwise, pattern is matched

against file names using a simple textual comparison.

If *<pattern>* begins with the character '``@``', then the rest of the string

is interpreted as a file name from which to read exclusion patterns,

one per line. If pattern is empty, the list of excluded patterns is

cleared.

Note that at program startup, the default exclude list contains names of

common hidden and system files, patterns for binary files, and directories

for which it is generally not desirable to descend while processing the

``--recurse`` option. To see the list of built-in exclude patterns, use

``--list-excludes``.

See also the description for ``--exclude-exception=`` option.

``--exclude-exception=<pattern>``

Add *<pattern>* to a list of included files and directories. The pattern

affects the files and directories that are excluded by the pattern

specified with ``--exclude=`` option.

For an example, you want @CTAGS_NAME_EXECUTABLE@ to ignore all files

under ``foo`` directory except ``foo/main.c``, use the following command

line: ``--exclude=foo/* --exclude-exception=foo/main.c``.

``--filter[=(yes|no)]``

Makes @CTAGS_NAME_EXECUTABLE@ behave as a filter, reading source

file names from standard input and printing their tags to standard

output on a file-by-file basis. If ``--sort`` is enabled, tags are sorted

only within the source file in which they are defined. File names are

read from standard input in line-oriented input mode (see note for ``-L``

option) and only after file names listed on the command line or from

any file supplied using the ``-L`` option. When this option is enabled,

the options ``-f``, ``-o``, and ``--totals`` are ignored. This option is quite

esoteric and is disabled by default.

``--filter-terminator=<string>``

Specifies a *<string>* to print to standard output following the tags for

each file name parsed when the ``--filter`` option is enabled. This may

permit an application reading the output of @CTAGS_NAME_EXECUTABLE@

to determine when the output for each file is finished.

Note that if the

file name read is a directory and ``--recurse`` is enabled, this string will

be printed only once at the end of all tags found for by descending

the directory. This string will always be separated from the last tag

line for the file by its terminating newline.

This option is quite esoteric and is empty by default.

``--links[=(yes|no)]``

Indicates whether symbolic links (if supported) should be followed.

When disabled, symbolic links are ignored. This option is on by default.

``--maxdepth=<N>``

Limits the depth of directory recursion enabled with the ``--recurse``

(``-R``) option.

``--recurse[=(yes|no)]``

Recurse into directories encountered in the list of supplied files.

If the list of supplied files is empty and no file list is specified with

the ``-L`` option, then the current directory (i.e. '``.``') is assumed.

Symbolic links are followed by default (See ``--links`` option). If you don't like these behaviors, either

explicitly specify the files or pipe the output of ``find(1)`` into

"``@CTAGS_NAME_EXECUTABLE@ -L -``" instead. See, also, the ``--exclude`` and

``--maxdepth`` to limit recursion.

Note: This option is not supported on

all platforms at present. It is available if the output of the ``--help``

option includes this option.

.. TODO(code): --list-features option should support this.

``-R``

Equivalent to ``--recurse``.

``-L <file>``

Read from *<file>* a list of file names for which tags should be generated.

If file is specified as '``-``', then file names are read from standard

input. File names read using this option are processed following file

names appearing on the command line. Options are also accepted in this

input. If this option is specified more than once, only the last will

apply.

Note: file is read in line-oriented mode, where a new line is

the only delimiter and non-trailing white space is considered significant,

in order that file names containing spaces may be supplied

(however, trailing white space is stripped from lines); this can affect

how options are parsed if included in the input.

``--append[=(yes|no)]``

Indicates whether tags generated from the specified files should be

appended to those already present in the tag file or should replace them.

This option is ``no`` by default.

``-a``

Equivalent to ``--append``.

``-f <tagfile>``

Use the name specified by *<tagfile>* for the tag file (default is "``tags``",

or "``TAGS``" when running in etags mode). If *<tagfile>* is specified as '``-``',

then the tags are written to standard output instead.

@CTAGS_NAME_EXECUTABLE@

will stubbornly refuse to take orders if tagfile exists and

its first line contains something other than a valid tags line. This

will save your neck if you mistakenly type "``@CTAGS_NAME_EXECUTABLE@ -f

*.c``", which would otherwise overwrite your first C file with the tags

generated by the rest! It will also refuse to accept a multi-character

file name which begins with a '``-``' (dash) character, since this most

likely means that you left out the tag file name and this option tried to

grab the next option as the file name. If you really want to name your

output tag file ``-ugly``, specify it as "``-f ./-ugly``".

This option must

appear before the first file name. If this option is specified more

than once, only the last will apply.

``-o <tagfile>``

Equivalent to "``-f tagfile``".

.. _option_output_format:

Output Format Options

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``--format=(1|2)``

Change the format of the output tag file. Currently the only valid

values for level are 1 or 2. Level 1 specifies the original tag file

format and level 2 specifies a new extended format containing extension

fields (but in a manner which retains backward-compatibility with

original ``vi(1)`` implementations). The default level is 2.

[Ignored in etags mode]

``--output-format=(u-ctags|e-ctags|etags|xref|json)``

Specify the output format. The default is ``u-ctags``.

See tags(5) for ``u-ctags`` and ``e-ctags``.

See ``-e`` for ``etags``, and ``-x`` for ``xref``.

``json`` format is available only if

the ctags executable is built with ``libjansson``.

See ctags-client-tools(7) for more about ``json`` format.

``-e``

Same as ``--output-format=etags``.

Enable etags mode, which will create a tag file for use with the Emacs

editor. Alternatively, if @CTAGS_NAME_EXECUTABLE@ is invoked by a

name containing the string "@ETAGS_NAME_EXECUTABLE@" (either by renaming,

or creating a link to, the executable), etags mode will be enabled.

``-x``

Same as ``--output-format=xref``.

Print a tabular, human-readable cross reference (xref) file to standard

output instead of generating a tag file. The information contained in

the output includes: the tag name; the kind of tag; the line number,

file name, and source line (with extra white space condensed) of the

file which defines the tag. No tag file is written and all options

affecting tag file output will be ignored.

Example applications for this

feature are generating a listing of all functions located in a source

file (e.g. "``@CTAGS_NAME_EXECUTABLE@ -x --kinds-c=f file``"), or generating

a list of all externally visible global variables located in a source

file (e.g. "``@CTAGS_NAME_EXECUTABLE@ -x --kinds-c=v --extras=-F file``").

``--sort=(yes|no|foldcase)``

Indicates whether the tag file should be sorted on the tag name

(default is ``yes``). Note that the original ``vi(1)`` required sorted tags.

The ``foldcase`` value specifies case insensitive (or case-folded) sorting.

Fast binary searches of tag files sorted with case-folding will require

special support from tools using tag files, such as that found in the

@CTAGS_NAME_EXECUTABLE@ readtags library, or Vim version 6.2 or higher

(using "``set ignorecase``").

[Ignored in etags mode]

``-u``

Equivalent to ``--sort=no`` (i.e. "unsorted").

``--etags-include=<file>``

Include a reference to *<file>* in the tag file. This option may be specified

as many times as desired. This supports Emacs' capability to use a

tag file which *includes* other tag files. [Available only in etags mode]

``--input-encoding=<encoding>``

Specifies the *<encoding>* of the input files.

If this option is specified, Universal Ctags converts the input from this

encoding to the encoding specified by ``--output-encoding=encoding``.

``--input-encoding-<LANG>=<encoding>``

Specifies a specific input *<encoding>* for *<LANG>*. It overrides the global

default value given with ``--input-encoding``.

``--output-encoding=<encoding>``

Specifies the *<encoding>* of the tags file.

Universal Ctags converts the encoding of input files from the encoding

specified by ``--input-encoding=<encoding>`` to this encoding.

In addition *<encoding>* is specified at the top the tags file as the

value for the ``TAG_FILE_ENCODING`` pseudo-tag. The default value of

*<encoding>* is ``UTF-8``.

.. _option_lang_mapping:

Language Selection and Mapping Options

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``--language-force=(<language>|auto)``

By default, @CTAGS_NAME_EXECUTABLE@ automatically selects the language

of a source file, ignoring those files whose language cannot be

determined (see "`Determining file language`_"). This option forces the specified

*language* (case-insensitive; either built-in or user-defined) to be used

for every supplied file instead of automatically selecting the language

based upon its extension.

In addition, the special value ``auto`` indicates

that the language should be automatically selected (which effectively

disables this option).

``--languages=[+|-](<list>|all)``

Specifies the languages for which tag generation is enabled, with *<list>*

containing a comma-separated list of language names (case-insensitive;

either built-in or user-defined).

If the first language of *<list>* is not

preceded by either a '``+``' or '``-``', the current list (the current settings

of enabled/disabled languages managed in @CTAGS_NAME_EXECUTABLE@ internally)

will be cleared before adding or removing the languages in *<list>*. Until a '``-``' is

encountered, each language in the *<list>* will be added to the current list.

As either the '``+``' or '``-``' is encountered in the *<list>*, the languages

following it are added or removed from the current list, respectively.

Thus, it becomes simple to replace the current list with a new one, or

to add or remove languages from the current list.

The actual list of

files for which tags will be generated depends upon the language

extension mapping in effect (see the ``--langmap`` option). Note that the most of

languages, including user-defined languages, are enabled unless explicitly

disabled using this option. Language names included in list may be any

built-in language or one previously defined with ``--langdef``.

The default

is ``all``, which is also accepted as a valid argument. See the

``--list-languages`` option for a list of the all (built-in and user-defined)

language names.

Note ``--languages=`` option works cumulative way; the option can be

specified with different arguments multiple times in a command line.

``--alias-<LANG>=[+|-](<pattern>|default)``

Adds ('``+``') or removes ('``-``') an alias *<pattern>* to a language specified

with *<LANG>*. @CTAGS_NAME_EXECUTABLE@ refers to the alias pattern in

"`Determining file language`_" stage.

The parameter *<pattern>* is not a list. Use this option multiple

times in a command line to add or remove multiple alias

patterns.

To restore the default language aliases, specify ``default``.

Using ``all`` for *<LANG>* has meaning in following two cases:

``--alias-all=``

This clears aliases setting of all languages.

``--alias-all=default``

This restores the default languages aliases for all languages.

``--guess-language-eagerly``

Looks into the file contents for heuristically guessing the proper language parser.

See "`Determining file language`_".

``-G``

Equivalent to ``--guess-language-eagerly``.

``--langmap=<map>[,<map>[...]]``

Controls how file names are mapped to languages (see the ``--list-maps``

option). Each comma-separated *<map>* consists of the language name (either

a built-in or user-defined language), a colon, and a list of *file

extensions* and/or *file name patterns*. A file extension is specified by

preceding the extension with a period (e.g. ``.c``). A file name pattern

is specified by enclosing the pattern in parentheses (e.g.

``([Mm]akefile)``).

If appropriate support is available from the runtime

library of your C compiler, then the file name pattern may contain the usual

shell wildcards common on Unix (be sure to quote the option parameter to

protect the wildcards from being expanded by the shell before being

passed to @CTAGS_NAME_EXECUTABLE@). You can determine if shell wildcards

are available on your platform by examining the output of the

``--list-features`` option, which will include ``wildcards`` in the compiled

feature list; otherwise, the file name patterns are matched against

file names using a simple textual comparison.

When mapping a file extension with ``--langmap`` option,

it will first be unmapped from any other languages. (``--map-<LANG>``

option provides more fine-grained control.)

If the first character in a *<map>* is a plus sign ('``+``'), then the extensions and

file name patterns in that map will be appended to the current map

for that language; otherwise, the map will replace the current map.

For example, to specify that only files with extensions of ``.c`` and ``.x`` are

to be treated as C language files, use ``--langmap=c:.c.x``; to also add

files with extensions of ``.j`` as Java language files, specify

``--langmap=c:.c.x,java:+.j``. To map makefiles (e.g. files named either

``Makefile``, ``makefile``, or having the extension ``.mak``) to a language

called ``make``, specify ``--langmap=make:([Mm]akefile).mak``. To map files

having no extension, specify a period not followed by a non-period

character (e.g. '``.``', ``..x``, ``.x.``).

To clear the mapping for a

particular language (thus inhibiting automatic generation of tags for

that language), specify an empty extension list (e.g. ``--langmap=fortran:``).

To restore the default language mappings for a particular language,

supply the keyword ``default`` for the mapping. To specify restore the

default language mappings for all languages, specify ``--langmap=default``.

Note that file name patterns are tested before file extensions when inferring

the language of a file. This order of Universal Ctags is different from

Exuberant Ctags. See ctags-incompatibilities(7) for the background of

this incompatible change.

``--map-<LANG>=[+|-]<extension>|<pattern>``

This option provides the way to control mapping(s) of file names to

languages in a more fine-grained way than ``--langmap`` option.

In @CTAGS_NAME_EXECUTABLE@, more than one language can map to a

file name *<pattern>* or file *<extension>* (*N:1 map*). Alternatively,

``--langmap`` option handle only *1:1 map*, only one language

mapping to one file name *<pattern>* or file *<extension>*. A typical N:1

map is seen in C++ and ObjectiveC language; both languages have

a map to ``.h`` as a file extension.

A file extension is specified by preceding the extension with a period (e.g. ``.c``).

A file name pattern is specified by enclosing the pattern in parentheses (e.g.

``([Mm]akefile)``). A prefixed plus ('``+``') sign is for adding, and

minus ('``-``') is for removing. No prefix means replacing the map of *<LANG>*.

Unlike ``--langmap``, *<extension>* (or *<pattern>*) is not a list.

``--map-<LANG>`` takes one extension (or pattern). However,

the option can be specified with different arguments multiple times

in a command line.

.. _option_tags_file_contents:

Tags File Contents Options

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See "`TAG ENTRIES`_" about fields, kinds, roles, and extras.

``--excmd=(number|pattern|mix|combine)``

Determines the type of ``EX`` command used to locate tags in the source

file. [Ignored in etags mode]

The valid values for type (either the entire word or the first letter

is accepted) are:

``number``

Use only line numbers in the tag file for locating tags. This has

four advantages:

1. Significantly reduces the size of the resulting tag file.

2. Eliminates failures to find tags because the line defining the

tag has changed, causing the pattern match to fail (note that

some editors, such as ``vim``, are able to recover in many such

instances).

3. Eliminates finding identical matching, but incorrect, source

lines (see "`BUGS`_").

4. Retains separate entries in the tag file for lines which are

identical in content. In pattern mode, duplicate entries are

dropped because the search patterns they generate are identical,

making the duplicate entries useless.

However, this option has one significant drawback: changes to the

source files can cause the line numbers recorded in the tag file

to no longer correspond to the lines in the source file, causing

jumps to some tags to miss the target definition by one or more

lines. Basically, this option is best used when the source code

to which it is applied is not subject to change. Selecting this

option type causes the following options to be ignored: ``-B``, ``-F``.

``number`` type is ignored in Xref and JSON output formats. Use

``--_xformat="...%n"`` for Xref output format, or ``--fields=+n-P`` for

JSON output format.

.. NOTE: #2792

``pattern``

Use only search patterns for all tags, rather than the line numbers

usually used for macro definitions. This has the advantage of

not referencing obsolete line numbers when lines have been added or

removed since the tag file was generated.

``mixed``

In this mode, patterns are generally used with a few exceptions.

For C, line numbers are used for macro definition tags. For Fortran, line numbers

are used for common blocks because their corresponding source lines

are generally identical, making pattern searches useless

for finding all matches.

This was the default format generated by the original ctags and is,

therefore, retained as the default for this option.

``combine``

Concatenate the line number and pattern with a semicolon in between.

``-n``

Equivalent to ``--excmd=number``.

``-N``

Equivalent to ``--excmd=pattern``.

``--extras=[+|-][<flags>|*]``

Specifies whether to include extra tag entries for certain kinds of

information. See also "`Extras`_" subsection to know what are extras.

The parameter *<flags>* is a set of one-letter flags (and/or long-name flags), each

representing one kind of extra tag entry to include in the tag file.

If flags is preceded by either the '``+``' or '``-``' character, the effect of

each flag is added to, or removed from, those currently enabled;

otherwise the flags replace any current settings. All entries are

included if '``*``' is given.

This ``--extras=`` option is for controlling extras common in all

languages (or language-independent extras). Universal Ctags also

supports language-specific extras. (See "`Language-specific fields and

extras`_" about the concept). Use ``--extras-<LANG>=`` option for

controlling them.

``--extras-(<LANG>|all)=[+|-][<flags>|*]``

Specifies whether to include extra tag entries for certain kinds of

information for language *<LANG>*. Universal Ctags

introduces language-specific extras. See "`Language-specific fields and

extras`_" about the concept. This option is for controlling them.

Specifies ``all`` as *<LANG>* to apply the parameter *<flags>* to all

languages; all extras are enabled with specifying '``*``' as the

parameter flags. If specifying nothing as the parameter flags

(``--extras-all=``), all extras are disabled. These two combinations

are useful for testing.

Check the output of the ``--list-extras=<LANG>`` option for the

extras of specific language *<LANG>*.

``--fields=[+|-][<flags>|*]``

Specifies which language-independent fields are to be included in the tag

entries. Language-independent fields are extension fields which are common

in all languages. See "`TAG FILE FORMAT`_" section, and "`Extension fields`_"

subsection, for details of extension fields.

The parameter *<flags>* is a set of one-letter or long-name flags,

each representing one type of extension field to include.

Each flag or group of flags may be preceded by either '``+``' to add it

to the default set, or '``-``' to exclude it. In the absence of any

preceding '``+``' or '``-``' sign, only those fields explicitly listed in flags

will be included in the output (i.e. overriding the default set). All

fields are included if '``*``' is given.

This option is ignored if the

option ``--format=1`` (legacy tag file format) has been specified.

Use ``--fields-<LANG>=`` option for controlling language-specific fields.

``--fields-(<LANG>|all)=[+|-][<flags>|*]``

Specifies which language-specific fields are to be included in

the tag entries. Universal Ctags

supports language-specific fields. (See "`Language-specific fields and

extras`_" about the concept).

Specify ``all`` as *<LANG>* to apply the parameter *<flags>* to all

languages; all fields are enabled with specifying '``*``' as the

parameter flags. If specifying nothing as the parameter *<flags>*

(i.e. ``--fields-all=``), all fields are disabled. These two combinations

are useful for testing.

See the description of ``--fields=[+|-][<flags>|*]`` about *<flags>*.

Use ``--fields=`` option for controlling language-independent fields.

``--kinds-(<LANG>|all)=[+|-](<kinds>|*)``

Specifies a list of language-specific *<kinds>* of tags (or kinds) to

include in the output file for a particular language, where *<LANG>* is

case-insensitive and is one of the built-in language names (see the

``--list-languages`` option for a complete list).

The parameter *<kinds>* is a group

of one-letter or long-name flags designating kinds of tags (particular to the language)

to either include or exclude from the output. The specific sets of

flags recognized for each language, their meanings and defaults may be

list using the ``--list-kinds-full`` option.

Each letter or group of letters

may be preceded by either '``+``' to add it to, or '``-``' to remove it from,

the default set. In the absence of any preceding '``+``' or '``-``' sign, only

those kinds explicitly listed in kinds will be included in the output

(i.e. overriding the default for the specified language).

Specify '``*``' as the parameter to include all kinds implemented

in *<LANG>* in the output. Furthermore if ``all`` is given as *<LANG>*,

specification of the parameter ``kinds`` affects all languages defined

in @CTAGS_NAME_EXECUTABLE@. Giving ``all`` makes sense only when '``*``' or

'``F``' is given as the parameter ``kinds``.

As an example for the C language, in order to add prototypes and

external variable declarations to the default set of tag kinds,

but exclude macros, use ``--kinds-c=+px-d``; to include only tags for

functions, use ``--kinds-c=f``.

Some kinds of C and C++ languages are synchronized; enabling

(or disabling) a kind in one language enables the kind having

the same one-letter and long-name in the other language. See also the

description of ``MASTER`` column of ``--list-kinds-full``.

.. COMMENT:

``--param-<LANG>.name=argument`` is moved to "Language Specific Options"

``--pattern-length-limit=<N>``

Truncate patterns of tag entries after *<N>* characters. Disable by setting to 0

(default is 96).

An input source file with long lines and multiple tag matches per

line can generate an excessively large tags file with an

unconstrained pattern length. For example, running ctags on a

minified JavaScript source file often exhibits this behavior.

The truncation avoids cutting in the middle of a UTF-8 code point

spanning multiple bytes to prevent writing invalid byte sequences from

valid input files. This handling allows for an extra 3 bytes above the

configured limit in the worse case of a 4 byte code point starting

right before the limit. Please also note that this handling is fairly

naive and fast, and although it is resistant against any input, it

requires a valid input to work properly; it is not guaranteed to work

as the user expects when dealing with partially invalid UTF-8 input.

This also partially affect non-UTF-8 input, if the byte sequence at

the truncation length looks like a multibyte UTF-8 sequence. This

should however be rare, and in the worse case will lead to including

up to an extra 3 bytes above the limit.

``--pseudo-tags=[+|-](<pseudo-tag>|*)``

Enable/disable emitting pseudo-tag named *<pseudo-tag>*.

If '``*``' is given, enable/disable emitting all pseudo-tags.

``--put-field-prefix``

Put ``UCTAGS`` as prefix for the name of fields newly introduced in

Universal Ctags.

Some fields are newly introduced in Universal Ctags and more will

be introduced in the future. Other tags generators may also

introduce their specific fields.

In such a situation, there is a concern about conflicting field

names; mixing tags files generated by multiple tags generators

including Universal Ctags is difficult. This option provides a

workaround for such station.

.. code-block:: console

$ @CTAGS_NAME_EXECUTABLE@ --fields='{line}{end}' -o - hello.c

main hello.c /^main(int argc, char **argv)$/;" f line:3 end:6

$ @CTAGS_NAME_EXECUTABLE@ --put-field-prefix --fields='{line}{end}' -o - hello.c

main hello.c /^main(int argc, char **argv)$/;" f line:3 UCTAGSend:6

In the above example, the prefix is put to ``end`` field which is

newly introduced in Universal Ctags.

``--roles-(<LANG>|all).(<kind>|*)=[+|-][<roles>|*]``

Specifies a list of kind-specific roles of tags to include in the

output file for a particular language.

*<kind>* specifies the kind where the *<roles>* are defined.

*<LANG>* specifies the language where the kind is defined.

Each role in *<roles>* must be surrounded by braces (e.g. ``{system}``

for a role named "system").

Like ``--kinds-<LANG>`` option, '``+``' is for adding the role to the

list, and '``-``' is for removing from the list. '``*``' is for including

all roles of the kind to the list. The option with no argument

makes the list empty.

Both a one-letter flag or a long name flag surrounded by braces are

acceptable for specifying a kind (e.g. ``--roles-C.h=+{system}{local}``

or ``--roles-C.{header}=+{system}{local}``). '``*``' can be used for *<KIND>*

only for adding/removing all roles of all kinds in a language to/from

the list (e.g. ``--roles-C.*=*`` or ``--roles-C.*=``).

``all`` can be used for *<LANG>* only for adding/removing all roles of

all kinds in all languages to/from the list

(e.g. ``--roles-all.*=*`` or ``--roles-all.*=``).

``--tag-relative=(yes|no|always|never)``

Specifies how the file paths recorded in the tag file.

The default is ``yes`` when running in etags mode (see

the ``-e`` option), ``no`` otherwise.

``yes``

indicates that the file paths recorded in the tag file should be

*relative to the directory containing the tag file*

unless the files supplied on the command line

are specified with absolute paths.

``no``

indicates that the file paths recorded in the tag file should be

*relative to the current directory*

unless the files supplied on the command line

are specified with absolute paths.

``always``

indicates the recorded file paths should be relative

even if source file names are passed in with absolute paths.

``never``

indicates the recorded file paths should be absolute

even if source file names are passed in with relative paths.

``--use-slash-as-filename-separator[=(yes|no)]``

Uses slash ('``/``') character as filename separators instead of backslash

('``\``') character when printing ``input:`` field.

The default is ``yes`` for the default "u-ctags" output format, and

``no`` for the other formats.

This option is available on MS Windows only.

``-B``

Use backward searching patterns (e.g. ``?pattern?``). [Ignored in etags mode]

``-F``

Use forward searching patterns (e.g. ``/pattern/``) (default). [Ignored

in etags mode]

Option File Options

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. TODO: merge some of description in option-file.rst into FILE or a dedicated

section

``--options=<pathname>``

Read additional options from file or directory.

@CTAGS_NAME_EXECUTABLE@ searches *<pathname>* in the optlib path list

first. If @CTAGS_NAME_EXECUTABLE@ cannot find a file or directory

in the list, @CTAGS_NAME_EXECUTABLE@ reads a file or directory

at the specified *<pathname>*.

If a file is specified, it should contain one option per line. If

a directory is specified, files suffixed with ``.ctags`` under it

are read in alphabetical order.

As a special case, if ``--options=NONE`` is specified as the first

option on the command line, preloading is disabled; the option

will disable the automatic reading of any configuration options

from a file (see "`FILES`_").

``--options-maybe=<pathname>``

Same as ``--options`` but doesn't cause an error if file

(or directory) specified with *<pathname>* doesn't exist.

``--optlib-dir=[+]<directory>``

Add an optlib *<directory>* to or reset the optlib path list.

By default, the optlib path list is empty.

optlib Options

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See ctags-optlib(7) for details of each option.

``--kinddef-<LANG>=<letter>,<name>,<description>``

Define a kind for *<LANG>*.

Don't be confused this with ``--kinds-<LANG>``.

``--langdef=<name>``

Defines a new user-defined language, *<name>*, to be parsed with regular

expressions.

``--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]``

Define multi-line regular expression for locating tags in specific language.

``--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]``

Define single-line regular expression for locating tags in specific language.

.. _option_lang_specific:

Language Specific Options

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``--if0[=(yes|no)]``

Indicates a preference as to whether code within an "``#if 0``" branch of a

preprocessor conditional should be examined for non-macro tags (macro

tags are always included). Because the intent of this construct is to

disable code, the default value of this option is ``no`` (disabled).

Note that this

indicates a preference only and does not guarantee skipping code within

an "``#if 0``" branch, since the fall-back algorithm used to generate

tags when preprocessor conditionals are too complex follows all branches

of a conditional.

``--line-directives[=(yes|no)]``

Specifies whether ``#line`` directives should be recognized. These are

present in the output of a preprocessor and contain the line number, and

possibly the file name, of the original source file(s) from which the

preprocessor output file was generated. This option is off by default.

When enabled, this option will

cause @CTAGS_NAME_EXECUTABLE@ to generate tag entries marked with the

file names and line numbers of their locations original source file(s),

instead of their actual locations in the preprocessor output. The actual

file names placed into the tag file will have the same leading path

components as the preprocessor output file, since it is assumed that

the original source files are located relative to the preprocessor

output file (unless, of course, the ``#line`` directive specifies an

absolute path).

Note: This option is generally

only useful when used together with the ``--excmd=number`` (``-n``) option.

Also, you may have to use either the ``--langmap`` or ``--language-force`` option

if the extension of the preprocessor output file is not known to

@CTAGS_NAME_EXECUTABLE@.

``-D <macro>=<definition>``

Defines a C preprocessor *<macro>*. This emulates the behavior of the

corresponding gcc option. All types of macros are supported,

including the ones with parameters and variable arguments.

Stringification, token pasting and recursive macro expansion are also

supported.

This extends the function provided by ``-I`` option.

``-h (<list>|default)``

Specifies a *<list>* of file extensions, separated by periods, which are

to be interpreted as include (or header) files. To indicate files having

no extension, use a period not followed by a non-period character

(e.g. '``.``', ``..x``, ``.x.``).

This option only affects how the scoping of

particular kinds of tags are interpreted (i.e. whether or not they are

considered as globally visible or visible only within the file in which

they are defined); it does not map the extension to any particular

language. Any tag which is located in a non-include file and cannot be

seen (e.g. linked to) from another file is considered to have file-limited

(e.g. static) scope. No kind of tag appearing in an include file

will be considered to have file-limited scope.

If the first character in the list is '``+``', then the extensions in the list will be

appended to the current list; otherwise, the list will replace the

current list. See, also, the ``fileScope``/``F`` flag of ``--extras`` option.

The default list is

``.h.H.hh.hpp.hxx.h++.inc.def``. To restore the default list, specify "``-h

default``".

Note that if an extension supplied to this option is not

already mapped to a particular language (see "`Determining file language`_", above),

you will also need to use either the ``--map-<LANG>``, ``--langmap`` or

``--language-force`` option.

``-I <identifier-list>``

Specifies a *<identifier-list>* of identifiers which are to be specially handled while

parsing C and C++ source files. This option is specifically provided

to handle special cases arising through the use of preprocessor macros.

When the identifiers listed are simple identifiers, these identifiers

will be ignored during parsing of the source files.

If an identifier is

suffixed with a '``+``' character (i.e. "``-I FOO+``"), @CTAGS_NAME_EXECUTABLE@ will also

ignore any parenthesis-enclosed argument list which may immediately

follow the identifier in the source files. See the example of "``-I

MODULE_VERSION+``" below.

If two identifiers are

separated with the '``=``' character (i.e. ``-I FOO=BAR``), the first identifiers is replaced by

the second identifiers for parsing purposes. The list of identifiers may

be supplied directly on the command line or read in from a separate file.

See the example of "``-I CLASS=class``" below.

If the first character of *<identifier-list>* is '``@``', '``.``' or a pathname

separator ('``/``' or '``\``'), or the first two characters specify a drive

letter (e.g. ``C:``), the parameter *<identifier-list>* will be interpreted as

a filename from which to read a list of identifiers, one per input line.

Otherwise, *<identifier-list>* is a list of identifiers (or identifier

pairs) to be specially handled, each delimited by either a comma or

by white space (in which case the list should be quoted to keep the

entire list as one command line argument).

Multiple ``-I`` options may be

supplied. To clear the list of ignore identifiers, supply a single

dash ('``-``') for *<identifier-list>*.

This feature is useful when preprocessor macros are used in such a way

that they cause syntactic confusion due to their presence. Indeed,

this is the best way of working around a number of problems caused by

the presence of syntax-busting macros in source files (see "`CAVEATS`_").

Some examples will illustrate this point.

.. code-block:: C

int foo ARGDECL4(void *, ptr, long int, nbytes)

In the above example, the macro ``ARGDECL4`` would be mistakenly

interpreted to be the name of the function instead of the correct name

of ``foo``. Specifying "``-I ARGDECL4``" results in the correct behavior.

.. code-block:: C

/* creates an RCS version string in module */

MODULE_VERSION("$Revision$")

In the above example the macro invocation looks too much like a function

definition because it is not followed by a semicolon (indeed, it

could even be followed by a global variable definition that would look

much like a K&R style function parameter declaration). In fact, this

seeming function definition could possibly even cause the rest of the

file to be skipped over while trying to complete the definition.

Specifying "``-I MODULE_VERSION+``" would avoid such a problem.

.. code-block:: C

CLASS Example {

// your content here

};

The example above uses ``CLASS`` as a preprocessor macro which expands to

something different for each platform. For instance ``CLASS`` may be

defined as ``class __declspec(dllexport)`` on Win32 platforms and simply

``class`` on UNIX. Normally, the absence of the C++ keyword ``class``

would cause the source file to be incorrectly parsed. Correct behavior

can be restored by specifying "``-I CLASS=class``".

``--param-<LANG>.<name>=<argument>``

Set a *<LANG>* specific parameter, a parameter specific to the *<LANG>*.

Available parameters can be listed with ``--list-params``.