Variable: projectile-auto-update-cache-with-watches

projectile-auto-update-cache-with-watches is a customizable variable defined in projectile.el.

Value

nil

Documentation

When non-nil, watch project directories to keep the files cache fresh.

Experimental. When enabled (and projectile-enable-caching is non-nil), Projectile registers filesystem notification watches (via file-notify-add-watch) for the directories of a project whenever the project's file list is cached. Files created, deleted or renamed outside Emacs then update the cached file list automatically, largely removing the need for manual projectile-invalidate-cache calls.

Emacs file notifications are not recursive, so this costs one watch per directory; projects spanning more directories than projectile-watch-directory-limit are not watched. Remote (TRAMP) projects are never watched. When an event cannot be applied incrementally the project's cache is invalidated instead and rebuilt lazily on the next file listing, which also re-arms the watches.

Change this via Customize (or setopt): disabling it then drops all active watches immediately, and enabling it arms watches for the projects that are already cached. With plain setq the new value only takes effect the next time a project's file list is cached.

This variable was added, or its default value changed, in projectile version 3.1.0.

Source Code

;; Defined in ~/.emacs.d/elpa/projectile-20260820.1509/projectile.el
(defcustom projectile-auto-update-cache-with-watches nil
  "When non-nil, watch project directories to keep the files cache fresh.

Experimental.  When enabled (and `projectile-enable-caching' is
non-nil), Projectile registers filesystem notification watches (via
`file-notify-add-watch') for the directories of a project whenever the
project's file list is cached.  Files created, deleted or renamed
outside Emacs then update the cached file list automatically, largely
removing the need for manual `projectile-invalidate-cache' calls.

Emacs file notifications are not recursive, so this costs one watch per
directory; projects spanning more directories than
`projectile-watch-directory-limit' are not watched.  Remote (TRAMP)
projects are never watched.  When an event cannot be applied
incrementally the project's cache is invalidated instead and rebuilt
lazily on the next file listing, which also re-arms the watches.

Change this via Customize (or `setopt'): disabling it then drops all
active watches immediately, and enabling it arms watches for the
projects that are already cached.  With plain `setq' the new value only
takes effect the next time a project's file list is cached."
  :group 'projectile
  :type 'boolean
  :set (lambda (symbol value)
         (set-default symbol value)
         ;; The watch machinery is defined further down in this file, so
         ;; guard against the initial `defcustom' evaluation at load time.
         (if value
             ;; Only arm watches when the mode is on; otherwise they'd have no
             ;; mode-disable teardown to fire and would linger until Emacs exits.
             (when (and (bound-and-true-p projectile-mode)
                        (fboundp 'projectile--watch-all-cached-projects))
               (projectile--watch-all-cached-projects))
           (when (fboundp 'projectile--teardown-all-watches)
             (projectile--teardown-all-watches))))
  :package-version '(projectile . "3.1.0"))