*** empty log message ***
[emacs.git] / lispref / backups.texi
blob893f6df42050e0ec118d53e4a1b92b633ed03c62
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2001, 2002, 2003,
4 @c   2004, 2005, 2006, 2007  Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/backups
7 @node Backups and Auto-Saving, Buffers, Files, Top
8 @chapter Backups and Auto-Saving
10   Backup files and auto-save files are two methods by which Emacs tries
11 to protect the user from the consequences of crashes or of the user's
12 own errors.  Auto-saving preserves the text from earlier in the current
13 editing session; backup files preserve file contents prior to the
14 current session.
16 @menu
17 * Backup Files::   How backup files are made; how their names are chosen.
18 * Auto-Saving::    How auto-save files are made; how their names are chosen.
19 * Reverting::      @code{revert-buffer}, and how to customize what it does.
20 @end menu
22 @node Backup Files
23 @section Backup Files
24 @cindex backup file
26   A @dfn{backup file} is a copy of the old contents of a file you are
27 editing.  Emacs makes a backup file the first time you save a buffer
28 into its visited file.  Normally, this means that the backup file
29 contains the contents of the file as it was before the current editing
30 session.  The contents of the backup file normally remain unchanged once
31 it exists.
33   Backups are usually made by renaming the visited file to a new name.
34 Optionally, you can specify that backup files should be made by copying
35 the visited file.  This choice makes a difference for files with
36 multiple names; it also can affect whether the edited file remains owned
37 by the original owner or becomes owned by the user editing it.
39   By default, Emacs makes a single backup file for each file edited.
40 You can alternatively request numbered backups; then each new backup
41 file gets a new name.  You can delete old numbered backups when you
42 don't want them any more, or Emacs can delete them automatically.
44 @menu
45 * Making Backups::     How Emacs makes backup files, and when.
46 * Rename or Copy::     Two alternatives: renaming the old file or copying it.
47 * Numbered Backups::   Keeping multiple backups for each source file.
48 * Backup Names::       How backup file names are computed; customization.
49 @end menu
51 @node Making Backups
52 @subsection Making Backup Files
54 @defun backup-buffer
55   This function makes a backup of the file visited by the current
56 buffer, if appropriate.  It is called by @code{save-buffer} before
57 saving the buffer the first time.
59 If a backup was made by renaming, the return value is a cons cell of
60 the form (@var{modes} . @var{backupname}), where @var{modes} are the
61 mode bits of the original file, as returned by @code{file-modes}
62 (@pxref{File Attributes,, Other Information about Files}), and
63 @var{backupname} is the name of the backup.  In all other cases, that
64 is, if a backup was made by copying or if no backup was made, this
65 function returns @code{nil}.
66 @end defun
68 @defvar buffer-backed-up
69   This buffer-local variable indicates whether this buffer's file has
70 been backed up on account of this buffer.  If it is non-@code{nil}, then
71 the backup file has been written.  Otherwise, the file should be backed
72 up when it is next saved (if backups are enabled).  This is a
73 permanent local; @code{kill-all-local-variables} does not alter it.
74 @end defvar
76 @defopt make-backup-files
77 This variable determines whether or not to make backup files.  If it
78 is non-@code{nil}, then Emacs creates a backup of each file when it is
79 saved for the first time---provided that @code{backup-inhibited}
80 is @code{nil} (see below).
82 The following example shows how to change the @code{make-backup-files}
83 variable only in the Rmail buffers and not elsewhere.  Setting it
84 @code{nil} stops Emacs from making backups of these files, which may
85 save disk space.  (You would put this code in your init file.)
87 @smallexample
88 @group
89 (add-hook 'rmail-mode-hook
90           (function (lambda ()
91                       (make-local-variable
92                        'make-backup-files)
93                       (setq make-backup-files nil))))
94 @end group
95 @end smallexample
96 @end defopt
98 @defvar backup-enable-predicate
99 This variable's value is a function to be called on certain occasions to
100 decide whether a file should have backup files.  The function receives
101 one argument, an absolute file name to consider.  If the function returns
102 @code{nil}, backups are disabled for that file.  Otherwise, the other
103 variables in this section say whether and how to make backups.
105 @findex normal-backup-enable-predicate
106 The default value is @code{normal-backup-enable-predicate}, which checks
107 for files in @code{temporary-file-directory} and
108 @code{small-temporary-file-directory}.
109 @end defvar
111 @defvar backup-inhibited
112 If this variable is non-@code{nil}, backups are inhibited.  It records
113 the result of testing @code{backup-enable-predicate} on the visited file
114 name.  It can also coherently be used by other mechanisms that inhibit
115 backups based on which file is visited.  For example, VC sets this
116 variable non-@code{nil} to prevent making backups for files managed
117 with a version control system.
119 This is a permanent local, so that changing the major mode does not lose
120 its value.  Major modes should not set this variable---they should set
121 @code{make-backup-files} instead.
122 @end defvar
124 @defvar backup-directory-alist
125 This variable's value is an alist of filename patterns and backup
126 directory names.  Each element looks like
127 @smallexample
128 (@var{regexp} . @var{directory})
129 @end smallexample
131 @noindent
132 Backups of files with names matching @var{regexp} will be made in
133 @var{directory}.  @var{directory} may be relative or absolute.  If it is
134 absolute, so that all matching files are backed up into the same
135 directory, the file names in this directory will be the full name of the
136 file backed up with all directory separators changed to @samp{!} to
137 prevent clashes.  This will not work correctly if your filesystem
138 truncates the resulting name.
140 For the common case of all backups going into one directory, the alist
141 should contain a single element pairing @samp{"."} with the appropriate
142 directory name.
144 If this variable is @code{nil}, or it fails to match a filename, the
145 backup is made in the original file's directory.
147 On MS-DOS filesystems without long names this variable is always
148 ignored.
149 @end defvar
151 @defvar make-backup-file-name-function
152 This variable's value is a function to use for making backups instead
153 of the default @code{make-backup-file-name}.  A value of @code{nil}
154 gives the default @code{make-backup-file-name} behavior.
155 @xref{Backup Names,, Naming Backup Files}.
157 This could be buffer-local to do something special for specific
158 files.  If you define it, you may need to change
159 @code{backup-file-name-p} and @code{file-name-sans-versions} too.
160 @end defvar
163 @node Rename or Copy
164 @subsection Backup by Renaming or by Copying?
165 @cindex backup files, how to make them
167   There are two ways that Emacs can make a backup file:
169 @itemize @bullet
170 @item
171 Emacs can rename the original file so that it becomes a backup file, and
172 then write the buffer being saved into a new file.  After this
173 procedure, any other names (i.e., hard links) of the original file now
174 refer to the backup file.  The new file is owned by the user doing the
175 editing, and its group is the default for new files written by the user
176 in that directory.
178 @item
179 Emacs can copy the original file into a backup file, and then overwrite
180 the original file with new contents.  After this procedure, any other
181 names (i.e., hard links) of the original file continue to refer to the
182 current (updated) version of the file.  The file's owner and group will
183 be unchanged.
184 @end itemize
186   The first method, renaming, is the default.
188   The variable @code{backup-by-copying}, if non-@code{nil}, says to use
189 the second method, which is to copy the original file and overwrite it
190 with the new buffer contents.  The variable @code{file-precious-flag},
191 if non-@code{nil}, also has this effect (as a sideline of its main
192 significance).  @xref{Saving Buffers}.
194 @defopt backup-by-copying
195 If this variable is non-@code{nil}, Emacs always makes backup files by
196 copying.
197 @end defopt
199   The following three variables, when non-@code{nil}, cause the second
200 method to be used in certain special cases.  They have no effect on the
201 treatment of files that don't fall into the special cases.
203 @defopt backup-by-copying-when-linked
204 If this variable is non-@code{nil}, Emacs makes backups by copying for
205 files with multiple names (hard links).
207 This variable is significant only if @code{backup-by-copying} is
208 @code{nil}, since copying is always used when that variable is
209 non-@code{nil}.
210 @end defopt
212 @defopt backup-by-copying-when-mismatch
213 If this variable is non-@code{nil}, Emacs makes backups by copying in cases
214 where renaming would change either the owner or the group of the file.
216 The value has no effect when renaming would not alter the owner or
217 group of the file; that is, for files which are owned by the user and
218 whose group matches the default for a new file created there by the
219 user.
221 This variable is significant only if @code{backup-by-copying} is
222 @code{nil}, since copying is always used when that variable is
223 non-@code{nil}.
224 @end defopt
226 @defopt backup-by-copying-when-privileged-mismatch
227 This variable, if non-@code{nil}, specifies the same behavior as
228 @code{backup-by-copying-when-mismatch}, but only for certain user-id
229 values: namely, those less than or equal to a certain number.  You set
230 this variable to that number.
232 Thus, if you set @code{backup-by-copying-when-privileged-mismatch}
233 to 0, backup by copying is done for the superuser only,
234 when necessary to prevent a change in the owner of the file.
236 The default is 200.
237 @end defopt
239 @node Numbered Backups
240 @subsection Making and Deleting Numbered Backup Files
242   If a file's name is @file{foo}, the names of its numbered backup
243 versions are @file{foo.~@var{v}~}, for various integers @var{v}, like
244 this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{},
245 @file{foo.~259~}, and so on.
247 @defopt version-control
248 This variable controls whether to make a single non-numbered backup
249 file or multiple numbered backups.
251 @table @asis
252 @item @code{nil}
253 Make numbered backups if the visited file already has numbered backups;
254 otherwise, do not.  This is the default.
256 @item @code{never}
257 Do not make numbered backups.
259 @item @var{anything else}
260 Make numbered backups.
261 @end table
262 @end defopt
264   The use of numbered backups ultimately leads to a large number of
265 backup versions, which must then be deleted.  Emacs can do this
266 automatically or it can ask the user whether to delete them.
268 @defopt kept-new-versions
269 The value of this variable is the number of newest versions to keep
270 when a new numbered backup is made.  The newly made backup is included
271 in the count.  The default value is 2.
272 @end defopt
274 @defopt kept-old-versions
275 The value of this variable is the number of oldest versions to keep
276 when a new numbered backup is made.  The default value is 2.
277 @end defopt
279   If there are backups numbered 1, 2, 3, 5, and 7, and both of these
280 variables have the value 2, then the backups numbered 1 and 2 are kept
281 as old versions and those numbered 5 and 7 are kept as new versions;
282 backup version 3 is excess.  The function @code{find-backup-file-name}
283 (@pxref{Backup Names}) is responsible for determining which backup
284 versions to delete, but does not delete them itself.
286 @defopt delete-old-versions
287 If this variable is @code{t}, then saving a file deletes excess
288 backup versions silently.  If it is @code{nil}, that means
289 to ask for confirmation before deleting excess backups.
290 Otherwise, they are not deleted at all.
291 @end defopt
293 @defopt dired-kept-versions
294 This variable specifies how many of the newest backup versions to keep
295 in the Dired command @kbd{.} (@code{dired-clean-directory}).  That's the
296 same thing @code{kept-new-versions} specifies when you make a new backup
297 file.  The default value is 2.
298 @end defopt
300 @node Backup Names
301 @subsection Naming Backup Files
303   The functions in this section are documented mainly because you can
304 customize the naming conventions for backup files by redefining them.
305 If you change one, you probably need to change the rest.
307 @defun backup-file-name-p filename
308 This function returns a non-@code{nil} value if @var{filename} is a
309 possible name for a backup file.  A file with the name @var{filename}
310 need not exist; the function just checks the name.
312 @smallexample
313 @group
314 (backup-file-name-p "foo")
315      @result{} nil
316 @end group
317 @group
318 (backup-file-name-p "foo~")
319      @result{} 3
320 @end group
321 @end smallexample
323 The standard definition of this function is as follows:
325 @smallexample
326 @group
327 (defun backup-file-name-p (file)
328   "Return non-nil if FILE is a backup file \
329 name (numeric or not)..."
330   (string-match "~\\'" file))
331 @end group
332 @end smallexample
334 @noindent
335 Thus, the function returns a non-@code{nil} value if the file name ends
336 with a @samp{~}.  (We use a backslash to split the documentation
337 string's first line into two lines in the text, but produce just one
338 line in the string itself.)
340 This simple expression is placed in a separate function to make it easy
341 to redefine for customization.
342 @end defun
344 @defun make-backup-file-name filename
345 This function returns a string that is the name to use for a
346 non-numbered backup file for file @var{filename}.  On Unix, this is just
347 @var{filename} with a tilde appended.
349 The standard definition of this function, on most operating systems, is
350 as follows:
352 @smallexample
353 @group
354 (defun make-backup-file-name (file)
355   "Create the non-numeric backup file name for FILE..."
356   (concat file "~"))
357 @end group
358 @end smallexample
360 You can change the backup-file naming convention by redefining this
361 function.  The following example redefines @code{make-backup-file-name}
362 to prepend a @samp{.} in addition to appending a tilde:
364 @smallexample
365 @group
366 (defun make-backup-file-name (filename)
367   (expand-file-name
368     (concat "." (file-name-nondirectory filename) "~")
369     (file-name-directory filename)))
370 @end group
372 @group
373 (make-backup-file-name "backups.texi")
374      @result{} ".backups.texi~"
375 @end group
376 @end smallexample
378 Some parts of Emacs, including some Dired commands, assume that backup
379 file names end with @samp{~}.  If you do not follow that convention, it
380 will not cause serious problems, but these commands may give
381 less-than-desirable results.
382 @end defun
384 @defun find-backup-file-name filename
385 This function computes the file name for a new backup file for
386 @var{filename}.  It may also propose certain existing backup files for
387 deletion.  @code{find-backup-file-name} returns a list whose @sc{car} is
388 the name for the new backup file and whose @sc{cdr} is a list of backup
389 files whose deletion is proposed.  The value can also be @code{nil},
390 which means not to make a backup.
392 Two variables, @code{kept-old-versions} and @code{kept-new-versions},
393 determine which backup versions should be kept.  This function keeps
394 those versions by excluding them from the @sc{cdr} of the value.
395 @xref{Numbered Backups}.
397 In this example, the value says that @file{~rms/foo.~5~} is the name
398 to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess''
399 version that the caller should consider deleting now.
401 @smallexample
402 @group
403 (find-backup-file-name "~rms/foo")
404      @result{} ("~rms/foo.~5~" "~rms/foo.~3~")
405 @end group
406 @end smallexample
407 @end defun
409 @c Emacs 19 feature
410 @defun file-newest-backup filename
411 This function returns the name of the most recent backup file for
412 @var{filename}, or @code{nil} if that file has no backup files.
414 Some file comparison commands use this function so that they can
415 automatically compare a file with its most recent backup.
416 @end defun
418 @node Auto-Saving
419 @section Auto-Saving
420 @cindex auto-saving
422   Emacs periodically saves all files that you are visiting; this is
423 called @dfn{auto-saving}.  Auto-saving prevents you from losing more
424 than a limited amount of work if the system crashes.  By default,
425 auto-saves happen every 300 keystrokes, or after around 30 seconds of
426 idle time.  @xref{Auto Save, Auto Save, Auto-Saving: Protection Against
427 Disasters, emacs, The GNU Emacs Manual}, for information on auto-save
428 for users.  Here we describe the functions used to implement auto-saving
429 and the variables that control them.
431 @defvar buffer-auto-save-file-name
432 This buffer-local variable is the name of the file used for
433 auto-saving the current buffer.  It is @code{nil} if the buffer
434 should not be auto-saved.
436 @example
437 @group
438 buffer-auto-save-file-name
439      @result{} "/xcssun/users/rms/lewis/#backups.texi#"
440 @end group
441 @end example
442 @end defvar
444 @deffn Command auto-save-mode arg
445 When used interactively without an argument, this command is a toggle
446 switch: it turns on auto-saving of the current buffer if it is off, and
447 vice versa.  With an argument @var{arg}, the command turns auto-saving
448 on if the value of @var{arg} is @code{t}, a nonempty list, or a positive
449 integer.  Otherwise, it turns auto-saving off.
450 @end deffn
452 @defun auto-save-file-name-p filename
453 This function returns a non-@code{nil} value if @var{filename} is a
454 string that could be the name of an auto-save file.  It assumes
455 the usual naming convention for auto-save files: a name that
456 begins and ends with hash marks (@samp{#}) is a possible auto-save file
457 name.  The argument @var{filename} should not contain a directory part.
459 @example
460 @group
461 (make-auto-save-file-name)
462      @result{} "/xcssun/users/rms/lewis/#backups.texi#"
463 @end group
464 @group
465 (auto-save-file-name-p "#backups.texi#")
466      @result{} 0
467 @end group
468 @group
469 (auto-save-file-name-p "backups.texi")
470      @result{} nil
471 @end group
472 @end example
474 The standard definition of this function is as follows:
476 @example
477 @group
478 (defun auto-save-file-name-p (filename)
479   "Return non-nil if FILENAME can be yielded by..."
480   (string-match "^#.*#$" filename))
481 @end group
482 @end example
484 This function exists so that you can customize it if you wish to
485 change the naming convention for auto-save files.  If you redefine it,
486 be sure to redefine the function @code{make-auto-save-file-name}
487 correspondingly.
488 @end defun
490 @defun make-auto-save-file-name
491 This function returns the file name to use for auto-saving the current
492 buffer.  This is just the file name with hash marks (@samp{#}) prepended
493 and appended to it.  This function does not look at the variable
494 @code{auto-save-visited-file-name} (described below); callers of this
495 function should check that variable first.
497 @example
498 @group
499 (make-auto-save-file-name)
500      @result{} "/xcssun/users/rms/lewis/#backups.texi#"
501 @end group
502 @end example
504 Here is a simplified version of the standard definition of this
505 function:
507 @example
508 @group
509 (defun make-auto-save-file-name ()
510   "Return file name to use for auto-saves \
511 of current buffer.."
512   (if buffer-file-name
513 @end group
514 @group
515       (concat
516        (file-name-directory buffer-file-name)
517        "#"
518        (file-name-nondirectory buffer-file-name)
519        "#")
520     (expand-file-name
521      (concat "#%" (buffer-name) "#"))))
522 @end group
523 @end example
525 This exists as a separate function so that you can redefine it to
526 customize the naming convention for auto-save files.  Be sure to
527 change @code{auto-save-file-name-p} in a corresponding way.
528 @end defun
530 @defopt auto-save-visited-file-name
531 If this variable is non-@code{nil}, Emacs auto-saves buffers in
532 the files they are visiting.  That is, the auto-save is done in the same
533 file that you are editing.  Normally, this variable is @code{nil}, so
534 auto-save files have distinct names that are created by
535 @code{make-auto-save-file-name}.
537 When you change the value of this variable, the new value does not take
538 effect in an existing buffer until the next time auto-save mode is
539 reenabled in it.  If auto-save mode is already enabled, auto-saves
540 continue to go in the same file name until @code{auto-save-mode} is
541 called again.
542 @end defopt
544 @defun recent-auto-save-p
545 This function returns @code{t} if the current buffer has been
546 auto-saved since the last time it was read in or saved.
547 @end defun
549 @defun set-buffer-auto-saved
550 This function marks the current buffer as auto-saved.  The buffer will
551 not be auto-saved again until the buffer text is changed again.  The
552 function returns @code{nil}.
553 @end defun
555 @defopt auto-save-interval
556 The value of this variable specifies how often to do auto-saving, in
557 terms of number of input events.  Each time this many additional input
558 events are read, Emacs does auto-saving for all buffers in which that is
559 enabled.  Setting this to zero disables autosaving based on the
560 number of characters typed.
561 @end defopt
563 @defopt auto-save-timeout
564 The value of this variable is the number of seconds of idle time that
565 should cause auto-saving.  Each time the user pauses for this long,
566 Emacs does auto-saving for all buffers in which that is enabled.  (If
567 the current buffer is large, the specified timeout is multiplied by a
568 factor that increases as the size increases; for a million-byte
569 buffer, the factor is almost 4.)
571 If the value is zero or @code{nil}, then auto-saving is not done as a
572 result of idleness, only after a certain number of input events as
573 specified by @code{auto-save-interval}.
574 @end defopt
576 @defvar auto-save-hook
577 This normal hook is run whenever an auto-save is about to happen.
578 @end defvar
580 @defopt auto-save-default
581 If this variable is non-@code{nil}, buffers that are visiting files
582 have auto-saving enabled by default.  Otherwise, they do not.
583 @end defopt
585 @deffn Command do-auto-save &optional no-message current-only
586 This function auto-saves all buffers that need to be auto-saved.  It
587 saves all buffers for which auto-saving is enabled and that have been
588 changed since the previous auto-save.
590 If any buffers are auto-saved, @code{do-auto-save} normally displays a
591 message saying @samp{Auto-saving...} in the echo area while
592 auto-saving is going on.  However, if @var{no-message} is
593 non-@code{nil}, the message is inhibited.
595 If @var{current-only} is non-@code{nil}, only the current buffer
596 is auto-saved.
597 @end deffn
599 @defun delete-auto-save-file-if-necessary &optional force
600 This function deletes the current buffer's auto-save file if
601 @code{delete-auto-save-files} is non-@code{nil}.  It is called every
602 time a buffer is saved.
604 Unless @var{force} is non-@code{nil}, this function only deletes the
605 file if it was written by the current Emacs session since the last
606 true save.
607 @end defun
609 @defopt delete-auto-save-files
610 This variable is used by the function
611 @code{delete-auto-save-file-if-necessary}.  If it is non-@code{nil},
612 Emacs deletes auto-save files when a true save is done (in the visited
613 file).  This saves disk space and unclutters your directory.
614 @end defopt
616 @defun rename-auto-save-file
617 This function adjusts the current buffer's auto-save file name if the
618 visited file name has changed.  It also renames an existing auto-save
619 file, if it was made in the current Emacs session.  If the visited
620 file name has not changed, this function does nothing.
621 @end defun
623 @defvar buffer-saved-size
624 The value of this buffer-local variable is the length of the current
625 buffer, when it was last read in, saved, or auto-saved.  This is
626 used to detect a substantial decrease in size, and turn off auto-saving
627 in response.
629 If it is @minus{}1, that means auto-saving is temporarily shut off in
630 this buffer due to a substantial decrease in size.  Explicitly saving
631 the buffer stores a positive value in this variable, thus reenabling
632 auto-saving.  Turning auto-save mode off or on also updates this
633 variable, so that the substantial decrease in size is forgotten.
634 @end defvar
636 @defvar auto-save-list-file-name
637 This variable (if non-@code{nil}) specifies a file for recording the
638 names of all the auto-save files.  Each time Emacs does auto-saving, it
639 writes two lines into this file for each buffer that has auto-saving
640 enabled.  The first line gives the name of the visited file (it's empty
641 if the buffer has none), and the second gives the name of the auto-save
642 file.
644 When Emacs exits normally, it deletes this file; if Emacs crashes, you
645 can look in the file to find all the auto-save files that might contain
646 work that was otherwise lost.  The @code{recover-session} command uses
647 this file to find them.
649 The default name for this file specifies your home directory and starts
650 with @samp{.saves-}.  It also contains the Emacs process @acronym{ID} and the
651 host name.
652 @end defvar
654 @defvar auto-save-list-file-prefix
655 After Emacs reads your init file, it initializes
656 @code{auto-save-list-file-name} (if you have not already set it
657 non-@code{nil}) based on this prefix, adding the host name and process
658 ID.  If you set this to @code{nil} in your init file, then Emacs does
659 not initialize @code{auto-save-list-file-name}.
660 @end defvar
662 @node Reverting
663 @section Reverting
665   If you have made extensive changes to a file and then change your mind
666 about them, you can get rid of them by reading in the previous version
667 of the file with the @code{revert-buffer} command.  @xref{Reverting, ,
668 Reverting a Buffer, emacs, The GNU Emacs Manual}.
670 @deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes
671 This command replaces the buffer text with the text of the visited
672 file on disk.  This action undoes all changes since the file was visited
673 or saved.
675 By default, if the latest auto-save file is more recent than the visited
676 file, and the argument @var{ignore-auto} is @code{nil},
677 @code{revert-buffer} asks the user whether to use that auto-save
678 instead.  When you invoke this command interactively, @var{ignore-auto}
679 is @code{t} if there is no numeric prefix argument; thus, the
680 interactive default is not to check the auto-save file.
682 Normally, @code{revert-buffer} asks for confirmation before it changes
683 the buffer; but if the argument @var{noconfirm} is non-@code{nil},
684 @code{revert-buffer} does not ask for confirmation.
686 Normally, this command reinitializes the buffer's major and minor modes
687 using @code{normal-mode}.  But if @var{preserve-modes} is
688 non-@code{nil}, the modes remain unchanged.
690 Reverting tries to preserve marker positions in the buffer by using the
691 replacement feature of @code{insert-file-contents}.  If the buffer
692 contents and the file contents are identical before the revert
693 operation, reverting preserves all the markers.  If they are not
694 identical, reverting does change the buffer; in that case, it preserves
695 the markers in the unchanged text (if any) at the beginning and end of
696 the buffer.  Preserving any additional markers would be problematical.
697 @end deffn
699 You can customize how @code{revert-buffer} does its work by setting
700 the variables described in the rest of this section.
702 @defopt revert-without-query
703 This variable holds a list of files that should be reverted without
704 query.  The value is a list of regular expressions.  If the visited file
705 name matches one of these regular expressions, and the file has changed
706 on disk but the buffer is not modified, then @code{revert-buffer}
707 reverts the file without asking the user for confirmation.
708 @end defopt
710   Some major modes customize @code{revert-buffer} by making
711 buffer-local bindings for these variables:
713 @defvar revert-buffer-function
714 @anchor{Definition of revert-buffer-function}
715 The value of this variable is the function to use to revert this
716 buffer.  If non-@code{nil}, it should be a function with two optional
717 arguments to do the work of reverting.  The two optional arguments,
718 @var{ignore-auto} and @var{noconfirm}, are the arguments that
719 @code{revert-buffer} received.  If the value is @code{nil}, reverting
720 works the usual way.
722 Modes such as Dired mode, in which the text being edited does not
723 consist of a file's contents but can be regenerated in some other
724 fashion, can give this variable a buffer-local value that is a function to
725 regenerate the contents.
726 @end defvar
728 @defvar revert-buffer-insert-file-contents-function
729 The value of this variable, if non-@code{nil}, specifies the function to use to
730 insert the updated contents when reverting this buffer.  The function
731 receives two arguments: first the file name to use; second, @code{t} if
732 the user has asked to read the auto-save file.
734 The reason for a mode to set this variable instead of
735 @code{revert-buffer-function} is to avoid duplicating or replacing the
736 rest of what @code{revert-buffer} does: asking for confirmation,
737 clearing the undo list, deciding the proper major mode, and running the
738 hooks listed below.
739 @end defvar
741 @defvar before-revert-hook
742 This normal hook is run by @code{revert-buffer} before
743 inserting the modified contents---but only if
744 @code{revert-buffer-function} is @code{nil}.
745 @end defvar
747 @defvar after-revert-hook
748 This normal hook is run by @code{revert-buffer} after inserting
749 the modified contents---but only if @code{revert-buffer-function} is
750 @code{nil}.
751 @end defvar
753 @ignore
754    arch-tag: 295a6321-e5ab-46d5-aef5-0bb4f447a67f
755 @end ignore