README.org

counsel-etags (v1.8.2)

Fast, energy-saving, and powerful code navigation solution.

It’s been tested on Linux/Windows/macOS.

Install

You can install counsel-etags from MELPA with package.el (M-x package-install git-gutter).

If “Exuberant Ctags” (some people prefer “Universal Ctags” because it’s more actively maintained) exists, this program works out of box.

“GNU Find” is used if it’s installed but it’s optional.

Or else, customize counsel-etags-update-tags-backend to create tags file with your own CLI.

Please note it’s reported “Exuberant Ctags” v5.8.5 is buggy.

Usage

Run M-x counsel-etags-find-tag-at-point to navigate in code files without any setup.

This command will:

• find project root folder and scan code automatically
• find correct tag automatically
• if no tag is find, it runs ripgrep or grep automatically

That’s it.

Please note parsing tags file containing line with 2K characters could be slow. That’s the known issue of Emacs Lisp. The program itself is perfectly fine.

If you prefer manually setup tags file. You only need run M-x counsel-etags-scan-code once or create tags file in your own way.

Tips (OPTIONAL)

Options file

Path of options file is defined in counsel-etags-ctags-options-file. Its default value is ~/.ctags.

Exuberant Ctags actually can NOT open option file “.ctags” through cli option.

But path ~/.ctags is OK because we use Emacs Lisp to load ~.ctags.

Please use file name like ctags.cnf instead .ctags when customize this variable.

Universal Ctags does NOT have this bug.

Ignore directories and files

You can setup counsel-etags-ignore-directories and counsel-etags-ignore-filenames,

(eval-after-load 'counsel-etags
  '(progn
     ;; counsel-etags-ignore-directories does NOT support wildcast
     (add-to-list 'counsel-etags-ignore-directories "build_clang")
     (add-to-list 'counsel-etags-ignore-directories "build_clang")
     ;; counsel-etags-ignore-filenames supports wildcast
     (add-to-list 'counsel-etags-ignore-filenames "TAGS")
     (add-to-list 'counsel-etags-ignore-filenames "*.json")))

Neither tags-file-name nor tags-table-list is used

Specify multiple tags files

counsel-etags-extra-tags-files contains extra tags file to parse.

Set it like (setq counsel-etags-extra-tags-files '("/usr/include/TAGS" "/usr/local/include/TAGS"))

Tags files in counsel-etags-extra-tags-files should contain only tag with absolute path.

Here is a shell CLI to create tags file:

find /usr/include | ctags -e -L -

Auto update tags file

;; Don't ask before rereading the TAGS files if they have changed
(setq tags-revert-without-query t)
;; Don't warn when TAGS files are large
(setq large-file-warning-threshold nil)
;; Setup auto update now
(add-hook 'prog-mode-hook
  (lambda ()
    (add-hook 'after-save-hook
              'counsel-etags-virtual-update-tags 'append 'local)))

You can change callback counsel-etags-update-tags-backend to update tags file using your own solution,

(setq counsel-etags-update-tags-backend (lambda () (shell-command "find . -type f -iname \"*.[ch]\" | etags -")))

List all tags

M-x counsel-etags-list-tag

Two-step tag matching using regular expression and filter

M-x counsel-etags-find-tag

Open recent tag

M-x counsel-etags-recent-tag

Ctags setup

Google “filetype:ctags site:github.com”. Here is mine.

You may need configure environment variable “HOME” on Windows because Ctags looks for “%HOME%/.ctags” by default.

Search with negative pattern

All counsel-etags commands supports negative pattern from ivy.

You can filter the candidates with keyword1 !keyword2 keyword3. So we display only candidate containing keyword1 but neither keyword2 nor keyword3.

You can also press C-c C-o to create a buffer containing all candidates.

In summary, all functionality from powerful ivy are supported perfectly.

Grep program

If ripgrep is installed, it’s used as faster grep program. Or else we fallback to grep.

You can use M-x counsel-etags-grep or M-x counsel-etags-grep-symbol-at-point to grep in current project.

Windows

No extra setup is needed if you install Cygwin to its default location on any driver except make sure “Exuberant Ctags” has been installed through Cygwin. Or else, you could setup counsel-etags-find-program, counsel-etags-tags-program, and counsel-etags-grep-program.

Bug Report

Check https://github.com/redguardtoo/counsel-etags.