Function: debug-on-variable-change

debug-on-variable-change is an autoloaded, interactive and byte-compiled function defined in debug.el.gz.

Signature

(debug-on-variable-change VARIABLE)

Documentation

Trigger a debugger invocation when VARIABLE is changed.

When called interactively, prompt for VARIABLE in the minibuffer.

This works by calling add-variable-watcher on VARIABLE. If you quit from the debugger, this will abort the change (unless the change is caused by the termination of a let-binding).

The watchpoint may be circumvented by C code that changes the variable directly (i.e., not via set). Changing the value of the variable (e.g., setcar on a list variable) will not trigger watchpoint.

Use M-x cancel-debug-on-variable-change (cancel-debug-on-variable-change) to cancel the effect of this command. Uninterning VARIABLE or making it an alias of another symbol also cancels it.

Probably introduced at or before Emacs version 26.1.

Key Bindings

Aliases

debug-watch

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/debug.el.gz
;;;###autoload
(defun debug-on-variable-change (variable)
  "Trigger a debugger invocation when VARIABLE is changed.

When called interactively, prompt for VARIABLE in the minibuffer.

This works by calling `add-variable-watcher' on VARIABLE.  If you
quit from the debugger, this will abort the change (unless the
change is caused by the termination of a let-binding).

The watchpoint may be circumvented by C code that changes the
variable directly (i.e., not via `set').  Changing the value of
the variable (e.g., `setcar' on a list variable) will not trigger
watchpoint.

Use \\[cancel-debug-on-variable-change] to cancel the effect of
this command.  Uninterning VARIABLE or making it an alias of
another symbol also cancels it."
  (interactive
   (let* ((var-at-point (variable-at-point))
          (var (and (symbolp var-at-point) var-at-point))
          (val (completing-read
                (format-prompt "Debug when setting variable" var)
                obarray #'boundp
                t nil nil (and var (symbol-name var)))))
     (list (if (equal val "") var (intern val)))))
  (add-variable-watcher variable #'debug--implement-debug-watch))