1CTAGS-FAQ(7)                    Universal Ctags                   CTAGS-FAQ(7)
2
3
4

NAME

6       ctags-faq - Universal Ctags FAQ
7
8       This  is  the  Universal Ctags FAQ (Frequently-Asked Questions).  It is
9       based on Exuberant Ctags FAQ
10
11   Contents
12DESCRIPTION
13
14What is the difference between Universal Ctags and Exuberant Ctags?
15
16How can I avoid having to specify my favorite option every time?
17
18What are these strange bits of text beginning with ;" which  follow
19           many of the lines in the tag file?
20
21         Why can't I jump to class::member?
22
23         Why do I end up on the wrong line when I jump to a tag?
24
25How  do  I  jump  to the tag I want instead of the wrong one by the
26           same name?
27
28How can I locate all references to a specific function or variable?
29
30Why does appending tags to a tag file tag so long?
31
32How should I set up tag files for a multi-level  directory  hierar‐
33           chy?
34
35Does Universal Ctags support Unicode file names?
36
37Why does zsh cause "zsh: no matches found" error?
38
39SEE ALSO
40
41AUTHOR
42

DESCRIPTION

44   What is the difference between Universal Ctags and Exuberant Ctags?
45       Universal  Ctags is an unofficial fork of Exuberant Ctags.  The differ‐
46       ences are summarized in ctags-incompatibilities(7) man page.
47
48       The most notable one is that  Universal  Ctags  doesn't  read  ~/.ctags
49       file.  Instead, it reads *.ctags under ~/.ctags.d directory.
50
51   How can I avoid having to specify my favorite option every time?
52       Either  by  setting  the  environment variable CTAGS to your custom op‐
53       tions, or putting them into a  ~/.ctags.d/anyname.ctags  file  in  your
54       home directory.
55
56   What  are these strange bits of text beginning with ;" which follow many of
57       the lines in the tag file?
58       These are extension flags. They are added in order to provide extra in‐
59       formation  about the tag that may be utilized by the editor in order to
60       more intelligently handle tags. They are appended  to  the  EX  command
61       part  of the tag line in a manner that provides backwards compatibility
62       with existing implementations of the Vi editor. The semicolon is an  EX
63       command  separator and the double quote begins an EX comment. Thus, the
64       extension flags appear as an EX comment and should be  ignored  by  the
65       editor when it processes the EX command.
66
67       Some  non-vi  editors,  however,  implement only the bare minimum of EX
68       commands in order to process the search command or line number  in  the
69       third field of the tag file. If you encounter this problem, use the op‐
70       tion --format=1 to generate a tag file without these extensions (remem‐
71       ber  that you can set the CTAGS environment variable to any default ar‐
72       guments you wish to supply). Then ask the supplier of  your  editor  to
73       implement handling of this feature of EX commands.
74
75   Why can't I jump to class::member?
76       Because, by default, ctags only generates tags for the separate identi‐
77       fiers found in the source files. If you specify the --extra=+q  option,
78       then  ctags  will  also generate a second, class-qualified tag for each
79       class member (data and function/method) in the form  class::member  for
80       C++, and in the form class.method for Eiffel and Java.
81
82   Why do I end up on the wrong line when I jump to a tag?
83       By default, ctags encodes the line number in the file where macro (#de‐
84       fine) tags are found. This was done to remain compatible with the orig‐
85       inal  UNIX  version of ctags. If you change the file containing the tag
86       without rebuilding the tag file, the location of tag in  the  tag  file
87       may no longer match the current location.
88
89       In  order  to avoid this problem, you can specify the option --excmd=p,
90       which causes ctags to use a search pattern to locate macro tags. I have
91       never  uncovered  the reason why the original UNIX ctags used line num‐
92       bers exclusively for macro tags, but have so far resisted changing  the
93       default  behavior  of Exuberant (and Universal) Ctags to behave differ‐
94       ently.
95
96   How do I jump to the tag I want instead of the wrong one by the same name?
97       A tag file is simple a list of tag names and where  to  find  them.  If
98       there  are  duplicate  entries, you often end up going to the wrong one
99       because the tag file is sorted and your editor locates the first one in
100       the tag file.
101
102       Standard Vi provides no facilities to alter this behavior. However, Vim
103       has some nice features to minimize this problem, primarily by examining
104       all matches and choosing the best one under the circumstances. Vim also
105       provides commands which allow for selection  of  the  desired  matching
106       tag.
107
108   How can I locate all references to a specific function or variable?
109       There  are  several packages already available which provide this capa‐
110       bility.   Namely,  these  are:  GLOBAL  source  code  tag  system,  GNU
111       id-utils,  cscope,  and cflow. As of this writing, they can be found in
112       the following locations:
113
114       • GLOBAL:    http://www.gnu.org/software/global
115
116       • id-utils:  http://www.gnu.org/software/idutils/idutils.html
117
118       • cscope:    http://cscope.sourceforge.net
119
120       • cflow:     ftp://www.ibiblio.org/pub/Linux/devel/lang/c
121
122   Why does appending tags to a tag file tag so long?
123       Sometimes, in an attempt to build a global  tag  file  for  all  source
124       files  in a large source tree of many directories, someone will make an
125       attempt to run ctags in append (-a) mode on every directory in the  hi‐
126       erarchy.  Each  time  ctags is invoked, its default behavior is to sort
127       the tag file once the tags for that execution have been added.  As  the
128       cumulative tag file grows, the sort time increases arithmetically.
129
130       The  best way to avoid this problem (and the most efficient) is to make
131       use of the --recurse (or -R) option of ctags by executing the following
132       command in the root of the directory hierarchy (thus running ctags only
133       once):
134
135              ctags -R
136
137       If you really insist on running ctags separately on each directory, you
138       can  avoid  the sort pass each time by specifying the option --sort=no.
139       Once the tag file is completely built, use the sort command to manually
140       sort  the final tag file, or let the final invocation of ctags sort the
141       file.
142
143   How should I set up tag files for a multi-level directory hierarchy?
144       There are a few ways of approaching this:
145
146       1. A local tag file in each directory  containing  only  the  tags  for
147          source files in that directory.
148
149       2. One  single  big,  global  tag file present in the root directory of
150          your hierarchy, containing all tags present in all source  files  in
151          the hierarchy.
152
153       3. A  local  tag  file  in  each directory containing only the tags for
154          source files in that directory, in addition to one single global tag
155          file present in the root directory of your hierarchy, containing all
156          non-static tags present in all source files in the hierarchy.
157
158       4. A local tag file in each directory of the hierarchy, each  one  con‐
159          taining  all  tags present in source files in that directory and all
160          non-static tags in every directory below it (note that this  implies
161          also  having  one  big tag file in the root directory of the hierar‐
162          chy).
163
164       Each of these approaches has its own set of  advantages  and  disadvan‐
165       tages,  depending  upon  your  particular conditions. Which approach is
166       deemed best depends upon the following factors:
167
168       A. The ability of your editor to use multiple tag files.
169
170          If your editor cannot make use of multiple tag  files  (original  vi
171          implementations  could not), then one large tag file is the only way
172          to go if you ever desire to jump to tags located in  other  directo‐
173          ries.  If  you never need to jump to tags in another directory (i.e.
174          the source in each directory is entirely self-contained), then a lo‐
175          cal tag file in each directory will fit your needs.
176
177       B. The time is takes for your editor to look up a tag in the tag file.
178
179          The significance of this factor depends upon the size of your source
180          tree and on whether the source files are located on a local  or  re‐
181          mote  file  system. For source and tag files located on a local file
182          system, looking up a tag is not as big a  hit  as  one  might  first
183          imagine,  since vi implementations typically perform a binary search
184          on a sorted tag file. This may or may not be true for the editor you
185          use. For files located on a remote file system, reading a large file
186          is an expensive operation.
187
188       C. Whether or not you expect the source code to change and the time  it
189          takes  to  rebuild  a  tag file to account for changes to the source
190          code.
191
192          While Universal Ctags is particularly fast in scanning  source  code
193          (around  1-2 MB/sec), a large project may still result in objection‐
194          able delays if one wishes to keep their tag file(s) up to date on  a
195          frequent basis, or if the files are located on a remote file system.
196
197       D. The presence of duplicate tags in the source code and the ability to
198          handle them.
199
200          The impact of this factor is influenced by the following  three  is‐
201          sues:
202
203          1. How common are duplicate tags in your project?
204
205          2. Does  your  editor provide any facilities for dealing with dupli‐
206             cate tags?
207
208             While standard vi does not, many modern vi implementations,  such
209             as  Vim have good facilities for selecting the desired match from
210             the list of duplicates. If your editor does not support duplicate
211             tags,  then  it  will  typically  send  you  to only one of them,
212             whether or not that is the one you wanted (and not even notifying
213             you that there are other potential matches).
214
215          3. What is the significance of duplicate tags?
216
217             For  example, if you have two tags of the same name from entirely
218             isolated software components, jumping first to the match found in
219             component B while working in component A may be entirely mislead‐
220             ing, distracting or inconvenient (to keep having to choose  which
221             one  if  your  editor provides you with a list of matches).  How‐
222             ever, if you have two tags of the same name for  parallel  builds
223             (say  two  initialization  routines for different hosts), you may
224             always want to specify which one you want.
225
226       Of the approaches listed above, I tend to favor Approach 3.  My  editor
227       of  choice  is  Vim, which provides a rich set of features for handling
228       multiple tag files, which partly influences my choice. If you are work‐
229       ing  with  source files on a remote file system, then I would recommend
230       either Approach 3 or Approach 4, depending upon the  hit  when  reading
231       the global tag file.
232
233       The  advantages  of  Approach 3 are many (assuming that your editor has
234       the ability to support both multiple tag files and duplicate tags). All
235       lookups  of tag located in the current directory are fast and the local
236       tag file can be quickly and easily regenerated in one second or less (I
237       have  even mapped a keystroke to do this easily). A lookup of a (neces‐
238       sarily non-static) tag found in another directory fails a lookup in the
239       local  tag  file,  but is found in the global tag file, which satisfies
240       all cross-directory lookups. The global tag file can  be  automatically
241       regenerated  periodically  with  a  cron job (and perhaps the local tag
242       files also).
243
244       Now I give an example of how you would implement Approach 3.  Means  of
245       implementing the other approaches can be performed in a similar manner.
246
247       Here is a visual representation of an example directory hierarchy:
248
249          project
250          `-----misccomp
251          |       `...
252          `-----sysint
253                  `-----client
254                  |       `-----hdrs
255                  |       `-----lib
256                  |       `-----src
257                  |       `-----test
258                  `-----common
259                  |       `-----hdrs
260                  |       `-----lib
261                  |       `-----src
262                  |       `-----test
263                  `-----server
264                          `-----hdrs
265                          `-----lib
266                          `-----src
267                          `-----test
268
269       Here is a recommended solution (conceptually) to build the tag files:
270
271       1. Within  each  of  the leaf nodes (i.e. hdrs, lib, src, test) build a
272          tag file using "ctags *.[ch]". This can be easily be  done  for  the
273          whole  hierarchy by making a shell script, call it dirtags, contain‐
274          ing the following lines:
275
276                 #!/bin/sh
277                 cd $1
278                 ctags *
279
280          Now execute the following command:
281
282                 find * -type d -exec dirtags {} \;
283
284          These tag files are trivial (and extremely quick) to  rebuild  while
285          making  changes within a directory. The following Vim key mapping is
286          quite useful to rebuild the tag file in the directory of the current
287          source file:
288
289                 :nmap ,t :!(cd %:p:h;ctags *.[ch])&<CR><CR>
290
291       2. Build the global tag file:
292
293                 cd ~/project
294                 ctags --file-scope=no -R
295
296          thus constructing a tag file containing only non-static tags for all
297          source files in all descendent directories.
298
299       3. Configure your editor to read the local tag file first, then consult
300          the  global  tag  file when not found in the local tag file. In Vim,
301          this is done as follows:
302
303                 :set tags=./tags,tags,~/project/tags
304
305       If you wish to implement Approach 4, you  would  need  to  replace  the
306       dirtags script of step 1 with the following:
307
308              #!/bin/sh
309              cd $1
310              ctags *
311              # Now append the non-static tags from descendent directories
312              find * -type d -prune -print | ctags -aR --file-scope=no -L-
313
314       And replace the configuration of step 3 with this:
315
316              :set tags=./tags;$HOME,tags
317
318       As  a  caveat,  it should be noted that step 2 builds a global tag file
319       whose file names will be relative to the directory in which the  global
320       tag  file  is  being built. This takes advantage of the Vim tagrelative
321       option, which causes the path to be interpreted a relative to the loca‐
322       tion of the tag file instead of the current directory. For standard vi,
323       which always interprets the paths as relative to the current directory,
324       we need to build the global tag file with absolute path names. This can
325       be accomplished by replacing step 2 with the following:
326
327              cd ~/project
328              ctags --file-scope=no -R `pwd`
329
330   Does Universal Ctags support Unicode file names?
331       Yes, Unicode file names are supported on  unix-like  platforms  (Linux,
332       macOS, Cygwin, etc.).
333
334       However,  on  Windows, you need to use Windows 10 version 1903 or later
335       to use Unicode file names. (This is an experimental  feature,  though.)
336       On  older  versions on Windows, Universal Ctags only support file names
337       represented in the current code page. If you still want to use  Unicode
338       file names on them, use Cygwin or MSYS2 version of Universal Ctags as a
339       workaround.
340
341   Why does zsh cause zsh: no matches found error?
342       zsh causes error on the following cases;
343
344              ctags --extra=+* ...
345              ctags --exclude=foo/* ...
346
347       This is the 2nd most significant incompatibility feature of zsh.
348
349       Cited from "Z-Shell Frequently-Asked Questions", "2.1: Differences from
350       sh and ksh";
351          ... The next most classic difference is that unmatched glob patterns
352          cause the command to abort; set NO_NOMATCH for those.
353
354       You may add "setopt nonomatch" on your ~/.zshrc. Or you can escape glob
355       patterns with backslash;
356
357              ctags --extra=+\* ...
358              ctags --exclude=foo/\* ...
359
360       Or quote them;
361
362              ctags '--extra=+*' ...
363              ctags '--exclude=foo/*' ...
364

SEE ALSO

366       The official Universal Ctags web site at:
367
368       https://ctags.io/
369
370       ctags(1), tags(5)
371

AUTHOR

373       This  FAQ  is  based  on  Exuberant  Ctags  FAQ  by  Darren Hiebert and
374       vberthoux@users.sourceforge.net
375
376       Universal Ctags project: https://ctags.io/
377
378
379
380
3816.0.0                                                             CTAGS-FAQ(7)
Impressum