@c This is part of the Emacs manual.@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.@c See file emacs.texi for copying conditions.@c@c This file is included either in emacs-xtra.texi (when producing the@c printed version) or in the main Emacs manual (for the on-line version).@node Autorevert@section Auto Reverting non-file BuffersNormally Global Auto Revert Mode only reverts file buffers. There aretwo ways to auto-revert certain non-file buffers: enabling Auto RevertMode in those buffers (using @kbd{M-x auto-revert-mode}) and setting@code{global-auto-revert-non-file-buffers} to @code{t}. The latterenables Auto Reverting for all types of buffers for which it isimplemented, that is, for the types of buffers listed in the menubelow.Like file buffers, non-file buffers should normally not revert whileyou are working on them, or while they contain information that mightget lost after reverting. Therefore, they do not revert if they are``modified''. This can get tricky, because deciding when a non-filebuffer should be marked modified is usually more difficult than forfile buffers.Another tricky detail is that, for efficiency reasons, Auto Revertoften does not try to detect all possible changes in the buffer, onlychanges that are ``major'' or easy to detect. Hence, enablingauto-reverting for a non-file buffer does not always guarantee thatall information in the buffer is up to date and does not necessarilymake manual reverts useless.At the other extreme, certain buffers automatically auto-revert every@code{auto-revert-interval} seconds. (This currently only applies tothe Buffer Menu.) In this case, Auto Revert does not print anymessages while reverting, even when @code{auto-revert-verbose} isnon-@code{nil}.The details depend on the particular types of buffers and areexplained in the corresponding sections.@menu* Auto Reverting the Buffer Menu::* Auto Reverting Dired::* Supporting additional buffers::@end menu@node Auto Reverting the Buffer Menu@subsection Auto Reverting the Buffer MenuIf auto-reverting of non-file buffers is enabled, the Buffer Menuautomatically reverts every @code{auto-revert-interval} seconds,whether there is a need for it or not. (It would probably take longerto check whether there is a need than to actually revert.)If the Buffer Menu inappropriately gets marked modified, just revertit manually using @kbd{g} and auto-reverting will resume. However, ifyou marked certain buffers to get deleted or to be displayed, you haveto be careful, because reverting erases all marks. The fact thatadding marks sets the buffer's modified flag prevents Auto Revert fromautomatically erasing the marks.@node Auto Reverting Dired@subsection Auto Reverting Dired buffersAuto-reverting Dired buffers currently works on GNU or Unix styleoperating systems. It may not work satisfactorily on some othersystems.Dired buffers only auto-revert when the file list of the buffer's maindirectory changes. They do not auto-revert when information about aparticular file changes or when inserted subdirectories change. To besure that @emph{all} listed information is up to date, you have tomanually revert using @kbd{g}, @emph{even} if auto-reverting isenabled in the Dired buffer. Sometimes, you might get the impressionthat modifying or saving files listed in the main directory actuallydoes cause auto-reverting. This is because making changes to a file,or saving it, very often causes changes in the directory itself, forinstance, through backup files or auto-save files. However, this isnot guaranteed.If the Dired buffer is marked modified and there are no changes youwant to protect, then most of the time you can make auto-revertingresume by manually reverting the buffer using @kbd{g}. There is oneexception. If you flag or mark files, you can safely revert thebuffer. This will not erase the flags or marks (unless the markedfile has been deleted, of course). However, the buffer will staymodified, even after reverting, and auto-reverting will not resume.This is because, if you flag or mark files, you may be working on thebuffer and you might not want the buffer to change without warning.If you want auto-reverting to resume in the presence of marks andflags, mark the buffer non-modified using @kbd{M-~}. However, adding,deleting or changing marks or flags will mark it modified again.Remote Dired buffers are not auto-reverted. Neither are Dired buffersfor which you used shell wildcards or file arguments to list only someof the files. @samp{*Find*} and @samp{*Locate*} buffers do notauto-revert either.@node Supporting additional buffers@subsection Adding Support for Auto-Reverting additional Buffers.This section is intended for Elisp programmers who would like to addsupport for auto-reverting new types of buffers.To support auto-reverting the buffer must first of all have a@code{revert-buffer-function}. @xref{Definition ofrevert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}.In addition, it @emph{must} have a @code{buffer-stale-function}.@defvar buffer-stale-functionThe value of this variable is a function to check whether a non-filebuffer needs reverting. This should be a function with one optionalargument @var{noconfirm}. The function should return non-@code{nil}if the buffer should be reverted. The buffer is current when thisfunction is called.While this function is mainly intended for use in auto-reverting, itcould be used for other purposes as well. For instance, ifauto-reverting is not enabled, it could be used to warn the user thatthe buffer needs reverting. The idea behind the @var{noconfirm}argument is that it should be @code{t} if the buffer is going to bereverted without asking the user and @code{nil} if the function isjust going to be used to warn the user that the buffer is out of date.In particular, for use in auto-reverting, @var{noconfirm} is @code{t}.If the function is only going to be used for auto-reverting, you canignore the @var{noconfirm} argument.If you just want to automatically auto-revert every@code{auto-revert-interval} seconds, use:@example(set (make-local-variable 'buffer-stale-function) #'(lambda (&optional noconfirm) 'fast))@end example@noindentin the buffer's mode function.The special return value @samp{fast} tells the caller that the needfor reverting was not checked, but that reverting the buffer is fast.It also tells Auto Revert not to print any revert messages, even if@code{auto-revert-verbose} is non-@code{nil}. This is important, asgetting revert messages every @code{auto-revert-interval} seconds canbe very annoying. The information provided by this return value couldalso be useful if the function is consulted for purposes other thanauto-reverting.@end defvarOnce the buffer has a @code{revert-buffer-function} and a@code{buffer-stale-function}, several problems usually remain.The buffer will only auto-revert if it is marked unmodified. Hence,you will have to make sure that various functions mark the buffermodified if and only if either the buffer contains information thatmight be lost by reverting or there is reason to believe that the usermight be inconvenienced by auto-reverting, because he is activelyworking on the buffer. The user can always override this by manuallyadjusting the modified status of the buffer. To support this, callingthe @code{revert-buffer-function} on a buffer that is markedunmodified should always keep the buffer marked unmodified.It is important to assure that point does not continuously jump aroundas a consequence of auto-reverting. Of course, moving point might beinevitable if the buffer radically changes.You should make sure that the @code{revert-buffer-function} does notprint messages that unnecessarily duplicate Auto Revert's own messagesif @code{auto-revert-verbose} is @code{t} and effectively override a@code{nil} value for @code{auto-revert-verbose}. Hence, adapting amode for auto-reverting often involves getting rid of such messages.This is especially important for buffers that automaticallyauto-revert every @code{auto-revert-interval} seconds.Also, you may want to update the documentation string of@code{global-auto-revert-non-file-buffers}.@ifinfoFinally, you should add a node to this chapter's menu. This node@end ifinfo@ifnotinfoFinally, you should add a section to this chapter. This section@end ifnotinfoshould at the very least make clear whether enabling auto-revertingfor the buffer reliably assures that all information in the buffer iscompletely up to date (or will be after @code{auto-revert-interval}seconds).@ignore arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e@end ignore