HTAGS(1)

💖 HTAGS(1) 💖

okay bestie, sit down, because htags is literally the moment. it's a General Commands Manual page, section 1, and it's about to make your source code look gorgeous. 🦋

---

✨ NAME ✨

htags — generate a hypertext from a set of source files. no cap, that's the whole job. 🎀

---

🌸 SYNOPSIS 🌸

htags [-aDfFghInosTvw][-d dbpath][-m name][-t title][dir]

---

💅 DESCRIPTION 💅

so. htags generates a hypertext from a set of source files — and we're talking C, Yacc, Java, PHP and assembly. all of them. the whole squad. 💖

before you run this, you gotta run gtags(1) in the root directory of your source project first. that's the vibe check. then you run htags in the exact same place. htags makes a directory named HTML, drops the hypertext inside it, and you can start browsing at HTML/index.html. literally that easy. ✨

here's the tea: as long as you don't specify -D or -f, htags generates a static hypertext, which means you can move it anywhere and browse it with any browser — no HTTP server required, we love a low-maintenance queen. 👑

but if you use -D or -f, you DO need an HTTP server. any HTTP server works, but htags-server(1) is the recommended one. 🫶

ngl, this command has so many options. if you're new to htags, use --suggest — with that option, htags picks popular options on your behalf. it's giving "let the algorithm choose your outfit." 😭

---

🌈 OPTIONS 🌈

the following options are available:

• -a, --alphabet — make an alphabetical index suitable for a large project. big-project energy only. 📚
• --auto-completion[=limit] — enable the auto-completion facility for the input form. if limit is specified, the number of candidates is limited to that value. please note this function requires javascript language in your browser. ⚠️
• -C, --directory dir — change the directory before doing all the work including parameter analysis. yes, before the analysis. she's thorough. 💅
• --caution — display a caution message on the top page.
• --cflow cflowfile — add a call tree by cflow(1). cflowfile must be posix format. if you use GNU cflow, invoke the command at the project root directory with the --format=posix option. this option is deprecated; please use --call-tree or --callee-tree instead. 🚨
• --call-tree callfile — add a call tree by cflow(1); callfile must be posix format. if you use GNU cflow, invoke the command at the project root directory with the --format=posix option.
• --callee-tree calleefile — add a callee tree by cflow(1); calleefile must be posix format. if you use GNU cflow, invoke the command at the project root directory with the --format=posix and --reverse options.
• --colorize-warned-line — use color to highlight warned lines. aesthetic and functional. 🎨
• --cvsweb url — add a link to cvsweb; url is used as the base of URL. when directory CVS exists in the root directory of the project, the content of CVS/Repository is used as the relative path from the base.
• --cvsweb-cvsroot cvsroot — specify cvsroot in cvsweb URL.
• -D, --dynamic — generate a tag list dynamically using CGI program. though this option decreases both the size and generation time of hypertext, you need to start up HTTP server. 🖥️
• -d, --dbpath dbpath — specify the directory in which GTAGS exists. the default is the current directory.
• --disable-grep — disable grep in the search form (-f, --form).
• --disable-idutils — disable idutils in the search form (-f, --form).
• -F, --frame — use frames for the top page. (yes, frames. retro icon behavior. 👵)
• -f, --form — add a search form using CGI program. you need to start a HTTP server for it.
• --fixed-guide — put a fixed guide at the bottom of the screen of the browser.
• --full-path — use full path name in the file index. by default, use just the last component of a path.
• -g, --gtags — execute gtags(1) before starting job. the -v, -w and dbpath options are passed to gtags.
• --gtagsconf file — set environment variable GTAGSCONF to file.
• --gtagslabel label — set environment variable GTAGSLABEL to label.
• -h, --func-header[=position] — insert a function header for each function. by default, htags doesn't generate them. you can choose the position using position, which allows one of before, right or after (default).
• --help — print a usage message.
• --html-header file — insert a header record derived from file into the HTML header of each file.
• -I, --icon — use icons instead of text for some links. 🎀
• --insert-footer file — insert custom footer derived from file before </body> tag.
• --insert-header file — insert custom header derived from file after <body> tag.
• --item-order spec — specify the order of the items in the top page. the spec is a string consisting of item signs in order. each sign means as follows: c: caution; s: search form; m: mains; d: definitions; f: files; t: call tree. the default is csmdf.
• -m, --main-func name — specify startup function name; the default is main.
• --map-file — generate file MAP.
• -n, --line-number[=columns] — print line numbers. by default, don't print line numbers. the default value of columns is 4.
• --no-order-list — numbers are not given in list form.
• -o, --other — pick up not only source files but also other files for the file index.
• -s, --symbol — make anchors not only for definitions and references but also other symbols.
• --show-position — print the position string per function definition. the string can be interpreted by general editors in UNIX. the default is false.
• --statistics — print statistics information.
• --suggest — htags chooses popular options on behalf of beginners. it is equivalent to -aghInosTxv --show-position --fixed-guide now.
• --suggest2 — htags chooses popular options on behalf of beginners. this option enables frame, AJAX and CGI facility in addition to the facilities by the --suggest option. it is equivalent to --suggest -DfF --auto-completion --tree-view=filetree now. 🔥
• -T, --table-flist[=rows] — use <table> tag to display the file index. you can optionally specify the number of rows; the default is 5.
• -t, --title title — title of the hypertext. the default is the last component of the path of the current directory.
• --tabs cols — tab stops. the default is 8.
• --table-list — use <table> tag to display the tag list.
• --tree-view[=type] — use treeview for the file index. please note this function requires javascript language in your browser. possible values of type are as follows: treeview, filetree, treeview-red, treeview-black, treeview-gray, treeview-famfamfam. the default is treeview. 🌳
• -v, --verbose — verbose mode.
• --version — show version number.
• -w, --warning — print warning messages.
• dir — the directory in which the result of this command is stored. the default is the current directory.

