Commit | Line | Data |
---|---|---|
6f585e44 | 1 | @c This is part of the Emacs manual. |
ab422c4d | 2 | @c Copyright (C) 2004-2013 Free Software Foundation, Inc. |
6f585e44 EZ |
3 | @c See file emacs.texi for copying conditions. |
4 | @c | |
c5184807 EZ |
5 | @c This file is included either in emacs-xtra.texi (when producing the |
6 | @c printed version) or in the main Emacs manual (for the on-line version). | |
7 | @node Autorevert | |
75962ab7 | 8 | @section Auto Reverting Non-File Buffers |
c5184807 | 9 | |
82ec412e | 10 | Global Auto Revert Mode normally only reverts file buffers. There are |
bfd779dd CY |
11 | two ways to auto-revert certain non-file buffers: by enabling Auto |
12 | Revert Mode in those buffers (using @kbd{M-x auto-revert-mode}); and | |
13 | by setting @code{global-auto-revert-non-file-buffers} to a | |
14 | non-@code{nil} value. The latter enables Auto Reverting for all types | |
15 | of buffers for which it is implemented (listed in the menu below). | |
c5184807 EZ |
16 | |
17 | Like file buffers, non-file buffers should normally not revert while | |
18 | you are working on them, or while they contain information that might | |
19 | get lost after reverting. Therefore, they do not revert if they are | |
20 | ``modified''. This can get tricky, because deciding when a non-file | |
21 | buffer should be marked modified is usually more difficult than for | |
22 | file buffers. | |
23 | ||
24 | Another tricky detail is that, for efficiency reasons, Auto Revert | |
25 | often does not try to detect all possible changes in the buffer, only | |
26 | changes that are ``major'' or easy to detect. Hence, enabling | |
27 | auto-reverting for a non-file buffer does not always guarantee that | |
82ec412e | 28 | all information in the buffer is up-to-date, and does not necessarily |
c5184807 EZ |
29 | make manual reverts useless. |
30 | ||
82ec412e | 31 | At the other extreme, certain buffers automatically revert every |
c5184807 EZ |
32 | @code{auto-revert-interval} seconds. (This currently only applies to |
33 | the Buffer Menu.) In this case, Auto Revert does not print any | |
34 | messages while reverting, even when @code{auto-revert-verbose} is | |
35 | non-@code{nil}. | |
36 | ||
37 | The details depend on the particular types of buffers and are | |
38 | explained in the corresponding sections. | |
39 | ||
40 | @menu | |
75962ab7 GM |
41 | * Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. |
42 | * Auto Reverting Dired:: Auto Revert of Dired buffers. | |
1df7defd | 43 | * Supporting additional buffers:: How to add more Auto Revert support. |
c5184807 EZ |
44 | @end menu |
45 | ||
46 | @node Auto Reverting the Buffer Menu | |
47 | @subsection Auto Reverting the Buffer Menu | |
48 | ||
49 | If auto-reverting of non-file buffers is enabled, the Buffer Menu | |
50 | automatically reverts every @code{auto-revert-interval} seconds, | |
51 | whether there is a need for it or not. (It would probably take longer | |
52 | to check whether there is a need than to actually revert.) | |
53 | ||
54 | If the Buffer Menu inappropriately gets marked modified, just revert | |
55 | it manually using @kbd{g} and auto-reverting will resume. However, if | |
56 | you marked certain buffers to get deleted or to be displayed, you have | |
57 | to be careful, because reverting erases all marks. The fact that | |
58 | adding marks sets the buffer's modified flag prevents Auto Revert from | |
59 | automatically erasing the marks. | |
60 | ||
61 | @node Auto Reverting Dired | |
62 | @subsection Auto Reverting Dired buffers | |
63 | ||
64 | Auto-reverting Dired buffers currently works on GNU or Unix style | |
65 | operating systems. It may not work satisfactorily on some other | |
66 | systems. | |
67 | ||
68 | Dired buffers only auto-revert when the file list of the buffer's main | |
1df7defd | 69 | directory changes (e.g., when a new file is added). They do not |
82ec412e | 70 | auto-revert when information about a particular file changes |
1df7defd | 71 | (e.g., when the size changes) or when inserted subdirectories change. |
82ec412e GM |
72 | To be sure that @emph{all} listed information is up to date, you have |
73 | to manually revert using @kbd{g}, @emph{even} if auto-reverting is | |
c5184807 EZ |
74 | enabled in the Dired buffer. Sometimes, you might get the impression |
75 | that modifying or saving files listed in the main directory actually | |
76 | does cause auto-reverting. This is because making changes to a file, | |
82ec412e | 77 | or saving it, very often causes changes in the directory itself; for |
c5184807 EZ |
78 | instance, through backup files or auto-save files. However, this is |
79 | not guaranteed. | |
80 | ||
81 | If the Dired buffer is marked modified and there are no changes you | |
82 | want to protect, then most of the time you can make auto-reverting | |
83 | resume by manually reverting the buffer using @kbd{g}. There is one | |
84 | exception. If you flag or mark files, you can safely revert the | |
85 | buffer. This will not erase the flags or marks (unless the marked | |
86 | file has been deleted, of course). However, the buffer will stay | |
87 | modified, even after reverting, and auto-reverting will not resume. | |
88 | This is because, if you flag or mark files, you may be working on the | |
89 | buffer and you might not want the buffer to change without warning. | |
90 | If you want auto-reverting to resume in the presence of marks and | |
91 | flags, mark the buffer non-modified using @kbd{M-~}. However, adding, | |
92 | deleting or changing marks or flags will mark it modified again. | |
93 | ||
82ec412e GM |
94 | Remote Dired buffers are not auto-reverted (because it may be slow). |
95 | Neither are Dired buffers for which you used shell wildcards or file | |
1c64e6ed GM |
96 | arguments to list only some of the files. @file{*Find*} and |
97 | @file{*Locate*} buffers do not auto-revert either. | |
c5184807 | 98 | |
6945faa6 | 99 | @c FIXME? This should be in the elisp manual? |
c5184807 EZ |
100 | @node Supporting additional buffers |
101 | @subsection Adding Support for Auto-Reverting additional Buffers. | |
102 | ||
103 | This section is intended for Elisp programmers who would like to add | |
104 | support for auto-reverting new types of buffers. | |
105 | ||
106 | To support auto-reverting the buffer must first of all have a | |
107 | @code{revert-buffer-function}. @xref{Definition of | |
108 | revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. | |
109 | ||
110 | In addition, it @emph{must} have a @code{buffer-stale-function}. | |
111 | ||
eceeb5fc | 112 | @c FIXME only defvar in all of doc/emacs! |
c5184807 EZ |
113 | @defvar buffer-stale-function |
114 | The value of this variable is a function to check whether a non-file | |
115 | buffer needs reverting. This should be a function with one optional | |
116 | argument @var{noconfirm}. The function should return non-@code{nil} | |
117 | if the buffer should be reverted. The buffer is current when this | |
118 | function is called. | |
119 | ||
120 | While this function is mainly intended for use in auto-reverting, it | |
121 | could be used for other purposes as well. For instance, if | |
122 | auto-reverting is not enabled, it could be used to warn the user that | |
123 | the buffer needs reverting. The idea behind the @var{noconfirm} | |
124 | argument is that it should be @code{t} if the buffer is going to be | |
125 | reverted without asking the user and @code{nil} if the function is | |
126 | just going to be used to warn the user that the buffer is out of date. | |
127 | In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. | |
128 | If the function is only going to be used for auto-reverting, you can | |
129 | ignore the @var{noconfirm} argument. | |
130 | ||
131 | If you just want to automatically auto-revert every | |
82ec412e | 132 | @code{auto-revert-interval} seconds (like the Buffer Menu), use: |
c5184807 EZ |
133 | |
134 | @example | |
135 | (set (make-local-variable 'buffer-stale-function) | |
136 | #'(lambda (&optional noconfirm) 'fast)) | |
137 | @end example | |
138 | ||
139 | @noindent | |
140 | in the buffer's mode function. | |
141 | ||
142 | The special return value @samp{fast} tells the caller that the need | |
143 | for reverting was not checked, but that reverting the buffer is fast. | |
144 | It also tells Auto Revert not to print any revert messages, even if | |
145 | @code{auto-revert-verbose} is non-@code{nil}. This is important, as | |
146 | getting revert messages every @code{auto-revert-interval} seconds can | |
147 | be very annoying. The information provided by this return value could | |
148 | also be useful if the function is consulted for purposes other than | |
149 | auto-reverting. | |
150 | @end defvar | |
151 | ||
152 | Once the buffer has a @code{revert-buffer-function} and a | |
153 | @code{buffer-stale-function}, several problems usually remain. | |
154 | ||
155 | The buffer will only auto-revert if it is marked unmodified. Hence, | |
156 | you will have to make sure that various functions mark the buffer | |
157 | modified if and only if either the buffer contains information that | |
82ec412e | 158 | might be lost by reverting, or there is reason to believe that the user |
c5184807 EZ |
159 | might be inconvenienced by auto-reverting, because he is actively |
160 | working on the buffer. The user can always override this by manually | |
161 | adjusting the modified status of the buffer. To support this, calling | |
162 | the @code{revert-buffer-function} on a buffer that is marked | |
163 | unmodified should always keep the buffer marked unmodified. | |
164 | ||
165 | It is important to assure that point does not continuously jump around | |
166 | as a consequence of auto-reverting. Of course, moving point might be | |
167 | inevitable if the buffer radically changes. | |
168 | ||
169 | You should make sure that the @code{revert-buffer-function} does not | |
82ec412e GM |
170 | print messages that unnecessarily duplicate Auto Revert's own messages, |
171 | displayed if @code{auto-revert-verbose} is @code{t}, and effectively | |
172 | override a @code{nil} value for @code{auto-revert-verbose}. Hence, | |
173 | adapting a mode for auto-reverting often involves getting rid of such | |
174 | messages. This is especially important for buffers that automatically | |
175 | revert every @code{auto-revert-interval} seconds. | |
c5184807 | 176 | |
82ec412e GM |
177 | If the new auto-reverting is part of Emacs, you should mention it |
178 | in the documentation string of @code{global-auto-revert-non-file-buffers}. | |
c5184807 EZ |
179 | |
180 | @ifinfo | |
82ec412e | 181 | Similarly, you should add a node to this chapter's menu. This node |
c5184807 EZ |
182 | @end ifinfo |
183 | @ifnotinfo | |
82ec412e | 184 | Similarly, you should add a section to this chapter. This section |
c5184807 EZ |
185 | @end ifnotinfo |
186 | should at the very least make clear whether enabling auto-reverting | |
187 | for the buffer reliably assures that all information in the buffer is | |
188 | completely up to date (or will be after @code{auto-revert-interval} | |
189 | seconds). |