ctags-incompatibilities(7) Universal Ctags ctags-incompatibilities(7)

# [Name](#Name)

ctags-incompatibilities - Incompatibilities between Universal Ctags and Exuberant Ctags

# [SYNOPSIS](#SYNOPSIS)

```
ctags [options] [file(s)]
etags [options] [file(s)]
```

# [DESCRIPTION](#DESCRIPTION)

This page describes major incompatible changes introduced to Universal Ctags forked from Exuberant Ctags.

## [Option files loading at starting up time (preload files)](#Option_files_loading_at_starting_up_time_%28preload_files%29)

Universal Ctags doesn't load **~/.ctags** at starting up time. File paths for preload files are changed. See "FILES" section of [ctags(1)](/man/os/universal-ctags/ctags.1).

## [Environment variables for arranging command lines](#Environment_variables_for_arranging_command_lines)

Universal Ctags doesn't read **CTAGS** and/or **ETAGS** environment variables.

## [Behavior when **--excmd=mixed** is given](#Behavior_when_)

Exuberant Ctags uses line numbers as addresses for C preprocessor macro definition tags. Universal Ctags uses patterns for the tags.

## [Incompatibilities in command line interface](#Incompatibilities_in_command_line_interface)

## [Ordering in a command line](#Ordering_in_a_command_line)

The command line format of Universal Ctags is "**ctags \[options]** **\[source\_file(s)]**" following the standard POSIX convention.

Exuberant Ctags accepts a option following a source file.

```
$ ctags -o - foo.c --list-kinds=Sh
f  functions
```

Universal Ctags warns and ignores the option **--list-kinds=Sh** as follows.

```
$ ctags -o - foo.c --list-kinds=Sh
ctags: Warning: cannot open input file "--list-kinds=Sh" : No such file or directory
a       foo.c   /^void a () {}$/;"      f       typeref:typename:void
b       foo.c   /^void b () {}$/;"      f       typeref:typename:void
```

## [The order of application of patterns and extensions in **--langmap**](#The_order_of_application_of_patterns_and_extensions_in_)

When applying mappings for a name of given source file, Exuberant Ctags tests file name patterns *AFTER* file extensions (*e-map-order*). Universal Ctags does this differently; it tests file name patterns *BEFORE* file extensions (*u-map-order*).

This incompatible change is introduced to deal with the following situation:

- **build.xml** as a source file,
- The Ant parser declares it handles a file name pattern **build.xml**, and
- The XML parser declares it handles a file extension **.xml**.

Which parser should be used for parsing **build.xml**? The assumption of Universal Ctags is the user may want to use the Ant parser; the file name pattern it declares is more specific than the file extension that the XML parser declares. However, e-map-order chooses the XML parser.

So Universal Ctags uses the u-map-order even though it introduces an incompatibility.

**--list-map-extensions=<language>** and **--list-map-patterns=<language>** options are helpful to verify and the file extensions and the file name patterns of given *<language>*.

## [Remove **--file-tags** and **--file-scope** options](#Remove_)

Even in Exuberant Ctags, **--file-tags** is not documented in its man page. Instead of specifying **--file-tags** or **--file-tags=yes**, use **--extras=+f** or **--extras=+{inputFile}**.

Instead of specifying **--file-tags=no**, use **--extras=-f** or **--extras=-{inputFile}**.

Universal Ctags introduces **F/fileScope** extra as the replacement for **--file-scope** option.

Instead of specifying **--file-tags** or **--file-tags=yes**, use **--extras=+F** or **--extras=+{fileScope}**.

Instead of specifying **--file-tags=no**, use **--extras=-F** or **--extras=-{fileScope}**.

## [Incompatibilities in language and kind definitions](#Incompatibilities_in_language_and_kind_definitions)

## [Language name defined with **--langdef=name** option](#Language_name_defined_with_)

The characters you can use are more restricted than Exuberant Ctags. For more details, see the description of **--langdef=name** in [ctags-optlib(7)](/man/os/universal-ctags/ctags-optlib.7).

## [Obsoleting **--<LANG>-kinds** option](#Obsoleting_)

