{"id":13570958,"url":"https://github.com/universal-ctags/citre","last_synced_at":"2025-04-04T07:32:32.330Z","repository":{"id":38413593,"uuid":"239525297","full_name":"universal-ctags/citre","owner":"universal-ctags","description":"A superior code reading \u0026 auto-completion tool with pluggable backends.","archived":false,"fork":false,"pushed_at":"2024-10-28T15:52:55.000Z","size":2012,"stargazers_count":337,"open_issues_count":17,"forks_count":26,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-05T03:36:57.008Z","etag":null,"topics":["code-completion","ctags","emacs","emacs-lisp","lsp"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/universal-ctags.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-10T14:00:57.000Z","updated_at":"2024-10-28T15:52:59.000Z","dependencies_parsed_at":"2023-12-31T15:31:22.936Z","dependency_job_id":"ae9ba4f9-2d75-4a53-92b6-bb0672e80b70","html_url":"https://github.com/universal-ctags/citre","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-ctags%2Fcitre","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-ctags%2Fcitre/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-ctags%2Fcitre/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-ctags%2Fcitre/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/universal-ctags","download_url":"https://codeload.github.com/universal-ctags/citre/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247139220,"owners_count":20890190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-completion","ctags","emacs","emacs-lisp","lsp"],"created_at":"2024-08-01T14:00:56.872Z","updated_at":"2025-04-04T07:32:27.322Z","avatar_url":"https://github.com/universal-ctags.png","language":"Emacs Lisp","funding_links":["https://www.buymeacoffee.com/amaikinono"],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./img/logo.svg\" alt=\"logo\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ci\u003eCtags IDE on the True Editor!\u003c/i\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e(Or, a superior code reading \u0026 auto-completion tool with\npluggable backends.)\u003c/p\u003e\n\n## What is it?\n\n(If you are already familiar with Citre, see [changelog](CHANGELOG.md) for the\nnews.)\n\nCitre started out as a tool utilizing tags files (in the ctags format). Now it\nis a superior code reading and auto-completion tool with pluggable backend\ndesign. The built-in backends include:\n\n- A tags file (in ctags format) backend.\n- A GNU global backend.\n- An xref adapter that transforms any xref backend into Citre backend.\n- Eglot backend, based on the xref adapter.\n\nThe tools offered by Citre are:\n\n- `completion-at-point`, xref and imenu integration.\n- `citre-jump`: A `completing-read` UI for jumping to definition/references.\n- `citre-peek`: A powerful code reading tool that lets you go down the rabbit\n  hole without leaving current buffer.\n\nLet's see them in action!\n\n- `completion-at-point`, with the UI of\n  [company](https://company-mode.github.io/) and\n  [Vertico](https://github.com/minad/vertico):\n\n  ![capf](./img/capf.jpg)\n\n  Notice the rich annotations. Candidates are annotated by `(kind/type@scope)`,\n  so you know \"it's a member of struct `thread`, with `pid_t` type\", etc. This\n  is because Ctags \"tags\" format records much more abundant info than the etags\n  \"TAGS\" format.\n\n  Also, notice that candidates with \"member\" kind are put above the others\n  because we are in a C source file, and the current symbol is after a dot.\n  Citre guesses that you want a struct member (but completiong won't be\n  available just after typing a dot, due to limitations of all tagging\n  systems).\n\n- `citre-jump`, with `completing-read` UI provided by\n  [Selectrum](https://github.com/raxod502/selectrum):\n\n  ![citre-jump](./img/citre-jump.jpg)\n\n- `citre-peek`. It opens a \"peek window\" to show the definition of a symbol:\n\n  ![citre-peek](./img/citre-peek.jpg)\n\n  And there's more. Notice the code reading history at the bottom of the peek\n  window. Do you hate having to switch between a lot of buffers while reading\n  code? With `citre-peek`, you can peek a symbol in the peek window. This\n  allows a tree-like code reading history, that you can browse and edit,\n  without leaving current buffer!\n\nAll above screenshots were taken in a huge project (the Linux kernel), using\nthe tags file backend, and Citre is still fast, because readtags performes\nbinary search on the tags file.\n\n## Quick start\n\n### Installation\n\nYou can install `citre` from [MELPA](https://melpa.org). Below are instructions\nto install Citre manually.\n\n1. Clone this repository:\n\n   ```console\n   $ git clone https://github.com/universal-ctags/citre.git /path/to/citre\n   ```\n\n2. Add the path to your `load-path` in your Emacs configuration:\n\n   ```elisp\n   (add-to-list 'load-path \"/path/to/citre\")\n   ```\n\n3. Require `citre` and `citre-config` in your configuration:\n\n   ```elisp\n   (require 'citre)\n   (require 'citre-config)\n   ```\n\n   Or, you can read [citre-config.el](citre-config.el), and write your own\n   config.\n\n### Pick a backend\n\nHere's a comparison of their capabilities:\n\n| Backend | Auto-completion | Find definition | Find references | Imenu |\n|---------|-----------------|-----------------|-----------------|-------|\n| Tags    | ✓               | ✓               |                 | ✓     |\n| Global  | ✓               | ✓               | ✓               | ✓     |\n| Eglot   | [1]             | ✓[2]            | ✓[2]            |       |\n\n[1]: Auto-completion is handled by eglot itself.\n\n[2]: Eglot backend doesn't support finding definition or references of an user\n    inputted symbol.\n\nPick a backend, and read its \"getting started\" documentation:\n\n- Tags: [Getting Started on Tags\n  Backend](docs/user-manual/getting-started-on-tags-backend.md)\n- Global: [Use Global Backend](docs/user-manual/use-global-backend.md)\n- Eglot: [Use Eglot Backend](docs/user-manual/use-eglot-backend.md)\n\nYou don't have to use only one backend. For example, you can use tags backend\nfor finding definitions, eglot backend for finding references with global\nbackend as a fallback. We'll show you how this works in the configuration\nsection later.\n\nBelow is a brief discussion of the backends. If you still don't have an idea\nafter reading it, I would recommended tags backend as it's fast, easy to use,\nand fulfills most of the needs.\n\n#### Tags\n\nTags file (in ctags format) is a widely adopted text format for source code\nindexing. The best tags file generating tool is [Universal\nCtags](https://github.com/universal-ctags/ctags). The advantages of the Citre\ntags backend \u0026 Universal Ctags combination are:\n\n- Supports many, many languages (157 by now!), and works great in a\n  multi-language project. Many markup languages are also supported so you could\n  even use it to browse your personal notes.\n- The tags file contains abundant information, which enables a more informative\n  UI, and Citre uses them to further filter the tags.\n- Lines in the tags file are sorted so we can use binary search, and you'll\n  feel super fast when finding definitions/completions.\n\nThe disadvantages are:\n\n- Is not as accurate as a language server. Think of it as a fuzzy finder.\n- Doesn't support finding references for now.\n- Tags file doesn't support incremental updating.\n\n#### Global\n\nThis is based on [GNU Global](https://www.gnu.org/software/global/), another\nsource code indexing tool. Its advantages are:\n\n- Supports finding references.\n- Uses a compact binary database format, and supports incremental updating.\n\nThe disadvantages are:\n\n- Not as accurate as a language server.\n- Supports only 5 languages. But this can be saved by using Universal Ctags \u0026\n  pygments as plugin parsers.\n- The database only contains brief information, so the UI and filtering is not\n  as good as the tags backend.\n\n#### Eglot\n\nThis is based on [Eglot](https://github.com/joaotavora/eglot), a language\nserver client now built into Emacs. Its advantages are:\n\n- Finds definition/references accurately.\n\nIts disadvantages are:\n\n- You need to install a language server for each language you use.\n- For dynamic languages, sometimes it may fail to find a definition/reference.\n- Some language servers can be slow and heavy on CPU/memory.\n\n### Use Citre\n\n#### `citre-mode`\n\nUse `citre-mode` to enable `completion-at-point`, xref and imenu integration.\nIf you also use `company`, make sure `company-capf` is in `company-backends`.\n\nWhen you open a file, Citre asks the backends if they can work (like if the\ntags backend cound find a tags file). If any of them can work, `citre-mode` is\nautomatically enabled. If you don't use `citre-config`, you can put this in\nyour configuration:\n\n``` elisp\n(add-hook 'find-file-hook #'citre-auto-enable-citre-mode)\n```\n\n#### `citre-jump` and `citre-peek`\n\nOther tools provided by citre, `citre-jump` and `citre-peek`, doesn't need\n`citre-mode` enabled to work. These are all `citre-jump` commands:\n\n- `citre-jump` and `citre-jump-to-reference`: Jump to definition or references\n  of symbol at point.\n- `citre-query-jump` and `citre-query-jump-to-reference`: Jump to definition or\n  references of a user inputted symbol. When called with a prefix argument, the\n  identifiers in the project is used as completion for your input, if the\n  backend supports it.\n\nFor `citre-peek`, see [Use Citre Peek](docs/user-manual/use-citre-peek.md) to\nknow how to use it.\n\n### Configuration\n\nHere's an example configuration using\n[`use-package`](https://github.com/jwiegley/use-package). Be sure to tweak it\nto your own need.\n\n``` elisp\n(use-package citre\n  :defer t\n  :init\n  ;; This is needed in `:init' block for lazy load to work.\n  (require 'citre-config)\n  ;; Bind your frequently used commands.  Alternatively, you can define them\n  ;; in `citre-mode-map' so you can only use them when `citre-mode' is enabled.\n  (global-set-key (kbd \"C-x c j\") 'citre-jump)\n  (global-set-key (kbd \"C-x c J\") 'citre-jump-back)\n  (global-set-key (kbd \"C-x c p\") 'citre-ace-peek)\n  (global-set-key (kbd \"C-x c u\") 'citre-update-this-tags-file)\n  :config\n  (setq\n   ;; Set these if readtags/ctags is not in your PATH.\n   citre-readtags-program \"/path/to/readtags\"\n   citre-ctags-program \"/path/to/ctags\"\n   ;; Set these if gtags/global is not in your PATH (and you want to use the\n   ;; global backend)\n   citre-gtags-program \"/path/to/gtags\"\n   citre-global-program \"/path/to/global\"\n   ;; Set this if you use project management plugin like projectile.  It's\n   ;; used for things like displaying paths relatively, see its docstring.\n   citre-project-root-function #'projectile-project-root\n   ;; Set this if you want to always use one location to create a tags file.\n   citre-default-create-tags-file-location 'global-cache\n   ;; Set this if you'd like to use ctags options generated by Citre\n   ;; directly, rather than further editing them.\n   citre-edit-ctags-options-manually nil\n   ;; If you only want the auto enabling citre-mode behavior to work for\n   ;; certain modes (like `prog-mode'), set it like this.\n   citre-auto-enable-citre-mode-modes '(prog-mode)))\n```\n\nThese user options are for customizing enabled backends:\n\n- `citre-completion-backends`\n- `citre-find-definition-backends`\n- `citre-find-reference-backends`\n- `citre-tags-in-buffer-backends`\n- `citre-identifier-list-backends`\n- `citre-auto-enable-citre-mode-backends`\n\nEach is a list that's tried in turn when Citre is doing things. For example,\nwhen finding definitions, backends in `citre-find-definition-backends` are\ntried in turn until one succeeded. See their docstrings to learn more. Normally\nyou don't need to modify them.\n\n## Documentations\n\n- [User Manual](docs/user-manual/toc.md)\n- [Developer Manual](docs/developer-manual/toc.md)\n- [Wiki](https://github.com/universal-ctags/citre/wiki)\n\nNote that the user manual doesn't cover all aspects of Citre. To learn more,\nuse `M-x customize-group` to see all customizable options of Citre, and `M-x\ndescribe-command` to know all commands of Citre.\n\n## FAQ\n\n- Q: How to use Citre over TRAMP?\n\n  A: I don't have a remote machine to test, so I can't guarantee Citre will\n  work over TRAMP. But I've written the code with TRAMP in mind, and for now,\n  tags and global backends seem to work over TRAMP if you've installed required\n  executables (readtags, global) on the remote machine. If anything goes wrong,\n  it shouldn't be hard to fix.\n\n  For eglot backend, I've not tried. I think you need to make eglot works over\n  TRAMP, and the eglot backend will just work.\n\n- Q: Why does `xref-find-reference` prompts me for a symbol, rather than pick\n  the symbol at point?\n\n  A: By default, `xref-find-references` always prompts you to choose an\n  identifier from a list. You could set `xref-prompt-for-identifier` to `nil`\n  to make it use the symbol at point instead. See its docstring for more\n  details.\n\n- Q: What to do if Citre didn't grab the right symbol for me, e.g., I want to\n  find the definition of `foo.bar`, but can only get `foo` or `bar`?\n\n  A: For tags and global backends, you can select `foo.bar` first (by an active\n  region), then find its definitions.\n\n- Q: Why doesn't Citre support automatically update tags file?\n\n  A: Citre uses both line number and a search pattern to locate a tag. When the\n  file containing the tag is edited, Citre could still locate the tag using the\n  search pattern. Citre even tries to locate the tag when the line containing\n  the tag itself is edited.\n\n  So, jumping to definition is still useable when the file is edited. There's\n  no need to frequently update the tags file.\n\n  You may ask \"what if I add new definitions, or modify/delete existing ones?\"\n  The truth is, if your codebase is reasonably large that you have to index\n  them by Ctags, then small edits won't cause much trouble. You can just\n  update the tags file when needed.\n\n- Q: Citre freezes Emacs when opening a file on Windows.\n- A: I'm not 100% sure about the cause, but seems some anti-virus softwares\n  consider the way Citre communicates with external programs to be suspicious\n  (see [this\n  report](https://github.com/universal-ctags/citre/issues/163#issuecomment-1893801573)).\n  Try adding Emacs and the program Citre uses (readtags and global) to the\n  whitelist and see if it's solved.\n\n## Donation\n\nIf Citre makes you happy, please consider buying me (@AmaiKinono) a beer to\nmake me happy ;)\n\n- by Alipay\n\n  \u003cimg src=\"./img/alipay.jpg\" alt=\"Alipay\" width=\"180\" /\u003e\n\n- by Wechat Pay\n\n  \u003cimg src=\"./img/wechat-pay.png\" alt=\"Wechat Pay\" width=\"180\" /\u003e\n\n- by [Buy me a coffee](https://www.buymeacoffee.com/amaikinono)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funiversal-ctags%2Fcitre","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funiversal-ctags%2Fcitre","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funiversal-ctags%2Fcitre/lists"}