lisp/autorevert.el

   1 ;;; autorevert.el --- revert buffers when files on disk change
   2
   3 ;; Copyright (C) 1997, 1998, 1999, 2001 Free Software Foundation, Inc.
   4
   5 ;; Author: Anders Lindgren <andersl@andersl.com>
   6 ;; Keywords: convenience
   7 ;; Created: 1997-06-01
   8 ;; Date: 1999-11-30
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software; you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation; either version 2, or (at your option)
  15 ;; any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  25 ;; Boston, MA 02111-1307, USA.
  26
  27 ;;; Commentary:
  28
  29 ;; Introduction:
  30 ;;
  31 ;; Whenever a file that Emacs is editing has been changed by another
  32 ;; program the user normally has to execute the command `revert-buffer'
  33 ;; to load the new content of the file into Emacs.
  34 ;;
  35 ;; This package contains two minor modes: Global Auto-Revert Mode and
  36 ;; Auto-Revert Mode.  Both modes automatically revert buffers
  37 ;; whenever the corresponding files have been changed on disk.
  38 ;;
  39 ;; Auto-Revert Mode can be activated for individual buffers.
  40 ;; Global Auto-Revert Mode applies to all file buffers.
  41 ;;
  42 ;; Both modes operate by checking the time stamp of all files at
  43 ;; intervals of `auto-revert-interval'.  The default is every five
  44 ;; seconds.  The check is aborted whenever the user actually uses
  45 ;; Emacs.  You should never even notice that this package is active
  46 ;; (except that your buffers will be reverted, of course).
  47 ;;
  48 ;; After reverting a file buffer, Auto Revert Mode normally puts point
  49 ;; at the same position that a regular manual revert would.  However,
  50 ;; there is one exception to this rule.  If point is at the end of the
  51 ;; buffer before reverting, it stays at the end.  Similarly if point
  52 ;; is displayed at the end of a file buffer in any window, it will stay
  53 ;; at the end of the buffer in that window, even if the window is not
  54 ;; selected.  This way, you can use Auto Revert Mode to `tail' a file.
  55 ;; Just put point at the end of the buffer and it will stay there.
  56 ;; These rules apply to file buffers. For non-file buffers, the
  57 ;; behavior may be mode dependent.
  58
  59 ;; Usage:
  60 ;;
  61 ;; Go to the appropriate buffer and press:
  62 ;;   M-x auto-revert-mode RET
  63 ;;
  64 ;; To activate Global Auto-Revert Mode, press:
  65 ;;   M-x global-auto-revert-mode RET
  66 ;;
  67 ;; To activate Global Auto-Revert Mode every time Emacs is started
  68 ;; customise the option `global-auto-revert-mode' or the following
  69 ;; line could be added to your ~/.emacs:
  70 ;;   (global-auto-revert-mode 1)
  71 ;;
  72 ;; The function `turn-on-auto-revert-mode' could be added to any major
  73 ;; mode hook to activate Auto-Revert Mode for all buffers in that
  74 ;; mode.  For example, the following line will activate Auto-Revert
  75 ;; Mode in all C mode buffers:
  76 ;;
  77 ;; (add-hook 'c-mode-hook 'turn-on-auto-revert-mode)
  78
  79 ;;; Code:
  80
  81 ;; Dependencies:
  82
  83 (require 'timer)
  84
  85 (eval-when-compile (require 'cl))
  86
  87
  88 ;; Custom Group:
  89 ;;
  90 ;; The two modes will be placed next to Auto Save Mode under the
  91 ;; Files group under Emacs.
  92
  93 (defgroup auto-revert nil
  94   "Revert individual buffers when files on disk change.
  95
  96 Auto-Revert Mode can be activated for individual buffer.
  97 Global Auto-Revert Mode applies to all buffers."
  98   :group 'files
  99   :group 'convenience)
 100
 101
 102 ;; Variables:
 103
 104 ;; Autoload for the benefit of `make-mode-line-mouse-sensitive'.
 105 ;;;###autoload
 106 (defvar auto-revert-mode nil
 107   "*Non-nil when Auto-Revert Mode is active.
 108 Never set this variable directly, use the command `auto-revert-mode' instead.")
 109 (put 'auto-revert-mode 'permanent-local t)
 110
 111 (defvar auto-revert-timer nil
 112   "Timer used by Auto-Revert Mode.")
 113
 114 (defcustom auto-revert-interval 5
 115   "Time, in seconds, between Auto-Revert Mode file checks.
 116 The value may be an integer or floating point number.
 117
 118 If a timer is already active, there are two ways to make sure
 119 that the new value will take effect immediately.  You can set
 120 this variable through Custom or you can call the command
 121 `auto-revert-set-timer' after setting the variable.  Otherwise,
 122 the new value will take effect the first time Auto Revert Mode
 123 calls `auto-revert-set-timer' for internal reasons or in your
 124 next editing session."
 125   :group 'auto-revert
 126   :type 'number
 127   :set (lambda (variable value)
 128          (set-default variable value)
 129          (and (boundp 'auto-revert-timer)
 130               auto-revert-timer
 131               (auto-revert-set-timer))))
 132
 133 (defcustom auto-revert-stop-on-user-input t
 134   "When non-nil Auto-Revert Mode stops checking files on user input."
 135   :group 'auto-revert
 136   :type 'boolean)
 137
 138 (defcustom auto-revert-verbose t
 139   "When nil, Auto-Revert Mode will not generate any messages.
 140 When non-nil, a message is generated whenever a file is reverted."
 141   :group 'auto-revert
 142   :type 'boolean)
 143
 144 (defcustom auto-revert-mode-text " ARev"
 145   "String to display in the mode line when Auto-Revert Mode is active.
 146
 147 \(When the string is not empty, make sure that it has a leading space.)"
 148   :tag "Auto Revert Mode Text"          ; To separate it from `global-...'
 149   :group 'auto-revert
 150   :type 'string)
 151
 152 (defcustom auto-revert-mode-hook nil
 153   "Functions to run when Auto-Revert Mode is activated."
 154   :tag "Auto Revert Mode Hook"          ; To separate it from `global-...'
 155   :group 'auto-revert
 156   :type 'hook)
 157
 158 (defcustom global-auto-revert-mode-text ""
 159   "String to display when Global Auto-Revert Mode is active.
 160
 161 The default is nothing since when this mode is active this text doesn't
 162 vary over time, or between buffers.  Hence mode line text
 163 would only waste precious space."
 164   :group 'auto-revert
 165   :type 'string)
 166
 167 (defcustom global-auto-revert-mode-hook nil
 168   "Hook called when Global Auto-Revert Mode is activated."
 169   :group 'auto-revert
 170   :type 'hook)
 171
 172 (defcustom global-auto-revert-non-file-buffers nil
 173   "When nil only file buffers are reverted by Global Auto-Revert Mode.
 174
 175 When non-nil, both file buffers and buffers with a custom
 176 `revert-buffer-function' and a `buffer-stale-function' are
 177 reverted by Global Auto-Revert Mode.
 178
 179 Use this option with care since it could lead to excessive reverts.
 180 Note also that for some non-file buffers the check whether the
 181 buffer needs updating may be imperfect, due to efficiency
 182 considerations, and may not take all information listed in the
 183 buffer into account.  Hence, a non-nil value for this option does
 184 not necessarily make manual updates useless for non-file buffers."
 185   :group 'auto-revert
 186   :type 'boolean)
 187
 188 (defcustom global-auto-revert-ignore-modes '()
 189   "List of major modes Global Auto-Revert Mode should not check."
 190   :group 'auto-revert
 191   :type '(repeat sexp))
 192
 193 (defcustom auto-revert-load-hook nil
 194   "Functions to run when Auto-Revert Mode is first loaded."
 195   :tag "Load Hook"
 196   :group 'auto-revert
 197   :type 'hook)
 198
 199 (defcustom auto-revert-check-vc-info nil
 200   "If non-nil Auto Revert Mode reliably updates version control info.
 201 Auto Revert Mode updates version control info whenever the buffer
 202 needs reverting, regardless of the value of this variable.
 203 However, the version control state can change without changes to
 204 the work file.  If the change is made from the current Emacs
 205 session, all info is updated.  But if, for instance, a new
 206 version is checked in from outside the current Emacs session, the
 207 version control number in the mode line, as well as other version
 208 control related information, may not be properly updated.  If you
 209 are worried about this, set this variable to a non-nil value.
 210
 211 This currently works by automatically updating the version
 212 control info every `auto-revert-interval' seconds.  Nevertheless,
 213 it should not cause excessive CPU usage on a reasonably fast
 214 machine, if it does not apply to too many version controlled
 215 buffers.  CPU usage depends on the version control system"
 216   :group 'auto-revert
 217   :type 'boolean
 218   :version "21.4")
 219
 220 (defvar global-auto-revert-ignore-buffer nil
 221   "*When non-nil, Global Auto-Revert Mode will not revert this buffer.
 222
 223 This variable becomes buffer local when set in any fashion.")
 224 (make-variable-buffer-local 'global-auto-revert-ignore-buffer)
 225
 226 ;; Internal variables:
 227
 228 (defvar auto-revert-buffer-list '()
 229   "List of buffers in Auto-Revert Mode.
 230
 231 Note that only Auto-Revert Mode, never Global Auto-Revert Mode, adds
 232 buffers to this list.
 233
 234 The timer function `auto-revert-buffers' is responsible for purging
 235 the list of old buffers.")
 236
 237 (defvar auto-revert-remaining-buffers '()
 238   "Buffers not checked when user input stopped execution.")
 239
 240
 241 ;; Functions:
 242
 243 ;;;###autoload
 244 (define-minor-mode auto-revert-mode
 245   "Toggle reverting buffer when file on disk changes.
 246
 247 With arg, turn Auto Revert mode on if and only if arg is positive.
 248 This is a minor mode that affects only the current buffer.
 249 Use `global-auto-revert-mode' to automatically revert all buffers."
 250   nil auto-revert-mode-text nil
 251   (if auto-revert-mode
 252       (if (not (memq (current-buffer) auto-revert-buffer-list))
 253           (push (current-buffer) auto-revert-buffer-list))
 254     (setq auto-revert-buffer-list
 255           (delq (current-buffer) auto-revert-buffer-list)))
 256   (auto-revert-set-timer)
 257   (when auto-revert-mode
 258     (auto-revert-buffers)))
 259
 260
 261 ;;;###autoload
 262 (defun turn-on-auto-revert-mode ()
 263   "Turn on Auto-Revert Mode.
 264
 265 This function is designed to be added to hooks, for example:
 266   (add-hook 'c-mode-hook 'turn-on-auto-revert-mode)"
 267   (auto-revert-mode 1))
 268
 269
 270 ;;;###autoload
 271 (define-minor-mode global-auto-revert-mode
 272   "Revert any buffer when file on disk changes.
 273
 274 With arg, turn Auto Revert mode on globally if and only if arg is positive.
 275 This is a minor mode that affects all buffers.
 276 Use `auto-revert-mode' to revert a particular buffer."
 277   :global t :group 'auto-revert :lighter global-auto-revert-mode-text
 278   (auto-revert-set-timer)
 279   (when global-auto-revert-mode
 280     (auto-revert-buffers)))
 281
 282
 283 (defun auto-revert-set-timer ()
 284   "Restart or cancel the timer used by Auto-Revert Mode.
 285 If such a timer is active, cancel it.  Start a new timer if
 286 Global Auto-Revert Mode is active or if Auto-Revert Mode is active
 287 in some buffer.  Restarting the timer ensures that Auto-Revert Mode
 288 will use an up-to-date value of `auto-revert-interval'"
 289   (interactive)
 290   (if (timerp auto-revert-timer)
 291       (cancel-timer auto-revert-timer))
 292   (setq auto-revert-timer
 293         (if (or global-auto-revert-mode auto-revert-buffer-list)
 294             (run-with-timer auto-revert-interval
 295                             auto-revert-interval
 296                             'auto-revert-buffers)
 297           nil)))
 298
 299 (defun auto-revert-active-p ()
 300   "Check if auto-revert is active (in current buffer or globally)."
 301   (or auto-revert-mode
 302       (and
 303        global-auto-revert-mode
 304        (not global-auto-revert-ignore-buffer)
 305        (not (memq major-mode
 306                   global-auto-revert-ignore-modes)))))
 307
 308 (defun auto-revert-handler ()
 309   "Revert current buffer, if appropriate.
 310 This is an internal function used by Auto-Revert Mode."
 311   (unless (buffer-modified-p)
 312     (let ((buffer (current-buffer)) revert eob eoblist)
 313       (or (and buffer-file-name
 314                (file-readable-p buffer-file-name)
 315                (not (verify-visited-file-modtime buffer))
 316                (setq revert t))
 317           (and (or auto-revert-mode global-auto-revert-non-file-buffers)
 318                revert-buffer-function
 319                (boundp 'buffer-stale-function)
 320                (functionp buffer-stale-function)
 321                (setq revert (funcall buffer-stale-function t))))
 322       (when revert
 323         (when (and auto-revert-verbose
 324                    (not (eq revert 'fast)))
 325           (message "Reverting buffer `%s'." (buffer-name)))
 326         ;; If point (or a window point) is at the end of the buffer,
 327         ;; we want to keep it at the end after reverting.  This allows
 328         ;; to tail a file.
 329         (when buffer-file-name
 330           (setq eob (eobp))
 331           (walk-windows
 332            #'(lambda (window)
 333                (and (eq (window-buffer window) buffer)
 334                     (= (window-point window) (point-max))
 335                     (push window eoblist)))
 336            'no-mini t))
 337         (revert-buffer 'ignore-auto 'dont-ask 'preserve-modes)
 338         (when buffer-file-name
 339           (when eob (goto-char (point-max)))
 340           (dolist (window eoblist)
 341             (set-window-point window (point-max)))))
 342       ;; `preserve-modes' avoids changing the (minor) modes.  But we
 343       ;; do want to reset the mode for VC, so we do it manually.
 344       (when (or revert auto-revert-check-vc-info)
 345         (vc-find-file-hook)))))
 346
 347 (defun auto-revert-buffers ()
 348   "Revert buffers as specified by Auto-Revert and Global Auto-Revert Mode.
 349
 350 Should `global-auto-revert-mode' be active all file buffers are checked.
 351
 352 Should `auto-revert-mode' be active in some buffers, those buffers
 353 are checked.
 354
 355 Non-file buffers that have a custom `revert-buffer-function' and
 356 a `buffer-stale-function' are reverted either when Auto-Revert
 357 Mode is active in that buffer, or when the variable
 358 `global-auto-revert-non-file-buffers' is non-nil and Global
 359 Auto-Revert Mode is active.
 360
 361 This function stops whenever there is user input.  The buffers not
 362 checked are stored in the variable `auto-revert-remaining-buffers'.
 363
 364 To avoid starvation, the buffers in `auto-revert-remaining-buffers'
 365 are checked first the next time this function is called.
 366
 367 This function is also responsible for removing buffers no longer in
 368 Auto-Revert mode from `auto-revert-buffer-list', and for canceling
 369 the timer when no buffers need to be checked."
 370   (let ((bufs (if global-auto-revert-mode
 371                   (buffer-list)
 372                 auto-revert-buffer-list))
 373         (remaining '())
 374         (new '()))
 375     ;; Partition `bufs' into two halves depending on whether or not
 376     ;; the buffers are in `auto-revert-remaining-buffers'.  The two
 377     ;; halves are then re-joined with the "remaining" buffers at the
 378     ;; head of the list.
 379     (dolist (buf auto-revert-remaining-buffers)
 380       (if (memq buf bufs)
 381           (push buf remaining)))
 382     (dolist (buf bufs)
 383       (if (not (memq buf remaining))
 384           (push buf new)))
 385     (setq bufs (nreverse (nconc new remaining)))
 386     (while (and bufs
 387                 (not (and auto-revert-stop-on-user-input
 388                           (input-pending-p))))
 389       (let ((buf (car bufs)))
 390         (if (buffer-name buf)           ; Buffer still alive?
 391             (with-current-buffer buf
 392               ;; Test if someone has turned off Auto-Revert Mode in a
 393               ;; non-standard way, for example by changing major mode.
 394               (if (and (not auto-revert-mode)
 395                        (memq buf auto-revert-buffer-list))
 396                   (setq auto-revert-buffer-list
 397                         (delq buf auto-revert-buffer-list)))
 398               (when (auto-revert-active-p) (auto-revert-handler)))
 399           ;; Remove dead buffer from `auto-revert-buffer-list'.
 400           (setq auto-revert-buffer-list
 401                 (delq buf auto-revert-buffer-list))))
 402       (setq bufs (cdr bufs)))
 403     (setq auto-revert-remaining-buffers bufs)
 404     ;; Check if we should cancel the timer.
 405     (when (and (not global-auto-revert-mode)
 406                (null auto-revert-buffer-list))
 407       (cancel-timer auto-revert-timer)
 408       (setq auto-revert-timer nil))))
 409
 410
 411 ;; The end:
 412 (provide 'autorevert)
 413
 414 (run-hooks 'auto-revert-load-hook)
 415
 416 ;;; arch-tag: f6bcb07b-4841-477e-9e44-b18678e58876
 417 ;;; autorevert.el ends here