Emacs integration for tagref, a tool for managing cross-references in code.

Tagref helps you maintain cross-references in your codebase using simple tags:

• [tag:name] defines a tag
• [ref:name] references a tag

This package provides Emacs support for working with these directives:

• Completion for [ref:] and [tag:] with existing tag names
• Navigation via M-. to jump from a reference to its tag definition, and M-? to find all references of a tag
• Validation via M-x tagref-check with clickable error locations
• Browsing via M-x tagref-list-tags to see all tags in the project

• Emacs 28.1 or later
• tagref CLI installed and available in your PATH

(add-to-list 'load-path "/path/to/tagref.el")
(require 'tagref)

(use-package tagref
  :ensure t
  :hook (prog-mode . tagref-mode))

(straight-use-package
 '(tagref :type git
          :host github
          :repo "vedang/tagref.el"))

Enable tagref-mode in any buffer:

M-x tagref-mode

tagref-mode understands projects as defined by project.el and will be turned on for all buffers of that project.

When tagref-mode is active, type [ref: or [tag: and invoke completion:

Completions show the tag name with its file location:

polynomial_nonzero    src/math.rs:42
path_default          src/main.rs:93

Smart conversion: When completing [tag: and you select an existing tag, the directive is automatically converted to [ref: to prevent duplicates.

Navigate between references and their definitions using standard xref keys:

Place your cursor inside a [ref:name] and press M-. to jump to where the tag is defined.

When on a [tag:name], press M-? to find all references. The results include the tag definition as the first entry for context. If there are no references, a message is shown.

Run tagref’s validation to find broken references:

M-x tagref-check

This opens a compilation buffer with any errors. Click on an error (or press RET) to jump to that location.

Standard compilation-mode keys work:

Browse all tags in the project:

M-x tagref-list-tags

This shows a sortable table of all tags:

Tag                                      File                                               Line
polynomial_nonzero                       src/math.rs                                        42
path_default                             src/main.rs                                        93
tag_sigil_default                        src/main.rs                                        103

;; Path to tagref executable (default: "tagref")
(setq tagref-executable "/path/to/tagref")

;; Additional arguments for tagref commands
(setq tagref-arguments '("--config" "custom.toml"))

M-x customize-group RET tagref RET

make test    # Run Buttercup test suite
make check   # Run byte-compile, checkdoc, package-lint
make all     # Run everything

├── Makefile           # Build and test commands
├── README.org         # This file
├── tagref.el          # Main package
└── test/
    └── tagref-test.el # Buttercup tests

1. Verify tagref-mode is active: Check for ” Tagref” in the mode line.
2. Verify tagref CLI works: Run M-x tagref-list-tags to see if tags are found. If this shows no tags, check that tagref is in your PATH.
3. Check CAPF is registered:

   (member 'tagref-completion-at-point completion-at-point-functions)
       

4. With Corfu/Company: Completion should trigger automatically when you type ​[ref: or ​[tag:. If not, manually invoke with C-M-i or M-TAB.
5. Debug the CAPF: Evaluate this with point inside a ​[ref: directive:

   (tagref-completion-at-point)
       

   It should return a list like (START END CANDIDATES ...).

The error regexp matches the format @ path/to/file:42. If your errors aren’t clickable, check that tagref output matches this format.

The package calls tagref list-tags on each completion. For very large projects, this may cause a delay. Consider:

• Increasing corfu-auto-delay if using Corfu
• Using M-x tagref-list-tags to browse tags instead

GPL-3.0-or-later. See the source file for details.