Home

Awesome

<p align="center"> <img src="./img/logo.svg" alt="logo"> </p> <p align="center"><i>Ctags IDE on the True Editor!</i></p> <p align="center">(Or, a superior code reading & auto-completion tool with pluggable backends.)</p>

What is it?

(If you are already familiar with Citre, see changelog for the news.)

Citre started out as a tool utilizing tags files (in the ctags format). Now it is a superior code reading and auto-completion tool with pluggable backend design. The built-in backends include:

The tools offered by Citre are:

Let's see them in action!

All above screenshots were taken in a huge project (the Linux kernel), using the tags file backend, and Citre is still fast, because readtags performes binary search on the tags file.

Quick start

Installation

You can install citre from MELPA. Below are instructions to install Citre manually.

  1. Clone this repository:

    $ git clone https://github.com/universal-ctags/citre.git /path/to/citre
    
  2. Add the path to your load-path in your Emacs configuration:

    (add-to-list 'load-path "/path/to/citre")
    
  3. Require citre and citre-config in your configuration:

    (require 'citre)
    (require 'citre-config)
    

    Or, you can read citre-config.el, and write your own config.

Pick a backend

Here's a comparison of their capabilities:

BackendAuto-completionFind definitionFind referencesImenu
Tags
Global
Eglot[1]✓[2]✓[2]

[1]: Auto-completion is handled by eglot itself.

[2]: Eglot backend doesn't support finding definition or references of an user inputted symbol.

Pick a backend, and read its "getting started" documentation:

You don't have to use only one backend. For example, you can use tags backend for finding definitions, eglot backend for finding references with global backend as a fallback. We'll show you how this works in the configuration section later.

Below is a brief discussion of the backends. If you still don't have an idea after reading it, I would recommended tags backend as it's fast, easy to use, and fulfills most of the needs.

Tags

Tags file (in ctags format) is a widely adopted text format for source code indexing. The best tags file generating tool is Universal Ctags. The advantages of the Citre tags backend & Universal Ctags combination are:

The disadvantages are:

Global

This is based on GNU Global, another source code indexing tool. Its advantages are:

The disadvantages are:

Eglot

This is based on Eglot, a language server client now built into Emacs. Its advantages are:

Its disadvantages are:

Use Citre

citre-mode

Use citre-mode to enable completion-at-point, xref and imenu integration. If you also use company, make sure company-capf is in company-backends.

When you open a file, Citre asks the backends if they can work (like if the tags backend cound find a tags file). If any of them can work, citre-mode is automatically enabled. If you don't use citre-config, you can put this in your configuration:

(add-hook 'find-file-hook #'citre-auto-enable-citre-mode)

citre-jump and citre-peek

Other tools provided by citre, citre-jump and citre-peek, doesn't need citre-mode enabled to work. These are all citre-jump commands:

For citre-peek, see Use Citre Peek to know how to use it.

Configuration

Here's an example configuration using use-package. Be sure to tweak it to your own need.

(use-package citre
  :defer t
  :init
  ;; This is needed in `:init' block for lazy load to work.
  (require 'citre-config)
  ;; Bind your frequently used commands.  Alternatively, you can define them
  ;; in `citre-mode-map' so you can only use them when `citre-mode' is enabled.
  (global-set-key (kbd "C-x c j") 'citre-jump)
  (global-set-key (kbd "C-x c J") 'citre-jump-back)
  (global-set-key (kbd "C-x c p") 'citre-ace-peek)
  (global-set-key (kbd "C-x c u") 'citre-update-this-tags-file)
  :config
  (setq
   ;; Set these if readtags/ctags is not in your PATH.
   citre-readtags-program "/path/to/readtags"
   citre-ctags-program "/path/to/ctags"
   ;; Set these if gtags/global is not in your PATH (and you want to use the
   ;; global backend)
   citre-gtags-program "/path/to/gtags"
   citre-global-program "/path/to/global"
   ;; Set this if you use project management plugin like projectile.  It's
   ;; used for things like displaying paths relatively, see its docstring.
   citre-project-root-function #'projectile-project-root
   ;; Set this if you want to always use one location to create a tags file.
   citre-default-create-tags-file-location 'global-cache
   ;; Set this if you'd like to use ctags options generated by Citre
   ;; directly, rather than further editing them.
   citre-edit-ctags-options-manually nil
   ;; If you only want the auto enabling citre-mode behavior to work for
   ;; certain modes (like `prog-mode'), set it like this.
   citre-auto-enable-citre-mode-modes '(prog-mode)))

These user options are for customizing enabled backends:

Each is a list that's tried in turn when Citre is doing things. For example, when finding definitions, backends in citre-find-definition-backends are tried in turn until one succeeded. See their docstrings to learn more. Normally you don't need to modify them.

Documentations

Note that the user manual doesn't cover all aspects of Citre. To learn more, use M-x customize-group to see all customizable options of Citre, and M-x describe-command to know all commands of Citre.

FAQ

Donation

If Citre makes you happy, please consider buying me (@AmaiKinono) a beer to make me happy ;)