Variable: cider-xref-references-mode

cider-xref-references-mode is a customizable variable defined in cider-xref-backend.el.

Value

source

Documentation

How xref-find-references (M-? (xref-find-references)) gathers references.

CIDER can find references two ways, and they answer different questions. The source search scans the project's files on disk (see cider-xref-source), so it covers code that hasn't been evaluated yet and pinpoints every exact occurrence, at the cost of some false positives - this is the natural fit for xref, which is occurrence-oriented. The runtime search (the cider/fn-refs op) introspects the REPL, so it is limited to Clojure on the JVM and to loaded project namespaces, and reports the calling functions (each hit points at the caller's definition, not the call site).

The value selects which of the two run:

  source - source matches only (the default).
  runtime - runtime references only (the historical behavior).
  both - both, combined.

In both mode the source matches lead, and runtime hits for files the source search already scanned are dropped (they would only duplicate the precise occurrences at a coarser granularity). What survives is mainly references the compiler generated from macros, which leave no textual trace for the scan.

When source is selected but the buffer isn't inside a project (so there are no files to scan), CIDER falls back to the runtime search if a REPL is connected, rather than reporting no references.

This variable was added, or its default value changed, in cider version 2.0.0.

Source Code

;; Defined in ~/.emacs.d/elpa/cider-20260822.1520/cider-xref-backend.el
(defcustom cider-xref-references-mode 'source
  "How `xref-find-references' (\\[xref-find-references]) gathers references.
CIDER can find references two ways, and they answer different questions.  The
source search scans the project's files on disk (see `cider-xref-source'), so it
covers code that hasn't been evaluated yet and pinpoints every exact occurrence,
at the cost of some false positives - this is the natural fit for xref, which is
occurrence-oriented.  The runtime search (the `cider/fn-refs' op) introspects
the REPL, so it is limited to Clojure on the JVM and to loaded project
namespaces, and reports the calling functions (each hit points at the caller's
definition, not the call site).

The value selects which of the two run:

  source  - source matches only (the default).
  runtime - runtime references only (the historical behavior).
  both    - both, combined.

In `both' mode the source matches lead, and runtime hits for files the source
search already scanned are dropped (they would only duplicate the precise
occurrences at a coarser granularity).  What survives is mainly references the
compiler generated from macros, which leave no textual trace for the scan.

When `source' is selected but the buffer isn't inside a project (so there are
no files to scan), CIDER falls back to the runtime search if a REPL is
connected, rather than reporting no references."
  :type '(choice (const :tag "Source matches only" source)
                 (const :tag "Runtime references only" runtime)
                 (const :tag "Runtime and source matches combined" both))
  :group 'cider
  :package-version '(cider . "2.0.0"))