---

⭐ EXAMPLES ⭐

like, actual receipts:

$ gtags -v
$ htags -sanohITvt 'Welcome to XXX source tour!'
$ firefox HTML/index.html

$ htags --suggest2
$ htags-server >& log &
$ firefox http://127.0.0.1:8000

---

🧚 FILES 🧚

the whole cast of characters:

• GTAGS — tag file for definitions.
• GRTAGS — tag file for references.
• GPATH — tag file for source files.
• gtags.conf, $HOME/.globalrc — configuration data for GNU Global. see gtags.conf(5).
• HTML/FILEMAP — mapping file for converting file name into the path of the file.
• HTML/GTAGSROOT — if this file exists, CGI program global.cgi sets environment variable GTAGSROOT to the contents of it. if you move directory HTML from the original place, please make this file. 🙈
• HTML/.htaccess — local configuration file for Apache. this file is generated when the -f or -D options are specified.
• HTML/index.html — start-up file.
• HTML/MAP — mapping file for converting tag name into the path of tag list.
• HTML/style.css — style sheet file.
• /usr/local/share/gtags/style.css.tmpl — the template of the style sheet file (HTML/style.css).

---

🦋 ENVIRONMENT 🦋

the following environment variables affect the execution of htags:

• GTAGSCACHE — the size of the B-tree cache. the default is 50000000 (bytes).
• GTAGSCONF — configuration file.
• GTAGSLABEL — configuration label. the default is default.
• HTAGS_OPTIONS — the value of this variable is inserted in the head of arguments. ✨
• TMPDIR — the location used to stored temporary files. the default is /tmp.
• GTAGSFORCECPP — if this variable is set, each file whose suffix is .h is treated as a C++ source file. plot twist! 😳

---

💜 CONFIGURATION 💜

the following configuration variables affect the execution of htags:

• datadir (string) — shared data directory. the default is /usr/local/share but you can change the value using configure script. htags looks up template files in the gtags directory in this data directory.
• include_file_suffixes (comma separated list) — suffixes of include files. the default is: h,hh,hxx,hpp,H,inc.php.
• langmap (comma separated list) — language mapping. each comma-separated map consists of the language name, a colon, and a list of file extensions. default mapping is: c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml.

---

😭 DIAGNOSTICS 😭

htags exits with a non-0 value if an error occurred, 0 otherwise. simple as that. ✌️

---

🔥 SEE ALSO 🔥

htags-server(1), global(1), gtags(1), gtags.conf(5).

GNU Global source code tag system (http://www.gnu.org/software/global/).

---

💀 BUG 💀

okay this is the serious part, bestie, listen up:

• generated hypertext is VERY LARGE. in advance, check the space of your disk. like, fr fr, check it. 💾
• PHP support is far from complete. 🙃
• the -f and -D options generate CGI programs. if you open the hypertext to the public, please recognize security dangers. 🚨
• htags does not support plug-in parser.

---

👑 AUTHOR 👑

Shigio YAMAGUCHI, Hideki IWAMOTO and others. icons, all of them. 💖

---

🌈 HISTORY 🌈

the htags command appeared in FreeBSD 2.2.2. a true legend since day one. 🎀

---

and that's the whole page, bestie 🫶 — this one came out of the GNU Project, dated June 2013, filed under HTAGS(1). go forth and generate that hypertext, you absolute main character. 💅✨🍓