ctags-incompatibilities(7)

🎀 NAME 🎀

ctags-incompatibilities — the incompatibilities between Universal Ctags and Exuberant Ctags. 💔

📜 SYNOPSIS 📜

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

💅 DESCRIPTION 💅

okay bestie, gather round, because this page is the lore: it describes the major incompatible changes introduced to Universal Ctags after it forked from Exuberant Ctags. Read it before you go copy-pasting your ancient config, fr fr. 🫶

---

🗂️ Option files loading at starting up time (preload files) 🗂️

Universal Ctags does NOT load ~/.ctags at starting up time. Not a thing anymore, sorry. The file paths for preload files are changed too, so go peep the "FILES" section of ctags(1) for where they live now. ✨

🌱 Environment variables for arranging command lines 🌱

Universal Ctags doesn't read the CTAGS and/or ETAGS environment variables. Like, at all. 🙈

😭 Behavior when --excmd=mixed is given 😭

Exuberant Ctags uses line numbers as addresses for C preprocessor macro definition tags. Universal Ctags uses patterns for the tags. Same flag, different vibe. 🔄

🚧 Incompatibilities in command line interface 🚧

📏 Ordering in a command line 📏

The command line format of Universal Ctags is "ctags [options] [source_file(s)]" — following the standard POSIX convention, periodt. 👑

Exuberant Ctags accepts an option following a source file, like this:

$ 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 🔍

When applying mappings for a name of given source file, Exuberant Ctags tests file name patterns AFTER file extensions — that's e-map-order. Universal Ctags does this differently; it tests file name patterns BEFORE file extensions — that's u-map-order. Iconic of it, honestly.

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.

So 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. But e-map-order chooses the XML parser. So Universal Ctags uses the u-map-order even though it introduces an incompatibility. Sacrifices were made. 😤

--list-map-extensions=<language> and --list-map-patterns=<language> options are helpful to verify the file extensions and the file name patterns of given <language>. Use them, they're so helpful. 🌈

🗑️ Remove --file-tags and --file-scope options 🗑️

Even in Exuberant Ctags, --file-tags is not documented in its man page. (not me calling out the old docs 💀)

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 🧬

🏷️ Language name defined with --langdef=name option 🏷️

The characters you can use are more restricted than Exuberant Ctags. For more details, see the description of --langdef=name in ctags-optlib(7). Go read it, bestie. 📖

💀 Obsoleting --<LANG>-kinds option 💀

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. (slay ✨)

🚫 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. Nope, can't do it. 🙅

🚫 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. Also no. 🙅

🔤 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. That's the rule now, bestie.

🅰️ 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. (it's giving structure 💅)

🎯 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. No duplicates, no cap. 🚫

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. Caught in 4k. 📸

📦 Incompatibilities in tags file format 📦

🔢 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 ✂️

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 🔤

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 👀

ctags(1), ctags-optlib(7), and tags(5).

---

and that's the whole page, bestie 💖 this was Universal Ctags version 6.2.1 bringing you the ctags-incompatibilities(7) energy, so if you're migrating off Exuberant Ctags, you've been warned and you're gonna be fine. slay, go read your tags files. 🦋✨