lisp/autorevert.el

   1 ;;; autorevert.el --- revert buffers when files on disk change
   2
   3 ;; Copyright (C) 1997, 1998, 1999, 2001, 2004 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 and the
  38 ;; buffer contains no unsaved changes.
  39 ;;
  40 ;; Auto-Revert Mode can be activated for individual buffers.  Global
  41 ;; Auto-Revert Mode applies to all file buffers. (If the user option
  42 ;; `global-auto-revert-non-file-buffers' is non-nil, it also applies
  43 ;; to some non-file buffers.  This option is disabled by default.)
  44 ;; Since checking a remote file is too slow, these modes do not check
  45 ;; or revert remote files.
  46 ;;
  47 ;; Both modes operate by checking the time stamp of all files at
  48 ;; intervals of `auto-revert-interval'.  The default is every five
  49 ;; seconds.  The check is aborted whenever the user actually uses
  50 ;; Emacs.  You should never even notice that this package is active
  51 ;; (except that your buffers will be reverted, of course).
  52 ;;
  53 ;; After reverting a file buffer, Auto Revert Mode normally puts point
  54 ;; at the same position that a regular manual revert would.  However,
  55 ;; there is one exception to this rule.  If point is at the end of the
  56 ;; buffer before reverting, it stays at the end.  Similarly if point
  57 ;; is displayed at the end of a file buffer in any window, it will stay
  58 ;; at the end of the buffer in that window, even if the window is not
  59 ;; selected.  This way, you can use Auto Revert Mode to `tail' a file.
  60 ;; Just put point at the end of the buffer and it will stay there.
  61 ;; These rules apply to file buffers. For non-file buffers, the
  62 ;; behavior may be mode dependent.
  63 ;;
  64 ;; While you can use Auto Revert Mode to tail a file, this package
  65 ;; contains a third minor mode, Auto Revert Tail Mode, which does so
  66 ;; more efficiently, as long as you are sure that the file will only
  67 ;; change by growing at the end.  It only appends the new output,
  68 ;; instead of reverting the entire buffer.  It does so even if the
  69 ;; buffer contains unsaved changes.  (Because they will not be lost.)
  70
  71 ;; Usage:
  72 ;;
  73 ;; Go to the appropriate buffer and press either of:
  74 ;;   M-x auto-revert-mode RET
  75 ;;   M-x auto-revert-tail-mode RET
  76 ;;
  77 ;; To activate Global Auto-Revert Mode, press:
  78 ;;   M-x global-auto-revert-mode RET
  79 ;;
  80 ;; To activate Global Auto-Revert Mode every time Emacs is started
  81 ;; customise the option `global-auto-revert-mode' or the following
  82 ;; line could be added to your ~/.emacs:
  83 ;;   (global-auto-revert-mode 1)
  84 ;;
  85 ;; The function `turn-on-auto-revert-mode' could be added to any major
  86 ;; mode hook to activate Auto-Revert Mode for all buffers in that
  87 ;; mode.  For example, the following line will activate Auto-Revert
  88 ;; Mode in all C mode buffers:
  89 ;;
  90 ;; (add-hook 'c-mode-hook 'turn-on-auto-revert-mode)
  91
  92 ;;; Code:
  93
  94 ;; Dependencies:
  95
  96 (require 'timer)
  97
  98 (eval-when-compile (require 'cl))
  99
 100
 101 ;; Custom Group:
 102 ;;
 103 ;; The two modes will be placed next to Auto Save Mode under the
 104 ;; Files group under Emacs.
 105
 106 (defgroup auto-revert nil
 107   "Revert individual buffers when files on disk change.
 108
 109 Auto-Revert Mode can be activated for individual buffer.
 110 Global Auto-Revert Mode applies to all buffers."
 111   :group 'files
 112   :group 'convenience)
 113
 114
 115 ;; Variables:
 116
 117 ;;; What's this?: ;; Autoload for the benefit of `make-mode-line-mouse-sensitive'.
 118 ;;; What's this?: ;;;###autoload
 119 (defvar auto-revert-mode nil
 120   "*Non-nil when Auto-Revert Mode is active.
 121 Never set this variable directly, use the command `auto-revert-mode' instead.")
 122 (put 'auto-revert-mode 'permanent-local t)
 123
 124 (defvar auto-revert-tail-mode nil
 125   "*Non-nil when Auto-Revert Tail Mode is active.
 126 Never set this variable directly, use the command `auto-revert-mode' instead.")
 127 (put 'auto-revert-tail-mode 'permanent-local t)
 128
 129 (defvar auto-revert-timer nil
 130   "Timer used by Auto-Revert Mode.")
 131
 132 (defcustom auto-revert-interval 5
 133   "Time, in seconds, between Auto-Revert Mode file checks.
 134 The value may be an integer or floating point number.
 135
 136 If a timer is already active, there are two ways to make sure
 137 that the new value will take effect immediately.  You can set
 138 this variable through Custom or you can call the command
 139 `auto-revert-set-timer' after setting the variable.  Otherwise,
 140 the new value will take effect the first time Auto Revert Mode
 141 calls `auto-revert-set-timer' for internal reasons or in your
 142 next editing session."
 143   :group 'auto-revert
 144   :type 'number
 145   :set (lambda (variable value)
 146          (set-default variable value)
 147          (and (boundp 'auto-revert-timer)
 148               auto-revert-timer
 149               (auto-revert-set-timer))))
 150
 151 (defcustom auto-revert-stop-on-user-input t
 152   "When non-nil Auto-Revert Mode stops checking files on user input."
 153   :group 'auto-revert
 154   :type 'boolean)
 155
 156 (defcustom auto-revert-verbose t
 157   "When nil, Auto-Revert Mode will not generate any messages.
 158 When non-nil, a message is generated whenever a file is reverted."
 159   :group 'auto-revert
 160   :type 'boolean)
 161
 162 (defcustom auto-revert-mode-text " ARev"
 163   "String to display in the mode line when Auto-Revert Mode is active.
 164
 165 \(When the string is not empty, make sure that it has a leading space.)"
 166   :tag "Auto Revert Mode Text"          ; To separate it from `global-...'
 167   :group 'auto-revert
 168   :type 'string)
 169
 170 (defcustom auto-revert-tail-mode-text " Tail"
 171   "String to display in the mode line when Auto-Revert Tail Mode is active.
 172
 173 \(When the string is not empty, make sure that it has a leading space.)"
 174   :group 'auto-revert
 175   :type 'string
 176   :version "21.4")
 177
 178 (defcustom auto-revert-mode-hook nil
 179   "Functions to run when Auto-Revert Mode is activated."
 180   :tag "Auto Revert Mode Hook"          ; To separate it from `global-...'
 181   :group 'auto-revert
 182   :type 'hook)
 183
 184 (defcustom global-auto-revert-mode-text ""
 185   "String to display when Global Auto-Revert Mode is active.
 186
 187 The default is nothing since when this mode is active this text doesn't
 188 vary over time, or between buffers.  Hence mode line text
 189 would only waste precious space."
 190   :group 'auto-revert
 191   :type 'string)
 192
 193 (defcustom global-auto-revert-mode-hook nil
 194   "Hook called when Global Auto-Revert Mode is activated."
 195   :group 'auto-revert
 196   :type 'hook)
 197
 198 (defcustom global-auto-revert-non-file-buffers nil
 199   "When nil, Global Auto-Revert mode operates only on file-visiting buffers.
 200
 201 When non-nil, both file buffers and buffers with a custom
 202 `revert-buffer-function' and a `buffer-stale-function' are
 203 reverted by Global Auto-Revert mode.  These include the Buffer
 204 List buffer, and Dired buffers showing complete local
 205 directories.  Dired buffers do not auto-revert as a result of
 206 changes in subdirectories or in the contents, size, modes, etc.,
 207 of files.  You may still sometimes want to revert them manually.
 208
 209 Use this option with care since it could lead to excessive auto-reverts.
 210 For more information, see Info node `(emacs-xtra)Autorevert'."
 211   :group 'auto-revert
 212   :type 'boolean
 213   :link '(info-link "(emacs-xtra)Autorevert"))
 214
 215 (defcustom global-auto-revert-ignore-modes ()
 216   "List of major modes Global Auto-Revert Mode should not check."
 217   :group 'auto-revert
 218   :type '(repeat sexp))
 219
 220 (defcustom auto-revert-load-hook nil
 221   "Functions to run when Auto-Revert Mode is first loaded."
 222   :tag "Load Hook"
 223   :group 'auto-revert
 224   :type 'hook)
 225
 226 (defcustom auto-revert-check-vc-info nil
 227   "If non-nil Auto Revert Mode reliably updates version control info.
 228 Auto Revert Mode updates version control info whenever the buffer
 229 needs reverting, regardless of the value of this variable.
 230 However, the version control state can change without changes to
 231 the work file.  If the change is made from the current Emacs
 232 session, all info is updated.  But if, for instance, a new
 233 version is checked in from outside the current Emacs session, the
 234 version control number in the mode line, as well as other version
 235 control related information, may not be properly updated.  If you
 236 are worried about this, set this variable to a non-nil value.
 237
 238 This currently works by automatically updating the version
 239 control info every `auto-revert-interval' seconds.  Nevertheless,
 240 it should not cause excessive CPU usage on a reasonably fast
 241 machine, if it does not apply to too many version controlled
 242 buffers.  CPU usage depends on the version control system"
 243   :group 'auto-revert
 244   :type 'boolean
 245   :version "21.4")
 246
 247 (defvar global-auto-revert-ignore-buffer nil
 248   "*When non-nil, Global Auto-Revert Mode will not revert this buffer.
 249
 250 This variable becomes buffer local when set in any fashion.")
 251 (make-variable-buffer-local 'global-auto-revert-ignore-buffer)
 252
 253 ;; Internal variables:
 254
 255 (defvar auto-revert-buffer-list ()
 256   "List of buffers in Auto-Revert Mode.
 257
 258 Note that only Auto-Revert Mode, never Global Auto-Revert Mode, adds
 259 buffers to this list.
 260
 261 The timer function `auto-revert-buffers' is responsible for purging
 262 the list of old buffers.")
 263
 264 (defvar auto-revert-remaining-buffers ()
 265   "Buffers not checked when user input stopped execution.")
 266
 267 (defvar auto-revert-tail-pos 0
 268   "Position of last known end of file.")
 269
 270 (add-hook 'find-file-hook
 271           (lambda ()
 272             (set (make-local-variable 'auto-revert-tail-pos)
 273                  (save-restriction (widen) (1- (point-max))))))
 274
 275 ;; Functions:
 276
 277 ;;;###autoload
 278 (define-minor-mode auto-revert-mode
 279   "Toggle reverting buffer when file on disk changes.
 280
 281 With arg, turn Auto Revert mode on if and only if arg is positive.
 282 This is a minor mode that affects only the current buffer.
 283 Use `global-auto-revert-mode' to automatically revert all buffers.
 284 Use `auto-revert-tail-mode' if you know that the file will only grow
 285 without being changed in the part that is already in the buffer."
 286   nil auto-revert-mode-text nil
 287   (if auto-revert-mode
 288       (if (not (memq (current-buffer) auto-revert-buffer-list))
 289           (push (current-buffer) auto-revert-buffer-list))
 290     (setq auto-revert-buffer-list
 291           (delq (current-buffer) auto-revert-buffer-list)))
 292   (auto-revert-set-timer)
 293   (when auto-revert-mode
 294     (auto-revert-buffers)
 295     (setq auto-revert-tail-mode nil)))
 296
 297
 298 ;;;###autoload
 299 (defun turn-on-auto-revert-mode ()
 300   "Turn on Auto-Revert Mode.
 301
 302 This function is designed to be added to hooks, for example:
 303   (add-hook 'c-mode-hook 'turn-on-auto-revert-mode)"
 304   (auto-revert-mode 1))
 305
 306
 307 ;;;###autoload
 308 (define-minor-mode auto-revert-tail-mode
 309   "Toggle reverting tail of buffer when file on disk grows.
 310 With arg, turn Tail mode on iff arg is positive.
 311
 312 When Tail mode is enabled, the tail of the file is constantly
 313 followed, as with the shell command `tail -f'.  This means that
 314 whenever the file grows on disk (presumably because some
 315 background process is appending to it from time to time), this is
 316 reflected in the current buffer.
 317
 318 You can edit the buffer and turn this mode off and on again as
 319 you please.  But make sure the background process has stopped
 320 writing before you save the file!
 321
 322 Use `auto-revert-mode' for changes other than appends!"
 323   :group 'find-file :lighter auto-revert-tail-mode-text
 324   (when auto-revert-tail-mode
 325     (unless buffer-file-name
 326       (auto-revert-tail-mode 0)
 327       (error "This buffer is not visiting a file"))
 328     (if (and (buffer-modified-p)
 329              (not auto-revert-tail-pos) ; library was loaded only after finding file
 330              (not (y-or-n-p "Buffer is modified, so tail offset may be wrong.  Proceed? ")))
 331         (auto-revert-tail-mode 0)
 332       ;; else we might reappend our own end when we save
 333       (add-hook 'before-save-hook (lambda () (auto-revert-tail-mode 0)) nil t)
 334       (or (local-variable-p 'auto-revert-tail-pos) ; don't lose prior position
 335           (set (make-variable-buffer-local 'auto-revert-tail-pos)
 336                (save-restriction (widen) (1- (point-max)))))
 337       ;; let auto-revert-mode set up the mechanism for us if it isn't already
 338       (or auto-revert-mode
 339           (let ((auto-revert-tail-mode t))
 340             (auto-revert-mode 1)))
 341       (setq auto-revert-mode nil))))
 342
 343
 344 ;;;###autoload
 345 (defun turn-on-auto-revert-tail-mode ()
 346   "Turn on Auto-Revert Tail Mode.
 347
 348 This function is designed to be added to hooks, for example:
 349   (add-hook 'my-logfile-mode-hook 'turn-on-auto-revert-tail-mode)"
 350   (auto-revert-tail-mode 1))
 351
 352
 353 ;;;###autoload
 354 (define-minor-mode global-auto-revert-mode
 355   "Revert any buffer when file on disk changes.
 356
 357 With arg, turn Auto Revert mode on globally if and only if arg is positive.
 358 This is a minor mode that affects all buffers.
 359 Use `auto-revert-mode' to revert a particular buffer."
 360   :global t :group 'auto-revert :lighter global-auto-revert-mode-text
 361   (auto-revert-set-timer)
 362   (when global-auto-revert-mode
 363     (auto-revert-buffers)))
 364
 365
 366 (defun auto-revert-set-timer ()
 367   "Restart or cancel the timer used by Auto-Revert Mode.
 368 If such a timer is active, cancel it.  Start a new timer if
 369 Global Auto-Revert Mode is active or if Auto-Revert Mode is active
 370 in some buffer.  Restarting the timer ensures that Auto-Revert Mode
 371 will use an up-to-date value of `auto-revert-interval'"
 372   (interactive)
 373   (if (timerp auto-revert-timer)
 374       (cancel-timer auto-revert-timer))
 375   (setq auto-revert-timer
 376         (if (or global-auto-revert-mode auto-revert-buffer-list)
 377             (run-with-timer auto-revert-interval
 378                             auto-revert-interval
 379                             'auto-revert-buffers))))
 380
 381 (defun auto-revert-active-p ()
 382   "Check if auto-revert is active (in current buffer or globally)."
 383   (or auto-revert-mode
 384       auto-revert-tail-mode
 385       (and
 386        global-auto-revert-mode
 387        (not global-auto-revert-ignore-buffer)
 388        (not (memq major-mode
 389                   global-auto-revert-ignore-modes)))))
 390
 391 (defun auto-revert-handler ()
 392   "Revert current buffer, if appropriate.
 393 This is an internal function used by Auto-Revert Mode."
 394   (when (or auto-revert-tail-mode (not (buffer-modified-p)))
 395     (let* ((buffer (current-buffer))
 396            (revert
 397             (or (and buffer-file-name
 398                      (not (file-remote-p buffer-file-name))
 399                      (file-readable-p buffer-file-name)
 400                      (not (verify-visited-file-modtime buffer)))
 401                 (and (or auto-revert-mode
 402                          global-auto-revert-non-file-buffers)
 403                      revert-buffer-function
 404                      (boundp 'buffer-stale-function)
 405                      (functionp buffer-stale-function)
 406                      (funcall buffer-stale-function t))))
 407            eob eoblist)
 408       (when revert
 409         (when (and auto-revert-verbose
 410                    (not (eq revert 'fast)))
 411           (message "Reverting buffer `%s'." (buffer-name)))
 412         ;; If point (or a window point) is at the end of the buffer,
 413         ;; we want to keep it at the end after reverting.  This allows
 414         ;; to tail a file.
 415         (when buffer-file-name
 416           (setq eob (eobp))
 417           (walk-windows
 418            #'(lambda (window)
 419                (and (eq (window-buffer window) buffer)
 420                     (= (window-point window) (point-max))
 421                     (push window eoblist)))
 422            'no-mini t))
 423         (if auto-revert-tail-mode
 424             (auto-revert-tail-handler)
 425           ;; Bind buffer-read-only in case user has done C-x C-q,
 426           ;; so as not to forget that.  This gives undesirable results
 427           ;; when the file's mode changes, but that is less common.
 428           (let ((buffer-read-only buffer-read-only))
 429             (revert-buffer 'ignore-auto 'dont-ask 'preserve-modes)))
 430         (when buffer-file-name
 431           (when eob (goto-char (point-max)))
 432           (dolist (window eoblist)
 433             (set-window-point window (point-max)))))
 434       ;; `preserve-modes' avoids changing the (minor) modes.  But we
 435       ;; do want to reset the mode for VC, so we do it manually.
 436       (when (or revert auto-revert-check-vc-info)
 437         (vc-find-file-hook)))))
 438
 439 (defun auto-revert-tail-handler ()
 440   (let ((size (nth 7 (file-attributes buffer-file-name)))
 441         (modified (buffer-modified-p))
 442         buffer-read-only                ; ignore
 443         (file buffer-file-name)
 444         buffer-file-name)               ; ignore that file has changed
 445     (when (> size auto-revert-tail-pos)
 446       (save-restriction
 447         (widen)
 448         (save-excursion
 449           (goto-char (point-max))
 450           (insert-file-contents file nil auto-revert-tail-pos size)))
 451       (setq auto-revert-tail-pos size)
 452       (set-buffer-modified-p modified)))
 453   (set-visited-file-modtime))
 454
 455 (defun auto-revert-buffers ()
 456   "Revert buffers as specified by Auto-Revert and Global Auto-Revert Mode.
 457
 458 Should `global-auto-revert-mode' be active all file buffers are checked.
 459
 460 Should `auto-revert-mode' be active in some buffers, those buffers
 461 are checked.
 462
 463 Non-file buffers that have a custom `revert-buffer-function' and
 464 a `buffer-stale-function' are reverted either when Auto-Revert
 465 Mode is active in that buffer, or when the variable
 466 `global-auto-revert-non-file-buffers' is non-nil and Global
 467 Auto-Revert Mode is active.
 468
 469 This function stops whenever there is user input.  The buffers not
 470 checked are stored in the variable `auto-revert-remaining-buffers'.
 471
 472 To avoid starvation, the buffers in `auto-revert-remaining-buffers'
 473 are checked first the next time this function is called.
 474
 475 This function is also responsible for removing buffers no longer in
 476 Auto-Revert mode from `auto-revert-buffer-list', and for canceling
 477 the timer when no buffers need to be checked."
 478   (let ((bufs (if global-auto-revert-mode
 479                   (buffer-list)
 480                 auto-revert-buffer-list))
 481         (remaining ())
 482         (new ()))
 483     ;; Partition `bufs' into two halves depending on whether or not
 484     ;; the buffers are in `auto-revert-remaining-buffers'.  The two
 485     ;; halves are then re-joined with the "remaining" buffers at the
 486     ;; head of the list.
 487     (dolist (buf auto-revert-remaining-buffers)
 488       (if (memq buf bufs)
 489           (push buf remaining)))
 490     (dolist (buf bufs)
 491       (if (not (memq buf remaining))
 492           (push buf new)))
 493     (setq bufs (nreverse (nconc new remaining)))
 494     (while (and bufs
 495                 (not (and auto-revert-stop-on-user-input
 496                           (input-pending-p))))
 497       (let ((buf (car bufs)))
 498         (if (buffer-name buf)           ; Buffer still alive?
 499             (with-current-buffer buf
 500               ;; Test if someone has turned off Auto-Revert Mode in a
 501               ;; non-standard way, for example by changing major mode.
 502               (if (and (not auto-revert-mode)
 503                        (not auto-revert-tail-mode)
 504                        (memq buf auto-revert-buffer-list))
 505                   (setq auto-revert-buffer-list
 506                         (delq buf auto-revert-buffer-list)))
 507               (when (auto-revert-active-p) (auto-revert-handler)))
 508           ;; Remove dead buffer from `auto-revert-buffer-list'.
 509           (setq auto-revert-buffer-list
 510                 (delq buf auto-revert-buffer-list))))
 511       (setq bufs (cdr bufs)))
 512     (setq auto-revert-remaining-buffers bufs)
 513     ;; Check if we should cancel the timer.
 514     (when (and (not global-auto-revert-mode)
 515                (null auto-revert-buffer-list))
 516       (cancel-timer auto-revert-timer)
 517       (setq auto-revert-timer nil))))
 518
 519
 520 ;; The end:
 521 (provide 'autorevert)
 522
 523 (run-hooks 'auto-revert-load-hook)
 524
 525 ;;; arch-tag: f6bcb07b-4841-477e-9e44-b18678e58876
 526 ;;; autorevert.el ends here