Some options have *<LANG>* as parameterized parts in their name like **--foo-<LANG>=...** or **--<LANG>-foo=...**. The most of all such options in Exuberant Ctags have the former form, **--foo-<LANG>=...**. The exception is **--<LANG>-kinds**.

Universal Ctags uses the former form for all *<LANG>* parameterized option. Use **--kinds-<LANG>** instead of **--<LANG>-kinds** in Universal Ctags. **--<LANG>-kinds** still works but it will be removed in the future.

The former form may be friendly to shell completion engines.

## Disallowing to define a kind with **file** as name

The kind name **file** is reserved. Using it as part of kind spec in **--regex-<LANG>** option is now disallowed.

## Disallowing to define a kind with '**F**' as letter

The kind letter '**F**' is reserved. Using it as part of a kind spec in **--regex-<LANG>** option is now disallowed.

## [Disallowing to use other than alphabetical character as kind letter](#Disallowing_to_use_other_than_alphabetical_character_as_kind_letter)

Exuberant Ctags accepts a character other than alphabetical character as kind letter in **--regex-<LANG>=...** option. Universal Ctags accepts only an alphabetical character.

## [Acceptable characters as parts of a kind name](#Acceptable_characters_as_parts_of_a_kind_name)

Exuberant Ctags accepts any character as a part of a kind name defined with **--regex-<LANG>=/regex/replacement/kind-spec/**.

Universal Ctags accepts only an alphabetical character as the initial letter of a kind name. Universal Ctags accepts only an alphabetical character or numerical character as the rest letters.

An example:

```
--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstract class/i
```

Universal Ctags rejects this because the kind name, **abstract class**, includes a whitespace character.

This requirement is for making the output of Universal Ctags follow the tags file format.

## [A combination of a kind letter and a kind name](#A_combination_of_a_kind_letter_and_a_kind_name)

In Universal Ctags, the combination of a kind letter and a kind name must be unique in a language.

You cannot define more than one kind reusing a kind letter with different kind names. You cannot define more than one kind reusing a kind name with different kind letters.

An example:

```
--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstractClass/i
--regex-Foo=/attribute +([a-z]+)/\1/a,attribute/i
```

Universal Ctags rejects this because the kind letter, '**a**', used twice for defining a kind **abstractClass** and **attribute**.

## [Incompatibilities in tags file format](#Incompatibilities_in_tags_file_format)

## [Using numerical character in the name part of tag tagfield](#Using_numerical_character_in_the_name_part_of_tag_tagfield)

The version 2 tags file format, the default output format of Exuberant Ctags, accepts only alphabetical characters in the name part of tag tagfield.

Universal Ctags introduces an exception to this specification; it may use numerical characters in addition to alphabetical characters as the letters other than initial letter of the name part.

The kinds **heading1**, **heading2**, and **heading3** in the HTML parser are the examples.

## [Truncating the pattern for long input lines](#Truncating_the_pattern_for_long_input_lines)

To prevent generating overly large tags files, a pattern field is truncated, by default, when its size exceeds 96 bytes. A different limit can be specified with **--pattern-length-limit=N**. Specifying 0 as *N* results no truncation as Exuberant Ctags does not.

## [Kind letters and names](#Kind_letters_and_names)

A kind letter '**F**' and a kind name **file** are reserved in the main part. A parser cannot have a kind conflicting with these reserved ones. Some incompatible changes are introduced to follow the above rule.

- Cobol's **file** kind is renamed to **fileDesc** because the kind name **file** is reserved.
- Ruby's '**F**' (singletonMethod) is changed to '**S**'.
- SQL's '**F**' (field) is changed to '**E**'.

# [SEE ALSO](#SEE_ALSO)

[ctags(1)](/man/os/universal-ctags/ctags.1), [ctags-optlib(7)](/man/os/universal-ctags/ctags-optlib.7), and [tags(5)](/man/os/universal-ctags/tags.5).

6.2.1

---

Document: ctags-incompatibilities(7) from universal-ctags 6.2.1-r1 (Chainguard OS)
Source: https://github.com/universal-ctags/ctags