Function: treemacs-filewatch-mode

treemacs-filewatch-mode is an interactive and byte-compiled function defined in treemacs-filewatch-mode.el.

Signature

(treemacs-filewatch-mode &optional ARG)

Documentation

Minor mode to let treemacs auto-refresh itself on file system changes.

Activating this mode enables treemacs to watch the files it is displaying (and only those) for changes and automatically refresh its view when it detects a change that it decides is relevant.

A file change event is relevant for treemacs if a new file has been created or deleted or a file has been changed and treemacs-git-mode(var)/treemacs-git-mode(fun) is enabled. Events caused by files that are ignored as per treemacs-ignored-file-predicates are counted as not relevant.

The refresh is not called immediately after an event was received, treemacs instead waits treemacs-file-event-delay ms to see if any more files have changed to avoid having to refresh multiple times over a short period of time.

Due to limitations in the underlying kqueue library this mode may not be able to track file modifications on MacOS, making it miss potentially useful updates when used in combination with treemacs-git-mode.

The watch mechanism only applies to directories opened *after* this mode has been activated. This means that to enable file watching in an already existing treemacs buffer it needs to be torn down and rebuilt by calling treemacs or treemacs-projectile.

Turning off this mode is, on the other hand, instantaneous - it will immediately turn off all existing file watch processes and outstanding refresh actions.

This is a global minor mode. If called interactively, toggle the Treemacs-Filewatch mode mode. If the prefix argument is positive, enable the mode, and if it is zero or negative, disable the mode.

If called from Lisp, toggle the mode if ARG is toggle. Enable the mode if ARG is nil, omitted, or is a positive number. Disable the mode if ARG is a negative number.

To check whether the minor mode is enabled in the current buffer, evaluate (default-value \=treemacs-filewatch-mode)'.

The mode's hook is called both when the mode is enabled and when it is disabled.

Key Bindings

Source Code

;; Defined in ~/.emacs.d/elpa/treemacs-20251226.1307/treemacs-filewatch-mode.el
(define-minor-mode treemacs-filewatch-mode
  "Minor mode to let treemacs auto-refresh itself on file system changes.
Activating this mode enables treemacs to watch the files it is displaying (and
only those) for changes and automatically refresh its view when it detects a
change that it decides is relevant.

A file change event is relevant for treemacs if a new file has been created or
deleted or a file has been changed and `treemacs-git-mode' is enabled.  Events
caused by files that are ignored as per `treemacs-ignored-file-predicates' are
counted as not relevant.

The refresh is not called immediately after an event was received, treemacs
instead waits `treemacs-file-event-delay' ms to see if any more files have
changed to avoid having to refresh multiple times over a short period of time.

Due to limitations in the underlying kqueue library this mode may not be able to
track file modifications on MacOS, making it miss potentially useful updates
when used in combination with `treemacs-git-mode.'

The watch mechanism only applies to directories opened *after* this mode has
been activated.  This means that to enable file watching in an already existing
treemacs buffer it needs to be torn down and rebuilt by calling `treemacs' or
`treemacs-projectile'.

Turning off this mode is, on the other hand, instantaneous - it will immediately
turn off all existing file watch processes and outstanding refresh actions."
  :init-value nil
  :global     t
  :lighter    nil
  :group      'treemacs
  (unless treemacs-filewatch-mode
    (treemacs--tear-down-filewatch-mode)))